logisheets-mcp 0.1.0

package/dist/server.js

@@ -0,0 +1,205 @@
+/**
+ * The MCP shell: logician tools in, MCP protocol out.
+ *
+ * We use the SDK's low-level `Server` rather than `McpServer` on purpose.
+ * `McpServer.registerTool` wants Zod schemas, while logician tools already
+ * carry hand-written JSON Schema — which is what MCP puts on the wire anyway.
+ * Going low-level passes those straight through instead of round-tripping them
+ * through a Zod translation layer.
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { CallToolRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { WorkbookSession } from './session.js';
+import { selectTools, toolModeFromEnv } from './surface.js';
+import { validateToolInput } from './validate.js';
+import { TOOLS_YIELDING_WORKBOOK, WORKBOOK_URI, XLSX_MIME, } from './lifecycle.js';
+export const SERVER_NAME = 'logisheets';
+export const SERVER_VERSION = '0.1.0';
+/**
+ * How the agent should approach this server. Sent as MCP `instructions`, so a
+ * host can put it in front of the model before it starts guessing.
+ */
+export const INSTRUCTIONS = [
+    'A real, Excel-compatible spreadsheet engine you can compute in and remember in.',
+    '',
+    'Two things it is for:',
+    '  1. Arithmetic you should not do yourself. Write a formula and let the engine evaluate it — `eval_formula` for a one-off, or store the formula in a cell so it keeps recalculating.',
+    '  2. Structured memory that survives the whole task. A *block* is a named table; you address its cells by (block name, row key, field name), never by A1 coordinates. Inserting rows never breaks a reference, so you can keep building without tracking where anything sits.',
+    '',
+    'The loop: `list_blocks` to see what you have, `create_block` to open a structured workspace, `add_block_rows` / `set_block_cells` to fill it, formulas for the math, `describe_block` to read results back, `save_workbook` to hand the human a real .xlsx.',
+    '',
+    'Prefer blocks over raw cells. `get_cells` / `set_cells` exist for data that genuinely has no structure.',
+].join('\n');
+/** Translate a logician tool into its MCP wire description. */
+function toMcpTool(t) {
+    // logician declares `required` readonly; the wire type wants it mutable.
+    const { required, ...schema } = t.inputSchema;
+    return {
+        // logician namespaces tools (`build__create_block`) to keep crafts from
+        // colliding. MCP hosts already prefix by server, so the namespace would
+        // just be noise in the model's context; names are asserted unique below.
+        name: t.name,
+        description: t.description,
+        // Spread first: a tool's own `type` must not shadow 'object', which is
+        // what MCP requires at the top level of a tool's input schema.
+        inputSchema: {
+            ...schema,
+            type: 'object',
+            ...(required !== undefined ? { required: [...required] } : {}),
+        },
+        annotations: {
+            readOnlyHint: !t.mutates,
+            // logician's 'destructive' policy marks the tools that discard data
+            // (clear a block, delete rows/sheets) rather than merely write.
+            destructiveHint: t.confirmation === 'destructive',
+        },
+    };
+}
+/**
+ * Build the server. Nothing is started — hand the result to a transport.
+ */
+export function createServer(opts = {}) {
+    const session = opts.session ?? new WorkbookSession();
+    const mode = opts.mode ?? toolModeFromEnv();
+    const log = opts.log ?? ((msg) => process.stderr.write(`${msg}\n`));
+    const tools = new Map();
+    for (const t of selectTools(session, mode)) {
+        if (tools.has(t.name)) {
+            throw new Error(`two tools share the MCP name "${t.name}" — namespaces differ but names must be unique`);
+        }
+        tools.set(t.name, t);
+    }
+    const server = new Server({ name: SERVER_NAME, version: SERVER_VERSION }, {
+        capabilities: { tools: {}, resources: {} },
+        instructions: INSTRUCTIONS,
+    });
+    // The workbook as a resource. This is how the finished file reaches the
+    // human: `save_workbook` returns a link, and a host that wants the bytes
+    // reads them here — outside the model's context, so a 200 KB workbook costs
+    // the conversation nothing.
+    server.setRequestHandler(ListResourcesRequestSchema, async () => {
+        if (!session.isOpen)
+            return { resources: [] };
+        return {
+            resources: [
+                {
+                    uri: WORKBOOK_URI,
+                    name: session.path ?? 'workbook.xlsx',
+                    title: 'The active workbook',
+                    description: 'The workbook this session is working in, serialized as a real .xlsx.',
+                    mimeType: XLSX_MIME,
+                    // Marked for the human: it is a file to open, not text to
+                    // reason over.
+                    annotations: { audience: ['user'] },
+                },
+            ],
+        };
+    });
+    server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+        if (request.params.uri !== WORKBOOK_URI) {
+            throw new Error(`unknown resource: ${request.params.uri}`);
+        }
+        // Serialize through the same lane as the tools, so a read can't observe
+        // a half-applied transaction.
+        const { base64, bytes } = await session.run(async () => session.exportBase64());
+        return {
+            contents: [
+                {
+                    uri: WORKBOOK_URI,
+                    mimeType: XLSX_MIME,
+                    blob: base64,
+                    _meta: { bytes },
+                },
+            ],
+        };
+    });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: [...tools.values()].map(toMcpTool),
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
+        const tool = tools.get(request.params.name);
+        if (tool === undefined) {
+            return {
+                content: [
+                    { type: 'text', text: `unknown tool: ${request.params.name}` },
+                ],
+                isError: true,
+            };
+        }
+        // Check arguments against the tool's declared schema first. Nothing
+        // else does — the SDK passes `arguments` through untouched — so a
+        // wrong parameter name would otherwise surface as whatever
+        // TypeError the handler happens to throw, naming neither the tool
+        // nor the parameter the agent got wrong.
+        const invalid = validateToolInput(tool, request.params.arguments);
+        if (invalid !== undefined) {
+            return {
+                content: [{ type: 'text', text: invalid }],
+                isError: true,
+            };
+        }
+        const ctx = {
+            workbook: session.client,
+            signal: extra.signal,
+            // The MCP host owns approval: it decided to dispatch this call,
+            // and a server-side prompt has nobody to ask. Mutating tools
+            // are flagged via annotations so the host can gate them there.
+            confirm: async () => true,
+            log,
+        };
+        try {
+            // One workbook, one lane. Handlers read state and then write it
+            // across an await, and the host may have several calls in
+            // flight, so without this they interleave and lose. See
+            // WorkbookSession.run.
+            const result = await session.run(() => tool.handler(request.params.arguments ?? {}, ctx));
+            if (result.canceled === true) {
+                return {
+                    content: [{ type: 'text', text: 'canceled' }],
+                    isError: true,
+                };
+            }
+            const content = [];
+            if (result.display !== undefined && result.display !== '') {
+                content.push({ type: 'text', text: result.display });
+            }
+            if (result.data !== undefined) {
+                content.push({
+                    type: 'text',
+                    text: JSON.stringify(result.data),
+                });
+            }
+            if (content.length === 0) {
+                content.push({ type: 'text', text: 'ok' });
+            }
+            // Hand back a reference to the file, not the file. The host can
+            // turn this into a download for the human; the model just sees a
+            // short link.
+            if (TOOLS_YIELDING_WORKBOOK.has(tool.name)) {
+                content.push({
+                    type: 'resource_link',
+                    uri: WORKBOOK_URI,
+                    name: session.path ?? 'workbook.xlsx',
+                    mimeType: XLSX_MIME,
+                    description: 'The saved workbook. Read this resource to get the .xlsx bytes.',
+                    annotations: { audience: ['user'] },
+                });
+            }
+            return { content };
+        }
+        catch (err) {
+            // Tool failures are results, not protocol errors: the agent
+            // should see the message and get a chance to correct itself.
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: err instanceof Error ? err.message : String(err),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    return { server, session, tools };
+}

