@fungi.computer/computer-contract 0.0.0-stage → 0.0.2

package/docs/api/README.md

@@ -0,0 +1,2055 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+**@fungi.computer/computer-contract**
+
+---
+
+# @fungi.computer/computer-contract
+
+## Classes
+
+### ComputerPortReservedError
+
+The port belongs to a Computer daemon and cannot be admitted for preview.
+
+#### Extends
+
+- `Error`
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new ComputerPortReservedError(port): ComputerPortReservedError;
+```
+
+###### Parameters
+
+| Parameter | Type     |
+| --------- | -------- |
+| `port`    | `number` |
+
+###### Returns
+
+[`ComputerPortReservedError`](#computerportreservederror)
+
+###### Overrides
+
+```ts
+Error.constructor;
+```
+
+---
+
+### ComputerPortConflictError
+
+A requested port cannot be reserved; no other process identity is disclosed.
+
+#### Extends
+
+- `Error`
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new ComputerPortConflictError(): ComputerPortConflictError;
+```
+
+###### Returns
+
+[`ComputerPortConflictError`](#computerportconflicterror)
+
+###### Overrides
+
+```ts
+Error.constructor;
+```
+
+---
+
+### ComputerPortLimitError
+
+This Computer already admits the maximum number of preview ports.
+
+#### Extends
+
+- `Error`
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new ComputerPortLimitError(): ComputerPortLimitError;
+```
+
+###### Returns
+
+[`ComputerPortLimitError`](#computerportlimiterror)
+
+###### Overrides
+
+```ts
+Error.constructor;
+```
+
+---
+
+### ComputerProcessNotFoundError
+
+No process with this id was started on this Computer.
+
+#### Extends
+
+- `Error`
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new ComputerProcessNotFoundError(id): ComputerProcessNotFoundError;
+```
+
+###### Parameters
+
+| Parameter | Type     |
+| --------- | -------- |
+| `id`      | `string` |
+
+###### Returns
+
+[`ComputerProcessNotFoundError`](#computerprocessnotfounderror)
+
+###### Overrides
+
+```ts
+Error.constructor;
+```
+
+---
+
+### ComputerProcessLimitError
+
+Every process slot is occupied by a running process.
+
+#### Extends
+
+- `Error`
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new ComputerProcessLimitError(): ComputerProcessLimitError;
+```
+
+###### Returns
+
+[`ComputerProcessLimitError`](#computerprocesslimiterror)
+
+###### Overrides
+
+```ts
+Error.constructor;
+```
+
+---
+
+### ComputerFileConflict
+
+The expected file contents no longer match at atomic replacement.
+
+#### Extends
+
+- `Error`
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new ComputerFileConflict(): ComputerFileConflict;
+```
+
+###### Returns
+
+[`ComputerFileConflict`](#computerfileconflict)
+
+###### Overrides
+
+```ts
+Error.constructor;
+```
+
+---
+
+### ComputerFileRangeError
+
+A byte window starts beyond the current file extent.
+
+#### Extends
+
+- `Error`
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new ComputerFileRangeError(size): ComputerFileRangeError;
+```
+
+###### Parameters
+
+| Parameter | Type     | Description                       |
+| --------- | -------- | --------------------------------- |
+| `size`    | `number` | The file's current size in bytes. |
+
+###### Returns
+
+[`ComputerFileRangeError`](#computerfilerangeerror)
+
+###### Overrides
+
+```ts
+Error.constructor;
+```
+
+#### Properties
+
+##### size
+
+```ts
+readonly size: number;
+```
+
+The file's current size in bytes.
+
+---
+
+### ComputerFileTooLargeError
+
+The requested file bytes exceed the admitted read bound.
+
+#### Extends
+
+- `Error`
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new ComputerFileTooLargeError(): ComputerFileTooLargeError;
+```
+
+###### Returns
+
+[`ComputerFileTooLargeError`](#computerfiletoolargeerror)
+
+###### Overrides
+
+```ts
+Error.constructor;
+```
+
+## Type Aliases
+
+### ComputerExecutionBudget
+
+```ts
+type ComputerExecutionBudget = Readonly<{
+  maximumTimeMs: number;
+}>;
+```
+
+Host-owned policy, never supplied in a Computer request body.
+
+---
+
+### ComputerValue
+
+```ts
+type ComputerValue = z.output<typeof computerValueSchema>;
+```
+
+A JSON value accepted by `computerValueSchema`.
+
+---
+
+### ComputerFileReadInput
+
+```ts
+type ComputerFileReadInput = z.output<typeof readInputSchema>;
+```
+
+A request to read one whole file as text.
+
+---
+
+### ComputerFileReadOutput
+
+```ts
+type ComputerFileReadOutput = z.output<typeof readOutputSchema>;
+```
+
+The reply to reading one whole file as text.
+
+---
+
+### ComputerFileByteReadInput
+
+```ts
+type ComputerFileByteReadInput = z.output<typeof readBytesInputSchema>;
+```
+
+A request to read a window of bytes from one file.
+
+---
+
+### ComputerFileListInput
+
+```ts
+type ComputerFileListInput = z.output<typeof listInputSchema>;
+```
+
+A request for one page of a directory's entries.
+
+---
+
+### ComputerFileListOutput
+
+```ts
+type ComputerFileListOutput = z.output<typeof listOutputSchema>;
+```
+
+The reply to a directory listing.
+
+---
+
+### ComputerFileWriteInput
+
+```ts
+type ComputerFileWriteInput = z.output<typeof writeInputSchema>;
+```
+
+A request to write one file.
+
+---
+
+### ComputerFileWriteOutput
+
+```ts
+type ComputerFileWriteOutput = z.output<typeof writeOutputSchema>;
+```
+
+The reply to a committed file write.
+
+---
+
+### ComputerFileGlobInput
+
+```ts
+type ComputerFileGlobInput = z.output<typeof globInputSchema>;
+```
+
+A request to find paths that match a glob.
+
+---
+
+### ComputerFileGrepInput
+
+```ts
+type ComputerFileGrepInput = z.output<typeof grepInputSchema>;
+```
+
+A request to search file contents.
+
+---
+
+### ComputerRequestId
+
+```ts
+type ComputerRequestId = z.output<typeof computerRequestIdSchema>;
+```
+
+A request id that passed `computerRequestIdSchema`.
+
+---
+
+### ComputerExecTruncation
+
+```ts
+type ComputerExecTruncation = z.output<typeof execTruncationSchema>;
+```
+
+A record that one command stream was cut.
+
+---
+
+### ComputerProcessId
+
+```ts
+type ComputerProcessId = z.output<typeof computerProcessIdSchema>;
+```
+
+A process id that passed `computerProcessIdSchema`.
+
+---
+
+### ComputerProcessSync
+
+```ts
+type ComputerProcessSync = z.output<typeof computerProcessSyncSchema>;
+```
+
+A value of `computerProcessSyncSchema`.
+
+---
+
+### ComputerProcess
+
+```ts
+type ComputerProcess = z.output<typeof computerProcessSchema>;
+```
+
+One started process, as the Computer reports it.
+
+---
+
+### ComputerExecInput
+
+```ts
+type ComputerExecInput = z.output<typeof execInputSchema>;
+```
+
+The model's command input.
+
+---
+
+### ComputerExecRequest
+
+```ts
+type ComputerExecRequest = z.output<typeof execRequestSchema>;
+```
+
+The host's command request: the model's input plus the host's request id.
+
+---
+
+### ComputerExecOutput
+
+```ts
+type ComputerExecOutput = z.output<typeof execOutputSchema>;
+```
+
+What a finished command left behind.
+
+---
+
+### ComputerExecutionCarriage
+
+```ts
+type ComputerExecutionCarriage = Readonly<{
+  env?: Readonly<Record<string, string>>;
+  stdin?: string | Uint8Array;
+}>;
+```
+
+Host-memory-only native inputs. Never part of a tool, replay row or log.
+
+---
+
+### ComputerExecutionInvocation
+
+```ts
+type ComputerExecutionInvocation = Readonly<{
+  id: string;
+  kind: "exec" | "process";
+}>;
+```
+
+Non-secret identity of the actual native invocation, not its credential.
+
+---
+
+### ComputerExecutionCloseReason
+
+```ts
+type ComputerExecutionCloseReason =
+  "refused_start" | "native_exit" | "unknown" | "reconstructed";
+```
+
+Authority closure is distinct from asserting a native exit code.
+
+---
+
+### ComputerExecutionHostHooks
+
+```ts
+type ComputerExecutionHostHooks = Readonly<{
+  open: Promise<
+    Readonly<{
+      env?: Readonly<Record<string, string>>;
+      stdin?: string | Uint8Array;
+    }>
+  >;
+  renew: Promise<void>;
+  close: Promise<void>;
+}>;
+```
+
+The resource host owns cargo meaning and issuance. Computer owns NEW/replay,
+dispatch and actual native liveness. Only non-secret context is durable; hooks
+and carriage stay in host memory.
+
+---
+
+### ComputerExecutionHostPort
+
+```ts
+type ComputerExecutionHostPort = Readonly<{
+  executionHooks:
+    | Readonly<{
+        open: Promise<
+          Readonly<{
+            env?: Readonly<Record<string, string>>;
+            stdin?: string | Uint8Array;
+          }>
+        >;
+        renew: Promise<void>;
+        close: Promise<void>;
+      }>
+    | undefined;
+  executionIsLive: Promise<boolean>;
+  executeOperationAfterAcceptance: Promise<{
+    requestId: string;
+    status:
+      "unknown" | "failed" | "running" | "accepted" | "succeeded" | "expired";
+    output: {
+      status: "completed" | "failed" | "cancelled";
+      exitCode: number;
+      stdout: string;
+      stderr: string;
+      truncated: false | object[];
+    } | null;
+  }>;
+  startProcessAfterAcceptance: Promise<{
+    id: string & object;
+    port: number | null;
+    command: string;
+    cwd: string | null;
+    state: "running" | "exited" | "uncertain";
+    exitCode: number | null;
+    sync: "unknown" | "synced" | "pending";
+    startedAt: number;
+    endedAt: number | null;
+  }>;
+  callAfterAcceptance: Promise<JSONType>;
+}>;
+```
+
+Protected host seam only. Public command/process parsers do not accept cargo.
+
+---
+
+### ComputerOperationResult
+
+```ts
+type ComputerOperationResult = z.output<typeof computerOperationResultSchema>;
+```
+
+The durable status of one command invocation, for the host that owns its request
+id.
+
+---
+
+### ComputerToolResult
+
+```ts
+type ComputerToolResult = z.output<typeof computerToolResultSchema>;
+```
+
+The status of one command invocation without the host's request id.
+
+---
+
+### ComputerOperation
+
+```ts
+type ComputerOperation = z.output<typeof computerOperationSchema>;
+```
+
+One public operation name.
+
+---
+
+### ComputerFileReplacement
+
+```ts
+type ComputerFileReplacement = z.output<typeof replaceInputSchema>;
+```
+
+A request to replace a file's contents if they still match.
+
+---
+
+### ComputerFileReplacementResult
+
+```ts
+type ComputerFileReplacementResult = z.output<typeof replaceOutputSchema>;
+```
+
+The reply to a committed replacement.
+
+## Variables
+
+### attachedBackendIdSchema
+
+```ts
+const attachedBackendIdSchema: ZodLazy<ZodString>;
+```
+
+The stable Workspace id of one attached execution backend: `container`, `vm-`
+followed by a lowercase letter-or-digit name that may contain hyphens, or
+`local-` followed by 16 lowercase base32 characters. A command request names one
+to run there; omitted, the Computer routes by its default order.
+
+---
+
+### maximumFileBytes
+
+```ts
+const maximumFileBytes: number;
+```
+
+Most bytes of file content one Computer read or write carries, counted as UTF-8.
+
+---
+
+### maximumListEntries
+
+```ts
+const maximumListEntries: 256 = 256;
+```
+
+Most entries one list, glob or grep reply returns in a single page.
+
+---
+
+### maximumPatternCharacters
+
+```ts
+const maximumPatternCharacters: 512 = 512;
+```
+
+Longest glob or search pattern a request may send.
+
+---
+
+### maximumCommandCharacters
+
+```ts
+const maximumCommandCharacters: number;
+```
+
+Longest command string a request may send.
+
+---
+
+### maximumStreamBytes
+
+```ts
+const maximumStreamBytes: number;
+```
+
+Most bytes of stdout or stderr kept from one command. A longer stream is cut and
+marked.
+
+---
+
+### truncationMarkerReserveBytes
+
+```ts
+const truncationMarkerReserveBytes: 256 = 256;
+```
+
+Room inside the stream cap for the visible truncation marker.
+
+---
+
+### maximumExecutionTimeMs
+
+```ts
+const maximumExecutionTimeMs: 120000 = 120_000;
+```
+
+The bound for ordinary Computer commands; hosts own any admitted job budget.
+
+---
+
+### genericComputerExecutionBudget
+
+```ts
+const genericComputerExecutionBudget: ComputerExecutionBudget;
+```
+
+The budget for ordinary Computer commands. Hosts that admit a job principal
+choose their own.
+
+---
+
+### computerValueSchema
+
+```ts
+const computerValueSchema: ZodJSONSchema;
+```
+
+Accepts any JSON value. Capability descriptions and other transport data are
+checked against it.
+
+---
+
+### capabilityNameSchema
+
+```ts
+const capabilityNameSchema: ZodLazy<ZodString>;
+```
+
+Accepts the name of one Computer operation: a letter, then letters, digits or
+underscores.
+
+---
+
+### computerPortSchema
+
+```ts
+const computerPortSchema: ZodLazy<ZodNumber>;
+```
+
+One valid TCP port number, used only with this Computer's container.
+
+---
+
+### maximumExposedPorts
+
+```ts
+const maximumExposedPorts: 64 = 64;
+```
+
+Most preview ports one Computer admits at once.
+
+---
+
+### computerDaemonPort
+
+```ts
+const computerDaemonPort: 8080 = 8080;
+```
+
+computerd's Workspace RPC port, pinned by the Cloudflare container backend.
+
+---
+
+### computerTerminalPort
+
+```ts
+const computerTerminalPort: 7681 = 7681;
+```
+
+The Computer-owned terminal server inside the container image.
+
+---
+
+### computerReservedPorts
+
+```ts
+const computerReservedPorts: ReadonlySet<number>;
+```
+
+Ports served by the Computer's own in-container daemons. An admitted preview
+must never reach a control plane.
+
+---
+
+### computerPortInputSchema
+
+```ts
+const computerPortInputSchema: ZodObject<
+  {
+    port: ZodLazy<ZodNumber>;
+  },
+  $strict
+>;
+```
+
+Names one container port to expose or remove.
+
+---
+
+### computerPortOutputSchema
+
+```ts
+const computerPortOutputSchema: ZodLazy<
+  ZodObject<
+    {
+      port: ZodLazy<ZodNumber>;
+      exposed: ZodBoolean;
+    },
+    $strict
+  >
+>;
+```
+
+Reply to a request to expose a port.
+
+---
+
+### computerPortRemovalOutputSchema
+
+```ts
+const computerPortRemovalOutputSchema: ZodLazy<
+  ZodObject<
+    {
+      port: ZodLazy<ZodNumber>;
+      removed: ZodBoolean;
+    },
+    $strict
+  >
+>;
+```
+
+Reply to a request to stop exposing a port.
+
+---
+
+### computerPortsOutputSchema
+
+```ts
+const computerPortsOutputSchema: ZodLazy<
+  ZodObject<
+    {
+      ports: ZodArray<ZodLazy<ZodNumber>>;
+    },
+    $strict
+  >
+>;
+```
+
+The ports this Computer currently admits for preview.
+
+---
+
+### computerCapabilitiesSchema
+
+```ts
+const computerCapabilitiesSchema: ZodLazy<
+  ZodArray<
+    ZodObject<
+      {
+        id: ZodLazy<ZodString>;
+        name: ZodLazy<ZodString>;
+        kind: ZodString;
+        description: ZodString;
+        parameters: ZodLazy<ZodRecord<ZodString, ZodUnknown>>;
+        output: ZodLazy<ZodRecord<ZodString, ZodUnknown>>;
+      },
+      $strict
+    >
+  >
+>;
+```
+
+Native operation descriptions shared by discovery and its OpenAPI document.
+
+---
+
+### pathSchema
+
+```ts
+const pathSchema: ZodString;
+```
+
+Accepts an absolute path inside the Computer: it starts with a slash and holds
+no null byte.
+
+---
+
+### readInputSchema
+
+```ts
+const readInputSchema: ZodObject<
+  {
+    path: ZodString;
+  },
+  $strict
+>;
+```
+
+Complete bounded UTF-8 text reads. Binary reads use the same path input.
+
+---
+
+### readOutputSchema
+
+```ts
+const readOutputSchema: ZodLazy<
+  ZodObject<
+    {
+      path: ZodString;
+      content: ZodString;
+    },
+    $strict
+  >
+>;
+```
+
+The whole contents of one file, as text.
+
+---
+
+### readBytesInputSchema
+
+```ts
+const readBytesInputSchema: ZodObject<
+  {
+    path: ZodString;
+    byteOffset: ZodOptional<ZodNumber>;
+    byteLength: ZodOptional<ZodNumber>;
+  },
+  $strict
+>;
+```
+
+Optional byte window; text reads remain complete and independently bounded.
+
+---
+
+### computerByteReadReplySchema
+
+```ts
+const computerByteReadReplySchema: ZodLazy<
+  ZodObject<
+    {
+      path: ZodString;
+      byteOffset: ZodNumber;
+      content: ZodString;
+      encoding: ZodLiteral<"base64">;
+      truncated: ZodBoolean;
+    },
+    $strict
+  >
+>;
+```
+
+Finite byte-read reply used by admitted App frame bindings.
+
+---
+
+### appMethodPreviewResultSchema
+
+```ts
+const appMethodPreviewResultSchema: ZodLazy<
+  ZodObject<
+    {
+      previewUrl: ZodURL;
+      expiresAt: ZodNumber;
+    },
+    $strict
+  >
+>;
+```
+
+Host-admitted App method preview; parsing does not grant port access.
+
+---
+
+### listLimitSchema
+
+```ts
+const listLimitSchema: ZodDefault<ZodNumber>;
+```
+
+Accepts how many entries a list returns: 1 up to `maximumListEntries`, 100 when
+omitted.
+
+---
+
+### listOffsetSchema
+
+```ts
+const listOffsetSchema: ZodDefault<ZodNumber>;
+```
+
+Accepts how many entries a list skips. Zero when omitted.
+
+---
+
+### listInputSchema
+
+```ts
+const listInputSchema: ZodObject<
+  {
+    path: ZodDefault<ZodString>;
+    limit: ZodDefault<ZodNumber>;
+    offset: ZodDefault<ZodNumber>;
+  },
+  $strict
+>;
+```
+
+A request for one page of a directory's entries.
+
+---
+
+### listOutputSchema
+
+```ts
+const listOutputSchema: ZodLazy<
+  ZodObject<
+    {
+      path: ZodString;
+      entries: ZodArray<
+        ZodLazy<
+          ZodObject<
+            {
+              name: ZodString;
+              size: ZodNumber;
+              modifiedAt: ZodNumber;
+              type: ZodEnum<{
+                file: "file";
+                directory: "directory";
+                symlink: "symlink";
+              }>;
+            },
+            $strict
+          >
+        >
+      >;
+      nextOffset: ZodNullable<ZodNumber>;
+    },
+    $strict
+  >
+>;
+```
+
+One page of a directory's entries.
+
+---
+
+### fileContentSchema
+
+```ts
+const fileContentSchema: ZodLazy<ZodString>;
+```
+
+Accepts text to store in a file, within `maximumFileBytes`.
+
+---
+
+### writeInputSchema
+
+```ts
+const writeInputSchema: ZodObject<
+  {
+    path: ZodString;
+    content: ZodLazy<ZodString>;
+  },
+  $strict
+>;
+```
+
+A request to write one file, creating or replacing its contents.
+
+---
+
+### writeOutputSchema
+
+```ts
+const writeOutputSchema: ZodLazy<
+  ZodObject<
+    {
+      path: ZodString;
+      bytes: ZodNumber;
+    },
+    $strict
+  >
+>;
+```
+
+The reply to a committed file write.
+
+---
+
+### writeBytesInputSchema
+
+```ts
+const writeBytesInputSchema: ZodObject<
+  {
+    path: ZodString;
+  },
+  $strict
+> = readInputSchema;
+```
+
+Names the file for a binary write. The bytes travel as the request body.
+
+---
+
+### replaceInputSchema
+
+```ts
+const replaceInputSchema: ZodObject<
+  {
+    path: ZodString;
+    expectedContent: ZodLazy<ZodString>;
+    content: ZodLazy<ZodString>;
+  },
+  $strict
+>;
+```
+
+A request to replace a file's contents only if they still equal what the caller
+last saw.
+
+---
+
+### replaceOutputSchema
+
+```ts
+const replaceOutputSchema: ZodLazy<
+  ZodObject<
+    {
+      path: ZodString;
+      bytes: ZodNumber;
+    },
+    $strict
+  >
+> = writeOutputSchema;
+```
+
+The reply to a committed replacement. It has the shape of a write reply.
+
+---
+
+### globInputSchema
+
+```ts
+const globInputSchema: ZodLazy<
+  ZodObject<
+    {
+      path: ZodString;
+      pattern: ZodString;
+      limit: ZodDefault<ZodNumber>;
+    },
+    $strict
+  >
+>;
+```
+
+A request to find paths under a directory that match a glob.
+
+---
+
+### globOutputSchema
+
+```ts
+const globOutputSchema: ZodLazy<
+  ZodObject<
+    {
+      path: ZodString;
+      matches: ZodArray<ZodString>;
+      truncated: ZodBoolean;
+    },
+    $strict
+  >
+>;
+```
+
+The paths a glob found.
+
+---
+
+### grepInputSchema
+
+```ts
+const grepInputSchema: ZodLazy<
+  ZodObject<
+    {
+      path: ZodString;
+      pattern: ZodString;
+      regex: ZodDefault<ZodBoolean>;
+      ignoreCase: ZodDefault<ZodBoolean>;
+      include: ZodOptional<ZodString>;
+      limit: ZodDefault<ZodNumber>;
+    },
+    $strict
+  >
+>;
+```
+
+A request to search file contents under a directory.
+
+---
+
+### grepOutputSchema
+
+```ts
+const grepOutputSchema: ZodLazy<
+  ZodObject<
+    {
+      path: ZodString;
+      matches: ZodArray<
+        ZodObject<
+          {
+            path: ZodString;
+            line: ZodNumber;
+            text: ZodString;
+          },
+          $strict
+        >
+      >;
+      truncated: ZodBoolean;
+    },
+    $strict
+  >
+>;
+```
+
+The lines a search found.
+
+---
+
+### editInputSchema
+
+```ts
+const editInputSchema: ZodLazy<
+  ZodObject<
+    {
+      path: ZodString;
+      oldText: ZodString;
+      newText: ZodString;
+    },
+    $strict
+  >
+>;
+```
+
+A request to replace one piece of text in a file.
+
+---
+
+### editOutputSchema
+
+```ts
+const editOutputSchema: ZodLazy<
+  ZodObject<
+    {
+      path: ZodString;
+      bytes: ZodNumber;
+      diff: ZodString;
+      firstChangedLine: ZodNullable<ZodNumber>;
+    },
+    $strict
+  >
+>;
+```
+
+The reply to a committed edit.
+
+---
+
+### mkdirInputSchema
+
+```ts
+const mkdirInputSchema: ZodLazy<
+  ZodObject<
+    {
+      path: ZodString;
+      recursive: ZodDefault<ZodBoolean>;
+    },
+    $strict
+  >
+>;
+```
+
+A request to create a directory.
+
+---
+
+### mkdirOutputSchema
+
+```ts
+const mkdirOutputSchema: ZodObject<
+  {
+    path: ZodString;
+  },
+  $strict
+>;
+```
+
+The reply to a directory creation.
+
+---
+
+### computerRequestIdSchema
+
+```ts
+const computerRequestIdSchema: ZodUUID;
+```
+
+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.
+
+---
+
+### execInputSchema
+
+```ts
+const execInputSchema: ZodObject<
+  {
+    command: ZodString;
+    cwd: ZodOptional<ZodString>;
+    backend: ZodOptional<ZodLazy<ZodString>>;
+    timeoutMs: ZodDefault<ZodNumber>;
+  },
+  $strict
+>;
+```
+
+The model's command input: command, directory, backend and timeout. It carries
+no request id.
+
+---
+
+### execRequestSchema
+
+```ts
+const execRequestSchema: ZodObject<
+  {
+    command: ZodString;
+    cwd: ZodOptional<ZodString>;
+    backend: ZodOptional<ZodLazy<ZodString>>;
+    timeoutMs: ZodDefault<ZodNumber>;
+    requestId: ZodUUID;
+  },
+  $strict
+>;
+```
+
+Host-to-Computer command request: the model input plus the host's ID.
+
+---
+
+### execTruncationSchema
+
+```ts
+const execTruncationSchema: ZodObject<
+  {
+    stream: ZodEnum<{
+      stdout: "stdout";
+      stderr: "stderr";
+    }>;
+    keptBytes: ZodNumber;
+    totalBytes: ZodNumber;
+  },
+  $strict
+>;
+```
+
+One command stream cut at `maximumStreamBytes`; absent streams were whole.
+
+---
+
+### execTruncationMarkerPattern
+
+```ts
+const execTruncationMarkerPattern: RegExp;
+```
+
+Matches the marker line `execTruncationMarker` appends at the end of a stream.
+
+---
+
+### execOutputSchema
+
+```ts
+const execOutputSchema: ZodObject<
+  {
+    status: ZodEnum<{
+      completed: "completed";
+      failed: "failed";
+      cancelled: "cancelled";
+    }>;
+    exitCode: ZodNumber;
+    stdout: ZodString;
+    stderr: ZodString;
+    truncated: ZodUnion<
+      readonly [
+        ZodLiteral<false>,
+        ZodArray<
+          ZodObject<
+            {
+              stream: ZodEnum<{
+                stdout: "stdout";
+                stderr: "stderr";
+              }>;
+              keptBytes: ZodNumber;
+              totalBytes: ZodNumber;
+            },
+            $strict
+          >
+        >,
+      ]
+    >;
+  },
+  $strict
+>;
+```
+
+What a finished command left behind.
+
+---
+
+### computerProcessIdSchema
+
+```ts
+const computerProcessIdSchema: ZodLazy<
+  ZodString &
+    ZodType<
+      CairnId<"computer-process", "process", 1>,
+      string,
+      $ZodTypeInternals<CairnId<"computer-process", "process", 1>, string>
+    >
+>;
+```
+
+Accepts the durable id of one started process.
+
+---
+
+### maximumRunningProcesses
+
+```ts
+const maximumRunningProcesses: 16 = 16;
+```
+
+At most this many processes may be running in one host scope at once.
+
+---
+
+### maximumProcessRecords
+
+```ts
+const maximumProcessRecords: 64 = 64;
+```
+
+At most this many process records, running or exited, are kept per host scope.
+
+---
+
+### processStartInputSchema
+
+```ts
+const processStartInputSchema: ZodObject<
+  {
+    requestId: ZodString;
+    requestScope: ZodString;
+    port: ZodOptional<ZodLazy<ZodNumber>>;
+    command: ZodString;
+    cwd: ZodOptional<ZodString>;
+  },
+  $strict
+>;
+```
+
+The host's request to start one long-running process.
+
+---
+
+### processStartToolInputSchema
+
+```ts
+const processStartToolInputSchema: ZodObject<
+  {
+    port: ZodOptional<ZodLazy<ZodNumber>>;
+    command: ZodString;
+    cwd: ZodOptional<ZodString>;
+  },
+  $strict
+>;
+```
+
+Model input excludes the host's replay identity and authority scope.
+
+---
+
+### processIdInputSchema
+
+```ts
+const processIdInputSchema: ZodObject<
+  {
+    id: ZodLazy<
+      ZodString &
+        ZodType<
+          CairnId<"computer-process", "process", 1>,
+          string,
+          $ZodTypeInternals<CairnId<"computer-process", "process", 1>, string>
+        >
+    >;
+  },
+  $strict
+>;
+```
+
+Names one started process.
+
+---
+
+### computerProcessStateSchema
+
+```ts
+const computerProcessStateSchema: ZodEnum<{
+  running: "running";
+  exited: "exited";
+  uncertain: "uncertain";
+}>;
+```
+
+`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.
+
+---
+
+### computerProcessSyncSchema
+
+```ts
+const computerProcessSyncSchema: ZodEnum<{
+  synced: "synced";
+  pending: "pending";
+  unknown: "unknown";
+}>;
+```
+
+`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`.
+
+---
+
+### computerProcessSchema
+
+```ts
+const computerProcessSchema: ZodObject<
+  {
+    id: ZodLazy<
+      ZodString &
+        ZodType<
+          CairnId<"computer-process", "process", 1>,
+          string,
+          $ZodTypeInternals<CairnId<"computer-process", "process", 1>, string>
+        >
+    >;
+    port: ZodNullable<ZodLazy<ZodNumber>>;
+    command: ZodString;
+    cwd: ZodNullable<ZodString>;
+    state: ZodEnum<{
+      running: "running";
+      exited: "exited";
+      uncertain: "uncertain";
+    }>;
+    exitCode: ZodNullable<ZodNumber>;
+    sync: ZodEnum<{
+      synced: "synced";
+      pending: "pending";
+      unknown: "unknown";
+    }>;
+    startedAt: ZodNumber;
+    endedAt: ZodNullable<ZodNumber>;
+  },
+  $strict
+>;
+```
+
+One started process, as the Computer reports it.
+
+---
+
+### processListOutputSchema
+
+```ts
+const processListOutputSchema: ZodObject<
+  {
+    processes: ZodArray<
+      ZodObject<
+        {
+          id: ZodLazy<
+            ZodString &
+              ZodType<
+                CairnId<"computer-process", "process", 1>,
+                string,
+                $ZodTypeInternals<
+                  CairnId<"computer-process", "process", 1>,
+                  string
+                >
+              >
+          >;
+          port: ZodNullable<ZodLazy<ZodNumber>>;
+          command: ZodString;
+          cwd: ZodNullable<ZodString>;
+          state: ZodEnum<{
+            running: "running";
+            exited: "exited";
+            uncertain: "uncertain";
+          }>;
+          exitCode: ZodNullable<ZodNumber>;
+          sync: ZodEnum<{
+            synced: "synced";
+            pending: "pending";
+            unknown: "unknown";
+          }>;
+          startedAt: ZodNumber;
+          endedAt: ZodNullable<ZodNumber>;
+        },
+        $strict
+      >
+    >;
+  },
+  $strict
+>;
+```
+
+The processes started on this Computer.
+
+---
+
+### processKillOutputSchema
+
+```ts
+const processKillOutputSchema: ZodLazy<
+  ZodObject<
+    {
+      process: ZodObject<
+        {
+          id: ZodLazy<
+            ZodString &
+              ZodType<
+                CairnId<"computer-process", "process", 1>,
+                string,
+                $ZodTypeInternals<
+                  CairnId<"computer-process", "process", 1>,
+                  string
+                >
+              >
+          >;
+          port: ZodNullable<ZodLazy<ZodNumber>>;
+          command: ZodString;
+          cwd: ZodNullable<ZodString>;
+          state: ZodEnum<{
+            running: "running";
+            exited: "exited";
+            uncertain: "uncertain";
+          }>;
+          exitCode: ZodNullable<ZodNumber>;
+          sync: ZodEnum<{
+            synced: "synced";
+            pending: "pending";
+            unknown: "unknown";
+          }>;
+          startedAt: ZodNumber;
+          endedAt: ZodNullable<ZodNumber>;
+        },
+        $strict
+      >;
+      signalled: ZodBoolean;
+    },
+    $strict
+  >
+>;
+```
+
+The reply to a request to stop a process.
+
+---
+
+### computerOperationStatusSchema
+
+```ts
+const computerOperationStatusSchema: ZodEnum<{
+  accepted: "accepted";
+  running: "running";
+  succeeded: "succeeded";
+  failed: "failed";
+  unknown: "unknown";
+  expired: "expired";
+}>;
+```
+
+Where one command invocation stands: accepted, running, succeeded, failed,
+unknown (the outcome cannot be established, because the Computer restarted
+mid-command or the id has no record yet is still inside the admission window) or
+expired (no record, and older than the admission window).
+
+---
+
+### computerOperationResultSchema
+
+```ts
+const computerOperationResultSchema: ZodObject<{
+  requestId: ZodUUID;
+  status: ZodEnum<{
+     accepted: "accepted";
+     running: "running";
+     succeeded: "succeeded";
+     failed: "failed";
+     unknown: "unknown";
+     expired: "expired";
+  }>;
+  output: ZodNullable<ZodObject<{
+     status: ZodEnum<{
+        completed: "completed";
+        failed: "failed";
+        cancelled: "cancelled";
+     }>;
+     exitCode: ZodNumber;
+     stdout: ZodString;
+     stderr: ZodString;
+     truncated: ZodUnion<readonly [ZodLiteral<false>, ZodArray<ZodObject<{
+        stream: ZodEnum<...>;
+        keptBytes: ZodNumber;
+        totalBytes: ZodNumber;
+     }, $strict>>]>;
+  }, $strict>>;
+}, $strict>;
+```
+
+Durable operation status returned to the host that owns the request ID.
+
+---
+
+### computerToolResultSchema
+
+```ts
+const computerToolResultSchema: ZodObject<{
+  status: ZodEnum<{
+     accepted: "accepted";
+     running: "running";
+     succeeded: "succeeded";
+     failed: "failed";
+     unknown: "unknown";
+     expired: "expired";
+  }>;
+  output: ZodNullable<ZodObject<{
+     status: ZodEnum<{
+        completed: "completed";
+        failed: "failed";
+        cancelled: "cancelled";
+     }>;
+     exitCode: ZodNumber;
+     stdout: ZodString;
+     stderr: ZodString;
+     truncated: ZodUnion<readonly [ZodLiteral<false>, ZodArray<ZodObject<{
+        stream: ZodEnum<...>;
+        keptBytes: ZodNumber;
+        totalBytes: ZodNumber;
+     }, $strict>>]>;
+  }, $strict>>;
+}, $strict>;
+```
+
+Model-facing command result: the durable status without the host's ID.
+
+---
+
+### computerOperationSchema
+
+```ts
+const computerOperationSchema: ZodEnum<{
+  files.read: "files.read";
+  files.readBytes: "files.readBytes";
+  files.write: "files.write";
+  files.writeBytes: "files.writeBytes";
+  files.list: "files.list";
+  files.glob: "files.glob";
+  files.grep: "files.grep";
+  files.edit: "files.edit";
+  files.patch: "files.patch";
+  mkdir: "mkdir";
+  bash: "bash";
+  exec: "exec";
+}>;
+```
+
+Public operation vocabulary; transport adapters map these to routes.
+
+---
+
+### patchInputSchema
+
+```ts
+const patchInputSchema: z.ZodLazy<
+  z.ZodObject<
+    {
+      patch: z.ZodString;
+    },
+    z.core.$strict
+  >
+>;
+```
+
+Browser-safe patch contracts shared by native Files tools and Computer HTTP.
+
+---
+
+### patchOutputSchema
+
+```ts
+const patchOutputSchema: z.ZodLazy<z.ZodUnion<readonly [z.ZodObject<{
+  status: z.ZodEnum<{
+     completed: "completed";
+     failed: "failed";
+     cancelled: "cancelled";
+  }>;
+  exitCode: z.ZodNumber;
+  stdout: z.ZodString;
+  stderr: z.ZodString;
+  truncated: z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodArray<z.ZodObject<..., ...>>]>;
+}, z.core.$strict>, z.ZodObject<{
+  status: z.ZodEnum<{
+     completed: "completed";
+     failed: "failed";
+     cancelled: "cancelled";
+  }>;
+  exitCode: z.ZodNumber;
+  stdout: z.ZodString;
+  stderr: z.ZodString;
+  truncated: z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodArray<z.ZodObject<..., ...>>]>;
+  error: z.ZodObject<{
+     kind: z.ZodLiteral<"mismatch">;
+  }, z.core.$strict>;
+}, z.core.$strict>]>>;
+```
+
+Native patch completion, cancellation or failure, including an optional
+mismatch.
+
+## Functions
+
+### isComputerReservedPort()
+
+```ts
+function isComputerReservedPort(port): boolean;
+```
+
+Whether a Computer daemon owns this port, so it can never be admitted for
+preview.
+
+#### Parameters
+
+| Parameter | Type     |
+| --------- | -------- |
+| `port`    | `number` |
+
+#### Returns
+
+`boolean`
+
+---
+
+### boundedTextSchema()
+
+```ts
+function boundedTextSchema(minimumLength?): ZodString;
+```
+
+Builds a schema for text of at least the given length whose UTF-8 size stays
+within `maximumFileBytes`.
+
+#### Parameters
+
+| Parameter       | Type     | Default value |
+| --------------- | -------- | ------------- |
+| `minimumLength` | `number` | `0`           |
+
+#### Returns
+
+`ZodString`
+
+---
+
+### mintComputerRequestId()
+
+```ts
+function mintComputerRequestId(): string;
+```
+
+Mint the request ID for one host tool invocation.
+
+#### Returns
+
+`string`
+
+---
+
+### computerExecutionRequestSchema()
+
+```ts
+function computerExecutionRequestSchema(budget): ZodObject<
+  {
+    command: ZodString;
+    cwd: ZodOptional<ZodString>;
+    backend: ZodOptional<ZodLazy<ZodString>>;
+    timeoutMs: ZodDefault<ZodNumber>;
+    requestId: ZodUUID;
+  },
+  $strict
+>;
+```
+
+Resource hosts select a budget only after admitting their job principal.
+
+#### Parameters
+
+| Parameter | Type                                                  |
+| --------- | ----------------------------------------------------- |
+| `budget`  | [`ComputerExecutionBudget`](#computerexecutionbudget) |
+
+#### Returns
+
+`ZodObject`\<\{ `command`: `ZodString`; `cwd`: `ZodOptional`\<`ZodString`\>;
+`backend`: `ZodOptional`\<`ZodLazy`\<`ZodString`\>\>; `timeoutMs`:
+`ZodDefault`\<`ZodNumber`\>; `requestId`: `ZodUUID`; \}, `$strict`\>
+
+---
+
+### execTruncationMarker()
+
+```ts
+function execTruncationMarker(entry): string;
+```
+
+The visible line appended to a cut stream; sizes exclude the line itself.
+
+#### Parameters
+
+| Parameter          | Type                                                                                     | Description                              |
+| ------------------ | ---------------------------------------------------------------------------------------- | ---------------------------------------- |
+| `entry`            | \{ `stream`: `"stdout"` \| `"stderr"`; `keptBytes`: `number`; `totalBytes`: `number`; \} | -                                        |
+| `entry.stream`     | `"stdout"` \| `"stderr"`                                                                 | Which stream was cut.                    |
+| `entry.keptBytes`  | `number`                                                                                 | Bytes of the stream that were kept.      |
+| `entry.totalBytes` | `number`                                                                                 | Bytes the stream held before it was cut. |
+
+#### Returns
+
+`string`
+
+---
+
+### utf8Prefix()
+
+```ts
+function utf8Prefix(bytes, limit): Uint8Array<ArrayBuffer>;
+```
+
+Longest prefix of `bytes` within `limit` that ends on a UTF-8 character
+boundary.
+
+#### Parameters
+
+| Parameter | Type         |
+| --------- | ------------ |
+| `bytes`   | `Uint8Array` |
+| `limit`   | `number`     |
+
+#### Returns
+
+`Uint8Array`\<`ArrayBuffer`\>
+
+---
+
+### mintComputerProcessId()
+
+```ts
+function mintComputerProcessId(): string & object;
+```
+
+Mint the durable identity of one started process.
+
+#### Returns
+
+---
+
+### installationProcessScope()
+
+```ts
+function installationProcessScope(installation, method, actor): string;
+```
+
+A trusted App host binds replay identity to its admitted installation and
+caller.
+
+#### Parameters
+
+| Parameter      | Type                                                                                 |
+| -------------- | ------------------------------------------------------------------------------------ |
+| `installation` | `string`                                                                             |
+| `method`       | `string`                                                                             |
+| `actor`        | `Readonly`\<\{ `kind`: `"member"` \| `"agent"` \| `"team-key"`; `id`: `string`; \}\> |
+
+#### Returns
+
+`string`
+
+---
+
+### computerToolResult()
+
+```ts
+function computerToolResult(result): object;
+```
+
+Project one host operation result onto the model-facing tool result.
+
+#### Parameters
+
+| Parameter          | Type                                                                                                                                                                                                                                                                                                                     | Description                                                         |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------- |
+| `result`           | \{ `requestId`: `string`; `status`: `"unknown"` \| `"failed"` \| `"running"` \| `"accepted"` \| `"succeeded"` \| `"expired"`; `output`: \| \{ `status`: `"completed"` \| `"failed"` \| `"cancelled"`; `exitCode`: `number`; `stdout`: `string`; `stderr`: `string`; `truncated`: `false` \| `object`[]; \} \| `null`; \} | -                                                                   |
+| `result.requestId` | `string`                                                                                                                                                                                                                                                                                                                 | The host's id for this invocation.                                  |
+| `result.status`    | `"unknown"` \| `"failed"` \| `"running"` \| `"accepted"` \| `"succeeded"` \| `"expired"`                                                                                                                                                                                                                                 | Where the invocation stands.                                        |
+| `result.output`    | \| \{ `status`: `"completed"` \| `"failed"` \| `"cancelled"`; `exitCode`: `number`; `stdout`: `string`; `stderr`: `string`; `truncated`: `false` \| `object`[]; \} \| `null`                                                                                                                                             | The command's output once known and still retained, otherwise null. |
+
+#### Returns
+
+| Name     | Type                                                                                                                                                                         | Default value                   | Description                                                         |
+| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | ------------------------------------------------------------------- |
+| `status` | `"unknown"` \| `"failed"` \| `"running"` \| `"accepted"` \| `"succeeded"` \| `"expired"`                                                                                     | `computerOperationStatusSchema` | Where the invocation stands.                                        |
+| `output` | \| \{ `status`: `"completed"` \| `"failed"` \| `"cancelled"`; `exitCode`: `number`; `stdout`: `string`; `stderr`: `string`; `truncated`: `false` \| `object`[]; \} \| `null` | -                               | The command's output once known and still retained, otherwise null. |
+
+---
+
+### computerCapabilities()
+
+```ts
+function computerCapabilities(): object[];
+```
+
+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.
+
+#### Returns