API reference

The generated reference is in docs/api.

Exports

Kind	Export	Description
Cclass	ComputerPortReservedError	The port belongs to a Computer daemon and cannot be admitted for preview.
Cclass	ComputerPortConflictError	A requested port cannot be reserved; no other process identity is disclosed.
Cclass	ComputerPortLimitError	This Computer already admits the maximum number of preview ports.
Cclass	ComputerProcessNotFoundError	No process with this id was started on this Computer.
Cclass	ComputerProcessLimitError	Every process slot is occupied by a running process.
Cclass	ComputerFileConflict	The expected file contents no longer match at atomic replacement.
Cclass	ComputerFileRangeError	A byte window starts beyond the current file extent.
Cclass	ComputerFileTooLargeError	The requested file bytes exceed the admitted read bound.
Ttype alias	ComputerExecutionBudget	Host-owned policy, never supplied in a Computer request body.
Ttype alias	ComputerValue	A JSON value accepted by computerValueSchema.
Ttype alias	ComputerFileReadInput	A request to read one whole file as text.
Ttype alias	ComputerFileReadOutput	The reply to reading one whole file as text.
Ttype alias	ComputerFileByteReadInput	A request to read a window of bytes from one file.
Ttype alias	ComputerFileListInput	A request for one page of a directory’s entries.
Ttype alias	ComputerFileListOutput	The reply to a directory listing.
Ttype alias	ComputerFileWriteInput	A request to write one file.
Ttype alias	ComputerFileWriteOutput	The reply to a committed file write.
Ttype alias	ComputerFileGlobInput	A request to find paths that match a glob.
Ttype alias	ComputerFileGrepInput	A request to search file contents.
Ttype alias	ComputerRequestId	A request id that passed computerRequestIdSchema.
Ttype alias	ComputerExecTruncation	A record that one command stream was cut.
Ttype alias	ComputerProcessId	A process id that passed computerProcessIdSchema.
Ttype alias	ComputerProcessSync	A value of computerProcessSyncSchema.
Ttype alias	ComputerProcess	One started process, as the Computer reports it.
Ttype alias	ComputerExecInput	The model’s command input.
Ttype alias	ComputerExecRequest	The host’s command request: the model’s input plus the host’s request id.
Ttype alias	ComputerExecOutput	What a finished command left behind.
Ttype alias	ComputerExecutionCarriage	Host-memory-only native inputs. Never part of a tool, replay row or log.
Ttype alias	ComputerExecutionInvocation	Non-secret identity of the actual native invocation, not its credential.
Ttype alias	ComputerExecutionCloseReason	Authority closure is distinct from asserting a native exit code.
Ttype alias	ComputerExecutionHostHooks	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.
Ttype alias	ComputerExecutionHostPort	Protected host seam only. Public command/process parsers do not accept cargo.
Ttype alias	ComputerOperationResult	The durable status of one command invocation, for the host that owns its request id.
Ttype alias	ComputerToolResult	The status of one command invocation without the host’s request id.
Ttype alias	ComputerOperation	One public operation name.
Ttype alias	ComputerFileReplacement	A request to replace a file’s contents if they still match.
Ttype alias	ComputerFileReplacementResult	The reply to a committed replacement.
constconstant	attachedBackendIdSchema	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.
constconstant	maximumFileBytes	Most bytes of file content one Computer read or write carries, counted as UTF-8.
constconstant	maximumListEntries	Most entries one list, glob or grep reply returns in a single page.
constconstant	maximumPatternCharacters	Longest glob or search pattern a request may send.
constconstant	maximumCommandCharacters	Longest command string a request may send.
constconstant	maximumStreamBytes	Most bytes of stdout or stderr kept from one command. A longer stream is cut and marked.
constconstant	truncationMarkerReserveBytes	Room inside the stream cap for the visible truncation marker.
constconstant	maximumExecutionTimeMs	The bound for ordinary Computer commands; hosts own any admitted job budget.
constconstant	genericComputerExecutionBudget	The budget for ordinary Computer commands. Hosts that admit a job principal choose their own.
constconstant	computerValueSchema	Accepts any JSON value. Capability descriptions and other transport data are checked against it.
constconstant	capabilityNameSchema	Accepts the name of one Computer operation: a letter, then letters, digits or underscores.
constconstant	computerPortSchema	One valid TCP port number, used only with this Computer’s container.
constconstant	maximumExposedPorts	Most preview ports one Computer admits at once.
constconstant	computerDaemonPort	computerd’s Workspace RPC port, pinned by the Cloudflare container backend.
constconstant	computerTerminalPort	The Computer-owned terminal server inside the container image.
constconstant	computerReservedPorts	Ports served by the Computer’s own in-container daemons. An admitted preview must never reach a control plane.
constconstant	computerPortInputSchema	Names one container port to expose or remove.
constconstant	computerPortOutputSchema	Reply to a request to expose a port.
constconstant	computerPortRemovalOutputSchema	Reply to a request to stop exposing a port.
constconstant	computerPortsOutputSchema	The ports this Computer currently admits for preview.
constconstant	computerCapabilitiesSchema	Native operation descriptions shared by discovery and its OpenAPI document.
constconstant	pathSchema	Accepts an absolute path inside the Computer: it starts with a slash and holds no null byte.
constconstant	readInputSchema	Complete bounded UTF-8 text reads. Binary reads use the same path input.
constconstant	readOutputSchema	The whole contents of one file, as text.
constconstant	readBytesInputSchema	Optional byte window; text reads remain complete and independently bounded.
constconstant	computerByteReadReplySchema	Finite byte-read reply used by admitted App frame bindings.
constconstant	appMethodPreviewResultSchema	Host-admitted App method preview; parsing does not grant port access.
constconstant	listLimitSchema	Accepts how many entries a list returns: 1 up to maximumListEntries, 100 when omitted.
constconstant	listOffsetSchema	Accepts how many entries a list skips. Zero when omitted.
constconstant	listInputSchema	A request for one page of a directory’s entries.
constconstant	listOutputSchema	One page of a directory’s entries.
constconstant	fileContentSchema	Accepts text to store in a file, within maximumFileBytes.
constconstant	writeInputSchema	A request to write one file, creating or replacing its contents.
constconstant	writeOutputSchema	The reply to a committed file write.
constconstant	writeBytesInputSchema	Names the file for a binary write. The bytes travel as the request body.
constconstant	replaceInputSchema	A request to replace a file’s contents only if they still equal what the caller last saw.
constconstant	replaceOutputSchema	The reply to a committed replacement. It has the shape of a write reply.
constconstant	globInputSchema	A request to find paths under a directory that match a glob.
constconstant	globOutputSchema	The paths a glob found.
constconstant	grepInputSchema	A request to search file contents under a directory.
constconstant	grepOutputSchema	The lines a search found.
constconstant	editInputSchema	A request to replace one piece of text in a file.
constconstant	editOutputSchema	The reply to a committed edit.
constconstant	mkdirInputSchema	A request to create a directory.
constconstant	mkdirOutputSchema	The reply to a directory creation.
constconstant	computerRequestIdSchema	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.
constconstant	execInputSchema	The model’s command input: command, directory, backend and timeout. It carries no request id.
constconstant	execRequestSchema	Host-to-Computer command request: the model input plus the host’s ID.
constconstant	execTruncationSchema	One command stream cut at maximumStreamBytes; absent streams were whole.
constconstant	execTruncationMarkerPattern	Matches the marker line execTruncationMarker appends at the end of a stream.
constconstant	execOutputSchema	What a finished command left behind.
constconstant	computerProcessIdSchema	Accepts the durable id of one started process.
constconstant	maximumRunningProcesses	At most this many processes may be running in one host scope at once.
constconstant	maximumProcessRecords	At most this many process records, running or exited, are kept per host scope.
constconstant	processStartInputSchema	The host’s request to start one long-running process.
constconstant	processStartToolInputSchema	Model input excludes the host’s replay identity and authority scope.
constconstant	processIdInputSchema	Names one started process.
constconstant	computerProcessStateSchema	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.
constconstant	computerProcessSyncSchema	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.
constconstant	computerProcessSchema	One started process, as the Computer reports it.
constconstant	processListOutputSchema	The processes started on this Computer.
constconstant	processKillOutputSchema	The reply to a request to stop a process.
constconstant	computerOperationStatusSchema	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).
constconstant	computerOperationResultSchema	Durable operation status returned to the host that owns the request ID.
constconstant	computerToolResultSchema	Model-facing command result: the durable status without the host’s ID.
constconstant	computerOperationSchema	Public operation vocabulary; transport adapters map these to routes.
constconstant	patchInputSchema	Browser-safe patch contracts shared by native Files tools and Computer HTTP.
constconstant	patchOutputSchema	Native patch completion, cancellation or failure, including an optional mismatch.
fnfunction	isComputerReservedPort()	Whether a Computer daemon owns this port, so it can never be admitted for preview.
fnfunction	boundedTextSchema()	Builds a schema for text of at least the given length whose UTF-8 size stays within maximumFileBytes.
fnfunction	mintComputerRequestId()	Mint the request ID for one host tool invocation.
fnfunction	computerExecutionRequestSchema()	Resource hosts select a budget only after admitting their job principal.
fnfunction	execTruncationMarker()	The visible line appended to a cut stream; sizes exclude the line itself.
fnfunction	utf8Prefix()	Longest prefix of bytes within limit that ends on a UTF-8 character boundary.
fnfunction	mintComputerProcessId()	Mint the durable identity of one started process.
fnfunction	installationProcessScope()	A trusted App host binds replay identity to its admitted installation and caller.
fnfunction	computerToolResult()	Project one host operation result onto the model-facing tool result.
fnfunction	computerCapabilities()	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.

