codesift-mcp 0.9.5 → 0.10.0

package/dist/server-helpers/response-hints.js

@@ -0,0 +1,225 @@
+import { getCallCount, getSessionState } from "../storage/session-state.js";
+const HIGH_CARDINALITY_THRESHOLD = 50;
+const BATCHABLE_TOOLS = new Set(["search_text", "search_symbols", "find_references", "get_symbol"]);
+const SEQUENTIAL_HINT_THRESHOLD = 3;
+let lastToolName = "";
+let consecutiveCount = 0;
+let listReposCallCount = 0;
+/** Session-level tracking for cross-tool hints */
+const fileTreePaths = new Set();
+let sessionSearchSymbolsCalled = false;
+let sessionGetSymbolCount = 0;
+const sessionSearchTextPatterns = new Set(); // H12: track distinct file_patterns in search_text
+/** Track sequential calls + session-level state. Exported for testing. */
+export function trackSequentialCalls(toolName) {
+    if (toolName === lastToolName && BATCHABLE_TOOLS.has(toolName)) {
+        consecutiveCount++;
+    }
+    else {
+        consecutiveCount = 1;
+    }
+    lastToolName = toolName;
+    if (toolName === "list_repos") {
+        listReposCallCount++;
+    }
+    if (toolName === "search_symbols") {
+        sessionSearchSymbolsCalled = true;
+    }
+    if (toolName === "get_symbol") {
+        sessionGetSymbolCount++;
+    }
+    // H12 tracking is in buildResponseHint (needs args, which trackSequentialCalls doesn't receive)
+}
+const QUESTION_PATTERN = /^(how|where|why|what|when|which)\b/i;
+const ROUTE_PATTERN = /\/api\/|endpoint|handler|router\.|middleware|app\.(get|post|put|delete)/i;
+const SECRET_PATTERN = /api[._-]?key|AWS_|OPENAI_|SECRET_KEY|password|credential/i;
+/**
+ * H18: literal substrings that show up in the regex string of Jest/Vitest/RTL
+ * test-quality audit patterns. Matches against the raw `query` text the agent
+ * passed (treated as a string, not as a parsed regex) — so escapes like `\b`
+ * appear as `\\b` here. Detection triggers a "batch via codebase_retrieval"
+ * hint to collapse 100+ per-pattern calls into one composite call.
+ */
+const TEST_ANTIPATTERN_SUBSTRINGS = [
+    // Distinctive Jest/Vitest/RTL matcher names — unlikely to appear outside test
+    // audit context, so plain substring match is safe.
+    "toBeTruthy", "toBeFalsy", "toBeDefined", "toBeGreaterThan", "toBeLessThan",
+    "toBeNull", "toBeUndefined",
+    "toHaveBeenCalled", "toHaveLength", "toHaveProperty",
+    "toMatchSnapshot", "toMatchInlineSnapshot",
+    // Common Jest/Vitest regex shapes — note backslash-escaped parens are LITERAL
+    // chars in the query string the agent passes (regex=true mode).
+    "toBe\\(true", "toBe\\(false", "expect\\(true", "expect\\(false",
+    "\\.skip\\(", "\\.only\\(",
+    // Use only the regex-escaped form for short tokens like "as any" — the bare
+    // 6-char string was false-positive prone (e.g. "has any value", "cargo has anyone").
+    "\\bas\\s+any",
+    "TODO|FIXME", "FIXME|TODO",
+];
+function isTestAntipatternQuery(query) {
+    for (const sig of TEST_ANTIPATTERN_SUBSTRINGS) {
+        if (query.includes(sig))
+            return true;
+    }
+    return false;
+}
+// ---------------------------------------------------------------------------
+// Hint codes — compact symbols decoded via CLAUDE.md legend.
+// Each hint costs ~3-5 tokens instead of 20-50 tokens in verbose form.
+// Legend lives in CLAUDE.md so LLM sees it once per session.
+// ---------------------------------------------------------------------------
+//
+// H1(n)  = >50 matches, add group_by_file=true
+// H2(n,t)= consecutive identical tool calls, batch them
+// H3(n)  = list_repos called multiple times, result is static
+// H4     = include_source without file_pattern, add file_pattern
+// H5(p)  = duplicate get_file_tree path, cache result
+// H6(n)  = many search_symbols results without detail_level, use compact
+// H7     = get_symbol after search_symbols, use get_context_bundle instead
+// H8(n)  = 3+ get_symbol calls, use assemble_context(level='L1')
+// H9     = question-word text query, use semantic search
+// ---------------------------------------------------------------------------
+/**
+ * Build optimization hints based on response data + call patterns.
+ * Returns compact hint codes (decoded in CLAUDE.md).
+ */
+export function buildResponseHint(toolName, args, data) {
+    const hints = [];
+    if (toolName === "search_text" && Array.isArray(data) && data.length > HIGH_CARDINALITY_THRESHOLD) {
+        if (!args["group_by_file"] && !args["auto_group"]) {
+            hints.push(`⚡H1(${data.length})`);
+        }
+    }
+    if (consecutiveCount >= SEQUENTIAL_HINT_THRESHOLD && BATCHABLE_TOOLS.has(toolName)) {
+        const batchTool = toolName === "get_symbol" ? "get_symbols" : "codebase_retrieval";
+        hints.push(`⚡H2(${consecutiveCount},${batchTool})`);
+    }
+    if (toolName === "list_repos" && listReposCallCount > 1) {
+        hints.push(`⚡H3(${listReposCallCount})`);
+    }
+    if (toolName === "search_symbols" && args["include_source"] && !args["file_pattern"]) {
+        hints.push(`⚡H4`);
+    }
+    if (toolName === "get_file_tree") {
+        const repo = typeof args["repo"] === "string" ? args["repo"] : "";
+        const pathPrefix = typeof args["path_prefix"] === "string" ? args["path_prefix"] : "";
+        const pathKey = `${repo}\0${pathPrefix}`;
+        if (fileTreePaths.has(pathKey)) {
+            hints.push(`⚡H5(${pathPrefix || "/"})`);
+        }
+        fileTreePaths.add(pathKey);
+    }
+    if (toolName === "search_symbols" && !args["detail_level"]) {
+        const resultCount = Array.isArray(data) ? data.length : 0;
+        if (resultCount > 5) {
+            hints.push(`⚡H6(${resultCount})`);
+        }
+    }
+    // H15: search_symbols("<bare keyword>") returned 0 results → query is likely a
+    // substring/concept, not a symbol name. Telemetry showed 98× zero-result calls
+    // for queries like "auth", "user", "render" — agents kept retrying instead of
+    // switching tool. Detect lowercase ≤8-char queries with no uppercase/underscore
+    // (true identifiers conventionally include caps or underscores).
+    if (toolName === "search_symbols" && Array.isArray(data) && data.length === 0) {
+        const q = typeof args["query"] === "string" ? args["query"] : "";
+        if (/^[a-z]{2,8}$/.test(q)) {
+            hints.push(`⚡H15 "${q}" returned 0 symbols — looks like a keyword, not a symbol name. Try search_text("${q}") for substring matches.`);
+        }
+    }
+    // H11: search_text returned 0 matches → guide next step. Most common causes:
+    // file_pattern too narrow, identifier not present as text (only as binding),
+    // or concept question that needs semantic search.
+    if (toolName === "search_text" && Array.isArray(data) && data.length === 0) {
+        const q = typeof args["query"] === "string" ? args["query"] : "";
+        const hasFilePattern = Boolean(args["file_pattern"]);
+        const isRegex = Boolean(args["regex"]);
+        if (q.length > 0) {
+            const tips = [];
+            if (hasFilePattern)
+                tips.push(`drop file_pattern`);
+            if (!isRegex && /^[A-Za-z_][A-Za-z0-9_]{2,}$/.test(q)) {
+                tips.push(`use search_symbols("${q}") for the declaration`);
+            }
+            if (QUESTION_PATTERN.test(q)) {
+                tips.push(`use semantic_search for concept questions`);
+            }
+            else if (tips.length === 0) {
+                tips.push(`try a broader query or codebase_retrieval(type="semantic")`);
+            }
+            hints.push(`⚡H11 0 matches for "${q.slice(0, 60)}" — ${tips.join(", or ")}.`);
+        }
+    }
+    // H16: get_file_tree returned an empty list while name_pattern was set →
+    // pattern matched nothing. Most common in telemetry: agents trying patterns
+    // for extensions the repo doesn't have (e.g. "*.kt" in a JS-only repo).
+    if (toolName === "get_file_tree" && typeof args["name_pattern"] === "string" && args["name_pattern"].length > 0) {
+        const isEmpty = Array.isArray(data)
+            ? data.length === 0
+            : (typeof data === "object" && data !== null && Array.isArray(data["entries"])
+                ? data["entries"].length === 0
+                : false);
+        if (isEmpty) {
+            hints.push(`⚡H16 0 files match name_pattern="${args["name_pattern"]}". Try omitting name_pattern, or use get_repo_outline to see file structure.`);
+        }
+    }
+    // H17: find_references returned 0 → symbol_name probably misspelled or not a
+    // registered symbol. Telemetry showed 94% empty rate for find_references.
+    // Agents should verify the symbol exists via search_symbols first.
+    if (toolName === "find_references" && Array.isArray(data) && data.length === 0) {
+        const name = typeof args["symbol_name"] === "string" ? args["symbol_name"] : "";
+        if (name.length > 0) {
+            hints.push(`⚡H17 0 references to "${name}" — verify with search_symbols(query="${name}") first; symbol may be misspelled, external, or only referenced in strings/comments (try search_text).`);
+        }
+    }
+    // H18 (Wariant B): search_text with regex matching a known test-antipattern
+    // signature → agents are running per-pattern audits one regex at a time.
+    // Suggest batching via codebase_retrieval. Catches the bursts of 100+ calls
+    // observed in zuvo:test-audit / zuvo:fix-tests sessions.
+    if (toolName === "search_text" && args["regex"] && typeof args["query"] === "string") {
+        if (isTestAntipatternQuery(args["query"])) {
+            hints.push(`⚡H18 query looks like a test-quality pattern — batch multiple via codebase_retrieval(queries=[{type:"text",regex:true,query:"..."}, ...]) to scan once instead of N times.`);
+        }
+    }
+    if (toolName === "get_symbol" && sessionSearchSymbolsCalled) {
+        hints.push(`⚡H7`);
+    }
+    if (toolName === "get_symbol" && sessionGetSymbolCount >= 3) {
+        hints.push(`⚡H8(${sessionGetSymbolCount})`);
+    }
+    if (toolName === "search_text" && typeof args["query"] === "string" && QUESTION_PATTERN.test(args["query"])) {
+        hints.push(`⚡H9`);
+        // Auto-reveal semantic_search so agents can use it immediately
+        import("../register-tools.js").then(m => m.enableToolByName("semantic_search")).catch(() => { });
+    }
+    // H10: Session snapshot reminder after 50 calls (read-only check; flag set by wrapTool)
+    if (getCallCount() >= 50 && !getSessionState().h10Emitted) {
+        hints.push(`⚡H10 50+ tool calls this session → call get_session_snapshot to preserve context`);
+    }
+    // H13: Route-shaped query → suggest trace_route
+    if (toolName === "search_text" && typeof args["query"] === "string" && ROUTE_PATTERN.test(args["query"])) {
+        hints.push(`⚡H13 route query → try trace_route(path=) for full endpoint tracing`);
+    }
+    // H14: Secret/credential pattern → suggest scan_secrets
+    if (toolName === "search_text" && typeof args["query"] === "string" && SECRET_PATTERN.test(args["query"])) {
+        hints.push(`⚡H14 secret pattern → try scan_secrets(min_confidence="high")`);
+    }
+    // H12: Repeated search_text with different file_patterns → suggest codebase_retrieval batch
+    if (toolName === "search_text") {
+        const fp = args["file_pattern"] ?? "__none__";
+        sessionSearchTextPatterns.add(fp);
+        if (sessionSearchTextPatterns.size >= SEQUENTIAL_HINT_THRESHOLD) {
+            hints.push(`⚡H12(${sessionSearchTextPatterns.size}) ${sessionSearchTextPatterns.size}× search_text with different file_patterns → batch into codebase_retrieval(queries=[...])`);
+        }
+    }
+    return hints.length > 0 ? hints.join(" ") : null;
+}
+export function resetHintState() {
+    lastToolName = "";
+    consecutiveCount = 0;
+    listReposCallCount = 0;
+    fileTreePaths.clear();
+    sessionSearchSymbolsCalled = false;
+    sessionGetSymbolCount = 0;
+    sessionSearchTextPatterns.clear();
+}
+//# sourceMappingURL=response-hints.js.map

