@tangle-network/agent-runtime 0.138.1 → 0.139.0

package/dist/{runtime-CUpB4rEP.js → runtime-tTA2iCZQ.js}

@@ -1,21 +1,23 @@
-import { c as RetainedRunAdmissionError, f as ValidationError, l as RetainedRunDispatchBindingError, n as AnalystError, s as PlannerError } from "./errors-CVIDr7GQ.js";
-import "./stream-agent-turn-Q5ellSUu.js";
-import { g as isTraceAnalysisStore, i as InMemorySpawnJournal, r as InMemoryResultBlobStore, y as contentAddress } from "./spawn-journal-DVFqdzO9.js";
+import { C as sameControlCoordinates, S as isTerminalSessionStatus, _ as exactSession, a as assertEventBinding, b as freezeControlRef, c as assertSequence, d as awaitAbortable, f as cancellationRequest, g as exactControlRef, h as exactContinuedControlRef, i as assertCanonicalEventBinding, l as assertStableText, m as delay, n as abortError, o as assertInteractionBinding, p as copyControlRef, r as assertBoundaryBinding, s as assertResultBinding, t as RetainedRunProviderContractError, u as assertWaitDuration, v as exactSessionCancel, w as freshTurnInput, x as hasDurableCancel, y as exactSessionResult } from "./retained-run-binding-Dp2e8xne.js";
+import { c as RetainedInteractiveAdmissionError, d as RetainedRunDispatchBindingError, l as RetainedInteractiveBindingError, m as ValidationError, n as AnalystError, s as PlannerError, u as RetainedRunAdmissionError } from "./errors-CDZ8XsVj.js";
+import "./stream-agent-turn-4kUH8Nnn.js";
+import { t as detachedSnapshot } from "./snapshot-cK9K420n.js";
+import { g as isTraceAnalysisStore, i as InMemorySpawnJournal, r as InMemoryResultBlobStore, y as contentAddress } from "./spawn-journal-DGXei3xG.js";
 import { _ as zeroTokenUsage, a as hasCompleteCacheBreakdown, d as sleep, f as stringifySafe, h as usdEstimatedOf, l as randomSuffix, n as chargedTokens, o as isAbortError, r as cloneTokenUsage, t as addTokenUsage } from "./util-C1bv6yog.js";
 import { i as redactProtectedValue, r as redactProtectedReason } from "./protected-redaction--F3v1oo8.js";
-import { a as notifySandboxEventObserver, c as parseCanonicalTransportEvent, s as extractTransportEventIdentity } from "./sandbox-events-CA2amHoA.js";
-import { c as profileProviderModel, i as concreteModelId, s as profileModelExecutionSettings, t as assertExecutableAgentProfile } from "./model-policy-UTTc9Z-A.js";
-import { E as executableAgentSpecSnapshot, T as executableAgentProfileSnapshot } from "./materialization-BP5zspr2.js";
-import { E as rollingDispatch, I as createExecutor, L as createExecutorRegistry, _t as runBrainLoop, ft as runAgentRounds, g as settledToIteration, gt as routerBrain, l as withDriverExecutor, mt as probeSandboxCapabilities, n as createSupervisor, pt as createSandboxLineage, q as createPushTraceSource, ut as defaultSelectWinner, vt as canonicalObservedModel, z as createWorktreeCliExecutor } from "./supervisor-BoC2tFgH.js";
-import "./environment-provider-CLNVqp6H.js";
+import { c as extractTransportEventIdentity, l as parseCanonicalTransportEvent, o as notifySandboxEventObserver } from "./sandbox-events-DPmXlcKw.js";
+import { c as profileProviderModel, i as concreteModelId, s as profileModelExecutionSettings, t as assertExecutableAgentProfile } from "./model-policy-DgRJIJse.js";
+import { E as executableAgentSpecSnapshot, T as executableAgentProfileSnapshot } from "./materialization-CrdcfWXp.js";
+import { E as rollingDispatch, I as createExecutor, L as createExecutorRegistry, _t as runBrainLoop, ft as runAgentRounds, g as settledToIteration, gt as routerBrain, l as withDriverExecutor, mt as probeSandboxCapabilities, n as createSupervisor, pt as createSandboxLineage, q as createPushTraceSource, ut as defaultSelectWinner, vt as canonicalObservedModel, z as createWorktreeCliExecutor } from "./supervisor-BV72aDmP.js";
+import "./environment-provider-BAO8wt1_.js";
 import { i as notifyRuntimeHookEvent } from "./runtime-hooks-C7iJOWm3.js";
-import { C as observe, O as strategyAuthorMethod, T as profileChatClient, b as sample, v as refine, x as sampleThenRefine, y as runAgentic } from "./structural-rollout-CwtVIJf-.js";
-import { It as gateOnDeliverable, Lt as mapExecutorResult, n as supervise } from "./supervise-CUJRmx3s.js";
-import "./authoring-Cw6Ufsng.js";
-import "./graph-DxU92LTL.js";
+import { C as observe, O as strategyAuthorMethod, T as profileChatClient, b as sample, v as refine, x as sampleThenRefine, y as runAgentic } from "./structural-rollout-7LP9Ex0F.js";
+import { It as gateOnDeliverable, Lt as mapExecutorResult, n as supervise } from "./supervise-Cx1QY_hj.js";
+import "./authoring-J93uFAwd.js";
+import "./graph-BbMjq7-x.js";
+import { AgentEnvironmentCapabilitiesSchema, AgentExactRunControlRefSchema, AgentInteractiveSessionControlClaimAcknowledgementSchema, AgentInteractiveSessionControlClaimSchema, AgentInteractiveSessionPromptAcknowledgementSchema, AgentInteractiveSessionRefSchema, AgentInteractiveSessionStatusSchema, AgentInteractiveSessionStopAcknowledgementSchema, AgentNativeContextContinuationResultSchema, AgentTurnResultSchema, InteractionAcknowledgementSchema, InteractionResponseCommandSchema, NativeContextBoundaryProofSchema, NativeContextContinuationRequestSchema, RuntimeEventEnvelopeSchema, TerminalReplayWindowSchema, TerminalSessionRefSchema, agentInteractiveSessionControlClaimAcknowledgementMatchesRequest, agentInteractiveSessionControlClaimMatchesRef, agentInteractiveSessionControlClaimRequestDigest, agentInteractiveSessionPromptAcknowledgementMatchesCommand, agentInteractiveSessionRefMatchesStart, agentInteractiveSessionRunRef, agentInteractiveSessionStatusMatchesRef, agentInteractiveSessionStopAcknowledgementMatchesCommand, agentNativeContextContinuationResultMatchesRequest, agentProfileSchema, canonicalAgentProfileDigest, canonicalCandidateDigest, exactAgentInteractiveSessionStart, nativeContextContinuationTurnDigest, validateAgentProfileSecurity } from "@tangle-network/agent-interface";
 import { CODING_HARNESSES, InMemoryTraceStore, OUTPUT_VALUE, benjaminiHochberg, buildTrajectory, computeFindingId as computeFindingId$1, confidenceInterval, expandProfileAxes, makeFinding as makeFinding$1, pairedBootstrap, paretoFrontier, wilcoxonSignedRank, wilson } from "@tangle-network/agent-eval";
 import { heldoutSignificance, runProfileMatrix } from "@tangle-network/agent-eval/campaign";
-import { AgentEnvironmentCapabilitiesSchema, AgentExactRunControlRefSchema, AgentNativeContextContinuationResultSchema, AgentRunCancellationAcknowledgementSchema, AgentRunCancellationRequestSchema, AgentTurnResultSchema, InteractionAcknowledgementSchema, InteractionResponseCommandSchema, NativeContextBoundaryProofSchema, NativeContextContinuationRequestSchema, RuntimeEventEnvelopeSchema, agentNativeContextContinuationResultMatchesRequest, agentProfileSchema, agentRunCancellationAcknowledgementMatchesRequest, agentRunCancellationRequestDigest, canonicalAgentProfileDigest, canonicalCandidateDigest, nativeContextContinuationTurnDigest, validateAgentProfileSecurity } from "@tangle-network/agent-interface";
 import { createHash } from "node:crypto";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { mkdir, readFile, realpath, writeFile } from "node:fs/promises";
@@ -3483,187 +3485,242 @@ function promotionGate(opts) {
 	};
 }
 //#endregion
