@foxden-app/foxclaw 0.11.1 → 0.13.0

package/dist/store/task_journal.js

@@ -0,0 +1,70 @@
+const transitions = {
+    accepted: ['queued', 'running', 'awaiting_confirmation', 'failed', 'cancelled'],
+    queued: ['running', 'failed', 'cancelled'],
+    running: ['running', 'awaiting_confirmation', 'delivery_pending', 'failed', 'cancelled'],
+    awaiting_confirmation: ['accepted', 'running', 'cancelled'],
+    delivery_pending: ['delivery_pending', 'completed', 'failed', 'cancelled'],
+    completed: [], failed: [], cancelled: [],
+};
+const unfinished = ['accepted', 'queued', 'running', 'awaiting_confirmation', 'delivery_pending'];
+/** Original inputs, native outcome and delivery progress are distinct durable facts. */
+export class TaskJournal {
+    db;
+    constructor(db) {
+        this.db = db;
+        db.exec(`CREATE TABLE IF NOT EXISTS engine_task_journal (
+      task_id TEXT PRIMARY KEY, scope_id TEXT NOT NULL, backend_id TEXT NOT NULL,
+      state TEXT NOT NULL, queue_id TEXT, record_json TEXT NOT NULL,
+      created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL);
+      CREATE INDEX IF NOT EXISTS engine_task_journal_scope_state ON engine_task_journal(scope_id, state, created_at);
+      CREATE INDEX IF NOT EXISTS engine_task_journal_receipt ON engine_task_journal(scope_id, json_extract(record_json, '$.event.messageId'));`);
+    }
+    atomic(operation) {
+        this.db.exec('SAVEPOINT task_journal_change');
+        try {
+            const result = operation();
+            this.db.exec('RELEASE task_journal_change');
+            return result;
+        }
+        catch (error) {
+            this.db.exec('ROLLBACK TO task_journal_change; RELEASE task_journal_change');
+            throw error;
+        }
+    }
+    insert(task) {
+        this.db.prepare(`INSERT INTO engine_task_journal VALUES (?, ?, ?, ?, ?, ?, ?, ?)`).run(task.id, task.event.scopeId, task.backendId, task.state, task.queueId, JSON.stringify(task), task.createdAt, task.updatedAt);
+    }
+    get(id) {
+        const row = this.db.prepare('SELECT record_json FROM engine_task_journal WHERE task_id = ?').get(id);
+        return row ? JSON.parse(String(row.record_json)) : null;
+    }
+    listUnfinished(scopeId) {
+        const placeholders = unfinished.map(() => '?').join(',');
+        const rows = this.db.prepare(`SELECT record_json FROM engine_task_journal WHERE state IN (${placeholders})${scopeId ? ' AND scope_id = ?' : ''} ORDER BY created_at, task_id`).all(...unfinished, ...(scopeId ? [scopeId] : []));
+        return rows.map(row => JSON.parse(String(row.record_json)));
+    }
+    findReceipt(event, prompt) {
+        if (event.messageId <= 0 || event.userId === 'system')
+            return null;
+        const row = this.db.prepare(`SELECT record_json FROM engine_task_journal WHERE scope_id = ?
+      AND json_extract(record_json, '$.event.messageId') = ? AND json_extract(record_json, '$.event.chatId') = ?
+      AND json_extract(record_json, '$.sourcePrompt') = ? LIMIT 1`).get(event.scopeId, event.messageId, event.chatId, prompt);
+        return row ? JSON.parse(String(row.record_json)) : null;
+    }
+    forQueue(queueId) {
+        const row = this.db.prepare('SELECT record_json FROM engine_task_journal WHERE queue_id = ?').get(queueId);
+        return row ? JSON.parse(String(row.record_json)) : null;
+    }
+    update(id, state, patch = {}) {
+        const previous = this.get(id);
+        if (!previous)
+            throw new Error(`Unknown task: ${id}`);
+        if (previous.state !== state && !transitions[previous.state].includes(state))
+            throw new Error(`Invalid task transition: ${previous.state} -> ${state}`);
+        if (['completed', 'failed', 'cancelled'].includes(previous.state))
+            throw new Error(`Task already resolved: ${id}`);
+        const next = { ...previous, ...patch, state, updatedAt: Date.now() };
+        this.db.prepare(`UPDATE engine_task_journal SET state = ?, queue_id = ?, record_json = ?, updated_at = ? WHERE task_id = ? AND state = ?`).run(state, next.queueId, JSON.stringify(next), next.updatedAt, id, previous.state);
+        return next;
+    }
+}

