@workbench-ai/workbench-core 0.0.46

package/dist/execution-runtime-types.d.ts

@@ -0,0 +1,35 @@
+import type { HostedWorkbenchEnvironmentVersion, HostedWorkbenchJob, Json, SurfaceSnapshotFile, WorkbenchAdapterInvocation } from "@workbench-ai/workbench-contract";
+import type { GenericRunSpec, WorkbenchEngineCase } from "./generic-spec.ts";
+import type { WorkbenchExecutionProgressTarget } from "./execution-events.ts";
+import type { WorkbenchAdapterAuthBundle } from "./adapter-auth.ts";
+import type { WorkbenchAdapterOperation, WorkbenchAdapterManifest } from "@workbench-ai/workbench-protocol";
+export interface WorkbenchExecutionRuntimeInput {
+    job: HostedWorkbenchJob;
+    spec: GenericRunSpec;
+    environmentVersion?: Pick<HostedWorkbenchEnvironmentVersion, "id" | "imageRef" | "sourceHash" | "spec">;
+    environmentDockerfile?: string;
+    baseFiles: readonly SurfaceSnapshotFile[];
+    engineResolveFiles: readonly SurfaceSnapshotFile[];
+    engineCases: readonly WorkbenchEngineCase[];
+    traceFiles?: readonly SurfaceSnapshotFile[];
+    now?: string;
+    adapterAuthProfiles?: readonly WorkbenchAdapterAuthBundle[];
+    adapterManifests?: readonly WorkbenchAdapterManifest[];
+    adapterAuthRoot?: string;
+    adapterAuthRequest?: Json;
+    adapterAuthEnv?: Record<string, string>;
+    progress?: WorkbenchExecutionProgressTarget;
+    runtimeRegistry?: string;
+    pullImages?: boolean;
+    workdir?: string;
+    workspaceRoot?: string;
+}
+export interface WorkbenchWorkloadPhaseCommand {
+    kind: "optimizer" | "runner" | "engine";
+    label: string;
+    operation: WorkbenchAdapterOperation;
+    adapter?: WorkbenchAdapterInvocation;
+    command?: string;
+    okExitCodes?: number[];
+}
+//# sourceMappingURL=execution-runtime-types.d.ts.map

package/dist/execution-runtime-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execution-runtime-types.d.ts","sourceRoot":"","sources":["../src/execution-runtime-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,iCAAiC,EACjC,kBAAkB,EAClB,IAAI,EACJ,mBAAmB,EACnB,0BAA0B,EAC3B,MAAM,kCAAkC,CAAC;AAE1C,OAAO,KAAK,EACV,cAAc,EACd,mBAAmB,EACpB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EACV,gCAAgC,EACjC,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EACV,0BAA0B,EAC3B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EACV,yBAAyB,EACzB,wBAAwB,EACzB,MAAM,kCAAkC,CAAC;AAE1C,MAAM,WAAW,8BAA8B;IAC7C,GAAG,EAAE,kBAAkB,CAAC;IACxB,IAAI,EAAE,cAAc,CAAC;IACrB,kBAAkB,CAAC,EAAE,IAAI,CAAC,iCAAiC,EAAE,IAAI,GAAG,UAAU,GAAG,YAAY,GAAG,MAAM,CAAC,CAAC;IACxG,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,SAAS,EAAE,SAAS,mBAAmB,EAAE,CAAC;IAC1C,kBAAkB,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACnD,WAAW,EAAE,SAAS,mBAAmB,EAAE,CAAC;IAC5C,UAAU,CAAC,EAAE,SAAS,mBAAmB,EAAE,CAAC;IAC5C,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,mBAAmB,CAAC,EAAE,SAAS,0BAA0B,EAAE,CAAC;IAC5D,gBAAgB,CAAC,EAAE,SAAS,wBAAwB,EAAE,CAAC;IACvD,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,kBAAkB,CAAC,EAAE,IAAI,CAAC;IAC1B,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC,QAAQ,CAAC,EAAE,gCAAgC,CAAC;IAC5C,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,6BAA6B;IAC5C,IAAI,EAAE,WAAW,GAAG,QAAQ,GAAG,QAAQ,CAAC;IACxC,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,yBAAyB,CAAC;IACrC,OAAO,CAAC,EAAE,0BAA0B,CAAC;IACrC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB"}

