Agent recipes

{
  "mcpServers": {
    "browz": {
      "command": "npx",
      "args": ["-y", "@browz/mcp"]
    }
  }
}

## Browsing with Browz

Use the Browz MCP tools (`browz_*`) for every web page in this project.

- One task, one isolated browser: start each task with `browz_session_open` (`task` says what you are
  doing; `mode` stays `ephemeral` unless the task names a returning identity) and end it with
  `browz_session_close`. Pass the returned `profileId` as `id` to the page tools. Never reuse another
  task's session.
- Read a page with `browz_snapshot` and act with `browz_act` on the refs it returns (`e12`). Take a new
  snapshot after every navigation. Use `browz_screenshot` only to check layout or images.
- If a snapshot says `NEEDS A PERSON` (a sign-in, a verification code or a CAPTCHA), call
  `browz_request_human` with a short reason and wait. Never type a password or code, and never try to
  solve a CAPTCHA.
- Only visit sites whose terms allow automated use. If a page says automated access is not allowed,
  stop and say so.

{
  "mcpServers": {
    "browz": {
      "command": "npx",
      "args": ["-y", "@browz/mcp"]
    }
  }
}

---
description: Use Browz for any task that opens a web page (checking a deploy, reproducing a bug, reading docs behind a sign-in)
alwaysApply: false
---

# Browsing with Browz

Open web pages only through the Browz MCP tools (`browz_*`), never with a shell command or a browser you start yourself.

- One task, one isolated browser: `browz_session_open` with a short `task`, then use the returned `profileId` as `id` in the page tools, and finish with `browz_session_close` (an ephemeral session is wiped then).
- To test a local dev server, open it by its `http://127.0.0.1:<port>` or `http://localhost:<port>` address.
- Read with `browz_snapshot`; act with `browz_act` on its refs (`e12`); take a new snapshot after each navigation; `browz_wait` for text or a URL instead of sleeping.
- `browz_screenshot` when the layout matters (a visual bug, a broken image).
- `NEEDS A PERSON` in a snapshot (sign-in, verification code, CAPTCHA): call `browz_request_human` and wait. Never type a password or code, never try to solve a CAPTCHA.
- Use only sites whose terms allow automated access.

"""An OpenAI Agents SDK agent that drives Browz through the hosted MCP server, with an agent token.

    uv run main.py                     # the agent (needs OPENAI_API_KEY and BROWZ_AGENT_TOKEN)
    uv run main.py --no-llm            # the same browser steps as direct tool calls, no model
    uv run main.py --task "Open https://example.com and tell me the title, then end the session"

The hosted server (https://mcp.gobrowz.com/mcp, free public beta) relays each tool call to the
Browz app on YOUR computer, which must be open, signed in, with Remote control on. The browser is
your real Browz profile there; nothing runs in a cloud browser.

Environment:
    BROWZ_AGENT_TOKEN   a Browz agent token (app: Automate > Connect an AI agent, or the account
                        page). Read from the environment, never written in code.
    BROWZ_MCP_URL       default https://mcp.gobrowz.com/mcp. Any Browz Streamable HTTP endpoint works,
                        e.g. a `browz-mcp serve` on your own server with its bearer token.
    BROWZ_DEVICE_ID     which computer to use, when more than one is online (browz_devices_list).
    OPENAI_API_KEY      for the model (not needed with --no-llm).
    OPENAI_MODEL        default gpt-5.4-mini.
"""

import argparse
import asyncio
import json
import os
import sys

from agents import Agent, Runner
from agents.mcp import MCPServerStreamableHttp

MCP_URL = os.environ.get("BROWZ_MCP_URL", "https://mcp.gobrowz.com/mcp")
TASK = (
    "Using Browz: create a new profile called agent-check, start it, open https://example.com, "
    "tell me the page title, take a screenshot, then end the session and delete the profile."
)
INSTRUCTIONS = (
    "You control web browsers through the Browz tools (browz_*). Read pages with browz_snapshot and "
    "act on them with browz_act using the refs it returns. If a snapshot says NEEDS A PERSON (a "
    "sign-in, a verification code or a CAPTCHA), call browz_request_human and never type a password "
    "or try to solve a CAPTCHA yourself. Always end the sessions you start with browz_session_end."
)


def with_device(args):
    """Add deviceId when one is set: needed only when several computers are online."""
    device = os.environ.get("BROWZ_DEVICE_ID")
    return {**args, "deviceId": device} if device else args


def text_of(result):
    return "\n".join(getattr(c, "text", "") for c in result.content if getattr(c, "type", "") == "text")


def first_json(text):
    start = text.find("{")
    return json.JSONDecoder().raw_decode(text[start:])[0]


