58c6b9b7c6
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.
81 lines
4.4 KiB
Markdown
81 lines
4.4 KiB
Markdown
# 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.
|