@finalai/computers 0.1.0

package/dist/modules/types.d.mts

@@ -0,0 +1,467 @@
+import type { ComputerScreenOpenOptionsIface, ComputerScreenSessionIface } from "./screen.mjs";
+import type { ComputerBrowserAccessIface, ComputerBrowserAccessOptionsIface } from "./browser-access.mjs";
+import type { ResultIface } from "./result.mjs";
+import type { ComputerSnapshotRequestIface, ComputerSnapshotResponseIface } from "./file-snapshots.mjs";
+import type { JsonObject } from "./json.mjs";
+export declare enum ComputerState {
+    Unknown = 0,
+    Pending = 1,
+    Creating = 2,
+    Running = 3,
+    Paused = 4,
+    Stopped = 5,
+    Resuming = 6,
+    Error = 8,
+    Deleted = 9,
+    Shelved = 10
+}
+export declare enum ComputerCommandMode {
+    Auto = 1,
+    None = 2,
+    Custom = 3
+}
+export declare enum ComputerIdlePolicy {
+    Shelve = "shelve",
+    Pause = "pause",
+    Delete = "delete"
+}
+export declare enum ComputerImageState {
+    Pending = "pending",
+    Building = "building",
+    Ready = "ready",
+    Failed = "failed",
+    Expired = "expired"
+}
+export declare enum ComputerImageSource {
+    Platform = "platform",
+    Customer = "customer"
+}
+export declare enum ComputerEgressPolicy {
+    Internet = "internet",
+    None = "none",
+    Allowlist = "allowlist"
+}
+export declare enum ComputerBaseState {
+    Capturing = "capturing",
+    Ready = "ready",
+    Failed = "failed",
+    Expired = "expired"
+}
+export interface ComputerApiKeyAuthIface {
+    apiKey: string;
+}
+export type ComputerClientAuth = ComputerApiKeyAuthIface;
+export interface LifecycleActionOptionsIface {
+    signal?: AbortSignal;
+}
+export interface CreateComputerClientArgsIface {
+    baseUrl: string;
+    auth: ComputerClientAuth;
+    requestTimeoutMs?: number;
+    fetch?: typeof fetch;
+    signal?: AbortSignal;
+}
+export interface ComputerInfoIface {
+    id: string;
+    name: string;
+    teamId: string | null;
+    ownerUserId: string | null;
+    state: ComputerState;
+    stateName: string | null;
+    desiredState: number | null;
+    image: string | null;
+    imageVersionId: string | null;
+    regionSlug: string | null;
+    vcpu: number | null;
+    memoryMb: number | null;
+    diskGb: number | null;
+    httpPort: number | null;
+    httpPublic: boolean;
+    ephemeral: boolean;
+    idleTimeoutSeconds: number | null;
+    autoResume: boolean;
+    tags: string[];
+    comment: string | null;
+    errorMessage: string | null;
+    hostname: string | null;
+    createdAt: string | null;
+    lastActiveAt: string | null;
+    startupTimings: JsonObject;
+    legacyBackupCheckpoint: JsonObject | null;
+    storageCheckpointCompletedAtMs: number | null;
+}
+export interface CreateComputerBaseOptsIface {
+    name?: string;
+    /** Create a team-owned computer. Omit to create a private computer for the acting user. */
+    teamId?: string;
+    regionSlug?: string;
+    vcpu?: number;
+    memoryMb?: number;
+    diskGb?: number;
+    /**
+     * Size of the user volume holding /home/user and /workspaces. Omit for the
+     * tier default on computers that retain state; null for none.
+     */
+    userVolumeGb?: number | null;
+    env?: Record<string, string>;
+    setupScript?: string;
+    commandMode?: ComputerCommandMode;
+    customCommand?: string;
+    httpPort?: number;
+    httpPublic?: boolean;
+    ephemeral?: boolean;
+    idleTimeoutSeconds?: number;
+    /**
+     * What happens after idleTimeoutSeconds: shelve (default), pause, or delete.
+     */
+    idlePolicy?: ComputerIdlePolicy;
+    /** Outbound network: internet, none, or an exact DNS/IPv4/CIDR allowlist. */
+    network?: {
+        egress: ComputerEgressPolicy;
+        allow?: string[];
+    };
+    terminationGraceSeconds?: number;
+    autoResume?: boolean;
+    tags?: string[];
+    comment?: string;
+    /** Sent as the Idempotency-Key header, never in the body. */
+    idempotencyKey?: string;
+}
+/** Create from a ready image version (`cimv_…`), registered with `registerImage`. */
+export interface CreateComputerFromImageVersionOptsIface extends CreateComputerBaseOptsIface {
+    imageVersionId: string;
+    baseId?: never;
+    image?: never;
+    lineage?: never;
+    registryCredentialId?: never;
+}
+/** API keys: create from a ready base (`part_…`), captured with `captureComputer`. */
+export interface CreateComputerFromBaseOptsIface extends CreateComputerBaseOptsIface {
+    baseId: string;
+    imageVersionId?: never;
+    image?: never;
+    lineage?: never;
+    registryCredentialId?: never;
+    projectArtifact?: never;
+}
+export type CreateComputerOptsIface = CreateComputerFromImageVersionOptsIface | CreateComputerFromBaseOptsIface;
+export interface ComputerImageIface {
+    id: string;
+    /** Platform images are built by each release; customer ones by registerImage. */
+    source: ComputerImageSource;
+    reference: string;
+    lineage: string;
+    digest: string;
+    state: ComputerImageState;
+    error: string | null;
+    sizes: string[];
+    registryCredentialId: string | null;
+    createdAt: string | null;
+    readyAt: string | null;
+    lastUsedAt: string | null;
+}
+export interface ComputerBaseIface {
+    id: string;
+    state: ComputerBaseState;
+    error: string | null;
+    computerId: string | null;
+    image: string;
+    digest: string;
+    diskGb: number | null;
+    createdAt: string | null;
+    readyAt: string | null;
+    lastUsedAt: string | null;
+    /** Remains available until retention is released explicitly. */
+    retained: boolean;
+}
+export interface RegisterImageOptsIface {
+    reference: string;
+    /** A stored credential for the image's registry. */
+    registryCredentialId?: string;
+    /** Stored for the registration; deleted once nothing uses it. */
+    registryCredential?: {
+        username: string;
+        password: string;
+    };
+    /** Machine tier names to build for; defaults to ['standard']. */
+    sizes?: string[];
+    /** Sent as the Idempotency-Key header (API keys only), never in the body. */
+    idempotencyKey?: string;
+}
+export interface ListImagesOptsIface {
+    lineage?: string;
+    state?: ComputerImageState;
+}
+export interface ComputerUseStatusIface {
+    available: boolean;
+    installed: boolean;
+}
+export interface ComputerUseOpenOptsIface {
+    cwd?: string;
+    readyTimeoutMs?: number;
+}
+export interface ExecProcessOptsIface {
+    /** False refuses a sleeping computer instead of automatically waking it. */
+    autoResume?: boolean;
+    env?: Record<string, string>;
+    cwd?: string;
+    user?: string;
+    pty?: boolean;
+    cols?: number;
+    rows?: number;
+    /** Explicit process lifetime timeout. Waiting for output has its own timeout. */
+    timeoutMs?: number;
+}
+export interface ProcessWaitResultIface {
+    exitCode: number | null;
+    signal: string | null;
+}
+export interface ComputerProcessIface {
+    id: string;
+    bootId: string;
+    command: string;
+    leaderPid: number | null;
+    state: 'running' | 'exited';
+    keepsAwake: boolean;
+    createdAtMs: number;
+    updatedAtMs: number;
+    endedAtMs: number | null;
+    cpuUsec: number;
+    memoryBytes: number;
+    memoryPeakBytes: number;
+    ioReadBytes: number;
+    ioWriteBytes: number;
+    processCount: number;
+    descendantCount?: number;
+}
+export interface ProcessOutputChunkIface {
+    data: string;
+    /** Raw output bytes for incremental decoding across UTF-8 chunk boundaries. */
+    dataBytes: Uint8Array;
+    offset: number;
+    nextOffset: number;
+    eof: boolean;
+    state: 'running' | 'exited';
+}
+export interface ProcessOutputIface {
+    read: (opts?: {
+        offset?: number;
+        waitMs?: number;
+    }) => Promise<ResultIface<ProcessOutputChunkIface>>;
+}
+export interface ReadProcessOutputOptsIface {
+    stdoutOffset: number;
+    stderrOffset: number;
+    waitMs?: number;
+}
+export interface ProcessOutputBatchIface {
+    stdout: ProcessOutputChunkIface;
+    stderr: ProcessOutputChunkIface;
+    state: 'running' | 'exited';
+    result: ProcessWaitResultIface | null;
+}
+export interface RunCommandOptsIface {
+    /** False refuses a sleeping computer instead of automatically waking it. */
+    autoResume?: boolean;
+    env?: Record<string, string>;
+    cwd?: string;
+    user?: string;
+    /** Process lifetime timeout, enforced in the computer. */
+    timeoutMs?: number;
+    /** How long the request waits for the exit; at most 30 seconds, the default. */
+    waitMs?: number;
+    /** How long the service waits for the computer to be able to start the process. */
+    readyTimeoutMs?: number;
+}
+export interface ComputerRunIface {
+    /** The process, for reading more output or terminating it. */
+    process: ProcessHandleIface;
+    /**
+     * Output from offset zero. It is complete when `state` is `exited` and both streams
+     * are at `eof`; otherwise read on with `process.readOutput` from each `nextOffset`.
+     */
+    output: ProcessOutputBatchIface;
+    /** The computer killed the process at its `timeoutMs`. */
+    timedOut: boolean;
+    /** How long the process had been running when this answer was made. */
+    elapsedMs: number;
+}
+export interface ProcessHandleIface {
+    id: string;
+    bootId: string;
+    pid: number | null;
+    state: 'running' | 'exited';
+    /** Stateless read of both streams and the exit result, using byte offsets. */
+    readOutput: (opts: ReadProcessOutputOptsIface) => Promise<ResultIface<ProcessOutputBatchIface>>;
+    stdout: ProcessOutputIface;
+    stderr: ProcessOutputIface;
+    wait: (opts?: {
+        timeoutMs?: number;
+    }) => Promise<ResultIface<ProcessWaitResultIface>>;
+    write: (data: string | Uint8Array) => Promise<ResultIface<{
+        ok: true;
+    }>>;
+    eof: () => Promise<ResultIface<{
+        ok: true;
+    }>>;
+    resize: (cols: number, rows: number) => Promise<ResultIface<{
+        ok: true;
+    }>>;
+    signal: (signal: string) => Promise<ResultIface<{
+        ok: true;
+    }>>;
+    terminate: () => Promise<ResultIface<{
+        ok: true;
+    }>>;
+}
+export interface ComputerFileWriteResultIface {
+    bytesWritten: number;
+}
+export interface ComputerSettingsPatchIface {
+    network?: {
+        egress: ComputerEgressPolicy;
+        allow?: string[];
+    };
+    name?: string;
+    vcpu?: number;
+    memoryMb?: number;
+    diskGb?: number;
+    httpPort?: number | null;
+    httpPublic?: boolean;
+    idleTimeoutSeconds?: number | null;
+    autoResume?: boolean;
+    tags?: string[];
+    comment?: string | null;
+    env?: Record<string, string>;
+}
+export interface ComputerProcessesIface {
+    list: () => Promise<ResultIface<ComputerProcessIface[]>>;
+    get: (id: string, bootId: string) => Promise<ResultIface<ProcessHandleIface>>;
+}
+export interface ComputerFilesIface {
+    /** Read a committed sleeping workspace without waking it. Pin subsequent reads by generation. */
+    snapshot: (request: ComputerSnapshotRequestIface) => Promise<ResultIface<ComputerSnapshotResponseIface>>;
+    /** Reads the whole file as UTF-8 text, in ranged requests. */
+    read: (path: string, options?: {
+        autoResume?: boolean;
+    }) => Promise<ResultIface<string>>;
+    /** Reads the whole file as bytes, in ranged requests. */
+    readBytes: (path: string, options?: {
+        autoResume?: boolean;
+    }) => Promise<ResultIface<Uint8Array>>;
+    /** Replaces the file. Data over one chunk is appended in order, so a failure can leave a prefix. */
+    write: (path: string, data: string | Uint8Array) => Promise<ResultIface<ComputerFileWriteResultIface>>;
+}
+export declare enum ComputerTokenScope {
+    /** The public API, within the token's organization or computer. */
+    Api = "api",
+    /** The computer's HTTP ports through the gateway, never the API. */
+    Http = "http",
+    Screen = "screen",
+    ScreenControl = "screen:control"
+}
+export interface CreateTokenOptsIface {
+    name: string;
+    /** Confines the token to one computer. Without it the token covers the organization. */
+    computerId?: string;
+    /** Omit for a full-access token. */
+    scopes?: ComputerTokenScope[];
+    expiresAt?: Date;
+}
+export interface ComputerTokenIface {
+    id: string;
+    /** Returned once; send as `Authorization: Bearer <token>`. */
+    token: string;
+}
+export interface CreatePreviewTokenOptsIface {
+    name?: string;
+    /** Defaults to one hour from now. */
+    expiresAt?: Date;
+}
+export interface ComputerHandleIface {
+    browserAccess: {
+        open(options: ComputerBrowserAccessOptionsIface): Promise<ResultIface<ComputerBrowserAccessIface>>;
+        close(tokenId: string): Promise<ResultIface<{
+            ok: boolean;
+        }>>;
+    };
+    screen: {
+        status: () => Promise<ResultIface<{
+            available: boolean;
+        }>>;
+        open: (options?: ComputerScreenOpenOptionsIface) => Promise<ResultIface<ComputerScreenSessionIface>>;
+    };
+    computerUse: {
+        status(): Promise<ResultIface<ComputerUseStatusIface>>;
+        available(): Promise<ResultIface<boolean>>;
+        open(options?: ComputerUseOpenOptsIface): Promise<ResultIface<ProcessHandleIface>>;
+    };
+    id: string;
+    name: string;
+    getInfo: () => ComputerInfoIface;
+    refresh: () => Promise<ResultIface<ComputerInfoIface>>;
+    refreshActivity: () => Promise<ResultIface<ComputerInfoIface>>;
+    exec: (command: string, opts?: ExecProcessOptsIface) => Promise<ResultIface<ProcessHandleIface>>;
+    /**
+     * Runs a command with stdin closed and returns its output and exit in one request. Use
+     * `exec` for a process that reads stdin, needs a terminal, or outlives the call.
+     */
+    run: (command: string, opts?: RunCommandOptsIface) => Promise<ResultIface<ComputerRunIface>>;
+    processes: ComputerProcessesIface;
+    files: ComputerFilesIface;
+    /** `hostname[:port]` from the computer's hostname; port 443 → bare hostname. Null until the computer has a hostname. */
+    getHost: (port: number) => string | null;
+    /**
+     * Mints a token that opens this computer's HTTP ports and nothing else: the API refuses
+     * it. Send it as `Authorization: Bearer <token>` to a `getHost` URL of a private computer.
+     */
+    createPreviewToken: (opts?: CreatePreviewTokenOptsIface) => Promise<ResultIface<ComputerTokenIface>>;
+    pause: () => Promise<ResultIface<ComputerInfoIface>>;
+    resume: () => Promise<ResultIface<ComputerInfoIface>>;
+    start: () => Promise<ResultIface<ComputerInfoIface>>;
+    stop: () => Promise<ResultIface<ComputerInfoIface>>;
+    restart: () => Promise<ResultIface<ComputerInfoIface>>;
+    /** Convenience alias: kill performs the delete lifecycle action. */
+    kill: () => Promise<ResultIface<ComputerInfoIface>>;
+    settings: (patch: ComputerSettingsPatchIface) => Promise<ResultIface<ComputerInfoIface>>;
+}
+export type ComputerConnectTarget = ({
+    id: string;
+} | {
+    name: string;
+}) & {
+    /**
+     * Resume paused, stopped, or shelved computers before returning a handle.
+     * Defaults to true. Set false for background work that must never wake a VM.
+     */
+    resumeIfNeeded?: boolean;
+};
+export interface ComputerClientIface {
+    stopComputerRetained: (idOrName: string) => Promise<ResultIface<ComputerInfoIface>>;
+    createComputer: (opts: CreateComputerOptsIface) => Promise<ResultIface<ComputerHandleIface>>;
+    connectComputer: (target: ComputerConnectTarget) => Promise<ResultIface<ComputerHandleIface>>;
+    pauseComputer: (idOrName: string) => Promise<ResultIface<ComputerInfoIface>>;
+    resumeComputer: (idOrName: string) => Promise<ResultIface<ComputerInfoIface>>;
+    stopComputer: (idOrName: string, options?: LifecycleActionOptionsIface) => Promise<ResultIface<ComputerInfoIface>>;
+    refreshComputerActivity: (idOrName: string) => Promise<ResultIface<ComputerInfoIface>>;
+    listComputers: () => Promise<ResultIface<ComputerInfoIface[]>>;
+    getComputer: (idOrName: string) => Promise<ResultIface<ComputerInfoIface>>;
+    deleteComputer: (idOrName: string) => Promise<ResultIface<ComputerInfoIface>>;
+    /** Registers an image; poll getImage until it is ready, then create from its id. */
+    registerImage: (opts: RegisterImageOptsIface) => Promise<ResultIface<ComputerImageIface>>;
+    getImage: (id: string) => Promise<ResultIface<ComputerImageIface>>;
+    listImages: (opts?: ListImagesOptsIface) => Promise<ResultIface<ComputerImageIface[]>>;
+    /**
+     * API keys: captures a running computer (created with userVolumeGb: null) as a
+     * base; poll getBase until it is ready, then create with its id as baseId.
+     * The computer stops for the capture.
+     */
+    captureComputer: (idOrName: string, options?: {
+        retained?: boolean;
+    }) => Promise<ResultIface<ComputerBaseIface>>;
+    setBaseRetention: (id: string, retained: boolean) => Promise<ResultIface<ComputerBaseIface>>;
+    getBase: (id: string) => Promise<ResultIface<ComputerBaseIface>>;
+    createToken: (opts: CreateTokenOptsIface) => Promise<ResultIface<ComputerTokenIface>>;
+    revokeToken: (id: string) => Promise<ResultIface<void>>;
+    withEphemeralComputer: <T>(opts: CreateComputerOptsIface, fn: (computer: ComputerHandleIface) => Promise<T>) => Promise<T>;
+}

