@aliceshimada/mica 1.0.0

package/dist/src/bridge/httpBridge.js

@@ -0,0 +1,366 @@
+import http from "node:http";
+import { DEFAULT_BRIDGE_HOST, DEFAULT_BRIDGE_PORT } from "../types.js";
+const DEFAULT_PALETTE_STALE_TIMEOUT_MS = 30_000;
+export class HttpBridge {
+    queue;
+    options;
+    server;
+    attachedNotebook;
+    permissions;
+    notebooks = new Map();
+    activeNotebookId;
+    /** Timestamp (ms) of the last Palette heartbeat. 0 = never connected. */
+    lastPaletteHeartbeat = 0;
+    paletteStaleTimeoutMs;
+    static MAX_BODY_BYTES = 1024 * 1024; // 1 MiB
+    constructor(queue, options = {}) {
+        this.queue = queue;
+        this.options = options;
+        this.paletteStaleTimeoutMs =
+            options.paletteStaleTimeoutMs ?? DEFAULT_PALETTE_STALE_TIMEOUT_MS;
+        this.server = http.createServer((request, response) => {
+            this.handle(request, response);
+        });
+    }
+    get port() {
+        const address = this.server.address();
+        return address?.port ?? this.options.port ?? DEFAULT_BRIDGE_PORT;
+    }
+    /**
+     * Return a snapshot of the current bridge status.
+     *
+     * Exposed so the MCP `mma_status` tool can report real Palette connection
+     * and notebook attachment state instead of hardcoded false values.
+     */
+    statusSnapshot() {
+        return this.status();
+    }
+    async start() {
+        const host = this.options.host ?? DEFAULT_BRIDGE_HOST;
+        const port = this.options.port ?? DEFAULT_BRIDGE_PORT;
+        await new Promise((resolve) => this.server.listen(port, host, resolve));
+    }
+    async stop() {
+        // Close the HTTP server first to prevent new interactions, then drain
+        // the queue so pending MCP promises don't hang.
+        if (this.server.listening) {
+            await new Promise((resolve, reject) => {
+                this.server.close((error) => (error ? reject(error) : resolve()));
+            });
+        }
+        this.queue.drain("HTTP bridge stopped");
+    }
+    async handle(request, response) {
+        try {
+            const url = new URL(request.url ?? "/", "http://127.0.0.1");
+            if (request.method === "GET" && url.pathname === "/status") {
+                this.sendJson(response, 200, this.status());
+                return;
+            }
+            if (request.method === "POST" && url.pathname === "/attach") {
+                const body = await this.readJson(request);
+                if (typeof body !== "object" || body === null || Object.keys(body).length === 0) {
+                    this.sendJson(response, 400, {
+                        error: { code: "BAD_REQUEST", message: "attach body must be a non-empty JSON object" }
+                    });
+                    return;
+                }
+                const attach = body;
+                const permissions = Object.prototype.hasOwnProperty.call(attach, "permissions")
+                    ? this.parsePermissions(attach.permissions)
+                    : undefined;
+                if (Object.prototype.hasOwnProperty.call(attach, "permissions") && !permissions) {
+                    this.sendJson(response, 400, {
+                        error: { code: "BAD_REQUEST", message: "permissions must include boolean values" }
+                    });
+                    return;
+                }
+                this.attachedNotebook = permissions ? { ...attach, permissions } : attach;
+                this.permissions = permissions;
+                if (typeof attach.notebookId === "string" && attach.notebookId.length > 0) {
+                    this.upsertNotebook({
+                        notebookId: attach.notebookId,
+                        notebookTitle: attach.notebookTitle,
+                        notebookPath: attach.notebookPath,
+                        wolframVersion: attach.wolframVersion,
+                        platform: attach.platform,
+                        permissions,
+                        lastSeenAt: Date.now()
+                    });
+                }
+                this.heartbeat();
+                this.sendJson(response, 200, { ok: true });
+                return;
+            }
+            if (request.method === "POST" && url.pathname === "/notebooks/upsert") {
+                const body = await this.readJson(request);
+                if (!this.isNotebookPayload(body)) {
+                    this.sendJson(response, 400, {
+                        error: { code: "BAD_REQUEST", message: "notebookId is required" }
+                    });
+                    return;
+                }
+                this.upsertNotebook({
+                    notebookId: body.notebookId,
+                    notebookTitle: body.notebookTitle,
+                    notebookPath: body.notebookPath,
+                    wolframVersion: body.wolframVersion,
+                    platform: body.platform,
+                    permissions: this.parsePermissions(body),
+                    lastSeenAt: Date.now()
+                });
+                if (!this.activeNotebookId) {
+                    this.activeNotebookId = body.notebookId;
+                }
+                this.heartbeat();
+                this.sendJson(response, 200, { ok: true, activeNotebookId: this.activeNotebookId });
+                return;
+            }
+            if (request.method === "GET" && url.pathname === "/notebooks") {
+                this.sendJson(response, 200, {
+                    notebooks: this.listNotebooks(),
+                    activeNotebookId: this.activeNotebookId
+                });
+                return;
+            }
+            if (request.method === "POST" && url.pathname === "/notebooks/select") {
+                const body = await this.readJson(request);
+                const notebookId = this.getNotebookId(body);
+                if (!notebookId) {
+                    this.sendJson(response, 400, {
+                        error: { code: "BAD_REQUEST", message: "notebookId is required" }
+                    });
+                    return;
+                }
+                if (!this.notebooks.has(notebookId)) {
+                    this.sendJson(response, 404, {
+                        error: { code: "NOTEBOOK_NOT_FOUND", message: `Unknown notebookId: ${notebookId}` }
+                    });
+                    return;
+                }
+                this.activeNotebookId = notebookId;
+                this.heartbeat();
+                this.sendJson(response, 200, { ok: true, activeNotebookId: this.activeNotebookId });
+                return;
+            }
+            if (request.method === "GET" && url.pathname === "/poll") {
+                const activeNotebookId = url.searchParams.get("activeNotebookId");
+                if (activeNotebookId && this.notebooks.has(activeNotebookId)) {
+                    this.activeNotebookId = activeNotebookId;
+                }
+                this.heartbeat();
+                const requestInfo = this.queue.claimNext();
+                const body = {
+                    status: this.status(),
+                    cancelRequests: this.queue.listCancellations(),
+                    request: requestInfo
+                };
+                this.sendJson(response, 200, body);
+                return;
+            }
+            if (request.method === "POST" && url.pathname === "/permissions") {
+                const body = await this.readJson(request);
+                const permissions = this.parsePermissions(body);
+                if (!permissions) {
+                    this.sendJson(response, 400, {
+                        error: { code: "BAD_REQUEST", message: "permissions must include boolean values" }
+                    });
+                    return;
+                }
+                this.permissions = permissions;
+                if (this.attachedNotebook) {
+                    this.attachedNotebook = { ...this.attachedNotebook, permissions };
+                }
+                const attachedNotebookId = this.getAttachedNotebookId();
+                if (attachedNotebookId) {
+                    this.upsertNotebook({
+                        notebookId: attachedNotebookId,
+                        notebookTitle: this.attachedNotebook?.notebookTitle,
+                        notebookPath: this.attachedNotebook?.notebookPath,
+                        wolframVersion: this.attachedNotebook?.wolframVersion,
+                        platform: this.attachedNotebook?.platform,
+                        permissions,
+                        lastSeenAt: Date.now()
+                    });
+                }
+                this.sendJson(response, 200, { ok: true });
+                return;
+            }
+            if (request.method === "GET" && url.pathname === "/requests") {
+                this.heartbeat();
+                this.sendJson(response, 200, { request: this.queue.claimNext() });
+                return;
+            }
+            if (request.method === "POST" && url.pathname === "/result") {
+                const body = (await this.readJson(request));
+                const accepted = body.ok
+                    ? this.queue.resolveSuccess(body.requestId, body.result)
+                    : this.queue.resolveFailure(body.requestId, body.error.code, body.error.message);
+                this.sendJson(response, accepted ? 200 : 404, { ok: accepted });
+                return;
+            }
+            if (request.method === "GET" && url.pathname === "/cancellations") {
+                this.sendJson(response, 200, { cancelRequests: this.queue.listCancellations() });
+                return;
+            }
+            if (request.method === "POST" && url.pathname === "/cancel") {
+                const body = (await this.readJson(request));
+                if (!body.requestId) {
+                    this.sendJson(response, 400, { error: { code: "BAD_REQUEST", message: "requestId is required" } });
+                    return;
+                }
+                const accepted = this.queue.cancelFromPalette(body.requestId, body.reason ?? "USER_CANCELLED_IN_PALETTE");
+                this.sendJson(response, accepted ? 200 : 404, { ok: accepted });
+                return;
+            }
+            this.sendJson(response, 404, { error: { code: "NOT_FOUND", message: `${request.method} ${url.pathname}` } });
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            if (msg === "PAYLOAD_TOO_LARGE") {
+                this.sendJson(response, 413, { error: { code: "PAYLOAD_TOO_LARGE", message: "Request body exceeds 1 MiB limit" } });
+            }
+            else if (msg === "MALFORMED_JSON") {
+                this.sendJson(response, 400, { error: { code: "BAD_REQUEST", message: "Malformed JSON body" } });
+            }
+            else {
+                this.sendJson(response, 500, { error: { code: "INTERNAL_ERROR", message: msg } });
+            }
+        }
+    }
+    status() {
+        const permissions = this.permissions ?? this.attachedNotebook?.permissions;
+        const runningRequest = this.queue.runningRequestSnapshot();
+        const notebookAttached = Boolean(this.attachedNotebook) || Boolean(this.activeNotebookId && this.notebooks.has(this.activeNotebookId));
+        return {
+            server: "running",
+            paletteConnected: this.isPaletteConnected(),
+            notebookAttached,
+            attachedNotebook: this.attachedNotebook,
+            permissions,
+            activeNotebookId: this.activeNotebookId,
+            notebooks: this.listNotebooks(),
+            transportMode: "main-kernel",
+            executorState: runningRequest ? "running" : "idle",
+            runningRequest,
+            pendingRequests: this.queue.pendingCount()
+        };
+    }
+    upsertNotebook(notebook) {
+        const existing = this.notebooks.get(notebook.notebookId);
+        this.notebooks.set(notebook.notebookId, {
+            ...(existing ?? { notebookId: notebook.notebookId, lastSeenAt: notebook.lastSeenAt }),
+            ...notebook
+        });
+    }
+    listNotebooks() {
+        return [...this.notebooks.values()];
+    }
+    getNotebookId(payload) {
+        if (typeof payload !== "object" || payload === null || Array.isArray(payload)) {
+            return undefined;
+        }
+        const record = payload;
+        return typeof record.notebookId === "string" && record.notebookId.length > 0 ? record.notebookId : undefined;
+    }
+    isNotebookPayload(payload) {
+        return this.getNotebookId(payload) !== undefined;
+    }
+    getAttachedNotebookId() {
+        if (!this.attachedNotebook)
+            return undefined;
+        return typeof this.attachedNotebook.notebookId === "string"
+            ? this.attachedNotebook.notebookId
+            : undefined;
+    }
+    /**
+     * Record a Palette heartbeat, refreshing the connection timestamp.
+     *
+     * Called on POST /attach and GET /requests — the two endpoints the Palette
+     * uses to interact with the bridge. If the Palette stops polling, the
+     * heartbeat expires and {@link isPaletteConnected} returns false.
+     */
+    heartbeat() {
+        this.lastPaletteHeartbeat = Date.now();
+    }
+    /**
+     * Whether the Palette is considered connected based on heartbeat freshness.
+     *
+     * Returns true only if the Palette has sent a heartbeat within
+     * `paletteStaleTimeoutMs`. This prevents agents from enqueuing requests
+     * that will never be claimed after the Palette dies or disconnects.
+     */
+    isPaletteConnected() {
+        if (this.lastPaletteHeartbeat === 0)
+            return false;
+        return Date.now() - this.lastPaletteHeartbeat < this.paletteStaleTimeoutMs;
+    }
+    parsePermissions(payload) {
+        const source = this.getPermissionsSource(payload);
+        if (!source)
+            return undefined;
+        const keys = [
+            "ReadNotebook",
+            "InsertCell",
+            "ModifyCell",
+            "DeleteCell",
+            "RunCell",
+            "SaveNotebook"
+        ];
+        const permissions = {};
+        for (const key of keys) {
+            if (typeof source[key] !== "boolean") {
+                return undefined;
+            }
+            permissions[key] = source[key];
+        }
+        return permissions;
+    }
+    getPermissionsSource(payload) {
+        if (typeof payload !== "object" || payload === null || Array.isArray(payload)) {
+            return null;
+        }
+        const record = payload;
+        if (Object.prototype.hasOwnProperty.call(record, "permissions")) {
+            const nested = record.permissions;
+            if (typeof nested !== "object" || nested === null || Array.isArray(nested)) {
+                return null;
+            }
+            return nested;
+        }
+        return record;
+    }
+    async readJson(request) {
+        const chunks = [];
+        let totalBytes = 0;
+        let exceeded = false;
+        for await (const chunk of request) {
+            if (exceeded)
+                continue; // drain remaining chunks
+            const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            totalBytes += buf.length;
+            if (totalBytes > HttpBridge.MAX_BODY_BYTES) {
+                exceeded = true;
+                chunks.length = 0; // discard accumulated data
+                continue;
+            }
+            chunks.push(buf);
+        }
+        if (exceeded) {
+            throw new Error("PAYLOAD_TOO_LARGE");
+        }
+        const text = Buffer.concat(chunks).toString("utf8");
+        if (text.length === 0)
+            return {};
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            throw new Error("MALFORMED_JSON");
+        }
+    }
+    sendJson(response, statusCode, body) {
+        response.writeHead(statusCode, { "content-type": "application/json; charset=utf-8" });
+        response.end(JSON.stringify(body));
+    }
+}

