@oya-ai/browser 1.0.125 → 1.0.129

package/README.md

@@ -50,6 +50,18 @@ Node.js 20 or newer; the examples are ES modules. `OYA_BASE_URL` points at a sel
 control plane. On Node.js 24+, `await using browser = await oya.browser.start()` stops it
 when the scope exits, errors included.
 
+
+## For AI agents
+
+No key yet? Get your own, and use your person's own browser with their logins:
+
+```js
+await Oya.signup({ email: 'person@example.com' }); // saved to ~/.oya/config.json
+const browser = await new Oya().desktop.connect(); // pairs the Oya desktop app
+```
+
+Written for agents: [oyabrowser.com/llms.txt](https://oyabrowser.com/llms.txt).
+
 ## Portal automation: record once, replay with new inputs
 
 This example adapts the portal-automation project's workflow: reuse a persona, attach to an existing browser or start one, run a prompt the first time, then replay its saved playbook. The portal, workflow names, and request values below are fictional. Supply your own test portal and credentials through environment variables; adapt the task to its actual pages.

package/dist/index.cjs

@@ -70,6 +70,9 @@ var Status = {
   /** A browser did not come up in time. */
   GATEWAY_TIMEOUT: 504
 };
+var DESKTOP_PROVIDER = "oya-desktop";
+var DESKTOP_TIMEOUT_MS = 3e5;
+var DESKTOP_DOWNLOAD_URL = "https://oyabrowser.com/#download";
 
 // src/errors.ts
 var OyaError = class extends Error {
@@ -111,6 +114,18 @@ function savedConfig() {
     return {};
   }
 }
+var PRIVATE_FILE = 384;
+var JSON_INDENT = 2;
+function saveKey(apiKey, baseUrl) {
+  const fs = builtin("node:fs");
+  const file2 = configFile();
+  if (!fs || !file2 || savedConfig().apiKey) return false;
+  fs.mkdirSync(file2.slice(0, file2.lastIndexOf("/")), { recursive: true });
+  fs.writeFileSync(file2, JSON.stringify({ ...savedConfig(), apiKey, baseUrl }, null, JSON_INDENT), {
+    mode: PRIVATE_FILE
+  });
+  return true;
+}
 
 // src/client.ts
 var OPTIONS_ORIGIN = { apiKeyFrom: "the apiKey option", baseUrlFrom: "the baseUrl option", savedKey: false };
@@ -855,6 +870,83 @@ async function assertNotEnded(checks, id) {
   }
 }
 
