@sean.holung/minicode 0.3.10 → 0.4.0

package/dist/src/tools/search-code-map.js

@@ -1,13 +1,99 @@
-import { expectNonEmptyString, expectOptionalNumber } from "@minicode/agent-sdk";
+import { expectNonEmptyString, expectOptionalNumber } from "@sean.holung/minicode-sdk";
 import { getSymbolDisplayName, getSymbolLookupNames } from "../indexer/symbol-names.js";
 import { searchSymbols } from "../shared/symbol-search.js";
 const DEFAULT_LIMIT = 30;
+const DOC_SUMMARY_MAX_CHARS = 100;
+/**
+ * Strip JSDoc/block-comment markers and return the first non-empty line of
+ * the comment, truncated.
+ *
+ * Surfacing this beside each match in `search_code_map` output is what
+ * addresses the disambiguation failure case from issue #184: when a search
+ * returns several similar-named symbols (e.g. `ToolRegistry` class +
+ * `createToolRegistry` wrapper + `ToolRegistry.createDefault` method), the
+ * model has no way to pick the right one from kind+path alone. The doc
+ * summary tells it which is which.
+ */
+export function summarizeDocComment(doc) {
+    if (!doc) {
+        return "";
+    }
+    // Strip leading /** and trailing */ — defense-in-depth; symbol indexing
+    // already cleans most of this.
+    const lines = doc
+        .replace(/^\s*\/\*\*?/, "")
+        .replace(/\*\/\s*$/, "")
+        // TS compiler can emit JSDoc with `\r` line separators (not `\n`),
+        // so we split on both. Without this, the entire comment becomes a
+        // single "line" and the truncation chops mid-paragraph rather than
+        // at the first description sentence.
+        .split(/\r\n|\r|\n/)
+        .map((line) => line.replace(/^\s*\*\s?/, "").trim())
+        .filter((line) => line.length > 0);
+    if (lines.length === 0) {
+        return "";
+    }
+    const first = lines[0];
+    if (first.length <= DOC_SUMMARY_MAX_CHARS) {
+        return first;
+    }
+    return `${first.slice(0, DOC_SUMMARY_MAX_CHARS - 3)}...`;
+}
+/**
+ * When a search returns matches of multiple symbol kinds (class, function,
+ * method, …) for what is likely the same conceptual name, the model can
+ * confidently pick the wrong one — particularly for queries like
+ * `ToolRegistry` that resolve to a class, several class methods, and a
+ * standalone wrapper function. This is exactly the failure shape from
+ * issue #184. We surface the ambiguity so the model knows to refine
+ * rather than guess.
+ *
+ * The hint fires only on cross-kind ambiguity (class/interface/type AND
+ * function/method) — the typical "noun vs. verb" shape (`Foo` class vs.
+ * `createFoo()` factory). Methods alone alongside their class are
+ * structurally expected and not flagged.
+ */
+export function buildAmbiguityHint(matches) {
+    const kinds = new Set(matches.map((m) => m.kind));
+    if (kinds.size <= 1) {
+        return "";
+    }
+    const hasNoun = kinds.has("class") || kinds.has("interface") || kinds.has("type");
+    // Standalone functions only — class methods alongside their class
+    // (e.g. `Widget` + `Widget.init`) are a structurally expected pairing,
+    // not a disambiguation problem. The model already understands that
+    // `Foo.method` is a member of `Foo`. The real confusion is between a
+    // type-name and a same-base-name standalone function (`Widget` class
+    // vs. `createWidget()` factory).
+    //
+    // Trade-off: this deliberately under-flags the rarer cross-class case
+    // (`class Widget` in one file plus an unrelated `widget()` method on
+    // some other class). Adding `method` to the verb set would close that
+    // gap but would also make the hint fire on every class-with-its-own-
+    // methods search, which is by far the more common shape — false
+    // positives there would be louder than the missed cross-class case.
+    const hasStandaloneVerb = kinds.has("function");
+    if (!hasNoun || !hasStandaloneVerb) {
+        return "";
+    }
+    return [
+        "Note: results span multiple symbol kinds. A class/interface/type and a function/method with similar",
+        "names usually have different responsibilities (e.g. `Foo` class vs. `createFoo()` factory). Read the",
+        "doc summaries below or call `read_symbol` on a specific candidate before assuming which one the",
+        "question is about.",
+    ].join("\n");
+}
+function formatMatchLine(s) {
+    const main = `- ${getSymbolDisplayName(s)} (${s.kind}) — ${s.filePath}:${s.startLine} — qualified: ${s.qualifiedName}`;
+    const summary = summarizeDocComment(s.docComment);
+    return summary ? `${main}\n    └─ ${summary}` : main;
+}
 export function createSearchCodeMapTool(projectIndex) {
     return {
         name: "search_code_map",
         description: "Search the full project index for symbols by name or substring. " +
             "Use when the code map is truncated and you need to find a symbol not listed. " +
-            "Returns disambiguated display names, qualified names, and file paths; use read_symbol with the result.",
+            "Returns disambiguated display names, qualified names, file paths, and a one-line doc summary; use read_symbol with the result.",
         inputSchema: {
             type: "object",
             properties: {
@@ -52,10 +138,10 @@ export function createSearchCodeMapTool(projectIndex) {
                 lookupNames: getSymbolLookupNames(sym),
             })), pattern, { kind, limit, skip });
             const shown = result.matches;
-            const lines = shown.map((s) => `- ${getSymbolDisplayName(s)} (${s.kind}) — ${s.filePath}:${s.startLine} — qualified: ${s.qualifiedName}`);
+            const lines = shown.map(formatMatchLine);
             const remaining = result.total - skip - shown.length;
             const footer = remaining > 0
-                ? `\n... and ${remaining} more (use skip: ${skip + limit}, limit: ${limit} for next page)`
+                ? `\n... and ${remaining} more. Use skip: ${skip + limit}, limit: ${limit} for the next page, or refine the pattern to narrow.`
                 : "";
             if (result.total === 0) {
                 return `No symbols matching "${pattern}"${kind ? ` (kind: ${kind})` : ""}. Try a shorter or different pattern.`;
@@ -70,12 +156,18 @@ export function createSearchCodeMapTool(projectIndex) {
                     footer,
                 ].join("\n");
             }
-            return [
+            const ambiguityHint = buildAmbiguityHint(shown);
+            const sections = [
                 `# Symbols matching "${pattern}" (${result.total} total)`,
-                "",
-                ...lines,
-                footer,
-            ].join("\n");
+            ];
+            if (ambiguityHint) {
+                sections.push("", ambiguityHint);
+            }
+            sections.push("", ...lines);
+            if (footer) {
+                sections.push(footer);
+            }
+            return sections.join("\n");
         },
     };
 }

