@solarisdk/mcp 0.2.1 → 0.3.0

package/README.md

@@ -86,6 +86,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_API_KEY` | | `SOLARI_API_KEY` | separate key for the browser gateway, for environments where the browser and desktop key stores are split |
 
 ## Tools
 

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,19 +94,40 @@ 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. " +
@@ -88,16 +157,44 @@ 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.
                 return text({
                     sessionId: s.sessionId,
@@ -111,13 +208,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 +236,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 +307,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 +336,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 +360,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 +373,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 +388,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 +401,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 */
+        }
+    }));
+}