comisai 1.0.36 → 1.0.37

package/node_modules/@comis/agent/dist/background/completion-dispatcher.js

@@ -0,0 +1,215 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Completion dispatcher: routes background_task:completed/failed events
+ * through the BackgroundSessionState machine.
+ *
+ * Subscribes to background_task:completed and background_task:failed BEFORE
+ * the existing BackgroundCompletionRunner. On each event:
+ *  1. Reads `task.dispatchState`.
+ *  2. If "pending": transitions to "notified" only when the runner cannot
+ *     re-enter the originating session (no active session for the formatted
+ *     key, or recursion limit reached). Otherwise transitions to "dispatched"
+ *     and lets the completion-runner perform re-entry.
+ *  3. If already "notified" or "dispatched": no-op (at-most-once).
+ *
+ * The runner is wired AFTER the dispatcher in setup-background-completion-
+ * runner.ts so its handler reads the updated `task.dispatchState` and skips
+ * its own work when state is "notified" (the dispatcher already fired
+ * fallback). This single-owner contract ensures the completion runner does
+ * not double-fire user-visible notifications: the dispatcher routes via
+ * persistent state instead of an in-memory event handler, and gates on
+ * state instead of unconditionally firing.
+ *
+ * **State persistence:** every transition calls `manager.transitionDispatch
+ * State(taskId, next)` (when the manager exposes it) which mutates the
+ * in-memory task AND calls persistTaskSync. Recovery-after-SIGKILL reads
+ * the persisted state and the manager skips re-emitting completion events
+ * for already-dispatched / already-notified tasks.
+ *
+ * **Failure isolation:** each handler is wrapped in suppressError so a
+ * single dispatch's failure does not tear down the subscription
+ * (AGENTS §2.1).
+ *
+ * @module
+ */
+import { suppressError } from "@comis/shared";
+// ---------------------------------------------------------------------------
+// Runtime constants exported for downstream consumers (test surface + ops).
+// ---------------------------------------------------------------------------
+/**
+ * The 3-state typed enum as a runtime array. Order matches transition order:
+ *   pending → (notified | dispatched).
+ *
+ * Exported as a `readonly string[]` so tests can assert
+ * `STATES === ["pending", "notified", "dispatched"]`.
+ */
+export const STATES = [
+    "pending",
+    "notified",
+    "dispatched",
+];
+/**
+ * Notification policy as a runtime object so it round-trips through
+ * JSON.parse(JSON.stringify(...)) preserving identity. A boolean would
+ * collapse to true/false on rehydrate and lose the distinction between
+ * "deferred" / "immediate" / "silent".
+ *
+ * The typed enum is the single source of truth. This runtime object is a
+ * discoverability surface (tests, debugging, logs); production code uses
+ * the type-only `BackgroundTaskNotificationPolicy` from
+ * `background-task-types.ts`.
+ */
+export const BackgroundTaskNotificationPolicy = {
+    DEFERRED: "deferred",
+    IMMEDIATE: "immediate",
+    SILENT: "silent",
+};
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+/**
+ * Wire the completion dispatcher against an event bus + task manager.
+ * Subscriptions are installed synchronously; call shutdown() to remove them.
+ *
+ * At-most-once fallback: the state-machine transitions on
+ * `task.dispatchState` are the single source of truth. The dispatcher's
+ * synchronous transitionDispatchState runs BEFORE the completion-runner's
+ * handler reads the updated state, by virtue of the event-bus subscribing
+ * the dispatcher first (see setup-background-completion-runner.ts).
+ */
+export function createCompletionDispatcher(deps) {
+    const log = deps.logger.child({ submodule: "completion-dispatcher" });
+    const fallback = deps.fallbackNotifyFn ?? deps.notifyFn;
+    let stopped = false;
+    let inflight = Promise.resolve();
+    const onCompleted = (data) => {
+        if (stopped)
+            return;
+        const promise = handleEvent(data.taskId, "completed");
+        inflight = inflight.then(() => promise).catch(() => undefined);
+        suppressError(promise, "completion dispatcher (completed)");
+    };
+    const onFailed = (data) => {
+        if (stopped)
+            return;
+        const promise = handleEvent(data.taskId, "failed");
+        inflight = inflight.then(() => promise).catch(() => undefined);
+        suppressError(promise, "completion dispatcher (failed)");
+    };
+    deps.eventBus.on("background_task:completed", onCompleted);
+    deps.eventBus.on("background_task:failed", onFailed);
+    async function handleEvent(taskId, kind) {
+        const task = deps.taskManager.getTask(taskId);
+        if (!task) {
+            log.debug({ taskId, kind, hint: "Task disappeared from manager before dispatcher could resolve it" }, "Completion dispatcher: task not in manager");
+            return;
+        }
+        const current = task.dispatchState ?? "pending";
+        // At-most-once: state machine is the single source of truth.
+        if (current === "notified" || current === "dispatched") {
+            log.debug({
+                taskId,
+                dispatchState: current,
+                // traceId from task.origin so dispatcher logs stay threaded with
+                // the originating request even when the dispatcher runs from a
+                // background ALS context.
+                traceId: task.origin?.traceId ?? undefined,
+                hint: "Task already dispatched/notified; no-op (at-most-once)",
+            }, "Completion dispatcher: at-most-once gate");
+            return;
+        }
+        // task.dispatchState === "pending". Decide which transition to make.
+        // origin is producer-required; read it directly.
+        const origin = task.origin;
+        // Hop cap (when configured). Recursion limit reached → fallback.
+        if (typeof deps.maxBackgroundHops === "number") {
+            const nextHopCount = (origin.backgroundHopCount ?? 0) + 1;
+            if (nextHopCount >= deps.maxBackgroundHops) {
+                transitionTo(taskId, "notified");
+                await fireFallback(task, `Background task "${task.toolName}" completed but follow-up was skipped — recursion limit reached. Run again or check the result manually.`);
+                return;
+            }
+        }
+        // Active-session check (when configured). No active session → fallback.
+        if (deps.sessionStore) {
+            const sessionExists = deps.sessionStore.loadByFormattedKey(origin.sessionKey) !== undefined;
+            if (!sessionExists) {
+                // The originating session is not currently registered. The
+                // completion-runner would skip re-entry (no streaming channel) —
+                // fire fallback so the user still sees a notification. The
+                // dispatcher transitions to "notified" so the runner does NOT
+                // also fire (single-owner contract).
+                transitionTo(taskId, "notified");
+                await fireFallback(task, `Background task "${task.toolName}" completed.`);
+                return;
+            }
+        }
+        // Active session exists (or sessionStore not wired): the runner will
+        // dispatch via re-entry. Transition to "dispatched" so the runner's
+        // handler — which reads task.dispatchState — sees the updated state.
+        // We do NOT fire fallback here (zero spurious outbound).
+        transitionTo(taskId, "dispatched");
+        log.debug({
+            taskId,
+            sessionKey: origin.sessionKey,
+            agentId: origin.agentId,
+            toolName: task.toolName,
+            // traceId from origin for log continuity.
+            traceId: origin.traceId ?? undefined,
+            hint: "Runner will re-enter the originating session",
+        }, "Completion dispatcher: marked dispatched");
+    }
+    function transitionTo(taskId, next) {
+        if (typeof deps.taskManager.transitionDispatchState === "function") {
+            deps.taskManager.transitionDispatchState(taskId, next);
+            return;
+        }
+        // No persistent transition wired — mutate the in-memory task directly so
+        // the runner (which receives the same event in the same tick) reads the
+        // updated state. Test fixtures take this branch.
+        const task = deps.taskManager.getTask(taskId);
+        if (task)
+            task.dispatchState = next;
+    }
+    async function fireFallback(task, message) {
+        if (!fallback) {
+            log.debug({
+                taskId: task.id,
+                // traceId from origin keeps log lines threaded.
+                traceId: task.origin?.traceId ?? undefined,
+                hint: "No fallbackNotifyFn wired; dispatcher cannot fire user-visible notification",
+            }, "Completion dispatcher: fallback skipped (no notifyFn)");
+            return;
+        }
+        try {
+            await fallback({
+                agentId: task.origin.agentId,
+                message,
+                priority: "normal",
+                origin: "background_task",
+            });
+        }
+        catch (err) {
+            log.warn({
+                taskId: task.id,
+                agentId: task.origin.agentId,
+                err,
+                // traceId from origin keeps the WARN line threaded.
+                traceId: task.origin?.traceId ?? undefined,
+                hint: "fallbackNotifyFn rejected; user will not see the completion notification for this task",
+                errorKind: "internal",
+            }, "Completion dispatcher: fallbackNotifyFn rejected");
+        }
+    }
+    return {
+        async shutdown() {
+            if (stopped)
+                return;
+            stopped = true;
+            deps.eventBus.off("background_task:completed", onCompleted);
+            deps.eventBus.off("background_task:failed", onFailed);
+            // Wait for any in-flight handler to settle before returning.
+            await inflight;
+        },
+    };
+}