package/dist/modules/types.mjs

@@ -0,0 +1,69 @@
+var ComputerState = /* @__PURE__ */ ((ComputerState2) => {
+  ComputerState2[ComputerState2["Unknown"] = 0] = "Unknown";
+  ComputerState2[ComputerState2["Pending"] = 1] = "Pending";
+  ComputerState2[ComputerState2["Creating"] = 2] = "Creating";
+  ComputerState2[ComputerState2["Running"] = 3] = "Running";
+  ComputerState2[ComputerState2["Paused"] = 4] = "Paused";
+  ComputerState2[ComputerState2["Stopped"] = 5] = "Stopped";
+  ComputerState2[ComputerState2["Resuming"] = 6] = "Resuming";
+  ComputerState2[ComputerState2["Error"] = 8] = "Error";
+  ComputerState2[ComputerState2["Deleted"] = 9] = "Deleted";
+  ComputerState2[ComputerState2["Shelved"] = 10] = "Shelved";
+  return ComputerState2;
+})(ComputerState || {});
+var ComputerCommandMode = /* @__PURE__ */ ((ComputerCommandMode2) => {
+  ComputerCommandMode2[ComputerCommandMode2["Auto"] = 1] = "Auto";
+  ComputerCommandMode2[ComputerCommandMode2["None"] = 2] = "None";
+  ComputerCommandMode2[ComputerCommandMode2["Custom"] = 3] = "Custom";
+  return ComputerCommandMode2;
+})(ComputerCommandMode || {});
+var ComputerIdlePolicy = /* @__PURE__ */ ((ComputerIdlePolicy2) => {
+  ComputerIdlePolicy2["Shelve"] = "shelve";
+  ComputerIdlePolicy2["Pause"] = "pause";
+  ComputerIdlePolicy2["Delete"] = "delete";
+  return ComputerIdlePolicy2;
+})(ComputerIdlePolicy || {});
+var ComputerImageState = /* @__PURE__ */ ((ComputerImageState2) => {
+  ComputerImageState2["Pending"] = "pending";
+  ComputerImageState2["Building"] = "building";
+  ComputerImageState2["Ready"] = "ready";
+  ComputerImageState2["Failed"] = "failed";
+  ComputerImageState2["Expired"] = "expired";
+  return ComputerImageState2;
+})(ComputerImageState || {});
+var ComputerImageSource = /* @__PURE__ */ ((ComputerImageSource2) => {
+  ComputerImageSource2["Platform"] = "platform";
+  ComputerImageSource2["Customer"] = "customer";
+  return ComputerImageSource2;
+})(ComputerImageSource || {});
+var ComputerEgressPolicy = /* @__PURE__ */ ((ComputerEgressPolicy2) => {
+  ComputerEgressPolicy2["Internet"] = "internet";
+  ComputerEgressPolicy2["None"] = "none";
+  ComputerEgressPolicy2["Allowlist"] = "allowlist";
+  return ComputerEgressPolicy2;
+})(ComputerEgressPolicy || {});
+var ComputerBaseState = /* @__PURE__ */ ((ComputerBaseState2) => {
+  ComputerBaseState2["Capturing"] = "capturing";
+  ComputerBaseState2["Ready"] = "ready";
+  ComputerBaseState2["Failed"] = "failed";
+  ComputerBaseState2["Expired"] = "expired";
+  return ComputerBaseState2;
+})(ComputerBaseState || {});
+var ComputerTokenScope = /* @__PURE__ */ ((ComputerTokenScope2) => {
+  ComputerTokenScope2["Api"] = "api";
+  ComputerTokenScope2["Http"] = "http";
+  ComputerTokenScope2["Screen"] = "screen";
+  ComputerTokenScope2["ScreenControl"] = "screen:control";
+  return ComputerTokenScope2;
+})(ComputerTokenScope || {});
+export {
+  ComputerBaseState,
+  ComputerCommandMode,
+  ComputerEgressPolicy,
+  ComputerIdlePolicy,
+  ComputerImageSource,
+  ComputerImageState,
+  ComputerState,
+  ComputerTokenScope
+};
+//# sourceMappingURL=types.mjs.map

