@solarisdk/mcp 0.2.2 → 0.3.1

package/README.md

@@ -20,7 +20,8 @@ registry**: `*_create` tools return a `sessionId`, and the rest take it.
 Point any MCP client at the hosted Streamable HTTP endpoint with your API key:
 
 - **Prod:** `https://mcp.getsolari.com/mcp`
-- **Staging:** `https://mcp-sta.solaribrowser.com/mcp`
+- **Staging:** currently NOT deployed — the us-east-1 ALB it rode was
+  removed in the us-west-1 migration and its DNS record has been deleted.
 
 Claude Desktop / claude.ai: **Settings → Connectors → Add custom connector**,
 URL as above, and send `Authorization: Bearer slr_live_…`. Or in
@@ -68,8 +69,9 @@ lifecycles — re-attach with `solari_connect`).
       "env": {
         "SOLARI_API_KEY": "slr_live_…"
         // optional overrides (defaults hit prod https://api.getsolari.com):
-        // "SOLARI_BASE_URL":    "https://desktops-sta.solaribrowser.com",  // sandbox/desktop gateway
-        // "SOLARI_BROWSER_URL": "https://api-sta.solaribrowser.com"        // browser gateway
+        // optional staging override — ONE host now serves both gateways:
+        // "SOLARI_BASE_URL":    "https://api-sta.getsolari.com",
+        // "SOLARI_BROWSER_URL": "https://api-sta.getsolari.com"
       }
     }
   }
@@ -85,7 +87,7 @@ Chat, Code and Cowork alike.
 |---|---|---|---|
 | `SOLARI_API_KEY` | ✅ | — | unified `slr_live_…` key (works on both gateways) |
 | `SOLARI_BASE_URL` | | `https://api.getsolari.com` | sandbox/desktop gateway |
-| `SOLARI_BROWSER_URL` | | `SOLARI_BASE_URL` → prod | cloud-browser gateway (differs from `SOLARI_BASE_URL` on staging) |
+| `SOLARI_BROWSER_URL` | | `SOLARI_BASE_URL` → prod | cloud-browser gateway. Both prod (`api.getsolari.com`) and staging (`api-sta.getsolari.com`) now path-route browser AND desktop on one host, so this rarely needs setting |
 | `SOLARI_BROWSER_API_KEY` | | `SOLARI_API_KEY` | separate key for the browser gateway, for environments where the browser and desktop key stores are split |
 
 ## Tools
@@ -94,7 +96,7 @@ Chat, Code and Cowork alike.
 
 | Tool | What it does |
 |---|---|
-| `solari_browser_create` | Start a browser session (`stealth`, `proxy`, `captcha`, `recording`, `profileId`) → `sessionId` |
+| `solari_browser_create` | Start a browser session (`mode`, `proxy`, `captcha`, `recording`, `profileId`) → `{sessionId, mode, captcha}` |
 | `solari_browser_navigate` | Go to a URL → `{url, title, status}` |
 | `solari_browser_read_page` | Page text / links / HTML (30k-char cap) |
 | `solari_browser_screenshot` | JPEG screenshot (image content) |
@@ -103,6 +105,39 @@ Chat, Code and Cowork alike.
 | `solari_browser_replay_url` | rrweb replay URL (needs `recording: true`) |
 | `solari_browser_close` | Release the session |
 
