@narumitw/pi-subagents 1.0.1 → 2.0.0

package/src/in-process-transport.ts

@@ -9,12 +9,18 @@ import {
 } from "@earendil-works/pi-coding-agent";
 import { discoverAgents } from "./agents/discovery.js";
 import type { AgentConfig, SubagentThinkingLevel } from "./agents/types.js";
+import { formatPeerMessage } from "./child-peer-tools.js";
 import { redactPrivateText } from "./context.js";
 import { appendDelegationContract } from "./delegation-contract.js";
 import { resolveDefaultSubagentTimeoutMs } from "./execution/runtime-policy.js";
 import { DEFAULT_MAX_CONTEXT_BYTES, DEFAULT_MAX_OUTPUT_BYTES, truncateUtf8 } from "./limits.js";
+import {
+	CHILD_PEER_TOOL_NAMES,
+	createInProcessPeerExtension,
+	type PeerTransportRuntime,
+} from "./peer-transport.js";
 import { resolvePiPromptResources } from "./prompt-resources.js";
-import type { AgentTurn, ManagedAgent, TurnOutcome } from "./registry.js";
+import type { AgentMailboxMessage, AgentTurn, ManagedAgent, TurnOutcome } from "./registry.js";
 import { appendResultInstruction } from "./result-contract.js";
 import { safeTerminalLine } from "./safe-text.js";
 import { readSubagentSettings } from "./settings.js";
