@kosa8/sdk 0.1.0 → 0.3.0

package/dist/index.d.ts

@@ -89,6 +89,24 @@ interface Sandbox {
     ip?: string;
     labels?: Record<string, string>;
     broker?: BrokerInfo;
+    /** When it stops or is deleted by itself (pkg/sandbox Lifecycle). */
+    lifecycle?: Lifecycle;
+    /** When it last stopped (RFC 3339). */
+    stopped_at?: string;
+}
+/**
+ * When a sandbox stops or goes away by itself (pkg/sandbox Lifecycle).
+ * A field left out (or 0) is off.
+ */
+interface Lifecycle {
+    /** Stop after this many minutes without use. */
+    auto_stop_min?: number;
+    /** Delete once it has been stopped this many minutes. */
+    auto_delete_min?: number;
+    /** Stop this many minutes after it was created, in use or not. */
+    ttl_min?: number;
+    /** Delete instead of stopping, disk and all. */
+    ephemeral?: boolean;
 }
 /** A saved sandbox state (pkg/sandbox Snapshot). */
 interface Snapshot {
@@ -257,6 +275,124 @@ interface ExploreResult {
     winner: string;
     removed: number;
 }
+/** A file a code run produced: today, a chart as a PNG. */
+interface CodeArtifact {
+    /** Media type, e.g. `image/png`. */
+    type: string;
+    name: string;
+    data: Buffer;
+}
+/** The outcome of `runCode`. A non-zero `exitCode` is a result, not an error. */
+interface CodeResult {
+    /** `exitCode === 0` and not timed out. */
+    ok: boolean;
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    language: string;
+    image: string;
+    artifacts: CodeArtifact[];
+    durationMs: number;
+    timedOut: boolean;
+    /** Output was cut at the daemon's limit. */
+    truncated: boolean;
+}
+/** The outcome of one command in a shell session. `cwd` is where the shell is now. */
+interface ShellResult {
+    ok: boolean;
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    cwd: string;
+    durationMs: number;
+    timedOut: boolean;
+    truncated: boolean;
+}
+/** A file or folder in the sandbox workspace (pkg/engine FileInfo). */
+interface FileInfo {
+    name: string;
+    path: string;
+    /** file | dir | symlink | other */
+    type: string;
+    size: number;
+    /** Permission bits. */
+    mode: number;
+    mod_time: string;
+    /** A symlink's target. */
+    link?: string;
+}
+/** One changed path in `git status`. */
+interface GitFileStatus {
+    path: string;
+    /** A rename's old path. */
+    from?: string;
+    index: string;
+    worktree: string;
+}
+interface GitStatus {
+    branch: string;
+    upstream?: string;
+    ahead: number;
+    behind: number;
+    clean: boolean;
+    files: GitFileStatus[];
+}
+interface GitCommit {
+    hash: string;
+    author_name: string;
+    author_email: string;
+    date: string;
+    subject: string;
+}
+interface GitBranch {
+    name: string;
+    current: boolean;
+}
+/** The git operations the daemon runs (POST …/git). */
+type GitOp = 'clone' | 'status' | 'add' | 'commit' | 'push' | 'pull' | 'checkout' | 'branches' | 'log' | 'diff';
+/**
+ * The outcome of a git operation. A git failure is `ok: false`, not an error;
+ * `status`, `log` or `branches` are filled for those ops.
+ */
+interface GitResult {
+    op: string;
+    ok: boolean;
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    /** The repository, in the workspace. */
+    path: string;
+    status?: GitStatus;
+    log?: GitCommit[];
+    branches?: GitBranch[];
+}
+/** A shell session (POST/GET …/sessions). */
+interface SessionInfo {
+    name: string;
+    /** The session's container id. */
+    id: string;
+    image: string;
+    status: string;
+}
+/** POST …/previews answer: a signed link to a port in the sandbox. */
+interface Preview {
+    url: string;
+    token: string;
+    /** RFC 3339. */
+    expires_at: string;
+    container: string;
+    port: number;
+    /** Where the daemon's preview listener is. */
+    listen: string;
+}
+/** A sandbox template (GET /kosa8/v1/templates). */
+interface Template {
+    name: string;
+    image: string;
+    size_bytes: number;
+    created: string;
+    dockerfile?: string;
+}
 
 /**
  * Checkpoints are client-side bookkeeping over daemon snapshots, exactly as
@@ -356,6 +492,13 @@ interface TransportOptions {
     headers?: Record<string, string>;
     /** Environment to read KOSA8_* variables from. Default `process.env`. */
     env?: Record<string, string | undefined>;
+    /**
+     * The CLI's saved worker connection, used when neither `host` nor KOSA8_HOST
+     * is set (and no `socketPath` is given): what `kosa8 wsl setup` writes on
+     * Windows, and `kosa8 worker join` anywhere. Default
+     * `$HOME/.kosa8/worker.json`; `null` reads none.
+     */
+    workerFile?: string | null;
 }
 interface RequestOptions {
     query?: Record<string, string | number | boolean | undefined>;
@@ -380,6 +523,8 @@ declare const ACTOR_HEADER = "X-Kosa8-Actor";
 declare const AGENT_TOKEN_HEADER = "X-Kosa8-Agent-Token";
 /** The daemon's default socket: $HOME/.kosa8/run/kosa8.sock (pkg/paths). */
 declare function defaultSocketPath(): string;
+/** The CLI's saved worker connection: $HOME/.kosa8/worker.json (internal/cli/worker.go). */
+declare function defaultWorkerFile(): string;
 /** Resolve where to connect, following the CLI's KOSA8_HOST rules. */
 declare function resolveEndpoint(opts: TransportOptions): Endpoint;
 interface RawResponse {
@@ -447,6 +592,106 @@ interface CreateSandboxOptions extends CallOptions {
     labels?: Record<string, string>;
     /** Put the sandbox behind an egress broker that adds credentials it never holds. */
     broker?: BrokerSpec;
+    /** Stop it after this many idle minutes. */
+    autoStopMin?: number;
+    /** Stop it this many minutes after creation, in use or not. */
+    ttlMin?: number;
+    /** Delete it once it has been stopped this many minutes. */
+    autoDeleteMin?: number;
+    /** Delete it (disk and all) whenever it stops. */
+    ephemeral?: boolean;
+    /** Start it with a template's image (see `buildTemplate`). */
+    template?: string;
+}
+interface RunCodeOptions extends CallOptions {
+    /** `python` (default), `javascript` or `typescript`. */
+    language?: string;
+    /** Image to run in; the daemon picks one per language (or the sandbox template's). */
+    image?: string;
+    env?: Record<string, string>;
+    /** Time limit in seconds; past it the run is killed and `timedOut` set. */
+    timeoutS?: number;
+}
+interface WriteFileOptions extends CallOptions {
+    /** Permission bits as octal text, e.g. `0755`. */
+    mode?: string;
+}
+/** The fields of a git op; which ones matter depends on the op. */
+interface GitOptions extends CallOptions {
+    /** The repository, in the workspace. */
+    path?: string;
+    /** clone */
+    url?: string;
+    branch?: string;
+    /** clone --depth */
+    depth?: number;
+    /** push | pull; default origin */
+    remote?: string;
+    /** checkout -b */
+    create?: boolean;
+    /** add: these paths (default everything) */
+    files?: string[];
+    /** commit */
+    message?: string;
+    authorName?: string;
+    authorEmail?: string;
+    /** log: how many (default 20) */
+    n?: number;
+    /** diff --cached */
+    staged?: boolean;
+    /** For an https remote that needs credentials. */
+    username?: string;
+    token?: string;
+    /** Image git runs in. */
+    image?: string;
+}
+interface GitCommitOptions extends Omit<GitOptions, 'path' | 'message'> {
+    /** Stage everything first (default true). */
+    addAll?: boolean;
+}
+interface CreateSessionOptions extends CallOptions {
+    image?: string;
+    env?: Record<string, string>;
+}
+interface SessionExecOptions extends CallOptions {
+    /** Time limit in seconds for this command. */
+    timeoutS?: number;
+}
+interface ShellOptions extends SessionExecOptions {
+    /** Session to run in; made on first use. Default `main`. */
+    session?: string;
+}
+interface StartPtyOptions extends CallOptions {
+    image?: string;
+    command?: string[];
+    cols?: number;
+    rows?: number;
+    env?: Record<string, string>;
+}
+interface CreatePreviewOptions extends CallOptions {
+    /** Which session's container serves the port. */
+    session?: string;
+    /** Or which container. */
+    container?: string;
+    /** How long the link lives, in seconds. */
+    expiresInS?: number;
+}
+interface SetLifecycleOptions extends CallOptions {
+    autoStopMin?: number;
+    autoDeleteMin?: number;
+    ttlMin?: number;
+    ephemeral?: boolean;
+}
+interface BuildTemplateOptions extends CallOptions {
+    /** Dockerfile name inside the context (default `Dockerfile`). */
+    dockerfile?: string;
+    buildArgs?: Record<string, string>;
+    /** Network the build sandbox gets (daemon default `any`). */
+    egress?: EgressPolicy;
+    /** Build again over an existing template of the same name. */
+    replace?: boolean;
+    /** Build output as it arrives. */
+    onOutput?: (chunk: Buffer, stream: string) => void;
 }
 interface RunOptions extends CallOptions {
     env?: Record<string, string> | string[];
@@ -629,6 +874,92 @@ declare class Kosa8Client {
      * checkpoints taken after the target are discarded. Current state is lost.
      */
     rewind(sandbox: string, opts?: RewindOptions): Promise<RewindResult>;
+    /**
+     * POST /kosa8/v1/sandboxes/{id}/code: run a Python, JavaScript or
+     * TypeScript snippet. It starts in `/workspace`. Charts a Python snippet
+     * draws with matplotlib come back in `artifacts` as PNG bytes.
+     */
+    runCode(id: string, code: string, opts?: RunCodeOptions): Promise<CodeResult>;
+    /** GET …/files: a folder in the workspace (default `/workspace`), or one entry. */
+    listFiles(id: string, path?: string, opts?: CallOptions): Promise<FileInfo[]>;
+    /** GET …/files/stat: one entry, not following a symlink. */
+    statFile(id: string, path: string, opts?: CallOptions): Promise<FileInfo>;
+    /** GET …/files/content: a file's bytes. A body cut short is a Kosa8StreamError. */
+    readFile(id: string, path: string, opts?: CallOptions): Promise<Buffer>;
+    /** A file's contents as text (UTF-8 by default). */
+    readText(id: string, path: string, opts?: CallOptions & {
+        encoding?: BufferEncoding;
+    }): Promise<string>;
+    /** PUT …/files/content: replace a file, making its folders. Answers the new entry. */
+    writeFile(id: string, path: string, data: Uint8Array | string | AsyncIterable<Uint8Array | string>, opts?: WriteFileOptions): Promise<FileInfo>;
+    /** DELETE …/files: a file, or with `recursive` a folder and everything in it. */
+    deleteFile(id: string, path: string, opts?: CallOptions & {
+        recursive?: boolean;
+    }): Promise<{
+        removed: string;
+    }>;
+    /** POST …/files/mkdir: a folder, with its parents. */
+    makeDir(id: string, path: string, opts?: CallOptions): Promise<FileInfo>;
+    /** POST …/files/move: rename or move a file or folder. Answers the entry at `to`. */
+    moveFile(id: string, from: string, to: string, opts?: CallOptions): Promise<FileInfo>;
+    /**
+     * POST …/git: one git operation in the workspace. A git failure resolves
+     * with `ok: false`; only a refusal (bad op, no sandbox, policy) throws.
+     */
+    git(id: string, op: GitOp | (string & {}), opts?: GitOptions): Promise<GitResult>;
+    /** Clone `url` into the workspace (into `path`, else a folder named after the repo). */
+    gitClone(id: string, url: string, opts?: GitOptions): Promise<GitResult>;
+    /** `git status` of the repository at `path`, parsed into `status`. */
+    gitStatus(id: string, path: string, opts?: GitOptions): Promise<GitResult>;
+    /** Stage everything (unless `addAll: false`) and commit. A failed add is returned as is. */
+    gitCommit(id: string, path: string, message: string, opts?: GitCommitOptions): Promise<GitResult>;
+    /** POST …/sessions: a shell that keeps `cd` and `export` between commands. */
+    createSession(id: string, name?: string, opts?: CreateSessionOptions): Promise<SessionInfo>;
+    /** GET …/sessions */
+    listSessions(id: string, opts?: CallOptions): Promise<SessionInfo[]>;
+    /** POST …/sessions/{name}/exec: run one command line in the session. */
+    sessionExec(id: string, session: string, command: string, opts?: SessionExecOptions): Promise<ShellResult>;
+    /** Run a command in a session (default `main`), making the session on first use. */
+    shell(id: string, command: string, opts?: ShellOptions): Promise<ShellResult>;
+    /** DELETE …/sessions/{name} */
+    deleteSession(id: string, session: string, opts?: CallOptions): Promise<{
+        deleted: string;
+    }>;
+    /**
+     * POST …/pty: a container with a terminal; resolves with its id. Connect
+     * to `/kosa8/v1/sandboxes/{id}/containers/{cid}/tty` with any WebSocket
+     * client: binary messages are the terminal, text messages JSON control.
+     */
+    startPty(id: string, opts?: StartPtyOptions): Promise<string>;
+    /** POST …/containers/{cid}/resize: set a terminal's size. */
+    resizePty(id: string, container: string, cols: number, rows: number, opts?: CallOptions): Promise<{
+        ok: boolean;
+    }>;
+    /** POST …/previews: a signed link, which expires, to a web server in the sandbox. */
+    createPreview(id: string, port: number, opts?: CreatePreviewOptions): Promise<Preview>;
+    /** POST /kosa8/v1/previews/rotate: end every preview link at once. */
+    revokePreviews(opts?: CallOptions): Promise<{
+        ok: boolean;
+        revoked: string;
+    }>;
+    /**
+     * POST …/lifecycle: change auto-stop, auto-delete, TTL or ephemeral.
+     * Options left out keep their value; 0 (or `false`) turns one off.
+     */
+    setLifecycle(id: string, opts?: SetLifecycleOptions): Promise<Sandbox>;
+    /** GET /kosa8/v1/templates */
+    listTemplates(opts?: CallOptions): Promise<Template[]>;
+    /** DELETE /kosa8/v1/templates/{name}. Sandboxes made from it keep their copy. */
+    deleteTemplate(name: string, opts?: CallOptions): Promise<{
+        deleted: string;
+    }>;
+    /**
+     * POST /kosa8/v1/templates: build `contextDir`'s Dockerfile in a throwaway
+     * sandbox and keep the image as a template, for `createSandbox({ template })`.
+     * The context is packed honouring `.dockerignore`. Resolves with the final
+     * frame (`{ done, ok, image }`); a failed build throws Kosa8StreamError.
+     */
+    buildTemplate(name: string, contextDir?: string, opts?: BuildTemplateOptions): Promise<Frame>;
     /** A handle bound to one sandbox. */
     sandbox(id: string): SandboxHandle;
     private collect;
@@ -666,8 +997,46 @@ declare class SandboxHandle {
     checkpoint(opts?: CheckpointOptions): Promise<CheckpointResult>;
     checkpoints(): Promise<Checkpoint[]>;
     rewind(opts?: RewindOptions): Promise<RewindResult>;
+    runCode(code: string, opts?: RunCodeOptions): Promise<CodeResult>;
+    listFiles(path?: string, opts?: CallOptions): Promise<FileInfo[]>;
+    statFile(path: string, opts?: CallOptions): Promise<FileInfo>;
+    readFile(path: string, opts?: CallOptions): Promise<Buffer<ArrayBufferLike>>;
+    readText(path: string, opts?: CallOptions & {
+        encoding?: BufferEncoding;
+    }): Promise<string>;
+    writeFile(path: string, data: Uint8Array | string | AsyncIterable<Uint8Array | string>, opts?: WriteFileOptions): Promise<FileInfo>;
+    deleteFile(path: string, opts?: CallOptions & {
+        recursive?: boolean;
+    }): Promise<{
+        removed: string;
+    }>;
+    makeDir(path: string, opts?: CallOptions): Promise<FileInfo>;
+    moveFile(from: string, to: string, opts?: CallOptions): Promise<FileInfo>;
+    git(op: GitOp | (string & {}), opts?: GitOptions): Promise<GitResult>;
+    gitClone(url: string, opts?: GitOptions): Promise<GitResult>;
+    gitStatus(path: string, opts?: GitOptions): Promise<GitResult>;
+    gitCommit(path: string, message: string, opts?: GitCommitOptions): Promise<GitResult>;
+    createSession(name?: string, opts?: CreateSessionOptions): Promise<SessionInfo>;
+    sessions(opts?: CallOptions): Promise<SessionInfo[]>;
+    sessionExec(session: string, command: string, opts?: SessionExecOptions): Promise<ShellResult>;
+    shell(command: string, opts?: ShellOptions): Promise<ShellResult>;
+    deleteSession(session: string, opts?: CallOptions): Promise<{
+        deleted: string;
+    }>;
+    startPty(opts?: StartPtyOptions): Promise<string>;
+    resizePty(container: string, cols: number, rows: number, opts?: CallOptions): Promise<{
+        ok: boolean;
+    }>;
+    createPreview(port: number, opts?: CreatePreviewOptions): Promise<Preview>;
+    setLifecycle(opts: SetLifecycleOptions): Promise<Sandbox>;
 }
 
+/**
+ * Pack `dir` as a tar archive for POST /kosa8/v1/templates. Throws when the
+ * Dockerfile is missing, so a bad path fails before anything is sent.
+ */
+declare function tarContext(dir: string, dockerfile?: string): Promise<Buffer>;
+
 /**
  * Typed errors. Every error the daemon answers with carries its own words:
  * `daemonMessage` is the daemon's `error` field verbatim, and `remediation`
@@ -722,6 +1091,8 @@ interface Kosa8ErrorOptions {
     path?: string;
     body?: unknown;
     cause?: unknown;
+    /** kosa8 Cloud's stable error code, such as payment_required. */
+    code?: string;
 }
 /** Base class of every error this SDK throws. */
 declare class Kosa8Error extends Error {
@@ -735,11 +1106,19 @@ declare class Kosa8Error extends Error {
     readonly path?: string;
     /** The decoded response body, when there was one. */
     readonly body?: unknown;
+    /** kosa8 Cloud's stable error code (payment_required, quota_exceeded, ...). */
+    readonly code?: string;
     constructor(message: string, options?: Kosa8ErrorOptions);
 }
 /** The daemon could not be reached (no socket, connection refused, ...). */
 declare class Kosa8ConnectionError extends Kosa8Error {
 }
+/**
+ * A call took longer than its timeout. A connection error too, so code that
+ * catches Kosa8ConnectionError keeps catching it.
+ */
+declare class Kosa8TimeoutError extends Kosa8ConnectionError {
+}
 /** The daemon answered with an HTTP error. */
 declare class Kosa8ApiError extends Kosa8Error {
 }
@@ -782,6 +1161,12 @@ declare class Kosa8StreamError extends Kosa8Error {
         stderr: string;
     }, options?: Kosa8ErrorOptions);
 }
+/** kosa8 Cloud refused new work until a payment method is on file (402). */
+declare class Kosa8PaymentRequiredError extends Kosa8ApiError {
+}
+/** Too many requests or a quota reached (429). */
+declare class Kosa8RateLimitError extends Kosa8ApiError {
+}
 /** A client-side checkpoint operation failed (no checkpoint, bad name, ...). */
 declare class Kosa8CheckpointError extends Kosa8Error {
 }
@@ -793,6 +1178,166 @@ declare class Kosa8CheckpointError extends Kosa8Error {
 declare function errorFromResponse(status: number, body: unknown, ctx?: {
     method?: string;
     path?: string;
+    code?: string;
 }): Kosa8ApiError;
 
-export { ACTOR_HEADER, AGENT_TOKEN_HEADER, APPROVAL_HEADER, type Actor, type ApprovalAction, type ApprovalRefusal, type ApprovalRequirement, type ApprovalRule, type BrokerHostRule, type BrokerInfo, type BrokerRoute, type BrokerSpec, type CallOptions, type CaptureSpec, type Checkpoint, CheckpointBook, type CheckpointOptions, type CheckpointResult, type CheckpointStore, type Container, type CreateSandboxOptions, type CreateSandboxResult, type DeleteSandboxResult, type DeleteSnapshotResult, type EgressPolicy, type EgressPolicyString, type EgressStatus, type ExecOptions, type ExecResult, type ExploreBranch, type ExploreOptions, type ExploreResult, FileCheckpointStore, type ForkOptions, type ForkResult, type Frame, type Health, Kosa8ApiError, Kosa8ApprovalRequiredError, Kosa8AuthError, Kosa8BadRequestError, Kosa8CheckpointError, Kosa8Client, type Kosa8ClientOptions, Kosa8ConflictError, Kosa8ConnectionError, Kosa8Error, Kosa8NotFoundError, Kosa8PolicyError, Kosa8StreamError, Kosa8UnsupportedError, MAX_CHECKPOINTS_PER_SANDBOX, MemoryCheckpointStore, type Mount, type RequestOptions, type RestoreOptions, type RestoreResult, type RewindOptions, type RewindResult, type RunOptions, type Sandbox, SandboxHandle, type Snapshot, type SnapshotSandboxResult, type StartSandboxResult, type StopSandboxResult, Transport, type TransportOptions, defaultSocketPath, errorFromResponse, resolveEndpoint, validateSandboxName };
+declare const DEFAULT_CLOUD_URL = "https://api.kosa8.cloud";
+declare const CLOUD_KEY_PREFIX = "k8c_live_";
+interface Kosa8CloudOptions {
+    /** API key. Defaults to the KOSA8_API_KEY environment variable. */
+    apiKey?: string;
+    /** Control-plane address. Defaults to KOSA8_CLOUD_URL, then https://api.kosa8.cloud. */
+    baseUrl?: string;
+    /** Where to read KOSA8_API_KEY and KOSA8_CLOUD_URL from. Defaults to process.env. */
+    env?: Record<string, string | undefined>;
+    /** A fetch to use instead of the global one (tests, proxies). */
+    fetch?: typeof fetch;
+    /** Per-request timeout. Default 120 s. */
+    timeoutMs?: number;
+}
+interface CloudSandboxInfo {
+    id: string;
+    state: 'creating' | 'running' | 'sleeping' | 'stopped' | 'deleted' | 'error' | string;
+    template: string;
+    cpus: number;
+    mem_mb: number;
+    source: 'pool' | 'restore' | 'cold' | null;
+    region: string | null;
+    own_host: boolean;
+    created_at: number;
+    started_at: number | null;
+    stopped_at: number | null;
+    deleted_at: number | null;
+    last_error: string | null;
+    running_s: number;
+    asleep_s: number;
+    sleep_bytes: number;
+    cost_usd: number;
+}
+interface CloudCreateOptions {
+    /** Template key, such as base, python or node. Defaults to the org's setting. */
+    template?: string;
+    /** Region id, such as eu-hel1. Defaults to the org's setting (any region). */
+    region?: string;
+    /** Idle seconds before the sandbox sleeps; 0 never. Defaults to the org's setting. */
+    sleepAfterS?: number;
+}
+interface CloudExecOptions {
+    /** Image to run the command in. Defaults to the template's own image. */
+    image?: string;
+    /** Environment variables for the command. */
+    env?: Record<string, string>;
+}
+interface CloudExecResult {
+    exitCode: number | null;
+    stdout: string;
+    stderr: string;
+    /** Set when the sandbox was asleep and woke for this command. */
+    wokeMs?: number;
+}
+interface CloudInvocation {
+    id: string;
+    function: string;
+    function_id: string;
+    version: number;
+    trigger: 'api' | 'web' | 'map' | 'cron' | string;
+}
+interface CloudInvokeResult<T = unknown> {
+    invocation: CloudInvocation | null;
+    /** False when the handler raised; `error` then says what. */
+    ok: boolean;
+    result?: T;
+    error?: {
+        type: string;
+        message: string;
+    };
+    logs?: string;
+    source?: 'pool' | 'restore' | null;
+    timings_ms?: {
+        start: number | null;
+        run: number | null;
+        host_total: number | null;
+        total: number;
+    };
+}
+interface CloudFunctionSpec {
+    runtime: 'python3.12' | 'node22' | string;
+    code: string;
+    env?: Record<string, string>;
+    timeout_s?: number;
+    web?: 'off' | 'public' | 'key' | string;
+    schedule?: string | null;
+    [k: string]: unknown;
+}
+type Json = Record<string, unknown>;
+/** A client for the kosa8 Cloud control plane. */
+declare class Kosa8Cloud {
+    readonly baseUrl: string;
+    readonly sandboxes: CloudSandboxes;
+    readonly functions: CloudFunctions;
+    private readonly apiKey;
+    private readonly fetchImpl;
+    private readonly timeoutMs;
+    constructor(options?: Kosa8CloudOptions);
+    /** The org, the key in use and, for a member's key, the member. */
+    me(): Promise<Json>;
+    /** This month's usage, bill estimate and whether work is paused for payment. */
+    usage(): Promise<Json>;
+    /** @internal */
+    request<T = Json>(method: string, path: string, body?: unknown): Promise<T>;
+}
+declare class CloudSandboxes {
+    private readonly cloud;
+    constructor(cloud: Kosa8Cloud);
+    /** Start a sandbox; resolves once it is running. */
+    create(opts?: CloudCreateOptions): Promise<CloudSandbox>;
+    /** The org's sandboxes; with all, deleted ones too. */
+    list(opts?: {
+        all?: boolean;
+    }): Promise<CloudSandbox[]>;
+    get(id: string): Promise<CloudSandbox>;
+}
+/** One cloud sandbox. `info` is its state as of the last call. */
+declare class CloudSandbox {
+    private readonly cloud;
+    info: CloudSandboxInfo;
+    constructor(cloud: Kosa8Cloud, info: CloudSandboxInfo);
+    get id(): string;
+    private path;
+    /**
+     * Run a command and wait for it. A string runs through `sh -c`. A
+     * sleeping sandbox wakes for it.
+     */
+    exec(cmd: string | string[], opts?: CloudExecOptions): Promise<CloudExecResult>;
+    /** Snapshot it and free its VM; it then costs only snapshot storage. */
+    sleep(): Promise<this>;
+    /** Restore a sleeping sandbox, files and all. */
+    wake(): Promise<this>;
+    refresh(): Promise<this>;
+    delete(): Promise<void>;
+}
+declare class CloudFunctions {
+    private readonly cloud;
+    constructor(cloud: Kosa8Cloud);
+    /** Deploy (create or replace) a function; every deploy bumps its version. */
+    deploy(name: string, spec: CloudFunctionSpec): Promise<Json>;
+    list(): Promise<Json[]>;
+    get(name: string): Promise<Json>;
+    delete(name: string): Promise<void>;
+    /** Call it once. A handler that raises resolves with ok: false, not a throw. */
+    invoke<T = unknown>(name: string, event?: unknown): Promise<CloudInvokeResult<T>>;
+    /** One call per event, results in input order. */
+    map<T = unknown>(name: string, events: unknown[], opts?: {
+        concurrency?: number;
+    }): Promise<{
+        function: string;
+        version: number;
+        count: number;
+        succeeded: number;
+        failed: number;
+        total_ms: number;
+        results: CloudInvokeResult<T>[];
+    }>;
+}
+
+export { ACTOR_HEADER, AGENT_TOKEN_HEADER, APPROVAL_HEADER, type Actor, type ApprovalAction, type ApprovalRefusal, type ApprovalRequirement, type ApprovalRule, type BrokerHostRule, type BrokerInfo, type BrokerRoute, type BrokerSpec, type BuildTemplateOptions, CLOUD_KEY_PREFIX, type CallOptions, type CaptureSpec, type Checkpoint, CheckpointBook, type CheckpointOptions, type CheckpointResult, type CheckpointStore, type CloudCreateOptions, type CloudExecOptions, type CloudExecResult, type CloudFunctionSpec, CloudFunctions, type CloudInvocation, type CloudInvokeResult, CloudSandbox, type CloudSandboxInfo, CloudSandboxes, type CodeArtifact, type CodeResult, type Container, type CreatePreviewOptions, type CreateSandboxOptions, type CreateSandboxResult, type CreateSessionOptions, DEFAULT_CLOUD_URL, type DeleteSandboxResult, type DeleteSnapshotResult, type EgressPolicy, type EgressPolicyString, type EgressStatus, type ExecOptions, type ExecResult, type ExploreBranch, type ExploreOptions, type ExploreResult, FileCheckpointStore, type FileInfo, type ForkOptions, type ForkResult, type Frame, type GitBranch, type GitCommit, type GitCommitOptions, type GitFileStatus, type GitOp, type GitOptions, type GitResult, type GitStatus, type Health, Kosa8ApiError, Kosa8ApprovalRequiredError, Kosa8AuthError, Kosa8BadRequestError, Kosa8CheckpointError, Kosa8Client, type Kosa8ClientOptions, Kosa8Cloud, type Kosa8CloudOptions, Kosa8ConflictError, Kosa8ConnectionError, Kosa8Error, Kosa8NotFoundError, Kosa8PaymentRequiredError, Kosa8PolicyError, Kosa8RateLimitError, Kosa8StreamError, Kosa8TimeoutError, Kosa8UnsupportedError, type Lifecycle, MAX_CHECKPOINTS_PER_SANDBOX, MemoryCheckpointStore, type Mount, type Preview, type RequestOptions, type RestoreOptions, type RestoreResult, type RewindOptions, type RewindResult, type RunCodeOptions, type RunOptions, type Sandbox, SandboxHandle, type SessionExecOptions, type SessionInfo, type SetLifecycleOptions, type ShellOptions, type ShellResult, type Snapshot, type SnapshotSandboxResult, type StartPtyOptions, type StartSandboxResult, type StopSandboxResult, type Template, Transport, type TransportOptions, type WriteFileOptions, defaultSocketPath, defaultWorkerFile, errorFromResponse, resolveEndpoint, tarContext, validateSandboxName };