server: export a finished stage's real session as session.md and session.html

Every OpenCode-harness model stage now writes its real session into its own
step artifacts directory as session.md and session.html, so the existing
bounded artifact listing, the /artifacts/<run>/<step>/<name> serving path and
the artifact scan find and serve them with no special casing, while the stage
keeps its bounded preview in the run record unchanged.

- internal/opencode/export.go adds the one shared native export invocation and
  the exact session-ID/messages validation used by both Connection.Messages and
  the new ExportSession, so the readback path does not diverge. The backend's
  published subcommand is used (v1 `export <id>`, v2 `session export <id>`),
  the source read is capped at 8 MiB, and a larger session is read as a prefix
  and reported truncated instead of failing. boundedOutput.ReadFrom keeps the
  cap effective so overflow and the truncation path are real.
- internal/stage/session_export.go renders markdown and html with a metadata
  header, every role and every part (unknown part types as raw JSON, every
  session text escaped in html), atomic temp+rename writes that never overwrite
  an existing file, a visible truncation banner at both ends when the source or
  the 2 MiB rendered cap cuts it, and an honest 0-message header for an empty
  session rather than fabricated text.
- protocol.SessionExport and RunStep.SessionExport are stored in a new
  step_session_exports table (CREATE TABLE IF NOT EXISTS, so an old database
  gains an empty table with no migration) loaded through the existing main
  SELECT alongside the other per-step evidence and deleted by run retention.
- internal/server/runner.go exports after the post-stage filediff capture and
  before scanArtifacts, with context.WithTimeout(context.WithoutCancel(ctx),
  10s); it never waits for session idleness and a failure or a Pi stage (no
  native export path) records a sanitized diagnostic and continues, never
  changing the stage status, outcome, target, timing or result validation.