package/dist/session.d.ts

@@ -0,0 +1,99 @@
+/**
+ * The session's workbook — the thing that makes this server *memory* rather
+ * than a calculator.
+ *
+ * One MCP session owns one active workbook, held here and persistent across
+ * tool calls. Every tool operates on it, so state the agent built in step 3 is
+ * still there in step 30. (Multiple named workbooks per session is a later
+ * feature; a single active one keeps the tool surface small and the agent's
+ * mental model simple.)
+ */
+import { Workbook } from 'logisheets-runtime';
+/** The async engine client, as logician's tool handlers consume it. */
+export type WorkbookClient = Workbook['client'];
+export interface OpenResult {
+    /** Where the workbook came from. */
+    source: 'new' | 'file' | 'bytes';
+    /** Absolute path, when opened from (or destined for) a file. */
+    path?: string;
+    /** Sheet names in order. */
+    sheets: string[];
+}
+export interface SaveResult {
+    path: string;
+    bytes: number;
+}
+export declare class WorkbookSession {
+    private readonly runtime;
+    private active;
+    /** Tail of the serialization chain — see {@link run}. */
+    private lane;
+    /** Where {@link saveTo} last wrote, so the workbook resource can be named
+     *  after the file the human is actually being handed. */
+    private lastSaved;
+    /**
+     * Run `fn` after everything already queued on this session, and before
+     * anything queued later. One workbook, one lane.
+     *
+     * Tool handlers are read-then-write against shared state: `create_block`
+     * asks whether its sheet exists and creates it if not; it asks the engine
+     * for a free block id and then claims it. Those are two awaits with a gap
+     * in between, and MCP does not promise to serialize requests — JSON-RPC
+     * allows pipelining and the SDK dispatches concurrently. Three
+     * `create_block` calls in flight at once therefore each saw the sheet
+     * missing, each tried to create it, and two failed.
+     *
+     * Serializing costs nothing here. The engine is a single synchronous WASM
+     * instance, so concurrent handlers never bought throughput — they only
+     * interleaved. Reads are queued too: a read overlapping a half-applied
+     * transaction would report state that never existed.
+     *
+     * Not reentrant. Wrap once, at the dispatch boundary; a handler that called
+     * back into `run` would wait on itself forever.
+     */
+    run<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * The active workbook, created empty on first touch.
+     *
+     * Lazy creation is deliberate: an agent that dives straight into
+     * `create_block` shouldn't fail because it skipped `open_workbook`. The
+     * scratchpad simply exists as soon as anything reaches for it.
+     */
+    get workbook(): Workbook;
+    get client(): WorkbookClient;
+    /**
+     * The file this workbook belongs to: where it was last saved, else where it
+     * was opened from. Undefined for a scratch workbook that has never been
+     * written.
+     */
+    get path(): string | undefined;
+    /** True once a workbook exists — i.e. anything has touched the session. */
+    get isOpen(): boolean;
+    /**
+     * Replace the active workbook.
+     *
+     * `path` loads a real `.xlsx` from disk; `xlsxBase64` loads one from bytes
+     * (for hosts with no shared filesystem); neither starts an empty workbook.
+     */
+    open(opts: {
+        path?: string;
+        xlsxBase64?: string;
+        name?: string;
+    }): Promise<OpenResult>;
+    /** Sheet names of the active workbook, in order. */
+    sheetNames(): Promise<string[]>;
+    /**
+     * Write the workbook to `path`, defaulting to where it was opened from.
+     * Returns the absolute path actually written and the file size.
+     */
+    saveTo(path?: string, opts?: {
+        resolveBlockRefs?: boolean;
+    }): Promise<SaveResult>;
+    /** Serialize the workbook to base64 `.xlsx` for transports with no shared disk. */
+    exportBase64(resolveBlockRefs?: boolean): {
+        base64: string;
+        bytes: number;
+    };
+    /** Release every engine resource this session holds. */
+    close(): void;
+}

