@arhen/pi-core-subagent 1.3.1 → 1.3.3

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:
 
@@ -132,7 +234,7 @@ Background + intercom:
 
 | Tool | Purpose |
 |---|---|
-| `subagent` | single / `tasks` (parallel or graph via `needs`) / `chain` (`{previous}`); `background:true` fire-and-forget; `allowIntercom:true` enables child talk tools; `notifyPerTask: true` wakes you as each task completes (default off) |
+| `subagent` | single / `tasks` (parallel or graph via `needs`) / `chain` (`{previous}`); `background:true` fire-and-forget; `allowIntercom:true` enables child talk tools; `notifyPerTask: true` wakes you as each task completes (background runs only; default off) |
 | `subagent_status` | live per-task snapshot (non-blocking), including each child's session file path |
 | `subagent_result` | full output of a run or one task |
 | `await_subagent` | block until a run finishes (optional `timeoutMs`) |
@@ -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.1",
+  "version": "1.3.3",
   "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/child.ts

@@ -100,7 +100,7 @@ export function createChildTools(taskId: string, handlers: ChildHandlers): ToolD
 					.map((m) => `from ${m.from}: ${m.text}`)
 					.join("\n");
 				const capped = body.length > 4000 ? body.slice(0, 4000).replace(/[\uD800-\uDBFF]$/, "") : body; // multibyte-safe
-				return { content: [{ type: "text" as const, text: body }], details: { messages } };
+				return { content: [{ type: "text" as const, text: capped }], details: { messages } };
 			},
 		},
 	];

package/src/index.ts

@@ -17,7 +17,7 @@ import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
 import { StringEnum, type Api, type AssistantMessage, type Model } from "@earendil-works/pi-ai";
 import { Text, truncateToWidth } from "@earendil-works/pi-tui";
 import type { Component, TUI } from "@earendil-works/pi-tui";
-import { Type } from "typebox";
+import { Type, type Static } from "typebox";
 import { join } from "node:path";
 import { CHILD_TALK_TOOLS, createChildTools, createWatchdog, type ChildHandlers } from "./child.ts";
 import { createMailbox, type Mailbox } from "./mailbox.ts";
@@ -50,24 +50,6 @@ interface UsageStats {
 	turns: number;
 }
 
