ast-mcp-server 0.5.1 → 0.7.0

package/dist/tools/get_file.js

@@ -0,0 +1,107 @@
+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 { createRequestContext } from "../services/request-context.js";
+import { FRESHNESS_CAUSES, SNAPSHOT_STATES } from "../services/read-contracts.js";
+import { createToolErrorContext, 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"]),
+    freshness: z.object({
+        state: z.enum(SNAPSHOT_STATES),
+        causes: z.array(z.enum(FRESHNESS_CAUSES)),
+        checked_at: z.string().nullable(),
+    }),
+};
+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; file snapshot freshness and project freshness are 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 }, extra) => {
+        const requestContext = createRequestContext(extra.signal);
+        try {
+            const structuredContent = await withProject(project_root, async ({ project, projectRoot, status }, operationContext) => {
+                const snapshot = await readFileSnapshot(project, projectRoot, file_path, { offset, limit }, operationContext);
+                const freshness = {
+                    state: status.state,
+                    causes: status.causes,
+                    checked_at: status.lastSuccessfulSyncAt,
+                };
+                if (!symbols_only) {
+                    return {
+                        mode: "source",
+                        ...snapshot,
+                        freshness,
+                    };
+                }
+                const sourceFile = getSourceFileOrThrow(project, file_path);
+                return {
+                    mode: "symbols_only",
+                    file: snapshot.file,
+                    file_hash: snapshot.file_hash,
+                    snapshot_state: snapshot.snapshot_state,
+                    freshness,
+                    symbols: buildFileOutline(sourceFile, operationContext).symbols,
+                };
+            }, requestContext);
+            return structuredResult(structuredContent);
+        }
+        catch (error) {
+            return errorResult(error, createToolErrorContext("ast_get_file", project_root));
+        }
+    });
+}

package/dist/tools/get_impact.js

