Files
pipelines/internal/author/skill/references/delivery.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

4.4 KiB

Publish artefacts, name them honestly, keep installs the operator's

A run's job ends at a reviewed, committed change and, when the operator must try it, a published build. Publishing to a phone, a device or a service is a delivery step with its own rules.

Run artifacts

  • Every agent visit gets a per-run/step artifacts directory under the data directory. The directory is passed to the stage as PIPELINES_ARTIFACTS_DIR and stated in the agent prompt next to Run directory:; the instruction is to save images, screenshots, reports and logs there (references/operations.md).
  • After the visit the server makes one bounded inventory and records each file's name, size, content type and URL; they appear under the step's artifacts in inspect RUN_ID --json and are served at GET /artifacts/<run>/<step>/<name>.
  • Artifacts are evidence, not a gate: an absent, unreadable, symlinked or oversized file records nothing and never changes the verdict. Never invent an artifact or claim a stage produced one — the server observes the directory after the stage.
  • An OpenCode-harness stage also gets its real session exported as session.md and session.html in the same directory: bounded (8 MiB source, 2 MiB per file), with a visible truncation banner and session_export.truncated when cut; the step's session_export records the files. Export failures and Pi (no native export path) record a diagnostic and never fail the run or change the stage result.

Publish a build to the LAN

  • When an item builds something the operator should try (an app, a binary, a report), have the run publish the built file into the current run's artifacts directory and report its LAN URL: http://<server-host>:<port>/artifacts/<run>/<step>/<name>.
  • Verify the URL serves the real file before reporting it; a printed path or an exit-0 publish is not proof. Fetch it and confirm the bytes are the artefact.
  • The phone or client reaches the server at its configured endpoint; never hardcode a server address into the project. A URL the operator's device cannot reach is not a delivery.

Name a WIP so it cannot be mistaken for verified

  • Give a not-yet-verified build a name that marks it: wip-<short-HEAD> (for example myapp-wip-1fece88.apk).
  • Reserve the plain, unmarked name for the verified build, so the operator and later runs can tell at a glance which artefact passed review and which did not.
  • Never overwrite or relabel a WIP as verified without the review that qualifies it.

Install and deploy boundaries

  • Installing onto the operator's physical device is the operator's job, not a run's. A run may install only on the emulator or device its lane owns (references/lanes.md).
  • Restarting, rebuilding or reconfiguring the Pipelines/OpenCode service is the operator's job. A run may not stop a server another run depends on.
  • A run may build and publish; it may not deploy a service, install to hardware the operator holds, or push or tag a shared branch.

Drafts, approvals and immutable history

  • Delivery still obeys the authoring rules (SKILL.md): drafts are retained, publication creates immutable versions, and submission, execution, retry, cancellation and deletion ask for explicit confirmation.
  • --yes approves only the specific action you named; it is not approval to publish, run or schedule. A run must not submit a pipeline or activate a schedule.

Example (this repository, not a rule)

This repository's Android client is delivered as a debug APK:

  • Build and publish the APK into the current run's artifacts directory as pipelines-debug-wip-<short-HEAD>.apk and report the LAN URL, for example http://10.0.0.249:8080/artifacts/<run>/1/pipelines-debug-wip-1fece88.apk. The plain name is reserved for the verified build.
  • Screenshots come from android/scripts/capture_png.sh -s <serial> <out.png> (and --check <file.png> to re-validate); it captures on the device, pulls and checks the PNG magic bytes, deleting a file that is not a real image. Never write adb ... screencap to a file through exec-out or a redirect.
  • The lane's emulator serial is fixed per lane (for example emulator-5554 for one lane, emulator-5556 for another); the operator's attached Pixel is never the runs' device.
  • This is the concrete instance of the general rules above; a different project substitutes its own build artefact, capture tool and device, and keeps the naming and boundary rules.