@narumitw/pi-subagents 0.54.0 → 1.0.1

package/src/stateful-tool-params.ts

@@ -1,25 +1,18 @@
 import { StringEnum } from "@earendil-works/pi-ai";
 import { Type } from "typebox";
 
-const MANAGE_ACTIONS = ["list", "interrupt", "close"] as const;
+const MANAGE_ACTIONS = ["interrupt", "close"] as const;
 const MAILBOX_ACTIONS = ["send", "read"] as const;
 const MAX_MAILBOX_MESSAGE_LENGTH = 16 * 1024;
 
 export const ManageParamsSchema = Type.Object(
 	{
 		action: StringEnum(MANAGE_ACTIONS, {
-			description:
-				"Use list to inspect agents, interrupt to stop active work, or close to release agents.",
+			description: "Interrupt active work or close an agent and release its resources.",
 		}),
 		agentId: Type.Optional(
 			Type.String({ minLength: 1, description: "Required for interrupt and close." }),
 		),
-		includeClosed: Type.Optional(
-			Type.Boolean({
-				default: false,
-				description: "List closed records as well as retained agents.",
-			}),
-		),
 		subtree: Type.Optional(
 			Type.Boolean({
 				default: false,
@@ -57,9 +50,11 @@ export const MailboxParamsSchema = Type.Object(
 	{ additionalProperties: false },
 );
 
-export type ValidatedManageParams =
-	| { action: "list"; includeClosed?: boolean }
-	| { action: "interrupt" | "close"; agentId: string; subtree?: boolean };
+export type ValidatedManageParams = {
+	action: "interrupt" | "close";
+	agentId: string;
+	subtree?: boolean;
+};
 
 export type ValidatedMailboxParams =
 	| {
@@ -73,21 +68,19 @@ export type ValidatedMailboxParams =
 
 export function validateManageParams(params: unknown): ValidatedManageParams {
 	const values = parameterRecord(params, "subagent_manage");
-	assertKnownKeys("subagent_manage", values, ["action", "agentId", "includeClosed", "subtree"]);
+	assertKnownKeys("subagent_manage", values, ["action", "agentId", "subtree"]);
 	const action = values.action;
+	if (action === "list") {
+		throw new Error(
+			'subagent_manage no longer supports "list"; use subagent_inspect action "list_runs"',
+		);
+	}
 	if (
 		typeof action !== "string" ||
 		!MANAGE_ACTIONS.includes(action as (typeof MANAGE_ACTIONS)[number])
 	) {
 		throw new Error(`subagent_manage action must be one of: ${MANAGE_ACTIONS.join(", ")}`);
 	}
-	if (action === "list") {
-		assertOptionalBoolean("subagent_manage", action, values, "includeClosed");
-		return {
-			action,
-			...(values.includeClosed === undefined ? {} : { includeClosed: values.includeClosed }),
-		} as ValidatedManageParams;
-	}
 	assertRequiredString("subagent_manage", action, values, "agentId");
 	assertOptionalBoolean("subagent_manage", action, values, "subtree");
 	return {

package/src/stateful.ts

@@ -20,7 +20,10 @@ import {
 import { issueCapabilityGrant } from "./capability-grant.js";
 import { CompletionDeliveryBroker } from "./completion-delivery.js";
 import { buildContextSnapshot, type ContextMode, redactPrivateText } from "./context.js";
-import { createStatefulTransport } from "./create-stateful-transport.js";
+import {
+	type CreateStatefulTransportOptions,
+	createStatefulTransport,
+} from "./create-stateful-transport.js";
 import {
 	assertDelegationTargetAllowed,
 	resolveSubagentTarget,
@@ -52,7 +55,7 @@ import {
 	hashSpawnRequest,
 	MAX_SPAWN_IDEMPOTENCY_KEY_LENGTH,
 } from "./spawn-idempotency.js";
-import { formatStatefulAgentLine, summarizeStatefulAgent } from "./stateful-agent-view.js";
+import { summarizeStatefulAgent } from "./stateful-agent-view.js";
 import { resolveCompletionDelivery, resolveStatefulTransportKind } from "./stateful-config.js";
 import { createSpawnPromptGuidelines } from "./stateful-guidance.js";
 import {
@@ -133,6 +136,7 @@ export interface StatefulSubagentDependencies {
 	workspaceManager?: WorkspaceManager;
 	settings?: SubagentRuntimeSettings;
 	getSettings?: () => SubagentSettings | undefined;
+	loadTransport?: CreateStatefulTransportOptions["loadTransport"];
 }
 
 export interface StatefulSubagentRuntimeStatus {
@@ -300,10 +304,16 @@ export function registerStatefulSubagents(
 					const reason = error instanceof Error ? error.message : String(error);
 					ctx.ui.notify(`Subagent completion delivery failed: ${reason}`, "warning");
 				},
-				onDelivered: (completions, deliveredAt) => {
+				onAcknowledged: (completions, deliveredAt) => {
 					if (generation !== runtimeGeneration) return;
 					for (const completion of completions) {
-						nextRegistry.markCompletionDelivered(completion.agent.id, deliveredAt);
+						void nextRegistry
+							.markCompletionDelivered(completion.completionId, deliveredAt)
+							.catch((error: unknown) => {
+								if (!ctx.hasUI || generation !== runtimeGeneration) return;
+								const reason = error instanceof Error ? error.message : String(error);
+								ctx.ui.notify(`Subagent completion acknowledgement failed: ${reason}`, "warning");
+							});
 					}
 				},
 			});
@@ -313,6 +323,7 @@ export function registerStatefulSubagents(
 				getParentRuntime: () => ({ ...parentRuntime }),
 				getSettings: getCurrentSettings,
 				createInProcessSession: dependencies.createInProcessSession,
+				loadTransport: dependencies.loadTransport,
 			});
 			nextRegistry = new AgentRegistry(transport, {
 				maxAgents: nextLimits.maxAgents,
@@ -378,6 +389,9 @@ export function registerStatefulSubagents(
 			registry = nextRegistry;
 			persistence = sessionPersistence;
 			completionBroker = sessionBroker;
+			for (const completion of nextRegistry.listPendingCompletions()) {
+				sessionBroker.enqueue(completion);
+			}
 			runtimeLimits = nextLimits;
 			refreshSpawnToolRegistration?.();
 			const sweepEveryMs = Math.max(
@@ -402,6 +416,10 @@ export function registerStatefulSubagents(
 		completionBroker?.onParentTurnStart();
 	});
 
+	pi.on("context", (event) => {
+		completionBroker?.onParentContext(event.messages);
+	});
+
 	pi.on("agent_settled", () => {
 		completionBroker?.onParentSettled();
 	});
@@ -835,8 +853,8 @@ export function registerStatefulSubagents(
 		name: "subagent_manage",
 		label: "Manage Subagents",
 		description:
-			"List retained subagents through the compatibility route, interrupt active work while keeping an agent reusable, or close agents and release their resources. Prefer subagent_inspect when the whole activated capability must be read-only.",
-		promptSnippet: "List or control retained detached subagents",
+			"Interrupt active work while keeping an agent reusable, or close agents and release their resources. Use subagent_inspect for every read-only list, detail, status, and diagnostic operation.",
+		promptSnippet: "Interrupt or close retained detached subagents",
 		parameters: ManageParamsSchema,
 		...createStatefulToolRenderer("manage"),
 		async execute(_id, params, signal): Promise<StatefulActionToolResult> {
@@ -848,20 +866,6 @@ export function registerStatefulSubagents(
 				return value;
 			};
 			const operation = validateManageParams(params);
-			if (operation.action === "list") {
-				const agents = ownedRegistry.list(operation.includeClosed);
-				return {
-					content: [
-						{
-							type: "text",
-							text: agents.length
-								? agents.map(formatStatefulAgentLine).join("\n")
-								: "No stateful subagents.",
-						},
-					],
-					details: { agents: agents.map(summarizeStatefulAgent) },
-				};
-			}
 			const agentId = operation.agentId;
 			if (operation.action === "interrupt") {
 				if (operation.subtree) {

package/src/subagents.ts

@@ -21,11 +21,24 @@ import type {
 	DelegationCwdPolicy,
 	SubagentSettings,
 } from "./agents/types.js";
-import { registerSubagentAutomation } from "./automation.js";
-import { registerSubagentConfigCommand, registerSubagentConfigLifecycle } from "./config-ui.js";
-import { registerSubagentConsult } from "./consult.js";
-import { executeSubagent } from "./execution.js";
-import { registerSubagentInspect } from "./inspect.js";
+import {
+	type AutomationRegistrationDependencies,
+	registerSubagentAutomation,
+} from "./automation-registration.js";
+import { cachedModuleLoader, throwIfAborted } from "./cached-module-loader.js";
+import {
+	type ConfigRegistrationDependencies,
+	registerSubagentConfigCommand,
+	registerSubagentConfigLifecycle,
+} from "./config-registration.js";
+import {
+	type ConsultRegistrationDependencies,
+	registerSubagentConsult,
+} from "./consult-registration.js";
+import {
+	type InspectRegistrationDependencies,
+	registerSubagentInspect,
+} from "./inspect-registration.js";
 import { MAX_BLOCKING_PARALLEL_CONCURRENCY } from "./limits.js";
 import { SubagentParams } from "./params.js";
 import { renderSubagentCall, renderSubagentResult } from "./render.js";
@@ -40,17 +53,34 @@ import {
 	resolveBlockingMaxParallelTasks,
 } from "./settings.js";
 import { registerStatefulSubagents } from "./stateful.js";
+import type { SubagentTransport } from "./transport.js";
+
+type BlockingExecutionModule = Pick<typeof import("./execution.js"), "executeSubagent">;
+
+export interface SubagentsDependencies {
+	loadBlockingExecution?: () => Promise<BlockingExecutionModule>;
+	loadStatefulTransport?: () => Promise<SubagentTransport>;
+	automation?: AutomationRegistrationDependencies;
+	config?: ConfigRegistrationDependencies;
+	consult?: ConsultRegistrationDependencies;
+	inspect?: InspectRegistrationDependencies;
+}
 
-export default function (pi: ExtensionAPI) {
+export default function (pi: ExtensionAPI, dependencies: SubagentsDependencies = {}) {
+	const loadBlockingExecution = cachedModuleLoader(
+		dependencies.loadBlockingExecution ?? (() => import("./execution.js")),
+	);
 	const configOwner = registerSubagentConfigLifecycle(pi);
 	const settings = readSubagentSettings();
 	let currentSettings: SubagentSettings | undefined = settings;
 	let currentCatalog = "";
 	const blockingEnabled = settings?.blocking?.enabled !== false;
 	const refreshBlockingCatalog = blockingEnabled
-		? registerBlockingSubagent(pi, () => currentSettings)
+		? registerBlockingSubagent(pi, () => currentSettings, loadBlockingExecution)
 		: () => undefined;
-	if (blockingEnabled) registerSubagentAutomation(pi, { getSettings: () => currentSettings });
+	if (blockingEnabled) {
+		registerSubagentAutomation(pi, { getSettings: () => currentSettings }, dependencies.automation);
+	}
 	let refreshStatefulCatalog: (catalog: string) => void = () => undefined;
 	let refreshConsultCatalog: (catalog: string) => void = () => undefined;
 
@@ -78,6 +108,7 @@ export default function (pi: ExtensionAPI) {
 		blockingEnabled,
 		settings: settings?.stateful,
 		getSettings: () => currentSettings,
+		loadTransport: dependencies.loadStatefulTransport,
 	});
 	refreshStatefulCatalog = statefulRuntime.setAgentCatalog;
 	const getBlockingEnabled = () => blockingEnabled;
@@ -88,18 +119,24 @@ export default function (pi: ExtensionAPI) {
 		currentSettings?.cwdPolicy?.consultation ?? DEFAULT_CONSULTATION_CWD_POLICY;
 	const getDelegationCwdPolicy = () =>
 		currentSettings?.cwdPolicy?.delegation ?? DEFAULT_DELEGATION_CWD_POLICY;
-	registerSubagentInspect(pi, {
-		...statefulRuntime,
-		getBlockingEnabled,
-		getMaxParallelTasks,
-		getConsultResourcePolicy,
-		getConsultationCwdPolicy,
-		getDelegationCwdPolicy,
-	});
+	registerSubagentInspect(
+		pi,
+		{
+			...statefulRuntime,
+			getBlockingEnabled,
+			getMaxParallelTasks,
+			getConsultResourcePolicy,
+			getConsultationCwdPolicy,
+			getDelegationCwdPolicy,
+		},
+		dependencies.inspect,
+	);
 	if (blockingEnabled) {
-		refreshConsultCatalog = registerSubagentConsult(pi, {
-			getSettings: () => currentSettings,
-		});
+		refreshConsultCatalog = registerSubagentConsult(
+			pi,
+			{ getSettings: () => currentSettings },
+			dependencies.consult,
+		);
 	}
 	registerSubagentConfigCommand(
 		pi,
@@ -155,12 +192,14 @@ export default function (pi: ExtensionAPI) {
 			},
 		},
 		configOwner,
+		dependencies.config,
 	);
 }
 
 function registerBlockingSubagent(
 	pi: ExtensionAPI,
 	getSettings: () => SubagentSettings | undefined,
+	loadExecution: () => Promise<BlockingExecutionModule>,
 ): (catalog: string) => void {
 	let catalog = "";
 	const activeControllers = new Set<AbortController>();
@@ -212,14 +251,28 @@ function registerBlockingSubagent(
 			const effectiveSignal = signal
 				? AbortSignal.any([signal, lifecycleController.signal])
 				: lifecycleController.signal;
-			const work = executeSubagent(
-				toolCallId,
-				params,
-				effectiveSignal,
-				onUpdate,
-				ctx,
-				getSettings(),
-			);
+			const work = (async () => {
+				throwIfAborted(effectiveSignal, "Blocking subagent execution was cancelled");
+				let executionModule: BlockingExecutionModule;
+				try {
+					executionModule = await loadExecution();
+				} catch (error) {
+					throwIfAborted(
+						effectiveSignal,
+						"Blocking subagent execution was cancelled while loading",
+					);
+					throw error;
+				}
+				throwIfAborted(effectiveSignal, "Blocking subagent execution was cancelled while loading");
+				return executionModule.executeSubagent(
+					toolCallId,
+					params,
+					effectiveSignal,
+					onUpdate,
+					ctx,
+					getSettings(),
+				);
+			})();
 			activeWork.add(work);
 			try {
 				return await work;
@@ -256,8 +309,8 @@ function appendAgentCatalog(baseDescription: string, catalog: string): string {
 }
 
 export { parsePositiveInteger } from "./execution/runtime-policy.js";
+export { buildPiArgs } from "./pi-args.js";
 export { formatTokens, formatUsageStats } from "./render.js";
-export { buildPiArgs } from "./runner.js";
 export {
 	DEFAULT_CONSULT_RESOURCE_POLICY,
 	DEFAULT_CONSULTATION_CWD_POLICY,

package/src/verified-execution-contract.ts

@@ -1,41 +1,13 @@
-import { StringEnum } from "@earendil-works/pi-ai";
-import { type Static, Type } from "typebox";
 import { normalizeDelegationContract } from "./delegation-contract.js";
 import {
 	type VerificationCheckRequest,
 	validateVerificationChecks,
 } from "./verification-harness.js";
+import type { VerifiedExecutionContract } from "./verified-execution-schema.js";
 import type { ResolvedWorkflowTask } from "./workflow-planning.js";
 
-const VerificationCheckSchema = Type.Object(
-	{
-		id: Type.String({
-			minLength: 1,
-			maxLength: 256,
-			pattern: "^[A-Za-z0-9][A-Za-z0-9._:-]{0,255}$",
-		}),
-		command: StringEnum(["git", "node", "npm", "npx"] as const),
-		args: Type.Optional(Type.Array(Type.String({ maxLength: 4096 }), { maxItems: 64 })),
-		cwd: Type.Optional(Type.String({ minLength: 1, maxLength: 4096 })),
-		timeoutMs: Type.Optional(Type.Integer({ minimum: 1, maximum: 600_000 })),
-	},
-	{ additionalProperties: false },
-);
-
-export const VerifiedExecutionContractSchema = Type.Object(
-	{
-		verifierAgent: Type.String({ minLength: 1, maxLength: 256 }),
-		maxReworkCycles: Type.Optional(Type.Integer({ minimum: 0, maximum: 1, default: 1 })),
-		checks: Type.Optional(Type.Array(VerificationCheckSchema, { maxItems: 32 })),
-	},
-	{
-		additionalProperties: false,
-		description:
-			"Explicitly gate mutating workflow success on executor-owned deterministic checks, one least-authority independent verifier, exact submitted-state identity, and managed integration acceptance.",
-	},
-);
-
-export type VerifiedExecutionContract = Static<typeof VerifiedExecutionContractSchema>;
+export type { VerifiedExecutionContract } from "./verified-execution-schema.js";
+export { VerifiedExecutionContractSchema } from "./verified-execution-schema.js";
 
 export interface PreparedVerifiedWorkflow {
 	tasks: ResolvedWorkflowTask[];

package/src/verified-execution-schema.ts

@@ -0,0 +1,32 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import { type Static, Type } from "typebox";
+
+const VerificationCheckSchema = Type.Object(
+	{
+		id: Type.String({
+			minLength: 1,
+			maxLength: 256,
+			pattern: "^[A-Za-z0-9][A-Za-z0-9._:-]{0,255}$",
+		}),
+		command: StringEnum(["git", "node", "npm", "npx"] as const),
+		args: Type.Optional(Type.Array(Type.String({ maxLength: 4096 }), { maxItems: 64 })),
+		cwd: Type.Optional(Type.String({ minLength: 1, maxLength: 4096 })),
+		timeoutMs: Type.Optional(Type.Integer({ minimum: 1, maximum: 600_000 })),
+	},
+	{ additionalProperties: false },
+);
+
+export const VerifiedExecutionContractSchema = Type.Object(
+	{
+		verifierAgent: Type.String({ minLength: 1, maxLength: 256 }),
+		maxReworkCycles: Type.Optional(Type.Integer({ minimum: 0, maximum: 1, default: 1 })),
+		checks: Type.Optional(Type.Array(VerificationCheckSchema, { maxItems: 32 })),
+	},
+	{
+		additionalProperties: false,
+		description:
+			"Explicitly gate mutating workflow success on executor-owned deterministic checks, one least-authority independent verifier, exact submitted-state identity, and managed integration acceptance.",
+	},
+);
+
+export type VerifiedExecutionContract = Static<typeof VerifiedExecutionContractSchema>;