@solarisdk/mcp 0.3.1 → 0.3.3

package/README.md

@@ -103,6 +103,9 @@ Chat, Code and Cowork alike.
 | `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
@@ -138,13 +141,44 @@ asked for. Stealth ⇒ on, fast ⇒ off, explicit value always wins. Asking for
 *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 |
 |---|---|
 | `solari_sandbox_create` | Create a headless sandbox → `sessionId` |
 | `solari_desktop_create` | Create a GUI desktop → `sessionId` + `streamUrl` |
-| `solari_list` | List the org's sandboxes |
+| `solari_list` | List the org's VMs — **both** sandboxes and desktops, each labelled with its `kind` (optional `kind`/`state` filters) |
 | `solari_kill` | Destroy a session |
 | `solari_connect` | Re-attach to a session by id across restarts (auto-resumes if paused) |
 | `solari_exec` | Run a shell command (via `sh -c`) → `{stdout,stderr,exitCode}` |

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) {
@@ -237,6 +239,7 @@ export function makeBrowserToolset(cfg, reg, deps = defaultDeps) {
                         page,
                         expiresAt: s.expiresAt,
                         recording: Boolean(a.recording),
+                        cdpEndpoint: cdp,
                     });
                 }
                 catch (err) {
@@ -257,6 +260,253 @@ export function makeBrowserToolset(cfg, reg, deps = defaultDeps) {
                 });
             },
         },
+        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() } : {}),
+                });
+            },
+        },
         solari_browser_navigate: {
             description: "Navigate the browser session to a URL. Returns final url, title and HTTP status.",
             inputSchema: { sessionId: z.string(), url: z.string() },

package/dist/server.js

@@ -12,11 +12,14 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { SolariClient } from "@solarisdk/sdk";
+import { VERSION } from "./version.js";
 import { makeBrowserToolset, releaseAllBrowserSessions, } from "./browser.js";
 // Guest output (file reads, command stdout, code results) is unbounded on the
 // wire; cap it so one `cat` of a big file can't blow the MCP payload budget or
 // OOM the shared hosted task.
 const MAX_TOOL_TEXT = 30_000;
+// Pages of `GET /sandboxes` solari_list will follow per kind (100 rows each).
+const MAX_LIST_PAGES = 5;
 const text = (o) => {
     const s = typeof o === "string" ? o : JSON.stringify(o, null, 2);
     const capped = s.length > MAX_TOOL_TEXT
@@ -81,9 +84,59 @@ export function makeToolset(client, reg) {
             },
         },
         solari_list: {
-            description: "List the org's sandboxes.",
-            inputSchema: {},
-            handler: async () => text(await client.sandboxes.list()),
+            description: "List the org's live VMs — BOTH sandboxes and desktops. Each entry is labelled " +
+                "with its `kind`; `registered:true` means this MCP session already holds a handle " +
+                "so the other tools accept its sessionId directly (otherwise call solari_connect " +
+                "first). Optional kind/state filters.",
+            inputSchema: {
+                kind: z.enum(["sandbox", "desktop"]).optional(),
+                state: z.string().optional(),
+            },
+            handler: async (a) => {
+                // GET /sandboxes is the unified VM index (desktops write the same
+                // SandboxRecord), but it is queried per-kind here so the two flavours
+                // are merged EXPLICITLY: an agent asking "what do I have running"
+                // must never silently lose desktops to a default filter, and the
+                // per-kind counts are what make the answer legible.
+                const kinds = a.kind ? [a.kind] : ["sandbox", "desktop"];
+                const vms = [];
+                const counts = { sandbox: 0, desktop: 0 };
+                let truncated = false;
+                for (const kind of kinds) {
+                    // Follow nextCursor so a big org's desktops aren't cut off by the
+                    // gateway's 100-row default page — bounded so one call can't spin.
+                    let cursor;
+                    for (let page = 0; page < MAX_LIST_PAGES; page++) {
+                        const res = await client.sandboxes.list({
+                            kind,
+                            // `state` is a closed union on the SDK; an unknown value is
+                            // simply ignored by the gateway, so pass it through.
+                            ...(a.state ? { state: a.state } : {}),
+                            ...(cursor ? { cursor } : {}),
+                        });
+                        for (const v of res.sandboxes ?? []) {
+                            const rec = v;
+                            // The wire calls the id `sandboxId` for both kinds; re-label it
+                            // `sessionId` because that is what every other tool here takes.
+                            const id = (rec.sandboxId ?? rec.sessionId);
+                            const k = rec.kind ?? kind;
+                            vms.push({
+                                ...rec,
+                                ...(id ? { sessionId: id } : {}),
+                                kind: k,
+                                registered: id ? reg.sessions.has(id) : false,
+                            });
+                            counts[k] = (counts[k] ?? 0) + 1;
+                        }
+                        cursor = res.nextCursor;
+                        if (!cursor)
+                            break;
+                        if (page === MAX_LIST_PAGES - 1)
+                            truncated = true;
+                    }
+                }
+                return text({ counts, total: vms.length, ...(truncated ? { truncated } : {}), vms });
+            },
         },
         solari_kill: {
             description: "Destroy a session by id.",
@@ -284,7 +337,7 @@ export function buildServerParts(client, browserCfg) {
             process.env.SOLARI_BASE_URL ??
             "https://api.getsolari.com",
     };
-    const server = new McpServer({ name: "solari-mcp", version: "0.3.0" });
+    const server = new McpServer({ name: "solari-mcp", version: VERSION });
     const browserReg = { sessions: new Map() };
     const vmReg = { sessions: new Map() };
     registerToolset(server, {

package/dist/solari-mcp-http.bundle.cjs

@@ -112357,6 +112357,9 @@ var SolariClient = class {
   }
 };
 
+// src/version.ts
+var VERSION = "0.3.3";
+
 // node_modules/puppeteer-core/lib/esm/puppeteer/index.js
 init_index_browser();
 
@@ -113676,6 +113679,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}`, {
@@ -113821,7 +113825,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(() => {
@@ -113839,6 +113844,199 @@ function makeBrowserToolset(cfg, reg, deps = defaultDeps) {
         });
       }
     },