package/dist/telegram/api.d.ts

@@ -9,8 +9,8 @@ export interface TelegramRemoteFile {
     file_size?: number;
     file_path?: string;
 }
-export declare function isTransientNetworkError(err: unknown): boolean;
-export declare function callTelegramApi<T>(botToken: string, method: string, body: Record<string, unknown>): Promise<TelegramApiResult<T>>;
+export { isTransientNetworkError } from '../core/network_errors.js';
+export declare function callTelegramApi<T>(botToken: string, method: string, body: Record<string, unknown>, signal?: AbortSignal): Promise<TelegramApiResult<T>>;
 export declare function callTelegramMultipartApi<T>(botToken: string, method: string, fields: Record<string, string>, files: Array<{
     fieldName: string;
     filename: string;

package/dist/telegram/api.js

@@ -1,33 +1,13 @@
+import { setTimeout as delay } from 'node:timers/promises';
 import fs from 'node:fs';
 import http from 'node:http';
 import https from 'node:https';
 import path from 'node:path';
 import { pipeline } from 'node:stream/promises';
 const DEFAULT_API_BASE_URL = 'https://api.telegram.org';
-export function isTransientNetworkError(err) {
-    if (!err)
-        return false;
-    const msg = String(err.message || err).toLowerCase();
-    return (msg.includes('client network socket disconnected') ||
-        msg.includes('econnreset') ||
-        msg.includes('etimedout') ||
-        msg.includes('eai_again') ||
-        msg.includes('enotfound') ||
-        msg.includes('econnrefused') ||
-        msg.includes('socket hang up') ||
-        msg.includes('timed out') ||
-        msg.includes('timeout') ||
-        msg.includes('network socket disconnected') ||
-        msg.includes('network error') ||
-        msg.includes('fetch failed') ||
-        msg.includes('und_err_') ||
-        msg.includes('read tcp') ||
-        msg.includes('connection timed out') ||
-        msg.includes('broken pipe') ||
-        msg.includes('ehostunreach') ||
-        msg.includes('enetunreach'));
-}
-function callTelegramApiOnce(botToken, method, body) {
+export { isTransientNetworkError } from '../core/network_errors.js';
+import { isTransientNetworkError } from '../core/network_errors.js';
+function callTelegramApiOnce(botToken, method, body, signal) {
     const payload = JSON.stringify(body);
     const endpoint = telegramApiUrl(botToken, method);
     return new Promise((resolve, reject) => {
@@ -37,7 +17,7 @@ function callTelegramApiOnce(botToken, method, body) {
                 'content-type': 'application/json',
                 'content-length': Buffer.byteLength(payload),
             },
-            signal: AbortSignal.timeout(telegramApiTimeoutMs(false)),
+            signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(telegramApiTimeoutMs(false))]) : AbortSignal.timeout(telegramApiTimeoutMs(false)),
         }, (response) => {
             response.on('error', reject);
             const chunks = [];
@@ -62,17 +42,19 @@ function callTelegramApiOnce(botToken, method, body) {
         request.end();
     });
 }
-export async function callTelegramApi(botToken, method, body) {
+export async function callTelegramApi(botToken, method, body, signal) {
     const maxAttempts = method === 'getUpdates' ? 1 : 4;
     let lastError;
     for (let attempt = 1; attempt <= maxAttempts; attempt++) {
         try {
-            return await callTelegramApiOnce(botToken, method, body);
+            signal?.throwIfAborted();
+            return await callTelegramApiOnce(botToken, method, body, signal);
         }
         catch (err) {
+            signal?.throwIfAborted();
             lastError = err;
             if (attempt < maxAttempts && isTransientNetworkError(err)) {
-                await new Promise((r) => setTimeout(r, Math.min(3000, 500 * Math.pow(2, attempt - 1))));
+                await delay(Math.min(3000, 500 * Math.pow(2, attempt - 1)), undefined, { signal });
                 continue;
             }
             throw err;

package/dist/telegram/gateway.d.ts

@@ -1,28 +1,15 @@
+import type { ChannelInbound } from '../core/channel_events.js';
 import { EventEmitter } from 'node:events';
 import { type TelegramRemoteFile } from './api.js';
 import type { BridgeStore } from '../store/database.js';
 import type { Logger } from '../logger.js';
-import type { TelegramMessageEntity } from './addressing.js';
 import type { TelegramInboundAttachment } from './media.js';
 import type { TelegramInputRichMessage } from './rich.js';
 export type TelegramCommandProvider = (locale: 'en' | 'zh') => Array<{
     command: string;
     description: string;
 }>;
-export interface TelegramTextEvent {
-    chatId: string;
-    topicId: number | null;
-    scopeId: string;
-    chatType: string;
-    userId: string;
-    text: string;
-    messageId: number;
-    mediaGroupId?: string | null;
-    attachments: TelegramInboundAttachment[];
-    entities: TelegramMessageEntity[];
-    replyToBot: boolean;
-    languageCode?: string;
-}
+export type { ChannelTextEvent as TelegramTextEvent } from '../core/channel_events.js';
 export interface TelegramPeerDocumentEvent {
     chatId: string;
     userId: string;
@@ -31,16 +18,7 @@ export interface TelegramPeerDocumentEvent {
     text: string;
     attachment: TelegramInboundAttachment;
 }
-export interface TelegramCallbackEvent {
-    chatId: string;
-    topicId: number | null;
-    scopeId: string;
-    userId: string;
-    data: string;
-    callbackQueryId: string;
-    messageId: number;
-    languageCode?: string;
-}
+export type { ChannelCallbackEvent as TelegramCallbackEvent } from '../core/channel_events.js';
 export declare class TelegramGateway extends EventEmitter {
     private readonly botToken;
     private readonly allowedUserId;
@@ -50,7 +28,15 @@ export declare class TelegramGateway extends EventEmitter {
     private readonly logger;
     private readonly namespacedScopes;
     private readonly commandProvider;
+    private inboundConsumer;
+    private readonly generations;
+    setInboundConsumer(consumer: (id: string, inbound: ChannelInbound) => Promise<void>): () => void;
+    registerGeneration(draftId: number, scopeId: string, taskId: string, chatId: string, topicId: number | null): void;
+    releaseGeneration(draftId: number): void;
+    private dispatchInbound;
     private running;
+    private polling;
+    private pollAbort;
     private botKey;
     private botUsername;
     private botUserId;
@@ -60,7 +46,7 @@ export declare class TelegramGateway extends EventEmitter {
     initializeIdentity(): Promise<string>;
     resolveUsername(): Promise<string | null>;
     start(): Promise<void>;
-    stop(): void;
+    stop(): Promise<void>;
     sendMessage(chatId: string, text: string, inlineKeyboard?: Array<Array<{
         text: string;
         callback_data: string;
@@ -76,7 +62,7 @@ export declare class TelegramGateway extends EventEmitter {
     sendDocument(chatId: string, filename: string, contents: Buffer, caption?: string): Promise<number>;
     sendVoice(chatId: string, filename: string, contents: Buffer, caption?: string, messageThreadId?: number | null, contentType?: string): Promise<number>;
     sendMessageDraft(chatId: string, draftId: number, text: string, messageThreadId?: number | null): Promise<void>;
-    sendRichMessageDraft(chatId: string, draftId: number, richMessage: TelegramInputRichMessage, messageThreadId?: number | null): Promise<void>;
+    sendRichMessageDraft(chatId: string, draftId: number, richMessage: TelegramInputRichMessage, messageThreadId?: number | null, canStop?: boolean): Promise<void>;
     editMessage(chatId: string, messageId: number, text: string, inlineKeyboard?: Array<Array<{
         text: string;
         callback_data: string;

package/dist/telegram/gateway.js

@@ -1,3 +1,4 @@
+import { setTimeout as delay } from 'node:timers/promises';
 import { EventEmitter } from 'node:events';
 import crypto from 'node:crypto';
 import { callTelegramApi, callTelegramMultipartApi, downloadTelegramFile, getTelegramFile } from './api.js';
@@ -13,7 +14,28 @@ export class TelegramGateway extends EventEmitter {
     logger;
     namespacedScopes;
     commandProvider;
+    inboundConsumer = null;
+    generations = new Map();
+    setInboundConsumer(consumer) {
+        if (this.inboundConsumer && this.inboundConsumer !== consumer)
+            throw new Error('Telegram inbound consumer already owned');
+        this.inboundConsumer = consumer;
+        return () => { if (this.inboundConsumer === consumer)
+            this.inboundConsumer = null; };
+    }
+    registerGeneration(draftId, scopeId, taskId, chatId, topicId) {
+        this.generations.set(draftId, { scopeId, taskId, chatId, topicId });
+    }
+    releaseGeneration(draftId) { this.generations.delete(draftId); }
+    async dispatchInbound(updateId, inbound) {
+        if (this.inboundConsumer)
+            await this.inboundConsumer(`${this.botKey}:${updateId}`, inbound);
+        else
+            this.emit(inbound.kind, inbound.event);
+    }
     running = false;
+    polling = null;
+    pollAbort = null;
     botKey;
     botUsername = null;
     botUserId = null;
@@ -57,11 +79,16 @@ export class TelegramGateway extends EventEmitter {
     async start() {
         if (this.running)
             return;
+        await this.polling;
         this.running = true;
-        void this.pollLoop();
+        this.pollAbort = new AbortController();
+        this.polling = this.pollLoop();
     }
-    stop() {
+    async stop() {
         this.running = false;
+        this.pollAbort?.abort();
+        await this.polling;
+        this.generations.clear();
     }
     async sendMessage(chatId, text, inlineKeyboard, messageThreadId) {
         return this.sendMessageWithOptions(chatId, text, inlineKeyboard, undefined, messageThreadId);
@@ -124,11 +151,12 @@ export class TelegramGateway extends EventEmitter {
             throw new Error(result.description || 'Failed to send Telegram draft message');
         }
     }
-    async sendRichMessageDraft(chatId, draftId, richMessage, messageThreadId) {
+    async sendRichMessageDraft(chatId, draftId, richMessage, messageThreadId, canStop = false) {
         const result = await callTelegramApi(this.botToken, 'sendRichMessageDraft', {
             chat_id: chatId,
             draft_id: draftId,
             rich_message: richMessage,
+            ...(canStop ? { can_stop: true, keep_on_stop: true } : {}),
             ...(messageThreadId !== null && messageThreadId !== undefined ? { message_thread_id: messageThreadId } : {}),
         });
         if (!result.ok) {
@@ -223,8 +251,8 @@ export class TelegramGateway extends EventEmitter {
     async downloadResolvedFile(remoteFilePath, destinationPath) {
         return downloadTelegramFile(this.botToken, remoteFilePath, destinationPath);
     }
-    async resolveBotIdentity(required = false) {
-        const result = await callTelegramApi(this.botToken, 'getMe', {});
+    async resolveBotIdentity(required = false, signal) {
+        const result = await callTelegramApi(this.botToken, 'getMe', {}, signal);
         if (result.ok && result.result) {
             this.botKey = `telegram:bot${result.result.id}`;
             this.botUserId = result.result.id;
@@ -235,18 +263,18 @@ export class TelegramGateway extends EventEmitter {
             throw new Error(result.description || 'Failed to resolve Telegram bot identity');
         }
     }
-    async registerCommands() {
+    async registerCommands(signal) {
         await callTelegramApi(this.botToken, 'setMyCommands', {
             commands: this.commandProvider('zh'),
-        });
+        }, signal);
         await callTelegramApi(this.botToken, 'setMyCommands', {
             commands: this.commandProvider('en'),
             language_code: 'en',
-        });
+        }, signal);
         await callTelegramApi(this.botToken, 'setMyCommands', {
             commands: this.commandProvider('zh'),
             language_code: 'zh',
-        });
+        }, signal);
     }
     async setChatCommands(chatId, commands) {
         try {
@@ -261,11 +289,14 @@ export class TelegramGateway extends EventEmitter {
     }
     async pollLoop() {
         let remoteInitialized = false;
+        const signal = this.pollAbort?.signal;
         while (this.running) {
             try {
                 if (!remoteInitialized) {
-                    await this.resolveBotIdentity(true);
-                    await this.registerCommands();
+                    await this.resolveBotIdentity(true, signal);
+                    if (!this.running)
+                        return;
+                    await this.registerCommands(signal);
                     remoteInitialized = true;
                     this.emit('remoteReady');
                     if (!this.running)
@@ -275,25 +306,40 @@ export class TelegramGateway extends EventEmitter {
                 const result = await callTelegramApi(this.botToken, 'getUpdates', {
                     timeout: Math.max(1, Math.floor(this.pollIntervalMs / 1000)),
                     offset,
-                    allowed_updates: ['message', 'callback_query']
-                });
+                    allowed_updates: ['message', 'callback_query', 'stopped_message_generation']
+                }, signal);
+                if (!this.running)
+                    return;
                 if (!result.ok || !result.result) {
                     this.logger.warn('telegram.getUpdates failed', result.description);
-                    await sleep(this.pollIntervalMs);
+                    await delay(this.pollIntervalMs, undefined, { signal }).catch(() => { });
                     continue;
                 }
                 for (const update of result.result) {
-                    this.store.setTelegramOffset(this.botKey, update.update_id);
+                    if (!this.running)
+                        return;
                     await this.handleUpdate(update);
+                    this.store.setTelegramOffset(this.botKey, update.update_id);
                 }
             }
             catch (error) {
+                if (!this.running)
+                    return;
                 this.logger.error('telegram.pollLoop error', toErrorMeta(error));
-                await sleep(this.pollIntervalMs);
+                await delay(this.pollIntervalMs, undefined, { signal }).catch(() => { });
             }
         }
     }
     async handleUpdate(update) {
+        const stopped = update.stopped_message_generation;
+        if (stopped) {
+            const generation = this.generations.get(stopped.draft_id);
+            // Native drafts are private-chat only; the private chat id identifies the authorized user.
+            if (!generation || stopped.chat.type !== 'private' || String(stopped.chat.id) !== this.allowedUserId || generation.chatId !== String(stopped.chat.id) || generation.topicId !== (stopped.message_thread_id ?? null))
+                return;
+            await this.dispatchInbound(update.update_id, { kind: 'stop', event: { scopeId: generation.scopeId, taskId: generation.taskId } });
+            return;
+        }
         if (update.message && update.message.from && this.isAllowedChat(update.message.chat)) {
             if (String(update.message.from.id) !== this.allowedUserId) {
                 if (update.message.chat.type === 'private') {
@@ -320,20 +366,20 @@ export class TelegramGateway extends EventEmitter {
             const entities = update.message.text ? (update.message.entities ?? []) : (update.message.caption_entities ?? []);
             const replyToBot = this.botUserId !== null && update.message.reply_to_message?.from?.id === this.botUserId;
             if (text || attachments.length > 0) {
-                this.emit('text', {
-                    chatId: String(update.message.chat.id),
-                    topicId,
-                    scopeId,
-                    chatType: update.message.chat.type,
-                    userId: String(update.message.from.id),
-                    text,
-                    messageId: update.message.message_id,
-                    mediaGroupId: update.message.media_group_id ?? null,
-                    attachments,
-                    entities,
-                    replyToBot,
-                    ...(update.message.from.language_code ? { languageCode: update.message.from.language_code } : {}),
-                });
+                await this.dispatchInbound(update.update_id, { kind: 'text', event: {
+                        chatId: String(update.message.chat.id),
+                        topicId,
+                        scopeId,
+                        chatType: update.message.chat.type,
+                        userId: String(update.message.from.id),
+                        text,
+                        messageId: update.message.message_id,
+                        mediaGroupId: update.message.media_group_id ?? null,
+                        attachments,
+                        entities,
+                        replyToBot,
+                        ...(update.message.from.language_code ? { languageCode: update.message.from.language_code } : {}),
+                    } });
                 if (update.message.chat.type === 'private' && this.identity) {
                     this.store.rememberTelegramPrivateScope(this.identity, scopeId, String(update.message.chat.id));
                 }
@@ -346,16 +392,16 @@ export class TelegramGateway extends EventEmitter {
             if (!this.isAllowedChat(update.callback_query.message.chat))
                 return;
             const topicId = update.callback_query.message.message_thread_id ?? null;
-            this.emit('callback', {
-                chatId: String(update.callback_query.message.chat.id),
-                topicId,
-                scopeId: toTelegramBridgeScopeId(createTelegramScopeId(String(update.callback_query.message.chat.id), topicId), this.namespacedScopes ? this.identity : null),
-                userId: String(update.callback_query.from.id),
-                data: update.callback_query.data,
-                callbackQueryId: update.callback_query.id,
-                messageId: update.callback_query.message.message_id,
-                ...(update.callback_query.from.language_code ? { languageCode: update.callback_query.from.language_code } : {}),
-            });
+            await this.dispatchInbound(update.update_id, { kind: 'callback', event: {
+                    chatId: String(update.callback_query.message.chat.id),
+                    topicId,
+                    scopeId: toTelegramBridgeScopeId(createTelegramScopeId(String(update.callback_query.message.chat.id), topicId), this.namespacedScopes ? this.identity : null),
+                    userId: String(update.callback_query.from.id),
+                    data: update.callback_query.data,
+                    callbackQueryId: update.callback_query.id,
+                    messageId: update.callback_query.message.message_id,
+                    ...(update.callback_query.from.language_code ? { languageCode: update.callback_query.from.language_code } : {}),
+                } });
         }
     }
     isAllowedChat(chat) {
@@ -368,9 +414,6 @@ export class TelegramGateway extends EventEmitter {
         return false;
     }
 }
-function sleep(ms) {
-    return new Promise(resolve => setTimeout(resolve, ms));
-}
 export function parseTelegramBotId(botToken) {
     const match = /^(\d+):/.exec(botToken.trim());
     if (!match)

package/dist/telegram/media.d.ts

@@ -1,34 +1,2 @@
-export declare const TELEGRAM_INBOX_DIR = ".telegram-inbox";
-export declare const TELEGRAM_BOT_API_DOWNLOAD_LIMIT_BYTES: number;
-export type TelegramAttachmentKind = 'photo' | 'document' | 'audio' | 'voice' | 'video' | 'animation' | 'sticker' | 'videoNote';
-export interface TelegramInboundAttachment {
-    kind: TelegramAttachmentKind;
-    fileId: string;
-    fileUniqueId: string;
-    fileName: string | null;
-    mimeType: string | null;
-    fileSize: number | null;
-    width: number | null;
-    height: number | null;
-    durationSeconds: number | null;
-    isAnimated: boolean;
-    isVideo: boolean;
-    /** When set, {@link stageAttachments} copies this file instead of Telegram Bot API download. */
-    localPath?: string;
-}
-export interface StagedTelegramAttachment extends TelegramInboundAttachment {
-    fileName: string;
-    localPath: string;
-    relativePath: string;
-    nativeImage: boolean;
-}
-interface PlannedAttachmentPath {
-    fileName: string;
-    localPath: string;
-    relativePath: string;
-}
-export declare function isNativeImageAttachment(attachment: TelegramInboundAttachment): boolean;
-export declare function planAttachmentStoragePath(cwd: string, threadId: string, attachment: TelegramInboundAttachment, remoteFilePath?: string | null, now?: Date): PlannedAttachmentPath;
-export declare function buildAttachmentPrompt(userText: string, attachments: readonly StagedTelegramAttachment[]): string;
-export declare function summarizeTelegramInput(text: string, attachments: readonly TelegramInboundAttachment[]): string;
-export {};
+export type { AttachmentKind as TelegramAttachmentKind, InboundAttachment as TelegramInboundAttachment, StagedAttachment as StagedTelegramAttachment } from '../core/attachment_types.js';
+export { ATTACHMENT_INBOX_DIR as TELEGRAM_INBOX_DIR, DEFAULT_REMOTE_DOWNLOAD_LIMIT_BYTES as TELEGRAM_BOT_API_DOWNLOAD_LIMIT_BYTES, isNativeImageAttachment, planAttachmentStoragePath, buildAttachmentPrompt, summarizeInput as summarizeTelegramInput } from '../core/attachment_files.js';