package/dist/server-helpers/response-hints.js.map

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

package/dist/server-helpers.d.ts

@@ -1,30 +1,5 @@
-interface RegistryRepoMeta {
-    name: string;
-    root: string;
-    symbol_count: number;
-    file_count: number;
-}
-/** Read registry synchronously, cached by mtime to avoid disk hits in the hot path. */
-export declare function loadRegistrySync(registryPath?: string): RegistryRepoMeta[];
-/** True iff `descendant` is `ancestor` or sits underneath it on a path-segment boundary. */
-export declare function isAncestorOrEqual(ancestor: string, descendant: string): boolean;
-/**
- * Resolve the repo name for a CWD by consulting the registry.
- *
- * Strategy:
- *  1. Drop chat-history indexes (`~/.claude/projects/...`) — they shadow real
- *     repos when the AI session's CWD matches them as a sibling/ancestor.
- *  2. Drop empty entries (symbol_count=0) — they're stub registrations from
- *     `index_folder` calls that found nothing or got auto-created on cd.
- *  3. From remaining repos whose `root` is an ancestor of `cwd`, pick the
- *     longest match. This handles monorepo subdirs and worktrees correctly:
- *     cwd=/repo/apps/api with root=/repo registered → resolves to /repo's name.
- *  4. If nothing matches, fall back to `local/<basename(cwd)>` so the tool
- *     surfaces a clear NOT INDEXED error instead of silently using a stale value.
- */
-export declare function resolveRepoFromCwd(cwd: string, registryPath?: string): string;
-/** Test-only: drop the registry cache. */
-export declare function _resetRegistryCacheForTests(): void;
+export { loadRegistrySync, isAncestorOrEqual, resolveRepoFromCwd, canonicalizeRepoName, _resetRegistryCacheForTests } from "./server-helpers/repo-resolution.js";
+export { buildResponseHint, trackSequentialCalls } from "./server-helpers/response-hints.js";
 export interface ToolResponse {
     [key: string]: unknown;
     content: Array<{
@@ -39,18 +14,22 @@ interface ShorteningEntry {
 }
 export declare function registerShortener(toolName: string, entry: ShorteningEntry): void;
 export declare function resetShorteningRegistry(): void;
-/** Track sequential calls + session-level state. Exported for testing. */
-export declare function trackSequentialCalls(toolName: string): void;
-export declare function errorResult(message: string): ToolResponse;
 /**
- * Build optimization hints based on response data + call patterns.
- * Returns compact hint codes (decoded in CLAUDE.md).
+ * Tool calls that mutate the index — must invalidate the response cache so
+ * the next search/symbol read sees fresh data (otherwise the 30s-5min TTL
+ * serves stale results for up to several minutes after an edit).
+ *
+ * Exported because the registration runtime derives its timeout-exempt allowlist
+ * from it (indexing is legitimately long-running — index_repo clones + indexes a
+ * remote repo — so it must never be cut off by the client-facing timeout).
  */
-export declare function buildResponseHint(toolName: string, args: Record<string, unknown>, data: unknown): string | null;
-export declare function wrapTool<T>(toolName: string, args: Record<string, unknown>, fn: () => Promise<T>): () => Promise<ToolResponse>;
+export declare const INDEX_MUTATING_TOOLS: ReadonlySet<string>;
+export declare function errorResult(message: string): ToolResponse;
+export declare function wrapTool<T>(toolName: string, args: Record<string, unknown>, fn: () => Promise<T>, opts?: {
+    bypassCache?: boolean;
+}): () => Promise<ToolResponse>;
 /**
  * Reset all session-level tracking state. Exported for testing only.
  */
 export declare function resetSessionState(): void;
-export {};
 //# sourceMappingURL=server-helpers.d.ts.map

package/dist/server-helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server-helpers.d.ts","sourceRoot":"","sources":["../src/server-helpers.ts"],"names":[],"mappings":"AAgBA,UAAU,gBAAgB;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;CACpB;AAID,uFAAuF;AACvF,wBAAgB,gBAAgB,CAAC,YAAY,GAAE,MAAsB,GAAG,gBAAgB,EAAE,CAazF;AAED,4FAA4F;AAC5F,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAI/E;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,GAAE,MAAsB,GAAG,MAAM,CAa5F;AAOD,0CAA0C;AAC1C,wBAAgB,2BAA2B,IAAI,IAAI,CAElD;AAiDD,MAAM,WAAW,YAAY;IAC3B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IACvB,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAMD,UAAU,eAAe;IACvB,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,MAAM,CAAC;IACpC,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,MAAM,CAAC;CACpC;AAID,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,GAAG,IAAI,CAEhF;AAED,wBAAgB,uBAAuB,IAAI,IAAI,CAE9C;AA6ED,0EAA0E;AAC1E,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAkB3D;AAMD,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,CAOzD;AAoDD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAkJ/G;AAuED,wBAAgB,QAAQ,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,MAAM,OAAO,CAAC,YAAY,CAAC,CA0E9H;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,IAAI,CAUxC"}
+{"version":3,"file":"server-helpers.d.ts","sourceRoot":"","sources":["../src/server-helpers.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,2BAA2B,EAAE,MAAM,qCAAqC,CAAC;AACjK,OAAO,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,oCAAoC,CAAC;AAyC7F,MAAM,WAAW,YAAY;IAC3B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IACvB,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAMD,UAAU,eAAe;IACvB,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,MAAM,CAAC;IACpC,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,MAAM,CAAC;CACpC;AAID,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,GAAG,IAAI,CAEhF;AAED,wBAAgB,uBAAuB,IAAI,IAAI,CAE9C;AAkDD;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,EAAE,WAAW,CAAC,MAAM,CAKnD,CAAC;AAWH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,CAOzD;AAuED,wBAAgB,QAAQ,CAAC,CAAC,EACxB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,IAAI,CAAC,EAAE;IAAE,WAAW,CAAC,EAAE,OAAO,CAAA;CAAE,GAC/B,MAAM,OAAO,CAAC,YAAY,CAAC,CA4F7B;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,IAAI,CAIxC"}