comisai 1.0.37 → 1.0.40

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

@@ -0,0 +1,114 @@
+// SPDX-License-Identifier: Apache-2.0
+// @allow-throw: skill bridge / integration boundary; throws caught by AgentTool wrapper or skill loader boundary.
+/**
+ * Tool metadata enforcement wrapper.
+ *
+ * Standalone pipeline wrapper that applies metadata-driven behavior
+ * (pre-flight input validation, post-execution result truncation) to
+ * every tool invocation. Runs unconditionally -- NOT gated by eventBus --
+ * because the daemon path passes eventBus: undefined which skips the
+ * audit wrapper entirely.
+ *
+ * @module
+ */
+import { getToolMetadata, truncateContentBlocks } from "@comis/core";
+import { validateToolEntry } from "./schema-validator.js";
+/**
+ * Check whether a tool result's content is effectively empty.
+ *
+ * Returns `true` when the LLM would see a blank tool_result content block:
+ * - content is falsy (undefined/null)
+ * - content is an empty array
+ * - content contains ONLY text blocks where every `.text` is empty or whitespace-only
+ *
+ * Returns `false` if content contains any ImageContent blocks (images are never "empty")
+ * or any TextContent with non-whitespace text.
+ *
+ * @param content - The tool result content array to inspect
+ * @returns Whether the content is effectively empty
+ */
+export function isToolResultContentEmpty(content) {
+    if (!content)
+        return true;
+    if (content.length === 0)
+        return true;
+    for (const block of content) {
+        // Any non-text block (e.g. image) means content is not empty
+        if (block.type !== "text")
+            return false;
+        // Any text block with non-whitespace content means not empty
+        if (block.text.trim().length > 0)
+            return false;
+    }
+    return true;
+}
+/**
+ * Wrap an AgentTool with metadata enforcement.
+ *
+ * Pre-flight: If `validateInput` is registered, calls it with params.
+ * On failure, throws with `[invalid_value]` prefix (matches pi-agent SDK
+ * error classification).
+ *
+ * Post-execution: If `maxResultSizeChars` is registered and the result
+ * has content blocks, truncates them via `truncateContentBlocks()`.
+ * Returns the original result by reference when no truncation occurs.
+ *
+ * @param tool - The AgentTool to wrap
+ * @returns A new AgentTool with metadata enforcement
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- AgentTool generic requires `any` per pi-agent-core API
+export function wrapWithMetadataEnforcement(tool) {
+    return {
+        ...tool,
+        async execute(toolCallId, params, signal, onUpdate) {
+            const meta = getToolMetadata(tool.name);
+            // Generic tool-entry schema validation.
+            // Runs BEFORE per-tool validateInput so action-shape errors short-circuit
+            // before tool-specific business rules. Skips silently when the tool has
+            // not registered validActions / validKeys / requiredByAction.
+            const schemaError = validateToolEntry(params, meta);
+            if (schemaError !== undefined) {
+                const err = new Error(`[invalid_value] ${schemaError}`);
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any -- match existing errorKind propagation pattern
+                err.errorKind = "validation";
+                throw err;
+            }
+            // Pre-flight validation
+            if (meta?.validateInput) {
+                const validationError = await meta.validateInput(params);
+                if (validationError !== undefined && validationError !== "") {
+                    const err = new Error(`[invalid_value] ${validationError}`);
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- attach errorKind for audit wrapper propagation
+                    err.errorKind = "validation";
+                    throw err;
+                }
+            }
+            // Execute the original tool
+            const result = await tool.execute(toolCallId, params, signal, onUpdate);
+            // Post-execution result truncation
+            if (meta?.maxResultSizeChars && result?.content) {
+                // Cast through unknown: AgentToolResult.content is (TextContent | ImageContent)[]
+                // while truncateContentBlocks accepts a looser ContentBlock[] with index signature.
+                // The shapes are structurally compatible at runtime (both have type + text fields).
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                const capped = truncateContentBlocks(result.content, meta.maxResultSizeChars);
+                // Only create a new result object if truncation actually occurred
+                if (capped !== result.content) {
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    return { ...result, content: capped };
+                }
+            }
+            // Empty result marker injection -- prevent LLM confusion on empty tool_result.
+            // Runs AFTER truncation so truncated results (which add a notice) are never marked empty.
+            // Error results (isError: true) are exempt -- empty errors are a different signal.
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any -- isError is set by SDK agent-loop, not in AgentToolResult type
+            if (!result?.isError && isToolResultContentEmpty(result?.content)) {
+                return {
+                    ...result,
+                    content: [{ type: "text", text: `(${tool.name} completed with no output)` }],
+                };
+            }
+            return result;
+        },
+    };
+}

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

@@ -0,0 +1,493 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Tool metadata registry: Consolidated registration of all tool metadata.
+ *
+ * Previously split across 5 side-effect import files, now unified into
+ * a single explicit registration function. Metadata is registered in
+ * category order: result caps, parallelism, validators, output schemas,
+ * search hints. For tools appearing in multiple categories, merge
+ * semantics ({ ...existing, ...new }) are preserved by the
+ * registerToolMetadata() function in @comis/core.
+ *
+ * @module
+ */
+import { registerToolMetadata, isImmutableConfigPath, getMutableOverridesForSection, getManagedSectionRedirect, formatRedirectHint, } from "@comis/core";
+import { validateExecCommand } from "../../tools/builtin/exec-security/index.js";
+import { GATEWAY_ACTIONS } from "../../platform-tools/tools/gateway-tool.js";
+export function registerAllToolMetadata() {
+    // =========================================================================
+    // Result Size Caps
+    // =========================================================================
+    // --- File tools (Comis-native via createComisFileTools) ---
+    registerToolMetadata("grep", { maxResultSizeChars: 100_000 });
+    registerToolMetadata("read", { maxResultSizeChars: 200_000 });
+    registerToolMetadata("find", { maxResultSizeChars: 50_000 });
+    registerToolMetadata("ls", { maxResultSizeChars: 20_000 });
+    // --- Exec tool ---
+    registerToolMetadata("exec", { maxResultSizeChars: 100_000 });
+    // --- Web tools ---
+    registerToolMetadata("web_fetch", { maxResultSizeChars: 150_000 });
+    registerToolMetadata("web_search", { maxResultSizeChars: 50_000 });
+    // --- Platform tools (RPC-based, created in daemon wiring) ---
+    registerToolMetadata("sessions_history", { maxResultSizeChars: 100_000 });
+    registerToolMetadata("obs_query", { maxResultSizeChars: 100_000 });
+    registerToolMetadata("memory_search", { maxResultSizeChars: 50_000 });
+    // =========================================================================
+    // Parallelism Metadata
+    // =========================================================================
+    // --- Read-only tools (25) ---
+    registerToolMetadata("read", { isReadOnly: true });
+    registerToolMetadata("grep", { isReadOnly: true, searchHint: "search file contents with regex pattern ripgrep" });
+    registerToolMetadata("find", { isReadOnly: true });
+    registerToolMetadata("ls", { isReadOnly: true });
+    registerToolMetadata("web_search", { isReadOnly: true });
+    registerToolMetadata("web_fetch", { isReadOnly: true });
+    registerToolMetadata("browser", { isReadOnly: true });
+    registerToolMetadata("memory_search", { isReadOnly: true });
+    registerToolMetadata("memory_get", { isReadOnly: true });
+    registerToolMetadata("session_search", { isReadOnly: true });
+    registerToolMetadata("sessions_list", { isReadOnly: true });
+    registerToolMetadata("session_status", { isReadOnly: true });
+    registerToolMetadata("sessions_history", { isReadOnly: true });
+    registerToolMetadata("ctx_search", { isReadOnly: true });
+    registerToolMetadata("ctx_inspect", { isReadOnly: true });
+    registerToolMetadata("ctx_expand", { isReadOnly: true });
+    registerToolMetadata("ctx_recall", { isReadOnly: true });
+    registerToolMetadata("image_analyze", { isReadOnly: true });
+    registerToolMetadata("describe_video", { isReadOnly: true });
+    registerToolMetadata("extract_document", { isReadOnly: true });
+    registerToolMetadata("transcribe_audio", { isReadOnly: true });
+    registerToolMetadata("obs_query", { isReadOnly: true });
+    registerToolMetadata("models_manage", { isReadOnly: true });
+    registerToolMetadata("discover_tools", { isReadOnly: true });
+    // --- Mutating tools (25) ---
+    registerToolMetadata("edit", { isReadOnly: false });
+    registerToolMetadata("write", { isReadOnly: false });
+    registerToolMetadata("apply_patch", { isReadOnly: false });
+    registerToolMetadata("exec", { isReadOnly: false });
+    registerToolMetadata("process", { isReadOnly: false });
+    registerToolMetadata("memory_store", { isReadOnly: false });
+    registerToolMetadata("memory_manage", { isReadOnly: false });
+    registerToolMetadata("sessions_manage", { isReadOnly: false });
+    registerToolMetadata("sessions_send", { isReadOnly: false });
+    registerToolMetadata("sessions_spawn", { isReadOnly: false });
+    registerToolMetadata("subagents", { isReadOnly: false });
+    registerToolMetadata("pipeline", { isReadOnly: false });
+    registerToolMetadata("cron", { isReadOnly: false });
+    registerToolMetadata("gateway", { isReadOnly: false });
+    registerToolMetadata("heartbeat_manage", { isReadOnly: false });
+    registerToolMetadata("channels_manage", { isReadOnly: false });
+    registerToolMetadata("tokens_manage", { isReadOnly: false });
+    registerToolMetadata("skills_manage", { isReadOnly: false });
+    registerToolMetadata("mcp_manage", { isReadOnly: false });
+    registerToolMetadata("agents_manage", { isReadOnly: false });
+    registerToolMetadata("whatsapp_action", { isReadOnly: false });
+    registerToolMetadata("discord_action", { isReadOnly: false });
+    registerToolMetadata("telegram_action", { isReadOnly: false });
+    registerToolMetadata("slack_action", { isReadOnly: false });
+    registerToolMetadata("tts_synthesize", { isReadOnly: false });
+    // --- Concurrency-safe mutating tool ---
+    registerToolMetadata("message", { isReadOnly: false, isConcurrencySafe: true });
+    // =========================================================================
+    // Input Validators
+    // =========================================================================
+    // Exec tool -- command + env validation via security pipeline
+    registerToolMetadata("exec", {
+        validateInput: (params) => {
+            const command = typeof params.command === "string" ? params.command : undefined;
+            if (!command || command.trim() === "") {
+                return "Missing required parameter: command";
+            }
+            const result = validateExecCommand(command, params.env && typeof params.env === "object"
+                ? params.env
+                : undefined);
+            return result?.message;
+        },
+    });
+    // Cron tool -- action enum + per-action required param validation
+    const VALID_CRON_ACTIONS = ["add", "list", "update", "remove", "status", "runs", "run", "wake"];
+    const VALID_SCHEDULE_KINDS = ["cron", "every", "at"];
+    registerToolMetadata("cron", {
+        validateInput: (params) => {
+            const action = typeof params.action === "string" ? params.action : undefined;
+            if (!action || !VALID_CRON_ACTIONS.includes(action)) {
+                return `Invalid action: "${action ?? ""}". Valid: ${VALID_CRON_ACTIONS.join(", ")}`;
+            }
+            if (action === "add") {
+                if (!params.payload_kind)
+                    return "Missing required parameter: payload_kind (for add)";
+                if (!params.payload_text)
+                    return "Missing required parameter: payload_text (for add)";
+                if (params.schedule_kind && typeof params.schedule_kind === "string") {
+                    if (!VALID_SCHEDULE_KINDS.includes(params.schedule_kind)) {
+                        return `Invalid schedule_kind: "${params.schedule_kind}". Valid: ${VALID_SCHEDULE_KINDS.join(", ")}`;
+                    }
+                }
+            }
+            if (["update", "remove", "runs", "run"].includes(action)) {
+                if (!params.job_name)
+                    return `Missing required parameter: job_name (for ${action})`;
+            }
+            return undefined;
+        },
+    });
+    // Message tool -- action enum + channel_type/channel_id presence
+    const VALID_MESSAGE_ACTIONS = ["send", "reply", "react", "edit", "delete", "fetch", "attach"];
+    registerToolMetadata("message", {
+        validateInput: (params) => {
+            const action = typeof params.action === "string" ? params.action : undefined;
+            if (!action || !VALID_MESSAGE_ACTIONS.includes(action)) {
+                return `Invalid action: "${action ?? ""}". Valid: ${VALID_MESSAGE_ACTIONS.join(", ")}`;
+            }
+            if (!params.channel_type || typeof params.channel_type !== "string") {
+                return "Missing required parameter: channel_type";
+            }
+            if (!params.channel_id || typeof params.channel_id !== "string") {
+                return "Missing required parameter: channel_id";
+            }
+            return undefined;
+        },
+    });
+    // Gateway tool -- action enum + immutable path rejection for patch and apply.
+    // Whitelist is derived from the tool's exported GATEWAY_ACTIONS tuple so
+    // bridge + handler cannot drift.
+    // When the rejected section has a dedicated *_manage tool, the message
+    // includes a parameter-correct redirect via formatRedirectHint() so any
+    // LLM (Opus/Sonnet/Haiku, GPT-5, Gemini, Mistral, etc.) can self-recover
+    // without model-specific prompting.
+    registerToolMetadata("gateway", {
+        validateInput: (params) => {
+            const action = typeof params.action === "string" ? params.action : undefined;
+            if (!action || !GATEWAY_ACTIONS.includes(action)) {
+                return `Invalid action: "${action ?? ""}". Valid: ${GATEWAY_ACTIONS.join(", ")}`;
+            }
+            const section = typeof params.section === "string" ? params.section : undefined;
+            // Only check immutability for mutating actions (reads must succeed on immutable paths).
+            if (action === "patch") {
+                const key = typeof params.key === "string" ? params.key : undefined;
+                if (section && isImmutableConfigPath(section, key)) {
+                    const mutablePaths = getMutableOverridesForSection(section, key);
+                    const redirect = getManagedSectionRedirect(section, key);
+                    const fullPath = `${section}${key ? "." + key : ""}`;
+                    const suffix = redirect
+                        ? ` ${formatRedirectHint(redirect, mutablePaths)}`
+                        : mutablePaths.length > 0
+                            ? ` Patchable: ${mutablePaths.join(", ")}.`
+                            : "";
+                    return `Cannot patch immutable config path: ${fullPath}.${suffix}`;
+                }
+            }
+            if (action === "apply") {
+                if (section && isImmutableConfigPath(section)) {
+                    const redirect = getManagedSectionRedirect(section);
+                    const suffix = redirect ? ` ${formatRedirectHint(redirect)}` : "";
+                    return `Cannot apply to immutable config section: ${section}.${suffix}`;
+                }
+            }
+            return undefined;
+        },
+    });
+    // =========================================================================
+    // Tool-Entry Schema
+    //
+    // Generic action enum + valid keys + per-action required fields. Consumed
+    // by validateToolEntry() in ./schema-validator.ts via
+    // wrapWithMetadataEnforcement BEFORE per-tool validateInput runs.
+    //
+    // Each tool's shape is sourced from its TypeBox Type.Union([Type.Literal(...)])
+    // action enum + each action handler's readStringParam(p, X) /
+    // throwToolError("missing_param", ...) calls in its actionOverrides.
+    //
+    // Cross-consistency: managed-section entries in
+    // @comis/core/src/config/managed-sections.ts also declare
+    // requiredByAction for the redirect-hint payload. The registrations
+    // here are the runtime gate; the managed-section entries are the
+    // user-facing redirect hint.
+    // =========================================================================
+    registerToolMetadata("mcp_manage", {
+        validActions: ["list", "status", "connect", "disconnect", "reconnect"],
+        validKeys: ["action", "server_name", "transport", "command", "args", "url", "headers"],
+        // connect requires [server_name, transport]; command (stdio) / url (sse|http) are
+        // transport-conditional and validated downstream by the handler.
+        requiredByAction: {
+            status: ["server_name"],
+            connect: ["server_name", "transport"],
+            disconnect: ["server_name"],
+            reconnect: ["server_name"],
+        },
+    });
+    registerToolMetadata("agents_manage", {
+        validActions: ["create", "get", "update", "delete", "suspend", "resume", "list"],
+        validKeys: ["action", "agent_id", "config"],
+        // agent_id is required for every action except list.
+        requiredByAction: {
+            create: ["agent_id", "config"],
+            get: ["agent_id"],
+            update: ["agent_id", "config"],
+            delete: ["agent_id"],
+            suspend: ["agent_id"],
+            resume: ["agent_id"],
+        },
+    });
+    registerToolMetadata("tokens_manage", {
+        validActions: ["list", "create", "revoke", "rotate"],
+        validKeys: ["action", "token_id", "scopes"],
+        // create: token_id is auto-generated when omitted (per the schema +
+        // handler's non-required readStringParam call); only scopes is strictly
+        // required.
+        requiredByAction: {
+            create: ["scopes"],
+            revoke: ["token_id"],
+            rotate: ["token_id"],
+        },
+    });
+    registerToolMetadata("providers_manage", {
+        validActions: ["list", "get", "create", "update", "delete", "enable", "disable"],
+        validKeys: ["action", "provider_id", "config"],
+        requiredByAction: {
+            get: ["provider_id"],
+            create: ["provider_id", "config"],
+            update: ["provider_id", "config"],
+            delete: ["provider_id"],
+            enable: ["provider_id"],
+            disable: ["provider_id"],
+        },
+    });
+    registerToolMetadata("channels_manage", {
+        validActions: ["list", "get", "enable", "disable", "restart", "configure"],
+        validKeys: ["action", "channel_type", "setting", "enabled"],
+        requiredByAction: {
+            get: ["channel_type"],
+            enable: ["channel_type"],
+            disable: ["channel_type"],
+            restart: ["channel_type"],
+            configure: ["channel_type", "setting", "enabled"],
+        },
+    });
+    registerToolMetadata("sessions_manage", {
+        validActions: ["delete", "reset", "export", "compact"],
+        validKeys: ["action", "session_key", "instructions"],
+        requiredByAction: {
+            delete: ["session_key"],
+            reset: ["session_key"],
+            export: ["session_key"],
+            compact: ["session_key"],
+        },
+    });
+    registerToolMetadata("skills_manage", {
+        validActions: ["list", "import", "delete", "create", "update"],
+        validKeys: ["action", "url", "name", "content", "description", "scope"],
+        requiredByAction: {
+            import: ["url"],
+            delete: ["name"],
+            create: ["name", "content"],
+            update: ["name", "content"],
+        },
+    });
+    registerToolMetadata("memory_manage", {
+        validActions: ["stats", "browse", "delete", "flush", "export"],
+        validKeys: [
+            "action", "tenant_id", "agent_id", "ids", "offset", "limit", "sort",
+            "memory_type", "trust_level", "tags",
+        ],
+        // tenant_id / agent_id are scope filters with defaults; only ids is
+        // strictly required (for delete).
+        requiredByAction: {
+            delete: ["ids"],
+        },
+    });
+    registerToolMetadata("models_manage", {
+        validActions: ["list", "test", "list_providers"],
+        validKeys: ["action", "provider", "model"],
+        requiredByAction: {
+            test: ["provider", "model"],
+        },
+    });
+    registerToolMetadata("heartbeat_manage", {
+        validActions: ["get", "update", "status", "trigger"],
+        validKeys: [
+            "action", "agent_id", "enabled", "interval_ms", "prompt", "model",
+            "target_channel_type", "target_channel_id", "target_chat_id", "target_is_dm",
+            "light_context", "show_ok", "show_alerts", "allow_dm",
+            "skip_heartbeat_only_delivery", "ack_max_chars", "response_prefix", "session",
+            "alert_threshold", "alert_cooldown_ms", "stale_ms",
+        ],
+        // Every action's params beyond `action` are Type.Optional. Empty
+        // requiredByAction still gates unknown action values + unknown keys via
+        // validActions / validKeys.
+        requiredByAction: {},
+    });
+    // =========================================================================
+    // Output Schemas
+    // =========================================================================
+    registerToolMetadata("read", {
+        outputSchema: {
+            type: "object",
+            description: "File read metadata",
+            properties: {
+                totalLines: { type: "number", description: "Total lines in file" },
+                startLine: { type: "number", description: "First line returned (1-based)" },
+                endLine: { type: "number", description: "Last line returned (1-based)" },
+                sizeBytes: { type: "number", description: "File size in bytes" },
+                encoding: { type: "string", description: "Detected encoding (utf-8, utf-16le, latin1)" },
+                paginated: { type: "boolean", description: "True when offset/limit cropped the output" },
+                notebook: { type: "boolean", description: "True for .ipynb files" },
+                cells: { type: "number", description: "Number of notebook cells (notebooks only)" },
+                pdf: { type: "boolean", description: "True for PDF files" },
+                pageCount: { type: "number", description: "Pages extracted (PDFs only)" },
+                totalPages: { type: "number", description: "Total pages in PDF" },
+            },
+        },
+    });
+    registerToolMetadata("grep", {
+        outputSchema: {
+            type: "string",
+            description: "Text output (not JSON). Default mode: `filepath:linenum: content` per line. " +
+                "files_with_matches mode: one filepath per line. " +
+                "count mode: `filepath: N matches` per line, sorted descending. " +
+                "Trailing `[...]` notices indicate truncation or limits.",
+        },
+    });
+    registerToolMetadata("find", {
+        outputSchema: {
+            type: "string",
+            description: "Text output (not JSON). Newline-separated file paths sorted by modification time (most recent first). " +
+                "Paths relative to workspace root. Trailing `[...]` notices for truncation.",
+        },
+    });
+    registerToolMetadata("exec", {
+        outputSchema: {
+            type: "object",
+            description: "Shell command execution result",
+            properties: {
+                exitCode: { type: "number", description: "0 = success, 124 = timeout" },
+                stdout: { type: "string", description: "Standard output" },
+                stderr: { type: "string", description: "Standard error" },
+                description: { type: "string", description: "User-provided command label" },
+                truncated: { type: "boolean", description: "True when output exceeded buffer" },
+                fullOutputPath: { type: "string", description: "Path to full output on disk" },
+            },
+        },
+    });
+    registerToolMetadata("memory_search", {
+        outputSchema: {
+            type: "object",
+            description: "Memory search results",
+            properties: {
+                results: {
+                    type: "array",
+                    description: "Matching entries (content max 500 chars each)",
+                    items: {
+                        type: "object",
+                        properties: {
+                            id: { type: "string" },
+                            content: { type: "string" },
+                            score: { type: "number" },
+                            tags: { type: "array", items: { type: "string" } },
+                            createdAt: { type: "number", description: "Epoch ms" },
+                        },
+                    },
+                },
+            },
+        },
+    });
+    registerToolMetadata("web_search", {
+        outputSchema: {
+            type: "object",
+            description: "Web search results. List-based providers (Brave/Tavily) return results[]. " +
+                "Perplexity/Grok return { content, citations } instead.",
+            properties: {
+                query: { type: "string" },
+                provider: { type: "string" },
+                tookMs: { type: "number" },
+                results: {
+                    type: "array",
+                    description: "List-based provider results",
+                    items: {
+                        type: "object",
+                        properties: {
+                            title: { type: "string" },
+                            url: { type: "string" },
+                            description: { type: "string" },
+                        },
+                    },
+                },
+            },
+        },
+    });
+    registerToolMetadata("sessions_list", {
+        outputSchema: {
+            type: "object",
+            description: "Active sessions listing",
+            properties: {
+                sessions: {
+                    type: "array",
+                    items: {
+                        type: "object",
+                        properties: {
+                            sessionKey: { type: "string" },
+                            agentId: { type: "string" },
+                            userId: { type: "string" },
+                            channelId: { type: "string" },
+                            kind: { type: "string" },
+                            messageCount: { type: "number" },
+                            totalTokens: { type: "number" },
+                            updatedAt: { type: "number" },
+                            createdAt: { type: "number" },
+                        },
+                    },
+                },
+                total: { type: "number", description: "Total session count" },
+            },
+        },
+    });
+    // =========================================================================
+    // Search Hints
+    // =========================================================================
+    // --- Session tools ---
+    registerToolMetadata("sessions_list", { searchHint: "active sessions connections users online list enumerate" });
+    registerToolMetadata("sessions_history", { searchHint: "chat log transcript conversation history messages past" });
+    registerToolMetadata("sessions_send", { searchHint: "send reply respond direct message channel session inject" });
+    registerToolMetadata("sessions_spawn", { searchHint: "delegate subagent background async child worker spawn" });
+    registerToolMetadata("subagents", { searchHint: "parallel fan-out concurrent multi-agent batch delegate" });
+    registerToolMetadata("pipeline", { searchHint: "workflow dag graph orchestrate chain multi-step sequential" });
+    registerToolMetadata("session_status", { searchHint: "session state alive running progress heartbeat check" });
+    registerToolMetadata("session_search", { searchHint: "find session lookup filter match query user channel" });
+    // --- Platform tools ---
+    registerToolMetadata("cron", { searchHint: "schedule timer reminder recurring job automation crontab interval" });
+    registerToolMetadata("gateway", { searchHint: "config restart patch status settings yaml update system admin" });
+    registerToolMetadata("image_analyze", { searchHint: "vision ocr describe photo picture identify detect recognize" });
+    registerToolMetadata("tts_synthesize", { searchHint: "speech voice audio speak narrate text-to-speech vocalize" });
+    registerToolMetadata("transcribe_audio", { searchHint: "stt speech-to-text whisper dictation voice recording audio" });
+    registerToolMetadata("describe_video", { searchHint: "video clip movie mp4 mov webm scene describe motion visual" });
+    // --- Document and browser tools ---
+    registerToolMetadata("extract_document", { searchHint: "pdf csv docx xlsx parse text content extract spreadsheet" });
+    registerToolMetadata("browser", { searchHint: "chrome headless puppeteer navigate click screenshot scrape" });
+    // --- Context tools ---
+    registerToolMetadata("ctx_search", { searchHint: "rag context knowledge semantic embedding retrieve similar" });
+    registerToolMetadata("ctx_inspect", { searchHint: "context detail metadata source provenance inspect entry" });
+    registerToolMetadata("ctx_expand", { searchHint: "context expand elaborate detail follow-up deeper related" });
+    registerToolMetadata("ctx_recall", { searchHint: "memory recall remember fact previous mentioned earlier" });
+    // --- Platform channel actions ---
+    registerToolMetadata("discord_action", { searchHint: "pin kick ban roles threads channels guild server discord" });
+    registerToolMetadata("telegram_action", { searchHint: "pin poll sticker admin topics group supergroup telegram" });
+    registerToolMetadata("slack_action", { searchHint: "pin react thread channel topic archive bookmark slack" });
+    registerToolMetadata("whatsapp_action", { searchHint: "status group admin label broadcast forward whatsapp" });
+    // --- Privileged management tools ---
+    registerToolMetadata("agents_manage", { searchHint: "fleet list create delete suspend resume agent configure roster inventory" });
+    registerToolMetadata("obs_query", { searchHint: "diagnostics monitoring metrics billing traces logs health" });
+    registerToolMetadata("sessions_manage", { searchHint: "delete reset export compact session lifecycle cleanup admin" });
+    registerToolMetadata("memory_manage", { searchHint: "delete flush export browse stats storage cleanup purge" });
+    registerToolMetadata("channels_manage", { searchHint: "enable disable restart channel adapter platform connection" });
+    registerToolMetadata("tokens_manage", { searchHint: "api key token rotate revoke generate auth credential" });
+    registerToolMetadata("models_manage", { searchHint: "llm provider model switch configure cost tier pricing" });
+    registerToolMetadata("skills_manage", { searchHint: "skill plugin capability register unregister enable toggle" });
+    registerToolMetadata("mcp_manage", { searchHint: "mcp server protocol connect disconnect tool external" });
+    registerToolMetadata("heartbeat_manage", { searchHint: "heartbeat keepalive watchdog health probe interval alive" });
+    // =========================================================================
+    // Co-discovery Relationships
+    // =========================================================================
+    // Model switching requires both models_manage (catalog) and agents_manage (apply model to agent)
+    registerToolMetadata("models_manage", { coDiscoverWith: ["agents_manage"] });
+    registerToolMetadata("agents_manage", { coDiscoverWith: ["models_manage"] });
+}