package/dist/execution-runtime-types.js

@@ -0,0 +1 @@
+export {};

package/dist/execution-scheduler.d.ts

@@ -0,0 +1,31 @@
+import type { HostedWorkbenchJob } from "@workbench-ai/workbench-contract";
+import { type SandboxProviderHostCost, type SandboxProviderRequestedResources, type WorkbenchSandboxProviderName } from "./sandbox-backends/index.ts";
+export interface WorkbenchExecutionDagCapacity {
+    cpu: number;
+    memoryGb: number;
+    diskGb: number;
+}
+export interface WorkbenchExecutionDagResult {
+    jobs: HostedWorkbenchJob[];
+    maxConcurrency: number;
+    startedJobCount: number;
+    cancelledJobCount: number;
+}
+export interface WorkbenchExecutionDagRunInput {
+    jobs: readonly HostedWorkbenchJob[];
+    capacity: WorkbenchExecutionDagCapacity;
+    sandboxProvider: WorkbenchSandboxProviderName;
+    executeJob: (job: HostedWorkbenchJob) => Promise<HostedWorkbenchJob>;
+    now?: () => string;
+    onJobQueued?: (job: HostedWorkbenchJob) => void;
+    onJobStarted?: (job: HostedWorkbenchJob) => void;
+    onJobFinished?: (job: HostedWorkbenchJob) => void;
+}
+export declare function runWorkbenchExecutionDag(args: WorkbenchExecutionDagRunInput): Promise<WorkbenchExecutionDagResult>;
+export declare function workbenchJobDependencies(job: HostedWorkbenchJob): string[];
+export declare function workbenchJobResources(job: HostedWorkbenchJob): SandboxProviderRequestedResources;
+export declare function workbenchJobHostCost(job: HostedWorkbenchJob, provider: WorkbenchSandboxProviderName): SandboxProviderHostCost;
+export declare function addCapacity(left: WorkbenchExecutionDagCapacity, right: WorkbenchExecutionDagCapacity): WorkbenchExecutionDagCapacity;
+export declare function subtractCapacity(left: WorkbenchExecutionDagCapacity, right: WorkbenchExecutionDagCapacity): WorkbenchExecutionDagCapacity;
+export declare function capacityFits(available: WorkbenchExecutionDagCapacity, cost: WorkbenchExecutionDagCapacity): boolean;
+//# sourceMappingURL=execution-scheduler.d.ts.map

package/dist/execution-scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execution-scheduler.d.ts","sourceRoot":"","sources":["../src/execution-scheduler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,kBAAkB,EAEnB,MAAM,kCAAkC,CAAC;AAE1C,OAAO,EAEL,KAAK,uBAAuB,EAC5B,KAAK,iCAAiC,EACtC,KAAK,4BAA4B,EAClC,MAAM,6BAA6B,CAAC;AAErC,MAAM,WAAW,6BAA6B;IAC5C,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,2BAA2B;IAC1C,IAAI,EAAE,kBAAkB,EAAE,CAAC;IAC3B,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,MAAM,CAAC;IACxB,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,6BAA6B;IAC5C,IAAI,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACpC,QAAQ,EAAE,6BAA6B,CAAC;IACxC,eAAe,EAAE,4BAA4B,CAAC;IAC9C,UAAU,EAAE,CAAC,GAAG,EAAE,kBAAkB,KAAK,OAAO,CAAC,kBAAkB,CAAC,CAAC;IACrE,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,kBAAkB,KAAK,IAAI,CAAC;IAChD,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,kBAAkB,KAAK,IAAI,CAAC;IACjD,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,kBAAkB,KAAK,IAAI,CAAC;CACnD;AASD,wBAAsB,wBAAwB,CAC5C,IAAI,EAAE,6BAA6B,GAClC,OAAO,CAAC,2BAA2B,CAAC,CAuLtC;AAED,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,kBAAkB,GAAG,MAAM,EAAE,CAM1E;AAED,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,kBAAkB,GACtB,iCAAiC,CASnC;AAED,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,kBAAkB,EACvB,QAAQ,EAAE,4BAA4B,GACrC,uBAAuB,CAEzB;AAED,wBAAgB,WAAW,CACzB,IAAI,EAAE,6BAA6B,EACnC,KAAK,EAAE,6BAA6B,GACnC,6BAA6B,CAM/B;AAED,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,6BAA6B,EACnC,KAAK,EAAE,6BAA6B,GACnC,6BAA6B,CAM/B;AAED,wBAAgB,YAAY,CAC1B,SAAS,EAAE,6BAA6B,EACxC,IAAI,EAAE,6BAA6B,GAClC,OAAO,CAIT"}

