spectra-cli 4.2.0 → 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":"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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"}

package/dist/mcp/lib/telemetry.js

@@ -0,0 +1,113 @@
+/**
+ * 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 { appendFileSync } from 'node:fs';
+import { buildErrorResponse } from './tool-response.js';
+/**
+ * 写入 telemetry JSONL —— 静默降级：
+ *   - env 未设置 → no-op
+ *   - 写入失败 → 静默吞，不影响 MCP response
+ */
+export function writeTelemetry(entry) {
+    const telPath = process.env['SPECTRA_MCP_TELEMETRY_PATH'];
+    if (telPath === undefined || telPath.length === 0)
+        return;
+    try {
+        appendFileSync(telPath, JSON.stringify(entry) + '\n', 'utf-8');
+    }
+    catch {
+        // FR-G-002: silent degrade — 写入失败时不抛异常，不影响 handler 返回
+    }
+}
+/**
+ * 从 ToolResult 中提取 errorCode（仅 isError=true 时存在）。
+ * 解析失败时返回 undefined（telemetry 字段缺省）。
+ */
+export function extractErrorCode(result) {
+    if (result.isError !== true)
+        return undefined;
+    const text = result.content?.[0]?.text;
+    if (typeof text !== 'string')
+        return undefined;
+    try {
+        const parsed = JSON.parse(text);
+        return typeof parsed.code === 'string' ? parsed.code : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Wrapper：记录 handler 调用 telemetry 后返回原 result。
+ * 包裹所有 return 路径（含 buildErrorResponse 早 return）。
+ */
+export function recordAndReturn(toolName, startTimeMs, requestSize, result, responseSummary, responseSamples) {
+    const responseText = result.content?.[0]?.text ?? '';
+    const responseSize = typeof responseText === 'string' ? Buffer.byteLength(responseText, 'utf-8') : 0;
+    const entry = {
+        ts: new Date().toISOString(),
+        toolName,
+        requestSize,
+        responseSize,
+        durationMs: Date.now() - startTimeMs,
+        runId: process.env['SPECTRA_MCP_RUN_ID'] ?? 'unknown',
+    };
+    const errorCode = extractErrorCode(result);
+    if (errorCode !== undefined)
+        entry.errorCode = errorCode;
+    if (responseSummary !== undefined && errorCode === undefined) {
+        entry.responseSummary = responseSummary;
+    }
+    if (responseSamples !== undefined && errorCode === undefined) {
+        entry.responseSamples = responseSamples;
+    }
+    writeTelemetry(entry);
+    return result;
+}
+/**
+ * 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 function withTelemetry(toolName, handler) {
+    return async (args) => {
+        const startTimeMs = Date.now();
+        let requestSize = 0;
+        try {
+            requestSize = JSON.stringify(args).length;
+        }
+        catch {
+            // 循环引用等无法序列化 → requestSize 记 0
+        }
+        try {
+            const result = await handler(args);
+            return recordAndReturn(toolName, startTimeMs, requestSize, result);
+        }
+        catch {
+            // 顶层未预期异常 → 脱敏 internal-error（不回传 err.message/stack）
+            return recordAndReturn(toolName, startTimeMs, requestSize, buildErrorResponse('internal-error', `${toolName} 内部错误`));
+        }
+    };
+}
+//# sourceMappingURL=telemetry.js.map

package/dist/mcp/lib/telemetry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.js","sourceRoot":"","sources":["../../../src/mcp/lib/telemetry.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,EAAE,kBAAkB,EAAmB,MAAM,oBAAoB,CAAC;AAsBzE;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,KAAqB;IAClD,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,4BAA4B,CAAC,CAAC;IAC1D,IAAI,OAAO,KAAK,SAAS,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO;IAC1D,IAAI,CAAC;QACH,cAAc,CAAC,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,IAAI,EAAE,OAAO,CAAC,CAAC;IACjE,CAAC;IAAC,MAAM,CAAC;QACP,sDAAsD;IACxD,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAkB;IACjD,IAAI,MAAM,CAAC,OAAO,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IAC9C,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC;IACvC,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IAC/C,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAuB,CAAC;QACtD,OAAO,OAAO,MAAM,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;IACnE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAC7B,QAAgB,EAChB,WAAmB,EACnB,WAAmB,EACnB,MAAkB,EAClB,eAAwC,EACxC,eAA0D;IAE1D,MAAM,YAAY,GAAG,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,IAAI,EAAE,CAAC;IACrD,MAAM,YAAY,GAAG,OAAO,YAAY,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACrG,MAAM,KAAK,GAAmB;QAC5B,EAAE,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QAC5B,QAAQ;QACR,WAAW;QACX,YAAY;QACZ,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,WAAW;QACpC,KAAK,EAAE,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC,IAAI,SAAS;KACtD,CAAC;IACF,MAAM,SAAS,GAAG,gBAAgB,CAAC,MAAM,CAAC,CAAC;IAC3C,IAAI,SAAS,KAAK,SAAS;QAAE,KAAK,CAAC,SAAS,GAAG,SAAS,CAAC;IACzD,IAAI,eAAe,KAAK,SAAS,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;QAC7D,KAAK,CAAC,eAAe,GAAG,eAAe,CAAC;IAC1C,CAAC;IACD,IAAI,eAAe,KAAK,SAAS,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;QAC7D,KAAK,CAAC,eAAe,GAAG,eAAe,CAAC;IAC1C,CAAC;IACD,cAAc,CAAC,KAAK,CAAC,CAAC;IACtB,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,aAAa,CAC3B,QAAgB,EAChB,OAA4D;IAE5D,OAAO,KAAK,EAAE,IAAa,EAAuB,EAAE;QAClD,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC/B,IAAI,WAAW,GAAG,CAAC,CAAC;QACpB,IAAI,CAAC;YACH,WAAW,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC;QAC5C,CAAC;QAAC,MAAM,CAAC;YACP,+BAA+B;QACjC,CAAC;QACD,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;YACnC,OAAO,eAAe,CAAC,QAAQ,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,CAAC,CAAC;QACrE,CAAC;QAAC,MAAM,CAAC;YACP,qDAAqD;YACrD,OAAO,eAAe,CACpB,QAAQ,EACR,WAAW,EACX,WAAW,EACX,kBAAkB,CAAC,gBAAgB,EAAE,GAAG,QAAQ,OAAO,CAAC,CACzD,CAAC;QACJ,CAAC;IACH,CAAC,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,46 @@
+/**
+ * Feature 171 — MCP 共享响应原语（tool-response）
+ *
+ * 从 agent-context-tools.ts 抽出的共享层，解决 Feature 171 Codex C-4：
+ *   ToolResult / ErrorCode / buildErrorResponse / buildSuccessResponse / PAYLOAD_CAP_BYTES
+ *   原为 agent-context-tools.ts 私有符号，file-nav-tools.ts 无法复用。
+ * 抽到本模块后 agent-context-tools 与 file-nav 双向导入（去重，非污染）。
+ *
+ * ErrorCode union 在既有 9 码基础上新增 Feature 171 的 3 码：
+ *   path-outside-root / binary-file / file-not-found
+ */
+/** 统一错误码（Feature 155 既有 9 码 + Feature 171 新增 3 码） */
+export type ErrorCode = 'graph-not-built' | 'symbol-not-found' | 'invalid-symbol-id' | 'invalid-input' | 'invalid-diff' | 'payload-too-large' | 'git-spawn-failed' | 'git-timeout' | 'internal-error' | 'path-outside-root' | 'binary-file' | 'file-not-found' | 'graph-query-failed' | 'graph-format-stale';
+/** MCP tool 统一响应 envelope */
+export interface ToolResult {
+    [key: string]: unknown;
+    content: Array<{
+        type: 'text';
+        text: string;
+        [key: string]: unknown;
+    }>;
+    isError?: true;
+}
+/**
+ * 构造错误响应 envelope。
+ * 调用方负责脱敏：message/hint/context 不得包含绝对路径、stack、raw errno path
+ * （Feature 171 FR-014）。
+ */
+export declare function buildErrorResponse(code: ErrorCode, message: string, hint?: string, context?: Record<string, unknown>): ToolResult;
+/** payload 字节上限：超限时截断可截断数组并加 payload-truncated warning */
+export declare const PAYLOAD_CAP_BYTES = 1000000;
+/**
+ * 构造成功响应 envelope。
+ * 当序列化超 PAYLOAD_CAP_BYTES 且提供了 truncatableArrayKeys 时，
+ * 按比例收缩这些数组并追加 warnings 含 'payload-truncated'。
+ *
+ * 注意：本函数始终返回 success（不返回 payload-too-large）。
+ * 若收缩后仍超 cap，由调用方（handler）复核 byteLength 后决定是否改返 payload-too-large。
+ */
+export declare function buildSuccessResponse(data: Record<string, unknown>, truncatableArrayKeys?: string[], warningsKey?: string): ToolResult;
+/**
+ * 复核 ToolResult 的序列化字节是否仍超 cap（Feature 171 FR-021）。
+ * handler 在 buildSuccessResponse 收缩后调用本函数，仍超则改返 payload-too-large。
+ */
+export declare function exceedsPayloadCap(result: ToolResult): boolean;
+//# sourceMappingURL=tool-response.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tool-response.d.ts","sourceRoot":"","sources":["../../../src/mcp/lib/tool-response.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,qDAAqD;AACrD,MAAM,MAAM,SAAS,GAEjB,iBAAiB,GACjB,kBAAkB,GAClB,mBAAmB,GACnB,eAAe,GACf,cAAc,GACd,mBAAmB,GACnB,kBAAkB,GAClB,aAAa,GACb,gBAAgB,GAEhB,mBAAmB,GACnB,aAAa,GACb,gBAAgB,GAGhB,oBAAoB,GAGpB,oBAAoB,CAAC;AAEzB,6BAA6B;AAC7B,MAAM,WAAW,UAAU;IACzB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IACvB,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC,CAAC;IACvE,OAAO,CAAC,EAAE,IAAI,CAAC;CAChB;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,SAAS,EACf,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,UAAU,CAQZ;AAED,0DAA0D;AAC1D,eAAO,MAAM,iBAAiB,UAAY,CAAC;AAE3C;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,oBAAoB,GAAE,MAAM,EAAO,EACnC,WAAW,GAAE,MAAmB,GAC/B,UAAU,CAkCZ;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAG7D"}

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

@@ -0,0 +1,83 @@
+/**
+ * Feature 171 — MCP 共享响应原语（tool-response）
+ *
+ * 从 agent-context-tools.ts 抽出的共享层，解决 Feature 171 Codex C-4：
+ *   ToolResult / ErrorCode / buildErrorResponse / buildSuccessResponse / PAYLOAD_CAP_BYTES
+ *   原为 agent-context-tools.ts 私有符号，file-nav-tools.ts 无法复用。
+ * 抽到本模块后 agent-context-tools 与 file-nav 双向导入（去重，非污染）。
+ *
+ * ErrorCode union 在既有 9 码基础上新增 Feature 171 的 3 码：
+ *   path-outside-root / binary-file / file-not-found
+ */
+/**
+ * 构造错误响应 envelope。
+ * 调用方负责脱敏：message/hint/context 不得包含绝对路径、stack、raw errno path
+ * （Feature 171 FR-014）。
+ */
+export function buildErrorResponse(code, message, hint, context) {
+    const payload = { code, message };
+    if (hint !== undefined)
+        payload['hint'] = hint;
+    if (context !== undefined)
+        payload['context'] = context;
+    return {
+        isError: true,
+        content: [{ type: 'text', text: JSON.stringify(payload) }],
+    };
+}
+/** payload 字节上限：超限时截断可截断数组并加 payload-truncated warning */
+export const PAYLOAD_CAP_BYTES = 1_000_000;
+/**
+ * 构造成功响应 envelope。
+ * 当序列化超 PAYLOAD_CAP_BYTES 且提供了 truncatableArrayKeys 时，
+ * 按比例收缩这些数组并追加 warnings 含 'payload-truncated'。
+ *
+ * 注意：本函数始终返回 success（不返回 payload-too-large）。
+ * 若收缩后仍超 cap，由调用方（handler）复核 byteLength 后决定是否改返 payload-too-large。
+ */
+export function buildSuccessResponse(data, truncatableArrayKeys = [], warningsKey = 'warnings') {
+    let text = JSON.stringify(data);
+    let bytes = Buffer.byteLength(text, 'utf-8');
+    if (bytes > PAYLOAD_CAP_BYTES && truncatableArrayKeys.length > 0) {
+        let truncated = false;
+        let safety = 0;
+        while (bytes > PAYLOAD_CAP_BYTES && safety < 8) {
+            safety++;
+            let progressed = false;
+            for (const key of truncatableArrayKeys) {
+                const arr = data[key];
+                if (!Array.isArray(arr) || arr.length === 0)
+                    continue;
+                // 按比例 0.7 收缩，至少减 1
+                const ratio = PAYLOAD_CAP_BYTES / bytes;
+                const newLen = Math.max(0, Math.min(arr.length - 1, Math.floor(arr.length * ratio * 0.7)));
+                if (newLen < arr.length) {
+                    data[key] = arr.slice(0, newLen);
+                    truncated = true;
+                    progressed = true;
+                }
+            }
+            if (!progressed)
+                break;
+            text = JSON.stringify(data);
+            bytes = Buffer.byteLength(text, 'utf-8');
+        }
+        if (truncated) {
+            const warnings = data[warningsKey] ?? [];
+            if (!warnings.includes('payload-truncated')) {
+                data[warningsKey] = [...warnings, 'payload-truncated'];
+                text = JSON.stringify(data);
+            }
+        }
+    }
+    return { content: [{ type: 'text', text }] };
+}
+/**
+ * 复核 ToolResult 的序列化字节是否仍超 cap（Feature 171 FR-021）。
+ * handler 在 buildSuccessResponse 收缩后调用本函数，仍超则改返 payload-too-large。
+ */
+export function exceedsPayloadCap(result) {
+    const text = result.content?.[0]?.text ?? '';
+    return Buffer.byteLength(text, 'utf-8') > PAYLOAD_CAP_BYTES;
+}
+//# sourceMappingURL=tool-response.js.map

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

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