@tangle-network/agent-runtime 0.128.0 → 0.131.1

package/dist/stream-agent-turn-rYgaOLO0.js

@@ -0,0 +1,910 @@
+import { l as SessionMismatchError, r as BackendTransportError, u as ValidationError } from "./errors-DEAvWQPy.js";
+import { i as mapSandboxToolEvent, r as mapSandboxEvent, t as createSandboxToolPartState } from "./sandbox-events-CRDwc5WN.js";
+import { c as profileProviderModel, i as concreteModelId, o as profileBridgeWireModel } from "./model-policy-CqziaqS1.js";
+import { _ as unknownMaterializationReceipt, a as authoredProfileDigest, c as knownExecutionBindingReceipt, f as runtimeOwnedExecutorExecutionBinding, g as unknownExecutionBindingReceipt, l as knownMaterializationReceipt, m as runtimeOwnedPendingExecutorMaterialization, p as runtimeOwnedExecutorMaterialization, v as executableAgentProfileSnapshot } from "./materialization-COJ1UYQ-.js";
+import { scoreKnowledgeReadiness } from "@tangle-network/agent-eval";
+import { canonicalCandidateDigest } from "@tangle-network/agent-interface";
+//#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 ?? 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` + `extractLlmCallEvent` (sandbox-events.ts)
+*                  project the sandbox event stream; 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 (typeof input === "string") return input;
+	for (let index = input.messages.length - 1; index >= 0; index -= 1) {
+		const message = input.messages[index];
+		if (message?.role === "user" && typeof message.content === "string") return message.content;
+	}
+	return "structured agent turn";
+}
+function turnBackendInput(task, input) {
+	if (typeof input === "string") return {
+		task,
+		message: input
+	};
+	return {
+		task,
+		messages: input.messages.map((message) => ({ ...message }))
+	};
+}
+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
+	};
+	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");
+		}
+		session = await startTurnSession(backend, task, input, deadline.signal, label);
+		yield {
+			type: "backend_start",
+			task,
+			session,
+			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, session, input, deadline.signal, acc) : backend.kind === "executor" ? driveExecutorTurn(executor, task, session, input, deadline.signal, acc, materializedModel(materialization, profile)) : driveBoxTurn(backend.box, turnIntent(input), deadline.signal, backend.agentRunName ?? "agent", acc, {
+			...backend.options ? { options: backend.options } : {},
+			preserveToolParts: opts.preserveToolParts === true,
+			...opts.onRawEvent ? { onRawEvent: opts.onRawEvent } : {}
+		});
+		for await (const event of inner) {
+			yield event;
+			throwIfAborted(deadline.signal);
+		}
+		if (backend.kind === "executor") {
+			({materialization, executionBinding} = executorEvidence(executor, profile, attemptId));
+			assertExactExecutorEvidence(materialization, executionBinding);
+		}
+		yield buildFinalEvent(task, session, acc, {
+			status: "completed",
+			reason: "turn completed"
+		}, turnProvenance(startedAt, opts.timeoutMs, profileDigest, taskDigest, materialization, executionBinding, correlation));
+	} catch (err) {
+		const callerAborted = opts.signal?.aborted === true;
+		const status = callerAborted ? "aborted" : "failed";
+		const message = err instanceof Error ? err.message : String(err);
+		const 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 {
+		await executor?.teardown("brutalKill").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 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 } : {}
+	};
+}
+/** 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. Usage accumulates off the mapped `llm_call` events — the same
+* fold `sumSandboxUsage` applies. Final text prefers the terminal
+* `result`/`done`/`final` payload over concatenated deltas, because the
+* sandbox `message.part.updated` fallback may carry running accumulations.
+*/
+async function* driveBoxTurn(box, prompt, signal, agentRunName, acc, cfg) {
+	const callOptions = {
+		...cfg.options ?? {},
+		signal
+	};
+	const stream = box.streamPrompt(prompt, callOptions);
+	const toolParts = cfg.preserveToolParts ? createSandboxToolPartState() : void 0;
+	for await (const event of stream) {
+		if (cfg.onRawEvent) await cfg.onRawEvent(event);
+		const terminalText = terminalTextFromSandboxEvent(event);
+		if (terminalText !== void 0) acc.terminalText = terminalText;
+		if (toolParts) for (const toolEvent of mapSandboxToolEvent(event, toolParts)) yield toolEvent;
+		const mapped = mapSandboxEvent(event, { agentRunName });
+		if (!mapped) continue;
+		foldEvent(mapped, acc, agentRunName);
+		yield mapped;
+	}
+}
+/** 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 backend.stream(backendInput, context)) {
+		const event = normalizeBackendStreamEvent(raw, task, session);
+		foldEvent(event, acc);
+		yield event;
+	}
+}
+async function* driveExecutorTurn(executor, task, session, input, signal, acc, declaredModel) {
+	const taskValue = typeof input === "string" ? input : { messages: input.messages };
+	const run = executor.execute(taskValue, signal);
+	let result;
+	if (isAsyncIterable(run)) {
+		for await (const _usage of run) throwIfAborted(signal);
+		result = executor.resultArtifact();
+	} else result = await run;
+	acc.result = result;
+	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()
+	};
+}
+function isAsyncIterable(value) {
+	return typeof value === "object" && value !== null && Symbol.asyncIterator in value;
+}
+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;
+}
+function executorResultToolCalls(value) {
+	if (!value || typeof value !== "object") return [];
+	const raw = value.toolCalls;
+	if (!Array.isArray(raw)) return [];
+	return raw.flatMap((entry) => {
+		if (!entry || typeof entry !== "object") return [];
+		const call = entry;
+		if (typeof call.name !== "string") return [];
+		return [{
+			...typeof call.id === "string" ? { id: call.id } : {},
+			name: call.name,
+			arguments: typeof call.arguments === "string" ? call.arguments : JSON.stringify(call.arguments ?? {})
+		}];
+	});
+}
+/** 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;
+	const type = String(event.type ?? "");
+	if (type !== "result" && type !== "done" && type !== "final") 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.result ? { result: {
+				outRef: acc.result.outRef,
+				output: acc.result.out,
+				...acc.result.verdict ? { verdict: acc.result.verdict } : {},
+				spent: acc.result.spent
+			} } : {},
+			...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
+export { normalizeBackendStreamEvent as a, nowIso as c, createSandboxPromptBackend as i, startOrResumeRuntimeSession as l, streamAgentTurn as n, InMemoryRuntimeSessionStore as o, createIterableBackend as r, newRuntimeSession as s, collectAgentTurn as t, touchSession as u };
+
+//# sourceMappingURL=stream-agent-turn-rYgaOLO0.js.map