async def direct(server):
    """The task's steps as plain tool calls through the same MCP connection."""
    async def call(name, args):
        result = await server.call_tool(name, with_device(args))
        if getattr(result, "is_error", None) or getattr(result, "isError", None):   # name differs by mcp version
            raise RuntimeError(f"{name}: {text_of(result)}")
        return result

    pid = first_json(text_of(await call("browz_profile_create", {"name": "agent-check"})))["id"]
    try:
        await call("browz_profile_start", {"id": pid})
        await call("browz_navigate", {"id": pid, "url": "https://example.com"})
        snapshot = text_of(await call("browz_snapshot", {"id": pid}))
        title = next((line[len("Title: "):] for line in snapshot.splitlines() if line.startswith("Title: ")), None)
        shot = await call("browz_screenshot", {"id": pid})
        images = [c for c in shot.content if getattr(c, "type", "") == "image"]
        return {"profileId": pid, "title": title, "screenshotBytes": len(images[0].data) * 3 // 4 if images else 0}
    finally:
        await call("browz_session_end", {"id": pid, "delete": True})


async def main():
    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
    parser.add_argument("--no-llm", action="store_true", help="direct tool calls, no model")
    parser.add_argument("--task", default=TASK)
    args = parser.parse_args()

    token = os.environ.get("BROWZ_AGENT_TOKEN")
    if not token:
        sys.exit("set BROWZ_AGENT_TOKEN to a Browz agent token (never paste it into code)")

    server = MCPServerStreamableHttp(
        name="browz",
        params={"url": MCP_URL, "headers": {"Authorization": f"Bearer {token}"}, "timeout": 60},
        cache_tools_list=True,
        client_session_timeout_seconds=90,   # a browser start can take longer than the SDK's default 5 s
    )
    async with server:
        tools = [t.name for t in await server.list_tools()]
        if args.no_llm:
            out = await direct(server)
        else:
            agent = Agent(
                name="Browz agent",
                instructions=INSTRUCTIONS,
                mcp_servers=[server],
                model=os.environ.get("OPENAI_MODEL", "gpt-5.4-mini"),
            )
            result = await Runner.run(agent, args.task, max_turns=30)
            out = {"answer": str(result.final_output)}
    print(json.dumps({"ok": True, "mcp": MCP_URL, "tools": len(tools), **out}, indent=2))


if __name__ == "__main__":
    asyncio.run(main())

// Playwright attached over CDP to a Browz profile.
//
//   npm install
//   node index.mjs                      # a throwaway profile, created and removed again
//   BROWZ_PROFILE_ID=<id> node index.mjs   # an existing profile (started and stopped, never deleted)
//
// The rule that matters: ATTACH to the browser Browz started (chromium.connectOverCDP). Never
// chromium.launch(): that starts stock Chromium with its own fingerprint and none of the profile's
// cookies, proxy or storage.
import { readFile, writeFile } from 'node:fs/promises';
import { homedir } from 'node:os';
import { join } from 'node:path';
import { chromium } from 'playwright-core';

const URL_TO_OPEN = process.env.BROWZ_TEST_URL || 'https://example.com/';

// ── Local API credentials: the Browz app writes its token to <data dir>/api-token ──────────────
const DATA = process.env.BROWZ_DATA || join(homedir(), '.browz');
const TOKEN = process.env.BROWZ_TOKEN || (await readFile(join(DATA, 'api-token'), 'utf8')).trim();
let HOST = process.env.BROWZ_API;
if (!HOST) {
  let port = 50333;
  try { port = JSON.parse(await readFile(join(DATA, 'agent.json'), 'utf8')).port || port; } catch { /* default port */ }
  HOST = `127.0.0.1:${port}`;
}

/** One Local API call. Throws with the agent's own message on failure. */
async function api(path, body) {
  const res = await fetch(`http://${HOST}${path}`, {
    method: body === undefined ? 'GET' : 'POST',
    headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
    body: body === undefined ? undefined : JSON.stringify(body),
  });
  const json = await res.json().catch(() => ({}));
  if (!res.ok || (typeof json.code === 'number' && json.code !== 0)) {
    throw new Error(`${path}: ${json.msg || json.error || `HTTP ${res.status}`}`);
  }
  return json;
}

// ── 1. A profile: your own, or a throwaway one ────────────────────────────────────────────────
const owned = !process.env.BROWZ_PROFILE_ID;
const profileId = process.env.BROWZ_PROFILE_ID
  || (await api('/api/v1/profile/create', { name: `recipe-playwright-${Date.now()}` })).data.id;

let browser;
let started = false;
try {
  // ── 2. Start it through Browz. The reply carries the CDP endpoints. ───────────────────────────
  const { data: session } = await api('/api/v1/browser/start', { id: profileId });
  started = true;

  // ── 3. Attach. Use the existing context: it IS the profile (cookies, storage). ───────────────
  //    browser.newContext() would make an incognito-like context without the profile's state.
  browser = await chromium.connectOverCDP(session.wsEndpoint || session.cdpEndpoint, { timeout: 30_000 });
  const context = browser.contexts()[0];
  const page = context.pages()[0] || (await context.newPage());

  // ── 4. Ordinary Playwright from here on. ───────────────────────────────────────────────────────
  await page.goto(URL_TO_OPEN, { waitUntil: 'load', timeout: 30_000 });
  const title = await page.title();
  await writeFile('screenshot.png', await page.screenshot());
  console.log(JSON.stringify({ ok: true, profileId, browser: browser.version(), url: page.url(), title, screenshot: 'screenshot.png' }));
} finally {
  // ── 5. Detach (close() on a CDP connection does not kill Browz's browser), then stop through
  //       Browz so the profile is saved cleanly. A throwaway profile is deleted and purged.
  if (browser) await browser.close().catch(() => {});
  if (started) await api('/api/v1/browser/stop', { id: profileId }).catch((e) => console.error(String(e)));
  if (owned) {
    await api('/api/v1/profile/delete', { id: profileId });
    await api('/api/v1/profile/purge', { id: profileId });
  }
}

// Puppeteer attached over CDP to a Browz profile.
//
//   npm install
//   node index.mjs                         # a throwaway profile, created and removed again
//   BROWZ_PROFILE_ID=<id> node index.mjs   # an existing profile (started and stopped, never deleted)
//
// Use puppeteer.connect() on the browser Browz started. Never puppeteer.launch(): that runs a
// different browser with none of the profile's fingerprint, proxy, cookies or storage.
import { readFile, writeFile } from 'node:fs/promises';
import { homedir } from 'node:os';
import { join } from 'node:path';
import puppeteer from 'puppeteer-core';

const URL_TO_OPEN = process.env.BROWZ_TEST_URL || 'https://example.com/';

// ── Local API credentials: the Browz app writes its token to <data dir>/api-token ──────────────
const DATA = process.env.BROWZ_DATA || join(homedir(), '.browz');
const TOKEN = process.env.BROWZ_TOKEN || (await readFile(join(DATA, 'api-token'), 'utf8')).trim();
let HOST = process.env.BROWZ_API;
if (!HOST) {
  let port = 50333;
  try { port = JSON.parse(await readFile(join(DATA, 'agent.json'), 'utf8')).port || port; } catch { /* default port */ }
  HOST = `127.0.0.1:${port}`;
}

async function api(path, body) {
  const res = await fetch(`http://${HOST}${path}`, {
    method: body === undefined ? 'GET' : 'POST',
    headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
    body: body === undefined ? undefined : JSON.stringify(body),
  });
  const json = await res.json().catch(() => ({}));
  if (!res.ok || (typeof json.code === 'number' && json.code !== 0)) {
    throw new Error(`${path}: ${json.msg || json.error || `HTTP ${res.status}`}`);
  }
  return json;
}

const owned = !process.env.BROWZ_PROFILE_ID;
const profileId = process.env.BROWZ_PROFILE_ID
  || (await api('/api/v1/profile/create', { name: `recipe-puppeteer-${Date.now()}` })).data.id;

let browser;
let started = false;
try {
  // 1. Start through Browz.
  const { data: session } = await api('/api/v1/browser/start', { id: profileId });
  started = true;

  // 2. Attach. browserWSEndpoint is the browser's ws:// URL; browserURL (http://127.0.0.1:<port>)
  //    works too. defaultViewport: null keeps the profile's own window and screen size, which are
  //    part of its fingerprint; Puppeteer's default would resize every page to 800x600.
  browser = session.wsEndpoint
    ? await puppeteer.connect({ browserWSEndpoint: session.wsEndpoint, defaultViewport: null })
    : await puppeteer.connect({ browserURL: session.cdpEndpoint, defaultViewport: null });

  // 3. Reuse the profile's first tab.
  const page = (await browser.pages())[0] || (await browser.newPage());
  await page.goto(URL_TO_OPEN, { waitUntil: 'load', timeout: 30_000 });
  const title = await page.title();
  await writeFile('screenshot.png', await page.screenshot());
  console.log(JSON.stringify({ ok: true, profileId, browser: await browser.version(), url: page.url(), title, screenshot: 'screenshot.png' }));
} finally {
  // 4. disconnect() leaves the browser running; Browz stops it and saves the profile.
  if (browser) await browser.disconnect().catch(() => {});
  if (started) await api('/api/v1/browser/stop', { id: profileId }).catch((e) => console.error(String(e)));
  if (owned) {
    await api('/api/v1/profile/delete', { id: profileId });
    await api('/api/v1/profile/purge', { id: profileId });
  }
}

// The TypeScript SDK: add a proxy, create a profile behind it, launch it, take a screenshot, stop.
//
//   npm install
//   BROWZ_PROXY='http://user:[email protected]:8000' npm start
//   npm run typecheck
//
// BROWZ_PROXY is any proxy you are allowed to use: http, https, socks4 or socks5. Without it the
// profile runs direct (this machine's IP), which links it to every other unproxied profile.
import { writeFile } from 'node:fs/promises';
import { Browz, BrowzError, localCredentials, type ProxyScheme } from '@browz/sdk';

const URL_TO_OPEN = process.env.BROWZ_TEST_URL ?? 'https://example.com/';

/** `scheme://user:pass@host:port` → the SDK's ProxySpec. */
function parseProxy(raw: string) {
  const u = new URL(raw);
  const scheme = u.protocol.replace(':', '') as ProxyScheme;
  if (!['http', 'https', 'socks4', 'socks5'].includes(scheme)) throw new Error(`unsupported proxy scheme ${scheme}`);
  return {
    scheme,
    host: u.hostname,
    port: Number(u.port),
    ...(u.username ? { user: decodeURIComponent(u.username) } : {}),
    ...(u.password ? { pass: decodeURIComponent(u.password) } : {}),
  };
}

// Reads the Browz app's own Local API token (<BROWZ_DATA or ~/.browz>/api-token) and port.
const creds = await localCredentials();
const browz = new Browz(creds);

// 1. A pool proxy. Its id is what profiles (and the MCP tools) refer to; the password is
//    write-only and never returned by any list.
let proxyId: string | undefined;
if (process.env.BROWZ_PROXY) {
  proxyId = (await browz.proxies.create({ name: `recipe-proxy-${Date.now()}`, ...parseProxy(process.env.BROWZ_PROXY) })).id;
} else {
  console.error('BROWZ_PROXY is not set: this profile will use this machine\'s own IP.');
}

// 2. A profile behind it. Timezone and languages follow the proxy's exit unless you set them.
const profile = await browz.profiles.create({ name: `recipe-sdk-${Date.now()}`, ...(proxyId ? { proxyId } : {}) });

let started = false;
try {
  // 3. Launch. coherenceWarnings flags anything that contradicts the exit (e.g. a timezone).
  const session = await browz.browser.start(profile.id);
  started = true;

  // 4. Open a page through the agent and wait for it to load.
  const nav = await browz.browser.navigate(profile.id, URL_TO_OPEN);

  // 5. Screenshot. The published SDK (0.2.0) has no wrapper for it yet, so this is the Local API route
  //    itself (POST /api/v1/browser/screenshot, PNG as base64), with the same credentials.
  //    @browz/sdk 0.3.0 adds browser.snapshot/act/wait/screenshot; this recipe switches to them
  //    once 0.3.0 is on npm.
  const res = await fetch(`http://${creds.host}/api/v1/browser/screenshot`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${creds.token}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({ id: profile.id }),
  });
  const shot = (await res.json()) as { code: number; msg?: string; data?: { base64: string } };
  if (!res.ok || shot.code !== 0 || !shot.data) throw new Error(`screenshot: ${shot.msg ?? res.status}`);
  await writeFile('screenshot.png', Buffer.from(shot.data.base64, 'base64'));

  console.log(JSON.stringify({
    ok: true,
    profileId: profile.id,
    archetype: profile.archetype,
    proxyId: proxyId ?? null,
    cdpEndpoint: session.cdpEndpoint,
    coherenceWarnings: session.coherenceWarnings ?? [],
    url: nav.url,
    loaded: nav.loaded,
    screenshot: 'screenshot.png',
  }));
} catch (e) {
  // BrowzError carries the agent's own message and HTTP status.
  if (e instanceof BrowzError) console.error(`Browz refused: ${e.message} (HTTP ${e.status})`);
  throw e;
} finally {
  // 6. Stop (saves the profile cleanly), then remove what this recipe made.
  if (started) await browz.browser.stop(profile.id);
  await browz.profiles.delete(profile.id);
  await browz.profiles.purge(profile.id);
  if (proxyId) await browz.proxies.delete(proxyId);
}

