@tangle-network/agent-runtime 0.197.1 → 0.198.1

package/dist/{structural-rollout-DPbZWgEm.js → structural-rollout-D__lmWXe.js}

@@ -1,11 +1,1104 @@
-import { n as streamAgentTurn, t as collectAgentTurn } from "./stream-agent-turn-Dt5mZpc3.js";
-import { a as executableAgentProfileSnapshot } from "./jsonl-file-BEpaEYjT.js";
-import { c as profileModelExecutionSettings, i as concreteModelId, o as enforceTokenLimits, t as assertExecutableAgentProfile } from "./model-policy-DKDyr-fc.js";
-import { Ht as InMemorySpawnJournal, Vt as InMemoryResultBlobStore, a as createSupervisor, h as withDriverExecutor, lt as createExecutor, mn as observedModelMatchesDeclared, ot as captureReusableExecutorConfig, ut as createExecutorRegistry } from "./redact-Cbl2O-4N.js";
-import { agentProfileSchema, canonicalAgentProfileDigest, canonicalCandidateDigest } from "@tangle-network/agent-interface";
-import { costForTokenPricing, makeProposalFinding } from "@tangle-network/agent-eval";
+import { $r as executableAgentProfileSnapshot, Br as knownExecutionBindingReceipt, Kr as runtimeOwnedExecutorExecutionBinding, Lr as authoredProfileDigest, Qr as unknownMaterializationReceipt, Rt as InMemoryResultBlobStore, Vr as knownMaterializationReceipt, Yr as runtimeOwnedPendingExecutorMaterialization, Zr as unknownExecutionBindingReceipt, a as createSupervisor, ci as promptOptionsFromAgentTurnInput, f as withDriverExecutor, ii as readSandboxOutcome, li as providerMessageText, oi as awaitAbortable, ot as createExecutor, qr as runtimeOwnedExecutorMaterialization, ri as projectSandboxOutcome, rt as captureReusableExecutorConfig, si as promptFromAgentTurnInput, st as createExecutorRegistry, un as observedModelMatchesDeclared, zt as InMemorySpawnJournal } from "./redact-CVyxp2AU.js";
+import { m as ValidationError, p as SessionMismatchError, r as BackendTransportError } from "./errors-DodWX-cb.js";
+import { c as mapSandboxToolEvent, i as createSandboxUsageLedger, n as canonicalStreamEventFromSandboxEvent, o as isSandboxTerminalEvent, r as createSandboxToolPartState, s as mapSandboxEvent } from "./sandbox-events-DbC2WKKS.js";
+import { c as profileModelExecutionSettings, i as concreteModelId, l as profileProviderModel, o as enforceTokenLimits, s as profileBridgeWireModel, t as assertExecutableAgentProfile } from "./model-policy-DKDyr-fc.js";
+import { agentProfileSchema, canonicalAgentProfileDigest, canonicalCandidateDigest, renderInputPartsAsText } from "@tangle-network/agent-interface";
+import { costForTokenPricing, makeProposalFinding, scoreKnowledgeReadiness } from "@tangle-network/agent-eval";
+import { createAgentRunOutcomeTracker } from "@tangle-network/sandbox/runtime";
 import { randomBytes } from "node:crypto";
 import { assertProposalFindings } from "@tangle-network/agent-eval/analyst";
