spectra-cli 4.1.1 → 4.3.0

package/dist/mcp/lib/file-nav-helpers.js

@@ -0,0 +1,305 @@
+/**
+ * Feature 171 — File Navigation 纯计算/IO helper（对标 response-helpers.ts，便于 ≥95% 单测）
+ *
+ * 把 view_file / search_in_file / list_directory 的全部可独立测试逻辑下沉到本模块，
+ * 让 file-nav-tools.ts 的 handler 保持薄编排。
+ *
+ * 🔴 路径安全（resolveSafePath）是 LFI 红线：词法 containment 先于 fs，realpath 穿透 symlink，
+ *    path.relative 防前缀碰撞，全部错误码脱敏（不回传绝对路径）。
+ */
+import * as path from 'node:path';
+import { realpathSync, readdirSync, statSync } from 'node:fs';
+// ============================================================
+// 常量（REFACTOR 阶段集中）
+// ============================================================
+/** view_file 无定位参数时的默认窗口（对标 OpenHands 前 200 行） */
+export const DEFAULT_VIEW_WINDOW = 200;
+/** search_in_file 默认返回命中数 */
+export const DEFAULT_MAX_MATCHES = 50;
+/** maxMatches 安全上界（clamp） */
+export const MAX_MATCHES_CAP = 1000;
+/** 用户 pattern 长度上界（ReDoS 缓解：限制输入） */
+export const MAX_PATTERN_LENGTH = 200;
+/** contextLines 上界 */
+export const MAX_CONTEXT_LINES = 20;
+/** list_directory depth 上界 */
+export const MAX_DIR_DEPTH = 10;
+/** list_directory 单次最多返回条目（防超大目录灌爆 payload） */
+export const MAX_DIR_ENTRIES = 5000;
+/** isBinary 探测前缀字节数 */
+const BINARY_SNIFF_BYTES = 8000;
+/** path 参数长度上界（防超长 path 灌爆响应 / 异常输入） */
+export const MAX_PATH_LENGTH = 4096;
+/** 用户正则可搜索的内容字节上界（ReDoS 缓解：限制 regex 作用的输入规模） */
+export const MAX_REGEX_CONTENT_BYTES = 2_000_000;
+/**
+ * 解析并校验用户路径在 projectRoot 内（含 symlink 穿透）。
+ *
+ * 判定顺序（FR-013，修 Codex PATH-CLASSIFICATION）：
+ *   1. NUL 字节 → invalid-input
+ *   2. realRoot = realpath(projectRoot)（projectRoot 自身 symlink 也解析）
+ *   3. 词法 containment（path.relative）→ 越界(含不存在)立即 path-outside-root，不触 fs
+ *   4. realpath 穿透候选 → ENOENT/error → file-not-found（脱敏）
+ *   5. realpath 后再 containment → symlink 逃逸 → path-outside-root
+ * posix-only（Windows 归一化 YAGNI）。
+ */
+export function resolveSafePath(projectRoot, userPath) {
+    if (typeof userPath !== 'string' || userPath.length === 0 || userPath.length > MAX_PATH_LENGTH || userPath.includes('\0')) {
+        return { ok: false, code: 'invalid-input' };
+    }
+    let realRoot;
+    try {
+        realRoot = realpathSync.native(projectRoot);
+    }
+    catch {
+        return { ok: false, code: 'file-not-found' };
+    }
+    const candidate = path.resolve(realRoot, userPath);
+    // 词法 containment 先于任何 fs（越界且不存在的路径也归类 path-outside-root，不泄露 fs 状态）
+    if (isOutside(realRoot, candidate)) {
+        return { ok: false, code: 'path-outside-root' };
+    }
+    let realCandidate;
+    try {
+        realCandidate = realpathSync.native(candidate);
+    }
+    catch {
+        return { ok: false, code: 'file-not-found' };
+    }
+    // realpath 后再判，拦截 symlink 逃逸
+    if (isOutside(realRoot, realCandidate)) {
+        return { ok: false, code: 'path-outside-root' };
+    }
+    return { ok: true, realPath: realCandidate };
+}
+/**
+ * 用 path.relative 判定 target 是否在 root 外。
+ * 禁止裸 startsWith（避免 /repo vs /repo2 前缀碰撞）。rel==='' 视为 root 本身，contained。
+ */
+function isOutside(root, target) {
+    const rel = path.relative(root, target);
+    return rel.startsWith('..') || path.isAbsolute(rel);
+}
+/**
+ * 将内容拆为行数组：按 \r?\n 切分；末尾换行不计为额外空行；空内容 → []。
+ */
+export function splitLines(content) {
+    if (content === '')
+        return [];
+    const parts = content.split(/\r?\n/);
+    if (parts.length > 0 && parts[parts.length - 1] === '')
+        parts.pop();
+    return parts;
+}
+/**
+ * 按行区间切片，带行号前缀。无定位参数时返回前 defaultWindow 行 + truncated 标志。
+ * 区间端点被安全 clamp 到 [1, totalLines]，超界不抛错。
+ */
+export function sliceLines(content, opts = {}) {
+    const allLines = splitLines(content);
+    const totalLines = allLines.length;
+    if (totalLines === 0) {
+        return { lines: [], startLine: 0, endLine: 0, totalLines: 0, truncated: false };
+    }
+    const window = opts.defaultWindow ?? DEFAULT_VIEW_WINDOW;
+    let start;
+    let end;
+    let truncated = false;
+    if (opts.startLine === undefined && opts.endLine === undefined) {
+        start = 1;
+        end = Math.min(totalLines, window);
+        truncated = totalLines > window;
+    }
+    else {
+        start = opts.startLine ?? 1;
+        end = opts.endLine ?? totalLines;
+    }
+    start = Math.max(1, Math.min(Math.trunc(start), totalLines));
+    end = Math.max(start, Math.min(Math.trunc(end), totalLines));
+    const lines = allLines.slice(start - 1, end).map((t, i) => `${start + i}\t${t}`);
+    return { lines, startLine: start, endLine: end, totalLines, truncated };
+}
+/** UTF-8 byte / 4 的 token 代理（改名避开 token-counter.ts 的 estimateTokens 命名碰撞） */
+export function estimateUtf8ByteTokens(text) {
+    return Math.ceil(Buffer.byteLength(text, 'utf-8') / 4);
+}
+/** 二进制探测：前缀字节含 NUL 即判二进制 */
+export function isBinary(buf) {
+    const n = Math.min(buf.length, BINARY_SNIFF_BYTES);
+    for (let i = 0; i < n; i++) {
+        if (buf[i] === 0)
+            return true;
+    }
+    return false;
+}
+// ============================================================
+// 数值 clamp（FR-008）
+// ============================================================
+/** 把数值 clamp 到 [min, max]，非法值（NaN/缺省）回退 fallback；返回是否被 clamp */
+export function clampInt(value, min, max, fallback) {
+    if (typeof value !== 'number' || Number.isNaN(value)) {
+        return { value: fallback, clamped: true };
+    }
+    const int = Math.trunc(value);
+    if (int < min)
+        return { value: min, clamped: true };
+    if (int > max)
+        return { value: max, clamped: true };
+    return { value: int, clamped: int !== value };
+}
+/** 转义 literal pattern 中的正则元字符 */
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * ReDoS 启发式：探测高危结构，命中则拒绝。覆盖：
+ *   - 嵌套量词组后接量词/有界重复：(a+)+ / (.*)* / (a{1,99}){1,99}
+ *   - 量化的交替组：(a|a)+ / (a|b)*
+ * 非完整 ReDoS 证明（配合 pattern 长度 + content byte 上界，FR-005 明示）。
+ */
+export function isRiskyRegex(pattern) {
+    const innerQuantGroup = /\([^)]*[+*{][^)]*\)/; // 组内含量词
+    const outerRepeat = /\)\s*([+*]|\{\d+,?\d*\})/; // 组后接 + * 或 {n,m}
+    if (innerQuantGroup.test(pattern) && outerRepeat.test(pattern))
+        return true;
+    if (/\([^)]*\|[^)]*\)\s*[+*]/.test(pattern))
+        return true; // 量化交替组
+    return false;
+}
+/**
+ * 在内容内逐行匹配 pattern，返回带上下文行的命中列表。
+ * 失败（空/超长/非法正则/高危正则）返回 { ok:false, reason }，由 handler 映射 invalid-input。
+ */
+export function matchInFile(content, pattern, opts = {}) {
+    if (typeof pattern !== 'string' || pattern.length === 0) {
+        return { ok: false, reason: 'pattern 必填且非空' };
+    }
+    if (pattern.length > MAX_PATTERN_LENGTH) {
+        return { ok: false, reason: `pattern 过长（上限 ${MAX_PATTERN_LENGTH}）` };
+    }
+    const isRegex = opts.isRegex ?? false;
+    const contextLines = clampInt(opts.contextLines ?? 0, 0, MAX_CONTEXT_LINES, 0);
+    const maxMatches = clampInt(opts.maxMatches ?? DEFAULT_MAX_MATCHES, 1, MAX_MATCHES_CAP, DEFAULT_MAX_MATCHES);
+    const warnings = [];
+    if (maxMatches.clamped)
+        warnings.push('maxMatches-clamped');
+    if (contextLines.clamped)
+        warnings.push('contextLines-clamped');
+    let regex;
+    if (isRegex) {
+        if (isRiskyRegex(pattern)) {
+            return { ok: false, reason: 'pattern 含高危结构（嵌套/量化分组，ReDoS 风险）' };
+        }
+        // ReDoS 缓解：限制用户正则作用的内容规模（literal 搜索无回溯风险，不限制）
+        if (Buffer.byteLength(content, 'utf-8') > MAX_REGEX_CONTENT_BYTES) {
+            return { ok: false, reason: `内容超 ${MAX_REGEX_CONTENT_BYTES} 字节，正则搜索受限，请用 literal 或先 view_file 缩小范围` };
+        }
+        try {
+            regex = new RegExp(pattern);
+        }
+        catch {
+            return { ok: false, reason: '非法正则' };
+        }
+    }
+    else {
+        regex = new RegExp(escapeRegExp(pattern));
+    }
+    const lines = splitLines(content);
+    const matches = [];
+    let totalMatches = 0;
+    for (let i = 0; i < lines.length; i++) {
+        if (regex.test(lines[i])) {
+            totalMatches++;
+            if (matches.length < maxMatches.value) {
+                matches.push({
+                    line: i + 1,
+                    text: lines[i],
+                    before: lines.slice(Math.max(0, i - contextLines.value), i),
+                    after: lines.slice(i + 1, Math.min(lines.length, i + 1 + contextLines.value)),
+                });
+            }
+        }
+    }
+    if (totalMatches > matches.length)
+        warnings.push('matches-truncated');
+    return { ok: true, matches, totalMatches, returnedMatches: matches.length, warnings };
+}
+/**
+ * 列举目录条目（可递归 depth 层）。默认仅过滤 .git；includeIgnored=true 含 .git。
+ * 超 MAX_DIR_ENTRIES 截断并加 listing-truncated warning。readdir 失败的子目录静默跳过。
+ */
+export function buildDirListing(absDir, opts = {}) {
+    const depth = clampInt(opts.depth ?? 1, 1, MAX_DIR_DEPTH, 1);
+    const includeIgnored = opts.includeIgnored ?? false;
+    // maxEntries 仅供测试注入截断阈值；生产默认 MAX_DIR_ENTRIES
+    const maxEntries = opts.maxEntries && opts.maxEntries > 0 ? opts.maxEntries : MAX_DIR_ENTRIES;
+    const warnings = [];
+    if (depth.clamped)
+        warnings.push('depth-clamped');
+    const entries = [];
+    let truncated = false;
+    const walk = (dir, rel, level) => {
+        if (truncated)
+            return;
+        let dirents;
+        try {
+            dirents = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        dirents.sort((a, b) => a.name.localeCompare(b.name));
+        for (const d of dirents) {
+            if (!includeIgnored && d.name === '.git')
+                continue;
+            if (entries.length >= maxEntries) {
+                truncated = true;
+                return;
+            }
+            const relName = rel ? `${rel}/${d.name}` : d.name;
+            const type = d.isSymbolicLink() ? 'symlink' : d.isDirectory() ? 'dir' : 'file';
+            let size = null;
+            if (type === 'file') {
+                try {
+                    size = statSync(path.join(dir, d.name)).size;
+                }
+                catch {
+                    size = null;
+                }
+            }
+            entries.push({ name: relName, type, size });
+            if (type === 'dir' && level < depth.value) {
+                walk(path.join(dir, d.name), relName, level + 1);
+            }
+        }
+    };
+    walk(absDir, '', 1);
+    if (truncated)
+        warnings.push('listing-truncated');
+    return { entries, warnings };
+}
+// ============================================================
+// nextStepHint（FR-040，独立实现不碰 response-helpers.ts）
+// ============================================================
+/** 生成 file-nav 工具的下一步引导（风格对齐 generateNextStepHint，闭环 view_file ↔ context） */
+export function buildFileNavHint(toolName, data) {
+    if (toolName === 'view_file') {
+        const startLine = data['startLine'] ?? 0;
+        const endLine = data['endLine'] ?? 0;
+        const totalLines = data['totalLines'] ?? 0;
+        if (data['truncated'] === true) {
+            return `已显示前 ${endLine}/${totalLines} 行（截断），建议用 startLine/endLine 翻页，或调 context 看该 symbol 的调用方与依赖`;
+        }
+        return `已显示第 ${startLine}-${endLine}/${totalLines} 行，建议调 context 查看该区域 symbol 的调用方与依赖`;
+    }
+    if (toolName === 'search_in_file') {
+        const total = data['totalMatches'] ?? 0;
+        if (total === 0) {
+            return '未找到匹配，建议放宽 pattern、改用 isRegex，或确认文件路径';
+        }
+        return `找到 ${total} 处匹配，建议用 view_file 按某处行号查看完整上下文行段`;
+    }
+    const count = data['entryCount'] ?? 0;
+    return `目录含 ${count} 项，建议用 view_file 查看具体文件，或 search_in_file 在文件内定位 symbol`;
+}
+//# sourceMappingURL=file-nav-helpers.js.map

package/dist/mcp/lib/file-nav-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-nav-helpers.js","sourceRoot":"","sources":["../../../src/mcp/lib/file-nav-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,QAAQ,EAAe,MAAM,SAAS,CAAC;AAE3E,+DAA+D;AAC/D,oBAAoB;AACpB,+DAA+D;AAE/D,kDAAkD;AAClD,MAAM,CAAC,MAAM,mBAAmB,GAAG,GAAG,CAAC;AACvC,6BAA6B;AAC7B,MAAM,CAAC,MAAM,mBAAmB,GAAG,EAAE,CAAC;AACtC,6BAA6B;AAC7B,MAAM,CAAC,MAAM,eAAe,GAAG,IAAI,CAAC;AACpC,qCAAqC;AACrC,MAAM,CAAC,MAAM,kBAAkB,GAAG,GAAG,CAAC;AACtC,sBAAsB;AACtB,MAAM,CAAC,MAAM,iBAAiB,GAAG,EAAE,CAAC;AACpC,8BAA8B;AAC9B,MAAM,CAAC,MAAM,aAAa,GAAG,EAAE,CAAC;AAChC,+CAA+C;AAC/C,MAAM,CAAC,MAAM,eAAe,GAAG,IAAI,CAAC;AACpC,uBAAuB;AACvB,MAAM,kBAAkB,GAAG,IAAI,CAAC;AAChC,wCAAwC;AACxC,MAAM,CAAC,MAAM,eAAe,GAAG,IAAI,CAAC;AACpC,gDAAgD;AAChD,MAAM,CAAC,MAAM,uBAAuB,GAAG,SAAS,CAAC;AASjD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,eAAe,CAAC,WAAmB,EAAE,QAAgB;IACnE,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,IAAI,QAAQ,CAAC,MAAM,GAAG,eAAe,IAAI,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QAC1H,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,eAAe,EAAE,CAAC;IAC9C,CAAC;IACD,IAAI,QAAgB,CAAC;IACrB,IAAI,CAAC;QACH,QAAQ,GAAG,YAAY,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;IAC9C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,gBAAgB,EAAE,CAAC;IAC/C,CAAC;IACD,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IACnD,mEAAmE;IACnE,IAAI,SAAS,CAAC,QAAQ,EAAE,SAAS,CAAC,EAAE,CAAC;QACnC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,mBAAmB,EAAE,CAAC;IAClD,CAAC;IACD,IAAI,aAAqB,CAAC;IAC1B,IAAI,CAAC;QACH,aAAa,GAAG,YAAY,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACjD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,gBAAgB,EAAE,CAAC;IAC/C,CAAC;IACD,6BAA6B;IAC7B,IAAI,SAAS,CAAC,QAAQ,EAAE,aAAa,CAAC,EAAE,CAAC;QACvC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,mBAAmB,EAAE,CAAC;IAClD,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,aAAa,EAAE,CAAC;AAC/C,CAAC;AAED;;;GAGG;AACH,SAAS,SAAS,CAAC,IAAY,EAAE,MAAc;IAC7C,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACxC,OAAO,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;AACtD,CAAC;AAcD;;GAEG;AACH,MAAM,UAAU,UAAU,CAAC,OAAe;IACxC,IAAI,OAAO,KAAK,EAAE;QAAE,OAAO,EAAE,CAAC;IAC9B,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IACrC,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,KAAK,EAAE;QAAE,KAAK,CAAC,GAAG,EAAE,CAAC;IACpE,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU,CACxB,OAAe,EACf,OAAyE,EAAE;IAE3E,MAAM,QAAQ,GAAG,UAAU,CAAC,OAAO,CAAC,CAAC;IACrC,MAAM,UAAU,GAAG,QAAQ,CAAC,MAAM,CAAC;IACnC,IAAI,UAAU,KAAK,CAAC,EAAE,CAAC;QACrB,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,SAAS,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;IAClF,CAAC;IACD,MAAM,MAAM,GAAG,IAAI,CAAC,aAAa,IAAI,mBAAmB,CAAC;IACzD,IAAI,KAAa,CAAC;IAClB,IAAI,GAAW,CAAC;IAChB,IAAI,SAAS,GAAG,KAAK,CAAC;IACtB,IAAI,IAAI,CAAC,SAAS,KAAK,SAAS,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QAC/D,KAAK,GAAG,CAAC,CAAC;QACV,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;QACnC,SAAS,GAAG,UAAU,GAAG,MAAM,CAAC;IAClC,CAAC;SAAM,CAAC;QACN,KAAK,GAAG,IAAI,CAAC,SAAS,IAAI,CAAC,CAAC;QAC5B,GAAG,GAAG,IAAI,CAAC,OAAO,IAAI,UAAU,CAAC;IACnC,CAAC;IACD,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC;IAC7D,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC;IAC7D,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,EAAE,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,KAAK,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IACjF,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,UAAU,EAAE,SAAS,EAAE,CAAC;AAC1E,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,sBAAsB,CAAC,IAAY;IACjD,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;AACzD,CAAC;AAED,4BAA4B;AAC5B,MAAM,UAAU,QAAQ,CAAC,GAAW;IAClC,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;IACnD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC3B,IAAI,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;IAChC,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,+DAA+D;AAC/D,mBAAmB;AACnB,+DAA+D;AAE/D,gEAAgE;AAChE,MAAM,UAAU,QAAQ,CACtB,KAAyB,EACzB,GAAW,EACX,GAAW,EACX,QAAgB;IAEhB,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC;QACrD,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAC5C,CAAC;IACD,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAC9B,IAAI,GAAG,GAAG,GAAG;QAAE,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IACpD,IAAI,GAAG,GAAG,GAAG;QAAE,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IACpD,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,KAAK,KAAK,EAAE,CAAC;AAChD,CAAC;AAiBD,iCAAiC;AACjC,SAAS,YAAY,CAAC,CAAS;IAC7B,OAAO,CAAC,CAAC,OAAO,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAC;AAClD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,OAAe;IAC1C,MAAM,eAAe,GAAG,qBAAqB,CAAC,CAAC,QAAQ;IACvD,MAAM,WAAW,GAAG,0BAA0B,CAAC,CAAC,kBAAkB;IAClE,IAAI,eAAe,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC;QAAE,OAAO,IAAI,CAAC;IAC5E,IAAI,yBAAyB,CAAC,IAAI,CAAC,OAAO,CAAC;QAAE,OAAO,IAAI,CAAC,CAAC,QAAQ;IAClE,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CACzB,OAAe,EACf,OAAe,EACf,OAA0E,EAAE;IAE5E,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,eAAe,EAAE,CAAC;IAChD,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,GAAG,kBAAkB,EAAE,CAAC;QACxC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,iBAAiB,kBAAkB,GAAG,EAAE,CAAC;IACvE,CAAC;IACD,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,KAAK,CAAC;IACtC,MAAM,YAAY,GAAG,QAAQ,CAAC,IAAI,CAAC,YAAY,IAAI,CAAC,EAAE,CAAC,EAAE,iBAAiB,EAAE,CAAC,CAAC,CAAC;IAC/E,MAAM,UAAU,GAAG,QAAQ,CAAC,IAAI,CAAC,UAAU,IAAI,mBAAmB,EAAE,CAAC,EAAE,eAAe,EAAE,mBAAmB,CAAC,CAAC;IAC7G,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,IAAI,UAAU,CAAC,OAAO;QAAE,QAAQ,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC;IAC5D,IAAI,YAAY,CAAC,OAAO;QAAE,QAAQ,CAAC,IAAI,CAAC,sBAAsB,CAAC,CAAC;IAEhE,IAAI,KAAa,CAAC;IAClB,IAAI,OAAO,EAAE,CAAC;QACZ,IAAI,YAAY,CAAC,OAAO,CAAC,EAAE,CAAC;YAC1B,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,iCAAiC,EAAE,CAAC;QAClE,CAAC;QACD,8CAA8C;QAC9C,IAAI,MAAM,CAAC,UAAU,CAAC,OAAO,EAAE,OAAO,CAAC,GAAG,uBAAuB,EAAE,CAAC;YAClE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,uBAAuB,yCAAyC,EAAE,CAAC;QACxG,CAAC;QACD,IAAI,CAAC;YACH,KAAK,GAAG,IAAI,MAAM,CAAC,OAAO,CAAC,CAAC;QAC9B,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;QACvC,CAAC;IACH,CAAC;SAAM,CAAC;QACN,KAAK,GAAG,IAAI,MAAM,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC;IAC5C,CAAC;IAED,MAAM,KAAK,GAAG,UAAU,CAAC,OAAO,CAAC,CAAC;IAClC,MAAM,OAAO,GAAkB,EAAE,CAAC;IAClC,IAAI,YAAY,GAAG,CAAC,CAAC;IACrB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,IAAI,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAE,CAAC,EAAE,CAAC;YAC1B,YAAY,EAAE,CAAC;YACf,IAAI,OAAO,CAAC,MAAM,GAAG,UAAU,CAAC,KAAK,EAAE,CAAC;gBACtC,OAAO,CAAC,IAAI,CAAC;oBACX,IAAI,EAAE,CAAC,GAAG,CAAC;oBACX,IAAI,EAAE,KAAK,CAAC,CAAC,CAAE;oBACf,MAAM,EAAE,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,GAAG,YAAY,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;oBAC3D,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;iBAC9E,CAAC,CAAC;YACL,CAAC;QACH,CAAC;IACH,CAAC;IACD,IAAI,YAAY,GAAG,OAAO,CAAC,MAAM;QAAE,QAAQ,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;IACtE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,OAAO,CAAC,MAAM,EAAE,QAAQ,EAAE,CAAC;AACxF,CAAC;AAYD;;;GAGG;AACH,MAAM,UAAU,eAAe,CAC7B,MAAc,EACd,OAA0E,EAAE;IAE5E,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC,EAAE,CAAC,EAAE,aAAa,EAAE,CAAC,CAAC,CAAC;IAC7D,MAAM,cAAc,GAAG,IAAI,CAAC,cAAc,IAAI,KAAK,CAAC;IACpD,6CAA6C;IAC7C,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,IAAI,IAAI,CAAC,UAAU,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,eAAe,CAAC;IAC9F,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,IAAI,KAAK,CAAC,OAAO;QAAE,QAAQ,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;IAClD,MAAM,OAAO,GAAe,EAAE,CAAC;IAC/B,IAAI,SAAS,GAAG,KAAK,CAAC;IAEtB,MAAM,IAAI,GAAG,CAAC,GAAW,EAAE,GAAW,EAAE,KAAa,EAAQ,EAAE;QAC7D,IAAI,SAAS;YAAE,OAAO;QACtB,IAAI,OAAiB,CAAC;QACtB,IAAI,CAAC;YACH,OAAO,GAAG,WAAW,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;QACtD,CAAC;QAAC,MAAM,CAAC;YACP,OAAO;QACT,CAAC;QACD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;QACrD,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;YACxB,IAAI,CAAC,cAAc,IAAI,CAAC,CAAC,IAAI,KAAK,MAAM;gBAAE,SAAS;YACnD,IAAI,OAAO,CAAC,MAAM,IAAI,UAAU,EAAE,CAAC;gBACjC,SAAS,GAAG,IAAI,CAAC;gBACjB,OAAO;YACT,CAAC;YACD,MAAM,OAAO,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;YAClD,MAAM,IAAI,GAAqB,CAAC,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC;YACjG,IAAI,IAAI,GAAkB,IAAI,CAAC;YAC/B,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;gBACpB,IAAI,CAAC;oBACH,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;gBAC/C,CAAC;gBAAC,MAAM,CAAC;oBACP,IAAI,GAAG,IAAI,CAAC;gBACd,CAAC;YACH,CAAC;YACD,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;YAC5C,IAAI,IAAI,KAAK,KAAK,IAAI,KAAK,GAAG,KAAK,CAAC,KAAK,EAAE,CAAC;gBAC1C,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;YACnD,CAAC;QACH,CAAC;IACH,CAAC,CAAC;IACF,IAAI,CAAC,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;IACpB,IAAI,SAAS;QAAE,QAAQ,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;IAClD,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC;AAC/B,CAAC;AAED,+DAA+D;AAC/D,kDAAkD;AAClD,+DAA+D;AAE/D,6EAA6E;AAC7E,MAAM,UAAU,gBAAgB,CAC9B,QAA2D,EAC3D,IAA6B;IAE7B,IAAI,QAAQ,KAAK,WAAW,EAAE,CAAC;QAC7B,MAAM,SAAS,GAAI,IAAI,CAAC,WAAW,CAAwB,IAAI,CAAC,CAAC;QACjE,MAAM,OAAO,GAAI,IAAI,CAAC,SAAS,CAAwB,IAAI,CAAC,CAAC;QAC7D,MAAM,UAAU,GAAI,IAAI,CAAC,YAAY,CAAwB,IAAI,CAAC,CAAC;QACnE,IAAI,IAAI,CAAC,WAAW,CAAC,KAAK,IAAI,EAAE,CAAC;YAC/B,OAAO,QAAQ,OAAO,IAAI,UAAU,8DAA8D,CAAC;QACrG,CAAC;QACD,OAAO,QAAQ,SAAS,IAAI,OAAO,IAAI,UAAU,qCAAqC,CAAC;IACzF,CAAC;IACD,IAAI,QAAQ,KAAK,gBAAgB,EAAE,CAAC;QAClC,MAAM,KAAK,GAAI,IAAI,CAAC,cAAc,CAAwB,IAAI,CAAC,CAAC;QAChE,IAAI,KAAK,KAAK,CAAC,EAAE,CAAC;YAChB,OAAO,uCAAuC,CAAC;QACjD,CAAC;QACD,OAAO,MAAM,KAAK,mCAAmC,CAAC;IACxD,CAAC;IACD,MAAM,KAAK,GAAI,IAAI,CAAC,YAAY,CAAwB,IAAI,CAAC,CAAC;IAC9D,OAAO,OAAO,KAAK,wDAAwD,CAAC;AAC9E,CAAC"}

package/dist/mcp/lib/response-helpers.d.ts

@@ -0,0 +1,67 @@
+/**
+ * F170c — MCP response 共享 helper（纯函数模块）
+ *
+ * 用于 handleImpact / handleContext / handleDetectChanges 的 enrichment 计算。
+ * 所有函数为纯函数（无 side effect，无 LLM 调用，同步执行）；safeStderrLog 是 IO 但吞掉自身异常。
+ */
+/** TopImpacted 排名条目 */
+export interface TopImpacted {
+    id: string;
+    score: number;
+}
+/** TopRelevantCaller 排名条目 */
+export interface TopRelevantCaller {
+    id: string;
+    confidence: number;
+    score: number;
+}
+/** impact tool 新增字段（producer success path 总产出） */
+export interface ImpactEnrichment {
+    topImpacted?: TopImpacted[];
+    nextStepHint?: string;
+    _enrichmentDegraded?: true;
+}
+/** detect_changes tool 新增字段 */
+export interface DetectChangesEnrichment {
+    riskTier?: 'low' | 'medium' | 'high';
+    topImpacted?: TopImpacted[];
+    nextStepHint?: string;
+    _enrichmentDegraded?: true;
+}
+/** context tool 新增字段 */
+export interface ContextEnrichment {
+    topRelevantCallers?: TopRelevantCaller[];
+    nextStepHint?: string;
+    _enrichmentDegraded?: true;
+}
+/**
+ * 安全 stderr 日志，吞掉 write 自身异常（响应 codex C-6：避免 enrichment failure 升级为 handler error）。
+ */
+export declare function safeStderrLog(message: string): void;
+/**
+ * 从 BFS affected 列表构建 topImpacted 排名。
+ * 按 score = 1/depth 降序、confidence 降序、id 字母升序（stable sort），取前 maxItems 项。
+ * @pure 无副作用，同步执行
+ */
+export declare function buildTopImpactedRanking(affected: ReadonlyArray<{
+    id: string;
+    depth: number;
+    confidence?: number;
+}>, maxItems: number): TopImpacted[];
+/**
+ * 生成 nextStepHint 引导文本（中文）。
+ * success 路径返回非空字符串（≥ 5 字符）；degraded 路径固定返回 ""。
+ * @pure 无副作用，同步执行
+ */
+export declare function generateNextStepHint(toolName: 'impact' | 'detect_changes' | 'context', responseData: Record<string, unknown>, path: 'success' | 'degraded'): string;
+/**
+ * 从 context callers 列表构建 topRelevantCallers 排名。
+ * 按 confidence 降序（同分按 id 字母升序），取前 maxItems 项。
+ * @pure 无副作用，同步执行
+ */
+export declare function buildTopRelevantCallers(callers: ReadonlyArray<{
+    id: string;
+    confidence: number;
+    relation?: string;
+}>, maxItems: number): TopRelevantCaller[];
+//# sourceMappingURL=response-helpers.d.ts.map

package/dist/mcp/lib/response-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"response-helpers.d.ts","sourceRoot":"","sources":["../../../src/mcp/lib/response-helpers.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,uBAAuB;AACvB,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;CACf;AAED,6BAA6B;AAC7B,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,kDAAkD;AAClD,MAAM,WAAW,gBAAgB;IAC/B,WAAW,CAAC,EAAE,WAAW,EAAE,CAAC;IAC5B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,mBAAmB,CAAC,EAAE,IAAI,CAAC;CAC5B;AAED,+BAA+B;AAC/B,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;IACrC,WAAW,CAAC,EAAE,WAAW,EAAE,CAAC;IAC5B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,mBAAmB,CAAC,EAAE,IAAI,CAAC;CAC5B;AAED,wBAAwB;AACxB,MAAM,WAAW,iBAAiB;IAChC,kBAAkB,CAAC,EAAE,iBAAiB,EAAE,CAAC;IACzC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,mBAAmB,CAAC,EAAE,IAAI,CAAC;CAC5B;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAMnD;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,aAAa,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,EAC3E,QAAQ,EAAE,MAAM,GACf,WAAW,EAAE,CAef;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,QAAQ,GAAG,gBAAgB,GAAG,SAAS,EACjD,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACrC,IAAI,EAAE,SAAS,GAAG,UAAU,GAC3B,MAAM,CAwCR;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,aAAa,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,EAC7E,QAAQ,EAAE,MAAM,GACf,iBAAiB,EAAE,CASrB"}

package/dist/mcp/lib/response-helpers.js

@@ -0,0 +1,103 @@
+/**
+ * F170c — MCP response 共享 helper（纯函数模块）
+ *
+ * 用于 handleImpact / handleContext / handleDetectChanges 的 enrichment 计算。
+ * 所有函数为纯函数（无 side effect，无 LLM 调用，同步执行）；safeStderrLog 是 IO 但吞掉自身异常。
+ */
+/**
+ * 安全 stderr 日志，吞掉 write 自身异常（响应 codex C-6：避免 enrichment failure 升级为 handler error）。
+ */
+export function safeStderrLog(message) {
+    try {
+        process.stderr.write(message);
+    }
+    catch {
+        // 静默吞掉 — stderr 不可用时不应进一步抛错破坏 handler success path
+    }
+}
+/**
+ * 从 BFS affected 列表构建 topImpacted 排名。
+ * 按 score = 1/depth 降序、confidence 降序、id 字母升序（stable sort），取前 maxItems 项。
+ * @pure 无副作用，同步执行
+ */
+export function buildTopImpactedRanking(affected, maxItems) {
+    if (maxItems <= 0)
+        return [];
+    return affected
+        .map((a) => ({
+        id: a.id,
+        score: 1 / a.depth,
+        _confidence: a.confidence ?? 0,
+    }))
+        .sort((x, y) => {
+        if (y.score !== x.score)
+            return y.score - x.score;
+        if (y._confidence !== x._confidence)
+            return y._confidence - x._confidence;
+        return x.id.localeCompare(y.id);
+    })
+        .slice(0, maxItems)
+        .map(({ id, score }) => ({ id, score }));
+}
+/**
+ * 生成 nextStepHint 引导文本（中文）。
+ * success 路径返回非空字符串（≥ 5 字符）；degraded 路径固定返回 ""。
+ * @pure 无副作用，同步执行
+ */
+export function generateNextStepHint(toolName, responseData, path) {
+    if (path === 'degraded')
+        return '';
+    if (toolName === 'impact') {
+        const topImpacted = responseData['topImpacted'] ?? [];
+        const affected = responseData['affected'] ?? [];
+        const top0 = topImpacted[0];
+        // topImpacted 非空时优先按其内容生成 hint（包含 top id）
+        if (top0 !== undefined) {
+            if (affected.length === 1) {
+                return `仅 1 个直接调用方 ${top0.id}，建议直接调 context 查看其上下文`;
+            }
+            return `建议接下来调 context for ${top0.id}（影响 score 最高，了解其调用链上下文）`;
+        }
+        // topImpacted 为空时根据 affected 数量决定
+        if (affected.length === 0) {
+            return '受影响范围为空，建议检查 symbol ID 是否正确，或改用 context 查看调用方';
+        }
+        return '建议查看 affected 列表中的受影响 symbol';
+    }
+    if (toolName === 'detect_changes') {
+        const topImpacted = responseData['topImpacted'] ?? [];
+        const riskTier = responseData['riskTier'] ?? 'low';
+        const totalChanged = responseData['totalChanged'] ?? 0;
+        const top0 = topImpacted[0];
+        if (top0 === undefined) {
+            return `检测到 ${totalChanged} 个改动 symbol，暂无上游调用方，建议调 context 查看改动 symbol 的依赖`;
+        }
+        return `检测到 ${totalChanged} 个改动 symbol，风险等级 ${riskTier}，建议调 impact for ${top0.id} 评估影响范围`;
+    }
+    // context
+    const definition = responseData['definition'];
+    const callers = responseData['callers'] ?? [];
+    const defId = definition?.id ?? '<unknown>';
+    if (callers.length === 0) {
+        return `${defId} 无已知调用方，可能为顶层入口，建议直接查看 callees 确认依赖`;
+    }
+    return `若将修改 ${defId}，建议调 impact for ${defId} 评估受影响的上游调用链`;
+}
+/**
+ * 从 context callers 列表构建 topRelevantCallers 排名。
+ * 按 confidence 降序（同分按 id 字母升序），取前 maxItems 项。
+ * @pure 无副作用，同步执行
+ */
+export function buildTopRelevantCallers(callers, maxItems) {
+    if (maxItems <= 0)
+        return [];
+    return callers
+        .map((c) => ({ id: c.id, confidence: c.confidence, score: c.confidence }))
+        .sort((x, y) => {
+        if (y.score !== x.score)
+            return y.score - x.score;
+        return x.id.localeCompare(y.id);
+    })
+        .slice(0, maxItems);
+}
+//# sourceMappingURL=response-helpers.js.map

package/dist/mcp/lib/response-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"response-helpers.js","sourceRoot":"","sources":["../../../src/mcp/lib/response-helpers.ts"],"names":[],"mappings":"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"}

