@arhen/pi-core-subagent 1.3.0 → 1.3.2

package/README.md

@@ -14,6 +14,21 @@ One rule underneath everything else:
 
 That is [Graph Protocol](#graph-protocol), applied to the runtime rather than to the prompt.
 
+```mermaid
+flowchart LR
+    subgraph w1["wave 1 — runs in parallel"]
+        api["api<br/><i>api-mapper</i>"]
+        db["db<br/><i>db-mapper</i>"]
+    end
+    gate{{"gate"}}
+    subgraph w2["wave 2"]
+        doc["doc<br/><i>writer</i>"]
+    end
+    api -- "route map" --> gate
+    db -- "schema map" --> gate
+    gate -- "both outputs<br/>prepended to the prompt" --> doc
+```
+
 ![Subagents widget](docs/subagents-widget.png)
 
 *The `subagent` tool call plus the live above-editor widget: per-agent activity, tool counts, turns, token counters and timers.*
@@ -33,6 +48,29 @@ That is [Graph Protocol](#graph-protocol), applied to the runtime rather than to
 - **No silent hangs** — watchdog aborts children that produce no events for 3 minutes.
 - **No default runtime cap** — tasks run until done, stalled (watchdog), or aborted by the user. `maxRuntimeMs` is opt-in (default 0 = unlimited).
 
+## How it runs
+
+Children are not subprocesses. They are separate `AgentSession`s inside the same pi process — which is why spawning is instant, and why a child's transcript never lands in your context:
+
+```mermaid
+flowchart TB
+    subgraph proc["one OS process — no spawn, no IPC"]
+        direction TB
+        L["<b>leader</b><br/>your session, your context"]
+        subgraph kids["isolated child sessions"]
+            direction LR
+            A["api-mapper"]
+            B["db-mapper"]
+        end
+    end
+    L -- "task text in" --> A
+    L -- "task text in" --> B
+    A -. "final answer only" .-> L
+    B -. "final answer only" .-> L
+```
+
+The dotted arrows are the whole point: a child may burn 200k tokens reading files, and the leader receives only its final answer.
+
 ## Install
 
 ```sh
@@ -103,18 +141,82 @@ subagent graph 3
 
 `✎` marks a write-toolset task; `←` lists its edges. With no `needs` anywhere the wave line is omitted entirely.
 
-What the edge does:
+### What one edge does
+
+An edge is not just ordering. It is a delivery:
+
+```mermaid
+sequenceDiagram
+    participant S as scheduler
+    participant A as api
+    participant D as db
+    participant W as doc
+
+    Note over S,D: wave 1 — both start together
+    S->>A: "Map every route in src/api/"
+    S->>D: "Map the schema in src/db/"
+    A-->>S: route map
+    Note right of W: doc is queued,<br/>waiting at the gate
+    D-->>S: schema map
+    Note over S: gate opens: every need settled
+    S->>W: ## Output of api<br/>&lt;route map&gt;<br/><br/>## Output of db<br/>&lt;schema map&gt;<br/>---<br/>"Write ARCHITECTURE.md…"
+```
+
+The leader never copies those outputs into the prompt — so it cannot forget to.
+
+### One scheduler, four shapes
+
+Single, parallel, chain and graph are not four code paths. They are four shapes of the same wave loop:
+
+```mermaid
+flowchart LR
+    subgraph one["single"]
+        direction TB
+        s1(("a"))
+    end
+    subgraph par["parallel — no needs"]
+        direction TB
+        p1(("a")) ~~~ p2(("b")) ~~~ p3(("c"))
+    end
+    subgraph ch["chain — needs: [previous]"]
+        direction TB
+        c1(("a")) --> c2(("b")) --> c3(("c"))
+    end
+    subgraph gr["graph — needs"]
+        direction TB
+        g1(("a")) --> g2(("b"))
+        g1 --> g3(("c"))
+        g2 --> g4(("d"))
+        g3 --> g4
+    end
+```
+
+### The loop
+
+```mermaid
+flowchart TD
+    start(["subagent call"]) --> validate{"graph valid?<br/><small>unknown id · self-edge · cycle</small>"}
+    validate -- no --> reject["reject the call<br/><b>zero children spawned</b>"]
+    validate -- yes --> loop{"tasks left?"}
+    loop -- no --> done(["run finished"])
+    loop -- yes --> ready["frontier =<br/>tasks whose needs are all settled"]
+    ready --> spawn["run that wave in parallel<br/><small>throttled by concurrency</small>"]
+    spawn --> collect["record each output<br/>mark tasks settled"]
+    collect --> loop
+```
+
+Two consequences worth stating plainly:
 
-- **Gates** — `doc` starts only after both `api` and `db` finish.
-- **Carries** — `api`'s and `db`'s outputs are prepended to `doc`'s prompt as `## Output of api` / `## Output of db`. You do not pass them yourself, and you cannot forget to.
-- **Skips on breakage** — if an upstream fails or is aborted, dependents are marked aborted instead of running against a prompt with a hole in it.
+- **A bad graph costs nothing.** Validation happens before the first spawn, never halfway through with three children already burning tokens.
+- **A broken upstream stops its branch.** If a need fails or is aborted, its dependents are marked aborted rather than run against a prompt with a hole in it:
 
-Rules:
+```mermaid
+flowchart LR
+    api["api ✓"] --> doc
+    db["db ✗ failed"] --> doc["doc ⏹ skipped<br/><small>never spawned</small>"]
+```
 
-- Tasks with no unmet `needs` run together, throttled by `concurrency`.
-- Unknown ids, self-edges and cycles are rejected **before any child spawns**.
-- `chain` is exactly `needs: [previous]` — same scheduler, kept for convenience. `{previous}` still expands.
-- Zero `needs` anywhere = plain parallel. No ceremony added to flat fan-out.
+And the rule that keeps this from becoming ceremony: **zero `needs` anywhere = plain parallel.** No waves, no gates, no graph vocabulary imposed on flat work.
 
 Background + intercom:
 
@@ -163,7 +265,16 @@ Read-only pane over the session's subagents:
 
 ## Watching a child from outside
 
-`subagent_status` returns each running child's session file (JSONL). Children are `AgentSession`s in this process — they have no TTY — but their transcript is a real file, so any external viewer can follow one:
+A child has no terminal of its own — but it does write a real transcript file, and that file is the seam every external viewer can use:
+
+```mermaid
+flowchart LR
+    child["child session<br/><small>no TTY</small>"] -- writes --> file[("session.jsonl")]
+    file -- "peek · enter" --> pane["in-pi tail"]
+    file -- "tail -f" --> term["any terminal pane<br/><small>herdr · tmux · zellij</small>"]
+```
+
+`subagent_status` returns that path for every running child:
 
 ```sh
 tail -f /path/from/subagent_status.jsonl
@@ -212,6 +323,16 @@ The protocol asks the coordinator to compare the delegated subgraph against the
 - Across 9,876 τ2-bench and 1,879 AppWorld trajectories, "false success" reached **75.8%** of self-assessing coding-agent failures; adding an LLM judge scored **0.54–0.65 AUROC** (0.5 = coin flip). ([arXiv:2606.09863](https://doi.org/10.48550/arxiv.2606.09863))
 - LLM judges reading agent traces can be flipped by rewriting the trace — the exact surface a self-reported graph exposes. ([arXiv:2601.14691](https://arxiv.org/html/2601.14691))
 
+The shape of the problem:
+
+```mermaid
+flowchart TD
+    W["worker finishes"] --> Q{"who says it's correct?"}
+    Q -- "the worker itself" --> S["self-report<br/><b>0 of 34 caught</b><br/><small>at 90–100 confidence</small>"]
+    Q -- "another model reading the trace" --> J["LLM judge<br/><b>0.54–0.65 AUROC</b><br/><small>0.5 = coin flip</small>"]
+    Q -- "the machine" --> D["exit code + git diff<br/><b>34 of 34 caught</b>"]
+```
+
 So §9 in practice is two things you already have:
 
 ```sh

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arhen/pi-core-subagent",
-  "version": "1.3.0",
+  "version": "1.3.2",
   "type": "module",
   "description": "pi extension: fast in-process subagents with a dependency-graph scheduler (needs edges gate tasks and carry upstream output into dependent prompts), plus background runs, intercom and agent-to-agent mailbox. Leader defines agents inline.",
   "license": "MIT",

package/src/index.ts

@@ -1252,12 +1252,7 @@ const TaskItem = Type.Object({
 	cwd: Type.Optional(Type.String({ description: "Working directory for this task. Default: current project." })),
 	tools: Type.Optional(Type.Array(Type.String(), { description: "Explicit tool allowlist (overrides the toolset)" })),
 	maxRuntimeMs: Type.Optional(Type.Number({ description: "Per-task timeout (ms)" })),
-	needs: Type.Optional(
-		Type.Array(Type.String(), {
-			description:
-				"Task ids this task depends on (requires those tasks to declare id). It starts only after they finish, and their outputs are prepended to its prompt. Tasks with no unmet needs run together as a wave.",
-		}),
-	),
+	needs: Type.Optional(Type.Array(Type.String(), { description: "Ids of tasks this one waits for; their outputs are prepended to this prompt." })),
 });
 
 type SubagentParamsShape = {
@@ -1380,18 +1375,18 @@ export default function (pi: ExtensionAPI) {
 	pi.registerTool<typeof SubagentParams, RunDetails>({
 		name: "subagent",
 		label: "Subagent",
-		description: "Define and run isolated subagents (own context, own session). You invent the agent: name, optional system prompt, toolset (read-only default, write:true for edits). Modes: single, parallel (tasks), chain ({previous}). Tasks with `needs` form a dependency graph: each wave of tasks with satisfied needs runs in parallel, and an upstream task's output is prepended to its dependents' prompts. background:true fire-and-forgets with completion notice. allowIntercom:true lets children ask you questions and message each other.\n\nExamples (copy these shapes):\nSingle: subagent({ agent: \"reviewer\", prompt: \"You review code for correctness\", task: \"Review src/auth.ts\" })\nParallel: subagent({ tasks: [{ agent: \"mapper\", task: \"Map all API routes\" }, { agent: \"critic\", task: \"Review auth for vulnerabilities\" }] })\nGraph: subagent({ tasks: [{ id: \"api\", agent: \"api-mapper\", task: \"Map API routes\" }, { id: \"db\", agent: \"db-mapper\", task: \"Map DB schema\" }, { id: \"doc\", agent: \"writer\", needs: [\"api\", \"db\"], write: true, task: \"Write ARCHITECTURE.md. Verify: test -s ARCHITECTURE.md\" }] })\nChain: subagent({ chain: [{ agent: \"planner\", task: \"Plan the change\" }, { agent: \"doer\", write: true, task: \"Execute: {previous}\" }] })\nBackground: subagent({ agent: \"auditor\", task: \"Audit deps\", background: true })",
+		// ponytail: this string is billed on every request. One example — the graph one —
+		// covers ids, needs, write and Verify; the simpler shapes are subsets of it.
+		description:
+			"Run isolated subagents (own context, own session). You invent each agent: name, optional system prompt, toolset (read-only default, write:true to edit). Use `agent`+`task` for one, `tasks` for many. `needs` declares dependency edges: a task waits for its needs and receives their outputs prepended to its prompt. background:true returns immediately; allowIntercom:true lets children talk to you and each other.\n\nsubagent({ tasks: [{ id: \"api\", agent: \"api-mapper\", task: \"Map API routes\" }, { id: \"db\", agent: \"db-mapper\", task: \"Map DB schema\" }, { id: \"doc\", agent: \"writer\", needs: [\"api\", \"db\"], write: true, task: \"Write ARCHITECTURE.md. Verify: test -s ARCHITECTURE.md\" }] })",
 		promptSnippet: "Define and delegate work to specialized subagents.",
 		promptGuidelines: [
 			"Use subagent when independent review, testing, research, or parallel analysis improves quality.",
-			"Decompose parallelizable work: if the request has 2+ independent sub-tasks (separate files, separate concerns, independent research/review), spawn N agents with a SINGLE call: subagent({ tasks: [{agent, task}, ...] }). NEVER make multiple parallel subagent calls for parallel work — one call, one run, N tasks.",
-			"If independent sub-tasks are sequential (each builds on the previous one's output), use chain mode with {previous}.",
-			"When some tasks depend on others but not all do, give tasks an `id` and list `needs`. Independent tasks then still run in parallel while dependents wait, and each dependent receives its upstream outputs automatically — do not re-describe them in the prompt.",
-			"Give every task a way to check itself: end the task text with a runnable command, e.g. 'Verify: npx tsc --noEmit && bun test'. A subagent's own claim of success is not evidence.",
-			"Define each subagent yourself: an invented name, a focused system prompt (prompt:), and a toolset — read-only (default) or write (write:true).",
-			"Prefer read-only subagents unless the task explicitly needs edits.",
-			"Use background:true for long-running work; you'll be notified on completion.",
-			"Use allowIntercom:true only when a child may need to ask you something; keep children autonomous otherwise.",
+			"Put every sub-task in ONE call: subagent({ tasks: [...] }). Never make multiple parallel subagent calls — one call, one run, N tasks.",
+			"Order comes from `needs`, not from separate calls: give tasks an `id`, list the ids each depends on. Tasks with no unmet needs run in parallel; dependents receive their upstream outputs automatically — do not restate them.",
+			"End each task with a runnable check, e.g. 'Verify: npx tsc --noEmit && bun test'. A subagent's claim of success is not evidence.",
+			"Define each agent yourself: invented name, focused system prompt, and read-only (default) or write:true. Prefer read-only.",
+			"Use background:true for long work; allowIntercom:true only when a child may need to ask you something.",
 		],
 		parameters: SubagentParams,
 		executionMode: "parallel", // sibling subagent calls run concurrently, not serialized