package/dist/src/ui/cli-ink.js

@@ -1,5 +1,5 @@
 import process from "node:process";
-import { CodingAgent, createModelClient } from "@minicode/agent-sdk";
+import { CodingAgent, createModelClient } from "@sean.holung/minicode-sdk";
 import { loadAgentConfig, getConfigSetupMessage } from "../agent/config.js";
 import { handleConfigSlashCommand } from "../cli/config-slash-command.js";
 import { computeFileHashes, getWorkspaceCacheDir, loadIndex, saveIndex, } from "../indexer/cache.js";

package/dist/tests/agent.test.js

@@ -1,7 +1,7 @@
 import assert from "node:assert/strict";
 import path from "node:path";
 import { test } from "node:test";
-import { CodingAgent, ToolRegistry, } from "@minicode/agent-sdk";
+import { CodingAgent, ToolRegistry, } from "@sean.holung/minicode-sdk";
 import { buildProjectIndex } from "../src/indexer/project-index.js";
 import { createTestAgentConfig } from "./test-utils.js";
 class SequenceModelClient {

package/dist/tests/context-indicator.test.js

@@ -5,7 +5,7 @@ import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { createRequestHandler } from "../src/serve/server.js";
 import { AgentBridge } from "../src/serve/agent-bridge.js";
-import { CodingAgent, ToolRegistry, } from "@minicode/agent-sdk";
+import { CodingAgent, ToolRegistry, } from "@sean.holung/minicode-sdk";
 import { UiStore } from "../src/ui/state/ui-store.js";
 import { createTestAgentConfig } from "./test-utils.js";
 const distWeb = join(import.meta.dirname, "..", "dist", "src", "web");

package/dist/tests/file-tools.test.js

@@ -3,7 +3,7 @@ import { mkdtemp, readFile, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import { test } from "node:test";
-import { createEditFileTool, createReadFileTool, createRunCommandTool, createWriteFileTool } from "@minicode/agent-sdk";
+import { createEditFileTool, createReadFileTool, createRunCommandTool, createWriteFileTool } from "@sean.holung/minicode-sdk";
 import { buildProjectIndex } from "../src/indexer/project-index.js";
 import { createToolRegistry } from "../src/tools/registry.js";
 import { createTestAgentConfig } from "./test-utils.js";
@@ -33,7 +33,7 @@ test("edit_file fails when old_string is not unique", async () => {
         path: "sample.txt",
         old_string: "repeat",
         new_string: "once",
-    }), /matched 3 times/);
+    }), /multiple matches/i);
     const unchanged = await readFile(filePath, "utf8");
     assert.equal(unchanged, "repeat repeat repeat");
 });

