165 lines
9.5 KiB
Markdown
165 lines
9.5 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.
|
|
|
|
## Harness defaults
|
|
|
|
Configure two independent model defaults:
|
|
|
|
```sh
|
|
./install --docker --harness pi # Docker setup without OpenCode login
|
|
./install --opencode --default
|
|
./install --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> --host` configures (or
|
|
converts) a host profile and clears any Docker link; without `--host`,
|
|
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. 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 and the run's accumulated `memory.md` are handed to
|
|
each model stage as files; there is no `memory` map or field selection. Put the
|
|
facts later stages need in free-form headings. 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`.
|