+// src/api/agent.ts
+var NO_KEY = "signup";
+var solves = (crypto, challenge, nonce, zeros) => crypto.createHash("sha256").update(challenge + nonce).digest("hex").startsWith(zeros);
+function solve({ challenge, difficulty }) {
+  const crypto = builtin("node:crypto");
+  if (!crypto) throw new Error("Oya.signup() needs Node 22.3 or newer.");
+  const zeros = "0".repeat(difficulty);
+  let nonce = 0;
+  while (!solves(crypto, challenge, nonce, zeros)) nonce++;
+  return String(nonce);
+}
+async function signup(options) {
+  const http = createHttp({ baseUrl: options.baseUrl, fetch: options.fetch, apiKey: NO_KEY });
+  const puzzle = await http.request("GET", "/api/auth/agent/challenge");
+  const body = { email: options.email, challenge: puzzle.challenge, nonce: solve(puzzle) };
+  const answer = await http.request("POST", "/api/auth/agent/signup", body);
+  const saved = options.save !== false && saveKey(answer.api_key, http.baseUrl);
+  return { apiKey: answer.api_key, claimUrl: answer.claim_url, cloudBrowsers: answer.cloud_browsers, saved };
+}
+var desktopOf = (all, persona) => all.find(
+  (b) => b.provider === DESKTOP_PROVIDER && b.health !== "dead" && (!persona || b.persona === persona || b.personaName === persona)
+);
+async function pairingLink(http, persona) {
+  const { code } = await http.request("POST", "/api/pairing", {
+    persona
+  });
+  const server = `${http.baseUrl.replace(/^http/, "ws")}/ws`;
+  return `oya://connect?code=${encodeURIComponent(code)}&server=${encodeURIComponent(server)}`;
+}
+var OPENERS = {
+  darwin: ["open"],
+  linux: ["xdg-open"],
+  win32: ["rundll32", "url.dll,FileProtocolHandler"]
+};
+function openLink(link) {
+  const platform = globalThis.process?.platform ?? "";
+  const cp = builtin("node:child_process");
+  if (!cp || !Object.hasOwn(OPENERS, platform)) return;
+  const [cmd, ...args] = OPENERS[platform];
+  const child = cp.spawn(cmd, [...args, link], { detached: true, stdio: "ignore" });
+  child.on("error", () => {
+  });
+  child.unref();
+}
+async function waitForDesktop(list, link, timeoutMs, persona) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const found = desktopOf(await list(), persona);
+    if (found) return found;
+    await new Promise((r) => setTimeout(r, READY_POLL_MS));
+  }
+  const how = `Install it from ${DESKTOP_DOWNLOAD_URL} if needed, then open ${link} and click Connect.`;
+  throw new OyaError(`The Oya desktop app did not connect. ${how}`, Status.GATEWAY_TIMEOUT, { link });
+}
+async function handleOn(http, id) {
+  const found = await http.request("GET", `/api/browsers/${segment(id)}`);
+  const started = { id, provider: DESKTOP_PROVIDER, persona: found.persona || "default", cdpUrl: found.cdpUrl };
+  return new Browser(http, { ...started, status: "ready", reused: true }, false);
+}
+var desktopApi = (http, list) => ({
+  /**
+   * The person's own desktop browser, signed in to their sites. When it is not
+   * connected yet this pairs it: it opens a link, the person clicks Connect in
+   * the app (with "Import my logins" ticked, their Chrome logins come along),
+   * and this waits until it is up. With `persona`, a running app signed in as
+   * another persona is switched the same way: the link reconnects it as this one.
+   */
+  connect: async (options = {}) => {
+    const running = desktopOf(await list(), options.persona);
+    if (running) return handleOn(http(), running.id);
+    const link = await pairingLink(http(), options.persona);
+    if (options.open !== false) openLink(link);
+    const found = await waitForDesktop(list, link, options.timeoutMs ?? DESKTOP_TIMEOUT_MS, options.persona);
+    return handleOn(http(), found.id);
+  }
+});
+
 // src/file.ts
 var MAX_FILE_BYTES = MAX_FILE_MB * BYTES_PER_MB;
 var NODE_FS = "node:fs/promises";
@@ -934,6 +1026,18 @@ var Oya = class {
     () => this.http,
     (id, timeoutMs) => this.waitUntilConnected(id, timeoutMs)
   );
+  /** The person's own desktop browser, with their logins: `await oya.desktop.connect()` pairs it when it is not up yet. */
+  desktop = desktopApi(
+    () => this.http,
+    () => this.browser.list()
+  );
+  /**
+   * An agent's own key, with no person or dashboard: `await Oya.signup({ email })`.
+   * Saved to ~/.oya/config.json, so a later `new Oya()` finds it.
+   */
+  static signup(options) {
+    return signup(options);
+  }
   /** Durable operational controls, including disconnected and cleanup-pending sessions. */
   control = controlApi(() => this.http);
   /** Playbooks saved with `browser.toPlaybook()`. */

package/dist/index.d.cts

@@ -272,7 +272,9 @@ type LlmProvider = 'openai' | 'anthropic'
  | 'gemini'
 /** Gemini Enterprise, ex-Vertex AI. Express mode by default; set `openai_base_url` to a
  *  project-scoped `.../endpoints/openapi` endpoint to use an enterprise project. */
