pi-agent-fleet 0.2.0 → 0.4.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,51 @@ 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`.
-
-## Fleet modes
+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. Watch the live widget or open the browser canvas; read the report at `.fleet/<name>-<ts>/report.md`.
 
-**One-shot DAG** — static dependency graph, parallel layers, contracts at exit:
+## 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 live widget.
+- `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 +99,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 +112,8 @@ 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 |
+| `yaml` | parses as YAML |
 
 Failed required contract → `contract_failed`, dependents blocked, orchestrator notified. No silent passes.
 
@@ -85,33 +121,58 @@ 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_launch` | launch the planned fleet after user confirmation; `skip_confirm` for unattended runs |
+| `fleet_status` | live DAG status and widget lines |
+| `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 | relaunch <id> [model] | kill all`
+`/fleet viz | status | clear | pause | resume | 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
+
+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 widget 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          # 232 tests, zero-API (fake session factory)
 npm run typecheck
 ```
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-agent-fleet",
-  "version": "0.2.0",
-  "description": "DAG-of-agents fleets for pi \u2014 parallel workers with contracts, reviewer-gated iteration loops, and live progress",
+  "version": "0.4.0",
+  "description": "DAG-of-agents fleets for pi — parallel workers with contracts, reviewer-gated iteration loops, and live progress",
   "type": "module",
   "scripts": {
     "test": "vitest run",
@@ -9,21 +9,22 @@
     "typecheck": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "*",
     "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
     "typebox": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.80.0",
     "@earendil-works/pi-ai": "^0.80.0",
+    "@earendil-works/pi-coding-agent": "^0.80.0",
+    "@types/node": "^22.0.0",
     "typescript": "^5.5.0",
-    "vitest": "^2.1.0",
-    "@types/node": "^22.0.0"
+    "vitest": "^2.1.0"
   },
   "pi": {
     "extensions": [
       "./src/index.ts"
-    ]
+    ],
+    "image": "https://raw.githubusercontent.com/sagarsrc/pi-agent-fleet/v0.4.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"
+  }
 }