@tangle-network/agent-runtime 0.301.0 → 0.306.1

package/dist/{workspace-streams-D5gHJdTb.js → workspace-streams-ILw0eWZ0.js}

@@ -1,3 +1,5 @@
+import { m as ValidationError } from "./errors-DodWX-cb.js";
+import { runTaskQueue } from "./task-queue.js";
 import { agentCandidateArtifactRefSchema, canonicalCandidateBytes as canonicalCandidateBytes$1 } from "@tangle-network/agent-interface";
 import { createHash, randomUUID } from "node:crypto";
 import { spawn } from "node:child_process";
@@ -9,6 +11,618 @@ import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import { extract, pack } from "tar-stream";
 import { isAnyArrayBuffer, isSharedArrayBuffer } from "node:util/types";
+//#region src/runtime/supervise/deadline.ts
+const MAX_TIMER_DELAY_MS = 2147483647;
+const DEFAULT_SUCCESSFUL_SHUTDOWN_MS = 5e3;
+/** The abort reason a child's own deadline carries. */
+const CHILD_DEADLINE_REASON = "child deadline exceeded";
+/** The abort reason the root's budget deadline cascades to every node. */
+const ROOT_DEADLINE_REASON = "root budget deadline exceeded";
+/**
+* How long an abort waits for a manager whose result was already accepted to end the turn that
+* submitted it. Acceptance asks the turn's harness to stop; what remains is the turn's final
+* session copy (a bounded native capture), metering its usage and committing its result. Its
+* workspace capture is not part of it: the manager's owner runs that after the result.
+*/
+const ACCEPTED_RESULT_GRACE_MS = 5 * 6e4;
+/** Whether an abort reason is a deadline: the child's own or the root budget's. */
+function isDeadlineAbortReason(reason) {
+	return reason === "child deadline exceeded" || reason === "root budget deadline exceeded";
+}
+const TEARDOWN_ACKNOWLEDGEMENT_MS = 250;
+/** Arm a finite wall-clock deadline in safe chunks. Resource deadlines unref by default;
+* a standalone wait opts into keeping the process alive until it settles or is cancelled. */
+function armDeadlineTimer(delayMs, onDeadline, keepAlive = false) {
+	const deadlineAtMs = Date.now() + Math.max(0, delayMs);
+	if (!Number.isFinite(delayMs) || !Number.isSafeInteger(Math.ceil(deadlineAtMs))) throw new ValidationError("timer delay must produce a finite safe deadline");
+	let cleared = false;
+	let timer;
+	const arm = () => {
+		if (cleared) return;
+		const remainingMs = Math.max(0, deadlineAtMs - Date.now());
+		timer = setTimeout(() => {
+			if (cleared) return;
+			if (Date.now() >= deadlineAtMs) onDeadline();
+			else arm();
+		}, Math.min(remainingMs, MAX_TIMER_DELAY_MS));
+		if (!keepAlive && typeof timer.unref === "function") timer.unref();
+	};
+	arm();
+	return () => {
+		cleared = true;
+		if (timer !== void 0) clearTimeout(timer);
+	};
+}
+/**
+* Resolve a spawned child's duration into one absolute cutoff. An omitted child deadline inherits
+* the parent cutoff; an explicit child duration may shorten, but never extend, that cutoff.
+*/
+function boundedChildDeadlineAt(parentDeadlineAtMs, childDeadlineMs, nowMs) {
+	const parent = parentDeadlineAtMs > 0 ? parentDeadlineAtMs : void 0;
+	const child = childDeadlineMs === void 0 ? void 0 : nowMs + childDeadlineMs;
+	if (parent === void 0) return child;
+	if (child === void 0) return parent;
+	return Math.min(parent, child);
+}
+/** Invoke teardown once and bound how long the runtime waits for its acknowledgement. A hard
+* execution deadline always wins; without one, numeric grace gets a short acknowledgement
+* allowance and a brutal kill gets only that allowance. Explicit `infinity` remains unbounded
+* only when no execution deadline exists. The losing promise stays observed. `ask` issues the
+* request; a scope passes its per-child single-flight asker (see `singleFlightTeardown`). */
+async function teardownExecutor(executor, grace, deadlineAtMs, now, ask = (requested) => Promise.resolve(executor.teardown(requested))) {
+	const work = Promise.resolve(ask(grace));
+	const requestedWaitMs = grace === "infinity" ? void 0 : grace === "brutalKill" ? executor.teardownTimeoutMs ?? TEARDOWN_ACKNOWLEDGEMENT_MS : grace + TEARDOWN_ACKNOWLEDGEMENT_MS;
+	const deadlineWaitMs = deadlineAtMs === void 0 ? void 0 : Math.max(0, deadlineAtMs - now()) + TEARDOWN_ACKNOWLEDGEMENT_MS;
+	const waitMs = requestedWaitMs === void 0 ? deadlineWaitMs : deadlineWaitMs === void 0 ? requestedWaitMs : Math.min(requestedWaitMs, deadlineWaitMs);
+	let receipt;
+	if (waitMs === void 0) receipt = await work;
+	else if (waitMs <= 0) {
+		work.catch(() => void 0);
+		throw new ValidationError("executor teardown did not acknowledge before its deadline");
+	} else {
+		let clearTimer;
+		const timedOut = new Promise((_resolve, reject) => {
+			clearTimer = armDeadlineTimer(waitMs, () => reject(new ValidationError(`executor teardown did not acknowledge within ${waitMs}ms`)), true);
+		});
+		try {
+			receipt = await Promise.race([work, timedOut]);
+		} finally {
+			clearTimer?.();
+		}
+	}
+	if (!receipt.destroyed) throw new ValidationError(`executor teardown reported destroyed=false${receipt.detail ? `: ${receipt.detail}` : ""}`);
+}
+/**
+* The optional teardown surfaces a wrapping executor forwards, so wrapping never changes how a
+* child is released: the acknowledgement window a remote teardown needs, the release of a
+* retained execution at root settlement, and the environments an unconfirmed teardown names for
+* a sweeper. A wrapper that dropped `releaseRetained` left every retained child it wrapped
+* running after settlement. Each surface is present only when the inner executor implements it.
+*/
+function teardownSurfaces(inner) {
+	return {
+		...inner.teardownTimeoutMs === void 0 ? {} : { teardownTimeoutMs: inner.teardownTimeoutMs },
+		...inner.releaseRetained === void 0 ? {} : { releaseRetained: (signal) => inner.releaseRetained(signal) },
+		...inner.heldEnvironments === void 0 ? {} : { heldEnvironments: () => inner.heldEnvironments() }
+	};
+}
+/**
+* An asker that sends an executor at most one teardown at a time. While a request is still
+* running, every later ask returns that same request instead of sending another beside it.
+*
+* A settlement's own teardown has a short acknowledgement window, and a request that misses it
+* keeps running. Without this, the first settlement retry sent a second teardown next to the
+* first. An executor that does not deduplicate internally, such as one that re-issues its
+* cancels, then ran two teardowns at once. `onRequest` runs once for each request actually sent.
+*/
+function singleFlightTeardown(executor, onRequest) {
+	let inFlight;
+	return (grace) => {
+		if (inFlight !== void 0) return inFlight;
+		onRequest();
+		let request;
+		try {
+			request = Promise.resolve(executor.teardown(grace));
+		} catch (error) {
+			request = Promise.reject(error);
+		}
+		inFlight = request;
+		const settle = () => {
+			if (inFlight === request) inFlight = void 0;
+		};
+		request.then(settle, settle);
+		return request;
+	};
+}
+//#endregion
+//#region src/runtime/supervise/resources.ts
+/** Validate caller-owned names and units without assigning domain meaning to them. */
+function assertResources(resources, kind, label) {
+	if (resources === void 0) return;
+	if (resources === null || typeof resources !== "object" || Array.isArray(resources)) throw new Error(`${label} must be a resource map`);
+	for (const [name, resource] of Object.entries(resources)) {
+		if (!name.trim() || !resource || typeof resource !== "object" || typeof resource.unit !== "string" || !resource.unit.trim()) throw new Error(`${label}: resource names and units must be non-empty strings`);
+		const value = kind === "limit" ? "limit" in resource ? resource.limit : void 0 : "amount" in resource ? resource.amount : void 0;
+		if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) throw new Error(`${label}.${name}.${kind} must be a non-negative safe integer`);
+		if (kind === "amount" && (!("known" in resource) || typeof resource.known !== "boolean")) throw new Error(`${label}.${name}.known must be a boolean`);
+	}
+}
+/** Missing contributors are not usage claims; enforced omissions are marked before aggregation.
+* Overflow retains a safe lower bound and marks it unknown, preserving readable component receipts. */
+function addResourceSpend(...maps) {
+	const totals = /* @__PURE__ */ new Map();
+	for (const resources of maps) {
+		assertResources(resources, "amount", "resource spend");
+		for (const [name, resource] of Object.entries(resources ?? {})) {
+			const prior = totals.get(name);
+			if (prior && prior.unit !== resource.unit) throw new Error(`resource ${name}: unit mismatch`);
+			const amount = (prior?.amount ?? 0) + resource.amount;
+			totals.set(name, {
+				unit: resource.unit,
+				amount: Math.min(amount, Number.MAX_SAFE_INTEGER),
+				known: (prior?.known ?? true) && resource.known && Number.isSafeInteger(amount)
+			});
+		}
+	}
+	return totals.size ? { resources: Object.fromEntries(totals) } : {};
+}
+/** A terminal omission under an enforced ceiling is unknown, never measured zero. */
+function withBudgetResources(spend, budget, notStarted = false) {
+	const resources = new Map(Object.entries(addResourceSpend(spend.resources).resources ?? {}));
+	for (const [name, limit] of Object.entries(budget.resources ?? {})) {
+		const observed = resources.get(name);
+		if (observed && observed.unit !== limit.unit) throw new Error(`resource ${name}: unit mismatch`);
+		if (!observed) resources.set(name, {
+			unit: limit.unit,
+			amount: 0,
+			known: notStarted
+		});
+	}
+	return resources.size ? {
+		...spend,
+		resources: Object.fromEntries(resources)
+	} : spend;
+}
+/** Stream increments and a terminal total describe the same work; never sum them twice. */
+function resourceTelemetry(streamed, terminal) {
+	const resources = new Map(Object.entries(addResourceSpend(terminal.resources).resources ?? {}));
+	for (const [name, value] of Object.entries(streamed.resources ?? {})) {
+		const other = resources.get(name);
+		if (other && other.unit !== value.unit) throw new Error(`resource ${name}: unit mismatch`);
+		resources.set(name, {
+			...value,
+			amount: Math.max(value.amount, other?.amount ?? 0),
+			known: value.known && (other?.known ?? true) && (other === void 0 || other.amount === value.amount)
+		});
+	}
+	return addResourceSpend(Object.fromEntries(resources));
+}
+//#endregion
+//#region src/runtime/util.ts
+/**
+* Best-effort sandbox delete. Skips instances without a `delete` (test fakes);
+* swallows errors (the platform reaps on expiry). Returns `false` when delete
+* threw, `true` otherwise, so callers can surface a leak if they choose.
+*/
+async function deleteBoxSafe(box) {
+	if (!box || typeof box.delete !== "function") return true;
+	try {
+		await box.delete();
+		return true;
+	} catch {
+		return false;
+	}
+}
+/** Short base36 id for trace correlation. Not cryptographic, not collision-free. */
+function randomSuffix(len = 8) {
+	return Math.random().toString(36).slice(2, 2 + len);
+}
+/** Collision-resistant id for sandbox naming (find-by-name recovery must be unique). */
+function randomUuid() {
+	return crypto.randomUUID();
+}
+/** Construct an AbortError. Downstream code pattern-matches on `err.name`. */
+function abortError() {
+	const err = /* @__PURE__ */ new Error("aborted");
+	err.name = "AbortError";
+	return err;
+}
+/** Throw an AbortError. */
+function throwAbort() {
+	throw abortError();
+}
+/** Throw if the signal is already aborted; otherwise no-op. */
+function throwIfAborted(signal) {
+	if (signal?.aborted) throw abortError();
+}
+/** True for any error whose `name` is `AbortError` (the cross-kernel abort contract). */
+function isAbortError(err) {
+	return err instanceof Error && err.name === "AbortError";
+}
+/**
+* Sleep that resolves early on abort and always clears its timer so it never
+* keeps the event loop alive. Resolves (does not reject) on abort — callers
+* re-check the signal explicitly after the sleep.
+*/
+function sleep(ms, signal, keepAlive = true) {
+	if (signal?.aborted) return Promise.resolve();
+	return new Promise((resolve) => {
+		const done = () => {
+			clearTimer();
+			signal?.removeEventListener("abort", done);
+			resolve();
+		};
+		const clearTimer = armDeadlineTimer(ms, done, keepAlive);
+		signal?.addEventListener("abort", done, { once: true });
+	});
+}
+/**
+* Race a promise against a timeout. Resolves with the value if it settles in
+* time, otherwise resolves with `undefined`. Always clears the timer.
+*/
+function withTimeout(promise, ms) {
+	return new Promise((resolve) => {
+		const clearTimer = armDeadlineTimer(ms, () => resolve(void 0), true);
+		promise.then((value) => {
+			clearTimer();
+			resolve(value);
+		}, () => {
+			clearTimer();
+			resolve(void 0);
+		});
+	});
+}
+/**
+* `JSON.stringify` with a `String()` fallback on throw (cyclic / non-JSON).
+* Strings pass through unstringified so a preview of a string output is the
+* string itself, not a quoted re-encoding.
+*/
+function stringifySafe(value, opts = {}) {
+	let s;
+	try {
+		if (typeof value === "string") s = value;
+		else s = (opts.pretty ? JSON.stringify(value, null, 2) : JSON.stringify(value)) ?? String(value);
+	} catch {
+		s = String(value);
+	}
+	if (opts.max !== void 0 && s.length > opts.max) return `${s.slice(0, opts.max)}…`;
+	return s;
+}
+/** A fresh zero token-usage accumulator. */
+function zeroTokenUsage() {
+	return {
+		input: 0,
+		output: 0
+	};
+}
+/**
+* Sum the catalog-priced part of a dollar total across spends, as a field to spread.
+*
+* Returns nothing when no input carried one. A fold of pure provider receipts must not gain a
+* `usdEstimated: 0`, which would read as "this runtime checked and priced none" on a path that
+* never prices at all.
+*/
+function usdEstimatedOf(...spends) {
+	let total = 0;
+	let priced = false;
+	for (const spend of spends) {
+		if (spend.usdEstimated === void 0) continue;
+		priced = true;
+		total += spend.usdEstimated;
+	}
+	return priced ? { usdEstimated: total } : {};
+}
+/** A conserved spend with every channel at zero and no completeness claim on it. */
+function zeroSpend() {
+	return {
+		iterations: 0,
+		tokens: zeroTokenUsage(),
+		usd: 0,
+		ms: 0
+	};
+}
+/**
+* The spend of work that HAPPENED and reported no usage receipt.
+*
+* Not the same value as {@link zeroSpend} even though both carry `{0,0}` tokens and `$0`. A bare
+* zero asserts a MEASUREMENT — "this ran and cost nothing" — and every consumer downstream reads it
+* that way: the pool keeps reporting `readout().tokensKnown === true`, the journal totals stay
+* clean, the OTEL span records a priced zero, and a caller's token-denominated ceiling can never
+* fire no matter how much the work really burned. A ceiling that cannot fire is worse than no
+* ceiling, because it reads as protection.
+*
+* `tokensKnown` is the marker the substrate already threads end to end for exactly this case
+* (`budget.ts`, `otel-spans.ts`, `spawn-journal.ts`, `supervisor.ts`): the work is recorded, the
+* zero is labelled a floor rather than a total, and every rollup that touches it reports its
+* balance as a ceiling rather than a measurement. Use this — never a bare zero — whenever a runtime
+* cannot see what its worker spent.
+*
+* The same rule applies to dollars. A dollar-capped run must refuse an executor whose billed spend
+* is unknowable; `budgetExempt` does not authorize Runtime to relabel unknown spend as a measured
+* zero. Callers that require dollar accounting must use a backend with a trusted billing receipt.
+*/
+function unmeteredSpend(ms) {
+	return {
+		iterations: 0,
+		tokens: zeroTokenUsage(),
+		tokensKnown: false,
+		usd: 0,
+		usdKnown: false,
+		ms
+	};
+}
+/** Copy a conserved spend without dropping a completeness marker or the catalog-priced part. */
+function cloneSpend(spend) {
+	return {
+		...addResourceSpend(spend.resources),
+		iterations: spend.iterations,
+		tokens: cloneTokenUsage(spend.tokens),
+		...spend.tokensKnown === false ? { tokensKnown: false } : {},
+		usd: spend.usd,
+		...spend.usdKnown === false ? { usdKnown: false } : {},
+		...spend.usdEstimated !== void 0 ? { usdEstimated: spend.usdEstimated } : {},
+		ms: spend.ms,
+		...boxMinutesOf(spend),
+		...spend.tokensProvenance === void 0 ? {} : { tokensProvenance: spend.tokensProvenance }
+	};
+}
+/**
+* Sum two conserved spends per channel. Tokens and dollars never fold into each other, an
+* incomplete input keeps the sum incomplete on that channel, and the catalog-priced part of the
+* dollar total is summed separately so `usd - usdEstimated` still names what a provider billed.
+*/
+function addSpend(a, b) {
+	const tokens = cloneTokenUsage(a.tokens);
+	addTokenUsage(tokens, b.tokens);
+	return {
+		...addResourceSpend(a.resources, b.resources),
+		iterations: a.iterations + b.iterations,
+		tokens,
+		...a.tokensKnown === false || b.tokensKnown === false ? { tokensKnown: false } : {},
+		usd: a.usd + b.usd,
+		...a.usdKnown === false || b.usdKnown === false ? { usdKnown: false } : {},
+		...usdEstimatedOf(a, b),
+		ms: a.ms + b.ms,
+		...boxMinutesOf(a, b),
+		...tokensProvenanceOf(a, b)
+	};
+}
+/**
+* Fold the token-provenance channel across spends, as a field to spread.
+*
+* Returns nothing when no contributor stated one, because ABSENT already means "the executor's own
+* live stream", which is what every path reported before a harness store was readable. A
+* contributor that stated one and a contributor that did not therefore disagree, and the sum is
+* `'mixed'` — the honest answer for a tree whose spend came from two kinds of receipt.
+*/
+function tokensProvenanceOf(...spends) {
+	let folded;
+	let sawStated = false;
+	for (const spend of spends) {
+		const stated = spend.tokensProvenance ?? "stream-receipt";
+		if (spend.tokensProvenance !== void 0) sawStated = true;
+		folded = folded === void 0 || folded === stated ? stated : "mixed";
+	}
+	return !sawStated || folded === void 0 || folded === "stream-receipt" ? {} : { tokensProvenance: folded };
+}
+/**
+* Fold the platform box-time channel across spends, as a field to spread.
+*
+* Returns nothing when no input carried the channel, so a fold over router or cli-bridge work —
+* which runs no box at all — never gains a `boxMinutesProvenance: 'uncaptured'` that would claim
+* a box ran and went unmetered.
+*
+* Three rules, one per field:
+*  - `boxMinutes` sums the numbers that are present, and stays ABSENT when none is. A missing
+*    measurement never enters the sum as a zero.
+*  - `boxMinutesKnown` is sticky-false, like `tokensKnown`: one contributor that could not state
+*    its box time makes the whole sum a floor.
+*  - `boxMinutesProvenance` degrades. `'observed'` survives only when every contributor that
+*    carried a number was observed; one derived number makes the sum `'estimated'`; no number at
+*    all is `'uncaptured'`.
+*/
+function boxMinutesOf(...spends) {
+	const present = spends.filter((spend) => spend.boxMinutesProvenance !== void 0);
+	if (present.length === 0) return {};
+	let minutes = 0;
+	let sawNumber = false;
+	let known = true;
+	let observedOnly = true;
+	for (const spend of present) {
+		if (typeof spend.boxMinutes === "number" && Number.isFinite(spend.boxMinutes)) {
+			minutes += spend.boxMinutes;
+			sawNumber = true;
+			if (spend.boxMinutesProvenance !== "observed") observedOnly = false;
+		}
+		if (spend.boxMinutesKnown !== true) known = false;
+	}
+	return {
+		...sawNumber ? { boxMinutes: roundBoxMinutes(minutes) } : {},
+		boxMinutesKnown: known,
+		boxMinutesProvenance: sawNumber ? observedOnly ? "observed" : "estimated" : "uncaptured"
+	};
+}
+/**
+* Box minutes at four decimals — a tenth of a second.
+*
+* Fine enough that a box alive for two seconds reports `0.0333` instead of a zero that would read
+* as a measured free box, and coarse enough that summing floats does not print
+* `1.5000000000000002`.
+*/
+function roundBoxMinutes(minutes) {
+	return Number(minutes.toFixed(4));
+}
+/** Copy a token subtotal without dropping optional provider cache telemetry. */
+function cloneTokenUsage(usage) {
+	const cacheBreakdownUnknown = usage.cacheBreakdownKnown === false || usage.input > 0 && !hasClassifiedCacheBreakdown(usage);
+	return {
+		input: usage.input,
+		output: usage.output,
+		...usage.tokensKnown === false ? { tokensKnown: false } : {},
+		...usage.freshInput !== void 0 ? { freshInput: usage.freshInput } : {},
+		...usage.cacheRead !== void 0 ? { cacheRead: usage.cacheRead } : {},
+		...usage.cacheWrite !== void 0 ? { cacheWrite: usage.cacheWrite } : {},
+		...cacheBreakdownUnknown ? { cacheBreakdownKnown: false } : {}
+	};
+}
+/** True only when every positive prompt token has a consistent cache classification. */
+function hasCompleteCacheBreakdown(usage) {
+	if (usage.cacheBreakdownKnown === false) return false;
+	return hasClassifiedCacheBreakdown(usage);
+}
+function hasClassifiedCacheBreakdown(usage) {
+	if (usage.input === 0) return true;
+	if (usage.freshInput === void 0 || usage.cacheRead === void 0 || usage.cacheWrite === void 0) return false;
+	return usage.freshInput + usage.cacheRead + usage.cacheWrite === usage.input;
+}
+/**
+* The token charge for one observation: every token counted ONCE, at the moment it first enters
+* the context — `input − cacheRead + output`.
+*
+* `input` is a rolled-up prompt total that re-counts a cached prefix on every turn that reads it,
+* so charging `input` makes a 100K prefix read 40 times cost 4.1M for content authored once. A
+* cache read is content that was already charged when it was written, so it is the one class the
+* charge subtracts. Under a complete split the result is exactly `freshInput + cacheWrite`. No
+* price weight is involved: this counts work, and money is a separate channel.
+*
+* The subtraction form is what makes the charge ADDITIVE. `input` and `cacheRead` both accumulate
+* through `addTokenUsage`, so the charge on an aggregate equals the sum of the charges on the
+* records that built it — including an aggregate that mixes classified and unclassified turns,
+* where the unclassified remainder is charged in full and only the reported cache reads are
+* credited. A form that read `freshInput + cacheWrite` directly loses that: one unclassified turn
+* would drop the whole aggregate to `input + output` and over-charge every classified turn with it.
+*
+* The one arithmetic guarantee: a set of classes that does not FIT inside the prompt total it
+* partitions credits nothing, so the charge is never below `output` and a class that overflows its
+* own total buys no tokens. It is not a guarantee against a provider that reports a cache read it
+* never served — that provider can under-report `input` just as easily, and the token channel is an
+* accounting unit, not a trust boundary. Prompt tokens the provider left unclassified are charged
+* in full, so a spend with no readable split charges an upper bound on newly-presented work rather
+* than a measurement, and every caller that enforces a ceiling must report the difference
+* (`BudgetPool` does it through `readout().cacheBreakdownKnown`).
+*/
+function chargedTokens(usage) {
+	return usage.input - creditedCacheRead(usage) + usage.output;
+}
+/** `cacheRead` if the reported classes fit inside `input`, else nothing. */
+function creditedCacheRead(usage) {
+	const { cacheRead } = usage;
+	if (cacheRead === void 0) return 0;
+	return classifiedTotal(usage, cacheRead) > usage.input ? 0 : cacheRead;
+}
+function classifiedTotal(usage, cacheRead) {
+	return (usage.freshInput ?? 0) + cacheRead + (usage.cacheWrite ?? 0);
+}
+/**
+* Translate one provider prompt-cache report into the prompt token classes `addTokenUsage` folds
+* and `chargedTokens` credits.
+*
+* The input is the open `promptCache` record an `llm_call` carries, keyed by the `PromptCacheUsage`
+* vocabulary (`readTokens`, `writeTokens`). Providers report that vocabulary unevenly, and the
+* three outcomes are different facts that must not collapse into one another:
+*
+*  - **Nothing reported** — no classes and no marker. The caller's own unknown handling decides,
+*    because a provider that says nothing about caching has not said the split is unknowable.
+*  - **Read and write both reported, and fitting inside `input`** — a complete partition, so
+*    `freshInput` is the remainder and the split is known.
+*  - **One counter reported, or classes that overflow `input`** — the counters that ARE measured
+*    pass through and `cacheBreakdownKnown` is false. A read with no write counter (OpenAI reports
+*    no write) still credits the read it measured, while declaring the rest unclassified so the
+*    charge stays a declared upper bound. An overflowing claim buys nothing: it cannot be a
+*    partition of a total it exceeds.
+*
+* A counter the provider did not report stays absent. A zero would claim the provider measured no
+* cache, which is a different fact from a provider that did not report.
+*/
+function promptCacheTokenClasses(input, promptCache) {
+	if (promptCache === void 0) return {};
+	const read = tokenCount(promptCache.readTokens);
+	const write = tokenCount(promptCache.writeTokens);
+	if (read === void 0 && write === void 0) return {};
+	if (input === void 0 || (read ?? 0) + (write ?? 0) > input) return { cacheBreakdownKnown: false };
+	if (read !== void 0 && write !== void 0) return {
+		freshInput: input - read - write,
+		cacheRead: read,
+		cacheWrite: write
+	};
+	return {
+		...read !== void 0 ? { cacheRead: read } : {},
+		...write !== void 0 ? { cacheWrite: write } : {},
+		cacheBreakdownKnown: false
+	};
+}
+function tokenCount(value) {
+	return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : void 0;
+}
+/**
+* Add the observed subtotal into `acc`; token and cache incompleteness are sticky.
+*
+* A delta whose classes do not FIT inside its own `input` contributes its prompt total and NO
+* classes. Folding them in would hide the overflow: the accumulator's larger `input` can absorb a
+* class total that overflowed the one delta that reported it, and `chargedTokens` would then credit
+* at the aggregate a cache read it refuses at the record. That is the one way the charge could come
+* out below the sum of the charges on the records that built it.
+*/
+function addTokenUsage(acc, delta) {
+	acc.input += delta.input ?? 0;
+	acc.output += delta.output ?? 0;
+	if (delta.tokensKnown === false) acc.tokensKnown = false;
+	const input = delta.input ?? 0;
+	const fits = classifiedTotal(delta, delta.cacheRead ?? 0) <= input;
+	if (fits) {
+		if (delta.freshInput !== void 0) acc.freshInput = (acc.freshInput ?? 0) + delta.freshInput;
+		if (delta.cacheRead !== void 0) acc.cacheRead = (acc.cacheRead ?? 0) + delta.cacheRead;
+		if (delta.cacheWrite !== void 0) acc.cacheWrite = (acc.cacheWrite ?? 0) + delta.cacheWrite;
+	}
+	const classified = fits && delta.freshInput !== void 0 && delta.cacheRead !== void 0 && delta.cacheWrite !== void 0 && delta.freshInput + delta.cacheRead + delta.cacheWrite === input;
+	if (delta.cacheBreakdownKnown === false || input > 0 && !classified) acc.cacheBreakdownKnown = false;
+}
+/**
+* Map `items` through `fn` with at most `limit` calls in flight at once,
+* preserving input order in the result. On the first `fn` rejection no NEW
+* items are picked up; already-in-flight calls are awaited, then the first
+* error is rethrown. `limit` is clamped to ≥ 1.
+*
+* Used where a burst of provisioning (e.g. forking N child boxes) must respect
+* the loop's concurrency bound instead of firing all N at once.
+*/
+async function mapWithConcurrency(items, limit, fn) {
+	const results = new Array(items.length);
+	let next = 0;
+	for await (const settled of runTaskQueue({
+		concurrency: Math.max(1, Math.min(Math.floor(limit), items.length)),
+		take: () => {
+			const index = next++;
+			return index < items.length ? {
+				id: String(index),
+				value: index
+			} : void 0;
+		},
+		execute: ({ value: index }) => fn(items[index], index)
+	})) {
+		if (settled.status === "rejected") throw settled.reason;
+		results[settled.task.value] = settled.value;
+	}
+	return results;
+}
+/** The message of a thrown value: an `Error`'s own message, anything else stringified. */
+function errorMessage(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+/** True for an object whose `Symbol.asyncIterator` is callable, so `for await` can consume it. */
+function isAsyncIterable(value) {
+	return value !== null && typeof value === "object" && typeof value[Symbol.asyncIterator] === "function";
+}
+/** 32-bit FNV-1a over a string's UTF-16 code units, as eight lowercase hex digits. */
+function fnv1a32Hex(text) {
+	let h = 2166136261;
+	for (let i = 0; i < text.length; i += 1) {
+		h ^= text.charCodeAt(i);
+		h = Math.imul(h, 16777619);
+	}
+	return (h >>> 0).toString(16).padStart(8, "0");
+}
+//#endregion
 //#region src/candidate-execution/digest.ts
 /** Use native hashing for workspace archives. */
 function sha256Bytes$1(bytes) {
@@ -256,6 +870,7 @@ async function walkWorkspace(root, options, keepBytes) {
 		for (const entry of entries) {
 			options.signal?.throwIfAborted();
 			if (directory === absoluteRoot && ignoredProtectedRootEntries.has(entry.name)) continue;
+			if (options.skipPythonBytecode === true && (entry.isDirectory() && entry.name === "__pycache__" || entry.isFile() && entry.name.endsWith(".pyc"))) continue;
 			const absolute = resolve(directory, entry.name);
 			const relPath = relative(absoluteRoot, absolute).split(sep).join("/");
 			if (!relPath || relPath.startsWith("../") || relPath.includes("/../")) throw new Error(`workspace entry escapes root: ${relPath}`);
@@ -1307,6 +1922,83 @@ async function captureAgentCandidateWorkspaceToArtifacts(rootInput, options) {
 		archive: archiveArtifact
 	}) });
 }