"""Drive a Browz profile from Python through the Local API, with the standard library only.

    python3 browz_rest.py                       # a throwaway profile, removed afterwards
    python3 browz_rest.py --url https://example.com/ --keep

Create a profile, start it, open a page, read it as an accessibility snapshot, take a screenshot,
stop it, then delete and purge the profile. No browser driver, no pip install: every step is one
HTTP call to the Browz agent on this computer (OpenAPI: https://gobrowz.com/openapi/local-api.json).

Credentials: BROWZ_TOKEN and BROWZ_API (host:port) when set, otherwise the token in
<BROWZ_DATA or ~/.browz>/api-token and the port in agent.json (default 50333).
"""

import argparse
import base64
import json
import os
import pathlib
import time
import urllib.error
import urllib.request

DATA = pathlib.Path(os.environ.get("BROWZ_DATA") or pathlib.Path.home() / ".browz")


def credentials():
    token = os.environ.get("BROWZ_TOKEN") or (DATA / "api-token").read_text().strip()
    host = os.environ.get("BROWZ_API")
    if not host:
        port = 50333
        try:
            port = json.loads((DATA / "agent.json").read_text()).get("port") or port
        except (OSError, ValueError):
            pass
        host = f"127.0.0.1:{port}"
    return host, token


HOST, TOKEN = credentials()


def api(path, body=None, timeout=120):
    """One Local API call: GET without a body, POST with one. Raises with the agent's message."""
    req = urllib.request.Request(
        f"http://{HOST}{path}",
        data=None if body is None else json.dumps(body).encode(),
        method="GET" if body is None else "POST",
        headers={"Authorization": f"Bearer {TOKEN}", "Content-Type": "application/json"},
    )
    try:
        with urllib.request.urlopen(req, timeout=timeout) as res:
            reply = json.loads(res.read() or b"{}")
    except urllib.error.HTTPError as e:
        reply = json.loads(e.read() or b"{}")
        raise RuntimeError(f"{path}: HTTP {e.code}: {reply.get('msg') or reply.get('error')}") from None
    if reply.get("code", 0) != 0:
        raise RuntimeError(f"{path}: {reply.get('msg') or reply}")
    return reply