@@ -0,0 +1,134 @@
+import { z } from "zod";
+import { DEFAULT_IMPACT_MAX_DEPTH, DEFAULT_IMPACT_MAX_EDGES, DEFAULT_IMPACT_MAX_NODES, IMPACT_DIRECTIONS, MAX_IMPACT_DEPTH, MAX_IMPACT_EDGES, MAX_IMPACT_NODES, resolveImpactRoot, traverseCompilerImpact, } from "../services/impact.js";
+import { FRESHNESS_CAUSES, SNAPSHOT_STATES, TRUNCATION_REASONS, } from "../services/read-contracts.js";
+import { withProject } from "../services/project.js";
+import { createRequestContext } from "../services/request-context.js";
+import { RELATIONSHIP_CONFIDENCES, RELATIONSHIP_EDGE_KINDS, RELATIONSHIP_PROVENANCES, RELATIONSHIP_RESOLUTIONS, } from "../services/relationships.js";
+import { createToolErrorContext, errorResult, formattedResult, ToolOutputFormatInputSchema, } from "./result.js";
+const AstGetImpactInputSchema = z.object({
+    project_root: z
+        .string()
+        .describe("Absolute project directory containing tsconfig.json, or the config path."),
+    file_path: z.string().describe("Project-relative file containing the exact impact root."),
+    symbol_path: z.string().describe("Exact symbol path returned by an outline or symbol search."),
+    direction: z
+        .enum(IMPACT_DIRECTIONS)
+        .default("both")
+        .describe("Traversal direction relative to the root symbol."),
+    max_depth: z
+        .number()
+        .int()
+        .min(0)
+        .max(MAX_IMPACT_DEPTH)
+        .default(DEFAULT_IMPACT_MAX_DEPTH)
+        .describe("Maximum relationship depth, including zero for the root only."),
+    max_nodes: z
+        .number()
+        .int()
+        .min(1)
+        .max(MAX_IMPACT_NODES)
+        .default(DEFAULT_IMPACT_MAX_NODES)
+        .describe("Maximum returned impact nodes, including the root."),
+    max_edges: z
+        .number()
+        .int()
+        .min(1)
+        .max(MAX_IMPACT_EDGES)
+        .default(DEFAULT_IMPACT_MAX_EDGES)
+        .describe("Maximum returned relationship edges."),
+    relationship_kinds: z
+        .array(z.enum(RELATIONSHIP_EDGE_KINDS))
+        .optional()
+        .describe("Optional relationship kinds to traverse; defaults to all normalized kinds."),
+    ...ToolOutputFormatInputSchema,
+});
+const SourceRangeSchema = z.object({
+    start_line: z.number().int().positive(),
+    start_column: z.number().int().positive().optional(),
+    end_line: z.number().int().positive().optional(),
+    end_column: z.number().int().positive().optional(),
+});
+const RelationshipEndpointSchema = z.object({
+    file: z.string(),
+    symbol_path: z.string(),
+    selector: z.string(),
+    range: SourceRangeSchema.optional(),
+});
+const FreshnessSchema = z.object({
+    state: z.enum(SNAPSHOT_STATES),
+    causes: z.array(z.enum(FRESHNESS_CAUSES)),
+    checked_at: z.string().nullable(),
+});
+const RelationshipEdgeSchema = z.object({
+    relationship_id: z.string(),
+    source: RelationshipEndpointSchema,
+    target: RelationshipEndpointSchema,
+    kind: z.enum(RELATIONSHIP_EDGE_KINDS),
+    provenance: z.enum(RELATIONSHIP_PROVENANCES),
+    confidence: z.enum(RELATIONSHIP_CONFIDENCES),
+    resolution: z.enum(RELATIONSHIP_RESOLUTIONS),
+    compiler_authoritative: z.boolean(),
+    freshness: FreshnessSchema,
+});
+const ImpactOutputSchema = z.object({
+    root: RelationshipEndpointSchema,
+    direction: z.enum(IMPACT_DIRECTIONS),
+    relationship_kinds: z.array(z.enum(RELATIONSHIP_EDGE_KINDS)),
+    nodes: z.array(z.object({
+        endpoint: RelationshipEndpointSchema,
+        depth: z.number().int().min(0),
+        direct: z.boolean(),
+    })),
+    edges: z.array(RelationshipEdgeSchema),
+    visited_nodes: z.number().int().min(0),
+    visited_edges: z.number().int().min(0),
+    max_depth_reached: z.number().int().min(0),
+    max_depth: z.number().int().min(0),
+    max_nodes: z.number().int().positive(),
+    max_edges: z.number().int().positive(),
+    incomplete: z.boolean(),
+    truncation: z.object({
+        truncated: z.boolean(),
+        reason: z.enum(TRUNCATION_REASONS).nullable(),
+    }),
+    truncation_reasons: z.array(z.enum(TRUNCATION_REASONS)),
+    freshness: FreshnessSchema,
+});
+export function registerGetImpact(server) {
+    server.registerTool("ast_get_impact", {
+        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,
+        outputSchema: ImpactOutputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async ({ project_root, file_path, symbol_path, direction, max_depth, max_nodes, max_edges, relationship_kinds, output_format, }, extra) => {
+        const requestContext = createRequestContext(extra.signal);
+        try {
+            const structuredContent = await withProject(project_root, (context, operationContext) => {
+                if (context.status.state !== "fresh") {
+                    throw new Error("Compiler-backed impact evidence is not fresh. Retry the read.");
+                }
+                const freshness = {
+                    state: context.status.state,
+                    causes: context.status.causes,
+                    checked_at: context.status.lastSuccessfulSyncAt,
+                };
+                const root = resolveImpactRoot(context.project, context.projectRoot, { file_path, symbol_path }, operationContext);
+                const impact = traverseCompilerImpact(context.project, context.projectRoot, root, freshness, { direction, max_depth, max_nodes, max_edges, relationship_kinds }, operationContext);
+                return {
+                    ...impact,
+                    freshness,
+                };
+            }, requestContext);
+            return formattedResult(ImpactOutputSchema, structuredContent, output_format);
+        }
+        catch (error) {
+            return errorResult(error, createToolErrorContext("ast_get_impact", project_root));
+        }
+    });
+}

package/dist/tools/get_operation_preview.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { getOperationPreview } from "../services/operations.js";
-import { errorResult, structuredResult } from "./result.js";
+import { createRequestContext } from "../services/request-context.js";
+import { createToolErrorContext, errorResult, structuredResult } from "./result.js";
 const AstGetOperationPreviewInputSchema = z.object({
     operation_id: z.string().uuid(),
     file: z.string().optional().describe("Optional affected file path to retrieve only its diff."),
@@ -22,12 +23,14 @@ export function registerGetOperationPreview(server) {
             idempotentHint: true,
             openWorldHint: false,
         },
-    }, async ({ operation_id, file }) => {
+    }, async ({ operation_id, file }, extra) => {
+        const requestContext = createRequestContext(extra.signal);
         try {
-            return structuredResult(getOperationPreview(operation_id, file));
+            const output = await getOperationPreview(operation_id, file, requestContext);
+            return structuredResult(output);
         }
         catch (error) {
-            return errorResult(error);
+            return errorResult(error, createToolErrorContext("ast_get_operation_preview"));
         }
     });
 }

