agent-dir 0.2.0 → 0.3.1

package/dist/src/mcp.js

@@ -1,5 +1,7 @@
+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";
@@ -327,10 +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) {
@@ -361,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 &&
@@ -385,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,
@@ -401,30 +474,46 @@ export function createMcpHandler(root, commandConfig = {}) {
                     protocolVersion: LEGACY_PROTOCOL_VERSION,
                     capabilities: capabilities(),
                     serverInfo: SERVER_INFO,
-                    instructions: buildAgentInstructions(npmAllowed, allowedCommands, await codeGraph.capability()),
+                    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,
@@ -433,14 +522,15 @@ export function createMcpHandler(root, commandConfig = {}) {
                             supportedVersions: [PROTOCOL_VERSION],
                             capabilities: capabilities(),
                             _meta: SERVER_INFO_META,
-                            instructions: buildAgentInstructions(npmAllowed, allowedCommands, await codeGraph.capability()),
+                            instructions: buildAgentInstructions(npmAllowed, allowedCommands, blacklistedCommands, gitEnabled, await codeGraph.capability()),
                             codeGraph: await codeGraph.capability(),
                             ttlMs: 0,
                             cacheScope: "private",
                         },
                     });
                 case "tools/list": {
-                    const page = paginate(await availableTools(codeGraph), params.cursor);
+                    const page = paginate(await availableTools(codeGraph, gitEnabled), params.cursor);
+                    mcpSuccess = true;
                     return json({
                         jsonrpc: "2.0",
                         id: message.id,
@@ -455,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 = (await availableTools(codeGraph)).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, codeGraph),
-                    });
+                    }
+                    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 = [
@@ -493,6 +646,7 @@ export function createMcpHandler(root, commandConfig = {}) {
                         })),
                     ];
                     const page = paginate(resources, params.cursor);
+                    mcpSuccess = true;
                     return json({
                         jsonrpc: "2.0",
                         id: message.id,
@@ -509,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,
@@ -519,7 +674,7 @@ export function createMcpHandler(root, commandConfig = {}) {
                                     {
                                         uri: INSTRUCTIONS_URI,
                                         mimeType: "text/markdown",
-                                        text: buildAgentInstructions(npmAllowed, allowedCommands, await codeGraph.capability()),
+                                        text: buildAgentInstructions(npmAllowed, allowedCommands, blacklistedCommands, gitEnabled, await codeGraph.capability()),
                                     },
                                 ],
                                 ttlMs: 0,
@@ -527,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,
@@ -537,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,
@@ -545,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,
@@ -563,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,
@@ -578,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,
@@ -593,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,
@@ -610,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",
@@ -637,8 +802,29 @@ export function createMcpHandler(root, commandConfig = {}) {
                 : -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",
@@ -658,19 +844,23 @@ export function createMcpHandler(root, commandConfig = {}) {
     };
     return handler;
 }
-async function availableTools(codeGraph) {
+async function availableTools(codeGraph, gitEnabled) {
     const capability = await codeGraph.capability();
-    return capability.status === "available" ||
+    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, codeGraph) {
+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";
+    const blacklist = blacklistedCommands.length
+        ? blacklistedCommands.map((item) => `- ${item}`).join("\n")
+        : "- none";
     const codeGraphSection = codeGraph.status === "available" ||
         codeGraph.status === "startup_failed" ||
         codeGraph.status === "runtime_failed"
@@ -679,14 +869,21 @@ function buildAgentInstructions(npmAllowed, allowedCommands, codeGraph) {
             (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\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_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}`;
+    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_context",
@@ -716,7 +913,7 @@ function capabilities() {
         extensions: { "io.modelcontextprotocol/skills": { directoryRead: true } },
     };
 }
-async function callTool(name, args, root, npmAllowed, allowedCommands, notify, signal, codeGraph) {
+async function callTool(name, args, root, npmAllowed, allowedCommands, blacklistedCommands, gitEnabled, notify, signal, codeGraph) {
     let structuredContent;
     if (name === "codegraph_explore") {
         if (!codeGraph)
@@ -728,6 +925,9 @@ async function callTool(name, args, root, npmAllowed, allowedCommands, notify, s
             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": {
             const items = await listFiles(root);
@@ -1158,6 +1358,7 @@ async function callTool(name, args, root, npmAllowed, allowedCommands, notify, s
             structuredContent = {
                 npmScripts: [...npmAllowed],
                 commands: [...allowedCommands],
+                blacklistedCommands: [...blacklistedCommands],
             };
             break;
         case "file_info":
@@ -1197,7 +1398,7 @@ async function callTool(name, args, root, npmAllowed, allowedCommands, notify, s
         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;
@@ -1336,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);
 }