@workbench-ai/workbench-core 0.0.46

package/dist/sandbox-backends/index.js

@@ -0,0 +1,79 @@
+import { createDockerSandboxBackendDescriptor, createDockerSandboxPlane, } from "./docker.js";
+import { DOCKER_SANDBOX_BACKEND, resolveWorkbenchSandboxProviderName, } from "./names.js";
+export { DOCKER_SANDBOX_BACKEND, resolveWorkbenchSandboxProviderName, } from "./names.js";
+export { createDockerSandboxBackendDescriptor, createDockerSandboxPlane, } from "./docker.js";
+export function createSandboxBackendPlaneForProvider(provider, args, startedAt, fileStore) {
+    const resolved = resolveWorkbenchSandboxProviderName(provider);
+    if (resolved !== DOCKER_SANDBOX_BACKEND) {
+        throw new Error(`Unsupported local sandbox provider ${provider}.`);
+    }
+    return createDockerSandboxPlane(args, startedAt, fileStore);
+}
+export function sandboxHostHealthExpectationForProvider(provider) {
+    if (provider !== DOCKER_SANDBOX_BACKEND) {
+        resolveWorkbenchSandboxProviderName(provider);
+    }
+    return {
+        provider,
+        backend: provider,
+        capabilities: createDockerSandboxBackendDescriptor().capabilities,
+    };
+}
+export function assertSandboxHostHealthForProvider(value, provider) {
+    const expected = sandboxHostHealthExpectationForProvider(provider);
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("sandbox host health response must be an object.");
+    }
+    const record = value;
+    if (record.provider !== expected.provider) {
+        throw new Error(`sandbox host provider ${String(record.provider ?? "missing")} does not match expected ${expected.provider}.`);
+    }
+    if (record.backend !== expected.backend) {
+        throw new Error(`sandbox host backend ${String(record.backend ?? "missing")} does not match expected ${expected.backend}.`);
+    }
+    if (!isSandboxBackendCapabilities(record.capabilities)) {
+        throw new Error(`sandbox host capabilities are invalid for backend ${expected.backend}.`);
+    }
+}
+export function sandboxProviderDefaultMaxConcurrentJobs(_provider) {
+    return null;
+}
+export function sandboxProviderAdmissionForResources(provider, resources) {
+    if (provider !== DOCKER_SANDBOX_BACKEND) {
+        resolveWorkbenchSandboxProviderName(provider);
+    }
+    assertPositiveResource(resources.cpu, "resources.cpu");
+    assertPositiveResource(resources.memoryGb, "resources.memoryGb");
+    if (resources.diskGb !== undefined) {
+        assertPositiveResource(resources.diskGb, "resources.diskGb");
+    }
+    return {
+        provider,
+        hostCost: {
+            cpu: resources.cpu,
+            memoryGb: resources.memoryGb,
+            diskGb: resources.diskGb ?? 1,
+        },
+        providerLeases: [],
+    };
+}
+export function sandboxProviderLeaseScope(provider) {
+    throw new Error(`Local sandbox provider ${provider} does not use provider leases.`);
+}
+function isSandboxBackendCapabilities(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return false;
+    }
+    const record = value;
+    return typeof record.snapshots === "boolean" &&
+        typeof record.interactiveExec === "boolean" &&
+        typeof record.filesystemDiff === "boolean" &&
+        typeof record.fileCapabilities === "boolean" &&
+        Array.isArray(record.networkPolicy) &&
+        record.networkPolicy.every((policy) => policy === "none" || policy === "open" || policy === "allowlist");
+}
+function assertPositiveResource(value, label) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+        throw new Error(`${label} must be a positive number.`);
+    }
+}

package/dist/sandbox-backends/names.d.ts

@@ -0,0 +1,6 @@
+export declare const DOCKER_SANDBOX_BACKEND = "docker";
+export type WorkbenchSandboxBackendName = typeof DOCKER_SANDBOX_BACKEND;
+export type WorkbenchSandboxProviderName = WorkbenchSandboxBackendName;
+export declare function isWorkbenchSandboxProviderName(value: string): value is WorkbenchSandboxProviderName;
+export declare function resolveWorkbenchSandboxProviderName(value: string | null | undefined): WorkbenchSandboxProviderName;
+//# sourceMappingURL=names.d.ts.map

