@aliceshimada/mica 1.0.0

package/dist/src/cli/index.js

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { startBunRuntime } from "../bun/index.js";
+import { runDoctor } from "./doctor.js";
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function resolveProjectRoot() {
+    let dir = path.dirname(fileURLToPath(import.meta.url));
+    while (!existsSync(path.join(dir, "package.json"))) {
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            throw new Error("Cannot find project root (no package.json found)");
+        dir = parent;
+    }
+    return dir;
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+export function helpText() {
+    return `Usage: mica <command> [options]
+
+Commands:
+  start                   Start the MICA bridge runtime (default)
+  install [options]       Install MICA bridge into Wolfram
+  uninstall [options]     Uninstall MICA bridge from Wolfram
+  doctor                  Diagnose MICA bridge configuration
+  status                  Show MICA bridge status
+  config codex            Configure for Codex
+  config claude-desktop   Configure for Claude Desktop
+  config cursor           Configure for Cursor
+
+Options:
+  --help, -h              Show this help message
+  --dry-run               Preview changes without applying (install/uninstall)
+`;
+}
+export async function runCli(argv, deps) {
+    const stdout = deps?.stdout ?? process.stdout;
+    const stderr = deps?.stderr ?? process.stderr;
+    const startRuntime = deps?.startRuntime;
+    const runInstaller = deps?.runInstaller;
+    const _runDoctor = deps?.runDoctor;
+    const command = argv[0];
+    // --help / -h
+    if (command === "--help" || command === "-h") {
+        stdout.write(helpText());
+        return 0;
+    }
+    // install
+    if (command === "install") {
+        if (!runInstaller) {
+            stderr.write("Error: runInstaller not available\n");
+            return 1;
+        }
+        const output = runInstaller(argv.slice(1));
+        stdout.write(output);
+        return 0;
+    }
+    // uninstall
+    if (command === "uninstall") {
+        if (!runInstaller) {
+            stderr.write("Error: runInstaller not available\n");
+            return 1;
+        }
+        const output = runInstaller(["--uninstall", ...argv.slice(1)]);
+        stdout.write(output);
+        return 0;
+    }
+    // start or no args
+    if (command === "start" || command === undefined) {
+        if (!startRuntime) {
+            stderr.write("Error: startRuntime not available\n");
+            return 1;
+        }
+        const runtime = await startRuntime();
+        await runtime.keepAlive;
+        return 0;
+    }
+    // doctor
+    if (command === "doctor") {
+        if (!_runDoctor) {
+            stderr.write("Error: runDoctor not available\n");
+            return 1;
+        }
+        const { exitCode, output } = await _runDoctor();
+        stdout.write(output);
+        return exitCode;
+    }
+    // Future commands (listed in help but not yet implemented)
+    if (command === "status" || command === "config") {
+        stderr.write(`Command '${command}' is not yet implemented. Use --help for available commands.\n`);
+        return 1;
+    }
+    // Unknown command
+    stderr.write(`Unknown command: ${command}\n`);
+    return 1;
+}
+// ---------------------------------------------------------------------------
+// Direct invocation (node dist/src/cli/index.js)
+// ---------------------------------------------------------------------------
+async function main() {
+    const projectRoot = resolveProjectRoot();
+    const installerUrl = pathToFileURL(path.join(projectRoot, "scripts", "install.js")).href;
+    const { runInstaller, detectWolframUserBase } = (await import(installerUrl));
+    const exitCode = await runCli(process.argv.slice(2), {
+        startRuntime: async () => startBunRuntime(),
+        runInstaller,
+        runDoctor: async () => runDoctor({
+            projectRoot,
+            detectWolframUserBase: () => detectWolframUserBase(),
+        }),
+    });
+    process.exitCode = exitCode;
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+    main().catch((error) => {
+        const message = error instanceof Error ? error.stack ?? error.message : String(error);
+        process.stderr.write(`${message}\n`);
+        process.exitCode = 1;
+    });
+}

package/dist/src/index.js

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+// Legacy Palette compatibility path. Product entrypoint is src/bun/index.ts.
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { HttpBridge } from "./bridge/httpBridge.js";
+import { RequestQueue } from "./bridge/requestQueue.js";
+import { createMicaMcpServer, registerMicaPrompts } from "./mcp/prompts.js";
+import { registerMmaTools } from "./mcp/tools.js";
+import { runtimeModeFromArgs } from "./runtimeOptions.js";
+async function main() {
+    const queue = new RequestQueue();
+    const bridge = new HttpBridge(queue);
+    const mode = runtimeModeFromArgs(process.argv.slice(2));
+    await bridge.start();
+    const server = createMicaMcpServer("mica");
+    registerMmaTools(server, queue, () => bridge.statusSnapshot());
+    registerMicaPrompts(server);
+    let shuttingDown = false;
+    async function shutdown(exitCode) {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        console.error("MICA shutting down...");
+        await bridge.stop();
+        if (exitCode !== undefined) {
+            process.exit(exitCode);
+        }
+    }
+    process.on("SIGINT", () => {
+        shutdown(130).catch((error) => {
+            console.error(error);
+            process.exit(1);
+        });
+    });
+    process.on("SIGTERM", () => {
+        shutdown(143).catch((error) => {
+            console.error(error);
+            process.exit(1);
+        });
+    });
+    // Log only to stderr — stdout is reserved for MCP stdio JSON-RPC.
+    console.error(`MICA HTTP listening on http://127.0.0.1:${bridge.port}`);
+    if (mode === "bridge-only") {
+        console.error("MICA running in bridge-only development mode.");
+        return;
+    }
+    await server.connect(new StdioServerTransport());
+    // server.connect() completes stdio transport setup; the HTTP bridge keeps
+    // the process alive while the MCP client owns the MCP server. Signal handlers above
+    // perform cleanup on explicit process termination.
+}
+main().catch((error) => {
+    console.error(error);
+    process.exit(1);
+});

package/dist/src/mcp/backendTools.js

@@ -0,0 +1,216 @@
+import { randomUUID } from "node:crypto";
+import { DEFAULT_TIMEOUTS_MS } from "../backend/protocol.js";
+import { abortEvaluationSchema, deleteCellSchema, getCellOutputSchema, insertCellSchema, listCellsSchema, modifyCellSchema, noArgsSchema, readArtifactSchema, readCellSchema, runCellSchema, selectNotebookSchema, saveNotebookSchema, symbolLookupSchema, } from "./toolSchemas.js";
+import { INSERT_ANCHOR_GUIDANCE, notebookToolDescription } from "./descriptions.js";
+import { toolSuccess, withToolErrors } from "./toolResults.js";
+function assertLiveAgent(state) {
+    if (!state.requireLiveAgent().ok) {
+        throw new Error("NO_LIVE_AGENT");
+    }
+}
+function sweepStateLiveness(state) {
+    state.sweepLiveness(Date.now());
+}
+function liveActiveNotebookId(state, clientSessionId) {
+    const resolution = state.resolveNotebook({}, clientSessionId);
+    return resolution.ok ? resolution.record.notebookId : null;
+}
+function liveAgents(state) {
+    return state.agents.list().filter((agent) => !agent.offline && !agent.retired);
+}
+function resolveNotebookTarget(state, args, clientSessionId) {
+    const resolution = state.resolveNotebook(args, clientSessionId);
+    if (!resolution.ok) {
+        throw new Error(resolution.error);
+    }
+    return resolution.record;
+}
+export function resolveToolTarget(state, args, extra) {
+    sweepStateLiveness(state);
+    assertLiveAgent(state);
+    const notebook = resolveNotebookTarget(state, {
+        notebookId: typeof args.notebookId === "string" ? args.notebookId : undefined,
+        displayName: typeof args.displayName === "string" ? args.displayName : undefined,
+    }, extra?.sessionId);
+    const notebookAgent = state.agents.get(notebook.agentSessionId);
+    if (!notebookAgent || notebookAgent.offline) {
+        throw new Error("NO_LIVE_AGENT");
+    }
+    return { agentSessionId: notebook.agentSessionId, notebook };
+}
+function queueNotebookOperation(state, target, tool, args, timeoutMs, extra) {
+    const requestId = randomUUID();
+    const createdAt = Date.now();
+    state.queue.enqueue({
+        requestId,
+        tool,
+        arguments: args,
+        targetNotebookId: target.notebook.notebookId,
+        agentSessionId: target.agentSessionId,
+        timeoutMs,
+        createdAt,
+    });
+    const abortHandler = () => {
+        state.queue.cancel(requestId, "MCP client cancelled operation", Date.now());
+    };
+    if (extra?.signal?.aborted) {
+        abortHandler();
+    }
+    else if (extra?.signal) {
+        extra.signal.addEventListener("abort", abortHandler, { once: true });
+    }
+    const timeoutHandle = setTimeout(() => {
+        state.queue.markTimedOut(Date.now());
+    }, timeoutMs);
+    return state.queue
+        .waitForResult(requestId)
+        .then((result) => toolSuccess(result))
+        .finally(() => {
+        clearTimeout(timeoutHandle);
+        extra?.signal?.removeEventListener("abort", abortHandler);
+    });
+}
+function ensurePermission(notebook, tool, permission) {
+    if (!notebook.permissions[permission]) {
+        throw new Error(`PERMISSION_DENIED: ${tool}`);
+    }
+}
+function registerQueuedNotebookTool(server, state, config) {
+    server.tool(config.name, notebookToolDescription(config.summary, config.extraGuidance), config.schema, async (args, extra) => {
+        const recordArgs = args;
+        return withToolErrors({ tool: config.name, args: recordArgs }, async () => {
+            if (process.env.MICA_STRICT_TARGETING === "1" && config.requiresExplicitTarget) {
+                const hasNotebookId = typeof recordArgs.notebookId === "string" && recordArgs.notebookId.trim().length > 0;
+                const hasDisplayName = typeof recordArgs.displayName === "string" && recordArgs.displayName.trim().length > 0;
+                if (!hasNotebookId && !hasDisplayName) {
+                    throw new Error("EXPLICIT_NOTEBOOK_REQUIRED");
+                }
+            }
+            const target = resolveToolTarget(state, recordArgs, extra);
+            ensurePermission(target.notebook, config.name, config.permission);
+            return queueNotebookOperation(state, target, config.name, recordArgs, config.timeoutMs(recordArgs), extra);
+        });
+    });
+}
+export function registerBackendMcpTools(server, state) {
+    server.tool("mma_status", notebookToolDescription("Report backend status and notebook registry state."), noArgsSchema.shape, async (_args, extra) => {
+        return withToolErrors({ tool: "mma_status" }, () => {
+            sweepStateLiveness(state);
+            return toolSuccess({
+                server: "running",
+                activeNotebookId: liveActiveNotebookId(state, extra?.sessionId),
+                notebooks: state.notebooks.listLive(),
+                agents: liveAgents(state),
+            });
+        });
+    });
+    server.tool("mma_list_notebooks", notebookToolDescription("List notebooks registered with the Mathematica bridge Palette."), noArgsSchema.shape, async (_args, extra) => {
+        return withToolErrors({ tool: "mma_list_notebooks" }, () => {
+            sweepStateLiveness(state);
+            return toolSuccess({ notebooks: state.notebooks.listLive(), activeNotebookId: liveActiveNotebookId(state, extra?.sessionId) });
+        });
+    });
+    server.tool("mma_select_notebook", notebookToolDescription("Select the active Mathematica notebook in the backend registry."), selectNotebookSchema.shape, async (args, extra) => {
+        const recordArgs = args;
+        return withToolErrors({ tool: "mma_select_notebook", args: recordArgs }, () => {
+            const clientSessionId = extra?.sessionId;
+            const target = resolveToolTarget(state, recordArgs, extra);
+            state.setActiveNotebook(target.notebook.notebookId);
+            if (clientSessionId)
+                state.setActiveNotebook(target.notebook.notebookId, clientSessionId);
+            return toolSuccess({ activeNotebookId: state.activeNotebookId, notebook: target.notebook });
+        });
+    });
+    const queuedNotebookTools = [
+        {
+            name: "mma_symbol_lookup",
+            summary: "Look up Wolfram Language symbol documentation. Provide an exact symbol name (e.g. 'Plot') for full details including usage, options, attributes, and documentation URL, or a partial name (e.g. 'integrate') for a list of matching symbols.",
+            schema: symbolLookupSchema.shape,
+            permission: "ReadNotebook",
+            timeoutMs: () => DEFAULT_TIMEOUTS_MS.symbolLookup,
+        },
+        {
+            name: "mma_list_cells",
+            summary: "List cells in the attached active Mathematica notebook.",
+            schema: listCellsSchema.shape,
+            permission: "ReadNotebook",
+            timeoutMs: () => DEFAULT_TIMEOUTS_MS.listCells,
+        },
+        {
+            name: "mma_read_cell",
+            summary: "Read one cell from the attached Mathematica notebook.",
+            schema: readCellSchema.shape,
+            permission: "ReadNotebook",
+            timeoutMs: () => DEFAULT_TIMEOUTS_MS.readCell,
+        },
+        {
+            name: "mma_insert_cell",
+            summary: "Insert a cell through the Mathematica FrontEnd bridge.",
+            schema: insertCellSchema.shape,
+            permission: "InsertCell",
+            timeoutMs: () => DEFAULT_TIMEOUTS_MS.insertCell,
+            extraGuidance: INSERT_ANCHOR_GUIDANCE,
+            requiresExplicitTarget: true,
+        },
+        {
+            name: "mma_modify_cell",
+            summary: "Modify one existing cell through the Mathematica FrontEnd bridge.",
+            schema: modifyCellSchema.shape,
+            permission: "ModifyCell",
+            timeoutMs: () => DEFAULT_TIMEOUTS_MS.mutation,
+            requiresExplicitTarget: true,
+        },
+        {
+            name: "mma_delete_cell",
+            summary: "Delete one cell through the Mathematica FrontEnd bridge.",
+            schema: deleteCellSchema.shape,
+            permission: "DeleteCell",
+            timeoutMs: () => DEFAULT_TIMEOUTS_MS.mutation,
+            requiresExplicitTarget: true,
+        },
+        {
+            name: "mma_run_cell",
+            summary: "Run one cell in the attached Mathematica notebook.",
+            schema: runCellSchema.shape,
+            permission: "RunCell",
+            timeoutMs: (args) => {
+                const timeoutSec = typeof args.timeoutSec === "number" ? args.timeoutSec : 120;
+                return timeoutSec * 1000;
+            },
+            requiresExplicitTarget: true,
+        },
+        {
+            name: "mma_abort_evaluation",
+            summary: "Abort the running Wolfram evaluation in the attached notebook.",
+            schema: abortEvaluationSchema.shape,
+            permission: "RunCell",
+            timeoutMs: () => DEFAULT_TIMEOUTS_MS.mutation,
+            requiresExplicitTarget: true,
+        },
+        {
+            name: "mma_get_cell_output",
+            summary: "Read output and messages for one Mathematica notebook cell, refreshing completed run status when observed.",
+            schema: getCellOutputSchema.shape,
+            permission: "ReadNotebook",
+            timeoutMs: () => DEFAULT_TIMEOUTS_MS.readCell,
+        },
+        {
+            name: "mma_read_artifact",
+            summary: "Read one large output or message artifact by byte page. Artifact ids are resolved against current notebook state and may become stale after notebook edits or reruns.",
+            schema: readArtifactSchema.shape,
+            permission: "ReadNotebook",
+            timeoutMs: () => DEFAULT_TIMEOUTS_MS.readCell,
+        },
+        {
+            name: "mma_save_notebook",
+            summary: "Save the attached Mathematica notebook through the FrontEnd.",
+            schema: saveNotebookSchema.shape,
+            permission: "SaveNotebook",
+            timeoutMs: () => DEFAULT_TIMEOUTS_MS.mutation,
+            requiresExplicitTarget: true,
+        },
+    ];
+    for (const config of queuedNotebookTools) {
+        registerQueuedNotebookTool(server, state, config);
+    }
+}

package/dist/src/mcp/descriptions.js

@@ -0,0 +1,6 @@
+const NOTEBOOK_WORKFLOW_GUIDANCE = "Start by calling mma_status or mma_list_notebooks. Use the latest notebookId because notebookIds change across sessions/restarts. Restart your MCP client or the MICA MCP server after changing this MCP server code or tool descriptions.";
+const LIVE_NOTEBOOK_DEBUG_GUIDANCE = "Debug live notebooks only through MCP notebook cells: insert cells, run cells, and read output/messages. Do not use detached wolframscript for live-notebook debugging or mutation.";
+export const INSERT_ANCHOR_GUIDANCE = 'For append or unknown anchors, use afterCellId="__end__"; empty notebooks are supported.';
+export function notebookToolDescription(summary, extraGuidance) {
+    return [summary, NOTEBOOK_WORKFLOW_GUIDANCE, extraGuidance, LIVE_NOTEBOOK_DEBUG_GUIDANCE].filter(Boolean).join(" ");
+}

package/dist/src/mcp/prompts.js

@@ -0,0 +1,52 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export const MICA_TOOL_GUIDE_PROMPT_NAME = "mica_notebook_workflow";
+const TOOL_GUIDE = [
+    ["mma_status", "Report server, agent, and notebook registry state."],
+    ["mma_list_notebooks", "List live notebooks and the active notebook id."],
+    ["mma_select_notebook", "Select the active notebook by notebookId or displayName."],
+    ["mma_symbol_lookup", "Look up Wolfram Language symbol usage, options, attributes, and documentation URLs."],
+    ["mma_list_cells", "List cells in the selected notebook."],
+    ["mma_read_cell", "Read one cell's content and metadata."],
+    ["mma_insert_cell", "Insert a notebook cell; use afterCellId=\"__end__\" to append."],
+    ["mma_modify_cell", "Modify an existing cell."],
+    ["mma_delete_cell", "Delete an existing cell."],
+    ["mma_run_cell", "Evaluate one cell and wait for completion or timeout."],
+    ["mma_abort_evaluation", "Abort a running notebook evaluation."],
+    ["mma_get_cell_output", "Read output and messages produced by one cell; this may refresh completed run status."],
+    ["mma_read_artifact", "Read large output or message artifacts by byte page; ids may become stale after notebook edits or reruns."],
+    ["mma_save_notebook", "Save the selected notebook when SaveNotebook permission is granted."],
+];
+export const MICA_AGENT_INSTRUCTIONS = [
+    "MICA controls already-open Mathematica / Wolfram Desktop notebooks through MCP.",
+    "",
+    "Workflow rules:",
+    "1. Start with mma_status or mma_list_notebooks. Use the latest notebookId because notebookIds change across Mathematica restarts.",
+    "2. Work only with notebooks returned by mma_list_notebooks unless the user explicitly asks for a different external action. Do not create hidden or offscreen notebooks.",
+    "3. Prefer notebookId for targeting. Use displayName only when the notebook name is unambiguous.",
+    "4. For all mutating operations, pass notebookId explicitly.",
+    "5. For live notebook debugging, use MCP notebook cells: insert cells, run cells, read cells, and inspect outputs/messages. Do not use detached wolframscript for live notebook mutation or debugging.",
+    "6. Cell ids are session-local. Refresh with mma_list_cells after large edits, deletes, or notebook restarts.",
+    "7. For appending cells, pass afterCellId=\"__end__\". Empty notebooks are supported.",
+    "8. All tool results are structured. Success returns ok: true. Expected failures return ok: false with error.code, error.message, error.retryable, error.tool, and sometimes error.notebookId.",
+    "9. Respect notebook permissions. SaveNotebook is commonly disabled; handle PERMISSION_DENIED instead of retrying blindly.",
+    "",
+    "Tools:",
+    ...TOOL_GUIDE.map(([name, description]) => `- ${name}: ${description}`),
+].join("\n");
+export function createMicaMcpServer(name, version = "0.1.0") {
+    return new McpServer({ name, version }, { instructions: MICA_AGENT_INSTRUCTIONS });
+}
+export function registerMicaPrompts(server) {
+    server.prompt(MICA_TOOL_GUIDE_PROMPT_NAME, "How an agent should use MICA's Mathematica notebook MCP tools.", () => ({
+        description: "MICA Mathematica notebook workflow and tool guide.",
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: MICA_AGENT_INSTRUCTIONS,
+                },
+            },
+        ],
+    }));
+}

