@yandy0725/pi-subagents 0.1.0

package/src/config/default-agents.ts

@@ -0,0 +1,117 @@
+/**
+ * default-agents.ts — Embedded default agent configurations.
+ *
+ * These are always available but can be overridden by user .md files with the same name.
+ */
+
+import type { AgentConfig } from "../types";
+
+const READ_ONLY_TOOLS = ["read", "bash", "grep", "find", "ls"];
+
+export const DEFAULT_AGENTS: Map<string, AgentConfig> = new Map([
+	[
+		"general-purpose",
+		{
+			name: "general-purpose",
+			displayName: "Agent",
+			description: "General-purpose agent for complex, multi-step tasks",
+			// builtinToolNames omitted — means "all available tools" (resolved at lookup time)
+			// inheritContext / runInBackground omitted — strategy fields, callers decide per-call.
+			// Setting them to false would lock callsite intent (see resolveAgentInvocationConfig in invocation-config.ts).
+			systemPrompt: "",
+			promptMode: "append",
+			isDefault: true,
+		},
+	],
+	[
+		"Explore",
+		{
+			name: "Explore",
+			displayName: "Explore",
+			description: "Fast codebase exploration agent (read-only)",
+			builtinToolNames: READ_ONLY_TOOLS,
+			model: "anthropic/claude-haiku-4-5-20251001",
+			systemPrompt: `# CRITICAL: READ-ONLY MODE - NO FILE MODIFICATIONS
+You are a file search specialist. You excel at thoroughly navigating and exploring codebases.
+Your role is EXCLUSIVELY to search and analyze existing code. You do NOT have access to file editing tools.
+
+You are STRICTLY PROHIBITED from:
+- Creating new files
+- Modifying existing files
+- Deleting files
+- Moving or copying files
+- Creating temporary files anywhere, including /tmp
+- Using redirect operators (>, >>, |) or heredocs to write to files
+- Running ANY commands that change system state
+
+Use Bash ONLY for read-only operations: ls, git status, git log, git diff, find, cat, head, tail.
+
+# Tool Usage
+- Use the find tool for file pattern matching (NOT the bash find command)
+- Use the grep tool for content search (NOT bash grep/rg command)
+- Use the read tool for reading files (NOT bash cat/head/tail)
+- Use Bash ONLY for read-only operations
+- Make independent tool calls in parallel for efficiency
+- Adapt search approach based on thoroughness level specified
+
+# Output
+- Use absolute file paths in all references
+- Report findings as regular messages
+- Do not use emojis
+- Be thorough and precise`,
+			promptMode: "replace",
+			isDefault: true,
+		},
+	],
+	[
+		"Plan",
+		{
+			name: "Plan",
+			displayName: "Plan",
+			description: "Software architect for implementation planning (read-only)",
+			builtinToolNames: READ_ONLY_TOOLS,
+			systemPrompt: `# CRITICAL: READ-ONLY MODE - NO FILE MODIFICATIONS
+You are a software architect and planning specialist.
+Your role is EXCLUSIVELY to explore the codebase and design implementation plans.
+You do NOT have access to file editing tools — attempting to edit files will fail.
+
+You are STRICTLY PROHIBITED from:
+- Creating new files
+- Modifying existing files
+- Deleting files
+- Moving or copying files
+- Creating temporary files anywhere, including /tmp
+- Using redirect operators (>, >>, |) or heredocs to write to files
+- Running ANY commands that change system state
+
+# Planning Process
+1. Understand requirements
+2. Explore thoroughly (read files, find patterns, understand architecture)
+3. Design solution based on your assigned perspective
+4. Detail the plan with step-by-step implementation strategy
+
+# Requirements
+- Consider trade-offs and architectural decisions
+- Identify dependencies and sequencing
+- Anticipate potential challenges
+- Follow existing patterns where appropriate
+
+# Tool Usage
+- Use the find tool for file pattern matching (NOT the bash find command)
+- Use the grep tool for content search (NOT bash grep/rg command)
+- Use the read tool for reading files (NOT bash cat/head/tail)
+- Use Bash ONLY for read-only operations
+
+# Output Format
+- Use absolute file paths
+- Do not use emojis
+- End your response with:
+
+### Critical Files for Implementation
+List 3-5 files most critical for implementing this plan:
+- /absolute/path/to/file.ts - [Brief reason]`,
+			promptMode: "replace",
+			isDefault: true,
+		},
+	],
+]);

