@ryan_nookpi/pi-extension-subagent 0.1.0

package/format.ts

@@ -0,0 +1,188 @@
+/**
+ * Formatting and display utility functions for the Subagent tool.
+ */
+
+import * as os from "node:os";
+import type { ThemeColor } from "@earendil-works/pi-coding-agent";
+import { normalizeModelRef as normalizeModelRefUtil } from "./utils/format-utils.js";
+
+export {
+	AGENT_NAME_PALETTE,
+	agentBgIndex,
+	formatContextUsageBar,
+	formatTokens,
+	formatUsageStats,
+	getContextBarColorByRemaining,
+	getRemainingContextPercent,
+	getUsedContextPercent,
+	truncateLines,
+	truncatePlainToWidth,
+	truncateToWidthWithEllipsis,
+} from "./utils/format-utils.js";
+export const normalizeModelRef = normalizeModelRefUtil;
+
+// ─── Context Usage ───────────────────────────────────────────────────────────
+
+type ContextWindowResolverContext = {
+	model?: { contextWindow?: number };
+	modelRegistry?: {
+		getAll: () => Array<{ provider: string; id: string; contextWindow?: number }>;
+	};
+};
+
+type ThemeFg = (color: ThemeColor, text: string) => string;
+
+export function resolveContextWindow(ctx: ContextWindowResolverContext, modelRef?: string): number | undefined {
+	const fallback = ctx?.model?.contextWindow;
+	if (!ctx?.modelRegistry || typeof ctx.modelRegistry.getAll !== "function") return fallback;
+	const models = ctx.modelRegistry.getAll() as Array<{ provider: string; id: string; contextWindow?: number }>;
+	if (!modelRef) return fallback;
+
+	const normalized = normalizeModelRef(modelRef);
+	if (normalized.provider) {
+		const exact = models.find((m) => m.provider === normalized.provider && m.id === normalized.id);
+		if (exact?.contextWindow) return exact.contextWindow;
+	}
+
+	const byId = models.find((m) => m.id === normalized.id);
+	if (byId?.contextWindow) return byId.contextWindow;
+
+	return fallback;
+}
+
+// ─── Tool Call Formatting ────────────────────────────────────────────────────
+
+function stringifyPreviewValue(value: unknown): string {
+	if (value === undefined || value === null) return "...";
+	if (typeof value === "string") return value;
+	if (Array.isArray(value)) {
+		const parts = value.map((item) => stringifyPreviewValue(item));
+		return parts.length > 3 ? `${parts.slice(0, 3).join(", ")}, ...` : parts.join(", ");
+	}
+	try {
+		return JSON.stringify(value);
+	} catch {
+		return String(value);
+	}
+}
+
+function formatPathValueForPreview(value: unknown): string {
+	const text = stringifyPreviewValue(value);
+	const home = os.homedir();
+	return text.startsWith(home) ? `~${text.slice(home.length)}` : text;
+}
+
+export function formatToolCall(toolName: string, args: Record<string, unknown>, themeFg: ThemeFg): string {
+	const shortenPath = (value: unknown) => formatPathValueForPreview(value);
+
+	switch (toolName) {
+		case "bash": {
+			const command = (args.command as string) || "...";
+			const preview = command.length > 60 ? `${command.slice(0, 60)}...` : command;
+			return themeFg("muted", "$ ") + themeFg("toolOutput", preview);
+		}
+		case "read": {
+			const rawPath = args.file_path || args.path || "...";
+			const filePath = shortenPath(rawPath);
+			const offset = args.offset as number | undefined;
+			const limit = args.limit as number | undefined;
+			let text = themeFg("accent", filePath);
+			if (offset !== undefined || limit !== undefined) {
+				const startLine = offset ?? 1;
+				const endLine = limit !== undefined ? startLine + limit - 1 : "";
+				text += themeFg("warning", `:${startLine}${endLine ? `-${endLine}` : ""}`);
+			}
+			return themeFg("muted", "read ") + text;
+		}
+		case "write": {
+			const rawPath = args.file_path || args.path || "...";
+			const filePath = shortenPath(rawPath);
+			const content = (args.content || "") as string;
+			const lines = content.split("\n").length;
+			let text = themeFg("muted", "write ") + themeFg("accent", filePath);
+			if (lines > 1) text += themeFg("dim", ` (${lines} lines)`);
+			return text;
+		}
+		case "edit": {
+			const rawPath = args.file_path || args.path || "...";
+			return themeFg("muted", "edit ") + themeFg("accent", shortenPath(rawPath));
+		}
+		case "ls": {
+			const rawPath = args.path || ".";
+			return themeFg("muted", "ls ") + themeFg("accent", shortenPath(rawPath));
+		}
+		case "find": {
+			const pattern = (args.pattern || "*") as string;
+			const rawPath = args.path || ".";
+			return themeFg("muted", "find ") + themeFg("accent", pattern) + themeFg("dim", ` in ${shortenPath(rawPath)}`);
+		}
+		case "grep": {
+			const pattern = (args.pattern || "") as string;
+			const rawPath = args.path || ".";
+			return (
+				themeFg("muted", "grep ") + themeFg("accent", `/${pattern}/`) + themeFg("dim", ` in ${shortenPath(rawPath)}`)
+			);
+		}
+		default: {
+			const argsStr = JSON.stringify(args);
+			const preview = argsStr.length > 50 ? `${argsStr.slice(0, 50)}...` : argsStr;
+			return themeFg("accent", toolName) + themeFg("dim", ` ${preview}`);
+		}
+	}
+}
+
+export function shortenPathForPreview(p: unknown): string {
+	return formatPathValueForPreview(p);
+}
+
+export function formatToolCallPlain(toolName: string, args: Record<string, unknown>): string {
+	switch (toolName) {
+		case "bash": {
+			const command = (args.command as string) || "...";
+			const preview = command.length > 60 ? `${command.slice(0, 60)}...` : command;
+			return `$ ${preview}`;
+		}
+		case "read": {
+			const rawPath = args.file_path || args.path || "...";
+			const filePath = shortenPathForPreview(rawPath);
+			const offset = args.offset as number | undefined;
+			const limit = args.limit as number | undefined;
+			if (offset !== undefined || limit !== undefined) {
+				const startLine = offset ?? 1;
+				const endLine = limit !== undefined ? startLine + limit - 1 : "";
+				return `read ${filePath}:${startLine}${endLine ? `-${endLine}` : ""}`;
+			}
+			return `read ${filePath}`;
+		}
+		case "write": {
+			const rawPath = args.file_path || args.path || "...";
+			const filePath = shortenPathForPreview(rawPath);
+			const content = (args.content || "") as string;
+			const lines = content.split("\n").length;
+			return lines > 1 ? `write ${filePath} (${lines} lines)` : `write ${filePath}`;
+		}
+		case "edit": {
+			const rawPath = args.file_path || args.path || "...";
+			return `edit ${shortenPathForPreview(rawPath)}`;
+		}
+		case "ls": {
+			const rawPath = args.path || ".";
+			return `ls ${shortenPathForPreview(rawPath)}`;
+		}
+		case "find": {
+			const pattern = (args.pattern || "*") as string;
+			const rawPath = args.path || ".";
+			return `find ${pattern} in ${shortenPathForPreview(rawPath)}`;
+		}
+		case "grep": {
+			const pattern = (args.pattern || "") as string;
+			const rawPath = args.path || ".";
+			return `grep /${pattern}/ in ${shortenPathForPreview(rawPath)}`;
+		}
+		default: {
+			const argsStr = JSON.stringify(args);
+			const preview = argsStr.length > 50 ? `${argsStr.slice(0, 50)}...` : argsStr;
+			return `${toolName} ${preview}`;
+		}
+	}
+}

