ast-mcp-server 0.11.2 → 0.12.0

package/CHANGELOG.md

@@ -6,7 +6,22 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
-## [0.11.2] — local release candidate, pending release (2026-08-25)
+## [0.12.0] — local release candidate, pending release (2026-08-27)
+
+### Added
+
+- Diagnostic pagination can now include opt-in bounded aggregates computed from the complete normalized snapshot, with code and file dimensions capped at 20 entries and explicit coverage metadata.
+- Added an immutable tool capability catalog with MCP, batch, and agent projections derived from one source of truth, plus independent inventory, integration, canary, package, and documentation oracles.
+
+### Fixed
+
+- Canary validation continues to enforce the established public runtime gate payload while capability metadata is checked independently, preventing an internal catalog change from widening the public canary schema.
+
+### Release status
+
+- Version `0.12.0` remains pending its exact-tree two-runtime matrix, CI, and separately authorized delivery sequence. It has not been published, assigned to an npm dist-tag, tagged in Git, or released on GitHub.
+
+## [0.11.2] — published to `latest` and `next`, registry verified (2026-08-25)
 
 ### Added
 
@@ -22,7 +37,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ### Release status
 
-- This local release candidate succeeds immutable npm versions `0.11.0` and `0.11.1`, neither of which was promotable: `0.11.0` verification exposed stale managed-skill predicates, and `0.11.1` verification exposed the copied runner's missing validator module. Version `0.11.2` remains pending its exact-tree matrix, CI, and separately authorized delivery sequence; it has not been published or assigned to any dist-tag.
+- npm published these immutable bytes under `next` with provenance and the expected Git commit. Public-registry consumer and release-preflight verification passed, `latest` and `next` both resolve to `0.11.2`, and the annotated `v0.11.2` tag plus GitHub Release resolve to the same release commit. This release supersedes immutable versions `0.11.0` and `0.11.1`, whose separate public-registry verification defects prevented promotion.
 
 ## [0.11.1] — published to `next`, verification failed, not promoted (2026-08-23)
 

package/README.md

@@ -84,7 +84,7 @@ The included batch benchmark records a 50% reduction in model round-trips and a
 
 ## Supported environment and trust boundary
 
-The local `0.11.2` release candidate requires Node.js `>=22.13.0`; its evidence matrix targets exact Node.js 22.13.0 and the current Node.js 24 line. Published v0.10.0 retains its immutable historical Node.js 22.13.0/24 evidence. Managed setup-file publication additionally requires GNU coreutils 9.7 `mv` supporting `--update=none-fail`, `--exchange`, `--no-copy`, and `--no-target-directory`, GNU coreutils `ln -L -T`, procfs descriptor paths at `/proc/self/fd`, and `O_DIRECTORY`/`O_NOFOLLOW`. Other Linux architectures or systems without those filesystem primitives, macOS, and Windows remain unverified.
+The local `0.12.0` release candidate requires Node.js `>=22.13.0`; its evidence matrix targets exact Node.js 22.13.0 and the current Node.js 24 line. Published v0.11.2 retains its immutable historical Node.js 22.13.0/24 evidence. Managed setup-file publication additionally requires GNU coreutils 9.7 `mv` supporting `--update=none-fail`, `--exchange`, `--no-copy`, and `--no-target-directory`, GNU coreutils `ln -L -T`, procfs descriptor paths at `/proc/self/fd`, and `O_DIRECTORY`/`O_NOFOLLOW`. Other Linux architectures or systems without those filesystem primitives, macOS, and Windows remain unverified.
 
 This is a local stdio server. It runs with the invoking user's filesystem permissions, and clients may request any `project_root` that user can access. It does not provide HTTP authentication, sandboxing, tenant isolation, or a remote-service security boundary. Remote, untrusted, and multi-tenant operation is unsupported.
 
@@ -100,7 +100,7 @@ The parent waits for child readiness before replaying bounded initialization sta
 
 The scoped Linux canary passed on exact Node.js 22.13.0 and Node.js 24 with repeatable PSS reclamation, stable compiler fingerprints, unchanged SQLite reuse, bounded redacted diagnostics, and no orphan after parent death. This is one child per connection, not a shared daemon, pool, or new default. See [ADR 0014](docs/adr/0014-supervised-compiler-worker.md).
 
-In published v0.10.0 and the local `0.11.2` release candidate, an absent `AST_SYMBOL_INDEX_PERSISTENCE` or explicit `enabled` selects the private SQLite symbol-index cache. `disabled` is the immediate memory-only rollback. `canary` requires an explicit absolute normalized `AST_SYMBOL_INDEX_CACHE_ROOT`. Invalid policy or storage fails closed to compiler-authoritative memory reads with bounded path-free status.
+In published v0.11.2 and the local `0.12.0` release candidate, an absent `AST_SYMBOL_INDEX_PERSISTENCE` or explicit `enabled` selects the private SQLite symbol-index cache. `disabled` is the immediate memory-only rollback. `canary` requires an explicit absolute normalized `AST_SYMBOL_INDEX_CACHE_ROOT`. Invalid policy or storage fails closed to compiler-authoritative memory reads with bounded path-free status.
 
 The default cache root is selected from `AST_SYMBOL_INDEX_CACHE_ROOT`, then `XDG_CACHE_HOME`, then `HOME`. Inspect or clear only derived cache artifacts through the bounded CLI:
 
@@ -345,6 +345,12 @@ Project-scoped tools accept `project_root`, either the project directory or an e
 
 Read results use project-relative paths, deterministic ordering, structured MCP output, and pagination where result sets can grow with the project.
 
+### Diagnostic aggregates
+
+Set `include_aggregates: true` on `ast_get_diagnostics` to summarize the complete normalized diagnostic snapshot independently of the selected raw page. The option defaults to `false`; disabled responses omit `aggregates` and keep the existing shape.
+
+Each code and file dimension returns at most 20 ranked groups. `groups.length + omitted_group_count = total_group_count`, and `sum(groups[*].count) = covered_diagnostic_count`. Code coverage plus `omitted_diagnostic_count` equals the diagnostic total; file coverage also adds `unfiled_diagnostic_count`. File groups contain normalized project-relative paths only, but may disclose a path that is absent from the selected raw page.
+
 `ast_explore` supports query, exact file, and exact symbol routes. Its default `summary` profile returns bounded reusable selectors; `context` adds selected source and `full` adds compiler references. Whole symbol clusters are admitted under the caller's `max_bytes` ceiling, so source, reference records, and call paths are never sliced. `omissions` classifies withheld components as `budget`, `incomplete`, or `untrusted`, and any requested omission keeps completeness false.
 
 Exact `file_path` plus `symbol_path` requests may opt into bounded static `call_spines`. Only fresh, exact, compiler-resolved invocation sites qualify; generic references, dynamic dispatch, and runtime behavior are not inferred. Absence of `call_spines` performs no call traversal. Every response still reports freshness, completeness, truncation, unresolved selectors, record limits, and canonical serialized-byte accounting. Use the primitive tools when a single exact operation is clearer or when preparing a mutation. See [ADR 0013](docs/adr/0013-ast-explore-presentation.md).
@@ -486,7 +492,19 @@ The server does **not** claim a filesystem-wide transaction:
 
 ## Development gates
 
