@solarisdk/mcp 0.3.0 → 0.3.2

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,15 +96,82 @@ 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) |
 | `solari_browser_click` / `solari_browser_type` / `solari_browser_key` | Interact (selector or x/y) |
 | `solari_browser_evaluate` | Run a JS expression on the page |
 | `solari_browser_replay_url` | rrweb replay URL (needs `recording: true`) |
+| `solari_browser_login` | Ask a HUMAN to sign in — returns a short-lived URL to show them |
+| `solari_browser_await_login` | Wait for them to finish, then re-attach the session |
+| `solari_browser_save_profile` | Persist the signed-in state to a profile (explicit — see below) |
 | `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`.
+
+### Login handoff — the agent never touches a password
+
+When a session hits a login form or 2FA prompt, the agent calls
+`solari_browser_login` and shows the returned URL to the user. They open it, get
+a **live view of the exact page the agent is on**, and type their credentials
+directly into it. The agent then calls `solari_browser_await_login` and carries
+on where it left off — same page, now signed in.
+
+**The agent is locked out for the duration.** The gateway refuses its CDP
+upgrades *and* severs the socket it already holds, so it cannot watch the typing
+even though it is mid-session. That is enforced at the proxy, not here: a check
+in this layer would be advisory, because the agent speaks raw CDP.
+
+Two consequences worth knowing:
+
+- Other browser tools on that session fail while a handoff is open. That is the
+  freeze working, not a bug.
+- `await_login` **reconnects** on success. The sever kills the stored puppeteer
+  handle, so resuming needs a fresh dial; without it the agent would "resume"
+  into a Target-closed error.
+
+The link lives 5 minutes and is single-use. If it lapses, call
+`solari_browser_login` again — the session is untouched.
+
+**Saving the login for next time is explicit.** `solari_browser_save_profile`
+captures the session's cookies + localStorage into a profile, and future runs
+skip the human entirely via `create({profileId})`. It is deliberately *not*
+automatic: those are live session cookies, which bypass 2FA, so the profile is a
+credential store and should exist because the user chose it. The tool reports the
+cookie count and origins it stored, so they can see what was persisted.
+
 ### Sandboxes + desktops
 
 | Tool | What it does |
@@ -137,11 +206,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