def main():
    p = argparse.ArgumentParser(description=__doc__.splitlines()[0])
    p.add_argument("--url", default="https://example.com/")
    p.add_argument("--keep", action="store_true", help="keep the profile afterwards")
    p.add_argument("--out", default="screenshot.png")
    args = p.parse_args()

    profile = api("/api/v1/profile/create", {"name": f"recipe-python-{int(time.time())}"})["data"]
    pid = profile["id"]
    started = False
    try:
        start = api("/api/v1/browser/start", {"id": pid})["data"]
        started = True
        nav = api("/api/v1/browser/navigate", {"id": pid, "url": args.url})["data"]
        snap = api("/api/v1/browser/snapshot", {"id": pid, "mode": "compact", "maxTokens": 2000})["data"]
        shot = api("/api/v1/browser/screenshot", {"id": pid})["data"]
        pathlib.Path(args.out).write_bytes(base64.b64decode(shot["base64"]))
        print(json.dumps({
            "ok": True,
            "profileId": pid,
            "debugPort": start["debugPort"],
            "url": nav.get("url"),
            "title": snap["title"],
            "snapshotRefs": snap["refs"],
            "snapshotFirstLines": snap["snapshot"].splitlines()[:5],
            "screenshot": args.out,
        }, indent=2, ensure_ascii=False))
    finally:
        if started:
            api("/api/v1/browser/stop", {"id": pid})
        if not args.keep:
            api("/api/v1/profile/delete", {"id": pid})
            api("/api/v1/profile/purge", {"id": pid})


if __name__ == "__main__":
    main()

// Two accounts, kept apart: two Browz profiles sign in to the same site side by side, each with
// its own cookies and storage, driven only through the Local API's page model (snapshot + act).
//
//   node index.mjs                       # against the small demo site this script serves on 127.0.0.1
//   BROWZ_PROXY_A=<pool id> BROWZ_PROXY_B=<pool id> node index.mjs   # each profile on its own exit
//
// Use this pattern only on sites whose terms allow you to hold more than one account (many do, for
// example separate business and personal accounts, or one per client you manage). The demo site
// here is ours and exists for this recipe.
import http from 'node:http';
import { readFile } from 'node:fs/promises';
import { homedir } from 'node:os';
import { join } from 'node:path';

// ── Local API credentials ────────────────────────────────────────────────────────────────────
const DATA = process.env.BROWZ_DATA || join(homedir(), '.browz');
const TOKEN = process.env.BROWZ_TOKEN || (await readFile(join(DATA, 'api-token'), 'utf8')).trim();
let HOST = process.env.BROWZ_API;
if (!HOST) {
  let port = 50333;
  try { port = JSON.parse(await readFile(join(DATA, 'agent.json'), 'utf8')).port || port; } catch { /* default port */ }
  HOST = `127.0.0.1:${port}`;
}
async function api(path, body) {
  const res = await fetch(`http://${HOST}${path}`, {
    method: body === undefined ? 'GET' : 'POST',
    headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
    body: body === undefined ? undefined : JSON.stringify(body),
  });
  const json = await res.json().catch(() => ({}));
  if (!res.ok || (typeof json.code === 'number' && json.code !== 0)) {
    throw new Error(`${path}: ${json.msg || json.error || `HTTP ${res.status}`}`);
  }
  return json;
}

// ── The demo site: a sign-in form that sets a session cookie, and an account page ──────────────
const page = (title, body) => `<!doctype html><html lang="en"><head><meta charset="utf-8"><title>${title}</title></head><body>${body}</body></html>`;
function demoSite() {
  const server = http.createServer((req, res) => {
    const user = /(?:^|;\s*)demo_user=([a-z0-9-]+)/.exec(req.headers.cookie || '')?.[1];
    if (req.method === 'POST' && req.url === '/login') {
      let body = '';
      req.on('data', (c) => { body += c; });
      req.on('end', () => {
        const name = (new URLSearchParams(body).get('name') || '').toLowerCase().replace(/[^a-z0-9-]/g, '').slice(0, 32) || 'anonymous';
        res.writeHead(303, { 'Set-Cookie': `demo_user=${name}; Path=/; HttpOnly; SameSite=Lax`, Location: '/account' });
        res.end();
      });
      return;
    }
    if (req.url === '/account') {
      res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
      res.end(page('Account', user ? `<h1>Signed in as ${user}</h1>` : '<h1>Not signed in</h1><a href="/login">Sign in</a>'));
      return;
    }
    res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
    res.end(page('Demo sign-in', `<h1>Demo shop</h1><form method="post" action="/login">
      <label>Account name <input name="name" autocomplete="off"></label>
      <button type="submit">Continue</button></form>`));
  });
  return new Promise((resolve) => server.listen(0, '127.0.0.1', () => resolve(server)));
}

/** The ref of the first snapshot line with this role and accessible name, e.g. `textbox "Account name" [e5]`. */
function refOf(snapshot, role, name) {
  const line = snapshot.split('\n').find((l) => l.includes(`${role} "${name}`) && /\[e\d+\]/.test(l));
  if (!line) throw new Error(`no ${role} "${name}" in the snapshot:\n${snapshot}`);
  return /\[(e\d+)\]/.exec(line)[1];
}

/** Sign one profile in as `name` the way a person would: read the page, fill the field, click. */
async function signIn(id, base, name) {
  await api('/api/v1/browser/navigate', { id, url: `${base}/login` });
  const snap = (await api('/api/v1/browser/snapshot', { id, mode: 'interactive' })).data.snapshot;
  await api('/api/v1/browser/act', { id, action: 'fill', ref: refOf(snap, 'textbox', 'Account name'), text: name });
  await api('/api/v1/browser/act', { id, action: 'click', ref: refOf(snap, 'button', 'Continue') });
  const waited = (await api('/api/v1/browser/wait', { id, text: `Signed in as ${name}`, timeoutMs: 15_000 })).data;
  if (!waited.matched) throw new Error(`${name}: sign-in did not finish`);
}

async function whoIsSignedIn(id, base) {
  await api('/api/v1/browser/navigate', { id, url: `${base}/account` });
  const { title, snapshot } = (await api('/api/v1/browser/snapshot', { id })).data;
  return { title, heading: /heading "([^"]+)"/.exec(snapshot)?.[1] ?? null };
}