ComputerPortReservedErrorCclass

The port belongs to a Computer daemon and cannot be admitted for preview.

Extends

• Error

Constructors

Constructor

Signature

new ComputerPortReservedError(port): ComputerPortReservedError;

Parameters

Parameter	Type
port	number

Returns

ComputerPortReservedError

Overrides

Signature

Error.constructor;

---

ComputerPortConflictErrorCclass

A requested port cannot be reserved; no other process identity is disclosed.

Extends

• Error

Constructors

Constructor

Signature

new ComputerPortConflictError(): ComputerPortConflictError;

Returns

ComputerPortConflictError

Overrides

Signature

Error.constructor;

---

ComputerPortLimitErrorCclass

This Computer already admits the maximum number of preview ports.

Extends

• Error

Constructors

Constructor

Signature

new ComputerPortLimitError(): ComputerPortLimitError;

Returns

ComputerPortLimitError

Overrides

Signature

Error.constructor;

---

ComputerProcessNotFoundErrorCclass

No process with this id was started on this Computer.

Extends

• Error

Constructors

Constructor

Signature

new ComputerProcessNotFoundError(id): ComputerProcessNotFoundError;

Parameters

Parameter	Type
id	string

Returns

ComputerProcessNotFoundError

Overrides

Signature

Error.constructor;