package/dist/sandbox-backends/names.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"names.d.ts","sourceRoot":"","sources":["../../src/sandbox-backends/names.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,sBAAsB,WAAW,CAAC;AAE/C,MAAM,MAAM,2BAA2B,GAAG,OAAO,sBAAsB,CAAC;AAExE,MAAM,MAAM,4BAA4B,GAAG,2BAA2B,CAAC;AAEvE,wBAAgB,8BAA8B,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,4BAA4B,CAEnG;AAED,wBAAgB,mCAAmC,CACjD,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC/B,4BAA4B,CAS9B"}

package/dist/sandbox-backends/names.js

@@ -0,0 +1,14 @@
+export const DOCKER_SANDBOX_BACKEND = "docker";
+export function isWorkbenchSandboxProviderName(value) {
+    return value === DOCKER_SANDBOX_BACKEND;
+}
+export function resolveWorkbenchSandboxProviderName(value) {
+    const normalized = value?.trim();
+    if (!normalized) {
+        throw new Error("Sandbox provider is required.");
+    }
+    if (isWorkbenchSandboxProviderName(normalized)) {
+        return normalized;
+    }
+    throw new Error(`Unsupported local sandbox provider ${normalized}. Supported providers: docker.`);
+}

package/dist/sandbox-backends/template-images.d.ts

@@ -0,0 +1,4 @@
+import type { WorkbenchExecutionSpec } from "@workbench-ai/workbench-contract";
+import type { WorkbenchExecutionRuntimeInput } from "../execution-runtime-types.ts";
+export declare function resolveSandboxTemplateImage(execution: WorkbenchExecutionSpec, args: WorkbenchExecutionRuntimeInput): string;
+//# sourceMappingURL=template-images.d.ts.map

package/dist/sandbox-backends/template-images.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-images.d.ts","sourceRoot":"","sources":["../../src/sandbox-backends/template-images.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,sBAAsB,EACvB,MAAM,kCAAkC,CAAC;AAE1C,OAAO,KAAK,EACV,8BAA8B,EAC/B,MAAM,+BAA+B,CAAC;AAMvC,wBAAgB,2BAA2B,CACzC,SAAS,EAAE,sBAAsB,EACjC,IAAI,EAAE,8BAA8B,GACnC,MAAM,CAiBR"}

package/dist/sandbox-backends/template-images.js

@@ -0,0 +1,48 @@
+import { normalizeRuntimeRegistry, resolveDockerRuntimeImageRef, } from "../runtime-utils.js";
+export function resolveSandboxTemplateImage(execution, args) {
+    if (execution.sandbox.kind === "oci") {
+        return resolveDockerRuntimeImageRef(execution.sandbox.ref, {
+            runtimeRegistry: normalizeRuntimeRegistry(args.runtimeRegistry ?? process.env.WORKBENCH_RUNTIME_REGISTRY ?? ""),
+            label: `Execution ${execution.id} sandbox ref`,
+        });
+    }
+    const image = sandboxTemplateImageForRef(execution.sandbox.ref);
+    if (!image) {
+        throw new Error(`Execution ${execution.id} uses snapshot template ${execution.sandbox.ref}, but WORKBENCH_SANDBOX_TEMPLATE_IMAGES does not map that ref.`);
+    }
+    return image.startsWith("docker://")
+        ? resolveDockerRuntimeImageRef(image, {
+            runtimeRegistry: normalizeRuntimeRegistry(args.runtimeRegistry ?? process.env.WORKBENCH_RUNTIME_REGISTRY ?? ""),
+            label: `WORKBENCH_SANDBOX_TEMPLATE_IMAGES[${execution.sandbox.ref}]`,
+        })
+        : image;
+}
+function sandboxTemplateImageForRef(templateRef) {
+    const raw = process.env.WORKBENCH_SANDBOX_TEMPLATE_IMAGES?.trim() ?? "";
+    if (!raw) {
+        return null;
+    }
+    if (raw.startsWith("{")) {
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            throw new Error("WORKBENCH_SANDBOX_TEMPLATE_IMAGES must be a JSON object or comma-separated ref=image list.");
+        }
+        const value = parsed[templateRef];
+        return typeof value === "string" && value.trim() ? value.trim() : null;
+    }
+    const entries = raw.split(",")
+        .map((entry) => entry.trim())
+        .filter(Boolean);
+    for (const entry of entries) {
+        const separator = entry.indexOf("=");
+        if (separator <= 0) {
+            throw new Error("WORKBENCH_SANDBOX_TEMPLATE_IMAGES entries must use ref=image.");
+        }
+        const ref = entry.slice(0, separator).trim();
+        const image = entry.slice(separator + 1).trim();
+        if (ref === templateRef) {
+            return image || null;
+        }
+    }
+    return null;
+}

