@workweave/router 0.1.8 → 0.2.1

package/pi-router/src/config.ts

@@ -0,0 +1,261 @@
+/**
+ * Environment, routing-knob presets, identity, and the static per-process
+ * header policy shared by every part of the extension.
+ *
+ * The whole design hinges on one pi constraint: `before_provider_request` can
+ * mutate the request body but cannot set HTTP headers (headers bind when the
+ * Anthropic client is created, before the hook runs). So routing-knob headers
+ * are *static per provider config*, i.e. static per process. Subagents are
+ * separate processes, which is exactly why "quality for the main loop, speed
+ * for subagents" maps cleanly onto process identity (`WEAVE_PI_SUBAGENT`).
+ */
+
+import { execFileSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import type { ProviderModelConfig } from "@mariozechner/pi-coding-agent";
+
+/** Provider name. NOT "anthropic" — overriding the built-in provider hijacks the Claude OAuth token. */
+export const PROVIDER_NAME = "weave";
+
+export type Role = "main" | "subagent";
+
+/** Children spawned by the dispatch tool run with WEAVE_PI_SUBAGENT=1. */
+export function isSubagent(): boolean {
+	return process.env.WEAVE_PI_SUBAGENT === "1";
+}
+
+export function getRole(): Role {
+	return isSubagent() ? "subagent" : "main";
+}
+
+function numEnv(name: string, fallback: number): number {
+	const raw = process.env[name];
+	if (raw === undefined || raw.trim() === "") return fallback;
+	const n = Number(raw);
+	return Number.isFinite(n) ? n : fallback;
+}
+
+// ---------- router endpoint ----------
+
+/**
+ * Router base URL — the ROOT, with no /v1 and no trailing slash. pi's
+ * anthropic-messages provider uses @anthropic-ai/sdk, which appends /v1/messages
+ * to this; a trailing /v1 would produce /v1/v1/messages and 404. Order:
+ * WEAVE_ROUTER_URL env (children inherit it), then the installer-written
+ * models.json baseUrl (so the extension always agrees with however the user
+ * installed — hosted, --local, or custom), then the local default. Without the
+ * models.json fallback, a hosted install with no env var would be silently
+ * re-pointed at localhost. The /v1 strip on the models.json value keeps installs
+ * written by an older installer (which appended /v1) working after an update.
+ */
+export function getRouterBaseUrl(): string {
+	const env = process.env.WEAVE_ROUTER_URL?.trim();
+	if (env) return env.replace(/\/v1\/?$/, "").replace(/\/+$/, "");
+	const fromModels = readWeaveProvider().baseUrl?.trim();
+	if (fromModels) return fromModels.replace(/\/v1\/?$/, "").replace(/\/+$/, "");
+	return "http://localhost:8080";
+}
+
+// ---------- router key resolution ----------
+
+/** Agent config dir, honoring PI_CODING_AGENT_DIR (set for project-scope installs). */
+function getAgentDir(): string {
+	const env = process.env.PI_CODING_AGENT_DIR?.trim();
+	if (env) return env.startsWith("~/") ? path.join(os.homedir(), env.slice(2)) : env;
+	return path.join(os.homedir(), ".pi", "agent");
+}
+
+export function getKeyFilePath(): string {
+	return process.env.WEAVE_ROUTER_KEY_FILE?.trim() || path.join(getAgentDir(), ".weave_router_key");
+}
+
+interface WeaveProviderConfig {
+	baseUrl?: string;
+	apiKey?: string;
+}
+
+let cachedWeaveProvider: WeaveProviderConfig | undefined;
+
+/** Read the installer-written `weave` provider block from models.json (cached). */
+function readWeaveProvider(): WeaveProviderConfig {
+	if (cachedWeaveProvider) return cachedWeaveProvider;
+	let result: WeaveProviderConfig = {};
+	try {
+		const raw = fs.readFileSync(path.join(getAgentDir(), "models.json"), "utf-8");
+		const parsed = JSON.parse(raw) as { providers?: { weave?: WeaveProviderConfig } };
+		result = parsed.providers?.weave ?? {};
+	} catch {
+		/* no models.json — fall through to env/defaults */
+	}
+	// Cache only a successful, non-empty read. An empty result (file missing or no
+	// weave block yet) must not be cached forever — a later install/write should be
+	// picked up on the next call.
+	if (result.baseUrl || result.apiKey) cachedWeaveProvider = result;
+	return result;
+}
+
+/** Router key from WEAVE_ROUTER_KEY, else the installer-written key file, else models.json. */
+export function resolveRouterKey(): string | undefined {
+	const envKey = process.env.WEAVE_ROUTER_KEY?.trim();
+	if (envKey) return envKey;
+	try {
+		const contents = fs.readFileSync(getKeyFilePath(), "utf-8").trim();
+		if (contents) return contents;
+	} catch {
+		/* no key file — fall through */
+	}
+	return readWeaveProvider().apiKey?.trim() || undefined;
+}
+
+// ---------- identity ----------
+
+export interface Identity {
+	email?: string;
+	name?: string;
+}
+
+function gitConfig(key: string): string | undefined {
+	try {
+		const out = execFileSync("git", ["config", "--get", key], {
+			encoding: "utf-8",
+			stdio: ["ignore", "pipe", "ignore"],
+		}).trim();
+		return out || undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+let cachedIdentity: Identity | undefined;
+
+/** Resolve user identity the same way the installer does: env overrides, then git config. */
+export function resolveIdentity(): Identity {
+	if (cachedIdentity) return cachedIdentity;
+	const email = process.env.WEAVE_USER_EMAIL?.trim() || gitConfig("user.email");
+	const name = process.env.WEAVE_USER_NAME?.trim() || gitConfig("user.name");
+	cachedIdentity = { email: email || undefined, name: name || undefined };
+	return cachedIdentity;
+}
+
+// ---------- routing-knob presets ----------
+
+export interface Knobs {
+	alpha: number;
+	speedWeight: number;
+	outputCostRatio: number;
+	expectedOutputTokens: number;
+}
+
+// Validated against the scorer: alpha + speedWeight <= 1.
+//   main:       0.80 + 0.05 = 0.85  (quality-biased; first turn pins a high tier)
+//   subagent:   0.25 + 0.45 = 0.70  (speed + cheap fan-out, isolated session)
+//   compaction: 0.05 + 0.55 = 0.60  (cheapest — summarization is throwaway)
+const MAIN_LOOP_KNOBS: Knobs = { alpha: 0.8, speedWeight: 0.05, outputCostRatio: 0.5, expectedOutputTokens: 3000 };
+const FAST_CHEAP_KNOBS: Knobs = { alpha: 0.25, speedWeight: 0.45, outputCostRatio: 2.0, expectedOutputTokens: 1500 };
+const COMPACTION_KNOBS: Knobs = { alpha: 0.05, speedWeight: 0.55, outputCostRatio: 3.0, expectedOutputTokens: 1000 };
+
+/** Knobs for this process, with per-knob env overrides applied on top of the role preset. */
+export function knobsForRole(role: Role): Knobs {
+	const base = role === "subagent" ? FAST_CHEAP_KNOBS : MAIN_LOOP_KNOBS;
+	return {
+		alpha: numEnv("WEAVE_ROUTING_ALPHA", base.alpha),
+		speedWeight: numEnv("WEAVE_ROUTING_SPEED_WEIGHT", base.speedWeight),
+		outputCostRatio: numEnv("WEAVE_ROUTING_OUTPUT_COST_RATIO", base.outputCostRatio),
+		expectedOutputTokens: numEnv("WEAVE_ROUTING_EXPECTED_OUTPUT_TOKENS", base.expectedOutputTokens),
+	};
+}
+
+export function compactionKnobs(): Knobs {
+	return { ...COMPACTION_KNOBS };
+}
+
+// ---------- header builders ----------
+
+const KNOB_HEADER = {
+	alpha: "x-weave-routing-alpha",
+	speedWeight: "x-weave-routing-speed-weight",
+	outputCostRatio: "x-weave-routing-output-cost-ratio",
+	expectedOutputTokens: "x-weave-routing-expected-output-tokens",
+} as const;
+
+export function knobHeaders(k: Knobs): Record<string, string> {
+	return {
+		[KNOB_HEADER.alpha]: String(k.alpha),
+		[KNOB_HEADER.speedWeight]: String(k.speedWeight),
+		[KNOB_HEADER.outputCostRatio]: String(k.outputCostRatio),
+		[KNOB_HEADER.expectedOutputTokens]: String(k.expectedOutputTokens),
+	};
+}
+
+/** Identity + auth headers. The router authenticates off X-Weave-Router-Key (authHeader stays false). */
+export function identityHeaders(role: Role, key: string): Record<string, string> {
+	const id = resolveIdentity();
+	const headers: Record<string, string> = {
+		"X-Weave-Router-Key": key,
+		"X-App": role === "subagent" ? "pi-subagent" : "pi",
+	};
+	if (id.email) headers["X-Weave-User-Email"] = id.email;
+	if (id.name) headers["X-Weave-User-Name"] = id.name;
+	return headers;
+}
+
+/** The full static header set for this process's `weave` provider. */
+export function providerHeaders(role: Role, key: string): Record<string, string> {
+	return {
+		...identityHeaders(role, key),
+		...knobHeaders(knobsForRole(role)),
+		// pi surfaces the routed model in its status bar (from x-router-model), so
+		// opt out of the router's in-band "✦ Weave Router → …" badge — it arrives as
+		// a separate text block that hides the answer in pi's renderer. (router #263)
+		"X-Weave-Routing-Marker": "off",
+	};
+}
+
+// ---------- model list ----------
+
+// Carried as a shared constant rather than relying on registerProvider preserving
+// an omitted `models` list, so the extension is self-sufficient: a freshly
+// dispatched child (and a `pi -e` smoke test with no models.json) can still
+// resolve `weave/<model>`. The list mirrors the installer's headline models;
+// the router re-routes every request regardless, so this is a UX/label surface.
+export const WEAVE_MODELS: ProviderModelConfig[] = [
+	model("claude-opus-4-8", "Claude Opus 4.8 (via Weave Router)", 64000),
+	model("claude-opus-4-7", "Claude Opus 4.7 (via Weave Router)", 64000),
+	model("claude-sonnet-4-6", "Claude Sonnet 4.6 (via Weave Router)", 64000),
+	model("claude-haiku-4-5", "Claude Haiku 4.5 (via Weave Router)", 32000),
+];
+
+function model(id: string, name: string, maxTokens: number): ProviderModelConfig {
+	return {
+		id,
+		name,
+		reasoning: true,
+		input: ["text", "image"],
+		// Real cost is decided by the router per request and is unknown client-side.
+		cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+		contextWindow: 200000,
+		maxTokens,
+	};
+}
+
+// ---------- dispatch / misc tunables ----------
+
+export const ROUTED_MODEL_HEADER = (process.env.WEAVE_ROUTED_MODEL_HEADER || "x-router-model").toLowerCase();
+/** Marker a headless child prints to stderr so the parent dispatch can read its routed model. */
+export const ROUTED_MODEL_STDERR_PREFIX = "weave-routed-model:";
+
+export const SUBAGENT_MODEL = process.env.WEAVE_PI_SUBAGENT_MODEL?.trim() || "claude-sonnet-4-6";
+export const DISPATCH_CONCURRENCY = Math.max(1, numEnv("WEAVE_PI_DISPATCH_CONCURRENCY", 4));
+export const MAX_SUBAGENTS = 8;
+export const SUBAGENT_TIMEOUT_MS = Math.max(1000, numEnv("WEAVE_PI_SUBAGENT_TIMEOUT_MS", 600000));
+export const DEFAULT_READONLY_TOOLS = ["read", "grep", "find", "ls"];
+
+// Tools that let a subagent mutate the filesystem or run arbitrary commands.
+// dispatch strips these from model-requested per-task `tools` (and downgrades
+// readOnly:false's "all tools") unless WEAVE_PI_ALLOW_SUBAGENT_TOOLS=1, so a
+// prompt-injected main loop can't silently escalate a read-only fan-out into
+// writes/exec. The catastrophic-command gate in safety.ts is a separate, narrower
+// backstop; this is the capability gate.
+export const DANGEROUS_SUBAGENT_TOOLS = new Set(["bash", "edit", "write", "patch", "multiedit", "apply_patch"]);

package/pi-router/src/dispatch.ts

@@ -0,0 +1,344 @@
+/**
+ * `dispatch` — parallel, context-isolated subagents.
+ *
+ * pi has no native subagents. The canonical pattern (examples/extensions/
+ * subagent) is to spawn a fresh `pi --print --mode json --no-session` process
+ * per task: true context isolation, reuses pi's own agent loop, and an
+ * independent router session. We layer Weave routing on top by loading this
+ * same extension in each child (`-e <self>`) with WEAVE_PI_SUBAGENT=1, so the
+ * child registers the `weave` provider with the speed/cheap knobs and a
+ * "subagent:" session id. Only the final assistant text comes back to the
+ * parent — intermediate tool output stays in the child, keeping the main
+ * context tiny.
+ */
+
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { Message } from "@mariozechner/pi-ai";
+import { Text } from "@mariozechner/pi-tui";
+import { Type } from "typebox";
+import {
+	DANGEROUS_SUBAGENT_TOOLS,
+	DEFAULT_READONLY_TOOLS,
+	DISPATCH_CONCURRENCY,
+	getRouterBaseUrl,
+	MAX_SUBAGENTS,
+	PROVIDER_NAME,
+	resolveIdentity,
+	resolveRouterKey,
+	ROUTED_MODEL_STDERR_PREFIX,
+	SUBAGENT_MODEL,
+	SUBAGENT_TIMEOUT_MS,
+} from "./config.js";
+
+const SIGKILL_GRACE_MS = 5000;
+
+const TaskItem = Type.Object({
+	prompt: Type.String({ description: "The full instruction for this subagent." }),
+	tools: Type.Optional(
+		Type.Array(Type.String(), {
+			description: "Tool names this subagent may use (e.g. read, grep). Overrides readOnly for this task. Dangerous tools (bash, write, edit) are ignored unless WEAVE_PI_ALLOW_SUBAGENT_TOOLS=1.",
+		}),
+	),
+	cwd: Type.Optional(Type.String({ description: "Working directory for this subagent. Defaults to the parent cwd." })),
+});
+
+const DispatchParams = Type.Object({
+	tasks: Type.Array(TaskItem, {
+		minItems: 1,
+		maxItems: MAX_SUBAGENTS,
+		description: "Tasks to run as parallel, context-isolated subagents.",
+	}),
+	readOnly: Type.Optional(
+		Type.Boolean({
+			default: true,
+			description: "When true (default), subagents get read-only tools (read, grep, find, ls). Per-task `tools` overrides this. Without WEAVE_PI_ALLOW_SUBAGENT_TOOLS=1, readOnly:false still yields read-only tools (no silent bash/write).",
+		}),
+	),
+});
+
+interface ChildResult {
+	index: number;
+	finalText: string;
+	routedModel?: string;
+	exitCode: number;
+	error?: string;
+}
+
+/** Resolve how to launch a nested pi (node/bun script, compiled binary, or `pi` on PATH). */
+function getPiInvocation(args: string[]): { command: string; args: string[] } {
+	const currentScript = process.argv[1];
+	const isBunVirtualScript = currentScript?.startsWith("/$bunfs/root/");
+	if (currentScript && !isBunVirtualScript && fs.existsSync(currentScript)) {
+		return { command: process.execPath, args: [currentScript, ...args] };
+	}
+	const execName = path.basename(process.execPath).toLowerCase();
+	const isGenericRuntime = /^(node|bun)(\.exe)?$/.test(execName);
+	if (!isGenericRuntime) return { command: process.execPath, args };
+	return { command: "pi", args };
+}
+
+async function mapWithConcurrencyLimit<TIn, TOut>(
+	items: TIn[],
+	concurrency: number,
+	fn: (item: TIn, index: number) => Promise<TOut>,
+): Promise<TOut[]> {
+	if (items.length === 0) return [];
+	const limit = Math.max(1, Math.min(concurrency, items.length));
+	const results: TOut[] = new Array(items.length);
+	let nextIndex = 0;
+	const workers = new Array(limit).fill(null).map(async () => {
+		while (true) {
+			const current = nextIndex++;
+			if (current >= items.length) return;
+			results[current] = await fn(items[current], current);
+		}
+	});
+	await Promise.all(workers);
+	return results;
+}
+
+/** Full text of the child's last assistant message (all text blocks joined). */
+function finalAssistantText(messages: Message[]): string {
+	for (let i = messages.length - 1; i >= 0; i--) {
+		const msg = messages[i];
+		if (msg.role !== "assistant") continue;
+		const texts: string[] = [];
+		for (const part of msg.content ?? []) {
+			if (part.type === "text") texts.push(part.text);
+		}
+		if (texts.length > 0) return texts.join("");
+	}
+	return "";
+}
+
+function runChild(
+	selfPath: string,
+	task: { prompt: string; tools?: string[]; cwd?: string },
+	readOnly: boolean,
+	defaultCwd: string,
+	key: string,
+	signal: AbortSignal | undefined,
+	index: number,
+): Promise<ChildResult> {
+	const args = ["--print", "--mode", "json", "--no-session", "-e", selfPath, "--model", `${PROVIDER_NAME}/${SUBAGENT_MODEL}`];
+
+	// Secure-by-default tool gating. Task input is model-influenced, so without an
+	// explicit opt-in we never hand a child write/exec tools: model-requested
+	// `tools` are stripped of dangerous entries, and readOnly:false's "all tools"
+	// is downgraded to read-only. WEAVE_PI_ALLOW_SUBAGENT_TOOLS=1 restores full
+	// flexibility. Stops a prompt-injected main loop from escalating a read-only
+	// fan-out into arbitrary command/file execution under the user's identity.
+	const allowDangerousTools = process.env.WEAVE_PI_ALLOW_SUBAGENT_TOOLS === "1";
+	let tools: string[] | undefined;
+	if (task.tools && task.tools.length > 0) {
+		tools = task.tools;
+	} else if (readOnly || !allowDangerousTools) {
+		tools = DEFAULT_READONLY_TOOLS;
+	} else {
+		tools = undefined; // readOnly:false + opt-in => full toolset
+	}
+	if (tools && !allowDangerousTools) {
+		// Trim first: pi's `--tools` parser trims each entry, so " bash" would slip
+		// past a non-trimmed check here and then get re-enabled downstream.
+		tools = tools.map((t) => t.trim()).filter((t) => t !== "" && !DANGEROUS_SUBAGENT_TOOLS.has(t.toLowerCase()));
+		if (tools.length === 0) tools = DEFAULT_READONLY_TOOLS;
+	}
+	if (tools) args.push("--tools", tools.join(","));
+	args.push(task.prompt);
+
+	const identity = resolveIdentity();
+	const env: NodeJS.ProcessEnv = {
+		...process.env,
+		WEAVE_PI_SUBAGENT: "1",
+		WEAVE_PI_SUBAGENT_ID: randomUUID(),
+		WEAVE_ROUTER_KEY: key,
+		WEAVE_ROUTER_URL: getRouterBaseUrl(),
+	};
+	// Don't let the main loop's per-knob routing overrides leak into children:
+	// knobsForRole prefers env values over the role preset, which would route
+	// subagents on the main loop's quality knobs instead of the speed/cheap ones.
+	delete env.WEAVE_ROUTING_ALPHA;
+	delete env.WEAVE_ROUTING_SPEED_WEIGHT;
+	delete env.WEAVE_ROUTING_OUTPUT_COST_RATIO;
+	delete env.WEAVE_ROUTING_EXPECTED_OUTPUT_TOKENS;
+	if (identity.email) env.WEAVE_USER_EMAIL = identity.email;
+	if (identity.name) env.WEAVE_USER_NAME = identity.name;
+
+	const result: ChildResult = { index, finalText: "", exitCode: 0 };
+	const messages: Message[] = [];
+
+	return new Promise<ChildResult>((resolve) => {
+		const invocation = getPiInvocation(args);
+		const proc = spawn(invocation.command, invocation.args, {
+			cwd: task.cwd ?? defaultCwd,
+			shell: false,
+			stdio: ["ignore", "pipe", "pipe"],
+			env,
+		});
+
+		let stdoutBuf = "";
+		let stderrBuf = "";
+		let settled = false;
+		let timedOut = false;
+
+		const processLine = (line: string) => {
+			if (!line.trim()) return;
+			let event: { type?: string; message?: Message };
+			try {
+				event = JSON.parse(line);
+			} catch {
+				return;
+			}
+			if ((event.type === "message_end" || event.type === "tool_result_end") && event.message) {
+				messages.push(event.message);
+			}
+		};
+
+		proc.stdout.on("data", (data) => {
+			stdoutBuf += data.toString();
+			const lines = stdoutBuf.split("\n");
+			stdoutBuf = lines.pop() ?? "";
+			for (const line of lines) processLine(line);
+		});
+		proc.stderr.on("data", (data) => {
+			stderrBuf += data.toString();
+		});
+
+		const timer = setTimeout(() => {
+			timedOut = true;
+			proc.kill("SIGTERM");
+			// proc.killed flips true the instant SIGTERM is *sent*, so escalate based
+			// on whether the process actually exited (settled), not proc.killed.
+			setTimeout(() => {
+				if (!settled) proc.kill("SIGKILL");
+			}, SIGKILL_GRACE_MS);
+		}, SUBAGENT_TIMEOUT_MS);
+
+		const onAbort = () => {
+			proc.kill("SIGTERM");
+			setTimeout(() => {
+				if (!settled) proc.kill("SIGKILL");
+			}, SIGKILL_GRACE_MS);
+		};
+		if (signal) {
+			if (signal.aborted) onAbort();
+			else signal.addEventListener("abort", onAbort, { once: true });
+		}
+
+		const settle = (exitCode: number) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			signal?.removeEventListener("abort", onAbort);
+			result.exitCode = exitCode;
+			// resolve() must always run — a parse error here would otherwise strand
+			// this promise and block the whole dispatch via mapWithConcurrencyLimit.
+			try {
+				if (stdoutBuf.trim()) processLine(stdoutBuf);
+				result.finalText = finalAssistantText(messages);
+				result.routedModel = lastRoutedModel(stderrBuf);
+				if (exitCode !== 0 && !result.finalText) {
+					result.error = timedOut
+						? `timed out after ${Math.round(SUBAGENT_TIMEOUT_MS / 1000)}s`
+						: signal?.aborted
+							? "aborted"
+							: lastStderrLine(stderrBuf) || `exited with code ${exitCode}`;
+				}
+			} catch (err) {
+				if (!result.error) result.error = `failed to read subagent output: ${(err as Error).message}`;
+			}
+			resolve(result);
+		};
+
+		// A null exit code means the child was killed by a signal (timeout / abort /
+		// crash) — settle as failure (1), not success (0), so a killed subagent with
+		// no output can't be counted as succeeded.
+		proc.on("close", (code) => settle(code ?? 1));
+		proc.on("error", (err) => {
+			stderrBuf += `${err.message}\n`;
+			settle(1);
+		});
+	});
+}
+
+function lastRoutedModel(stderr: string): string | undefined {
+	let found: string | undefined;
+	for (const line of stderr.split("\n")) {
+		const idx = line.indexOf(ROUTED_MODEL_STDERR_PREFIX);
+		if (idx !== -1) found = line.slice(idx + ROUTED_MODEL_STDERR_PREFIX.length).trim();
+	}
+	return found || undefined;
+}
+
+function lastStderrLine(stderr: string): string {
+	const lines = stderr
+		.split("\n")
+		.map((l) => l.trim())
+		.filter(Boolean);
+	return lines.length > 0 ? lines[lines.length - 1] : "";
+}
+
+export function registerDispatch(pi: ExtensionAPI, selfPath: string): void {
+	pi.registerTool({
+		name: "dispatch",
+		label: "Dispatch",
+		description: [
+			"Run tasks as parallel, context-isolated subagents (separate pi processes).",
+			"Each subagent has its own context window and routes through the Weave Router on speed/cheap knobs;",
+			"only its final answer returns here, so intermediate work never bloats this context.",
+			"Subagents are read-only by default (read, grep, find, ls); pass per-task `tools` to widen.",
+			"Use for fan-out investigation/search across independent questions.",
+		].join(" "),
+		parameters: DispatchParams,
+		executionMode: "parallel",
+
+		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+			const key = resolveRouterKey();
+			if (!key) {
+				return {
+					content: [
+						{ type: "text", text: "Weave dispatch unavailable: no router key (set WEAVE_ROUTER_KEY or run the --pi installer)." },
+					],
+					details: { results: [] as ChildResult[] },
+					isError: true,
+				};
+			}
+
+			const readOnly = params.readOnly ?? true;
+			const results = await mapWithConcurrencyLimit(params.tasks, DISPATCH_CONCURRENCY, (task, index) =>
+				runChild(selfPath, task, readOnly, ctx.cwd, key, signal, index),
+			);
+
+			const succeeded = results.filter((r) => r.exitCode === 0 && !r.error).length;
+			const blocks = results.map((r) => {
+				const tags = [r.routedModel ? `routed: ${r.routedModel}` : null, r.exitCode === 0 && !r.error ? null : "FAILED"]
+					.filter(Boolean)
+					.join(" · ");
+				const header = `## Subagent ${r.index + 1}${tags ? ` (${tags})` : ""}`;
+				const body = r.error ? `Error: ${r.error}` : r.finalText || "(no output)";
+				return `${header}\n${body}`;
+			});
+
+			return {
+				content: [{ type: "text", text: `${succeeded}/${results.length} subagents succeeded\n\n${blocks.join("\n\n")}` }],
+				details: { results },
+				isError: succeeded === 0,
+			};
+		},
+
+		renderCall(args, theme) {
+			const tasks = args.tasks ?? [];
+			let text = `${theme.fg("toolTitle", theme.bold("dispatch "))}${theme.fg("accent", `${tasks.length} subagent${tasks.length === 1 ? "" : "s"}`)}`;
+			for (const t of tasks.slice(0, 3)) {
+				const preview = t.prompt.length > 60 ? `${t.prompt.slice(0, 60)}...` : t.prompt;
+				text += `\n  ${theme.fg("dim", preview)}`;
+			}
+			if (tasks.length > 3) text += `\n  ${theme.fg("muted", `... +${tasks.length - 3} more`)}`;
+			return new Text(text, 0, 0);
+		},
+	});
+}

package/pi-router/src/index.ts

@@ -0,0 +1,49 @@
+/**
+ * @workweave/router — route the pi coding agent through the WorkWeave Router.
+ *
+ * Wiring (all on the existing router surface — no router source change beyond
+ * the installer):
+ *   - provider:     register `weave` with per-process knob headers (quality on
+ *                   the main loop, speed/cheap in subagents).
+ *   - metadata:     stamp body.metadata.user_id for sticky sessions + subagent
+ *                   detection.
+ *   - routed-model: show which model the router actually picked.
+ *   - safety:       block catastrophic bash (unless WEAVE_NO_SAFETY=1).
+ *   - compaction:   experimental cheap path (only when WEAVE_CHEAP_COMPACTION=1).
+ *   - dispatch:     parallel, context-isolated subagents — top-level process
+ *                   only (no grandchildren).
+ *
+ * The same module loads in dispatched children via `-e <self>`; WEAVE_PI_SUBAGENT
+ * flips the provider knobs and suppresses the dispatch tool so fan-out doesn't recurse.
+ */
+
+import { fileURLToPath } from "node:url";
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { isSubagent } from "./config.js";
+import { registerCheapCompaction } from "./compaction.js";
+import { registerDispatch } from "./dispatch.js";
+import { registerMetadata } from "./metadata.js";
+import { registerRoutedModel } from "./routed-model.js";
+import { registerSafety } from "./safety.js";
+import { registerWeave } from "./provider.js";
+
+const SELF_PATH = fileURLToPath(import.meta.url);
+
+export default function (pi: ExtensionAPI): void {
+	// Register at load so the provider is available for `--list-models` and
+	// print mode (dispatched children), and again on session_start so the right
+	// knob headers survive `/reload` and new/resumed sessions.
+	registerWeave(pi);
+	pi.on("session_start", () => registerWeave(pi));
+
+	registerMetadata(pi);
+	registerRoutedModel(pi);
+
+	if (process.env.WEAVE_NO_SAFETY !== "1") registerSafety(pi);
+	if (process.env.WEAVE_CHEAP_COMPACTION === "1") registerCheapCompaction(pi);
+
+	// Only the top-level process fans out. Children (WEAVE_PI_SUBAGENT=1) load
+	// this same extension but get no dispatch tool, so subagents can't spawn
+	// grandchildren.
+	if (!isSubagent()) registerDispatch(pi, SELF_PATH);
+}

package/pi-router/src/metadata.ts

@@ -0,0 +1,32 @@
+/**
+ * Injects `metadata.user_id` into the request body so the router can:
+ *   - keep the main loop on a sticky session pin ("pi:<sessionId>"), and
+ *   - detect subagents ("subagent:<uuid>") for an independent pin + server-side
+ *     SubAgentDispatch handling.
+ *
+ * This is the one body-level signal we control (the session pin key derives
+ * from metadata.user_id when present; subagent detection on the Anthropic
+ * ingress path keys off a "subagent:" prefix). Headers can't carry it because
+ * before_provider_request can't set headers.
+ */
+
+import { randomUUID } from "node:crypto";
+import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import { isSubagent } from "./config.js";
+
+// One id per child process so all of a subagent's requests share a single pin.
+// The parent passes WEAVE_PI_SUBAGENT_ID; a standalone child falls back to a uuid.
+const SUBAGENT_USER_ID = `subagent:${process.env.WEAVE_PI_SUBAGENT_ID?.trim() || randomUUID()}`;
+
+export function registerMetadata(pi: ExtensionAPI): void {
+	pi.on("before_provider_request", (event, ctx: ExtensionContext) => {
+		const body = event.payload as { metadata?: { user_id?: string } } | undefined;
+		if (!body || typeof body !== "object") return undefined;
+
+		const userId = isSubagent() ? SUBAGENT_USER_ID : `pi:${ctx.sessionManager.getSessionId()}`;
+		if (body.metadata?.user_id === userId) return undefined;
+
+		body.metadata = { ...(body.metadata ?? {}), user_id: userId };
+		return body;
+	});
+}