@aliceshimada/mica 1.0.0

package/SECURITY.md

@@ -0,0 +1,22 @@
+# Security Policy
+
+## Supported scope
+
+MICA is designed for local control of already-open Wolfram Desktop / Mathematica notebooks. Wolfram Desktop / Mathematica 14.1+ is supported; Mathematica 13.x / 14.0 remains experimental. Headless Wolfram Engine is not supported for live notebook control.
+
+## Security assumptions
+
+- The HTTP bridge binds to `127.0.0.1` / localhost by default.
+- MICA has no remote mode. Do not expose the bridge port to a network.
+- Protocol endpoints require bearer token auth with the generated local session token.
+- The dashboard token is carried in the URL fragment (`#token=...`) and should be treated as sensitive for the current user session.
+- Notebook mutation permissions are explicit. Insert, modify, delete, run, and save operations are controlled by the Wolfram permission block installed for the bridge.
+- MICA does not provide an arbitrary shell tool or a raw-eval MCP endpoint.
+
+## Reporting vulnerabilities
+
+Report security issues through the GitHub repository security contact or issues page:
+
+https://github.com/Alice-Shimada/mica/issues
+
+Please avoid including sensitive notebook content, bearer tokens, or local session files in public reports.

package/dist/src/backend/agentRegistry.js

@@ -0,0 +1,115 @@
+export class AgentRegistry {
+    agents = new Map();
+    register(input) {
+        const next = {
+            agentSessionId: input.agentSessionId,
+            wolframVersion: input.wolframVersion,
+            platform: input.platform,
+            lastSeenAt: input.seenAt,
+            degradedAt: undefined,
+            degraded: false,
+            offlineAt: undefined,
+            offline: false,
+            retired: false,
+            retiredReason: undefined,
+            status: "live",
+            machineId: input.machineId,
+            frontendSessionId: input.frontendSessionId,
+            wolframProcessId: input.wolframProcessId,
+        };
+        this.agents.set(input.agentSessionId, next);
+        return this.clone(next);
+    }
+    heartbeat(agentSessionId, seenAt) {
+        const existing = this.agents.get(agentSessionId);
+        if (!existing)
+            return undefined;
+        if (existing.retired)
+            return undefined;
+        const next = {
+            ...existing,
+            lastSeenAt: seenAt,
+            degradedAt: undefined,
+            degraded: false,
+            offlineAt: undefined,
+            offline: false,
+            retired: false,
+            retiredReason: undefined,
+            status: "live",
+        };
+        this.agents.set(agentSessionId, next);
+        return this.clone(next);
+    }
+    retire(agentSessionId, retiredAt, reason = "no_live_notebooks") {
+        const existing = this.agents.get(agentSessionId);
+        if (!existing || existing.retired)
+            return existing ? this.clone(existing) : undefined;
+        const next = {
+            ...existing,
+            degraded: false,
+            degradedAt: undefined,
+            offline: true,
+            retired: true,
+            retiredReason: reason,
+            offlineAt: retiredAt,
+            status: "retired",
+        };
+        this.agents.set(agentSessionId, next);
+        return this.clone(next);
+    }
+    get(agentSessionId) {
+        const existing = this.agents.get(agentSessionId);
+        return existing ? this.clone(existing) : undefined;
+    }
+    list() {
+        return [...this.agents.values()]
+            .sort((a, b) => b.lastSeenAt - a.lastSeenAt)
+            .map((agent) => this.clone(agent));
+    }
+    hasLiveAgent() {
+        for (const agent of this.agents.values()) {
+            if (!agent.offline && !agent.retired)
+                return true;
+        }
+        return false;
+    }
+    markOfflineOlderThan(now, maxAgeMs) {
+        const newlyOffline = [];
+        for (const agent of this.agents.values()) {
+            if (agent.offline || agent.retired)
+                continue;
+            if (now - agent.lastSeenAt < maxAgeMs)
+                continue;
+            this.agents.set(agent.agentSessionId, {
+                ...agent,
+                degraded: false,
+                degradedAt: undefined,
+                offline: true,
+                offlineAt: now,
+                status: "offline",
+            });
+            newlyOffline.push(agent.agentSessionId);
+        }
+        return newlyOffline;
+    }
+    markDegradedOlderThan(now, maxAgeMs) {
+        const newlyDegraded = [];
+        for (const agent of this.agents.values()) {
+            if (agent.degraded || agent.offline || agent.retired)
+                continue;
+            if (now - agent.lastSeenAt < maxAgeMs)
+                continue;
+            this.agents.set(agent.agentSessionId, {
+                ...agent,
+                degraded: true,
+                degradedAt: now,
+                status: "degraded",
+            });
+            newlyDegraded.push(agent.agentSessionId);
+        }
+        return newlyDegraded;
+    }
+    clone(agent) {
+        return { ...agent };
+    }
+}

