@tianshu-ai/tianshu 0.3.0

package/plugins/microsandbox/dist/tools/mcp-client.js

@@ -0,0 +1,226 @@
+// Minimal MCP client over Streamable HTTP.
+//
+// @playwright/mcp 0.x supports two transports: legacy SSE (GET /sse +
+// POST /messages?sessionId=…) and the newer "Streamable HTTP" single
+// endpoint (POST /mcp). We use the latter — it's a single round-trip
+// per tool call and the server returns either a JSON body or an SSE
+// stream we can read until the response message arrives.
+//
+// We don't pull in the official @modelcontextprotocol/sdk because:
+//   1. it's ~150 KB pulled into the plugin bundle for what is, at
+//      this stage, four method calls (initialize, tools/list,
+//      tools/call, "notifications/initialized");
+//   2. node:http reads SSE chunks in ~30 lines.
+// If we end up calling more MCP servers we'll switch to the SDK.
+//
+// Why node:http and not Node's built-in fetch? Playwright MCP
+// validates the Host request header against its bound address
+// (default "localhost:<port>") and 403's mismatches with
+// `Access is only allowed at localhost:<port>`. We're behind a
+// per-tenant microsandbox port forward, so the upstream host
+// (e.g. 127.0.0.1:58474) is never "localhost:3200". Setting
+// `Host: localhost:3200` is the right answer — but Node's undici
+// fetch implementation silently overrides any caller-supplied Host
+// header with the URL's host (see undici's `Request` validation).
+// node:http lets us set Host explicitly, so we use that. The MCP
+// server itself can stay locked to localhost — no need to widen
+// `--allowed-hosts` in the sandboxfile.
+import { request as httpRequest } from "node:http";
+const PROTOCOL_VERSION = "2025-06-18";
+const CLIENT_INFO = { name: "tianshu-microsandbox", version: "0.1.0" };
+export class McpClientError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = "McpClientError";
+    }
+}
+export class McpClient {
+    baseUrl;
+    timeoutMs;
+    sessionId = null;
+    nextId = 1;
+    initialised = false;
+    host;
+    port;
+    /** Host header to send. Always the MCP server's bound address
+     *  inside the sandbox (default localhost:3200), regardless of
+     *  whatever forwarded port we connect to from the host. */
+    hostHeader;
+    constructor(
+    /** e.g. http://localhost:6701 (no trailing slash). */
+    baseUrl, 
+    /** Per-call request timeout. Default 30s. */
+    timeoutMs = 30_000, 
+    /** Override the upstream MCP server's bound Host. Defaults to
+     *  `localhost:3200` which is what the supervisord-managed
+     *  Playwright MCP listens on inside browser.yaml's VM. */
+    upstreamHost = "localhost:3200") {
+        this.baseUrl = baseUrl;
+        this.timeoutMs = timeoutMs;
+        const u = new URL(baseUrl);
+        this.host = u.hostname;
+        this.port = u.port ? Number(u.port) : u.protocol === "https:" ? 443 : 80;
+        this.hostHeader = upstreamHost;
+    }
+    /** One-shot: open an MCP session, call a tool, close. Caller
+     *  doesn't have to manage session lifecycle. */
+    async callTool(name, args) {
+        if (!this.initialised)
+            await this.initialise();
+        const result = await this.request("tools/call", {
+            name,
+            arguments: args,
+        });
+        return result;
+    }
+    /** Returns the registered tools advertised by the server. Mostly
+     *  useful for diagnostics; the host already knows tool names from
+     *  manifest contributions. */
+    async listTools() {
+        if (!this.initialised)
+            await this.initialise();
+        return this.request("tools/list", {});
+    }
+    // ─── internals ─────────────────────────────────────────────
+    async initialise() {
+        const init = await this.request("initialize", {
+            protocolVersion: PROTOCOL_VERSION,
+            capabilities: { tools: {} },
+            clientInfo: CLIENT_INFO,
+        });
+        if (!init.protocolVersion) {
+            throw new McpClientError(`MCP initialize returned no protocolVersion: ${JSON.stringify(init)}`);
+        }
+        // Send the post-init notification (per MCP spec).
+        await this.notify("notifications/initialized", {});
+        this.initialised = true;
+    }
+    async request(method, params) {
+        const id = this.nextId++;
+        const body = { jsonrpc: "2.0", id, method, params };
+        const headers = {
+            "Content-Type": "application/json",
+            Accept: "application/json, text/event-stream",
+        };
+        if (this.sessionId)
+            headers["Mcp-Session-Id"] = this.sessionId;
+        const { res, status, headers: respHeaders } = await this.send(headers, JSON.stringify(body));
+        if (status < 200 || status >= 300) {
+            const text = await drain(res).catch(() => "");
+            throw new McpClientError(`MCP HTTP ${status}: ${text.slice(0, 400)}`, status);
+        }
+        // Server returns Mcp-Session-Id on the initialize response.
+        const newSession = respHeaders["mcp-session-id"];
+        if (typeof newSession === "string")
+            this.sessionId = newSession;
+        const ct = (respHeaders["content-type"] ?? "");
+        let envelope;
+        if (ct.includes("text/event-stream")) {
+            envelope = await readJsonRpcFromSse(res, id);
+        }
+        else {
+            const buf = await drain(res);
+            envelope = JSON.parse(buf);
+        }
+        if ("error" in envelope) {
+            throw new McpClientError(envelope.error.message, envelope.error.code);
+        }
+        return envelope.result;
+    }
+    async notify(method, params) {
+        const headers = {
+            "Content-Type": "application/json",
+            Accept: "application/json, text/event-stream",
+        };
+        if (this.sessionId)
+            headers["Mcp-Session-Id"] = this.sessionId;
+        // Notifications have no id, no response needed; we still wait
+        // for the HTTP 202/200 to make sure the server saw it before
+        // we send the next request.
+        const { res, status } = await this.send(headers, JSON.stringify({ jsonrpc: "2.0", method, params }));
+        if (status < 200 || status >= 300) {
+            const text = await drain(res).catch(() => "");
+            throw new McpClientError(`MCP notify HTTP ${status}: ${text.slice(0, 200)}`, status);
+        }
+        // Drain body so the connection can be reused.
+        await drain(res).catch(() => "");
+    }
+    /** Send a single POST to /mcp using node:http, with the Host
+     *  header pinned to the upstream MCP's bound address. */
+    send(headers, body) {
+        return new Promise((resolve, reject) => {
+            const req = httpRequest({
+                host: this.host,
+                port: this.port,
+                path: "/mcp",
+                method: "POST",
+                headers: {
+                    Host: this.hostHeader,
+                    "Content-Length": Buffer.byteLength(body),
+                    ...headers,
+                },
+            }, (res) => {
+                resolve({
+                    res,
+                    status: res.statusCode ?? 0,
+                    headers: res.headers,
+                });
+            });
+            req.on("error", reject);
+            const timer = setTimeout(() => {
+                req.destroy(new Error(`MCP request timed out after ${this.timeoutMs}ms`));
+            }, this.timeoutMs);
+            req.on("close", () => clearTimeout(timer));
+            req.write(body);
+            req.end();
+        });
+    }
+}
+async function drain(res) {
+    const chunks = [];
+    for await (const chunk of res) {
+        chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+    }
+    return Buffer.concat(chunks).toString("utf8");
+}
+/**
+ * Read an SSE stream and return the first jsonrpc envelope whose `id`
+ * matches the request we sent. The server may emit progress events
+ * (notifications/progress) before the final response; we skip those.
+ */
+async function readJsonRpcFromSse(res, expectId) {
+    let buf = "";
+    for await (const chunk of res) {
+        buf += typeof chunk === "string" ? chunk : chunk.toString("utf8");
+        let blockEnd;
+        // eslint-disable-next-line no-cond-assign
+        while ((blockEnd = buf.indexOf("\n\n")) >= 0) {
+            const block = buf.slice(0, blockEnd);
+            buf = buf.slice(blockEnd + 2);
+            const dataLines = block
+                .split("\n")
+                .filter((l) => l.startsWith("data:"))
+                .map((l) => l.slice(5).trimStart());
+            if (dataLines.length === 0)
+                continue;
+            const payload = dataLines.join("\n");
+            try {
+                const env = JSON.parse(payload);
+                if (env.id === expectId) {
+                    // Drop the connection so the server stops streaming.
+                    res.destroy();
+                    return env;
+                }
+                // Otherwise it's a notification (id missing) or another
+                // request we don't care about; keep reading.
+            }
+            catch {
+                // Malformed event; ignore and keep reading.
+            }
+        }
+    }
+    throw new McpClientError("MCP SSE stream ended before response arrived");
+}
+//# sourceMappingURL=mcp-client.js.map

