comisai 1.0.36 → 1.0.37

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.36",
+  "version": "1.0.37",
   "author": "Moshe Anconina",
   "license": "Apache-2.0",
   "description": "Background daemon and orchestrator for the Comis platform",

package/node_modules/@comis/gateway/dist/webhook/webhook-endpoint.d.ts

@@ -19,13 +19,9 @@ interface WebhookEnv extends Env {
  * the required fields before passing to the handler.
  */
 export declare const WebhookPayloadSchema: z.ZodObject<{
-    /** Event type (e.g., "deployment.completed", "alert.fired") */
     event: z.ZodString;
-    /** Source system identifier */
     source: z.ZodString;
-    /** Arbitrary event data */
     data: z.ZodRecord<z.ZodString, z.ZodUnknown>;
-    /** Optional ISO 8601 timestamp */
     timestamp: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 /**

package/node_modules/@comis/gateway/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@comis/gateway",
   "private": true,
-  "version": "1.0.36",
+  "version": "1.0.37",
   "author": "Moshe Anconina",
   "license": "Apache-2.0",
   "description": "HTTP, JSON-RPC, and WebSocket gateway for Comis",

package/node_modules/@comis/infra/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@comis/infra",
   "private": true,
-  "version": "1.0.36",
+  "version": "1.0.37",
   "author": "Moshe Anconina",
   "license": "Apache-2.0",
   "description": "Structured logging infrastructure for Comis",

package/node_modules/@comis/memory/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@comis/memory",
   "private": true,
-  "version": "1.0.36",
+  "version": "1.0.37",
   "author": "Moshe Anconina",
   "license": "Apache-2.0",
   "description": "SQLite memory, embeddings, and RAG storage for Comis agents",

package/node_modules/@comis/scheduler/dist/cron/cron-types.d.ts

@@ -8,19 +8,14 @@ import { z } from "zod";
  */
 export declare const CronScheduleSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     kind: z.ZodLiteral<"cron">;
-    /** Standard cron expression (5 or 6 fields) */
     expr: z.ZodString;
-    /** IANA timezone (e.g. "America/New_York"), omit for UTC */
     tz: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>, z.ZodObject<{
     kind: z.ZodLiteral<"every">;
-    /** Interval in milliseconds */
     everyMs: z.ZodNumber;
-    /** Optional anchor timestamp in ms (first tick aligned to this) */
     anchorMs: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strict>, z.ZodObject<{
     kind: z.ZodLiteral<"at">;
-    /** ISO 8601 datetime string for one-shot execution */
     at: z.ZodString;
 }, z.core.$strict>], "kind">;
 export type CronSchedule = z.infer<typeof CronScheduleSchema>;
@@ -32,15 +27,11 @@ export type CronSchedule = z.infer<typeof CronScheduleSchema>;
  */
 export declare const CronPayloadSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     kind: z.ZodLiteral<"system_event">;
-    /** Event text to emit */
     text: z.ZodString;
 }, z.core.$strict>, z.ZodObject<{
     kind: z.ZodLiteral<"agent_turn">;
-    /** Message to send to the agent */
     message: z.ZodString;
-    /** Optional model override for this turn */
     model: z.ZodOptional<z.ZodString>;
-    /** Optional timeout in seconds for this turn */
     timeoutSeconds: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strict>], "kind">;
 export type CronPayload = z.infer<typeof CronPayloadSchema>;
@@ -80,99 +71,66 @@ export type CronDeliveryTarget = z.infer<typeof CronDeliveryTargetSchema>;
  * Full cron job definition.
  */
 export declare const CronJobSchema: z.ZodObject<{
-    /** Unique job identifier */
     id: z.ZodString;
-    /** Human-readable job name */
     name: z.ZodString;
-    /** Agent ID that owns this job */
     agentId: z.ZodString;
-    /** Schedule definition */
     schedule: z.ZodDiscriminatedUnion<[z.ZodObject<{
         kind: z.ZodLiteral<"cron">;
-        /** Standard cron expression (5 or 6 fields) */
         expr: z.ZodString;
-        /** IANA timezone (e.g. "America/New_York"), omit for UTC */
         tz: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>, z.ZodObject<{
         kind: z.ZodLiteral<"every">;
-        /** Interval in milliseconds */
         everyMs: z.ZodNumber;
-        /** Optional anchor timestamp in ms (first tick aligned to this) */
         anchorMs: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>, z.ZodObject<{
         kind: z.ZodLiteral<"at">;
-        /** ISO 8601 datetime string for one-shot execution */
         at: z.ZodString;
     }, z.core.$strict>], "kind">;
-    /** Payload to execute */
     payload: z.ZodDiscriminatedUnion<[z.ZodObject<{
         kind: z.ZodLiteral<"system_event">;
-        /** Event text to emit */
         text: z.ZodString;
     }, z.core.$strict>, z.ZodObject<{
         kind: z.ZodLiteral<"agent_turn">;
-        /** Message to send to the agent */
         message: z.ZodString;
-        /** Optional model override for this turn */
         model: z.ZodOptional<z.ZodString>;
-        /** Optional timeout in seconds for this turn */
         timeoutSeconds: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>], "kind">;
-    /** Session target for execution */
     sessionTarget: z.ZodDefault<z.ZodEnum<{
         main: "main";
         isolated: "isolated";
     }>>;
-    /** Wake mode: when to trigger heartbeat after enqueuing a system event. */
     wakeMode: z.ZodDefault<z.ZodEnum<{
         now: "now";
         "next-heartbeat": "next-heartbeat";
     }>>;
-    /** Whether to forward isolated session results back to main heartbeat session. */
     forwardToMain: z.ZodDefault<z.ZodBoolean>;
-    /** Session history strategy for cron executions. Default: fresh. */
     sessionStrategy: z.ZodDefault<z.ZodEnum<{
         fresh: "fresh";
         rolling: "rolling";
         accumulate: "accumulate";
     }>>;
-    /** Number of recent turns to keep for rolling strategy (default 3). */
     maxHistoryTurns: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
-    /** Per-job cache retention override. Default inherits OPERATION_CACHE_DEFAULTS["cron"] = "short". */
     cacheRetention: z.ZodOptional<z.ZodEnum<{
         none: "none";
         short: "short";
         long: "long";
     }>>;
-    /** Per-job tool policy override -- matches AgentConfig.toolPolicy shape.
-     *
-     *  Resolution order: job.toolPolicy > agentConfig.toolPolicy > passthrough
-     *  (no filtering). Opt-in: omitting this field preserves existing tool set
-     *  for the job. No silent defaults -- operators explicitly request
-     *  conservative presets like `{ profile: "cron-minimal" }`. */
     toolPolicy: z.ZodOptional<z.ZodObject<{
         profile: z.ZodDefault<z.ZodString>;
         allow: z.ZodDefault<z.ZodArray<z.ZodString>>;
         deny: z.ZodDefault<z.ZodArray<z.ZodString>>;
     }, z.core.$strip>>;
-    /** Delivery target for routing results to originating channel */
     deliveryTarget: z.ZodOptional<z.ZodObject<{
         channelId: z.ZodString;
         userId: z.ZodString;
         tenantId: z.ZodString;
         channelType: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>;
-    /** Whether this job is currently enabled */
     enabled: z.ZodDefault<z.ZodBoolean>;
-    /** Next scheduled run timestamp (ms since epoch) */
     nextRunAtMs: z.ZodOptional<z.ZodNumber>;
-    /** Last completed run timestamp (ms since epoch) */
     lastRunAtMs: z.ZodOptional<z.ZodNumber>;
-    /** Number of consecutive errors */
     consecutiveErrors: z.ZodDefault<z.ZodNumber>;
-    /** Maximum consecutive errors before auto-suspend. Per-job override of scheduler default. */
     maxConsecutiveErrors: z.ZodOptional<z.ZodNumber>;
-    /** Job creation timestamp (ms since epoch) */
     createdAtMs: z.ZodNumber;
 }, z.core.$strict>;
 export type CronJob = z.infer<typeof CronJobSchema>;

package/node_modules/@comis/scheduler/dist/heartbeat/agent-heartbeat-source.d.ts

@@ -37,9 +37,19 @@ interface HeartbeatExecutor {
         response: string;
     }>;
 }
-/** Minimal ActiveRunRegistry -- only needs has() for queue-busy check. */
-interface HeartbeatActiveRunRegistry {
-    has(sessionKey: string): boolean;
+/**
+ * Minimal BackgroundSessionResolver shape -- only needs hasActiveSession()
+ * for the queue-busy check. The scheduler package cannot import @comis/agent
+ * (would create a cycle), so we re-declare the structural minimum here. The
+ * daemon wires `createBackgroundSessionResolver({activeRunRegistry})` and
+ * the resulting object is structurally assignable to this shape (R3, B36).
+ */
+interface HeartbeatSessionResolver {
+    hasActiveSession(key: {
+        agentId: string;
+        channelType: string;
+        channelId: string;
+    }): boolean;
 }
 /** Tool policy filter function signature -- matches applyToolPolicy from @comis/skills.
  *  Injected as a dep so scheduler doesn't take a hard dependency on skills. */
@@ -96,8 +106,12 @@ export interface AgentHeartbeatSourceDeps {
     systemEventQueue: SystemEventQueue;
     /** Delivery bridge dependencies for routing notifications. */
     deliveryBridge: DeliveryBridgeDeps;
-    /** Optional ActiveRunRegistry for queue-busy detection. */
-    activeRunRegistry?: HeartbeatActiveRunRegistry;
+    /**
+     * Optional composite-key resolver for queue-busy detection (R3, B36).
+     * Wired by the daemon as
+     * `createBackgroundSessionResolver({activeRunRegistry})`.
+     */
+    sessionResolver?: HeartbeatSessionResolver;
     /** Optional session operations for response processing side-effects. */
     sessionOps?: HeartbeatSessionOps;
     /** Optional: fetch memory stats for an agent (for heartbeat prompt injection). */
@@ -119,12 +133,19 @@ export interface AgentHeartbeatSourceDeps {
  */
 export declare function resolveHeartbeatModel(perAgentHeartbeatModel: string | undefined, globalHeartbeatModel: string | undefined, agentDefaultModel: string): string;
 /**
- * Check if a session is actively running an agent turn.
+ * Check if a session is actively running an agent turn (R3, B36).
  *
- * Returns false when no ActiveRunRegistry is provided (heartbeat
+ * Uses the composite-key resolver: `(agentId, channelType, channelId)`
+ * uniquely identifies a session across multi-agent / multi-channel
+ * deployments (the previous single-arg `formattedKey` collapsed those
+ * dimensions). Returns false when no resolver is provided (heartbeat
  * operates in isolation without collision detection).
  */
-export declare function isQueueBusy(activeRunRegistry: HeartbeatActiveRunRegistry | undefined, sessionKey: string): boolean;
+export declare function isQueueBusy(sessionResolver: HeartbeatSessionResolver | undefined, composite: {
+    agentId: string;
+    channelType: string;
+    channelId: string;
+}): boolean;
 /**
  * Resolve the SessionKey for a heartbeat tick.
  *