22801a9b06
Six computed Flutter runs stopped at the export handoff gate because the rendered session.html cap was 2 MiB while their complete sessions (well inside the 8 MiB source read bound) rendered between 2.25 and 4.28 MiB once html escaping and the readable projection duplicated native text. Raise SessionExportFileLimit to 8 MiB, the server's existing per-artifact file bound, so a complete export is still listed and served. Normal export verification, versioned repair and the handoff gate keep using the single shared constant. The source read bound is unchanged, and an over-cap render is still visibly truncated and recorded partial. Add focused regressions for a complete export above the old cap, an over-new-cap file rejected as partial, repair above the old cap leaving original evidence untouched, the gate accepting the larger repair, and the constant staying inside the artifact file bound. Update the artifact, handoff-gate and operations docs and record the diagnosis in docs/notes/session-export-render-cap.md.
464 lines
31 KiB
Markdown
464 lines
31 KiB
Markdown
# System, storage and run evidence
|
|
|
|
Pipelines turns a reusable process into sequential stages with explicit handoffs,
|
|
outcome routing and retained evidence. A Go CLI/TUI connects to an execution server;
|
|
the server owns execution and SQLite history, OpenCode owns model/tool sessions,
|
|
and optional ntfy delivery supplies notifications. It is technology-neutral, not a
|
|
parallel/distributed task engine or a guarantee that model reports are correct.
|
|
|
|
## Lifecycle and location
|
|
|
|
- Drafts are editable Markdown plus JSON metadata. Publishing validates and creates
|
|
immutable versions; drafts remain retained. Keep context create-only/base-version
|
|
guards. Five optional generic starters are task, three-stage, review, research
|
|
and debug; a fresh database starts empty. Templates can be created directly with
|
|
an editable prefilled name or customized first. Editing a bundled repository
|
|
template changes no installed or published definition; only explicit authoring
|
|
then submission creates a new immutable version.
|
|
- A run pins its exact definition version, initial input and resolved directory.
|
|
The client invocation directory is the default, but files/tools execute on the
|
|
server. Docker needs that directory mounted at the same absolute path. A remote
|
|
client does not upload its repository or make host credentials available remotely.
|
|
- Host and Docker OpenCode credentials are separate. Preserve setup-selected model
|
|
inheritance; do not select a provider just because its ID appears in an example.
|
|
- Runtime caps are 30 stage steps and five visits to a stage. Runs in different
|
|
resolved workspaces execute concurrently; only a second run in a workspace an
|
|
active run is already changing is refused, naming the conflicting run and
|
|
advising you to wait or use a different workspace (for example another
|
|
checkout). Agent-session quiescence is scoped to the run: a run fails only when
|
|
one of its own sessions cannot be confirmed idle, so one run's active agent never
|
|
fails another's concurrent run. An active session left over by a restart with no
|
|
owning active run is an orphan and still refuses new work until interrupted.
|
|
Reusing that active run's request key reattaches idempotently.
|
|
`type=human` decision stages exist and pause the run (see `references/format.md`);
|
|
there are no parallel branches. Optional worktrees, full backup/restore,
|
|
automatic database sync and independent verifier stage types are future ideas,
|
|
not existing capabilities. Do not invent them in definitions.
|
|
- Services are native or Docker-based. With an existing Docker installation do not
|
|
start a competing native server. Server APIs are unauthenticated: trusted networks
|
|
only; never recommend public exposure. Tool scope is not a universal OS sandbox.
|
|
- Docker setup resolves the current supported OpenCode V2 release from the single
|
|
documented complete `GET .../git/matching-refs/tags/v2` response (a bounded
|
|
complete array with no pagination parameters; never the moving `latest` tag or
|
|
the registry's insertion order) and the current Pi release from npm, resolves the
|
|
selected tag's immutable GHCR `sha256` digest, builds `FROM` that digest, and
|
|
verifies the built image reports exactly those executable versions plus a
|
|
Node-compatible Pi engine.
|
|
It fails closed, keeping the last verified Dockerfile fallback pins, when discovery,
|
|
digest resolution, completeness, build or compatibility cannot be established: never
|
|
a hardcoded fallback, never a silent stale-pin substitution. A full install skips a
|
|
rebuild only when the release receipt **and** the actual built image's release and
|
|
source identity labels already match; a dirty source always invokes the Docker
|
|
build and relies on layer caching. A model/login-only reconfiguration compares only
|
|
the verified release image identity, so a changed source alone does not rebuild.
|
|
`./install --opencode|--pi` reconfigures inside the existing container and
|
|
refuses an image that does not match; it does not rebuild or restart services (an
|
|
explicit ordinary `./install` does when the user asks).
|
|
|
|
## Where data lives
|
|
|
|
SQLite retains pipelines/immutable versions, runs, recorded stage visits,
|
|
inputs/outputs, status/errors, audit transcripts, session ownership/references,
|
|
reported per-stage model usage (tokens/cost), retry links, schedules/state,
|
|
notification receipts and file changes. Not everything
|
|
is in that database: drafts/settings are client files; complete OpenCode sessions
|
|
and credentials use OpenCode storage; repository artifacts are files; ntfy has its
|
|
own storage. A pipeline ZIP is not a full backup of these components.
|
|
Never merge or sync live SQLite files using generic file synchronization. Do not
|
|
delete databases, sessions, volumes or credentials to repair a workflow.
|
|
|
|
## Inspect results first
|
|
|
|
Use the authoritative `CLI_PREFIX` from the prompt:
|
|
|
|
- `CLI_PREFIX runs --json`: run history (optional `--pipeline NAME` scope).
|
|
- `CLI_PREFIX search QUERY [--type KIND] [--limit N] --json`: one read-only query
|
|
across pipelines, versions, runs, steps, field text and artifacts. QUERY is free
|
|
text, a bare status word (`queued`/`running`/`succeeded`/`failed`/`canceled`/
|
|
`interrupted`) selecting those runs, or a lone date expression (`today`,
|
|
`yesterday`, `this week` — Monday 00:00 local — or `YYYY-MM-DD`) selecting the
|
|
runs created in that window; anything else stays free text. `--type` is the only
|
|
narrowing mechanism and takes one of `pipeline`, `version`, `run`, `step`,
|
|
`field`, `artifact`; an unknown kind is an error. Ranking is exact name (3) >
|
|
name substring (2) > body text (1), equal tiers by recency, and every hit
|
|
reports `score`, `matched_field` and `recency`. The cap defaults to 50 and clamps
|
|
to 200; every kind scans at most 2000 rows and field scanning stops at 2000
|
|
steps / 1 MiB and reports
|
|
`truncated`/`scanned_steps`/`scanned_bytes`/`cap`/`scan_bound_bytes`. Targets are
|
|
stable: `pipeline:<id>`, `pipeline:<id>:v<version>`, `run:<id>`,
|
|
`run:<id>:<sequence>`, `run:<id>:<sequence>:<field>`, or an artifact URL.
|
|
- `CLI_PREFIX runs --json`: run history (optional `--pipeline NAME` scope). Each run
|
|
carries a bounded, single-line `title` saying what it was for, set explicitly with
|
|
`CLI_PREFIX run ... --title "..."` or generated from its prompt by the shared
|
|
summariser on the configured default harness. It is never empty: when generation is
|
|
unavailable or times out the server derives the prompt's first line, and
|
|
`title_source` (`model`, `fallback`, or `explicit`) plus `title_model` record how it
|
|
was produced, so a diagnosis can tell them apart. Human `runs` and `inspect` show the
|
|
title beside the pipeline name and version, so two runs of one pipeline are
|
|
distinguishable; `CLI_PREFIX title RUN_ID "..."` renames a run after the fact
|
|
without changing its input or steps. The stored prompt is unchanged, and
|
|
listing/renaming never calls a model.
|
|
- `CLI_PREFIX inspect RUN_ID --json`: selected run, visits and retained evidence.
|
|
Each model step carries the usage its harness reported (`usage.tokens_total`,
|
|
`tokens_in`/`tokens_out` only when `split_known`, `cost_usd` only when
|
|
`cost_known`, plus the model the step actually ran with); the run carries the
|
|
totalled `usage` over those stages, so a mixed-model run shows what each stage
|
|
cost. An unreported cost or split is shown as unavailable, never as zero and
|
|
never inferred from output length or transcript text; a historical or
|
|
pre-upgrade run simply omits `usage`.
|
|
Exact stage outputs are authoritative; a transcript over the 32 KiB retained
|
|
bound is a valid, credential-redacted preview envelope (with preserved stage
|
|
limits, failure/format diagnostics and the retained session pointer), not the
|
|
complete tool history.
|
|
- `CLI_PREFIX decide RUN_ID [STAGE] --option KEY [--feedback TEXT] [--json]`: answer
|
|
a run that is `waiting` on a `type=human` stage. The status and the stage's
|
|
instructions/options are visible in `runs` and `inspect --json` (and the TUI
|
|
picker); the stage is inferred from the run's current stage unless named. The
|
|
choice and feedback are recorded as the step's evidence (its output and derived
|
|
verdict; the feedback is never an error diagnostic) and the run resumes along
|
|
`edges[KEY]`. An unknown option is
|
|
refused with the valid list; a stage that is not waiting is refused; a repeated
|
|
decision for an already-decided visit does not double-apply. The wait is persisted,
|
|
so `decide` still works after a server restart. `cancel` and `retry` keep working
|
|
while waiting and after a decision; a human stage is never killed by a stage
|
|
timeout or `max_visits` (the shared 30-step run budget still applies).
|
|
- `CLI_PREFIX run ... --json --wait --wait-timeout DURATION`: `--wait` polls until
|
|
terminal and `--wait-timeout` bounds only the client wait after admission,
|
|
independent of per-request `--timeout`. A reached wait limit leaves the admitted run
|
|
active; inspect it read-only with `inspect RUN_ID --json`, or keep waiting by
|
|
rerunning `--wait` and reusing the original `--request-key`. Never start a duplicate
|
|
run, and never expect an automatic replay or cancel of admitted work.
|
|
- `CLI_PREFIX show NAME --version N --json`: exact pinned definition, not whichever
|
|
version happens to be latest now.
|
|
- `CLI_PREFIX status --json`: connection details; candidate addresses are not proof
|
|
they are reachable from another device.
|
|
- `CLI_PREFIX ping --json`: `pong.build.version`, `build.commit` (full Git revision)
|
|
and `build.dirty` identify the compiled **server**, not the client or its runtime
|
|
checkout. A dirty build includes `-dirty`; `commit: "unknown"` or `dirty: null`
|
|
means metadata was unavailable. Older servers omit `build`. Never infer a deployed
|
|
fix from source/skill contents. Native Go builds use embedded VCS metadata;
|
|
Docker setup stamps build arguments. For an explicitly requested Docker rebuild,
|
|
`python3 scripts/build_metadata.py` resolves the current releases and stamps
|
|
`docker compose build` from the checkout with the immutable digest; it does not
|
|
restart/deploy. A plain `docker compose build` without that resolved digest cannot
|
|
build the image.
|
|
Plain `ping` also displays server identity; `CLI_PREFIX version --json` (alias
|
|
`--version`) identifies the client offline. Include both in sanitized bug reports.
|
|
Two dirty builds at the same commit can differ. Docker setup verifies its started
|
|
server identity against the build arguments before declaring setup complete.
|
|
|
|
Pipelines is a single-user first-version preview for supervised work, not a
|
|
multi-user service. Recommend a disposable repository for initial trials. Tool
|
|
permissions and same-path home mounts do not isolate valuable files. Never collect
|
|
raw credential/session databases or publish private inspect output as diagnostics.
|
|
In a source checkout, `python3 scripts/smoke-first-install.py` checks a disposable
|
|
source-built test binaries, draft/publication/transfer and restart persistence without
|
|
inference, notifications or deployment. It is not a live-provider or phone test.
|
|
That is a developer test fixture, not the native installer. End-user installation
|
|
runs natively through `./install` by default (`scripts/setup-native.py`, with
|
|
`--native` equivalent); the Docker server + ntfy installation is explicit with
|
|
`./install --docker`.
|
|
|
|
In the TUI, Home advertises `/` omni search and `:` commands. Home `/` opens one
|
|
popup over pipelines, versions, runs, steps/visits, artifact names and stage
|
|
input/output/evidence text; each row shows a short type badge and a text match
|
|
shows a bracketed snippet, and a bare status word or date selects runs. The same
|
|
query is available as `pipelines search QUERY [--type KIND]`, where `--type`
|
|
narrows the kind. Run Tab switches only
|
|
Details ↔ Graph. `n/p` select recorded visits, including repeated stages; `d`
|
|
focuses/toggles file changes, `A` opens the run's grouped artifacts view (name,
|
|
content type, size and URL per entry, `PgUp`/`PgDn` scroll so a trailing visit
|
|
that recorded none stays reachable, `Enter`/`o` to open the selected URL and
|
|
`y` to copy it), `a` selects the active/latest retained
|
|
configured-harness agent session's bounded, redacted tool evidence, `D`/`:debug`
|
|
opens fresh investigation, and `P` opens the pinned pipeline version. `:quit`
|
|
exits; `q` does not. Results are retained reports, not independently confirmed
|
|
achievements. Distinguish partial output from full success.
|
|
|
|
## Retained stage file changes
|
|
|
|
Each newly executed visit compares a bounded, read-only workspace snapshot just
|
|
before execution with one after execution/cleanup. SQLite retains unified patches
|
|
and metadata in `steps[].file_changes`; snapshots themselves are transient memory.
|
|
The stage's File changes section highlights added/removed lines and hunk headers.
|
|
|
|
- The baseline is stage-start content, **not HEAD/index**. Pre-existing edits and
|
|
earlier stages' changes are not attributed to this visit. Added/deleted/modified
|
|
files, modes and binary-change metadata are recorded; renames are delete/add.
|
|
- Git scope is tracked and nonignored untracked files within the run directory;
|
|
outside Git, regular workspace files. Symlinks/special files, Git internals,
|
|
node_modules and common environment/key/credential/database paths are excluded.
|
|
This is path-based protection, **not secret-content scanning**. Patches may still
|
|
contain sensitive text; never publish them without approval.
|
|
- Limits: 10,000 entries, 1 MiB/file, 32 MiB/snapshot, five-second snapshot context,
|
|
5,000 combined text lines, 64 KiB/patch, 128 KiB serialized file evidence/visit.
|
|
Missing/skipped/truncated captures must be described as partial/unavailable.
|
|
- Failed/canceled stages retain changes when execution returns; unconfirmed agent
|
|
cleanup is partial. Crashes may have no after-capture. Historical visits say
|
|
not recorded—**never infer no edits from absent evidence**.
|
|
- These are observed workspace changes, not exclusive authorship. Concurrent edits,
|
|
changes outside scope, ignored new files and changes reverted before capture can
|
|
be absent or mixed in. Capture failure does not change the declared run verdict.
|
|
|
|
Do not add model output fields, new stages or extra model calls merely to obtain
|
|
file diffs: current capture is server-owned. Do not promise full files/rollback.
|
|
|
|
## Retained stage artifacts
|
|
|
|
Every model visit gets a file-based turn under the data directory
|
|
(`<data>/artifacts/<run>/stages/<seq>-<stage>/`) with `input.md`, `memory.md`,
|
|
`output.md` and `private/`; `public/` is run-level and shared by every stage.
|
|
The root is configurable and defaults next to the database. The writable
|
|
`private/` and shared `public/` directories are stated in the agent prompt for
|
|
every harness, and `PIPELINES_ARTIFACTS_DIR` points at the turn directory for a
|
|
locally spawned Pi process. OpenCode V2 tools run inside the shared serve
|
|
process, so there the prompt, not the environment, is the reliable carrier.
|
|
Turn-local files belong in `private/`; reports, logs and screenshots for later
|
|
stages belong in `public/`. The server owns `input.md`, `memory.md` and
|
|
`output.md` and never asks the model to write them directly.
|
|
|
|
After the visit the server makes one bounded inventory of the turn and public
|
|
directories and records each file's name, size, content type (extension, sniff
|
|
fallback) and a relative url; these appear under each step's `artifacts` in
|
|
`inspect RUN_ID --json` and the TUI's `A` artifacts view, which groups them by
|
|
stage and visit, marks images and shows the recorded count,
|
|
capture-pending/not-recorded wording and partial-capture notes. Public entries
|
|
carry a `public/` prefix. `input.md`, `memory.md` and `output.md` are the primary
|
|
artifacts of every model visit.
|
|
`GET /artifacts/<run>/<step>/<name>` serves the bytes (correct Content-Type and
|
|
Content-Length, HEAD, and Range/206/416 via `http.ServeContent`), refusing
|
|
traversal, absolute paths, symlink escapes and unknown runs/steps. A pre-turn
|
|
`<run>/<step>/` path stays readable for runs recorded before the file protocol
|
|
landed.
|
|
|
|
- Limits: 200 files, 8 MiB/file, 64 MiB total per visit; over-cap files are
|
|
skipped and counted; symlinks and non-regular files are excluded.
|
|
- Artifacts are read-only evidence, not a gate: absent, unreadable, symlinked or
|
|
oversized directories record nothing and never change the run verdict. The
|
|
database keeps the recorded list, not file copies.
|
|
- Do not invent artifact files or claim a stage produced one without the recorded
|
|
evidence; the server observes the directory after the stage.
|
|
|
|
### Session export
|
|
|
|
- When an OpenCode-harness model stage finishes, the server exports its real
|
|
session read-only (v1 `opencode export <id>`, v2 `opencode session export <id>`)
|
|
and writes exactly one file, `session.html`, into the same turn artifacts
|
|
directory; it lists and serves like any other artifact.
|
|
- The `session.md` export is retired: nothing writes it any more and it is never
|
|
presented. A run recorded before the HTML-only change still lists `session.md`
|
|
among its stored artifacts (dated evidence kept on disk, not deleted); every
|
|
listing — app, TUI, web spike — hides it rather than showing it beside the html.
|
|
- The source read is capped at 8 MiB and the rendered file at 8 MiB, matching the
|
|
ordinary per-artifact file bound; a cut source or a cut rendered file carries a
|
|
visible truncation banner at both ends and `session_export.truncated: true`, and
|
|
a truncated export is never called whole.
|
|
- The step records `session_export` (`session_id`, `backend`, `source`, the html
|
|
file name, `html_bytes`, `messages`, `truncated`, `diagnostic`) in
|
|
`inspect RUN_ID --json`. A record written before the change still carried
|
|
`markdown` and `markdown_bytes`; readers ignore those fields.
|
|
- A failed export, or a Pi stage with no native export path, records a diagnostic
|
|
(Pi: `source: "unavailable"`) and never fails the run or changes the stage result.
|
|
An existing `session.html` is never overwritten.
|
|
|
|
### Operator-only retention
|
|
|
|
Run history and its artifacts are never pruned automatically. The operator-only
|
|
`pipelines retention report` (strictly read-only) and `pipelines retention apply`
|
|
(removal after explicit approval) are the only commands that remove them; no
|
|
server startup, scheduler, `list_runs`, `stats`, `runs` or `inspect` path calls
|
|
retention, and there is no background goroutine, timer or startup hook. A policy
|
|
selects by rolling UTC age (`--older-than`), newest-N count (`--keep`), or their
|
|
intersection. Runs that are queued/running, waiting on a person, running a cleanup
|
|
agent, or referenced by a retained run's retry provenance are protected and
|
|
reported with a reason; their artifacts are kept. Removing a run removes its
|
|
`<root>/<run>` artifact directory and reclaims database space with one `VACUUM`
|
|
and one WAL checkpoint, reporting measured bytes. Pipeline definitions and their
|
|
immutable versions are never touched. The commands are local, require an existing
|
|
`--db`, and need no running server.
|
|
|
|
## Brokered OpenCode chat
|
|
|
|
The protocol declares the brokered `chat_*` surface (`chat_sessions`,
|
|
`chat_create`, `chat_directories`, `chat_prompt`, `chat_messages`,
|
|
`chat_interrupt`, `chat_permission`, `chat_reply`). The server dispatches all of
|
|
them, and pushes `chat_event` frames derived from OpenCode's global SSE firehose
|
|
(`/event` on the native serve, `/api/event` on the V2 API), with retained
|
|
per-session/per-message state so a reconnecting client re-syncs instead of
|
|
replaying deltas.
|
|
|
|
At startup `cmd/pipelines-server` calls `opencode.OpenChat`, which detects the
|
|
installed backend and opens exactly one owned `opencode serve` endpoint for it:
|
|
the native wire for v1, the V2 API for the installed V2 CLI. Chat is enabled only
|
|
when that connection carries a URL-bearing, SSE-capable event endpoint; otherwise
|
|
chat stays disabled and every `chat_*` request is answered with a protocol error
|
|
naming the missing configuration rather than hanging. Stage generation still
|
|
reaches V2 through the `opencode api` CLI, so the owned serve process is chat's
|
|
single transport and starts no process for stages. The adapter skips firehose
|
|
events it does not surface before decoding their data, so an unrelated event
|
|
whose `delta` has a different shape (`session.instructions.updated` carries an
|
|
object) never fails the stream.
|
|
|
|
The operator can instead broker chat from their own OpenCode service with the
|
|
opt-in `-opencode-endpoint` flag or `PIPELINES_OPENCODE_ENDPOINT`, with precedence
|
|
flag > environment > the endpoint recorded on a previous run and the spawned
|
|
instance as the default. `opencode.OpenEndpoint` validates the reference once
|
|
(the established http(s)/host/no-credentials/no-query/no-path idiom), detects the
|
|
backend from the service's own `/api/info` (V2) or `/global/health` (native)
|
|
contract and requires a streamable `text/event-stream` event path; it returns a
|
|
connection with **no owned process** and never calls `startServe`. A malformed
|
|
reference, an unreachable host, a reachable non-OpenCode service or a
|
|
health-ok-but-no-SSE service each disable chat with an error naming the endpoint
|
|
and never fall back to the spawned instance. An authenticating endpoint accepts an
|
|
optional password only through the private file
|
|
`PIPELINES_OPENCODE_ENDPOINT_PASSWORD_FILE` (regular, 0600, single-owner), and
|
|
`PIPELINES_OPENCODE_ENDPOINT_USERNAME` overrides the detected default user. The
|
|
validated choice is recorded in the additive `server_settings` table so a restart
|
|
with no flag/environment reuses it; an unreachable recorded endpoint disables chat
|
|
with a clear message and no fallback. `pipelines service enable` preserves the
|
|
endpoint and the password-file reference in autostart.
|
|
|
|
`chat_sessions` lists the operator's own chat sessions, not the sessions pipeline
|
|
runs create. Operator sessions are recorded in the dedicated `operator_sessions`
|
|
table (`session_id` primary key, plus `directory`, `title`, `tag`, `created_at`,
|
|
`last_used_at`), separate from `run_steps`/`run_session_owners`, so an operator
|
|
chat is a first-class thing and a pipeline stage session — recorded as run
|
|
ownership, never in the operator registry — is never listed. The handler reads the
|
|
registry once (bounded to 128 rows, most-recently-used first), calls OpenCode's
|
|
session list once, and keeps only registry rows the endpoint still reports, so a
|
|
session with no recorded tag is never listed and a deleted upstream session does
|
|
not linger. It fills each session's `directory`, `tag` and `created_at`/
|
|
`updated_at` from the registry and marks `busy` when another client currently
|
|
holds the session (an in-server claim, released when the stream ends or the client
|
|
disconnects); a second client's `chat_prompt` for a held session is rejected
|
|
before any OpenCode call. It is fail-closed: with no registry configured it
|
|
returns an empty list, never the endpoint's whole session list. The OpenCode
|
|
session list is read unscoped by directory (the V2 `GET /api/session` otherwise
|
|
defaults to the caller's directory), because an operator session may live in any
|
|
directory.
|
|
|
|
`chat_create` creates one operator session and records it in the same registry
|
|
with the stored tag `operator` (the display label `Operator` is derived from it,
|
|
so there is no second tag vocabulary). It takes a `title` (default "New chat") and
|
|
a `directory` (default `~`): an omitted or empty value, `~`, and any `~/...` value
|
|
all resolve to `os.UserHomeDir`, never the server's working directory; a relative
|
|
path or a missing directory is rejected before any OpenCode call, and a session
|
|
created but not recordable is reported as an error naming its id. Create posts the
|
|
verified V2 shape `POST /api/session` `{"title":...,"location":{"directory":...}}`.
|
|
`chat_directories` returns the operator's home first, then the directories of
|
|
previous operator sessions most-recently-used first, deduplicated and bounded (8);
|
|
it is a dedicated request so the create dialog can load the choices without first
|
|
listing sessions and `chat_sessions` stays a pure, fail-closed session list. A
|
|
successful `chat_prompt` touches the session's `last_used_at` in one UPDATE, so it
|
|
moves to the front of the list; a non-operator session id touches no row.
|
|
|
|
`chat_adopt` records a session that already exists on the configured endpoint in
|
|
the same operator registry, using the endpoint's own directory and title
|
|
verbatim (never a guess, the server's working directory or the home directory).
|
|
It reads the endpoint once through the shared `Chat.Session` (which reuses
|
|
`Sessions`/`decodeChatSessions`), records through the existing
|
|
`RecordOperatorSession` with the `operator` tag, and echoes the adopted session
|
|
plus its registry row like `chat_create`, so `chat_sessions` lists it and
|
|
`chat_prompt` continues it. A nil payload, a blank or foreign-shaped id, a nil
|
|
broker or a nil registry is refused before any endpoint call; an id the endpoint
|
|
does not report is refused naming the id and records nothing; an endpoint record
|
|
with an empty directory is refused rather than substituting a directory. The CLI
|
|
equivalent is `pipelines chat-adopt <session-id>` (`--json` prints the full
|
|
response, otherwise a short `Adopted <id> · <directory>` line).
|
|
|
|
While a `chat_prompt` subscription is open the server also polls
|
|
`GET /api/permission/request` on a fixed small interval (first poll immediately) and
|
|
pushes one `chat_permission` frame per newly pending approval request, deduped by
|
|
request id so a repeated poll never re-pushes the same request. The app answers with
|
|
`chat_reply`, which the server forwards as
|
|
`POST /api/session/{id}/permission/{requestID}/reply` with
|
|
`{"decision":"once"|"always"|"reject"}`. A missing session/request id or an invalid
|
|
decision is rejected before any OpenCode call, and the poller stops when the stream
|
|
ends or the client disconnects.
|
|
|
|
The permission list and reply are implemented against the V2 HTTP API only: their
|
|
field names match the service's `Permission.Request`/`Permission.Reply` schemas
|
|
(verified against the installed service's `/openapi.json`). The native v1 serve
|
|
translation rejects them explicitly instead of guessing an endpoint, so on v1 the
|
|
permission poller stops quietly rather than reporting the documented limitation as
|
|
a per-prompt error.
|
|
|
|
### Verification evidence (2026-10-17)
|
|
|
|
Verified against the installed OpenCode 2.0.20 on 2026-10-17:
|
|
|
|
- `opencode --version` reports `2.0.20`; `opencode --help` advertises `api` and
|
|
`serve`. `GET /openapi.json` on an owned `opencode serve` lists `GET /api/event`
|
|
(SSE) and the session/prompt/interrupt/permission endpoints.
|
|
- A live turn streamed token-level `session.text.delta` and
|
|
`session.reasoning.delta` events (each with `assistantMessageID` and `ordinal`),
|
|
plus `session.step.*` and `session.usage.updated`; the V2 API server
|
|
authenticates the fixed `opencode` basic-auth user.
|
|
- The opt-in live end-to-end test (`PIPELINES_TEST_OPENCODE_CHAT_LIVE=1 go test
|
|
./internal/server -run TestChatLiveEndToEnd -v`) opened an owned V2 endpoint,
|
|
created an operator session through `chat_create` in a chosen directory, listed
|
|
exactly that session through `chat_sessions` (with its directory and tag
|
|
`operator`), recorded a genuine pipeline stage session in
|
|
`run_steps`/`run_session_owners` and showed it never appeared in the list, and
|
|
streamed a completed turn as `[step:started,text,step:streamed,step:ended]`
|
|
(first delta `"pong"`). The operator-session registry, the filter, directory
|
|
defaulting and the recents bound are also covered by the `pipeline`, `opencode`
|
|
and `server` unit tests, which run without the live gate.
|
|
- Not verified live: a genuine pending-approval round trip and any backend other
|
|
than the installed 2.0.20. The permission wire shapes are unit-tested over an
|
|
httptest fixture, not against a live pending request.
|
|
- Operator-supplied endpoint selection and `chat_adopt` (added 2026-10-17):
|
|
`opencode.OpenEndpoint` and the flag/env/recorded precedence, the URL-shape
|
|
validation failures (scheme, empty host, userinfo, query, fragment, non-empty
|
|
path), the unreachable/non-OpenCode/no-SSE/auth-mismatch failures, the
|
|
no-owned-process property (`conn.process == nil`) and the password-file rule
|
|
are unit-tested over httptest fixtures in `internal/opencode/endpoint_test.go`.
|
|
`chat_adopt` (endpoint directory/title recorded with the `operator` tag, echo,
|
|
missing id refused naming the id and recording nothing, nil payload/blank id/nil
|
|
broker/nil registry refused before any endpoint call, empty endpoint directory
|
|
refused) is unit-tested over the server fake broker in
|
|
`internal/server/chat_test.go`; the recorded-endpoint round-trip across a store
|
|
Close/Open is in `internal/pipeline/settings_test.go`; the protocol round-trip
|
|
and the CLI dispatch (`pipelines chat-adopt`) are covered in
|
|
`internal/protocol/chat_test.go` and `internal/cli/chat_adopt_test.go`. The
|
|
live scratch-server check against the operator's real endpoint (adopt, list,
|
|
prompt) was **not** run in this change; only the unit fixtures above were
|
|
executed.
|
|
|
|
Deployment state: not deployed. This is reviewed and committed locally only;
|
|
deploying it (and restarting the server) is the operator's step. Do not describe
|
|
brokered chat as already deployed.
|
|
|
|
## Debug and retry
|
|
|
|
Debug opens a new conversation with retained failure context, exact definition and
|
|
session evidence; it does not resume implementation or grant permission to edit.
|
|
Inspect first, identify evidence-supported causes, and say what remains unknown.
|
|
Server-side session evidence is the latest bounded, credential-redacted evidence
|
|
for up to the 3 most recent session-bearing steps; OpenCode V2 selects the latest
|
|
assistant message with the same bounded readback as the final result, so a small
|
|
final result is visible behind large prior tool content. Inspect the retained
|
|
session itself when a preview is bounded or omitted; never assume a complete tool
|
|
history from a preview.
|
|
Retry is allowed for a failed run after cleanup stops: a fresh run/session starts
|
|
at entry with the original input/directory/pinned version/edit scope. Previous
|
|
side effects remain and can happen again. Never describe retry or cancellation as
|
|
rollback, or resume/replay admitted tool work just to recover formatting.
|
|
|
|
Retained model-stage failures carry a fixed sanitized category. `FINAL RESULT
|
|
VALIDATION` names the exact duplicate-field/syntax detail and byte offset for a
|
|
strictly invalid final result; `HARNESS TRANSPORT` covers request, active-session
|
|
poll and final-readback failures. A validation failure never re-prompts the
|
|
admitted tool-using stage: completed edits and tool side effects are retained and
|
|
not undone, so a full retry repeats work. An explicit read-only stage is the one
|
|
exception: a malformed result there mutates nothing, so it may be re-emitted up
|
|
to `retries` with its `format_repairs` evidence retained, and a post-admission
|
|
deadline or transport failure may be retried. A failure to reach the harness
|
|
before any prompt or tool call is admitted (connecting, or creating the session)
|
|
replays nothing, so it is retried within `retries` for any stage, mutating or not.
|
|
A stage whose tools include
|
|
`edit`/`shell`, or that has no tools block (the legacy read/glob/grep/edit/shell
|
|
bundle), is never replayed. Neither category exposes provider/model bodies or
|
|
credentials. The isolated formatter's deadline is proportional to the stage
|
|
timeout and clamped so it never extends the stage's own deadline.
|