+### Add or change an MCP tool
+
+Keep schemas, metadata, annotations, handlers, errors, and serialization in the tool module. Export
+one frozen descriptor, add it to the intentional order in `src/tools/catalog.ts`, and declare only
+static effect, batch, compatibility, and direct-format facts. Do not add request state, dynamic
+discovery, invocation-by-name, or a generic executor to the catalog.
+
+Update the independent `tools/list` inventories only after reviewing the complete wire metadata;
+they must not import or derive expectations from the catalog. Then run the focused catalog and MCP
+integration tests plus the runtime, package, and managed-skill gates below.
+
 ```bash
+yarn vitest run test/tool-catalog.test.ts test/mcp.integration.test.ts
 yarn format:check
 yarn lint
 yarn typecheck

package/SECURITY.md

@@ -11,7 +11,7 @@ Security fixes are provided for the exact version currently identified by the np
 | Earlier npm versions                        | No        |
 | Unpublished release candidates              | No        |
 
-This project supports trusted single-user local stdio use; the supported operating-system and architecture boundary remains Linux x64 only. The local `0.11.2` release candidate requires Node.js `>=22.13.0`, with evidence targeted at exact Node.js 22.13.0 and the governed Node.js 24 major. Published v0.10.0 retains its immutable Node.js 22.13.0/24 release matrix. Managed setup mutation requires GNU coreutils 9.7 `mv --update=none-fail --exchange --no-copy --no-target-directory`, GNU coreutils `ln -L -T`, and procfs descriptor-relative paths at `/proc/self/fd` with `O_DIRECTORY`/`O_NOFOLLOW`. The candidate's default SQLite cache also relies on Linux ownership, mode, no-follow, link-count and inode-identity checks; it does not defend against a malicious same-UID process. Other Linux architectures and systems without those primitives are unverified, as are macOS and Windows. Remote, untrusted, and multi-tenant use is outside the supported security boundary.
+This project supports trusted single-user local stdio use; the supported operating-system and architecture boundary remains Linux x64 only. The local `0.12.0` release candidate requires Node.js `>=22.13.0`, with evidence targeted at exact Node.js 22.13.0 and the governed Node.js 24 major. Published v0.11.2 retains its immutable Node.js 22.13.0/24 release matrix. Managed setup mutation requires GNU coreutils 9.7 `mv --update=none-fail --exchange --no-copy --no-target-directory`, GNU coreutils `ln -L -T`, and procfs descriptor-relative paths at `/proc/self/fd` with `O_DIRECTORY`/`O_NOFOLLOW`. The candidate's default SQLite cache also relies on Linux ownership, mode, no-follow, link-count and inode-identity checks; it does not defend against a malicious same-UID process. Other Linux architectures and systems without those primitives are unverified, as are macOS and Windows. Remote, untrusted, and multi-tenant use is outside the supported security boundary.
 
 ## Reporting a vulnerability
 

package/dist/batch/schema.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { toolCatalog } from "../tools/catalog.js";
 export const BATCH_SCHEMA_VERSION = 1;
 export const MAX_BATCH_STEPS = 50;
 export const MAX_BATCH_INVOCATIONS = 500;
@@ -8,22 +9,12 @@ export const MAX_BATCH_CONCURRENCY = 16;
 export const MAX_BATCH_INPUT_BYTES = 1024 * 1024;
 export const MAX_BATCH_OUTPUT_BYTES = 10 * 1024 * 1024;
 export const MAX_BATCH_CONTEXT_BYTES = 50 * 1024 * 1024;
-export const READ_BATCH_TOOLS = [
-    "ast_list_files",
-    "ast_get_outline",
-    "ast_get_symbol_source",
-    "ast_search_symbols",
-    "ast_find_references",
-    "ast_find_test_candidates",
-    "ast_explore",
-    "ast_get_diagnostics",
-];
-export const PREPARE_BATCH_TOOLS = [
-    "ast_rename_symbol",
-    "ast_replace_symbol_body",
-    "ast_scaffold_class",
-];
-export const BATCH_TOOLS = [...READ_BATCH_TOOLS, ...PREPARE_BATCH_TOOLS];
+export const READ_BATCH_TOOLS = toolCatalog.batch.read;
+export const PREPARE_BATCH_TOOLS = toolCatalog.batch.prepare;
+export const BATCH_TOOLS = Object.freeze([
+    ...READ_BATCH_TOOLS,
+    ...PREPARE_BATCH_TOOLS,
+]);
 const BatchToolSchema = z.enum(BATCH_TOOLS);
 const BatchStepSchema = z
     .object({

package/dist/server.js

@@ -1,22 +1,7 @@
 import { createRequire } from "node:module";
 import { McpServer, } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { PublicOperationalError } from "./services/public-errors.js";
-import { registerApplyOperation } from "./tools/apply_operation.js";
-import { registerFindReferences } from "./tools/find_references.js";
-import { registerFindTestCandidates } from "./tools/find_test_candidates.js";
-import { registerGetDiagnostics } from "./tools/get_diagnostics.js";
-import { registerGetFile } from "./tools/get_file.js";
-import { registerGetImpact } from "./tools/get_impact.js";
-import { registerGetOperationPreview } from "./tools/get_operation_preview.js";
-import { registerGetOutline } from "./tools/get_outline.js";
-import { registerGetProjectStatus } from "./tools/get_project_status.js";
-import { registerGetSymbolSource } from "./tools/get_symbol_source.js";
-import { registerListFiles } from "./tools/list_files.js";
-import { registerRenameSymbol } from "./tools/rename_symbol.js";
-import { registerReplaceSymbolBody } from "./tools/replace_symbol_body.js";
-import { registerScaffoldClass } from "./tools/scaffold_class.js";
-import { registerSearchSymbols } from "./tools/search_symbols.js";
-import { registerExplore } from "./tools/explore.js";
+import { toolCatalog } from "./tools/catalog.js";
 import { createToolErrorContext, errorResult } from "./tools/result.js";
 const packageMetadata = createRequire(import.meta.url)("../package.json");
 export const PACKAGE_VERSION = packageMetadata.version;
@@ -40,21 +25,6 @@ export function createServer(options = {}) {
     });
     if (options.runtimeActivity)
         installRuntimeActivityTracking(server, options.runtimeActivity);
-    registerListFiles(server);
-    registerGetProjectStatus(server);
-    registerExplore(server);
-    registerGetOutline(server);
-    registerGetSymbolSource(server);
-    registerSearchSymbols(server);
-    registerFindReferences(server);
-    registerGetImpact(server);
-    registerFindTestCandidates(server);
-    registerGetDiagnostics(server);
-    registerGetFile(server);
-    registerRenameSymbol(server);
-    registerReplaceSymbolBody(server);
-    registerScaffoldClass(server);
-    registerGetOperationPreview(server);
-    registerApplyOperation(server);
+    toolCatalog.registerAll(server);
     return server;
 }

package/dist/services/agent-targets.js

@@ -1,18 +1,6 @@
+import { toolCatalog } from "../tools/catalog.js";
 export const MCP_SERVER_NAME = "ast";
-const EXPECTED_TOOLS = [
-    "ast_list_files",
-    "ast_get_outline",
-    "ast_get_symbol_source",
-    "ast_search_symbols",
-    "ast_find_references",
-    "ast_find_test_candidates",
-    "ast_get_diagnostics",
-    "ast_rename_symbol",
-    "ast_replace_symbol_body",
-    "ast_scaffold_class",
-    "ast_get_operation_preview",
-    "ast_apply_operation",
-];
+const EXPECTED_TOOLS = toolCatalog.compatibility.required;
 function semver(value) {
     const match = value.match(/(?:^|\s|v)(\d+)\.(\d+)\.(\d+)(?=\s|$|[-+()]|\.(?:\s|$))/);
     return match ? [Number(match[1]), Number(match[2]), Number(match[3])] : undefined;

package/dist/services/diagnostics.js

@@ -1,6 +1,61 @@
 import path from "node:path";
 import { DiagnosticCategory, ts } from "ts-morph";
 import { NO_REQUEST_CONTEXT } from "./request-context.js";
+export const DIAGNOSTIC_AGGREGATE_GROUP_LIMIT = 20;
+function safeCount(value) {
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new RangeError("Diagnostic aggregate count is outside the safe integer range.");
+    }
+    return value;
+}
+function increment(counts, key) {
+    counts.set(key, safeCount((counts.get(key) ?? 0) + 1));
+}
+function rankGroups(counts, createGroup, compareKey, groupedDiagnosticCount, requestContext) {
+    const groups = [];
+    for (const [key, count] of counts) {
+        requestContext.checkpoint();
+        groups.push(createGroup(key, safeCount(count)));
+    }
+    groups.sort((left, right) => {
+        requestContext.checkpoint();
+        return right.count - left.count || compareKey(left, right);
+    });
+    const selected = groups.slice(0, DIAGNOSTIC_AGGREGATE_GROUP_LIMIT);
+    const covered = safeCount(selected.reduce((total, group) => safeCount(total + group.count), 0));
+    const omittedGroups = safeCount(groups.length - selected.length);
+    return {
+        groups: selected,
+        total_group_count: safeCount(groups.length),
+        omitted_group_count: omittedGroups,
+        covered_diagnostic_count: covered,
+        omitted_diagnostic_count: safeCount(groupedDiagnosticCount - covered),
+        truncated: omittedGroups > 0,
+    };
+}
+export function buildDiagnosticAggregates(diagnostics, requestContext = NO_REQUEST_CONTEXT) {
+    requestContext.checkpoint();
+    const codeCounts = new Map();
+    const fileCounts = new Map();
+    let unfiled = 0;
+    for (const diagnostic of diagnostics) {
+        requestContext.checkpoint();
+        increment(codeCounts, diagnostic.code);
+        if (diagnostic.file === null) {
+            unfiled = safeCount(unfiled + 1);
+        }
+        else {
+            increment(fileCounts, diagnostic.file);
+        }
+    }
+    const codes = rankGroups(codeCounts, (code, count) => ({ code, count }), (left, right) => left.code - right.code, safeCount(diagnostics.length), requestContext);
+    const files = rankGroups(fileCounts, (file, count) => ({ file, count }), (left, right) => (left.file < right.file ? -1 : left.file > right.file ? 1 : 0), safeCount(diagnostics.length - unfiled), requestContext);
+    return {
+        group_limit: DIAGNOSTIC_AGGREGATE_GROUP_LIMIT,
+        codes,
+        files: { ...files, unfiled_diagnostic_count: unfiled },
+    };
+}
 export function normalizeDiagnostic(diagnostic, projectRoot, requestContext = NO_REQUEST_CONTEXT) {
     requestContext.checkpoint();
     const sourceFile = diagnostic.getSourceFile();

package/dist/tools/apply_operation.js

@@ -2,6 +2,7 @@ import { z } from "zod";
 import { applyOperation } from "../services/operations.js";
 import { createRequestContext } from "../services/request-context.js";
 import { createToolErrorContext, errorResult, structuredResult } from "./result.js";
+const TOOL_NAME = "ast_apply_operation";
 const AstApplyOperationInputSchema = z.object({
     operation_id: z.string().uuid().describe("Identifier returned by a prepare operation."),
     plan_hash: z.string().length(64).describe("Plan hash returned by the same prepare operation."),
@@ -15,7 +16,7 @@ const AstApplyOperationOutputSchema = z.object({
     idempotent_replay: z.boolean(),
 });
 export function registerApplyOperation(server) {
-    server.registerTool("ast_apply_operation", {
+    server.registerTool(TOOL_NAME, {
         title: "Apply a prepared structural operation",
         description: "Applies exactly the reviewed plan after verifying its plan hash and the complete TypeScript workspace fingerprint. Conflicts abort before writes; retries after success are idempotent.",
         inputSchema: AstApplyOperationInputSchema,
@@ -34,7 +35,9 @@ export function registerApplyOperation(server) {
             });
         }
         catch (error) {
-            return errorResult(error, createToolErrorContext("ast_apply_operation"));
+            return errorResult(error, createToolErrorContext(TOOL_NAME));
         }
     });
 }
+// prettier-ignore
+export const toolDescriptor = Object.freeze({ name: TOOL_NAME, register: registerApplyOperation, compatibility: "required", effect: "apply", batch: "none", directOutputFormats: Object.freeze(["json"]) });

package/dist/tools/catalog.js

@@ -0,0 +1,80 @@
+import { toolDescriptor as applyOperation } from "./apply_operation.js";
+import { toolDescriptor as explore } from "./explore.js";
+import { toolDescriptor as findReferences } from "./find_references.js";
+import { toolDescriptor as findTestCandidates } from "./find_test_candidates.js";
+import { toolDescriptor as getDiagnostics } from "./get_diagnostics.js";
+import { toolDescriptor as getFile } from "./get_file.js";
+import { toolDescriptor as getImpact } from "./get_impact.js";
+import { toolDescriptor as getOperationPreview } from "./get_operation_preview.js";
+import { toolDescriptor as getOutline } from "./get_outline.js";
+import { toolDescriptor as getProjectStatus } from "./get_project_status.js";
+import { toolDescriptor as getSymbolSource } from "./get_symbol_source.js";
+import { toolDescriptor as listFiles } from "./list_files.js";
+import { toolDescriptor as renameSymbol } from "./rename_symbol.js";
+import { toolDescriptor as replaceSymbolBody } from "./replace_symbol_body.js";
+import { toolDescriptor as scaffoldClass } from "./scaffold_class.js";
+import { toolDescriptor as searchSymbols } from "./search_symbols.js";
+function validateDescriptor(descriptor) {
+    const formats = descriptor.directOutputFormats.join(",");
+    const valid = (descriptor.effect === "read" &&
+        (descriptor.batch === "none" || descriptor.batch === "read") &&
+        (formats === "json" || formats === "json,toon")) ||
+        (descriptor.effect === "prepare" && descriptor.batch === "prepare" && formats === "json") ||
+        (descriptor.effect === "apply" && descriptor.batch === "none" && formats === "json");
+    if (!valid)
+        throw new Error(`Contradictory capability descriptor: ${descriptor.name}`);
+}
+export function defineToolCatalog(input) {
+    const seen = new Set();
+    for (const descriptor of input) {
+        if (seen.has(descriptor.name))
+            throw new Error(`Duplicate tool name: ${descriptor.name}`);
+        seen.add(descriptor.name);
+        validateDescriptor(descriptor);
+    }
+    const descriptors = Object.freeze(input.map((descriptor) => Object.freeze({
+        ...descriptor,
+        directOutputFormats: Object.freeze([...descriptor.directOutputFormats]),
+    })));
+    const names = (predicate) => Object.freeze(descriptors.filter(predicate).map(({ name }) => name));
+    return Object.freeze({
+        descriptors,
+        batch: Object.freeze({
+            read: names((item) => item.batch === "read"),
+            prepare: names((item) => item.batch === "prepare"),
+            excluded: names((item) => item.batch === "none"),
+        }),
+        compatibility: Object.freeze({
+            required: names((item) => item.compatibility === "required"),
+            optional: names((item) => item.compatibility === "optional"),
+        }),
+        byEffect: Object.freeze({
+            read: names((item) => item.effect === "read"),
+            prepare: names((item) => item.effect === "prepare"),
+            apply: names((item) => item.effect === "apply"),
+        }),
+        directToon: names((item) => item.directOutputFormats.length === 2),
+        registerAll(server) {
+            for (const descriptor of descriptors)
+                descriptor.register(server);
+        },
+    });
+}
+export const toolCatalog = defineToolCatalog([
+    listFiles,
+    getProjectStatus,
+    explore,
+    getOutline,
+    getSymbolSource,
+    searchSymbols,
+    findReferences,
+    getImpact,
+    findTestCandidates,
+    getDiagnostics,
+    getFile,
+    renameSymbol,
+    replaceSymbolBody,
+    scaffoldClass,
+    getOperationPreview,
+    applyOperation,
+]);

package/dist/tools/explore.js

@@ -8,6 +8,7 @@ import { createRequestContext } from "../services/request-context.js";
 import { FRESHNESS_CAUSES, SNAPSHOT_STATES, TRUNCATION_REASONS, } from "../services/read-contracts.js";
 import { createToolErrorContext, errorResult, structuredResult } from "./result.js";
 import { RelationshipEndpointSchema } from "./relationship-schema.js";
+const TOOL_NAME = "ast_explore";
 const ExploreDetailSchema = z.enum(["selectors", "summary", "context", "full"]).default("summary");
 const ReferenceDetailSchema = z.enum(["locations", "context"]).default("locations");
 const CallSpinesInputSchema = z.object({
@@ -200,7 +201,7 @@ const ExploreOutputSchema = z.object({
     }),
 });
 export function registerExplore(server) {
-    server.registerTool("ast_explore", {
+    server.registerTool(TOOL_NAME, {
         title: "Explore project context",
         description: "Composes bounded structural search, exact selectors, source evidence and compiler references without weakening the primitive AST tools. Returns bounded session freshness metadata for fresh, pending, stale, rebuilding or degraded state.",
         inputSchema: ExploreInputSchema,
@@ -241,7 +242,9 @@ export function registerExplore(server) {
             return structuredResult(ExploreOutputSchema.parse(output));
         }
         catch (error) {
-            return errorResult(error, createToolErrorContext("ast_explore", project_root));
+            return errorResult(error, createToolErrorContext(TOOL_NAME, project_root));
         }
     });
 }
+// prettier-ignore
+export const toolDescriptor = Object.freeze({ name: TOOL_NAME, register: registerExplore, compatibility: "optional", effect: "read", batch: "read", directOutputFormats: Object.freeze(["json"]) });

package/dist/tools/find_references.js

@@ -4,6 +4,7 @@ import { findDeclarationByName, getSourceFileOrThrow, withProject } from "../ser
 import { collectSymbolReferences } from "../services/references.js";
 import { createRequestContext } from "../services/request-context.js";
 import { createToolErrorContext, errorResult, formattedResult, ToolOutputFormatInputSchema, } from "./result.js";
+const TOOL_NAME = "ast_find_references";
 const ReferenceDetailSchema = z.enum(["locations", "context"]).default("locations");
 const AstFindReferencesInputSchema = z.object({
     project_root: z
@@ -44,7 +45,7 @@ const ReferenceOutputSchemas = {
     }),
 };
 export function registerFindReferences(server) {
-    server.registerTool("ast_find_references", {
+    server.registerTool(TOOL_NAME, {
         title: "Find semantic symbol references",
         description: "Finds type-resolved references and returns bounded project-relative locations, including declaration impact by default.",
         inputSchema: AstFindReferencesInputSchema,
@@ -76,7 +77,9 @@ export function registerFindReferences(server) {
             return formattedResult(outputSchema, structuredContent, output_format);
         }
         catch (error) {
-            return errorResult(error, createToolErrorContext("ast_find_references", project_root));
+            return errorResult(error, createToolErrorContext(TOOL_NAME, project_root));
         }
     });
 }
+// prettier-ignore
+export const toolDescriptor = Object.freeze({ name: TOOL_NAME, register: registerFindReferences, compatibility: "required", effect: "read", batch: "read", directOutputFormats: Object.freeze(["json", "toon"]) });

package/dist/tools/find_test_candidates.js

@@ -7,6 +7,7 @@ import { createRequestContext } from "../services/request-context.js";
 import { findTestCandidates, MAX_TEST_CANDIDATE_CONVENTION_ITEMS, MAX_TEST_CANDIDATE_CONVENTION_LENGTH, TEST_CANDIDATE_CONFIDENCES, TEST_CANDIDATE_REASONS, } from "../services/test-candidates.js";
 import { FreshnessSchema, RelationshipEdgeSchema, RelationshipEndpointSchema, } from "./relationship-schema.js";
 import { createToolErrorContext, errorResult, structuredResult } from "./result.js";
+const TOOL_NAME = "ast_find_test_candidates";
 const ConventionSchema = z
     .array(z.string().min(1).max(MAX_TEST_CANDIDATE_CONVENTION_LENGTH))
     .max(MAX_TEST_CANDIDATE_CONVENTION_ITEMS)
@@ -59,7 +60,7 @@ const FindTestCandidatesOutputSchema = z.object({
     }),
 });
 export function registerFindTestCandidates(server) {
-    server.registerTool("ast_find_test_candidates", {
+    server.registerTool(TOOL_NAME, {
         title: "Find compiler-backed affected test candidates",
         description: "Finds deterministic affected test candidates from fresh, complete incoming compiler relationships. Returns bounded whole-candidate proofs and never executes tests or prepares mutations.",
         inputSchema: AstFindTestCandidatesInputSchema,
@@ -118,7 +119,9 @@ export function registerFindTestCandidates(server) {
             return structuredResult(FindTestCandidatesOutputSchema.parse(result));
         }
         catch (error) {
-            return errorResult(error, createToolErrorContext("ast_find_test_candidates", project_root));
+            return errorResult(error, createToolErrorContext(TOOL_NAME, project_root));
         }
     });
 }
+// prettier-ignore
+export const toolDescriptor = Object.freeze({ name: TOOL_NAME, register: registerFindTestCandidates, compatibility: "required", effect: "read", batch: "read", directOutputFormats: Object.freeze(["json"]) });

package/dist/tools/get_diagnostics.js

@@ -1,9 +1,10 @@
 import { z } from "zod";
-import { normalizeDiagnostic } from "../services/diagnostics.js";
+import { buildDiagnosticAggregates, DIAGNOSTIC_AGGREGATE_GROUP_LIMIT, normalizeDiagnostic, } from "../services/diagnostics.js";
 import { PaginationInputSchema, PaginationOutputSchema, paginate } from "../services/pagination.js";
 import { getSourceFileOrThrow, withProject } from "../services/project.js";
 import { createRequestContext } from "../services/request-context.js";
 import { createToolErrorContext, errorResult, formattedResult, ToolOutputFormatInputSchema, } from "./result.js";
+const TOOL_NAME = "ast_get_diagnostics";
 const DiagnosticSchema = z.object({
     code: z.number().int(),
     category: z.string(),
@@ -12,6 +13,29 @@ const DiagnosticSchema = z.object({
     column: z.number().int().positive().nullable(),
     message: z.string(),
 });
+const AggregateMetadataSchema = {
+    total_group_count: z.number().int().safe().min(0),
+    omitted_group_count: z.number().int().safe().min(0),
+    covered_diagnostic_count: z.number().int().safe().min(0),
+    omitted_diagnostic_count: z.number().int().safe().min(0),
+    truncated: z.boolean(),
+};
+const DiagnosticAggregatesSchema = z.object({
+    group_limit: z.literal(DIAGNOSTIC_AGGREGATE_GROUP_LIMIT),
+    codes: z.object({
+        groups: z
+            .array(z.object({ code: z.number().int().safe(), count: z.number().int().safe().positive() }))
+            .max(DIAGNOSTIC_AGGREGATE_GROUP_LIMIT),
+        ...AggregateMetadataSchema,
+    }),
+    files: z.object({
+        groups: z
+            .array(z.object({ file: z.string(), count: z.number().int().safe().positive() }))
+            .max(DIAGNOSTIC_AGGREGATE_GROUP_LIMIT),
+        ...AggregateMetadataSchema,
+        unfiled_diagnostic_count: z.number().int().safe().min(0),
+    }),
+});
 const AstGetDiagnosticsInputSchema = z.object({
     project_root: z
         .string()
@@ -20,6 +44,7 @@ const AstGetDiagnosticsInputSchema = z.object({
         .string()
         .optional()
         .describe("Optional project-relative or absolute file path. Omit for project diagnostics."),
+    include_aggregates: z.boolean().optional().default(false),
     ...ToolOutputFormatInputSchema,
     ...PaginationInputSchema,
 });
@@ -28,10 +53,11 @@ const AstGetDiagnosticsOutputSchema = z.object({
     error_count: z.number().int().min(0),
     warning_count: z.number().int().min(0),
     duration_ms: z.number().min(0),
+    aggregates: DiagnosticAggregatesSchema.optional(),
     ...PaginationOutputSchema,
 });
 export function registerGetDiagnostics(server) {
-    server.registerTool("ast_get_diagnostics", {
+    server.registerTool(TOOL_NAME, {
         title: "Get TypeScript diagnostics",
         description: "Returns bounded normalized TypeScript diagnostics for a project or one source file. Existing errors are preserved as evidence for write-operation delta checks.",
         inputSchema: AstGetDiagnosticsInputSchema,
@@ -41,7 +67,7 @@ export function registerGetDiagnostics(server) {
             idempotentHint: true,
             openWorldHint: false,
         },
-    }, async ({ project_root, file_path, output_format, offset, limit }, extra) => {
+    }, async ({ project_root, file_path, include_aggregates, output_format, offset, limit }, extra) => {
         const requestContext = createRequestContext(extra.signal);
         try {
             const structuredContent = await withProject(project_root, ({ project, projectRoot }, operationContext) => {
@@ -52,6 +78,9 @@ export function registerGetDiagnostics(server) {
                 const normalized = diagnostics
                     .map((diagnostic) => normalizeDiagnostic(diagnostic, projectRoot, operationContext))
                     .sort((left, right) => `${left.file ?? ""}:${left.line ?? 0}:${left.column ?? 0}:${left.code}`.localeCompare(`${right.file ?? ""}:${right.line ?? 0}:${right.column ?? 0}:${right.code}`));
+                const aggregates = include_aggregates
+                    ? buildDiagnosticAggregates(normalized, operationContext)
+                    : undefined;
                 const page = paginate(normalized, offset, limit);
                 const { items, ...metadata } = page;
                 return {
@@ -61,13 +90,16 @@ export function registerGetDiagnostics(server) {
                     warning_count: normalized.filter((diagnostic) => diagnostic.category === "Warning")
                         .length,
                     duration_ms: performance.now() - startedAt,
+                    ...(aggregates ? { aggregates } : {}),
                     ...metadata,
                 };
             }, requestContext);
             return formattedResult(AstGetDiagnosticsOutputSchema, structuredContent, output_format);
         }
         catch (error) {
-            return errorResult(error, createToolErrorContext("ast_get_diagnostics", project_root));
+            return errorResult(error, createToolErrorContext(TOOL_NAME, project_root));
         }
     });
 }
+// prettier-ignore
+export const toolDescriptor = Object.freeze({ name: TOOL_NAME, register: registerGetDiagnostics, compatibility: "required", effect: "read", batch: "read", directOutputFormats: Object.freeze(["json", "toon"]) });

package/dist/tools/get_file.js

@@ -5,6 +5,7 @@ import { getSourceFileOrThrow, withProject } from "../services/project.js";
 import { createRequestContext } from "../services/request-context.js";
 import { FRESHNESS_CAUSES, SNAPSHOT_STATES } from "../services/read-contracts.js";
 import { createToolErrorContext, errorResult, structuredResult } from "./result.js";
+const TOOL_NAME = "ast_get_file";
 const AstGetFileInputSchema = z.object({
     project_root: z
         .string()
@@ -60,7 +61,7 @@ const AstGetFileOutputSchema = z.object({
     symbols: z.array(OutlineSymbolSchema).optional(),
 });
 export function registerGetFile(server) {
-    server.registerTool("ast_get_file", {
+    server.registerTool(TOOL_NAME, {
         title: "Get bounded source file",
         description: "Returns exact bounded source lines for one TypeScript/JavaScript file, or body-free symbols when symbols_only is true. Read-only; file snapshot freshness and project freshness are reported separately from compiler diagnostics.",
         inputSchema: AstGetFileInputSchema,
@@ -101,7 +102,9 @@ export function registerGetFile(server) {
             return structuredResult(structuredContent);
         }
         catch (error) {
-            return errorResult(error, createToolErrorContext("ast_get_file", project_root));
+            return errorResult(error, createToolErrorContext(TOOL_NAME, project_root));
         }
     });
 }
+// prettier-ignore
+export const toolDescriptor = Object.freeze({ name: TOOL_NAME, register: registerGetFile, compatibility: "optional", effect: "read", batch: "none", directOutputFormats: Object.freeze(["json"]) });

package/dist/tools/get_impact.js

@@ -6,6 +6,7 @@ import { createRequestContext } from "../services/request-context.js";
 import { RELATIONSHIP_EDGE_KINDS } from "../services/relationships.js";
 import { FreshnessSchema, RelationshipEdgeSchema, RelationshipEndpointSchema, } from "./relationship-schema.js";
 import { createToolErrorContext, errorResult, formattedResult, ToolOutputFormatInputSchema, } from "./result.js";
+const TOOL_NAME = "ast_get_impact";
 const AstGetImpactInputSchema = z.object({
     project_root: z
         .string()
@@ -68,7 +69,7 @@ const ImpactOutputSchema = z.object({
     freshness: FreshnessSchema,
 });
 export function registerGetImpact(server) {
-    server.registerTool("ast_get_impact", {
+    server.registerTool(TOOL_NAME, {
         title: "Get bounded compiler-backed impact",
         description: "Traverses exact compiler-backed relationships around a symbol with explicit direction, depth, node and edge budgets. Returns bounded session freshness metadata and fails closed when exact relationships are not fresh. Read-only evidence only; it never prepares or applies mutations.",
         inputSchema: AstGetImpactInputSchema,
@@ -101,7 +102,9 @@ export function registerGetImpact(server) {
             return formattedResult(ImpactOutputSchema, structuredContent, output_format);
         }
         catch (error) {
-            return errorResult(error, createToolErrorContext("ast_get_impact", project_root));
+            return errorResult(error, createToolErrorContext(TOOL_NAME, project_root));
         }
     });
 }
+// prettier-ignore
+export const toolDescriptor = Object.freeze({ name: TOOL_NAME, register: registerGetImpact, compatibility: "optional", effect: "read", batch: "none", directOutputFormats: Object.freeze(["json", "toon"]) });

package/dist/tools/get_operation_preview.js

@@ -2,6 +2,7 @@ import { z } from "zod";
 import { getOperationPreview } from "../services/operations.js";
 import { createRequestContext } from "../services/request-context.js";
 import { createToolErrorContext, errorResult, structuredResult } from "./result.js";
+const TOOL_NAME = "ast_get_operation_preview";
 const AstGetOperationPreviewInputSchema = z.object({
     operation_id: z.string().uuid(),
     file: z.string().optional().describe("Optional affected file path to retrieve only its diff."),
@@ -12,7 +13,7 @@ const AstGetOperationPreviewOutputSchema = z.object({
     files: z.array(z.object({ file: z.string(), diff: z.string() })),
 });
 export function registerGetOperationPreview(server) {
-    server.registerTool("ast_get_operation_preview", {
+    server.registerTool(TOOL_NAME, {
         title: "Get complete prepared-operation diff",
         description: "Retrieves exact unified diffs retained for a prepared operation, optionally one affected file at a time.",
         inputSchema: AstGetOperationPreviewInputSchema,
@@ -30,7 +31,9 @@ export function registerGetOperationPreview(server) {
             return structuredResult(output);
         }
         catch (error) {
-            return errorResult(error, createToolErrorContext("ast_get_operation_preview"));
+            return errorResult(error, createToolErrorContext(TOOL_NAME));
         }
     });
 }
+// prettier-ignore
+export const toolDescriptor = Object.freeze({ name: TOOL_NAME, register: registerGetOperationPreview, compatibility: "required", effect: "read", batch: "none", directOutputFormats: Object.freeze(["json"]) });

package/dist/tools/get_outline.js

@@ -4,6 +4,7 @@ import { buildFileOutline } from "../services/outline.js";
 import { getSourceFileOrThrow, withProject } from "../services/project.js";
 import { createRequestContext } from "../services/request-context.js";
 import { createToolErrorContext, errorResult, structuredResult } from "./result.js";
+const TOOL_NAME = "ast_get_outline";
 const AstGetOutlineInputSchema = z.object({
     project_root: z
         .string()
@@ -28,7 +29,7 @@ const AstGetOutlineOutputSchema = z.object({
     symbols: z.array(OutlineSymbolSchema).optional(),
 });
 export function registerGetOutline(server) {
-    server.registerTool("ast_get_outline", {
+    server.registerTool(TOOL_NAME, {
         title: "Get compact file outline",
         description: "Returns body-free declaration signatures for one TypeScript/JavaScript file. Detailed symbol metadata is opt-in because it duplicates signature text.",
         inputSchema: AstGetOutlineInputSchema,
@@ -54,7 +55,9 @@ export function registerGetOutline(server) {
             return structuredResult(structuredContent);
         }
         catch (error) {
-            return errorResult(error, createToolErrorContext("ast_get_outline", project_root));
+            return errorResult(error, createToolErrorContext(TOOL_NAME, project_root));
         }
     });
 }
+// prettier-ignore
+export const toolDescriptor = Object.freeze({ name: TOOL_NAME, register: registerGetOutline, compatibility: "required", effect: "read", batch: "read", directOutputFormats: Object.freeze(["json"]) });

package/dist/tools/get_project_status.js

@@ -3,6 +3,7 @@ import { FRESHNESS_CAUSES, SNAPSHOT_STATES, TRUNCATION_REASONS, } from "../servi
 import { getProjectStatus } from "../services/project.js";
 import { createRequestContext } from "../services/request-context.js";
 import { createToolErrorContext, errorResult, structuredResult } from "./result.js";
+const TOOL_NAME = "ast_get_project_status";
 const AstGetProjectStatusInputSchema = z.object({
     project_root: z
         .string()
@@ -113,7 +114,7 @@ const ProjectStatusOutputSchema = z.object({
     index_observability: IndexObservabilitySchema,
 });
 export function registerGetProjectStatus(server) {
-    server.registerTool("ast_get_project_status", {
+    server.registerTool(TOOL_NAME, {
         title: "Get project freshness status",
         description: "Returns bounded, read-only compiler freshness and project status without exposing filesystem identities or credentials.",
         inputSchema: AstGetProjectStatusInputSchema,
@@ -131,7 +132,9 @@ export function registerGetProjectStatus(server) {
             return structuredResult({ ...output });
         }
         catch (error) {
-            return errorResult(error, createToolErrorContext("ast_get_project_status", project_root));
+            return errorResult(error, createToolErrorContext(TOOL_NAME, project_root));
         }
     });
 }
+// prettier-ignore
+export const toolDescriptor = Object.freeze({ name: TOOL_NAME, register: registerGetProjectStatus, compatibility: "optional", effect: "read", batch: "none", directOutputFormats: Object.freeze(["json"]) });

package/dist/tools/get_symbol_source.js

@@ -3,6 +3,7 @@ import { nodeSourceWithLocation } from "../services/outline.js";
 import { findDeclarationByName, getSourceFileOrThrow, withProject } from "../services/project.js";
 import { createRequestContext } from "../services/request-context.js";
 import { createToolErrorContext, errorResult, structuredResult } from "./result.js";
+const TOOL_NAME = "ast_get_symbol_source";
 const AstGetSymbolSourceInputSchema = z.object({
     project_root: z
         .string()
@@ -17,7 +18,7 @@ const AstGetSymbolSourceOutputSchema = z.object({
     text: z.string(),
 });
 export function registerGetSymbolSource(server) {
-    server.registerTool("ast_get_symbol_source", {
+    server.registerTool(TOOL_NAME, {
         title: "Get one symbol implementation",
         description: "Returns exactly one declaration or implementation with its project-relative location, not the complete file.",
         inputSchema: AstGetSymbolSourceInputSchema,
@@ -39,7 +40,9 @@ export function registerGetSymbolSource(server) {
             return structuredResult(structuredContent);
         }
         catch (error) {
-            return errorResult(error, createToolErrorContext("ast_get_symbol_source", project_root));
+            return errorResult(error, createToolErrorContext(TOOL_NAME, project_root));
         }
     });
 }
+// prettier-ignore
+export const toolDescriptor = Object.freeze({ name: TOOL_NAME, register: registerGetSymbolSource, compatibility: "required", effect: "read", batch: "read", directOutputFormats: Object.freeze(["json"]) });

package/dist/tools/list_files.js

@@ -4,6 +4,7 @@ import { PaginationInputSchema, PaginationOutputSchema, paginate } from "../serv
 import { withProject } from "../services/project.js";
 import { createRequestContext } from "../services/request-context.js";
 import { createToolErrorContext, errorResult, structuredResult } from "./result.js";
+const TOOL_NAME = "ast_list_files";
 const AstListFilesInputSchema = z.object({
     project_root: z
         .string()
@@ -19,7 +20,7 @@ const AstListFilesOutputSchema = z.object({
     ...PaginationOutputSchema,
 });
 export function registerListFiles(server) {
-    server.registerTool("ast_list_files", {
+    server.registerTool(TOOL_NAME, {
         title: "List TypeScript/JavaScript project files",
         description: "Lists source files included by the project's tsconfig in deterministic, project-relative, paginated form.",
         inputSchema: AstListFilesInputSchema,
@@ -50,7 +51,9 @@ export function registerListFiles(server) {
             return structuredResult(output);
         }
         catch (error) {
-            return errorResult(error, createToolErrorContext("ast_list_files", project_root));
+            return errorResult(error, createToolErrorContext(TOOL_NAME, project_root));
         }
     });
 }
+// prettier-ignore
+export const toolDescriptor = Object.freeze({ name: TOOL_NAME, register: registerListFiles, compatibility: "required", effect: "read", batch: "read", directOutputFormats: Object.freeze(["json"]) });

package/dist/tools/rename_symbol.js

@@ -3,6 +3,7 @@ import { prepareRename } from "../services/operations.js";
 import { createRequestContext } from "../services/request-context.js";
 import { PreparedOperationOutputSchema, serializePreparedOperation } from "./operation-schema.js";
 import { createToolErrorContext, errorResult, structuredResult } from "./result.js";
+const TOOL_NAME = "ast_rename_symbol";
 const AstRenameSymbolInputSchema = z.object({
     project_root: z.string(),
     file_path: z.string(),
@@ -18,7 +19,7 @@ const AstRenameSymbolInputSchema = z.object({
         .describe("Permit a plan with new TypeScript errors after explicit review."),
 });
 export function registerRenameSymbol(server) {
-    server.registerTool("ast_rename_symbol", {
+    server.registerTool(TOOL_NAME, {
         title: "Prepare a project-wide structural rename",
         description: "Prepares an exact hash-bound rename plan without writing. Review the preview and apply its operation_id with ast_apply_operation.",
         inputSchema: AstRenameSymbolInputSchema,
@@ -45,7 +46,9 @@ export function registerRenameSymbol(server) {
             return structuredResult(serializePreparedOperation(operation));
         }
         catch (error) {
-            return errorResult(error, createToolErrorContext("ast_rename_symbol", project_root));
+            return errorResult(error, createToolErrorContext(TOOL_NAME, project_root));
         }
     });
 }
+// prettier-ignore
+export const toolDescriptor = Object.freeze({ name: TOOL_NAME, register: registerRenameSymbol, compatibility: "required", effect: "prepare", batch: "prepare", directOutputFormats: Object.freeze(["json"]) });

package/dist/tools/replace_symbol_body.js

@@ -3,6 +3,7 @@ import { prepareReplaceBody } from "../services/operations.js";
 import { createRequestContext } from "../services/request-context.js";
 import { PreparedOperationOutputSchema, serializePreparedOperation } from "./operation-schema.js";
 import { createToolErrorContext, errorResult, structuredResult } from "./result.js";
+const TOOL_NAME = "ast_replace_symbol_body";
 const AstReplaceSymbolBodyInputSchema = z.object({
     project_root: z.string(),
     file_path: z.string(),
@@ -18,7 +19,7 @@ const AstReplaceSymbolBodyInputSchema = z.object({
         .describe("Permit a plan with new TypeScript errors after explicit review."),
 });
 export function registerReplaceSymbolBody(server) {
-    server.registerTool("ast_replace_symbol_body", {
+    server.registerTool(TOOL_NAME, {
         title: "Prepare an exact function-body replacement",
         description: "Prepares a hash-bound body replacement while preserving the signature. Supports declarations, methods, accessors and function-valued variables/properties.",
         inputSchema: AstReplaceSymbolBodyInputSchema,
@@ -45,7 +46,9 @@ export function registerReplaceSymbolBody(server) {
             return structuredResult(serializePreparedOperation(operation));
         }
         catch (error) {
-            return errorResult(error, createToolErrorContext("ast_replace_symbol_body", project_root));
+            return errorResult(error, createToolErrorContext(TOOL_NAME, project_root));
         }
     });
 }
+// prettier-ignore
+export const toolDescriptor = Object.freeze({ name: TOOL_NAME, register: registerReplaceSymbolBody, compatibility: "required", effect: "prepare", batch: "prepare", directOutputFormats: Object.freeze(["json"]) });

package/dist/tools/scaffold_class.js

@@ -3,6 +3,7 @@ import { prepareScaffoldClass } from "../services/operations.js";
 import { createRequestContext } from "../services/request-context.js";
 import { createToolErrorContext, errorResult, structuredResult } from "./result.js";
 import { PreparedOperationOutputSchema, serializePreparedOperation } from "./operation-schema.js";
+const TOOL_NAME = "ast_scaffold_class";
 const IdentifierSchema = z.string().min(1).max(200);
 const TypeTextSchema = z.string().min(1).max(10_000);
 const AccessSchema = z.enum(["public", "protected", "private"]);
@@ -111,7 +112,7 @@ export function registerScaffoldClass(server) {
     // The SDK compatibility overload exceeds TypeScript's instantiation depth for this schema.
     // Keep the complete runtime schema and isolate only the registrar type.
     const registerTool = server.registerTool.bind(server);
-    registerTool("ast_scaffold_class", {
+    registerTool(TOOL_NAME, {
         title: "Prepare Class Scaffold",
         description: "Prepares a hash-bound new TypeScript class file without writing it. Each method body throws an explicit not-implemented error. Review the diff, then apply the returned operation_id and plan_hash with ast_apply_operation.",
         inputSchema: ScaffoldClassInputSchema,
@@ -141,7 +142,9 @@ export function registerScaffoldClass(server) {
             return structuredResult(structuredContent);
         }
         catch (error) {
-            return errorResult(error, createToolErrorContext("ast_scaffold_class", args.project_root));
+            return errorResult(error, createToolErrorContext(TOOL_NAME, args.project_root));
         }
     });
 }
+// prettier-ignore
+export const toolDescriptor = Object.freeze({ name: TOOL_NAME, register: registerScaffoldClass, compatibility: "required", effect: "prepare", batch: "prepare", directOutputFormats: Object.freeze(["json"]) });

package/dist/tools/search_symbols.js

@@ -4,6 +4,7 @@ import { withProject, reportSymbolIndexFailure } from "../services/project.js";
 import { createRequestContext } from "../services/request-context.js";
 import { searchProjectSymbolsPage, searchProjectSymbolsPageWithIndex, } from "../services/symbols.js";
 import { createToolErrorContext, errorResult, formattedResult, ToolOutputFormatInputSchema, } from "./result.js";
+const TOOL_NAME = "ast_search_symbols";
 const SEARCH_DEFAULT_LIMIT = 20;
 const SearchDetailSchema = z.enum(["selectors", "summary", "full"]).default("summary");
 const AstSearchSymbolsInputSchema = z.object({
@@ -77,7 +78,7 @@ function projectSymbols(detail, symbols) {
     return symbols.map(({ file, selector, kind }) => ({ file, selector, kind }));
 }
 export function registerSearchSymbols(server) {
-    server.registerTool("ast_search_symbols", {
+    server.registerTool(TOOL_NAME, {
         title: "Search project symbols",
         description: "Ranks structural declarations and returns exact file/symbol selectors for downstream AST tools.",
         inputSchema: AstSearchSymbolsInputSchema,
@@ -108,7 +109,9 @@ export function registerSearchSymbols(server) {
             return formattedResult(outputSchema, structuredContent, output_format);
         }
         catch (error) {
-            return errorResult(error, createToolErrorContext("ast_search_symbols", project_root));
+            return errorResult(error, createToolErrorContext(TOOL_NAME, project_root));
         }
     });
 }
+// prettier-ignore
+export const toolDescriptor = Object.freeze({ name: TOOL_NAME, register: registerSearchSymbols, compatibility: "required", effect: "read", batch: "read", directOutputFormats: Object.freeze(["json", "toon"]) });

package/docs/support.md

@@ -1,20 +1,20 @@
 # Support policy
 
-This document defines the supported platform, runtime, persistence, and operational boundary for published `ast-mcp-server` v0.10.0 and the local `0.11.2` release candidate.
+This document defines the supported platform, runtime, persistence, and operational boundary for published `ast-mcp-server` v0.11.2 and the local `0.12.0` release candidate.
 
 ## Supported release target
 
 | Environment                                                                   | Status      | Contract                                                                                      |
 | ----------------------------------------------------------------------------- | ----------- | --------------------------------------------------------------------------------------------- |
 | Linux x64 with required GNU coreutils and procfs, Node.js 22.5.0              | Historical  | Immutable v0.8.1 release evidence; not the runtime floor of the published or candidate lines. |
-| Linux x64 with required GNU coreutils and procfs, exact Node.js 22.13.0       | Supported   | Published v0.10.0 and local 0.11.2 matrices, each bound to its own package and tree bytes.    |
-| Linux x64 with required GNU coreutils and procfs, current Node.js 24 line     | Supported   | Published v0.10.0 and local 0.11.2 matrices, each bound to its own package and tree bytes.    |
+| Linux x64 with required GNU coreutils and procfs, exact Node.js 22.13.0       | Supported   | Published v0.11.2 and local 0.12.0 matrices, each bound to its own package and tree bytes.    |
+| Linux x64 with required GNU coreutils and procfs, current Node.js 24 line     | Supported   | Published v0.11.2 and local 0.12.0 matrices, each bound to its own package and tree bytes.    |
 | Other Linux architectures or systems without the required filesystem features | Unverified  | Not supported until equivalent architecture, mutation, and filesystem-publication gates pass. |
 | macOS                                                                         | Unverified  | Not supported until equivalent filesystem, process, package, mutation, and canary gates pass. |
 | Windows                                                                       | Unverified  | Not supported until equivalent filesystem, process, package, mutation, and canary gates pass. |
 | Remote, untrusted, or multi-tenant service use                                | Unsupported | No network authentication, sandbox, or tenant-isolation boundary is provided.                 |
 
-The local `0.11.2` release candidate requires Node.js `>=22.13.0`; its matrix targets exact Node.js 22.13.0 and the governed Node.js 24 major. Published v0.10.0 retains its immutable `>=22.13.0` metadata and exact Node.js 22.13.0/24 release evidence. The earlier v0.8.1 Node.js 22.5.0/24 matrix remains historical evidence for those bytes only. A future runtime satisfying an engine range is not automatically a verified release target.
+The local `0.12.0` release candidate requires Node.js `>=22.13.0`; its matrix targets exact Node.js 22.13.0 and the governed Node.js 24 major. Published v0.11.2 retains its immutable `>=22.13.0` metadata and exact Node.js 22.13.0/24 release evidence. The earlier v0.8.1 Node.js 22.5.0/24 matrix remains historical evidence for those bytes only. A future runtime satisfying an engine range is not automatically a verified release target.
 
 The checked-evidence freezer requires GNU coreutils 9.7 `mv` with `--update=none-fail`, `--no-copy`, and `--no-target-directory`. Managed setup-file mutation additionally requires that same `mv` with `--exchange`, GNU coreutils `ln -L -T`, procfs descriptor paths at `/proc/self/fd`, `O_DIRECTORY`, and `O_NOFOLLOW`. It fails closed when any verified Linux primitive is unavailable. Equivalent publication, exchange, descriptor-link, and descriptor-relative mutation semantics have not been verified on other operating systems or architectures.
 
@@ -50,7 +50,7 @@ The scoped Linux evidence passed on exact Node.js 22.13.0 and the governed Node.
 
 ## Symbol-index persistence
 
-Published v0.10.0 and the local `0.11.2` release candidate select native SQLite when the persistence setting is absent or explicitly `enabled`; operators requiring no persistent index state must set `disabled` explicitly:
+Published v0.11.2 and the local `0.12.0` release candidate select native SQLite when the persistence setting is absent or explicitly `enabled`; operators requiring no persistent index state must set `disabled` explicitly:
 
 ```bash
 AST_SYMBOL_INDEX_PERSISTENCE=disabled \
