@narumitw/pi-subagents 0.53.0 → 1.0.0

package/src/settings.ts

@@ -3,26 +3,44 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import lockfile from "proper-lockfile";
+import type {
+	AgentConfig,
+	CompletionDelivery,
+	ConsultationCwdPolicy,
+	ConsultResourcePolicy,
+	DelegationCwdPolicy,
+	SubagentAgentConfig,
+	SubagentSettings,
+	SubagentThinkingLevel,
+	SubagentTransportKind,
+} from "./agents/types.js";
+import { MAX_CONFIGURABLE_PARALLEL_TASKS } from "./limits.js";
 import {
-	type AgentConfig,
-	CONSULT_RESOURCE_POLICIES,
-	CONSULTATION_CWD_POLICIES,
-	type CompletionDelivery,
-	type ConsultationCwdPolicy,
-	type ConsultResourcePolicy,
-	DELEGATION_CWD_POLICIES,
-	type DelegationCwdPolicy,
-	isThinkingLevel,
-	type SubagentAgentConfig,
-	type SubagentSettings,
-	type SubagentThinkingLevel,
-	type SubagentTransportKind,
-} from "./agents.js";
+	type BlockingParallelLimitSettingsSnapshot,
+	buildBlockingParallelLimitSettingsSnapshot,
+	buildCompletionDeliverySettingsSnapshot,
+	buildConsultResourceSettingsSnapshot,
+	buildCwdPolicySettingsSnapshot,
+	buildDelegationWorkflowSettingsSnapshot,
+	buildStatefulLimitSettingsSnapshot,
+	buildStatefulTransportSettingsSnapshot,
+	buildSubagentSettingsSnapshot,
+	type CompletionDeliverySettingsSnapshot,
+	type ConsultResourceSettingsSnapshot,
+	type CwdPolicySettingsSnapshot,
+	type DelegationWorkflow,
+	type DelegationWorkflowSettingsSnapshot,
+	type InspectedSubagentSettingsDocument,
+	type StatefulLimitSettingsSnapshot,
+	type StatefulTransportSettingsSnapshot,
+	type SubagentSettingsSnapshot,
+} from "./settings/inspection.js";
 import {
-	DEFAULT_MAX_PARALLEL_TASKS,
-	MAX_CONFIGURABLE_PARALLEL_TASKS,
-	MAX_SUBAGENT_TIMEOUT_MS,
-} from "./limits.js";
+	hasOwn,
+	isPlainObject,
+	isPositiveInteger,
+	normalizeSubagentSettings,
+} from "./settings/schema.js";
 import {
 	isValidStatefulLimit,
 	resolveStatefulLimits,
@@ -32,185 +50,32 @@ import {
 	statefulLimitDefinition,
 } from "./stateful-limits.js";
 
-export function hasOwn(obj: object, key: PropertyKey): boolean {
-	return Object.hasOwn(obj, key);
-}
-
-function isPlainObject(value: unknown): value is Record<string, unknown> {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-function isStringArray(value: unknown): value is string[] {
-	return Array.isArray(value) && value.every((item) => typeof item === "string");
-}
-
-function isPositiveNumber(value: unknown): value is number {
-	return typeof value === "number" && Number.isFinite(value) && value >= 1;
-}
-
-function isPositiveInteger(value: unknown): value is number {
-	return isPositiveNumber(value) && Number.isSafeInteger(value);
-}
-
-export function normalizeAgentSettings(value: unknown): SubagentAgentConfig | undefined {
-	if (!isPlainObject(value)) return undefined;
-
-	const config: SubagentAgentConfig = {};
-	let hasKnownField = false;
-
-	if (hasOwn(value, "tools")) {
-		if (!isStringArray(value.tools)) return undefined;
-		config.tools = value.tools;
-		hasKnownField = true;
-	}
-
-	if (hasOwn(value, "model")) {
-		if (value.model !== null && typeof value.model !== "string") return undefined;
-		config.model = value.model;
-		hasKnownField = true;
-	}
-
-	if (hasOwn(value, "thinkingLevel")) {
-		if (value.thinkingLevel !== null && !isThinkingLevel(value.thinkingLevel)) return undefined;
-		config.thinkingLevel = value.thinkingLevel;
-		hasKnownField = true;
-	}
-
-	if (hasOwn(value, "timeoutMs")) {
-		if (
-			value.timeoutMs !== null &&
-			(!isPositiveNumber(value.timeoutMs) || value.timeoutMs > MAX_SUBAGENT_TIMEOUT_MS)
-		) {
-			return undefined;
-		}
-		config.timeoutMs = value.timeoutMs;
-		hasKnownField = true;
-	}
-
-	return hasKnownField ? config : undefined;
-}
-
-export function normalizeSubagentSettings(value: unknown): SubagentSettings | undefined {
-	if (!isPlainObject(value)) return undefined;
-	const settings: SubagentSettings = {};
-	if (hasOwn(value, "agents")) {
-		if (!isPlainObject(value.agents)) return undefined;
-		const agents: Record<string, SubagentAgentConfig> = {};
-		for (const [name, rawConfig] of Object.entries(value.agents)) {
-			const config = normalizeAgentSettings(rawConfig);
-			if (config) agents[name] = config;
-		}
-		if (Object.keys(agents).length > 0) settings.agents = agents;
-	}
-	if (hasOwn(value, "blocking")) {
-		if (!isPlainObject(value.blocking)) return undefined;
-		const blocking: NonNullable<SubagentSettings["blocking"]> = {};
-		if (hasOwn(value.blocking, "enabled")) {
-			if (typeof value.blocking.enabled !== "boolean") return undefined;
-			blocking.enabled = value.blocking.enabled;
-		}
-		if (hasOwn(value.blocking, "maxParallelTasks")) {
-			if (
-				!isPositiveInteger(value.blocking.maxParallelTasks) ||
-				value.blocking.maxParallelTasks > MAX_CONFIGURABLE_PARALLEL_TASKS
-			) {
-				return undefined;
-			}
-			blocking.maxParallelTasks = value.blocking.maxParallelTasks;
-		}
-		settings.blocking = blocking;
-	}
-	if (hasOwn(value, "stateful")) {
-		if (!isPlainObject(value.stateful)) return undefined;
-		const runtime: NonNullable<SubagentSettings["stateful"]> = {};
-		if (hasOwn(value.stateful, "transport")) {
-			if (
-				value.stateful.transport !== "subprocess" &&
-				value.stateful.transport !== "in-process" &&
-				value.stateful.transport !== "rpc" &&
-				value.stateful.transport !== "auto"
-			) {
-				return undefined;
-			}
-			runtime.transport = value.stateful.transport;
-		}
-		if (hasOwn(value.stateful, "completionDelivery")) {
-			if (
-				value.stateful.completionDelivery !== "next-turn" &&
-				value.stateful.completionDelivery !== "auto-resume"
-			) {
-				return undefined;
-			}
-			runtime.completionDelivery = value.stateful.completionDelivery;
-		}
-		for (const key of STATEFUL_LIMIT_FIELDS) {
-			if (hasOwn(value.stateful, key)) {
-				if (!isValidStatefulLimit(key, value.stateful[key])) return undefined;
-				runtime[key] = value.stateful[key];
-			}
-		}
-		for (const key of ["maxMailboxMessages", "maxMailboxMessageBytes", "idleTtlMs"] as const) {
-			if (hasOwn(value.stateful, key)) {
-				if (!isPositiveInteger(value.stateful[key])) return undefined;
-				runtime[key] = value.stateful[key];
-			}
-		}
-		if (hasOwn(value.stateful, "retentionDays")) {
-			if (!isPositiveNumber(value.stateful.retentionDays)) return undefined;
-			runtime.retentionDays = value.stateful.retentionDays;
-		}
-		if (hasOwn(value.stateful, "enabled")) {
-			if (typeof value.stateful.enabled !== "boolean") return undefined;
-			runtime.enabled = value.stateful.enabled;
-		}
-		settings.stateful = runtime;
-	}
-	if (hasOwn(value, "consult")) {
-		if (!isPlainObject(value.consult)) return undefined;
-		const consult: NonNullable<SubagentSettings["consult"]> = {};
-		if (hasOwn(value.consult, "resources")) {
-			if (
-				typeof value.consult.resources !== "string" ||
-				!CONSULT_RESOURCE_POLICIES.includes(value.consult.resources as ConsultResourcePolicy)
-			) {
-				return undefined;
-			}
-			consult.resources = value.consult.resources as ConsultResourcePolicy;
-		}
-		settings.consult = consult;
-	}
-	if (hasOwn(value, "cwdPolicy")) {
-		if (!isPlainObject(value.cwdPolicy)) return undefined;
-		const cwdPolicy: NonNullable<SubagentSettings["cwdPolicy"]> = {};
-		if (hasOwn(value.cwdPolicy, "consultation")) {
-			if (
-				typeof value.cwdPolicy.consultation !== "string" ||
-				!CONSULTATION_CWD_POLICIES.includes(value.cwdPolicy.consultation as ConsultationCwdPolicy)
-			) {
-				return undefined;
-			}
-			cwdPolicy.consultation = value.cwdPolicy.consultation as ConsultationCwdPolicy;
-		}
-		if (hasOwn(value.cwdPolicy, "delegation")) {
-			if (
-				typeof value.cwdPolicy.delegation !== "string" ||
-				!DELEGATION_CWD_POLICIES.includes(value.cwdPolicy.delegation as DelegationCwdPolicy)
-			) {
-				return undefined;
-			}
-			cwdPolicy.delegation = value.cwdPolicy.delegation as DelegationCwdPolicy;
-		}
-		settings.cwdPolicy = cwdPolicy;
-	}
-	return settings;
-}
+export {
+	type BlockingParallelLimitSettingsSnapshot,
+	type CompletionDeliverySettingsSnapshot,
+	type ConsultResourceSettingsSnapshot,
+	type CwdPolicyFieldSnapshot,
+	type CwdPolicySettingsSnapshot,
+	DEFAULT_CONSULT_RESOURCE_POLICY,
+	DEFAULT_CONSULTATION_CWD_POLICY,
+	DEFAULT_DELEGATION_CWD_POLICY,
+	type DelegationWorkflow,
+	type DelegationWorkflowSettingsSnapshot,
+	resolveBlockingMaxParallelTasks,
+	resolveDelegationWorkflow,
+	type StatefulLimitFieldSnapshot,
+	type StatefulLimitSettingsSnapshot,
+	type StatefulTransportSettingsSnapshot,
+	type SubagentSettingsSnapshot,
+} from "./settings/inspection.js";
+export {
+	hasOwn,
+	normalizeAgentSettings,
+	normalizeSubagentSettings,
+} from "./settings/schema.js";
 
 const SETTINGS_FILE = "pi-subagents.json";
 const LEGACY_SETTINGS_FILE = "pi-subagents-config.json";
-const DEFAULT_COMPLETION_DELIVERY: CompletionDelivery = "next-turn";
-export const DEFAULT_CONSULT_RESOURCE_POLICY: ConsultResourcePolicy = "project-context";
-export const DEFAULT_CONSULTATION_CWD_POLICY: ConsultationCwdPolicy = "anywhere";
-export const DEFAULT_DELEGATION_CWD_POLICY: DelegationCwdPolicy = "trusted-targets";
 const SETTINGS_LOCK_FS_ADAPTER = {
 	mkdir: fs.mkdir,
 	mkdirSync: fs.mkdirSync,
@@ -284,94 +149,11 @@ export function saveSubagentConfig(settings: SubagentSettings): void {
 	writeSettingsObject(settings);
 }
 
-export type DelegationWorkflow = "all" | "async-only" | "blocking-only" | "disabled";
-
-export interface DelegationWorkflowSettingsSnapshot {
-	path: string;
-	value: DelegationWorkflow;
-	source: "default" | "user settings";
-	error?: string;
-}
-
-export interface CompletionDeliverySettingsSnapshot {
-	path: string;
-	value: CompletionDelivery;
-	source: "default" | "user settings";
-	error?: string;
-}
-
-export interface StatefulTransportSettingsSnapshot {
-	path: string;
-	value: SubagentTransportKind;
-	source: "default" | "user settings";
-	error?: string;
-}
-
-export interface BlockingParallelLimitSettingsSnapshot {
-	path: string;
-	value: number;
-	source: "default" | "user settings";
-	error?: string;
-}
-
-export interface StatefulLimitFieldSnapshot {
-	value: number;
-	source: "default" | "user settings";
-}
-
-export interface StatefulLimitSettingsSnapshot {
-	path: string;
-	writePath: string;
-	values?: Record<StatefulLimitField, StatefulLimitFieldSnapshot>;
-	error?: string;
-}
-
-export interface ConsultResourceSettingsSnapshot {
-	path: string;
-	value: ConsultResourcePolicy;
-	source: "default" | "user settings";
-	error?: string;
-}
-
-export interface CwdPolicyFieldSnapshot<T> {
-	value: T;
-	source: "default" | "user settings";
-}
-
-export interface CwdPolicySettingsSnapshot {
-	path: string;
-	consultation: CwdPolicyFieldSnapshot<ConsultationCwdPolicy>;
-	delegation: CwdPolicyFieldSnapshot<DelegationCwdPolicy>;
-	error?: string;
-}
-
-export interface SubagentSettingsSnapshot {
-	path: string;
-	settings?: SubagentSettings;
-	source: "default" | "user settings";
-	error?: string;
-}
-
 export function subagentSettingsFilePath(): string {
 	return path.join(getAgentDir(), SETTINGS_FILE);
 }
 
-export function resolveDelegationWorkflow(
-	blockingEnabled: boolean,
-	statefulEnabled: boolean,
-): DelegationWorkflow {
-	if (blockingEnabled && statefulEnabled) return "all";
-	if (statefulEnabled) return "async-only";
-	if (blockingEnabled) return "blocking-only";
-	return "disabled";
-}
-
-function inspectSubagentSettingsDocument(): {
-	path: string;
-	raw?: Record<string, unknown>;
-	settings?: SubagentSettings;
-	error?: string;
-} {
+function inspectSubagentSettingsDocument(): InspectedSubagentSettingsDocument {
 	const { canonicalPath, activePath } = resolveSubagentSettingsPaths();
 	if (activePath === undefined) return { path: canonicalPath };
 	const inspected = inspectSubagentSettingsPath(activePath);
@@ -380,12 +162,7 @@ function inspectSubagentSettingsDocument(): {
 		: inspected;
 }
 
-function inspectSubagentSettingsPath(configPath: string): {
-	path: string;
-	raw?: Record<string, unknown>;
-	settings?: SubagentSettings;
-	error?: string;
-} {
+function inspectSubagentSettingsPath(configPath: string): InspectedSubagentSettingsDocument {
 	const fileName = path.basename(configPath);
 	let contents: string;
 	try {
@@ -411,163 +188,38 @@ function inspectSubagentSettingsPath(configPath: string): {
 }
 
 export function inspectSubagentSettings(): SubagentSettingsSnapshot {
-	const inspected = inspectSubagentSettingsDocument();
-	return {
-		path: inspected.path,
-		settings: inspected.settings,
-		source: inspected.settings ? "user settings" : "default",
-		...(inspected.error ? { error: inspected.error } : {}),
-	};
+	return buildSubagentSettingsSnapshot(inspectSubagentSettingsDocument());
 }
 
 export function inspectConsultResourceSettings(): ConsultResourceSettingsSnapshot {
-	const inspected = inspectSubagentSettingsDocument();
-	if (!inspected.raw || !inspected.settings) {
-		return {
-			path: inspected.path,
-			value: DEFAULT_CONSULT_RESOURCE_POLICY,
-			source: "default",
-			...(inspected.error ? { error: inspected.error } : {}),
-		};
-	}
-	const explicit =
-		isPlainObject(inspected.raw.consult) && hasOwn(inspected.raw.consult, "resources");
-	return {
-		path: inspected.path,
-		value: inspected.settings.consult?.resources ?? DEFAULT_CONSULT_RESOURCE_POLICY,
-		source: explicit ? "user settings" : "default",
-	};
+	return buildConsultResourceSettingsSnapshot(inspectSubagentSettingsDocument());
 }
 
 export function inspectCwdPolicySettings(): CwdPolicySettingsSnapshot {
-	const inspected = inspectSubagentSettingsDocument();
-	if (!inspected.raw || !inspected.settings) {
-		return {
-			path: inspected.path,
-			consultation: { value: DEFAULT_CONSULTATION_CWD_POLICY, source: "default" },
-			delegation: { value: DEFAULT_DELEGATION_CWD_POLICY, source: "default" },
-			...(inspected.error ? { error: inspected.error } : {}),
-		};
-	}
-	const rawPolicy = isPlainObject(inspected.raw.cwdPolicy) ? inspected.raw.cwdPolicy : undefined;
-	return {
-		path: inspected.path,
-		consultation: {
-			value: inspected.settings.cwdPolicy?.consultation ?? DEFAULT_CONSULTATION_CWD_POLICY,
-			source: rawPolicy && hasOwn(rawPolicy, "consultation") ? "user settings" : "default",
-		},
-		delegation: {
-			value: inspected.settings.cwdPolicy?.delegation ?? DEFAULT_DELEGATION_CWD_POLICY,
-			source: rawPolicy && hasOwn(rawPolicy, "delegation") ? "user settings" : "default",
-		},
-	};
+	return buildCwdPolicySettingsSnapshot(inspectSubagentSettingsDocument());
 }
 
 export function inspectDelegationWorkflowSettings(): DelegationWorkflowSettingsSnapshot {
-	const inspected = inspectSubagentSettingsDocument();
-	if (!inspected.raw || !inspected.settings) {
-		return {
-			path: inspected.path,
-			value: "all",
-			source: "default",
-			...(inspected.error ? { error: inspected.error } : {}),
-		};
-	}
-	const explicit =
-		(isPlainObject(inspected.raw.blocking) && hasOwn(inspected.raw.blocking, "enabled")) ||
-		(isPlainObject(inspected.raw.stateful) && hasOwn(inspected.raw.stateful, "enabled"));
-	return {
-		path: inspected.path,
-		value: resolveDelegationWorkflow(
-			inspected.settings.blocking?.enabled !== false,
-			inspected.settings.stateful?.enabled !== false,
-		),
-		source: explicit ? "user settings" : "default",
-	};
+	return buildDelegationWorkflowSettingsSnapshot(inspectSubagentSettingsDocument());
 }
 
 export function inspectCompletionDeliverySettings(): CompletionDeliverySettingsSnapshot {
-	const inspected = inspectSubagentSettingsDocument();
-	if (!inspected.raw || !inspected.settings) {
-		return {
-			path: inspected.path,
-			value: DEFAULT_COMPLETION_DELIVERY,
-			source: "default",
-			...(inspected.error ? { error: inspected.error } : {}),
-		};
-	}
-	const explicit =
-		isPlainObject(inspected.raw.stateful) && hasOwn(inspected.raw.stateful, "completionDelivery");
-	return {
-		path: inspected.path,
-		value: inspected.settings.stateful?.completionDelivery ?? DEFAULT_COMPLETION_DELIVERY,
-		source: explicit ? "user settings" : "default",
-	};
+	return buildCompletionDeliverySettingsSnapshot(inspectSubagentSettingsDocument());
 }
 
 export function inspectStatefulTransportSettings(): StatefulTransportSettingsSnapshot {
-	const inspected = inspectSubagentSettingsDocument();
-	if (!inspected.raw || !inspected.settings) {
-		return {
-			path: inspected.path,
-			value: "subprocess",
-			source: "default",
-			...(inspected.error ? { error: inspected.error } : {}),
-		};
-	}
-	const explicit =
-		isPlainObject(inspected.raw.stateful) && hasOwn(inspected.raw.stateful, "transport");
-	return {
-		path: inspected.path,
-		value: inspected.settings.stateful?.transport ?? "subprocess",
-		source: explicit ? "user settings" : "default",
-	};
-}
-
-export function resolveBlockingMaxParallelTasks(settings?: SubagentSettings): number {
-	return settings?.blocking?.maxParallelTasks ?? DEFAULT_MAX_PARALLEL_TASKS;
+	return buildStatefulTransportSettingsSnapshot(inspectSubagentSettingsDocument());
 }
 
 export function inspectBlockingParallelLimitSettings(): BlockingParallelLimitSettingsSnapshot {
-	const inspected = inspectSubagentSettingsDocument();
-	if (!inspected.raw || !inspected.settings) {
-		return {
-			path: inspected.path,
-			value: DEFAULT_MAX_PARALLEL_TASKS,
-			source: "default",
-			...(inspected.error ? { error: inspected.error } : {}),
-		};
-	}
-	const explicit =
-		isPlainObject(inspected.raw.blocking) && hasOwn(inspected.raw.blocking, "maxParallelTasks");
-	return {
-		path: inspected.path,
-		value: resolveBlockingMaxParallelTasks(inspected.settings),
-		source: explicit ? "user settings" : "default",
-	};
+	return buildBlockingParallelLimitSettingsSnapshot(inspectSubagentSettingsDocument());
 }
 
 export function inspectStatefulLimitSettings(): StatefulLimitSettingsSnapshot {
-	const inspected = inspectSubagentSettingsDocument();
-	const writePath = subagentSettingsFilePath();
-	if (inspected.error) {
-		return { path: inspected.path, writePath, error: inspected.error };
-	}
-	const resolved = resolveStatefulLimits(inspected.settings?.stateful);
-	const rawStateful = isPlainObject(inspected.raw?.stateful) ? inspected.raw.stateful : undefined;
-	return {
-		path: inspected.path,
-		writePath,
-		values: Object.fromEntries(
-			STATEFUL_LIMIT_FIELDS.map((field) => [
-				field,
-				{
-					value: resolved[field],
-					source: rawStateful && hasOwn(rawStateful, field) ? "user settings" : "default",
-				},
-			]),
-		) as unknown as Record<StatefulLimitField, StatefulLimitFieldSnapshot>,
-	};
+	return buildStatefulLimitSettingsSnapshot(
+		inspectSubagentSettingsDocument(),
+		subagentSettingsFilePath(),
+	);
 }
 
 export function updateDelegationWorkflowSetting(

package/src/spawn-idempotency.ts

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-import type { AgentScope, SubagentThinkingLevel } from "./agents.js";
+import type { AgentScope, SubagentThinkingLevel } from "./agents/types.js";
 import type { DelegationContract } from "./delegation-contract.js";
 import type { SubagentResultFormat } from "./result-contract.js";
 

package/src/stateful-agent-view.ts

@@ -0,0 +1,87 @@
+import { MAX_TOOL_MESSAGE_BYTES, truncateUtf8 } from "./limits.js";
+import type { ManagedAgent } from "./registry.js";
+
+export function formatStatefulAgentLine(agent: ManagedAgent, now = Date.now()): string {
+	const elapsedSeconds = Math.max(0, Math.floor((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}`;
+}
+
+export function summarizeStatefulAgent(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,
+	};
+}
+
+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()
+	);
+}

package/src/stateful-config.ts

@@ -1,4 +1,4 @@
-import type { CompletionDelivery, SubagentTransportKind } from "./agents.js";
+import type { CompletionDelivery, SubagentTransportKind } from "./agents/types.js";
 
 export function resolveStatefulTransportKind(
 	value: SubagentTransportKind | undefined,

package/src/stateful-guidance.ts

@@ -1,4 +1,4 @@
-import type { CompletionDelivery } from "./agents.js";
+import type { CompletionDelivery } from "./agents/types.js";
 
 export function createSpawnPromptGuidelines(
 	completionDelivery: CompletionDelivery,
@@ -31,6 +31,6 @@ export function createSpawnPromptGuidelines(
 		"Add another subagent_spawn only for truly independent work with safe workspace concurrency.",
 		noLocalWorkGuidance,
 		'Consume and synthesize available subagent_spawn completion messages; use subagent_manage with action "interrupt" or "close" for agents that are no longer needed.',
-		'Completion from subagent_spawn is delivered automatically. Do not poll with subagent_manage action "list" or subagent_mailbox action "read", repeatedly check progress, or duplicate the delegated work.',
+		'Completion from subagent_spawn is delivered automatically. Do not poll with subagent_inspect or subagent_mailbox action "read", repeatedly check progress, or duplicate the delegated work.',
 	];
 }

package/src/stateful-limits.ts

@@ -1,4 +1,4 @@
-import type { SubagentRuntimeSettings } from "./agents.js";
+import type { SubagentRuntimeSettings } from "./agents/types.js";
 
 export const STATEFUL_LIMIT_FIELDS = [
 	"maxAgents",

package/src/stateful-prompt.ts

@@ -1,7 +1,7 @@
-import type { AgentConfig } from "./agents.js";
+import type { AgentConfig } from "./agents/types.js";
 import { redactPrivateText } from "./context.js";
 import { appendDelegationContract } from "./delegation-contract.js";
-import { resolveDefaultSubagentTimeoutMs } from "./execution.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";