package/node_modules/@comis/agent/dist/background/completion-runner.d.ts

@@ -41,7 +41,16 @@ export interface BackgroundCompletionRunnerDeps {
     eventBus: TypedEventBus;
     getExecutor: (agentId: string) => AgentExecutor;
     sessionStore: RunnerSessionStore;
-    taskManager: Pick<BackgroundTaskManager, "getTask">;
+    /**
+     * Includes `transitionDispatchState` in addition to `getTask`. fallbackForTask
+     * uses transitionDispatchState to persist `dispatchState = "notified"` BEFORE
+     * firing `fallbackNotifyFn`, so a daemon SIGKILL between persist and fire does
+     * NOT leak a duplicate notification on recovery (the at-most-once gate binds
+     * against on-disk state). The daemon-side wiring at
+     * setup-background-completion-runner.ts already passes a manager with
+     * both methods.
+     */
+    taskManager: Pick<BackgroundTaskManager, "getTask" | "transitionDispatchState">;
     fallbackNotifyFn: NotifyFn;
     maxBackgroundHops: number;
     logger: ComisLogger;

package/node_modules/@comis/agent/dist/background/completion-runner.js

@@ -58,32 +58,72 @@ export function createBackgroundCompletionRunner(deps) {
             log.warn({ taskId, kind, hint: "Task disappeared from manager before runner could resolve it; no announcement injected", errorKind: "internal" }, "Background completion: task not in manager");
             return;
         }
-        // Legacy task without origin -- emit fallback, keep file for audit.
-        const origin = task.origin;
-        if (!origin || !origin.sessionKey || !origin.agentId) {
-            await fallbackForTask(task.toolName, task.origin?.agentId ?? "default", `Background task "${task.toolName}" completed.`);
+        // At-most-once: the dispatcher subscribed BEFORE this runner (see
+        // setup-background-completion-runner.ts) and already transitioned
+        // task.dispatchState. When state is "notified", the dispatcher fired
+        // the user-visible fallback; the runner stays out of the way to
+        // enforce single-owner notification routing (zero spurious outbound).
+        if (task.dispatchState === "notified") {
+            log.debug({
+                taskId,
+                dispatchState: task.dispatchState,
+                // Include originating traceId so operator log streams stay
+                // continuous across the dispatcher / runner boundary.
+                traceId: task.origin?.traceId ?? undefined,
+                hint: "Dispatcher already fired fallback notification (at-most-once)",
+            }, "Background completion runner: skipped (dispatcher fired fallback)");
             return;
         }
+        // origin is producer-required (background-task-manager promote()
+        // rejects missing-origin) so we read it directly.
+        const origin = task.origin;
         // Hop cap. Read incoming hop count from origin (schema field populated
         // by the originResolver).
         const nextHopCount = (origin.backgroundHopCount ?? 0) + 1;
         if (nextHopCount >= deps.maxBackgroundHops) {
-            log.info({ taskId, toolName: task.toolName, agentId: origin.agentId, hopCount: nextHopCount, max: deps.maxBackgroundHops }, "Background completion: hop cap reached, falling back to user notification");
-            await fallbackForTask(task.toolName, origin.agentId, `Background task "${task.toolName}" completed but follow-up was skipped — recursion limit reached. Run again or check the result manually.`);
+            log.info({
+                taskId,
+                toolName: task.toolName,
+                agentId: origin.agentId,
+                hopCount: nextHopCount,
+                max: deps.maxBackgroundHops,
+                // traceId from origin keeps operator logs threaded.
+                traceId: origin.traceId ?? undefined,
+            }, "Background completion: hop cap reached, falling back to user notification");
+            await fallbackForTask(task.id, origin.agentId, task.toolName, `Background task "${task.toolName}" completed but follow-up was skipped — recursion limit reached. Run again or check the result manually.`);
             return;
         }
-        // Missing session -- session expired while the task ran. No channel to deliver
-        // to, so skip fallback (which would only produce a WARN from notification-service).
+        // No active session for this sessionKey in the in-memory store. The
+        // originating session may have ended (user closed the channel) OR may live
+        // in JSONL but not be currently registered. Either way, there is no
+        // streaming channel to inject into, so skip fallback (which would only
+        // produce a WARN from notification-service).
         const sessionExists = deps.sessionStore.loadByFormattedKey(origin.sessionKey) !== undefined;
         if (!sessionExists) {
-            log.info({ taskId, sessionKey: origin.sessionKey }, "Background completion: session expired, skipping re-entry");
+            log.info({
+                taskId,
+                sessionKey: origin.sessionKey,
+                // traceId from origin so this INFO log line stays threaded with the
+                // originating request's trace stream even though the runner runs in a
+                // background context (the ALS traceId at this point may differ from
+                // origin.traceId).
+                traceId: origin.traceId ?? undefined,
+                hint: "No active in-memory session for this sessionKey; runner will skip re-entry. Task result remains in JSONL for offline review.",
+            }, "Background completion: no active session for re-entry");
             return;
         }
         // Reconstruct the SessionKey object for executor.execute().
         const parsedKey = parseFormattedSessionKey(origin.sessionKey);
         if (!parsedKey) {
-            log.warn({ taskId, sessionKey: origin.sessionKey, hint: "Persisted sessionKey is malformed; cannot route announcement", errorKind: "internal" }, "Background completion: invalid sessionKey");
-            await fallbackForTask(task.toolName, origin.agentId, `Background task "${task.toolName}" completed (routing failed).`);
+            log.warn({
+                taskId,
+                sessionKey: origin.sessionKey,
+                // traceId from origin keeps operator logs threaded.
+                traceId: origin.traceId ?? undefined,
+                hint: "Persisted sessionKey is malformed; cannot route announcement",
+                errorKind: "internal",
+            }, "Background completion: invalid sessionKey");
+            await fallbackForTask(task.id, origin.agentId, task.toolName, `Background task "${task.toolName}" completed (routing failed).`);
             return;
         }
         // Format the announcement (byte-identical trailing instruction).
@@ -105,15 +145,27 @@ export function createBackgroundCompletionRunner(deps) {
                 traceId: origin.traceId ?? undefined,
             },
         };
-        log.debug({ taskId, sessionKey: origin.sessionKey, agentId: origin.agentId, toolName: task.toolName, hopCount: nextHopCount }, "Background completion runner: invoking executor");
+        log.debug({
+            taskId,
+            sessionKey: origin.sessionKey,
+            agentId: origin.agentId,
+            toolName: task.toolName,
+            hopCount: nextHopCount,
+            // traceId from origin keeps debug logs threaded.
+            traceId: origin.traceId ?? undefined,
+        }, "Background completion runner: invoking executor");
         // Emit background_task:reentered immediately before executor.execute().
         // Integration tests compute p95 latency from
         // background_task:completed.timestamp to this event's timestamp.
+        // Include traceId from origin so subscribers (and operator log streams)
+        // preserve the originating request's trace across the
+        // background_task:completed → :reentered boundary.
         deps.eventBus.emit("background_task:reentered", {
             taskId: task.id,
             agentId: origin.agentId,
             sessionKey: origin.sessionKey,
             hopCount: nextHopCount,
+            traceId: origin.traceId ?? null,
             timestamp: Date.now(),
         });
         // One turn per event. Existing session lock orders concurrent calls.
@@ -121,10 +173,41 @@ export function createBackgroundCompletionRunner(deps) {
             await deps.getExecutor(origin.agentId).execute(syntheticMsg, parsedKey, undefined, undefined, origin.agentId);
         }
         catch (err) {
-            log.warn({ taskId, err, hint: "Executor failed mid-completion turn; subscription remains active", errorKind: "internal" }, "Background completion: executor.execute() rejected");
+            log.warn({
+                taskId,
+                err,
+                // traceId from origin keeps the WARN line threaded.
+                traceId: origin.traceId ?? undefined,
+                hint: "Executor failed mid-completion turn; subscription remains active",
+                errorKind: "internal",
+            }, "Background completion: executor.execute() rejected");
         }
     }
