agent-dir 0.1.4 → 0.3.0

package/dist/src/mcp.js

@@ -1,8 +1,11 @@
+import { randomUUID } from "node:crypto";
 import { createRequire } from "node:module";
+import { CodeGraphIntegration } from "./codegraph.js";
+import { TelemetryRecorder } from "./telemetry/recorder.js";
 import { findDefinition, findExports, findFiles, findImports, findReferences, findSymbol, searchCode, searchFiles, } from "./tools/code.js";
 import { runCommand } from "./tools/commands.js";
 import { diagnostics } from "./tools/diagnostics.js";
-import { deleteFile, listDirs, listFiles, patchFiles, readFile, readRange, writeFile, } from "./tools/files.js";
+import { applyFileChanges, deleteFile, listDirs, listFiles, patchFiles, readFile, readRange, writeFile, } from "./tools/files.js";
 import { gitCommit, gitDiff, gitLog, gitPush, gitRestore, gitStage, gitStatus, gitUnstage, } from "./tools/git.js";
 import { fileInfo, packageInfo, projectOverview } from "./tools/metadata.js";
 import { runNpm } from "./tools/npm.js";
@@ -16,6 +19,7 @@ const SERVER_INFO_META = { "io.modelcontextprotocol/serverInfo": SERVER_INFO };
 const PROTOCOL_META = "io.modelcontextprotocol/protocolVersion";
 const CLIENT_CAPABILITIES_META = "io.modelcontextprotocol/clientCapabilities";
 const PAGE_SIZE = 50;
+const DEFAULT_OUTPUT_BYTES = 32_000;
 const INSTRUCTIONS_URI = "agent-dir://instructions";
 const CAPABILITIES_URI = "agent-dir://capabilities";
 const SUBSCRIPTION_ID_META = "io.modelcontextprotocol/subscriptionId";
@@ -43,9 +47,18 @@ const commandResultSchema = objectOutput({
     stdout: stringSchema,
     stderr: stringSchema,
 }, ["command", "exitCode", "stdout", "stderr"]);
