comisai 1.0.36 → 1.0.40

package/node_modules/@comis/daemon/dist/wiring/setup-tools.js

@@ -1,17 +1,31 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
  * Tool assembly setup: assembleToolsForAgent and preprocessMessageText.
- * Extracted from daemon.ts steps 6.6.8.5 (tool pipeline assembly) to isolate
- * per-agent tool creation and message preprocessing from the main wiring
- * sequence.
+ * Isolates per-agent tool creation and message preprocessing from the
+ * main wiring sequence.
  * @module
  */
 import { isAbsolute, resolve } from "node:path";
-import { enterConfigMutationFence, leaveConfigMutationFence } from "../rpc/persist-to-config.js";
-import { SkillsConfigSchema, sanitizeLogString, tryGetContext, parseFormattedSessionKey, safePath, formatSessionKey } from "@comis/core";
-import { sessionKeyToPath, WORKSPACE_FILE_NAMES, DEFAULT_TEMPLATES, registerWorkspaceFilesInTracker, } from "@comis/agent";
+import { enterConfigMutationFence, leaveConfigMutationFence } from "../api/shared/persist-to-config.js";
+import { SkillsConfigSchema, sanitizeLogString, tryGetContext, parseFormattedSessionKey, safePath, formatSessionKey, } from "@comis/core";
+import { sessionKeyToPath } from "@comis/agent";
+// Workspace helpers live in @comis/core.
+import { WORKSPACE_FILE_NAMES, DEFAULT_TEMPLATES, registerWorkspaceFilesInTracker, } from "@comis/core";
 import { stat as fsStat } from "node:fs/promises";
-import { assembleToolPipeline, createFileStateTracker, createCronTool, createUnifiedMemoryTool, createUnifiedSessionTool, createUnifiedContextTool, createMessageTool, createDiscordActionTool, createTelegramActionTool, createSlackActionTool, createWhatsAppActionTool, createSessionsSendTool, createSessionsSpawnTool, createSubagentsTool, createPipelineTool, createImageTool, createTTSTool, createTranscribeAudioTool, createDescribeVideoTool, createExtractDocumentTool, createGatewayTool, createBrowserTool, createAgentsManageTool, createObsQueryTool, createSessionsManageTool, createModelsManageTool, createTokensManageTool, createChannelsManageTool, createSkillsManageTool, createMcpManageTool, createHeartbeatManageTool, createProvidersManageTool, createNotifyTool, createImageGenerateTool, createBackgroundTasksTool, createExecTool, createProcessTool, createProcessRegistry, createApplyPatchTool, sanitizeImageForApi, createMediaPersistenceService, createCredentialInjector, mcpToolsToAgentTools, TOOL_PROFILES, TOOL_GROUPS, } from "@comis/skills";
+// Skills-concern symbols staying on the `.` subpath (policy, pipeline, MCP
+// bridge, credential injection, link understanding). These symbols live
+// in packages/skills/src/skills/index.ts.
+import { TOOL_PROFILES, TOOL_GROUPS, assembleToolPipeline, mcpToolsToAgentTools, createCredentialInjector, } from "@comis/skills";
+// Tool capability adapters + factories live on the `./tools` subpath.
+// Exec / process / apply-patch tool factories, file-state tracker,
+// media-persistence / image-sanitizer all live under
+// packages/skills/src/tools/. Daemon imports them from the dedicated
+// subpath to surface the architectural boundary in the type system.
+import { createExecTool, createProcessTool, createProcessRegistry, createApplyPatchTool, createFileStateTracker, sanitizeImageForApi, createMediaPersistenceService, } from "@comis/skills/tools";
+// Descriptor registry on the `./platform-tools` subpath. Replaces the
+// prior inline 38-call enumeration of `createXTool(agentRpc, ...)`
+// factories.
+import { createPlatformToolRegistry, } from "@comis/skills/platform-tools";
 // ---------------------------------------------------------------------------
 // Setup function
 // ---------------------------------------------------------------------------
