@mcoda/codali 0.1.108 → 0.1.110

package/dist/tools/TruncateResult.js

@@ -0,0 +1,91 @@
+/**
+ * Fitting a tool result into a budget without destroying it.
+ *
+ * Cutting a serialized payload at a character count leaves the model invalid
+ * JSON ending mid-token. Observed with `list_commits`: 12,063 characters cut at
+ * 12,000, so the model received a broken document and reported "I can only see
+ * one commit" — accurate about what survived, useless as an answer.
+ *
+ * Most oversized results are a list of similar things. Keeping whole items and
+ * saying how many were dropped preserves both validity and the fact that more
+ * exists, which is what the model needs to be honest about coverage.
+ */
+const NOTICE = (detail) => `\n\n[TRUNCATED: ${detail}. This result is INCOMPLETE — say so explicitly and do not present it as the full set.]`;
+/**
+ * Finds the largest array in a payload — the part worth trimming. A connector
+ * usually wraps its list in an envelope (`{ value: [...] }`, `{ issues: [...] }`),
+ * so the array is rarely at the root.
+ */
+const findLargestArray = (value, depth = 0) => {
+    if (depth > 4)
+        return undefined;
+    if (Array.isArray(value))
+        return { parent: undefined, items: value };
+    if (!value || typeof value !== "object")
+        return undefined;
+    let best;
+    for (const [key, entry] of Object.entries(value)) {
+        if (Array.isArray(entry)) {
+            if (!best || entry.length > best.items.length) {
+                best = { parent: value, key, items: entry };
+            }
+            continue;
+        }
+        const nested = findLargestArray(entry, depth + 1);
+        if (nested?.parent && (!best || nested.items.length > best.items.length)) {
+            best = { parent: nested.parent, key: nested.key, items: nested.items };
+        }
+    }
+    return best;
+};
+/**
+ * Trims a tool result to `limit` characters.
+ *
+ * When the payload holds a list, drops whole items from the end until it fits,
+ * so the result stays parseable. Otherwise falls back to a character cut, which
+ * is still better than silence for prose.
+ */
+export const truncateToolResult = (raw, serialized, limit) => {
+    if (serialized.length <= limit) {
+        return { text: serialized, truncated: false };
+    }
+    const found = findLargestArray(raw);
+    if (found && found.items.length > 1) {
+        const total = found.items.length;
+        // Binary search the largest prefix that fits, rather than dropping one at a
+        // time — a 500-item result would otherwise re-serialize 500 times.
+        let low = 1;
+        let high = total;
+        let bestFit = 1;
+        let bestText = "";
+        while (low <= high) {
+            const mid = Math.floor((low + high) / 2);
+            const kept = found.items.slice(0, mid);
+            const candidate = found.parent
+                ? { ...found.parent, [found.key]: kept }
+                : kept;
+            const text = JSON.stringify(candidate, null, 2);
+            if (text.length <= limit) {
+                bestFit = mid;
+                bestText = text;
+                low = mid + 1;
+            }
+            else {
+                high = mid - 1;
+            }
+        }
+        if (bestText) {
+            const dropped = total - bestFit;
+            return {
+                text: `${bestText}${NOTICE(`showing ${bestFit} of ${total} items; ${dropped} omitted`)}`,
+                truncated: true,
+                keptItems: bestFit,
+                droppedItems: dropped,
+            };
+        }
+    }
+    return {
+        text: `${serialized.slice(0, limit)}${NOTICE(`${serialized.length - limit} more characters were cut`)}`,
+        truncated: true,
+    };
+};

