@narumitw/pi-subagents 2.1.4 → 3.0.0

package/src/child-peer-tools.ts

@@ -1,132 +0,0 @@
-import { defineTool, type ExtensionFactory } from "@earendil-works/pi-coding-agent";
-import { Type } from "typebox";
-import { redactPrivateText } from "./context.js";
-import { MAX_TOOL_MESSAGE_BYTES, truncateUtf8 } from "./limits.js";
-import type { AgentMailboxMessage } from "./registry.js";
-
-const MAX_PEER_MESSAGE_BYTES = 16 * 1024;
-const MAX_DEDUPLICATION_KEY_LENGTH = 256;
-const PEER_ENVELOPE_HEADER =
-	/^Message Type: SUBAGENT_(?:COMPLETION|PEER_MESSAGE)\nProtocol: pi-subagents:v1\nMessage ID: (msg_[^\s]+)\n(?:Completion ID: (completion:[^\s]+)\n)?Sender ID: [^\n]+\n(?:Sender Path: [^\n]+\n)?Payload:\n/u;
-
-export interface ChildPeerClient {
-	send(target: string, message: string, deduplicationKey?: string): Promise<AgentMailboxMessage>;
-	list(): Promise<unknown>;
-	acknowledge(messageIds: readonly string[], completionIds: readonly string[]): Promise<void>;
-}
-
-export function createChildPeerExtension(client: ChildPeerClient): ExtensionFactory {
-	return (pi) => {
-		pi.registerTool(
-			defineTool({
-				name: "subagent_peer_send",
-				label: "Send Peer Message",
-				description:
-					"Send a bounded queue-only message to /root or another retained agent by canonical task path. The runtime binds your sender identity; this tool never starts an idle turn.",
-				promptSnippet: "Send a queue-only message to another retained agent",
-				parameters: Type.Object(
-					{
-						target: Type.String({ minLength: 1, maxLength: 2_048 }),
-						message: Type.String({ minLength: 1, maxLength: MAX_PEER_MESSAGE_BYTES }),
-						deduplicationKey: Type.Optional(
-							Type.String({ minLength: 1, maxLength: MAX_DEDUPLICATION_KEY_LENGTH }),
-						),
-					},
-					{ additionalProperties: false },
-				),
-				async execute(_id, params) {
-					const message = await client.send(params.target, params.message, params.deduplicationKey);
-					return {
-						content: [
-							{
-								type: "text" as const,
-								text: `Queued ${message.id} for ${message.recipientId}; delivery does not start an idle turn.`,
-							},
-						],
-						details: {
-							messageId: message.id,
-							recipientId: message.recipientId,
-							createdAt: message.createdAt,
-						},
-					};
-				},
-			}),
-		);
-		pi.registerTool(
-			defineTool({
-				name: "subagent_peer_list",
-				label: "List Peers",
-				description:
-					"List bounded identity and lifecycle metadata for /root and retained agents in this session.",
-				promptSnippet: "List retained peer task paths",
-				parameters: Type.Object({}, { additionalProperties: false }),
-				async execute() {
-					const peers = await client.list();
-					const text = truncateUtf8(JSON.stringify(peers, null, 2), MAX_TOOL_MESSAGE_BYTES).text;
-					return { content: [{ type: "text" as const, text }], details: { peers } };
-				},
-			}),
-		);
-
-		const acknowledgedMessageIds = new Set<string>();
-		const acknowledgedCompletionIds = new Set<string>();
-		pi.on("context", async (event) => {
-			const visible = visibleDeliveryIds(event.messages);
-			const messageIds = [...visible.messageIds].filter((id) => !acknowledgedMessageIds.has(id));
-			const completionIds = [...visible.completionIds].filter(
-				(id) => !acknowledgedCompletionIds.has(id),
-			);
-			if (messageIds.length === 0 && completionIds.length === 0) return;
-			await client.acknowledge(messageIds, completionIds);
-			for (const id of messageIds) acknowledgedMessageIds.add(id);
-			for (const id of completionIds) acknowledgedCompletionIds.add(id);
-		});
-	};
-}
-
-export function formatPeerMessage(message: AgentMailboxMessage, senderPath?: string): string {
-	return truncateUtf8(
-		[
-			`Message Type: ${message.completionId ? "SUBAGENT_COMPLETION" : "SUBAGENT_PEER_MESSAGE"}`,
-			"Protocol: pi-subagents:v1",
-			`Message ID: ${message.id}`,
-			...(message.completionId ? [`Completion ID: ${message.completionId}`] : []),
-			`Sender ID: ${message.senderId}`,
-			...(senderPath ? [`Sender Path: ${senderPath}`] : []),
-			"Payload:",
-			redactPrivateText(message.content),
-		].join("\n"),
-		MAX_TOOL_MESSAGE_BYTES,
-	).text;
-}
-
-export function visibleDeliveryIds(messages: readonly unknown[]): {
-	messageIds: Set<string>;
-	completionIds: Set<string>;
-} {
-	const messageIds = new Set<string>();
-	const completionIds = new Set<string>();
-	for (const message of messages) {
-		for (const text of messageText(message)) {
-			const match = PEER_ENVELOPE_HEADER.exec(text);
-			if (!match) continue;
-			messageIds.add(match[1]);
-			if (match[2]) completionIds.add(match[2]);
-		}
-	}
-	return { messageIds, completionIds };
-}
-
-function messageText(message: unknown): string[] {
-	if (!message || typeof message !== "object" || Array.isArray(message)) return [];
-	const candidate = message as Record<string, unknown>;
-	if (candidate.role !== "user") return [];
-	const content = candidate.content;
-	if (typeof content === "string") return [content];
-	if (!Array.isArray(content)) return [];
-	return content.flatMap((part) => {
-		if (!part || typeof part !== "object" || Array.isArray(part)) return [];
-		const text = (part as Record<string, unknown>).text;
-		return typeof text === "string" ? [text] : [];
-	});
-}

