@oai404iao/pi-subagent 0.2.0 → 0.4.0-alpha.0

package/src/descriptor.ts

@@ -3,23 +3,38 @@ import type { SessionEntry } from "@earendil-works/pi-coding-agent";
 import type {
 	AgentScope,
 	AgentSnapshot,
-	AgentSource,
+	AgentSnapshotSource,
+	BackgroundProtocol,
+	ContextInheritance,
 	ReportDelivery,
 	SubagentDescriptor,
 	SubagentMode,
 	SubagentProviderName,
 } from "./types.ts";
+import { validateDescriptorTask } from "./task-path.ts";
 
 export const DESCRIPTOR_CUSTOM_TYPE = "pi-subagent/descriptor";
-export const DESCRIPTOR_VERSION = 1;
+export const DESCRIPTOR_VERSION = 3;
+export const LEGACY_DESCRIPTOR_VERSION = 2;
+const LEGACY_MAX_CONCURRENT_BACKGROUND_RUNS = 4;
+const LEGACY_MAX_IDLE_RUNTIMES = 0;
+const LEGACY_BACKGROUND_PROTOCOL: BackgroundProtocol = "legacy";
 
 const THINKING_LEVELS = new Set<ThinkingLevel>(["off", "minimal", "low", "medium", "high", "xhigh", "max"]);
-const AGENT_SOURCES = new Set<AgentSource>(["bundled", "user", "project"]);
+const AGENT_SOURCES = new Set<AgentSnapshotSource>(["bundled", "user", "project"]);
 const MODES = new Set<SubagentMode>(["one-shot", "continuable"]);
 const PROVIDERS = new Set<SubagentProviderName>(["spawn", "fork"]);
 const REPORT_DELIVERIES = new Set<ReportDelivery>(["wakeup", "quiet"]);
+const BACKGROUND_PROTOCOLS = new Set<BackgroundProtocol>(["legacy", "mailbox-v2"]);
 const AGENT_SCOPES = new Set<AgentScope>(["user", "project", "both"]);
 const AGENT_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
+/** UUIDv7 with the standard RFC 9562 variant bits (version 7, variant 10xx). */
+const AGENT_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const CONTEXT_MODES = new Set<ContextInheritance["mode"]>([
+	"fresh",
+	"all_completed",
+	"last_n_completed",
+]);
 
 type UnknownRecord = Record<string, unknown>;
 
@@ -46,6 +61,14 @@ function optionalString(value: unknown, field: string): string | undefined {
 	return value === undefined ? undefined : string(value, field);
 }
 