+    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() } : {}
+        });
+      }
+    },
     solari_browser_navigate: {
       description: "Navigate the browser session to a URL. Returns final url, title and HTTP status.",
       inputSchema: { sessionId: external_exports.string(), url: external_exports.string() },
@@ -114043,6 +114241,7 @@ async function releaseAllBrowserSessions(cfg, reg, fetchApi = api) {
 // src/server.ts
 var import_meta2 = {};
 var MAX_TOOL_TEXT = 3e4;
+var MAX_LIST_PAGES = 5;
 var text2 = (o) => {
   const s = typeof o === "string" ? o : JSON.stringify(o, null, 2);
   const capped = s.length > MAX_TOOL_TEXT ? `${s.slice(0, MAX_TOOL_TEXT)}
@@ -114099,9 +114298,45 @@ function makeToolset(client, reg) {
       }
     },
     solari_list: {
-      description: "List the org's sandboxes.",
-      inputSchema: {},
-      handler: async () => text2(await client.sandboxes.list())
+      description: "List the org's live VMs \u2014 BOTH sandboxes and desktops. Each entry is labelled with its `kind`; `registered:true` means this MCP session already holds a handle so the other tools accept its sessionId directly (otherwise call solari_connect first). Optional kind/state filters.",
+      inputSchema: {
+        kind: external_exports.enum(["sandbox", "desktop"]).optional(),
+        state: external_exports.string().optional()
+      },
+      handler: async (a2) => {
+        const kinds = a2.kind ? [a2.kind] : ["sandbox", "desktop"];
+        const vms = [];
+        const counts = { sandbox: 0, desktop: 0 };
+        let truncated = false;
+        for (const kind of kinds) {
+          let cursor;
+          for (let page = 0; page < MAX_LIST_PAGES; page++) {
+            const res = await client.sandboxes.list({
+              kind,
+              // `state` is a closed union on the SDK; an unknown value is
+              // simply ignored by the gateway, so pass it through.
+              ...a2.state ? { state: a2.state } : {},
+              ...cursor ? { cursor } : {}
+            });
+            for (const v2 of res.sandboxes ?? []) {
+              const rec = v2;
+              const id = rec.sandboxId ?? rec.sessionId;
+              const k = rec.kind ?? kind;
+              vms.push({
+                ...rec,
+                ...id ? { sessionId: id } : {},
+                kind: k,
+                registered: id ? reg.sessions.has(id) : false
+              });
+              counts[k] = (counts[k] ?? 0) + 1;
+            }
+            cursor = res.nextCursor;
+            if (!cursor) break;
+            if (page === MAX_LIST_PAGES - 1) truncated = true;
+          }
+        }
+        return text2({ counts, total: vms.length, ...truncated ? { truncated } : {}, vms });
+      }
     },
     solari_kill: {
       description: "Destroy a session by id.",
@@ -114275,7 +114510,7 @@ function buildServerParts(client, browserCfg) {
     apiKey: process.env.SOLARI_BROWSER_API_KEY ?? apiKey,
     baseUrl: process.env.SOLARI_BROWSER_URL ?? process.env.SOLARI_BASE_URL ?? "https://api.getsolari.com"
   };
-  const server = new McpServer({ name: "solari-mcp", version: "0.3.0" });
+  const server = new McpServer({ name: "solari-mcp", version: VERSION });
   const browserReg = { sessions: /* @__PURE__ */ new Map() };
   const vmReg = { sessions: /* @__PURE__ */ new Map() };
   registerToolset(server, {

package/dist/solari-mcp.bundle.cjs

@@ -111026,6 +111026,9 @@ var SolariClient = class {
   }
 };
 
+// src/version.ts
+var VERSION = "0.3.3";
+
 // node_modules/puppeteer-core/lib/esm/puppeteer/index.js
 init_index_browser();
 
@@ -112345,6 +112348,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}`, {
@@ -112490,7 +112494,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(() => {
@@ -112508,6 +112513,199 @@ function makeBrowserToolset(cfg, reg, deps = defaultDeps) {
         });
       }
     },
+    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() } : {}
+        });
+      }
+    },
     solari_browser_navigate: {
       description: "Navigate the browser session to a URL. Returns final url, title and HTTP status.",
       inputSchema: { sessionId: external_exports.string(), url: external_exports.string() },
@@ -112712,6 +112910,7 @@ async function releaseAllBrowserSessions(cfg, reg, fetchApi = api) {
 // src/server.ts
 var import_meta2 = {};
 var MAX_TOOL_TEXT = 3e4;
+var MAX_LIST_PAGES = 5;
 var text2 = (o) => {
   const s = typeof o === "string" ? o : JSON.stringify(o, null, 2);
   const capped = s.length > MAX_TOOL_TEXT ? `${s.slice(0, MAX_TOOL_TEXT)}
@@ -112768,9 +112967,45 @@ function makeToolset(client, reg) {
       }
     },
     solari_list: {
-      description: "List the org's sandboxes.",
-      inputSchema: {},
-      handler: async () => text2(await client.sandboxes.list())
+      description: "List the org's live VMs \u2014 BOTH sandboxes and desktops. Each entry is labelled with its `kind`; `registered:true` means this MCP session already holds a handle so the other tools accept its sessionId directly (otherwise call solari_connect first). Optional kind/state filters.",
+      inputSchema: {
+        kind: external_exports.enum(["sandbox", "desktop"]).optional(),
+        state: external_exports.string().optional()
+      },
+      handler: async (a2) => {
+        const kinds = a2.kind ? [a2.kind] : ["sandbox", "desktop"];
+        const vms = [];
+        const counts = { sandbox: 0, desktop: 0 };
+        let truncated = false;
+        for (const kind of kinds) {
+          let cursor;
+          for (let page = 0; page < MAX_LIST_PAGES; page++) {
+            const res = await client.sandboxes.list({
+              kind,
+              // `state` is a closed union on the SDK; an unknown value is
+              // simply ignored by the gateway, so pass it through.
+              ...a2.state ? { state: a2.state } : {},
+              ...cursor ? { cursor } : {}
+            });
+            for (const v2 of res.sandboxes ?? []) {
+              const rec = v2;
+              const id = rec.sandboxId ?? rec.sessionId;
+              const k = rec.kind ?? kind;
+              vms.push({
+                ...rec,
+                ...id ? { sessionId: id } : {},
+                kind: k,
+                registered: id ? reg.sessions.has(id) : false
+              });
+              counts[k] = (counts[k] ?? 0) + 1;
+            }
+            cursor = res.nextCursor;
+            if (!cursor) break;
+            if (page === MAX_LIST_PAGES - 1) truncated = true;
+          }
+        }
+        return text2({ counts, total: vms.length, ...truncated ? { truncated } : {}, vms });
+      }
     },
     solari_kill: {
       description: "Destroy a session by id.",
@@ -112944,7 +113179,7 @@ function buildServerParts(client, browserCfg) {
     apiKey: process.env.SOLARI_BROWSER_API_KEY ?? apiKey,
     baseUrl: process.env.SOLARI_BROWSER_URL ?? process.env.SOLARI_BASE_URL ?? "https://api.getsolari.com"
   };
-  const server = new McpServer({ name: "solari-mcp", version: "0.3.0" });
+  const server = new McpServer({ name: "solari-mcp", version: VERSION });
   const browserReg = { sessions: /* @__PURE__ */ new Map() };
   const vmReg = { sessions: /* @__PURE__ */ new Map() };
   registerToolset(server, {

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare const VERSION = "0.3.3";

package/dist/version.js

@@ -0,0 +1,11 @@
+// The single source of truth for the version this server reports to MCP
+// clients (`initialize` → serverInfo.version).
+//
+// It CANNOT be imported straight from package.json: tsconfig pins
+// `rootDir: "src"`, so `import "../package.json"` is outside the root and tsc
+// refuses it; widening rootDir would emit `dist/src/*.js` and break the `bin`
+// path + the esbuild bundles. So it is a literal here — and
+// `test/version.test.mjs` FAILS the build if it ever drifts from package.json.
+//
+// KEEP IN SYNC WITH sdk/mcp/package.json "version".
+export const VERSION = "0.3.3";

package/package.json

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