const site = await demoSite();
const base = `http://127.0.0.1:${site.address().port}`;
const accounts = [
  { label: 'alice', proxyId: process.env.BROWZ_PROXY_A },
  { label: 'bob', proxyId: process.env.BROWZ_PROXY_B },
];
const made = [];
try {
  // One profile per account. Each has its own seed (fingerprint), folder (cookies, storage) and,
  // when you pass one, its own proxy. Two profiles without proxies share this machine's IP.
  for (const a of accounts) {
    const { data } = await api('/api/v1/profile/create', { name: `recipe-account-${a.label}-${Date.now()}`, ...(a.proxyId ? { proxyId: a.proxyId } : {}) });
    made.push({ ...a, id: data.id });
  }
  await Promise.all(made.map((a) => api('/api/v1/browser/start', { id: a.id })));
  // Both sign in at the same time, in their own browsers.
  await Promise.all(made.map((a) => signIn(a.id, base, a.label)));
  // Each profile still sees only its own account: the cookie lives in that profile alone.
  const seen = await Promise.all(made.map(async (a) => ({ profile: a.id, expected: a.label, ...(await whoIsSignedIn(a.id, base)) })));
  const ok = seen.every((s) => s.heading === `Signed in as ${s.expected}`);
  console.log(JSON.stringify({ ok, site: base, accounts: seen }, null, 2));
  process.exitCode = ok ? 0 : 1;
} finally {
  for (const a of made) {
    await api('/api/v1/browser/stop', { id: a.id }).catch(() => {});
    await api('/api/v1/profile/delete', { id: a.id }).catch(() => {});
    await api('/api/v1/profile/purge', { id: a.id }).catch((e) => console.error(String(e)));
  }
  site.close();
}

// Human in the loop: the agent drives a Browz profile through MCP, meets a sign-in page, hands the
// live window to the person at the computer (browz_request_human), waits, and then carries on in
// the same session, signed in. The agent never sees, types or asks for the password.
//
//   npm install
//   node index.mjs                 # against the demo sign-in page this script serves on 127.0.0.1
//
// The profile must run WITH a window (a person has to see it), so run this on the computer where
// the Browz app is open, not under `browz-mcp serve` (its profiles are headless and a handoff is
// refused there). Browz shows a notification and a banner with "I'm done"; this demo also finishes
// by itself when the page reaches /dashboard (doneWhenUrlContains).
//
//   BROWZ_MCP   the browz-mcp binary to run (default: npx -y @browz/mcp, which finds the app's)
import http from 'node:http';
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport, getDefaultEnvironment } from '@modelcontextprotocol/sdk/client/stdio.js';

// ── Demo site: a sign-in form (/login) and a page behind it (/dashboard) ───────────────────────
const html = (title, body) => `<!doctype html><html lang="en"><head><meta charset="utf-8"><title>${title}</title></head><body>${body}</body></html>`;
const site = http.createServer((req, res) => {
  const signedIn = /(?:^|;\s*)demo_session=ok/.test(req.headers.cookie || '');
  if (req.method === 'POST' && req.url === '/login') {
    req.resume();
    req.on('end', () => { res.writeHead(303, { 'Set-Cookie': 'demo_session=ok; Path=/; HttpOnly; SameSite=Lax', Location: '/dashboard' }); res.end(); });
    return;
  }
  res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
  if (req.url === '/dashboard' && signedIn) return res.end(html('Dashboard', '<h1>Welcome back</h1><p>Your orders: 3 open.</p>'));
  res.end(html('Sign in', `<h1>Sign in to the demo shop</h1><form method="post" action="/login">
    <label>Email <input name="email" type="email" autocomplete="username"></label>
    <label>Password <input name="password" type="password" autocomplete="current-password"></label>
    <button type="submit">Sign in</button></form>`));
});
await new Promise((r) => site.listen(0, '127.0.0.1', r));
const BASE = `http://127.0.0.1:${site.address().port}`;

// ── The local Browz MCP server over stdio. It reads the app's own credentials. ────────────────
const transport = new StdioClientTransport({
  command: process.env.BROWZ_MCP || 'npx',
  args: process.env.BROWZ_MCP ? [] : ['-y', '@browz/mcp'],
  env: { ...getDefaultEnvironment(), ...(process.env.BROWZ_DATA ? { BROWZ_DATA: process.env.BROWZ_DATA } : {}) },
  stderr: 'inherit',
});
const client = new Client({ name: 'browz-handoff-recipe', version: '1.0.0' });
await client.connect(transport);

async function tool(name, args, options = {}) {
  const result = await client.callTool({ name, arguments: args }, undefined, { timeout: 120_000, ...options });
  const text = result.content.filter((c) => c.type === 'text').map((c) => c.text).join('\n');
  if (result.isError) throw new Error(`${name}: ${text}`);
  return text;
}
/** The JSON object at the start of a tool's text (browz_profile_create may add a note after it). */
function firstJson(text) {
  const start = text.indexOf('{');
  for (let end = text.length; end > start; end = text.lastIndexOf('}', end - 1)) {
    try { return JSON.parse(text.slice(start, end + 1)); } catch { /* try a shorter span */ }
  }
  throw new Error(`no JSON in: ${text.slice(0, 200)}`);
}
const log = (step, detail = '') => console.log(`${step.padEnd(22)} ${detail}`);

let id;
try {
  // 1. A profile of its own for this task, started with a window.
  id = firstJson(await tool('browz_profile_create', { name: `recipe-handoff-${Date.now()}` })).id;
  await tool('browz_profile_start', { id, headless: false });
  log('profile started', id);

  // 2. Open the page and read it.
  await tool('browz_navigate', { id, url: `${BASE}/login` });
  const before = await tool('browz_snapshot', { id });
  const needsPerson = /NEEDS A PERSON/i.test(before) || /"challenge"/.test(before);
  log('snapshot', needsPerson ? 'sign-in page detected: NEEDS A PERSON' : 'no challenge flagged');

  // 3. Hand the window to the person. This call waits until they finish (or timeoutSec passes);
  //    Browz pauses automation on the profile meanwhile, so the agent cannot watch or type.
  log('browz_request_human', 'waiting for the person to sign in in the Browz window…');
  const outcome = await tool('browz_request_human', {
    id,
    reason: 'Sign in to the demo shop, then click "I\'m done" in Browz',
    kind: 'login',
    timeoutSec: 300,
    doneWhenUrlContains: '/dashboard',
  }, {
    timeout: 320_000,                 // a little longer than timeoutSec
    resetTimeoutOnProgress: true,
    onprogress: (p) => log('  progress', p.message || `${p.progress}${p.total ? `/${p.total}` : ''}`),
  });
  log('handoff returned', outcome.split('\n')[0].slice(0, 160));

  // 4. Carry on in the same session: take a NEW snapshot (refs from before the handoff are stale).
  const after = await tool('browz_snapshot', { id });
  const signedIn = after.includes('Welcome back');
  log('snapshot after', signedIn ? 'signed in: "Welcome back"' : 'not signed in');
  process.exitCode = signedIn ? 0 : 1;
} catch (e) {
  // timed_out, cancelled and closed come back as tool errors with a sentence saying what to do.
  log('stopped', String(e.message || e));
  process.exitCode = 1;
} finally {
  if (id) await tool('browz_session_end', { id, delete: true }).catch(() => {});
  await client.close();
  site.close();
}