package/src/config/invocation-config.ts

@@ -0,0 +1,30 @@
+import type { AgentConfig, ThinkingLevel } from "../types";
+
+interface AgentInvocationParams {
+	model?: string;
+	thinking?: string;
+	max_turns?: number;
+	run_in_background?: boolean;
+	inherit_context?: boolean;
+}
+
+export function resolveAgentInvocationConfig(
+	agentConfig: AgentConfig | undefined,
+	params: AgentInvocationParams,
+): {
+	modelInput?: string;
+	modelFromParams: boolean;
+	thinking?: ThinkingLevel;
+	maxTurns?: number;
+	inheritContext: boolean;
+	runInBackground: boolean;
+} {
+	return {
+		modelInput: agentConfig?.model ?? params.model,
+		modelFromParams: agentConfig?.model == null && params.model != null,
+		thinking: (agentConfig?.thinking ?? params.thinking) as ThinkingLevel | undefined,
+		maxTurns: agentConfig?.maxTurns ?? params.max_turns,
+		inheritContext: agentConfig?.inheritContext ?? params.inherit_context ?? false,
+		runInBackground: agentConfig?.runInBackground ?? params.run_in_background ?? false,
+	};
+}

package/src/debug.ts

@@ -0,0 +1,14 @@
+/**
+ * debug.ts — Debug logging utility for silenced catch blocks.
+ *
+ * Set PI_SUBAGENTS_DEBUG=1 to reveal silent failures in catch blocks
+ * throughout the package. Production behavior is unchanged when unset.
+ */
+
+export function isDebug(): boolean {
+	return process.env.PI_SUBAGENTS_DEBUG === "1";
+}
+
+export function debugLog(context: string, err: unknown): void {
+	if (isDebug()) console.warn(`[pi-subagents:debug] ${context}:`, err);
+}

package/src/handlers/index.ts

@@ -0,0 +1,3 @@
+export { InterruptHandler } from "../handlers/interrupt";
+export { SessionLifecycleHandler } from "../handlers/lifecycle";
+export { ToolStartHandler } from "../handlers/tool-start";

package/src/handlers/interrupt.ts

@@ -0,0 +1,49 @@
+/**
+ * turn_start event handler that aborts subagents on a parent interrupt (ESC).
+ *
+ * The parent agent loop creates a fresh AbortController per run and only aborts
+ * it on an explicit interrupt — never on normal completion. So latching to the
+ * current run's signal and aborting on its `abort` event fires exactly on ESC.
+ *
+ * `turn_start` carries the live per-run `ctx.signal`, so re-latching each turn
+ * keeps the handler tracking the current signal across runs and tool-less turns.
+ */
+
+/** Narrow manager interface — only the method the interrupt handler calls. */
+export interface InterruptManager {
+	abortAll(): number;
+}
+
+/** Minimal context shape — only the field the handler reads. */
+interface InterruptCtx {
+	signal: AbortSignal | undefined;
+}
+
+/**
+ * Latches the current parent abort signal and aborts all subagents when it fires.
+ *
+ * The latch dedups by reference: most turns reuse the same signal (no-op); a new
+ * run's signal triggers a detach-and-rewire. The `abort` listener is one-shot.
+ */
+export class InterruptHandler {
+	private latched?: AbortSignal;
+	private detach?: () => void;
+
+	constructor(private readonly manager: InterruptManager) {}
+
+	handleTurnStart(ctx: InterruptCtx): void {
+		const signal = ctx.signal;
+		if (signal === this.latched) return;
+
+		this.detach?.();
+		this.detach = undefined;
+		this.latched = signal;
+		if (!signal) return;
+
+		const onAbort = (): void => {
+			this.manager.abortAll();
+		};
+		signal.addEventListener("abort", onAbort, { once: true });
+		this.detach = () => signal.removeEventListener("abort", onAbort);
+	}
+}