@@ -26,6 +26,15 @@ interface BrowserEntry {
     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>;

package/dist/browser.js

@@ -12,6 +12,8 @@ const text = (o) => ({
 const MAX_PAGE_TEXT = 30_000;
 const MAX_LINKS = 200;
 const CDP_DIAL_ATTEMPTS = 3;
+/** How often await_login re-checks handoff status. */
+const HANDOFF_POLL_MS = 2_000;
 /** 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) {
@@ -131,21 +133,69 @@ export function makeBrowserToolset(cfg, reg, deps = defaultDeps) {
     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;
@@ -189,6 +239,7 @@ export function makeBrowserToolset(cfg, reg, deps = defaultDeps) {
                         page,
                         expiresAt: s.expiresAt,
                         recording: Boolean(a.recording),
+                        cdpEndpoint: cdp,
                     });
                 }
                 catch (err) {
@@ -196,10 +247,263 @@ export function makeBrowserToolset(cfg, reg, deps = defaultDeps) {
                     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),
+                });
+            },
+        },
+        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_login: {
+            description: "Ask a HUMAN to sign in, so you never handle credentials yourself. 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);
+                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 */
+                }
+                return text({
+                    mode: "hot",
+                    handoffId: h.handoffId,
+                    url: h.url,
+                    expiresAt: h.expiresAt,
+                    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/solari-mcp-http.bundle.cjs

@@ -113676,6 +113676,7 @@ var text = (o) => ({
 var MAX_PAGE_TEXT = 3e4;
 var MAX_LINKS = 200;
 var CDP_DIAL_ATTEMPTS = 3;
+var HANDOFF_POLL_MS = 2e3;
 var redact = (s) => s.replace(/wss?:\/\/[^\s"']+/gi, "[redacted-ws-url]");
 async function api(cfg, method, path12, body) {
   const res = await fetch(`${cfg.baseUrl}${path12}`, {
@@ -113768,18 +113769,31 @@ function makeBrowserToolset(cfg, reg, deps = defaultDeps) {
 \u2026[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' \u2014 requires stealth), captcha auto-solving (requires stealth), recording (rrweb replay).",
+      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.\nmode defaults to 'stealth' \u2014 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.\nPass 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'.\ncaptcha auto-solving is ALSO on by default (it follows the pool: on for stealth, off for fast). Pass captcha:false to turn it off \u2014 solving a challenge costs money and adds latency, so switch it off for sites you know never challenge.\nproxy ('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: external_exports.enum(["stealth", "fast"]).optional(),
+        /** @deprecated use mode. Kept so existing callers keep working. */
         stealth: external_exports.boolean().optional(),
         proxy: external_exports.string().optional(),
+        /** Defaults to ON (following the pool). Pass false to opt out. */
         captcha: external_exports.boolean().optional(),
         recording: external_exports.boolean().optional(),
         profileId: external_exports.string().optional()
       },
       handler: async (a2) => {
+        const stealth = a2.mode !== void 0 ? a2.mode === "stealth" : a2.stealth ?? true;
+        const captcha = a2.captcha ?? stealth;
+        if (!stealth) {
+          const needsStealth = [a2.proxy ? "proxy" : "", a2.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 (a2.stealth) body.stealth = true;
-        if (a2.captcha) body.captcha = true;
+        if (stealth) body.stealth = true;
+        if (captcha) body.captcha = true;
         if (a2.recording) body.recording = true;
         if (a2.proxy) body.proxy = a2.proxy;
         if (a2.profileId) body.profileId = a2.profileId;
@@ -113808,7 +113822,8 @@ function makeBrowserToolset(cfg, reg, deps = defaultDeps) {
             browser,
             page,
             expiresAt: s.expiresAt,
-            recording: Boolean(a2.recording)
+            recording: Boolean(a2.recording),
+            cdpEndpoint: cdp
           });
         } catch (err) {
           await releaseBrowserSession(cfg, s.sessionId, api2).catch(() => {
@@ -113819,8 +113834,203 @@ function makeBrowserToolset(cfg, reg, deps = defaultDeps) {
         }
         return text({
           sessionId: s.sessionId,
+          mode: stealth ? "stealth" : "fast",
+          captcha,
           expiresAt: s.expiresAt,
-          proxy: s.proxy ?? (a2.proxy ? "NOT APPLIED (check plan/stealth)" : void 0)
+          proxy: s.proxy ?? (a2.proxy ? "NOT APPLIED (check plan)" : void 0)
+        });
+      }
+    },
+    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.\nCheck 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 \u2014 that one still needs solari_browser_login({profileName}).",
+      inputSchema: {},
+      handler: async () => {
+        const res = await api2(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_login: {
+      description: "Ask a HUMAN to sign in, so you never handle credentials yourself. Two ways to call it:\nHOT \u2014 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.\nCOLD \u2014 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.\nPass exactly one of the two. Either way, SHOW THE RETURNED URL TO THE USER, then call solari_browser_await_login.\nIn the HOT case your access to that session is REVOKED while the handoff is open \u2014 deliberately, so you cannot observe what they type \u2014 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 \u2014 say plainly which site is asking and what for, because they are being asked to type a password on your say-so.",
+      inputSchema: {
+        sessionId: external_exports.string().optional(),
+        profileName: external_exports.string().optional(),
+        reason: external_exports.string()
+      },
+      handler: async (a2) => {
+        const sessionId = typeof a2.sessionId === "string" ? a2.sessionId : "";
+        const profileName = typeof a2.profileName === "string" ? a2.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)."
+          );
+        }
+        if (profileName) {
+          const listRes = await api2(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 api2(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 api2(cfg, "POST", `/profiles/${encodeURIComponent(profileId)}/login-handoff`, {
+            reason: a2.reason
+          });
+          if (hRes.status !== 200) await apiError(hRes, "cold login request");
+          const h2 = await hRes.json();
+          return text({
+            mode: "cold",
+            profileId,
+            profileName,
+            handoffId: h2.handoffId,
+            url: h2.url,
+            expiresAt: h2.expiresAt,
+            // Echoed so await_login can tell a fresh save from the state it
+            // started in — the version bump IS the completion signal.
+            sinceVersion: h2.version,
+            next: `Show the url to the user, then call solari_browser_await_login({ profileId: "${profileId}", sinceVersion: ${h2.version} }).`
+          });
+        }
+        const e = need(sessionId);
+        const res = await api2(
+          cfg,
+          "POST",
+          `/sessions/${encodeURIComponent(sessionId)}/handoff`,
+          { reason: a2.reason }
+        );
+        if (res.status !== 200) await apiError(res, "handoff request");
+        const h = await res.json();
+        try {
+          await e.browser.close();
+        } catch {
+        }
+        return text({
+          mode: "hot",
+          handoffId: h.handoffId,
+          url: h.url,
+          expiresAt: h.expiresAt,
+          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.\nONLY 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 \u2014 it is a credential store, and it should exist because someone chose it. If they have not said so, ask first.\nReturns what was captured (cookie count and origins) so the user can see what they just persisted.",
+      inputSchema: {
+        sessionId: external_exports.string(),
+        profileId: external_exports.string()
+      },
+      handler: async (a2) => {
+        need(a2.sessionId);
+        const res = await api2(
+          cfg,
+          "POST",
+          `/sessions/${encodeURIComponent(a2.sessionId)}/save-profile`,
+          { profileId: a2.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 \u2014 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: external_exports.string().optional(),
+        profileId: external_exports.string().optional(),
+        sinceVersion: external_exports.number().optional(),
+        handoffId: external_exports.string().optional(),
+        timeoutMs: external_exports.number().optional()
+      },
+      handler: async (a2) => {
+        const sessionId = typeof a2.sessionId === "string" ? a2.sessionId : "";
+        const profileId = typeof a2.profileId === "string" ? a2.profileId : "";
+        if (Boolean(sessionId) === Boolean(profileId)) {
+          throw new Error(
+            "Pass exactly one of sessionId (hot handoff) or profileId (cold handoff) \u2014 the same one solari_browser_login returned."
+          );
+        }
+        const requested = typeof a2.timeoutMs === "number" ? a2.timeoutMs : 3e5;
+        const deadline = Date.now() + Math.min(Math.max(requested, 5e3), 6e5);
+        let status = "pending";
+        if (profileId) {
+          const since = typeof a2.sinceVersion === "number" ? a2.sinceVersion : 0;
+          let version2 = since;
+          while (Date.now() < deadline) {
+            const res = await api2(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`);
+            version2 = typeof row.version === "number" ? row.version : since;
+            if (version2 > 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: version2,
+            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 q2 = typeof a2.handoffId === "string" && a2.handoffId ? `?handoffId=${encodeURIComponent(a2.handoffId)}` : "";
+          const res = await api2(
+            cfg,
+            "GET",
+            `/sessions/${encodeURIComponent(sessionId)}/handoff${q2}`
+          );
+          if (res.status !== 200) await apiError(res, "handoff status");
+          const body = await res.json();
+          status = body.status ?? "none";
+          if (status !== "pending") break;
+          await new Promise((r) => setTimeout(r, HANDOFF_POLL_MS));
+        }
+        if (status === "pending") status = "timeout";
+        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/solari-mcp.bundle.cjs

@@ -112345,6 +112345,7 @@ var text = (o) => ({
 var MAX_PAGE_TEXT = 3e4;
 var MAX_LINKS = 200;
 var CDP_DIAL_ATTEMPTS = 3;
+var HANDOFF_POLL_MS = 2e3;
 var redact = (s) => s.replace(/wss?:\/\/[^\s"']+/gi, "[redacted-ws-url]");
 async function api(cfg, method, path12, body) {
   const res = await fetch(`${cfg.baseUrl}${path12}`, {
@@ -112437,18 +112438,31 @@ function makeBrowserToolset(cfg, reg, deps = defaultDeps) {
 \u2026[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' \u2014 requires stealth), captcha auto-solving (requires stealth), recording (rrweb replay).",
+      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.\nmode defaults to 'stealth' \u2014 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.\nPass 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'.\ncaptcha auto-solving is ALSO on by default (it follows the pool: on for stealth, off for fast). Pass captcha:false to turn it off \u2014 solving a challenge costs money and adds latency, so switch it off for sites you know never challenge.\nproxy ('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: external_exports.enum(["stealth", "fast"]).optional(),
+        /** @deprecated use mode. Kept so existing callers keep working. */
         stealth: external_exports.boolean().optional(),
         proxy: external_exports.string().optional(),
+        /** Defaults to ON (following the pool). Pass false to opt out. */
         captcha: external_exports.boolean().optional(),
         recording: external_exports.boolean().optional(),
         profileId: external_exports.string().optional()
       },
       handler: async (a2) => {
+        const stealth = a2.mode !== void 0 ? a2.mode === "stealth" : a2.stealth ?? true;
+        const captcha = a2.captcha ?? stealth;
+        if (!stealth) {
+          const needsStealth = [a2.proxy ? "proxy" : "", a2.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 (a2.stealth) body.stealth = true;
-        if (a2.captcha) body.captcha = true;
+        if (stealth) body.stealth = true;
+        if (captcha) body.captcha = true;
         if (a2.recording) body.recording = true;
         if (a2.proxy) body.proxy = a2.proxy;
         if (a2.profileId) body.profileId = a2.profileId;
@@ -112477,7 +112491,8 @@ function makeBrowserToolset(cfg, reg, deps = defaultDeps) {
             browser,
             page,
             expiresAt: s.expiresAt,
-            recording: Boolean(a2.recording)
+            recording: Boolean(a2.recording),
+            cdpEndpoint: cdp
           });
         } catch (err) {
           await releaseBrowserSession(cfg, s.sessionId, api2).catch(() => {
@@ -112488,8 +112503,203 @@ function makeBrowserToolset(cfg, reg, deps = defaultDeps) {
         }
         return text({
           sessionId: s.sessionId,
+          mode: stealth ? "stealth" : "fast",
+          captcha,
           expiresAt: s.expiresAt,
-          proxy: s.proxy ?? (a2.proxy ? "NOT APPLIED (check plan/stealth)" : void 0)
+          proxy: s.proxy ?? (a2.proxy ? "NOT APPLIED (check plan)" : void 0)
+        });
+      }
+    },
+    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.\nCheck 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 \u2014 that one still needs solari_browser_login({profileName}).",
+      inputSchema: {},
+      handler: async () => {
+        const res = await api2(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_login: {
+      description: "Ask a HUMAN to sign in, so you never handle credentials yourself. Two ways to call it:\nHOT \u2014 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.\nCOLD \u2014 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.\nPass exactly one of the two. Either way, SHOW THE RETURNED URL TO THE USER, then call solari_browser_await_login.\nIn the HOT case your access to that session is REVOKED while the handoff is open \u2014 deliberately, so you cannot observe what they type \u2014 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 \u2014 say plainly which site is asking and what for, because they are being asked to type a password on your say-so.",
+      inputSchema: {
+        sessionId: external_exports.string().optional(),
+        profileName: external_exports.string().optional(),
+        reason: external_exports.string()
+      },
+      handler: async (a2) => {
+        const sessionId = typeof a2.sessionId === "string" ? a2.sessionId : "";
+        const profileName = typeof a2.profileName === "string" ? a2.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)."
+          );
+        }
+        if (profileName) {
+          const listRes = await api2(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 api2(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 api2(cfg, "POST", `/profiles/${encodeURIComponent(profileId)}/login-handoff`, {
+            reason: a2.reason
+          });
+          if (hRes.status !== 200) await apiError(hRes, "cold login request");
+          const h2 = await hRes.json();
+          return text({
+            mode: "cold",
+            profileId,
+            profileName,
+            handoffId: h2.handoffId,
+            url: h2.url,
+            expiresAt: h2.expiresAt,
+            // Echoed so await_login can tell a fresh save from the state it
+            // started in — the version bump IS the completion signal.
+            sinceVersion: h2.version,
+            next: `Show the url to the user, then call solari_browser_await_login({ profileId: "${profileId}", sinceVersion: ${h2.version} }).`
+          });
+        }
+        const e = need(sessionId);
+        const res = await api2(
+          cfg,
+          "POST",
+          `/sessions/${encodeURIComponent(sessionId)}/handoff`,
+          { reason: a2.reason }
+        );
+        if (res.status !== 200) await apiError(res, "handoff request");
+        const h = await res.json();
+        try {
+          await e.browser.close();
+        } catch {
+        }
+        return text({
+          mode: "hot",
+          handoffId: h.handoffId,
+          url: h.url,
+          expiresAt: h.expiresAt,
+          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.\nONLY 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 \u2014 it is a credential store, and it should exist because someone chose it. If they have not said so, ask first.\nReturns what was captured (cookie count and origins) so the user can see what they just persisted.",
+      inputSchema: {
+        sessionId: external_exports.string(),
+        profileId: external_exports.string()
+      },
+      handler: async (a2) => {
+        need(a2.sessionId);
+        const res = await api2(
+          cfg,
+          "POST",
+          `/sessions/${encodeURIComponent(a2.sessionId)}/save-profile`,
+          { profileId: a2.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 \u2014 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: external_exports.string().optional(),
+        profileId: external_exports.string().optional(),
+        sinceVersion: external_exports.number().optional(),
+        handoffId: external_exports.string().optional(),
+        timeoutMs: external_exports.number().optional()
+      },
+      handler: async (a2) => {
+        const sessionId = typeof a2.sessionId === "string" ? a2.sessionId : "";
+        const profileId = typeof a2.profileId === "string" ? a2.profileId : "";
+        if (Boolean(sessionId) === Boolean(profileId)) {
+          throw new Error(
+            "Pass exactly one of sessionId (hot handoff) or profileId (cold handoff) \u2014 the same one solari_browser_login returned."
+          );
+        }
+        const requested = typeof a2.timeoutMs === "number" ? a2.timeoutMs : 3e5;
+        const deadline = Date.now() + Math.min(Math.max(requested, 5e3), 6e5);
+        let status = "pending";
+        if (profileId) {
+          const since = typeof a2.sinceVersion === "number" ? a2.sinceVersion : 0;
+          let version2 = since;
+          while (Date.now() < deadline) {
+            const res = await api2(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`);
+            version2 = typeof row.version === "number" ? row.version : since;
+            if (version2 > 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: version2,
+            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 q2 = typeof a2.handoffId === "string" && a2.handoffId ? `?handoffId=${encodeURIComponent(a2.handoffId)}` : "";
+          const res = await api2(
+            cfg,
+            "GET",
+            `/sessions/${encodeURIComponent(sessionId)}/handoff${q2}`
+          );
+          if (res.status !== 200) await apiError(res, "handoff status");
+          const body = await res.json();
+          status = body.status ?? "none";
+          if (status !== "pending") break;
+          await new Promise((r) => setTimeout(r, HANDOFF_POLL_MS));
+        }
+        if (status === "pending") status = "timeout";
+        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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@solarisdk/mcp",
-  "version": "0.3.0",
-  "description": "Model Context Protocol server for the Solari cloud browser, sandboxes + desktops — drive them from Claude Desktop/Cowork, Claude Code, Cursor, etc.",
+  "version": "0.3.2",
+  "description": "Model Context Protocol server for the Solari cloud browser, sandboxes + desktops \u2014 drive them from Claude Desktop/Cowork, Claude Code, Cursor, etc.",
   "type": "module",
   "bin": {
     "solari-mcp": "./dist/cli.js"