// The agent's side: sign in to the demo site with a password and one-time code stored in Browz,
// without ever seeing either. A small MCP client (the official @modelcontextprotocol/sdk) runs the
// local Browz MCP server over stdio with a local agent key, so every call runs as that key: its
// scopes, its one profile and its allowed sites.
//
//   BROWZ_LOCAL_AGENT_TOKEN_FILE=./agent-key DEMO_URL=http://127.0.0.1:<port> PROFILE=<id> node agent.mjs
//
//   BROWZ_LOCAL_AGENT_TOKEN_FILE  file holding the agent key (from `browz agent-token create`)
//   DEMO_URL                      the demo site's address (demo-site.mjs prints it)
//   PROFILE                       the profile the key may use
//   BROWZ_MCP                     the browz-mcp binary (default: npx -y @browz/mcp, which finds the app's)
//   SHOW_WINDOW=1                 start the profile with a window (default: headless)
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport, getDefaultEnvironment } from '@modelcontextprotocol/sdk/client/stdio.js';

const { DEMO_URL, PROFILE: id, BROWZ_LOCAL_AGENT_TOKEN_FILE: keyFile } = process.env;
if (!DEMO_URL || !id || !keyFile) {
  console.error('Set DEMO_URL, PROFILE and BROWZ_LOCAL_AGENT_TOKEN_FILE (see README.md).');
  process.exit(2);
}

// The key reaches the MCP server through its environment, as a file name; never on a command line.
const env = { ...getDefaultEnvironment(), BROWZ_LOCAL_AGENT_TOKEN_FILE: keyFile };
if (process.env.BROWZ_DATA) env.BROWZ_DATA = process.env.BROWZ_DATA;
const transport = new StdioClientTransport({
  command: process.env.BROWZ_MCP || 'npx',
  args: process.env.BROWZ_MCP ? [] : ['-y', '@browz/mcp'],
  env,
  stderr: 'inherit',
});
const client = new Client({ name: 'browz-stored-sign-in-recipe', version: '1.0.0' });
await client.connect(transport);

/** Call a tool; resolves to { ok, text } so the refusals can be shown too. */
async function call(name, args) {
  const result = await client.callTool({ name, arguments: args }, undefined, { timeout: 120_000 });
  const text = result.content.filter((c) => c.type === 'text').map((c) => c.text).join('\n');
  return { ok: !result.isError, text };
}
async function tool(name, args) {
  const r = await call(name, args);
  if (!r.ok) throw new Error(`${name}: ${r.text}`);
  return r.text;
}
const log = (step, detail = '') => console.log(`${step.padEnd(24)} ${detail}`);
const indent = (text) => text.trim().split('\n').map((l) => `    ${l}`).join('\n');

/** The ref of the first snapshot line with this role and accessible name, e.g. `textbox "Password" [e7]`. */
function refOf(snapshot, role, name) {
  const line = snapshot.split('\n').find((l) => l.includes(`${role} "${name}`) && /\[e\d+\]/.test(l));
  if (!line) throw new Error(`no ${role} "${name}" in the snapshot:\n${snapshot}`);
  return /\[(e\d+)\]/.exec(line)[1];
}
const snap = () => tool('browz_snapshot', { id, mode: 'interactive' });

/** Wait for the next page. While the tab is between two pages its address is empty, which a key
 *  with allowed sites is not let into, so ask again for a moment until the new page is there. */
async function waitForUrl(part) {
  for (let i = 0; ; i++) {
    const r = await call('browz_wait', { id, urlContains: part, timeoutMs: 15_000 });
    if (r.ok) return;
    if (i >= 20 || !/allowed sites/.test(r.text)) throw new Error(`browz_wait: ${r.text}`);
    await new Promise((resolve) => setTimeout(resolve, 250));
  }
}

let started = false;
try {
  // 1. Open the sign-in page in the profile the key may use.
  await tool('browz_profile_start', { id, headless: process.env.SHOW_WINDOW !== '1' });
  started = true;
  await tool('browz_navigate', { id, url: `${DEMO_URL}/login` });
  const login = await snap();
  const hint = login.split('\n').find((l) => /SAVED SIGN-IN/i.test(l));
  log('snapshot', hint ? hint.trim() : 'sign-in page');

  // 2. Which stored sign-ins may this profile use here? Ids, labels and masked usernames only.
  const listed = await tool('browz_credential_list', { id });
  log('browz_credential_list', 'what the agent receives:');
  console.log(indent(listed));
  const creds = JSON.parse(listed.slice(listed.indexOf('['), listed.lastIndexOf(']') + 1));
  const cred = creds.find((c) => c.sites?.some((s) => s.startsWith(DEMO_URL))) || creds[0];
  if (!cred) throw new Error('no stored sign-in for this site');

  // 3. Browz types the username and the password itself. The agent gets back only "filled".
  const filledUser = await tool('browz_credential_fill', { id, credentialId: cred.id, ref: refOf(login, 'textbox', 'Username'), field: 'username' });
  log('fill username', filledUser.replace(/\s+/g, ' '));
  const filledPass = await tool('browz_credential_fill', { id, credentialId: cred.id, ref: refOf(login, 'textbox', 'Password'), field: 'password' });
  log('fill password', filledPass.replace(/\s+/g, ' '));

  // 4. The password is in the page now. Try to read it back: snapshots hide it, a screenshot is refused.
  const after = await snap();
  log('snapshot (password)', after.split('\n').find((l) => l.includes('"Password"'))?.trim());
  const shot = await call('browz_screenshot', { id });
  log('browz_screenshot', shot.ok ? 'returned an image' : `refused: ${shot.text.split('\n')[0]}`);

  // 5. Submit. The next page is a new document, so the read-back guard lifts with it.
  await tool('browz_act', { id, action: 'click', ref: refOf(after, 'button', 'Sign in') });
  await waitForUrl(cred.hasTotp ? '/verify' : '/account');

  // 6. The one-time code: Browz computes it from the stored seed and types it.
  if (cred.hasTotp) {
    const verify = await snap();
    const filledCode = await tool('browz_credential_fill', {
      id, credentialId: cred.id, ref: refOf(verify, 'textbox', 'Code from your authenticator app'), field: 'totp', submit: true,
    });
    log('fill totp', filledCode.replace(/\s+/g, ' '));
    await waitForUrl('/account');
  }

  // 7. Signed in?
  const account = await tool('browz_snapshot', { id });
  const heading = /Signed in as [\w-]+/.exec(account)?.[0];
  log('result', heading || 'not signed in');
  process.exitCode = heading ? 0 : 1;
} catch (e) {
  log('stopped', String(e.message || e));
  process.exitCode = 1;
} finally {
  if (started) await call('browz_profile_stop', { id }).catch(() => {});
  await client.close();
}