Reflected where it belongs: the packaged skill references
(internal/author/skill/references/operations.md and delivery.md) carry the new
Session export rules and the run-artifacts bullet, and docs/stage-artifacts.md
documents the names, the <run>/<step> paths, the served URL, the caps, the
truncation labels, failure isolation and the Pi limitation. The packaged
templates (examples/*.md) only tell a stage to save its own artifacts and say
nothing about the server-written session export, so none needed updating; no
new reference file was added, so install.go's managed inventory is unchanged.

Shared documentation: README.md's per-step artifacts sentence is now stale - it
should name the exported session alongside images, screenshots, reports and
logs. It is deliberately not committed here; the shared documents are folded by
the single documentation writer.

Checks: gofmt -l on the touched packages produced no output; go vet ./...
passed; go test -race -count=1 ./... passed.
This commit is contained in:
2026-10-17 19:40:43 +01:00
parent b568c86d13
commit 58c6b9b7c6
16 changed files with 1710 additions and 24 deletions
+19 -1
View File
@@ -515,7 +515,10 @@ type nativeChatModel struct {
ID string `json:"id"`
}
// nativeChatPart is one content element shared by both message envelopes.
// nativeChatPart is one content element shared by both message envelopes. Raw
// keeps the element's original JSON so the session exporter can render an
// unrecognised part type (file, patch, step, ...) instead of dropping it; it is
// ignored when a part is re-encoded.
type nativeChatPart struct {
Type string `json:"type"`
ID string `json:"id"`
@@ -524,6 +527,21 @@ type nativeChatPart struct {
Executed bool `json:"executed"`
State *protocol.ChatToolState `json:"state"`
Time *protocol.ChatTime `json:"time"`
Raw json.RawMessage `json:"-"`
}
// UnmarshalJSON decodes one content part and retains its raw JSON alongside the
// decoded fields, so a part type the decoder does not model is still available
// verbatim to the session exporter.
func (p *nativeChatPart) UnmarshalJSON(data []byte) error {
type part nativeChatPart
var decoded part
if err := json.Unmarshal(data, &decoded); err != nil {
return err
}
*p = nativeChatPart(decoded)
p.Raw = append(p.Raw[:0], data...)
return nil
}
// role, parts and the accessor methods below read the V2 top-level fields first
+236
View File
@@ -0,0 +1,236 @@
package opencode
import (
"bytes"
"context"
"encoding/json"
"fmt"
"git.a-wan.net/alan/pipelines/internal/protocol"
)
// MaxSessionExport bounds the native session readback used for the stage session
// export. A larger session is read as a bounded prefix and reported truncated,
// never presented as the whole session.
const MaxSessionExport = 8 << 20
// nativeExportResult is one bounded `opencode export` readback. envelope is the
// stdout prefix the CLI wrote, capped at the caller's limit; truncated is true
// when the CLI wrote more than the cap, so the prefix is not valid whole JSON.
type nativeExportResult struct {
envelope []byte
truncated bool
}
// exportNative runs the read-only session export CLI once with stdout capped at
// limit bytes. It is the single export invocation shared by Connection.Messages
// and ExportSession; the returned envelope is validated by the one
// validNativeExport check both call. The subcommand follows the backend's
// published interface: the native v1 CLI exposes top-level `export <id>`, while
// the installed v2 CLI exposes it as `session export <id>`. It never writes to,
// resumes or mutates the session, and it does not wait for session idleness.
func exportNative(ctx context.Context, executable, directory, backend, id string, limit int) (nativeExportResult, error) {
if !sessionID.MatchString(id) {
return nativeExportResult{}, fmt.Errorf("invalid session ID")
}
args := []string{"export", id}
if backend == "v2" {
args = []string{"session", "export", id}
}
cmd := CommandContext(ctx, executable, args...)
cmd.Dir = directory
stdout := &boundedOutput{limit: limit}
stderr := &boundedOutput{limit: 8 << 10}
cmd.Stdout = stdout
cmd.Stderr = stderr
if err := cmd.Run(); err != nil {
return nativeExportResult{envelope: stdout.Bytes(), truncated: stdout.overflow}, err
}
return nativeExportResult{envelope: stdout.Bytes(), truncated: stdout.overflow}, nil
}
// validNativeExport is the exact-ID and messages-array validation
// Connection.Messages and ExportSession share: the envelope must parse, carry an
// info.id equal to wantID and a non-empty JSON messages array.
func validNativeExport(data []byte, wantID string) (json.RawMessage, bool) {
var envelope struct {
Info struct {
ID string `json:"id"`
} `json:"info"`
Messages json.RawMessage `json:"messages"`
}
if json.Unmarshal(data, &envelope) != nil || envelope.Info.ID != wantID || len(envelope.Messages) == 0 || envelope.Messages[0] != '[' {
return nil, false
}
return envelope.Messages, true
}
// ExportedPart is one decoded content element of an exported session. Raw keeps
// the part's original JSON so an unrecognised type is rendered rather than
// silently dropped; State carries a tool call's status, input, result and error.
type ExportedPart struct {
Type string
ID string
Text string
Name string
State *protocol.ChatToolState
Time *protocol.ChatTime
Raw json.RawMessage
}
// ExportedMessage is one decoded turn. Every role is kept, not only
// user/assistant, so the export is the session the harness stored.
type ExportedMessage struct {
ID string
Role string
Model string
Agent string
CreatedAt int64
Parts []ExportedPart
}
// ExportedSession is one bounded native session readback for the stage session
// export. Truncated is true when the source exceeded MaxSessionExport; Messages
// then covers the complete turns decoded before the cut.
type ExportedSession struct {
ID string
Backend string
Messages []ExportedMessage
Truncated bool
}
// ExportSession reads the session's native export read-only and decodes it into
// ExportedSession. It reuses the shared export invocation and exact-ID check,
// decodes the v1/v2 message and part shapes through chatMessageRecords and, when
// the source exceeded MaxSessionExport, streams the complete turns decoded from
// the bounded prefix and reports Truncated instead of failing. It performs no
// writes, no resumption, no idleness wait and no retries.
func ExportSession(ctx context.Context, executable, directory, backend, id string) (ExportedSession, error) {
if !sessionID.MatchString(id) {
return ExportedSession{}, fmt.Errorf("invalid session ID")
}
exported, err := exportNative(ctx, executable, directory, backend, id, MaxSessionExport)
if err != nil {
if ctx.Err() != nil {
return ExportedSession{}, ctx.Err()
}
return ExportedSession{}, fmt.Errorf("native session export failed: %w", err)
}
session := ExportedSession{ID: id, Backend: backend}
if !exported.truncated {
messages, ok := validNativeExport(exported.envelope, id)
if !ok {
return ExportedSession{}, fmt.Errorf("native export returned invalid or mismatched session evidence")
}
records, err := chatMessageRecords(messages)
if err != nil {
return ExportedSession{}, err
}
session.Messages = exportedMessages(records)
return session, nil
}
// The source exceeded the cap, so the session is larger than what was read
// and must never be presented as whole. The prefix still yields every turn
// that decoded before the cut.
records, _, err := decodeExportPrefix(exported.envelope, id)
if err != nil {
return ExportedSession{}, err
}
session.Messages = exportedMessages(records)
session.Truncated = true
return session, nil
}
// exportedMessages maps decoded native turns onto ExportedMessage, preserving
// every role and each part's raw JSON for unknown types.
func exportedMessages(records []nativeChatMessage) []ExportedMessage {
messages := make([]ExportedMessage, 0, len(records))
for _, record := range records {
message := ExportedMessage{
ID: record.messageID(),
Role: record.role(),
Model: record.modelID(),
Agent: record.agent(),
CreatedAt: record.createdAt(),
}
for _, part := range record.contentParts() {
message.Parts = append(message.Parts, ExportedPart{
Type: part.Type, ID: part.ID, Text: part.Text, Name: part.Name,
State: part.State, Time: part.Time, Raw: part.Raw,
})
}
// A v2 user turn carries its prompt text as a message-level string rather
// than a content array, so surface it as the turn's single text part.
if len(message.Parts) == 0 && message.Role == protocol.ChatRoleUser && record.Text != "" {
message.Parts = append(message.Parts, ExportedPart{Type: protocol.ChatPartText, Text: record.Text})
}
messages = append(messages, message)
}
return messages
}
// decodeExportPrefix streams the messages of a bounded export prefix. Complete
// turns decoded before the cut are returned with truncated=true; a mismatched
// info.id is an error so an unrelated session is never exported.
func decodeExportPrefix(data []byte, wantID string) ([]nativeChatMessage, bool, error) {
decoder := json.NewDecoder(bytes.NewReader(data))
open, err := decoder.Token()
if err != nil {
return nil, false, fmt.Errorf("native export returned invalid session evidence")
}
if delim, ok := open.(json.Delim); !ok || delim != '{' {
return nil, false, fmt.Errorf("native export returned invalid session evidence")
}
var messages []nativeChatMessage
sawMessages := false
for decoder.More() {
keyToken, err := decoder.Token()
if err != nil {
return messages, true, nil
}
key, _ := keyToken.(string)
switch key {
case "info":
var info struct {
ID string `json:"id"`
}
if err := decoder.Decode(&info); err != nil {
return messages, true, nil
}
if info.ID != "" && info.ID != wantID {
return nil, false, fmt.Errorf("native export session id mismatch")
}
case "messages":
sawMessages = true
open, err := decoder.Token()
if err != nil {
return messages, true, nil
}
if delim, ok := open.(json.Delim); !ok || delim != '[' {
return nil, false, fmt.Errorf("native export returned invalid session evidence")
}
for decoder.More() {
var message nativeChatMessage
if err := decoder.Decode(&message); err != nil {
return messages, true, nil
}
messages = append(messages, message)
}
if _, err := decoder.Token(); err != nil {
return messages, true, nil
}
default:
var skip json.RawMessage
if err := decoder.Decode(&skip); err != nil {
return messages, true, nil
}
}
}
if !sawMessages {
return nil, false, fmt.Errorf("native export returned no session messages")
}
if _, err := decoder.Token(); err != nil {
return messages, true, nil
}
return messages, false, nil
}
+159
View File
@@ -0,0 +1,159 @@
package opencode
import (
"context"
"path/filepath"
"strings"
"testing"
)
// exportFixture writes a fake `opencode` CLI that answers only the session
// export invocation with the given JSON body, accepting both the v1 top-level
// `export <id>` and the v2 `session export <id>` forms, so the native export
// path is exercised without a real service.
func exportFixture(t *testing.T, id, body string) string {
t.Helper()
script := "#!/bin/sh\n" +
"[ \"$1\" = export ] && shift || { [ \"$1\" = session ] && [ \"$2\" = export ] && shift 2 || exit 8; }\n" +
"[ \"$1\" = " + id + " ] || exit 9\n" +
"cat <<'EOF'\n" + body + "\nEOF\n"
return writeFixture(t, script)
}
func TestExportSessionDecodesRolesPartsAndUnknownTypes(t *testing.T) {
id := "ses_ok"
body := `{"info":{"id":"ses_ok"},"messages":[` +
`{"info":{"id":"m1","role":"assistant","modelID":"gpt"},"parts":[` +
`{"type":"text","text":"hello"},` +
`{"type":"reasoning","text":"because"},` +
`{"type":"tool","name":"read","state":{"status":"completed","input":{"path":"a.go"},"content":[{"type":"text","text":"ok"}]}},` +
`{"type":"file","uri":"file:///tmp/x"}]},` +
`{"info":{"id":"m2","role":"user"},"text":"hi"}]}`
bin := exportFixture(t, id, body)
session, err := ExportSession(context.Background(), bin, t.TempDir(), "v2", id)
if err != nil {
t.Fatal(err)
}
if session.ID != id || session.Backend != "v2" || session.Truncated {
t.Fatalf("unexpected session: %+v", session)
}
if len(session.Messages) != 2 {
t.Fatalf("messages = %d, want 2", len(session.Messages))
}
assistant := session.Messages[0]
if assistant.Role != "assistant" || assistant.ID != "m1" || assistant.Model != "gpt" {
t.Fatalf("assistant metadata wrong: %+v", assistant)
}
if len(assistant.Parts) != 4 {
t.Fatalf("assistant parts = %d, want 4 (unknown type kept)", len(assistant.Parts))
}
if assistant.Parts[0].Type != "text" || assistant.Parts[0].Text != "hello" {
t.Fatalf("text part wrong: %+v", assistant.Parts[0])
}
if assistant.Parts[1].Type != "reasoning" || assistant.Parts[1].Text != "because" {
t.Fatalf("reasoning part wrong: %+v", assistant.Parts[1])
}
tool := assistant.Parts[2]
if tool.Type != "tool" || tool.Name != "read" || tool.State == nil || tool.State.Status != "completed" {
t.Fatalf("tool part wrong: %+v", tool)
}
if len(tool.State.Input) == 0 || string(tool.State.Input) != `{"path":"a.go"}` {
t.Fatalf("tool input lost: %s", tool.State.Input)
}
if len(tool.State.Content) != 1 || tool.State.Content[0].Text != "ok" {
t.Fatalf("tool output lost: %+v", tool.State.Content)
}
unknown := assistant.Parts[3]
if unknown.Type != "file" || !strings.Contains(string(unknown.Raw), "file:///tmp/x") {
t.Fatalf("unknown part raw JSON lost: %+v", unknown)
}
user := session.Messages[1]
if user.Role != "user" || len(user.Parts) != 1 || user.Parts[0].Text != "hi" {
t.Fatalf("user message-level text not surfaced: %+v", user)
}
}
func TestExportSessionRejectsMismatchedOrInvalidID(t *testing.T) {
bin := exportFixture(t, "ses_other", `{"info":{"id":"ses_other"},"messages":[{"info":{"role":"assistant"}}]}`)
if _, err := ExportSession(context.Background(), bin, t.TempDir(), "v2", "ses_want"); err == nil {
t.Fatal("mismatched session export accepted")
}
if _, err := ExportSession(context.Background(), bin, t.TempDir(), "v2", "not-a-session"); err == nil {
t.Fatal("invalid session id accepted without running the CLI")
}
}
func TestExportSessionFailsSanitizedWhenCLIUnavailable(t *testing.T) {
bin := filepath.Join(t.TempDir(), "absent-opencode")
if _, err := ExportSession(context.Background(), bin, t.TempDir(), "v2", "ses_ok"); err == nil {
t.Fatal("missing CLI must fail the export")
}
}
func TestExportNativeReportsBoundedOverflow(t *testing.T) {
id := "ses_ok"
body := `{"info":{"id":"ses_ok"},"messages":[{"info":{"role":"assistant"},"parts":[{"type":"text","text":"` + strings.Repeat("x", 256) + `"}]}]}`
bin := exportFixture(t, id, body)
res, err := exportNative(context.Background(), bin, t.TempDir(), "v2", id, 32)
if err != nil {
t.Fatal(err)
}
if !res.truncated {
t.Fatal("bounded stdout overflow was not reported")
}
if len(res.envelope) != 32 {
t.Fatalf("bounded prefix = %d bytes, want 32", len(res.envelope))
}
}
func TestExportNativeUsesBackendSubcommand(t *testing.T) {
id := "ses_ok"
body := `{"info":{"id":"ses_ok"},"messages":[{"info":{"role":"assistant"},"parts":[{"type":"text","text":"hello"}]}]}`
bin := exportFixture(t, id, body)
// Both a v1 (top-level export) and a v2 (session export) CLI accept the one
// shared invocation.
for _, backend := range []string{"v1", "v2"} {
session, err := ExportSession(context.Background(), bin, t.TempDir(), backend, id)
if err != nil || len(session.Messages) != 1 {
t.Fatalf("backend %s export failed: %v %+v", backend, err, session)
}
}
}
func TestExportSessionKeepsCompleteTurnsFromOverCapSource(t *testing.T) {
id := "ses_ok"
huge := strings.Repeat("x", MaxSessionExport+(1<<20))
body := `{"info":{"id":"ses_ok"},"messages":[` +
`{"info":{"role":"assistant"},"parts":[{"type":"text","text":"first"}]},` +
`{"info":{"role":"user"},"parts":[{"type":"text","text":"` + huge + `"}]}]}`
bin := exportFixture(t, id, body)
session, err := ExportSession(context.Background(), bin, t.TempDir(), "v2", id)
if err != nil {
t.Fatal(err)
}
if !session.Truncated {
t.Fatal("an over-cap source must be reported truncated")
}
if len(session.Messages) != 1 || session.Messages[0].Parts[0].Text != "first" {
t.Fatalf("complete turn before the cut was lost: %+v", session.Messages)
}
}
func TestDecodeExportPrefixRejectsMismatchedID(t *testing.T) {
id := "ses_ok"
full := `{"info":{"id":"ses_ok"},"messages":[` +
`{"info":{"role":"assistant"},"parts":[{"type":"text","text":"first"}]},` +
`{"info":{"role":"user"},"parts":[{"type":"text","text":"second"}]}]}`
// Cut mid-way through the second message so only the first is complete.
cut := strings.Index(full, `"second"`) + len(`"second"`) - 3
records, truncated, err := decodeExportPrefix([]byte(full[:cut]), id)
if err != nil {
t.Fatal(err)
}
if !truncated || len(records) != 1 || records[0].role() != "assistant" {
t.Fatalf("prefix decode = %d records, truncated=%v", len(records), truncated)
}
if _, _, err := decodeExportPrefix([]byte(full), "ses_other"); err == nil {
t.Fatal("mismatched prefix session accepted")
}
}
+31 -16
View File
@@ -3,9 +3,9 @@ package opencode
import (
"bytes"
"context"
"encoding/json"
"errors"
"fmt"
"io"
"strings"
)
@@ -26,6 +26,30 @@ func (b *boundedOutput) Write(p []byte) (int, error) {
return n, nil
}
// ReadFrom reads through the bounded Write so the cap applies even when
// os/exec's io.Copy selects a ReadFrom on the destination: without this the
// embedded bytes.Buffer's promoted ReadFrom would bypass Write and buffer the
// whole output without bound, making overflow (and the truncation path) dead.
func (b *boundedOutput) ReadFrom(r io.Reader) (int64, error) {
var total int64
buffer := make([]byte, 32<<10)
for {
n, err := r.Read(buffer)
if n > 0 {
if _, writeErr := b.Write(buffer[:n]); writeErr != nil {
return total, writeErr
}
total += int64(n)
}
if err != nil {
if errors.Is(err, io.EOF) {
return total, nil
}
return total, err
}
}
}
// Messages preserves old sessions with native OutputFormat readback failures:
// the CLI export reads the local stored data without that HTTP encoder. It does
// not regenerate, repair the database, delete history or change conversations.
@@ -48,12 +72,8 @@ func (c *Connection) Messages(ctx context.Context, id string) ([]byte, error) {
if executable == "" {
executable = Executable()
}
cmd := CommandContext(ctx, executable, "export", id)
cmd.Dir = c.Directory
stdout, stderr := &boundedOutput{limit: MaxResponse}, &boundedOutput{limit: 8 << 10}
cmd.Stdout = stdout
cmd.Stderr = stderr
if exportErr := cmd.Run(); exportErr != nil {
res, exportErr := exportNative(ctx, executable, c.Directory, c.Backend, id, MaxResponse)
if exportErr != nil {
if ctx.Err() != nil {
return data, ctx.Err()
}
@@ -61,18 +81,13 @@ func (c *Connection) Messages(ctx context.Context, id string) ([]byte, error) {
// preserving exec.ErrWaitDelay from a descendant-held output pipe.
return data, errors.Join(err, fmt.Errorf("read-only native export fallback failed: %w", exportErr))
}
if stdout.overflow {
if res.truncated {
return data, fmt.Errorf("%w; native export exceeds 1 MiB evidence limit", err)
}
var exported struct {
Info struct {
ID string `json:"id"`
} `json:"info"`
Messages json.RawMessage `json:"messages"`
}
if json.Unmarshal(stdout.Bytes(), &exported) != nil || exported.Info.ID != id || len(exported.Messages) == 0 || exported.Messages[0] != '[' {
messages, ok := validNativeExport(res.envelope, id)
if !ok {
return data, fmt.Errorf("%w; native export returned invalid or mismatched session evidence", err)
}
c.MessageReadbackDiagnostic = "Native HTTP message readback rejected stored OutputFormat (HTTP 400); read-only CLI export recovered the original messages without modifying the session."
return exported.Messages, nil
return messages, nil
}