comisai 1.0.34 → 1.0.37

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

@@ -0,0 +1,130 @@
+/**
+ * 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 type { TypedEventBus } from "@comis/core";
+import type { ComisLogger } from "@comis/infra";
+import type { BackgroundTask, BackgroundSessionState, BackgroundTaskNotificationPolicy as NotificationPolicyType } from "./background-task-types.js";
+import type { NotifyFn } from "./background-task-manager.js";
+/**
+ * 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 declare const STATES: readonly BackgroundSessionState[];
+/**
+ * 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 declare const BackgroundTaskNotificationPolicy: Record<string, NotificationPolicyType>;
+/** Public-facing handle on the dispatcher. */
+export interface CompletionDispatcher {
+    /** Unsubscribe from the event bus. Idempotent. Awaitable so callers can
+     *  ensure no in-flight handler outlives daemon shutdown. */
+    shutdown(): Promise<void>;
+}
+/** Minimal session-store contract the dispatcher needs (active-session check). */
+export interface DispatcherSessionStore {
+    loadByFormattedKey(sessionKey: string): unknown | undefined;
+}
+/**
+ * Minimal taskManager contract: read + (optionally) persist transitions.
+ *
+ * `transitionDispatchState` is optional so the dispatcher composes cleanly
+ * with the test fixture in completion-dispatcher.test.ts (which constructs
+ * `taskManager: { getTask: vi.fn() }` and asserts the at-most-once gate
+ * without exercising state persistence). Production wiring adds
+ * `transitionDispatchState` on the real BackgroundTaskManager so the
+ * recovery-after-SIGKILL contract is binding.
+ */
+export interface DispatcherTaskManager {
+    getTask(taskId: string): BackgroundTask | undefined;
+    /**
+     * Atomically transition the in-memory task's dispatchState AND persist.
+     * Returns true on success; false if task does not exist. Optional —
+     * when absent, the dispatcher routes purely via in-memory state.
+     */
+    transitionDispatchState?(taskId: string, next: BackgroundSessionState): boolean;
+}
+/**
+ * Dispatcher dependencies.
+ *
+ * Public minimum: `eventBus`, `taskManager`, `logger`. Tests use
+ * `notifyFn`; production wires both `notifyFn` and `fallbackNotifyFn`
+ * (they are aliases — the dispatcher prefers `fallbackNotifyFn` when
+ * both are provided so production callers reading the daemon wiring
+ * see the canonical name).
+ *
+ * `sessionStore` + `maxBackgroundHops` are optional. When absent, the
+ * dispatcher falls back to the safe behavior: pending → dispatched
+ * (let the runner attempt re-entry), no fallback notification fired
+ * from the dispatcher itself.
+ */
+export interface CompletionDispatcherDeps {
+    eventBus: TypedEventBus;
+    taskManager: DispatcherTaskManager;
+    /**
+     * User-visible notification fired when the dispatcher cannot route to
+     * the originating session. Either name accepted; `fallbackNotifyFn`
+     * preferred when both are provided.
+     */
+    fallbackNotifyFn?: NotifyFn;
+    /** Alias for `fallbackNotifyFn` (test fixture compatibility). */
+    notifyFn?: NotifyFn;
+    /** Active-session check (production wiring). When absent, the dispatcher
+     *  defers to the runner without firing fallback. */
+    sessionStore?: DispatcherSessionStore;
+    /** Recursion limit for background-task hop counting. When absent, the
+     *  dispatcher does not enforce the cap (defers to the runner). */
+    maxBackgroundHops?: number;
+    logger: ComisLogger;
+}
+/**
+ * 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 declare function createCompletionDispatcher(deps: CompletionDispatcherDeps): CompletionDispatcher;

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-formatter.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Background completion formatter: transforms a BackgroundTask into a
+ * tagged announcement string ready for injection into the originating
+ * agent's session as a synthetic NormalizedMessage.
+ *
+ * Mirrors the shape of packages/agent/src/spawn/narrative-caster.ts (the
+ * sub-agent announcement formatter). Simplified: no condensation levels,
+ * no metadata stats, no labels -- just a single tool result with
+ * toolName + result/error.
+ *
+ * The trailing instruction is byte-identical to TRAILING_INSTRUCTION in
+ * narrative-caster.ts so AnnouncementBatcher.stripSystemPrefix()
+ * (announcement-batcher.ts:81-85) keeps working unchanged.
+ *
+ * Pure synchronous string formatting -- no async, no LLM calls, no I/O.
+ *
+ * @module
+ */
+import type { BackgroundTask } from "./background-task-types.js";
+/** Re-export so consumers (tests, completion runner) can assert byte-identity. */
+export { TRAILING_INSTRUCTION } from "../spawn/narrative-caster.js";
+/**
+ * Format a BackgroundTask completion or failure into a tagged announcement.
+ *
+ * Header forms:
+ *   - success: `[Background Task: ${toolName}]`
+ *   - failure: `[Background Task Failed: ${toolName}]`
+ *
+ * Body:
+ *   - success: `task.result` (already capped at 100 KB by manager.truncateResult).
+ *   - generic failure: `task.error`.
+ *   - restart-recovery failure (`task.error === "Daemon restarted while task was running"`):
+ *     uses the explicit recovery copy.
+ *
+ * Total-length cap: NormalizedMessageSchema.text limits at 32768 chars.
+ * If the assembled string would exceed the cap, only the body section is
+ * truncated; the header and trailing instruction are NEVER touched.
+ */
+export declare function formatCompletionAnnouncement(task: BackgroundTask): string;

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