package/src/handlers/lifecycle.ts

@@ -0,0 +1,63 @@
+import type { SessionContext } from "../types";
+
+/**
+ * Session lifecycle event handlers: session_start, session_before_switch, session_shutdown.
+ *
+ * Extracted from index.ts so each handler can be tested in isolation
+ * with mocked narrow interfaces.
+ */
+
+/** Narrow manager interface — only the methods lifecycle handlers call. */
+export interface LifecycleManager {
+	clearCompleted(): void;
+	abortAll(): void;
+	dispose(): void;
+}
+
+/** Narrow runtime interface — only the methods lifecycle handlers call. */
+export interface LifecycleRuntime {
+	setSessionContext(ctx: SessionContext): void;
+	clearSessionContext(): void;
+}
+
+/**
+ * Handles session lifecycle events.
+ *
+ * Constructor deps:
+ * - `runtime` — owns session context state
+ * - `manager` — manages agent lifecycle (clear, abort, dispose)
+ * - `disposeNotifications` — tears down the notification system on shutdown
+ * - `unpublishService` — unpublishes the SubagentsService symbol on shutdown
+ */
+export class SessionLifecycleHandler {
+	constructor(
+		private readonly runtime: LifecycleRuntime,
+		private readonly manager: LifecycleManager,
+		private readonly disposeNotifications: () => void,
+		private readonly unpublishService: () => void,
+	) {}
+
+	handleSessionStart(_event: unknown, ctx: unknown): void {
+		this.runtime.setSessionContext(ctx as SessionContext);
+		this.manager.clearCompleted();
+	}
+
+	handleSessionBeforeSwitch(): void {
+		this.manager.clearCompleted();
+	}
+
+	// Cleanup order matters:
+	// 1. Unpublish service — prevent new cross-extension calls
+	// 2. Clear session context — no more session state
+	// 3. Abort all agents — stop running work
+	// 4. Dispose notifications — cancel pending nudges/timers
+	// 5. Dispose manager — final cleanup
+	handleSessionShutdown(): Promise<void> {
+		this.unpublishService();
+		this.runtime.clearSessionContext();
+		this.manager.abortAll();
+		this.disposeNotifications();
+		this.manager.dispose();
+		return Promise.resolve();
+	}
+}

package/src/handlers/tool-start.ts

@@ -0,0 +1,32 @@
+/**
+ * tool_execution_start event handler.
+ *
+ * Extracted from index.ts so the handler can be tested in isolation
+ * with a mocked narrow runtime interface.
+ */
+
+/** Narrow widget interface — only the methods the handler calls. */
+export interface ToolStartWidget {
+	setUICtx(ctx: unknown): void;
+	onTurnStart(): void;
+}
+
+/** Minimal context shape for tool_execution_start — only the field the handler reads. */
+interface ToolStartCtx {
+	ui: unknown;
+}
+
+/**
+ * Handles tool_execution_start events.
+ *
+ * Grabs UI context from the first tool execution of each turn
+ * and signals the widget to clear lingering state.
+ */
+export class ToolStartHandler {
+	constructor(private readonly widget: ToolStartWidget) {}
+
+	handleToolExecutionStart(_event: unknown, ctx: ToolStartCtx): void {
+		this.widget.setUICtx(ctx.ui);
+		this.widget.onTurnStart();
+	}
+}

package/src/index.ts