-//#region src/runtime/retained-run-binding.ts
-function exactSession(environment, controlRef) {
-	if (environment.id !== controlRef.environmentId || environment.provider !== controlRef.provider) throw new Error("provider reconstructed a different retained environment");
-	if (!environment.session || !controlRef.sessionId) throw new Error("retained run control requires a provider session id");
-	const session = environment.session(controlRef.sessionId, { controlRef });
-	if (session.id !== controlRef.sessionId) throw new Error("provider reconstructed a different session");
-	if (session.controlRef === void 0) throw new Error("provider session did not return its provider-owned run control reference");
-	const currentControlRef = AgentExactRunControlRefSchema.parse(session.controlRef);
-	if (!sameControlCoordinates(currentControlRef, controlRef)) throw new Error("provider session reconstructed a different retained session");
-	if (canonicalCandidateDigest(currentControlRef) !== canonicalCandidateDigest(controlRef)) throw new Error("provider session did not retain the exact run control reference");
-	return {
-		session,
-		controlRef: currentControlRef
-	};
-}
-function sameControlCoordinates(left, right) {
-	return canonicalCandidateDigest(left) === canonicalCandidateDigest(right);
-}
-function freezeControlRef(controlRef) {
-	return Object.freeze({ ...AgentExactRunControlRefSchema.parse(controlRef) });
-}
-function copyControlRef(controlRef) {
-	return { ...controlRef };
-}
-function exactControlRef(candidate, expected) {
-	if (!candidate) throw new Error("provider dispatch returned no durable run control reference");
-	const controlRef = AgentExactRunControlRefSchema.parse(candidate);
-	if (controlRef.provider !== expected.provider || controlRef.environmentId !== expected.environmentId || controlRef.sessionId !== expected.sessionId) throw new Error("provider dispatch returned control coordinates for another run");
-	return controlRef;
-}
-function exactContinuedControlRef(candidate, initial) {
-	const controlRef = AgentExactRunControlRefSchema.parse(candidate);
-	if (controlRef.provider !== initial.provider || controlRef.environmentId !== initial.environmentId || controlRef.sessionId !== initial.sessionId) throw new Error("provider continuation advanced to another retained session");
-	if (controlRef.runId === initial.runId && controlRef.executionId === initial.executionId) throw new Error("provider continuation did not return a new exact run execution");
-	return controlRef;
+//#region src/runtime/retained-interactive-handle.ts
+function createRetainedInteractiveRunHandle(environment, inputRef, capabilities, requestedStart) {
+	const ref = freezeInteractiveRef(inputRef);
+	const source = environment.interactive(ref);
+	if (!sameInteractiveRef(source.ref, ref)) throw new Error("provider reconstructed a different interactive process");
+	if (!source.sendPrompt) throw new Error("provider declared interactive prompt support but exposed no prompt method");
+	return Object.freeze({
+		ref,
+		capabilities,
+		claimControl: async (request, options) => exactClaim(ref, request, await awaitAbortable(Promise.resolve().then(() => source.claimControl(request, options)), options?.signal)),
+		status: async (options) => exactStatus(ref, await awaitAbortable(Promise.resolve().then(() => source.status(options)), options?.signal), requestedStart),
+		attach: async (request, options) => exactTerminal(ref, request, await awaitAbortable(Promise.resolve().then(() => source.attach(request, options)), options?.signal)),
+		sendPrompt: async (command, options) => exactPrompt(ref, await awaitAbortable(Promise.resolve().then(() => source.sendPrompt(command, options)), options?.signal), command),
+		stop: async (command, options) => exactStop(ref, await awaitAbortable(Promise.resolve().then(() => source.stop(command, options)), options?.signal), command)
+	});
 }
-function assertInteractionBinding(controlRef, command) {
-	if (command.binding.runId !== controlRef.runId || command.binding.provider !== controlRef.provider || command.binding.environmentId !== controlRef.environmentId || command.binding.sessionId !== controlRef.sessionId || command.binding.executionId !== controlRef.executionId) throw new Error("interaction response command does not target this retained run");
+function freezeInteractiveRef(value) {
+	return detachedSnapshot(AgentInteractiveSessionRefSchema.parse(value), "interactive session ref");
 }
-function assertBoundaryBinding(controlRef, proof) {
-	if (proof.runId !== controlRef.runId || proof.provider !== controlRef.provider || proof.environmentId !== controlRef.environmentId || proof.sessionId !== controlRef.sessionId || proof.executionId !== controlRef.executionId || proof.requestDigest !== controlRef.requestDigest) throw new Error("native context proof does not identify this retained run");
+function exactClaim(ref, request, value) {
+	const acknowledgement = parseProviderAcknowledgement(AgentInteractiveSessionControlClaimAcknowledgementSchema, value, "control claim");
+	if (!agentInteractiveSessionControlClaimAcknowledgementMatchesRequest(request, acknowledgement)) throw new RetainedRunProviderContractError("provider returned a control claim acknowledgement for another request");
+	if (acknowledgement.control && !agentInteractiveSessionControlClaimMatchesRef(ref, acknowledgement.control)) throw new RetainedRunProviderContractError("provider returned a control claim for another interactive process");
+	return acknowledgement;
 }
-function assertSequence(value, label) {
-	if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) throw new Error(`${label} must be a non-negative safe integer`);
+function exactPrompt(ref, value, command) {
+	const acknowledgement = parseProviderAcknowledgement(AgentInteractiveSessionPromptAcknowledgementSchema, value, "prompt");
+	if (!agentInteractiveSessionPromptAcknowledgementMatchesCommand(command, acknowledgement)) throw new RetainedRunProviderContractError("provider returned a prompt acknowledgement for another request");
+	if (!agentInteractiveSessionControlClaimMatchesRef(ref, acknowledgement.control)) throw new RetainedRunProviderContractError("provider returned a prompt acknowledgement for another interactive process");
+	return acknowledgement;
 }
-function assertResultBinding(controlRef, result) {
-	if (result.sessionId !== controlRef.sessionId) throw new Error("provider returned a result for another retained session");
-	const metadata = result.metadata;
-	if (controlRef.executionId !== void 0 && metadata?.executionId !== controlRef.executionId) throw new Error("provider returned a result for another retained execution");
-	if (metadata?.runId !== controlRef.runId) throw new Error("provider returned a result for another retained run");
-	if (metadata?.requestDigest !== controlRef.requestDigest) throw new Error("provider returned a result for another retained request");
+function exactStop(ref, value, command) {
+	const acknowledgement = parseProviderAcknowledgement(AgentInteractiveSessionStopAcknowledgementSchema, value, "stop");
+	if (!agentInteractiveSessionStopAcknowledgementMatchesCommand(command, acknowledgement)) throw new RetainedRunProviderContractError("provider returned a stop acknowledgement for another request");
+	if (!agentInteractiveSessionControlClaimMatchesRef(ref, acknowledgement.control)) throw new RetainedRunProviderContractError("provider returned a stop acknowledgement for another interactive process");
+	return acknowledgement;
 }
-var RetainedRunProviderContractError = class extends Error {
-	constructor(message) {
-		super(message);
-		this.name = "RetainedRunProviderContractError";
+function parseProviderAcknowledgement(schema, value, operation) {
+	try {
+		return schema.parse(value);
+	} catch {
+		throw new RetainedRunProviderContractError(`provider returned an invalid interactive ${operation} acknowledgement`);
 	}
-};
-function cancellationRequest(controlRef, operationId, reason) {
-	const material = {
-		operationId,
-		run: AgentExactRunControlRefSchema.parse(controlRef),
-		...reason === void 0 ? {} : { reason }
-	};
-	return AgentRunCancellationRequestSchema.parse({
-		...material,
-		requestDigest: agentRunCancellationRequestDigest(material)
-	});
 }
-async function exactSessionCancel(session, request, options) {
-	if (!session.cancelRun) throw new Error("provider session does not expose durable cancellation operations");
-	let acknowledgement;
+function exactStatus(ref, value, requestedStart) {
+	let status;
 	try {
-		acknowledgement = await awaitAbortable(Promise.resolve().then(() => session.cancelRun(request, options)), options.signal);
+		status = AgentInteractiveSessionStatusSchema.parse(value);
 	} catch (error) {
-		if (error instanceof RetainedRunProviderContractError) throw error;
-		throw error;
+		if (requestedStart === void 0) throw error;
+		throw new RetainedInteractiveBindingError(detachedSnapshot(requestedStart, "interactive status binding request"), {}, { cause: error });
 	}
-	let exactAcknowledgement;
-	try {
-		exactAcknowledgement = AgentRunCancellationAcknowledgementSchema.parse(acknowledgement);
-	} catch {
-		throw new RetainedRunProviderContractError("provider returned an invalid retained cancellation acknowledgement");
+	if (!agentInteractiveSessionStatusMatchesRef(ref, status)) {
+		if (requestedStart !== void 0) throw new RetainedInteractiveBindingError(detachedSnapshot(requestedStart, "interactive status binding request"), detachedSnapshot({ status: detachedSnapshot(status, "interactive provider status") }, "interactive provider status result"), { cause: /* @__PURE__ */ new Error("provider returned status for another interactive process") });
+		throw new Error("provider returned status for another interactive process");
 	}
-	if (!agentRunCancellationAcknowledgementMatchesRequest(request, exactAcknowledgement)) throw new RetainedRunProviderContractError("provider returned a retained cancellation acknowledgement for another request");
-	return exactAcknowledgement;
+	return status;
+}
+function exactTerminal(ref, request, terminal) {
+	const terminalRef = TerminalSessionRefSchema.parse(terminal.ref);
+	TerminalReplayWindowSchema.parse(terminal.cursors);
+	if (terminalRef.parentExecutionId !== ref.run.executionId) throw new Error("provider attached a terminal from another interactive run");
+	AgentInteractiveSessionControlClaimSchema.parse(terminal.control);
+	if (!agentInteractiveSessionControlClaimMatchesRef(ref, terminal.control)) throw new Error("provider attached a terminal with a claim for another interactive process");
+	if (canonicalCandidateDigest(terminal.control) !== canonicalCandidateDigest(request.control)) throw new Error("provider attached a terminal with a different interactive control claim");
+	return terminal;
+}
+function sameInteractiveRef(left, right) {
+	return canonicalCandidateDigest(left) === canonicalCandidateDigest(right);
 }
-function hasDurableCancel(session) {
-	return typeof session.cancelRun === "function";
+//#endregion
+//#region src/runtime/retained-interactive-lifecycle.ts
+const INTERACTIVE_CLEANUP_TIMEOUT_MS = 3e4;
+/** Create one environment while retaining ownership if cancellation wins the race. */
+async function createInteractiveEnvironment(create, signal) {
+	if (signal?.aborted) throw abortError(signal.reason);
+	const creation = Promise.resolve().then(create);
+	if (signal === void 0) return creation;
+	return new Promise((resolve, reject) => {
+		let owner = "pending";
+		const removeAbortListener = () => signal.removeEventListener("abort", onAbort);
+		const onAbort = () => {
+			if (owner !== "pending") return;
+			owner = "runtime";
+			removeAbortListener();
+			disposeInteractiveEnvironment(creation, signal.reason);
+			reject(abortError(signal.reason));
+		};
+		signal.addEventListener("abort", onAbort, { once: true });
+		creation.then((environment) => {
+			if (owner !== "pending") return;
+			owner = "caller";
+			removeAbortListener();
+			resolve(environment);
+		}, (error) => {
+			if (owner !== "pending") return;
+			owner = "runtime";
+			removeAbortListener();
+			reject(error);
+		});
+	});
 }
-async function awaitAbortable(work, signal) {
-	if (signal === void 0) return await work;
-	if (signal.aborted) {
-		Promise.resolve(work).catch(() => void 0);
+/** Start one process while destroying its unreturned environment on cancellation. */
+async function startInteractiveProcess(environment, start, signal) {
+	if (signal?.aborted) {
+		disposeInteractiveEnvironment(Promise.resolve(environment), signal.reason);
 		throw abortError(signal.reason);
 	}
-	return await new Promise((resolve, reject) => {
-		let settled = false;
-		const cleanup = () => signal.removeEventListener("abort", onAbort);
+	const pending = Promise.resolve().then(start);
+	if (signal === void 0) return pending;
+	return new Promise((resolve, reject) => {
+		let owner = "pending";
+		const removeAbortListener = () => signal.removeEventListener("abort", onAbort);
 		const onAbort = () => {
-			queueMicrotask(() => {
-				if (settled) return;
-				settled = true;
-				cleanup();
-				reject(abortError(signal.reason));
-			});
+			if (owner !== "pending") return;
+			owner = "runtime";
+			removeAbortListener();
+			disposeInteractiveEnvironment(Promise.resolve(environment), signal.reason);
+			reject(abortError(signal.reason));
 		};
 		signal.addEventListener("abort", onAbort, { once: true });
-		Promise.resolve(work).then((value) => {
-			if (settled) return;
-			settled = true;
-			cleanup();
-			resolve(value);
+		pending.then((result) => {
+			if (owner !== "pending") return;
+			owner = "caller";
+			removeAbortListener();
+			resolve(result);
 		}, (error) => {
-			if (settled) return;
-			settled = true;
-			cleanup();
+			if (owner !== "pending") return;
+			owner = "runtime";
+			removeAbortListener();
 			reject(error);
 		});
 	});
 }
-async function exactSessionResult(session) {
-	return session.result();
-}
-function assertEventBinding(source, controlRef) {
-	const transport = isRecord(source) ? source : void 0;
-	const payload = isRecord(source.data) ? source.data : void 0;
-	const providerEvent = isRecord(source.providerEvent) ? source.providerEvent : void 0;
-	const bindings = [
-		{
-			value: transport,
-			checkSessionId: true
-		},
-		{
-			value: payload,
-			checkSessionId: source.type !== "session.updated"
-		},
-		{
-			value: providerEvent,
-			checkSessionId: true
-		}
-	];
-	for (const { value, checkSessionId } of bindings) {
-		if (value === void 0) continue;
-		if (value.runId !== void 0 && value.runId !== controlRef.runId) throw new Error("provider returned an event for another retained run");
-		if (value.executionId !== void 0 && value.executionId !== controlRef.executionId) throw new Error("provider returned an event for another retained execution");
-		if (checkSessionId && value.sessionId !== void 0 && value.sessionId !== controlRef.sessionId) throw new Error("provider returned an event for another retained session");
+/** Destroy an environment with fresh, bounded cleanup authority. */
+async function destroyInteractiveEnvironment(environment) {
+	if (!environment.destroy) throw new Error(`provider environment "${environment.id}" does not expose destroy()`);
+	const controller = new AbortController();
+	const timeout = /* @__PURE__ */ new Error("interactive environment cleanup timed out");
+	let timer;
+	const destruction = Promise.resolve().then(() => environment.destroy?.({ signal: controller.signal }));
+	destruction.catch(() => void 0);
+	try {
+		await Promise.race([destruction, new Promise((_resolve, reject) => {
+			timer = setTimeout(() => {
+				controller.abort(timeout);
+				reject(timeout);
+			}, INTERACTIVE_CLEANUP_TIMEOUT_MS);
+		})]);
+	} finally {
+		if (timer !== void 0) clearTimeout(timer);
 	}
 }
-function isRecord(value) {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
+function disposeInteractiveEnvironment(environment, abortReason) {
+	environment.then(destroyInteractiveEnvironment, () => void 0).catch((cleanupError) => {
+		const reason = abortReason instanceof Error ? abortReason : new Error(String(abortReason));
+		const failure = new AggregateError([reason, cleanupError], "cancelled interactive environment cleanup failed");
+		process.emitWarning(failure, { code: "AGENT_RUNTIME_INTERACTIVE_CLEANUP_FAILED" });
+	});
 }
-function assertStableText(value, label) {
-	if (value.length === 0 || value.trim() !== value) throw new Error(`${label} must be non-empty and have no outer whitespace`);
+//#endregion
+//#region src/runtime/retained-run-intent.ts
+/**
+* Project environment creation input into public digest material.
+*
+* Opaque values never enter the material or its digest. Public scalar fields
+* remain bound directly, while opaque records retain only their key names.
+* Secret names remain public binding data, so changing requested credentials
+* still conflicts before provider effects begin.
+*/
+function retainedCreateMaterial(environment) {
+	return {
+		...environment.backend === void 0 ? {} : { backend: environment.backend },
+		...environment.workspace === void 0 ? {} : { workspaceDigest: canonicalCandidateDigest(publicWorkspaceMaterial(environment.workspace)) },
+		...environment.resources === void 0 ? {} : { resourcesDigest: canonicalCandidateDigest(publicResourceMaterial(environment.resources)) },
+		...environment.name === void 0 ? {} : { name: environment.name },
+		...environment.env === void 0 ? {} : { environmentVariableNames: retainedObjectNames(environment.env) },
+		...environment.secrets === void 0 ? {} : { secretNames: retainedSecretNames(environment.secrets) },
+		...environment.metadata === void 0 ? {} : { metadataKeys: retainedObjectNames(environment.metadata) },
+		...environment.providerOptions === void 0 ? {} : { providerOptionNames: retainedObjectNames(environment.providerOptions) }
+	};
 }
-function abortError(reason) {
-	const error = new Error(reason === void 0 ? "aborted" : String(reason));
-	error.name = "AbortError";
-	return error;
+function publicWorkspaceMaterial(workspace) {
+	return {
+		...workspace.environment === void 0 ? {} : { environment: workspace.environment },
+		...workspace.image === void 0 ? {} : { image: workspace.image },
+		...workspace.repoUrl === void 0 ? {} : { repoUrl: workspace.repoUrl },
+		...workspace.gitRef === void 0 ? {} : { gitRef: workspace.gitRef },
+		...workspace.cwd === void 0 ? {} : { cwd: workspace.cwd },
+		...workspace.providerOptions === void 0 ? {} : { providerOptionNames: retainedObjectNames(workspace.providerOptions) }
+	};
 }
-function assertWaitDuration(value, label) {
-	if (!Number.isSafeInteger(value) || value < 0) throw new Error(`${label} must be a non-negative safe integer`);
+function publicResourceMaterial(resources) {
+	return {
+		...resources.cpu === void 0 ? {} : { cpu: resources.cpu },
+		...resources.memoryMb === void 0 ? {} : { memoryMb: resources.memoryMb },
+		...resources.diskMb === void 0 ? {} : { diskMb: resources.diskMb },
+		...resources.gpu === void 0 ? {} : { gpu: resources.gpu },
+		...resources.providerOptions === void 0 ? {} : { providerOptionNames: retainedObjectNames(resources.providerOptions) }
+	};
 }
-function isTerminalSessionStatus(status) {
-	return status === "completed" || status === "failed" || status === "cancelled" || status === "expired";
+function retainedObjectNames(value) {
+	return Object.keys(value).sort();
 }
-function delay(ms, signal) {
-	if (signal?.aborted) return Promise.reject(abortError(signal.reason));
-	return new Promise((resolveDelay, rejectDelay) => {
-		const timer = setTimeout(finish, ms);
-		function finish() {
-			signal?.removeEventListener("abort", onAbort);
-			resolveDelay();
-		}
-		function onAbort() {
-			clearTimeout(timer);
-			signal?.removeEventListener("abort", onAbort);
-			rejectDelay(abortError(signal?.reason));
-		}
-		signal?.addEventListener("abort", onAbort, { once: true });
-	});
+function retainedSecretNames(secrets) {
+	return Array.isArray(secrets) ? [...secrets].sort() : Object.keys(secrets).sort();
+}
+/** Project one headless turn into the material that `freshTurnInput` forwards. */
+function retainedTurnMaterial(input) {
+	return {
+		...input.prompt === void 0 ? {} : { prompt: input.prompt },
+		...input.parts === void 0 ? {} : { parts: input.parts },
+		...input.model === void 0 ? {} : { model: input.model },
+		...input.timeoutMs === void 0 ? {} : { timeoutMs: input.timeoutMs },
+		...input.context === void 0 ? {} : { context: input.context },
+		...input.interactions === void 0 ? {} : { interactions: input.interactions },
+		...input.providerOptions === void 0 ? {} : { providerOptions: input.providerOptions }
+	};
+}
+//#endregion
+//#region src/runtime/interaction-capabilities.ts
+/**
+* Check one turn's interaction request before the provider can dispatch it.
+*
+* A requested interaction is durable only when the provider can replay its
+* event and safely replay the response command. An unsupported request fails
+* before environment creation or dispatch begins.
+*/
+function assertRequestedInteractionCapabilities(providerName, requested, capabilities) {
+	const requestedKinds = Object.entries(requested ?? {}).filter(([, enabled]) => enabled === true).map(([kind]) => kind);
+	if (requestedKinds.length === 0) return;
+	const interactions = capabilities.interactions;
+	if (!interactions) throw new Error(`provider "${providerName}" does not support requested interactions: ${requestedKinds.join(", ")}`);
+	const unsupportedKinds = requestedKinds.filter((kind) => !interactions.kinds.includes(kind));
+	if (unsupportedKinds.length > 0) throw new Error(`provider "${providerName}" does not support requested interaction kinds: ${unsupportedKinds.join(", ")}`);
+	if (interactions.replay !== true || interactions.responseIdempotency !== true) throw new Error(`provider "${providerName}" cannot safely dispatch requested interactions without replay and response idempotency`);
 }
 //#endregion
 //#region src/runtime/retained-run-events.ts
@@ -3693,6 +3750,7 @@ async function* retainedRunEvents(session, controlRef, options, now) {
 			if (sourceCursor === after?.cursor) continue;
 			const event = canonicalEvent(source);
 			if (!event) continue;
+			assertCanonicalEventBinding(controlRef, event);
 			if (firstAfterEvent && after !== void 0) {
 				if (identity.sequence !== void 0 && identity.sequence <= after.sequence) throw new Error("provider replay did not prove that the first event follows the requested cursor");
 				firstAfterEvent = false;
@@ -3736,6 +3794,7 @@ function canonicalEvent(source) {
 //#region src/runtime/retained-run-handle.ts
 function createRetainedRunHandle(environment, session, initialControlRef, capabilities, now) {
 	const clock = now ?? Date.now;
+	const measuredCapabilities = structuredClone(capabilities);
 	let activeControlRef = freezeControlRef(initialControlRef);
 	const snapshot = async (reason, signal) => {
 		if (signal?.aborted) throw abortError(signal.reason);
@@ -3761,6 +3820,9 @@ function createRetainedRunHandle(environment, session, initialControlRef, capabi
 		get controlRef() {
 			return copyControlRef(activeControlRef);
 		},
+		get capabilities() {
+			return structuredClone(measuredCapabilities);
+		},
 		status: async (options) => {
 			const waitMs = options?.waitMs ?? 0;
 			assertWaitDuration(waitMs, "retained status wait");
@@ -3784,7 +3846,7 @@ function createRetainedRunHandle(environment, session, initialControlRef, capabi
 		async respondToInteraction(command, options) {
 			const exactCommand = InteractionResponseCommandSchema.parse(command);
 			assertInteractionBinding(activeControlRef, exactCommand);
-			if (capabilities.interactions?.responseIdempotency !== true) throw new Error(`provider "${activeControlRef.provider}" does not promise retry-safe interaction responses`);
+			if (measuredCapabilities.interactions?.replay !== true || measuredCapabilities.interactions.responseIdempotency !== true) throw new Error(`provider "${activeControlRef.provider}" does not promise retry-safe interaction responses`);
 			const respond = session.respondToInteraction ?? environment.respondToInteraction;
 			if (!respond) throw new Error(`provider "${activeControlRef.provider}" does not support interaction responses`);
 			const acknowledgement = InteractionAcknowledgementSchema.parse(await awaitAbortable(Promise.resolve().then(() => respond.call(session.respondToInteraction ? session : environment, exactCommand, options)), options?.signal));
@@ -3804,7 +3866,7 @@ function createRetainedRunHandle(environment, session, initialControlRef, capabi
 			if (!sameControlCoordinates(exactRequest.run, activeControlRef)) throw new Error("native continuation request targets another retained run");
 			const { timeoutMs, signal, ...semanticTurn } = turn;
 			if (nativeContextContinuationTurnDigest(semanticTurn) !== exactRequest.turnDigest) throw new Error("native continuation request targets another user turn");
-			if (capabilities.nativeContinuation?.atomicBoundary !== true || capabilities.nativeContinuation.requestIdempotency !== true || !session.continueNative) throw new Error(`provider "${activeControlRef.provider}" does not support retry-safe native continuation`);
+			if (measuredCapabilities.nativeContinuation?.atomicBoundary !== true || measuredCapabilities.nativeContinuation.requestIdempotency !== true || !session.continueNative) throw new Error(`provider "${activeControlRef.provider}" does not support retry-safe native continuation`);
 			const outcome = AgentNativeContextContinuationResultSchema.parse(await awaitAbortable(Promise.resolve().then(() => session.continueNative(exactRequest, {
 				turn: semanticTurn,
 				...timeoutMs === void 0 ? {} : { timeoutMs },
@@ -3862,31 +3924,6 @@ function createRetainedRunHandle(environment, session, initialControlRef, capabi
 	};
 }
 //#endregion
-//#region src/runtime/turn-input.ts
-/**
-* Copy only fields that describe a new provider turn.
-*
-* Session, replay, continuation, and transfer coordinates are runtime-owned
-* and are injected by the caller that owns that lifecycle. Keeping this copy
-* explicit also makes JavaScript callers subject to the same boundary.
-*/
-function freshTurnInput(input, runtime) {
-	return {
-		...input.prompt === void 0 ? {} : { prompt: input.prompt },
-		...input.parts === void 0 ? {} : { parts: input.parts },
-		...input.model === void 0 ? {} : { model: input.model },
-		...input.timeoutMs === void 0 ? {} : { timeoutMs: input.timeoutMs },
-		...input.context === void 0 ? {} : { context: input.context },
-		...input.providerOptions === void 0 ? {} : { providerOptions: input.providerOptions },
-		...input.signal === void 0 ? {} : { signal: input.signal },
-		turnId: runtime.turnId,
-		detach: runtime.detach,
-		...runtime.sessionId === void 0 ? {} : { sessionId: runtime.sessionId },
-		...runtime.executionId === void 0 ? {} : { executionId: runtime.executionId },
-		...runtime.contextTransfer === void 0 ? {} : { contextTransfer: runtime.contextTransfer }
-	};
-}
-//#endregion
 //#region src/runtime/retained-run-start.ts
 /**
 * Mint deterministic dispatch coordinates from the two caller-supplied keys.
@@ -3911,11 +3948,10 @@ function mintRetainedIdentity(idempotencyKey, turnId) {
 * Dispatch one detached, replayable run and return only after exact durable
 * coordinates are confirmed by the provider and persisted by the caller.
 *
-* The required `onAdmission` hook is awaited twice: with the recovery
-* coordinates after environment creation, and with the verified exact control
-* reference after dispatch. The returned promise resolves only after the
-* dispatched admission is durable, so no caller can observe a successful start
-* whose exact reference a crash would lose.
+* The required `onAdmission` hook first records a digest-only intent before
+* creation, then records recovery coordinates and the verified exact control
+* reference. The returned promise resolves only after the dispatched admission
+* is durable, so a crash cannot lose a successful start's exact reference.
 *
 * @stable
 */
@@ -3928,17 +3964,35 @@ async function startRetainedRun(options) {
 	}
 	if (typeof options.onAdmission !== "function") throw new Error("startRetainedRun requires an awaited onAdmission durability hook");
 	const identity = options.identity ?? mintRetainedIdentity(options.environment.idempotencyKey, options.turn.turnId);
-	const capabilities = await assertRetainedCapabilities(options.provider);
 	if (!options.provider.get) throw new Error(`provider "${options.provider.name}" cannot reconstruct an environment by id`);
+	const intent = retainedRunIntent(options, identity);
+	if (options.intent === void 0) await admitDurably(options.onAdmission, intent);
+	else assertExactRetainedRunIntent(options.intent, intent);
+	const providerCapabilities = await assertRetainedCapabilities(options.provider);
+	assertRequestedInteractionCapabilities(options.provider.name, options.turn.interactions, providerCapabilities);
 	const environment = await options.provider.create({
 		...options.environment,
 		metadata: {
 			...options.environment.metadata,
 			retainedIdempotencyKey: options.environment.idempotencyKey,
+			retainedIntentDigest: intent.requestDigest,
+			retainedRunId: intent.runId,
 			sessionId: identity.sessionId,
 			executionId: identity.executionId
 		}
 	});
+	let capabilities;
+	try {
+		capabilities = retainedCapabilitiesForEnvironment(options.provider.name, providerCapabilities, environment);
+		assertRequestedInteractionCapabilities(options.provider.name, options.turn.interactions, capabilities);
+	} catch (error) {
+		try {
+			await environment.destroy?.();
+		} catch (cleanupError) {
+			throw new AggregateError([error, cleanupError], "retained run environment published invalid capabilities and could not be destroyed");
+		}
+		throw error;
+	}
 	if (!environment.dispatch || !environment.session) {
 		try {
 			await environment.destroy?.();
@@ -3977,11 +4031,13 @@ async function startRetainedRunInEnvironment(options) {
 	}
 	if (typeof options.onAdmission !== "function") throw new Error("startRetainedRunInEnvironment requires an awaited onAdmission durability hook");
 	const identity = options.identity ?? mintRetainedIdentity(options.environment.idempotencyKey, options.turn.turnId);
-	const capabilities = await assertRetainedCapabilities(options.provider);
+	const providerCapabilities = await assertRetainedCapabilities(options.provider);
 	if (!options.provider.get) throw new Error(`provider "${options.provider.name}" cannot reconstruct an environment by id`);
 	const environment = await options.provider.get(options.environment.id);
 	if (!environment) throw new Error(`provider "${options.provider.name}" no longer holds environment "${options.environment.id}"`);
 	if (environment.id !== options.environment.id || environment.provider !== options.provider.name) throw new Error("provider reconstructed a different retained environment");
+	const capabilities = retainedCapabilitiesForEnvironment(options.provider.name, providerCapabilities, environment);
+	assertRequestedInteractionCapabilities(options.provider.name, options.turn.interactions, capabilities);
 	if (!environment.dispatch || !environment.session) throw new Error(`provider "${options.provider.name}" does not expose detached session control`);
 	await assertRetainedEnvironmentOwnership(options.provider, environment.id, options.environment.idempotencyKey);
 	return dispatchRetainedRun({
@@ -4002,6 +4058,7 @@ async function assertRetainedEnvironmentOwnership(provider, environmentId, idemp
 }
 async function dispatchRetainedRun(options) {
 	const { environment, identity } = options;
+	assertRequestedInteractionCapabilities(options.provider.name, options.turn.interactions, options.capabilities);
 	await admitDurably(options.onAdmission, {
 		phase: "environment",
 		provider: options.provider.name,
@@ -4054,37 +4111,39 @@ async function dispatchRetainedRun(options) {
 * callers can distinguish a persistence failure from a provider failure.
 */
 async function admitDurably(onAdmission, admission) {
+	const stableAdmission = detachedSnapshot(admission, "retained run admission");
 	try {
-		await onAdmission(Object.freeze(admission));
+		await onAdmission(stableAdmission);
 	} catch (error) {
-		throw new RetainedRunAdmissionError(admission, { cause: error });
+		if (isInteractiveAdmission(stableAdmission)) throw new RetainedInteractiveAdmissionError(stableAdmission, { cause: error });
+		throw new RetainedRunAdmissionError(stableAdmission, { cause: error });
 	}
 }
-/**
-* Rebuild the exact run named by pre-dispatch admission coordinates, or
-* report why the provider cannot prove it.
-*
-* `not_found`: the provider no longer holds the environment, so nothing
-* remains to destroy. `recovered`: the provider self-identified the session
-* with a strict exact reference matching the recorded coordinates.
-* `unverifiable`: the environment exists but the provider cannot
-* self-identify the session — no session accessor, an accessor that throws,
-* a lazy accessor with no stored reference, or a loose reference. That
-* outcome is never destroy-safe: keep the environment, retry
-* `reconnectRetainedRun` with a dispatched admission record, or inspect the
-* environment with provider-native tools. A session that self-identifies
-* with different coordinates throws: something live is not the recorded run.
-*
-* @stable
-*/
+function isInteractiveAdmission(admission) {
+	return admission.phase === "interactive_intent" || admission.phase === "interactive_environment" || admission.phase === "interactive_started";
+}
 async function recoverRetainedRun(options) {
+	if ("admission" in options) {
+		if (options.admission.provider !== options.provider.name) throw new Error("retained run intent belongs to another provider");
+		return {
+			outcome: "recovered",
+			handle: await startRetainedRun({
+				provider: options.provider,
+				...options.replay,
+				intent: options.admission,
+				onAdmission: options.onAdmission,
+				now: options.now
+			})
+		};
+	}
 	assertStableText(options.environmentId, "retained environment id");
 	assertStableText(options.sessionId, "retained session id");
 	assertStableText(options.executionId, "retained execution id");
-	const capabilities = await assertRetainedCapabilities(options.provider);
+	const providerCapabilities = await assertRetainedCapabilities(options.provider);
 	if (!options.provider.get) throw new Error(`provider "${options.provider.name}" cannot reconstruct an environment by id`);
 	const environment = await options.provider.get(options.environmentId);
 	if (!environment) return { outcome: "not_found" };
+	const capabilities = retainedCapabilitiesForEnvironment(options.provider.name, providerCapabilities, environment);
 	if (!environment.session) return {
 		outcome: "unverifiable",
 		environment
@@ -4111,23 +4170,392 @@ async function recoverRetainedRun(options) {
 		handle: createRetainedRunHandle(environment, exact.session, exact.controlRef, capabilities, options.now)
 	};
 }
+function retainedRunIntent(options, identity) {
+	const requestedProfileDigest = canonicalCandidateDigest(options.environment.profile);
+	const requestDigest = canonicalCandidateDigest({
+		kind: "retained-run-intent.v1",
+		provider: options.provider.name,
+		idempotencyKey: options.environment.idempotencyKey,
+		turnId: options.turn.turnId,
+		sessionId: identity.sessionId,
+		executionId: identity.executionId,
+		requestedProfileDigest,
+		create: retainedCreateMaterial(options.environment),
+		turn: retainedTurnMaterial(options.turn)
+	});
+	return {
+		phase: "intent",
+		provider: options.provider.name,
+		idempotencyKey: options.environment.idempotencyKey,
+		turnId: options.turn.turnId,
+		sessionId: identity.sessionId,
+		executionId: identity.executionId,
+		runId: `retained-intent-run:${requestDigest.slice(7)}`,
+		requestedProfileDigest,
+		requestDigest
+	};
+}
+function assertExactRetainedRunIntent(received, expected) {
+	if (canonicalCandidateDigest(parseRetainedRunIntent(received)) !== canonicalCandidateDigest(expected)) throw new Error("retained run intent conflicts with replay material");
+}
+function parseRetainedRunIntent(value) {
+	const stable = detachedSnapshot(value, "retained run intent");
+	if (stable === null || typeof stable !== "object" || Array.isArray(stable)) throw new Error("retained run intent is malformed");
+	const record = stable;
+	const allowed = /* @__PURE__ */ new Set([
+		"phase",
+		"provider",
+		"idempotencyKey",
+		"turnId",
+		"sessionId",
+		"executionId",
+		"runId",
+		"requestedProfileDigest",
+		"requestDigest"
+	]);
+	if (Object.keys(record).some((key) => !allowed.has(key))) throw new Error("retained run intent contains unsupported material");
+	if (record.phase !== "intent") throw new Error("retained run intent has an invalid phase");
+	for (const [key, value] of Object.entries(record)) {
+		if (key === "phase") continue;
+		if (typeof value !== "string" || value.length === 0) throw new Error(`retained run intent field "${key}" is invalid`);
+	}
+	assertDigest$1(record.requestedProfileDigest, "retained run intent profile digest");
+	assertDigest$1(record.requestDigest, "retained run intent request digest");
+	return stable;
+}
+function assertDigest$1(value, label) {
+	if (typeof value !== "string" || !/^sha256:[a-f0-9]{64}$/u.test(value)) throw new Error(`${label} is invalid`);
+}
 /** Rebuild a retained-run client without retaining any object from the starter. @stable */
 async function reconnectRetainedRun(options) {
 	const controlRef = AgentExactRunControlRefSchema.parse(options.controlRef);
 	if (controlRef.provider !== options.provider.name) throw new Error(`run provider "${controlRef.provider}" does not match "${options.provider.name}"`);
-	const capabilities = await assertRetainedCapabilities(options.provider);
+	const providerCapabilities = await assertRetainedCapabilities(options.provider);
 	if (!options.provider.get) throw new Error(`provider "${options.provider.name}" cannot reconstruct an environment by id`);
 	const environment = await options.provider.get(controlRef.environmentId);
 	if (!environment) return null;
+	const capabilities = retainedCapabilitiesForEnvironment(options.provider.name, providerCapabilities, environment);
 	const exact = exactSession(environment, controlRef);
 	return createRetainedRunHandle(environment, exact.session, exact.controlRef, capabilities, options.now);
 }
 async function assertRetainedCapabilities(provider) {
 	const capabilities = AgentEnvironmentCapabilitiesSchema.parse(await provider.capabilities());
+	assertRetainedCapabilityRequirements(provider.name, capabilities);
+	return capabilities;
+}
+/**
+* Select the capability document for one concrete environment.
+*
+* A measured environment document is authoritative. An absent document uses
+* the provider document because that provider claims the same guarantee for
+* every environment it creates.
+*/
+function retainedCapabilitiesForEnvironment(providerName, providerCapabilities, environment) {
+	if (environment.capabilities === void 0) return providerCapabilities;
+	const measured = AgentEnvironmentCapabilitiesSchema.parse(environment.capabilities);
+	assertRetainedCapabilityRequirements(providerName, measured);
+	return measured;
+}
+function assertRetainedCapabilityRequirements(providerName, capabilities) {
 	const retained = capabilities.retainedControl;
-	if (retained?.exactRunIdentity !== true || retained.resultIdentity !== true || retained.eventIdentity !== true || retained.cancellationIdempotency !== true || !capabilities.streaming.detach || !capabilities.streaming.replay || !capabilities.streaming.turnIdempotency) throw new Error(`provider "${provider.name}" cannot control a retry-safe retained run`);
+	if (retained?.exactRunIdentity !== true || retained.resultIdentity !== true || retained.eventIdentity !== true || retained.cancellationIdempotency !== true || !capabilities.streaming.detach || !capabilities.streaming.replay || !capabilities.streaming.turnIdempotency) throw new Error(`provider "${providerName}" cannot control a retry-safe retained run`);
+}
+//#endregion
+//#region src/runtime/retained-interactive.ts
+/**
+* Start one retry-safe native coding-agent TUI without dispatching a headless turn.
+* The intent admission is durable before provider.create; the environment and
+* process admissions follow only after their exact provider coordinates exist.
+* @stable
+*/
+async function startRetainedInteractiveRun(options) {
+	options.signal?.throwIfAborted();
+	assertStableText(options.environment.idempotencyKey, "environment idempotency key");
+	assertStableText(options.interactiveIdempotencyKey, "interactive idempotency key");
+	if (typeof options.onAdmission !== "function") throw new Error("startRetainedInteractiveRun requires an awaited onAdmission durability hook");
+	if (!options.provider.get) throw new Error(`provider "${options.provider.name}" cannot reconstruct an environment by id`);
+	const profile = agentProfileSchema.parse(options.environment.profile);
+	if (profile.harness === void 0) throw new Error("retained interactive runs require AgentProfile.harness");
+	const requestedProfileDigest = canonicalAgentProfileDigest(profile);
+	const identity = mintRetainedIdentity(options.environment.idempotencyKey, options.interactiveIdempotencyKey);
+	const intent = interactiveIntent(options, profile, identity);
+	if (options.intent === void 0) await admitDurably(options.onAdmission, intent);
+	else assertExactInteractiveIntent(options.intent, intent);
+	const providerCapabilities = AgentEnvironmentCapabilitiesSchema.parse(await awaitAbortable(Promise.resolve().then(() => options.provider.capabilities()), options.signal));
+	assertInteractiveCapabilities(options.provider.name, providerCapabilities);
+	const environment = await createInteractiveEnvironment(() => options.provider.create({
+		...options.environment,
+		profile,
+		signal: options.signal,
+		metadata: {
+			...options.environment.metadata,
+			retainedIdempotencyKey: options.environment.idempotencyKey,
+			interactiveIdempotencyKey: options.interactiveIdempotencyKey,
+			requestedProfileDigest,
+			interactiveIntentDigest: intent.requestDigest,
+			interactiveRunId: intent.runId,
+			sessionId: identity.sessionId,
+			executionId: identity.executionId
+		}
+	}), options.signal);
+	let capabilities;
+	try {
+		assertExactEnvironment(options.provider.name, environment);
+		options.signal?.throwIfAborted();
+		capabilities = interactiveCapabilitiesForEnvironment(options.provider.name, providerCapabilities, environment);
+		assertInteractiveMethods(options.provider.name, environment);
+	} catch (error) {
+		await destroyUnusedEnvironment(environment, error);
+		throw error;
+	}
+	const request = interactiveRequest(options, environment, profile, requestedProfileDigest, identity);
+	await admitDurably(options.onAdmission, {
+		phase: "interactive_environment",
+		provider: options.provider.name,
+		environmentId: environment.id,
+		idempotencyKey: options.environment.idempotencyKey,
+		interactiveIdempotencyKey: options.interactiveIdempotencyKey,
+		request
+	});
+	const ref = exactStartedRef(request, await startInteractiveProcess(environment, () => environment.startInteractive(request, { signal: options.signal }), options.signal));
+	await admitDurably(options.onAdmission, {
+		phase: "interactive_started",
+		idempotencyKey: options.environment.idempotencyKey,
+		interactiveIdempotencyKey: options.interactiveIdempotencyKey,
+		ref
+	});
+	return createRetainedInteractiveRunHandle(environment, ref, capabilities, request);
+}
+/** Retry one exact start after its provider response may have been lost. @stable */
+async function recoverRetainedInteractiveRun(options) {
+	options.signal?.throwIfAborted();
+	if (typeof options.onAdmission !== "function") throw new Error("recoverRetainedInteractiveRun requires an awaited onAdmission durability hook");
+	const admission = options.admission;
+	if (admission.provider !== options.provider.name) throw new Error("interactive admission belongs to another provider");
+	if (admission.phase === "interactive_intent") {
+		if (options.replay === void 0) throw new Error("recoverRetainedInteractiveRun requires the original start material for an interactive intent");
+		return startRetainedInteractiveRun({
+			provider: options.provider,
+			...options.replay,
+			intent: admission,
+			onAdmission: options.onAdmission,
+			signal: options.signal
+		});
+	}
+	const request = exactRecoveryRequest(admission);
+	const { environment, capabilities } = await reconstructEnvironment(options.provider, admission.environmentId, options.signal);
+	if (!environment || !capabilities) return null;
+	const ref = exactStartedRef(request, await awaitAbortable(Promise.resolve().then(() => environment.startInteractive(request, { signal: options.signal })), options.signal));
+	await admitDurably(options.onAdmission, {
+		phase: "interactive_started",
+		idempotencyKey: admission.idempotencyKey,
+		interactiveIdempotencyKey: admission.interactiveIdempotencyKey,
+		ref
+	});
+	return createRetainedInteractiveRunHandle(environment, ref, capabilities, request);
+}
+function exactRecoveryRequest(admission) {
+	assertStableText(admission.environmentId, "interactive environment id");
+	assertStableText(admission.idempotencyKey, "environment idempotency key");
+	assertStableText(admission.interactiveIdempotencyKey, "interactive idempotency key");
+	const request = exactAgentInteractiveSessionStart(admission.request);
+	const identity = mintRetainedIdentity(admission.idempotencyKey, admission.interactiveIdempotencyKey);
+	if (request.run.provider !== admission.provider || request.run.environmentId !== admission.environmentId || request.run.sessionId !== identity.sessionId || request.run.executionId !== identity.executionId) throw new Error("interactive admission does not match its recovery coordinates");
+	return request;
+}
+/** Rebuild controls for one exact provider-owned coding-agent process. @stable */
+async function reconnectRetainedInteractiveRun(options) {
+	options.signal?.throwIfAborted();
+	const ref = AgentInteractiveSessionRefSchema.parse(options.ref);
+	if (ref.run.provider !== options.provider.name) throw new Error("interactive session reference belongs to another provider");
+	const { environment, capabilities } = await reconstructEnvironment(options.provider, ref.run.environmentId, options.signal);
+	if (!environment || !capabilities) return null;
+	const handle = createRetainedInteractiveRunHandle(environment, ref, capabilities);
+	await handle.status({ signal: options.signal });
+	return handle;
+}
+function interactiveRequest(options, environment, profile, requestedProfileDigest, identity) {
+	const start = {
+		profile,
+		requestedProfileDigest,
+		...options.initialPrompt === void 0 ? {} : { initialPrompt: options.initialPrompt },
+		...options.cwd === void 0 ? {} : { cwd: options.cwd },
+		...options.cols === void 0 ? {} : { cols: options.cols },
+		...options.rows === void 0 ? {} : { rows: options.rows }
+	};
+	return exactAgentInteractiveSessionStart({
+		run: agentInteractiveSessionRunRef({
+			provider: options.provider.name,
+			environmentId: environment.id,
+			...identity
+		}, start),
+		...start
+	});
+}
+function interactiveIntent(options, profile, identity) {
+	const requestedProfileDigest = canonicalAgentProfileDigest(profile);
+	const requestDigest = canonicalCandidateDigest({
+		kind: "retained-interactive-intent.v1",
+		provider: options.provider.name,
+		idempotencyKey: options.environment.idempotencyKey,
+		interactiveIdempotencyKey: options.interactiveIdempotencyKey,
+		sessionId: identity.sessionId,
+		executionId: identity.executionId,
+		requestedProfileDigest,
+		create: retainedCreateMaterial(options.environment),
+		start: sanitizedStartMaterial(options)
+	});
+	return {
+		phase: "interactive_intent",
+		provider: options.provider.name,
+		idempotencyKey: options.environment.idempotencyKey,
+		interactiveIdempotencyKey: options.interactiveIdempotencyKey,
+		sessionId: identity.sessionId,
+		executionId: identity.executionId,
+		runId: `interactive-intent-run:${requestDigest.slice(7)}`,
+		requestedProfileDigest,
+		requestDigest
+	};
+}
+function sanitizedStartMaterial(options) {
+	return {
+		...options.initialPrompt === void 0 ? {} : { initialPrompt: options.initialPrompt },
+		...options.cwd === void 0 ? {} : { cwd: options.cwd },
+		...options.cols === void 0 ? {} : { cols: options.cols },
+		...options.rows === void 0 ? {} : { rows: options.rows }
+	};
+}
+function assertExactInteractiveIntent(received, expected) {
+	if (canonicalCandidateDigest(parseInteractiveIntent(received)) !== canonicalCandidateDigest(expected)) throw new Error("interactive intent conflicts with replay material");
+}
+function parseInteractiveIntent(value) {
+	const stable = detachedSnapshot(value, "interactive intent");
+	if (stable === null || typeof stable !== "object" || Array.isArray(stable)) throw new Error("interactive intent is malformed");
+	const record = stable;
+	const allowed = /* @__PURE__ */ new Set([
+		"phase",
+		"provider",
+		"idempotencyKey",
+		"interactiveIdempotencyKey",
+		"sessionId",
+		"executionId",
+		"runId",
+		"requestedProfileDigest",
+		"requestDigest"
+	]);
+	if (Object.keys(record).some((key) => !allowed.has(key))) throw new Error("interactive intent contains unsupported material");
+	if (record.phase !== "interactive_intent") throw new Error("interactive intent has an invalid phase");
+	for (const [key, value] of Object.entries(record)) {
+		if (key === "phase") continue;
+		if (typeof value !== "string" || value.length === 0) throw new Error(`interactive intent field "${key}" is invalid`);
+	}
+	assertDigest(record.requestedProfileDigest, "interactive intent profile digest");
+	assertDigest(record.requestDigest, "interactive intent request digest");
+	return stable;
+}
+function assertDigest(value, label) {
+	if (typeof value !== "string" || !/^sha256:[a-f0-9]{64}$/u.test(value)) throw new Error(`${label} is invalid`);
+}
+async function reconstructEnvironment(provider, environmentId, signal) {
+	if (!provider.get) throw new Error(`provider "${provider.name}" cannot reconstruct an environment by id`);
+	const providerCapabilities = AgentEnvironmentCapabilitiesSchema.parse(await awaitAbortable(Promise.resolve().then(() => provider.capabilities()), signal));
+	assertInteractiveCapabilities(provider.name, providerCapabilities);
+	const environment = await awaitAbortable(Promise.resolve().then(() => provider.get(environmentId, { signal })), signal);
+	if (!environment) return {
+		environment: null,
+		capabilities: null
+	};
+	assertExactEnvironment(provider.name, environment, environmentId);
+	const capabilities = interactiveCapabilitiesForEnvironment(provider.name, providerCapabilities, environment);
+	assertInteractiveMethods(provider.name, environment);
+	return {
+		environment,
+		capabilities
+	};
+}
+function exactStartedRef(request, value) {
+	const stableRequest = detachedSnapshot(request, "interactive start binding request");
+	let ref;
+	try {
+		ref = AgentInteractiveSessionRefSchema.parse(value);
+	} catch (error) {
+		throw new RetainedInteractiveBindingError(stableRequest, {}, { cause: error });
+	}
+	if (!agentInteractiveSessionRefMatchesStart(request, ref)) throw new RetainedInteractiveBindingError(stableRequest, detachedSnapshot({ ref: detachedSnapshot(ref, "interactive provider start reference") }, "interactive provider start result"), { cause: /* @__PURE__ */ new Error("provider started another interactive run than requested") });
+	return freezeInteractiveRef(ref);
+}
+function assertExactEnvironment(providerName, environment, environmentId) {
+	if (environment.provider !== providerName || environmentId && environment.id !== environmentId) throw new Error("provider returned another interactive environment");
+	assertStableText(environment.id, "interactive environment id");
+}
+function interactiveCapabilitiesForEnvironment(providerName, providerCapabilities, environment) {
+	const capabilities = environment.capabilities === void 0 ? providerCapabilities : AgentEnvironmentCapabilitiesSchema.parse(environment.capabilities);
+	assertInteractiveCapabilities(providerName, capabilities);
 	return capabilities;
 }
+function assertInteractiveCapabilities(providerName, capabilities) {
+	const interactive = capabilities.interactiveAgent;
+	if (!interactive?.start || !interactive.control || !interactive.status || !interactive.attach || !interactive.reattach || !interactive.sendPrompt || !interactive.input || !interactive.resize || !interactive.stop) throw new Error(`provider "${providerName}" cannot control an exact interactive agent`);
+}
+function assertInteractiveMethods(providerName, environment) {
+	if (!environment.startInteractive || !environment.interactive) throw new Error(`provider "${providerName}" exposes incomplete interactive agent controls`);
+}
+async function destroyUnusedEnvironment(environment, cause) {
+	try {
+		await destroyInteractiveEnvironment(environment);
+	} catch (cleanupError) {
+		throw new AggregateError([cause, cleanupError], "interactive environment was invalid and could not be destroyed");
+	}
+}
+//#endregion
+//#region src/runtime/retained-interactive-control.ts
+const MAX_GENERATION_CONFLICTS = 8;
+/**
+* Acquire provider-issued write authority without reading authority from status.
+*
+* A new coordinator starts at generation zero. If another claim already exists,
+* the provider returns its public generation and this helper retries one new
+* compare-and-swap operation. Every generation has a deterministic operation
+* identifier, so retrying after an ambiguous response cannot create two claims.
+* @stable
+*/
+async function claimRetainedInteractiveControl(options) {
+	const expected = options.expectedGeneration ?? 0;
+	if (!Number.isSafeInteger(expected) || expected < 0) throw new Error("interactive control expectedGeneration must be a non-negative integer");
+	let generation = expected;
+	for (let conflict = 0; conflict <= MAX_GENERATION_CONFLICTS; conflict += 1) {
+		if (options.signal?.aborted) throw abortError(options.signal.reason);
+		const material = {
+			operationId: controlClaimOperationId(options.handle, options.holderId, generation),
+			ref: options.handle.ref,
+			holderId: options.holderId,
+			expectedGeneration: generation
+		};
+		const acknowledgement = await options.handle.claimControl({
+			...material,
+			requestDigest: agentInteractiveSessionControlClaimRequestDigest(material)
+		}, options.signal === void 0 ? void 0 : { signal: options.signal });
+		if (acknowledgement.status === "accepted" || acknowledgement.status === "replayed") {
+			const control = acknowledgement.control;
+			if (control === void 0) throw new Error("provider accepted interactive control without returning its claim");
+			if (Date.parse(control.expiresAt) <= Date.now()) throw new Error("provider returned an expired interactive control claim");
+			return control;
+		}
+		if (acknowledgement.status !== "conflict" || acknowledgement.conflictReason !== "generation_mismatch") throw new Error(acknowledgement.status === "unknown" ? "interactive control claim outcome is unknown; retry the same acquisition" : "interactive control claim operation conflicts with different request material");
+		const current = acknowledgement.currentGeneration;
+		if (current === void 0 || current <= generation) throw new Error("provider returned a non-advancing interactive control generation");
+		generation = current;
+	}
+	throw new Error("interactive control changed too often to acquire safely");
+}
+function controlClaimOperationId(handle, holderId, expectedGeneration) {
+	return `interactive-claim-${canonicalCandidateDigest({
+		kind: "retained-interactive-control-claim.v1",
+		ref: handle.ref,
+		holderId,
+		expectedGeneration
+	}).slice(7, 47)}`;
+}
 //#endregion
 //#region src/runtime/run-benchmark.ts
 /**
@@ -6670,6 +7098,6 @@ function tail(s) {
 	return s.slice(-400);
 }
 //#endregion
-export { FileCorpus as $, pickChampion as A, renderLeaderboardMarkdown as At, runBenchmark as B, envKeyProvider as Bt, analyzeTrace as C, completionAuthorizes as Ct, chatWorkerSeam as D, leaderboard as Dt, chatTransportExecutor as E, stopSentinel as Et, strategyAuthorContract as F, McpSpawnFault as Ft, promotionGate as G, recoverRetainedRun as H, resolveMcpServerLaunch as Ht, strategyAuthorSystemPrompt as I, connectStdioMcp as It, definePersona as J, equalKOnCost as K, SandboxRunAbortError as L, materializeLocalMcp as Lt, selectChampion as M, renderPairwiseMarkdown as Mt, assertStrategyContract as N, auditIntent as Nt, createChatSessionStore as O, pairwiseSignificance as Ot, authorStrategy as P, defaultAuditorInstruction as Pt, registerShape as Q, openSandboxRun as R, createMcpEnvironment as Rt, withUntrackedArtifacts as S, superviseDispatch as St, runCoderChecks as T, sentinelCompletion as Tt, startRetainedRun as U, resolveSecretEnv as Ut, reconnectRetainedRun as V, mcpSecretEnvMetadataKey as Vt, startRetainedRunInEnvironment as W, secretEnvOfMcpServer as Wt, builtinShapes as X, runPersonified as Y, createShapeRegistry as Z, VERIFY_TAIL_CHARS as _, resolveSandboxClient as _t, localShell as a, panel as at, settledWorkerOut as b, loopCampaignDispatch as bt, createVerifierEnvironment as c, verify as ct, harvestSurfaceDiffs as d, buildSteerContext as dt, InMemoryCorpus as et, failuresAnalyst as f, createScopeAnalyst as ft, NOTE_MAX_CHARS as g, defineLeaderboard as gt, EVIDENCE_MAX_CHARS as h, harvestCorpus as ht, jjWorkspace as i, loopUntil as it, runStrategyEvolution as j, renderLeaderboardSvg as jt, discriminatingMeans as k, renderLeaderboardHtml as kt, boxSurfaceReader as l, widen as lt, worktreeFanout as m, inProcessSandboxClient as mt, makeFinding$1 as n, fanout as nt, runInWorkspace as o, pipeline as ot, superviseSurface as p, registryScopeAnalyst as pt, trajectoryReport as q, gitWorkspace as r, flatWidenGate as rt, createWaterfallCollector as s, selectValidWinner as st, computeFindingId$1 as t, renderCorpusToInstructions as tt, fsSurfaceReader as u, assertTraceDerivedFindings as ut, closingWorkerNote as v, localSandboxClient as vt, patchDelivered as w, deterministicCompletion as wt, copyUntrackedIntoClone as x, loopDispatch as xt, composeWorkerEvidence as y, inlineSandboxClient as yt, printBenchmarkReport as z, sanitizeMcpToolSchema as zt };
+export { runPersonified as $, pickChampion as A, stopSentinel as At, runBenchmark as B, connectStdioMcp as Bt, analyzeTrace as C, inlineSandboxClient as Ct, chatWorkerSeam as D, completionAuthorizes as Dt, chatTransportExecutor as E, superviseDispatch as Et, strategyAuthorContract as F, renderLeaderboardSvg as Ft, reconnectRetainedRun as G, mcpSecretEnvMetadataKey as Gt, reconnectRetainedInteractiveRun as H, createMcpEnvironment as Ht, strategyAuthorSystemPrompt as I, renderPairwiseMarkdown as It, startRetainedRunInEnvironment as J, secretEnvOfMcpServer as Jt, recoverRetainedRun as K, resolveMcpServerLaunch as Kt, SandboxRunAbortError as L, auditIntent as Lt, selectChampion as M, pairwiseSignificance as Mt, assertStrategyContract as N, renderLeaderboardHtml as Nt, createChatSessionStore as O, deterministicCompletion as Ot, authorStrategy as P, renderLeaderboardMarkdown as Pt, definePersona as Q, openSandboxRun as R, defaultAuditorInstruction as Rt, withUntrackedArtifacts as S, localSandboxClient as St, runCoderChecks as T, loopDispatch as Tt, recoverRetainedInteractiveRun as U, sanitizeMcpToolSchema as Ut, claimRetainedInteractiveControl as V, materializeLocalMcp as Vt, startRetainedInteractiveRun as W, envKeyProvider as Wt, equalKOnCost as X, promotionGate as Y, trajectoryReport as Z, VERIFY_TAIL_CHARS as _, registryScopeAnalyst as _t, localShell as a, renderCorpusToInstructions as at, settledWorkerOut as b, defineLeaderboard as bt, createVerifierEnvironment as c, loopUntil as ct, harvestSurfaceDiffs as d, selectValidWinner as dt, builtinShapes as et, failuresAnalyst as f, verify as ft, NOTE_MAX_CHARS as g, createScopeAnalyst as gt, EVIDENCE_MAX_CHARS as h, buildSteerContext as ht, jjWorkspace as i, InMemoryCorpus as it, runStrategyEvolution as j, leaderboard as jt, discriminatingMeans as k, sentinelCompletion as kt, boxSurfaceReader as l, panel as lt, worktreeFanout as m, assertTraceDerivedFindings as mt, makeFinding$1 as n, registerShape as nt, runInWorkspace as o, fanout as ot, superviseSurface as p, widen as pt, startRetainedRun as q, resolveSecretEnv as qt, gitWorkspace as r, FileCorpus as rt, createWaterfallCollector as s, flatWidenGate as st, computeFindingId$1 as t, createShapeRegistry as tt, fsSurfaceReader as u, pipeline as ut, closingWorkerNote as v, inProcessSandboxClient as vt, patchDelivered as w, loopCampaignDispatch as wt, copyUntrackedIntoClone as x, resolveSandboxClient as xt, composeWorkerEvidence as y, harvestCorpus as yt, printBenchmarkReport as z, McpSpawnFault as zt };
 
-//# sourceMappingURL=runtime-CUpB4rEP.js.map
+//# sourceMappingURL=runtime-tTA2iCZQ.js.map