@workbench-ai/workbench-core 0.0.46

package/dist/execution-outputs.js

@@ -0,0 +1,393 @@
+import { normalizeUsageSummary } from "./execution-usage.js";
+export function validateWorkbenchExecutionOutputPayloads(execution, payloads) {
+    const issues = [];
+    const declaredOutputs = new Map(execution.outputs.map((output) => [output.name, output]));
+    for (const output of execution.outputs) {
+        if (output.required && !(output.name in payloads)) {
+            issues.push(`Execution ${execution.id} did not produce required output ${output.name}.`);
+        }
+    }
+    for (const outputName of Object.keys(payloads)) {
+        if (!declaredOutputs.has(outputName)) {
+            issues.push(`Execution ${execution.id} produced undeclared output ${outputName}.`);
+        }
+    }
+    const validated = {};
+    for (const [name, payload] of Object.entries(payloads)) {
+        const contract = declaredOutputs.get(name);
+        if (!contract) {
+            continue;
+        }
+        switch (contract.schema) {
+            case "workbench.subject_patch.v1":
+                validated.subjectPatch = normalizeSubjectPatch(payload, execution, contract, issues);
+                break;
+            case "workbench.result.v1":
+                validated.result = normalizeResult(payload, execution, contract, issues);
+                break;
+            default:
+                break;
+        }
+    }
+    if (issues.length > 0) {
+        throw new Error(issues.join("\n"));
+    }
+    return validated;
+}
+export function collectWorkbenchExecutionIsolationIssues(execution) {
+    const issues = [];
+    if (!execution.policy.tenantId.trim()) {
+        issues.push(`Execution ${execution.id} must include a non-empty tenant id.`);
+    }
+    if (!execution.projectId.trim()) {
+        issues.push(`Execution ${execution.id} must include a project id.`);
+    }
+    if (!execution.runId.trim()) {
+        issues.push(`Execution ${execution.id} must include a run id.`);
+    }
+    if (!execution.sandbox.ref.trim()) {
+        issues.push(`Execution ${execution.id} must include a sandbox template ref.`);
+    }
+    if (execution.sandbox.kind !== "oci" && execution.sandbox.kind !== "snapshot") {
+        issues.push(`Execution ${execution.id} has unsupported sandbox kind ${execution.sandbox.kind}.`);
+    }
+    const inputNames = new Set();
+    const mountPaths = new Set();
+    const expectedInputs = expectedInputsForPurpose(execution.purpose);
+    for (const input of execution.inputs) {
+        if (!input.name.trim()) {
+            issues.push(`Execution ${execution.id} has an input with an empty name.`);
+        }
+        if (inputNames.has(input.name)) {
+            issues.push(`Execution ${execution.id} declares duplicate input ${input.name}.`);
+        }
+        inputNames.add(input.name);
+        if (!input.ref.trim()) {
+            issues.push(`Execution ${execution.id} input ${input.name} must include a ref.`);
+        }
+        if (!expectedInputs.has(input.name)) {
+            issues.push(`Execution ${execution.id} declares unsupported input ${input.name} for purpose ${execution.purpose}.`);
+        }
+        const expectedMountPath = `/workspace/input/${input.name}`;
+        if (input.mountPath !== expectedMountPath) {
+            issues.push(`Execution ${execution.id} input ${input.name} must mount at ${expectedMountPath}.`);
+        }
+        if (mountPaths.has(input.mountPath)) {
+            issues.push(`Execution ${execution.id} declares duplicate mount path ${input.mountPath}.`);
+        }
+        mountPaths.add(input.mountPath);
+        if (input.writable) {
+            issues.push(`Execution ${execution.id} inputs must be read-only.`);
+        }
+    }
+    for (const expectedInput of expectedInputs) {
+        if (!inputNames.has(expectedInput)) {
+            issues.push(`Execution ${execution.id} missing required input ${expectedInput} for purpose ${execution.purpose}.`);
+        }
+    }
+    const outputNames = new Set();
+    const expectedOutput = expectedOutputForPurpose(execution.purpose);
+    for (const output of execution.outputs) {
+        if (outputNames.has(output.name)) {
+            issues.push(`Execution ${execution.id} declares duplicate output ${output.name}.`);
+        }
+        outputNames.add(output.name);
+        if (expectedOutput === null) {
+            issues.push(`Execution ${execution.id} cannot declare outputs for purpose ${execution.purpose}.`);
+        }
+        else if (output.name !== expectedOutput) {
+            issues.push(`Execution ${execution.id} output for purpose ${execution.purpose} must be named ${expectedOutput}.`);
+        }
+        if (!outputAllowedForPurpose(execution.purpose, output)) {
+            issues.push(`Execution ${execution.id} cannot declare ${output.schema} for purpose ${execution.purpose}.`);
+        }
+    }
+    if (expectedOutput !== null && !outputNames.has(expectedOutput)) {
+        issues.push(`Execution ${execution.id} missing required output ${expectedOutput} for purpose ${execution.purpose}.`);
+    }
+    const resources = execution.policy.resources;
+    for (const [name, value] of Object.entries(resources)) {
+        if (!Number.isFinite(value) || value <= 0) {
+            issues.push(`Execution ${execution.id} policy.resources.${name} must be a positive number.`);
+        }
+    }
+    if (execution.policy.network.egress === "allowlist" && (!execution.policy.network.allow || execution.policy.network.allow.length === 0)) {
+        issues.push(`Execution ${execution.id} allowlist network policy must include at least one allowed host.`);
+    }
+    return issues;
+}
+function expectedInputsForPurpose(purpose) {
+    if (purpose === "improve") {
+        return new Set(["subject", "traces"]);
+    }
+    if (purpose === "attempt") {
+        return new Set(["subject", "case"]);
+    }
+    return new Set();
+}
+function expectedOutputForPurpose(purpose) {
+    if (purpose === "improve") {
+        return "subject_patch";
+    }
+    if (purpose === "attempt") {
+        return "result";
+    }
+    return null;
+}
+export function assertWorkbenchExecutionIsolation(execution) {
+    const issues = collectWorkbenchExecutionIsolationIssues(execution);
+    if (issues.length > 0) {
+        throw new Error(issues.join("\n"));
+    }
+}
+function outputAllowedForPurpose(purpose, output) {
+    if (purpose === "improve") {
+        return output.schema === "workbench.subject_patch.v1";
+    }
+    if (purpose === "attempt") {
+        return output.schema === "workbench.result.v1";
+    }
+    return false;
+}
+function normalizeSubjectPatch(value, execution, contract, issues) {
+    const record = readRecord(value, contract.name, issues);
+    const files = normalizeSnapshotFiles(record?.files, `${contract.name}.files`, issues);
+    const fileChanges = normalizeStringArray(record?.fileChanges, `${contract.name}.fileChanges`, issues);
+    const edits = normalizeMetadataStringArray(execution.metadata.edits);
+    if (edits.length === 0) {
+        issues.push(`Execution ${execution.id} subject patch validation requires metadata.edits.`);
+    }
+    for (const file of files) {
+        if (!isAllowedEditPath(file.path, edits)) {
+            issues.push(`${contract.name}.files contains path outside optimizer edits: ${file.path}.`);
+        }
+    }
+    for (const fileChange of fileChanges) {
+        if (!isSafeRelativePath(fileChange)) {
+            issues.push(`${contract.name}.fileChanges contains unsafe path ${fileChange}.`);
+        }
+        else if (!isAllowedEditPath(fileChange, edits)) {
+            issues.push(`${contract.name}.fileChanges contains path outside optimizer edits: ${fileChange}.`);
+        }
+    }
+    return {
+        files,
+        fileChanges,
+        ...(typeof record?.summary === "string" ? { summary: record.summary } : {}),
+        ...(isJson(record?.feedback) ? { feedback: record.feedback } : {}),
+    };
+}
+function normalizeResult(value, execution, contract, issues) {
+    void execution;
+    const record = readRecord(value, contract.name, issues);
+    const score = readFiniteNumber(record?.score, `${contract.name}.score`, issues);
+    const usage = normalizeUsageSummary(record?.usage);
+    return {
+        score: score ?? 0,
+        ...(record?.metrics !== undefined ? { metrics: normalizeNumberRecord(record.metrics, `${contract.name}.metrics`, issues) } : {}),
+        ...(record?.cases !== undefined ? { cases: normalizeCaseResults(record.cases, `${contract.name}.cases`, issues) } : {}),
+        ...(usage ? { usage } : {}),
+        ...(typeof record?.summary === "string" ? { summary: record.summary } : {}),
+        ...(isJson(record?.feedback) ? { feedback: record.feedback } : {}),
+    };
+}
+function normalizeSnapshotFiles(value, label, issues) {
+    if (!Array.isArray(value)) {
+        issues.push(`${label} must be an array.`);
+        return [];
+    }
+    return value.flatMap((entry, index) => {
+        const itemLabel = `${label}[${index}]`;
+        const record = readRecord(entry, itemLabel, issues);
+        if (!record) {
+            return [];
+        }
+        const filePath = readSafePath(record.path, `${itemLabel}.path`, issues);
+        const encoding = record.encoding === "base64" ? "base64" : "utf8";
+        const kind = record.kind === "text" || record.kind === "binary"
+            ? record.kind
+            : encoding === "base64" ? "binary" : "text";
+        if (typeof record.content !== "string") {
+            issues.push(`${itemLabel}.content must be a string.`);
+        }
+        if (!filePath || typeof record.content !== "string") {
+            return [];
+        }
+        return [{
+                path: filePath,
+                kind,
+                encoding,
+                content: record.content,
+                executable: record.executable === true,
+            }];
+    });
+}
+function normalizeCaseResults(value, label, issues) {
+    if (!Array.isArray(value)) {
+        issues.push(`${label} must be an array.`);
+        return [];
+    }
+    return value.flatMap((entry, index) => {
+        const itemLabel = `${label}[${index}]`;
+        const record = readRecord(entry, itemLabel, issues);
+        const id = readNonEmptyString(record?.id, `${itemLabel}.id`, issues);
+        if (!record || !id) {
+            return [];
+        }
+        const status = record.status === undefined || record.status === "completed" || record.status === "error"
+            ? record.status
+            : null;
+        if (status === null) {
+            issues.push(`${itemLabel}.status must be completed or error.`);
+        }
+        const criteria = record.criteria === undefined
+            ? undefined
+            : normalizeCaseCriteria(record.criteria, `${itemLabel}.criteria`, issues);
+        return [{
+                id,
+                ...(typeof record.label === "string" ? { label: record.label } : {}),
+                ...(typeof record.split === "string" ? { split: record.split } : {}),
+                ...(status ? { status } : {}),
+                ...(record.durationMs !== undefined ? { durationMs: readFiniteNumber(record.durationMs, `${itemLabel}.durationMs`, issues) ?? 0 } : {}),
+                metrics: normalizeNumberRecord(record.metrics ?? {}, `${itemLabel}.metrics`, issues),
+                ...(isJson(record.source) && record.source && typeof record.source === "object" && !Array.isArray(record.source)
+                    ? { source: record.source }
+                    : {}),
+                ...(isJson(record.feedback) ? { feedback: record.feedback } : {}),
+                ...(criteria && criteria.length > 0 ? { criteria } : {}),
+            }];
+    });
+}
+function normalizeCaseCriteria(value, label, issues) {
+    if (!Array.isArray(value)) {
+        issues.push(`${label} must be an array.`);
+        return [];
+    }
+    return value.flatMap((entry, index) => {
+        const itemLabel = `${label}[${index}]`;
+        const record = readRecord(entry, itemLabel, issues);
+        const criterionId = readNonEmptyString(record?.criterion_id, `${itemLabel}.criterion_id`, issues);
+        const score = readFiniteNumber(record?.score, `${itemLabel}.score`, issues);
+        if (!record || !criterionId || score === null) {
+            return [];
+        }
+        const pass = record.pass === undefined
+            ? score >= 0.5
+            : typeof record.pass === "boolean"
+                ? record.pass
+                : null;
+        if (pass === null) {
+            issues.push(`${itemLabel}.pass must be a boolean.`);
+        }
+        const errors = record.errors === undefined
+            ? []
+            : Array.isArray(record.errors)
+                ? record.errors.filter((error) => typeof error === "string")
+                : null;
+        if (errors === null) {
+            issues.push(`${itemLabel}.errors must be an array when provided.`);
+        }
+        const rationale = typeof record.rationale === "string" && record.rationale.trim().length > 0
+            ? record.rationale.trim()
+            : undefined;
+        return [{
+                criterion_id: criterionId,
+                label: typeof record.label === "string" ? record.label : criterionId,
+                score,
+                pass: pass ?? false,
+                ...(errors && errors.length > 0 ? { errors } : {}),
+                ...(rationale ? { rationale } : {}),
+            }];
+    });
+}
+function normalizeNumberRecord(value, label, issues) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        issues.push(`${label} must be an object.`);
+        return {};
+    }
+    const output = {};
+    for (const [key, entry] of Object.entries(value)) {
+        const numericValue = readFiniteNumber(entry, `${label}.${key}`, issues);
+        if (numericValue !== null) {
+            output[key] = numericValue;
+        }
+    }
+    return output;
+}
+function normalizeStringArray(value, label, issues) {
+    if (!Array.isArray(value)) {
+        issues.push(`${label} must be an array.`);
+        return [];
+    }
+    return value.flatMap((entry, index) => {
+        const normalized = readNonEmptyString(entry, `${label}[${index}]`, issues);
+        return normalized ? [normalized] : [];
+    });
+}
+function normalizeMetadataStringArray(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.filter((entry) => typeof entry === "string").map((entry) => normalizeRelativePath(entry));
+}
+function readRecord(value, label, issues) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        issues.push(`${label} must be an object.`);
+        return null;
+    }
+    return value;
+}
+function readNonEmptyString(value, label, issues) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        issues.push(`${label} must be a non-empty string.`);
+        return null;
+    }
+    return value;
+}
+function readSafePath(value, label, issues) {
+    const filePath = readNonEmptyString(value, label, issues);
+    if (!filePath) {
+        return null;
+    }
+    const normalized = normalizeRelativePath(filePath);
+    if (!isSafeRelativePath(normalized)) {
+        issues.push(`${label} must be a safe relative path.`);
+        return null;
+    }
+    return normalized;
+}
+function readFiniteNumber(value, label, issues) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        issues.push(`${label} must be a finite number.`);
+        return null;
+    }
+    return value;
+}
+function isAllowedEditPath(filePath, edits) {
+    const normalizedPath = normalizeRelativePath(filePath);
+    return edits.some((entry) => {
+        const normalizedEditPath = normalizeRelativePath(entry).replace(/\/+$/u, "");
+        return normalizedPath === normalizedEditPath || normalizedPath.startsWith(`${normalizedEditPath}/`);
+    });
+}
+function isSafeRelativePath(filePath) {
+    const normalized = normalizeRelativePath(filePath);
+    return normalized.length > 0
+        && !normalized.startsWith("/")
+        && !normalized.split("/").includes("..");
+}
+function normalizeRelativePath(filePath) {
+    return filePath.replace(/\\/gu, "/").replace(/^\.\/+/u, "").replace(/\/+/gu, "/");
+}
+function isJson(value) {
+    if (value === null || typeof value === "boolean" || typeof value === "number" || typeof value === "string") {
+        return true;
+    }
+    if (Array.isArray(value)) {
+        return value.every(isJson);
+    }
+    if (value && typeof value === "object") {
+        return Object.values(value).every(isJson);
+    }
+    return false;
+}