+### Browser mode — stealth by default
+
+`solari_browser_create` defaults to **`mode: "stealth"`** (the anti-bot hardened pool). A bare
+call with no arguments gets it; the model does not have to ask.
+
+This used to be an optional `stealth: true` boolean, and in practice models did not opt in — so
+sessions quietly landed on the fast pool and got blocked by bot detection. The failure looked
+like "the site is broken" rather than "we chose the wrong pool", which is the worst way for a
+default to be wrong.
+
+`mode: "fast"` is the explicit opt-out: lower latency, for sites you already know do not
+fingerprint or block automation (internal tools, localhost, your own app, plain docs). If a page
+returns a block/captcha/challenge in fast mode, close the session and retry on stealth.
+
+`proxy` and `captcha` are stealth-only upstream and are now **rejected** in fast mode rather than
+silently dropped — a quietly unproxied request leaks the origin IP, which is the one thing the
+caller was trying to avoid. The response echoes the resolved `mode`, so a later block is
+actionable.
+
+The deprecated `stealth` boolean still works in both directions for existing callers
+(`stealth: false` still means fast); an explicit `mode` wins when both are supplied.
+
+**Captcha auto-solving is on by default too**, for the same reason: an option a model has to opt
+into does not get used, and the resulting failure ("the page is a challenge screen") reads as a
+broken site rather than a missing flag. Pass **`captcha: false`** to opt out — solving costs money
+and adds latency, so turn it off for sites you know never challenge.
+
+The default *follows the pool* rather than being a flat `true`: captcha is stealth-only upstream,
+so a flat default would make a plain `mode: "fast"` call throw on an option the caller never
+asked for. Stealth ⇒ on, fast ⇒ off, explicit value always wins. Asking for `captcha: true`
+*together with* `mode: "fast"` is a real contradiction and is refused. The response echoes the
+resolved `captcha` alongside `mode`.
+
 ### Sandboxes + desktops
 
 | Tool | What it does |
@@ -137,11 +172,46 @@ npm run build:bundle # esbuild → dist/solari-mcp.bundle.cjs (single file, no n
 
 ```bash
 SOLARI_API_KEY=slr_live_… \
-SOLARI_BASE_URL=https://desktops-sta.solaribrowser.com \
-SOLARI_BROWSER_URL=https://api-sta.solaribrowser.com \
+SOLARI_BASE_URL=https://api-sta.getsolari.com \
+SOLARI_BROWSER_URL=https://api-sta.getsolari.com \
 node test/live-smoke.mjs            # add SMOKE_SERVER=dist/solari-mcp.bundle.cjs to test the bundle
 ```
 
 Round-trips browser create→navigate→read→screenshot→search→close, sandbox
 create→exec→run_code→kill, and desktop create→screenshot→kill as a real MCP
 client over stdio.
+
+## Hosted connector — where it runs (ops)
+
+All of this is **manual**, not terraform.
+
+| | Prod | Staging |
+|---|---|---|
+| URL | `https://mcp.getsolari.com/mcp` | *(not deployed — see above)* |
+| Region | **us-west-1** | — |
+| Cluster | `solari-desktops-prod-usw1-gw` | — |
+| Service / taskdef | `solari-mcp-prod-usw1` | — |
+| Image | ECR `solari-mcp:prod` (us-west-1) | — |
+| Ingress | listener rule **prio 20** on the gateway ALB, host-header match | — |
+
+It rides the desktop gateway's ALB, so it is **coupled to that ALB's lifetime**.
+
+### ⚠️ `/health` returning 200 does NOT mean the connector is up
+
+The desktop gateway answers `GET /health` with `{"ok":true}` too. If DNS points at the
+gateway instead of the connector — which is exactly what happened on 2026-07-28, when the
+us-west-1 migration deleted the old us-east-1 gateway ALB and re-aliased
+`mcp.getsolari.com` to the new one — `/health` still returns 200 while **every MCP call
+404s**. The connector was down and the health check was green.
+
+Two checks that actually discriminate:
+
+```sh
+curl -s https://mcp.getsolari.com/health      # connector's body has a "sessions" field; the gateway's does not
+curl -s -o /dev/null -w '%{http_code}\n' -XPOST https://mcp.getsolari.com/mcp \
+     -H 'content-type: application/json' -d '{}'
+#   401 = the connector (auth required)   404 = the gateway is answering — connector NOT reachable
+```
+
+**If you move or rebuild the desktop gateway ALB, you must re-point this service too** —
+target group, listener rule, and the Route53 alias all live on that ALB.

package/dist/browser.d.ts

@@ -31,9 +31,13 @@ export interface BrowserRegistry {
     sessions: Map<string, BrowserEntry>;
 }
 declare function api(cfg: BrowserConfig, method: string, path: string, body?: unknown): Promise<Response>;
