@oya-ai/browser 1.0.97 → 1.0.101

package/dist/index.cjs

@@ -30,10 +30,13 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 
-// src/types.ts
+// src/errors.ts
 var OyaError = class extends Error {
+  /** The HTTP status, or the SDK's own status for errors it raises itself. */
   status;
+  /** The server's response body, parsed when it was JSON. */
   body;
+  /** Records the message, status and body. */
   constructor(message, status, body) {
     super(message);
     this.name = "OyaError";
@@ -42,8 +45,44 @@ var OyaError = class extends Error {
   }
 };
 
+// src/constants.ts
+var DEFAULT_BASE_URL = "https://browser.getoya.ai";
+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 Http = class {
+  /** Stores where to call, with which key, how long to wait and which fetch to use. */
   constructor(baseUrl, apiKey, timeoutMs, fetchImpl) {
     this.baseUrl = baseUrl;
     this.apiKey = apiKey;
@@ -54,36 +93,141 @@ var Http = class {
   apiKey;
   timeoutMs;
   fetchImpl;
+  /** 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.fetchImpl(`${this.baseUrl}${path}`, {
-      method,
-      headers: {
-        Authorization: `Bearer ${this.apiKey}`,
-        ...headers,
-        ...body === void 0 ? {} : { "Content-Type": "application/json" }
-      },
-      body: body === void 0 ? void 0 : JSON.stringify(body),
-      signal: AbortSignal.timeout(timeoutMs)
+    const init = requestInit(method, body, timeoutMs, { Authorization: `Bearer ${this.apiKey}`, ...headers });
+    return readAnswer(await this.fetchImpl(`${this.baseUrl}${path}`, init), `${method} ${path}`, this.baseUrl);
+  }
+};
+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) {
+  const payload = parseBody(await res.text());
+  if (!res.ok) throw failure(call2, res.status, payload, baseUrl);
+  return payload;
+}
+function parseBody(text) {
+  try {
+    return text ? JSON.parse(text) : null;
+  } catch {
+    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);
+}
+var env = (name) => globalThis.process?.env?.[name];
+function createHttp(options) {
+  const apiKey = options.apiKey || env("OYA_API_KEY");
+  if (!apiKey) {
+    throw new Error("No API key. Pass { apiKey } or set OYA_API_KEY \u2014 run `oya login` to get one.");
+  }
+  const baseUrl = (options.baseUrl || env("OYA_BASE_URL") || DEFAULT_BASE_URL).replace(/\/+$/, "");
+  const fetchImpl = options.fetch || globalThis.fetch;
+  if (!fetchImpl) throw new Error("No fetch available \u2014 pass { fetch } or use Node 18+.");
+  return new Http(baseUrl, apiKey, options.timeoutMs ?? DEFAULT_TIMEOUT_MS, fetchImpl.bind(globalThis));
+}
+
+// src/run-watch.ts
+var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+async function call(fn) {
+  try {
+    await fn();
+  } catch (err) {
+    console.error("[oya] run callback threw:", err);
+  }
+}
+async function watchRun(run, baseUrl, cb, pollMs) {
+  const watch = { run, baseUrl, cb, errors: 0 };
+  for (; ; ) {
+    const result = await step(watch);
+    if (result) return result;
+    await sleep(pollMs);
+  }
+}
+async function step(watch) {
+  const info = await poll(watch);
+  if (!info) return void 0;
+  noticeAttention(watch, info);
+  if (info.status === "succeeded") return succeed(watch.cb, info);
+  if (info.status === "failed") return fail(watch.cb, info);
+  return void 0;
+}
+async function poll(watch) {
+  try {
+    const info = await watch.run.status();
+    watch.errors = 0;
+    return info;
+  } catch (err) {
+    if (++watch.errors < MAX_RUN_POLL_ERRORS) return null;
+    return giveUp(watch.cb, err);
+  }
+}
+async function giveUp(cb, err) {
+  const failure2 = err instanceof OyaError ? err : new OyaError(String(err), 0, null);
+  await call(() => cb.onFailure?.(failure2));
+  throw failure2;
+}
+function noticeAttention(watch, info) {
+  if (info.status !== "needs_attention" || !info.attention || info.attention.id === watch.seen) return;
+  watch.seen = info.attention.id;
+  const request = {
+    ...info.attention,
+    liveViewUrl: info.attention.liveViewUrl && new URL(info.attention.liveViewUrl, watch.baseUrl).href,
+    respond: (response) => watch.run.respond(response)
+  };
+  void call(() => watch.cb.onHumanAttention?.(request));
+}
+async function succeed(cb, info) {
+  const result = info.result || {};
+  if (result.healed) await call(() => cb.onHealed?.(result));
+  await call(() => cb.onSuccess?.(result));
+  return result;
+}
+async function fail(cb, info) {
+  const failure2 = new OyaError(info.error || "Run failed", info.errorStatus ?? Status.SERVER_ERROR, info);
+  await call(() => cb.onFailure?.(failure2));
+  throw failure2;
+}
+
+// src/run.ts
+var Run = class {
+  /** Starts watching the run straight away. */
+  constructor(http, id, callbacks, pollMs = RUN_POLL_MS) {
+    this.http = http;
+    this.id = id;
+    this.done = this.watch(callbacks, pollMs);
+    this.done.catch(() => {
     });
-    const text = await res.text();
-    let payload;
-    try {
-      payload = text ? JSON.parse(text) : null;
-    } catch {
-      payload = text;
-    }
-    if (!res.ok) {
-      let message = payload?.error || `${method} ${path} failed (${res.status})`;
-      if (message === "Invalid API key") message += ` for ${this.baseUrl}. Check OYA_API_KEY: a value exported in your shell beats .env.`;
-      throw new OyaError(message, res.status, payload);
-    }
-    return payload;
+  }
+  http;
+  id;
+  /** Settles with the result when the run succeeds, or rejects when it fails. */
+  done;
+  /** The run's current state. */
+  status() {
+    return this.http.request("GET", `/api/runs/${encodeURIComponent(this.id)}`);
+  }
+  /** Answer the open attention request: `'done'` after handling it by hand, or your reply to the agent. */
+  async respond(response = "done") {
+    await this.http.request("POST", `/api/runs/${encodeURIComponent(this.id)}/respond`, { response });
+  }
+  /** Polls until the run ends, firing callbacks on the way. */
+  watch(cb, pollMs) {
+    return watchRun(this, this.http.baseUrl, cb, pollMs);
   }
 };
 
 // src/browser.ts
-var NAVIGATE_TIMEOUT_MS = 12e4;
 var Browser = class {
+  /** Wraps a started browser; `autoCaptcha` solves CAPTCHAs after every `goto()`. */
   constructor(http, info, autoCaptcha) {
     this.http = http;
     this.autoCaptcha = autoCaptcha;
@@ -94,51 +238,52 @@ var Browser = class {
   }
   http;
   autoCaptcha;
+  /** The browser's id. */
   id;
+  /** Which provider runs it. */
   provider;
+  /** Which persona it runs as. */
   persona;
   /** Point Playwright, Puppeteer or browser-use here. */
   cdpUrl;
+  /** Runs one browser command; a command that ran and failed throws. */
   async command(action, params = {}, timeoutMs) {
-    const result = await this.http.request(
-      "POST",
-      `/api/browsers/${this.id}/command`,
-      { action, params },
-      timeoutMs
-    );
-    if (result.ok === false) throw new OyaError(result.error || `${action} failed`, 422, result);
+    const path = `/api/browsers/${this.id}/command`;
+    const result = await this.http.request("POST", path, { action, params }, timeoutMs);
+    if (result.ok === false) throw new OyaError(result.error || `${action} failed`, Status.UNPROCESSABLE, result);
     return result.data;
   }
+  /** Navigates, then clears any CAPTCHA when `captcha: 'auto'` was asked for. */
   async goto(url) {
     await this.command("navigate", { url }, NAVIGATE_TIMEOUT_MS);
-    if (this.autoCaptcha) {
-      const result = await this.solveCaptcha();
-      if (result.present && !result.solved && !result.invisible) throw new OyaError(result.error || "CAPTCHA needs attention. Call solveCaptcha() again or open the live view.", 409, result);
-    }
+    if (this.autoCaptcha) assertCaptchaCleared(await this.solveCaptcha());
   }
-  /** The page as markdown plus numbered elements to act on. */
-  async analyze() {
-    return this.command("analyze");
+  /**
+   * The page, written as markdown (the default), TOON or JSONL, plus its blocks and
+   * the numbered elements to act on.
+   */
+  async analyze(options = {}) {
+    return this.command("analyze", options.format ? { format: options.format } : {});
   }
   /** Only the visible elements, which is what an agent almost always wants. */
   async elements() {
     return (await this.analyze()).elements.filter((e) => e.visible);
   }
+  /** Clicks an element by its id from `analyze()`. */
   async click(elementId) {
     const id = this.elementId(elementId);
     await this.command("click", { element_id: id, selector: `[data-ac-id="${id}"]` });
   }
+  /** Types into an element by its id from `analyze()`. */
   async type(elementId, text) {
     const id = this.elementId(elementId);
     return this.command("type", { element_id: id, selector: `[data-ac-id="${id}"]`, text });
   }
+  /** A valid element id, or an OyaError saying where ids come from. */
   elementId(value) {
-    const id = Number(value);
-    if (typeof value !== "number" && typeof value !== "string" || value === "" || !Number.isInteger(id) || id < 0) {
-      throw new OyaError("Use a numeric element id from browser.analyze().", 400, null);
-    }
-    return id;
+    return toElementId(value);
   }
+  /** Presses one key, such as Enter or Escape. */
   async pressKey(key) {
     await this.command("press_key", { key });
   }
@@ -152,47 +297,49 @@ var Browser = class {
   }
   /** `at` aims the wheel at an inner scroller (a results panel, a chat pane) instead of the page. */
   async scroll(direction, amount, at) {
-    await this.command("scroll", at ? { direction, amount: amount ?? 500, ...at, smooth: false } : { direction, amount });
+    await this.command("scroll", scrollParams(direction, amount, at));
   }
-  async waitFor(selector, timeout = 3e4) {
-    await this.command("wait", { selector, timeout }, timeout + 5e3);
+  /** Waits until `selector` matches, up to `timeout` milliseconds. */
+  async waitFor(selector, timeout = WAIT_FOR_DEFAULT_MS) {
+    await this.command("wait", { selector, timeout }, timeout + WAIT_FOR_GRACE_MS);
   }
   /** A `data:image/…;base64,` URL. PNG or JPEG depending on the driver. */
   async screenshot() {
-    const data = await this.command("screenshot");
-    return data.screenshot;
+    return (await this.command("screenshot")).screenshot;
   }
+  /** The active tab's URL, or empty when there is none. */
   async url() {
-    const tabs = await this.tabs();
-    return tabs.find((t) => t.active)?.url || "";
+    return (await this.tabs()).find((t) => t.active)?.url || "";
   }
+  /** Every open tab. */
   async tabs() {
-    const data = await this.command("list_tabs");
-    return data.tabs || [];
+    return (await this.command("list_tabs")).tabs || [];
   }
+  /** Opens a tab, optionally at `url`, and returns its id. */
   async openTab(url) {
-    const data = await this.command("open_tab", { url }, NAVIGATE_TIMEOUT_MS);
-    return data.tab_id;
+    return (await this.command("open_tab", { url }, NAVIGATE_TIMEOUT_MS)).tab_id;
   }
+  /** Makes a tab the one commands act on. */
   async switchTab(tabId) {
     await this.command("switch_tab", { tab_id: tabId });
   }
+  /** Closes a tab. */
   async closeTab(tabId) {
     await this.command("close_tab", { tab_id: tabId });
   }
   /**
-  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() {
-    return this.http.request("POST", `/api/browsers/${this.id}/captcha`, {}, 18e4);
+    return this.http.request("POST", `/api/browsers/${this.id}/captcha`, {}, CHALLENGE_TIMEOUT_MS);
   }
   /**
    * Answer an MFA prompt with the persona's configured factor. When nothing can
    * answer it, `liveViewUrl` is where a person finishes by hand.
    */
   async completeMfa() {
-    const result = await this.http.request("POST", `/api/browsers/${this.id}/mfa`, {}, 18e4);
+    const result = await this.http.request("POST", `/api/browsers/${this.id}/mfa`, {}, CHALLENGE_TIMEOUT_MS);
     if (result.liveViewUrl) result.liveViewUrl = new URL(result.liveViewUrl, this.http.baseUrl).href;
     return result;
   }
@@ -203,14 +350,9 @@ var Browser = class {
    * with filters like `{{name|first}}`, so a playbook saved from the run stores no values.
    */
   async ask(prompt, { data, secrets } = {}) {
-    const res = await this.http.request(
-      "POST",
-      `/api/browsers/${this.id}/chat`,
-      { messages: [{ role: "user", content: prompt }], data, secrets },
-      6e5
-    );
-    if (res.error) throw new OyaError(res.error, res.status ?? 500, res);
-    return res.text;
+    const body = { messages: [{ role: "user", content: prompt }], data, secrets };
+    const path = `/api/browsers/${this.id}/chat`;
+    return agentAnswer(await this.http.request("POST", path, body, AGENT_TIMEOUT_MS)).text;
   }
   /**
    * Save the last `ask()` on this browser as a named playbook. Every value that was
@@ -219,7 +361,7 @@ var Browser = class {
    * swapped. `code` is the same flow as a Playwright module, to read or run yourself.
    */
   toPlaybook(name) {
-    return this.http.request("POST", `/api/browsers/${this.id}/playbooks`, { name }, 12e4);
+    return this.http.request("POST", `/api/browsers/${this.id}/playbooks`, { name }, PLAYBOOK_TIMEOUT_MS);
   }
   /**
    * Replay a playbook with no LLM in the loop. Variables left out reuse the
@@ -229,14 +371,10 @@ var Browser = class {
    * Play `'<name>:draft'` to try a draft before promoting it.
    */
   async play(name, data = {}, { autoHeal = true } = {}) {
-    const res = await this.http.request(
-      "POST",
-      `/api/browsers/${this.id}/playbooks/${encodeURIComponent(name)}/play`,
-      { variables: data, autoHeal },
-      6e5
+    const path = `/api/browsers/${this.id}/playbooks/${encodeURIComponent(name)}/play`;
+    return agentAnswer(
+      await this.http.request("POST", path, { variables: data, autoHeal }, AGENT_TIMEOUT_MS)
     );
-    if (res.error) throw new OyaError(res.error, res.status ?? 500, res);
-    return res;
   }
   /**
    * Start a prompt or playbook in the background and hear back through callbacks.
@@ -250,19 +388,11 @@ var Browser = class {
     return new Run(this.http, started.id, { onSuccess, onFailure, onHumanAttention, onHealed }, pollMs);
   }
   /**
-   * 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() {
-    return `${this.http.baseUrl}/dashboard/?browser=${encodeURIComponent(this.id)}`;
+    return consoleLink(this.http.baseUrl, this.id);
   }
   /**
    * The SSE stream of JPEG frames, for embedding in your own UI. EventSource
@@ -270,11 +400,8 @@ var Browser = class {
    * 60 seconds. Mint one per viewer — the first connection spends it.
    */
   async liveStreamUrl() {
-    const { ticket } = await this.http.request(
-      "POST",
-      `/api/control/sessions/${encodeURIComponent(this.id)}/ticket`,
-      {}
-    );
+    const path = `/api/control/sessions/${encodeURIComponent(this.id)}/ticket`;
+    const { ticket } = await this.http.request("POST", path, {});
     return `${this.http.baseUrl}/api/live/${this.id}?ticket=${encodeURIComponent(ticket)}`;
   }
   /**
@@ -289,12 +416,9 @@ var Browser = class {
    * expires or you revoke it, so treat it like a password.
    */
   async shareUrl({ control = false, expiresInSeconds = 3600 } = {}) {
-    const c = await this.http.request(
-      "POST",
-      `/api/control/sessions/${encodeURIComponent(this.id)}/share`,
-      { control, expiresIn: expiresInSeconds }
-    );
-    return { url: `${this.http.baseUrl}/live/${encodeURIComponent(this.id)}#t=${encodeURIComponent(c.token)}`, id: c.id, expiresAt: c.expiresAt };
+    const path = `/api/control/sessions/${encodeURIComponent(this.id)}/share`;
+    const c = await this.http.request("POST", path, { control, expiresIn: expiresInSeconds });
+    return { url: shareLink(this.http.baseUrl, this.id, c.token), id: c.id, expiresAt: c.expiresAt };
   }
   /** Revoke a link from `shareUrl()` before it expires, by the id it returned. */
   async revokeShare(id) {
@@ -309,7 +433,7 @@ var Browser = class {
    * CDP session is handed back to its provider, a desktop browser disconnects.
    */
   stop() {
-    return this.http.request("POST", `/api/browsers/${this.id}/stop`, {}, 6e4);
+    return this.http.request("POST", `/api/browsers/${this.id}/stop`, {}, STOP_TIMEOUT_MS);
   }
   /** `await using browser = await oya.browser.start()` stops it however the block exits, errors included. */
   async [Symbol.asyncDispose]() {
@@ -320,75 +444,258 @@ var Browser = class {
     await this.stop();
   }
 };
-var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
-var Run = class {
-  constructor(http, id, callbacks, pollMs = 2e3) {
-    this.http = http;
-    this.id = id;
-    this.done = this.watch(callbacks, pollMs);
-    this.done.catch(() => {
-    });
+function assertCaptchaCleared(result) {
+  if (!result.present || result.solved || result.invisible) return;
+  const message = result.error || "CAPTCHA needs attention. Call solveCaptcha() again or open the live view.";
+  throw new OyaError(message, Status.CONFLICT, result);
+}
+function toElementId(value) {
+  const id = Number(value);
+  const wrongType = typeof value !== "number" && typeof value !== "string";
+  if (wrongType || value === "" || !Number.isInteger(id) || id < 0) {
+    throw new OyaError("Use a numeric element id from browser.analyze().", Status.BAD_REQUEST, null);
   }
-  http;
-  id;
-  done;
-  status() {
-    return this.http.request("GET", `/api/runs/${encodeURIComponent(this.id)}`);
+  return id;
+}
+function scrollParams(direction, amount, at) {
+  if (!at) return { direction, amount };
+  return { direction, amount: amount ?? AIMED_SCROLL_AMOUNT, ...at, smooth: false };
+}
+function agentAnswer(res) {
+  if (res.error) throw new OyaError(res.error, res.status ?? Status.SERVER_ERROR, res);
+  return res;
+}
+function consoleLink(baseUrl, id) {
+  return `${baseUrl}/dashboard/?browser=${encodeURIComponent(id)}`;
+}
+function shareLink(baseUrl, id, token) {
+  return `${baseUrl}/live/${encodeURIComponent(id)}#t=${encodeURIComponent(token)}`;
+}
+
+// src/api/browsers.ts
+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 };
+}
+async function start(http, wait, options) {
+  const headers = { "Idempotency-Key": options.idempotencyKey || globalThis.crypto.randomUUID() };
+  const path = "/api/browsers/start";
+  const started = await http().request("POST", path, startBody(options), START_TIMEOUT_MS, headers);
+  if (started.status === "starting") {
+    await wait(started.id, options.readyTimeoutMs ?? READY_TIMEOUT_MS + (options.queueMs || 0));
+    started.cdpUrl = (await fetchBrowser(http, started.id)).cdpUrl;
+  }
+  return new Browser(http(), started, options.captcha === "auto");
+}
+var fetchBrowser = (http, id) => http().request("GET", `/api/browsers/${encodeURIComponent(id)}`);
+async function reattach(http, id) {
+  const found = await fetchBrowser(http, id);
+  return new Browser(http(), asStarted(found), false);
+}
+function asStarted(found) {
+  const provider = found.provider || "cdp";
+  return { id: found.id, provider, persona: found.persona || "default", status: "ready", cdpUrl: found.cdpUrl };
+}
+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),
+  /** Reattach to a browser that is already running. */
+  get: (id) => reattach(http, id),
+  /** Every browser on this key. */
+  list: () => http().request("GET", "/api/browsers"),
+  /** Stop some (`ids`) or every browser on this key. Each reports separately. */
+  stop: (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 sessionCalls = (http) => ({
+  /** Settings, sessions and recent events at a glance. */
+  overview: () => http().request("GET", "/api/control"),
+  /** Every session, including disconnected and cleanup-pending ones. */
+  sessions: () => http().request("GET", "/api/control/sessions"),
+  /** One session. */
+  session: (id) => http().request("GET", session(id)),
+  /** Update limits, rate cards and retention. */
+  settings: (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; `force` stops despite a profile-save error, or reconciles. */
+  stop: (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 }),
+  /** Send one input as the human holding the control lease. */
+  input: (id, action, params) => http().request("POST", session(id, "/input"), { action, params })
+});
+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 }),
+  /** A single-use ticket for the live stream. */
+  ticket: (id) => http().request("POST", session(id, "/ticket"), {}),
+  /** Durable lifecycle events after a cursor. */
+  events: (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),
+  /** Revoke a service credential. */
+  revokeCredential: (id) => http().request("DELETE", item("credentials", id))
+});
+var memberCalls = (http) => ({
+  /** The owner and every member. */
+  members: () => http().request("GET", "/api/control/members"),
+  /** An invitation code for a new member. */
+  inviteMember: (role = "operator") => http().request("POST", "/api/control/members/invite", { role }),
+  /** Remove a member. */
+  removeMember: (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 }),
+  /** Disable a webhook. */
+  removeWebhook: (id) => http().request("DELETE", item("webhooks", id)),
+  /** Send a delivery again. */
+  replayDelivery: (id) => http().request("POST", `${item("deliveries", id)}/replay`, {})
+});
+var controlApi = (http) => ({
+  ...sessionCalls(http),
+  ...lifecycleCalls(http),
+  ...recoveryCalls(http),
+  ...credentialCalls(http),
+  ...memberCalls(http),
+  ...webhookCalls(http)
+});
+
+// src/api/playbooks.ts
+var playbook = (name) => `/api/playbooks/${encodeURIComponent(name)}`;
+var playbookApi = (http) => ({
+  /** Every saved playbook, with any draft waiting on it. */
+  list: async () => (await http().request("GET", "/api/playbooks")).playbooks,
+  /** Delete a playbook and its draft, or only the draft with `'<name>:draft'`. */
+  remove: async (name) => {
+    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`, {})
+});
+
+// src/api/proxies.ts
+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),
+  /** Remove one of this key's proxies. */
+  remove: async (id) => {
+    await http().request("DELETE", `/api/proxies/${encodeURIComponent(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
+});
+
+// src/api/personas.ts
+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}`),
+  /**
+   * 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),
+  /** Name, concurrency cap and proxy hint. Never the device — clone for that. */
+  update: (id, changes) => http().request("PUT", `/api/personas/${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)
+});
+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"),
+  /** 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 }),
+  /** Delete a persona. */
+  remove: async (id) => {
+    await http().request("DELETE", `/api/personas/${id}`);
   }
-  /** Answer the open attention request: `'done'` after handling it by hand, or your reply to the agent. */
-  async respond(response = "done") {
-    await this.http.request("POST", `/api/runs/${encodeURIComponent(this.id)}/respond`, { response });
+});
+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),
+  /** 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)}` : ""}`);
+  }
+});
+var loginCalls = (http) => ({
+  /**
+   * 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, config) => http().request("PUT", `/api/personas/${id}/credentials`, config),
+  /** Which sites this identity can sign in to. Usernames only. */
+  credentials: (id) => http().request("GET", `/api/personas/${id}/credentials`),
+  /** Remove the login stored for one site. */
+  clearCredentials: async (id, domain) => {
+    await http().request("DELETE", `/api/personas/${id}/credentials?domain=${encodeURIComponent(domain)}`);
   }
-  async watch(cb, pollMs) {
-    const call = async (fn) => {
-      try {
-        await fn();
-      } catch (err) {
-        console.error("[oya] run callback threw:", err);
-      }
-    };
-    let seen;
-    for (let errors = 0; ; ) {
-      let run;
-      try {
-        run = await this.status();
-        errors = 0;
-      } catch (err) {
-        if (++errors < 5) {
-          await sleep(pollMs);
-          continue;
-        }
-        const failure = err instanceof OyaError ? err : new OyaError(String(err), 0, null);
-        await call(() => cb.onFailure?.(failure));
-        throw failure;
-      }
-      if (run.status === "needs_attention" && run.attention && run.attention.id !== seen) {
-        seen = run.attention.id;
-        const request = {
-          ...run.attention,
-          liveViewUrl: run.attention.liveViewUrl && new URL(run.attention.liveViewUrl, this.http.baseUrl).href,
-          respond: (response) => this.respond(response)
-        };
-        void call(() => cb.onHumanAttention?.(request));
-      }
-      if (run.status === "succeeded") {
-        const result = run.result || {};
-        if (result.healed) await call(() => cb.onHealed?.(result));
-        await call(() => cb.onSuccess?.(result));
-        return result;
-      }
-      if (run.status === "failed") {
-        const failure = new OyaError(run.error || "Run failed", run.errorStatus ?? 500, run);
-        await call(() => cb.onFailure?.(failure));
-        throw failure;
-      }
-      await sleep(pollMs);
+});
+var personaApi = (http) => ({
+  ...identityCalls(http),
+  ...deviceCalls(http),
+  ...mfaCalls(http),
+  ...loginCalls(http)
+});
+
+// src/api/config.ts
+var configApi = (http) => ({
+  /** This key's settings. Secrets read back masked. */
+  get: () => http().request("GET", "/api/config"),
+  /** Change settings; `null` clears a field back to the deployment default. */
+  set: (values) => http().request("POST", "/api/config", values)
+});
+
+// src/api/ready.ts
+var ENDED = ["failed", "stopped", "unknown_outcome"];
+async function waitUntilConnected(checks, id, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (await isUp(checks, id)) return;
+    await new Promise((r) => setTimeout(r, READY_POLL_MS));
+  }
+  const seconds = Math.round(timeoutMs / MS_PER_SECOND);
+  throw new OyaError(`Browser ${id} did not come up within ${seconds}s`, Status.GATEWAY_TIMEOUT, null);
+}
+async function isUp(checks, id) {
+  const all = await checks.list();
+  if (all.some((b) => b.id === id && b.health !== "dead")) return true;
+  await assertNotEnded(checks, id);
+  return false;
+}
+async function assertNotEnded(checks, id) {
+  try {
+    const session2 = await checks.session(id);
+    if (ENDED.includes(session2.state)) {
+      throw new OyaError(`Browser creation ended in ${session2.state}`, Status.CONFLICT, session2);
     }
+  } catch (e) {
+    if (!(e instanceof OyaError) || e.status !== Status.NOT_FOUND) throw e;
   }
-};
+}
 
 // src/file.ts
-var MAX_FILE_BYTES = 10 * 1024 * 1024;
+var MAX_FILE_BYTES = MAX_FILE_MB * BYTES_PER_MB;
 var NODE_FS = "node:fs/promises";
 var MIME = {
   pdf: "application/pdf",
@@ -416,172 +723,67 @@ var base64 = (bytes) => {
   const buffer = globalThis.Buffer;
   if (buffer) return buffer.from(bytes).toString("base64");
   let binary = "";
-  for (let i = 0; i < bytes.length; i += 8192) binary += String.fromCharCode(...bytes.subarray(i, i + 8192));
+  for (let i = 0; i < bytes.length; i += BASE64_CHUNK_BYTES) {
+    binary += String.fromCharCode(...bytes.subarray(i, i + BASE64_CHUNK_BYTES));
+  }
   return btoa(binary);
 };
-async function file(source, options = {}) {
-  let bytes;
-  let name = options.name;
-  if (typeof source === "string") {
-    const fs = await import(
-      /* webpackIgnore: true */
-      /* @vite-ignore */
-      NODE_FS
-    );
-    bytes = new Uint8Array(await fs.readFile(source));
-    name ||= source.split(/[\\/]/).pop() || "file";
-  } else if (source instanceof Uint8Array) {
-    bytes = source;
-  } else {
-    bytes = new Uint8Array(await source.arrayBuffer());
-    name ||= source.name;
-  }
-  name ||= "file";
-  if (bytes.length > MAX_FILE_BYTES) {
-    throw new Error(`${name} is ${Math.round(bytes.length / 1024 / 1024)}MB; the limit for a task file is ${MAX_FILE_BYTES / 1024 / 1024}MB.`);
-  }
+async function readPath(path) {
+  const fs = await import(
+    /* webpackIgnore: true */
+    /* @vite-ignore */
+    NODE_FS
+  );
+  return { bytes: new Uint8Array(await fs.readFile(path)), name: path.split(/[\\/]/).pop() || "file" };
+}
+async function readSource(source) {
+  if (typeof source === "string") return readPath(source);
+  if (source instanceof Uint8Array) return { bytes: source };
+  return { bytes: new Uint8Array(await source.arrayBuffer()), name: source.name };
+}
+function checkSize(name, bytes) {
+  if (bytes.length <= MAX_FILE_BYTES) return;
+  throw new Error(
+    `${name} is ${Math.round(bytes.length / BYTES_PER_MB)}MB; the limit for a task file is ${MAX_FILE_BYTES / BYTES_PER_MB}MB.`
+  );
+}
+function mimeFor(name) {
   const ext = name.includes(".") ? name.split(".").pop().toLowerCase() : "";
-  return { file: name, type: options.type || MIME[ext] || "application/octet-stream", b64: base64(bytes) };
+  return MIME[ext] || "application/octet-stream";
+}
+function fileValue(name, bytes, type) {
+  checkSize(name, bytes);
+  return { file: name, type: type || mimeFor(name), b64: base64(bytes) };
+}
+async function file(source, options = {}) {
+  const read = await readSource(source);
+  return fileValue(options.name || read.name || "file", read.bytes, options.type);
 }
 
 // src/index.ts
-var DEFAULT_BASE_URL = "https://browser.getoya.ai";
-var READY_POLL_MS = 2e3;
-var env = (name) => globalThis.process?.env?.[name];
 var Oya = class {
+  /** The one HTTP path every call goes through. */
   http;
+  /** Reads the key and URL from `options`, then OYA_API_KEY and OYA_BASE_URL. Throws without a key. */
   constructor(options = {}) {
-    const apiKey = options.apiKey || env("OYA_API_KEY");
-    if (!apiKey) {
-      throw new Error("No API key. Pass { apiKey } or set OYA_API_KEY \u2014 run `oya login` to get one.");
-    }
-    const baseUrl = (options.baseUrl || env("OYA_BASE_URL") || DEFAULT_BASE_URL).replace(/\/+$/, "");
-    const fetchImpl = options.fetch || globalThis.fetch;
-    if (!fetchImpl) throw new Error("No fetch available \u2014 pass { fetch } or use Node 18+.");
-    this.http = new Http(baseUrl, apiKey, options.timeoutMs ?? 6e4, fetchImpl.bind(globalThis));
-  }
-  browser = {
-    /** Start a browser and wait until it can take commands. */
-    start: async (options = {}) => {
-      const started = await this.http.request("POST", "/api/browsers/start", {
-        profile: options.profile || options.persona,
-        provider: options.provider,
-        wsUrl: options.wsUrl,
-        name: options.name,
-        queueMs: options.queueMs,
-        priority: options.priority,
-        budgetUsd: options.budgetUsd,
-        governed: options.governed,
-        policy: options.policy
-      }, 12e4, { "Idempotency-Key": options.idempotencyKey || globalThis.crypto.randomUUID() });
-      if (started.status === "starting") {
-        await this.waitUntilConnected(started.id, options.readyTimeoutMs ?? 12e4 + (options.queueMs || 0));
-        const connected = await this.http.request("GET", `/api/browsers/${encodeURIComponent(started.id)}`);
-        started.cdpUrl = connected.cdpUrl;
-      }
-      return new Browser(this.http, started, options.captcha === "auto");
-    },
-    /** Reattach to a browser that is already running. */
-    get: async (id) => {
-      const found = await this.http.request("GET", `/api/browsers/${encodeURIComponent(id)}`);
-      return new Browser(this.http, {
-        id: found.id,
-        provider: found.provider || "cdp",
-        persona: found.persona || "default",
-        status: "ready",
-        cdpUrl: found.cdpUrl
-      }, false);
-    },
-    list: () => this.http.request("GET", "/api/browsers"),
-    /** Stop some (`ids`) or every browser on this key. Each reports separately. */
-    stop: (ids) => this.http.request("POST", "/api/browsers/stop", ids === "all" ? { all: true } : { ids }, 12e4),
-    stopAll: async () => (await this.browser.stop("all")).stopped
-  };
+    this.http = createHttp(options);
+  }
+  /** Start, reattach to, list and stop browsers. */
+  browser = browserApi(
+    () => this.http,
+    (id, timeoutMs) => this.waitUntilConnected(id, timeoutMs)
+  );
   /** Durable operational controls, including disconnected and cleanup-pending sessions. */
-  control = {
-    overview: () => this.http.request("GET", "/api/control"),
-    sessions: () => this.http.request("GET", "/api/control/sessions"),
-    session: (id) => this.http.request("GET", `/api/control/sessions/${encodeURIComponent(id)}`),
-    settings: (changes) => this.http.request("PATCH", "/api/control/project", changes),
-    cancel: (id) => this.http.request("POST", `/api/control/sessions/${encodeURIComponent(id)}/cancel`, {}),
-    stop: (id, force = false) => this.http.request("POST", `/api/control/sessions/${encodeURIComponent(id)}/stop`, { force }),
-    takeover: (id, action) => this.http.request("POST", `/api/control/sessions/${encodeURIComponent(id)}/control`, { action }),
-    input: (id, action, params) => this.http.request("POST", `/api/control/sessions/${encodeURIComponent(id)}/input`, { action, params }),
-    recover: (id, replace = false) => this.http.request("POST", `/api/control/sessions/${encodeURIComponent(id)}/recover`, { replace }),
-    ticket: (id) => this.http.request("POST", `/api/control/sessions/${encodeURIComponent(id)}/ticket`, {}),
-    events: (after = 0) => this.http.request("GET", `/api/control/events?after=${after}`),
-    createCredential: (options) => this.http.request("POST", "/api/control/credentials", options),
-    revokeCredential: (id) => this.http.request("DELETE", `/api/control/credentials/${encodeURIComponent(id)}`),
-    members: () => this.http.request("GET", "/api/control/members"),
-    inviteMember: (role = "operator") => this.http.request("POST", "/api/control/members/invite", { role }),
-    removeMember: (userId) => this.http.request("DELETE", `/api/control/members/${encodeURIComponent(userId)}`),
-    createWebhook: (url, types = []) => this.http.request("POST", "/api/control/webhooks", { url, types }),
-    removeWebhook: (id) => this.http.request("DELETE", `/api/control/webhooks/${encodeURIComponent(id)}`),
-    replayDelivery: (id) => this.http.request("POST", `/api/control/deliveries/${encodeURIComponent(id)}/replay`, {})
-  };
+  control = controlApi(() => this.http);
   /** Playbooks saved with `browser.toPlaybook()`. */
-  playbooks = {
-    list: async () => (await this.http.request("GET", "/api/playbooks")).playbooks,
-    /** Delete a playbook and its draft, or only the draft with `'<name>:draft'`. */
-    remove: async (name) => {
-      await this.http.request("DELETE", `/api/playbooks/${encodeURIComponent(name)}`);
-    },
-    /** Replace a playbook with the draft a healed replay saved. Try it first with `browser.play('<name>:draft')`. */
-    promote: (name) => this.http.request("POST", `/api/playbooks/${encodeURIComponent(name)}/promote`, {})
-  };
+  playbooks = playbookApi(() => this.http);
   /**
    * Proxy exits for your personas. A persona takes one at first connect (by its
    * geo hint) or by `personas.pinProxy`, and keeps it.
    */
-  proxies = {
-    list: async () => (await this.http.request("GET", "/api/proxies")).proxies,
-    create: (proxy) => this.http.request("POST", "/api/proxies", proxy),
-    remove: async (id) => {
-      await this.http.request("DELETE", `/api/proxies/${encodeURIComponent(id)}`);
-    },
-    /** Dial each proxy and learn its real exit IP. Failing ones cool down and are skipped. */
-    check: async () => (await this.http.request("POST", "/api/proxies/check", {})).results
-  };
-  personas = {
-    list: async () => (await this.http.request("GET", "/api/personas")).personas,
-    get: (id) => this.http.request("GET", `/api/personas/${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 = {}) => this.http.request("POST", "/api/personas", options),
-    /** Name, concurrency cap and proxy hint. Never the device — clone for that. */
-    update: (id, changes) => this.http.request("PUT", `/api/personas/${id}`, changes),
-    /** A new persona of the same kind of device: same choices, fresh identity, empty jar. */
-    clone: (id, options = {}) => this.http.request("POST", `/api/personas/${id}/clone`, options),
-    /** The fingerprint these choices would produce. Persists nothing. */
-    preview: async (prefs = {}) => (await this.http.request("POST", "/api/personas/preview", { prefs })).fingerprint,
-    /** Platforms, and the timezones and locales each may coherently claim. */
-    options: () => this.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) => this.http.request("PUT", `/api/personas/${id}/proxy`, { proxyId }),
-    remove: async (id) => {
-      await this.http.request("DELETE", `/api/personas/${id}`);
-    },
-    /** Store the second factor for this identity. Sealed at rest, never read back. */
-    setMfa: (id, config) => this.http.request("PUT", `/api/personas/${id}/mfa`, config),
-    clearMfa: async (id, domain) => {
-      await this.http.request("DELETE", `/api/personas/${id}/mfa${domain ? `?domain=${encodeURIComponent(domain)}` : ""}`);
-    },
-    /**
-     * 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, config) => this.http.request("PUT", `/api/personas/${id}/credentials`, config),
-    /** Which sites this identity can sign in to. Usernames only. */
-    credentials: (id) => this.http.request("GET", `/api/personas/${id}/credentials`),
-    clearCredentials: async (id, domain) => {
-      await this.http.request("DELETE", `/api/personas/${id}/credentials?domain=${encodeURIComponent(domain)}`);
-    }
-  };
+  proxies = proxyApi(() => this.http);
+  /** Identities: fingerprint, cookie jar and proxy bound together, plus their stored factors and logins. */
+  personas = personaApi(() => this.http);
   /**
    * This key's settings: LLM credentials, browser provider, solver.
    *
@@ -593,29 +795,17 @@ var Oya = class {
    * project-scoped endpoint, set `openai_base_url` to `.../endpoints/openapi` and pass an
    * OAuth access token as `openai_api_key`. See {@link ConfigUpdate} for every field.
    */
-  config = {
-    get: () => this.http.request("GET", "/api/config"),
-    set: (values) => this.http.request("POST", "/api/config", values)
-  };
+  config = configApi(() => this.http);
   /** Saved profiles. `personas` is retained as an alias for existing clients. */
   profiles = this.personas;
+  /** What this key has spent. */
   usage() {
     return this.http.request("GET", "/api/usage");
   }
+  /** Waits for a starting browser to dial in, through this client's own list and session calls. */
   async waitUntilConnected(id, timeoutMs) {
-    const deadline = Date.now() + timeoutMs;
-    while (Date.now() < deadline) {
-      const all = await this.browser.list();
-      if (all.some((b) => b.id === id && b.health !== "dead")) return;
-      try {
-        const session = await this.control.session(id);
-        if (["failed", "stopped", "unknown_outcome"].includes(session.state)) throw new OyaError(`Browser creation ended in ${session.state}`, 409, session);
-      } catch (e) {
-        if (!(e instanceof OyaError) || e.status !== 404) throw e;
-      }
-      await new Promise((r) => setTimeout(r, READY_POLL_MS));
-    }
-    throw new OyaError(`Browser ${id} did not come up within ${Math.round(timeoutMs / 1e3)}s`, 504, null);
+    const checks = { list: () => this.browser.list(), session: (sid) => this.control.session(sid) };
+    await waitUntilConnected(checks, id, timeoutMs);
   }
 };
 var index_default = Oya;