@oya-ai/browser 1.0.97 → 1.0.99

package/dist/index.d.cts

@@ -1,14 +1,232 @@
-/** The one HTTP path. Everything else in this package is a wrapper over it. */
-declare class Http {
-    readonly baseUrl: string;
-    readonly apiKey: string;
-    private readonly timeoutMs;
-    private readonly fetchImpl;
-    constructor(baseUrl: string, apiKey: string, timeoutMs: number, fetchImpl: typeof globalThis.fetch);
-    request<T>(method: string, path: string, body?: unknown, timeoutMs?: number, headers?: Record<string, string>): Promise<T>;
+/**
+ * Types for browsers themselves: starting one, what a page looks like to the
+ * SDK, the results of CAPTCHA and MFA handling, and the fleet listing.
+ */
+/** Where a browser comes from. Configuration, not something a caller must know. */
+type Provider = 'oya-cloud' | 'oya-selfhosted' | 'browseruse' | 'browserbase' | 'steel' | 'anchor' | 'cdp';
+/** How `oya.browser.start()` should start a browser. Every field is optional. */
+interface StartOptions {
+    /** Reuse this value when retrying the same logical creation. */
+    idempotencyKey?: string;
+    /** Wait for capacity for up to five minutes; zero rejects immediately. */
+    queueMs?: number;
+    /** Spend ceiling for this browser, in US dollars. */
+    budgetUsd?: number;
+    /** Run under the project's governance: policies, budgets and recordings. */
+    governed?: boolean;
+    /** Egress and recording rules for a governed browser. */
+    policy?: {
+        /** Hosts the browser may reach; everything else is blocked. */
+        allowedHosts?: string[];
+        /** Hosts where a person, not the agent, must act. */
+        humanHosts?: string[];
+        /** Where the browser must run. */
+        region?: string;
+        /** Blur typed values out of the session recording. */
+        redactRecording?: boolean;
+    };
+    /** Place in the queue when capacity is short. */
+    priority?: 'low' | 'normal' | 'high';
+    /** Saved login profile. Defaults to the desktop's default profile. */
+    profile?: string;
+    /**
+     * Which identity to run as. A persona is one device: fingerprint, cookie jar
+     * and proxy bound together and stable for its life.
+     *   'default' — this key's own persona (the default)
+     *   'auto'    — the least recently used persona under its concurrency cap
+     *   <id>      — a specific persona
+     */
+    persona?: 'default' | 'auto' | (string & {});
+    /** Solve CAPTCHAs as they appear rather than waiting to be asked. */
+    captcha?: 'auto' | 'off';
+    /** Override the key's configured provider for this browser only. */
+    provider?: Provider;
+    /** Required only for the 'cdp' provider. */
+    wsUrl?: string;
+    /** A label for the fleet listing. */
+    name?: string;
+    /** How long to wait for a cloud browser to dial in. Default 120s. */
+    readyTimeoutMs?: number;
+}
+/** What the server answers when a browser starts. */
+interface StartResult {
+    /** The browser's id, for every later call. */
+    id: string;
+    /** Which provider runs it. */
+    provider: string;
+    /** Which persona it runs as. */
+    persona: string;
+    /** 'starting' while a cloud browser has yet to dial in. */
+    status: 'ready' | 'starting';
+    /** Point Playwright, Puppeteer or browser-use at this. */
+    cdpUrl?: string;
+    /** Anything the server wants the caller to know about this start. */
+    note?: string;
+}
+/** One element on the page, numbered by `analyze()`. */
+interface Element {
+    /** The number to pass to `click()` and `type()`. Valid until the page changes. */
+    id: number;
+    /** What kind of control it is: link, button, input and so on. */
+    type: string;
+    /** Visible label, capped at 80 characters by the analyzer. */
+    text?: string;
+    /** Where a link goes. */
+    href?: string;
+    /** The current value of a field. */
+    value?: string;
+    /** Whether a checkbox or radio is ticked. */
+    checked?: boolean;
+    /** Whether it refuses input. */
+    disabled?: boolean;
+    /** Whether it is on screen. */
+    visible: boolean;
+    /** The HTML tag name. */
+    tag?: string;
+    /** The element's DOM `id`. Usually the most stable handle a site offers. */
+    domId?: string;
+    /** Its `aria-label`. */
+    ariaLabel?: string;
+    /** `data-testid`, when the site ships one. */
+    testId?: string;
+    /** Its `name` attribute. */
+    name?: string;
+    /** A field's placeholder text. */
+    placeholder?: string;
+    /** Action of the enclosing form. */
+    formName?: string;
+}
+/** The page as `analyze()` sees it. */
+interface Analysis {
+    /** The page as markdown. */
+    markdown: string;
+    /** Every numbered element, visible or not. */
+    elements: Element[];
+    /** The window size, in CSS pixels. */
+    viewport?: {
+        /** Width in CSS pixels. */
+        width: number;
+        /** Height in CSS pixels. */
+        height: number;
+    };
+    /** How far the page is scrolled. */
+    scroll?: {
+        /** Horizontal offset in CSS pixels. */
+        x: number;
+        /** Vertical offset in CSS pixels. */
+        y: number;
+    };
+    /** True when the page was too long to send in full. */
+    truncated?: boolean;
+}
+/** What `solveCaptcha()` found and did. */
+interface CaptchaResult {
+    /** Whether a CAPTCHA was on the page. */
+    present: boolean;
+    /** Whether it was cleared. */
+    solved: boolean;
+    /** 'provider' when the vendor solved it, 'solver' when we did, 'none' otherwise. */
+    method: 'provider' | 'solver' | 'none';
+    /** Which kind of CAPTCHA it was. */
+    type?: string;
+    /** Invisible reCAPTCHA v3 scores the visit passively; there is nothing on screen to clear. */
+    invisible?: boolean;
+    /** The site key the solver was given. */
+    sitekey?: string | null;
+    /** Why it was not solved. */
+    error?: string;
+}
+/** What `completeMfa()` found and did. */
+interface MfaResult {
+    /** Whether an MFA prompt was on the page. */
+    present: boolean;
+    /** Whether it was answered and accepted. */
+    completed: boolean;
+    /** Which factor answered it, or 'handoff' when a person must. */
+    method?: 'totp' | 'email' | 'sms' | 'handoff' | 'none';
+    /** Whether the code was typed in. */
+    filled?: boolean;
+    /** Whether the form was submitted. */
+    submitted?: boolean;
+    /** Open this to finish by hand when nothing automated can. */
+    liveViewUrl?: string | null;
+    /** Why it could not be completed. */
+    error?: string;
+}
+/** How a browser is doing, judged from its recent commands and heartbeats. */
+type Health = 'ok' | 'stale' | 'errors' | 'dead';
+/** One thing a browser did. */
+interface Activity {
+    /** When, as an ISO timestamp. */
+    ts: string;
+    /** The command's name. */
+    action: string;
+    /** A one-line account of it. */
+    summary: string;
+    /** Whether it succeeded. */
+    ok: boolean;
+    /** How long it took. */
+    ms: number;
+    /** Why it failed. */
+    error?: string;
+}
+/** The outcome of stopping one browser. */
+interface StopResult {
+    /** The browser. */
+    id: string;
+    /** Whether it stopped. */
+    ok: boolean;
+    /** Which provider ran it. */
+    provider?: string | null;
+    /** For a cloud browser, whether its sandbox was destroyed (and billing ended). */
+    sandboxRemoved?: boolean | null;
+    /** Why it did not stop. */
+    error?: string;
+}
+/** One browser in the fleet listing. */
+interface BrowserInfo {
+    /** The browser's id. */
+    id: string;
+    /** Its label. */
+    name: string;
+    /** An Oya Browser on the control socket, or a third-party browser over CDP. */
+    clientType: 'oya' | 'cdp';
+    /** Which provider runs it. */
+    provider: string | null;
+    /** The persona id it runs as. */
+    persona: string | null;
+    /** That persona's name. */
+    personaName: string | null;
+    /** How it is doing. */
+    health: Health;
+    /** When it connected. */
+    connectedAt: string;
+    /** When it was last heard from. */
+    lastSeen: string;
+    /** The page it is on. */
+    currentUrl: string;
+    /** Commands run so far. */
+    commands: number;
+    /** Commands that failed. */
+    errors: number;
+    /** Commands in flight. */
+    pending: number;
+    /** When it last ran a command. */
+    lastCommandAt: string | null;
+    /** The last failure's message. */
+    lastError: string | null;
+}
+/** A browser plus what it has been doing, from `browser.status()`. */
+interface BrowserDetail extends BrowserInfo {
+    /** Its most recent commands, newest first. */
+    activity: Activity[];
 }
 
-/** Everything the API returns or accepts, in one place. */
+/**
+ * Types for a key's settings: the LLM behind `ask()`, the browser provider and
+ * the CAPTCHA solver, as `config.set()` accepts them and `config.get()` returns them.
+ */
+
 /** Which model drives `ask()` and the chat API. */
 type LlmProvider = 'openai' | 'anthropic'
 /** Gemini via AI Studio. */
@@ -24,6 +242,7 @@ type CaptchaSolver = 'capsolver' | '2captcha' | '';
  * `null` clears a field and falls back to the deployment default.
  */
 interface ConfigUpdate {
+    /** Which LLM vendor `ask()` and the chat API call. */
     llm_provider?: LlmProvider | null;
     /** The credential for whichever `llm_provider` is set — the field name is shared. */
     openai_api_key?: string | null;
@@ -31,111 +250,119 @@ interface ConfigUpdate {
     openai_base_url?: string | null;
     /** Overrides the provider's default model. */
     chat_model?: string | null;
+    /** Where this key's browsers run unless `start()` names a provider. */
     browser_provider?: Provider | null;
+    /** Anchor's API key, for the 'anchor' provider. */
     anchor_api_key?: string | null;
+    /** Browserbase's API key, for the 'browserbase' provider. */
     browserbase_api_key?: string | null;
+    /** The Browserbase project browsers are created in. */
     browserbase_project_id?: string | null;
+    /** Steel's API key, for the 'steel' provider. */
     steel_api_key?: string | null;
+    /** Browser Use Cloud's API key, for the 'browseruse' provider. */
     browseruse_api_key?: string | null;
+    /** The DevTools WebSocket URL of your own Chrome, for the 'cdp' provider. */
     cdp_ws_url?: string | null;
+    /** Which CAPTCHA solving service to call. */
     captcha_solver?: CaptchaSolver | null;
+    /** The solving service's API key. */
     captcha_api_key?: string | null;
+    /** Set once onboarding has been completed, so the console stops offering it. */
     onboarded?: string | null;
 }
 /** What `config.get()` returns. Secrets read back masked, never in full. */
 interface Config extends Omit<ConfigUpdate, 'llm_provider' | 'browser_provider' | 'captcha_solver'> {
+    /** The configured LLM vendor, or empty for the deployment default. */
     llm_provider?: LlmProvider | '';
+    /** The configured browser provider, or empty for the deployment default. */
     browser_provider?: Provider | '';
+    /** The configured CAPTCHA solver; empty when solving is off. */
     captcha_solver?: CaptchaSolver;
     /** What this key would actually use right now, deployment defaults included. */
     effective: {
+        /** The LLM endpoint in use. */
         baseUrl: string;
+        /** The model in use. */
         model: string;
+        /** Whether any LLM credential is available. */
         hasLlmKey: boolean;
     };
     /** True when the LLM key in play belongs to the deployment, not this key. */
     inherited: boolean;
+    /** Whether this key has its own LLM credential stored. */
     has_openai_key: boolean;
+    /** Every browser provider, what it needs configured, and whether it is. */
     providers: Array<{
+        /** The provider. */
         id: Provider;
+        /** Its display name. */
         label: string;
+        /** The config fields it requires. */
         needs: string[];
+        /** Whether those fields are set. */
         configured: boolean;
     }>;
 }
-/** Where a browser comes from. Configuration, not something a caller must know. */
-type Provider = 'oya-cloud' | 'oya-selfhosted' | 'browseruse' | 'browserbase' | 'steel' | 'anchor' | 'cdp';
-interface StartOptions {
-    /** Reuse this value when retrying the same logical creation. */
-    idempotencyKey?: string;
-    /** Wait for capacity for up to five minutes; zero rejects immediately. */
-    queueMs?: number;
-    budgetUsd?: number;
-    governed?: boolean;
-    policy?: {
-        allowedHosts?: string[];
-        humanHosts?: string[];
-        region?: string;
-        redactRecording?: boolean;
-    };
-    priority?: 'low' | 'normal' | 'high';
-    /** Saved login profile. Defaults to the desktop's default profile. */
-    profile?: string;
-    /**
-     * Which identity to run as. A persona is one device: fingerprint, cookie jar
-     * and proxy bound together and stable for its life.
-     *   'default' — this key's own persona (the default)
-     *   'auto'    — the least recently used persona under its concurrency cap
-     *   <id>      — a specific persona
-     */
-    persona?: 'default' | 'auto' | (string & {});
-    /** Solve CAPTCHAs as they appear rather than waiting to be asked. */
-    captcha?: 'auto' | 'off';
-    /** Override the key's configured provider for this browser only. */
-    provider?: Provider;
-    /** Required only for the 'cdp' provider. */
-    wsUrl?: string;
-    name?: string;
-    /** How long to wait for a cloud browser to dial in. Default 120s. */
-    readyTimeoutMs?: number;
-}
-interface StartResult {
-    id: string;
-    provider: string;
-    persona: string;
-    status: 'ready' | 'starting';
-    /** Point Playwright, Puppeteer or browser-use at this. */
-    cdpUrl?: string;
-    note?: string;
+
+/**
+ * OyaError: the one error type the SDK throws for a failed call, carrying the
+ * HTTP status and the server's answer so a caller can branch on either.
+ */
+/** A failed API call or browser command. */
+declare class OyaError extends Error {
+    /** The HTTP status, or the SDK's own status for errors it raises itself. */
+    readonly status: number;
+    /** The server's response body, parsed when it was JSON. */
+    readonly body: unknown;
+    /** Records the message, status and body. */
+    constructor(message: string, status: number, body: unknown);
 }
+
+/**
+ * Types for agent work: task values and files, playbooks and their replays,
+ * and background runs with their attention requests.
+ */
+
+/** A saved flow, replayable without an LLM. */
 interface Playbook {
+    /** The name it is played by. */
     name: string;
     /** Inputs `play()` accepts; any left out reuse the recorded value. */
     variables: string[];
     /** What each variable was recorded with. A secret has none — it never left the page. */
     defaults: Record<string, string>;
+    /** How many steps it replays. */
     steps: number;
     /** The same flow as a Playwright module: `export default async function run(page, vars)`. */
     code: string;
 }
+/** What a `play()` did. */
 interface PlayResult {
     /** Steps replayed before finishing or handing over to the agent. */
     steps: number;
+    /** Steps in the playbook. */
     total: number;
     /** A step no longer fit the page and the agent finished the task. */
     fellBack: boolean;
     /** The agent's fix was saved as `draft`; promote it with `oya.playbooks.promote(name)`. */
     healed?: boolean;
+    /** The draft's name, when one was saved. */
     draft?: string;
     /** The agent's summary, when it fell back. */
     text?: string;
 }
+/** A playbook in the listing, with its history and any pending fix. */
 interface PlaybookSummary extends Playbook {
+    /** When it was saved. */
     createdAt: string | null;
+    /** When a draft last replaced it. */
     promotedAt: string | null;
     /** A healed replay's fix, waiting for `promote()` or `remove('<name>:draft')`. */
     draft: (Playbook & {
+        /** When the replay was healed. */
         healedAt: string;
+        /** The step the replay broke at. */
         healedFrom: number;
     }) | null;
 }
@@ -161,29 +388,46 @@ interface FileValue {
  * upload tool rather than typing it.
  */
 type RunData = Record<string, string | number | FileValue>;
+/** A run is waiting on a person. */
 interface AttentionRequest {
+    /** Identifies this request; a new one means a new problem. */
     id: string;
     /** captcha / login / mfa: finish it in the live view. agent: the agent's question. heal_failed: replay and the agent both gave up. */
     reason: 'captcha' | 'login' | 'mfa' | 'agent' | 'heal_failed';
+    /** What is needed, in words. */
     message: string;
+    /** Where to finish it by hand. */
     liveViewUrl?: string;
+    /** When it was raised, in epoch milliseconds. */
     at: number;
 }
+/** What a finished run produced: a replay's result, an agent's answer, or both. */
 type RunResult = Partial<PlayResult> & {
+    /** The agent's answer. */
     text?: string;
 };
+/** A background run's state. */
 interface RunInfo {
+    /** The run's id. */
     id: string;
+    /** The browser it runs on. */
     browserId: string;
+    /** Where it is. */
     status: 'running' | 'needs_attention' | 'succeeded' | 'failed';
+    /** When it started, in epoch milliseconds. */
     createdAt: number;
+    /** When it ended. */
     endedAt?: number;
+    /** The open request for a person, if any. */
     attention: AttentionRequest | null;
+    /** What it produced, once it succeeded. */
     result?: RunResult;
+    /** Why it failed. */
     error?: string;
     /** HTTP-style status of a failure: 429 when a quota stopped the run. */
     errorStatus?: number;
 }
+/** The inputs and callbacks for `browser.submit()`. */
 interface SubmitOptions {
     /** Task values the agent can read; for a playbook, its variables (secret ones included). */
     data?: RunData;
@@ -191,7 +435,9 @@ interface SubmitOptions {
     secrets?: RunData;
     /** Playbooks only: let the agent finish a broken replay and save its fix as a draft. Default true. */
     autoHeal?: boolean;
+    /** Fires once with the result when the run succeeds. */
     onSuccess?: (result: RunResult) => unknown;
+    /** Fires once when the run fails, or when it can no longer be polled. */
     onFailure?: (error: OyaError) => unknown;
     /** Call `respond()` once it is handled: `'done'` after finishing by hand, or your answer to the agent. */
     onHumanAttention?: (request: AttentionRequest & {
@@ -202,165 +448,151 @@ interface SubmitOptions {
     /** How often to check on the run. Default 2000. */
     pollMs?: number;
 }
-interface Element {
-    id: number;
-    type: string;
-    /** Visible label, capped at 80 characters by the analyzer. */
-    text?: string;
-    href?: string;
-    value?: string;
-    checked?: boolean;
-    disabled?: boolean;
-    visible: boolean;
-    tag?: string;
-    /** The element's DOM `id`. Usually the most stable handle a site offers. */
-    domId?: string;
-    ariaLabel?: string;
-    /** `data-testid`, when the site ships one. */
-    testId?: string;
-    name?: string;
-    placeholder?: string;
-    /** Action of the enclosing form. */
-    formName?: string;
-}
-interface Analysis {
-    /** The page as markdown. */
-    markdown: string;
-    elements: Element[];
-    viewport?: {
-        width: number;
-        height: number;
-    };
-    scroll?: {
-        x: number;
-        y: number;
-    };
-    truncated?: boolean;
-}
-interface CaptchaResult {
-    present: boolean;
-    solved: boolean;
-    /** 'provider' when the vendor solved it, 'solver' when we did, 'none' otherwise. */
-    method: 'provider' | 'solver' | 'none';
-    type?: string;
-    /** Invisible reCAPTCHA v3 scores the visit passively; there is nothing on screen to clear. */
-    invisible?: boolean;
-    sitekey?: string | null;
-    error?: string;
-}
-interface MfaResult {
-    present: boolean;
-    completed: boolean;
-    method?: 'totp' | 'email' | 'sms' | 'handoff' | 'none';
-    filled?: boolean;
-    submitted?: boolean;
-    /** Open this to finish by hand when nothing automated can. */
-    liveViewUrl?: string | null;
-    error?: string;
-}
+
+/**
+ * Types for identities: a persona's device and fingerprint, the proxies it
+ * exits through, and the second factors and site logins stored for it.
+ */
+/** The device a persona presents. Fixed for its life. */
 interface Fingerprint {
+    /** `navigator.platform`. */
     platform: string;
+    /** IANA timezone. */
     timezone: string;
+    /** BCP 47 locale. */
     locale: string;
+    /** Screen size, as `WIDTHxHEIGHT`. */
     screen: string;
+    /** The GPU the WebGL renderer reports. */
     webgl: string;
+    /** Logical CPU cores reported. */
     hardwareConcurrency: number;
+    /** Device memory reported, in GB. */
     deviceMemory: number;
+    /** Seed for the persona's stable canvas noise. */
     canvasSeed: number;
 }
 /** Device choices made at creation. Fixed for the persona's life. */
 interface PersonaPrefs {
+    /** Which operating system to present. */
     platform?: 'Win32' | 'MacIntel' | 'Linux x86_64';
+    /** IANA timezone; must be one the platform can coherently claim. */
     timezone?: string;
+    /** BCP 47 locale; must be one the platform can coherently claim. */
     locale?: string;
 }
 /** A proxy exit. Credentials go in on create and never come back out. */
 interface ProxyInfo {
+    /** The proxy's id. */
     id: string;
+    /** Its display name. */
     label: string;
+    /** Residential IPs look like homes; datacenter ones are cheaper and easier to flag. */
     kind: 'residential' | 'datacenter';
     /** Two-letter country, optionally a region: "US", "US-CA". */
     geo: string | null;
     /** Provided by the host rather than this key. Cannot be removed. */
     shared: boolean;
+    /** Whether its last check passed. */
     healthy: boolean;
     /** Healthy and not cooling down after a failure. */
     available: boolean;
     /** Where traffic actually leaves, as of the last check. */
     exitIp: string | null;
+    /** When it was last checked. */
     lastCheckedAt: string | null;
     /** Personas on it now, out of `maxPersonas`. */
     assigned: number;
+    /** How many personas may share it. */
     maxPersonas: number;
+    /** How long until a failed proxy is tried again. */
     cooldownMsRemaining: number;
 }
+/** A proxy to add. */
 interface ProxyCreate {
     /** http(s)://user:pass@host:port from your vendor. Chromium cannot use SOCKS5 with a password. */
     url: string;
+    /** A display name. */
     label?: string;
+    /** Two-letter country, optionally a region, used to match personas' geo hints. */
     geo?: string;
+    /** Residential or datacenter. */
     kind?: 'residential' | 'datacenter';
     /** Personas that may share it. Keep 1 for a sticky-session URL so each keeps its own IP. */
     maxPersonas?: number;
 }
+/** A persona: one device, its cookie jar and its proxy. */
 interface PersonaInfo {
+    /** The persona's id. */
     id: string;
+    /** Its display name. */
     name: string;
+    /** Whether it is this key's own default persona. */
     isDefault: boolean;
+    /** Browsers running as it now. */
     activeBrowsers: number;
+    /** How many may run as it at once; null for no cap. */
     maxConcurrent: number | null;
+    /** Where its proxy should be, before one is assigned. */
     proxy: {
+        /** Two-letter country, optionally a region. */
         geo: string | null;
     } | null;
     /** The proxy it is actually on, once assigned or pinned. */
     exit: {
+        /** The proxy's id. */
         id: string;
+        /** Its display name. */
         label: string;
+        /** Its country and region. */
         geo: string | null;
+        /** Whether its last check passed. */
         healthy: boolean;
     } | null;
+    /** The device choices it was created with. */
     prefs: PersonaPrefs | null;
+    /** The device it presents. */
     fingerprint: Fingerprint;
+    /** Its persona-wide second factor. */
     mfa: {
+        /** Whether a factor is stored. */
         configured: boolean;
+        /** Which kind of factor. */
         type?: string;
+        /** The site it is filed against, if any. */
         domain?: string;
     };
     /** Per-site factors and stored logins. Usernames and types only, never secrets. */
     sites: {
+        /** Second factors filed against one site. */
         mfa: {
+            /** The site. */
             domain: string;
+            /** Which kind of factor. */
             type: string;
         }[];
+        /** Stored site logins. */
         credentials: {
+            /** The site. */
             domain: string;
+            /** The account name. */
             username: string;
         }[];
     };
+    /** What its cookie jar holds. */
     login: {
+        /** Cookies in the jar. */
         cookies: number;
+        /** Sites it holds a session for. */
         sites: string[];
+        /** When the jar last changed. */
         updatedAt: string | null;
     };
+    /** When it was created. */
     createdAt: string;
+    /** When a browser last ran as it. */
     lastUsedAt: string | null;
 }
-type Health = 'ok' | 'stale' | 'errors' | 'dead';
-interface Activity {
-    ts: string;
-    action: string;
-    summary: string;
-    ok: boolean;
-    ms: number;
-    error?: string;
-}
-interface StopResult {
-    id: string;
-    ok: boolean;
-    provider?: string | null;
-    sandboxRemoved?: boolean | null;
-    error?: string;
-}
 /**
  * A second factor. `domain` files it against one site, because a persona driving
  * several portals meets several kinds of factor; without it the record is the
@@ -375,122 +607,452 @@ interface StopResult {
  * `pattern` is only the fallback for when no LLM key is set or the call fails.
  */
 type MfaConfig = {
+    /** The site this factor answers for; without it, the persona-wide default. */
     domain?: string;
 } & ({
+    /** An authenticator app's time-based codes. */
     type: 'totp';
+    /** The base32 seed. */
     secret: string;
 } | {
+    /** Codes delivered to an endpoint you host. */
     type: 'email' | 'sms';
+    /** The endpoint polled for the latest message. */
     url: string;
+    /** Headers sent with each poll. */
     headers?: Record<string, string>;
+    /** Fallback regex for the code, used when no LLM is available. */
     pattern?: string;
+    /** How long to wait for a code. */
     timeoutMs?: number;
 } | {
+    /** Codes read from a Gmail or Microsoft 365 mailbox. */
     type: 'gmail' | 'graph';
+    /** The mailbox's OAuth refresh token. */
     refreshToken: string;
+    /** The OAuth client the token was issued to. */
     clientId: string;
+    /** That client's secret, when it has one. */
     clientSecret?: string;
+    /** The Microsoft tenant, for `graph`. */
     tenant?: string;
+    /** A mailbox search narrowing which messages are read. */
     query?: string;
+    /** Fallback regex for the code, used when no LLM is available. */
     pattern?: string;
+    /** How long to wait for a code. */
     timeoutMs?: number;
 });
 /** A site login. The password is write-only: no API ever reads it back. */
 interface SiteCredentials {
+    /** The site it signs in to. */
     domain: string;
+    /** The account name. */
     username: string;
+    /** The password; stored sealed and never returned. */
     password: string;
 }
-interface BrowserInfo {
-    id: string;
-    name: string;
-    clientType: 'oya' | 'cdp';
-    provider: string | null;
-    persona: string | null;
-    personaName: string | null;
-    health: Health;
-    connectedAt: string;
-    lastSeen: string;
-    currentUrl: string;
-    commands: number;
-    errors: number;
-    pending: number;
-    lastCommandAt: string | null;
-    lastError: string | null;
-}
-interface BrowserDetail extends BrowserInfo {
-    activity: Activity[];
-}
-interface OyaOptions {
-    /** Defaults to OYA_API_KEY. */
-    apiKey?: string;
-    /** Defaults to OYA_BASE_URL, then https://browser.getoya.ai. */
-    baseUrl?: string;
-    /** Per-request timeout. Navigation gets its own, longer budget. */
-    timeoutMs?: number;
-    fetch?: typeof globalThis.fetch;
-}
-declare class OyaError extends Error {
-    readonly status: number;
-    readonly body: unknown;
-    constructor(message: string, status: number, body: unknown);
-}
+
+/**
+ * Types for the durable control plane: sessions and their lifecycle, human
+ * takeover, project settings, lifecycle events and service credentials.
+ */
+/** What a member or credential may do: read, operate browsers, or also administer the project. */
 type ControlRole = 'viewer' | 'operator' | 'administrator';
 /** What a human holding the control lease may send. Mirrors the server's allowlist. */
 type HumanInputAction = 'click' | 'type' | 'press_key' | 'scroll' | 'click_coordinates' | 'double_click' | 'drag' | 'mouse_move' | 'scroll_at' | 'type_text' | 'keyboard_type' | 'navigate' | 'back' | 'forward' | 'reload' | 'screenshot' | 'analyze' | 'read_page';
+/** A browser session as the control plane records it, including ones no longer connected. */
 interface ControlSession {
+    /** The session's id, which is also the browser's. */
     id: string;
+    /** The project it belongs to. */
     project: string;
+    /** Which provider runs it. */
     provider: string;
+    /** The persona it runs as. */
     persona: string | null;
+    /** Where it is in its lifecycle. */
     state: 'queued' | 'provisioning' | 'ready' | 'disconnected' | 'stopping' | 'cleanup_pending' | 'stopped' | 'failed' | 'unknown_outcome';
+    /** Whether the control plane provisioned it (and so must clean it up). */
     managed: boolean;
+    /** When it was created, in epoch milliseconds. */
     createdAt: number;
+    /** When its state last changed. */
     updatedAt: number;
+    /** Estimated spend so far, in US dollars. */
     costUsd: number;
+    /** Who is driving it. */
     control: {
+        /** The agent, a person, or nobody while paused. */
         mode: 'agent' | 'human' | 'paused';
+        /** When a human lease runs out. */
         expiresAt?: number;
     };
+    /** Why cleanup has not finished. */
     cleanupError?: string;
 }
+/** A project's limits, retention and rate cards. */
 interface ProjectSettings {
+    /** Days recordings are kept. */
     recordingDays: number;
+    /** Days audit events are kept. */
     auditDays: number;
+    /** Spend ceiling in US dollars; null for none. */
     budgetUsd: number | null;
+    /** Browsers that may run at once; null for no cap. */
     maxConcurrent: number | null;
+    /** Price per unit, by what is metered. */
     rates: Record<string, number>;
+    /** The default policy for governed browsers. */
     policy: Record<string, unknown>;
 }
+/** One durable lifecycle event. */
 interface ControlEvent {
+    /** Increasing id, used as the read cursor. */
     id: number;
+    /** The project it belongs to. */
     project: string;
+    /** What happened. */
     type: string;
+    /** The session it concerns, if any. */
     sessionId: string | null;
+    /** When, in epoch milliseconds. */
     at: number;
+    /** Event-specific fields. */
     detail: Record<string, unknown>;
 }
+/** A service credential. Its token is shown once, at creation. */
 interface ControlCredential {
+    /** The credential's id, for revoking it. */
     id: string;
+    /** What it is for. */
     label: string;
+    /** What it may do. */
     role: ControlRole;
+    /** When it stops working; null for never. */
     expiresAt: number | null;
+    /** When it was revoked, if it was. */
     revokedAt: number | null;
 }
+/** The project at a glance: settings, sessions, recent events. */
 interface ControlOverview {
     /** costUsd: estimated lifetime spend, metered from rate cards. */
     project: {
+        /** The project's id. */
         id: string;
+        /** Its name. */
         name: string;
+        /** Its limits and retention. */
         settings: ProjectSettings;
+        /** Estimated lifetime spend, in US dollars. */
         costUsd?: number;
     };
+    /** Every session the control plane knows about. */
     sessions: ControlSession[];
+    /** Recent lifecycle events. */
     events: ControlEvent[];
+    /** True while the server is draining for a restart. */
     draining: boolean;
+    /** Service credentials, for administrators. */
     credentials?: ControlCredential[];
 }
 
+/**
+ * The options the `Oya` client is constructed with.
+ */
+/** How to reach the control plane, and as whom. */
+interface OyaOptions {
+    /** Defaults to OYA_API_KEY. */
+    apiKey?: string;
+    /** Defaults to OYA_BASE_URL, then https://browser.getoya.ai. */
+    baseUrl?: string;
+    /** Per-request timeout. Navigation gets its own, longer budget. */
+    timeoutMs?: number;
+    /** A fetch to use instead of the global one, for tests, proxies or old runtimes. */
+    fetch?: typeof globalThis.fetch;
+}
+
+/** The one HTTP path. Everything else in this package is a wrapper over it. */
+declare class Http {
+    readonly baseUrl: string;
+    readonly apiKey: string;
+    private readonly timeoutMs;
+    private readonly fetchImpl;
+    /** Stores where to call, with which key, how long to wait and which fetch to use. */
+    constructor(baseUrl: string, apiKey: string, timeoutMs: number, fetchImpl: typeof globalThis.fetch);
+    /** Sends one request and returns the parsed answer, or throws an OyaError when it failed. */
+    request<T>(method: string, path: string, body?: unknown, timeoutMs?: number, headers?: Record<string, string>): Promise<T>;
+}
+
+/**
+ * The shapes the client's namespaces (`oya.browser`, `oya.control`,
+ * `oya.personas` …) take and return that are not part of the exported types,
+ * named so each field can say what it is.
+ */
+
+/** What stopping several browsers did. */
+interface StopManyResult {
+    /** How many stopped. */
+    stopped: number;
+    /** Each browser's outcome. */
+    results: StopResult[];
+}
+/** A plain acknowledgement. */
+interface Ack {
+    /** Whether it was done. */
+    ok: boolean;
+}
+/** A single-use live-stream ticket. */
+interface Ticket {
+    /** The ticket. */
+    ticket: string;
+    /** Seconds until it expires. */
+    expiresIn: number;
+}
+/** A page of lifecycle events. */
+interface EventPage {
+    /** Events after the cursor asked for. */
+    events: ControlEvent[];
+    /** Pass this as `after` to read on. */
+    cursor: number;
+}
+/** A service credential to mint. */
+interface CredentialRequest {
+    /** What it may do. */
+    role: ControlRole;
+    /** What it is for. */
+    label?: string;
+    /** When it stops working, in epoch milliseconds. */
+    expiresAt?: number;
+}
+/** A new service credential, with its token: shown this once. */
+interface NewCredential extends ControlCredential {
+    /** The secret to authenticate with. */
+    token: string;
+}
+/** One project member. */
+interface Member {
+    /** The member's user id. */
+    userId: string;
+    /** What they may do. */
+    role: ControlRole;
+}
+/** The project's owner and members. */
+interface MemberList {
+    /** The owner's user id. */
+    owner: string | null;
+    /** Everyone else. */
+    members: Member[];
+}
+/** An invitation code. */
+interface Invite {
+    /** The code to hand to the invitee. */
+    code: string;
+    /** Seconds until it expires. */
+    expiresIn: number;
+}
+/** A registered webhook. */
+interface Webhook {
+    /** Its id, for removing it. */
+    id: string;
+    /** The key its deliveries are signed with. */
+    secret: string;
+}
+/** One proxy's check. */
+interface ProxyCheck {
+    /** The proxy. */
+    id: string;
+    /** Whether it answered. */
+    ok: boolean;
+    /** Where its traffic actually leaves. */
+    exitIp?: string | null;
+    /** Why it failed. */
+    error?: string;
+}
+/** Where a persona's proxy should be. */
+interface GeoHint {
+    /** Two-letter country, optionally a region. */
+    geo?: string;
+}
+/** A persona to create. */
+interface PersonaCreate {
+    /** Its display name. */
+    name?: string;
+    /** Device choices, fixed for its life. */
+    prefs?: PersonaPrefs;
+    /** Where its proxy should be. */
+    proxy?: GeoHint;
+    /** How many browsers may run as it at once; null for no cap. */
+    maxConcurrent?: number | null;
+}
+/** What may change on a persona. Never the device. */
+interface PersonaUpdate {
+    /** Its display name. */
+    name?: string;
+    /** How many browsers may run as it at once; null for no cap. */
+    maxConcurrent?: number | null;
+    /** Where its proxy should be; null clears the hint. */
+    proxy?: GeoHint | null;
+}
+/** Options for a clone. */
+interface CloneOptions {
+    /** The new persona's name. */
+    name?: string;
+}
+/** What a persona may claim, per platform. */
+interface PersonaOptions {
+    /** The platforms on offer. */
+    platforms: string[];
+    /** Timezones each platform may coherently claim. */
+    timezones: Record<string, string[]>;
+    /** Locales each platform may coherently claim. */
+    locales: Record<string, string[]>;
+}
+/** The proxy a persona is pinned to. */
+interface PinnedProxy {
+    /** The proxy's id. */
+    id: string;
+    /** Its display name. */
+    label: string;
+}
+/** The outcome of pinning a proxy. */
+interface ProxyPin {
+    /** Whether it was saved. */
+    ok: boolean;
+    /** The proxy now pinned, or null when assignment is left to connect time. */
+    proxy: PinnedProxy | null;
+}
+/** A stored second factor, as confirmed. */
+interface MfaSaved {
+    /** Whether it is stored. */
+    configured: boolean;
+    /** Which kind of factor. */
+    type: string;
+}
+/** A site login the persona can use. Never the password. */
+interface SiteLogin {
+    /** The site. */
+    domain: string;
+    /** The account name. */
+    username: string;
+}
+/** A stored site login, as confirmed. */
+interface CredentialsSaved extends SiteLogin {
+    /** Whether it is stored. */
+    configured: boolean;
+}
+/** The sites a persona can sign in to. */
+interface SiteLogins {
+    /** Usernames only. */
+    credentials: SiteLogin[];
+}
+
+/**
+ * The shapes Browser's methods take and return that are not part of the
+ * exported types: tab listings, dialog answers, share links and the like.
+ * Named here so each field can say what it is.
+ */
+
+/** What `type()` reports back. */
+interface TypeResult {
+    /** An autocomplete list opened under the field; pick from it before moving on. */
+    suggestions_visible?: boolean;
+}
+/** The dialog `handleDialog()` answered. */
+interface DialogResult {
+    /** alert, confirm, prompt or beforeunload. */
+    type: string;
+    /** The dialog's text. */
+    message: string;
+    /** Whether it was accepted. */
+    accepted: boolean;
+}
+/** A point on the page, in CSS pixels. */
+interface Point {
+    /** From the left edge. */
+    x: number;
+    /** From the top edge. */
+    y: number;
+}
+/** One open tab. */
+interface Tab {
+    /** The tab's id, for `switchTab()` and `closeTab()`. */
+    id: string;
+    /** The page it shows. */
+    url: string;
+    /** The page's title. */
+    title: string;
+    /** Whether it is the tab commands act on. */
+    active: boolean;
+}
+/** Task values for `ask()`. */
+interface AskValues {
+    /** Values the agent can read. */
+    data?: RunData;
+    /** Values the agent never sees. */
+    secrets?: RunData;
+}
+/** How `play()` handles a step that no longer fits. */
+interface PlayOptions {
+    /** Let the agent finish the task and save its fix as a draft. Default true. */
+    autoHeal?: boolean;
+}
+/** What `submit()` runs: a prompt for the agent, or a saved playbook. */
+type Task = {
+    /** A natural-language task for the agent. */
+    prompt: string;
+} | {
+    /** The name of a saved playbook. */
+    playbook: string;
+};
+/** How a `shareUrl()` link works. */
+interface ShareOptions {
+    /** Let whoever opens it act in the browser. Default view-only. */
+    control?: boolean;
+    /** How long it lasts. Default one hour. */
+    expiresInSeconds?: number;
+}
+/** A link from `shareUrl()`. */
+interface ShareLink {
+    /** The link to hand out. */
+    url: string;
+    /** Its credential's id, for `revokeShare()`. */
+    id: string;
+    /** When it stops working, in epoch milliseconds; null for never. */
+    expiresAt: number | null;
+}
+
+/** The callbacks a run can fire. */
+type RunCallbacks = Pick<SubmitOptions, 'onSuccess' | 'onFailure' | 'onHumanAttention' | 'onHealed'>;
+
+/**
+ * Run: a task submitted with `browser.submit()`, running in the background.
+ * The polling itself lives in run-watch.ts.
+ */
+
+/** A submitted task. Callbacks fire as it changes; `done` settles when it ends. */
+declare class Run {
+    private readonly http;
+    readonly id: string;
+    /** Settles with the result when the run succeeds, or rejects when it fails. */
+    readonly done: Promise<RunResult>;
+    /** Starts watching the run straight away. */
+    constructor(http: Http, id: string, callbacks: RunCallbacks, pollMs?: number);
+    /** The run's current state. */
+    status(): Promise<RunInfo>;
+    /** Answer the open attention request: `'done'` after handling it by hand, or your reply to the agent. */
+    respond(response?: string): Promise<void>;
+    /** Polls until the run ends, firing callbacks on the way. */
+    private watch;
+}
+
+/**
+ * Browser: one running browser, driven through the API. Page actions go
+ * through the command endpoint; CAPTCHA, MFA, agent runs, playbooks and live
+ * view links have their own endpoints. The small rules the methods share
+ * (element ids, aimed scrolls, agent errors) are the functions below the class.
+ */
+
 /**
  * One running browser.
  *
@@ -501,54 +1063,56 @@ interface ControlOverview {
 declare class Browser {
     private readonly http;
     private readonly autoCaptcha;
+    /** The browser's id. */
     readonly id: string;
+    /** Which provider runs it. */
     readonly provider: string;
+    /** Which persona it runs as. */
     readonly persona: string;
     /** Point Playwright, Puppeteer or browser-use here. */
     readonly cdpUrl?: string;
+    /** Wraps a started browser; `autoCaptcha` solves CAPTCHAs after every `goto()`. */
     constructor(http: Http, info: StartResult, autoCaptcha: boolean);
+    /** Runs one browser command; a command that ran and failed throws. */
     private command;
+    /** Navigates, then clears any CAPTCHA when `captcha: 'auto'` was asked for. */
     goto(url: string): Promise<void>;
     /** The page as markdown plus numbered elements to act on. */
     analyze(): Promise<Analysis>;
     /** Only the visible elements, which is what an agent almost always wants. */
     elements(): Promise<Element[]>;
+    /** Clicks an element by its id from `analyze()`. */
     click(elementId: number | string): Promise<void>;
-    type(elementId: number | string, text: string): Promise<{
-        suggestions_visible?: boolean;
-    }>;
+    /** Types into an element by its id from `analyze()`. */
+    type(elementId: number | string, text: string): Promise<TypeResult>;
+    /** A valid element id, or an OyaError saying where ids come from. */
     private elementId;
+    /** Presses one key, such as Enter or Escape. */
     pressKey(key: string): Promise<void>;
     /**
      * Answer a native dialog holding the page. alert() and beforeunload are
      * answered for you; a confirm() or prompt() waits for this, and every other
      * command fails fast with the dialog's text until it is answered.
      */
-    handleDialog(accept: boolean, promptText?: string): Promise<{
-        type: string;
-        message: string;
-        accepted: boolean;
-    }>;
+    handleDialog(accept: boolean, promptText?: string): Promise<DialogResult>;
     /** `at` aims the wheel at an inner scroller (a results panel, a chat pane) instead of the page. */
-    scroll(direction: 'up' | 'down' | 'top' | 'bottom', amount?: number, at?: {
-        x: number;
-        y: number;
-    }): Promise<void>;
+    scroll(direction: 'up' | 'down' | 'top' | 'bottom', amount?: number, at?: Point): Promise<void>;
+    /** Waits until `selector` matches, up to `timeout` milliseconds. */
     waitFor(selector: string, timeout?: number): Promise<void>;
     /** A `data:image/…;base64,` URL. PNG or JPEG depending on the driver. */
     screenshot(): Promise<string>;
+    /** The active tab's URL, or empty when there is none. */
     url(): Promise<string>;
-    tabs(): Promise<Array<{
-        id: string;
-        url: string;
-        title: string;
-        active: boolean;
-    }>>;
+    /** Every open tab. */
+    tabs(): Promise<Array<Tab>>;
+    /** Opens a tab, optionally at `url`, and returns its id. */
     openTab(url?: string): Promise<string>;
+    /** Makes a tab the one commands act on. */
     switchTab(tabId: string): Promise<void>;
+    /** Closes a tab. */
     closeTab(tabId: string): Promise<void>;
     /**
-    x * Detect and clear a CAPTCHA. Providers that solve natively are left to do
+     * Detect and clear a CAPTCHA. Providers that solve natively are left to do
      * it; everything else goes to the configured solver.
      */
     solveCaptcha(): Promise<CaptchaResult>;
@@ -563,10 +1127,7 @@ declare class Browser {
      * the matching option; `secrets` it never sees. It types both through placeholders,
      * with filters like `{{name|first}}`, so a playbook saved from the run stores no values.
      */
-    ask(prompt: string, { data, secrets }?: {
-        data?: RunData;
-        secrets?: RunData;
-    }): Promise<string>;
+    ask(prompt: string, { data, secrets }?: AskValues): Promise<string>;
     /**
      * Save the last `ask()` on this browser as a named playbook. Every value that was
      * typed, picked or clicked becomes a variable, with what the run used kept in
@@ -581,31 +1142,17 @@ declare class Browser {
      * saved as a draft (`healed`, `draft`); off, the step's error is thrown.
      * Play `'<name>:draft'` to try a draft before promoting it.
      */
-    play(name: string, data?: RunData, { autoHeal }?: {
-        autoHeal?: boolean;
-    }): Promise<PlayResult>;
+    play(name: string, data?: RunData, { autoHeal }?: PlayOptions): Promise<PlayResult>;
     /**
      * Start a prompt or playbook in the background and hear back through callbacks.
      * `onHumanAttention` fires for an unsolved CAPTCHA, an unfinished MFA, the agent
      * asking for help, or a replay the agent could not heal; the run waits (up to 30
      * minutes) until you call `respond()`.
      */
-    submit(task: {
-        prompt: string;
-    } | {
-        playbook: string;
-    }, options?: SubmitOptions): Promise<Run>;
+    submit(task: Task, options?: SubmitOptions): Promise<Run>;
     /**
-     * Watch it work: the console, opened on this browser.
-     *
-     * This used to return the raw frame stream with the project's API key in the
-     * query string — a permanent credential in browser history, Referer headers
-     * and every proxy log on the way, and a URL that renders as a wall of
-     * text/event-stream if a person actually opens it. It is the console deep
-     * link now, the same one the server hands back from `completeMfa()`, and it
-     * carries no credential at all.
-     *
-     * For the frames themselves, use `liveStreamUrl()`.
+     * Watch it work: the console, opened on this browser. It carries no
+     * credential. For the frames themselves, use `liveStreamUrl()`.
      */
     liveViewUrl(): string;
     /**
@@ -625,14 +1172,7 @@ declare class Browser {
      * rest of your project. Anyone holding the link has that access until it
      * expires or you revoke it, so treat it like a password.
      */
-    shareUrl({ control, expiresInSeconds }?: {
-        control?: boolean;
-        expiresInSeconds?: number;
-    }): Promise<{
-        url: string;
-        id: string;
-        expiresAt: number | null;
-    }>;
+    shareUrl({ control, expiresInSeconds }?: ShareOptions): Promise<ShareLink>;
     /** Revoke a link from `shareUrl()` before it expires, by the id it returned. */
     revokeShare(id: string): Promise<void>;
     /** Counters, health and the last 50 things this browser did. */
@@ -647,18 +1187,6 @@ declare class Browser {
     /** @deprecated use stop() — close() only dropped the socket, and a cloud browser redialled. */
     close(): Promise<void>;
 }
-type RunCallbacks = Pick<SubmitOptions, 'onSuccess' | 'onFailure' | 'onHumanAttention' | 'onHealed'>;
-/** A submitted task. Callbacks fire as it changes; `done` settles when it ends. */
-declare class Run {
-    private readonly http;
-    readonly id: string;
-    readonly done: Promise<RunResult>;
-    constructor(http: Http, id: string, callbacks: RunCallbacks, pollMs?: number);
-    status(): Promise<RunInfo>;
-    /** Answer the open attention request: `'done'` after handling it by hand, or your reply to the agent. */
-    respond(response?: string): Promise<void>;
-    private watch;
-}
 
 /**
  * Files as task values.
@@ -678,100 +1206,52 @@ declare const MAX_FILE_BYTES: number;
  * from the extension.
  */
 declare function file(source: string | Uint8Array | Blob, options?: {
+    /** The filename the site sees. */
     name?: string;
+    /** The MIME type, instead of the one guessed from the extension. */
     type?: string;
 }): Promise<FileValue>;
 
-/**
- * @oya-ai/browser — thousands of browsers, one API.
- *
- *   import { Oya } from '@oya-ai/browser';
- *
- *   const oya = new Oya();                                    // OYA_API_KEY
- *   const browser = await oya.browser.start({ persona: 'auto', captcha: 'auto' });
- *   await browser.goto('https://example.com');
- *
- * Which provider actually runs the browser — Oya Cloud, your own machines,
- * Browser Use, Browserbase, Steel, Anchor, or a CDP URL you hand us — is
- * configuration on your API key, not something this code has to know.
- */
-
+/** The client: one API key, every browser behind it. */
 declare class Oya {
+    /** The one HTTP path every call goes through. */
     private readonly http;
+    /** Reads the key and URL from `options`, then OYA_API_KEY and OYA_BASE_URL. Throws without a key. */
     constructor(options?: OyaOptions);
+    /** Start, reattach to, list and stop browsers. */
     readonly browser: {
-        /** Start a browser and wait until it can take commands. */
         start: (options?: StartOptions) => Promise<Browser>;
-        /** Reattach to a browser that is already running. */
         get: (id: string) => Promise<Browser>;
         list: () => Promise<BrowserInfo[]>;
-        /** Stop some (`ids`) or every browser on this key. Each reports separately. */
-        stop: (ids: string[] | "all") => Promise<{
-            stopped: number;
-            results: StopResult[];
-        }>;
+        stop: (ids: string[] | "all") => Promise<StopManyResult>;
         stopAll: () => Promise<number>;
     };
     /** Durable operational controls, including disconnected and cleanup-pending sessions. */
     readonly control: {
-        overview: () => Promise<ControlOverview>;
-        sessions: () => Promise<ControlSession[]>;
-        session: (id: string) => Promise<ControlSession>;
-        settings: (changes: Partial<ProjectSettings>) => Promise<ControlOverview["project"]>;
+        createWebhook: (url: string, types?: string[]) => Promise<Webhook>;
+        removeWebhook: (id: string) => Promise<Ack>;
+        replayDelivery: (id: string) => Promise<Ack>;
+        members: () => Promise<MemberList>;
+        inviteMember: (role?: ControlRole) => Promise<Invite>;
+        removeMember: (userId: string) => Promise<Ack>;
+        createCredential: (options: CredentialRequest) => Promise<NewCredential>;
+        revokeCredential: (id: string) => Promise<Ack>;
+        recover: (id: string, replace?: boolean) => Promise<unknown>;
+        ticket: (id: string) => Promise<Ticket>;
+        events: (after?: number) => Promise<EventPage>;
         cancel: (id: string) => Promise<ControlSession>;
         stop: (id: string, force?: boolean) => Promise<StopResult>;
         takeover: (id: string, action: "acquire" | "release" | "resume") => Promise<ControlSession["control"]>;
         input: (id: string, action: HumanInputAction, params: Record<string, unknown>) => Promise<unknown>;
-        recover: (id: string, replace?: boolean) => Promise<unknown>;
-        ticket: (id: string) => Promise<{
-            ticket: string;
-            expiresIn: number;
-        }>;
-        events: (after?: number) => Promise<{
-            events: ControlEvent[];
-            cursor: number;
-        }>;
-        createCredential: (options: {
-            role: ControlRole;
-            label?: string;
-            expiresAt?: number;
-        }) => Promise<ControlCredential & {
-            token: string;
-        }>;
-        revokeCredential: (id: string) => Promise<{
-            ok: boolean;
-        }>;
-        members: () => Promise<{
-            owner: string | null;
-            members: {
-                userId: string;
-                role: ControlRole;
-            }[];
-        }>;
-        inviteMember: (role?: ControlRole) => Promise<{
-            code: string;
-            expiresIn: number;
-        }>;
-        removeMember: (userId: string) => Promise<{
-            ok: boolean;
-        }>;
-        createWebhook: (url: string, types?: string[]) => Promise<{
-            id: string;
-            secret: string;
-        }>;
-        removeWebhook: (id: string) => Promise<{
-            ok: boolean;
-        }>;
-        replayDelivery: (id: string) => Promise<{
-            ok: boolean;
-        }>;
+        overview: () => Promise<ControlOverview>;
+        sessions: () => Promise<ControlSession[]>;
+        session: (id: string) => Promise<ControlSession>;
+        settings: (changes: Partial<ProjectSettings>) => Promise<ControlOverview["project"]>;
     };
     /** Playbooks saved with `browser.toPlaybook()`. */
     readonly playbooks: {
         list: () => Promise<PlaybookSummary[]>;
-        /** Delete a playbook and its draft, or only the draft with `'<name>:draft'`. */
         remove: (name: string) => Promise<void>;
-        /** Replace a playbook with the draft a healed replay saved. Try it first with `browser.play('<name>:draft')`. */
         promote: (name: string) => Promise<Playbook>;
     };
     /**
@@ -782,84 +1262,24 @@ declare class Oya {
         list: () => Promise<ProxyInfo[]>;
         create: (proxy: ProxyCreate) => Promise<ProxyInfo>;
         remove: (id: string) => Promise<void>;
-        /** Dial each proxy and learn its real exit IP. Failing ones cool down and are skipped. */
-        check: () => Promise<Array<{
-            id: string;
-            ok: boolean;
-            exitIp?: string | null;
-            error?: string;
-        }>>;
+        check: () => Promise<Array<ProxyCheck>>;
     };
+    /** Identities: fingerprint, cookie jar and proxy bound together, plus their stored factors and logins. */
     readonly personas: {
-        list: () => Promise<PersonaInfo[]>;
-        get: (id: string) => Promise<PersonaInfo>;
-        /**
-         * Create an identity. The device — platform, timezone, locale — is chosen
-         * here and fixed for its life; `preview()` shows what a choice produces.
-         */
-        create: (options?: {
-            name?: string;
-            prefs?: PersonaPrefs;
-            proxy?: {
-                geo?: string;
-            };
-            maxConcurrent?: number | null;
-        }) => Promise<PersonaInfo>;
-        /** Name, concurrency cap and proxy hint. Never the device — clone for that. */
-        update: (id: string, changes: {
-            name?: string;
-            maxConcurrent?: number | null;
-            proxy?: {
-                geo?: string;
-            } | null;
-        }) => Promise<PersonaInfo>;
-        /** A new persona of the same kind of device: same choices, fresh identity, empty jar. */
-        clone: (id: string, options?: {
-            name?: string;
-        }) => Promise<PersonaInfo>;
-        /** The fingerprint these choices would produce. Persists nothing. */
+        setCredentials: (id: string, config: SiteCredentials) => Promise<CredentialsSaved>;
+        credentials: (id: string) => Promise<SiteLogins>;
+        clearCredentials: (id: string, domain: string) => Promise<void>;
+        setMfa: (id: string, config: MfaConfig) => Promise<MfaSaved>;
+        clearMfa: (id: string, domain?: string) => Promise<void>;
         preview: (prefs?: PersonaPrefs) => Promise<Fingerprint>;
-        /** Platforms, and the timezones and locales each may coherently claim. */
-        options: () => Promise<{
-            platforms: string[];
-            timezones: Record<string, string[]>;
-            locales: Record<string, string[]>;
-        }>;
-        /** Pin the persona to one of your proxies, or `null` to let assignment happen at connect. */
-        pinProxy: (id: string, proxyId: string | null) => Promise<{
-            ok: boolean;
-            proxy: {
-                id: string;
-                label: string;
-            } | null;
-        }>;
+        options: () => Promise<PersonaOptions>;
+        pinProxy: (id: string, proxyId: string | null) => Promise<ProxyPin>;
         remove: (id: string) => Promise<void>;
-        /** Store the second factor for this identity. Sealed at rest, never read back. */
-        setMfa: (id: string, config: MfaConfig) => Promise<{
-            configured: boolean;
-            type: string;
-        }>;
-        clearMfa: (id: string, domain?: string) => Promise<void>;
-        /**
-         * Store a site login for this identity. Sealed at rest, never read back.
-         *
-         * Signing in once on the desktop and inheriting the cookies is still the
-         * better path. This is for portals that expire a session server-side
-         * between runs, where an unattended run has nothing else to recover with.
-         */
-        setCredentials: (id: string, config: SiteCredentials) => Promise<{
-            configured: boolean;
-            domain: string;
-            username: string;
-        }>;
-        /** Which sites this identity can sign in to. Usernames only. */
-        credentials: (id: string) => Promise<{
-            credentials: {
-                domain: string;
-                username: string;
-            }[];
-        }>;
-        clearCredentials: (id: string, domain: string) => Promise<void>;
+        list: () => Promise<PersonaInfo[]>;
+        get: (id: string) => Promise<PersonaInfo>;
+        create: (options?: PersonaCreate) => Promise<PersonaInfo>;
+        update: (id: string, changes: PersonaUpdate) => Promise<PersonaInfo>;
+        clone: (id: string, options?: CloneOptions) => Promise<PersonaInfo>;
     };
     /**
      * This key's settings: LLM credentials, browser provider, solver.
@@ -878,77 +1298,24 @@ declare class Oya {
     };
     /** Saved profiles. `personas` is retained as an alias for existing clients. */
     readonly profiles: {
-        list: () => Promise<PersonaInfo[]>;
-        get: (id: string) => Promise<PersonaInfo>;
-        /**
-         * Create an identity. The device — platform, timezone, locale — is chosen
-         * here and fixed for its life; `preview()` shows what a choice produces.
-         */
-        create: (options?: {
-            name?: string;
-            prefs?: PersonaPrefs;
-            proxy?: {
-                geo?: string;
-            };
-            maxConcurrent?: number | null;
-        }) => Promise<PersonaInfo>;
-        /** Name, concurrency cap and proxy hint. Never the device — clone for that. */
-        update: (id: string, changes: {
-            name?: string;
-            maxConcurrent?: number | null;
-            proxy?: {
-                geo?: string;
-            } | null;
-        }) => Promise<PersonaInfo>;
-        /** A new persona of the same kind of device: same choices, fresh identity, empty jar. */
-        clone: (id: string, options?: {
-            name?: string;
-        }) => Promise<PersonaInfo>;
-        /** The fingerprint these choices would produce. Persists nothing. */
+        setCredentials: (id: string, config: SiteCredentials) => Promise<CredentialsSaved>;
+        credentials: (id: string) => Promise<SiteLogins>;
+        clearCredentials: (id: string, domain: string) => Promise<void>;
+        setMfa: (id: string, config: MfaConfig) => Promise<MfaSaved>;
+        clearMfa: (id: string, domain?: string) => Promise<void>;
         preview: (prefs?: PersonaPrefs) => Promise<Fingerprint>;
-        /** Platforms, and the timezones and locales each may coherently claim. */
-        options: () => Promise<{
-            platforms: string[];
-            timezones: Record<string, string[]>;
-            locales: Record<string, string[]>;
-        }>;
-        /** Pin the persona to one of your proxies, or `null` to let assignment happen at connect. */
-        pinProxy: (id: string, proxyId: string | null) => Promise<{
-            ok: boolean;
-            proxy: {
-                id: string;
-                label: string;
-            } | null;
-        }>;
+        options: () => Promise<PersonaOptions>;
+        pinProxy: (id: string, proxyId: string | null) => Promise<ProxyPin>;
         remove: (id: string) => Promise<void>;
-        /** Store the second factor for this identity. Sealed at rest, never read back. */
-        setMfa: (id: string, config: MfaConfig) => Promise<{
-            configured: boolean;
-            type: string;
-        }>;
-        clearMfa: (id: string, domain?: string) => Promise<void>;
-        /**
-         * Store a site login for this identity. Sealed at rest, never read back.
-         *
-         * Signing in once on the desktop and inheriting the cookies is still the
-         * better path. This is for portals that expire a session server-side
-         * between runs, where an unattended run has nothing else to recover with.
-         */
-        setCredentials: (id: string, config: SiteCredentials) => Promise<{
-            configured: boolean;
-            domain: string;
-            username: string;
-        }>;
-        /** Which sites this identity can sign in to. Usernames only. */
-        credentials: (id: string) => Promise<{
-            credentials: {
-                domain: string;
-                username: string;
-            }[];
-        }>;
-        clearCredentials: (id: string, domain: string) => Promise<void>;
+        list: () => Promise<PersonaInfo[]>;
+        get: (id: string) => Promise<PersonaInfo>;
+        create: (options?: PersonaCreate) => Promise<PersonaInfo>;
+        update: (id: string, changes: PersonaUpdate) => Promise<PersonaInfo>;
+        clone: (id: string, options?: CloneOptions) => Promise<PersonaInfo>;
     };
+    /** What this key has spent. */
     usage(): Promise<unknown>;
+    /** Waits for a starting browser to dial in, through this client's own list and session calls. */
     private waitUntilConnected;
 }