@narumitw/pi-subagents 0.49.3 → 0.52.0

package/src/render.ts

@@ -8,6 +8,7 @@ import {
 } from "@earendil-works/pi-coding-agent";
 import { Container, Markdown, Spacer, Text } from "@earendil-works/pi-tui";
 import type { AgentScope, SubagentThinkingLevel } from "./agents.js";
+import { renderPanelCall, renderPanelResult } from "./panel-render.js";
 import { hasUsableAggregator, type SubagentParams } from "./params.js";
 import { expansionHint, formatToolActivity, safeBlock, safeLine } from "./render-common.js";
 import {
@@ -137,6 +138,12 @@ function sanitizeSingleResultForRender(result: SingleResult): SingleResult {
 }
 
 function renderResultStatus(result: SingleResult, isPartial: boolean): string {
+	if (result.outcome && !["completed", "partial"].includes(result.outcome.status)) {
+		return result.outcome.status
+			.split("-")
+			.map((part) => `${part.slice(0, 1).toUpperCase()}${part.slice(1)}`)
+			.join(" ");
+	}
 	if (isResultError(result)) {
 		return result.stopReason === "aborted" || result.aborted ? "Cancelled" : "Failed";
 	}
@@ -153,6 +160,31 @@ function coloredResultStatus(theme: Theme, result: SingleResult, isPartial: bool
 	return coloredStatus(theme, renderResultStatus(result, isPartial));
 }
 
+function formatResultIntelligence(result: SingleResult): string {
+	const structured =
+		result.structuredResult?.version === "pi-subagents:result:v2"
+			? result.structuredResult
+			: undefined;
+	return [
+		result.contract ? `contract: ${result.contract.level} · ${result.contract.taskId}` : undefined,
+		result.outcome
+			? `outcome: ${result.outcome.status}${result.outcome.reasonCode ? ` · ${result.outcome.reasonCode}` : ""}`
+			: undefined,
+		structured
+			? `evidence: ${structured.claims.length} claims · ${structured.artifacts.length} artifacts · ${structured.verification.length} verification items · ${structured.limitations.length} limitations`
+			: undefined,
+		result.resultContractInvalid ? "contract warning: invalid structured result" : undefined,
+		result.executionPlan
+			? `plan: ${result.executionPlan.id.slice(0, 12)} · generation ${result.executionPlan.taskGeneration} · admission ${result.executionPlan.admission.recommendation}`
+			: undefined,
+		result.capabilityGrant
+			? `grant: ${result.capabilityGrant.state} · expires ${result.capabilityGrant.expiresAt}`
+			: undefined,
+	]
+		.filter((line): line is string => Boolean(line))
+		.join("\n");
+}
+
 function formatResultPolicy(result: SingleResult): string {
 	if (!result.policy) return "";
 	return [
@@ -164,11 +196,34 @@ function formatResultPolicy(result: SingleResult): string {
 
 export function renderSubagentCall(args: SubagentParams, theme: Theme) {
 	const scope: AgentScope = args.agentScope ?? "user";
+	const limits = [
+		typeof args.timeoutMs === "number" ? `timeout:${args.timeoutMs}ms` : undefined,
+		typeof args.totalTimeoutMs === "number" ? `total:${args.totalTimeoutMs}ms` : undefined,
+		typeof args.idleTimeoutMs === "number" ? `idle:${args.idleTimeoutMs}ms` : undefined,
+		typeof args.maxTurns === "number" ? `turns:${args.maxTurns}` : undefined,
+		typeof args.maxToolCalls === "number" ? `tools:${args.maxToolCalls}` : undefined,
+	].filter((value): value is string => Boolean(value));
+	const limitText = limits.length > 0 ? ` · ${limits.join(" · ")}` : "";
+	const panelCall = renderPanelCall(args, theme);
+	if (panelCall) return panelCall;
+	if (args.workflow && args.workflow.tasks.length > 0) {
+		let text =
+			theme.fg("toolTitle", theme.bold("subagent ")) +
+			theme.fg("accent", `workflow (${args.workflow.tasks.length} tasks)`) +
+			theme.fg("muted", ` [${scope}]${limitText}`);
+		for (const task of args.workflow.tasks.slice(0, 3)) {
+			text += `\n  ${theme.fg("muted", `${task.id}:`)} ${theme.fg("accent", previewAgent(task.agent))}${theme.fg("dim", ` ${previewTask(task.task)}`)}`;
+		}
+		if (args.workflow.tasks.length > 3) {
+			text += `\n  ${theme.fg("muted", `... +${args.workflow.tasks.length - 3} more`)}`;
+		}
+		return new Text(text, 0, 0);
+	}
 	if (args.chain && args.chain.length > 0) {
 		let text =
 			theme.fg("toolTitle", theme.bold("subagent ")) +
 			theme.fg("accent", `chain (${args.chain.length} steps)`) +
-			theme.fg("muted", ` [${scope}]`);
+			theme.fg("muted", ` [${scope}]${limitText}`);
 		for (let i = 0; i < Math.min(args.chain.length, 3); i++) {
 			const step = args.chain[i] as { agent?: unknown; task?: unknown } | undefined;
 			// Clean up {previous} placeholder for display
@@ -189,7 +244,7 @@ export function renderSubagentCall(args: SubagentParams, theme: Theme) {
 		let text =
 			theme.fg("toolTitle", theme.bold("subagent ")) +
 			theme.fg("accent", `parallel (${args.tasks.length} tasks)`) +
-			theme.fg("muted", ` [${scope}]`);
+			theme.fg("muted", ` [${scope}]${limitText}`);
 		for (const task of args.tasks.slice(0, 3)) {
 			const item = task as { agent?: unknown; task?: unknown } | undefined;
 			text += `\n  ${theme.fg("accent", previewAgent(item?.agent))}${theme.fg("dim", ` ${previewTask(item?.task)}`)}`;
@@ -210,7 +265,7 @@ export function renderSubagentCall(args: SubagentParams, theme: Theme) {
 	let text =
 		theme.fg("toolTitle", theme.bold("subagent ")) +
 		theme.fg("accent", agentName) +
-		theme.fg("muted", ` [${scope}]`);
+		theme.fg("muted", ` [${scope}]${limitText}`);
 	text += `\n  ${theme.fg("dim", preview)}`;
 	return new Text(text, 0, 0);
 }
@@ -221,6 +276,10 @@ export function renderSubagentResult(
 	theme: Theme,
 ) {
 	const rawDetails = result.details as SubagentDetails | undefined;
+	if (rawDetails?.mode === "panel") {
+		const panelResult = renderPanelResult(rawDetails, expanded, isPartial, theme);
+		if (panelResult) return panelResult;
+	}
 	if (!rawDetails || rawDetails.results.length === 0) {
 		const text = result.content[0];
 		return new Text(
@@ -277,6 +336,12 @@ export function renderSubagentResult(
 			container.addChild(new Spacer(1));
 			container.addChild(new Text(theme.fg("muted", "─── Task ───"), 0, 0));
 			container.addChild(new Text(theme.fg("dim", r.task), 0, 0));
+			const intelligence = formatResultIntelligence(r);
+			if (intelligence) {
+				container.addChild(new Spacer(1));
+				container.addChild(new Text(theme.fg("muted", "─── Delegation ───"), 0, 0));
+				container.addChild(new Text(theme.fg("dim", intelligence), 0, 0));
+			}
 			const policy = formatResultPolicy(r);
 			if (policy) {
 				container.addChild(new Spacer(1));
@@ -467,7 +532,8 @@ export function renderSubagentResult(
 		return new Text(text, 0, 0);
 	}
 
-	if (details.mode === "parallel") {
+	if (details.mode === "parallel" || details.mode === "workflow") {
+		const modeLabel = details.mode === "workflow" ? "workflow" : "parallel";
 		const resultIsRunning = (result: SingleResult) =>
 			result.exitCode === -1 && !isResultError(result);
 		const running = details.results.filter(resultIsRunning).length;
@@ -507,7 +573,7 @@ export function renderSubagentResult(
 			const container = new Container();
 			container.addChild(
 				new Text(
-					`${icon} ${theme.fg("toolTitle", theme.bold("parallel "))}${theme.fg("accent", status)} · ${coloredStatus(theme, overallStatus)}`,
+					`${icon} ${theme.fg("toolTitle", theme.bold(`${modeLabel} `))}${theme.fg("accent", status)} · ${coloredStatus(theme, overallStatus)}`,
 					0,
 					0,
 				),
@@ -623,7 +689,7 @@ export function renderSubagentResult(
 		}
 
 		// Collapsed view (or still running)
-		let text = `${icon} ${theme.fg("toolTitle", theme.bold("parallel "))}${theme.fg("accent", status)} · ${coloredStatus(theme, overallStatus)}`;
+		let text = `${icon} ${theme.fg("toolTitle", theme.bold(`${modeLabel} `))}${theme.fg("accent", status)} · ${coloredStatus(theme, overallStatus)}`;
 		for (const r of details.results) {
 			const rFailed = isResultError(r);
 			const rRunning = resultIsRunning(r);

package/src/result-contract.ts

@@ -0,0 +1,416 @@
+import { redactPrivateText } from "./context.js";
+import { DEFAULT_MAX_OUTPUT_BYTES, truncateUtf8 } from "./limits.js";
+
+export const SUBAGENT_RESULT_FORMATS = ["text", "structured-v1", "structured-v2"] as const;
+export type SubagentResultFormat = (typeof SUBAGENT_RESULT_FORMATS)[number];
+
+export interface StructuredSubagentResult {
+	version: "pi-subagents:result:v1";
+	summary: string;
+	evidence: string[];
+	changes: string[];
+	verification: string[];
+	risks: string[];
+}
+
+export const SUBAGENT_OUTCOME_STATUSES = [
+	"completed",
+	"partial",
+	"blocked",
+	"needs-input",
+	"abstained",
+	"failed",
+	"interrupted",
+	"stale",
+	"contract-invalid",
+] as const;
+export type SubagentOutcomeStatus = (typeof SUBAGENT_OUTCOME_STATUSES)[number];
+
+export const SUBAGENT_CLAIM_CLASSIFICATIONS = ["observed", "inferred", "unverified"] as const;
+export type SubagentClaimClassification = (typeof SUBAGENT_CLAIM_CLASSIFICATIONS)[number];
+
+export interface EvidenceBackedClaim {
+	claim: string;
+	classification: SubagentClaimClassification;
+	evidence: string[];
+}
+
+export interface SubagentArtifactReference {
+	id: string;
+	kind: string;
+	version?: string;
+	location?: string;
+	digest?: string;
+}
+
+export interface SubagentChangeReference {
+	path: string;
+	summary: string;
+}
+
+export interface SubagentVerificationReference {
+	status: "passed" | "failed" | "not-run";
+	summary: string;
+	command?: string;
+	evidence?: string[];
+}
+
+export interface SubagentResultProvenance {
+	taskId?: string;
+	taskGeneration?: number;
+	executionPlanId?: string;
+	cancellationLineage?: string[];
+	inputArtifacts?: string[];
+	repositoryGeneration?: string;
+}
+
+export interface StructuredSubagentResultV2 {
+	version: "pi-subagents:result:v2";
+	status: SubagentOutcomeStatus;
+	reasonCode?: string;
+	summary: string;
+	claims: EvidenceBackedClaim[];
+	artifacts: SubagentArtifactReference[];
+	changes: SubagentChangeReference[];
+	verification: SubagentVerificationReference[];
+	limitations: string[];
+	unresolvedDependencies: string[];
+	provenance?: SubagentResultProvenance;
+}
+
+export type AnyStructuredSubagentResult = StructuredSubagentResult | StructuredSubagentResultV2;
+
+export interface ResultContractRuntimeMetadata {
+	truncated?: boolean;
+	usage?: {
+		input: number;
+		output: number;
+		cost: number;
+		turns: number;
+	};
+}
+
+export interface ResultContractEnvelope<T extends AnyStructuredSubagentResult> {
+	result: T;
+	truncated?: boolean;
+	usage?: ResultContractRuntimeMetadata["usage"];
+}
+
+const MAX_FIELD_BYTES = 8 * 1024;
+const MAX_ITEMS = 50;
+const MAX_REASON_CODE_BYTES = 256;
+const MAX_ARTIFACT_IDENTIFIER_BYTES = 256;
+
+export function structuredResultInstruction(format: SubagentResultFormat | undefined): string {
+	if (format === "structured-v1") {
+		return [
+			"Return the final answer as one JSON object and no surrounding prose.",
+			'Use exactly version "pi-subagents:result:v1" and fields summary, evidence, changes, verification, and risks.',
+			"summary must be a string and the other fields must be arrays of strings.",
+		].join(" ");
+	}
+	if (format === "structured-v2") {
+		return [
+			"Return the final answer as one JSON object and no surrounding prose.",
+			'Use exactly version "pi-subagents:result:v2".',
+			"Required fields are status, summary, claims, artifacts, changes, verification, limitations, and unresolvedDependencies.",
+			`status must be one of ${SUBAGENT_OUTCOME_STATUSES.join(", ")}.`,
+			"Each claim must include claim, classification (observed, inferred, or unverified), and an evidence string array.",
+			"Each artifact must include id and kind; each change must include path and summary; each verification item must include status (passed, failed, or not-run) and summary.",
+			"Use optional reasonCode for non-completed outcomes and optional provenance for taskId, inputArtifacts, and repositoryGeneration; executor-owned generation and plan identity are stamped after parsing.",
+		].join(" ");
+	}
+	return "";
+}
+
+export function appendResultInstruction(
+	prompt: string,
+	format: SubagentResultFormat | undefined,
+	maxBytes = DEFAULT_MAX_OUTPUT_BYTES,
+): string {
+	const instruction = structuredResultInstruction(format);
+	if (!instruction) return prompt;
+	const suffix = `\n\nResult contract:\n${instruction}`;
+	const suffixBytes = Buffer.byteLength(suffix, "utf8");
+	const boundedPrompt = truncateUtf8(prompt, Math.max(0, maxBytes - suffixBytes)).text;
+	return `${boundedPrompt}${suffix}`;
+}
+
+export function parseStructuredSubagentResult(text: string): StructuredSubagentResult | undefined {
+	const value = parseJsonObject(text);
+	if (
+		value?.version !== "pi-subagents:result:v1" ||
+		!hasOnlyKeys(value, ["version", "summary", "evidence", "changes", "verification", "risks"]) ||
+		typeof value.summary !== "string"
+	) {
+		return undefined;
+	}
+	const evidence = stringArray(value.evidence);
+	const changes = stringArray(value.changes);
+	const verification = stringArray(value.verification);
+	const risks = stringArray(value.risks);
+	if (!evidence || !changes || !verification || !risks) return undefined;
+	return {
+		version: "pi-subagents:result:v1",
+		summary: bounded(value.summary),
+		evidence,
+		changes,
+		verification,
+		risks,
+	};
+}
+
+export function parseStructuredSubagentResultV2(
+	text: string,
+): StructuredSubagentResultV2 | undefined {
+	const value = parseJsonObject(text);
+	if (
+		value?.version !== "pi-subagents:result:v2" ||
+		!hasOnlyKeys(value, [
+			"version",
+			"status",
+			"reasonCode",
+			"summary",
+			"claims",
+			"artifacts",
+			"changes",
+			"verification",
+			"limitations",
+			"unresolvedDependencies",
+			"provenance",
+		]) ||
+		typeof value.status !== "string" ||
+		!SUBAGENT_OUTCOME_STATUSES.includes(value.status as SubagentOutcomeStatus) ||
+		typeof value.summary !== "string"
+	) {
+		return undefined;
+	}
+	const claims = objectArray(value.claims, parseClaim);
+	const artifacts = objectArray(value.artifacts, parseArtifact);
+	const changes = objectArray(value.changes, parseChange);
+	const verification = objectArray(value.verification, parseVerification);
+	const limitations = stringArray(value.limitations);
+	const unresolvedDependencies = stringArray(value.unresolvedDependencies);
+	if (
+		!claims ||
+		!artifacts ||
+		new Set(artifacts.map((artifact) => artifact.id)).size !== artifacts.length ||
+		!changes ||
+		!verification ||
+		!limitations ||
+		!unresolvedDependencies
+	) {
+		return undefined;
+	}
+	const reasonCode = optionalBoundedString(value.reasonCode, MAX_REASON_CODE_BYTES);
+	if (reasonCode === false) return undefined;
+	const provenance = parseProvenance(value.provenance);
+	if (provenance === false) return undefined;
+	return {
+		version: "pi-subagents:result:v2",
+		status: value.status as SubagentOutcomeStatus,
+		...(reasonCode === undefined ? {} : { reasonCode }),
+		summary: bounded(value.summary),
+		claims,
+		artifacts,
+		changes,
+		verification,
+		limitations,
+		unresolvedDependencies,
+		...(provenance === undefined ? {} : { provenance }),
+	};
+}
+
+export function parseAnyStructuredSubagentResult(
+	text: string,
+	format: SubagentResultFormat | undefined,
+): AnyStructuredSubagentResult | undefined {
+	if (format === "structured-v2") return parseStructuredSubagentResultV2(text);
+	if (format === "structured-v1") return parseStructuredSubagentResult(text);
+	return undefined;
+}
+
+export function resultContractEnvelope<T extends AnyStructuredSubagentResult>(
+	result: T,
+	metadata: ResultContractRuntimeMetadata = {},
+): ResultContractEnvelope<T> {
+	return {
+		result,
+		...(metadata.truncated === undefined ? {} : { truncated: metadata.truncated }),
+		...(metadata.usage === undefined ? {} : { usage: { ...metadata.usage } }),
+	};
+}
+
+function parseClaim(value: Record<string, unknown>): EvidenceBackedClaim | undefined {
+	if (
+		typeof value.claim !== "string" ||
+		typeof value.classification !== "string" ||
+		!SUBAGENT_CLAIM_CLASSIFICATIONS.includes(value.classification as SubagentClaimClassification)
+	) {
+		return undefined;
+	}
+	const evidence = stringArray(value.evidence);
+	if (!evidence) return undefined;
+	return {
+		claim: bounded(value.claim),
+		classification: value.classification as SubagentClaimClassification,
+		evidence,
+	};
+}
+
+function parseArtifact(value: Record<string, unknown>): SubagentArtifactReference | undefined {
+	if (typeof value.id !== "string" || typeof value.kind !== "string") return undefined;
+	const id = truncateUtf8(redactPrivateText(value.id), MAX_ARTIFACT_IDENTIFIER_BYTES).text.trim();
+	const kind = truncateUtf8(
+		redactPrivateText(value.kind),
+		MAX_ARTIFACT_IDENTIFIER_BYTES,
+	).text.trim();
+	if (!/^[A-Za-z0-9][A-Za-z0-9._:-]*$/u.test(id) || !kind) return undefined;
+	const version = optionalTrimmedBoundedString(value.version, MAX_ARTIFACT_IDENTIFIER_BYTES);
+	const location = optionalTrimmedBoundedString(value.location);
+	const digest = optionalTrimmedBoundedString(value.digest);
+	if (version === false || location === false || digest === false) return undefined;
+	return {
+		id,
+		kind,
+		...(version === undefined ? {} : { version }),
+		...(location === undefined ? {} : { location }),
+		...(digest === undefined ? {} : { digest }),
+	};
+}
+
+function parseChange(value: Record<string, unknown>): SubagentChangeReference | undefined {
+	if (typeof value.path !== "string" || typeof value.summary !== "string") return undefined;
+	return { path: bounded(value.path), summary: bounded(value.summary) };
+}
+
+function parseVerification(
+	value: Record<string, unknown>,
+): SubagentVerificationReference | undefined {
+	if (
+		typeof value.status !== "string" ||
+		!(["passed", "failed", "not-run"] as const).includes(
+			value.status as SubagentVerificationReference["status"],
+		) ||
+		typeof value.summary !== "string"
+	) {
+		return undefined;
+	}
+	const command = optionalBoundedString(value.command);
+	const evidence = value.evidence === undefined ? undefined : stringArray(value.evidence);
+	if (command === false || (evidence === undefined && value.evidence !== undefined))
+		return undefined;
+	return {
+		status: value.status as SubagentVerificationReference["status"],
+		summary: bounded(value.summary),
+		...(command === undefined ? {} : { command }),
+		...(evidence === undefined ? {} : { evidence }),
+	};
+}
+
+function parseProvenance(value: unknown): SubagentResultProvenance | undefined | false {
+	if (value === undefined) return undefined;
+	if (!isPlainObject(value)) return false;
+	const taskId = optionalBoundedString(value.taskId);
+	const repositoryGeneration = optionalBoundedString(value.repositoryGeneration);
+	const taskGeneration =
+		value.taskGeneration === undefined
+			? undefined
+			: Number.isSafeInteger(value.taskGeneration) && Number(value.taskGeneration) >= 0
+				? Number(value.taskGeneration)
+				: false;
+	const executionPlanId = optionalBoundedString(value.executionPlanId);
+	const cancellationLineage =
+		value.cancellationLineage === undefined ? undefined : stringArray(value.cancellationLineage);
+	const inputArtifacts =
+		value.inputArtifacts === undefined ? undefined : stringArray(value.inputArtifacts);
+	if (
+		taskId === false ||
+		repositoryGeneration === false ||
+		taskGeneration === false ||
+		executionPlanId === false ||
+		(cancellationLineage === undefined && value.cancellationLineage !== undefined) ||
+		(inputArtifacts === undefined && value.inputArtifacts !== undefined)
+	) {
+		return false;
+	}
+	return {
+		...(taskId === undefined ? {} : { taskId }),
+		...(taskGeneration === undefined ? {} : { taskGeneration }),
+		...(executionPlanId === undefined ? {} : { executionPlanId }),
+		...(cancellationLineage === undefined ? {} : { cancellationLineage }),
+		...(inputArtifacts === undefined ? {} : { inputArtifacts }),
+		...(repositoryGeneration === undefined ? {} : { repositoryGeneration }),
+	};
+}
+
+function parseJsonObject(text: string): Record<string, unknown> | undefined {
+	if (Buffer.byteLength(text, "utf8") > DEFAULT_MAX_OUTPUT_BYTES) return undefined;
+	const source = unwrapJsonFence(text).trim();
+	if (!source.startsWith("{") || !source.endsWith("}")) return undefined;
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(source);
+	} catch {
+		return undefined;
+	}
+	return isPlainObject(parsed) ? parsed : undefined;
+}
+
+function objectArray<T>(
+	value: unknown,
+	parse: (entry: Record<string, unknown>) => T | undefined,
+): T[] | undefined {
+	if (!Array.isArray(value) || value.length > MAX_ITEMS) return undefined;
+	const result: T[] = [];
+	for (const item of value) {
+		if (!isPlainObject(item)) return undefined;
+		const parsed = parse(item);
+		if (!parsed) return undefined;
+		result.push(parsed);
+	}
+	return result;
+}
+
+function stringArray(value: unknown): string[] | undefined {
+	if (!Array.isArray(value) || value.length > MAX_ITEMS) return undefined;
+	if (!value.every((item) => typeof item === "string")) return undefined;
+	return value.map((item) => bounded(item));
+}
+
+function optionalTrimmedBoundedString(
+	value: unknown,
+	maxBytes = MAX_FIELD_BYTES,
+): string | undefined | false {
+	const boundedValue = optionalBoundedString(value, maxBytes);
+	if (boundedValue === undefined || boundedValue === false) return boundedValue;
+	const trimmed = boundedValue.trim();
+	return trimmed || false;
+}
+
+function optionalBoundedString(
+	value: unknown,
+	maxBytes = MAX_FIELD_BYTES,
+): string | undefined | false {
+	if (value === undefined) return undefined;
+	if (typeof value !== "string") return false;
+	return truncateUtf8(redactPrivateText(value), maxBytes).text;
+}
+
+function bounded(value: string): string {
+	return truncateUtf8(redactPrivateText(value), MAX_FIELD_BYTES).text;
+}
+
+function hasOnlyKeys(value: Record<string, unknown>, allowed: readonly string[]): boolean {
+	return Object.keys(value).every((key) => allowed.includes(key));
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function unwrapJsonFence(value: string): string {
+	const trimmed = value.trim();
+	const match = /^```(?:json)?\s*\n([\s\S]*?)\n```$/iu.exec(trimmed);
+	return match?.[1] ?? trimmed;
+}

package/src/retained-semantic-state.ts

@@ -0,0 +1,100 @@
+import * as path from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import type { AgentConfig, SubagentThinkingLevel, SubagentTransportKind } from "./agents.js";
+import type { TargetPolicyAudit } from "./cwd-policy.js";
+import type { DelegationContract } from "./delegation-contract.js";
+import {
+	acknowledgeExecutionPlan,
+	createExecutionPlan,
+	type ExecutionPlan,
+	resolveContractTools,
+} from "./execution-plan.js";
+import type { SubagentResultFormat } from "./result-contract.js";
+import {
+	captureRepositoryGeneration,
+	captureSemanticResourceGeneration,
+	captureSemanticSnapshot,
+	type SemanticSnapshot,
+} from "./semantic-snapshot.js";
+
+export interface RetainedSemanticStateInput {
+	agent: AgentConfig;
+	contract?: DelegationContract;
+	target: TargetPolicyAudit;
+	cwd: string;
+	workspaceMode: "shared" | "worktree";
+	transport: SubagentTransportKind;
+	resultFormat: SubagentResultFormat;
+	thinkingLevel?: SubagentThinkingLevel;
+	timeoutMs?: number;
+	taskGeneration?: number;
+	cancellationLineage?: string[];
+}
+
+export interface RetainedSemanticState {
+	executionPlan: ExecutionPlan;
+	semanticSnapshot: SemanticSnapshot;
+}
+
+export async function buildRetainedSemanticState(
+	input: RetainedSemanticStateInput,
+): Promise<RetainedSemanticState> {
+	const executionPlan = createExecutionPlan({
+		contract: input.contract,
+		agent: input.agent,
+		effectiveTools: resolveContractTools(input.agent.tools, input.contract),
+		target: input.target,
+		workspaceMode: input.workspaceMode,
+		transport: input.transport,
+		resultFormat: input.resultFormat,
+		model: input.agent.model,
+		thinkingLevel: input.thinkingLevel ?? input.agent.thinkingLevel,
+		timeoutMs: input.timeoutMs ?? input.agent.timeoutMs,
+		taskGeneration: input.taskGeneration,
+		cancellationLineage: input.cancellationLineage,
+	});
+	const acknowledgement = acknowledgeExecutionPlan(executionPlan);
+	if (acknowledgement.status === "rejected") {
+		throw new Error(`Execution plan rejected: ${JSON.stringify(acknowledgement)}`);
+	}
+	const agentDir = getAgentDir();
+	const [repository, resourceGeneration] = await Promise.all([
+		captureRepositoryGeneration(input.cwd),
+		captureSemanticResourceGeneration([
+			path.join(agentDir, "skills"),
+			path.join(agentDir, "prompts"),
+			path.join(agentDir, "SYSTEM.md"),
+			path.join(agentDir, "APPEND_SYSTEM.md"),
+			path.join(input.cwd, ".pi", "skills"),
+			path.join(input.cwd, ".pi", "prompts"),
+			path.join(input.cwd, "AGENTS.md"),
+			path.join(input.cwd, "CLAUDE.md"),
+			path.join(input.cwd, "SYSTEM.md"),
+			path.join(input.cwd, "APPEND_SYSTEM.md"),
+		]),
+	]);
+	return {
+		executionPlan,
+		semanticSnapshot: captureSemanticSnapshot({
+			agentName: input.agent.name,
+			agentManifest: {
+				manifest: input.agent.capabilityManifest,
+				delegationContract: input.contract,
+				resourceGeneration,
+			},
+			rolePrompt: input.agent.systemPrompt,
+			tools: executionPlan.effectiveTools,
+			model: executionPlan.model,
+			thinkingLevel: executionPlan.thinkingLevel,
+			transport: input.transport,
+			trust: {
+				kind: input.target.trust.kind,
+				projectTrusted: input.target.trust.projectTrusted,
+			},
+			repository,
+			artifacts: {},
+			workflowGeneration: 0,
+			schedulerPolicy: "retained-fifo-v1",
+		}),
+	};
+}