@narumitw/pi-subagents 0.53.0 → 1.0.0

package/src/stateful-render.ts

@@ -75,7 +75,6 @@ function renderStatefulCall(tool: StatefulRenderTool, args: Record<string, unkno
 		const metadata: string[] = [];
 		if (typeof args.agentId === "string") metadata.push(`id:${safeLine(args.agentId, "", 256)}`);
 		if (args.subtree === true) metadata.push("subtree");
-		if (args.includeClosed === true) metadata.push("include closed");
 		return new Text(toolHeader(theme, "subagent_manage", args.action, metadata), 0, 0);
 	}
 	const metadata = [`id:${safeLine(args.agentId, "...", 256)}`];

package/src/stateful-safety.ts

@@ -1,7 +1,8 @@
 import { realpathSync } from "node:fs";
 import * as path from "node:path";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { type AgentScope, discoverAgents, type SubagentSettings } from "./agents.js";
+import { discoverAgents } from "./agents/discovery.js";
+import type { AgentScope, SubagentSettings } from "./agents/types.js";
 import type { AgentRegistry, ManagedAgent } from "./registry.js";
 import { safeTerminalLine } from "./safe-text.js";
 import { readSubagentSettings } from "./settings.js";

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

@@ -2,20 +2,21 @@
  * Stateful registration remains one lifecycle owner so session replacement, persistence,
  * capability revocation, workspace cleanup, and completion delivery cannot reorder.
  */
+
 import { randomUUID } from "node:crypto";
 import { StringEnum } from "@earendil-works/pi-ai";
 import { defineTool, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
+import { discoverAgents } from "./agents/discovery.js";
 import {
 	type AgentScope,
 	type CompletionDelivery,
-	discoverAgents,
 	isThinkingLevel,
 	type SubagentRuntimeSettings,
 	type SubagentSettings,
 	type SubagentTransportKind,
 	THINKING_LEVELS,
-} from "./agents.js";
+} from "./agents/types.js";
 import { issueCapabilityGrant } from "./capability-grant.js";
 import { CompletionDeliveryBroker } from "./completion-delivery.js";
 import { buildContextSnapshot, type ContextMode, redactPrivateText } from "./context.js";
@@ -26,9 +27,14 @@ import {
 	targetPolicyAudit,
 } from "./cwd-policy.js";
 import { DelegationContractSchema, normalizeDelegationContract } from "./delegation-contract.js";
-import { assertSubagentDepthAllowed } from "./execution.js";
+import { assertSubagentDepthAllowed } from "./execution/runtime-policy.js";
 import type { ChildSessionFactory, ParentRuntimeSnapshot } from "./in-process-transport.js";
-import { DEFAULT_MAX_CONTEXT_BYTES, MAX_SUBAGENT_TIMEOUT_MS, truncateUtf8 } from "./limits.js";
+import {
+	DEFAULT_MAX_CONTEXT_BYTES,
+	MAX_SUBAGENT_TIMEOUT_MS,
+	MAX_TOOL_MESSAGE_BYTES,
+	truncateUtf8,
+} from "./limits.js";
 import { AgentPersistence } from "./persistence.js";
 import {
 	AgentRegistry,
@@ -39,12 +45,14 @@ import {
 import { SUBAGENT_RESULT_FORMATS, type SubagentResultFormat } from "./result-contract.js";
 import { buildRetainedSemanticState } from "./retained-semantic-state.js";
 import { evaluateSemanticCompatibility } from "./semantic-snapshot.js";
-import { DEFAULT_DELEGATION_CWD_POLICY, readSubagentSettings } from "./settings.js";
+import { DEFAULT_DELEGATION_CWD_POLICY } from "./settings/inspection.js";
+import { readSubagentSettings } from "./settings.js";
 import {
 	assertSpawnIdempotencyKey,
 	hashSpawnRequest,
 	MAX_SPAWN_IDEMPOTENCY_KEY_LENGTH,
 } from "./spawn-idempotency.js";
+import { summarizeStatefulAgent } from "./stateful-agent-view.js";
 import { resolveCompletionDelivery, resolveStatefulTransportKind } from "./stateful-config.js";
 import { createSpawnPromptGuidelines } from "./stateful-guidance.js";
 import {
@@ -119,8 +127,6 @@ const StatefulTurnLimitFields = {
 		}),
 	),
 };
-const MAX_TOOL_MESSAGE_BYTES = 2 * 1024;
-
 export interface StatefulSubagentDependencies {
 	blockingEnabled?: boolean;
 	createInProcessSession?: ChildSessionFactory;
@@ -294,10 +300,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");
+							});
 					}
 				},
 			});
@@ -372,6 +384,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(
@@ -396,6 +411,10 @@ export function registerStatefulSubagents(
 		completionBroker?.onParentTurnStart();
 	});
 
+	pi.on("context", (event) => {
+		completionBroker?.onParentContext(event.messages);
+	});
+
 	pi.on("agent_settled", () => {
 		completionBroker?.onParentSettled();
 	});