package/dist/tools/get_outline.js

@@ -2,7 +2,8 @@ import path from "node:path";
 import { z } from "zod";
 import { buildFileOutline } from "../services/outline.js";
 import { getSourceFileOrThrow, withProject } from "../services/project.js";
-import { errorResult, structuredResult } from "./result.js";
+import { createRequestContext } from "../services/request-context.js";
+import { createToolErrorContext, errorResult, structuredResult } from "./result.js";
 const AstGetOutlineInputSchema = z.object({
     project_root: z
         .string()
@@ -38,21 +39,22 @@ export function registerGetOutline(server) {
             idempotentHint: true,
             openWorldHint: false,
         },
-    }, async ({ project_root, file_path, include_symbols }) => {
+    }, async ({ project_root, file_path, include_symbols }, extra) => {
+        const requestContext = createRequestContext(extra.signal);
         try {
-            const structuredContent = await withProject(project_root, ({ project, projectRoot }) => {
+            const structuredContent = await withProject(project_root, ({ project, projectRoot }, operationContext) => {
                 const sourceFile = getSourceFileOrThrow(project, file_path);
-                const outline = buildFileOutline(sourceFile);
+                const outline = buildFileOutline(sourceFile, operationContext);
                 return {
                     file: path.relative(projectRoot, sourceFile.getFilePath()),
                     outline: outline.text,
                     ...(include_symbols ? { symbols: outline.symbols } : {}),
                 };
-            });
+            }, requestContext);
             return structuredResult(structuredContent);
         }
         catch (error) {
-            return errorResult(error);
+            return errorResult(error, createToolErrorContext("ast_get_outline", project_root));
         }
     });
 }

package/dist/tools/get_project_status.js

@@ -1,7 +1,8 @@
 import { z } from "zod";
 import { FRESHNESS_CAUSES, SNAPSHOT_STATES, TRUNCATION_REASONS, } from "../services/read-contracts.js";
 import { getProjectStatus } from "../services/project.js";