package/dist/mcp/lib/telemetry.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Feature 158 — MCP Telemetry（从 agent-context-tools.ts 抽出，Feature 171）
+ *
+ * 抽到独立模块的动机（Feature 171 Codex TELEMETRY-COUPLING）：
+ *   file-nav-tools.ts 需复用 recordAndReturn，若从 agent-context-tools.ts import
+ *   会把整个 graph 查询依赖图拉进来。抽到本轻量模块后 file-nav 只依赖 tool-response + telemetry。
+ *
+ * agent-context-tools.ts 保留向后兼容 re-export（既有 telemetry.test.ts 从该路径 import）。
+ */
+import { type ToolResult } from './tool-response.js';
+/**
+ * Telemetry entry — 单次 handler 调用的可观测数据，按行写入 JSONL。
+ * 由评测脚本通过 SPECTRA_MCP_TELEMETRY_PATH 注入路径，SPECTRA_MCP_RUN_ID 标识 run。
+ */
+export interface TelemetryEntry {
+    ts: string;
+    toolName: string;
+    requestSize: number;
+    responseSize: number;
+    durationMs: number;
+    runId: string;
+    errorCode?: string;
+    responseSummary?: Record<string, number>;
+    responseSamples?: {
+        symbols?: string[];
+        files?: string[];
+    };
+}
+/**
+ * 写入 telemetry JSONL —— 静默降级：
+ *   - env 未设置 → no-op
+ *   - 写入失败 → 静默吞，不影响 MCP response
+ */
+export declare function writeTelemetry(entry: TelemetryEntry): void;
+/**
+ * 从 ToolResult 中提取 errorCode（仅 isError=true 时存在）。
+ * 解析失败时返回 undefined（telemetry 字段缺省）。
+ */
+export declare function extractErrorCode(result: ToolResult): string | undefined;
+/**
+ * Wrapper：记录 handler 调用 telemetry 后返回原 result。
+ * 包裹所有 return 路径（含 buildErrorResponse 早 return）。
+ */
+export declare function recordAndReturn(toolName: string, startTimeMs: number, requestSize: number, result: ToolResult, responseSummary?: Record<string, number>, responseSamples?: {
+    symbols?: string[];
+    files?: string[];
+}): ToolResult;
+/**
+ * Feature 177 — 注册层 telemetry 装饰器。
+ *
+ * 把 F158 telemetry 采样从"handler 内部自调 recordAndReturn"推广到**注册层**，
+ * 用于无富采样需求（responseSummary/responseSamples）的工具（graph 6 + server 5 共 11 个）。
+ *
+ * 职责：
+ *   1. 入口记 start / requestSize
+ *   2. 出口经 recordAndReturn 透传（含 errorCode 提取）
+ *   3. 顶层未预期异常 → 脱敏 internal-error 安全网（不泄漏 err.message/stack，spec C-4）
+ *
+ * 不变量（spec AD-1 双源分区）：被本装饰器包裹的工具**不得**在 handler 内再调 recordAndReturn；
+ * 已在 handler 内自采样的工具（agent-context / file-nav）**不得**被本装饰器包裹。
+ * → 每个到达 handler 的调用恰写 1 行 telemetry（锁死双发射 EC-1）。
+ *
+ * 范围（spec EC-10）：MCP SDK 在 handler 前的 schema 校验失败走 SDK 自身错误，
+ * 不进入本装饰器，不在 F177 telemetry 覆盖范围内。
+ *
+ * 不接受泛型（YAGNI）：args 用 unknown；SDK 传入的 extra 形参被忽略（17 工具均不用 extra）。
+ */
+export declare function withTelemetry(toolName: string, handler: (args: unknown) => Promise<ToolResult> | ToolResult): (args: unknown) => Promise<ToolResult>;
+//# sourceMappingURL=telemetry.d.ts.map

package/dist/mcp/lib/telemetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.d.ts","sourceRoot":"","sources":["../../../src/mcp/lib/telemetry.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAsB,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAEzE;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzC,eAAe,CAAC,EAAE;QAChB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;QACnB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;KAClB,CAAC;CACH;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI,CAQ1D;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,GAAG,SAAS,CAUvE;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,UAAU,EAClB,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACxC,eAAe,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,GACzD,UAAU,CAqBZ;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC,UAAU,CAAC,GAAG,UAAU,GAC3D,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC,UAAU,CAAC,CAsBxC"}