package/plugins/microsandbox/dist/tools/mcp-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-client.js","sourceRoot":"","sources":["../../src/tools/mcp-client.ts"],"names":[],"mappings":"AAAA,2CAA2C;AAC3C,EAAE;AACF,sEAAsE;AACtE,qEAAqE;AACrE,qEAAqE;AACrE,oEAAoE;AACpE,yDAAyD;AACzD,EAAE;AACF,mEAAmE;AACnE,kEAAkE;AAClE,8DAA8D;AAC9D,iDAAiD;AACjD,gDAAgD;AAChD,iEAAiE;AACjE,EAAE;AACF,8DAA8D;AAC9D,8DAA8D;AAC9D,yDAAyD;AACzD,+DAA+D;AAC/D,6DAA6D;AAC7D,4DAA4D;AAC5D,iEAAiE;AACjE,mEAAmE;AACnE,kEAAkE;AAClE,iEAAiE;AACjE,gEAAgE;AAChE,wCAAwC;AAExC,OAAO,EAAE,OAAO,IAAI,WAAW,EAAwB,MAAM,WAAW,CAAC;AAEzE,MAAM,gBAAgB,GAAG,YAAY,CAAC;AACtC,MAAM,WAAW,GAAG,EAAE,IAAI,EAAE,sBAAsB,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;AAkCvE,MAAM,OAAO,cAAe,SAAQ,KAAK;IAG5B;IAFX,YACE,OAAe,EACN,IAAa;QAEtB,KAAK,CAAC,OAAO,CAAC,CAAC;QAFN,SAAI,GAAJ,IAAI,CAAS;QAGtB,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;IAC/B,CAAC;CACF;AAED,MAAM,OAAO,SAAS;IAaD;IAEA;IAdX,SAAS,GAAkB,IAAI,CAAC;IAChC,MAAM,GAAG,CAAC,CAAC;IACX,WAAW,GAAG,KAAK,CAAC;IACX,IAAI,CAAS;IACb,IAAI,CAAS;IAC9B;;+DAE2D;IAC1C,UAAU,CAAS;IAEpC;IACE,sDAAsD;IACrC,OAAe;IAChC,6CAA6C;IAC5B,YAAoB,MAAM;IAC3C;;8DAE0D;IAC1D,eAAuB,gBAAgB;QANtB,YAAO,GAAP,OAAO,CAAQ;QAEf,cAAS,GAAT,SAAS,CAAiB;QAM3C,MAAM,CAAC,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC;QAC3B,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC,QAAQ,CAAC;QACvB,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;QACzE,IAAI,CAAC,UAAU,GAAG,YAAY,CAAC;IACjC,CAAC;IAED;oDACgD;IAChD,KAAK,CAAC,QAAQ,CAAC,IAAY,EAAE,IAA6B;QACxD,IAAI,CAAC,IAAI,CAAC,WAAW;YAAE,MAAM,IAAI,CAAC,UAAU,EAAE,CAAC;QAC/C,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAgB,YAAY,EAAE;YAC7D,IAAI;YACJ,SAAS,EAAE,IAAI;SAChB,CAAC,CAAC;QACH,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;kCAE8B;IAC9B,KAAK,CAAC,SAAS;QACb,IAAI,CAAC,IAAI,CAAC,WAAW;YAAE,MAAM,IAAI,CAAC,UAAU,EAAE,CAAC;QAC/C,OAAO,IAAI,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC;IACxC,CAAC;IAED,8DAA8D;IAEtD,KAAK,CAAC,UAAU;QACtB,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,OAAO,CAI5B,YAAY,EAAE;YACf,eAAe,EAAE,gBAAgB;YACjC,YAAY,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE;YAC3B,UAAU,EAAE,WAAW;SACxB,CAAC,CAAC;QACH,IAAI,CAAC,IAAI,CAAC,eAAe,EAAE,CAAC;YAC1B,MAAM,IAAI,cAAc,CACtB,+CAA+C,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CACtE,CAAC;QACJ,CAAC;QACD,kDAAkD;QAClD,MAAM,IAAI,CAAC,MAAM,CAAC,2BAA2B,EAAE,EAAE,CAAC,CAAC;QACnD,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC;IAC1B,CAAC;IAEO,KAAK,CAAC,OAAO,CAAI,MAAc,EAAE,MAAe;QACtD,MAAM,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;QACzB,MAAM,IAAI,GAAmB,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;QACpE,MAAM,OAAO,GAA2B;YACtC,cAAc,EAAE,kBAAkB;YAClC,MAAM,EAAE,qCAAqC;SAC9C,CAAC;QACF,IAAI,IAAI,CAAC,SAAS;YAAE,OAAO,CAAC,gBAAgB,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC;QAE/D,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,GAAG,MAAM,IAAI,CAAC,IAAI,CAC3D,OAAO,EACP,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CACrB,CAAC;QAEF,IAAI,MAAM,GAAG,GAAG,IAAI,MAAM,IAAI,GAAG,EAAE,CAAC;YAClC,MAAM,IAAI,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;YAC9C,MAAM,IAAI,cAAc,CACtB,YAAY,MAAM,KAAK,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,EAC3C,MAAM,CACP,CAAC;QACJ,CAAC;QAED,4DAA4D;QAC5D,MAAM,UAAU,GAAG,WAAW,CAAC,gBAAgB,CAAC,CAAC;QACjD,IAAI,OAAO,UAAU,KAAK,QAAQ;YAAE,IAAI,CAAC,SAAS,GAAG,UAAU,CAAC;QAEhE,MAAM,EAAE,GAAG,CAAC,WAAW,CAAC,cAAc,CAAC,IAAI,EAAE,CAAW,CAAC;QACzD,IAAI,QAA4B,CAAC;QACjC,IAAI,EAAE,CAAC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,CAAC;YACrC,QAAQ,GAAG,MAAM,kBAAkB,CAAI,GAAG,EAAE,EAAE,CAAC,CAAC;QAClD,CAAC;aAAM,CAAC;YACN,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,CAAC;YAC7B,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAuB,CAAC;QACnD,CAAC;QAED,IAAI,OAAO,IAAI,QAAQ,EAAE,CAAC;YACxB,MAAM,IAAI,cAAc,CAAC,QAAQ,CAAC,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACxE,CAAC;QACD,OAAO,QAAQ,CAAC,MAAM,CAAC;IACzB,CAAC;IAEO,KAAK,CAAC,MAAM,CAAC,MAAc,EAAE,MAAe;QAClD,MAAM,OAAO,GAA2B;YACtC,cAAc,EAAE,kBAAkB;YAClC,MAAM,EAAE,qCAAqC;SAC9C,CAAC;QACF,IAAI,IAAI,CAAC,SAAS;YAAE,OAAO,CAAC,gBAAgB,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC;QAC/D,8DAA8D;QAC9D,6DAA6D;QAC7D,4BAA4B;QAC5B,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,IAAI,CAAC,IAAI,CACrC,OAAO,EACP,IAAI,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CACnD,CAAC;QACF,IAAI,MAAM,GAAG,GAAG,IAAI,MAAM,IAAI,GAAG,EAAE,CAAC;YAClC,MAAM,IAAI,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;YAC9C,MAAM,IAAI,cAAc,CACtB,mBAAmB,MAAM,KAAK,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,EAClD,MAAM,CACP,CAAC;QACJ,CAAC;QACD,8CAA8C;QAC9C,MAAM,KAAK,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;IACnC,CAAC;IAED;6DACyD;IACjD,IAAI,CACV,OAA+B,EAC/B,IAAY;QAMZ,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACrC,MAAM,GAAG,GAAG,WAAW,CACrB;gBACE,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,IAAI,EAAE,MAAM;gBACZ,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE;oBACP,IAAI,EAAE,IAAI,CAAC,UAAU;oBACrB,gBAAgB,EAAE,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC;oBACzC,GAAG,OAAO;iBACX;aACF,EACD,CAAC,GAAG,EAAE,EAAE;gBACN,OAAO,CAAC;oBACN,GAAG;oBACH,MAAM,EAAE,GAAG,CAAC,UAAU,IAAI,CAAC;oBAC3B,OAAO,EAAE,GAAG,CAAC,OAAO;iBACrB,CAAC,CAAC;YACL,CAAC,CACF,CAAC;YACF,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;YACxB,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;gBAC5B,GAAG,CAAC,OAAO,CAAC,IAAI,KAAK,CAAC,+BAA+B,IAAI,CAAC,SAAS,IAAI,CAAC,CAAC,CAAC;YAC5E,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;YACnB,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC;YAC3C,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YAChB,GAAG,CAAC,GAAG,EAAE,CAAC;QACZ,CAAC,CAAC,CAAC;IACL,CAAC;CACF;AAED,KAAK,UAAU,KAAK,CAAC,GAAoB;IACvC,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,GAAG,EAAE,CAAC;QAC9B,MAAM,CAAC,IAAI,CAAC,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;IACtE,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;AAChD,CAAC;AAED;;;;GAIG;AACH,KAAK,UAAU,kBAAkB,CAC/B,GAAoB,EACpB,QAAyB;IAEzB,IAAI,GAAG,GAAG,EAAE,CAAC;IACb,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,GAAG,EAAE,CAAC;QAC9B,GAAG,IAAI,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QAClE,IAAI,QAAgB,CAAC;QACrB,0CAA0C;QAC1C,OAAO,CAAC,QAAQ,GAAG,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC;YAC7C,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;YACrC,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,QAAQ,GAAG,CAAC,CAAC,CAAC;YAC9B,MAAM,SAAS,GAAG,KAAK;iBACpB,KAAK,CAAC,IAAI,CAAC;iBACX,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;iBACpC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC;YACtC,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;gBAAE,SAAS;YACrC,MAAM,OAAO,GAAG,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACrC,IAAI,CAAC;gBACH,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAA0C,CAAC;gBACzE,IAAI,GAAG,CAAC,EAAE,KAAK,QAAQ,EAAE,CAAC;oBACxB,qDAAqD;oBACrD,GAAG,CAAC,OAAO,EAAE,CAAC;oBACd,OAAO,GAAG,CAAC;gBACb,CAAC;gBACD,wDAAwD;gBACxD,6CAA6C;YAC/C,CAAC;YAAC,MAAM,CAAC;gBACP,4CAA4C;YAC9C,CAAC;QACH,CAAC;IACH,CAAC;IACD,MAAM,IAAI,cAAc,CAAC,8CAA8C,CAAC,CAAC;AAC3E,CAAC"}

