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