- | 'vertex';
+ | 'vertex'
+/** OpenRouter: one key for many vendors' models, named vendor/model (e.g. 'anthropic/claude-sonnet-5'). */
+ | 'openrouter';
 /**
  * Which runtime this key's `'oya-cloud'` browsers run on. `'docker'` and `'k8s'`
  * run on the deployment's own daemon or cluster, exactly as its operator set them up;
@@ -422,6 +424,30 @@ interface Config extends Omit<ConfigUpdate, 'llm_provider' | 'browser_provider'
         /** Whether those fields are set. */
         configured: boolean;
     }>;
+    /** Every LLM provider and the models it offers; the console, desktop app and CLI build their pickers from this. */
+    llm_catalog: LlmCatalogEntry[];
+}
+/** One LLM provider in `Config.llm_catalog`. */
+interface LlmCatalogEntry {
+    /** The `llm_provider` value. */
+    id: LlmProvider;
+    /** Its name. */
+    label: string;
+    /** How its key looks. */
+    hint: string;
+    /** Where to get a key. */
+    keysUrl: string;
+    /** Its endpoint. */
+    base: string;
+    /** The model a key runs on when it sets no `chat_model`. */
+    model: string;
+    /** The models to offer (OpenRouter's is its live list); any other id works as `chat_model` too. */
+    models: Array<{
+        /** The id the provider's API expects. */
+        id: string;
+        /** A readable name. */
+        label: string;
+    }>;
 }
 
 /** A failed API call or browser command. */
@@ -918,6 +944,37 @@ interface OyaOptions {
     /** A fetch to use instead of the global one, for tests, proxies or old runtimes. */
     fetch?: typeof globalThis.fetch;
 }