package/dist/tools/diff/DiffTool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DiffTool.d.ts","sourceRoot":"","sources":["../../../src/tools/diff/DiffTool.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAe,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAanE,eAAO,MAAM,cAAc,QAAO,cAsBhC,CAAC"}
+{"version":3,"file":"DiffTool.d.ts","sourceRoot":"","sources":["../../../src/tools/diff/DiffTool.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAe,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAanE,eAAO,MAAM,cAAc,QAAO,cAwBhC,CAAC"}

package/dist/tools/diff/DiffTool.js

@@ -12,6 +12,8 @@ const runGitStatus = (cwd) => {
 export const createDiffTool = () => ({
     name: "diff_summary",
     description: "Show a git status summary of workspace changes.",
+    readOnly: true,
+    capability: "workspace",
     inputSchema: {
         type: "object",
         properties: {

package/dist/tools/docdex/DocdexTools.d.ts

@@ -1,4 +1,24 @@
 import type { ToolDefinition } from "../ToolTypes.js";
 import type { DocdexClient } from "../../docdex/DocdexClient.js";
-export declare const createDocdexTools: (client: DocdexClient) => ToolDefinition[];
+/**
+ * Judges whether search results actually answer the question.
+ *
+ * Needed because presence is not relevance. The local index returns *something*
+ * for almost any query — "GDP of France 2025" scores 29.07 against this
+ * repository, higher than "gateway planner class" at 14.35, because a test
+ * fixture happens to contain the phrase. A score threshold would therefore be
+ * both arbitrary and wrong, and keyword rules ("if the query mentions GDP, go
+ * to the web") are exactly the hardcoding this project rules out.
+ *
+ * So the judgement is delegated to a model: cheap, generic, and it degrades to
+ * the old presence-based behaviour when no judge is supplied.
+ */
+export type RelevanceJudge = (input: {
+    query: string;
+    results: unknown;
+}) => Promise<boolean>;
+export interface DocdexToolOptions {
+    judgeRelevance?: RelevanceJudge;
+}
+export declare const createDocdexTools: (client: DocdexClient, options?: DocdexToolOptions) => ToolDefinition[];
 //# sourceMappingURL=DocdexTools.d.ts.map

package/dist/tools/docdex/DocdexTools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DocdexTools.d.ts","sourceRoot":"","sources":["../../../src/tools/docdex/DocdexTools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAOjE,eAAO,MAAM,iBAAiB,GAAI,QAAQ,YAAY,KAAG,cAAc,EA8iBtE,CAAC"}
+{"version":3,"file":"DocdexTools.d.ts","sourceRoot":"","sources":["../../../src/tools/docdex/DocdexTools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAsFjE;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,KAAK,EAAE;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;CAClB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAEvB,MAAM,WAAW,iBAAiB;IAChC,cAAc,CAAC,EAAE,cAAc,CAAC;CACjC;AAED,eAAO,MAAM,iBAAiB,GAC5B,QAAQ,YAAY,EACpB,UAAS,iBAAsB,KAC9B,cAAc,EAAgE,CAAC"}

package/dist/tools/docdex/DocdexTools.js

@@ -2,7 +2,85 @@ const toOutput = (payload) => ({
     output: typeof payload === "string" ? payload : JSON.stringify(payload, null, 2),
     data: payload,
 });
-export const createDocdexTools = (client) => [
+/**
+ * Docdex tools that mutate state (index, memory, profile, repo binding). Every
+ * other docdex tool is read-only. Listed as the exception set so a newly added
+ * read tool is safe by default and a newly added write tool must be declared.
+ */
+const DOCDEX_WRITE_TOOLS = new Set([
+    "docdex_initialize",
+    "docdex_index_rebuild",
+    "docdex_index_ingest",
+    "docdex_memory_save",
+    "docdex_save_preference",
+    "docdex_delegate",
+]);
+/**
+ * Docdex is one capability from the orchestrator's point of view, except web
+ * research, which is a distinct capability ("current external information")
+ * even though docdex happens to serve it.
+ */
+const docdexCapabilityFor = (name) => name === "docdex_web_research" ? "web" : "docdex";
+const isRecord = (value) => Boolean(value && typeof value === "object" && !Array.isArray(value));
+/**
+ * Whether a docdex search payload actually returned anything usable. Docdex
+ * answers with `hits: []` rather than an error when the index has no match, so
+ * an empty result is a normal outcome that the waterfall must recognize.
+ */
+const hasSearchHits = (payload) => {
+    if (!isRecord(payload))
+        return false;
+    for (const key of ["hits", "results", "matches"]) {
+        const value = payload[key];
+        if (Array.isArray(value) && value.length > 0)
+            return true;
+    }
+    return false;
+};
+/**
+ * Whether a forced-web search actually discovered anything.
+ *
+ * Docdex reports web findings under `webDiscovery.discovery.results` and leaves
+ * `hits` empty until the fetched pages are indexed, so judging a web result by
+ * `hits` alone throws away everything it just found.
+ */
+const hasWebFindings = (payload) => {
+    if (hasSearchHits(payload))
+        return true;
+    if (!isRecord(payload))
+        return false;
+    const discovery = isRecord(payload.webDiscovery) ? payload.webDiscovery : undefined;
+    if (!discovery)
+        return false;
+    const inner = isRecord(discovery.discovery) ? discovery.discovery : undefined;
+    const results = inner?.results ?? discovery.results;
+    if (Array.isArray(results) && results.length > 0)
+        return true;
+    const fetches = discovery.fetches;
+    return Array.isArray(fetches) && fetches.length > 0;
+};
+/**
+ * Whether a web-research payload carries anything quotable. Docdex answers a
+ * cache hit with discovery metadata only, which reads as success but gives a
+ * model nothing to cite.
+ */
+const hasWebContent = (payload) => {
+    if (!isRecord(payload))
+        return false;
+    for (const key of ["web_context", "webContext", "hits", "results"]) {
+        const value = payload[key];
+        if (Array.isArray(value) && value.length > 0)
+            return true;
+    }
+    return false;
+};
+const withDocdexMetadata = (tools) => tools.map((tool) => ({
+    ...tool,
+    readOnly: tool.readOnly ?? !DOCDEX_WRITE_TOOLS.has(tool.name),
+    capability: tool.capability ?? docdexCapabilityFor(tool.name),
+}));
+export const createDocdexTools = (client, options = {}) => withDocdexMetadata(docdexToolDefinitions(client, options));
+const docdexToolDefinitions = (client, options) => [
     {
         name: "docdex_health",
         description: "Check docdex healthz endpoint.",
@@ -30,7 +108,12 @@ export const createDocdexTools = (client) => [
     },
     {
         name: "docdex_search",
-        description: "Search docdex index.",
+        description: "Search the indexed repository and organizational memory for code, docs, and prior decisions. " +
+            "Searches locally first and falls back to the web when the local index has nothing relevant, " +
+            "so this is the default tool for both repo questions and general external questions. " +
+            "Returns file paths, doc ids, and a snippet from the START of each file — usually imports, " +
+            "not the part that answers the question. To explain what something does, follow up with " +
+            "docdex_symbols for its signature or docdex_open for the relevant lines.",
         inputSchema: {
             type: "object",
             required: ["query"],
@@ -41,13 +124,42 @@ export const createDocdexTools = (client) => [
         },
         handler: async (args) => {
             const { query, limit } = args;
-            const result = await client.search(query, { limit });
-            return toOutput(result);
+            const local = await client.search(query, { limit });
+            // The local-then-web waterfall lives here, inside the search tool, rather
+            // than in the orchestrator. The orchestrator should only have to know
+            // "search"; whether an answer comes from the repository index or the
+            // public web is an implementation detail of searching. Putting this
+            // decision in the router would make it special-case logic that every new
+            // question type has to be taught.
+            let localAnswers = hasSearchHits(local);
+            // Hits alone do not mean the question was answered. Ask a model whether
+            // they are actually relevant before settling for them.
+            if (localAnswers && options.judgeRelevance) {
+                try {
+                    localAnswers = await options.judgeRelevance({ query, results: local });
+                }
+                catch {
+                    // A judge that fails must not block a search that already succeeded.
+                }
+            }
+            if (!localAnswers) {
+                try {
+                    const web = await client.search(query, { limit, forceWeb: true });
+                    if (hasWebFindings(web)) {
+                        return toOutput(web);
+                    }
+                }
+                catch {
+                    // Web discovery being unavailable must not fail a local search that
+                    // simply found nothing. Return the local (empty) result instead.
+                }
+            }
+            return toOutput(local);
         },
     },
     {
         name: "docdex_open",
-        description: "Open a file by path or fetch a snippet by doc id.",
+        description: "Read an exact slice of a file, either by repo-relative path or by a doc id returned from a search. Use after a search has identified a target rather than guessing paths.",
         inputSchema: {
             type: "object",
             properties: {
@@ -76,7 +188,9 @@ export const createDocdexTools = (client) => [
     },
     {
         name: "docdex_symbols",
-        description: "Fetch docdex symbols for a file.",
+        description: "List the definitions in a file with their exact signatures and line numbers — functions, " +
+            "classes, methods, exported constants. Use after docdex_search to find out what a file " +
+            "actually contains, since search snippets only show the file's opening lines.",
         inputSchema: {
             type: "object",
             required: ["path"],
@@ -92,7 +206,7 @@ export const createDocdexTools = (client) => [
     },
     {
         name: "docdex_ast",
-        description: "Fetch docdex AST nodes for a file.",
+        description: "Query a file's syntax tree for precise structure: class and function definitions, call sites, imports. More exact than text search when the question is structural.",
         inputSchema: {
             type: "object",
             required: ["path"],
@@ -109,7 +223,7 @@ export const createDocdexTools = (client) => [
     },
     {
         name: "docdex_impact_graph",
-        description: "Fetch docdex impact graph for a file.",
+        description: "Show what depends on a file and what it depends on. Answers \"what breaks if this changes\" and identifies the blast radius of an edit.",
         inputSchema: {
             type: "object",
             required: ["file"],
@@ -128,7 +242,7 @@ export const createDocdexTools = (client) => [
     },
     {
         name: "docdex_impact_diagnostics",
-        description: "Fetch docdex impact diagnostics (dynamic imports).",
+        description: "List unresolved or dynamic imports that the dependency graph could not follow, so gaps in impact analysis are visible rather than silent.",
         inputSchema: {
             type: "object",
             properties: {
@@ -163,7 +277,7 @@ export const createDocdexTools = (client) => [
     },
     {
         name: "docdex_tree",
-        description: "Render a folder tree from docdex.",
+        description: "Render the repository folder tree with build output and vendor directories excluded. Use to orient in an unfamiliar repo instead of listing directories manually.",
         inputSchema: {
             type: "object",
             properties: {
@@ -218,7 +332,7 @@ export const createDocdexTools = (client) => [
     },
     {
         name: "docdex_get_profile",
-        description: "Fetch docdex profile preferences.",
+        description: "Read stored global preferences and constraints that should shape the answer, such as style rules or disallowed libraries.",
         inputSchema: {
             type: "object",
             properties: {
@@ -251,7 +365,7 @@ export const createDocdexTools = (client) => [
     },
     {
         name: "docdex_memory_recall",
-        description: "Recall repo memory from docdex.",
+        description: "Recall durable facts previously recorded about this repository - architectural decisions, gotchas, where things live.",
         inputSchema: {
             type: "object",
             required: ["query"],
@@ -268,7 +382,7 @@ export const createDocdexTools = (client) => [
     },
     {
         name: "docdex_web_research",
-        description: "Run docdex web research (requires DOCDEX_WEB_ENABLED=1).",
+        description: "Search the public web for current external information: facts, news, third-party documentation, anything not in this repository. Returns sourced results with URLs.",
         inputSchema: {
             type: "object",
             required: ["query"],
@@ -282,7 +396,27 @@ export const createDocdexTools = (client) => [
         },
         handler: async (args) => {
             const { query, forceWeb, skipLocalSearch, webLimit, noCache } = args;
-            const result = await client.webResearch(query, { forceWeb, skipLocalSearch, webLimit, noCache });
+            let result = await client.webResearch(query, { forceWeb, skipLocalSearch, webLimit, noCache });
+            // A cache hit returns discovery metadata with no page content at all —
+            // no web_context, no hits — so the run sees that a search happened and
+            // nothing it can quote. Retrying uncached fetches the pages the cache
+            // was standing in for.
+            if (!noCache && !hasWebContent(result)) {
+                try {
+                    const fresh = await client.webResearch(query, {
+                        forceWeb,
+                        skipLocalSearch,
+                        webLimit,
+                        noCache: true,
+                    });
+                    if (hasWebContent(fresh)) {
+                        result = fresh;
+                    }
+                }
+                catch {
+                    // Keep the cached response rather than failing a search that worked.
+                }
+            }
             return toOutput(result);
         },
     },
@@ -343,7 +477,7 @@ export const createDocdexTools = (client) => [
     },
     {
         name: "docdex_batch_search",
-        description: "Run batched docdex search queries via optional batch endpoint/tool.",
+        description: "Run several related search queries in one call. Use when a question decomposes into multiple independent lookups, to save round trips.",
         inputSchema: {
             type: "object",
             required: ["queries"],
@@ -376,7 +510,7 @@ export const createDocdexTools = (client) => [
     },
     {
         name: "docdex_stats",
-        description: "Fetch docdex index stats.",
+        description: "Report index size and when it was last updated. Use to detect a stale index before trusting a negative search result.",
         inputSchema: { type: "object", properties: {} },
         handler: async () => {
             const result = await client.stats();
@@ -385,7 +519,7 @@ export const createDocdexTools = (client) => [
     },
     {
         name: "docdex_files",
-        description: "List docdex indexed files.",
+        description: "List the files currently present in the index, to confirm coverage before concluding that something does not exist.",
         inputSchema: {
             type: "object",
             properties: {

package/dist/tools/filesystem/FileTools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FileTools.d.ts","sourceRoot":"","sources":["../../../src/tools/filesystem/FileTools.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAe,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAgEnE,eAAO,MAAM,eAAe,QAAO,cAAc,EAwFhD,CAAC"}
+{"version":3,"file":"FileTools.d.ts","sourceRoot":"","sources":["../../../src/tools/filesystem/FileTools.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAe,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAgEnE,eAAO,MAAM,eAAe,QAAO,cAAc,EAgGhD,CAAC"}

package/dist/tools/filesystem/FileTools.js

@@ -55,6 +55,8 @@ export const createFileTools = () => {
         {
             name: "read_file",
             description: "Read a text file from the workspace.",
+            readOnly: true,
+            capability: "workspace",
             inputSchema: {
                 type: "object",
                 required: ["path"],
@@ -73,6 +75,8 @@ export const createFileTools = () => {
         {
             name: "write_file",
             description: "Write content to a file inside the workspace.",
+            readOnly: false,
+            capability: "workspace",
             inputSchema: {
                 type: "object",
                 required: ["path", "content"],
@@ -96,6 +100,8 @@ export const createFileTools = () => {
         {
             name: "list_files",
             description: "List files under a directory within the workspace.",
+            readOnly: true,
+            capability: "workspace",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -115,6 +121,8 @@ export const createFileTools = () => {
         {
             name: "stat_path",
             description: "Get stat info for a file or directory.",
+            readOnly: true,
+            capability: "workspace",
             inputSchema: {
                 type: "object",
                 required: ["path"],

package/dist/tools/search/SearchTool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SearchTool.d.ts","sourceRoot":"","sources":["../../../src/tools/search/SearchTool.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAe,cAAc,EAAE,MAAM,iBAAiB,CAAC;AA0BnE,eAAO,MAAM,gBAAgB,QAAO,cAwBlC,CAAC"}
+{"version":3,"file":"SearchTool.d.ts","sourceRoot":"","sources":["../../../src/tools/search/SearchTool.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAe,cAAc,EAAE,MAAM,iBAAiB,CAAC;AA0BnE,eAAO,MAAM,gBAAgB,QAAO,cA0BlC,CAAC"}

package/dist/tools/search/SearchTool.js

@@ -22,7 +22,9 @@ const runGrepFallback = (query, cwd) => {
 };
 export const createSearchTool = () => ({
     name: "search_repo",
-    description: "Search for text in the workspace using rg when available.",
+    description: "Search for literal text in the working tree. Use when an exact string is known; prefer docdex_search for conceptual questions.",
+    readOnly: true,
+    capability: "workspace",
     inputSchema: {
         type: "object",
         required: ["query"],

package/dist/tools/shell/ShellTool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ShellTool.d.ts","sourceRoot":"","sources":["../../../src/tools/shell/ShellTool.ts"],"names":[],"mappings":"AAEA,OAAO,EAAwC,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAC;AA2C5F,eAAO,MAAM,eAAe,QAAO,cAyEjC,CAAC"}
+{"version":3,"file":"ShellTool.d.ts","sourceRoot":"","sources":["../../../src/tools/shell/ShellTool.ts"],"names":[],"mappings":"AAEA,OAAO,EAAwC,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAC;AA2C5F,eAAO,MAAM,eAAe,QAAO,cA2EjC,CAAC"}

package/dist/tools/shell/ShellTool.js

@@ -41,6 +41,8 @@ const isDestructiveShellAction = (command, args) => {
 export const createShellTool = () => ({
     name: "run_shell",
     description: "Run a shell command from the workspace root (allowlist only).",
+    readOnly: false,
+    capability: "shell",
     inputSchema: {
         type: "object",
         required: ["command"],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcoda/codali",
-  "version": "0.1.108",
+  "version": "0.1.110",
   "description": "Standalone tool-runner adapter for mcoda.",
   "type": "module",
   "main": "dist/index.js",
@@ -34,8 +34,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@mcoda/db": "0.1.108",
-    "@mcoda/shared": "0.1.108"
+    "@modelcontextprotocol/sdk": "1.30.0",
+    "@mcoda/db": "0.1.110",
+    "@mcoda/shared": "0.1.110"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",