-interface TaskInput {
-	id?: string;
-	/** Name the leader invents for this subagent (display + mailbox addressing). */
-	agent: string;
-	task: string;
-	/** Task ids this task depends on. The edge carries the upstream output into this prompt. */
-	needs?: string[];
-	/** System prompt the leader writes for this agent. Optional — a minimal default is used. */
-	prompt?: string;
-	/** true = write toolset; false/omitted = read-only toolset. */
-	write?: boolean;
-	tools?: string[];
-	model?: string;
-	thinking?: string;
-	cwd?: string;
-	maxRuntimeMs?: number;
-}
-
 interface TaskSnapshot {
 	id: string;
 	runId: string;
@@ -1215,25 +1197,31 @@ class SubagentManager {
 	awaitRun(runId: string, timeoutMs?: number): Promise<RunSnapshot | undefined> {
 		const run = this.runs.get(runId);
 		if (!run) return Promise.resolve(undefined);
-		run.awaited = true;
-		if (TERMINAL.includes(run.status)) return Promise.resolve(cloneRun(run));
+		if (TERMINAL.includes(run.status)) {
+			run.awaited = true;
+			return Promise.resolve(cloneRun(run));
+		}
 		const settled = new Promise<RunSnapshot | undefined>((resolve) => {
 			const prev = this.settlers.get(runId);
 			this.settlers.set(runId, (r) => {
 				prev?.(r);
 				resolve(r);
 			});
-			// Settle may have run between the terminal check and wiring.
-			if (TERMINAL.includes(run.status)) resolve(cloneRun(run));
 		});
-		if (!timeoutMs) return settled;
-		return Promise.race([
-			settled,
-			new Promise<RunSnapshot | undefined>((resolve) => {
-				const timer = setTimeout(() => resolve(this.runs.get(runId) ? cloneRun(this.runs.get(runId)!) : undefined), timeoutMs);
-				settled.then(() => clearTimeout(timer));
-			}),
-		]);
+		if (timeoutMs) {
+			return Promise.race([
+				settled,
+				new Promise<RunSnapshot | undefined>((resolve) => {
+					const timer = setTimeout(() => resolve(this.runs.get(runId) ? cloneRun(this.runs.get(runId)!) : undefined), timeoutMs);
+					settled.then(() => clearTimeout(timer));
+				}),
+			]);
+		}
+		// Awaiting to completion: parent gets the real result, so suppress the
+		// completion notice. On timeout we resolve a snapshot and leave awaited
+		// unset, so the parent still receives the completion notification.
+		run.awaited = true;
+		return settled;
 	}
 }
 
@@ -1255,29 +1243,13 @@ const TaskItem = Type.Object({
 	needs: Type.Optional(Type.Array(Type.String(), { description: "Ids of tasks this one waits for; their outputs are prepended to this prompt." })),
 });
 
-type SubagentParamsShape = {
-	agent?: string;
-	task?: string;
-	prompt?: string;
-	write?: boolean;
-	tasks?: TaskInput[];
-	chain?: TaskInput[];
-	model?: string;
-	thinking?: string;
-	cwd?: string;
-	tools?: string[];
-	concurrency?: number;
-	maxRuntimeMs?: number;
-	background?: boolean;
-	allowIntercom?: boolean;
-	notifyPerTask?: boolean;
-};
 
 const SubagentParams = Type.Object({
 	agent: Type.Optional(Type.String({ minLength: 1, description: "Name you invent for this subagent (single mode)" })),
 	task: Type.Optional(Type.String({ minLength: 1, description: "Task (single mode)" })),
 	prompt: Type.Optional(Type.String({ description: "System prompt for this agent (single mode)" })),
 	write: Type.Optional(Type.Boolean({ description: "true = write toolset; default false = read-only (single mode)" })),
+	tools: Type.Optional(Type.Array(Type.String(), { description: "Explicit tool allowlist (overrides the toolset) (single mode)" })),
 	tasks: Type.Optional(Type.Array(TaskItem, { description: "Parallel tasks" })),
 	chain: Type.Optional(Type.Array(TaskItem, { description: "Sequential tasks; {previous} = prior output" })),
 	model: Type.Optional(Type.String({ description: "Model override (single mode)" })),
@@ -1286,10 +1258,14 @@ const SubagentParams = Type.Object({
 	concurrency: Type.Optional(Type.Number({ description: `Parallel concurrency (default ${DEFAULT_CONCURRENCY}, max ${MAX_CONCURRENCY})` })),
 	maxRuntimeMs: Type.Optional(Type.Number({ description: "Per-task timeout, ms. Omit for no cap (default): tasks run until done, stalled, or user-aborted." })),
 	background: Type.Optional(Type.Boolean({ description: "Fire-and-forget: return immediately with a runId; you'll be notified on completion" })),
-	notifyPerTask: Type.Optional(Type.Boolean({ description: "Wake you (queued follow-up turn) as each task completes, even mid-run. Default false." })),
+	notifyPerTask: Type.Optional(Type.Boolean({ description: "Wake you (queued follow-up turn) as each task completes — background runs only, since blocking runs can't be woken mid-tool. Default false." })),
 	allowIntercom: Type.Optional(Type.Boolean({ description: "Let children ask you questions, notify you, and message sibling subagents" })),
 });
 
+/** Derived from the schemas — single source of truth, no hand-maintained mirror. */
+type TaskInput = Static<typeof TaskItem>;
+type SubagentParamsShape = Static<typeof SubagentParams>;
+
 const RunIdParam = Type.Object({ runId: Type.String({ description: "Run id from subagent()" }) });
 const ResultParam = Type.Object({
 	runId: Type.String(),
@@ -1391,7 +1367,7 @@ export default function (pi: ExtensionAPI) {
 		parameters: SubagentParams,
 		executionMode: "parallel", // sibling subagent calls run concurrently, not serialized
 		async execute(_toolCallId, params, signal, onUpdate, ctx) {
-			const typed = params as unknown as SubagentParamsShape;
+			const typed = params as SubagentParamsShape;
 			if (typed.background) {
 				const details = manager.startInBackground(typed, ctx);
 				return {