package/dist/src/backend/backendQueue.js

@@ -0,0 +1,212 @@
+const SNAPSHOT_STATUSES = [
+    "queued",
+    "dispatched",
+    "running",
+    "succeeded",
+    "failed",
+    "timed_out",
+    "cancelled",
+];
+export class BackendQueue {
+    static DEFAULT_TERMINAL_HISTORY_LIMIT = 500;
+    requests = new Map();
+    completions = new Map();
+    waiters = new Map();
+    cancellations = new Map();
+    terminalOrder = [];
+    enqueue(input) {
+        if (this.requests.has(input.requestId)) {
+            throw new Error(`Duplicate requestId: ${input.requestId}`);
+        }
+        const request = this.cloneRequest({ ...input, status: "queued" });
+        this.requests.set(request.requestId, request);
+        return this.cloneRequest(request);
+    }
+    get(requestId) {
+        const request = this.requests.get(requestId);
+        return request ? this.cloneRequest(request) : undefined;
+    }
+    claimNext(agentSessionId, claimedAt) {
+        let next;
+        const busyNotebooks = new Set();
+        for (const request of this.requests.values()) {
+            if ((request.status === "running" || request.status === "dispatched") && request.targetNotebookId) {
+                busyNotebooks.add(request.targetNotebookId);
+            }
+        }
+        for (const request of this.requests.values()) {
+            if (request.status !== "queued" || request.agentSessionId !== agentSessionId)
+                continue;
+            if (busyNotebooks.has(request.targetNotebookId))
+                continue;
+            if (!next || request.createdAt < next.createdAt) {
+                next = request;
+            }
+        }
+        if (!next)
+            return undefined;
+        const updated = this.cloneRequest({ ...next, status: "running", claimedAt });
+        this.requests.set(updated.requestId, updated);
+        return this.cloneRequest(updated);
+    }
+    waitForResult(requestId) {
+        const request = this.requests.get(requestId);
+        if (!request) {
+            return Promise.reject(new Error("REQUEST_NOT_FOUND"));
+        }
+        const completion = this.completions.get(requestId);
+        if (completion) {
+            return completion.status === "succeeded" ? Promise.resolve(this.cloneValue(completion.result)) : Promise.reject(completion.error);
+        }
+        if (request.status === "succeeded") {
+            return Promise.resolve(undefined);
+        }
+        if (request.status === "failed") {
+            return Promise.reject(new Error("REQUEST_FAILED"));
+        }
+        if (request.status === "timed_out") {
+            return Promise.reject(new Error("REQUEST_TIMED_OUT"));
+        }
+        if (request.status === "cancelled") {
+            return Promise.reject(new Error("REQUEST_CANCELLED"));
+        }
+        return new Promise((resolve, reject) => {
+            const waiters = this.waiters.get(requestId) ?? [];
+            waiters.push({ resolve, reject });
+            this.waiters.set(requestId, waiters);
+        });
+    }
+    markTimedOut(now) {
+        const timedOut = [];
+        for (const request of this.requests.values()) {
+            if (request.status !== "queued" && request.status !== "running")
+                continue;
+            if (now - request.createdAt < request.timeoutMs)
+                continue;
+            const updated = this.cloneRequest({ ...request, status: "timed_out" });
+            this.requests.set(request.requestId, updated);
+            this.completions.set(request.requestId, { status: "timed_out", error: new Error("REQUEST_TIMED_OUT") });
+            this.settleWaiters(request.requestId, undefined, new Error("REQUEST_TIMED_OUT"));
+            this.recordTerminal(request.requestId);
+            timedOut.push(request.requestId);
+        }
+        return timedOut;
+    }
+    resolve(requestId, _payload, resolvedAt) {
+        const request = this.requests.get(requestId);
+        if (!request)
+            return { accepted: false, late: false };
+        if (request.status === "timed_out")
+            return { accepted: false, late: true };
+        if (request.status === "cancelled")
+            return { accepted: false, late: true };
+        if (request.status !== "queued" && request.status !== "running" && request.status !== "dispatched") {
+            return { accepted: false, late: false };
+        }
+        const updated = this.cloneRequest({ ...request, status: "succeeded", claimedAt: request.claimedAt ?? resolvedAt });
+        this.requests.set(requestId, updated);
+        this.completions.set(requestId, { status: "succeeded", result: this.cloneValue(_payload) });
+        this.settleWaiters(requestId, this.cloneValue(_payload), undefined);
+        this.recordTerminal(requestId);
+        return { accepted: true, late: false };
+    }
+    fail(requestId, error) {
+        const request = this.requests.get(requestId);
+        if (!request)
+            return false;
+        if (request.status !== "queued" && request.status !== "running" && request.status !== "dispatched") {
+            return false;
+        }
+        const rejection = this.toError(error, "REQUEST_FAILED");
+        this.requests.set(requestId, this.cloneRequest({ ...request, status: "failed" }));
+        this.completions.set(requestId, { status: "failed", error: rejection });
+        this.settleWaiters(requestId, undefined, rejection);
+        this.recordTerminal(requestId);
+        return true;
+    }
+    cancel(requestId, reason, cancelledAt) {
+        const request = this.requests.get(requestId);
+        if (!request)
+            return false;
+        if (request.status !== "queued" && request.status !== "running")
+            return false;
+        this.requests.set(requestId, this.cloneRequest({ ...request, status: "cancelled", claimedAt: request.claimedAt ?? cancelledAt }));
+        const rejection = new Error(reason);
+        this.completions.set(requestId, { status: "cancelled", error: rejection });
+        this.settleWaiters(requestId, undefined, rejection);
+        this.recordTerminal(requestId);
+        const agentSessionId = request.agentSessionId;
+        if (!agentSessionId)
+            return true;
+        const notices = this.cancellations.get(agentSessionId) ?? [];
+        notices.push({ requestId, reason });
+        this.cancellations.set(agentSessionId, notices);
+        return true;
+    }
+    cancellationsForAgent(agentSessionId) {
+        const notices = this.cancellations.get(agentSessionId) ?? [];
+        this.cancellations.set(agentSessionId, []);
+        return notices.map((notice) => ({ ...notice }));
+    }
+    snapshot() {
+        const snapshot = Object.fromEntries(SNAPSHOT_STATUSES.map((status) => [
+            status,
+            [...this.requests.values()].filter((request) => request.status === status).map((request) => this.cloneRequest(request)),
+        ]));
+        return snapshot;
+    }
+    cloneRequest(request) {
+        return {
+            ...request,
+            arguments: this.cloneValue(request.arguments),
+        };
+    }
+    cloneValue(value) {
+        if (value === undefined)
+            return value;
+        return typeof structuredClone === "function" ? structuredClone(value) : JSON.parse(JSON.stringify(value));
+    }
+    settleWaiters(requestId, value, error) {
+        const waiters = this.waiters.get(requestId);
+        if (!waiters || waiters.length === 0)
+            return;
+        this.waiters.delete(requestId);
+        for (const waiter of waiters) {
+            if (error) {
+                waiter.reject(error);
+            }
+            else {
+                waiter.resolve(this.cloneValue(value));
+            }
+        }
+    }
+    toError(value, fallbackMessage) {
+        if (value instanceof Error)
+            return value;
+        if (typeof value === "string" && value.trim())
+            return new Error(value);
+        if (typeof value === "object" && value !== null) {
+            const record = value;
+            const code = typeof record.code === "string" && record.code.trim() ? record.code.trim() : undefined;
+            const message = typeof record.message === "string" && record.message.trim() ? record.message.trim() : undefined;
+            if (code && message)
+                return new Error(`${code}: ${message}`);
+            if (code)
+                return new Error(code);
+            if (message)
+                return new Error(message);
+        }
+        return new Error(fallbackMessage);
+    }
+    recordTerminal(requestId) {
+        this.terminalOrder.push(requestId);
+        while (this.terminalOrder.length > BackendQueue.DEFAULT_TERMINAL_HISTORY_LIMIT) {
+            const evictedRequestId = this.terminalOrder.shift();
+            if (!evictedRequestId)
+                continue;
+            this.requests.delete(evictedRequestId);
+            this.completions.delete(evictedRequestId);
+            this.waiters.delete(evictedRequestId);
+        }
+    }
+}