@@ -80,7 +80,7 @@ Both commands are bounded and path-free. Clear preflights the tree, refuses unsa
 
 ## Production-readiness acceptance
 
-The four retained Linux x64 production-readiness reports cover `ast-mcp-server` and `x-scraper` under Node.js 22.5.0 and Node.js 24 for package version 0.6.0, commit `2d0b21bbb80fae1acfca6a85d5891d87e68b59c1`, and tree `af931d49769fabdf06f623965a6cfe1f9afb8a81`. They are historical integration evidence only: they are not reattributed to v0.8.1, published-next v0.9.0 or v0.9.1, the local 0.9.2 candidate, published v0.10.0, published-next v0.11.0 or v0.11.1, or the local v0.11.2 release candidate. The exact 0.9.0 and 0.9.1 release matrices remain historical evidence for their immutable published-next bytes, the exact 0.9.2 matrix remains historical local-candidate evidence, the exact 0.10.0 matrix remains historical published-release evidence, and the exact 0.11.0 and 0.11.1 matrices remain historical evidence for their immutable published-next bytes before public-registry verification exposed their distinct verifier defects. A separate exact 0.11.2 release matrix is the release-candidate gate for current repository bytes under both supported runtime lines, including supervised-worker lifecycle and reclamation evidence, deterministic CLI project-discovery fixture setup, local-registry managed-asset verification, and the public copied-runner dependency-closure regression; none of these matrices rebinds the older retained reports. MCP-PROD-404 remains normative for admission:
+The four retained Linux x64 production-readiness reports cover `ast-mcp-server` and `x-scraper` under Node.js 22.5.0 and Node.js 24 for package version 0.6.0, commit `2d0b21bbb80fae1acfca6a85d5891d87e68b59c1`, and tree `af931d49769fabdf06f623965a6cfe1f9afb8a81`. They are historical integration evidence only: they are not reattributed to v0.8.1, published-next v0.9.0 or v0.9.1, the local 0.9.2 candidate, published v0.10.0, published-next v0.11.0 or v0.11.1, published v0.11.2, or the local v0.12.0 release candidate. The exact 0.9.0 and 0.9.1 release matrices remain historical evidence for their immutable published-next bytes, the exact 0.9.2 matrix remains historical local-candidate evidence, the exact 0.10.0 matrix remains historical published-release evidence, the exact 0.11.0 and 0.11.1 matrices remain historical evidence for their immutable published-next bytes before public-registry verification exposed their distinct verifier defects, and the exact 0.11.2 matrix remains historical published-release evidence. A separate exact 0.12.0 release matrix is the release-candidate gate for current repository bytes under both supported runtime lines, including bounded diagnostic aggregates, catalog-derived tool capability projections, and their independent release oracles; none of these matrices rebinds the older retained reports. MCP-PROD-404 remains normative for admission:
 
 - zero semantic mismatches across disabled, cold, warm, restart, and rollback reads;
 - byte-identical real-repository status and worktree trees;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ast-mcp-server",
