Merge: one way to set up harnesses (pipelines harness setup)
This commit is contained in:
@@ -42,8 +42,8 @@ Configure two independent model defaults:
|
||||
|
||||
```sh
|
||||
./install --docker --harness pi # Docker setup without OpenCode login
|
||||
./install --opencode --default
|
||||
./install --pi
|
||||
pipelines harness setup opencode --default
|
||||
pipelines harness setup pi
|
||||
pipelines harness
|
||||
pipelines harness default pi
|
||||
pipelines new --harness pi
|
||||
@@ -82,8 +82,9 @@ 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`,
|
||||
`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
|
||||
|
||||
+76
-28
@@ -1,8 +1,8 @@
|
||||
# Harnesses
|
||||
|
||||
A harness is the agent program Pipelines drives. Pipelines never installs,
|
||||
upgrades or signs in a harness for you; it uses the copy and login you already
|
||||
have on the server machine.
|
||||
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 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
@@ -13,6 +13,52 @@ have on the server machine.
|
||||
|
||||
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`
|
||||
@@ -48,18 +94,16 @@ profiles in `~/.config/pipelines/harnesses.json` (override with
|
||||
drafts and starters). Published versions are never rewritten.
|
||||
|
||||
```sh
|
||||
pipelines harness list # profiles, default, launch mode
|
||||
pipelines harness setup opencode --host # fuzzy-pick both models
|
||||
pipelines harness setup pi --host --login # sign in to Pi, then pick models
|
||||
pipelines harness setup opencode --host --model P/M --pipeline-model P/M
|
||||
pipelines harness default pi # default harness for new/edit/debug
|
||||
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
|
||||
```
|
||||
|
||||
`--host` writes a native profile and clears any Docker link. `./install`
|
||||
writes the OpenCode host 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. `./install --opencode` and `./install --pi` (which run
|
||||
`scripts/setup-harness.py`) apply only to a Docker installation.
|
||||
`./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.
|
||||
@@ -93,9 +137,9 @@ A server started with `-opencode-endpoint URL` (or
|
||||
`PIPELINES_OPENCODE_ENDPOINT`) attaches chat to that service instead; the
|
||||
native installer does not set this.
|
||||
|
||||
**Install and sign in:** install OpenCode yourself, then sign in to your
|
||||
providers with OpenCode (`opencode auth login`). Pipelines reads the default
|
||||
model with `opencode api get /api/model/default`.
|
||||
**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
|
||||
@@ -118,12 +162,12 @@ thinking level and is verified before the task is sent.
|
||||
**Install and sign in:**
|
||||
|
||||
```sh
|
||||
# install Pi yourself so `pi` is on PATH, then:
|
||||
pipelines harness setup pi --host --login
|
||||
pipelines harness setup pi
|
||||
```
|
||||
|
||||
`--login` 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.
|
||||
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
|
||||
|
||||
@@ -138,7 +182,9 @@ 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:** use your existing Claude Code login. A background service can see
|
||||
**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:
|
||||
@@ -171,7 +217,8 @@ and read at its next step. Model changes apply from the next turn.
|
||||
it every 10 seconds and attaches when it appears. Pipelines never starts a
|
||||
Codex daemon or changes Codex settings.
|
||||
|
||||
**Sign in:** your existing Codex login. Threads created from Pipelines are
|
||||
**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
|
||||
@@ -207,14 +254,15 @@ elsewhere once you continue it in Pipelines.
|
||||
- **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`, or set an absolute `executable` with
|
||||
`pipelines harness setup <name> --host --executable /path/to/bin`.
|
||||
- **Claude Code not listed under Chat.** Check `claude` resolves in one of the
|
||||
locations above and `claude auth status` reports logged in.
|
||||
- **Codex not listed under Chat.** Open the Codex app and confirm the socket
|
||||
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 --host` on the server machine.
|
||||
`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.
|
||||
|
||||
+26
-9
@@ -23,8 +23,8 @@ them, and it stops naming whatever is missing.
|
||||
| git, curl | source checkout, updates, release lookup |
|
||||
| C compiler (`cc`, `clang` or `gcc`) | ntfy's SQLite driver is cgo (Xcode Command Line Tools on macOS) |
|
||||
| **Docker, running** | builds the Flutter web app and the APK |
|
||||
| OpenCode on `PATH` | required; default stage and chat harness |
|
||||
| Pi, Claude Code, Codex | optional; see [Harnesses](harnesses.md) |
|
||||
| OpenCode on `PATH` | required; default stage and chat harness (`curl -fsSL https://opencode.ai/install \| bash`) |
|
||||
| Pi, Claude Code, Codex | optional; set up after install with `pipelines harness setup <name>` |
|
||||
| tailscale | optional; tailnet HTTPS access |
|
||||
|
||||
The install is **all or nothing**: the web app and the server are built before
|
||||
@@ -60,7 +60,24 @@ Linux needs `systemctl --user`. Other platforms are refused.
|
||||
(stopped, plist renamed to `.disabled`), so only one web app is served.
|
||||
11. If `PIPELINES_WEB_PUBLIC_URL` is an `https://…ts.net` address, runs
|
||||
`tailscale serve --bg --https=<port> http://127.0.0.1:<web-port>`.
|
||||
12. Prints the browser URLs.
|
||||
12. Prints the browser URLs and the next step, setting up harnesses.
|
||||
|
||||
## Set up harnesses
|
||||
|
||||
One command per harness, the same on native and Docker installations:
|
||||
|
||||
```sh
|
||||
pipelines harness setup opencode # stages + chat (required; ./install already configured it)
|
||||
pipelines harness setup pi # stages
|
||||
pipelines harness setup claude # chat
|
||||
pipelines harness setup codex # chat
|
||||
pipelines harness list # status of all four
|
||||
```
|
||||
|
||||
Each run checks the CLI is installed where the server finds it (printing the
|
||||
install command if not), signs in with the harness's own login when needed,
|
||||
picks OpenCode/Pi default models, and verifies with the server's check. No
|
||||
restart is needed. See [Harnesses](harnesses.md#set-up-harnesses).
|
||||
|
||||
It also warns when a different `pipelines` earlier on `PATH` shadows the new
|
||||
one; it does not touch that binary.
|
||||
@@ -129,10 +146,10 @@ Options: `--server-url ws(s)://host:port/connect`, `--notes TEXT`, `--prefix`.
|
||||
|
||||
`./install --docker` is the optional Compose installation with its own
|
||||
container harness credentials; see [Docker](docker.md). Do not run it
|
||||
alongside a native install on the same ports. `./install --opencode` and
|
||||
`./install --pi` reconfigure a **Docker** installation's harness and refuse on
|
||||
a native install; native installs use `pipelines harness setup` (see
|
||||
[Harnesses](harnesses.md)).
|
||||
alongside a native install on the same ports. Its harnesses are set up with
|
||||
the same `pipelines harness setup opencode|pi` (run from the checkout), which
|
||||
configures them inside the container. The old `./install --opencode` and
|
||||
`./install --pi` only print that command and exit.
|
||||
|
||||
## Lifecycle commands
|
||||
|
||||
@@ -251,5 +268,5 @@ per-user data directory (`XDG_DATA_HOME`, or Application Support on macOS).
|
||||
- **Web app missing**: the server refuses to start without it. Run
|
||||
`./install --web`.
|
||||
- **A harness works in the terminal but not in the service**: the service uses
|
||||
the `PATH` recorded at install time. Rerun `./install` from a shell where the
|
||||
harness is on `PATH`. See [Harnesses](harnesses.md#troubleshooting).
|
||||
the `PATH` recorded at install time; `pipelines harness setup <name>` says
|
||||
so. Rerun `./install` from a shell where the harness is on `PATH`. See [Harnesses](harnesses.md#troubleshooting).
|
||||
|
||||
Reference in New Issue
Block a user