@narumitw/pi-subagents 0.54.0 → 1.0.1

package/src/completion-delivery.ts

@@ -12,6 +12,9 @@ const COMPLETION_BATCH_DELAY_MS = 10;
 
 interface CompletionMetadata {
 	protocol: typeof PI_SUBAGENTS_RPC_PROTOCOL;
+	completionId: string;
+	runId: string;
+	generation: number;
 	agentId: string;
 	agent: string;
 	state: string;
@@ -38,13 +41,15 @@ type CompletionPi = Pick<ExtensionAPI, "sendMessage">;
 
 export interface CompletionDeliveryBrokerOptions {
 	onDeliveryError?: (error: unknown) => void;
-	onDelivered?: (completions: readonly AgentTurnCompletion[], deliveredAt: number) => 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 awaitingParentAck: AgentTurnCompletion[] = [];
 	private flushTimer?: NodeJS.Timeout;
 	private wakeInFlight = false;
 	private closed = false;
@@ -57,7 +62,8 @@ export class CompletionDeliveryBroker {
 	) {}
 
 	enqueue(completion: AgentTurnCompletion): void {
-		if (this.closed) return;
+		if (this.closed || this.knownCompletionIds.has(completion.completionId)) return;
+		this.knownCompletionIds.add(completion.completionId);
 		this.pending.push(completion);
 		this.scheduleFlush();
 	}
@@ -72,6 +78,14 @@ export class CompletionDeliveryBroker {
 		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();
@@ -88,18 +102,21 @@ export class CompletionDeliveryBroker {
 		let canWake = this.shouldWakeRoot();
 		for (let index = 0; index < batches.length; index++) {
 			const triggerTurn = canWake && index === batches.length - 1;
-			const message = buildCompletionMessage(batches[index]);
+			const batch = batches[index];
+			const message = buildCompletionMessage(batch);
 			if (triggerTurn) this.wakeInFlight = true;
+			this.awaitingParentAck.push(...batch);
 			try {
 				this.pi.sendMessage(message, { deliverAs: "steer", triggerTurn });
-				this.notifyDelivered(batches[index]);
 			} catch (primaryError) {
+				this.removeAwaiting(batch);
 				if (triggerTurn) this.wakeInFlight = false;
 				canWake = false;
+				this.awaitingParentAck.push(...batch);
 				try {
 					this.pi.sendMessage(message, { deliverAs: "nextTurn", triggerTurn: false });
-					this.notifyDelivered(batches[index]);
 				} catch (fallbackError) {
+					this.removeAwaiting(batch);
 					this.pending = [...batches.slice(index).flat(), ...this.pending];
 					try {
 						this.options.onDeliveryError?.(
@@ -122,6 +139,8 @@ export class CompletionDeliveryBroker {
 		if (this.flushTimer) clearTimeout(this.flushTimer);
 		this.flushTimer = undefined;
 		this.pending = [];
+		this.awaitingParentAck = [];
+		this.knownCompletionIds.clear();
 	}
 
 	private scheduleFlush(): void {
@@ -132,14 +151,34 @@ export class CompletionDeliveryBroker {
 		}, COMPLETION_BATCH_DELAY_MS);
 	}
 
-	private notifyDelivered(completions: readonly AgentTurnCompletion[]): void {
+	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);
 		try {
-			this.options.onDelivered?.(completions, (this.options.now ?? Date.now)());
+			this.options.onAcknowledged?.(completions, (this.options.now ?? Date.now)());
 		} catch {
-			// Delivery already succeeded, so observer failures cannot requeue it.
+			// Context assembly already observed the message, so observer failures cannot retract it.
 		}
 	}
 
+	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 isRootIdle(): boolean {
 		try {
 			return this.ctx.isIdle();
@@ -158,6 +197,33 @@ export class CompletionDeliveryBroker {
 	}
 }
 
+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 !== "pi-subagent-completion") 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) {
@@ -203,6 +269,9 @@ function buildCompletionMessage(completions: AgentTurnCompletion[]): CompletionM
 function completionMetadata(completion: AgentTurnCompletion): CompletionMetadata {
 	return {
 		protocol: PI_SUBAGENTS_RPC_PROTOCOL,
+		completionId: completion.completionId,
+		runId: completion.runId,
+		generation: completion.generation,
 		agentId: completion.agent.id,
 		agent: completion.agent.agent,
 		state: completion.agent.state,
@@ -233,6 +302,9 @@ export function buildDetachedCompletionMessage(completion: AgentTurnCompletion):
 		[
 			"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}`,
 			`Agent: ${agentName}`,
 			`Task: ${task}`,

package/src/config-registration.ts

@@ -0,0 +1,89 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { cachedModuleLoader } from "./cached-module-loader.js";
+import { showSubagentHelp, showSubagentStatus } from "./config-status.js";
+import type { SubagentMenuOwner, SubagentSettingsRuntime } from "./config-ui.js";
+
+const SUBCOMMANDS = [
+	{ value: "settings", label: "settings", description: "Configure subagent user settings" },
+	{ value: "status", label: "status", description: "Show effective subagent settings" },
+	{ value: "help", label: "help", description: "Show subagent settings help" },
+];
+
+type ConfigUiModule = Pick<
+	typeof import("./config-ui.js"),
+	"showSubagentManager" | "showSubagentSettings"
+>;
+
+export interface ConfigRegistrationDependencies {
+	loadConfigUi?: () => Promise<ConfigUiModule>;
+}
+
+export function registerSubagentConfigLifecycle(pi: ExtensionAPI): SubagentMenuOwner {
+	const owner: SubagentMenuOwner = { generation: 0, controller: new AbortController() };
+	pi.on("session_start", () => {
+		owner.generation += 1;
+		owner.controller.abort(new DOMException("Subagent session replaced", "AbortError"));
+		owner.controller = new AbortController();
+	});
+	pi.on("session_shutdown", () => {
+		owner.generation += 1;
+		owner.controller.abort(new DOMException("Subagent session shut down", "AbortError"));
+	});
+	return owner;
+}
+
+export function registerSubagentConfigCommand(
+	pi: ExtensionAPI,
+	runtime: SubagentSettingsRuntime,
+	owner = registerSubagentConfigLifecycle(pi),
+	dependencies: ConfigRegistrationDependencies = {},
+): void {
+	const loadConfigUi = cachedModuleLoader(
+		dependencies.loadConfigUi ?? (() => import("./config-ui.js")),
+	);
+	pi.registerCommand("subagents", {
+		description: "Manage current-session subagents and user settings",
+		getArgumentCompletions(prefix: string) {
+			const normalized = prefix.trim().toLowerCase();
+			const matches = SUBCOMMANDS.filter((item) => item.value.startsWith(normalized));
+			return matches.length > 0 ? matches : null;
+		},
+		async handler(args, ctx) {
+			const subcommand = args.trim().toLowerCase();
+			if (!subcommand && ctx.mode !== "tui") {
+				showSubagentStatus(ctx, runtime);
+				return;
+			}
+			if (subcommand === "status") {
+				showSubagentStatus(ctx, runtime);
+				return;
+			}
+			if (subcommand === "help") {
+				showSubagentHelp(ctx, runtime);
+				return;
+			}
+			if (!subcommand || subcommand === "settings") {
+				const generation = owner.generation;
+				const controller = owner.controller;
+				const isCurrent = () =>
+					generation === owner.generation &&
+					controller === owner.controller &&
+					!controller.signal.aborted;
+				let configUi: ConfigUiModule;
+				try {
+					configUi = await loadConfigUi();
+				} catch (error) {
+					if (!isCurrent()) return;
+					throw error;
+				}
+				if (!isCurrent()) return;
+				if (!subcommand) await configUi.showSubagentManager(pi, ctx, runtime, owner);
+				else await configUi.showSubagentSettings(ctx, runtime, owner);
+				return;
+			}
+			if (ctx.mode === "tui" || ctx.hasUI) {
+				ctx.ui.notify(`Unknown /subagents subcommand: ${subcommand}`, "warning");
+			}
+		},
+	});
+}

package/src/config-ui.ts

@@ -168,7 +168,7 @@ function registerSubagentPrimaryCommand(
 	});
 }
 
-async function showSubagentManager(
+export async function showSubagentManager(
 	pi: ExtensionAPI,
 	ctx: ExtensionCommandContext,
 	runtime: SubagentSettingsRuntime,
@@ -681,7 +681,7 @@ async function showSubagentManager(
 	});
 }
 
-async function showSubagentSettings(
+export async function showSubagentSettings(
 	ctx: ExtensionCommandContext,
 	runtime: SubagentSettingsRuntime,
 	owner: SubagentMenuOwner,

package/src/consult-registration.ts

@@ -0,0 +1,132 @@
+import type { ExtensionAPI, ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { cachedModuleLoader, throwIfAborted } from "./cached-module-loader.js";
+import type { RegisterSubagentConsultOptions } from "./consult.js";
+import { renderConsultCall, renderConsultResult } from "./consult-render.js";
+import { type ConsultDetails, SubagentConsultParams } from "./consult-tool.js";
+import {
+	DEFAULT_CONSULT_RESOURCE_POLICY,
+	DEFAULT_CONSULTATION_CWD_POLICY,
+} from "./settings/inspection.js";
+
+interface ConsultExecutionModule {
+	executeSubagentConsult: typeof import("./consult.js").executeSubagentConsult;
+}
+
+export interface ConsultRegistrationDependencies {
+	loadExecution?: () => Promise<ConsultExecutionModule>;
+}
+
+export function registerSubagentConsult(
+	pi: ExtensionAPI,
+	options: RegisterSubagentConsultOptions,
+	dependencies: ConsultRegistrationDependencies = {},
+): (catalog: string) => void {
+	const loadExecution = cachedModuleLoader(
+		dependencies.loadExecution ?? (() => import("./consult.js")),
+	);
+	let generation = 0;
+	const active = new Set<AbortController>();
+	const activeWork = new Set<Promise<unknown>>();
+	const cancelActive = (reason: string) => {
+		generation++;
+		for (const controller of active) {
+			controller.abort(new DOMException(reason, "AbortError"));
+		}
+		active.clear();
+	};
+	const cancelAndWaitForWork = async (reason: string) => {
+		cancelActive(reason);
+		await Promise.allSettled([...activeWork]);
+	};
+	pi.on("session_start", () => cancelAndWaitForWork("Subagent consultation session replaced"));
+	pi.on("session_shutdown", () => cancelAndWaitForWork("Subagent consultation session shut down"));
+
+	const baseDescription = () =>
+		`Run one ephemeral subagent synchronously under enforced read-only tool and resource policies and return its answer. The child can use only the effective subset of Pi's built-in read, grep, find, and ls tools. Shell commands, file writes, extension tools, detached lifecycle operations, and persistent agent state are disabled. Working-directory target policy: ${options.getSettings()?.cwdPolicy?.consultation ?? DEFAULT_CONSULTATION_CWD_POLICY}; configured trusted-target resources: ${options.getSettings()?.consult?.resources ?? DEFAULT_CONSULT_RESOURCE_POLICY}; allowed targets without effective trust inherit no target/project resources. This is not a filesystem sandbox.`;
+	const definition: ToolDefinition<typeof SubagentConsultParams, ConsultDetails> = {
+		name: "subagent_consult",
+		label: "Consult Read-only Subagent",
+		description: baseDescription(),
+		promptSnippet: "Consult one constrained read-only subagent and wait for its answer",
+		promptGuidelines: [
+			"Use subagent_consult for bounded reconnaissance, planning, or review whose result is required in the current turn.",
+			"Set subagent_consult timeoutMs to the shortest realistic work deadline for the task difficulty; split oversized consultations instead of extending the deadline merely to compensate for broad scope.",
+			"Implementation-shaped tasks remain read-only and can return only analysis or instructions.",
+		],
+		parameters: SubagentConsultParams,
+		async execute(_toolCallId, params, signal, onUpdate, ctx) {
+			const ownerGeneration = generation;
+			const ownedController = new AbortController();
+			active.add(ownedController);
+			const combined = combineAbortSignals(signal, ownedController.signal);
+			const work = (async () => {
+				throwIfAborted(combined.signal, "Subagent consultation loading was cancelled");
+				let executionModule: ConsultExecutionModule;
+				try {
+					executionModule = await loadExecution();
+				} catch (error) {
+					throwIfAborted(combined.signal, "Subagent consultation loading was cancelled");
+					throw error;
+				}
+				throwIfAborted(combined.signal, "Subagent consultation loading was cancelled");
+				if (ownerGeneration !== generation) {
+					throw new DOMException("Subagent consultation owner was replaced", "AbortError");
+				}
+				return executionModule.executeSubagentConsult(
+					params,
+					combined.signal,
+					onUpdate,
+					ctx,
+					options,
+					() => ownerGeneration === generation,
+				);
+			})();
+			activeWork.add(work);
+			try {
+				return await work;
+			} finally {
+				combined.dispose();
+				active.delete(ownedController);
+				activeWork.delete(work);
+			}
+		},
+		renderCall(args, theme) {
+			return renderConsultCall(args, theme);
+		},
+		renderResult(result, renderOptions, theme, context) {
+			return renderConsultResult(result, renderOptions, theme, context);
+		},
+	};
+	pi.registerTool<typeof SubagentConsultParams, ConsultDetails>(definition);
+	pi.on("tool_result", (event) => {
+		if (event.toolName !== "subagent_consult") return;
+		if ((event.details as ConsultDetails | undefined)?.isError) return { isError: true };
+	});
+	return (catalog: string) => {
+		definition.description = catalog ? `${baseDescription()}\n\n${catalog}` : baseDescription();
+		pi.registerTool<typeof SubagentConsultParams, ConsultDetails>(definition);
+	};
+}
+
+function combineAbortSignals(
+	external: AbortSignal | undefined,
+	owned: AbortSignal,
+): { signal: AbortSignal; dispose(): void } {
+	if (!external) return { signal: owned, dispose() {} };
+	const controller = new AbortController();
+	const sources = [external, owned];
+	const listeners = sources.map((source) => {
+		const listener = () => {
+			if (!controller.signal.aborted) controller.abort(source.reason);
+		};
+		if (source.aborted) listener();
+		else source.addEventListener("abort", listener, { once: true });
+		return { source, listener };
+	});
+	return {
+		signal: controller.signal,
+		dispose() {
+			for (const { source, listener } of listeners) source.removeEventListener("abort", listener);
+		},
+	};
+}

package/src/consult-tool.ts

@@ -0,0 +1,95 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import { type Static, Type } from "typebox";
+import type { AgentScope, ConsultResourcePolicy } from "./agents/types.js";
+import { THINKING_LEVELS } from "./agents/types.js";
+import { DEFAULT_MAX_CONTEXT_BYTES, MAX_SUBAGENT_TIMEOUT_MS } from "./limits.js";
+
+const ConsultScopeSchema = StringEnum(["user", "project", "both"] as const, {
+	default: "user",
+	description: "Agent definition scope. Project scopes require a trusted project.",
+});
+const ConsultThinkingSchema = StringEnum(THINKING_LEVELS);
+
+export const SubagentConsultParams = Type.Object(
+	{
+		agent: Type.String({ minLength: 1 }),
+		task: Type.String({ minLength: 1, maxLength: DEFAULT_MAX_CONTEXT_BYTES }),
+		agentScope: Type.Optional(ConsultScopeSchema),
+		confirmProjectAgents: Type.Optional(Type.Boolean({ default: true })),
+		cwd: Type.Optional(Type.String({ minLength: 1 })),
+		timeoutMs: Type.Optional(
+			Type.Number({
+				minimum: 1,
+				maximum: MAX_SUBAGENT_TIMEOUT_MS,
+				description:
+					"Work deadline selected for the consultation difficulty. On expiry, Pi aborts the work and makes one separately bounded summary attempt.",
+			}),
+		),
+		thinkingLevel: Type.Optional(ConsultThinkingSchema),
+	},
+	{ additionalProperties: false },
+);
+
+export type SubagentConsultParams = Static<typeof SubagentConsultParams>;
+
+export interface ConsultProgressActivity {
+	type: "text" | "toolCall";
+	text?: string;
+	name?: "read" | "grep" | "find" | "ls";
+	args?: Record<string, string | number | boolean>;
+}
+
+export interface ConsultProgress {
+	phase: "starting" | "running";
+	recentActivity: ConsultProgressActivity[];
+	recentActivityTotal: number;
+	actualProvider?: string;
+	actualModel?: string;
+	usage: {
+		input: number;
+		output: number;
+		cacheRead: number;
+		cacheWrite: number;
+		cost: number;
+		contextTokens: number;
+		turns: number;
+	};
+}
+
+export interface ConsultDetails {
+	agent: string;
+	agentSource: string;
+	agentScope: AgentScope;
+	cwd: string;
+	model?: string;
+	thinkingLevel?: string;
+	timeoutMs: number;
+	policy: {
+		requestedTools: string[] | null;
+		effectiveTools: string[];
+		cwdBoundary: "current-workspace" | "external";
+		targetTrust: {
+			kind: string;
+			projectTrusted: boolean;
+			sourcePath?: string;
+			warning?: string;
+		};
+		requestedResources: ConsultResourcePolicy;
+		effectiveResources: {
+			policy: ConsultResourcePolicy;
+			projectResources: boolean;
+			contextFiles: boolean;
+			skills: boolean;
+			promptTemplates: boolean;
+		};
+		resourceDowngradeReason?: string;
+		extensions: "disabled";
+		sessionPersistence: "disabled";
+		retainedAgent: false;
+	};
+	child?: Record<string, unknown>;
+	progress?: ConsultProgress;
+	cancelled?: boolean;
+	isError?: boolean;
+	truncated?: boolean;
+}