-import { errorResult, structuredResult } from "./result.js";
+import { createRequestContext } from "../services/request-context.js";
+import { createToolErrorContext, errorResult, structuredResult } from "./result.js";
 const AstGetProjectStatusInputSchema = z.object({
     project_root: z
         .string()
@@ -11,6 +12,54 @@ const TruncationMetadataSchema = z.object({
     truncated: z.boolean(),
     reason: z.enum(TRUNCATION_REASONS).nullable(),
 });
+const IndexObservabilitySchema = z.object({
+    policy: z.enum(["disabled", "canary", "enabled"]),
+    policy_reason: z.enum([
+        "default",
+        "invalid_mode",
+        "enabled_not_released",
+        "cache_root_missing",
+        "cache_root_invalid",
+    ]),
+    backend: z.enum(["memory", "sqlite"]),
+    state: z.enum(["disabled", "ready", "rebuilding", "failed"]),
+    operation: z.enum([
+        "disabled",
+        "hit",
+        "miss",
+        "rebuild",
+        "fallback",
+        "migration",
+        "corruption",
+        "read_failure",
+        "write_failure",
+    ]),
+    last_operation: z.enum([
+        "disabled",
+        "hit",
+        "miss",
+        "rebuild",
+        "fallback",
+        "migration",
+        "corruption",
+        "read_failure",
+        "write_failure",
+    ]),
+    loaded_entries: z.number().int().min(0),
+    accepted_entries: z.number().int().min(0),
+    rejected_entries: z.number().int().min(0),
+    cache_hits: z.number().int().min(0),
+    cache_misses: z.number().int().min(0),
+    fallback_count: z.number().int().min(0),
+    migration_count: z.number().int().min(0),
+    corruption_count: z.number().int().min(0),
+    write_failure_count: z.number().int().min(0),
+    rebuilt_files: z.number().int().min(0),
+    reused_files: z.number().int().min(0),
+    removed_files: z.number().int().min(0),
+    last_error: z.string().nullable(),
+    last_successful_persistence_at: z.string().nullable(),
+});
 const ProjectStatusOutputSchema = z.object({
     project: z.object({
         project_id: z.string().regex(/^project_[0-9a-f]{20}$/),
@@ -28,21 +77,40 @@ const ProjectStatusOutputSchema = z.object({
     pending_files_truncation: TruncationMetadataSchema,
     pending_files_filename_truncation: TruncationMetadataSchema,
     compiler: z.object({ state: z.enum(["ready", "rebuilding", "failed"]) }),
-    index: z.object({ state: z.literal("disabled") }),
+    index: z.object({ state: z.enum(["disabled", "ready", "rebuilding", "failed"]) }),
     operation_queue: z.object({
         state: z.enum(["idle", "queued", "running"]),
-        active_operations: z.number().int().min(0),
-        queued_operations: z.number().int().min(0),
+        admission: z.enum(["open", "closed"]),
+        queue_capacity: z.number().int().min(1).max(256),
+        active_operations: z.number().int().min(0).max(1),
+        queued_operations: z.number().int().min(0).max(256),
+        rejected_operations: z.number().int().min(0).max(2_147_483_647),
+        cancelled_operations: z.number().int().min(0).max(2_147_483_647),
+        queue_timeout_operations: z.number().int().min(0).max(2_147_483_647),
+        deadline_exceeded_operations: z.number().int().min(0).max(2_147_483_647),
+        last_outcome: z.enum([
+            "none",
+            "succeeded",
+            "failed",
+            "rejected",
+            "cancelled",
+            "queue_timeout",
+            "deadline_exceeded",
+            "internal_error",
+        ]),
+        max_queue_wait_ms: z.number().int().min(0).max(86_400_000),
+        max_execution_ms: z.number().int().min(0).max(86_400_000),
     }),
     watcher: z.object({ state: z.enum(["disabled", "ready", "failed"]) }),
     last_successful_sync_at: z.string().nullable(),
-    last_successful_index_at: z.null(),
+    last_successful_index_at: z.string().nullable(),
     source_snapshot_fingerprint: z.string().nullable(),
     config_snapshot_fingerprint: z.string().nullable(),
     canonical_snapshot_fingerprint: z.string().nullable(),
     degraded_errors: z.array(z.string()),
     degraded_errors_truncation: TruncationMetadataSchema,
     degraded_errors_text_truncation: TruncationMetadataSchema,
+    index_observability: IndexObservabilitySchema,
 });
 export function registerGetProjectStatus(server) {
     server.registerTool("ast_get_project_status", {
@@ -56,13 +124,14 @@ export function registerGetProjectStatus(server) {
             idempotentHint: true,
             openWorldHint: false,
         },
-    }, async ({ project_root }) => {
+    }, async ({ project_root }, extra) => {
+        const requestContext = createRequestContext(extra.signal);
         try {
-            const output = await getProjectStatus(project_root);
+            const output = await getProjectStatus(project_root, requestContext);
             return structuredResult({ ...output });
         }
         catch (error) {
-            return errorResult(error);
+            return errorResult(error, createToolErrorContext("ast_get_project_status", project_root));
         }
     });
 }

package/dist/tools/get_symbol_source.js

@@ -1,7 +1,8 @@
 import { z } from "zod";
 import { nodeSourceWithLocation } from "../services/outline.js";
 import { findDeclarationByName, getSourceFileOrThrow, withProject } from "../services/project.js";
-import { errorResult, structuredResult } from "./result.js";
+import { createRequestContext } from "../services/request-context.js";
+import { createToolErrorContext, errorResult, structuredResult } from "./result.js";
 const AstGetSymbolSourceInputSchema = z.object({
     project_root: z
         .string()
@@ -27,17 +28,18 @@ export function registerGetSymbolSource(server) {
             idempotentHint: true,
             openWorldHint: false,
         },
-    }, async ({ project_root, file_path, symbol_path }) => {
+    }, async ({ project_root, file_path, symbol_path }, extra) => {
+        const requestContext = createRequestContext(extra.signal);
         try {
-            const structuredContent = await withProject(project_root, ({ project, projectRoot }) => {
+            const structuredContent = await withProject(project_root, ({ project, projectRoot }, operationContext) => {
                 const sourceFile = getSourceFileOrThrow(project, file_path);
                 const node = findDeclarationByName(sourceFile, symbol_path);
-                return nodeSourceWithLocation(node, projectRoot);
-            });
+                return nodeSourceWithLocation(node, projectRoot, operationContext);
+            }, requestContext);
             return structuredResult(structuredContent);
         }
         catch (error) {
-            return errorResult(error);
+            return errorResult(error, createToolErrorContext("ast_get_symbol_source", project_root));
         }
     });
 }

package/dist/tools/list_files.js

@@ -2,7 +2,8 @@ import path from "node:path";
 import { z } from "zod";
 import { PaginationInputSchema, PaginationOutputSchema, paginate } from "../services/pagination.js";
 import { withProject } from "../services/project.js";
-import { errorResult, structuredResult } from "./result.js";
+import { createRequestContext } from "../services/request-context.js";
+import { createToolErrorContext, errorResult, structuredResult } from "./result.js";
 const AstListFilesInputSchema = z.object({
     project_root: z
         .string()
@@ -29,23 +30,27 @@ export function registerListFiles(server) {
             idempotentHint: true,
             openWorldHint: false,
         },
-    }, async ({ project_root, glob_filter, offset, limit }) => {
+    }, async ({ project_root, glob_filter, offset, limit }, extra) => {
+        const requestContext = createRequestContext(extra.signal);
         try {
-            const output = await withProject(project_root, ({ project, projectRoot }) => {
+            const output = await withProject(project_root, ({ project, projectRoot }, operationContext) => {
                 const filter = glob_filter?.toLowerCase();
                 const files = project
                     .getSourceFiles()
-                    .map((sourceFile) => path.relative(projectRoot, sourceFile.getFilePath()))
+                    .map((sourceFile) => {
+                    operationContext.checkpoint();
+                    return path.relative(projectRoot, sourceFile.getFilePath());
+                })
                     .filter((file) => !filter || file.toLowerCase().includes(filter))
                     .sort((left, right) => left.localeCompare(right));
                 const page = paginate(files, offset, limit);
                 const { items, ...metadata } = page;
                 return { files: items, ...metadata };
-            });
+            }, requestContext);
             return structuredResult(output);
         }
         catch (error) {
-            return errorResult(error);
+            return errorResult(error, createToolErrorContext("ast_list_files", project_root));
         }
     });
 }

package/dist/tools/rename_symbol.js

@@ -1,7 +1,8 @@
 import { z } from "zod";
 import { prepareRename } from "../services/operations.js";
+import { createRequestContext } from "../services/request-context.js";
 import { PreparedOperationOutputSchema, serializePreparedOperation } from "./operation-schema.js";
-import { errorResult, structuredResult } from "./result.js";
+import { createToolErrorContext, errorResult, structuredResult } from "./result.js";
 const AstRenameSymbolInputSchema = z.object({
     project_root: z.string(),
     file_path: z.string(),
@@ -28,7 +29,8 @@ export function registerRenameSymbol(server) {
             idempotentHint: false,
             openWorldHint: false,
         },
-    }, async ({ project_root, file_path, symbol_path, new_name, dry_run, allow_new_errors }) => {
+    }, async ({ project_root, file_path, symbol_path, new_name, dry_run, allow_new_errors }, extra) => {
+        const requestContext = createRequestContext(extra.signal);
         try {
             if (!dry_run) {
                 throw new Error("Direct rename application is disabled. Prepare with dry_run=true, then call ast_apply_operation with the returned operation_id.");
@@ -39,11 +41,11 @@ export function registerRenameSymbol(server) {
                 symbolPath: symbol_path,
                 newName: new_name,
                 allowNewErrors: allow_new_errors,
-            });
+            }, requestContext);
             return structuredResult(serializePreparedOperation(operation));
         }
         catch (error) {
-            return errorResult(error);
+            return errorResult(error, createToolErrorContext("ast_rename_symbol", project_root));
         }
     });
 }

package/dist/tools/replace_symbol_body.js

@@ -1,7 +1,8 @@
 import { z } from "zod";
 import { prepareReplaceBody } from "../services/operations.js";
+import { createRequestContext } from "../services/request-context.js";
 import { PreparedOperationOutputSchema, serializePreparedOperation } from "./operation-schema.js";
-import { errorResult, structuredResult } from "./result.js";
+import { createToolErrorContext, errorResult, structuredResult } from "./result.js";
 const AstReplaceSymbolBodyInputSchema = z.object({
     project_root: z.string(),
     file_path: z.string(),
@@ -28,7 +29,8 @@ export function registerReplaceSymbolBody(server) {
             idempotentHint: false,
             openWorldHint: false,
         },
-    }, async ({ project_root, file_path, symbol_path, new_body, dry_run, allow_new_errors }) => {
+    }, async ({ project_root, file_path, symbol_path, new_body, dry_run, allow_new_errors }, extra) => {
+        const requestContext = createRequestContext(extra.signal);
         try {
             if (!dry_run) {
                 throw new Error("Direct body replacement is disabled. Prepare with dry_run=true, then call ast_apply_operation with the returned operation_id.");
@@ -39,11 +41,11 @@ export function registerReplaceSymbolBody(server) {
                 symbolPath: symbol_path,
                 newBody: new_body,
                 allowNewErrors: allow_new_errors,
-            });
+            }, requestContext);
             return structuredResult(serializePreparedOperation(operation));
         }
         catch (error) {
-            return errorResult(error);
+            return errorResult(error, createToolErrorContext("ast_replace_symbol_body", project_root));
         }
     });
 }

