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