Files
pipelines/docs/stage-artifacts.md
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

5.2 KiB

Stage artifacts

A stage that produces images, screenshots, reports or logs - typically written into an ignored or untracked directory - would otherwise leave nothing retrievable per step. Every agent visit therefore gets its own artifacts directory, and the files it contains are recorded on the step and served over HTTP.

Where they live

The server creates <artifacts root>/<run>/<step>/ before executing an agent visit. The artifacts root defaults to the directory holding the database (<data directory>/artifacts) and can be pointed elsewhere with the server's ArtifactsRoot option. Only model stages get a directory.

The directory is passed to the stage:

  • as the PIPELINES_ARTIFACTS_DIR environment variable in a locally spawned Pi process, and exported to the OpenCode CLI where the runtime controls it;
  • in the agent prompt, next to Run directory:, for every agent harness. Because OpenCode V2 tools execute inside the shared serve process, that prompt line is the reliable carrier there.

The prompt instruction is deliberately general: save any artifacts you produce - images, screenshots, reports, logs - into the directory; they are attached to the stage. There are no technology, language or file-type rules.

What is recorded

After the stage finishes and before the step is stored, the server makes one bounded inventory of the directory and records, per file, its name, size_bytes, content_type (from the extension, with a content sniff of at most the first 512 bytes as a fallback) and a server-relative url (/artifacts/<run>/<step>/<name>). The same fields appear under each step's artifacts in pipelines inspect RUN_ID --json and in the TUI.

  • Limits: 200 files per step, 8 MiB per file and 64 MiB total. Over-cap files are skipped and the skipped/truncated counts are recorded with the step.
  • Symlinks in any component and non-regular files are excluded, and the walk is bounded by the file cap so a large directory is never fully enumerated.
  • Artifacts are evidence, not a gate. A missing, unreadable, symlinked, oversized or empty directory records nothing and never fails the run or changes its outcome. The database retains the recorded list, not file copies.

Fetching bytes

GET /artifacts/<run>/<step>/<name> on the server that serves /healthz and /connect returns the file. Only files inside that run's and step's artifact root are reachable: path traversal, absolute paths, symlink escapes and unknown runs/steps are refused. Responses carry the correct Content-Type and Content-Length; HEAD returns headers without a body; and Range requests 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. pipelines retention report/apply (see CLI and agent authoring) is the only thing that removes them, and it does so only for a run the operator explicitly selected for removal. Removing a run removes its whole artifact directory; protected and retained runs keep theirs, and their recorded artifact URLs keep serving. A symlink at <root>/<run> is removed as a link without touching its target, and a regular file at that path is refused rather than deleted. Nothing removes artifacts automatically.