95362134aa
A stage's session was exported twice, as session.md and session.html, and both files were presented. It is now one html file; the markdown export is retired. - internal/stage/session_export.go: ExportSession renders and writes exactly one file, session.html, via writeSessionFile; renderSessionMarkdown and its helpers are gone; SessionExportResult carries HTML/HTMLBytes only. The source read, the 8 MiB source / 2 MiB rendered bounds, the truncation banner, the never-overwrite rule and the honest empty-session handling are unchanged. - internal/protocol/runs.go: SessionExport drops markdown/markdown_bytes (a record written before the change still decodes; unknown fields are ignored), and adds LegacySessionMarkdownArtifact with RunStep.PresentedArtifacts(), the one Go rule that hides the retired session.md from every artifact listing. - internal/server/runner.go: evidence.Markdown/MarkdownBytes are no longer copied. - internal/tui: the artifacts panel, the recorded count and the per-visit summary derive from PresentedArtifacts(), so the terminal never lists session.md. - web/src/app.js: the spike's renderArtifacts applies the same filter. - android: the Session section is the html export alone in a WebView — SessionView, the Markdown/HTML toggle and the session markdown path are removed; presentedArtifacts(step) filters the retired session.md out of the per-visit gallery, the run gallery and its count, the verdict/selection lists and the timeline indicator; data/protocol SessionExport drops the markdown fields. - Tests pin the single html file, prove no session.md is written and that a pre-existing one is neither overwritten nor presented, and prove a legacy export record still loads and its session.md is hidden. The legacy session.md of an older run stays on disk (dated evidence); it is only no longer produced and no longer presented. Checks (macOS, Go 1.24, Android Gradle 8.11.1, 18 Oct 2026): gofmt -l . prints nothing; go build ./... && go vet ./... clean; go test ./internal/... ./cmd/... -> 19 packages ok, 0 failures; node --check web/src/app.js ok and node --test web/test -> 20/20; gradle --offline --no-daemon :app:assembleDebug :app:testDebugUnitTest -> BUILD SUCCESSFUL. Packaged references checked: internal/author/skill/references/delivery.md and operations.md both described the session.md+session.html pair, so both are updated here to describe the single session.html export and the retired, hidden session.md. README.md and internal/author/skill/SKILL.md carry no session.md reference and install.go's managed inventory is unchanged (no reference added or removed). docs/notes/session-html-only.md records the remaining stale shared documentation (docs/stage-artifacts.md, docs/app-integration-verification.md) for the docs-fold writer; shared docs are not edited by this item.
456 lines
30 KiB
Markdown
456 lines
30 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. Four optional generic starters are task, review, research and
|
|
three-stage; 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 agent visit gets a per-run/step artifacts directory under the data
|
|
directory (`<data>/artifacts/<run>/<step>/`); the root is configurable and
|
|
defaults next to the database. The directory is passed as
|
|
`PIPELINES_ARTIFACTS_DIR` to a locally spawned Pi process and exported to the
|
|
OpenCode CLI where controllable, and it is stated in the agent prompt next to
|
|
`Run directory:` for every harness. OpenCode V2 tools run inside the shared serve
|
|
process, so there the prompt line, not the environment, is the reliable carrier.
|
|
The instruction is general: save images, screenshots, reports and logs there.
|
|
|
|
After the visit the server makes one bounded inventory 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.
|
|
`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.
|
|
|
|
- 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 `<run>/<step>` 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 2 MiB; 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.
|