ast-mcp-server 0.5.1 → 0.6.0

package/CHANGELOG.md

@@ -4,6 +4,15 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.6.0] - 2026-08-05
+
+### Added
+
+- Read-only `ast_get_file` with bounded exact source lines, SHA-256 byte hashes, compiler snapshot state, and `symbols_only` body-free output.
+- Project-scoped file snapshot validation with UTF-8 checks, traversal rejection, symlink containment checks, and ambiguous-path failures.
+- Read-only `ast_explore` with query/file/symbol routing, progressive source and compiler-reference evidence, freshness/completeness metadata, unresolved selectors, and serialized byte budgets.
+- A deterministic context workflow benchmark comparing full-file, primitive, and composed exploration workflows.
+
 ## [0.5.1] - 2026-08-05
 
 ### Added

package/README.md

@@ -23,13 +23,25 @@ This MCP server gives the agent structural code tools in addition to generic fil
 
 | Need                           | Structural operation      | Returned scope                                        |
 | ------------------------------ | ------------------------- | ----------------------------------------------------- |
+| Read a bounded file            | `ast_get_file`            | Exact selected source lines, hash, and snapshot state |
+| Explore bounded context        | `ast_explore`             | Ranked selectors plus optional source and references  |
 | Understand a file              | `ast_get_outline`         | Signatures without implementation bodies              |
 | Inspect one declaration        | `ast_get_symbol_source`   | Exact source for one function, method, class, or type |
 | Find usages across the project | `ast_find_references`     | Compiler-resolved reference locations                 |
 | Rename a symbol everywhere     | `ast_rename_symbol`       | A reviewed project-wide rename plan                   |
 | Change one implementation      | `ast_replace_symbol_body` | A body-only plan that preserves the declaration       |
 
-Reads can start with a compact outline and fetch exact source only when needed. Mutations are prepared in memory first, compared against baseline diagnostics, and returned as immutable, hash-bound plans. Nothing is written until the caller reviews and explicitly applies the plan.
+Reads can start with a bounded file slice, a compact outline, or exact source only for the declaration that needs inspection. Mutations are prepared in memory first, compared against baseline diagnostics, and returned as immutable, hash-bound plans. Nothing is written until the caller reviews and explicitly applies the plan.
+
+### Choosing a read tool
+
+- Use `ast_get_file` when the file path is known and the agent needs exact source lines. It is read-only, uses zero-based `offset` and bounded `limit`, returns one-based line records, a SHA-256 byte hash, and `snapshot_state`.
+- Use `ast_get_file` with `symbols_only: true` when only selectors and body-free signatures are needed from one known file.
+- Use `ast_explore` when the question spans discovery and evidence. Its default summary is bounded; use `detail: "context"` for selected source and `detail: "full"` for source plus compiler references.
+- Use `ast_get_outline` for a compact body-free view of a known file without source lines.
+- Use `ast_get_symbol_source` when one declaration or implementation is the required evidence.
+
+`snapshot_state: "fresh"` means that the returned file bytes match the synchronized compiler snapshot. It does not mean that the project has zero TypeScript diagnostics; use `ast_get_diagnostics` for compiler errors and warnings.
 
 ## Why this helps
 
@@ -39,7 +51,7 @@ Reads can start with a compact outline and fetch exact source only when needed.
 
 AST-aware editing is not a proof that a change is semantically correct. The safety comes from combining structural selection with diagnostics, exact previews, reviewed hashes, freshness checks, and fail-closed apply semantics.
 
-The included batch benchmark records a 50% reduction in model round-trips and a 94.67% reduction in serialized context for its search-to-source scenario. The result-shaping corpus records a 68.80% reduction in aggregate model-facing TOON tokens while preserving declared selectors/reference coordinates with the same six logical calls. The separate format benchmark records 25.87% across its eligible collection corpus. These are reproducible local `o200k_base` estimates, not universal token, billing, cache, or latency claims.
+The included batch benchmark records a 50% reduction in model round-trips and a 94.67% reduction in serialized context for its search-to-source scenario. The result-shaping corpus records a 68.80% reduction in aggregate model-facing TOON tokens while preserving declared selectors/reference coordinates with the same six logical calls. The separate format benchmark records 25.87% across its eligible collection corpus. The context workflow benchmark verifies evidence preservation and call bounds for full-file, primitive, and `ast_explore` workflows. These are reproducible local `o200k_base` estimates, not universal token, billing, cache, or latency claims.
 
 ## Requirements
 
@@ -217,6 +229,9 @@ Project-scoped tools accept `project_root`, either the project directory or an e
 | Tool                        | Purpose                                                              | Mutates files |
 | --------------------------- | -------------------------------------------------------------------- | ------------- |
 | `ast_list_files`            | Paginated, project-relative source file inventory                    | No            |
+| `ast_get_project_status`    | Read-only compiler, freshness, index, and operation status           | No            |
+| `ast_explore`               | Bounded composed selectors, source evidence, and references          | No            |
+| `ast_get_file`              | Bounded exact source lines, byte hash, and snapshot state            | No            |
 | `ast_get_outline`           | Body-free declaration signatures; detailed symbol metadata is opt-in | No            |
 | `ast_get_symbol_source`     | Exact source for one declaration                                     | No            |
 | `ast_search_symbols`        | Paginated structural symbol discovery                                | No            |
@@ -230,6 +245,8 @@ 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.
 