package/plugins/microsandbox/manifest.json

@@ -0,0 +1,177 @@
+{
+  "id": "microsandbox",
+  "version": "0.1.0",
+  "displayName": "MicroSandbox",
+  "description": "Per-tenant shell sandbox running on microsandbox (Apple Virtualization.framework / KVM). Provides sandbox.shell + an opt-in browser.cdp sidecar (Stealth Chromium via CloakBrowser + Playwright MCP + noVNC; lit up by a follow-up PR).",
+  "author": "tianshu-ai",
+  "license": "Apache-2.0",
+  "permissions": ["workspace.read", "workspace.write", "process.spawn"],
+  "provides": ["sandbox.shell", "sandbox.taskPool", "browser.cdp"],
+  "client": { "entry": "@tianshu-builtin/plugin-microsandbox/client" },
+  "server": { "entry": "@tianshu-builtin/plugin-microsandbox/server" },
+  "contributes": {
+    "topBarButtons": [
+      {
+        "id": "browser",
+        "icon": "Globe",
+        "tooltip": "Browser viewport (noVNC)",
+        "opensPanel": "microsandbox.browser",
+        "order": 210
+      }
+    ],
+    "rightPanels": [
+      {
+        "id": "browser",
+        "displayName": "Browser",
+        "component": "BrowserViewportPanel"
+      }
+    ],
+    "adminPages": [
+      {
+        "id": "main",
+        "displayName": "Sandbox",
+        "icon": "Box",
+        "component": "MicroSandboxAdminPage",
+        "group": "Plugins",
+        "order": 100
+      }
+    ],
+    "sandboxes": [
+      {
+        "id": "main",
+        "kind": "shell",
+        "displayName": "MicroSandbox",
+        "module": "MicroSandboxRunner"
+      }
+    ],
+    "tools": [
+      { "id": "exec",                  "module": "ExecTool" },
+      { "id": "reset_sandbox",         "module": "ResetSandboxTool" },
+      { "id": "get_sandbox_status",    "module": "GetSandboxStatusTool" },
+      { "id": "update_sandbox_config", "module": "UpdateSandboxConfigTool" },
+      { "id": "build_sandbox",         "module": "BuildSandboxTool" },
+      { "id": "list_sandbox_builds",   "module": "ListSandboxBuildsTool" },
+      { "id": "use_sandbox_build",     "module": "UseSandboxBuildTool" },
+      { "id": "browser_health_check", "module": "BrowserHealthCheckTool" }
+    ],
+    "toolsets": [
+      { "id": "browser", "module": "BrowserToolset", "displayName": "Playwright (Browser)" }
+    ],
+    "skills": [
+      { "id": "exec-howto",     "path": "skills/microsandbox-exec-howto.md" },
+      { "id": "config",         "path": "skills/microsandbox-config.md" },
+      { "id": "build-use",      "path": "skills/microsandbox-build-use.md" },
+      { "id": "browser-howto",  "path": "skills/microsandbox-browser-howto.md" },
+      { "id": "libreoffice",   "path": "skills/microsandbox-libreoffice.md" }
+    ],
+    "systemPromptFragments": [
+      {
+        "id": "no-foreground-servers",
+        "text": "- Long-running servers (`python -m http.server`, `npm start`, `npm run dev`, anything that listens on a port and never returns) WILL hang the `exec` call until the host's per-call timeout fires (5 min default). Even with `nohup` alone the call hangs because microsandbox's exec channel waits for the started process tree's stdio to close, and nohup doesn't close stdin or detach from the controlling terminal.\n\n  If you need to start a server, the ONLY safe pattern is:\n\n    nohup setsid <cmd> > /tmp/srv.log 2>&1 < /dev/null &\n\n  All four pieces are required: `setsid` puts the process in a new session (no controlling terminal); `< /dev/null` closes stdin; `>/tmp/srv.log 2>&1` redirects stdout AND stderr; trailing `&` puts it in the shell background. Skip any one and exec hangs.\n\n  Then verify with `curl http://localhost:<port>/...` in a separate exec call. Don't background-then-curl in the same shell line \u2014 the shell process itself becomes the parent and won't exit."
+      },
+      {
+        "id": "already-installed-runtimes",
+        "text": "- The sandbox already ships chromium (CDP 9222), Playwright MCP (3200), LibreOffice, Node 22, and Python 3.12. Don't `apt install` / `pip install` / `playwright install` what's already there."
+      },
+      {
+        "id": "task-sandbox-is-ephemeral",
+        "text": "- If you are running as a workboard task worker (you have a workboard task id and your run will end with `task_complete`), the sandbox you `exec` in is per-task and gets stopped the moment the task terminates. Anything you nohup / setsid / disown into the background dies with the sandbox \u2014 don't try to leave servers / queues / cron jobs / file watchers running for someone else to consume. Run the work inline, capture its output to a file under your home, then `task_complete` with the file path.\n\n  Concrete VERIFY-task pattern: if the deliverable is an HTML / PDF / image file and you want to confirm it renders, DON'T spin up `python -m http.server` to serve it. Either (a) use a Playwright MCP `browser_navigate` to `file:///workspace/users/<self>/projects/<slug>/report.html` directly (Playwright MCP is configured with `--allow-unrestricted-file-access`, so file:// URLs work), or (b) `cat` / `head` the file and inspect the structure inline, or (c) for charts, check the rendered file's size + that it contains expected canvas/svg/img markup (`grep -c '<canvas\\|<svg\\|<img' report.html`). Spinning up a transient http server adds a process that has to be cleanly torn down before task_complete, and the typical agent forgets the `setsid + </dev/null` pattern and hangs the run.\n\n  Long-lived background services belong in a chat session (the long-lived sandbox there survives between turns), not in a task. Installed packages, files you wrote, and other on-disk state DO survive across attempts of the same task \u2014 only running processes don't."
+      }
+    ],
+    "apiRoutes": [
+      { "method": "GET",  "path": "/status",          "handler": "status" },
+      { "method": "GET",  "path": "/sandboxfile",     "handler": "getSandboxfile" },
+      { "method": "PUT",  "path": "/sandboxfile",     "handler": "putSandboxfile" },
+      { "method": "GET",  "path": "/sandboxfile/templates", "handler": "getSandboxfileTemplates" },
+      { "method": "GET",  "path": "/builds",          "handler": "getBuilds" },
+      { "method": "POST", "path": "/builds",          "handler": "postBuilds" },
+      { "method": "POST", "path": "/builds/use",      "handler": "postUseBuild" },
+      { "method": "POST", "path": "/reset",           "handler": "postReset" },
+      { "method": "POST", "path": "/exec",            "handler": "postExec" },
+      { "method": "GET",  "path": "/task-pool",       "handler": "getTaskPool" },
+      { "method": "POST", "path": "/task-pool/destroy", "handler": "postTaskPoolDestroy" },
+      { "method": "GET",  "path": "/browser/status",   "handler": "getBrowserStatus" },
+      { "method": "POST", "path": "/browser/restart",  "handler": "postBrowserRestart" },
+      { "method": "POST", "path": "/browser/resize",   "handler": "postBrowserResize" }
+    ]
+  },
+  "configSchema": {
+    "fields": [
+      {
+        "key": "memoryMib",
+        "label": "Browser sandbox memory",
+        "kind": "number",
+        "unit": "MiB",
+        "min": 512,
+        "max": 65536,
+        "step": 512,
+        "default": 2048,
+        "description": "RAM allotted to the long-lived Browser sandbox VM. Increase to 8192+ MiB for browser-heavy workloads (chromium + Playwright MCP), 12288+ for build-time pip / npm of large stacks. Restart the sandbox (Reset) for the new value to take effect."
+      },
+      {
+        "key": "cpus",
+        "label": "Browser sandbox vCPU count",
+        "kind": "number",
+        "min": 1,
+        "max": 16,
+        "step": 1,
+        "default": 2,
+        "description": "Logical CPU count handed to the long-lived Browser sandbox VM. Reset the sandbox after changing."
+      },
+      {
+        "key": "execTimeoutMs",
+        "label": "Per-exec timeout (Browser)",
+        "kind": "number",
+        "unit": "ms",
+        "min": 5000,
+        "max": 1800000,
+        "step": 5000,
+        "default": 300000,
+        "description": "Max wall-clock time for one Browser `exec` call before it's force-killed. Bump this for long-running installers; consider running them with `nohup setsid … &` instead."
+      },
+      {
+        "key": "taskMemoryMib",
+        "label": "Task sandbox memory",
+        "kind": "number",
+        "unit": "MiB",
+        "min": 512,
+        "max": 65536,
+        "step": 512,
+        "default": 2048,
+        "description": "RAM allotted to per-task sandbox VMs (forked from the Task snapshot). Set lower than the Browser value to fit more parallel tasks; raise it for tasks that need a heavy data-science stack. Effective on the next task acquire."
+      },
+      {
+        "key": "taskCpus",
+        "label": "Task sandbox vCPU count",
+        "kind": "number",
+        "min": 1,
+        "max": 16,
+        "step": 1,
+        "default": 2,
+        "description": "Logical CPU count handed to each per-task sandbox VM. Effective on the next task acquire."
+      },
+      {
+        "key": "taskExecTimeoutMs",
+        "label": "Per-exec timeout (Task)",
+        "kind": "number",
+        "unit": "ms",
+        "min": 5000,
+        "max": 1800000,
+        "step": 5000,
+        "default": 300000,
+        "description": "Max wall-clock time for one Task `exec` call before it's force-killed. Per-task sandboxes typically run shorter, more focused commands than the Browser sandbox."
+      },
+      {
+        "key": "taskIdleShutdownMs",
+        "label": "Task sandbox idle shutdown",
+        "kind": "number",
+        "unit": "ms",
+        "min": 0,
+        "max": 86400000,
+        "step": 60000,
+        "default": 600000,
+        "description": "How long a task sandbox stays alive after its task ends before it's stopped. 0 = stop immediately on release. Higher values trade RAM for faster reuse when the same kind of task runs again soon."
+      }
+    ]
+  }
+}

