mcp-probe-kit 3.0.12 → 3.0.13

package/build/lib/gitnexus-bridge.js

@@ -61,9 +61,9 @@ function isBridgeEnabled() {
     }
     return !/^(0|false|no|off)$/i.test(raw.trim());
 }
-function splitArgs(raw) {
+function splitArgs(raw, fallback = DEFAULT_GITNEXUS_ARGS) {
     if (!raw) {
-        return [...DEFAULT_GITNEXUS_ARGS];
+        return [...fallback];
     }
     return raw
         .trim()
@@ -119,14 +119,14 @@ function parseAvailableReposFromError(text) {
         .map((item) => item.trim())
         .filter(Boolean);
 }
-function resolveBridgeCommand() {
-    const command = (process.env.MCP_GITNEXUS_COMMAND || "npx").trim() || "npx";
-    const args = splitArgs(process.env.MCP_GITNEXUS_ARGS);
-    return resolveSpawnCommand(command, args);
+function isGitNexusCliCommand(command) {
+    const normalized = path.basename((command || "").trim()).toLowerCase();
+    return normalized === "gitnexus"
+        || normalized === "gitnexus.cmd"
+        || normalized === "gitnexus.exe"
+        || normalized === "gitnexus.bat";
 }
-function resolveGitNexusCliCommand(subcommand) {
-    const command = (process.env.MCP_GITNEXUS_COMMAND || "npx").trim() || "npx";
-    const bridgeArgs = splitArgs(process.env.MCP_GITNEXUS_ARGS);
+function resolveNpxPackageArgs(bridgeArgs) {
     const flags = [];
     let packageSpec = "gitnexus@latest";
     for (const arg of bridgeArgs) {
@@ -140,17 +140,58 @@ function resolveGitNexusCliCommand(subcommand) {
         packageSpec = arg;
         break;
     }
-    return resolveSpawnCommand(command, [...flags, packageSpec, subcommand]);
+    return [...flags, packageSpec];
 }
-export function resolveExecutableCommand(command, platform = process.platform) {
+export function resolveGitNexusBridgeCommand(env = process.env, platform = process.platform) {
+    const explicitCommand = env.MCP_GITNEXUS_COMMAND?.trim();
+    if (explicitCommand) {
+        const args = splitArgs(env.MCP_GITNEXUS_ARGS, isGitNexusCliCommand(explicitCommand) ? ["mcp"] : DEFAULT_GITNEXUS_ARGS);
+        return {
+            ...resolveSpawnCommand(explicitCommand, args, platform, env),
+            strategy: "env",
+        };
+    }
+    const localCli = findExecutablePath("gitnexus", platform, env);
+    if (localCli) {
+        return {
+            command: localCli,
+            args: ["mcp"],
+            strategy: "local",
+        };
+    }
+    return {
+        ...resolveSpawnCommand("npx", splitArgs(env.MCP_GITNEXUS_ARGS), platform, env),
+        strategy: "npx",
+    };
+}
+function resolveGitNexusCliCommand(subcommand, env = process.env, platform = process.platform) {
+    const explicitCommand = env.MCP_GITNEXUS_COMMAND?.trim();
+    if (explicitCommand) {
+        if (isGitNexusCliCommand(explicitCommand)) {
+            return resolveSpawnCommand(explicitCommand, [subcommand], platform, env);
+        }
+        const bridgeArgs = splitArgs(env.MCP_GITNEXUS_ARGS);
+        return resolveSpawnCommand(explicitCommand, [...resolveNpxPackageArgs(bridgeArgs), subcommand], platform, env);
+    }
+    const localCli = findExecutablePath("gitnexus", platform, env);
+    if (localCli) {
+        return {
+            command: localCli,
+            args: [subcommand],
+        };
+    }
+    const bridgeArgs = splitArgs(env.MCP_GITNEXUS_ARGS);
+    return resolveSpawnCommand("npx", [...resolveNpxPackageArgs(bridgeArgs), subcommand], platform, env);
+}
+export function resolveExecutableCommand(command, platform = process.platform, env = process.env) {
     const normalized = (command || "").trim();
     if (!normalized) {
-        return resolveExecutableCommand("npx", platform);
+        return resolveExecutableCommand("npx", platform, env);
     }
     if (path.isAbsolute(normalized) && fs.existsSync(normalized)) {
         return normalized;
     }
-    const found = findExecutablePath(normalized, platform);
+    const found = findExecutablePath(normalized, platform, env);
     if (found) {
         return found;
     }
@@ -166,7 +207,7 @@ export function resolveExecutableCommand(command, platform = process.platform) {
     }
     return normalized;
 }
-function findExecutablePath(command, platform = process.platform) {
+function findExecutablePath(command, platform = process.platform, env = process.env) {
     const trimmed = (command || "").trim();
     if (!trimmed || path.isAbsolute(trimmed)) {
         return undefined;
@@ -197,6 +238,7 @@ function findExecutablePath(command, platform = process.platform) {
         try {
             const output = execFileSync("where.exe", [trimmed], {
                 encoding: "utf-8",
+                env,
                 stdio: ["ignore", "pipe", "ignore"],
                 windowsHide: true,
             }).trim();
@@ -210,7 +252,7 @@ function findExecutablePath(command, platform = process.platform) {
             // fall back to PATH scan
         }
     }
-    const pathEntries = (process.env.PATH || "")
+    const pathEntries = (env.PATH || "")
         .split(path.delimiter)
         .map((entry) => entry.trim())
         .filter(Boolean);
@@ -232,21 +274,215 @@ function findExecutablePath(command, platform = process.platform) {
     }
     if (platform === "win32" && trimmed.toLowerCase() === "git") {
         const commonCandidates = [
-            path.join(process.env["ProgramFiles"] || "C:\\Program Files", "Git", "cmd", "git.exe"),
-            path.join(process.env["ProgramFiles"] || "C:\\Program Files", "Git", "bin", "git.exe"),
-            path.join(process.env["ProgramFiles(x86)"] || "C:\\Program Files (x86)", "Git", "cmd", "git.exe"),
+            path.join(env["ProgramFiles"] || "C:\\Program Files", "Git", "cmd", "git.exe"),
+            path.join(env["ProgramFiles"] || "C:\\Program Files", "Git", "bin", "git.exe"),
+            path.join(env["ProgramFiles(x86)"] || "C:\\Program Files (x86)", "Git", "cmd", "git.exe"),
         ];
         return preferredPath(commonCandidates);
     }
     return undefined;
 }
-export function resolveSpawnCommand(command, args, platform = process.platform) {
-    const executable = resolveExecutableCommand(command, platform);
+export function resolveSpawnCommand(command, args, platform = process.platform, env = process.env) {
+    const executable = resolveExecutableCommand(command, platform, env);
     return {
         command: executable,
         args,
     };
 }
+function toRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function extractStructuredStatus(value) {
+    const status = toRecord(value)?.status;
+    return typeof status === "string" ? status : undefined;
+}
+function extractStructuredMessage(value) {
+    const record = toRecord(value);
+    if (!record) {
+        return undefined;
+    }
+    for (const key of ["message", "summary", "explanation", "detail"]) {
+        const candidate = record[key];
+        if (typeof candidate === "string" && candidate.trim()) {
+            return candidate.trim();
+        }
+    }
+    return undefined;
+}
+function extractStructuredCandidates(value) {
+    const candidates = toRecord(value)?.candidates;
+    if (!Array.isArray(candidates)) {
+        return [];
+    }
+    return candidates
+        .filter((item) => item && typeof item === "object" && !Array.isArray(item))
+        .map((item) => ({ ...item }));
+}
+function buildAmbiguities(executions) {
+    return executions
+        .filter((item) => item.ok && item.status === "ambiguous")
+        .map((item) => {
+        const candidates = extractStructuredCandidates(item.structuredContent);
+        const message = extractStructuredMessage(item.structuredContent) || item.text;
+        return {
+            tool: item.tool,
+            message: message ? shorten(message, 220) : undefined,
+            candidates,
+        };
+    });
+}
+const QUERY_STOP_WORDS = new Set([
+    "the", "and", "for", "with", "from", "into", "that", "this", "user", "flow",
+    "sign", "code", "project", "module",
+    "理解", "分析", "流程", "模块", "项目", "代码", "查询", "相关", "功能",
+]);
+function tokenizeQueryHints(...values) {
+    const tokens = new Set();
+    for (const value of values) {
+        for (const token of (value || "").toLowerCase().split(/[^a-z0-9_\u4e00-\u9fa5]+/)) {
+            const normalized = token.trim();
+            if (!normalized || QUERY_STOP_WORDS.has(normalized)) {
+                continue;
+            }
+            if (normalized.length < 3 && !/[\u4e00-\u9fa5]/.test(normalized)) {
+                continue;
+            }
+            tokens.add(normalized);
+        }
+    }
+    return [...tokens];
+}
+function collectStringFields(value, depth = 0, bag = [], currentKey = "") {
+    if (depth > 3 || value == null) {
+        return bag;
+    }
+    if (typeof value === "string") {
+        const normalized = value.trim().toLowerCase();
+        if (normalized) {
+            bag.push({ key: currentKey.toLowerCase(), value: normalized });
+        }
+        return bag;
+    }
+    if (Array.isArray(value)) {
+        for (const item of value.slice(0, 12)) {
+            collectStringFields(item, depth + 1, bag, currentKey);
+        }
+        return bag;
+    }
+    if (typeof value === "object") {
+        for (const [key, item] of Object.entries(value).slice(0, 20)) {
+            collectStringFields(item, depth + 1, bag, key);
+        }
+    }
+    return bag;
+}
+function scoreQueryCandidate(candidate, terms) {
+    const fields = collectStringFields(candidate);
+    if (fields.length === 0 || terms.length === 0) {
+        return 0;
+    }
+    let score = 0;
+    let matchedTerms = 0;
+    for (const term of terms) {
+        let matched = false;
+        for (const field of fields) {
+            if (!field.value.includes(term)) {
+                continue;
+            }
+            matched = true;
+            if (field.key.includes("name") || field.key.includes("title") || field.key.includes("label")) {
+                score += field.value === term ? 24 : 16;
+            }
+            else if (field.key.includes("path") || field.key.includes("file") || field.key.includes("module")) {
+                score += 10;
+            }
+            else {
+                score += 4;
+            }
+        }
+        if (matched) {
+            matchedTerms += 1;
+        }
+    }
+    if (matchedTerms > 0) {
+        score += matchedTerms * 5;
+    }
+    if (matchedTerms === terms.length) {
+        score += 12;
+    }
+    const candidateRecord = toRecord(candidate);
+    const priority = candidateRecord?.priority;
+    if (typeof priority === "number" && Number.isFinite(priority)) {
+        score += priority;
+    }
+    return score;
+}
+function describeQueryTopMatches(structuredContent) {
+    const processes = toRecord(structuredContent)?.processes;
+    if (!Array.isArray(processes) || processes.length === 0) {
+        return undefined;
+    }
+    const labels = processes
+        .slice(0, 3)
+        .map((item) => {
+        const record = toRecord(item);
+        return [
+            record?.heuristicLabel,
+            record?.title,
+            record?.name,
+            record?.processName,
+        ].find((value) => typeof value === "string" && value.trim());
+    })
+        .filter((value) => typeof value === "string" && value.trim().length > 0);
+    return labels.length > 0 ? `Top matches: ${labels.join(" | ")}` : undefined;
+}
+export function rerankQueryStructuredContent(structuredContent, hints) {
+    const record = toRecord(structuredContent);
+    if (!record) {
+        return { structuredContent, changed: false };
+    }
+    const terms = tokenizeQueryHints(hints.query, hints.goal, hints.taskContext);
+    if (terms.length === 0) {
+        return { structuredContent, changed: false };
+    }
+    let changed = false;
+    const next = { ...record };
+    for (const key of ["processes", "definitions"]) {
+        const value = next[key];
+        if (!Array.isArray(value) || value.length < 2) {
+            continue;
+        }
+        const reranked = value
+            .map((item, index) => ({
+            item,
+            index,
+            score: scoreQueryCandidate(item, terms),
+        }))
+            .sort((a, b) => (b.score - a.score) || (a.index - b.index))
+            .map((entry) => entry.item);
+        const orderChanged = reranked.some((item, index) => item !== value[index]);
+        if (orderChanged) {
+            next[key] = reranked;
+            changed = true;
+        }
+    }
+    return {
+        structuredContent: next,
+        changed,
+        note: changed ? describeQueryTopMatches(next) : undefined,
+    };
+}
+function describeExecutionSummary(item) {
+    if (item.tool === "query") {
+        const rerankedTopMatches = describeQueryTopMatches(item.structuredContent);
+        if (rerankedTopMatches) {
+            return shorten(rerankedTopMatches, 110);
+        }
+    }
+    return shorten(item.text || "已返回结构化结果", 110);
+}
 function extractText(result) {
     if (!result || typeof result !== "object") {
         return "";
@@ -507,10 +743,10 @@ function resolveMode(request) {
     if (mode === "query" || mode === "context" || mode === "impact") {
         return mode;
     }
-    if (request.target && request.direction) {
+    if ((request.target || request.uid) && request.direction) {
         return "impact";
     }
-    if (request.target && !request.query) {
+    if ((request.target || request.uid) && !request.query) {
         return "context";
     }
     return "query";
@@ -528,6 +764,10 @@ async function callBridgeTool(client, tool, args, signal, workspace) {
         const durationMs = Date.now() - startedAt;
         const text = extractText(result);
         const isError = Boolean(result.isError);
+        const structuredContent = workspace
+            ? mapValueToSourceRoot(result.structuredContent, workspace)
+            : result.structuredContent;
+        const status = extractStructuredStatus(structuredContent);
         if (isError) {
             return {
                 tool,
@@ -535,9 +775,8 @@ async function callBridgeTool(client, tool, args, signal, workspace) {
                 ok: false,
                 durationMs,
                 text: workspace ? mapValueToSourceRoot(text, workspace) : text,
-                structuredContent: workspace
-                    ? mapValueToSourceRoot(result.structuredContent, workspace)
-                    : result.structuredContent,
+                structuredContent,
+                status,
                 error: workspace
                     ? mapValueToSourceRoot(text || `GitNexus 工具 ${tool} 返回错误`, workspace)
                     : text || `GitNexus 工具 ${tool} 返回错误`,
@@ -549,9 +788,8 @@ async function callBridgeTool(client, tool, args, signal, workspace) {
             ok: true,
             durationMs,
             text: workspace ? mapValueToSourceRoot(text, workspace) : text,
-            structuredContent: workspace
-                ? mapValueToSourceRoot(result.structuredContent, workspace)
-                : result.structuredContent,
+            structuredContent,
+            status,
         };
     }
     catch (error) {
@@ -571,6 +809,7 @@ export async function runCodeInsightBridge(request) {
     const modeRequested = request.mode || "auto";
     const modeResolved = resolveMode(request);
     const requestedProjectRoot = resolveRequestedProjectRoot(request.projectRoot);
+    const launcher = resolveGitNexusBridgeCommand();
     if (!isBridgeEnabled() || isEnvDisabled("MCP_ENABLE_GITNEXUS_BRIDGE")) {
         const sourceRoot = findGitRoot(requestedProjectRoot) || requestedProjectRoot;
         return {
@@ -584,6 +823,8 @@ export async function runCodeInsightBridge(request) {
             executions: [],
             warnings: ["bridge_disabled"],
             repo: resolvePreferredRepoName(request.repo),
+            launcherStrategy: launcher.strategy,
+            ambiguities: [],
             workspaceMode: "direct",
             sourceRoot,
             analysisRoot: sourceRoot,
@@ -603,6 +844,8 @@ export async function runCodeInsightBridge(request) {
             executions: [],
             warnings: ["bridge_failure_cached"],
             repo: resolvePreferredRepoName(request.repo),
+            launcherStrategy: launcher.strategy,
+            ambiguities: [],
             workspaceMode: "direct",
             sourceRoot,
             analysisRoot: sourceRoot,
@@ -622,6 +865,8 @@ export async function runCodeInsightBridge(request) {
             executions: [],
             warnings: ["project_root_required", "unsafe_home_directory"],
             repo: resolvePreferredRepoName(request.repo),
+            launcherStrategy: launcher.strategy,
+            ambiguities: [],
             workspaceMode: "direct",
             sourceRoot: requestedProjectRoot,
             analysisRoot: requestedProjectRoot,
@@ -633,7 +878,7 @@ export async function runCodeInsightBridge(request) {
     const effectiveRepo = workspace.workspaceMode === "temp-repo"
         ? workspace.repoName
         : resolvePreferredRepoName(request.repo) || workspace.repoName;
-    const { command, args } = resolveBridgeCommand();
+    const { command, args } = launcher;
     const warnings = [];
     if (workspace.workspaceMode === "temp-repo") {
         warnings.push("temp_repo_workspace");
@@ -670,30 +915,50 @@ export async function runCodeInsightBridge(request) {
                 warnings.push("缺少 query 参数，已跳过 query");
                 return;
             }
-            executions.push(await callBridgeTool(client, "query", {
+            const execution = await callBridgeTool(client, "query", {
                 query: queryText,
                 ...(request.goal ? { goal: request.goal } : {}),
                 ...(request.taskContext ? { task_context: request.taskContext } : {}),
+                ...(request.includeContent ? { include_content: true } : {}),
                 ...(effectiveRepo ? { repo: effectiveRepo } : {}),
-            }, request.signal, workspace));
+            }, request.signal, workspace);
+            if (execution.ok) {
+                const reranked = rerankQueryStructuredContent(execution.structuredContent, {
+                    query: queryText,
+                    goal: request.goal,
+                    taskContext: request.taskContext,
+                });
+                execution.structuredContent = reranked.structuredContent;
+                if (reranked.changed) {
+                    warnings.push("query_results_reranked");
+                    if (reranked.note) {
+                        execution.text = execution.text
+                            ? `${reranked.note}\n\n${execution.text}`
+                            : reranked.note;
+                    }
+                }
+            }
+            executions.push(execution);
         };
         const runContext = async () => {
-            if (!request.target) {
-                warnings.push("缺少 target 参数，已跳过 context");
+            if (!request.target && !request.uid) {
+                warnings.push("缺少 target/uid 参数，已跳过 context");
                 return;
             }
             executions.push(await callBridgeTool(client, "context", {
-                name: request.target,
+                ...(request.uid ? { uid: request.uid } : { name: request.target }),
+                ...(request.filePath ? { file_path: request.filePath } : {}),
+                ...(request.includeContent ? { include_content: true } : {}),
                 ...(effectiveRepo ? { repo: effectiveRepo } : {}),
             }, request.signal, workspace));
         };
         const runImpact = async () => {
-            if (!request.target) {
-                warnings.push("缺少 target 参数，已跳过 impact");
+            if (!request.target && !request.uid) {
+                warnings.push("缺少 target/uid 参数，已跳过 impact");
                 return;
             }
             executions.push(await callBridgeTool(client, "impact", {
-                target: request.target,
+                target: request.uid || request.target,
                 direction: request.direction || "upstream",
                 ...(request.maxDepth ? { maxDepth: request.maxDepth } : {}),
                 ...(typeof request.includeTests === "boolean"
@@ -704,10 +969,10 @@ export async function runCodeInsightBridge(request) {
         };
         if (modeRequested === "auto") {
             await runQuery();
-            if (request.target) {
+            if (request.target || request.uid) {
                 await runContext();
             }
-            if (request.target && request.direction) {
+            if ((request.target || request.uid) && request.direction) {
                 await runImpact();
             }
         }
@@ -740,6 +1005,8 @@ export async function runCodeInsightBridge(request) {
             executions: [],
             warnings: ["bridge_unavailable", ...warnings],
             repo: effectiveRepo,
+            launcherStrategy: launcher.strategy,
+            ambiguities: [],
             workspaceMode: workspace.workspaceMode,
             sourceRoot: workspace.sourceRoot,
             analysisRoot: workspace.analysisRoot,
@@ -768,6 +1035,7 @@ export async function runCodeInsightBridge(request) {
     }
     bridgeFailureUntil = 0;
     bridgeFailureReason = "";
+    const ambiguities = buildAmbiguities(successful);
     if (successful.length === 0) {
         const fallbackError = failed.length > 0
             ? shorten(failed.map((item) => `${item.tool}: ${item.error || "unknown error"}`).join(" | "), 220)
@@ -783,14 +1051,19 @@ export async function runCodeInsightBridge(request) {
             executions,
             warnings: ["bridge_call_failed", ...warnings],
             repo: effectiveRepo,
+            launcherStrategy: launcher.strategy,
+            ambiguities,
             workspaceMode: workspace.workspaceMode,
             sourceRoot: workspace.sourceRoot,
             analysisRoot: workspace.analysisRoot,
             pathMapped: workspace.pathMapped,
         };
     }
-    const summaryParts = successful.map((item) => `${item.tool}: ${shorten(item.text || "已返回结构化结果", 110)}`);
-    const summary = `GitNexus 图谱增强已启用（${successful.length}/${executions.length} 成功）: ${summaryParts.join(" | ")}`;
+    const summary = ambiguities.length > 0
+        ? `GitNexus 返回了 ${ambiguities.length} 个歧义结果，请指定 uid 或 file_path 后重试。`
+        : `GitNexus 图谱增强已启用（${successful.length}/${executions.length} 成功）: ${successful
+            .map((item) => `${item.tool}: ${describeExecutionSummary(item)}`)
+            .join(" | ")}`;
     return {
         provider: "gitnexus",
         enabled: true,
@@ -802,6 +1075,8 @@ export async function runCodeInsightBridge(request) {
         executions,
         warnings,
         repo: effectiveRepo,
+        launcherStrategy: launcher.strategy,
+        ambiguities,
         workspaceMode: workspace.workspaceMode,
         sourceRoot: workspace.sourceRoot,
         analysisRoot: workspace.analysisRoot,

package/build/tools/__tests__/code_insight.unit.test.js

@@ -1,5 +1,5 @@
 import { describe, expect, test } from "vitest";
-import { codeInsight, resolveCodeInsightQuery } from "../code_insight.js";
+import { buildCodeInsightDelegatedPlan, codeInsight, deriveCodeInsightStatus, resolveCodeInsightQuery, } from "../code_insight.js";
 import * as os from "node:os";
 import * as fs from "node:fs";
 import * as path from "node:path";
@@ -76,6 +76,56 @@ describe("code_insight 单元测试", () => {
         expect(resolved.finalQuery).toMatch(/核心流程/);
         expect(resolved.finalQuery).toMatch(/依赖关系/);
     });
+    test("歧义结果会生成候选选择 delegated plan", () => {
+        const status = deriveCodeInsightStatus({
+            available: true,
+            ambiguities: [
+                {
+                    tool: "context",
+                    message: "找到多个 login 符号",
+                    candidates: [{ uid: "Method:auth.ts:login:12", file_path: "/repo/src/auth.ts" }],
+                },
+            ],
+            executions: [{ tool: "context", ok: true, durationMs: 10, args: {}, status: "ambiguous" }],
+        });
+        const plan = buildCodeInsightDelegatedPlan({
+            status,
+            ambiguities: [
+                {
+                    tool: "context",
+                    message: "找到多个 login 符号",
+                    candidates: [{ uid: "Method:auth.ts:login:12", file_path: "/repo/src/auth.ts" }],
+                },
+            ],
+            showPlan: true,
+        });
+        expect(status).toBe("ambiguous");
+        expect(plan?.kind).toBe("ambiguity");
+        expect(plan?.steps[1].action).toMatch(/uid 或 file_path/);
+    });
+    test("未显式要求保存时不生成 docs delegated plan", async () => {
+        const prev = process.env.MCP_ENABLE_GITNEXUS_BRIDGE;
+        process.env.MCP_ENABLE_GITNEXUS_BRIDGE = "0";
+        try {
+            const result = await codeInsight({
+                mode: "auto",
+            });
+            expect(result.isError).toBe(false);
+            const text = String(result.content?.[0]?.text || "");
+            const structured = result.structuredContent;
+            expect(text).not.toMatch(/delegated plan/);
+            expect(structured.plan).toBeUndefined();
+            expect(structured.projectDocs).toBeUndefined();
+        }
+        finally {
+            if (prev === undefined) {
+                delete process.env.MCP_ENABLE_GITNEXUS_BRIDGE;
+            }
+            else {
+                process.env.MCP_ENABLE_GITNEXUS_BRIDGE = prev;
+            }
+        }
+    });
     test("返回 docs 保存指引而不直接代写文件", async () => {
         const prev = process.env.MCP_ENABLE_GITNEXUS_BRIDGE;
         process.env.MCP_ENABLE_GITNEXUS_BRIDGE = "0";

package/build/tools/code_insight.d.ts

@@ -1,5 +1,34 @@
-import { type CodeInsightMode } from "../lib/gitnexus-bridge.js";
+import { type CodeInsightAmbiguity, type CodeInsightBridgeResult, type CodeInsightMode } from "../lib/gitnexus-bridge.js";
 import { type ToolExecutionContext } from "../lib/tool-execution-context.js";
+type CodeInsightStatus = "ok" | "degraded" | "ambiguous" | "not_found";
+interface ProjectDocsPlan {
+    docsDir: string;
+    projectContextFilePath: string;
+    latestMarkdownFilePath: string;
+    latestJsonFilePath: string;
+    archiveMarkdownFilePath: string;
+    archiveJsonFilePath: string;
+    navigationSnippet: string;
+    devGuideSnippet: string;
+}
+interface DelegatedPlanStep {
+    id: string;
+    action: string;
+    outputs?: string[];
+    note?: string;
+}
+interface DelegatedPlan {
+    mode: "delegated";
+    kind: "docs" | "ambiguity";
+    steps: DelegatedPlanStep[];
+}
+export declare function deriveCodeInsightStatus(result: Pick<CodeInsightBridgeResult, "available" | "ambiguities" | "executions">): CodeInsightStatus;
+export declare function buildCodeInsightDelegatedPlan(input: {
+    status: CodeInsightStatus;
+    ambiguities: CodeInsightAmbiguity[];
+    projectDocs?: ProjectDocsPlan;
+    showPlan: boolean;
+}): DelegatedPlan | undefined;
 export declare function resolveCodeInsightQuery(input: {
     mode: CodeInsightMode;
     query: string;
@@ -16,3 +45,4 @@ export declare function codeInsight(args: any, context?: ToolExecutionContext):
     }[];
     isError: boolean;
 }>;
+export {};