// A tiny demo site with a real sign-in: username, password, then a one-time code (TOTP), then a
// "Signed in as …" page. It runs on your computer only (127.0.0.1, a random port), so the recipe
// never signs in to anyone else's site.
//
//   node demo-site.mjs              # username + password + one-time code
//   node demo-site.mjs --no-totp    # username + password only
//
// Each start makes a fresh random password and TOTP seed. The site writes them to a file only you
// can read (mode 600), one per line in the order `browz credential add --password-stdin` reads
// them: the password, then the seed. Hand that file to Browz, then delete it (the site also deletes it
// when it stops); the secrets are never printed and never sit in this folder.
import http from 'node:http';
import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';

const USERNAME = 'demo-user';
const WITH_TOTP = !process.argv.includes('--no-totp');

// ── Fresh secrets for this run ─────────────────────────────────────────────────────────────────
const B32 = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ234567';
const base32 = (buf) => {
  let bits = '';
  for (const b of buf) bits += b.toString(2).padStart(8, '0');
  return bits.match(/.{1,5}/g).map((c) => B32[parseInt(c.padEnd(5, '0'), 2)]).join('');
};
const unbase32 = (s) => {
  const bits = [...s].map((c) => B32.indexOf(c).toString(2).padStart(5, '0')).join('');
  return Buffer.from(bits.match(/.{8}/g).map((b) => parseInt(b, 2)));
};
const password = randomBytes(18).toString('base64url');
const seed = base32(randomBytes(20));

/** RFC 6238: SHA-1, 30-second steps, 6 digits. */
function totp(secret, step) {
  const counter = Buffer.alloc(8);
  counter.writeBigUInt64BE(BigInt(step));
  const mac = createHmac('sha1', unbase32(secret)).update(counter).digest();
  const off = mac[mac.length - 1] & 15;
  return String((mac.readUInt32BE(off) & 0x7fffffff) % 1_000_000).padStart(6, '0');
}
const codeOk = (code) => {
  const now = Math.floor(Date.now() / 30_000);
  return [now - 1, now, now + 1].some((s) => totp(seed, s) === code);
};
const same = (a, b) => a.length === b.length && timingSafeEqual(Buffer.from(a), Buffer.from(b));

const dir = mkdtempSync(join(tmpdir(), 'browz-demo-signin-'));
const secretsFile = join(dir, 'secrets');
writeFileSync(secretsFile, WITH_TOTP ? `${password}\n${seed}\n` : `${password}\n`, { mode: 0o600 });

// ── The site ───────────────────────────────────────────────────────────────────────────────────
const sessions = new Map(); // cookie value -> 'password' (code still due) | 'ok'
const page = (title, body) => `<!doctype html><html lang="en"><head><meta charset="utf-8"><title>${title}</title>
<style>body{font:16px system-ui;max-width:420px;margin:48px auto}label{display:block;margin:12px 0}input{display:block;width:100%;padding:6px}</style>
</head><body>${body}</body></html>`;
const loginForm = (msg = '') => page('Sign in', `<h1>Sign in to the demo site</h1>${msg ? `<p role="alert">${msg}</p>` : ''}
<form method="post" action="/login">
  <label>Username <input name="username" type="text" autocomplete="username"></label>
  <label>Password <input name="password" type="password" autocomplete="current-password"></label>
  <button type="submit">Sign in</button>
</form>`);
const codeForm = (msg = '') => page('Verification code', `<h1>Enter your verification code</h1>${msg ? `<p role="alert">${msg}</p>` : ''}
<form method="post" action="/verify">
  <label>Code from your authenticator app <input name="code" type="text" inputmode="numeric" autocomplete="one-time-code"></label>
  <button type="submit">Verify</button>
</form>`);

function readForm(req) {
  return new Promise((resolve) => {
    let body = '';
    req.on('data', (c) => { body += c; if (body.length > 4096) req.destroy(); });
    req.on('end', () => resolve(new URLSearchParams(body)));
  });
}
const send = (res, status, html, headers = {}) => { res.writeHead(status, { 'Content-Type': 'text/html; charset=utf-8', ...headers }); res.end(html); };
const redirect = (res, to, headers = {}) => { res.writeHead(303, { Location: to, ...headers }); res.end(); };

const server = http.createServer(async (req, res) => {
  const sid = /(?:^|;\s*)demo_sid=([A-Za-z0-9_-]+)/.exec(req.headers.cookie || '')?.[1];
  const state = sid && sessions.get(sid);
  const path = new URL(req.url, 'http://x').pathname;

  if (req.method === 'POST' && path === '/login') {
    const f = await readForm(req);
    if (f.get('username') !== USERNAME || !same(f.get('password') || '', password)) {
      return send(res, 401, loginForm('Wrong username or password.'));
    }
    const id = randomBytes(16).toString('base64url');
    sessions.set(id, WITH_TOTP ? 'password' : 'ok');
    return redirect(res, WITH_TOTP ? '/verify' : '/account', { 'Set-Cookie': `demo_sid=${id}; Path=/; HttpOnly; SameSite=Lax` });
  }
  if (path === '/verify' && state === 'password') {
    if (req.method !== 'POST') return send(res, 200, codeForm());
    const f = await readForm(req);
    if (!codeOk((f.get('code') || '').trim())) return send(res, 401, codeForm('That code is not right. Try the current one.'));
    sessions.set(sid, 'ok');
    return redirect(res, '/account');
  }
  if (path === '/account') {
    if (state === 'ok') return send(res, 200, page('Account', `<h1>Signed in as ${USERNAME}</h1><p>Your demo account is open.</p>`));
    return redirect(res, '/login');
  }
  if (path === '/login' || path === '/') return send(res, 200, loginForm());
  send(res, 404, page('Not found', '<h1>Not found</h1>'));
});

