pi-agent-fleet 0.3.0 → 0.5.0

package/README.md

@@ -9,6 +9,16 @@ DAG-of-agents fleets for [pi](https://github.com/earendil-works/pi-coding-agent)
 └─ ○ reviewer (k3) · waiting on builder-relaunch
 ```
 
+## Demo
+
+Live browser canvas — per-node status, turns, tokens, cost, and click-to-peek session tail:
+
+![Fleet canvas — live DAG with per-node cost and status](assets/canvas.png)
+
+Node detail side panel — peek a running node's recent session without leaving the canvas:
+
+![Fleet canvas — click a node to peek its session tail](assets/canvas-node-peek.png)
+
 ## Why
 
 One agent is a tool. A **fleet** is a workflow: researchers feed builders, builders feed reviewers, reviewers gate quality — all visible, all recorded, all contract-checked. Fleets run in-process via pi's SDK: any provider pi is logged into (Claude, Codex, Kimi, …) works per-node.
@@ -32,26 +42,57 @@ Ask your pi session (the LLM drives the tools):
 > combiner (depends on both) writes output/sum.md with the total.
 > Each declares its output as a markdown contract.
 
-The agent calls `fleet_plan` (validates + ASCII preview), you confirm, `fleet_launch` runs it. Watch the live widget; read the report at `.fleet/<name>-<ts>/report.md`.
+The agent calls `fleet_design` (if you describe it in prose) or `fleet_plan` (if you already have JSON), you confirm the preview, then `fleet_launch` runs it. Plan and launch responses include a fleet canvas link by default; the in-chat widget is hidden until you run `/fleet viz`. Read the report at `.fleet/<name>-<ts>/report.md`.
 
-## Fleet modes
+JSON pipeline variant — a numeric handoff chain where workers pass typed JSON, verified by schemas at contract check:
+
+> Plan and launch the fleet defined in `examples/json-number-pipeline.json`.
 
-**One-shot DAG** — static dependency graph, parallel layers, contracts at exit:
+One writer emits `{"values":[3,5,8]}`, two parallel consumers add and subtract, a synthesizer combines the results — each output declared as a `json` contract with a `schema` naming its required and numeric keys.
+
+## Writing a fleet
 
 ```json
 {
   "fleet_name": "auth-research",
   "type": "dag",
-  "config": { "max_concurrent": 4, "model": "gpt-5.4-mini" },
+  "config": {
+    "max_concurrent": 4,
+    "model": "gpt-5.4-mini",
+    "effort": "medium",
+    "warn_cost_usd": 10
+  },
   "workers": [
-    { "id": "research", "type": "research", "task": "…",
-      "outputs": [{ "path": "output/findings.md", "kind": "markdown", "required": true }] },
-    { "id": "build", "type": "code-run", "task": "…", "depends_on": ["research"],
-      "outputs": [{ "path": "src/auth/login.ts", "kind": "file-exists", "required": true }] }
+    {
+      "id": "research",
+      "type": "research",
+      "task": "…",
+      "outputs": [{ "path": "output/findings.md", "kind": "markdown", "required": true }]
+    },
+    {
+      "id": "build",
+      "type": "code-run",
+      "task": "…",
+      "depends_on": ["research"],
+      "model": "kimi-coding/k3",
+      "effort": "high",
+      "outputs": [{ "path": "src/auth/login.ts", "kind": "file-exists", "required": true }]
+    }
   ]
 }
 ```
 
+- `config.model` / `config.effort` — fleet-wide defaults; per-worker `model` and `effort` override.
+- `effort` maps to pi thinking levels: `off | minimal | low | medium | high | xhigh | max`.
+- `config.warn_cost_usd` — soft cost guardrail surfaced in the canvas and report.
+- `iterate: false` — run the node once at iteration 1 and carry its outputs forward.
+- `worktree: true` — run the node in a dedicated git worktree.
+- Worker types `research`, `code-run`, `reviewer`, `write`, `read-only` each get a tailored tool set.
+
+## Fleet modes
+
+**One-shot DAG** — static dependency graph, parallel layers, contracts at exit.
+
 **Iterative fleet** — reviewer-gated replay until quality passes:
 
 ```json
@@ -64,7 +105,7 @@ The agent calls `fleet_plan` (validates + ASCII preview), you confirm, `fleet_la
 
 A reviewer node writes a verdict contract (`verdict: lgtm | iterate | escalate` + actionable body). `iterate` → builders get the review injected as feedback next iteration. `lgtm` × `lgtm_count` consecutive → completed. `escalate` → fleet pauses and notifies you. `gate: "none"` → free-running loop (autoresearch pattern: eval instructions live in the worker's task text).
 
-**Worktree mode** — `worktree: true` on a node: the worker is directed to create its own git worktree at a designated path/branch. Downstream nodes see upstream worktree paths/branches in their prompts. The extension runs zero git commands; conflicts are resolved by resolver nodes you add to the DAG.
+**Worktree mode** — `worktree: true` on a node: the worker runs in a dedicated git worktree on a deterministic branch (`fleet/<fleet-name>/<node-id>`). The extension creates the worktree, commits the worker's changes, and, when two or more worktree workers exist, auto-injects a `fleet-integrator` node that merges their branches in dependency order before the agent runs. Overlapping repo-relative output paths without an ordered handoff are rejected at plan time. Merge conflicts surface as a failed integrator with a `status_note` listing the files, so the operator can resolve and relaunch.
 
 **Run-once vs replay nodes** — `iterate: false`: node runs at iteration 1 only, outputs carry over (e.g. research that doesn't change).
 
@@ -77,7 +118,15 @@ Every worker declares `outputs[]` with kinds, verified in code at worker exit be
 | `markdown` | exists, non-empty, starts with `#` |
 | `file-exists` | exists, non-empty (repo-relative paths = code edits) |
 | `verdict` | `verdict: lgtm\|iterate\|escalate` line + non-empty body |
-| `json` / `yaml` | parses |
+| `json` | parses as JSON; optional `schema` checks (below) |
+| `yaml` | parses as YAML |
+
+JSON outputs may declare a `schema` with `required_keys` (keys that must exist) and `number_keys` (keys that must be numbers or arrays of numbers). Schemas are only allowed on `kind: "json"` outputs, are injected into the worker's prompt, and are enforced at contract check. When a `schema` is present, the JSON must be a top-level object (arrays and scalars fail):
+
+```json
+{ "path": "output/sum.json", "kind": "json", "required": true,
+  "schema": { "required_keys": ["operation", "result"], "number_keys": ["result"] } }
+```
 
 Failed required contract → `contract_failed`, dependents blocked, orchestrator notified. No silent passes.
 
@@ -85,37 +134,64 @@ Failed required contract → `contract_failed`, dependents blocked, orchestrator
 
 | tool | purpose |
 |---|---|
+| `fleet_design` | draft a fleet DAG from plain-language requirements (planner agent → validated JSON + preview) |
 | `fleet_plan` | validate + preview a fleet definition (no launch) |
-| `fleet_launch` | launch (confirm gate, `skip_confirm` for unattended) |
-| `fleet_status` | live DAG status |
-| `fleet_pause` / `fleet_resume` | pause/resume loop fleets at iteration boundary |
-| `fleet_relaunch` | re-run a failed node (+ blocked downstream), optional model override |
-| `fleet_kill` | fleet-wide kill |
-| `fleet_report` | regenerate report.md |
+| `fleet_models` | list available model refs (provider/id) from the live registry — call before `fleet_plan` if you don't know exact model IDs |
+| `fleet_launch` | launch the planned fleet after user confirmation; `skip_confirm` for unattended runs |
+| `fleet_status` | live DAG status and text summary |
+| `fleet_continue` | resume a failed/killed fleet from current state without restarting completed nodes |
+| `fleet_pause` / `fleet_resume` | pause/resume loop fleets at the next iteration boundary |
+| `fleet_kill` | kill all, or kill a single node by worker id |
+| `fleet_relaunch` | re-run a failed/killed node and its blocked downstream; optional model override |
+| `fleet_add_node` | insert new workers into a running fleet mid-flight |
+| `fleet_edit` | edit a pending node's model/effort/task, or fleet config mid-run |
+| `fleet_report` | regenerate the fleet markdown report |
+| `fleet_canvas` | open a browser canvas; `?demo=1` shows synthetic data for UI iteration |
+
+`/fleet viz | status | clear | pause | resume | continue | kill all|<node_id> | relaunch <id> [model] | add <json> | edit <node_id>|config ... | configure [show|set k v] | canvas [open|url|stop]`
+
+## Runtime mutation
+
+Fleets are not frozen after launch. You can kill a single stuck node, relaunch it with a stronger model, edit a pending node's task, or inject new workers with `fleet_add_node`. Inserted nodes validate against the existing DAG (unique ids, acyclic, loop-gate rules) and start dispatching as soon as their dependencies complete.
+
+## Preferences
 
-`/fleet viz | status | clear | pause | resume | relaunch <id> [model] | kill all`
+Set fleet-wide defaults in `~/.pi/agent/fleet.json`:
+
+```json
+{
+  "max_concurrent": 4,
+  "model": "gpt-5.4-mini",
+  "effort": "medium",
+  "warn_cost_usd": 10
+}
+```
+
+These are merged into `fleet_plan` results. Manage them with `/fleet configure show | set <key> <value>`.
 
 ## Records
 
-Everything lands in `.fleet/<name>-<ts>/` (git-ignored): `state.json` (single source of truth, atomic writes), per-worker `prompt.md` + `session.jsonl` + outputs, per-iteration archives, and a machine-written `report.md` with per-worker turns/tokens/cost, contract results, verdict history, and git diff stats.
+Everything lands in `.fleet/<name>-<ts>/` (git-ignored): `state.json` (single source of truth, atomic writes), per-worker `prompt.md` + `session.jsonl` + outputs, per-iteration archives, and a machine-written `report.md` with per-worker turns/tokens/cost, contract results, verdict history, and git diff stats. Completed nodes keep their stats visible in the canvas and report after the fleet ends.
 
-## Model selection
+## Model selection and effort
 
-Fleet-wide default via `config.model`; per-node override via `worker.model`. Any model pi can resolve — including any provider pi is logged into. Cheap models for trivial writers, strong models for reviewers:
+Fleet-wide default via `config.model` and `config.effort`; per-node override via `worker.model` and `worker.effort`. Any model pi can resolve works, including any provider pi is logged into. Cheap models for trivial writers, strong models for reviewers:
 
 ```json
-{ "id": "reviewer", "type": "reviewer", "model": "kimi-coding/k3", … }
+{ "id": "reviewer", "type": "reviewer", "model": "kimi-coding/k3", "effort": "high" }
 ```
 
+Model refs are validated at plan and launch time so bad names fail fast. There is no baked-in default provider: the extension uses whatever pi has configured.
+
 ## Development
 
 ```bash
 npm install
-npm test          # 111 tests, zero-API (fake session factory)
+npm test          # 274 tests, zero-API (fake session factory)
 npm run typecheck
 ```
 
-Design docs live in `docs/superpowers/specs/`; experiment history in `docs/experiments/`.
+Design docs are archived locally under `.archive/docs/superpowers/` (not tracked); experiment history in `docs/experiments/`.
 
 ## License
 

package/examples/json-number-pipeline.json

@@ -0,0 +1,35 @@
+{
+  "fleet_name": "json-number-pipeline",
+  "type": "dag",
+  "config": { "max_concurrent": 2 },
+  "workers": [
+    {
+      "id": "write-numbers",
+      "type": "write",
+      "task": "Write output/numbers.json containing exactly {\"values\":[3,5,8]}. No markdown. No commentary.",
+      "depends_on": [],
+      "outputs": [{ "path": "output/numbers.json", "kind": "json", "required": true, "schema": { "required_keys": ["values"], "number_keys": ["values"] } }]
+    },
+    {
+      "id": "add-numbers",
+      "type": "write",
+      "task": "Read output/numbers.json from write-numbers. Write output/sum.json containing {\"operation\":\"add\",\"result\":16}.",
+      "depends_on": ["write-numbers"],
+      "outputs": [{ "path": "output/sum.json", "kind": "json", "required": true, "schema": { "required_keys": ["operation", "result"], "number_keys": ["result"] } }]
+    },
+    {
+      "id": "subtract-numbers",
+      "type": "write",
+      "task": "Read output/numbers.json from write-numbers. Write output/difference.json containing {\"operation\":\"subtract\",\"result\":-10} using first value minus the rest.",
+      "depends_on": ["write-numbers"],
+      "outputs": [{ "path": "output/difference.json", "kind": "json", "required": true, "schema": { "required_keys": ["operation", "result"], "number_keys": ["result"] } }]
+    },
+    {
+      "id": "synthesize",
+      "type": "write",
+      "task": "Read output/sum.json and output/difference.json. Write output/final.json containing {\"sum\":16,\"difference\":-10,\"combined\":6} where combined = sum + difference.",
+      "depends_on": ["add-numbers", "subtract-numbers"],
+      "outputs": [{ "path": "output/final.json", "kind": "json", "required": true, "schema": { "required_keys": ["sum", "difference", "combined"], "number_keys": ["sum", "difference", "combined"] } }]
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-agent-fleet",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "DAG-of-agents fleets for pi — parallel workers with contracts, reviewer-gated iteration loops, and live progress",
   "type": "module",
   "scripts": {
@@ -23,7 +23,8 @@
   "pi": {
     "extensions": [
       "./src/index.ts"
-    ]
+    ],
+    "image": "https://raw.githubusercontent.com/sagarsrc/pi-agent-fleet/v0.5.0/assets/canvas.png"
   },
   "license": "MIT",
   "author": "Sagar Sarkale",
@@ -45,8 +46,15 @@
   ],
   "files": [
     "src/",
+    "assets/",
     "examples/",
     "README.md",
     "LICENSE"
-  ]
+  ],
+  "dependencies": {
+    "@xyflow/react": "^12.11.2",
+    "esbuild": "^0.21.5",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8"
+  }
 }