package/group-pending.ts

@@ -0,0 +1,90 @@
+/**
+ * Durable storage for grouped batch/chain pending completion summaries.
+ *
+ * This intentionally covers only finished group summaries that still need to be
+ * delivered back to the origin session. It does NOT attempt to resume in-flight
+ * batch/chain orchestration after reload or process restart.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import type { PendingCompletion } from "./types.js";
+
+export type PendingGroupScope = "batch" | "chain";
+
+export interface PersistedPendingGroupCompletion {
+	scope: PendingGroupScope;
+	groupId: string;
+	originSessionFile: string;
+	runIds: number[];
+	pendingCompletion: PendingCompletion;
+}
+
+function getStateDir(): string {
+	return path.join(getAgentDir(), "state");
+}
+
+function getPendingGroupsFile(): string {
+	return path.join(getStateDir(), "subagent-pending-groups.json");
+}
+
+function ensureStateDir(): void {
+	fs.mkdirSync(getStateDir(), { recursive: true });
+}
+
+function readPersistedEntries(): PersistedPendingGroupCompletion[] {
+	try {
+		if (!fs.existsSync(getPendingGroupsFile())) return [];
+		const raw = fs.readFileSync(getPendingGroupsFile(), "utf-8");
+		if (!raw.trim()) return [];
+		const parsed = JSON.parse(raw);
+		if (!Array.isArray(parsed)) return [];
+		return parsed.filter((entry): entry is PersistedPendingGroupCompletion => {
+			return Boolean(
+				entry &&
+					(entry.scope === "batch" || entry.scope === "chain") &&
+					typeof entry.groupId === "string" &&
+					typeof entry.originSessionFile === "string" &&
+					Array.isArray(entry.runIds) &&
+					entry.pendingCompletion &&
+					typeof entry.pendingCompletion.createdAt === "number",
+			);
+		});
+	} catch {
+		return [];
+	}
+}
+
+function writePersistedEntries(entries: PersistedPendingGroupCompletion[]): void {
+	ensureStateDir();
+	fs.writeFileSync(getPendingGroupsFile(), `${JSON.stringify(entries, null, 2)}\n`, "utf-8");
+}
+
+export function upsertPendingGroupCompletion(entry: PersistedPendingGroupCompletion): void {
+	const entries = readPersistedEntries().filter(
+		(item) => !(item.scope === entry.scope && item.groupId === entry.groupId),
+	);
+	entries.push(entry);
+	writePersistedEntries(entries);
+}
+
+export function clearPendingGroupCompletion(scope: PendingGroupScope, groupId: string): void {
+	const entries = readPersistedEntries().filter((entry) => !(entry.scope === scope && entry.groupId === groupId));
+	writePersistedEntries(entries);
+}
+
+export function consumePendingGroupCompletionsForSession(sessionFile: string): PersistedPendingGroupCompletion[] {
+	const entries = readPersistedEntries();
+	const matched = entries.filter((entry) => entry.originSessionFile === sessionFile);
+	if (matched.length === 0) return [];
+	const remaining = entries.filter((entry) => entry.originSessionFile !== sessionFile);
+	writePersistedEntries(remaining);
+	return matched;
+}
+
+export function evictStalePendingGroupCompletions(maxAgeMs: number): void {
+	const now = Date.now();
+	const entries = readPersistedEntries().filter((entry) => now - entry.pendingCompletion.createdAt <= maxAgeMs);
+	writePersistedEntries(entries);
+}

package/index.ts

@@ -0,0 +1,200 @@
+/**
+ * Subagent Tool - Delegate tasks to specialized agents
+ *
+ * Spawns a separate `pi` process for each subagent invocation,
+ * giving it an isolated context window.
+ *
+ * Supports a single run mode via the CLI-style `subagent` command.
+ *
+ * Uses JSON mode to capture structured output from subagents.
+ *
+ * Architecture:
+ *   types.ts    — Type definitions, interfaces, Typebox schemas
+ *   store.ts    — Shared state (SubagentStore) and state-mutation helpers
+ *   format.ts   — Token/usage/tool-call formatting utilities
+ *   session.ts  — Session file management and context helpers
+ *   runner.ts   — Subagent process execution, agent matching, concurrency
+ *   replay.ts   — Session replay viewer (TUI overlay)
+ *   widget.ts   — Run status widget (above-editor display)
+ *   commands.ts — Tool handler, slash-commands, event handlers
+ *   index.ts    — Orchestrator (this file)
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { cleanupPixelTimer } from "./above-widget.js";
+import { registerAll } from "./commands.js";
+import { HANG_CHECK_INTERVAL_MS, HANG_TIMEOUT_MS } from "./constants.js";
+import { registerAskMasterTool } from "./escalation.js";
+import { getSessionFileMtimeMs, readPersistedSessionSnapshot } from "./persisted-session.js";
+import { getLastNonEmptyLine } from "./runner.js";
+import { createStore, type SubagentStore } from "./store.js";
+import type { CommandRunState } from "./types.js";
+import { cleanupCommandRunsWidgetTimer, updateCommandRunsWidget } from "./widget.js";
+
+function reconcileRunWithPersistedSession(run: CommandRunState): void {
+	if (!run.sessionFile) return;
+
+	const mtimeMs = getSessionFileMtimeMs(run.sessionFile);
+	if (mtimeMs && mtimeMs > run.lastActivityAt) {
+		run.lastActivityAt = mtimeMs;
+	}
+
+	const snapshot = readPersistedSessionSnapshot(run.sessionFile, {
+		startOffset: run.persistedSessionBaseOffset,
+	});
+	if (snapshot.latestActivityAt && snapshot.latestActivityAt > run.lastActivityAt) {
+		run.lastActivityAt = snapshot.latestActivityAt;
+	}
+	if (!snapshot.isTerminal) return;
+
+	const exitCode =
+		snapshot.completionMarker?.exitCode ??
+		(snapshot.terminalStopReason === "error" || snapshot.terminalStopReason === "aborted" ? 1 : 0);
+	run.status = exitCode === 0 ? "done" : "error";
+	if (snapshot.finalOutput) {
+		run.lastOutput = snapshot.finalOutput;
+		run.lastLine = getLastNonEmptyLine(snapshot.finalOutput) || run.lastLine;
+	}
+	if (snapshot.latestActivityAt) {
+		run.elapsedMs = Math.max(run.elapsedMs, snapshot.latestActivityAt - run.startedAt);
+	}
+}
+
+/**
+ * Abort all session-scoped child processes before Pi invalidates this
+ * extension runtime. A non-triggering failure entry is persisted so returning
+ * to the old session explains why the run stopped.
+ */
+type SessionShutdownReason = "quit" | "reload" | "new" | "resume" | "fork";
+
+export function shutdownSubagentRuns(store: SubagentStore, pi: ExtensionAPI, reason: SessionShutdownReason): void {
+	if (store.disposed) return;
+	store.disposed = true;
+
+	const activeRuns = new Map<number, CommandRunState>();
+	for (const [runId, run] of store.commandRuns) activeRuns.set(runId, run);
+	for (const [runId, entry] of store.globalLiveRuns) activeRuns.set(runId, entry.runState);
+
+	for (const [runId, run] of activeRuns) {
+		if (run.status !== "running") continue;
+		const message = `Aborted because the parent pi session ${reason} is shutting down.`;
+		run.status = "error";
+		run.elapsedMs = Date.now() - run.startedAt;
+		run.lastActivityAt = Date.now();
+		run.lastLine = message;
+		run.lastOutput = message;
+		run.removed = true;
+
+		const controller = run.abortController ?? store.globalLiveRuns.get(runId)?.abortController;
+		controller?.abort();
+		run.abortController = undefined;
+
+		if (run.deliveryMode === "humanOnly") continue;
+		try {
+			pi.sendMessage(
+				{
+					customType: run.source === "tool" ? "subagent-tool" : "subagent-command",
+					content: `[subagent:${run.agent}#${runId}] failed\n\n${message}`,
+					display: false,
+					details: {
+						runId,
+						agent: run.agent,
+						task: run.task,
+						displayTask: run.displayTask,
+						status: "error",
+						error: message,
+						startedAt: run.startedAt,
+						elapsedMs: run.elapsedMs,
+						lastActivityAt: run.lastActivityAt,
+						sessionFile: run.sessionFile,
+					},
+				},
+				{ deliverAs: "followUp", triggerTurn: false },
+			);
+		} catch {
+			// The runtime may already be closing; aborting the child remains the priority.
+		}
+	}
+
+	store.globalLiveRuns.clear();
+	store.batchGroups.clear();
+	store.pipelines.clear();
+	store.recentLaunchTimestamps.clear();
+	store.commandRuns.clear();
+	store.commandWidgetCtx = null;
+	store.pixelWidgetCtx = null;
+	cleanupCommandRunsWidgetTimer();
+}
+
+/**
+ * Sweep active runs for inactivity. The normal run finalizer owns completion
+ * delivery so an auto-abort cannot emit two follow-up messages.
+ */
+export function checkForHungRuns(store: SubagentStore, _pi: ExtensionAPI): void {
+	if (store.disposed) return;
+	const now = Date.now();
+	const processed = new Set<number>();
+
+	function tryAbort(runId: number, run: CommandRunState): void {
+		reconcileRunWithPersistedSession(run);
+		// Skip if already completed/aborted or not running
+		if (run.status !== "running") return;
+		if (!run.lastActivityAt) return;
+		// Guard: skip runs already auto-aborted (prevents duplicate abort/followUp)
+		if (run.lastLine?.startsWith("Auto-aborted:")) return;
+
+		const idleMs = now - run.lastActivityAt;
+		if (idleMs < HANG_TIMEOUT_MS) return;
+
+		// Try to abort via run's own controller, then globalLiveRuns fallback
+		const globalEntry = store.globalLiveRuns.get(runId);
+		const controller = run.abortController ?? globalEntry?.abortController;
+
+		const reason = `Auto-aborted: no activity for ${Math.round(idleMs / 1000)}s`;
+		run.lastLine = reason;
+		run.lastOutput = reason;
+		run.status = "error";
+		run.autoAbortReason = reason;
+
+		if (controller) {
+			controller.abort();
+		}
+	}
+
+	// Sweep commandRuns first
+	for (const [runId, run] of store.commandRuns) {
+		processed.add(runId);
+		tryAbort(runId, run);
+	}
+
+	// Sweep registry-only runs that are not present in the current widget view.
+	for (const [runId, entry] of store.globalLiveRuns) {
+		if (processed.has(runId)) continue;
+		tryAbort(runId, entry.runState);
+	}
+
+	updateCommandRunsWidget(store);
+}
+
+export default function (pi: ExtensionAPI) {
+	const store = createStore();
+	registerAskMasterTool(pi);
+	registerAll(pi, store);
+
+	let hangCheckTimer: ReturnType<typeof setInterval> | undefined;
+	pi.on("session_start", () => {
+		store.disposed = false;
+		if (!hangCheckTimer) {
+			hangCheckTimer = setInterval(() => checkForHungRuns(store, pi), HANG_CHECK_INTERVAL_MS);
+		}
+	});
+
+	pi.on("session_shutdown", async (event) => {
+		if (hangCheckTimer) {
+			clearInterval(hangCheckTimer);
+			hangCheckTimer = undefined;
+		}
+		shutdownSubagentRuns(store, pi, event.reason);
+		cleanupPixelTimer();
+	});
+}

