berry-agent 0.1.0-alpha.1

package/dist/lsp/types.js

@@ -0,0 +1,201 @@
+/**
+ * core:lsp 类型面（03 §10.2——帧层 + 惰性实例 + 诊断回流；批 17a-3）。
+ *
+ * 词面独立律（02 §4.1 席 deps = contracts + context）：本件与 exec/tools 零
+ * DAG 边——spawn / 工具注册 / 事件挂线 / 盘读全经**窄面注入**消费（mcp 件
+ * McpSpawnFace 先例同律）：
+ * - `LspSpawnFace` 与 exec SpawnPipeline.spawnInteractive 结构兼容（组合根
+ *   直接传管道真身；兼容性互证测试在 compat.test.ts）；
+ * - `LspRegisterToolsFace` 与 tools ToolRegistry.register 子面结构兼容；
+ * - `LspScopeFace` 与 context Scope 的 effect/isDisposed 子面结构兼容；
+ * - `LspEventsFace` 与 context EventDispatch.onWaterfall 子面结构兼容
+ *   （tools_post_execute 挂线面）；
+ * - `LspFsFace` 与 node:fs/promises 子面结构兼容（readFile/realpath——盘
+ *   真相源同步用）。
+ *
+ * context 席边为真消费（createLogger——装载态 ui.notify 接线随装配批）。
+ *
+ * 配置面归一（03 §10.2「config 坏形装载期归一响亮拒」条——2026-09-13 f-2
+ * 批立）：行 config 经 `normalizeLspSettings` 装载期归一，坏形抛
+ * `LSP_CONFIG_INVALID` → 行级装载失败（/reload 时刻可修，与
+ * `MCP_CONFIG_INVALID`/`ISSUE_CONFIG_INVALID` 坏形律同族）。归一器与辅助
+ * 函数落本件——词面独立律下不 import mcp（镜像实现各自自持）。
+ */
+import { BaseError } from '../contracts/index.js';
+/* ---------------- 常量（缺省值单源——03 §10.2 字段落码定形注） ---------------- */
+/** 攒头态字节帽（无 \r\n\r\n 分隔符的持续流不无界攒积——超帽走坏帧路径） */
+export const LSP_HEADER_LIMIT_BYTES = 16 * 1024;
+/** 攒正文态字节帽（Content-Length 声明值即缓冲吸收上界——超帽走坏帧路径） */
+export const LSP_BODY_LIMIT_BYTES = 16 * 1024 * 1024;
+/** initialize 握手预算缺省秒数（只罩 spawn+握手；与请求钟分账不互截） */
+export const LSP_STARTUP_TIMEOUT_SEC_DEFAULT = 30;
+/** 单请求预算缺省秒数（只计单请求——与握手钟分账，两钟接力） */
+export const LSP_REQUEST_TIMEOUT_SEC_DEFAULT = 15;
+/** 同 server 连败熔断阈值（实例级旗标、复位走 /reload） */
+export const LSP_CIRCUIT_FAILURE_LIMIT = 3;
+/** 协议化关停宽限缺省（shutdown → exit 通知 → 宽限等退 → killTree 兜底） */
+export const LSP_CLOSE_GRACE_MS = 3_000;
+/** 诊断回流竞速钟缺省（工具面与 post 注入同源） */
+export const LSP_DIAGNOSTICS_TIMEOUT_MS_DEFAULT = 3_500;
+/** 诊断回流竞速钟硬帽（04 §11 同数——min(配置, 硬帽) 执法位） */
+export const LSP_DIAGNOSTICS_TIMEOUT_MS_CAP = 3_500;
+/** 诊断段条目上限（单次注入合计——超限截断注记） */
+export const LSP_DIAGNOSTICS_MAX_ITEMS = 50;
+/** 诊断段总字节上限（追加进 result.content 的段尺寸帽） */
+export const LSP_DIAGNOSTICS_SEGMENT_LIMIT_BYTES = 4 * 1024;
+/**
+ * 归一行 config（坏形响亮拒 LSP_CONFIG_INVALID——/reload 时刻可见；镜像
+ * mcp normalizeMcpConfig 律，词面独立律下辅助函数局部自持）。
+ * null/undefined → 空形 `{servers:{}}`（缺省 servers 空 = 行惰性无害零
+ * spawn）；servers 键缺席同归空表（件级 diagnostics_timeout_ms 可独行）。
+ */
+export function normalizeLspSettings(raw) {
+    if (raw === undefined || raw === null)
+        return { servers: {} };
+    if (typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new BaseError('LSP_CONFIG_INVALID', 'config 须为对象（servers + diagnostics_timeout_ms）');
+    }
+    const v = raw;
+    const servers = v.servers === undefined ? {} : normalizeServers(v.servers);
+    const diagnostics = positiveNumber(v.diagnostics_timeout_ms, 'diagnostics_timeout_ms');
+    return { servers, ...(diagnostics !== undefined ? { diagnostics_timeout_ms: diagnostics } : {}) };
+}
+/** servers 整值归一（键声明序 = 路由裁决序，Object.entries 保插入序） */
+function normalizeServers(raw) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        throw new BaseError('LSP_CONFIG_INVALID', 'config.servers 须为对象（键 = 服务器名）');
+    }
+    const out = {};
+    for (const [name, value] of Object.entries(raw)) {
+        out[name] = normalizeServerEntry(name, value);
+    }
+    return out;
+}
+/** 单服务器条目归一（字段集逐一类型校验——绝对路径/非空路由表/正数域） */
+function normalizeServerEntry(name, value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new BaseError('LSP_CONFIG_INVALID', `servers.${name} 须为对象`);
+    }
+    const v = value;
+    const command = v.command;
+    if (typeof command !== 'string' || command === '' || !command.startsWith('/')) {
+        throw new BaseError('LSP_CONFIG_INVALID', `servers.${name}.command 须为绝对路径（v1 只收绝对路径）：${JSON.stringify(command)}`);
+    }
+    const languages = v.languages;
+    if (!Array.isArray(languages) || languages.length === 0 || languages.some((l) => typeof l !== 'string' || l === '')) {
+        // 空表即路由永不命中的死行——扩展名路由表的物理前提，缺席与空表同拒
+        throw new BaseError('LSP_CONFIG_INVALID', `servers.${name}.languages 须为非空字符串数组`);
+    }
+    const args = strArray(v.args, `servers.${name}.args`);
+    const env = strRecord(v.env, `servers.${name}.env`);
+    const startup = positiveNumber(v.startup_timeout_sec, `servers.${name}.startup_timeout_sec`);
+    const request = positiveNumber(v.request_timeout_sec, `servers.${name}.request_timeout_sec`);
+    return {
+        command,
+        languages: languages,
+        ...(args !== undefined ? { args } : {}),
+        ...(env !== undefined ? { env } : {}),
+        ...(startup !== undefined ? { startup_timeout_sec: startup } : {}),
+        ...(request !== undefined ? { request_timeout_sec: request } : {}),
+    };
+}
+/** 字符串数组字段校验（undefined 放行——可选字段缺席合法） */
+function strArray(value, label) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value) || value.some((e) => typeof e !== 'string')) {
+        throw new BaseError('LSP_CONFIG_INVALID', `${label} 须为字符串数组`);
+    }
+    return value;
+}
+/** 字符串记录字段校验（env 显式注入面） */
+function strRecord(value, label) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new BaseError('LSP_CONFIG_INVALID', `${label} 须为 string→string 对象`);
+    }
+    for (const [k, val] of Object.entries(value)) {
+        if (typeof val !== 'string') {
+            throw new BaseError('LSP_CONFIG_INVALID', `${label}.${k} 须为 string`);
+        }
+    }
+    return value;
+}
+/** 正数域字段校验（超时秒/ms——0/负/非数拒） */
+function positiveNumber(value, label) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) {
+        throw new BaseError('LSP_CONFIG_INVALID', `${label} 须为正数`);
+    }
+    return value;
+}
+/* ---------------- 路由（扩展名路由表——全件唯一裁决序） ---------------- */
+/** 扩展名归一（剥前导点 + lowercase） */
+export function normalizeExtension(ext) {
+    return ext.replace(/^\.+/, '').toLowerCase();
+}
+/** 路径扩展名提取（末点后段，lowercase；无点返空串） */
+export function extensionOf(path) {
+    const base = path.slice(Math.max(path.lastIndexOf('/'), path.lastIndexOf('\\')) + 1);
+    const dot = base.lastIndexOf('.');
+    return dot < 0 ? '' : base.slice(dot + 1).toLowerCase();
+}
+/**
+ * 扩展名路由：config 键声明序扫描，首命中即返（多服务器同扩展名 = 声明序
+ * 首裁决——四工具与诊断注入同表同序，路由规则全件唯一）。无命中返 null。
+ */
+export function routeServer(config, path) {
+    const ext = extensionOf(path);
+    if (ext === '')
+        return null;
+    for (const [name, entry] of Object.entries(config)) {
+        if (entry.languages.some((l) => normalizeExtension(l) === ext))
+            return name;
+    }
+    return null;
+}
+/** didOpen languageId 派生表（常见扩展名；缺席回退扩展名本身） */
+const LANGUAGE_IDS = {
+    ts: 'typescript',
+    tsx: 'typescriptreact',
+    mts: 'typescript',
+    cts: 'typescript',
+    js: 'javascript',
+    jsx: 'javascriptreact',
+    mjs: 'javascript',
+    cjs: 'javascript',
+    json: 'json',
+    md: 'markdown',
+    py: 'python',
+    rs: 'rust',
+    go: 'go',
+    java: 'java',
+    rb: 'ruby',
+    php: 'php',
+    c: 'c',
+    h: 'c',
+    cpp: 'cpp',
+    cc: 'cpp',
+    hpp: 'cpp',
+    cs: 'csharp',
+    css: 'css',
+    scss: 'scss',
+    html: 'html',
+    yml: 'yaml',
+    yaml: 'yaml',
+    toml: 'toml',
+    sh: 'shellscript',
+    zsh: 'shellscript',
+    sql: 'sql',
+};
+/** languageId 派生（扩展名 → languageId；未收录回退扩展名——诚实不猜语义） */
+export function languageIdForPath(path) {
+    const ext = extensionOf(path);
+    return LANGUAGE_IDS[ext] ?? (ext !== '' ? ext : 'plaintext');
+}
+/** 工具结果文本项便捷构造（测试与工具面共用） */
+export function textResult(text, isError) {
+    return { content: [{ type: 'text', text }], ...(isError === true ? { isError: true } : {}) };
+}