+/** 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;
 }
 export declare function makeBrowserToolset(cfg: BrowserConfig, reg: BrowserRegistry, deps?: BrowserDeps): Record<string, Tool>;
+/** Release every browser session in a registry (used on eviction/shutdown). */
+export declare function releaseAllBrowserSessions(cfg: BrowserConfig, reg: BrowserRegistry, fetchApi?: typeof api): Promise<void>;
 export {};

package/dist/browser.js

@@ -10,6 +10,10 @@ const text = (o) => ({
     content: [{ type: "text", text: typeof o === "string" ? o : JSON.stringify(o, null, 2) }],
 });
 const MAX_PAGE_TEXT = 30_000;
+const MAX_LINKS = 200;
+const CDP_DIAL_ATTEMPTS = 3;
+/** Signed ws/wss capability URLs must never reach the model or a log. */
+const redact = (s) => s.replace(/wss?:\/\/[^\s"']+/gi, "[redacted-ws-url]");
 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}`, {
@@ -23,20 +27,64 @@ async function api(cfg, method, path, body) {
     });
     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).
+ */
 async function apiError(res, what) {
     let detail = "";
     try {
-        detail = await res.text();
+        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.slice(0, 500)}`);
+    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");
 }
 const defaultDeps = {
     connect: (cdpEndpoint) => puppeteer.connect({
         browserWSEndpoint: cdpEndpoint,
-        defaultViewport: { width: 1280, height: 800 },
+        // null = adopt the pool browser's real window. Forcing a viewport here
+        // applies an Emulation override, which makes window/screen metrics
+        // inconsistent and weakens stealth sessions.
+        defaultViewport: null,
     }),
     fetchApi: api,
 };
@@ -46,37 +94,106 @@ export function makeBrowserToolset(cfg, reg, deps = defaultDeps) {
         const e = reg.sessions.get(id);
         if (!e)
             throw new Error(`unknown browser sessionId: ${id} (create one with solari_browser_create)`);
+        // The signed CDP URL is not re-dialable after the session expires, so say
+        // so plainly instead of surfacing a raw "Target closed".
+        if (e.expiresAt && Date.parse(e.expiresAt) <= Date.now()) {
+            reg.sessions.delete(id);
+            throw new Error(`browser session ${id} expired at ${e.expiresAt}; create a new one with solari_browser_create`);
+        }
         return e;
     };
-    // The agent may have navigated into a popup/new tab; act on the most
-    // recently opened page that is still attached.
+    // Act on the newest attached, non-blank page so a click that opened a tab or
+    // popup is followed rather than silently ignored.
     const activePage = async (e) => {
-        if (!e.page.isClosed())
-            return e.page;
-        const pages = await e.browser.pages();
-        if (pages.length === 0)
+        let pages = [];
+        try {
+            pages = await e.browser.pages();
+        }
+        catch {
+            /* browser gone; fall through to the cached page */
+        }
+        const usable = pages.filter((p) => !p.isClosed());
+        if (usable.length === 0) {
+            if (!e.page.isClosed())
+                return e.page;
             throw new Error("no open pages in this browser session");
-        e.page = pages[pages.length - 1];
+        }
+        const named = usable.filter((p) => {
+            const u = p.url();
+            return u && u !== "about:blank";
+        });
+        e.page = (named.length ? named : usable)[named.length ? named.length - 1 : usable.length - 1];
         return e.page;
     };