server.listen(0, '127.0.0.1', () => {
  const url = `http://127.0.0.1:${server.address().port}`;
  console.log(`demo site     ${url}/login`);
  console.log(`username      ${USERNAME}`);
  console.log(`secrets file  ${secretsFile}  (${WITH_TOTP ? 'password, then TOTP seed' : 'password'}; mode 600)`);
  console.log('Press Ctrl+C to stop.');
});
// The secrets file goes when the site stops (try-it.sh deletes it as soon as Browz has stored it).
for (const sig of ['SIGINT', 'SIGTERM']) process.on(sig, () => { rmSync(dir, { recursive: true, force: true }); server.close(); process.exit(0); });

{
  "mcpServers": {
    "browz": {
      "command": "npx",
      "args": ["-y", "@browz/mcp"],
      "env": { "BROWZ_LOCAL_AGENT_TOKEN_FILE": "${BROWZ_AGENT_KEY_FILE}" }
    }
  }
}

## Signing in with Browz

Use the Browz MCP tools (`browz_*`) for every web page in this project.

- Read a page with `browz_snapshot` and act with `browz_act` on the refs it returns (`e12`). Take a new
  snapshot after every navigation.
- To sign in, use a sign-in the person stored in Browz. A snapshot of a sign-in page names it
  (`SAVED SIGN-IN: …`); `browz_credential_list` with the profile `id` lists every one this profile may
  use. Fill each field with `browz_credential_fill`: its `credentialId`, the field's ref, and `field`
  `username`, `password` or `totp` (for a verification code). Pass `submit: true` on the last field of
  a form. Browz types the value and tells you only that it was filled.
- Never type, guess or ask for a password or code yourself. If no stored sign-in fits the page, call
  `browz_request_human` with a short reason and wait.
- While a filled password is in a page, screenshots are refused and snapshots show it as
  `[value=<redacted>]`. Submitting the form loads the next page and lifts that.

// A scheduled, headless check: for each URL, open an isolated throwaway Browz session through the
// MCP server that `browz-mcp serve` runs, read the page, save a screenshot, and wipe the session.
//
//   npm install
//   BROWZ_MCP_TOKEN_FILE=~/.browz-mcp-token node run.mjs https://example.com/ https://example.org/
//
// Run it from cron, a systemd timer or launchd (files next to this one). Exits non-zero when any
// page fails, so the scheduler (or your alerting) sees it.
//
//   BROWZ_MCP_URL         MCP endpoint (default http://127.0.0.1:50334/mcp, what `serve` prints)
//   BROWZ_MCP_TOKEN_FILE  file holding the bearer token (or BROWZ_MCP_TOKEN with the token itself)
//   BROWZ_PROXY           none (default) | pool | a proxy id from browz_proxy_list
//   OUT_DIR               where screenshots and report.json go (default ./out)
import { mkdir, readFile, writeFile } from 'node:fs/promises';
import { join } from 'node:path';
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';

const MCP_URL = process.env.BROWZ_MCP_URL || 'http://127.0.0.1:50334/mcp';
const TOKEN = (process.env.BROWZ_MCP_TOKEN
  || (process.env.BROWZ_MCP_TOKEN_FILE ? await readFile(process.env.BROWZ_MCP_TOKEN_FILE, 'utf8') : '')).trim();
if (!TOKEN) throw new Error('set BROWZ_MCP_TOKEN_FILE (or BROWZ_MCP_TOKEN) to the bearer token `serve` uses');
const PROXY = !process.env.BROWZ_PROXY || process.env.BROWZ_PROXY === 'none' ? 'none'
  : process.env.BROWZ_PROXY === 'pool' ? 'pool' : { proxyId: process.env.BROWZ_PROXY };
const OUT_DIR = process.env.OUT_DIR || 'out';
const URLS = process.argv.slice(2).length ? process.argv.slice(2) : ['https://example.com/'];

const client = new Client({ name: 'browz-scheduled-check', version: '1.0.0' });
await client.connect(new StreamableHTTPClientTransport(new URL(MCP_URL), {
  requestInit: { headers: { Authorization: `Bearer ${TOKEN}` } },
}));

/** Call a Browz tool; a tool error becomes an exception carrying Browz's own message. */
async function tool(name, args) {
  const result = await client.callTool({ name, arguments: args }, undefined, { timeout: 120_000 });
  const text = result.content.filter((c) => c.type === 'text').map((c) => c.text).join('\n');
  if (result.isError) throw new Error(`${name}: ${text}`);
  return { result, text };
}
/** The JSON object at the start of a tool's text (some tools add a note after it). */
function firstJson(text) {
  const start = text.indexOf('{');
  for (let end = text.length; end > start; end = text.lastIndexOf('}', end - 1)) {
    try { return JSON.parse(text.slice(start, end + 1)); } catch { /* shorter */ }
  }
  throw new Error(`no JSON in: ${text.slice(0, 200)}`);
}

await mkdir(OUT_DIR, { recursive: true });
const stamp = new Date().toISOString().replace(/[:.]/g, '-');
const report = { startedAt: new Date().toISOString(), mcp: MCP_URL, pages: [] };

for (const [i, url] of URLS.entries()) {
  const entry = { url, ok: false };
  let sessionId;
  try {
    // A fresh, isolated profile for this check; wiped by browz_session_close.
    const open = firstJson((await tool('browz_session_open', { task: `scheduled check of ${url}`, mode: 'ephemeral', proxy: PROXY, ttlMinutes: 30 })).text);
    sessionId = open.sessionId;
    const id = open.profileId;                       // the page tools take the profile id
    await tool('browz_navigate', { id, url });
    const snap = (await tool('browz_snapshot', { id, mode: 'compact', maxTokens: 1500 })).text;
    entry.title = /^Title: (.+)$/m.exec(snap)?.[1] ?? null;   // the snapshot starts with URL: and Title: lines
    entry.snapshotStart = snap.split('\n').slice(0, 6);
    const shot = (await tool('browz_screenshot', { id })).result.content.find((c) => c.type === 'image');
    if (shot) {
      entry.screenshot = join(OUT_DIR, `${stamp}-${i + 1}.png`);
      await writeFile(entry.screenshot, Buffer.from(shot.data, 'base64'));
    }
    entry.ok = true;
  } catch (e) {
    entry.error = String(e.message || e);
  } finally {
    if (sessionId) {
      const closed = await tool('browz_session_close', { sessionId }).catch((e) => ({ text: String(e.message) }));
      entry.cleanup = closed.text.includes('"cleaned"') ? 'cleaned' : closed.text.slice(0, 200);
    }
  }
  report.pages.push(entry);
}

await client.close();
report.ok = report.pages.every((p) => p.ok);
await writeFile(join(OUT_DIR, 'report.json'), JSON.stringify(report, null, 2));
console.log(JSON.stringify(report, null, 2));
process.exitCode = report.ok ? 0 : 1;