package/dist/src/mcp/toolResults.js

@@ -0,0 +1,183 @@
+const ERROR_DEFINITIONS = {
+    AMBIGUOUS_NOTEBOOK_NAME: {
+        code: "AMBIGUOUS_NOTEBOOK_NAME",
+        message: "More than one live notebook matches that display name.",
+        retryable: false,
+    },
+    EXPLICIT_NOTEBOOK_REQUIRED: {
+        code: "EXPLICIT_NOTEBOOK_REQUIRED",
+        message: "Strict targeting is enabled. Provide notebookId or displayName explicitly for mutating operations.",
+        retryable: false,
+    },
+    NOTEBOOK_CLOSED: {
+        code: "NOTEBOOK_CLOSED",
+        message: "The selected Mathematica notebook has been closed.",
+        retryable: true,
+    },
+    NOTEBOOK_NOT_ATTACHED: {
+        code: "NOTEBOOK_NOT_ATTACHED",
+        message: "No Mathematica notebook is attached to the bridge.",
+        retryable: true,
+    },
+    NOTEBOOK_NOT_FOUND: {
+        code: "NOTEBOOK_NOT_FOUND",
+        message: "No live Mathematica notebook matches the requested selector.",
+        retryable: true,
+    },
+    NOTEBOOK_NOT_SELECTED: {
+        code: "NOTEBOOK_NOT_SELECTED",
+        message: "No Mathematica notebook is selected.",
+        retryable: true,
+    },
+    NOTEBOOK_STALE: {
+        code: "NOTEBOOK_STALE",
+        message: "The selected Mathematica notebook has stopped sending heartbeats.",
+        retryable: true,
+    },
+    NO_LIVE_AGENT: {
+        code: "NO_LIVE_AGENT",
+        message: "No live Mathematica control agent is registered.",
+        retryable: true,
+    },
+    PALETTE_NOT_CONNECTED: {
+        code: "PALETTE_NOT_CONNECTED",
+        message: "The Mathematica bridge palette is not connected.",
+        retryable: true,
+    },
+    PERMISSION_DENIED: {
+        code: "PERMISSION_DENIED",
+        message: "The selected notebook did not grant permission for this tool.",
+        retryable: false,
+    },
+    REQUEST_CANCELLED: {
+        code: "REQUEST_CANCELLED",
+        message: "The MCP client cancelled the operation.",
+        retryable: false,
+    },
+    REQUEST_TIMED_OUT: {
+        code: "REQUEST_TIMED_OUT",
+        message: "The Mathematica control agent did not answer before the tool timeout.",
+        retryable: true,
+    },
+    UNSUPPORTED_SELECTOR: {
+        code: "UNSUPPORTED_SELECTOR",
+        message: "That notebook selector is not supported by this MCP transport.",
+        retryable: false,
+    },
+    WOLFRAM_AGENT_ERROR: {
+        code: "WOLFRAM_AGENT_ERROR",
+        message: "The Mathematica control agent reported an error.",
+        retryable: true,
+    },
+};
+export function toolSuccess(value) {
+    const { ok: _ignoredOk, ...payload } = objectPayload(value);
+    return textResult({ ok: true, ...payload });
+}
+export function toolFailure(error, context = {}) {
+    return { ...textResult({ ok: false, error: normalizeToolError(error, context) }), isError: true };
+}
+export async function withToolErrors(context, handler) {
+    try {
+        return await handler();
+    }
+    catch (error) {
+        return toolFailure(error, context);
+    }
+}
+function textResult(structuredContent) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(structuredContent, null, 2) }],
+        structuredContent,
+    };
+}
+function objectPayload(value) {
+    if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+        return value;
+    }
+    return { result: value };
+}
+function normalizeToolError(error, context) {
+    const raw = readErrorFields(error);
+    const definition = classifyError(raw.code ?? raw.message);
+    const notebookId = context.notebookId ?? notebookIdFromArgs(context.args);
+    const tool = raw.tool ?? context.tool;
+    return {
+        code: definition.code,
+        message: raw.message && !isBareCode(raw.message) ? raw.message : definition.message,
+        retryable: raw.retryable ?? definition.retryable,
+        ...(tool ? { tool } : {}),
+        ...(notebookId ? { notebookId } : {}),
+        ...(raw.details ? { details: raw.details } : {}),
+    };
+}
+function readErrorFields(error) {
+    if (error instanceof Error) {
+        return parseMessage(error.message);
+    }
+    if (typeof error === "string") {
+        return parseMessage(error);
+    }
+    if (error !== null && typeof error === "object") {
+        const record = error;
+        const nested = record.error !== null && typeof record.error === "object" ? record.error : record;
+        const code = readString(nested.code);
+        const message = readString(nested.message);
+        const retryable = typeof nested.retryable === "boolean" ? nested.retryable : undefined;
+        const tool = readString(nested.tool);
+        const details = nested.details !== null && typeof nested.details === "object" && !Array.isArray(nested.details)
+            ? nested.details
+            : undefined;
+        return { code, message, retryable, tool, details };
+    }
+    return { message: String(error) };
+}
+function parseMessage(message) {
+    const trimmed = message.trim();
+    if (!trimmed)
+        return {};
+    const permissionMatch = trimmed.match(/^PERMISSION_DENIED:\s*(.+)$/);
+    if (permissionMatch) {
+        return { code: "PERMISSION_DENIED", message: ERROR_DEFINITIONS.PERMISSION_DENIED.message, tool: permissionMatch[1].trim() };
+    }
+    if (trimmed === "MCP client cancelled operation") {
+        return { code: "REQUEST_CANCELLED", message: trimmed };
+    }
+    if (trimmed.startsWith("Mathematica Palette is not connected")) {
+        return { code: "PALETTE_NOT_CONNECTED", message: trimmed };
+    }
+    if (trimmed.startsWith("No Mathematica notebook is attached")) {
+        return { code: "NOTEBOOK_NOT_ATTACHED", message: trimmed };
+    }
+    if (trimmed.startsWith("No Mathematica notebook is selected")) {
+        return { code: "NOTEBOOK_NOT_SELECTED", message: trimmed };
+    }
+    if (trimmed.startsWith("Unknown notebookId:")) {
+        return { code: "NOTEBOOK_NOT_FOUND", message: trimmed };
+    }
+    if (trimmed.startsWith("Display-name notebook selection is not supported")) {
+        return { code: "UNSUPPORTED_SELECTOR", message: trimmed };
+    }
+    const codeMatch = trimmed.match(/^([A-Z][A-Z0-9_]+)(?::\s*(.+))?$/);
+    if (codeMatch) {
+        return { code: codeMatch[1], message: codeMatch[2] ?? codeMatch[1] };
+    }
+    return { message: trimmed };
+}
+function classifyError(input) {
+    if (input && ERROR_DEFINITIONS[input])
+        return ERROR_DEFINITIONS[input];
+    return { code: "INTERNAL_ERROR", message: "The MCP tool failed unexpectedly.", retryable: false };
+}
+function notebookIdFromArgs(args) {
+    return readString(args?.notebookId);
+}
+function readString(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed ? trimmed : undefined;
+}
+function isBareCode(message) {
+    return /^[A-Z][A-Z0-9_]+$/.test(message);
+}