@solarisdk/mcp 0.4.3 → 0.4.4

package/README.md

@@ -187,7 +187,7 @@ cookie count and origins it stored, so they can see what was persisted.
 | `solari_read_file` / `solari_write_file` / `solari_list_files` | Guest filesystem |
 | `solari_get_preview_url` | Public preview URL for an in-guest port |
 | `solari_screenshot` | Capture the desktop as a PNG (image content) |
-| `solari_click` / `solari_type` / `solari_key` | Desktop mouse/keyboard |
+| `solari_click` / `solari_type` / `solari_key` | Desktop mouse/keyboard (`solari_click` takes optional `doubleClick` + `button: left\|right\|middle`) |
 | `solari_open_app` | Launch an app on the desktop |
 
 (The desktop GUI tools require a `solari_desktop_create` session; they error on

package/dist/browser-tools/auth.d.ts

@@ -0,0 +1,2 @@
+import { type BrowserToolCtx, type Tool } from "./context.js";
+export declare function makeAuthTools(ctx: BrowserToolCtx): Record<string, Tool>;

package/dist/browser-tools/auth.js

@@ -0,0 +1,403 @@
+// Profiles + login: saved sign-in state, password-manager auto-login, and the
+// human handoff flow (hot mid-session rescue + cold profile seeding).
+import { z } from "zod";
+import { apiError, HANDOFF_POLL_MS, redact, text } from "./context.js";
+export function makeAuthTools(ctx) {
+    const { cfg, deps, api, need } = ctx;
+    return {
+        solari_browser_profiles: {
+            description: "List saved browser profiles for this account. A profile is a stored signed-in state " +
+                "(cookies + localStorage) that solari_browser_create({profileId}) replays, so the " +
+                "session starts already logged in.\n" +
+                "Check here FIRST when a task will need a login: if a profile for that site already " +
+                "exists, use it and no human is involved at all. `version` is 1 and `populated` is " +
+                "false for a profile nobody has signed into yet — that one still needs " +
+                "solari_browser_login({profileName}).",
+            inputSchema: {},
+            handler: async () => {
+                const res = await api(cfg, "GET", "/profiles");
+                if (res.status !== 200)
+                    await apiError(res, "list profiles");
+                const rows = (await res.json());
+                return text({
+                    profiles: rows.map((p) => ({
+                        profileId: p.id,
+                        name: p.name,
+                        version: p.version,
+                        populated: Boolean(p.storageStateS3Key),
+                        lastUsedAt: p.lastUsedAt ?? null,
+                    })),
+                });
+            },
+        },
+        solari_browser_autologin_status: {
+            description: "Check whether this account can sign in to websites automatically, and get a direct " +
+                "setup link if it cannot.\n" +
+                "Call this when a task will clearly need a login, BEFORE you start — if nothing is set " +
+                "up you can tell the user once, up front, with a link, instead of interrupting them " +
+                "mid-run. Also worth calling if a login keeps needing a human.\n" +
+                "Returns the connected password managers, the sites already configured, and `setupUrl`. " +
+                "If `configured` is false, SHOW setupUrl TO THE USER: it opens the page where they " +
+                "connect a password manager. You cannot do that step for them — it needs a credential " +
+                "that must never pass through you — but the link removes all the guesswork.",
+            inputSchema: {},
+            handler: async () => {
+                const res = await api(cfg, "GET", "/vault/status");
+                if (res.status === 501) {
+                    return text({
+                        configured: false,
+                        available: false,
+                        note: "Automatic sign-in is not available on this deployment.",
+                    });
+                }
+                if (res.status !== 200)
+                    await apiError(res, "auto-login status");
+                const d = (await res.json());
+                const managers = d.managers ?? [];
+                const sites = d.sites ?? [];
+                return text({
+                    configured: managers.length > 0,
+                    available: true,
+                    managers: managers.map((m) => ({ name: m.name, provider: m.provider, vaults: m.vaults })),
+                    sites,
+                    setupUrl: d.setupUrl ?? null,
+                    next: managers.length === 0
+                        ? "No password manager is connected. Show setupUrl to the user — it takes them " +
+                            "straight to the page where they connect one, after which logins happen with no " +
+                            "human involved."
+                        : sites.length === 0
+                            ? "A password manager is connected but no sites use it yet. Add one with " +
+                                "solari_browser_autologin_site, or the user can do it at setupUrl."
+                            : "Automatic sign-in is set up. Sessions will log in to these sites on their own.",
+                });
+            },
+        },
+        solari_browser_autologin_site: {
+            description: "Tell Solari to sign in to a site automatically using a connected password manager.\n" +
+                "`domain` is the site, e.g. 'github.com'. `manager` is the NAME of a connected password " +
+                "manager (see solari_browser_autologin_status) — omit it to mean 'remember the session " +
+                "but ask a human for a fresh login'. `item` is an optional 'Vault/Item' path for when " +
+                "one site has several logins; omit it to match by site.\n" +
+                "This only says WHICH credential to use — it never handles the credential itself.",
+            inputSchema: {
+                domain: z.string(),
+                manager: z.string().optional(),
+                item: z.string().optional(),
+            },
+            handler: async (a) => {
+                const res = await api(cfg, "POST", "/vault/sites", {
+                    domain: a.domain,
+                    ...(typeof a.manager === "string" ? { manager: a.manager } : {}),
+                    ...(typeof a.item === "string" ? { item: a.item } : {}),
+                });
+                if (res.status !== 200)
+                    await apiError(res, "configure auto-login site");
+                const d = (await res.json());
+                return text({
+                    ...d,
+                    next: "Set. The next session that hits a login wall on this site signs in automatically " +
+                        "if the credential is found; otherwise a human is asked, as before.",
+                });
+            },
+        },
+        solari_browser_login: {
+            description: "Get this session signed in. Call it the moment you hit a login form, a 2FA prompt, or "
+                + "anything asking for a password — you must never handle credentials yourself.\n"
+                + "It tries the account's connected password manager FIRST: if one is set up for this "
+                + "site, you are signed in automatically and NO human is involved — the reply says "
+                + 'signedIn:true and you simply carry on. Otherwise it falls back to asking a human.\n'
+                + "Two ways to call it:\n" +
+                "HOT — pass `sessionId` when you are ALREADY on a login wall mid-task. The user gets a " +
+                "live view of the exact page you are on and types into it; you resume on that same page.\n" +
+                "COLD — pass `profileName` when you know a task will need a login and no session is open " +
+                "yet. The user signs in once in a profile editor, and every later " +
+                "solari_browser_create({profileId}) starts already authenticated. Prefer this when you " +
+                "can: nobody has to be watching mid-run. The profile is created if it does not exist.\n" +
+                "Pass exactly one of the two. Either way, SHOW THE RETURNED URL TO THE USER, then call " +
+                "solari_browser_await_login.\n" +
+                "In the HOT case your access to that session is REVOKED while the handoff is open — " +
+                "deliberately, so you cannot observe what they type — and the link expires in 5 minutes. " +
+                "Cold links last longer and revoke nothing, because there is no session yet.\n" +
+                "`reason` is required and is shown to the user — say plainly which site is asking and " +
+                "what for, because they are being asked to type a password on your say-so.",
+            inputSchema: {
+                sessionId: z.string().optional(),
+                profileName: z.string().optional(),
+                reason: z.string(),
+            },
+            handler: async (a) => {
+                const sessionId = typeof a.sessionId === "string" ? a.sessionId : "";
+                const profileName = typeof a.profileName === "string" ? a.profileName.trim() : "";
+                if (Boolean(sessionId) === Boolean(profileName)) {
+                    throw new Error("Pass exactly one of sessionId (rescue a live session) or profileName (seed a " +
+                        "profile before you start).");
+                }
+                // ── COLD: seed a profile, no session involved ────────────────────
+                if (profileName) {
+                    const listRes = await api(cfg, "GET", "/profiles");
+                    if (listRes.status !== 200)
+                        await apiError(listRes, "list profiles");
+                    const rows = (await listRes.json());
+                    const match = rows.find((p) => (p.name ?? "").toLowerCase() === profileName.toLowerCase());
+                    let profileId = match?.id ?? "";
+                    if (!profileId) {
+                        const mk = await api(cfg, "POST", "/profiles", { name: profileName });
+                        if (mk.status !== 200 && mk.status !== 201)
+                            await apiError(mk, "create profile");
+                        profileId = (await mk.json()).id ?? "";
+                        if (!profileId)
+                            throw new Error("profile created but no id returned");
+                    }
+                    const hRes = await api(cfg, "POST", `/profiles/${encodeURIComponent(profileId)}/login-handoff`, {
+                        reason: a.reason,
+                    });
+                    if (hRes.status !== 200)
+                        await apiError(hRes, "cold login request");
+                    const h = (await hRes.json());
+                    return text({
+                        mode: "cold",
+                        profileId,
+                        profileName,
+                        handoffId: h.handoffId,
+                        url: h.url,
+                        expiresAt: h.expiresAt,
+                        // Echoed so await_login can tell a fresh save from the state it
+                        // started in — the version bump IS the completion signal.
+                        sinceVersion: h.version,
+                        next: `Show the url to the user, then call solari_browser_await_login({ profileId: ` +
+                            `"${profileId}", sinceVersion: ${h.version} }).`,
+                    });
+                }
+                // ── HOT: rescue the live session ─────────────────────────────────
+                const e = need(sessionId);
+                // Try the account's password manager FIRST. If a vault is connected and
+                // this site is configured, the gateway signs in on its own and no human
+                // is involved at all — we never see the credential either way. Only
+                // escalate to a human when that cannot work. Best-effort: any failure
+                // here just falls through to the handoff below, which is the behaviour
+                // that existed before.
+                let setupUrl = null;
+                try {
+                    const auto = await api(cfg, "POST", `/sessions/${encodeURIComponent(sessionId)}/autologin`, {});
+                    if (auto.status === 200) {
+                        const r = (await auto.json());
+                        if (r.outcome === "already_authenticated" || r.outcome === "vault_login") {
+                            return text({
+                                mode: "auto",
+                                signedIn: true,
+                                via: r.outcome === "vault_login" ? "password manager" : "saved session",
+                                next: "You are signed in — carry on. No human was needed.",
+                            });
+                        }
+                        // The chain could not sign in and ALREADY OPENED a handoff for us.
+                        // Falling through here would POST /handoff for a session that now
+                        // has one open, which the gateway correctly refuses with 409
+                        // HandoffAlreadyOpen -- and the url we were just handed would be
+                        // thrown away, leaving an open handoff that nobody can reach and a
+                        // session frozen until it expires. Use what we were given.
+                        if (r.outcome === "human_required" && r.handoffUrl) {
+                            try {
+                                await e.browser.close();
+                            }
+                            catch {
+                                /* the gateway is severing this socket anyway */
+                            }
+                            return text({
+                                mode: "hot",
+                                handoffId: r.handoffId,
+                                url: r.handoffUrl,
+                                // Why the password manager could not do this unaided. Surfaced
+                                // because otherwise a mis-configured site is indistinguishable
+                                // from an unsupported one.
+                                ...(r.reason ? { autoLoginFailed: r.reason } : {}),
+                                ...(r.setupRequired && r.setupUrl ? { setupUrl: r.setupUrl } : {}),
+                                next: "Show the url to the user, then call solari_browser_await_login. " +
+                                    "Your access to this session is revoked until they finish.",
+                            });
+                        }
+                        // Nothing is configured for this site. Remember the setup link so
+                        // it can be offered alongside the handoff below — the user is
+                        // already being interrupted, so this is the cheapest possible
+                        // moment to tell them how to stop being interrupted next time.
+                        if (r.setupRequired && r.setupUrl)
+                            setupUrl = r.setupUrl;
+                    }
+                }
+                catch {
+                    /* fall through to the human handoff */
+                }
+                const res = await api(cfg, "POST", `/sessions/${encodeURIComponent(sessionId)}/handoff`, { reason: a.reason });
+                if (res.status !== 200)
+                    await apiError(res, "handoff request");
+                const h = (await res.json());
+                // The gateway is severing our socket right now. Drop the local handle
+                // rather than leave a half-dead Browser object that throws confusing
+                // Target-closed errors on every subsequent tool call.
+                try {
+                    await e.browser.close();
+                }
+                catch {
+                    /* already gone — that is the point */
+                }
+                // Prefer the short link when the gateway offers one — it is far easier
+                // to relay to someone on a phone. Fall back to the long URL for older
+                // gateways that do not return shortUrl yet.
+                const showUrl = h.shortUrl ?? h.url;
+                return text({
+                    mode: "hot",
+                    handoffId: h.handoffId,
+                    url: showUrl,
+                    fullUrl: h.url,
+                    expiresAt: h.expiresAt,
+                    // Offered only when the account has NOTHING configured for this site.
+                    // The user is already being interrupted, so this is the cheapest
+                    // moment to show them how to stop being interrupted next time.
+                    ...(setupUrl
+                        ? {
+                            setupUrl,
+                            tip: "This account has no password manager connected for this site, so a human is " +
+                                "needed every time. Connecting one at the setupUrl lets future logins happen " +
+                                "automatically. MENTION THIS TO THE USER along with the sign-in link.",
+                        }
+                        : {}),
+                    next: "Show the url to the user, then call solari_browser_await_login.",
+                });
+            },
+        },
+        solari_browser_save_profile: {
+            description: "Save this session's signed-in state (cookies + localStorage) into an existing profile, " +
+                "so future sessions start already logged in and no human is needed again. Pass the " +
+                "profileId to overwrite.\n" +
+                "ONLY do this when the user has asked you to remember the login. It is deliberately not " +
+                "automatic: a saved profile holds live session cookies, which bypass 2FA — it is a " +
+                "credential store, and it should exist because someone chose it. If they have not said " +
+                "so, ask first.\n" +
+                "Returns what was captured (cookie count and origins) so the user can see what they " +
+                "just persisted.",
+            inputSchema: {
+                sessionId: z.string(),
+                profileId: z.string(),
+            },
+            handler: async (a) => {
+                need(a.sessionId);
+                const res = await api(cfg, "POST", `/sessions/${encodeURIComponent(a.sessionId)}/save-profile`, { profileId: a.profileId });
+                if (res.status !== 200)
+                    await apiError(res, "save profile");
+                const body = (await res.json());
+                return text({
+                    ...body,
+                    note: "Future sessions can use this with solari_browser_create({profileId}).",
+                });
+            },
+        },
+        solari_browser_await_login: {
+            description: "Wait for the human to finish the sign-in you requested with solari_browser_login. " +
+                "Blocks until they are done, the link expires, or timeoutMs elapses. Returns only a " +
+                "status — never anything the user typed. On 'completed' the session is yours again, " +
+                "on the same page, still signed in, and you can carry on where you left off. On " +
+                "'expired' or 'timeout' the user did not finish: ask if they still want to, and call " +
+                "solari_browser_login again for a fresh link rather than retrying this.",
+            inputSchema: {
+                sessionId: z.string().optional(),
+                profileId: z.string().optional(),
+                sinceVersion: z.number().optional(),
+                handoffId: z.string().optional(),
+                timeoutMs: z.number().optional(),
+            },
+            handler: async (a) => {
+                const sessionId = typeof a.sessionId === "string" ? a.sessionId : "";
+                const profileId = typeof a.profileId === "string" ? a.profileId : "";
+                if (Boolean(sessionId) === Boolean(profileId)) {
+                    throw new Error("Pass exactly one of sessionId (hot handoff) or profileId (cold handoff) — the " +
+                        "same one solari_browser_login returned.");
+                }
+                // Clamp: never spin forever, never poll so briefly the human has no
+                // chance. Defaults to the handoff's own 5-minute life.
+                const requested = typeof a.timeoutMs === "number" ? a.timeoutMs : 300_000;
+                const deadline = Date.now() + Math.min(Math.max(requested, 5_000), 600_000);
+                let status = "pending";
+                // ── COLD: watch the profile's version, which the editor's save bumps.
+                // Deliberately NOT "did a storageState appear": re-signing into a
+                // profile that already had one must also count as completed.
+                if (profileId) {
+                    const since = typeof a.sinceVersion === "number" ? a.sinceVersion : 0;
+                    let version = since;
+                    while (Date.now() < deadline) {
+                        const res = await api(cfg, "GET", "/profiles");
+                        if (res.status !== 200)
+                            await apiError(res, "profile status");
+                        const rows = (await res.json());
+                        const row = rows.find((p) => p.id === profileId);
+                        if (!row)
+                            throw new Error(`profile ${profileId} no longer exists`);
+                        version = typeof row.version === "number" ? row.version : since;
+                        if (version > since) {
+                            status = "completed";
+                            break;
+                        }
+                        await new Promise((r) => setTimeout(r, HANDOFF_POLL_MS));
+                    }
+                    if (status !== "completed")
+                        status = "timeout";
+                    return text({
+                        mode: "cold",
+                        status,
+                        profileId,
+                        version,
+                        next: status === "completed"
+                            ? `Signed in and saved. Use solari_browser_create({ profileId: "${profileId}" }) ` +
+                                "and you will start already authenticated."
+                            : "The user did not finish. Ask if they still want to, then call " +
+                                "solari_browser_login again for a fresh link.",
+                    });
+                }
+                const e = need(sessionId);
+                while (Date.now() < deadline) {
+                    const q = typeof a.handoffId === "string" && a.handoffId
+                        ? `?handoffId=${encodeURIComponent(a.handoffId)}`
+                        : "";
+                    const res = await api(cfg, "GET", `/sessions/${encodeURIComponent(sessionId)}/handoff${q}`);
+                    if (res.status !== 200)
+                        await apiError(res, "handoff status");
+                    const body = (await res.json());
+                    status = body.status ?? "none";
+                    // "none" means no open handoff and no id to look up — treat as done
+                    // rather than spinning; the caller can re-mint if that was wrong.
+                    if (status !== "pending")
+                        break;
+                    await new Promise((r) => setTimeout(r, HANDOFF_POLL_MS));
+                }
+                if (status === "pending")
+                    status = "timeout";
+                // Reconnect: the handoff severed our old socket on purpose, so the
+                // stored handle is dead even on success. Re-dial and re-adopt the page
+                // the human left us on, which is the whole point of a HOT handoff —
+                // the agent resumes mid-flow instead of starting over.
+                let resumed = false;
+                if (status === "completed" || status === "none") {
+                    try {
+                        const browser = await deps.connect(e.cdpEndpoint);
+                        const pages = await browser.pages();
+                        const page = pages.find((p) => !p.isClosed()) ?? (await browser.newPage());
+                        e.browser = browser;
+                        e.page = page;
+                        resumed = true;
+                    }
+                    catch (err) {
+                        return text({
+                            status,
+                            resumed: false,
+                            note: "the sign-in finished but the session could not be re-attached: " +
+                                redact(err instanceof Error ? err.message : String(err)),
+                        });
+                    }
+                }
+                return text({
+                    status,
+                    resumed,
+                    ...(resumed ? { url: e.page.url() } : {}),
+                });
+            },
+        },
+    };
+}

package/dist/browser-tools/capture.d.ts

@@ -0,0 +1,2 @@
+import { type BrowserToolCtx, type Tool } from "./context.js";
+export declare function makeCaptureTools(ctx: BrowserToolCtx): Record<string, Tool>;

package/dist/browser-tools/capture.js

@@ -0,0 +1,67 @@
+// Reading/screenshotting the current page.
+import { z } from "zod";
+import { MAX_LINKS, text } from "./context.js";
+export function makeCaptureTools(ctx) {
+    const { need, activePage, capText } = ctx;
+    return {
+        solari_browser_read_page: {
+            description: "Read the current page. format 'text' (default) returns visible text; 'links' returns " +
+                "clickable links {text, href}; 'html' returns HTML with scripts/styles stripped. " +
+                "Large output is truncated with an explicit marker.",
+            inputSchema: {
+                sessionId: z.string(),
+                format: z.enum(["text", "links", "html"]).optional(),
+            },
+            handler: async (a) => {
+                const page = await activePage(need(a.sessionId));
+                const fmt = a.format ?? "text";
+                if (fmt === "links") {
+                    const all = await page.$$eval("a[href]", (as) => as
+                        .map((el) => ({
+                        text: (el.textContent ?? "").trim().slice(0, 120),
+                        href: el.href,
+                    }))
+                        .filter((l) => l.text));
+                    // Truncate whole elements — slicing the serialized JSON would hand
+                    // the model unparseable output.
+                    const shown = all.slice(0, MAX_LINKS);
+                    return text({ url: page.url(), shown: shown.length, total: all.length, links: shown });
+                }
+                let out;
+                if (fmt === "html") {
+                    out = await page.evaluate(() => {
+                        const d = document.cloneNode(true);
+                        d.querySelectorAll("script,style,noscript,svg").forEach((n) => n.remove());
+                        return d.documentElement?.outerHTML ?? "";
+                    });
+                }
+                else {
+                    out = await page.evaluate(() => document.body?.innerText ?? "");
+                }
+                return text(`${page.url()}\n\n${capText(out, "chars")}`);
+            },
+        },
+        solari_browser_screenshot: {
+            description: "Screenshot the browser session's current page (JPEG). fullPage captures the whole " +
+                "scrollable page (may be downscaled by the client if very tall).",
+            inputSchema: {
+                sessionId: z.string(),
+                fullPage: z.boolean().optional(),
+                quality: z.number().min(1).max(100).optional(),
+            },
+            handler: async (a) => {
+                const page = await activePage(need(a.sessionId));
+                const buf = await page.screenshot({
+                    type: "jpeg",
+                    quality: a.quality ?? 75,
+                    fullPage: Boolean(a.fullPage),
+                });
+                return {
+                    content: [
+                        { type: "image", data: Buffer.from(buf).toString("base64"), mimeType: "image/jpeg" },
+                    ],
+                };
+            },
+        },
+    };
+}

package/dist/browser-tools/context.d.ts

@@ -0,0 +1,79 @@
+import type { Browser, Page } from "puppeteer-core";
+import type { ZodTypeAny } from "zod";
+export interface McpResult {
+    content: Array<{
+        type: "text";
+        text: string;
+    } | {
+        type: "image";
+        data: string;
+        mimeType: string;
+    }>;
+    isError?: boolean;
+}
+export interface Tool {
+    description: string;
+    inputSchema: Record<string, ZodTypeAny>;
+    handler: (args: Record<string, unknown>) => Promise<McpResult>;
+}
+export interface BrowserConfig {
+    apiKey: string;
+    baseUrl: string;
+}
+export interface BrowserEntry {
+    sessionId: string;
+    browser: Browser;
+    page: Page;
+    expiresAt: string;
+    recording: boolean;
+    /**
+     * The session's raw CDP endpoint, kept so the handoff flow can RECONNECT.
+     *
+     * A login handoff severs the agent's socket gateway-side — deliberately, so
+     * the agent cannot watch the human type. That kills this entry's puppeteer
+     * handle, so resuming afterwards needs a fresh connect rather than the dead
+     * one. Without this the agent "resumes" into a Target-closed error.
+     */
+    cdpEndpoint: string;
+}
+export interface BrowserRegistry {
+    sessions: Map<string, BrowserEntry>;
+}
+export declare const text: (o: unknown) => McpResult;
+export declare const MAX_PAGE_TEXT = 30000;
+export declare const MAX_LINKS = 200;
+export declare const CDP_DIAL_ATTEMPTS = 3;
+/** How often await_login re-checks handoff status. */
+export declare const HANDOFF_POLL_MS = 2000;
+/** Signed ws/wss capability URLs must never reach the model or a log. */
+export declare const redact: (s: string) => string;
+export declare function api(cfg: BrowserConfig, method: string, path: string, body?: unknown): Promise<Response>;
+/**
+ * Turn a gateway error into a model-safe message: only the documented
+ * {code,message} fields, never the raw body (which on a 2xx-shaped response
+ * carries the session's bearer-capability ws URLs).
+ */
+export declare function apiError(res: Response, what: string): Promise<never>;
+/** Release a browser session gateway-side. Safe to call for unknown ids. */
+export declare function releaseBrowserSession(cfg: BrowserConfig, id: string, fetchApi?: typeof api): Promise<void>;
+export interface BrowserDeps {
+    connect: (cdpEndpoint: string) => Promise<Browser>;
+    fetchApi: typeof api;
+}
+/**
+ * Everything a browser-tools/* capability module needs, gathered once by
+ * makeBrowserToolset and passed to each module's factory — rather than each
+ * module reaching back into browser.ts (which would close over its own
+ * `reg`/`deps`, duplicating state instead of sharing it).
+ */
+export interface BrowserToolCtx {
+    cfg: BrowserConfig;
+    reg: BrowserRegistry;
+    deps: BrowserDeps;
+    /** deps.fetchApi, hoisted for convenience (matches the old local `api`). */
+    api: typeof api;
+    need: (id: string) => BrowserEntry;
+    /** The newest attached, non-blank page — see browser.ts for the rationale. */
+    activePage: (e: BrowserEntry) => Promise<Page>;
+    capText: (s: string, what: string) => string;
+}

package/dist/browser-tools/context.js

@@ -0,0 +1,74 @@
+export const text = (o) => ({
+    content: [{ type: "text", text: typeof o === "string" ? o : JSON.stringify(o, null, 2) }],
+});
+export const MAX_PAGE_TEXT = 30_000;
+export const MAX_LINKS = 200;
+export const CDP_DIAL_ATTEMPTS = 3;
+/** How often await_login re-checks handoff status. */
+export const HANDOFF_POLL_MS = 2_000;
+/** Signed ws/wss capability URLs must never reach the model or a log. */
+export const redact = (s) => s.replace(/wss?:\/\/[^\s"']+/gi, "[redacted-ws-url]");
+export async function api(cfg, method, path, body) {
+    // Session create can block up to 60s gateway-side waiting for a slot.
+    const res = await fetch(`${cfg.baseUrl}${path}`, {
+        method,
+        headers: {
+            authorization: `Bearer ${cfg.apiKey}`,
+            ...(body ? { "content-type": "application/json" } : {}),
+        },
+        ...(body ? { body: JSON.stringify(body) } : {}),
+        signal: AbortSignal.timeout(90_000),
+    });
+    return res;
+}
+/**
+ * Turn a gateway error into a model-safe message: only the documented
+ * {code,message} fields, never the raw body (which on a 2xx-shaped response
+ * carries the session's bearer-capability ws URLs).
+ */
+export async function apiError(res, what) {
+    let detail = "";
+    try {
+        const raw = await res.text();
+        try {
+            const j = JSON.parse(raw);
+            detail = [j.code, j.error ?? j.message].filter(Boolean).join(": ");
+        }
+        catch {
+            detail = redact(raw).slice(0, 200);
+        }
+    }
+    catch {
+        /* body unavailable */
+    }
+    throw new Error(`${what} failed: HTTP ${res.status}${detail ? ` ${detail}` : ""}`);
+}
+/** Release a browser session gateway-side. Safe to call for unknown ids. */
+export async function releaseBrowserSession(cfg, id, fetchApi = api) {
+    const api_ = fetchApi;
+    // Gateway bearer verification can transiently 401 (control-plane verify blip
+    // / auth-cache churn) and a failed release leaks the pool slot until TTL, so
+    // retry transient statuses before giving up.
+    let res = await api_(cfg, "DELETE", `/sessions/${encodeURIComponent(id)}`);
+    for (let i = 0; i < 2 && (res.status === 401 || res.status === 429 || res.status >= 500); i++) {
+        await new Promise((r) => setTimeout(r, 1500));
+        res = await api_(cfg, "DELETE", `/sessions/${encodeURIComponent(id)}`);
+    }
+    if (res.status === 404) {
+        // Bare 404 = already gone (fine). 404 + InvalidSessionId = the gateway
+        // refused the id and released NOTHING.
+        let code;
+        try {
+            code = (await res.json()).code;
+        }
+        catch {
+            /* no body */
+        }
+        if (code === "InvalidSessionId") {
+            throw new Error(`release failed: gateway rejected sessionId (session may still be live)`);
+        }
+        return;
+    }
+    if (res.status !== 204 && !res.ok)
+        await apiError(res, "session release");
+}

package/dist/browser-tools/interaction.d.ts

@@ -0,0 +1,2 @@
+import { type BrowserToolCtx, type Tool } from "./context.js";
+export declare function makeInteractionTools(ctx: BrowserToolCtx): Record<string, Tool>;