package/dist/src/bridge/requestQueue.js

@@ -0,0 +1,200 @@
+/**
+ * Serial request queue for the MMA MCP bridge.
+ *
+ * Only one notebook operation is processed at a time. The MCP client enqueues
+ * tool calls, the Mathematica Palette polls and claims them, then posts results
+ * back. Cancellation is supported from both sides.
+ *
+ * ## Cancellation semantics
+ *
+ * **MCP-client cancellation** (`cancelFromMcp`):
+ * - Queued requests are rejected immediately and removed.
+ * - Claimed requests are rejected immediately and removed, and a one-shot
+ *   cancellation notification is stored for the Palette to pick up via
+ *   `listCancellations`. This ensures the MCP call terminates instead of
+ *   hanging indefinitely.
+ *
+ * **Palette-originated cancellation** (`cancelFromPalette`):
+ * - The Palette already knows it is cancelling, so no notification is stored.
+ *   The active call is rejected and removed immediately.
+ */
+export class RequestQueue {
+    counter = 0;
+    calls = new Map();
+    order = [];
+    /**
+     * One-shot cancellation notifications for the Palette.
+     * Populated by cancelFromMcp on claimed requests, drained by listCancellations.
+     */
+    cancellations = [];
+    /**
+     * Enqueue a tool call and return only the promise.
+     *
+     * Convenience wrapper around {@link enqueueWithId} for callers that don't
+     * need the requestId (e.g. tests, simple fire-and-forget usage).
+     */
+    enqueue(tool, args) {
+        return this.enqueueWithId(tool, args).promise;
+    }
+    /**
+     * Enqueue a tool call and return both the requestId and the promise.
+     *
+     * The requestId is needed by MCP tool handlers so they can wire an
+     * AbortSignal listener to {@link cancelFromMcp}.
+     */
+    enqueueWithId(tool, args) {
+        const notebookId = typeof args.notebookId === "string" && args.notebookId.length > 0 ? args.notebookId : undefined;
+        const requestId = `req_${++this.counter}`;
+        const request = {
+            requestId,
+            tool,
+            arguments: args,
+            notebookId,
+            state: "queued",
+            createdAt: Date.now()
+        };
+        const promise = new Promise((resolve, reject) => {
+            this.calls.set(requestId, { request, resolve, reject });
+            this.order.push(requestId);
+        });
+        return { requestId, promise };
+    }
+    claimNext() {
+        if ([...this.calls.values()].some((call) => call.request.state === "claimed")) {
+            return null;
+        }
+        const requestId = this.order.find((id) => this.calls.get(id)?.request.state === "queued");
+        if (!requestId)
+            return null;
+        const call = this.calls.get(requestId);
+        if (!call)
+            return null;
+        call.request.state = "claimed";
+        call.request.claimedAt = Date.now();
+        return { ...call.request, arguments: { ...call.request.arguments } };
+    }
+    runningRequestSnapshot() {
+        const running = this.order
+            .map((id) => this.calls.get(id)?.request)
+            .find((request) => request !== undefined && request.state === "claimed");
+        if (!running || running.claimedAt === undefined)
+            return null;
+        return {
+            requestId: running.requestId,
+            tool: running.tool,
+            arguments: { ...running.arguments },
+            notebookId: running.notebookId,
+            state: "claimed",
+            createdAt: running.createdAt,
+            claimedAt: running.claimedAt
+        };
+    }
+    peekQueued() {
+        return this.order
+            .map((id) => this.calls.get(id)?.request)
+            .filter((request) => request !== undefined && request.state === "queued")
+            .map((request) => ({ ...request, arguments: { ...request.arguments } }));
+    }
+    pendingCount() {
+        return [...this.calls.values()].filter((call) => call.request.state === "queued" || call.request.state === "claimed").length;
+    }
+    resolveSuccess(requestId, result) {
+        const call = this.calls.get(requestId);
+        if (!call)
+            return false;
+        if (call.request.state !== "claimed")
+            return false;
+        call.request.state = "completed";
+        call.resolve(result);
+        this.remove(requestId);
+        return true;
+    }
+    resolveFailure(requestId, code, message) {
+        const call = this.calls.get(requestId);
+        if (!call)
+            return false;
+        if (call.request.state !== "claimed")
+            return false;
+        call.request.state = "failed";
+        call.reject(new Error(`${code}: ${message}`));
+        this.remove(requestId);
+        return true;
+    }
+    /**
+     * Cancel a request from the MCP client side.
+     *
+     * - Queued: rejects the promise and removes the call immediately.
+     * - Claimed: rejects the promise, removes the call, and stores a one-shot
+     *   cancellation notification for the Palette to discover via listCancellations.
+     * - Unknown/removed: returns false.
+     */
+    cancelFromMcp(requestId, reason) {
+        const call = this.calls.get(requestId);
+        if (!call)
+            return false;
+        if (call.request.state === "queued") {
+            call.request.state = "cancelled";
+            call.reject(new Error(reason));
+            this.remove(requestId);
+            return true;
+        }
+        // Claimed: reject immediately so the MCP call terminates, and store a
+        // one-shot notification for the Palette to pick up.
+        call.request.state = "cancelled";
+        call.reject(new Error(reason));
+        this.cancellations.push({ requestId, reason });
+        this.remove(requestId);
+        return true;
+    }
+    /**
+     * Cancel a request originating from the Palette (user action in Mathematica).
+     *
+     * Rejects the promise and removes the call immediately. No cancellation
+     * notification is stored because the Palette already knows it cancelled.
+     * Returns false if the requestId is unknown or already removed.
+     */
+    cancelFromPalette(requestId, reason) {
+        const call = this.calls.get(requestId);
+        if (!call)
+            return false;
+        call.request.state = "cancelled";
+        call.reject(new Error(reason));
+        this.remove(requestId);
+        return true;
+    }
+    /**
+     * Return pending one-shot MCP cancellation notifications and clear them.
+     *
+     * The Palette polls this endpoint to discover claimed requests that were
+     * cancelled by the MCP client. Each cancellation is reported exactly once.
+     */
+    listCancellations() {
+        if (this.cancellations.length === 0)
+            return [];
+        const result = [...this.cancellations];
+        this.cancellations.length = 0;
+        return result;
+    }
+    /**
+     * Reject all outstanding promises and clear all internal state.
+     *
+     * Used when the HTTP bridge shuts down so pending MCP tool-call promises
+     * don't hang indefinitely. Clears active calls, FIFO order, and one-shot
+     * cancellation notifications.
+     */
+    drain(reason) {
+        for (const call of this.calls.values()) {
+            call.request.state = "cancelled";
+            call.reject(new Error(reason));
+        }
+        this.calls.clear();
+        this.order.length = 0;
+        this.cancellations.length = 0;
+    }
+    remove(requestId) {
+        this.calls.delete(requestId);
+        const index = this.order.indexOf(requestId);
+        if (index >= 0)
+            this.order.splice(index, 1);
+    }
+}