package/dist/execution-phases.d.ts

@@ -0,0 +1,21 @@
+import type { SubjectCaseReview, HostedWorkbenchJob, HostedWorkbenchJobStatus, WorkbenchExecutionEventRole, WorkbenchExecutionSpec, WorkbenchExecutionTrace, WorkbenchTracePhase } from "@workbench-ai/workbench-contract";
+export declare function buildSubjectCasePhaseRefs(args: {
+    jobs: readonly HostedWorkbenchJob[];
+    subjectId: string;
+    caseId: string;
+    sampleIndex?: number;
+}): SubjectCaseReview["phases"];
+export declare function buildWorkbenchTracePhases(args: {
+    jobs: readonly HostedWorkbenchJob[];
+    traceIdPrefix: string;
+    traceForJob: (job: HostedWorkbenchJob, role: WorkbenchExecutionEventRole) => WorkbenchExecutionTrace;
+}): WorkbenchTracePhase[];
+export declare function readWorkbenchExecutionPurpose(job: HostedWorkbenchJob): WorkbenchExecutionSpec["purpose"] | null;
+export declare function readWorkbenchExecutionId(job: HostedWorkbenchJob): string | null;
+export declare function readWorkbenchExecutionMetadataString(job: HostedWorkbenchJob, key: string): string | null;
+export declare function readWorkbenchExecutionMetadataNumber(job: HostedWorkbenchJob, key: string): number | null;
+export declare function isWorkbenchPhaseActive(phase: SubjectCaseReview["phases"][number]): boolean;
+export declare function resolveWorkbenchJobGroupStatus(jobs: readonly {
+    status: HostedWorkbenchJobStatus;
+}[]): HostedWorkbenchJobStatus;
+//# sourceMappingURL=execution-phases.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"execution-phases.d.ts","sourceRoot":"","sources":["../src/execution-phases.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,iBAAiB,EACjB,kBAAkB,EAClB,wBAAwB,EAExB,2BAA2B,EAC3B,sBAAsB,EACtB,uBAAuB,EACvB,mBAAmB,EACpB,MAAM,kCAAkC,CAAC;AAI1C,wBAAgB,yBAAyB,CAAC,IAAI,EAAE;IAC9C,IAAI,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,GAAG,iBAAiB,CAAC,QAAQ,CAAC,CA0D9B;AAED,wBAAgB,yBAAyB,CAAC,IAAI,EAAE;IAC9C,IAAI,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACpC,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,CACX,GAAG,EAAE,kBAAkB,EACvB,IAAI,EAAE,2BAA2B,KAC9B,uBAAuB,CAAC;CAC9B,GAAG,mBAAmB,EAAE,CAkDxB;AAED,wBAAgB,6BAA6B,CAC3C,GAAG,EAAE,kBAAkB,GACtB,sBAAsB,CAAC,SAAS,CAAC,GAAG,IAAI,CAQ1C;AAED,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,kBAAkB,GAAG,MAAM,GAAG,IAAI,CAG/E;AAED,wBAAgB,oCAAoC,CAClD,GAAG,EAAE,kBAAkB,EACvB,GAAG,EAAE,MAAM,GACV,MAAM,GAAG,IAAI,CAGf;AAED,wBAAgB,oCAAoC,CAClD,GAAG,EAAE,kBAAkB,EACvB,GAAG,EAAE,MAAM,GACV,MAAM,GAAG,IAAI,CAGf;AAED,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,iBAAiB,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,GACzC,OAAO,CAET;AAED,wBAAgB,8BAA8B,CAC5C,IAAI,EAAE,SAAS;IAAE,MAAM,EAAE,wBAAwB,CAAA;CAAE,EAAE,GACpD,wBAAwB,CAc1B"}