package/invocation-queue.ts

@@ -0,0 +1,29 @@
+import { SUBAGENT_QUEUE_INTERVAL_MS } from "./constants.js";
+
+let startQueueTail: Promise<void> = Promise.resolve();
+
+function sleep(ms: number): Promise<void> {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Queue only subagent invocation starts through a single pacing queue.
+ *
+ * Each invocation waits for its start slot (fixed delay per slot), but once
+ * started the job runs independently so multiple subagents can execute in
+ * parallel.
+ */
+export function enqueueSubagentInvocation<T>(job: () => Promise<T>): Promise<T> {
+	const startGate = startQueueTail.then(
+		() => sleep(SUBAGENT_QUEUE_INTERVAL_MS),
+		() => sleep(SUBAGENT_QUEUE_INTERVAL_MS),
+	);
+
+	// Important: only pace the next start slot. Do not wait for job completion.
+	startQueueTail = startGate.then(
+		() => undefined,
+		() => undefined,
+	);
+
+	return startGate.then(() => job());
+}

package/live-preview.ts

@@ -0,0 +1,39 @@
+import { formatToolCallPlain } from "./format.js";
+
+const THOUGHT_PREVIEW_MAX_CHARS = 80;
+const ACTIVITY_PREVIEW_MAX_CHARS = 240;
+
+function getFirstNonEmptyLine(raw: string): string | undefined {
+	return raw
+		.split("\n")
+		.map((line) => line.trim())
+		.filter(Boolean)[0];
+}
+
+export function extractThoughtText(raw: string): string | undefined {
+	const firstLine = getFirstNonEmptyLine(raw);
+	if (!firstLine) return undefined;
+
+	const clean = firstLine
+		.replace(/^#+\s*/, "")
+		.replace(/\*{1,3}([^*]+)\*{1,3}/g, "$1")
+		.replace(/`([^`]+)`/g, "$1")
+		.trim();
+	if (!clean) return undefined;
+	return clean.slice(0, THOUGHT_PREVIEW_MAX_CHARS);
+}
+
+export function extractActivityPreviewFromTextDelta(raw: string): string | undefined {
+	const lastLine = raw
+		.split("\n")
+		.map((line) => line.trim())
+		.filter(Boolean)
+		.pop();
+	if (!lastLine) return undefined;
+	return lastLine.slice(0, ACTIVITY_PREVIEW_MAX_CHARS);
+}
+
+export function formatPiToolExecutionPreview(toolName: string, args: unknown): string {
+	const normalizedArgs = args && typeof args === "object" ? (args as Record<string, unknown>) : {};
+	return `→ ${formatToolCallPlain(toolName, normalizedArgs)}`;
+}

package/package.json

@@ -0,0 +1,95 @@
+{
+  "name": "@ryan_nookpi/pi-extension-subagent",
+  "version": "0.1.0",
+  "description": "Asynchronous subagent delegation for pi with run, batch, chain, and continuation workflows.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Jonghakseo/pi-extension.git",
+    "directory": "packages/subagent"
+  },
+  "bugs": {
+    "url": "https://github.com/Jonghakseo/pi-extension/issues"
+  },
+  "homepage": "https://github.com/Jonghakseo/pi-extension/tree/main/packages/subagent#readme",
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "subagent",
+    "delegation"
+  ],
+  "files": [
+    "above-widget.ts",
+    "agents.ts",
+    "claude-args.ts",
+    "claude-sdk-runner.ts",
+    "claude-sdk-stream-adapter.ts",
+    "claude-sidecar-writer.ts",
+    "claude-stream-parser.ts",
+    "cli.ts",
+    "commands.ts",
+    "config.ts",
+    "constants.ts",
+    "context-limits.ts",
+    "display-task.ts",
+    "escalation.ts",
+    "format.ts",
+    "group-pending.ts",
+    "index.ts",
+    "invocation-queue.ts",
+    "live-preview.ts",
+    "persisted-session.ts",
+    "replay.ts",
+    "retry.ts",
+    "run-utils.ts",
+    "runner.ts",
+    "session.ts",
+    "store.ts",
+    "tool-execute.ts",
+    "tool-render.ts",
+    "types.ts",
+    "widget.ts",
+    "utils/agent-utils.ts",
+    "utils/short-label.ts",
+    "utils/string-utils.ts",
+    "utils/format-utils.ts",
+    "utils/time-utils.ts",
+    "README.md"
+  ],
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.2.98",
+    "yaml": "^2.9.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-agent-core": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
+    "@earendil-works/pi-agent-core": {
+      "optional": true
+    },
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "@earendil-works/pi-tui": {
+      "optional": true
+    },
+    "typebox": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}