Files
pipelines/internal/server/session_export_test.go
T
alan 58c6b9b7c6 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.
2026-10-17 19:40:43 +01:00

223 lines
8.3 KiB
Go

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)
}
}
})
}
}