package/dist/tools/result.js

@@ -2,7 +2,9 @@ import { Buffer } from "node:buffer";
 import { isDeepStrictEqual } from "node:util";
 import { decode, encode } from "@toon-format/toon";
 import { z } from "zod";
-export const MAX_TOOL_ERROR_BYTES = 64 * 1024;
+import { createProjectIdentity } from "../services/project-status.js";
+import { renderPublicError } from "../services/public-errors.js";
+import { emitToolFailureEvent } from "../services/runtime-logger.js";
 export const MAX_TOON_RESULT_BYTES = 10 * 1024 * 1024;
 export const ToolOutputFormatSchema = z.enum(["json", "toon"]).default("json");
 export const ToolOutputFormatInputSchema = {
@@ -12,6 +14,16 @@ export const ToonResultSchema = z.object({
     format: z.literal("toon"),
     data: z.string(),
 });
+export function createToolErrorContext(toolName, projectRoot) {
+    if (typeof projectRoot !== "string")
+        return { toolName };
+    try {
+        return { toolName, projectIdentity: createProjectIdentity({ projectRoot }) };
+    }
+    catch {
+        return { toolName };
+    }
+}
 export function structuredResult(structuredContent) {
     return { content: [], structuredContent };
 }
@@ -30,27 +42,25 @@ export function formattedResult(outputSchema, candidate, outputFormat, maxToonBy
     }
     return structuredResult({ format: "toon", data: text });
 }
