@ryan_nookpi/pi-extension-subagent 0.3.0 → 0.3.1

package/commands.ts

@@ -42,6 +42,7 @@ import {
 } from "./group-pending.js";
 import { enqueueSubagentInvocation } from "./invocation-queue.js";
 import { appendDisplayTaskUpdate, getSessionFileSize } from "./persisted-session.js";
+import { SUBAGENT_COMMANDS, type SubagentCommandName } from "./registration-manifest.js";
 import { readSessionReplayItems, SubagentSessionReplayOverlay } from "./replay.js";
 import { invokeWithAutoRetry, MAX_SUBAGENT_AUTO_RETRIES } from "./retry.js";
 import { getLatestRun, removeRun, trimCommandRunHistory } from "./run-utils.js";
@@ -890,7 +891,18 @@ function finalizeHumanOnlyCompletion(
 	store.globalLiveRuns.delete(runId);
 }
 
-export function registerAll(pi: ExtensionAPI, store: SubagentStore): void {
+export type SubagentCommandDefinition = Parameters<ExtensionAPI["registerCommand"]>[1];
+
+export interface SubagentRegistrations {
+	commands: ReadonlyMap<SubagentCommandName, SubagentCommandDefinition>;
+}
+
+export function registerAll(pi: ExtensionAPI, store: SubagentStore): SubagentRegistrations {
+	const commandDefinitions = new Map<SubagentCommandName, SubagentCommandDefinition>();
+	const defineCommand = (name: SubagentCommandName, definition: SubagentCommandDefinition): void => {
+		commandDefinitions.set(name, definition);
+	};
+
 	pi.registerTool({
 		name: "list-agents",
 		label: "List Agents",
@@ -958,8 +970,7 @@ export function registerAll(pi: ExtensionAPI, store: SubagentStore): void {
 	});
 
 	const subCommand = {
-		description:
-			"Run a subagent in a dedicated sub-session: /sub:isolate <agent|alias> <task>, /sub:isolate <runId> <task>, /sub:isolate <task> (uses configured defaultAgent)",
+		description: SUBAGENT_COMMANDS["sub:isolate"],
 		getArgumentCompletions: (argumentPrefix: string) => {
 			const trimmedStart = argumentPrefix.trimStart();
 			if (trimmedStart.includes(" ")) return null;
@@ -1574,10 +1585,10 @@ export function registerAll(pi: ExtensionAPI, store: SubagentStore): void {
 		},
 	};
 
-	pi.registerCommand("sub:isolate", subCommand);
+	defineCommand("sub:isolate", subCommand);
 
-	pi.registerCommand("sub:main", {
-		description: "Run a subagent with main-session context inheritance: /sub:main <agent|alias> <task>",
+	defineCommand("sub:main", {
+		description: SUBAGENT_COMMANDS["sub:main"],
 		getArgumentCompletions: subCommand.getArgumentCompletions,
 		handler: async (args, ctx) => {
 			captureSwitchSession(store, ctx);
@@ -1586,8 +1597,8 @@ export function registerAll(pi: ExtensionAPI, store: SubagentStore): void {
 		},
 	});
 
-	pi.registerCommand("subagents", {
-		description: "List available subagents and offer the starter pack when none are configured",
+	defineCommand("subagents", {
+		description: SUBAGENT_COMMANDS.subagents,
 		handler: async (_args, ctx) => {
 			captureSwitchSession(store, ctx);
 			const starterPack = await offerStarterPackIfEmpty(ctx);
@@ -1619,8 +1630,8 @@ export function registerAll(pi: ExtensionAPI, store: SubagentStore): void {
 		},
 	});
 
-	pi.registerCommand("sub:peek", {
-		description: "Show the latest response from a subagent in an overlay: /sub:peek [runId]",
+	defineCommand("sub:peek", {
+		description: SUBAGENT_COMMANDS["sub:peek"],
 		getArgumentCompletions: (argumentPrefix) => {
 			const trimmedStart = argumentPrefix.trimStart();
 			if (trimmedStart.includes(" ")) return null;
@@ -1643,8 +1654,8 @@ export function registerAll(pi: ExtensionAPI, store: SubagentStore): void {
 		},
 	});
 
-	pi.registerCommand("sub:open", {
-		description: "Open a subagent session replay overlay: /sub:open [runId]",
+	defineCommand("sub:open", {
+		description: SUBAGENT_COMMANDS["sub:open"],
 		getArgumentCompletions: (argumentPrefix) => {
 			const trimmedStart = argumentPrefix.trimStart();
 			if (trimmedStart.includes(" ")) return null;
@@ -1735,8 +1746,8 @@ export function registerAll(pi: ExtensionAPI, store: SubagentStore): void {
 		},
 	});
 
-	pi.registerCommand("sub:history", {
-		description: "Show all subagent run history (including removed) in an overlay: /sub:history",
+	defineCommand("sub:history", {
+		description: SUBAGENT_COMMANDS["sub:history"],
 		handler: async (_args, ctx) => {
 			captureSwitchSession(store, ctx);
 
@@ -1787,8 +1798,8 @@ export function registerAll(pi: ExtensionAPI, store: SubagentStore): void {
 		},
 	});
 
-	pi.registerCommand("sub:rm", {
-		description: "Remove one /sub job entry (aborts it if running): /sub:rm [runId]",
+	defineCommand("sub:rm", {
+		description: SUBAGENT_COMMANDS["sub:rm"],
 		handler: async (args, ctx) => {
 			captureSwitchSession(store, ctx);
 			const raw = (args ?? "").trim();
@@ -1871,8 +1882,8 @@ export function registerAll(pi: ExtensionAPI, store: SubagentStore): void {
 		ctx.ui.notify(`Cleared ${removed} finished subagent job(s).`, "info");
 	};
 
-	pi.registerCommand("sub:clear", {
-		description: "Clear /sub job widget entries. /sub:clear (finished only) or /sub:clear all",
+	defineCommand("sub:clear", {
+		description: SUBAGENT_COMMANDS["sub:clear"],
 		handler: async (args, ctx) => {
 			await handleSubClear(args, ctx);
 		},
@@ -1947,23 +1958,16 @@ export function registerAll(pi: ExtensionAPI, store: SubagentStore): void {
 		ctx.ui.notify("Usage: /sub:abort [runId|all]", "info");
 	};
 
-	pi.registerCommand("sub:abort", {
-		description: "Abort running subagent job(s). /sub:abort [runId|all]",
+	defineCommand("sub:abort", {
+		description: SUBAGENT_COMMANDS["sub:abort"],
 		handler: async (args, ctx) => {
 			captureSwitchSession(store, ctx);
 			await handleSubAbort(args, ctx);
 		},
 	});
 
-	// Only actual keyboard shortcuts appear in the /hotkeys Extensions section.
-	// NOTE: plain ">" is a real keybinding and hijacks editor text input,
-	// so the hidden subagent prefix is documented via footer/status hints instead.
-	pi.registerShortcut(">>" as any, {
-		description: "Run subagent task",
-		handler: async () => {
-			// Documentation-only entry.
-		},
-	});
+	// Text-prefix shortcuts are registered synchronously in index.ts for
+	// /hotkeys visibility. Their actual routing remains in the input handlers below.
 
 	pi.on("input", async (event, ctx) => {
 		if (event.source === "extension") {
@@ -2073,13 +2077,6 @@ export function registerAll(pi: ExtensionAPI, store: SubagentStore): void {
 	});
 
 	// #<runId> shortcut: resume a subagent run (e.g. #42 keep going)
-	pi.registerShortcut("#<runId>" as any, {
-		description: "Resume subagent run: #<runId> <task>",
-		handler: async () => {
-			// Documentation-only entry.
-		},
-	});
-
 	pi.on("input", async (event, ctx) => {
 		if (event.source === "extension") {
 			return { action: "continue" as const };
@@ -2126,20 +2123,6 @@ export function registerAll(pi: ExtensionAPI, store: SubagentStore): void {
 	});
 
 	// << shortcut: abort running jobs or clear finished jobs
-	pi.registerShortcut("<<" as any, {
-		description: "Abort or clear subagent runs",
-		handler: async () => {
-			// Documentation-only entry.
-		},
-	});
-
-	pi.registerShortcut("<<<" as any, {
-		description: "Clear finished subagent jobs (= /sub:clear). <<< all to clear all",
-		handler: async () => {
-			// Documentation-only entry.
-		},
-	});
-
 	pi.on("input", async (event, ctx) => {
 		if (event.source === "extension") {
 			return { action: "continue" as const };
@@ -2226,6 +2209,15 @@ export function registerAll(pi: ExtensionAPI, store: SubagentStore): void {
 		ctx.ui.notify(parts.join(", ") || "Nothing to do.", parts.length ? (aborted ? "warning" : "info") : "info");
 		return { action: "handled" as const };
 	});
+
+	const missingCommands = (Object.keys(SUBAGENT_COMMANDS) as SubagentCommandName[]).filter(
+		(name) => !commandDefinitions.has(name),
+	);
+	if (missingCommands.length > 0) {
+		throw new Error(`Missing subagent command definitions: ${missingCommands.join(", ")}`);
+	}
+
+	return { commands: commandDefinitions };
 }
 
 // ── onTerminalInput hack: auto-redirect <>7 to /sub:peek 7 ───────────

package/index.ts

@@ -29,10 +29,12 @@
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { HANG_CHECK_INTERVAL_MS } from "./constants.js";
+import { SUBAGENT_COMMANDS, SUBAGENT_SHORTCUTS, type SubagentCommandName } from "./registration-manifest.js";
 
 interface SubagentCore {
 	store: import("./store.js").SubagentStore;
 	commands: typeof import("./commands.js");
+	registrations: import("./commands.js").SubagentRegistrations;
 	escalation: typeof import("./escalation.js");
 	lifecycle: typeof import("./lifecycle.js");
 }
@@ -52,10 +54,13 @@ export default function (pi: ExtensionAPI) {
 				import("./store.js"),
 			]);
 			const store = storeMod.createStore();
-			commands.registerAll(pi, store);
-			core = { store, commands, escalation, lifecycle };
+			const registrations = commands.registerAll(pi, store);
+			core = { store, commands, registrations, escalation, lifecycle };
 			return core;
-		})();
+		})().catch((error) => {
+			corePromise = null;
+			throw error;
+		});
 		return corePromise;
 	};
 
@@ -69,6 +74,39 @@ export default function (pi: ExtensionAPI) {
 		return chain;
 	};
 
+	const getCommandDefinition = async (name: SubagentCommandName) => {
+		const loaded = await loadCore();
+		await chain;
+		const definition = loaded.registrations.commands.get(name);
+		if (!definition) throw new Error(`Subagent command definition not found: ${name}`);
+		return definition;
+	};
+
+	// Register lightweight proxies synchronously so Pi's initial autocomplete
+	// and command registry contain every subagent command before lazy core load.
+	for (const [name, description] of Object.entries(SUBAGENT_COMMANDS) as Array<[SubagentCommandName, string]>) {
+		pi.registerCommand(name, {
+			description,
+			getArgumentCompletions: async (prefix) => {
+				const definition = await getCommandDefinition(name);
+				return definition.getArgumentCompletions?.(prefix) ?? null;
+			},
+			handler: async (args, ctx) => {
+				const definition = await getCommandDefinition(name);
+				return definition.handler(args, ctx);
+			},
+		});
+	}
+
+	// These entries document text-prefix shortcuts in /hotkeys. Actual routing
+	// remains in commands.ts input handlers after the lazy core is loaded.
+	for (const [shortcut, description] of Object.entries(SUBAGENT_SHORTCUTS)) {
+		pi.registerShortcut(shortcut as never, {
+			description,
+			handler: async () => {},
+		});
+	}
+
 	// Start loading in the background without blocking extension boot.
 	// setTimeout keeps the load out of the boot path's microtask drains.
 	setTimeout(() => {

package/package.json

@@ -1,98 +1,99 @@
 {
-	"name": "@ryan_nookpi/pi-extension-subagent",
-	"version": "0.3.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",
-		"lifecycle.ts",
-		"invocation-queue.ts",
-		"live-preview.ts",
-		"persisted-session.ts",
-		"replay.ts",
-		"retry.ts",
-		"run-utils.ts",
-		"runner.ts",
-		"session.ts",
-		"starter-pack.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",
-		"seeds",
-		"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"
-	}
-}
+  "name": "@ryan_nookpi/pi-extension-subagent",
+  "version": "0.3.1",
+  "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",
+    "lifecycle.ts",
+    "invocation-queue.ts",
+    "live-preview.ts",
+    "persisted-session.ts",
+    "replay.ts",
+    "registration-manifest.ts",
+    "retry.ts",
+    "run-utils.ts",
+    "runner.ts",
+    "session.ts",
+    "starter-pack.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",
+    "seeds",
+    "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"
+  }
+}

package/registration-manifest.ts

@@ -0,0 +1,23 @@
+export const SUBAGENT_COMMANDS = {
+	"sub:isolate":
+		"Run a subagent in a dedicated sub-session: /sub:isolate <agent|alias> <task>, /sub:isolate <runId> <task>, /sub:isolate <task> (uses configured defaultAgent)",
+	"sub:main": "Run a subagent with main-session context inheritance: /sub:main <agent|alias> <task>",
+	subagents: "List available subagents and offer the starter pack when none are configured",
+	"sub:peek": "Show the latest response from a subagent in an overlay: /sub:peek [runId]",
+	"sub:open": "Open a subagent session replay overlay: /sub:open [runId]",
+	"sub:history": "Show all subagent run history (including removed) in an overlay: /sub:history",
+	"sub:rm": "Remove one /sub job entry (aborts it if running): /sub:rm [runId]",
+	"sub:clear": "Clear /sub job widget entries. /sub:clear (finished only) or /sub:clear all",
+	"sub:abort": "Abort running subagent job(s). /sub:abort [runId|all]",
+} as const;
+
+export type SubagentCommandName = keyof typeof SUBAGENT_COMMANDS;
+
+export const SUBAGENT_SHORTCUTS = {
+	">>": "Run subagent task",
+	"#<runId>": "Resume subagent run: #<runId> <task>",
+	"<<": "Abort or clear subagent runs",
+	"<<<": "Clear finished subagent jobs (= /sub:clear). <<< all to clear all",
+} as const;
+
+export type SubagentShortcutName = keyof typeof SUBAGENT_SHORTCUTS;