@oya-ai/browser 1.0.103 → 1.0.105

package/README.md

@@ -1,49 +1,54 @@
 # @oya-ai/browser
 
 <p align="center">
-  <strong>Thousands of browsers behind one API: personas, residential proxies, measured stealth, CAPTCHA, and MFA.</strong>
+  <strong>A real browser your agents drive from the inside. Record a run once, replay it with no model in the loop.</strong>
 </p>
 
 <p align="center">
   <a href="https://www.npmjs.com/package/@oya-ai/browser"><img src="https://img.shields.io/npm/v/@oya-ai/browser?color=39ed35&label=@oya-ai/browser&logo=npm" alt="NPM Version"></a>
   <a href="https://github.com/OyadotAI/oya-browser/blob/main/packages/sdk/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg?color=39ed35" alt="License: MIT"></a>
   <a href="https://www.typescriptlang.org"><img src="https://img.shields.io/badge/TypeScript-Ready-3178C6.svg?logo=typescript&logoColor=white" alt="TypeScript"></a>
-  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg" alt="Node Version"></a>
+  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen.svg" alt="Node Version"></a>
   <a href="https://bundlephobia.com/package/@oya-ai/browser"><img src="https://img.shields.io/bundlephobia/minzip/@oya-ai/browser?color=39ed35" alt="Bundle Size"></a>
 </p>
 
 ---
 
-Orchestrate browser instances running on **Oya Cloud sandboxes**, **Browserbase**, **Steel**, **Anchor**, **Browser Use**, or your own **private Chrome fleet**.
-
-Oya does for browser vendors what OpenRouter does for LLM providers. The vendor behind a browser is a setting on your API key, or one `provider` parameter, so switching vendors never means rewriting your agent.
+## From nothing to an answer
 
 ```bash
 npm install @oya-ai/browser
 ```
 
