@fungi.computer/computer 0.0.0-stage → 0.1.0

package/dist/operation-contract.js

@@ -0,0 +1,450 @@
+import { replayKey, defineIdFamily } from "@fungi.computer/cairn";
+import * as z from "zod";
+import { attachedBackendIdSchema } from "./computer-backends.js";
+const utf8 = new TextEncoder();
+export const maximumFileBytes = 128 * 1_024;
+export const maximumListEntries = 256;
+export const maximumPatternCharacters = 512;
+export const maximumCommandCharacters = 16 * 1_024;
+export const maximumStreamBytes = 64 * 1_024;
+/** The bound for ordinary Computer commands; hosts own any admitted job budget. */
+export const maximumExecutionTimeMs = 120_000;
+export const genericComputerExecutionBudget = Object.freeze({ maximumTimeMs: maximumExecutionTimeMs });
+export const computerValueSchema = z.json();
+export const capabilityNameSchema = z.lazy(() => z
+    .string()
+    .min(1)
+    .max(128)
+    .regex(/^[A-Za-z][A-Za-z0-9_]*$/));
+/** One valid TCP port number, used only with this Computer's container. */
+export const computerPortSchema = z.lazy(() => z.number().int().min(1).max(65_535));
+export const maximumExposedPorts = 64;
+/** computerd's Workspace RPC port, pinned by the Cloudflare container backend. */
+export const computerDaemonPort = 8080;
+/** The Computer-owned terminal server inside the container image. */
+export const computerTerminalPort = 7681;
+/**
+ * Ports served by the Computer's own in-container daemons. An admitted
+ * preview must never reach a control plane.
+ */
+export const computerReservedPorts = new Set([
+    computerDaemonPort,
+    computerTerminalPort,
+]);
+export function isComputerReservedPort(port) {
+    return computerReservedPorts.has(port);
+}
+export const computerPortInputSchema = z.strictObject({
+    port: computerPortSchema,
+});
+export const computerPortOutputSchema = z.lazy(() => z.strictObject({
+    port: computerPortSchema,
+    exposed: z.boolean(),
+}));
+export const computerPortRemovalOutputSchema = z.lazy(() => z.strictObject({
+    port: computerPortSchema,
+    removed: z.boolean(),
+}));
+export const computerPortsOutputSchema = z.lazy(() => z.strictObject({
+    ports: z.array(computerPortSchema).max(maximumExposedPorts),
+}));
+/** The port belongs to a Computer daemon and cannot be admitted for preview. */
+export class ComputerPortReservedError extends Error {
+    constructor(port) {
+        super(`Computer port ${String(port)} is reserved`);
+        this.name = "ComputerPortReservedError";
+    }
+}
+/** A requested port cannot be reserved; no other process identity is disclosed. */
+export class ComputerPortConflictError extends Error {
+    constructor() {
+        super("Computer port is unavailable");
+        this.name = "ComputerPortConflictError";
+    }
+}
+/** This Computer already admits the maximum number of preview ports. */
+export class ComputerPortLimitError extends Error {
+    constructor() {
+        super(`Computer can expose at most ${String(maximumExposedPorts)} ports`);
+        this.name = "ComputerPortLimitError";
+    }
+}
+// Schema keywords are opaque transport data. Zod still validates every value
+// as JSON before the description leaves or enters the Computer boundary.
+const schemaDocument = z.lazy(() => z
+    .record(z.string(), z.unknown())
+    .refine((value) => computerValueSchema.safeParse(value).success, "Capability schema must contain JSON values"));
+/** Native operation descriptions shared by discovery and its OpenAPI document. */
+export const computerCapabilitiesSchema = z.lazy(() => z.array(z.strictObject({
+    id: capabilityNameSchema,
+    name: capabilityNameSchema,
+    kind: z.string(),
+    description: z.string(),
+    parameters: schemaDocument,
+    output: schemaDocument,
+})));
+export const pathSchema = z
+    .string()
+    .min(1)
+    .max(4_096)
+    .startsWith("/")
+    .refine((path) => !path.includes("\0"), "Path cannot contain null bytes");
+export const boundedTextSchema = (minimumLength = 0) => z
+    .string()
+    .min(minimumLength)
+    .refine((content) => utf8.encode(content).byteLength <= maximumFileBytes, `Text exceeds the ${String(maximumFileBytes)}-byte Computer bound`);
+/** Complete bounded UTF-8 text reads. Binary reads use the same path input. */
+export const readInputSchema = z.strictObject({ path: pathSchema });
+export const readOutputSchema = z.lazy(() => z.strictObject({
+    path: pathSchema,
+    content: boundedTextSchema(),
+}));
+/** Optional byte window; text reads remain complete and independently bounded. */
+export const readBytesInputSchema = z.strictObject({
+    path: pathSchema,
+    byteOffset: z.number().int().nonnegative().optional(),
+    byteLength: z.number().int().positive().max(maximumFileBytes).optional(),
+});
+/** Finite byte-read reply used by admitted App frame bindings. */
+export const computerByteReadReplySchema = z.lazy(() => z.strictObject({
+    path: readBytesInputSchema.shape.path,
+    byteOffset: z.number().int().nonnegative(),
+    content: z.string(),
+    encoding: z.literal("base64"),
+    truncated: z.boolean(),
+}));
+/** Host-admitted App method preview; parsing does not grant port access. */
+export const appMethodPreviewResultSchema = z.lazy(() => z.strictObject({
+    previewUrl: z.url(),
+    expiresAt: z.number().int().positive(),
+}));
+export const listLimitSchema = z
+    .number()
+    .int()
+    .min(1)
+    .max(maximumListEntries)
+    .default(100);
+export const listOffsetSchema = z.number().int().nonnegative().default(0);
+export const listInputSchema = z.strictObject({
+    path: pathSchema.default("/"),
+    limit: listLimitSchema,
+    offset: listOffsetSchema,
+});
+const listEntrySchema = z.lazy(() => z.strictObject({
+    name: z.string(),
+    size: z.number().int().nonnegative(),
+    modifiedAt: z.number(),
+    type: z.enum(["file", "directory", "symlink"]),
+}));
+export const listOutputSchema = z.lazy(() => z.strictObject({
+    path: pathSchema,
+    entries: z.array(listEntrySchema).max(maximumListEntries),
+    nextOffset: z.number().int().nonnegative().nullable(),
+}));
+export const fileContentSchema = z.lazy(() => z
+    .string()
+    .refine((content) => utf8.encode(content).byteLength <= maximumFileBytes, "File exceeds the Computer write bound"));
+export const writeInputSchema = z.strictObject({
+    path: pathSchema,
+    content: fileContentSchema,
+});
+export const writeOutputSchema = z.lazy(() => z.strictObject({
+    path: pathSchema,
+    bytes: z.number().int().nonnegative(),
+}));
+export const writeBytesInputSchema = readInputSchema;
+export const replaceInputSchema = z.strictObject({
+    path: pathSchema,
+    expectedContent: fileContentSchema,
+    content: fileContentSchema,
+});
+export const replaceOutputSchema = writeOutputSchema;
+export const globInputSchema = z.lazy(() => z.strictObject({
+    path: pathSchema,
+    pattern: z.string().min(1).max(maximumPatternCharacters),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(maximumListEntries)
+        .default(maximumListEntries),
+}));
+export const globOutputSchema = z.lazy(() => z.strictObject({
+    path: pathSchema,
+    matches: z.array(pathSchema).max(maximumListEntries),
+    truncated: z.boolean(),
+}));
+export const grepInputSchema = z.lazy(() => z.strictObject({
+    path: pathSchema,
+    pattern: z.string().min(1).max(maximumPatternCharacters),
+    regex: z.boolean().default(false),
+    ignoreCase: z.boolean().default(false),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(maximumListEntries)
+        .default(maximumListEntries),
+}));
+export const grepOutputSchema = z.lazy(() => z.strictObject({
+    path: pathSchema,
+    matches: z
+        .array(z.strictObject({
+        path: pathSchema,
+        line: z.number().int().positive(),
+        text: z.string(),
+    }))
+        .max(maximumListEntries),
+    truncated: z.boolean(),
+}));
+export const editInputSchema = z.lazy(() => z.strictObject({
+    path: pathSchema,
+    oldText: boundedTextSchema(1),
+    newText: boundedTextSchema(),
+}));
+export const editOutputSchema = z.lazy(() => z.strictObject({
+    path: pathSchema,
+    bytes: z.number().int().nonnegative(),
+    diff: z.string(),
+    firstChangedLine: z.number().int().positive().nullable(),
+}));
+// Native Files tools and Computer HTTP decode the same patch contract.
+export { patchInputSchema, patchOutputSchema, } from "@fungi.computer/knapsack/files-patch";
+export const mkdirInputSchema = z.lazy(() => z.strictObject({
+    path: pathSchema,
+    recursive: z.boolean().default(true),
+}));
+export const mkdirOutputSchema = z.strictObject({ path: pathSchema });
+/**
+ * Host-owned idempotency key for one `exec` or `bash` tool invocation. The
+ * host mints it once per invocation and keeps it across its own retries of that
+ * invocation; the model never sees or supplies it.
+ */
+export const computerRequestIdSchema = z.uuid({ version: "v7" });
+/** Mint the request ID for one host tool invocation. */
+export function mintComputerRequestId() {
+    return computerRequestIdSchema.parse(replayKey());
+}
+/** Model-facing command input. It carries no request identity. */
+function executionInputSchema(budget) {
+    return z.strictObject({
+        command: z.string().min(1).max(maximumCommandCharacters),
+        cwd: pathSchema.optional(),
+        /** An attached backend id; omitted routes by the Computer's default order. */
+        backend: attachedBackendIdSchema.optional(),
+        timeoutMs: z
+            .number()
+            .int()
+            .min(1)
+            .max(budget.maximumTimeMs)
+            .default(10_000),
+    });
+}
+export const execInputSchema = executionInputSchema(genericComputerExecutionBudget);
+/** Resource hosts select a budget only after admitting their job principal. */
+export function computerExecutionRequestSchema(budget) {
+    return executionInputSchema(budget).extend({
+        requestId: computerRequestIdSchema,
+    });
+}
+/** Host-to-Computer command request: the model input plus the host's ID. */
+export const execRequestSchema = execInputSchema.extend({
+    requestId: computerRequestIdSchema,
+});
+export const execOutputSchema = z.strictObject({
+    status: z.enum(["completed", "failed", "cancelled"]),
+    exitCode: z.number().int(),
+    stdout: z.string(),
+    stderr: z.string(),
+    truncated: z.boolean(),
+});
+/** One long-running container process owned by this Computer. */
+const processIds = defineIdFamily({
+    family: "computer-process",
+    version: 1,
+    kinds: { process: { prefix: "computer_process" } },
+}).process;
+export const computerProcessIdSchema = z.lazy(() => z.string().refine((value) => processIds.is(value)));
+/** At most this many processes may be running in one host scope at once. */
+export const maximumRunningProcesses = 16;
+/** At most this many process records, running or exited, are kept per host scope. */
+export const maximumProcessRecords = 64;
+/** Mint the durable identity of one started process. */
+export function mintComputerProcessId() {
+    return processIds.generate();
+}
+export const processStartInputSchema = z.strictObject({
+    requestId: z.string().min(1).max(256),
+    requestScope: z.string().min(1).max(512),
+    port: computerPortSchema.optional(),
+    command: z.string().min(1).max(maximumCommandCharacters),
+    cwd: pathSchema.optional(),
+});
+/** Model input excludes the host's replay identity and authority scope. */
+export const processStartToolInputSchema = processStartInputSchema.omit({
+    requestId: true,
+    requestScope: true,
+});
+/** A trusted App host binds replay identity to its admitted installation and caller. */
+export function installationProcessScope(installation, method, actor) {
+    return processStartInputSchema.shape.requestScope.parse(`installation:${JSON.stringify([installation, method, `${actor.kind}:${actor.id}`])}`);
+}
+export const processIdInputSchema = z.strictObject({
+    id: computerProcessIdSchema,
+});
+/**
+ * `running`: computerd still reports the execution live. `exited`: it ended;
+ * `exitCode` is null when the runtime that ran it was replaced or its record
+ * expired before the exit code was observed. `uncertain`: the Computer could
+ * not reach its container to check, so neither is claimed.
+ */
+export const computerProcessStateSchema = z.enum([
+    "running",
+    "exited",
+    "uncertain",
+]);
+/**
+ * `synced`: the drain that recorded this exit read all the way to EOF,
+ * which is also the read that runs computerd's post-command pull.
+ * `pending`: that drain gave up waiting at its own deadline (a
+ * backgrounded child, for example `node server.js &`, can hold the
+ * transport open long after its parent exits) -- a background
+ * continuation keeps watching and upgrades this row to `synced` once it
+ * reaches that real EOF, so `pending` rows stay updatable. `unknown`:
+ * this exit was recorded with no pull evidence at all (a replaced
+ * runtime, an expired record, or any other exit path that never drained
+ * for one). Never claim `synced` without the specific evidence for this
+ * exit; default to `unknown`, not `synced`.
+ */
+export const computerProcessSyncSchema = z.enum([
+    "synced",
+    "pending",
+    "unknown",
+]);
+export const computerProcessSchema = z.strictObject({
+    id: computerProcessIdSchema,
+    port: computerPortSchema.nullable(),
+    command: z.string(),
+    cwd: z.string().nullable(),
+    state: computerProcessStateSchema,
+    exitCode: z.number().int().nullable(),
+    sync: computerProcessSyncSchema,
+    startedAt: z.number().int(),
+    endedAt: z.number().int().nullable(),
+});
+export const processListOutputSchema = z.strictObject({
+    processes: z.array(computerProcessSchema).max(maximumProcessRecords),
+});
+export const processKillOutputSchema = z.lazy(() => z.strictObject({
+    process: computerProcessSchema,
+    signalled: z.boolean(),
+}));
+/** No process with this id was started on this Computer. */
+export class ComputerProcessNotFoundError extends Error {
+    constructor(id) {
+        super(`Computer process not found: ${id}`);
+        this.name = "ComputerProcessNotFoundError";
+    }
+}
+/** Every process slot is occupied by a running process. */
+export class ComputerProcessLimitError extends Error {
+    constructor() {
+        super(`Computer process scope can run at most ${String(maximumRunningProcesses)} processes`);
+        this.name = "ComputerProcessLimitError";
+    }
+}
+export const computerOperationStatusSchema = z.enum([
+    "accepted",
+    "running",
+    "succeeded",
+    "failed",
+    "unknown",
+    "expired",
+]);
+/** Durable operation status returned to the host that owns the request ID. */
+export const computerOperationResultSchema = z.strictObject({
+    requestId: computerRequestIdSchema,
+    status: computerOperationStatusSchema,
+    output: execOutputSchema.nullable(),
+});
+/** Model-facing command result: the durable status without the host's ID. */
+export const computerToolResultSchema = computerOperationResultSchema.omit({
+    requestId: true,
+});
+/** Project one host operation result onto the model-facing tool result. */
+export function computerToolResult(result) {
+    return computerToolResultSchema.parse({
+        status: result.status,
+        output: result.output,
+    });
+}
+/** Public operation vocabulary; transport adapters map these to routes. */
+export const computerOperationSchema = z.enum([
+    "files.read",
+    "files.readBytes",
+    "files.write",
+    "files.writeBytes",
+    "files.list",
+    "files.glob",
+    "files.grep",
+    "files.edit",
+    "files.patch",
+    "mkdir",
+    "bash",
+    "exec",
+]);
+/** The expected file contents no longer match at atomic replacement. */
+export class ComputerFileConflict extends Error {
+    constructor() {
+        super("Files edit conflict: contents changed before replacement");
+        this.name = "ComputerFileConflict";
+    }
+}
+/** A byte window starts beyond the current file extent. */
+export class ComputerFileRangeError extends Error {
+    size;
+    constructor(size) {
+        super("Byte offset exceeds file size");
+        this.size = size;
+        this.name = "ComputerFileRangeError";
+    }
+}
+/** The requested file bytes exceed the admitted read bound. */
+export class ComputerFileTooLargeError extends Error {
+    constructor() {
+        super("File exceeds the Computer read bound");
+        this.name = "ComputerFileTooLargeError";
+    }
+}
+function capability(id, kind, description, input, output) {
+    const parameters = structuredClone(z.toJSONSchema(input));
+    const result = structuredClone(z.toJSONSchema(output));
+    return computerValueSchema.parse({
+        id,
+        name: id,
+        kind,
+        description,
+        parameters,
+        output: result,
+    });
+}
+let capabilities;
+/**
+ * The operations every Computer advertises; static, so hosts can describe them
+ * without a call. Built on first read: deriving JSON Schema for every operation
+ * is real work that a Worker should not pay at startup.
+ */
+export function computerCapabilities() {
+    capabilities ??= computerCapabilitiesSchema.parse([
+        capability("read", "fileStore", "Read one bounded UTF-8 file from this Computer.", readInputSchema, readOutputSchema),
+        capability("list", "fileStore", "List one bounded page of a directory on this Computer.", listInputSchema, listOutputSchema),
+        capability("mkdir", "fileStore", "Create a directory on this Computer.", mkdirInputSchema, mkdirOutputSchema),
+        capability("write", "fileStore", "Write one bounded UTF-8 file without creating its parent directory.", writeInputSchema, writeOutputSchema),
+        capability("bash", "runtime", "Run one bounded shell command in this Computer's Linux container, with node, npm and the programs installed there.", execInputSchema, computerToolResultSchema),
+        capability("exec", "runtime", "Run one bounded command in a lightweight Worker shell over this Computer's files. It has no node, npm or installed programs; use bash to run programs.", execInputSchema, computerToolResultSchema),
+        capability("start_process", "runtime", "Start one long-running command, such as a dev server, in this Computer's container. Returns its durable process id.", processStartToolInputSchema, computerProcessSchema),
+        capability("list_processes", "runtime", "List this Computer's started processes as running, exited or uncertain.", z.strictObject({}), processListOutputSchema),
+        capability("kill_process", "runtime", "Send SIGTERM to one running process on this Computer.", processIdInputSchema, processKillOutputSchema),
+    ]);
+    return capabilities;
+}