@@ -0,0 +1,77 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Background completion formatter: transforms a BackgroundTask into a
+ * tagged announcement string ready for injection into the originating
+ * agent's session as a synthetic NormalizedMessage.
+ *
+ * Mirrors the shape of packages/agent/src/spawn/narrative-caster.ts (the
+ * sub-agent announcement formatter). Simplified: no condensation levels,
+ * no metadata stats, no labels -- just a single tool result with
+ * toolName + result/error.
+ *
+ * The trailing instruction is byte-identical to TRAILING_INSTRUCTION in
+ * narrative-caster.ts so AnnouncementBatcher.stripSystemPrefix()
+ * (announcement-batcher.ts:81-85) keeps working unchanged.
+ *
+ * Pure synchronous string formatting -- no async, no LLM calls, no I/O.
+ *
+ * @module
+ */
+import { TRAILING_INSTRUCTION } from "../spawn/narrative-caster.js";
+/** Re-export so consumers (tests, completion runner) can assert byte-identity. */
+export { TRAILING_INSTRUCTION } from "../spawn/narrative-caster.js";
+/** NormalizedMessageSchema.text caps at 32768 chars. Reserve headroom for header + trailing instruction. */
+const MAX_ANNOUNCEMENT_CHARS = 32768;
+const TRUNCATION_MARKER = "\n…[truncated]";
+/** Recovery announcement body for tasks failed via recoverOnStartup. */
+const RESTART_RECOVERY_BODY = "This background task was interrupted by a daemon restart. The result is unavailable; let the user know if relevant.";
+const RESTART_RECOVERY_ERROR = "Daemon restarted while task was running";
+/**
+ * Format a BackgroundTask completion or failure into a tagged announcement.
+ *
+ * Header forms:
+ *   - success: `[Background Task: ${toolName}]`
+ *   - failure: `[Background Task Failed: ${toolName}]`
+ *
+ * Body:
+ *   - success: `task.result` (already capped at 100 KB by manager.truncateResult).
+ *   - generic failure: `task.error`.
+ *   - restart-recovery failure (`task.error === "Daemon restarted while task was running"`):
+ *     uses the explicit recovery copy.
+ *
+ * Total-length cap: NormalizedMessageSchema.text limits at 32768 chars.
+ * If the assembled string would exceed the cap, only the body section is
+ * truncated; the header and trailing instruction are NEVER touched.
+ */
+export function formatCompletionAnnouncement(task) {
+    const isFailure = task.status === "failed" || task.status === "cancelled";
+    const headerPrefix = isFailure ? "Background Task Failed" : "Background Task";
+    const header = `[${headerPrefix}: ${task.toolName}]`;
+    let body;
+    if (isFailure) {
+        const rawError = task.error ?? "(no error message)";
+        body = rawError === RESTART_RECOVERY_ERROR ? RESTART_RECOVERY_BODY : rawError;
+    }
+    else {
+        body = task.result ?? "(no result)";
+    }
+    // Build assembled string: header, blank line, body, blank line, trailing instruction.
+    const sections = [];
+    sections.push(header);
+    sections.push("");
+    sections.push(body);
+    sections.push("");
+    sections.push(TRAILING_INSTRUCTION);
+    let assembled = sections.join("\n");
+    // Enforce NormalizedMessageSchema.text.max(32768). Truncate the body section
+    // ONLY if needed; header and trailing instruction are byte-identical guarantees.
+    if (assembled.length > MAX_ANNOUNCEMENT_CHARS) {
+        const headerSection = `${header}\n\n`;
+        const tailSection = `\n\n${TRAILING_INSTRUCTION}`;
+        const reservedChars = headerSection.length + tailSection.length + TRUNCATION_MARKER.length;
+        const allowedBodyChars = MAX_ANNOUNCEMENT_CHARS - reservedChars;
+        const truncatedBody = body.slice(0, Math.max(0, allowedBodyChars)) + TRUNCATION_MARKER;
+        assembled = headerSection + truncatedBody + tailSection;
+    }
+    return assembled;
+}

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