package/dist/sandbox-inputs.d.ts

@@ -0,0 +1,27 @@
+import type { BlobObjectRef, HostedWorkbenchJob, Json, SurfaceSnapshotFile, WorkbenchExecutionCapability, WorkbenchExecutionResult, WorkbenchExecutionSpec, WorkbenchSandboxExecutionMetadata } from "@workbench-ai/workbench-contract";
+import { type SandboxCreateRequest, type SandboxExecutionFileStore, type SandboxMaterializedInput } from "./sandbox-plane.ts";
+import type { WorkbenchExecutionRuntimeInput } from "./execution-runtime-types.ts";
+export declare function readWorkbenchExecutionSpec(job: HostedWorkbenchJob): WorkbenchExecutionSpec;
+export declare function createWorkbenchSandboxFileStore(args: WorkbenchExecutionRuntimeInput): SandboxExecutionFileStore;
+export declare function materializeWorkbenchSandboxInput(args: WorkbenchExecutionRuntimeInput, execution: WorkbenchExecutionSpec, input: WorkbenchExecutionSpec["inputs"][number]): SandboxMaterializedInput;
+export declare function materializedFileInput(input: WorkbenchExecutionSpec["inputs"][number], files: readonly SurfaceSnapshotFile[]): SandboxMaterializedInput;
+export declare function createSandboxAdapterRequest(args: WorkbenchExecutionRuntimeInput, request: SandboxCreateRequest, startedAt: string): Json;
+export declare function sanitizeWorkbenchExecutionJobForSandbox(job: HostedWorkbenchJob, execution: WorkbenchExecutionSpec): HostedWorkbenchJob;
+export declare function materializedInputForSandboxRequest(input: SandboxMaterializedInput): Record<string, Json>;
+export declare function executionResultFromCompletedSandboxJob(args: {
+    completedJob: HostedWorkbenchJob;
+    execution: WorkbenchExecutionSpec;
+    startedAt: string;
+    backend: string;
+    allocation: WorkbenchSandboxExecutionMetadata["allocation"];
+    capability: WorkbenchSandboxExecutionMetadata["capability"];
+    handle: WorkbenchSandboxExecutionMetadata["handle"];
+    fileStore: SandboxExecutionFileStore;
+}): Promise<WorkbenchExecutionResult>;
+export declare function outputPayloadForContract(output: Record<string, unknown>, outputName: string): Json | undefined;
+export declare function sandboxOutputRef(capability: WorkbenchExecutionCapability, outputName: string, body: string): Promise<BlobObjectRef>;
+export declare function sha256Hex(body: string): Promise<string>;
+export declare function withSandboxCompletionMetadata(job: HostedWorkbenchJob, metadata: WorkbenchSandboxExecutionMetadata): HostedWorkbenchJob;
+export declare function attachSandboxMetadataToJob(job: HostedWorkbenchJob, metadata: unknown): HostedWorkbenchJob;
+export declare function isSurfaceSnapshotFile(value: unknown): value is SurfaceSnapshotFile;
+//# sourceMappingURL=sandbox-inputs.d.ts.map