-  "version": "0.11.2",
+  "version": "0.12.0",
   "description": "Structural code MCP server and batch CLI for compact TypeScript/JavaScript reads and hash-bound AST edits.",
   "keywords": [
     "mcp",
@@ -97,5 +97,5 @@
     "typescript-eslint": "^8.65.0",
     "vitest": "^4.1.10"
   },
-  "gitHead": "f7b429670093bd9f43195979e395ccf418eb4ba2"
+  "gitHead": "3991d0a74e672c6c4d3fbd1c8bbb1a60009515ec"
 }

package/skills/structural-code-editing/SKILL.md

@@ -4,7 +4,7 @@ description: "Trigger: navegar, analizar o editar TypeScript/JavaScript con el c
 license: "ISC"
 metadata:
   author: "yail"
-  version: "4.5.0"
+  version: "4.6.0"
   hermes:
     tags: ["typescript", "javascript", "ast", "refactoring", "mcp"]
     homepage: "https://github.com/yailPeralta/ast-mcp-server"
@@ -18,7 +18,7 @@ Cargar este skill antes de navegar semánticamente, analizar impacto o referenci
 
 No forzar un roundtrip AST para Markdown, configuración, comentarios ni una edición textual trivial en un archivo ya conocido. Si las tools `ast_*` no están disponibles, declarar el fallback y no presentar búsquedas textuales como evidencia compiler-backed.
 
