comisai 1.0.34 → 1.0.37

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

@@ -0,0 +1,212 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Output retention housekeeper: scans the agent's output/ directory,
+ * deletes files whose age exceeds the per-class retentionMs.
+ *
+ * Mirrors setup-delivery.ts drain+prune timer pattern (single-tick gate +
+ * unref() + structured DEBUG log per pass).
+ *
+ * Consumes JSONL details.visibleDelivery for offline analysis (the
+ * housekeeper does NOT delete JSONL itself; it only manages output/
+ * files referenced by it).
+ *
+ * Per AGENTS §2.2: NO `path.join`, NO `process.env`. All paths via
+ *   `safePath(workspaceDir, ...)`. Per AGENTS §2.4: factory + Deps with
+ *   ComisLogger injected. Per AGENTS §2.1: error paths log WARN/DEBUG with
+ *   hint+errorKind; never throws. Per AGENTS §2.3 KISS: in-place file
+ *   deletion. No "trash dir", no "soft delete". Per AGENTS §6.6
+ *   (security/daemon): file deletion is destructive — operator can
+ *   disable via `enabled: false` config.
+ *
+ * Test contract: `validateOutputRetentionConfig({ classes:
+ * [{classId, retentionMs}] })` returns `{ ok, value | error }`.
+ *
+ * @module setup-output-retention
+ */
+import { readdirSync, statSync, unlinkSync } from "node:fs";
+import { safePath } from "@comis/core";
+import { ok, err, suppressError } from "@comis/shared";
+// ---------------------------------------------------------------------------
+// Validator (test contract gate)
+// ---------------------------------------------------------------------------
+/**
+ * Validate an output-retention config supplied as the legacy
+ * `{ classes: [{classId, retentionMs}] }` shape. Returns a Result-shaped
+ * `{ ok: true, value }` on success, `{ ok: false, error }` on failure.
+ *
+ * Validator contract:
+ *   - retentionMs = -1   → rejected
+ *   - retentionMs = 0    → rejected
+ *   - retentionMs = 1    → accepted
+ *
+ * Production wiring uses the Zod schema in
+ * @comis/core/config/schema-output-retention.ts directly; this
+ * validator is a thin compatibility surface for the test contract.
+ */
+export function validateOutputRetentionConfig(config) {
+    if (typeof config !== "object" || config === null) {
+        return err(new Error("output retention config must be an object"));
+    }
+    const obj = config;
+    if (!Array.isArray(obj.classes)) {
+        return err(new Error("output retention config: 'classes' must be an array"));
+    }
+    const out = [];
+    for (let i = 0; i < obj.classes.length; i++) {
+        const entry = obj.classes[i];
+        if (typeof entry !== "object" || entry === null) {
+            return err(new Error(`output retention config: classes[${i}] must be an object`));
+        }
+        const e = entry;
+        if (typeof e.classId !== "string" || e.classId.length === 0) {
+            return err(new Error(`output retention config: classes[${i}].classId must be a non-empty string`));
+        }
+        if (typeof e.retentionMs !== "number" ||
+            !Number.isInteger(e.retentionMs) ||
+            e.retentionMs <= 0) {
+            return err(new Error(`output retention config: classes[${i}].retentionMs must be a positive integer (got ${String(e.retentionMs)})`));
+        }
+        out.push({ classId: e.classId, retentionMs: e.retentionMs });
+    }
+    return ok({ classes: out });
+}
+// ---------------------------------------------------------------------------
+// Housekeeper factory
+// ---------------------------------------------------------------------------
+/**
+ * Wire the per-class output-retention housekeeper.
+ *
+ * Mirrors setup-delivery.ts (drain + prune timer): single-tick gate, .unref(),
+ * structured per-pass log. The factory starts the recurring interval
+ * immediately on construction; call shutdown() on system:shutdown.
+ *
+ * Returns a handle exposing `shutdown()` (idempotent) and `runOnePass()`
+ * (manual trigger for tests).
+ */
+export function setupOutputRetention(deps) {
+    const log = deps.logger.child({ submodule: "output-retention-housekeeper" });
+    // Defensive degradation: when config is undefined (legacy test mocks
+    // bypassing the AppConfig schema via `as unknown as`), behave as if
+    // disabled. Mirrors setupDeliveryMirror's optional-chain pattern.
+    // Production paths get a fully-defaulted config from
+    // AppConfigSchema.outputRetention, so this branch only triggers in
+    // tests with hand-constructed config objects.
+    if (!deps.config) {
+        log.debug({
+            hint: "Output retention config not present; housekeeper inactive (likely a hand-constructed test mock)",
+        }, "Output retention: no config");
+        return {
+            shutdown: () => { },
+            runOnePass: async () => ({ deleted: 0, bytesFreed: 0 }),
+        };
+    }
+    const config = deps.config;
+    let interval;
+    let running = null;
+    async function runOnePass() {
+        const outputDir = safePath(deps.workspaceDir, "output");
+        const now = Date.now();
+        let deleted = 0;
+        let bytesFreed = 0;
+        // Read class subdirectories under output/. Missing dir = nothing to do.
+        let classDirs;
+        try {
+            classDirs = readdirSync(outputDir);
+        }
+        catch {
+            log.debug({ outputDir, hint: "Output dir missing — nothing to retain yet" }, "Output retention: output dir not present");
+            return { deleted, bytesFreed };
+        }
+        for (const className of classDirs) {
+            // Resolve class config: explicit class, else fall back to "default".
+            const classConfig = config.classes[className] ?? config.classes.default;
+            if (!classConfig)
+                continue;
+            const classDir = safePath(outputDir, className);
+            let entries;
+            try {
+                entries = readdirSync(classDir);
+            }
+            catch (entryErr) {
+                log.debug({
+                    err: entryErr,
+                    classDir,
+                    hint: "Could not read class dir; will retry next pass",
+                    errorKind: "internal",
+                }, "Output retention: class dir read failed");
+                continue;
+            }
+            for (const entry of entries) {
+                const filePath = safePath(classDir, entry);
+                try {
+                    const stats = statSync(filePath);
+                    // Skip subdirectories — only retain leaf files. Per KISS, no
+                    // recursion: each retention class is a single flat directory.
+                    if (!stats.isFile())
+                        continue;
+                    const ageMs = now - stats.mtimeMs;
+                    if (ageMs > classConfig.retentionMs) {
+                        bytesFreed += stats.size;
+                        unlinkSync(filePath);
+                        deleted++;
+                    }
+                }
+                catch (fileErr) {
+                    log.debug({
+                        err: fileErr,
+                        filePath,
+                        hint: "Failed to inspect/delete file in housekeeper pass; will retry next pass",
+                        errorKind: "internal",
+                    }, "Output retention: file inspect/delete failed");
+                }
+            }
+        }
+        if (deleted > 0) {
+            log.info({
+                deleted,
+                bytesFreed,
+                class: "output_retention",
+                hint: "Per-class output retention completed; files older than configured retentionMs removed",
+            }, "Output retention: housekeeper pass completed");
+        }
+        else {
+            log.debug({ class: "output_retention", hint: "No files exceeded retentionMs this pass" }, "Output retention: nothing to delete");
+        }
+        return { deleted, bytesFreed };
+    }
+    function startInterval() {
+        if (!config.enabled) {
+            log.info({ hint: "Output retention disabled by config; not starting housekeeper" }, "Output retention: disabled");
+            return;
+        }
+        interval = setInterval(() => {
+            // Single-tick gate: in-flight Promise prevents overlapping ticks.
+            if (running)
+                return;
+            running = runOnePass()
+                .then(() => undefined)
+                .finally(() => {
+                running = null;
+            });
+            // Fire-and-forget: failures inside runOnePass are already logged
+            // and do not propagate (it never throws). suppressError satisfies
+            // the no-floating-promise lint without altering semantics.
+            suppressError(running, "output retention recurring tick");
+        }, config.intervalMs);
+        interval.unref();
+        log.info({
+            intervalMs: config.intervalMs,
+            classes: Object.keys(config.classes),
+            hint: "Output retention housekeeper started",
+        }, "Output retention: started");
+    }
+    function shutdown() {
+        if (interval) {
+            clearInterval(interval);
+            interval = undefined;
+        }
+    }
+    // Start immediately on construction (mirrors setup-delivery's startup pattern).
+    startInterval();
+    return { shutdown, runOnePass };
+}

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