---

ComputerProcessLimitErrorCclass

Every process slot is occupied by a running process.

Extends

• Error

Constructors

Constructor

Signature

new ComputerProcessLimitError(): ComputerProcessLimitError;

Returns

ComputerProcessLimitError

Overrides

Signature

Error.constructor;

---

ComputerFileConflictCclass

The expected file contents no longer match at atomic replacement.

Extends

• Error

Constructors

Constructor

Signature

new ComputerFileConflict(): ComputerFileConflict;

Returns

ComputerFileConflict

Overrides

Signature

Error.constructor;

---

ComputerFileRangeErrorCclass

A byte window starts beyond the current file extent.

Extends

• Error

Constructors

Constructor

Signature

new ComputerFileRangeError(size): ComputerFileRangeError;

Parameters

Parameter	Type	Description
size	number	The file’s current size in bytes.

Returns

ComputerFileRangeError

Overrides

Signature

Error.constructor;

Properties

size

Signature

readonly size: number;

The file’s current size in bytes.

---

ComputerFileTooLargeErrorCclass

The requested file bytes exceed the admitted read bound.

Extends

• Error

Constructors

Constructor

Signature

new ComputerFileTooLargeError(): ComputerFileTooLargeError;

Returns

ComputerFileTooLargeError

Overrides

Signature

Error.constructor;

ComputerExecutionBudgetTtype alias

Signature

type ComputerExecutionBudget = Readonly<{
  maximumTimeMs: number;
}>;

Host-owned policy, never supplied in a Computer request body.

