@yandy0725/pi-subagents 0.1.0

package/src/runtime.ts

@@ -0,0 +1,77 @@
+/**
+ * runtime.ts — SubagentRuntime: composition root for all mutable extension state.
+ *
+ * Eliminates module-scope state in agent-runner.ts and closure-scoped state
+ * in index.ts by consolidating them into a single, testable object.
+ * Follows the same pattern as pi-permission-system's ExtensionRuntime.
+ */
+
+import { buildParentSnapshot, type ParentSnapshot } from "./lifecycle/parent-snapshot";
+import type { ModelInfo } from "./tools/spawn-config";
+import type { SessionContext } from "./types";
+
+/**
+ * Narrow config subset read by Agent when driving the turn loop (defaultMaxTurns, graceTurns).
+ * Kept separate so callers can satisfy it without depending on the full runtime.
+ */
+export interface RunConfig {
+	readonly defaultMaxTurns: number | undefined;
+	readonly graceTurns: number;
+}
+
+/**
+ * All mutable state owned by the pi-subagents extension.
+ *
+ * Created once inside `piSubagentsExtension()` via `createSubagentRuntime()`.
+ * Tests construct a fresh runtime per test for full isolation.
+ */
+export class SubagentRuntime {
+	// ── Session state (was closure-scoped in index.ts) ───────────────────────
+	/** Active Pi session context — set on session_start, cleared on session_shutdown. */
+	currentCtx: SessionContext | undefined = undefined;
+
+	// ── Session-context methods ──────────────────────────────────────────────
+
+	/** Store the active Pi session context (called from session_start). */
+	setSessionContext(ctx: SessionContext): void {
+		this.currentCtx = ctx;
+	}
+
+	/** Clear the session context (called from session_shutdown). */
+	clearSessionContext(): void {
+		this.currentCtx = undefined;
+	}
+
+	/**
+	 * Build a parent snapshot from the current session context.
+	 * Only valid during an active session (currentCtx is defined).
+	 */
+	buildSnapshot(inheritContext: boolean): ParentSnapshot {
+		return buildParentSnapshot(this.currentCtx!, inheritContext);
+	}
+
+	/** Extract model info from the current session context. */
+	getModelInfo(): ModelInfo {
+		return {
+			parentModel: this.currentCtx?.model as ModelInfo["parentModel"],
+			modelRegistry: this.currentCtx?.modelRegistry,
+		};
+	}
+
+	/** Extract session identity from the current session context. */
+	getSessionInfo(): { parentSessionFile: string; parentSessionId: string } {
+		return {
+			parentSessionFile: this.currentCtx?.sessionManager.getSessionFile() ?? "",
+			parentSessionId: this.currentCtx?.sessionManager.getSessionId() ?? "",
+		};
+	}
+}
+
+/**
+ * Create a fully-initialized SubagentRuntime with default values.
+ *
+ * Call once at extension startup; pass the result to factories and handlers.
+ */
+export function createSubagentRuntime(): SubagentRuntime {
+	return new SubagentRuntime();
+}

package/src/service/service-adapter.ts

