@solarisdk/mcp 0.4.4 → 0.4.6

package/dist/server.js

@@ -20,6 +20,24 @@ import { makeBrowserToolset, releaseAllBrowserSessions, } from "./browser.js";
 const MAX_TOOL_TEXT = 30_000;
 // Pages of `GET /sandboxes` solari_list will follow per kind (100 rows each).
 const MAX_LIST_PAGES = 5;
+// The four park/checkpoint tool args, flat on the wire-facing tool schemas
+// (see the create tools below), assembled into the nested `lifecycle` shape
+// the gateway actually accepts. Returns undefined -- not an empty object --
+// when the caller set none of them, so a create that never mentions lifecycle
+// does not send `lifecycle: {}` (the gateway defaults onTimeout/autoResume
+// itself; sending an empty object would just be noise on the wire).
+function buildLifecycle(a) {
+    const lc = {};
+    if (a.parkAfterMs)
+        lc.parkAfterMs = a.parkAfterMs;
+    if (a.parkMaxMs)
+        lc.parkMaxMs = a.parkMaxMs;
+    if (a.hibernateAfterParkedMs)
+        lc.hibernateAfterParkedMs = a.hibernateAfterParkedMs;
+    if (a.checkpointEveryMs)
+        lc.checkpointEveryMs = a.checkpointEveryMs;
+    return Object.keys(lc).length > 0 ? lc : undefined;
+}
 const text = (o) => {
     const s = typeof o === "string" ? o : JSON.stringify(o, null, 2);
     const capped = s.length > MAX_TOOL_TEXT
@@ -27,17 +45,58 @@ const text = (o) => {
         : s;
     return { content: [{ type: "text", text: capped }] };
 };
+// Rebuild a registry Entry for `id` by asking the gateway what it is and
+// re-attaching. This is the same sequence solari_connect performs by hand, and
+// it is what makes the registry a CACHE rather than authoritative state: the
+// gateway already knows every session, and the client already carries the id
+// (create tools return it, every other tool takes it).
+async function rehydrate(client, reg, id) {
+    let kind = reg.sessions.get(id)?.kind ?? "sandbox";
+    let state;
+    try {
+        const view = await client.sandboxes.get(id);
+        if (view?.kind === "desktop" || view?.kind === "sandbox")
+            kind = view.kind;
+        state = view?.state;
+    }
+    catch {
+        // The gateway is the authority on existence; if it cannot be reached we
+        // fall through to connect() and let ITS error surface, rather than
+        // inventing an "unknown sessionId" that hides a gateway outage.
+    }
+    const handle = kind === "desktop" ? await client.desktops.connect(id) : await client.sandboxes.connect(id);
+    // desktops.connect() auto-resumes; sandboxes.connect() does not.
+    if (kind === "sandbox" && state === "paused" && typeof handle.resume === "function") {
+        await handle.resume();
+    }
+    // commands: [] is correct, not a loss. The array only exists to keep the
+    // rejecting exit promise of a background command owned; no tool ever reads
+    // it back, so a rebuilt Entry owes nothing to the pod that started one.
+    const e = { kind, handle, commands: [] };
+    reg.sessions.set(id, e);
+    return e;
+}
 export function makeToolset(client, reg) {
-    const need = (id) => {
+    // A MISS IS NOT AN ERROR — it is a cold cache. Before 2026-09-21 this threw
+    // `unknown sessionId`, which is why the hosted connector could only ever run
+    // one replica: a request that landed on a pod which had not served the
+    // create call was indistinguishable from a request for a session that never
+    // existed. Rebuilding on demand is what lets any pod serve any request.
+    const need = async (id) => {
         const e = reg.sessions.get(id);
-        if (!e)
-            throw new Error(`unknown sessionId: ${id}`);
-        return e;
+        if (e)
+            return e;
+        return rehydrate(client, reg, id);
     };
     // A paused session refuses the /control upgrade with 409, so resume it and
     // retry rather than surfacing an opaque websocket error.
+    //
+    // A PARKED session needs nothing here: park keeps the slot, the host and the
+    // routing, and the gateway unparks on the /control upgrade itself (wake-on-
+    // touch). The connect below just works, a few hundred milliseconds slower.
+    // Do not add an unpark call -- it would be a redundant round trip.
     const live = async (id) => {
-        const e = need(id);
+        const e = await need(id);
         if (e.handle.connected)
             return e;
         try {
@@ -60,12 +119,52 @@ export function makeToolset(client, reg) {
     return {
         solari_sandbox_create: {
             description: "Create a headless sandbox (microVM). Returns its sessionId.",
-            inputSchema: { template: z.string().optional(), cpu: z.number().optional(), memMb: z.number().optional() },
+            inputSchema: {
+                template: z.string().optional(),
+                cpu: z.number().optional(),
+                memMb: z.number().optional(),
+                // Kept FLAT rather than a nested `lifecycle` object, matching every
+                // other tool schema in this file -- a flat schema is what an LLM
+                // tool-calling interface parses most reliably. Mapped into the
+                // gateway's nested `lifecycle` shape only inside the handler.
+                ttlSeconds: z
+                    .number()
+                    .optional()
+                    .describe("Legacy idle-window fallback in seconds, only used when the gateway's default " +
+                    "timeout is not already set by another field. Usually unnecessary."),
+                isolation: z
+                    .enum(["shared", "dedicated", "hardened"])
+                    .optional()
+                    .describe("VM isolation tier. \"shared\" runs inside a VM shared with your other shared " +
+                    "sandboxes (smaller footprint, faster start). \"dedicated\" (default) is your " +
+                    "own VM. \"hardened\" is your own VM with outbound network blocked -- verified " +
+                    "on staging, not yet on prod; refused if the assigned host doesn't support it."),
+                parkAfterMs: z
+                    .number()
+                    .optional()
+                    .describe("Auto-park (freeze, keep the slot) after this many ms of no activity."),
+                parkMaxMs: z
+                    .number()
+                    .optional()
+                    .describe("Wake a parked session unconditionally after this many ms, even if idle."),
+                hibernateAfterParkedMs: z
+                    .number()
+                    .optional()
+                    .describe("Escalate a parked session to a full hibernate after this many ms parked."),
+                checkpointEveryMs: z
+                    .number()
+                    .optional()
+                    .describe("Take a durable checkpoint at most this often while the session runs."),
+            },
             handler: async (a) => {
+                const lifecycle = buildLifecycle(a);
                 const sbx = await client.sandboxes.create({
                     ...(a.template ? { template: a.template } : {}),
                     ...(a.cpu ? { cpu: a.cpu } : {}),
                     ...(a.memMb ? { memMb: a.memMb } : {}),
+                    ...(a.ttlSeconds ? { ttlSeconds: a.ttlSeconds } : {}),
+                    ...(a.isolation ? { isolation: a.isolation } : {}),
+                    ...(lifecycle ? { lifecycle: lifecycle } : {}),
                 });
                 reg.sessions.set(sbx.sandboxId, { kind: "sandbox", handle: sbx, commands: [] });
                 return text({ sessionId: sbx.sandboxId });
@@ -73,11 +172,46 @@ export function makeToolset(client, reg) {
         },
         solari_desktop_create: {
             description: "Create a GUI desktop (microVM). Returns sessionId + streamUrl (noVNC).",
-            inputSchema: { template: z.string().optional(), resolution: z.string().optional() },
+            inputSchema: {
+                template: z.string().optional(),
+                resolution: z.string().optional(),
+                ttlSeconds: z
+                    .number()
+                    .optional()
+                    .describe("Legacy idle-window fallback in seconds, only used when the gateway's default " +
+                    "timeout is not already set by another field. Usually unnecessary."),
+                isolation: z
+                    .enum(["dedicated", "hardened"])
+                    .optional()
+                    .describe("VM isolation tier. \"dedicated\" (default) is your own VM. \"hardened\" is your " +
+                    "own VM with outbound network blocked -- verified on staging, not yet on prod; " +
+                    "refused if the assigned host doesn't support it. \"shared\" is sandbox-only " +
+                    "(a desktop's display is per-VM) and is not offered here."),
+                parkAfterMs: z
+                    .number()
+                    .optional()
+                    .describe("Auto-park (freeze, keep the slot) after this many ms of no activity."),
+                parkMaxMs: z
+                    .number()
+                    .optional()
+                    .describe("Wake a parked session unconditionally after this many ms, even if idle."),
+                hibernateAfterParkedMs: z
+                    .number()
+                    .optional()
+                    .describe("Escalate a parked session to a full hibernate after this many ms parked."),
+                checkpointEveryMs: z
+                    .number()
+                    .optional()
+                    .describe("Take a durable checkpoint at most this often while the session runs."),
+            },
             handler: async (a) => {
+                const lifecycle = buildLifecycle(a);
                 const d = await client.desktops.create({
                     ...(a.template ? { template: a.template } : {}),
                     ...(a.resolution ? { resolution: a.resolution } : {}),
+                    ...(a.ttlSeconds ? { ttlSeconds: a.ttlSeconds } : {}),
+                    ...(a.isolation ? { isolation: a.isolation } : {}),
+                    ...(lifecycle ? { lifecycle: lifecycle } : {}),
                 });
                 reg.sessions.set(d.sessionId, { kind: "desktop", handle: d, commands: [] });
                 return text({ sessionId: d.sessionId, streamUrl: d.streamUrl });
@@ -142,7 +276,7 @@ export function makeToolset(client, reg) {
             description: "Destroy a session by id.",
             inputSchema: { sessionId: z.string() },
             handler: async (a) => {
-                const e = need(a.sessionId);
+                const e = await need(a.sessionId);
                 await e.handle.kill();
                 reg.sessions.delete(a.sessionId);
                 return text({ ok: true });
@@ -275,6 +409,62 @@ export function makeToolset(client, reg) {
                 return text({ ok: true });
             },
         },
+        solari_mouse_down: {
+            description: "Press and HOLD a mouse button at (x, y) — the start of a drag (e.g. grab a window " +
+                "title bar). Follow with solari_mouse_move to drag while held, then solari_mouse_up " +
+                "to release. For a simple one-shot drag prefer solari_drag.",
+            inputSchema: {
+                sessionId: z.string(),
+                x: z.number(),
+                y: z.number(),
+                button: z.enum(["left", "right", "middle"]).optional(),
+            },
+            handler: async (a) => {
+                const e = await desktop(a.sessionId);
+                await e.handle.mouse.down(a.x, a.y, a.button ?? "left");
+                return text({ ok: true });
+            },
+        },
+        solari_mouse_move: {
+            description: "Move the pointer to (x, y). While a button is held (solari_mouse_down) this drags.",
+            inputSchema: { sessionId: z.string(), x: z.number(), y: z.number() },
+            handler: async (a) => {
+                const e = await desktop(a.sessionId);
+                await e.handle.mouse.move(a.x, a.y);
+                return text({ ok: true });
+            },
+        },
+        solari_mouse_up: {
+            description: "Release the held mouse button at (x, y) — the end of a drag started with solari_mouse_down.",
+            inputSchema: {
+                sessionId: z.string(),
+                x: z.number(),
+                y: z.number(),
+                button: z.enum(["left", "right", "middle"]).optional(),
+            },
+            handler: async (a) => {
+                const e = await desktop(a.sessionId);
+                await e.handle.mouse.up(a.x, a.y, a.button ?? "left");
+                return text({ ok: true });
+            },
+        },
+        solari_drag: {
+            description: "Drag in one call: press at (fromX, fromY), move to (toX, toY), release. " +
+                "Good for moving windows, sliders, and drag-and-drop.",
+            inputSchema: {
+                sessionId: z.string(),
+                fromX: z.number(),
+                fromY: z.number(),
+                toX: z.number(),
+                toY: z.number(),
+                button: z.enum(["left", "right", "middle"]).optional(),
+            },
+            handler: async (a) => {
+                const e = await desktop(a.sessionId);
+                await e.handle.mouse.drag({ x: a.fromX, y: a.fromY }, { x: a.toX, y: a.toY }, a.button ?? "left");
+                return text({ ok: true });
+            },
+        },
         solari_type: {
             description: "Type text into the focused desktop element.",
             inputSchema: { sessionId: z.string(), text: z.string() },
@@ -331,7 +521,7 @@ export async function closeAllVmSessions(reg) {
         }
     }));
 }
-export function buildServerParts(client, browserCfg) {
+export function buildServerParts(client, browserCfg, regs) {
     const apiKey = browserCfg?.apiKey ?? process.env.SOLARI_API_KEY ?? "";
     const c = client ??
         new SolariClient({
@@ -349,8 +539,12 @@ export function buildServerParts(client, browserCfg) {
             "https://api.getsolari.com",
     };
     const server = new McpServer({ name: "solari-mcp", version: VERSION });
-    const browserReg = { sessions: new Map() };
-    const vmReg = { sessions: new Map() };
+    // Registries may be SUPPLIED by the caller. The hosted HTTP transport is
+    // stateless (a fresh McpServer per request), so it keeps one pair of
+    // registries per API key and passes them in — otherwise every request would
+    // start with a cold cache and re-attach every handle from the gateway.
+    const browserReg = regs?.browserReg ?? { sessions: new Map() };
+    const vmReg = regs?.vmReg ?? { sessions: new Map() };
     registerToolset(server, {
         ...makeToolset(c, vmReg),
         ...makeBrowserToolset(bCfg, browserReg),

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.4.4";
+export declare const VERSION = "0.4.6";

package/dist/version.js

@@ -8,4 +8,4 @@
 // `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.4.4";
+export const VERSION = "0.4.6";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solarisdk/mcp",
-  "version": "0.4.4",
+  "version": "0.4.6",
   "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": {