+function agentId(value: unknown, field: string): string {
+	const parsed = string(value, field);
+	if (!AGENT_ID_PATTERN.test(parsed)) {
+		throw new Error(`${field} must be a UUIDv7 agent id`);
+	}
+	return parsed;
+}
+
 function limitedString(value: unknown, field: string, maxLength: number): string {
 	const parsed = string(value, field);
 	if (parsed.length > maxLength) throw new Error(`${field} exceeds ${maxLength} characters`);
@@ -87,7 +110,7 @@ function stringArray(value: unknown, field: string): string[] | undefined {
 
 function parseAgent(value: unknown): AgentSnapshot {
 	const input = record(value, "agent");
-	const source = string(input.source, "agent.source") as AgentSource;
+	const source = string(input.source, "agent.source") as AgentSnapshotSource;
 	if (!AGENT_SOURCES.has(source)) throw new Error(`agent.source is unsupported: ${source}`);
 	const thinking = optionalString(input.thinking, "agent.thinking") as ThinkingLevel | undefined;
 	if (thinking && !THINKING_LEVELS.has(thinking)) throw new Error(`agent.thinking is unsupported: ${thinking}`);
@@ -106,11 +129,40 @@ function parseAgent(value: unknown): AgentSnapshot {
 	};
 }
 
+function parseContext(value: unknown): ContextInheritance {
+	const input = record(value, "context");
+	const mode = string(input.mode, "context.mode") as ContextInheritance["mode"];
+	if (!CONTEXT_MODES.has(mode)) {
+		throw new Error(`unsupported context.mode: ${mode}`);
+	}
+	if (mode === "last_n_completed") {
+		return {
+			mode,
+			completedTurns: boundedInteger(
+				input.completedTurns,
+				"context.completedTurns",
+				1,
+				100,
+			),
+		};
+	}
+	if (input.completedTurns !== undefined) {
+		throw new Error(
+			"context.completedTurns is available only for last_n_completed",
+		);
+	}
+	return { mode };
+}
+
 export function parseDescriptor(value: unknown): SubagentDescriptor {
 	const input = record(value, "descriptor");
-	if (input.version !== DESCRIPTOR_VERSION) {
+	if (
+		input.version !== LEGACY_DESCRIPTOR_VERSION
+		&& input.version !== DESCRIPTOR_VERSION
+	) {
 		throw new Error(`unsupported descriptor version: ${String(input.version)}`);
 	}
+	const version = input.version;
 	const mode = string(input.mode, "mode") as SubagentMode;
 	if (!MODES.has(mode)) throw new Error(`unsupported descriptor mode: ${mode}`);
 	const provider = string(input.provider, "provider") as SubagentProviderName;
@@ -126,16 +178,29 @@ export function parseDescriptor(value: unknown): SubagentDescriptor {
 	if (!REPORT_DELIVERIES.has(reportDelivery)) {
 		throw new Error(`unsupported runtime.reportDelivery: ${reportDelivery}`);
 	}
+	const backgroundProtocol =
+		runtime.backgroundProtocol === undefined
+			? LEGACY_BACKGROUND_PROTOCOL
+			: string(runtime.backgroundProtocol, "runtime.backgroundProtocol") as BackgroundProtocol;
+	if (!BACKGROUND_PROTOCOLS.has(backgroundProtocol)) {
+		throw new Error(`unsupported runtime.backgroundProtocol: ${backgroundProtocol}`);
+	}
+	if (runtime.syncBundledAgents !== undefined) {
+		// Validate, then discard the retired 0.2/0.3 runtime switch. Keeping this
+		// read compatibility allows persisted children to cold-resume.
+		boolean(runtime.syncBundledAgents, "runtime.syncBundledAgents");
+	}
 
 	const createdAt = string(input.createdAt, "createdAt");
 	if (Number.isNaN(Date.parse(createdAt))) throw new Error("createdAt must be an ISO date string");
 
-	return {
-		version: DESCRIPTOR_VERSION,
+	const base = {
 		mode,
 		provider,
 		label: limitedString(input.label, "label", 200),
-		parentSessionId: string(input.parentSessionId, "parentSessionId"),
+		agentId: agentId(input.agentId, "agentId"),
+		parentAgentId: agentId(input.parentAgentId, "parentAgentId"),
+		parentPiSessionId: string(input.parentPiSessionId, "parentPiSessionId"),
 		...(optionalString(input.parentSessionFile, "parentSessionFile")
 			? { parentSessionFile: input.parentSessionFile as string }
 			: {}),
@@ -150,18 +215,34 @@ export function parseDescriptor(value: unknown): SubagentDescriptor {
 		thinkingLevel,
 		runtime: {
 			agentScope,
-			syncBundledAgents:
-				runtime.syncBundledAgents === undefined
-					? true
-					: boolean(runtime.syncBundledAgents, "runtime.syncBundledAgents"),
 			maxDepth: safeNatural(runtime.maxDepth, "runtime.maxDepth"),
 			enableRunInBackground:
 				runtime.enableRunInBackground === undefined
 					? true
 					: boolean(runtime.enableRunInBackground, "runtime.enableRunInBackground"),
 			defaultBackground: boolean(runtime.defaultBackground, "runtime.defaultBackground"),
+			maxConcurrentBackgroundRuns:
+				runtime.maxConcurrentBackgroundRuns === undefined
+					? LEGACY_MAX_CONCURRENT_BACKGROUND_RUNS
+					: boundedInteger(
+							runtime.maxConcurrentBackgroundRuns,
+							"runtime.maxConcurrentBackgroundRuns",
+							1,
+							Number.MAX_SAFE_INTEGER,
+						),
+			maxIdleRuntimes:
+				runtime.maxIdleRuntimes === undefined
+					? LEGACY_MAX_IDLE_RUNTIMES
+					: boundedInteger(
+							runtime.maxIdleRuntimes,
+							"runtime.maxIdleRuntimes",
+							0,
+							Number.MAX_SAFE_INTEGER,
+						),
+			backgroundProtocol,
 			reportDelivery,
 			inheritExtensions: boolean(runtime.inheritExtensions, "runtime.inheritExtensions"),
+			openAIIdentity: boolean(runtime.openAIIdentity, "runtime.openAIIdentity"),
 			maxOutputBytes: boundedInteger(
 				runtime.maxOutputBytes,
 				"runtime.maxOutputBytes",
@@ -170,6 +251,22 @@ export function parseDescriptor(value: unknown): SubagentDescriptor {
 			),
 		},
 	};
+	if (version === LEGACY_DESCRIPTOR_VERSION) {
+		return {
+			version: LEGACY_DESCRIPTOR_VERSION,
+			...base,
+		};
+	}
+	const task = record(input.task, "task");
+	return {
+		version: DESCRIPTOR_VERSION,
+		...base,
+		task: validateDescriptorTask({
+			name: string(task.name, "task.name"),
+			path: string(task.path, "task.path"),
+		}),
+		context: parseContext(input.context),
+	};
 }
 
 export function foldDescriptor(entries: readonly SessionEntry[]): DescriptorFold {
@@ -187,3 +284,12 @@ export function foldDescriptor(entries: readonly SessionEntry[]): DescriptorFold
 		return { kind: "corrupt", message: error instanceof Error ? error.message : String(error) };
 	}
 }
+
+export function descriptorContext(
+	descriptor: SubagentDescriptor,
+): ContextInheritance {
+	if (descriptor.version === 3) return structuredClone(descriptor.context);
+	return descriptor.provider === "fork"
+		? { mode: "all_completed" }
+		: { mode: "fresh" };
+}

package/src/index.ts

@@ -14,9 +14,11 @@ import {
 } from "./agents.ts";
 import type { AgentSyncResult } from "./agent-sync.ts";
 import {
+	FollowupTaskParameters,
 	InterruptParameters,
 	ListAgentsParameters,
 	SendMessageParameters,
+	WaitAgentParameters,
 	delegationParameters,
 	forkDelegationParameters,
 } from "./schemas.ts";
@@ -74,16 +76,18 @@ function registerDelegationTool(
 	const { enableRunInBackground, defaultBackground } = settings;
 	const agentNames = agentDiscovery?.agents.map((agent) => agent.name);
 	const description = !enableRunInBackground
-		? "Delegate a complete standalone task to a fresh child with its own Pi session and context. " +
+		? "Delegate a complete task to a named child path with selectable completed-turn context. " +
 			"This foreground-only tool waits for the child and returns its final answer. " +
 			"Independent sibling calls may still execute in parallel."
 		: defaultBackground
-			? "Delegate a complete standalone task to a fresh child with its own Pi session and context. " +
-				"Background mode is continuable and returns a durable child id; use send_message for later FIFO turns. " +
-				"Start independent children together in one assistant message."
-			: "Delegate a complete standalone task to a fresh child with its own Pi session and context. " +
-				"This tool waits for the result by default; set run_in_background to true to return a durable child id.";
-	const promptGuidelines = !enableRunInBackground
+		? "Delegate a complete task to a named child path with selectable completed-turn context. " +
+			(settings.backgroundProtocol === "mailbox-v2"
+				? "Background mode is continuable and returns a readable path plus durable id; use send_message to enqueue, followup_task to start, and wait_agent for quiet completions. "
+				: "Background mode is continuable and returns a readable path plus durable id; use send_message for later FIFO turns. ") +
+			"Start independent children together in one assistant message."
+		: "Delegate a complete task to a named child path with selectable completed-turn context. " +
+			"This tool waits for the result by default; set run_in_background to true to return a readable path plus durable id.";
+	const promptGuidelines = (!enableRunInBackground
 		? [
 				"Use subagent for focused independent work and give it a complete standalone prompt.",
 				"This subagent tool is foreground-only: every call waits for and returns the child's final answer.",
@@ -99,14 +103,17 @@ function registerDelegationTool(
 					"Use subagent for focused independent work and give it a complete standalone prompt.",
 					"Subagent calls wait for the result by default; request background mode only when work can continue independently.",
 					"Independent subagent calls can still be issued together in one assistant message and execute in parallel.",
-				];
+				]).concat([
+					"Set task_name when a stable readable path will help later control calls; otherwise a name is generated from description.",
+					"Use fresh context by default and request all_completed or last_n_completed only when parent history materially helps.",
+				]);
 	const parameters = delegationParameters(enableRunInBackground, agentNames);
 	pi.registerTool({
 		name: "subagent",
 		label: "Subagent",
 		description,
 		promptSnippet: enableRunInBackground
-			? "Delegate focused independent work to fresh child agents"
+			? "Delegate focused work to named child agents"
 			: "Run focused independent work in foreground child agents",
 		promptGuidelines,
 		executionMode: "parallel",
@@ -150,13 +157,16 @@ function registerForkDelegationTool(
 	agentDiscovery?: AgentDiscoveryResult,
 ): unknown {
 	const agentNames = agentDiscovery?.agents.map((agent) => agent.name);
-	const parameters = forkDelegationParameters(agentNames);
+	const parameters = forkDelegationParameters(
+		agentNames,
+		settings.enableRunInBackground,
+	);
 	pi.registerTool({
 		name: "subagent_fork",
 		label: "Subagent Fork",
 		description:
-			"Delegate a one-shot task to a child seeded with all completed turns in this conversation. " +
-			"The current in-flight tool-calling turn is excluded. Use this when the child needs parent history.",
+			"Delegate a task to a child seeded with all completed turns in this conversation. " +
+			"The current in-flight tool-calling turn is excluded. It is foreground by default; request background mode for a continuable fork.",
 		promptSnippet: "Delegate context-dependent work to a child seeded with completed turns",
 		promptGuidelines: [
 			"Use subagent_fork only when completed conversation history materially helps the delegated task.",
@@ -206,6 +216,8 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 	registerForkDelegationTool(pi, coordinator, DEFAULT_SETTINGS);
 	const backgroundControlParameters = new Map<string, unknown>([
 		["send_message", SendMessageParameters],
+		["followup_task", FollowupTaskParameters],
+		["wait_agent", WaitAgentParameters],
 		["interrupt_agent", InterruptParameters],
 		["list_agents", ListAgentsParameters],
 	]);
@@ -214,23 +226,114 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 		name: "send_message",
 		label: "Send Message",
 		description:
-			"Queue a message as a direct continuable child's next FIFO turn. If it is inactive, its persisted session is cold-resumed. " +
+			"Send a message to a direct continuable child. Legacy children start or join a FIFO turn; mailbox-v2 children only durably enqueue it and require followup_task to execute. " +
 			"This call returns acceptance only, never the child's answer.",
-		promptSnippet: "Send a later FIFO turn to a direct continuable subagent",
+		promptSnippet: "Send or enqueue a message for a direct continuable subagent",
 		executionMode: "parallel",
 		parameters: SendMessageParameters,
 		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
 			assertBackgroundControlsEnabled(sessionSettings, "send_message");
 			const parent = await coordinator.parentFromContext(ctx);
-			await coordinator.sendMessage(parent, params.subagent_id, params.message, signal);
+			const delivery = await coordinator.sendMessageWithOutcome(
+				parent,
+				params.subagent_id,
+				params.message,
+				signal,
+			);
 			return {
 				content: [
 					{
 						type: "text",
-						text: `message queued as the next turn for subagent ${params.subagent_id}`,
+						text:
+							delivery.kind === "mailbox-v2"
+								? `message ${delivery.messageId} durably enqueued for ${delivery.taskPath}; ${delivery.pendingMessages} pending`
+								: `message queued as the next turn for ${delivery.taskPath}`,
 					},
 				],
-				details: { kind: "control", action: "send", id: params.subagent_id } satisfies ControlDetails,
+				details: {
+					kind: "control",
+					action: "send",
+					agentId: delivery.agentId,
+					taskPath: delivery.taskPath,
+					...(delivery.kind === "mailbox-v2"
+						? {
+								messageId: delivery.messageId,
+								pendingMessages: delivery.pendingMessages,
+							}
+						: {}),
+				} satisfies ControlDetails,
+			};
+		},
+	});
+
+	pi.registerTool({
+		name: "followup_task",
+		label: "Follow-up Task",
+		description:
+			"For a direct mailbox-v2 continuable child, atomically claim its current pending FIFO mailbox and start exactly one scheduled turn. " +
+			"This call returns turn acceptance, not the child's answer.",
+		promptSnippet: "Start one mailbox-v2 child turn from queued messages",
+		executionMode: "parallel",
+		parameters: FollowupTaskParameters,
+		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+			assertBackgroundControlsEnabled(sessionSettings, "followup_task");
+			const parent = await coordinator.parentFromContext(ctx);
+			const outcome = await coordinator.followupTask(
+				parent,
+				params.subagent_id,
+				signal,
+			);
+			return {
+				content: [
+					{
+						type: "text",
+						text: `started turn ${outcome.turnId} for ${outcome.taskPath}, claiming ${outcome.claimedMessages} mailbox message${outcome.claimedMessages === 1 ? "" : "s"}`,
+					},
+				],
+				details: {
+					kind: "control",
+					action: "followup",
+					agentId: outcome.agentId,
+					taskPath: outcome.taskPath,
+					turnId: outcome.turnId,
+					claimedMessages: outcome.claimedMessages,
+				} satisfies ControlDetails,
+			};
+		},
+	});
+
+	pi.registerTool({
+		name: "wait_agent",
+		label: "Wait Agent",
+		description:
+			"Wait event-driven for unread completion updates from direct mailbox-v2 children. Existing updates return immediately; timeout does not consume later updates.",
+		promptSnippet: "Wait for quiet mailbox-v2 child completion updates",
+		parameters: WaitAgentParameters,
+		async execute(toolCallId, params, signal, _onUpdate, ctx) {
+			assertBackgroundControlsEnabled(sessionSettings, "wait_agent");
+			const parent = await coordinator.parentFromContext(ctx);
+			const outcome = await coordinator.waitAgent(
+				parent,
+				toolCallId,
+				params.timeout_ms,
+				signal,
+			);
+			return {
+				content: [
+					{
+						type: "text",
+						text: coordinator.formatWaitAgentOutcome(outcome),
+					},
+				],
+				details: {
+					kind: "control",
+					action: "wait",
+					timedOut: outcome.timedOut,
+					completionIds: outcome.updates.map(
+						(update) => update.completionId,
+					),
+					unreadUpdates: outcome.unreadUpdates,
+				} satisfies ControlDetails,
 			};
 		},
 	});
@@ -247,10 +350,18 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
 			assertBackgroundControlsEnabled(sessionSettings, "interrupt_agent");
 			const parent = await coordinator.parentFromContext(ctx);
-			await coordinator.interrupt(parent, params.agent_id);
+			const outcome = await coordinator.interruptWithOutcome(
+				parent,
+				params.agent_id,
+			);
 			return {
-				content: [{ type: "text", text: `interrupt requested for agent ${params.agent_id}` }],
-				details: { kind: "control", action: "interrupt", id: params.agent_id } satisfies ControlDetails,
+				content: [{ type: "text", text: `interrupt requested for ${outcome.taskPath}` }],
+				details: {
+					kind: "control",
+					action: "interrupt",
+					agentId: outcome.agentId,
+					taskPath: outcome.taskPath,
+				} satisfies ControlDetails,
 			};
 		},
 	});
@@ -260,7 +371,7 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 		label: "List Agents",
 		description:
 			"List direct continuable children or all descendants. running means an active turn, idle means resident between turns, " +
-			"and ready means persisted and cold-resumable.",
+			"ready means persisted and cold-resumable, and mailbox-v2 children show pending task messages separately from unread completion updates.",
 		promptSnippet: "List continuable child agents and their lifecycle status",
 		parameters: ListAgentsParameters,
 		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
@@ -307,9 +418,13 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 					: "foreground-first";
 			const sections = [
 				`Mode: ${schedulingMode}`,
-				sessionSettings.syncBundledAgents
-					? `Bundled presets: synchronized to ${agentSync?.userAgentsDir ?? coordinator.getUserAgentsDir()}`
-					: "Bundled presets: package defaults (no filesystem sync)",
+				`Background concurrency: ${sessionSettings.maxConcurrentBackgroundRuns}`,
+				`Idle runtime LRU: ${sessionSettings.maxIdleRuntimes}`,
+				`Background protocol: ${sessionSettings.backgroundProtocol ?? "legacy"}`,
+				`OpenAI identity inline: ${sessionSettings.openAIIdentity ? "enabled" : "disabled"}`,
+				agentSync?.diagnostics.length
+					? "Bundled templates: initialization skipped (see diagnostics)"
+					: `Bundled templates: initialization only (${agentSync?.packageVersion ?? "not initialized"})`,
 				`User agent dir: ${agentSync?.userAgentsDir ?? coordinator.getUserAgentsDir()}`,
 				`Agents:\n${formatAgentCatalog(discovery.agents)}`,
 				`Children:\n${coordinator.formatCatalog(entries, "descendants")}`,
@@ -323,10 +438,14 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 
 	pi.on("session_start", async (_event, ctx) => {
 		const loaded = loadSettings({ cwd: ctx.cwd, projectTrusted: ctx.isProjectTrusted() });
+		coordinator.configureBackgroundRuns(
+			loaded.settings.maxConcurrentBackgroundRuns,
+		);
+		await coordinator.configureIdleRuntimes(
+			loaded.settings.maxIdleRuntimes,
+		);
 		sessionSettings = loaded.settings;
-		agentSync = sessionSettings.syncBundledAgents
-			? coordinator.synchronizeBundledAgents()
-			: undefined;
+		agentSync = coordinator.synchronizeBundledAgents();
 		sessionDiscovery = coordinator.discoverAvailableAgents(
 			ctx.cwd,
 			sessionSettings,
@@ -347,6 +466,29 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 		}
 		if (!sessionSettings.enableRunInBackground) {
 			disableOwnedTools(pi, backgroundControlParameters);
+		} else if (sessionSettings.backgroundProtocol !== "mailbox-v2") {
+			let hasMailboxChild = true;
+			try {
+				const parent = await coordinator.parentFromContext(ctx);
+				const entries = await coordinator.list(parent, "descendants");
+				hasMailboxChild = entries.some(
+					(entry) =>
+						entry.kind === "child"
+						&& entry.descriptor.runtime.backgroundProtocol === "mailbox-v2",
+				);
+			} catch {
+				// Keep the control available when catalog inspection fails so a
+				// transient diagnostic cannot strand an existing mailbox child.
+			}
+			if (!hasMailboxChild) {
+				disableOwnedTools(
+					pi,
+					new Map<string, unknown>([
+						["followup_task", FollowupTaskParameters],
+						["wait_agent", WaitAgentParameters],
+					]),
+				);
+			}
 		}
 		if (!agentSyncNotified && agentSync) {
 			agentSyncNotified = true;
@@ -377,6 +519,14 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 		}
 	});
 
+	pi.on("agent_end", async (_event, ctx) => {
+		const parent = await coordinator.parentFromContext(ctx);
+		await coordinator.releaseWaitAgentDeliveries(
+			parent,
+			"parent agent turn ended without a durable wait_agent result",
+		);
+	});
+
 	pi.on("session_shutdown", async () => {
 		await coordinator.shutdown();
 	});