@narumitw/pi-subagents 0.49.2 → 0.51.0

package/src/stateful-lifecycle.ts

@@ -1,6 +1,24 @@
-import type { AgentRegistry } from "./registry.js";
+import type { AgentRegistry, ManagedAgent } from "./registry.js";
 import type { WorkspaceManager } from "./workspace.js";
 
+export async function cleanupPersistedWorkspaces(
+	agents: readonly ManagedAgent[],
+	workspaceManager: WorkspaceManager,
+): Promise<number> {
+	const cleanup = (
+		workspaceManager as WorkspaceManager & {
+			cleanupPersisted?: (ownerId: string, cwd: string) => Promise<void>;
+		}
+	).cleanupPersisted?.bind(workspaceManager);
+	if (!cleanup) return 0;
+	const results = await Promise.allSettled(
+		agents
+			.filter((agent) => agent.workspaceMode === "worktree")
+			.map((agent) => cleanup(agent.id, agent.cwd)),
+	);
+	return results.filter((result) => result.status === "rejected").length;
+}
+
 export async function disposeStatefulRuntime(
 	registry: AgentRegistry | undefined,
 	workspaceManager: WorkspaceManager,
@@ -19,13 +37,38 @@ export async function disposeStatefulRuntime(
 	return errors;
 }
 
+export async function waitForOwnedSpawn<T>(
+	promise: Promise<T>,
+	signal: AbortSignal | undefined,
+): Promise<T> {
+	if (!signal) return promise;
+	if (signal.aborted) throw ownedSpawnAbortError();
+	let abortHandler: (() => void) | undefined;
+	try {
+		return await Promise.race([
+			promise,
+			new Promise<T>((_resolve, reject) => {
+				abortHandler = () => reject(ownedSpawnAbortError());
+				signal.addEventListener("abort", abortHandler, { once: true });
+				if (signal.aborted) abortHandler();
+			}),
+		]);
+	} finally {
+		if (abortHandler) signal.removeEventListener("abort", abortHandler);
+	}
+}
+
 export function assertCurrentSpawn(
 	signal: AbortSignal | undefined,
 	generation: number,
 	currentGeneration: number,
 ): void {
 	if (!signal?.aborted && generation === currentGeneration) return;
+	throw ownedSpawnAbortError();
+}
+
+function ownedSpawnAbortError(): Error {
 	const error = new Error("Subagent spawn owner was replaced or aborted");
 	error.name = "AbortError";
-	throw error;
+	return error;
 }

package/src/stateful-limit-ui.ts

@@ -0,0 +1,246 @@
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { projectAgentRecords } from "./agent-projection.js";
+import type { ManagedAgent } from "./registry.js";
+import { safeTerminalLine as safeTerminalText } from "./safe-text.js";
+import { inspectStatefulLimitSettings, updateStatefulLimitSetting } from "./settings.js";
+import type { StatefulSubagentRuntimeStatus } from "./stateful.js";
+import {
+	isValidStatefulLimit,
+	resolveStatefulLimits,
+	STATEFUL_LIMIT_DEFINITIONS,
+	type StatefulLimitField,
+	type StatefulLimits,
+	statefulLimitDefinition,
+} from "./stateful-limits.js";
+
+export interface StatefulLimitRuntime {
+	getRuntimeStatus(): StatefulSubagentRuntimeStatus;
+	listAgents(includeClosed?: boolean): ManagedAgent[];
+}
+
+export interface StatefulLimitApplyOptions {
+	signal: AbortSignal;
+	isCurrent(): boolean;
+}
+
+export function statefulLimitListScreen(runtime: StatefulLimitRuntime) {
+	const inspected = inspectStatefulLimitSettings();
+	const current = runtime.getRuntimeStatus().limits;
+	return {
+		kind: "actions" as const,
+		title: "Detached Agent Limits",
+		lines: [
+			"These limits apply after /reload or the next Pi session.",
+			"Reloading can interrupt retained detached work.",
+			...(inspected.error
+				? [
+						`Settings cannot be edited: ${safeTerminalText(inspected.error)}`,
+						`Repair ${safeTerminalText(inspected.path)} and retry.`,
+					]
+				: []),
+		],
+		items: [
+			...(inspected.values
+				? STATEFUL_LIMIT_DEFINITIONS.map((definition) => {
+						const configured = inspected.values?.[definition.field];
+						return {
+							id: definition.field,
+							label: definition.label,
+							description: `Current ${current[definition.field]} · configured ${configured?.value ?? "unavailable"} (${configured?.source ?? "unknown"})`,
+							action: "pick-stateful-limit" as const,
+						};
+					})
+				: []),
+			{ id: "back", label: "Back", action: "back" as const },
+		],
+		hint: "back" as const,
+	};
+}
+
+export function statefulLimitInputScreen(field: StatefulLimitField, runtime: StatefulLimitRuntime) {
+	const definition = statefulLimitDefinition(field);
+	const inspected = inspectStatefulLimitSettings();
+	const configured = inspected.values?.[field];
+	return {
+		kind: "input" as const,
+		title: definition.label,
+		lines: [
+			definition.description,
+			`Current session: ${runtime.getRuntimeStatus().limits[field]}`,
+			`Configured after reload: ${configured?.value ?? "unavailable"} (${configured?.source ?? "unknown"})`,
+			`Allowed: whole numbers ${definition.minimum === 0 ? "0 or greater" : "1 or greater"}`,
+			`Read from: ${safeTerminalText(inspected.path)}`,
+			...(inspected.writePath !== inspected.path
+				? [`Saves to: ${safeTerminalText(inspected.writePath)}`]
+				: []),
+		],
+		placeholder: "Enter a whole number",
+		action: "set-stateful-limit" as const,
+		hint: "back" as const,
+	};
+}
+
+export async function applyStatefulLimitSetting(
+	field: StatefulLimitField,
+	value: string | undefined,
+	ctx: ExtensionCommandContext,
+	runtime: StatefulLimitRuntime,
+	options: StatefulLimitApplyOptions,
+) {
+	const next = parseStatefulLimit(field, value);
+	if (next === undefined) {
+		notifyValidationError(field, ctx);
+		return { kind: "rejected" as const };
+	}
+	const inspected = inspectStatefulLimitSettings();
+	if (inspected.error || !inspected.values) {
+		if (options.isCurrent() && !options.signal.aborted) {
+			ctx.ui.notify(
+				`Subagent settings cannot be edited: ${safeTerminalText(inspected.error ?? "settings are unavailable")}`,
+				"error",
+			);
+		}
+		return { kind: "rejected" as const };
+	}
+	const expected = configuredValues(inspected.values);
+	if (next === expected[field]) return { kind: "back" as const };
+
+	const beforeAgents = runtime.listAgents();
+	const affectedBefore = projectedRemovedAgentIds(beforeAgents, expected, {
+		...expected,
+		[field]: next,
+	});
+	if (affectedBefore.length > 0) {
+		const confirmed = await ctx.ui.confirm(
+			`Lower ${statefulLimitDefinition(field).label}?`,
+			[
+				`This configured value would omit ${affectedBefore.length} currently retained agent record${affectedBefore.length === 1 ? "" : "s"} from projected recovery after reload.`,
+				"No agent is closed now, and this menu will not reload Pi.",
+				"A later state rewrite can make omitted records unavailable for recovery.",
+			].join("\n\n"),
+			{ signal: options.signal },
+		);
+		if (options.signal.aborted || !options.isCurrent()) return { kind: "close" as const };
+		if (!confirmed) return { kind: "rejected" as const };
+		const affectedAfter = projectedRemovedAgentIds(runtime.listAgents(), expected, {
+			...expected,
+			[field]: next,
+		});
+		if (!sameIds(affectedBefore, affectedAfter)) {
+			ctx.ui.notify("Detached agents changed while confirming; review the limit again.", "warning");
+			return { kind: "rejected" as const };
+		}
+	}
+
+	if (options.signal.aborted || !options.isCurrent()) return { kind: "close" as const };
+	try {
+		updateStatefulLimitSetting(field, next, expected);
+	} catch (error) {
+		if (options.isCurrent() && !options.signal.aborted) {
+			ctx.ui.notify(
+				`Detached limit was not saved; the previous setting is unchanged: ${formatError(error)}`,
+				"error",
+			);
+		}
+		return { kind: "rejected" as const };
+	}
+	if (options.signal.aborted || !options.isCurrent()) return { kind: "close" as const };
+	ctx.ui.notify(
+		`Saved ${statefulLimitDefinition(field).label.toLowerCase()}: ${next}. Applies after /reload; clear retained agents before reloading if their work must not be interrupted.`,
+		"info",
+	);
+	return { kind: "back" as const };
+}
+
+export function formatDetachedLimitSummary(status: StatefulSubagentRuntimeStatus): string {
+	return [
+		`${status.limits.maxAgents} retained`,
+		`${status.limits.maxActiveTurns} active turns`,
+		`${status.limits.maxChildrenPerAgent} children`,
+		`depth ${status.limits.maxDepth}`,
+		`${status.limits.maxStoredAgents} stored`,
+	].join(" · ");
+}
+
+export function formatConfiguredDetachedLimitDivergence(
+	status: StatefulSubagentRuntimeStatus,
+	values: NonNullable<ReturnType<typeof inspectStatefulLimitSettings>["values"]>,
+): string | undefined {
+	const changed = STATEFUL_LIMIT_DEFINITIONS.flatMap((definition) => {
+		const configured = values[definition.field].value;
+		return configured === status.limits[definition.field]
+			? []
+			: [`${definition.label.toLowerCase()} ${configured}`];
+	});
+	return changed.length > 0 ? `Configured after reload: ${changed.join(" · ")}` : undefined;
+}
+
+export function formatConfiguredDetachedLimits(
+	values: NonNullable<ReturnType<typeof inspectStatefulLimitSettings>["values"]>,
+): string {
+	return STATEFUL_LIMIT_DEFINITIONS.map((definition) => {
+		const snapshot = values[definition.field];
+		return `${definition.label.toLowerCase()} ${snapshot.value} (${snapshot.source})`;
+	}).join(" · ");
+}
+
+export function formatEmptyStatefulRuntime(status: StatefulSubagentRuntimeStatus): string {
+	if (!status.enabled) return "Stateful subagents are disabled in user settings.";
+	if (!status.initialized) return "Stateful subagents are not initialized for this session.";
+	return "No current-session subagents.";
+}
+
+function parseStatefulLimit(
+	field: StatefulLimitField,
+	value: string | undefined,
+): number | undefined {
+	const normalized = value?.trim() ?? "";
+	if (!/^\d+$/u.test(normalized)) return undefined;
+	const parsed = Number(normalized);
+	return isValidStatefulLimit(field, parsed) ? parsed : undefined;
+}
+
+function notifyValidationError(field: StatefulLimitField, ctx: ExtensionCommandContext): void {
+	const definition = statefulLimitDefinition(field);
+	ctx.ui.notify(
+		`${definition.label} must be a safe whole number ${definition.minimum === 0 ? "0 or greater" : "1 or greater"}.`,
+		"warning",
+	);
+}
+
+function configuredValues(
+	values: NonNullable<ReturnType<typeof inspectStatefulLimitSettings>["values"]>,
+): StatefulLimits {
+	return resolveStatefulLimits(
+		Object.fromEntries(Object.entries(values).map(([field, snapshot]) => [field, snapshot.value])),
+	);
+}
+
+function projectedRemovedAgentIds(
+	agents: readonly ManagedAgent[],
+	current: StatefulLimits,
+	next: StatefulLimits,
+): string[] {
+	const restorable = agents.filter(
+		(agent) => agent.state !== "closed" && agent.workspaceMode !== "worktree",
+	);
+	const before = projectForReload(restorable, current);
+	const afterIds = new Set(projectForReload(restorable, next).map((agent) => agent.id));
+	return before.filter((agent) => !afterIds.has(agent.id)).map((agent) => agent.id);
+}
+
+function projectForReload(agents: readonly ManagedAgent[], limits: StatefulLimits): ManagedAgent[] {
+	const stored = projectAgentRecords(agents, { maxAgents: limits.maxStoredAgents });
+	return projectAgentRecords(stored, {
+		maxAgents: limits.maxAgents,
+		maxDepth: limits.maxDepth,
+	});
+}
+
+function sameIds(left: readonly string[], right: readonly string[]): boolean {
+	return left.length === right.length && left.every((id, index) => id === right[index]);
+}
+
+function formatError(error: unknown): string {
+	return safeTerminalText(error instanceof Error ? error.message : String(error));
+}

package/src/stateful-limits.ts

@@ -0,0 +1,96 @@
+import type { SubagentRuntimeSettings } from "./agents.js";
+
+export const STATEFUL_LIMIT_FIELDS = [
+	"maxAgents",
+	"maxActiveTurns",
+	"maxChildrenPerAgent",
+	"maxDepth",
+	"maxStoredAgents",
+] as const;
+
+export type StatefulLimitField = (typeof STATEFUL_LIMIT_FIELDS)[number];
+
+export interface StatefulLimits {
+	maxAgents: number;
+	maxActiveTurns: number;
+	maxChildrenPerAgent: number;
+	maxDepth: number;
+	maxStoredAgents: number;
+}
+
+export interface StatefulLimitDefinition {
+	field: StatefulLimitField;
+	label: string;
+	description: string;
+	defaultValue: number;
+	minimum: number;
+}
+
+export const STATEFUL_LIMIT_DEFINITIONS: readonly StatefulLimitDefinition[] = [
+	{
+		field: "maxAgents",
+		label: "Retained agents",
+		description: "Running, queued, and reusable idle detached agents",
+		defaultValue: 16,
+		minimum: 1,
+	},
+	{
+		field: "maxActiveTurns",
+		label: "Active turns",
+		description: "Detached agent turns that may run at the same time",
+		defaultValue: 4,
+		minimum: 1,
+	},
+	{
+		field: "maxChildrenPerAgent",
+		label: "Children per agent",
+		description: "Direct child agents retained beneath one parent",
+		defaultValue: 8,
+		minimum: 1,
+	},
+	{
+		field: "maxDepth",
+		label: "Agent tree depth",
+		description: "Nested child levels below a root agent",
+		defaultValue: 3,
+		minimum: 0,
+	},
+	{
+		field: "maxStoredAgents",
+		label: "Stored agents",
+		description: "Detached agent records kept per session on disk",
+		defaultValue: 50,
+		minimum: 1,
+	},
+];
+
+const definitionsByField = new Map(
+	STATEFUL_LIMIT_DEFINITIONS.map((definition) => [definition.field, definition]),
+);
+
+export function statefulLimitDefinition(field: StatefulLimitField): StatefulLimitDefinition {
+	const definition = definitionsByField.get(field);
+	if (!definition) throw new Error(`Unknown stateful limit: ${field}`);
+	return definition;
+}
+
+export function isStatefulLimitField(value: string): value is StatefulLimitField {
+	return (STATEFUL_LIMIT_FIELDS as readonly string[]).includes(value);
+}
+
+export function isValidStatefulLimit(field: StatefulLimitField, value: unknown): value is number {
+	return (
+		typeof value === "number" &&
+		Number.isSafeInteger(value) &&
+		value >= statefulLimitDefinition(field).minimum
+	);
+}
+
+export function resolveStatefulLimits(settings?: SubagentRuntimeSettings): StatefulLimits {
+	return Object.fromEntries(
+		STATEFUL_LIMIT_DEFINITIONS.map((definition) => [
+			definition.field,
+			settings?.[definition.field] ?? definition.defaultValue,
+		]),
+	) as unknown as StatefulLimits;
+}

package/src/stateful-prompt.ts

@@ -1,11 +1,16 @@
 import type { AgentConfig } from "./agents.js";
 import { redactPrivateText } from "./context.js";
+import { appendDelegationContract } from "./delegation-contract.js";
 import { resolveDefaultSubagentTimeoutMs } from "./execution.js";
 import { DEFAULT_MAX_CONTEXT_BYTES, truncateUtf8 } from "./limits.js";
 import type { ManagedAgent } from "./registry.js";
+import { appendResultInstruction } from "./result-contract.js";
 
 export function buildStatefulTurnPrompt(
-	record: Pick<ManagedAgent, "context" | "history" | "mailbox" | "currentMailboxMessageIds">,
+	record: Pick<
+		ManagedAgent,
+		"context" | "history" | "mailbox" | "currentMailboxMessageIds" | "contract" | "resultFormat"
+	>,
 	task: string,
 	maxBytes = DEFAULT_MAX_CONTEXT_BYTES,
 ): { text: string; truncated: boolean } {
@@ -30,7 +35,11 @@ export function buildStatefulTurnPrompt(
 	]
 		.filter(Boolean)
 		.join("\n\n---\n\n");
-	return truncateUtf8(context, maxBytes);
+	const contracted = appendDelegationContract(context, record.contract, maxBytes);
+	return truncateUtf8(
+		appendResultInstruction(contracted.text, record.resultFormat, maxBytes),
+		maxBytes,
+	);
 }
 
 export function resolveStatefulTurnTimeout(

package/src/stateful-render.ts

@@ -43,6 +43,10 @@ function renderStatefulCall(tool: StatefulRenderTool, args: Record<string, unkno
 			safeLine(args.workspaceMode, "shared", 64),
 		];
 		if (typeof args.thinkingLevel === "string") metadata.push(`thinking:${args.thinkingLevel}`);
+		if (typeof args.timeoutMs === "number") metadata.push(`timeout:${args.timeoutMs}ms`);
+		if (typeof args.idleTimeoutMs === "number") metadata.push(`idle:${args.idleTimeoutMs}ms`);
+		if (typeof args.maxTurns === "number") metadata.push(`turns:${args.maxTurns}`);
+		if (typeof args.maxToolCalls === "number") metadata.push(`tools:${args.maxToolCalls}`);
 		return new Text(
 			[
 				toolHeader(theme, "subagent_spawn", args.agent, metadata),
@@ -53,9 +57,14 @@ function renderStatefulCall(tool: StatefulRenderTool, args: Record<string, unkno
 		);
 	}
 	if (tool === "send") {
+		const metadata = ["follow-up"];
+		if (typeof args.timeoutMs === "number") metadata.push(`timeout:${args.timeoutMs}ms`);
+		if (typeof args.idleTimeoutMs === "number") metadata.push(`idle:${args.idleTimeoutMs}ms`);
+		if (typeof args.maxTurns === "number") metadata.push(`turns:${args.maxTurns}`);
+		if (typeof args.maxToolCalls === "number") metadata.push(`tools:${args.maxToolCalls}`);
 		return new Text(
 			[
-				toolHeader(theme, "subagent_send", args.agentId, ["follow-up"]),
+				toolHeader(theme, "subagent_send", args.agentId, metadata),
 				`  ${theme.fg("dim", safeLine(args.task, "...", 2 * 1024))}`,
 			].join("\n"),
 			0,
@@ -112,12 +121,43 @@ function renderAgentResult(
 		`${statusBadge(theme, lifecycleStatus(state))} · ${theme.fg("accent", safeLine(agent.id, "agent", 256))} · ${theme.fg("toolOutput", safeLine(agent.agent, "subagent", 256))} · ${theme.fg("muted", state)}`,
 	];
 	const thinking = stringValue(agent.thinkingLevel);
+	const timeout =
+		typeof agent.currentTimeoutMs === "number"
+			? agent.currentTimeoutMs
+			: typeof agent.timeoutMs === "number"
+				? agent.timeoutMs
+				: 0;
+	const idleTimeout =
+		typeof agent.currentIdleTimeoutMs === "number"
+			? agent.currentIdleTimeoutMs
+			: typeof agent.idleTimeoutMs === "number"
+				? agent.idleTimeoutMs
+				: 0;
+	const maxTurns =
+		typeof agent.currentMaxTurns === "number"
+			? agent.currentMaxTurns
+			: typeof agent.maxTurns === "number"
+				? agent.maxTurns
+				: 0;
+	const maxToolCalls =
+		typeof agent.currentMaxToolCalls === "number"
+			? agent.currentMaxToolCalls
+			: typeof agent.maxToolCalls === "number"
+				? agent.maxToolCalls
+				: 0;
 	const unread = typeof agent.unreadMessages === "number" ? agent.unreadMessages : 0;
-	if (thinking || unread > 0) {
+	if (thinking || timeout || idleTimeout || maxTurns || maxToolCalls || unread > 0) {
 		lines.push(
 			theme.fg(
 				"dim",
-				[thinking && `thinking:${safeLine(thinking, "", 128)}`, unread > 0 && `unread:${unread}`]
+				[
+					thinking && `thinking:${safeLine(thinking, "", 128)}`,
+					timeout && `timeout:${timeout}ms`,
+					idleTimeout && `idle:${idleTimeout}ms`,
+					maxTurns && `turns:${maxTurns}`,
+					maxToolCalls && `tools:${maxToolCalls}`,
+					unread > 0 && `unread:${unread}`,
+				]
 					.filter(Boolean)
 					.join(" · "),
 			),
@@ -237,6 +277,11 @@ function lifecycleStatus(state: string): RenderStatus {
 			return "running";
 		case "idle":
 			return "idle";
+		case "blocked":
+		case "needs-input":
+		case "abstained":
+		case "stale":
+			return "warning";
 		case "failed":
 			return "failed";
 		case "interrupted":