@oya-ai/cli 0.1.0

package/dist/index.js

@@ -0,0 +1,861 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { spawn } from "child_process";
+
+// ../sdk/dist/index.js
+var OyaError = class extends Error {
+  status;
+  body;
+  constructor(message, status, body) {
+    super(message);
+    this.name = "OyaError";
+    this.status = status;
+    this.body = body;
+  }
+};
+var Http = class {
+  constructor(baseUrl, apiKey, timeoutMs, fetchImpl) {
+    this.baseUrl = baseUrl;
+    this.apiKey = apiKey;
+    this.timeoutMs = timeoutMs;
+    this.fetchImpl = fetchImpl;
+  }
+  baseUrl;
+  apiKey;
+  timeoutMs;
+  fetchImpl;
+  async request(method, path, body, timeoutMs = this.timeoutMs, headers = {}) {
+    const res = await this.fetchImpl(`${this.baseUrl}${path}`, {
+      method,
+      headers: {
+        Authorization: `Bearer ${this.apiKey}`,
+        ...headers,
+        ...body === void 0 ? {} : { "Content-Type": "application/json" }
+      },
+      body: body === void 0 ? void 0 : JSON.stringify(body),
+      signal: AbortSignal.timeout(timeoutMs)
+    });
+    const text = await res.text();
+    let payload;
+    try {
+      payload = text ? JSON.parse(text) : null;
+    } catch {
+      payload = text;
+    }
+    if (!res.ok) {
+      let message = payload?.error || `${method} ${path} failed (${res.status})`;
+      if (message === "Invalid API key") message += ` for ${this.baseUrl}. Check OYA_API_KEY: a value exported in your shell beats .env.`;
+      throw new OyaError(message, res.status, payload);
+    }
+    return payload;
+  }
+};
+var NAVIGATE_TIMEOUT_MS = 12e4;
+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;
+  }
+  http;
+  autoCaptcha;
+  id;
+  provider;
+  persona;
+  /** Point Playwright, Puppeteer or browser-use here. */
+  cdpUrl;
+  async command(action, params = {}, timeoutMs) {
+    const result = await this.http.request(
+      "POST",
+      `/api/browsers/${this.id}/command`,
+      { action, params },
+      timeoutMs
+    );
+    if (result.ok === false) throw new OyaError(result.error || `${action} failed`, 422, result);
+    return result.data;
+  }
+  async goto(url) {
+    await this.command("navigate", { url }, NAVIGATE_TIMEOUT_MS);
+    if (this.autoCaptcha) {
+      const result = await this.solveCaptcha();
+      if (result.present && !result.solved && !result.invisible) throw new OyaError(result.error || "CAPTCHA needs attention. Call solveCaptcha() again or open the live view.", 409, result);
+    }
+  }
+  /** The page as markdown plus numbered elements to act on. */
+  async analyze() {
+    return this.command("analyze");
+  }
+  /** Only the visible elements, which is what an agent almost always wants. */
+  async elements() {
+    return (await this.analyze()).elements.filter((e) => e.visible);
+  }
+  async click(elementId) {
+    const id = this.elementId(elementId);
+    await this.command("click", { element_id: id, selector: `[data-ac-id="${id}"]` });
+  }
+  async type(elementId, text) {
+    const id = this.elementId(elementId);
+    return this.command("type", { element_id: id, selector: `[data-ac-id="${id}"]`, text });
+  }
+  elementId(value) {
+    const id = Number(value);
+    if (typeof value !== "number" && typeof value !== "string" || value === "" || !Number.isInteger(id) || id < 0) {
+      throw new OyaError("Use a numeric element id from browser.analyze().", 400, null);
+    }
+    return id;
+  }
+  async pressKey(key) {
+    await this.command("press_key", { key });
+  }
+  /** `at` aims the wheel at an inner scroller (a results panel, a chat pane) instead of the page. */
+  async scroll(direction, amount, at) {
+    await this.command("scroll", at ? { direction, amount: amount ?? 500, ...at, smooth: false } : { direction, amount });
+  }
+  async waitFor(selector, timeout = 3e4) {
+    await this.command("wait", { selector, timeout }, timeout + 5e3);
+  }
+  /** A `data:image/…;base64,` URL. PNG or JPEG depending on the driver. */
+  async screenshot() {
+    const data = await this.command("screenshot");
+    return data.screenshot;
+  }
+  async url() {
+    const tabs = await this.tabs();
+    return tabs.find((t) => t.active)?.url || "";
+  }
+  async tabs() {
+    const data = await this.command("list_tabs");
+    return data.tabs || [];
+  }
+  async openTab(url) {
+    const data = await this.command("open_tab", { url }, NAVIGATE_TIMEOUT_MS);
+    return data.tab_id;
+  }
+  async switchTab(tabId) {
+    await this.command("switch_tab", { tab_id: tabId });
+  }
+  async closeTab(tabId) {
+    await this.command("close_tab", { tab_id: tabId });
+  }
+  /**
+   * Detect and clear a CAPTCHA. Providers that solve natively are left to do
+   * it; everything else goes to the configured solver.
+   */
+  solveCaptcha() {
+    return this.http.request("POST", `/api/browsers/${this.id}/captcha`, {}, 18e4);
+  }
+  /**
+   * Answer an MFA prompt with the persona's configured factor. When nothing can
+   * answer it, `liveViewUrl` is where a person finishes by hand.
+   */
+  async completeMfa() {
+    const result = await this.http.request("POST", `/api/browsers/${this.id}/mfa`, {}, 18e4);
+    if (result.liveViewUrl) result.liveViewUrl = new URL(result.liveViewUrl, this.http.baseUrl).href;
+    return result;
+  }
+  /** Natural-language control, using this key's configured model. */
+  async ask(prompt) {
+    const res = await this.http.request(
+      "POST",
+      `/api/browsers/${this.id}/chat`,
+      { messages: [{ role: "user", content: prompt }] },
+      6e5
+    );
+    return res.text;
+  }
+  /**
+   * Watch it work: an SSE stream of JPEG frames. EventSource cannot set
+   * headers, so the key travels as a query parameter — treat the URL itself as
+   * a credential.
+   */
+  liveViewUrl() {
+    return `${this.http.baseUrl}/api/live/${this.id}?key=${encodeURIComponent(this.http.apiKey)}`;
+  }
+  /** Counters, health and the last 50 things this browser did. */
+  status() {
+    return this.http.request("GET", `/api/browsers/${this.id}`);
+  }
+  /**
+   * Stop it, whatever it is: a cloud sandbox is destroyed so billing ends, a
+   * CDP session is handed back to its provider, a desktop browser disconnects.
+   */
+  stop() {
+    return this.http.request("POST", `/api/browsers/${this.id}/stop`, {}, 6e4);
+  }
+  /** `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. */
+  async close() {
+    await this.stop();
+  }
+};
+var DEFAULT_BASE_URL = "https://browser.getoya.ai";
+var READY_POLL_MS = 2e3;
+var env = (name) => globalThis.process?.env?.[name];
+var Oya = class {
+  http;
+  constructor(options = {}) {
+    const apiKey = options.apiKey || env("OYA_API_KEY");
+    if (!apiKey) {
+      throw new Error("No API key. Pass { apiKey } or set OYA_API_KEY \u2014 run `oya login` to get one.");
+    }
+    const baseUrl = (options.baseUrl || env("OYA_BASE_URL") || DEFAULT_BASE_URL).replace(/\/+$/, "");
+    const fetchImpl = options.fetch || globalThis.fetch;
+    if (!fetchImpl) throw new Error("No fetch available \u2014 pass { fetch } or use Node 18+.");
+    this.http = new Http(baseUrl, apiKey, options.timeoutMs ?? 6e4, fetchImpl.bind(globalThis));
+  }
+  browser = {
+    /** Start a browser and wait until it can take commands. */
+    start: async (options = {}) => {
+      const started = await this.http.request("POST", "/api/browsers/start", {
+        profile: options.profile || options.persona,
+        provider: options.provider,
+        wsUrl: options.wsUrl,
+        name: options.name,
+        queueMs: options.queueMs,
+        priority: options.priority,
+        budgetUsd: options.budgetUsd,
+        governed: options.governed,
+        policy: options.policy
+      }, 12e4, { "Idempotency-Key": options.idempotencyKey || globalThis.crypto.randomUUID() });
+      if (started.status === "starting") {
+        await this.waitUntilConnected(started.id, options.readyTimeoutMs ?? 12e4 + (options.queueMs || 0));
+        const connected = await this.http.request("GET", `/api/browsers/${encodeURIComponent(started.id)}`);
+        started.cdpUrl = connected.cdpUrl;
+      }
+      return new Browser(this.http, started, options.captcha === "auto");
+    },
+    /** Reattach to a browser that is already running. */
+    get: async (id) => {
+      const found = await this.http.request("GET", `/api/browsers/${encodeURIComponent(id)}`);
+      return new Browser(this.http, {
+        id: found.id,
+        provider: found.provider || "cdp",
+        persona: found.persona || "default",
+        status: "ready",
+        cdpUrl: found.cdpUrl
+      }, false);
+    },
+    list: () => this.http.request("GET", "/api/browsers"),
+    /** Stop some (`ids`) or every browser on this key. Each reports separately. */
+    stop: (ids) => this.http.request("POST", "/api/browsers/stop", ids === "all" ? { all: true } : { ids }, 12e4),
+    stopAll: async () => (await this.browser.stop("all")).stopped
+  };
+  /** Durable operational controls, including disconnected and cleanup-pending sessions. */
+  control = {
+    overview: () => this.http.request("GET", "/api/control"),
+    sessions: () => this.http.request("GET", "/api/control/sessions"),
+    session: (id) => this.http.request("GET", `/api/control/sessions/${encodeURIComponent(id)}`),
+    settings: (changes) => this.http.request("PATCH", "/api/control/project", changes),
+    cancel: (id) => this.http.request("POST", `/api/control/sessions/${encodeURIComponent(id)}/cancel`, {}),
+    stop: (id, force = false) => this.http.request("POST", `/api/control/sessions/${encodeURIComponent(id)}/stop`, { force }),
+    takeover: (id, action) => this.http.request("POST", `/api/control/sessions/${encodeURIComponent(id)}/control`, { action }),
+    input: (id, action, params) => this.http.request("POST", `/api/control/sessions/${encodeURIComponent(id)}/input`, { action, params }),
+    recover: (id, replace = false) => this.http.request("POST", `/api/control/sessions/${encodeURIComponent(id)}/recover`, { replace }),
+    ticket: (id) => this.http.request("POST", `/api/control/sessions/${encodeURIComponent(id)}/ticket`, {}),
+    events: (after = 0) => this.http.request("GET", `/api/control/events?after=${after}`),
+    createCredential: (options) => this.http.request("POST", "/api/control/credentials", options),
+    revokeCredential: (id) => this.http.request("DELETE", `/api/control/credentials/${encodeURIComponent(id)}`),
+    members: () => this.http.request("GET", "/api/control/members"),
+    inviteMember: (role = "operator") => this.http.request("POST", "/api/control/members/invite", { role }),
+    removeMember: (userId) => this.http.request("DELETE", `/api/control/members/${encodeURIComponent(userId)}`),
+    createWebhook: (url, types = []) => this.http.request("POST", "/api/control/webhooks", { url, types }),
+    removeWebhook: (id) => this.http.request("DELETE", `/api/control/webhooks/${encodeURIComponent(id)}`),
+    replayDelivery: (id) => this.http.request("POST", `/api/control/deliveries/${encodeURIComponent(id)}/replay`, {})
+  };
+  personas = {
+    list: async () => (await this.http.request("GET", "/api/personas")).personas,
+    get: (id) => this.http.request("GET", `/api/personas/${id}`),
+    /**
+     * Create an identity. The device — platform, timezone, locale — is chosen
+     * here and fixed for its life; `preview()` shows what a choice produces.
+     */
+    create: (options = {}) => this.http.request("POST", "/api/personas", options),
+    /** Name, concurrency cap and proxy hint. Never the device — clone for that. */
+    update: (id, changes) => this.http.request("PUT", `/api/personas/${id}`, changes),
+    /** A new persona of the same kind of device: same choices, fresh identity, empty jar. */
+    clone: (id, options = {}) => this.http.request("POST", `/api/personas/${id}/clone`, options),
+    /** The fingerprint these choices would produce. Persists nothing. */
+    preview: async (prefs = {}) => (await this.http.request("POST", "/api/personas/preview", { prefs })).fingerprint,
+    /** Platforms, and the timezones and locales each may coherently claim. */
+    options: () => this.http.request("GET", "/api/personas/options"),
+    /** Pin the persona to one of your proxies, or `null` to let assignment happen at connect. */
+    pinProxy: (id, proxyId) => this.http.request("PUT", `/api/personas/${id}/proxy`, { proxyId }),
+    remove: async (id) => {
+      await this.http.request("DELETE", `/api/personas/${id}`);
+    },
+    /** Store the second factor for this identity. Sealed at rest, never read back. */
+    setMfa: (id, config) => this.http.request("PUT", `/api/personas/${id}/mfa`, config),
+    clearMfa: async (id) => {
+      await this.http.request("DELETE", `/api/personas/${id}/mfa`);
+    }
+  };
+  /** This key's settings: LLM credentials, browser provider, solver. */
+  config = {
+    get: () => this.http.request("GET", "/api/config"),
+    set: (values) => this.http.request("POST", "/api/config", values)
+  };
+  /** Saved profiles. `personas` is retained as an alias for existing clients. */
+  profiles = this.personas;
+  usage() {
+    return this.http.request("GET", "/api/usage");
+  }
+  async waitUntilConnected(id, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+      const all = await this.browser.list();
+      if (all.some((b) => b.id === id && b.health !== "dead")) return;
+      try {
+        const session = await this.control.session(id);
+        if (["failed", "stopped", "unknown_outcome"].includes(session.state)) throw new OyaError(`Browser creation ended in ${session.state}`, 409, session);
+      } catch (e) {
+        if (!(e instanceof OyaError) || e.status !== 404) throw e;
+      }
+      await new Promise((r) => setTimeout(r, READY_POLL_MS));
+    }
+    throw new OyaError(`Browser ${id} did not come up within ${Math.round(timeoutMs / 1e3)}s`, 504, null);
+  }
+};
+
+// src/config.ts
+import { readFileSync, writeFileSync, mkdirSync, chmodSync } from "fs";
+import { homedir } from "os";
+import { join, dirname } from "path";
+var FILE = join(process.env.OYA_CONFIG_HOME || join(homedir(), ".oya"), "config.json");
+function load() {
+  try {
+    return JSON.parse(readFileSync(FILE, "utf8"));
+  } catch {
+    return {};
+  }
+}
+function save(values) {
+  const merged = { ...load(), ...values };
+  mkdirSync(dirname(FILE), { recursive: true });
+  writeFileSync(FILE, JSON.stringify(merged, null, 2), { mode: 384 });
+  chmodSync(FILE, 384);
+}
+var configPath = FILE;
+function resolved() {
+  const saved = load();
+  return {
+    apiKey: process.env.OYA_API_KEY || saved.apiKey || "",
+    baseUrl: (process.env.OYA_BASE_URL || saved.baseUrl || "https://browser.getoya.ai").replace(/\/+$/, "")
+  };
+}
+
+// src/prompt.ts
+import { createInterface } from "readline/promises";
+import { stdin, stdout } from "process";
+async function ask(question, fallback = "") {
+  const rl = createInterface({ input: stdin, output: stdout });
+  try {
+    const answer = (await rl.question(fallback ? `${question} [${fallback}] ` : `${question} `)).trim();
+    return answer || fallback;
+  } finally {
+    rl.close();
+  }
+}
+async function askSecret(question) {
+  const rl = createInterface({ input: stdin, output: stdout, terminal: true });
+  const asAny = rl;
+  asAny._writeToOutput = (s) => {
+    asAny.output.write(s.includes(question) ? s : "*");
+  };
+  try {
+    const answer = (await rl.question(`${question} `)).trim();
+    stdout.write("\n");
+    return answer;
+  } finally {
+    rl.close();
+  }
+}
+async function choose(question, options) {
+  console.log(`
+${question}`);
+  options.forEach((o, i) => console.log(`  ${i + 1}) ${o.label}${o.note ? `  \u2014 ${o.note}` : ""}`));
+  while (true) {
+    const answer = await ask("  choice:", "1");
+    const index = Number(answer) - 1;
+    if (options[index]) return options[index].id;
+    const byId = options.find((o) => o.id === answer);
+    if (byId) return byId.id;
+    console.log("  Pick one of the numbers above.");
+  }
+}
+
+// src/index.ts
+var HELP = `oya \u2014 thousands of browsers, one API
+
+  oya login                       Save an API key for this machine
+  oya init                        Set your model, browser provider and sign-ins
+  oya start [--persona auto]      Start a browser and print its id
+  oya goto <url> [--id <id>]      Navigate (defaults to the newest browser)
+  oya ask "<prompt>" [--id <id>]  Drive it in plain language
+  oya ls                          List running browsers
+  oya rm <id> | --all             Stop browsers
+  oya personas                    Identities: fingerprint + cookies + proxy
+  oya personas new [name]         --platform Win32|MacIntel|Linux --tz <zone> --locale <l> --max <n>
+  oya personas edit <id>          --name <n> --max <n> --geo <cc>
+  oya personas clone|rm <id>      A new device of the same kind \xB7 delete
+  oya status [--id <id>]          Health, counters and what it has been doing
+  oya open [--id <id>]            Open the live view in your browser
+  oya config [key=value ...]      Show or change this key's settings
+  oya control                     Durable project overview
+  oya sessions [id]               All sessions, including pending cleanup
+  oya stop <id> --force           Stop despite a profile-save error, or reconcile
+  oya takeover <id>               Acquire human control
+  oya release <id>                Release human control, leaving the agent paused
+  oya resume <id>                 Acknowledge agent resume
+  oya events [--after <cursor>]   Read durable lifecycle events
+  oya project <settings-json>     Update limits, rate cards and retention
+  oya start --governed --provider oya-selfhosted [--queue-ms 30000]
+            [--budget-usd 5] [--policy JSON] [--idempotency-key ID]
+  oya cancel <id>               Cancel queued or provisioning work
+  oya recover <id> [--replace]   Explicitly recover or replace a session
+  oya members [invite|remove]   List members, invite, or remove a user
+  oya credential new [--role viewer|operator|administrator]
+  oya credential revoke <id>     Revoke a service credential
+  oya webhook new <https-url>    Register a signed event webhook
+  oya webhook remove <id>        Disable a webhook
+  oya webhook replay <id>        Replay a delivery
+  oya usage                       What this key has spent
+  oya stealth-test [--live]       Score this deployment against bot detectors
+
+Options: --url <control plane>   --key <api key>   --json
+Config:  ${configPath}
+`;
+function parse(argv) {
+  const [command2 = "help", ...rest] = argv;
+  const args2 = [];
+  const flags2 = {};
+  for (let i = 0; i < rest.length; i++) {
+    const token = rest[i];
+    if (!token.startsWith("--")) {
+      args2.push(token);
+      continue;
+    }
+    const name = token.slice(2);
+    const next = rest[i + 1];
+    if (next === void 0 || next.startsWith("--")) flags2[name] = true;
+    else {
+      flags2[name] = next;
+      i++;
+    }
+  }
+  return { command: command2, args: args2, flags: flags2 };
+}
+var flagStr = (flags2, name) => typeof flags2[name] === "string" ? flags2[name] : void 0;
+function client(flags2) {
+  const saved = resolved();
+  const apiKey = flagStr(flags2, "key") || saved.apiKey;
+  const baseUrl = flagStr(flags2, "url") || saved.baseUrl;
+  if (!apiKey) {
+    console.error("No API key. Run `oya login`, or pass --key / set OYA_API_KEY.");
+    process.exit(1);
+  }
+  return new Oya({ apiKey, baseUrl });
+}
+var out = (flags2, value, human) => {
+  if (flags2.json) console.log(JSON.stringify(value, null, 2));
+  else human();
+};
+async function targetBrowser(oya, flags2) {
+  const id = flagStr(flags2, "id");
+  if (id) return oya.browser.get(id);
+  const all = await oya.browser.list();
+  if (!all.length) {
+    console.error("No browsers running. Start one with `oya start`.");
+    process.exit(1);
+  }
+  return oya.browser.get(all[all.length - 1].id);
+}
+async function cmdLogin(flags2) {
+  const current = resolved();
+  let apiKey = flagStr(flags2, "key") || "";
+  const baseUrl = (flagStr(flags2, "url") || (apiKey ? current.baseUrl : await ask("Control plane URL:", current.baseUrl))).replace(/\/+$/, "");
+  const how = apiKey ? "paste" : await choose("How do you want to authenticate?", [
+    { id: "paste", label: "Paste an API key", note: "from the dashboard, or a self-hosted key" },
+    { id: "password", label: "Sign in with email and password", note: "mints a new key for this machine" }
+  ]);
+  if (!apiKey && how === "paste") apiKey = await askSecret("API key:");
+  if (!apiKey && how === "password") {
+    const email = await ask("Email:");
+    const password = await askSecret("Password:");
+    const res = await fetch(`${baseUrl}/api/auth/login`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ email, password })
+    });
+    const session = await res.json();
+    if (!res.ok || !session.access_token) throw new Error(session.error || "Sign-in failed");
+    const minted = await fetch(`${baseUrl}/api/auth/keys`, {
+      method: "POST",
+      headers: { Authorization: `Bearer ${session.access_token}`, "Content-Type": "application/json" },
+      body: JSON.stringify({ label: "CLI" })
+    });
+    const created = await minted.json();
+    if (!minted.ok || !created.key) throw new Error(created.error || "Could not create an API key");
+    apiKey = created.key;
+    console.log('  Created a new API key labelled "CLI".');
+  }
+  if (!apiKey) throw new Error("No API key given");
+  const check = await fetch(`${baseUrl}/api/config`, { headers: { Authorization: `Bearer ${apiKey}` } });
+  if (!check.ok) throw new Error(`That key was rejected by ${baseUrl} (${check.status})`);
+  save({ apiKey, baseUrl });
+  console.log(`
+\u2705 Signed in to ${baseUrl}. Saved to ${configPath}`);
+  console.log("   Next: `oya init` to pick your model and browser provider.");
+}
+async function cmdInit(flags2) {
+  const oya = client(flags2);
+  const current = await oya.config.get();
+  console.log("\n\u2500\u2500 1. Your model \u2500\u2500");
+  const llm = await choose("Which LLM should agents use?", [
+    { id: "anthropic", label: "Claude (Anthropic)" },
+    { id: "openai", label: "OpenAI" },
+    { id: "skip", label: "Skip", note: current.has_openai_key ? "keep what is configured" : "no agent control" }
+  ]);
+  const updates = {};
+  if (llm !== "skip") {
+    updates.llm_provider = llm;
+    const key = await askSecret(`${llm === "anthropic" ? "Anthropic" : "OpenAI"} API key:`);
+    if (key) updates.openai_api_key = key;
+    const model = await ask("Default model:", llm === "anthropic" ? "claude-sonnet-4-5" : "gpt-4o-mini");
+    if (model) updates.chat_model = model;
+  }
+  console.log("\n\u2500\u2500 2. Where your browsers run \u2500\u2500");
+  const provider = await choose("Browser provider:", current.providers.map((p) => ({
+    id: p.id,
+    label: p.label,
+    note: p.needs.length ? p.configured ? "configured" : "needs an API key" : void 0
+  })));
+  updates.browser_provider = provider;
+  const needs = current.providers.find((p) => p.id === provider)?.needs || [];
+  for (const field of needs) {
+    const value = await askSecret(`${field.replace(/_/g, " ")}:`);
+    if (value) updates[field] = value;
+  }
+  console.log("\n\u2500\u2500 3. CAPTCHAs \u2500\u2500");
+  const solver = await choose("Solve CAPTCHAs automatically?", [
+    { id: "", label: "No", note: "providers that solve natively still will" },
+    { id: "capsolver", label: "Yes, via CapSolver" }
+  ]);
+  updates.captcha_solver = solver;
+  if (solver) {
+    const key = await askSecret("Solver API key:");
+    if (key) updates.captcha_api_key = key;
+  }
+  updates.onboarded = "true";
+  await oya.config.set(updates);
+  console.log("\n\u2705 Saved against your API key.");
+  if (provider === "oya-cloud" || provider === "oya-selfhosted") {
+    console.log("\n\u2500\u2500 4. Sign in once, on your own machine \u2500\u2500");
+    console.log("   Your remote browsers reuse the cookies from a desktop sign-in, so agents");
+    console.log("   arrive already logged in \u2014 as the same identity, from the same fingerprint.");
+    console.log(`   Download the desktop browser: ${resolved().baseUrl}/downloads`);
+  }
+  console.log("\n   Then:  oya start && oya goto https://example.com");
+}
+async function cmdStart(flags2) {
+  const oya = client(flags2);
+  const browser = await oya.browser.start({
+    persona: flagStr(flags2, "persona") || "default",
+    captcha: flags2.captcha === false ? "off" : "auto",
+    provider: flagStr(flags2, "provider"),
+    wsUrl: flagStr(flags2, "ws-url"),
+    name: flagStr(flags2, "name"),
+    idempotencyKey: flagStr(flags2, "idempotency-key"),
+    queueMs: flagStr(flags2, "queue-ms") === void 0 ? void 0 : Number(flagStr(flags2, "queue-ms")),
+    budgetUsd: flagStr(flags2, "budget-usd") === void 0 ? void 0 : Number(flagStr(flags2, "budget-usd")),
+    governed: flags2.governed === true,
+    priority: flagStr(flags2, "priority"),
+    policy: flagStr(flags2, "policy") ? JSON.parse(flagStr(flags2, "policy")) : void 0
+  });
+  out(flags2, { id: browser.id, provider: browser.provider, persona: browser.persona, cdpUrl: browser.cdpUrl }, () => {
+    console.log(`\u2705 ${browser.id}`);
+    console.log(`   provider: ${browser.provider}   persona: ${browser.persona}`);
+    if (browser.cdpUrl) console.log(`   cdp:      ${browser.cdpUrl}`);
+  });
+}
+async function cmdGoto(args2, flags2) {
+  const url = args2[0];
+  if (!url) throw new Error("Usage: oya goto <url>");
+  const oya = client(flags2);
+  const browser = await targetBrowser(oya, flags2);
+  await browser.goto(url);
+  console.log(`\u2705 ${browser.id} \u2192 ${url}`);
+}
+async function cmdAsk(args2, flags2) {
+  const prompt = args2.join(" ");
+  if (!prompt) throw new Error('Usage: oya ask "find the pricing page"');
+  const oya = client(flags2);
+  const browser = await targetBrowser(oya, flags2);
+  console.log(await browser.ask(prompt));
+}
+async function cmdLs(flags2) {
+  const all = await client(flags2).browser.list();
+  out(flags2, all, () => {
+    if (!all.length) return console.log("No browsers running.");
+    const dot = { ok: "\u25CF", stale: "\u25D0", errors: "\u2717", dead: "\u25CB" };
+    for (const b of all) {
+      console.log(`${dot[b.health] || "\xB7"} ${b.id}  ${(b.provider || "oya").padEnd(14)} ${(b.personaName || b.persona || "default").padEnd(14)} ${b.name.padEnd(18)} ${b.commands}\xB7${b.errors}  ${b.currentUrl.replace(/^https?:\/\//, "").slice(0, 40)}`);
+    }
+    console.log(`
+${all.length} running.`);
+  });
+}
+async function cmdRm(args2, flags2) {
+  const oya = client(flags2);
+  if (!flags2.all && !args2.length) throw new Error("Usage: oya rm <id>\u2026 | oya rm --all");
+  const r = await oya.browser.stop(flags2.all ? "all" : args2);
+  for (const x of r.results) {
+    const note = x.sandboxRemoved === true ? " (sandbox destroyed)" : x.sandboxRemoved === false ? " \u2014 sandbox NOT removed, check Daytona" : "";
+    console.log(`${x.ok ? "\u2705" : "\u2717"} ${x.id}${note}${x.error ? ` ${x.error}` : ""}`);
+  }
+  console.log(`stopped ${r.stopped}`);
+}
+async function cmdStatus(flags2) {
+  const oya = client(flags2);
+  const browser = await targetBrowser(oya, flags2);
+  const s = await browser.status();
+  out(flags2, s, () => {
+    console.log(`${s.name}  ${s.id}`);
+    console.log(`  ${s.health} \xB7 ${s.provider || "oya"} \xB7 persona ${s.personaName || s.persona || "default"}`);
+    console.log(`  ${s.commands} commands \xB7 ${s.errors} errors \xB7 ${s.pending} in flight \xB7 at ${s.currentUrl || "\u2014"}`);
+    if (s.lastError) console.log(`  last error: ${s.lastError}`);
+    if (s.activity.length) {
+      console.log("  recent:");
+      for (const a of s.activity.slice(0, 10)) console.log(`    ${a.ok ? "\xB7" : "\u2717"} ${a.action.padEnd(18)} ${a.summary}${a.error ? ` \u2014 ${a.error}` : ""}  ${a.ms}ms`);
+    }
+  });
+}
+async function cmdPersonas(args2, flags2) {
+  const oya = client(flags2);
+  const [sub, ...rest] = args2;
+  if (sub === "new" || sub === "create") {
+    const platformAlias = {
+      win32: "Win32",
+      windows: "Win32",
+      win: "Win32",
+      macintel: "MacIntel",
+      mac: "MacIntel",
+      macos: "MacIntel",
+      linux: "Linux x86_64",
+      "linux x86_64": "Linux x86_64"
+    };
+    const platformFlag = flagStr(flags2, "platform");
+    const prefs = {
+      ...platformFlag ? { platform: platformAlias[platformFlag.toLowerCase()] || platformFlag } : {},
+      ...flagStr(flags2, "tz") ? { timezone: flagStr(flags2, "tz") } : {},
+      ...flagStr(flags2, "locale") ? { locale: flagStr(flags2, "locale") } : {}
+    };
+    if (flags2.preview) {
+      const fp = await oya.personas.preview(prefs);
+      return out(flags2, fp, () => console.log(`${fp.platform} \xB7 ${fp.timezone} \xB7 ${fp.locale} \xB7 ${fp.screen} \xB7 ${fp.webgl}`));
+    }
+    const created = await oya.personas.create({
+      name: flagStr(flags2, "name") || rest[0],
+      prefs,
+      proxy: flagStr(flags2, "geo") ? { geo: flagStr(flags2, "geo") } : void 0,
+      maxConcurrent: flagStr(flags2, "max") ? Number(flagStr(flags2, "max")) : void 0
+    });
+    return out(flags2, created, () => console.log(`\u2705 ${created.id}  ${created.name}  ${created.fingerprint.platform} \xB7 ${created.fingerprint.timezone}`));
+  }
+  if (sub === "edit") {
+    if (!rest[0]) throw new Error("Usage: oya personas edit <id> --name <n> --max <n> --geo <cc>");
+    const updated = await oya.personas.update(rest[0], {
+      ...flagStr(flags2, "name") ? { name: flagStr(flags2, "name") } : {},
+      ...flagStr(flags2, "max") ? { maxConcurrent: flagStr(flags2, "max") === "none" ? null : Number(flagStr(flags2, "max")) } : {},
+      ...flagStr(flags2, "geo") ? { proxy: { geo: flagStr(flags2, "geo") } } : {}
+    });
+    return out(flags2, updated, () => console.log(`\u2705 ${updated.id}  ${updated.name}  cap ${updated.maxConcurrent ?? "\u221E"}`));
+  }
+  if (sub === "clone") {
+    if (!rest[0]) throw new Error("Usage: oya personas clone <id> [--name <n>]");
+    const c = await oya.personas.clone(rest[0], { name: flagStr(flags2, "name") });
+    return out(flags2, c, () => console.log(`\u2705 ${c.id}  ${c.name}  ${c.fingerprint.platform} \xB7 ${c.fingerprint.timezone}  (new identity, same kind of device)`));
+  }
+  if (sub === "rm" || sub === "delete") {
+    if (!rest[0]) throw new Error("Usage: oya personas rm <id>");
+    await oya.personas.remove(rest[0]);
+    return console.log(`\u2705 removed ${rest[0]}`);
+  }
+  const all = await oya.personas.list();
+  out(flags2, all, () => {
+    if (!all.length) return console.log("No personas yet \u2014 `oya personas new`.");
+    for (const p of all) {
+      const cap = p.maxConcurrent === null ? "\u221E" : String(p.maxConcurrent);
+      console.log(`${p.id}  ${p.name.padEnd(20)} ${p.activeBrowsers}/${cap} running  ${p.fingerprint.platform} \xB7 ${p.fingerprint.timezone}${p.exit ? `  via ${p.exit.label}` : p.proxy?.geo ? `  geo ${p.proxy.geo}` : ""}${p.mfa?.configured ? `  mfa:${p.mfa.type}` : ""}${p.isDefault ? "  (default)" : ""}`);
+    }
+  });
+}
+async function cmdOpen(flags2) {
+  const browser = await targetBrowser(client(flags2), flags2);
+  const url = browser.liveViewUrl();
+  const opener = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+  spawn(opener, [url], { detached: true, stdio: "ignore" }).unref();
+  console.log(`Opening ${browser.id}`);
+}
+async function cmdConfig(args2, flags2) {
+  const oya = client(flags2);
+  if (!args2.length) {
+    const current = await oya.config.get();
+    return out(flags2, current, () => console.log(JSON.stringify(current, null, 2)));
+  }
+  const updates = {};
+  for (const pair of args2) {
+    const index = pair.indexOf("=");
+    if (index < 1) throw new Error(`Expected key=value, got "${pair}"`);
+    updates[pair.slice(0, index)] = pair.slice(index + 1);
+  }
+  await oya.config.set(updates);
+  console.log(`\u2705 updated ${Object.keys(updates).join(", ")}`);
+}
+async function cmdUsage(flags2) {
+  const usage = await client(flags2).usage();
+  console.log(JSON.stringify(usage, null, 2));
+}
+function cmdStealthTest(flags2) {
+  return new Promise((resolve, reject) => {
+    const child = spawn("node", ["test-stealth.js", ...flags2.live ? ["--live"] : []], {
+      cwd: process.env.OYA_SERVER_DIR || "server",
+      stdio: "inherit"
+    });
+    child.on("error", () => reject(new Error(
+      "Could not find the stealth harness. Run it from a checkout, or set OYA_SERVER_DIR."
+    )));
+    child.on("exit", (code) => code === 0 ? resolve() : reject(new Error(`stealth test exited ${code}`)));
+  });
+}
+var { command, args, flags } = parse(process.argv.slice(2));
+try {
+  if (["control", "sessions", "takeover", "release", "resume", "events", "project", "credential", "webhook", "cancel", "recover", "members"].includes(command) || command === "stop" && flags.force === true) {
+    const c = client(flags).control;
+    const required = (i = 0) => {
+      if (!args[i]) throw new Error("Missing argument; run oya help");
+      return args[i];
+    };
+    let result;
+    switch (command) {
+      case "control":
+        result = await c.overview();
+        break;
+      case "sessions":
+        result = args[0] ? await c.session(args[0]) : await c.sessions();
+        break;
+      case "cancel":
+        result = await c.cancel(required());
+        break;
+      case "recover":
+        result = await c.recover(required(), flags.replace === true);
+        break;
+      case "members":
+        if (!args[0]) result = await c.members();
+        else if (args[0] === "remove") result = await c.removeMember(required(1));
+        else if (args[0] === "invite") {
+          const role = flagStr(flags, "role") || "operator";
+          if (!["viewer", "operator", "administrator"].includes(role)) throw new Error("Invalid role");
+          result = await c.inviteMember(role);
+        } else throw new Error("Use members, members invite, or members remove");
+        break;
+      case "stop":
+        result = await c.stop(required(), flags.force === true);
+        break;
+      case "takeover":
+      case "release":
+      case "resume":
+        result = await c.takeover(required(), command === "takeover" ? "acquire" : command);
+        break;
+      case "events":
+        result = await c.events(Number(flagStr(flags, "after") || 0));
+        break;
+      case "project":
+        result = await c.settings(JSON.parse(required()));
+        break;
+      case "credential":
+        if (required() === "revoke") result = await c.revokeCredential(required(1));
+        else if (args[0] === "new") {
+          const role = flagStr(flags, "role") || "operator";
+          if (!["viewer", "operator", "administrator"].includes(role)) throw new Error("Invalid role");
+          result = await c.createCredential({ role, label: flagStr(flags, "label") });
+        } else throw new Error("Use credential new or credential revoke");
+        break;
+      case "webhook":
+        if (required() === "new") result = await c.createWebhook(required(1));
+        else if (args[0] === "remove") result = await c.removeWebhook(required(1));
+        else if (args[0] === "replay") result = await c.replayDelivery(required(1));
+        else throw new Error("Use webhook new, remove, or replay");
+        break;
+    }
+    console.log(JSON.stringify(result, null, 2));
+  } else switch (command) {
+    case "login":
+      await cmdLogin(flags);
+      break;
+    case "init":
+      await cmdInit(flags);
+      break;
+    case "start":
+      await cmdStart(flags);
+      break;
+    case "goto":
+      await cmdGoto(args, flags);
+      break;
+    case "ask":
+      await cmdAsk(args, flags);
+      break;
+    case "ls":
+    case "list":
+      await cmdLs(flags);
+      break;
+    case "status":
+      await cmdStatus(flags);
+      break;
+    case "rm":
+    case "stop":
+      await cmdRm(args, flags);
+      break;
+    case "personas":
+      await cmdPersonas(args, flags);
+      break;
+    case "open":
+      await cmdOpen(flags);
+      break;
+    case "config":
+      await cmdConfig(args, flags);
+      break;
+    case "usage":
+      await cmdUsage(flags);
+      break;
+    case "stealth-test":
+      await cmdStealthTest(flags);
+      break;
+    case "whoami":
+      console.log(JSON.stringify({ ...resolved(), apiKey: load().apiKey ? "saved" : "none" }, null, 2));
+      break;
+    case "help":
+    case "--help":
+    case "-h":
+      console.log(HELP);
+      break;
+    default:
+      console.error(`Unknown command: ${command}
+`);
+      console.log(HELP);
+      process.exit(1);
+  }
+} catch (err) {
+  const error = err;
+  console.error(`
+\u2717 ${error.message}`);
+  if (error.status === 401) console.error("  The API key was rejected. Run `oya login`.");
+  if (error.status === 429) console.error("  A quota or a persona concurrency cap. `oya personas` shows what is running.");
+  process.exit(1);
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@oya-ai/cli",
+  "version": "0.1.0",
+  "description": "Command line for the Oya browser control plane.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "oya": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@oya-ai/browser": "0.1.0",
+    "@types/node": "^20.19.43",
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0"
+  }
+}