+/**
+* Store a workspace as a tree: each regular file the store does not already hold, then the
+* manifest. The store must find objects by content (`locate`) and stream them.
+*/
+async function captureAgentCandidateWorkspaceTreeToArtifacts(rootInput, options) {
+	const { outputArtifacts, executionId, signal } = options.artifactPersistence;
+	if (!outputArtifacts.putStream || !outputArtifacts.readStream || !outputArtifacts.locate) throw new Error("workspace tree persistence requires putStream, readStream and locate");
+	if (!executionId.trim()) throw new Error("candidate workspace artifact persistence requires an executionId");
+	signal?.throwIfAborted();
+	const limits = workspaceLimits(options.limits);
+	const material = await scanMaterializedWorkspaceManifest(rootInput, {
+		limits,
+		signal
+	});
+	validateManifest(material, limits);
+	const root = await realpath(resolve(rootInput));
+	let bytes = 0;
+	let storedBytes = 0;
+	for (const file of material.files) {
+		signal?.throwIfAborted();
+		bytes += file.byteLength;
+		if (await outputArtifacts.locate({
+			sha256: file.sha256,
+			byteLength: file.byteLength
+		}, signal === void 0 ? void 0 : { signal }) !== void 0) continue;
+		const stored = await persistCandidateOutputArtifactStream(outputArtifacts, {
+			executionId,
+			purpose: "candidate-workspace-file",
+			chunks: workspaceFileChunks(root, file, signal),
+			maxBytes: file.byteLength,
+			signal
+		});
+		if (stored.sha256 !== file.sha256 || stored.byteLength !== file.byteLength) throw new Error(`workspace file changed during capture: ${file.path}`);
+		storedBytes += file.byteLength;
+	}
+	const manifestBytes = canonicalCandidateBytes$1(material);
+	const manifest = await persistCandidateOutputArtifactStream(outputArtifacts, {
+		executionId,
+		purpose: "candidate-workspace-manifest",
+		chunks: oneChunk(manifestBytes),
+		maxBytes: manifestBytes.byteLength,
+		signal
+	});
+	const digest = canonicalCandidateDigest$1(material);
+	if (manifest.sha256 !== digest) throw new Error("candidate workspace manifest digest does not name its stored bytes");
+	return deepFreezeCandidate({
+		kind: "agent-candidate-workspace-tree",
+		digest,
+		manifest,
+		files: material.files.length,
+		bytes,
+		storedBytes
+	});
+}
+/**
+* Read a tree back by its digest and confirm the store holds every file it names. Returns the
+* manifest; reading a file is `artifacts.read` of what `locate` returns for its digest.
+*/
+async function verifyAgentCandidateWorkspaceTree(tree, artifacts, options = {}) {
+	const { signal } = options;
+	if (!artifacts.locate) throw new Error("workspace tree verification requires locate");
+	if (tree.manifest.sha256 !== tree.digest) throw new Error("workspace tree digest does not name its manifest");
+	signal?.throwIfAborted();
+	const bytes = await artifacts.read(tree.manifest);
+	verifyBytes(bytes, tree.manifest.sha256, tree.manifest.byteLength, "workspace tree manifest");
+	const material = JSON.parse(Buffer.from(bytes).toString("utf8"));
+	validateManifest(material, workspaceLimits(options.limits));
+	if (canonicalCandidateDigest$1(material) !== tree.digest) throw new Error("workspace tree manifest is not canonical");
+	for (const file of material.files) {
+		signal?.throwIfAborted();
+		if (await artifacts.locate({
+			sha256: file.sha256,
+			byteLength: file.byteLength
+		}, signal === void 0 ? void 0 : { signal }) === void 0) throw new Error(`workspace tree file is not in the store: ${file.path}`);
+	}
+	return material;
+}
 /** Verify durable regular-file workspace evidence without retaining archive or file contents. */
 async function verifyAgentCandidateWorkspaceArtifacts(input) {
 	await consumeWorkspaceArtifacts(input);
@@ -1510,6 +2202,6 @@ function asError(error) {
 	return error instanceof Error ? error : new Error(String(error));
 }
 //#endregion
-export { canonicalCandidateDocument as A, verifyBytes as C, verifiedArtifactChunks as D, verifyWorkspaceSnapshotArtifacts as E, sha256Bytes$1 as F, verifyCanonicalCandidateDocument as I, embeddedCandidateArtifact as M, immutableCandidateValue as N, canonicalCandidateBytes$1 as O, omitTopLevelDigest as P, scanMaterializedWorkspaceManifest as S, verifyMaterializedWorkspace as T, artifactCacheKey as _, captureAgentCandidateWorkspace as a, readMaterializedWorkspaceFiles as b, verifyAgentCandidateWorkspaceArchive as c, verifyCandidateCode as d, verifyTaskCheckout as f, WorkspaceScanLimitError as g, isWellFormedUnicode as h, verifyAgentCandidateWorkspaceArtifacts as i, deepFreezeCandidate as j, canonicalCandidateDigest$1 as k, persistCandidateOutputArtifact as l, assertExactObjectKeys as m, materializeAgentCandidateWorkspaceFromArtifacts as n, captureAgentCandidateWorkspaceFiles as o, verifyTaskOutcomePatch as p, readAgentCandidateWorkspaceArtifactFiles as r, createAgentCandidateWorkspacePort as s, captureAgentCandidateWorkspaceToArtifacts as t, readCandidateGitHubResource as u, candidateWorkspaceManifest as v, verifyMaterializedProfileWorkspace as w, readVerifiedArtifact as x, captureMaterializedWorkspace as y };
+export { randomUuid as $, canonicalCandidateBytes$1 as A, addTokenUsage as B, readVerifiedArtifact as C, verifyMaterializedWorkspace as D, verifyMaterializedProfileWorkspace as E, immutableCandidateValue as F, errorMessage as G, cloneSpend as H, omitTopLevelDigest as I, isAbortError as J, fnv1a32Hex as K, sha256Bytes$1 as L, canonicalCandidateDocument as M, deepFreezeCandidate as N, verifyWorkspaceSnapshotArtifacts as O, embeddedCandidateArtifact as P, randomSuffix as Q, verifyCanonicalCandidateDocument as R, readMaterializedWorkspaceFiles as S, teardownSurfaces as St, verifyBytes as T, cloneTokenUsage as U, chargedTokens as V, deleteBoxSafe as W, mapWithConcurrency as X, isAsyncIterable as Y, promptCacheTokenClasses as Z, isWellFormedUnicode as _, armDeadlineTimer as _t, verifyAgentCandidateWorkspaceArtifacts as a, unmeteredSpend as at, candidateWorkspaceManifest as b, singleFlightTeardown as bt, captureAgentCandidateWorkspaceFiles as c, zeroTokenUsage as ct, persistCandidateOutputArtifact as d, resourceTelemetry as dt, roundBoxMinutes as et, readCandidateGitHubResource as f, withBudgetResources as ft, assertExactObjectKeys as g, ROOT_DEADLINE_REASON as gt, verifyTaskOutcomePatch as h, DEFAULT_SUCCESSFUL_SHUTDOWN_MS as ht, readAgentCandidateWorkspaceArtifactFiles as i, throwIfAborted as it, canonicalCandidateDigest$1 as j, verifiedArtifactChunks as k, createAgentCandidateWorkspacePort as l, addResourceSpend as lt, verifyTaskCheckout as m, CHILD_DEADLINE_REASON as mt, captureAgentCandidateWorkspaceTreeToArtifacts as n, stringifySafe as nt, verifyAgentCandidateWorkspaceTree as o, withTimeout as ot, verifyCandidateCode as p, ACCEPTED_RESULT_GRACE_MS as pt, hasCompleteCacheBreakdown as q, materializeAgentCandidateWorkspaceFromArtifacts as r, throwAbort as rt, captureAgentCandidateWorkspace as s, zeroSpend as st, captureAgentCandidateWorkspaceToArtifacts as t, sleep as tt, verifyAgentCandidateWorkspaceArchive as u, assertResources as ut, WorkspaceScanLimitError as v, boundedChildDeadlineAt as vt, scanMaterializedWorkspaceManifest as w, captureMaterializedWorkspace as x, teardownExecutor as xt, artifactCacheKey as y, isDeadlineAbortReason as yt, addSpend as z };
 
-//# sourceMappingURL=workspace-streams-D5gHJdTb.js.map
+//# sourceMappingURL=workspace-streams-ILw0eWZ0.js.map