-The local 0.11.2 release candidate requires Node.js `>=22.13.0` and is verified with exact Node.js 22.13.0 plus the governed Node.js 24 line. Published v0.10.0 retains its immutable Node.js 22.13.0/24 release evidence.
+The local 0.12.0 release candidate requires Node.js `>=22.13.0` and is verified with exact Node.js 22.13.0 plus the governed Node.js 24 line. Published v0.11.2 retains its immutable Node.js 22.13.0/24 release evidence.
 
 ## Hard Rules
 
@@ -29,6 +29,18 @@ The local 0.11.2 release candidate requires Node.js `>=22.13.0` and is verified
 - Nunca reconstruir postimages desde un diff; después del apply, ejecutar el gate canónico del proyecto.
 - Conservar `correlation_id` en errores públicos sin exponer source, paths absolutos, argumentos, environment, cache, stacks ni credenciales.
 
+## Diagnostic aggregates
+
+`ast_get_diagnostics` keeps its existing response shape unless `include_aggregates: true` is requested. Enabled summaries cover the complete normalized snapshot, not only the selected raw page, and cap both code and file groups at 20.
+
+For each dimension, `groups.length + omitted_group_count = total_group_count` and group counts sum to `covered_diagnostic_count`. Code coverage plus omitted diagnostics equals the total; file coverage additionally includes `unfiled_diagnostic_count`. File groups expose normalized project-relative paths only and may include paths absent from the raw page.
+
+## Contributor contract
+
+Al agregar o modificar una tool, mantener schemas, metadata, annotations, handler, errores y serialización en su módulo. Exportar un descriptor congelado y ubicarlo deliberadamente en `src/tools/catalog.ts`; el catálogo solo admite hechos estáticos de efecto, batch, compatibilidad y formatos directos.
+
+Las expectativas de `tools/list` deben seguir siendo independientes: revisar el inventario y metadata completos antes de actualizar sus hashes, sin importar ni derivar valores desde el catálogo.
+
 ## Decision Gates
 
 | Situación                              | Acción                                                                 |

