@arker-ai/sdk 0.2.1 → 0.5.1

package/dist/index.d.ts

@@ -1,120 +1,797 @@
+interface components {
+    schemas: {
+        /**
+         * @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: {
+            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` = ran to completion; `exit_code` conveys success (0) or a non-zero program exit (still `completed`). `failed` = the platform could not run/finish the command (worker died, evicted mid-run); `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 */
+            type: "open";
+        };
+        NetworkPolicyBlocked: {
+            /** @constant */
+            type: "blocked";
+        };
+        NetworkPolicyAllow: {
+            /** @constant */
+            type: "allow";
+            allow: string[];
+        };
+        NetworkPolicyBlock: {
+            /** @constant */
+            type: "block";
+            block: string[];
+        };
+        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;
+            /** @description Make the new VM publicly forkable from other orgs. */
+            public?: boolean | null;
+            network?: components["schemas"]["NetworkPolicyInput"] | null;
+            /** @default true */
+            disk?: boolean;
+            vcpu_count?: number | null;
+            memory_mib?: number | null;
+            max_memory_mib?: number | null;
+            disk_mib?: number | null;
+            durable?: boolean | null;
+        };
+        Session: {
+            session_id: string;
+            /** @default 0 */
+            session_idx?: number;
+            state: components["schemas"]["SessionState"];
+            cwd: string;
+            /** @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;
+            /** @description Org that owns this VM. */
+            owner_org_id: string;
+            created_at: string;
+            /** @description VM name, scoped to `owner_org_id`. */
+            name?: 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;
+            /** @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"]["Vm"][];
+            next_cursor?: string | null;
+        };
+        DeleteVmResponse: {
+            deleted: boolean;
+        };
+        DeleteSessionResponse: {
+            deleted: boolean;
+        };
+        RunRequest: {
+            session_id?: string | null;
+            session_idx?: number | null;
+            command: string;
+            /** @default false */
+            background?: boolean;
+            timeout?: number | null;
+            /** @default auto */
+            end_symbol?: string | null;
+            vcpu_count?: number | null;
+            memory_mib?: number | null;
+            disk_mib?: number | null;
+            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;
+            signal?: string | null;
+        };
+        NetworkRequest: {
+            inbound?: components["schemas"]["InboundRequest"] | null;
+        };
+        InboundRequest: {
+            /** @default {} */
+            ports?: {
+                [key: string]: components["schemas"]["InboundPortRequest"];
+            };
+        };
+        InboundPortRequest: {
+            /** @default private */
+            visibility?: string;
+            /** @default http */
+            protocol?: string;
+        };
+        RunResponse: components["schemas"]["CompletedRunResponse"] | components["schemas"]["BackgroundRunResponse"];
+        CompletedRunResponse: {
+            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;
+            dispatch?: string | null;
+        };
+        BackgroundRunResponse: {
+            run_id: string;
+            /** @default [] */
+            tunnels?: components["schemas"]["Tunnel"][];
+        };
+        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. "worker died: <id>"). Distinct from `stderr`, which is the program's own output. */
+            fail_reason?: string | null;
+            stdout: string;
+            stdout_encoding: string;
+            stderr: string;
+            stderr_encoding: string;
+            tunnels: components["schemas"]["Tunnel"][];
+            /** @default 0 */
+            retry_count?: number;
+            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` (e.g. "worker died: <id>"). Distinct from `stderr`, which is the program's own output. */
+            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;
+        };
+        NetworkStatus: {
+            inbound: components["schemas"]["InboundStatus"];
+        };
+        InboundStatus: {
+            ports: {
+                [key: string]: components["schemas"]["InboundPortStatus"];
+            };
+        };
+        InboundPortStatus: {
+            requested: string;
+            observed: string;
+            effective: string;
+            protocol: string;
+            url?: string | null;
+        };
+        Tunnel: {
+            /** @description The VM this tunnel belongs to. Always populated, including when embedded in `Run.tunnels`. */
+            vm_id: string;
+            /** @description Unique-per-VM identifier. */
+            port: number;
+            /** @description The Run that opened this tunnel, if any. Tunnels allocated at fork time have `run_id: null`. */
+            run_id?: string | null;
+            visibility: string;
+            protocol: string;
+            url?: string | null;
+            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;
+        };
+        ListTunnelsResponse: {
+            tunnels: components["schemas"]["Tunnel"][];
+            next_cursor?: string | null;
+        };
+        DeleteTunnelResponse: {
+            deleted: boolean;
+        };
+        CancelRunResponse: {
+            cancelled: boolean;
+        };
+        CreateSessionRequest: {
+            env?: {
+                [key: string]: string;
+            } | null;
+            cwd?: string | null;
+        };
+        ResizeRequest: {
+            vcpu_count?: number | null;
+            memory_mib?: number | null;
+            disk_mib?: number | null;
+        };
+        ResizeResponse: {
+            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;
+            created_at: string;
+            vm_name?: string | null;
+            filesystem_name?: string | null;
+            source_org_id?: string | null;
+            region?: string | null;
+            /** @enum {string|null} */
+            provider?: "aws" | "aws-burst" | null;
+            live?: boolean;
+            live_error?: string;
+            idempotent?: boolean;
+        };
+        ListSyncsResponse: {
+            syncs: components["schemas"]["Sync"][];
+            next_cursor?: string | null;
+        };
+        DeleteSyncResponse: {
+            deleted: boolean;
+        };
+        SyncCreateRequest: {
+            filesystem_id: string;
+            /** @description VM-side path. Returns `ErrorResponse` code `conflict` if a sync already exists at this path. */
+            path?: string;
+        };
+        SyncReadRequest: {
+            /** @constant */
+            op: "read";
+            path: string;
+        };
+        SyncWriteRequest: {
+            /** @constant */
+            op: "write";
+            writes: components["schemas"]["SyncWriteEntry"][];
+        };
+        SyncWriteEntry: components["schemas"]["SyncChunkWrite"] | components["schemas"]["SyncPresignedWriteRequest"] | components["schemas"]["SyncPresignedWriteCommit"];
+        SyncChunkWrite: {
+            path: string;
+            size: number;
+            upload_id: string;
+            content: string;
+            start: number;
+            end: number;
+            sha256?: string | null;
+            /** @default false */
+            is_secret?: boolean;
+        };
+        SyncPresignedWriteRequest: {
+            path: string;
+            size: number;
+            presigned: boolean;
+            /** @default false */
+            is_secret?: boolean;
+        };
+        SyncPresignedWriteCommit: {
+            path: string;
+            size: number;
+            upload_id: string;
+            sha256?: string | null;
+        };
+        SyncReadResponse: components["schemas"]["SyncReadInlineResponse"] | components["schemas"]["SyncReadPresignedResponse"];
+        SyncReadInlineResponse: {
+            path: string;
+            size: number;
+            content: string;
+            encoding: string;
+        };
+        SyncReadPresignedResponse: {
+            path: string;
+            size: number;
+            presigned_url: string;
+            expires_in: number;
+            method: string;
+        };
+        SyncWriteResponse: {
+            results: components["schemas"]["SyncWriteResult"][];
+        };
+        SyncWriteResult: components["schemas"]["SyncChunkWriteResult"] | components["schemas"]["SyncPresignedWriteRequestResult"] | components["schemas"]["SyncCommitWriteResult"];
+        SyncChunkWriteResult: {
+            path: string;
+            size: number;
+            received_bytes: number;
+            ranges: components["schemas"]["SyncByteRange"][];
+            complete: boolean;
+            written: boolean;
+            error?: components["schemas"]["SyncEntryError"] | null;
+        };
+        SyncPresignedWriteRequestResult: {
+            path: string;
+            size: number;
+            presigned_url: string;
+            upload_id: string;
+            expires_in: number;
+            method: string;
+            complete: boolean;
+            written: boolean;
+            error?: components["schemas"]["SyncEntryError"] | null;
+        };
+        SyncCommitWriteResult: {
+            path: string;
+            size: number;
+            complete: boolean;
+            written: boolean;
+            error?: components["schemas"]["SyncEntryError"] | null;
+        };
+        SyncByteRange: {
+            start: number;
+            end: number;
+        };
+        SyncEntryError: {
+            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;
+        };
+    };
+    responses: {
+        /** @description API error. */
+        Error: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["ErrorResponse"];
+            };
+        };
+        /** @description The request is valid, but this backend does not support the requested operation or option. */
+        UnsupportedOperation: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["ErrorResponse"];
+            };
+        };
+    };
+    parameters: {
+        VmId: string;
+        RunId: string;
+        SessionId: string;
+        SyncId: string;
+        TunnelPort: number;
+        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;
+    };
+    requestBodies: never;
+    headers: never;
+    pathItems: never;
+}
+
 /**
- * Arker SDK — TypeScript client.
- *
- * Quickstart:
- *
- *   import { Arker } from "@arker-ai/sdk";
- *   const arker = new Arker({ apiKey: "ark_live_..." });
- *   const vm    = await arker.vm("arkuntu").fork({ name: "hello" });
- *
- *   const result = await vm.run("echo hi");
- *   console.log(new TextDecoder().decode(result.stdout)); // → "hi\n"
- *
- *   await vm.sync.writeFile("/home/user/data.bin", new Uint8Array([1, 2, 3]));
- *   const blob = await vm.sync.readFile("/home/user/data.bin");
- *
- *   const child = await vm.fork({ name: "branch" });
- *   await child.delete();
- *   await vm.delete();
- *
- *   // List your VMs (paginated):
- *   const page = await arker.list({ limit: 10 });
- *   for (const summary of page.items) {
- *     console.log(summary.vm_id, summary.name, summary.created_at);
- *   }
+ * Arker TypeScript SDK.
  *
- * Errors are thrown as `ArkerError(code, message, status)`.
+ * A small wrapper around the VM API. Configure a region for the standard
+ * Arker endpoints, or pass baseUrl directly for internal/dev targets.
  */
-declare const DEFAULT_BASE_URL = "https://aws-burst-us-west-2.arker.ai";
-/** `list` is served from a different host than the rest; used regardless of the client's baseUrl. */
-declare const LIST_BASE_URL = "https://arker.ai";
-/** 1000 pre-forked public VMs (snapshots of `arkuntu`). The SDK picks one
- * at random per `vm("arkuntu").fork()` call so concurrent fork bursts
- * fan out across distinct source state.log keys, avoiding per-key
- * throttling under load. */
-declare const ARKUNTU_POOL: readonly string[];
-/** Source-VM aliases. `arkuntu` resolves to the 1000-VM pool above. */
-declare const SOURCE_ALIASES: Record<string, readonly string[] | string>;
-/** Files above this size go through a direct upload path. */
+
+type ApiSchema<Name extends keyof components["schemas"]> = components["schemas"][Name];
 declare const CHUNK_SIZE: number;
-interface ArkerOptions {
-    apiKey: string;
-    baseUrl?: string;
+/**
+ * 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 {
+    attempts?: number;
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+    jitterMs?: number;
 }
-interface ForkOptions {
-    name?: string;
-    isPublic?: boolean;
+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;
+    retry?: RetryOptions | false;
 }
-interface RunOptions {
-    sessionId?: string | number;
-    timeout?: number;
-}
-interface RunResult {
+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 Session = ApiSchema<"Session">;
+type Vm = ApiSchema<"Vm">;
+type ListVmsResponse = ApiSchema<"ListVmsResponse">;
+type ListSessionsResponse = ApiSchema<"ListSessionsResponse">;
+type DeleteVmResponse = ApiSchema<"DeleteVmResponse">;
+type DeleteSessionResponse = ApiSchema<"DeleteSessionResponse">;
+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 = Partial<Omit<RunRequest, "command">> & {
+    /**
+     * Optional idempotency key for retrying the run. Sent as the
+     * `Idempotency-Key` HTTP header.
+     */
+    idempotencyKey?: string;
+};
+type InboundPortRequest = ApiSchema<"InboundPortRequest">;
+type NetworkRequest = ApiSchema<"NetworkRequest">;
+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 Run = ApiSchema<"Run">;
+type RunSummary = ApiSchema<"RunSummary">;
+type ListRunsResponse = ApiSchema<"ListRunsResponse">;
+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";
+    /** 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;
-    durationMs: number;
-    sessionId: string;
-    cwd: string;
-}
-interface VmSummary {
-    vm_id: string;
-    name: string | null;
-    base_image: string;
-    region: string;
-    /** ISO 8601 UTC. */
-    created_at: string;
-}
-interface VmList {
-    items: VmSummary[];
-    /** Total matching the query, ignoring limit/offset. */
-    total: number;
+    /** System failure explanation when `state` is "failed". Distinct from
+     * `stderr` (the program's own error output); null otherwise. */
+    failReason?: string | null;
 }
-interface ListOptions {
-    limit?: number;
-    offset?: number;
-    q?: string;
-    /** `created_at` | `-created_at` | `region` | `-region`. Default `-created_at`. */
-    sort?: string;
+interface BackgroundRunResult {
+    type: "background";
+    runId: string;
+    /** Lifecycle state — "running". */
+    state: string;
+    tunnels: Tunnel[];
 }
+type RunResult = CompletedRunResult | BackgroundRunResult;
 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 baseUrl;
-    constructor(opts: ArkerOptions);
+    private readonly fetchImpl;
+    private readonly retry;
+    constructor(opts?: ArkerOptions);
+    /**
+     * 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;
+    }>;
+    /** 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 */
-    _request<T = any>(method: string, path: string, body?: unknown, overrideBaseUrl?: string): Promise<T>;
-    /** Open a handle to a VM by ULID *or* template name. No network call. */
-    vm(vmId: string): Computer;
-    /** List VMs in the caller's organization. Always hits `https://arker.ai`. */
-    list(opts?: ListOptions): Promise<VmList>;
+    _fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+    /** @internal */
+    _retryAttempts(): number;
+    /** @internal */
+    _retryDelay(attempt: number): number;
+    /** @internal */
+    _baseUrlFor(ref: string): string;
 }
