Files
pipelines/docs/harnesses-and-control.md
T
alan a70e3aef4b Install Pipelines natively by default on macOS and Linux
Add scripts/setup-native.py and make ./install (and --native) build the server, the CLI
and ntfy from source into ~/.local/share/pipelines, detect an existing host OpenCode
and Pi instead of installing them, install the packaged authoring skill, migrate an
existing Docker database and ntfy auth store, save the host client default and start
both services. ./install --docker keeps the previous Docker server + ntfy
installation unchanged.

ntfy is compiled from its pinned Go module on every host because upstream publishes
no macOS server binary (its darwin asset is built with -tags noserver); its cgo
SQLite driver is why a C compiler is now required natively. The ntfy credential
bootstrap and the client default writer are shared by both installers,
installation.Load resolves symlinked prefixes, the Docker migration copies the
SQLite write-ahead log so the newest definitions and runs are not lost, and the
account subcommands read the generated configuration through NTFY_CONFIG_FILE.

Verified on macOS: 115 Python tests, go build/vet/test, and scratch installs that
migrate 9 pipelines and 31 runs, build ntfy v2.30.0 and start both services healthy
on spare ports before stopping them.
2026-10-13 17:20:14 +01:00

100 lines
6.0 KiB
Markdown

# Harnesses and runner-owned control
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.
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.
Add a fenced `memory` map such as
`{"task":"input.prompt","checks":"planner.checks"}` to select reviewer
input without previous verdicts. Implementers can select
`{"task":"input.prompt","plan":"planner.plan","feedback":"review.findings?"}`.
`?` means omit if unavailable. A memory block replaces the previous-stage input;
without it, existing previous-output handoffs are unchanged. 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`.