peaks-loop 4.1.2 → 4.1.4

package/dist/services/mcp/memory-tool.js

@@ -0,0 +1,62 @@
+// src/services/mcp/memory-tool.ts
+//
+// `peaks_memory_search`: one argv, a bounded reply (§7.1).
+//
+// It answers "is there anything, and what is it called" — never "what does it
+// say". The raw CLI output is measured in megabytes, so the reply is bounded
+// twice over: a hard ceiling on how many matches come back, and a truncated
+// excerpt per match. Both are on §3.2's allowed list for a composite tool
+// (field selection and truncation), and neither concludes anything: the count,
+// the names and the first characters are all the CLI's.
+import { buildArgv } from '../readonly-surface/argv-guard.js';
+import { MEMORY_EXCERPT_CHARS, MEMORY_MAX_RETURNED, rejectedResult, resultOf, runArgv, valuesForEntry } from './tool-core.js';
+/** Project one raw CLI match down to the fields §7.1 allows, with a bounded excerpt. */
+function boundMatch(raw) {
+    const match = typeof raw === 'object' && raw !== null ? raw : {};
+    const description = typeof match['description'] === 'string' ? match['description'] : '';
+    return {
+        name: match['name'],
+        kind: match['kind'],
+        excerpt: description.slice(0, MEMORY_EXCERPT_CHARS)
+    };
+}
+export async function callMemorySearchTool(tool, args, context) {
+    const entry = tool.entries[0];
+    if (entry === undefined) {
+        return { content: [{ type: 'text', text: '{"reason":"no entry"}' }], isError: true };
+    }
+    const values = valuesForEntry(entry, args, context);
+    if (values === undefined) {
+        return rejectedResult(entry, 'A search query is required.');
+    }
+    const built = buildArgv(entry, values);
+    if (!built.ok) {
+        return rejectedResult(entry, `Parameter ${built.param} was refused: ${built.message}`);
+    }
+    const outcome = await runArgv(entry.id, built.argv, context);
+    if (outcome.failure !== undefined)
+        return resultOf([outcome]);
+    const envelope = outcome.envelope;
+    const record = typeof envelope === 'object' && envelope !== null ? envelope : {};
+    const matches = record['matches'];
+    if (!Array.isArray(matches)) {
+        // No `matches` array is not "nothing matched" — it is a shape this tool does
+        // not understand, and reporting it as empty is the failure §9 rule 3 names.
+        const argv = outcome.execution.argv.join(' ');
+        return resultOf([
+            { ...outcome, failure: `peaks memory search returned no matches array: peaks ${argv}` }
+        ]);
+    }
+    return {
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify({
+                    query: record['query'],
+                    total: record['total'],
+                    matches: matches.slice(0, MEMORY_MAX_RETURNED).map(boundMatch)
+                })
+            }
+        ]
+    };
+}

package/dist/services/mcp/server-main.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/services/mcp/server-main.js

