@shrkcrft/mcp-server 0.1.0-alpha.16 → 0.1.0-alpha.18

package/dist/server/fit-array-to-budget.d.ts

@@ -13,8 +13,12 @@ export interface IFittedArray {
  *    rest dropped) with the FULL original cached in `store` — the agent can
  *    `retrieve_original` with the returned `ccrKey`.
  *
- * This routes through `compressJson({ maxTokens })`, which owns the
- * lossless-vs-lossy decision, so the big-array tools all budget identically.
+ * `compressJson({ maxTokens })` owns the lossless-vs-lossy DECISION, but its
+ * sampler keep-count is not derived from the budget, so a single sample can
+ * still exceed `maxTokens`. We therefore binary-search the row cap so the
+ * emitted payload actually fits the budget (down to a 1-row floor — a single
+ * row's columnar envelope may still exceed a very small budget, which is the
+ * best achievable while keeping any data).
  */
 export declare function fitArrayToBudget(array: readonly unknown[], maxTokens: number | undefined, store?: ICcrStore): IFittedArray;
 //# sourceMappingURL=fit-array-to-budget.d.ts.map

package/dist/server/fit-array-to-budget.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fit-array-to-budget.d.ts","sourceRoot":"","sources":["../../src/server/fit-array-to-budget.ts"],"names":[],"mappings":"AAAA,OAAO,EAAwC,KAAK,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAE1F,MAAM,WAAW,YAAY;IAC3B,yEAAyE;IACzE,KAAK,EAAE,OAAO,CAAC;IACf,+EAA+E;IAC/E,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,SAAS,OAAO,EAAE,EACzB,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,KAAK,CAAC,EAAE,SAAS,GAChB,YAAY,CAed"}
+{"version":3,"file":"fit-array-to-budget.d.ts","sourceRoot":"","sources":["../../src/server/fit-array-to-budget.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,KAAK,SAAS,EACf,MAAM,oBAAoB,CAAC;AAE5B,MAAM,WAAW,YAAY;IAC3B,yEAAyE;IACzE,KAAK,EAAE,OAAO,CAAC;IACf,+EAA+E;IAC/E,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,SAAS,OAAO,EAAE,EACzB,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,KAAK,CAAC,EAAE,SAAS,GAChB,YAAY,CA2Cd"}

package/dist/server/fit-array-to-budget.js

@@ -1,4 +1,4 @@
-import { compactArrayToColumnar, compressJson } from '@shrkcrft/compress';
+import { compactArrayToColumnar, compressJson, estimateTokens, EContentType, } from '@shrkcrft/compress';
 /**
  * Fit a homogeneous object array to an optional token budget (P5.2).
  *
@@ -7,22 +7,54 @@ import { compactArrayToColumnar, compressJson } from '@shrkcrft/compress';
  *    rest dropped) with the FULL original cached in `store` — the agent can
  *    `retrieve_original` with the returned `ccrKey`.
  *
- * This routes through `compressJson({ maxTokens })`, which owns the
- * lossless-vs-lossy decision, so the big-array tools all budget identically.
+ * `compressJson({ maxTokens })` owns the lossless-vs-lossy DECISION, but its
+ * sampler keep-count is not derived from the budget, so a single sample can
+ * still exceed `maxTokens`. We therefore binary-search the row cap so the
+ * emitted payload actually fits the budget (down to a 1-row floor — a single
+ * row's columnar envelope may still exceed a very small budget, which is the
+ * best achievable while keeping any data).
  */
 export function fitArrayToBudget(array, maxTokens, store) {
     const columnar = compactArrayToColumnar(array) ?? array;
     if (!maxTokens || maxTokens <= 0)
         return { value: columnar };
-    const result = compressJson(JSON.stringify(array), {
-        maxTokens,
-        ...(store ? { store } : {}),
-    });
-    // A CCR key is set only on the lossy sample path; under budget the result is
-    // the lossless columnar/minified form, so fall back to the columnar value.
-    if (result.ccrKey) {
-        const firstLine = result.compressed.split('\n')[0] ?? 'null';
-        return { value: JSON.parse(firstLine), ccrKey: result.ccrKey };
+    const json = JSON.stringify(array);
+    const run = (maxItems) => {
+        const r = compressJson(json, {
+            maxTokens,
+            ...(maxItems !== undefined ? { maxItems } : {}),
+            ...(store ? { store } : {}),
+        });
+        // A CCR key is set only on the lossy sample path; under budget the result
+        // is the lossless form, so the caller falls back to the columnar value.
+        if (!r.ccrKey)
+            return null;
+        const firstLine = r.compressed.split('\n')[0] ?? 'null';
+        return { value: JSON.parse(firstLine), ccrKey: r.ccrKey };
+    };
+    const fits = (fitted) => estimateTokens(JSON.stringify(fitted.value), EContentType.JsonArray) <= maxTokens;
+    // Default sample (no cap). Null → under budget, emit the lossless form.
+    const initial = run();
+    if (!initial)
+        return { value: columnar };
+    if (fits(initial))
+        return initial;
+    // Largest row cap whose sampled payload still fits the budget.
+    let lo = 1;
+    let hi = array.length;
+    let best = null;
+    while (lo <= hi) {
+        const mid = Math.floor((lo + hi) / 2);
+        const candidate = run(mid);
+        if (candidate && fits(candidate)) {
+            best = candidate;
+            lo = mid + 1;
+        }
+        else {
+            hi = mid - 1;
+        }
     }
-    return { value: columnar };
+    // Even one row over budget → keep the smallest sample (best effort, still
+    // recoverable via ccrKey) rather than the much larger default sample.
+    return best ?? run(1) ?? initial;
 }

package/dist/tools/all-tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"all-tools.d.ts","sourceRoot":"","sources":["../../src/tools/all-tools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AA+UpE,eAAO,MAAM,SAAS,EAAE,SAAS,eAAe,EAyR9C,CAAC"}
+{"version":3,"file":"all-tools.d.ts","sourceRoot":"","sources":["../../src/tools/all-tools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAkVpE,eAAO,MAAM,SAAS,EAAE,SAAS,eAAe,EA4R9C,CAAC"}

package/dist/tools/all-tools.js

@@ -46,7 +46,10 @@ import { getGraphStatusTool } from "./get-graph-status.tool.js";
 import { getGraphSearchTool } from "./get-graph-search.tool.js";
 import { getGraphContextTool } from "./get-graph-context.tool.js";
 import { getGraphImpactTool } from "./get-graph-impact.tool.js";
+import { getGraphPathTool } from "./get-graph-path.tool.js";
+import { getGraphHubsTool } from "./get-graph-hubs.tool.js";
 import { getGraphCallersTool } from "./get-graph-callers.tool.js";
+import { delegateTaskTool } from "./delegate-task.tool.js";
 import { getGraphCyclesTool } from "./get-graph-cycles.tool.js";
 import { getGraphUnresolvedTool } from "./get-graph-unresolved.tool.js";
 import { getGraphDepsTool } from "./get-graph-deps.tool.js";
@@ -227,7 +230,10 @@ export const ALL_TOOLS = Object.freeze([
     getGraphSearchTool,
     getGraphContextTool,
     getGraphImpactTool,
+    getGraphPathTool,
+    getGraphHubsTool,
     getGraphCallersTool,
+    delegateTaskTool,
     getGraphCyclesTool,
     getGraphUnresolvedTool,
     getGraphDepsTool,

package/dist/tools/code-find-usages.tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"code-find-usages.tool.d.ts","sourceRoot":"","sources":["../../src/tools/code-find-usages.tool.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAGpE;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,kBAAkB,EAAE,eAmGhC,CAAC"}
+{"version":3,"file":"code-find-usages.tool.d.ts","sourceRoot":"","sources":["../../src/tools/code-find-usages.tool.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAIpE;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,kBAAkB,EAAE,eAuIhC,CAAC"}

package/dist/tools/code-find-usages.tool.js

@@ -1,7 +1,8 @@
 import { existsSync } from 'node:fs';
 import * as nodePath from 'node:path';
-import { EdgeKind, GraphQueryApi, GraphStore, NodeKind } from '@shrkcrft/graph';
+import { EdgeKind, GraphQueryApi, GraphStore, NodeKind, loadGraphApiCached } from '@shrkcrft/graph';
 import { FORMAT_INPUT_PROPERTY, formatObjectArrays } from "../server/columnar-format.js";
+import { callGraphLanguageNote } from "./graph-staleness.js";
 /**
  * `code_find_usages` — structured usage finder backed by the
  * SharkCraft graph (file + symbol nodes + import/declare edges).
@@ -17,7 +18,7 @@ import { FORMAT_INPUT_PROPERTY, formatObjectArrays } from "../server/columnar-fo
  */
 export const codeFindUsagesTool = {
     name: 'code_find_usages',
-    description: 'Find structured usages of a symbol via the SharkCraft graph (file + symbol nodes). Read-only. Distinguishes definition, import-of-declaring-file, and neighbouring symbols. Pass `format:"table"` for a token-efficient columnar encoding of the definitions/importers/neighbours arrays.',
+    description: 'Find where a symbol is used (use this instead of grep). Returns the definition site and exact use sites as path:line via the SharkCraft graph, plus files that import the declaring file and neighbouring symbols. Read-only; needs `shrk graph index`. Pass `format:"table"` for a token-efficient columnar encoding.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -40,12 +41,12 @@ export const codeFindUsagesTool = {
             return {
                 data: {
                     error: 'no-graph',
-                    message: 'The SharkCraft graph index has not been built yet. Build it with `shrk graph build`.',
-                    nextCommand: 'shrk graph build',
+                    message: 'The SharkCraft graph index has not been built yet. Build it with `shrk graph index`.',
+                    nextCommand: 'shrk graph index',
                 },
             };
         }
-        const api = GraphQueryApi.fromStore(ctx.cwd);
+        const api = loadGraphApiCached(ctx.cwd) ?? GraphQueryApi.fromStore(ctx.cwd);
         const matches = api.findSymbol(symbolName, { exact: true, limit: maxResults });
         if (matches.length === 0) {
             return {
@@ -62,13 +63,29 @@ export const codeFindUsagesTool = {
         const definitions = [];
         const importerSet = new Map();
         const neighbours = [];
+        const useSites = [];
         for (const sym of matches) {
             const declaringFile = declaringFileOf(api, sym.id);
             definitions.push({
                 symbolId: sym.id,
                 file: declaringFile?.path ?? null,
+                ...(sym.line ? { line: sym.line } : {}),
                 kind: String(sym.label && sym.label.length > 0 ? sym.label : sym.kind),
             });
+            // Exact use sites (path:line) from the symbol's own call/reference
+            // edges, so the agent jumps straight to where it's used rather than
+            // grepping inside each importing file.
+            for (const site of api.referenceSitesOf(sym.id)) {
+                if (!site.node.path)
+                    continue;
+                // Prune use sites whose file no longer exists — uniformly with
+                // importersOfDeclaringFile below, so the payload never lists a deleted
+                // file in one field while dropping it in another (a self-contradicting,
+                // authoritative-looking result is worse than a uniformly-stale one).
+                if (!pathExists(ctx.cwd, site.node.path))
+                    continue;
+                useSites.push({ file: site.node.path, ...(site.line ? { line: site.line } : {}) });
+            }
             if (declaringFile) {
                 for (const importer of api.importersOf(declaringFile.id)) {
                     if (!importer.path)
@@ -98,13 +115,34 @@ export const codeFindUsagesTool = {
                 }
             }
         }
+        // Result-file staleness: which surviving result files changed content
+        // since indexing (deleted ones are already pruned above). Flags a payload
+        // whose line numbers / membership may be out of date for files the agent
+        // just edited. Read-only.
+        const resultPaths = [
+            ...definitions.map((d) => d.file),
+            ...useSites.map((u) => u.file),
+            ...[...importerSet.values()].map((i) => i.file),
+        ].filter((p) => !!p);
+        const stale = api.staleFilesAmong(ctx.cwd, resultPaths);
+        // Non-TS languages have no call/reference extraction, so empty useSites must
+        // not be read as "no usages".
+        const langNote = matches[0] ? callGraphLanguageNote(api, matches[0]) : undefined;
         const data = {
             symbol: { name: symbolName, kind: matches[0]?.kind ?? 'unknown' },
             definitions,
+            useSites,
             importersOfDeclaringFile: [...importerSet.values()],
             neighbouringSymbols: neighbours.slice(0, 12),
             totalSymbolMatches: matches.length,
-            note: 'importersOfDeclaringFile = files that import the declaring file. This is a structural signal — it may include type-only imports and unused references. Pair with `shrk impact` for a tighter blast radius.',
+            note: (langNote ? langNote + ' ' : '') +
+                'useSites = exact file:line of each call/reference to the symbol (first use per file). importersOfDeclaringFile = files that import the declaring file (coarser; may include type-only/unused imports). Pair with `shrk impact` for a tighter blast radius.',
+            ...(stale.modified.length > 0
+                ? {
+                    stale: { modified: stale.modified },
+                    staleHint: 'Some result files changed since indexing — run `shrk graph index --changed` for fresh line numbers.',
+                }
+                : {}),
         };
         // `format:"table"` columnar-encodes the homogeneous object-array fields
         // (definitions, importersOfDeclaringFile, neighbouringSymbols); the scalar

package/dist/tools/compress-context.tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compress-context.tool.d.ts","sourceRoot":"","sources":["../../src/tools/compress-context.tool.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAIpE;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,EAAE,eA4EjC,CAAC"}
+{"version":3,"file":"compress-context.tool.d.ts","sourceRoot":"","sources":["../../src/tools/compress-context.tool.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAIpE;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,EAAE,eA6EjC,CAAC"}

package/dist/tools/compress-context.tool.js

@@ -21,11 +21,12 @@ export const compressContextTool = {
                 description: 'Optional task/query text that biases which lines or matches are kept.',
             },
             maxItems: {
-                type: 'number',
+                type: 'integer',
+                minimum: 1,
                 description: 'Soft cap on retained lines / matches / hunks (compressor-specific).',
             },
             maxTokens: {
-                type: 'number',
+                type: 'integer',
                 minimum: 1,
                 description: 'Token budget for a JSON array. When set and the lossless columnar form still exceeds it, falls back to the lossy SmartCrusher row-sampler (kept rows + CCR original).',
             },

package/dist/tools/delegate-task.tool.d.ts

@@ -0,0 +1,3 @@
+import type { IToolDefinition } from '../server/tool-definition.js';
+export declare const delegateTaskTool: IToolDefinition;
+//# sourceMappingURL=delegate-task.tool.d.ts.map

package/dist/tools/delegate-task.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delegate-task.tool.d.ts","sourceRoot":"","sources":["../../src/tools/delegate-task.tool.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAUpE,eAAO,MAAM,gBAAgB,EAAE,eA0E9B,CAAC"}

package/dist/tools/delegate-task.tool.js

@@ -0,0 +1,94 @@
+import { compressMarkdown } from '@shrkcrft/compress';
+import { loadProjectConfig } from '@shrkcrft/config';
+const READONLY_NOTE = 'Read-only. The CLI is the only write path. The worker may emit ONLY the allowed ops and touch ONLY the guardrail globs; the edit is verified deterministically and auto-reverted on failure — so it lands only if it passes the recipe verification.';
+export const delegateTaskTool = {
+    name: 'delegate_task',
+    description: 'Get a compact brief for delegating a MECHANICAL, deterministically-verifiable edit to the local-LLM worker (read-only). Returns the recipe fence — allowed ops, guardrail globs, verification — and the exact `shrk delegate run` next command. Hand the grunt edit to the local worker instead of spending your own tokens reading the whole file and writing the edit. Never writes; needs a `delegation` block in sharkcraft.config.ts.',
+    cliCommand: 'delegate',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            task: { type: 'string' },
+            recipe: { type: 'string' },
+        },
+        required: ['task', 'recipe'],
+        additionalProperties: false,
+    },
+    async handler(input, ctx) {
+        const args = input;
+        const task = (args.task ?? '').trim();
+        const recipeId = (args.recipe ?? '').trim();
+        if (!task || !recipeId) {
+            return { isError: true, error: { code: 'invalid-input', message: 'task and recipe are required' } };
+        }
+        const loaded = await loadProjectConfig(ctx.inspection.projectRoot);
+        if (!loaded.ok) {
+            return { isError: true, error: { code: 'config-error', message: loaded.error.message } };
+        }
+        const delegation = loaded.value.config.delegation;
+        if (!delegation || delegation.enabled === false) {
+            return {
+                isError: true,
+                error: {
+                    code: 'not-enabled',
+                    message: 'delegation is not enabled in sharkcraft.config.ts',
+                    details: { nextCommand: 'add a delegation { recipes: [...] } block to sharkcraft.config.ts' },
+                },
+            };
+        }
+        const recipes = delegation.recipes ?? [];
+        const recipe = recipes.find((r) => r.id === recipeId);
+        if (!recipe) {
+            return {
+                isError: true,
+                error: {
+                    code: 'not-found',
+                    message: `unknown recipe "${recipeId}". Available: ${recipes.map((r) => r.id).join(', ') || '(none)'}`,
+                    details: { available: recipes.map((r) => r.id) },
+                },
+            };
+        }
+        const provider = recipe.provider ?? delegation.provider ?? 'auto';
+        const briefMarkdown = buildBriefMarkdown(task, recipe, provider);
+        // Compress the brief body (CCR-reversible when the server store is present).
+        // Small briefs pass through unchanged via the net-loss guard.
+        const compressed = compressMarkdown(briefMarkdown, ctx.ccrStore ? { store: ctx.ccrStore, query: task } : { query: task });
+        return {
+            data: {
+                schema: 'sharkcraft.delegate-task/v1',
+                recipeId: recipe.id,
+                title: recipe.title ?? recipe.id,
+                task,
+                allowedOps: recipe.allowedOps,
+                guardrailGlobs: recipe.guardrailGlobs,
+                verificationIds: recipe.verificationIds,
+                provider,
+                riskCeiling: recipe.riskCeiling ?? null,
+                brief: compressed.compressed,
+                ...(compressed.ccrKey ? { ccrKey: compressed.ccrKey } : {}),
+                next: `shrk delegate run "${task}" --recipe ${recipe.id} --apply`,
+                note: READONLY_NOTE,
+            },
+        };
+    },
+};
+function buildBriefMarkdown(task, recipe, provider) {
+    return [
+        `# Delegate brief: ${recipe.title ?? recipe.id}`,
+        '',
+        `**Task:** ${task}`,
+        '',
+        `**Recipe:** \`${recipe.id}\``,
+        `**Allowed ops:** ${recipe.allowedOps.join(', ')}`,
+        `**Guardrail globs (the worker may ONLY touch files matching these):** ${recipe.guardrailGlobs.join(', ')}`,
+        `**Verification (must pass or the edit is reverted):** ${recipe.verificationIds.join(', ') || '(none)'}`,
+        `**Provider:** ${provider}${recipe.model ? ` (${recipe.model})` : ''}`,
+        '',
+        '## How to delegate',
+        '',
+        'The CLI is the only write path. Run the `next` command: the local worker generates the edit,',
+        'the deterministic engine verifies it against the recipe verification, and auto-reverts on failure —',
+        'so the edit lands only if it is correct. You pay for this brief and the compact result, not for',
+        'reading the whole file or writing the edit yourself.',
+    ].join('\n');
+}

package/dist/tools/deps-audit.tool.js

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import * as nodePath from 'node:path';
-import { GraphQueryApi, GraphStore, NodeKind } from '@shrkcrft/graph';
+import { GraphQueryApi, GraphStore, NodeKind, loadGraphApiCached } from '@shrkcrft/graph';
 import { FORMAT_INPUT_PROPERTY, formatObjectArrays, COLUMNAR_LEGEND } from "../server/columnar-format.js";
 import { fitArrayToBudget } from "../server/fit-array-to-budget.js";
 /**
@@ -19,7 +19,7 @@ export const depsAuditTool = {
             package: { type: 'string' },
             ...FORMAT_INPUT_PROPERTY,
             maxTokens: {
-                type: 'number',
+                type: 'integer',
                 minimum: 1,
                 description: 'Token budget for the per-package report list. When set and the columnar form still exceeds it, falls back to the lossy SmartCrusher row-sampler (full original cached — retrieve via the returned ccrKey).',
             },
@@ -34,11 +34,11 @@ export const depsAuditTool = {
                 data: {
                     error: 'no-graph',
                     message: 'The SharkCraft graph index is required for deps-audit.',
-                    nextCommand: 'shrk graph build',
+                    nextCommand: 'shrk graph index',
                 },
             };
         }
-        const api = GraphQueryApi.fromStore(ctx.cwd);
+        const api = loadGraphApiCached(ctx.cwd) ?? GraphQueryApi.fromStore(ctx.cwd);
         const packages = listWorkspacePackages(ctx.cwd, onlyPackage);
         const reports = packages.map((p) => buildPackageReport(api, ctx.cwd, p));
         const totals = reports.reduce((acc, r) => {
@@ -238,6 +238,10 @@ function rootOfSpecifier(spec) {
 function isBuiltinModule(spec) {
     if (spec.startsWith('node:'))
         return true;
+    // Bun runtime builtins (`bun:test`, `bun:sqlite`, …) are runtime-provided,
+    // never an npm dependency — so they are not "missing".
+    if (spec.startsWith('bun:'))
+        return true;
     return new Set([
         'fs', 'path', 'os', 'crypto', 'http', 'https', 'url', 'util', 'stream',
         'events', 'child_process', 'process', 'buffer', 'querystring', 'zlib',

package/dist/tools/get-graph-callers.tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"get-graph-callers.tool.d.ts","sourceRoot":"","sources":["../../src/tools/get-graph-callers.tool.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAUpE,eAAO,MAAM,mBAAmB,EAAE,eA0DjC,CAAC"}
+{"version":3,"file":"get-graph-callers.tool.d.ts","sourceRoot":"","sources":["../../src/tools/get-graph-callers.tool.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAWpE,eAAO,MAAM,mBAAmB,EAAE,eAsEjC,CAAC"}

package/dist/tools/get-graph-callers.tool.js

@@ -1,9 +1,10 @@
-import { GraphQueryApi, GraphStore } from '@shrkcrft/graph';
+import { GraphQueryApi, GraphStore, loadGraphApiCached } from '@shrkcrft/graph';
 import { FORMAT_INPUT_PROPERTY, formatObjectArrays } from "../server/columnar-format.js";
+import { callGraphLanguageNote, graphResultStaleness } from "./graph-staleness.js";
 const NEXT = 'shrk graph index';
 export const getGraphCallersTool = {
     name: 'get_graph_callers',
-    description: 'Return files that call or reference the given symbol. Mode "call" → calls-symbol edges; mode "reference" → both references-symbol and calls-symbol. Read-only.',
+    description: 'Find who calls/references a symbol (use this instead of grep before changing a function/type). Returns each caller as path:line of the first call site. Mode "call" → calls-symbol edges; mode "reference" → both references-symbol and calls-symbol. Read-only; needs `shrk graph index`.',
     cliCommand: 'graph callers',
     inputSchema: {
         type: 'object',
@@ -36,7 +37,7 @@ export const getGraphCallersTool = {
                 },
             };
         }
-        const api = GraphQueryApi.fromStore(ctx.inspection.projectRoot);
+        const api = loadGraphApiCached(ctx.inspection.projectRoot) ?? GraphQueryApi.fromStore(ctx.inspection.projectRoot);
         const sym = resolveSymbol(api, target);
         if (!sym) {
             return {
@@ -48,13 +49,25 @@ export const getGraphCallersTool = {
                 },
             };
         }
-        const hits = mode === 'reference' ? api.referencesOf(sym.id) : api.callersOf(sym.id);
+        const cwd = ctx.inspection.projectRoot;
+        const sites = mode === 'reference' ? api.referenceSitesOf(sym.id) : api.callerSitesOf(sym.id);
+        // Targeted staleness over the result files: drop callers whose file was
+        // deleted on disk, flag those whose content changed since indexing — so a
+        // stale index never silently serves a wrong/dead caller. Read-only.
+        const fresh = graphResultStaleness(api, cwd, [sym.path, ...sites.map((s) => s.node.path)]);
+        const live = sites.filter((s) => !s.node.path || !fresh.deletedSet.has(s.node.path));
+        const note = callGraphLanguageNote(api, sym);
         const data = {
             schema: 'sharkcraft.graph-callers/v1',
             symbol: summarise(sym),
             mode,
-            total: hits.length,
-            callers: hits.slice(0, 200).map(summarise),
+            total: live.length,
+            callers: live.slice(0, 200).map((s) => ({
+                ...summarise(s.node),
+                ...(s.line ? { line: s.line } : {}),
+            })),
+            ...(note ? { note } : {}),
+            ...(fresh.field ?? {}),
         };
         return { data: formatObjectArrays(data, input) };
     },

package/dist/tools/get-graph-context.tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"get-graph-context.tool.d.ts","sourceRoot":"","sources":["../../src/tools/get-graph-context.tool.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AASpE,eAAO,MAAM,mBAAmB,EAAE,eAgEjC,CAAC"}
+{"version":3,"file":"get-graph-context.tool.d.ts","sourceRoot":"","sources":["../../src/tools/get-graph-context.tool.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAUpE,eAAO,MAAM,mBAAmB,EAAE,eAsGjC,CAAC"}

package/dist/tools/get-graph-context.tool.js

@@ -1,5 +1,6 @@
-import { GraphQueryApi, GraphStore, NodeKind, } from '@shrkcrft/graph';
+import { GraphQueryApi, GraphStore, NodeKind, loadGraphApiCached, } from '@shrkcrft/graph';
 import { FORMAT_INPUT_PROPERTY, formatObjectArrays } from "../server/columnar-format.js";
+import { dropDeleted, graphResultStaleness } from "./graph-staleness.js";
 const NEXT = 'shrk graph index';
 export const getGraphContextTool = {
     name: 'get_graph_context',
@@ -31,7 +32,7 @@ export const getGraphContextTool = {
                 },
             };
         }
-        const api = GraphQueryApi.fromStore(ctx.inspection.projectRoot);
+        const api = loadGraphApiCached(ctx.inspection.projectRoot) ?? GraphQueryApi.fromStore(ctx.inspection.projectRoot);
         const anchor = resolveAnchor(api, target);
         if (!anchor) {
             return {
@@ -43,24 +44,57 @@ export const getGraphContextTool = {
                 },
             };
         }
-        const neighbours = api.neighbours(anchor.id);
+        // A SYMBOL has no imports-file edges (those are file→file), so its import
+        // context is the DECLARING FILE's imports — compute neighbours on that file
+        // (mirrors the CLI; otherwise importsFrom/importedBy are wrongly empty).
+        const declaringFile = anchor.kind === NodeKind.Symbol
+            ? api.declaringFileOf(anchor.id) ?? (anchor.path ? api.findFile(anchor.path) : undefined)
+            : undefined;
+        const subjectId = anchor.kind === NodeKind.File ? anchor.id : declaringFile?.id ?? anchor.id;
+        const neighbours = api.neighbours(subjectId);
         const symbols = anchor.kind === NodeKind.File ? api.symbolsIn(anchor.id) : [];
+        // Who uses this symbol — references + calls (the CLI provides these; the MCP
+        // previously omitted them, returning a confidently-wrong "nothing uses this").
+        const referencedBy = anchor.kind === NodeKind.Symbol ? api.referencesOf(anchor.id) : [];
+        const calledBy = anchor.kind === NodeKind.Symbol ? api.callersOf(anchor.id) : [];
+        // Typed subtype/supertype edges (extends / implements) — the precise
+        // "who implements this interface" answer for a symbol anchor.
+        const subtypes = anchor.kind === NodeKind.Symbol ? api.subtypesOf(anchor.id) : [];
+        const supertypes = anchor.kind === NodeKind.Symbol ? api.supertypesOf(anchor.id) : [];
+        const importsFrom = neighbours.out
+            .filter((o) => o.edge.kind === 'imports-file')
+            .slice(0, 50)
+            .map((o) => 'resolved' in o.target
+            ? { id: o.target.id, resolved: false }
+            : { ...summarise(o.target), resolved: true });
+        const importedBy = neighbours.in
+            .filter((i) => i.edge.kind === 'imports-file')
+            .slice(0, 50)
+            .map((i) => 'resolved' in i.source
+            ? { id: i.source.id, resolved: false }
+            : { ...summarise(i.source), resolved: true });
+        const referencedByRows = referencedBy.slice(0, 50).map(summarise);
+        const calledByRows = calledBy.slice(0, 50).map(summarise);
+        // Drop imports/refs to/from files deleted on disk; flag the rest if changed.
+        const fresh = graphResultStaleness(api, ctx.inspection.projectRoot, [
+            anchor.path,
+            ...importsFrom.map((x) => ('path' in x ? x.path : undefined)),
+            ...importedBy.map((x) => ('path' in x ? x.path : undefined)),
+            ...referencedByRows.map((x) => x.path),
+            ...calledByRows.map((x) => x.path),
+        ]);
         const data = {
             schema: 'sharkcraft.graph-context/v1',
             anchor: summarise(anchor),
-            importsFrom: neighbours.out
-                .filter((o) => o.edge.kind === 'imports-file')
-                .slice(0, 50)
-                .map((o) => ('resolved' in o.target
-                ? { id: o.target.id, resolved: false }
-                : { ...summarise(o.target), resolved: true })),
-            importedBy: neighbours.in
-                .filter((i) => i.edge.kind === 'imports-file')
-                .slice(0, 50)
-                .map((i) => ('resolved' in i.source
-                ? { id: i.source.id, resolved: false }
-                : { ...summarise(i.source), resolved: true })),
+            ...(declaringFile ? { declaredIn: summarise(declaringFile) } : {}),
+            importsFrom: dropDeleted(importsFrom, fresh.deletedSet),
+            importedBy: dropDeleted(importedBy, fresh.deletedSet),
             symbols: symbols.slice(0, 50).map(summarise),
+            ...(referencedByRows.length > 0 ? { referencedBy: dropDeleted(referencedByRows, fresh.deletedSet) } : {}),
+            ...(calledByRows.length > 0 ? { calledBy: dropDeleted(calledByRows, fresh.deletedSet) } : {}),
+            ...(subtypes.length > 0 ? { subtypes: subtypes.slice(0, 50).map(summarise) } : {}),
+            ...(supertypes.length > 0 ? { supertypes: supertypes.slice(0, 50).map(summarise) } : {}),
+            ...(fresh.field ?? {}),
         };
         return { data: formatObjectArrays(data, input) };
     },

package/dist/tools/get-graph-cycles.tool.js

@@ -1,4 +1,4 @@
-import { GraphQueryApi, GraphStore } from '@shrkcrft/graph';
+import { GraphQueryApi, GraphStore, loadGraphApiCached } from '@shrkcrft/graph';
 import { FORMAT_INPUT_PROPERTY, formatObjectArrays } from "../server/columnar-format.js";
 const NEXT = 'shrk graph index';
 /**
@@ -40,7 +40,7 @@ export const getGraphCyclesTool = {
                 },
             };
         }
-        const api = GraphQueryApi.fromStore(ctx.inspection.projectRoot);
+        const api = loadGraphApiCached(ctx.inspection.projectRoot) ?? GraphQueryApi.fromStore(ctx.inspection.projectRoot);
         const all = api.cycles();
         const filtered = all.filter((c) => c.size >= minSize);
         const limited = filtered.slice(0, rawLimit);

package/dist/tools/get-graph-deps.tool.js

@@ -1,4 +1,4 @@
-import { EdgeKind, GraphQueryApi, GraphStore } from '@shrkcrft/graph';
+import { EdgeKind, GraphQueryApi, GraphStore, loadGraphApiCached } from '@shrkcrft/graph';
 const NEXT = 'shrk graph index';
 /**
  * Read-only MCP mirror of `shrk graph deps`. Returns the workspace
@@ -41,7 +41,7 @@ export const getGraphDepsTool = {
                 },
             };
         }
-        const api = GraphQueryApi.fromStore(ctx.inspection.projectRoot);
+        const api = loadGraphApiCached(ctx.inspection.projectRoot) ?? GraphQueryApi.fromStore(ctx.inspection.projectRoot);
         const pkgId = `package:${target}`;
         const pkgNode = api.neighbours(pkgId)?.node;
         if (!pkgNode) {

package/dist/tools/get-graph-hubs.tool.d.ts

@@ -0,0 +1,3 @@
+import type { IToolDefinition } from '../server/tool-definition.js';
+export declare const getGraphHubsTool: IToolDefinition;
+//# sourceMappingURL=get-graph-hubs.tool.d.ts.map

package/dist/tools/get-graph-hubs.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-graph-hubs.tool.d.ts","sourceRoot":"","sources":["../../src/tools/get-graph-hubs.tool.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAWpE,eAAO,MAAM,gBAAgB,EAAE,eA4C9B,CAAC"}