package/dist/session.js

@@ -0,0 +1,164 @@
+/**
+ * The session's workbook — the thing that makes this server *memory* rather
+ * than a calculator.
+ *
+ * One MCP session owns one active workbook, held here and persistent across
+ * tool calls. Every tool operates on it, so state the agent built in step 3 is
+ * still there in step 30. (Multiple named workbooks per session is a later
+ * feature; a single active one keeps the tool surface small and the agent's
+ * mental model simple.)
+ */
+import { resolve } from 'node:path';
+import { stat } from 'node:fs/promises';
+import { SpreadsheetRuntime } from 'logisheets-runtime';
+export class WorkbookSession {
+    runtime = new SpreadsheetRuntime();
+    active;
+    /** Tail of the serialization chain — see {@link run}. */
+    lane = Promise.resolve();
+    /** Where {@link saveTo} last wrote, so the workbook resource can be named
+     *  after the file the human is actually being handed. */
+    lastSaved;
+    /**
+     * Run `fn` after everything already queued on this session, and before
+     * anything queued later. One workbook, one lane.
+     *
+     * Tool handlers are read-then-write against shared state: `create_block`
+     * asks whether its sheet exists and creates it if not; it asks the engine
+     * for a free block id and then claims it. Those are two awaits with a gap
+     * in between, and MCP does not promise to serialize requests — JSON-RPC
+     * allows pipelining and the SDK dispatches concurrently. Three
+     * `create_block` calls in flight at once therefore each saw the sheet
+     * missing, each tried to create it, and two failed.
+     *
+     * Serializing costs nothing here. The engine is a single synchronous WASM
+     * instance, so concurrent handlers never bought throughput — they only
+     * interleaved. Reads are queued too: a read overlapping a half-applied
+     * transaction would report state that never existed.
+     *
+     * Not reentrant. Wrap once, at the dispatch boundary; a handler that called
+     * back into `run` would wait on itself forever.
+     */
+    run(fn) {
+        // Run `fn` whether or not its predecessor settled cleanly, then keep the
+        // lane resolved so one failed tool call can't poison the queue.
+        const result = this.lane.then(fn, fn);
+        this.lane = result.then(() => undefined, () => undefined);
+        return result;
+    }
+    /**
+     * The active workbook, created empty on first touch.
+     *
+     * Lazy creation is deliberate: an agent that dives straight into
+     * `create_block` shouldn't fail because it skipped `open_workbook`. The
+     * scratchpad simply exists as soon as anything reaches for it.
+     */
+    get workbook() {
+        if (this.active === undefined) {
+            this.active = this.runtime.createWorkbook();
+        }
+        return this.active;
+    }
+    get client() {
+        return this.workbook.client;
+    }
+    /**
+     * The file this workbook belongs to: where it was last saved, else where it
+     * was opened from. Undefined for a scratch workbook that has never been
+     * written.
+     */
+    get path() {
+        return this.lastSaved ?? this.workbook.path;
+    }
+    /** True once a workbook exists — i.e. anything has touched the session. */
+    get isOpen() {
+        return this.active !== undefined;
+    }
+    /**
+     * Replace the active workbook.
+     *
+     * `path` loads a real `.xlsx` from disk; `xlsxBase64` loads one from bytes
+     * (for hosts with no shared filesystem); neither starts an empty workbook.
+     */
+    async open(opts) {
+        if (opts.path !== undefined && opts.xlsxBase64 !== undefined) {
+            throw new Error('pass either path or xlsx_base64, not both');
+        }
+        let next;
+        let source;
+        if (opts.path !== undefined) {
+            next = await this.runtime.loadWorkbook(opts.path);
+            source = 'file';
+        }
+        else if (opts.xlsxBase64 !== undefined) {
+            const bytes = Buffer.from(opts.xlsxBase64, 'base64');
+            if (bytes.length === 0) {
+                throw new Error('xlsx_base64 decoded to zero bytes');
+            }
+            next = this.runtime.loadWorkbookFromBytes(bytes, opts.name ?? 'workbook.xlsx');
+            source = 'bytes';
+        }
+        else {
+            next = this.runtime.createWorkbook();
+            source = 'new';
+        }
+        // Release the workbook being displaced. The runtime dedups loads by
+        // path, so re-opening the current file hands back the same handle —
+        // closing it then would release the workbook we just "opened".
+        const previous = this.active;
+        this.active = next;
+        this.lastSaved = undefined;
+        if (previous !== undefined && previous !== next) {
+            this.runtime.close(previous);
+        }
+        return { source, path: next.path, sheets: await this.sheetNames() };
+    }
+    /** Sheet names of the active workbook, in order. */
+    async sheetNames() {
+        const infos = await this.workbook.client.getAllSheetInfo();
+        if (isErrorMessage(infos)) {
+            throw new Error(`getAllSheetInfo failed: ${infos.msg}`);
+        }
+        return infos.map((s) => s.name);
+    }
+    /**
+     * Write the workbook to `path`, defaulting to where it was opened from.
+     * Returns the absolute path actually written and the file size.
+     */
+    async saveTo(path, opts = {}) {
+        // `this.path`, not `workbook.path`: a second bare save should go back to
+        // wherever the last one went, even for a workbook that started empty.
+        const target = path ?? this.path;
+        if (target === undefined) {
+            throw new Error('no path given, and this workbook was not opened from a file — ' +
+                'pass an explicit path');
+        }
+        const absolute = resolve(target);
+        await this.workbook.saveAs(absolute, '', opts.resolveBlockRefs ?? false);
+        this.lastSaved = absolute;
+        // Size from disk rather than a second `save()` — serializing a whole
+        // workbook twice just to report a number is not worth it.
+        return { path: absolute, bytes: (await stat(absolute)).size };
+    }
+    /** Serialize the workbook to base64 `.xlsx` for transports with no shared disk. */
+    exportBase64(resolveBlockRefs = false) {
+        const data = this.workbook.save('', resolveBlockRefs);
+        return {
+            base64: Buffer.from(data).toString('base64'),
+            bytes: data.length,
+        };
+    }
+    /** Release every engine resource this session holds. */
+    close() {
+        this.runtime.closeAll();
+        this.active = undefined;
+        this.lastSaved = undefined;
+    }
+}
+/** Local copy of the engine's error-shape guard (avoids a direct engine dep). */
+function isErrorMessage(v) {
+    return (typeof v === 'object' &&
+        v !== null &&
+        'msg' in v &&
+        typeof v.msg === 'string');
+}