package/dist/sandbox-inputs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-inputs.d.ts","sourceRoot":"","sources":["../src/sandbox-inputs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,aAAa,EACb,kBAAkB,EAClB,IAAI,EACJ,mBAAmB,EACnB,4BAA4B,EAC5B,wBAAwB,EACxB,sBAAsB,EACtB,iCAAiC,EAClC,MAAM,kCAAkC,CAAC;AAE1C,OAAO,EAEL,KAAK,oBAAoB,EACzB,KAAK,yBAAyB,EAC9B,KAAK,wBAAwB,EAC9B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EACV,8BAA8B,EAC/B,MAAM,8BAA8B,CAAC;AActC,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,kBAAkB,GAAG,sBAAsB,CAO1F;AAED,wBAAgB,+BAA+B,CAAC,IAAI,EAAE,8BAA8B,GAAG,yBAAyB,CAoB/G;AAED,wBAAgB,gCAAgC,CAC9C,IAAI,EAAE,8BAA8B,EACpC,SAAS,EAAE,sBAAsB,EACjC,KAAK,EAAE,sBAAsB,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,GAC9C,wBAAwB,CAW1B;AAqBD,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,sBAAsB,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,EAC/C,KAAK,EAAE,SAAS,mBAAmB,EAAE,GACpC,wBAAwB,CAO1B;AAED,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,8BAA8B,EACpC,OAAO,EAAE,oBAAoB,EAC7B,SAAS,EAAE,MAAM,GAChB,IAAI,CAkBN;AAED,wBAAgB,uCAAuC,CACrD,GAAG,EAAE,kBAAkB,EACvB,SAAS,EAAE,sBAAsB,GAChC,kBAAkB,CAgBpB;AAED,wBAAgB,kCAAkC,CAAC,KAAK,EAAE,wBAAwB,GAAG,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAgBxG;AAED,wBAAsB,sCAAsC,CAAC,IAAI,EAAE;IACjE,YAAY,EAAE,kBAAkB,CAAC;IACjC,SAAS,EAAE,sBAAsB,CAAC;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,iCAAiC,CAAC,YAAY,CAAC,CAAC;IAC5D,UAAU,EAAE,iCAAiC,CAAC,YAAY,CAAC,CAAC;IAC5D,MAAM,EAAE,iCAAiC,CAAC,QAAQ,CAAC,CAAC;IACpD,SAAS,EAAE,yBAAyB,CAAC;CACtC,GAAG,OAAO,CAAC,wBAAwB,CAAC,CA6CpC;AAED,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAQ9G;AAED,wBAAsB,gBAAgB,CACpC,UAAU,EAAE,4BAA4B,EACxC,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,aAAa,CAAC,CAYxB;AAED,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAG7D;AAED,wBAAgB,6BAA6B,CAC3C,GAAG,EAAE,kBAAkB,EACvB,QAAQ,EAAE,iCAAiC,GAC1C,kBAAkB,CAEpB;AAED,wBAAgB,0BAA0B,CACxC,GAAG,EAAE,kBAAkB,EACvB,QAAQ,EAAE,OAAO,GAChB,kBAAkB,CAepB;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,mBAAmB,CAWlF"}

package/dist/sandbox-inputs.js