@@ -0,0 +1,131 @@
+/**
+ * service-adapter.ts — Adapter that wraps SubagentManager to satisfy SubagentsService.
+ *
+ * Handles model resolution at the API boundary, record serialization
+ * (stripping non-serializable fields), and session gating.
+ */
+
+import type { ParentSnapshot } from "../lifecycle/parent-snapshot";
+import type { WorkspaceProvider } from "../lifecycle/workspace";
+import type { SpawnOptions, SubagentRecord, SubagentsService } from "../service/service";
+import type { ModelRegistry } from "../session/model-resolver";
+import type { SessionContext, Subagent } from "../types";
+
+/** Narrow interface for the SubagentManager — avoids coupling to the concrete class. */
+export interface SubagentManagerLike {
+	spawn(snapshot: ParentSnapshot, type: string, prompt: string, options: unknown): string;
+	getRecord(id: string): Subagent | undefined;
+	listAgents(): Subagent[];
+	abort(id: string): boolean;
+	waitForAll(): Promise<void>;
+	hasRunning(): boolean;
+	registerWorkspaceProvider(provider: WorkspaceProvider): () => void;
+}
+
+/**
+ * Narrow runtime interface consumed by the service adapter.
+ * `SubagentRuntime` satisfies this structurally; tests use plain stubs.
+ */
+export interface ServiceRuntimeLike {
+	readonly currentCtx: SessionContext | undefined;
+	buildSnapshot(inheritContext: boolean): ParentSnapshot;
+}
+
+/** Adapter that wraps SubagentManager to satisfy SubagentsService. */
+export class SubagentsServiceAdapter implements SubagentsService {
+	constructor(
+		private readonly manager: SubagentManagerLike,
+		private readonly resolveModel: (input: string, registry: ModelRegistry) => unknown,
+		private readonly runtime: ServiceRuntimeLike,
+	) {}
+
+	spawn(type: string, prompt: string, options?: SpawnOptions): string {
+		if (!this.runtime.currentCtx) {
+			throw new Error("No active session — cannot spawn agents outside a session.");
+		}
+
+		let model: unknown;
+		if (options?.model) {
+			const registry = this.runtime.currentCtx.modelRegistry;
+			if (!registry) {
+				throw new Error("No model registry available.");
+			}
+			const resolved = this.resolveModel(options.model, registry);
+			if (typeof resolved === "string") {
+				throw new Error(resolved);
+			}
+			model = resolved;
+		}
+
+		const description = options?.description ?? prompt.slice(0, 80);
+		const isBackground = !(options?.foreground ?? false);
+
+		const snapshot = this.runtime.buildSnapshot(options?.inheritContext ?? false);
+		return this.manager.spawn(snapshot, type, prompt, {
+			description,
+			model,
+			maxTurns: options?.maxTurns,
+			thinkingLevel: options?.thinkingLevel,
+			inheritContext: options?.inheritContext,
+			bypassQueue: options?.bypassQueue,
+			isBackground,
+		});
+	}
+
+	getRecord(id: string): SubagentRecord | undefined {
+		const record = this.manager.getRecord(id);
+		return record ? toSubagentRecord(record) : undefined;
+	}
+
+	listAgents(): SubagentRecord[] {
+		return this.manager.listAgents().map(toSubagentRecord);
+	}
+
+	abort(id: string): boolean {
+		return this.manager.abort(id);
+	}
+
+	async steer(id: string, message: string): Promise<boolean> {
+		const record = this.manager.getRecord(id);
+		if (record?.status !== "running") {
+			return false;
+		}
+		await record.steer(message);
+		return true;
+	}
+
+	async waitForAll(): Promise<void> {
+		return this.manager.waitForAll();
+	}
+
+	hasRunning(): boolean {
+		return this.manager.hasRunning();
+	}
+
+	registerWorkspaceProvider(provider: WorkspaceProvider): () => void {
+		return this.manager.registerWorkspaceProvider(provider);
+	}
+}
+
+/**
+ * Convert an internal Subagent to a serializable SubagentRecord.
+ * Uses an explicit allowlist — new fields must be opted in.
+ */
+export function toSubagentRecord(record: Subagent): SubagentRecord {
+	const out: SubagentRecord = {
+		id: record.id,
+		type: record.type,
+		description: record.description,
+		status: record.status,
+		toolUses: record.toolUses,
+		startedAt: record.startedAt,
+		lifetimeUsage: record.lifetimeUsage,
+		compactionCount: record.compactionCount,
+	};
+
+	if (record.result !== undefined) out.result = record.result;
+	if (record.error !== undefined) out.error = record.error;
+	if (record.completedAt !== undefined) out.completedAt = record.completedAt;
+
+	return out;
+}

package/src/service/service.ts

