humanish 0.104.3 → 0.106.0

package/dist/run/contained-output.js

@@ -0,0 +1,351 @@
+import { constants } from "node:fs";
+import { lstat, mkdir, open, realpath, rename, unlink } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import path from "node:path";
+import { assertDirectoryIdentity, assertRegularFileOrMissing, isPathInside, prepareHumanishStorageDirectory, resolveExistingHumanishStorageDirectory, validatePreparedRunArtifactPaths, validatePreparedRunRootIdentity, } from "./paths.js";
+import { isNodeError } from "./type-guards.js";
+/**
+ * Prepare an arbitrary caller-selected output directory without changing the
+ * caller's resolution contract. Relative values resolve against baseDir;
+ * absolute values keep their authority. Every spelling is caller authority:
+ * existing aliases in the selected directory or its parents are canonicalized
+ * once, then bound by physical path and directory identity. Managed defaults
+ * must use a strict storage preparer instead.
+ */
+export async function prepareSelectedOutputDirectory(baseDir, selectedPath) {
+    assertPathText(selectedPath, "Output directory");
+    const requestedPath = path.resolve(baseDir, selectedPath);
+    const physicalPath = await prepareAbsoluteSelectedDirectory(requestedPath);
+    return captureSelectedOutputDirectory(requestedPath, physicalPath);
+}
+/** Prepare a strict `.humanish`-managed directory, then bind its identity. */
+export async function prepareManagedHumanishOutputDirectory(cwd, ...segments) {
+    const requestedPath = path.resolve(cwd, ".humanish", ...segments);
+    const preparedPath = await prepareHumanishStorageDirectory(cwd, ...segments);
+    const physicalPath = await realpath(preparedPath);
+    return captureSelectedOutputDirectory(requestedPath, physicalPath);
+}
+/** Bind an existing strict `.humanish` directory without creating storage. */
+export async function bindExistingManagedHumanishOutputDirectory(cwd, ...segments) {
+    const requestedPath = path.resolve(cwd, ".humanish", ...segments);
+    const existing = await resolveExistingHumanishStorageDirectory(cwd, ...segments);
+    if (!existing || existing !== requestedPath) {
+        return null;
+    }
+    return captureSelectedOutputDirectory(requestedPath, await realpath(existing));
+}
+/** Prepare an arbitrary caller-selected output file whose parent is independent. */
+export async function prepareSelectedOutputFile(baseDir, selectedPath) {
+    assertPathText(selectedPath, "Output file");
+    const requestedPath = path.resolve(baseDir, selectedPath);
+    const fileName = path.basename(requestedPath);
+    if (!fileName || requestedPath === path.parse(requestedPath).root) {
+        throw new Error("Output file must name a regular file.");
+    }
+    const requestedParent = path.dirname(requestedPath);
+    const physicalParent = await prepareAbsoluteSelectedDirectory(requestedParent);
+    const physicalPath = path.join(physicalParent, fileName);
+    await assertRegularFileOrMissing(physicalPath, "Selected output files");
+    const parentIdentity = await captureDirectoryIdentity(physicalParent);
+    const prepared = Object.freeze({
+        parentIdentity,
+        physicalParent,
+        physicalPath,
+        requestedPath,
+    });
+    await assertPreparedSelectedOutputFile(prepared);
+    return prepared;
+}
+export async function assertPreparedSelectedOutputDirectory(prepared) {
+    if (prepared.parentRun) {
+        await validatePreparedRunRootIdentity(prepared.parentRun);
+    }
+    const requestedPhysicalPath = await realpath(prepared.requestedPath);
+    if (requestedPhysicalPath !== prepared.physicalPath) {
+        throw new Error("Selected output root changed physical destination.");
+    }
+    await assertDirectoryIdentity(prepared.physicalPath, prepared.identity, "Selected output root identity changed after it was prepared.");
+}
+async function assertPreparedSelectedOutputFile(prepared) {
+    const requestedPhysicalParent = await realpath(path.dirname(prepared.requestedPath));
+    if (requestedPhysicalParent !== prepared.physicalParent) {
+        throw new Error("Selected output parent changed physical destination.");
+    }
+    await assertDirectoryIdentity(prepared.physicalParent, prepared.parentIdentity, "Selected output parent identity changed after it was prepared.");
+    await assertRegularFileOrMissing(prepared.physicalPath, "Selected output files");
+}
+export async function writePreparedSelectedOutputFile(prepared, data, encoding) {
+    await atomicWriteOutputFile(prepared.physicalParent, prepared.physicalPath, data, encoding, () => assertPreparedSelectedOutputFile(prepared));
+}
+/** Atomically write the sibling latest pointer bound by a prepared run token. */
+export async function writePreparedRunLatestPointer(prepared, data, encoding) {
+    await atomicWriteOutputFile(prepared.physicalRunsRoot, prepared.physicalLatestPointer, data, encoding, async () => {
+        await validatePreparedRunArtifactPaths(prepared);
+    });
+}
+export async function prepareContainedOutputDirectory(rootInput, relativePath) {
+    assertSafeRelativeOutputPath(relativePath, true);
+    const root = await resolveOutputRoot(rootInput);
+    return prepareDirectoryWithinRoot(root, normalizeRelativeOutputPath(relativePath));
+}
+/** Prepare and identity-bind a generated child directory under a prepared root. */
+export async function prepareContainedOutputDirectoryRoot(rootInput, relativePath) {
+    const root = await resolveOutputRoot(rootInput);
+    const physicalPath = await prepareContainedOutputDirectory(rootInput, relativePath);
+    const revalidatedRoot = await resolveOutputRoot(rootInput);
+    if (revalidatedRoot !== root) {
+        throw new Error("Output root changed after it was prepared.");
+    }
+    const parentRun = "physicalRunRoot" in rootInput ? rootInput : rootInput.parentRun;
+    return captureSelectedOutputDirectory(physicalPath, physicalPath, parentRun);
+}
+export async function prepareContainedOutputFile(rootInput, relativePath) {
+    assertSafeRelativeOutputPath(relativePath, false);
+    const root = await resolveOutputRoot(rootInput);
+    const absolute = path.resolve(root, normalizeRelativeOutputPath(relativePath));
+    if (!isPathInside(root, absolute) || absolute === root) {
+        throw new Error("Output file must stay inside its selected root.");
+    }
+    const parent = await prepareDirectoryWithinRoot(root, path.relative(root, path.dirname(absolute)));
+    const filePath = path.join(parent, path.basename(absolute));
+    await assertRegularFileOrMissing(filePath, "Selected output files");
+    return filePath;
+}
+export async function writeContainedOutputFile(rootInput, relativePath, data, encoding) {
+    const filePath = await prepareContainedOutputFile(rootInput, relativePath);
+    const root = await resolveOutputRoot(rootInput);
+    await atomicWriteOutputFile(path.dirname(filePath), filePath, data, encoding, async () => {
+        const validatedRoot = await resolveOutputRoot(rootInput);
+        if (validatedRoot !== root) {
+            throw new Error("Output root changed after it was prepared.");
+        }
+        await assertContainedDirectoryChain(root, path.dirname(filePath));
+        await assertRegularFileOrMissing(filePath, "Selected output files");
+    });
+}
+/** Read one regular file only when both lexical and physical paths stay in root. */
+export async function readContainedRegularFile(rootInput, relativePath) {
+    const handle = await openContainedRegularFile(rootInput, relativePath);
+    if (!handle)
+        return null;
+    try {
+        return await handle.readFile();
+    }
+    catch {
+        return null;
+    }
+    finally {
+        await handle.close().catch(() => { });
+    }
+}
+/**
+ * Whether a contained path is confirmed absent. A present entry that readContainedRegularFile
+ * refuses or fails to read is not absent.
+ */
+export async function containedPathAbsent(rootInput, relativePath) {
+    try {
+        assertSafeRelativeOutputPath(relativePath, false);
+        const root = await resolveOutputRoot(rootInput);
+        await lstat(path.resolve(root, normalizeRelativeOutputPath(relativePath)));
+        return false;
+    }
+    catch (error) {
+        return error.code === "ENOENT";
+    }
+}
+/** The caller owns this checked descriptor and must close it after reading/streaming. */
+export async function openContainedRegularFile(rootInput, relativePath) {
+    let handle;
+    try {
+        assertSafeRelativeOutputPath(relativePath, false);
+        const root = await resolveOutputRoot(rootInput);
+        const candidate = path.resolve(root, normalizeRelativeOutputPath(relativePath));
+        if (!isPathInside(root, candidate) || candidate === root) {
+            return null;
+        }
+        await assertContainedDirectoryChain(root, path.dirname(candidate));
+        const before = await lstat(candidate, { bigint: true });
+        if (before.isSymbolicLink() || !before.isFile() || before.nlink > 1n) {
+            return null;
+        }
+        const physicalFile = await realpath(candidate);
+        if (!isPathInside(root, physicalFile)) {
+            return null;
+        }
+        handle = await open(candidate, constants.O_RDONLY | constants.O_NOFOLLOW);
+        const after = await handle.stat({ bigint: true });
+        if (!after.isFile() ||
+            after.nlink > 1n ||
+            after.dev !== before.dev ||
+            after.ino !== before.ino) {
+            throw new Error("Artifact identity changed.");
+        }
+        const revalidatedRoot = await resolveOutputRoot(rootInput);
+        if (revalidatedRoot !== root) {
+            throw new Error("Artifact root changed.");
+        }
+        await assertContainedDirectoryChain(root, path.dirname(candidate));
+        return handle;
+    }
+    catch {
+        await handle?.close().catch(() => { });
+        return null;
+    }
+}
+export function assertSafeOutputPathSegment(value, label = "Output path segment") {
+    if (value.length === 0 ||
+        value === "." ||
+        value === ".." ||
+        value.includes("/") ||
+        value.includes("\\") ||
+        value.includes("\0")) {
+        throw new Error(`${label} must be one non-empty path segment.`);
+    }
+}
+function assertSafeRelativeOutputPath(value, allowEmpty) {
+    if ((!allowEmpty && value.length === 0) || value.includes("\0")) {
+        throw new Error("Output path must be a non-empty relative path.");
+    }
+    if (value === "" && allowEmpty) {
+        return;
+    }
+    if (path.isAbsolute(value) || path.posix.isAbsolute(value) || path.win32.isAbsolute(value)) {
+        throw new Error("Output path must be relative to its selected root.");
+    }
+    const parts = value.replace(/\\/g, "/").split("/");
+    if (parts.some((part) => part.length === 0 || part === "." || part === "..")) {
+        throw new Error("Output path must not contain empty or traversal segments.");
+    }
+}
+function normalizeRelativeOutputPath(value) {
+    return value.replace(/[\\/]+/g, path.sep);
+}
+async function prepareDirectoryWithinRoot(root, relativePath) {
+    const segments = relativePath === "" ? [] : relativePath.replace(/[\\/]+/g, path.sep).split(path.sep);
+    let current = root;
+    for (const segment of segments) {
+        assertSafeOutputPathSegment(segment);
+        current = path.join(current, segment);
+        await mkdirDirectoryLeaf(current);
+    }
+    const physical = await realpath(current);
+    if (!isPathInside(root, physical)) {
+        throw new Error("Output directory resolved outside its selected root.");
+    }
+    return physical;
+}
+async function captureSelectedOutputDirectory(requestedPath, physicalPath, parentRun) {
+    const prepared = Object.freeze({
+        identity: await captureDirectoryIdentity(physicalPath),
+        ...(parentRun === undefined ? {} : { parentRun }),
+        physicalPath,
+        requestedPath,
+    });
+    await assertPreparedSelectedOutputDirectory(prepared);
+    return prepared;
+}
+async function prepareAbsoluteSelectedDirectory(absolutePath) {
+    const resolved = path.resolve(absolutePath);
+    try {
+        const existing = await lstat(resolved);
+        if (!existing.isDirectory() && !existing.isSymbolicLink()) {
+            throw new Error("Selected output root must resolve to a directory.");
+        }
+        const physical = await realpath(resolved);
+        const physicalStats = await lstat(physical);
+        if (!physicalStats.isDirectory()) {
+            throw new Error("Selected output root must resolve to a directory.");
+        }
+        return physical;
+    }
+    catch (error) {
+        if (!isNodeError(error) || error.code !== "ENOENT") {
+            throw error;
+        }
+    }
+    await mkdir(path.dirname(resolved), { recursive: true });
+    const physicalParent = await resolveBaseDirectory(path.dirname(resolved), "Selected output parent");
+    const selectedLeaf = path.join(physicalParent, path.basename(resolved));
+    await mkdirDirectoryLeaf(selectedLeaf);
+    return realpath(selectedLeaf);
+}
+async function mkdirDirectoryLeaf(directory) {
+    try {
+        await mkdir(directory);
+    }
+    catch (error) {
+        if (!isNodeError(error) || error.code !== "EEXIST") {
+            throw error;
+        }
+    }
+    const stats = await lstat(directory, { bigint: true });
+    if (stats.isSymbolicLink() || !stats.isDirectory()) {
+        throw new Error("Selected output directories must not be symbolic links or non-directories.");
+    }
+}
+async function resolveOutputRoot(root) {
+    if ("physicalRunRoot" in root) {
+        await validatePreparedRunRootIdentity(root);
+        return root.physicalRunRoot;
+    }
+    await assertPreparedSelectedOutputDirectory(root);
+    return root.physicalPath;
+}
+async function resolveBaseDirectory(directory, label) {
+    const physical = await realpath(path.resolve(directory));
+    const stats = await lstat(physical);
+    if (!stats.isDirectory()) {
+        throw new Error(`${label} must be a directory.`);
+    }
+    return physical;
+}
+async function captureDirectoryIdentity(directory) {
+    const stats = await lstat(directory, { bigint: true });
+    if (stats.isSymbolicLink() || !stats.isDirectory() || (await realpath(directory)) !== directory) {
+        throw new Error("Prepared output root must use a physical directory.");
+    }
+    return Object.freeze({ birthtimeNs: stats.birthtimeNs, dev: stats.dev, ino: stats.ino });
+}
+async function assertContainedDirectoryChain(root, directory) {
+    if (!isPathInside(root, directory)) {
+        throw new Error("Output directory must stay inside its selected root.");
+    }
+    const relative = path.relative(root, directory);
+    let current = root;
+    for (const segment of relative === "" ? [] : relative.split(path.sep)) {
+        current = path.join(current, segment);
+        const stats = await lstat(current);
+        if (stats.isSymbolicLink() || !stats.isDirectory()) {
+            throw new Error("Selected output directories must not be symbolic links or non-directories.");
+        }
+    }
+}
+async function atomicWriteOutputFile(parent, target, data, encoding, revalidate) {
+    await revalidate();
+    const temporary = path.join(parent, `.humanish-write-${process.pid}-${randomUUID()}.tmp`);
+    let handle;
+    try {
+        handle = await open(temporary, "wx", 0o600);
+        if (typeof data === "string") {
+            await handle.writeFile(data, encoding ?? "utf8");
+        }
+        else {
+            await handle.writeFile(data);
+        }
+        await handle.sync();
+        await handle.close();
+        handle = undefined;
+        await revalidate();
+        await rename(temporary, target);
+        await assertRegularFileOrMissing(target, "Selected output files");
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+        await unlink(temporary).catch(() => undefined);
+    }
+}
+function assertPathText(value, label) {
+    if (value.includes("\0")) {
+        throw new Error(`${label} must not contain a null byte.`);
+    }
+}