@@ -33,6 +47,18 @@ export function setupTools(deps) {
      * repeats on every LLM call even though the underlying state is fixed at
      * daemon startup (detectSandboxProvider runs once). */
     const warnedNoSandboxAgents = new Set();
+    /**
+     * Platform-tool descriptor registry -- single source of truth for the 45
+     * platform-tools. Constructed once at `setupTools` invocation (the set is
+     * static at module-load time). Daemon's per-agent assembly filters the
+     * registry by `conditional` predicates and invokes each surviving
+     * descriptor's `build(ctx)` callback with a runtime context. This replaces
+     * the prior 175-line `agentPlatformTools` closure that hand-enumerated
+     * 38 `createXTool(agentRpc, ...)` factory calls. The exec / process /
+     * apply-patch tools stay enumerated inline below — they are `./tools`
+     * subpath (built-in non-platform).
+     */
+    const PLATFORM_TOOL_REGISTRY = createPlatformToolRegistry();
     function getOrCreateRegistry(agentId) {
         let registry = processRegistries.get(agentId);
         if (!registry) {
@@ -117,7 +143,7 @@ export function setupTools(deps) {
         // admin agents are covered by agents_manage's onAgentCreated callback.
         const ownWorkspaceDir = workspaceDirs.get(agentId) ?? defaultWorkspaceDir;
         await registerWorkspaceFilesInTracker(ownWorkspaceDir, fileStateTracker, skillsLogger);
-        // Enrich sharedPaths for admin-trust agents: grant cross-workspace file access (Quick 165)
+        // Enrich sharedPaths for admin-trust agents: grant cross-workspace file access.
         // Default agent (orchestrator) and supervisor-profile agents can access other agent workspaces.
         // Lazy callback for admin agents so hot-added workspaces are visible without re-assembling tools.
         const isDefaultAgent = agentId === defaultAgentId;
@@ -134,7 +160,7 @@ export function setupTools(deps) {
             }
             : [...(sharedPaths ?? [])]; // Non-admin: static empty array (no change)
         const agentConfig = agents[agentId] ?? agents[defaultAgentId];
-        // Use the agent's own skills config (SkillsConfigSchema defaults apply if not specified)
+        // Use the agent's own skills config (SkillsConfigSchema defaults apply if not specified).
         const skillsConfig = agentConfig?.skills ?? SkillsConfigSchema.parse({});
         // Resolve relative discoveryPaths against dataDir so ./skills -> ~/.comis/skills
         const agentWorkspaceSkillsDir = safePath(workspaceDirs.get(agentId) ?? defaultWorkspaceDir, "skills");
@@ -147,95 +173,74 @@ export function setupTools(deps) {
         if (!readOnlyPaths.includes(logsDir)) {
             readOnlyPaths.push(logsDir);
         }
-        // Create per-agent rpcCall that injects _agentId
+        // Create per-agent rpcCall that injects _agentId.
         const agentRpc = createAgentRpcCall(agentId);
+        // Per-agent build context for the descriptor registry. The platform-tool
+        // factory calls live in packages/skills/src/platform-tools/registry.ts.
+        // The 4 truly-conditional tools (background_tasks, image_generate,
+        // unified_context, browser) carry `conditional` predicates on the
+        // registry side; daemon filters via .filter(d => !d.conditional ||
+        // d.conditional(ctx)) BEFORE invoking d.build(ctx).
+        //
+        // The agents-manage callbacks (onMutationStart / onMutationEnd /
+        // onAgentCreated) are NOT a conditional -- they're complex args passed
+        // unconditionally via the build context.
+        //
+        // The exec/process/apply-patch tools remain enumerated inline below the
+        // registry call (their per-call config involves the sandbox provider,
+        // workspace dir, tool-results dir resolver, and capability port -- too
+        // complex to fit the descriptor `build(ctx)` shape; they're `./tools`
+        // subpath, not platform-tools, so they don't belong in the platform-tool
+        // registry).
         const agentPlatformTools = () => {
-            const tools = [
-                createCronTool(agentRpc),
-                createUnifiedMemoryTool(agentRpc, approvalGate),
-                createUnifiedSessionTool(agentRpc),
-                createMessageTool(agentRpc),
-                createDiscordActionTool(agentRpc, skillsLogger),
-                createTelegramActionTool(agentRpc),
-                createSlackActionTool(agentRpc),
-                createWhatsAppActionTool(agentRpc),
-                createSessionsSendTool(agentRpc),
-                createSessionsSpawnTool(agentRpc),
-                createSubagentsTool(agentRpc, skillsLogger),
-                createPipelineTool(agentRpc, skillsLogger, approvalGate),
-                createImageTool(agentRpc),
-                createTTSTool(agentRpc),
-                createTranscribeAudioTool(agentRpc),
-                createDescribeVideoTool(agentRpc),
-                createExtractDocumentTool(agentRpc),
-                createGatewayTool(agentRpc, skillsLogger),
-                createAgentsManageTool(agentRpc, skillsLogger, approvalGate, {
-                    onMutationStart: enterConfigMutationFence,
-                    onMutationEnd: leaveConfigMutationFence,
-                    // After agents.create seeds the new workspace's template files
-                    // (IDENTITY.md, ROLE.md, etc.) via ensureWorkspace, register those
-                    // seeded paths in THIS session's tracker so the caller LLM can
-                    // overwrite them via `write` without hitting the [not_read] gate.
-                    // Each file path is absolute; the seeded content is deterministic
-                    // (DEFAULT_TEMPLATES[name]), so we register the known mtime + content.
-                    onAgentCreated: async ({ workspaceDir }) => {
-                        if (!workspaceDir)
-                            return;
-                        for (const name of WORKSPACE_FILE_NAMES) {
-                            const filePath = safePath(workspaceDir, name);
-                            try {
-                                const st = await fsStat(filePath);
-                                // Idempotency: skip when tracker already records this path at
-                                // the same mtime -- avoids redundant recordRead work when the
-                                // same admin session creates the same agent twice (e.g. create,
-                                // delete, re-create within one turn).
-                                const existing = fileStateTracker.getReadState(filePath);
-                                if (existing && existing.mtime === st.mtimeMs)
-                                    continue;
-                                fileStateTracker.recordRead(filePath, st.mtimeMs, 0, undefined, Buffer.from(DEFAULT_TEMPLATES[name], "utf-8"));
-                            }
-                            catch {
-                                /* file absent or stat failed -- skip registration */
-                            }
+            const ctx = {
+                agentId,
+                rpcCall: agentRpc,
+                skillsLogger,
+                approvalGate,
+                eventBus,
+                imageGenProvider: deps.imageGenProvider,
+                backgroundTaskManager: deps.backgroundTaskManager,
+                toolCapabilityPort: deps.getCapabilityPortForAgent(agentId),
+                contextEngineVersion: agentConfig?.contextEngine?.version ?? "pipeline",
+                builtinToolsBrowserEnabled: skillsConfig.builtinTools.browser,
+                onConfigMutationStart: enterConfigMutationFence,
+                onConfigMutationEnd: leaveConfigMutationFence,
+                // After agents.create seeds the new workspace's template files
+                // (IDENTITY.md, ROLE.md, etc.) via ensureWorkspace, register those
+                // seeded paths in THIS session's tracker so the caller LLM can
+                // overwrite them via `write` without hitting the [not_read] gate.
+                // Each file path is absolute; the seeded content is deterministic
+                // (DEFAULT_TEMPLATES[name]), so we register the known mtime + content.
+                onAgentCreated: async ({ workspaceDir }) => {
+                    if (!workspaceDir)
+                        return;
+                    for (const name of WORKSPACE_FILE_NAMES) {
+                        const filePath = safePath(workspaceDir, name);
+                        try {
+                            const st = await fsStat(filePath);
+                            // Idempotency: skip when tracker already records this path at
+                            // the same mtime -- avoids redundant recordRead work when the
+                            // same admin session creates the same agent twice (e.g. create,
+                            // delete, re-create within one turn).
+                            const existing = fileStateTracker.getReadState(filePath);
+                            if (existing && existing.mtime === st.mtimeMs)
+                                continue;
+                            fileStateTracker.recordRead(filePath, st.mtimeMs, 0, undefined, Buffer.from(DEFAULT_TEMPLATES[name], "utf-8"));
                         }
-                    },
-                }),
-                createObsQueryTool(agentRpc),
-                createSessionsManageTool(agentRpc, approvalGate),
-                createModelsManageTool(agentRpc),
-                createProvidersManageTool(agentRpc, approvalGate, {
-                    onMutationStart: enterConfigMutationFence,
-                    onMutationEnd: leaveConfigMutationFence,
-                }),
-                createTokensManageTool(agentRpc, approvalGate),
-                createChannelsManageTool(agentRpc, approvalGate),
-                createSkillsManageTool(agentRpc, approvalGate),
-                createMcpManageTool(agentRpc, approvalGate),
-                createHeartbeatManageTool(agentRpc),
-                createNotifyTool(agentRpc),
-            ];
-            // Background tasks tool -- always registered (any user can check their tasks)
-            if (deps.backgroundTaskManager) {
-                tools.push(createBackgroundTasksTool({ manager: deps.backgroundTaskManager, agentId }));
-            }
-            // Image generation tool only when provider available (API key present)
-            if (deps.imageGenProvider) {
-                tools.push(createImageGenerateTool(agentRpc));
-            }
-            // Conditional: DAG context tools
-            const ceVersion = agentConfig?.contextEngine?.version ?? "pipeline";
-            if (ceVersion === "dag") {
-                tools.push(createUnifiedContextTool(agentRpc));
-            }
-            // Browser tool is conditional on builtinTools.browser config toggle
-            if (skillsConfig.builtinTools.browser) {
-                tools.push(createBrowserTool({
-                    rpcCall: agentRpc,
-                    sanitizeImage: sanitizeImageForApi,
-                    persistMedia: getOrCreateScreenshotPersistence(agentId),
-                    workspaceDir: workspaceDirs.get(agentId) ?? defaultWorkspaceDir,
-                }));
-            }
+                        catch {
+                            /* file absent or stat failed -- skip registration */
+                        }
+                    }
+                },
+                browserSanitizeImage: sanitizeImageForApi,
+                browserPersistMedia: getOrCreateScreenshotPersistence(agentId),
+                browserWorkspaceDir: workspaceDirs.get(agentId) ?? defaultWorkspaceDir,
+            };
+            const tools = PLATFORM_TOOL_REGISTRY
+                .filter((d) => !d.conditional || d.conditional(ctx))
+                .map((d) => d.build(ctx))
+                .filter((t) => t !== undefined);
             // Build per-agent sandbox config from daemon provider + agent config
             const sandboxCfg = skillsConfig.execSandbox.enabled === "always" && sandboxProvider
                 ? {
@@ -262,26 +267,48 @@ export function setupTools(deps) {
                 const agentWorkspaceDir = workspaceDirs.get(agentId) ?? defaultWorkspaceDir;
                 // Getter for session tool-results dir, resolved at call time via ALS context.
                 // Matches session path pattern from comis-session-manager + microcompaction-guard.
+                // Renamed local from `ctx` to `alsCtx` to avoid shadowing the outer
+                // `PlatformToolBuildContext` variable created for the registry call.
                 const getToolResultsDir = () => {
-                    const ctx = tryGetContext();
-                    if (!ctx?.sessionKey)
+                    const alsCtx = tryGetContext();
+                    if (!alsCtx?.sessionKey)
                         return undefined;
-                    const parsed = parseFormattedSessionKey(ctx.sessionKey);
+                    const parsed = parseFormattedSessionKey(alsCtx.sessionKey);
                     if (!parsed)
                         return undefined;
                     const sessionBaseDir = safePath(agentWorkspaceDir, "sessions");
                     const sessionDir = sessionKeyToPath(parsed, sessionBaseDir);
                     return safePath(sessionDir, "tool-results");
                 };
-                tools.push(createExecTool(agentWorkspaceDir, registry, secretManager, platformSecretNames, skillsLogger, subprocessEnv, // Filtered subprocess environment
-                sandboxCfg, // Per-agent sandbox config
-                eventBus, // command:blocked + secret:accessed audit events
-                getToolResultsDir));
+                tools.push(createExecTool({
+                    workspacePath: agentWorkspaceDir,
+                    registry,
+                    secretManager,
+                    platformSecretNames,
+                    logger: skillsLogger,
+                    subprocessEnv, // Filtered subprocess environment
+                    sandboxConfig: sandboxCfg, // Per-agent sandbox config
+                    eventBus, // command:blocked + secret:accessed audit events
+                    getToolResultsDir, // Session tool-results dir for output persistence
+                    // Live per-agent ToolCapabilityPort resolver populated by daemon.ts
+                    // from AgentsResult.toolCapabilityPorts map. Single mandated form
+                    // `deps.<field>(agentId)` mirrors the surrounding direct-deps-access
+                    // convention.
+                    toolCapabilityPort: deps.getCapabilityPortForAgent(agentId),
+                    approvalGate, // Soft-stop override path
+                }));
             }
             // Process tool -- always instantiated; builtinTools ceiling applied after profile filtering
             {
                 const registry = getOrCreateRegistry(agentId);
-                tools.push(createProcessTool(registry, skillsLogger));
+                tools.push(createProcessTool({
+                    registry,
+                    logger: skillsLogger,
+                    // Live per-agent ToolCapabilityPort resolver populated by daemon.ts
+                    // from AgentsResult.toolCapabilityPorts. Single mandated form
+                    // `deps.<field>(agentId)`.
+                    toolCapabilityPort: deps.getCapabilityPortForAgent(agentId),
+                }));
             }
             // Apply patch tool -- always included, gated by tool policy
             tools.push(createApplyPatchTool(workspaceDirs.get(agentId) ?? defaultWorkspaceDir, effectiveSharedPaths, skillsLogger));

package/node_modules/@comis/daemon/dist/wiring/tool-capability-adapter.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Live ToolCapabilityPort adapter -- daemon-side wiring.
+ *
+ * Factory whose 9 frozen methods read live state from:
+ *   - `deps.toolingConfig`        (operator config; the `tooling.*` subtree)
+ *   - `deps.skillRegistry`        (already applies allow/deny + eligibility +
+ *                                   disableModelInvocation filters)
+ *   - `deps.mcpClientManager`     (live MCP connection state per server)
+ *
+ * Cross-field cluster-ID validation runs at construction time across three
+ * surfaces (`builtinAssignments`, `mcp.capabilityHints[*].cluster`,
+ * `skills.capabilityHints[*].cluster`). Operator typos emit a Pino WARN with
+ *   { errorKind: "config", configPath, unresolvedClusterId, hint }
+ * and DO NOT throw -- lookup-time fallback applies (`external-integrations`
+ * for unresolved MCP clusters; `prompt-skills` for unresolved skill clusters).
+ * WARN (not DEBUG) is intentional: operator visibility for misconfiguration.
+ *
+ * Default merge contract: `mergedClusters = { ...DEFAULT_CLUSTER_CONFIG,
+ * ...operator.clusters }` because `z.record(...).default({})` would replace
+ * the entire record. Empty operator config preserves the 3 reserved IDs;
+ * partial-add preserves defaults plus addition; per-key override wins for the
+ * overridden key only. The same shape applies to `mergedBuiltinAssignments`.
+ *
+ * Liveness:
+ *   - `getConnectedMcpServers()` filters `getAllConnections()` by
+ *     `c.status === "connected"` on EVERY call -- never cached at construction
+ *     (TOCTOU mitigation).
+ *   - `getPackageAliasMap()` rebuilds fresh per call from operator MCP hints +
+ *     visible skills + universal MCP fallback. No memoization.
+ *   - `getPromptSkillCapabilities()` re-invokes `skillRegistry`'s sweep on
+ *     every call; the operator-hint callback resolves through `port.getSkillHint`
+ *     at call time (the arrow lambda holds the `port` reference, not a
+ *     snapshot of `getSkillHint`).
+ *
+ * Returned port is `Object.freeze`d -- post-construction tampering is
+ * structurally impossible in strict mode (silently no-ops in sloppy mode).
+ *
+ * Boundary discipline: production source MUST NOT import test stubs from
+ * `@comis/core/__test-helpers/`.
+ *
+ * @module
+ */
+import type { ToolCapabilityPort, ToolingConfig } from "@comis/core";
+import type { SkillRegistry, McpClientManager } from "@comis/skills";
+import type { ComisLogger } from "@comis/infra";
+/**
+ * Dependencies for the live ToolCapabilityPort adapter.
+ *
+ * Receivers MUST hold the daemon's container.config.tooling slice (NOT the
+ * top-level AppConfig) and the live skill registry / MCP client manager
+ * instances -- the adapter closes over them and re-reads on every method call.
+ */
+export interface ToolCapabilityAdapterDeps {
+    readonly toolingConfig: ToolingConfig;
+    readonly skillRegistry: SkillRegistry;
+    readonly mcpClientManager: McpClientManager;
+    readonly logger: ComisLogger;
+}
+/**
+ * Build the live ToolCapabilityPort adapter.
+ *
+ * Pure synchronous function. Construction-time work:
+ *   - Key-by-key merge of `DEFAULT_CLUSTER_CONFIG` with operator clusters.
+ *   - Key-by-key merge of `DEFAULT_BUILTIN_ASSIGNMENTS` with operator assignments.
+ *   - Cross-field cluster-ID validation across 3 surfaces (one Pino WARN per
+ *     unresolved reference; never throws).
+ *
+ * Lookup-time work:
+ *   - All 9 port methods are closures over the merged maps + the live
+ *     `skillRegistry` / `mcpClientManager` references.
+ *
+ * @param deps - The adapter's dependencies.
+ * @returns A frozen `ToolCapabilityPort`.
+ */
+export declare function createToolCapabilityAdapter(deps: ToolCapabilityAdapterDeps): ToolCapabilityPort;

package/node_modules/@comis/daemon/dist/wiring/tool-capability-adapter.js

@@ -0,0 +1,253 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Live ToolCapabilityPort adapter -- daemon-side wiring.
+ *
+ * Factory whose 9 frozen methods read live state from:
+ *   - `deps.toolingConfig`        (operator config; the `tooling.*` subtree)
+ *   - `deps.skillRegistry`        (already applies allow/deny + eligibility +
+ *                                   disableModelInvocation filters)
+ *   - `deps.mcpClientManager`     (live MCP connection state per server)
+ *
+ * Cross-field cluster-ID validation runs at construction time across three
+ * surfaces (`builtinAssignments`, `mcp.capabilityHints[*].cluster`,
+ * `skills.capabilityHints[*].cluster`). Operator typos emit a Pino WARN with
+ *   { errorKind: "config", configPath, unresolvedClusterId, hint }
+ * and DO NOT throw -- lookup-time fallback applies (`external-integrations`
+ * for unresolved MCP clusters; `prompt-skills` for unresolved skill clusters).
+ * WARN (not DEBUG) is intentional: operator visibility for misconfiguration.
+ *
+ * Default merge contract: `mergedClusters = { ...DEFAULT_CLUSTER_CONFIG,
+ * ...operator.clusters }` because `z.record(...).default({})` would replace
+ * the entire record. Empty operator config preserves the 3 reserved IDs;
+ * partial-add preserves defaults plus addition; per-key override wins for the
+ * overridden key only. The same shape applies to `mergedBuiltinAssignments`.
+ *
+ * Liveness:
+ *   - `getConnectedMcpServers()` filters `getAllConnections()` by
+ *     `c.status === "connected"` on EVERY call -- never cached at construction
+ *     (TOCTOU mitigation).
+ *   - `getPackageAliasMap()` rebuilds fresh per call from operator MCP hints +
+ *     visible skills + universal MCP fallback. No memoization.
+ *   - `getPromptSkillCapabilities()` re-invokes `skillRegistry`'s sweep on
+ *     every call; the operator-hint callback resolves through `port.getSkillHint`
+ *     at call time (the arrow lambda holds the `port` reference, not a
+ *     snapshot of `getSkillHint`).
+ *
+ * Returned port is `Object.freeze`d -- post-construction tampering is
+ * structurally impossible in strict mode (silently no-ops in sloppy mode).
+ *
+ * Boundary discipline: production source MUST NOT import test stubs from
+ * `@comis/core/__test-helpers/`.
+ *
+ * @module
+ */
+import { DEFAULT_CLUSTER_CONFIG, DEFAULT_BUILTIN_ASSIGNMENTS, getToolMetadata, } from "@comis/core";
+// Module-level reference-stable empty alias map. Returned only when no
+// operator hints / visible skills / connected servers exist; downstream
+// callers can rely on stable identity for cheap equality checks.
+const EMPTY_ALIAS_MAP = new Map();
+/**
+ * PEP-503-like normalization for package alias keys.
+ *
+ * - npm scoped packages (`@scope/name`) are preserved as-is, lowercased.
+ * - Everything else: lowercased, with runs of `_`, `.`, `-` collapsed to a
+ *   single `-`.
+ *
+ * @param pkg - The raw package identifier from operator config or skill metadata.
+ * @returns The normalized key for `getPackageAliasMap`.
+ */
+function normalizeAliasKey(pkg) {
+    if (pkg.startsWith("@"))
+        return pkg.toLowerCase();
+    return pkg.toLowerCase().replace(/[_.-]+/g, "-");
+}
+/**
+ * Build the live ToolCapabilityPort adapter.
+ *
+ * Pure synchronous function. Construction-time work:
+ *   - Key-by-key merge of `DEFAULT_CLUSTER_CONFIG` with operator clusters.
+ *   - Key-by-key merge of `DEFAULT_BUILTIN_ASSIGNMENTS` with operator assignments.
+ *   - Cross-field cluster-ID validation across 3 surfaces (one Pino WARN per
+ *     unresolved reference; never throws).
+ *
+ * Lookup-time work:
+ *   - All 9 port methods are closures over the merged maps + the live
+ *     `skillRegistry` / `mcpClientManager` references.
+ *
+ * @param deps - The adapter's dependencies.
+ * @returns A frozen `ToolCapabilityPort`.
+ */
+export function createToolCapabilityAdapter(deps) {
+    const log = deps.logger.child({ submodule: "tool-capability-adapter" });
+    // Key-by-key default merge at adapter construction. Schema cannot supply
+    // DEFAULT_CLUSTER_CONFIG via `.default(...)` because z.record(...).default({})
+    // replaces the entire record.
+    const mergedClusters = {
+        ...DEFAULT_CLUSTER_CONFIG,
+        ...deps.toolingConfig.capabilityClusters.clusters,
+    };
+    const mergedBuiltinAssignments = {
+        ...DEFAULT_BUILTIN_ASSIGNMENTS,
+        ...deps.toolingConfig.capabilityClusters.builtinAssignments,
+    };
+    // Build the validation set once; used by all three loops AND by the lookup
+    // closures below (so a runtime typo also falls through to the documented
+    // fallback rather than silently substituting at lookup time).
+    const validClusterIds = new Set(Object.keys(mergedClusters));
+    // ---------------------------------------------------------------------------
+    // Cross-field cluster-ID validation (3 surfaces). Each loop emits one Pino
+    // WARN per unresolved reference. Construction is total -- no throws.
+    // ---------------------------------------------------------------------------
+    // Surface 1: builtinAssignments[toolName] -> clusterId
+    for (const [toolName, clusterId] of Object.entries(mergedBuiltinAssignments)) {
+        if (!validClusterIds.has(clusterId)) {
+            log.warn({
+                hint: `Add cluster '${clusterId}' to tooling.capabilityClusters.clusters or fix the reference at tooling.capabilityClusters.builtinAssignments.${toolName}`,
+                errorKind: "config",
+                configPath: `tooling.capabilityClusters.builtinAssignments.${toolName}`,
+                unresolvedClusterId: clusterId,
+            }, "Unresolved cluster ID in tooling config (builtinAssignments)");
+        }
+    }
+    // Surface 2: mcp.capabilityHints[serverName].cluster
+    for (const [serverName, hint] of Object.entries(deps.toolingConfig.mcp.capabilityHints)) {
+        if (!validClusterIds.has(hint.cluster)) {
+            log.warn({
+                hint: `Add cluster '${hint.cluster}' to tooling.capabilityClusters.clusters or fix the reference at tooling.mcp.capabilityHints.${serverName}.cluster`,
+                errorKind: "config",
+                configPath: `tooling.mcp.capabilityHints.${serverName}.cluster`,
+                unresolvedClusterId: hint.cluster,
+            }, "Unresolved cluster ID in tooling config (mcp.capabilityHints)");
+        }
+    }
+    // Surface 3: skills.capabilityHints[skillName].cluster
+    for (const [skillName, hint] of Object.entries(deps.toolingConfig.skills.capabilityHints)) {
+        if (!validClusterIds.has(hint.cluster)) {
+            log.warn({
+                hint: `Add cluster '${hint.cluster}' to tooling.capabilityClusters.clusters or fix the reference at tooling.skills.capabilityHints.${skillName}.cluster`,
+                errorKind: "config",
+                configPath: `tooling.skills.capabilityHints.${skillName}.cluster`,
+                unresolvedClusterId: hint.cluster,
+            }, "Unresolved cluster ID in tooling config (skills.capabilityHints)");
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Build the frozen port. All closures capture `deps`, `mergedClusters`,
+    // `mergedBuiltinAssignments`, and `validClusterIds` lexically; runtime state
+    // (MCP connections, visible skills) is re-read on every method call.
+    // ---------------------------------------------------------------------------
+    const port = Object.freeze({
+        isCapabilityIndexEnabled: () => deps.toolingConfig.capabilityIndex.enabled,
+        getInstallDetourMode: () => deps.toolingConfig.installDetours.mode,
+        getBuiltinCluster: (toolName) => {
+            // Operator override wins when it resolves; an unresolved override
+            // already triggered a construction-time WARN -- fall through to
+            // metadata so the caller never sees a phantom cluster ID.
+            const opOverride = mergedBuiltinAssignments[toolName];
+            if (opOverride !== undefined && validClusterIds.has(opOverride)) {
+                return opOverride;
+            }
+            const meta = getToolMetadata(toolName);
+            return meta?.capability?.cluster;
+        },
+        getClusterConfig: (clusterId) => mergedClusters[clusterId],
+        getMcpServerHint: (serverName) => {
+            const hint = deps.toolingConfig.mcp.capabilityHints[serverName];
+            if (!hint)
+                return undefined;
+            // Fallback: unresolved cluster -> "external-integrations".
+            const cluster = validClusterIds.has(hint.cluster)
+                ? hint.cluster
+                : "external-integrations";
+            return {
+                cluster,
+                description: hint.description,
+                replacesPackages: hint.replacesPackages,
+            };
+        },
+        getSkillHint: (skillName, skillKey) => {
+            // Precedence: operator(skillKey) > operator(skillName).
+            const hintByKey = skillKey
+                ? deps.toolingConfig.skills.capabilityHints[skillKey]
+                : undefined;
+            const hintByName = !hintByKey
+                ? deps.toolingConfig.skills.capabilityHints[skillName]
+                : undefined;
+            const hint = hintByKey ?? hintByName;
+            if (!hint)
+                return undefined;
+            // Fallback: unresolved cluster -> "prompt-skills".
+            const cluster = validClusterIds.has(hint.cluster)
+                ? hint.cluster
+                : "prompt-skills";
+            return {
+                cluster,
+                ...(hint.description !== undefined ? { description: hint.description } : {}),
+                replacesPackages: hint.replacesPackages,
+            };
+        },
+        getPackageAliasMap: () => {
+            // Fresh per call -- no memoization. Visible skills can change
+            // mid-session (file-watcher reloads, allow/deny edits); MCP servers
+            // connect/disconnect; capturing at construction would freeze stale
+            // state.
+            const skills = port.getPromptSkillCapabilities();
+            const connectedServers = port.getConnectedMcpServers();
+            const mcpHints = Object.entries(deps.toolingConfig.mcp.capabilityHints);
+            // Reference-stable empty result for cheap equality checks downstream.
+            if (mcpHints.length === 0 &&
+                skills.length === 0 &&
+                connectedServers.length === 0) {
+                return EMPTY_ALIAS_MAP;
+            }
+            const map = new Map();
+            // 1. Operator MCP hints -- replacesPackages entries point at the server.
+            for (const [serverName, hint] of mcpHints) {
+                for (const pkg of hint.replacesPackages) {
+                    const key = normalizeAliasKey(pkg);
+                    if (!map.has(key)) {
+                        map.set(key, { type: "mcp", name: serverName });
+                    }
+                }
+            }
+            // 2. Visible skills -- replacesPackages entries point at the skill.
+            // `port.getPromptSkillCapabilities()` reference resolves at call time;
+            // the lexical `port` const is in scope by the time
+            // `getPackageAliasMap` fires.
+            for (const skill of skills) {
+                for (const pkg of skill.replacesPackages) {
+                    const key = normalizeAliasKey(pkg);
+                    if (!map.has(key)) {
+                        map.set(key, { type: "skill", name: skill.name });
+                    }
+                }
+            }
+            // 3. Universal MCP fallback -- each connected server alias-keyed by its
+            // own name (so `pip install <serverName>` resolves to the server itself
+            // even without an operator-supplied replacesPackages entry).
+            for (const serverName of connectedServers) {
+                const key = normalizeAliasKey(serverName);
+                if (!map.has(key)) {
+                    map.set(key, { type: "mcp", name: serverName });
+                }
+            }
+            // Reference-stability guarantee (line 80-82 module docstring):
+            // the early-return shortcut above only fires when ALL three input
+            // sources are length-zero. Operator hints / skills / connected servers
+            // that produce zero map entries (e.g. every hint has
+            // `replacesPackages: []`) bypass that shortcut and would otherwise
+            // return a fresh empty map -- silently breaking the documented
+            // identity-stable empty-result contract. Re-check the size after the
+            // loops complete and collapse to the shared sentinel when empty.
+            if (map.size === 0)
+                return EMPTY_ALIAS_MAP;
+            return map;
+        },
+        getConnectedMcpServers: () => deps.mcpClientManager
+            .getAllConnections()
+            .filter((c) => c.status === "connected")
+            .map((c) => c.name),
+        getPromptSkillCapabilities: () => deps.skillRegistry.getPromptSkillCapabilities((skillName, skillKey) => port.getSkillHint(skillName, skillKey)),
+    });
+    return port;
+}

package/node_modules/@comis/daemon/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@comis/daemon",
   "private": true,
-  "version": "1.0.36",
+  "version": "1.0.40",
   "author": "Moshe Anconina",
   "license": "Apache-2.0",
   "description": "Background daemon and orchestrator for the Comis platform",

package/node_modules/@comis/gateway/dist/acp/acp-server.js

@@ -1,4 +1,5 @@
 // SPDX-License-Identifier: Apache-2.0
+// @allow-throw: ACP HTTP server route handler; throws caught by Hono framework error-handler boundary.
 /**
  * ACP Agent Server — Agent Communication Protocol implementation for IDE integration.
  *