package/dist/src/backend/backendState.js

@@ -0,0 +1,99 @@
+import { AgentRegistry } from "./agentRegistry.js";
+import { BackendQueue } from "./backendQueue.js";
+import { NotebookRegistry } from "./notebookRegistry.js";
+import { DEFAULT_TIMEOUTS_MS } from "./protocol.js";
+export class BackendState {
+    agents;
+    notebooks;
+    queue = new BackendQueue();
+    activeNotebookId;
+    activeNotebookByClientSession = new Map();
+    constructor(createNotebookId) {
+        this.notebooks = new NotebookRegistry(createNotebookId);
+        this.agents = new AgentRegistry();
+    }
+    setActiveNotebook(notebookId, clientSessionId) {
+        if (clientSessionId) {
+            this.activeNotebookByClientSession.set(clientSessionId, notebookId);
+        }
+        else {
+            this.activeNotebookId = notebookId;
+        }
+    }
+    sweepLiveness(now = Date.now()) {
+        const degradedAgents = this.agents.markDegradedOlderThan(now, DEFAULT_TIMEOUTS_MS.agentHeartbeatDegradedMs);
+        for (const agentSessionId of degradedAgents) {
+            this.notebooks.markDegradedByAgent(agentSessionId, now);
+        }
+        const offlineAgents = this.agents.markOfflineOlderThan(now, DEFAULT_TIMEOUTS_MS.agentHeartbeatOfflineMs);
+        for (const agentSessionId of offlineAgents) {
+            this.notebooks.markStaleByAgent(agentSessionId, now);
+        }
+        this.clearInactiveActiveNotebook();
+        return {
+            offlineAgents,
+            staleNotebooks: this.notebooks.listAll().filter((record) => record.stale).map((record) => record.notebookId),
+        };
+    }
+    requireLiveAgent() {
+        return this.agents.hasLiveAgent() ? { ok: true } : { ok: false, error: "NO_LIVE_AGENT" };
+    }
+    resolveNotebook(selector, clientSessionId) {
+        if (selector.notebookId !== undefined) {
+            const notebookId = selector.notebookId.trim();
+            if (!notebookId)
+                return { ok: false, error: "NOTEBOOK_NOT_FOUND" };
+            const record = this.notebooks.get(notebookId);
+            if (!record)
+                return { ok: false, error: "NOTEBOOK_NOT_FOUND" };
+            if (record.closed)
+                return { ok: false, error: "NOTEBOOK_CLOSED" };
+            if (record.stale)
+                return { ok: false, error: "NOTEBOOK_STALE" };
+            return { ok: true, record };
+        }
+        if (selector.displayName !== undefined) {
+            const displayName = selector.displayName.trim();
+            if (!displayName)
+                return { ok: false, error: "NOTEBOOK_NOT_FOUND" };
+            const lookup = this.notebooks.findByDisplayName(displayName);
+            if (lookup.ok)
+                return { ok: true, record: lookup.record };
+            return { ok: false, error: lookup.error, candidates: lookup.candidates };
+        }
+        if (clientSessionId) {
+            const clientActiveNotebookId = this.activeNotebookByClientSession.get(clientSessionId);
+            if (clientActiveNotebookId) {
+                return this.resolveNotebook({ notebookId: clientActiveNotebookId });
+            }
+        }
+        if (this.activeNotebookId) {
+            return this.resolveNotebook({ notebookId: this.activeNotebookId });
+        }
+        return { ok: false, error: "NOTEBOOK_NOT_FOUND" };
+    }
+    closeNotebook(notebookId, closedAt) {
+        const notebook = this.notebooks.get(notebookId);
+        if (!notebook)
+            return;
+        this.notebooks.markClosed(notebookId, closedAt);
+        this.clearInactiveActiveNotebook();
+        if (!this.notebooks.hasLiveForAgent(notebook.agentSessionId)) {
+            this.agents.retire(notebook.agentSessionId, closedAt);
+        }
+    }
+    clearInactiveActiveNotebook() {
+        if (this.activeNotebookId) {
+            const active = this.notebooks.get(this.activeNotebookId);
+            if (!active || active.closed || active.stale) {
+                this.activeNotebookId = undefined;
+            }
+        }
+        for (const [clientSessionId, notebookId] of this.activeNotebookByClientSession) {
+            const record = this.notebooks.get(notebookId);
+            if (!record || record.closed || record.stale) {
+                this.activeNotebookByClientSession.delete(clientSessionId);
+            }
+        }
+    }
+}

