Files
pipelines/docs/stage-artifacts.md
T
alan 0f5a188c6a Record and serve per-stage artifacts
Every agent stage now writes into a per-run/step artifacts directory under
the data dir (<data>/artifacts/<run>/<step>), passed to Pi as
PIPELINES_ARTIFACTS_DIR, exposed on the OpenCode client env seam, and stated
in the agent prompt boilerplate so agents save images, screenshots, reports
and logs there.

After each step the server scans that directory with a bounded, symlink- and
traversal-safe inventory (os.OpenRoot + Lstat + O_NOFOLLOW) recording name,
size_bytes, content type (extension then 512-byte sniff fallback) and URL,
enforcing max files, per-file bytes and total bytes while counting skipped
and truncated entries. A missing, unreadable or oversized directory yields
only a best-effort diagnostic and never changes the step outcome.

The list is carried on protocol.RunStep as Artifacts []StageArtifact plus
skipped/truncated counters (omitempty, backwards compatible), persisted in a
new step_artifacts table keyed (run_id, sequence) alongside the
notifications/file-changes tables and loaded by GetRun.

GET /artifacts/{run}/{step}/{name} on the existing handler serves the bytes
with http.ServeContent, so Content-Type, Content-Length, HEAD and Range
(206/416) come from the stdlib; unknown runs/steps, absolute paths,
traversal, symlink escapes and non-regular files are refused.

The TUI lists each selected step's artifacts (name + human size) in the
retained-evidence section and adds an artifacts summary in the style of the
file-changes summary. Adds docs/stage-artifacts.md linked from README and an
artifacts subsection to the packaged operations skill reference.

Tests cover the scan records and caps, missing/oversized directories,
HTTP HEAD/Range/traversal/symlink/unknown refusals and protocol round-trips.
2026-10-15 17:51:18 +01:00

2.8 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.