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
+30
View File
@@ -52,6 +52,36 @@ return `206 Partial Content` with the exact slice (or `416` when unsatisfiable),
so images and video can stream. `http.ServeContent` streams from the opened file,
so a request never loads the whole file into memory.
## Session export
When a model stage that ran against an OpenCode harness finishes, the server also
exports the session the harness actually produced and writes it into the same
`<artifacts root>/<run>/<step>/` directory in markdown (`session.md`) and html
(`session.html`). They are ordinary artifacts: the bounded inventory lists them
and `GET /artifacts/<run>/<step>/session.md` (or `.html`) serves them with no
special casing.
- Source: the read-only native export path. The native v1 CLI exposes it as
`opencode export <id>`; the installed v2 CLI exposes it as
`opencode session export <id>`. Both reuse the same invocation helper and
session-ID/messages validation as the transcript readback. The files are the
harness's real session, never a reconstruction.
- Bounds: the source read is capped at 8 MiB and each rendered file at 2 MiB. When
either the source or the rendered output is cut, both files carry a visible
truncation banner near the start and the end and the step records
`truncated: true`; a truncated export is never described as whole.
- Evidence: the step records `session_export` (`session_id`, `backend`, `source`,
`markdown`, `html`, `markdown_bytes`, `html_bytes`, `messages`, `truncated`,
`diagnostic`), so `pipelines inspect RUN_ID --json` shows what was written
without reading the files.
- Isolation: exporting never changes the stage's status, outcome, target or
result validation, never waits for the session, never mutates, resumes or
interrupts it, and a failure records a sanitized diagnostic and continues. An
existing `session.md`/`session.html` is never overwritten and the skip reason is
recorded.
- Pi limitation: a Pi stage has no native session export path, so the step records
`source: "unavailable"` with an explicit diagnostic and writes no files.
## Removal with run history
Run artifacts live under `<root>/<run>/<step>` and last as long as the run does.
@@ -17,6 +17,11 @@ with its own rules.
oversized file records nothing and never changes the verdict. Never invent an
artifact or claim a stage produced one — the server observes the directory after the
stage.
- An OpenCode-harness stage also gets its real session exported as `session.md` and
`session.html` in the same directory: bounded (8 MiB source, 2 MiB per file), with
a visible truncation banner and `session_export.truncated` when cut; the step's
`session_export` records the files. Export failures and Pi (no native export path)
record a diagnostic and never fail the run or change the stage result.
## Publish a build to the LAN
@@ -224,6 +224,21 @@ traversal, absolute paths, symlink escapes and unknown runs/steps.
- Do not invent artifact files or claim a stage produced one without the recorded
evidence; the server observes the directory after the stage.
### Session export
- When an OpenCode-harness model stage finishes, the server exports its real
session read-only (v1 `opencode export <id>`, v2 `opencode session export <id>`)
and writes `session.md` and `session.html` into the same `<run>/<step>` artifacts
directory; they list and serve like any other artifact.
- The source read is capped at 8 MiB and each file at 2 MiB; a cut source or a cut
rendered file carries a visible truncation banner at both ends and
`session_export.truncated: true`, and a truncated export is never called whole.
- The step records `session_export` (`session_id`, `backend`, `source`, file names,
sizes, `messages`, `truncated`, `diagnostic`) in `inspect RUN_ID --json`.
- A failed export, or a Pi stage with no native export path, records a diagnostic
(Pi: `source: "unavailable"`) and never fails the run or changes the stage result.
An existing `session.md`/`session.html` is never overwritten.
### Operator-only retention
Run history and its artifacts are never pruned automatically. The operator-only
+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
}
+1
View File
@@ -625,6 +625,7 @@ func deleteRetentionRows(ctx context.Context, tx *sql.Tx, ids []int64) error {
{"step_control", "run_id"},
{"step_artifacts", "run_id"},
{"step_verdicts", "run_id"},
{"step_session_exports", "run_id"},
{"run_session_owners", "run_id"},
{"run_steps", "run_id"},
} {
+21 -2
View File
@@ -47,6 +47,9 @@ PRIMARY KEY(run_id,sequence), FOREIGN KEY(run_id,sequence) REFERENCES run_steps(
CREATE TABLE IF NOT EXISTS step_verdicts (
run_id INTEGER NOT NULL, sequence INTEGER NOT NULL, verdict_json TEXT NOT NULL,
PRIMARY KEY(run_id,sequence), FOREIGN KEY(run_id,sequence) REFERENCES run_steps(run_id,sequence));
CREATE TABLE IF NOT EXISTS step_session_exports (
run_id INTEGER NOT NULL, sequence INTEGER NOT NULL, export_json TEXT NOT NULL,
PRIMARY KEY(run_id,sequence), FOREIGN KEY(run_id,sequence) REFERENCES run_steps(run_id,sequence));
CREATE TABLE IF NOT EXISTS run_session_owners (
run_id INTEGER NOT NULL, sequence INTEGER NOT NULL, backend TEXT NOT NULL, reference TEXT NOT NULL DEFAULT '',
PRIMARY KEY(run_id,sequence), FOREIGN KEY(run_id,sequence) REFERENCES run_steps(run_id,sequence));
@@ -343,6 +346,7 @@ COALESCE((SELECT receipts_json FROM step_notifications n WHERE n.run_id=run_step
COALESCE((SELECT changes_json FROM step_file_changes f WHERE f.run_id=run_steps.run_id AND f.sequence=run_steps.sequence),'null'),
COALESCE((SELECT artifacts_json FROM step_artifacts a WHERE a.run_id=run_steps.run_id AND a.sequence=run_steps.sequence),'null'),
COALESCE((SELECT verdict_json FROM step_verdicts v WHERE v.run_id=run_steps.run_id AND v.sequence=run_steps.sequence),''),
COALESCE((SELECT export_json FROM step_session_exports x WHERE x.run_id=run_steps.run_id AND x.sequence=run_steps.sequence),''),
strftime('%Y-%m-%dT%H:%M:%SZ',started_at),COALESCE(strftime('%Y-%m-%dT%H:%M:%SZ',finished_at),'') FROM run_steps WHERE run_id=? ORDER BY sequence`, id)
if err != nil {
return nil, err
@@ -351,8 +355,8 @@ strftime('%Y-%m-%dT%H:%M:%SZ',started_at),COALESCE(strftime('%Y-%m-%dT%H:%M:%SZ'
for rows.Next() {
var step protocol.RunStep
var notifications string
var fileChanges, artifacts, storedVerdict string
if err := rows.Scan(&step.Sequence, &step.Stage, &step.Status, &step.Outcome, &step.Target, &input, &output, &step.Diagnostic, &step.SessionID, &step.AgentActive, &step.Transcript, &step.Provider, &step.Model, &notifications, &fileChanges, &artifacts, &storedVerdict, &step.StartedAt, &step.FinishedAt); err != nil {
var fileChanges, artifacts, storedVerdict, sessionExport string
if err := rows.Scan(&step.Sequence, &step.Stage, &step.Status, &step.Outcome, &step.Target, &input, &output, &step.Diagnostic, &step.SessionID, &step.AgentActive, &step.Transcript, &step.Provider, &step.Model, &notifications, &fileChanges, &artifacts, &storedVerdict, &sessionExport, &step.StartedAt, &step.FinishedAt); err != nil {
rows.Close()
return nil, err
}
@@ -394,6 +398,12 @@ strftime('%Y-%m-%dT%H:%M:%SZ',started_at),COALESCE(strftime('%Y-%m-%dT%H:%M:%SZ'
}
}
step.Verdict = protocol.NewStageVerdict(step.Outcome, step.Target, step.Output, step.Artifacts, stored.Reason, stored.Source)
if sessionExport != "" {
if err := json.Unmarshal([]byte(sessionExport), &step.SessionExport); err != nil {
rows.Close()
return nil, err
}
}
// Loaded below after the rows cursor closes to preserve SQLite connection use.
r.Steps = append(r.Steps, step)
}
@@ -634,6 +644,15 @@ WHERE run_id=? AND sequence=? AND status='running'`, step.Status, step.Outcome,
return err
}
}
if step.SessionExport != nil {
data, err := json.Marshal(step.SessionExport)
if err != nil {
return err
}
if _, err := tx.ExecContext(ctx, "INSERT INTO step_session_exports(run_id,sequence,export_json) VALUES(?,?,?)", id, step.Sequence, string(data)); err != nil {
return err
}
}
return tx.Commit()
}
+60
View File
@@ -446,3 +446,63 @@ func TestOwnedSessionsListsRecordedWithActiveFlag(t *testing.T) {
t.Fatalf("ActiveSessionOwners = %+v %v, want both now-active sessions", active, err)
}
}
// TestSessionExportRoundTripAndAbsentEvidence proves a recorded session export
// survives FinishStep/GetRun and that a step with no export row (an old database
// that gained the empty table on Open) loads with no export evidence.
func TestSessionExportRoundTripAndAbsentEvidence(t *testing.T) {
ctx := context.Background()
store, err := Open(filepath.Join(t.TempDir(), "session-exports.db"))
if err != nil {
t.Fatal(err)
}
defer store.Close()
if _, err := store.Submit(ctx, "exports", Template([]string{"one"}, true)); err != nil {
t.Fatal(err)
}
items, _ := store.List(ctx)
definition, _ := store.Get(ctx, items[0].ID, 1)
withExport, _, err := store.CreateRun(ctx, definition, "with-export", "workspace", false, nil, map[string]any{"prompt": "task"})
if err != nil {
t.Fatal(err)
}
withoutExport, _, err := store.CreateRun(ctx, definition, "without-export", "workspace", false, nil, map[string]any{"prompt": "task"})
if err != nil {
t.Fatal(err)
}
for _, id := range []int64{withExport, withoutExport} {
if err := store.BeginStep(ctx, id, 1, "one", map[string]any{"prompt": "task"}); err != nil {
t.Fatal(err)
}
}
want := &protocol.SessionExport{
SessionID: "ses_recorded", Backend: "v2", Source: "native_export",
Markdown: "session.md", HTML: "session.html",
MarkdownBytes: 1234, HTMLBytes: 2345, Messages: 9, Truncated: true,
Diagnostic: "kept",
}
if err := store.FinishStep(ctx, withExport, protocol.RunStep{Sequence: 1, Stage: "one", Status: "completed", Outcome: "success", Output: map[string]any{}, Transcript: strings.Repeat("x", 40<<10), SessionExport: want}); err != nil {
t.Fatal(err)
}
if err := store.FinishStep(ctx, withoutExport, protocol.RunStep{Sequence: 1, Stage: "one", Status: "completed", Outcome: "success", Output: map[string]any{}}); err != nil {
t.Fatal(err)
}
got, err := store.GetRun(ctx, withExport)
if err != nil {
t.Fatal(err)
}
if len(got.Steps) != 1 || got.Steps[0].SessionExport == nil || *got.Steps[0].SessionExport != *want {
t.Fatalf("session export did not round-trip: %+v", got.Steps[0].SessionExport)
}
// The export evidence must not change how the transcript is bounded.
if len(got.Steps[0].Transcript) > 32<<10 || !strings.Contains(got.Steps[0].Transcript, "truncated") {
t.Fatalf("transcript bound changed by export: %d bytes", len(got.Steps[0].Transcript))
}
plain, err := store.GetRun(ctx, withoutExport)
if err != nil {
t.Fatal(err)
}
if plain.Steps[0].SessionExport != nil {
t.Fatalf("absent export evidence was fabricated: %+v", plain.Steps[0].SessionExport)
}
}
+18
View File
@@ -100,6 +100,23 @@ type SessionEvidence struct {
Diagnostic string `json:"diagnostic,omitempty"`
}
// SessionExport is the recorded evidence of one stage's session file export:
// the file names written under the step's artifacts directory, their byte sizes,
// the decoded message count, the source, whether the export was truncated and a
// sanitized diagnostic. It is observed server-side evidence, not a model claim.
type SessionExport struct {
SessionID string `json:"session_id,omitempty"`
Backend string `json:"backend,omitempty"`
Source string `json:"source,omitempty"`
Markdown string `json:"markdown,omitempty"`
HTML string `json:"html,omitempty"`
MarkdownBytes int64 `json:"markdown_bytes,omitempty"`
HTMLBytes int64 `json:"html_bytes,omitempty"`
Messages int `json:"messages"`
Truncated bool `json:"truncated,omitempty"`
Diagnostic string `json:"diagnostic,omitempty"`
}
type RunSummary struct {
ID int64 `json:"id"`
PipelineID int64 `json:"pipeline_id"`
@@ -142,6 +159,7 @@ type RunStep struct {
Control *ControlEvidence `json:"control,omitempty"`
FileChanges *StageFileChanges `json:"file_changes,omitempty"`
Verdict *StageVerdict `json:"verdict,omitempty"`
SessionExport *SessionExport `json:"session_export,omitempty"`
Notifications []NotificationReceipt `json:"notifications,omitempty"`
Artifacts []StageArtifact `json:"artifacts,omitempty"`
Sequence int `json:"sequence"`
+67 -5
View File
@@ -46,9 +46,13 @@ type runner struct {
verdict func(context.Context, map[string]any) string
// events pushes run state deltas to subscribed clients. When nil (tests that
// build a runner directly) emits are dropped, so nothing else changes.
events *runEventHub
wg sync.WaitGroup
schedulerWG sync.WaitGroup
events *runEventHub
// exportSession writes a finished stage's session into its own artifacts
// directory. It defaults to stage.ExportSession; a failure is best-effort and
// never changes the stage's status, outcome, target or result validation.
exportSession func(context.Context, stage.SessionExportRequest) (stage.SessionExportResult, error)
wg sync.WaitGroup
schedulerWG sync.WaitGroup
// attentionMu guards attentionSent, the per-run set of run-attention events
// already delivered — by a stage's own notify policy or by the run-level
// default — so neither republishes the same genuine event.
@@ -78,7 +82,7 @@ func newRunner(ctx context.Context, s *pipeline.Store) (*runner, error) {
return nil, err
}
root := filepath.Join(s.Directory(), "artifacts")
return &runner{ctx: ctx, store: s, artifactsRoot: root, active: map[int64]activeRun{}, attentionSent: map[int64]map[string]bool{}}, nil
return &runner{ctx: ctx, store: s, artifactsRoot: root, active: map[int64]activeRun{}, attentionSent: map[int64]map[string]bool{}, exportSession: stage.ExportSession}, nil
}
func (r *runner) start(request protocol.Message, retryOf ...int64) (*protocol.RunDetail, error) {
@@ -956,8 +960,19 @@ func (r *runner) runLoop(ctx context.Context, id int64, graph protocol.Graph, na
changes.Status = "partial"
changes.Diagnostic = "Agent cleanup was not confirmed; files may still be changing."
}
// Export the stage's session into its own artifacts directory before the
// bounded scan, so the existing listing and serving paths find the files
// with no special casing. This is bounded, best-effort evidence: it never
// waits for session idleness and a failure never changes the stage's
// status, outcome, target or result validation.
var sessionExport *protocol.SessionExport
if artifactsDir != "" {
if owner, ownerErr := r.store.RunSessionOwner(ctx, id, sequence); ownerErr == nil && owner.ID != "" {
sessionExport = r.exportStageSession(ctx, owner, artifactsDir, id, sequence, key, modelConfig)
}
}
artifacts, artifactsSkipped, artifactsTruncated := r.scanArtifacts(id, sequence, artifactsDir)
step := protocol.RunStep{Sequence: sequence, Stage: key, Status: "completed", Outcome: result.Outcome, Output: result.Output, Transcript: operations.Transcript(client.Transcript), SessionID: stageSession, FileChanges: changes, Artifacts: artifacts, ArtifactsSkipped: artifactsSkipped, ArtifactsTruncated: artifactsTruncated}
step := protocol.RunStep{Sequence: sequence, Stage: key, Status: "completed", Outcome: result.Outcome, Output: result.Output, Transcript: operations.Transcript(client.Transcript), SessionID: stageSession, FileChanges: changes, SessionExport: sessionExport, Artifacts: artifacts, ArtifactsSkipped: artifactsSkipped, ArtifactsTruncated: artifactsTruncated}
// Stamp the effective provider/model this visit actually ran with for every
// model stage, including failures, so the app/TUI evidence reflects any
// override. Non-model stages keep empty values.
@@ -1058,6 +1073,53 @@ func (r *runner) runLoop(ctx context.Context, id int64, graph protocol.Graph, na
finish("failed", "error", "total stage budget exceeded")
}
// exportStageSession writes the finished stage's session into its own artifacts
// directory and returns the evidence for the step. A non-OpenCode harness (pi)
// has no native export path, so it records that limitation and writes no files.
// Any export error is recorded as a sanitized diagnostic and never returned to
// the stage: the export is read-only, bounded and best-effort.
func (r *runner) exportStageSession(ctx context.Context, owner pipeline.SessionOwner, artifactsDir string, runID int64, sequence int, key string, modelConfig stage.ModelConfig) *protocol.SessionExport {
evidence := &protocol.SessionExport{SessionID: owner.ID, Backend: owner.Backend}
if owner.Backend != "v1" && owner.Backend != "v2" {
evidence.Source = "unavailable"
evidence.Diagnostic = "session export unavailable: harness has no native export path"
return evidence
}
export := r.exportSession
if export == nil {
export = stage.ExportSession
}
// A canceled stage still gets one bounded, non-blocking attempt; the export
// never consumes the stage timeout and never waits for the session.
exportCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), stage.SessionExportTimeout)
defer cancel()
result, err := export(exportCtx, stage.SessionExportRequest{
SessionID: owner.ID,
Backend: owner.Backend,
Directory: owner.Directory,
ArtifactsDir: artifactsDir,
RunID: runID,
Sequence: sequence,
Stage: key,
Provider: modelConfig.Provider,
Model: modelConfig.Model,
})
if err != nil {
evidence.Source = "native_export"
evidence.Diagnostic = stage.RedactEvidence(err.Error())
return evidence
}
evidence.Source = result.Source
evidence.Markdown = result.Markdown
evidence.HTML = result.HTML
evidence.MarkdownBytes = result.MarkdownBytes
evidence.HTMLBytes = result.HTMLBytes
evidence.Messages = result.Messages
evidence.Truncated = result.Truncated
evidence.Diagnostic = result.Diagnostic
return evidence
}
// setTitle renames a run: it replaces the stored operator-facing title without
// touching the run's input, steps or execution, then returns the updated detail.
func (r *runner) setTitle(id int64, title string) (*protocol.RunDetail, error) {
+168
View File
@@ -0,0 +1,168 @@
package server
import (
"context"
"fmt"
"io"
"net/http"
"net/http/httptest"
"os"
"path/filepath"
"strings"
"testing"
"time"
"git.a-wan.net/alan/pipelines/internal/pipeline"
"git.a-wan.net/alan/pipelines/internal/protocol"
"git.a-wan.net/alan/pipelines/internal/stage"
)
// sessionExportLiveSource is a one-stage pipeline that declares the read tool so
// the stage runs as an agent (the V2 path that persists session messages) while
// the prompt tells it not to use any tool.
func sessionExportLiveSource(provider, model string) string {
return "# stage one\n\n```output\n{ summary }\n```\n\n" +
"```prompt\nReturn success with summary exactly: session export live check. Do not use any tool.\n```\n\n" +
"```tools\nread\n```\n\n" +
"```configs\nprovider=" + provider + "\nmodel=" + model + "\nretries=0\ntimeout=2m\n```\n\n" +
"```edges\nsuccess -> #success\nerror -> #failure\n```\n\n"
}
// TestSessionExportLive is an opt-in live check: it runs one real OpenCode stage
// on a temporary store and artifacts root using the configured host harness,
// then proves the real session.md/session.html are written, listed and served
// 200. It is gated so the default suite never spends inference.
func TestSessionExportLive(t *testing.T) {
if os.Getenv("PIPELINES_SESSION_EXPORT_LIVE") != "1" {
t.Skip("set PIPELINES_SESSION_EXPORT_LIVE=1 and PIPELINES_SESSION_EXPORT_MODEL to run chargeable session-export inference")
}
model := os.Getenv("PIPELINES_SESSION_EXPORT_MODEL")
provider, id, ok := strings.Cut(model, "/")
if !ok || !stage.ValidModel(provider, id) {
t.Fatal("explicit valid PIPELINES_SESSION_EXPORT_MODEL required")
}
// Isolate notifications from the operator's real ntfy service.
endpoint := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Content-Type", "application/json")
fmt.Fprint(w, `{"id":"session-export-live-receipt","event":"message"}`)
}))
defer endpoint.Close()
t.Setenv("PIPELINES_NTFY_URL", endpoint.URL+"/live")
t.Setenv("PIPELINES_NTFY_TOKEN", "")
t.Setenv("PIPELINES_NTFY_TOKEN_FILE", "")
ctx, cancel := context.WithTimeout(context.Background(), 6*time.Minute)
defer cancel()
root := t.TempDir()
store, err := pipeline.Open(filepath.Join(root, "runs.db"))
if err != nil {
t.Fatal(err)
}
defer store.Close()
if _, err := store.Submit(ctx, "session-export-live", sessionExportLiveSource(provider, id)); err != nil {
t.Fatal(err)
}
items, err := store.List(ctx)
if err != nil {
t.Fatal(err)
}
handler := Handler(ctx, store).(*runHandler)
handler.runner.artifactsRoot = filepath.Join(root, "artifacts")
defer func() { cancel(); WaitRuns(handler) }()
workspace := filepath.Join(root, "ws")
if err := os.Mkdir(workspace, 0700); err != nil {
t.Fatal(err)
}
run, err := handler.runner.start(protocol.Message{
PipelineID: items[0].ID, Version: 1, RequestKey: "session-export-live",
Workspace: workspace, Input: map[string]any{"prompt": "Return the fixed session export live check."},
})
if err != nil {
t.Fatal(err)
}
handler.runner.wg.Wait()
detail, err := store.GetRun(context.Background(), run.ID)
if err != nil {
t.Fatal(err)
}
if detail.Status != "succeeded" || len(detail.Steps) != 1 {
t.Fatalf("live run did not succeed: %+v", detail)
}
step := detail.Steps[0]
if step.SessionExport == nil || step.SessionExport.Source != "native_export" || step.SessionExport.MarkdownBytes == 0 || step.SessionExport.HTMLBytes == 0 {
t.Fatalf("live session export evidence missing: %+v", step.SessionExport)
}
if step.SessionExport.Messages == 0 || step.SessionExport.Truncated {
t.Fatalf("live session export was empty or truncated: %+v", step.SessionExport)
}
srv := httptest.NewServer(handler)
defer srv.Close()
for _, name := range []string{"session.md", "session.html"} {
artifact, ok := artifactNamed(step.Artifacts, name)
if !ok {
t.Fatalf("%s not in live artifact listing: %+v", name, step.Artifacts)
}
resp, err := http.Get(srv.URL + artifact.URL)
if err != nil {
t.Fatal(err)
}
body, _ := io.ReadAll(resp.Body)
resp.Body.Close()
if resp.StatusCode != http.StatusOK {
t.Fatalf("%s served HTTP %d", name, resp.StatusCode)
}
path := filepath.Join(handler.runner.artifactsRoot, fmt.Sprint(run.ID), "1", name)
if evidenceDir := os.Getenv("PIPELINES_SESSION_EXPORT_LIVE_DIR"); evidenceDir != "" {
if err := os.MkdirAll(evidenceDir, 0700); err != nil {
t.Fatal(err)
}
if err := os.WriteFile(filepath.Join(evidenceDir, name), body, 0600); err != nil {
t.Fatal(err)
}
}
first := string(body)
if idx := strings.IndexByte(first, '\n'); idx >= 0 {
first = first[:idx]
}
t.Logf("live export %s: path=%s size=%d messages=%d url=%s http=%d first_line=%q", name, path, len(body), step.SessionExport.Messages, artifact.URL, resp.StatusCode, first)
}
}
// TestSessionExportRecorded is the fallback evidence path: with no chargeable
// inference, it exports one real recorded session read-only through the same
// code path, clearly labelled as not produced by a fresh runner stage.
func TestSessionExportRecorded(t *testing.T) {
session := os.Getenv("PIPELINES_SESSION_EXPORT_RECORDED_ID")
if session == "" {
t.Skip("set PIPELINES_SESSION_EXPORT_RECORDED_ID and _DIR to export a recorded session read-only (no inference)")
}
dir := os.Getenv("PIPELINES_SESSION_EXPORT_RECORDED_DIR")
if dir == "" {
t.Fatal("PIPELINES_SESSION_EXPORT_RECORDED_DIR required")
}
if err := os.MkdirAll(dir, 0700); err != nil {
t.Fatal(err)
}
result, err := stage.ExportSession(context.Background(), stage.SessionExportRequest{
SessionID: session, Backend: "v2", Directory: dir, ArtifactsDir: dir,
RunID: 0, Sequence: 0, Stage: "recorded",
})
if err != nil {
t.Fatalf("recorded session export failed: %v", err)
}
for _, name := range []string{stage.SessionMarkdownFile, stage.SessionHTMLFile} {
info, err := os.Stat(filepath.Join(dir, name))
if err != nil {
t.Fatal(err)
}
data, _ := os.ReadFile(filepath.Join(dir, name))
first := string(data)
if idx := strings.IndexByte(first, '\n'); idx >= 0 {
first = first[:idx]
}
t.Logf("recorded export (NOT a fresh runner stage) %s: path=%s size=%d first_line=%q", name, filepath.Join(dir, name), info.Size(), first)
}
if result.MarkdownBytes == 0 || result.HTMLBytes == 0 {
t.Fatalf("recorded export wrote no files: %+v", result)
}
}
+222
View File
@@ -0,0 +1,222 @@
package server
import (
"context"
"errors"
"fmt"
"io"
"net/http"
"net/http/httptest"
"os"
"path/filepath"
"strings"
"testing"
"git.a-wan.net/alan/pipelines/internal/pipeline"
"git.a-wan.net/alan/pipelines/internal/protocol"
"git.a-wan.net/alan/pipelines/internal/stage"
)
// sessionExportBody is a minimal native export envelope with a user and an
// assistant turn, used by the fake CLI below.
const sessionExportBody = `{"info":{"id":"ses_run"},"messages":[` +
`{"info":{"id":"m1","role":"user"},"text":"do the task"},` +
`{"info":{"id":"m2","role":"assistant"},"parts":[` +
`{"type":"text","text":"done"},` +
`{"type":"tool","name":"shell","state":{"status":"completed","input":{"cmd":"ls"},"content":[{"type":"text","text":"output here"}]}}]}]}`
// sessionExportCLI points PIPELINES_OPENCODE at a fake `opencode export` that
// returns sessionExportBody, so the runner's real export path runs.
func sessionExportCLI(t *testing.T) {
t.Helper()
path := filepath.Join(t.TempDir(), "opencode")
script := "#!/bin/sh\n" +
"[ \"$1\" = export ] && shift || { [ \"$1\" = session ] && [ \"$2\" = export ] && shift 2 || exit 8; }\n" +
"[ \"$1\" = ses_run ] || exit 9\n" +
"cat <<'EOF'\n" + sessionExportBody + "\nEOF\n"
if err := os.WriteFile(path, []byte(script), 0700); err != nil {
t.Fatal(err)
}
t.Setenv("PIPELINES_OPENCODE", path)
}
// sessionExportRunner runs one stage that records a session for the run, so the
// runner's post-stage export has an owner to read. The export seam is supplied by
// the caller; ready gates the stage until the test has captured the run id.
func sessionExportRunner(t *testing.T, backend string, seam func(stage.SessionExportRequest) (stage.SessionExportResult, error)) (*runHandler, *pipeline.Store, int64) {
t.Helper()
ctx, cancel := context.WithCancel(context.Background())
t.Cleanup(cancel)
store, err := pipeline.Open(filepath.Join(t.TempDir(), "session.db"))
if err != nil {
t.Fatal(err)
}
t.Cleanup(func() { store.Close() })
if _, err := store.Submit(ctx, "session-export", pipeline.Template([]string{"one"}, true)); err != nil {
t.Fatal(err)
}
items, err := store.List(ctx)
if err != nil {
t.Fatal(err)
}
handler := Handler(ctx, store).(*runHandler)
t.Cleanup(func() { cancel(); WaitRuns(handler) })
handler.runner.artifactsRoot = t.TempDir()
if seam != nil {
handler.runner.exportSession = func(_ context.Context, request stage.SessionExportRequest) (stage.SessionExportResult, error) {
return seam(request)
}
}
ready := make(chan struct{})
var runID int64
handler.runner.execute = func(ctx context.Context, _ stage.Definition, _ stage.Values) (stage.Result, error) {
<-ready
if err := handler.runner.store.RunSession(ctx, runID, 1, "ses_run", true, backend, ""); err != nil {
return stage.Result{}, err
}
return stage.Result{Outcome: "success", Output: stage.Values{"summary": "done"}}, nil
}
run, err := handler.runner.start(protocol.Message{PipelineID: items[0].ID, Version: 1, RequestKey: "session", Workspace: t.TempDir(), Input: map[string]any{"prompt": "task"}})
if err != nil {
t.Fatal(err)
}
runID = run.ID
close(ready)
handler.runner.wg.Wait()
return handler, store, run.ID
}
// TestRunnerExportsSessionFilesIntoArtifactsAndServesThem proves the real export
// path writes both files into the step's artifacts directory, lists them with
// artifact URLs and serves them 200, without changing the step's status, outcome
// or target.
func TestRunnerExportsSessionFilesIntoArtifactsAndServesThem(t *testing.T) {
sessionExportCLI(t)
handler, store, runID := sessionExportRunner(t, "v2", nil)
detail, err := store.GetRun(context.Background(), runID)
if err != nil {
t.Fatal(err)
}
if detail.Status != "succeeded" || len(detail.Steps) != 1 {
t.Fatalf("unexpected run: %+v", detail)
}
step := detail.Steps[0]
if step.Status != "completed" || step.Outcome != "success" {
t.Fatalf("export changed the stage result: %+v", step)
}
if len(step.Transcript) > 32<<10 || strings.Contains(step.Transcript, "do the task") || strings.Contains(step.Transcript, "session.md") {
t.Fatalf("transcript was changed by the export: %q", step.Transcript)
}
if step.SessionExport == nil || step.SessionExport.SessionID != "ses_run" || step.SessionExport.Source != "native_export" {
t.Fatalf("export evidence missing: %+v", step.SessionExport)
}
if step.SessionExport.Messages != 2 || step.SessionExport.MarkdownBytes == 0 || step.SessionExport.HTMLBytes == 0 {
t.Fatalf("export evidence wrong: %+v", step.SessionExport)
}
for _, name := range []string{"session.md", "session.html"} {
artifact, ok := artifactNamed(step.Artifacts, name)
if !ok {
t.Fatalf("%s not in the artifact listing: %+v", name, step.Artifacts)
}
wantURL := fmt.Sprintf("/artifacts/%d/1/%s", runID, name)
if artifact.URL != wantURL || artifact.SizeBytes == 0 {
t.Fatalf("%s listing wrong: %+v", name, artifact)
}
}
srv := httptest.NewServer(handler)
defer srv.Close()
for _, name := range []string{"session.md", "session.html"} {
resp, err := http.Get(srv.URL + fmt.Sprintf("/artifacts/%d/1/%s", runID, name))
if err != nil {
t.Fatal(err)
}
body, _ := io.ReadAll(resp.Body)
resp.Body.Close()
if resp.StatusCode != http.StatusOK || len(body) == 0 {
t.Fatalf("%s served %d (%d bytes)", name, resp.StatusCode, len(body))
}
contentType := resp.Header.Get("Content-Type")
if name == "session.md" && !strings.HasPrefix(contentType, "text/markdown") && !strings.HasPrefix(contentType, "text/plain") {
t.Fatalf("session.md content type = %q", contentType)
}
if name == "session.html" && !strings.HasPrefix(contentType, "text/html") {
t.Fatalf("session.html content type = %q", contentType)
}
if name == "session.md" && !strings.Contains(string(body), "do the task") {
t.Fatalf("served markdown missing session text")
}
if name == "session.html" && !strings.Contains(string(body), "output here") {
t.Fatalf("served html missing tool output")
}
}
}
// TestRunnerSessionExportFailureTruncationAndUnavailableHarness proves the three
// non-success export outcomes are recorded as evidence and never fail the run.
func TestRunnerSessionExportFailureTruncationAndUnavailableHarness(t *testing.T) {
cases := []struct {
name string
backend string
seam func(stage.SessionExportRequest) (stage.SessionExportResult, error)
wantSrc string
wantDiag string
wantTrunc bool
}{
{
name: "failure",
backend: "v2",
seam: func(stage.SessionExportRequest) (stage.SessionExportResult, error) {
return stage.SessionExportResult{}, errors.New("native session export failed")
},
wantSrc: "native_export",
wantDiag: "native session export failed",
},
{
name: "truncated",
backend: "v2",
seam: func(stage.SessionExportRequest) (stage.SessionExportResult, error) {
return stage.SessionExportResult{Source: "native_export", Truncated: true, Messages: 3}, nil
},
wantSrc: "native_export",
wantTrunc: true,
},
{
name: "unavailable",
backend: "pi",
seam: nil,
wantSrc: "unavailable",
wantDiag: "harness has no native export path",
},
}
for _, tc := range cases {
t.Run(tc.name, func(t *testing.T) {
handler, store, runID := sessionExportRunner(t, tc.backend, tc.seam)
detail, err := store.GetRun(context.Background(), runID)
if err != nil {
t.Fatal(err)
}
if detail.Status != "succeeded" {
t.Fatalf("export outcome failed the run: %+v", detail.Status)
}
step := detail.Steps[0]
if step.Status != "completed" || step.Outcome != "success" {
t.Fatalf("export changed the stage result: %+v", step)
}
if step.SessionExport == nil || step.SessionExport.Source != tc.wantSrc {
t.Fatalf("export evidence wrong: %+v", step.SessionExport)
}
if tc.wantDiag != "" && !strings.Contains(step.SessionExport.Diagnostic, tc.wantDiag) {
t.Fatalf("diagnostic %q missing %q", step.SessionExport.Diagnostic, tc.wantDiag)
}
if step.SessionExport.Truncated != tc.wantTrunc {
t.Fatalf("truncated = %v, want %v", step.SessionExport.Truncated, tc.wantTrunc)
}
if tc.wantSrc == "unavailable" {
if artifacts, _, _ := handler.runner.scanArtifacts(runID, 1, filepath.Join(handler.runner.artifactsRoot, fmt.Sprint(runID), "1")); len(artifacts) != 0 {
t.Fatalf("unavailable harness wrote files: %+v", artifacts)
}
}
})
}
}
+452
View File
@@ -0,0 +1,452 @@
package stage
import (
"bytes"
"context"
"fmt"
"html"
"os"
"path/filepath"
"strconv"
"strings"
"time"
"git.a-wan.net/alan/pipelines/internal/opencode"
"git.a-wan.net/alan/pipelines/internal/protocol"
)
// Session file export bounds. A stage's session is written under its own
// artifacts directory in markdown and html so the existing artifact listing and
// serving paths find it with no special casing. The source read is capped at
// SessionExportSourceLimit and each rendered file at SessionExportFileLimit, so
// the pair adds at most ~4 MiB per step, inside the artifact scan limits.
const (
SessionMarkdownFile = "session.md"
SessionHTMLFile = "session.html"
// SessionExportSourceLimit is the native session read cap; it is the one
// opencode.MaxSessionExport value, not a second copy.
SessionExportSourceLimit = opencode.MaxSessionExport
SessionExportFileLimit = 2 << 20
SessionExportTimeout = 10 * time.Second
)
// SessionExportRequest names the stage session to export and the evidence the
// rendered files carry. Directory is the session's workspace (the directory the
// export CLI runs in); ArtifactsDir is the step's artifacts directory.
type SessionExportRequest struct {
SessionID string
Backend string
Directory string
ArtifactsDir string
RunID int64
Sequence int
Stage string
Provider string
Model string
}
// SessionExportResult is the outcome of one session export. Markdown/HTML are
// the written file names, their byte sizes, the decoded message count, the
// source, whether either file or the source was truncated and a sanitized
// diagnostic (for example a skipped overwrite).
type SessionExportResult struct {
Markdown string
HTML string
MarkdownBytes int64
HTMLBytes int64
Messages int
Source string
Truncated bool
Diagnostic string
}
const (
// sessionExportSource is the recorded source of a native-export readback.
sessionExportSource = "native_export"
// markdownTruncationBanner and htmlTruncationBanner are the visible labels a
// truncated export carries near its start and end so it is never mistaken for
// the whole session.
markdownTruncationBanner = "\n> **TRUNCATED**: this exported session is not the whole session; it was cut at the export size cap.\n"
htmlTruncationBanner = "<p style=\"padding:0.5rem;border:1px solid #b00;color:#900\"><strong>TRUNCATED</strong>: this exported session is not the whole session; it was cut at the export size cap.</p>\n"
)
// ExportSession reads the stage's session read-only through the native export
// path, renders it to bounded markdown and html and writes both files
// atomically into the step's artifacts directory, refusing to overwrite an
// existing file. It returns a sanitized error and writes nothing when the read
// fails; it never mutates, resumes, interrupts or deletes the session.
func ExportSession(ctx context.Context, request SessionExportRequest) (SessionExportResult, error) {
if !opencode.ValidSessionID(request.SessionID) {
return SessionExportResult{}, fmt.Errorf("session export: invalid session ID")
}
if request.ArtifactsDir == "" {
return SessionExportResult{}, fmt.Errorf("session export: no artifacts directory")
}
session, err := opencode.ExportSession(ctx, opencode.Executable(), request.Directory, request.Backend, request.SessionID)
if err != nil {
return SessionExportResult{}, fmt.Errorf("session export: %s", RedactEvidence(err.Error()))
}
markdown, markdownTruncated := renderSessionMarkdown(session, request)
htmlDoc, htmlTruncated := renderSessionHTML(session, request)
result := SessionExportResult{
Markdown: SessionMarkdownFile,
HTML: SessionHTMLFile,
Messages: len(session.Messages),
Source: sessionExportSource,
Truncated: session.Truncated || markdownTruncated || htmlTruncated,
Diagnostic: "",
}
written, diagnostic, err := writeSessionPair(request.ArtifactsDir, []sessionFile{
{name: SessionMarkdownFile, data: []byte(markdown)},
{name: SessionHTMLFile, data: []byte(htmlDoc)},
})
if err != nil {
return SessionExportResult{}, fmt.Errorf("session export: %s", RedactEvidence(err.Error()))
}
if written[0] {
result.MarkdownBytes = int64(len(markdown))
}
if written[1] {
result.HTMLBytes = int64(len(htmlDoc))
}
result.Diagnostic = diagnostic
return result, nil
}
// sessionFile is one rendered file to write into the artifacts directory.
type sessionFile struct {
name string
data []byte
}
// writeSessionPair stages every rendered file to a temporary file, then renames
// each into place, so a failure before the renames leaves no partial session.md
// or session.html behind. An existing target is never overwritten: its file is
// skipped and the reason is returned as a diagnostic.
func writeSessionPair(dir string, files []sessionFile) ([]bool, string, error) {
written := make([]bool, len(files))
temps := make([]string, len(files))
cleanup := func() {
for _, tmp := range temps {
if tmp != "" {
_ = os.Remove(tmp)
}
}
}
var skipped []string
for i, file := range files {
target := filepath.Join(dir, file.name)
if _, err := os.Lstat(target); err == nil {
skipped = append(skipped, file.name)
continue
} else if !os.IsNotExist(err) {
cleanup()
return written, "", err
}
tmp, err := os.CreateTemp(dir, "."+file.name+".tmp-*")
if err != nil {
cleanup()
return written, "", err
}
temps[i] = tmp.Name()
if _, err := tmp.Write(file.data); err != nil {
tmp.Close()
cleanup()
return written, "", err
}
if err := tmp.Close(); err != nil {
cleanup()
return written, "", err
}
}
for i, file := range files {
if temps[i] == "" {
continue
}
if err := os.Rename(temps[i], filepath.Join(dir, file.name)); err != nil {
cleanup()
return written, "", err
}
written[i] = true
}
diagnostic := ""
if len(skipped) > 0 {
diagnostic = "existing " + strings.Join(skipped, ", ") + " was not overwritten"
}
return written, diagnostic, nil
}
// sessionMeta is one metadata row the rendered files carry.
type sessionMeta struct {
label string
value string
}
// sessionMetadata is the run/step/session identity both renderers show, so a
// file is self-describing without the run record.
func sessionMetadata(session opencode.ExportedSession, request SessionExportRequest) []sessionMeta {
meta := []sessionMeta{
{"run", strconv.FormatInt(request.RunID, 10)},
{"step", strconv.Itoa(request.Sequence)},
{"stage", request.Stage},
{"session", session.ID},
{"backend", session.Backend},
{"messages", strconv.Itoa(len(session.Messages))},
{"source", sessionExportSource},
{"truncated", strconv.FormatBool(session.Truncated)},
{"exported_at", time.Now().UTC().Format(time.RFC3339)},
}
if request.Provider != "" {
meta = append(meta, sessionMeta{"provider", request.Provider})
}
if request.Model != "" {
meta = append(meta, sessionMeta{"model", request.Model})
}
return meta
}
// renderSessionMarkdown renders the session as bounded markdown. The second
// result reports whether the rendered file itself was cut at the cap.
func renderSessionMarkdown(session opencode.ExportedSession, request SessionExportRequest) (string, bool) {
var header bytes.Buffer
header.WriteString("# Stage session export\n\n")
for _, meta := range sessionMetadata(session, request) {
fmt.Fprintf(&header, "- %s: %s\n", meta.label, meta.value)
}
header.WriteString("\n")
var body bytes.Buffer
if len(session.Messages) == 0 {
body.WriteString("_No messages were recorded for this session._\n\n")
}
for i, message := range session.Messages {
renderMarkdownMessage(&body, i+1, message)
}
return assembleSessionFile(header.String(), body.String(), session.Truncated, markdownTruncationBanner, markdownTruncationBanner)
}
// renderMarkdownMessage renders one turn with its role and parts.
func renderMarkdownMessage(out *bytes.Buffer, index int, message opencode.ExportedMessage) {
role := message.Role
if role == "" {
role = "unknown"
}
fmt.Fprintf(out, "## %d. %s\n\n", index, role)
var details bytes.Buffer
if message.ID != "" {
fmt.Fprintf(&details, "- id: %s\n", message.ID)
}
if message.Model != "" {
fmt.Fprintf(&details, "- model: %s\n", message.Model)
}
if message.Agent != "" {
fmt.Fprintf(&details, "- agent: %s\n", message.Agent)
}
if message.CreatedAt != 0 {
fmt.Fprintf(&details, "- created_at: %d\n", message.CreatedAt)
}
if details.Len() > 0 {
out.WriteString(details.String())
out.WriteString("\n")
}
for _, part := range message.Parts {
renderMarkdownPart(out, part)
}
}
// renderMarkdownPart renders one content element. Unknown types are rendered as
// their raw JSON rather than dropped.
func renderMarkdownPart(out *bytes.Buffer, part opencode.ExportedPart) {
switch part.Type {
case protocol.ChatPartText:
out.WriteString(part.Text)
out.WriteString("\n\n")
case protocol.ChatPartReasoning:
fmt.Fprintf(out, "_reasoning_\n\n%s\n\n", part.Text)
case protocol.ChatPartTool:
renderMarkdownTool(out, part)
default:
label := part.Type
if label == "" {
label = "unknown"
}
fmt.Fprintf(out, "### %s\n\n", label)
raw := part.Raw
if len(raw) == 0 {
raw = []byte("{}")
}
fence := dynamicFence(string(raw))
fmt.Fprintf(out, "%sjson\n%s\n%s\n\n", fence, strings.TrimSpace(string(raw)), fence)
}
}
// renderMarkdownTool renders a tool call with its name, status, input, result
// and error.
func renderMarkdownTool(out *bytes.Buffer, part opencode.ExportedPart) {
name := part.Name
if name == "" {
name = part.ID
}
status := ""
if part.State != nil {
status = part.State.Status
}
fmt.Fprintf(out, "### tool: %s (%s)\n\n", name, status)
if part.State == nil {
return
}
if len(part.State.Input) > 0 {
input := string(part.State.Input)
fence := dynamicFence(input)
fmt.Fprintf(out, "input:\n\n%sjson\n%s\n%s\n\n", fence, strings.TrimSpace(input), fence)
}
for _, content := range part.State.Content {
if content.Text != "" {
out.WriteString(content.Text)
out.WriteString("\n\n")
} else if content.URI != "" {
fmt.Fprintf(out, "- %s (%s)\n", content.URI, content.Mime)
}
}
if part.State.Error != nil {
fmt.Fprintf(out, "error: %s\n\n", part.State.Error.Message)
}
}
// renderSessionHTML renders the session as bounded html, escaping every session
// text value. The second result reports whether the rendered file was cut.
func renderSessionHTML(session opencode.ExportedSession, request SessionExportRequest) (string, bool) {
var header bytes.Buffer
header.WriteString("<!doctype html>\n<html lang=\"en\"><head><meta charset=\"utf-8\">")
header.WriteString("<title>Stage session export</title>")
header.WriteString("<style>body{font-family:system-ui,sans-serif;margin:1rem}pre{overflow:auto;background:#f6f6f6;padding:0.5rem}dl{display:grid;grid-template-columns:max-content 1fr;gap:0 1rem}</style>")
header.WriteString("</head><body>\n<h1>Stage session export</h1>\n<dl>\n")
for _, meta := range sessionMetadata(session, request) {
fmt.Fprintf(&header, "<dt>%s</dt><dd>%s</dd>\n", html.EscapeString(meta.label), html.EscapeString(meta.value))
}
header.WriteString("</dl>\n")
var body bytes.Buffer
if len(session.Messages) == 0 {
body.WriteString("<p><em>No messages were recorded for this session.</em></p>\n")
}
for i, message := range session.Messages {
renderHTMLMessage(&body, i+1, message)
}
body.WriteString("</body></html>\n")
trailing := htmlTruncationBanner + "</body></html>\n"
return assembleSessionFile(header.String(), body.String(), session.Truncated, htmlTruncationBanner, trailing)
}
// renderHTMLMessage renders one turn with its role and parts.
func renderHTMLMessage(out *bytes.Buffer, index int, message opencode.ExportedMessage) {
role := message.Role
if role == "" {
role = "unknown"
}
fmt.Fprintf(out, "<h2>%d. %s</h2>\n", index, html.EscapeString(role))
fmt.Fprintf(out, "<p class=\"meta\">id: %s | model: %s | agent: %s | created_at: %d</p>\n",
html.EscapeString(message.ID), html.EscapeString(message.Model), html.EscapeString(message.Agent), message.CreatedAt)
for _, part := range message.Parts {
renderHTMLPart(out, part)
}
}
// renderHTMLPart renders one content element, escaping all session text.
func renderHTMLPart(out *bytes.Buffer, part opencode.ExportedPart) {
switch part.Type {
case protocol.ChatPartText:
fmt.Fprintf(out, "<pre class=\"text\">%s</pre>\n", html.EscapeString(part.Text))
case protocol.ChatPartReasoning:
fmt.Fprintf(out, "<details><summary>reasoning</summary><pre>%s</pre></details>\n", html.EscapeString(part.Text))
case protocol.ChatPartTool:
renderHTMLTool(out, part)
default:
label := part.Type
if label == "" {
label = "unknown"
}
raw := part.Raw
if len(raw) == 0 {
raw = []byte("{}")
}
fmt.Fprintf(out, "<h3>%s</h3>\n<pre>%s</pre>\n", html.EscapeString(label), html.EscapeString(strings.TrimSpace(string(raw))))
}
}
// renderHTMLTool renders a tool call with its name, status, input, result and
// error, escaping every value.
func renderHTMLTool(out *bytes.Buffer, part opencode.ExportedPart) {
name := part.Name
if name == "" {
name = part.ID
}
status := ""
if part.State != nil {
status = part.State.Status
}
fmt.Fprintf(out, "<h3>tool: %s (%s)</h3>\n", html.EscapeString(name), html.EscapeString(status))
if part.State == nil {
return
}
if len(part.State.Input) > 0 {
fmt.Fprintf(out, "<pre class=\"input\">%s</pre>\n", html.EscapeString(strings.TrimSpace(string(part.State.Input))))
}
for _, content := range part.State.Content {
if content.Text != "" {
fmt.Fprintf(out, "<pre class=\"output\">%s</pre>\n", html.EscapeString(content.Text))
} else if content.URI != "" {
fmt.Fprintf(out, "<p>%s (%s)</p>\n", html.EscapeString(content.URI), html.EscapeString(content.Mime))
}
}
if part.State.Error != nil {
fmt.Fprintf(out, "<p class=\"error\">error: %s</p>\n", html.EscapeString(part.State.Error.Message))
}
}
// assembleSessionFile joins the metadata header and the rendered body, adding
// the visible truncation banners near the start and the end when the source was
// already truncated or when the rendered output itself had to be cut, and never
// returning more than SessionExportFileLimit bytes. The second result reports
// whether the rendered output was cut.
func assembleSessionFile(header, body string, sourceTruncated bool, leading, trailing string) (string, bool) {
limit := SessionExportFileLimit
rendered := false
truncated := sourceTruncated
if len(header)+len(body)+len(leading)+len(trailing) > limit {
rendered = true
truncated = true
room := limit - len(header) - len(leading) - len(trailing)
if room < 0 {
room = 0
}
if len(body) > room {
body, _ = truncateRunes(body, room)
}
}
var out strings.Builder
out.Grow(min(limit, len(header)+len(body)+2*len(leading)))
out.WriteString(header)
if truncated {
out.WriteString(leading)
}
out.WriteString(body)
if truncated {
out.WriteString(trailing)
}
result := out.String()
if len(result) > limit {
result, _ = truncateRunes(result, limit)
}
return result, rendered
}
// dynamicFence returns a run of at least three backticks longer than any run in
// text, so markdown content that itself contains a fence cannot break out.
func dynamicFence(text string) string {
fence := "```"
for strings.Contains(text, fence) {
fence += "`"
}
return fence
}
+206
View File
@@ -0,0 +1,206 @@
package stage
import (
"context"
"os"
"path/filepath"
"strings"
"testing"
"git.a-wan.net/alan/pipelines/internal/opencode"
)
// sessionCLI writes a fake `opencode` CLI that answers the session export
// invocation (v1 `export <id>` or v2 `session export <id>`) with body and points
// PIPELINES_OPENCODE at it, so ExportSession runs without a service.
func sessionCLI(t *testing.T, id, body string) {
t.Helper()
path := filepath.Join(t.TempDir(), "opencode")
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"
if err := os.WriteFile(path, []byte(script), 0700); err != nil {
t.Fatal(err)
}
t.Setenv("PIPELINES_OPENCODE", path)
}
func sessionBody() string {
return `{"info":{"id":"ses_ok"},"messages":[` +
`{"info":{"id":"m1","role":"user"},"text":"please run"},` +
`{"info":{"id":"m2","role":"assistant","modelID":"gpt"},"parts":[` +
`{"type":"text","text":"hello <b>&\" world"},` +
`{"type":"reasoning","text":"thinking hard"},` +
`{"type":"tool","name":"read","state":{"status":"completed","input":{"path":"a.go"},"content":[{"type":"text","text":"tool output"}]}},` +
`{"type":"file","uri":"file:///tmp/x"}]}]}`
}
func sessionRequest(dir string) SessionExportRequest {
return SessionExportRequest{
SessionID: "ses_ok", Backend: "v2", Directory: dir, ArtifactsDir: dir,
RunID: 7, Sequence: 2, Stage: "implementer", Provider: "prov", Model: "gpt",
}
}
func TestExportSessionWritesBothFilesWithRealContent(t *testing.T) {
dir := t.TempDir()
sessionCLI(t, "ses_ok", sessionBody())
result, err := ExportSession(context.Background(), sessionRequest(dir))
if err != nil {
t.Fatal(err)
}
if result.Markdown != "session.md" || result.HTML != "session.html" {
t.Fatalf("file names wrong: %+v", result)
}
if result.Messages != 2 || result.Source != "native_export" || result.Truncated {
t.Fatalf("evidence wrong: %+v", result)
}
markdown, err := os.ReadFile(filepath.Join(dir, SessionMarkdownFile))
if err != nil {
t.Fatal(err)
}
htmlDoc, err := os.ReadFile(filepath.Join(dir, SessionHTMLFile))
if err != nil {
t.Fatal(err)
}
if result.MarkdownBytes != int64(len(markdown)) || result.HTMLBytes != int64(len(htmlDoc)) {
t.Fatalf("sizes wrong: %+v", result)
}
for _, want := range []string{"hello <b>&\" world", "thinking hard", "tool: read (completed)", "tool output", `{"path":"a.go"}`, "please run"} {
if !strings.Contains(string(markdown), want) {
t.Fatalf("markdown missing %q", want)
}
}
if !strings.Contains(string(markdown), "file:///tmp/x") {
t.Fatal("markdown dropped the unknown 'file' part")
}
// HTML must escape session text and still carry the tool detail.
if strings.Contains(string(htmlDoc), "<b>") {
t.Fatal("html rendered unescaped session text")
}
for _, want := range []string{"&lt;b&gt;", "&amp;", "tool: read (completed)", "tool output"} {
if !strings.Contains(string(htmlDoc), want) {
t.Fatalf("html missing %q", want)
}
}
// No temporary file may survive a successful write.
temps, _ := filepath.Glob(filepath.Join(dir, ".*tmp*"))
if len(temps) != 0 {
t.Fatalf("temporary files left behind: %v", temps)
}
}
func TestExportSessionRenderedTruncationBannerInBothFiles(t *testing.T) {
// A source under the read cap but whose rendering exceeds the file cap.
huge := strings.Repeat("line of text\n", SessionExportFileLimit/7)
session := opencode.ExportedSession{
ID: "ses_ok",
Backend: "v2",
Messages: []opencode.ExportedMessage{{
Role: "assistant",
Parts: []opencode.ExportedPart{{Type: "text", Text: huge}},
}},
}
markdown, mdTruncated := renderSessionMarkdown(session, sessionRequest(t.TempDir()))
htmlDoc, htmlTruncated := renderSessionHTML(session, sessionRequest(t.TempDir()))
if !mdTruncated || !htmlTruncated {
t.Fatalf("rendered truncation not reported: md=%v html=%v", mdTruncated, htmlTruncated)
}
for name, content := range map[string]string{"markdown": markdown, "html": htmlDoc} {
if len(content) > SessionExportFileLimit {
t.Fatalf("%s exceeds cap: %d", name, len(content))
}
if strings.Count(content, "TRUNCATED") < 2 {
t.Fatalf("%s lacks a leading and trailing truncation banner", name)
}
}
}
func TestExportSessionSourceTruncationIsLabelledNotWhole(t *testing.T) {
session := opencode.ExportedSession{
ID: "ses_ok",
Backend: "v2",
Truncated: true,
Messages: []opencode.ExportedMessage{{Role: "assistant", Parts: []opencode.ExportedPart{{Type: "text", Text: "partial"}}}},
}
markdown, _ := renderSessionMarkdown(session, sessionRequest(t.TempDir()))
if strings.Count(markdown, "TRUNCATED") < 2 {
t.Fatalf("source truncation must be labelled at both ends:\n%s", markdown)
}
if !strings.Contains(markdown, "truncated: true") {
t.Fatal("metadata must record truncation")
}
}
func TestExportSessionEmptySessionIsHonest(t *testing.T) {
session := opencode.ExportedSession{ID: "ses_ok", Backend: "v2"}
markdown, _ := renderSessionMarkdown(session, sessionRequest(t.TempDir()))
if !strings.Contains(markdown, "messages: 0") || !strings.Contains(markdown, "No messages were recorded") {
t.Fatalf("empty session must be honest, not fabricated:\n%s", markdown)
}
}
func TestExportSessionRefusesOverwrite(t *testing.T) {
dir := t.TempDir()
sessionCLI(t, "ses_ok", sessionBody())
existing := filepath.Join(dir, SessionMarkdownFile)
if err := os.WriteFile(existing, []byte("keep me"), 0600); err != nil {
t.Fatal(err)
}
result, err := ExportSession(context.Background(), sessionRequest(dir))
if err != nil {
t.Fatal(err)
}
kept, err := os.ReadFile(existing)
if err != nil || string(kept) != "keep me" {
t.Fatalf("existing session.md was overwritten: %q %v", kept, err)
}
if result.MarkdownBytes != 0 || !strings.Contains(result.Diagnostic, "not overwritten") {
t.Fatalf("skip reason not recorded: %+v", result)
}
if _, err := os.Stat(filepath.Join(dir, SessionHTMLFile)); err != nil {
t.Fatalf("html should still be written: %v", err)
}
}
func TestExportSessionFailureWritesNoFiles(t *testing.T) {
dir := t.TempDir()
t.Setenv("PIPELINES_OPENCODE", filepath.Join(t.TempDir(), "absent-opencode"))
_, err := ExportSession(context.Background(), sessionRequest(dir))
if err == nil {
t.Fatal("export failure must return an error")
}
entries, err := os.ReadDir(dir)
if err != nil {
t.Fatal(err)
}
if len(entries) != 0 {
t.Fatalf("failure wrote files: %v", entries)
}
}
func TestExportSessionRejectsInvalidIDAndMissingDirectory(t *testing.T) {
sessionCLI(t, "ses_ok", sessionBody())
bad := sessionRequest(t.TempDir())
bad.SessionID = "not-a-session"
if _, err := ExportSession(context.Background(), bad); err == nil {
t.Fatal("invalid session id accepted")
}
missing := sessionRequest(t.TempDir())
missing.ArtifactsDir = ""
if _, err := ExportSession(context.Background(), missing); err == nil {
t.Fatal("missing artifacts directory accepted")
}
}
// TestAssembleSessionFileNeverExceedsLimit confirms the final guard bounds even
// a pathological header.
func TestAssembleSessionFileNeverExceedsLimit(t *testing.T) {
header := strings.Repeat("h", SessionExportFileLimit+10)
body := strings.Repeat("b", 100)
got, _ := assembleSessionFile(header, body, false, markdownTruncationBanner, markdownTruncationBanner)
if len(got) > SessionExportFileLimit {
t.Fatalf("assembled file exceeds cap: %d", len(got))
}
}