-Get an API key at [browser.getoya.ai](https://browser.getoya.ai) or self-host your control plane, and set `OYA_API_KEY`.
+```js
+import { Oya } from '@oya-ai/browser';
 
----
+const browser = await new Oya().browser.start();
+await browser.goto('https://news.ycombinator.com');
+console.log(await browser.ask('What are the top 3 stories?'));
+```
 
-## Quickstart
+Two things to have first: an API key from [oyabrowser.com](https://oyabrowser.com)
+(or your own deployment) in `OYA_API_KEY`, and a browser to drive.
 
-Requires Node.js 18+; examples use ES modules. Set `OYA_API_KEY` in your environment. `OYA_BASE_URL` optionally points to a self-hosted control plane.
+**The fastest browser to have is one you already have.** Open the
+[Oya desktop browser](https://oyabrowser.com) and sign in with the same key: `start()`
+hands over the browser that is already connected when no provider is configured, so the
+five lines above work with nothing else set up. `stop()` leaves a browser you borrowed
+alone, because you did not start it.
 
-```js
-import { Oya } from "@oya-ai/browser";
+When you would rather it start one for you, run `npx @oya-ai/cli init` and pick where
+browsers run: Oya Cloud, your own Docker, Browserbase, Steel, Anchor, Browser Use, or a
+Chrome of your own over CDP. Your code does not change.
 
-const oya = new Oya();
-const browser = await oya.browser.start({ captcha: "auto" });
-try {
-  await browser.goto("https://example.com");
-  console.log(await browser.ask("What is the main heading on this page?"));
-} finally {
-  await browser.stop();
-}
-```
+**Where the key comes from**, in order: `new Oya({ apiKey })`, then `OYA_API_KEY`, then the
+file `oya login` wrote (`~/.oya/config.json`, or `OYA_CONFIG_HOME`), which is read on Node
+22.3 and newer. `baseUrl` resolves the same way. A CI job that sets neither fails loudly
+rather than borrowing whatever is on the machine.
 
-On Node.js 24+, `await using browser = await oya.browser.start()` also stops the browser when its scope exits, including on error.
+Node.js 20 or newer; the examples are ES modules. `OYA_BASE_URL` points at a self-hosted
+control plane. On Node.js 24+, `await using browser = await oya.browser.start()` stops it
+when the scope exits, errors included.
 
 ## Portal automation: record once, replay with new inputs
 
@@ -52,8 +57,8 @@ This example adapts the portal-automation project's workflow: reuse a persona, a
 Save as `portal.mjs` and run `node portal.mjs` after setting `OYA_API_KEY`, `PORTAL_URL`, `PORTAL_USERNAME`, and `PORTAL_PASSWORD`. Set `OYA_BROWSER_ID` only to reuse an already running browser.
 
 ```js
-import { createInterface } from "node:readline/promises";
-import { Oya } from "@oya-ai/browser";
+import { createInterface } from 'node:readline/promises';
+import { Oya } from '@oya-ai/browser';
 
 function requiredEnv(name) {
   const value = process.env[name];
@@ -61,79 +66,76 @@ function requiredEnv(name) {
   return value;
 }
 
-const oya = new Oya({ apiKey: requiredEnv("OYA_API_KEY") });
-const portalUrl = requiredEnv("PORTAL_URL");
-const playbookName = "portal-request-review";
+const oya = new Oya({ apiKey: requiredEnv('OYA_API_KEY') });
+const portalUrl = requiredEnv('PORTAL_URL');
+const playbookName = 'portal-request-review';
 const secrets = {
-  username: requiredEnv("PORTAL_USERNAME"),
-  password: requiredEnv("PORTAL_PASSWORD"),
+  username: requiredEnv('PORTAL_USERNAME'),
+  password: requiredEnv('PORTAL_PASSWORD'),
 };
 // Fictional test inputs. data is visible to the agent.
 const data = {
-  customerName: "Alex Example",
-  requestId: "DEMO-0001",
-  requestedDate: "2030-01-15",
+  customerName: 'Alex Example',
+  requestId: 'DEMO-0001',
+  requestedDate: '2030-01-15',
 };
 const task = [
-  "If not logged in, log in with {{username}} and {{password}}.",
-  "Open New Request and enter {{requestId}} as the reference.",
-  "Fill first name {{customerName|first}} and last name {{customerName|last}}.",
-  "Set the requested date to {{requestedDate|date:MM/DD/YYYY}}.",
-  "If a field is already correct, do not type its value again.",
-  "If an action times out, inspect the page before retrying it.",
-  "If information is missing, ask the person instead of guessing.",
-  "Stop on the review page. Do not submit the request.",
-].join("\n");
+  'If not logged in, log in with {{username}} and {{password}}.',
+  'Open New Request and enter {{requestId}} as the reference.',
+  'Fill first name {{customerName|first}} and last name {{customerName|last}}.',
+  'Set the requested date to {{requestedDate|date:MM/DD/YYYY}}.',
+  'If a field is already correct, do not type its value again.',
+  'If an action times out, inspect the page before retrying it.',
+  'If information is missing, ask the person instead of guessing.',
+  'Stop on the review page. Do not submit the request.',
+].join('\n');
 
 const existingId = process.env.OYA_BROWSER_ID;
 let browser;
 if (existingId) {
   browser = await oya.browser.get(existingId);
 } else {
-  const persona = (await oya.personas.list())
-    .find((p) => p.name === "portal-demo")
-    ?? await oya.personas.create({ name: "portal-demo" });
-  browser = await oya.browser.start({ persona: persona.id, captcha: "auto" });
+  const persona =
+    (await oya.personas.list()).find((p) => p.name === 'portal-demo') ??
+    (await oya.personas.create({ name: 'portal-demo' }));
+  browser = await oya.browser.start({ persona: persona.id, captcha: 'auto' });
 }
 
 try {
-  console.log("Watch in your Oya dashboard:", browser.liveViewUrl());
+  console.log('Watch in your Oya dashboard:', browser.liveViewUrl());
   await browser.goto(portalUrl);
   const exists = (await oya.playbooks.list()).some((p) => p.name === playbookName);
-  const run = await browser.submit(
-    exists ? { playbook: playbookName } : { prompt: task },
-    {
-      // Replay accepts all variables in data; the playbook remembers secret names.
-      ...(exists ? { data: { ...data, ...secrets } } : { data, secrets }),
-      onSuccess: () => console.log("Run succeeded."),
-      onFailure: (error) => console.error("Run failed with status:", error.status),
-      onHealed: (result) => {
-        console.log("A repair draft is ready for review:", result.draft);
-      },
-      onHumanAttention: async (request) => {
-        console.log("Attention needed:", request.reason);
-        console.log(request.message);
-        console.log("Open:", request.liveViewUrl ?? browser.liveViewUrl());
-        const terminal = createInterface({ input: process.stdin, output: process.stdout });
-        try {
-          const answer = await terminal.question(request.reason === "agent"
-            ? "Answer the agent: "
-            : "Handle this in the live view, then press Enter: ");
-          await request.respond(answer || "done");
-        } finally {
-          terminal.close();
-        }
-      },
+  const run = await browser.submit(exists ? { playbook: playbookName } : { prompt: task }, {
+    // Replay accepts all variables in data; the playbook remembers secret names.
+    ...(exists ? { data: { ...data, ...secrets } } : { data, secrets }),
+    onSuccess: () => console.log('Run succeeded.'),
+    onFailure: (error) => console.error('Run failed with status:', error.status),
+    onHealed: (result) => {
+      console.log('A repair draft is ready for review:', result.draft);
+    },
+    onHumanAttention: async (request) => {
+      console.log('Attention needed:', request.reason);
+      console.log(request.message);
+      console.log('Open:', request.liveViewUrl ?? browser.liveViewUrl());
+      const terminal = createInterface({ input: process.stdin, output: process.stdout });
+      try {
+        const answer = await terminal.question(
+          request.reason === 'agent' ? 'Answer the agent: ' : 'Handle this in the live view, then press Enter: ',
+        );
+        await request.respond(answer || 'done');
+      } finally {
+        terminal.close();
+      }
     },
-  );
+  });
 
   await run.done; // Rejects on failure; do not save a failed run as a playbook.
   const info = await run.status();
-  console.log("Run status:", info.status);
+  console.log('Run status:', info.status);
   if (!exists) {
     const playbook = await browser.toPlaybook(playbookName);
-    console.log("Saved:", playbook.name, "Steps:", playbook.steps);
-    console.log("Variables:", playbook.variables);
+    console.log('Saved:', playbook.name, 'Steps:', playbook.steps);
+    console.log('Variables:', playbook.variables);
     // playbook.code contains the flow as an exported Playwright module.
   }
 } finally {
@@ -152,22 +154,22 @@ For prompt runs, pass credentials in `secrets`. For replay, pass all variables i
 
 ### Files
 
-`file()` puts a file in `data`. The agent attaches it with its upload tool: hand it the element id of whatever you can see — the "Choose file" button, the drop zone, the field itself — and the real `<input type="file">` is found from there, including the hidden ones most upload widgets use.
+`file()` puts a file in `data`. The agent attaches it with its upload tool: hand it the element id of whatever you can see (the "Choose file" button, the drop zone, the field itself) and the real `<input type="file">` is found from there, including the hidden ones most upload widgets use.
 
 ```js
-import { Oya, file } from "@oya-ai/browser";
+import { Oya, file } from '@oya-ai/browser';
 
-await browser.ask("Attach my resume to the application and submit it", {
-  data: { name: "Ada Lovelace", resume: await file("./cv.pdf") },
+await browser.ask('Attach my resume to the application and submit it', {
+  data: { name: 'Ada Lovelace', resume: await file('./cv.pdf') },
 });
 ```
 
-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.
+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.
 
 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
-await browser.play("job-application", { name: "Ada Lovelace", resume: await file("./other.pdf") });
+await browser.play('job-application', { name: 'Ada Lovelace', resume: await file('./other.pdf') });
 ```
 
 The generated Playwright module calls `setInputFiles`, where the same variable is a plain path rather than a `file()` value.
@@ -179,8 +181,7 @@ Replay normally runs recorded steps without an LLM. With `autoHeal: true` (the d
 The following continues with an active `browser` and the inputs above. Replaying a draft performs its actions, so review its code and use test inputs before promoting it.
 
 ```js
-const saved = (await oya.playbooks.list())
-  .find((p) => p.name === playbookName);
+const saved = (await oya.playbooks.list()).find((p) => p.name === playbookName);
 if (saved?.draft) {
   // Review saved.draft.code before executing it.
   await browser.play(`${playbookName}:draft`, { ...data, ...secrets }, { autoHeal: false });
@@ -195,13 +196,13 @@ Use `autoHeal: false` with `play()` or `submit({ playbook: name }, options)` to
 As in the portal-automation project's model setup script, configure the model on your Oya API key once for subsequent agent runs:
 
 ```js
-import { Oya } from "@oya-ai/browser";
+import { Oya } from '@oya-ai/browser';
 
 const modelKey = process.env.GEMINI_API_KEY;
-if (!modelKey) throw new Error("Set GEMINI_API_KEY first.");
+if (!modelKey) throw new Error('Set GEMINI_API_KEY first.');
 const oya = new Oya();
 await oya.config.set({
-  llm_provider: "gemini", // LlmProvider: "openai" | "anthropic" | "gemini" | "vertex"
+  llm_provider: 'gemini', // LlmProvider: "openai" | "anthropic" | "gemini" | "vertex"
   openai_api_key: modelKey, // Shared field name for every supported provider.
   // chat_model: process.env.OYA_CHAT_MODEL, // Optional provider model override.
 });
@@ -210,13 +211,13 @@ await oya.config.set({
 `config.set` takes `ConfigUpdate` and `config.get()` returns `Config`, so an editor offers the valid providers and a typo fails to compile rather than silently falling back:
 
 ```ts
-import { Oya, type LlmProvider } from "@oya-ai/browser";
+import { Oya, type LlmProvider } from '@oya-ai/browser';
 
-await oya.config.set({ llm_provider: "vertx" });
+await oya.config.set({ llm_provider: 'vertx' });
 //                                   ~~~~~~~ Type '"vertx"' is not assignable to type
 //                                           'LlmProvider'. Did you mean '"vertex"'?
 
-const provider: LlmProvider = "vertex";   // for your own config plumbing
+const provider: LlmProvider = 'vertex'; // for your own config plumbing
 const { effective } = await oya.config.get();
 console.log(effective.baseUrl, effective.model, effective.hasLlmKey);
 ```
@@ -228,17 +229,18 @@ console.log(effective.baseUrl, effective.model, effective.hasLlmKey);
 `llm_provider: "vertex"` targets express mode, whose API keys work against a global endpoint with no GCP project or location:
 
 ```js
-await oya.config.set({ llm_provider: "vertex", openai_api_key: process.env.VERTEX_EXPRESS_KEY });
+await oya.config.set({ llm_provider: 'vertex', openai_api_key: process.env.VERTEX_EXPRESS_KEY });
 ```
 
 For an enterprise project instead, point at its OpenAI-compatible endpoint. That path authenticates with a Google OAuth access token rather than an API key, and the token expires after about an hour, so it suits a one-off run rather than a long-lived deployment:
 
 ```js
 await oya.config.set({
-  llm_provider: "vertex",
-  openai_base_url: "https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT/locations/us-central1/endpoints/openapi",
+  llm_provider: 'vertex',
+  openai_base_url:
+    'https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT/locations/us-central1/endpoints/openapi',
   openai_api_key: accessToken, // gcloud auth print-access-token
-  chat_model: "google/gemini-2.5-flash", // this endpoint prefixes model ids
+  chat_model: 'google/gemini-2.5-flash', // this endpoint prefixes model ids
 });
 ```
 
@@ -270,21 +272,21 @@ For an embedded SSE stream of JPEG frames, use `await browser.liveStreamUrl()`.
 A persona groups a stable device fingerprint, saved login cookies, and a proxy assignment for reuse across browser sessions.
 
 ```ts
-import { Oya } from "@oya-ai/browser";
+import { Oya } from '@oya-ai/browser';
 
 const oya = new Oya();
 
 // Create a persistent persona
 const persona = await oya.personas.create({
-  name: "us-shopper",
-  prefs: { platform: "MacIntel", timezone: "America/New_York", locale: "en-US" },
-  proxy: { geo: "US" },
+  name: 'us-shopper',
+  prefs: { platform: 'MacIntel', timezone: 'America/New_York', locale: 'en-US' },
+  proxy: { geo: 'US' },
   maxConcurrent: 2, // Limit simultaneous sessions for this identity
 });
 
 // Launch a browser with this persona (or persona: 'auto' for least-recently-used)
 await using browser = await oya.browser.start({ persona: persona.id });
-await browser.goto("https://www.amazon.com");
+await browser.goto('https://www.amazon.com');
 
 // Hardware attributes remain byte-identical on subsequent sessions
 console.log(persona.fingerprint.platform, persona.fingerprint.timezone);
@@ -300,18 +302,18 @@ console.log(persona.fingerprint.platform, persona.fingerprint.timezone);
 Skip messy DOM traversal. Get clean markdown and numbered interactive elements:
 
 ```ts
-import { Oya } from "@oya-ai/browser";
+import { Oya } from '@oya-ai/browser';
 
 const oya = new Oya();
 await using browser = await oya.browser.start();
-await browser.goto("https://github.com/trending");
+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));
 
 // Interact using numbered element IDs:
-const firstRepo = elements.find((el) => el.tag === "a" && el.href?.includes("/stargazers"));
+const firstRepo = elements.find((el) => el.tag === 'a' && el.href?.includes('/stargazers'));
 if (firstRepo) {
   await browser.click(firstRepo.id); // clicks [data-ac-id="firstRepo.id"]
 }
@@ -322,23 +324,23 @@ if (firstRepo) {
 ## 🧩 Challenge Handling: Automated CAPTCHA & Sealed MFA
 
 ```ts
-import { Oya } from "@oya-ai/browser";
+import { Oya } from '@oya-ai/browser';
 
 const oya = new Oya();
 
 // 1. Seal a TOTP secret on a persona (encrypted with AES-256-GCM at rest, never exposed over API)
-const persona = await oya.personas.create({ name: "finance-admin" });
+const persona = await oya.personas.create({ name: 'finance-admin' });
 await oya.personas.setMfa(persona.id, {
-  type: "totp",
+  type: 'totp',
   secret: process.env.TOTP_SECRET!,
 });
 
 await using browser = await oya.browser.start({ persona: persona.id });
 
 // 2. Clear CAPTCHAs automatically (uses vendor solver or CapSolver/2Captcha fallback)
-await browser.goto("https://www.google.com/recaptcha/api2/demo");
+await browser.goto('https://www.google.com/recaptcha/api2/demo');
 const captcha = await browser.solveCaptcha();
-console.log("CAPTCHA Solved:", captcha.solved, "via", captcha.method);
+console.log('CAPTCHA Solved:', captcha.solved, 'via', captcha.method);
 
 // 3. Complete Two-Factor Authentication
 await browser.goto(process.env.MFA_LOGIN_URL!);
@@ -346,7 +348,7 @@ const mfa = await browser.completeMfa();
 
 if (!mfa.completed && mfa.liveViewUrl) {
   // Hand off to human operator if interactive push notification or WebAuthn is needed
-  console.log("Interactive handoff required at:", mfa.liveViewUrl);
+  console.log('Interactive handoff required at:', mfa.liveViewUrl);
 }
 ```
 
@@ -357,20 +359,20 @@ if (!mfa.completed && mfa.liveViewUrl) {
 Every browser exposes an authenticated `browser.cdpUrl` routed through Oya's gateway. Connect standard Playwright, Puppeteer, or Stagehand:
 
 ```ts
-import { chromium } from "playwright-core";
-import { Oya } from "@oya-ai/browser";
+import { chromium } from 'playwright-core';
+import { Oya } from '@oya-ai/browser';
 
 const oya = new Oya();
 
 // Run on any underlying provider: browserbase, steel, anchor, browseruse, or oya-cloud
-await using browser = await oya.browser.start({ provider: "browserbase" });
+await using browser = await oya.browser.start({ provider: 'browserbase' });
 
 // Connect Playwright directly over Oya's gateway
 const context = (await chromium.connectOverCDP(browser.cdpUrl!)).contexts()[0];
 const page = context.pages()[0] ?? (await context.newPage());
 
-await page.goto("https://news.ycombinator.com");
-console.log("Page Title:", await page.title());
+await page.goto('https://news.ycombinator.com');
+console.log('Page Title:', await page.title());
 ```
 
 ---
@@ -380,120 +382,125 @@ console.log("Page Title:", await page.title());
 ### Initialization
 
 ```ts
-import { Oya } from "@oya-ai/browser";
+import { Oya } from '@oya-ai/browser';
 
 const oya = new Oya({
-  apiKey: "oya_...",                    // default: process.env.OYA_API_KEY
-  baseUrl: "https://browser.getoya.ai", // default: OYA_BASE_URL, then the hosted service
-  timeoutMs: 60_000,                    // per request
+  apiKey: 'oya_...', // default: process.env.OYA_API_KEY
+  baseUrl: 'https://oyabrowser.com', // default: OYA_BASE_URL, then the hosted service
+  timeoutMs: 60_000, // per request
   // fetch: customFetch,                // any fetch-compatible implementation
 });
 ```
 
 ### Browser Operations (`oya.browser`)
 
-| Method | Signature | Description |
-|:---|:---|:---|
-| `start(options)` | `(options?: StartOptions) => Promise<Browser>` | Start a browser and wait until it is ready for commands |
-| `get(id)` | `(id: string) => Promise<Browser>` | Reattach to an existing running browser |
-| `list()` | `() => Promise<BrowserInfo[]>` | List all active running browser sessions |
-| `stop(ids \| 'all')` | `(ids: string[] \| 'all') => Promise<{ stopped: number; results: StopResult[] }>` | Stop target browsers or all browsers |
-| `stopAll()` | `() => Promise<number>` | Terminate all active browser sessions |
+| Method               | Signature                                                                         | Description                                             |
+| :------------------- | :-------------------------------------------------------------------------------- | :------------------------------------------------------ |
+| `start(options)`     | `(options?: StartOptions) => Promise<Browser>`                                    | Start a browser and wait until it is ready for commands |
+| `get(id)`            | `(id: string) => Promise<Browser>`                                                | Reattach to an existing running browser                 |
+| `list()`             | `() => Promise<BrowserInfo[]>`                                                    | List all active running browser sessions                |
+| `stop(ids \| 'all')` | `(ids: string[] \| 'all') => Promise<{ stopped: number; results: StopResult[] }>` | Stop target browsers or all browsers                    |
+| `stopAll()`          | `() => Promise<number>`                                                           | Terminate all active browser sessions                   |
 
 #### `StartOptions`
 
-- `persona?: 'default' | 'auto' | string` — Assign persistent identity
+- `persona?: 'default' | 'auto' | string`, Assign persistent identity
 - `provider?: 'oya-cloud' | 'oya-selfhosted' | 'browserbase' | 'steel' | 'anchor' | 'browseruse' | 'cdp'`
-- `wsUrl?: string`: required only for the `'cdp'` provider
+- `wsUrl?: string`: required only for the `'cdp'` provider. Either the WebSocket URL, or the
+  plain `http://localhost:9222` that Chrome prints for `--remote-debugging-port`, which is
+  resolved through Chrome's own `/json/version`
 - `name?: string`: display name in the console and `oya ls`
-- `captcha?: 'auto' | 'off'` — Automatically solve CAPTCHAs on navigation
-- `queueMs?: number` — Wait duration for fleet capacity (ms)
-- `budgetUsd?: number` — Enforce budget limit for session
-- `idempotencyKey?: string` — Safe retry token
-- `governed?: boolean` — Enable governed session controls
-- `profile?: string` — Saved login profile (takes precedence over `persona`)
-- `priority?: 'low' | 'normal' | 'high'` — Queue priority
-- `policy?: { allowedHosts?, humanHosts?, region?, redactRecording? }` — Session policy
-- `readyTimeoutMs?: number` — Wait budget for a starting browser to connect
+- `captcha?: 'auto' | 'off'`, Automatically solve CAPTCHAs on navigation
+- `queueMs?: number`, Wait duration for fleet capacity (ms)
+- `budgetUsd?: number`, Enforce budget limit for session
+- `idempotencyKey?: string`, Safe retry token
+- `governed?: boolean`, Enable governed session controls
+- `profile?: string`, Saved login profile (takes precedence over `persona`)
+- `priority?: 'low' | 'normal' | 'high'`, Queue priority
+- `policy?: { allowedHosts?, humanHosts?, region?, redactRecording? }`, Session policy
+- `readyTimeoutMs?: number`, Wait budget for a starting browser to connect
 
 ### 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 |
+| `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`)
 
 `oya.profiles` exposes the same methods as `oya.personas`; the persona name remains available for existing integrations.
 
-| Method | Description |
-|:---|:---|
-| `create({ name?, prefs?, proxy?, maxConcurrent? })` | Create new deterministic device identity |
-| `list()` | List all saved personas and active concurrency |
-| `get(id)` | Get persona profile details |
-| `update(id, changes)` | Update name, concurrency limit, or proxy geo |
-| `clone(id, options)` | Create fresh persona with same device traits but empty cookie jar |
-| `preview(prefs)` | Preview generated hardware fingerprint before creating |
-| `options()` | Available platforms, timezones, and valid locales |
-| `pinProxy(id, proxyId)` | Bind persona permanently to a residential proxy exit node |
-| `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 |
+| Method                                              | Description                                                       |
+| :-------------------------------------------------- | :---------------------------------------------------------------- |
+| `create({ name?, prefs?, proxy?, maxConcurrent? })` | Create new deterministic device identity                          |
+| `list()`                                            | List all saved personas and active concurrency                    |
+| `get(id)`                                           | Get persona profile details                                       |
+| `update(id, changes)`                               | Update name, concurrency limit, or proxy geo                      |
+| `clone(id, options)`                                | Create fresh persona with same device traits but empty cookie jar |
+| `preview(prefs)`                                    | Preview generated hardware fingerprint before creating            |
+| `options()`                                         | Available platforms, timezones, and valid locales                 |
+| `pinProxy(id, proxyId)`                             | Bind persona permanently to a residential proxy exit node         |
+| `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                                    |
 
 ### Proxies (`oya.proxies`)
 
-| Method | Description |
-|:---|:---|
-| `create({ url, label?, geo?, kind?, maxPersonas? })` | Add a proxy from your vendor. Credentials are encrypted and never returned |
-| `list()` | Your proxies and shared ones, with exit IP, health and how many personas use each |
-| `check()` | Dial every proxy and record its real exit IP |
-| `remove(id)` | Delete a proxy and unpin the personas on it |
+| Method                                               | Description                                                                       |
+| :--------------------------------------------------- | :-------------------------------------------------------------------------------- |
+| `create({ url, label?, geo?, kind?, maxPersonas? })` | Add a proxy from your vendor. Credentials are encrypted and never returned        |
+| `list()`                                             | Your proxies and shared ones, with exit IP, health and how many personas use each |
+| `check()`                                            | Dial every proxy and record its real exit IP                                      |
+| `remove(id)`                                         | Delete a proxy and unpin the personas on it                                       |
 
 ```ts
 const proxy = await oya.proxies.create({
-  url: "http://user:pass_session-shopper1@gate.vendor.com:7000", // one sticky session per persona
-  label: "us-shopper-1", geo: "US", kind: "residential", maxPersonas: 1,
+  url: 'http://user:pass_session-shopper1@gate.vendor.com:7000', // one sticky session per persona
+  label: 'us-shopper-1',
+  geo: 'US',
+  kind: 'residential',
+  maxPersonas: 1,
 });
 await oya.personas.pinProxy(persona.id, proxy.id);
 ```
 
 ### Durable Governance & Control (`oya.control`)
 
-| Method | Description |
-|:---|:---|
-| `overview()` | Fleet overview, spend, sessions, and active rate cards |
-| `sessions()` | List all durable sessions (including cleanup-pending) |
-| `session(id)` | Get detailed session execution state |
-| `takeover(id, 'acquire' \| 'release' \| 'resume')` | Manage human control leases |
-| `ticket(id)` | Generate single-use connection ticket for secure handoff |
-| `events(after?)` | Read audit events and a pagination cursor |
-| `createCredential(options)` | Mint scoped service credential (`viewer` / `operator` / `administrator`) |
-| `createWebhook(url, types)` | Register HMAC-signed webhook for fleet lifecycle events |
+| Method                                             | Description                                                              |
+| :------------------------------------------------- | :----------------------------------------------------------------------- |
+| `overview()`                                       | Fleet overview, spend, sessions, and active rate cards                   |
+| `sessions()`                                       | List all durable sessions (including cleanup-pending)                    |
+| `session(id)`                                      | Get detailed session execution state                                     |
+| `takeover(id, 'acquire' \| 'release' \| 'resume')` | Manage human control leases                                              |
+| `ticket(id)`                                       | Generate single-use connection ticket for secure handoff                 |
+| `events(after?)`                                   | Read audit events and a pagination cursor                                |
+| `createCredential(options)`                        | Mint scoped service credential (`viewer` / `operator` / `administrator`) |
+| `createWebhook(url, types)`                        | Register HMAC-signed webhook for fleet lifecycle events                  |
 
 ---
 
@@ -502,11 +509,11 @@ await oya.personas.pinProxy(persona.id, proxy.id);
 API error responses and failed browser commands throw `OyaError`. Network failures, request timeouts, and configuration errors may throw other error types:
 
 ```ts
-import { Oya, OyaError } from "@oya-ai/browser";
+import { Oya, OyaError } from '@oya-ai/browser';
 
 try {
   const oya = new Oya();
-  await oya.browser.start({ persona: "invalid-id" });
+  await oya.browser.start({ persona: 'invalid-id' });
 } catch (err) {
   if (err instanceof OyaError) {
     console.error(`Oya API Error (${err.status}):`, err.message);

package/dist/index.cjs

@@ -45,8 +45,30 @@ var OyaError = class extends Error {
   }
 };
 
+// src/cli-config.ts
+var node = () => globalThis.process;
+function builtin(name) {
+  const get = node()?.getBuiltinModule;
+  return typeof get === "function" ? get.call(node(), name) ?? null : null;
+}
+function configFile() {
+  const os = builtin("node:os");
+  const home = node()?.env?.OYA_CONFIG_HOME || (os ? `${os.homedir()}/.oya` : null);
+  return home ? `${home}/config.json` : null;
+}
+function savedConfig() {
+  try {
+    const fs = builtin("node:fs");
+    const file2 = configFile();
+    if (!fs || !file2 || !fs.existsSync(file2)) return {};
+    return JSON.parse(fs.readFileSync(file2, "utf8"));
+  } catch {
+    return {};
+  }
+}
+
 // src/constants.ts
-var DEFAULT_BASE_URL = "https://browser.getoya.ai";
+var DEFAULT_BASE_URL = "https://oyabrowser.com";
 var DEFAULT_TIMEOUT_MS = 6e4;
 var START_TIMEOUT_MS = 12e4;
 var READY_TIMEOUT_MS = 12e4;
@@ -95,10 +117,31 @@ var Http = class {
   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 init = requestInit(method, body, timeoutMs, { Authorization: `Bearer ${this.apiKey}`, ...headers });
-    return readAnswer(await this.fetchImpl(`${this.baseUrl}${path}`, init), `${method} ${path}`, this.baseUrl);
+    const res = await this.send(`${this.baseUrl}${path}`, this.init(method, body, timeoutMs, headers), timeoutMs);
+    return readAnswer(res, `${method} ${path}`, this.baseUrl);
+  }
+  /** The fetch options for one call, with this client's key on them. */
+  init(method, body, timeoutMs, headers) {
+    return requestInit(method, body, timeoutMs, { Authorization: `Bearer ${this.apiKey}`, ...headers });
+  }
+  /**
+   * fetch's own failures say only "fetch failed" or "The operation was
+   * aborted", which leaves a reader guessing at the address, the port and
+   * whether anything is listening. Say which it was.
+   */
+  async send(url, init, timeoutMs) {
+    try {
+      return await this.fetchImpl(url, init);
+    } catch (err) {
+      throw new OyaError(unreachable(this.baseUrl, timeoutMs, err), 0, { error: String(err?.message) });
+    }
   }
 };
+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?`;
+}
 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);
@@ -125,13 +168,12 @@ function failure(call2, status, payload, baseUrl) {
 }
 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 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 fetchImpl = options.fetch || globalThis.fetch;
-  if (!fetchImpl) throw new Error("No fetch available \u2014 pass { fetch } or use Node 18+.");
+  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));
 }
 
@@ -231,10 +273,8 @@ var Browser = class {
   constructor(http, info, autoCaptcha) {
     this.http = http;
     this.autoCaptcha = autoCaptcha;
-    this.id = info.id;
-    this.provider = info.provider;
-    this.persona = info.persona;
-    this.cdpUrl = info.cdpUrl;
+    ({ id: this.id, provider: this.provider, persona: this.persona, cdpUrl: this.cdpUrl } = info);
+    this.reused = info.reused === true;
   }
   http;
   autoCaptcha;
@@ -246,6 +286,8 @@ var Browser = class {
   persona;
   /** Point Playwright, Puppeteer or browser-use here. */
   cdpUrl;
+  /** True when `start()` handed over a browser that was already running, such as the desktop app. */
+  reused;
   /** Runs one browser command; a command that ran and failed throws. */
   async command(action, params = {}, timeoutMs) {
     const path = `/api/browsers/${this.id}/command`;
@@ -397,7 +439,7 @@ var Browser = class {
   /**
    * The SSE stream of JPEG frames, for embedding in your own UI. EventSource
    * cannot set headers, so the URL carries a connection ticket: single use,
-   * 60 seconds. Mint one per viewer — the first connection spends it.
+   * 60 seconds. Mint one per viewer, the first connection spends it.
    */
   async liveStreamUrl() {
     const path = `/api/control/sessions/${encodeURIComponent(this.id)}/ticket`;
@@ -433,13 +475,14 @@ var Browser = class {
    * CDP session is handed back to its provider, a desktop browser disconnects.
    */
   stop() {
+    if (this.reused) return Promise.resolve({ id: this.id, ok: true, reused: true });
     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]() {
     await this.stop();
   }
-  /** @deprecated use stop() — close() only dropped the socket, and a cloud browser redialled. */
+  /** @deprecated use stop(), close() only dropped the socket, and a cloud browser redialled. */
   async close() {
     await this.stop();
   }
@@ -606,11 +649,11 @@ var identityCalls = (http) => ({
   /** One persona. */
   get: (id) => http().request("GET", `/api/personas/${id}`),
   /**
-   * Create an identity. The device — platform, timezone, locale — is chosen
+   * 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. */
+  /** 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)

package/dist/index.d.cts

@@ -32,16 +32,19 @@ interface StartOptions {
     /**
      * 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
+     *   '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. */
+    /**
+     * Required only for the 'cdp' provider: the CDP WebSocket URL, or the plain
+     * `http://localhost:9222` Chrome prints for `--remote-debugging-port`.
+     */
     wsUrl?: string;
     /** A label for the fleet listing. */
     name?: string;
@@ -62,6 +65,8 @@ interface StartResult {
     cdpUrl?: string;
     /** Anything the server wants the caller to know about this start. */
     note?: string;
+    /** True when this browser was already running and was handed over rather than started. */
+    reused?: boolean;
 }
 /** One element on the page, numbered by `analyze()`. */
 interface Element {
@@ -212,6 +217,8 @@ interface StopResult {
     sandboxRemoved?: boolean | null;
     /** Why it did not stop. */
     error?: string;
+    /** True when nothing was stopped because the browser was only borrowed. */
+    reused?: boolean;
 }
 /** One browser in the fleet listing. */
 interface BrowserInfo {
@@ -274,7 +281,7 @@ type CaptchaSolver = 'capsolver' | '2captcha' | '';
 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. */
+    /** The credential for whichever `llm_provider` is set, the field name is shared. */
     openai_api_key?: string | null;
     /** Only honoured alongside this key's own `openai_api_key`. */
     openai_base_url?: string | null;
@@ -360,7 +367,7 @@ interface Playbook {
     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. */
+    /** 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;
@@ -629,7 +636,7 @@ interface PersonaInfo {
  * persona-wide default.
  *
  * `gmail` and `graph` read the code straight out of a mailbox. `email` and `sms`
- * poll an endpoint you host — set `x-oya-received-at` on its response (epoch ms)
+ * poll an endpoint you host, set `x-oya-received-at` on its response (epoch ms)
  * and a code from a previous run will never be reused.
  *
  * The code is pulled out of the message by your own configured LLM, because
@@ -794,7 +801,7 @@ interface ControlOverview {
 interface OyaOptions {
     /** Defaults to OYA_API_KEY. */
     apiKey?: string;
-    /** Defaults to OYA_BASE_URL, then https://browser.getoya.ai. */
+    /** Defaults to OYA_BASE_URL, then https://oyabrowser.com. */
     baseUrl?: string;
     /** Per-request timeout. Navigation gets its own, longer budget. */
     timeoutMs?: number;
@@ -812,6 +819,14 @@ declare class Http {
     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 fetch options for one call, with this client's key on them. */
+    private init;
+    /**
+     * fetch's own failures say only "fetch failed" or "The operation was
+     * aborted", which leaves a reader guessing at the address, the port and
+     * whether anything is listening. Say which it was.
+     */
+    private send;
 }
 
 /**
@@ -1086,7 +1101,7 @@ declare class Run {
 /**
  * One running browser.
  *
- * Element ids come from `analyze()` and are only valid until the page changes —
+ * Element ids come from `analyze()` and are only valid until the page changes,
  * the same contract the agent tools use. `click(13)` after a navigation is a
  * bug; call `analyze()` again.
  */
@@ -1101,6 +1116,8 @@ declare class Browser {
     readonly persona: string;
     /** Point Playwright, Puppeteer or browser-use here. */
     readonly cdpUrl?: string;
+    /** True when `start()` handed over a browser that was already running, such as the desktop app. */
+    readonly reused: boolean;
     /** 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. */
@@ -1191,7 +1208,7 @@ declare class Browser {
     /**
      * The SSE stream of JPEG frames, for embedding in your own UI. EventSource
      * cannot set headers, so the URL carries a connection ticket: single use,
-     * 60 seconds. Mint one per viewer — the first connection spends it.
+     * 60 seconds. Mint one per viewer, the first connection spends it.
      */
     liveStreamUrl(): Promise<string>;
     /**
@@ -1217,7 +1234,7 @@ declare class Browser {
     stop(): Promise<StopResult>;
     /** `await using browser = await oya.browser.start()` stops it however the block exits, errors included. */
     [Symbol.asyncDispose](): Promise<void>;
-    /** @deprecated use stop() — close() only dropped the socket, and a cloud browser redialled. */
+    /** @deprecated use stop(), close() only dropped the socket, and a cloud browser redialled. */
     close(): Promise<void>;
 }
 
@@ -1227,7 +1244,7 @@ declare class Browser {
  *   await browser.ask('Attach my resume', { data: { resume: await file('./cv.pdf') } });
  *
  * The bytes ride inline in the run request, so the agent's `upload_file` tool can put
- * them into a page's file input. `secrets` cannot hold one — a file is never typed
+ * them into a page's file input. `secrets` cannot hold one, a file is never typed
  * through a placeholder, so there is nothing to hide.
  */
 

package/dist/index.d.ts

@@ -32,16 +32,19 @@ interface StartOptions {
     /**
      * 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
+     *   '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. */
+    /**
+     * Required only for the 'cdp' provider: the CDP WebSocket URL, or the plain
+     * `http://localhost:9222` Chrome prints for `--remote-debugging-port`.
+     */
     wsUrl?: string;
     /** A label for the fleet listing. */
     name?: string;
@@ -62,6 +65,8 @@ interface StartResult {
     cdpUrl?: string;
     /** Anything the server wants the caller to know about this start. */
     note?: string;
+    /** True when this browser was already running and was handed over rather than started. */
+    reused?: boolean;
 }
 /** One element on the page, numbered by `analyze()`. */
 interface Element {
@@ -212,6 +217,8 @@ interface StopResult {
     sandboxRemoved?: boolean | null;
     /** Why it did not stop. */
     error?: string;
+    /** True when nothing was stopped because the browser was only borrowed. */
+    reused?: boolean;
 }
 /** One browser in the fleet listing. */
 interface BrowserInfo {
@@ -274,7 +281,7 @@ type CaptchaSolver = 'capsolver' | '2captcha' | '';
 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. */
+    /** The credential for whichever `llm_provider` is set, the field name is shared. */
     openai_api_key?: string | null;
     /** Only honoured alongside this key's own `openai_api_key`. */
     openai_base_url?: string | null;
@@ -360,7 +367,7 @@ interface Playbook {
     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. */
+    /** 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;
@@ -629,7 +636,7 @@ interface PersonaInfo {
  * persona-wide default.
  *
  * `gmail` and `graph` read the code straight out of a mailbox. `email` and `sms`
- * poll an endpoint you host — set `x-oya-received-at` on its response (epoch ms)
+ * poll an endpoint you host, set `x-oya-received-at` on its response (epoch ms)
  * and a code from a previous run will never be reused.
  *
  * The code is pulled out of the message by your own configured LLM, because
@@ -794,7 +801,7 @@ interface ControlOverview {
 interface OyaOptions {
     /** Defaults to OYA_API_KEY. */
     apiKey?: string;
-    /** Defaults to OYA_BASE_URL, then https://browser.getoya.ai. */
+    /** Defaults to OYA_BASE_URL, then https://oyabrowser.com. */
     baseUrl?: string;
     /** Per-request timeout. Navigation gets its own, longer budget. */
     timeoutMs?: number;
@@ -812,6 +819,14 @@ declare class Http {
     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 fetch options for one call, with this client's key on them. */
+    private init;
+    /**
+     * fetch's own failures say only "fetch failed" or "The operation was
+     * aborted", which leaves a reader guessing at the address, the port and
+     * whether anything is listening. Say which it was.
+     */
+    private send;
 }
 
 /**
@@ -1086,7 +1101,7 @@ declare class Run {
 /**
  * One running browser.
  *
- * Element ids come from `analyze()` and are only valid until the page changes —
+ * Element ids come from `analyze()` and are only valid until the page changes,
  * the same contract the agent tools use. `click(13)` after a navigation is a
  * bug; call `analyze()` again.
  */
@@ -1101,6 +1116,8 @@ declare class Browser {
     readonly persona: string;
     /** Point Playwright, Puppeteer or browser-use here. */
     readonly cdpUrl?: string;
+    /** True when `start()` handed over a browser that was already running, such as the desktop app. */
+    readonly reused: boolean;
     /** 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. */
@@ -1191,7 +1208,7 @@ declare class Browser {
     /**
      * The SSE stream of JPEG frames, for embedding in your own UI. EventSource
      * cannot set headers, so the URL carries a connection ticket: single use,
-     * 60 seconds. Mint one per viewer — the first connection spends it.
+     * 60 seconds. Mint one per viewer, the first connection spends it.
      */
     liveStreamUrl(): Promise<string>;
     /**
@@ -1217,7 +1234,7 @@ declare class Browser {
     stop(): Promise<StopResult>;
     /** `await using browser = await oya.browser.start()` stops it however the block exits, errors included. */
     [Symbol.asyncDispose](): Promise<void>;
-    /** @deprecated use stop() — close() only dropped the socket, and a cloud browser redialled. */
+    /** @deprecated use stop(), close() only dropped the socket, and a cloud browser redialled. */
     close(): Promise<void>;
 }
 
@@ -1227,7 +1244,7 @@ declare class Browser {
  *   await browser.ask('Attach my resume', { data: { resume: await file('./cv.pdf') } });
  *
  * The bytes ride inline in the run request, so the agent's `upload_file` tool can put
- * them into a page's file input. `secrets` cannot hold one — a file is never typed
+ * them into a page's file input. `secrets` cannot hold one, a file is never typed
  * through a placeholder, so there is nothing to hide.
  */
 

package/dist/index.js

@@ -13,8 +13,30 @@ var OyaError = class extends Error {
   }
 };
 
+// src/cli-config.ts
+var node = () => globalThis.process;
+function builtin(name) {
+  const get = node()?.getBuiltinModule;
+  return typeof get === "function" ? get.call(node(), name) ?? null : null;
+}
+function configFile() {
+  const os = builtin("node:os");
+  const home = node()?.env?.OYA_CONFIG_HOME || (os ? `${os.homedir()}/.oya` : null);
+  return home ? `${home}/config.json` : null;
+}
+function savedConfig() {
+  try {
+    const fs = builtin("node:fs");
+    const file2 = configFile();
+    if (!fs || !file2 || !fs.existsSync(file2)) return {};
+    return JSON.parse(fs.readFileSync(file2, "utf8"));
+  } catch {
+    return {};
+  }
+}
+
 // src/constants.ts
-var DEFAULT_BASE_URL = "https://browser.getoya.ai";
+var DEFAULT_BASE_URL = "https://oyabrowser.com";
 var DEFAULT_TIMEOUT_MS = 6e4;
 var START_TIMEOUT_MS = 12e4;
 var READY_TIMEOUT_MS = 12e4;
@@ -63,10 +85,31 @@ var Http = class {
   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 init = requestInit(method, body, timeoutMs, { Authorization: `Bearer ${this.apiKey}`, ...headers });
-    return readAnswer(await this.fetchImpl(`${this.baseUrl}${path}`, init), `${method} ${path}`, this.baseUrl);
+    const res = await this.send(`${this.baseUrl}${path}`, this.init(method, body, timeoutMs, headers), timeoutMs);
+    return readAnswer(res, `${method} ${path}`, this.baseUrl);
+  }
+  /** The fetch options for one call, with this client's key on them. */
+  init(method, body, timeoutMs, headers) {
+    return requestInit(method, body, timeoutMs, { Authorization: `Bearer ${this.apiKey}`, ...headers });
+  }
+  /**
+   * fetch's own failures say only "fetch failed" or "The operation was
+   * aborted", which leaves a reader guessing at the address, the port and
+   * whether anything is listening. Say which it was.
+   */
+  async send(url, init, timeoutMs) {
+    try {
+      return await this.fetchImpl(url, init);
+    } catch (err) {
+      throw new OyaError(unreachable(this.baseUrl, timeoutMs, err), 0, { error: String(err?.message) });
+    }
   }
 };
+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?`;
+}
 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);
@@ -93,13 +136,12 @@ function failure(call2, status, payload, baseUrl) {
 }
 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 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 fetchImpl = options.fetch || globalThis.fetch;
-  if (!fetchImpl) throw new Error("No fetch available \u2014 pass { fetch } or use Node 18+.");
+  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));
 }
 
@@ -199,10 +241,8 @@ var Browser = class {
   constructor(http, info, autoCaptcha) {
     this.http = http;
     this.autoCaptcha = autoCaptcha;
-    this.id = info.id;
-    this.provider = info.provider;
-    this.persona = info.persona;
-    this.cdpUrl = info.cdpUrl;
+    ({ id: this.id, provider: this.provider, persona: this.persona, cdpUrl: this.cdpUrl } = info);
+    this.reused = info.reused === true;
   }
   http;
   autoCaptcha;
@@ -214,6 +254,8 @@ var Browser = class {
   persona;
   /** Point Playwright, Puppeteer or browser-use here. */
   cdpUrl;
+  /** True when `start()` handed over a browser that was already running, such as the desktop app. */
+  reused;
   /** Runs one browser command; a command that ran and failed throws. */
   async command(action, params = {}, timeoutMs) {
     const path = `/api/browsers/${this.id}/command`;
@@ -365,7 +407,7 @@ var Browser = class {
   /**
    * The SSE stream of JPEG frames, for embedding in your own UI. EventSource
    * cannot set headers, so the URL carries a connection ticket: single use,
-   * 60 seconds. Mint one per viewer — the first connection spends it.
+   * 60 seconds. Mint one per viewer, the first connection spends it.
    */
   async liveStreamUrl() {
     const path = `/api/control/sessions/${encodeURIComponent(this.id)}/ticket`;
@@ -401,13 +443,14 @@ var Browser = class {
    * CDP session is handed back to its provider, a desktop browser disconnects.
    */
   stop() {
+    if (this.reused) return Promise.resolve({ id: this.id, ok: true, reused: true });
     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]() {
     await this.stop();
   }
-  /** @deprecated use stop() — close() only dropped the socket, and a cloud browser redialled. */
+  /** @deprecated use stop(), close() only dropped the socket, and a cloud browser redialled. */
   async close() {
     await this.stop();
   }
@@ -574,11 +617,11 @@ var identityCalls = (http) => ({
   /** One persona. */
   get: (id) => http().request("GET", `/api/personas/${id}`),
   /**
-   * Create an identity. The device — platform, timezone, locale — is chosen
+   * 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. */
+  /** 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)

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@oya-ai/browser",
-  "version": "1.0.103",
-  "description": "Rotate thousands of browsers behind one API — personas, proxies, stealth, CAPTCHA and MFA.",
+  "version": "1.0.105",
+  "description": "Rotate thousands of browsers behind one API, personas, proxies, stealth, CAPTCHA and MFA.",
   "license": "MIT",
-  "homepage": "https://browser.getoya.ai",
+  "homepage": "https://oyabrowser.com",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/OyadotAI/oya-browser.git",