harness-dispatch 0.4.0 → 0.5.0

package/README.md

@@ -1,97 +1,190 @@
 # harness-dispatch
 
-Delegate coding tasks to the agent CLIs you already pay for. harness-dispatch is a
-local MCP server that turns the coding harnesses on your machine (Claude Code,
-Codex, Cursor Agent, Antigravity CLI) and any local or remote API endpoint into
-tools any AI can call — routing each task to the best-fit agent, spending the
-flat-rate subscription quota you already own first. Routes with no billing backstop
-at all — a raw metered API key, or unknown billing — stay blocked until you opt in.
-
-Exposing harnesses as explicit tools is more reliable than telling an agent to shell
-out to another CLI: models are trained on tool calling, so they actually use tools
-they are given. And it routes whole tasks, not API requests — each harness keeps its
-own scaffolding, test loop, and codebase context; there's no proxy in between. Long
-tasks run as async jobs: start one, get an id back immediately, check for partial
-output, collect the result when it finishes. Runs execute in a detached runner
-process, so nothing is lost to a client timeout — or to the server itself
-restarting mid-run.
-(There is no Gemini CLI dispatcher; Google discontinued that CLI's backend in
-mid-2026, and Antigravity CLI is its replacement.)
-
-**What this does on your machine**, stated plainly before you install it: it spawns the
-CLI subprocesses above with your prompts, which can read and write files under the
-`workingDir` you pass it (this is the point — it's a coding agent router) and, depending
-on the workspace/safety policy in effect, run shell commands via those CLIs. Running
-`serve` additionally binds a local HTTP port (loopback by default, bearer-token gated —
-see [HTTP Surface](#http-surface) before pointing `--host` anywhere else). Nothing here
-is unusual for a coding-agent tool, but it's worth having in one place rather than
-inferred from separate sections.
-
-**A configured harness runs automatically** — nothing extra to switch on. If that
-harness's account has paid/overage billing enabled on the *provider's* side (Cursor's
-on-demand billing, Claude's usage credits, Codex's flexible credits, a raw metered API
-key, etc.), harness-dispatch will use it too — it does not detect or prevent provider-side
-billing state. It only blocks a route by default when there's no provider-side backstop
-at all (a raw metered API key, or unknown billing), until you set `allow_paid_usage: true`
-on it. See [Adding a harness](#adding-a-harness) for the config, and `status --json` /
-`status`'s `note:` lines for a given route's billing classification.
-
-## Requirements
-
-- Node.js `>=24.15.0`
-- At least one configured harness or OpenAI-compatible endpoint
+**Route whole coding tasks — not API requests — to the agent CLIs you already pay for.**
+
+Each harness keeps its own scaffolding, test loop, and codebase index. There's no
+proxy in between and nothing is re-implemented: Claude Code stays Claude Code. One
+orchestrating agent picks the right one per task and spends your flat-rate
+subscription quota before anything metered.
+
+It's a local MCP server, so the harnesses on your machine (Claude Code, Codex,
+Cursor Agent, Antigravity CLI, plus any local or remote OpenAI-compatible endpoint)
+become tools any AI can call. Exposing them as real tools beats asking an agent to
+shell out to another CLI: models are trained on tool calling, so they actually use
+the tools they're given. (No Gemini CLI: Google discontinued that CLI's backend in
+mid-2026, and Antigravity CLI replaced it.)
+
+## What it looks like
+
+Your agent calls one tool:
+
+```json
+{
+  "prompt": "Port the retry logic in src/net/ to the new backoff helper, then run the tests.",
+  "workingDir": "/path/to/project",
+  "hints": { "taskType": "execute" }
+}
+```
+
+Quick tasks come straight back:
+
+```json
+{
+  "mode": "single",
+  "completed": true,
+  "success": true,
+  "route": "codex_cli",
+  "model": "gpt-5.6-terra",
+  "output": "Ported 4 call sites to withBackoff(); 118 tests pass.",
+  "durationMs": 47210,
+  "routing": { "tier": 1, "taskType": "execute", "reason": "tier 1 best (3 available)" }
+}
+```
+
+Slow ones hand back a `jobId` after 25 seconds instead, and keep running:
+
+```json
+{ "mode": "single", "completed": false, "jobId": "job-1786977316001-b49d1232" }
+```
+
+Carry on working, then call `job_status` with that id for a live output tail or the
+finished result. The run lives in a detached process, so **nothing is lost to a client
+timeout — or to the server itself restarting mid-run.**
 
 ## Install
 
+Needs Node.js `>=22.22.2` (so current LTS works) and at least one harness or endpoint.
+
 ```bash
 npm install -g harness-dispatch
 harness-dispatch configure --yes
 harness-dispatch doctor --live
 ```
 
-`configure --yes` detects installed harnesses and writes `config.yaml`.
-Without `--yes` it only previews what it would detect and writes nothing —
-useful to check first, but not a substitute for the real run above. `doctor`
-then verifies the install end-to-end: binary + config load, harness
-detection, auth/billing classification, and route readiness. `--live` goes one
-step further and routes a single tiny prompt through the best eligible route so
-you see a real completion before wiring the server into your agent. The live
-probe respects billing policy — it never touches paid or unknown-billing routes
-unless you pass `--allow-paid`.
-
-Your Claude Code / Codex / Cursor subscriptions run by default, no opt-in needed
-— `configure`'s output tells you if anything's blocked and why. See
-[Adding a harness](#adding-a-harness) below for the config and the paid-usage note.
-
-> This project was renamed from `harness-router` to `harness-dispatch` — the npm
-> package, CLI command, env var prefix (`HARNESS_DISPATCH_*`), and MCP resource URIs
-> (`harness-dispatch://status`) all changed together. If you have an older install,
-> `npm uninstall -g harness-router && npm install -g harness-dispatch` and update any
-> `mcpServers`/`claude_desktop_config.json` entry to invoke `harness-dispatch`, not the
-> old command. Two older packages predate this rename and are no longer maintained:
-> `harness-router` (`0.3.2` on the registry) and the separately-published
-> `harness-router-mcp` (`0.2.0`) — both lack `usage`, `/v1/models`, `/v1/usage`,
-> Antigravity support, and every fix described in this README. Note that `npx -y
-> harness-dispatch` (used by the plugin's fallback launch path, see
-> [plugin/README.md](./plugin/README.md)) resolves to whatever is currently on the npm
-> registry, which can lag behind a local clone's `dist/`. Run `npm ls -g harness-dispatch`
-> to check which version is actually installed.
-
-You can also run without a global install:
+`configure --yes` detects installed harnesses and writes `config.yaml`; without
+`--yes` it previews and writes nothing. `doctor` then checks the whole chain:
+binary, config load, harness detection, auth and billing classification, route
+readiness. `--live` goes further and routes one tiny real prompt, so you see a
+completion before wiring anything into your agent. The live probe never touches paid or
+unknown-billing routes unless you pass `--allow-paid`.
 
-```bash
-npx harness-dispatch configure
-```
+Your Claude Code / Codex / Cursor subscriptions run by default with no opt-in;
+`configure` tells you if anything is blocked and why.
+
+No global install needed either: `npx harness-dispatch configure`.
 
 ### Plugin install (Claude Code / Claude Desktop / Codex)
 
 The `plugin/` directory packages the MCP server plus a delegation skill and
 `/route` + `/jobs` commands for one-step installs — see
-[plugin/README.md](./plugin/README.md). Claude Code:
+[plugin/README.md](https://github.com/fstubner/harness-dispatch/blob/main/plugin/README.md)
+(absolute link on purpose: `plugin/` is not shipped in the npm tarball, so a
+relative link is dead on npmjs.com). Claude Code:
 `/plugin marketplace add <repo path or URL>` then
 `/plugin install harness-dispatch@harness-dispatch`. Codex:
 `node plugin/scripts/install-codex.mjs`.
 
+## What it does on your machine
+
+Stated plainly, up front, rather than left to be inferred:
+
+- It **spawns the CLIs above as subprocesses** with your prompts.
+- Those CLIs **read and write files** under the `workingDir` you pass (that's the
+  point of the tool) and **run shell commands**, depending on the workspace and
+  safety policy in effect.
+- At most **4 agent CLIs run at once**; extra dispatches queue and start as slots
+  free. Tune with `max_concurrent_runs`.
+- `serve` additionally binds a local HTTP port: loopback only by default,
+  bearer-token gated. Read [HTTP Surface](#http-surface) before pointing `--host`
+  anywhere else.
+
+None of this is unusual for a coding-agent tool. It's here in one place so you can
+decide before installing rather than after.
+
+## Billing, and what it can't promise
+
+**A configured harness runs automatically**, with nothing to switch on. Routes that
+have no billing backstop at all, meaning a raw metered API key or billing it can't
+classify, stay blocked until you set `allow_paid_usage: true` on them.
+
+The honest limit: if a harness's account already has paid or overage billing switched
+on at the **provider** (Cursor on-demand, Claude usage credits, Codex flexible
+credits), harness-dispatch will spend that too. It cannot see or change provider-side
+billing state. What it does is refuse routes where *no* provider-side ceiling exists
+at all.
+
+Run `status` (or `status --json`) for any route's billing classification; the `note:`
+lines spell out the reasoning per route.
+
+<details>
+<summary>Renamed from <code>harness-router</code> — upgrade notes</summary>
+
+The npm package, CLI command, env var prefix (`HARNESS_DISPATCH_*`), and MCP resource
+URIs (`harness-dispatch://status`) all changed together. From an older install:
+`npm uninstall -g harness-router && npm install -g harness-dispatch`, then update any
+`mcpServers` / `claude_desktop_config.json` entry to invoke `harness-dispatch`.
+
+Two packages predate the rename and are unmaintained: `harness-router` (`0.3.2`) and
+the separately-published `harness-router-mcp` (`0.2.0`). Both lack `usage`,
+`/v1/models`, `/v1/usage`, Antigravity support, and every fix described here.
+
+`npx -y harness-dispatch`, the plugin's fallback launch path, resolves to whatever
+is currently on the npm registry, which can lag a local clone's `dist/`. Check with
+`npm ls -g harness-dispatch`.
+
+</details>
+
+## Safety profiles, and Cursor on Windows
+
+A caller asks for one of three profiles, and each is a limit rather than a
+capability:
+
+| Profile | Means |
+|---|---|
+| `read_only` | Look, don't touch |
+| `workspace_edit` | Edit files in the workspace, no arbitrary shell |
+| `full_auto` | Edit files and run shell |
+
+A route declares the floor it actually runs at (`effective_safety`), and is
+skipped when that floor exceeds what was asked for. A route is never quietly
+given more access than the caller requested.
+
+`cursor_cli` is the interesting case, because its capability differs by mode:
+
+- `read_only` uses `--mode plan`, which is genuinely read-only (verified: asked
+  to create one file and overwrite another, it did neither).
+- `full_auto` uses print mode, which edits and runs shell.
+- `workspace_edit` is **skipped on Windows**. Cursor's print mode grants write
+  and shell together, and `--sandbox enabled` — the flag that would constrain
+  shell while allowing edits — is macOS/Linux only. There is no edit-without-shell
+  mode to route to, so claiming that level would mean handing shell access to a
+  caller who explicitly asked not to have it.
+
+Cursor still edits code on Windows. Ask for `full_auto`.
+
+### Overriding it
+
+If you accept that Cursor's editing mode carries shell access and you want it
+to serve `workspace_edit` anyway, declare the floor yourself in `config.yaml` —
+your value replaces the shipped default:
+
+```yaml
+clis:
+  - name: cursor_cli
+    harness: cursor
+    command: cursor-agent
+    effective_safety:
+      read_only: read_only
+      workspace_edit: workspace_edit   # you are accepting shell access here
+      full_auto: full_auto
+```
+
+That is a deliberate local decision, not a bug workaround: the shipped default
+is conservative because the tool cannot verify what a given `cursor-agent`
+build will do. On macOS and Linux the better route is `--sandbox enabled`,
+which constrains shell for real — untested here, so it is not shipped on by
+default.
+
 ## Adding a harness
 
 `config.yaml` is entirely optional. There is no separate hidden defaults format —
@@ -264,8 +357,9 @@ harness-dispatch auth rotate             # rotate HTTP bearer token
 ```
 
 Hidden compatibility aliases currently map old alpha commands to the new surface:
-`dashboard` and `list-services` map to `status`, and `mcp --http <port>` maps to `serve`.
-They are not part of the public v0.4.0 vocabulary.
+`dashboard` and `list-services` map to `status`, `route <prompt>` runs a one-off
+routed dispatch, and `mcp --http <port>` maps to `serve`.
+They are not part of the public v0.5.0 vocabulary.
 
 ## MCP Surface
 
@@ -379,11 +473,18 @@ curl http://127.0.0.1:3333/v1/chat/completions \
 The REST surface is OpenAI-compatible enough for local clients that can speak
 `/v1/chat/completions`. The `model` field is treated as a routing/model hint.
 
+Non-streaming completions are backed by the same persisted job pipeline as the
+MCP `dispatch` tool: the reply carries `harness_dispatch.jobId`, and the same id
+is sent early as an `x-harness-dispatch-job-id` response header. If your client
+times out mid-run (curl defaults, CI step limits), the run still finishes and
+the result persists — recover it with the `job_status` MCP tool or by reading
+`~/.harness-dispatch/jobs/<jobId>/output/`.
+
 ## Endpoint Modes
 
-Harness Router supports two local/custom endpoint patterns:
+harness-dispatch supports two local/custom endpoint patterns:
 
-- `direct_openai_compatible`: Harness Router calls an OpenAI-compatible
+- `direct_openai_compatible`: harness-dispatch calls an OpenAI-compatible
   `/v1/chat/completions` endpoint directly. This is the right mode for Ollama,
   LM Studio, vLLM, LiteLLM, and private local HTTP model servers.
 - `harness_native_endpoint`: a downstream CLI keeps its agent scaffold but is
@@ -435,7 +536,7 @@ services:
 2. Verify configured routes without spending quota where possible.
 3. Classify auth and billing so paid or unknown-paid routes are not selected by accident.
 4. Choose routed harnesses, model priority, and safety profile.
-5. Write v0.4 config YAML.
+5. Write config YAML.
 6. Connect selected MCP agents or print snippets.
 
 The current command is conservative: it prints detected routes by default and writes
@@ -454,8 +555,10 @@ shape. Each route includes:
 - tier and model metadata
 - quota score and local call count
 - circuit breaker state — a tripped route's remaining cooldown is persisted to disk
-  (`~/.harness-dispatch/breaker_state.json`), so a server restart mid-cooldown still
-  excludes that route instead of retrying an exhausted one with a clean slate
+  (one file per route under `~/.harness-dispatch/breaker_state/`), so a server
+  restart mid-cooldown still excludes that route instead of retrying an exhausted
+  one with a clean slate; a pre-0.5 single-blob `breaker_state.json` is migrated
+  automatically on first read
 - skip reason when a route is disabled, unavailable, paid-blocked, unknown-billing,
   safety-incompatible, or circuit-broken
 - token limits when known
@@ -470,7 +573,9 @@ Workspace policy:
 
 - `shared`: run directly in the caller's `workingDir`.
 - `shared_locked`: run directly in `workingDir`, but serialize write-capable
-  dispatches for the same directory inside one router process.
+  dispatches for the same directory across ALL processes — concurrent dispatches
+  from separate server instances and detached job runners queue on a heartbeated
+  cross-process lock rather than editing the directory at the same time.
 - `copy`: copy the project into `.harness-dispatch/workspaces/...`, run the agent
   there, and return the isolated workspace path plus changed-file metadata.
 - `git_worktree`: create a detached git worktree for the route and return the
@@ -520,12 +625,49 @@ size-capped via single-file rotation, and never sent anywhere. Job artifacts
 `~/.harness-dispatch/jobs/<jobId>/` and are pruned after 7 days of inactivity by
 default — set `retention: { jobs_days: N }` in `config.yaml` (or
 `HARNESS_DISPATCH_JOB_MAX_AGE_MS` for a millisecond override) to change that
-window.
+window. `0` means keep forever, and a running or queued job with a live
+heartbeat is never pruned regardless of the window.
+
+At most **4 agent CLIs run at once**, machine-wide. Dispatches past that limit
+wait in `queued` and start as slots free — you still get a `jobId` back
+immediately and nothing is rejected or lost, only delayed. The bound exists
+because agent CLIs are heavyweight processes, not fan-outable HTTP calls: a
+measured burst of 13 concurrent runs exhausted memory and failed half of them.
+Change it with `max_concurrent_runs: N` in `config.yaml`; `0` removes the bound.
+
+Prompts and outputs flow only to the harnesses/endpoints you configured. **The
+router makes no other network call by default.**
+
+Routes rank on the `tier` and `weight` you set. Optionally, public Arena ELO
+benchmark data can inform ranking and derive tiers automatically:
+
+```yaml
+leaderboard:
+  enabled: true    # default false
+```
+
+Turning it on adds one GET to `api.wulong.dev` per process, refreshed daily.
+It sends nothing about you or your prompts. It is off by default because a
+benchmark maintained elsewhere should not quietly reorder the subscriptions
+you are paying for, and because a routing tool should not need the network to
+decide which of your local CLIs to run.
+
+## Chaining delegated work
+
+Pass the jobIds of earlier dispatches as `contextJobs` and their prompts and
+outputs are rendered into the new prompt directly:
+
+```json
+{ "prompt": "Now write the migration.", "contextJobs": ["job-1786977300001-0f0aaaaa"] }
+```
+
+Without it, chaining means reading the first job's output into your own context
+and re-summarising it into the second prompt — which spends the context that
+delegating was meant to save, and loses detail in the retelling.
 
-Prompts and outputs otherwise flow only to the harnesses/endpoints you
-configured. The router's only network call by default is the leaderboard
-refresh — a GET of public Arena ELO benchmark data from `api.wulong.dev` used
-for route scoring; it sends nothing about you or your prompts.
+Injected context is capped (24k characters total, 8k per job, 16 jobs) so it
+cannot crowd out the task itself, and a referenced job that is missing or still
+running is reported in the preamble rather than silently dropped.
 
 ## Development