+`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. Every response reports freshness, completeness, truncation, unresolved selectors, record limits, and a serialized byte budget. Use the primitive tools when a single exact operation is clearer or when preparing a mutation.
+
 Symbol search is relevance-ranked and defaults to at most 20 `summary` records containing `file`, a directly reusable `selector`, `kind`, and body-free `signature`. Request `detail: "selectors"` for routing coordinates only, or `detail: "full", limit: 100` for the v0.4.0 fields/page. References default to `detail: "locations"`; request `detail: "context"` only when the bounded source line is needed.
 
 ### Optional TOON results
@@ -392,7 +409,7 @@ The batch benchmark compares two separate client calls with one batch invocation
 
 The format benchmark runs real tools against this repository plus deterministic reference/diagnostic fixtures. It checks JSON→TOON→value equality, UTF-8 bytes, `gpt-tokenizer` `o200k_base` estimates, encode/decode latency, the actual MCP envelope, tool metadata, and negative controls. Its checked result is `benchmark/results/self-formats.json`; local tokenizer estimates do not establish provider-side billing or cache savings. See `benchmark/README.md` for methodology and limitations.
 
-The result-shaping benchmark compares the v0.4.0-compatible `full/100/context` profiles with the new public defaults across exact-name, exact-path, prefix, broad-substring, and multi-file-reference tasks. It fails on missing evidence, extra logical calls, fewer than 11 tools, or less than 35% aggregate TOON token reduction. Its checked result is `benchmark/results/self-result-shapes.json`.
+The result-shaping benchmark compares the v0.4.0-compatible `full/100/context` profiles with the new public defaults across exact-name, exact-path, prefix, broad-substring, and multi-file-reference tasks. It fails on missing evidence, extra required calls, fewer than the benchmark's required minimum tool surface, or less than 35% aggregate TOON token reduction. Its checked result is `benchmark/results/self-result-shapes.json`.
 
 ## Scope
 

package/dist/server.js

@@ -3,6 +3,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { registerApplyOperation } from "./tools/apply_operation.js";
 import { registerFindReferences } from "./tools/find_references.js";
 import { registerGetDiagnostics } from "./tools/get_diagnostics.js";
+import { registerGetFile } from "./tools/get_file.js";
 import { registerGetOperationPreview } from "./tools/get_operation_preview.js";
 import { registerGetOutline } from "./tools/get_outline.js";
 import { registerGetProjectStatus } from "./tools/get_project_status.js";
@@ -12,6 +13,7 @@ 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";
 const packageMetadata = createRequire(import.meta.url)("../package.json");
 export const PACKAGE_VERSION = packageMetadata.version;
 export function createServer() {
@@ -21,11 +23,13 @@ export function createServer() {
     });
     registerListFiles(server);
     registerGetProjectStatus(server);
+    registerExplore(server);
     registerGetOutline(server);
     registerGetSymbolSource(server);
     registerSearchSymbols(server);
     registerFindReferences(server);
     registerGetDiagnostics(server);
+    registerGetFile(server);
     registerRenameSymbol(server);
     registerReplaceSymbolBody(server);
     registerScaffoldClass(server);

package/dist/services/context-builder.js

@@ -0,0 +1,234 @@
+import { Buffer } from "node:buffer";
+import path from "node:path";
+import { buildFileOutline, nodeSourceWithLocation } from "./outline.js";
+import { paginate } from "./pagination.js";
+import { findDeclarationByName, getSourceFileOrThrow } from "./project.js";
+import { collectSymbolReferences } from "./references.js";
+import { searchProjectSymbols, sourceFileSymbols, symbolMatchRank, } from "./symbols.js";
+export const EXPLORE_DEFAULT_LIMIT = 20;
+export const EXPLORE_DEFAULT_REFERENCE_LIMIT = 20;
+export const EXPLORE_DEFAULT_MAX_BYTES = 64 * 1024;
+export const EXPLORE_MAX_BYTES = 1024 * 1024;
+function matchesQuery(record, query) {
+    const normalizedQuery = query.toLowerCase();
+    return (record.name.toLowerCase().includes(normalizedQuery) ||
+        record.symbol_path.toLowerCase().includes(normalizedQuery) ||
+        record.selector.toLowerCase().includes(normalizedQuery));
+}
+function sortRecords(records, query) {
+    return records.sort((left, right) => {
+        if (query) {
+            const rank = symbolMatchRank(query, {
+                symbolPath: left.symbol_path,
+                name: left.name,
+                line: left.line,
+            }) -
+                symbolMatchRank(query, {
+                    symbolPath: right.symbol_path,
+                    name: right.name,
+                    line: right.line,
+                });
+            if (rank !== 0)
+                return rank;
+        }
+        return (left.file.localeCompare(right.file) ||
+            left.line - right.line ||
+            left.symbol_path.localeCompare(right.symbol_path) ||
+            left.kind.localeCompare(right.kind));
+    });
+}
+function recordFromOutlineSymbol(sourceFile, projectRoot, symbol) {
+    return {
+        file: path.relative(projectRoot, sourceFile.getFilePath()).replaceAll("\\", "/"),
+        symbol_path: symbol.symbolPath,
+        selector: `${symbol.symbolPath}@${symbol.startLine}`,
+        name: symbol.name,
+        kind: symbol.kind,
+        line: symbol.startLine,
+        signature: symbol.signature,
+    };
+}
+function fileRecords(sourceFile, projectRoot) {
+    const outline = buildFileOutline(sourceFile);
+    if (outline.symbols.length > 0) {
+        return outline.symbols.map((symbol) => recordFromOutlineSymbol(sourceFile, projectRoot, symbol));
+    }
+    return sourceFileSymbols(sourceFile, projectRoot);
+}
+function projectRecords(context, request) {
+    const { project, projectRoot } = context;
+    if (request.filePath) {
+        const sourceFile = getSourceFileOrThrow(project, request.filePath);
+        const file = path.relative(projectRoot, sourceFile.getFilePath()).replaceAll("\\", "/");
+        const requestedSymbolPath = request.symbolPath;
+        if (requestedSymbolPath) {
+            const node = findDeclarationByName(sourceFile, requestedSymbolPath);
+            const record = fileRecords(sourceFile, projectRoot).find((candidate) => candidate.symbol_path === requestedSymbolPath ||
+                candidate.selector === requestedSymbolPath ||
+                (candidate.symbol_path === requestedSymbolPath.split("@")[0] &&
+                    candidate.line === node.getStartLineNumber()));
+            if (!record) {
+                throw new Error(`Symbol "${requestedSymbolPath}" could not be projected from ${file}.`);
+            }
+            return {
+                route: "symbol",
+                file,
+                symbol: record.selector,
+                records: [record],
+            };
+        }
+        const records = fileRecords(sourceFile, projectRoot)
+            .filter((record) => !request.query || matchesQuery(record, request.query))
+            .filter((record) => !request.kinds || request.kinds.includes(record.kind));
+        return { route: "file", file, symbol: null, records: sortRecords(records, request.query) };
+    }
+    if (!request.query) {
+        throw new Error("ast_explore requires query, file_path, or both file_path and symbol_path.");
+    }
+    return {
+        route: "query",
+        file: null,
+        symbol: null,
+        records: searchProjectSymbols(project, projectRoot, {
+            query: request.query,
+            kinds: request.kinds,
+            fileFilter: request.fileFilter,
+        }),
+    };
+}
+function projectSymbol(detail, record) {
+    const base = { file: record.file, selector: record.selector, kind: record.kind };
+    if (detail === "selectors")
+        return base;
+    if (detail === "summary" || detail === "context") {
+        return { ...base, signature: record.signature };
+    }
+    return {
+        ...base,
+        symbol_path: record.symbol_path,
+        name: record.name,
+        line: record.line,
+        signature: record.signature,
+    };
+}
+function jsonBytes(value) {
+    return Buffer.byteLength(JSON.stringify(value), "utf8");
+}
+function effectiveExpansion(request) {
+    return {
+        source: request.includeSource ?? (request.detail === "context" || request.detail === "full"),
+        references: request.includeReferences ?? request.detail === "full",
+    };
+}
+export function buildExploreContext(context, request) {
+    const routed = projectRecords(context, request);
+    const page = paginate(routed.records, request.offset, request.limit);
+    const expansion = effectiveExpansion(request);
+    const unresolved = [];
+    const evidence = [];
+    for (const record of page.items) {
+        let sourceFile;
+        try {
+            sourceFile = getSourceFileOrThrow(context.project, record.file);
+        }
+        catch {
+            unresolved.push({ selector: record.selector, reason: "source_unresolved" });
+            continue;
+        }
+        let node;
+        try {
+            node = findDeclarationByName(sourceFile, record.selector);
+        }
+        catch {
+            unresolved.push({ selector: record.selector, reason: "source_unresolved" });
+            continue;
+        }
+        let source;
+        let references;
+        if (expansion.source)
+            source = nodeSourceWithLocation(node, context.projectRoot);
+        if (expansion.references) {
+            try {
+                references = collectSymbolReferences(node, context.projectRoot, record.selector, true, request.referenceDetail, 0, request.referenceLimit);
+            }
+            catch {
+                unresolved.push({ selector: record.selector, reason: "references_unresolved" });
+            }
+        }
+        if (source || references) {
+            evidence.push({
+                selector: record.selector,
+                ...(source ? { source } : {}),
+                ...(references ? { references } : {}),
+            });
+        }
+    }
+    const symbols = page.items.map((record) => projectSymbol(request.detail, record));
+    let returnedSymbols = [...symbols];
+    let returnedEvidence = [...evidence];
+    let reason = page.has_more ? "record_limit" : null;
+    let result = createResult(context, request, routed.route, routed.file, routed.symbol, returnedSymbols, returnedEvidence, page.total, unresolved, reason);
+    while (jsonBytes(result) > request.maxBytes &&
+        (returnedEvidence.length > 0 || returnedSymbols.length > 0)) {
+        reason = "byte_limit";
+        if (returnedEvidence.length > 0) {
+            returnedEvidence = returnedEvidence.slice(0, -1);
+        }
+        else {
+            returnedSymbols = returnedSymbols.slice(0, -1);
+            const selectors = new Set(returnedSymbols.map((symbol) => symbol.selector));
+            returnedEvidence = returnedEvidence.filter((item) => selectors.has(item.selector));
+        }
+        result = createResult(context, request, routed.route, routed.file, routed.symbol, returnedSymbols, returnedEvidence, page.total, unresolved, reason);
+    }
+    const usedBytes = jsonBytes(result);
+    return {
+        ...result,
+        budget: { ...result.budget, used_bytes: usedBytes },
+    };
+}
+function createResult(context, request, route, file, symbol, symbols, evidence, total, unresolved, reason) {
+    const hasMore = request.offset + symbols.length < total;
+    const nextOffset = hasMore ? request.offset + symbols.length : null;
+    const expansion = effectiveExpansion(request);
+    const evidenceComplete = unresolved.length === 0 &&
+        evidence.length >= (expansion.source || expansion.references ? symbols.length : 0);
+    const symbolsComplete = !hasMore;
+    return {
+        route,
+        query: request.query ?? null,
+        file,
+        symbol,
+        detail: request.detail,
+        symbols,
+        evidence,
+        offset: request.offset,
+        limit: request.limit,
+        total,
+        has_more: hasMore,
+        next_offset: nextOffset,
+        freshness: {
+            state: context.status.state,
+            causes: context.status.causes,
+            checked_at: context.status.lastSuccessfulSyncAt,
+        },
+        completeness: {
+            complete: symbolsComplete && evidenceComplete,
+            symbols_complete: symbolsComplete,
+            evidence_complete: evidenceComplete,
+            unresolved,
+        },
+        budget: {
+            max_records: request.limit,
+            max_bytes: request.maxBytes,
+            max_depth: null,
+            max_edges: null,
+            max_invocations: 1,
+            used_bytes: 0,
+        },
+        truncation: {
+            truncated: reason !== null || hasMore,
+            reason: reason ?? (hasMore ? "record_limit" : null),
+        },
+    };
+}

package/dist/services/file-snapshot.js

@@ -0,0 +1,96 @@
+import { TextDecoder } from "node:util";
+import { lstat, readFile, realpath } from "node:fs/promises";
+import path from "node:path";
+import { getSourceFileOrThrow } from "./project.js";
+import { hashBytes } from "./workspace.js";
+export const DEFAULT_FILE_LINE_LIMIT = 200;
+export const MAX_FILE_LINE_LIMIT = 500;
+function assertBoundedRange({ offset, limit }) {
+    if (!Number.isInteger(offset) || offset < 0) {
+        throw new Error("File offset must be a non-negative integer.");
+    }
+    if (!Number.isInteger(limit) || limit < 1 || limit > MAX_FILE_LINE_LIMIT) {
+        throw new Error(`File limit must be an integer between 1 and ${MAX_FILE_LINE_LIMIT}.`);
+    }
+}
+function rejectTraversalPath(filePath) {
+    const normalized = filePath.replaceAll("\\", "/");
+    const segments = normalized.split("/");
+    const isWindowsAbsolute = /^[A-Za-z]:\//.test(normalized) || normalized.startsWith("//");
+    if (segments.includes("..")) {
+        throw new Error("File path traversal is not allowed.");
+    }
+    if (isWindowsAbsolute && !path.isAbsolute(filePath)) {
+        throw new Error("Windows absolute paths are not valid on this host.");
+    }
+}
+function isContained(root, candidate) {
+    const relative = path.relative(root, candidate);
+    return (relative.length > 0 &&
+        relative !== ".." &&
+        !relative.startsWith(`..${path.sep}`) &&
+        !path.isAbsolute(relative));
+}
+function projectRelative(root, filePath) {
+    return path.relative(root, filePath).split(path.sep).join("/");
+}
+function decodeUtf8(bytes, filePath) {
+    try {
+        return new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
+    }
+    catch {
+        throw new Error(`Source file "${filePath}" is not valid UTF-8.`);
+    }
+}
+function splitLines(source) {
+    if (source.length === 0)
+        return [];
+    const lines = source.split(/\r\n|\n|\r/);
+    if (source.endsWith("\n") || source.endsWith("\r"))
+        lines.pop();
+    return lines;
+}
+function compilerSnapshotHashes(sourceText) {
+    const sourceBytes = Buffer.from(sourceText, "utf8");
+    const hashes = [hashBytes(sourceBytes)];
+    if (sourceText.charCodeAt(0) !== 0xfeff) {
+        hashes.push(hashBytes(Buffer.concat([Buffer.from([0xef, 0xbb, 0xbf]), sourceBytes])));
+    }
+    return hashes;
+}
+export async function readFileSnapshot(project, projectRoot, filePath, options) {
+    assertBoundedRange(options);
+    rejectTraversalPath(filePath);
+    const sourceFile = getSourceFileOrThrow(project, filePath);
+    const canonicalRoot = await realpath(projectRoot);
+    const sourcePath = sourceFile.getFilePath();
+    const canonicalFile = await realpath(sourcePath);
+    if (!isContained(canonicalRoot, canonicalFile)) {
+        throw new Error("Source file resolves outside the configured project root.");
+    }
+    const stat = await lstat(canonicalFile);
+    if (!stat.isFile()) {
+        throw new Error("Source file is not a regular file.");
+    }
+    const bytes = await readFile(canonicalFile);
+    const source = decodeUtf8(bytes, projectRelative(canonicalRoot, canonicalFile));
+    const fileHash = hashBytes(bytes);
+    const compilerHashes = compilerSnapshotHashes(sourceFile.getFullText());
+    const snapshotState = compilerHashes.includes(fileHash) ? "fresh" : "stale";
+    const allLines = splitLines(source);
+    const selectedLines = allLines.slice(options.offset, options.offset + options.limit);
+    return {
+        file: projectRelative(canonicalRoot, canonicalFile),
+        range: {
+            offset: options.offset,
+            limit: options.limit,
+            total_lines: allLines.length,
+        },
+        lines: selectedLines.map((text, index) => ({
+            line: options.offset + index + 1,
+            text,
+        })),
+        file_hash: fileHash,
+        snapshot_state: snapshotState,
+    };
+}

package/dist/services/references.js

@@ -0,0 +1,48 @@
+import path from "node:path";
+import { Node } from "ts-morph";
+import { paginate } from "./pagination.js";
+export function collectSymbolReferences(node, projectRoot, symbolPath, includeDeclaration, detail, offset, limit) {
+    if (!Node.isReferenceFindable(node)) {
+        throw new Error(`Symbol "${symbolPath}" (${node.getKindName()}) does not support semantic reference search.`);
+    }
+    const lineCache = new Map();
+    const location = (referenceNode, isDeclaration) => {
+        const referenceSource = referenceNode.getSourceFile();
+        const absoluteFile = referenceSource.getFilePath();
+        let lines = lineCache.get(absoluteFile);
+        if (!lines) {
+            lines = referenceSource.getFullText().split(/\r?\n/);
+            lineCache.set(absoluteFile, lines);
+        }
+        const position = referenceSource.getLineAndColumnAtPos(referenceNode.getStart());
+        return {
+            file: path.relative(projectRoot, absoluteFile),
+            line: position.line,
+            column: position.column,
+            kind: referenceNode.getParent()?.getKindName() ?? referenceNode.getKindName(),
+            is_declaration: isDeclaration,
+            ...(detail === "context"
+                ? { context: (lines[position.line - 1] ?? "").trim().slice(0, 500) }
+                : {}),
+        };
+    };
+    const references = node.findReferencesAsNodes().map((reference) => location(reference, false));
+    const declaration = location(node, true);
+    const allLocations = includeDeclaration ? [declaration, ...references] : references;
+    allLocations.sort((left, right) => `${left.file}:${left.line}:${left.column}:${left.is_declaration ? 0 : 1}`.localeCompare(`${right.file}:${right.line}:${right.column}:${right.is_declaration ? 0 : 1}`));
+    const affectedFiles = [...new Set([declaration, ...references].map((item) => item.file))].sort();
+    const page = paginate(allLocations, offset, limit);
+    return {
+        symbol: symbolPath,
+        include_declaration: includeDeclaration,
+        declaration_count: 1,
+        reference_count: references.length,
+        affected_files: affectedFiles,
+        references: page.items,
+        offset: page.offset,
+        limit: page.limit,
+        total: page.total,
+        has_more: page.has_more,
+        next_offset: page.next_offset,
+    };
+}

package/dist/services/symbols.js

@@ -1,4 +1,22 @@
+import path from "node:path";
 import { Node, } from "ts-morph";
+import { buildFileOutline } from "./outline.js";
+export function sourceFileSymbols(sourceFile, projectRoot) {
+    const file = path.relative(projectRoot, sourceFile.getFilePath());
+    const signatures = new Map(buildFileOutline(sourceFile).symbols.map((symbol) => [
+        `${symbol.symbolPath}@${symbol.startLine}`,
+        symbol.signature,
+    ]));
+    return collectSymbols(sourceFile).map((symbol) => ({
+        file,
+        symbol_path: symbol.symbolPath,
+        selector: `${symbol.symbolPath}@${symbol.line}`,
+        name: symbol.name,
+        kind: symbol.kind,
+        line: symbol.line,
+        signature: signatures.get(`${symbol.symbolPath}@${symbol.line}`) ?? symbol.node.getText(),
+    }));
+}
 export function symbolMatchRank(query, symbol) {
     const normalizedQuery = query.toLowerCase();
     const normalizedPath = symbol.symbolPath.toLowerCase();
@@ -15,6 +33,47 @@ export function symbolMatchRank(query, symbol) {
     }
     return 4;
 }
+export function searchProjectSymbols(project, projectRoot, options) {
+    const normalizedQuery = options.query.toLowerCase();
+    const normalizedFileFilter = options.fileFilter?.toLowerCase();
+    const kindSet = options.kinds ? new Set(options.kinds) : undefined;
+    const matches = [];
+    for (const sourceFile of project.getSourceFiles()) {
+        const file = path.relative(projectRoot, sourceFile.getFilePath());
+        if (normalizedFileFilter && !file.toLowerCase().includes(normalizedFileFilter))
+            continue;
+        const matchingSymbols = sourceFileSymbols(sourceFile, projectRoot).filter((symbol) => {
+            return ((!kindSet || kindSet.has(symbol.kind)) &&
+                (symbol.name.toLowerCase().includes(normalizedQuery) ||
+                    symbol.symbol_path.toLowerCase().includes(normalizedQuery) ||
+                    symbol.selector.toLowerCase().includes(normalizedQuery)));
+        });
+        if (matchingSymbols.length === 0)
+            continue;
+        for (const symbol of matchingSymbols) {
+            matches.push(symbol);
+        }
+    }
+    matches.sort((left, right) => {
+        const rank = symbolMatchRank(options.query, {
+            symbolPath: left.symbol_path,
+            name: left.name,
+            line: left.line,
+        }) -
+            symbolMatchRank(options.query, {
+                symbolPath: right.symbol_path,
+                name: right.name,
+                line: right.line,
+            });
+        if (rank !== 0)
+            return rank;
+        return (left.file.localeCompare(right.file) ||
+            left.line - right.line ||
+            left.symbol_path.localeCompare(right.symbol_path) ||
+            left.kind.localeCompare(right.kind));
+    });
+    return matches;
+}
 function namedNode(node) {
     if (Node.isConstructorDeclaration(node))
         return "constructor";

package/dist/tools/explore.js

@@ -0,0 +1,174 @@
+import { z } from "zod";
+import { buildExploreContext, EXPLORE_DEFAULT_LIMIT, EXPLORE_DEFAULT_MAX_BYTES, EXPLORE_DEFAULT_REFERENCE_LIMIT, EXPLORE_MAX_BYTES, } from "../services/context-builder.js";
+import { createPaginationInputSchema } from "../services/pagination.js";
+import { withProject } from "../services/project.js";
+import { FRESHNESS_CAUSES, SNAPSHOT_STATES, TRUNCATION_REASONS, } from "../services/read-contracts.js";
+import { errorResult, structuredResult } from "./result.js";
+const ExploreDetailSchema = z.enum(["selectors", "summary", "context", "full"]).default("summary");
+const ReferenceDetailSchema = z.enum(["locations", "context"]).default("locations");
+const ExploreInputSchema = z
+    .object({
+    project_root: z
+        .string()
+        .describe("Absolute project directory containing tsconfig.json, or the config path."),
+    query: z.string().min(1).optional().describe("Bounded case-insensitive symbol query."),
+    file_path: z.string().optional().describe("Known project-relative or unambiguous source file."),
+    symbol_path: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Exact symbol path or selector, valid only with file_path."),
+    kinds: z.array(z.string()).max(32).optional().describe("Optional exact syntax-kind filters."),
+    file_filter: z.string().optional().describe("Optional query-route file path substring filter."),
+    detail: ExploreDetailSchema.describe("selectors returns routing coordinates; summary adds signatures; context adds source; full adds source and references."),
+    include_source: z
+        .boolean()
+        .optional()
+        .describe("Override detail-based source expansion for selected symbols."),
+    include_references: z
+        .boolean()
+        .optional()
+        .describe("Override detail-based compiler reference expansion for selected symbols."),
+    reference_detail: ReferenceDetailSchema.describe("Reference locations or bounded source-line context."),
+    reference_limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(100)
+        .default(EXPLORE_DEFAULT_REFERENCE_LIMIT)
+        .describe("Maximum compiler references per selected symbol."),
+    ...createPaginationInputSchema(EXPLORE_DEFAULT_LIMIT),
+    max_bytes: z
+        .number()
+        .int()
+        .min(1024)
+        .max(EXPLORE_MAX_BYTES)
+        .default(EXPLORE_DEFAULT_MAX_BYTES)
+        .describe("Maximum serialized logical result size in UTF-8 bytes."),
+})
+    .refine((input) => Boolean(input.query || input.file_path), {
+    message: "Provide query, file_path, or both file_path and symbol_path.",
+    path: ["query"],
+})
+    .refine((input) => !input.symbol_path || Boolean(input.file_path), {
+    message: "symbol_path requires file_path so the exact declaration can be resolved.",
+    path: ["symbol_path"],
+});
+const ExploreSymbolSchema = z.object({
+    file: z.string(),
+    selector: z.string(),
+    kind: z.string(),
+    symbol_path: z.string().optional(),
+    name: z.string().optional(),
+    line: z.number().int().positive().optional(),
+    signature: z.string().optional(),
+});
+const ExploreSourceSchema = z.object({
+    file: z.string(),
+    startLine: z.number().int().positive(),
+    endLine: z.number().int().positive(),
+    text: z.string(),
+});
+const ExploreReferenceSchema = z.object({
+    file: z.string(),
+    line: z.number().int().positive(),
+    column: z.number().int().positive(),
+    kind: z.string(),
+    is_declaration: z.boolean(),
+    context: z.string().optional(),
+});
+const ExploreEvidenceSchema = z.object({
+    selector: z.string(),
+    source: ExploreSourceSchema.optional(),
+    references: z
+        .object({
+        symbol: z.string(),
+        include_declaration: z.boolean(),
+        declaration_count: z.number().int().min(0),
+        reference_count: z.number().int().min(0),
+        affected_files: z.array(z.string()),
+        references: z.array(ExploreReferenceSchema),
+        offset: z.number().int().min(0),
+        limit: z.number().int().positive(),
+        total: z.number().int().min(0),
+        has_more: z.boolean(),
+        next_offset: z.number().int().min(0).nullable(),
+    })
+        .optional(),
+});
+const ExploreOutputSchema = z.object({
+    route: z.enum(["query", "file", "symbol"]),
+    query: z.string().nullable(),
+    file: z.string().nullable(),
+    symbol: z.string().nullable(),
+    detail: ExploreDetailSchema,
+    symbols: z.array(ExploreSymbolSchema),
+    evidence: z.array(ExploreEvidenceSchema),
+    offset: z.number().int().min(0),
+    limit: z.number().int().positive(),
+    total: z.number().int().min(0),
+    has_more: z.boolean(),
+    next_offset: z.number().int().min(0).nullable(),
+    freshness: z.object({
+        state: z.enum(SNAPSHOT_STATES),
+        causes: z.array(z.enum(FRESHNESS_CAUSES)),
+        checked_at: z.string().nullable(),
+    }),
+    completeness: z.object({
+        complete: z.boolean(),
+        symbols_complete: z.boolean(),
+        evidence_complete: z.boolean(),
+        unresolved: z.array(z.object({
+            selector: z.string(),
+            reason: z.enum(["source_unresolved", "references_unresolved"]),
+        })),
+    }),
+    budget: z.object({
+        max_records: z.number().int().positive(),
+        max_bytes: z.number().int().positive(),
+        max_depth: z.null(),
+        max_edges: z.null(),
+        max_invocations: z.number().int().positive(),
+        used_bytes: z.number().int().nonnegative(),
+    }),
+    truncation: z.object({
+        truncated: z.boolean(),
+        reason: z.enum(TRUNCATION_REASONS).nullable(),
+    }),
+});
+export function registerExplore(server) {
+    server.registerTool("ast_explore", {
+        title: "Explore project context",
+        description: "Composes bounded structural search, exact selectors, source evidence and compiler references without weakening the primitive AST tools.",
+        inputSchema: ExploreInputSchema,
+        outputSchema: ExploreOutputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async ({ project_root, query, file_path, symbol_path, kinds, file_filter, detail, include_source, include_references, reference_detail, reference_limit, offset, limit, max_bytes, }) => {
+        try {
+            const output = await withProject(project_root, (context) => buildExploreContext(context, {
+                query,
+                filePath: file_path,
+                symbolPath: symbol_path,
+                kinds,
+                fileFilter: file_filter,
+                detail,
+                includeSource: include_source,
+                includeReferences: include_references,
+                referenceDetail: reference_detail,
+                offset,
+                limit,
+                referenceLimit: reference_limit,
+                maxBytes: max_bytes,
+            }));
+            return structuredResult(ExploreOutputSchema.parse(output));
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+}

package/dist/tools/find_references.js

@@ -1,8 +1,7 @@
-import path from "node:path";
-import { Node } from "ts-morph";
 import { z } from "zod";
-import { PaginationInputSchema, PaginationOutputSchema, paginate } from "../services/pagination.js";
+import { PaginationInputSchema, PaginationOutputSchema } from "../services/pagination.js";
 import { findDeclarationByName, getSourceFileOrThrow, withProject } from "../services/project.js";
+import { collectSymbolReferences } from "../services/references.js";
 import { errorResult, formattedResult, ToolOutputFormatInputSchema } from "./result.js";
 const ReferenceDetailSchema = z.enum(["locations", "context"]).default("locations");
 const AstFindReferencesInputSchema = z.object({
@@ -59,55 +58,19 @@ export function registerFindReferences(server) {
             const structuredContent = await withProject(project_root, ({ project, projectRoot }) => {
                 const sourceFile = getSourceFileOrThrow(project, file_path);
                 const node = findDeclarationByName(sourceFile, symbol_path);
-                if (!Node.isReferenceFindable(node)) {
-                    throw new Error(`Symbol "${symbol_path}" (${node.getKindName()}) does not support semantic reference search.`);
-                }
-                const lineCache = new Map();
-                const location = (referenceNode, isDeclaration) => {
-                    const referenceSource = referenceNode.getSourceFile();
-                    const absoluteFile = referenceSource.getFilePath();
-                    let lines = lineCache.get(absoluteFile);
-                    if (!lines) {
-                        lines = referenceSource.getFullText().split(/\r?\n/);
-                        lineCache.set(absoluteFile, lines);
-                    }
-                    const position = referenceSource.getLineAndColumnAtPos(referenceNode.getStart());
-                    return {
-                        file: path.relative(projectRoot, absoluteFile),
-                        line: position.line,
-                        column: position.column,
-                        kind: referenceNode.getParent()?.getKindName() ?? referenceNode.getKindName(),
-                        is_declaration: isDeclaration,
-                        context: (lines[position.line - 1] ?? "").trim().slice(0, 500),
-                    };
-                };
-                const references = node
-                    .findReferencesAsNodes()
-                    .map((reference) => location(reference, false));
-                const declaration = location(node, true);
-                const allLocations = include_declaration ? [declaration, ...references] : references;
-                allLocations.sort((left, right) => `${left.file}:${left.line}:${left.column}:${left.is_declaration ? 0 : 1}`.localeCompare(`${right.file}:${right.line}:${right.column}:${right.is_declaration ? 0 : 1}`));
-                const affectedFiles = [
-                    ...new Set([declaration, ...references].map((item) => item.file)),
-                ].sort();
-                const page = paginate(allLocations, offset, limit);
-                const { items, ...metadata } = page;
+                const collected = collectSymbolReferences(node, projectRoot, symbol_path, include_declaration, detail, offset, limit);
+                const { references, ...metadata } = collected;
                 return {
-                    symbol: symbol_path,
-                    include_declaration,
-                    declaration_count: 1,
-                    reference_count: references.length,
-                    affected_files: affectedFiles,
+                    ...metadata,
                     references: detail === "context"
-                        ? items
-                        : items.map(({ file, line, column, kind, is_declaration }) => ({
+                        ? references
+                        : references.map(({ file, line, column, kind, is_declaration }) => ({
                             file,
                             line,
                             column,
                             kind,
                             is_declaration,
                         })),
-                    ...metadata,
                 };
             });
             const outputSchema = ReferenceOutputSchemas[detail];

package/dist/tools/get_file.js

@@ -0,0 +1,95 @@
+import { z } from "zod";
+import { DEFAULT_FILE_LINE_LIMIT, MAX_FILE_LINE_LIMIT, readFileSnapshot, } from "../services/file-snapshot.js";
+import { buildFileOutline } from "../services/outline.js";
+import { getSourceFileOrThrow, withProject } from "../services/project.js";
+import { errorResult, structuredResult } from "./result.js";
+const AstGetFileInputSchema = z.object({
+    project_root: z
+        .string()
+        .describe("Absolute project directory containing tsconfig.json, or the config path."),
+    file_path: z
+        .string()
+        .describe("Project-relative or unambiguous source file path included by the active tsconfig."),
+    offset: z.number().int().min(0).default(0).describe("Zero-based line offset for source mode."),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(MAX_FILE_LINE_LIMIT)
+        .default(DEFAULT_FILE_LINE_LIMIT)
+        .describe(`Maximum source lines to return, capped at ${MAX_FILE_LINE_LIMIT}.`),
+    symbols_only: z
+        .boolean()
+        .default(false)
+        .describe("Return body-free symbol selectors and signatures instead of source lines."),
+});
+const FileRangeSchema = z.object({
+    offset: z.number().int().min(0),
+    limit: z.number().int().min(1).max(MAX_FILE_LINE_LIMIT),
+    total_lines: z.number().int().min(0),
+});
+const FileLineSchema = z.object({
+    line: z.number().int().positive(),
+    text: z.string(),
+});
+const OutlineSymbolSchema = z.object({
+    symbolPath: z.string(),
+    name: z.string(),
+    kind: z.string(),
+    signature: z.string(),
+    startLine: z.number().int().positive(),
+    endLine: z.number().int().positive(),
+});
+const FileSnapshotBaseSchema = {
+    file: z.string(),
+    file_hash: z.string().regex(/^[0-9a-f]{64}$/),
+    snapshot_state: z.enum(["fresh", "stale"]),
+};
+const AstGetFileOutputSchema = z.object({
+    mode: z.enum(["source", "symbols_only"]),
+    ...FileSnapshotBaseSchema,
+    range: FileRangeSchema.optional(),
+    lines: z.array(FileLineSchema).optional(),
+    symbols: z.array(OutlineSymbolSchema).optional(),
+});
+export function registerGetFile(server) {
+    server.registerTool("ast_get_file", {
+        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; freshness is reported separately from compiler diagnostics.",
+        inputSchema: AstGetFileInputSchema,
+        outputSchema: AstGetFileOutputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async ({ project_root, file_path, offset, limit, symbols_only }) => {
+        try {
+            const structuredContent = await withProject(project_root, async ({ project, projectRoot }) => {
+                const snapshot = await readFileSnapshot(project, projectRoot, file_path, {
+                    offset,
+                    limit,
+                });
+                if (!symbols_only) {
+                    return {
+                        mode: "source",
+                        ...snapshot,
+                    };
+                }
+                const sourceFile = getSourceFileOrThrow(project, file_path);
+                return {
+                    mode: "symbols_only",
+                    file: snapshot.file,
+                    file_hash: snapshot.file_hash,
+                    snapshot_state: snapshot.snapshot_state,
+                    symbols: buildFileOutline(sourceFile).symbols,
+                };
+            });
+            return structuredResult(structuredContent);
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+}

package/dist/tools/search_symbols.js

@@ -1,9 +1,7 @@
-import path from "node:path";
 import { z } from "zod";
-import { buildFileOutline } from "../services/outline.js";
 import { createPaginationInputSchema, PaginationOutputSchema, paginate, } from "../services/pagination.js";
 import { withProject } from "../services/project.js";
-import { collectSymbols, symbolMatchRank } from "../services/symbols.js";
+import { searchProjectSymbols } from "../services/symbols.js";
 import { errorResult, formattedResult, ToolOutputFormatInputSchema } from "./result.js";
 const SEARCH_DEFAULT_LIMIT = 20;
 const SearchDetailSchema = z.enum(["selectors", "summary", "full"]).default("summary");
@@ -92,57 +90,10 @@ export function registerSearchSymbols(server) {
         try {
             const structuredContent = await withProject(project_root, ({ project, projectRoot }) => {
                 const startedAt = performance.now();
-                const normalizedQuery = query.toLowerCase();
-                const normalizedFileFilter = file_filter?.toLowerCase();
-                const kindSet = kinds ? new Set(kinds) : undefined;
-                const matches = [];
-                for (const sourceFile of project.getSourceFiles()) {
-                    const file = path.relative(projectRoot, sourceFile.getFilePath());
-                    if (normalizedFileFilter && !file.toLowerCase().includes(normalizedFileFilter)) {
-                        continue;
-                    }
-                    const matchingSymbols = collectSymbols(sourceFile).filter((symbol) => {
-                        const selector = `${symbol.symbolPath}@${symbol.line}`.toLowerCase();
-                        return ((!kindSet || kindSet.has(symbol.kind)) &&
-                            (symbol.name.toLowerCase().includes(normalizedQuery) ||
-                                symbol.symbolPath.toLowerCase().includes(normalizedQuery) ||
-                                selector.includes(normalizedQuery)));
-                    });
-                    if (matchingSymbols.length === 0)
-                        continue;
-                    const signatures = new Map(buildFileOutline(sourceFile).symbols.map((symbol) => [
-                        `${symbol.symbolPath}@${symbol.startLine}`,
-                        symbol.signature,
-                    ]));
-                    for (const symbol of matchingSymbols) {
-                        matches.push({
-                            file,
-                            symbol_path: symbol.symbolPath,
-                            selector: `${symbol.symbolPath}@${symbol.line}`,
-                            name: symbol.name,
-                            kind: symbol.kind,
-                            line: symbol.line,
-                            signature: signatures.get(`${symbol.symbolPath}@${symbol.line}`) ?? symbol.node.getText(),
-                        });
-                    }
-                }
-                matches.sort((left, right) => {
-                    const rank = symbolMatchRank(query, {
-                        symbolPath: left.symbol_path,
-                        name: left.name,
-                        line: left.line,
-                    }) -
-                        symbolMatchRank(query, {
-                            symbolPath: right.symbol_path,
-                            name: right.name,
-                            line: right.line,
-                        });
-                    if (rank !== 0)
-                        return rank;
-                    return (left.file.localeCompare(right.file) ||
-                        left.line - right.line ||
-                        left.symbol_path.localeCompare(right.symbol_path) ||
-                        left.kind.localeCompare(right.kind));
+                const matches = searchProjectSymbols(project, projectRoot, {
+                    query,
+                    kinds,
+                    fileFilter: file_filter,
                 });
                 const page = paginate(matches, offset, limit);
                 const { items, ...metadata } = page;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ast-mcp-server",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "Structural code MCP server and batch CLI for compact TypeScript/JavaScript reads and hash-bound AST edits.",
   "keywords": [
     "mcp",
@@ -56,6 +56,7 @@
     "benchmark:batch": "yarn build && node scripts/benchmark-batch.mjs",
     "benchmark:formats": "yarn build && node scripts/benchmark-formats.mjs",
     "benchmark:shapes": "yarn build && node scripts/benchmark-result-shapes.mjs",
+    "benchmark:agent-workflows": "yarn build && node scripts/benchmark-agent-workflows.mjs",
     "lint": "eslint src test scripts vitest.config.ts eslint.config.js",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
@@ -82,4 +83,4 @@
     "typescript-eslint": "^8.65.0",
     "vitest": "^4.1.10"
   }
-}
+}

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

@@ -17,6 +17,7 @@ metadata:
 Usar las tools del servidor MCP `ast` en proyectos TypeScript/JavaScript con `tsconfig.json` cuando haya que:
 
 - orientarse en archivos o módulos grandes/desconocidos;
+- leer rangos acotados del source exacto de un archivo conocido;
 - encontrar declaraciones o referencias reales;
 - medir el radio de impacto de un rename;
 - renombrar un símbolo en varios archivos;
@@ -40,16 +41,22 @@ El setup falla cerrado ante un registro `ast` conflictivo. No eliminar ni reempl
 ## Flujo compacto de lectura
 
 1. `ast_list_files` para descubrir archivos. Paginar; no pedir todo un monorepo si alcanza con un filtro.
-2. `ast_search_symbols` si todavía no se conoce el archivo o el selector exacto.
-3. `ast_get_outline` para ver contratos sin cuerpos. No pedir `include_symbols` salvo que haga falta la metadata detallada.
-4. `ast_get_symbol_source` solo para las declaraciones cuya implementación haya que inspeccionar.
-5. `ast_find_references` antes de renames o cambios con impacto cross-file.
-6. `ast_get_diagnostics` para establecer y verificar el estado del proyecto.
+2. `ast_explore` para una pregunta de lectura que combine descubrimiento y evidencia. Usar `summary` por defecto, `context` para source seleccionado y `full` para source más referencias.
+3. `ast_get_file` si ya se conoce el archivo y hace falta source exacto. Usar `offset`/`limit`; no cargar el archivo completo por defecto.
+4. `ast_search_symbols` si todavía no se conoce el archivo o el selector exacto.
+5. `ast_get_outline` para ver contratos sin cuerpos. No pedir `include_symbols` salvo que haga falta la metadata detallada.
+6. `ast_get_symbol_source` solo para las declaraciones cuya implementación haya que inspeccionar.
+7. `ast_find_references` antes de renames o cambios con impacto cross-file.
+8. `ast_get_diagnostics` para establecer y verificar el estado del proyecto.
 
 `ast_search_symbols` devuelve por default hasta 20 records `summary` rankeados. Su campo `selector` es el valor que se pasa como `symbol_path` a la siguiente tool; pedir `detail: "selectors"` para routing puro o `detail: "full", limit: 100` para el perfil v0.4.0. `ast_find_references` devuelve `detail: "locations"` por default; expandir a `detail: "context"` únicamente cuando la línea fuente aporte evidencia necesaria.
 
 `file_path` debe ser preferentemente relativo al proyecto. Si un suffix coincide con varios archivos, la tool falla y devuelve candidatos en vez de elegir uno silenciosamente.
 
+`ast_get_file` es read-only y solo acepta archivos incluidos por el tsconfig activo. Su modo normal devuelve líneas exactas, paginadas y numeradas desde 1, junto con el hash SHA-256 de los bytes actuales. `symbols_only: true` devuelve selectors y signatures sin cuerpos. `snapshot_state: "fresh"` describe sincronización con el snapshot del compilador, no ausencia de diagnostics; consultar `ast_get_diagnostics` por separado.
+
+`ast_explore` es read-only y no prepara ni aplica operaciones. Sus selectors son directamente reutilizables por las tools primitivas y de mutación. La respuesta declara `freshness`, `completeness`, `truncation`, `unresolved` y `budget`; si el límite de bytes impide incluir todo el contexto, el resultado queda marcado como incompleto.
+
 Los clientes pueden prefijar los nombres publicados (`ast_*`) según su convención MCP; elegir por el nombre base y el schema, no adivinar el prefijo.
 
 ## Formato de resultado para el modelo

package/benchmark/README.md

@@ -1,129 +0,0 @@
-# Benchmark methodology
-
-The benchmark suite measures structural payload reduction, batch orchestration, and model-facing result formats. The first two benchmarks deliberately avoid converting characters into tokens. The format benchmark pins and names one tokenizer so its estimates are reproducible rather than universal.
-
-## Project payload and latency
-
-`scripts/benchmark.mjs`:
-
-1. Loads a real TypeScript project from disk.
-2. Selects the lexicographically first non-declaration source files after an optional filter.
-3. Serializes the default compact outline payload (`file` plus `outline`).
-4. Also records the larger opt-in payload containing detailed symbol metadata.
-5. Reports fresh project load, cold cached-session, warm cached-session, and per-file outline latency.
-
-Run:
-
-```bash
-yarn benchmark /absolute/project/path --sample 20 --output benchmark/results/project.json
-```
-
-The selection rule is deterministic but not statistically representative of every repository. Use `--filter` and multiple samples when comparing particular modules.
-
-## Compact-first task corpus
-
-`task-corpus.json` defines twelve questions over this repository. Each task declares:
-
-- files a full-file workflow would load;
-- declarations a compact-first workflow would request after inspecting outlines;
-- evidence strings necessary to answer that task.
-
-`scripts/benchmark-corpus.mjs` compares:
-
-- baseline: complete text of every declared file;
-- compact: default outline payloads plus only the selected declaration sources.
-
-It fails unless every predefined evidence string is present in the compact payload. This makes the check reproducible, but it does not prove that every possible reviewer would reach an equivalent conclusion.
-
-Run:
-
-```bash
-yarn benchmark:corpus benchmark/task-corpus.json --output benchmark/results/self-corpus.json
-```
-
-## Interpreting results
-
-- Character reduction measures serialized payload size, not billed model tokens.
-- Negative reduction on a tiny file is valid: protocol structure can cost more than reading that file directly.
-- Project-load latency and warm-session latency should be considered separately.
-- Detailed symbol metadata is opt-in because it repeats signature text and can dominate small files.
-- Benchmark scripts record absolute local paths and timestamps. Checked reports replace local paths with descriptive placeholders; regenerate them when comparing another machine or revision.
-
-## Batch orchestration
-
-`scripts/benchmark-batch.mjs` compares a two-operation search-to-source workflow in fresh Node processes:
-
-- separate: the client receives the broad symbol-search payload, selects the first match, then requests its source;
-- batch: `ast-tool` performs the same two MCP tool invocations in process and emits only the final source result.
-
-Run:
-
-```bash
-yarn benchmark:batch --iterations 5 --output benchmark/results/self-batch.json
-```
-
-The report records logical model round-trips, actual tool invocations, median wall time, process maximum RSS, final-result characters, and total characters exposed to the model. It does not include model inference latency, so the practical wall-time benefit of removing a model round-trip will be larger than this local process-only comparison. Maximum RSS includes the Node runtime and TypeScript project in each fresh worker.
-
-## Model-facing JSON and TOON
-
-`scripts/benchmark-formats.mjs` compares compact JSON with TOON for actual MCP logical results. It uses this repository for broad symbol search and deterministic temporary TypeScript fixtures for repeated references and non-empty diagnostics. File lists, outlines, exact source, and a prepared rename are retained as negative controls.
-
-For each payload it records:
-
-- exact JSON→TOON→value round-trip equality;
-- UTF-8 bytes;
-- `gpt-tokenizer@3.4.0` `o200k_base` token estimates;
-- plain TOON for CLI output and the real MCP `{format,data}` envelope;
-- median encode/decode time over 50 local iterations;
-- serialized `tools/list` metadata against the checked v0.3.0 baseline.
-
-Run:
-
-```bash
-yarn benchmark:formats
-```
-
-The script fails unless every round trip is exact, the broad-search MCP envelope reduces estimated tokens by at least 20%, and the aggregate eligible corpus reduces them by at least 15%. Tokenizer estimates are not provider usage records and do not establish billed-token or prompt-cache savings.
-
-## Checked results
-
-Results generated on 2026-08-03 with Node.js v24.16.0:
-
-| Workload        |   Sample | Full source chars | Compact chars | Reduction | Fresh load | Warm session |
-| --------------- | -------: | ----------------: | ------------: | --------: | ---------: | -----------: |
-| This repository | 20 files |            77,982 |        12,512 |    83.96% |     543 ms |      1.86 ms |
-| `x-scraper`     | 20 files |           178,110 |        17,036 |    90.44% |   3,951 ms |    180.16 ms |
-| Task corpus     | 12 tasks |            83,289 |        28,372 |    65.94% |        n/a |          n/a |
-
-The task corpus passed all 12 predefined evidence checks. Its compact count includes the selected declaration bodies, not just outlines. Exact raw reports are under `benchmark/results/`.
-
-The checked broad search-to-source batch result used five fresh-process samples:
-
-| Mode     | Model round-trips | Tool invocations | Context chars | Median wall time | Median max RSS |
-| -------- | ----------------: | ---------------: | ------------: | ---------------: | -------------: |
-| Separate |                 2 |                2 |         7,818 |        587.03 ms |      380.68 MB |
-| Batch    |                 1 |                2 |           417 |        607.95 ms |      379.15 MB |
-
-That run reduced model round-trips by 50% and serialized context by 94.67%. Local execution latency increased by 3.56% and RSS decreased by 0.40%, both small enough to treat as noise rather than a performance claim. The batch value is orchestration/context reduction; it does not make TypeScript analysis free.
-
-The checked model-facing format corpus used the complete MCP envelope for TOON:
-
-| Payload             | Records | JSON tokens | MCP TOON tokens | Reduction |
-| ------------------- | ------: | ----------: | --------------: | --------: |
-| Broad symbol search |     100 |       5,382 |           4,061 |    24.54% |
-| References          |      71 |       3,094 |           2,159 |    30.22% |
-| Diagnostics         |      30 |       1,309 |           1,034 |    21.01% |
-| Eligible aggregate  |     201 |       9,785 |           7,254 |    25.87% |
-
-All seven positive and negative payloads round-tripped exactly. File list, outline, source, and prepare envelopes were 5.13% to 13.56% worse in estimated tokens, which is why they remain JSON-only. The complete eleven-tool metadata is 3,372 serialized characters larger than the retained v0.3.0 baseline; this static protocol cost is reported separately from dynamic result savings.
-
-The checked result-shaping corpus compares the v0.4.0-compatible `full/100/context` profiles with the new public defaults across exact-name, exact-path, prefix, broad-substring, and multi-file-reference workflows:
-
-| Profile   | Logical calls | MCP TOON tokens |
-| --------- | ------------: | --------------: |
-| Baseline  |             6 |           3,910 |
-| Candidate |             6 |           1,220 |
-
-Every declared selector and reference coordinate remained present, and the aggregate reduction was 68.80%, above the checked 35% gate. `duration_ms` is omitted from both measured representations to make token counts deterministic; real JSON/TOON outputs are still decode-compared before measurement. These are local `o200k_base` estimates, not provider billing, cache, or latency evidence.
-
-The complete v0.5.0 `tools/list` metadata is 22,473 serialized characters versus the retained v0.4.0 value of 16,650 (`+5,823`). Removing only `ast_scaffold_class` from the current list reduces it by 5,411 characters and 1,295 local `o200k_base` tokens. No v0.4.0 metadata token count was retained, so the report intentionally leaves the historical token delta unset.