@runblackcat/sdk 0.1.0-alpha.100

package/sdk/dist/index.d.ts

@@ -0,0 +1,1020 @@
+/**
+ * Server-side TypeScript client for the Blackcat gateway.
+ *
+ * The SDK intentionally contains transport primitives only.  Workload-specific
+ * workflows (a consumer's dirty-worktree sync, say) compose file and exec
+ * operations in their own repository.
+ */
+export declare const CAPABILITY_OPS: {
+    readonly EXEC: 1;
+    readonly READ: 2;
+    readonly WRITE: 4;
+    readonly SNAPSHOT: 8;
+    readonly DESTROY: 16;
+    readonly INSPECT: 32;
+    readonly SANDBOX_CREATE: 64;
+    readonly TEMPLATE_RW: 128;
+    readonly PUBLISH: 256;
+    readonly PROCESS_START: 512;
+    readonly PROCESS_INSPECT: 1024;
+    readonly PROCESS_CANCEL: 2048;
+    readonly RENEW: 4096;
+};
+export type CapabilityOps = number;
+export declare const BLACKCAT_ERROR_CODES: {
+    readonly SANDBOX_TRANSITIONING: "sandbox_transitioning";
+    readonly FLEET_UPGRADE_QUIESCING: "fleet_upgrade_quiescing";
+};
+export type FetchFunction = (input: RequestInfo | URL, init?: RequestInit & {
+    tls?: {
+        ca: string;
+    };
+    timeout?: false;
+}) => Promise<Response>;
+export interface BlackcatClientOptions {
+    baseUrl: string;
+    /**
+     * A tenant API key. The gateway accepts it directly on every resource route
+     * for the tenant's own resources (limited to the key's operation set), so a
+     * trusted server-side caller needs no `tokens.mint` per call. Keep it
+     * server-side; hand less-trusted holders a minted `token` instead.
+     */
+    apiKey?: string;
+    /** A capability token; preferred over `apiKey` when both are set. */
+    token?: string;
+    /** Capability identity and expiry, using idiomatic TypeScript names. */
+    tokenId?: string;
+    tokenExpiresAt?: number;
+    /** Backward-compatible aliases retained for pre-publication callers. */
+    token_id?: string;
+    token_expires_at?: number;
+    /** Re-mint a capability when renewal must replace the token secret. */
+    renewCapability?: () => Promise<MintTokenResponse>;
+    /** Private gateway trust root. Bun forwards this through its fetch TLS option. */
+    caPem?: string;
+    fetch?: FetchFunction;
+}
+export interface TemplateDefaults {
+    vcpus: number;
+    memory_mib: number;
+    hibernate?: HibernateMode;
+    on_interruption?: "evacuate" | "destroy";
+    /** MiB of virtio-mem region booted into the checkpoint; a multiple of 128. Defaults to the template's memory. */
+    hotplug_max_mib?: number;
+}
+/**
+ * The size a stored template version carries: `memory_mib` is the size it was
+ * captured at (boot memory plus what was plugged), and a sandbox can later
+ * take any size from `base_memory_mib` to `base_memory_mib + hotplug_max_mib`.
+ */
+export interface TemplateShapeDefaults extends TemplateDefaults {
+    base_memory_mib: number;
+    hotplug_max_mib: number;
+}
+export type HibernateMode = "memory";
+export type TemplateEgressPolicy = {
+    mode: "deny_all";
+} | {
+    mode: "allow_public";
+} | {
+    mode: "rules";
+    rules: ReadonlyArray<{
+        protocol: "tcp" | "udp";
+        port: number;
+        target: {
+            kind: "cidr";
+            value: string;
+        } | {
+            kind: "dns_name";
+            value: string;
+        } | {
+            kind: "dns_suffix";
+            value: string;
+        };
+    }>;
+};
+export type TemplatePreparationValue = {
+    from: "literal";
+    value: string;
+} | {
+    from: "parameter";
+    name: string;
+} | {
+    from: "secret";
+    name: string;
+};
+export interface TemplateRestoreHealth {
+    command: string;
+    args: readonly string[];
+    cwd: string;
+    timeout_ms: number;
+}
+interface TemplateDockerSourceBase {
+    /** A prepared filesystem; each sandbox starts a fresh process tree. */
+    docker: {
+        image: string;
+    };
+    defaults: TemplateDefaults;
+    egress: TemplateEgressPolicy;
+    restore_health: TemplateRestoreHealth;
+    /** Runs in the guest after it is ready and before the capture, so every
+     * clone restores with the app's caches and JIT already hot. Must exit 0. */
+    warmup?: TemplateRestoreHealth;
+}
+interface TemplatePreparation {
+    parameters: Record<string, {
+        min_length: number;
+        max_length: number;
+        charset: "printable_ascii" | "lower_hex";
+    }>;
+    prepare: {
+        command: string;
+        args: TemplatePreparationValue[];
+        cwd: string;
+        environment: Record<string, TemplatePreparationValue>;
+        timeout_ms: number;
+        output_limit_bytes: number;
+    };
+}
+export type TemplateDockerSource = TemplateDockerSourceBase & (TemplatePreparation | {
+    parameters?: never;
+    prepare?: never;
+});
+/** A build whose image was uploaded rather than pulled from a registry. */
+export type TemplateUploadedImageSource = Omit<TemplateDockerSourceBase, "docker"> & {
+    docker: UploadedImageSource;
+} & (TemplatePreparation | {
+    parameters?: never;
+    prepare?: never;
+});
+export interface UploadedImageSource {
+    /** The `sha256:<hex>` digest returned by `templates.uploadImage`. */
+    uploaded_image: string;
+}
+export interface UploadedImage {
+    image: string;
+    bytes: number;
+    /** True when the control plane already held this exact image. */
+    unchanged: boolean;
+}
+export interface TemplateSandboxSource {
+    /** `warmup` runs in the sandbox just before it is captured; omitted, the
+     * sandbox's template's own warm-up (if any) runs. */
+    sandbox: {
+        id: string;
+        warmup?: TemplateRestoreHealth;
+    };
+    /**
+     * A promoted sandbox keeps the machine dimensions it was captured on, so
+     * the gateway rejects `defaults` here. Omit `egress` to inherit the source
+     * template's policy.
+     */
+    egress?: TemplateEgressPolicy;
+}
+export type TemplateSource = TemplateDockerSource | TemplateUploadedImageSource | TemplateSandboxSource;
+/** What a promotion adds to a template create: how it is warmed and packed. */
+export interface PromotionOptions {
+    /** Warm the new version onto this many more nodes in bulk, beyond the node
+     * that captured it (at most 99), or onto `"all"` the other healthy nodes.
+     * Nodes bound to a capacity reservation that follows the template are warmed
+     * regardless. */
+    prefetch_copies?: number | "all";
+    /** Millicores each clone of the new version reserves, at most 1000 per vCPU.
+     * Omitted, the version inherits what the sandbox's own template reserves. */
+    cpu_reservation_mcpu?: number;
+}
+export type CreateTemplateInput = {
+    name: string;
+    source: TemplateDockerSource;
+} | {
+    name: string;
+    source: TemplateUploadedImageSource;
+} | ({
+    name?: string;
+    source: TemplateSandboxSource;
+} & PromotionOptions);
+export interface Template {
+    id: string;
+    name: string;
+    version: number;
+    /** `local_ready` while a promotion's chunks are still being published. */
+    state?: "local_ready" | "published";
+    /** The gateway stores the complete source manifest as JSON text. */
+    source: string;
+    current: boolean;
+}
+/** Public record name retained for consumers that distinguish it from creation input. */
+export type TemplateRecord = Template;
+export interface CreateTemplateBuildInput {
+    name: string;
+    content_key: string;
+    activate_on_ready: boolean;
+    source: TemplateDockerSource;
+}
+export type TemplateBuildPhase = "queued" | "building" | "validating" | "ready" | "failed";
+export interface TemplateBuildRecord {
+    id: string;
+    name: string;
+    content_key: string;
+    phase: TemplateBuildPhase;
+    attempt: number;
+    template_version_id: string | null;
+    error: string | null;
+}
+export interface PrepareSandboxResponse {
+    prepared?: boolean;
+    process: Pick<ProcessRecord, "id" | "state" | "exit_code">;
+}
+export interface CreateTemplateResponse {
+    id: string;
+    version: number;
+    /**
+     * `local_ready`: a promotion whose capture has been proved but whose chunks
+     * are still being published. The version is current and claimable, but only
+     * on the node that captured it; clones depend only on that node's files and
+     * are destroyed if the publication fails. `published`: every chunk is in the
+     * object store.
+     */
+    state?: "local_ready" | "published";
+    /**
+     * Capture/publish phase breakdown for a checkpoint promotion, when this
+     * create captured a running sandbox. Absent for a template created without
+     * a capture, and for a server that predates this field.
+     */
+    capture_timing?: {
+        capture_ms: number;
+        /** How long the source VM stood paused: the memory/state dump, the disk
+         * freeze and the resume. Sealing and upload happen after it. */
+        pause_ms: number;
+        /** Absent while the version is `local_ready`: publication is not over. */
+        publish_ms?: number;
+        /** Restoring a disposable clone from the capture and running the
+         * template's restore-health command in it; both overlap the upload. */
+        validation_restore_ms?: number;
+        validation_health_ms?: number;
+        /** Whether the capturing node was left holding the new version's memory
+         * and disk for fault-free restores. */
+        warmed?: {
+            memory: boolean;
+            disk: boolean;
+        };
+    };
+    /** Present for a promotion that asked for or achieved warming. */
+    warming?: {
+        capturing_node_warm: boolean;
+        prefetch_copies: number;
+        /** Pass to `templates.prefetchStatus` to follow the extra copies. */
+        prefetch_id?: string;
+        error?: string;
+    };
+}
+export type CreateSandboxInput = {
+    /**
+     * The template name or version id. Omitted, it is the tenant's `default`
+     * template, which the gateway builds on the tenant's first use: that first
+     * create fails with a 503 `default_template_building` until the build is
+     * ready, and repeating the same request is how to wait for it.
+     */
+    template?: string;
+    /** Must equal the checkpoint's vCPUs, which are fixed at capture; omit it. */
+    vcpus?: number;
+    /**
+     * Guest memory in MiB: the checkpoint's captured size or larger, up to its
+     * boot memory plus hotplug region (the extra is plugged right after restore).
+     */
+    memory_mib?: number;
+    /** CPU entitlement in millicores, at most the checkpoint's vCPUs * 1000. */
+    cpu_mcpu?: number;
+    /** Stable across retries of one acquisition; never reuse for another request. */
+    request_id: string;
+    ssh_public_key?: string;
+    lease: SandboxLeaseInput;
+    /** A capacity reservation this create should draw a bound slot from. */
+    reservation?: string;
+    /**
+     * Ask for a capability scoped to each sandbox this request creates, returned
+     * in the response (`capability` on the receipt, or on each batch member), so
+     * a caller driving many sandboxes mints none of its own. `ops` must be within
+     * the creating token's; `ttl_secs` is capped at 900 and renewable like any
+     * token. Only the request that creates a sandbox gets its capability: a
+     * repeat of the same `request_id` returns none.
+     */
+    capability?: {
+        ops: string[] | CapabilityOps;
+        ttl_secs: number;
+    };
+};
+/** A capability scoped to one sandbox, as returned by a create. */
+export interface SandboxCapability {
+    token: string;
+    token_id: string;
+    ops: string[];
+    /** Epoch milliseconds. */
+    expires_at: number;
+    renewable_until: number;
+}
+/** A batch create: `request_id` names the batch, member `i` is `<request_id>.<i>`. */
+export type CreateSandboxBatchInput = CreateSandboxInput & {
+    /** How many identical sandboxes to create, 1 to 1000. */
+    count: number;
+};
+export type SandboxBatchMemberState = "pending" | "placed" | "failed" | "destroyed";
+export interface SandboxBatchMember {
+    /** Poll this member alone with `sandboxes.acquisition(request_id)`. */
+    request_id: string;
+    id: string;
+    state: SandboxBatchMemberState;
+    /** Present when the create asked for `capability`. */
+    capability?: SandboxCapability;
+}
+export interface SandboxBatch {
+    /** The batch's request id. */
+    request_id: string;
+    count: number;
+    /** Members in each state; a state with no members is absent. */
+    counts: Partial<Record<SandboxBatchMemberState, number>>;
+    members: SandboxBatchMember[];
+}
+export type SandboxBatchResponse = SandboxBatch | {
+    request_id: string;
+    state: "prevented";
+};
+export interface SandboxLeaseInput {
+    /** Initial lease duration, between 60 seconds and 24 hours. */
+    ttl_secs: number;
+    /** Hard lifetime from acquisition, at least ttl_secs and at most 30 days. */
+    renewable_for_secs: number;
+}
+export type CreateCapacityReservationInput = ({
+    /** One immutable template version, pinned for the reservation's life. */
+    template: string;
+    template_resource?: never;
+} | {
+    /** A template resource name: the reservation follows whichever version
+     * is current, even one that does not exist yet, and its bound nodes are
+     * warmed with each new version as it is activated. */
+    template_resource: string;
+    template?: never;
+}) & {
+    /** How many sandboxes of this template/shape to reserve. */
+    count: number;
+    vcpus: number;
+    memory_mib: number;
+    /** How long to hold the reservation, between 1 second and 4 hours. */
+    ttl_secs: number;
+    /** Defaults to `consumable`; `reusable` returns each slot after confirmed destruction.
+     * `warm` keeps `count` free slots on workers that cache a pinned template
+     * version; it takes `template` (not `template_resource`), is never held
+     * against other claims, and a sandbox create naming it is a 400. */
+    mode?: "consumable" | "reusable" | "warm";
+    /** When the capacity must be ready: seconds from now, or an RFC 3339 time
+     * within `ttl_secs`. Absent: as soon as it can be, at the lowest cost. */
+    needed_by?: number | string;
+    /** `shared` (default): any eligible node, free headroom first. `dedicated`:
+     * only hosts dedicated reservations hold, launched for them. A held host
+     * serves only dedicated reservations (of any tenant: they pack), never
+     * ordinary work; a sandbox create naming it waits for one of its slots. */
+    placement?: "shared" | "dedicated";
+    /** With `placement: "dedicated"`, the provider shape to launch: an exact
+     * shape or a family (`c7i`) the fleet can launch (direct EC2: the config's
+     * instance_types). Absent: the planner chooses. */
+    shape?: string;
+    /** Stable retry key, at most 107 ASCII letters, digits, `_` or `-`. */
+    idempotency_key?: string;
+};
+export interface CapacityReservation {
+    id: string;
+    state: "active" | "released" | "expired";
+    /** The version nodes are warmed with; null while a reservation following a
+     * template resource waits for the resource's first version. */
+    template: string | null;
+    /** The template resource this reservation follows, or null when pinned. */
+    template_resource: string | null;
+    count: number;
+    mode: "consumable" | "reusable" | "warm";
+    placement: "shared" | "dedicated";
+    /** The shape a dedicated reservation launches, or null. */
+    shape: string | null;
+    vcpus: number;
+    memory_mib: number;
+    /** Slots consumed by an actual sandbox create. */
+    claimed: number;
+    /** Current slot occupancy for reusable reservations; zero otherwise. */
+    occupied: number;
+    /** Slots bound to a specific node and not yet claimed. */
+    bound: number;
+    /** Bound slots whose node already has the template warm. For warm mode this
+     * counts member nodes at 1 each. */
+    warm: number;
+    /** Warm mode: free slots of the shape on member workers whose template is
+     * ready, as of the last reconcile; zero for other modes. */
+    warm_free: number;
+    expires_at: SystemTimeValue;
+    /** When the capacity must be ready (epoch milliseconds), or null. */
+    needed_by: number | null;
+}
+export interface WaitOptions {
+    /**
+     * Have the gateway hold a still-pending claim for up to this many seconds
+     * and answer as soon as it is placed or fails, with its ports, instead of
+     * answering `pending` at once. The gateway holds at most 55 seconds. A claim
+     * still pending after the hold is returned as `pending`; ask again.
+     */
+    wait_secs?: number;
+}
+/**
+ * Response returned by POST /v1/sandboxes (the gateway has no template field).
+ * The gateway sends a `failed` receipt with HTTP 409, so `create` and
+ * `acquisition` surface it as a `BlackcatApiError` whose `details` this
+ * parser accepts: placement was abandoned and its sandbox torn down, which is
+ * retryable under a new request id rather than a protocol fault.
+ */
+export type CreateSandboxResponse = {
+    request_id: string;
+    state: "prevented";
+} | ({
+    request_id: string;
+    id: string;
+    tier: "boot" | "warm_pool" | "restore";
+    expires_at: SystemTimeValue;
+    renewable_until: SystemTimeValue;
+    /**
+     * Phase-timing breakdown for the launch that placed this sandbox, once one
+     * has committed. Absent while still queued/pending, and for a server that
+     * predates this field.
+     */
+    restore_timing?: RestoreTiming;
+    /** Present when the create asked for `capability` and created this sandbox. */
+    capability?: SandboxCapability;
+} & ({
+    state: "placed";
+    node: string;
+} | {
+    state: "pending";
+    node: string | null;
+} | {
+    state: "failed";
+    node: null;
+    error: string;
+} | {
+    state: "destroyed";
+    node: string | null;
+    error: string;
+}));
+/**
+ * Restore phase breakdown a node reported for a checkpoint launch (Proposal
+ * F, docs/restore-performance.md). `phase_ms` mirrors the node's own
+ * `checkpoint vm timing` log line; `chunk_source` reports how much of the
+ * checkpoint's memory/disk was fetched remotely vs. served locally, how many
+ * UFFD faults and NBD reads this restore actually served (both zero on the
+ * file-restore path), and the checkpoint's logical sizes. `memory_source` is
+ * `"file"` when a node-local materialized copy let this restore skip
+ * UFFD/NBD lazy faulting entirely (fault-free warm restore,
+ * docs/restore-performance.md), or `"uffd"` for the lazy chunk-source path
+ * every checkpoint restore used before it.
+ */
+export interface RestoreTiming {
+    proposal_ms: number;
+    restore_vm_ms: number;
+    commit_ms: number;
+    total_ms: number;
+    phase_ms: {
+        open: number;
+        network: number;
+        firecracker: number;
+        state: number;
+        disk: number;
+        pager: number;
+        load: number;
+        activation: number;
+        /** Milliseconds from the TAP being raised until the guest's gateway and resolver answered; absent from a node that predates it, 0 from a guest that does. */
+        network_ready?: number;
+    };
+    memory_source?: "file" | "uffd";
+    /** The node already held what it restores from as files (a warm restore), so no fetch ran for this claim: the memory, and the disk on a node that clones disks (one that cannot still pages its disk through NBD). Null when the node did not say; absent from a server that predates it. */
+    template_cached?: boolean | null;
+    chunk_source: {
+        remote_requests: number;
+        remote_bytes: number;
+        local_requests?: number;
+        local_bytes?: number;
+        uffd_faults?: number;
+        uffd_fault_bytes?: number;
+        nbd_reads?: number;
+        nbd_read_bytes?: number;
+        logical_memory_bytes: number;
+        logical_disk_bytes: number;
+    };
+}
+export interface Sandbox {
+    id: string;
+    template: string;
+    state: string;
+    node?: string;
+    /** vCPUs the guest has now: the template's, until a cold resize reboots it onto another count. */
+    vcpus: number;
+    /** Current guest memory in MiB (boot memory plus what is plugged). */
+    memory_mib: number;
+    /** Current CPU entitlement in millicores. */
+    cpu_mcpu: number;
+    expires_at: SystemTimeValue;
+    renewable_until: SystemTimeValue;
+}
+/** A short-lived SSH key to authorize on a running sandbox. */
+export interface GrantSshKeyInput {
+    /** One `ssh-ed25519` public key line. */
+    public_key: string;
+    /** Lifetime in seconds, 1 to 86400. The key only matters while connecting. */
+    ttl_secs: number;
+}
+export interface SshKeyGrant {
+    /** Unix milliseconds at which the key stops authenticating. */
+    expires_at: number;
+    /** The login account in the sandbox. */
+    user: string;
+    /** The sandbox's SSH host public key; pin it before connecting. */
+    host_key: string;
+}
+/**
+ * Where and how to reach a port inside a sandbox through the gateway. Send
+ * `headers` with every request and with the WebSocket handshake; the gateway
+ * strips them before the application sees the request. A browser `WebSocket`
+ * cannot send headers, so the WebSocket form is for server-side clients.
+ */
+export interface PortConnection {
+    /** HTTPS URL of the path on the port. */
+    url: string;
+    /** The same target as a `wss:` URL. */
+    websocketUrl: string;
+    headers: {
+        Authorization: string;
+    };
+}
+export interface RenewSandboxResponse {
+    id: string;
+    expires_at: SystemTimeValue;
+    renewable_until: SystemTimeValue;
+}
+/** The CPU a node runs on, as it reports it. */
+export interface CpuIdentity {
+    vendor: string;
+    model_name: string;
+    family: number;
+    model: number;
+    stepping: number;
+    microcode: string;
+    /** Hash of the CPUID feature leaves a guest's CPUID is derived from. */
+    features_hash: string;
+    /** The host is itself a guest (nested virtualization). */
+    nested: boolean;
+}
+/**
+ * Tenant-scoped view returned by GET /v1/fleet. Residents and cached snapshots
+ * are already filtered by the gateway to the caller's tenant.
+ */
+export interface FleetNode {
+    id: string;
+    addr: string;
+    total_mib: number;
+    reserved_mib: number;
+    vcpus: number;
+    health: string;
+    schedulable: boolean;
+    lease_until: SystemTimeValue;
+    committed_mib: number;
+    residents: string[];
+    cached_snapshots: string[];
+    interruption: FleetInterruption | null;
+    /** Charged versus measured memory and the node's pressure state. */
+    memory: FleetNodeMemory;
+    /** Whether the host runs with SMT active. */
+    smt_active: boolean;
+    /** Bytes the worker reserves for cached templates; 0 until it reports one. */
+    cache_budget_bytes: number;
+    /** The node's CPU; absent from nodes older than CPU-aware placement. */
+    cpu?: CpuIdentity | null;
+    /** 1000 charges file-backed clones in full; 2000 charges them at half. */
+    max_memory_ratio_milli: number;
+    max_vcpu_ratio_milli: number;
+    /** How the fleet decides what a sandbox costs. */
+    packing_mode?: "learned" | "manual";
+}
+export type MemoryPressure = "normal" | "high" | "critical";
+export interface FleetNodeMemory {
+    /** What admission charged for the node's residents. */
+    charged_mib: number;
+    /** The residents' sizes before the overcommit discount. */
+    plugged_mib: number;
+    /** Resident memory of the residents' VMMs, shared pages counted per mapper. */
+    measured_rss_mib: number;
+    /** Proportional memory the residents cost; compare with `charged_mib`. */
+    measured_pss_mib: number;
+    /** Memory only one resident maps (Private_Clean + Private_Dirty). */
+    measured_uss_mib: number;
+    host_available_mib: number;
+    psi_some_avg10_milli: number;
+    pressure: MemoryPressure;
+}
+export type FleetTrust = "single_trust" | "multi_tenant";
+export interface ResizeSandboxInput {
+    /**
+     * Target vCPU count. A count different from the sandbox's reboots the guest
+     * cold on its own disk: every process ends, template boot services restart,
+     * processes started by hand do not.
+     */
+    vcpus?: number;
+    /** Target guest memory in MiB: boot memory plus a multiple of 128. */
+    memory_mib?: number;
+    /** Target CPU entitlement in millicores. */
+    cpu_mcpu?: number;
+    /** Drop the guest's page caches before a shrink. Defaults to true. */
+    drop_caches?: boolean;
+    /** Stable across retries of one resize; generated when omitted. */
+    request_id?: string;
+}
+/** The size a resize reached. A shrink the guest could not fully honour reports what it reached. */
+export interface SandboxResize {
+    id: string;
+    state: "placed";
+    request_id: string;
+    /** True when the guest was rebooted to change its vCPU count. */
+    cold: boolean;
+    vcpus: number;
+    memory_mib: number;
+    cpu_mcpu: number;
+    /** False when the guest stopped short of the requested memory. */
+    reached_target: boolean;
+    elapsed_ms: number;
+    /** Cold resizes only: durable processes the reboot ended. */
+    processes_ended?: number;
+    /** Cold resizes only: where the reboot spent its time, in milliseconds. */
+    phases?: {
+        quiesce_ms: number;
+        stop_ms: number;
+        boot_ms: number;
+        plug_ms: number;
+        handshake_ms: number;
+        health_ms: number;
+    };
+    /** Cold resizes only: unexpired SSH grants installed again, and ones that failed. */
+    ssh_grants_restored?: number;
+    ssh_grants_failed?: number;
+}
+export interface FleetInterruption {
+    reason: string;
+    deadline: SystemTimeValue;
+}
+export interface FleetResponse {
+    nodes: FleetNode[];
+    fleet_trust: FleetTrust;
+    /** `native`, or a CPU template (`t2`, `t2s`, `t2cl`, `t2a`). */
+    cpu_baseline?: string;
+}
+export interface TemplateRefreshPolicy {
+    interval_seconds: number;
+    plugin_installation: string;
+}
+export interface ConfigureTemplateResourceInput {
+    keep_versions: number;
+    refresh: TemplateRefreshPolicy | null;
+}
+export interface TemplateResource {
+    name: string;
+    current_version_id: string;
+    retention: {
+        keep_versions: number;
+    };
+    refresh: TemplateRefreshPolicy | null;
+    next_refresh_at: number | null;
+    last_refresh?: unknown;
+}
+export interface ExecInput {
+    command: string;
+    args: string[];
+    cwd: string;
+    /** Positive guest execution budget; effects before timeout are not undone. */
+    timeout_ms: number;
+    /** Optional bounded stdin for the streaming EXEC endpoint. */
+    stdin?: number[];
+}
+export interface ExecResult {
+    exit_code: number | null;
+    timed_out: boolean;
+    stdout: Uint8Array;
+    stderr: Uint8Array;
+}
+export interface ExecStreamChunk {
+    stdout: Uint8Array;
+    stderr: Uint8Array;
+    done: boolean;
+    exit_code: number | null;
+    timed_out: boolean;
+}
+export type ProcessState = "starting" | "running" | "succeeded" | "failed" | "timed_out" | "cancelled" | "interrupted";
+export interface ProcessStartInput {
+    command: string;
+    args: string[];
+    cwd: string;
+    env: Array<[string, string]>;
+    timeout_ms: number;
+    output_limit_bytes: number;
+    /** Optional payload delivered once and followed by EOF. Maximum 512 KiB. */
+    stdin?: Uint8Array;
+}
+export interface ProcessRecord {
+    id: string;
+    sandbox_id: string;
+    state: ProcessState;
+    exit_code: number | null;
+    stdout_bytes: number;
+    stderr_bytes: number;
+    stdout_truncated: boolean;
+    stderr_truncated: boolean;
+    failure: string | null;
+    created_at: number;
+    updated_at: number;
+    terminal_at: number | null;
+}
+export interface ProcessLogs {
+    stdout: Uint8Array;
+    stderr: Uint8Array;
+    next_stdout_offset: number;
+    next_stderr_offset: number;
+    stdout_truncated: boolean;
+    stderr_truncated: boolean;
+    state: ProcessState;
+}
+export interface ProcessLogsResponse {
+    process: ProcessRecord;
+    logs: ProcessLogs;
+}
+export interface FileReadChunk {
+    data: Uint8Array;
+    offset: number;
+    eof: boolean;
+}
+export interface ReadFileInput {
+    path: string;
+    offset?: number;
+    /** Total bytes to read. Omit to read through EOF. */
+    length?: number;
+    /** Per-request chunk size; defaults to the gateway's maximum. */
+    chunk_size?: number;
+}
+export interface WriteFileInput {
+    path: string;
+    data: Uint8Array;
+    offset?: number;
+    truncate?: boolean;
+}
+export interface WriteFileStreamInput {
+    path: string;
+    data: AsyncIterable<Uint8Array>;
+    offset?: number;
+    truncate?: boolean;
+}
+export interface MintTokenInput {
+    sandbox?: string;
+    ops: CapabilityOps;
+    ttl_secs: number;
+}
+/** JSON representation emitted by serde for Rust's SystemTime. */
+export interface SystemTimeValue {
+    secs_since_epoch: number;
+    nanos_since_epoch: number;
+}
+export interface MintTokenResponse {
+    token: string;
+    token_id: string;
+    /** Capability timestamps are epoch milliseconds. */
+    expires_at: number;
+    renewable_until: number;
+}
+export interface RenewTokenResponse {
+    expires_at: number;
+}
+export declare class BlackcatApiError extends Error {
+    readonly status: number;
+    /** Stable gateway error code when one is provided. */
+    readonly code?: string;
+    readonly retryAfter?: number;
+    readonly requestId?: string;
+    readonly details: unknown;
+    constructor(status: number, message: string, details: unknown, retryAfter?: number, requestId?: string);
+}
+declare const MAX_FILE_CHUNK: number;
+declare const MAX_FILE_READ_CHUNK = 1000000;
+declare const MAX_PROCESS_STDIN: number;
+declare const MAX_EXEC_STDIN: number;
+export declare function epochMillis(value: unknown, field: string): number;
+export declare function parseCreateSandboxResponse(value: unknown, requestId: string): CreateSandboxResponse;
+export declare function parseSandboxBatch(value: unknown, requestId: string): SandboxBatchResponse;
+export declare function assertSecureBlackcatGatewayUrl(baseUrl: string): void;
+declare class GatewayClient {
+    readonly baseUrl: string;
+    readonly apiKey?: string;
+    token?: string;
+    tokenId?: string;
+    tokenExpiresAt?: number;
+    readonly renewCapability?: () => Promise<MintTokenResponse>;
+    readonly caPem?: string;
+    readonly fetcher: FetchFunction;
+    private renewalInFlight?;
+    constructor(options: BlackcatClientOptions);
+    credential(kind: "apiKey" | "token" | "either"): string;
+    json<T>(method: string, path: string, body?: unknown, kind?: "apiKey" | "token" | "either", timeout?: false, signal?: AbortSignal, extraHeaders?: HeadersInit): Promise<T>;
+    raw(method: string, path: string, body?: BodyInit, kind?: "apiKey" | "token" | "either", contentType?: string, timeout?: false, signal?: AbortSignal): Promise<Response>;
+    renewIfNeeded(signal?: AbortSignal): Promise<void>;
+    stream(method: string, path: string, body?: BodyInit, kind?: "apiKey" | "token" | "either", contentType?: string, renew?: boolean, signal?: AbortSignal): AsyncGenerator<Uint8Array>;
+}
+declare class TemplatesResource {
+    private readonly client;
+    constructor(client: GatewayClient);
+    create(input: CreateTemplateInput): Promise<CreateTemplateResponse>;
+    list(): Promise<Template[]>;
+    /**
+     * Upload a `docker save` / OCI archive as a build input. The image is named
+     * by its own content, so re-uploading the same bytes is free, and a build
+     * that names it needs no registry credentials anywhere.
+     */
+    uploadImage(archive: BodyInit, options?: {
+        signal?: AbortSignal;
+    }): Promise<UploadedImage>;
+    activate(id: string): Promise<{
+        id: string;
+        name: string;
+        version: number;
+    }>;
+}
+declare class TemplateResourcesResource {
+    private readonly client;
+    constructor(client: GatewayClient);
+    get(name: string): Promise<TemplateResource>;
+    configure(name: string, input: ConfigureTemplateResourceInput): Promise<TemplateResource>;
+    delete(name: string): Promise<void>;
+}
+declare class TemplateBuildsResource {
+    private readonly client;
+    constructor(client: GatewayClient);
+    create(input: CreateTemplateBuildInput): Promise<{
+        build: TemplateBuildRecord;
+    }>;
+    get(id: string): Promise<{
+        build: TemplateBuildRecord;
+    }>;
+    retry(id: string): Promise<{
+        build: TemplateBuildRecord;
+    }>;
+}
+declare class TokensResource {
+    private readonly client;
+    constructor(client: GatewayClient);
+    mint(input: MintTokenInput): Promise<MintTokenResponse>;
+    renew(id: string): Promise<RenewTokenResponse>;
+    revoke(id: string): Promise<void>;
+}
+declare class FleetResource {
+    private readonly client;
+    constructor(client: GatewayClient);
+    /** List the nodes and this tenant's residents/snapshots visible to INSPECT. */
+    list(): Promise<FleetResponse>;
+}
+declare class ReservationsResource {
+    private readonly client;
+    constructor(client: GatewayClient);
+    /** Reserve capacity for a burst of sandboxes of one template/shape. */
+    create(input: CreateCapacityReservationInput): Promise<CapacityReservation>;
+    get(id: string): Promise<CapacityReservation>;
+    /** Release early. Unclaimed slots free immediately; bound nodes then fall
+     * back to the normal empty-worker scale-in grace period. */
+    release(id: string): Promise<CapacityReservation>;
+    renew(id: string, input: {
+        ttl_secs: number;
+        idempotency_key: string;
+    }): Promise<CapacityReservation>;
+}
+declare class SandboxesResource {
+    private readonly client;
+    constructor(client: GatewayClient);
+    /** List all of this tenant's non-destroyed sandboxes, including hibernated ones. */
+    list(): Promise<Sandbox[]>;
+    /**
+     * Acquire once under a caller-owned request ID. Repeat the exact request to
+     * recover a lost response. A pending receipt is not an executable sandbox;
+     * no automatic retry, new ID, or replacement allocation is synthesized here.
+     */
+    create(input: CreateSandboxInput, options?: WaitOptions): Promise<CreateSandboxResponse>;
+    /**
+     * Create `count` identical sandboxes under one request ID. Resolves as soon
+     * as the whole batch is durably recorded; nothing waits on a restore.
+     * Repeat the exact request to recover a lost response: member IDs are
+     * stable. Poll `batch` for counts by state, or a member with `acquisition`.
+     */
+    createBatch(input: CreateSandboxBatchInput): Promise<SandboxBatchResponse>;
+    /** Counts by state and every member of a batch created with `createBatch`. */
+    batch(requestId: string): Promise<SandboxBatchResponse>;
+    acquisition(requestId: string, options?: WaitOptions): Promise<CreateSandboxResponse>;
+    /**
+     * Fence an acquisition request ID before its create is recorded, or destroy
+     * the allocation when the create has already won.
+     */
+    cancelAcquisition(requestId: string): Promise<CreateSandboxResponse>;
+    get(id: string): Promise<Sandbox>;
+    /** Extend the soft expiry without moving the immutable hard deadline. */
+    renew(id: string, ttl_secs: number): Promise<RenewSandboxResponse>;
+    /**
+     * Authorize `public_key` on a running sandbox for `ttl_secs`, whether or not
+     * it was created with a key. Needs the sandbox-scoped exec capability. Connect
+     * with `CONNECT /v1/sandboxes/{id}/ssh`, or let `blackcat sandbox ssh` do it.
+     */
+    grantSshKey(id: string, input: GrantSshKeyInput): Promise<SshKeyGrant>;
+    /**
+     * Describe a tunnel to `port` (any TCP port the sandbox listens on, not only
+     * a declared preview port), at `path` on that port. Needs the sandbox-scoped
+     * exec capability, which is checked once when a connection opens: an open
+     * WebSocket outlives it. Renews a nearly expired capability first, so call
+     * this again for each new connection. A `CONNECT` to `url` instead returns
+     * a raw byte stream, as `blackcat sandbox port-forward` uses.
+     */
+    portConnection(id: string, port: number, path?: string): Promise<PortConnection>;
+    exec(id: string, input: ExecInput): Promise<ExecResult>;
+    execStream(id: string, input: ExecInput): AsyncGenerator<ExecStreamChunk>;
+    startProcess(id: string, requestId: string, input: ProcessStartInput): Promise<ProcessRecord>;
+    getProcess(id: string, processId: string): Promise<ProcessRecord>;
+    processLogs(id: string, processId: string, input?: number | {
+        stdout_offset?: number;
+        stderr_offset?: number;
+        max_bytes?: number;
+    }): Promise<ProcessLogsResponse>;
+    cancelProcess(id: string, processId: string): Promise<ProcessRecord>;
+    prepare(id: string, input: {
+        parameters: Record<string, string>;
+        secrets: Record<string, string>;
+    }, idempotencyKey: string): Promise<PrepareSandboxResponse>;
+    logs(id: string): AsyncGenerator<Uint8Array>;
+    readFileChunk(id: string, input: {
+        path: string;
+        offset: number;
+        length: number;
+    }): Promise<FileReadChunk>;
+    readFileStream(id: string, input: ReadFileInput): AsyncGenerator<FileReadChunk>;
+    readFile(id: string, input: ReadFileInput): Promise<Uint8Array>;
+    writeFileChunk(id: string, input: {
+        path: string;
+        offset: number;
+        data: Uint8Array;
+        truncate: boolean;
+    }): Promise<void>;
+    writeFileStream(id: string, input: WriteFileStreamInput): Promise<number>;
+    writeFile(id: string, input: WriteFileInput): Promise<number>;
+    /**
+     * Capture a restore point. The sandbox keeps running, and the returned
+     * template version is what it restarts from.
+     */
+    snapshot(id: string): Promise<{
+        template: string;
+    }>;
+    /**
+     * Pause a running sandbox's VM in memory: processes, memory and network
+     * state are kept, nothing is captured, and `resume` continues it where it
+     * stopped. Memory stays resident and charged (`hibernate` frees it); the CPU
+     * entitlement is released. Idempotent. Requests that need the guest are
+     * refused while it is paused.
+     */
+    pause(id: string): Promise<void>;
+    hibernate(id: string, input?: {
+        mode: HibernateMode;
+    }): Promise<void>;
+    /**
+     * Change a running sandbox's memory (live, within its checkpoint's hotplug
+     * region) and CPU entitlement; processes keep running. A `vcpus` different
+     * from the sandbox's is a cold reboot instead (`cold: true`). Repeating the
+     * same `request_id` replays the result.
+     */
+    resize(id: string, input: ResizeSandboxInput): Promise<SandboxResize>;
+    /** Continue a paused sandbox, or restore a hibernated one. */
+    resume(id: string): Promise<void>;
+    /**
+     * Destroy a sandbox. Resolves when its VM is dead and the node has released
+     * its capacity, not when the node has finished removing its network device,
+     * jail and cgroup: that follows in the background, usually within a second.
+     * Destroying a sandbox that is already destroyed succeeds.
+     */
+    destroy(id: string): Promise<void>;
+}
+export declare class BlackcatClient extends GatewayClient {
+    readonly templates: TemplatesResource;
+    readonly templateResources: TemplateResourcesResource;
+    readonly templateBuilds: TemplateBuildsResource;
+    readonly sandboxes: SandboxesResource;
+    readonly tokens: TokensResource;
+    readonly fleet: FleetResource;
+    readonly reservations: ReservationsResource;
+    constructor(options: BlackcatClientOptions);
+    /**
+     * Create a client that uses a sandbox capability for resource operations.
+     * Passing the complete mint response enables renewal during long streams.
+     */
+    withToken(token: string | MintTokenResponse, renewCapability?: () => Promise<MintTokenResponse>): BlackcatClient;
+}
+export { MAX_EXEC_STDIN, MAX_FILE_CHUNK, MAX_FILE_CHUNK as MAX_FILE_WRITE_CHUNK, MAX_FILE_READ_CHUNK, MAX_PROCESS_STDIN, };