@narumitw/pi-subagents 2.1.3 → 3.0.0

package/src/stateful-lifecycle.ts

@@ -1,74 +0,0 @@
-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,
-): Promise<unknown[]> {
-	const errors: unknown[] = [];
-	try {
-		await registry?.shutdown();
-	} catch (error) {
-		errors.push(error);
-	}
-	try {
-		await workspaceManager.cleanupAll();
-	} catch (error) {
-		errors.push(error);
-	}
-	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";
-	return error;
-}

package/src/stateful-limit-ui.ts

@@ -1,249 +0,0 @@
-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: "Background Agent Limits",
-		lines: [
-			"These advanced limits apply after /reload or the next Pi session.",
-			"Reloading can interrupt subagents saved for follow-up.",
-			...(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]} · after reload: ${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]}`,
-			`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}?`,
-			[
-				`After reload, this value could exclude ${affectedBefore.length} saved subagent record${affectedBefore.length === 1 ? "" : "s"} from recovery.`,
-				"No subagent is removed now, and this menu will not reload Pi.",
-				"A later state save can make excluded 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(
-				"Current subagents 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(
-				`Background-agent 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 current subagents first if their work must not be interrupted.`,
-		"info",
-	);
-	return { kind: "back" as const };
-}
-
-export function formatDetachedLimitSummary(status: StatefulSubagentRuntimeStatus): string {
-	return [
-		`${status.limits.maxAgents} saved`,
-		`${status.limits.maxActiveTurns} working at once`,
-		`${status.limits.maxChildrenPerAgent} children each`,
-		`${status.limits.maxDepth} nested levels`,
-		`${status.limits.maxStoredAgents} stored records`,
-	].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 ? `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 "Background subagents are disabled in How subagents run.";
-	if (!status.initialized) return "Background subagents have not started in this session.";
-	return "No subagents are working or saved for follow-up in this session.";
-}
-
-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

@@ -1,96 +0,0 @@
-import type { SubagentRuntimeSettings } from "./agents/types.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: "Subagents saved for follow-up",
-		description: "Working, queued, and reusable background subagents kept in one session",
-		defaultValue: 16,
-		minimum: 1,
-	},
-	{
-		field: "maxActiveTurns",
-		label: "Subagents working at once",
-		description: "Background subagent turns that may run at the same time",
-		defaultValue: 4,
-		minimum: 1,
-	},
-	{
-		field: "maxChildrenPerAgent",
-		label: "Direct children per subagent",
-		description: "Subagents that one parent subagent may keep for follow-up",
-		defaultValue: 8,
-		minimum: 1,
-	},
-	{
-		field: "maxDepth",
-		label: "Nested subagent levels",
-		description: "Child levels allowed below a top-level subagent",
-		defaultValue: 3,
-		minimum: 0,
-	},
-	{
-		field: "maxStoredAgents",
-		label: "Stored subagent records",
-		description: "Background subagent records kept on disk for each session",
-		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,49 +0,0 @@
-import type { AgentConfig } from "./agents/types.js";
-import { redactPrivateText } from "./context.js";
-import { appendDelegationContract } from "./delegation-contract.js";
-import { resolveDefaultSubagentTimeoutMs } from "./execution/runtime-policy.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" | "contract" | "resultFormat"
-	>,
-	task: string,
-	maxBytes = DEFAULT_MAX_CONTEXT_BYTES,
-): { text: string; truncated: boolean } {
-	const previous = record.history
-		.map((turn) => {
-			const redactedTask = redactPrivateText(turn.task);
-			const redactedOutput = redactPrivateText(turn.output);
-			return `Task: ${redactedTask}\nOutput: ${redactedOutput}`;
-		})
-		.join("\n\n");
-	const currentMessageIds = new Set(record.currentMailboxMessageIds ?? []);
-	const messages = record.mailbox
-		.filter((message) => currentMessageIds.has(message.id))
-		.slice(-20)
-		.map((message) => `From ${message.senderId}: ${redactPrivateText(message.content)}`)
-		.join("\n");
-	const context = [
-		`Current task:\n${redactPrivateText(task)}`,
-		messages ? `Mailbox messages:\n${messages}` : "",
-		previous ? `Prior subagent turns:\n${previous}` : "",
-		record.context ? `Parent context:\n${redactPrivateText(record.context)}` : "",
-	]
-		.filter(Boolean)
-		.join("\n\n---\n\n");
-	const contracted = appendDelegationContract(context, record.contract, maxBytes);
-	return truncateUtf8(
-		appendResultInstruction(contracted.text, record.resultFormat, maxBytes),
-		maxBytes,
-	);
-}
-
-export function resolveStatefulTurnTimeout(
-	agent: Pick<AgentConfig, "timeoutMs"> | undefined,
-): number {
-	return agent?.timeoutMs ?? resolveDefaultSubagentTimeoutMs();
-}