package/dist/run/cost-summary.d.ts

@@ -0,0 +1,28 @@
+import type { ActorTrace } from "../actors/contract.js";
+import type { DesktopResourceObservation } from "../substrates/e2b/desktop-resources.js";
+import { type RunCostSummary } from "./bundle.js";
+/** One hosted sandbox's observed lifetime and size. */
+export interface DesktopUsage {
+    /** The participant the sandbox belonged to, saved on its cost lines as `laneId`. */
+    participantId?: string;
+    minutes: number | undefined;
+    observation: DesktopResourceObservation | undefined;
+    lifetimeComplete: boolean;
+}
+/** One participant's trace; its id is saved on the participant's cost lines as `laneId`. */
+type CostParticipant = {
+    participantId?: string;
+    trace: ActorTrace;
+};
+interface CostArgs {
+    participants: CostParticipant[];
+    /** Legacy library input: uses a labeled planning assumption; live routes use desktops. */
+    desktopMinutes?: number | undefined;
+    desktops?: DesktopUsage[];
+}
+export declare function buildRunCostSummary(args: CostArgs): RunCostSummary | undefined;
+/** A live run that sent no model request and held no hosted desktop records an explicit zero, so
+ *  a missing cost block always means "not measured". */
+export declare function spendFreeCostSummary(): RunCostSummary;
+export declare function desktopSpanToMinutes(desktopDurationMs: number | undefined): number | undefined;
+export {};