package/dist/surface.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Which tools this server exposes.
+ *
+ * logician ships ~55 tools, built for an in-app assistant with a UI. Handing an
+ * agent all of them is a real cost: tool-selection accuracy falls as the list
+ * grows, and every description is context the agent pays for on every turn. So
+ * the default is a deliberate core — the loop from the design doc and nothing
+ * else — with the rest available behind an env flag.
+ *
+ *   LOGISHEETS_MCP_TOOLS=core   (default) the 19 below
+ *   LOGISHEETS_MCP_TOOLS=full   everything except the browser-only tools
+ */
+import type { Tool } from 'logisheets-logician';
+import type { WorkbookSession } from './session.js';
+export type ToolMode = 'core' | 'full';
+/** Read the mode from the environment, defaulting to `core`. */
+export declare function toolModeFromEnv(env?: Record<string, string | undefined>): ToolMode;
+/**
+ * Resolve the tool list for a session.
+ *
+ * Core tools come first and in the declared order, so a host that renders the
+ * list in order shows the agent the loop rather than an alphabet soup.
+ */
+export declare function selectTools(session: WorkbookSession, mode: ToolMode): Tool[];

package/dist/surface.js

@@ -0,0 +1,147 @@
+/**
+ * Which tools this server exposes.
+ *
+ * logician ships ~55 tools, built for an in-app assistant with a UI. Handing an
+ * agent all of them is a real cost: tool-selection accuracy falls as the list
+ * grows, and every description is context the agent pays for on every turn. So
+ * the default is a deliberate core — the loop from the design doc and nothing
+ * else — with the rest available behind an env flag.
+ *
+ *   LOGISHEETS_MCP_TOOLS=core   (default) the 19 below
+ *   LOGISHEETS_MCP_TOOLS=full   everything except the browser-only tools
+ */
+import { BLOCK_OPS_TOOLS, BUILDER_TOOLS, CELL_TOOLS, COMMENT_TOOLS, EDIT_TOOLS, FORMAT_TOOLS, HISTORY_TOOLS, INSPECT_TOOLS, LINK_TOOLS, STRUCTURE_TOOLS, toolId, } from 'logisheets-logician';
+import { createLifecycleTools } from './lifecycle.js';
+/**
+ * The core surface, in the order an agent meets it: orient, build structured
+ * memory, compute, read back, hand over.
+ *
+ * Everything here is addressed semantically — `(block, row_key, field)` rather
+ * than `C7` — because positional addressing is exactly what agents get wrong.
+ * The raw-cell pair is the escape hatch, kept last on purpose.
+ */
+const CORE_IDS = [
+    // Lifecycle
+    'workbook__open_workbook',
+    'workbook__save_workbook',
+    'workbook__export_xlsx',
+    // Orient
+    'build__list_blocks',
+    'build__describe_block',
+    // Compute
+    'build__eval_formula',
+    // Structured memory
+    'build__create_block',
+    // The counterpart for a workbook someone hands you: `create_block` refuses
+    // to write over existing data, and this takes data that is already there and
+    // makes it addressable in place. Without it an agent given a legacy file has
+    // only the destructive half of the pair.
+    'build__convert_to_block',
+    'build__add_block_rows',
+    'build__delete_block_rows',
+    // Row order is presentation, not model — but the presentation is part of
+    // the deliverable. A person can drag rows around in the app; without this
+    // an agent handed the same file cannot, and cannot put a table into the
+    // order someone asked for.
+    'build__move_block_row',
+    'edit__set_block_cells',
+    'build__set_field_rule',
+    // Sheets
+    'build__create_sheet',
+    // Raw-cell escape hatch
+    'cell__get_cells',
+    'cell__set_cells',
+    // `set_field_rule` can attach a validation rule, and this is the only way
+    // to see what breaks it — without it, validation is write-only and the
+    // agent has no way to check its own work.
+    'inspect__list_violations',
+    // Answering "what would happen if…" without changing anything. Read-only:
+    // it runs the edits on the engine's temp branch, reports the whole cascade
+    // and discards them. Without it the only way to explore is to mutate and
+    // put back, which walks the model somewhere else if anything goes wrong
+    // mid-scan — and a sensitivity scan is dozens of probes.
+    'edit__preview_changes',
+    // Auditing a number and predicting the blast radius of an edit, from the
+    // engine's own dependency graph. The alternative is reading every formula
+    // in the workbook and parsing it — and that still cannot answer the reverse
+    // direction, which is the one you want before changing an assumption.
+    'inspect__trace',
+    // Reverse the model: what input lands the answer on a given number. Runs the
+    // whole search on the temp branch inside one call — as a conversation it is
+    // one round trip per bisection step, and it changes nothing either way.
+    'edit__goal_seek',
+];
+/**
+ * Tools that cannot work here, excluded from `full` as well as `core`.
+ *
+ * The craft-interaction tools register cell widgets in the browser app; they
+ * detect a headless host and return "not available", so exposing them would
+ * only spend context to advertise failures. `get_active_selection` reads what
+ * the user has selected on a canvas that doesn't exist in an MCP session.
+ */
+const NEVER_IDS = new Set([
+    'craft__register_radio_group',
+    'craft__register_multi_select_group',
+    'craft__register_point_allocator',
+    'craft__register_percent_allocator',
+    'craft__register_number_slider',
+    'craft__clear_interaction',
+    'craft__read_selection',
+    'inspect__get_active_selection',
+]);
+/** Every logician tool this server is willing to expose, core first. */
+function allEngineTools() {
+    return [
+        ...BUILDER_TOOLS,
+        ...EDIT_TOOLS,
+        ...CELL_TOOLS,
+        ...INSPECT_TOOLS,
+        ...STRUCTURE_TOOLS,
+        ...FORMAT_TOOLS,
+        ...HISTORY_TOOLS,
+        ...COMMENT_TOOLS,
+        ...BLOCK_OPS_TOOLS,
+        ...LINK_TOOLS,
+    ];
+}
+/** Read the mode from the environment, defaulting to `core`. */
+export function toolModeFromEnv(env = process.env) {
+    const raw = env.LOGISHEETS_MCP_TOOLS?.trim().toLowerCase();
+    if (raw === undefined || raw === '')
+        return 'core';
+    if (raw === 'core' || raw === 'full')
+        return raw;
+    throw new Error(`LOGISHEETS_MCP_TOOLS must be "core" or "full", got "${raw}"`);
+}
+/**
+ * Resolve the tool list for a session.
+ *
+ * Core tools come first and in the declared order, so a host that renders the
+ * list in order shows the agent the loop rather than an alphabet soup.
+ */
+export function selectTools(session, mode) {
+    const available = new Map();
+    for (const t of [...createLifecycleTools(session), ...allEngineTools()]) {
+        const id = toolId(t);
+        if (available.has(id)) {
+            throw new Error(`duplicate tool id from logician: ${id}`);
+        }
+        available.set(id, t);
+    }
+    const core = CORE_IDS.map((id) => {
+        const t = available.get(id);
+        if (t === undefined) {
+            // A rename upstream must fail loudly at startup rather than
+            // silently shrink the agent's surface.
+            throw new Error(`core tool "${id}" not found — logisheets-logician may have renamed it`);
+        }
+        return t;
+    });
+    if (mode === 'core')
+        return core;
+    const coreIds = new Set(CORE_IDS);
+    const rest = [...available.entries()]
+        .filter(([id]) => !coreIds.has(id) && !NEVER_IDS.has(id))
+        .map(([, t]) => t);
+    return [...core, ...rest];
+}