-declare class Computer {
+interface ListOpts {
+    cursor?: string;
+    limit?: number;
+}
+declare class VM {
     readonly id: string;
-    readonly sync: Sync;
+    readonly baseUrl: string;
     /** @internal */
     readonly _client: Arker;
-    constructor(client: Arker, vmId: string);
-    delete(): Promise<void>;
-    /** Fork this VM. Aliases like `"arkuntu"` resolve client-side. */
-    fork(opts?: ForkOptions): Promise<Computer>;
-    run(command: string, opts?: RunOptions): Promise<RunResult>;
-}
-declare class Sync {
-    /** @internal */
-    readonly _vm: Computer;
-    constructor(vm: Computer);
-    private path;
-    readFile(path: string): Promise<Uint8Array>;
-    writeFile(path: string, data: Uint8Array | string): Promise<void>;
-    private fastPath;
-    private presignedPath;
+    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 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>;
+    /**
+     * 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>;
+    getTunnel(port: number): Promise<Tunnel>;
+    deleteTunnel(port: number): Promise<DeleteTunnelResponse>;
 }
 
-export { ARKUNTU_POOL, Arker, ArkerError, type ArkerOptions, CHUNK_SIZE, Computer, DEFAULT_BASE_URL, type ForkOptions, LIST_BASE_URL, type ListOptions, type RunOptions, type RunResult, SOURCE_ALIASES, Sync, 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 ListRunsResponse, type ListSessionsResponse, type ListSyncsResponse, type ListTunnelsResponse, type ListVmsResponse, type NetworkPolicy, type NetworkPolicyInput, type NetworkRequest, type NetworkStatus, type ResizeRequest, type ResizeResponse, type ResourceKind, type RetryOptions, type Run, type RunInboundPortRequest, 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 TunnelState, VM, type Vm, type VmState };