@specship/specship-win32-arm64 0.15.0 → 0.17.0

package/lib/dist/mcp/tools.js

@@ -10,9 +10,13 @@ exports.getExploreBudget = getExploreBudget;
 exports.getExploreOutputBudget = getExploreOutputBudget;
 exports.formatStaleBanner = formatStaleBanner;
 exports.formatStaleFooter = formatStaleFooter;
+exports.integrationEnabled = integrationEnabled;
+exports.toolIntegration = toolIntegration;
+exports.filterIntegrationTools = filterIntegrationTools;
 exports.getStaticTools = getStaticTools;
 const directory_1 = require("../directory");
 const statusline_1 = require("../statusline");
+const model_context_1 = require("./model-context");
 // Lazy-load the heavy SpecShip chain off the MCP startup path — see the same
 // helper in engine.ts. ToolHandler must load to answer tools/list (static
 // schemas), but it must NOT drag in sqlite/query layers before the daemon binds;
@@ -469,6 +473,25 @@ exports.tools = [
     // Independent of the code graph.
     ...jira_tools_1.jiraToolDefinitions,
 ];
+function integrationEnabled(name, env = process.env) {
+    const raw = env.SPECSHIP_INTEGRATIONS ?? '';
+    return raw.split(',').map((s) => s.trim().toLowerCase()).includes(name);
+}
+/** Which integration (if any) a tool belongs to. Core tools return null. */
+function toolIntegration(toolName) {
+    if (toolName.startsWith('designer_'))
+        return 'designer';
+    if (toolName.startsWith('specship_jira_'))
+        return 'jira';
+    return null;
+}
+/** Drop tools whose integration isn't enabled (REQ-INTEG-001.A1/A2). */
+function filterIntegrationTools(list, env = process.env) {
+    return list.filter((t) => {
+        const integ = toolIntegration(t.name);
+        return integ === null || integrationEnabled(integ, env);
+    });
+}
 /**
  * Allowlist-filtered tool definitions WITHOUT an engine — the static surface the
  * proxy answers `tools/list` with before any project is open. Mirrors
@@ -476,11 +499,12 @@ exports.tools = [
  * note in a description only adds once `cg` is loaded; the schemas are static).
  */
 function getStaticTools() {
+    const base = filterIntegrationTools(exports.tools);
     const raw = process.env.SPECSHIP_MCP_TOOLS;
     if (!raw || !raw.trim())
-        return exports.tools;
+        return base;
     const allow = new Set(raw.split(',').map(s => s.trim().replace(/^specship_/, '')).filter(Boolean));
-    return allow.size ? exports.tools.filter(t => allow.has(t.name.replace(/^specship_/, ''))) : exports.tools;
+    return allow.size ? base.filter(t => allow.has(t.name.replace(/^specship_/, ''))) : base;
 }
 /**
  * Tool handler that executes tools against a SpecShip instance
@@ -572,10 +596,13 @@ class ToolHandler {
      * allowlist so a trimmed surface is reflected in ListTools.
      */
     getTools() {
+        // Integration tier first (INTEG-TIER-DOC): jira/designer tools exist only
+        // when explicitly enabled, before any allowlist/size gating applies.
+        const base = filterIntegrationTools(exports.tools);
         const allow = this.toolAllowlist();
         let visible = allow
-            ? exports.tools.filter(t => allow.has(t.name.replace(/^specship_/, '')))
-            : exports.tools;
+            ? base.filter(t => allow.has(t.name.replace(/^specship_/, '')))
+            : base;
         if (!this.cg)
             return visible;
         try {
@@ -614,6 +641,22 @@ class ToolHandler {
                 // economics that justify trimming don't apply, so they always survive.
                 visible = visible.filter(t => TINY_REPO_CORE_TOOLS.has(t.name) || t.name.startsWith('designer_'));
             }
+            // Haiku-tier menu trim (LOWMODEL-DOC, REQ-LOWMODEL-004): small-model
+            // tool choice degrades with menu size, so the code-graph group trims
+            // to the core three; spec/link tools and enabled integrations are
+            // untouched. Composes with the tiny-repo gate as an intersection.
+            // Schemas never vary — only the list; `execute()` still answers a
+            // trimmed-away tool for clients that cached the full list (A2).
+            if ((0, model_context_1.detectModelTier)(this.cg.getProjectRoot()) === 'haiku') {
+                const HAIKU_CORE = new Set(['specship_explore', 'specship_search', 'specship_node']);
+                const CODE_GRAPH_GROUP = new Set([
+                    'specship_explore', 'specship_search', 'specship_node',
+                    'specship_callers', 'specship_callees', 'specship_impact',
+                    'specship_files', 'specship_status',
+                    'specship_maintainability', 'specship_fitness',
+                ]);
+                visible = visible.filter(t => !CODE_GRAPH_GROUP.has(t.name) || HAIKU_CORE.has(t.name));
+            }
             return visible.map(tool => {
                 if (tool.name === 'specship_explore') {
                     return {
@@ -798,6 +841,58 @@ class ToolHandler {
      * Cost when nothing is pending — the common case — is one boolean check.
      * No I/O, no parsing of markdown beyond a per-pending-file substring scan.
      */
+    /**
+     * Model-aware compaction (MODCTX-DOC, REQ-MODCTX-002/003). Resolves the
+     * session's model tier (status-line marker / SPECSHIP_MODEL; SPECSHIP_COMPACT=0
+     * disables) and, on haiku/sonnet, compresses the response's prose
+     * scaffolding — fenced code stays byte-verbatim. Full tier is identity.
+     */
+    /**
+     * Tier-change listeners (LOWMODEL-DOC, REQ-LOWMODEL-004.A3): the haiku
+     * menu trim changes `tools/list`, so a mid-session /model switch must ride
+     * an MCP `notifications/tools/list_changed`. Sessions subscribe here; the
+     * change is detected on the next code-graph call (the same funnel that
+     * reads the tier for compaction).
+     */
+    tierListeners = new Set();
+    lastTier = null;
+    addTierChangeListener(cb) {
+        this.tierListeners.add(cb);
+        return () => this.tierListeners.delete(cb);
+    }
+    noteTier(tier) {
+        if (this.lastTier !== null && tier !== this.lastTier) {
+            for (const cb of this.tierListeners) {
+                try {
+                    cb(tier);
+                }
+                catch { /* a listener must never break a tool call */ }
+            }
+        }
+        this.lastTier = tier;
+    }
+    withModelCompaction(result) {
+        if (result.isError)
+            return result;
+        let root = null;
+        try {
+            root = this.cg?.getProjectRoot() ?? null;
+        }
+        catch {
+            root = null;
+        }
+        const tier = (0, model_context_1.detectModelTier)(root);
+        this.noteTier(tier);
+        if (tier === 'full')
+            return result;
+        const first = result.content?.[0];
+        if (!first || first.type !== 'text' || typeof first.text !== 'string')
+            return result;
+        return {
+            ...result,
+            content: [{ ...first, text: (0, model_context_1.compactToolResult)(first.text, tier) }, ...result.content.slice(1)],
+        };
+    }
     withStalenessNotice(result, projectPath) {
         if (result.isError)
             return result;
@@ -900,6 +995,13 @@ class ToolHandler {
             if (!this.isToolAllowed(toolName)) {
                 return this.errorResult(`Tool ${toolName} is disabled via SPECSHIP_MCP_TOOLS`);
             }
+            // Integration tier (INTEG-TIER-DOC, REQ-INTEG-001): a jira/designer
+            // call without the opt-in is rejected even if a client cached the tool.
+            const integ = toolIntegration(toolName);
+            if (integ && !integrationEnabled(integ)) {
+                return this.errorResult(`Tool ${toolName} belongs to the optional "${integ}" integration, which is not enabled. ` +
+                    `Enable it with: specship install --with-${integ} (it talks to ${integ === 'jira' ? 'your Atlassian instance' : 'claude.ai — experimental'}).`);
+            }
             // Cross-cutting input validation. All tools accept an optional
             // `projectPath` and most accept either `query`, `task`, or
             // `symbol` — bound their lengths centrally so individual handlers
@@ -1018,7 +1120,12 @@ class ToolHandler {
                     return this.errorResult(`Unknown tool: ${toolName}`);
             }
             const withWorktree = this.withWorktreeNotice(result, args.projectPath);
-            return this.withStalenessNotice(withWorktree, args.projectPath);
+            const withStaleness = this.withStalenessNotice(withWorktree, args.projectPath);
+            // Model-aware compaction (MODCTX-DOC): on haiku/sonnet sessions the
+            // prose scaffolding compresses; code stays byte-verbatim. Only the
+            // code-graph tools reach this funnel — designer/jira returned above
+            // (REQ-MODCTX-004).
+            return this.withModelCompaction(withStaleness);
         }
         catch (err) {
             return this.errorResult(`Tool execution failed: ${err instanceof Error ? err.message : String(err)}`);
@@ -1040,7 +1147,7 @@ class ToolHandler {
             kinds: kind ? [kind] : undefined,
         });
         if (results.length === 0) {
-            return this.textResult(`No results found for "${query}"`);
+            return this.missWithSuggestions(cg, 'Query', query);
         }
         // Down-rank generated files within the FTS-returned set so a search
         // for "Send" surfaces the hand-written keeper before .pb.go stubs
@@ -1053,6 +1160,47 @@ class ToolHandler {
         const formatted = this.formatSearchResults(ranked);
         return this.textResult(this.truncateOutput(formatted));
     }
+    /**
+     * Anti-flounder miss template (LOWMODEL-DOC, REQ-LOWMODEL-001): a "not
+     * found" that just says "not found" leaves the agent — small models
+     * especially — to guess its next move, and the guess is usually grep/Read.
+     * Instead: name the nearest REAL symbols (token-level lookup, since the
+     * full query already failed FTS+LIKE) and end with a copy-pasteable next
+     * call. Applies at every tier.
+     */
+    missWithSuggestions(cg, kindLabel, query) {
+        // Split on separators AND camelCase so "AuthServic.logn" still yields
+        // useful probes ("Auth", "Servic", "logn" → LIKE finds AuthService/login).
+        const tokens = [...new Set(query
+                .split(/[\s._:\->#/\\]+/)
+                .flatMap((t) => t.split(/(?=[A-Z])/))
+                .map((t) => t.trim())
+                .filter((t) => t.length >= 3))].slice(0, 6);
+        const seen = new Set();
+        const suggestions = [];
+        for (const token of tokens) {
+            for (const r of cg.searchNodes(token, { limit: 3 })) {
+                const key = r.node.qualifiedName;
+                if (seen.has(key))
+                    continue;
+                seen.add(key);
+                suggestions.push({ name: key, where: `${r.node.filePath}:${r.node.startLine}` });
+                if (suggestions.length >= 4)
+                    break;
+            }
+            if (suggestions.length >= 4)
+                break;
+        }
+        const lines = [`${kindLabel} "${query}" not found in the index.`];
+        if (suggestions.length > 0) {
+            lines.push(`Closest indexed symbols: ${suggestions.map((s) => `${s.name} (${s.where})`).join(' · ')}`);
+            lines.push(`Next: specship_explore "${suggestions.map((s) => s.name).join(' ')}"`);
+        }
+        else {
+            lines.push('Nothing close in the index either. Next: specship_explore with broader words from the question — it also matches file names and doc text.');
+        }
+        return this.textResult(lines.join('\n'));
+    }
     /**
      * Handle specship_callers
      */
@@ -1064,7 +1212,7 @@ class ToolHandler {
         const limit = (0, utils_1.clamp)(args.limit || 20, 1, 100);
         const allMatches = this.findAllSymbols(cg, symbol);
         if (allMatches.nodes.length === 0) {
-            return this.textResult(`Symbol "${symbol}" not found in the codebase`);
+            return this.missWithSuggestions(cg, 'Symbol', symbol);
         }
         // Aggregate callers across all matching symbols
         const seen = new Set();
@@ -1094,7 +1242,7 @@ class ToolHandler {
         const limit = (0, utils_1.clamp)(args.limit || 20, 1, 100);
         const allMatches = this.findAllSymbols(cg, symbol);
         if (allMatches.nodes.length === 0) {
-            return this.textResult(`Symbol "${symbol}" not found in the codebase`);
+            return this.missWithSuggestions(cg, 'Symbol', symbol);
         }
         // Aggregate callees across all matching symbols
         const seen = new Set();
@@ -1124,7 +1272,7 @@ class ToolHandler {
         const depth = (0, utils_1.clamp)(args.depth || 2, 1, 10);
         const allMatches = this.findAllSymbols(cg, symbol);
         if (allMatches.nodes.length === 0) {
-            return this.textResult(`Symbol "${symbol}" not found in the codebase`);
+            return this.missWithSuggestions(cg, 'Symbol', symbol);
         }
         // Aggregate impact across all matching symbols
         const mergedNodes = new Map();
@@ -1267,7 +1415,7 @@ class ToolHandler {
      * whose qualifiedName contains another named token (`PmsProductServiceImpl::list`),
      * dropping unrelated `OmsOrderService::list`.
      */
-    buildFlowFromNamedSymbols(cg, query) {
+    buildFlowFromNamedSymbols(cg, query, tier = 'full') {
         const EMPTY = { text: '', pathNodeIds: new Set(), namedNodeIds: new Set(), uniqueNamedNodeIds: new Set() };
         try {
             const CALLABLE = new Set(['method', 'function', 'component', 'constructor']);
@@ -1402,11 +1550,23 @@ class ToolHandler {
                 out.push('## Flow (call path among the symbols you queried)', '');
                 for (let i = 0; i < best.length; i++) {
                     const step = best[i];
-                    if (step.edge) {
-                        const sy = this.synthEdgeNote(step.edge);
-                        out.push(`   ↓ ${sy ? sy.compact : step.edge.kind}`);
+                    if (tier === 'haiku') {
+                        // LOWMODEL-DOC REQ-LOWMODEL-003: small models don't synthesize
+                        // the flow from evidence — render each hop as ONE explicit line
+                        // with its mechanism inline. Additive formatting only; the code
+                        // bodies below are identical to the full tier's (A2).
+                        const mech = step.edge
+                            ? ` — via ${(this.synthEdgeNote(step.edge)?.compact ?? step.edge.kind)}`
+                            : '';
+                        out.push(`${i + 1}. ${i > 0 ? '→ ' : ''}${step.node.name} (${step.node.filePath}:${step.node.startLine})${mech}`);
+                    }
+                    else {
+                        if (step.edge) {
+                            const sy = this.synthEdgeNote(step.edge);
+                            out.push(`   ↓ ${sy ? sy.compact : step.edge.kind}`);
+                        }
+                        out.push(`${i + 1}. ${step.node.name} (${step.node.filePath}:${step.node.startLine})`);
                     }
-                    out.push(`${i + 1}. ${step.node.name} (${step.node.filePath}:${step.node.startLine})`);
                 }
                 out.push('');
             }
@@ -2016,7 +2176,7 @@ class ToolHandler {
         // Compute the flow spine once — used both to prepend the Flow section (below)
         // and to gate adaptive source sizing: files on the spine get full source,
         // off-spine peers skeletonize.
-        const flow = this.buildFlowFromNamedSymbols(cg, query);
+        const flow = this.buildFlowFromNamedSymbols(cg, query, (0, model_context_1.detectModelTier)(cg.getProjectRoot()));
         // Polymorphic-sibling detector for adaptive sizing. A class that implements/
         // extends a supertype shared by >= MIN_SIBLINGS classes is one of many
         // INTERCHANGEABLE implementations (OkHttp's 14 `: Interceptor` classes —
@@ -2597,7 +2757,7 @@ class ToolHandler {
         const lineHint = typeof args.line === 'number' && args.line > 0 ? args.line : undefined;
         let matches = this.findSymbolMatches(cg, symbol);
         if (matches.length === 0) {
-            return this.textResult(`Symbol "${symbol}" not found in the codebase`);
+            return this.missWithSuggestions(cg, 'Symbol', symbol);
         }
         // Disambiguate a heavily-overloaded name to a specific definition the caller
         // pinned by file/line (the `file:line` a trail or another tool showed it) —