bd07abcde8
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.
239 lines
14 KiB
Markdown
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`.
|