@@ -0,0 +1,123 @@
+/**
+ * service.ts — Public API surface for cross-extension access to subagents.
+ *
+ * Consumers declare this package as an optional peer dependency and use
+ * dynamic import to access the accessor functions:
+ *
+ *   const { getSubagentsService } = await import("@yandy0725/pi-subagents");
+ *   const svc = getSubagentsService();
+ *   svc?.spawn("Explore", "Check for stale TODOs");
+ */
+
+import type { SubagentStatus } from "../lifecycle/subagent";
+import type { LifetimeUsage } from "../lifecycle/usage";
+import type {
+	Workspace,
+	WorkspaceDisposeOutcome,
+	WorkspaceDisposeResult,
+	WorkspacePrepareContext,
+	WorkspaceProvider,
+} from "../lifecycle/workspace";
+
+// SubagentStatus is defined in the lifecycle layer (single home) and re-exported
+// here for the public API surface — mirrors the LifetimeUsage / workspace pattern.
+export type { SubagentStatus } from "../lifecycle/subagent";
+// Generative extension seam (ADR 0002, Phase 16 Step 2). The provider type
+// and all four collaborator types it references are re-exported by name so
+// consumers can import them directly rather than recovering them via
+// indexed-access inference (e.g. `Parameters<WorkspaceProvider["prepare"]>[0]`).
+export type {
+	LifetimeUsage,
+	Workspace,
+	WorkspaceDisposeOutcome,
+	WorkspaceDisposeResult,
+	WorkspacePrepareContext,
+	WorkspaceProvider,
+};
+
+/** Serializable snapshot of an agent's state — no live session objects. */
+export interface SubagentRecord {
+	id: string;
+	type: string;
+	description: string;
+	status: SubagentStatus;
+	result?: string;
+	error?: string;
+	toolUses: number;
+	startedAt: number;
+	completedAt?: number;
+	lifetimeUsage: LifetimeUsage;
+	compactionCount: number;
+}
+
+/** Options for spawning an agent via the service. */
+export interface SpawnOptions {
+	description?: string;
+	model?: string;
+	maxTurns?: number;
+	thinkingLevel?: string;
+	inheritContext?: boolean;
+	foreground?: boolean;
+	bypassQueue?: boolean;
+}
+
+/** The public service contract for cross-extension subagent access. */
+export interface SubagentsService {
+	/** Spawn an agent. Returns the agent ID immediately. */
+	spawn(type: string, prompt: string, options?: SpawnOptions): string;
+
+	/** Get a snapshot of an agent's current state. */
+	getRecord(id: string): SubagentRecord | undefined;
+
+	/** List all tracked agents, most recent first. */
+	listAgents(): SubagentRecord[];
+
+	/** Abort a running or queued agent. Returns false if not found. */
+	abort(id: string): boolean;
+
+	/** Send a steering message to a running agent. */
+	steer(id: string, message: string): Promise<boolean>;
+
+	/** Wait for all running and queued agents to complete. */
+	waitForAll(): Promise<void>;
+
+	/** Whether any agents are running or queued. */
+	hasRunning(): boolean;
+
+	/**
+	 * Register the single workspace provider that supplies a child's working
+	 * directory plus bracketed setup/teardown. Throws if one is already
+	 * registered. Returns a disposer that unregisters the provider.
+	 */
+	registerWorkspaceProvider(provider: WorkspaceProvider): () => void;
+}
+
+/** Event channel constants for pi.events subscriptions. */
+export const SUBAGENT_EVENTS = {
+	STARTED: "subagents:started",
+	COMPLETED: "subagents:completed",
+	FAILED: "subagents:failed",
+	COMPACTED: "subagents:compacted",
+	CREATED: "subagents:created",
+	STEERED: "subagents:steered",
+} as const;
+
+// ---- Accessor functions ----
+
+const SERVICE_KEY = Symbol.for("@yandy0725/pi-subagents:service");
+
+/** Publish the SubagentsService on globalThis for cross-extension access. */
+export function publishSubagentsService(service: SubagentsService): void {
+	(globalThis as Record<symbol, unknown>)[SERVICE_KEY] = service;
+}
+
+/** Retrieve the published SubagentsService, or undefined if not yet published. */
+export function getSubagentsService(): SubagentsService | undefined {
+	return (globalThis as Record<symbol, unknown>)[SERVICE_KEY] as SubagentsService | undefined;
+}
+
+/** Remove the SubagentsService from globalThis (call on shutdown/reload). */
+export function unpublishSubagentsService(): void {
+	// eslint-disable-next-line @typescript-eslint/no-dynamic-delete -- Symbol-keyed global property; Map.delete() is not applicable
+	delete (globalThis as Record<symbol, unknown>)[SERVICE_KEY];
+}

package/src/session/content-items.ts