+/** What `Oya.signup()` takes. */
+interface SignupOptions {
+    /** The email of the person the agent works for. They get the claim link that unlocks cloud browsers. */
+    email: string;
+    /** Defaults to OYA_BASE_URL, then https://oyabrowser.com. */
+    baseUrl?: string;
+    /** Save the key to ~/.oya/config.json, where `new Oya()` finds it later. On by default; a key already saved there is never replaced. */
+    save?: boolean;
+    /** A fetch to use instead of the global one. */
+    fetch?: typeof globalThis.fetch;
+}
+/** A new key from `Oya.signup()`. */
+interface Signup {
+    /** The key. Shown once; keep it secret. */
+    apiKey: string;
+    /** Send this to the person: opening it while signed in to Oya claims the key and unlocks cloud browsers. */
+    claimUrl: string;
+    /** Whether cloud browsers work yet (false until the key is claimed). */
+    cloudBrowsers: boolean;
+    /** Whether the key was saved to ~/.oya/config.json. */
+    saved: boolean;
+}
+/** What `oya.desktop.connect()` takes. */
+interface DesktopOptions {
+    /** The persona (id or name) the desktop app signs in as, switching a running app that is on another one. Defaults to the key's own. */
+    persona?: string;
+    /** Open the pairing link on this machine (the default). Off, the link is only in the error when the app does not connect. */
+    open?: boolean;
+    /** How long to wait for the person to click Connect in the app. Five minutes by default. */
+    timeoutMs?: number;
+}
 
 /** Where the key and the address came from, so a message names the one to fix. */
 interface Origin {
@@ -1412,6 +1469,15 @@ declare class Oya {
         stop: (ids: string[] | "all") => Promise<StopManyResult>;
         stopAll: () => Promise<number>;
     };
+    /** The person's own desktop browser, with their logins: `await oya.desktop.connect()` pairs it when it is not up yet. */
+    readonly desktop: {
+        connect: (options?: DesktopOptions) => Promise<Browser>;
+    };
+    /**
+     * An agent's own key, with no person or dashboard: `await Oya.signup({ email })`.
+     * Saved to ~/.oya/config.json, so a later `new Oya()` finds it.
+     */
+    static signup(options: SignupOptions): Promise<Signup>;
     /** Durable operational controls, including disconnected and cleanup-pending sessions. */
     readonly control: {
         createWebhook: (url: string, types?: string[]) => Promise<Webhook>;
@@ -1513,4 +1579,4 @@ declare class Oya {
     private waitUntilConnected;
 }
 
-export { type Activity, type Analysis, type AnalyzeOptions, type AttentionRequest, type Block, Browser, type BrowserDetail, type BrowserInfo, type CaptchaResult, type CaptchaSolver, type Config, type ConfigUpdate, type ControlCredential, type ControlEvent, type ControlOverview, type ControlRole, type ControlSession, type Cookie, type CookieFormat, type EcsAuth, type EcsConfig, type Element, type FileValue, type Fingerprint, type Health, type HumanInputAction, type LlmProvider, MAX_FILE_BYTES, type MfaConfig, type MfaResult, Oya, OyaError, type OyaOptions, type PageFormat, type PersonaInfo, type PersonaPrefs, type PlayResult, type Playbook, type PlaybookSummary, type ProjectSettings, type Provider, type ProxyCreate, type ProxyInfo, type RecoverOptions, Run, type RunData, type RunInfo, type RunResult, type SandboxRuntime, type SiteCredentials, type StartOptions, type StartResult, type StopResult, type SubmitOptions, Oya as default, file };
+export { type Activity, type Analysis, type AnalyzeOptions, type AttentionRequest, type Block, Browser, type BrowserDetail, type BrowserInfo, type CaptchaResult, type CaptchaSolver, type Config, type ConfigUpdate, type ControlCredential, type ControlEvent, type ControlOverview, type ControlRole, type ControlSession, type Cookie, type CookieFormat, type DesktopOptions, type EcsAuth, type EcsConfig, type Element, type FileValue, type Fingerprint, type Health, type HumanInputAction, type LlmCatalogEntry, type LlmProvider, MAX_FILE_BYTES, type MfaConfig, type MfaResult, Oya, OyaError, type OyaOptions, type PageFormat, type PersonaInfo, type PersonaPrefs, type PlayResult, type Playbook, type PlaybookSummary, type ProjectSettings, type Provider, type ProxyCreate, type ProxyInfo, type RecoverOptions, Run, type RunData, type RunInfo, type RunResult, type SandboxRuntime, type Signup, type SignupOptions, type SiteCredentials, type StartOptions, type StartResult, type StopResult, type SubmitOptions, Oya as default, file };

package/dist/index.d.ts

@@ -272,7 +272,9 @@ type LlmProvider = 'openai' | 'anthropic'
  | 'gemini'
 /** Gemini Enterprise, ex-Vertex AI. Express mode by default; set `openai_base_url` to a
  *  project-scoped `.../endpoints/openapi` endpoint to use an enterprise project. */
- | 'vertex';
+ | 'vertex'
+/** OpenRouter: one key for many vendors' models, named vendor/model (e.g. 'anthropic/claude-sonnet-5'). */
+ | 'openrouter';
 /**
  * Which runtime this key's `'oya-cloud'` browsers run on. `'docker'` and `'k8s'`
  * run on the deployment's own daemon or cluster, exactly as its operator set them up;
@@ -422,6 +424,30 @@ interface Config extends Omit<ConfigUpdate, 'llm_provider' | 'browser_provider'
         /** Whether those fields are set. */
         configured: boolean;
     }>;
+    /** Every LLM provider and the models it offers; the console, desktop app and CLI build their pickers from this. */
+    llm_catalog: LlmCatalogEntry[];
+}
+/** One LLM provider in `Config.llm_catalog`. */
+interface LlmCatalogEntry {
+    /** The `llm_provider` value. */
+    id: LlmProvider;
+    /** Its name. */
+    label: string;
+    /** How its key looks. */
+    hint: string;
+    /** Where to get a key. */
+    keysUrl: string;
+    /** Its endpoint. */
+    base: string;
+    /** The model a key runs on when it sets no `chat_model`. */
+    model: string;
+    /** The models to offer (OpenRouter's is its live list); any other id works as `chat_model` too. */
+    models: Array<{
+        /** The id the provider's API expects. */
+        id: string;
+        /** A readable name. */
+        label: string;
+    }>;
 }
 
 /** A failed API call or browser command. */
