clearclaw 0.6.1 → 0.8.0

package/dist/channel/telegram.js

@@ -1,5 +1,5 @@
 import { EventEmitter } from "node:events";
-import { Bot, InlineKeyboard, InputFile } from "grammy";
+import { Bot, GrammyError, InlineKeyboard, InputFile } from "grammy";
 import mime from "mime";
 import telegramifyMarkdown from "telegramify-markdown";
 import log from "../logger.js";
@@ -15,6 +15,9 @@ export class TelegramChannel extends EventEmitter {
     pendingCallbacks = new Map();
     // Pending text input: chatId → resolve function (for requestText follow-ups)
     pendingTextResolvers = new Map();
+    // Our bot's @username, captured at connect. Used to strip the `@bot` suffix
+    // Telegram appends to commands in group chats.
+    botUsername;
     constructor(botToken, isAuthorized, onUnauthorizedDM) {
         super();
         this.botToken = botToken;
@@ -22,6 +25,31 @@ export class TelegramChannel extends EventEmitter {
         this.onUnauthorizedDM = onUnauthorizedDM;
         this.bot = new Bot(botToken);
     }
+    /**
+     * Strip the `@<botUsername>` suffix Telegram appends to commands in group
+     * chats (`/context@mybot args` → `/context args`), so downstream command
+     * handling — ClearClaw's own `/new` etc. and slash-command pass-through —
+     * sees the bare `/command`. No-op for non-command text and in DMs (no suffix).
+     * Telegram usernames are `[A-Za-z0-9_]`, so they need no regex escaping.
+     */
+    stripCommandMention(text) {
+        if (!this.botUsername || !text.startsWith("/"))
+            return text;
+        return text.replace(new RegExp(`^(/[^\\s@]+)@${this.botUsername}(?=\\s|$)`, "i"), "$1");
+    }
+    async telegramCall(call, label) {
+        try {
+            return await call();
+        }
+        catch (err) {
+            const retryAfter = telegramRetryAfterSeconds(err);
+            if (retryAfter === null)
+                throw err;
+            log.warn("[channel] Telegram rate limited during %s, retrying after %ss", label, retryAfter);
+            await sleep((retryAfter + 1) * 1000);
+            return await call();
+        }
+    }
     async connect() {
         this.bot.on("message:text", (ctx) => {
             const sender = this.extractSender(ctx);
@@ -36,7 +64,7 @@ export class TelegramChannel extends EventEmitter {
             }
             this.emit("message", {
                 ...sender,
-                text: ctx.message.text,
+                text: this.stripCommandMention(ctx.message.text),
                 messageId: String(ctx.message.message_id),
                 replyTo: this.extractReplyContext(ctx.message),
             });
@@ -89,6 +117,7 @@ export class TelegramChannel extends EventEmitter {
         await new Promise((resolve) => {
             this.bot.start({
                 onStart: (botInfo) => {
+                    this.botUsername = botInfo.username;
                     log.info(`[channel] Telegram bot: @${botInfo.username}`);
                     resolve();
                 },
@@ -106,27 +135,39 @@ export class TelegramChannel extends EventEmitter {
     ownsId(chatId) {
         return chatId.startsWith("tg:");
     }
+    /** A private chat is the user's own id; a ":thread" suffix means a topic inside it. */
+    isRootDM(chatId, userId) {
+        return /^tg:[1-9]\d*$/.test(chatId) && chatId === userId;
+    }
     async sendMessage(chatId, text, opts) {
         const numId = this.numericId(chatId);
         const chunks = splitMessage(text);
         const handles = [];
+        const plain = opts?.format === "plain";
         let firstChunk = true;
         for (const chunk of chunks) {
             const replyParams = firstChunk && opts?.replyToMessageId
                 ? { reply_parameters: { message_id: Number(opts.replyToMessageId) } }
                 : {};
-            const rendered = telegramifyMarkdown(chunk, "escape");
-            try {
-                const sent = await this.bot.api.sendMessage(numId, rendered, {
-                    parse_mode: "MarkdownV2",
-                    ...replyParams,
-                });
+            if (plain) {
+                const sent = await this.telegramCall(() => this.bot.api.sendMessage(numId, chunk, { ...this.threadOpts(chatId), ...replyParams }), "sendMessage");
                 handles.push(String(sent.message_id));
             }
-            catch (err) {
-                log.warn("[channel] sendMessage failed with MarkdownV2, retrying as plain text");
-                const sent = await this.bot.api.sendMessage(numId, chunk, replyParams);
-                handles.push(String(sent.message_id));
+            else {
+                const rendered = telegramifyMarkdown(chunk, "escape");
+                try {
+                    const sent = await this.telegramCall(() => this.bot.api.sendMessage(numId, rendered, {
+                        ...this.threadOpts(chatId),
+                        parse_mode: "MarkdownV2",
+                        ...replyParams,
+                    }), "sendMessage");
+                    handles.push(String(sent.message_id));
+                }
+                catch (err) {
+                    log.warn("[channel] sendMessage failed with MarkdownV2, retrying as plain text");
+                    const sent = await this.telegramCall(() => this.bot.api.sendMessage(numId, chunk, { ...this.threadOpts(chatId), ...replyParams }), "sendMessage");
+                    handles.push(String(sent.message_id));
+                }
             }
             firstChunk = false;
         }
@@ -157,16 +198,18 @@ export class TelegramChannel extends EventEmitter {
         const mdv2Text = telegramifyMarkdown(text, "escape");
         let sent;
         try {
-            sent = await this.bot.api.sendMessage(numId, mdv2Text, {
+            sent = await this.telegramCall(() => this.bot.api.sendMessage(numId, mdv2Text, {
+                ...this.threadOpts(chatId),
                 reply_markup: keyboard,
                 parse_mode: "MarkdownV2",
-            });
+            }), "sendInteractive");
         }
         catch {
             log.warn("[channel] sendInteractive failed with MarkdownV2, retrying as plain text");
-            sent = await this.bot.api.sendMessage(numId, text, {
+            sent = await this.telegramCall(() => this.bot.api.sendMessage(numId, text, {
+                ...this.threadOpts(chatId),
                 reply_markup: keyboard,
-            });
+            }), "sendInteractive");
         }
         const cleanupAll = () => {
             for (const { cbData } of cbEntries) {
@@ -194,17 +237,18 @@ export class TelegramChannel extends EventEmitter {
             feedbackKeyboard.row();
         }
         try {
-            await this.bot.api.editMessageReplyMarkup(numId, sent.message_id, {
+            await this.telegramCall(() => this.bot.api.editMessageReplyMarkup(numId, sent.message_id, {
                 reply_markup: feedbackKeyboard,
-            });
+            }), "editMessageReplyMarkup");
         }
         catch { /* best-effort */ }
         // If the button requests text, prompt for follow-up input
         if (pressed.requestText) {
-            await this.bot.api.sendMessage(numId, "Add your feedback:", {
+            await this.telegramCall(() => this.bot.api.sendMessage(numId, "Add your feedback:", {
+                ...this.threadOpts(chatId),
                 reply_markup: { force_reply: true },
                 reply_parameters: { message_id: sent.message_id },
-            });
+            }), "sendInteractiveFollowUp");
             const followUpText = await new Promise((resolve) => {
                 this.pendingTextResolvers.set(chatId, resolve);
             });
@@ -212,9 +256,20 @@ export class TelegramChannel extends EventEmitter {
         }
         return { value: pressed.value };
     }
-    async editMessage(chatId, handle, text) {
+    async editMessage(chatId, handle, text, opts) {
         const numId = this.numericId(chatId);
-        await this.bot.api.editMessageText(numId, Number(handle), text);
+        if (opts?.format === "plain") {
+            await this.telegramCall(() => this.bot.api.editMessageText(numId, Number(handle), text), "editMessage");
+        }
+        else {
+            const rendered = telegramifyMarkdown(text, "escape");
+            try {
+                await this.telegramCall(() => this.bot.api.editMessageText(numId, Number(handle), rendered, { parse_mode: "MarkdownV2" }), "editMessage");
+            }
+            catch {
+                await this.telegramCall(() => this.bot.api.editMessageText(numId, Number(handle), text), "editMessage");
+            }
+        }
     }
     async deleteMessage(chatId, handle) {
         const numId = this.numericId(chatId);
@@ -222,13 +277,18 @@ export class TelegramChannel extends EventEmitter {
     }
     async pinMessage(chatId, handle) {
         const numId = this.numericId(chatId);
-        await this.bot.api.pinChatMessage(numId, Number(handle), {
+        await this.telegramCall(() => this.bot.api.pinChatMessage(numId, Number(handle), {
             disable_notification: true,
-        });
+        }), "pinMessage");
     }
+    /** Unpin everything in this chat's scope: the forum topic for a topic chat, else the whole chat. */
     async unpinAllMessages(chatId) {
         const numId = this.numericId(chatId);
-        await this.bot.api.unpinAllChatMessages(numId);
+        const { message_thread_id } = this.threadOpts(chatId);
+        if (message_thread_id)
+            await this.bot.api.unpinAllForumTopicMessages(numId, message_thread_id);
+        else
+            await this.bot.api.unpinAllChatMessages(numId);
     }
     async updateStatus(chatId, text) {
         const existing = this.statusHandles.get(chatId);
@@ -248,7 +308,9 @@ export class TelegramChannel extends EventEmitter {
                 }
             }
         }
-        // No existing handle, or edit failed — create new pinned message
+        // No existing handle, or edit failed — (re)create the pinned status. The handle lives only in
+        // memory, so after a restart the previous status is unknown; clear every pin in scope instead
+        // (topic-scoped for forum topics, so peers in other topics keep theirs).
         try {
             await this.unpinAllMessages(chatId);
         }
@@ -270,10 +332,10 @@ export class TelegramChannel extends EventEmitter {
             const numId = this.numericId(chatId);
             // Send immediately, then repeat every 4s
             await this.bot.api
-                .sendChatAction(numId, "typing")
+                .sendChatAction(numId, "typing", this.threadOpts(chatId))
                 .catch(() => { });
             const interval = setInterval(() => {
-                this.bot.api.sendChatAction(numId, "typing").catch(() => { });
+                this.bot.api.sendChatAction(numId, "typing", this.threadOpts(chatId)).catch(() => { });
             }, 4000);
             this.typingIntervals.set(chatId, interval);
         }
@@ -305,10 +367,13 @@ export class TelegramChannel extends EventEmitter {
             }
             return null;
         }
+        const topicSuffix = ctx.message?.is_topic_message && ctx.message.message_thread_id
+            ? `:${ctx.message.message_thread_id}`
+            : "";
         return {
-            chatId: `tg:${ctx.chat.id}`,
+            chatId: `tg:${ctx.chat.id}${topicSuffix}`,
             chatType: ctx.chat.type === "private" ? "dm" : "group",
-            user,
+            origin: { kind: "user", user },
         };
     }
     /** Extract reply context from a Telegram message, if it's a reply. */
@@ -369,16 +434,16 @@ export class TelegramChannel extends EventEmitter {
         const file = new InputFile(buffer, filename);
         const caption = opts?.caption;
         if (mimeType.startsWith("image/")) {
-            await this.bot.api.sendPhoto(id, file, { caption });
+            await this.bot.api.sendPhoto(id, file, { caption, ...this.threadOpts(chatId) });
         }
         else if (mimeType.startsWith("video/")) {
-            await this.bot.api.sendVideo(id, file, { caption });
+            await this.bot.api.sendVideo(id, file, { caption, ...this.threadOpts(chatId) });
         }
         else if (mimeType.startsWith("audio/")) {
-            await this.bot.api.sendAudio(id, file, { caption });
+            await this.bot.api.sendAudio(id, file, { caption, ...this.threadOpts(chatId) });
         }
         else {
-            await this.bot.api.sendDocument(id, file, { caption });
+            await this.bot.api.sendDocument(id, file, { caption, ...this.threadOpts(chatId) });
         }
     }
     async reactToMessage(chatId, messageId, emoji) {
@@ -393,6 +458,45 @@ export class TelegramChannel extends EventEmitter {
             log.warn("[channel] failed to set reaction on %s: %s", messageId, err instanceof Error ? err.message : String(err));
         }
     }
+    async createProjectChat(projectName, anchor, title) {
+        await this.validateProjectChat(projectName, anchor);
+        const topic = await this.bot.api.createForumTopic(this.numericId(anchor), title);
+        return `tg:${this.numericId(anchor)}:${topic.message_thread_id}`;
+    }
+    async closeProjectChat(chatId) {
+        const thread = chatId.split(":")[2];
+        if (!thread)
+            throw new Error("Telegram cannot close a whole chat; only topics can be archived");
+        const parentId = this.numericId(chatId);
+        if (parentId > 0) {
+            await this.bot.api.deleteForumTopic(parentId, Number(thread));
+            return;
+        }
+        try {
+            await this.bot.api.closeForumTopic(parentId, Number(thread));
+        }
+        catch (err) {
+            if (err instanceof GrammyError && err.description === "Bad Request: TOPIC_NOT_MODIFIED")
+                return;
+            throw err;
+        }
+    }
+    async validateProjectChat(projectName, anchor) {
+        const parentId = this.numericId(anchor);
+        if (!Number.isFinite(parentId)) {
+            throw new Error(`Telegram project "${projectName}" must use a valid chat ID`);
+        }
+        const chat = await this.bot.api.getChat(parentId);
+        if (chat.type === "private") {
+            const botInfo = await this.bot.api.getMe();
+            if (botInfo.has_topics_enabled)
+                return;
+            throw new Error(`Telegram project "${projectName}" requires Threaded Mode for this bot. Enable it in BotFather, then retry.`);
+        }
+        if (chat.type === "supergroup" && chat.is_forum)
+            return;
+        throw new Error(`Telegram project "${projectName}" requires a forum supergroup. Enable Topics manually in Telegram, then retry.`);
+    }
     /** Download a Telegram file by file_id, returning the raw buffer. */
     async downloadFile(fileId) {
         const file = await this.bot.api.getFile(fileId);
@@ -404,8 +508,14 @@ export class TelegramChannel extends EventEmitter {
             throw new Error(`File download failed: ${resp.status}`);
         return Buffer.from(await resp.arrayBuffer());
     }
+    /** "tg:123" → 123; "tg:123:45" (forum topic) → 123 */
     numericId(chatId) {
-        return Number(chatId.replace(/^tg:/, ""));
+        return Number(chatId.split(":")[1]);
+    }
+    /** Topic part of a composite chat id, as spreadable send options. */
+    threadOpts(chatId) {
+        const thread = chatId.split(":")[2];
+        return thread ? { message_thread_id: Number(thread) } : {};
     }
 }
 const MAX_MSG_LEN = 4096;
@@ -432,4 +542,18 @@ function splitMessage(text) {
         chunks.push(remaining);
     return chunks;
 }
+function telegramRetryAfterSeconds(err) {
+    const candidate = err;
+    const retryAfter = candidate?.parameters?.retry_after;
+    if (typeof retryAfter === "number" && Number.isFinite(retryAfter))
+        return retryAfter;
+    const message = err instanceof Error ? err.message : String(err);
+    const match = message.match(/retry after (\d+)/i);
+    if (!match)
+        return null;
+    return Number(match[1]);
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
 //# sourceMappingURL=telegram.js.map

package/dist/config.d.ts

@@ -21,6 +21,25 @@ export interface PendingPairing {
     chatId: string;
     expiresAt: number;
 }
+export interface EngineEntry {
+    name: string;
+    default?: boolean;
+    path?: string;
+    configPath?: string;
+}
+export interface ScheduleEntry {
+    id: string;
+    cron: string;
+    prompt: string;
+    enabled: boolean;
+    timezone?: string;
+    createdAt: number;
+}
+export interface Project {
+    name: string;
+    description: string;
+    main_workspace: string;
+}
 export declare function resolveDataDir(): string;
 /**
  * Unified config: env var resolution + persistent store backed by config.json.
@@ -33,36 +52,61 @@ export declare function resolveDataDir(): string;
  */
 export declare class Config {
     channel?: ChannelConfig;
+    engines: Record<string, EngineEntry>;
+    defaultEngine: string;
     permissionMode: PermissionMode;
     private envUserIds;
-    readonly defaultPromptPath: string;
+    readonly homeWorkspacePath: string;
     readonly filesPath: string;
     readonly logPath: string;
+    readonly instructionsDir: string;
+    readonly frameworkPromptDir: string;
     private readonly dataDir;
     private readonly filePath;
     constructor();
     /** Resolve channel + env vars. Throws if no channel config found. */
     resolve(): this;
+    private readRaw;
     private read;
     private write;
     getChannel(): ChannelConfig | undefined;
     setChannel(config: ChannelConfig): void;
+    setEngines(engines: EngineEntry[]): void;
     hasUser(userId: string): boolean;
     addUser(user: AuthorizedUser): void;
     listUsers(): AuthorizedUser[];
+    /** All authorized IDs, including environment-configured and pairing-approved users. */
+    listAuthorizedUserIds(): string[];
     /** env var IDs (in-memory) + pairing-approved users (hot-reload from disk) */
     isAuthorized(userId: string): boolean;
     createPairing(userId: string, userName: string, chatId: string): string;
     consumePairing(code: string): PendingPairing | null;
     private generateCode;
+    /** Home exists before a chat is paired. Never replace an existing home's settings. */
+    ensureHomeWorkspace(): Workspace;
+    /**
+     * ensureHomeWorkspace creates home's records at startup, before any chat is known.
+     * This gives it its destination, once: an existing binding is never replaced.
+     * Callers decide what counts as home's chat — see Channel.isRootDM.
+     */
+    connectHomeWorkspace(chatId: string): boolean;
     workspaceByChat(chatId: string): Workspace | undefined;
     workspaceByName(name: string): Workspace | undefined;
+    listWorkspaces(): Workspace[];
     upsertWorkspace(ws: Workspace): void;
+    removeWorkspace(name: string): Workspace | undefined;
+    /** Persist the session ID without changing the saved model setting. */
     setSession(name: string, sessionId: string): void;
     clearSession(name: string): void;
+    setModel(name: string, model: string | undefined): void;
     setBehavior(name: string, behavior: "assistant" | "relay"): void;
-    ensureDefaultWorkspace(chatId: string): void;
-    /** Copy bundled skills from the repo's skills/ directory to the home workspace's .claude/skills/. */
-    syncSkills(): void;
-    approveUser(userId: string, userName: string, chatId: string): void;
+    addProject(project: Project): void;
+    listProjects(): Project[];
+    projectByName(name: string): Project | undefined;
+    removeProject(name: string): void;
+    listSchedules(): ScheduleEntry[];
+    addSchedule(entry: ScheduleEntry): void;
+    removeSchedule(id: string): void;
+    updateSchedule(id: string, update: Partial<Pick<ScheduleEntry, "enabled" | "cron" | "prompt" | "timezone">>): void;
+    approveUser(userId: string, userName: string): void;
 }