peaks-loop 4.1.2 → 4.1.4

package/dist/services/ide/ide-mcp-install-types.js

@@ -0,0 +1,104 @@
+/**
+ * The REGISTRATION profile of one harness's MCP entry point (spec §8.3).
+ *
+ * WHY THIS IS NOT `IdeMcpProfile`. That profile (on `IdeAdapter.mcp`) answers
+ * "how does this harness SPELL a peaks tool name", which the pre-tool branch
+ * needs. This one answers "how does this harness register a server", which only
+ * the distribution path needs. One field would conflate two questions asked by
+ * two callers that never run together.
+ *
+ * WHY IT DECLARES ARGV AND NOT A COMMAND STRING. Registering is the HARNESS's
+ * own operation: `peaks mcp install` calls the harness's entry point rather than
+ * hand-editing the harness's config file, because that file is full of the
+ * user's state and hand-editing it is neither safe nor version-stable (§8.3).
+ * The entry is declared as an ARRAY with three placeholders, so the engine that
+ * consumes it substitutes values into an array and never builds a command line.
+ *
+ * WHY add AND remove ARE BOTH DECLARED. A harness's register verb is not
+ * idempotent — same name, same scope, and it fails, with no `--force` and no
+ * `update` — so the install is delete-then-add (§8.3). Both halves are therefore
+ * part of the contract, and `scopes` exists because the entry can already sit in
+ * more than one of them: the delete is a sweep, not a targeted call.
+ *
+ * WHAT IS DELIBERATELY ABSENT: any harness name, any platform name, and any
+ * branch on either. A vendor's own spellings belong in its adapter, which is the
+ * only module that fills this type in.
+ */
+/** Placeholder for the server key the harness files peaks under. */
+export const MCP_NAME_PLACEHOLDER = '<name>';
+/** Placeholder for one scope the entry can live in; substituted once per removal. */
+export const MCP_SCOPE_PLACEHOLDER = '<scope>';
+/** Placeholder for the launched server argv — the command and every token after it. */
+export const MCP_SERVER_ARGV_PLACEHOLDER = '<server-argv>';
+/** The placeholders an argv template may carry, and nothing else may look like one. */
+export const MCP_ARGV_PLACEHOLDERS = [
+    MCP_NAME_PLACEHOLDER,
+    MCP_SCOPE_PLACEHOLDER,
+    MCP_SERVER_ARGV_PLACEHOLDER
+];
+/**
+ * One template's structural requirements: it must carry something, its
+ * bracket-shaped tokens must be ones the engine knows how to substitute, and the
+ * placeholders the caller needs in it must be there. An unknown placeholder is a
+ * refusal rather than a literal, because passing it through would hand the
+ * harness an argument that means nothing to it.
+ */
+function assertArgvTemplate(label, argv, required, refuse) {
+    if (argv.length === 0)
+        refuse(`${label} is empty`);
+    for (const token of argv) {
+        const bracketShaped = token.startsWith('<') && token.endsWith('>');
+        const known = MCP_ARGV_PLACEHOLDERS.includes(token);
+        if (bracketShaped && !known)
+            refuse(`${label} carries unknown placeholder '${token}'`);
+    }
+    for (const placeholder of required) {
+        if (!argv.includes(placeholder))
+            refuse(`${label} does not carry ${placeholder}`);
+    }
+}
+/**
+ * A declaration that cannot drive an install is a defect in the adapter, and it
+ * is reported as one rather than silently producing an argv the harness will
+ * reject. That is the whole argument for throwing here: a profile missing its
+ * server-argv placeholder would install a registration that launches nothing,
+ * and nothing would say so.
+ */
+export function assertMcpInstallProfile(profile) {
+    const refuse = (reason) => {
+        throw new Error(`IdeMcpInstallProfile is not installable: ${reason}`);
+    };
+    if (profile.serverName.length === 0)
+        refuse('serverName is empty');
+    if (profile.scopes.length === 0)
+        refuse('scopes is empty');
+    if (!profile.scopes.includes(profile.targetScope)) {
+        refuse(`targetScope '${profile.targetScope}' is not one of the declared scopes`);
+    }
+    assertArgvTemplate('addArgv', profile.addArgv, [MCP_NAME_PLACEHOLDER, MCP_SCOPE_PLACEHOLDER, MCP_SERVER_ARGV_PLACEHOLDER], refuse);
+    assertArgvTemplate('removeArgv', profile.removeArgv, [MCP_NAME_PLACEHOLDER, MCP_SCOPE_PLACEHOLDER], refuse);
+}
+/**
+ * Expand one argv template. A placeholder that stands for SEVERAL tokens expands
+ * to all of them, which is why this returns an array and why the launched server
+ * argv is passed as one: the caller never joins and never splits.
+ */
+export function expandMcpArgv(argv, values) {
+    const expanded = [];
+    for (const token of argv) {
+        if (token === MCP_NAME_PLACEHOLDER) {
+            expanded.push(values.serverName);
+            continue;
+        }
+        if (token === MCP_SCOPE_PLACEHOLDER) {
+            expanded.push(values.scope);
+            continue;
+        }
+        if (token === MCP_SERVER_ARGV_PLACEHOLDER) {
+            expanded.push(...values.serverArgv);
+            continue;
+        }
+        expanded.push(token);
+    }
+    return expanded;
+}