+const codeGraphTool = tool("codegraph_explore", "Explore the current project through its optional CodeGraph MCP index. Returns CodeGraph native structured tool results for structural, flow, and symbol questions.", {
+    query: { type: "string", minLength: 1 },
+    maxFiles: { type: "integer", minimum: 1, maximum: 100 },
+}, { type: "object" }, ["query"]);
 const baseTools = [
-    tool("list_files", "List all visible project files and directories recursively up to the server's discovery depth. Prefer project_overview, find_files, search_code, or list_dirs for targeted discovery; use this only when broad recursive discovery is actually needed.", {}, arrayOutput(fileEntrySchema)),
-    tool("list_dirs", "List files and directories directly inside one or more project directories.", { paths: { type: "array", items: pathSchema, minItems: 1 } }, arrayOutput(objectOutput({ path: stringSchema, entries: arrayOutput(fileEntrySchema) }, [
+    tool("list_files", "List all visible project files and directories recursively up to the server's discovery depth. Prefer project_overview, find_files, search_code, or list_dirs for targeted discovery; use this only when broad recursive discovery is actually needed.", {
+        maxBytes: { type: "integer", minimum: 1024, maximum: 1000000, default: DEFAULT_OUTPUT_BYTES },
+    }, arrayOutput(fileEntrySchema)),
+    tool("list_dirs", "List files and directories directly inside one or more project directories.", {
+        paths: { type: "array", items: pathSchema, minItems: 1 },
+        maxBytes: { type: "integer", minimum: 1024, maximum: 1000000, default: DEFAULT_OUTPUT_BYTES },
+    }, arrayOutput(objectOutput({ path: stringSchema, entries: arrayOutput(fileEntrySchema) }, [
         "path",
         "entries",
     ])), ["paths"]),
@@ -53,14 +66,50 @@ const baseTools = [
         path: pathSchema,
         startLine: { type: "integer", minimum: 1 },
         endLine: { type: "integer", minimum: 1 },
+        maxBytes: { type: "integer", minimum: 1024, maximum: 1000000, default: DEFAULT_OUTPUT_BYTES },
     }, objectOutput({
         path: stringSchema,
         startLine: { type: "integer" },
         endLine: { type: "integer" },
         content: stringSchema,
     }, ["path", "startLine", "endLine", "content"]), ["path", "startLine", "endLine"]),
-    tool("read_files", "Read one or more UTF-8 project files in one call. Prefer read_range when only a bounded section is needed; batch related files here to reduce round trips.", { paths: { type: "array", items: pathSchema, minItems: 1 } }, arrayOutput(objectOutput({ path: stringSchema, content: stringSchema }, ["path", "content"])), ["paths"]),
+    tool("read_files", "Read one or more UTF-8 project files in one call. Prefer read_range when only a bounded section is needed; batch related files here to reduce round trips.", {
+        paths: { type: "array", items: pathSchema, minItems: 1 },
+        maxBytes: { type: "integer", minimum: 1024, maximum: 1000000, default: DEFAULT_OUTPUT_BYTES },
+    }, arrayOutput(objectOutput({ path: stringSchema, content: stringSchema }, ["path", "content"])), ["paths"]),
+    tool("apply_changes", "Apply multiple file writes, exact patches, and deletes as one preflighted transaction. Use this for related multi-file edits when partial changes would be undesirable; supports dry-run previews.", {
+        dryRun: { type: "boolean", default: false },
+        changes: {
+            type: "array",
+            minItems: 1,
+            items: {
+                type: "object",
+                properties: {
+                    kind: { type: "string", enum: ["write", "patch", "delete"] },
+                    path: pathSchema,
+                    content: stringSchema,
+                    patches: {
+                        type: "array",
+                        items: objectOutput({
+                            search: stringSchema,
+                            replace: stringSchema,
+                            count: { type: "integer", minimum: 1 },
+                        }, ["search", "replace"]),
+                        minItems: 1,
+                    },
+                },
+                required: ["kind", "path"],
+                additionalProperties: false,
+            },
+        },
+    }, arrayOutput(objectOutput({
+        kind: { type: "string", enum: ["write", "patch", "delete"] },
+        path: stringSchema,
+        changed: { type: "boolean" },
+        dryRun: { type: "boolean" },
+    }, ["kind", "path", "changed"])), ["changes"]),
     tool("write_files", "Create or completely replace one or more UTF-8 project files.", {
+        dryRun: { type: "boolean", default: false },
         files: {
             type: "array",
             items: objectOutput({ path: pathSchema, content: stringSchema }, ["path", "content"]),
@@ -68,6 +117,7 @@ const baseTools = [
         },
     }, arrayOutput(objectOutput({ path: stringSchema, written: { type: "boolean" } }, ["path", "written"])), ["files"]),
     tool("patch_files", "Apply exact text replacements to one or more UTF-8 files. Prefer this for targeted edits instead of rewriting whole files; batch related patches in one call.", {
+        dryRun: { type: "boolean", default: false },
         files: {
             type: "array",
             items: objectOutput({
@@ -84,29 +134,37 @@ const baseTools = [
             }, ["path", "patches"]),
             minItems: 1,
         },
+        maxBytes: { type: "integer", minimum: 1024, maximum: 1000000, default: DEFAULT_OUTPUT_BYTES },
     }, arrayOutput(objectOutput({ path: stringSchema, applied: { type: "integer" }, content: stringSchema }, [
         "path",
         "applied",
         "content",
     ])), ["files"]),
-    tool("delete_files", "Delete one or more project files.", { paths: { type: "array", items: pathSchema, minItems: 1 } }, arrayOutput(objectOutput({ path: stringSchema, deleted: { type: "boolean" } }, ["path", "deleted"])), ["paths"]),
+    tool("delete_files", "Delete one or more project files.", {
+        paths: { type: "array", items: pathSchema, minItems: 1 },
+        dryRun: { type: "boolean", default: false },
+    }, arrayOutput(objectOutput({ path: stringSchema, deleted: { type: "boolean" } }, ["path", "deleted"])), ["paths"]),
     tool("search_files", "Search text across visible project files. Prefer this over broad file reads; use search_code for source-only searches and keep maxResults tight.", {
         query: stringSchema,
         regex: { type: "boolean", default: false },
         maxResults: { type: "integer", minimum: 1, maximum: 1000, default: 200 },
+        maxBytes: { type: "integer", minimum: 1024, maximum: 1000000, default: DEFAULT_OUTPUT_BYTES },
     }, arrayOutput(searchMatchSchema), ["query"]),
     tool("find_files", "Find project files by a simple glob pattern using * and ?. Prefer this over list_files when you know the filename pattern.", {
         pattern: stringSchema,
         maxResults: { type: "integer", minimum: 1, maximum: 1000, default: 200 },
+        maxBytes: { type: "integer", minimum: 1024, maximum: 1000000, default: DEFAULT_OUTPUT_BYTES },
     }, arrayOutput(stringSchema), ["pattern"]),
     tool("search_code", "Search source-like project files for text or a regular expression. Prefer this over reading files broadly; start with a narrow query and expand only if needed.", {
         query: stringSchema,
         regex: { type: "boolean", default: false },
         maxResults: { type: "integer", minimum: 1, maximum: 1000, default: 200 },
+        maxBytes: { type: "integer", minimum: 1024, maximum: 1000000, default: DEFAULT_OUTPUT_BYTES },
     }, arrayOutput(searchMatchSchema), ["query"]),
     tool("find_symbol", "Find likely symbol definitions across source files. Prefer this over reading whole modules when locating an implementation.", {
         symbol: stringSchema,
         maxResults: { type: "integer", minimum: 1, maximum: 500, default: 100 },
+        maxBytes: { type: "integer", minimum: 1024, maximum: 1000000, default: DEFAULT_OUTPUT_BYTES },
     }, arrayOutput(objectOutput({
         ...searchMatchSchema.properties,
         symbol: stringSchema,
@@ -115,6 +173,7 @@ const baseTools = [
     tool("find_definition", "Find likely definitions of a symbol. Use this before reading a large file when you need one implementation.", {
         symbol: stringSchema,
         maxResults: { type: "integer", minimum: 1, maximum: 500, default: 100 },
+        maxBytes: { type: "integer", minimum: 1024, maximum: 1000000, default: DEFAULT_OUTPUT_BYTES },
     }, arrayOutput(objectOutput({
         ...searchMatchSchema.properties,
         symbol: stringSchema,
@@ -123,25 +182,101 @@ const baseTools = [
     tool("find_references", "Find source-code references to a symbol. Use this instead of searching entire files when tracing usage of a known symbol.", {
         symbol: stringSchema,
         maxResults: { type: "integer", minimum: 1, maximum: 1000, default: 200 },
+        maxBytes: { type: "integer", minimum: 1024, maximum: 1000000, default: DEFAULT_OUTPUT_BYTES },
     }, arrayOutput(searchMatchSchema), ["symbol"]),
-    tool("find_imports", "Find import and require statements in source files.", { maxResults: { type: "integer", minimum: 1, maximum: 1000, default: 200 } }, arrayOutput(objectOutput({
+    tool("find_imports", "Find import and require statements in source files.", {
+        maxResults: { type: "integer", minimum: 1, maximum: 1000, default: 200 },
+        maxBytes: { type: "integer", minimum: 1024, maximum: 1000000, default: DEFAULT_OUTPUT_BYTES },
+    }, arrayOutput(objectOutput({
         ...searchMatchSchema.properties,
         module: stringSchema,
         kind: { type: "string", enum: ["import", "require"] },
     }, ["path", "line", "column", "text", "module", "kind"]))),
-    tool("find_exports", "Find exported declarations in source files.", { maxResults: { type: "integer", minimum: 1, maximum: 1000, default: 200 } }, arrayOutput(objectOutput({
+    tool("find_exports", "Find exported declarations in source files.", {
+        maxResults: { type: "integer", minimum: 1, maximum: 1000, default: 200 },
+        maxBytes: { type: "integer", minimum: 1024, maximum: 1000000, default: DEFAULT_OUTPUT_BYTES },
+    }, arrayOutput(objectOutput({
         ...searchMatchSchema.properties,
         symbol: stringSchema,
         kind: { type: "string", const: "export" },
     }, ["path", "line", "column", "text", "symbol", "kind"]))),
-    tool("git_status", "Show Git working-tree status and branch information. Use this as the lightweight first Git check; do not run a full diff unless changes need inspection.", {}, commandResultSchema),
-    tool("git_stage", "Stage one or more Git paths.", { paths: { type: "array", items: pathSchema, minItems: 1 } }, commandResultSchema, ["paths"]),
-    tool("git_unstage", "Unstage one or more Git paths without changing their working-tree contents.", { paths: { type: "array", items: pathSchema, minItems: 1 } }, commandResultSchema, ["paths"]),
-    tool("git_commit", "Create a Git commit with the currently staged changes.", { message: stringSchema }, commandResultSchema, ["message"]),
-    tool("git_restore", "Restore one or more Git paths from the index, discarding unstaged working-tree changes.", { paths: { type: "array", items: pathSchema, minItems: 1 } }, commandResultSchema, ["paths"]),
-    tool("git_push", "Push the current Git branch to a remote.", { remote: stringSchema, branch: stringSchema }, commandResultSchema),
-    tool("git_diff", "Show a read-only Git diff, optionally staged or limited to a path. Prefer path-scoped or staged diffs over dumping the entire repository diff.", { staged: { type: "boolean", default: false }, path: pathSchema }, commandResultSchema),
-    tool("git_log", "Show recent Git commits in a compact, read-only form. Keep the limit small and scope by path when history context is local.", { limit: { type: "integer", minimum: 1, maximum: 200, default: 20 }, path: pathSchema }, commandResultSchema),
+    tool("git_status", "Show Git working-tree status and branch information. Use this as the lightweight first Git check; do not run a full diff unless changes need inspection.", {
+        maxBytes: { type: "integer", minimum: 1024, maximum: 1000000, default: DEFAULT_OUTPUT_BYTES },
+    }, commandResultSchema),
+    tool("git_stage", "Stage one or more Git paths.", {
+        paths: { type: "array", items: pathSchema, minItems: 1 },
+        maxBytes: { type: "integer", minimum: 1024, maximum: 1000000, default: DEFAULT_OUTPUT_BYTES },
+    }, commandResultSchema, ["paths"]),
+    tool("git_unstage", "Unstage one or more Git paths without changing their working-tree contents.", {
+        paths: { type: "array", items: pathSchema, minItems: 1 },
+        maxBytes: { type: "integer", minimum: 1024, maximum: 1000000, default: DEFAULT_OUTPUT_BYTES },
+    }, commandResultSchema, ["paths"]),
+    tool("git_commit", "Create a Git commit with the currently staged changes.", {
+        message: stringSchema,
+        maxBytes: { type: "integer", minimum: 1024, maximum: 1000000, default: DEFAULT_OUTPUT_BYTES },
+    }, commandResultSchema, ["message"]),
+    tool("git_restore", "Restore one or more Git paths from the index, discarding unstaged working-tree changes.", {
+        paths: { type: "array", items: pathSchema, minItems: 1 },
+        maxBytes: { type: "integer", minimum: 1024, maximum: 1000000, default: DEFAULT_OUTPUT_BYTES },
+    }, commandResultSchema, ["paths"]),
+    tool("git_push", "Push the current Git branch to a remote.", {
+        remote: stringSchema,
+        branch: stringSchema,
+        maxBytes: { type: "integer", minimum: 1024, maximum: 1000000, default: DEFAULT_OUTPUT_BYTES },
+    }, commandResultSchema),
+    tool("git_diff", "Show a read-only Git diff, optionally staged or limited to a path. Prefer path-scoped or staged diffs over dumping the entire repository diff.", {
+        staged: { type: "boolean", default: false },
+        path: pathSchema,
+        maxBytes: { type: "integer", minimum: 1024, maximum: 1000000, default: DEFAULT_OUTPUT_BYTES },
+    }, commandResultSchema),
+    tool("git_log", "Show recent Git commits in a compact, read-only form. Keep the limit small and scope by path when history context is local.", {
+        limit: { type: "integer", minimum: 1, maximum: 200, default: 20 },
+        path: pathSchema,
+        maxBytes: { type: "integer", minimum: 1024, maximum: 1000000, default: DEFAULT_OUTPUT_BYTES },
+    }, commandResultSchema),
+    tool("locate", "Locate project code or files in one call. Use kind auto, code, text, or file.", {
+        query: stringSchema,
+        kind: { type: "string", enum: ["auto", "code", "text", "file"], default: "auto" },
+        regex: { type: "boolean", default: false },
+        maxResults: { type: "integer", minimum: 1, maximum: 100, default: 20 },
+        maxBytes: { type: "integer", minimum: 1024, maximum: 1000000, default: DEFAULT_OUTPUT_BYTES },
+    }, { type: "object", additionalProperties: true }, ["query"]),
+    tool("inspect_symbol", "Inspect a known symbol in one call, returning its definition, bounded source context, and optionally references.", {
+        symbol: stringSchema,
+        includeReferences: { type: "boolean", default: false },
+        contextLines: { type: "integer", minimum: 0, maximum: 20, default: 3 },
+        maxResults: { type: "integer", minimum: 1, maximum: 20, default: 5 },
+        maxBytes: { type: "integer", minimum: 1024, maximum: 1000000, default: DEFAULT_OUTPUT_BYTES },
+    }, { type: "object", additionalProperties: true }, ["symbol"]),
+    tool("inspect", "Inspect a project target in one call. Use kind auto, file, symbol, or code; returns bounded context and optional symbol references.", {
+        target: stringSchema,
+        kind: { type: "string", enum: ["auto", "file", "symbol", "code"], default: "auto" },
+        includeReferences: { type: "boolean", default: false },
+        contextLines: { type: "integer", minimum: 0, maximum: 20, default: 3 },
+        maxResults: { type: "integer", minimum: 1, maximum: 20, default: 5 },
+        maxBytes: { type: "integer", minimum: 1024, maximum: 1000000, default: DEFAULT_OUTPUT_BYTES },
+    }, { type: "object", additionalProperties: true }, ["target"]),
+    tool("project_context", "Return a compact LLM-oriented project snapshot combining project overview, package metadata, and active execution policy. Prefer this over separate orientation calls.", {
+        maxBytes: { type: "integer", minimum: 1024, maximum: 1000000, default: DEFAULT_OUTPUT_BYTES },
+    }, { type: "object", additionalProperties: true }),
+    tool("read_relevant", "Locate relevant source matches for a query and return bounded source context in one call. Prefer this when you know what you need but not the exact lines.", {
+        query: stringSchema,
+        regex: { type: "boolean", default: false },
+        contextLines: { type: "integer", minimum: 0, maximum: 20, default: 3 },
+        maxResults: { type: "integer", minimum: 1, maximum: 20, default: 5 },
+        maxBytes: { type: "integer", minimum: 1024, maximum: 1000000, default: DEFAULT_OUTPUT_BYTES },
+    }, { type: "object", additionalProperties: true }, ["query"]),
+    tool("validate", "Run a unified project validation pass: lightweight diagnostics first, then explicitly requested allowed npm scripts. Use diagnostics for cheap checks and scripts only when executable validation is needed.", {
+        level: { type: "string", enum: ["diagnostics", "scripts", "full"], default: "diagnostics" },
+        scripts: { type: "array", items: stringSchema, minItems: 1 },
+        maxResults: { type: "integer", minimum: 1, maximum: 1000, default: 200 },
+        maxBytes: { type: "integer", minimum: 1024, maximum: 1000000, default: DEFAULT_OUTPUT_BYTES },
+    }, { type: "object", additionalProperties: true }),
+    tool("git_changes", "Return a compact Git working-tree snapshot combining status and an optional diff. Prefer this over separate git_status and git_diff calls when reviewing changes.", {
+        includeDiff: { type: "boolean", default: false },
+        path: pathSchema,
+        maxBytes: { type: "integer", minimum: 1024, maximum: 1000000, default: DEFAULT_OUTPUT_BYTES },
+    }, { type: "object", additionalProperties: true }),
     tool("project_overview", "Summarize project structure, languages, package managers, project metadata files, and Git state in one lightweight call. Prefer this before broad discovery.", {}, objectOutput({
         root: stringSchema,
         files: { type: "integer" },
@@ -157,20 +292,27 @@ const baseTools = [
         commands: { type: "array", items: stringSchema },
     }, ["npmScripts", "commands"])),
     tool("file_info", "Return filesystem metadata for a project path.", { path: pathSchema }, { type: "object", additionalProperties: true }, ["path"]),
-    tool("diagnostics", "Run lightweight project-independent diagnostics without invoking tests, linters, or typecheckers. Prefer this before expensive validation when checking basic file/JSON/conflict issues.", { maxResults: { type: "integer", minimum: 1, maximum: 1000, default: 200 } }, arrayOutput(objectOutput({
+    tool("diagnostics", "Run lightweight project-independent diagnostics without invoking tests, linters, or typecheckers. Prefer this before expensive validation when checking basic file/JSON/conflict issues.", {
+        maxResults: { type: "integer", minimum: 1, maximum: 1000, default: 200 },
+        maxBytes: { type: "integer", minimum: 1024, maximum: 1000000, default: DEFAULT_OUTPUT_BYTES },
+    }, arrayOutput(objectOutput({
         severity: { type: "string", enum: ["error", "warning", "info"] },
         code: stringSchema,
         path: stringSchema,
         line: { type: "integer" },
         message: stringSchema,
     }, ["severity", "code", "message"]))),
-    tool("run_npm_batch", "Run one or more explicitly allowed npm scripts sequentially. Prefer the narrowest relevant script; batch independent scripts in one call and avoid running full check/test when a targeted check answers the question.", { scripts: { type: "array", items: stringSchema, minItems: 1 } }, arrayOutput(commandResultSchema), ["scripts"]),
+    tool("run_npm_batch", "Run one or more explicitly allowed npm scripts sequentially. Prefer the narrowest relevant script; batch independent scripts in one call and avoid running full check/test when a targeted check answers the question.", {
+        scripts: { type: "array", items: stringSchema, minItems: 1 },
+        maxBytes: { type: "integer", minimum: 1024, maximum: 1000000, default: DEFAULT_OUTPUT_BYTES },
+    }, arrayOutput(commandResultSchema), ["scripts"]),
     tool("run_command_batch", "Run one or more explicitly allowed commands sequentially without a shell. Prefer dedicated Agent Dir tools over generic commands because they return structured, bounded results with less token overhead.", {
         commands: {
             type: "array",
             items: objectOutput({ command: stringSchema, args: { type: "array", items: stringSchema } }, ["command"]),
             minItems: 1,
         },
+        maxBytes: { type: "integer", minimum: 1024, maximum: 1000000, default: DEFAULT_OUTPUT_BYTES },
     }, arrayOutput(commandResultSchema), ["commands"]),
 ];
 function tool(name, description, properties, outputSchema, required = []) {
@@ -187,9 +329,28 @@ function tool(name, description, properties, outputSchema, required = []) {
         outputSchema,
     };
 }
-export function createMcpHandler(root, commandConfig = {}) {
+export function createMcpHandler(root, commandConfig = {}, telemetry = { level: "none" }) {
+    const codeGraph = new CodeGraphIntegration(root);
+    const telemetryRecorder = new TelemetryRecorder({
+        level: telemetry.level,
+        persist: telemetry.persist ?? false,
+        ...(telemetry.configId ? { configId: telemetry.configId } : {}),
+        sessionId: telemetry.sessionId ?? randomUUID(),
+    });
+    let sessionStartedAt;
+    let sessionLastActivityAt;
+    let sessionActiveRequestDurationMs = 0;
+    let sessionRequestCount = 0;
+    let sessionToolCallCount = 0;
+    let sessionCommandCallCount = 0;
+    let sessionRecorded = false;
+    const telemetryProjectPromise = telemetry.level === "detailed"
+        ? buildTelemetryProjectContext(root, codeGraph).catch(() => undefined)
+        : undefined;
     const npmAllowed = commandConfig.npm?.allowedScripts ?? [];
     const allowedCommands = commandConfig.commands ?? [];
+    const blacklistedCommands = commandConfig.blacklistedCommands ?? [];
+    const gitEnabled = commandConfig.git ?? allowedCommands.includes("git");
     const subscriptions = new Set();
     const notify = (event) => {
         for (const subscription of subscriptions) {
@@ -220,23 +381,65 @@ export function createMcpHandler(root, commandConfig = {}) {
         }
     };
     const handler = async (request) => {
+        const requestStartedAt = performance.now();
+        if (sessionStartedAt === undefined)
+            sessionStartedAt = requestStartedAt;
+        sessionRequestCount += 1;
+        const telemetryProject = telemetryProjectPromise ? await telemetryProjectPromise : undefined;
         let message;
+        let mcpSuccess = false;
+        let runtime;
+        let telemetryRequestErrorCategory;
+        const recordMcpRequest = (method = message?.method ?? "unknown") => {
+            telemetryRecorder.record({
+                event: "mcp_request",
+                method,
+                success: mcpSuccess,
+                durationMs: performance.now() - requestStartedAt,
+                ...(telemetryRequestErrorCategory
+                    ? { errorCategory: telemetryRequestErrorCategory }
+                    : {}),
+            }, runtime, telemetryProject);
+        };
         try {
-            message = (await request.json());
+            const parsed = await request.json();
+            if (!isRecord(parsed)) {
+                telemetryRequestErrorCategory = "invalid_input";
+                recordMcpRequest("unknown");
+                return jsonRpcError(null, -32600, "Invalid Request", 400);
+            }
+            message = parsed;
         }
         catch {
+            telemetryRequestErrorCategory = "invalid_input";
+            recordMcpRequest("unknown");
             return jsonRpcError(null, -32700, "Parse error", 400);
         }
-        if (message.jsonrpc !== "2.0" || typeof message.method !== "string")
+        if (message.jsonrpc !== "2.0" || typeof message.method !== "string") {
+            telemetryRequestErrorCategory = "invalid_input";
+            recordMcpRequest(typeof message?.method === "string" ? message.method : "unknown");
             return jsonRpcError(message.id ?? null, -32600, "Invalid Request", 400);
+        }
         const hasId = Object.hasOwn(message, "id");
-        if (hasId && !isValidRequestId(message.id))
+        if (hasId && !isValidRequestId(message.id)) {
+            telemetryRequestErrorCategory = "invalid_input";
+            recordMcpRequest(message.method);
             return jsonRpcError(null, -32600, "Invalid Request", 400);
-        if (!hasId)
+        }
+        if (!hasId) {
+            mcpSuccess = message.method.startsWith("notifications/");
+            if (!mcpSuccess)
+                telemetryRequestErrorCategory = "invalid_input";
+            recordMcpRequest();
             return new Response(null, { status: 202 });
-        if (message.params !== undefined && !isRecord(message.params))
+        }
+        if (message.params !== undefined && !isRecord(message.params)) {
+            telemetryRequestErrorCategory = "invalid_input";
+            recordMcpRequest();
             return jsonRpcError(message.id, -32602, "Invalid params.", 400);
+        }
         const params = message.params ?? {};
+        runtime = telemetryRuntime(params);
         const requestedProtocolVersion = typeof params.protocolVersion === "string" ? params.protocolVersion : undefined;
         const legacyInitialize = message.method === "initialize";
         const legacyRequest = !legacyInitialize &&
@@ -244,15 +447,26 @@ export function createMcpHandler(root, commandConfig = {}) {
             !isRecord(params._meta);
         if (legacyInitialize) {
             const protocolHeader = request.headers.get("mcp-protocol-version");
-            if (protocolHeader !== null && protocolHeader !== LEGACY_PROTOCOL_VERSION)
+            if (protocolHeader !== null && protocolHeader !== LEGACY_PROTOCOL_VERSION) {
+                telemetryRequestErrorCategory = "invalid_input";
+                recordMcpRequest();
                 return jsonRpcError(message.id ?? null, -32020, "MCP-Protocol-Version does not match the initialize protocol version.", 400);
-            if (requestedProtocolVersion !== LEGACY_PROTOCOL_VERSION)
+            }
+            if (requestedProtocolVersion !== LEGACY_PROTOCOL_VERSION) {
+                telemetryRequestErrorCategory = "invalid_input";
+                recordMcpRequest();
                 return jsonRpcError(message.id ?? null, -32602, "Unsupported protocol version.", 400, {
                     supported: [LEGACY_PROTOCOL_VERSION],
                     requested: requestedProtocolVersion,
                 });
-            if (!isRecord(params.capabilities) || !isRecord(params.clientInfo))
+            }
+            if (!isRecord(params.capabilities) || !isRecord(params.clientInfo)) {
+                telemetryRequestErrorCategory = "invalid_input";
+                recordMcpRequest();
                 return jsonRpcError(message.id ?? null, -32602, "Invalid initialize params.", 400);
+            }
+            mcpSuccess = true;
+            recordMcpRequest();
             return json({
                 jsonrpc: "2.0",
                 id: message.id,
@@ -260,30 +474,46 @@ export function createMcpHandler(root, commandConfig = {}) {
                     protocolVersion: LEGACY_PROTOCOL_VERSION,
                     capabilities: capabilities(),
                     serverInfo: SERVER_INFO,
-                    instructions: buildAgentInstructions(npmAllowed, allowedCommands),
+                    instructions: buildAgentInstructions(npmAllowed, allowedCommands, blacklistedCommands, gitEnabled, await codeGraph.capability()),
                 },
             });
         }
         if (legacyRequest) {
-            if (request.headers.get("mcp-protocol-version") !== LEGACY_PROTOCOL_VERSION)
+            if (request.headers.get("mcp-protocol-version") !== LEGACY_PROTOCOL_VERSION) {
+                telemetryRequestErrorCategory = "invalid_input";
+                recordMcpRequest();
                 return jsonRpcError(message.id ?? null, -32020, "MCP-Protocol-Version must be 2025-11-25 for legacy requests.", 400);
+            }
         }
-        else if (!isRecord(params._meta))
+        else if (!isRecord(params._meta)) {
+            telemetryRequestErrorCategory = "invalid_input";
+            recordMcpRequest();
             return jsonRpcError(message.id ?? null, -32602, "Missing required request metadata.", 400);
+        }
         const meta = isRecord(params._meta) ? params._meta : {};
         const version = meta[PROTOCOL_META];
-        if (!legacyRequest && typeof version !== "string")
+        if (!legacyRequest && typeof version !== "string") {
+            telemetryRequestErrorCategory = "invalid_input";
+            recordMcpRequest();
             return jsonRpcError(message.id ?? null, -32602, "Missing required protocol version metadata.", 400);
-        if (!legacyRequest && version !== PROTOCOL_VERSION)
+        }
+        if (!legacyRequest && version !== PROTOCOL_VERSION) {
+            telemetryRequestErrorCategory = "invalid_input";
+            recordMcpRequest();
             return jsonRpcError(message.id ?? null, -32022, "Unsupported protocol version.", 400, {
                 supported: [PROTOCOL_VERSION],
                 requested: version,
             });
-        if (!legacyRequest && !isRecord(meta[CLIENT_CAPABILITIES_META]))
+        }
+        if (!legacyRequest && !isRecord(meta[CLIENT_CAPABILITIES_META])) {
+            telemetryRequestErrorCategory = "invalid_input";
+            recordMcpRequest();
             return jsonRpcError(message.id ?? null, -32602, "Missing required client capabilities metadata.", 400);
+        }
         try {
             switch (message.method) {
                 case "server/discover":
+                    mcpSuccess = true;
                     return json({
                         jsonrpc: "2.0",
                         id: message.id,
@@ -292,13 +522,15 @@ export function createMcpHandler(root, commandConfig = {}) {
                             supportedVersions: [PROTOCOL_VERSION],
                             capabilities: capabilities(),
                             _meta: SERVER_INFO_META,
-                            instructions: buildAgentInstructions(npmAllowed, allowedCommands),
+                            instructions: buildAgentInstructions(npmAllowed, allowedCommands, blacklistedCommands, gitEnabled, await codeGraph.capability()),
+                            codeGraph: await codeGraph.capability(),
                             ttlMs: 0,
                             cacheScope: "private",
                         },
                     });
                 case "tools/list": {
-                    const page = paginate(baseTools, params.cursor);
+                    const page = paginate(await availableTools(codeGraph, gitEnabled), params.cursor);
+                    mcpSuccess = true;
                     return json({
                         jsonrpc: "2.0",
                         id: message.id,
@@ -313,23 +545,86 @@ export function createMcpHandler(root, commandConfig = {}) {
                     });
                 }
                 case "tools/call": {
-                    if (typeof params.name !== "string" || params.name.length === 0)
+                    if (typeof params.name !== "string" || params.name.length === 0) {
+                        telemetryRequestErrorCategory = "invalid_input";
                         return jsonRpcError(message.id ?? null, -32602, "tools/call name must be a non-empty string.", 400);
+                    }
                     const toolName = params.name;
-                    const toolDefinition = baseTools.find((item) => item.name === toolName);
+                    const toolDefinition = (await availableTools(codeGraph, gitEnabled)).find((item) => item.name === toolName);
                     if (!toolDefinition)
                         throw new Error(`Unknown tool: ${toolName}`);
-                    if (params.arguments !== undefined && !isRecord(params.arguments))
+                    if (params.arguments !== undefined && !isRecord(params.arguments)) {
+                        telemetryRequestErrorCategory = "invalid_input";
                         return jsonRpcError(message.id ?? null, -32602, "tools/call arguments must be an object.", 400);
+                    }
                     const argumentsValue = params.arguments ?? {};
                     const headerError = validateMcpParamHeaders(toolDefinition.inputSchema, argumentsValue, request.headers);
-                    if (headerError)
+                    if (headerError) {
+                        telemetryRequestErrorCategory = "invalid_input";
                         return jsonRpcError(message.id ?? null, -32020, headerError, 400);
-                    return json({
-                        jsonrpc: "2.0",
-                        id: message.id,
-                        result: await callTool(toolName, argumentsValue, root, npmAllowed, allowedCommands, notify, request.signal),
-                    });
+                    }
+                    sessionToolCallCount += 1;
+                    const startedAt = performance.now();
+                    try {
+                        const result = await callTool(toolName, argumentsValue, root, npmAllowed, allowedCommands, blacklistedCommands, gitEnabled, notify, request.signal, codeGraph);
+                        const durationMs = performance.now() - startedAt;
+                        const count = resultCount(result);
+                        const runtime = telemetryRuntime(params);
+                        telemetryRecorder.record({
+                            event: "tool_call",
+                            tool: toolName,
+                            success: true,
+                            durationMs,
+                            inputBytes: Buffer.byteLength(JSON.stringify(argumentsValue), "utf8"),
+                            outputBytes: Buffer.byteLength(JSON.stringify(result), "utf8"),
+                            ...(count === undefined ? {} : { resultCount: count }),
+                            ...toolTelemetryMetrics(toolName, result),
+                        }, runtime, telemetryProject);
+                        const command = commandTelemetryDescriptor(toolName);
+                        if (command) {
+                            sessionCommandCallCount += 1;
+                            telemetryRecorder.record({
+                                event: "command_call",
+                                commandFamily: command.family,
+                                operation: command.operation,
+                                success: true,
+                                durationMs,
+                                outputBytes: Buffer.byteLength(JSON.stringify(result), "utf8"),
+                            }, runtime, telemetryProject);
+                        }
+                        mcpSuccess = true;
+                        return json({
+                            jsonrpc: "2.0",
+                            id: message.id,
+                            result,
+                        });
+                    }
+                    catch (error) {
+                        const durationMs = performance.now() - startedAt;
+                        const runtime = telemetryRuntime(params);
+                        const errorCategory = classifyTelemetryError(error);
+                        telemetryRecorder.record({
+                            event: "tool_call",
+                            tool: toolName,
+                            success: false,
+                            durationMs,
+                            inputBytes: Buffer.byteLength(JSON.stringify(argumentsValue), "utf8"),
+                            errorCategory,
+                        }, runtime, telemetryProject);
+                        const command = commandTelemetryDescriptor(toolName);
+                        if (command) {
+                            sessionCommandCallCount += 1;
+                            telemetryRecorder.record({
+                                event: "command_call",
+                                commandFamily: command.family,
+                                operation: command.operation,
+                                success: false,
+                                durationMs,
+                                errorCategory,
+                            }, runtime, telemetryProject);
+                        }
+                        throw error;
+                    }
                 }
                 case "resources/list": {
                     const resources = [
@@ -351,6 +646,7 @@ export function createMcpHandler(root, commandConfig = {}) {
                         })),
                     ];
                     const page = paginate(resources, params.cursor);
+                    mcpSuccess = true;
                     return json({
                         jsonrpc: "2.0",
                         id: message.id,
@@ -367,7 +663,8 @@ export function createMcpHandler(root, commandConfig = {}) {
                 case "resources/read": {
                     if (typeof params.uri !== "string" || params.uri.length === 0)
                         return jsonRpcError(message.id ?? null, -32602, "resources/read uri must be a non-empty string.", 400);
-                    if (params.uri === INSTRUCTIONS_URI)
+                    if (params.uri === INSTRUCTIONS_URI) {
+                        mcpSuccess = true;
                         return json({
                             jsonrpc: "2.0",
                             id: message.id,
@@ -377,7 +674,7 @@ export function createMcpHandler(root, commandConfig = {}) {
                                     {
                                         uri: INSTRUCTIONS_URI,
                                         mimeType: "text/markdown",
-                                        text: buildAgentInstructions(npmAllowed, allowedCommands),
+                                        text: buildAgentInstructions(npmAllowed, allowedCommands, blacklistedCommands, gitEnabled, await codeGraph.capability()),
                                     },
                                 ],
                                 ttlMs: 0,
@@ -385,7 +682,9 @@ export function createMcpHandler(root, commandConfig = {}) {
                                 _meta: SERVER_INFO_META,
                             },
                         });
-                    if (params.uri === CAPABILITIES_URI)
+                    }
+                    if (params.uri === CAPABILITIES_URI) {
+                        mcpSuccess = true;
                         return json({
                             jsonrpc: "2.0",
                             id: message.id,
@@ -395,7 +694,7 @@ export function createMcpHandler(root, commandConfig = {}) {
                                     {
                                         uri: CAPABILITIES_URI,
                                         mimeType: "application/json",
-                                        text: JSON.stringify(buildAgentCapabilities(npmAllowed, allowedCommands), null, 2),
+                                        text: JSON.stringify(buildAgentCapabilities(npmAllowed, allowedCommands, blacklistedCommands, gitEnabled), null, 2),
                                     },
                                 ],
                                 ttlMs: 0,
@@ -403,7 +702,9 @@ export function createMcpHandler(root, commandConfig = {}) {
                                 _meta: SERVER_INFO_META,
                             },
                         });
+                    }
                     const value = await readSkillResource(root, params.uri);
+                    mcpSuccess = true;
                     return json({
                         jsonrpc: "2.0",
                         id: message.id,
@@ -421,6 +722,7 @@ export function createMcpHandler(root, commandConfig = {}) {
                         return jsonRpcError(message.id ?? null, -32602, "resources/directory/read uri must be a non-empty string.", 400);
                     const resources = await readSkillDirectory(root, params.uri);
                     const page = paginate(resources, params.cursor);
+                    mcpSuccess = true;
                     return json({
                         jsonrpc: "2.0",
                         id: message.id,
@@ -436,6 +738,7 @@ export function createMcpHandler(root, commandConfig = {}) {
                 }
                 case "skills/list": {
                     const page = paginate(await listSkills(root), params.cursor);
+                    mcpSuccess = true;
                     return json({
                         jsonrpc: "2.0",
                         id: message.id,
@@ -451,11 +754,13 @@ export function createMcpHandler(root, commandConfig = {}) {
                 }
                 case "subscriptions/listen": {
                     const notifications = subscriptionNotifications(params.notifications);
+                    mcpSuccess = true;
                     return subscriptionResponse(message.id, notifications, subscriptions);
                 }
                 case "skills/get":
                     if (typeof params.uri !== "string" || params.uri.length === 0)
                         return jsonRpcError(message.id ?? null, -32602, "skills/get uri must be a non-empty string.", 400);
+                    mcpSuccess = true;
                     return json({
                         jsonrpc: "2.0",
                         id: message.id,
@@ -468,10 +773,12 @@ export function createMcpHandler(root, commandConfig = {}) {
                         },
                     });
                 default:
+                    telemetryRequestErrorCategory = "not_found";
                     return jsonRpcError(message.id ?? null, -32601, `Method not found: ${message.method}`, 404);
             }
         }
         catch (error) {
+            telemetryRequestErrorCategory = classifyTelemetryError(error);
             if (message.method === "tools/call")
                 return json({
                     jsonrpc: "2.0",
@@ -489,13 +796,35 @@ export function createMcpHandler(root, commandConfig = {}) {
             const code = message.method === "skills/get" ||
                 message.method === "resources/read" ||
                 message.method === "resources/directory/read" ||
-                message.method === "subscriptions/listen"
+                message.method === "subscriptions/listen" ||
+                message.method === "skills/list"
                 ? -32602
                 : -32603;
             return jsonRpcError(message.id ?? null, code, error instanceof Error ? error.message : String(error), code === -32602 ? 400 : 500);
         }
+        finally {
+            const requestDurationMs = performance.now() - requestStartedAt;
+            sessionActiveRequestDurationMs += requestDurationMs;
+            sessionLastActivityAt = performance.now();
+            recordMcpRequest();
+        }
     };
+    handler.telemetrySnapshot = () => telemetryRecorder.snapshot();
     handler.closeSubscriptions = () => {
+        if (!sessionRecorded && sessionRequestCount > 0 && telemetry.level !== "none") {
+            sessionRecorded = true;
+            telemetryRecorder.record({
+                event: "session",
+                wallClockDurationMs: Math.max(0, (sessionLastActivityAt ?? performance.now()) - (sessionStartedAt ?? performance.now())),
+                activeRequestDurationMs: sessionActiveRequestDurationMs,
+                idleGapDurationMs: Math.max(0, (sessionLastActivityAt ?? performance.now()) -
+                    (sessionStartedAt ?? performance.now()) -
+                    sessionActiveRequestDurationMs),
+                requestCount: sessionRequestCount,
+                toolCallCount: sessionToolCallCount,
+                commandCallCount: sessionCommandCallCount,
+            });
+        }
         for (const subscription of subscriptions) {
             writeSse(subscription.controller, {
                 jsonrpc: "2.0",
@@ -511,31 +840,61 @@ export function createMcpHandler(root, commandConfig = {}) {
             subscription.controller.close();
         }
         subscriptions.clear();
+        void codeGraph.close();
     };
     return handler;
 }
-function buildAgentInstructions(npmAllowed, allowedCommands) {
+async function availableTools(codeGraph, gitEnabled) {
+    const capability = await codeGraph.capability();
+    const tools = capability.status === "available" ||
+        capability.status === "startup_failed" ||
+        capability.status === "runtime_failed"
+        ? [...baseTools, codeGraphTool]
+        : baseTools;
+    return gitEnabled ? tools : tools.filter((item) => !item.name.startsWith("git_"));
+}
+function buildAgentInstructions(npmAllowed, allowedCommands, blacklistedCommands, gitEnabled, codeGraph) {
     const npm = npmAllowed.length ? npmAllowed.map((item) => `- ${item}`).join("\n") : "- none";
     const commands = allowedCommands.length
         ? allowedCommands.map((item) => `- ${item}`).join("\n")
         : "- none";
-    return `# Agent Dir operating instructions\n\nUse Agent Dir as the primary project interface. Optimize for correctness with the minimum necessary tool calls, filesystem reads, command output, and context.\n\n## Efficiency rules\n- Start with the narrowest operation that can answer the question. Do not dump the repository, large files, or full command output when a targeted operation is sufficient.\n- Prefer project_overview for initial orientation instead of list_files plus package/config reads.\n- Prefer find_files for known filename patterns and list_dirs for one directory. Use list_files only when recursive discovery is genuinely required.\n- Prefer search_code/search_files before reading files. Search first, then read only the relevant ranges.\n- Prefer find_symbol/find_definition/find_references for known symbols instead of scanning source files manually.\n- Prefer read_range for a bounded section. Use read_files to batch several already-identified files.\n- Prefer patch_files for targeted edits. Do not rewrite an entire file when a small exact replacement is sufficient.\n- Batch related reads, writes, patches, searches, and commands into one tool call when practical.\n- Keep maxResults and Git log limits small unless the initial result is insufficient.\n- Prefer dedicated Agent Dir tools over run_command_batch because dedicated tools return structured, bounded results.\n- Prefer diagnostics before expensive tests, linters, or typechecks when checking basic structural issues.\n- Run the narrowest relevant validation after a change; escalate only when required by the task or release workflow.\n- Before a broad Git diff, use git_status; then inspect only the relevant path or staged diff.\n- Never repeat a successful discovery/read just because another tool can provide the same information.\n\n## Preferred workflow\n1. Orient: project_overview.\n2. Locate: find_files/search_code/find_symbol/find_definition as appropriate.\n3. Read: read_range or batched read_files.\n4. Modify: patch_files for targeted changes; write_files for new/complete files.\n5. Validate: diagnostics first when applicable, then the narrowest relevant npm script.\n6. Review: git_status, then scoped git_diff when needed.\n\n## Execution policy\nAllowed npm scripts:\n${npm}\n\nAllowed executables:\n${commands}\n\nOnly use commands from the execution policy. Do not attempt to bypass it with shells or alternate executables.\n\n## Tool selection\n- Discovery: project_overview > find_files/list_dirs > list_files.\n- Code location: find_definition/find_symbol > search_code > broad file reads.\n- File reading: read_range > targeted read_files > broad recursive reads.\n- Editing: patch_files > write_files for complete files.\n- Validation: diagnostics > targeted npm script > full check/test.\n- Git inspection: git_status > scoped git_diff > full repository diff.\n\nThe execution policy and this guidance are generated from the running Agent Dir configuration; do not maintain a separate client-specific copy.`;
+    const blacklist = blacklistedCommands.length
+        ? blacklistedCommands.map((item) => `- ${item}`).join("\n")
+        : "- none";
+    const codeGraphSection = codeGraph.status === "available" ||
+        codeGraph.status === "startup_failed" ||
+        codeGraph.status === "runtime_failed"
+        ? "\n\n## CodeGraph\n- CodeGraph is an optional code-intelligence backend for this project.\n- Prefer `codegraph_explore` for structural, symbol, and code-flow questions when available.\n- Agent Dir pins CodeGraph to this project root; do not attempt to select another project.\n- Current status: " +
+            codeGraph.status +
+            (codeGraph.detail ? ` — ${codeGraph.detail}` : "") +
+            "."
+        : "";
+    return `# Agent Dir operating instructions\n\nUse Agent Dir as the primary project interface. Optimize for correctness with the minimum necessary tool calls, filesystem reads, command output, and context.\n\n## Efficiency rules\n- Start with the narrowest operation that can answer the question. Do not dump the repository, large files, or full command output when a targeted operation is sufficient.\n- Prefer project_context for initial orientation; it combines project structure, package metadata, and execution policy in one call. Use project_overview when package metadata is unnecessary.\n- Prefer find_files for known filename patterns and list_dirs for one directory. Use list_files only when recursive discovery is genuinely required.\n- Prefer search_code/search_files before reading files. Search first, then read only the relevant ranges. Use read_relevant when one call can locate and return the needed source context.\n- Prefer find_symbol/find_definition/find_references for known symbols instead of scanning source files manually.\n- Prefer read_range for a bounded section. Use read_files to batch several already-identified files.\n- Prefer patch_files for targeted edits. Do not rewrite an entire file when a small exact replacement is sufficient.\n- Batch related reads, writes, patches, searches, and commands into one tool call when practical.\n- Keep maxResults and Git log limits small unless the initial result is insufficient.\n- Prefer dedicated Agent Dir tools over run_command_batch because dedicated tools return structured, bounded results.\n- Prefer diagnostics before expensive tests, linters, or typechecks when checking basic structural issues.\n- Run the narrowest relevant validation after a change; escalate only when required by the task or release workflow.\n- Before a broad Git diff, use git_status; then inspect only the relevant path or staged diff.\n- Never repeat a successful discovery/read just because another tool can provide the same information.\n\n## Preferred workflow\n1. Orient: project_overview.\n2. Locate: find_files/search_code/find_symbol/find_definition as appropriate.\n3. Read: read_range or batched read_files.\n4. Modify: patch_files for targeted changes; write_files for new/complete files.\n5. Validate: diagnostics first when applicable, then the narrowest relevant npm script.\n6. Review: git_status, then scoped git_diff when needed.\n\n## Execution policy\nAllowed npm scripts:\n${npm}\n\nAllowed executables:\n${commands}\n\nBlacklisted command prefixes:\n${blacklist}\n\nOnly use commands from the execution policy. A blacklisted command prefix overrides an allowed executable. Do not attempt to bypass it with shells or alternate executables.\n\n## Git capability\nDedicated Git MCP tools are ${gitEnabled ? "enabled" : "disabled"} for this profile.\n\n## Tool selection\n- Discovery: project_context > locate > project_overview > find_files/list_dirs > list_files.\n- Code location: inspect_symbol > find_definition/find_symbol > locate > search_code > broad file reads.\n- File reading: read_relevant > read_range > targeted read_files > broad recursive reads.\n- Editing: patch_files > write_files for complete files.\n- Validation: diagnostics > targeted npm script > full check/test.\n- Git inspection: git_changes > git_status > scoped git_diff > full repository diff.\n\nThe execution policy and this guidance are generated from the running Agent Dir configuration; do not maintain a separate client-specific copy.${codeGraphSection}`;
 }
-function buildAgentCapabilities(npmAllowed, allowedCommands) {
+function buildAgentCapabilities(npmAllowed, allowedCommands, blacklistedCommands, gitEnabled) {
     return {
         version: packageVersion,
-        tools: baseTools.map((item) => item.name),
+        tools: baseTools
+            .filter((item) => gitEnabled || !item.name.startsWith("git_"))
+            .map((item) => item.name),
         resources: [INSTRUCTIONS_URI, CAPABILITIES_URI],
-        execution: { npmScripts: [...npmAllowed], commands: [...allowedCommands] },
+        execution: {
+            npmScripts: [...npmAllowed],
+            commands: [...allowedCommands],
+            blacklistedCommands: [...blacklistedCommands],
+            git: gitEnabled,
+        },
         efficiency: {
             preferred: {
-                orientation: "project_overview",
+                orientation: "project_context",
+                focusedReading: "read_relevant",
+                changeReview: "git_changes",
                 discovery: ["find_files", "list_dirs", "search_code"],
                 symbolNavigation: ["find_definition", "find_symbol", "find_references"],
                 reading: ["read_range", "read_files"],
-                editing: ["patch_files", "write_files"],
-                validation: ["diagnostics", "targeted npm script"],
-                gitInspection: ["git_status", "git_diff", "git_log"],
+                editing: ["apply_changes", "patch_files", "write_files"],
+                validation: ["validate", "diagnostics", "targeted npm script"],
+                gitInspection: ["git_changes", "git_status", "git_diff", "git_log"],
             },
             avoid: [
                 "recursive discovery when targeted search is enough",
@@ -554,37 +913,105 @@ function capabilities() {
         extensions: { "io.modelcontextprotocol/skills": { directoryRead: true } },
     };
 }
-async function callTool(name, args, root, npmAllowed, allowedCommands, notify, signal) {
+async function callTool(name, args, root, npmAllowed, allowedCommands, blacklistedCommands, gitEnabled, notify, signal, codeGraph) {
     let structuredContent;
+    if (name === "codegraph_explore") {
+        if (!codeGraph)
+            throw new Error("CodeGraph integration is unavailable.");
+        if (typeof args.query !== "string" || args.query.trim().length === 0)
+            throw new Error("query must be a non-empty string.");
+        if (args.maxFiles !== undefined &&
+            (!Number.isInteger(args.maxFiles) || Number(args.maxFiles) < 1 || Number(args.maxFiles) > 100))
+            throw new Error("maxFiles must be an integer between 1 and 100.");
+        return await codeGraph.explore(args.query, args.maxFiles === undefined ? undefined : Number(args.maxFiles));
+    }
+    if (name.startsWith("git_") && !gitEnabled) {
+        throw new Error("Dedicated Git tools are disabled for this profile.");
+    }
     switch (name) {
-        case "list_files":
-            structuredContent = await listFiles(root);
+        case "list_files": {
+            const items = await listFiles(root);
+            structuredContent = boundedItems(items, outputBytesArg(args.maxBytes)).items;
             break;
-        case "list_dirs":
-            structuredContent = await listDirs(root, stringArray(args.paths, "paths"));
+        }
+        case "list_dirs": {
+            const items = await listDirs(root, stringArray(args.paths, "paths"));
+            structuredContent = boundedItems(items, outputBytesArg(args.maxBytes)).items;
             break;
-        case "read_range":
-            structuredContent = await readRange(root, String(args.path), Number(args.startLine), Number(args.endLine));
+        }
+        case "read_range": {
+            const result = await readRange(root, String(args.path), Number(args.startLine), Number(args.endLine));
+            const bounded = truncateText(result.content, outputBytesArg(args.maxBytes));
+            structuredContent = { ...result, content: bounded.text };
             break;
-        case "read_files":
-            structuredContent = await Promise.all(stringArray(args.paths, "paths").map(async (p) => ({
-                path: p,
-                content: await readFile(root, p),
-            })));
+        }
+        case "read_files": {
+            const maxBytes = outputBytesArg(args.maxBytes);
+            let remaining = maxBytes;
+            const output = [];
+            for (const p of stringArray(args.paths, "paths")) {
+                const content = await readFile(root, p);
+                const bounded = truncateText(content, remaining);
+                output.push({ path: p, content: bounded.text });
+                remaining -= Buffer.byteLength(bounded.text, "utf8");
+                if (bounded.truncated || remaining <= 0)
+                    break;
+            }
+            structuredContent = output;
+            break;
+        }
+        case "apply_changes": {
+            const changes = objectArray(args.changes, "changes").map((change) => {
+                const kind = String(change.kind);
+                if (kind !== "write" && kind !== "patch" && kind !== "delete")
+                    throw new Error("Change kind must be write, patch, or delete.");
+                if (kind === "write" && typeof change.content !== "string")
+                    throw new Error("write changes require content.");
+                if (kind === "patch" && !Array.isArray(change.patches))
+                    throw new Error("patch changes require patches.");
+                return {
+                    kind,
+                    path: String(change.path),
+                    ...(kind === "write" ? { content: String(change.content) } : {}),
+                    ...(kind === "patch"
+                        ? {
+                            patches: objectArray(change.patches, "patches").map((patch) => ({
+                                search: String(patch.search),
+                                replace: String(patch.replace),
+                                ...(patch.count === undefined ? {} : { count: Number(patch.count) }),
+                            })),
+                        }
+                        : {}),
+                };
+            });
+            const dryRun = args.dryRun === true;
+            const affected = [...new Set(changes.map((change) => change.path))];
+            const before = new Map();
+            for (const p of affected)
+                before.set(p, await skillResourceUrisForPath(root, p));
+            structuredContent = await applyFileChanges(root, changes, dryRun);
+            if (!dryRun)
+                for (const p of affected)
+                    await notifyResourceChange(notify, root, p, before.get(p) ?? []);
             break;
+        }
         case "write_files": {
+            const dryRun = args.dryRun === true;
             const output = [];
             for (const file of objectArray(args.files, "files")) {
                 const p = String(file.path);
                 const before = await skillResourceUrisForPath(root, p);
-                await writeFile(root, p, String(file.content));
-                await notifyResourceChange(notify, root, p, before);
-                output.push({ path: p, written: true });
+                if (!dryRun) {
+                    await writeFile(root, p, String(file.content));
+                    await notifyResourceChange(notify, root, p, before);
+                }
+                output.push({ path: p, written: true, ...(dryRun ? { dryRun: true } : {}) });
             }
             structuredContent = output;
             break;
         }
         case "patch_files": {
+            const dryRun = args.dryRun === true;
             const files = objectArray(args.files, "files").map((file) => ({
                 path: String(file.path),
                 patches: objectArray(file.patches, "patches").map((p) => ({
@@ -596,70 +1023,331 @@ async function callTool(name, args, root, npmAllowed, allowedCommands, notify, s
             const before = new Map();
             for (const file of files)
                 before.set(file.path, await skillResourceUrisForPath(root, file.path));
-            structuredContent = await patchFiles(root, files);
-            for (const file of files)
-                await notifyResourceChange(notify, root, file.path, before.get(file.path) ?? []);
+            if (dryRun) {
+                structuredContent = await patchFilesDryRun(root, files);
+            }
+            else {
+                structuredContent = await patchFiles(root, files);
+            }
+            const maxBytes = outputBytesArg(args.maxBytes);
+            if (Array.isArray(structuredContent)) {
+                structuredContent = boundedItems(structuredContent.map((item) => {
+                    if (!isRecord(item) || typeof item.content !== "string")
+                        return item;
+                    return { ...item, content: truncateText(item.content, maxBytes).text };
+                }), maxBytes).items;
+            }
+            if (!dryRun) {
+                for (const file of files)
+                    await notifyResourceChange(notify, root, file.path, before.get(file.path) ?? []);
+            }
             break;
         }
         case "delete_files": {
+            const dryRun = args.dryRun === true;
             const output = [];
             for (const p of stringArray(args.paths, "paths")) {
                 const before = await skillResourceUrisForPath(root, p);
-                await deleteFile(root, p);
-                await notifyResourceChange(notify, root, p, before);
-                output.push({ path: p, deleted: true });
+                if (!dryRun) {
+                    await deleteFile(root, p);
+                    await notifyResourceChange(notify, root, p, before);
+                }
+                output.push({ path: p, deleted: true, ...(dryRun ? { dryRun: true } : {}) });
             }
             structuredContent = output;
             break;
         }
         case "search_files":
-            structuredContent = await searchFiles(root, String(args.query), Boolean(args.regex), numberArg(args.maxResults, 200, 1000));
+            structuredContent = await searchFiles(root, String(args.query), Boolean(args.regex), numberArg(args.maxResults, 200, 1000), outputBytesArg(args.maxBytes));
             break;
         case "find_files":
-            structuredContent = await findFiles(root, String(args.pattern), numberArg(args.maxResults, 200, 1000));
+            structuredContent = boundedItems(await findFiles(root, String(args.pattern), numberArg(args.maxResults, 200, 1000)), outputBytesArg(args.maxBytes)).items;
             break;
         case "search_code":
-            structuredContent = await searchCode(root, String(args.query), Boolean(args.regex), numberArg(args.maxResults, 200, 1000));
+            structuredContent = await searchCode(root, String(args.query), Boolean(args.regex), numberArg(args.maxResults, 200, 1000), outputBytesArg(args.maxBytes));
             break;
         case "find_symbol":
-            structuredContent = await findSymbol(root, String(args.symbol), numberArg(args.maxResults, 100, 500));
+            structuredContent = await findSymbol(root, String(args.symbol), numberArg(args.maxResults, 100, 500), outputBytesArg(args.maxBytes));
             break;
         case "find_definition":
-            structuredContent = await findDefinition(root, String(args.symbol), numberArg(args.maxResults, 100, 500));
+            structuredContent = await findDefinition(root, String(args.symbol), numberArg(args.maxResults, 100, 500), outputBytesArg(args.maxBytes));
             break;
         case "find_references":
-            structuredContent = await findReferences(root, String(args.symbol), numberArg(args.maxResults, 200, 1000));
+            structuredContent = await findReferences(root, String(args.symbol), numberArg(args.maxResults, 200, 1000), outputBytesArg(args.maxBytes));
             break;
         case "find_imports":
-            structuredContent = await findImports(root, numberArg(args.maxResults, 200, 1000));
+            structuredContent = await findImports(root, numberArg(args.maxResults, 200, 1000), outputBytesArg(args.maxBytes));
             break;
         case "find_exports":
-            structuredContent = await findExports(root, numberArg(args.maxResults, 200, 1000));
+            structuredContent = await findExports(root, numberArg(args.maxResults, 200, 1000), outputBytesArg(args.maxBytes));
             break;
         case "git_status":
-            structuredContent = await gitStatus(root);
+            structuredContent = boundCommandResult(await gitStatus(root), outputBytesArg(args.maxBytes));
             break;
         case "git_stage":
-            structuredContent = await gitStage(root, stringArray(args.paths, "paths"));
+            structuredContent = boundCommandResult(await gitStage(root, stringArray(args.paths, "paths")), outputBytesArg(args.maxBytes));
             break;
         case "git_unstage":
-            structuredContent = await gitUnstage(root, stringArray(args.paths, "paths"));
+            structuredContent = boundCommandResult(await gitUnstage(root, stringArray(args.paths, "paths")), outputBytesArg(args.maxBytes));
             break;
         case "git_commit":
-            structuredContent = await gitCommit(root, String(args.message));
+            structuredContent = boundCommandResult(await gitCommit(root, String(args.message)), outputBytesArg(args.maxBytes));
             break;
         case "git_restore":
-            structuredContent = await gitRestore(root, stringArray(args.paths, "paths"));
+            structuredContent = boundCommandResult(await gitRestore(root, stringArray(args.paths, "paths")), outputBytesArg(args.maxBytes));
             break;
         case "git_push":
-            structuredContent = await gitPush(root, args.remote === undefined ? undefined : String(args.remote), args.branch === undefined ? undefined : String(args.branch));
+            structuredContent = boundCommandResult(await gitPush(root, args.remote === undefined ? undefined : String(args.remote), args.branch === undefined ? undefined : String(args.branch)), outputBytesArg(args.maxBytes));
             break;
         case "git_diff":
-            structuredContent = await gitDiff(root, Boolean(args.staged), args.path === undefined ? undefined : String(args.path));
+            structuredContent = boundCommandResult(await gitDiff(root, Boolean(args.staged), args.path === undefined ? undefined : String(args.path)), outputBytesArg(args.maxBytes));
             break;
         case "git_log":
-            structuredContent = await gitLog(root, numberArg(args.limit, 20, 200), args.path === undefined ? undefined : String(args.path));
+            structuredContent = boundCommandResult(await gitLog(root, numberArg(args.limit, 20, 200), args.path === undefined ? undefined : String(args.path)), outputBytesArg(args.maxBytes));
+            break;
+        case "locate": {
+            const query = String(args.query);
+            const kind = typeof args.kind === "string" ? args.kind : "auto";
+            const regex = args.regex === true;
+            const maxResults = numberArg(args.maxResults, 20, 100);
+            const resolvedKind = kind === "auto"
+                ? /[*?]/.test(query)
+                    ? "file"
+                    : /\.(ts|tsx|js|jsx|py|go|rs|java|json|md|yml|yaml|css|html)$/.test(query)
+                        ? "file"
+                        : "code"
+                : kind;
+            const items = resolvedKind === "file"
+                ? await findFiles(root, query, maxResults)
+                : resolvedKind === "text"
+                    ? await searchFiles(root, query, regex, maxResults)
+                    : await searchCode(root, query, regex, maxResults);
+            const bounded = boundedItems(items, outputBytesArg(args.maxBytes));
+            structuredContent = {
+                query,
+                kind: resolvedKind,
+                items: bounded.items,
+                count: bounded.items.length,
+                truncated: bounded.truncated || items.length >= maxResults,
+            };
+            break;
+        }
+        case "inspect_symbol": {
+            const symbol = String(args.symbol);
+            const contextLines = args.contextLines === undefined ? 3 : Number(args.contextLines);
+            if (!Number.isInteger(contextLines) || contextLines < 0 || contextLines > 20)
+                throw new Error("contextLines must be an integer between 0 and 20.");
+            const maxResults = numberArg(args.maxResults, 5, 20);
+            const maxBytes = outputBytesArg(args.maxBytes);
+            const definitions = await findDefinition(root, symbol, maxResults, maxBytes);
+            const definitionContext = await Promise.all(definitions.map(async (definition) => {
+                const range = await readRange(root, definition.path, Math.max(1, definition.line - contextLines), definition.line + contextLines);
+                return { ...definition, context: range.content };
+            }));
+            const references = args.includeReferences === true
+                ? await findReferences(root, symbol, maxResults, maxBytes)
+                : undefined;
+            const result = {
+                symbol,
+                definitions: definitionContext,
+                ...(references ? { references } : {}),
+            };
+            const bounded = truncateText(JSON.stringify(result), maxBytes);
+            structuredContent = bounded.truncated
+                ? { symbol, result: bounded.text, truncated: true }
+                : result;
+            break;
+        }
+        case "inspect": {
+            const target = String(args.target);
+            const requestedKind = typeof args.kind === "string" ? args.kind : "auto";
+            const contextLines = args.contextLines === undefined ? 3 : Number(args.contextLines);
+            if (!Number.isInteger(contextLines) || contextLines < 0 || contextLines > 20)
+                throw new Error("contextLines must be an integer between 0 and 20.");
+            const maxResults = numberArg(args.maxResults, 5, 20);
+            const maxBytes = outputBytesArg(args.maxBytes);
+            let kind = requestedKind;
+            if (kind === "auto") {
+                try {
+                    await readFile(root, target);
+                    kind = "file";
+                }
+                catch {
+                    kind = /[*?]/.test(target) ? "code" : "symbol";
+                }
+            }
+            if (kind === "file") {
+                const content = await readFile(root, target);
+                const boundedContent = truncateText(content, Math.max(1, maxBytes - 128));
+                const result = {
+                    target,
+                    kind,
+                    path: target,
+                    content: boundedContent.text,
+                    truncated: boundedContent.truncated,
+                };
+                structuredContent = result;
+                break;
+            }
+            if (kind === "symbol") {
+                const definitions = await findDefinition(root, target, maxResults, maxBytes);
+                const definitionsWithContext = await Promise.all(definitions.map(async (definition) => {
+                    const range = await readRange(root, definition.path, Math.max(1, definition.line - contextLines), definition.line + contextLines);
+                    return { ...definition, context: range.content };
+                }));
+                const references = args.includeReferences === true
+                    ? await findReferences(root, target, maxResults, maxBytes)
+                    : undefined;
+                const result = {
+                    target,
+                    kind,
+                    definitions: definitionsWithContext,
+                    ...(references ? { references } : {}),
+                };
+                const bounded = truncateText(JSON.stringify(result), maxBytes);
+                structuredContent = bounded.truncated
+                    ? { target, kind, result: bounded.text, truncated: true }
+                    : result;
+                break;
+            }
+            const matches = await searchCode(root, target, false, maxResults, maxBytes);
+            const relevant = await Promise.all(matches.map(async (match) => {
+                const range = await readRange(root, match.path, Math.max(1, match.line - contextLines), match.line + contextLines);
+                return {
+                    ...match,
+                    context: range.content,
+                    startLine: range.startLine,
+                    endLine: range.endLine,
+                };
+            }));
+            const bounded = boundedItems(relevant, maxBytes);
+            structuredContent = {
+                target,
+                kind: "code",
+                matches: bounded.items,
+                count: bounded.items.length,
+                truncated: bounded.truncated || relevant.length >= maxResults,
+            };
+            break;
+        }
+        case "project_context": {
+            const overview = await projectOverview(root);
+            let pkg = { path: "package.json", exists: false };
+            try {
+                const packageJson = JSON.parse(await readFile(root, "package.json"));
+                pkg = {
+                    path: "package.json",
+                    name: packageJson.name ?? null,
+                    version: packageJson.version ?? null,
+                    description: packageJson.description ?? null,
+                    packageManager: packageJson.packageManager ?? null,
+                    scripts: packageJson.scripts ?? {},
+                };
+            }
+            catch {
+                // Package metadata is optional; project context remains useful without it.
+            }
+            const maxBytes = outputBytesArg(args.maxBytes);
+            const bounded = truncateText(JSON.stringify({
+                ...overview,
+                package: pkg,
+                execution: { npmScripts: [...npmAllowed], commands: [...allowedCommands] },
+            }), maxBytes);
+            structuredContent = bounded.truncated
+                ? { result: bounded.text, truncated: true }
+                : JSON.parse(bounded.text);
             break;
+        }
+        case "read_relevant": {
+            const query = String(args.query);
+            const contextLines = args.contextLines === undefined ? 3 : Number(args.contextLines);
+            if (!Number.isInteger(contextLines) || contextLines < 0 || contextLines > 20)
+                throw new Error("contextLines must be an integer between 0 and 20.");
+            const maxResults = numberArg(args.maxResults, 5, 20);
+            const matches = await searchCode(root, query, Boolean(args.regex), maxResults, outputBytesArg(args.maxBytes));
+            const relevant = await Promise.all(matches.map(async (match) => {
+                const range = await readRange(root, match.path, Math.max(1, match.line - contextLines), match.line + contextLines);
+                return {
+                    ...match,
+                    context: range.content,
+                    startLine: range.startLine,
+                    endLine: range.endLine,
+                };
+            }));
+            const maxBytes = outputBytesArg(args.maxBytes);
+            const bounded = boundedItems(relevant, Math.max(1, maxBytes - 128));
+            const result = {
+                query,
+                matches: bounded.items,
+                count: relevant.length,
+                truncated: bounded.truncated || relevant.length >= maxResults,
+            };
+            structuredContent = result;
+            break;
+        }
+        case "validate": {
+            const level = typeof args.level === "string" ? args.level : "diagnostics";
+            const maxResults = numberArg(args.maxResults, 200, 1000);
+            const maxBytes = outputBytesArg(args.maxBytes);
+            const diagnosticItems = await diagnostics(root, maxResults);
+            const scripts = level === "diagnostics"
+                ? []
+                : args.scripts !== undefined
+                    ? stringArray(args.scripts, "scripts")
+                    : level === "full"
+                        ? ["check", "test"].filter((script) => npmAllowed.includes(script))
+                        : [];
+            const checks = [
+                {
+                    kind: "diagnostics",
+                    ok: !diagnosticItems.some((item) => item.severity === "error"),
+                    count: diagnosticItems.length,
+                    issues: boundedItems(diagnosticItems, maxBytes).items,
+                },
+            ];
+            for (const script of scripts) {
+                const result = await runNpm(root, script, 120000, npmAllowed, signal);
+                checks.push({
+                    kind: "npm",
+                    script,
+                    ok: result.exitCode === 0,
+                    result,
+                });
+                if (result.exitCode !== 0)
+                    break;
+            }
+            structuredContent = {
+                level,
+                ok: checks.every((check) => check.ok === true),
+                checks,
+                scriptsRequested: scripts,
+            };
+            break;
+        }
+        case "git_changes": {
+            const status = await gitStatus(root);
+            const includeDiff = Boolean(args.includeDiff);
+            const path = args.path === undefined ? undefined : String(args.path);
+            const maxBytes = outputBytesArg(args.maxBytes);
+            const diff = includeDiff ? await gitDiff(root, false, path) : undefined;
+            const statusBytes = Buffer.byteLength(JSON.stringify(status), "utf8");
+            const diffBudget = Math.max(0, maxBytes - statusBytes - 64);
+            const boundedDiff = diff ? truncateText(diff.stdout, diffBudget) : undefined;
+            const result = {
+                status,
+                ...(diff
+                    ? {
+                        diff: {
+                            ...diff,
+                            stdout: boundedDiff?.text ?? "",
+                            truncated: boundedDiff?.truncated ?? false,
+                        },
+                    }
+                    : {}),
+            };
+            structuredContent = result;
+            break;
+        }
         case "project_overview":
             structuredContent = await projectOverview(root);
             break;
@@ -670,13 +1358,14 @@ async function callTool(name, args, root, npmAllowed, allowedCommands, notify, s
             structuredContent = {
                 npmScripts: [...npmAllowed],
                 commands: [...allowedCommands],
+                blacklistedCommands: [...blacklistedCommands],
             };
             break;
         case "file_info":
             structuredContent = await fileInfo(root, String(args.path));
             break;
         case "diagnostics":
-            structuredContent = await diagnostics(root, numberArg(args.maxResults, 200, 1000));
+            structuredContent = boundedItems(await diagnostics(root, numberArg(args.maxResults, 200, 1000)), outputBytesArg(args.maxBytes)).items;
             break;
         case "run_npm_batch": {
             const output = [];
@@ -686,18 +1375,52 @@ async function callTool(name, args, root, npmAllowed, allowedCommands, notify, s
                 if (value.exitCode !== 0)
                     break;
             }
-            structuredContent = output;
+            const maxBytes = outputBytesArg(args.maxBytes);
+            const boundedOutput = [];
+            let remaining = maxBytes - 2;
+            for (const item of output) {
+                const separatorBytes = boundedOutput.length ? 1 : 0;
+                if (remaining <= separatorBytes)
+                    break;
+                const budget = remaining - separatorBytes;
+                const bounded = boundCommandResult(item, budget);
+                const boundedBytes = Buffer.byteLength(JSON.stringify(bounded), "utf8");
+                if (boundedBytes > budget)
+                    break;
+                boundedOutput.push(bounded);
+                remaining -= separatorBytes + boundedBytes;
+                if (remaining <= 0)
+                    break;
+            }
+            structuredContent = boundedOutput;
             break;
         }
         case "run_command_batch": {
             const output = [];
             for (const item of objectArray(args.commands, "commands")) {
-                const value = await runCommand(root, String(item.command), Array.isArray(item.args) ? item.args.map(String) : [], allowedCommands, 120000, signal);
+                const value = await runCommand(root, String(item.command), Array.isArray(item.args) ? item.args.map(String) : [], allowedCommands, blacklistedCommands, 120000, signal);
                 output.push(value);
                 if (value.exitCode !== 0)
                     break;
             }
-            structuredContent = output;
+            const maxBytes = outputBytesArg(args.maxBytes);
+            const boundedOutput = [];
+            let remaining = maxBytes - 2;
+            for (const item of output) {
+                const separatorBytes = boundedOutput.length ? 1 : 0;
+                if (remaining <= separatorBytes)
+                    break;
+                const budget = remaining - separatorBytes;
+                const bounded = boundCommandResult(item, budget);
+                const boundedBytes = Buffer.byteLength(JSON.stringify(bounded), "utf8");
+                if (boundedBytes > budget)
+                    break;
+                boundedOutput.push(bounded);
+                remaining -= separatorBytes + boundedBytes;
+                if (remaining <= 0)
+                    break;
+            }
+            structuredContent = boundedOutput;
             break;
         }
         default:
@@ -814,6 +1537,114 @@ function completeToolResult(structuredContent) {
         _meta: SERVER_INFO_META,
     };
 }
+function telemetryRuntime(params) {
+    const clientInfo = isRecord(params.clientInfo) ? params.clientInfo : undefined;
+    return {
+        agentDirVersion: packageVersion,
+        nodeMajor: Number(process.versions.node.split(".")[0]),
+        os: process.platform === "darwin"
+            ? "macos"
+            : process.platform === "linux"
+                ? "linux"
+                : process.platform === "win32"
+                    ? "windows"
+                    : "other",
+        arch: process.arch,
+        ...(typeof clientInfo?.name === "string" ? { mcpClientName: clientInfo.name } : {}),
+        ...(typeof clientInfo?.version === "string" ? { mcpClientVersion: clientInfo.version } : {}),
+    };
+}
+function toolTelemetryMetrics(toolName, result) {
+    const structured = result.structuredContent;
+    if (!Array.isArray(structured) && !isRecord(structured))
+        return {};
+    const paths = new Set();
+    let truncated = false;
+    let paginated = false;
+    const visit = (value) => {
+        if (!isRecord(value))
+            return;
+        if (typeof value.path === "string")
+            paths.add(value.path);
+        if (value.truncated === true)
+            truncated = true;
+        if (value.nextCursor !== undefined)
+            paginated = true;
+        for (const child of Object.values(value)) {
+            if (Array.isArray(child))
+                for (const item of child)
+                    visit(item);
+            else if (isRecord(child))
+                visit(child);
+        }
+    };
+    visit(structured);
+    return {
+        ...(paths.size > 0 && /^(write|patch|delete|read|file|git_changes|inspect)/.test(toolName)
+            ? { affectedFiles: paths.size }
+            : {}),
+        ...(truncated ? { truncated: true } : {}),
+        ...(paginated ? { paginated: true } : {}),
+    };
+}
+function commandTelemetryDescriptor(toolName) {
+    if (toolName === "run_npm_batch")
+        return { family: "npm", operation: "batch" };
+    if (toolName === "run_command_batch")
+        return { family: "command", operation: "batch" };
+    if (toolName === "validate")
+        return { family: "npm", operation: "validate" };
+    if (toolName.startsWith("git_"))
+        return { family: "git", operation: toolName.slice("git_".length) };
+    return undefined;
+}
+async function buildTelemetryProjectContext(root, codeGraph) {
+    const overview = await projectOverview(root);
+    const extension = overview.languages[0]?.extension;
+    const language = extension === ".ts" || extension === ".tsx"
+        ? "typescript"
+        : extension === ".js" || extension === ".jsx"
+            ? "javascript"
+            : extension === ".py"
+                ? "python"
+                : extension === ".go"
+                    ? "go"
+                    : extension === ".rs"
+                        ? "rust"
+                        : extension === ".java"
+                            ? "java"
+                            : undefined;
+    const packageManager = overview.packageManagers[0];
+    const projectSize = overview.files < 100 ? "small" : overview.files < 1000 ? "medium" : "large";
+    const capability = await codeGraph.capability();
+    return {
+        ...(language ? { language } : {}),
+        ...(packageManager && ["npm", "pnpm", "yarn", "bun"].includes(packageManager)
+            ? { packageManager: packageManager }
+            : {}),
+        hasGit: overview.git.available,
+        hasCodegraph: capability.installed && capability.indexed,
+        projectSize,
+    };
+}
+function resultCount(result) {
+    const structured = result.structuredContent;
+    return Array.isArray(structured) ? structured.length : undefined;
+}
+function classifyTelemetryError(error) {
+    const message = error instanceof Error ? error.message.toLowerCase() : "";
+    if (message.includes("not found"))
+        return "not_found";
+    if (message.includes("invalid") || message.includes("must be"))
+        return "invalid_input";
+    if (message.includes("blocked") || message.includes("not allowed"))
+        return "authorization";
+    if (message.includes("timeout") || message.includes("timed out"))
+        return "timeout";
+    if (message.includes("authentication") || message.includes("unauthorized"))
+        return "authentication";
+    return "execution";
+}
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -830,6 +1661,69 @@ function objectArray(value, name) {
         throw new Error(`${name} must be an array of objects.`);
     return value;
 }
+function outputBytesArg(value) {
+    const result = value === undefined ? DEFAULT_OUTPUT_BYTES : Number(value);
+    if (!Number.isInteger(result) || result < 1024 || result > 1_000_000)
+        throw new Error("maxBytes must be an integer between 1024 and 1000000.");
+    return result;
+}
+function truncateText(value, maxBytes) {
+    if (Buffer.byteLength(value, "utf8") <= maxBytes)
+        return { text: value, truncated: false };
+    if (maxBytes <= 32)
+        return { text: "", truncated: true };
+    const buffer = Buffer.from(value, "utf8");
+    return {
+        text: `${buffer.subarray(0, Math.max(0, maxBytes - 32)).toString("utf8")}\n…[truncated]`,
+        truncated: true,
+    };
+}
+function boundCommandResult(value, maxBytes) {
+    if (!isRecord(value))
+        return value;
+    const command = typeof value.command === "string" ? value.command : "";
+    const stdout = typeof value.stdout === "string" ? value.stdout : "";
+    const stderr = typeof value.stderr === "string" ? value.stderr : "";
+    let commandBudget = Buffer.byteLength(command, "utf8");
+    let stdoutBudget = Buffer.byteLength(stdout, "utf8");
+    let stderrBudget = Buffer.byteLength(stderr, "utf8");
+    const candidate = () => ({
+        ...value,
+        command: truncateText(command, commandBudget).text,
+        stdout: truncateText(stdout, stdoutBudget).text,
+        stderr: truncateText(stderr, stderrBudget).text,
+    });
+    let result = candidate();
+    while (Buffer.byteLength(JSON.stringify(result), "utf8") > maxBytes &&
+        (commandBudget > 0 || stdoutBudget > 0 || stderrBudget > 0)) {
+        const excess = Buffer.byteLength(JSON.stringify(result), "utf8") - maxBytes;
+        if (stdoutBudget >= stderrBudget && stdoutBudget > 0)
+            stdoutBudget = Math.max(0, stdoutBudget - excess);
+        else if (stderrBudget > 0)
+            stderrBudget = Math.max(0, stderrBudget - excess);
+        else
+            commandBudget = Math.max(0, commandBudget - excess);
+        result = candidate();
+    }
+    if (Buffer.byteLength(JSON.stringify(result), "utf8") <= maxBytes)
+        return result;
+    return { ...value, command: truncateText(command, commandBudget).text, stdout: "", stderr: "" };
+}
+function boundedItems(items, maxBytes) {
+    const selected = [];
+    let bytes = 2;
+    for (const item of items) {
+        const itemBytes = Buffer.byteLength(JSON.stringify(item), "utf8");
+        const separatorBytes = selected.length ? 1 : 0;
+        if (selected.length && bytes + separatorBytes + itemBytes > maxBytes)
+            break;
+        if (!selected.length && bytes + itemBytes > maxBytes)
+            break;
+        selected.push(item);
+        bytes += separatorBytes + itemBytes;
+    }
+    return { items: selected, truncated: selected.length < items.length };
+}
 function numberArg(value, fallback, max) {
     const result = value === undefined ? fallback : Number(value);
     if (!Number.isInteger(result) || result < 1 || result > max)
@@ -862,11 +1756,40 @@ function decodeCursor(value) {
     catch {
         throw new Error("Invalid pagination cursor.");
     }
+    if (!/^(?:0|[1-9]\d*)$/.test(decoded))
+        throw new Error("Invalid pagination cursor.");
     const offset = Number(decoded);
     if (!Number.isSafeInteger(offset) || offset < 0)
         throw new Error("Invalid pagination cursor.");
     return offset;
 }
+async function patchFilesDryRun(root, files) {
+    return Promise.all(files.map(async ({ path: relativePath, patches }) => {
+        let content = await readFile(root, relativePath);
+        for (const patch of patches) {
+            if (!patch.search)
+                throw new Error("Patch search text cannot be empty.");
+            const occurrences = content.split(patch.search).length - 1;
+            const count = patch.count ?? 1;
+            if (occurrences === 0)
+                throw new Error(`Patch text was not found in '${relativePath}'.`);
+            if (!Number.isInteger(count) || count < 1)
+                throw new Error("Patch count must be a positive integer.");
+            if (occurrences < count)
+                throw new Error(`Patch text occurs ${occurrences} time(s), but ${count} replacement(s) were requested.`);
+            let offset = 0;
+            for (let index = 0; index < count; index += 1) {
+                const position = content.indexOf(patch.search, offset);
+                content =
+                    content.slice(0, position) +
+                        patch.replace +
+                        content.slice(position + patch.search.length);
+                offset = position + patch.replace.length;
+            }
+        }
+        return { path: relativePath, applied: patches.length, content, dryRun: true };
+    }));
+}
 async function notifyResourceChange(notify, root, pathValue, before) {
     const after = await skillResourceUrisForPath(root, pathValue);
     if (before.length === 0 && after.length === 0)