comisai 1.0.33 → 1.0.36

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

@@ -1,6 +1,7 @@
 import type { BackgroundTasksConfig } from "@comis/core";
 import type { AgentToolResult } from "@mariozechner/pi-agent-core";
 import type { BackgroundTaskManager, NotifyFn } from "./background-task-manager.js";
+import type { BackgroundTaskOrigin } from "./background-task-types.js";
 /**
  * Tool definition interface matching pi-agent-core ToolDefinition.
  *
@@ -19,9 +20,18 @@ export interface ToolDefinition {
 /**
  * Wrap a tool's execute() with auto-background promotion on timeout.
  *
+ * `originResolver` is called synchronously at promote-time (before the agent
+ * yields) so the captured origin reflects the originating session, not the
+ * background continuation context. Returns undefined when the wrap-site cannot
+ * resolve a valid origin (e.g., during a non-session-bound subagent path) --
+ * in that case the wrapper falls through to foreground execution (no promote).
+ *
+ * Explicit threading, NOT AsyncLocalStorage. Origin flows through factory
+ * params end-to-end.
+ *
  * If the tool is in `config.excludeTools`, returns unchanged.
  * If the tool completes before `config.autoBackgroundMs`, returns the result directly.
  * If the tool exceeds the timeout, promotes to background via manager.promote().
  * If promotion fails (concurrency limit), awaits the tool normally (foreground fallback).
  */
-export declare function wrapToolForAutoBackground(tool: ToolDefinition, manager: BackgroundTaskManager, config: BackgroundTasksConfig, notifyFn: NotifyFn, agentId: string): ToolDefinition;
+export declare function wrapToolForAutoBackground(tool: ToolDefinition, manager: BackgroundTaskManager, config: BackgroundTasksConfig, notifyFn: NotifyFn, originResolver: () => BackgroundTaskOrigin | undefined): ToolDefinition;

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

@@ -12,12 +12,21 @@ import { suppressError } from "@comis/shared";
 /**
  * Wrap a tool's execute() with auto-background promotion on timeout.
  *
+ * `originResolver` is called synchronously at promote-time (before the agent
+ * yields) so the captured origin reflects the originating session, not the
+ * background continuation context. Returns undefined when the wrap-site cannot
+ * resolve a valid origin (e.g., during a non-session-bound subagent path) --
+ * in that case the wrapper falls through to foreground execution (no promote).
+ *
+ * Explicit threading, NOT AsyncLocalStorage. Origin flows through factory
+ * params end-to-end.
+ *
  * If the tool is in `config.excludeTools`, returns unchanged.
  * If the tool completes before `config.autoBackgroundMs`, returns the result directly.
  * If the tool exceeds the timeout, promotes to background via manager.promote().
  * If promotion fails (concurrency limit), awaits the tool normally (foreground fallback).
  */