---

ComputerValueTtype alias

Signature

type ComputerValue = z.output<typeof computerValueSchema>;

A JSON value accepted by computerValueSchema.

---

ComputerFileReadInputTtype alias

Signature

type ComputerFileReadInput = z.output<typeof readInputSchema>;

A request to read one whole file as text.

---

ComputerFileReadOutputTtype alias

Signature

type ComputerFileReadOutput = z.output<typeof readOutputSchema>;

The reply to reading one whole file as text.

---

ComputerFileByteReadInputTtype alias

Signature

type ComputerFileByteReadInput = z.output<typeof readBytesInputSchema>;

A request to read a window of bytes from one file.

---

ComputerFileListInputTtype alias

Signature

type ComputerFileListInput = z.output<typeof listInputSchema>;

A request for one page of a directory’s entries.

---

ComputerFileListOutputTtype alias

Signature

type ComputerFileListOutput = z.output<typeof listOutputSchema>;

The reply to a directory listing.

---

ComputerFileWriteInputTtype alias

Signature

type ComputerFileWriteInput = z.output<typeof writeInputSchema>;

A request to write one file.

---

ComputerFileWriteOutputTtype alias

Signature

type ComputerFileWriteOutput = z.output<typeof writeOutputSchema>;

The reply to a committed file write.

---

ComputerFileGlobInputTtype alias

Signature

type ComputerFileGlobInput = z.output<typeof globInputSchema>;

A request to find paths that match a glob.

---

ComputerFileGrepInputTtype alias

Signature

type ComputerFileGrepInput = z.output<typeof grepInputSchema>;

A request to search file contents.

---

ComputerRequestIdTtype alias

Signature

type ComputerRequestId = z.output<typeof computerRequestIdSchema>;

A request id that passed computerRequestIdSchema.

---

ComputerExecTruncationTtype alias

Signature

type ComputerExecTruncation = z.output<typeof execTruncationSchema>;

A record that one command stream was cut.

---

ComputerProcessIdTtype alias

Signature

type ComputerProcessId = z.output<typeof computerProcessIdSchema>;

A process id that passed computerProcessIdSchema.

---

ComputerProcessSyncTtype alias

Signature

type ComputerProcessSync = z.output<typeof computerProcessSyncSchema>;

A value of computerProcessSyncSchema.

---

ComputerProcessTtype alias

Signature

type ComputerProcess = z.output<typeof computerProcessSchema>;

One started process, as the Computer reports it.

---

ComputerExecInputTtype alias

Signature

type ComputerExecInput = z.output<typeof execInputSchema>;

The model’s command input.

---

ComputerExecRequestTtype alias

Signature

type ComputerExecRequest = z.output<typeof execRequestSchema>;

The host’s command request: the model’s input plus the host’s request id.

---

ComputerExecOutputTtype alias

Signature

type ComputerExecOutput = z.output<typeof execOutputSchema>;

What a finished command left behind.

---

ComputerExecutionCarriageTtype alias

Signature

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.

---

ComputerExecutionInvocationTtype alias

Signature

type ComputerExecutionInvocation = Readonly<{
  id: string;
  kind: "exec" | "process";
}>;

Non-secret identity of the actual native invocation, not its credential.

---

ComputerExecutionCloseReasonTtype alias

Signature

type ComputerExecutionCloseReason =
  "refused_start" | "native_exit" | "unknown" | "reconstructed";

Authority closure is distinct from asserting a native exit code.

---

ComputerExecutionHostHooksTtype alias

Signature

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.

---

ComputerExecutionHostPortTtype alias

Signature

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.

---

ComputerOperationResultTtype alias

Signature

type ComputerOperationResult = z.output<typeof computerOperationResultSchema>;

The durable status of one command invocation, for the host that owns its request id.

---

ComputerToolResultTtype alias

Signature

type ComputerToolResult = z.output<typeof computerToolResultSchema>;

The status of one command invocation without the host’s request id.

---

ComputerOperationTtype alias

Signature

type ComputerOperation = z.output<typeof computerOperationSchema>;

One public operation name.

---

ComputerFileReplacementTtype alias

Signature

type ComputerFileReplacement = z.output<typeof replaceInputSchema>;