package/plugins/microsandbox/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@tianshu-builtin/plugin-microsandbox",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Per-tenant shell sandbox + browser sidecar driver for Tianshu (builtin plugin, ADR-0004 §9).",
+  "type": "module",
+  "main": "./dist/server.js",
+  "types": "./dist/server.d.ts",
+  "exports": {
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "default": "./dist/server.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "default": "./dist/client.js"
+    },
+    "./manifest.json": "./manifest.json"
+  },
+  "files": ["dist", "src", "skills", "manifest.json"],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch --preserveWatchOutput",
+    "test": "vitest run --passWithNoTests"
+  },
+  "dependencies": {
+    "@tianshu/plugin-sdk": "*",
+    "microsandbox": "^0.5.7"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.1",
+    "@types/react": "^19.2.17",
+    "lucide-react": "^1.17.0",
+    "react": "^19.0.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.6"
+  }
+}

package/plugins/microsandbox/skills/microsandbox-browser-howto.md

@@ -0,0 +1,155 @@
+---
+name: microsandbox-browser-howto
+description: How the embedded browser surface works — three agent tools (browser_navigate / browser_snapshot / browser_screenshot), when each is the right pick, and what to do when the tools are not yet available.
+when:
+  toolPresent: browser_navigate
+---
+
+The microsandbox plugin ships an embedded **Stealth Chromium**
+(CloakBrowser) reachable through Playwright MCP, plus a noVNC
+viewport in the admin Browser page. Three agent tools surface that
+stack:
+
+| Tool | Use when |
+|------|----------|
+| `browser_navigate(url)` | You need a real page render — JS, redirects, cookies. Equivalent to `page.goto()`. |
+| `browser_snapshot()` | You want to *act on* the page next. Returns an accessibility tree (roles, names, refs). Cheap, structured, easy to reason about. |
+| `browser_screenshot()` | You need pixels — visual diffing, vision-model prompting, sharing a screenshot back to the user. |
+
+## Don't install another browser
+
+The sandbox **already has** a chromium running on port 9222 (CDP),
+a Playwright MCP server on 3200, and noVNC on 6080. You will
+sometimes feel like reaching for `pip install playwright &&
+playwright install chromium` or `npx playwright install` to do
+your own scripted scrape — don't.
+
+- `playwright install chromium` downloads ~200 MB to the sandbox
+  every time. The sandbox is ephemeral; the next reset throws
+  the download away. Network egress is restricted; the install
+  often hangs or 403s.
+- A second chromium would race the first for `--user-data-dir`,
+  CDP port 9222, and X11 display :99.
+- The MCP tools (`browser_navigate`, etc.) already cover the 90%
+  case more cheaply than a hand-rolled Playwright script.
+
+Use the MCP tools first. If you genuinely need scripted control
+(login flows with conditional logic, multi-step forms),
+connect to the existing chromium via CDP from inside the sandbox
+shell:
+
+```python
+from playwright.sync_api import sync_playwright
+with sync_playwright() as p:
+    # Reuse the already-running browser — no install step.
+    browser = p.chromium.connect_over_cdp("http://127.0.0.1:9222")
+    page = browser.contexts[0].new_page()
+    page.goto("https://example.com")
+    print(page.title())
+```
+
+`pip install playwright` (the Python package) is fine — it's
+small. **Skip the `playwright install` step**. You're connecting
+to an existing browser, not launching a new one.
+
+## Default workflow
+
+```
+1. browser_navigate("https://…")
+2. browser_snapshot()                 # find the element to act on
+3. browser_screenshot()               # only if you need the picture
+```
+
+Snapshots beat screenshots whenever the model needs to *interact*
+or *extract*. Screenshots are best treated as a presentation
+format, not a comprehension format.
+
+## Tool availability
+
+These tools are gated on the BrowserSidecar reporting a live
+Playwright MCP port. If the chromium stack isn't built into the
+tenant's Sandboxfile yet, the tools won't show up in your tool
+list — there's no point trying to fall back to them.
+
+If the user wants to use the browser:
+
+1. They open `/admin/microsandbox/browser` and check **Status**.
+2. If "not running", they edit the Sandboxfile (Sandbox admin
+   page) to include the browser layer (CloakBrowser + Xvfb +
+   x11vnc + noVNC + Playwright MCP), build, then `use & reset`.
+3. Once the admin page reports `ready: true` with three live
+   ports, your tool list reloads and `browser_*` tools show up.
+
+Don't tell the user "I'll navigate" before the tools are available
+— the call will return a structured error and waste a turn.
+
+## Coordinates and viewports
+
+When the user has the admin Browser page open, the noVNC iframe
+reports its size back to the host via a ResizeObserver, and that
+viewport is reachable through `browser.cdp`'s `getLastViewport()`.
+The browser tools auto-set Playwright's viewport from this before
+each navigation, so screenshots match what the user sees.
+
+If the user is **not** watching the page (no admin tab open), the
+viewport falls back to `1280x800`. Don't write skills that
+hard-code coordinates — they'll only work for one viewport.
+
+## When the browser tools hang
+
+If a `browser_*` call returns a confusing timeout / error, or
+`exec` itself sticks (the symptom is "the conversation just
+stops emitting tokens for 30+s"), call:
+
+```
+browser_health_check()
+```
+
+It probes CDP `/json/version` with a 2.5s timeout and returns
+`{ok, latencyMs, error?, suggestion?}`. The `suggestion` field
+tells you the next concrete recovery step:
+
+- **CDP host port not mapped**: the snapshot you booted doesn't
+  ship the browser stack. Build one that does (template
+  `browser.yaml`).
+- **CDP not reachable / connect refused**: chromium or
+  supervisord crashed inside the guest. Try `browser_restart`
+  first (cheap, ~5s). If the next `browser_health_check` still
+  fails, escalate to `reset_sandbox`.
+- **CDP probe timed out**: the sandbox VM itself is wedged.
+  Skip `browser_restart` (it'll hang too) and go straight to
+  `reset_sandbox`. Files under `/workspace` survive.
+
+Don't loop the probe — call once, act on the suggestion, call
+again only after attempting recovery.
+
+## What NOT to do
+
+- Don't `browser_navigate` to user input as a URL without
+  validating the scheme. Stick to `https://` for arbitrary user
+  input; if the user explicitly asks for a local resource (a
+  service running in the same sandbox), confirm `http://localhost`
+  is intended.
+- Don't `browser_screenshot` without `browser_navigate` first —
+  the tool will return whatever the page state was, which may be
+  blank or the previous user's content.
+- Don't paste large snapshot blobs back into the chat verbatim.
+  Summarise: "the page has a search box (ref=e3) and a list of 12
+  results (refs=e7..e18)" is much more useful than 4 KB of AX
+  JSON.
+- Don't expect the embedded chromium to share cookies with the
+  user's host browser. Each sandbox has an isolated profile;
+  authenticated sessions need to be performed inside the sandbox
+  (e.g. via `browser_navigate` to a login URL the user trusts).
+
+## Why CloakBrowser instead of stock Chromium
+
+Stock headless chromium leaks several automation tells (navigator.
+webdriver, headless UA, missing GPU/WebGL profile, abnormal
+plugin/font lists). CloakBrowser patches those at the C++ source
+level, so common bot-detection sites don't refuse the page. Same
+Playwright API, drop-in `launch()` replacement.
+
+This does **not** mean you can ignore site terms of service.
+Realistic fingerprints help compatibility, not authorisation. If a
+site's TOS forbids automated access, that's still a no.