@@ -0,0 +1,66 @@
+// src/services/mcp/server-main.ts
+//
+// The process entry: a stdin pipe, a stdout pipe, and spec §6's L4 check before
+// either is used.
+//
+// STDOUT CARRIES PROTOCOL AND NOTHING ELSE. Any diagnostic goes to stderr,
+// because a harness reads stdout as the message stream and one stray line is a
+// parse error that is indistinguishable from a broken server. That is also why
+// the startup refusal below writes to stderr and exits non-zero rather than
+// printing a JSON error: at that point there is no session to answer in.
+//
+// L4 REFUSES TO START. If the surface cannot be served as proven — a tool with
+// no description, an argv the whitelist does not carry, a whitelisted argv
+// reachable from no tool, or a tool with no handler — this process exits 1.
+// A server that started anyway would be serving something nobody proved, and the
+// failure would surface as data rather than as a refusal (spec §6, L4).
+import { loadReadOnlyWhitelist } from '../readonly-surface/readonly-whitelist.js';
+import { LineDecoder } from './json-rpc.js';
+import { buildToolDefinitions, validateSurface } from './surface.js';
+import { createMcpServer } from './server.js';
+import { missingHandlers } from './tools.js';
+function refuse(reason) {
+    process.stderr.write(`peaks mcp: ${reason}\n`);
+    process.exit(1);
+}
+function start() {
+    let tools;
+    try {
+        const whitelist = loadReadOnlyWhitelist();
+        tools = buildToolDefinitions(whitelist);
+        validateSurface(whitelist, tools);
+    }
+    catch (error) {
+        refuse(`refusing to start: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const unserved = missingHandlers(tools);
+    if (unserved.length > 0) {
+        refuse(`refusing to start: no handler for tool(s) ${unserved.join(', ')}`);
+    }
+    const server = createMcpServer({ tools });
+    const decoder = new LineDecoder();
+    const write = (line) => {
+        if (line !== undefined)
+            process.stdout.write(line);
+    };
+    const consume = (line) => {
+        void server.handleLine(line).then(write);
+    };
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => {
+        for (const line of decoder.push(chunk))
+            consume(line);
+    });
+    process.stdin.on('end', () => {
+        for (const line of decoder.flush())
+            consume(line);
+    });
+    // A read error on our own transport is not recoverable and not ours to
+    // interpret: report it and stop, so the harness sees a dead server instead of
+    // a live one that answers nothing.
+    process.stdin.on('error', (error) => {
+        process.stderr.write(`peaks mcp: stdin error: ${error.message}\n`);
+        process.exitCode = 1;
+    });
+}
+start();

package/dist/services/mcp/server.d.ts

@@ -0,0 +1,22 @@
+import type { McpToolDefinition } from './surface.js';
+import { type ToolCallContext } from './tool-core.js';
+/** Used when the client names no protocol version. */
+export declare const DEFAULT_PROTOCOL_VERSION = "2025-06-18";
+/** The server's own name, as it appears in `initialize`. */
+export declare const SERVER_NAME = "peaks";
+export declare const METHOD_INITIALIZE = "initialize";
+export declare const METHOD_INITIALIZED = "notifications/initialized";
+export declare const METHOD_TOOLS_LIST = "tools/list";
+export declare const METHOD_TOOLS_CALL = "tools/call";
+export interface McpServerOptions {
+    readonly tools: readonly McpToolDefinition[];
+    readonly context?: ToolCallContext;
+    readonly serverVersion?: string;
+}
+export interface McpServer {
+    /** Answer one line. A notification (or blank line) yields `undefined`. */
+    handleLine(line: string): Promise<string | undefined>;
+    /** The tools, for a caller that wants to assert what it built. */
+    readonly tools: readonly McpToolDefinition[];
+}
+export declare function createMcpServer(options: McpServerOptions): McpServer;

package/dist/services/mcp/server.js

@@ -0,0 +1,152 @@
+// src/services/mcp/server.ts
+//
+// The protocol core: one decoded line in, at most one encoded line out.
+//
+// WHAT THIS SERVER IS. A table lookup, an execution, and the CLI's own answer —
+// nothing else (spec §3, component 3: "there is no fourth responsibility").
+// It does not know what a gate is, does not cache, keeps no state between
+// messages, and never rewrites a CLI result. `handleLine` is a pure function of
+// (line, surface, context), which is also what makes it testable without a pipe.
+//
+// THE PROTOCOL SURFACE IS DELIBERATELY SMALL and is listed in full here so it can
+// be checked line by line rather than inferred:
+//
+//   initialize                -> protocolVersion, capabilities.tools, serverInfo
+//   notifications/initialized -> accepted, no reply (it is a notification)
+//   tools/list                -> tools[] {name, description, inputSchema}
+//   tools/call                -> params {name, arguments} -> content[] | isError
+//   (anything else, request)  -> -32601 METHOD_NOT_FOUND
+//   (anything else, notification) -> ignored; JSON-RPC forbids replying
+//   malformed JSON            -> -32700   wrong envelope -> -32600
+//   bad tools/call params     -> -32602   handler crash  -> -32603
+//
+// NOT IMPLEMENTED, on purpose: `ping`, `resources/*`, `prompts/*`, `logging/*`,
+// `completion/*`, `notifications/*` beyond `initialized`, progress tokens,
+// cancellation, and resource subscriptions. Any of them arrives as a
+// METHOD_NOT_FOUND rather than as silence.
+//
+// NO HANDSHAKE STATE. The server does not track whether `initialize` has been
+// seen; every method is answerable on any line. MCP asks clients to initialize
+// first, and this server simply does not depend on it — a state machine here
+// would be state kept for no decision.
+//
+// PROTOCOL VERSION. The client's requested version is echoed when it names one,
+// and a constant is used otherwise. Echoing is honest for this surface and not a
+// claim of unlimited support: the four methods above have had identical request
+// and response shapes across every published revision, so there is no version
+// whose meaning this server would get wrong.
+import { CLI_VERSION } from 'peaks-loop-shared/version';
+import { decodeMessage, encodeMessage, failureResponse, isPlainObject, makeError, successResponse, JSON_RPC_INTERNAL_ERROR, JSON_RPC_INVALID_PARAMS, JSON_RPC_METHOD_NOT_FOUND } from './json-rpc.js';
+import { handlerFor } from './tools.js';
+/** Used when the client names no protocol version. */
+export const DEFAULT_PROTOCOL_VERSION = '2025-06-18';
+/** The server's own name, as it appears in `initialize`. */
+export const SERVER_NAME = 'peaks';
+export const METHOD_INITIALIZE = 'initialize';
+export const METHOD_INITIALIZED = 'notifications/initialized';
+export const METHOD_TOOLS_LIST = 'tools/list';
+export const METHOD_TOOLS_CALL = 'tools/call';
+/** The tool shape that goes on the wire — behaviour without the whitelist entries. */
+function wireTool(tool) {
+    return {
+        name: tool.name,
+        description: tool.description,
+        inputSchema: tool.inputSchema
+    };
+}
+function requestedVersion(params) {
+    if (!isPlainObject(params))
+        return undefined;
+    const version = params['protocolVersion'];
+    return typeof version === 'string' && version.length > 0 ? version : undefined;
+}
+function callArguments(params) {
+    const args = params['arguments'];
+    if (args === undefined)
+        return {};
+    return isPlainObject(args) ? args : undefined;
+}
+/**
+ * Reject an argument the tool does not declare, BEFORE anything runs. The tool
+ * schemas set `additionalProperties: false`; enforcing it here is what makes
+ * that a promise rather than a hint, and it is the boundary at which an
+ * injection-shaped key ("--apply") stops being an argument.
+ */
+function unknownArgument(tool, args) {
+    const declared = new Set(Object.keys(tool.inputSchema.properties));
+    return Object.keys(args).find((name) => !declared.has(name));
+}
+function initializeResult(params, version) {
+    return {
+        protocolVersion: requestedVersion(params) ?? DEFAULT_PROTOCOL_VERSION,
+        capabilities: { tools: { listChanged: false } },
+        serverInfo: { name: SERVER_NAME, version }
+    };
+}
+function fail(id, message) {
+    return encodeMessage(failureResponse(id, makeError(JSON_RPC_INVALID_PARAMS, message)));
+}
+async function toolsCallResult(tools, context, id, params) {
+    if (!isPlainObject(params)) {
+        return fail(id, 'tools/call requires an object of parameters.');
+    }
+    const name = params['name'];
+    if (typeof name !== 'string' || name.length === 0) {
+        return fail(id, 'tools/call requires a tool "name".');
+    }
+    const tool = tools.find((candidate) => candidate.name === name);
+    const handler = tool === undefined ? undefined : handlerFor(tool.name);
+    if (tool === undefined || handler === undefined) {
+        return fail(id, `Unknown tool: ${name}`);
+    }
+    const args = callArguments(params);
+    if (args === undefined) {
+        return fail(id, 'tools/call "arguments" must be an object.');
+    }
+    const unexpected = unknownArgument(tool, args);
+    if (unexpected !== undefined) {
+        return fail(id, `Tool ${name} declares no argument "${unexpected}".`);
+    }
+    return encodeMessage(successResponse(id, await handler(tool, args, context)));
+}
+export function createMcpServer(options) {
+    const tools = options.tools;
+    const context = options.context ?? {};
+    const version = options.serverVersion ?? CLI_VERSION;
+    const respond = async (id, method, params) => {
+        switch (method) {
+            case METHOD_INITIALIZE:
+                return encodeMessage(successResponse(id, initializeResult(params, version)));
+            case METHOD_TOOLS_LIST:
+                return encodeMessage(successResponse(id, { tools: tools.map(wireTool) }));
+            case METHOD_TOOLS_CALL:
+                return toolsCallResult(tools, context, id, params);
+            default:
+                return encodeMessage(failureResponse(id, makeError(JSON_RPC_METHOD_NOT_FOUND, `Unknown method: ${method}`)));
+        }
+    };
+    const handleLine = async (line) => {
+        const decoded = decodeMessage(line);
+        if (decoded === undefined)
+            return undefined;
+        if (decoded.kind === 'invalid') {
+            return encodeMessage(failureResponse(decoded.id, decoded.error));
+        }
+        if (decoded.kind === 'notification') {
+            // Notifications are answered by not answering. `initialized` needs no
+            // branch of its own for that reason — but an unknown one is silently
+            // dropped, which is the protocol's rule, not this server's leniency.
+            return undefined;
+        }
+        try {
+            return await respond(decoded.request.id, decoded.request.method, decoded.request.params);
+        }
+        catch (error) {
+            // A handler crash is reported, never swallowed: the caller has to know the
+            // answer is missing rather than empty.
+            const message = error instanceof Error ? error.message : 'Internal error';
+            return encodeMessage(failureResponse(decoded.request.id, makeError(JSON_RPC_INTERNAL_ERROR, message)));
+        }
+    };
+    return { tools, handleLine };
+}

package/dist/services/mcp/surface.d.ts

@@ -0,0 +1,62 @@
+import { type ReadOnlyWhitelist, type ReadOnlyWhitelistEntry } from '../readonly-surface/readonly-whitelist.js';
+/** One JSON Schema property, as far as this surface needs one. */
+export interface JsonSchemaProperty {
+    readonly type: 'string' | 'integer';
+    readonly description?: string;
+    readonly pattern?: string;
+    readonly enum?: readonly string[];
+    readonly minimum?: number;
+    readonly maximum?: number;
+    readonly default?: number;
+}
+export interface JsonSchema {
+    readonly type: 'object';
+    readonly properties: Readonly<Record<string, JsonSchemaProperty>>;
+    readonly required: readonly string[];
+    /** The LLM must not send anything else; an unknown key is a refused call. */
+    readonly additionalProperties: false;
+}
+export interface McpToolDefinition {
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: JsonSchema;
+    /** The whitelist entries this tool runs, in whitelist order. Kept off the wire. */
+    readonly entries: readonly ReadOnlyWhitelistEntry[];
+}
+/** Group the whitelist's entries into tools, preserving first-appearance order. */
+export declare function buildToolDefinitions(whitelist: ReadOnlyWhitelist): readonly McpToolDefinition[];
+/** Load the whitelist artifact and build the surface from it. */
+export declare function loadToolDefinitions(): readonly McpToolDefinition[];
+/** Why a surface was refused. Named so the server can print it and exit non-zero. */
+export declare class McpSurfaceError extends Error {
+    constructor(message: string);
+}
+/** An entry's argv as a comparable template key: literals literal, placeholders `{name}`. */
+export declare function argvTemplateOf(entry: ReadOnlyWhitelistEntry): string;
+/**
+ * Refuse a whitelist artifact that is not internally coherent.
+ *
+ * WHO THIS IS FOR. The artifact is generated and CI re-generates it, so the
+ * shape below holds on a clean checkout. The failure it exists for is the one
+ * that leaves no other trace: the file is edited by hand, or an entry is
+ * half-written, and a server starts up happily serving a surface nothing proved.
+ * Every rule here is a property the generator establishes and a hand-edit
+ * breaks, so a violated rule means "this is not the generated artifact".
+ */
+export declare function validateWhitelist(whitelist: ReadOnlyWhitelist): void;
+/**
+ * L4 (spec §6): refuse to start when the tool surface and the proven whitelist do
+ * not describe the same thing.
+ *
+ * Two properties, each meant to fail loudly rather than degrade:
+ *
+ *   1. Every argv a tool can run is a whitelisted argv, by template. The surface
+ *      is derived from the same artifact today, so on the production path this
+ *      reads as "nothing unproven got in" — but it is the boundary that has to
+ *      hold the moment a tool is authored rather than derived, and the test
+ *      proves it can fail by handing it a surface that names an unproven argv.
+ *   2. Every whitelisted entry is reachable from some tool. This one DOES have a
+ *      live trigger: an entry added to `readonly-surface.json` whose tool name is
+ *      mistyped is proven read-only and then never served.
+ */
+export declare function validateSurface(whitelist: ReadOnlyWhitelist, tools: readonly McpToolDefinition[]): void;

package/dist/services/mcp/surface.js

@@ -0,0 +1,198 @@
+// src/services/mcp/surface.ts
+//
+// The tool surface, DERIVED from the generated read-only whitelist rather than
+// restated beside it.
+//
+// WHY DERIVED. "Every argv a tool can run is whitelisted" is only checkable if
+// there is no second list to disagree with. So the tools ARE the whitelist's
+// entries grouped by their `tool` field: adding a tool means editing
+// `contracts/readonly-surface.json` and regenerating, and a tool whose argv was
+// never proven read-only cannot be declared here at all.
+//
+// `validateSurface` is spec §6's L4 — the startup check. L1 ("the server only
+// runs whitelisted argv") is a property of the code; L4 turns "someone put a
+// write argv into the surface" from a silent hole into a refusal to start. Its
+// unit is the ARGV, not the tool: a composite tool carries several, and checking
+// per tool would wave through all but one of them.
+//
+// JSON SCHEMA, NOT COMMANDER. The parameter constraints below come from the
+// whitelist's `params`, which the generator introspected out of the live
+// Commander registry when it wrote the artifact (`constraintSource` marks the
+// few that were hand-written). One build of latency is the price of not loading
+// the whole CLI command registry into a read-only server process; the artifact
+// is regenerated in the build and CI fails on a diff, so it cannot drift.
+import { loadReadOnlyWhitelist } from '../readonly-surface/readonly-whitelist.js';
+/**
+ * LLM-facing prose, per tool name. Every tool the whitelist declares must have
+ * an entry here or `validateSurface` refuses to start — spec §8.4 rule 2 asks
+ * the description to state the precondition, and a tool that silently has none
+ * is how an LLM ends up calling it outside a peaks project.
+ */
+const TOOL_DESCRIPTIONS = {
+    peaks_status: 'Where a Peaks-Loop workflow currently is. Read-only. Composes `peaks skill presence --json`, ' +
+        '`peaks session list --json` and, when both `rid` and `role` are given, `peaks request show ' +
+        '<rid> --role <role> --json --project <project>`. Each CLI result is returned verbatim under ' +
+        'its own key; a key is absent when that call was not run. Requires a Peaks-Loop project ' +
+        '(a `.peaks/` directory) as the working directory.',
+    peaks_memory_search: 'Search this project’s durable memory for a term, and get back NAMES and short excerpts — ' +
+        'never note bodies. Read-only. Use it to answer "has this project settled anything about X?" ' +
+        'Requires a Peaks-Loop project (a `.peaks/` directory) as the working directory.'
+};
+/** Per-parameter prose, by placeholder name. Absent names simply carry no description. */
+const PARAM_DESCRIPTIONS = {
+    rid: 'The id of the request to read.',
+    role: 'Role whose artifact to read. One of the declared enum values.',
+    project: 'Absolute path of the Peaks-Loop project. Defaults to the server’s working directory.',
+    query: 'The term to search project memory for.',
+    limit: 'Maximum number of matching notes to return.'
+};
+const TYPE_SHAPES = {
+    slug: (spec) => spec.pattern === undefined ? { type: 'string' } : { type: 'string', pattern: spec.pattern },
+    enum: (spec) => ({ type: 'string', enum: spec.values ?? [] }),
+    integer: (spec) => ({
+        type: 'integer',
+        minimum: spec.min ?? 0,
+        maximum: spec.max ?? Number.MAX_SAFE_INTEGER,
+        ...(spec.default === undefined ? {} : { default: spec.default })
+    }),
+    token: () => ({ type: 'string' }),
+    path: () => ({ type: 'string' })
+};
+function propertyFor(name, spec) {
+    const description = PARAM_DESCRIPTIONS[name];
+    const described = description === undefined ? {} : { description };
+    return { ...TYPE_SHAPES[spec.type](spec), ...described };
+}
+function inputSchemaOf(entries) {
+    const properties = {};
+    for (const entry of entries) {
+        for (const [name, spec] of Object.entries(entry.params)) {
+            properties[name] = propertyFor(name, spec);
+        }
+    }
+    // Nothing is `required` at the tool level. A tool whose entries all take no
+    // parameter is callable with `{}`, and a tool with several entries (three
+    // argv behind `peaks_status`) runs the subset whose parameters the caller
+    // actually supplied. Requiring the union would make the two parameterless
+    // argv unreachable.
+    return { type: 'object', properties, required: [], additionalProperties: false };
+}
+/** Group the whitelist's entries into tools, preserving first-appearance order. */
+export function buildToolDefinitions(whitelist) {
+    const byTool = new Map();
+    for (const entry of whitelist.entries) {
+        const bucket = byTool.get(entry.tool);
+        if (bucket === undefined) {
+            byTool.set(entry.tool, [entry]);
+        }
+        else {
+            bucket.push(entry);
+        }
+    }
+    return [...byTool].map(([name, entries]) => ({
+        name,
+        description: TOOL_DESCRIPTIONS[name] ?? '',
+        inputSchema: inputSchemaOf(entries),
+        entries
+    }));
+}
+/** Load the whitelist artifact and build the surface from it. */
+export function loadToolDefinitions() {
+    return buildToolDefinitions(loadReadOnlyWhitelist());
+}
+/** Why a surface was refused. Named so the server can print it and exit non-zero. */
+export class McpSurfaceError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'McpSurfaceError';
+    }
+}
+/** An entry's argv as a comparable template key: literals literal, placeholders `{name}`. */
+export function argvTemplateOf(entry) {
+    return entry.argv
+        .map((segment) => (segment.kind === 'literal' ? segment.value : `{${segment.name}}`))
+        .join(' ');
+}
+/**
+ * Refuse a whitelist artifact that is not internally coherent.
+ *
+ * WHO THIS IS FOR. The artifact is generated and CI re-generates it, so the
+ * shape below holds on a clean checkout. The failure it exists for is the one
+ * that leaves no other trace: the file is edited by hand, or an entry is
+ * half-written, and a server starts up happily serving a surface nothing proved.
+ * Every rule here is a property the generator establishes and a hand-edit
+ * breaks, so a violated rule means "this is not the generated artifact".
+ */
+export function validateWhitelist(whitelist) {
+    const seenIds = new Set();
+    for (const entry of whitelist.entries) {
+        if (seenIds.has(entry.id)) {
+            throw new McpSurfaceError(`Whitelist entry id '${entry.id}' is declared twice; refusing to start.`);
+        }
+        seenIds.add(entry.id);
+        const literals = entry.argv
+            .filter((segment) => segment.kind === 'literal')
+            .map((segment) => (segment.kind === 'literal' ? segment.value : ''));
+        // The command path must open the argv: an entry whose template does not
+        // begin with the command it claims to be is an entry about something else.
+        const prefix = literals.slice(0, entry.commandPath.length).join(' ');
+        if (prefix !== entry.commandPath.join(' ')) {
+            throw new McpSurfaceError(`Whitelist entry '${entry.id}' declares commandPath '${entry.commandPath.join(' ')}' but its argv starts '${prefix}'; refusing to start.`);
+        }
+        const used = entry.argv.flatMap((segment) => (segment.kind === 'param' ? [segment.name] : []));
+        for (const name of used) {
+            if (!(name in entry.params)) {
+                throw new McpSurfaceError(`Whitelist entry '${entry.id}' uses placeholder '${name}' that it does not declare; refusing to start.`);
+            }
+            if (used.filter((candidate) => candidate === name).length !== 1) {
+                throw new McpSurfaceError(`Whitelist entry '${entry.id}' uses placeholder '${name}' more than once; refusing to start.`);
+            }
+        }
+        for (const name of Object.keys(entry.params)) {
+            if (!used.includes(name)) {
+                throw new McpSurfaceError(`Whitelist entry '${entry.id}' declares parameter '${name}' that its argv never uses; refusing to start.`);
+            }
+        }
+    }
+}
+/**
+ * L4 (spec §6): refuse to start when the tool surface and the proven whitelist do
+ * not describe the same thing.
+ *
+ * Two properties, each meant to fail loudly rather than degrade:
+ *
+ *   1. Every argv a tool can run is a whitelisted argv, by template. The surface
+ *      is derived from the same artifact today, so on the production path this
+ *      reads as "nothing unproven got in" — but it is the boundary that has to
+ *      hold the moment a tool is authored rather than derived, and the test
+ *      proves it can fail by handing it a surface that names an unproven argv.
+ *   2. Every whitelisted entry is reachable from some tool. This one DOES have a
+ *      live trigger: an entry added to `readonly-surface.json` whose tool name is
+ *      mistyped is proven read-only and then never served.
+ */
+export function validateSurface(whitelist, tools) {
+    validateWhitelist(whitelist);
+    if (tools.length === 0) {
+        throw new McpSurfaceError('MCP surface declares no tools; refusing to start.');
+    }
+    const whitelistedTemplates = new Set(whitelist.entries.map((entry) => argvTemplateOf(entry)));
+    const servedTemplates = new Set();
+    for (const tool of tools) {
+        if (tool.description.trim().length === 0) {
+            throw new McpSurfaceError(`MCP tool '${tool.name}' has no description; refusing to start (spec §8.4 rule 2).`);
+        }
+        for (const entry of tool.entries) {
+            const template = argvTemplateOf(entry);
+            if (!whitelistedTemplates.has(template)) {
+                throw new McpSurfaceError(`MCP tool '${tool.name}' carries argv '${template}' that is not in the read-only whitelist; refusing to start.`);
+            }
+            servedTemplates.add(template);
+        }
+    }
+    for (const entry of whitelist.entries) {
+        const template = argvTemplateOf(entry);
+        if (!servedTemplates.has(template)) {
+            throw new McpSurfaceError(`Whitelist entry '${entry.id}' ('${template}') is reachable from no MCP tool; refusing to start.`);
+        }
+    }
+}

package/dist/services/mcp/tool-core.d.ts

@@ -0,0 +1,42 @@
+import type { ReadOnlyWhitelistEntry } from '../readonly-surface/readonly-whitelist.js';
+import { type CliExecution } from './cli-executor.js';
+/** How much of one memory note's description travels back. */
+export declare const MEMORY_EXCERPT_CHARS = 120;
+/** Hard ceiling on matches returned, independent of what the CLI was asked for. */
+export declare const MEMORY_MAX_RETURNED = 50;
+export interface ToolTextContent {
+    readonly type: 'text';
+    readonly text: string;
+}
+export interface ToolCallResult {
+    readonly content: readonly ToolTextContent[];
+    /** Present and `true` only when something failed. Absent means success. */
+    readonly isError?: boolean;
+}
+/** Injectable execution, so a test can drive a handler without a CLI. */
+export type CliExecutor = (argv: readonly string[]) => Promise<CliExecution>;
+export interface ToolCallContext {
+    readonly execute?: CliExecutor;
+    /** Directory the CLI runs in. Defaults to the server process's own. */
+    readonly cwd?: string;
+}
+/**
+ * The values to render one entry with, or `undefined` when the caller did not
+ * supply enough for this entry to run. A value the caller DID supply is always
+ * present — it is handed to the guard, which is what decides whether it is
+ * allowed, so nothing supplied can be silently skipped.
+ */
+export declare function valuesForEntry(entry: ReadOnlyWhitelistEntry, args: Readonly<Record<string, unknown>>, context: ToolCallContext): Record<string, string> | undefined;
+/** One argv's outcome, kept whole so the caller can see every envelope. */
+export interface EntryOutcome {
+    readonly key: string;
+    readonly execution: CliExecution;
+    readonly envelope: unknown;
+    readonly failure?: string;
+}
+/** Render the outcomes as a tool result, failing the call when any argv failed. */
+export declare function resultOf(outcomes: readonly EntryOutcome[]): ToolCallResult;
+/** A refused call: the parameter guard said no, before anything was executed. */
+export declare function rejectedResult(entry: ReadOnlyWhitelistEntry, reason: string): ToolCallResult;
+/** Execute one already-validated argv and keep its whole outcome. */
+export declare function runArgv(key: string, argv: readonly string[], context: ToolCallContext): Promise<EntryOutcome>;