@narumitw/pi-subagents 0.53.0 → 1.0.0

package/src/panel-execution.ts

@@ -1,6 +1,6 @@
 import type { AgentToolResult, AgentToolUpdateCallback } from "@earendil-works/pi-agent-core";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import type { AgentConfig, AgentScope, SubagentThinkingLevel } from "./agents.js";
+import type { AgentConfig, AgentScope, SubagentThinkingLevel } from "./agents/types.js";
 import { panelReviewStatus, panelSynthesisStatus, startSubagentStatus } from "./blocking-status.js";
 import { issueCapabilityGrant, revokeCapabilityGrant } from "./capability-grant.js";
 import type { ResolvedSubagentTarget } from "./cwd-policy.js";

package/src/panel-planning.ts

@@ -1,4 +1,4 @@
-import type { AgentConfig } from "./agents.js";
+import type { AgentConfig } from "./agents/types.js";
 import { DEFAULT_MAX_CONTEXT_BYTES, truncateUtf8 } from "./limits.js";
 import { type WorkItemDefinition, WorkItemLedger } from "./work-item-ledger.js";
 

package/src/params.ts

@@ -1,11 +1,12 @@
 import { StringEnum } from "@earendil-works/pi-ai";
 import { type Static, Type } from "typebox";
-import { THINKING_LEVELS } from "./agents.js";
+import { THINKING_LEVELS } from "./agents/types.js";
 import { DelegationContractSchema } from "./delegation-contract.js";
 import { MAX_CONFIGURABLE_PARALLEL_TASKS, MAX_SUBAGENT_TIMEOUT_MS } from "./limits.js";
 import { PANEL_PRESETS } from "./panel-planning.js";
 import { SUBAGENT_RESULT_FORMATS } from "./result-contract.js";
 import { MAX_SUBAGENT_TOOL_CALLS, MAX_SUBAGENT_TURNS } from "./turn-budget.js";