@@ -79,6 +85,7 @@ export interface ChildSession {
 	readonly model?: string;
 	readonly thinkingLevel?: SubagentThinkingLevel;
 	prompt(text: string): Promise<void>;
+	steer?(text: string): Promise<void>;
 	subscribe(listener: (event: unknown) => void): () => void;
 	abort(): Promise<void>;
 	dispose(): void;
@@ -93,6 +100,7 @@ export interface ChildSessionCreateOptions {
 	modelRegistry: ModelRegistry;
 	parentRuntime: ParentRuntimeSnapshot;
 	tools?: string[];
+	peerRuntime?: PeerTransportRuntime;
 }
 
 export type ChildSessionFactory = (options: ChildSessionCreateOptions) => Promise<ChildSession>;
@@ -105,6 +113,7 @@ export interface InProcessTransportOptions {
 	defaultTimeoutMs?: number;
 	abortGraceMs?: number;
 	timeoutFinalizationMs?: number;
+	peerRuntime?: PeerTransportRuntime;
 }
 
 interface ChildSessionRecord {
@@ -362,6 +371,13 @@ export class InProcessTransport implements SubagentTransport {
 		}
 	}
 
+	async deliverMessage(agent: ManagedAgent, message: AgentMailboxMessage): Promise<boolean> {
+		const record = this.sessions.get(agent.id);
+		if (!record || record.disposed || !record.session.steer) return false;
+		await record.session.steer(formatPeerMessage(message));
+		return true;
+	}
+
 	async release(agent: ManagedAgent): Promise<void> {
 		await this.releaseById(agent.id);
 	}
@@ -384,6 +400,7 @@ export class InProcessTransport implements SubagentTransport {
 		const record = this.sessions.get(agentId);
 		if (!record) return;
 		this.sessions.delete(agentId);
+		this.options.peerRuntime?.revoke(agentId);
 		if (record.disposed) return;
 		record.disposed = true;
 		const failures: unknown[] = [];
@@ -423,6 +440,7 @@ export class InProcessTransport implements SubagentTransport {
 			modelRegistry: this.options.modelRegistry,
 			parentRuntime: this.options.getParentRuntime(),
 			tools,
+			peerRuntime: this.options.peerRuntime,
 		});
 		const record: ChildSessionRecord = {
 			session,
@@ -563,6 +581,9 @@ export async function createSdkChildSession(
 		agentDir,
 		options.agentConfig.systemPrompt,
 		projectTrusted,
+		options.peerRuntime
+			? createInProcessPeerExtension(options.peerRuntime, options.agent.id)
+			: undefined,
 	);
 	copyRegisteredProviders(
 		options.modelRegistry as unknown as RegisteredProviderRegistry,
@@ -577,18 +598,24 @@ export async function createSdkChildSession(
 	const model = resolved.model;
 	const sessionManager = SessionManager.inMemory(options.agent.cwd);
 	seedChildSessionManager(sessionManager, options, model);
+	const selectedTools =
+		options.tools === undefined
+			? undefined
+			: options.peerRuntime
+				? [...options.tools, ...CHILD_PEER_TOOL_NAMES]
+				: options.tools;
 	const created = await coreSupport.createAgentSessionFromServices({
 		services,
 		sessionManager,
 		model,
 		thinkingLevel: resolved.thinkingLevel,
-		tools: options.tools,
-		noTools: options.tools?.length === 0 ? "all" : undefined,
+		tools: selectedTools,
+		noTools: selectedTools?.length === 0 ? "all" : undefined,
 	});
 	const session = created.session;
-	if (options.tools !== undefined) {
+	if (selectedTools !== undefined) {
 		const active = session.getActiveToolNames();
-		const expected = [...options.tools].sort();
+		const expected = [...selectedTools].sort();
 		if (
 			active.length !== expected.length ||
 			[...active].sort().some((name, index) => name !== expected[index])
@@ -616,6 +643,7 @@ export async function createSdkChildSession(
 			return session.thinkingLevel;
 		},
 		prompt: (text) => session.prompt(text),
+		steer: (text) => session.steer(text),
 		subscribe: (listener) => session.subscribe((event) => listener(event)),
 		abort: () => session.abort(),
 		dispose: () => session.dispose(),
@@ -713,6 +741,7 @@ async function prepareInProcessServices(
 	agentDir: string,
 	agentSystemPrompt: string,
 	projectTrusted: boolean,
+	peerExtension?: import("@earendil-works/pi-coding-agent").ExtensionFactory,
 ): Promise<{ services: AgentSessionServices; support: CoreSessionSupport }> {
 	const promptResources = await resolvePiPromptResources(cwd, projectTrusted, agentDir);
 	const settingsManager = SettingsManager.create(cwd, agentDir, { projectTrusted });
@@ -724,6 +753,7 @@ async function prepareInProcessServices(
 		settingsManager,
 		resourceLoaderOptions: {
 			noExtensions: true,
+			...(peerExtension ? { extensionFactories: [peerExtension] } : {}),
 			appendSystemPrompt: [
 				...promptResources.appendSystemPromptPaths,
 				...(agentSystemPrompt.trim() ? [agentSystemPrompt] : []),
@@ -787,8 +817,10 @@ export function buildCurrentTurnPrompt(agent: ManagedAgent, task: string): strin
 	const messages = agent.mailbox
 		.filter((message) => ids.has(message.id))
 		.slice(-20)
-		.map((message) => `From ${message.senderId}: ${redactPrivateText(message.content)}`)
-		.join("\n");
+		.map((message) =>
+			formatPeerMessage({ ...message, content: redactPrivateText(message.content) }),
+		)
+		.join("\n\n");
 	const base = messages
 		? `${redactPrivateText(task)}\n\nMailbox messages:\n${messages}`
 		: redactPrivateText(task);

package/src/inspect-tool.ts

@@ -28,7 +28,9 @@ export const SubagentInspectParams = Type.Object(
 	{
 		action: StringEnum(INSPECT_ACTIONS),
 		agent: Type.Optional(Type.String({ minLength: 1 })),
-		agentId: Type.Optional(Type.String({ minLength: 1 })),
+		agentId: Type.Optional(
+			Type.String({ minLength: 1, description: "Retained agent ID or canonical task path." }),
+		),
 		workflowId: Type.Optional(Type.String({ minLength: 1, maxLength: 256 })),
 		agentScope: Type.Optional(AgentScopeSchema),
 		limit: Type.Optional(LimitSchema),

package/src/panel-planning.ts

@@ -1,9 +1,9 @@
 import type { AgentConfig } from "./agents/types.js";
 import { DEFAULT_MAX_CONTEXT_BYTES, truncateUtf8 } from "./limits.js";
+import type { PanelPreset } from "./panel-presets.js";
 import { type WorkItemDefinition, WorkItemLedger } from "./work-item-ledger.js";
 
-export const PANEL_PRESETS = ["code-review", "research", "security-review", "custom"] as const;
-export type PanelPreset = (typeof PANEL_PRESETS)[number];
+export type { PanelPreset } from "./panel-presets.js";
 
 export interface PanelReviewerRequest {
 	id: string;

package/src/panel-presets.ts

@@ -0,0 +1,3 @@
+export const PANEL_PRESETS = ["code-review", "research", "security-review", "custom"] as const;
+
+export type PanelPreset = (typeof PANEL_PRESETS)[number];

package/src/params.ts

@@ -3,7 +3,7 @@ import { type Static, Type } from "typebox";
 import { THINKING_LEVELS } from "./agents/types.js";
 import { DelegationContractSchema } from "./delegation-contract.js";
 import { MAX_CONFIGURABLE_PARALLEL_TASKS, MAX_SUBAGENT_TIMEOUT_MS } from "./limits.js";
-import { PANEL_PRESETS } from "./panel-planning.js";
+import { PANEL_PRESETS } from "./panel-presets.js";
 import { SUBAGENT_RESULT_FORMATS } from "./result-contract.js";
 import { MAX_SUBAGENT_TOOL_CALLS, MAX_SUBAGENT_TURNS } from "./turn-budget.js";
 import { VerifiedExecutionContractSchema } from "./verified-execution-schema.js";

package/src/peer-communication.ts

@@ -0,0 +1,352 @@
+import { randomBytes, randomUUID } from "node:crypto";
+import net, { type AddressInfo, type Server, type Socket } from "node:net";
+import { redactPrivateText } from "./context.js";
+import { truncateUtf8 } from "./limits.js";
+import type { AgentMailboxMessage, AgentRegistry, ManagedAgent } from "./registry.js";
+import { ROOT_TASK_PATH } from "./task-path.js";
+
+const MAX_BRIDGE_FRAME_BYTES = 64 * 1024;
+const MAX_BRIDGE_CONNECTIONS = 32;
+const BRIDGE_HANDSHAKE_TIMEOUT_MS = 2_000;
+const MAX_ROOT_MESSAGE_BYTES = 16 * 1024;
+const MAX_LISTED_PEERS = 20;
+
+export interface PeerDescriptor {
+	id: string;
+	taskName: string;
+	taskPath: string;
+	agent: string;
+	state: string;
+	self: boolean;
+}
+
+export interface PeerRootMessage {
+	message: AgentMailboxMessage;
+	senderPath: string;
+}
+
+export interface PeerBridgeCredentials {
+	host: string;
+	port: number;
+	token: string;
+	generation: number;
+}
+
+export interface PeerCommunicationBrokerOptions {
+	getRegistry(): AgentRegistry;
+	sendRoot(message: PeerRootMessage): void | Promise<void>;
+	dispatch?(recipient: ManagedAgent, message: AgentMailboxMessage): boolean | Promise<boolean>;
+	now?: () => number;
+}
+
+interface CredentialRecord extends PeerBridgeCredentials {
+	agentId: string;
+}
+
+/** Session-owned authenticated routing and process-child JSONL bridge. */
+export class PeerCommunicationBroker {
+	private server?: Server;
+	private starting?: Promise<void>;
+	private closed = false;
+	private readonly sockets = new Set<Socket>();
+	private readonly credentialsByToken = new Map<string, CredentialRecord>();
+	private readonly tokenByAgent = new Map<string, string>();
+	private readonly dispatchedIds = new Set<string>();
+	private readonly rootDeduplication = new Map<string, AgentMailboxMessage>();
+
+	constructor(private readonly options: PeerCommunicationBrokerOptions) {}
+
+	async send(
+		senderId: string,
+		target: string,
+		content: string,
+		deduplicationKey?: string,
+	): Promise<AgentMailboxMessage> {
+		if (this.closed) throw new Error("Subagent peer broker is closed");
+		const registry = this.options.getRegistry();
+		const sender = registry.resolveAgent(senderId);
+		if (!sender) throw new Error(`Unknown subagent: ${senderId}`);
+		if (sender.state === "closed")
+			throw new Error(`Closed agent ${sender.id} cannot send messages`);
+		if (target === ROOT_TASK_PATH) {
+			return this.sendToRoot(sender, content, deduplicationKey);
+		}
+		const message = await registry.sendMessage(target, content, sender.id, deduplicationKey);
+		if (this.closed) return message;
+		const recipient = registry.get(message.recipientId);
+		if (recipient?.state === "running" && !this.dispatchedIds.has(message.id)) {
+			this.dispatchedIds.add(message.id);
+			try {
+				await this.options.dispatch?.(recipient, redactedDeliveryCopy(message));
+			} catch {
+				// Durable mailbox delivery remains available for the recipient's next turn.
+			}
+		}
+		return message;
+	}
+
+	list(senderId: string): PeerDescriptor[] {
+		const registry = this.options.getRegistry();
+		const sender = registry.resolveAgent(senderId);
+		if (!sender) throw new Error(`Unknown subagent: ${senderId}`);
+		const root: PeerDescriptor = {
+			id: "root",
+			taskName: "root",
+			taskPath: ROOT_TASK_PATH,
+			agent: "root",
+			state: "active",
+			self: false,
+		};
+		const retained = registry
+			.list()
+			.map((agent) => ({
+				id: truncateUtf8(agent.id, 256).text,
+				taskName: truncateUtf8(agent.taskName ?? "unknown", 128).text,
+				taskPath: truncateUtf8(agent.taskPath ?? agent.id, 2_048).text,
+				agent: truncateUtf8(agent.agent, 128).text,
+				state: agent.state,
+				self: agent.id === sender.id,
+			}))
+			.sort((left, right) => left.taskPath.localeCompare(right.taskPath));
+		const selected = retained.slice(0, MAX_LISTED_PEERS - 1);
+		if (!selected.some((peer) => peer.id === sender.id)) {
+			const senderPeer = retained.find((peer) => peer.id === sender.id);
+			if (senderPeer) selected.splice(Math.max(0, selected.length - 1), 1, senderPeer);
+		}
+		return [root, ...selected].sort((left, right) => left.taskPath.localeCompare(right.taskPath));
+	}
+
+	async acknowledge(
+		agentId: string,
+		messageIds: readonly string[],
+		completionIds: readonly string[] = [],
+	): Promise<void> {
+		if (this.closed) return;
+		await this.options
+			.getRegistry()
+			.acknowledgeVisibleMessages(
+				agentId,
+				messageIds,
+				completionIds,
+				(this.options.now ?? Date.now)(),
+			);
+	}
+
+	async issueCredentials(agentId: string, generation: number): Promise<PeerBridgeCredentials> {
+		if (this.closed) throw new Error("Subagent peer broker is closed");
+		if (!Number.isSafeInteger(generation) || generation < 1) {
+			throw new Error("Subagent peer bridge generation must be a positive safe integer");
+		}
+		const agent = this.options.getRegistry().resolveAgent(agentId);
+		if (!agent || agent.state === "closed") throw new Error(`Unknown subagent: ${agentId}`);
+		await this.ensureServer();
+		this.revoke(agent.id);
+		const address = this.server?.address();
+		if (!address || typeof address === "string") {
+			throw new Error("Subagent peer bridge did not expose a loopback address");
+		}
+		const token = randomBytes(32).toString("hex");
+		const credentials: CredentialRecord = {
+			agentId: agent.id,
+			host: "127.0.0.1",
+			port: address.port,
+			token,
+			generation,
+		};
+		this.credentialsByToken.set(token, credentials);
+		this.tokenByAgent.set(agent.id, token);
+		return { host: credentials.host, port: credentials.port, token, generation };
+	}
+
+	revoke(agentId: string): void {
+		const token = this.tokenByAgent.get(agentId);
+		if (!token) return;
+		this.tokenByAgent.delete(agentId);
+		this.credentialsByToken.delete(token);
+	}
+
+	async close(): Promise<void> {
+		if (this.closed) return;
+		this.closed = true;
+		this.credentialsByToken.clear();
+		this.tokenByAgent.clear();
+		this.rootDeduplication.clear();
+		this.dispatchedIds.clear();
+		for (const socket of this.sockets) socket.destroy();
+		this.sockets.clear();
+		const server = this.server;
+		this.server = undefined;
+		if (!server) return;
+		await new Promise<void>((resolve) => server.close(() => resolve()));
+	}
+
+	private async sendToRoot(
+		sender: ManagedAgent,
+		content: string,
+		deduplicationKey?: string,
+	): Promise<AgentMailboxMessage> {
+		if (!content.trim()) throw new Error("Subagent peer messages cannot be empty");
+		if (deduplicationKey && deduplicationKey.length > 256) {
+			throw new Error("Subagent peer deduplication keys cannot exceed 256 characters");
+		}
+		const deduplicationId = deduplicationKey ? `${sender.id}\0${deduplicationKey}` : undefined;
+		const duplicate = deduplicationId ? this.rootDeduplication.get(deduplicationId) : undefined;
+		if (duplicate) return { ...duplicate };
+		const message: AgentMailboxMessage = {
+			id: `msg_${randomUUID()}`,
+			senderId: sender.id,
+			recipientId: "root",
+			content: truncateUtf8(content, MAX_ROOT_MESSAGE_BYTES).text,
+			createdAt: (this.options.now ?? Date.now)(),
+			deduplicationKey,
+		};
+		await this.options.sendRoot({
+			message: redactedDeliveryCopy(message),
+			senderPath: sender.taskPath ?? sender.id,
+		});
+		if (deduplicationId) {
+			this.rootDeduplication.set(deduplicationId, message);
+			while (this.rootDeduplication.size > 100) {
+				const oldest = this.rootDeduplication.keys().next().value;
+				if (typeof oldest !== "string") break;
+				this.rootDeduplication.delete(oldest);
+			}
+		}
+		return { ...message };
+	}
+
+	private async ensureServer(): Promise<void> {
+		if (this.server) return;
+		if (!this.starting) {
+			this.starting = new Promise<void>((resolve, reject) => {
+				const server = net.createServer((socket) => this.accept(socket));
+				server.maxConnections = MAX_BRIDGE_CONNECTIONS;
+				server.once("error", reject);
+				server.listen({ host: "127.0.0.1", port: 0 }, () => {
+					server.off("error", reject);
+					this.server = server;
+					resolve();
+				});
+			}).finally(() => {
+				this.starting = undefined;
+			});
+		}
+		await this.starting;
+		if (this.closed) {
+			const server = this.server as Server | undefined;
+			this.server = undefined;
+			if (server) await new Promise<void>((resolve) => server.close(() => resolve()));
+			throw new Error("Subagent peer broker closed while starting");
+		}
+	}
+
+	private accept(socket: Socket): void {
+		if (this.closed || this.sockets.size >= MAX_BRIDGE_CONNECTIONS) {
+			socket.destroy();
+			return;
+		}
+		this.sockets.add(socket);
+		let frame = Buffer.alloc(0);
+		let handled = false;
+		const timer = setTimeout(() => {
+			handled = true;
+			this.respond(socket, { ok: false, error: "bridge handshake timed out" });
+		}, BRIDGE_HANDSHAKE_TIMEOUT_MS);
+		timer.unref();
+		const cleanup = () => {
+			clearTimeout(timer);
+			this.sockets.delete(socket);
+		};
+		socket.on("data", (chunk: Buffer) => {
+			if (handled) return;
+			frame = Buffer.concat([frame, chunk]);
+			if (frame.byteLength > MAX_BRIDGE_FRAME_BYTES) {
+				handled = true;
+				clearTimeout(timer);
+				this.respond(socket, { ok: false, error: "bridge frame exceeds size limit" });
+				return;
+			}
+			const newline = frame.indexOf(0x0a);
+			if (newline < 0) return;
+			handled = true;
+			clearTimeout(timer);
+			void this.handleFrame(frame.subarray(0, newline).toString("utf8")).then((response) =>
+				this.respond(socket, response),
+			);
+		});
+		socket.once("close", cleanup);
+		socket.once("error", cleanup);
+	}
+
+	private async handleFrame(frame: string): Promise<Record<string, unknown>> {
+		let request: Record<string, unknown>;
+		try {
+			const parsed = JSON.parse(frame) as unknown;
+			if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error();
+			request = parsed as Record<string, unknown>;
+		} catch {
+			return { ok: false, error: "malformed bridge request" };
+		}
+		const credential =
+			typeof request.token === "string" ? this.credentialsByToken.get(request.token) : undefined;
+		if (!credential) return { ok: false, error: "unauthenticated bridge request" };
+		try {
+			switch (request.action) {
+				case "send": {
+					if (typeof request.target !== "string" || typeof request.message !== "string") {
+						throw new Error("send requires target and message strings");
+					}
+					const message = await this.send(
+						credential.agentId,
+						request.target,
+						request.message,
+						typeof request.deduplicationKey === "string" ? request.deduplicationKey : undefined,
+					);
+					return { ok: true, message };
+				}
+				case "list":
+					return { ok: true, peers: this.list(credential.agentId) };
+				case "acknowledge": {
+					const messageIds = stringArray(request.messageIds);
+					const completionIds = stringArray(request.completionIds);
+					await this.acknowledge(credential.agentId, messageIds, completionIds);
+					return { ok: true };
+				}
+				default:
+					return { ok: false, error: "unsupported bridge action" };
+			}
+		} catch (error) {
+			return { ok: false, error: error instanceof Error ? error.message : String(error) };
+		}
+	}
+
+	private respond(socket: Socket, value: Record<string, unknown>): void {
+		if (socket.destroyed) return;
+		const content = `${JSON.stringify(value)}\n`;
+		socket.end(content);
+	}
+}
+
+function redactedDeliveryCopy(message: AgentMailboxMessage): AgentMailboxMessage {
+	return { ...message, content: redactPrivateText(message.content) };
+}
+
+function stringArray(value: unknown): string[] {
+	if (value === undefined) return [];
+	if (
+		!Array.isArray(value) ||
+		value.length > 100 ||
+		value.some((item) => typeof item !== "string")
+	) {
+		throw new Error("acknowledgement IDs must be a bounded string array");
+	}
+	return value;
+}
+
+export function peerBridgeAddress(credentials: PeerBridgeCredentials): string {
+	return `${credentials.host}:${credentials.port}`;
+}
+
+export function isLoopbackAddress(address: AddressInfo | string | null): address is AddressInfo {
+	return Boolean(address && typeof address !== "string" && address.address === "127.0.0.1");
+}

package/src/peer-transport.ts

@@ -0,0 +1,49 @@
+import { fileURLToPath } from "node:url";
+import type { ExtensionFactory } from "@earendil-works/pi-coding-agent";
+import { createChildPeerExtension } from "./child-peer-tools.js";
+import type { PeerBridgeCredentials, PeerDescriptor } from "./peer-communication.js";
+import type { AgentMailboxMessage } from "./registry.js";
+
+export const CHILD_PEER_TOOL_NAMES = ["subagent_peer_send", "subagent_peer_list"] as const;
+
+export interface PeerTransportRuntime {
+	send(
+		senderId: string,
+		target: string,
+		message: string,
+		deduplicationKey?: string,
+	): Promise<AgentMailboxMessage>;
+	list(senderId: string): PeerDescriptor[];
+	acknowledge(
+		agentId: string,
+		messageIds: readonly string[],
+		completionIds?: readonly string[],
+	): Promise<void>;
+	issueCredentials(agentId: string, generation: number): Promise<PeerBridgeCredentials>;
+	revoke(agentId: string): void;
+}
+
+export function createInProcessPeerExtension(
+	runtime: PeerTransportRuntime,
+	agentId: string,
+): ExtensionFactory {
+	return createChildPeerExtension({
+		send: (target, message, deduplicationKey) =>
+			runtime.send(agentId, target, message, deduplicationKey),
+		list: async () => runtime.list(agentId),
+		acknowledge: (messageIds, completionIds) =>
+			runtime.acknowledge(agentId, messageIds, completionIds),
+	});
+}
+
+export function childPeerBridgePath(): string {
+	return fileURLToPath(new URL("./child-peer-bridge.ts", import.meta.url));
+}
+
+export function peerBridgeEnvironment(credentials: PeerBridgeCredentials): NodeJS.ProcessEnv {
+	return {
+		PI_SUBAGENT_PEER_HOST: credentials.host,
+		PI_SUBAGENT_PEER_PORT: String(credentials.port),
+		PI_SUBAGENT_PEER_TOKEN: credentials.token,
+	};
+}

package/src/persistence.ts

@@ -13,6 +13,7 @@ import type { ManagedAgent } from "./registry.js";
 import { parseAnyStructuredSubagentResult, SUBAGENT_RESULT_FORMATS } from "./result-contract.js";
 import { isSemanticSnapshot } from "./semantic-snapshot.js";
 import { resolveStatefulLimits } from "./stateful-limits.js";
+import { validateTaskName, validateTaskPath } from "./task-path.js";
 import { copyTurnTerminationReport, type TurnTerminationReport } from "./timeout-checkpoint.js";
 import { MAX_SUBAGENT_TOOL_CALLS, MAX_SUBAGENT_TURNS } from "./turn-budget.js";
 
@@ -239,6 +240,8 @@ function isStoredState(value: unknown): value is StoredState {
 		const record = agent as Partial<ManagedAgent>;
 		return (
 			typeof record.id === "string" &&
+			(record.taskName === undefined || isValidTaskName(record.taskName)) &&
+			(record.taskPath === undefined || isValidTaskPath(record.taskPath)) &&
 			typeof record.agent === "string" &&
 			typeof record.cwd === "string" &&
 			typeof record.createdAt === "number" &&
@@ -291,6 +294,24 @@ function isStoredState(value: unknown): value is StoredState {
 	});
 }
 
+function isValidTaskName(value: unknown): value is string {
+	if (typeof value !== "string") return false;
+	try {
+		return validateTaskName(value) === value;
+	} catch {
+		return false;
+	}
+}
+
+function isValidTaskPath(value: unknown): value is string {
+	if (typeof value !== "string") return false;
+	try {
+		return validateTaskPath(value) === value;
+	} catch {
+		return false;
+	}
+}
+
 function isSemanticCompatibility(value: unknown): boolean {
 	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
 	const compatibility = value as Record<string, unknown>;
@@ -434,6 +455,9 @@ function isPersistedCompletion(
 		typeof completion.completionId === "string" &&
 		completion.completionId.length > 0 &&
 		completion.completionId.length <= 256 &&
+		(completion.recipientId === undefined ||
+			(typeof completion.recipientId === "string" && completion.recipientId.length > 0)) &&
+		(completion.recipientPath === undefined || isValidTaskPath(completion.recipientPath)) &&
 		typeof completion.runId === "string" &&
 		completion.runId.length > 0 &&
 		completion.runId.length <= 256 &&
@@ -483,6 +507,7 @@ function isMailboxMessage(value: unknown): boolean {
 		Number.isFinite(message.createdAt) &&
 		(message.readAt === undefined ||
 			(typeof message.readAt === "number" && Number.isFinite(message.readAt))) &&
-		(message.deduplicationKey === undefined || typeof message.deduplicationKey === "string")
+		(message.deduplicationKey === undefined || typeof message.deduplicationKey === "string") &&
+		(message.completionId === undefined || typeof message.completionId === "string")
 	);
 }

package/src/pi-args.ts

@@ -11,6 +11,7 @@ export interface PiArgsOptions {
 	projectTrust?: boolean;
 	baseSystemPromptPath?: string;
 	appendSystemPromptPaths?: string[];
+	extensionPaths?: string[];
 	/** Existing single append prompt path retained for compatibility. */
 	systemPromptPath?: string;
 	task: string;
@@ -21,6 +22,7 @@ export function buildPiArgs(options: PiArgsOptions): string[] {
 	if (options.model) args.push("--model", options.model);
 	if (options.thinkingLevel) args.push("--thinking", options.thinkingLevel);
 	if (options.disableExtensions) args.push("--no-extensions");
+	for (const extensionPath of options.extensionPaths ?? []) args.push("-e", extensionPath);
 	if (options.disableSkills) args.push("--no-skills");
 	if (options.disablePromptTemplates) args.push("--no-prompt-templates");
 	if (options.disableContextFiles) args.push("--no-context-files");