@@ -0,0 +1,62 @@
+/**
+ * Background completion runner: subscribes to background_task:completed and
+ * background_task:failed events from the TypedEventBus and re-enters the
+ * originating agent session with a formatted completion announcement.
+ *
+ * Per-session lock serialization is delegated to the existing session
+ * manager (ComisSessionManager.withSession in packages/agent/src/session/).
+ * The runner does NOT introduce its own queueing -- one turn per completion
+ * event, ordering follows the existing per-session lock.
+ *
+ * Recursion bound: per-task incoming hop count + 1 must stay below
+ * `maxBackgroundHops` (default 3). When the cap is hit, the runner emits
+ * the fallback notification instead of triggering executor.execute().
+ * The hop count is read from `task.origin.backgroundHopCount`
+ * (populated by the originResolver).
+ *
+ * Latency-instrumentation hook: emits `background_task:reentered`
+ * immediately before executor.execute(). Integration tests compute the delta
+ * from `background_task:completed.timestamp` to this event for SLO tracking.
+ *
+ * Failure isolation: each handler is wrapped in suppressError so a single
+ * completion's failure does not tear down the subscription (AGENTS §2.1).
+ *
+ * @module
+ */
+import type { TypedEventBus } from "@comis/core";
+import type { ComisLogger } from "@comis/infra";
+import type { AgentExecutor } from "../executor/types.js";
+import type { BackgroundTaskManager, NotifyFn } from "./background-task-manager.js";
+/** Public-facing handle on the runner returned by createBackgroundCompletionRunner. */
+export interface BackgroundCompletionRunner {
+    /** Unsubscribe from the event bus. Idempotent. Awaitable so callers can
+     *  ensure no in-flight handler outlives the daemon shutdown. */
+    shutdown(): Promise<void>;
+}
+/** Minimal session-store contract the runner needs (fallback gate). */
+export interface RunnerSessionStore {
+    loadByFormattedKey(sessionKey: string): unknown | undefined;
+}
+export interface BackgroundCompletionRunnerDeps {
+    eventBus: TypedEventBus;
+    getExecutor: (agentId: string) => AgentExecutor;
+    sessionStore: RunnerSessionStore;
+    /**
+     * 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;
+}
+/**
+ * Wire the completion runner against an event bus + executor + session store.
+ * Subscriptions are installed synchronously; call shutdown() to remove them.
+ */
+export declare function createBackgroundCompletionRunner(deps: BackgroundCompletionRunnerDeps): BackgroundCompletionRunner;