@oya-ai/browser 1.0.110 → 1.0.113

package/README.md

@@ -166,6 +166,21 @@ await browser.ask('Attach my resume to the application and submit it', {
 
 A string argument is a path on disk (Node only); a `Blob`, a `File`, or a `Uint8Array` works anywhere. `name` sets the filename the site sees and `type` overrides the MIME guessed from the extension. The ceiling is 10MB per file, and the bytes travel inline with the run. Nothing is stored server-side after it ends.
 
+### Data instead of a sentence
+
+`extract()` runs the same agent and answers in the shape you ask for, so you do not
+parse prose:
+
+```ts
+const { title, price } = await browser.extract('What is the product on this page?', {
+  type: 'object',
+  properties: { title: { type: 'string' }, price: { type: 'string' } },
+  required: ['title', 'price'],
+});
+```
+
+It throws when the agent reports it could not do the task.
+
 Files work in `data` for `ask()`, `submit()`, and `play()`; `secrets` rejects them, because a file is never typed through a placeholder. A run recorded with `toPlaybook()` keeps the upload as a variable, so the replay takes a different file:
 
 ```js
@@ -310,7 +325,7 @@ await browser.goto('https://github.com/trending');
 
 // Analyze page: returns markdown and visible numbered elements
 const { markdown, elements } = await browser.analyze();
-console.log(markdown.slice(0, 300));
+console.log((markdown ?? '').slice(0, 300));
 
 // Interact using numbered element IDs:
 const firstRepo = elements.find((el) => el.tag === 'a' && el.href?.includes('/stargazers'));
@@ -422,34 +437,35 @@ const oya = new Oya({
 
 ### Browser Instance Methods (`browser.*`)
 
-| Method                              | Returns                                      | Description                                              |
-| :---------------------------------- | :------------------------------------------- | :------------------------------------------------------- |
-| `goto(url)`                         | `Promise<void>`                              | Navigate to URL (with optional auto-CAPTCHA)             |
-| `ask(prompt, { data?, secrets? }?)` | `Promise<string>`                            | Natural-language AI driving using key's configured model |
-| `analyze()`                         | `Promise<Analysis>`                          | Returns markdown representation and numbered elements    |
-| `elements()`                        | `Promise<Element[]>`                         | Returns only visible interactable elements               |
-| `click(elementId)`                  | `Promise<void>`                              | Click element by numeric ID from `analyze()`             |
-| `type(elementId, text)`             | `Promise<{ suggestions_visible?: boolean }>` | Type text into specified element                         |
-| `pressKey(key)`                     | `Promise<void>`                              | Dispatch keyboard key event (e.g. `'Enter'`)             |
-| `scroll(dir, amount?, at?)`         | `Promise<void>`                              | Scroll `'up' \| 'down' \| 'top' \| 'bottom'`             |
-| `waitFor(selector, timeout?)`       | `Promise<void>`                              | Wait for DOM selector                                    |
-| `screenshot()`                      | `Promise<string>`                            | Capture page as base64 image data URL                    |
-| `url()`                             | `Promise<string>`                            | Current active tab URL                                   |
-| `tabs()`                            | `Promise<Tab[]>`                             | List open tabs                                           |
-| `openTab(url?)`                     | `Promise<string>`                            | Open a new tab                                           |
-| `switchTab(tabId)`                  | `Promise<void>`                              | Switch active tab                                        |
-| `closeTab(tabId)`                   | `Promise<void>`                              | Close target tab                                         |
-| `solveCaptcha()`                    | `Promise<CaptchaResult>`                     | Detect and solve on-screen CAPTCHA                       |
-| `completeMfa()`                     | `Promise<MfaResult>`                         | Resolve TOTP/SMS MFA or return `liveViewUrl`             |
-| `liveViewUrl()`                     | `string`                                     | Dashboard link for this browser                          |
-| `liveStreamUrl()`                   | `Promise<string>`                            | SSE frame stream URL with a single-use ticket            |
-| `shareUrl(options?)`                | `Promise<{ url, id, expiresAt }>`            | Expiring browser share link; optional control access     |
-| `revokeShare(id)`                   | `Promise<void>`                              | Revoke a share link                                      |
-| `submit(task, options?)`            | `Promise<Run>`                               | Background prompt or playbook with callbacks             |
-| `toPlaybook(name)`                  | `Promise<Playbook>`                          | Save the latest agent flow and export Playwright code    |
-| `play(name, data?, { autoHeal? }?)` | `Promise<PlayResult>`                        | Replay a saved flow                                      |
-| `status()`                          | `Promise<BrowserDetail>`                     | Instance metrics, health, and recent activity log        |
-| `stop()`                            | `Promise<StopResult>`                        | Tear down sandbox and release CDP session                |
+| Method                                          | Returns                                      | Description                                              |
+| :---------------------------------------------- | :------------------------------------------- | :------------------------------------------------------- |
+| `goto(url)`                                     | `Promise<void>`                              | Navigate to URL (with optional auto-CAPTCHA)             |
+| `ask(prompt, { data?, secrets? }?)`             | `Promise<string>`                            | Natural-language AI driving using key's configured model |
+| `extract(prompt, schema, { data?, secrets? }?)` | `Promise<T>`                                 | The same, answered as data in the shape of a JSON schema |
+| `analyze()`                                     | `Promise<Analysis>`                          | Returns markdown representation and numbered elements    |
+| `elements()`                                    | `Promise<Element[]>`                         | Returns only visible interactable elements               |
+| `click(elementId)`                              | `Promise<void>`                              | Click element by numeric ID from `analyze()`             |
+| `type(elementId, text)`                         | `Promise<{ suggestions_visible?: boolean }>` | Type text into specified element                         |
+| `pressKey(key)`                                 | `Promise<void>`                              | Dispatch keyboard key event (e.g. `'Enter'`)             |
+| `scroll(dir, amount?, at?)`                     | `Promise<void>`                              | Scroll `'up' \| 'down' \| 'top' \| 'bottom'`             |
+| `waitFor(selector, timeout?)`                   | `Promise<void>`                              | Wait for DOM selector                                    |
+| `screenshot()`                                  | `Promise<string>`                            | Capture page as base64 image data URL                    |
+| `url()`                                         | `Promise<string>`                            | Current active tab URL                                   |
+| `tabs()`                                        | `Promise<Tab[]>`                             | List open tabs                                           |
+| `openTab(url?)`                                 | `Promise<string>`                            | Open a new tab                                           |
+| `switchTab(tabId)`                              | `Promise<void>`                              | Switch active tab                                        |
+| `closeTab(tabId)`                               | `Promise<void>`                              | Close target tab                                         |
+| `solveCaptcha()`                                | `Promise<CaptchaResult>`                     | Detect and solve on-screen CAPTCHA                       |
+| `completeMfa()`                                 | `Promise<MfaResult>`                         | Resolve TOTP/SMS MFA or return `liveViewUrl`             |
+| `liveViewUrl()`                                 | `string`                                     | Dashboard link for this browser                          |
+| `liveStreamUrl()`                               | `Promise<string>`                            | SSE frame stream URL with a single-use ticket            |
+| `shareUrl(options?)`                            | `Promise<{ url, id, expiresAt }>`            | Expiring browser share link; optional control access     |
+| `revokeShare(id)`                               | `Promise<void>`                              | Revoke a share link                                      |
+| `submit(task, options?)`                        | `Promise<Run>`                               | Background prompt or playbook with callbacks             |
+| `toPlaybook(name)`                              | `Promise<Playbook>`                          | Save the latest agent flow and export Playwright code    |
+| `play(name, data?, { autoHeal? }?)`             | `Promise<PlayResult>`                        | Replay a saved flow                                      |
+| `status()`                                      | `Promise<BrowserDetail>`                     | Instance metrics, health, and recent activity log        |
+| `stop()`                                        | `Promise<StopResult>`                        | Tear down sandbox and release CDP session                |
 
 ### Profile and persona management (`oya.profiles`, `oya.personas`)
 
@@ -468,10 +484,10 @@ const oya = new Oya({
 | `remove(id)`                                        | Delete persona and associated cookie jar                          |
 | `setMfa(id, config)`                                | Store TOTP secret (sealed at rest with AES-256-GCM)               |
 | `clearMfa(id)`                                      | Remove MFA secret from persona                                    |
-| `cookies(id, format?)` | Export the persona's logins; `'playwright'` fits `addCookies()` |
-| `importCookies(id, cookies)` | Merge cookies into the jar (from a file, a script, anywhere) |
-| `copyCookies(from, to)` | Copy one persona's logins into another |
-| `clearCookies(id)` | Forget every cookie: signs the persona out everywhere |
+| `cookies(id, format?)`                              | Export the persona's logins; `'playwright'` fits `addCookies()`   |
+| `importCookies(id, cookies)`                        | Merge cookies into the jar (from a file, a script, anywhere)      |
+| `copyCookies(from, to)`                             | Copy one persona's logins into another                            |
+| `clearCookies(id)`                                  | Forget every cookie: signs the persona out everywhere             |
 
 ### Proxies (`oya.proxies`)
 

package/dist/index.cjs

@@ -30,6 +30,47 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/constants.ts
+var DEFAULT_BASE_URL = "https://oyabrowser.com";
+var DEFAULT_TIMEOUT_MS = 6e4;
+var START_TIMEOUT_MS = 12e4;
+var READY_TIMEOUT_MS = 12e4;
+var READY_POLL_MS = 2e3;
+var NAVIGATE_TIMEOUT_MS = 12e4;
+var CHALLENGE_TIMEOUT_MS = 18e4;
+var AGENT_TIMEOUT_MS = 6e5;
+var PLAYBOOK_TIMEOUT_MS = 12e4;
+var STOP_TIMEOUT_MS = 6e4;
+var WAIT_FOR_DEFAULT_MS = 3e4;
+var WAIT_FOR_GRACE_MS = 5e3;
+var AIMED_SCROLL_AMOUNT = 500;
+var RUN_POLL_MS = 2e3;
+var MAX_RUN_POLL_ERRORS = 5;
+var BYTES_PER_MB = 1048576;
+var MAX_FILE_MB = 10;
+var BASE64_CHUNK_BYTES = 8192;
+var MS_PER_SECOND = 1e3;
+var LATIN1_MAX = 255;
+var SPACE = 32;
+var TAB = 9;
+var DEL = 127;
+var HEX = 16;
+var CODE_POINT_DIGITS = 4;
+var Status = {
+  /** The caller passed something unusable, such as a non-numeric element id. */
+  BAD_REQUEST: 400,
+  /** The server does not know that session. */
+  NOT_FOUND: 404,
+  /** The browser is in a state that needs attention first. */
+  CONFLICT: 409,
+  /** A browser command ran and failed. */
+  UNPROCESSABLE: 422,
+  /** A run failed without saying why. */
+  SERVER_ERROR: 500,
+  /** A browser did not come up in time. */
+  GATEWAY_TIMEOUT: 504
+};
+
 // src/errors.ts
 var OyaError = class extends Error {
   /** The HTTP status, or the SDK's own status for errors it raises itself. */
@@ -44,6 +85,10 @@ var OyaError = class extends Error {
     this.body = body;
   }
 };
+function refusal(message, field, suggestion) {
+  const body = { error: message, code: "invalid_request", field, ...suggestion ? { suggestion } : {} };
+  return new OyaError(message, Status.BAD_REQUEST, body);
+}
 
 // src/cli-config.ts
 var node = () => globalThis.process;
@@ -67,58 +112,26 @@ function savedConfig() {
   }
 }
 
-// src/constants.ts
-var DEFAULT_BASE_URL = "https://oyabrowser.com";
-var DEFAULT_TIMEOUT_MS = 6e4;
-var START_TIMEOUT_MS = 12e4;
-var READY_TIMEOUT_MS = 12e4;
-var READY_POLL_MS = 2e3;
-var NAVIGATE_TIMEOUT_MS = 12e4;
-var CHALLENGE_TIMEOUT_MS = 18e4;
-var AGENT_TIMEOUT_MS = 6e5;
-var PLAYBOOK_TIMEOUT_MS = 12e4;
-var STOP_TIMEOUT_MS = 6e4;
-var WAIT_FOR_DEFAULT_MS = 3e4;
-var WAIT_FOR_GRACE_MS = 5e3;
-var AIMED_SCROLL_AMOUNT = 500;
-var RUN_POLL_MS = 2e3;
-var MAX_RUN_POLL_ERRORS = 5;
-var BYTES_PER_MB = 1048576;
-var MAX_FILE_MB = 10;
-var BASE64_CHUNK_BYTES = 8192;
-var MS_PER_SECOND = 1e3;
-var Status = {
-  /** The caller passed something unusable, such as a non-numeric element id. */
-  BAD_REQUEST: 400,
-  /** The server does not know that session. */
-  NOT_FOUND: 404,
-  /** The browser is in a state that needs attention first. */
-  CONFLICT: 409,
-  /** A browser command ran and failed. */
-  UNPROCESSABLE: 422,
-  /** A run failed without saying why. */
-  SERVER_ERROR: 500,
-  /** A browser did not come up in time. */
-  GATEWAY_TIMEOUT: 504
-};
-
 // src/client.ts
+var OPTIONS_ORIGIN = { apiKeyFrom: "the apiKey option", baseUrlFrom: "the baseUrl option", savedKey: false };
 var Http = class {
-  /** Stores where to call, with which key, how long to wait and which fetch to use. */
-  constructor(baseUrl, apiKey, timeoutMs, fetchImpl) {
+  /** Stores where to call, with which key, how long to wait, which fetch to use, and where the key and address came from. */
+  constructor(baseUrl, apiKey, timeoutMs, fetchImpl, origin = OPTIONS_ORIGIN) {
     this.baseUrl = baseUrl;
     this.apiKey = apiKey;
     this.timeoutMs = timeoutMs;
     this.fetchImpl = fetchImpl;
+    this.origin = origin;
   }
   baseUrl;
   apiKey;
   timeoutMs;
   fetchImpl;
+  origin;
   /** Sends one request and returns the parsed answer, or throws an OyaError when it failed. */
   async request(method, path, body, timeoutMs = this.timeoutMs, headers = {}) {
     const res = await this.send(`${this.baseUrl}${path}`, this.init(method, body, timeoutMs, headers), timeoutMs);
-    return readAnswer(res, `${method} ${path}`, this.baseUrl);
+    return readAnswer(res, `${method} ${path}`, this);
   }
   /** The fetch options for one call, with this client's key on them. */
   init(method, body, timeoutMs, headers) {
@@ -133,23 +146,34 @@ var Http = class {
     try {
       return await this.fetchImpl(url, init);
     } catch (err) {
-      throw new OyaError(unreachable(this.baseUrl, timeoutMs, err), 0, { error: String(err?.message) });
+      throw noAnswer(this, timeoutMs, err);
     }
   }
 };
-function unreachable(baseUrl, timeoutMs, err) {
-  const cause = err?.name === "TimeoutError" || /abort/i.test(String(err?.message));
-  if (cause) return `No answer from ${baseUrl} within ${timeoutMs}ms. Is it reachable, and is the call this slow?`;
-  return `Could not reach ${baseUrl}. Is the server running, and is OYA_BASE_URL right?`;
+var timedOut = (err) => err?.name === "TimeoutError" || /abort/i.test(String(err?.message));
+function causeOf(err) {
+  const cause = err?.cause;
+  return cause?.code ?? cause?.errors?.[0]?.code;
+}
+function noAnswer(http, timeoutMs, err) {
+  const code = timedOut(err) ? "timeout" : "unreachable";
+  const body = { error: String(err?.message), code, ...causeOf(err) ? { cause: causeOf(err) } : {} };
+  return new OyaError(unreachable(http, timeoutMs, code), 0, body);
+}
+function unreachable({ baseUrl, origin }, timeoutMs, code) {
+  if (code === "timeout")
+    return `No answer from ${baseUrl} within ${timeoutMs}ms. Is it reachable, and is the call this slow?`;
+  if (origin.baseUrlFrom === "default") return `Could not reach ${baseUrl}. Check your connection.`;
+  return `Could not reach ${baseUrl}. Is the server running, and is ${origin.baseUrlFrom} right?`;
 }
 function requestInit(method, body, timeoutMs, headers) {
   const json = body === void 0 ? {} : { "Content-Type": "application/json" };
   const payload = body === void 0 ? void 0 : JSON.stringify(body);
   return { method, headers: { ...headers, ...json }, body: payload, signal: AbortSignal.timeout(timeoutMs) };
 }
-async function readAnswer(res, call2, baseUrl) {
+async function readAnswer(res, call2, http) {
   const payload = parseBody(await res.text());
-  if (!res.ok) throw failure(call2, res.status, payload, baseUrl);
+  if (!res.ok) throw failure(call2, res.status, payload, http);
   return payload;
 }
 function parseBody(text) {
@@ -159,22 +183,74 @@ function parseBody(text) {
     return text;
   }
 }
-function failure(call2, status, payload, baseUrl) {
-  let message = payload?.error || `${call2} failed (${status})`;
-  if (message === "Invalid API key") {
-    message += ` for ${baseUrl}. Check OYA_API_KEY: a value exported in your shell beats .env.`;
-  }
-  return new OyaError(message, status, payload);
+function failure(call2, status, payload, http) {
+  const message = payload?.error || `${call2} failed (${status})`;
+  return new OyaError(message === "Invalid API key" ? invalidKey(http) : message, status, payload);
+}
+function invalidKey({ baseUrl, origin }) {
+  const overrides = origin.apiKeyFrom === "OYA_API_KEY" && origin.savedKey;
+  const rest = overrides ? ", which overrides the one saved in ~/.oya/config.json" : "";
+  return `Invalid API key for ${baseUrl}. The key came from ${origin.apiKeyFrom}${rest}.`;
 }
 var env = (name) => globalThis.process?.env?.[name];
+function firstOf(option, name, saved, optionName) {
+  if (option) return { value: option, from: `the ${optionName} option` };
+  if (env(name)) return { value: env(name), from: name };
+  return { value: saved, from: "~/.oya/config.json" };
+}
+function addressOf(options, saved) {
+  const found = firstOf(options.baseUrl, "OYA_BASE_URL", saved, "baseUrl");
+  return found.value ? found : { value: DEFAULT_BASE_URL, from: "default" };
+}
+function keyOf(options, saved) {
+  const found = firstOf(options.apiKey, "OYA_API_KEY", saved, "apiKey");
+  if (!found.value) throw new Error("No API key. Pass { apiKey }, set OYA_API_KEY, or run `npx @oya-ai/cli login`.");
+  return { ...found, value: headerSafe(found.value, "apiKey", "Copy the key again.") };
+}
 function createHttp(options) {
   const saved = savedConfig();
-  const apiKey = options.apiKey || env("OYA_API_KEY") || saved.apiKey;
-  if (!apiKey) throw new Error("No API key. Pass { apiKey }, set OYA_API_KEY, or run `npx @oya-ai/cli login`.");
-  const baseUrl = (options.baseUrl || env("OYA_BASE_URL") || saved.baseUrl || DEFAULT_BASE_URL).replace(/\/+$/, "");
+  const key = keyOf(options, saved.apiKey);
+  const address = addressOf(options, saved.baseUrl);
   const fetchImpl = options.fetch || globalThis.fetch;
   if (!fetchImpl) throw new Error("No fetch available, pass { fetch } or use Node 18+.");
-  return new Http(baseUrl, apiKey, options.timeoutMs ?? DEFAULT_TIMEOUT_MS, fetchImpl.bind(globalThis));
+  const origin = { apiKeyFrom: key.from, baseUrlFrom: address.from, savedKey: !!saved.apiKey };
+  const timeout = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  return new Http(webAddress(address), key.value, timeout, fetchImpl.bind(globalThis), origin);
+}
+var LOCAL_HOST = /^(localhost|127\.)/i;
+function webAddress({ value, from }) {
+  const url = value.trim().replace(/\/+$/, "");
+  if (/^https?:\/\//i.test(url)) return url;
+  const name = from.startsWith("the ") ? "baseUrl" : from === "OYA_BASE_URL" ? from : `baseUrl in ${from}`;
+  const suggestion = suggestionFor(url);
+  const tryIt = suggestion ? ` Try ${suggestion}.` : "";
+  throw refusal(`${name} must start with http:// or https://, not "${url}".${tryIt}`, "baseUrl", suggestion);
+}
+function suggestionFor(url) {
+  if (/^[a-z][a-z0-9+.-]*:/i.test(url) && !/^[^:/]+:\d+(\/|$)/.test(url)) return void 0;
+  return `${LOCAL_HOST.test(url) ? "http" : "https"}://${url}`;
+}
+function notInAHeader(ch) {
+  const code = ch.codePointAt(0);
+  return code < SPACE && code !== TAB || code === DEL || code > LATIN1_MAX;
+}
+function headerSafe(value, field, ending) {
+  const trimmed = value.trim();
+  const chars = Array.from(trimmed);
+  const at = chars.findIndex(notInAHeader);
+  if (at < 0) return trimmed;
+  const leading = Array.from(value).length - Array.from(value.trimStart()).length;
+  const where = `position ${leading + at + 1} (${codePoint(chars[at])})`;
+  throw refusal(`${field} has a character HTTP headers cannot carry at ${where}. ${ending}`, field);
+}
+var codePoint = (ch) => `U+${ch.codePointAt(0).toString(HEX).toUpperCase().padStart(CODE_POINT_DIGITS, "0")}`;
+var shown = (value) => typeof value === "string" ? JSON.stringify(value) : String(value);
+function segment(value, field = "id") {
+  if (typeof value !== "string" || !value)
+    throw refusal(`${field} must be a non-empty string, not ${shown(value)}`, field);
+  if (value.includes("/") || value === "." || value === "..")
+    throw refusal(`${field} must be a single path segment (no "/" and not "." or ".."), not ${shown(value)}`, field);
+  return encodeURIComponent(value);
 }
 
 // src/run-watch.ts
@@ -396,6 +472,17 @@ var Browser = class {
     const path = `/api/browsers/${this.id}/chat`;
     return agentAnswer(await this.http.request("POST", path, body, AGENT_TIMEOUT_MS)).text;
   }
+  /**
+   * `ask()` for data: the agent does the task and answers in the shape of `schema`
+   * (a JSON schema), instead of in words. Throws when the agent reports it could not.
+   */
+  async extract(prompt, schema, values = {}) {
+    const body = { messages: [{ role: "user", content: prompt }], ...values, schema };
+    const path = `/api/browsers/${this.id}/chat`;
+    const res = agentAnswer(await this.http.request("POST", path, body, AGENT_TIMEOUT_MS));
+    if (res.failed || res.data === void 0) throw new OyaError(res.text, Status.UNPROCESSABLE, res);
+    return res.data;
+  }
   /**
    * 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
@@ -413,7 +500,7 @@ var Browser = class {
    * Play `'<name>:draft'` to try a draft before promoting it.
    */
   async play(name, data = {}, { autoHeal = true } = {}) {
-    const path = `/api/browsers/${this.id}/playbooks/${encodeURIComponent(name)}/play`;
+    const path = `/api/browsers/${this.id}/playbooks/${segment(name, "name")}/play`;
     return agentAnswer(
       await this.http.request("POST", path, { variables: data, autoHeal }, AGENT_TIMEOUT_MS)
     );
@@ -464,7 +551,7 @@ var Browser = class {
   }
   /** Revoke a link from `shareUrl()` before it expires, by the id it returned. */
   async revokeShare(id) {
-    await this.http.request("DELETE", `/api/control/credentials/${encodeURIComponent(id)}`);
+    await this.http.request("DELETE", `/api/control/credentials/${segment(id)}`);
   }
   /** Counters, health and the last 50 things this browser did. */
   status() {
@@ -520,8 +607,9 @@ function startBody(options) {
   const { profile, persona, provider, wsUrl, name, queueMs, priority, budgetUsd, governed, policy } = options;
   return { profile: profile || persona, provider, wsUrl, name, queueMs, priority, budgetUsd, governed, policy };
 }
+var idempotencyKeyOf = ({ idempotencyKey }) => idempotencyKey ? headerSafe(idempotencyKey, "idempotencyKey", 'Use letters, digits, "-" and "_".') : globalThis.crypto.randomUUID();
 async function start(http, wait, options) {
-  const headers = { "Idempotency-Key": options.idempotencyKey || globalThis.crypto.randomUUID() };
+  const headers = { "Idempotency-Key": idempotencyKeyOf(options) };
   const path = "/api/browsers/start";
   const started = await http().request("POST", path, startBody(options), START_TIMEOUT_MS, headers);
   if (started.status === "starting") {
@@ -530,7 +618,7 @@ async function start(http, wait, options) {
   }
   return new Browser(http(), started, options.captcha === "auto");
 }
-var fetchBrowser = (http, id) => http().request("GET", `/api/browsers/${encodeURIComponent(id)}`);
+var fetchBrowser = (http, id) => http().request("GET", `/api/browsers/${segment(id)}`);
 async function reattach(http, id) {
   const found = await fetchBrowser(http, id);
   return new Browser(http(), asStarted(found), false);
@@ -542,69 +630,79 @@ function asStarted(found) {
 var stopBrowsers = (http, ids) => http().request("POST", "/api/browsers/stop", ids === "all" ? { all: true } : { ids }, START_TIMEOUT_MS);
 var browserApi = (http, wait) => ({
   /** Start a browser and wait until it can take commands. */
-  start: (options = {}) => start(http, wait, options),
+  start: async (options = {}) => start(http, wait, options),
   /** Reattach to a browser that is already running. */
-  get: (id) => reattach(http, id),
+  get: async (id) => reattach(http, id),
   /** Every browser on this key. */
-  list: () => http().request("GET", "/api/browsers"),
+  list: async () => http().request("GET", "/api/browsers"),
   /** Stop some (`ids`) or every browser on this key. Each reports separately. */
-  stop: (ids) => stopBrowsers(http, ids),
+  stop: async (ids) => stopBrowsers(http, ids),
   /** Stop every browser on this key; returns how many stopped. */
   stopAll: async () => (await stopBrowsers(http, "all")).stopped
 });
 
 // src/api/control.ts
-var session = (id, action = "") => `/api/control/sessions/${encodeURIComponent(id)}${action}`;
-var item = (kind, id) => `/api/control/${kind}/${encodeURIComponent(id)}`;
+var session = (id, action = "") => `/api/control/sessions/${segment(id)}${action}`;
+var item = (kind, id) => `/api/control/${kind}/${segment(id)}`;
 var sessionCalls = (http) => ({
   /** Settings, sessions and recent events at a glance. */
-  overview: () => http().request("GET", "/api/control"),
+  overview: async () => http().request("GET", "/api/control"),
   /** Every session, including disconnected and cleanup-pending ones. */
-  sessions: () => http().request("GET", "/api/control/sessions"),
+  sessions: async () => http().request("GET", "/api/control/sessions"),
   /** One session. */
-  session: (id) => http().request("GET", session(id)),
+  session: async (id) => http().request("GET", session(id)),
   /** Update limits, rate cards and retention. */
-  settings: (changes) => http().request("PATCH", "/api/control/project", changes)
+  settings: async (changes) => http().request("PATCH", "/api/control/project", changes)
 });
 var lifecycleCalls = (http) => ({
-  /** Cancel queued or provisioning work. */
-  cancel: (id) => http().request("POST", session(id, "/cancel"), {}),
+  /** Stop a session in any state; answers its final state. */
+  cancel: async (id) => http().request("POST", session(id, "/cancel"), {}),
   /** Stop a session; `force` stops despite a profile-save error, or reconciles. */
-  stop: (id, force = false) => http().request("POST", session(id, "/stop"), { force }),
+  stop: async (id, force = false) => http().request("POST", session(id, "/stop"), { force }),
   /** Acquire or release human control, or acknowledge the agent's resume. */
-  takeover: (id, action) => http().request("POST", session(id, "/control"), { action }),
+  takeover: async (id, action) => http().request("POST", session(id, "/control"), { action }),
   /** Send one input as the human holding the control lease. */
-  input: (id, action, params) => http().request("POST", session(id, "/input"), { action, params })
+  input: async (id, action, params) => http().request("POST", session(id, "/input"), { action, params })
 });
+function recoverBody(options) {
+  const { replace = false, wsUrl } = typeof options === "boolean" ? { replace: options } : options ?? {};
+  if (wsUrl && !replace)
+    throw refusal("wsUrl is only used with replace: true; recovering in place keeps the endpoint it had.", "wsUrl");
+  return wsUrl ? { replace, wsUrl } : { replace };
+}
 var recoveryCalls = (http) => ({
-  /** Explicitly recover a session, or replace it with a fresh one. */
-  recover: (id, replace = false) => http().request("POST", session(id, "/recover"), { replace }),
+  /**
+   * Explicitly recover a session, or replace it with a fresh one. A cdp
+   * session's replacement needs the Chrome it runs on: `{ replace: true, wsUrl }`.
+   * `recover(id, true)` still means replace.
+   */
+  recover: async (id, options = {}) => http().request("POST", session(id, "/recover"), recoverBody(options)),
   /** A single-use ticket for the live stream. */
-  ticket: (id) => http().request("POST", session(id, "/ticket"), {}),
+  ticket: async (id) => http().request("POST", session(id, "/ticket"), {}),
   /** Durable lifecycle events after a cursor. */
-  events: (after = 0) => http().request("GET", `/api/control/events?after=${after}`)
+  events: async (after = 0) => http().request("GET", `/api/control/events?after=${after}`)
 });
 var credentialCalls = (http) => ({
   /** Mint a service credential. Its token is returned this once. */
-  createCredential: (options) => http().request("POST", "/api/control/credentials", options),
+  createCredential: async (options) => http().request("POST", "/api/control/credentials", options),
   /** Revoke a service credential. */
-  revokeCredential: (id) => http().request("DELETE", item("credentials", id))
+  revokeCredential: async (id) => http().request("DELETE", item("credentials", id))
 });
 var memberCalls = (http) => ({
   /** The owner and every member. */
-  members: () => http().request("GET", "/api/control/members"),
+  members: async () => http().request("GET", "/api/control/members"),
   /** An invitation code for a new member. */
-  inviteMember: (role = "operator") => http().request("POST", "/api/control/members/invite", { role }),
+  inviteMember: async (role = "operator") => http().request("POST", "/api/control/members/invite", { role }),
   /** Remove a member. */
-  removeMember: (userId) => http().request("DELETE", item("members", userId))
+  removeMember: async (userId) => http().request("DELETE", item("members", userId))
 });
 var webhookCalls = (http) => ({
   /** Register a webhook; `types` limits which events it receives. */
-  createWebhook: (url, types = []) => http().request("POST", "/api/control/webhooks", { url, types }),
+  createWebhook: async (url, types = []) => http().request("POST", "/api/control/webhooks", { url, types }),
   /** Disable a webhook. */
-  removeWebhook: (id) => http().request("DELETE", item("webhooks", id)),
+  removeWebhook: async (id) => http().request("DELETE", item("webhooks", id)),
   /** Send a delivery again. */
-  replayDelivery: (id) => http().request("POST", `${item("deliveries", id)}/replay`, {})
+  replayDelivery: async (id) => http().request("POST", `${item("deliveries", id)}/replay`, {})
 });
 var controlApi = (http) => ({
   ...sessionCalls(http),
@@ -616,7 +714,7 @@ var controlApi = (http) => ({
 });
 
 // src/api/playbooks.ts
-var playbook = (name) => `/api/playbooks/${encodeURIComponent(name)}`;
+var playbook = (name) => `/api/playbooks/${segment(name, "name")}`;
 var playbookApi = (http) => ({
   /** Every saved playbook, with any draft waiting on it. */
   list: async () => (await http().request("GET", "/api/playbooks")).playbooks,
@@ -625,7 +723,7 @@ var playbookApi = (http) => ({
     await http().request("DELETE", playbook(name));
   },
   /** Replace a playbook with the draft a healed replay saved. Try it first with `browser.play('<name>:draft')`. */
-  promote: (name) => http().request("POST", `${playbook(name)}/promote`, {})
+  promote: async (name) => http().request("POST", `${playbook(name)}/promote`, {})
 });
 
 // src/api/proxies.ts
@@ -633,10 +731,10 @@ var proxyApi = (http) => ({
   /** Every proxy this key can use, shared ones included. */
   list: async () => (await http().request("GET", "/api/proxies")).proxies,
   /** Add a proxy. Its credentials are never read back. */
-  create: (proxy) => http().request("POST", "/api/proxies", proxy),
+  create: async (proxy) => http().request("POST", "/api/proxies", proxy),
   /** Remove one of this key's proxies. */
   remove: async (id) => {
-    await http().request("DELETE", `/api/proxies/${encodeURIComponent(id)}`);
+    await http().request("DELETE", `/api/proxies/${segment(id)}`);
   },
   /** Dial each proxy and learn its real exit IP. Failing ones cool down and are skipped. */
   check: async () => (await http().request("POST", "/api/proxies/check", {})).results
@@ -647,35 +745,38 @@ var identityCalls = (http) => ({
   /** Every persona on this key. */
   list: async () => (await http().request("GET", "/api/personas")).personas,
   /** One persona. */
-  get: (id) => http().request("GET", `/api/personas/${id}`),
+  get: async (id) => http().request("GET", `/api/personas/${segment(id)}`),
   /**
    * Create an identity. The device, platform, timezone, locale, is chosen
    * here and fixed for its life; `preview()` shows what a choice produces.
    */
-  create: (options = {}) => http().request("POST", "/api/personas", options),
+  create: async (options = {}) => http().request("POST", "/api/personas", options),
   /** Name, concurrency cap and proxy hint. Never the device, clone for that. */
-  update: (id, changes) => http().request("PUT", `/api/personas/${id}`, changes),
+  update: async (id, changes) => http().request("PUT", `/api/personas/${segment(id)}`, changes),
   /** A new persona of the same kind of device: same choices, fresh identity, empty jar. */
-  clone: (id, options = {}) => http().request("POST", `/api/personas/${id}/clone`, options)
+  clone: async (id, options = {}) => http().request("POST", `/api/personas/${segment(id)}/clone`, options)
 });
 var deviceCalls = (http) => ({
   /** The fingerprint these choices would produce. Persists nothing. */
   preview: async (prefs = {}) => (await http().request("POST", "/api/personas/preview", { prefs })).fingerprint,
   /** Platforms, and the timezones and locales each may coherently claim. */
-  options: () => http().request("GET", "/api/personas/options"),
+  options: async () => http().request("GET", "/api/personas/options"),
   /** Pin the persona to one of your proxies, or `null` to let assignment happen at connect. */
-  pinProxy: (id, proxyId) => http().request("PUT", `/api/personas/${id}/proxy`, { proxyId }),
+  pinProxy: async (id, proxyId) => http().request("PUT", `/api/personas/${segment(id)}/proxy`, { proxyId }),
   /** Delete a persona. */
   remove: async (id) => {
-    await http().request("DELETE", `/api/personas/${id}`);
+    await http().request("DELETE", `/api/personas/${segment(id)}`);
   }
 });
 var mfaCalls = (http) => ({
   /** Store the second factor for this identity. Sealed at rest, never read back. */
-  setMfa: (id, config) => http().request("PUT", `/api/personas/${id}/mfa`, config),
+  setMfa: async (id, config) => http().request("PUT", `/api/personas/${segment(id)}/mfa`, config),
   /** Remove the persona-wide factor, or the one filed against `domain`. */
   clearMfa: async (id, domain) => {
-    await http().request("DELETE", `/api/personas/${id}/mfa${domain ? `?domain=${encodeURIComponent(domain)}` : ""}`);
+    await http().request(
+      "DELETE",
+      `/api/personas/${segment(id)}/mfa${domain ? `?domain=${encodeURIComponent(domain)}` : ""}`
+    );
   }
 });
 var loginCalls = (http) => ({
@@ -686,20 +787,20 @@ var loginCalls = (http) => ({
    * 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, config) => http().request("PUT", `/api/personas/${id}/credentials`, config),
+  setCredentials: async (id, config) => http().request("PUT", `/api/personas/${segment(id)}/credentials`, config),
   /** Which sites this identity can sign in to. Usernames only. */
-  credentials: (id) => http().request("GET", `/api/personas/${id}/credentials`),
+  credentials: async (id) => http().request("GET", `/api/personas/${segment(id)}/credentials`),
   /** Remove the login stored for one site. */
   clearCredentials: async (id, domain) => {
-    await http().request("DELETE", `/api/personas/${id}/credentials?domain=${encodeURIComponent(domain)}`);
+    await http().request("DELETE", `/api/personas/${segment(id)}/credentials?domain=${encodeURIComponent(domain)}`);
   }
 });
-var jarPath = (id) => `/api/pool/cookies?persona=${encodeURIComponent(id)}`;
+var jarPath = (id) => `/api/pool/cookies?persona=${segment(id)}`;
 var jarCalls = (http) => ({
   /** Every cookie in the jar; `format: 'playwright'` is ready for `context.addCookies()`. */
-  cookies: async (id, format = "json") => (await http().request("GET", `${jarPath(id)}&format=${format}`)).cookies,
+  cookies: async (id, format = "json") => (await http().request("GET", `${jarPath(id)}&format=${encodeURIComponent(format)}`)).cookies,
   /** Merge cookies into the jar. The persona's browsers pick them up on their next visit to each site. */
-  importCookies: (id, list) => http().request("PUT", jarPath(id), { cookies: list })
+  importCookies: async (id, list) => http().request("PUT", jarPath(id), { cookies: list })
 });
 var cookieCalls = (http) => ({
   ...jarCalls(http),