-function truncateUtf8(value, maxBytes) {
-    if (Buffer.byteLength(value, "utf8") <= maxBytes)
-        return value;
-    const suffix = "... [truncated]";
-    const source = Buffer.from(value, "utf8");
-    let end = Math.max(0, maxBytes - Buffer.byteLength(suffix, "utf8"));
-    while (end > 0 && (source[end] & 0xc0) === 0x80)
-        end -= 1;
-    let prefix = source.subarray(0, end).toString("utf8");
-    while (Buffer.byteLength(prefix + suffix, "utf8") > maxBytes) {
-        prefix = prefix.slice(0, -1);
+export function errorResult(error, context) {
+    const { envelope, text } = renderPublicError(error);
+    try {
+        emitToolFailureEvent({
+            correlationId: envelope.error.correlation_id,
+            toolName: context.toolName,
+            code: envelope.error.code,
+            message: envelope.error.message,
+            projectIdentity: context.projectIdentity,
+        });
+    }
+    catch {
+        // A logging sink failure must not replace the bounded MCP error.
     }
-    return prefix + suffix;
-}
-export function errorResult(error) {
-    const message = error instanceof Error ? error.message : String(error);
     return {
         content: [
             {
                 type: "text",
-                text: truncateUtf8(message, MAX_TOOL_ERROR_BYTES),
+                text,
             },
         ],
         isError: true,