Files
pipelines/docs/harnesses-and-control.md
alan bd07abcde8 Run pipeline stages on Claude Code (harness=claude)
A model stage with harness=claude, provider=anthropic and a Claude model id
runs one claude -p process per visit with the server user's Claude sign-in.
Only the declared tools exist (--tools) and nothing else is approved
(--permission-mode dontAsk); edits are approved only below the run directory
and the stage's artifacts directory. A permissions block, run write paths,
delivery=true and reasoning_effort none/minimal are refused, not widened.

Usage comes from the CLI's final result and counts toward budgets. Failures
are fixed text; billing, quota and rate-limit refusals map to
ErrProviderQuota. The redacted stream is the session export and evidence.
provider-check --harness claude and model overrides are covered.
2026-11-11 10:30:37 +00:00

239 lines
14 KiB
Markdown

# Harnesses and runner-owned control
## Reasoning effort (thinking level)
Add an optional setting to the model stage's existing `configs` block:
````markdown
```configs
provider=openai
model=gpt-5.2
reasoning_effort=high
```
````
Use your actual configured provider/model IDs. Each stage chooses its own level;
leaving it out, or using `default`, preserves the model/harness default.
| Setting | Behavior |
| --- | --- |
| `none` (alias `off`) | Disable reasoning, when supported |
| `minimal`, `low`, `medium`, `high`, `xhigh`, `max` | Select that native effort level, when supported |
| omitted / `default` | Leave existing defaults unchanged |
OpenCode V2 passes this as the selected model's named **variant**, for both
text-only and tool-using stages. Variant availability is model-specific; an
unavailable level is rejected, not silently replaced. See
[OpenCode variants](https://opencode.ai/v2/docs/models#variants).
Pi uses its native **thinking level**, mapping `none` to `off`, and verifies that
the selected model actually applied it before sending the task. Unsupported or
clamped levels fail clearly; availability also depends on the installed Pi
version. OpenCode V1 cannot apply this setting and rejects explicit effort.
This is a native runtime option, not a prompt instruction or token limit. Higher
effort can increase latency and cost; keep `budget_tokens`, `budget_usd`, and
provider spending limits separate. Existing definitions, defaults and published
versions are never rewritten. Editing the setting requires publishing a new
pipeline version as usual.
## OpenCode limits for stages and chats
OpenCode reads its tool-output and compaction limits only from configuration;
there is no per-session or per-agent setting. Pipeline stages therefore run on
their own OpenCode process, the **stage service**, so stages and chats can use
different limits:
- **Stages** run on a Pipelines-owned `opencode serve` on `127.0.0.1`, started
lazily by the first stage with `OPENCODE_CONFIG_CONTENT` holding the stage
limits merged over any inherited `OPENCODE_CONFIG_CONTENT`. It is the same
binary, user and XDG directories as your normal OpenCode, so it reads your
configuration, directory `opencode.json` files and provider credentials, and
writes sessions to the same OpenCode database (SQLite WAL; OpenCode sets a
busy timeout). Stage sessions stay visible to `opencode --session <id>`.
- **Chats** keep the OpenCode service they already use and its configuration.
Pipelines never writes `~/.config/opencode`. `PIPELINES_OPENCODE_CHAT_CONFIG`
(a JSON object) applies only when the server spawns its own chat
`opencode serve`. A shared or `-opencode-endpoint` service keeps the limits in
your OpenCode configuration (`tool_output`, `compaction`).
Server environment settings (add them to `opencode_env` in the install
manifest, or the server's environment):
| Setting | Default | Meaning |
| --- | --- | --- |
| `PIPELINES_OPENCODE_STAGE_TOOL_OUTPUT_MAX_BYTES` | `16384` | stage `tool_output.max_bytes`; `0` keeps OpenCode's default (51200) |
| `PIPELINES_OPENCODE_STAGE_TOOL_OUTPUT_MAX_LINES` | `400` | stage `tool_output.max_lines`; `0` keeps OpenCode's default (2000) |
| `PIPELINES_OPENCODE_STAGE_COMPACTION` | `on` | `on`/`off` set `compaction.auto`; `opencode` leaves it unset |
| `PIPELINES_OPENCODE_STAGE_CONFIG` | none | JSON object merged last, e.g. `{"compaction":{"keep":{"tokens":20000}}}` |
| `PIPELINES_OPENCODE_STAGE_SERVICE` | `owned` | `shared` runs stages on the CLI-managed service again, without stage limits |
| `PIPELINES_OPENCODE_CHAT_CONFIG` | none | JSON object for a server-spawned chat `opencode serve` only |
Over-limit tool output is truncated by OpenCode itself. Bash keeps the tail
with a `[showing lines X-Y of N; full output saved to <file>]` note, so the
model can still read the full file.
How the stage service behaves:
- **Registration.** Its URL, password and pid are in the owner-only file
`opencode-stage-service.json` (log: `opencode-stage-service.log`) under the
user cache directory's `pipelines/private`. A stage's retained reference
points at this file, so restart recovery, interruption and `session.html`
export reach the same service. References made before this change still point
at the CLI-managed service and keep working.
- **Health and restarts.** Every stage admission checks it with the
authenticated `/api/info`. A crashed service is started again on the same
port and password, also when a retained reference is used after it exited.
Start-up is bounded (20 s per attempt, 3 attempts). If it cannot start, the
stage fails with `OpenCode stage service exited before becoming ready (see
<log>)` or a timeout error. It never falls back to the shared service, because
that would silently drop the stage limits. Use
`PIPELINES_OPENCODE_STAGE_SERVICE=shared` to opt out deliberately.
- **Changed settings or an upgraded OpenCode** restart the service when no
session is active on it. A busy service keeps its old limits until it is idle.
- **Lifetime.** It runs detached in its own process session, so a stopping
Pipelines service does not take active stage work with it. On server shutdown
it is stopped only when no session is active on it. A busy service keeps
running, and the next start re-adopts its sessions and continues their runs
(see [Installation](install.md#restarts-keep-sessions-running)). With
`PIPELINES_SHUTDOWN_SESSIONS=stop`, or when the service is gone, restart
recovery interrupts the retained sessions through it, as before.
- `pipelines debug` is unchanged: it opens a fresh interactive harness
conversation, not the stage session.
Codex is a chat-only harness and Claude Code stages (`harness=claude`) run the
CLI's own print mode, so neither has a stage limit here. Their chats
keep their own defaults. Claude Code has `BASH_MAX_OUTPUT_LENGTH` and
`MAX_MCP_OUTPUT_TOKENS` (environment or `--settings`). Codex has
`tool_output_token_limit` (config override `-c`). Pi stages keep Pi's built-in
tool-output truncation; Pipelines sets no Pi limit.
## Harness defaults
Configure two independent model defaults:
```sh
./install --docker --harness pi # Docker setup without OpenCode login
pipelines harness setup opencode --default
pipelines harness setup pi
pipelines harness
pipelines harness default pi
pipelines new --harness pi
pipelines debug 12 --harness nvim
```
Setup uses a styled onboarding wizard that shows authentication and model steps
and fuzzy-searchable catalogs; the live picker renders each numbered step with
its title and purpose (no duplicated numbered prose is printed outside it). It
preserves existing credentials and does not perform inference. The interactive
harness model is chosen first (`Step 1 of 2`) and the new-pipeline-stage model
second (`Step 2 of 2`), in two separate pickers with the saved value preselected
and marked `(current)`; typing filters, arrow keys or Tab navigate, Enter
confirms, and Esc cancels without changing anything. Pi signs in through
`/login` in a fresh, no-context, extension-free, no-prompt-templates, no-tools
session launched with `--tui-mode regular` so the handoff stays visible above
Pi's interface instead of the default fullscreen clear (there is no standalone
`pi auth login`); the handoff names `/login`, the authentication-method step
("Sign in with an API key" for provider API credentials; account and Radius stay
the user's choice), finishing provider sign-in and exiting Pi with
`ctrl+c`/`ctrl+d` to return to model configuration. Existing credentials stay in
the Docker volume and are reused by exiting when no new sign-in is needed;
completing a sign-in can update the credentials stored in the volume.
Canceling or failing either picker leaves saved preferences unchanged.
On existing Docker setups, the reconfiguration commands
resolve and verify the current OpenCode V2/Pi releases, then operate inside the
container without restarting it. A rebuild is required only when the verified
release image identity (versions/digest) differs from the resolved releases; a
model/login-only change does not rebuild. A full `./install --docker` always
invokes the Docker build for a dirty source and relies on layer caching. Harness
installation stays Docker-only: the default native setup only detects an existing
host OpenCode/Pi and never installs, upgrades or downloads them, and
reconfiguration never falls back to host harness execution.
Container credentials and accounts are separate from host credentials and are
reused on reinstall/reconfigure.
Profiles live in XDG config home's `pipelines/harnesses.json` and record their
launch mode: a host profile launches the executable directly, while a
Docker-linked profile records the checkout directory and launches through
`docker compose exec`. `harness setup <opencode|pi>` on a native installation
configures (or converts) a host profile and clears any Docker link; on a Docker
installation it configures the container. Without a native installation,
reconfiguring a Docker-linked profile re-verifies that the recorded directory
still has `compose.yaml` and fails naming it instead of saving a link that cannot
launch. Setup's summary and `harness list` report the resulting mode (and, for
Docker, the directory) so a profile never silently stays Docker-linked. The
native installer writes host profiles for the harnesses it detects and clears a
stale Docker link rather than leaving the config Docker-linked.
Defaults affect only new drafts/starters, not existing immutable versions.
OpenCode uses `mini --model` to avoid changing unrelated host/project defaults.
Pi stage execution requires its profile on the server; interactive host and
execution-server credentials/settings remain separate.
The shared authoring/debug CLI prefix is Docker-aware: a loopback logical
`--url` is mapped to this Compose service only when a single bounded
`docker compose port` probe returns a `host:port` binding covering the requested
loopback address and port. Remote DNS names (including names such as
`127.remote.example` that merely begin with `127.`), malformed or non-matching
bindings, unmatched loopback endpoints and loopback `wss` endpoints fail safely
instead of being silently redirected or downgraded to plaintext. `provider-check`
on a Docker-linked profile runs in-container and preserves the caller's output
mode (`--json` only when requested) with exact stdout/exit propagation.
Put `harness=pi` in a model stage's configs to select Pi, or `harness=claude`
with `provider=anthropic` for Claude Code ([harnesses](harnesses.md#claude-code-stages)). nvim edits definitions
or displays debug evidence; it does not execute model stages.
For bounded review loops, add a fenced `limits` JSON object to the reviewer:
`{"max_visits":3,"on":["rejected"]}`. Its ordinary edges can be
`approved -> #success`, `rejected -> implement`, and `error -> #failure`.
On the third rejection the server terminates at failure regardless of model
counters. Approval on that visit can still succeed. Limits never enter prompts.
A reviewer that must separate a blocking defect from advisory notes declares both
edges: `rejected -> implement` (kept, with the `limits` above) is reserved for a
must-fix finding that names a concrete location, evidence and remedy, and
`advisory -> <next stage>` carries non-blocking duplication, performance or style
notes. An advisory outcome continues the run and never buys another implementer
visit. An implementer that can tell a transient environment, tooling or device
problem from an acceptance criterion that genuinely cannot be met declares a
bounded self-edge: `blocked_retryable -> implementer`, while `blocked -> #failure`
stays terminal. `max_visits` caps every visit of that stage, including re-entries
from the reviewer's `rejected` edge, so an implementer that is also the rejection
target needs a cap at least as large as the reviewer's budget; the published
maintenance, quick and focused pipelines use
`{"max_visits":5,"on":["blocked_retryable"]}`. A smaller implementer cap stops the
loop on the implementer's pre-execution limit before the reviewer's own cap can
fire, which silently makes the reviewer's `rejected` control unreachable. The runner
already counts the visits and stops at the cap, so neither loop needs new server
code and no model counts visits.
The previous turn's output (`input.md`), a capped essential `memory.md` (inlined)
and the run's full `history.md` are handed to each model stage as files; there
is no `memory` map or field selection. Put the facts the next stage needs in a
short `# handoff` section; it is what the next stage sees first. Only the `# outcome` section is
interpreted. Latest completed outputs are shared only within this run. Read
provenance and routing overrides are retained in SQLite and exposed in run
inspection/metadata.
These controls enforce counts/field selection, not semantic independence or every
prose guideline. AI-assisted guidelines validation is not implemented.
Verification: `go test` uses controlled RPC fixtures for Pi stage accounting,
results and timeout cleanup; `node --test scripts/test_pi_policy.mjs` exercises
policy gates. `python3 scripts/check-pi-rpc.py` checks installed Pi metadata RPC,
policy loading and idle lease cleanup without inference, also checked in an
isolated built Docker image non-root with networking disabled. Real-provider Pi
stage execution is now covered for the dated 2026-10-11 final install: run17 ran
both the OpenCode and Pi real stages on the installed runtime and each returned the
exact `pipelines-docker-verified` marker (see the dated install receipt in
`docs/installation-verification.md`). Active lease-expiry recovery, web tool
delivery and fresh interactive Docker Pi sign-in remain not tested. An additional
opt-in integration command,
`PIPELINES_PI_LOCAL=1 go test ./internal/stage -run TestPiInstalledLocalIntegration`,
exercised installed Pi with scripted loopback responses: actual permitted/denied
writes, budget exhaustion and active-shell cancellation without a delayed write.
It also covers isolated deny-all syntax repair and cumulative usage.
These are not real-provider results. Pi syntax-only formatting repair uses a separate deny-all
session, retains ownership and shares the budget; value changes are rejected
locally. Permission gates are not an OS sandbox.
Detailed packaged guidance: `internal/author/skill/references/control.md` and
`internal/author/skill/references/harnesses.md`.