ODS V3 Pre-Release: Public testing and refinement ahead of the official V3 launch. Turn your PC, Mac, or Linux box into a private AI server.
Python ai-agentsamdcomfyuidockerllama-cppllmlocal-ain8nnvidiaopen-webuiragself-hostedspeech-to-textstrix-halotext-to-speechworkflow-automation
import { spawnSync } from "node:child_process";
import { createHash, randomBytes } from "node:crypto";
import { constants } from "node:fs";
import { lstat, mkdir, open, readFile, readdir, realpath, rename, unlink } from "node:fs/promises";
import { dirname, isAbsolute, join, resolve } from "node:path";
import { assertJsonSchema } from "../../scripts/lib/json-schema.mjs";
import { canonical, validateWorkCapabilityGrant, validateWorkWatchdogDecision } from "../../scripts/lib/work-contract.mjs";
import { loadCapabilityImageAdmission } from "./capability-image-admission.mjs";
import { loadPassingCapabilityHealth, statusCapabilityHealth } from "./capability-health.mjs";
import {
acquireCapabilityPackOperation, CapabilityPackOperationError,
loadCapabilityPackOperation, releaseCapabilityPackOperation,
} from "./capability-pack-operation.mjs";
import {
buildCapabilityAdapterCleanupDockerCommands, buildCapabilityAdapterDockerCommand,
buildCapabilityWorkspaceDockerCommands, capabilityPackSha256, claimCapabilityGrant,
loadCapabilityGrantClaim, validateCapabilityWorkspaceVolume,
} from "./capability-packs.mjs";
import { runCapabilityMcpToolWithTrustedLaunch } from "./mcp-stdio-client.mjs";
const DOCKER_PATH = "/usr/bin/docker";
const SHA_RE = /^[a-f0-9]{64}$/u;
const GRANT_RE = /^workcapgrant-[0-9]{13}-[a-f0-9]{12}$/u;
const NAME_RE = /^[a-z0-9][a-z0-9_.-]{1,127}$/u;
const RECEIPT_RE = /^(workcapgrant-[0-9]{13}-[a-f0-9]{12})-([a-f0-9]{64})\.json$/u;
const RECEIPT_STAGE_RE = /^\.receipt-[a-f0-9]{16}$/u;
const authority = Object.freeze({ grantsFutureExecution: false, grantsReplay: false, grantsImagePull: false, grantsNetwork: false, grantsHostAccess: false, grantsCredentials: false, grantsExternalEffects: false, grantsScopeExpansion: false, grantsControllerRegistration: false, grantsCompletion: false });
const boundary = "Content-free terminal evidence for one exact single-use capability grant. Structured output crossed only the live caller boundary and is not retained here; the receipt grants no replay, future execution, image pull, network, host access, credential, external effect, scope expansion, controller registration, or completion authority.";
const cleanupBoundary = "Cleanup-only custody for one exact single-use capability execution. It may inspect and remove only the named claim-bound container and disposable workspace and grants no tool replay, image pull, data access, network, host access, credential, external effect, scope expansion, controller registration, or completion authority.";
const runtimeSchema = JSON.parse(await readFile(new URL("../../schemas/work-capability-runtime-v1.schema.json", import.meta.url), "utf8"));
export class CapabilityRuntimeError extends Error {}
function fail(message) { throw new CapabilityRuntimeError(message); }
function sha(value) { return createHash("sha256").update(typeof value === "string" || Buffer.isBuffer(value) ? value : canonical(value)).digest("hex"); }
async function operationCall(promise) { try { return await promise; } catch (error) { if (error instanceof CapabilityPackOperationError) fail(error.message); throw error; } }
function observed(clock, label) {
if (typeof clock !== "function") fail(`${label} clock is invalid`);
const value = clock();
if (!(value instanceof Date) || !Number.isSafeInteger(value.getTime())) fail(`${label} time is invalid`);
return value;
}
async function privateDirectory(path, label, create = false) {
if (!isAbsolute(path) || resolve(path) === dirname(resolve(path))) fail(`${label} must be an absolute non-root directory`);
if (create) await mkdir(path, { mode: 0o700 }).catch((error) => { if (error?.code !== "EEXIST") throw error; });
const info = await lstat(path).catch(() => null);
if (!info?.isDirectory() || info.isSymbolicLink() || await realpath(path) !== resolve(path)) fail(`${label} must be a real unlinked directory`);
if (process.platform !== "win32" && (info.uid !== process.geteuid() || (info.mode & 0o077) !== 0)) fail(`${label} must be owner-private`);
return resolve(path);
}
async function privateRegular(path, maximumBytes, label) {
let handle;
try { handle = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0)); }
catch { fail(`${label} must be a descriptor-bound regular file`); }
try {
const info = await handle.stat(), current = await lstat(path);
if (!info.isFile() || info.nlink !== 1 || info.size < 1 || info.size > maximumBytes || current.isSymbolicLink() || current.dev !== info.dev || current.ino !== info.ino) fail(`${label} must be a bounded regular single-link file`);
if (process.platform !== "win32" && (info.uid !== process.geteuid() || (info.mode & 0o077) !== 0)) fail(`${label} must be owner-private`);
return await handle.readFile();
} finally { await handle.close(); }
}
async function syncDirectory(path) {
if (process.platform === "win32") return;
const handle = await open(path, constants.O_RDONLY);
try { await handle.sync(); } finally { await handle.close(); }
}
async function writeExclusive(path, payload) {
const handle = await open(path, "wx", 0o600);
try { await handle.writeFile(payload); await handle.sync(); } finally { await handle.close(); }
}
async function roots(admitted, create = false) {
const base = await privateDirectory(join(admitted.installed.root, "capability-pack-runtime"), "capability runtime root", create);
const identity = await privateDirectory(join(base, admitted.receipt.pack.id), "capability runtime identity root", create);
const version = await privateDirectory(join(identity, `${admitted.receipt.pack.version}-${admitted.receipt.pack.packSha256}`), "capability runtime version root", create);
const receipts = await privateDirectory(join(version, "receipts"), "capability runtime receipt root", create);
const cleanups = await privateDirectory(join(version, "cleanups"), "capability runtime cleanup root", create);
const cids = await privateDirectory(join(version, "cids"), "capability runtime CID root", create);
return { base, identity, version, receipts, cleanups, cids };
}
function checkedGrant(grant, admitted) {
if (validateWorkCapabilityGrant(grant).length || grant.pack.id !== admitted.receipt.pack.id || grant.pack.version !== admitted.receipt.pack.version || grant.pack.packSha256 !== admitted.receipt.pack.packSha256 || grant.pack.treeSha256 !== admitted.receipt.pack.treeSha256) fail("capability runtime grant differs from the admitted pack");
return grant;
}
function runtimeBinding({ pack, admissionReceiptSha256, healthReceiptSha256, grant, toolName, watchdogDecisionSha256, inputBytes, containerName, workspaceVolumeName, cidFile, dockerConfigPath }) {
return sha({ operation: "pixel-work-capability-runtime", pack, admissionReceiptSha256, healthReceiptSha256, grantSha256: sha(grant), toolName, watchdogDecisionSha256, inputBytes, containerName, workspaceVolumeName, cidFile, dockerConfigPath });
}
function checkedIntent(value, admitted, operation, name) {
const keys = ["admissionReceiptSha256", "boundary", "cidFile", "containerName", "dockerConfigPath", "grant", "healthReceiptSha256", "inputBytes", "operationBindingSha256", "operationToken", "pack", "schemaVersion", "toolName", "watchdogDecisionSha256", "workspaceVolumeName"];
if (!value || typeof value !== "object" || Array.isArray(value) || canonical(Object.keys(value).sort()) !== canonical(keys) || value.schemaVersion !== 1 || value.boundary !== cleanupBoundary || canonical(value.pack) !== canonical(admitted.receipt.pack) || value.admissionReceiptSha256 !== sha(admitted.receipt) || !SHA_RE.test(value.healthReceiptSha256 ?? "") || !GRANT_RE.test(value.grant?.grantId ?? "") || `${value.grant.grantId}.json` !== name || !NAME_RE.test(value.containerName ?? "") || !isAbsolute(value.cidFile ?? "") || value.cidFile !== join(admitted.installed.root, "capability-pack-runtime", admitted.receipt.pack.id, `${admitted.receipt.pack.version}-${admitted.receipt.pack.packSha256}`, "cids", `${value.grant.grantId}.cid`) || !isAbsolute(value.dockerConfigPath ?? "") || value.operationBindingSha256 !== operation.bindingSha256 || value.operationToken !== operation.token || !SHA_RE.test(value.watchdogDecisionSha256 ?? "") || !Number.isSafeInteger(value.inputBytes) || value.inputBytes < 0 || value.inputBytes > 1048576 || typeof value.toolName !== "string" || value.workspaceVolumeName !== null && !NAME_RE.test(value.workspaceVolumeName ?? "")) fail("capability runtime cleanup intent is invalid");
checkedGrant(value.grant, admitted);
if (!value.grant.tools.includes(value.toolName) || (admitted.installed.pack.adapter.workspace === "disposable-read-write") !== (value.workspaceVolumeName !== null)) fail("capability runtime cleanup intent widens its grant");
if (runtimeBinding(value) !== operation.bindingSha256) fail("capability runtime cleanup intent differs from operation custody");
return value;
}
function validateReceipt(receipt, admitted, name) {
try { assertJsonSchema(receipt, runtimeSchema, "capability runtime receipt"); } catch { fail("capability runtime receipt is invalid"); }
if (canonical(receipt.pack) !== canonical(admitted.receipt.pack) || receipt.admissionReceiptSha256 !== sha(admitted.receipt) || receipt.container.reference !== admitted.installed.pack.adapter.imageRef || receipt.container.id !== admitted.installed.pack.adapter.imageId || canonical(receipt.authority) !== canonical(authority) || receipt.enabled !== false || receipt.boundary !== boundary) fail("capability runtime receipt differs from its admission or authority boundary");
if (Date.parse(receipt.completedAt) < Date.parse(receipt.startedAt) || name !== undefined && name !== `${receipt.grant.grantId}-${sha(receipt)}.json`) fail("capability runtime receipt time or filename is invalid");
if (receipt.result.status === "succeeded" && (receipt.result.failureClass !== null || receipt.result.protocolVersion !== "2026-07-28" || !SHA_RE.test(receipt.result.toolSurfaceSha256 ?? "") || receipt.result.frames < 3 || receipt.container.startState !== "started")) fail("successful capability runtime receipt is incoherent");
if (receipt.result.status !== "succeeded" && (receipt.result.failureClass === null || receipt.result.outputBytes !== 0)) fail("failed capability runtime receipt is incoherent");
return receipt;
}
async function readReceipts(admitted, create = false, allowStage = false) {
if (!create) {
const base = join(admitted.installed.root, "capability-pack-runtime");
if (!(await lstat(base).catch((error) => error?.code === "ENOENT" ? null : Promise.reject(error)))) return { place: null, receipts: [], stages: [] };
}
const place = await roots(admitted, create), names = (await readdir(place.receipts)).sort();
const stages = names.filter((name) => RECEIPT_STAGE_RE.test(name)), finals = names.filter((name) => RECEIPT_RE.test(name));
if (finals.length > 999999 || finals.length + stages.length !== names.length || stages.length > 1 || stages.length && !allowStage) fail("capability runtime receipt root contains unsafe or recovery-required entries");
const receipts = [];
for (const name of finals) {
let receipt;
try { receipt = JSON.parse((await privateRegular(join(place.receipts, name), 512 * 1024, "capability runtime receipt")).toString("utf8")); } catch (error) { if (error instanceof CapabilityRuntimeError) throw error; fail("capability runtime receipt is not JSON"); }
validateReceipt(receipt, admitted, name);
if (receipts.some((entry) => entry.grant.grantId === receipt.grant.grantId)) fail("capability runtime contains duplicate terminal receipts");
receipts.push(receipt);
}
return { place, receipts, stages };
}
function defaultRun(command, maximumBytes) {
const result = spawnSync(command.command, command.args, { env: command.env, encoding: null, windowsHide: true, shell: false, timeout: 30000, maxBuffer: maximumBytes });
return { status: result.status, error: result.error, signal: result.signal, stdout: result.stdout ?? Buffer.alloc(0), stderr: result.stderr ?? Buffer.alloc(0) };
}
async function invoke(dependencies, command, maximumBytes, label) {
const result = await (dependencies.runDocker ?? defaultRun)(command, maximumBytes);
if (!result || typeof result !== "object" || !Number.isInteger(result.status) || !Buffer.isBuffer(result.stdout) || !Buffer.isBuffer(result.stderr) || result.stdout.length > maximumBytes || result.stderr.length > 65536 || result.error || result.signal) fail(`${label} failed or exceeded its bounded process contract`);
return result;
}
function parseInspect(result, label) {
if (result.status !== 0) {
const absence = result.stdout.toString("ascii").trim();
if (absence !== "" && absence !== "[]") fail(`${label} returned ambiguous absence evidence`);
return null;
}
if (result.stderr.length !== 0) fail(`${label} returned unexpected diagnostic output`);
let value;
try { value = JSON.parse(result.stdout.toString("utf8")); } catch { fail(`${label} returned invalid JSON`); }
if (!Array.isArray(value) || value.length !== 1 || !value[0] || typeof value[0] !== "object") fail(`${label} returned an ambiguous object set`);
return value[0];
}
function validateOwnedContainer(value, admitted, claim, runtime) {
if (value.Name !== `/${runtime.containerName}` || value.Image !== admitted.installed.pack.adapter.imageId || value.Config?.Image !== admitted.installed.pack.adapter.imageRef || value.Config?.Labels?.["com.osmantic.pixel.work-capability-claim"] !== claim.claimId || value.Config?.Labels?.["com.osmantic.pixel.work-job"] !== claim.jobId || value.Config?.Labels?.["com.osmantic.pixel.work-capability-pack"] !== admitted.installed.pack.id || value.HostConfig?.NetworkMode !== "none" || value.HostConfig?.Privileged !== false || value.HostConfig?.ReadonlyRootfs !== true) fail("capability runtime refuses to remove a container outside exact claim custody");
}
async function proveContainerAbsent(dependencies, admitted, grant, claim, runtime) {
const commands = buildCapabilityAdapterCleanupDockerCommands({ pack: admitted.installed.pack, expectedPackSha256: capabilityPackSha256(admitted.installed.pack), grant, claim, runtime });
const owned = parseInspect(await invoke(dependencies, commands.inspectOwned, 512 * 1024, "capability runtime container ownership inspection"), "capability runtime container ownership inspection");
if (owned) validateOwnedContainer(owned, admitted, claim, runtime);
if (owned) await invoke(dependencies, commands.remove, 65536, "capability runtime container removal");
const absent = await invoke(dependencies, commands.inspectAbsent, 65536, "capability runtime container absence inspection");
if (absent.status === 0 || absent.stdout.toString("ascii").trim().length !== 0) fail("capability runtime container absence was not proven");
const listed = await invoke(dependencies, commands.listAbsent, 65536, "capability runtime container absence listing");
if (listed.status !== 0 || listed.stderr.length !== 0 || listed.stdout.toString("ascii").trim().length !== 0) fail("capability runtime container absence was not proven");
}
async function createWorkspace(dependencies, admitted, grant, claim, runtime) {
if (runtime.workspaceVolumeName === null) return;
const commands = buildCapabilityWorkspaceDockerCommands({ pack: admitted.installed.pack, expectedPackSha256: capabilityPackSha256(admitted.installed.pack), grant, claim, runtime });
const created = await invoke(dependencies, commands.create, 65536, "capability runtime workspace creation");
if (created.status !== 0 || created.stderr.length !== 0 || created.stdout.toString("utf8").trim() !== runtime.workspaceVolumeName) fail("capability runtime workspace creation was not exact");
const volume = parseInspect(await invoke(dependencies, commands.inspectOwned, 512 * 1024, "capability runtime workspace inspection"), "capability runtime workspace inspection");
if (!volume) fail("capability runtime workspace was not created");
validateCapabilityWorkspaceVolume(volume, admitted.installed.pack, grant, claim, runtime);
}
async function proveWorkspaceAbsent(dependencies, admitted, grant, claim, runtime) {
if (runtime.workspaceVolumeName === null) return;
const commands = buildCapabilityWorkspaceDockerCommands({ pack: admitted.installed.pack, expectedPackSha256: capabilityPackSha256(admitted.installed.pack), grant, claim, runtime });
const owned = parseInspect(await invoke(dependencies, commands.inspectOwned, 512 * 1024, "capability runtime workspace ownership inspection"), "capability runtime workspace ownership inspection");
if (owned) validateCapabilityWorkspaceVolume(owned, admitted.installed.pack, grant, claim, runtime);
if (owned) await invoke(dependencies, commands.remove, 65536, "capability runtime workspace removal");
const absent = await invoke(dependencies, commands.inspectAbsent, 65536, "capability runtime workspace absence inspection");
const absence = absent.stdout.toString("ascii").trim();
if (absent.status === 0 || absence !== "" && absence !== "[]") fail("capability runtime workspace absence was not proven");
const listed = await invoke(dependencies, commands.listAbsent, 65536, "capability runtime workspace absence listing");
if (listed.status !== 0 || listed.stderr.length !== 0 || listed.stdout.toString("ascii").trim().length !== 0) fail("capability runtime workspace absence was not proven");
}
async function removeCid(path) {
const info = await lstat(path).catch((error) => error?.code === "ENOENT" ? null : Promise.reject(error));
if (!info) return;
if (!info.isFile() || info.isSymbolicLink() || info.nlink !== 1 || info.size > 256) fail("capability runtime CID file is unsafe");
await unlink(path); await syncDirectory(dirname(path));
}
function classify(error, recovered = false) {
if (recovered) return "uncertain-recovered";
const message = error instanceof Error ? error.message.toLowerCase() : "";
if (message.includes("runtime ceiling") || message.includes("timeout")) return "timeout";
if (message.includes("could not be started") || message.includes("launch") || message.includes("workspace creation")) return "launch";
if (message.includes("server identity") || message.includes("tool surface") || message.includes("schema")) return "identity-or-schema";
if (message.includes("bounded error") || message.includes("tool failed")) return "tool-failure";
if (message.includes("output schema") || message.includes("structured output") || message.includes("differs from structured")) return "output-validation";
if (message.includes("protocol") || message.includes("malformed") || message.includes("server request") || message.includes("incomplete")) return "protocol";
return "transport";
}
function resultEvidence(evidence, error, recovered = false) {
if (evidence) return { status: "succeeded", failureClass: null, protocolVersion: evidence.protocolVersion, toolSurfaceSha256: evidence.toolSurfaceSha256, frames: evidence.frames, stdoutBytes: evidence.stdoutBytes, stderrBytes: evidence.stderrBytes, stderrSha256: evidence.stderrSha256, outputBytes: Buffer.byteLength(canonical(evidence.structuredContent)), externalEffects: false, authority: "none" };
return { status: recovered ? "uncertain-recovered" : "failed", failureClass: classify(error, recovered), protocolVersion: null, toolSurfaceSha256: null, frames: 0, stdoutBytes: 0, stderrBytes: 0, stderrSha256: sha(Buffer.alloc(0)), outputBytes: 0, externalEffects: false, authority: "none" };
}
function receiptFor({ admitted, healthReceiptSha256, grant, claim, operation, toolName, inputBytes, watchdogDecisionSha256, startedAt, completedAt, result }) {
return {
$schema: "https://osmantic.com/pixel/schemas/work-capability-runtime-v1.schema.json", schemaVersion: 1, operation: "pixel-work-capability-runtime",
pack: { ...admitted.receipt.pack }, admissionReceiptSha256: sha(admitted.receipt), healthReceiptSha256,
grant: { grantId: grant.grantId, grantSha256: sha(grant), jobId: grant.jobId, checkpointSha256: grant.checkpointSha256, dataClassification: grant.dataClassification, tool: toolName },
claim: { claimId: claim.claimId, claimSha256: sha(claim) }, operationCustody: { bindingSha256: operation.bindingSha256, token: operation.token },
request: { inputBytes, watchdogDecisionSha256 }, startedAt: startedAt.toISOString(), completedAt: completedAt.toISOString(), result,
container: { reference: admitted.installed.pack.adapter.imageRef, id: admitted.installed.pack.adapter.imageId, startState: result.status === "succeeded" ? "started" : "uncertain", network: "none", removed: true, absenceProven: true },
workspace: { used: admitted.installed.pack.adapter.workspace === "disposable-read-write", removed: true, absenceProven: true }, enabled: false, authority: { ...authority }, boundary,
};
}
async function publishReceipt({ admitted, receipt, afterStage }) {
const history = await readReceipts(admitted, true);
if (history.receipts.some((entry) => entry.grant.grantId === receipt.grant.grantId)) fail("capability runtime grant already has terminal evidence");
validateReceipt(receipt, admitted);
const temporary = join(history.place.receipts, `.receipt-${randomBytes(8).toString("hex")}`), destination = join(history.place.receipts, `${receipt.grant.grantId}-${sha(receipt)}.json`);
await writeExclusive(temporary, `${JSON.stringify(receipt, null, 2)}\n`);
if (afterStage) await afterStage();
await rename(temporary, destination); await syncDirectory(history.place.receipts);
return Object.freeze(receipt);
}
function projection(receipt, structuredContent) {
return Object.freeze({ schemaVersion: 1, operation: "pixel-work-capability-runtime-result", status: receipt.result.status === "succeeded" ? "succeeded-disabled" : `${receipt.result.status}-contained`, pack: { ...receipt.pack }, grantId: receipt.grant.grantId, receiptSha256: sha(receipt), dataClassification: receipt.grant.dataClassification, ...(structuredContent === undefined ? {} : { structuredContent, contentSha256: sha(structuredContent) }), enabled: false, authority: { ...authority }, boundary });
}
function checkedDependencies(dependencies) {
if (!dependencies || typeof dependencies !== "object" || Array.isArray(dependencies) || ["runDocker", "runMcp", "afterIntent", "afterClaim", "afterCleanup", "afterReceiptStage", "afterReceipt"].some((key) => dependencies[key] !== undefined && typeof dependencies[key] !== "function")) fail("capability runtime dependencies are invalid");
return dependencies;
}
export async function executeCapabilityTool({ stateRoot, id, version, allowedSignersPath, sshKeygenPath, dockerConfigPath, grant, toolName, input, preflightDecision, maxHealthAgeMs, claimSuffix = randomBytes(6).toString("hex"), clock = () => new Date(), dependencies = {} }) {
checkedDependencies(dependencies);
const startedAt = observed(clock, "capability runtime start"), admitted = await loadCapabilityImageAdmission({ stateRoot, id, version, allowedSignersPath, sshKeygenPath });
checkedGrant(grant, admitted);
if (!grant.tools.includes(toolName) || validateWorkWatchdogDecision(preflightDecision).length) fail("capability runtime request is not bound to a granted tool and valid watchdog decision");
const inputBytes = Buffer.byteLength(canonical(input));
if (inputBytes > grant.limits.maxInputBytes) fail("capability runtime input exceeds its grant");
if (typeof dockerConfigPath !== "string" || resolve(dockerConfigPath) !== dockerConfigPath) fail("capability runtime Docker configuration path must be absolute");
const config = await privateDirectory(dockerConfigPath, "capability runtime Docker configuration");
if ((await readdir(config)).length !== 0) fail("capability runtime Docker configuration must be empty and credential-free");
const health = await loadPassingCapabilityHealth({ stateRoot, id, version, allowedSignersPath, sshKeygenPath, now: startedAt, maxAgeMs: maxHealthAgeMs });
const place = await roots(admitted, true), containerName = `pixel-cap-run-${randomBytes(8).toString("hex")}`, workspaceVolumeName = admitted.installed.pack.adapter.workspace === "disposable-read-write" ? `pixel-cap-work-${randomBytes(8).toString("hex")}` : null;
const runtime = { dockerPath: DOCKER_PATH, dockerConfigPath: config, cidFile: join(place.cids, `${grant.grantId}.cid`), containerName, workspaceVolumeName, imageIdentifier: admitted.installed.pack.adapter.imageRef };
const watchdogDecisionSha256 = sha(preflightDecision), bindingSha256 = runtimeBinding({ pack: admitted.receipt.pack, admissionReceiptSha256: sha(admitted.receipt), healthReceiptSha256: health.receiptSha256, grant, toolName, watchdogDecisionSha256, inputBytes, containerName, workspaceVolumeName, cidFile: runtime.cidFile, dockerConfigPath: config });
const operation = await operationCall(acquireCapabilityPackOperation({ stateRoot: admitted.installed.root, pack: admitted.receipt.pack, kind: "tool-execution", bindingSha256 }));
try {
const currentHealth = await loadPassingCapabilityHealth({ stateRoot, id, version, allowedSignersPath, sshKeygenPath, now: startedAt, maxAgeMs: maxHealthAgeMs });
if (currentHealth.receiptSha256 !== health.receiptSha256) fail("capability health changed before runtime custody");
} catch (error) { await operationCall(releaseCapabilityPackOperation({ stateRoot: admitted.installed.root, operation })); throw error; }
const intent = { schemaVersion: 1, pack: { ...admitted.receipt.pack }, admissionReceiptSha256: sha(admitted.receipt), healthReceiptSha256: health.receiptSha256, grant: structuredClone(grant), toolName, inputBytes, watchdogDecisionSha256, containerName, workspaceVolumeName, cidFile: runtime.cidFile, dockerConfigPath: config, operationBindingSha256: operation.bindingSha256, operationToken: operation.token, boundary: cleanupBoundary };
const intentPath = join(place.cleanups, `${grant.grantId}.json`);
try { await writeExclusive(intentPath, `${JSON.stringify(intent, null, 2)}\n`); await syncDirectory(place.cleanups); }
catch (error) { await operationCall(releaseCapabilityPackOperation({ stateRoot: admitted.installed.root, operation })); throw error; }
if (dependencies.afterIntent) await dependencies.afterIntent();
let claimed;
try { claimed = await claimCapabilityGrant({ stateRoot: admitted.installed.root, pack: admitted.installed.pack, expectedPackSha256: capabilityPackSha256(admitted.installed.pack), grant, now: observed(clock, "capability runtime claim"), suffix: claimSuffix }); }
catch (error) { await unlink(intentPath); await syncDirectory(place.cleanups); await operationCall(releaseCapabilityPackOperation({ stateRoot: admitted.installed.root, operation })); throw error; }
if (dependencies.afterClaim) await dependencies.afterClaim();
const claim = claimed.claim;
let evidence = null, executionError = null;
try {
await createWorkspace(dependencies, admitted, grant, claim, runtime);
const command = buildCapabilityAdapterDockerCommand({ pack: admitted.installed.pack, expectedPackSha256: capabilityPackSha256(admitted.installed.pack), grant, claim, runtime });
evidence = await (dependencies.runMcp ?? runCapabilityMcpToolWithTrustedLaunch)({ stateRoot: admitted.installed.root, pack: admitted.installed.pack, expectedPackSha256: capabilityPackSha256(admitted.installed.pack), grant, claim, toolName, input, preflightDecision, command: command.command, args: command.args, cwd: admitted.installed.root, env: command.env, now: observed(clock, "capability runtime execution") });
} catch (error) { executionError = error; }
await proveContainerAbsent(dependencies, admitted, grant, claim, runtime);
await proveWorkspaceAbsent(dependencies, admitted, grant, claim, runtime);
await removeCid(runtime.cidFile);
if (dependencies.afterCleanup) await dependencies.afterCleanup();
const completedAt = observed(clock, "capability runtime completion");
if (completedAt.getTime() < startedAt.getTime()) fail("capability runtime time is reversed");
const receipt = await publishReceipt({ admitted, receipt: receiptFor({ admitted, healthReceiptSha256: health.receiptSha256, grant, claim, operation, toolName, inputBytes, watchdogDecisionSha256, startedAt, completedAt, result: resultEvidence(evidence, executionError) }), afterStage: dependencies.afterReceiptStage });
if (dependencies.afterReceipt) await dependencies.afterReceipt();
await unlink(intentPath); await syncDirectory(place.cleanups);
await operationCall(releaseCapabilityPackOperation({ stateRoot: admitted.installed.root, operation }));
return projection(receipt, evidence?.structuredContent);
}
async function readIntent(admitted, operation, place) {
const names = (await readdir(place.cleanups)).sort();
if (names.length > 1 || names.some((name) => !GRANT_RE.test(name.slice(0, -5)) || !name.endsWith(".json"))) fail("capability runtime cleanup custody is ambiguous");
if (names.length === 0) return null;
let intent;
try { intent = JSON.parse((await privateRegular(join(place.cleanups, names[0]), 512 * 1024, "capability runtime cleanup intent")).toString("utf8")); } catch (error) { if (error instanceof CapabilityRuntimeError) throw error; fail("capability runtime cleanup intent is not JSON"); }
return { intent: checkedIntent(intent, admitted, operation, names[0]), path: join(place.cleanups, names[0]) };
}
async function finalizeStagedReceipt(admitted, operation, history) {
if (history.stages.length === 0) return null;
const path = join(history.place.receipts, history.stages[0]); let receipt;
try { receipt = JSON.parse((await privateRegular(path, 512 * 1024, "staged capability runtime receipt")).toString("utf8")); } catch (error) { if (error instanceof CapabilityRuntimeError) throw error; fail("staged capability runtime receipt is not JSON"); }
validateReceipt(receipt, admitted);
if (receipt.operationCustody.token !== operation.token || receipt.operationCustody.bindingSha256 !== operation.bindingSha256) fail("staged capability runtime receipt differs from current custody");
if (history.receipts.some((entry) => entry.grant.grantId === receipt.grant.grantId)) fail("staged capability runtime receipt duplicates terminal evidence");
await rename(path, join(history.place.receipts, `${receipt.grant.grantId}-${sha(receipt)}.json`)); await syncDirectory(history.place.receipts);
return receipt;
}
export async function recoverCapabilityRuntime({ stateRoot, id, version, allowedSignersPath, sshKeygenPath, clock = () => new Date(), dependencies = {} }) {
checkedDependencies(dependencies); const admitted = await loadCapabilityImageAdmission({ stateRoot, id, version, allowedSignersPath, sshKeygenPath });
const operation = await operationCall(loadCapabilityPackOperation({ stateRoot: admitted.installed.root, id, version, packSha256: admitted.receipt.pack.packSha256 }));
if (operation.kind !== "tool-execution") fail("capability runtime recovery is not the current pack operation");
const place = await roots(admitted, true), history = await readReceipts(admitted, true, true);
let terminal = history.receipts.find((receipt) => receipt.operationCustody.token === operation.token && receipt.operationCustody.bindingSha256 === operation.bindingSha256) ?? await finalizeStagedReceipt(admitted, operation, history);
const held = await readIntent(admitted, operation, place);
if (!held) {
if (!terminal) {
await operationCall(releaseCapabilityPackOperation({ stateRoot: admitted.installed.root, operation }));
return Object.freeze({ schemaVersion: 1, operation: "pixel-work-capability-runtime-recovery", status: "aborted-before-custody", enabled: false, authority: { ...authority }, boundary });
}
await operationCall(releaseCapabilityPackOperation({ stateRoot: admitted.installed.root, operation }));
return projection(terminal);
}
const { intent } = held, health = await statusCapabilityHealth({ stateRoot, id, version, allowedSignersPath, sshKeygenPath });
if (health.receiptSha256 !== intent.healthReceiptSha256) fail("capability runtime recovery health binding changed");
const config = await privateDirectory(intent.dockerConfigPath, "capability runtime Docker configuration");
if ((await readdir(config)).length !== 0) fail("capability runtime Docker configuration must remain empty and credential-free");
const grant = checkedGrant(intent.grant, admitted), claim = await loadCapabilityGrantClaim({ stateRoot: admitted.installed.root, pack: admitted.installed.pack, expectedPackSha256: capabilityPackSha256(admitted.installed.pack), grant, optional: true });
if (!claim) {
await removeCid(intent.cidFile); await unlink(held.path); await syncDirectory(place.cleanups);
await operationCall(releaseCapabilityPackOperation({ stateRoot: admitted.installed.root, operation }));
return Object.freeze({ schemaVersion: 1, operation: "pixel-work-capability-runtime-recovery", status: "aborted-before-claim", grantId: grant.grantId, enabled: false, authority: { ...authority }, boundary });
}
const runtime = { dockerPath: DOCKER_PATH, dockerConfigPath: config, cidFile: intent.cidFile, containerName: intent.containerName, workspaceVolumeName: intent.workspaceVolumeName, imageIdentifier: admitted.installed.pack.adapter.imageRef };
await proveContainerAbsent(dependencies, admitted, grant, claim, runtime); await proveWorkspaceAbsent(dependencies, admitted, grant, claim, runtime); await removeCid(runtime.cidFile);
if (!terminal) {
const recoveredAt = observed(clock, "capability runtime recovery");
terminal = await publishReceipt({ admitted, receipt: receiptFor({ admitted, healthReceiptSha256: intent.healthReceiptSha256, grant, claim, operation, toolName: intent.toolName, inputBytes: intent.inputBytes, watchdogDecisionSha256: intent.watchdogDecisionSha256, startedAt: recoveredAt, completedAt: recoveredAt, result: resultEvidence(null, null, true) }) });
}
await unlink(held.path); await syncDirectory(place.cleanups);
await operationCall(releaseCapabilityPackOperation({ stateRoot: admitted.installed.root, operation }));
return projection(terminal);
}
export async function statusCapabilityRuntime({ stateRoot, id, version, allowedSignersPath, sshKeygenPath }) {
const admitted = await loadCapabilityImageAdmission({ stateRoot, id, version, allowedSignersPath, sshKeygenPath }), history = await readReceipts(admitted, false, true);
const operation = await operationCall(loadCapabilityPackOperation({ stateRoot: admitted.installed.root, id, version, packSha256: admitted.receipt.pack.packSha256, optional: true }));
let cleanupRequired = 0;
if (history.place) {
const names = (await readdir(history.place.cleanups)).sort();
if (names.length > 1 || names.some((name) => !name.endsWith(".json") || !GRANT_RE.test(name.slice(0, -5)))) fail("capability runtime cleanup root contains an unsafe entry");
if (names.length && operation?.kind !== "tool-execution") fail("capability runtime cleanup custody lacks its exact operation");
if (names.length) await readIntent(admitted, operation, history.place);
if (history.stages.length && operation?.kind !== "tool-execution") fail("staged capability runtime evidence lacks its exact operation");
cleanupRequired = Math.max(names.length, history.stages.length, operation?.kind === "tool-execution" ? 1 : 0);
} else if (operation?.kind === "tool-execution") cleanupRequired = 1;
const latest = history.receipts.at(-1) ?? null;
return Object.freeze({ schemaVersion: 1, operation: "pixel-work-capability-runtime-status", status: cleanupRequired ? "cleanup-required" : "disabled", receipts: history.receipts.length, latest: latest ? { grantId: latest.grant.grantId, result: latest.result.status, receiptSha256: sha(latest) } : null, cleanupRequired, enabled: false, authority: { ...authority }, boundary });
}
export const capabilityRuntimeBoundary = boundary;