@@ -829,8 +848,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> {
@@ -842,18 +861,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(formatLine).join("\n") : "No stateful subagents.",
-						},
-					],
-					details: { agents: agents.map(summarizeAgent) },
-				};
-			}
 			const agentId = operation.agentId;
 			if (operation.action === "interrupt") {
 				if (operation.subtree) {
@@ -862,8 +869,8 @@ export function registerStatefulSubagents(
 					return {
 						content: [{ type: "text", text: `Interrupted ${agents.length} active agent(s).` }],
 						details: {
-							agent: summarizeAgent(ownedAgent(agentId)),
-							agents: agents.map(summarizeAgent),
+							agent: summarizeStatefulAgent(ownedAgent(agentId)),
+							agents: agents.map(summarizeStatefulAgent),
 						},
 					};
 				}
@@ -890,8 +897,8 @@ export function registerStatefulSubagents(
 				return {
 					content: [{ type: "text", text: `Closed ${agents.length} agent(s).` }],
 					details: {
-						agent: summarizeAgent(ownedAgent(agentId)),
-						agents: agents.map(summarizeAgent),
+						agent: summarizeStatefulAgent(ownedAgent(agentId)),
+						agents: agents.map(summarizeStatefulAgent),
 					},
 				};
 			}
@@ -970,95 +977,6 @@ export function resolveSpawnContextMode(
 	return normalizeContextMode(value);
 }
 
-export function formatStatefulAgentLine(agent: ManagedAgent): string {
-	const elapsedSeconds = Math.max(0, Math.floor((Date.now() - agent.updatedAt) / 1000));
-	const actions =
-		agent.state === "running" || agent.state === "starting"
-			? "interrupt, close"
-			: agent.state === "closed"
-				? "inspect"
-				: "send, close";
-	const task = agent.currentTask ? ` — ${sanitizeStatusLine(agent.currentTask, 80)}` : "";
-	const unread = agent.mailbox.filter((message) => !message.readAt).length;
-	const indent = "  ".repeat(agent.depth);
-	const thinking = agent.thinkingLevel ? ` thinking:${agent.thinkingLevel}` : "";
-	const timeout = agent.currentTimeoutMs ?? agent.timeoutMs;
-	const timeoutText = timeout ? ` timeout:${timeout}ms` : "";
-	const idleTimeout = agent.currentIdleTimeoutMs ?? agent.idleTimeoutMs;
-	const idleText = idleTimeout ? ` idle:${idleTimeout}ms` : "";
-	const maxTurns = agent.currentMaxTurns ?? agent.maxTurns;
-	const turnsText = maxTurns ? ` turns:${maxTurns}` : "";
-	const maxToolCalls = agent.currentMaxToolCalls ?? agent.maxToolCalls;
-	const toolsText = maxToolCalls ? ` tools:${maxToolCalls}` : "";
-	const transport = agent.telemetry?.transport ? ` transport:${agent.telemetry.transport}` : "";
-	const phase = agent.telemetry?.phase ? ` phase:${agent.telemetry.phase}` : "";
-	const queued = agent.telemetry?.queuePosition ? ` queue:${agent.telemetry.queuePosition}` : "";
-	return `${indent}${sanitizeStatusLine(agent.id, 128)} ${sanitizeStatusLine(agent.agent, 128)} ${agent.state} ${elapsedSeconds}s${thinking}${timeoutText}${idleText}${turnsText}${toolsText}${transport}${phase}${queued} unread:${unread} [${actions}]${task}`;
-}
-
-function sanitizeStatusLine(value: string, maxLength: number): string {
-	return (
-		value
-			.slice(0, maxLength)
-			// biome-ignore lint/suspicious/noControlCharactersInRegex: Escape untrusted terminal controls.
-			.replace(/[\u0000-\u001f\u007f-\u009f]/gu, " ")
-			.replace(/\s+/gu, " ")
-			.trim()
-	);
-}
-
-function formatLine(agent: ManagedAgent): string {
-	return formatStatefulAgentLine(agent);
-}
-
-function summarizeAgent(agent: ManagedAgent) {
-	return {
-		id: agent.id,
-		agent: agent.agent,
-		parentId: agent.parentId,
-		rootId: agent.rootId,
-		depth: agent.depth,
-		children: [...agent.children],
-		state: agent.state,
-		createdAt: agent.createdAt,
-		updatedAt: agent.updatedAt,
-		cwd: agent.cwd,
-		workspaceMode: agent.workspaceMode ?? "shared",
-		thinkingLevel: agent.thinkingLevel,
-		timeoutMs: agent.timeoutMs,
-		currentTimeoutMs: agent.currentTimeoutMs,
-		idleTimeoutMs: agent.idleTimeoutMs,
-		currentIdleTimeoutMs: agent.currentIdleTimeoutMs,
-		maxTurns: agent.maxTurns,
-		currentMaxTurns: agent.currentMaxTurns,
-		maxToolCalls: agent.maxToolCalls,
-		currentMaxToolCalls: agent.currentMaxToolCalls,
-		currentTask: agent.currentTask
-			? truncateUtf8(agent.currentTask, MAX_TOOL_MESSAGE_BYTES).text
-			: undefined,
-		historyCount: agent.history.length,
-		unreadMessages: agent.mailbox.filter((message) => !message.readAt).length,
-		context: {
-			turns: agent.contextTurns ?? 0,
-			sources: agent.contextSourceIds?.length ?? 0,
-			bytes: agent.contextBytes ?? 0,
-			truncated: agent.contextTruncated === true,
-		},
-		resultFormat: agent.resultFormat ?? "text",
-		structuredResult: agent.structuredResult,
-		termination: agent.termination,
-		outcome: agent.outcome,
-		executionPlan: agent.executionPlan,
-		capabilityGrant: agent.capabilityGrant,
-		semanticCompatibility: agent.semanticCompatibility,
-		semanticSnapshotDigest: agent.semanticSnapshot?.digest,
-		telemetry: agent.telemetry,
-		error: agent.error ? truncateUtf8(agent.error, MAX_TOOL_MESSAGE_BYTES).text : undefined,
-		target: agent.target,
-		policy: agent.policy,
-	};
-}
-
 async function cleanupClosedWorkspaces(
 	registry: AgentRegistry,
 	isolatedAgents: Map<string, string>,
@@ -1078,7 +996,7 @@ function appendAgentCatalog(baseDescription: string, catalog: string): string {
 function result(agent: ManagedAgent, text: string) {
 	return {
 		content: [{ type: "text" as const, text }],
-		details: { agent: summarizeAgent(agent) },
+		details: { agent: summarizeStatefulAgent(agent) },
 	};
 }
 
@@ -1090,6 +1008,7 @@ export {
 	buildDetachedCompletionMessage,
 	CompletionDeliveryBroker,
 } from "./completion-delivery.js";
+export { formatStatefulAgentLine } from "./stateful-agent-view.js";
 export { resolveCompletionDelivery, resolveStatefulTransportKind } from "./stateful-config.js";
 export {
 	buildStatefulTurnPrompt,

package/src/subagents.ts

@@ -14,14 +14,13 @@ import {
 	type ExtensionAPI,
 	type ToolDefinition,
 } from "@earendil-works/pi-coding-agent";
-import {
-	type ConsultationCwdPolicy,
-	type ConsultResourcePolicy,
-	type DelegationCwdPolicy,
-	discoverAgentCatalog,
-	formatAgentCatalog,
-	type SubagentSettings,
-} from "./agents.js";
+import { discoverAgentCatalog, formatAgentCatalog } from "./agents/catalog.js";
+import type {
+	ConsultationCwdPolicy,
+	ConsultResourcePolicy,
+	DelegationCwdPolicy,
+	SubagentSettings,
+} from "./agents/types.js";
 import { registerSubagentAutomation } from "./automation.js";
 import { registerSubagentConfigCommand, registerSubagentConfigLifecycle } from "./config-ui.js";
 import { registerSubagentConsult } from "./consult.js";
@@ -256,7 +255,7 @@ function appendAgentCatalog(baseDescription: string, catalog: string): string {
 	return catalog ? `${baseDescription}\n\n${catalog}` : baseDescription;
 }
 
-export { parsePositiveInteger } from "./execution.js";
+export { parsePositiveInteger } from "./execution/runtime-policy.js";
 export { formatTokens, formatUsageStats } from "./render.js";
 export { buildPiArgs } from "./runner.js";
 export {

package/src/subprocess-transport.ts

@@ -1,9 +1,5 @@
-import {
-	type AgentConfig,
-	discoverAgents,
-	type SubagentSettings,
-	type SubagentThinkingLevel,
-} from "./agents.js";
+import { discoverAgents } from "./agents/discovery.js";
+import type { AgentConfig, SubagentSettings, SubagentThinkingLevel } from "./agents/types.js";
 import { resolvePiPromptResources } from "./prompt-resources.js";
 import type { ManagedAgent, TurnOutcome } from "./registry.js";
 import { getResultFinalOutput, runSingleAgent, type SubagentDetails } from "./runner.js";

package/src/transport-types.ts

@@ -1,4 +1,4 @@
-import type { SubagentThinkingLevel } from "./agents.js";
+import type { SubagentThinkingLevel } from "./agents/types.js";
 
 export const PI_SUBAGENTS_RPC_PROTOCOL = "pi-subagents:v1" as const;
 

package/src/transport-ui.ts

@@ -1,5 +1,5 @@
 import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
-import type { SubagentTransportKind } from "./agents.js";
+import type { SubagentTransportKind } from "./agents/types.js";
 import { safeTerminalLine as safeTerminalText } from "./safe-text.js";
 import { inspectStatefulTransportSettings, updateStatefulTransportSetting } from "./settings.js";
 import type { StatefulSubagentRuntimeStatus } from "./stateful.js";