@arhen/pi-core-subagent 1.2.1 → 1.3.0

package/README.md

@@ -90,10 +90,19 @@ Chain — `{previous}` is replaced with the prior agent's output:
 }
 ```
 
+The call line renders the graph in §2 notation as the model types it:
+
 ```
-wave 1: api ∥ db     →  gate  →  wave 2: doc
+subagent graph 3
+  6 at a time
+  wave1[api ∥ db] → gate → wave2[doc]
+  api api-mapper Map every route in src/api/
+  db  db-mapper Map the schema in src/db/
+  doc writer ✎ ← api, db Write ARCHITECTURE.md from the maps above. Verify: test -s ARCHI…
 ```
 
+`✎` marks a write-toolset task; `←` lists its edges. With no `needs` anywhere the wave line is omitted entirely.
+
 What the edge does:
 
 - **Gates** — `doc` starts only after both `api` and `db` finish.
@@ -124,7 +133,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_status` | live per-task snapshot (non-blocking) |
+| `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`) |
 | `reply_subagent` | answer a child's `ask_parent` question |
@@ -152,6 +161,23 @@ Read-only pane over the session's subagents:
 - `x` then `y` — abort ONE subagent (only mutation; `n`/any other key cancels)
 - `esc` — close
 
+## 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:
+
+```sh
+tail -f /path/from/subagent_status.jsonl
+```
+
+In a terminal multiplexer, that is a pane per agent — e.g. with [Herdr](https://herdr.dev):
+
+```sh
+herdr pane split --current --direction right
+herdr pane run w1:p2 "tail -f /path/from/subagent_status.jsonl"
+```
+
+The extension has no multiplexer integration and does not want one: it exposes the path, your agent already knows how to drive its own terminal. For an in-pi view of the same stream, use [`/subagents peek`](#peek--subagents-peek-or-ctrlshifta).
+
 ## Context budget
 
 - Parent tools: 6 schemas with short descriptions. **No catalog, no context hook** — nothing injected per request.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arhen/pi-core-subagent",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "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

@@ -472,6 +472,33 @@ export function resolveNeeds(inputs: { id?: string; needs?: string[] }[], mode:
 	return edges;
 }
 
+/**
+ * Graph Protocol §2 notation: `wave1[api ∥ db] → gate → wave2[doc]`.
+ *
+ * Tolerates half-streamed args: a need pointing at an id that has not arrived yet
+ * keeps its task out of the ready set, so the layout settles as the model types.
+ * Returns "" when there are no edges — flat fan-out gets no graph vocabulary.
+ */
+export function waveNotation(tasks: { id?: string; needs?: string[] }[]): string {
+	if (!tasks.some((t) => t.needs?.length)) return "";
+	const ids = tasks.map((t, i) => t.id ?? `task_${i + 1}`);
+	const settled = new Set<string>();
+	let remaining = tasks.map((t, i) => ({ id: ids[i] as string, needs: t.needs ?? [] }));
+	const waves: string[][] = [];
+	while (remaining.length > 0) {
+		const ready = remaining.filter((t) => t.needs.every((n) => settled.has(n)));
+		if (ready.length === 0) break; // cycle, or an upstream id not typed yet
+		waves.push(ready.map((t) => t.id));
+		for (const t of ready) settled.add(t.id);
+		remaining = remaining.filter((t) => !settled.has(t.id));
+	}
+	if (remaining.length > 0) waves.push(remaining.map((t) => t.id)); // show them rather than drop them
+	if (waves.length < 2) return "";
+	const full = waves.map((w, i) => `wave${i + 1}[${w.join(" ∥ ")}]`).join(" → gate → ");
+	// Long graphs: keep the shape, drop the names.
+	return full.length <= 100 ? full : waves.map((w, i) => `wave${i + 1}[${w.length}]`).join(" → gate → ");
+}
+
 /**
  * Graph Protocol §6: the edge carries the upstream output, not just ordering.
  * Upstream results are prepended verbatim; `{previous}` stays supported so old
@@ -1402,6 +1429,8 @@ export default function (pi: ExtensionAPI) {
 			if (args.concurrency) parts.push(`${args.concurrency} at a time`);
 			if (args.maxRuntimeMs) parts.push(`${Math.round(args.maxRuntimeMs / 60000)}m limit`);
 			const params = parts.length > 0 ? `\n  ${theme.fg("dim", parts.join(" · "))}` : "";
+			const notation = waveNotation(tasks);
+			const graphLine = notation ? `\n  ${theme.fg("muted", notation)}` : "";
 			// The plan the model actually wrote: ids, edges, toolset. Streams in as args arrive,
 			// so a graph is visible before the first child spawns.
 			const plan = tasks
@@ -1416,7 +1445,7 @@ export default function (pi: ExtensionAPI) {
 					return `\n  ${theme.fg("muted", id)} ${theme.fg("accent", t.agent ?? "…")}${mark}${edge}${what}`;
 				})
 				.join("");
-			return new Text(`${theme.fg("toolTitle", theme.bold("subagent"))} ${theme.fg("accent", mode)}${flags ? ` ${theme.fg("muted", `[${flags}]`)}` : ""}${params}${plan}`, 0, 0);
+			return new Text(`${theme.fg("toolTitle", theme.bold("subagent"))} ${theme.fg("accent", mode)}${flags ? ` ${theme.fg("muted", `[${flags}]`)}` : ""}${params}${graphLine}${plan}`, 0, 0);
 		},
 		renderResult(result, { expanded }, theme) {
 			const run = result.details?.run;
@@ -1444,14 +1473,18 @@ export default function (pi: ExtensionAPI) {
 	pi.registerTool<typeof RunIdParam, { run?: RunSnapshot }>({
 		name: "subagent_status",
 		label: "Subagent Status",
-		description: "Live status of a subagent run (non-blocking): per-task state.",
+		description: "Live status of a subagent run (non-blocking): per-task state, plus each child's session file path (JSONL) so you can tail it from outside — e.g. in a terminal multiplexer pane.",
 		promptSnippet: "Check progress of a subagent run.",
 		parameters: RunIdParam,
 		async execute(_id, params) {
 			const { runId } = params as { runId: string };
 			const run = manager.getRun(runId);
 			if (!run) return { content: [{ type: "text", text: `Unknown runId: ${runId}` }], isError: true, details: {} };
-			return { content: [{ type: "text", text: compactLines(run).join("\n") }], details: { run: cloneRun(run) } };
+			// Session file paths are the one primitive an outside tool needs: `tail -f` it in a
+			// multiplexer pane, a log viewer, anything. Cheaper than owning a pane integration.
+			const files = run.tasks.filter((t) => t.sessionFile).map((t) => `${t.id} (${t.agent}): ${t.sessionFile}`);
+			const text = [compactLines(run).join("\n"), ...(files.length > 0 ? ["", "Live session files (tail -f to watch):", ...files] : [])].join("\n");
+			return { content: [{ type: "text", text }], details: { run: cloneRun(run) } };
 		},
 	});