@@ -0,0 +1,51 @@
+/**
+ * content-items.ts — Shared parsing utilities for Pi SDK message content items.
+ *
+ * Provides type-safe extraction of text parts and tool-call names from
+ * assistant message content arrays. Pure functions — no IO.
+ */
+
+import type { TextContent, ToolCall } from "@earendil-works/pi-ai";
+
+// ── Types ─────────────────────────────────────────────────────────────────────
+
+/** Extracted text parts and tool names from assistant message content. */
+export interface AssistantContentParts {
+	textParts: string[];
+	toolNames: string[];
+}
+
+// ── Functions ─────────────────────────────────────────────────────────────────
+
+/**
+ * Extracts the display name from a tool-call content item.
+ *
+ * Returns 'unknown' for non-toolCall items.
+ * The Pi SDK's ToolCall.name is always present — no fallback chain needed.
+ */
+export function getToolCallName(c: { type: string }): string {
+	if (c.type !== "toolCall") return "unknown";
+	return (c as ToolCall).name;
+}
+
+/**
+ * Extract text parts and tool-call names from assistant message content items.
+ *
+ * Accepts any array whose elements carry a `type` discriminant — all Pi SDK
+ * content types (TextContent, ThinkingContent, ToolCall) satisfy this constraint.
+ * Pure data extraction — consumers apply their own presentation formatting.
+ * Skips items of unknown types (e.g. thinking blocks, images) and empty text.
+ */
+export function extractAssistantContent(content: ReadonlyArray<{ type: string }>): AssistantContentParts {
+	const textParts: string[] = [];
+	const toolNames: string[] = [];
+	for (const c of content) {
+		if (c.type === "text") {
+			const text = (c as TextContent).text;
+			if (text) textParts.push(text);
+		} else if (c.type === "toolCall") {
+			toolNames.push(getToolCallName(c));
+		}
+	}
+	return { textParts, toolNames };
+}

package/src/session/context.ts

@@ -0,0 +1,78 @@
+/**
+ * context.ts — Extract parent conversation context for subagent inheritance.
+ */
+
+import type { TextContent } from "@earendil-works/pi-ai";
+import type { SessionContext } from "../types";
+
+/**
+ * Minimal structural types for session branch entries consumed by buildParentContext.
+ * `getBranch()` returns `unknown[]` in SessionContext (ISP), so we cast to these
+ * local shapes instead of coupling to the SDK's SessionEntry type.
+ */
+type MessageEntry = {
+	type: "message";
+	message: { role: string; content: string | { type: string }[] };
+};
+type CompactionEntry = { type: "compaction"; summary?: string };
+type BranchEntry = MessageEntry | CompactionEntry | { type: string };
+
+/** Type predicate: narrow an unknown content block to TextContent. */
+function isTextContent(c: unknown): c is TextContent {
+	return typeof c === "object" && c !== null && (c as { type: string }).type === "text";
+}
+
+/** Extract text from a message content block array. */
+export function extractText(content: unknown[]): string {
+	return content
+		.filter(isTextContent)
+		.map((c) => c.text)
+		.join("\n");
+}
+
+/** Format a message entry (user/assistant); returns undefined for roles to skip. */
+function formatMessageEntry(entry: MessageEntry): string | undefined {
+	const msg = entry.message;
+	const text = typeof msg.content === "string" ? msg.content : extractText(msg.content);
+	if (!text.trim()) return undefined;
+	if (msg.role === "user") return `[User]: ${text.trim()}`;
+	if (msg.role === "assistant") return `[Assistant]: ${text.trim()}`;
+	return undefined; // skip toolResult and other roles
+}
+
+/** Format a compaction entry; returns undefined when no summary is present. */
+function formatCompactionEntry(entry: CompactionEntry): string | undefined {
+	return entry.summary ? `[Summary]: ${entry.summary}` : undefined;
+}
+
+/** Dispatch a branch entry to the appropriate formatter. */
+function formatBranchEntry(entry: BranchEntry): string | undefined {
+	if (entry.type === "message") return formatMessageEntry(entry as MessageEntry);
+	if (entry.type === "compaction") return formatCompactionEntry(entry as CompactionEntry);
+	return undefined;
+}
+
+/**
+ * Build a text representation of the parent conversation context.
+ * Used when inherit_context is true to give the subagent visibility
+ * into what has been discussed/done so far.
+ */
+export function buildParentContext(ctx: SessionContext): string {
+	const entries = ctx.sessionManager.getBranch();
+	// eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- getBranch() may return undefined at runtime despite its type
+	if (!entries || entries.length === 0) return "";
+
+	const parts = (entries as BranchEntry[]).map(formatBranchEntry).filter((p): p is string => p !== undefined);
+
+	if (parts.length === 0) return "";
+
+	return `# Parent Conversation Context
+The following is the conversation history from the parent session that spawned you.
+Use this context to understand what has been discussed and decided so far.
+
+${parts.join("\n\n")}
+
+---
+# Your Task (below)
+`;
+}