-export function wrapToolForAutoBackground(tool, manager, config, notifyFn, agentId) {
+export function wrapToolForAutoBackground(tool, manager, config, notifyFn, originResolver) {
     if (config.excludeTools.includes(tool.name)) {
         return tool;
     }
@@ -57,8 +66,16 @@ export function wrapToolForAutoBackground(tool, manager, config, notifyFn, agent
             if (raceResult.kind === "result") {
                 return raceResult.value;
             }
-            // Timeout: attempt background promotion
-            const promoteResult = manager.promote(agentId, tool.name, taskPromise, ac);
+            // Timeout: resolve origin synchronously before yielding to the background.
+            // Explicit threading, NOT AsyncLocalStorage.
+            const origin = originResolver();
+            if (!origin) {
+                // No originating session context (e.g., wrap-site is a subagent without
+                // a captured caller session). Treat like a concurrency-limit fallback:
+                // run the tool in the foreground, no background promotion.
+                return await taskPromise;
+            }
+            const promoteResult = manager.promote(tool.name, taskPromise, ac, origin);
             if (!promoteResult.ok) {
                 // Concurrency limit hit: fall back to foreground (await normally)
                 return await taskPromise;
@@ -73,7 +90,7 @@ export function wrapToolForAutoBackground(tool, manager, config, notifyFn, agent
             // collapses to `content: undefined` and triggers the silent-LLM-failure
             // cascade (see AGENTS.md / auto-background-middleware.test.ts invariant).
             const placeholderText = `Tool "${tool.name}" is taking longer than expected and has been moved to the background. ` +
-                `Task ID: ${taskId}. The user will be notified when it completes.`;
+                `Task ID: ${taskId}. I'll continue when it completes.`;
             return {
                 content: [{ type: "text", text: placeholderText }],
                 details: {

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 } from "./background-task-types.js";
+import type { BackgroundTask, BackgroundTaskOrigin } from "./background-task-types.js";
 /** Notification callback fired when background task completes or fails. */
 export type NotifyFn = (opts: {
     agentId: string;
@@ -21,7 +21,7 @@ export interface BackgroundTaskManagerOpts {
     maxBackgroundDurationMs?: number;
 }
 export interface BackgroundTaskManager {
-    promote(agentId: string, toolName: string, promise: Promise<unknown>, ac: AbortController): Result<string, Error>;
+    promote(toolName: string, promise: Promise<unknown>, ac: AbortController, origin: BackgroundTaskOrigin): Result<string, Error>;
     complete(taskId: string, result: unknown, notifyFn?: NotifyFn): void;
     fail(taskId: string, error: unknown, notifyFn?: NotifyFn): void;
     cancel(taskId: string): Result<void, Error>;

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

@@ -35,7 +35,26 @@ export function createBackgroundTaskManager(opts) {
         }
     }
     const manager = {
-        promote(agentId, toolName, promise, ac) {
+        promote(toolName, promise, ac, origin) {
+            // 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)"));
+            }
+            if (!origin.agentId || origin.agentId.length === 0) {
+                return err(new Error("BackgroundTaskOrigin.agentId must be a non-empty string"));
+            }
+            if (!origin.sessionKey || origin.sessionKey.length === 0) {
+                return err(new Error("BackgroundTaskOrigin.sessionKey must be a non-empty string"));
+            }
+            if (!origin.channelType || origin.channelType.length === 0) {
+                return err(new Error("BackgroundTaskOrigin.channelType must be a non-empty string"));
+            }
+            if (!origin.channelId || origin.channelId.length === 0) {
+                return err(new Error("BackgroundTaskOrigin.channelId must be a non-empty string"));
+            }
+            // traceId may be null (per BackgroundTaskOriginSchema), so no length check.
+            // backgroundHopCount has a schema-level default of 0; no inline guard needed.
+            const agentId = origin.agentId;
             const agentCurrent = perAgentCount.get(agentId) ?? 0;
             if (agentCurrent >= maxPerAgent) {
                 return err(new Error(`Concurrency limit exceeded: agent ${agentId} has ${agentCurrent}/${maxPerAgent} tasks`));
@@ -46,24 +65,25 @@ export function createBackgroundTaskManager(opts) {
             const taskId = randomUUID();
             const task = {
                 id: taskId,
-                agentId,
                 toolName,
                 status: "running",
                 startedAt: Date.now(),
+                origin,
                 _promise: promise,
                 _abortController: ac,
             };
-            tasks.set(taskId, task);
-            incrementCounters(agentId);
-            // sync write BEFORE returning placeholder
-            persistTaskSync(dataDir, task);
-            // Hard timeout
-            task._hardTimeoutTimer = setTimeout(() => {
+            // Hard-timeout abort
+            const timer = setTimeout(() => {
                 if (task.status === "running") {
                     ac.abort();
                     manager.fail(taskId, new Error("Hard timeout exceeded"));
                 }
             }, maxBackgroundDurationMs);
+            timer.unref();
+            task._hardTimeoutTimer = timer;
+            tasks.set(taskId, task);
+            incrementCounters(agentId);
+            persistTaskSync(dataDir, task);
             eventBus.emit("background_task:promoted", {
                 agentId,
                 taskId,
@@ -81,19 +101,20 @@ export function createBackgroundTaskManager(opts) {
             task.result = truncateResult(result);
             if (task._hardTimeoutTimer)
                 clearTimeout(task._hardTimeoutTimer);
-            decrementCounters(task.agentId);
+            decrementCounters(task.origin.agentId);
             persistTaskSync(dataDir, task);
             const durationMs = task.completedAt - task.startedAt;
             eventBus.emit("background_task:completed", {
-                agentId: task.agentId,
+                agentId: task.origin.agentId,
                 taskId,
                 toolName: task.toolName,
                 durationMs,
+                origin: task.origin,
                 timestamp: Date.now(),
             });
             if (notifyFn) {
                 suppressError(notifyFn({
-                    agentId: task.agentId,
+                    agentId: task.origin.agentId,
                     message: `Background task "${task.toolName}" completed (${Math.round(durationMs / 1000)}s). Task ID: ${taskId}`,
                     priority: "normal",
                     origin: "background_task",
@@ -109,20 +130,21 @@ export function createBackgroundTaskManager(opts) {
             task.error = error instanceof Error ? error.message : String(error);
             if (task._hardTimeoutTimer)
                 clearTimeout(task._hardTimeoutTimer);
-            decrementCounters(task.agentId);
+            decrementCounters(task.origin.agentId);
             persistTaskSync(dataDir, task);
             const durationMs = task.completedAt - task.startedAt;
             eventBus.emit("background_task:failed", {
-                agentId: task.agentId,
+                agentId: task.origin.agentId,
                 taskId,
                 toolName: task.toolName,
                 error: task.error,
                 durationMs,
+                origin: task.origin,
                 timestamp: Date.now(),
             });
             if (notifyFn) {
                 suppressError(notifyFn({
-                    agentId: task.agentId,
+                    agentId: task.origin.agentId,
                     message: `Background task "${task.toolName}" failed: ${task.error}. Task ID: ${taskId}`,
                     priority: "normal",
                     origin: "background_task",
@@ -141,10 +163,10 @@ export function createBackgroundTaskManager(opts) {
                 task._abortController.abort();
             if (task._hardTimeoutTimer)
                 clearTimeout(task._hardTimeoutTimer);
-            decrementCounters(task.agentId);
+            decrementCounters(task.origin.agentId);
             persistTaskSync(dataDir, task);
             eventBus.emit("background_task:cancelled", {
-                agentId: task.agentId,
+                agentId: task.origin.agentId,
                 taskId,
                 toolName: task.toolName,
                 timestamp: Date.now(),
@@ -155,7 +177,7 @@ export function createBackgroundTaskManager(opts) {
             return tasks.get(taskId);
         },
         getTasks(agentId) {
-            return [...tasks.values()].filter((t) => t.agentId === agentId);
+            return [...tasks.values()].filter((t) => t.origin.agentId === agentId);
         },
         getAllTasks() {
             return [...tasks.values()];
@@ -163,8 +185,19 @@ export function createBackgroundTaskManager(opts) {
         recoverOnStartup() {
             const recovered = recoverTasks(dataDir);
             let count = 0;
+            let skipped = 0;
             for (const persisted of recovered) {
-                // Only import tasks that were recovered (previously running -> now failed)
+                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,
                 };
@@ -172,11 +205,12 @@ export function createBackgroundTaskManager(opts) {
                 if (persisted.status === "failed" && persisted.error === "Daemon restarted while task was running") {
                     count++;
                     eventBus.emit("background_task:failed", {
-                        agentId: task.agentId,
+                        agentId: task.origin.agentId,
                         taskId: task.id,
                         toolName: task.toolName,
                         error: persisted.error,
                         durationMs: (persisted.completedAt ?? Date.now()) - persisted.startedAt,
+                        origin: task.origin,
                         timestamp: Date.now(),
                     });
                 }
@@ -184,13 +218,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");
+            }
         },
         cleanup(maxAgeMs = 86_400_000) {
             const cutoff = Date.now() - maxAgeMs;
             for (const [taskId, task] of tasks) {
                 if (task.status !== "running" && (task.completedAt ?? task.startedAt) < cutoff) {
                     tasks.delete(taskId);
-                    removeTaskFile(dataDir, task.agentId, taskId);
+                    removeTaskFile(dataDir, task.origin.agentId, taskId);
                 }
             }
         },

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

@@ -17,13 +17,13 @@ export const TASK_DIR_NAME = "background-tasks";
 function toPersistedState(task) {
     return {
         id: task.id,
-        agentId: task.agentId,
         toolName: task.toolName,
         status: task.status,
         startedAt: task.startedAt,
         completedAt: task.completedAt,
         result: task.result,
         error: task.error,
+        origin: task.origin,
     };
 }
 /**
@@ -32,7 +32,7 @@ function toPersistedState(task) {
  * Writes to `dataDir/{agentId}/{taskId}.json`.
  */
 export function persistTaskSync(dataDir, task) {
-    const agentDir = safePath(dataDir, task.agentId);
+    const agentDir = safePath(dataDir, task.origin.agentId);
     mkdirSync(agentDir, { recursive: true });
     const filePath = safePath(agentDir, `${task.id}.json`);
     const state = "_promise" in task ? toPersistedState(task) : task;
@@ -85,7 +85,14 @@ export function recoverTasks(dataDir) {
             const filePath = safePath(agentDir, file);
             try {
                 const raw = readFileSync(filePath, "utf-8");
-                const task = JSON.parse(raw);
+                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) {
+                    continue;
+                }
+                const task = parsed;
                 if (task.status === "running") {
                     task.status = "failed";
                     task.error = "Daemon restarted while task was running";

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

@@ -1,18 +1,23 @@
 /**
- * Background task types for automatic tool execution promotion.
+ * Background task type definitions.
  *
  * @module
  */
+import type { BackgroundTaskOrigin } from "@comis/core";
+export type { BackgroundTaskOrigin };
 export type BackgroundTaskStatus = "running" | "completed" | "failed" | "cancelled";
 export interface BackgroundTask {
     id: string;
-    agentId: string;
     toolName: string;
     status: BackgroundTaskStatus;
     startedAt: number;
     completedAt?: number;
     result?: string;
     error?: string;
+    /** Originating session attribution (incl. backgroundHopCount) -- captured at
+     *  promote-time, persisted on disk, preserved across recoverOnStartup.
+     *  Required (no silent fallback). */
+    origin: BackgroundTaskOrigin;
     _promise?: Promise<unknown>;
     _abortController?: AbortController;
     _hardTimeoutTimer?: ReturnType<typeof setTimeout>;
@@ -20,11 +25,13 @@ export interface BackgroundTask {
 /** Serializable subset of BackgroundTask for file persistence. */
 export interface PersistedTaskState {
     id: string;
-    agentId: string;
     toolName: string;
     status: BackgroundTaskStatus;
     startedAt: number;
     completedAt?: number;
     result?: string;
     error?: string;
+    /** Persisted origin -- read back by recoverOnStartup so completion routing
+     *  survives daemon restarts. */
+    origin: BackgroundTaskOrigin;
 }

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

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * Background task types for automatic tool execution promotion.
+ * Background task type definitions.
  *
  * @module
  */

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,53 @@
+/**
+ * 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;
+    taskManager: Pick<BackgroundTaskManager, "getTask">;
+    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;