comisai 1.0.4

package/node_modules/@comis/skills/dist/bridge/mcp-tool-bridge.js

@@ -0,0 +1,260 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * MCP Tool Bridge: Converts MCP tool definitions to AgentTool instances.
+ *
+ * Follows the pattern established by skill-tool-bridge.ts for converting
+ * external tool definitions into the AgentTool format expected by the
+ * agent executor (pi-agent-core).
+ *
+ * Key functions:
+ * - mcpToolsToAgentTools: Batch convert MCP tools to AgentTool[]
+ * - jsonSchemaToTypeBox: Basic JSON Schema -> TypeBox conversion
+ *
+ * @module
+ */
+import { Type } from "@sinclair/typebox";
+import { registerToolMetadata } from "@comis/core";
+import { resolveSourceProfile } from "../builtin/tool-source-profiles.js";
+import { sanitizeMcpToolResult } from "../integrations/mcp-result-sanitizer.js";
+import { truncateJsonAware } from "./json-truncate.js";
+// ---------------------------------------------------------------------------
+// MCP tool name parsing and error classification
+// ---------------------------------------------------------------------------
+/**
+ * Extract the MCP server name from a sanitized tool name.
+ *
+ * Sanitized MCP tool names use the format `mcp__serverName--toolName`.
+ * Returns `undefined` for non-MCP tools or malformed names.
+ *
+ * @example
+ * extractMcpServerName("mcp__context7--resolve-library-id") // "context7"
+ * extractMcpServerName("mcp__srv__v2--ns--tool") // "srv__v2"
+ * extractMcpServerName("bash") // undefined
+ */
+export function extractMcpServerName(toolName) {
+    if (!toolName.startsWith("mcp__"))
+        return undefined;
+    const rest = toolName.slice(5); // strip "mcp__"
+    const sepIdx = rest.indexOf("--");
+    if (sepIdx <= 0)
+        return undefined; // no separator or empty server name
+    return rest.slice(0, sepIdx);
+}
+/**
+ * Classify an MCP error message into a category for observability.
+ *
+ * Returns one of: "timeout", "connection", "tool_error", "transport", "unknown".
+ */
+export function classifyMcpErrorType(errorText) {
+    if (!errorText)
+        return "unknown";
+    const lower = errorText.toLowerCase();
+    if (lower.includes("timed out") || lower.includes("timeout"))
+        return "timeout";
+    if (lower.includes("not connected") || lower.includes("disconnected"))
+        return "connection";
+    if (lower.includes("crashed unexpectedly") || lower.includes("pipe") || lower.includes("epipe") || lower.includes("econnreset"))
+        return "transport";
+    if (lower.includes("mcp tool error:") || lower.includes("mcp tool returned an error"))
+        return "tool_error";
+    return "unknown";
+}
+// ---------------------------------------------------------------------------
+// JSON Schema -> TypeBox conversion
+// ---------------------------------------------------------------------------
+/**
+ * Convert a basic JSON Schema definition to a TypeBox TSchema.
+ *
+ * Handles primitive types, arrays, and objects. Complex schema features
+ * (oneOf, allOf, $ref, etc.) fall back to Type.Any().
+ *
+ * This is intentionally simple -- MCP tool schemas are typically flat
+ * objects with primitive properties. Complex schemas still work but
+ * lose TypeBox-level validation detail.
+ */
+export function jsonSchemaToTypeBox(schema) {
+    const type = schema.type;
+    if (type === "string") {
+        return Type.String();
+    }
+    if (type === "number") {
+        return Type.Number();
+    }
+    if (type === "integer") {
+        return Type.Integer();
+    }
+    if (type === "boolean") {
+        return Type.Boolean();
+    }
+    if (type === "array") {
+        const items = schema.items;
+        if (items) {
+            return Type.Array(jsonSchemaToTypeBox(items));
+        }
+        return Type.Array(Type.Any());
+    }
+    if (type === "object") {
+        const properties = schema.properties;
+        const required = schema.required ?? [];
+        if (!properties) {
+            return Type.Object({});
+        }
+        const typeboxProps = {};
+        for (const [key, propSchema] of Object.entries(properties)) {
+            const converted = jsonSchemaToTypeBox(propSchema);
+            typeboxProps[key] = required.includes(key) ? converted : Type.Optional(converted);
+        }
+        return Type.Object(typeboxProps);
+    }
+    // Fallback for unknown or complex schema types
+    return Type.Any();
+}
+// ---------------------------------------------------------------------------
+// Description truncation
+// ---------------------------------------------------------------------------
+/** Maximum characters for LLM-facing MCP tool descriptions. */
+export const MAX_LLM_DESCRIPTION_CHARS = 2048;
+const TRUNCATED_SUFFIX = " [truncated]";
+/**
+ * Truncate a tool description for LLM consumption. Returns the original
+ * string when it fits within the budget, or a truncated version with
+ * "[truncated]" suffix. Returns undefined for undefined input.
+ */
+function truncateDescription(desc) {
+    if (!desc || desc.length <= MAX_LLM_DESCRIPTION_CHARS)
+        return desc;
+    return desc.slice(0, MAX_LLM_DESCRIPTION_CHARS - TRUNCATED_SUFFIX.length) + TRUNCATED_SUFFIX;
+}
+// ---------------------------------------------------------------------------
+// MCP tool -> AgentTool conversion
+// ---------------------------------------------------------------------------
+/**
+ * Extract the server name from a qualified tool name "mcp:{server}/{tool}".
+ * Returns the full name as fallback.
+ */
+function extractServerName(qualifiedName) {
+    const match = qualifiedName.match(/^mcp:([^/]+)\//);
+    return match ? match[1] : qualifiedName;
+}
+/**
+ * Sanitize a qualified MCP tool name for use as an LLM API tool name.
+ *
+ * LLM APIs (Anthropic, OpenAI) require tool names to match `^[a-zA-Z0-9_-]{1,128}$`.
+ * Qualified names like "mcp:context7/resolve-library-id" contain invalid characters
+ * (`:`, `/`). This function replaces them: "mcp:" -> "mcp__", "/" -> "--".
+ *
+ * Example: "mcp:context7/resolve-library-id" -> "mcp__context7--resolve-library-id"
+ */
+export function sanitizeMcpToolName(qualifiedName) {
+    return qualifiedName.replace(/:/g, "__").replace(/\//g, "--");
+}
+/**
+ * Convert an array of MCP tool definitions to AgentTool instances.
+ *
+ * Each AgentTool's execute() delegates to the provided callTool function,
+ * which dispatches to the correct MCP server connection. Error results
+ * from the MCP server are returned as text content (not thrown), matching
+ * the AgentTool contract.
+ *
+ * Successful results are capped to the resolved source profile's maxChars
+ * limit, preventing oversized MCP responses from consuming agent context.
+ *
+ * @param tools - MCP tool definitions from McpClientManager.getTools()
+ * @param callTool - McpClientManager.callTool bound function
+ * @param toolSourceProfiles - Optional per-tool overrides for source profiles
+ * @param logger - Optional diagnostic logger for tracing tool result content shape
+ * @returns AgentTool instances ready for the agent executor
+ */
+export function mcpToolsToAgentTools(tools, callTool, toolSourceProfiles, logger) {
+    /** Log the content shape of an execute() return value for content-loss diagnosis. */
+    function logResult(result, toolCallId, toolName, isError) {
+        if (!logger)
+            return;
+        const firstBlock = result.content?.[0];
+        logger.debug({
+            toolName,
+            toolCallId,
+            contentLength: result.content?.length ?? 0,
+            hasDetails: !!result.details,
+            firstBlockType: firstBlock?.type,
+            firstBlockTextLen: firstBlock?.type === "text" ? firstBlock.text.length : undefined,
+            isError,
+        }, "MCP bridge execute() result shape");
+    }
+    return tools.map((tool) => {
+        const typeboxSchema = jsonSchemaToTypeBox(tool.inputSchema);
+        const serverName = extractServerName(tool.qualifiedName);
+        const sanitizedName = sanitizeMcpToolName(tool.qualifiedName);
+        // Register full description as searchHint for BM25 scoring in discover_tools
+        registerToolMetadata(sanitizedName, { searchHint: tool.description ?? "" });
+        return {
+            name: sanitizedName,
+            label: tool.name,
+            // Truncate description for LLM token budget; full text preserved in searchHint above
+            description: truncateDescription(tool.description) ?? `MCP tool from ${serverName}`,
+            parameters: typeboxSchema,
+            async execute(_toolCallId, params) {
+                try {
+                    const result = await callTool(tool.qualifiedName, params);
+                    if (!result.ok) {
+                        const errorResult = {
+                            content: [{ type: "text", text: `MCP tool error: ${result.error.message}` }],
+                            details: { success: false },
+                        };
+                        logResult(errorResult, _toolCallId, sanitizedName, true);
+                        return errorResult;
+                    }
+                    const value = result.value;
+                    if (value.isError) {
+                        const errorText = value.content
+                            .filter((c) => c.type === "text" && c.text)
+                            .map((c) => c.text)
+                            .join("\n");
+                        const isErrorResult = {
+                            content: [
+                                {
+                                    type: "text",
+                                    text: errorText || "MCP tool returned an error with no details",
+                                },
+                            ],
+                            details: { success: false },
+                        };
+                        logResult(isErrorResult, _toolCallId, sanitizedName, true);
+                        return isErrorResult;
+                    }
+                    // Collect text content from the MCP result
+                    let textParts = value.content
+                        .filter((c) => c.type === "text" && c.text)
+                        .map((c) => c.text)
+                        .join("\n");
+                    // Sanitize MCP result (NFKC normalization + invisible char removal)
+                    textParts = sanitizeMcpToolResult(textParts);
+                    // Source-gate: cap text to resolved profile's maxChars limit
+                    const profile = resolveSourceProfile(sanitizedName, toolSourceProfiles?.[sanitizedName]);
+                    if (textParts.length > profile.maxChars) {
+                        const { truncated } = truncateJsonAware(textParts, profile.maxChars);
+                        textParts = truncated;
+                    }
+                    const successResult = {
+                        content: [{ type: "text", text: textParts || "Tool returned no text content" }],
+                        details: { success: true },
+                    };
+                    logResult(successResult, _toolCallId, sanitizedName, false);
+                    return successResult;
+                }
+                catch (error) {
+                    // Defense-in-depth: callTool returns Result and should never throw,
+                    // but if something unexpected happens, return a clean error to the agent
+                    // instead of letting it propagate and produce an opaque SDK error message.
+                    const message = error instanceof Error ? error.message : String(error);
+                    const crashResult = {
+                        content: [{ type: "text", text: `MCP tool "${tool.qualifiedName}" crashed unexpectedly: ${message}` }],
+                        details: { success: false },
+                    };
+                    logResult(crashResult, _toolCallId, sanitizedName, true);
+                    return crashResult;
+                }
+            },
+        };
+    });
+}

package/node_modules/@comis/skills/dist/bridge/tool-audit.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Tool audit wrapper: Wraps any AgentTool to emit timing and success/failure
+ * events via the TypedEventBus.
+ *
+ * Every tool invocation emits a `tool:executed` event with toolName, durationMs,
+ * and success boolean. Duration is measured inside execute() (not at wrap time)
+ * to accurately reflect actual execution time.
+ *
+ * @module
+ */
+import type { AgentTool } from "@mariozechner/pi-agent-core";
+import type { TypedEventBus } from "@comis/core";
+/**
+ * Wrap an AgentTool with audit event emission.
+ *
+ * The returned tool behaves identically to the original, but emits a
+ * `tool:executed` event on the provided eventBus after every execution
+ * (whether successful or failed).
+ *
+ * @param tool - The AgentTool to wrap
+ * @param eventBus - The TypedEventBus to emit events on
+ * @param agentId - Optional agent ID to include in audit events
+ * @returns A new AgentTool with audit instrumentation
+ */
+export declare function wrapWithAudit(tool: AgentTool<any>, eventBus: TypedEventBus, agentId?: string): AgentTool<any>;

package/node_modules/@comis/skills/dist/bridge/tool-audit.js

@@ -0,0 +1,78 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Tool audit wrapper: Wraps any AgentTool to emit timing and success/failure
+ * events via the TypedEventBus.
+ *
+ * Every tool invocation emits a `tool:executed` event with toolName, durationMs,
+ * and success boolean. Duration is measured inside execute() (not at wrap time)
+ * to accurately reflect actual execution time.
+ *
+ * @module
+ */
+import { tryGetContext } from "@comis/core";
+/**
+ * Wrap an AgentTool with audit event emission.
+ *
+ * The returned tool behaves identically to the original, but emits a
+ * `tool:executed` event on the provided eventBus after every execution
+ * (whether successful or failed).
+ *
+ * @param tool - The AgentTool to wrap
+ * @param eventBus - The TypedEventBus to emit events on
+ * @param agentId - Optional agent ID to include in audit events
+ * @returns A new AgentTool with audit instrumentation
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- AgentTool generic requires `any` per pi-agent-core API
+export function wrapWithAudit(tool, eventBus, agentId) {
+    return {
+        ...tool,
+        async execute(toolCallId, params, signal, onUpdate) {
+            const startMs = performance.now();
+            let success = true;
+            let errorMessage;
+            let errorKind;
+            try {
+                const result = await tool.execute(toolCallId, params, signal, onUpdate);
+                // Detect non-zero exit codes from tools that never throw (e.g., exec tool).
+                // These tools return { details: { exitCode: number } } via jsonResult().
+                const details = result?.details;
+                if (details &&
+                    typeof details.exitCode === "number" &&
+                    details.exitCode !== 0) {
+                    success = false;
+                    errorKind = "nonzero-exit";
+                }
+                return result;
+            }
+            catch (error) {
+                success = false;
+                errorMessage = (error instanceof Error ? error.message : String(error)).slice(0, 1500);
+                // Read errorKind from error property if present (e.g., validation errors from enforcement wrapper)
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any -- errorKind propagation from enforcement wrapper
+                if (error instanceof Error && typeof error.errorKind === "string") {
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- errorKind propagation
+                    errorKind = error.errorKind;
+                }
+                errorKind ??= signal?.aborted ? "timeout" : "internal";
+                throw error;
+            }
+            finally {
+                const durationMs = performance.now() - startMs;
+                const ctx = tryGetContext();
+                eventBus.emit("tool:executed", {
+                    toolName: tool.name,
+                    durationMs,
+                    success,
+                    timestamp: Date.now(),
+                    userId: ctx?.userId,
+                    traceId: ctx?.traceId,
+                    agentId,
+                    sessionKey: ctx?.sessionKey,
+                    params,
+                    ...(errorMessage !== undefined && { errorMessage }),
+                    ...(errorKind !== undefined && { errorKind }),
+                });
+            }
+        },
+    };
+}

package/node_modules/@comis/skills/dist/bridge/tool-bridge.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Tool bridge: Collects built-in tools and assembles the two-tier tool pipeline.
+ *
+ * This is the integration layer between the skill system and the agent executor.
+ * It provides built-in tools and platform tools to the agent.
+ *
+ * Key functions:
+ * - getBuiltinTools: Collects enabled built-in tools from config
+ * - assembleToolPipeline: Two-tier tool pipeline with policy and audit
+ *
+ * @module
+ */
+import type { SecretManager } from "@comis/core";
+import type { SkillsConfig } from "@comis/core";
+import type { TypedEventBus } from "@comis/core";
+import type { WrapExternalContentOptions } from "@comis/core";
+import type { AgentTool } from "@mariozechner/pi-agent-core";
+import type { CredentialInjector } from "./credential-injector.js";
+import type { FileStateTracker } from "../builtin/file/file-state-tracker.js";
+import type { LazyPaths } from "../builtin/file/safe-path-wrapper.js";
+import { type ToolSourceProfile } from "../builtin/tool-source-profiles.js";
+/** Minimal pino-compatible logger interface for tool bridge logging. */
+interface ToolBridgeLogger {
+    info(obj: Record<string, unknown>, msg: string): void;
+    warn(obj: Record<string, unknown>, msg: string): void;
+    debug(obj: Record<string, unknown>, msg: string): void;
+}
+/**
+ * Collect enabled built-in tools based on config toggles.
+ *
+ * @param config - Skills configuration with builtinTools toggles
+ * @param workspacePath - Workspace root path for file/bash operations
+ * @param secretManager - Optional secret manager for API keys
+ * @returns Array of enabled AgentTool instances
+ */
+export declare function getBuiltinTools(config: SkillsConfig, workspacePath: string, secretManager?: SecretManager, logger?: ToolBridgeLogger, onSuspiciousContent?: WrapExternalContentOptions["onSuspiciousContent"], readOnlyPaths?: string[], 
+/** Per-agent source profile overrides from config. */
+toolSourceProfiles?: Record<string, Partial<ToolSourceProfile>>, 
+/** Shared read+write paths for graph pipeline nodes. */
+sharedPaths?: LazyPaths, 
+/** Optional per-session FileStateTracker for file safety guards. */
+fileStateTracker?: FileStateTracker): AgentTool<any>[];
+/** Platform tools are injected by the caller (agent executor, daemon). */
+export type PlatformToolProvider = () => AgentTool<any>[];
+/**
+ * Dependencies for the two-tier tool assembly pipeline.
+ */
+export interface ToolPipelineDeps {
+    /** Skills configuration with toolPolicy and builtinTools. */
+    config: SkillsConfig;
+    /** Workspace root path for builtin tools. */
+    workspacePath: string;
+    /** Secret manager for API keys. */
+    secretManager?: SecretManager;
+    /** Platform tool providers (injected by caller). */
+    platformTools?: PlatformToolProvider;
+    /** Event bus for audit wrapper. */
+    eventBus?: TypedEventBus;
+    /** Optional structured logger for pipeline assembly. */
+    logger?: ToolBridgeLogger;
+    /** Optional agent ID for audit event attribution. */
+    agentId?: string;
+    /** Optional credential injector for transparent API key injection. */
+    credentialInjector?: CredentialInjector;
+    /** Optional callback for suspicious content detection in external content. */
+    onSuspiciousContent?: WrapExternalContentOptions["onSuspiciousContent"];
+    /** Optional read-only paths that read-only file tools (read/ls/grep/find) may access. */
+    readOnlyPaths?: string[];
+    /** Per-agent source profile overrides from config. */
+    toolSourceProfiles?: Record<string, Partial<ToolSourceProfile>>;
+    /** Shared read+write paths for graph pipeline nodes. */
+    sharedPaths?: LazyPaths;
+    /** Optional per-session FileStateTracker for file safety guards. */
+    fileStateTracker?: FileStateTracker;
+}
+/**
+ * Assemble the two-tier tool pipeline with policy filtering and audit wrapping.
+ *
+ * Pipeline stages:
+ * 1. **Tier 1 - Builtin**: Enabled built-in tools from config toggles
+ * 2. **Tier 2 - Platform**: Tools injected by the caller (channel adapters, daemon)
+ * 3. **Policy filter**: Config-driven tool policy (profile + allow/deny)
+ * 4. **Credential injection**: Transparent HTTP credential injection for matching URLs
+ * 5. **Metadata enforcement**: Pre-flight validation and per-tool result size caps
+ * 6. **Audit wrap**: Event emission for each tool invocation
+ *
+ * @param deps - Pipeline dependencies
+ * @returns Filtered and instrumented array of AgentTools
+ */
+export declare function assembleToolPipeline(deps: ToolPipelineDeps): Promise<AgentTool<any>[]>;
+export {};

package/node_modules/@comis/skills/dist/bridge/tool-bridge.js

@@ -0,0 +1,136 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Tool bridge: Collects built-in tools and assembles the two-tier tool pipeline.
+ *
+ * This is the integration layer between the skill system and the agent executor.
+ * It provides built-in tools and platform tools to the agent.
+ *
+ * Key functions:
+ * - getBuiltinTools: Collects enabled built-in tools from config
+ * - assembleToolPipeline: Two-tier tool pipeline with policy and audit
+ *
+ * @module
+ */
+import { registerAllToolMetadata } from "./tool-metadata-registry.js";
+registerAllToolMetadata();
+import { applyToolPolicy } from "../policy/tool-policy.js";
+import { wrapWithAudit } from "./tool-audit.js";
+import { wrapWithMetadataEnforcement } from "./tool-metadata-enforcement.js";
+import { wrapWithCredentialInjection } from "./credential-injector.js";
+import { createComisFileTools } from "../builtin/file/file-tools.js";
+import { createWebFetchTool } from "../builtin/web-fetch-tool.js";
+import { createWebSearchTool } from "../builtin/web-search-tool.js";
+import { resolveSourceProfile } from "../builtin/tool-source-profiles.js";
+/**
+ * Collect enabled built-in tools based on config toggles.
+ *
+ * @param config - Skills configuration with builtinTools toggles
+ * @param workspacePath - Workspace root path for file/bash operations
+ * @param secretManager - Optional secret manager for API keys
+ * @returns Array of enabled AgentTool instances
+ */
+export function getBuiltinTools(config, workspacePath, secretManager, logger, onSuspiciousContent, readOnlyPaths, 
+/** Per-agent source profile overrides from config. */
+toolSourceProfiles, 
+/** Shared read+write paths for graph pipeline nodes. */
+sharedPaths, 
+/** Optional per-session FileStateTracker for file safety guards. */
+fileStateTracker) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- AgentTool generic requires `any` per pi-agent-core API
+    const tools = [];
+    // Resolve source profiles for web tools
+    const fetchProfile = resolveSourceProfile("web_fetch", toolSourceProfiles?.web_fetch);
+    const searchProfile = resolveSourceProfile("web_search", toolSourceProfiles?.web_search);
+    // Web Search -- pass resolved profile values
+    if (config.builtinTools.webSearch) {
+        tools.push(createWebSearchTool({
+            apiKey: secretManager?.get("SEARCH_API_KEY"),
+            perplexity: { apiKey: secretManager?.get("PERPLEXITY_API_KEY") },
+            tavily: { apiKey: secretManager?.get("TAVILY_API_KEY") },
+            exa: { apiKey: secretManager?.get("EXA_API_KEY") },
+            jina: { apiKey: secretManager?.get("JINA_API_KEY") },
+            grok: { apiKey: secretManager?.get("XAI_API_KEY") },
+            totalCharsBudget: searchProfile.maxChars,
+            onSuspiciousContent,
+        }));
+    }
+    // Web Fetch -- pass resolved profile values
+    if (config.builtinTools.webFetch) {
+        tools.push(createWebFetchTool({
+            maxCharsCap: fetchProfile.maxChars,
+            maxResponseBytes: fetchProfile.maxResponseBytes,
+            onSuspiciousContent,
+        }));
+    }
+    // File tools (Comis-native)
+    const fileTools = createComisFileTools(config, workspacePath, logger, readOnlyPaths, sharedPaths, fileStateTracker);
+    tools.push(...fileTools);
+    return tools;
+}
+/**
+ * Assemble the two-tier tool pipeline with policy filtering and audit wrapping.
+ *
+ * Pipeline stages:
+ * 1. **Tier 1 - Builtin**: Enabled built-in tools from config toggles
+ * 2. **Tier 2 - Platform**: Tools injected by the caller (channel adapters, daemon)
+ * 3. **Policy filter**: Config-driven tool policy (profile + allow/deny)
+ * 4. **Credential injection**: Transparent HTTP credential injection for matching URLs
+ * 5. **Metadata enforcement**: Pre-flight validation and per-tool result size caps
+ * 6. **Audit wrap**: Event emission for each tool invocation
+ *
+ * @param deps - Pipeline dependencies
+ * @returns Filtered and instrumented array of AgentTools
+ */
+export async function assembleToolPipeline(deps) {
+    // Tier 1 - Builtin
+    const builtinTools = getBuiltinTools(deps.config, deps.workspacePath, deps.secretManager, deps.logger, deps.onSuspiciousContent, deps.readOnlyPaths, deps.toolSourceProfiles, deps.sharedPaths, deps.fileStateTracker);
+    // Tier 2 - Platform
+    const platformTools = deps.platformTools ? deps.platformTools() : [];
+    // Combine all tiers
+    let tools = [...builtinTools, ...platformTools];
+    // Policy filter
+    if (deps.config.toolPolicy) {
+        const policyResult = applyToolPolicy(tools, deps.config.toolPolicy);
+        tools = policyResult.tools;
+        // Log denied tools at DEBUG level (internal step per CLAUDE.md logging rules)
+        if (policyResult.filtered.length > 0 && deps.logger) {
+            deps.logger.debug({
+                agentId: deps.agentId,
+                profile: deps.config.toolPolicy.profile,
+                filteredCount: policyResult.filtered.length,
+                filtered: policyResult.filtered.map((f) => ({
+                    tool: f.toolName,
+                    reason: f.reason.kind,
+                    ...(f.reason.kind === "explicit_deny" && { denyEntry: f.reason.denyEntry }),
+                    ...(f.reason.kind === "not_in_profile" && { profile: f.reason.profile }),
+                })),
+            }, "Tool policy filtered tools");
+        }
+        // Emit audit event if eventBus available
+        if (policyResult.filtered.length > 0 && deps.eventBus) {
+            deps.eventBus.emit("tool:policy_filtered", {
+                profile: deps.config.toolPolicy.profile,
+                agentId: deps.agentId,
+                filtered: policyResult.filtered.map((f) => ({
+                    toolName: f.toolName,
+                    reason: f.reason.kind === "explicit_deny"
+                        ? `explicit_deny:${f.reason.denyEntry}`
+                        : `not_in_profile:${f.reason.profile}`,
+                })),
+                timestamp: Date.now(),
+            });
+        }
+    }
+    // Credential injection -- after policy filter, before audit wrap
+    if (deps.credentialInjector) {
+        tools = tools.map((tool) => wrapWithCredentialInjection(tool, deps.credentialInjector));
+    }
+    // Metadata enforcement -- ALWAYS runs (not gated by eventBus)
+    // Handles pre-flight validation and per-tool result size caps.
+    tools = tools.map((tool) => wrapWithMetadataEnforcement(tool));
+    // Audit wrap
+    if (deps.eventBus) {
+        tools = tools.map((tool) => wrapWithAudit(tool, deps.eventBus, deps.agentId));
+    }
+    return tools;
+}

package/node_modules/@comis/skills/dist/bridge/tool-definition-adapter.d.ts

@@ -0,0 +1,33 @@
+/**
+ * AgentTool to ToolDefinition adapter.
+ *
+ * Converts Comis's AgentTool instances to pi-coding-agent's ToolDefinition
+ * format by wrapping the execute() signature to accept the additional
+ * ExtensionContext parameter (which is ignored -- Comis manages its own context).
+ *
+ * The adapter preserves tool.name exactly, which is critical for tool policy
+ * matching (TOOL_PROFILES and TOOL_GROUPS filter on .name).
+ *
+ * When resolvedDescriptions is provided (pre-resolved lean descriptions from
+ * the daemon), the adapter overrides tool.description with the lean version.
+ * This avoids a circular dependency (skills cannot import from agent).
+ *
+ * @module
+ */
+import type { ToolDefinition } from "@mariozechner/pi-coding-agent";
+import type { AgentTool } from "@mariozechner/pi-agent-core";
+/**
+ * Convert a single AgentTool to ToolDefinition format.
+ *
+ * When resolvedDescriptions is provided and contains an entry for tool.name,
+ * the lean description overrides tool.description. This enables the dual-summary
+ * architecture: TOOL_SUMMARIES in system prompt, LEAN_TOOL_DESCRIPTIONS in API defs.
+ */
+export declare function agentToolToToolDefinition(tool: AgentTool<any>, resolvedDescriptions?: Record<string, string>): ToolDefinition;
+/**
+ * Batch convert AgentTool[] to ToolDefinition[].
+ *
+ * When resolvedDescriptions is provided, each tool's description is overridden
+ * with the pre-resolved lean description (if an entry exists for that tool name).
+ */
+export declare function agentToolsToToolDefinitions(tools: AgentTool<any>[], resolvedDescriptions?: Record<string, string>): ToolDefinition[];