+    const capText = (s, what) => s.length > MAX_PAGE_TEXT
+        ? `${s.slice(0, MAX_PAGE_TEXT)}\n…[truncated ${s.length - MAX_PAGE_TEXT} of ${s.length} ${what}]`
+        : s;
     return {
         solari_browser_create: {
             description: "Start a Solari cloud browser session. Use this whenever you need to browse the web. " +
-                "Returns a sessionId for the other solari_browser_* tools. Options: stealth (anti-bot " +
-                "hardened pool), proxy ('smart' | country code like 'us' — requires stealth), captcha " +
-                "auto-solving (requires stealth), recording (rrweb replay).",
+                "Returns a sessionId for the other solari_browser_* tools.\n" +
+                "mode defaults to 'stealth' — the anti-bot hardened pool. Just call this with no " +
+                "arguments and you get it; you do NOT need to ask for stealth explicitly. Stealth is " +
+                "the right default for the open web: ordinary sites work fine on it, and it is what " +
+                "keeps bot-detection from blocking the session.\n" +
+                "Pass mode:'fast' ONLY for a site you already know does not fingerprint or block " +
+                "automation (internal tools, localhost, your own app, plain docs/API pages) and you " +
+                "want the lower-latency pool. If a page in fast mode returns a block/captcha/challenge, " +
+                "close the session and retry with mode:'stealth'.\n" +
+                "captcha auto-solving is ALSO on by default (it follows the pool: on for stealth, off " +
+                "for fast). Pass captcha:false to turn it off — solving a challenge costs money and " +
+                "adds latency, so switch it off for sites you know never challenge.\n" +
+                "proxy ('smart' | country code like 'us') REQUIRES stealth, as does captcha; both are " +
+                "rejected if you ask for them explicitly in fast mode. recording gives an rrweb replay.",
             inputSchema: {
+                mode: z.enum(["stealth", "fast"]).optional(),
+                /** @deprecated use mode. Kept so existing callers keep working. */
                 stealth: z.boolean().optional(),
                 proxy: z.string().optional(),
+                /** Defaults to ON (following the pool). Pass false to opt out. */
                 captcha: z.boolean().optional(),
                 recording: z.boolean().optional(),
                 profileId: z.string().optional(),
             },
             handler: async (a) => {
+                // STEALTH IS THE DEFAULT. Models consistently declined to opt in when it
+                // was an optional boolean, so sessions silently landed on the fast pool
+                // and got blocked by bot detection — the failure looked like "the site
+                // is broken" rather than "we picked the wrong pool". Defaulting on, with
+                // an explicit escape hatch, removes that whole class of confusion.
+                //
+                // Precedence: explicit mode wins; then the deprecated stealth boolean
+                // (so `stealth:false` still means fast for old callers); then stealth.
+                const stealth = a.mode !== undefined ? a.mode === "stealth" : (a.stealth ?? true);
+                // CAPTCHA IS ALSO ON BY DEFAULT — same reasoning as stealth: a model
+                // that has to opt in does not, and the resulting failure ("the page is
+                // a challenge screen") reads as a broken site rather than a missing
+                // option.
+                //
+                // The default FOLLOWS the pool rather than being a flat `true`, because
+                // captcha is stealth-only upstream. A flat true would make plain
+                // mode:'fast' throw on an option the caller never asked for, turning the
+                // escape hatch into a dead end. So: stealth ⇒ on, fast ⇒ off, and an
+                // explicit value always wins (captcha:false is the opt-out).
+                const captcha = a.captcha ?? stealth;
+                // proxy/captcha are stealth-only upstream. Previously a fast-pool
+                // session with proxy came back with the proxy silently dropped and only
+                // a note in the response; fail loudly instead — a silently unproxied
+                // request can leak the origin IP, which is the one thing the caller was
+                // trying to avoid. Only an EXPLICIT ask conflicts; the captcha default
+                // simply turns itself off in fast mode.
+                if (!stealth) {
+                    const needsStealth = [a.proxy ? "proxy" : "", a.captcha === true ? "captcha" : ""].filter(Boolean);
+                    if (needsStealth.length) {
+                        throw new Error(`${needsStealth.join(" and ")} ${needsStealth.length > 1 ? "require" : "requires"} ` +
+                            `stealth, but mode is 'fast'. ` +
+                            `Drop ${needsStealth.length > 1 ? "them" : "it"} or use mode:'stealth'.`);
+                    }
+                }
                 const body = {};
-                if (a.stealth)
+                if (stealth)
                     body.stealth = true;
-                if (a.captcha)
+                if (captcha)
                     body.captcha = true;
                 if (a.recording)
                     body.recording = true;
@@ -88,21 +205,55 @@ export function makeBrowserToolset(cfg, reg, deps = defaultDeps) {
                 if (res.status !== 201)
                     await apiError(res, "session create");
                 const s = (await res.json());
-                const browser = await deps.connect(s.cdpEndpoint);
-                const pages = await browser.pages();
-                const page = pages[0] ?? (await browser.newPage());
-                reg.sessions.set(s.sessionId, {
-                    sessionId: s.sessionId,
-                    browser,
-                    page,
-                    expiresAt: s.expiresAt,
-                    recording: Boolean(a.recording),
-                });
+                // cdpEndpoint is optional on the wire; derive it from wsEndpoint the
+                // way the official SDK does.
+                const cdp = s.cdpEndpoint ?? s.wsEndpoint?.replace("/ws/", "/cdp/");
+                if (!cdp)
+                    throw new Error("gateway returned no cdpEndpoint or wsEndpoint");
+                // From here on the session is BILLABLE. Any failure before it is
+                // registered must release it, or it leaks until TTL with an id the
+                // model never saw.
+                try {
+                    let browser;
+                    let lastErr;
+                    for (let i = 0; i < CDP_DIAL_ATTEMPTS; i++) {
+                        try {
+                            browser = await deps.connect(cdp);
+                            break;
+                        }
+                        catch (err) {
+                            // A freshly-started session has a transient upstream window.
+                            lastErr = err;
+                            await new Promise((r) => setTimeout(r, 500 * (i + 1)));
+                        }
+                    }
+                    if (!browser)
+                        throw lastErr ?? new Error("could not connect to the browser");
+                    const pages = await browser.pages();
+                    const page = pages.find((p) => !p.isClosed()) ?? (await browser.newPage());
+                    reg.sessions.set(s.sessionId, {
+                        sessionId: s.sessionId,
+                        browser,
+                        page,
+                        expiresAt: s.expiresAt,
+                        recording: Boolean(a.recording),
+                    });
+                }
+                catch (err) {
+                    await releaseBrowserSession(cfg, s.sessionId, api).catch(() => { });
+                    throw new Error(`browser session started but could not be attached (released it): ${redact(err instanceof Error ? err.message : String(err))}`);
+                }
                 // Proxy silently degrades rather than erroring — surface what we got.
+                // Echo the resolved mode back: the caller did not necessarily pick it
+                // (stealth is the default), and knowing which pool it landed on is what
+                // makes a later block actionable — "retry on stealth" vs "this site
+                // blocks us even hardened".
                 return text({
                     sessionId: s.sessionId,
+                    mode: stealth ? "stealth" : "fast",
+                    captcha,
                     expiresAt: s.expiresAt,
-                    proxy: s.proxy ?? (a.proxy ? "NOT APPLIED (check plan/stealth)" : undefined),
+                    proxy: s.proxy ?? (a.proxy ? "NOT APPLIED (check plan)" : undefined),
                 });
             },
         },
@@ -111,13 +262,27 @@ export function makeBrowserToolset(cfg, reg, deps = defaultDeps) {
             inputSchema: { sessionId: z.string(), url: z.string() },
             handler: async (a) => {
                 const page = await activePage(need(a.sessionId));
-                const resp = await page.goto(a.url, { waitUntil: "domcontentloaded", timeout: 60_000 });
+                let url = a.url.trim();
+                if (!/^[a-z][a-z0-9+.-]*:/i.test(url))
+                    url = `https://${url}`;
+                const scheme = url.slice(0, url.indexOf(":")).toLowerCase();
+                if (scheme !== "http" && scheme !== "https") {
+                    throw new Error(`refusing to navigate to a non-http(s) URL (${scheme}:)`);
+                }
+                // Block link-local / cloud metadata so page content can't steer the
+                // agent into reading the browser pool's instance credentials.
+                const host = new URL(url).hostname;
+                if (/^(169\.254\.|127\.|\[?::1\]?$|localhost$|metadata\.google)/i.test(host)) {
+                    throw new Error(`refusing to navigate to internal host ${host}`);
+                }
+                const resp = await page.goto(url, { waitUntil: "domcontentloaded", timeout: 60_000 });
                 return text({ url: page.url(), title: await page.title(), status: resp?.status() ?? null });
             },
         },
         solari_browser_read_page: {
             description: "Read the current page. format 'text' (default) returns visible text; 'links' returns " +
-                "clickable links {text, href}; 'html' returns raw HTML. Output is truncated to 30k chars.",
+                "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(),
@@ -125,35 +290,45 @@ export function makeBrowserToolset(cfg, reg, deps = defaultDeps) {
             handler: async (a) => {
                 const page = await activePage(need(a.sessionId));
                 const fmt = a.format ?? "text";
-                let out;
-                if (fmt === "html") {
-                    out = await page.content();
-                }
-                else if (fmt === "links") {
-                    const links = await page.$$eval("a[href]", (as) => as
+                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)
-                        .slice(0, 200));
-                    out = JSON.stringify(links, null, 2);
+                        .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 ?? "");
                 }
-                const truncated = out.length > MAX_PAGE_TEXT;
-                return text(`${page.url()}\n\n${out.slice(0, MAX_PAGE_TEXT)}${truncated ? "\n…[truncated]" : ""}`);
+                return text(`${page.url()}\n\n${capText(out, "chars")}`);
             },
         },
         solari_browser_screenshot: {
-            description: "Screenshot the browser session's current page (JPEG image).",
-            inputSchema: { sessionId: z.string(), fullPage: z.boolean().optional() },
+            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: 75,
+                    quality: a.quality ?? 75,
                     fullPage: Boolean(a.fullPage),
                 });
                 return {
@@ -186,17 +361,28 @@ export function makeBrowserToolset(cfg, reg, deps = defaultDeps) {
             },
         },
         solari_browser_type: {
-            description: "Type text into the page. Optionally focus a CSS selector first. Set pressEnter to submit.",
+            description: "Type text into the page. Optionally focus a CSS selector first. clear:true replaces the " +
+                "field's existing value (otherwise text is appended at the caret). pressEnter submits.",
             inputSchema: {
                 sessionId: z.string(),
                 text: z.string(),
                 selector: z.string().optional(),
+                clear: z.boolean().optional(),
                 pressEnter: z.boolean().optional(),
             },
             handler: async (a) => {
                 const page = await activePage(need(a.sessionId));
-                if (a.selector)
-                    await page.click(a.selector);
+                if (a.selector) {
+                    const sel = a.selector;
+                    await page.focus(sel);
+                    if (a.clear) {
+                        await page.$eval(sel, (el) => {
+                            const f = el;
+                            f.value = "";
+                            f.dispatchEvent(new Event("input", { bubbles: true }));
+                        });
+                    }
+                }
                 await page.keyboard.type(a.text, { delay: 20 });
                 if (a.pressEnter)
                     await page.keyboard.press("Enter");
@@ -204,12 +390,22 @@ export function makeBrowserToolset(cfg, reg, deps = defaultDeps) {
             },
         },
         solari_browser_key: {
-            description: "Press a key in the browser session (e.g. 'Enter', 'Escape', 'ArrowDown', 'PageDown').",
+            description: "Press a key in the browser session (e.g. 'Enter', 'Escape', 'ArrowDown', 'PageDown'). " +
+                "Chords use '+' (e.g. 'Control+a').",
             inputSchema: { sessionId: z.string(), key: z.string() },
             handler: async (a) => {
                 const page = await activePage(need(a.sessionId));
-                // eslint-disable-next-line @typescript-eslint/no-explicit-any
-                await page.keyboard.press(a.key);
+                const parts = a.key.split("+").filter(Boolean);
+                const key = parts.pop();
+                for (const m of parts)
+                    await page.keyboard.down(m);
+                try {
+                    await page.keyboard.press(key);
+                }
+                finally {
+                    for (const m of parts.reverse())
+                        await page.keyboard.up(m);
+                }
                 return text({ ok: true });
             },
         },
@@ -218,17 +414,11 @@ export function makeBrowserToolset(cfg, reg, deps = defaultDeps) {
             inputSchema: { sessionId: z.string(), expression: z.string() },
             handler: async (a) => {
                 const page = await activePage(need(a.sessionId));
-                const result = await page.evaluate((expr) => {
-                    // eslint-disable-next-line no-eval
-                    const v = (0, eval)(expr);
-                    try {
-                        return JSON.parse(JSON.stringify(v ?? null));
-                    }
-                    catch {
-                        return String(v);
-                    }
-                }, a.expression);
-                return text(result);
+                // Pass the expression as a string: puppeteer sends it as a
+                // debugger-originated Runtime.evaluate, which is exempt from the
+                // page's CSP. Wrapping it in eval() inside page context is not.
+                const result = await page.evaluate(a.expression);
+                return text(result === undefined ? "undefined" : result);
             },
         },
         solari_browser_replay_url: {
@@ -237,6 +427,10 @@ export function makeBrowserToolset(cfg, reg, deps = defaultDeps) {
             inputSchema: { sessionId: z.string() },
             handler: async (a) => {
                 const id = a.sessionId;
+                const known = reg.sessions.get(id);
+                if (known && !known.recording) {
+                    throw new Error(`session ${id} was not created with recording: true, so it has no replay`);
+                }
                 const res = await api(cfg, "GET", `/sessions/${encodeURIComponent(id)}/replay-url`);
                 if (!res.ok)
                     await apiError(res, "replay-url");
@@ -248,6 +442,9 @@ export function makeBrowserToolset(cfg, reg, deps = defaultDeps) {
             inputSchema: { sessionId: z.string() },
             handler: async (a) => {
                 const id = a.sessionId;
+                // Release FIRST: if it fails, keep the registry entry so the model can
+                // retry rather than losing the handle to a still-billing session.
+                await releaseBrowserSession(cfg, id, api);
                 const e = reg.sessions.get(id);
                 if (e) {
                     try {
@@ -258,31 +455,28 @@ export function makeBrowserToolset(cfg, reg, deps = defaultDeps) {
                     }
                     reg.sessions.delete(id);
                 }
-                // Gateway bearer verification can transiently 401 (control-plane
-                // verify blip / auth-cache churn); a failed release leaks the pool
-                // slot until TTL, so retry once before surfacing the error.
-                let res = await api(cfg, "DELETE", `/sessions/${encodeURIComponent(id)}`);
-                if (res.status === 401) {
-                    await new Promise((r) => setTimeout(r, 1500));
-                    res = await api(cfg, "DELETE", `/sessions/${encodeURIComponent(id)}`);
-                }
-                // 204 = released; bare 404 = already gone (fine); 404 + InvalidSessionId = real failure.
-                if (res.status === 404) {
-                    let code;
-                    try {
-                        code = (await res.json()).code;
-                    }
-                    catch {
-                        /* no body */
-                    }
-                    if (code === "InvalidSessionId")
-                        throw new Error("release failed: gateway rejected sessionId");
-                }
-                else if (res.status !== 204) {
-                    await apiError(res, "session release");
-                }
                 return text({ ok: true });
             },
         },
     };
 }
+/** Release every browser session in a registry (used on eviction/shutdown). */
+export async function releaseAllBrowserSessions(cfg, reg, fetchApi = api) {
+    const ids = [...reg.sessions.keys()];
+    await Promise.all(ids.map(async (id) => {
+        const e = reg.sessions.get(id);
+        reg.sessions.delete(id);
+        try {
+            await releaseBrowserSession(cfg, id, fetchApi);
+        }
+        catch (err) {
+            console.error(`solari-mcp: failed to release browser session ${id}:`, err);
+        }
+        try {
+            await e?.browser.disconnect();
+        }
+        catch {
+            /* already gone */
+        }
+    }));
+}