package/skills/structural-code-editing/releases.json

@@ -2,11 +2,11 @@
   "schema_version": 2,
   "algorithm": "sha256",
   "current": {
-    "version": "4.5.0",
+    "version": "4.6.0",
     "files": [
       {
         "path": "SKILL.md",
-        "sha256": "18132b4b747d135e4ccfbca9e2190a9afb41e144cc06c31c5e6bc0f1571e11da"
+        "sha256": "d0048ffd9a585d00791540c6fa5e0bec91ff95b1448479678f85702e6b09be8a"
       },
       {
         "path": "references/operations.md",
@@ -79,6 +79,21 @@
       "version": "4.4.0",
       "sha256": "253b588c56d44c8f5565db3f33ce227d80c7c29aa6604d362844f44b1278385a",
       "npm_versions": ["0.10.0"]
+    },
+    {
+      "version": "4.5.0",
+      "sha256": "be757e8bd98733c7ee952d63a2805dcd9877becf651b4fcb6ab63d20f6546f21",
+      "npm_versions": ["0.11.0"]
+    },
+    {
+      "version": "4.5.0",
+      "sha256": "2729b30ff6b7344e6680c7ee02ab540bc6db9774ad7111f091cd356f8cc9d4ce",
+      "npm_versions": ["0.11.1"]
+    },
+    {
+      "version": "4.5.0",
+      "sha256": "18132b4b747d135e4ccfbca9e2190a9afb41e144cc06c31c5e6bc0f1571e11da",
+      "npm_versions": ["0.11.2"]
     }
   ]
 }