Files
pipelines/docs/stage-artifacts.md
T
alan 14175eba70 retention: explicit run-history and artifact retention
Add `pipelines retention report` (strictly read-only) and
`pipelines retention apply` (explicit, approval-gated removal) with an age
and/or count policy, protected-run rules, atomic single-transaction removal
and honest database space reclaim. Nothing prunes automatically.
2026-10-17 15:45:46 +01:00

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

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.