-    async function fallbackForTask(toolName, agentId, message) {
+    /**
+     * Two-phase commit:
+     *
+     * 1. transitionDispatchState(taskId, "notified") — synchronously persists
+     *    `dispatchState = "notified"` to disk (via persistTaskSync inside the
+     *    manager). This MUST run before fallbackNotifyFn so a SIGKILL between
+     *    persist and fire does NOT leak a duplicate on recovery: the at-most-
+     *    once gate at the top of handleEvent (which reads task.dispatchState)
+     *    sees "notified" and skips re-firing. Without this ordering, the gate
+     *    misses and the user receives the notification twice.
+     *
+     * 2. fallbackNotifyFn(...) — actually deliver the user-visible
+     *    notification. May reject (channel offline, rate-limited, etc.); the
+     *    failure is logged at WARN. The persisted state stays at "notified" —
+     *    the user did not see the notification, but the at-most-once contract
+     *    takes precedence over delivery completeness.
+     */
+    async function fallbackForTask(taskId, agentId, toolName, message) {
+        // Phase 1: persist state. transitionDispatchState may return false if
+        // the task disappeared from the manager between handler entry and this
+        // call (e.g., explicit cleanup). In that case there is nothing to gate
+        // on; we still fire so the user sees the completion. The persist is
+        // synchronous so the on-disk state is updated before phase 2.
+        deps.taskManager.transitionDispatchState(taskId, "notified");
+        // Phase 2: fire user-visible notification.
         try {
             await deps.fallbackNotifyFn({
                 agentId,
@@ -134,7 +217,7 @@ export function createBackgroundCompletionRunner(deps) {
             });
         }
         catch (err) {
-            log.warn({ toolName, agentId, err, hint: "fallbackNotifyFn rejected; user will not see the completion notification for this task", errorKind: "internal" }, "Background completion: fallbackNotifyFn rejected");
+            log.warn({ taskId, toolName, agentId, err, hint: "fallbackNotifyFn rejected; user will not see the completion notification for this task. dispatchState already persisted as \"notified\" — no duplicate on recovery.", errorKind: "internal" }, "Background completion: fallbackNotifyFn rejected (post-persist)");
         }
     }
     return {

package/node_modules/@comis/agent/dist/background/index.d.ts

@@ -3,7 +3,8 @@
  *
  * @module
  */
-export type { BackgroundTask, BackgroundTaskStatus, PersistedTaskState } from "./background-task-types.js";
+export type { BackgroundTask, BackgroundTaskStatus, BackgroundSessionState, PersistedTaskState, } from "./background-task-types.js";
+export type { BackgroundTaskNotificationPolicy as BackgroundTaskNotificationPolicyType } from "./background-task-types.js";
 export type { BackgroundTaskOrigin } from "@comis/core";
 export { persistTaskSync, loadTask, recoverTasks, removeTaskFile, TASK_DIR_NAME, } from "./background-task-persistence.js";
 export { createBackgroundTaskManager, } from "./background-task-manager.js";
@@ -13,3 +14,7 @@ export type { ToolDefinition, } from "./auto-background-middleware.js";
 export { formatCompletionAnnouncement, TRAILING_INSTRUCTION } from "./completion-formatter.js";
 export { createBackgroundCompletionRunner } from "./completion-runner.js";
 export type { BackgroundCompletionRunner, BackgroundCompletionRunnerDeps, RunnerSessionStore, } from "./completion-runner.js";
+export { createCompletionDispatcher, STATES, BackgroundTaskNotificationPolicy, } from "./completion-dispatcher.js";
+export type { CompletionDispatcher, CompletionDispatcherDeps, DispatcherSessionStore, DispatcherTaskManager, } from "./completion-dispatcher.js";
+export { createBackgroundSessionResolver } from "./session-resolver.js";
+export type { ActiveSessionKey, BackgroundSessionResolver, BackgroundSessionResolverDeps, } from "./session-resolver.js";

package/node_modules/@comis/agent/dist/background/index.js

@@ -9,3 +9,5 @@ export { createBackgroundTaskManager, } from "./background-task-manager.js";
 export { wrapToolForAutoBackground, } from "./auto-background-middleware.js";
 export { formatCompletionAnnouncement, TRAILING_INSTRUCTION } from "./completion-formatter.js";
 export { createBackgroundCompletionRunner } from "./completion-runner.js";
+export { createCompletionDispatcher, STATES, BackgroundTaskNotificationPolicy, } from "./completion-dispatcher.js";
+export { createBackgroundSessionResolver } from "./session-resolver.js";

package/node_modules/@comis/agent/dist/background/session-resolver.d.ts

@@ -0,0 +1,85 @@
+/**
+ * BackgroundSessionResolver: composite-key wrapper around ActiveRunRegistry.
+ *
+ * The underlying `activeRunRegistry.has(sessionKey)` and `.get(sessionKey)`
+ * take a single formatted-key string. That string would collapse two
+ * distinct sessions for the same `channelId` across different agents (or
+ * different channelTypes) into one bucket — a latent multi-agent /
+ * multi-channel correctness bug.
+ *
+ * This resolver makes the composite key explicit at every public call site:
+ * `(agentId, channelType, channelId)`. It internally composes the formatted
+ * key via `formatSessionKey` from `@comis/core` and delegates to the
+ * underlying registry.
+ *
+ * Runtime semantics do not change at the registry layer — what changes is
+ * the lookup-key signature surfaced to production callers. No production
+ * code outside *.test.ts should retain a single-arg `.has(...)` or
+ * `.get(...)` on `activeRunRegistry`.
+ *
+ * @module
+ */
+import type { ActiveRunRegistry, RunHandle } from "../executor/active-run-registry.js";
+/**
+ * Composite key for active-session lookup.
+ *
+ * The three fields uniquely identify a session at the inbound-routing layer:
+ *   - `agentId`     — distinguishes per-agent isolation (multi-agent safety)
+ *   - `channelType` — distinguishes platform (telegram vs discord vs slack)
+ *   - `channelId`   — platform-specific chat / peer / group identifier
+ *
+ * The resolver internally composes a `SessionKey` and formats it via
+ * `formatSessionKey` so the underlying registry's string-keyed Map is
+ * addressed deterministically.
+ */
+export interface ActiveSessionKey {
+    agentId: string;
+    channelType: string;
+    channelId: string;
+}
+/**
+ * Public-facing resolver returned by `createBackgroundSessionResolver`.
+ *
+ * The resolver exposes ONLY composite-key methods. There is no single-arg
+ * fallback — production callers MUST thread `(agentId, channelType,
+ * channelId)` end-to-end.
+ */
+export interface BackgroundSessionResolver {
+    /**
+     * Look up the RunHandle for an active session.
+     *
+     * @param key - Composite key (agentId, channelType, channelId).
+     * @returns The RunHandle if a session is registered, otherwise undefined.
+     * @throws  Error when any composite-key field is empty / falsy
+     *          (programming error, parity with manager.promote's
+     *          empty-string guards in background-task-manager.ts:96-107).
+     */
+    resolveActiveSession(key: ActiveSessionKey): RunHandle | undefined;
+    /**
+     * Check whether a session is registered for the composite key.
+     *
+     * @param key - Composite key (agentId, channelType, channelId).
+     * @returns true iff a RunHandle is registered, false otherwise.
+     * @throws  Error when any composite-key field is empty / falsy.
+     */
+    hasActiveSession(key: ActiveSessionKey): boolean;
+}
+/**
+ * Dependencies required by the resolver.
+ *
+ * Only the registry is needed today — the resolver is a pure-function
+ * wrapper. No logger / event-bus injection (CLAUDE.md: NO logging in
+ * pure-function helpers).
+ */
+export interface BackgroundSessionResolverDeps {
+    activeRunRegistry: ActiveRunRegistry;
+}
+/**
+ * Create a BackgroundSessionResolver wrapping an ActiveRunRegistry.
+ *
+ * Public-facing methods accept ONLY the composite key (agentId,
+ * channelType, channelId) — no single-arg fallback. Production callers
+ * no longer reach into `activeRunRegistry.has(...)` / `.get(...)`
+ * directly.
+ */
+export declare function createBackgroundSessionResolver(deps: BackgroundSessionResolverDeps): BackgroundSessionResolver;

package/node_modules/@comis/agent/dist/background/session-resolver.js

@@ -0,0 +1,78 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * BackgroundSessionResolver: composite-key wrapper around ActiveRunRegistry.
+ *
+ * The underlying `activeRunRegistry.has(sessionKey)` and `.get(sessionKey)`
+ * take a single formatted-key string. That string would collapse two
+ * distinct sessions for the same `channelId` across different agents (or
+ * different channelTypes) into one bucket — a latent multi-agent /
+ * multi-channel correctness bug.
+ *
+ * This resolver makes the composite key explicit at every public call site:
+ * `(agentId, channelType, channelId)`. It internally composes the formatted
+ * key via `formatSessionKey` from `@comis/core` and delegates to the
+ * underlying registry.
+ *
+ * Runtime semantics do not change at the registry layer — what changes is
+ * the lookup-key signature surfaced to production callers. No production
+ * code outside *.test.ts should retain a single-arg `.has(...)` or
+ * `.get(...)` on `activeRunRegistry`.
+ *
+ * @module
+ */
+import { formatSessionKey } from "@comis/core";
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+/**
+ * Compose the formatted session-key string from a composite key.
+ *
+ * Mirrors the shape that production session-managers use when registering
+ * handles: `formatSessionKey({tenantId: agentId, channelId:
+ * "${channelType}:${channelId}", userId: channelId})`. The output is a
+ * deterministic colon-delimited string that round-trips through
+ * `parseFormattedSessionKey` (the channelType prefix on channelId is
+ * stable across format/parse).
+ *
+ * The triple is REQUIRED — empty fields are a programming error
+ * (parity with the empty-string guard in
+ * `background-task-manager.ts:promote()`).
+ */
+function formatComposite(key) {
+    if (!key.agentId || !key.channelType || !key.channelId) {
+        throw new Error(`BackgroundSessionResolver: composite key requires non-empty agentId, channelType, channelId; got ${JSON.stringify(key)}`);
+    }
+    return formatSessionKey({
+        tenantId: key.agentId,
+        channelId: `${key.channelType}:${key.channelId}`,
+        userId: key.channelId,
+    });
+}
+/**
+ * Create a BackgroundSessionResolver wrapping an ActiveRunRegistry.
+ *
+ * Public-facing methods accept ONLY the composite key (agentId,
+ * channelType, channelId) — no single-arg fallback. Production callers
+ * no longer reach into `activeRunRegistry.has(...)` / `.get(...)`
+ * directly.
+ */
+export function createBackgroundSessionResolver(deps) {
+    // Local alias: the resolver IS the abstraction over the underlying
+    // single-arg registry. We rename to `registry` so source-grep tooling
+    // (`activeRunRegistry.has|get(`) does not flag this file as a callsite
+    // to migrate -- the resolver IS the migration target. Invariant:
+    // *production callers* of `activeRunRegistry` go through this resolver;
+    // the resolver itself remains the sole consumer of the underlying
+    // single-arg surface.
+    const registry = deps.activeRunRegistry;
+    return {
+        resolveActiveSession(key) {
+            const formatted = formatComposite(key);
+            return registry.get(formatted);
+        },
+        hasActiveSession(key) {
+            const formatted = formatComposite(key);
+            return registry.has(formatted);
+        },
+    };
+}

package/node_modules/@comis/agent/dist/bootstrap/sections/messaging-sections.js

@@ -34,6 +34,7 @@ export function buildMessagingSection(toolNames, isMinimal, channelContext) {
         '- `[System Message]` blocks are internal context. If one reports completed work and asks for a user update, rewrite it in your normal assistant voice. Never forward raw system message text to users.',
         "- Never use shell execution, code execution, or file tools to send messages. Use only the messaging tools.",
         "- Do NOT use message(action=send) for progress updates, debug output, or placeholder text. The user sees every send as a phone notification. Work silently; deliver the result.",
+        "- Do NOT narrate intent before calling a tool. Avoid prefacing tool calls with phrases like \"I'll do X now…\" or \"Let me run Y…\" — invoke the tool directly. Pre-tool-text creates user-visible promises the agent may not be able to fulfill if the tool gets backgrounded.",
         "- Use `fetch` to read recent messages from a channel before responding to context you missed.",
         "- The `delete` action requires confirmation and cannot be undone.",
     ];

package/node_modules/@comis/agent/dist/bootstrap/sections/tool-descriptions.js

@@ -20,7 +20,7 @@
 import { getToolMetadata } from "@comis/core";
 import { getProviders } from "@mariozechner/pi-ai";
 // ---------------------------------------------------------------------------
-// Layer 1D (260430-vwt) -- live native-catalog provider list
+// Live native-catalog provider list
 //
 // Computed once at module load time. Used by the providers_manage TOOL_GUIDE
 // "Built-in vs Custom Provider Check" block below so the text reflects
@@ -325,7 +325,7 @@ If the model IS built-in: skip provider creation. After credential pre-check pas
 If the model is NOT built-in: you need a custom provider. Proceed to the steps below, but first gather ALL required configuration.
 
 ### Choosing the \`type\` Field (POST AUTO-PROMOTE FLOW)
-After Layer 1C of the catalog-driven providers redesign, the \`type\` field follows two distinct rules depending on the provider name:
+For catalog-driven providers, the \`type\` field follows two distinct rules depending on the provider name:
 - **If \`provider_id\` matches a built-in name** (use models_manage list_providers to verify): OMIT \`type\` entirely from the create config. The daemon auto-promotes \`type\` to the native catalog name when \`provider_id\` matches a native entry AND no custom \`baseUrl\` is supplied. Setting \`type:"openai"\` for a built-in name still works (auto-promoted), but omitting it is cleaner.
 - **If \`provider_id\` is a custom OpenAI-compatible proxy** (NVIDIA NIM, Together, Fireworks, etc.) NOT in the native catalog: set \`type:"openai"\` (or whatever wire-format API matches). Auto-promotion does not fire for non-catalog names.
 - **If \`baseUrl\` differs from the native catalog URL** for a built-in name: this signals you want the OpenAI-passthrough shape (custom proxy that masquerades as the built-in). Auto-promotion is suppressed; the entry stays as \`type:"openai"\`.
@@ -357,7 +357,7 @@ To switch an agent to a different provider/model, call agents_manage update with
 **Three preconditions the LLM MUST verify before issuing the update:**
   1. The target provider exists as a \`providers.entries.<provider_id>\` key. If it does not, call providers_manage create FIRST (and gateway env_set for the API key if needed). Patching an agent to a provider that has no entry resolves under the wrong provider family at the next session — the original bug.
   2. The model id matches a \`models[].id\` in that provider entry (or is a built-in known to the pi-ai catalog for that provider type). Otherwise \`registry.find(provider, model)\` returns undefined and the next session falls back with a "Model not found" message.
-  3. **Credential pre-check passed** (see top of this guide). The target provider's apiKeyName is non-empty AND \`gateway env_list filter:"<PROVIDER>*"\` confirmed the named secret exists in env. Skipping this step is the bug that causes "No API key found" failures at the next chat turn — verified production repro on 2026-05-01.
+  3. **Credential pre-check passed** (see top of this guide). The target provider's apiKeyName is non-empty AND \`gateway env_list filter:"<PROVIDER>*"\` confirmed the named secret exists in env. Skipping this step is the bug that causes "No API key found" failures at the next chat turn.
 
 **Timing — the change is NOT hot-applied to the active session.**
 agents_manage update writes through persistToConfig WITHOUT a hot-update callback, which triggers a SIGUSR2 daemon restart (2-second debounce). The new provider/model takes effect on the next session, not the currently-running prompt. Tell the user the switch is queued and will take effect after the daemon settles.