@@ -0,0 +1,186 @@
+/* eslint-disable @typescript-eslint/no-unsafe-argument -- Pi SDK types are not fully exported; see upstream Pi SDK for type improvements */
+/**
+ * pi-agents — A pi extension providing focused, in-process autonomous sub-agents.
+ *
+ * Tools:
+ *   Agent             — LLM-callable: spawn a sub-agent
+ *   get_subagent_result  — LLM-callable: check background agent status/result
+ *   steer_subagent       — LLM-callable: send a steering message to a running agent
+ *
+ * Commands:
+ */
+
+import { readFileSync } from "node:fs";
+import {
+	createAgentSession,
+	DefaultResourceLoader,
+	type ExtensionAPI,
+	getAgentDir,
+	SettingsManager as SdkSettingsManager,
+	SessionManager,
+} from "@earendil-works/pi-coding-agent";
+import { AgentTypeRegistry } from "./config/agent-types";
+import { loadCustomAgents } from "./config/custom-agents";
+import { InterruptHandler, SessionLifecycleHandler, ToolStartHandler } from "./handlers/index";
+import { createChildLifecyclePublisher } from "./lifecycle/child-lifecycle";
+import { ConcurrencyLimiter } from "./lifecycle/concurrency-limiter";
+import { createSubagentSession, type SubagentSessionDeps } from "./lifecycle/create-subagent-session";
+import { SubagentManager } from "./lifecycle/subagent-manager";
+import { CompositeSubagentObserver } from "./observation/composite-subagent-observer";
+import { type NotificationDetails, NotificationManager } from "./observation/notification";
+import { createNotificationRenderer } from "./observation/renderer";
+import { SubagentEventsObserver } from "./observation/subagent-events-observer";
+import { createSubagentRuntime } from "./runtime";
+import { publishSubagentsService, unpublishSubagentsService } from "./service/service";
+import { SubagentsServiceAdapter } from "./service/service-adapter";
+import { detectEnv } from "./session/env";
+
+import { resolveModel } from "./session/model-resolver";
+import { buildAgentPrompt } from "./session/prompts";
+import { deriveSubagentSessionDir } from "./session/session-dir";
+import { SettingsManager } from "./settings";
+import { AgentTool } from "./tools/agent-tool";
+import { GetResultTool } from "./tools/get-result-tool";
+import { SteerTool } from "./tools/steer-tool";
+import { AgentWidget } from "./ui/agent-widget";
+import { SessionNavigatorHandler } from "./ui/session-navigator";
+import { SubagentsSettingsHandler } from "./ui/subagents-settings";
+
+export default function (pi: ExtensionAPI) {
+	// ---- Register custom notification renderer ----
+	pi.registerMessageRenderer<NotificationDetails>("subagent-notification", createNotificationRenderer());
+
+	const registry = new AgentTypeRegistry(() => loadCustomAgents(process.cwd()));
+
+	// ---- Runtime: all mutable extension state in one place ----
+	const runtime = createSubagentRuntime();
+
+	// ---- Notification system ----
+	// Owns completion nudges and live-activity cleanup. The widget detects finished
+	// agents itself (AgentWidget.update self-seeds), so NotificationManager has no
+	// widget dependency — keeping the construction graph a cycle-free DAG.
+	const notifications = new NotificationManager((msg, opts) => pi.sendMessage(msg, opts));
+
+	// Settings: owns all three in-memory values and handles load/save/emit.
+	// onMaxConcurrentChanged is wired to the limiter directly (closure captures by reference).
+	const settings = new SettingsManager({
+		emit: (event, payload) => pi.events.emit(event, payload),
+		cwd: process.cwd(),
+		agentDir: getAgentDir(),
+		onMaxConcurrentChanged: () => limiter.recheck(),
+	});
+	settings.load();
+
+	// Observer: receives agent lifecycle notifications and dispatches events/notifications.
+	const eventsObserver = new SubagentEventsObserver({
+		emit: (channel, data) => pi.events.emit(channel, data),
+		appendEntry: (customType, data) => pi.appendEntry(customType, data),
+		notifications,
+	});
+
+	// Fan-out observer: lets the widget subscribe as a second lifecycle consumer
+	// while the manager keeps its single-observer contract. The widget is added
+	// after construction (it needs the manager); the manager consults the observer
+	// only at spawn time, so registering late is safe.
+	const observer = new CompositeSubagentObserver([eventsObserver]);
+
+	const subagentSessionDeps: SubagentSessionDeps = {
+		io: {
+			detectEnv,
+			getAgentDir,
+			createResourceLoader: (opts) => new DefaultResourceLoader(opts),
+			deriveSessionDir: deriveSubagentSessionDir,
+			createSessionManager: (cwd, dir) => SessionManager.create(cwd, dir),
+			createSettingsManager: (cwd, dir) => SdkSettingsManager.create(cwd, dir),
+			createSession: (opts) => createAgentSession(opts as any),
+			assemblerIO: {
+				buildAgentPrompt,
+			},
+		},
+		exec: (cmd, args, opts) => pi.exec(cmd, args, opts),
+		registry,
+		lifecycle: createChildLifecyclePublisher((channel, data) => pi.events.emit(channel, data)),
+	};
+
+	// ConcurrencyLimiter: schedules background run thunks FIFO against the limit.
+	// It knows nothing about agents or the manager — dependency direction is strictly manager → limiter.
+	const limiter = new ConcurrencyLimiter(() => settings.maxConcurrent);
+
+	const manager = new SubagentManager({
+		createSubagentSession: (params) => createSubagentSession(params, subagentSessionDeps),
+		baseCwd: process.cwd(),
+		observer,
+		limiter,
+		getRunConfig: () => settings,
+	});
+
+	// Typed service published via Symbol.for() for cross-extension access.
+	// Consumers: const { getSubagentsService } = await import("@yandy0725/pi-subagents");
+	const service = new SubagentsServiceAdapter(manager, resolveModel, runtime);
+	publishSubagentsService(service);
+
+	const lifecycle = new SessionLifecycleHandler(
+		runtime,
+		manager,
+		() => notifications.dispose(),
+		unpublishSubagentsService,
+	);
+
+	pi.on("session_start", (event, ctx) => lifecycle.handleSessionStart(event, ctx));
+	pi.on("session_before_switch", () => lifecycle.handleSessionBeforeSwitch());
+	pi.on("session_shutdown", () => lifecycle.handleSessionShutdown());
+
+	// Live widget: constructed after the manager (it polls listAgents()) and
+	// registered as a lifecycle observer so it self-drives its update timer.
+	const widget = new AgentWidget(manager, registry);
+	observer.add(widget);
+
+	// Grab UI context from first tool execution + clear lingering widget on new turn
+	const toolStart = new ToolStartHandler(widget);
+	pi.on("tool_execution_start", (event, ctx) => toolStart.handleToolExecutionStart(event, ctx));
+
+	// Abort all subagents when the parent agent loop is interrupted (ESC).
+	const interrupt = new InterruptHandler(manager);
+	pi.on("turn_start", (_event, ctx) => interrupt.handleTurnStart(ctx));
+
+	// ---- Agent tool ----
+
+	pi.registerTool(new AgentTool(manager, runtime, settings, registry, getAgentDir()).toToolDefinition());
+
+	// ---- get_subagent_result tool ----
+
+	pi.registerTool(new GetResultTool(manager, notifications, registry).toToolDefinition());
+
+	// ---- steer_subagent tool ----
+
+	pi.registerTool(new SteerTool(manager, pi.events).toToolDefinition());
+
+	// ---- /subagents:settings command ----
+
+	const subagentsSettings = new SubagentsSettingsHandler(settings);
+
+	pi.registerCommand("subagents:settings", {
+		description: "Configure subagent settings (concurrency, turn limits)",
+		handler: async (_args, ctx) => {
+			await subagentsSettings.handle({ ui: ctx.ui });
+		},
+	});
+
+	// ---- /subagents:sessions command ----
+
+	const sessionNavigator = new SessionNavigatorHandler();
+
+	pi.registerCommand("subagents:sessions", {
+		description: "View a subagent's session transcript (read-only)",
+		handler: async (_args, ctx) => {
+			await sessionNavigator.handle({
+				ui: ctx.ui,
+				agents: manager.listAgents(),
+				evicted: manager.listEvicted(),
+				registry,
+				cwd: ctx.cwd,
+				readFile: (path) => readFileSync(path, "utf8"),
+			});
+		},
+	});
+}