package/dist/execution-phases.js

@@ -0,0 +1,262 @@
+import { mergeWorkbenchExecutionTracesByJob } from "./execution-traces.js";
+export function buildSubjectCasePhaseRefs(args) {
+    const groups = new Map();
+    for (const job of args.jobs) {
+        const phase = readWorkbenchExecutionPurpose(job);
+        const jobSubjectId = job.subjectId ?? readWorkbenchExecutionMetadataString(job, "subjectId");
+        const jobCaseId = readWorkbenchExecutionMetadataString(job, "caseId");
+        if (jobSubjectId === args.subjectId &&
+            phase === "attempt" &&
+            caseReviewCaseIdsMatch(jobCaseId, args.caseId) &&
+            caseReviewSampleIndicesMatch(readWorkbenchExecutionMetadataNumber(job, "sampleIndex"), args.sampleIndex)) {
+            const key = [
+                job.runId,
+                phase,
+                jobCaseId ?? "",
+                readWorkbenchExecutionMetadataNumber(job, "sampleIndex") ?? "",
+            ].join("\0");
+            groups.set(key, [...(groups.get(key) ?? []), job]);
+        }
+    }
+    const phases = [...groups.values()]
+        .map((group) => group.slice().sort(compareWorkbenchPhaseJobs))
+        .flatMap((group) => {
+        const first = group[0];
+        if (!first) {
+            return [];
+        }
+        const phase = readWorkbenchExecutionPurpose(first);
+        if (phase !== "attempt") {
+            return [];
+        }
+        const startedAt = minTimestamp(group.map((job) => job.startedAt));
+        const finishedAt = maxTimestamp(group.map((job) => job.finishedAt));
+        const durationMs = startedAt && finishedAt
+            ? Math.max(0, Date.parse(finishedAt) - Date.parse(startedAt))
+            : null;
+        return [{
+                runId: first.runId,
+                phase,
+                role: "engine",
+                status: resolveWorkbenchJobGroupStatus(group),
+                jobIds: group.map((job) => job.id),
+                createdAt: minTimestamp(group.map((job) => job.createdAt)) ?? first.createdAt,
+                ...(startedAt ? { startedAt } : {}),
+                ...(finishedAt ? { finishedAt } : {}),
+                ...(durationMs !== null ? { durationMs } : {}),
+                ...optionalNumber("sampleIndex", readWorkbenchExecutionMetadataNumber(first, "sampleIndex")),
+            }];
+    })
+        .sort(compareSubjectCasePhases);
+    return selectCurrentPhaseRun(phases);
+}
+export function buildWorkbenchTracePhases(args) {
+    const groups = new Map();
+    for (const job of args.jobs) {
+        const purpose = readWorkbenchExecutionPurpose(job);
+        if (!purpose) {
+            continue;
+        }
+        const key = [
+            job.runId,
+            purpose,
+            job.subjectId ?? readWorkbenchExecutionMetadataString(job, "subjectId") ?? "",
+            readWorkbenchExecutionMetadataString(job, "caseId") ?? "",
+            readWorkbenchExecutionMetadataNumber(job, "sampleIndex") ?? "",
+            readWorkbenchExecutionMetadataNumber(job, "attemptIndex") ?? "",
+        ].join("\0");
+        groups.set(key, [...(groups.get(key) ?? []), job]);
+    }
+    return [...groups.values()]
+        .map((group) => group.slice().sort(compareWorkbenchTraceJobs))
+        .flatMap((group) => {
+        const first = group[0];
+        if (!first) {
+            return [];
+        }
+        const purpose = readWorkbenchExecutionPurpose(first);
+        if (!purpose) {
+            return [];
+        }
+        const role = traceRoleForPurpose(purpose);
+        return [{
+                phase: purpose,
+                executionId: group.length === 1 ? readWorkbenchExecutionId(first) : null,
+                role,
+                status: resolveWorkbenchJobGroupStatus(group),
+                jobIds: group.map((job) => job.id),
+                ...(first.subjectId ? { subjectId: first.subjectId } : {}),
+                ...optionalString("caseId", readWorkbenchExecutionMetadataString(first, "caseId")),
+                ...optionalNumber("sampleIndex", readWorkbenchExecutionMetadataNumber(first, "sampleIndex")),
+                ...optionalNumber("attemptIndex", readWorkbenchExecutionMetadataNumber(first, "attemptIndex")),
+                trace: mergeWorkbenchExecutionTracesByJob({
+                    traceIdPrefix: args.traceIdPrefix,
+                    stageId: purpose,
+                    jobs: group.map((job) => ({
+                        id: job.id,
+                        trace: args.traceForJob(job, role),
+                    })),
+                }),
+            }];
+    })
+        .sort(compareWorkbenchTracePhases);
+}
+export function readWorkbenchExecutionPurpose(job) {
+    if (job.kind !== "execute") {
+        return null;
+    }
+    const purpose = readExecutionRecord(job)?.purpose;
+    return purpose === "improve" || purpose === "attempt"
+        ? purpose
+        : null;
+}
+export function readWorkbenchExecutionId(job) {
+    const id = readExecutionRecord(job)?.id;
+    return typeof id === "string" && id.length > 0 ? id : null;
+}
+export function readWorkbenchExecutionMetadataString(job, key) {
+    const raw = readWorkbenchExecutionMetadataValue(job, key);
+    return typeof raw === "string" && raw.length > 0 ? raw : null;
+}
+export function readWorkbenchExecutionMetadataNumber(job, key) {
+    const raw = readWorkbenchExecutionMetadataValue(job, key);
+    return typeof raw === "number" && Number.isFinite(raw) ? raw : null;
+}
+export function isWorkbenchPhaseActive(phase) {
+    return phase.status === "queued" || phase.status === "running";
+}
+export function resolveWorkbenchJobGroupStatus(jobs) {
+    if (jobs.some((job) => job.status === "running")) {
+        return "running";
+    }
+    if (jobs.some((job) => job.status === "queued")) {
+        return "queued";
+    }
+    if (jobs.some((job) => job.status === "failed")) {
+        return "failed";
+    }
+    if (jobs.some((job) => job.status === "cancelled")) {
+        return "cancelled";
+    }
+    return "succeeded";
+}
+function readWorkbenchExecutionMetadataValue(job, key) {
+    const input = asRecord(job.input);
+    const execution = asRecord(input?.execution);
+    const metadata = asRecord(execution?.metadata);
+    return metadata?.[key] ?? input?.[key] ?? null;
+}
+function readExecutionRecord(job) {
+    const input = asRecord(job.input);
+    return asRecord(input?.execution);
+}
+function caseReviewCaseIdsMatch(jobCaseId, reviewCaseId) {
+    return Boolean(jobCaseId) &&
+        (jobCaseId === reviewCaseId || reviewCaseId.startsWith(`${jobCaseId}__`));
+}
+function caseReviewSampleIndicesMatch(jobSampleIndex, reviewSampleIndex) {
+    return typeof reviewSampleIndex !== "number" || jobSampleIndex === reviewSampleIndex;
+}
+function selectCurrentPhaseRun(phases) {
+    if (phases.length <= 1) {
+        return phases;
+    }
+    const activeRunId = phases
+        .filter(isWorkbenchPhaseActive)
+        .sort(comparePhaseRecency)[0]?.runId;
+    const selectedRunId = activeRunId ?? phases.slice().sort(comparePhaseRecency)[0]?.runId;
+    return selectedRunId
+        ? phases.filter((phase) => phase.runId === selectedRunId)
+        : phases;
+}
+function compareSubjectCasePhases(left, right) {
+    return (phasePurposeOrder(left.phase) - phasePurposeOrder(right.phase) ||
+        (left.sampleIndex ?? -1) - (right.sampleIndex ?? -1) ||
+        readPhaseRecencyMs(right) - readPhaseRecencyMs(left));
+}
+function comparePhaseRecency(left, right) {
+    return readPhaseRecencyMs(right) - readPhaseRecencyMs(left);
+}
+function compareWorkbenchPhaseJobs(left, right) {
+    return (phasePurposeOrder(readWorkbenchExecutionPurpose(left)) -
+        phasePurposeOrder(readWorkbenchExecutionPurpose(right)) ||
+        (readWorkbenchExecutionMetadataNumber(left, "sampleIndex") ?? -1) -
+            (readWorkbenchExecutionMetadataNumber(right, "sampleIndex") ?? -1) ||
+        readJobRecencyMs(right) - readJobRecencyMs(left) ||
+        left.id.localeCompare(right.id));
+}
+function compareWorkbenchTraceJobs(left, right) {
+    return (phasePurposeOrder(readWorkbenchExecutionPurpose(left)) -
+        phasePurposeOrder(readWorkbenchExecutionPurpose(right)) ||
+        String(readWorkbenchExecutionMetadataString(left, "caseId") ?? "").localeCompare(String(readWorkbenchExecutionMetadataString(right, "caseId") ?? "")) ||
+        (readWorkbenchExecutionMetadataNumber(left, "sampleIndex") ?? -1) -
+            (readWorkbenchExecutionMetadataNumber(right, "sampleIndex") ?? -1) ||
+        (readWorkbenchExecutionMetadataNumber(left, "attemptIndex") ?? -1) -
+            (readWorkbenchExecutionMetadataNumber(right, "attemptIndex") ?? -1) ||
+        left.id.localeCompare(right.id));
+}
+function compareWorkbenchTracePhases(left, right) {
+    return (phasePurposeOrder(left.phase) - phasePurposeOrder(right.phase) ||
+        String(left.caseId ?? "").localeCompare(String(right.caseId ?? "")) ||
+        (left.sampleIndex ?? -1) - (right.sampleIndex ?? -1) ||
+        (left.attemptIndex ?? -1) - (right.attemptIndex ?? -1) ||
+        String(left.jobIds[0] ?? "").localeCompare(String(right.jobIds[0] ?? "")));
+}
+function traceRoleForPurpose(purpose) {
+    if (purpose === "improve") {
+        return "optimizer";
+    }
+    return "engine";
+}
+function phasePurposeOrder(purpose) {
+    if (purpose === "improve") {
+        return 0;
+    }
+    if (purpose === "attempt") {
+        return 1;
+    }
+    return 3;
+}
+function readPhaseRecencyMs(phase) {
+    return (parseTimestampMs(phase.finishedAt) ??
+        parseTimestampMs(phase.startedAt) ??
+        parseTimestampMs(phase.createdAt) ??
+        0);
+}
+function readJobRecencyMs(job) {
+    return (parseTimestampMs(job.finishedAt) ??
+        parseTimestampMs(job.startedAt) ??
+        parseTimestampMs(job.updatedAt) ??
+        parseTimestampMs(job.createdAt) ??
+        0);
+}
+function minTimestamp(values) {
+    const sorted = values
+        .filter((value) => typeof value === "string" && value.length > 0)
+        .sort();
+    return sorted[0] ?? null;
+}
+function maxTimestamp(values) {
+    const sorted = values
+        .filter((value) => typeof value === "string" && value.length > 0)
+        .sort();
+    return sorted[sorted.length - 1] ?? null;
+}
+function parseTimestampMs(value) {
+    if (!value) {
+        return null;
+    }
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed) ? parsed : null;
+}
+function optionalString(key, value) {
+    return value ? { [key]: value } : {};
+}
+function optionalNumber(key, value) {
+    return value == null ? {} : { [key]: value };
+}
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}