package/dist/src/backend/notebookRegistry.js

@@ -0,0 +1,136 @@
+import { canonicalizeNotebookPath } from "./protocol.js";
+export class NotebookRegistry {
+    createNotebookId;
+    records = new Map();
+    constructor(createNotebookId) {
+        this.createNotebookId = createNotebookId;
+    }
+    upsertHeartbeat(input) {
+        const existingByFrontend = this.findByFrontend(input.agentSessionId, input.frontendObjectKey);
+        const normalizedPath = this.canonicalizeFirstPath(input.savedPath, input.notebookPath, input.platform);
+        const existingByPath = normalizedPath ? this.findByNormalizedPath(normalizedPath) : undefined;
+        const existing = existingByFrontend ?? existingByPath;
+        if (existingByFrontend && existingByPath && existingByFrontend.notebookId !== existingByPath.notebookId) {
+            this.markClosed(existingByPath.notebookId, input.seenAt);
+        }
+        const notebookId = existing?.notebookId ?? this.createNotebookId();
+        const record = {
+            ...input,
+            permissions: this.clonePermissions(input.permissions),
+            notebookId,
+            normalizedPath,
+            createdAt: existing?.createdAt ?? input.seenAt,
+            lastSeenAt: input.seenAt,
+            closed: false,
+            degradedAt: undefined,
+            degraded: false,
+            offlineAt: undefined,
+            stale: false,
+            status: "live",
+        };
+        this.records.set(notebookId, record);
+        return this.cloneRecord(record);
+    }
+    get(notebookId) {
+        const record = this.records.get(notebookId);
+        return record ? this.cloneRecord(record) : undefined;
+    }
+    listLive() {
+        return this.listAll().filter((record) => !record.closed && !record.stale).map((record) => this.cloneRecord(record));
+    }
+    listAll() {
+        return [...this.records.values()].map((record) => this.cloneRecord(record));
+    }
+    hasLiveForAgent(agentSessionId) {
+        for (const record of this.records.values()) {
+            if (record.agentSessionId !== agentSessionId)
+                continue;
+            if (record.closed || record.stale)
+                continue;
+            return true;
+        }
+        return false;
+    }
+    findByDisplayName(displayName) {
+        const matches = this.listLive().filter((record) => record.displayName === displayName || record.windowTitle === displayName);
+        if (matches.length === 1) {
+            return { ok: true, record: this.cloneRecord(matches[0]) };
+        }
+        if (matches.length > 1) {
+            return { ok: false, error: "AMBIGUOUS_NOTEBOOK_NAME", candidates: matches };
+        }
+        return { ok: false, error: "NOTEBOOK_NOT_FOUND", candidates: [] };
+    }
+    markClosed(notebookId, closedAt) {
+        const record = this.records.get(notebookId);
+        if (!record)
+            return;
+        this.records.set(notebookId, {
+            ...record,
+            closed: true,
+            degraded: false,
+            degradedAt: undefined,
+            offlineAt: undefined,
+            stale: false,
+            status: "closed",
+            lastSeenAt: closedAt,
+        });
+    }
+    markDegradedByAgent(agentSessionId, degradedAt) {
+        for (const record of this.records.values()) {
+            if (record.agentSessionId !== agentSessionId || record.closed || record.stale || record.degraded)
+                continue;
+            this.records.set(record.notebookId, {
+                ...record,
+                degraded: true,
+                degradedAt,
+                offlineAt: undefined,
+                status: "degraded",
+            });
+        }
+    }
+    markStaleByAgent(agentSessionId, staleAt) {
+        for (const record of this.records.values()) {
+            if (record.agentSessionId !== agentSessionId || record.closed || record.stale)
+                continue;
+            this.records.set(record.notebookId, {
+                ...record,
+                degraded: false,
+                degradedAt: undefined,
+                offlineAt: staleAt,
+                stale: true,
+                status: "offline",
+            });
+        }
+    }
+    findByFrontend(agentSessionId, frontendObjectKey) {
+        for (const record of this.records.values()) {
+            if (record.closed)
+                continue;
+            if (record.agentSessionId === agentSessionId && record.frontendObjectKey === frontendObjectKey) {
+                return record;
+            }
+        }
+        return undefined;
+    }
+    findByNormalizedPath(normalizedPath) {
+        for (const record of this.records.values()) {
+            if (!record.closed && record.normalizedPath === normalizedPath) {
+                return record;
+            }
+        }
+        return undefined;
+    }
+    canonicalizeFirstPath(savedPath, notebookPath, platform) {
+        return canonicalizeNotebookPath(savedPath, platform) ?? canonicalizeNotebookPath(notebookPath, platform);
+    }
+    cloneRecord(record) {
+        return {
+            ...record,
+            permissions: this.clonePermissions(record.permissions),
+        };
+    }
+    clonePermissions(permissions) {
+        return { ...permissions };
+    }
+}

package/dist/src/backend/protocol.js

@@ -0,0 +1,32 @@
+import path from "node:path";
+export const DEFAULT_TIMEOUTS_MS = {
+    status: 5000,
+    listNotebooks: 5000,
+    listCells: 10_000,
+    readCell: 10_000,
+    mutation: 10_000,
+    insertCell: 60_000,
+    runCell: 120_000,
+    symbolLookup: 30_000,
+    agentHeartbeatDegradedMs: 10_000,
+    agentHeartbeatOfflineMs: 30_000,
+};
+function looksLikeWindowsPath(input) {
+    return /^[A-Za-z]:[\\/]/.test(input) || /^\\\\/.test(input);
+}
+function usesWindowsPathSemantics(platform, input) {
+    if (platform === "Windows")
+        return true;
+    if (platform !== undefined)
+        return false;
+    return process.platform === "win32" || looksLikeWindowsPath(input);
+}
+export function canonicalizeNotebookPath(input, platform) {
+    const trimmed = input?.trim();
+    if (!trimmed)
+        return undefined;
+    if (usesWindowsPathSemantics(platform, trimmed)) {
+        return path.win32.normalize(trimmed).toLowerCase();
+    }
+    return path.posix.normalize(trimmed);
+}