package/dist/execution-scheduler.js

@@ -0,0 +1,241 @@
+import { sandboxProviderAdmissionForResources, } from "./sandbox-backends/index.js";
+const RESOURCE_EPSILON = 1e-9;
+export async function runWorkbenchExecutionDag(args) {
+    assertPositiveCapacity(args.capacity);
+    const now = args.now ?? (() => new Date().toISOString());
+    const jobsById = new Map();
+    const pending = new Map();
+    const terminal = new Map();
+    const running = new Map();
+    const dependencies = new Map();
+    const results = new Map();
+    const originalOrder = args.jobs.map((job) => job.id);
+    let activeCost = emptyCapacity();
+    let maxConcurrency = 0;
+    let startedJobCount = 0;
+    let cancelledJobCount = 0;
+    for (const job of args.jobs) {
+        if (jobsById.has(job.id)) {
+            throw new Error(`Execution DAG includes duplicate job id ${job.id}.`);
+        }
+        jobsById.set(job.id, job);
+    }
+    for (const job of args.jobs) {
+        const jobDependencies = workbenchJobDependencies(job);
+        dependencies.set(job.id, jobDependencies);
+        for (const dependencyId of jobDependencies) {
+            if (!jobsById.has(dependencyId)) {
+                throw new Error(`Job ${job.id} depends on unknown job ${dependencyId}.`);
+            }
+        }
+        if (isTerminalJob(job)) {
+            terminal.set(job.id, job);
+            results.set(job.id, job);
+            continue;
+        }
+        if (job.status !== "queued") {
+            throw new Error(`Job ${job.id} has unsupported initial DAG status ${job.status}.`);
+        }
+        pending.set(job.id, job);
+        args.onJobQueued?.(job);
+    }
+    while (pending.size > 0 || running.size > 0) {
+        const progressed = startReadyJobs();
+        if (running.size === 0) {
+            if (pending.size === 0) {
+                break;
+            }
+            const ready = readyPendingJobs();
+            if (ready.length > 0) {
+                const blocked = ready[0];
+                throw new Error(`Job ${blocked.id} requires ${formatCapacity(workbenchJobHostCost(blocked, args.sandboxProvider))}, ` +
+                    `which exceeds available dev capacity ${formatCapacity(args.capacity)}.`);
+            }
+            throw new Error(`Execution DAG cannot make progress; remaining jobs have cyclic or blocked dependencies: ${[...pending.keys()].join(", ")}.`);
+        }
+        if (!progressed || pending.size > 0) {
+            await Promise.race([...running.values()].map((entry) => entry.promise));
+        }
+    }
+    return {
+        jobs: originalOrder.map((jobId) => {
+            const result = results.get(jobId);
+            if (!result) {
+                throw new Error(`Execution DAG finished without result for job ${jobId}.`);
+            }
+            return result;
+        }),
+        maxConcurrency,
+        startedJobCount,
+        cancelledJobCount,
+    };
+    function startReadyJobs() {
+        let progressed = false;
+        for (const job of [...pending.values()]) {
+            const dependencyStatus = dependencyTerminalStatus(job);
+            if (dependencyStatus === "blocked") {
+                continue;
+            }
+            if (dependencyStatus !== "ready") {
+                cancelPendingJob(job, dependencyStatus);
+                progressed = true;
+                continue;
+            }
+            const cost = workbenchJobHostCost(job, args.sandboxProvider);
+            const available = subtractCapacity(args.capacity, activeCost);
+            if (!capacityFits(available, cost)) {
+                continue;
+            }
+            pending.delete(job.id);
+            activeCost = addCapacity(activeCost, cost);
+            const startedAt = now();
+            const runningJob = {
+                ...job,
+                status: "running",
+                startedAt,
+                updatedAt: startedAt,
+            };
+            startedJobCount += 1;
+            maxConcurrency = Math.max(maxConcurrency, running.size + 1);
+            args.onJobStarted?.(runningJob);
+            const promise = finishJob(runningJob, cost);
+            running.set(job.id, { cost, promise });
+            progressed = true;
+        }
+        return progressed;
+    }
+    function readyPendingJobs() {
+        return [...pending.values()].filter((job) => dependencyTerminalStatus(job) === "ready");
+    }
+    function dependencyTerminalStatus(job) {
+        const jobDependencies = dependencies.get(job.id) ?? [];
+        let blocked = false;
+        for (const dependencyId of jobDependencies) {
+            const dependency = terminal.get(dependencyId);
+            if (!dependency) {
+                blocked = true;
+                continue;
+            }
+            if (dependency.status === "failed") {
+                return "failed";
+            }
+            if (dependency.status === "cancelled") {
+                return "cancelled";
+            }
+            if (dependency.status !== "succeeded") {
+                blocked = true;
+            }
+        }
+        return blocked ? "blocked" : "ready";
+    }
+    function cancelPendingJob(job, dependencyStatus) {
+        pending.delete(job.id);
+        const finishedAt = now();
+        const cancelled = {
+            ...job,
+            status: "cancelled",
+            updatedAt: finishedAt,
+            finishedAt,
+            error: `Dependency ${dependencyStatus}.`,
+        };
+        cancelledJobCount += 1;
+        terminal.set(job.id, cancelled);
+        results.set(job.id, cancelled);
+        args.onJobFinished?.(cancelled);
+    }
+    async function finishJob(runningJob, cost) {
+        let completed;
+        try {
+            completed = await args.executeJob(runningJob);
+        }
+        catch (error) {
+            const finishedAt = now();
+            completed = {
+                ...runningJob,
+                status: "failed",
+                updatedAt: finishedAt,
+                finishedAt,
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+        finally {
+            activeCost = subtractCapacity(activeCost, cost);
+            running.delete(runningJob.id);
+        }
+        terminal.set(runningJob.id, completed);
+        results.set(runningJob.id, completed);
+        args.onJobFinished?.(completed);
+    }
+}
+export function workbenchJobDependencies(job) {
+    const input = jsonRecord(job.input);
+    const dependsOn = input.dependsOn;
+    return Array.isArray(dependsOn)
+        ? dependsOn.filter((entry) => typeof entry === "string")
+        : [];
+}
+export function workbenchJobResources(job) {
+    const resources = jsonRecord(jsonRecord(jsonRecord(job.input).execution).policy).resources;
+    const record = jsonRecord(resources);
+    return {
+        cpu: readPositiveResource(record.cpu, job.id, "resources.cpu"),
+        memoryGb: readPositiveResource(record.memoryGb, job.id, "resources.memoryGb"),
+        diskGb: readPositiveResource(record.diskGb, job.id, "resources.diskGb"),
+        timeoutMinutes: readPositiveResource(record.timeoutMinutes, job.id, "resources.timeoutMinutes"),
+    };
+}
+export function workbenchJobHostCost(job, provider) {
+    return sandboxProviderAdmissionForResources(provider, workbenchJobResources(job)).hostCost;
+}
+export function addCapacity(left, right) {
+    return {
+        cpu: left.cpu + right.cpu,
+        memoryGb: left.memoryGb + right.memoryGb,
+        diskGb: left.diskGb + right.diskGb,
+    };
+}
+export function subtractCapacity(left, right) {
+    return {
+        cpu: left.cpu - right.cpu,
+        memoryGb: left.memoryGb - right.memoryGb,
+        diskGb: left.diskGb - right.diskGb,
+    };
+}
+export function capacityFits(available, cost) {
+    return available.cpu + RESOURCE_EPSILON >= cost.cpu &&
+        available.memoryGb + RESOURCE_EPSILON >= cost.memoryGb &&
+        available.diskGb + RESOURCE_EPSILON >= cost.diskGb;
+}
+function emptyCapacity() {
+    return { cpu: 0, memoryGb: 0, diskGb: 0 };
+}
+function isTerminalJob(job) {
+    return job.status === "succeeded" || job.status === "failed" || job.status === "cancelled";
+}
+function assertPositiveCapacity(capacity) {
+    readPositiveNumber(capacity.cpu, "capacity.cpu");
+    readPositiveNumber(capacity.memoryGb, "capacity.memoryGb");
+    readPositiveNumber(capacity.diskGb, "capacity.diskGb");
+}
+function readPositiveResource(value, jobId, label) {
+    const number = typeof value === "number" ? value : Number(value);
+    if (!Number.isFinite(number) || number <= 0) {
+        throw new Error(`Job ${jobId} ${label} must be a positive number.`);
+    }
+    return number;
+}
+function readPositiveNumber(value, label) {
+    const number = typeof value === "number" ? value : Number(value);
+    if (!Number.isFinite(number) || number <= 0) {
+        throw new Error(`${label} must be a positive number.`);
+    }
+    return number;
+}
+function jsonRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : {};
+}
+function formatCapacity(capacity) {
+    return `${capacity.cpu} CPU, ${capacity.memoryGb} GiB memory, ${capacity.diskGb} GiB disk`;
+}

package/dist/execution-traces.d.ts

@@ -0,0 +1,16 @@
+import type { HostedWorkbenchJob, WorkbenchExecutionTrace } from "@workbench-ai/workbench-contract";
+export interface WorkbenchTraceMergeJob {
+    id: string;
+    trace: WorkbenchExecutionTrace;
+}
+export declare function finalizeWorkbenchExecutionTraceForJob(args: {
+    job: HostedWorkbenchJob;
+    stageId: string;
+    trace: WorkbenchExecutionTrace;
+}): WorkbenchExecutionTrace;
+export declare function mergeWorkbenchExecutionTracesByJob(args: {
+    traceIdPrefix: string;
+    stageId?: string | null;
+    jobs: readonly WorkbenchTraceMergeJob[];
+}): WorkbenchExecutionTrace;
+//# sourceMappingURL=execution-traces.d.ts.map

package/dist/execution-traces.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execution-traces.d.ts","sourceRoot":"","sources":["../src/execution-traces.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,kBAAkB,EAElB,uBAAuB,EACxB,MAAM,kCAAkC,CAAC;AAE1C,MAAM,WAAW,sBAAsB;IACrC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,uBAAuB,CAAC;CAChC;AAED,wBAAgB,qCAAqC,CAAC,IAAI,EAAE;IAC1D,GAAG,EAAE,kBAAkB,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,uBAAuB,CAAC;CAChC,GAAG,uBAAuB,CAsD1B;AAED,wBAAgB,kCAAkC,CAAC,IAAI,EAAE;IACvD,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,IAAI,EAAE,SAAS,sBAAsB,EAAE,CAAC;CACzC,GAAG,uBAAuB,CAoC1B"}

package/dist/execution-traces.js

@@ -0,0 +1,164 @@
+export function finalizeWorkbenchExecutionTraceForJob(args) {
+    const status = traceStatusForJob(args.job.status);
+    const terminal = isTerminalTraceStatus(status);
+    const attempt = Math.max(1, args.job.attempt || 1);
+    const startedAt = args.job.startedAt ?? args.job.createdAt;
+    const endedAt = terminal
+        ? args.job.finishedAt ?? args.job.updatedAt ?? startedAt
+        : null;
+    const spans = args.trace.spans.map((span) => ({
+        ...span,
+        stage_id: args.stageId,
+        stage_run_index: null,
+        status: terminal && span.status === "running" ? status : span.status,
+        ended_at: terminal && !span.ended_at ? endedAt : span.ended_at,
+    }));
+    const events = args.trace.events.map((event) => ({
+        ...event,
+        stage_id: args.stageId,
+        stage_run_index: null,
+    }));
+    const summaries = args.trace.summaries.map((summary) => finalizeTraceSummary({
+        summary,
+        job: args.job,
+        status,
+        terminal,
+        attempt: Math.max(1, summary.attempt_number || attempt),
+        stageId: args.stageId,
+        startedAt,
+        endedAt,
+        spans,
+    }));
+    if (!summaries.some((summary) => sameSummaryStage(summary, attempt, args.stageId))) {
+        summaries.push(finalizeTraceSummary({
+            summary: null,
+            job: args.job,
+            status,
+            terminal,
+            attempt,
+            stageId: args.stageId,
+            startedAt,
+            endedAt,
+            spans,
+        }));
+    }
+    return {
+        trace_id: args.trace.trace_id,
+        spans,
+        events,
+        summaries,
+    };
+}
+export function mergeWorkbenchExecutionTracesByJob(args) {
+    const spans = [];
+    const events = [];
+    const summaries = [];
+    for (const job of args.jobs) {
+        const prefix = sanitizeTraceComponent(job.id);
+        spans.push(...job.trace.spans.map((span) => ({
+            ...span,
+            id: `${prefix}:${span.id}`,
+            parent_id: span.parent_id ? `${prefix}:${span.parent_id}` : null,
+            stage_id: args.stageId ?? span.stage_id,
+            stage_run_index: null,
+            attributes: withTraceJobId(span.attributes, job.id),
+        })));
+        events.push(...job.trace.events.map((event) => ({
+            ...event,
+            id: `${prefix}:${event.id}`,
+            span_id: `${prefix}:${event.span_id}`,
+            stage_id: args.stageId ?? event.stage_id,
+            stage_run_index: null,
+            attributes: withTraceJobId(event.attributes, job.id),
+        })));
+        summaries.push(...job.trace.summaries.map((summary) => ({
+            ...summary,
+            stage_id: args.stageId ?? summary.stage_id,
+            stage_run_index: null,
+        })));
+    }
+    return {
+        trace_id: `${args.traceIdPrefix}-${args.jobs.map((job) => sanitizeTraceComponent(job.id)).join("-")}`,
+        spans: spans.sort(compareTraceSpans),
+        events: events.sort(compareTraceEvents),
+        summaries: summaries.sort(compareTraceSummaries),
+    };
+}
+function withTraceJobId(attributes, jobId) {
+    return {
+        ...attributes,
+        job_id: jobId,
+    };
+}
+function compareTraceSpans(left, right) {
+    return (left.started_at.localeCompare(right.started_at) ||
+        left.id.localeCompare(right.id));
+}
+function compareTraceEvents(left, right) {
+    return left.at.localeCompare(right.at) || left.id.localeCompare(right.id);
+}
+function compareTraceSummaries(left, right) {
+    return (left.started_at.localeCompare(right.started_at) ||
+        traceSummaryKey(left).localeCompare(traceSummaryKey(right)));
+}
+function traceSummaryKey(summary) {
+    return [
+        summary.attempt_number,
+        summary.stage_id ?? "attempt",
+        summary.stage_run_index ?? "none",
+    ].join(":");
+}
+function sanitizeTraceComponent(value) {
+    return value.replaceAll(/[^A-Za-z0-9_-]+/g, "-");
+}
+function finalizeTraceSummary(args) {
+    const startedAt = args.summary?.started_at ?? args.startedAt;
+    const endedAt = args.terminal ? args.summary?.ended_at ?? args.endedAt : args.summary?.ended_at ?? null;
+    return {
+        attempt_number: args.attempt,
+        stage_id: args.stageId,
+        stage_run_index: null,
+        status: args.terminal ? args.status : args.summary?.status ?? args.status,
+        started_at: startedAt,
+        ended_at: endedAt,
+        duration_ms: endedAt
+            ? durationBetween(startedAt, endedAt)
+            : args.summary?.duration_ms ?? 0,
+        tool_call_count: args.summary?.tool_call_count ??
+            args.spans.filter((span) => span.kind === "tool_call").length,
+        input_tokens: args.summary?.input_tokens ?? null,
+        output_tokens: args.summary?.output_tokens ?? null,
+        usage: args.summary?.usage ?? null,
+        final_output_present: args.summary?.final_output_present ??
+            Boolean(args.job.output),
+        error_message: args.summary?.error_message ??
+            (typeof args.job.error === "string" ? args.job.error : null),
+    };
+}
+function sameSummaryStage(summary, attempt, stageId) {
+    return summary.attempt_number === attempt &&
+        (summary.stage_id == null || summary.stage_id === stageId) &&
+        summary.stage_run_index == null;
+}
+function traceStatusForJob(status) {
+    if (status === "succeeded") {
+        return "completed";
+    }
+    if (status === "failed") {
+        return "failed";
+    }
+    if (status === "cancelled") {
+        return "canceled";
+    }
+    return "running";
+}
+function isTerminalTraceStatus(status) {
+    return status === "completed" || status === "failed" || status === "canceled";
+}
+function durationBetween(startedAt, endedAt) {
+    const start = Date.parse(startedAt);
+    const end = Date.parse(endedAt);
+    return Number.isFinite(start) && Number.isFinite(end)
+        ? Math.max(0, end - start)
+        : 0;
+}

package/dist/execution-usage.d.ts

@@ -0,0 +1,12 @@
+import type { EvaluationUsageStats, ExecutionRole, ExecutionUsage, UsageSummary } from "@workbench-ai/workbench-contract";
+export declare function extractExecutionUsageFromTrace(trace: unknown, provider: {
+    model?: string;
+}, providerId: string, events?: readonly unknown[]): UsageSummary | undefined;
+export declare function assignUsageRole(role: ExecutionRole, usage: UsageSummary | undefined): UsageSummary | undefined;
+export declare function usageSummaryFromExecutionUsage(usage: ExecutionUsage | undefined): UsageSummary | undefined;
+export declare function completeUsageSummary(usage: UsageSummary | undefined): UsageSummary | undefined;
+export declare function normalizeUsageSummary(value: unknown): UsageSummary | undefined;
+export declare function mergeUsageSummaries(summaries: readonly (UsageSummary | undefined)[]): UsageSummary | undefined;
+export declare function mergeUsageRoles(roles: Partial<Record<ExecutionRole, UsageSummary | undefined>>): UsageSummary | undefined;
+export declare function usageStats(summaries: readonly UsageSummary[]): EvaluationUsageStats | undefined;
+//# sourceMappingURL=execution-usage.d.ts.map

package/dist/execution-usage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execution-usage.d.ts","sourceRoot":"","sources":["../src/execution-usage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,oBAAoB,EACpB,aAAa,EACb,cAAc,EAId,YAAY,EACb,MAAM,kCAAkC,CAAC;AAiC1C,wBAAgB,8BAA8B,CAC5C,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,EAC5B,UAAU,EAAE,MAAM,EAClB,MAAM,GAAE,SAAS,OAAO,EAAO,GAC9B,YAAY,GAAG,SAAS,CAa1B;AAED,wBAAgB,eAAe,CAC7B,IAAI,EAAE,aAAa,EACnB,KAAK,EAAE,YAAY,GAAG,SAAS,GAC9B,YAAY,GAAG,SAAS,CAQ1B;AAED,wBAAgB,8BAA8B,CAC5C,KAAK,EAAE,cAAc,GAAG,SAAS,GAChC,YAAY,GAAG,SAAS,CAE1B;AAED,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,YAAY,GAAG,SAAS,GAC9B,YAAY,GAAG,SAAS,CAmB1B;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,YAAY,GAAG,SAAS,CAY9E;AAED,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,SAAS,CAAC,YAAY,GAAG,SAAS,CAAC,EAAE,GAC/C,YAAY,GAAG,SAAS,CAc1B;AAED,wBAAgB,eAAe,CAC7B,KAAK,EAAE,OAAO,CAAC,MAAM,CAAC,aAAa,EAAE,YAAY,GAAG,SAAS,CAAC,CAAC,GAC9D,YAAY,GAAG,SAAS,CAS1B;AAED,wBAAgB,UAAU,CACxB,SAAS,EAAE,SAAS,YAAY,EAAE,GACjC,oBAAoB,GAAG,SAAS,CAQlC"}