package/src/session/conversation.ts

@@ -0,0 +1,44 @@
+/**
+ * conversation.ts — Render a subagent session's messages as formatted text.
+ *
+ * Extracted from agent-runner.ts (issue #265) into the session domain, where the
+ * other message-extraction helpers (content-items, context) live. Consumed by
+ * the get_subagent_result tool's verbose output.
+ */
+
+import type { AgentSession } from "@earendil-works/pi-coding-agent";
+import { extractAssistantContent } from "../session/content-items";
+import { extractText } from "../session/context";
+
+/**
+ * Get the subagent's conversation messages as formatted text.
+ */
+export function getAgentConversation(session: AgentSession): string {
+	const parts: string[] = [];
+
+	for (const msg of session.messages) {
+		if (msg.role === "user") {
+			const text = typeof msg.content === "string" ? msg.content : extractText(msg.content);
+			if (text.trim()) parts.push(`[User]: ${text.trim()}`);
+		} else if (msg.role === "assistant") {
+			const { textParts, toolNames } = extractAssistantContent(msg.content);
+			const attribution = formatAttribution(msg);
+			if (textParts.length > 0) parts.push(`[Assistant${attribution}]: ${textParts.join("\n")}`);
+			if (toolNames.length > 0) parts.push(`[Tool Calls]:\n${toolNames.map((n) => `  Tool: ${n}`).join("\n")}`);
+		} else if (msg.role === "toolResult") {
+			const text = extractText(msg.content);
+			const truncated = text.length > 200 ? text.slice(0, 200) + "..." : text;
+			parts.push(`[Tool Result (${msg.toolName})]: ${truncated}`);
+		}
+	}
+
+	return parts.join("\n\n");
+}
+
+/** Build a `(provider/model)` attribution suffix for assistant messages. */
+function formatAttribution(msg: { provider?: string; model?: string }): string {
+	const { provider, model } = msg;
+	if (!provider && !model) return "";
+	if (provider && model) return ` (${provider}/${model})`;
+	return ` (${provider ?? model})`;
+}

package/src/session/env.ts

@@ -0,0 +1,40 @@
+/**
+ * env.ts — Detect environment info (git, platform) for subagent system prompts.
+ */
+
+import { debugLog } from "../debug";
+import type { ShellExec } from "../types";
+
+export interface EnvInfo {
+	isGitRepo: boolean;
+	branch: string;
+	platform: string;
+}
+
+export async function detectEnv(exec: ShellExec, cwd: string): Promise<EnvInfo> {
+	let isGitRepo = false;
+	let branch = "";
+
+	try {
+		const result = await exec("git", ["rev-parse", "--is-inside-work-tree"], { cwd, timeout: 5000 });
+		isGitRepo = result.code === 0 && result.stdout.trim() === "true";
+	} catch (err) {
+		debugLog("git rev-parse", err);
+	}
+
+	if (isGitRepo) {
+		try {
+			const result = await exec("git", ["branch", "--show-current"], { cwd, timeout: 5000 });
+			branch = result.code === 0 ? result.stdout.trim() : "unknown";
+		} catch (err) {
+			debugLog("git branch", err);
+			branch = "unknown";
+		}
+	}
+
+	return {
+		isGitRepo,
+		branch,
+		platform: process.platform,
+	};
+}

package/src/session/model-resolver.ts