package/dist/run/cost-summary.js

@@ -0,0 +1,213 @@
+import { estimateActorCostForExecution, estimateAllocatedDesktopCost, estimateDesktopCost, round6, } from "./pricing.js";
+import {} from "./bundle.js";
+export function buildRunCostSummary(args) {
+    const breakdown = [...modelCostLines(args.participants), ...desktopCostLines(args)];
+    if (breakdown.length === 0) {
+        return undefined;
+    }
+    const totals = costTotals(breakdown);
+    return {
+        schema: "humanish.run-cost-summary.v1",
+        currency: "usd",
+        estimatedTotalUsd: totals.estimatedTotalUsd,
+        ratesAsOf: totals.minRatesAsOf,
+        fullyEstimated: !totals.anyNull,
+        placeholder: totals.placeholder,
+        breakdown,
+        tokenUsage: runTokenUsage(args.participants),
+        desktopMinutes: runDesktopMinutes(args),
+        note: costNote(args, totals),
+    };
+}
+/** Each participant's model-token lines: an estimate, and a null line for each unreported part. */
+function modelCostLines(participants) {
+    const breakdown = [];
+    for (const participant of participants) {
+        const usage = participant.trace.tokenUsage;
+        // A stalled/ambiguous interaction can remain unreported after a later successful retry.
+        // Keep known token estimates and make the additional unknown explicit.
+        if (participant.trace.interactionUsageIncomplete === true) {
+            breakdown.push({
+                kind: "model-tokens",
+                ...(participant.participantId === undefined ? {} : { laneId: participant.participantId }),
+                ...(participant.trace.providerVersion === undefined
+                    ? {}
+                    : { modelId: participant.trace.providerVersion }),
+                estimatedCostUsd: null,
+                reason: "interaction_usage_unreported",
+                ratesAsOf: null,
+            });
+        }
+        // An attempted closing request has its own accounting boundary.
+        if (participant.trace.debrief?.usageReported === false) {
+            breakdown.push({
+                kind: "model-tokens",
+                ...(participant.participantId === undefined ? {} : { laneId: participant.participantId }),
+                ...(participant.trace.providerVersion === undefined
+                    ? {}
+                    : { modelId: participant.trace.providerVersion }),
+                estimatedCostUsd: null,
+                reason: "closing_usage_unreported",
+                ratesAsOf: null,
+            });
+        }
+        const est = participant.trace.executionProfile?.billing === "account-unknown"
+            ? estimateActorCostForExecution(usage, participant.trace.ids.model, participant.trace.executionProfile)
+            : participant.trace.estimatedCost;
+        if (!est) {
+            continue;
+        }
+        breakdown.push({
+            kind: "model-tokens",
+            ...(participant.participantId === undefined ? {} : { laneId: participant.participantId }),
+            ...(est.modelId === undefined ? {} : { modelId: est.modelId }),
+            estimatedCostUsd: est.estimatedCostUsd,
+            ...(est.reason === undefined ? {} : { reason: est.reason }),
+            ratesAsOf: est.ratesAsOf,
+            ...(est.source === undefined ? {} : { source: est.source }),
+            ...(est.placeholder ? { placeholder: true } : {}),
+        });
+    }
+    return breakdown;
+}
+/** Each hosted sandbox's compute line, or the legacy planning line when only minutes are given. */
+function desktopCostLines(args) {
+    const breakdown = [];
+    for (const usage of args.desktops ?? []) {
+        const observation = usage.observation;
+        const resources = observation && "resources" in observation ? observation.resources : undefined;
+        const estimate = estimateAllocatedDesktopCost(usage.minutes, resources);
+        breakdown.push({
+            kind: "desktop-minutes",
+            ...(usage.participantId === undefined ? {} : { laneId: usage.participantId }),
+            estimatedCostUsd: estimate.estimatedCostUsd,
+            ...(estimate.reason === undefined ? {} : { reason: estimate.reason }),
+            ratesAsOf: estimate.ratesAsOf,
+            ...(estimate.source === undefined ? {} : { source: estimate.source }),
+            desktop: {
+                minutes: estimate.minutes,
+                durationBasis: "host-acquired-to-cleanup",
+                ...(resources === undefined ? {} : { resources, resourceSource: "e2b.getInfo" }),
+                ...(observation && "reason" in observation
+                    ? { resourceUnavailableReason: observation.reason }
+                    : {}),
+                ...(estimate.usdPerSecond === undefined ? {} : { usdPerSecond: estimate.usdPerSecond }),
+            },
+        });
+        if (!usage.lifetimeComplete) {
+            breakdown.push({
+                kind: "desktop-minutes",
+                ...(usage.participantId === undefined ? {} : { laneId: usage.participantId }),
+                estimatedCostUsd: null,
+                reason: "desktop_lifetime_incomplete",
+                ratesAsOf: null,
+            });
+        }
+    }
+    if (args.desktops === undefined && args.desktopMinutes !== undefined) {
+        const desktop = estimateDesktopCost(args.desktopMinutes);
+        breakdown.push({
+            kind: "desktop-minutes",
+            estimatedCostUsd: desktop.estimatedCostUsd,
+            ...(desktop.reason === undefined ? {} : { reason: desktop.reason }),
+            ratesAsOf: desktop.ratesAsOf,
+            ...(desktop.source === undefined ? {} : { source: desktop.source }),
+            ...(desktop.placeholder ? { placeholder: true } : {}),
+        });
+    }
+    return breakdown;
+}
+/** The priced total and its freshness; a null line makes the total a lower bound. */
+function costTotals(breakdown) {
+    let knownSum = 0;
+    let anyKnown = false;
+    let anyNull = false;
+    let placeholder = false;
+    // Aggregate freshness is CONSERVATIVE: an aggregate estimate is only as current as its OLDEST
+    // contributing rate, so ratesAsOf takes the MIN (oldest) asOf — MAX would overclaim freshness the
+    // moment operator-edited rates in src/run/pricing.ts diverge. Each breakdown line keeps its own true asOf.
+    let minRatesAsOf = null;
+    for (const line of breakdown) {
+        if (line.estimatedCostUsd === null) {
+            anyNull = true;
+            continue;
+        }
+        anyKnown = true;
+        knownSum += line.estimatedCostUsd;
+        if (line.placeholder)
+            placeholder = true;
+        if (line.ratesAsOf !== null && (minRatesAsOf === null || line.ratesAsOf < minRatesAsOf)) {
+            minRatesAsOf = line.ratesAsOf;
+        }
+    }
+    return {
+        estimatedTotalUsd: anyKnown ? round6(knownSum) : null,
+        anyNull,
+        placeholder,
+        minRatesAsOf,
+    };
+}
+/** The summary's note: what the total means, then what the desktop lines measured. */
+function costNote(args, totals) {
+    const { estimatedTotalUsd, anyNull, placeholder, minRatesAsOf } = totals;
+    const estimateNote = estimatedTotalUsd === null
+        ? `No priced spend lines this run — every cost line is DECLARED ABSENT (unknown rate / no usage / no duration); nothing is guessed. ${args.participants.some((participant) => participant.trace.executionProfile?.billing === "account-unknown") ? "Account billing remains unknown; API prices do not measure account spend." : "Add a rate to src/run/pricing.ts to estimate this model."}`
+        : `Estimated ${estimatedTotalUsd} USD total${anyNull ? " (LOWER BOUND — some lines unmeasured/unpriced)" : ""}${placeholder ? "; includes PLACEHOLDER rate(s) — confirm before trusting the magnitude" : ""}. Every figure is an ESTIMATE (rates as of ${minRatesAsOf} — the OLDEST contributing rate, since an aggregate is only as fresh as its stalest input), a rate-table multiply, NOT an authoritative provider charge.`;
+    return (estimateNote +
+        ((args.desktops?.length ?? 0) > 0
+            ? args.desktops.some((usage) => usage.observation !== undefined && "resources" in usage.observation)
+                ? " Desktop compute uses observed CPU/RAM and a host-acquired-to-cleanup span where available; pre-handle startup, plan fees, credits, and negotiated pricing are excluded."
+                : " Desktop compute is unmeasured: no allocation CPU/RAM observation is available."
+            : ""));
+}
+/** Token totals across participants; an account-billed participant leaves unknown parts out. */
+function runTokenUsage(participants) {
+    const sumInput = participants.reduce((sum, participant) => sum + (participant.trace.tokenUsage?.input ?? 0), 0);
+    const sumOutput = participants.reduce((sum, participant) => sum + (participant.trace.tokenUsage?.output ?? 0), 0);
+    return participants.some((participant) => participant.trace.executionProfile?.billing === "account-unknown")
+        ? {
+            ...(participants.some((participant) => participant.trace.tokenUsage?.input !== undefined)
+                ? { input: sumInput }
+                : {}),
+            ...(participants.some((participant) => participant.trace.tokenUsage?.output !== undefined)
+                ? { output: sumOutput }
+                : {}),
+            ...(participants.every((participant) => participant.trace.tokenUsage?.input !== undefined &&
+                participant.trace.tokenUsage?.output !== undefined &&
+                participant.trace.interactionUsageIncomplete !== true &&
+                participant.trace.debrief?.usageReported !== false &&
+                (participant.trace.executionProfile === undefined ||
+                    participant.trace.providerRequests?.every((r) => r.usageComplete) === true))
+                ? { total: sumInput + sumOutput }
+                : {}),
+        }
+        : { input: sumInput, output: sumOutput, total: sumInput + sumOutput };
+}
+/** Total desktop minutes, or null when no sandbox reported a span. */
+function runDesktopMinutes(args) {
+    return args.desktops === undefined
+        ? (args.desktopMinutes ?? null)
+        : args.desktops.some((usage) => usage.minutes !== undefined)
+            ? round6(args.desktops.reduce((sum, usage) => sum + (usage.minutes ?? 0), 0))
+            : null;
+}
+/** A live run that sent no model request and held no hosted desktop records an explicit zero, so
+ *  a missing cost block always means "not measured". */
+export function spendFreeCostSummary() {
+    return {
+        schema: "humanish.run-cost-summary.v1",
+        currency: "usd",
+        estimatedTotalUsd: 0,
+        ratesAsOf: null,
+        fullyEstimated: true,
+        placeholder: false,
+        breakdown: [],
+        tokenUsage: { input: 0, output: 0, total: 0 },
+        desktopMinutes: null,
+        note: "No model request and no hosted desktop: this run spent $0 by construction.",
+    };
+}
+// Convert a host-side desktop span (ms) into billed minutes, or undefined when no sandbox ran.
+export function desktopSpanToMinutes(desktopDurationMs) {
+    return desktopDurationMs === undefined ? undefined : desktopDurationMs / 60_000;
+}