package/src/completion-delivery.ts

@@ -1,409 +0,0 @@
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import type { CompletionDelivery } from "./agents/types.js";
-import { SUBAGENT_COMPLETION_MESSAGE_TYPE } from "./completion-render.js";
-import { requirementForCompletion } from "./completion-requirement.js";
-import { redactPrivateText } from "./context.js";
-import { DEFAULT_MAX_CONTEXT_BYTES, MAX_TOOL_MESSAGE_BYTES, truncateUtf8 } from "./limits.js";
-import type { AgentTurnCompletion, ManagedAgent } from "./registry.js";
-import { safeTerminalText } from "./safe-text.js";
-import { PI_SUBAGENTS_RPC_PROTOCOL } from "./transport-types.js";
-
-const MAX_COMPLETION_ERROR_BYTES = 512;
-const MAX_COMPLETIONS_PER_MESSAGE = 16;
-const MAX_ACKNOWLEDGED_COMPLETION_IDS = 2_048;
-const COMPLETION_BATCH_DELAY_MS = 10;
-
-interface CompletionMetadata {
-	protocol: typeof PI_SUBAGENTS_RPC_PROTOCOL;
-	completionId: string;
-	runId: string;
-	generation: number;
-	agentId: string;
-	taskPath?: string;
-	recipientPath?: string;
-	agent: string;
-	task: string;
-	state: string;
-	transport?: string;
-	structuredResult?: ManagedAgent["structuredResult"];
-	outcome?: ManagedAgent["outcome"];
-	capabilityGrant?: ManagedAgent["capabilityGrant"];
-	completionRequirement?: NonNullable<ManagedAgent["completionRequirements"]>[number];
-}
-
-interface CompletionMessage {
-	customType: typeof SUBAGENT_COMPLETION_MESSAGE_TYPE;
-	content: string;
-	display: true;
-	details:
-		| CompletionMetadata
-		| {
-				completionCount: number;
-				completions: CompletionMetadata[];
-		  };
-}
-
-type CompletionContext = Pick<ExtensionContext, "hasPendingMessages" | "isIdle">;
-type CompletionPi = Pick<ExtensionAPI, "sendMessage">;
-
-export interface CompletionDeliveryBrokerOptions {
-	onDeliveryError?: (error: unknown) => void;
-	onDeliveryAttempt?: (
-		completions: readonly AgentTurnCompletion[],
-		input: {
-			delivery: "steer" | "nextTurn";
-			triggerTurn: boolean;
-			outcome: "accepted" | "failed";
-		},
-	) => void;
-	onAcknowledged?: (completions: readonly AgentTurnCompletion[], acknowledgedAt: number) => void;
-	now?: () => number;
-}
-
-/** Owns bounded completion batching and at most one idle-root wake for one parent session. */
-export class CompletionDeliveryBroker {
-	private pending: AgentTurnCompletion[] = [];
-	private readonly knownCompletionIds = new Set<string>();
-	private readonly acknowledgedCompletionIds = new Set<string>();
-	private awaitingParentAck: AgentTurnCompletion[] = [];
-	private flushTimer?: NodeJS.Timeout;
-	private wakeInFlight = false;
-	private closed = false;
-
-	constructor(
-		private readonly pi: CompletionPi,
-		private readonly ctx: CompletionContext,
-		private delivery: CompletionDelivery,
-		private readonly options: CompletionDeliveryBrokerOptions = {},
-	) {}
-
-	enqueue(completion: AgentTurnCompletion): void {
-		if (
-			this.closed ||
-			this.knownCompletionIds.has(completion.completionId) ||
-			this.acknowledgedCompletionIds.has(completion.completionId)
-		) {
-			return;
-		}
-		this.knownCompletionIds.add(completion.completionId);
-		this.pending.push(completion);
-		this.scheduleFlush();
-	}
-
-	setDelivery(value: CompletionDelivery): void {
-		this.delivery = value;
-		this.scheduleFlush();
-	}
-
-	onParentTurnStart(): void {
-		this.wakeInFlight = false;
-		this.scheduleFlush();
-	}
-
-	onParentContext(messages: readonly unknown[]): void {
-		this.acknowledgeVisible(completionIdsFromContext(messages));
-		if (this.awaitingParentAck.length > 0) {
-			this.pending = [...this.awaitingParentAck.splice(0), ...this.pending];
-		}
-		this.scheduleFlush();
-	}
-
-	onParentSettled(): void {
-		this.wakeInFlight = false;
-		this.scheduleFlush();
-	}
-
-	flush(): void {
-		if (this.closed || this.pending.length === 0) return;
-		if (this.flushTimer) clearTimeout(this.flushTimer);
-		this.flushTimer = undefined;
-
-		const completions = this.pending.splice(0);
-		const batches = chunkCompletions(completions);
-		let canWake = this.shouldWakeRoot();
-		for (let index = 0; index < batches.length; index++) {
-			const triggerTurn = canWake && index === batches.length - 1;
-			const batch = batches[index];
-			const message = buildCompletionMessage(batch);
-			if (triggerTurn) this.wakeInFlight = true;
-			this.awaitingParentAck.push(...batch);
-			try {
-				// Pi treats explicit false as immediate insertion instead of queued steering while streaming.
-				this.pi.sendMessage(message, {
-					deliverAs: "steer",
-					...(triggerTurn ? { triggerTurn: true } : {}),
-				});
-				this.notifyDeliveryAttempt(batch, {
-					delivery: "steer",
-					triggerTurn,
-					outcome: "accepted",
-				});
-			} catch (primaryError) {
-				this.notifyDeliveryAttempt(batch, {
-					delivery: "steer",
-					triggerTurn,
-					outcome: "failed",
-				});
-				this.removeAwaiting(batch);
-				if (triggerTurn) this.wakeInFlight = false;
-				canWake = false;
-				this.awaitingParentAck.push(...batch);
-				try {
-					this.pi.sendMessage(message, { deliverAs: "nextTurn", triggerTurn: false });
-					this.notifyDeliveryAttempt(batch, {
-						delivery: "nextTurn",
-						triggerTurn: false,
-						outcome: "accepted",
-					});
-				} catch (fallbackError) {
-					this.notifyDeliveryAttempt(batch, {
-						delivery: "nextTurn",
-						triggerTurn: false,
-						outcome: "failed",
-					});
-					this.removeAwaiting(batch);
-					this.pending = [...batches.slice(index).flat(), ...this.pending];
-					try {
-						this.options.onDeliveryError?.(
-							new AggregateError(
-								[primaryError, fallbackError],
-								"Detached subagent completion delivery failed",
-							),
-						);
-					} catch {
-						// Delivery retention must survive a failing observer.
-					}
-					return;
-				}
-			}
-		}
-	}
-
-	close(): void {
-		this.closed = true;
-		if (this.flushTimer) clearTimeout(this.flushTimer);
-		this.flushTimer = undefined;
-		this.pending = [];
-		this.awaitingParentAck = [];
-		this.knownCompletionIds.clear();
-		this.acknowledgedCompletionIds.clear();
-	}
-
-	private scheduleFlush(): void {
-		if (this.closed || this.pending.length === 0 || this.flushTimer) return;
-		this.flushTimer = setTimeout(() => {
-			this.flushTimer = undefined;
-			this.flush();
-		}, COMPLETION_BATCH_DELAY_MS);
-	}
-
-	private acknowledgeVisible(visibleIds: ReadonlySet<string>): void {
-		if (visibleIds.size === 0) return;
-		const completions = [...this.awaitingParentAck, ...this.pending].filter((completion) =>
-			visibleIds.has(completion.completionId),
-		);
-		if (completions.length === 0) return;
-		const acknowledgedIds = new Set(completions.map((completion) => completion.completionId));
-		this.awaitingParentAck = this.awaitingParentAck.filter(
-			(completion) => !acknowledgedIds.has(completion.completionId),
-		);
-		this.pending = this.pending.filter(
-			(completion) => !acknowledgedIds.has(completion.completionId),
-		);
-		for (const completion of completions) {
-			this.knownCompletionIds.delete(completion.completionId);
-			this.rememberAcknowledged(completion.completionId);
-		}
-		try {
-			this.options.onAcknowledged?.(completions, (this.options.now ?? Date.now)());
-		} catch {
-			// Context assembly already observed the message, so observer failures cannot retract it.
-		}
-	}
-
-	private rememberAcknowledged(completionId: string): void {
-		this.acknowledgedCompletionIds.add(completionId);
-		while (this.acknowledgedCompletionIds.size > MAX_ACKNOWLEDGED_COMPLETION_IDS) {
-			const oldest = this.acknowledgedCompletionIds.values().next().value;
-			if (typeof oldest !== "string") return;
-			this.acknowledgedCompletionIds.delete(oldest);
-		}
-	}
-
-	private removeAwaiting(completions: readonly AgentTurnCompletion[]): void {
-		const removed = new Set(completions.map((completion) => completion.completionId));
-		this.awaitingParentAck = this.awaitingParentAck.filter(
-			(completion) => !removed.has(completion.completionId),
-		);
-	}
-
-	private notifyDeliveryAttempt(
-		completions: readonly AgentTurnCompletion[],
-		input: {
-			delivery: "steer" | "nextTurn";
-			triggerTurn: boolean;
-			outcome: "accepted" | "failed";
-		},
-	): void {
-		try {
-			this.options.onDeliveryAttempt?.(completions, input);
-		} catch {
-			// Delivery already succeeded, so an observer cannot retract it.
-		}
-	}
-
-	private isRootIdle(): boolean {
-		try {
-			return this.ctx.isIdle();
-		} catch {
-			return false;
-		}
-	}
-
-	private shouldWakeRoot(): boolean {
-		if (this.delivery !== "auto-resume" || this.wakeInFlight || !this.isRootIdle()) return false;
-		try {
-			return !this.ctx.hasPendingMessages();
-		} catch {
-			return false;
-		}
-	}
-}
-
-function completionIdsFromContext(messages: readonly unknown[]): Set<string> {
-	const ids = new Set<string>();
-	for (const message of messages) {
-		if (!message || typeof message !== "object" || Array.isArray(message)) continue;
-		const record = message as Record<string, unknown>;
-		if (record.role !== "custom" || record.customType !== SUBAGENT_COMPLETION_MESSAGE_TYPE)
-			continue;
-		const details = record.details;
-		if (!details || typeof details !== "object" || Array.isArray(details)) continue;
-		const metadata = details as Record<string, unknown>;
-		if (
-			metadata.protocol === PI_SUBAGENTS_RPC_PROTOCOL &&
-			typeof metadata.completionId === "string"
-		) {
-			ids.add(metadata.completionId);
-		}
-		if (!Array.isArray(metadata.completions)) continue;
-		for (const completion of metadata.completions) {
-			if (!completion || typeof completion !== "object" || Array.isArray(completion)) continue;
-			const item = completion as Record<string, unknown>;
-			if (item.protocol === PI_SUBAGENTS_RPC_PROTOCOL && typeof item.completionId === "string") {
-				ids.add(item.completionId);
-			}
-		}
-	}
-	return ids;
-}
-
-function chunkCompletions(completions: AgentTurnCompletion[]): AgentTurnCompletion[][] {
-	const batches: AgentTurnCompletion[][] = [];
-	for (let index = 0; index < completions.length; index += MAX_COMPLETIONS_PER_MESSAGE) {
-		batches.push(completions.slice(index, index + MAX_COMPLETIONS_PER_MESSAGE));
-	}
-	return batches;
-}
-
-function buildCompletionMessage(completions: AgentTurnCompletion[]): CompletionMessage {
-	if (completions.length === 1) {
-		const completion = completions[0];
-		return {
-			customType: SUBAGENT_COMPLETION_MESSAGE_TYPE,
-			content: buildDetachedCompletionMessage(completion),
-			display: true,
-			details: completionMetadata(completion),
-		};
-	}
-	const content = truncateUtf8(
-		[
-			"Message Type: SUBAGENT_COMPLETION_BATCH",
-			`Protocol: ${PI_SUBAGENTS_RPC_PROTOCOL}`,
-			`Completion Count: ${completions.length}`,
-			...completions.flatMap((completion, index) => [
-				"",
-				`--- Completion ${index + 1} of ${completions.length} ---`,
-				buildDetachedCompletionMessage(completion),
-			]),
-		].join("\n"),
-		DEFAULT_MAX_CONTEXT_BYTES,
-	).text;
-	return {
-		customType: SUBAGENT_COMPLETION_MESSAGE_TYPE,
-		content,
-		display: true,
-		details: {
-			completionCount: completions.length,
-			completions: completions.map(completionMetadata),
-		},
-	};
-}
-
-function completionMetadata(completion: AgentTurnCompletion): CompletionMetadata {
-	const completionRequirement = requirementForCompletion(completion.agent, completion.completionId);
-	return {
-		protocol: PI_SUBAGENTS_RPC_PROTOCOL,
-		completionId: completion.completionId,
-		runId: completion.runId,
-		generation: completion.generation,
-		agentId: completion.agent.id,
-		...(completion.agent.taskPath ? { taskPath: completion.agent.taskPath } : {}),
-		...(completion.recipientPath ? { recipientPath: completion.recipientPath } : {}),
-		agent: completion.agent.agent,
-		task: sanitizeCompletionLine(completion.task, 256) || "(unknown task)",
-		state: completion.agent.state,
-		...(completion.agent.telemetry?.transport
-			? { transport: completion.agent.telemetry.transport }
-			: {}),
-		...(completion.agent.structuredResult
-			? { structuredResult: completion.agent.structuredResult }
-			: {}),
-		...(completion.agent.outcome ? { outcome: completion.agent.outcome } : {}),
-		...(completion.agent.capabilityGrant
-			? { capabilityGrant: completion.agent.capabilityGrant }
-			: {}),
-		...(completionRequirement ? { completionRequirement } : {}),
-	};
-}
-
-export function buildDetachedCompletionMessage(completion: AgentTurnCompletion): string {
-	const task = sanitizeCompletionLine(completion.task, 256) || "(unknown task)";
-	const agentName = sanitizeCompletionLine(completion.agent.agent, 128) || "(unknown agent)";
-	const output = safeTerminalText(redactPrivateText(completion.output));
-	const error = completion.error
-		? truncateUtf8(
-				safeTerminalText(redactPrivateText(completion.error)),
-				MAX_COMPLETION_ERROR_BYTES,
-			).text
-		: "";
-	return truncateUtf8(
-		[
-			"Message Type: SUBAGENT_COMPLETION",
-			`Protocol: ${PI_SUBAGENTS_RPC_PROTOCOL}`,
-			`Completion ID: ${completion.completionId}`,
-			`Run ID: ${completion.runId}`,
-			`Generation: ${completion.generation}`,
-			`Agent ID: ${completion.agent.id}`,
-			...(completion.agent.taskPath ? [`Agent Path: ${completion.agent.taskPath}`] : []),
-			...(completion.recipientPath ? [`Recipient Path: ${completion.recipientPath}`] : []),
-			`Agent: ${agentName}`,
-			`Task: ${task}`,
-			`State: ${completion.agent.state}`,
-			...(error.trim() ? ["Error:", error] : []),
-			"Payload:",
-			output.trim() ? output : "(no output)",
-		].join("\n"),
-		MAX_TOOL_MESSAGE_BYTES,
-	).text;
-}
-
-function sanitizeCompletionLine(value: string, maxBytes: number): string {
-	return (
-		truncateUtf8(redactPrivateText(value), maxBytes)
-			// biome-ignore lint/suspicious/noControlCharactersInRegex: Strip untrusted terminal controls.
-			.text.replace(/[\u0000-\u001f\u007f]+/g, " ")
-			.replace(/\s+/g, " ")
-			.trim()
-	);
-}