@@ -0,0 +1,220 @@
+import { createWorkbenchSandboxExecutionMetadata, } from "./sandbox-plane.js";
+import { asRuntimeRecord, importNodeModule, isJsonPayload, nodeBuiltin, } from "./runtime-utils.js";
+import { engineCaseForCase, } from "./execution-jobs.js";
+import { engineCaseFilesForRuntimeInput, } from "./generic-spec.js";
+export function readWorkbenchExecutionSpec(job) {
+    const input = asRuntimeRecord(job.input);
+    const execution = input.execution;
+    if (!execution || typeof execution !== "object" || Array.isArray(execution)) {
+        throw new Error(`Execution job ${job.id} is missing input.execution.`);
+    }
+    return execution;
+}
+export function createWorkbenchSandboxFileStore(args) {
+    const outputPayloads = new Map();
+    return {
+        async materializeInputs(execution) {
+            return execution.inputs.map((input) => materializeWorkbenchSandboxInput(args, execution, input));
+        },
+        async publishJson(capability, outputName, payload) {
+            const body = JSON.stringify(payload);
+            const ref = await sandboxOutputRef(capability, outputName, body);
+            outputPayloads.set(ref.key, payload);
+            return ref;
+        },
+        async readJson(ref) {
+            const payload = outputPayloads.get(ref.key);
+            if (payload === undefined) {
+                throw new Error(`Sandbox output payload is missing: ${ref.key}.`);
+            }
+            return payload;
+        },
+    };
+}
+export function materializeWorkbenchSandboxInput(args, execution, input) {
+    if (input.name === "subject") {
+        return materializedFileInput(input, args.baseFiles);
+    }
+    if (input.name === "case") {
+        return materializedFileInput(input, selectSandboxCaseFiles(args, execution));
+    }
+    if (input.name === "traces") {
+        return materializedFileInput(input, args.traceFiles ?? []);
+    }
+    throw new Error(`Execution ${readWorkbenchExecutionSpec(args.job).id} declares unsupported sandbox input: ${input.name}.`);
+}
+function selectSandboxCaseFiles(args, execution) {
+    if (execution.purpose !== "attempt") {
+        return [];
+    }
+    const metadata = asRuntimeRecord(execution.metadata);
+    const jobInput = asRuntimeRecord(args.job.input);
+    const caseId = typeof metadata.caseId === "string"
+        ? metadata.caseId
+        : typeof jobInput.caseId === "string"
+            ? jobInput.caseId
+            : "current";
+    const engineCase = engineCaseForCase(args.engineCases, caseId);
+    return engineCaseFilesForRuntimeInput({ spec: args.spec, engineCase });
+}
+export function materializedFileInput(input, files) {
+    return {
+        input,
+        mountPath: input.mountPath,
+        kind: "files",
+        files: files.map((file) => ({ ...file })),
+    };
+}
+export function createSandboxAdapterRequest(args, request, startedAt) {
+    return {
+        jobInput: {
+            job: sanitizeWorkbenchExecutionJobForSandbox(args.job, request.execution),
+            spec: args.spec,
+            environmentVersion: (args.environmentVersion ?? null),
+            engineCases: args.engineCases,
+            ...(args.adapterAuthProfiles ? { adapterAuthProfiles: args.adapterAuthProfiles } : {}),
+            ...(args.adapterManifests ? { adapterManifests: args.adapterManifests } : {}),
+            ...(args.progress ? { progress: args.progress } : {}),
+        },
+        execution: request.execution,
+        capability: request.capability,
+        inputBundle: {
+            inputs: request.inputs.map((input) => materializedInputForSandboxRequest(input)),
+        },
+        startedAt,
+    };
+}
+export function sanitizeWorkbenchExecutionJobForSandbox(job, execution) {
+    const input = asRuntimeRecord(job.input);
+    const sanitizedInput = {};
+    for (const [key, value] of Object.entries(input)) {
+        if (key === "baseFiles" || key === "traceFiles") {
+            continue;
+        }
+        if (isJsonPayload(value)) {
+            sanitizedInput[key] = value;
+        }
+    }
+    sanitizedInput.execution = execution;
+    return {
+        ...job,
+        input: sanitizedInput,
+    };
+}
+export function materializedInputForSandboxRequest(input) {
+    const base = {
+        input: input.input,
+        mountPath: input.mountPath,
+        kind: input.kind,
+    };
+    if (input.kind === "files") {
+        return {
+            ...base,
+            files: (input.files ?? []).map((file) => ({ ...file })),
+        };
+    }
+    return {
+        ...base,
+        json: (input.json ?? null),
+    };
+}
+export async function executionResultFromCompletedSandboxJob(args) {
+    const completedJob = withSandboxCompletionMetadata(args.completedJob, {
+        backend: args.backend,
+        allocation: args.allocation,
+        capability: args.capability,
+        handle: args.handle,
+    });
+    if (completedJob.status !== "succeeded") {
+        return {
+            executionId: args.execution.id,
+            status: completedJob.status === "cancelled" ? "cancelled" : "failed",
+            startedAt: completedJob.startedAt ?? args.startedAt,
+            finishedAt: completedJob.finishedAt ?? new Date().toISOString(),
+            outputs: {},
+            ...(completedJob.error ? { error: completedJob.error } : {}),
+            metadata: {
+                backend: args.backend,
+                allocation: args.allocation,
+                completedJob: completedJob,
+            },
+        };
+    }
+    const output = asRuntimeRecord(completedJob.output);
+    const outputs = {};
+    for (const contract of args.execution.outputs) {
+        const payload = outputPayloadForContract(output, contract.name);
+        if (payload === undefined) {
+            continue;
+        }
+        const ref = await args.fileStore.publishJson(args.capability, contract.name, payload);
+        outputs[contract.name] = ref;
+    }
+    return {
+        executionId: args.execution.id,
+        status: "succeeded",
+        startedAt: completedJob.startedAt ?? args.startedAt,
+        finishedAt: completedJob.finishedAt ?? new Date().toISOString(),
+        outputs,
+        metadata: {
+            backend: args.backend,
+            allocation: args.allocation,
+            completedJob: completedJob,
+        },
+    };
+}
+export function outputPayloadForContract(output, outputName) {
+    if (outputName === "subject_patch") {
+        return isJsonPayload(output.subjectPatch) ? output.subjectPatch : undefined;
+    }
+    if (outputName === "result") {
+        return isJsonPayload(output.result) ? output.result : undefined;
+    }
+    return isJsonPayload(output[outputName]) ? output[outputName] : undefined;
+}
+export async function sandboxOutputRef(capability, outputName, body) {
+    const prefix = capability.outputPrefix.endsWith("/") ? capability.outputPrefix : `${capability.outputPrefix}/`;
+    const key = `${prefix}${outputName}.json`;
+    if (!key.startsWith(prefix)) {
+        throw new Error(`Sandbox output ${outputName} escaped capability output prefix.`);
+    }
+    return {
+        bucket: "memory",
+        key,
+        byteLength: Buffer.byteLength(body, "utf8"),
+        sha256: await sha256Hex(body),
+    };
+}
+export async function sha256Hex(body) {
+    const crypto = await importNodeModule(nodeBuiltin("crypto"));
+    return crypto.createHash("sha256").update(body).digest("hex");
+}
+export function withSandboxCompletionMetadata(job, metadata) {
+    return attachSandboxMetadataToJob(job, createWorkbenchSandboxExecutionMetadata(metadata));
+}
+export function attachSandboxMetadataToJob(job, metadata) {
+    const output = asRuntimeRecord(job.output);
+    if (!job.output || Array.isArray(job.output) || typeof job.output !== "object") {
+        return job;
+    }
+    if (!metadata || typeof metadata !== "object" || Array.isArray(metadata)) {
+        return job;
+    }
+    return {
+        ...job,
+        output: {
+            ...output,
+            sandbox: metadata,
+        },
+    };
+}
+export function isSurfaceSnapshotFile(value) {
+    return Boolean(value &&
+        typeof value === "object" &&
+        !Array.isArray(value) &&
+        typeof value.path === "string" &&
+        (value.kind === "text" || value.kind === "binary") &&
+        (value.encoding === "utf8" || value.encoding === "base64") &&
+        typeof value.content === "string" &&
+        typeof value.executable === "boolean");
+}

