cedfc22e45
Resolve the run workspace's environment with workenv (direnv, parent .envrc, mise; same account rule as Claude chats) at run start and resume, and apply it to Pi stage processes, a per-environment Pipelines-owned OpenCode stage service (keyed by a hash of the change, reused across runs, idle ones stopped after PIPELINES_OPENCODE_STAGE_IDLE_TIMEOUT, revived per registration), delivery-gate checks and merges, plain-stage opencode CLI calls and file-change capture git reads. Record the directory, .envrc files, sources and variable names (never values) on the run detail; a blocked .envrc becomes a run warning.
388 lines
18 KiB
Markdown
388 lines
18 KiB
Markdown
# Harnesses
|
|
|
|
A harness is the agent program Pipelines drives. Pipelines never installs or
|
|
upgrades a harness; it uses the copy you install on the server machine and the
|
|
harness's own login, which `pipelines harness setup <name>` opens for you.
|
|
|
|
| Harness | Pipeline stages | Chat | Mid-turn messages | Authoring/debug sessions |
|
|
| --- | --- | --- | --- | --- |
|
|
| OpenCode | yes (default) | yes (default) | queued until the turn ends | yes |
|
|
| Pi | yes (`harness=pi`) | no | n/a | yes |
|
|
| Claude Code | no | yes | yes, delivered into the running turn | no |
|
|
| Codex | no | yes | yes, via `turn/steer` | no |
|
|
|
|
Stage configs accept only `harness=opencode` or `harness=pi`.
|
|
|
|
## Set up harnesses
|
|
|
|
After `./install` (native or `--docker`), set up each harness with one
|
|
command. It works the same on native and Docker installations (the mode is
|
|
detected from the installation):
|
|
|
|
```sh
|
|
pipelines harness setup opencode # stages + chat: sign in, pick the two default models
|
|
pipelines harness setup pi # stages: sign in via /login, pick the two default models
|
|
pipelines harness setup claude # chat: claude auth login if needed, verify
|
|
pipelines harness setup codex # chat: codex login if needed, verify the App Server socket
|
|
pipelines harness list # installed / signed in / configured / default, all four
|
|
```
|
|
|
|
Each run:
|
|
|
|
1. **Checks the CLI** is installed where the server finds it (the `PATH`
|
|
recorded by `./install`, plus the locations listed per harness below). If
|
|
it is missing, it prints the install command and stops:
|
|
|
|
| Harness | Install command |
|
|
| --- | --- |
|
|
| OpenCode | `curl -fsSL https://opencode.ai/install \| bash` |
|
|
| Pi | `npm install --global @earendil-works/pi-coding-agent` |
|
|
| Claude Code | `curl -fsSL https://claude.ai/install.sh \| bash` |
|
|
| Codex | `npm install --global @openai/codex` |
|
|
|
|
2. **Signs in** with the harness's own login only when it is not signed in
|
|
(`opencode auth login`, Pi's `/login`, `claude auth login`, `codex login`).
|
|
`--login` forces it.
|
|
3. **Models.** OpenCode and Pi: fuzzy-pick the interactive model and the
|
|
new-pipeline model (or pass `--model P/M --pipeline-model P/M`; `--default`
|
|
makes the harness the default). Claude Code and Codex: nothing to pick;
|
|
models are chosen per chat in the app.
|
|
4. **Verifies** with the server's own check and prints one success line:
|
|
OpenCode/Pi list both models from a signed-in provider (no inference);
|
|
Claude Code `claude auth status`; Codex the App Server socket. No restart is
|
|
needed: new runs read OpenCode/Pi profiles when they start, and the server
|
|
looks for Claude Code and Codex every 10 seconds. (After a first OpenCode
|
|
sign-in to a new provider, run `pipelines restart` if the app's chat does not
|
|
offer it yet.)
|
|
|
|
OpenCode is required: `./install` stops without it, because it is the default
|
|
stage and chat harness, and configures its profile itself. Claude Code and
|
|
Codex are chat-only and need a native installation.
|
|
|
|
## Choosing models
|
|
|
|
**Pipeline stages.** Each model stage pins its own model in its `configs`
|
|
block:
|
|
|
|
````markdown
|
|
```configs
|
|
provider=PROVIDER
|
|
model=MODEL
|
|
harness=opencode
|
|
reasoning_effort=high
|
|
```
|
|
````
|
|
|
|
`harness` defaults to `opencode`. `reasoning_effort` is optional; see
|
|
[harnesses and control](harnesses-and-control.md). Use the exact IDs your
|
|
harness lists (`opencode models`, `pi --list-models`).
|
|
|
|
**Per run**, without changing the definition:
|
|
|
|
```sh
|
|
pipelines run "my pipeline" "task" --model PROVIDER/MODEL
|
|
pipelines run "my pipeline" "task" --stage-model review=PROVIDER/MODEL
|
|
```
|
|
|
|
Precedence: `--stage-model` > `--model` > the model pinned in the stage.
|
|
Unknown stage keys and malformed models are refused before the run starts.
|
|
|
|
**Defaults for new pipelines and interactive sessions** come from harness
|
|
profiles in `~/.config/pipelines/harnesses.json` (override with
|
|
`PIPELINES_HARNESS_CONFIG`). Each profile has an `executable`, a `model`
|
|
(interactive authoring/debug sessions) and a `pipeline_model` (stages in new
|
|
drafts and starters). Published versions are never rewritten.
|
|
|
|
```sh
|
|
pipelines harness setup opencode # fuzzy-pick both models
|
|
pipelines harness setup pi --login # sign in to Pi again, then pick models
|
|
pipelines harness setup opencode --model P/M --pipeline-model P/M
|
|
pipelines harness default pi # default harness for new/edit/debug
|
|
pipelines harness list --json # profiles, launch mode and status
|
|
```
|
|
|
|
`./install` writes the OpenCode profile itself (from `--model`, the saved
|
|
profile, or OpenCode's own default) and keeps an existing valid Pi profile; it
|
|
never adds a Pi profile on its own.
|
|
|
|
**Chat** models are chosen in the chat's model picker; each harness supplies
|
|
its own catalog.
|
|
|
|
## Verifying
|
|
|
|
```sh
|
|
pipelines doctor # health + OpenCode API discovery, no inference
|
|
pipelines provider-check --model P/M # one tiny tool-free generation (may cost)
|
|
pipelines provider-check --harness pi --model P/M
|
|
python3 scripts/check-pi-rpc.py # Pi RPC and policy, no inference
|
|
```
|
|
|
|
`pipelines restart` and `pipelines doctor` print the server's startup report.
|
|
Its **Chat** row lists the chat harnesses the server found (for example
|
|
`claude, codex, opencode`), and the **Harnesses** rows list the profiles. Then
|
|
start a chat with each harness in the app.
|
|
|
|
## OpenCode
|
|
|
|
**Used for:** default stage harness, default chat harness, and `pipelines
|
|
new`, `edit` and `debug` sessions.
|
|
|
|
**Found by:** `PIPELINES_OPENCODE`, then `PATH`, then `/opt/homebrew/bin`,
|
|
`/usr/local/bin`, `/usr/bin`, `~/.local/bin`. `./install` requires `opencode`
|
|
on `PATH` and records its absolute path.
|
|
|
|
**Launched as:** chat uses the OpenCode service the server attached to (an
|
|
endpoint from `-opencode-endpoint URL` / `PIPELINES_OPENCODE_ENDPOINT`, or a
|
|
loopback `opencode serve` the server spawns). Stage sessions run on a separate
|
|
Pipelines-owned loopback `opencode serve`, the *stage service*, which uses your
|
|
normal OpenCode configuration, login and session database but adds the stage
|
|
tool-output and compaction limits. See "OpenCode limits for stages and chats"
|
|
in [harnesses-and-control.md](harnesses-and-control.md).
|
|
|
|
**Install and sign in:** `pipelines harness setup opencode` (runs
|
|
`opencode auth login` when no provider is connected). Pipelines reads the
|
|
default model with `opencode api get /api/model/default`.
|
|
|
|
**Mid-turn messages:** not supported by the harness. A message sent while a
|
|
turn runs is stored in the server's durable queue (up to 8 per chat) and sent
|
|
in order when the turn ends, also after a server restart.
|
|
|
|
## Pi
|
|
|
|
**Used for:** pipeline stages with `harness=pi`, and `new`/`edit`/`debug`
|
|
with `--harness pi`. Not a chat harness.
|
|
|
|
**Found by:** the `executable` in the `pi` profile. A run with a Pi stage is
|
|
refused unless that profile exists on the server.
|
|
|
|
**Launched as:** `pi --mode rpc --provider P --model M --session-dir <run dir>
|
|
--no-approve --no-extensions --no-skills --no-context-files
|
|
--no-prompt-templates --no-themes --extension policy.js`. The policy extension
|
|
enforces the stage's tool and edit permissions. `reasoning_effort` maps to Pi's
|
|
thinking level and is verified before the task is sent.
|
|
|
|
**Install and sign in:**
|
|
|
|
```sh
|
|
pipelines harness setup pi
|
|
```
|
|
|
|
When Pi lists no models (or with `--login`) setup opens a bare Pi session; run
|
|
`/login` there, finish the provider sign-in, and exit with Ctrl+C or Ctrl+D to
|
|
return to model selection.
|
|
|
|
## Claude Code
|
|
|
|
**Used for:** chat only.
|
|
|
|
**Found by:** `PIPELINES_CLAUDE`, then `PATH`, then `~/.local/bin/claude`,
|
|
`/opt/homebrew/bin/claude`, `/usr/local/bin/claude`. The server checks again
|
|
every 10 seconds, so installing it later needs no restart.
|
|
|
|
**Launched as:** one `claude -p` process per active chat with stream-json input
|
|
and output and `--permission-prompt-tool=stdio` (at most 8 live at once). Idle
|
|
chats are resumed with `--resume <id>`. Approvals and `AskUserQuestion` appear
|
|
as cards in the app.
|
|
|
|
**Sign in:** `pipelines harness setup claude` runs `claude auth login` when
|
|
`claude auth status` (with the server's `PATH` and the fallbacks below) is not
|
|
signed in. A background service can see
|
|
a stale keychain entry; when the default login check fails, the server retries
|
|
with the login file in `~/.claude`. For a login that does not depend on either,
|
|
create a long-lived token and store it privately:
|
|
|
|
```sh
|
|
claude setup-token
|
|
# save the printed token:
|
|
install -m 600 /dev/null ~/.config/pipelines/claude-token
|
|
$EDITOR ~/.config/pipelines/claude-token
|
|
```
|
|
|
|
`PIPELINES_CLAUDE_TOKEN_FILE` names another file. The file must be a regular,
|
|
owner-only file. The startup report shows `Claude service token present` when
|
|
it is read. An `ANTHROPIC_API_KEY`, `CLAUDE_CODE_OAUTH_TOKEN` or
|
|
`CLAUDE_CONFIG_DIR` in the server's environment takes precedence, and a chat
|
|
directory that chooses its own account wins over all of these (see
|
|
[Per-directory accounts and environment](#per-directory-accounts-and-environment)).
|
|
|
|
**Models:** the catalog comes from the CLI; switching applies live and is kept
|
|
for the next turn.
|
|
|
|
**Mid-turn messages:** yes. The message is written to the running CLI's stdin
|
|
and read at its next step. Model changes apply from the next turn.
|
|
|
|
## Codex
|
|
|
|
**Used for:** chat only.
|
|
|
|
**Found by:** the Codex App Server control socket at
|
|
`$CODEX_HOME/app-server-control/app-server-control.sock` (default
|
|
`~/.codex/...`). The Codex app provides it while it runs. The server checks for
|
|
it every 10 seconds and attaches when it appears. Pipelines never starts a
|
|
Codex daemon or changes Codex settings.
|
|
|
|
**Sign in:** `pipelines harness setup codex` runs `codex login` when `codex
|
|
login status` fails, then checks for the socket. Threads created from Pipelines are
|
|
ordinary Codex threads and also show in the Codex app.
|
|
|
|
**Behavior:** new threads use the `workspace-write` sandbox and Codex's own
|
|
approval policy; command, file-change and permission requests appear as
|
|
approval cards.
|
|
|
|
**Mid-turn messages:** yes, with `turn/steer` pinned to the running turn. If
|
|
the turn already ended, the message is queued for the next turn instead.
|
|
|
|
## Per-directory accounts and environment
|
|
|
|
A chat runs in the directory you choose for it. For Claude Code the server
|
|
also applies that directory's own environment, so the chat behaves as if you
|
|
had opened a terminal there and started `claude`:
|
|
|
|
- **Working directory.** The `claude` process starts in the chat directory
|
|
with `PWD` set to it. Codex threads are started with that `cwd` and OpenCode
|
|
sessions with that location, so every harness runs tools there.
|
|
- **Git identity.** `includeIf "gitdir:..."` rules in your git config apply
|
|
automatically: git resolves them from the working directory of a repository
|
|
under the chosen directory.
|
|
- **direnv.** When `direnv` is installed (the service's `PATH`, then
|
|
`/opt/homebrew/bin`, `/usr/local/bin`, `~/.local/bin`, `~/.nix-profile/bin`)
|
|
the server runs `direnv export json` in the chat directory, so an `.envrc`
|
|
there or in a parent applies. Only an `.envrc` you already allowed is used;
|
|
the server never runs `direnv allow`. A blocked `.envrc` is logged and shown
|
|
in the chat as a "Directory environment" notice, and nothing from it is
|
|
applied.
|
|
- **mise.** When `mise` is installed the server merges `mise env --json`
|
|
(untrusted config is reported the same way). When both set a variable,
|
|
direnv wins.
|
|
- A plain `.env` file is not read on its own; use an `.envrc` (`dotenv` loads
|
|
one) so the allow check applies.
|
|
|
|
The result is merged onto the server's environment and cached per directory;
|
|
editing an `.envrc`, a mise config, a file direnv watches, or allowing or
|
|
denying an `.envrc` makes the next chat process read it again. Set
|
|
`PIPELINES_DIRECTORY_ENV=off` in the server's environment to turn this off.
|
|
|
|
**Choosing the Claude account per directory.** When the directory's
|
|
environment sets or unsets any of `CLAUDE_CONFIG_DIR`, `CLAUDE_CODE_OAUTH_TOKEN`,
|
|
`ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, `CLAUDE_SECURESTORAGE_CONFIG_DIR`,
|
|
`CLAUDE_CODE_USE_BEDROCK` or `CLAUDE_CODE_USE_VERTEX`, that directory owns the
|
|
account: the service token and the `~/.claude` login-file fallback are not
|
|
added, and inherited server credentials (`CLAUDE_CODE_OAUTH_TOKEN`,
|
|
`ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`) are dropped unless the directory
|
|
sets them. Transcripts kept in a directory's `CLAUDE_CONFIG_DIR` are found for
|
|
history and resume, also after a restart. For example:
|
|
|
|
```sh
|
|
# ~/work/.envrc (then run `direnv allow ~/work`)
|
|
export CLAUDE_CONFIG_DIR="$HOME/work/.claude-profile"
|
|
export GH_CONFIG_DIR="$HOME/work/.gh"
|
|
```
|
|
|
|
Sign that profile in once from a terminal in that directory (`claude`, then
|
|
`/login`). Shell functions or aliases in `~/.zshrc` that switch accounts by
|
|
`$PWD` are not seen by the server, which does not run your shell; move them
|
|
into an `.envrc`.
|
|
|
|
Codex and OpenCode chats share one App Server or `opencode serve` process
|
|
across directories, so only the working directory applies to them; their
|
|
account is the one that process uses.
|
|
|
|
**Pipeline runs.** A run resolves its workspace's environment the same way
|
|
(direnv in the workspace, so a parent `.envrc` applies to a worktree below it;
|
|
mise; the same account rule) when it starts, and again when it resumes after a
|
|
decision or a restart. Everything the server starts for the run gets it:
|
|
|
|
- Pi stage processes (`PWD` is the workspace).
|
|
- OpenCode stages: the server runs one Pipelines-owned stage service per
|
|
distinct environment (keyed by a hash of the change, registration
|
|
`opencode-stage-service-env-<key>.json` beside the original
|
|
`opencode-stage-service.json`), started with that environment, so the
|
|
agent's shell commands, `gcloud`, and any `claude` it launches use the
|
|
directory's accounts. Runs with the same environment share the service; a
|
|
workspace without its own environment keeps the original service. An idle
|
|
per-environment service is stopped after
|
|
`PIPELINES_OPENCODE_STAGE_IDLE_TIMEOUT` (default `30m`, `off` keeps it until
|
|
shutdown); its registration stays, so a retained session revives on the same
|
|
endpoint with the directory's current environment. With
|
|
`PIPELINES_OPENCODE_STAGE_SERVICE=shared` stages run on the CLI-managed
|
|
service and the directory environment does not reach their tools.
|
|
- Delivery-gate checks (`sh -c`) and the gate's merge commands, the
|
|
`opencode` CLI calls of plain model stages, and the git reads behind
|
|
file-change captures.
|
|
|
|
When the directory chooses the Claude account (for example its `.envrc` sets
|
|
`CLAUDE_CONFIG_DIR`), inherited `CLAUDE_CODE_OAUTH_TOKEN`, `ANTHROPIC_API_KEY`,
|
|
`ANTHROPIC_AUTH_TOKEN` and `CLAUDE_SECURESTORAGE_CONFIG_DIR` are removed for all
|
|
of these, as for chats.
|
|
|
|
The run detail (`pipelines inspect <run> --json`, field `environment`) records
|
|
what applied: the directory, the `.envrc` files, the sources, the names of the
|
|
variables set and unset, the dropped credential names, and the service key,
|
|
never a value. A blocked `.envrc` or untrusted mise config is listed in the
|
|
run's `warnings` (and printed by `pipelines inspect`); the run continues with
|
|
the server's environment.
|
|
|
|
## Adopting existing sessions
|
|
|
|
```sh
|
|
pipelines chat-adopt <session-id> [--harness opencode|claude|codex] [--title TEXT]
|
|
```
|
|
|
|
Without `--harness`, each available harness is asked. Stop using the session
|
|
elsewhere once you continue it in Pipelines.
|
|
|
|
## Continuing or exporting a chat
|
|
|
|
A chat's id is the harness's own session id (Claude Code session UUID, Codex
|
|
thread id, OpenCode `ses_…`). The app's chat information sheet shows it with
|
|
the harness and directory, and copies a command that continues the session in
|
|
a terminal on the server machine:
|
|
|
|
| Harness | Resume command |
|
|
| --- | --- |
|
|
| Claude Code | `cd <dir> && claude --resume <id>` |
|
|
| Codex | `cd <dir> && codex resume <id>` |
|
|
| OpenCode | `cd <dir> && opencode --session <id>` |
|
|
|
|
Each `chat_sessions` row carries this as `resume_command`. Stop the turn in
|
|
Pipelines before continuing the session elsewhere.
|
|
|
|
`chat_export` (`{"chat_export": {"session_id", "format"}}`) returns
|
|
`chat_export_file` (`name`, `mime`, `content`, `messages`, `truncated`):
|
|
`markdown` is a transcript of user and assistant messages and agent reports
|
|
with timestamps and one line per tool call; `json` is the same as data.
|
|
Reasoning and full tool output are left out, and an export is bounded at
|
|
8 MiB (older pages are dropped and `truncated` is set). `native` returns
|
|
Claude Code's own JSONL transcript, offered when a row has `native_export`.
|
|
Only operator chats are exported.
|
|
|
|
## Limits
|
|
|
|
- Stage session exports: the native session read is capped at 8 MiB and the
|
|
rendered `session.html` at 8 MiB. A session over the read cap cannot be
|
|
exported by retrying; the stage reports it.
|
|
- Claude Code chat history: a transcript over 64 MiB is reported as exceeding
|
|
the history limit instead of being truncated.
|
|
- Codex tool detail in history is truncated at 64 KiB and marked as such.
|
|
- Losing the Codex App Server connection drops pending approvals; they are
|
|
reported as an error, not shown as still actionable.
|
|
- Queued chat messages: at most 8 per chat while a turn runs.
|
|
|
|
## Troubleshooting
|
|
|
|
- **Harness works in a terminal but not from the service.** The login service
|
|
does not read your shell profile. It uses the `PATH` recorded when you ran
|
|
`./install` (prefixed with `<prefix>/bin`). Rerun `./install` from a shell
|
|
where the harness is on `PATH` (setup tells you when this is the case). For
|
|
OpenCode/Pi you can instead set an absolute executable with
|
|
`pipelines harness setup <name> --executable /path/to/bin`.
|
|
- **Claude Code not listed under Chat.** Run `pipelines harness setup claude`.
|
|
- **Codex not listed under Chat.** Run `pipelines harness setup codex`; open
|
|
the Codex app and confirm the socket
|
|
exists under `~/.codex/app-server-control/`. The installer does not record
|
|
a custom `CODEX_HOME` for the service, so the default `~/.codex` is used.
|
|
- **"Pi is not configured on this execution server".** Run
|
|
`pipelines harness setup pi` on the server machine.
|
|
- **"invalid provider/model identifier".** Use the exact IDs from the harness's
|
|
model list; placeholders such as `default/default` are refused.
|