A request to replace a file’s contents if they still match.

---

ComputerFileReplacementResultTtype alias

Signature

type ComputerFileReplacementResult = z.output<typeof replaceOutputSchema>;

The reply to a committed replacement.

attachedBackendIdSchemaconstconstant

Signature

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.

---

maximumFileBytesconstconstant

Signature

const maximumFileBytes: number;

Most bytes of file content one Computer read or write carries, counted as UTF-8.

---

maximumListEntriesconstconstant

Signature

const maximumListEntries: 256 = 256;

Most entries one list, glob or grep reply returns in a single page.

---

maximumPatternCharactersconstconstant

Signature

const maximumPatternCharacters: 512 = 512;

Longest glob or search pattern a request may send.

---

maximumCommandCharactersconstconstant

Signature

const maximumCommandCharacters: number;

Longest command string a request may send.

---

maximumStreamBytesconstconstant

Signature

const maximumStreamBytes: number;

Most bytes of stdout or stderr kept from one command. A longer stream is cut and marked.

---

truncationMarkerReserveBytesconstconstant

Signature

const truncationMarkerReserveBytes: 256 = 256;

Room inside the stream cap for the visible truncation marker.

---

maximumExecutionTimeMsconstconstant

Signature

const maximumExecutionTimeMs: 120000 = 120_000;

The bound for ordinary Computer commands; hosts own any admitted job budget.

---

genericComputerExecutionBudgetconstconstant

Signature

const genericComputerExecutionBudget: ComputerExecutionBudget;

The budget for ordinary Computer commands. Hosts that admit a job principal choose their own.

---

computerValueSchemaconstconstant

Signature

const computerValueSchema: ZodJSONSchema;

Accepts any JSON value. Capability descriptions and other transport data are checked against it.

---

capabilityNameSchemaconstconstant

Signature

const capabilityNameSchema: ZodLazy<ZodString>;

Accepts the name of one Computer operation: a letter, then letters, digits or underscores.

---

computerPortSchemaconstconstant

Signature

const computerPortSchema: ZodLazy<ZodNumber>;

One valid TCP port number, used only with this Computer’s container.

---

maximumExposedPortsconstconstant

Signature

const maximumExposedPorts: 64 = 64;

Most preview ports one Computer admits at once.

---

computerDaemonPortconstconstant

Signature

const computerDaemonPort: 8080 = 8080;

computerd’s Workspace RPC port, pinned by the Cloudflare container backend.

---

computerTerminalPortconstconstant

Signature

const computerTerminalPort: 7681 = 7681;

The Computer-owned terminal server inside the container image.

---

computerReservedPortsconstconstant

Signature

const computerReservedPorts: ReadonlySet<number>;

Ports served by the Computer’s own in-container daemons. An admitted preview must never reach a control plane.

---

computerPortInputSchemaconstconstant

Signature

const computerPortInputSchema: ZodObject<
  {
    port: ZodLazy<ZodNumber>;
  },
  $strict
>;

Names one container port to expose or remove.

---

computerPortOutputSchemaconstconstant

Signature

const computerPortOutputSchema: ZodLazy<
  ZodObject<
    {
      port: ZodLazy<ZodNumber>;
      exposed: ZodBoolean;
    },
    $strict
  >
>;

Reply to a request to expose a port.

---

computerPortRemovalOutputSchemaconstconstant

Signature

const computerPortRemovalOutputSchema: ZodLazy<
  ZodObject<
    {
      port: ZodLazy<ZodNumber>;
      removed: ZodBoolean;
    },
    $strict
  >
>;

Reply to a request to stop exposing a port.

---

computerPortsOutputSchemaconstconstant

Signature

const computerPortsOutputSchema: ZodLazy<
  ZodObject<
    {
      ports: ZodArray<ZodLazy<ZodNumber>>;
    },
    $strict
  >
>;

The ports this Computer currently admits for preview.

---

computerCapabilitiesSchemaconstconstant

Signature

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.

---

pathSchemaconstconstant

Signature

const pathSchema: ZodString;

Accepts an absolute path inside the Computer: it starts with a slash and holds no null byte.

---

readInputSchemaconstconstant

Signature

const readInputSchema: ZodObject<
  {
    path: ZodString;
  },
  $strict