package/dist/tests/focus-tracker.test.js

@@ -1,6 +1,6 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
-import { FocusTracker } from "@minicode/agent-sdk";
+import { FocusTracker } from "@sean.holung/minicode-sdk";
 test("FocusTracker tracks added symbols", () => {
     const tracker = new FocusTracker();
     tracker.addSymbol("Foo");

package/dist/tests/guardrails.test.js

@@ -1,6 +1,6 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
-import { resolveWorkspacePath, validateCommand, validatePath, } from "@minicode/agent-sdk";
+import { resolveWorkspacePath, validateCommand, validatePath, } from "@sean.holung/minicode-sdk";
 test("validatePath allows files within workspace", () => {
     const workspaceRoot = "/tmp/workspace";
     assert.equal(validatePath("src/index.ts", workspaceRoot), true);

package/dist/tests/indexer.test.js

@@ -168,11 +168,29 @@ test("Code map handles empty symbols map", () => {
     assert.ok(result.text.includes("# Project Code Map"));
     assert.ok(result.text.length < 100);
 });
+test("Code map honors MINICODE_CODE_MAP_FORMAT=full opt-out", () => {
+    const symbols = typescriptPlugin.indexFile("sample.ts", SAMPLE_TS);
+    const byFile = new Map([["sample.ts", symbols]]);
+    const prev = process.env.MINICODE_CODE_MAP_FORMAT;
+    process.env.MINICODE_CODE_MAP_FORMAT = "full";
+    try {
+        const result = generateCodeMap(byFile);
+        // Full format prefixes each non-method symbol with the bare kind keyword
+        // (e.g. "class CodingAgent") and emits a separate signature line.
+        assert.ok(result.text.includes("class CodingAgent"), "full format prefixes class keyword");
+    }
+    finally {
+        if (prev === undefined)
+            delete process.env.MINICODE_CODE_MAP_FORMAT;
+        else
+            process.env.MINICODE_CODE_MAP_FORMAT = prev;
+    }
+});
 test("Code map nests methods under class", () => {
     const symbols = typescriptPlugin.indexFile("sample.ts", SAMPLE_TS);
     const byFile = new Map([["sample.ts", symbols]]);
     const result = generateCodeMap(byFile);
-    assert.ok(result.text.includes("class CodingAgent"));
+    assert.ok(result.text.includes("CodingAgent (class)"));
     assert.ok(result.text.includes("runTurn"));
     const runTurnLine = result.text.split("\n").find((l) => l.includes("runTurn"));
     assert.ok(runTurnLine?.startsWith("    "), "method should be indented under class");
@@ -197,19 +215,32 @@ test("reindexFile updates symbols and code map after file change", async () => {
     const updatedSym = index.getSymbol("greet");
     assert.ok(updatedSym, "should still find greet");
     assert.ok(updatedSym.signature.includes("title?: string"), "signature should reflect updated params");
-    const codeMap = index.getCodeMap();
-    assert.ok(codeMap.text.includes("title?: string"), "code map should reflect new signature");
+    // Verify the code map is regenerated after reindex. The default named
+    // format doesn't include signatures, so we opt into the full format
+    // here to assert the signature change flows through.
+    const prev = process.env.MINICODE_CODE_MAP_FORMAT;
+    process.env.MINICODE_CODE_MAP_FORMAT = "full";
+    try {
+        const codeMap = index.getCodeMap();
+        assert.ok(codeMap.text.includes("title?: string"), "code map should reflect new signature");
+    }
+    finally {
+        if (prev === undefined)
+            delete process.env.MINICODE_CODE_MAP_FORMAT;
+        else
+            process.env.MINICODE_CODE_MAP_FORMAT = prev;
+    }
 });
 test("buildProjectIndex preserves colliding top-level symbols with distinct display names", async () => {
     const workspaceRoot = await mkdtemp(path.join(tmpdir(), "minicode-colliding-symbols-"));
     const samplePath = path.join(workspaceRoot, "sample.ts");
-    const content = `export interface Employee {
-  id: string;
-}
-
-export class Employee {
-  constructor(public id: string) {}
-}
+    const content = `export interface Employee {
+  id: string;
+}
+
+export class Employee {
+  constructor(public id: string) {}
+}
 `;
     await writeFile(samplePath, content, "utf8");
     const index = await buildProjectIndex(workspaceRoot);
@@ -227,8 +258,8 @@ export class Employee {
     assert.equal(employeeClass.kind, "class");
     assert.equal(employeeInterface.kind, "interface");
     const codeMap = index.getCodeMap();
-    assert.ok(codeMap.text.includes("interface Employee (interface)"));
-    assert.ok(codeMap.text.includes("class Employee (class)"));
+    assert.ok(codeMap.text.includes("Employee (interface)"));
+    assert.ok(codeMap.text.includes("Employee (class)"));
     const resolved = index.getSymbol("Employee");
     assert.ok(resolved, "bare lookup should still resolve one of the colliding symbols");
     assert.ok(resolved.displayName === "Employee (class)" || resolved.displayName === "Employee (interface)", "resolved symbol should use a disambiguated display name");
@@ -359,23 +390,23 @@ function beta() {}
     assert.ok(callEdge, "should resolve dependencies even without cached AST");
 });
 test("resolveDependencies prefers same-file symbols over same-named helpers in other files", () => {
-    const projectIndexCode = `
-async function collectSourceFiles(dir: string): Promise<void> {
-  await collectSourceFiles(dir + "/nested");
-}
-
-export async function buildProjectIndex(): Promise<void> {
-  await collectSourceFiles("src");
-}
+    const projectIndexCode = `
+async function collectSourceFiles(dir: string): Promise<void> {
+  await collectSourceFiles(dir + "/nested");
+}
+
+export async function buildProjectIndex(): Promise<void> {
+  await collectSourceFiles("src");
+}
 `;
-    const cacheCode = `
-async function collectSourceFiles(dir: string): Promise<void> {
-  await collectSourceFiles(dir + "/cached");
-}
-
-export async function computeFileHashes(): Promise<void> {
-  await collectSourceFiles("src");
-}
+    const cacheCode = `
+async function collectSourceFiles(dir: string): Promise<void> {
+  await collectSourceFiles(dir + "/cached");
+}
+
+export async function computeFileHashes(): Promise<void> {
+  await collectSourceFiles("src");
+}
 `;
     const byFile = new Map([
         ["src/indexer/project-index.ts", typescriptPlugin.indexFile("src/indexer/project-index.ts", projectIndexCode)],

package/dist/tests/model-client-openai.test.js

@@ -1,6 +1,6 @@
 import assert from "node:assert/strict";
 import { test } from "node:test";
-import { OpenAICompatibleModelClient, createModelClient, } from "@minicode/agent-sdk";
+import { OpenAICompatibleModelClient, createModelClient, } from "@sean.holung/minicode-sdk";
 import { createTestAgentConfig } from "./test-utils.js";
 test("openai-compatible client sends tool schemas and parses tool calls", async () => {
     let capturedUrl = "";

package/dist/tests/model-selection.test.js

@@ -1,7 +1,7 @@
 import assert from "node:assert/strict";
 import { test } from "node:test";
 import { createServer } from "node:http";
-import { OpenAICompatibleModelClient } from "@minicode/agent-sdk";
+import { OpenAICompatibleModelClient } from "@sean.holung/minicode-sdk";
 import { createRequestHandler } from "../src/serve/server.js";
 import { AgentBridge } from "../src/serve/agent-bridge.js";
 import { createTestAgentConfig } from "./test-utils.js";

package/dist/tests/python-plugin.test.js

@@ -37,9 +37,9 @@ test("buildProjectIndex indexes a Python workspace", async () => {
     assert.ok(index.getSymbol("Foo.bar"));
     assert.ok(index.getSymbol("baz"));
     const codeMap = index.getCodeMap();
-    assert.ok(codeMap.text.includes("class Foo"));
-    assert.ok(codeMap.text.includes("def bar"));
-    assert.ok(codeMap.text.includes("def baz"));
+    assert.ok(codeMap.text.includes("Foo (class)"));
+    assert.ok(codeMap.text.includes("bar"));
+    assert.ok(codeMap.text.includes("baz"));
 });
 test("verify-index-python fixture exercises the indexing pipeline", async () => {
     const root = path.resolve(import.meta.dirname, "..");

package/dist/tests/read-symbol.test.js

@@ -27,6 +27,11 @@ test("read_symbol returns error for unknown symbol name", async () => {
     const result = await tool.execute({ name: "NonExistentSymbol123" });
     assert.ok(result.includes("not found"));
     assert.ok(result.includes("search") || result.includes("read_file"));
+    // Miss path should preferentially nudge toward search_code_map (the
+    // graph-aware retry) before suggesting full-file reads — otherwise
+    // the agent abandons minicode's symbol-aware path the moment it
+    // hits a single miss.
+    assert.ok(result.includes("search_code_map"), `expected miss message to suggest search_code_map; got: ${result}`);
 });
 test("read_symbol with includeBody: false returns signature only", async () => {
     const root = path.resolve(import.meta.dirname, "..");
@@ -66,6 +71,75 @@ test("read_symbol appears in tool registry schemas when projectIndex provided",
     const props = readSymbol.input_schema.properties;
     assert.ok(props && "name" in props);
 });
+test("MINICODE_TOOL_PROFILE=file-search-only omits the five graph-aware tools", async () => {
+    const root = path.resolve(import.meta.dirname, "..");
+    const config = createTestAgentConfig(root);
+    const projectIndex = await buildProjectIndex(root);
+    const original = process.env.MINICODE_TOOL_PROFILE;
+    process.env.MINICODE_TOOL_PROFILE = "file-search-only";
+    try {
+        const registry = createToolRegistry(config, projectIndex);
+        const schemas = registry.getToolSchemas();
+        const names = new Set(schemas.map((s) => s.name));
+        // Graph-aware tools must be absent in file-search-only mode.
+        for (const omitted of [
+            "read_symbol",
+            "find_references",
+            "get_dependencies",
+            "find_path",
+            "search_code_map",
+        ]) {
+            assert.ok(!names.has(omitted), `expected ${omitted} to be absent`);
+        }
+        // Core file/search/run tools must still be present — that's the
+        // "search-only" half of the profile name.
+        for (const required of [
+            "read_file",
+            "write_file",
+            "edit_file",
+            "search",
+            "list_files",
+            "run_command",
+        ]) {
+            assert.ok(names.has(required), `expected ${required} to be present`);
+        }
+    }
+    finally {
+        if (original === undefined) {
+            delete process.env.MINICODE_TOOL_PROFILE;
+        }
+        else {
+            process.env.MINICODE_TOOL_PROFILE = original;
+        }
+    }
+});
+test("createToolRegistry includes graph-aware tools by default when projectIndex is provided", async () => {
+    const root = path.resolve(import.meta.dirname, "..");
+    const config = createTestAgentConfig(root);
+    const projectIndex = await buildProjectIndex(root);
+    // Must run with no MINICODE_TOOL_PROFILE set, otherwise the env from a
+    // host shell would mask the default behavior.
+    const original = process.env.MINICODE_TOOL_PROFILE;
+    delete process.env.MINICODE_TOOL_PROFILE;
+    try {
+        const registry = createToolRegistry(config, projectIndex);
+        const names = new Set(registry.getToolSchemas().map((s) => s.name));
+        for (const required of [
+            "read_symbol",
+            "find_references",
+            "get_dependencies",
+            "find_path",
+            "search_code_map",
+        ]) {
+            assert.ok(names.has(required), `expected ${required} to be present by default`);
+        }
+    }
+    finally {
+        if (original !== undefined) {
+            process.env.MINICODE_TOOL_PROFILE = original;
+        }
+    }
+});
 test("read_symbol includes Referenced Types section for createToolRegistry", async () => {
     const root = path.resolve(import.meta.dirname, "..");
     const config = createTestAgentConfig(root);
@@ -77,11 +151,11 @@ test("read_symbol includes Referenced Types section for createToolRegistry", asy
 });
 test("read_symbol returns disambiguation list for ambiguous bare symbol names", async () => {
     const workspaceRoot = await mkdtemp(path.join(tmpdir(), "minicode-read-symbol-collisions-"));
-    await writeFile(path.join(workspaceRoot, "sample.ts"), `export type Review = { id: string };
-
-export class Review {
-  constructor(public id: string) {}
-}
+    await writeFile(path.join(workspaceRoot, "sample.ts"), `export type Review = { id: string };
+
+export class Review {
+  constructor(public id: string) {}
+}
 `, "utf8");
     const config = createTestAgentConfig(workspaceRoot);
     const projectIndex = await buildProjectIndex(workspaceRoot);
@@ -95,11 +169,11 @@ export class Review {
 });
 test("read_symbol accepts qualified names for colliding symbols", async () => {
     const workspaceRoot = await mkdtemp(path.join(tmpdir(), "minicode-read-symbol-qualified-"));
-    await writeFile(path.join(workspaceRoot, "sample.ts"), `export type Review = { id: string };
-
-export class Review {
-  constructor(public id: string) {}
-}
+    await writeFile(path.join(workspaceRoot, "sample.ts"), `export type Review = { id: string };
+
+export class Review {
+  constructor(public id: string) {}
+}
 `, "utf8");
     const config = createTestAgentConfig(workspaceRoot);
     const projectIndex = await buildProjectIndex(workspaceRoot);

package/dist/tests/reasoning-effort.test.js

@@ -1,6 +1,6 @@
 import assert from "node:assert/strict";
 import { test } from "node:test";
-import { OpenAICompatibleModelClient, CodingAgent, ToolRegistry, } from "@minicode/agent-sdk";
+import { OpenAICompatibleModelClient, CodingAgent, ToolRegistry, } from "@sean.holung/minicode-sdk";
 import { createTestAgentConfig } from "./test-utils.js";
 import { loadAgentConfig } from "../src/agent/config.js";
 // ---------------------------------------------------------------------------

package/dist/tests/search-code-map.test.js

@@ -4,7 +4,7 @@ import path from "node:path";
 import { tmpdir } from "node:os";
 import { test } from "node:test";
 import { buildProjectIndex } from "../src/indexer/project-index.js";
-import { createSearchCodeMapTool } from "../src/tools/search-code-map.js";
+import { buildAmbiguityHint, createSearchCodeMapTool, summarizeDocComment, } from "../src/tools/search-code-map.js";
 test("search_code_map finds symbols by substring", async () => {
     const root = path.resolve(import.meta.dirname, "..");
     const projectIndex = await buildProjectIndex(root);
@@ -57,3 +57,134 @@ export class Employee {
     assert.ok(result.includes("qualified: Employee#interface"));
     assert.ok(result.includes("qualified: Employee#class"));
 });
+// ─── Issue #184: disambiguation hints + doc summaries ──────────────────
+test("search_code_map surfaces JSDoc summaries beside each match (issue #184)", async () => {
+    const workspaceRoot = await mkdtemp(path.join(tmpdir(), "minicode-doc-summaries-"));
+    await writeFile(path.join(workspaceRoot, "sample.ts"), `/**
+ * Create a default ToolWidget with all builtin gears.
+ * Wraps the SDK class for application-level setup.
+ */
+export function createToolWidget(): ToolWidget {
+  return new ToolWidget();
+}
+
+export class ToolWidget {
+  constructor() {}
+}
+`, "utf8");
+    const projectIndex = await buildProjectIndex(workspaceRoot);
+    const tool = createSearchCodeMapTool(projectIndex);
+    const result = await tool.execute({ pattern: "ToolWidget" });
+    // The doc summary's first line should appear under the createToolWidget
+    // entry — without it, the model can't tell `ToolWidget` (the class) apart
+    // from `createToolWidget` (the factory) by kind+path alone.
+    assert.match(result, /Create a default ToolWidget with all builtin gears\./);
+    // Each shown match should still expose its qualified name, intact.
+    assert.match(result, /qualified: ToolWidget/);
+    assert.match(result, /qualified: createToolWidget/);
+});
+test("search_code_map prepends an ambiguity hint when matches span class + function (issue #184)", async () => {
+    const workspaceRoot = await mkdtemp(path.join(tmpdir(), "minicode-ambiguity-"));
+    await writeFile(path.join(workspaceRoot, "sample.ts"), `export class Widget {
+  constructor() {}
+}
+
+export function createWidget(): Widget {
+  return new Widget();
+}
+`, "utf8");
+    const projectIndex = await buildProjectIndex(workspaceRoot);
+    const tool = createSearchCodeMapTool(projectIndex);
+    const result = await tool.execute({ pattern: "Widget" });
+    // The hint specifically calls out the noun-vs-verb-form shape that
+    // led to the find-tool-registration regression.
+    assert.match(result, /Note: results span multiple symbol kinds/);
+    assert.match(result, /class\/interface\/type and a function\/method/);
+    assert.match(result, /read_symbol/);
+});
+test("search_code_map does NOT prepend the ambiguity hint when matches are all the same kind", async () => {
+    const workspaceRoot = await mkdtemp(path.join(tmpdir(), "minicode-no-ambiguity-"));
+    await writeFile(path.join(workspaceRoot, "sample.ts"), `export function widgetA(): void {}
+export function widgetB(): void {}
+export function widgetC(): void {}
+`, "utf8");
+    const projectIndex = await buildProjectIndex(workspaceRoot);
+    const tool = createSearchCodeMapTool(projectIndex);
+    const result = await tool.execute({ pattern: "widget" });
+    // All three are functions — no ambiguity to flag.
+    assert.doesNotMatch(result, /results span multiple symbol kinds/);
+});
+test("search_code_map does NOT prepend the ambiguity hint for class-with-its-methods", async () => {
+    const workspaceRoot = await mkdtemp(path.join(tmpdir(), "minicode-class-methods-"));
+    await writeFile(path.join(workspaceRoot, "sample.ts"), `export class Widget {
+  init(): void {}
+  destroy(): void {}
+}
+`, "utf8");
+    const projectIndex = await buildProjectIndex(workspaceRoot);
+    const tool = createSearchCodeMapTool(projectIndex);
+    const result = await tool.execute({ pattern: "Widget" });
+    // class + methods is a structurally expected pairing, not a noun/verb
+    // disambiguation problem. The hint should stay quiet here.
+    assert.doesNotMatch(result, /results span multiple symbol kinds/);
+});
+// ─── Direct helper unit tests ──────────────────────────────────────────
+test("summarizeDocComment returns empty string for missing input", () => {
+    assert.equal(summarizeDocComment(undefined), "");
+    assert.equal(summarizeDocComment(""), "");
+    assert.equal(summarizeDocComment("   \n  \n"), "");
+});
+test("summarizeDocComment strips JSDoc markers and returns first non-empty line", () => {
+    const input = "/**\n * First sentence here.\n * More detail.\n */";
+    assert.equal(summarizeDocComment(input), "First sentence here.");
+});
+test("summarizeDocComment splits on \\r-only line separators (TS compiler shape)", () => {
+    // The TS compiler stores docComment with `\r` line separators on some
+    // platforms — without explicit `\r` handling the whole comment becomes
+    // a single line and the truncation chops mid-paragraph rather than at
+    // the first description sentence.
+    const input = "First sentence.\rSecond sentence.\rThird sentence.";
+    assert.equal(summarizeDocComment(input), "First sentence.");
+});
+test("summarizeDocComment truncates long first lines with ellipsis", () => {
+    const longLine = "a".repeat(150);
+    const result = summarizeDocComment(longLine);
+    assert.equal(result.length, 100);
+    assert.ok(result.endsWith("..."));
+});
+function makeSymbol(kind, name = "X") {
+    return {
+        name,
+        qualifiedName: name,
+        kind,
+        filePath: "x.ts",
+        startLine: 1,
+        endLine: 1,
+        exported: true,
+    };
+}
+test("buildAmbiguityHint stays quiet when all matches share one kind", () => {
+    const matches = [makeSymbol("function"), makeSymbol("function")];
+    assert.equal(buildAmbiguityHint(matches), "");
+});
+test("buildAmbiguityHint stays quiet for class-with-its-methods", () => {
+    const matches = [makeSymbol("class"), makeSymbol("method"), makeSymbol("method")];
+    assert.equal(buildAmbiguityHint(matches), "");
+});
+test("buildAmbiguityHint fires for class + standalone function (noun-vs-verb)", () => {
+    const matches = [makeSymbol("class"), makeSymbol("function")];
+    const hint = buildAmbiguityHint(matches);
+    assert.match(hint, /results span multiple symbol kinds/);
+    assert.match(hint, /read_symbol/);
+});
+test("buildAmbiguityHint fires for interface + standalone function", () => {
+    const matches = [makeSymbol("interface"), makeSymbol("function")];
+    assert.match(buildAmbiguityHint(matches), /results span multiple symbol kinds/);
+});
+test("buildAmbiguityHint stays quiet when only methods accompany the noun (no standalone function)", () => {
+    // Documents the deliberate trade-off: cross-class method collisions
+    // are under-flagged to avoid noisy false positives on the more
+    // common class-with-its-own-methods shape.
+    const matches = [makeSymbol("class"), makeSymbol("method")];
+    assert.equal(buildAmbiguityHint(matches), "");
+});

package/dist/tests/serve.integration.test.js

@@ -6,7 +6,7 @@ import os from "node:os";
 import path from "node:path";
 import { createRequestHandler, shutdownServe } from "../src/serve/server.js";
 import { AgentBridge } from "../src/serve/agent-bridge.js";
-import { Session } from "@minicode/agent-sdk";
+import { Session } from "@sean.holung/minicode-sdk";
 import { DuplicateSessionLabelError } from "../src/session/session-store.js";
 import { createTestAgentConfig } from "./test-utils.js";
 /**