package/dist/validate.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Check tool arguments against the tool's own declared JSON Schema, before the
+ * handler ever sees them.
+ *
+ * MCP puts each tool's `inputSchema` on the wire, but nothing enforces it: the
+ * SDK hands `params.arguments` straight through. Handlers then read fields that
+ * aren't there, and the agent gets whatever TypeError falls out —
+ * `Cannot read properties of undefined (reading 'startsWith')` for a missing
+ * `expr`. That names neither the tool nor the parameter, so the agent has no
+ * way to correct itself and burns turns guessing.
+ *
+ * Agents mostly get arguments wrong in a few predictable ways: they omit a
+ * required parameter, invent a plausible synonym for its name (`formula` for
+ * `expr`), pass a string where a number belongs, or guess an enum variant. So
+ * the messages here name the parameter, say what was expected, and — the part
+ * that actually saves a turn — suggest the declared name a stray key looks like.
+ *
+ * Deliberately a subset of draft-07: the keywords logician's schemas actually
+ * use (type incl. unions, required, properties, items, enum, bounds). No $ref,
+ * no anyOf/allOf. An unrecognized keyword is ignored rather than guessed at.
+ */
+import type { Tool } from 'logisheets-logician';
+/**
+ * Validate a tool call's arguments. Returns an agent-facing message listing
+ * every problem, or undefined when the arguments are acceptable.
+ */
+export declare function validateToolInput(tool: Pick<Tool, 'name' | 'inputSchema'>, args: unknown): string | undefined;