package/dist/operation-record.d.ts

@@ -0,0 +1,50 @@
+import { type ComputerExecOutput, type ComputerOperationResult, type ComputerRequestId } from "./operation-contract.js";
+/** Terminal status records are retained for 7 days. */
+export declare const operationRetentionMs: number;
+/** Command output may contain secrets, so it is cleared after 24 hours. */
+export declare const operationOutputRetentionMs: number;
+/** At most this many status records are stored per Computer. */
+export declare const maximumOperationRecords = 500;
+/**
+ * A request ID is admitted as new work only when its UUIDv7 time is within this
+ * distance of the owner's clock. Records stay protected from capacity eviction
+ * until both their acceptance time and their ID time are older than the window,
+ * so a missing in-window ID was never admitted and an out-of-window ID expires.
+ */
+export declare const operationAdmissionWindowMs: number;
+export declare class ComputerOperationConflictError extends Error {
+    constructor();
+}
+export declare class ComputerOperationLimitError extends Error {
+    constructor();
+}
+export declare class ComputerRequestInvalidError extends Error {
+    constructor();
+}
+/** The Durable Object storage surface this record owns. */
+export type ComputerOperationStorage = Pick<DurableObjectStorage, "sql" | "transactionSync">;
+/**
+ * Durable `exec`/`bash` operation outcomes for one Computer. Every retention,
+ * eviction and expiry decision uses the owner's clock; a caller's UUIDv7 time
+ * only selects whether an unseen ID is inside the admission window.
+ */
+export declare class ComputerOperationRecord {
+    #private;
+    constructor(storage: ComputerOperationStorage, now: () => number);
+    /**
+     * Atomically return the recorded state of a known ID, or admit a new one as
+     * `accepted`. `undefined` means the caller now owns dispatching it once.
+     */
+    admit(requestIdInput: string, inputHash: string, accept: () => void): ComputerOperationResult | undefined;
+    /** Record entry into the Workspace command. */
+    markRunning(requestId: ComputerRequestId): void;
+    /** Record the one terminal command result. */
+    settle(requestId: ComputerRequestId, output: ComputerExecOutput): void;
+    /**
+     * The command may have started, but no terminal result is established. The
+     * cause is logged so capacity or start failures stay diagnosable.
+     */
+    settleUnknown(requestId: ComputerRequestId, cause: string): void;
+    /** Durable status lookup; an unseen ID older than the window is expired. */
+    status(requestIdInput: string, accept: () => void): ComputerOperationResult;
+}