package/dist/modules/types.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/types.ts"],
+  "sourcesContent": ["import type { ComputerScreenOpenOptionsIface, ComputerScreenSessionIface } from \"./screen.mjs\";\n\nimport type {\n  ComputerBrowserAccessIface,\n  ComputerBrowserAccessOptionsIface,\n} from \"./browser-access.mjs\";\n\nimport type { ResultIface } from \"./result.mjs\";\n\nimport type { ComputerSnapshotRequestIface, ComputerSnapshotResponseIface } from \"./file-snapshots.mjs\";\n\nimport type { JsonObject } from \"./json.mjs\";\n\n// Stable values returned by the public Computers API.\nexport enum ComputerState {\n  Unknown = 0,\n  Pending = 1,\n  Creating = 2,\n  Running = 3,\n  Paused = 4,\n  Stopped = 5,\n  Resuming = 6,\n  // 7 was Migrating (the retired v2 -> v3 storage migration); never reuse it.\n  Error = 8,\n  Deleted = 9,\n  Shelved = 10,\n}\n\nexport enum ComputerCommandMode {\n  Auto = 1,\n  None = 2,\n  Custom = 3,\n}\n\nexport enum ComputerIdlePolicy {\n  Shelve = 'shelve',\n  Pause = 'pause',\n  Delete = 'delete',\n}\n\nexport enum ComputerImageState {\n  Pending = 'pending',\n  Building = 'building',\n  Ready = 'ready',\n  Failed = 'failed',\n  Expired = 'expired',\n}\n\nexport enum ComputerImageSource {\n  Platform = 'platform',\n  Customer = 'customer',\n}\n\nexport enum ComputerEgressPolicy {\n  Internet = 'internet',\n  None = 'none',\n  Allowlist = 'allowlist',\n}\n\nexport enum ComputerBaseState {\n  Capturing = 'capturing',\n  Ready = 'ready',\n  Failed = 'failed',\n  Expired = 'expired',\n}\n\nexport interface ComputerApiKeyAuthIface {\n  apiKey: string;\n}\n\nexport type ComputerClientAuth = ComputerApiKeyAuthIface;\n\nexport interface LifecycleActionOptionsIface {\n  signal?: AbortSignal;\n}\n\nexport interface CreateComputerClientArgsIface {\n  baseUrl: string;\n  auth: ComputerClientAuth;\n  // Aborts each request after this long; unbounded when omitted.\n  requestTimeoutMs?: number;\n  fetch?: typeof fetch;\n  signal?: AbortSignal;\n}\n\n// Normalized computer information returned by the public API.\nexport interface ComputerInfoIface {\n  id: string;\n  name: string;\n  teamId: string | null;\n  ownerUserId: string | null;\n  state: ComputerState;\n  stateName: string | null;\n  desiredState: number | null;\n  image: string | null;\n  imageVersionId: string | null;\n  regionSlug: string | null;\n  vcpu: number | null;\n  memoryMb: number | null;\n  diskGb: number | null;\n  httpPort: number | null;\n  httpPublic: boolean;\n  ephemeral: boolean;\n  idleTimeoutSeconds: number | null;\n  autoResume: boolean;\n  tags: string[];\n  comment: string | null;\n  errorMessage: string | null;\n  hostname: string | null;\n  createdAt: string | null;\n  lastActiveAt: string | null;\n  startupTimings: JsonObject;\n  legacyBackupCheckpoint: JsonObject | null;\n  storageCheckpointCompletedAtMs: number | null;\n}\n\nexport interface CreateComputerBaseOptsIface {\n  name?: string;\n  /** Create a team-owned computer. Omit to create a private computer for the acting user. */\n  teamId?: string;\n  regionSlug?: string;\n  vcpu?: number;\n  memoryMb?: number;\n  diskGb?: number;\n  /**\n   * Size of the user volume holding /home/user and /workspaces. Omit for the\n   * tier default on computers that retain state; null for none.\n   */\n  userVolumeGb?: number | null;\n  env?: Record<string, string>;\n  setupScript?: string;\n  commandMode?: ComputerCommandMode;\n  customCommand?: string;\n  httpPort?: number;\n  httpPublic?: boolean;\n  ephemeral?: boolean;\n  idleTimeoutSeconds?: number;\n  /**\n   * What happens after idleTimeoutSeconds: shelve (default), pause, or delete.\n   */\n  idlePolicy?: ComputerIdlePolicy;\n  /** Outbound network: internet, none, or an exact DNS/IPv4/CIDR allowlist. */\n  network?: { egress: ComputerEgressPolicy; allow?: string[] };\n  terminationGraceSeconds?: number;\n  autoResume?: boolean;\n  tags?: string[];\n  comment?: string;\n  /** Sent as the Idempotency-Key header, never in the body. */\n  idempotencyKey?: string;\n}\n\n/** Create from a ready image version (`cimv_\u2026`), registered with `registerImage`. */\nexport interface CreateComputerFromImageVersionOptsIface extends CreateComputerBaseOptsIface {\n  imageVersionId: string;\n  baseId?: never;\n  image?: never;\n  lineage?: never;\n  registryCredentialId?: never;\n}\n\n/** API keys: create from a ready base (`part_\u2026`), captured with `captureComputer`. */\nexport interface CreateComputerFromBaseOptsIface extends CreateComputerBaseOptsIface {\n  baseId: string;\n  imageVersionId?: never;\n  image?: never;\n  lineage?: never;\n  registryCredentialId?: never;\n  projectArtifact?: never;\n}\n\nexport type CreateComputerOptsIface =\n  | CreateComputerFromImageVersionOptsIface\n  | CreateComputerFromBaseOptsIface;\n\n// A registered image version. Computers are created from ready ones.\nexport interface ComputerImageIface {\n  id: string;\n  /** Platform images are built by each release; customer ones by registerImage. */\n  source: ComputerImageSource;\n  reference: string;\n  lineage: string;\n  digest: string;\n  state: ComputerImageState;\n  error: string | null;\n  sizes: string[];\n  registryCredentialId: string | null;\n  createdAt: string | null;\n  readyAt: string | null;\n  lastUsedAt: string | null;\n}\n\n// A computer's disk captured with captureComputer. Computers are created from ready ones.\nexport interface ComputerBaseIface {\n  id: string;\n  state: ComputerBaseState;\n  error: string | null;\n  // The captured computer.\n  computerId: string | null;\n  // The image the captured computer ran.\n  image: string;\n  digest: string;\n  diskGb: number | null;\n  createdAt: string | null;\n  readyAt: string | null;\n  lastUsedAt: string | null;\n  /** Remains available until retention is released explicitly. */\n  retained: boolean;\n}\n\nexport interface RegisterImageOptsIface {\n  reference: string;\n  /** A stored credential for the image's registry. */\n  registryCredentialId?: string;\n  /** Stored for the registration; deleted once nothing uses it. */\n  registryCredential?: { username: string; password: string };\n  /** Machine tier names to build for; defaults to ['standard']. */\n  sizes?: string[];\n  /** Sent as the Idempotency-Key header (API keys only), never in the body. */\n  idempotencyKey?: string;\n}\n\nexport interface ListImagesOptsIface {\n  lineage?: string;\n  state?: ComputerImageState;\n}\n\nexport interface ComputerUseStatusIface {\n  available: boolean;\n  installed: boolean;\n}\n\nexport interface ComputerUseOpenOptsIface {\n  cwd?: string;\n  readyTimeoutMs?: number;\n}\n\nexport interface ExecProcessOptsIface {\n  /** False refuses a sleeping computer instead of automatically waking it. */\n  autoResume?: boolean;\n  env?: Record<string, string>;\n  cwd?: string;\n  user?: string;\n  pty?: boolean;\n  cols?: number;\n  rows?: number;\n  /** Explicit process lifetime timeout. Waiting for output has its own timeout. */\n  timeoutMs?: number;\n}\n\nexport interface ProcessWaitResultIface {\n  exitCode: number | null;\n  signal: string | null;\n}\n\nexport interface ComputerProcessIface {\n  id: string;\n  bootId: string;\n  command: string;\n  leaderPid: number | null;\n  state: 'running' | 'exited';\n  keepsAwake: boolean;\n  createdAtMs: number;\n  updatedAtMs: number;\n  endedAtMs: number | null;\n  cpuUsec: number;\n  memoryBytes: number;\n  memoryPeakBytes: number;\n  ioReadBytes: number;\n  ioWriteBytes: number;\n  processCount: number;\n  descendantCount?: number;\n}\n\nexport interface ProcessOutputChunkIface {\n  data: string;\n  /** Raw output bytes for incremental decoding across UTF-8 chunk boundaries. */\n  dataBytes: Uint8Array;\n  offset: number;\n  nextOffset: number;\n  eof: boolean;\n  state: 'running' | 'exited';\n}\n\nexport interface ProcessOutputIface {\n  read: (opts?: {\n    offset?: number;\n    waitMs?: number;\n  }) => Promise<ResultIface<ProcessOutputChunkIface>>;\n}\n\nexport interface ReadProcessOutputOptsIface {\n  stdoutOffset: number;\n  stderrOffset: number;\n  waitMs?: number;\n}\n\nexport interface ProcessOutputBatchIface {\n  stdout: ProcessOutputChunkIface;\n  stderr: ProcessOutputChunkIface;\n  state: 'running' | 'exited';\n  result: ProcessWaitResultIface | null;\n}\n\nexport interface RunCommandOptsIface {\n  /** False refuses a sleeping computer instead of automatically waking it. */\n  autoResume?: boolean;\n  env?: Record<string, string>;\n  cwd?: string;\n  user?: string;\n  /** Process lifetime timeout, enforced in the computer. */\n  timeoutMs?: number;\n  /** How long the request waits for the exit; at most 30 seconds, the default. */\n  waitMs?: number;\n  /** How long the service waits for the computer to be able to start the process. */\n  readyTimeoutMs?: number;\n}\n\nexport interface ComputerRunIface {\n  /** The process, for reading more output or terminating it. */\n  process: ProcessHandleIface;\n  /**\n   * Output from offset zero. It is complete when `state` is `exited` and both streams\n   * are at `eof`; otherwise read on with `process.readOutput` from each `nextOffset`.\n   */\n  output: ProcessOutputBatchIface;\n  /** The computer killed the process at its `timeoutMs`. */\n  timedOut: boolean;\n  /** How long the process had been running when this answer was made. */\n  elapsedMs: number;\n}\n\nexport interface ProcessHandleIface {\n  id: string;\n  bootId: string;\n  pid: number | null;\n  state: 'running' | 'exited';\n  /** Stateless read of both streams and the exit result, using byte offsets. */\n  readOutput: (opts: ReadProcessOutputOptsIface) => Promise<ResultIface<ProcessOutputBatchIface>>;\n  stdout: ProcessOutputIface;\n  stderr: ProcessOutputIface;\n  wait: (opts?: { timeoutMs?: number }) => Promise<ResultIface<ProcessWaitResultIface>>;\n  write: (data: string | Uint8Array) => Promise<ResultIface<{ ok: true }>>;\n  eof: () => Promise<ResultIface<{ ok: true }>>;\n  resize: (cols: number, rows: number) => Promise<ResultIface<{ ok: true }>>;\n  signal: (signal: string) => Promise<ResultIface<{ ok: true }>>;\n  terminate: () => Promise<ResultIface<{ ok: true }>>;\n}\n\nexport interface ComputerFileWriteResultIface {\n  bytesWritten: number;\n}\n\nexport interface ComputerSettingsPatchIface {\n  network?: { egress: ComputerEgressPolicy; allow?: string[] };\n  name?: string;\n  vcpu?: number;\n  memoryMb?: number;\n  diskGb?: number;\n  httpPort?: number | null;\n  httpPublic?: boolean;\n  idleTimeoutSeconds?: number | null;\n  autoResume?: boolean;\n  tags?: string[];\n  comment?: string | null;\n  env?: Record<string, string>;\n}\n\nexport interface ComputerProcessesIface {\n  list: () => Promise<ResultIface<ComputerProcessIface[]>>;\n  get: (id: string, bootId: string) => Promise<ResultIface<ProcessHandleIface>>;\n}\n\nexport interface ComputerFilesIface {\n  /** Read a committed sleeping workspace without waking it. Pin subsequent reads by generation. */\n  snapshot: (\n    request: ComputerSnapshotRequestIface,\n  ) => Promise<ResultIface<ComputerSnapshotResponseIface>>;\n  /** Reads the whole file as UTF-8 text, in ranged requests. */\n  read: (path: string, options?: { autoResume?: boolean }) => Promise<ResultIface<string>>;\n  /** Reads the whole file as bytes, in ranged requests. */\n  readBytes: (path: string, options?: { autoResume?: boolean }) => Promise<ResultIface<Uint8Array>>;\n  /** Replaces the file. Data over one chunk is appended in order, so a failure can leave a prefix. */\n  write: (\n    path: string,\n    data: string | Uint8Array,\n  ) => Promise<ResultIface<ComputerFileWriteResultIface>>;\n}\n\nexport enum ComputerTokenScope {\n  /** The public API, within the token's organization or computer. */\n  Api = 'api',\n  /** The computer's HTTP ports through the gateway, never the API. */\n  Http = 'http',\n  Screen = 'screen',\n  ScreenControl = 'screen:control',\n}\n\nexport interface CreateTokenOptsIface {\n  name: string;\n  /** Confines the token to one computer. Without it the token covers the organization. */\n  computerId?: string;\n  /** Omit for a full-access token. */\n  scopes?: ComputerTokenScope[];\n  expiresAt?: Date;\n}\n\nexport interface ComputerTokenIface {\n  id: string;\n  /** Returned once; send as `Authorization: Bearer <token>`. */\n  token: string;\n}\n\nexport interface CreatePreviewTokenOptsIface {\n  name?: string;\n  /** Defaults to one hour from now. */\n  expiresAt?: Date;\n}\n\nexport interface ComputerHandleIface {\n  browserAccess: {\n    open(\n      options: ComputerBrowserAccessOptionsIface,\n    ): Promise<ResultIface<ComputerBrowserAccessIface>>;\n    close(tokenId: string): Promise<ResultIface<{ ok: boolean }>>;\n  };\n  screen: {\n    status: () => Promise<ResultIface<{ available: boolean }>>;\n    open: (\n      options?: ComputerScreenOpenOptionsIface,\n    ) => Promise<ResultIface<ComputerScreenSessionIface>>;\n  };\n  computerUse: {\n    status(): Promise<ResultIface<ComputerUseStatusIface>>;\n    available(): Promise<ResultIface<boolean>>;\n    // A newline-delimited JSON-RPC MCP process. Use write/output/signal as with exec.\n    open(options?: ComputerUseOpenOptsIface): Promise<ResultIface<ProcessHandleIface>>;\n  };\n  id: string;\n  name: string;\n  getInfo: () => ComputerInfoIface;\n  refresh: () => Promise<ResultIface<ComputerInfoIface>>;\n  refreshActivity: () => Promise<ResultIface<ComputerInfoIface>>;\n  exec: (command: string, opts?: ExecProcessOptsIface) => Promise<ResultIface<ProcessHandleIface>>;\n  /**\n   * Runs a command with stdin closed and returns its output and exit in one request. Use\n   * `exec` for a process that reads stdin, needs a terminal, or outlives the call.\n   */\n  run: (command: string, opts?: RunCommandOptsIface) => Promise<ResultIface<ComputerRunIface>>;\n  processes: ComputerProcessesIface;\n  files: ComputerFilesIface;\n  /** `hostname[:port]` from the computer's hostname; port 443 \u2192 bare hostname. Null until the computer has a hostname. */\n  getHost: (port: number) => string | null;\n  /**\n   * Mints a token that opens this computer's HTTP ports and nothing else: the API refuses\n   * it. Send it as `Authorization: Bearer <token>` to a `getHost` URL of a private computer.\n   */\n  createPreviewToken: (\n    opts?: CreatePreviewTokenOptsIface,\n  ) => Promise<ResultIface<ComputerTokenIface>>;\n  pause: () => Promise<ResultIface<ComputerInfoIface>>;\n  resume: () => Promise<ResultIface<ComputerInfoIface>>;\n  start: () => Promise<ResultIface<ComputerInfoIface>>;\n  stop: () => Promise<ResultIface<ComputerInfoIface>>;\n  restart: () => Promise<ResultIface<ComputerInfoIface>>;\n  /** Convenience alias: kill performs the delete lifecycle action. */\n  kill: () => Promise<ResultIface<ComputerInfoIface>>;\n  settings: (patch: ComputerSettingsPatchIface) => Promise<ResultIface<ComputerInfoIface>>;\n}\n\nexport type ComputerConnectTarget = ({ id: string } | { name: string }) & {\n  /**\n   * Resume paused, stopped, or shelved computers before returning a handle.\n   * Defaults to true. Set false for background work that must never wake a VM.\n   */\n  resumeIfNeeded?: boolean;\n};\n\nexport interface ComputerClientIface {\n  stopComputerRetained: (idOrName: string) => Promise<ResultIface<ComputerInfoIface>>;\n  createComputer: (opts: CreateComputerOptsIface) => Promise<ResultIface<ComputerHandleIface>>;\n  connectComputer: (target: ComputerConnectTarget) => Promise<ResultIface<ComputerHandleIface>>;\n  pauseComputer: (idOrName: string) => Promise<ResultIface<ComputerInfoIface>>;\n  resumeComputer: (idOrName: string) => Promise<ResultIface<ComputerInfoIface>>;\n  stopComputer: (\n    idOrName: string,\n    options?: LifecycleActionOptionsIface,\n  ) => Promise<ResultIface<ComputerInfoIface>>;\n  refreshComputerActivity: (idOrName: string) => Promise<ResultIface<ComputerInfoIface>>;\n  listComputers: () => Promise<ResultIface<ComputerInfoIface[]>>;\n  getComputer: (idOrName: string) => Promise<ResultIface<ComputerInfoIface>>;\n  deleteComputer: (idOrName: string) => Promise<ResultIface<ComputerInfoIface>>;\n  /** Registers an image; poll getImage until it is ready, then create from its id. */\n  registerImage: (opts: RegisterImageOptsIface) => Promise<ResultIface<ComputerImageIface>>;\n  getImage: (id: string) => Promise<ResultIface<ComputerImageIface>>;\n  listImages: (opts?: ListImagesOptsIface) => Promise<ResultIface<ComputerImageIface[]>>;\n  /**\n   * API keys: captures a running computer (created with userVolumeGb: null) as a\n   * base; poll getBase until it is ready, then create with its id as baseId.\n   * The computer stops for the capture.\n   */\n  captureComputer: (\n    idOrName: string,\n    options?: { retained?: boolean },\n  ) => Promise<ResultIface<ComputerBaseIface>>;\n  setBaseRetention: (id: string, retained: boolean) => Promise<ResultIface<ComputerBaseIface>>;\n  getBase: (id: string) => Promise<ResultIface<ComputerBaseIface>>;\n  createToken: (opts: CreateTokenOptsIface) => Promise<ResultIface<ComputerTokenIface>>;\n  revokeToken: (id: string) => Promise<ResultIface<void>>;\n  withEphemeralComputer: <T>(\n    opts: CreateComputerOptsIface,\n    fn: (computer: ComputerHandleIface) => Promise<T>,\n  ) => Promise<T>;\n}\n"],
+  "mappings": "AAcO,IAAK,gBAAL,kBAAKA,mBAAL;AACL,EAAAA,8BAAA,aAAU,KAAV;AACA,EAAAA,8BAAA,aAAU,KAAV;AACA,EAAAA,8BAAA,cAAW,KAAX;AACA,EAAAA,8BAAA,aAAU,KAAV;AACA,EAAAA,8BAAA,YAAS,KAAT;AACA,EAAAA,8BAAA,aAAU,KAAV;AACA,EAAAA,8BAAA,cAAW,KAAX;AAEA,EAAAA,8BAAA,WAAQ,KAAR;AACA,EAAAA,8BAAA,aAAU,KAAV;AACA,EAAAA,8BAAA,aAAU,MAAV;AAXU,SAAAA;AAAA,GAAA;AAcL,IAAK,sBAAL,kBAAKC,yBAAL;AACL,EAAAA,0CAAA,UAAO,KAAP;AACA,EAAAA,0CAAA,UAAO,KAAP;AACA,EAAAA,0CAAA,YAAS,KAAT;AAHU,SAAAA;AAAA,GAAA;AAML,IAAK,qBAAL,kBAAKC,wBAAL;AACL,EAAAA,oBAAA,YAAS;AACT,EAAAA,oBAAA,WAAQ;AACR,EAAAA,oBAAA,YAAS;AAHC,SAAAA;AAAA,GAAA;AAML,IAAK,qBAAL,kBAAKC,wBAAL;AACL,EAAAA,oBAAA,aAAU;AACV,EAAAA,oBAAA,cAAW;AACX,EAAAA,oBAAA,WAAQ;AACR,EAAAA,oBAAA,YAAS;AACT,EAAAA,oBAAA,aAAU;AALA,SAAAA;AAAA,GAAA;AAQL,IAAK,sBAAL,kBAAKC,yBAAL;AACL,EAAAA,qBAAA,cAAW;AACX,EAAAA,qBAAA,cAAW;AAFD,SAAAA;AAAA,GAAA;AAKL,IAAK,uBAAL,kBAAKC,0BAAL;AACL,EAAAA,sBAAA,cAAW;AACX,EAAAA,sBAAA,UAAO;AACP,EAAAA,sBAAA,eAAY;AAHF,SAAAA;AAAA,GAAA;AAML,IAAK,oBAAL,kBAAKC,uBAAL;AACL,EAAAA,mBAAA,eAAY;AACZ,EAAAA,mBAAA,WAAQ;AACR,EAAAA,mBAAA,YAAS;AACT,EAAAA,mBAAA,aAAU;AAJA,SAAAA;AAAA,GAAA;AAyUL,IAAK,qBAAL,kBAAKC,wBAAL;AAEL,EAAAA,oBAAA,SAAM;AAEN,EAAAA,oBAAA,UAAO;AACP,EAAAA,oBAAA,YAAS;AACT,EAAAA,oBAAA,mBAAgB;AANN,SAAAA;AAAA,GAAA;",
+  "names": ["ComputerState", "ComputerCommandMode", "ComputerIdlePolicy", "ComputerImageState", "ComputerImageSource", "ComputerEgressPolicy", "ComputerBaseState", "ComputerTokenScope"]
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@finalai/computers",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Client for the Final Computers public API, including files, processes, and exec WebSockets.",
+  "license": "UNLICENSED",
+  "files": [
+    "dist",
+    "README.md",
+    "THIRD_PARTY_NOTICES.md"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/modules/index.d.mts",
+      "import": "./dist/modules/index.mjs",
+      "default": "./dist/modules/index.mjs"
+    },
+    "./package.json": "./package.json",
+    "./transport": {
+      "types": "./dist/modules/transport-api.d.mts",
+      "import": "./dist/modules/transport-api.mjs",
+      "default": "./dist/modules/transport-api.mjs"
+    },
+    "./json": {
+      "types": "./dist/modules/json.d.mts",
+      "import": "./dist/modules/json.mjs",
+      "default": "./dist/modules/json.mjs"
+    },
+    "./shell": {
+      "types": "./dist/modules/shell.d.mts",
+      "import": "./dist/modules/shell.mjs",
+      "default": "./dist/modules/shell.mjs"
+    }
+  },
+  "publishConfig": {
+    "access": "restricted",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "zod": "4.6.5"
+  },
+  "engines": {
+    "node": ">=26"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/final-company/packages-typescript.git",
+    "directory": "packages/@finalai/computers"
+  }
+}