>;

Complete bounded UTF-8 text reads. Binary reads use the same path input.

---

readOutputSchemaconstconstant

Signature

const readOutputSchema: ZodLazy<
  ZodObject<
    {
      path: ZodString;
      content: ZodString;
    },
    $strict
  >
>;

The whole contents of one file, as text.

---

readBytesInputSchemaconstconstant

Signature

const readBytesInputSchema: ZodObject<
  {
    path: ZodString;
    byteOffset: ZodOptional<ZodNumber>;
    byteLength: ZodOptional<ZodNumber>;
  },
  $strict
>;

Optional byte window; text reads remain complete and independently bounded.

---

computerByteReadReplySchemaconstconstant

Signature

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.

---

appMethodPreviewResultSchemaconstconstant

Signature

const appMethodPreviewResultSchema: ZodLazy<
  ZodObject<
    {
      previewUrl: ZodURL;
      expiresAt: ZodNumber;
    },
    $strict
  >
>;

Host-admitted App method preview; parsing does not grant port access.

---

listLimitSchemaconstconstant

Signature

const listLimitSchema: ZodDefault<ZodNumber>;

Accepts how many entries a list returns: 1 up to maximumListEntries, 100 when omitted.

---

listOffsetSchemaconstconstant

Signature

const listOffsetSchema: ZodDefault<ZodNumber>;

Accepts how many entries a list skips. Zero when omitted.

---

listInputSchemaconstconstant

Signature

const listInputSchema: ZodObject<
  {
    path: ZodDefault<ZodString>;
    limit: ZodDefault<ZodNumber>;
    offset: ZodDefault<ZodNumber>;
  },
  $strict
>;

A request for one page of a directory’s entries.

---

listOutputSchemaconstconstant

Signature

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.

---

fileContentSchemaconstconstant

Signature

const fileContentSchema: ZodLazy<ZodString>;

Accepts text to store in a file, within maximumFileBytes.

---

writeInputSchemaconstconstant

Signature

const writeInputSchema: ZodObject<
  {
    path: ZodString;
    content: ZodLazy<ZodString>;
  },
  $strict
>;

A request to write one file, creating or replacing its contents.

---

writeOutputSchemaconstconstant

Signature

const writeOutputSchema: ZodLazy<
  ZodObject<
    {
      path: ZodString;
      bytes: ZodNumber;
    },
    $strict
  >
>;

The reply to a committed file write.

---

writeBytesInputSchemaconstconstant

Signature

const writeBytesInputSchema: ZodObject<
  {
    path: ZodString;
  },
  $strict
> = readInputSchema;

Names the file for a binary write. The bytes travel as the request body.

---

replaceInputSchemaconstconstant

Signature

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.

---

replaceOutputSchemaconstconstant

Signature

const replaceOutputSchema: ZodLazy<
  ZodObject<
    {
      path: ZodString;
      bytes: ZodNumber;
    },
    $strict
  >
> = writeOutputSchema;

The reply to a committed replacement. It has the shape of a write reply.

---

globInputSchemaconstconstant

Signature

const globInputSchema: ZodLazy<
  ZodObject<
    {
      path: ZodString;
      pattern: ZodString;
      limit: ZodDefault<ZodNumber>;
    },
    $strict
  >
>;

A request to find paths under a directory that match a glob.

---

globOutputSchemaconstconstant

Signature

const globOutputSchema: ZodLazy<
  ZodObject<
    {
      path: ZodString;
      matches: ZodArray<ZodString>;
      truncated: ZodBoolean;
    },
    $strict
  >
>;

The paths a glob found.

---

grepInputSchemaconstconstant

Signature

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.

---

grepOutputSchemaconstconstant

Signature

const grepOutputSchema: ZodLazy<
  ZodObject<
    {
      path: ZodString;
      matches: ZodArray<
        ZodObject<
          {
            path: ZodString;
            line: ZodNumber;
            text: ZodString;
          },
          $strict
        >
      >;
      truncated: ZodBoolean;
    },
    $strict
  >
>;

The lines a search found.

---

editInputSchemaconstconstant

Signature

const editInputSchema: ZodLazy<
  ZodObject<
    {
      path: ZodString;
      oldText: ZodString;
      newText: ZodString;
    },
    $strict
  >