package/dist/operation-record.js

@@ -0,0 +1,162 @@
+import { computerOperationResultSchema, computerRequestIdSchema, execOutputSchema, } from "./operation-contract.js";
+/** Terminal status records are retained for 7 days. */
+export const operationRetentionMs = 7 * 24 * 60 * 60 * 1_000;
+/** Command output may contain secrets, so it is cleared after 24 hours. */
+export const operationOutputRetentionMs = 24 * 60 * 60 * 1_000;
+/** At most this many status records are stored per Computer. */
+export const maximumOperationRecords = 500;
+/**
+ * A request ID is admitted as new work only when its UUIDv7 time is within this
+ * distance of the owner's clock. Records stay protected from capacity eviction
+ * until both their acceptance time and their ID time are older than the window,
+ * so a missing in-window ID was never admitted and an out-of-window ID expires.
+ */
+export const operationAdmissionWindowMs = 5 * 60 * 1_000;
+export class ComputerOperationConflictError extends Error {
+    constructor() {
+        super("Computer request ID is already bound to another operation");
+        this.name = "ComputerOperationConflictError";
+    }
+}
+export class ComputerOperationLimitError extends Error {
+    constructor() {
+        super("Computer operation record capacity is occupied by recent or active work");
+        this.name = "ComputerOperationLimitError";
+    }
+}
+export class ComputerRequestInvalidError extends Error {
+    constructor() {
+        super("Computer request ID is outside the allowed clock-skew window");
+        this.name = "ComputerRequestInvalidError";
+    }
+}
+/** The embedded UUIDv7 millisecond time; the ID is already Zod-validated. */
+function requestIdTime(requestId) {
+    return Number.parseInt(requestId.replaceAll("-", "").slice(0, 12), 16);
+}
+/**
+ * Durable `exec`/`bash` operation outcomes for one Computer. Every retention,
+ * eviction and expiry decision uses the owner's clock; a caller's UUIDv7 time
+ * only selects whether an unseen ID is inside the admission window.
+ */
+export class ComputerOperationRecord {
+    #storage;
+    #now;
+    constructor(storage, now) {
+        this.#storage = storage;
+        this.#now = now;
+        const sql = storage.sql;
+        sql.exec("CREATE TABLE IF NOT EXISTS computer_operations (request_id TEXT PRIMARY KEY, input_hash TEXT NOT NULL, status TEXT NOT NULL CHECK (status IN ('accepted', 'running', 'succeeded', 'failed', 'unknown')), created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL, output_expires_at INTEGER NOT NULL, output_json TEXT) STRICT");
+        // Reopening never reinterprets unfinished work as permission to rerun it.
+        storage.transactionSync(() => {
+            sql.exec("UPDATE computer_operations SET status = 'unknown', updated_at = ? WHERE status IN ('accepted', 'running')", now());
+        });
+    }
+    #admissionTime(requestIdInput) {
+        const requestId = computerRequestIdSchema.parse(requestIdInput);
+        const requestTime = requestIdTime(requestId);
+        const now = this.#now();
+        if (requestTime > now + operationAdmissionWindowMs) {
+            throw new ComputerRequestInvalidError();
+        }
+        return { requestId, requestTime, now };
+    }
+    /**
+     * Atomically return the recorded state of a known ID, or admit a new one as
+     * `accepted`. `undefined` means the caller now owns dispatching it once.
+     */
+    admit(requestIdInput, inputHash, accept) {
+        const { requestId, requestTime, now } = this.#admissionTime(requestIdInput);
+        return this.#storage.transactionSync(() => {
+            accept();
+            this.#sweep(now);
+            const existing = this.#row(requestId);
+            if (existing !== undefined) {
+                if (existing.input_hash !== inputHash)
+                    throw new ComputerOperationConflictError();
+                return this.#result(requestId, existing, now);
+            }
+            if (requestTime < now - operationAdmissionWindowMs) {
+                return this.#result(requestId, undefined, now);
+            }
+            this.#makeRoom(now);
+            this.#storage.sql.exec("INSERT INTO computer_operations (request_id, input_hash, status, created_at, updated_at, output_expires_at, output_json) VALUES (?, ?, 'accepted', ?, ?, ?, NULL)", requestId, inputHash, now, now, now + operationOutputRetentionMs);
+            return undefined;
+        });
+    }
+    /** Record entry into the Workspace command. */
+    markRunning(requestId) {
+        this.#storage.sql.exec("UPDATE computer_operations SET status = 'running', updated_at = ? WHERE request_id = ?", this.#now(), requestId);
+    }
+    /** Record the one terminal command result. */
+    settle(requestId, output) {
+        const finishedAt = this.#now();
+        this.#storage.sql.exec("UPDATE computer_operations SET status = ?, updated_at = ?, output_expires_at = ?, output_json = ? WHERE request_id = ?", output.status === "completed" ? "succeeded" : "failed", finishedAt, finishedAt + operationOutputRetentionMs, JSON.stringify(execOutputSchema.parse(output)), requestId);
+    }
+    /**
+     * The command may have started, but no terminal result is established. The
+     * cause is logged so capacity or start failures stay diagnosable.
+     */
+    settleUnknown(requestId, cause) {
+        console.error("Computer operation outcome unknown", { requestId, cause });
+        this.#storage.sql.exec("UPDATE computer_operations SET status = 'unknown', updated_at = ?, output_json = NULL WHERE request_id = ?", this.#now(), requestId);
+    }
+    /** Durable status lookup; an unseen ID older than the window is expired. */
+    status(requestIdInput, accept) {
+        const { requestId, now } = this.#admissionTime(requestIdInput);
+        return this.#storage.transactionSync(() => {
+            accept();
+            this.#sweep(now);
+            return this.#result(requestId, this.#row(requestId), now);
+        });
+    }
+    #row(requestId) {
+        return this.#storage.sql
+            .exec("SELECT request_id, input_hash, status, created_at, output_expires_at, output_json FROM computer_operations WHERE request_id = ?", requestId)
+            .toArray()[0];
+    }
+    #result(requestId, row, now) {
+        if (row !== undefined) {
+            return computerOperationResultSchema.parse({
+                requestId,
+                status: row.status,
+                output: row.output_json !== null && row.output_expires_at > now
+                    ? execOutputSchema.parse(JSON.parse(row.output_json))
+                    : null,
+            });
+        }
+        return computerOperationResultSchema.parse({
+            requestId,
+            status: requestIdTime(requestId) < now - operationAdmissionWindowMs
+                ? "expired"
+                : "unknown",
+            output: null,
+        });
+    }
+    #sweep(now) {
+        const sql = this.#storage.sql;
+        sql.exec("UPDATE computer_operations SET output_json = NULL WHERE output_json IS NOT NULL AND output_expires_at <= ?", now);
+        // Admission bounds an ID's time to its acceptance time plus the window, so
+        // a record accepted 7 days ago is always outside the admission window.
+        sql.exec("DELETE FROM computer_operations WHERE status IN ('succeeded', 'failed', 'unknown') AND created_at <= ?", now - operationRetentionMs);
+    }
+    /** Evict the oldest terminal record that no in-window retry can address. */
+    #makeRoom(now) {
+        const sql = this.#storage.sql;
+        const count = sql
+            .exec("SELECT COUNT(*) AS count FROM computer_operations")
+            .toArray()[0]?.count;
+        if (count === undefined)
+            throw new ComputerOperationLimitError();
+        if (count < maximumOperationRecords)
+            return;
+        const horizon = now - operationAdmissionWindowMs;
+        const evictable = sql
+            .exec("SELECT request_id FROM computer_operations WHERE status IN ('succeeded', 'failed', 'unknown') AND created_at < ? ORDER BY created_at ASC, request_id ASC", horizon)
+            .toArray()
+            .find(({ request_id }) => requestIdTime(request_id) < horizon);
+        if (evictable === undefined)
+            throw new ComputerOperationLimitError();
+        sql.exec("DELETE FROM computer_operations WHERE request_id = ?", evictable.request_id);
+    }
+}