comisai 1.0.36 → 1.0.37

package/node_modules/@comis/agent/dist/background/auto-background-middleware.js

@@ -27,6 +27,15 @@ import { suppressError } from "@comis/shared";
  * If promotion fails (concurrency limit), awaits the tool normally (foreground fallback).
  */
 export function wrapToolForAutoBackground(tool, manager, config, notifyFn, originResolver) {
+    // `exec` opts out of the generic auto-background wrapper to enforce
+    // single-owner backgrounding. The exec-tool's own internal escalation path
+    // (packages/skills/src/builtin/exec-tool.ts:613-668) is the SOLE
+    // backgrounding owner for `exec`; the generic timeout-based wrapper would
+    // double-promote. Hardcoded literal — does NOT modify config.excludeTools
+    // so operator-set exclusions remain unchanged.
+    if (tool.name === "exec") {
+        return tool;
+    }
     if (config.excludeTools.includes(tool.name)) {
         return tool;
     }

package/node_modules/@comis/agent/dist/background/background-task-manager.d.ts

@@ -1,6 +1,6 @@
 import { type Result } from "@comis/shared";
 import type { TypedEventBus } from "@comis/core";
-import type { BackgroundTask, BackgroundTaskOrigin } from "./background-task-types.js";
+import type { BackgroundTask, BackgroundTaskOrigin, BackgroundSessionState, BackgroundTaskNotificationPolicy } from "./background-task-types.js";
 /** Notification callback fired when background task completes or fails. */
 export type NotifyFn = (opts: {
     agentId: string;
@@ -21,8 +21,21 @@ export interface BackgroundTaskManagerOpts {
     maxBackgroundDurationMs?: number;
 }
 export interface BackgroundTaskManager {
-    promote(toolName: string, promise: Promise<unknown>, ac: AbortController, origin: BackgroundTaskOrigin): Result<string, Error>;
+    promote(toolName: string, promise: Promise<unknown>, ac: AbortController, origin: BackgroundTaskOrigin, notificationPolicy?: BackgroundTaskNotificationPolicy): Result<string, Error>;
+    /**
+     * Mark a task as completed.
+     *
+     * The legacy `notifyFn` argument is preserved for backward compatibility but
+     * unused — the completion-dispatcher subscribes to the
+     * `background_task:completed` event emitted here and decides whether to fire
+     * the user-visible fallback notification. Single-owner contract eliminates
+     * double-notify.
+     */
     complete(taskId: string, result: unknown, notifyFn?: NotifyFn): void;
+    /**
+     * Mark a task as failed. See `complete` for the single-owner note — the
+     * `notifyFn` argument is unused; the dispatcher routes notification.
+     */
     fail(taskId: string, error: unknown, notifyFn?: NotifyFn): void;
     cancel(taskId: string): Result<void, Error>;
     getTask(taskId: string): BackgroundTask | undefined;
@@ -30,5 +43,12 @@ export interface BackgroundTaskManager {
     getAllTasks(): BackgroundTask[];
     recoverOnStartup(): void;
     cleanup(maxAgeMs?: number): void;
+    /**
+     * Atomically transition the in-memory task's dispatchState AND persist.
+     * Returns true on success; false if task does not exist. The dispatcher
+     * calls this from its handler so SIGKILL-recovery preserves the recovered
+     * state across daemon restart.
+     */
+    transitionDispatchState(taskId: string, next: BackgroundSessionState): boolean;
 }
 export declare function createBackgroundTaskManager(opts: BackgroundTaskManagerOpts): BackgroundTaskManager;

package/node_modules/@comis/agent/dist/background/background-task-manager.js

@@ -8,7 +8,7 @@
  * @module
  */
 import { randomUUID } from "node:crypto";
-import { ok, err, suppressError } from "@comis/shared";
+import { ok, err } from "@comis/shared";
 import { persistTaskSync, recoverTasks, removeTaskFile } from "./background-task-persistence.js";
 const MAX_RESULT_CHARS = 102_400; // 100KB
 export function createBackgroundTaskManager(opts) {
@@ -35,7 +35,7 @@ export function createBackgroundTaskManager(opts) {
         }
     }
     const manager = {
-        promote(toolName, promise, ac, origin) {
+        promote(toolName, promise, ac, origin, notificationPolicy) {
             // Reject calls with missing/invalid origin (no silent fallback).
             if (!origin || typeof origin !== "object") {
                 return err(new Error("BackgroundTaskOrigin is required (received undefined or non-object)"));
@@ -69,6 +69,11 @@ export function createBackgroundTaskManager(opts) {
                 status: "running",
                 startedAt: Date.now(),
                 origin,
+                // Seed the dispatch state machine. Default policy is "deferred" —
+                // the dispatcher inspects dispatchState before firing fallback notify
+                // (at-most-once).
+                notificationPolicy: notificationPolicy ?? "deferred",
+                dispatchState: "pending",
                 _promise: promise,
                 _abortController: ac,
             };
@@ -92,7 +97,7 @@ export function createBackgroundTaskManager(opts) {
             });
             return ok(taskId);
         },
-        complete(taskId, result, notifyFn) {
+        complete(taskId, result, _notifyFn) {
             const task = tasks.get(taskId);
             if (!task || task.status !== "running")
                 return;
@@ -112,16 +117,14 @@ export function createBackgroundTaskManager(opts) {
                 origin: task.origin,
                 timestamp: Date.now(),
             });
-            if (notifyFn) {
-                suppressError(notifyFn({
-                    agentId: task.origin.agentId,
-                    message: `Background task "${task.toolName}" completed (${Math.round(durationMs / 1000)}s). Task ID: ${taskId}`,
-                    priority: "normal",
-                    origin: "background_task",
-                }), "background task completion notification");
-            }
+            // Notification routing lives in the completion-dispatcher (subscribed
+            // to background_task:completed above). The legacy `notifyFn` argument
+            // is kept for backward compatibility but unused here — the dispatcher
+            // inspects task.dispatchState before firing the user-visible fallback,
+            // and the runner skips when state is "notified" (single-owner contract,
+            // zero spurious outbound).
         },
-        fail(taskId, error, notifyFn) {
+        fail(taskId, error, _notifyFn) {
             const task = tasks.get(taskId);
             if (!task || task.status !== "running")
                 return;
@@ -142,14 +145,7 @@ export function createBackgroundTaskManager(opts) {
                 origin: task.origin,
                 timestamp: Date.now(),
             });
-            if (notifyFn) {
-                suppressError(notifyFn({
-                    agentId: task.origin.agentId,
-                    message: `Background task "${task.toolName}" failed: ${task.error}. Task ID: ${taskId}`,
-                    priority: "normal",
-                    origin: "background_task",
-                }), "background task failure notification");
-            }
+            // See complete() above — notifyFn arg is unused; dispatcher owns routing.
         },
         cancel(taskId) {
             const task = tasks.get(taskId);
@@ -185,24 +181,29 @@ export function createBackgroundTaskManager(opts) {
         recoverOnStartup() {
             const recovered = recoverTasks(dataDir);
             let count = 0;
-            let skipped = 0;
+            let dispatchPreserved = 0;
             for (const persisted of recovered) {
-                if (!persisted.origin || typeof persisted.origin !== "object" || !persisted.origin.agentId || !persisted.origin.sessionKey) {
-                    // Legacy file without origin. Skip with a warning -- the file
-                    // remains on disk for audit, but the manager doesn't import it.
-                    skipped++;
-                    logger.warn({
-                        taskId: persisted.id,
-                        hint: "Legacy task file lacks origin; skipping recovery -- delete the file or wait for cleanup",
-                        errorKind: "internal",
-                    }, "Skipping recovered task without origin");
-                    continue;
-                }
-                const task = {
-                    ...persisted,
-                };
+                // The persistence-write contract guarantees populated origin /
+                // notificationPolicy / dispatchState on every task file.
+                // background-task-persistence.ts rejects shape-malformed files
+                // (missing id / toolName) before they reach here; we propagate the
+                // persisted record as-is.
+                const task = persisted;
                 tasks.set(task.id, task);
                 if (persisted.status === "failed" && persisted.error === "Daemon restarted while task was running") {
+                    // Recovery-without-events: if dispatchState is already "notified" or
+                    // "dispatched", the dispatcher already routed pre-restart; do NOT
+                    // re-emit the background_task:failed event (which would re-trigger
+                    // fallback).
+                    if (task.dispatchState === "notified" || task.dispatchState === "dispatched") {
+                        dispatchPreserved++;
+                        logger.debug({
+                            taskId: task.id,
+                            dispatchState: task.dispatchState,
+                            hint: "Pre-restart dispatch state preserved; skipping re-emit (D-S2 recovery-without-events)",
+                        }, "Recovery: skipped re-emit");
+                        continue;
+                    }
                     count++;
                     eventBus.emit("background_task:failed", {
                         agentId: task.origin.agentId,
@@ -218,14 +219,20 @@ export function createBackgroundTaskManager(opts) {
             if (count > 0) {
                 logger.info({ count }, "Recovered background tasks marked as failed");
             }
-            if (skipped > 0) {
-                logger.warn({
-                    skipped,
-                    hint: "Legacy task files cannot be recovered without origin -- they remain on disk for audit",
-                    errorKind: "internal",
-                }, "Skipped legacy task files during recovery");
+            if (dispatchPreserved > 0) {
+                logger.info({ count: dispatchPreserved }, "Recovered tasks with preserved dispatch state (no re-emit)");
             }
         },
+        transitionDispatchState(taskId, next) {
+            const task = tasks.get(taskId);
+            if (!task)
+                return false;
+            // Idempotent — same-state transitions are allowed (no-op write).
+            task.dispatchState = next;
+            // Persist atomically so recovery-after-SIGKILL sees the transition.
+            persistTaskSync(dataDir, task);
+            return true;
+        },
         cleanup(maxAgeMs = 86_400_000) {
             const cutoff = Date.now() - maxAgeMs;
             for (const [taskId, task] of tasks) {

package/node_modules/@comis/agent/dist/background/background-task-persistence.js

@@ -7,12 +7,17 @@
  *
  * @module
  */
-import { mkdirSync, writeFileSync, readFileSync, readdirSync, unlinkSync, existsSync } from "node:fs";
+import { mkdirSync, writeFileSync, readFileSync, readdirSync, statSync, unlinkSync, existsSync } from "node:fs";
 import { safePath } from "@comis/core";
 /** Directory name under data dir for background task state files. */
 export const TASK_DIR_NAME = "background-tasks";
 /**
  * Extract the serializable subset from a BackgroundTask.
+ *
+ * notificationPolicy + dispatchState are copied across when present so the
+ * state machine survives daemon restart-recovery. Both fields are optional in
+ * PersistedTaskState; we use spread-when-defined to avoid emitting
+ * `"notificationPolicy": undefined` to disk for callers that do not set them.
  */
 function toPersistedState(task) {
     return {
@@ -24,6 +29,8 @@ function toPersistedState(task) {
         result: task.result,
         error: task.error,
         origin: task.origin,
+        ...(task.notificationPolicy !== undefined && { notificationPolicy: task.notificationPolicy }),
+        ...(task.dispatchState !== undefined && { dispatchState: task.dispatchState }),
     };
 }
 /**
@@ -72,6 +79,20 @@ export function recoverTasks(dataDir) {
     }
     for (const agentId of agentDirs) {
         const agentDir = safePath(dataDir, agentId);
+        // Guard against non-directory entries in dataDir. statSync may throw if
+        // the entry vanished between readdirSync and here; skip gracefully.
+        // Non-directory entries (lock files, READMEs, accidental
+        // file-with-agentId-name) MUST be skipped explicitly so they don't
+        // shadow legitimate agent recovery silently.
+        let dirStat;
+        try {
+            dirStat = statSync(agentDir);
+        }
+        catch {
+            continue;
+        }
+        if (!dirStat.isDirectory())
+            continue;
         let files;
         try {
             files = readdirSync(agentDir);
@@ -86,10 +107,12 @@ export function recoverTasks(dataDir) {
             try {
                 const raw = readFileSync(filePath, "utf-8");
                 const parsed = JSON.parse(raw);
-                // Sanity guard: skip completely malformed files (no id or toolName).
-                // Files missing origin (pre-Phase-14) are passed through to the manager
-                // so recoverOnStartup can warn about them and track the skip count.
-                if (!parsed.id || !parsed.toolName) {
+                // Shape guard — skip completely malformed files. Tasks always carry
+                // id + toolName + origin; the producer-side persistTaskSync writes
+                // all three unconditionally. A file failing this guard is either
+                // truncated mid-write or a legacy artifact operators should clean
+                // up manually.
+                if (!parsed.id || !parsed.toolName || !parsed.origin) {
                     continue;
                 }
                 const task = parsed;

package/node_modules/@comis/agent/dist/background/background-task-types.d.ts

@@ -6,6 +6,38 @@
 import type { BackgroundTaskOrigin } from "@comis/core";
 export type { BackgroundTaskOrigin };
 export type BackgroundTaskStatus = "running" | "completed" | "failed" | "cancelled";
+/**
+ * Notification policy for a background task. Typed enum (NOT a boolean):
+ * preserves intent across restart-recovery so the recovered task's dispatch
+ * path matches its original promote-time intent. A boolean collapses to
+ * true/false on rehydrate and loses the distinction between "the operator
+ * wanted deferred routing" and "the operator wanted immediate notification".
+ *
+ * - "deferred"  — Default. Wait for the dispatcher to attempt session
+ *                 re-entry; only fall back to user-visible notification
+ *                 when re-entry fails (session expired, hop cap hit).
+ * - "immediate" — Skip the dispatcher; fire user-visible notification
+ *                 immediately. Reserved for tasks that explicitly want
+ *                 the legacy literal-text notification.
+ * - "silent"    — Skip both dispatcher and user-visible notification.
+ *                 Reserved for fully-internal tasks.
+ *
+ * Default for new promote() calls: "deferred".
+ */
+export type BackgroundTaskNotificationPolicy = "deferred" | "immediate" | "silent";
+/**
+ * Three-state session lifecycle for a background task's notification routing.
+ * State-machine transitions are the single source of truth for at-most-once
+ * fallback.
+ *
+ * - "pending"    — Promotion happened; no completion event yet (or completion
+ *                   event arrived but dispatcher has not classified it).
+ * - "notified"   — Fallback notification fired (user-visible literal text);
+ *                   recovery-after-restart MUST NOT re-emit.
+ * - "dispatched" — Re-entry triggered against the originating session;
+ *                   no fallback notification needed.
+ */
+export type BackgroundSessionState = "pending" | "notified" | "dispatched";
 export interface BackgroundTask {
     id: string;
     toolName: string;
@@ -18,6 +50,13 @@ export interface BackgroundTask {
      *  promote-time, persisted on disk, preserved across recoverOnStartup.
      *  Required (no silent fallback). */
     origin: BackgroundTaskOrigin;
+    /** Live notification policy. Optional; recovery defaults to "deferred" when
+     *  absent. */
+    notificationPolicy?: BackgroundTaskNotificationPolicy;
+    /** Live three-state session lifecycle. Optional; recovery defaults to
+     *  "pending" when absent. The dispatcher inspects this before firing
+     *  notifyFn. */
+    dispatchState?: BackgroundSessionState;
     _promise?: Promise<unknown>;
     _abortController?: AbortController;
     _hardTimeoutTimer?: ReturnType<typeof setTimeout>;
@@ -34,4 +73,14 @@ export interface PersistedTaskState {
     /** Persisted origin -- read back by recoverOnStartup so completion routing
      *  survives daemon restarts. */
     origin: BackgroundTaskOrigin;
+    /**
+     * Notification policy chosen at promote time. Optional; recovery defaults
+     * to "deferred" when absent.
+     */
+    notificationPolicy?: BackgroundTaskNotificationPolicy;
+    /**
+     * Three-state session lifecycle. Optional; recovery defaults to "pending"
+     * when absent. The dispatcher inspects this before firing notifyFn.
+     */
+    dispatchState?: BackgroundSessionState;
 }

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;