package/src/layered-settings.ts

@@ -0,0 +1,105 @@
+/**
+ * Generic layered settings loader for `@yandy0725/pi-*` extensions.
+ *
+ * Extensions that store configuration in JSON files under a global agent
+ * directory and a per-project `.pi/` folder share the same three-step idiom:
+ *
+ *   1. Read the global file (`<agentDir>/<filename>`).
+ *   2. Read the project file (`<cwd>/.pi/<filename>`).
+ *   3. Merge them — project wins on conflicts — and return the result.
+ *
+ * Both layers are optional: a missing file is silent (`{}`), and a file that
+ * cannot be parsed warns to stderr and is treated as absent so startup
+ * proceeds normally.
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import { loadLayeredSettings, type LayeredSettingsSource } from "@yandy0725/pi-subagents/settings";
+ *
+ * interface MyConfig { enabled?: boolean; limit?: number }
+ *
+ * function sanitize(raw: unknown): Partial<MyConfig> {
+ *   if (!raw || typeof raw !== "object") return {};
+ *   const r = raw as Record<string, unknown>;
+ *   const out: Partial<MyConfig> = {};
+ *   if (typeof r.enabled === "boolean") out.enabled = r.enabled;
+ *   if (typeof r.limit === "number") out.limit = r.limit;
+ *   return out;
+ * }
+ *
+ * const config = loadLayeredSettings<MyConfig>({
+ *   agentDir,     // e.g. from the Pi runtime env — the agent home directory
+ *   cwd,          // project root — project file is at <cwd>/.pi/<filename>
+ *   filename: "my-extension.json",
+ *   sanitize,
+ *   warnLabel: "my-extension",
+ * });
+ * ```
+ *
+ * @public
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * Parameters for one layered settings load: describes where the files live,
+ * how to validate their contents, and what label to use in warnings.
+ *
+ * @public
+ */
+export interface LayeredSettingsSource<T> {
+	/** Directory holding the global settings file (typically the Pi agent dir). */
+	agentDir: string;
+	/** Project root; the project file lives at `<cwd>/.pi/<filename>`. */
+	cwd: string;
+	/** Base filename for both layers, e.g. `"subagents.json"`. */
+	filename: string;
+	/**
+	 * Validate and coerce parsed JSON into a partial settings object.
+	 * Unknown or invalid fields should be silently dropped — return `{}` for
+	 * unrecognised shapes. Never throw.
+	 */
+	sanitize: (raw: unknown) => Partial<T>;
+	/**
+	 * Short label used in the malformed-file warning prefix,
+	 * e.g. `"pi-subagents"` → `"[pi-subagents] Ignoring malformed settings at …"`.
+	 */
+	warnLabel: string;
+}
+
+/**
+ * Load merged layered settings: global provides defaults, project overrides.
+ *
+ * - A missing file is silent — returns `{}` for that layer.
+ * - A file that exists but cannot be parsed warns to stderr and returns `{}` for
+ *   that layer, so startup proceeds normally.
+ * - The two layers are merged with a shallow spread; project keys win.
+ *
+ * Throws nothing. All error conditions produce a warning and fall back to `{}`.
+ *
+ * @public
+ */
+export function loadLayeredSettings<T>(source: LayeredSettingsSource<T>): Partial<T> {
+	const { agentDir, cwd, filename, sanitize, warnLabel } = source;
+	const global = readLayer(join(agentDir, filename), sanitize, warnLabel);
+	const project = readLayer(join(cwd, ".pi", filename), sanitize, warnLabel);
+	return { ...global, ...project };
+}
+
+// ── Private helpers ──────────────────────────────────────────────────────────
+
+/**
+ * Read one settings file. Missing → `{}` (silent). Malformed → `{}` + warn.
+ */
+function readLayer<T>(path: string, sanitize: (raw: unknown) => Partial<T>, warnLabel: string): Partial<T> {
+	if (!existsSync(path)) return {};
+	try {
+		return sanitize(JSON.parse(readFileSync(path, "utf-8")));
+	} catch (err) {
+		const reason = err instanceof Error ? err.message : String(err);
+		console.warn(`[${warnLabel}] Ignoring malformed settings at ${path}: ${reason}`);
+		return {};
+	}
+}