>;

A request to replace one piece of text in a file.

---

editOutputSchemaconstconstant

Signature

const editOutputSchema: ZodLazy<
  ZodObject<
    {
      path: ZodString;
      bytes: ZodNumber;
      diff: ZodString;
      firstChangedLine: ZodNullable<ZodNumber>;
    },
    $strict
  >
>;

The reply to a committed edit.

---

mkdirInputSchemaconstconstant

Signature

const mkdirInputSchema: ZodLazy<
  ZodObject<
    {
      path: ZodString;
      recursive: ZodDefault<ZodBoolean>;
    },
    $strict
  >
>;

A request to create a directory.

---

mkdirOutputSchemaconstconstant

Signature

const mkdirOutputSchema: ZodObject<
  {
    path: ZodString;
  },
  $strict
>;

The reply to a directory creation.

---

computerRequestIdSchemaconstconstant

Signature

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.

---

execInputSchemaconstconstant

Signature

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.

---

execRequestSchemaconstconstant

Signature

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.

---

execTruncationSchemaconstconstant

Signature

const execTruncationSchema: ZodObject<
  {
    stream: ZodEnum<{
      stdout: "stdout";
      stderr: "stderr";
    }>;
    keptBytes: ZodNumber;
    totalBytes: ZodNumber;
  },
  $strict
>;

One command stream cut at maximumStreamBytes; absent streams were whole.

---

execTruncationMarkerPatternconstconstant

Signature

const execTruncationMarkerPattern: RegExp;

Matches the marker line execTruncationMarker appends at the end of a stream.

---

execOutputSchemaconstconstant

Signature

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.

---

computerProcessIdSchemaconstconstant

Signature

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.

---

maximumRunningProcessesconstconstant

Signature

const maximumRunningProcesses: 16 = 16;

At most this many processes may be running in one host scope at once.

---

maximumProcessRecordsconstconstant

Signature

const maximumProcessRecords: 64 = 64;

At most this many process records, running or exited, are kept per host scope.

---

processStartInputSchemaconstconstant

Signature

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.

---

processStartToolInputSchemaconstconstant

Signature

const processStartToolInputSchema: ZodObject<
  {
    port: ZodOptional<ZodLazy<ZodNumber>>;
    command: ZodString;
    cwd: ZodOptional<ZodString>;
  },
  $strict
>;

Model input excludes the host’s replay identity and authority scope.

---

processIdInputSchemaconstconstant

Signature

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.

---

computerProcessStateSchemaconstconstant

Signature

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.

---

computerProcessSyncSchemaconstconstant

Signature

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.

---

computerProcessSchemaconstconstant

Signature

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.

---

processListOutputSchemaconstconstant

Signature

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.

---

processKillOutputSchemaconstconstant

Signature

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.

---

computerOperationStatusSchemaconstconstant

Signature

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).

---

computerOperationResultSchemaconstconstant

Signature

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.

---

computerToolResultSchemaconstconstant

Signature

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.

---

computerOperationSchemaconstconstant

Signature

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.

---

patchInputSchemaconstconstant

Signature

const patchInputSchema: z.ZodLazy<
  z.ZodObject<
    {
      patch: z.ZodString;
    },
    z.core.$strict
  >
>;

Browser-safe patch contracts shared by native Files tools and Computer HTTP.

---

patchOutputSchemaconstconstant

Signature

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.

isComputerReservedPort()fnfunction

Signature

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()fnfunction

Signature

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()fnfunction

Signature

function mintComputerRequestId(): string;

Mint the request ID for one host tool invocation.

Returns

string

---

computerExecutionRequestSchema()fnfunction

Signature

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

Returns

ZodObject<{ command: ZodString; cwd: ZodOptional<ZodString>; backend: ZodOptional<ZodLazy<ZodString>>; timeoutMs: ZodDefault<ZodNumber>; requestId: ZodUUID; }, $strict>

---

execTruncationMarker()fnfunction

Signature

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()fnfunction

Signature

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()fnfunction

Signature

function mintComputerProcessId(): string & object;

Mint the durable identity of one started process.

Returns

---

installationProcessScope()fnfunction

Signature

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()fnfunction

Signature

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()fnfunction

Signature

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