package/dist/sandbox-plane.d.ts

@@ -0,0 +1,89 @@
+import type { BlobObjectRef, Json, SurfaceSnapshotFile, WorkbenchExecutionCapability, WorkbenchExecutionInputRef, WorkbenchExecutionNetworkPolicy, WorkbenchExecutionResult, WorkbenchExecutionSpec, WorkbenchSandboxAllocation, WorkbenchSandboxExecutionMetadata, WorkbenchSandboxHandle } from "@workbench-ai/workbench-contract";
+import { type WorkbenchExecutionOutputPayloads } from "./execution-outputs.ts";
+export interface SandboxMaterializedInput {
+    input: WorkbenchExecutionInputRef;
+    mountPath: string;
+    kind: "files" | "json";
+    files?: SurfaceSnapshotFile[];
+    json?: Json;
+}
+export interface SandboxExecutionFileStore {
+    materializeInputs(execution: WorkbenchExecutionSpec): Promise<SandboxMaterializedInput[]>;
+    publishJson(capability: WorkbenchExecutionCapability, outputName: string, payload: Json): Promise<BlobObjectRef>;
+    readJson(ref: BlobObjectRef): Promise<Json>;
+}
+export interface SandboxExecutionOptions {
+    fileStore: SandboxExecutionFileStore;
+    runnerId?: string;
+    now?: string;
+    signal?: AbortSignal;
+}
+export interface WorkbenchSandboxAllocationOptions {
+    backend: string;
+    runnerId?: string;
+    now?: string;
+    ttlMs?: number;
+    lifecycleId?: string;
+    sandboxId?: string;
+}
+export interface SandboxBackendCapabilities {
+    snapshots: boolean;
+    interactiveExec: boolean;
+    filesystemDiff: boolean;
+    networkPolicy: readonly WorkbenchExecutionNetworkPolicy["egress"][];
+    fileCapabilities: boolean;
+}
+export interface SandboxEnvironmentImage {
+    backend: string;
+    kind: WorkbenchSandboxAllocation["template"]["kind"];
+    ref: string;
+    metadata?: Record<string, Json>;
+}
+export type SandboxHandle = WorkbenchSandboxHandle;
+export interface SandboxBackendDescriptor {
+    name: string;
+    version?: string;
+    capabilities: SandboxBackendCapabilities;
+}
+export interface SandboxCreateRequest {
+    execution: WorkbenchExecutionSpec;
+    environment: SandboxEnvironmentImage;
+    allocation: WorkbenchSandboxAllocation;
+    capability: WorkbenchExecutionCapability;
+    inputs: SandboxMaterializedInput[];
+}
+export interface SandboxExecRequest {
+    execution: WorkbenchExecutionSpec;
+    environment: SandboxEnvironmentImage;
+    sandbox: SandboxHandle;
+    allocation: WorkbenchSandboxAllocation;
+    capability: WorkbenchExecutionCapability;
+    inputs: SandboxMaterializedInput[];
+}
+export interface SandboxPlane {
+    backend: SandboxBackendDescriptor;
+    prepareEnvironment?(execution: WorkbenchExecutionSpec, options: SandboxExecutionOptions): Promise<SandboxEnvironmentImage>;
+    createSandbox(request: SandboxCreateRequest, options: SandboxExecutionOptions): Promise<SandboxHandle>;
+    exec(request: SandboxExecRequest, options: SandboxExecutionOptions): Promise<WorkbenchExecutionResult>;
+    destroySandbox(sandbox: SandboxHandle, options: SandboxExecutionOptions): Promise<void>;
+}
+export interface ValidatedSandboxExecutionResult {
+    result: WorkbenchExecutionResult;
+    payloads: WorkbenchExecutionOutputPayloads;
+}
+export declare function executeValidatedSandboxExecution(plane: SandboxPlane, execution: WorkbenchExecutionSpec, options: SandboxExecutionOptions): Promise<ValidatedSandboxExecutionResult>;
+export declare function createWorkbenchSandboxExecutionMetadata(args: WorkbenchSandboxExecutionMetadata): WorkbenchSandboxExecutionMetadata;
+export declare function collectSandboxHandleScopeIssues(sandbox: SandboxHandle, allocation: WorkbenchSandboxAllocation, execution: WorkbenchExecutionSpec): string[];
+export declare function createWorkbenchSandboxAllocation(execution: WorkbenchExecutionSpec, options: WorkbenchSandboxAllocationOptions): WorkbenchSandboxAllocation;
+export declare function createWorkbenchExecutionCapability(execution: WorkbenchExecutionSpec, options?: {
+    now?: string;
+    ttlMs?: number;
+    outputPrefix?: string;
+}): WorkbenchExecutionCapability;
+export declare function collectExecutionCapabilityScopeIssues(capability: WorkbenchExecutionCapability, execution: WorkbenchExecutionSpec, options?: {
+    now?: string;
+}): string[];
+export declare function collectSandboxAllocationScopeIssues(allocation: WorkbenchSandboxAllocation, execution: WorkbenchExecutionSpec, options?: {
+    now?: string;
+}): string[];
+//# sourceMappingURL=sandbox-plane.d.ts.map

package/dist/sandbox-plane.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-plane.d.ts","sourceRoot":"","sources":["../src/sandbox-plane.ts"],"names":[],"mappings":"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"}