comisai 1.0.37 → 1.0.41

package/node_modules/@comis/orchestrator/dist/cross-session/announcement-batcher.js

@@ -0,0 +1,235 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Announcement batcher for coalescing near-simultaneous sub-agent completions.
+ * When multiple sub-agents complete within seconds of each other for the same
+ * parent session, the batcher debounces and combines their announcements into a
+ * single batched LLM execution -- reducing N sequential parent calls to 1.
+ * Single completions with no siblings deliver after the debounce timer with
+ * original text unmodified (no batching overhead).
+ * @module
+ */
+import { parseFormattedSessionKey, systemNowMs, systemSetTimeout, systemClearTimeout, systemScheduleTimeout } from "@comis/core";
+import { withTimeout } from "@comis/shared";
+/** Hard timeout for announceToParent calls (300 seconds / 5 minutes).
+ *  Parent agents may call slow tools (image generation at 120s, web search, etc.)
+ *  in response to announcements. 30s caused premature fallback + duplicate delivery.
+ *  Inlined locally (rather than imported from packages/daemon/src/sub-agent-runner.ts)
+ *  to avoid an orchestrator -> daemon back-edge; the daemon-side constant
+ *  remains the canonical export for daemon consumers. */
+const ANNOUNCE_PARENT_TIMEOUT_MS = 300_000;
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Strip the `[System Message]\n` prefix and trailing LLM instruction line
+ * from announcement text, leaving only the task-specific content.
+ */
+function stripSystemPrefix(text) {
+    let result = text;
+    // Strip [System Message] prefix
+    if (result.startsWith("[System Message]\n")) {
+        result = result.slice("[System Message]\n".length);
+    }
+    // Strip trailing instruction line
+    const marker = "Inform the user about this completed background task.";
+    const idx = result.lastIndexOf(marker);
+    if (idx !== -1) {
+        result = result.slice(0, idx).trimEnd();
+    }
+    return result;
+}
+/**
+ * Sanitize announcement text for direct user delivery (fallback path).
+ * Extracts human-readable content (Summary or Result sections) and strips
+ * internal metadata (session keys, file paths, condensation stats, subagent
+ * markers, runtime stats). Returns a safe generic message if no extractable
+ * content is found.
+ * Used only in fallback `sendToChannel` calls -- the `announceToParent` path
+ * goes through the LLM which can filter metadata itself.
+ */
+export function sanitizeForUser(text) {
+    const GENERIC_FALLBACK = "A background task completed but the result could not be delivered properly. Please ask me to check on it.";
+    // First strip system prefix and trailing instruction (shared cleanup)
+    const stripped = stripSystemPrefix(text);
+    // Try to extract "Summary:" content
+    const summaryMatch = stripped.match(/(?:^|\n)Summary:\s*([\s\S]*?)(?=\n---|\n###|\n\[Subagent Result|$)/i);
+    let extracted = summaryMatch?.[1]?.trim();
+    // If no Summary found, try "Result:" content
+    if (!extracted) {
+        const resultMatch = stripped.match(/(?:^|\n)Result:\s*([\s\S]*?)(?=\n---|\n###|\n\[Subagent Result|$)/i);
+        extracted = resultMatch?.[1]?.trim();
+    }
+    // If neither found, return generic fallback
+    if (!extracted) {
+        return GENERIC_FALLBACK;
+    }
+    // Strip internal metadata patterns from extracted text
+    let sanitized = extracted;
+    // [Subagent Result: ...] markers
+    sanitized = sanitized.replace(/\[Subagent Result:[^\]]*\]/g, "");
+    // Session keys (e.g., default:user1:channel:123)
+    sanitized = sanitized.replace(/\b\w+:\w+:[a-z_-]+:\d+\b/g, "");
+    // File paths (starting with / or ~)
+    sanitized = sanitized.replace(/(?:\/[\w./-]+|~\/[\w./-]+)/g, "");
+    // Runtime stats lines (Runtime: ... | Steps: ... | Tokens:)
+    sanitized = sanitized.replace(/Runtime:.*\|.*Steps:.*\|.*Tokens:[^\n]*/g, "");
+    // Token counts/costs (Tokens: 500 ... Cost: $0.0050)
+    sanitized = sanitized.replace(/Tokens:\s*\d+.*Cost:\s*\$[\d.]+/g, "");
+    // Condensation stats (e.g., "150->50 messages" or "condensed 150 to 50")
+    sanitized = sanitized.replace(/\d+\u2192\d+\s*messages/g, "");
+    sanitized = sanitized.replace(/condensed\s+\d+\s+to\s+\d+/gi, "");
+    // Clean up: collapse multiple whitespace/newlines and trim
+    sanitized = sanitized.replace(/\n{3,}/g, "\n\n").replace(/ {2,}/g, " ").trim();
+    return sanitized || GENERIC_FALLBACK;
+}
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+const DEFAULT_DEBOUNCE_MS = 2000;
+export function createAnnouncementBatcher(deps) {
+    const debounceMs = deps.debounceMs ?? DEFAULT_DEBOUNCE_MS;
+    const queues = new Map();
+    const timers = new Map();
+    // -------------------------------------------------------------------------
+    // Internal delivery
+    // -------------------------------------------------------------------------
+    async function deliverBatch(key) {
+        timers.delete(key);
+        const items = queues.get(key);
+        queues.delete(key);
+        if (!items || items.length === 0)
+            return;
+        const first = items[0];
+        try {
+            const parsedKey = parseFormattedSessionKey(first.callerSessionKey);
+            if (!parsedKey) {
+                deps.logger?.warn({ batchKey: key, callerSessionKey: first.callerSessionKey, errorKind: "internal", hint: "Invalid parent session key in batched announcement; batch dropped" }, "Announcement batch delivery failed: invalid session key");
+                return;
+            }
+            if (items.length === 1) {
+                // Single item -- deliver with original text unmodified
+                try {
+                    await withTimeout(deps.announceToParent(first.callerAgentId, parsedKey, first.announcementText, first.announceChannelType, first.announceChannelId), ANNOUNCE_PARENT_TIMEOUT_MS, systemScheduleTimeout, "announceToParent");
+                    return;
+                }
+                catch (err) {
+                    // Batch state fields in timeout WARN for diagnostics
+                    deps.logger?.warn({ batchKey: key, err, batchSize: 1, itemsDelivered: 0, itemsRemaining: 1, isPartialDelivery: false, errorKind: "internal", hint: "Parent session injection failed/timed out; falling back to direct send" }, "Announcement single-item delivery failed");
+                    try {
+                        await deps.sendToChannel(first.announceChannelType, first.announceChannelId, sanitizeForUser(first.announcementText));
+                    }
+                    catch (sendErr) {
+                        deps.logger?.warn({ batchKey: key, runId: first.runId, err: sendErr, errorKind: "network", hint: "Single-item fallback direct send failed" }, "Single-item batcher fallback delivery failed");
+                        // Persist to DLQ on single-item fallback delivery failure
+                        if (deps.deadLetterQueue) {
+                            deps.deadLetterQueue.enqueue({
+                                announcementText: sanitizeForUser(first.announcementText),
+                                channelType: first.announceChannelType,
+                                channelId: first.announceChannelId,
+                                runId: first.runId,
+                                failedAt: systemNowMs(),
+                                attemptCount: 0,
+                                lastError: sendErr instanceof Error ? sendErr.message : String(sendErr),
+                            });
+                        }
+                    }
+                    return;
+                }
+            }
+            // Multiple items -- build combined message
+            const taskSections = items.map((item, idx) => {
+                const stripped = stripSystemPrefix(item.announcementText);
+                return `### Task ${idx + 1}\n${stripped}`;
+            }).join("\n\n");
+            const combinedText = `[System Message]\n` +
+                `${items.length} background tasks have completed.\n\n` +
+                `---\n\n` +
+                `${taskSections}\n\n` +
+                `---\n\n` +
+                `Review these completed tasks and summarize the results for the user in your own voice. If no user notification is needed, respond with NO_REPLY.`;
+            try {
+                await withTimeout(deps.announceToParent(first.callerAgentId, parsedKey, combinedText, first.announceChannelType, first.announceChannelId), ANNOUNCE_PARENT_TIMEOUT_MS, systemScheduleTimeout, "announceToParent");
+            }
+            catch (err) {
+                deps.logger?.warn({ batchKey: key, batchSize: items.length, itemsDelivered: 0, itemsRemaining: items.length, isPartialDelivery: false, err, errorKind: "internal", hint: "Parent session injection failed/timed out; falling back to direct send" }, "Announcement batched delivery failed");
+                // Fallback: deliver each item individually via direct channel send
+                let fallbackDelivered = 0;
+                for (const item of items) {
+                    await deps.sendToChannel(item.announceChannelType, item.announceChannelId, sanitizeForUser(item.announcementText)).then(() => {
+                        fallbackDelivered++;
+                    }).catch((sendErr) => {
+                        deps.logger?.warn({ batchKey: key, runId: item.runId, batchSize: items.length, itemsDelivered: fallbackDelivered, itemsRemaining: items.length - fallbackDelivered, isPartialDelivery: fallbackDelivered > 0, err: sendErr, errorKind: "network", hint: "Fallback direct send also failed for batch item" }, "Batch item fallback delivery failed");
+                        // Persist to DLQ on fallback delivery failure
+                        if (deps.deadLetterQueue) {
+                            deps.deadLetterQueue.enqueue({
+                                announcementText: sanitizeForUser(item.announcementText),
+                                channelType: item.announceChannelType,
+                                channelId: item.announceChannelId,
+                                runId: item.runId,
+                                failedAt: systemNowMs(),
+                                attemptCount: 0,
+                                lastError: sendErr instanceof Error ? sendErr.message : String(sendErr),
+                            });
+                        }
+                    });
+                }
+            }
+        }
+        catch (err) {
+            deps.logger?.warn({ batchKey: key, batchSize: items.length, err, errorKind: "internal", hint: "Batch announcement delivery failed; individual results are logged separately" }, "Announcement batch delivery error");
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Public API
+    // -------------------------------------------------------------------------
+    function enqueue(params) {
+        const batchKey = `${params.callerAgentId}:${params.callerSessionKey}`;
+        let queue = queues.get(batchKey);
+        if (!queue) {
+            queue = [];
+            queues.set(batchKey, queue);
+        }
+        queue.push(params);
+        // Clear existing debounce timer and reset
+        const existingTimer = timers.get(batchKey);
+        if (existingTimer !== undefined) {
+            systemClearTimeout(existingTimer);
+        }
+        const timer = systemSetTimeout(() => {
+            void deliverBatch(batchKey);
+        }, debounceMs);
+        // Allow process to exit even with pending timers
+        if (typeof timer === "object" && "unref" in timer) {
+            timer.unref();
+        }
+        timers.set(batchKey, timer);
+        deps.logger?.debug({ batchKey, queueSize: queue.length, runId: params.runId }, "Announcement enqueued for batching");
+    }
+    async function flush() {
+        // Clear all debounce timers
+        for (const timer of timers.values()) {
+            systemClearTimeout(timer);
+        }
+        timers.clear();
+        // Deliver all pending batches
+        const keys = [...queues.keys()];
+        await Promise.allSettled(keys.map((key) => deliverBatch(key)));
+    }
+    async function shutdown() {
+        await flush();
+        queues.clear();
+        timers.clear();
+    }
+    return {
+        enqueue,
+        flush,
+        shutdown,
+        get pending() {
+            let count = 0;
+            for (const queue of queues.values()) {
+                count += queue.length;
+            }
+            return count;
+        },
+    };
+}

package/node_modules/@comis/orchestrator/dist/cross-session/announcement-dead-letter.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Announcement Dead-Letter Queue: JSONL-backed persistence and retry mechanism
+ * for failed sub-agent announcements.
+ * When a sub-agent announcement fails to deliver (provider outage, channel
+ * error), the entry is persisted to a JSONL file for later retry. The drain()
+ * method retries delivery sequentially, respects retry intervals, drops expired
+ * entries, and uses atomic file writes for crash safety.
+ * Dead-Letter Queue
+ * @module
+ */
+import type { TypedEventBus } from "@comis/core";
+/** Minimal pino-compatible logger for dead-letter queue diagnostics.
+ *  Structurally identical to packages/daemon/src/sub-agent-runner.ts
+ *  `SubAgentRunnerLogger`; inlined to avoid an orchestrator->daemon
+ *  back-edge that a relative import would have introduced after the
+ *  cross-session move. Daemon consumers continue to pass their
+ *  `SubAgentRunnerLogger`-shaped loggers unchanged; the structural
+ *  compatibility guarantees no call-site change. */
+export interface AnnouncementLogger {
+    info(obj: Record<string, unknown>, msg: string): void;
+    warn(obj: Record<string, unknown>, msg: string): void;
+    error(obj: Record<string, unknown>, msg: string): void;
+    debug(obj: Record<string, unknown>, msg: string): void;
+}
+/**
+ * Canonical 9-channel set covering production platform adapters. Used as the
+ * closed-union discriminator for sendToChannel(type, ...) instead of an open
+ * `string`. Local definition (no @comis/core export currently aggregates the
+ * platform-adapter channel types — the rest of the codebase carries this
+ * set implicitly as adapter-specific channelType strings). "echo" is
+ * included for development/testing parity with channels/echo-adapter.
+ */
+export type ChannelType = "discord" | "telegram" | "slack" | "whatsapp" | "imessage" | "signal" | "irc" | "line" | "email" | "echo";
+/** A single dead-letter queue entry representing a failed announcement. */
+export interface DeadLetterEntry {
+    id: string;
+    announcementText: string;
+    channelType: ChannelType;
+    channelId: string;
+    runId: string;
+    /** Timestamp when the original delivery failed. */
+    failedAt: number;
+    /** Number of retry attempts (starts at 0, incremented on each retry). */
+    attemptCount: number;
+    /** Timestamp of the most recent retry attempt. */
+    lastAttemptAt: number;
+    /** Last error message for diagnostics. */
+    lastError?: string;
+    /** Thread ID for threaded delivery Persisted so retried deliveries land in the correct thread. */
+    threadId?: string;
+}
+/** Dead-letter queue interface for announcement retry management. */
+export interface AnnouncementDeadLetterQueue {
+    /**
+     * Persist a failed announcement to the dead-letter queue.
+     * Synchronous return, fire-and-forget file write. Never throws.
+     */
+    enqueue(entry: Omit<DeadLetterEntry, "id" | "lastAttemptAt">): void;
+    /**
+     * Retry delivery of queued entries via the provided sendToChannel callback.
+     * Processes entries sequentially, drops expired entries, uses atomic write.
+     */
+    drain(sendToChannel: (type: ChannelType, id: string, text: string, options?: {
+        threadId?: string;
+    }) => Promise<boolean>): Promise<void>;
+    /** Return the current number of entries in the queue. */
+    size(): number;
+}
+/** Configuration options for the dead-letter queue factory. */
+interface AnnouncementDeadLetterQueueOptions {
+    /** JSONL file path (already safePath'd by caller). */
+    filePath: string;
+    /** Maximum retry attempts before dropping an entry (default: 5). */
+    maxRetries?: number;
+    /** Minimum interval between retry attempts in ms (default: 60_000). */
+    retryIntervalMs?: number;
+    /** Maximum age of an entry in ms before it is dropped (default: 3_600_000). */
+    maxAgeMs?: number;
+    /** Maximum number of entries in the queue (default: 100). */
+    maxEntries?: number;
+    /** Event bus for emitting dead-letter events. */
+    eventBus: TypedEventBus;
+    /** Optional logger for diagnostics. */
+    logger?: AnnouncementLogger;
+}
+/**
+ * Create an announcement dead-letter queue backed by a JSONL file.
+ * Uses closure over mutable state (no classes) following the factory pattern
+ * from provider-health-monitor.ts.
+ */
+export declare function createAnnouncementDeadLetterQueue(opts: AnnouncementDeadLetterQueueOptions): AnnouncementDeadLetterQueue;
+export {};

package/node_modules/@comis/orchestrator/dist/cross-session/announcement-dead-letter.js

@@ -0,0 +1,219 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Announcement Dead-Letter Queue: JSONL-backed persistence and retry mechanism
+ * for failed sub-agent announcements.
+ * When a sub-agent announcement fails to deliver (provider outage, channel
+ * error), the entry is persisted to a JSONL file for later retry. The drain()
+ * method retries delivery sequentially, respects retry intervals, drops expired
+ * entries, and uses atomic file writes for crash safety.
+ * Dead-Letter Queue
+ * @module
+ */
+import { appendFile, writeFile, rename, readFile, unlink } from "node:fs/promises";
+import { randomUUID, randomBytes } from "node:crypto";
+import { systemNowMs } from "@comis/core";
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/**
+ * Atomic write: write to temp file, then rename to target.
+ * Cleans up temp file on failure.
+ */
+async function atomicWrite(filePath, content) {
+    const tmpPath = filePath + `.tmp.${randomBytes(4).toString("hex")}`;
+    try {
+        await writeFile(tmpPath, content, "utf-8");
+        await rename(tmpPath, filePath);
+    }
+    catch (err) {
+        // Best-effort cleanup of temp file
+        try {
+            await unlink(tmpPath);
+        }
+        catch {
+            // Ignore cleanup failure
+        }
+        // @allow-throw: boundary adapter wrapping node:fs/promises (writeFile + rename); callers wrap via try/catch (see drain() catch at line 325). Renaming would not change behavior.
+        throw err;
+    }
+}
+/**
+ * Parse JSONL content into DeadLetterEntry array.
+ * Skips empty lines and corrupt entries (logs warning for corrupt lines).
+ */
+function parseEntries(content, logger) {
+    const result = [];
+    const lines = content.split("\n");
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (trimmed === "")
+            continue;
+        try {
+            result.push(JSON.parse(trimmed));
+        }
+        catch {
+            logger?.warn({ errorKind: "internal", hint: "Corrupt DLQ entry skipped" }, "Corrupt dead-letter entry skipped");
+        }
+    }
+    return result;
+}
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+/**
+ * Create an announcement dead-letter queue backed by a JSONL file.
+ * Uses closure over mutable state (no classes) following the factory pattern
+ * from provider-health-monitor.ts.
+ */
+export function createAnnouncementDeadLetterQueue(opts) {
+    const maxRetries = opts.maxRetries ?? 5;
+    const retryIntervalMs = opts.retryIntervalMs ?? 60_000;
+    const maxAgeMs = opts.maxAgeMs ?? 3_600_000;
+    const maxEntries = opts.maxEntries ?? 100;
+    const { filePath, eventBus, logger } = opts;
+    // Closure state
+    let entries = [];
+    let draining = false;
+    let loaded = false;
+    /** Lazy-load entries from disk on first drain. */
+    async function loadFromDisk() {
+        if (loaded)
+            return;
+        loaded = true;
+        try {
+            const content = await readFile(filePath, "utf-8");
+            entries = parseEntries(content, logger);
+            logger?.debug({ entryCount: entries.length }, "Loaded dead-letter entries from disk");
+        }
+        catch (err) {
+            // ENOENT is expected (no file yet)
+            if (err instanceof Error && "code" in err && err.code === "ENOENT") {
+                return;
+            }
+            logger?.warn({ err, errorKind: "internal", hint: "DLQ file read failed; starting with empty queue" }, "Failed to read dead-letter file");
+        }
+    }
+    return {
+        enqueue(entry) {
+            try {
+                const fullEntry = {
+                    ...entry,
+                    id: randomUUID(),
+                    lastAttemptAt: systemNowMs(),
+                };
+                // Enforce capacity cap
+                if (entries.length >= maxEntries) {
+                    const dropped = entries.shift();
+                    logger?.error({
+                        errorKind: "resource",
+                        hint: "Dead-letter queue at capacity; oldest entry dropped",
+                        droppedRunId: dropped?.runId,
+                    }, "Dead-letter queue at capacity");
+                }
+                entries.push(fullEntry);
+                // Emit dead-lettered event
+                eventBus.emit("announcement:dead_lettered", {
+                    runId: fullEntry.runId,
+                    channelType: fullEntry.channelType,
+                    reason: fullEntry.lastError ?? "delivery_failed",
+                    timestamp: systemNowMs(),
+                });
+                // Fire-and-forget file append
+                appendFile(filePath, JSON.stringify(fullEntry) + "\n", "utf-8").catch((err) => logger?.warn({ err, errorKind: "internal", hint: "DLQ append failed; entry exists in memory only" }, "Dead-letter file append failed"));
+            }
+            catch (err) {
+                // enqueue must NEVER throw
+                logger?.warn({ err, errorKind: "internal", hint: "DLQ enqueue failed entirely" }, "Dead-letter enqueue failed");
+            }
+        },
+        async drain(sendToChannel) {
+            // Concurrent drain protection
+            if (draining)
+                return;
+            draining = true;
+            try {
+                // Lazy load on first drain
+                await loadFromDisk();
+                if (entries.length === 0)
+                    return;
+                const now = systemNowMs();
+                // Filter out expired entries
+                entries = entries.filter((entry) => {
+                    if (entry.attemptCount >= maxRetries) {
+                        logger?.debug({ runId: entry.runId, attemptCount: entry.attemptCount }, "Dead-letter entry dropped: max retries exceeded");
+                        return false;
+                    }
+                    if (now - entry.failedAt >= maxAgeMs) {
+                        logger?.debug({ runId: entry.runId, ageMs: now - entry.failedAt }, "Dead-letter entry dropped: max age exceeded");
+                        return false;
+                    }
+                    return true;
+                });
+                // Process remaining entries sequentially (no retry storm)
+                const delivered = new Set();
+                for (const entry of entries) {
+                    // Skip if not yet eligible for retry
+                    if (now - entry.lastAttemptAt < retryIntervalMs)
+                        continue;
+                    try {
+                        // Pass persisted threadId so retried deliveries land in the correct thread
+                        const success = await sendToChannel(entry.channelType, entry.channelId, entry.announcementText, entry.threadId ? { threadId: entry.threadId } : undefined);
+                        if (success) {
+                            delivered.add(entry.id);
+                            eventBus.emit("announcement:dead_letter_delivered", {
+                                runId: entry.runId,
+                                channelType: entry.channelType,
+                                attemptCount: entry.attemptCount + 1,
+                                timestamp: systemNowMs(),
+                            });
+                            logger?.debug({ runId: entry.runId, attemptCount: entry.attemptCount + 1 }, "Dead-letter entry delivered successfully");
+                        }
+                        else {
+                            entry.attemptCount++;
+                            entry.lastAttemptAt = systemNowMs();
+                            entry.lastError = "sendToChannel returned false";
+                        }
+                    }
+                    catch (err) {
+                        entry.attemptCount++;
+                        entry.lastAttemptAt = systemNowMs();
+                        entry.lastError =
+                            err instanceof Error ? err.message : String(err);
+                    }
+                }
+                // Remove delivered entries
+                entries = entries.filter((e) => !delivered.has(e.id));
+                // Persist remaining entries atomically
+                try {
+                    if (entries.length === 0) {
+                        // Clean up empty file
+                        try {
+                            await unlink(filePath);
+                        }
+                        catch (err) {
+                            // ENOENT is fine (file already gone)
+                            if (!(err instanceof Error && "code" in err &&
+                                err.code === "ENOENT")) {
+                                // @allow-throw: re-raise non-ENOENT unlink failure to the outer drain() catch (line 325) which logs + degrades; boundary adapter pattern.
+                                throw err;
+                            }
+                        }
+                    }
+                    else {
+                        const content = entries.map((e) => JSON.stringify(e)).join("\n") + "\n";
+                        await atomicWrite(filePath, content);
+                    }
+                }
+                catch (err) {
+                    logger?.warn({ err, errorKind: "internal", hint: "DLQ atomic write failed; in-memory state may diverge from disk" }, "Dead-letter file write failed after drain");
+                }
+            }
+            finally {
+                draining = false;
+            }
+        },
+        size() {
+            return entries.length;
+        },
+    };
+}