package/dist/mcp/bridge.js

@@ -0,0 +1,222 @@
+/**
+ * MCP 服务器桥（03 §10.1 连接语义与子进程治理的承载腿——一服务器一桥）。
+ *
+ * connect 编舞：spawn（exec 管道窄面 + 登记簿同册）→ stderr 转 logger
+ * debug → initialize 握手（startup_timeout_sec 预算罩 spawn+握手全程）→
+ * notifications/initialized → tools/list 分页跟尽（nextCursor 不跟即静默丢
+ * 工具）。连接期任一步折 = MCP_CONNECT_FAILED（子进程收场不留孤儿）。
+ *
+ * call：tools/call 落桥（tool_timeout_sec 逐台执法）；crash（载体 close）→
+ * 在途请求拒 + onDown 通知（服务面撤工具）——不自动重连，复位走 /reload。
+ *
+ * close（协议化关停——ctx.effect 回卷消费）：stdin.end() 告别 → 宽限等退 →
+ * killTree 树杀兜底；幂等（二次 close 复用同一结算）。
+ */
+import { BaseError } from '../contracts/index.js';
+import { createLogger } from '../context/index.js';
+import { JsonRpcConnection } from './jsonrpc.js';
+import { MCP_CLOSE_GRACE_MS, MCP_LINE_LIMIT_BYTES, MCP_PROTOCOL_VERSION, MCP_STARTUP_TIMEOUT_SEC_DEFAULT, MCP_TOOL_TIMEOUT_SEC_DEFAULT, } from './types.js';
+/**
+ * 连接单服务器（发现全程——握手+分页）。连接期失败抛 MCP_CONNECT_FAILED
+ * （spawn 失败 / 握手超时 / 行帧超帽 / 服务器即退），子进程在抛出前收场。
+ */
+export async function connectMcpServer(server, config, deps) {
+    const logger = deps.logger ?? createLogger('mcp');
+    const graceMs = deps.closeGraceMs ?? MCP_CLOSE_GRACE_MS;
+    const startupMs = (config.startup_timeout_sec ?? MCP_STARTUP_TIMEOUT_SEC_DEFAULT) * 1_000;
+    const toolTimeoutMs = (config.tool_timeout_sec ?? MCP_TOOL_TIMEOUT_SEC_DEFAULT) * 1_000;
+    // ── spawn（登记簿同册：owner = mcp:<server>——「谁开的」审计面） ──
+    let child;
+    try {
+        child = deps.spawn.spawnInteractive({
+            argv: [config.command, ...(config.args ?? [])],
+            env: config.env !== undefined ? { set: config.env } : undefined,
+            owner: `mcp:${server}`,
+        });
+    }
+    catch (err) {
+        throw new BaseError('MCP_CONNECT_FAILED', `spawn 失败（${server}）：${errText(err)}`, { cause: asError(err) });
+    }
+    // ── 载体状态机（crash 检测 = close 事件；行帧 fatal = 封读+树杀） ──
+    let downReason;
+    const downCallbacks = [];
+    let exitInfo;
+    const exitWaiters = [];
+    let closePromise;
+    let connection;
+    const markDown = (reason) => {
+        if (downReason !== undefined)
+            return; // 一次结算（crash 与 fatal 双源竞速同封）
+        downReason = reason;
+        for (const cb of [...downCallbacks])
+            cb(reason);
+        for (const w of [...exitWaiters])
+            w();
+        exitWaiters.length = 0;
+    };
+    child.onExit((info) => {
+        exitInfo = info;
+        connection?.failAll(new BaseError('MCP_CONNECT_FAILED', info.spawnError !== undefined
+            ? `spawn 失败（${server}）：${info.spawnError.message}`
+            : `server 退出（${server}，code=${info.code}）`));
+        markDown(info.spawnError !== undefined ? `spawn 失败：${info.spawnError.message}` : `server 退出（code=${info.code}）`);
+    });
+    connection = new JsonRpcConnection({
+        send: (line) => child.stdin.write(`${line}\n`),
+        lineLimitBytes: MCP_LINE_LIMIT_BYTES,
+        warn: (message) => logger.warn(message),
+        onFatal: () => {
+            // 载体级失败收场：封读（静默巨行不进宿主堆）+ 树杀 server（不杀即永久孤儿）
+            child.stdout.destroy();
+            child.kill();
+        },
+    });
+    child.stdout.on('data', (chunk) => connection?.feed(chunk));
+    child.stderr.on('data', (chunk) => {
+        for (const line of chunk.toString('utf8').split('\n')) {
+            if (line.trim() !== '')
+                logger.debug(`[mcp:${server}] ${line}`);
+        }
+    });
+    try {
+        // ── initialize 握手（startup 预算罩全程；服务器回显异版本不拒——v1 不挑） ──
+        await connection.request('initialize', {
+            protocolVersion: MCP_PROTOCOL_VERSION,
+            capabilities: {},
+            clientInfo: { name: 'berry-agent', version: deps.clientVersion ?? '0.1.0' },
+        }, startupMs);
+        connection.notify('notifications/initialized');
+        // ── tools/list 分页跟尽（nextCursor 不跟即静默丢工具——03 §10.1 明律） ──
+        const tools = [];
+        let cursor;
+        do {
+            const page = (await connection.request('tools/list', cursor !== undefined ? { cursor } : undefined, startupMs));
+            if (page !== null && typeof page === 'object' && Array.isArray(page.tools)) {
+                for (const raw of page.tools) {
+                    const tool = normalizeTool(raw);
+                    if (tool !== undefined)
+                        tools.push(tool);
+                }
+            }
+            cursor = typeof page?.nextCursor === 'string' ? page.nextCursor : undefined;
+        } while (cursor !== undefined);
+        if (downReason !== undefined) {
+            // 发现途中已死（竞速护栏——close 与末页响应近同时到）
+            throw new BaseError('MCP_CONNECT_FAILED', `server 退出（${server}）：${downReason}`);
+        }
+        const bridge = {
+            server,
+            tools,
+            toolTimeoutMs,
+            call: (tool, args) => callTool(connection, server, tool, args, toolTimeoutMs, () => downReason),
+            onDown(callback) {
+                if (downReason !== undefined)
+                    callback(downReason); // 迟到订阅即回调
+                else
+                    downCallbacks.push(callback);
+            },
+            close: () => {
+                if (closePromise === undefined) {
+                    closePromise = closeChild(child, graceMs, () => exitInfo, (waiter) => exitWaiters.push(waiter));
+                }
+                return closePromise; // 幂等——二次 close 复用首次结算
+            },
+        };
+        return bridge;
+    }
+    catch (err) {
+        // 连接期失败收场：结清 pending + 树杀（不留孤儿）→ 分类抛出
+        connection.failAll(err instanceof BaseError ? err : new BaseError('MCP_CONNECT_FAILED', `连接失败（${server}）：${errText(err)}`));
+        child.kill();
+        if (err instanceof BaseError && err.code === 'MCP_CONNECT_FAILED')
+            throw err;
+        if (err instanceof Error && err.message.includes('超时')) {
+            throw new BaseError('MCP_CONNECT_FAILED', `initialize 握手超时（${server}，预算 ${startupMs}ms）`, {
+                cause: err,
+            });
+        }
+        throw new BaseError('MCP_CONNECT_FAILED', `连接失败（${server}）：${errText(err)}`, { cause: asError(err) });
+    }
+}
+/** tools/call 执行体（一切失败折 isError 结果——数据面不改抛出面） */
+function callTool(connection, server, tool, args, timeoutMs, downOf) {
+    const down = downOf();
+    if (connection === undefined || down !== undefined) {
+        return Promise.resolve({
+            content: [{ type: 'text', text: `MCP 服务器 ${server} 已断开（${down ?? '未知原因'}）——/reload 复位` }],
+            isError: true,
+        });
+    }
+    return connection
+        .request('tools/call', { name: tool, arguments: args }, timeoutMs)
+        .then((result) => mapToolResult(result))
+        .catch((err) => ({
+        content: [{ type: 'text', text: `MCP 工具调用失败（${server}__${tool}）：${errText(err)}` }],
+        isError: true,
+    }));
+}
+/** tools/call 响应映射（text/image 直映射；其余形折 JSON 文本——不丢内容） */
+function mapToolResult(result) {
+    const r = (result ?? {});
+    const content = [];
+    if (Array.isArray(r.content)) {
+        for (const item of r.content) {
+            if (typeof item !== 'object' || item === null)
+                continue;
+            const c = item;
+            if (c.type === 'text' && typeof c.text === 'string') {
+                content.push({ type: 'text', text: c.text });
+            }
+            else if (c.type === 'image' && typeof c.data === 'string' && typeof c.mimeType === 'string') {
+                content.push({ type: 'image', data: c.data, mimeType: c.mimeType });
+            }
+            else {
+                content.push({ type: 'text', text: JSON.stringify(item) });
+            }
+        }
+    }
+    return { content, isError: r.isError === true || undefined };
+}
+/** 协议化关停编舞（备忘录归调用侧）：stdin.end 告别 → 宽限 → 树杀兜底 */
+function closeChild(child, graceMs, exitOf, addWaiter) {
+    return (async () => {
+        try {
+            child.stdin.end(); // 协议化告别（stdin 关 = stdio server 的关停信号）
+        }
+        catch {
+            // stdin 已坏（服务器先死）——宽限/树杀照走
+        }
+        const exited = await new Promise((resolve) => {
+            if (exitOf() !== undefined) {
+                resolve(true);
+                return;
+            }
+            const timer = setTimeout(() => resolve(false), graceMs);
+            addWaiter(() => {
+                clearTimeout(timer);
+                resolve(true);
+            });
+        });
+        if (!exited)
+            child.kill(); // 宽限尽——树杀兜底（防挂死 server 永久孤儿）
+    })();
+}
+/** tools/list 条目归一（name 非 string 弃；inputSchema 缺席容错空 object） */
+function normalizeTool(raw) {
+    if (typeof raw !== 'object' || raw === null)
+        return undefined;
+    const t = raw;
+    if (typeof t.name !== 'string' || t.name === '')
+        return undefined;
+    return {
+        name: t.name,
+        ...(typeof t.description === 'string' ? { description: t.description } : {}),
+        inputSchema: typeof t.inputSchema === 'object' && t.inputSchema !== null ? t.inputSchema : { type: 'object' },
+    };
+}
+function errText(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+function asError(err) {
+    return err instanceof Error ? err : new Error(String(err));
+}

package/dist/mcp/codes.js

@@ -0,0 +1,21 @@
+/**
+ * mcp 桥域错误码注册（03 §10.1——MCP_ 前缀族首批）。
+ *
+ * 前缀族明列见 contracts/errors.ts ERROR_CODE_PREFIXES（02 §5.3 #1）；码名清
+ * 单与语义真源 = 03 篇 §10.1 连接语义/行帧卫生条 MCP_ 两码。本文件由模块公
+ * 开面 index.ts 引入（注册纪律：写入点文件必须实际 import 本文件注册才发
+ * 生——与 issue/scheduler 先例同款）。
+ */
+import { registerErrorCodes } from '../contracts/index.js';
+registerErrorCodes([
+    {
+        code: 'MCP_CONNECT_FAILED',
+        module: 'mcp',
+        description: '单服务器连接失败降级（spawn 失败 / initialize 握手超时 / 运行期 crash / 行帧坏或 stdout 单行超 8MiB 帽的载体级失败——不阻同行其余、撤工具 + ui.notify warn、不自动重连）',
+    },
+    {
+        code: 'MCP_CONFIG_INVALID',
+        module: 'mcp',
+        description: 'config.servers 行载荷坏（键词法违例 / command 非绝对路径 / 字段类型坏形——响亮拒不静默吞）',
+    },
+]);

package/dist/mcp/index.js

@@ -0,0 +1,19 @@
+/**
+ * core:mcp 公开面（02 §4.1 席 deps {contracts, context}——stdio 行帧
+ * JSON-RPC 手写最小桥，03 §10.1）。
+ *
+ * 装载态集成归批 12 装载面后装配批：core:mcp 插件装载时组服务（spawn 窄面
+ * 注入 exec 管道真身、registry 窄面注入 tools 注册表真身、scope = ctx 作
+ * 用域、notify 接 ui.notify warn 面）→ config.servers 归一 → apply 异步发现
+ * → 注册进全局层。
+ */
+import './codes.js';
+export { MCP_SERVER_NAME_RE, MCP_STARTUP_TIMEOUT_SEC_DEFAULT, MCP_TOOL_TIMEOUT_SEC_DEFAULT, MCP_LINE_LIMIT_BYTES, MCP_NATIVE_TOOL_LIMIT, MCP_CLOSE_GRACE_MS, MCP_PROTOCOL_VERSION, normalizeMcpConfig, } from './types.js';
+// 行帧 JSON-RPC 协议腿
+export { LineDecoder, JsonRpcConnection, JsonRpcError } from './jsonrpc.js';
+// 服务器桥
+export { connectMcpServer } from './bridge.js';
+// 工具注册面
+export { MCP_DIRECTORY_TOOL_NAME, mcpToolKey, splitMcpToolKey, filterServerTools, buildMcpToolDefs } from './tools.js';
+// 服务编排
+export { createMcpService } from './service.js';