@@ -918,6 +944,37 @@ interface OyaOptions {
     /** A fetch to use instead of the global one, for tests, proxies or old runtimes. */
     fetch?: typeof globalThis.fetch;
 }
+/** What `Oya.signup()` takes. */
+interface SignupOptions {
+    /** The email of the person the agent works for. They get the claim link that unlocks cloud browsers. */
+    email: string;
+    /** Defaults to OYA_BASE_URL, then https://oyabrowser.com. */
+    baseUrl?: string;
+    /** Save the key to ~/.oya/config.json, where `new Oya()` finds it later. On by default; a key already saved there is never replaced. */
+    save?: boolean;
+    /** A fetch to use instead of the global one. */
+    fetch?: typeof globalThis.fetch;
+}
+/** A new key from `Oya.signup()`. */
+interface Signup {
+    /** The key. Shown once; keep it secret. */
+    apiKey: string;
+    /** Send this to the person: opening it while signed in to Oya claims the key and unlocks cloud browsers. */
+    claimUrl: string;
+    /** Whether cloud browsers work yet (false until the key is claimed). */
+    cloudBrowsers: boolean;
+    /** Whether the key was saved to ~/.oya/config.json. */
+    saved: boolean;
+}
+/** What `oya.desktop.connect()` takes. */
+interface DesktopOptions {
+    /** The persona (id or name) the desktop app signs in as, switching a running app that is on another one. Defaults to the key's own. */
+    persona?: string;
+    /** Open the pairing link on this machine (the default). Off, the link is only in the error when the app does not connect. */
+    open?: boolean;
+    /** How long to wait for the person to click Connect in the app. Five minutes by default. */
+    timeoutMs?: number;
+}
 
 /** Where the key and the address came from, so a message names the one to fix. */
 interface Origin {
@@ -1412,6 +1469,15 @@ declare class Oya {
         stop: (ids: string[] | "all") => Promise<StopManyResult>;
         stopAll: () => Promise<number>;
     };
+    /** The person's own desktop browser, with their logins: `await oya.desktop.connect()` pairs it when it is not up yet. */
+    readonly desktop: {
+        connect: (options?: DesktopOptions) => Promise<Browser>;
+    };
+    /**
+     * An agent's own key, with no person or dashboard: `await Oya.signup({ email })`.
+     * Saved to ~/.oya/config.json, so a later `new Oya()` finds it.
+     */
+    static signup(options: SignupOptions): Promise<Signup>;
     /** Durable operational controls, including disconnected and cleanup-pending sessions. */
     readonly control: {
         createWebhook: (url: string, types?: string[]) => Promise<Webhook>;
@@ -1513,4 +1579,4 @@ declare class Oya {
     private waitUntilConnected;
 }
 
-export { type Activity, type Analysis, type AnalyzeOptions, type AttentionRequest, type Block, Browser, type BrowserDetail, type BrowserInfo, type CaptchaResult, type CaptchaSolver, type Config, type ConfigUpdate, type ControlCredential, type ControlEvent, type ControlOverview, type ControlRole, type ControlSession, type Cookie, type CookieFormat, type EcsAuth, type EcsConfig, type Element, type FileValue, type Fingerprint, type Health, type HumanInputAction, type LlmProvider, MAX_FILE_BYTES, type MfaConfig, type MfaResult, Oya, OyaError, type OyaOptions, type PageFormat, type PersonaInfo, type PersonaPrefs, type PlayResult, type Playbook, type PlaybookSummary, type ProjectSettings, type Provider, type ProxyCreate, type ProxyInfo, type RecoverOptions, Run, type RunData, type RunInfo, type RunResult, type SandboxRuntime, type SiteCredentials, type StartOptions, type StartResult, type StopResult, type SubmitOptions, Oya as default, file };
+export { type Activity, type Analysis, type AnalyzeOptions, type AttentionRequest, type Block, Browser, type BrowserDetail, type BrowserInfo, type CaptchaResult, type CaptchaSolver, type Config, type ConfigUpdate, type ControlCredential, type ControlEvent, type ControlOverview, type ControlRole, type ControlSession, type Cookie, type CookieFormat, type DesktopOptions, type EcsAuth, type EcsConfig, type Element, type FileValue, type Fingerprint, type Health, type HumanInputAction, type LlmCatalogEntry, type LlmProvider, MAX_FILE_BYTES, type MfaConfig, type MfaResult, Oya, OyaError, type OyaOptions, type PageFormat, type PersonaInfo, type PersonaPrefs, type PlayResult, type Playbook, type PlaybookSummary, type ProjectSettings, type Provider, type ProxyCreate, type ProxyInfo, type RecoverOptions, Run, type RunData, type RunInfo, type RunResult, type SandboxRuntime, type Signup, type SignupOptions, type SiteCredentials, type StartOptions, type StartResult, type StopResult, type SubmitOptions, Oya as default, file };

package/dist/index.js

@@ -38,6 +38,9 @@ var Status = {
   /** A browser did not come up in time. */
   GATEWAY_TIMEOUT: 504
 };
+var DESKTOP_PROVIDER = "oya-desktop";
+var DESKTOP_TIMEOUT_MS = 3e5;
+var DESKTOP_DOWNLOAD_URL = "https://oyabrowser.com/#download";
 
 // src/errors.ts
 var OyaError = class extends Error {
@@ -79,6 +82,18 @@ function savedConfig() {
     return {};
   }
 }
+var PRIVATE_FILE = 384;
+var JSON_INDENT = 2;
+function saveKey(apiKey, baseUrl) {
+  const fs = builtin("node:fs");
+  const file2 = configFile();
+  if (!fs || !file2 || savedConfig().apiKey) return false;
+  fs.mkdirSync(file2.slice(0, file2.lastIndexOf("/")), { recursive: true });
+  fs.writeFileSync(file2, JSON.stringify({ ...savedConfig(), apiKey, baseUrl }, null, JSON_INDENT), {
+    mode: PRIVATE_FILE
+  });
+  return true;
+}
 
 // src/client.ts
 var OPTIONS_ORIGIN = { apiKeyFrom: "the apiKey option", baseUrlFrom: "the baseUrl option", savedKey: false };
@@ -823,6 +838,83 @@ async function assertNotEnded(checks, id) {
   }
 }
 
+// src/api/agent.ts
+var NO_KEY = "signup";
+var solves = (crypto, challenge, nonce, zeros) => crypto.createHash("sha256").update(challenge + nonce).digest("hex").startsWith(zeros);
+function solve({ challenge, difficulty }) {
+  const crypto = builtin("node:crypto");
+  if (!crypto) throw new Error("Oya.signup() needs Node 22.3 or newer.");
+  const zeros = "0".repeat(difficulty);
+  let nonce = 0;
+  while (!solves(crypto, challenge, nonce, zeros)) nonce++;
+  return String(nonce);
+}
+async function signup(options) {
+  const http = createHttp({ baseUrl: options.baseUrl, fetch: options.fetch, apiKey: NO_KEY });
+  const puzzle = await http.request("GET", "/api/auth/agent/challenge");
+  const body = { email: options.email, challenge: puzzle.challenge, nonce: solve(puzzle) };
+  const answer = await http.request("POST", "/api/auth/agent/signup", body);
+  const saved = options.save !== false && saveKey(answer.api_key, http.baseUrl);
+  return { apiKey: answer.api_key, claimUrl: answer.claim_url, cloudBrowsers: answer.cloud_browsers, saved };
+}
+var desktopOf = (all, persona) => all.find(
+  (b) => b.provider === DESKTOP_PROVIDER && b.health !== "dead" && (!persona || b.persona === persona || b.personaName === persona)
+);
+async function pairingLink(http, persona) {
+  const { code } = await http.request("POST", "/api/pairing", {
+    persona
+  });
+  const server = `${http.baseUrl.replace(/^http/, "ws")}/ws`;
+  return `oya://connect?code=${encodeURIComponent(code)}&server=${encodeURIComponent(server)}`;
+}
+var OPENERS = {
+  darwin: ["open"],
+  linux: ["xdg-open"],
+  win32: ["rundll32", "url.dll,FileProtocolHandler"]
+};
+function openLink(link) {
+  const platform = globalThis.process?.platform ?? "";
+  const cp = builtin("node:child_process");
+  if (!cp || !Object.hasOwn(OPENERS, platform)) return;
+  const [cmd, ...args] = OPENERS[platform];
+  const child = cp.spawn(cmd, [...args, link], { detached: true, stdio: "ignore" });
+  child.on("error", () => {
+  });
+  child.unref();
+}
+async function waitForDesktop(list, link, timeoutMs, persona) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const found = desktopOf(await list(), persona);
+    if (found) return found;
+    await new Promise((r) => setTimeout(r, READY_POLL_MS));
+  }
+  const how = `Install it from ${DESKTOP_DOWNLOAD_URL} if needed, then open ${link} and click Connect.`;
+  throw new OyaError(`The Oya desktop app did not connect. ${how}`, Status.GATEWAY_TIMEOUT, { link });
+}
+async function handleOn(http, id) {
+  const found = await http.request("GET", `/api/browsers/${segment(id)}`);
+  const started = { id, provider: DESKTOP_PROVIDER, persona: found.persona || "default", cdpUrl: found.cdpUrl };
+  return new Browser(http, { ...started, status: "ready", reused: true }, false);
+}
+var desktopApi = (http, list) => ({
+  /**
+   * The person's own desktop browser, signed in to their sites. When it is not
+   * connected yet this pairs it: it opens a link, the person clicks Connect in
+   * the app (with "Import my logins" ticked, their Chrome logins come along),
+   * and this waits until it is up. With `persona`, a running app signed in as
+   * another persona is switched the same way: the link reconnects it as this one.
+   */
+  connect: async (options = {}) => {
+    const running = desktopOf(await list(), options.persona);
+    if (running) return handleOn(http(), running.id);
+    const link = await pairingLink(http(), options.persona);
+    if (options.open !== false) openLink(link);
+    const found = await waitForDesktop(list, link, options.timeoutMs ?? DESKTOP_TIMEOUT_MS, options.persona);
+    return handleOn(http(), found.id);
+  }
+});
+
 // src/file.ts
 var MAX_FILE_BYTES = MAX_FILE_MB * BYTES_PER_MB;
 var NODE_FS = "node:fs/promises";