+//#region src/sessions.ts
+/**
+*
+* Session helpers + an in-memory `RuntimeSessionStore` implementation suitable
+* for tests, scratch processes, and per-request scratch storage in serverless
+* runtimes. Durable stores (D1, postgres, Durable Objects) implement the same
+* interface from `./types`.
+*
+* @stable
+*/
+/** @internal */
+function newRuntimeSession(backend, requestedId, metadata) {
+	const now = nowIso();
+	return {
+		id: requestedId || crypto.randomUUID(),
+		backend,
+		status: "active",
+		createdAt: now,
+		updatedAt: now,
+		metadata
+	};
+}
+/** @internal */
+function touchSession(session) {
+	return {
+		...session,
+		updatedAt: nowIso()
+	};
+}
+/** @internal */
+function nowIso() {
+	return (/* @__PURE__ */ new Date()).toISOString();
+}
+/** Start or resume one backend session and persist its current identity. @internal */
+async function startOrResumeRuntimeSession(options) {
+	const existing = options.resume && options.sessionId ? await options.store?.get(options.sessionId) : void 0;
+	if (!existing) {
+		const input = resolveSessionInput(options.input);
+		const session = options.backend.start ? await options.backend.start(input, {
+			...options.context,
+			requestedSessionId: options.sessionId
+		}) : newRuntimeSession(options.backend.kind, options.sessionId);
+		assertSessionBackend(session, options.backend.kind);
+		options.validateSession?.(session);
+		await options.store?.put(session);
+		return {
+			session,
+			input,
+			resumed: false
+		};
+	}
+	assertSessionBackend(existing, options.backend.kind);
+	const input = resolveSessionInput(options.backend.resume !== void 0 ? options.continuationInput ?? options.input : options.input);
+	const session = options.backend.resume ? await options.backend.resume(existing, input, options.context) : touchSession({
+		...existing,
+		status: "active"
+	});
+	assertSessionBackend(session, options.backend.kind);
+	options.validateSession?.(session);
+	await options.store?.put(session);
+	return {
+		session,
+		input,
+		resumed: true
+	};
+}
+function resolveSessionInput(input) {
+	return typeof input === "function" ? input() : input;
+}
+function assertSessionBackend(session, backend) {
+	if (session.backend !== backend) throw new SessionMismatchError(session.backend, backend);
+}
+/** In-memory `RuntimeSessionStore` for single-process use and tests. @stable */
+var InMemoryRuntimeSessionStore = class {
+	sessions = /* @__PURE__ */ new Map();
+	events = /* @__PURE__ */ new Map();
+	get(sessionId) {
+		return this.sessions.get(sessionId);
+	}
+	put(session) {
+		this.sessions.set(session.id, session);
+	}
+	appendEvent(sessionId, event) {
+		const existing = this.events.get(sessionId) ?? [];
+		existing.push(event);
+		this.events.set(sessionId, existing);
+	}
+	listEvents(sessionId) {
+		return [...this.events.get(sessionId) ?? []];
+	}
+};
+//#endregion
+//#region src/backends.ts
+/**
+* Provider-neutral backend adapters for `runAgentTaskStream`.
+*
+* Model inference is deliberately absent. Paid model work enters the Runtime executor with an
+* exact `AgentProfile`; these adapters only normalize a caller-owned iterable or sandbox stream.
+*
+* @stable
+*/
+/** Wrap any custom async-iterable stream into a typed `AgentExecutionBackend`. @stable */
+function createIterableBackend(options) {
+	return options;
+}
+/** Build an `AgentExecutionBackend` backed by a sandbox/sidecar `streamPrompt` call. @stable */
+function createSandboxPromptBackend(options) {
+	const kind = options.kind ?? "sandbox";
+	return {
+		kind,
+		async start(input, context) {
+			const box = await options.getBox(input, context);
+			return newRuntimeSession(kind, options.getSessionId?.(box, input) ?? context.requestedSessionId, { resumable: true });
+		},
+		resume(session) {
+			return touchSession({
+				...session,
+				status: "active"
+			});
+		},
+		async *stream(input, context) {
+			const box = await options.getBox(input, context);
+			const message = input.message ?? input.messages?.at(-1)?.content ?? providerMessageText(input.providerOptions) ?? context.task.intent;
+			for await (const event of options.streamPrompt(box, message, context)) {
+				const mapped = options.mapEvent?.(event, context) ?? mapCommonBackendEvent(event, context);
+				if (mapped) yield mapped;
+			}
+		}
+	};
+}
+/** @internal */
+function normalizeBackendStreamEvent(event, task, session) {
+	if ("task" in event && event.task && "session" in event && event.session && "timestamp" in event && event.timestamp) return event;
+	return {
+		...event,
+		task: "task" in event && event.task ? event.task : task,
+		session: "session" in event && event.session ? event.session : session,
+		timestamp: "timestamp" in event && event.timestamp ? event.timestamp : nowIso()
+	};
+}
+function mapCommonBackendEvent(event, context) {
+	if (!event || typeof event !== "object") return void 0;
+	const record = event;
+	const type = String(record.type ?? "");
+	const data = record.data && typeof record.data === "object" ? record.data : record;
+	if (type === "message.part.updated" || type === "text_delta" || type === "delta") {
+		const part = data.part;
+		const partText = part !== void 0 && typeof part === "object" && (part.type === "text" || part.type === void 0) ? stringValue(part.text) : void 0;
+		const text = stringValue(data.text) ?? stringValue(data.delta) ?? stringValue(record.text) ?? partText;
+		return text ? {
+			type: "text_delta",
+			task: context.task,
+			session: context.session,
+			text,
+			timestamp: nowIso()
+		} : void 0;
+	}
+	if (type === "reasoning_delta") {
+		const text = stringValue(data.text) ?? stringValue(record.text);
+		return text ? {
+			type: "reasoning_delta",
+			task: context.task,
+			session: context.session,
+			text,
+			timestamp: nowIso()
+		} : void 0;
+	}
+	if (type === "tool_call") return {
+		type: "tool_call",
+		task: context.task,
+		session: context.session,
+		toolName: stringValue(data.name) ?? stringValue(record.toolName) ?? "tool",
+		toolCallId: stringValue(data.id) ?? stringValue(record.toolCallId),
+		args: data.args ?? data.input ?? record.args,
+		timestamp: nowIso()
+	};
+	if (type === "tool_result") return {
+		type: "tool_result",
+		task: context.task,
+		session: context.session,
+		toolName: stringValue(data.name) ?? stringValue(record.toolName) ?? "tool",
+		toolCallId: stringValue(data.id) ?? stringValue(record.toolCallId),
+		result: data.result ?? data.output ?? record.result,
+		timestamp: nowIso()
+	};
+	if (type === "artifact") {
+		const artifactId = stringValue(data.artifactId) ?? stringValue(data.id) ?? stringValue(record.artifactId);
+		if (!artifactId) return void 0;
+		return {
+			type: "artifact",
+			task: context.task,
+			session: context.session,
+			artifactId,
+			name: stringValue(data.name) ?? stringValue(record.name),
+			mimeType: stringValue(data.mimeType) ?? stringValue(record.mimeType),
+			uri: stringValue(data.uri) ?? stringValue(record.uri),
+			content: stringValue(data.content) ?? stringValue(data.body) ?? stringValue(record.content),
+			metadata: data.metadata && typeof data.metadata === "object" ? data.metadata : void 0,
+			timestamp: nowIso()
+		};
+	}
+	if (type === "proposal_created" || type === "proposal" || type === "filing") {
+		const proposalId = stringValue(data.proposalId) ?? stringValue(data.id) ?? stringValue(record.proposalId);
+		if (!proposalId) return void 0;
+		const status = stringValue(data.status) ?? stringValue(record.status);
+		return {
+			type: "proposal_created",
+			task: context.task,
+			session: context.session,
+			proposalId,
+			title: stringValue(data.title) ?? stringValue(record.title) ?? proposalId,
+			status: status === "pending" || status === "approved" || status === "rejected" ? status : void 0,
+			content: stringValue(data.content) ?? stringValue(data.body) ?? stringValue(record.content),
+			timestamp: nowIso()
+		};
+	}
+	if (type === "result" || type === "final") {
+		const text = stringValue(data.finalText) ?? stringValue(data.text) ?? stringValue(record.text);
+		return text ? {
+			type: "text_delta",
+			task: context.task,
+			session: context.session,
+			text,
+			timestamp: nowIso()
+		} : void 0;
+	}
+}
+function stringValue(value) {
+	return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+//#endregion
+//#region src/runtime/stream-agent-turn.ts
+/**
+* `streamAgentTurn` — the ONE run-a-turn event-stream contract over every
+* execution substrate: a sandbox box (`SandboxInstance.streamPrompt`), a
+* one-shot Runtime-owned `Executor` (cli-bridge / router / sandbox, via
+* `ExecutorFactory`), and an in-process `AgentExecutionBackend`.
+*
+* One function, one vocabulary: every backend kind yields the existing
+* `RuntimeStreamEvent` union incrementally and ALWAYS terminates with a
+* `final` event whose `text` is the turn's final text and whose
+* `metadata.tokenUsage` / `metadata.costUsd` / `metadata.model` carry the
+* turn's metered usage. `collectAgentTurn` drains a stream into that terminal
+* summary plus the full event list.
+*
+* This is a UNIFICATION seam, not a new stream parser — each kind is a thin
+* adapter over code that already exists and is already hardened:
+*   - `box`      — `mapSandboxEvent` projects the sandbox event stream and one
+*                  `SandboxUsageLedger` (sandbox-events.ts) meters it, so a harness
+*                  that reports usage only in its own event is counted once per turn;
+*                  its requested profile is explicitly recorded as unverified because
+*                  the box already exists.
+*   - `executor` — Runtime materializes the exact `AgentProfile`, records its
+*                  identity receipts, drives the executor once, and tears it
+*                  down after capturing the terminal artifact.
+*   - `chat`     — the backend's own `stream()` surface, normalized by
+*                  `normalizeBackendStreamEvent`; its requested profile is likewise
+*                  unverified because an arbitrary backend cannot attest its setup.
+*
+* Distinct from `openSandboxRun` (box-only, session resume over one persistent
+* artifact, raw `SandboxEvent` deliverables) and from `runAgentTaskStream`
+* (full task lifecycle: knowledge preflight, session store, resume). This is
+* the minimal turn primitive underneath both worlds: prompt in, one normalized
+* event stream out, terminal result+usage guaranteed on every non-thrown path.
+*
+* Stream envelope: `backend_start` → incremental events → (`backend_error` on
+* failure) → `final`. A caller-initiated abort terminates with
+* `final.status: 'aborted'`; an expired `timeoutMs` deadline with
+* `final.status: 'failed'` — so cancellation stays distinguishable from a
+* blown deadline.
+*
+* Mid-stream lifecycle work needs NO extra API: the generator is pull-based,
+* so the producer is suspended between yields and resumes only when the caller
+* pulls again. A consumer can therefore run arbitrary async work between
+* events — sync state on each `tool_result`, decide a no-op retry after
+* draining, run a pre-`done` flush when it receives `final` and BEFORE it
+* forwards its own terminal event downstream. The interleaving is guaranteed
+* (and locked by test): nothing is produced past the event the caller is
+* holding.
+*
+* @stable
+*/
+function turnIntent(input) {
+	if (input.prompt !== void 0) return input.prompt;
+	if (input.parts !== void 0) return renderInputPartsAsText(input.parts);
+	return providerMessageText(input.providerOptions) ?? "structured agent turn";
+}
+function turnBackendInput(task, input) {
+	return {
+		task,
+		...input.prompt === void 0 ? {} : { message: input.prompt },
+		...input.parts === void 0 ? {} : { parts: structuredClone(input.parts) },
+		...input.interactions === void 0 ? {} : { interactions: input.interactions },
+		...input.providerOptions === void 0 ? {} : { providerOptions: structuredClone(input.providerOptions) }
+	};
+}
+function executorEvidence(executor, profile, attemptId) {
+	const profileDigest = authoredProfileDigest(profile);
+	const declaration = runtimeOwnedExecutorMaterialization(executor);
+	if (!profileDigest || !declaration) {
+		const materialization = unknownMaterializationReceipt({
+			...profileDigest ? { authoredProfileDigest: profileDigest } : {},
+			runtime: executor.runtime,
+			reason: declaration ? "invalid-executor-report" : "executor-did-not-report"
+		});
+		return {
+			materialization,
+			executionBinding: unknownExecutionBindingReceipt(materialization, attemptId, declaration ? "invalid-executor-report" : "executor-did-not-report")
+		};
+	}
+	try {
+		const materialization = knownMaterializationReceipt({
+			authoredProfileDigest: profileDigest,
+			runtime: executor.runtime,
+			declaration
+		});
+		const binding = runtimeOwnedExecutorExecutionBinding(executor);
+		if (!binding || binding.attemptId !== attemptId) throw new Error("executor attempt id mismatch");
+		return {
+			materialization,
+			executionBinding: knownExecutionBindingReceipt(materialization, binding)
+		};
+	} catch {
+		const materialization = unknownMaterializationReceipt({
+			authoredProfileDigest: profileDigest,
+			runtime: executor.runtime,
+			reason: "invalid-executor-report"
+		});
+		return {
+			materialization,
+			executionBinding: unknownExecutionBindingReceipt(materialization, attemptId, "invalid-executor-report")
+		};
+	}
+}
+/** Exact turns require the model-bearing profile to be the sole behavioral authority. Runtime
+* checks the trusted declaration before execution so a seam fallback cannot hide behind the same
+* profile digest. */
+function assertExactExecutorDeclaration(executor, profile) {
+	const profileModel = profileProviderModel(profile);
+	if (!profileModel) throw new ValidationError("streamAgentTurn: exact AgentProfile.model.default must name the concrete model");
+	const declaration = runtimeOwnedExecutorMaterialization(executor) ?? runtimeOwnedPendingExecutorMaterialization(executor)?.declaration;
+	if (!declaration) return;
+	if (declaration.model.status !== "known") throw new ValidationError("streamAgentTurn: exact executor did not materialize a known model identity");
+	if (declaration.backend === "router" || declaration.backend === "router-tools") {
+		const plan = declaration.plan;
+		if (declaration.model.id !== profileModel) throw new ValidationError("streamAgentTurn: Router executor model differs from AgentProfile.model.default");
+		if (plan.configuredModel !== null && plan.configuredModel !== void 0 && concreteModelId(String(plan.configuredModel)) !== profileModel) throw new ValidationError("streamAgentTurn: configured Router model conflicts with AgentProfile.model.default");
+		const expectedEffort = profile.model?.reasoningEffort ?? null;
+		if (plan.configuredReasoningEffort !== null && plan.configuredReasoningEffort !== void 0 && plan.configuredReasoningEffort !== expectedEffort) throw new ValidationError("streamAgentTurn: configured Router reasoning conflicts with AgentProfile.model.reasoningEffort");
+		if ((plan.reasoningEffort ?? null) !== expectedEffort) throw new ValidationError("streamAgentTurn: Router reasoning effort must come from AgentProfile.model.reasoningEffort");
+	}
+	if (declaration.backend === "bridge" || declaration.backend === "bridge-worktree") {
+		const expectedWireModel = profileBridgeWireModel(profile);
+		if (!expectedWireModel || declaration.model.id !== expectedWireModel) throw new ValidationError("streamAgentTurn: bridge executor model differs from the AgentProfile harness/provider/model wire id");
+		const plan = declaration.plan;
+		if (plan.configuredModel !== null && plan.configuredModel !== void 0 && concreteModelId(String(plan.configuredModel)) !== expectedWireModel) throw new ValidationError("streamAgentTurn: configured bridge model conflicts with the AgentProfile harness/provider/model wire id");
+	}
+}
+function turnProvenance(startedAt, timeoutMs, profileDigest, taskDigest, materialization, executionBinding, correlation) {
+	const endedAt = Date.now();
+	return {
+		...profileDigest ? { identity: {
+			profileDigest,
+			taskDigest,
+			...Object.keys(correlation).length > 0 ? { correlation } : {}
+		} } : { taskDigest },
+		...materialization ? { materialization } : {},
+		...executionBinding ? { executionBindings: [executionBinding] } : {},
+		budget: { timeoutMs: timeoutMs ?? null },
+		timing: {
+			startedAt: new Date(startedAt).toISOString(),
+			endedAt: new Date(endedAt).toISOString(),
+			durationMs: endedAt - startedAt
+		}
+	};
+}
+/**
+* Run ONE agent turn on any backend kind and stream its events. Yields the
+* `RuntimeStreamEvent` vocabulary incrementally and always ends with a `final`
+* event carrying the turn's text and usage (`metadata.tokenUsage`,
+* `metadata.costUsd?`, `metadata.model?`) — on success, failure, abort, and
+* timeout alike. The generator never throws; failures surface in-band as
+* `backend_error` + `final` with a typed `error` detail.
+*
+* @stable
+*/
+async function* streamAgentTurn(backend, input, opts = {}) {
+	assertTurnTimeout(opts.timeoutMs);
+	if (backend.kind !== "executor") throw new ValidationError("streamAgentTurn: exact execution accepts only kind 'executor'; use Runtime-owned creation");
+	yield* streamAgentTurnInternal(backend, input, opts);
+}
+function assertTurnTimeout(timeoutMs) {
+	if (timeoutMs === void 0) return;
+	if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 2147483647) throw new ValidationError("streamAgentTurn: timeoutMs must be an integer from 1 to 2147483647");
+}
+function assertTurnIdentity(value, field) {
+	if (value !== void 0 && (typeof value !== "string" || value.trim().length === 0)) throw new ValidationError(`streamAgentTurn: ${field} must be a non-empty string`);
+}
+async function* streamAgentTurnInternal(backend, input, opts) {
+	const label = backend.kind === "chat" ? backend.backend.kind : backend.kind;
+	const profile = backend.kind === "executor" ? executableAgentProfileSnapshot(backend.profile, "streamAgentTurn") : void 0;
+	const profileDigest = profile ? authoredProfileDigest(profile) : void 0;
+	assertTurnIdentity(opts.callId, "callId");
+	assertTurnIdentity(opts.correlationId, "correlationId");
+	const correlation = {
+		...opts.callId ? { callId: opts.callId } : {},
+		...opts.correlationId ? { correlationId: opts.correlationId } : {}
+	};
+	const taskDigest = canonicalCandidateDigest(input);
+	const task = {
+		id: `turn-${crypto.randomUUID()}`,
+		intent: turnIntent(input),
+		...profileDigest ? { metadata: { identity: {
+			profileDigest,
+			taskDigest,
+			...Object.keys(correlation).length > 0 ? { correlation } : {}
+		} } } : {}
+	};
+	const acc = {
+		deltaText: "",
+		input: 0,
+		output: 0,
+		costUsd: 0,
+		estimatedCostUsd: 0,
+		sawEstimatedCost: false,
+		promptCache: {},
+		tokensKnown: false,
+		usdKnown: false,
+		sawLlmCall: false,
+		sawTokenUsage: false,
+		sawCostUsage: false
+	};
+	const deadline = deriveTurnSignal(opts.signal, opts.timeoutMs ?? 0);
+	const startedAt = Date.now();
+	let session;
+	let executor;
+	let materialization;
+	let executionBinding;
+	try {
+		const nodeId = task.id;
+		const attemptId = `${nodeId}:attempt:${crypto.randomUUID()}`;
+		if (backend.kind === "executor") {
+			executor = backend.factory({
+				profile,
+				harness: null
+			}, {
+				signal: deadline.signal,
+				seams: {},
+				node: {
+					rootId: nodeId,
+					parentId: nodeId,
+					nodeId,
+					attemptId,
+					identity: {
+						profileDigest,
+						taskDigest,
+						...Object.keys(correlation).length > 0 ? { correlation } : {}
+					}
+				}
+			});
+			assertExactExecutorDeclaration(executor, profile);
+			const pending = runtimeOwnedPendingExecutorMaterialization(executor);
+			if (pending !== void 0) {
+				if (pending.runtime !== executor.runtime || pending.binding.attemptId !== attemptId) throw new ValidationError("streamAgentTurn: pending executor did not bind the kernel-minted attempt");
+				if (authoredProfileDigest(pending.declaration.effectiveProfile) !== profileDigest) throw new ValidationError("streamAgentTurn: pending executor changed the authored AgentProfile before execution");
+				materialization = unknownMaterializationReceipt({
+					authoredProfileDigest: profileDigest,
+					runtime: executor.runtime,
+					reason: "executor-receipt-pending"
+				});
+				executionBinding = unknownExecutionBindingReceipt(materialization, attemptId, "executor-receipt-pending");
+			} else {
+				({materialization, executionBinding} = executorEvidence(executor, profile, attemptId));
+				assertExactExecutorEvidence(materialization, executionBinding);
+			}
+		} else {
+			materialization = unknownMaterializationReceipt({
+				runtime: backend.kind === "box" ? "sandbox" : label,
+				reason: "executor-did-not-report"
+			});
+			executionBinding = unknownExecutionBindingReceipt(materialization, attemptId, "executor-did-not-report");
+		}
+		const startedSession = await awaitAbortable(Promise.resolve().then(() => startTurnSession(backend, task, input, deadline.signal, label)), deadline.signal);
+		session = startedSession;
+		yield {
+			type: "backend_start",
+			task,
+			session: startedSession,
+			backend: executor?.runtime ?? label,
+			metadata: {
+				...profileDigest ? { identity: {
+					profileDigest,
+					taskDigest,
+					...Object.keys(correlation).length > 0 ? { correlation } : {}
+				} } : { taskDigest },
+				...materialization ? { materialization } : {},
+				...executionBinding ? { executionBindings: [executionBinding] } : {},
+				budget: { timeoutMs: opts.timeoutMs ?? null },
+				timing: { startedAt: new Date(startedAt).toISOString() }
+			},
+			timestamp: nowIso()
+		};
+		const inner = backend.kind === "chat" ? driveChatTurn(backend.backend, task, startedSession, input, deadline.signal, acc) : backend.kind === "executor" ? driveExecutorTurn(executor, task, startedSession, input, deadline.signal, acc, materializedModel(materialization, profile)) : driveBoxTurn(backend.box, input, deadline.signal, backend.agentRunName ?? "agent", acc, {
+			...backend.options ? { options: backend.options } : {},
+			preserveToolParts: opts.preserveToolParts === true,
+			...opts.onRawEvent ? { onRawEvent: opts.onRawEvent } : {},
+			...profile?.harness ? { harness: profile.harness } : {}
+		});
+		const seenChildTaskUpdates = /* @__PURE__ */ new Set();
+		for await (const event of abortableValues(inner, deadline.signal)) {
+			if (childTaskAlreadySeen(event, seenChildTaskUpdates)) {
+				throwIfAborted(deadline.signal);
+				continue;
+			}
+			yield event;
+			throwIfAborted(deadline.signal);
+		}
+		throwIfAborted(deadline.signal);
+		if (backend.kind === "executor") {
+			({materialization, executionBinding} = executorEvidence(executor, profile, attemptId));
+			assertExactExecutorEvidence(materialization, executionBinding);
+		}
+		const terminalOutcome = acc.sandboxOutcome ? projectSandboxOutcome(acc.sandboxOutcome) : {
+			status: "completed",
+			reason: "turn completed"
+		};
+		yield buildFinalEvent(task, session, acc, terminalOutcome, turnProvenance(startedAt, opts.timeoutMs, profileDigest, taskDigest, materialization, executionBinding, correlation));
+	} catch (err) {
+		if (materialization?.status === "unknown" && materialization.reason === "executor-receipt-pending" && executionBinding?.status === "unknown") {
+			const terminal = unknownMaterializationReceipt({
+				...materialization.authoredProfileDigest === void 0 ? {} : { authoredProfileDigest: materialization.authoredProfileDigest },
+				runtime: materialization.runtime,
+				reason: "executor-failed-before-receipt"
+			});
+			executionBinding = unknownExecutionBindingReceipt(terminal, executionBinding.attemptId, "executor-failed-before-receipt");
+			materialization = terminal;
+		}
+		const callerAborted = opts.signal?.aborted === true;
+		const sandboxProjection = acc.sandboxOutcome ? projectSandboxOutcome(acc.sandboxOutcome) : void 0;
+		const status = callerAborted ? "aborted" : sandboxProjection?.status ?? "failed";
+		const message = sandboxProjection?.reason ?? (err instanceof Error ? err.message : String(err));
+		const error = sandboxProjection?.error ?? (err instanceof BackendTransportError ? {
+			kind: "transport",
+			message,
+			status: err.status,
+			body: err.body
+		} : {
+			kind: "backend",
+			message
+		});
+		yield {
+			type: "backend_error",
+			task,
+			...session ? { session } : {},
+			backend: label,
+			message,
+			recoverable: !callerAborted,
+			error,
+			timestamp: nowIso()
+		};
+		yield buildFinalEvent(task, session, acc, {
+			status,
+			reason: message,
+			error
+		}, turnProvenance(startedAt, opts.timeoutMs, profileDigest, taskDigest, materialization, executionBinding, correlation));
+	} finally {
+		if (executor) await awaitAbortable(Promise.resolve().then(() => executor.teardown("brutalKill")), deadline.signal).catch(() => void 0);
+		deadline.dispose();
+	}
+}
+function assertExactExecutorEvidence(materialization, executionBinding) {
+	if (materialization.status !== "known" || executionBinding.status !== "known") throw new ValidationError("streamAgentTurn: exact profile execution requires terminally validated Runtime materialization and execution binding evidence");
+	if (materialization.effectiveProfileDigest !== materialization.authoredProfileDigest) throw new ValidationError("streamAgentTurn: executor changed the authored AgentProfile; exact turn execution refuses profile overlays");
+}
+/**
+* Drain a `streamAgentTurn` stream (or any `RuntimeStreamEvent` stream that
+* honors its terminal contract) into the turn summary plus the full event
+* list. Fail-loud: throws when the stream ends without a terminal `final`
+* event — a stream that violates the contract must not read as an empty turn.
+*
+* @stable
+*/
+async function collectAgentTurn(stream) {
+	const events = [];
+	for await (const event of stream) events.push(event);
+	const final = events.at(-1);
+	if (final?.type !== "final") throw new Error(`collectAgentTurn: stream ended without a terminal 'final' event (last: ${final ? final.type : "none"})`);
+	const metadata = final.metadata ?? {};
+	const resultMetadata = metadata.result && typeof metadata.result === "object" ? metadata.result : void 0;
+	const sandboxOutcome = metadata.sandboxOutcome && typeof metadata.sandboxOutcome === "object" ? metadata.sandboxOutcome : void 0;
+	const tokenUsage = metadata.tokenUsage && typeof metadata.tokenUsage === "object" ? metadata.tokenUsage : {};
+	const usage = {
+		input: finiteNumber(tokenUsage.input) ?? 0,
+		output: finiteNumber(tokenUsage.output) ?? 0,
+		...metadata.tokensKnown === false ? { tokensKnown: false } : {}
+	};
+	const costUsd = finiteNumber(metadata.costUsd);
+	if (costUsd !== void 0) usage.costUsd = costUsd;
+	if (metadata.usdKnown === false) usage.usdKnown = false;
+	const estimatedCostUsd = finiteNumber(metadata.estimatedCostUsd);
+	if (estimatedCostUsd !== void 0) usage.estimatedCostUsd = estimatedCostUsd;
+	if (metadata.promptCache && typeof metadata.promptCache === "object") usage.promptCache = metadata.promptCache;
+	const reasoningTokens = finiteNumber(metadata.reasoningTokens);
+	if (reasoningTokens !== void 0) usage.reasoningTokens = reasoningTokens;
+	if (typeof metadata.model === "string" && metadata.model.length > 0) usage.model = metadata.model;
+	const transportAttempts = finiteNumber(metadata.transportAttempts);
+	const toolCalls = events.filter((event) => event.type === "tool_call").map((event) => ({
+		...event.toolCallId ? { id: event.toolCallId } : {},
+		name: event.toolName,
+		arguments: typeof event.args === "string" ? event.args : JSON.stringify(event.args ?? {})
+	}));
+	return {
+		finalText: final.text ?? "",
+		...resultMetadata && "output" in resultMetadata ? { output: resultMetadata.output } : {},
+		usage,
+		...transportAttempts !== void 0 ? { transportAttempts } : {},
+		toolCalls,
+		events,
+		status: final.status,
+		...final.error ? { error: final.error } : {},
+		...sandboxOutcome ? { sandboxOutcome } : {}
+	};
+}
+/** Start the backend's session when it owns one (`chat` kind); mint a local
+*  correlation session otherwise. Box/executor turns carry no server session
+*  here — resume lives in `openSandboxRun`/`SandboxLineage`, not this primitive. */
+async function startTurnSession(backend, task, input, signal, label) {
+	if (backend.kind === "chat" && backend.backend.start) return backend.backend.start(turnBackendInput(task, input), {
+		task,
+		knowledge: emptyReadiness(task),
+		signal
+	});
+	return newRuntimeSession(label);
+}
+/**
+* One turn over a box: `box.streamPrompt` projected through the existing
+* `mapSandboxEvent` (text/reasoning deltas +
+* cost-bearing `llm_call`s), plus the opt-in `mapSandboxToolEvent` tool-part
+* projection. Final text prefers the terminal
+* `result`/`done`/`final` payload over concatenated deltas, because the
+* sandbox `message.part.updated` fallback may carry running accumulations.
+*
+* Usage rides ONE {@link SandboxUsageLedger} for the turn — the same accounting the leaf kernel,
+* the steerable session, and `sumSandboxUsage` use — so a harness that reports its tokens only
+* inside its own event is metered here too, and a turn reporting both sources is charged once.
+* The ledger settles when the stream ends AND on the error path, because a turn that failed
+* mid-stream still spent what the harness already reported.
+*/
+async function* driveBoxTurn(box, input, signal, agentRunName, acc, cfg) {
+	const callOptions = {
+		...cfg.options ?? {},
+		signal
+	};
+	const stream = box.streamPrompt(promptFromAgentTurnInput(input), {
+		...callOptions,
+		...promptOptionsFromAgentTurnInput(input),
+		signal
+	});
+	const toolParts = cfg.preserveToolParts ? createSandboxToolPartState() : void 0;
+	const outcomeTracker = createAgentRunOutcomeTracker();
+	const usageLedger = createSandboxUsageLedger(cfg.harness);
+	try {
+		for await (const event of abortableValues(stream, signal)) {
+			outcomeTracker.observe(event);
+			if (cfg.onRawEvent) await awaitAbortable(Promise.resolve().then(() => cfg.onRawEvent(event)), signal);
+			const terminalText = terminalTextFromSandboxEvent(event);
+			if (terminalText !== void 0) acc.terminalText = terminalText;
+			const call = usageLedger.observe(event, agentRunName);
+			if (call) foldEvent(call, acc, agentRunName);
+			const canonical = canonicalStreamEventFromSandboxEvent(event);
+			if (canonical) {
+				yield canonical;
+				continue;
+			}
+			if (toolParts) for (const toolEvent of mapSandboxToolEvent(event, toolParts)) yield toolEvent;
+			const mapped = mapSandboxEvent(event, { agentRunName });
+			if (mapped) {
+				if (mapped.type !== "llm_call") foldEvent(mapped, acc, agentRunName);
+				yield mapped;
+			}
+		}
+	} catch (err) {
+		const aborted = usageLedger.settleTurn(agentRunName);
+		if (aborted) {
+			foldEvent(aborted, acc, agentRunName);
+			yield aborted;
+		}
+		throw err;
+	}
+	const settled = usageLedger.settleTurn(agentRunName);
+	if (settled) {
+		foldEvent(settled, acc, agentRunName);
+		yield settled;
+	}
+	acc.sandboxOutcome = outcomeTracker.finish();
+	const projection = projectSandboxOutcome(acc.sandboxOutcome);
+	if (projection.status === "failed") throw new Error(projection.reason);
+}
+/** One turn over an in-process backend: its own `stream()` surface, projected
+*  through the same `normalizeBackendStreamEvent` the task lifecycle applies. */
+async function* driveChatTurn(backend, task, session, input, signal, acc) {
+	const backendInput = turnBackendInput(task, input);
+	const context = {
+		task,
+		knowledge: emptyReadiness(task),
+		session,
+		signal
+	};
+	for await (const raw of abortableValues(backend.stream(backendInput, context), signal)) {
+		const event = normalizeBackendStreamEvent(raw, task, session);
+		foldEvent(event, acc);
+		yield event;
+	}
+}
+async function* driveExecutorTurn(executor, task, session, input, signal, acc, declaredModel) {
+	const taskValue = executorTaskValue(input);
+	const run = executor.execute(taskValue, signal);
+	let result;
+	if (isAsyncIterable(run)) {
+		for await (const usage of abortableValues(run, signal)) {
+			if (usage.kind === "progress") {
+				const projected = executorProgressStreamEvent(usage.progress, task, session);
+				foldEvent(projected, acc);
+				yield projected;
+				throwIfAborted(signal);
+				continue;
+			}
+			foldUsageEvent(usage, acc);
+			throwIfAborted(signal);
+		}
+		result = executor.resultArtifact();
+	} else result = await awaitAbortable(run, signal);
+	acc.result = result;
+	acc.sandboxOutcome = readSandboxOutcome(result.out);
+	acc.terminalText = executorResultText(result.out);
+	acc.input = result.spent.tokens.input;
+	acc.output = result.spent.tokens.output;
+	acc.costUsd = result.spent.usd;
+	const estimatedCostUsd = executorResultEstimatedCost(result.out);
+	if (estimatedCostUsd !== void 0) {
+		acc.estimatedCostUsd = estimatedCostUsd;
+		acc.sawEstimatedCost = true;
+	}
+	Object.assign(acc.promptCache, executorResultPromptCache(result.out));
+	acc.reasoningTokens = executorResultReasoningTokens(result.out);
+	acc.tokensKnown = result.spent.tokensKnown !== false;
+	acc.usdKnown = result.spent.usdKnown !== false;
+	acc.sawLlmCall = true;
+	const model = executorResultModel(result.out);
+	if (model) acc.model = model;
+	acc.stopReason = executorResultStopReason(result.out);
+	acc.transportAttempts = executorResultTransportAttempts(result.out);
+	const latencyMs = result.spent.ms;
+	yield {
+		type: "llm_call",
+		task,
+		session,
+		model: model ?? declaredModel ?? executor.runtime,
+		...acc.tokensKnown ? {
+			tokensIn: acc.input,
+			tokensOut: acc.output
+		} : {},
+		...acc.usdKnown ? { costUsd: acc.costUsd } : {},
+		...acc.tokensKnown ? {} : { tokensKnown: false },
+		...acc.usdKnown ? {} : { usdKnown: false },
+		...acc.sawEstimatedCost ? { estimatedCostUsd: acc.estimatedCostUsd } : {},
+		...Object.keys(acc.promptCache).length > 0 ? { promptCache: acc.promptCache } : {},
+		latencyMs,
+		timestamp: nowIso()
+	};
+	for (const call of executorResultToolCalls(result.out)) yield {
+		type: "tool_call",
+		task,
+		session,
+		toolName: call.name,
+		...call.id ? { toolCallId: call.id } : {},
+		args: call.arguments,
+		timestamp: nowIso()
+	};
+	yield {
+		type: "artifact",
+		task,
+		session,
+		artifactId: result.outRef,
+		name: "agent-turn-result",
+		metadata: {
+			spend: result.spent,
+			...result.verdict ? { verdict: result.verdict } : {}
+		},
+		timestamp: nowIso()
+	};
+	if (acc.sandboxOutcome && projectSandboxOutcome(acc.sandboxOutcome).status === "failed") throw new Error(projectSandboxOutcome(acc.sandboxOutcome).reason);
+}
+function executorTaskValue(input) {
+	const messages = input.providerOptions?.messages;
+	if (Array.isArray(messages)) return { messages: structuredClone(messages) };
+	return {
+		...input.prompt === void 0 ? {} : { prompt: input.prompt },
+		...input.parts === void 0 ? {} : { parts: structuredClone(input.parts) },
+		...input.interactions === void 0 ? {} : { interactions: input.interactions }
+	};
+}
+function isAsyncIterable(value) {
+	return typeof value === "object" && value !== null && Symbol.asyncIterator in value;
+}
+/**
+* Pull one provider iterator under Runtime's deadline.
+*
+* Providers still receive the signal for native cancellation, but correctness
+* does not depend on them observing it. A losing iterator is asked to close;
+* its late rejection is observed and cannot delay the terminal Runtime event.
+*/
+async function* abortableValues(source, signal) {
+	const iterator = source[Symbol.asyncIterator]();
+	let completed = false;
+	try {
+		for (;;) {
+			const next = await awaitAbortable(Promise.resolve().then(() => iterator.next()), signal);
+			if (next.done) {
+				completed = true;
+				return;
+			}
+			yield next.value;
+		}
+	} finally {
+		if (!completed) try {
+			Promise.resolve(iterator.return?.()).catch(() => void 0);
+		} catch {}
+	}
+}
+function executorResultText(value) {
+	if (typeof value === "string") return value;
+	if (!value || typeof value !== "object") return "";
+	const content = value.content;
+	return typeof content === "string" ? content : "";
+}
+function executorResultModel(value) {
+	if (!value || typeof value !== "object") return void 0;
+	const model = value.model;
+	return typeof model === "string" && model.length > 0 ? model : void 0;
+}
+function executorResultStopReason(value) {
+	if (!value || typeof value !== "object") return void 0;
+	const reason = value.finishReason;
+	return typeof reason === "string" && reason.length > 0 ? reason : void 0;
+}
+function executorResultTransportAttempts(value) {
+	if (!value || typeof value !== "object") return void 0;
+	const attempts = value.transportAttempts;
+	return typeof attempts === "number" && Number.isSafeInteger(attempts) && attempts > 0 ? attempts : void 0;
+}
+function executorResultEstimatedCost(value) {
+	if (!value || typeof value !== "object") return void 0;
+	return finiteNumber(value.estimatedCostUsd);
+}
+function executorResultPromptCache(value) {
+	if (!value || typeof value !== "object") return {};
+	const raw = value.promptCache;
+	if (!raw || typeof raw !== "object" || Array.isArray(raw)) return {};
+	const cache = {};
+	for (const [key, entry] of Object.entries(raw)) if (typeof entry === "number" && Number.isFinite(entry) || typeof entry === "string") cache[key] = entry;
+	return cache;
+}
+function executorResultReasoningTokens(value) {
+	if (!value || typeof value !== "object") return void 0;
+	const count = value.reasoningTokens;
+	return Number.isSafeInteger(count) && count >= 0 ? count : void 0;
+}
+/**
+* Read the terminal tool calls an executor artifact published. Every Runtime-owned executor
+* reports `ExecutorToolCall[]`, so an artifact carrying any other shape is a defect in that
+* executor rather than a turn without tool calls: refuse it instead of dropping the calls.
+*/
+function executorResultToolCalls(value) {
+	if (!value || typeof value !== "object") return [];
+	const raw = value.toolCalls;
+	if (raw === void 0) return [];
+	if (!Array.isArray(raw)) throw new ValidationError(`streamAgentTurn: executor artifact toolCalls must be an ExecutorToolCall array, received ${typeof raw}`);
+	return raw.map((entry) => {
+		const call = entry && typeof entry === "object" ? entry : void 0;
+		if (!call || typeof call.name !== "string" || call.name.length === 0) throw new ValidationError("streamAgentTurn: executor artifact toolCalls entries require a non-empty name");
+		return {
+			...typeof call.id === "string" ? { id: call.id } : {},
+			name: call.name,
+			arguments: typeof call.arguments === "string" ? call.arguments : JSON.stringify(call.arguments ?? {})
+		};
+	});
+}
+/** Project one executor progress event onto the public turn vocabulary. */
+function executorProgressStreamEvent(progress, task, session) {
+	const timestamp = nowIso();
+	if (progress.kind === "text_delta") return {
+		type: "text_delta",
+		task,
+		session,
+		text: progress.text,
+		timestamp
+	};
+	if (progress.kind === "reasoning_delta") return {
+		type: "reasoning_delta",
+		task,
+		session,
+		text: progress.text,
+		timestamp
+	};
+	if (progress.kind === "tool_call") return {
+		type: "tool_call",
+		task,
+		session,
+		toolName: progress.toolName,
+		...progress.toolCallId === void 0 ? {} : { toolCallId: progress.toolCallId },
+		...progress.args === void 0 ? {} : { args: progress.args },
+		timestamp
+	};
+	if (progress.kind === "tool_result") return {
+		type: "tool_result",
+		task,
+		session,
+		toolName: progress.toolName,
+		...progress.toolCallId === void 0 ? {} : { toolCallId: progress.toolCallId },
+		...progress.result === void 0 ? {} : { result: progress.result },
+		timestamp
+	};
+	if (progress.kind === "child_task") return {
+		...progress.event,
+		task,
+		session,
+		timestamp
+	};
+	return {
+		type: "interaction",
+		request: progress.request,
+		task,
+		session,
+		timestamp
+	};
+}
+/**
+* Drop a child-task update this turn already published. The provider's `sourceEventId` names one
+* exact update, so a reconnect or replay that repeats it must not add a second child.
+*/
+function childTaskAlreadySeen(event, seen) {
+	if (event.type !== "child-task") return false;
+	if (seen.has(event.sourceEventId)) return true;
+	seen.add(event.sourceEventId);
+	return false;
+}
+/** Fold one normalized executor usage event into the turn accumulator. */
+function foldUsageEvent(event, acc) {
+	if (event.kind === "tokens") {
+		const known = event.tokensKnown !== false;
+		acc.tokensKnown = acc.sawTokenUsage ? acc.tokensKnown && known : known;
+		acc.sawTokenUsage = true;
+		acc.input += event.input;
+		acc.output += event.output;
+	} else if (event.kind === "cost") {
+		const known = event.usdKnown;
+		acc.usdKnown = acc.sawCostUsage ? acc.usdKnown && known : known;
+		acc.sawCostUsage = true;
+		acc.costUsd += event.usd;
+		if (event.usdKnown === false && event.usdEstimated !== void 0) {
+			acc.estimatedCostUsd += event.usdEstimated;
+			acc.sawEstimatedCost = true;
+		}
+	}
+	if (event.kind === "tokens" || event.kind === "cost") acc.sawLlmCall = true;
+}
+/** Fold one normalized event into the turn accumulator (text + usage).
+*  `fallbackModelLabel` — a mapper-stamped run label to exclude from
+*  `usage.model` (it is not a backend-reported model). */
+function foldEvent(event, acc, fallbackModelLabel) {
+	if (event.type === "text_delta") {
+		acc.deltaText += event.text;
+		return;
+	}
+	if (event.type === "llm_call") {
+		const tokensReported = event.tokensKnown !== false && event.tokensIn !== void 0 && event.tokensOut !== void 0;
+		const usdReported = event.usdKnown !== false && event.costUsd !== void 0;
+		if (!acc.sawLlmCall) {
+			acc.tokensKnown = tokensReported;
+			acc.usdKnown = usdReported;
+			acc.sawLlmCall = true;
+		} else {
+			acc.tokensKnown &&= tokensReported;
+			acc.usdKnown &&= usdReported;
+		}
+		acc.input += event.tokensIn ?? 0;
+		acc.output += event.tokensOut ?? 0;
+		acc.costUsd += event.costUsd ?? 0;
+		if (event.estimatedCostUsd !== void 0) {
+			acc.estimatedCostUsd += event.estimatedCostUsd;
+			acc.sawEstimatedCost = true;
+		}
+		if (event.promptCache) Object.assign(acc.promptCache, event.promptCache);
+		if (event.model && event.model !== fallbackModelLabel) acc.model = event.model;
+	}
+}
+/** Read the final text off a terminal sandbox event, when present. */
+function terminalTextFromSandboxEvent(event) {
+	if (!event || typeof event !== "object") return void 0;
+	if (!isSandboxTerminalEvent(String(event.type ?? ""))) return void 0;
+	const data = event.data && typeof event.data === "object" ? event.data : {};
+	for (const key of [
+		"finalText",
+		"text",
+		"response",
+		"content"
+	]) {
+		const value = data[key];
+		if (typeof value === "string") return value;
+	}
+}
+function buildFinalEvent(task, session, acc, outcome, provenance) {
+	const finalText = acc.terminalText ?? acc.deltaText;
+	return {
+		type: "final",
+		task,
+		...session ? { session } : {},
+		status: outcome.status,
+		reason: outcome.status === "completed" ? acc.stopReason ?? outcome.reason : outcome.reason,
+		...finalText ? { text: finalText } : {},
+		metadata: {
+			tokenUsage: {
+				input: acc.input,
+				output: acc.output
+			},
+			...acc.tokensKnown ? {} : { tokensKnown: false },
+			...acc.usdKnown ? { costUsd: acc.costUsd } : { usdKnown: false },
+			...acc.sawEstimatedCost ? { estimatedCostUsd: acc.estimatedCostUsd } : {},
+			...Object.keys(acc.promptCache).length > 0 ? { promptCache: acc.promptCache } : {},
+			...acc.reasoningTokens !== void 0 ? { reasoningTokens: acc.reasoningTokens } : {},
+			...acc.model ? { model: acc.model } : {},
+			...acc.stopReason ? { stopReason: acc.stopReason } : {},
+			...acc.transportAttempts !== void 0 ? { transportAttempts: acc.transportAttempts } : {},
+			...acc.sandboxOutcome ? {
+				sandboxOutcome: acc.sandboxOutcome,
+				verdict: projectSandboxOutcome(acc.sandboxOutcome).verdict
+			} : {},
+			...acc.result ? { result: {
+				outRef: acc.result.outRef,
+				output: acc.result.out,
+				...acc.sandboxOutcome ? { verdict: projectSandboxOutcome(acc.sandboxOutcome).verdict } : acc.result.verdict ? { verdict: acc.result.verdict } : {},
+				spent: acc.result.spent
+			} } : acc.sandboxOutcome ? { result: { verdict: projectSandboxOutcome(acc.sandboxOutcome).verdict } } : {},
+			...provenance
+		},
+		...outcome.error ? { error: outcome.error } : {},
+		timestamp: nowIso()
+	};
+}
+function materializedModel(receipt, profile) {
+	if (receipt?.status === "known" && receipt.model.status === "known") return receipt.model.id;
+	const fallback = profile.model?.default;
+	return typeof fallback === "string" && fallback.length > 0 ? fallback : void 0;
+}
+/** Minimal ready-by-construction readiness report for a requirement-free turn. */
+function emptyReadiness(task) {
+	return scoreKnowledgeReadiness({
+		taskId: task.id,
+		requirements: []
+	});
+}
+function finiteNumber(value) {
+	return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+function throwIfAborted(signal) {
+	if (!signal.aborted) return;
+	throw signal.reason instanceof Error ? signal.reason : new Error(String(signal.reason));
+}
+/**
+* Derive the turn's effective abort signal: fires when EITHER the caller's
+* signal aborts OR the `timeoutMs` deadline elapses. `dispose()` clears the
+* timer so a finished turn never leaks a pending timeout. `timeoutMs <= 0`
+* disables the deadline. Node-portable (no `AbortSignal.any`, which needs
+* >=20.3 — the package floor is >=20).
+*/
+function deriveTurnSignal(callerSignal, timeoutMs) {
+	const controller = new AbortController();
+	const timer = timeoutMs > 0 ? setTimeout(() => controller.abort(/* @__PURE__ */ new Error(`agent turn timed out after ${timeoutMs}ms`)), timeoutMs) : void 0;
+	if (timer && typeof timer.unref === "function") timer.unref();
+	const onCallerAbort = () => controller.abort(callerSignal?.reason ?? /* @__PURE__ */ new Error("agent turn aborted"));
+	if (callerSignal) if (callerSignal.aborted) onCallerAbort();
+	else callerSignal.addEventListener("abort", onCallerAbort, { once: true });
+	return {
+		signal: controller.signal,
+		dispose: () => {
+			if (timer) clearTimeout(timer);
+			callerSignal?.removeEventListener("abort", onCallerAbort);
+		}
+	};
+}
+//#endregion
 //#region src/improvement/optimizer-prompt.ts
 /**
 * The senior scientific-method optimizer doctrine — the ONE substantial prompt
@@ -1711,6 +2804,6 @@ function structuralRollout(config = {}) {
 	});
 }
 //#endregion
-export { observe as C, optimizerMethod as D, profileOptimizerModelCall as E, strategyAuthorMethod as O, defaultAnalystInstruction as S, profileChatClient as T, depthStrategy as _, defaultStructuralRolloutPolicy as a, sample as b, officialChecksFromMeta as c, selectBestIndex as d, structuralRollout as f, defineStrategy as g, breadthStrategy as h, defaultExtractCandidate as i, resolveEntrySymbol as l, adaptiveRefine as m, compareCheckOutcomes as n, filterAuthoredAsserts as o, visibleCheckScore as p, composeCheckSources as r, modelAuthoredChecks as s, canDisplace as t, sandboxCheckRunner as u, refine as v, renderReport as w, sampleThenRefine as x, runAgentic as y };
+export { streamAgentTurn as A, observe as C, optimizerMethod as D, profileOptimizerModelCall as E, newRuntimeSession as F, nowIso as I, startOrResumeRuntimeSession as L, createSandboxPromptBackend as M, normalizeBackendStreamEvent as N, strategyAuthorMethod as O, InMemoryRuntimeSessionStore as P, touchSession as R, defaultAnalystInstruction as S, profileChatClient as T, depthStrategy as _, defaultStructuralRolloutPolicy as a, sample as b, officialChecksFromMeta as c, selectBestIndex as d, structuralRollout as f, defineStrategy as g, breadthStrategy as h, defaultExtractCandidate as i, createIterableBackend as j, collectAgentTurn as k, resolveEntrySymbol as l, adaptiveRefine as m, compareCheckOutcomes as n, filterAuthoredAsserts as o, visibleCheckScore as p, composeCheckSources as r, modelAuthoredChecks as s, canDisplace as t, sandboxCheckRunner as u, refine as v, renderReport as w, sampleThenRefine as x, runAgentic as y };
 
-//# sourceMappingURL=structural-rollout-DPbZWgEm.js.map
+//# sourceMappingURL=structural-rollout-D__lmWXe.js.map