@evomap/evolver-mcp 2.0.23 → 2.0.25

package/dist/codexInstaller.js

@@ -24,6 +24,7 @@ import { parse as parseToml, stringify as stringifyToml } from 'smol-toml';
 import { util } from '@evomap/evolver-core';
 import { commitSharedFile, SharedFileConflictError } from './sharedFileCommit.js';
 import { SymlinkRefusedError, DEFAULT_HOOK_COMMAND, DEFAULT_PROMPT_RECALL_HOOK_COMMAND, evolverManagedHookStatus, stripEvolverHookEntries, } from './installerShared.js';
+import { withCodexProductBridge, isOwnedProductBridge, restoreProductBridgeEntry, PRODUCT_BRIDGE_SERVER_ID } from './productBridge.js';
 /** The MCP server id evolver registers under [mcp_servers.evolver] / removes on uninstall. */
 export const CODEX_MCP_SERVER_ID = 'evolver';
 /** SessionStart matcher: codex fires `startup` on a fresh thread and `resume` on a resumed one — cover both. */
@@ -228,10 +229,20 @@ export function stripCodexManaged(data) {
     const out = { ...data };
     const trustManagedStatus = isObj(out['mcp_servers'])
         && CODEX_MCP_SERVER_ID in out['mcp_servers'];
-    if (isObj(out['mcp_servers']) && CODEX_MCP_SERVER_ID in out['mcp_servers']) {
+    if (isObj(out['mcp_servers'])) {
         const next = { ...out['mcp_servers'] };
-        delete next[CODEX_MCP_SERVER_ID];
-        changed = true;
+        if (CODEX_MCP_SERVER_ID in next) {
+            delete next[CODEX_MCP_SERVER_ID];
+            changed = true;
+        }
+        if (PRODUCT_BRIDGE_SERVER_ID in next && isOwnedProductBridge(next[PRODUCT_BRIDGE_SERVER_ID])) {
+            const restored = restoreProductBridgeEntry(next[PRODUCT_BRIDGE_SERVER_ID]);
+            if (restored.restored)
+                next[PRODUCT_BRIDGE_SERVER_ID] = restored.entry;
+            else
+                delete next[PRODUCT_BRIDGE_SERVER_ID];
+            changed = true;
+        }
         if (Object.keys(next).length > 0)
             out['mcp_servers'] = next;
         else
@@ -290,11 +301,11 @@ export function installCodex(plan, opts) {
     mkdirSync(codexDir, { recursive: true });
     const changed = writeTomlWithRetry(configPath, (current) => {
         if (!opts.force && codexAlreadyInstalled(current, hookCommand, promptRecallHookCommand)) {
-            return { changed: false, data: current };
+            return withCodexProductBridge(current, false);
         }
         return {
             changed: true,
-            data: mergeCodexConfig(current, mcpServer, sessionStartHook, userPromptSubmitHook),
+            data: withCodexProductBridge(mergeCodexConfig(current, mcpServer, sessionStartHook, userPromptSubmitHook), opts.force === true).data,
         };
     }, assertSafe);
     return {

package/dist/index.d.ts

@@ -13,4 +13,5 @@ export * from './antigravityInstaller.js';
 export * from './jsonMcpInstaller.js';
 export * from './opencodeInstaller.js';
 export * from './kiroInstaller.js';
-export * from './envFile.js';
+export * from './envFile.js';
+export * from './productBridge.js';

package/dist/index.js

@@ -13,4 +13,5 @@ export * from './antigravityInstaller.js';
 export * from './jsonMcpInstaller.js';
 export * from './opencodeInstaller.js';
 export * from './kiroInstaller.js';
-export * from './envFile.js';
+export * from './envFile.js';
+export * from './productBridge.js';

package/dist/installer.js

@@ -23,6 +23,7 @@ import { installCodex, uninstallCodex } from './codexInstaller.js';
 // cursor injection is a different mechanism again (a project rules file, not a config/MCP writer): it renders
 // top genes into .cursor/rules/evolver.mdc. It plugs into the same install/uninstall dispatch below.
 import { installCursorRules, uninstallCursorRules } from './cursorRulesInstaller.js';
+import { withClaudeProductBridge, isOwnedProductBridge, restoreProductBridgeEntry, PRODUCT_BRIDGE_SERVER_ID } from './productBridge.js';
 import { installAntigravity, uninstallAntigravity } from './antigravityInstaller.js';
 import { installOpenCode, uninstallOpenCode } from './opencodeInstaller.js';
 import { installKiro, uninstallKiro } from './kiroInstaller.js';
@@ -389,12 +390,22 @@ export function stripManaged(data) {
             delete out['hooks'];
         }
     }
-    // remove evolver MCP server registration
+    // remove evolver MCP server registration and a managed evox-product entry
     const mcp = out['mcpServers'];
-    if (isObj(mcp) && 'evolver' in mcp) {
+    if (isObj(mcp)) {
         const next = { ...mcp };
-        delete next['evolver'];
-        changed = true;
+        if ('evolver' in next) {
+            delete next['evolver'];
+            changed = true;
+        }
+        if (PRODUCT_BRIDGE_SERVER_ID in next && isOwnedProductBridge(next[PRODUCT_BRIDGE_SERVER_ID])) {
+            const restored = restoreProductBridgeEntry(next[PRODUCT_BRIDGE_SERVER_ID]);
+            if (restored.restored)
+                next[PRODUCT_BRIDGE_SERVER_ID] = restored.entry;
+            else
+                delete next[PRODUCT_BRIDGE_SERVER_ID];
+            changed = true;
+        }
         if (Object.keys(next).length > 0)
             out['mcpServers'] = next;
         else {
@@ -444,11 +455,11 @@ function hasEvolverMcpRegistration(config) {
  * silently do nothing outside $HOME). The SessionStart hook lands in ~/.claude/settings.json (already user-level).
  * PROJECT scope keeps the legacy paths under configRoot.
  */
-function claudeCodeTargets(scope, configRoot) {
+function claudeCodeTargets(scope, configRoot, homeDir = homedir()) {
     if (scope === 'user') {
-        const claudeDir = join(homedir(), '.claude');
+        const claudeDir = join(homeDir, '.claude');
         return {
-            mcpConfigPath: join(homedir(), '.claude.json'),
+            mcpConfigPath: join(homeDir, '.claude.json'),
             mcpIsSharedUserConfig: true,
             claudeDir,
             settingsPath: join(claudeDir, 'settings.json'),
@@ -500,7 +511,7 @@ export function installInjection(plan, opts) {
     const hookCommand = opts.hookCommand ?? DEFAULT_HOOK_COMMAND;
     const promptRecallHookCommand = opts.promptRecallHookCommand ?? DEFAULT_PROMPT_RECALL_HOOK_COMMAND;
     const scope = opts.scope ?? 'project';
-    const { mcpConfigPath, mcpIsSharedUserConfig, claudeDir, settingsPath } = claudeCodeTargets(scope, opts.configRoot);
+    const { mcpConfigPath, mcpIsSharedUserConfig, claudeDir, settingsPath } = claudeCodeTargets(scope, opts.configRoot, opts.homeDir);
     const mcpLabel = mcpIsSharedUserConfig ? '~/.claude.json' : '.mcp.json';
     const settingsLabel = mcpIsSharedUserConfig ? '~/.claude/settings.json' : '.claude/settings.json';
     // project scope owns configRoot; user scope writes only home-anchored paths, so configRoot is irrelevant there.
@@ -527,22 +538,27 @@ export function installInjection(plan, opts) {
         && hasEvolverMcpRegistration(existingMcp)
         && hasExactHookCommand(existingSettings, 'SessionStart', hookCommand)
         && hasExactHookCommand(existingSettings, 'UserPromptSubmit', promptRecallHookCommand)) {
+        const product = withClaudeProductBridge(existingMcp, false);
+        if (product.changed) {
+            writeSharedJsonWithRetry(mcpConfigPath, mcpLabel, (current) => withClaudeProductBridge(current, false));
+            return { ok: true, runtime: plan.runtime, mode: plan.mode, files: [mcpConfigPath], alreadyInstalled: true };
+        }
         return { ok: true, runtime: plan.runtime, mode: plan.mode, files: [], alreadyInstalled: true };
     }
     // MCP server registration. project → <root>/.mcp.json (stamped _evolver_managed). user → ~/.claude.json's
     // top-level mcpServers (Claude Code's real user scope); we do NOT stamp the marker into ~/.claude.json because
     // it's Claude Code's own shared config, so uninstall keys off the mcpServers.evolver entry there instead.
     if (mcpIsSharedUserConfig) {
-        writeSharedJsonWithRetry(mcpConfigPath, mcpLabel, (current) => ({
-            changed: true,
-            data: deepMerge(current, plan.config),
-        }));
+        writeSharedJsonWithRetry(mcpConfigPath, mcpLabel, (current) => {
+            const merged = withClaudeProductBridge(deepMerge(current, plan.config), opts.force === true);
+            return { changed: true, data: merged.data };
+        });
     }
     else {
         writeSharedJsonWithRetry(mcpConfigPath, mcpLabel, (current) => {
             const mcpMerged = deepMerge(current, plan.config);
             mcpMerged[MANAGED_MARKER] = true;
-            return { changed: true, data: mcpMerged };
+            return { changed: true, data: withClaudeProductBridge(mcpMerged, opts.force === true).data };
         });
     }
     // .claude/settings.json ← SessionStart hook (hooks-union preserves the user's own hooks). For user scope this
@@ -591,7 +607,7 @@ export function uninstallInjection(runtime, opts) {
         return { ok: false, runtime, mode: 'n/a', files: [], error: `uninstall not implemented for ${runtime}` };
     }
     const scope = opts.scope ?? 'project';
-    const { mcpConfigPath, mcpIsSharedUserConfig, settingsPath } = claudeCodeTargets(scope, opts.configRoot);
+    const { mcpConfigPath, mcpIsSharedUserConfig, settingsPath } = claudeCodeTargets(scope, opts.configRoot, opts.homeDir);
     const cleaned = [];
     const targets = [
         [mcpConfigPath, mcpIsSharedUserConfig ? '~/.claude.json' : '.mcp.json'],

package/dist/productBridge.d.ts

@@ -0,0 +1,37 @@
+export declare const PRODUCT_BRIDGE_SERVER_ID = "evox-product";
+export declare const PRODUCT_BRIDGE_MANAGED_KEY = "_evox_product_managed";
+export declare const PRODUCT_BRIDGE_PREVIOUS_KEY = "_evox_product_previous";
+export declare const PRODUCT_BRIDGE_GRANT_SCHEMA = "evox.product_bridge.grant.v1";
+/** Resolve only a compiled JavaScript shim. Source TypeScript is never written into runtime config. */
+export declare function productBridgeShimPath(): string;
+/** Ownership is explicit. A matching filename alone is never enough to delete a user's server. */
+export declare function isOwnedProductBridge(entry: unknown): boolean;
+/** Restore a user entry previously preserved by an explicit force takeover. */
+export declare function restoreProductBridgeEntry(entry: unknown): {
+    restored: boolean;
+    entry?: unknown;
+};
+/** Merge a managed evox-product server into a parsed MCP JSON object (project .mcp.json or ~/.claude.json). */
+export declare function withClaudeProductBridge(data: Record<string, unknown>, force?: boolean): {
+    changed: boolean;
+    skipped?: boolean;
+    data: Record<string, unknown>;
+};
+/** Merge a managed evox-product table into parsed Codex TOML. */
+export declare function withCodexProductBridge(data: Record<string, unknown>, force?: boolean): {
+    changed: boolean;
+    skipped?: boolean;
+    data: Record<string, unknown>;
+};
+export declare function installClaudeProductBridge(configRoot: string, force?: boolean): {
+    changed: boolean;
+    skipped?: boolean;
+    path: string;
+};
+export declare function uninstallClaudeProductBridge(configRoot: string): boolean;
+export declare function installCodexProductBridge(configRoot: string, force?: boolean): {
+    changed: boolean;
+    skipped?: boolean;
+    path: string;
+};
+export declare function uninstallCodexProductBridge(configRoot: string): boolean;

package/dist/productBridge.js

@@ -0,0 +1,250 @@
+// Unique writer for the EvoX product-tools MCP server (`evox-product`).
+// This is not the evolver gene/memory server. Desktop publishes a loopback
+// grant at ~/.evox/product-bridge.json; this module only registers a stdio
+// shim that fails closed until that file exists. Uninstall removes only a
+// managed evox-product entry.
+import { existsSync, lstatSync, mkdirSync, readFileSync, statSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { parse as parseToml, stringify as stringifyToml } from 'smol-toml';
+import { util } from '@evomap/evolver-core';
+import { commitSharedFile, SharedFileConflictError } from './sharedFileCommit.js';
+export const PRODUCT_BRIDGE_SERVER_ID = 'evox-product';
+export const PRODUCT_BRIDGE_MANAGED_KEY = '_evox_product_managed';
+export const PRODUCT_BRIDGE_PREVIOUS_KEY = '_evox_product_previous';
+export const PRODUCT_BRIDGE_GRANT_SCHEMA = 'evox.product_bridge.grant.v1';
+const CONFIG_WRITE_RETRIES = 5;
+const CONFIG_MODE = 0o600;
+const isObj = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+/** Resolve only a compiled JavaScript shim. Source TypeScript is never written into runtime config. */
+export function productBridgeShimPath() {
+    const modulePath = fileURLToPath(import.meta.url);
+    const candidates = [
+        fileURLToPath(new URL('./productBridgeShim.js', import.meta.url)),
+        join(dirname(modulePath), '../dist/productBridgeShim.js'),
+    ];
+    const built = candidates.find((candidate) => existsSync(candidate));
+    if (!built) {
+        throw new Error('[setup-hooks] product-bridge shim is not built; run the evolver-mcp build before installing the bridge.');
+    }
+    return built;
+}
+const NO_PREVIOUS_ENTRY = Symbol('no previous product bridge entry');
+function productBridgeServerEntry(previous = NO_PREVIOUS_ENTRY) {
+    return {
+        command: process.execPath,
+        args: [productBridgeShimPath()],
+        [PRODUCT_BRIDGE_MANAGED_KEY]: true,
+        ...(previous === NO_PREVIOUS_ENTRY ? {} : { [PRODUCT_BRIDGE_PREVIOUS_KEY]: previous }),
+    };
+}
+function previousEntryForForce(existing, hasExisting) {
+    if (!hasExisting)
+        return NO_PREVIOUS_ENTRY;
+    if (!isOwnedProductBridge(existing))
+        return existing;
+    return isObj(existing) && Object.prototype.hasOwnProperty.call(existing, PRODUCT_BRIDGE_PREVIOUS_KEY)
+        ? existing[PRODUCT_BRIDGE_PREVIOUS_KEY]
+        : NO_PREVIOUS_ENTRY;
+}
+/** Ownership is explicit. A matching filename alone is never enough to delete a user's server. */
+export function isOwnedProductBridge(entry) {
+    return isObj(entry) && entry[PRODUCT_BRIDGE_MANAGED_KEY] === true;
+}
+/** Restore a user entry previously preserved by an explicit force takeover. */
+export function restoreProductBridgeEntry(entry) {
+    if (!isOwnedProductBridge(entry) || !isObj(entry) || !Object.prototype.hasOwnProperty.call(entry, PRODUCT_BRIDGE_PREVIOUS_KEY)) {
+        return { restored: false };
+    }
+    return { restored: true, entry: entry[PRODUCT_BRIDGE_PREVIOUS_KEY] };
+}
+/** Merge a managed evox-product server into a parsed MCP JSON object (project .mcp.json or ~/.claude.json). */
+export function withClaudeProductBridge(data, force = false) {
+    if (Object.prototype.hasOwnProperty.call(data, 'mcpServers') && !isObj(data['mcpServers'])) {
+        throw new Error('[setup-hooks] refusing to overwrite MCP configuration: mcpServers must be an object.');
+    }
+    const servers = isObj(data['mcpServers']) ? { ...data['mcpServers'] } : {};
+    const hasExisting = Object.prototype.hasOwnProperty.call(servers, PRODUCT_BRIDGE_SERVER_ID);
+    const existing = servers[PRODUCT_BRIDGE_SERVER_ID];
+    if (hasExisting && !isOwnedProductBridge(existing) && !force) {
+        return { changed: false, skipped: true, data };
+    }
+    const previous = previousEntryForForce(existing, hasExisting);
+    const next = productBridgeServerEntry(previous);
+    if (JSON.stringify(existing) === JSON.stringify(next))
+        return { changed: false, data };
+    return { changed: true, data: { ...data, mcpServers: { ...servers, [PRODUCT_BRIDGE_SERVER_ID]: next } } };
+}
+/** Merge a managed evox-product table into parsed Codex TOML. */
+export function withCodexProductBridge(data, force = false) {
+    if (Object.prototype.hasOwnProperty.call(data, 'mcp_servers') && !isObj(data['mcp_servers'])) {
+        throw new Error('[setup-hooks] refusing to overwrite MCP configuration: mcp_servers must be an object.');
+    }
+    const servers = isObj(data['mcp_servers']) ? { ...data['mcp_servers'] } : {};
+    const hasExisting = Object.prototype.hasOwnProperty.call(servers, PRODUCT_BRIDGE_SERVER_ID);
+    const existing = servers[PRODUCT_BRIDGE_SERVER_ID];
+    if (hasExisting && !isOwnedProductBridge(existing) && !force) {
+        return { changed: false, skipped: true, data };
+    }
+    const previous = previousEntryForForce(existing, hasExisting);
+    const next = productBridgeServerEntry(previous);
+    if (JSON.stringify(existing) === JSON.stringify(next))
+        return { changed: false, data };
+    return { changed: true, data: { ...data, mcp_servers: { ...servers, [PRODUCT_BRIDGE_SERVER_ID]: next } } };
+}
+function assertNotSymlink(path, label) {
+    let st;
+    try {
+        st = lstatSync(path);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return;
+        throw error;
+    }
+    if (st.isSymbolicLink()) {
+        throw new Error(`[setup-hooks] refusing to operate: ${label} ${path} is a symbolic link.`);
+    }
+}
+function assertConfigPathSafe(path, label) {
+    assertNotSymlink(path, label);
+    assertNotSymlink(`${path}.evolver.lock`, `${label} lock`);
+    const parent = lstatSync(dirname(path));
+    if (parent.isSymbolicLink())
+        throw new Error(`[setup-hooks] refusing to operate: ${label} parent directory is a symbolic link.`);
+    if (!parent.isDirectory())
+        throw new Error(`[setup-hooks] refusing to operate: ${label} parent is not a directory.`);
+}
+function readConfigSnapshot(path, label, parse) {
+    assertConfigPathSafe(path, label);
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return { data: {}, raw: undefined, mode: CONFIG_MODE };
+        throw error;
+    }
+    if (!raw.trim())
+        throw new Error(`[setup-hooks] refusing to overwrite ${label} (${path}): the existing file is empty.`);
+    let data;
+    try {
+        data = parse(raw.trim());
+    }
+    catch (error) {
+        throw new Error(`[setup-hooks] refusing to overwrite ${label} (${path}): the existing document is malformed.`, { cause: error });
+    }
+    if (!isObj(data))
+        throw new Error(`[setup-hooks] refusing to overwrite ${label} (${path}): the existing document must be an object.`);
+    const mode = statSync(path).mode & 0o777;
+    return { data, raw, mode: mode === 0 ? CONFIG_MODE : mode & 0o700 };
+}
+function readRawIfExists(path) {
+    try {
+        return readFileSync(path, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+}
+function releaseConfigLock(lockPath) {
+    const released = util.releaseLock(lockPath);
+    if (!released.released)
+        throw new util.LockReleaseError(released.reason);
+}
+/** Lock, compare, and commit a product bridge update without clobbering concurrent runtime writes. */
+function updateConfigFile(path, label, parse, serialize, update) {
+    const lockPath = `${path}.evolver.lock`;
+    assertConfigPathSafe(path, label);
+    util.acquireLock(lockPath);
+    try {
+        for (let attempt = 1; attempt <= CONFIG_WRITE_RETRIES; attempt += 1) {
+            const snapshot = readConfigSnapshot(path, label, parse);
+            const next = update(snapshot.data);
+            if (!next.changed)
+                return { changed: false, ...(next.skipped ? { skipped: true } : {}) };
+            assertConfigPathSafe(path, label);
+            if (readRawIfExists(path) !== snapshot.raw)
+                continue;
+            try {
+                commitSharedFile({
+                    path,
+                    expectedRaw: snapshot.raw,
+                    nextRaw: serialize(next.data),
+                    mode: snapshot.mode,
+                });
+                return { changed: true };
+            }
+            catch (error) {
+                if (error instanceof SharedFileConflictError)
+                    continue;
+                throw error;
+            }
+        }
+        throw new Error(`[setup-hooks] refusing to overwrite ${label} (${path}): the file changed repeatedly while the product bridge was being installed.`);
+    }
+    finally {
+        releaseConfigLock(lockPath);
+    }
+}
+export function installClaudeProductBridge(configRoot, force = false) {
+    const path = join(configRoot, '.mcp.json');
+    const result = updateConfigFile(path, '.mcp.json', (raw) => JSON.parse(raw), (data) => `${JSON.stringify(data, null, 2)}\n`, (data) => withClaudeProductBridge(data, force));
+    return { ...result, path };
+}
+export function uninstallClaudeProductBridge(configRoot) {
+    const path = join(configRoot, '.mcp.json');
+    if (!existsSync(path))
+        return false;
+    const result = updateConfigFile(path, '.mcp.json', (raw) => JSON.parse(raw), (data) => `${JSON.stringify(data, null, 2)}\n`, (data) => {
+        const servers = data['mcpServers'];
+        if (!isObj(servers) || !isOwnedProductBridge(servers[PRODUCT_BRIDGE_SERVER_ID]))
+            return { changed: false, data };
+        const next = { ...servers };
+        const restored = restoreProductBridgeEntry(next[PRODUCT_BRIDGE_SERVER_ID]);
+        if (restored.restored)
+            next[PRODUCT_BRIDGE_SERVER_ID] = restored.entry;
+        else
+            delete next[PRODUCT_BRIDGE_SERVER_ID];
+        const out = { ...data };
+        if (Object.keys(next).length > 0)
+            out['mcpServers'] = next;
+        else
+            delete out['mcpServers'];
+        return { changed: true, data: out };
+    });
+    return result.changed;
+}
+export function installCodexProductBridge(configRoot, force = false) {
+    const path = join(configRoot, '.codex', 'config.toml');
+    assertNotSymlink(join(configRoot, '.codex'), '.codex');
+    mkdirSync(dirname(path), { recursive: true });
+    const result = updateConfigFile(path, '.codex/config.toml', (raw) => parseToml(raw), (data) => `${stringifyToml(data)}\n`, (data) => withCodexProductBridge(data, force));
+    return { ...result, path };
+}
+export function uninstallCodexProductBridge(configRoot) {
+    const path = join(configRoot, '.codex', 'config.toml');
+    if (!existsSync(path))
+        return false;
+    const result = updateConfigFile(path, '.codex/config.toml', (raw) => parseToml(raw), (data) => `${stringifyToml(data)}\n`, (data) => {
+        const servers = data['mcp_servers'];
+        if (!isObj(servers) || !isOwnedProductBridge(servers[PRODUCT_BRIDGE_SERVER_ID]))
+            return { changed: false, data };
+        const next = { ...servers };
+        const restored = restoreProductBridgeEntry(next[PRODUCT_BRIDGE_SERVER_ID]);
+        if (restored.restored)
+            next[PRODUCT_BRIDGE_SERVER_ID] = restored.entry;
+        else
+            delete next[PRODUCT_BRIDGE_SERVER_ID];
+        const out = { ...data };
+        if (Object.keys(next).length > 0)
+            out['mcp_servers'] = next;
+        else
+            delete out['mcp_servers'];
+        return { changed: true, data: out };
+    });
+    return result.changed;
+}

package/dist/productBridgeShim.d.ts

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+export declare const GRANT_SCHEMA = "evox.product_bridge.grant.v1";
+export declare const MAX_STDIO_FRAME_BYTES: number;
+export declare const MAX_IN_FLIGHT_REQUESTS = 32;
+export declare const MAX_PENDING_STDIO_FRAMES = 64;
+export declare const MAX_PENDING_STDIO_BYTES: number;
+interface JsonRpcMessage {
+    jsonrpc?: string;
+    id?: unknown;
+    method?: string;
+    params?: unknown;
+    result?: unknown;
+    error?: unknown;
+}
+export declare function grantFilePath(env?: NodeJS.ProcessEnv): string;
+export declare function isLoopbackHttp(raw: string): boolean;
+export declare function readGrant(filePath?: string): {
+    url: string;
+    grant: string;
+};
+/** 将请求、通知和客户端响应转发到回环 product bridge。 */
+export declare function dispatch(req: JsonRpcMessage): Promise<Record<string, unknown> | null>;
+export interface DecodedStdioChunk {
+    readonly frames: string[];
+    readonly oversizedFrames: number;
+}
+/** MCP stdio 使用换行分隔 JSON；解码器限制单帧大小，并排出当前缓冲区中的全部完整帧。 */
+export declare class StdioLineDecoder {
+    private pending;
+    private discardingOversized;
+    push(chunk: Buffer | string): DecodedStdioChunk;
+    finish(): {
+        incomplete: boolean;
+    };
+}
+/** 对等待转发的完整帧同时施加数量和字节上限。 */
+export declare class BoundedStdioFrameQueue {
+    private readonly frames;
+    private queuedBytes;
+    get length(): number;
+    get bytes(): number;
+    enqueue(frame: string): boolean;
+    shift(): string | undefined;
+    isBelowResumeWatermark(): boolean;
+}
+export interface StdioBridgeOutput {
+    write(message: string): boolean;
+    on(event: 'drain', listener: () => void): unknown;
+}
+/** 启动可注入流和转发函数的 stdio bridge，便于验证背压与协议行为。 */
+export declare function runStdioBridge(input?: NodeJS.ReadableStream, output?: StdioBridgeOutput, dispatchMessage?: typeof dispatch): void;
+export {};

package/dist/productBridgeShim.js

@@ -0,0 +1,338 @@
+#!/usr/bin/env node
+// EvoX 产品工具的按需 stdio 代理；本进程绝不监听端口。
+// Desktop 通过 ~/.evox/product-bridge.json（或 EVOX_PRODUCT_BRIDGE_GRANT_FILE）发布授权。
+import { randomBytes } from 'node:crypto';
+import { existsSync, lstatSync, readFileSync } from 'node:fs';
+import http from 'node:http';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+export const GRANT_SCHEMA = 'evox.product_bridge.grant.v1';
+const GRANT_HEADER = 'X-Evox-Product-Bridge-Grant';
+const NONCE_HEADER = 'X-Evox-Product-Bridge-Nonce';
+const MAX_GRANT_BYTES = 64 * 1024;
+export const MAX_STDIO_FRAME_BYTES = 2 * 1024 * 1024;
+export const MAX_IN_FLIGHT_REQUESTS = 32;
+export const MAX_PENDING_STDIO_FRAMES = 64;
+export const MAX_PENDING_STDIO_BYTES = 8 * 1024 * 1024;
+const REQUEST_TIMEOUT_MS = 30_000;
+export function grantFilePath(env = process.env) {
+    const override = String(env['EVOX_PRODUCT_BRIDGE_GRANT_FILE'] ?? '').trim();
+    if (override)
+        return override;
+    return join(homedir(), '.evox', 'product-bridge.json');
+}
+export function isLoopbackHttp(raw) {
+    try {
+        const url = new URL(raw);
+        const host = url.hostname.toLowerCase();
+        return url.protocol === 'http:' && (host === '127.0.0.1' || host === '::1' || host === '[::1]');
+    }
+    catch {
+        return false;
+    }
+}
+export function readGrant(filePath = grantFilePath()) {
+    if (!existsSync(filePath)) {
+        throw new Error('EvoX Desktop is not publishing a product-bridge grant. Start EvoX Desktop and retry.');
+    }
+    const st = lstatSync(filePath);
+    if (st.isSymbolicLink() || !st.isFile() || st.size > MAX_GRANT_BYTES) {
+        throw new Error('product-bridge grant file is not a regular file');
+    }
+    const data = JSON.parse(readFileSync(filePath, 'utf8'));
+    if (data.schema !== GRANT_SCHEMA) {
+        throw new Error(`product-bridge grant schema is not ${GRANT_SCHEMA}`);
+    }
+    if (!isLoopbackHttp(String(data.url ?? '')) || !String(data.grant ?? '').trim()) {
+        throw new Error('product-bridge grant is missing a loopback URL or token');
+    }
+    return { url: String(data.url).trim(), grant: String(data.grant).trim() };
+}
+function postJson(url, body, headers) {
+    return new Promise((resolvePromise, reject) => {
+        const target = new URL(url);
+        const payload = Buffer.from(JSON.stringify(body), 'utf8');
+        if (payload.length > MAX_STDIO_FRAME_BYTES) {
+            reject(new Error('product-bridge request is too large'));
+            return;
+        }
+        const req = http.request({
+            protocol: target.protocol,
+            hostname: target.hostname.replace(/^\[(.*)\]$/, '$1'),
+            port: target.port,
+            path: `${target.pathname}${target.search}`,
+            method: 'POST',
+            headers: { 'content-type': 'application/json', 'content-length': payload.length, ...headers },
+        }, (res) => {
+            const chunks = [];
+            let size = 0;
+            let oversized = false;
+            res.on('data', (chunk) => {
+                if (oversized)
+                    return;
+                size += chunk.length;
+                if (size > MAX_STDIO_FRAME_BYTES) {
+                    oversized = true;
+                    req.destroy(new Error('product-bridge response is too large'));
+                    return;
+                }
+                chunks.push(chunk);
+            });
+            res.on('end', () => {
+                if (oversized)
+                    return;
+                if ((res.statusCode ?? 500) < 200 || (res.statusCode ?? 500) >= 300) {
+                    reject(new Error(`product-bridge returned HTTP ${res.statusCode ?? 500}`));
+                    return;
+                }
+                const raw = Buffer.concat(chunks).toString('utf8').trim();
+                if (!raw) {
+                    resolvePromise(undefined);
+                    return;
+                }
+                try {
+                    const parsed = JSON.parse(raw);
+                    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+                        reject(new Error('product-bridge returned a non-object JSON-RPC message'));
+                        return;
+                    }
+                    resolvePromise(parsed);
+                }
+                catch {
+                    reject(new Error('product-bridge returned invalid JSON'));
+                }
+            });
+        });
+        req.setTimeout(REQUEST_TIMEOUT_MS, () => {
+            req.destroy(new Error('product-bridge request timed out'));
+        });
+        req.on('error', reject);
+        req.end(payload);
+    });
+}
+function rpcError(id, message, code = -32000) {
+    return { jsonrpc: '2.0', id: id ?? null, error: { code, message } };
+}
+function isJsonRpcResponse(req) {
+    return req.id !== undefined && ('result' in req || 'error' in req) && req.method === undefined;
+}
+/** 将请求、通知和客户端响应转发到回环 product bridge。 */
+export async function dispatch(req) {
+    if (!req || req.jsonrpc !== '2.0')
+        return rpcError(req?.id, 'invalid JSON-RPC request', -32600);
+    const isRequest = typeof req.method === 'string' && req.method.length > 0;
+    const isResponse = isJsonRpcResponse(req);
+    if (!isRequest && !isResponse)
+        return rpcError(req.id, 'invalid JSON-RPC request', -32600);
+    const expectsResponse = isRequest && req.id !== undefined;
+    let grant;
+    try {
+        grant = readGrant();
+    }
+    catch (error) {
+        return expectsResponse ? rpcError(req.id, error instanceof Error ? error.message : String(error)) : null;
+    }
+    const headers = { [GRANT_HEADER]: grant.grant };
+    if (req.method === 'tools/call')
+        headers[NONCE_HEADER] = randomBytes(16).toString('hex');
+    try {
+        const response = await postJson(grant.url, req, headers);
+        if (!expectsResponse)
+            return null;
+        if (!response)
+            return rpcError(req.id, 'product-bridge returned an empty response');
+        response['id'] = req.id;
+        response['jsonrpc'] = '2.0';
+        return response;
+    }
+    catch (error) {
+        return expectsResponse ? rpcError(req.id, error instanceof Error ? error.message : String(error)) : null;
+    }
+}
+/** MCP stdio 使用换行分隔 JSON；解码器限制单帧大小，并排出当前缓冲区中的全部完整帧。 */
+export class StdioLineDecoder {
+    pending = Buffer.alloc(0);
+    discardingOversized = false;
+    push(chunk) {
+        const incoming = typeof chunk === 'string' ? Buffer.from(chunk, 'utf8') : chunk;
+        const frames = [];
+        let oversizedFrames = 0;
+        let offset = 0;
+        while (offset < incoming.length) {
+            if (this.discardingOversized) {
+                const newline = incoming.indexOf(0x0a, offset);
+                if (newline === -1)
+                    break;
+                this.discardingOversized = false;
+                offset = newline + 1;
+                continue;
+            }
+            const newline = incoming.indexOf(0x0a, offset);
+            if (newline === -1) {
+                const tail = incoming.subarray(offset);
+                if (this.pending.length + tail.length > MAX_STDIO_FRAME_BYTES) {
+                    this.pending = Buffer.alloc(0);
+                    this.discardingOversized = true;
+                    oversizedFrames += 1;
+                }
+                else {
+                    this.pending = Buffer.concat([this.pending, tail]);
+                }
+                break;
+            }
+            let line = Buffer.concat([this.pending, incoming.subarray(offset, newline)]);
+            this.pending = Buffer.alloc(0);
+            offset = newline + 1;
+            if (line.at(-1) === 0x0d)
+                line = line.subarray(0, -1);
+            if (line.length === 0)
+                continue;
+            if (line.length > MAX_STDIO_FRAME_BYTES) {
+                oversizedFrames += 1;
+                continue;
+            }
+            frames.push(line.toString('utf8'));
+        }
+        return { frames, oversizedFrames };
+    }
+    finish() {
+        const incomplete = this.pending.length > 0;
+        this.pending = Buffer.alloc(0);
+        return { incomplete };
+    }
+}
+/** 对等待转发的完整帧同时施加数量和字节上限。 */
+export class BoundedStdioFrameQueue {
+    frames = [];
+    queuedBytes = 0;
+    get length() { return this.frames.length; }
+    get bytes() { return this.queuedBytes; }
+    enqueue(frame) {
+        const bytes = Buffer.byteLength(frame, 'utf8');
+        if (this.frames.length >= MAX_PENDING_STDIO_FRAMES || this.queuedBytes + bytes > MAX_PENDING_STDIO_BYTES) {
+            return false;
+        }
+        this.frames.push({ frame, bytes });
+        this.queuedBytes += bytes;
+        return true;
+    }
+    shift() {
+        const item = this.frames.shift();
+        if (!item)
+            return undefined;
+        this.queuedBytes -= item.bytes;
+        return item.frame;
+    }
+    isBelowResumeWatermark() {
+        return this.frames.length <= Math.floor(MAX_PENDING_STDIO_FRAMES / 2)
+            && this.queuedBytes <= Math.floor(MAX_PENDING_STDIO_BYTES / 2);
+    }
+}
+/** 启动可注入流和转发函数的 stdio bridge，便于验证背压与协议行为。 */
+export function runStdioBridge(input = process.stdin, output = process.stdout, dispatchMessage = dispatch) {
+    const decoder = new StdioLineDecoder();
+    const pendingFrames = new BoundedStdioFrameQueue();
+    let inFlight = 0;
+    let inputPaused = false;
+    let outputBlocked = false;
+    const writeMessage = (message) => {
+        if (!output.write(`${JSON.stringify(message)}\n`)) {
+            outputBlocked = true;
+            pauseInput();
+        }
+    };
+    const processFrame = async (frame) => {
+        let req;
+        try {
+            const parsed = JSON.parse(frame);
+            if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+                writeMessage(rpcError(null, 'invalid JSON-RPC request', -32600));
+                return;
+            }
+            req = parsed;
+        }
+        catch (error) {
+            writeMessage(rpcError(null, error instanceof Error ? error.message : String(error), -32700));
+            return;
+        }
+        const response = await dispatchMessage(req);
+        if (response)
+            writeMessage(response);
+    };
+    const processFrameSafely = (frame) => {
+        void processFrame(frame).catch((error) => {
+            writeMessage(rpcError(null, error instanceof Error ? error.message : String(error)));
+        }).finally(() => {
+            inFlight -= 1;
+            drainFrames();
+        });
+    };
+    const pauseInput = () => {
+        if (inputPaused)
+            return;
+        inputPaused = true;
+        input.pause();
+    };
+    const resumeInputIfSafe = () => {
+        if (!inputPaused || outputBlocked || !pendingFrames.isBelowResumeWatermark())
+            return;
+        inputPaused = false;
+        input.resume();
+    };
+    const writeOverloadForRequest = (frame) => {
+        try {
+            const parsed = JSON.parse(frame);
+            if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+                return;
+            const request = parsed;
+            if (typeof request.method === 'string' && request.id !== undefined) {
+                writeMessage(rpcError(request.id, 'product-bridge stdio queue is full', -32001));
+            }
+        }
+        catch {
+            // 语法错误会由正常解析路径报告；过载路径不再保留该帧。
+        }
+    };
+    function drainFrames() {
+        while (!outputBlocked && inFlight < MAX_IN_FLIGHT_REQUESTS && pendingFrames.length > 0) {
+            const frame = pendingFrames.shift();
+            if (frame === undefined)
+                return;
+            inFlight += 1;
+            processFrameSafely(frame);
+        }
+        resumeInputIfSafe();
+    }
+    output.on('drain', () => {
+        outputBlocked = false;
+        drainFrames();
+    });
+    input.on('data', (chunk) => {
+        const decoded = decoder.push(chunk);
+        for (let index = 0; index < decoded.oversizedFrames; index += 1) {
+            writeMessage(rpcError(null, 'product-bridge stdio frame is too large', -32600));
+        }
+        for (const frame of decoded.frames) {
+            if (!outputBlocked && inFlight < MAX_IN_FLIGHT_REQUESTS && pendingFrames.length === 0) {
+                inFlight += 1;
+                processFrameSafely(frame);
+            }
+            else if (!pendingFrames.enqueue(frame)) {
+                pauseInput();
+                writeOverloadForRequest(frame);
+            }
+        }
+        drainFrames();
+    });
+    input.on('end', () => {
+        if (decoder.finish().incomplete)
+            writeMessage(rpcError(null, 'incomplete newline-delimited JSON-RPC frame', -32700));
+    });
+}
+function isEntrypoint() {
+    const argvPath = process.argv[1];
+    return argvPath !== undefined && resolve(argvPath) === resolve(fileURLToPath(import.meta.url));
+}
+if (isEntrypoint())
+    runStdioBridge();

package/dist/tools.js

@@ -171,7 +171,8 @@ export function buildEvolverTools(deps) {
                 const limit = optionalNonNegativeNumberArg(a, 'limit', 'evolver_recall limit must be a non-negative number') ?? 5;
                 const sessionId = typeof a['sessionId'] === 'string' && a['sessionId'].trim() ? a['sessionId'].trim() : undefined;
                 const review = assetstore.reviewLedgerForStore(deps.store);
-                const genes = await assetstore.listApprovedGenes(deps.store, review, limit);
+                const provenance = assetstore.provenanceStoreForStore(deps.store);
+                const genes = await assetstore.listApprovedGenes(deps.store, review, limit, provenance);
                 const primed = genes.map((g) => {
                     const r = g;
                     const id = typeof r['id'] === 'string' ? r['id'] : String(r['asset_id']);
@@ -199,7 +200,7 @@ export function buildEvolverTools(deps) {
         },
         ...(deps.proxy ? [{
                 name: 'evolver_recipe_search',
-                description: '默认第一步：通过本机 evolver-proxy 搜索 Hub 已发布 Recipe（有序 Gene/Capsule DNA）。命中后调用 evolver_recipe_express。无匹配时再 fallback 到 evolver_asset_search。',
+                description: '默认第一步：通过本机 evolver-proxy 搜索 Hub 已发布 Recipe（有序 Gene/Capsule DNA）。命中后调用 evolver_recipe_express。无匹配时再 fallback 到 evolver_asset_search。旧客户端默认收到 Recipe 数组；设置 includePagination=true 可读取 nextCursor/hasMore。',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -209,16 +210,25 @@ export function buildEvolverTools(deps) {
                         limit: { type: 'number' },
                         cursor: { type: 'string' },
                         sort: { type: 'string' },
+                        includePagination: {
+                            type: 'boolean',
+                            description: 'Set true to return the recipe page envelope with nextCursor/hasMore. The default array shape remains backwards compatible.',
+                        },
                     },
                 },
                 handler: async (a) => {
                     const q = [a['q'], a['query'], a['text']].find((value) => typeof value === 'string' && value.trim().length > 0);
+                    const includePagination = a['includePagination'] === true;
                     const receipt = record(await deps.proxy.searchRecipes({
                         ...(q ? { q } : {}),
                         ...(typeof a['limit'] === 'number' ? { limit: a['limit'] } : {}),
                         ...(typeof a['cursor'] === 'string' ? { cursor: a['cursor'] } : {}),
                         ...(typeof a['sort'] === 'string' ? { sort: a['sort'] } : {}),
                     }));
+                    if (includePagination && (Array.isArray(receipt['recipes'])
+                        || Array.isArray(receipt['results'])
+                        || Array.isArray(receipt['items'])))
+                        return receipt;
                     if (Array.isArray(receipt['recipes']))
                         return receipt['recipes'];
                     if (Array.isArray(receipt['results']))
@@ -327,7 +337,7 @@ export function buildEvolverTools(deps) {
         },
         {
             name: 'evolver_distill_conversation',
-            description: '从当前对话蒸馏可复用能力. 本地仍落 Gene/Capsule, 但 Hub 默认优先发布成 Recipe, 不再优先上 Skill Store. 需要具体 summary、strategy/evidence、artifacts、validation; quality gate 会拒绝弱信号. publish=true 时默认 compose_recipe, 可用 publish_recipe=false 关掉.',
+            description: '从当前对话蒸馏可复用能力. persist=true 只在结果可发布(经宿主验证)或为失败/无轨迹草稿时才落 Gene/Capsule; 携带调用方自报 success 轨迹而未经宿主验证时仅返回草稿不落库. 需要具体 summary、strategy/evidence、artifacts、validation; 质量闸门会将弱信号保留为草稿而不会发布. provider 若不具备 putBundle 能力，成对持久化会 fail-closed 并返回 bundle_persistence_unsupported. Hub 默认优先发布成 Recipe, 不再优先上 Skill Store. publish=true 时默认 compose_recipe, 可用 publish_recipe=false 关掉.',
             inputSchema: {
                 type: 'object',
                 required: ['summary'],
@@ -346,7 +356,7 @@ export function buildEvolverTools(deps) {
                     persist: { type: 'boolean' },
                     publish: { type: 'boolean' },
                     publish_recipe: { type: 'boolean', description: 'When publish=true, also compose and publish a Recipe. Defaults to true.' },
-                    min_score: { type: 'integer', minimum: 1, maximum: 10 },
+                    min_score: { type: 'integer', minimum: 5, maximum: 10 },
                 },
             },
             handler: async (a) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evomap/evolver-mcp",
-  "version": "2.0.23",
+  "version": "2.0.25",
   "private": false,
   "type": "module",
   "engines": {
@@ -20,10 +20,14 @@
     "./stdio": {
       "types": "./dist/stdio.d.ts",
       "default": "./dist/stdio.js"
+    },
+    "./product-bridge": {
+      "types": "./dist/productBridgeShim.d.ts",
+      "default": "./dist/productBridgeShim.js"
     }
   },
   "dependencies": {
-    "@evomap/evolver-core": "2.0.23",
+    "@evomap/evolver-core": "2.0.25",
     "smol-toml": "^1.6.1"
   },
   "repository": {