@@ -902,6 +994,18 @@ var Oya = class {
     () => this.http,
     (id, timeoutMs) => this.waitUntilConnected(id, timeoutMs)
   );
+  /** The person's own desktop browser, with their logins: `await oya.desktop.connect()` pairs it when it is not up yet. */
+  desktop = desktopApi(
+    () => this.http,
+    () => this.browser.list()
+  );
+  /**
+   * An agent's own key, with no person or dashboard: `await Oya.signup({ email })`.
+   * Saved to ~/.oya/config.json, so a later `new Oya()` finds it.
+   */
+  static signup(options) {
+    return signup(options);
+  }
   /** Durable operational controls, including disconnected and cleanup-pending sessions. */
   control = controlApi(() => this.http);
   /** Playbooks saved with `browser.toPlaybook()`. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oya-ai/browser",
-  "version": "1.0.125",
+  "version": "1.0.129",
   "description": "Rotate thousands of browsers behind one API, personas, proxies, stealth, CAPTCHA and MFA.",
   "license": "MIT",
   "homepage": "https://oyabrowser.com",
@@ -22,7 +22,18 @@
     "browser-use",
     "captcha",
     "fingerprint",
-    "mcp"
+    "mcp",
+    "ai-agent",
+    "agent-browser",
+    "browser-agent",
+    "agent-skills",
+    "claude-code",
+    "codex",
+    "openclaw",
+    "hermes-agent",
+    "computer-use",
+    "mcp-server",
+    "llms-txt"
   ],
   "type": "module",
   "main": "./dist/index.cjs",