@miosa/sdk 3.2.5 → 3.3.0

package/dist/index.d.ts

@@ -2230,6 +2230,20 @@ interface MiosaClientConfig {
     baseUrl?: string;
     timeout?: number;
     maxRetries?: number;
+    /**
+     * Opt-in SOMA one-hop runner path (ONE-HOP-RUNNER-DESIGN-2026-10-02.md).
+     * When enabled, `Miosa.runner` talks straight to `run-<region>.miosa.ai`
+     * for sandbox create/exec/destroy, bypassing the control-plane hop.
+     * Also enabled by the `MIOSA_RUNNER_MODE=1` environment variable.
+     * Every other client path (`miosa.sandboxes`, etc.) is unaffected either way.
+     */
+    runner?: {
+        enabled?: boolean;
+        /** Defaults to `us` (C5: not carried in the key this release); also settable via `MIOSA_RUNNER_REGION`. */
+        region?: string;
+        /** Overrides `miosa.ai` - for self-hosted / test deployments. */
+        baseDomain?: string;
+    };
 }
 
 type SnapshotStatus = "creating" | "uploading" | "ready" | "restoring" | "failed" | "deleted";
@@ -7168,6 +7182,21 @@ interface SandboxWriteManyEntry {
     content: string | Uint8Array;
 }
 interface SandboxWriteManyResult {
+    /**
+     * The guest's advertised batch transaction contract, forwarded verbatim.
+     * Only the exact value `"failure_atomic"` promises that a failed batch left
+     * no destination changed. Any other string, and an absent field on an older
+     * guest, is not that guarantee, so compare the literal instead of testing
+     * the field for presence.
+     */
+    atomicity?: "failure_atomic" | (string & {});
+    /**
+     * The guest's advertised read-isolation scope, forwarded verbatim.
+     * Only the exact value `"file_api_operations"` promises that file API reads
+     * serialize against batch publication, and even then separate shell/Docker
+     * readers, open descriptors and watchers are not transaction-isolated.
+     */
+    read_isolation?: "file_api_operations" | (string & {});
     written: Array<{
         path: string;
         size_bytes: number;
@@ -7263,7 +7292,16 @@ declare class SandboxFiles {
     download(path: string): Promise<Uint8Array>;
     /** GET /api/v1/sandboxes/{id}/files/tree — recursive directory tree. */
     tree(path?: string, depth?: number): Promise<SandboxFileTreeNode>;
-    /** POST /api/v1/sandboxes/{id}/files/write-many — write multiple files atomically. */
+    /**
+     * Write a failure-atomic batch on a batch-capable guest.
+     * The guest's guarantee is whatever the response advertises: rely on it only
+     * after `atomicity === "failure_atomic"` and `read_isolation ===
+     * "file_api_operations"` compare equal, because the fields are forwarded
+     * verbatim and an older guest omits them. Never treat an unknown value or a
+     * missing field as the guarantee, and never substitute sequential writes.
+     * Shell/Docker readers may see intermediate publication; coordinate them
+     * with the write if a consistent multi-file view is required.
+     */
     writeMany(files: SandboxWriteManyEntry[]): Promise<SandboxWriteManyResult>;
     /** GET /api/v1/sandboxes/{id}/files/watch (SSE) — live file change events. */
     watch(): AsyncIterableIterator<SandboxFileChange>;
@@ -7293,11 +7331,25 @@ declare class SandboxSnapshots {
     restore(snapshotId: string): Promise<Sandbox>;
     delete(snapshotId: string): Promise<void>;
 }
-/** Options for a `miosa-terminal-v1` PTY session. */
+/**
+ * Options for a `miosa-terminal-v1` PTY session.
+ *
+ * The server validates every option and answers `400 INVALID_TERMINAL_OPTIONS`
+ * before host dispatch; the client-side checks in `terminal.create()` only
+ * fail the locally decidable cases earlier. Direct command launch requires a
+ * compatible platform and guest. Older control planes may ignore these fields
+ * and return a default-shell ticket; verify platform support and the actual
+ * process or container context instead of treating a ticket as execution proof.
+ */
 interface SandboxTerminalCreateParams {
     cols?: number;
     rows?: number;
+    /** A single shell executable. Mutually exclusive with command. */
     shell?: string;
+    /** An executable to start directly, without an implicit outer shell. */
+    command?: string;
+    /** Literal executable arguments. Requires command; at most 256 entries. */
+    args?: string[];
     cwd?: string;
     env?: Record<string, string>;
 }
@@ -7305,8 +7357,14 @@ interface SandboxTerminalCreateParams {
  * A short-lived ticket for a `miosa-terminal-v1` WebSocket session.
  *
  * Connect to `wsUrl` with the `miosa-terminal-v1` subprotocol and provide
- * `streamAuth` as the Bearer credential. See docs/api/sandbox-terminal-v1.md
- * in the MIOSA runtime repository for the frame protocol.
+ * `streamAuth` as the Bearer credential. The frame, exit, close-code and
+ * reconnect contract is documented under "Interactive sandbox terminals" in
+ * this package's README.
+ *
+ * `streamAuthExpiresAt` and `expiresAt` are Unix epoch seconds, one hour after
+ * creation. `streamAuth` authorizes connections only until then; an account
+ * API key is accepted as the same Bearer credential and does not expire with
+ * the ticket.
  *
  * Every field is carried both as its wire (snake_case) key and its camelCase
  * alias, so callers that consumed the raw record keep working.
@@ -8612,6 +8670,459 @@ declare class WorkspaceInvites {
     accept(token: string): Promise<AcceptWorkspaceInviteResponse>;
 }
 
+/**
+ * Transport-level contract shared by the HTTP/2 and HTTP/3 runner
+ * transports (RUNNER-CONTRACTS-2026-10-02.md, C1/C6).
+ *
+ * A transport owns ONE pinned session pool per *region* hostname
+ * (`run-<region>.miosa.ai`): `sessionsPerAddress` sessions per resolved
+ * address (session `i` of that address's group), opened as soon as
+ * `prewarm` or `request` first names the region - never deferred further.
+ * A request waits only for the one session it lands on, never for a
+ * sibling's.
+ *
+ * That one pool serves both call shapes, varying only the HTTP/2
+ * `:authority` per request (connection coalescing: the cert covers both
+ * `run-<region>.miosa.ai` and `*.run-<region>.miosa.ai`, and a per-host
+ * name's one A record is the same IP already in the region pool, so no
+ * second TLS handshake is needed):
+ *
+ *   - create: `:authority` is the region hostname itself; RunnerClient
+ *     tries address index 0..n-1 in turn on retry (503 / connect failure).
+ *   - exec/destroy/etc: `:authority` is `<tag>.run-<region>.miosa.ai`;
+ *     RunnerClient has learned which address index that tag lives at
+ *     (from each address's own `/healthz`), so index is whichever one.
+ */
+interface RunnerRequestInit {
+    method: "GET" | "POST" | "PATCH" | "DELETE";
+    headers?: Record<string, string>;
+    body?: string;
+    /** Hard per-request deadline. Does not retry - that is the caller's job. */
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}
+interface RunnerResponse {
+    status: number;
+    headers: Record<string, string>;
+    body: string;
+}
+interface RunnerStreamResponse {
+    status: number;
+    headers: Record<string, string>;
+    /** Raw body text chunks as they arrive - SSE line/JSON parsing is the caller's job. */
+    chunks: AsyncIterableIterator<string>;
+}
+type RunnerProtocol = "h2" | "h3";
+interface RunnerTransport {
+    readonly protocol: RunnerProtocol;
+    /**
+     * Starts resolving `regionHostname` and connecting every address's
+     * session group now, without waiting for a request to need one (C6:
+     * "opened at client construction ... never lazily on first use").
+     * Fire-and-forget: a hostname that fails to resolve or connect here
+     * simply pays that cost again, synchronously, on its first real
+     * `request`/`addressCount` call. Idempotent - prewarming an
+     * already-warming-or-warm hostname is a no-op.
+     */
+    prewarm(regionHostname: string, sessionsPerAddress?: number): void;
+    /** The number of distinct runner hosts behind `regionHostname`. */
+    addressCount(regionHostname: string): Promise<number>;
+    /**
+     * Resolves once the session serving `addressIndex` is connected (or
+     * rejects if it fails to), without sending a request. Used by the
+     * HTTP/3-vs-HTTP/2 race in transport-factory.ts to pick a winner
+     * without firing the same request down both protocols.
+     */
+    ready(regionHostname: string, addressIndex: number): Promise<void>;
+    /**
+     * Sends a request through the session pinned to
+     * `regionHostname`'s address `addressIndex % n`, with the HTTP/2
+     * `:authority` set to `authority` (which may be `regionHostname`
+     * itself, for a create, or that address's own per-host name, for a
+     * per-sandbox call - see the module doc comment on connection
+     * coalescing). Waits only for that one session; never races or waits
+     * on a sibling's.
+     */
+    request(regionHostname: string, addressIndex: number, authority: string, path: string, init: RunnerRequestInit): Promise<RunnerResponse>;
+    /**
+     * Same routing as `request`, but for a server-sent-events response
+     * (exec/stream, C2): resolves once headers arrive, with `chunks` as the
+     * body streams in. HTTP/3 (today, no native streaming support in the
+     * addon) buffers the whole response first and yields it as one chunk -
+     * correct, just not incrementally streamed; HTTP/2 streams for real.
+     */
+    streamRequest(regionHostname: string, addressIndex: number, authority: string, path: string, init: RunnerRequestInit): Promise<RunnerStreamResponse>;
+    /** Releases every open session/connection. Safe to call more than once. */
+    close(): Promise<void>;
+}
+declare class RunnerTimeoutError extends Error {
+    constructor(hostname: string, path: string, timeoutMs: number);
+}
+declare class RunnerConnectError extends Error {
+    constructor(hostname: string, address: string, cause: unknown);
+}
+/**
+ * True for errors that mean "this address/session is unusable" rather than
+ * "the request itself failed" - the signal RunnerClient uses to retry a
+ * `create` on the next IP (C6).
+ */
+declare function isConnectFailure(error: unknown): boolean;
+
+/**
+ * soma.api.v1 envelope (RUNNER-CONTRACTS-2026-10-02.md, C2b).
+ *
+ * The per-sandbox routes (list, get, stop, filesystem, terminal) answer
+ * in soma-api's own envelope - distinct from the flatter fast-lane shapes
+ * C2 uses for create/exec/destroy/healthz. Every response, success or
+ * failure, is this one shape; `unwrapSomaEnvelope` returns `result` on
+ * success and throws a `RunnerError` (reusing its nested-error parsing,
+ * since the envelope's `error` field is that same `{code,message,
+ * retryable}` sub-shape) on failure.
+ */
+interface SomaEnvelope<T> {
+    schema: string;
+    operation: string;
+    status: "ok" | "error";
+    result: T | null;
+    error: {
+        code: string;
+        message: string;
+        retryable: boolean;
+    } | null;
+    receipt: Record<string, unknown> | null;
+}
+/** Bytes are never raw strings on these routes (C2b) - always this wrapper. */
+interface SomaBytes {
+    encoding: "base64";
+    byte_length: number;
+    data: string;
+}
+declare function encodeSomaBytes(content: string | Uint8Array): string;
+declare function decodeSomaBytes(bytes: SomaBytes): Uint8Array;
+/**
+ * `instance_id` inside the envelope is the sandbox's public id with every
+ * hyphen stripped (C2b). Normalizes back to the hyphenated UUID form used
+ * everywhere else in this SDK; passes through anything that isn't exactly
+ * 32 bare hex digits unchanged (already hyphenated, or not a UUID at all).
+ */
+declare function hyphenateInstanceId(instanceId: string): string;
+/**
+ * Parses the envelope and returns `result` on `status: "ok"`. Throws a
+ * `RunnerError` on `status: "error"` - `status` here is the envelope's
+ * own field, independent of the HTTP status (C2b: envelope failures ride
+ * on whatever HTTP status matches the facade outcome, not always 200).
+ */
+declare function unwrapSomaEnvelope<T>(httpStatus: number, body: string): T;
+
+/**
+ * RunnerClient - the SOMA one-hop runner path (ONE-HOP-RUNNER-DESIGN-2026-10-02.md
+ * section 6, RUNNER-CONTRACTS-2026-10-02.md C1/C2/C2b/C5/C6).
+ *
+ * Opt-in and additive: this talks directly to `run-<region>.miosa.ai` and
+ * its per-host names instead of `api.miosa.ai`, bypassing the
+ * control-plane hop entirely. It does not replace or alter
+ * `Sandboxes`/`Sandbox` - those keep using the existing HttpClient path
+ * unchanged. Construct a RunnerClient explicitly (or via `Miosa.runner`,
+ * gated by config/env - see ../client.ts) to use it.
+ *
+ * One pool, two `:authority` values (C1/C6): the region hostname's one
+ * session pool, resolved and opened at construction, serves both creates
+ * (`:authority` = the region hostname) and every per-sandbox call
+ * (`:authority` = that sandbox's `<tag>.run-<region>.miosa.ai`) via HTTP/2
+ * connection coalescing - see transport.ts's doc comment for why that's
+ * valid. `addressIndexByTag` is this client's only extra bookkeeping: which
+ * of the region's resolved addresses answers for which tag, learned from
+ * each address's own unauthenticated `/healthz` in the background.
+ *
+ * Two response shapes (C2 vs C2b): create/exec/destroy/healthz answer
+ * flat; get/stop/list/filesystem/terminal answer wrapped in soma-api's
+ * own envelope (envelope.ts). `sendToSandbox` is the one routing
+ * primitive (tag resolution, 421-follow, auth) both response parsers sit
+ * on top of.
+ */
+
+interface RunnerClientOptions {
+    apiKey: string;
+    /** Defaults to `us` (C5: not carried in the key this release). */
+    region?: string;
+    /** Overrides `miosa.ai` - for self-hosted / test deployments. */
+    baseDomain?: string;
+    /**
+     * Accepted for shape-parity with the rest of the SDK's resources. Not
+     * sent as a request header: C2 says the tenant comes only from the key
+     * record, and the runner strips any client-supplied tenant header.
+     */
+    tenant?: string;
+    /** Sessions opened per resolved region address. C6 default: 8. */
+    sessionsPerAddress?: number;
+    /** Injectable for tests; defaults to the best available transport. */
+    transport?: RunnerTransport;
+    /**
+     * Called for a create the runner doesn't serve (C2: template, image,
+     * snapshot, cwd, persistent, non-xs shapes) - wired by `Miosa` to
+     * `sandboxes.create()`. Without it, `createSandbox` throws rather than
+     * silently going nowhere for those shapes.
+     */
+    fallbackCreate?: (params: Record<string, unknown>, opts: {
+        idempotencyKey?: string;
+    }) => Promise<RunnerSandboxCreateResult>;
+}
+interface RunnerExecOptions {
+    cwd?: string;
+    env?: Record<string, string>;
+    /** Seconds. Defaults to 30 on the runner if omitted (C2). */
+    timeout?: number;
+}
+/** DELETE /api/v1/sandboxes/{id} - the sandbox's final usage (C2). */
+interface RunnerDestroyResult {
+    cpu_ms?: number;
+    lifetime_ms?: number;
+    [key: string]: unknown;
+}
+/** POST /api/v1/sandboxes/{id}/exec/stream events (C2) - same shape as the control plane's existing exec stream. */
+type RunnerExecStreamEvent = {
+    type: "stdout";
+    line: string;
+} | {
+    type: "stderr";
+    line: string;
+} | {
+    type: "exit";
+    exit_code: number;
+};
+interface RunnerSandboxCreateResult {
+    /** Empty string if the response body carried no `id` field. */
+    id: string;
+    /** The per-host URL this sandbox lives on. Empty when created via fallbackCreate (not runner-managed). */
+    runnerUrl: string;
+    data: Record<string, unknown>;
+}
+interface RunnerHealth {
+    ok: boolean;
+    /** The host tag this runner answers for, e.g. `"3"` (C2). */
+    tag?: string;
+    feed_age_ms?: number;
+    pool_ready?: number;
+}
+interface SomaSandboxGetResult {
+    instance_id: string;
+    state: "ready" | "stopping";
+    backend: "linux_kvm" | "macos_virtualization" | "docker_container" | "remote" | (string & {});
+}
+interface SomaSandboxStopResult {
+    instance_id: string;
+    state: "stopped";
+}
+/**
+ * PATCH /api/v1/sandboxes/{id} {"timeout":N} - C2's flat shape (C2b line
+ * 84), not the soma.api.v1 envelope every other per-sandbox route here
+ * uses. `id` is the normal hyphenated sandbox id, same as create's.
+ */
+interface RunnerSetTimeoutResult {
+    id: string;
+    timeout_sec: number;
+    expires_at: string | null;
+}
+interface SomaSandboxListEntry {
+    instance_id: string;
+    state: "launching" | "active" | "executing" | "terminating" | (string & {});
+    host: "live" | "absent" | "unknown";
+    backend: string;
+    name?: string;
+}
+interface SomaSandboxListResult {
+    sandboxes: SomaSandboxListEntry[];
+    count: number;
+}
+type SomaFilesystemRefusal = "not_found" | "denied" | "wrong_kind" | "already_exists" | "not_empty" | "too_large" | "failed";
+type SomaTerminalRefusal = "no_session" | "already_open" | "denied" | "failed";
+interface SomaOperationResult {
+    instance_id: string;
+    operation: string;
+}
+interface SomaFilesystemReadResult extends SomaOperationResult {
+    content?: SomaBytes;
+    refusal?: SomaFilesystemRefusal;
+}
+interface SomaFilesystemWriteResult extends SomaOperationResult {
+    byte_length?: number;
+    refusal?: SomaFilesystemRefusal;
+}
+interface SomaFilesystemListEntry {
+    name: SomaBytes;
+    kind: "file" | "directory" | "other";
+}
+interface SomaFilesystemListResult extends SomaOperationResult {
+    entries?: SomaFilesystemListEntry[];
+    more_entries?: boolean;
+    refusal?: SomaFilesystemRefusal;
+}
+interface SomaFilesystemExistsResult extends SomaOperationResult {
+    exists?: boolean;
+    kind?: "file" | "directory" | "other";
+    refusal?: SomaFilesystemRefusal;
+}
+interface SomaFilesystemRemoveResult extends SomaOperationResult {
+    refusal?: SomaFilesystemRefusal;
+}
+interface SomaFilesystemMkdirResult extends SomaOperationResult {
+    refusal?: SomaFilesystemRefusal;
+}
+interface SomaTerminalOpenResult extends SomaOperationResult {
+    columns?: number;
+    rows?: number;
+    refusal?: SomaTerminalRefusal;
+}
+interface SomaTerminalResizeResult extends SomaOperationResult {
+    columns?: number;
+    rows?: number;
+    refusal?: SomaTerminalRefusal;
+}
+interface SomaTerminalWriteResult extends SomaOperationResult {
+    written?: number;
+    refusal?: SomaTerminalRefusal;
+}
+interface SomaTerminalReadResult extends SomaOperationResult {
+    output?: SomaBytes;
+    ended?: boolean;
+    refusal?: SomaTerminalRefusal;
+}
+interface SomaTerminalCloseResult extends SomaOperationResult {
+    refusal?: SomaTerminalRefusal;
+}
+type SandboxMethod = "GET" | "POST" | "PATCH" | "DELETE";
+declare class RunnerClient {
+    readonly region: string;
+    readonly hostname: string;
+    private readonly baseDomain;
+    private readonly apiKey;
+    private readonly sessionsPerAddress;
+    private readonly transport;
+    private readonly fallbackCreate;
+    /** tag -> which of the region's resolved addresses answers for it, learned from /healthz. */
+    private readonly addressIndexByTag;
+    /** sandbox id -> tag, set only once a 421 corrects the id-derived guess. */
+    private readonly correctedTag;
+    constructor(options: RunnerClientOptions);
+    get protocol(): RunnerProtocol;
+    /** The tag a 421 has corrected sandboxId to, if any. */
+    correctedTagFor(sandboxId: string): string | undefined;
+    healthzByIndex(addressIndex: number): Promise<RunnerHealth>;
+    /**
+     * POST /api/v1/sandboxes against the region hostname. Create shapes the
+     * runner doesn't serve (C2) go straight to `fallbackCreate` without
+     * ever reaching the runner; a `400 RUNNER_UNSUPPORTED_REQUEST` the
+     * runner returns anyway falls back the same way, once. On `503
+     * runtime_busy`/`feed_stale` or a connect failure, retries on the next
+     * resolved IP, at most n-1 times (C6).
+     */
+    createSandbox(params?: Record<string, unknown>, opts?: {
+        idempotencyKey?: string;
+    }): Promise<RunnerSandboxCreateResult>;
+    exec(sandboxId: string, command: string, opts?: RunnerExecOptions): Promise<Record<string, unknown>>;
+    /** POST /api/v1/sandboxes/{id}/exec/stream - server-sent events (C2). */
+    execStream(sandboxId: string, command: string, opts?: RunnerExecOptions): AsyncIterableIterator<RunnerExecStreamEvent>;
+    /** Returns the sandbox's final usage: cpu_ms, lifetime_ms (C2). */
+    destroySandbox(sandboxId: string): Promise<RunnerDestroyResult>;
+    get(sandboxId: string, opts?: {
+        operationId?: string;
+    }): Promise<SomaSandboxGetResult>;
+    stop(sandboxId: string, opts?: {
+        operationId?: string;
+    }): Promise<SomaSandboxStopResult>;
+    /**
+     * PATCH /api/v1/sandboxes/{id} {"timeout":seconds} - resets the idle
+     * timeout (default 300s; every call to the sandbox already resets it).
+     * Flat C2 response shape (C2b line 84), not the envelope - errors still
+     * use the platform shape (400 INVALID_PARAM, 404 NOT_FOUND), which
+     * RunnerError.fromResponse already parses either way.
+     */
+    setTimeout(sandboxId: string, seconds: number): Promise<RunnerSetTimeoutResult>;
+    /**
+     * GET /api/v1/sandboxes - scoped to ONE runner host (C2b: "the calling
+     * tenant's sandboxes on this runner"), not the whole region. Defaults
+     * to address 0; pass `tag` to target the host currently known for that
+     * tag, or `addressIndex` directly.
+     */
+    list(opts?: {
+        addressIndex?: number;
+        tag?: string;
+    }): Promise<SomaSandboxListResult>;
+    readonly filesystem: {
+        read: (sandboxId: string, path: string) => Promise<SomaFilesystemReadResult>;
+        write: (sandboxId: string, path: string, content: string | Uint8Array) => Promise<SomaFilesystemWriteResult>;
+        list: (sandboxId: string, path: string) => Promise<SomaFilesystemListResult>;
+        exists: (sandboxId: string, path: string) => Promise<SomaFilesystemExistsResult>;
+        remove: (sandboxId: string, path: string, recursive?: boolean) => Promise<SomaFilesystemRemoveResult>;
+        mkdir: (sandboxId: string, path: string) => Promise<SomaFilesystemMkdirResult>;
+        /** Decodes a read() result's base64 `content` into bytes. */
+        decode: typeof decodeSomaBytes;
+    };
+    readonly terminal: {
+        open: (sandboxId: string, columns: number, rows: number) => Promise<SomaTerminalOpenResult>;
+        resize: (sandboxId: string, columns: number, rows: number) => Promise<SomaTerminalResizeResult>;
+        write: (sandboxId: string, input: string | Uint8Array) => Promise<SomaTerminalWriteResult>;
+        read: (sandboxId: string, waitMs?: number) => Promise<SomaTerminalReadResult>;
+        close: (sandboxId: string) => Promise<SomaTerminalCloseResult>;
+        /** Decodes a read() result's base64 `output` into bytes. */
+        decode: typeof decodeSomaBytes;
+    };
+    /**
+     * Low-level escape hatch: sends method/path straight to sandboxId's
+     * runner host, with the same tag-routing, 421-follow and auth every
+     * named method above uses, parsing the response as the flat C2 shape
+     * (not the C2b envelope - use filesystem/terminal/get/stop/list, or
+     * requestEnvelope() for an un-wrapped route not named here yet).
+     */
+    request(sandboxId: string, method: SandboxMethod, path: string, body?: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /** Same as request(), but unwraps the response as a C2b soma.api.v1 envelope. */
+    requestEnvelope<T>(sandboxId: string, method: SandboxMethod, path: string, body?: Record<string, unknown>): Promise<T>;
+    close(): Promise<void>;
+    private filesystemOp;
+    private terminalOp;
+    private createViaFallback;
+    /**
+     * Learns which resolved region address answers for which tag, via each
+     * one's own unauthenticated `/healthz` (C2) - best effort, never awaited
+     * by the constructor. A tag missed here (a host that joined after this
+     * client started, or a transient `/healthz` failure) just costs a
+     * repeat of this same probe on that sandbox's first real request,
+     * instead of none at all.
+     */
+    private discoverTags;
+    /**
+     * Sends method/path to sandboxId's runner host - the id-derived tag, or
+     * a previously 421-corrected one - following a single `421 misdirected`
+     * to the `runner_url` it names (C6). A connect failure here is not
+     * retried across other hosts: a sandbox has exactly one owner. Returns
+     * the raw response; requestToSandbox/requestEnvelopeToSandbox each
+     * parse it according to their route's response shape (C2 vs C2b).
+     */
+    private sendToSandbox;
+    /** Same routing as sendToSandbox, for a streaming (SSE) response. */
+    private sendToSandboxStream;
+    /** C2's flat shape: parses >=400 with RunnerError, else JSON.parses the raw body. */
+    private requestToSandbox;
+    /**
+     * C2b's envelope shape: a >=400 response may still be the flat C2 shape
+     * (401/403/429/503/421 happen before the envelope layer) - RunnerError
+     * .fromResponse parses either, so it's used directly rather than
+     * routing through the envelope parser. Only a <400 response is
+     * unwrapped as a genuine soma.api.v1 envelope.
+     */
+    private requestEnvelopeToSandbox;
+    /**
+     * `addressIndexByTag` first; if that tag hasn't been seen yet (a host
+     * that joined after construction, or this is the very first request
+     * racing the background discovery), refreshes discovery once and falls
+     * back to address 0 as a last resort - the request itself still ends up
+     * correct either way, via a 421 follow, just one round trip slower.
+     */
+    private resolveAddressIndexForTag;
+    private runnerUrlFrom;
+    private authHeaders;
+}
+
 /**
  * The top-level MIOSA client.
  *
@@ -8759,6 +9270,14 @@ declare class Miosa {
     readonly network: EgressNetwork;
     /** Egress audit log — every outbound request, paginated query + tail. */
     readonly audit: EgressAudit;
+    /**
+     * SOMA one-hop runner path (opt-in via `config.runner.enabled` or
+     * `MIOSA_RUNNER_MODE=1`) - talks straight to `run-<region>.miosa.ai` for
+     * sandbox create/exec/destroy, bypassing the control-plane hop. `undefined`
+     * unless enabled; every other resource above is unaffected either way.
+     * See ONE-HOP-RUNNER-DESIGN-2026-10-02.md and RUNNER-CONTRACTS-2026-10-02.md.
+     */
+    readonly runner: RunnerClient | undefined;
     private readonly http;
     constructor(config: MiosaClientConfig);
 }
@@ -8978,4 +9497,277 @@ declare class AppAuth {
     private _post;
 }
 
-export { AGENT_BUILD_KIND_SPECS, type AcceptOrgInviteResponse, type AcceptWorkspaceInviteResponse, type AddDomainParams, type AddWorkspaceMemberParams, Admin, type AgentBuildExecutionPacket, type AgentBuildFileSpec, type AgentBuildKind, type AgentBuildKindSpec, type AgentBuildPlannerDocument, type AgentDefinitionCreateParams, type AgentDefinitionData, type AgentDefinitionListParams, type AgentDefinitionUpdateParams, AgentDefinitions, type AgentDispatchParams, type AgentEvent$1 as AgentEvent, type AgentEventType, AgentRuntimeProfiles, type AgentSessionCreateParams, type AgentSessionData, type AgentSessionListResponse$1 as AgentSessionListResponse, type AgentSessionStatus$1 as AgentSessionStatus, type AgentVersionData, type AllowParams, Analytics, type AnalyticsFilters, type ApiKeyCreateParams, type ApiKeyCreateResult, type ApiKeyData, type ApiKeyId, type ApiKeyListParams, ApiKeys, type AppActionDecision, AppAuth, type AppAuthConfig, type AppAuthResourceType, type AppAuthSession, type AppAuthTokenPayload, type AppAutomationRun, type AppCatalogEntry, type AppCollectionRecord, type AppDocument, type AppDocumentCreateParams, type AppDocumentDiagnostics, type AppDocumentRecord, type AppDocumentUpdateParams, AppDocuments, type AppInstallData, type AppInstallEvent, type AppJson, type AppReleaseApproval, type AppReleaseCandidate, type AttachAwsRoleParams, type AuditListParams, AuditLog, type AuditLogEvent, type AuditLogListParams, type AuditTailParams, AuthError, type AuthToken, type BenchmarkCompareParams, type BenchmarkCreateParams, Benchmarks, type BindingCreateParams, type BindingListParams, type BrandingData, type BrandingUpdateParams, type BucketCreateParams, type BucketData, type BucketId, type BuilderSessionListParams, BuilderSessions, type BulkUserActionParams, type ChannelCreateParams, type ChannelData, type ChannelListParams, type ChannelUpdateParams, Channels, type ChatCompletionCreateParams, type ChatCompletionCreateStreamParams, Checkpoints, type ClickParams, Cloud, type CloudAccount, type CloudAccountCreateParams, type CloudAccountMode, type CloudAccountStatus, type CloudCredentialType, type CloudListParams, type CloudPlacementScope, type CloudPool, type CloudPoolCreateParams, type CloudPoolKind, type CloudPreflightRecordParams, type CloudPreflightRun, type CloudPreflightStatus, type CloudProvider, type CloudRegion, type CloudRegionCreateParams, type ClusterCreateParams, type ClusterData, type ClusterEvent, type ClusterId, type ClusterListResponse, type ClusterStatus, CommandCenter, Community, type CompletionCreateParams, type CompletionCreateStreamParams, Completions, type ComputeProduct, Computer, ComputerAudit, ComputerAutoStop, ComputerConnectors, type ComputerCreateParams, type ComputerData, ComputerEnv, type ComputerId, ComputerInbox, type ComputerListParams, type ComputerListResponse, ComputerLogs, type ComputerLogsGetParams, ComputerNetwork, ComputerOsa, ComputerPorts, ComputerSecrets, type ComputerSize, type ComputerStatus, type ComputerTemplateType, ComputerTerminal, type ComputerUpdateParams, type ComputerVisibility, ComputerVolumes, Computers, type ConnectorApplicableDefaultParams, type ConnectorCreateParams, type ConnectorData, type ConnectorDefault, type ConnectorDefaultListParams, type ConnectorDefaultParams, type ConnectorListParams, type ConnectorSubject, type ConnectorTokenParams, type ConnectorTokenResponse, Connectors, type CopyParams, type CreateAdminApiKeyParams, type CreateAgentBuildPacketParams, type CreateBuildRunParams, type CreateOrgInviteParams, type CreateWorkspaceInviteParams, type CreateWorkspaceInviteResponse, type CreditBalance, type CreditTransaction, type CreditTransactionListResponse, type CreditUsage, Credits, type CronJobCreateParams, type CronJobData, type CronJobExecutionData, type CronJobExecutionId, type CronJobId, type CronJobListParams, type CronJobUpdateParams, CronJobs, type CursorInfo, type CustomDomainCreateParams, type CustomDomainData, type CustomDomainId, type CustomDomainListParams, DEFAULT_AGENT_BUILD_OUTPUT_ROOT, DEFAULT_AGENT_BUILD_PACKET_VERSION, Dashboard, type DashboardSummary, type DatabaseCreateParams, type DatabaseCredentials, type DatabaseData, type DatabaseId, type DatabaseListParams, type DatabaseLogsParams, type DatabaseLogsResult, Databases, type DeploymentBuildData, DeploymentConnectors, type DeploymentCreateParams, type DeploymentData, DeploymentDomains, type DeploymentId, type DeploymentListParams, type DeploymentProduct, type DeploymentProofCheck, type DeploymentProofParams, type DeploymentProofProbe, type DeploymentProofResult, type DeploymentReleaseData, type DeploymentReleaseId, DeploymentReleases, DeploymentRuntimeInstances, type DeploymentServiceData, type DeploymentServiceId, type DeploymentServiceType, type DeploymentSourceType, type DeploymentState, type DeploymentUpdateParams, type DeploymentVersionData, type DeploymentVersionId, type DeploymentVersionKind, type DeploymentVersionState, DeploymentVersions, Deployments, Desktop$1 as Desktop, type DesktopActionResult, type DeviceBootstrapParams, type DeviceBootstrapResult, type DeviceBrowserResult, type DeviceCapabilities, type DeviceData, type DeviceExecParams, type DeviceExecResult, type DeviceExposeParams, type DeviceExposeResult, type DeviceExtendParams, type DeviceFileEntry, type DeviceFileListParams, type DeviceKind, type DeviceLifecycleResult, type DeviceListParams, type DeviceReadFileParams, type DeviceReadFileResult, type DeviceWriteFileParams, type DeviceWriteFileResult, Devices, type DirEntry, type DirListResult, type DiscordSendTestParams, DockerDeploy, type DockerDeployApplianceStatus, type DockerDeployCreateParams, type DockerDeployDoctorCheck, type DockerDeployDoctorParams, type DockerDeployDoctorProbe, type DockerDeployDoctorResult, type DockerDeployHostData, type DockerDeployHostEnsureParams, type DockerDeployHostId, type DockerDeployHostListParams, type DockerDeployHostListResponse, type DockerDeployHostResponse, type DockerDeployHostStatus, type DoubleClickParams, type DragParams, type EgressAllowlistRule, EgressAudit, type EgressAuditEvent, type EgressBindingData, EgressHostNotAllowedError, EgressNetwork, type EgressPolicyData, type EgressPolicyMode, type EgressRuleEffect, type EgressSecretData, type EgressSecretScope, type EgressSecretType, EgressSecrets, type EgressSuggestion, Email, EmailCampaigns, EmailInbox, EmailTemplates, type EmbeddingCreateParams, Embeddings, Exec, type ExecParams, type ExecPythonParams, type ExecResult, type ExternalAttribution, type ExternalKeyCreateParams, type ExternalKeyData, ExternalKeys, type FileDeleteParams, type FileDownloadParams, type FileEntry, type FileExportParams, type FileExportResult, type FileListParams, type FileListResult, type FileStat, Files, FlatCustomDomains, Forge, ForgeContractError, type ForgeDeleteReceipt, type ForgeOrganizationId, ForgePolicyViolationError, ForgeRepositories, type ForgeRepository, type ForgeRepositoryCreateParams, type ForgeRepositoryDeleteOptions, type ForgeRepositoryId, type ForgeRepositoryState, type ForgeRepositoryUpdateParams, type ForgeRepositoryVisibility, ForgeStorageError, ForgeUnavailableError, type FsEntry, type FsListResponse, type FsStat, type FunctionCreateParams, type FunctionData, type FunctionId, type FunctionInvokeParams, type FunctionListParams, type FunctionUpdateParams, Functions, type GithubRepo, type GithubSshKey, type HealthCheckCreateParams, type HealthCheckData, type HealthCheckId, type HealthCheckListParams, type HealthCheckUpdateParams, HealthChecks, type HostCreateParams, type HostData, type HostEvent, type HostId, type HostListResponse, type HostStatus, type HostUpdateParams, InstallationRequiredError, InsufficientCreditsError, type IntegrationCatalogEntry, type IntegrationData, Integrations, type JobData, type JobEvent, type JobEventType, type JobId, type JobListResponse, type JobRunParams, type JobStatus, type KeyParams, type LaunchParams, type LinearCreateIssueParams, type ListAdminApiKeysParams, type ListAdminComputersParams, type ListAdminTenantsParams, type ListAdminUsersParams, ManagedProviderBindingOnlyError, Mcp, type McpDispatchParams, Miosa, type MiosaClientConfig, MiosaError, type MiosaErrorBody, type MkdirParams, type ModeParams, Models, type MouseButton, NetworkError, NetworkPolicy, type NetworkPolicyData, type NetworkPolicyEffect, type NetworkPolicyProtocol, type NetworkPolicyRule, type NetworkPolicySetParams, NotFoundError, type NotificationPrefsUpdateParams, OAuthFlow, type OauthConnectParams, type OauthProvider, type OauthStartResult, type OauthStatusResult, type ObjectListParams, type AgentEvent as OcAgentEvent, type OcAgentSessionData, type AgentSessionListResponse as OcAgentSessionListResponse, type OcWorkspaceCreateParams, type OcWorkspaceData, type OcWorkspaceEvent, type OcWorkspaceListResponse, type OcWorkspaceStatus, type OcWorkspaceUpdateParams, OpenComputers, type OrgInvite, type OrgInviteCreated, type OrgInviteCreatedResponse, type OrgInviteListResponse, type OrgInvitePreview, type OrgInviteRevokeResponse, OrgInvites, type OrgRole, type OrganizationMember, type OrganizationMemberList, type OrganizationMemberRemoved, OrganizationMembers, type OrganizationRole, type OrganizationSummary, type OrganizationSwitchResult, Organizations, type OverviewData, type PolicyCreateParams, type PolicyListParams, type PolicyUpdateParams, type PresignParams, type PresignResult, type PreviewDomainData, type ProductCatalogEntry, type ProductTemplate, type ProductTemplateCatalog, ProjectAuth, type ProjectAuthEnableParams, type ProjectAuthStatus, type ProjectAuthUpdateParams, type ProjectIntegrationCatalogEntry, type ProjectIntegrationCreateParams, type ProjectIntegrationData, type ProjectIntegrationListParams, type ProjectIntegrationUpdateParams, ProjectIntegrations, ProjectNotLinkedError, ProviderDefaults, type ProviderKeyUpsertParams, type PublishFromSandboxParams, type PublishParams, type PublishResult, RateLimitError, type RegionData, Regions, type RollbackParams, type RulesListParams, type Run, type RunActivity, type RunCommandOutput, type RunCreateParams, type RunDiagnostic, type RunDownload, type RunFile, type RunGroup, type RunGroupActivity, type RunGroupCounts, type RunGroupCreateParams, type RunGroupDispatchEntry, type RunGroupDispatchResult, type RunGroupFile, type RunGroupListParams, type RunGroupStatus, type RunGroupWaitOptions, RunGroups, type RunListParams, type RunMessage, type RunOutputs, type RunPreview, type RunStatus, type RunTargetKind, type RunWaitOptions, Runs, type RuntimeCapabilities, RuntimeCapabilitiesResource, RuntimeEnv, type RuntimeEnvListParams, type RuntimeEnvScope, type RuntimeEnvSetParams, type RuntimeEnvTarget, type RuntimeEnvVar, type RuntimeInstanceData, type RuntimeInstanceId, type RuntimeInstanceState, type RuntimeLogsResult, SANDBOX_TEMPLATE, Sandbox, SandboxAudit, type SandboxBuildSpec, type SandboxBuildSpecError, type SandboxBuildSpecValidation, SandboxCommands, type SandboxConnectorAttachParams, type SandboxConnectorBinding, type SandboxConnectorPreflightParams, type SandboxConnectorPreflightResult, SandboxConnectors, type SandboxCreateParams, type SandboxData, SandboxEnv, SandboxEvents, type SandboxExecEvent, type SandboxExecOptions, type SandboxExecResult, type SandboxExecRunner, SandboxFiles, type SandboxGetOrCreateParams, type SandboxId, type SandboxListParams, SandboxNetwork, SandboxPreview, SandboxPreviews, SandboxSecrets, type SandboxState, SandboxTags, type SandboxTemplate, type SandboxTemplateBuild, type SandboxTemplateBuildCreateParams, type SandboxTemplateBuildResourceData, type SandboxTemplateBuildResourceId, type SandboxTemplateCreateParams, type SandboxTemplateList, type SandboxTemplateListParams, type SandboxTemplateResourceData, type SandboxTemplateResourceId, SandboxTemplates, SandboxTerminal, type SandboxTerminalCreateParams, type SandboxTerminalSession, Sandboxes, ScopeNotAllowedError, ScopedFs, type ScrollDirection, type ScrollParams, type SecretCreateParams, type SecretData, type SecretId, type SecretListParams, type SecretRotateParams, type SecretSetParams, type SecretUpdateParams, type SessionId, Settings, type SettingsUpdateParams, type SizeData, type SlackSendTestParams, type SnapshotCreateParams, type SnapshotData, type SnapshotListResponse, type SnapshotProgressEvent, type SnapshotRestoreResult, type SnapshotStatus, SnapshotsStandalone, Storage, type StorageObjectData, SubjectNotAllowedError, type SuggestionsParams, type TemplateBenchmarkLane, type TemplateBuildCreateParams, type TemplateCreateParams, type TemplateData, type TemplateReadinessContract, type TemplateReadinessState, type TemplateSizeReadiness, Templates, type TemplatesListParams, Tenant, type TenantBrandingUpdateParams, type TenantId, type TenantPlan, type TenantSummary, type TerminalCreateParams, TimeoutError, type TimeseriesParams, TokenRefreshFailedError, type TunnelAuthMode, type TunnelCreateParams, type TunnelData, type TunnelId, type TunnelListResponse, type TunnelUpdateParams, type TypeParams, type UpdateWorkspaceMemberRoleParams, Usage, type UsageReportParams, type UsageSession, type UsageSessionsParams, type UsageSummary, UserAuthorizationRequiredError, type UserId, ValidationError, type VersionListParams, type VolumeAttachParams, type VolumeAttachmentData, type VolumeCreateParams, type VolumeData, type VolumeId, type VolumeListParams, Volumes, type WaitParams, type WebhookCreateParams, type WebhookData, type WebhookDeliveryData, type WebhookDeliveryId, type WebhookId, type WebhookListParams, type WebhookUpdateParams, Webhooks, type WindowFocusParams, type WindowInfo, type WorkspaceId, type WorkspaceInvite, type WorkspaceInviteCreatedResponse, type WorkspaceInviteListResponse, type WorkspaceInvitePreview, type WorkspaceInviteRevokeResponse, WorkspaceInvites, type WorkspaceMember, type WorkspaceMemberAddedResponse, type WorkspaceMemberDeleteResponse, type WorkspaceMemberListResponse, type WorkspaceMemberRecord, type WorkspaceMemberRecordResponse, WorkspaceMembers, type WorkspaceRole, type WsTicket, createAgentBuildExecutionPacket, createAgentBuildExpectedOutputs, createAgentBuildPrompt, createBuildRunParams, getAgentBuildKindSpec, resolveAgentBuildKind, verifySignature };
+declare function regionFromApiKey(apiKey: string): string;
+
+declare function regionHostname(region: string, baseDomain?: string): string;
+declare function tagHostname(region: string, tag: string, baseDomain?: string): string;
+/**
+ * The host tag is the first character of a sandbox id (C1), lowercased
+ * since DNS labels are conventionally lowercase even though hostnames are
+ * case-insensitive.
+ */
+declare function sandboxTag(sandboxId: string): string;
+/** Resolves a hostname to the list of IP addresses it should be reached at. */
+interface AddressResolver {
+    resolve(hostname: string): Promise<string[]>;
+}
+/**
+ * Default resolver: plain DNS A-record lookup, with IP literals and
+ * `localhost` passed through unchanged so tests and self-hosted runners
+ * can point the transport straight at a fixed address without a resolver.
+ */
+declare class DnsAddressResolver implements AddressResolver {
+    private readonly ttlMs;
+    private readonly cache;
+    constructor(ttlMs?: number);
+    resolve(hostname: string): Promise<string[]>;
+}
+/** A fixed-table resolver, for tests and for pinning to known runner IPs (C1). */
+declare class StaticAddressResolver implements AddressResolver {
+    private readonly table;
+    constructor(table: ReadonlyMap<string, string[]>);
+    resolve(hostname: string): Promise<string[]>;
+}
+
+/**
+ * HTTP/2 runner transport (RUNNER-CONTRACTS-2026-10-02.md, C1/C6).
+ *
+ * One session pool per *region* hostname, `sessionsPerAddress` sessions
+ * per each of its `n` resolved addresses (session `i` of that address's
+ * group, pinned to `addresses[addressIndex]`). A pool's sessions all
+ * start connecting as soon as the region hostname is first named (by
+ * `prewarm` or `request`), not when a request actually needs one.
+ * `request`'s `addressIndex` selects which address's group to use (for
+ * create's retry-next-IP, or for a per-sandbox call's known host);
+ * within that group, concurrent callers are round-robined across its
+ * sessions, so a burst of simultaneous requests to the same address
+ * still spreads over every session pinned to it instead of serializing
+ * onto one. Either way, a request waits only for the one session it
+ * lands on - never for a sibling's.
+ *
+ * SNI is always the region hostname - one TLS session per address,
+ * reused for both creates and that address's own per-sandbox calls by
+ * varying only the HTTP/2 `:authority` per request (connection
+ * coalescing: the cert covers `run-<region>.miosa.ai` and
+ * `*.run-<region>.miosa.ai`, and a per-host name's one A record is the
+ * same IP already in this pool - see transport.ts's doc comment).
+ */
+
+interface Http2TransportOptions {
+    /** Sessions opened per address when no explicit count is given. C6 default: 8. */
+    defaultSessionsPerAddress?: number;
+    /** Plaintext h2c instead of TLS+h2 - for the local test server only. */
+    tls?: boolean;
+    port?: number;
+    resolver?: AddressResolver;
+    /** Default per-request timeout when the caller doesn't set one. */
+    defaultTimeoutMs?: number;
+}
+declare class Http2Transport implements RunnerTransport {
+    readonly protocol: "h2";
+    private readonly defaultSessionsPerAddress;
+    private readonly tls;
+    private readonly port;
+    private readonly resolver;
+    private readonly defaultTimeoutMs;
+    private readonly pools;
+    constructor(options?: Http2TransportOptions);
+    prewarm(regionHostname: string, sessionsPerAddress?: number): void;
+    addressCount(regionHostname: string): Promise<number>;
+    ready(regionHostname: string, addressIndex: number): Promise<void>;
+    request(regionHostname: string, addressIndex: number, authority: string, path: string, init: RunnerRequestInit): Promise<RunnerResponse>;
+    streamRequest(regionHostname: string, addressIndex: number, authority: string, path: string, init: RunnerRequestInit): Promise<RunnerStreamResponse>;
+    /** Shared by request() and ready() - the latter just discards the session. */
+    private acquireSession;
+    close(): Promise<void>;
+    private poolFor;
+    private buildPool;
+    private connectSession;
+    private sendRequest;
+    private sendStreamRequest;
+}
+
+/**
+ * HTTP/3 runner transport: a napi-rs addon over quinn + h3
+ * (native/h3-runner/), mirroring isorun's own native QUIC client.
+ *
+ * Built today for darwin-arm64 only - see native/h3-runner/README.md for
+ * exactly which platforms still need a CI build before this ships
+ * fleet-wide. `detectHttp3Support` reports unavailable on every other
+ * platform (or if the addon fails to load for any reason), and
+ * `createBestTransport` falls back to HTTP/2 automatically - the same
+ * zero-cost path this file documented before the addon existed.
+ *
+ * Pooling mirrors Http2Transport exactly (one pool per region hostname,
+ * sessions grouped by resolved address, round-robined within a group,
+ * self-healing) - only `connectSession`/`sendRequest` differ, swapping
+ * `node:http2` for the native addon's `h3Connect`/`h3Request`.
+ */
+
+interface Http3Availability {
+    available: boolean;
+    reason: string;
+}
+declare function detectHttp3Support(): Http3Availability;
+/** Exposed for tests - clears the cached load result and availability. */
+declare function resetHttp3DetectionCache(): void;
+interface Http3TransportOptions {
+    /** Sessions opened per address when no explicit count is given. C6: 4. */
+    defaultSessionsPerAddress?: number;
+    resolver?: AddressResolver;
+    /** Per-request timeout. */
+    defaultTimeoutMs?: number;
+    /**
+     * Hard cap on the QUIC handshake + h3 setup, independent of (and
+     * shorter than) the happy-eyeballs race in transport-factory.ts - see
+     * native/h3-runner/README.md's "known gap" for why this exists at all.
+     */
+    connectTimeoutMs?: number;
+    /** Skips certificate verification. Test-only - never set true in production. */
+    insecure?: boolean;
+    port?: number;
+}
+declare class Http3Transport implements RunnerTransport {
+    readonly protocol: "h3";
+    private readonly native;
+    private readonly defaultSessionsPerAddress;
+    private readonly resolver;
+    private readonly defaultTimeoutMs;
+    private readonly connectTimeoutMs;
+    private readonly insecure;
+    private readonly port;
+    private readonly pools;
+    constructor(options?: Http3TransportOptions);
+    prewarm(regionHostname: string, sessionsPerAddress?: number): void;
+    addressCount(regionHostname: string): Promise<number>;
+    ready(regionHostname: string, addressIndex: number): Promise<void>;
+    request(regionHostname: string, addressIndex: number, authority: string, path: string, init: RunnerRequestInit): Promise<RunnerResponse>;
+    /**
+     * The native addon has no streaming request support yet - buffers the
+     * whole response (same as request()) and hands it back as a single
+     * chunk. Correct, not incrementally streamed; see transport.ts's doc
+     * comment on streamRequest.
+     */
+    streamRequest(regionHostname: string, addressIndex: number, authority: string, path: string, init: RunnerRequestInit): Promise<RunnerStreamResponse>;
+    /** Shared by request() and ready() - the latter just discards the handle. */
+    private acquireHandle;
+    close(): Promise<void>;
+    private poolFor;
+    private buildPool;
+    private connectSession;
+    private sendRequest;
+}
+
+/**
+ * Picks the best transport available, and - when HTTP/3 is available -
+ * runs it against HTTP/2 per region host so a blocked or slow QUIC
+ * handshake never costs a request time (RUNNER-CONTRACTS-2026-10-02.md,
+ * C6; see http3-transport.ts's doc comment for the full requirement).
+ *
+ * Today, on a platform with no native HTTP/3 addon, this is unconditional
+ * HTTP/2 with zero QUIC probing - see http3-transport.ts.
+ */
+
+interface BestTransportOptions {
+    http2?: Http2TransportOptions;
+    http3?: Http3TransportOptions;
+}
+interface BestTransportResult {
+    transport: RunnerTransport;
+    http3: Http3Availability;
+}
+declare function createBestTransport(options?: BestTransportOptions): BestTransportResult;
+/**
+ * True happy-eyeballs, no waiting window: `prewarm` starts HTTP/2 and
+ * HTTP/3 connecting in parallel and immediately starts watching HTTP/3's
+ * readiness in the background - it does not block on it. Every request
+ * uses whichever protocol is already known-good for that region host at
+ * the moment it is sent:
+ *
+ *   - undecided or HTTP/3 still connecting -> HTTP/2 (never waits).
+ *   - HTTP/3 connected at some point        -> HTTP/2 until that moment,
+ *     HTTP/3 for every request from then on (remembered per host).
+ *   - HTTP/3 failed outright                -> HTTP/2 forever.
+ *
+ * A slow-but-alive QUIC path can only ever promote a host to HTTP/3 for
+ * *future* requests; it never delays the request that happens to be in
+ * flight when it finishes connecting.
+ */
+declare class RacingTransport implements RunnerTransport {
+    private readonly http2;
+    private readonly http3;
+    readonly protocol: RunnerProtocol;
+    private readonly protocolByHost;
+    private readonly watching;
+    constructor(http2: RunnerTransport, http3: RunnerTransport);
+    /** The protocol a region host is currently using - "h2" until HTTP/3 proves itself, per the class doc comment. */
+    perHostProtocol(regionHostname: string): RunnerProtocol;
+    prewarm(regionHostname: string, sessionsPerAddress?: number): void;
+    addressCount(regionHostname: string): Promise<number>;
+    ready(regionHostname: string, addressIndex: number): Promise<void>;
+    request(regionHostname: string, addressIndex: number, authority: string, path: string, init: RunnerRequestInit): Promise<RunnerResponse>;
+    streamRequest(regionHostname: string, addressIndex: number, authority: string, path: string, init: RunnerRequestInit): Promise<RunnerStreamResponse>;
+    close(): Promise<void>;
+    /** Whatever protocol is decided for regionHostname right now - never waits. */
+    private transportFor;
+    /**
+     * Starts (once per host) a background wait on HTTP/3's own readiness
+     * for address 0 - connection setup, not a request - and promotes the
+     * host to "h3" the moment it resolves. Never awaited by any caller;
+     * purely a side effect that later `transportFor` calls observe.
+     */
+    private watchHttp3;
+}
+
+/**
+ * Runner-specific error bodies (RUNNER-CONTRACTS-2026-10-02.md, C2/C2b).
+ *
+ * Two shapes, both handled by the one `fromResponse`:
+ *   - flat (401/403/421/429/503, C2): `{"error":"runtime_busy"}`.
+ *   - nested "platform" shape (400 RUNNER_UNSUPPORTED_REQUEST/INVALID_ID,
+ *     404 NOT_FOUND, and every soma.api.v1 envelope failure, C2/C2b):
+ *     `{"error":{"code":"...","message":"...","retryable":false},"ok":false}`.
+ *     The envelope's own top-level `error` field is this same sub-shape,
+ *     so envelope.ts's error path reuses this parser unchanged.
+ *
+ * Deliberately a lighter, separate parser from the control plane's
+ * src/errors.ts MiosaError rather than overloading it.
+ */
+type RunnerErrorCode = "unauthorized" | "forbidden" | "misdirected" | "rate_limited" | "runtime_busy" | "feed_stale" | "RUNNER_UNSUPPORTED_REQUEST" | "INVALID_ID" | "NOT_FOUND" | "not_found" | (string & {});
+interface RunnerErrorDetail {
+    code: string;
+    message?: string;
+    retryable?: boolean;
+}
+interface RunnerErrorBody {
+    error?: string | RunnerErrorDetail;
+    /** Present on 421 misdirected - the owning runner's URL, e.g. `https://3.run-us.miosa.ai`. */
+    runner_url?: string;
+    ok?: boolean;
+}
+interface RunnerErrorOptions {
+    runnerUrl?: string | undefined;
+    message?: string | undefined;
+    retryable?: boolean | undefined;
+}
+declare class RunnerError extends Error {
+    readonly status: number;
+    readonly code: RunnerErrorCode;
+    readonly runnerUrl: string | undefined;
+    /** Only meaningful for the nested "platform"/envelope shape - undefined for the flat C2 shape. */
+    readonly retryable: boolean | undefined;
+    constructor(status: number, code: RunnerErrorCode, options?: RunnerErrorOptions);
+    static fromResponse(status: number, body: string): RunnerError;
+    get isMisdirected(): boolean;
+    /**
+     * C2 (revised): admission-cap-reached ("runtime_busy") moved from 503 to
+     * 429 with `Retry-After: 0`; `feed_stale` stayed on 503. Checked by
+     * code, not status, so this stays correct regardless of which of the
+     * two carries it.
+     */
+    get isBusy(): boolean;
+    /** C2: the runner doesn't serve this create shape at all - send it to api.miosa.ai instead. */
+    get isUnsupportedRequest(): boolean;
+}
+
+export { AGENT_BUILD_KIND_SPECS, type AcceptOrgInviteResponse, type AcceptWorkspaceInviteResponse, type AddDomainParams, type AddWorkspaceMemberParams, type AddressResolver, Admin, type AgentBuildExecutionPacket, type AgentBuildFileSpec, type AgentBuildKind, type AgentBuildKindSpec, type AgentBuildPlannerDocument, type AgentDefinitionCreateParams, type AgentDefinitionData, type AgentDefinitionListParams, type AgentDefinitionUpdateParams, AgentDefinitions, type AgentDispatchParams, type AgentEvent$1 as AgentEvent, type AgentEventType, AgentRuntimeProfiles, type AgentSessionCreateParams, type AgentSessionData, type AgentSessionListResponse$1 as AgentSessionListResponse, type AgentSessionStatus$1 as AgentSessionStatus, type AgentVersionData, type AllowParams, Analytics, type AnalyticsFilters, type ApiKeyCreateParams, type ApiKeyCreateResult, type ApiKeyData, type ApiKeyId, type ApiKeyListParams, ApiKeys, type AppActionDecision, AppAuth, type AppAuthConfig, type AppAuthResourceType, type AppAuthSession, type AppAuthTokenPayload, type AppAutomationRun, type AppCatalogEntry, type AppCollectionRecord, type AppDocument, type AppDocumentCreateParams, type AppDocumentDiagnostics, type AppDocumentRecord, type AppDocumentUpdateParams, AppDocuments, type AppInstallData, type AppInstallEvent, type AppJson, type AppReleaseApproval, type AppReleaseCandidate, type AttachAwsRoleParams, type AuditListParams, AuditLog, type AuditLogEvent, type AuditLogListParams, type AuditTailParams, AuthError, type AuthToken, type BenchmarkCompareParams, type BenchmarkCreateParams, Benchmarks, type BestTransportOptions, type BestTransportResult, type BindingCreateParams, type BindingListParams, type BrandingData, type BrandingUpdateParams, type BucketCreateParams, type BucketData, type BucketId, type BuilderSessionListParams, BuilderSessions, type BulkUserActionParams, type ChannelCreateParams, type ChannelData, type ChannelListParams, type ChannelUpdateParams, Channels, type ChatCompletionCreateParams, type ChatCompletionCreateStreamParams, Checkpoints, type ClickParams, Cloud, type CloudAccount, type CloudAccountCreateParams, type CloudAccountMode, type CloudAccountStatus, type CloudCredentialType, type CloudListParams, type CloudPlacementScope, type CloudPool, type CloudPoolCreateParams, type CloudPoolKind, type CloudPreflightRecordParams, type CloudPreflightRun, type CloudPreflightStatus, type CloudProvider, type CloudRegion, type CloudRegionCreateParams, type ClusterCreateParams, type ClusterData, type ClusterEvent, type ClusterId, type ClusterListResponse, type ClusterStatus, CommandCenter, Community, type CompletionCreateParams, type CompletionCreateStreamParams, Completions, type ComputeProduct, Computer, ComputerAudit, ComputerAutoStop, ComputerConnectors, type ComputerCreateParams, type ComputerData, ComputerEnv, type ComputerId, ComputerInbox, type ComputerListParams, type ComputerListResponse, ComputerLogs, type ComputerLogsGetParams, ComputerNetwork, ComputerOsa, ComputerPorts, ComputerSecrets, type ComputerSize, type ComputerStatus, type ComputerTemplateType, ComputerTerminal, type ComputerUpdateParams, type ComputerVisibility, ComputerVolumes, Computers, type ConnectorApplicableDefaultParams, type ConnectorCreateParams, type ConnectorData, type ConnectorDefault, type ConnectorDefaultListParams, type ConnectorDefaultParams, type ConnectorListParams, type ConnectorSubject, type ConnectorTokenParams, type ConnectorTokenResponse, Connectors, type CopyParams, type CreateAdminApiKeyParams, type CreateAgentBuildPacketParams, type CreateBuildRunParams, type CreateOrgInviteParams, type CreateWorkspaceInviteParams, type CreateWorkspaceInviteResponse, type CreditBalance, type CreditTransaction, type CreditTransactionListResponse, type CreditUsage, Credits, type CronJobCreateParams, type CronJobData, type CronJobExecutionData, type CronJobExecutionId, type CronJobId, type CronJobListParams, type CronJobUpdateParams, CronJobs, type CursorInfo, type CustomDomainCreateParams, type CustomDomainData, type CustomDomainId, type CustomDomainListParams, DEFAULT_AGENT_BUILD_OUTPUT_ROOT, DEFAULT_AGENT_BUILD_PACKET_VERSION, Dashboard, type DashboardSummary, type DatabaseCreateParams, type DatabaseCredentials, type DatabaseData, type DatabaseId, type DatabaseListParams, type DatabaseLogsParams, type DatabaseLogsResult, Databases, type DeploymentBuildData, DeploymentConnectors, type DeploymentCreateParams, type DeploymentData, DeploymentDomains, type DeploymentId, type DeploymentListParams, type DeploymentProduct, type DeploymentProofCheck, type DeploymentProofParams, type DeploymentProofProbe, type DeploymentProofResult, type DeploymentReleaseData, type DeploymentReleaseId, DeploymentReleases, DeploymentRuntimeInstances, type DeploymentServiceData, type DeploymentServiceId, type DeploymentServiceType, type DeploymentSourceType, type DeploymentState, type DeploymentUpdateParams, type DeploymentVersionData, type DeploymentVersionId, type DeploymentVersionKind, type DeploymentVersionState, DeploymentVersions, Deployments, Desktop$1 as Desktop, type DesktopActionResult, type DeviceBootstrapParams, type DeviceBootstrapResult, type DeviceBrowserResult, type DeviceCapabilities, type DeviceData, type DeviceExecParams, type DeviceExecResult, type DeviceExposeParams, type DeviceExposeResult, type DeviceExtendParams, type DeviceFileEntry, type DeviceFileListParams, type DeviceKind, type DeviceLifecycleResult, type DeviceListParams, type DeviceReadFileParams, type DeviceReadFileResult, type DeviceWriteFileParams, type DeviceWriteFileResult, Devices, type DirEntry, type DirListResult, type DiscordSendTestParams, DnsAddressResolver, DockerDeploy, type DockerDeployApplianceStatus, type DockerDeployCreateParams, type DockerDeployDoctorCheck, type DockerDeployDoctorParams, type DockerDeployDoctorProbe, type DockerDeployDoctorResult, type DockerDeployHostData, type DockerDeployHostEnsureParams, type DockerDeployHostId, type DockerDeployHostListParams, type DockerDeployHostListResponse, type DockerDeployHostResponse, type DockerDeployHostStatus, type DoubleClickParams, type DragParams, type EgressAllowlistRule, EgressAudit, type EgressAuditEvent, type EgressBindingData, EgressHostNotAllowedError, EgressNetwork, type EgressPolicyData, type EgressPolicyMode, type EgressRuleEffect, type EgressSecretData, type EgressSecretScope, type EgressSecretType, EgressSecrets, type EgressSuggestion, Email, EmailCampaigns, EmailInbox, EmailTemplates, type EmbeddingCreateParams, Embeddings, Exec, type ExecParams, type ExecPythonParams, type ExecResult, type ExternalAttribution, type ExternalKeyCreateParams, type ExternalKeyData, ExternalKeys, type FileDeleteParams, type FileDownloadParams, type FileEntry, type FileExportParams, type FileExportResult, type FileListParams, type FileListResult, type FileStat, Files, FlatCustomDomains, Forge, ForgeContractError, type ForgeDeleteReceipt, type ForgeOrganizationId, ForgePolicyViolationError, ForgeRepositories, type ForgeRepository, type ForgeRepositoryCreateParams, type ForgeRepositoryDeleteOptions, type ForgeRepositoryId, type ForgeRepositoryState, type ForgeRepositoryUpdateParams, type ForgeRepositoryVisibility, ForgeStorageError, ForgeUnavailableError, type FsEntry, type FsListResponse, type FsStat, type FunctionCreateParams, type FunctionData, type FunctionId, type FunctionInvokeParams, type FunctionListParams, type FunctionUpdateParams, Functions, type GithubRepo, type GithubSshKey, type HealthCheckCreateParams, type HealthCheckData, type HealthCheckId, type HealthCheckListParams, type HealthCheckUpdateParams, HealthChecks, type HostCreateParams, type HostData, type HostEvent, type HostId, type HostListResponse, type HostStatus, type HostUpdateParams, Http2Transport, type Http2TransportOptions, type Http3Availability, Http3Transport, type Http3TransportOptions, InstallationRequiredError, InsufficientCreditsError, type IntegrationCatalogEntry, type IntegrationData, Integrations, type JobData, type JobEvent, type JobEventType, type JobId, type JobListResponse, type JobRunParams, type JobStatus, type KeyParams, type LaunchParams, type LinearCreateIssueParams, type ListAdminApiKeysParams, type ListAdminComputersParams, type ListAdminTenantsParams, type ListAdminUsersParams, ManagedProviderBindingOnlyError, Mcp, type McpDispatchParams, Miosa, type MiosaClientConfig, MiosaError, type MiosaErrorBody, type MkdirParams, type ModeParams, Models, type MouseButton, NetworkError, NetworkPolicy, type NetworkPolicyData, type NetworkPolicyEffect, type NetworkPolicyProtocol, type NetworkPolicyRule, type NetworkPolicySetParams, NotFoundError, type NotificationPrefsUpdateParams, OAuthFlow, type OauthConnectParams, type OauthProvider, type OauthStartResult, type OauthStatusResult, type ObjectListParams, type AgentEvent as OcAgentEvent, type OcAgentSessionData, type AgentSessionListResponse as OcAgentSessionListResponse, type OcWorkspaceCreateParams, type OcWorkspaceData, type OcWorkspaceEvent, type OcWorkspaceListResponse, type OcWorkspaceStatus, type OcWorkspaceUpdateParams, OpenComputers, type OrgInvite, type OrgInviteCreated, type OrgInviteCreatedResponse, type OrgInviteListResponse, type OrgInvitePreview, type OrgInviteRevokeResponse, OrgInvites, type OrgRole, type OrganizationMember, type OrganizationMemberList, type OrganizationMemberRemoved, OrganizationMembers, type OrganizationRole, type OrganizationSummary, type OrganizationSwitchResult, Organizations, type OverviewData, type PolicyCreateParams, type PolicyListParams, type PolicyUpdateParams, type PresignParams, type PresignResult, type PreviewDomainData, type ProductCatalogEntry, type ProductTemplate, type ProductTemplateCatalog, ProjectAuth, type ProjectAuthEnableParams, type ProjectAuthStatus, type ProjectAuthUpdateParams, type ProjectIntegrationCatalogEntry, type ProjectIntegrationCreateParams, type ProjectIntegrationData, type ProjectIntegrationListParams, type ProjectIntegrationUpdateParams, ProjectIntegrations, ProjectNotLinkedError, ProviderDefaults, type ProviderKeyUpsertParams, type PublishFromSandboxParams, type PublishParams, type PublishResult, RacingTransport, RateLimitError, type RegionData, Regions, type RollbackParams, type RulesListParams, type Run, type RunActivity, type RunCommandOutput, type RunCreateParams, type RunDiagnostic, type RunDownload, type RunFile, type RunGroup, type RunGroupActivity, type RunGroupCounts, type RunGroupCreateParams, type RunGroupDispatchEntry, type RunGroupDispatchResult, type RunGroupFile, type RunGroupListParams, type RunGroupStatus, type RunGroupWaitOptions, RunGroups, type RunListParams, type RunMessage, type RunOutputs, type RunPreview, type RunStatus, type RunTargetKind, type RunWaitOptions, RunnerClient, type RunnerClientOptions, RunnerConnectError, type RunnerDestroyResult, RunnerError, type RunnerErrorBody, type RunnerErrorCode, type RunnerErrorDetail, type RunnerErrorOptions, type RunnerExecOptions, type RunnerExecStreamEvent, type RunnerHealth, type RunnerProtocol, type RunnerRequestInit, type RunnerResponse, type RunnerSandboxCreateResult, type RunnerSetTimeoutResult, type RunnerStreamResponse, RunnerTimeoutError, type RunnerTransport, Runs, type RuntimeCapabilities, RuntimeCapabilitiesResource, RuntimeEnv, type RuntimeEnvListParams, type RuntimeEnvScope, type RuntimeEnvSetParams, type RuntimeEnvTarget, type RuntimeEnvVar, type RuntimeInstanceData, type RuntimeInstanceId, type RuntimeInstanceState, type RuntimeLogsResult, SANDBOX_TEMPLATE, Sandbox, SandboxAudit, type SandboxBuildSpec, type SandboxBuildSpecError, type SandboxBuildSpecValidation, SandboxCommands, type SandboxConnectorAttachParams, type SandboxConnectorBinding, type SandboxConnectorPreflightParams, type SandboxConnectorPreflightResult, SandboxConnectors, type SandboxCreateParams, type SandboxData, SandboxEnv, SandboxEvents, type SandboxExecEvent, type SandboxExecOptions, type SandboxExecResult, type SandboxExecRunner, SandboxFiles, type SandboxGetOrCreateParams, type SandboxId, type SandboxListParams, SandboxNetwork, SandboxPreview, SandboxPreviews, SandboxSecrets, type SandboxState, SandboxTags, type SandboxTemplate, type SandboxTemplateBuild, type SandboxTemplateBuildCreateParams, type SandboxTemplateBuildResourceData, type SandboxTemplateBuildResourceId, type SandboxTemplateCreateParams, type SandboxTemplateList, type SandboxTemplateListParams, type SandboxTemplateResourceData, type SandboxTemplateResourceId, SandboxTemplates, SandboxTerminal, type SandboxTerminalCreateParams, type SandboxTerminalSession, Sandboxes, ScopeNotAllowedError, ScopedFs, type ScrollDirection, type ScrollParams, type SecretCreateParams, type SecretData, type SecretId, type SecretListParams, type SecretRotateParams, type SecretSetParams, type SecretUpdateParams, type SessionId, Settings, type SettingsUpdateParams, type SizeData, type SlackSendTestParams, type SnapshotCreateParams, type SnapshotData, type SnapshotListResponse, type SnapshotProgressEvent, type SnapshotRestoreResult, type SnapshotStatus, SnapshotsStandalone, type SomaBytes, type SomaEnvelope, type SomaFilesystemExistsResult, type SomaFilesystemListEntry, type SomaFilesystemListResult, type SomaFilesystemMkdirResult, type SomaFilesystemReadResult, type SomaFilesystemRefusal, type SomaFilesystemRemoveResult, type SomaFilesystemWriteResult, type SomaSandboxGetResult, type SomaSandboxListEntry, type SomaSandboxListResult, type SomaSandboxStopResult, type SomaTerminalCloseResult, type SomaTerminalOpenResult, type SomaTerminalReadResult, type SomaTerminalRefusal, type SomaTerminalResizeResult, type SomaTerminalWriteResult, StaticAddressResolver, Storage, type StorageObjectData, SubjectNotAllowedError, type SuggestionsParams, type TemplateBenchmarkLane, type TemplateBuildCreateParams, type TemplateCreateParams, type TemplateData, type TemplateReadinessContract, type TemplateReadinessState, type TemplateSizeReadiness, Templates, type TemplatesListParams, Tenant, type TenantBrandingUpdateParams, type TenantId, type TenantPlan, type TenantSummary, type TerminalCreateParams, TimeoutError, type TimeseriesParams, TokenRefreshFailedError, type TunnelAuthMode, type TunnelCreateParams, type TunnelData, type TunnelId, type TunnelListResponse, type TunnelUpdateParams, type TypeParams, type UpdateWorkspaceMemberRoleParams, Usage, type UsageReportParams, type UsageSession, type UsageSessionsParams, type UsageSummary, UserAuthorizationRequiredError, type UserId, ValidationError, type VersionListParams, type VolumeAttachParams, type VolumeAttachmentData, type VolumeCreateParams, type VolumeData, type VolumeId, type VolumeListParams, Volumes, type WaitParams, type WebhookCreateParams, type WebhookData, type WebhookDeliveryData, type WebhookDeliveryId, type WebhookId, type WebhookListParams, type WebhookUpdateParams, Webhooks, type WindowFocusParams, type WindowInfo, type WorkspaceId, type WorkspaceInvite, type WorkspaceInviteCreatedResponse, type WorkspaceInviteListResponse, type WorkspaceInvitePreview, type WorkspaceInviteRevokeResponse, WorkspaceInvites, type WorkspaceMember, type WorkspaceMemberAddedResponse, type WorkspaceMemberDeleteResponse, type WorkspaceMemberListResponse, type WorkspaceMemberRecord, type WorkspaceMemberRecordResponse, WorkspaceMembers, type WorkspaceRole, type WsTicket, createAgentBuildExecutionPacket, createAgentBuildExpectedOutputs, createAgentBuildPrompt, createBestTransport, createBuildRunParams, decodeSomaBytes, detectHttp3Support, encodeSomaBytes, getAgentBuildKindSpec, hyphenateInstanceId, isConnectFailure, regionFromApiKey, regionHostname, resetHttp3DetectionCache, resolveAgentBuildKind, sandboxTag, tagHostname, unwrapSomaEnvelope, verifySignature };