@cogitator-ai/channels 0.15.12 → 0.17.0

package/dist/gateway.js

@@ -7,6 +7,7 @@ import { StatusReactionTracker } from './status-reactions.js';
 import { InboundDebouncer } from './inbound-debounce.js';
 import { formatEnvelope } from './envelope.js';
 import { MessageQueue } from './message-queue.js';
+import { CONVERSATIONS_KEY, defaultThreadKey, findConversation, legacyThreadKey, readConversations, rememberConversation, } from './thread-key.js';
 import { DEFAULT_APPROVE_WORDS, DEFAULT_DENY_WORDS, DEFAULT_NOT_ALLOWED_MESSAGE, DEFAULT_EXPIRED_MESSAGE, APPROVE_ACTION, DENY_ACTION, formatApprovalPrompt, parseApprovalReply, } from './approvals.js';
 /** Markdown as the channel takes it: as written when it renders Markdown itself. */
 function adaptFor(channel, msg, text) {
@@ -16,6 +17,18 @@ function adaptFor(channel, msg, text) {
 function limitFor(channel, msg) {
     return channel.maxMessageChars ?? getPlatformLimit(msg.channelType);
 }
+/**
+ * Lets the promise chains of what just settled run (the queue settles what it drops at once,
+ * and each answer settles a few promise steps later), without waiting for any timer.
+ */
+async function settleMicrotasks() {
+    for (let i = 0; i < 20; i++)
+        await Promise.resolve();
+}
+/** The key of a message whose answer the gateway tracks: its channel, chat and id. */
+function answerKey(msg) {
+    return `${msg.channelType}\u0000${msg.channelId}\u0000${msg.id}`;
+}
 function draftKey(channelType, channelId, draftId) {
     return `${channelType}:${channelId}:${draftId}`;
 }
@@ -26,6 +39,34 @@ const DEFAULT_SUMMARY_PROMPT = 'Summarize the following conversation between a u
     'Preserve facts, decisions, user preferences, open tasks and any commitments. ' +
     'Write a concise summary in the language of the conversation.';
 const TYPING_INTERVAL_MS = 4000;
+const DEFAULT_DRAIN_TIMEOUT_MS = 30_000;
+/** Why {@link Gateway.stop} aborts the runs still going past `drainTimeout` */
+const GATEWAY_STOPPED = new Error('The gateway stopped');
+/** Threads kept in the gateway's own bookkeeping (stats, sessions, envelope times) */
+export const MAX_TRACKED_THREADS = 10_000;
+/** Sets `key` as the most recent entry of `map`, dropping the least recent one past the limit */
+function touch(map, key, value) {
+    map.delete(key);
+    map.set(key, value);
+    if (map.size > MAX_TRACKED_THREADS) {
+        const oldest = map.keys().next();
+        if (!oldest.done)
+            map.delete(oldest.value);
+    }
+}
+/** Resolves `true` once `promise` settles, or `false` after `ms` */
+async function settlesWithin(promise, ms) {
+    let timer;
+    const timeout = new Promise((resolve) => {
+        timer = setTimeout(() => resolve(false), ms);
+    });
+    try {
+        return await Promise.race([promise.then(() => true), timeout]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
 function messageText(message) {
     if (typeof message.content === 'string')
         return message.content;
@@ -33,10 +74,6 @@ function messageText(message) {
         .map((part) => (part.type === 'text' ? part.text : `[${part.type}]`))
         .join(' ');
 }
-/** The thread of a user on a channel when `session.threadKey` does not name it */
-function defaultThreadId(channelType, userId) {
-    return `${channelType}:${userId}`;
-}
 function isScheduled(msg) {
     const raw = msg.raw;
     return typeof raw === 'object' && raw !== null && 'scheduled' in raw && raw.scheduled === true;
@@ -63,6 +100,8 @@ export class Gateway {
     hooks;
     approvalWords;
     pausedThreads = new Map();
+    /** The stop of every run in progress */
+    runs = new Set();
     /** The stop of each run, by the signal the run was given */
     stops = new WeakMap();
     /** The stop of each run streaming into a draft with a stop button, by channel, chat and draft */
@@ -72,6 +111,24 @@ export class Gateway {
     lastMessageTime = new Map();
     threads = new Map();
     inFlight = new Map();
+    /** Messages taken and not answered yet, for {@link idle} */
+    pending = new Set();
+    /** The stop in progress, which a second {@link stop} call returns */
+    stopping = null;
+    /** Calls of `channel.redeliver` in progress */
+    redeliveries = new Set();
+    /**
+     * Messages taken from a channel that can redeliver them, by the promise of their answer, until
+     * it settles. Those still here once `stop()` gave up on the runs are handed back.
+     */
+    unanswered = new Map();
+    /**
+     * Messages whose answer is going out or went out, by `answerKey`, so a run aborted after its
+     * first message was sent (or while it is being sent) is not redelivered
+     */
+    answeredKeys = new Set();
+    /** The last pending write of each user's session, so writes to one session never interleave */
+    sessionWrites = new Map();
     running = false;
     startedAt = null;
     messageCount = 0;
@@ -88,15 +145,23 @@ export class Gateway {
         };
         this.sessionManager =
             config.sessionManager ?? (config.memory ? new SessionManager(config.memory) : null);
+        const queueMode = config.queueMode ?? 'sequential';
         this.messageQueue =
-            config.queueMode && config.queueMode !== 'parallel'
-                ? new MessageQueue(config.queueMode, (msg, signal) => this.processMessage(msg, signal))
-                : null;
+            queueMode === 'parallel'
+                ? null
+                : new MessageQueue(queueMode, (msg, signal) => this.processMessage(msg, signal));
         this.debouncer = config.debounce?.enabled
-            ? new InboundDebouncer(config.debounce, (merged) => this.dispatch(merged))
+            ? new InboundDebouncer(config.debounce, async (merged, originals) => {
+                const answered = this.dispatch(merged);
+                const channel = this.channels.find((ch) => ch.type === merged.channelType);
+                if (channel?.redeliver)
+                    this.watchUnanswered(channel, merged, originals, answered);
+                else
+                    answered.catch(() => { });
+            })
             : null;
         for (const channel of this.channels) {
-            channel.onMessage((msg) => this.handleIncoming(msg));
+            channel.onMessage((msg) => this.handleIncoming(msg, false, channel));
             channel.onAction?.((action) => this.handleAction(channel, action));
             channel.onStop?.((stop) => {
                 this.stoppableDrafts
@@ -119,13 +184,48 @@ export class Gateway {
             throw failure.reason instanceof Error ? failure.reason : new Error(String(failure.reason));
         }
     }
-    async stop() {
+    /**
+     * Stops the gateway. Channels have already confirmed the messages they handed over, so it
+     * first lets them be answered: messages held by `debounce` are flushed, and it waits up to
+     * `drainTimeout` for the queues and the runs in progress. Then it aborts the runs still going,
+     * drops the messages still waiting, waits for the aborted runs to settle (up to `drainTimeout`
+     * again) and stops the channels. Messages that come in meanwhile are refused (see
+     * {@link injectMessage}). A second call while it stops returns the same promise.
+     */
+    stop() {
+        if (this.stopping)
+            return this.stopping;
         if (!this.running)
-            return;
+            return Promise.resolve();
         this.running = false;
-        if (this.debouncer)
+        const stopping = this.drainAndStop().finally(() => {
+            this.stopping = null;
+        });
+        this.stopping = stopping;
+        return stopping;
+    }
+    async drainAndStop() {
+        const timeout = this.config.drainTimeout ?? DEFAULT_DRAIN_TIMEOUT_MS;
+        if (this.debouncer) {
             await this.debouncer.flushAll();
+            this.debouncer.dispose();
+        }
+        if (!(await settlesWithin(this.idle(), timeout))) {
+            this.messageQueue?.dispose();
+            for (const run of this.runs)
+                run.abort(GATEWAY_STOPPED);
+            await settlesWithin(this.idle(), timeout);
+        }
         this.messageQueue?.dispose();
+        await settleMicrotasks();
+        for (const [answered, { channel, handled, messages }] of this.unanswered) {
+            this.unanswered.delete(answered);
+            if (this.answeredKeys.has(answerKey(handled)))
+                continue;
+            for (const msg of messages)
+                void this.redeliver(channel, msg);
+        }
+        await Promise.all([...this.redeliveries].map((redelivery) => settlesWithin(redelivery, timeout)));
         await Promise.all(this.channels.map((ch) => ch.stop()));
         this.startedAt = null;
     }
@@ -144,8 +244,26 @@ export class Gateway {
             .map(([threadId, info]) => ({ threadId, ...info, active: this.inFlight.has(threadId) }))
             .sort((a, b) => b.lastActiveAt - a.lastActiveAt);
     }
+    /**
+     * Feeds a message to the gateway as if a channel had received it (the scheduler sends its
+     * tasks this way). It resolves once the message is answered, or once it is buffered when
+     * `debounce` is on. It rejects when the message was not answered: its run failed (also
+     * reported to `onError`), it was aborted or dropped by {@link stop}, or it came in while the
+     * gateway was stopping.
+     */
     async injectMessage(msg) {
-        return this.handleIncoming(msg);
+        return this.handleIncoming(msg, true);
+    }
+    /**
+     * Resolves once every message the gateway has taken is answered: those waiting in their
+     * thread's queue and the runs in progress, including messages that come in while it waits.
+     * Messages held by `debounce` count from the moment they are flushed. {@link stop} waits
+     * for it, up to `drainTimeout`.
+     */
+    async idle() {
+        while (this.pending.size > 0) {
+            await Promise.allSettled(this.pending);
+        }
     }
     /**
      * Summarize older messages of a conversation thread, keeping `keepRecent` messages intact.
@@ -196,16 +314,31 @@ export class Gateway {
     }
     /**
      * The threads {@link compactAll} goes through: those served since the gateway started, and the
-     * default thread of each stored session when threads are not keyed by `session.threadKey`
+     * threads of each stored session when they are keyed by the default key (the conversations kept
+     * in the session's metadata, or the chat it was created in) or by `legacyThreadKey`
      */
     async knownThreads() {
         const threadIds = new Set(this.threads.keys());
-        if (!this.sessionManager || this.config.session?.threadKey) {
+        const threadKey = this.config.session?.threadKey;
+        if (!this.sessionManager || (threadKey && threadKey !== legacyThreadKey)) {
             return { threadIds: [...threadIds] };
         }
         try {
             for (const session of await this.sessionManager.list()) {
-                threadIds.add(defaultThreadId(session.channelType, session.userId));
+                if (threadKey) {
+                    threadIds.add(legacyThreadKey(session));
+                    continue;
+                }
+                const conversations = readConversations(session.metadata);
+                for (const conversation of conversations.length > 0
+                    ? conversations
+                    : [{ channelId: session.channelId }]) {
+                    threadIds.add(defaultThreadKey({
+                        channelType: session.channelType,
+                        userId: session.userId,
+                        ...conversation,
+                    }));
+                }
             }
         }
         catch (error) {
@@ -272,6 +405,7 @@ export class Gateway {
             ...(action.userName ? { userName: action.userName } : {}),
             ...(action.channelId.startsWith('-') ? { groupId: action.channelId } : {}),
             ...(action.topicId ? { topicId: action.topicId } : {}),
+            ...(action.conversationId ? { conversationId: action.conversationId } : {}),
             text: (approve ? this.approvalWords.approveWords : this.approvalWords.denyWords)[0] ?? '',
             raw: action.raw,
         };
@@ -300,7 +434,7 @@ export class Gateway {
         }
         await answer();
         await this.closePrompts(prompt.threadId, approve);
-        await this.handleIncoming(msg);
+        await this.handleIncoming(msg, false);
     }
     /**
      * Retires the buttons of a thread's approval prompts once it is answered: they show the
@@ -330,19 +464,118 @@ export class Gateway {
                 .catch(() => { });
         }
     }
-    async handleIncoming(msg) {
+    /**
+     * A message from a channel, a button or {@link injectMessage}. With a queue, a channel's message
+     * is only queued, so the channel goes on to its next update while the thread waits its turn.
+     * `untilAnswered` waits for the answer. A message of `channel` the gateway does not answer
+     * because it stops (refused while stopping, or dropped by `stop()`) goes back through
+     * `channel.redeliver`.
+     */
+    async handleIncoming(msg, untilAnswered, channel) {
+        if (this.stopping) {
+            const refused = new Error('The gateway is stopping: the message was dropped');
+            this.config.onError?.(refused, msg);
+            if (untilAnswered)
+                throw refused;
+            if (channel?.redeliver)
+                await this.redeliver(channel, msg);
+            return;
+        }
         if (this.debouncer) {
             this.debouncer.enqueue(msg);
             return;
         }
-        await this.dispatch(msg);
-    }
-    async dispatch(msg) {
-        if (this.messageQueue) {
-            this.messageQueue.push(msg, this.getThreadId(msg));
+        const answered = this.dispatch(msg);
+        if (channel?.redeliver && !untilAnswered)
+            this.watchUnanswered(channel, msg, [msg], answered);
+        if (untilAnswered || !this.messageQueue) {
+            const done = await answered;
+            if (!done && untilAnswered) {
+                throw new Error('The message was not answered: its run failed or was aborted');
+            }
             return;
         }
-        await this.processMessage(msg);
+        if (!channel?.redeliver)
+            answered.catch(() => { });
+    }
+    /** Hands a message back to its channel, reporting a failure to `onError`. */
+    redeliver(channel, msg) {
+        const redelivery = Promise.resolve()
+            .then(() => channel.redeliver?.(msg))
+            .catch((error) => this.config.onError?.(toError(error), msg))
+            .finally(() => this.redeliveries.delete(redelivery));
+        this.redeliveries.add(redelivery);
+        return redelivery;
+    }
+    /**
+     * Watches the answer of messages taken from `channel`: when the gateway stops before answering
+     * them they go back through `channel.redeliver`, and so do those whose run is still going when
+     * `stop()` gives up on it. A message whose answer went out is never handed back.
+     */
+    watchUnanswered(channel, handled, messages, answered) {
+        const entry = { channel, handled, messages };
+        this.unanswered.set(answered, entry);
+        void answered.then((done) => {
+            if (this.unanswered.get(answered) !== entry)
+                return;
+            this.unanswered.delete(answered);
+            if (done || this.running)
+                return;
+            for (const msg of messages)
+                void this.redeliver(channel, msg);
+        });
+    }
+    /** Puts a message through the queue of its thread, resolving once it is done with */
+    dispatch(msg) {
+        const answered = this.route(msg);
+        this.pending.add(answered);
+        const forget = () => {
+            this.pending.delete(answered);
+        };
+        answered.then(forget, forget);
+        return answered;
+    }
+    /** Resolves `true` once the message is handled, `false` when it failed or was dropped */
+    async route(incoming) {
+        const msg = await this.locateScheduled(incoming);
+        if (this.messageQueue)
+            return this.messageQueue.push(msg, this.getThreadId(msg));
+        return this.processMessage(msg);
+    }
+    /**
+     * A scheduled message names only its chat, so with the default thread key it gets the topic or
+     * conversation of the user's most recent conversation in that chat, kept in their session: the
+     * task is then answered in the thread and topic it was set up in.
+     */
+    async locateScheduled(msg) {
+        if (!isScheduled(msg) ||
+            msg.topicId ||
+            msg.conversationId ||
+            !this.sessionManager ||
+            this.config.session?.threadKey) {
+            return msg;
+        }
+        try {
+            const [session] = await this.sessionManager.list({
+                userId: msg.userId,
+                channelType: msg.channelType,
+                limit: 1,
+            });
+            const conversation = session
+                ? findConversation(readConversations(session.metadata), msg.channelId)
+                : undefined;
+            if (!conversation)
+                return msg;
+            return {
+                ...msg,
+                ...(conversation.topicId && { topicId: conversation.topicId }),
+                ...(conversation.conversationId && { conversationId: conversation.conversationId }),
+            };
+        }
+        catch (error) {
+            this.config.onError?.(toError(error), msg);
+            return msg;
+        }
     }
     rollMessageCounter() {
         const today = dayKey(Date.now());
@@ -363,24 +596,35 @@ export class Gateway {
         await runAll(0);
         return reachedEnd;
     }
+    /**
+     * Handles one message, `false` when its run failed or was aborted. A message for a channel
+     * the gateway does not run counts as handled: it never can be.
+     */
     async processMessage(msg, signal) {
         const channel = this.channels.find((ch) => ch.type === msg.channelType);
         if (!channel)
-            return;
+            return true;
         const threadId = this.getThreadId(msg);
         this.inFlight.set(threadId, (this.inFlight.get(threadId) ?? 0) + 1);
         const stop = new AbortController();
         const runSignal = signal ? AbortSignal.any([signal, stop.signal]) : stop.signal;
         this.stops.set(runSignal, stop);
+        this.runs.add(stop);
+        const key = answerKey(msg);
         try {
             await this.processWithChannel(msg, channel, threadId, runSignal);
+            if (this.answeredKeys.has(key))
+                return true;
+            return signal?.aborted !== true && stop.signal.reason !== GATEWAY_STOPPED;
         }
         catch (error) {
-            if (runSignal.aborted)
-                return;
-            this.config.onError?.(toError(error), msg);
+            if (!runSignal.aborted)
+                this.config.onError?.(toError(error), msg);
+            return this.answeredKeys.has(key);
         }
         finally {
+            this.answeredKeys.delete(key);
+            this.runs.delete(stop);
             const remaining = (this.inFlight.get(threadId) ?? 1) - 1;
             if (remaining <= 0)
                 this.inFlight.delete(threadId);
@@ -404,7 +648,7 @@ export class Gateway {
         this.rollMessageCounter();
         this.messageCount++;
         const known = this.threads.get(threadId);
-        this.threads.set(threadId, {
+        touch(this.threads, threadId, {
             channelType: msg.channelType,
             userId: msg.userId,
             ...(msg.userName || known?.userName ? { userName: msg.userName ?? known?.userName } : {}),
@@ -413,16 +657,22 @@ export class Gateway {
         });
         const agent = await this.resolveAgent(user);
         if (this.sessionManager) {
-            const session = await this.sessionManager.getOrCreate({
-                userId: msg.userId,
-                channelType: msg.channelType,
-                channelId: msg.channelId,
-                agentId: agent.name,
+            const sessionManager = this.sessionManager;
+            await this.writeSession(`${msg.channelType}:${msg.userId}`, async () => {
+                const session = await sessionManager.getOrCreate({
+                    userId: msg.userId,
+                    channelType: msg.channelType,
+                    channelId: msg.channelId,
+                    agentId: agent.name,
+                });
+                if (session.messageCount === 0) {
+                    await this.hooks?.emit('session:created', { session, threadId });
+                }
+                if (!this.config.session?.threadKey && !isScheduled(msg)) {
+                    await this.rememberConversation(sessionManager, session, msg);
+                }
+                await sessionManager.incrementMessageCount?.(session.id);
             });
-            if (session.messageCount === 0) {
-                await this.hooks?.emit('session:created', { session, threadId });
-            }
-            await this.sessionManager.incrementMessageCount?.(session.id);
         }
         const decision = this.readApprovalReply(msg, threadId, known !== undefined);
         if (!decision && this.config.memory && this.config.session?.compaction) {
@@ -480,7 +730,7 @@ export class Gateway {
         if (this.config.envelope?.enabled) {
             const prevTime = this.lastMessageTime.get(threadId);
             msg = { ...msg, text: formatEnvelope(msg, this.config.envelope, prevTime) };
-            this.lastMessageTime.set(threadId, Date.now());
+            touch(this.lastMessageTime, threadId, Date.now());
         }
         const { input, images } = await this.extractMedia(msg, agent);
         const options = {
@@ -619,6 +869,8 @@ export class Gateway {
             userId: msg.userId,
             channelType: msg.channelType,
             channelId: msg.channelId,
+            ...(msg.topicId && { topicId: msg.topicId }),
+            ...(msg.conversationId && { conversationId: msg.conversationId }),
             ...(signal ? { signal } : {}),
             ...(this.config.runTimeout !== undefined ? { timeout: this.config.runTimeout } : {}),
             ...(tracker
@@ -632,13 +884,24 @@ export class Gateway {
     async sendChunked(channel, msg, output, replyTo, buttons) {
         const chunks = chunkMessage(output, limitFor(channel, msg));
         const ids = [];
+        const key = answerKey(msg);
+        const first = !this.answeredKeys.has(key);
         for (let i = 0; i < chunks.length; i++) {
-            ids.push(await channel.sendText(msg.channelId, chunks[i], {
-                ...(i === 0 && replyTo ? { replyTo } : {}),
-                ...(i === chunks.length - 1 && buttons ? { buttons } : {}),
-                ...(msg.topicId ? { topicId: msg.topicId } : {}),
-                format: 'markdown',
-            }));
+            if (i === 0)
+                this.answeredKeys.add(key);
+            try {
+                ids.push(await channel.sendText(msg.channelId, chunks[i], {
+                    ...(i === 0 && replyTo ? { replyTo } : {}),
+                    ...(i === chunks.length - 1 && buttons ? { buttons } : {}),
+                    ...(msg.topicId ? { topicId: msg.topicId } : {}),
+                    format: 'markdown',
+                }));
+            }
+            catch (error) {
+                if (i === 0 && first)
+                    this.answeredKeys.delete(key);
+                throw error;
+            }
         }
         return ids;
     }
@@ -712,6 +975,7 @@ export class Gateway {
         const stoppedByUser = () => stop?.signal.aborted === true;
         const keepWhatWasWritten = async () => {
             await stream.finish();
+            this.answeredKeys.add(answerKey(msg));
             await this.hooks?.emit('stream:finished', {
                 msg,
                 threadId,
@@ -753,6 +1017,7 @@ export class Gateway {
         let replied = tokenCount > 0;
         if (replied) {
             await stream.finish();
+            this.answeredKeys.add(answerKey(msg));
         }
         else {
             await stream.abort();
@@ -774,7 +1039,41 @@ export class Gateway {
         if (this.config.session?.threadKey) {
             return this.config.session.threadKey(msg);
         }
-        return defaultThreadId(msg.channelType, msg.userId);
+        return defaultThreadKey(msg);
+    }
+    /**
+     * Keeps the message's conversation in the user's session, so its thread is known after a
+     * restart. A failure is reported to `onError` and does not keep the message from its answer.
+     */
+    async rememberConversation(sessionManager, session, msg) {
+        const conversations = rememberConversation(readConversations(session.metadata), msg);
+        if (!conversations)
+            return;
+        try {
+            await sessionManager.update(session.id, {
+                metadata: { [CONVERSATIONS_KEY]: conversations },
+            });
+        }
+        catch (error) {
+            this.config.onError?.(toError(error), msg);
+        }
+    }
+    /**
+     * Runs `write` after every earlier write to the same session has finished, so a read, change
+     * and write of its metadata never loses another one's change.
+     */
+    async writeSession(key, write) {
+        const previous = this.sessionWrites.get(key) ?? Promise.resolve();
+        const current = previous.then(write);
+        const settled = current.catch(() => { });
+        this.sessionWrites.set(key, settled);
+        try {
+            await current;
+        }
+        finally {
+            if (this.sessionWrites.get(key) === settled)
+                this.sessionWrites.delete(key);
+        }
     }
     async resolveAgent(user) {
         const agentOrFactory = this.config.agent;