@scalebrowser/sdk 0.2.0

package/dist/index.d.cts

@@ -0,0 +1,1613 @@
+import WebSocket from 'ws';
+
+/**
+ * Error model — stable numeric API error codes (SPEC §5,
+ * `crates/core/src/error.rs`) and the typed exceptions the SDK throws.
+ */
+/** Stable numeric API error codes (4001–4010). */
+declare const ErrorCode: {
+    readonly NotFound: 4001;
+    readonly ProxyGeo: 4002;
+    readonly Capacity: 4003;
+    readonly EngineMissing: 4004;
+    readonly Preflight: 4005;
+    readonly AlreadyRunning: 4006;
+    /** Retired: the removed Methode-D (VM) tier produced this. Reserved (never reused)
+     * to match the server's append-only code contract; never returned now. */
+    readonly VmProvisionFailed: 4007;
+    /** The subscription's abo-wide concurrent-browser allowance is used up (DEC-012).
+     * Distinct from Capacity (4003 = this machine is full, wait): the caller's move
+     * is to stop a running browser anywhere or upgrade the plan. */
+    readonly ConcurrencyLimit: 4008;
+    readonly Unauthorized: 4010;
+};
+type ErrorCodeValue = (typeof ErrorCode)[keyof typeof ErrorCode];
+/** Error body shape: `{ code, message }` (docs/features/api.md). */
+interface ApiErrorBody {
+    code?: number;
+    message?: string;
+}
+/** Base class for every error this SDK throws — lets callers `catch` one type. */
+declare class ScalebrowserError extends Error {
+    constructor(message: string);
+}
+/**
+ * A typed transport/contract error. Carries the HTTP `status` and the daemon's
+ * numeric `code` so callers (and the auth layer) can react — e.g. 401 / code
+ * 4010 → re-authenticate.
+ */
+declare class ApiError extends ScalebrowserError {
+    readonly status: number;
+    readonly code?: number;
+    readonly body?: ApiErrorBody;
+    constructor(status: number, body?: ApiErrorBody, fallbackMessage?: string);
+    /** True for auth failures that must trigger re-authentication. */
+    get isAuthError(): boolean;
+    /** Short label for the error code, if any. */
+    get codeLabel(): string | undefined;
+}
+/** A network-level failure (daemon unreachable, socket error, fetch rejected). */
+declare class NetworkError extends ScalebrowserError {
+    readonly cause?: unknown;
+    constructor(message: string, cause?: unknown);
+}
+/** A CDP command that returned an `error` frame, or a closed CDP connection. */
+declare class CdpError extends ScalebrowserError {
+    readonly code: number;
+    readonly data?: unknown;
+    constructor(code: number, message: string, data?: unknown);
+}
+/** Narrow an unknown thrown value to a user-facing message. */
+declare function errorMessage(err: unknown): string;
+
+interface Screen {
+    width: number;
+    height: number;
+    avail_width: number;
+    avail_height: number;
+    color_depth: number;
+    pixel_depth: number;
+    device_pixel_ratio: number;
+    orientation: string;
+}
+interface Locale {
+    language: string;
+    languages: string[];
+    accept_language: string;
+}
+interface WebGl {
+    vendor: string;
+    renderer: string;
+    unmasked_vendor: string;
+    unmasked_renderer: string;
+    version: string;
+    shading_language_version: string;
+}
+interface WebGpu {
+    present: boolean;
+    adapter: string;
+    vendor: string;
+    architecture: string;
+    device: string;
+    description: string;
+}
+interface AudioProps {
+    sample_rate: number;
+    base_latency: number;
+    max_channel_count: number;
+    output_channel_count: number;
+}
+interface SpeechVoice {
+    name: string;
+    lang: string;
+    local_service: boolean;
+    default: boolean;
+}
+interface GpuPersona {
+    backend: string;
+    vendor: string;
+    model: string;
+}
+interface Brand {
+    brand: string;
+    version: string;
+}
+interface ClientHints {
+    brands: Brand[];
+    full_version_list: Brand[];
+    platform: string;
+    platform_version: string;
+    architecture: string;
+    bitness: string;
+    model: string;
+    mobile: boolean;
+    ua_full_version: string;
+    wow64: boolean;
+}
+interface PermissionDefaults {
+    notifications: string;
+    geolocation: string;
+    camera: string;
+    microphone: string;
+}
+interface MediaDevice {
+    kind: string;
+    label: string;
+    device_id: string;
+    group_id: string;
+}
+interface PersonaMisc {
+    webdriver: boolean;
+    get_installed_related_apps: boolean;
+    max_touch_points: number;
+    pdf_viewer_enabled: boolean;
+    headless_guards: boolean;
+}
+interface Persona {
+    os: OsFamily;
+    user_agent: string;
+    platform: string;
+    browser_version: string;
+    screen: Screen;
+    hardware_concurrency: number;
+    device_memory: number;
+    timezone: string;
+    locale: Locale;
+    webgl: WebGl;
+    webgpu: WebGpu;
+    fonts: string[];
+    noise_seed: number;
+    audio: AudioProps;
+    speech_voices: SpeechVoice[];
+    gpu_persona: GpuPersona;
+    client_hints: ClientHints;
+    permissions: PermissionDefaults;
+    media_devices: MediaDevice[];
+    misc: PersonaMisc;
+}
+
+/**
+ * Wire types — a 1:1 mirror of the daemon's serialized domain model
+ * (`crates/core/src/model.rs`, `persona.rs`, `events.rs`) and the endpoint
+ * contract in `docs/features/api.md`. Mirrored against `web-ui/src/api/types/`
+ * (a directory of split files behind the `web-ui/src/api/types.ts` barrel), and
+ * that mirror is ENFORCED: `web-ui/src/test/sdk-type-mirror.test.ts` compares
+ * every shared exported declaration and goes red on drift. The Python SDK
+ * (`sdks/python/src/scalebrowser/models*.py`) carries the same shapes by hand,
+ * deliberately without a gate — a TS↔pydantic comparator is its own tool.
+ *
+ * All Rust enums serialize `snake_case` (serde `rename_all`). Timestamps are
+ * unix seconds (`number`, Rust `i64`). The truth for any disagreement is the
+ * UNION of the Rust route shapes, never one serde struct (create/delete answer
+ * the bare `Profile`, list/get the flattened `ProfileView`).
+ */
+/** `RuntimeState` (AC-PR-004). */
+type RuntimeState = 'stopped' | 'starting' | 'running' | 'crashed';
+declare const RUNTIME_STATES: readonly RuntimeState[];
+/** `HostMode` (PRD §B, DEC-004). Default `linux_engine_spoof`. */
+type HostMode = 'linux_engine_spoof' | 'local_native_windows';
+declare const HOST_MODES: readonly HostMode[];
+/** `GeoMode` (AC-PX-002). Default `follow_exit`. */
+type GeoMode = 'strict_expected' | 'follow_exit' | 'off';
+declare const GEO_MODES: readonly GeoMode[];
+/** `ProxyKind` (AC-PX-001). */
+type ProxyKind = 'http' | 'socks5' | 'gateway';
+declare const PROXY_KINDS: readonly ProxyKind[];
+/** `Rotation` (AC-PX-002). */
+type Rotation = 'sticky' | 'rotating';
+declare const ROTATIONS: readonly Rotation[];
+/** `SessionKind` (AC-ST-002). */
+type SessionKind = 'cookies' | 'local_storage' | 'indexed_db' | 'service_worker';
+type OsFamily = 'windows' | 'macos' | 'linux';
+/** How protected a profile is right now, decided by the daemon WITHOUT starting a
+ *  browser — it runs the same gates the launch runs. `blocked` means the launch
+ *  will refuse this profile; `warn` means it starts but something measurably
+ *  weakens it (most often a missing proxy). */
+type ProtectionLevel = 'ok' | 'warn' | 'blocked';
+interface ProtectionStatus {
+    level: ProtectionLevel;
+    /** Plain-language findings, worst first. Empty exactly when `level` is `ok`. */
+    reasons: string[];
+}
+/** A browser identity profile (`profiles`). */
+interface Profile {
+    id: string;
+    name: string;
+    runtime_state: RuntimeState;
+    enabled: boolean;
+    crash_reason: string | null;
+    pid: number | null;
+    run_lock: string | null;
+    seed: string;
+    engine_version: string;
+    persona: Persona;
+    host_mode: HostMode;
+    gpu_persona: string | null;
+    group_id: string | null;
+    proxy_id: string | null;
+    geo_mode: GeoMode;
+    expected_country: string | null;
+    data_dir: string;
+    created_at: number;
+    last_open_at: number | null;
+    /** Additive (a daemon predating it simply omits the field). Present on list/get
+     *  (`ProfileView`), absent on create/delete/bulk, which answer the bare profile. */
+    protection?: ProtectionStatus;
+    /**
+     * Platform slugs this profile has a stored login for, sorted by the daemon.
+     * Additive — a daemon predating the credential vault simply omits it.
+     */
+    platforms?: string[];
+}
+interface Group {
+    id: string;
+    name: string;
+    created_at: number;
+}
+/**
+ * Operating config: what the created profiles DO. Every key mirrors a
+ * `POST /v1/profiles` body field. The daemon refuses an unknown key with a 400
+ * rather than dropping it — a preset makes up to 1000 profiles, so a swallowed
+ * key is a thousand wrong ones.
+ */
+interface PresetConfig {
+    /** Pin the batch to one engine build. Omit for per-profile version diversity. */
+    engine_version?: string | null;
+    host_mode?: HostMode | null;
+    geo_mode?: GeoMode | null;
+    /** The geo GATE's expectation — not the persona's drawn region. */
+    expected_country?: string | null;
+    group_id?: string | null;
+    proxy_id?: string | null;
+    /**
+     * Library ids every profile of the batch is created with. Empty is normal —
+     * about half of real Chrome users carry no extension.
+     *
+     * An id the library no longer holds refuses the whole batch: a thousand profiles
+     * that silently differ from the preset look exactly like correct ones.
+     */
+    extensions?: string[];
+}
+/**
+ * Generator constraints: what the created profiles ARE. Exactly one axis,
+ * because an axis is only honest here if the daemon does not overwrite it at
+ * launch — the GPU, screen, DPR and Chrome version all are.
+ */
+interface PresetConstraints {
+    /**
+     * ISO-3166 alpha-2 from `GET /v1/persona/constraints`. Masks the persona's
+     * locale draw, pinning language, timezone and speech voices together.
+     */
+    country?: string | null;
+}
+interface Preset {
+    id: string;
+    name: string;
+    constraints: PresetConstraints;
+    config: PresetConfig;
+    created_at: number;
+}
+/** `GET /v1/persona/constraints` — the values a preset may constrain to. */
+interface PersonaConstraintOptions {
+    countries: string[];
+}
+/** Proxy — credentials are write-only (`#[serde(skip_serializing)]`); never returned. */
+interface Proxy {
+    id: string;
+    kind: ProxyKind;
+    host: string;
+    port: number;
+    rotation: Rotation;
+    last_exit_ip: string | null;
+    last_country: string | null;
+    last_check_at: number | null;
+    healthy: boolean | null;
+    created_at: number;
+}
+/** Per-detector outcome; `skip` means the page could not be evaluated, NOT a pass. */
+type AuditVerdict = 'pass' | 'warn' | 'fail' | 'skip' | 'error';
+interface AuditDetectorReport {
+    id: string;
+    verdict: AuditVerdict;
+    detail: string;
+}
+interface AuditReport {
+    schema_version: number;
+    timestamp: string;
+    overall: AuditVerdict;
+    detectors: AuditDetectorReport[];
+}
+interface AuditStatus {
+    profile_id: string;
+    /** `idle` (never run since the daemon started), `running`, or `finished`. */
+    state: 'idle' | 'running' | 'finished';
+    started_at?: number;
+    finished_at?: number;
+    /** Why the RUN failed — distinct from a detector's own `skip`. */
+    error?: string;
+    report?: AuditReport;
+}
+interface CreateGroupBody {
+    name: string;
+}
+type UpdateGroupBody = Partial<CreateGroupBody>;
+interface CreatePresetBody {
+    name: string;
+    constraints?: PresetConstraints;
+    config?: PresetConfig;
+}
+type UpdatePresetBody = Partial<CreatePresetBody>;
+interface SessionExportBody {
+    password: string;
+    kinds?: SessionKind[];
+}
+interface SessionExportResult {
+    bundle: string;
+    /**
+     * Whether the cookies came out of the RUNNING browser for this export.
+     *
+     * `false` means the bundle carries only what was stored earlier, which for a
+     * stopped profile is all there can be: a browser holds its jar in its own
+     * process. Export while the profile runs for a current session.
+     */
+    harvested?: boolean;
+    /** Why the bundle is thinner than it could be, when it is. */
+    note?: string;
+}
+interface SessionImportBody {
+    password: string;
+    bundle: string;
+}
+/**
+ * Trusted-input payload (`POST /v1/profiles/:id/input`, G8, AC-API-003). Only
+ * `action` and `humanize` are fixed by `docs/features/api.md`; the per-action coordinate
+ * fields below are the SDK's contract assumption for the daemon's input crate.
+ */
+type TrustedInputBody = {
+    action: 'move';
+    x: number;
+    y: number;
+    width?: number;
+    humanize?: boolean;
+} | {
+    action: 'click';
+    x: number;
+    y: number;
+    button?: string;
+    click_count?: number;
+    width?: number;
+    humanize?: boolean;
+} | {
+    action: 'type';
+    text: string;
+    humanize?: boolean;
+} | {
+    action: 'scroll';
+    x: number;
+    y: number;
+    delta_x?: number;
+    delta_y?: number;
+    humanize?: boolean;
+};
+/** Who is driving: an agent holding a reservation, or a person at a window. */
+type RunActor = 'agent' | 'human';
+/** How a run ended. `reached`/`partial` appear only when a source claimed it. */
+type RunOutcome = 'running' | 'reached' | 'partial' | 'blocked' | 'interrupted' | 'unknown';
+/** What kind of thing a trail entry is. */
+type StepKind = 'page' | 'action' | 'interruption';
+/** The element a step acted on, as it can still be recognised later. */
+interface StepTarget {
+    role: string;
+    name: string;
+}
+/** One tool call, as the operator gets to read it back. */
+interface RunStep {
+    /** Position within the run, starting at 1. */
+    seq: number;
+    at: number;
+    duration_ms: number | null;
+    kind: StepKind;
+    /** The tool name; `null` for a synthetic `page` step. */
+    tool: string | null;
+    target: StepTarget | null;
+    /** A short human line. Carries typed text unless `redacted`. */
+    summary: string | null;
+    redacted: boolean;
+    /** Set on `page` steps. */
+    url: string | null;
+    /** Path of the still under the runs API; the image is fetched separately. */
+    shot_path: string | null;
+    /**
+     * What the call produced, in one line — "3 blocks, 122 characters",
+     * "no visible change · 14 elements".
+     *
+     * `summary` says what the agent asked for, this says what came back. A step
+     * recorded before this field existed has `null`.
+     */
+    result: string | null;
+    error: string | null;
+}
+/** What one running profile is showing. */
+interface ProfileActivity {
+    profile_id: string;
+    profile_name: string;
+    url: string;
+    title: string;
+    actor: RunActor;
+    /** Unix seconds this address was first seen. */
+    since: number;
+    /** The browser did not answer the last sweep; this is the last known value. */
+    stale: boolean;
+}
+
+/**
+ * A daemon lifecycle event. Named `LifecycleEvent` (not `Event`) to avoid
+ * clashing with the global `Event`; also re-exported as `Event` for parity with
+ * the web-ui contract.
+ *
+ * Each event carries the whole state of the thing it is about, so a reader never
+ * has to fetch to act on one. The exception is an image: `RunStep.shot_path` is
+ * a reference, and the picture is already on disk when the event arrives.
+ */
+type LifecycleEvent = {
+    type: 'profile_state_changed';
+    profile_id: string;
+    from: RuntimeState;
+    to: RuntimeState;
+    at: number;
+} | {
+    type: 'profile_started';
+    profile_id: string;
+    cdp_ws: string;
+    headless: boolean;
+    at: number;
+} | {
+    type: 'profile_stopped';
+    profile_id: string;
+    at: number;
+} | {
+    type: 'profile_crashed';
+    profile_id: string;
+    reason: string;
+    at: number;
+} | {
+    type: 'preflight_failed';
+    profile_id: string;
+    detail: string;
+    at: number;
+} | {
+    type: 'proxy_checked';
+    proxy_id: string;
+    healthy: boolean;
+    country: string | null;
+    at: number;
+} | {
+    type: 'capacity_rejected';
+    profile_id: string;
+    at: number;
+}
+/** An agent declared a task on a profile, or one was opened for undeclared work. */
+ | {
+    type: 'run_started';
+    run_id: string;
+    profile_id: string;
+    actor: RunActor;
+    goal: string;
+    at: number;
+}
+/** One tool call was appended to a run's trail — the whole stored step. */
+ | {
+    type: 'run_step';
+    run_id: string;
+    profile_id: string;
+    step: RunStep;
+    at: number;
+} | {
+    type: 'run_finished';
+    run_id: string;
+    profile_id: string;
+    outcome: RunOutcome;
+    at: number;
+}
+/** A running profile's row appeared, or something about it is different. */
+ | {
+    type: 'profile_activity_changed';
+    activity: ProfileActivity;
+    at: number;
+}
+/** A profile is no longer running: its row goes away. */
+ | {
+    type: 'profile_activity_gone';
+    profile_id: string;
+    at: number;
+}
+/**
+ * Frames were lost; re-read rather than carry on. Raised when the daemon
+ * notices this connection fell behind. `dropped` counts what it skipped.
+ */
+ | {
+    type: 'resync';
+    dropped: number;
+    at: number;
+};
+/**
+ * An event as it arrives, with its position in this connection's stream.
+ *
+ * The daemon numbers every frame, starting at 1. A jump means frames were lost —
+ * the only way to tell "nothing happened" from "something happened and I did not
+ * get it". Optional so a daemon predating the numbering still type-checks.
+ */
+type StreamedEvent = LifecycleEvent & {
+    seq?: number;
+};
+
+/**
+ * Live lifecycle event stream (`GET /v1/events`, AC-API-003).
+ *
+ * Read as `text/event-stream` over `fetch` (so the Bearer header is attached —
+ * the browser `EventSource` cannot do that) and reconnect with backoff. A
+ * `/v1/ws` websocket carries the same events; SSE is sufficient for one-way
+ * fan-out. Mirrors `web-ui/src/api/events.ts`.
+ */
+
+/** Injectable `fetch` — defaults to the global at call time. */
+type FetchLike = typeof globalThis.fetch;
+type StreamStatus = 'connecting' | 'open' | 'closed';
+interface StreamParams {
+    baseUrl: string;
+    token?: string | null;
+    fetch?: FetchLike;
+    /** When unauthorized (401 / code 4010), stop and notify instead of retrying. */
+    onUnauthorized?: () => void;
+}
+interface StreamHandlers {
+    onEvent: (event: LifecycleEvent) => void;
+    onStatus?: (status: StreamStatus) => void;
+}
+/**
+ * Subscribe to the lifecycle event stream. Returns an unsubscribe function that
+ * aborts the connection and stops reconnection.
+ *
+ * **Loss is reported, never swallowed.** Two things can cost frames, and both
+ * end in the same synthetic `resync` event so a reader has one case to handle:
+ * a jump in the numbering (a frame the daemon sent and this side did not get),
+ * and a reconnect (a gap of unknown length). A third, the daemon noticing that
+ * this connection fell behind, arrives as a real `resync` from the other side.
+ *
+ * The FIRST connection is deliberately not a reconnect: nothing was subscribed
+ * before it, so there is nothing a gap could have cost.
+ */
+declare function subscribeEvents(params: StreamParams, handlers: StreamHandlers): () => void;
+/** Extract and JSON-parse the `data:` payload of a single SSE frame. */
+declare function parseSseFrame(frame: string): StreamedEvent | null;
+/**
+ * `for await (const event of eventStream({...}))` ergonomics over
+ * {@link subscribeEvents}. Break out of the loop (or call `.return()`) to
+ * unsubscribe.
+ */
+declare function eventStream(params: StreamParams): AsyncIterableIterator<LifecycleEvent>;
+
+/**
+ * What the browser asks (interruptions), the bytes that go in and out
+ * (artifacts), and what the licence says (account).
+ *
+ * Interruption shapes mirror `web-ui/src/api/types/credentials.ts`, the shared
+ * source of contract truth.
+ */
+/** What an operator has taken out of an agent's hands. */
+type InterruptionLock = 'always_block' | 'always_allow' | 'agent_decides';
+/**
+ * One answer, in the browser's OWN vocabulary — hence `allowOnce` in camelCase
+ * while everything else in this API is snake_case. The daemon's enum is
+ * `#[serde(rename_all = "camelCase")]`; sending `allow_once` is a 400.
+ */
+type InterruptionChoice = 'allow' | 'allowOnce' | 'block' | 'dismiss';
+interface InterruptionLockRow {
+    kind: string;
+    /** Null for the account-wide row. */
+    profile_id: string | null;
+    decision: InterruptionLock;
+}
+/** What applies right now for one kind, account-wide. */
+interface EffectiveInterruptionLock {
+    kind: string;
+    /** Null means the agent decides. */
+    decision: InterruptionLock | null;
+}
+/**
+ * Everything about locks in one call, `effective` included.
+ *
+ * The daemon computes `effective` with the same function the launch path uses.
+ * Recomputing it yourself would be a second opinion, and code that disagrees
+ * with the browser is worse than code that shows nothing.
+ */
+interface InterruptionLockView {
+    kinds: string[];
+    locked_by_default: string[];
+    rows: InterruptionLockRow[];
+    effective: EffectiveInterruptionLock[];
+}
+interface SetInterruptionLockBody {
+    kind: string;
+    profile_id?: string | null;
+    decision: InterruptionLock;
+}
+interface InterruptionRuleRow {
+    origin: string;
+    kind: string;
+    choice: InterruptionChoice;
+    /** Who wrote it — an agent must not be able to widen what the operator allowed. */
+    author: 'operator' | 'agent';
+    profile_id: string | null;
+}
+interface SetInterruptionRuleBody {
+    origin: string;
+    kind: string;
+    choice: InterruptionChoice;
+    profile_id?: string | null;
+}
+interface DeleteInterruptionRuleParams {
+    origin: string;
+    kind: string;
+    profile_id?: string | null;
+}
+/** The reply to a file handed in for a later upload. */
+interface ArtifactPutResult {
+    artifact_id: string;
+    size_bytes: number;
+    name: string | null;
+}
+/** Bytes plus what the daemon said they are. */
+interface ArtifactBytes {
+    bytes: Uint8Array;
+    content_type: string | null;
+    /** Parsed out of `Content-Disposition`, when the daemon sent one. */
+    filename: string | null;
+}
+/**
+ * Licence state, for display.
+ *
+ * The daemon decides on every launch whether a start is allowed; this never
+ * gets a say in it. Never gate your own code on it — a green light on a profile
+ * the launch gate refuses is worse than no light.
+ */
+interface Account {
+    /** `false` on a self-hosted build with no control plane. */
+    licensed: boolean;
+    plan?: string;
+    status?: string;
+    /**
+     * Browsers the subscription may run AT ONCE. Replaced the profile allowance
+     * on 2026-08-18: profiles are unlimited on every plan now.
+     */
+    concurrency?: number;
+    /** Browsers running on THIS machine, not the abo-wide count. */
+    running_local: number;
+    /** Profiles stored on THIS machine. */
+    profiles_local: number;
+    features?: string[];
+    /** Unix seconds; when the cached entitlement stops being valid. */
+    expires_at?: number;
+    permits_launch: boolean;
+}
+interface HealthStatus {
+    status: string;
+    service?: string;
+}
+interface ReadyStatus {
+    status: string;
+    /** Where the daemon looks for engines. Whether one is INSTALLED is a
+     *  launch-time question the preflight answers properly. */
+    engines_dir: string;
+}
+
+interface ScalebrowserClientOptions {
+    /** Daemon base URL. Default `http://127.0.0.1:8787`. */
+    baseUrl?: string;
+    /** Bearer token (AC-API-002). */
+    token?: string | null;
+    /** Injectable `fetch` (for testing / custom agents). Default `globalThis.fetch`. */
+    fetch?: FetchLike;
+}
+type QueryValue = string | number | boolean | null | undefined;
+type Query = Record<string, QueryValue>;
+interface RequestOptions {
+    query?: Query;
+    signal?: AbortSignal;
+}
+declare class ClientCore {
+    #private;
+    readonly baseUrl: string;
+    constructor(options?: ScalebrowserClientOptions);
+    /** For subclasses that hand the token to a sibling transport (SSE, CDP). */
+    protected get token(): string | null;
+    protected get fetchImpl(): FetchLike;
+    /** Rotate the Bearer token at runtime. */
+    setToken(token: string | null): void;
+    protected request<T>(method: string, path: string, body?: unknown, opts?: RequestOptions): Promise<T>;
+    /**
+     * A route that answers with bytes, not JSON — artifacts and run stills.
+     *
+     * Separate from {@link ClientCore.request} rather than a flag on it, because the two
+     * differ in the error path as well: a failed byte fetch still answers JSON,
+     * so the mapping to {@link ApiError} has to happen before the body is read as
+     * binary.
+     */
+    protected requestBytes(method: string, path: string, opts?: RequestOptions): Promise<ArtifactBytes>;
+}
+
+declare class ControlApi extends ClientCore {
+    /** Which browser surfaces are locked shut, and what actually applies. */
+    listInterruptionLocks(signal?: AbortSignal): Promise<InterruptionLockView>;
+    /** Omit `profile_id` to set the fleet-wide default. */
+    setInterruptionLock(body: SetInterruptionLockBody): Promise<unknown>;
+    /** Standing answers per origin and kind. */
+    listInterruptionRules(signal?: AbortSignal): Promise<InterruptionRuleRow[]>;
+    setInterruptionRule(body: SetInterruptionRuleBody): Promise<unknown>;
+    deleteInterruptionRule(params: DeleteInterruptionRuleParams): Promise<unknown>;
+    /**
+     * Hand the daemon a file so `interact action=upload` has something to attach.
+     *
+     * The bytes are bound to the PROFILE, not to a reservation: set a file up
+     * before leasing, and a lease released mid-task does not destroy it.
+     */
+    putArtifact(profileId: string, bytes: Uint8Array | ArrayBuffer, name?: string): Promise<ArtifactPutResult>;
+    /**
+     * Fetch one artifact's bytes — a screenshot, a download, a saved PDF.
+     *
+     * A miss is a plain 404 whether the id never existed, expired, or belonged to
+     * a released lease: the caller's next move is the same in all three cases.
+     */
+    getArtifact(artifactId: string, signal?: AbortSignal): Promise<ArtifactBytes>;
+    /**
+     * Licence state for display. The launch gate stays the authority on starts.
+     *
+     * A daemon predating the route answers 404, and that is not an error worth
+     * throwing: it means "self-hosted, no control plane", which is exactly what
+     * `licensed: false` says. Same shape of tolerance as {@link getMetrics}.
+     */
+    getAccount(signal?: AbortSignal): Promise<Account>;
+    /** "Is the daemon alive?" Public, needs no token. */
+    health(signal?: AbortSignal): Promise<HealthStatus>;
+    /** "Can it serve?" Local facts only — the control plane is deliberately not consulted. */
+    ready(signal?: AbortSignal): Promise<ReadyStatus>;
+}
+
+/** Column the DAEMON orders by. Sorting a fetched page would order a minority of
+ *  a paged fleet while looking authoritative, so ordering is a server parameter. */
+type ProfileSort = 'created_at' | 'name' | 'runtime_state' | 'last_open_at';
+type SortOrder = 'asc' | 'desc';
+/** `GET /v1/profiles/ids` — every id matching the same filters, unpaged. */
+interface ProfileIdsResult {
+    count: number;
+    ids: string[];
+}
+/** `POST /v1/bulk/start` — per-id results plus what the batch as a whole did. */
+interface BulkStartResult {
+    results: {
+        id: string;
+        ok: boolean;
+        cdp_ws?: string;
+        error?: string;
+    }[];
+    started: number;
+    remaining: string[];
+    stopped_reason?: string;
+}
+interface ListProfilesParams {
+    group?: string;
+    state?: RuntimeState;
+    q?: string;
+    limit?: number;
+    offset?: number;
+    sort?: ProfileSort;
+    order?: SortOrder;
+}
+interface CreateProfileBody {
+    name: string;
+    seed?: string;
+    host_mode?: HostMode;
+    geo_mode?: GeoMode;
+    expected_country?: string | null;
+    group_id?: string | null;
+    proxy_id?: string | null;
+}
+/**
+ * PATCH — all mutable fields optional. `host_mode` and `seed` are fixed at create
+ * time (C4/C5): a DIFFERING `host_mode` is refused with 400, an unchanged echo is
+ * accepted. Changing a tier requires delete + recreate.
+ */
+type UpdateProfileBody = Omit<Partial<CreateProfileBody>, "host_mode" | "seed">;
+interface StartProfileBody {
+    headless?: boolean;
+}
+interface StartProfileResult {
+    profile_id: string;
+    cdp_ws: string;
+    /** DevTools TCP port, parsed from `cdp_ws` (`null` if the URL has none). */
+    debug_port: number | null;
+    /** Effective headless state of this launch (AC-OR-005). */
+    headless: boolean;
+    pid: number | null;
+    started_at: number;
+}
+interface StopProfileResult {
+    stopped: boolean;
+}
+interface BulkCreateBody {
+    preset_id: string;
+    count: number;
+    /** Base name for the batch; the daemon appends an index per profile. */
+    name_prefix?: string;
+    /** Drop the whole batch into this group at create time. */
+    group_id?: string;
+}
+interface CreateProxyBody {
+    kind: ProxyKind;
+    host: string;
+    port: number;
+    username?: string | null;
+    password?: string | null;
+    rotation?: Rotation;
+}
+type UpdateProxyBody = Partial<CreateProxyBody>;
+/**
+ * Result of `POST /v1/proxies/:id/check` (health + geo).
+ *
+ * CONTRACT ASSUMPTION: the daemon returns the freshly-checked exit identity plus
+ * the JA4↔JA4T coherence verdict (AC-FP-011). Fields beyond the persisted `Proxy`
+ * columns (`ja4`, `ja4t`, `ja4t_mismatch`, `warnings`) are optional; if the
+ * daemon only echoes the updated `Proxy`, the JA4 verdict is simply absent.
+ */
+interface ProxyCheckResult {
+    healthy: boolean;
+    exit_ip: string | null;
+    country: string | null;
+    /** Carrier/mobile-exit hint from the exit lookup (a mobile exit is the best case). */
+    is_mobile?: boolean | null;
+    ja4?: string | null;
+    ja4t?: string | null;
+    ja4t_mismatch?: boolean;
+    warnings?: string[];
+    checked_at?: number;
+    /** Round-trip RTT — `null` on an unreachable exit (a timeout is not a latency). */
+    latency_ms?: number | null;
+}
+/**
+ * Body of `POST /v1/proxies/check` — probe a proxy config that is NOT persisted
+ * (health + geo before you commit it).
+ *
+ * Edit-mode: pass the `id` of an existing proxy and omit `username`/`password`
+ * to probe with its stored (write-only) credentials. A proxy whose credentials
+ * cannot be decrypted fails closed rather than probing unauthenticated.
+ */
+interface CheckProxyConfigBody {
+    kind: ProxyKind;
+    host: string;
+    port: number;
+    username?: string | null;
+    password?: string | null;
+    rotation?: Rotation;
+    /** Existing proxy id — enables the stored-credential fallback. */
+    id?: string | null;
+}
+/**
+ * One package in the daemon-wide extension library, keyed by id AND version: the
+ * library stocks several versions of the same extension and each profile draws one.
+ */
+interface Extension {
+    /** Canonical Web-Store id, derived from the package's own key. Repeats across versions. */
+    id: string;
+    name: string;
+    version: string;
+    /** Base64 DER public key lifted from the CRX header. */
+    public_key: string;
+    /**
+     * Unpacked library directory (the profile launches from its own copy).
+     * Derived by the daemon from its data dir rather than stored, so a moved data
+     * dir does not leave every row pointing at nothing.
+     */
+    dir: string;
+    /** SHA-256 of the unpacked tree — names the CONTENT of this version. */
+    content_hash: string;
+    added_at: number;
+}
+/**
+ * How a profile's extension set reaches the browser. Returned with every
+ * extensions response; `engine_switches` is what the launch actually emits.
+ *
+ * `id_model` is `"canonical"`: the id comes from the package's key and is the same
+ * for every profile — deliberately, since it is the id millions of real users
+ * report. Only the FILES are per-profile (`delivery: "per_profile_copy"`).
+ */
+interface ExtensionPolicy {
+    id_model: string;
+    delivery: string;
+    /** Exact, ordered engine switches emitted for this profile's set; empty when none. */
+    engine_switches: string[];
+}
+/** Response of every `/v1/profiles/:id/extensions` call: the set + the policy. */
+interface ExtensionsResult {
+    profile_id: string;
+    /** Assigned library ids, as an idempotent set. */
+    extensions: string[];
+    /**
+     * The set this profile actually loads — ONE version per extension, drawn from the
+     * profile's seed over what the library stocks. Shorter than `extensions` when an id
+     * no longer resolves.
+     */
+    packages: Extension[];
+    policy: ExtensionPolicy;
+    /**
+     * What is worth knowing about THIS set, judged by the daemon with the same
+     * function the launch gate uses. Empty for an unremarkable set — including an
+     * empty one, since about half of real Chrome users carry no extension.
+     *
+     * Never recompute it client-side: a second opinion could contradict the gate.
+     */
+    advice: ExtensionAdvice[];
+}
+/** One finding about a profile's extension set. */
+interface ExtensionAdvice {
+    /** `warn` — a launch is never blocked by an extension. */
+    level: string;
+    message: string;
+}
+
+declare class ExtensionsApi extends ClientCore {
+    /** The library, newest first. */
+    listLibraryExtensions(signal?: AbortSignal): Promise<Extension[]>;
+    /**
+     * Add a package. `crx` is the raw `.crx` file. A new VERSION is stocked alongside the
+     * existing ones (profiles draw their own); re-uploading the same version replaces it.
+     */
+    uploadExtension(crx: Uint8Array | ArrayBuffer): Promise<Extension>;
+    /** One library entry — the most recently added version. */
+    getLibraryExtension(id: string, signal?: AbortSignal): Promise<Extension>;
+    /** Remove EVERY version of a package, its files and every profile's assignment of it. */
+    deleteLibraryExtension(id: string): Promise<unknown>;
+    /**
+     * Remove ONE stocked version.
+     *
+     * Assignments survive — they name the extension, not the version — unless this
+     * was the last version, in which case they go with it.
+     */
+    deleteLibraryExtensionVersion(id: string, version: string): Promise<unknown>;
+    /** The profile's assigned set, resolved, + the launch policy. */
+    listExtensions(profileId: string, signal?: AbortSignal): Promise<ExtensionsResult>;
+    /** Assign a library id (idempotent) → the updated set + policy. 404 if unknown. */
+    attachExtension(profileId: string, extRef: string): Promise<ExtensionsResult>;
+    /** Unassign a library id (idempotent) → the updated set + policy. */
+    detachExtension(profileId: string, extRef: string): Promise<ExtensionsResult>;
+}
+
+/**
+ * One stored platform login — everything about it EXCEPT the secrets.
+ *
+ * The username IS returned: it is the account's display identity, not a secret on
+ * any platform, and without it two stored accounts are indistinguishable. The
+ * password and two-factor key travel only through `revealCredential`, which needs
+ * the vault password.
+ */
+interface CredentialMeta {
+    platform: string;
+    username: string | null;
+    login_url: string | null;
+    has_password: boolean;
+    has_totp: boolean;
+    /** Typed into a sign-up form but never confirmed — the account may not exist. */
+    pending?: boolean;
+    created_at: number;
+    updated_at: number;
+    last_used_at: number | null;
+    /** No longer opens with the current master key: listable, deletable, unusable. */
+    secrets_unreadable?: boolean;
+}
+/** An omitted secret means "leave it unchanged", not "delete it". */
+interface PutCredentialBody {
+    username?: string | null;
+    password?: string | null;
+    /** Base32 setup key. Grouped, lower-case input is normalised by the daemon. */
+    totp_secret?: string | null;
+    login_url?: string | null;
+}
+/** The only shape in this SDK that carries a password. */
+interface RevealedCredential {
+    platform: string;
+    username: string | null;
+    password: string | null;
+    totp_secret: string | null;
+}
+/** A passphrase-sealed backup of one profile's logins. */
+interface CredentialBundle {
+    bundle: string;
+    count: number;
+}
+interface CredentialImportResult {
+    /** Boolean, like the session import — the number is in `count`. */
+    imported: boolean;
+    count: number;
+    platforms: string[];
+}
+interface VaultStatus {
+    configured: boolean;
+}
+
+/**
+ * The account layer: mailboxes, passkeys and the one door a cookie value leaves
+ * through.
+ *
+ * Mailbox and passkey shapes mirror `web-ui/src/api/types/{inboxes,credentials}.ts`,
+ * the shared source of contract truth. The cookie reveal has no UI counterpart:
+ * it is a REST-only route deliberately kept off every screen.
+ */
+/** One configured mailbox. The password is never sent back. */
+interface Inbox {
+    id: string;
+    name: string;
+    host: string;
+    port: number;
+    /** The mailbox login. Not a secret, and it is how two rows are told apart. */
+    user: string;
+    /** TLS from the first byte. `false` is only accepted towards this machine. */
+    tls: boolean;
+    folder: string;
+    /**
+     * The domain new addresses are minted under, e.g. `my-domain.tld`. Absent for
+     * a mailbox with exactly one address.
+     */
+    address_domain: string | null;
+    created_at: number;
+    /**
+     * The stored password could not be decrypted — a restored database without
+     * its key. The row stays visible and deletable; every use of it fails closed.
+     */
+    credentials_unreadable?: boolean;
+}
+interface CreateInboxBody {
+    name: string;
+    host: string;
+    port: number;
+    user: string;
+    /** Required when creating; leave it out on an edit to keep the stored one. */
+    password?: string;
+    tls?: boolean;
+    folder?: string;
+    address_domain?: string | null;
+}
+type UpdateInboxBody = CreateInboxBody;
+/** Which channel a code arrives on. */
+type InboxChannel = 'email' | 'sms';
+/** What one profile is bound to, per channel. */
+interface InboxBinding {
+    profile_id: string;
+    channel: InboxChannel;
+    /** The address or number this profile is known by. */
+    address: string;
+    /**
+     * The mailbox that answers. `null` means the operator's configured command
+     * does, which is the only shape an SMS binding can have.
+     */
+    inbox_id: string | null;
+    created_at: number;
+}
+interface BindInboxBody {
+    channel: InboxChannel;
+    inbox_id?: string | null;
+    /** Absent mints one under the mailbox's catch-all domain. */
+    address?: string;
+}
+interface InboxBindings {
+    bindings: InboxBinding[];
+}
+/**
+ * One passkey of a profile — a login that needs no password.
+ *
+ * `credential_id` names the row for deletion and nothing else. The private key
+ * has no field here and no endpoint: it IS the account, and it could not be
+ * typed anywhere useful, so returning it would be risk without a purpose.
+ */
+interface PasskeyRow {
+    credential_id: string;
+    /** The site it belongs to, e.g. `github.com`. */
+    rp_id: string;
+    user_name: string | null;
+    user_display: string | null;
+    created_at: number;
+    last_used_at: number | null;
+    /** True when a stored secret cannot be decrypted — the sign-in WILL fail. */
+    secrets_unreadable: boolean;
+    /**
+     * When the key stopped being usable, if it has. A retired key is never loaded
+     * into the browser and never offered to an agent, but it stays visible until
+     * it is cleared: an account that quietly stops working is the first thing
+     * anyone asks about.
+     */
+    retired_at: number | null;
+    /**
+     * `unknown` is a reason this build cannot name, and it deliberately claims
+     * nothing — reading it as `operator` would tell you that you had deleted
+     * something you never touched.
+     */
+    retired_reason: 'operator' | 'agent' | 'site_revoked' | 'unknown' | null;
+}
+/** A cookie VALUE skips both the password and the second factor beside it. */
+interface RevealedCookie {
+    name: string;
+    domain: string;
+    path: string;
+    value: string;
+}
+interface RevealCookiesBody {
+    /** The same gate a far weaker password sits behind. */
+    vault_password: string;
+    domain: string;
+    /** One cookie by name; omit for every cookie on the domain. */
+    name?: string | null;
+}
+interface RevealCookiesResult {
+    domain: string;
+    cookies: RevealedCookie[];
+}
+
+declare class IdentityApi extends ClientCore {
+    /** Which platforms this profile can log into. Never carries a secret. */
+    listCredentials(profileId: string, signal?: AbortSignal): Promise<CredentialMeta[]>;
+    /**
+     * Store or update one login.
+     *
+     * An omitted secret keeps its stored value rather than clearing it — an edit form
+     * never saw the password in the clear, so it cannot resend one; delete the row to
+     * remove a credential. `totp_secret` may be pasted exactly as a site presents it
+     * (grouped, lower case): it is normalised and test-decoded by the daemon, so a
+     * broken key is refused here rather than half-way through a login.
+     */
+    putCredential(profileId: string, platform: string, body: PutCredentialBody): Promise<CredentialMeta>;
+    /** Forget one login. The account itself is untouched. */
+    deleteCredential(profileId: string, platform: string): Promise<void>;
+    /** Read one login back in the clear. Needs the vault password. */
+    revealCredential(profileId: string, platform: string, vaultPassword: string): Promise<RevealedCredential>;
+    /**
+     * Pack this profile's logins into a bundle sealed with `password`.
+     *
+     * `password` is deliberately separate from the vault password: a backup gets
+     * handed to another machine, and that must not also hand over daemon access. This
+     * is the answer to a lost master key — a daemon-generated password exists nowhere
+     * else.
+     */
+    exportCredentials(profileId: string, vaultPassword: string, password: string): Promise<CredentialBundle>;
+    /** Restore a bundle into this profile. */
+    importCredentials(profileId: string, vaultPassword: string, password: string, bundle: string): Promise<CredentialImportResult>;
+    /** Has a vault password been set on this daemon? */
+    vaultStatus(signal?: AbortSignal): Promise<VaultStatus>;
+    /** Set the vault password, or change it (then `currentPassword` is required). */
+    setVaultPassword(newPassword: string, currentPassword?: string): Promise<void>;
+    /** Mailboxes, passwords never returned. */
+    listInboxes(signal?: AbortSignal): Promise<Inbox[]>;
+    createInbox(body: CreateInboxBody): Promise<Inbox>;
+    /** An omitted `password` leaves the stored one unchanged. */
+    updateInbox(inboxId: string, body: UpdateInboxBody): Promise<Inbox>;
+    deleteInbox(inboxId: string): Promise<unknown>;
+    /** Which mailbox a profile's confirmation codes arrive in, per channel. */
+    getInboxBindings(profileId: string, signal?: AbortSignal): Promise<InboxBindings>;
+    bindInbox(profileId: string, body: BindInboxBody): Promise<InboxBindings>;
+    unbindInbox(profileId: string, channel: string): Promise<unknown>;
+    /** What this profile can sign in to without a password. Metadata only. */
+    listPasskeys(profileId: string, signal?: AbortSignal): Promise<PasskeyRow[]>;
+    /**
+     * Retire a passkey.
+     *
+     * Calling it twice is meaningful: the first call retires a live key and leaves
+     * a headstone, the second clears the headstone for good.
+     */
+    deletePasskey(profileId: string, credentialId: string): Promise<unknown>;
+    /**
+     * The one door a cookie VALUE leaves through, and it needs the vault password.
+     *
+     * A session cookie skips both the password and the second factor, which is why
+     * every other cookie surface answers with metadata only.
+     */
+    revealCookies(profileId: string, body: RevealCookiesBody): Promise<RevealCookiesResult>;
+}
+
+/**
+ * Agent runs and live activity (`/v1/runs`, `/v1/activity`).
+ *
+ * All of it is display: nothing here starts, stops or changes anything.
+ *
+ * `RunActor`, `RunOutcome`, `StepKind`, `StepTarget`, `RunStep` and
+ * `ProfileActivity` are NOT redeclared here — they live in `types.ts` because
+ * the live event stream carries them, and the run list describes the same rows.
+ * A second copy would let the two drift apart while both looked right.
+ *
+ * Mirrors `web-ui/src/api/types/runs.ts`, the shared source of contract truth.
+ */
+
+/** Who made the outcome claim. `derived` means nobody did. */
+type OutcomeSource = 'agent' | 'check' | 'human' | 'derived';
+/** Whether the goal text was stated or merely describes the session. */
+type GoalSource = 'agent' | 'derived';
+interface AgentRun {
+    id: string;
+    /** Groups runs that shared one profile reservation. */
+    session_id: string;
+    profile_id: string;
+    profile_name: string;
+    actor: RunActor;
+    /** Never empty — described when it was not declared (see `goal_source`). */
+    goal: string;
+    goal_source: GoalSource;
+    /**
+     * `reached` and `partial` are CLAIMS: the daemon can tell that a run ended,
+     * never that it worked, so those two only ever come from an agent, a check or
+     * a person.
+     */
+    outcome: RunOutcome;
+    outcome_source: OutcomeSource | null;
+    note: string | null;
+    started_at: number;
+    ended_at: number | null;
+    step_count: number;
+    /**
+     * Steps that never reached the trail because the writer queue was full. Zero
+     * on a healthy run, and worth reading: a trail missing entries looks exactly
+     * like an agent that did less work.
+     */
+    steps_lost: number;
+    first_domain: string | null;
+}
+interface ActivitySnapshot {
+    sampled_at: number | null;
+    profiles: ProfileActivity[];
+}
+interface ListRunsParams {
+    profile_id?: string;
+    limit?: number;
+    offset?: number;
+}
+interface ListStepsParams {
+    limit?: number;
+    offset?: number;
+}
+
+declare class RunsApi extends ClientCore {
+    /** Runs, newest first. Read-only, all of it. */
+    listRuns(params?: ListRunsParams, signal?: AbortSignal): Promise<AgentRun[]>;
+    /** One run. */
+    getRun(runId: string, signal?: AbortSignal): Promise<AgentRun>;
+    /** A run's steps, oldest first — the order they happened in. */
+    listRunSteps(runId: string, params?: ListStepsParams, signal?: AbortSignal): Promise<RunStep[]>;
+    /**
+     * The still taken at one step, as JPEG bytes.
+     *
+     * The picture shows a customer's account, so it is decrypted only on the way
+     * out and never cached anywhere shared.
+     */
+    getRunShot(runId: string, seq: number, signal?: AbortSignal): Promise<ArtifactBytes>;
+    /** What every running profile currently shows. */
+    getActivity(signal?: AbortSignal): Promise<ActivitySnapshot>;
+}
+
+/**
+ * Direct-CDP driver (DEC-006, AC-FP-005) — a minimal, nodriver-style Chrome
+ * DevTools Protocol client over a raw websocket. This is the recommended SDK
+ * driver plane: it is NOT the Playwright/Puppeteer control plane (which is a
+ * detection vector independent of patch quality). We never call `Runtime.enable`
+ * (a known leak surface); `Runtime.evaluate` works without it, and isolated
+ * worlds are created explicitly via `Page.createIsolatedWorld`.
+ */
+
+/** The slice of the REST client the CDP driver needs for `humanize*` helpers. */
+interface InputClient {
+    sendInput(profileId: string, body: TrustedInputBody): Promise<unknown>;
+}
+/** A CDP event frame (no `id`): `{ method, params, sessionId? }`. */
+interface CdpEvent {
+    method: string;
+    params: Record<string, unknown>;
+    sessionId?: string;
+}
+interface NavigateResult {
+    frameId: string;
+    loaderId?: string;
+    errorText?: string;
+}
+/**
+ * The websocket multiplexer: assigns command ids, resolves responses, and fans
+ * CDP events out to subscribers. One connection backs the root session and every
+ * attached page session.
+ */
+declare class CdpConnection {
+    #private;
+    constructor(ws: WebSocket);
+    request<T>(method: string, params?: Record<string, unknown>, sessionId?: string): Promise<T>;
+    subscribe(cb: (event: CdpEvent) => void): () => void;
+    /** Register a callback fired once when the connection closes (immediately if
+     *  it already has) — event streams use this to end instead of hanging. */
+    onClose(cb: () => void): () => void;
+    close(): void;
+    get closed(): boolean;
+}
+interface AttachOptions {
+    /** Attach to this exact target; otherwise the first `page` target is used. */
+    targetId?: string;
+    /** Create a fresh target (tab) instead of reusing an existing one. */
+    create?: boolean;
+    /** Initial URL when creating a target (default `about:blank`). */
+    url?: string;
+}
+interface NavigateOptions {
+    /** Wait until `document.readyState === 'complete'` (default true). */
+    wait?: boolean;
+    /** Wait timeout in ms (default 30000). */
+    timeout?: number;
+}
+interface EvaluateOptions {
+    awaitPromise?: boolean;
+    returnByValue?: boolean;
+    /** Run in a fresh isolated world rather than the page's main world. */
+    isolated?: boolean;
+}
+interface ClickOptions {
+    button?: string;
+    clickCount?: number;
+    /**
+     * B5: element-relative targeting — the effective target width (an element's
+     * bounding-box size). The daemon's Fitts-law approach lands within the element
+     * instead of on a fixed corner. Prefer {@link CdpSession.humanizeClickElement}.
+     */
+    width?: number;
+}
+interface MoveOptions {
+    /** B5: element-relative target width (see {@link ClickOptions.width}). */
+    width?: number;
+}
+interface ScrollOptions {
+    deltaX?: number;
+    deltaY?: number;
+}
+/** A DOM element's bounding box (e.g. from `getBoundingClientRect()`). */
+interface ElementBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * A CDP session. The root session (no `sessionId`) speaks browser-level CDP;
+ * `attachToPage()` returns a page-bound session whose commands carry its
+ * `sessionId` (flatten mode). `navigate`/`evaluate`/`createIsolatedWorld` and
+ * the `humanize*` helpers operate on a page-bound session.
+ */
+declare class CdpSession {
+    #private;
+    readonly sessionId: string | undefined;
+    constructor(conn: CdpConnection, sessionId?: string, client?: InputClient, profileId?: string);
+    /** Send a raw CDP command and await its result (by id). */
+    send<T = unknown>(method: string, params?: Record<string, unknown>): Promise<T>;
+    /** Register a callback for a CDP event scoped to this session. Returns unsubscribe. */
+    on(method: string, callback: (params: Record<string, unknown>) => void): () => void;
+    /** `for await (const event of session.events())` over this session's CDP events. */
+    events(): AsyncIterableIterator<CdpEvent>;
+    /** Attach to a page target, returning a page-bound child session. */
+    attachToPage(opts?: AttachOptions): Promise<CdpSession>;
+    /** Navigate the page; optionally wait for load. Never calls `Runtime.enable`. */
+    navigate(url: string, opts?: NavigateOptions): Promise<NavigateResult>;
+    /** Evaluate a JS expression in the page (or an isolated world) and return its value. */
+    evaluate<T = unknown>(expression: string, opts?: EvaluateOptions): Promise<T>;
+    /** Create an isolated world for the (main) frame and return its execution context id. */
+    createIsolatedWorld(frameId?: string, worldName?: string): Promise<number>;
+    humanizeMove(x: number, y: number, opts?: MoveOptions): Promise<unknown>;
+    humanizeClick(x: number, y: number, opts?: ClickOptions): Promise<unknown>;
+    /**
+     * B5: humanized move to the CENTRE of an element box, with the box width fed to the
+     * daemon's Fitts-law approach so the pointer lands *within* the element (not on a
+     * fixed corner). Pass a `getBoundingClientRect()`-shaped box.
+     */
+    humanizeMoveToElement(box: ElementBox): Promise<unknown>;
+    /** B5: humanized click at the centre of an element box (see {@link humanizeMoveToElement}). */
+    humanizeClickElement(box: ElementBox, opts?: ClickOptions): Promise<unknown>;
+    humanizeType(text: string): Promise<unknown>;
+    humanizeScroll(x: number, y: number, opts?: ScrollOptions): Promise<unknown>;
+    /** Close the underlying CDP connection. */
+    close(): void;
+}
+interface CdpConnectOptions {
+    token?: string | null;
+    client?: InputClient;
+    profileId?: string;
+    /** Auto-attach to a page target so navigate/evaluate work (default true). */
+    autoAttach?: boolean;
+    /** Create a fresh tab on attach instead of reusing an existing page (default false). */
+    createTarget?: boolean;
+    /** Initial URL when creating a target. */
+    targetUrl?: string;
+    /** Websocket handshake timeout in ms (default 30000). */
+    openTimeout?: number;
+}
+/** Open a CDP websocket and return a (page-bound, unless `autoAttach:false`) session. */
+declare function openCdpSession(url: string, options?: CdpConnectOptions): Promise<CdpSession>;
+
+/**
+ * Dashboard/SDK metrics (AC-UI-002, M3). The daemon serves `GET /v1/metrics`
+ * from a background sampler; each null-able figure is disambiguated by
+ * {@link Metrics.availability} (`measured` vs `unsupported` vs `unavailable`).
+ * Against an old daemon without the endpoint (404) the client falls back to
+ * deriving running counts from profile states and stamps `source: "derived"`
+ * (see {@link deriveMetricsFromProfiles}).
+ */
+type ProbeState = 'measured' | 'unsupported' | 'unavailable';
+type MetricsSource = 'live' | 'derived';
+interface MetricsAvailability {
+    ram: ProbeState;
+    cpu: ProbeState;
+    gpu: ProbeState;
+    vram: ProbeState;
+    per_profile: ProbeState;
+}
+interface ProfileResource {
+    profile_id: string;
+    name: string;
+    pid: number | null;
+    ram_mb: number | null;
+    cpu_pct: number | null;
+    vram_mb: number | null;
+}
+interface Metrics {
+    running: number;
+    capacity_max_concurrent: number;
+    ram_used_mb: number | null;
+    ram_budget_mb: number;
+    vram_used_mb: number | null;
+    vram_budget_mb: number | null;
+    cpu_pct: number | null;
+    gpu_pct: number | null;
+    source?: MetricsSource;
+    sampled_at?: number | null;
+    availability?: MetricsAvailability;
+    profiles?: ProfileResource[];
+    /**
+     * Launchable host memory (MiB) — the capacity gate's own reading. "How many
+     * more browsers fit" derives from THIS; `ram_budget_mb − ram_used_mb` does
+     * not subtract (used is host-wide, the budget is the daemon's own ceiling).
+     */
+    ram_available_mb?: number | null;
+}
+
+/**
+ * `ScalebrowserClient` — the one typed HTTP surface every REST call goes
+ * through. It centralises the base URL, Bearer auth, query-string building, JSON
+ * (de)serialisation and error mapping (`{ code, message }` → {@link ApiError}).
+ * Backend endpoint drift is a change in THIS file (paths) plus `types.ts`
+ * (shapes) — nowhere else.
+ */
+
+/** Mirrors `CapacityConfig::default()` (`crates/core/src/config.rs`). */
+declare const DEFAULT_CAPACITY: {
+    max_concurrent: number;
+    ram_budget_mb: number;
+    vram_budget_mb: number | null;
+};
+/** A live, CDP-driven browser launched via {@link ScalebrowserClient.launch}. */
+interface LaunchHandle {
+    /** The page-bound CDP session. */
+    readonly cdp: CdpSession;
+    /** The `start` result (`cdp_ws`, `debug_port`, `headless`). */
+    readonly result: StartProfileResult;
+    /** Close the CDP connection and stop the profile. */
+    stop(): Promise<void>;
+    /** `await using` support — calls {@link stop}. */
+    [Symbol.asyncDispose](): Promise<void>;
+}
+/** Fallback: compute what we can purely from profile runtime states. */
+declare function deriveMetricsFromProfiles(profiles: Profile[]): Metrics;
+declare class ScalebrowserClient extends ClientCore {
+    listProfiles(params?: ListProfilesParams, signal?: AbortSignal): Promise<Profile[]>;
+    /**
+     * Every id matching `params`, unpaged — what "act on all matches" needs.
+     *
+     * `listProfiles` is paged, so acting on "everything" from it only ever covers the
+     * page you fetched. Asking for ids costs one request and no persona payloads.
+     */
+    listProfileIds(params?: ListProfilesParams, signal?: AbortSignal): Promise<ProfileIdsResult>;
+    getProfile(id: string, signal?: AbortSignal): Promise<Profile>;
+    createProfile(body: CreateProfileBody): Promise<Profile>;
+    updateProfile(id: string, body: UpdateProfileBody): Promise<Profile>;
+    deleteProfile(id: string): Promise<void>;
+    /** Start a profile → CDP ws endpoint. Errors: 4002/4003/4005/4006/4008. */
+    startProfile(id: string, body?: StartProfileBody): Promise<StartProfileResult>;
+    stopProfile(id: string): Promise<StopProfileResult>;
+    bulkCreateProfiles(body: BulkCreateBody): Promise<Profile[]>;
+    /**
+     * Start a batch. `headless` is the ONE visibility decision for the run; omitted
+     * means headless, the right default for an unattended client. The daemon stops at
+     * the machine's capacity limit and reports how far it got (`started` /
+     * `remaining` / `stopped_reason`) instead of failing every remaining id.
+     */
+    bulkStart(ids: string[], headless?: boolean): Promise<BulkStartResult>;
+    bulkStop(ids: string[]): Promise<unknown>;
+    bulkDelete(ids: string[]): Promise<unknown>;
+    bulkAssignProxy(ids: string[], proxyId: string): Promise<unknown>;
+    /**
+     * Give every id exactly this set of extensions.
+     *
+     * It REPLACES rather than adds, the same shape as assigning a proxy: picking a
+     * set for a batch states what those profiles carry. An empty list is a
+     * legitimate "none". An id the library does not hold refuses the whole call.
+     */
+    bulkAssignExtensions(ids: string[], extRefs: string[]): Promise<unknown>;
+    listGroups(signal?: AbortSignal): Promise<Group[]>;
+    getGroup(id: string, signal?: AbortSignal): Promise<Group>;
+    createGroup(body: CreateGroupBody): Promise<Group>;
+    updateGroup(id: string, body: UpdateGroupBody): Promise<Group>;
+    deleteGroup(id: string): Promise<void>;
+    listPresets(signal?: AbortSignal): Promise<Preset[]>;
+    getPreset(id: string, signal?: AbortSignal): Promise<Preset>;
+    createPreset(body: CreatePresetBody): Promise<Preset>;
+    updatePreset(id: string, body: UpdatePresetBody): Promise<Preset>;
+    deletePreset(id: string): Promise<void>;
+    /**
+     * The values a preset's `constraints` may take. Ask rather than hardcode: the
+     * region list comes from the daemon's embedded persona model, so a pinned copy
+     * drifts the moment that model changes and every create 400s.
+     */
+    getPersonaConstraints(signal?: AbortSignal): Promise<PersonaConstraintOptions>;
+    listProxies(signal?: AbortSignal): Promise<Proxy[]>;
+    getProxy(id: string, signal?: AbortSignal): Promise<Proxy>;
+    createProxy(body: CreateProxyBody): Promise<Proxy>;
+    updateProxy(id: string, body: UpdateProxyBody): Promise<Proxy>;
+    deleteProxy(id: string): Promise<void>;
+    /** Health + geo check (exit-ip/country/healthy + JA4↔JA4T verdict). */
+    checkProxy(id: string): Promise<ProxyCheckResult>;
+    /**
+     * Probe a proxy config WITHOUT persisting it — validate before you commit.
+     * Pass `id` (and omit the credentials) to probe an existing proxy's stored,
+     * write-only credentials in an edit form.
+     */
+    checkProxyConfig(body: CheckProxyConfigBody): Promise<ProxyCheckResult>;
+    /** Queue a run → the status right after queueing. `409` if not running / already running. */
+    startAudit(profileId: string): Promise<AuditStatus>;
+    /** State plus the last stored report. */
+    getAudit(profileId: string, signal?: AbortSignal): Promise<AuditStatus>;
+    exportSession(profileId: string, body: SessionExportBody): Promise<SessionExportResult>;
+    importSession(profileId: string, body: SessionImportBody): Promise<unknown>;
+    sendInput(profileId: string, body: TrustedInputBody): Promise<unknown>;
+    getMetrics(signal?: AbortSignal): Promise<Metrics>;
+    /** Subscribe to lifecycle events. Returns an unsubscribe function. */
+    subscribeEvents(handlers: StreamHandlers): () => void;
+    /** `for await (const event of client.events())` over lifecycle events. */
+    events(): AsyncIterableIterator<LifecycleEvent>;
+    /**
+     * Open a direct-CDP session against a started profile's `cdp_ws`. Pass the
+     * `profileId` so `humanize*` helpers can route trusted input through the daemon.
+     */
+    connectCdp(target: StartProfileResult | string, profileId?: string): Promise<CdpSession>;
+    /**
+     * Start a profile, connect direct-CDP, and return a {@link LaunchHandle} whose
+     * `stop()` (or `await using`) closes CDP and stops the profile.
+     */
+    launch(profileId: string, body?: StartProfileBody): Promise<LaunchHandle>;
+}
+interface ScalebrowserClient extends IdentityApi, RunsApi, ControlApi, ExtensionsApi {
+}
+
+/**
+ * `@scalebrowser/sdk` — the official Node/TypeScript SDK for the Scalebrowser
+ * daemon. A typed REST client plus a direct-CDP driver plane (nodriver-style,
+ * NOT Playwright — DEC-006).
+ *
+ * ```ts
+ * import { ScalebrowserClient } from '@scalebrowser/sdk';
+ *
+ * const sb = new ScalebrowserClient({ baseUrl: 'http://127.0.0.1:8787', token });
+ * const profile = await sb.createProfile({ name: 'acct-01' });
+ * await using session = await sb.launch(profile.id, { headless: true });
+ * await session.cdp.navigate('https://example.com');
+ * const title = await session.cdp.evaluate<string>('document.title');
+ * await session.cdp.humanizeClick(120, 240);
+ * ```
+ */
+
+declare const VERSION = "0.2.0";
+
+export { type Account, type ActivitySnapshot, type AgentRun, ApiError, type ApiErrorBody, type ArtifactBytes, type ArtifactPutResult, type AttachOptions, type AuditDetectorReport, type AuditReport, type AuditStatus, type AuditVerdict, type BindInboxBody, type CdpConnectOptions, CdpError, type CdpEvent, CdpSession, type ClickOptions, type CreateGroupBody, type CreateInboxBody, type CreatePresetBody, DEFAULT_CAPACITY, type DeleteInterruptionRuleParams, type EffectiveInterruptionLock, ErrorCode, type ErrorCodeValue, type EvaluateOptions, type FetchLike, GEO_MODES, type GeoMode, type GoalSource, type Group, HOST_MODES, type HealthStatus, type HostMode, type Inbox, type InboxBinding, type InboxBindings, type InboxChannel, type InputClient, type InterruptionChoice, type InterruptionLock, type InterruptionLockRow, type InterruptionLockView, type InterruptionRuleRow, type LaunchHandle, type ListRunsParams, type ListStepsParams, type NavigateOptions, NetworkError, type OsFamily, type OutcomeSource, PROXY_KINDS, type PasskeyRow, type PersonaConstraintOptions, type Preset, type PresetConfig, type PresetConstraints, type Profile, type ProfileActivity, type ProtectionLevel, type ProtectionStatus, type Proxy, type ProxyKind, ROTATIONS, RUNTIME_STATES, type ReadyStatus, type RevealCookiesBody, type RevealCookiesResult, type RevealedCookie, type Rotation, type RunActor, type RunOutcome, type RunStep, type RuntimeState, ScalebrowserClient, type ScalebrowserClientOptions, ScalebrowserError, type ScrollOptions, type SessionExportBody, type SessionExportResult, type SessionImportBody, type SessionKind, type SetInterruptionLockBody, type SetInterruptionRuleBody, type StepKind, type StepTarget, type StreamHandlers, type StreamParams, type StreamStatus, type TrustedInputBody, type UpdateGroupBody, type UpdateInboxBody, type UpdatePresetBody, VERSION, deriveMetricsFromProfiles, errorMessage, eventStream, openCdpSession, parseSseFrame, subscribeEvents };