@arker-ai/sdk 0.3.0 → 0.5.2

package/dist/index.d.ts

@@ -1,15 +1,39 @@
 interface components {
     schemas: {
-        /** @description Standard API error. Backends use code "unsupported_operation" when the request is valid but names an operation or option this backend cannot support. */
+        /**
+         * @description Stable machine-readable error code. `unsupported_operation` means the backend doesn't implement the requested optional feature.
+         * @enum {string}
+         */
+        ErrorCode: "unsupported_operation" | "bad_request" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "payload_too_large" | "not_implemented" | "resource_pressure" | "internal" | "unavailable" | "network_error";
         ErrorResponse: {
-            /**
-             * @description Stable machine-readable error code. "unsupported_operation" means the backend does not implement the requested optional feature.
-             * @example unsupported_operation
-             */
-            code: string;
-            /** @description Human-readable error message. */
+            code: components["schemas"]["ErrorCode"];
             message: string;
         };
+        /**
+         * @description Unified lifecycle state for a VM or a Session. `idle` means no command is currently executing; `running` means a command is in flight.
+         * @enum {string}
+         */
+        VmState: "idle" | "running";
+        SessionState: components["schemas"]["VmState"];
+        /**
+         * @description Lifecycle state for a Run. `running` = command in flight.
+         *     `completed` = the command ran to completion; `exit_code` conveys
+         *     success (0) or a non-zero program exit (a non-zero exit is still
+         *     `completed`). `failed` = the platform could not run or finish the
+         *     command (host died, evicted mid-run, exec error); `fail_reason`
+         *     explains why, distinct from the program's `stderr`. `cancelled` =
+         *     cancelled by the client.
+         * @enum {string}
+         */
+        RunState: "running" | "completed" | "failed" | "cancelled";
+        /**
+         * @description `starting` = backend is allocating the tunnel; `open` = accepting
+         *     connections; `closed` = torn down or never came up.
+         * @enum {string}
+         */
+        TunnelState: "starting" | "open" | "closed";
+        /** @enum {string} */
+        ResourceKind: "cpu" | "memory" | "disk";
         NetworkPolicy: components["schemas"]["NetworkPolicyOpen"] | components["schemas"]["NetworkPolicyBlocked"] | components["schemas"]["NetworkPolicyAllow"] | components["schemas"]["NetworkPolicyBlock"];
         NetworkPolicyOpen: {
             /** @constant */
@@ -31,8 +55,16 @@ interface components {
         };
         NetworkPolicyInput: boolean | string | components["schemas"]["NetworkPolicy"];
         ForkRequest: {
+            /** @description Global VM identifier. Org is inferred from the row. */
+            source_vm_id?: string | null;
+            /** @description VM name within an org. Defaults `source_org_id` to the caller's org. A different org must be either the Arker org (for the public goldens `arkuntu` / `ubuntu`) or one with a `public: true` VM by that name. */
+            source_vm_name?: string | null;
+            /** @description Optional explicit org context for `source_vm_name`. SDK auto-fills the Arker org when forking the public goldens. */
+            source_org_id?: string | null;
+            /** @description Optional name for the new VM, scoped to the caller's org. */
             name?: string | null;
-            image?: string | null;
+            /** @description Make the new VM publicly forkable from other orgs. */
+            public?: boolean | null;
             network?: components["schemas"]["NetworkPolicyInput"] | null;
             /** @default true */
             disk?: boolean;
@@ -40,53 +72,69 @@ interface components {
             memory_mib?: number | null;
             max_memory_mib?: number | null;
             disk_mib?: number | null;
-            /**
-             * @description Request a durable VM. If the underlying host fails mid-run, the run resumes on a healthy host with the VM's filesystem state preserved. Use for long-running or non-idempotent work. Forked children default to non-durable. Backends without durability support return ErrorResponse code "unsupported_operation".
-             * @default false
-             */
             durable?: boolean | null;
+            /** @description Optional VM-scoped tunnel customization. Omitting it allocates an open any-port tunnel where supported. */
+            tunnel?: components["schemas"]["TunnelRequest"] | null;
         };
-        SessionInfo: {
+        Session: {
             session_id: string;
-            state: string;
+            /** @default 0 */
+            session_idx?: number;
+            state: components["schemas"]["SessionState"];
             cwd: string;
-        };
-        ListSessionsResponse: components["schemas"]["SessionInfo"][];
-        GoldenInfo: {
-            vm_id: string;
-            name: string;
-            source_golden: string;
-            memory_mib?: number | null;
-            vcpu_count?: number | null;
-            disk_mib?: number | null;
-        };
-        ListGoldensResponse: {
-            goldens: components["schemas"]["GoldenInfo"][];
-        };
-        VmInfo: {
+            /** @description Optional environment-variable overrides for this session. */
+            env?: {
+                [key: string]: string;
+            } | null;
+            started_at?: string | null;
+            vm_id?: string | null;
+            vm_name?: string | null;
+            source_org_id?: string | null;
+            region?: string | null;
+            /** @enum {string|null} */
+            provider?: "aws" | "aws-burst" | null;
+        };
+        ListSessionsResponse: {
+            sessions: components["schemas"]["Session"][];
+            next_cursor?: string | null;
+        };
+        Vm: {
             vm_id: string;
-            owner_id: string;
+            /** @description Org that owns this VM. */
+            owner_org_id: string;
             created_at: string;
+            /** @description VM name, scoped to `owner_org_id`. */
             name?: string | null;
-            source_golden?: string | null;
-            state: string;
-            last_activity?: string | null;
+            /** @description When `true`, other orgs can fork this VM (but cannot run on it). */
+            public: boolean;
+            /** @description ID of the root (deepest-ancestor) source VM, if this VM was created by a chain of forks. None for VMs forked directly from an image. */
+            root_source_vm_id?: string | null;
+            /** @description Name of the root source VM. Populated together with `root_source_vm_id`. */
+            root_source_vm_name?: string | null;
+            state: components["schemas"]["VmState"];
+            region?: string | null;
+            /** @enum {string|null} */
+            provider?: "aws" | "aws-burst" | null;
+            started_at?: string | null;
             vcpu_count?: number | null;
             memory_mib?: number | null;
             disk_mib?: number | null;
-            sessions: components["schemas"]["SessionInfo"][];
+            /** @description Effective VM fork-time egress policy. */
+            network?: components["schemas"]["NetworkPolicy"];
+            /** @description Hard vCPU ceiling for a fork of this VM (KVM slot count). Requesting more fails the run. */
+            max_vcpus?: number | null;
+            /** @description Hard memory ceiling (MiB) a fork can hotplug up to. */
+            max_memory_mib?: number | null;
+            /** @description Non-hotpluggable base memory (MiB). */
+            min_memory_mib?: number | null;
+            /** @description Worker host that owns this VM. Used by routers to populate caches without a fresh PlanetScale lookup. */
+            worker_id?: string | null;
+            sessions: components["schemas"]["Session"][];
+            tunnels?: components["schemas"]["Tunnel"][];
         };
         ListVmsResponse: {
-            vms: components["schemas"]["VmInfo"][];
-        };
-        ForkVmResponse: {
-            vm_id: string;
-            owner_id: string;
-            created_at: string;
-            sessions: components["schemas"]["SessionInfo"][];
-            ssh_private_key?: string | null;
-            tunnels?: components["schemas"]["RunTunnelStatus"][];
-            network?: components["schemas"]["RunNetworkStatus"] | null;
+            vms: components["schemas"]["Vm"][];
+            next_cursor?: string | null;
         };
         DeleteVmResponse: {
             deleted: boolean;
@@ -94,162 +142,249 @@ interface components {
         DeleteSessionResponse: {
             deleted: boolean;
         };
-        MountRequest: {
-            uri: string;
-            mount_point: string;
-            /** @default dir */
-            format?: string;
-        };
-        /** @description Foreground command execution is the portable baseline. Optional session, background, mount, resource, network, signal, release, and runtime fields may return ErrorResponse code "unsupported_operation" on backends that do not support them. */
         RunRequest: {
-            /** @description Optional persistent session id. Backends without persistent sessions return unsupported_operation when this is requested. */
             session_id?: string | null;
+            session_idx?: number | null;
             command: string;
-            /**
-             * @description Run asynchronously. Backends without background execution return unsupported_operation and must not silently run the command synchronously.
-             * @default false
-             */
+            /** @default false */
             background?: boolean;
             timeout?: number | null;
             /** @default auto */
             end_symbol?: string | null;
-            /**
-             * @description Optional external mounts. Backends without mount support return unsupported_operation when this is non-empty.
-             * @default []
-             */
-            mounts?: components["schemas"]["MountRequest"][];
-            /** @description Optional per-run resource override. Backends without resource override support return unsupported_operation when this is requested. */
             vcpu_count?: number | null;
-            /** @description Optional per-run resource override. Backends without resource override support return unsupported_operation when this is requested. */
             memory_mib?: number | null;
-            /** @description Optional per-run resource override. Backends without resource override support return unsupported_operation when this is requested. */
             disk_mib?: number | null;
-            /** @description Optional network/tunnel request. Backends without networking support return unsupported_operation when this is requested. */
-            network?: components["schemas"]["RunNetworkRequest"] | null;
-            /** @description Optional release selection. Backends without release selection support return unsupported_operation when this is requested. */
+            network?: components["schemas"]["NetworkRequest"] | null;
+            /**
+             * @description Comma-separated list of resources to ensure are
+             *     pre-allocated (warm) before the run starts. Values: `cpu`,
+             *     `memory`, `disk`. Example: `"cpu,memory"`.
+             */
+            acquire?: string | null;
+            /**
+             * @description Comma-separated list of resources to release after the run
+             *     finishes. Values: `cpu`, `memory`, `disk`. `"cpu"` frees
+             *     vCPU but keeps memory hot for the next run on this VM;
+             *     `"cpu,memory,disk"` is a full release (closest to a
+             *     suspend).
+             */
             release?: string | null;
-            /** @description Optional session signal. Backends without signal support return unsupported_operation when this is requested. */
             signal?: string | null;
-            /** @description Optional runtime selection. Backends without runtime selection support return unsupported_operation when this is requested. */
-            runtime?: string | null;
-            /** @description Optional runtime override. Backends without runtime overrides return unsupported_operation when this is requested. */
-            runtime_override?: string | null;
         };
-        RunNetworkRequest: {
-            inbound?: components["schemas"]["RunInboundRequest"] | null;
+        NetworkRequest: {
+            inbound?: components["schemas"]["InboundRequest"] | null;
         };
-        RunInboundRequest: {
+        InboundRequest: {
             /** @default {} */
             ports?: {
-                [key: string]: components["schemas"]["RunInboundPortRequest"];
+                [key: string]: components["schemas"]["InboundPortRequest"];
             };
         };
-        RunInboundPortRequest: {
+        InboundPortRequest: {
             /** @default private */
             visibility?: string;
             /** @default http */
             protocol?: string;
         };
-        /** @description Successful run result. BackgroundRunResponse and PtyRunResponse are returned only by backends that support those modes; unsupported modes return ErrorResponse code "unsupported_operation". */
-        RunResponse: components["schemas"]["CompletedRunResponse"] | components["schemas"]["BackgroundRunResponse"] | components["schemas"]["PtyRunResponse"];
+        RunResponse: components["schemas"]["CompletedRunResponse"] | components["schemas"]["BackgroundRunResponse"];
         CompletedRunResponse: {
+            /** @description The run's own id. Present for executed runs; absent for operation acks (release/signal) with no run record. */
+            run_id?: string | null;
+            /** @description Lifecycle state — "completed" for this shape. Read this (not the variant) for completion, uniformly with the run-status (`Run`) shape. */
+            state?: string;
             stdout: string;
+            /**
+             * @description TODO(encoding-normalize): goal is to always emit utf-8 from
+             *     every source so this field becomes unnecessary. Until then
+             *     the SDK uses it to decode.
+             */
             stdout_encoding: string;
             stderr: string;
             stderr_encoding: string;
             exit_code: number;
-            completed: boolean;
+            dispatch?: string | null;
         };
         BackgroundRunResponse: {
             run_id: string;
-            completed: boolean;
-            /** @default [] */
-            tunnels?: components["schemas"]["RunTunnelStatus"][];
-            network?: components["schemas"]["RunNetworkStatus"] | null;
+            /** @description Lifecycle state — "running" for a backgrounded run. */
+            state?: string;
         };
-        PtyRunResponse: {
-            /** @constant */
-            pty: true;
-            session_id: string;
-            ws_url: string;
-        };
-        RunStatusResponse: {
+        Run: {
             run_id: string;
+            session_id?: string | null;
+            command?: string | null;
+            state: components["schemas"]["RunState"];
+            started_at: string;
+            completed_at?: string | null;
+            exit_code: number | null;
+            /** @description System failure explanation when `state` is `failed` (e.g. "host died:&nbsp;<id>", "evicted mid-run"). Distinct from `stderr`, which is the program's own error output. Null for runs that ran to completion. */
+            fail_reason?: string | null;
             stdout: string;
             stdout_encoding: string;
             stderr: string;
             stderr_encoding: string;
-            exit_code: number | null;
-            completed: boolean;
-            tunnels: components["schemas"]["RunTunnelStatus"][];
-            network?: components["schemas"]["RunNetworkStatus"] | null;
-            /**
-             * @description Number of times this run has been automatically retried after an infrastructure failure. 0 for runs that completed without interruption. Backends without durability support omit this field; clients should treat it as 0 when absent.
-             * @default 0
-             */
+            /** @default 0 */
             retry_count?: number;
-        };
-        RunNetworkStatus: {
-            inbound: components["schemas"]["RunInboundStatus"];
-        };
-        RunInboundStatus: {
+            vm_id?: string | null;
+            vm_name?: string | null;
+            source_org_id?: string | null;
+            region?: string | null;
+            /** @enum {string|null} */
+            provider?: "aws" | "aws-burst" | null;
+        };
+        RunSummary: {
+            run_id: string;
+            session_id?: string | null;
+            command?: string | null;
+            state: components["schemas"]["RunState"];
+            started_at: string;
+            completed_at?: string | null;
+            exit_code: number | null;
+            /** @description System failure explanation when `state` is `failed` — see `Run.fail_reason`. Distinct from the program's `stderr`. */
+            fail_reason?: string | null;
+            vm_id?: string | null;
+            vm_name?: string | null;
+            source_org_id?: string | null;
+            region?: string | null;
+            /** @enum {string|null} */
+            provider?: "aws" | "aws-burst" | null;
+        };
+        ListRunsResponse: {
+            runs: components["schemas"]["RunSummary"][];
+            next_cursor?: string | null;
+        };
+        OrgRunListRow: {
+            /** @enum {string} */
+            source: "cf" | "arkerd";
+            t_ms: number;
+            request_id: string;
+            run_id: string;
+            vm_id: string;
+            session_id: string;
+            region: string;
+            status: number;
+            total_ms: number;
+            queue_ms: number;
+            lambda_call_ms: number;
+            lambda_duration_ms: number;
+            executor_duration_ms: number;
+            executor_kind: string;
+            executor_cpu_ms: number;
+            executor_mem_mb: number;
+            lambda_cpu_ms: number;
+            lambda_mem_mb: number;
+            vm_vcpus: number;
+            vm_memory_mib: number;
+            path: string;
+            method: string;
+            command: string;
+            source_vm_id: string;
+            exit_code: number | null;
+            endpoint: string;
+            api_key_prefix: string;
+            body_bytes_in: number;
+            body_bytes_out: number;
+            body_in: string;
+            body_out: string;
+        };
+        ListOrgRunsResponse: {
+            since: number;
+            until: number;
+            limit: number;
+            offset: number;
+            lite: boolean;
+            rows: components["schemas"]["OrgRunListRow"][];
+        };
+        NetworkStatus: {
+            inbound: components["schemas"]["InboundStatus"];
+        };
+        InboundStatus: {
             ports: {
-                [key: string]: components["schemas"]["RunInboundPortStatus"];
+                [key: string]: components["schemas"]["InboundPortStatus"];
             };
         };
-        RunInboundPortStatus: {
+        InboundPortStatus: {
             requested: string;
             observed: string;
             effective: string;
             protocol: string;
             url?: string | null;
         };
-        RunTunnelStatus: {
-            /** @default  */
-            run_id?: string;
+        Tunnel: {
+            /** @description The VM this tunnel belongs to. Always populated so flat tunnel listings work without restructuring. */
+            vm_id: string;
+            /** @description Unique-per-VM identifier. */
             port: number;
+            /** @description The Run that opened this tunnel, if any. VM-scoped tunnels created at fork time or via `POST /vms/{id}/tunnels` have `run_id: null`. */
+            run_id?: string | null;
             visibility: string;
             protocol: string;
             url?: string | null;
-            status: string;
+            state: components["schemas"]["TunnelState"];
             message?: string | null;
+            started_at?: string | null;
+            vm_name?: string | null;
+            source_org_id?: string | null;
+            region?: string | null;
+            /** @enum {string|null} */
+            provider?: "aws" | "aws-burst" | null;
+            /** @description Recoverable tunnel identity embedded in URLs (`p{port}-{key}`). Not a secret. Present on VM-scoped tunnel responses. */
+            tunnel_key?: string | null;
+            /**
+             * @description `open` or `authenticated` for VM-scoped tunnels.
+             * @enum {string|null}
+             */
+            auth_mode?: "open" | "authenticated" | null;
+            /** @description One-time bearer secret returned only when allocating an authenticated tunnel; never echoed on listings. */
+            auth_token?: string | null;
+        };
+        ListTunnelsResponse: {
+            tunnels: components["schemas"]["Tunnel"][];
+            next_cursor?: string | null;
+        };
+        DeleteTunnelResponse: {
+            deleted: boolean;
         };
         CancelRunResponse: {
             cancelled: boolean;
         };
-        /** @description Create a persistent session. Backends without persistent sessions return unsupported_operation. */
         CreateSessionRequest: {
             env?: {
                 [key: string]: string;
             } | null;
             cwd?: string | null;
         };
-        /** @description Resize a PTY session. Backends without PTY sessions return unsupported_operation. */
-        ResizePtyRequest: {
-            cols: number;
-            rows: number;
-        };
-        ResizePtyResponse: {
-            resized: boolean;
-        };
-        /** @description Resize VM resources. Backends without VM resize support return unsupported_operation. */
         ResizeRequest: {
             vcpu_count?: number | null;
             memory_mib?: number | null;
             disk_mib?: number | null;
         };
         ResizeResponse: {
-            ok: boolean;
+            resized: boolean;
+        };
+        Sync: {
+            sync_id: string;
+            vm_id: string;
+            filesystem_id: string;
+            /** @description VM-side path where the filesystem is mounted. Same field name as used by `SyncReadRequest.path`. */
+            path: string;
+            region?: string | null;
+        };
+        ListSyncsResponse: {
+            syncs: components["schemas"]["Sync"][];
+            next_cursor?: string | null;
+        };
+        DeleteSyncResponse: {
+            deleted: boolean;
+        };
+        SyncCreateRequest: {
+            filesystem_id: string;
+            path?: string;
         };
-        SyncRequest: components["schemas"]["SyncReadRequest"] | components["schemas"]["SyncWriteRequest"];
         SyncReadRequest: {
-            /** @constant */
-            op: "read";
             path: string;
         };
         SyncWriteRequest: {
-            /** @constant */
-            op: "write";
             writes: components["schemas"]["SyncWriteEntry"][];
         };
         SyncWriteEntry: components["schemas"]["SyncChunkWrite"] | components["schemas"]["SyncPresignedWriteRequest"] | components["schemas"]["SyncPresignedWriteCommit"];
@@ -277,21 +412,14 @@ interface components {
             upload_id: string;
             sha256?: string | null;
         };
-        SyncResponse: components["schemas"]["SyncReadResponse"] | components["schemas"]["SyncWriteResponse"];
         SyncReadResponse: components["schemas"]["SyncReadInlineResponse"] | components["schemas"]["SyncReadPresignedResponse"];
         SyncReadInlineResponse: {
-            ok: boolean;
-            /** @constant */
-            op: "read";
             path: string;
             size: number;
             content: string;
             encoding: string;
         };
         SyncReadPresignedResponse: {
-            ok: boolean;
-            /** @constant */
-            op: "read";
             path: string;
             size: number;
             presigned_url: string;
@@ -299,9 +427,6 @@ interface components {
             method: string;
         };
         SyncWriteResponse: {
-            ok: boolean;
-            /** @constant */
-            op: "write";
             results: components["schemas"]["SyncWriteResult"][];
         };
         SyncWriteResult: components["schemas"]["SyncChunkWriteResult"] | components["schemas"]["SyncPresignedWriteRequestResult"] | components["schemas"]["SyncCommitWriteResult"];
@@ -340,6 +465,43 @@ interface components {
             code: string;
             message: string;
         };
+        Filesystem: {
+            filesystem_id: string;
+            name: string;
+            owner_org_id: string;
+            created_at: string;
+            size_bytes?: number | null;
+            /** @default us-west-2 */
+            region?: string | null;
+            /**
+             * @default aws
+             * @enum {string|null}
+             */
+            provider?: "aws" | "aws-burst" | null;
+        };
+        ListFilesystemsResponse: {
+            filesystems: components["schemas"]["Filesystem"][];
+            next_cursor?: string | null;
+        };
+        DeleteFilesystemResponse: {
+            deleted: boolean;
+        };
+        FilesystemCreateRequest: {
+            name: string;
+        };
+        TunnelRequest: {
+            /**
+             * @description Allowed VM ports for this tunnel. Omitted, null, or empty means any port.
+             * @default []
+             */
+            ports?: number[] | null;
+            /**
+             * @description `open` allows unauthenticated tunnel requests. `authenticated` returns a one-time bearer `auth_token` and requires it on tunnel requests.
+             * @default open
+             * @enum {string|null}
+             */
+            auth_mode?: "open" | "authenticated" | null;
+        };
     };
     responses: {
         /** @description API error. */
@@ -351,7 +513,7 @@ interface components {
                 "application/json": components["schemas"]["ErrorResponse"];
             };
         };
-        /** @description The request is valid, but this backend does not support the requested operation or option. The response body uses ErrorResponse with code "unsupported_operation". */
+        /** @description The request is valid, but this backend does not support the requested operation or option. */
         UnsupportedOperation: {
             headers: {
                 [name: string]: unknown;
@@ -365,8 +527,14 @@ interface components {
         VmId: string;
         RunId: string;
         SessionId: string;
-        /** @description Optional idempotency key for safe retries of POST /v1/vms/{id}/run. A retry with the same key and the same request returns the original run. A different request under the same key returns ErrorResponse code "conflict" with the original run_id. Keys expire 24h after the run completes. */
-        IdempotencyKey: string;
+        SyncId: string;
+        FilesystemId: string;
+        /** @description Opaque pagination cursor returned by the previous page's `next_cursor`. */
+        Cursor: string | null;
+        /** @description Max items per page. Backend caps may apply. */
+        Limit: number;
+        /** @description Recoverable tunnel identity returned as `Tunnel.tunnel_key` and embedded in tunnel URLs. */
+        TunnelKey: string;
     };
     requestBodies: never;
     headers: never;
@@ -382,6 +550,14 @@ interface components {
 
 type ApiSchema<Name extends keyof components["schemas"]> = components["schemas"][Name];
 declare const CHUNK_SIZE: number;
+/**
+ * Org id for the "Arker" org — the org that owns the public golden VMs
+ * (`arkuntu`, `ubuntu`, `ubuntu-full`, `ubuntu-py-repl`, …). Pass it as
+ * `sourceOrgId` to fork a public golden:
+ *
+ *     arker.fork({ sourceVmName: "ubuntu-full", sourceOrgId: ARKER_ORG_ID })
+ */
+declare const ARKER_ORG_ID = "ArkerHQ";
 type FetchLike = typeof fetch;
 type HttpMethod = "GET" | "POST" | "DELETE";
 interface RetryOptions {
@@ -392,107 +568,235 @@ interface RetryOptions {
 }
 interface ArkerOptions {
     apiKey?: string;
+    /** Region (e.g. `"us-west-2"`). Combined with `provider` to build the
+     * compute endpoint. Back-compat: accepts the legacy combined form
+     * `"aws-us-west-2"`. */
+    region?: string;
+    /** Provider for compute calls. Defaults to `"aws"` (arkerd-managed
+     * VMs). Use `"aws-burst"` to target the Lambda burst backend
+     * directly. Has no effect on the burst-classified routing — a fork
+     * of `arkuntu` in the Arker org still goes to burst regardless. */
+    provider?: "aws" | "aws-burst";
+    /** Override the compute base URL (e.g. for internal / dev targets).
+     * If set, `provider` + `region` are ignored for compute. */
     baseUrl?: string;
+    /** Override the burst compute base URL. */
     burstBaseUrl?: string;
+    /** Override the control-plane URL — the CF Worker that owns
+     * administrative endpoints like `GET /v1/vms` (cross-provider list)
+     * and `/v1/filesystems`. Default `https://arker.ai/api`. */
+    controlBaseUrl?: string;
     fetch?: FetchLike;
-    region?: string;
     retry?: RetryOptions | false;
 }
+type VmState = ApiSchema<"VmState">;
+type SessionState = ApiSchema<"SessionState">;
+type RunState = ApiSchema<"RunState">;
+type TunnelState = ApiSchema<"TunnelState">;
+type ResourceKind = ApiSchema<"ResourceKind">;
+type ErrorCode = ApiSchema<"ErrorCode">;
 type NetworkPolicy = ApiSchema<"NetworkPolicy">;
 type NetworkPolicyInput = ApiSchema<"NetworkPolicyInput">;
 type ForkRequest = ApiSchema<"ForkRequest">;
 type ForkOptions = ForkRequest;
-type SessionInfo = ApiSchema<"SessionInfo">;
-type GoldenInfo = ApiSchema<"GoldenInfo">;
-type ListGoldensResponse = ApiSchema<"ListGoldensResponse">;
-type VmInfo = ApiSchema<"VmInfo">;
+type Session = ApiSchema<"Session">;
+type Vm = ApiSchema<"Vm">;
 type ListVmsResponse = ApiSchema<"ListVmsResponse">;
 type ListSessionsResponse = ApiSchema<"ListSessionsResponse">;
-type VmSummary = VmInfo;
-type VmList = ListVmsResponse;
-type ForkVmResponse = ApiSchema<"ForkVmResponse">;
 type DeleteVmResponse = ApiSchema<"DeleteVmResponse">;
 type DeleteSessionResponse = ApiSchema<"DeleteSessionResponse">;
-type MountRequest = ApiSchema<"MountRequest">;
+type Filesystem = ApiSchema<"Filesystem">;
+type ListFilesystemsResponse = ApiSchema<"ListFilesystemsResponse">;
+type DeleteFilesystemResponse = ApiSchema<"DeleteFilesystemResponse">;
+type FilesystemCreateRequest = ApiSchema<"FilesystemCreateRequest">;
+type Sync = ApiSchema<"Sync">;
+type ListSyncsResponse = ApiSchema<"ListSyncsResponse">;
+type DeleteSyncResponse = ApiSchema<"DeleteSyncResponse">;
+type SyncCreateRequest = ApiSchema<"SyncCreateRequest">;
+type SyncReadRequest = ApiSchema<"SyncReadRequest">;
+type SyncWriteRequest = ApiSchema<"SyncWriteRequest">;
+type SyncReadResponse = ApiSchema<"SyncReadResponse">;
+type SyncReadInlineResponse = ApiSchema<"SyncReadInlineResponse">;
+type SyncReadPresignedResponse = ApiSchema<"SyncReadPresignedResponse">;
+type SyncWriteResponse = ApiSchema<"SyncWriteResponse">;
+type SyncWriteResult = ApiSchema<"SyncWriteResult">;
+type SyncChunkWriteResult = ApiSchema<"SyncChunkWriteResult">;
+type SyncPresignedWriteRequestResult = ApiSchema<"SyncPresignedWriteRequestResult">;
+type SyncCommitWriteResult = ApiSchema<"SyncCommitWriteResult">;
+type SyncByteRange = ApiSchema<"SyncByteRange">;
 type RunRequest = ApiSchema<"RunRequest">;
-type RunOptions = Omit<RunRequest, "command"> & {
+type RunOptions = Partial<Omit<RunRequest, "command">> & {
     /**
-     * Optional idempotency key for retrying POST /v1/vms/{id}/run.
-     * Sent as the `Idempotency-Key` HTTP header. Retries with the same
-     * key and the same semantic request return the original run; a
-     * different semantic request under the same key returns
-     * ArkerError code "conflict" with the original run_id.
+     * Optional idempotency key for retrying the run. Sent as the
+     * `Idempotency-Key` HTTP header.
      */
     idempotencyKey?: string;
 };
-type RunInboundPortRequest = ApiSchema<"RunInboundPortRequest">;
-type RunNetworkRequest = ApiSchema<"RunNetworkRequest">;
-type RunTunnelStatus = ApiSchema<"RunTunnelStatus">;
-type RunNetworkStatus = ApiSchema<"RunNetworkStatus">;
+type InboundPortRequest = ApiSchema<"InboundPortRequest">;
+type NetworkRequest = ApiSchema<"NetworkRequest">;
+type TunnelRequest = ApiSchema<"TunnelRequest">;
+type Tunnel = ApiSchema<"Tunnel">;
+type ListTunnelsResponse = ApiSchema<"ListTunnelsResponse">;
+type DeleteTunnelResponse = ApiSchema<"DeleteTunnelResponse">;
+type NetworkStatus = ApiSchema<"NetworkStatus">;
 type RunResponse = ApiSchema<"RunResponse">;
 type CompletedRunResponse = ApiSchema<"CompletedRunResponse">;
 type BackgroundRunResponse = ApiSchema<"BackgroundRunResponse">;
-type PtyRunResponse = ApiSchema<"PtyRunResponse">;
-type RawRunResponse = RunResponse;
+type Run = ApiSchema<"Run">;
+type RunSummary = ApiSchema<"RunSummary">;
+type ListRunsResponse = ApiSchema<"ListRunsResponse">;
+type OrgRunListRow = ApiSchema<"OrgRunListRow">;
+type ListOrgRunsResponse = ApiSchema<"ListOrgRunsResponse">;
+type RunListRow = OrgRunListRow;
+type CancelRunResponse = ApiSchema<"CancelRunResponse">;
+type CreateSessionRequest = ApiSchema<"CreateSessionRequest">;
+type ResizeRequest = ApiSchema<"ResizeRequest">;
+type ResizeResponse = ApiSchema<"ResizeResponse">;
+type ErrorResponse = ApiSchema<"ErrorResponse">;
+/** @deprecated Use `Session`. */
+type SessionInfo = Session;
+/** @deprecated Use `Run`. */
+type RunStatusResponse = Run;
+/** @deprecated Use `NetworkRequest`. */
+type RunNetworkRequest = NetworkRequest;
+/** @deprecated Use `NetworkStatus`. */
+type RunNetworkStatus = NetworkStatus;
+/** @deprecated Use `InboundPortRequest`. */
+type RunInboundPortRequest = InboundPortRequest;
+/** @deprecated Use `Tunnel`. */
+type RunTunnelStatus = Tunnel;
 interface CompletedRunResult {
     type: "completed";
-    completed: true;
+    /** The run's own id. Present for executed runs; absent for operation acks. */
+    runId?: string;
+    /** Lifecycle state — "completed" or "failed". Mirrors the run-status (`Run`) shape. */
+    state: string;
     stdout: Uint8Array;
     stdoutEncoding: string;
     stderr: Uint8Array;
     stderrEncoding: string;
     exitCode: number;
+    /** System failure explanation when `state` is "failed". Distinct from
+     * `stderr` (the program's own error output); null otherwise. */
+    failReason?: string | null;
 }
 interface BackgroundRunResult {
     type: "background";
-    completed: boolean;
     runId: string;
-    tunnels: RunTunnelStatus[];
-    network?: RunNetworkStatus | null;
+    /** Lifecycle state — "running". */
+    state: string;
 }
-interface PtyRunResult {
-    type: "pty";
-    pty: true;
-    sessionId: string;
-    wsUrl: string;
+type RunResult = CompletedRunResult | BackgroundRunResult;
+interface ListOrgRunsOptions {
+    since?: number;
+    until?: number;
+    vm?: string;
+    vmIds?: string[];
+    region?: string;
+    provider?: "aws" | "aws-burst";
+    source?: "cf" | "arkerd";
+    search?: string;
+    limit?: number;
+    offset?: number;
+    lite?: boolean;
+    runtime?: string;
+    endpoint?: "run" | "fork" | "sync";
+    actions?: string[];
+    status?: string[];
+    statusMin?: number;
+    statusMax?: number;
+    sort?: "when" | "status" | "path" | "total" | "queue" | "your_code" | "runtime";
+    dir?: "asc" | "desc";
 }
-type RunResult = CompletedRunResult | BackgroundRunResult | PtyRunResult;
-type RunStatusResponse = ApiSchema<"RunStatusResponse">;
-type CancelRunResponse = ApiSchema<"CancelRunResponse">;
-type CreateSessionRequest = ApiSchema<"CreateSessionRequest">;
-type ResizePtyRequest = ApiSchema<"ResizePtyRequest">;
-type ResizePtyResponse = ApiSchema<"ResizePtyResponse">;
-type ResizeRequest = ApiSchema<"ResizeRequest">;
-type ResizeResponse = ApiSchema<"ResizeResponse">;
-type SyncRequest = ApiSchema<"SyncRequest">;
-type SyncResponse = ApiSchema<"SyncResponse">;
-type SyncReadResponse = ApiSchema<"SyncReadResponse">;
-type SyncReadInlineResponse = ApiSchema<"SyncReadInlineResponse">;
-type SyncReadPresignedResponse = ApiSchema<"SyncReadPresignedResponse">;
-type SyncByteRange = ApiSchema<"SyncByteRange">;
-type ErrorResponse = ApiSchema<"ErrorResponse">;
-type SyncChunkWriteResult = ApiSchema<"SyncChunkWriteResult">;
-type SyncPresignedWriteRequestResult = ApiSchema<"SyncPresignedWriteRequestResult">;
-type SyncCommitWriteResult = ApiSchema<"SyncCommitWriteResult">;
-type SyncWriteResult = ApiSchema<"SyncWriteResult">;
-type SyncWriteResponse = ApiSchema<"SyncWriteResponse">;
 declare class ArkerError extends Error {
     readonly code: string;
     readonly status: number;
     constructor(code: string, message: string, status: number);
 }
+/** Source for `Arker.fork()`. Exactly one of `sourceVmId` or
+ * `sourceVmName` must be set. When `sourceVmName` is set,
+ * `sourceOrgId` selects which org to look the name up in (defaults
+ * server-side to the caller's org; pass `ARKER_ORG_ID` to fork the
+ * public goldens like `"arkuntu"` / `"ubuntu"`).
+ *
+ * Distinct from the new VM's `name`, which is the *destination* name. */
+interface ForkSource {
+    sourceVmId?: string;
+    sourceVmName?: string;
+    sourceOrgId?: string;
+}
 declare class Arker {
+    /** Compute base URL for `provider` + `region` — used for fork/run/
+     * per-VM ops. SDK calls go straight to this host, skipping the CF
+     * Worker control plane. */
     readonly baseUrl: string;
+    /** Compute base URL for the burst provider in this region. */
     readonly burstBaseUrl?: string;
+    /** CF Worker control-plane URL — used for cross-cutting admin calls
+     * like list-VMs and filesystems. */
+    readonly controlBaseUrl: string;
     readonly region?: string;
+    readonly provider: "aws" | "aws-burst";
     private readonly apiKey;
     private readonly fetchImpl;
     private readonly retry;
     constructor(opts?: ArkerOptions);
-    vm(vmId: string): Computer;
-    goldens(): Promise<ListGoldensResponse>;
-    list(): Promise<ListVmsResponse>;
-    get(vmId: string): Promise<VmInfo>;
+    /**
+     * Address an existing VM. Doesn't make any network calls; returns a
+     * lightweight handle.
+     */
+    vm(vmId: string): VM;
+    /**
+     * Create a new VM by forking from a source.
+     *
+     *     fork("ubuntu-full")                       // public golden by name
+     *     fork("base")                              // a VM by name in your org
+     *     fork(vm)                                  // an existing VM (uses its id)
+     *     fork({ sourceVmId: "vm_abc..." })
+     *     fork({ sourceVmName: "base", sourceOrgId: "org_..." })
+     *
+     * The source can be a name string, a `VM` handle, or a `ForkSource`
+     * object. `sourceOrgId` defaults to the Arker org when `sourceVmName`
+     * is a known public golden, otherwise to your own org; an explicit
+     * value always wins, and it's irrelevant when forking by id. Forking a
+     * VM in another org requires that VM to be `public: true`. The new VM's
+     * name (in your org) is passed as `name`. When the source is a name or
+     * `VM`, extra fork options go in the second `opts` argument.
+     */
+    fork(source: string | VM | (ForkSource & Partial<Omit<ForkRequest, "source_vm_id" | "source_vm_name" | "source_org_id">>), opts?: Partial<Omit<ForkRequest, "source_vm_id" | "source_vm_name" | "source_org_id">>): Promise<VM>;
+    /**
+     * List VMs visible to the authenticated caller. **Admin call** —
+     * goes through the control plane (`controlBaseUrl`) so it can
+     * aggregate across providers and regions. Pass `?provider=` /
+     * `?region=` to narrow.
+     */
+    listVms(opts?: ListOpts & {
+        region?: string;
+        provider?: "aws" | "aws-burst";
+        state?: VmState;
+        sourceOrgId?: string;
+        startedAfter?: string;
+        startedBefore?: string;
+    }): Promise<{
+        vms: VM[];
+        nextCursor: string | null;
+    }>;
+    /**
+     * List run activity visible to the authenticated caller across VMs,
+     * providers, and regions. Admin call — routed through the control plane.
+     */
+    listRuns(opts?: ListOrgRunsOptions): Promise<ListOrgRunsResponse>;
+    /** Compute call — goes direct to the backend hosting this VM (no
+     * control-plane hop). Returns a fully-populated VM handle. */
+    getVm(vmId: string): Promise<VM>;
+    listFilesystems(opts?: ListOpts & {
+        namePrefix?: string;
+    }): Promise<ListFilesystemsResponse>;
+    createFilesystem(request: {
+        name: string;
+    }): Promise<Filesystem>;
+    getFilesystem(filesystemId: string): Promise<Filesystem>;
+    deleteFilesystem(filesystemId: string): Promise<DeleteFilesystemResponse>;
     /** @internal */
     _request<T>(method: HttpMethod, path: string, body?: unknown, baseUrl?: string, extraHeaders?: Record<string, string | undefined>): Promise<T>;
     /** @internal */
@@ -504,30 +808,94 @@ declare class Arker {
     /** @internal */
     _baseUrlFor(ref: string): string;
 }
-declare class Computer {
+interface ListOpts {
+    cursor?: string;
+    limit?: number;
+}
+declare class VM {
     readonly id: string;
     readonly baseUrl: string;
-    readonly sync: Sync;
     /** @internal */
     readonly _client: Arker;
-    constructor(client: Arker, vmId: string, baseUrl?: string);
-    fork(request?: ForkOptions): Promise<Computer>;
+    readonly vm_id?: string;
+    readonly name?: string | null;
+    readonly state?: VmState;
+    readonly owner_org_id?: string;
+    readonly created_at?: string;
+    readonly public?: boolean;
+    readonly region?: string | null;
+    readonly provider?: string | null;
+    readonly vcpu_count?: number | null;
+    readonly memory_mib?: number | null;
+    readonly disk_mib?: number | null;
+    readonly network?: NetworkPolicy;
+    readonly max_vcpus?: number | null;
+    readonly max_memory_mib?: number | null;
+    readonly min_memory_mib?: number | null;
+    readonly started_at?: string | null;
+    readonly root_source_vm_id?: string | null;
+    readonly root_source_vm_name?: string | null;
+    readonly worker_id?: string | null;
+    readonly sessions?: Session[];
+    readonly tunnels?: Tunnel[];
+    constructor(client: Arker, vmId: string, baseUrl?: string, data?: Vm);
+    /** Re-fetch this VM and return a fresh, fully-populated handle. */
+    refresh(): Promise<VM>;
+    /**
+     * @deprecated Use `Arker.fork({ sourceVmId: this.id, ... })`.
+     * Kept for back-compat with older user code that called `.fork()` on
+     * a VM instance.
+     */
+    fork(request?: Partial<ForkRequest>): Promise<VM>;
     run(command: string, options?: RunOptions): Promise<RunResult>;
-    runStatus(runId: string): Promise<RunStatusResponse>;
-    cancelRun(runId: string): Promise<CancelRunResponse>;
-    delete(): Promise<DeleteVmResponse>;
-}
-declare class Sync {
-    /** @internal */
-    readonly _vm: Computer;
-    constructor(vm: Computer);
-    readFile(path: string): Promise<Uint8Array>;
-    writeFile(path: string, data: Uint8Array | string): Promise<void>;
-    private path;
-    private writeInline;
-    private writePresigned;
+    /**
+     * Read or write a file in this VM over `POST /v1/vms/{id}/sync`.
+     * Omit `data` to read; pass `data` (string or bytes) to write. The
+     * client picks inline transfer for small files and presigned uploads
+     * for large ones automatically.
+     *
+     *     const bytes = await vm.sync("/home/user/out.txt");   // read
+     *     await vm.sync("/home/user/in.txt", "hello\n");       // write
+     *
+     * To mount a standalone filesystem into the VM, use `vm.syncs.create`.
+     */
+    sync(path: string): Promise<Uint8Array>;
+    sync(path: string, data: Uint8Array | string): Promise<void>;
+    private syncRead;
+    private syncWriteInline;
+    private syncWritePresigned;
     private putPresigned;
     private sendOneWrite;
+    resize(request: ResizeRequest): Promise<ResizeResponse>;
+    delete(): Promise<DeleteVmResponse>;
+    listSyncs(opts?: ListOpts & {
+        filesystemId?: string;
+    }): Promise<ListSyncsResponse>;
+    createSync(request: {
+        filesystemId: string;
+        path?: string;
+    }): Promise<Sync>;
+    deleteSync(syncId: string): Promise<DeleteSyncResponse>;
+    listRuns(opts?: ListOpts & {
+        state?: RunState;
+        startedAfter?: string;
+        startedBefore?: string;
+        completedAfter?: string;
+    }): Promise<ListRunsResponse>;
+    getRun(runId: string): Promise<Run>;
+    cancelRun(runId: string): Promise<CancelRunResponse>;
+    listSessions(opts?: ListOpts & {
+        state?: SessionState;
+    }): Promise<ListSessionsResponse>;
+    createSession(request?: CreateSessionRequest): Promise<Session>;
+    getSession(sessionId: string): Promise<Session>;
+    deleteSession(sessionId: string): Promise<DeleteSessionResponse>;
+    listTunnels(opts?: ListOpts & {
+        state?: TunnelState;
+    }): Promise<ListTunnelsResponse>;
+    createTunnel(request?: TunnelRequest): Promise<Tunnel>;
+    getTunnel(key: string): Promise<Tunnel>;
+    deleteTunnel(key: string): Promise<DeleteTunnelResponse>;
 }
 
-export { Arker, ArkerError, type ArkerOptions, type BackgroundRunResponse, type BackgroundRunResult, CHUNK_SIZE, type CancelRunResponse, type CompletedRunResponse, type CompletedRunResult, Computer, type CreateSessionRequest, type DeleteSessionResponse, type DeleteVmResponse, type ErrorResponse, type ForkOptions, type ForkRequest, type ForkVmResponse, type GoldenInfo, type ListGoldensResponse, type ListSessionsResponse, type ListVmsResponse, type MountRequest, type NetworkPolicy, type NetworkPolicyInput, type PtyRunResponse, type PtyRunResult, type RawRunResponse, type ResizePtyRequest, type ResizePtyResponse, type ResizeRequest, type ResizeResponse, type RetryOptions, type RunInboundPortRequest, type RunNetworkRequest, type RunNetworkStatus, type RunOptions, type RunRequest, type RunResponse, type RunResult, type RunStatusResponse, type RunTunnelStatus, type SessionInfo, Sync, type SyncByteRange, type SyncChunkWriteResult, type SyncCommitWriteResult, type SyncPresignedWriteRequestResult, type SyncReadInlineResponse, type SyncReadPresignedResponse, type SyncReadResponse, type SyncRequest, type SyncResponse, type SyncWriteResponse, type SyncWriteResult, type VmInfo, type VmList, type VmSummary };
+export { ARKER_ORG_ID, Arker, ArkerError, type ArkerOptions, type BackgroundRunResponse, type BackgroundRunResult, CHUNK_SIZE, type CancelRunResponse, type CompletedRunResponse, type CompletedRunResult, type CreateSessionRequest, type DeleteFilesystemResponse, type DeleteSessionResponse, type DeleteSyncResponse, type DeleteTunnelResponse, type DeleteVmResponse, type ErrorCode, type ErrorResponse, type Filesystem, type FilesystemCreateRequest, type ForkOptions, type ForkRequest, type ForkSource, type InboundPortRequest, type ListFilesystemsResponse, type ListOpts, type ListOrgRunsOptions, type ListOrgRunsResponse, type ListRunsResponse, type ListSessionsResponse, type ListSyncsResponse, type ListTunnelsResponse, type ListVmsResponse, type NetworkPolicy, type NetworkPolicyInput, type NetworkRequest, type NetworkStatus, type OrgRunListRow, type ResizeRequest, type ResizeResponse, type ResourceKind, type RetryOptions, type Run, type RunInboundPortRequest, type RunListRow, type RunNetworkRequest, type RunNetworkStatus, type RunOptions, type RunRequest, type RunResponse, type RunResult, type RunState, type RunStatusResponse, type RunSummary, type RunTunnelStatus, type Session, type SessionInfo, type SessionState, type Sync, type SyncByteRange, type SyncChunkWriteResult, type SyncCommitWriteResult, type SyncCreateRequest, type SyncPresignedWriteRequestResult, type SyncReadInlineResponse, type SyncReadPresignedResponse, type SyncReadRequest, type SyncReadResponse, type SyncWriteRequest, type SyncWriteResponse, type SyncWriteResult, type Tunnel, type TunnelRequest, type TunnelState, VM, type Vm, type VmState };