package/dist/services/ide/ide-types.d.ts

@@ -13,12 +13,13 @@
  */
 import type { SubAgentDispatcher } from '../dispatch/sub-agent-dispatcher.js';
 import type { ContextPercentFallbackInput, IdeCompactProfile } from './ide-compact-types.js';
+import type { IdeMcpInstallProfile } from './ide-mcp-install-types.js';
 /**
  * Re-exported so every importer of `./ide-types.js` keeps seeing the whole
  * adapter type surface from the original path (b1 file-size campaign: the two
  * declarations now live in `./ide-compact-types.js`).
  */
-export type { ContextPercentFallbackInput, IdeCompactProfile };
+export type { ContextPercentFallbackInput, IdeCompactProfile, IdeMcpInstallProfile };
 export type IdeId = 'claude-code' | 'trae' | 'codex' | 'cursor' | 'qoder' | 'tongyi-lingma' | 'hermes' | 'openclaw' | 'zcode';
 export interface IdeCapabilities {
     /** peaks gate enforce 是否适用该 IDE(必备) */
@@ -171,6 +172,49 @@ export interface IdeAdapter {
      * funnelling all vendor signal through this method.
      */
     readonly resolveCallerId: (env?: NodeJS.ProcessEnv) => string;
+    /**
+     * How this harness SPELLS the MCP tool names of a peaks server.
+     *
+     * Optional, like `skillInstall?` / `standardsProfile?` / `compact?`: an adapter
+     * that leaves it undefined declares "this harness has no MCP tool surface I can
+     * name", and every consumer treats that as "nothing to match" rather than as an
+     * error.
+     *
+     * It exists because one tool has SEVERAL spellings. A server registered
+     * directly and the same server arriving through a plugin produce different
+     * tool names, and an enforcement matcher written against one of them does not
+     * fire on the other — silently. Declaring them here is what lets the
+     * pre-tool branch and the installed hook entry agree on the full set.
+     *
+     * `resolveCallerId` above is the precedent for the placement rule: a vendor's
+     * naming convention is vendor signal, and vendor signal is funnelled through
+     * the adapter so no other module has to know it.
+     */
+    readonly mcp?: IdeMcpProfile;
+    /**
+     * How this harness REGISTERS an MCP server (spec §8.3), consumed by
+     * `peaks mcp install/uninstall`. Optional, like `mcp` above: leaving it
+     * undefined declares "no registration entry peaks may call", and the install
+     * reads that as "nothing to do". See `ide-mcp-install-types.ts`.
+     */
+    readonly mcpInstall?: IdeMcpInstallProfile;
+}
+/**
+ * The MCP naming profile of one harness.
+ *
+ * Deliberately ONE field. Templates both MATCH a concrete tool name and
+ * CONSTRUCT one, which is what lets a conformance test build a call for a
+ * channel it has never seen (spec §6.3) instead of restating the harness's
+ * naming in the test — a restatement that would go stale the moment a channel
+ * is added.
+ */
+export interface IdeMcpProfile {
+    /**
+     * Tool-name templates. `*` is replaced by the bare MCP tool id, so
+     * `mcp__peaks__*` describes every tool of a server registered under the name
+     * `peaks` on the direct channel.
+     */
+    readonly toolNameTemplates: readonly string[];
 }
 /**
  * Per-IDE standards-file location + format profile. Used by the

package/dist/services/ide/mcp-tool-matcher.d.ts

@@ -0,0 +1,34 @@
+import type { IdeAdapter, IdeMcpProfile } from './ide-types.js';
+/** The placeholder an adapter's tool-name template uses for the bare tool id. */
+export declare const TOOL_ID_PLACEHOLDER = "*";
+/** A concrete tool name matched back to the adapter template that produced it. */
+export interface McpToolMatch {
+    /** The bare tool id — the part the template's placeholder stood for. */
+    readonly toolId: string;
+    /** The template that matched, so a caller can report which channel fired. */
+    readonly template: string;
+}
+/** The declared profile, or an empty one for an adapter that opts out. */
+export declare function mcpProfileOf(adapter: IdeAdapter): IdeMcpProfile | undefined;
+/** Every tool-name template the adapter declares, in declaration order. */
+export declare function mcpToolNameTemplates(adapter: IdeAdapter): readonly string[];
+/** The concrete harness tool name for a tool id under one template. */
+export declare function mcpToolName(template: string, toolId: string): string;
+/**
+ * The tool id a concrete name carries under one template, or `undefined`. The
+ * template is anchored: an unanchored match would let a longer name smuggle the
+ * id (and would make `matchMcpToolName` order-dependent).
+ */
+export declare function mcpToolIdFrom(template: string, toolName: string): string | undefined;
+/**
+ * Match a concrete harness tool name against every template the adapter
+ * declares, in declaration order. This is the ONE entry point the enforcement
+ * branch uses, so "which channels are covered" is answered by the adapter alone.
+ */
+export declare function matchMcpToolName(adapter: IdeAdapter, toolName: string): McpToolMatch | undefined;
+/**
+ * The PreToolUse `matcher` source covering every declared channel, ready to be
+ * joined into a hook entry's matcher field. `*` becomes `.*` and everything else
+ * is escaped, so the source matches exactly the names the templates describe.
+ */
+export declare function mcpHookMatcher(adapter: IdeAdapter): string | undefined;

package/dist/services/ide/mcp-tool-matcher.js

@@ -0,0 +1,84 @@
+// src/services/ide/mcp-tool-matcher.ts
+//
+// The vendor-translation layer for MCP tool NAMES (spec §6.3, §13).
+//
+// An MCP tool's name is harness-specific AND channel-specific: the very same
+// `peaks_status` tool is spelled one way when the server is registered directly
+// and another way when it arrives through a plugin. A matcher hard-coded against
+// one spelling keeps working on the channel it was written for and SILENTLY
+// stops firing on the other — the failure mode is an enforcement layer that
+// reports nothing because it never ran. So the spellings are declared by the
+// adapter (`IdeAdapter.mcp`) and this module is the only place that turns a
+// declaration into (a) a match against a concrete tool name and (b) the
+// PreToolUse matcher written into the harness's settings.
+//
+// Vendor names do not belong here: every string below is either generic syntax
+// or comes from the adapter. The isolation zone lives in `adapters/`.
+/** The placeholder an adapter's tool-name template uses for the bare tool id. */
+export const TOOL_ID_PLACEHOLDER = '*';
+/** The declared profile, or an empty one for an adapter that opts out. */
+export function mcpProfileOf(adapter) {
+    return adapter.mcp;
+}
+/** Every tool-name template the adapter declares, in declaration order. */
+export function mcpToolNameTemplates(adapter) {
+    return adapter.mcp?.toolNameTemplates ?? [];
+}
+/** Escape a literal segment so it cannot act as a pattern metacharacter. */
+function escapeLiteral(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * Split a template on its placeholder. A template must carry EXACTLY one
+ * placeholder: zero would make the tool id unaddressable, and two would make the
+ * captured id ambiguous. Both are adapter bugs, so they throw with the template
+ * in the message rather than degrading to a matcher that matches nothing.
+ */
+function splitTemplate(template) {
+    const parts = template.split(TOOL_ID_PLACEHOLDER);
+    if (parts.length !== 2 || parts[0] === undefined || parts[1] === undefined) {
+        throw new Error(`MCP tool-name template '${template}' must contain exactly one '${TOOL_ID_PLACEHOLDER}' placeholder.`);
+    }
+    return [parts[0], parts[1]];
+}
+/** The concrete harness tool name for a tool id under one template. */
+export function mcpToolName(template, toolId) {
+    const [prefix, suffix] = splitTemplate(template);
+    return `${prefix}${toolId}${suffix}`;
+}
+/**
+ * The tool id a concrete name carries under one template, or `undefined`. The
+ * template is anchored: an unanchored match would let a longer name smuggle the
+ * id (and would make `matchMcpToolName` order-dependent).
+ */
+export function mcpToolIdFrom(template, toolName) {
+    const [prefix, suffix] = splitTemplate(template);
+    const pattern = new RegExp(`^${escapeLiteral(prefix)}(.*)${escapeLiteral(suffix)}$`);
+    const matched = pattern.exec(toolName);
+    return matched?.[1];
+}
+/**
+ * Match a concrete harness tool name against every template the adapter
+ * declares, in declaration order. This is the ONE entry point the enforcement
+ * branch uses, so "which channels are covered" is answered by the adapter alone.
+ */
+export function matchMcpToolName(adapter, toolName) {
+    for (const template of mcpToolNameTemplates(adapter)) {
+        const toolId = mcpToolIdFrom(template, toolName);
+        if (toolId !== undefined)
+            return { toolId, template };
+    }
+    return undefined;
+}
+/**
+ * The PreToolUse `matcher` source covering every declared channel, ready to be
+ * joined into a hook entry's matcher field. `*` becomes `.*` and everything else
+ * is escaped, so the source matches exactly the names the templates describe.
+ */
+export function mcpHookMatcher(adapter) {
+    const sources = mcpToolNameTemplates(adapter).map((template) => {
+        const [prefix, suffix] = splitTemplate(template);
+        return `${escapeLiteral(prefix)}.*${escapeLiteral(suffix)}`;
+    });
+    return sources.length === 0 ? undefined : sources.join('|');
+}

package/dist/services/lint/npx-resolver.js

@@ -17,6 +17,13 @@ import process from 'node:process';
 function locateNpmCliScript(scriptFile) {
     const candidates = process.platform === 'win32'
         ? [
+            // Standard Windows layout — the installer, the zip, and
+            // nvm-for-windows all put `node_modules/npm` beside `node.exe`, so the
+            // install is ONE level up from `process.execPath`, not two. This is the
+            // `npm` belonging to the very `node` that will run the script, so it is
+            // tried first; the three entries after it are the backstop for an `npm`
+            // installed elsewhere.
+            join(process.execPath, '..', 'node_modules', 'npm', 'bin', scriptFile),
             join(process.execPath, '..', '..', 'node_modules', 'npm', 'bin', scriptFile),
             `C:/nvm4w/nodejs/node_modules/npm/bin/${scriptFile}`,
             `C:/Program Files/nodejs/node_modules/npm/bin/${scriptFile}`

package/dist/services/mcp/cli-executor.d.ts

@@ -0,0 +1,36 @@
+/** Ceiling on one CLI execution. Generous for a read, far short of "forever". */
+export declare const DEFAULT_EXECUTION_TIMEOUT_MS = 15000;
+/** How to start this tree's own CLI. */
+export interface CliLaunch {
+    readonly command: string;
+    readonly argsPrefix: readonly string[];
+}
+/**
+ * Resolve the platform-neutral launch shape. Uses the shared daemon-supervisor
+ * resolvers rather than a second copy of them: the entry path and the
+ * TypeScript-loader flags have to agree with every other self-spawn in this
+ * tree, and the file that owns them says so in as many words.
+ */
+export declare function resolveCliLaunch(): CliLaunch;
+export interface CliExecution {
+    /** The concrete argv that was handed to the CLI, without the launch prefix. */
+    readonly argv: readonly string[];
+    /** Exit status, or `null` when the process died on a signal or was killed. */
+    readonly exitCode: number | null;
+    readonly stdout: string;
+    readonly stderr: string;
+    /** True when the deadline fired and the child was killed. */
+    readonly timedOut: boolean;
+    /** Set ONLY when the process could not be started at all. Never set on timeout. */
+    readonly launchError?: string;
+}
+export interface ExecuteOptions {
+    readonly launch?: CliLaunch;
+    readonly timeoutMs?: number;
+    readonly cwd?: string;
+}
+/**
+ * Run one argv. Always resolves: a failure is a described outcome, never a
+ * rejection, because the caller has to report it to the harness either way.
+ */
+export declare function executeCliArgv(argv: readonly string[], options?: ExecuteOptions): Promise<CliExecution>;

package/dist/services/mcp/cli-executor.js

@@ -0,0 +1,97 @@
+// src/services/mcp/cli-executor.ts
+//
+// The one place the MCP server touches the outside world: it runs a concrete
+// argv against the peaks CLI and hands back what happened.
+//
+// THREE RULES, EACH MEASURED INTO THE SHAPE BELOW.
+//
+// 1. NO SHELL, NO PLATFORM BRANCH (spec §8.2). The launch is
+//    `node <this tree's CLI entry>` — `process.execPath` plus the argument list
+//    that makes this Node interpret that entry. Naming the CLI as a command
+//    (`peaks`) is measurably wrong on a platform whose CLI is a batch shim:
+//    Node refuses to spawn `.cmd`/`.bat` without a shell, and with a shell the
+//    argv array stops being an argv array. `process.execPath` needs neither, so
+//    one shape serves every platform and no `if (platform)` exists.
+//
+// 2. THE TIMEOUT IS MANDATORY, NOT OPTIONAL. `peaks job status --watch` never
+//    returns. It is outside the read-only surface, but it proves the class: a
+//    server that waits forever on a hung child gives its caller no recovery
+//    path. A timeout therefore returns a NAMED failure, never an empty success
+//    (spec §7.2 + §9 rule 3).
+//
+// 3. THE CHILD GETS NO STDIN. Our stdin is the JSON-RPC transport; a child that
+//    inherited it would read our protocol stream and answer the harness itself.
+import { spawn } from 'node:child_process';
+import { readonlySpawnOptions } from '../readonly-surface/argv-guard.js';
+import { cliEntryPath, interpreterArgs } from '../web/daemon-supervisor.js';
+/** Ceiling on one CLI execution. Generous for a read, far short of "forever". */
+export const DEFAULT_EXECUTION_TIMEOUT_MS = 15_000;
+/**
+ * Resolve the platform-neutral launch shape. Uses the shared daemon-supervisor
+ * resolvers rather than a second copy of them: the entry path and the
+ * TypeScript-loader flags have to agree with every other self-spawn in this
+ * tree, and the file that owns them says so in as many words.
+ */
+export function resolveCliLaunch() {
+    return { command: process.execPath, argsPrefix: interpreterArgs(cliEntryPath()) };
+}
+/** The spawn + drain half: one child, one settlement, whatever happens to it. */
+function runChild(launch, argv, cwd, timeoutMs) {
+    return new Promise((resolve) => {
+        let stdout = '';
+        let stderr = '';
+        let timedOut = false;
+        let settled = false;
+        let launchError;
+        const child = spawn(launch.command, [...launch.argsPrefix, ...argv], {
+            ...readonlySpawnOptions(),
+            cwd,
+            // stdin must stay ours; stdout/stderr are read as data.
+            stdio: ['ignore', 'pipe', 'pipe'],
+            // Windows contract: a spawned child must not allocate a console window.
+            windowsHide: true
+        });
+        const deadline = setTimeout(() => {
+            timedOut = true;
+            child.kill();
+        }, timeoutMs);
+        const settle = (exitCode) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(deadline);
+            const outcome = { argv, exitCode, stdout, stderr, timedOut };
+            resolve(launchError === undefined ? outcome : { ...outcome, launchError });
+        };
+        child.stdout.setEncoding('utf8');
+        child.stdout.on('data', (chunk) => {
+            stdout += chunk;
+        });
+        child.stderr.setEncoding('utf8');
+        child.stderr.on('data', (chunk) => {
+            stderr += chunk;
+        });
+        child.on('error', (error) => {
+            launchError = error.message;
+        });
+        // `close` (not `exit`) so both pipes are drained before we read them.
+        child.on('close', (code) => {
+            settle(code);
+        });
+    });
+}
+/**
+ * Run one argv. Always resolves: a failure is a described outcome, never a
+ * rejection, because the caller has to report it to the harness either way.
+ */
+export async function executeCliArgv(argv, options = {}) {
+    let launch;
+    try {
+        launch = options.launch ?? resolveCliLaunch();
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { argv, exitCode: null, stdout: '', stderr: '', timedOut: false, launchError: message };
+    }
+    return runChild(launch, argv, options.cwd ?? process.cwd(), options.timeoutMs ?? DEFAULT_EXECUTION_TIMEOUT_MS);
+}

package/dist/services/mcp/json-rpc.d.ts

@@ -0,0 +1,81 @@
+/** The only JSON-RPC version this server speaks. */
+export declare const JSON_RPC_VERSION: "2.0";
+/** A request/response correlation id. `null` is legal and means "unknown". */
+export type JsonRpcId = string | number | null;
+export interface JsonRpcErrorObject {
+    readonly code: number;
+    readonly message: string;
+    readonly data?: unknown;
+}
+export interface JsonRpcRequest {
+    readonly jsonrpc: typeof JSON_RPC_VERSION;
+    readonly id: JsonRpcId;
+    readonly method: string;
+    readonly params?: unknown;
+}
+/** A request WITHOUT an id. JSON-RPC forbids replying to one. */
+export interface JsonRpcNotification {
+    readonly jsonrpc: typeof JSON_RPC_VERSION;
+    readonly method: string;
+    readonly params?: unknown;
+}
+export interface JsonRpcSuccess {
+    readonly jsonrpc: typeof JSON_RPC_VERSION;
+    readonly id: JsonRpcId;
+    readonly result: unknown;
+}
+export interface JsonRpcFailure {
+    readonly jsonrpc: typeof JSON_RPC_VERSION;
+    readonly id: JsonRpcId;
+    readonly error: JsonRpcErrorObject;
+}
+export type JsonRpcResponse = JsonRpcSuccess | JsonRpcFailure;
+/** Standard JSON-RPC codes. The server adds no private codes of its own. */
+export declare const JSON_RPC_PARSE_ERROR = -32700;
+export declare const JSON_RPC_INVALID_REQUEST = -32600;
+export declare const JSON_RPC_METHOD_NOT_FOUND = -32601;
+export declare const JSON_RPC_INVALID_PARAMS = -32602;
+export declare const JSON_RPC_INTERNAL_ERROR = -32603;
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+/** What one decoded line turned out to be. */
+export type DecodedMessage = {
+    readonly kind: 'request';
+    readonly request: JsonRpcRequest;
+} | {
+    readonly kind: 'notification';
+    readonly notification: JsonRpcNotification;
+} | {
+    readonly kind: 'invalid';
+    readonly id: JsonRpcId;
+    readonly error: JsonRpcErrorObject;
+};
+export declare function makeError(code: number, message: string, data?: unknown): JsonRpcErrorObject;
+export declare function successResponse(id: JsonRpcId, result: unknown): JsonRpcSuccess;
+export declare function failureResponse(id: JsonRpcId, error: JsonRpcErrorObject): JsonRpcFailure;
+/**
+ * Decode one frame.
+ *
+ * `undefined` means "nothing to answer" — an empty line, which is legal padding
+ * and must not be reported as a parse error (an empty line is not a message the
+ * peer sent; it is whitespace between messages).
+ */
+export declare function decodeMessage(line: string): DecodedMessage | undefined;
+/**
+ * Encode one frame for the wire. `JSON.stringify` escapes every newline inside
+ * a string, which is what keeps one message on one line.
+ */
+export declare function encodeMessage(message: JsonRpcResponse | JsonRpcNotification): string;
+/**
+ * The buffer that turns an arbitrary chunking of bytes into whole lines.
+ *
+ * Needed because a pipe delivers no framing of its own: one `data` event may
+ * carry half a message or three of them, and a server that parsed each event as
+ * a message would work on a fast local pipe and fail on a loaded one.
+ */
+export declare class LineDecoder {
+    private buffer;
+    /** Feed a chunk; get back the complete lines it completed (no trailing newline). */
+    push(chunk: string): string[];
+    /** Whatever is left when the stream ends. A peer that never sent a newline still sent a message. */
+    flush(): string[];
+}

package/dist/services/mcp/json-rpc.js

@@ -0,0 +1,116 @@
+// src/services/mcp/json-rpc.ts
+//
+// JSON-RPC 2.0 message shapes plus the stdio framing MCP uses, implemented in
+// this tree rather than pulled in as a dependency.
+//
+// WHY NOT THE SDK. peaks-loop ships 12 runtime dependencies to every user
+// globally, and the protocol surface this server needs is four methods and five
+// error codes — all frozen since the first MCP revision. A dependency would be
+// the larger commitment. See the slice report for the exact surface list.
+//
+// THE FRAMING IS NEWLINE-DELIMITED JSON, not LSP's `Content-Length` headers.
+// That is the MCP stdio transport's rule, and it is also why a message may not
+// contain a raw newline: this module therefore serializes with `JSON.stringify`
+// (which escapes newlines inside strings) and never pretty-prints.
+/** The only JSON-RPC version this server speaks. */
+export const JSON_RPC_VERSION = '2.0';
+/** Standard JSON-RPC codes. The server adds no private codes of its own. */
+export const JSON_RPC_PARSE_ERROR = -32700;
+export const JSON_RPC_INVALID_REQUEST = -32600;
+export const JSON_RPC_METHOD_NOT_FOUND = -32601;
+export const JSON_RPC_INVALID_PARAMS = -32602;
+export const JSON_RPC_INTERNAL_ERROR = -32603;
+export function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isJsonRpcId(value) {
+    return typeof value === 'string' || typeof value === 'number' || value === null;
+}
+export function makeError(code, message, data) {
+    return data === undefined ? { code, message } : { code, message, data };
+}
+export function successResponse(id, result) {
+    return { jsonrpc: JSON_RPC_VERSION, id, result };
+}
+export function failureResponse(id, error) {
+    return { jsonrpc: JSON_RPC_VERSION, id, error };
+}
+function invalid(id, code, message) {
+    return { kind: 'invalid', id, error: makeError(code, message) };
+}
+/** The message's id when it carries a legal one, else the protocol's `null`. */
+function idOf(parsed) {
+    const id = parsed['id'];
+    return isJsonRpcId(id) ? id : null;
+}
+/**
+ * Build the message from a well-formed envelope. The presence of the `id` KEY is
+ * the only thing separating a request from a notification — `id: null` is a legal
+ * id, so this cannot be written as a null check.
+ */
+function buildMessage(parsed, method) {
+    const params = parsed['params'];
+    const head = { jsonrpc: JSON_RPC_VERSION, method, ...(params === undefined ? {} : { params }) };
+    return 'id' in parsed
+        ? { kind: 'request', request: { ...head, id: idOf(parsed) } }
+        : { kind: 'notification', notification: head };
+}
+/**
+ * Decode one frame.
+ *
+ * `undefined` means "nothing to answer" — an empty line, which is legal padding
+ * and must not be reported as a parse error (an empty line is not a message the
+ * peer sent; it is whitespace between messages).
+ */
+export function decodeMessage(line) {
+    if (line.trim().length === 0)
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(line);
+    }
+    catch {
+        return invalid(null, JSON_RPC_PARSE_ERROR, 'Invalid JSON received on the transport.');
+    }
+    if (!isPlainObject(parsed) || parsed['jsonrpc'] !== JSON_RPC_VERSION) {
+        const id = isPlainObject(parsed) ? idOf(parsed) : null;
+        return invalid(id, JSON_RPC_INVALID_REQUEST, `Messages must declare jsonrpc "${JSON_RPC_VERSION}".`);
+    }
+    const method = parsed['method'];
+    if (typeof method !== 'string' || method.length === 0) {
+        return invalid(idOf(parsed), JSON_RPC_INVALID_REQUEST, 'Messages must carry a non-empty "method".');
+    }
+    return buildMessage(parsed, method);
+}
+/**
+ * Encode one frame for the wire. `JSON.stringify` escapes every newline inside
+ * a string, which is what keeps one message on one line.
+ */
+export function encodeMessage(message) {
+    return `${JSON.stringify(message)}\n`;
+}
+/**
+ * The buffer that turns an arbitrary chunking of bytes into whole lines.
+ *
+ * Needed because a pipe delivers no framing of its own: one `data` event may
+ * carry half a message or three of them, and a server that parsed each event as
+ * a message would work on a fast local pipe and fail on a loaded one.
+ */
+export class LineDecoder {
+    buffer = '';
+    /** Feed a chunk; get back the complete lines it completed (no trailing newline). */
+    push(chunk) {
+        this.buffer += chunk;
+        const lines = this.buffer.split('\n');
+        // The last element is either an incomplete line or '' when the chunk ended
+        // on a newline. Either way it stays buffered for the next push.
+        this.buffer = lines.pop() ?? '';
+        return lines;
+    }
+    /** Whatever is left when the stream ends. A peer that never sent a newline still sent a message. */
+    flush() {
+        const remainder = this.buffer.trim().length > 0 ? [this.buffer] : [];
+        this.buffer = '';
+        return remainder;
+    }
+}

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

@@ -0,0 +1,3 @@
+import type { McpToolDefinition } from './surface.js';
+import { type ToolCallContext, type ToolCallResult } from './tool-core.js';
+export declare function callMemorySearchTool(tool: McpToolDefinition, args: Readonly<Record<string, unknown>>, context: ToolCallContext): Promise<ToolCallResult>;