@@ -108,6 +108,10 @@ export async function setupSchedulers(deps) {
                         payloadKind: job.payload.kind,
                         sessionStrategy: job.sessionStrategy,
                         maxHistoryTurns: job.maxHistoryTurns,
+                        // Cadence is a literal number only for kind === "every"; cron-expression
+                        // schedules would require parsing the expression to estimate a cadence,
+                        // which is out of scope. Consumers must treat undefined as "unknown".
+                        cadenceMs: job.schedule.kind === "every" ? job.schedule.everyMs : undefined,
                         cronJobModel: job.payload.kind === "agent_turn" ? job.payload.model : undefined,
                         cacheRetention: job.cacheRetention,
                         toolPolicy: job.toolPolicy,

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

@@ -1,11 +1,10 @@
 /**
  * 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 type { AppContainer, ApprovalGate, CredentialMappingPort, WrapExternalContentOptions, SessionKey } from "@comis/core";
+import type { AppContainer, ApprovalGate, CredentialMappingPort, WrapExternalContentOptions, SessionKey, ToolCapabilityPort } from "@comis/core";
 import type { ComisLogger } from "@comis/infra";
 import type { SessionTrackerRegistry } from "@comis/agent";
 import type { PerAgentConfig } from "@comis/core";
@@ -54,6 +53,21 @@ export interface ToolsDeps {
      * without requiring a daemon restart.
      */
     mcpClientManager: McpClientManager;
+    /**
+     * Per-agent ToolCapabilityPort resolver. Populated by daemon.ts from the
+     * AgentsResult.toolCapabilityPorts map (one adapter per agent constructed
+     * inside setupSingleAgent). Used by exec / process tools to consult the
+     * live install-detour mode + connected MCP servers + visible skills, and
+     * to read operator-supplied cluster hints. The closure may throw or fall
+     * back to the default agent's port for unknown agentIds -- daemon.ts
+     * decides the contract.
+     *
+     * Consumed via the single mandated form `deps.getCapabilityPortForAgent(agentId)`
+     * inside assembleToolsForAgent (mirrors the deps.<field> direct-access
+     * convention used for nearby fields like deps.eventBus, deps.skillsLogger,
+     * deps.linkRunner, deps.subprocessEnv).
+     */
+    getCapabilityPortForAgent: (agentId: string) => ToolCapabilityPort;
     /** Image generation provider (undefined when API key missing -- tool not registered). */
     imageGenProvider?: ImageGenerationPort;
     /** OS-level sandbox provider detected once at daemon startup. */

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

@@ -1,14 +1,13 @@
 // 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 { SkillsConfigSchema, sanitizeLogString, tryGetContext, parseFormattedSessionKey, safePath, formatSessionKey, } from "@comis/core";
 import { sessionKeyToPath, WORKSPACE_FILE_NAMES, DEFAULT_TEMPLATES, registerWorkspaceFilesInTracker, } from "@comis/agent";
 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";
@@ -117,7 +116,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;
@@ -273,15 +272,35 @@ export function setupTools(deps) {
                     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.34",
+  "version": "1.0.37",
   "author": "Moshe Anconina",
   "license": "Apache-2.0",
   "description": "Background daemon and orchestrator for the Comis platform",