@cogitator-ai/channels 0.15.12 → 0.16.0

package/dist/gateway.d.ts

@@ -23,6 +23,12 @@ export interface GatewayFullConfig extends GatewayConfig {
      * the prompt cache they open with
      */
     brief?: (msg: ChannelMessage) => string | undefined;
+    /**
+     * How long {@link Gateway.stop} waits for the queued messages and the runs in progress to be
+     * answered, in milliseconds (default 30000). What is still running then is aborted, and what
+     * is still waiting is dropped.
+     */
+    drainTimeout?: number;
 }
 export interface GatewaySessionInfo {
     threadId: string;
@@ -33,6 +39,8 @@ export interface GatewaySessionInfo {
     lastActiveAt: number;
     active: boolean;
 }
+/** Threads kept in the gateway's own bookkeeping (stats, sessions, envelope times) */
+export declare const MAX_TRACKED_THREADS = 10000;
 export declare class Gateway {
     private readonly config;
     private readonly channels;
@@ -44,6 +52,8 @@ export declare class Gateway {
     private readonly hooks;
     private readonly approvalWords;
     private readonly pausedThreads;
+    /** The stop of every run in progress */
+    private readonly runs;
     /** The stop of each run, by the signal the run was given */
     private readonly stops;
     /** The stop of each run streaming into a draft with a stop button, by channel, chat and draft */
@@ -53,16 +63,45 @@ export declare class Gateway {
     private readonly lastMessageTime;
     private readonly threads;
     private readonly inFlight;
+    /** Messages taken and not answered yet, for {@link idle} */
+    private readonly pending;
+    /** The stop in progress, which a second {@link stop} call returns */
+    private stopping;
+    /** The last pending write of each user's session, so writes to one session never interleave */
+    private readonly sessionWrites;
     private running;
     private startedAt;
     private messageCount;
     private messageCountDay;
     constructor(config: GatewayFullConfig);
     start(): Promise<void>;
+    /**
+     * 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(): Promise<void>;
+    private drainAndStop;
     get stats(): GatewayStats;
     getSessions(): GatewaySessionInfo[];
+    /**
+     * 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.
+     */
     injectMessage(msg: ChannelMessage): Promise<void>;
+    /**
+     * 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`.
+     */
+    idle(): Promise<void>;
     /**
      * Summarize older messages of a conversation thread, keeping `keepRecent` messages intact.
      * Runs regardless of the configured thresholds.
@@ -77,7 +116,8 @@ export declare class Gateway {
     compactAll(): Promise<string>;
     /**
      * 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`
      */
     private knownThreads;
     /**
@@ -98,10 +138,28 @@ export declare class Gateway {
      * decision, or go away when the request was dropped.
      */
     private closePrompts;
+    /**
+     * 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.
+     */
     private handleIncoming;
+    /** Puts a message through the queue of its thread, resolving once it is done with */
     private dispatch;
+    /** Resolves `true` once the message is handled, `false` when it failed or was dropped */
+    private route;
+    /**
+     * 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.
+     */
+    private locateScheduled;
     private rollMessageCounter;
     private runMiddleware;
+    /**
+     * 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.
+     */
     private processMessage;
     private processWithChannel;
     private handleAccepted;
@@ -128,6 +186,16 @@ export declare class Gateway {
      */
     private streamRun;
     private getThreadId;
+    /**
+     * 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.
+     */
+    private rememberConversation;
+    /**
+     * 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.
+     */
+    private writeSession;
     private resolveAgent;
     private createMiddlewareContext;
     /**

package/dist/gateway.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gateway.d.ts","sourceRoot":"","sources":["../src/gateway.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"gateway.d.ts","sourceRoot":"","sources":["../src/gateway.ts"],"names":[],"mappings":"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"}

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) {
@@ -26,6 +27,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 +62,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 +88,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 +99,12 @@ 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;
+    /** 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 +121,18 @@ 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) => {
+                this.dispatch(merged).catch(() => { });
+            })
             : null;
         for (const channel of this.channels) {
-            channel.onMessage((msg) => this.handleIncoming(msg));
+            channel.onMessage((msg) => this.handleIncoming(msg, false));
             channel.onAction?.((action) => this.handleAction(channel, action));
             channel.onStop?.((stop) => {
                 this.stoppableDrafts
@@ -119,12 +155,38 @@ 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 Promise.all(this.channels.map((ch) => ch.stop()));
         this.startedAt = null;
@@ -144,8 +206,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 +276,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 +367,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 +396,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 +426,83 @@ 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.
+     */
+    async handleIncoming(msg, untilAnswered) {
+        if (this.stopping) {
+            const refused = new Error('The gateway is stopping: the message was dropped');
+            this.config.onError?.(refused, msg);
+            if (untilAnswered)
+                throw refused;
+            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 (untilAnswered || !this.messageQueue) {
+            if (!(await answered) && untilAnswered) {
+                throw new Error('The message was not answered: its run failed or was aborted');
+            }
             return;
         }
-        await this.processMessage(msg);
+        answered.catch(() => { });
+    }
+    /** 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 +523,31 @@ 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);
         try {
             await this.processWithChannel(msg, channel, threadId, runSignal);
+            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 false;
         }
         finally {
+            this.runs.delete(stop);
             const remaining = (this.inFlight.get(threadId) ?? 1) - 1;
             if (remaining <= 0)
                 this.inFlight.delete(threadId);
@@ -404,7 +571,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 +580,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 +653,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 +792,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
@@ -774,7 +949,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;