+import { VerifiedExecutionContractSchema } from "./verified-execution-contract.js";
 
 const TimeoutMs = Type.Number({
 	description:
@@ -221,6 +222,7 @@ export const SubagentParams = Type.Object({
 		Type.Object(
 			{
 				id: Type.Optional(Type.String({ minLength: 1, maxLength: 256 })),
+				verifiedExecution: Type.Optional(VerifiedExecutionContractSchema),
 				honorAdmission: Type.Optional(
 					Type.Boolean({
 						description:

package/src/persistence.ts

@@ -3,7 +3,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { getAgentDir, withFileMutationQueue } from "@earendil-works/pi-coding-agent";
 import { projectAgentRecords } from "./agent-projection.js";
-import { isThinkingLevel } from "./agents.js";
+import { isThinkingLevel } from "./agents/types.js";
 import { isCapabilityGrant, revokeCapabilityGrant } from "./capability-grant.js";
 import { redactPrivateText } from "./context.js";
 import { normalizeDelegationContract } from "./delegation-contract.js";
@@ -16,12 +16,13 @@ import { resolveStatefulLimits } from "./stateful-limits.js";
 import { copyTurnTerminationReport, type TurnTerminationReport } from "./timeout-checkpoint.js";
 import { MAX_SUBAGENT_TOOL_CALLS, MAX_SUBAGENT_TURNS } from "./turn-budget.js";
 
-const STATE_VERSION = 2;
+const STATE_VERSION = 3;
+const MAX_STORED_COMPLETIONS_PER_AGENT = 20;
 const DEFAULT_STATEFUL_LIMITS = resolveStatefulLimits();
-const MAX_STATE_BYTES = 1024 * 1024;
+const MAX_STATE_BYTES = 5 * 1024 * 1024;
 
 interface StoredState {
-	version: 2;
+	version: 3;
 	updatedAt: number;
 	agents: ManagedAgent[];
 }
@@ -86,8 +87,19 @@ export class AgentPersistence {
 		const state: StoredState = { version: STATE_VERSION, updatedAt: Date.now(), agents: records };
 		let content = `${JSON.stringify(state, null, "\t")}\n`;
 		while (Buffer.byteLength(content, "utf8") > MAX_STATE_BYTES && state.agents.length > 0) {
-			const oldestRootId = state.agents[0].rootId;
-			state.agents = state.agents.filter((agent) => agent.rootId !== oldestRootId);
+			const rootsWithPendingCompletions = new Set(
+				state.agents
+					.filter((agent) => (agent.pendingCompletions?.length ?? 0) > 0)
+					.map((agent) => agent.rootId),
+			);
+			const droppableRoot = state.agents.find(
+				(agent) => !rootsWithPendingCompletions.has(agent.rootId),
+			)?.rootId;
+			if (droppableRoot) {
+				state.agents = state.agents.filter((agent) => agent.rootId !== droppableRoot);
+			} else if (!trimOldestHistory(state.agents) && !clearOldestContext(state.agents)) {
+				throw new Error("Subagent state exceeds its durable completion storage limit");
+			}
 			content = `${JSON.stringify(state, null, "\t")}\n`;
 		}
 		await fs.promises.mkdir(path.dirname(this.filePath), { recursive: true });
@@ -113,6 +125,27 @@ export class AgentPersistence {
 	}
 }
 
+function trimOldestHistory(agents: ManagedAgent[]): boolean {
+	const candidate = agents
+		.filter((agent) => agent.history.length > 0)
+		.sort(
+			(left, right) =>
+				(left.history[0]?.completedAt ?? Number.POSITIVE_INFINITY) -
+				(right.history[0]?.completedAt ?? Number.POSITIVE_INFINITY),
+		)[0];
+	if (!candidate) return false;
+	candidate.history.shift();
+	return true;
+}
+
+function clearOldestContext(agents: ManagedAgent[]): boolean {
+	const candidate = agents.find((agent) => agent.context !== undefined);
+	if (!candidate) return false;
+	candidate.context = undefined;
+	candidate.contextTruncated = true;
+	return true;
+}
+
 function sanitizeAgent(agent: ManagedAgent): ManagedAgent {
 	return {
 		...agent,
@@ -126,6 +159,17 @@ function sanitizeAgent(agent: ManagedAgent): ManagedAgent {
 		})),
 		state: agent.state === "running" || agent.state === "starting" ? "interrupted" : agent.state,
 		currentTask: undefined,
+		currentRunId: undefined,
+		currentTurnGeneration: undefined,
+		turnGeneration: agent.turnGeneration ?? 0,
+		pendingCompletions: (agent.pendingCompletions ?? [])
+			.slice(-MAX_STORED_COMPLETIONS_PER_AGENT)
+			.map((completion) => ({
+				...completion,
+				task: redactPrivateText(completion.task),
+				output: redactPrivateText(completion.output),
+				error: completion.error ? redactPrivateText(completion.error) : undefined,
+			})),
 		currentTimeoutMs: undefined,
 		currentIdleTimeoutMs: undefined,
 		currentMaxTurns: undefined,
@@ -184,7 +228,10 @@ function sanitizeTermination(report: TurnTerminationReport): TurnTerminationRepo
 function isStoredState(value: unknown): value is StoredState {
 	if (!value || typeof value !== "object") return false;
 	const state = value as { version?: unknown; agents?: unknown };
-	if ((state.version !== 1 && state.version !== STATE_VERSION) || !Array.isArray(state.agents)) {
+	if (
+		(state.version !== 1 && state.version !== 2 && state.version !== STATE_VERSION) ||
+		!Array.isArray(state.agents)
+	) {
 		return false;
 	}
 	return state.agents.every((agent) => {
@@ -208,6 +255,9 @@ function isStoredState(value: unknown): value is StoredState {
 			(record.termination === undefined || isTerminationReport(record.termination)) &&
 			(record.contextTurns === undefined || isNonNegativeInteger(record.contextTurns)) &&
 			(record.contextBytes === undefined || isNonNegativeInteger(record.contextBytes)) &&
+			(record.turnGeneration === undefined || isNonNegativeInteger(record.turnGeneration)) &&
+			(record.pendingCompletions === undefined ||
+				isCompletionOutbox(record.pendingCompletions, record.turnGeneration ?? 0)) &&
 			(record.spawnIdempotencyKey === undefined ||
 				(typeof record.spawnIdempotencyKey === "string" &&
 					record.spawnIdempotencyKey.length > 0 &&
@@ -356,10 +406,59 @@ function isTargetPolicyAudit(value: unknown): boolean {
 	);
 }
 
+function isCompletionOutbox(value: unknown, turnGeneration: number): boolean {
+	if (!Array.isArray(value) || value.length > MAX_STORED_COMPLETIONS_PER_AGENT) return false;
+	const ids = new Set<string>();
+	let previousGeneration = 0;
+	let previousCreatedAt = Number.NEGATIVE_INFINITY;
+	for (const completion of value) {
+		if (!isPersistedCompletion(completion, turnGeneration)) return false;
+		if (ids.has(completion.completionId)) return false;
+		if (completion.generation <= previousGeneration || completion.createdAt <= previousCreatedAt) {
+			return false;
+		}
+		ids.add(completion.completionId);
+		previousGeneration = completion.generation;
+		previousCreatedAt = completion.createdAt;
+	}
+	return true;
+}
+
+function isPersistedCompletion(
+	value: unknown,
+	turnGeneration: number,
+): value is import("./registry.js").PersistedAgentCompletion {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+	const completion = value as Record<string, unknown>;
+	return (
+		typeof completion.completionId === "string" &&
+		completion.completionId.length > 0 &&
+		completion.completionId.length <= 256 &&
+		typeof completion.runId === "string" &&
+		completion.runId.length > 0 &&
+		completion.runId.length <= 256 &&
+		typeof completion.generation === "number" &&
+		Number.isSafeInteger(completion.generation) &&
+		completion.generation >= 1 &&
+		completion.generation <= turnGeneration &&
+		typeof completion.task === "string" &&
+		typeof completion.output === "string" &&
+		(completion.error === undefined || typeof completion.error === "string") &&
+		typeof completion.createdAt === "number" &&
+		Number.isFinite(completion.createdAt)
+	);
+}
+
 function isAgentTurn(value: unknown): boolean {
 	if (!value || typeof value !== "object") return false;
 	const turn = value as Record<string, unknown>;
 	return (
+		(turn.runId === undefined ||
+			(typeof turn.runId === "string" && turn.runId.length > 0 && turn.runId.length <= 256)) &&
+		(turn.generation === undefined ||
+			(typeof turn.generation === "number" &&
+				Number.isSafeInteger(turn.generation) &&
+				turn.generation >= 1)) &&
 		typeof turn.task === "string" &&
 		typeof turn.output === "string" &&
 		typeof turn.startedAt === "number" &&

package/src/registry-types.ts

@@ -1,4 +1,4 @@
-import type { SubagentThinkingLevel } from "./agents.js";
+import type { SubagentThinkingLevel } from "./agents/types.js";
 import type { CapabilityGrant } from "./capability-grant.js";
 import type { TargetPolicyAudit } from "./cwd-policy.js";
 import type { DelegationContract } from "./delegation-contract.js";
@@ -23,6 +23,8 @@ export type AgentLifecycleState =
 	| "closed";
 
 export interface AgentTurn {
+	runId?: string;
+	generation?: number;
 	task: string;
 	output: string;
 	startedAt: number;
@@ -32,6 +34,16 @@ export interface AgentTurn {
 	termination?: TurnTerminationReport;
 }
 
+export interface PersistedAgentCompletion {
+	completionId: string;
+	runId: string;
+	generation: number;
+	task: string;
+	output: string;
+	error?: string;
+	createdAt: number;
+}
+
 export interface AgentMailboxMessage {
 	id: string;
 	senderId: string;
@@ -64,6 +76,10 @@ export interface ManagedAgent {
 	maxToolCalls?: number;
 	currentMaxToolCalls?: number;
 	currentTask?: string;
+	turnGeneration?: number;
+	currentRunId?: string;
+	currentTurnGeneration?: number;
+	pendingCompletions?: PersistedAgentCompletion[];
 	history: AgentTurn[];
 	error?: string;
 	context?: string;
@@ -98,6 +114,8 @@ export interface AgentRunInspectionSummary {
 	updatedAt: number;
 	historyCount: number;
 	unreadMessages: number;
+	turnGeneration: number;
+	pendingCompletionCount: number;
 }
 
 export interface AgentRunInspectionDetail extends AgentRunInspectionSummary {
@@ -112,6 +130,8 @@ export interface AgentRunInspectionDetail extends AgentRunInspectionSummary {
 	maxToolCalls?: number;
 	currentMaxToolCalls?: number;
 	currentTask?: string;
+	currentRunId?: string;
+	currentTurnGeneration?: number;
 	error?: string;
 	workspaceMode?: "worktree";
 	contextTurns?: number;
@@ -151,11 +171,8 @@ export interface TurnOutcome {
 	telemetry?: TransportTelemetry;
 }
 
-export interface AgentTurnCompletion {
+export interface AgentTurnCompletion extends PersistedAgentCompletion {
 	agent: ManagedAgent;
-	task: string;
-	output: string;
-	error?: string;
 }
 
 export interface AgentRegistryOptions {