@@ -0,0 +1,121 @@
+/* eslint-disable @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-redundant-type-constituents -- Pi SDK types are not fully exported; see upstream Pi SDK for type improvements */
+/**
+ * Model resolution: exact match ("provider/modelId") with fuzzy fallback.
+ */
+
+export interface ModelEntry {
+	id: string;
+	name: string;
+	provider: string;
+}
+
+export interface ModelRegistry {
+	find(provider: string, modelId: string): any;
+	getAll(): any[];
+	getAvailable?(): any[];
+}
+
+/** Successful model resolution — `model` is the resolved or inherited model instance. */
+export interface ModelResolutionResult {
+	model: any;
+	error?: undefined;
+}
+
+/** Failed model resolution when the model was user-specified (params) — surface the error. */
+export interface ModelResolutionError {
+	model?: undefined;
+	error: string;
+}
+
+/** Discriminated union returned by `resolveInvocationModel`. */
+export type ModelResolution = ModelResolutionResult | ModelResolutionError;
+
+/**
+ * Resolve the effective model for an agent invocation.
+ *
+ * Encapsulates the three-branch fallback policy used in `Agent.execute`:
+ * 1. No `modelInput` → inherit `parentModel`.
+ * 2. `modelInput` resolves → return the resolved model.
+ * 3. `modelInput` fails:
+ *    - `modelFromParams` true  → return `{ error }` so the caller can surface it.
+ *    - `modelFromParams` false → silent fallback to `parentModel`.
+ */
+export function resolveInvocationModel(
+	parentModel: unknown,
+	modelInput: string | undefined,
+	modelFromParams: boolean,
+	registry: ModelRegistry,
+): ModelResolution {
+	if (!modelInput) return { model: parentModel };
+	const resolved = resolveModel(modelInput, registry);
+	if (typeof resolved !== "string") return { model: resolved };
+	if (modelFromParams) return { error: resolved };
+	return { model: parentModel };
+}
+
+/**
+ * Resolve a model string to a Model instance.
+ * Tries exact match first ("provider/modelId"), then fuzzy match against all available models.
+ * Returns the Model on success, or an error message string on failure.
+ */
+export function resolveModel(input: string, registry: ModelRegistry): any | string {
+	// Available models (those with auth configured)
+	const all = (registry.getAvailable?.() ?? registry.getAll()) as ModelEntry[];
+	const availableSet = new Set(all.map((m) => `${m.provider}/${m.id}`.toLowerCase()));
+
+	// 1. Exact match: "provider/modelId" — only if available (has auth)
+	const slashIdx = input.indexOf("/");
+	if (slashIdx !== -1) {
+		const provider = input.slice(0, slashIdx);
+		const modelId = input.slice(slashIdx + 1);
+		if (availableSet.has(input.toLowerCase())) {
+			const found = registry.find(provider, modelId);
+			if (found) return found;
+		}
+	}
+
+	// 2. Fuzzy match against available models
+	const query = input.toLowerCase();
+
+	// Score each model: prefer exact id match > id contains > name contains > provider+id contains
+	let bestMatch: ModelEntry | undefined;
+	let bestScore = 0;
+
+	for (const m of all) {
+		const id = m.id.toLowerCase();
+		const name = m.name.toLowerCase();
+		const full = `${m.provider}/${m.id}`.toLowerCase();
+
+		let score = 0;
+		if (id === query || full === query) {
+			score = 100; // exact
+		} else if (id.includes(query) || full.includes(query)) {
+			score = 60 + (query.length / id.length) * 30; // substring, prefer tighter matches
+		} else if (name.includes(query)) {
+			score = 40 + (query.length / name.length) * 20;
+		} else if (
+			query
+				.split(/[\s\-/]+/)
+				.every((part) => id.includes(part) || name.includes(part) || m.provider.toLowerCase().includes(part))
+		) {
+			score = 20; // all parts present somewhere
+		}
+
+		if (score > bestScore) {
+			bestScore = score;
+			bestMatch = m;
+		}
+	}
+
+	if (bestMatch && bestScore >= 20) {
+		const found = registry.find(bestMatch.provider, bestMatch.id);
+		if (found) return found;
+	}
+
+	// 3. No match — list available models
+	const modelList = all
+		.map((m) => `  ${m.provider}/${m.id}`)
+		.sort()
+		.join("\n");
+	return `Model not found: "${input}".\n\nAvailable models:\n${modelList}`;
+}