@asermax/tachikoma 2.0.0

package/dist/extensions/telegram/sending.js

@@ -0,0 +1,119 @@
+import { splitMessage } from "./chunking.js";
+// Telegram keeps a chat action visible for ~5 seconds, so refresh just before it expires.
+const TYPING_REFRESH_MS = 5000;
+const DELETE_RETRY_ATTEMPTS = 3;
+const errorDetail = (error) => {
+    if (typeof error !== "object" || error == null)
+        return "";
+    const description = error.description;
+    return typeof description === "string"
+        ? description
+        : error instanceof Error
+            ? error.message
+            : "";
+};
+export const isMarkdownParseError = (error) => /can't parse entities/i.test(errorDetail(error));
+/** Telegram rejects edits whose content matches the current message — benign. */
+export const isMessageNotModifiedError = (error) => /message is not modified/i.test(errorDetail(error));
+/** Try Markdown first; on a Telegram entity-parse rejection resend as plain text. */
+export const sendWithMarkdownFallback = async (api, chatId, text, options = {}) => {
+    const base = options.silent === true ? { disable_notification: true } : {};
+    try {
+        const sent = await api.sendMessage(chatId, text, { ...base, parse_mode: "Markdown" });
+        return sent.message_id;
+    }
+    catch (error) {
+        if (!isMarkdownParseError(error))
+            throw error;
+        const sent = await api.sendMessage(chatId, text, base);
+        return sent.message_id;
+    }
+};
+/**
+ * Edit a message trying Markdown first, falling back to plain text on a parse
+ * rejection. "Message is not modified" rejections are swallowed — the visible
+ * content already matches.
+ */
+export const editWithMarkdownFallback = async (api, chatId, messageId, text) => {
+    try {
+        await api.editMessageText(chatId, messageId, text, { parse_mode: "Markdown" });
+    }
+    catch (error) {
+        if (isMessageNotModifiedError(error))
+            return;
+        if (!isMarkdownParseError(error))
+            throw error;
+        try {
+            await api.editMessageText(chatId, messageId, text);
+        }
+        catch (fallbackError) {
+            if (!isMessageNotModifiedError(fallbackError))
+                throw fallbackError;
+        }
+    }
+};
+/** Send text as one or more messages, split at Telegram's length limit. */
+export const sendChunked = async (api, chatId, text, options = {}) => {
+    if (text.trim().length === 0)
+        return [];
+    const ids = [];
+    for (const chunk of splitMessage(text)) {
+        ids.push(await sendWithMarkdownFallback(api, chatId, chunk, options));
+    }
+    return ids;
+};
+/**
+ * Copy+delete a silently-sent message so the copy fires a push notification.
+ * Copy-first ordering keeps the
+ * text safe: on copy failure the original is preserved and no delete runs; on
+ * delete failure the duplicate is accepted after retries.
+ */
+export const notifyViaCopyDelete = async (api, chatId, messageId, log, retryDelayMs = 500) => {
+    let copied;
+    try {
+        copied = await api.copyMessage(chatId, chatId, messageId);
+    }
+    catch (error) {
+        log.warn({ err: error, messageId }, "copy for push notification failed — keeping original");
+        return null;
+    }
+    for (let attempt = 0; attempt < DELETE_RETRY_ATTEMPTS; attempt += 1) {
+        try {
+            await api.deleteMessage(chatId, messageId);
+            return copied.message_id;
+        }
+        catch (error) {
+            if (attempt < DELETE_RETRY_ATTEMPTS - 1) {
+                await sleep(retryDelayMs);
+            }
+            else {
+                log.warn({ err: error, messageId }, "delete after copy failed — duplicate left visible");
+            }
+        }
+    }
+    return copied.message_id;
+};
+/** Full background-delivery flow: silent chunked send, then copy+delete to fire the push. */
+export const deliverText = async (api, chatId, text, pushNotifications, log, retryDelayMs = 500) => {
+    const ids = await sendChunked(api, chatId, text, { silent: pushNotifications });
+    const lastId = ids.at(-1);
+    if (lastId == null)
+        return null;
+    if (!pushNotifications)
+        return lastId;
+    return (await notifyViaCopyDelete(api, chatId, lastId, log, retryDelayMs)) ?? lastId;
+};
+/** Show a typing indicator until the returned stop function is called. */
+export const startTyping = (api, chatId, log) => {
+    const send = () => {
+        api
+            .sendChatAction(chatId, "typing")
+            .catch((error) => log.debug({ err: error }, "typing chat action failed"));
+    };
+    send();
+    const timer = setInterval(send, TYPING_REFRESH_MS);
+    timer.unref();
+    return () => clearInterval(timer);
+};
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+//# sourceMappingURL=sending.js.map

package/dist/extensions/telegram/sending.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sending.js","sourceRoot":"","sources":["../../../src/extensions/telegram/sending.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAE7C,0FAA0F;AAC1F,MAAM,iBAAiB,GAAG,IAAI,CAAC;AAE/B,MAAM,qBAAqB,GAAG,CAAC,CAAC;AAiChC,MAAM,WAAW,GAAG,CAAC,KAAc,EAAU,EAAE;IAC7C,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,IAAI,IAAI;QAAE,OAAO,EAAE,CAAC;IAE1D,MAAM,WAAW,GAAI,KAAmC,CAAC,WAAW,CAAC;IAErE,OAAO,OAAO,WAAW,KAAK,QAAQ;QACpC,CAAC,CAAC,WAAW;QACb,CAAC,CAAC,KAAK,YAAY,KAAK;YACtB,CAAC,CAAC,KAAK,CAAC,OAAO;YACf,CAAC,CAAC,EAAE,CAAC;AACX,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,KAAc,EAAW,EAAE,CAC9D,uBAAuB,CAAC,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC;AAEnD,iFAAiF;AACjF,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,KAAc,EAAW,EAAE,CACnE,0BAA0B,CAAC,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC;AAEtD,qFAAqF;AACrF,MAAM,CAAC,MAAM,wBAAwB,GAAG,KAAK,EAC3C,GAAiC,EACjC,MAAc,EACd,IAAY,EACZ,UAAgC,EAAE,EACjB,EAAE;IACnB,MAAM,IAAI,GAAuB,OAAO,CAAC,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,oBAAoB,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAE/F,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,WAAW,CAAC,MAAM,EAAE,IAAI,EAAE,EAAE,GAAG,IAAI,EAAE,UAAU,EAAE,UAAU,EAAE,CAAC,CAAC;QACtF,OAAO,IAAI,CAAC,UAAU,CAAC;IACzB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,CAAC,oBAAoB,CAAC,KAAK,CAAC;YAAE,MAAM,KAAK,CAAC;QAE9C,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,WAAW,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;QACvD,OAAO,IAAI,CAAC,UAAU,CAAC;IACzB,CAAC;AACH,CAAC,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,KAAK,EAC3C,GAAqC,EACrC,MAAc,EACd,SAAiB,EACjB,IAAY,EACG,EAAE;IACjB,IAAI,CAAC;QACH,MAAM,GAAG,CAAC,eAAe,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,EAAE,UAAU,EAAE,UAAU,EAAE,CAAC,CAAC;IACjF,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,yBAAyB,CAAC,KAAK,CAAC;YAAE,OAAO;QAC7C,IAAI,CAAC,oBAAoB,CAAC,KAAK,CAAC;YAAE,MAAM,KAAK,CAAC;QAE9C,IAAI,CAAC;YACH,MAAM,GAAG,CAAC,eAAe,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,CAAC,CAAC;QACrD,CAAC;QAAC,OAAO,aAAa,EAAE,CAAC;YACvB,IAAI,CAAC,yBAAyB,CAAC,aAAa,CAAC;gBAAE,MAAM,aAAa,CAAC;QACrE,CAAC;IACH,CAAC;AACH,CAAC,CAAC;AAEF,2EAA2E;AAC3E,MAAM,CAAC,MAAM,WAAW,GAAG,KAAK,EAC9B,GAAiC,EACjC,MAAc,EACd,IAAY,EACZ,UAAgC,EAAE,EACf,EAAE;IACrB,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAExC,MAAM,GAAG,GAAa,EAAE,CAAC;IAEzB,KAAK,MAAM,KAAK,IAAI,YAAY,CAAC,IAAI,CAAC,EAAE,CAAC;QACvC,GAAG,CAAC,IAAI,CAAC,MAAM,wBAAwB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC;IACxE,CAAC;IAED,OAAO,GAAG,CAAC;AACb,CAAC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,KAAK,EACtC,GAAmD,EACnD,MAAc,EACd,SAAiB,EACjB,GAAW,EACX,YAAY,GAAG,GAAG,EACM,EAAE;IAC1B,IAAI,MAA8B,CAAC;IAEnC,IAAI,CAAC;QACH,MAAM,GAAG,MAAM,GAAG,CAAC,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC;IAC5D,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,GAAG,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,SAAS,EAAE,EAAE,sDAAsD,CAAC,CAAC;QAC5F,OAAO,IAAI,CAAC;IACd,CAAC;IAED,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,GAAG,qBAAqB,EAAE,OAAO,IAAI,CAAC,EAAE,CAAC;QACpE,IAAI,CAAC;YACH,MAAM,GAAG,CAAC,aAAa,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;YAC3C,OAAO,MAAM,CAAC,UAAU,CAAC;QAC3B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,OAAO,GAAG,qBAAqB,GAAG,CAAC,EAAE,CAAC;gBACxC,MAAM,KAAK,CAAC,YAAY,CAAC,CAAC;YAC5B,CAAC;iBAAM,CAAC;gBACN,GAAG,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,SAAS,EAAE,EAAE,mDAAmD,CAAC,CAAC;YAC3F,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC,UAAU,CAAC;AAC3B,CAAC,CAAC;AAEF,6FAA6F;AAC7F,MAAM,CAAC,MAAM,WAAW,GAAG,KAAK,EAC9B,GAAY,EACZ,MAAc,EACd,IAAY,EACZ,iBAA0B,EAC1B,GAAW,EACX,YAAY,GAAG,GAAG,EACM,EAAE;IAC1B,MAAM,GAAG,GAAG,MAAM,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,MAAM,EAAE,iBAAiB,EAAE,CAAC,CAAC;IAChF,MAAM,MAAM,GAAG,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IAE1B,IAAI,MAAM,IAAI,IAAI;QAAE,OAAO,IAAI,CAAC;IAChC,IAAI,CAAC,iBAAiB;QAAE,OAAO,MAAM,CAAC;IAEtC,OAAO,CAAC,MAAM,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,YAAY,CAAC,CAAC,IAAI,MAAM,CAAC;AACvF,CAAC,CAAC;AAEF,0EAA0E;AAC1E,MAAM,CAAC,MAAM,WAAW,GAAG,CACzB,GAAoC,EACpC,MAAc,EACd,GAAW,EACG,EAAE;IAChB,MAAM,IAAI,GAAG,GAAG,EAAE;QAChB,GAAG;aACA,cAAc,CAAC,MAAM,EAAE,QAAQ,CAAC;aAChC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,EAAE,2BAA2B,CAAC,CAAC,CAAC;IAC9E,CAAC,CAAC;IAEF,IAAI,EAAE,CAAC;IACP,MAAM,KAAK,GAAG,WAAW,CAAC,IAAI,EAAE,iBAAiB,CAAC,CAAC;IACnD,KAAK,CAAC,KAAK,EAAE,CAAC;IAEd,OAAO,GAAG,EAAE,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;AACpC,CAAC,CAAC;AAEF,MAAM,KAAK,GAAG,CAAC,EAAU,EAAiB,EAAE,CAAC,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC"}

package/dist/extensions/telegram/streaming.d.ts

@@ -0,0 +1,46 @@
+import type { Logger } from "../../log.ts";
+import { type SendApi } from "./sending.ts";
+export declare const EDIT_THROTTLE_MS = 1500;
+export type StreamApi = Pick<SendApi, "sendMessage" | "editMessageText" | "deleteMessage">;
+/**
+ * Progressive renderer for one agent exchange: sends a Telegram message early
+ * and edits it as text streams in, throttled and skipping no-op edits. Tool
+ * activity and pipeline status show as a transient italic line that the next
+ * text replaces. When the accumulated text outgrows Telegram's edit limit the
+ * current message is finalized in place and streaming continues in a new one.
+ * Edit failures degrade to the plain final-send behavior.
+ */
+export declare class StreamRenderer {
+    private readonly api;
+    private readonly chatId;
+    private readonly log;
+    private buffer;
+    private transient;
+    private messageId;
+    private lastRendered;
+    private lastEditAt;
+    private broken;
+    constructor(api: StreamApi, chatId: number, log: Logger);
+    appendText(text: string): Promise<void>;
+    /** Show a transient italic line (tool marker, status) below the streamed text. */
+    showTransient(line: string): Promise<void>;
+    /**
+     * Flush the remaining text bypassing the throttle, upgrading the streaming
+     * message to its final chunked form. Returns the last message id sent, or
+     * null when the exchange produced no text.
+     */
+    finalize(): Promise<number | null>;
+    private flush;
+    /**
+     * When the buffer exceeds the edit limit, finalize every full chunk (the
+     * first one in place, via edit) and keep only the tail streaming.
+     */
+    private commitOverflow;
+    private compose;
+    /**
+     * Fallback path after a streaming failure: the partial message may hold
+     * stale or duplicated content, so drop it and send the full remainder fresh.
+     */
+    private finalizeBroken;
+    private deleteCurrentMessage;
+}

package/dist/extensions/telegram/streaming.js

@@ -0,0 +1,140 @@
+import { splitMessage, TELEGRAM_MAX_MESSAGE_LENGTH } from "./chunking.js";
+import { editWithMarkdownFallback, sendChunked, sendWithMarkdownFallback, } from "./sending.js";
+export const EDIT_THROTTLE_MS = 1500;
+/**
+ * Progressive renderer for one agent exchange: sends a Telegram message early
+ * and edits it as text streams in, throttled and skipping no-op edits. Tool
+ * activity and pipeline status show as a transient italic line that the next
+ * text replaces. When the accumulated text outgrows Telegram's edit limit the
+ * current message is finalized in place and streaming continues in a new one.
+ * Edit failures degrade to the plain final-send behavior.
+ */
+export class StreamRenderer {
+    api;
+    chatId;
+    log;
+    buffer = "";
+    transient = null;
+    messageId = null;
+    lastRendered = "";
+    lastEditAt = 0;
+    broken = false;
+    constructor(api, chatId, log) {
+        this.api = api;
+        this.chatId = chatId;
+        this.log = log;
+    }
+    async appendText(text) {
+        this.transient = null;
+        this.buffer += text;
+        await this.flush(false);
+    }
+    /** Show a transient italic line (tool marker, status) below the streamed text. */
+    async showTransient(line) {
+        this.transient = line;
+        await this.flush(false);
+    }
+    /**
+     * Flush the remaining text bypassing the throttle, upgrading the streaming
+     * message to its final chunked form. Returns the last message id sent, or
+     * null when the exchange produced no text.
+     */
+    async finalize() {
+        this.transient = null;
+        if (this.broken)
+            return this.finalizeBroken();
+        if (this.buffer.trim().length === 0) {
+            await this.deleteCurrentMessage();
+            return null;
+        }
+        let lastId = this.messageId;
+        for (const [index, chunk] of splitMessage(this.buffer).entries()) {
+            if (index === 0 && this.messageId != null) {
+                try {
+                    await editWithMarkdownFallback(this.api, this.chatId, this.messageId, chunk);
+                    lastId = this.messageId;
+                    continue;
+                }
+                catch (error) {
+                    this.log.warn({ err: error }, "final edit failed — sending as a new message");
+                }
+            }
+            lastId = await sendWithMarkdownFallback(this.api, this.chatId, chunk);
+        }
+        return lastId;
+    }
+    async flush(force) {
+        if (this.broken)
+            return;
+        const now = Date.now();
+        if (!force && now - this.lastEditAt < EDIT_THROTTLE_MS)
+            return;
+        try {
+            await this.commitOverflow();
+            const display = this.compose();
+            if (display.length === 0 || display === this.lastRendered)
+                return;
+            if (this.messageId == null) {
+                this.messageId = await sendWithMarkdownFallback(this.api, this.chatId, display);
+            }
+            else {
+                await editWithMarkdownFallback(this.api, this.chatId, this.messageId, display);
+            }
+            this.lastRendered = display;
+            this.lastEditAt = now;
+        }
+        catch (error) {
+            // Stop streaming entirely — finalize() falls back to plain chunked sends.
+            this.broken = true;
+            this.log.warn({ err: error }, "streaming send/edit failed — falling back to final send");
+        }
+    }
+    /**
+     * When the buffer exceeds the edit limit, finalize every full chunk (the
+     * first one in place, via edit) and keep only the tail streaming.
+     */
+    async commitOverflow() {
+        if (this.buffer.length <= TELEGRAM_MAX_MESSAGE_LENGTH)
+            return;
+        const chunks = splitMessage(this.buffer);
+        this.buffer = chunks.at(-1) ?? "";
+        for (const chunk of chunks.slice(0, -1)) {
+            if (this.messageId != null) {
+                await editWithMarkdownFallback(this.api, this.chatId, this.messageId, chunk);
+                this.messageId = null;
+            }
+            else {
+                await sendWithMarkdownFallback(this.api, this.chatId, chunk);
+            }
+        }
+        this.lastRendered = "";
+    }
+    compose() {
+        if (this.transient == null)
+            return this.buffer;
+        const marker = `_${this.transient}_`;
+        if (this.buffer.length === 0)
+            return marker;
+        const joined = `${this.buffer}\n\n${marker}`;
+        return joined.length <= TELEGRAM_MAX_MESSAGE_LENGTH ? joined : this.buffer;
+    }
+    /**
+     * Fallback path after a streaming failure: the partial message may hold
+     * stale or duplicated content, so drop it and send the full remainder fresh.
+     */
+    async finalizeBroken() {
+        await this.deleteCurrentMessage();
+        const ids = await sendChunked(this.api, this.chatId, this.buffer);
+        return ids.at(-1) ?? null;
+    }
+    async deleteCurrentMessage() {
+        const messageId = this.messageId;
+        if (messageId == null)
+            return;
+        this.messageId = null;
+        await this.api
+            .deleteMessage(this.chatId, messageId)
+            .catch((error) => this.log.warn({ err: error }, "streaming message cleanup failed"));
+    }
+}
+//# sourceMappingURL=streaming.js.map

package/dist/extensions/telegram/streaming.js.map

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

package/dist/extensions/telegram/tools.d.ts

@@ -0,0 +1,80 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { InputFile } from "grammy";
+import type { InlineKeyboardMarkup, ReactionTypeEmoji } from "grammy/types";
+import { type Static, Type } from "typebox";
+/** Narrow grammY API surface the tools call — fakeable in tests. */
+export interface ToolApi {
+    sendMessage(chatId: number, text: string, other?: {
+        reply_markup?: InlineKeyboardMarkup;
+    }): Promise<{
+        message_id: number;
+    }>;
+    sendPhoto(chatId: number, photo: InputFile, other?: {
+        caption?: string;
+    }): Promise<{
+        message_id: number;
+    }>;
+    sendAudio(chatId: number, audio: InputFile, other?: {
+        caption?: string;
+    }): Promise<{
+        message_id: number;
+    }>;
+    sendVideo(chatId: number, video: InputFile, other?: {
+        caption?: string;
+    }): Promise<{
+        message_id: number;
+    }>;
+    sendDocument(chatId: number, document: InputFile, other?: {
+        caption?: string;
+    }): Promise<{
+        message_id: number;
+    }>;
+    setMessageReaction(chatId: number, messageId: number, reaction: ReactionTypeEmoji[]): Promise<unknown>;
+    pinChatMessage(chatId: number, messageId: number, other?: {
+        disable_notification?: boolean;
+    }): Promise<unknown>;
+    unpinChatMessage(chatId: number, messageId: number): Promise<unknown>;
+}
+export interface ToolDeps {
+    api: ToolApi;
+    chatId: number;
+    workspaceRoot: string;
+    /** Resolved, deduplicated roots that send_telegram_file accepts. */
+    allowedRoots: string[];
+    getLastInboundMessageId: () => number | null;
+    getLastOutboundMessageId: () => number | null;
+}
+declare const MEDIA_TYPES: {
+    readonly photo: readonly [".png", ".jpg", ".jpeg", ".gif", ".webp"];
+    readonly audio: readonly [".mp3", ".ogg", ".wav", ".flac"];
+    readonly video: readonly [".mp4", ".avi", ".mov", ".webm"];
+};
+type OutboundMediaType = keyof typeof MEDIA_TYPES | "document";
+export declare const detectMediaType: (path: string) => OutboundMediaType;
+export declare const validateFilePath: (filePath: string, workspaceRoot: string, allowedRoots: string[]) => Promise<string>;
+declare const SendFileParams: Type.TObject<{
+    filePath: Type.TString;
+    caption: Type.TOptional<Type.TString>;
+}>;
+export declare const handleSendFile: (deps: Pick<ToolDeps, "api" | "chatId" | "workspaceRoot" | "allowedRoots">, params: Static<typeof SendFileParams>) => Promise<string>;
+declare const ReactParams: Type.TObject<{
+    emoji: Type.TString;
+    messageId: Type.TOptional<Type.TNumber>;
+}>;
+export declare const handleReactToMessage: (deps: Pick<ToolDeps, "api" | "chatId" | "getLastInboundMessageId">, params: Static<typeof ReactParams>) => Promise<string>;
+export declare const handlePinMessage: (deps: Pick<ToolDeps, "api" | "chatId" | "getLastOutboundMessageId">) => Promise<string>;
+declare const UnpinParams: Type.TObject<{
+    messageId: Type.TNumber;
+}>;
+export declare const handleUnpinMessage: (deps: Pick<ToolDeps, "api" | "chatId">, params: Static<typeof UnpinParams>) => Promise<string>;
+declare const ButtonsParams: Type.TObject<{
+    prompt: Type.TString;
+    buttons: Type.TArray<Type.TArray<Type.TObject<{
+        label: Type.TString;
+        value: Type.TString;
+    }>>>;
+    singleUse: Type.TOptional<Type.TBoolean>;
+}>;
+export declare const handleSendMessageWithButtons: (deps: Pick<ToolDeps, "api" | "chatId">, params: Static<typeof ButtonsParams>) => Promise<string>;
+export declare const registerTelegramTools: (pi: ExtensionAPI, deps: ToolDeps) => void;
+export {};

package/dist/extensions/telegram/tools.js

@@ -0,0 +1,232 @@
+import { stat } from "node:fs/promises";
+import { basename, extname, isAbsolute, join, resolve, sep } from "node:path";
+import { InputFile } from "grammy";
+import { Type } from "typebox";
+import { buildInlineKeyboard, validateButtons } from "./buttons.js";
+// ---- send_telegram_file -------------------------------------------------------
+const MEDIA_TYPES = {
+    photo: [".png", ".jpg", ".jpeg", ".gif", ".webp"],
+    audio: [".mp3", ".ogg", ".wav", ".flac"],
+    video: [".mp4", ".avi", ".mov", ".webm"],
+};
+export const detectMediaType = (path) => {
+    const suffix = extname(path).toLowerCase();
+    for (const [category, extensions] of Object.entries(MEDIA_TYPES)) {
+        if (extensions.includes(suffix)) {
+            return category;
+        }
+    }
+    return "document";
+};
+const isWithin = (root, path) => path === root || path.startsWith(root.endsWith(sep) ? root : `${root}${sep}`);
+export const validateFilePath = async (filePath, workspaceRoot, allowedRoots) => {
+    const resolved = resolve(isAbsolute(filePath) ? filePath : join(workspaceRoot, filePath));
+    let stats;
+    try {
+        stats = await stat(resolved);
+    }
+    catch {
+        throw new Error(`File not found: ${resolved}`);
+    }
+    if (!stats.isFile())
+        throw new Error(`Path is not a regular file: ${resolved}`);
+    if (!allowedRoots.some((root) => isWithin(root, resolved))) {
+        throw new Error(`File must be under one of the allowed roots: ${allowedRoots.join(", ")} (got ${resolved})`);
+    }
+    return resolved;
+};
+const SendFileParams = Type.Object({
+    filePath: Type.String({
+        description: "Path to the file — workspace-relative, or absolute under the workspace, " +
+            "the system temporary directory, or a configured extra root",
+    }),
+    caption: Type.Optional(Type.String({ maxLength: 1024, description: "Brief description of the file" })),
+});
+export const handleSendFile = async (deps, params) => {
+    const resolved = await validateFilePath(params.filePath, deps.workspaceRoot, deps.allowedRoots);
+    const file = new InputFile(resolved);
+    const other = params.caption != null ? { caption: params.caption } : {};
+    switch (detectMediaType(resolved)) {
+        case "photo":
+            await deps.api.sendPhoto(deps.chatId, file, other);
+            break;
+        case "audio":
+            await deps.api.sendAudio(deps.chatId, file, other);
+            break;
+        case "video":
+            await deps.api.sendVideo(deps.chatId, file, other);
+            break;
+        default:
+            await deps.api.sendDocument(deps.chatId, file, other);
+            break;
+    }
+    return `File sent: ${basename(resolved)}`;
+};
+// ---- react_to_message ---------------------------------------------------------
+const ReactParams = Type.Object({
+    emoji: Type.String({
+        description: 'Reaction emoji, e.g. "👍" (Telegram supports a fixed set of reaction emoji)',
+    }),
+    messageId: Type.Optional(Type.Number({
+        description: "Telegram message ID to react to; defaults to the user's last message",
+    })),
+});
+export const handleReactToMessage = async (deps, params) => {
+    const messageId = params.messageId ?? deps.getLastInboundMessageId();
+    if (messageId == null)
+        throw new Error("No message available to react to");
+    // Telegram restricts reactions to a fixed emoji set; rather than hardcoding
+    // that evolving list, pass the string through and surface the API rejection.
+    await deps.api.setMessageReaction(deps.chatId, messageId, [
+        { type: "emoji", emoji: params.emoji },
+    ]);
+    return `Reacted to message ${messageId} with ${params.emoji}`;
+};
+// ---- pin_message / unpin_message ------------------------------------------------
+export const handlePinMessage = async (deps) => {
+    const messageId = deps.getLastOutboundMessageId();
+    if (messageId == null)
+        throw new Error("No message available to pin");
+    // An audible pin is the point: it delivers the push notification.
+    await deps.api.pinChatMessage(deps.chatId, messageId, { disable_notification: false });
+    return `Message pinned (ID: ${messageId})`;
+};
+const UnpinParams = Type.Object({
+    messageId: Type.Number({ description: "The Telegram message ID to unpin" }),
+});
+export const handleUnpinMessage = async (deps, params) => {
+    await deps.api.unpinChatMessage(deps.chatId, params.messageId);
+    return `Message unpinned (ID: ${params.messageId})`;
+};
+// ---- send_message_with_buttons ---------------------------------------------------
+const ButtonsParams = Type.Object({
+    prompt: Type.String({ description: "The message text shown above the buttons" }),
+    buttons: Type.Array(Type.Array(Type.Object({
+        label: Type.String({ description: "Text shown on the button" }),
+        value: Type.String({
+            description: "Machine-readable value you receive back on tap (max 58 UTF-8 bytes)",
+        }),
+    })), { description: "Rows of buttons; each row is a list of {label, value} objects" }),
+    singleUse: Type.Optional(Type.Boolean({
+        description: "Remove the keyboard after the first tap (default true)",
+    })),
+});
+export const handleSendMessageWithButtons = async (deps, params) => {
+    validateButtons(params.buttons);
+    const sent = await deps.api.sendMessage(deps.chatId, params.prompt, {
+        reply_markup: buildInlineKeyboard(params.buttons, params.singleUse ?? true),
+    });
+    return `Buttons sent (message_id: ${sent.message_id})`;
+};
+// ---- registration -----------------------------------------------------------------
+const SEND_FILE_DESCRIPTION = `Send a file to the user via Telegram.
+
+Supported media types (auto-detected from extension):
+- Images (.png, .jpg, .jpeg, .gif, .webp) → sent as photo
+- Audio (.mp3, .ogg, .wav, .flac) → sent as audio
+- Video (.mp4, .avi, .mov, .webm) → sent as video
+- All other files → sent as document
+
+The file must exist on disk and be a regular file under one of the allowed roots
+(the workspace, the system temporary directory, or a configured extra root).
+Allowed roots are enumerated in any rejection error. Telegram enforces a 50MB
+upload limit.`;
+const REACT_DESCRIPTION = `React to a Telegram message with an emoji.
+
+Defaults to the user's most recent message when messageId is omitted. Telegram
+supports a fixed set of reaction emoji (e.g. 👍 ❤️ 🔥 🎉 🤔 👀); unsupported emoji
+are rejected by the API.`;
+const PIN_DESCRIPTION = `Pin the most recent response message in the Telegram chat.
+
+The pin triggers a push notification so the user sees the pinned message promptly.
+Returns the pinned message's Telegram ID on success. Fails when no response has
+been sent yet or when pinning fails. Idempotent: pinning an already-pinned message
+succeeds.`;
+const UNPIN_DESCRIPTION = `Unpin a previously pinned message in the Telegram chat.
+
+Fails when the message ID does not exist or unpinning fails. Idempotent:
+unpinning a non-pinned message succeeds.`;
+const BUTTONS_DESCRIPTION = `Present a Telegram inline keyboard of tappable buttons in the chat.
+
+buttons is a list of rows; each row is a list of {label, value} buttons. label is
+shown on the button; value is the machine-readable identifier you receive back on
+tap. When singleUse is true (default) the keyboard is removed from the message
+after any button is tapped.
+
+When the user taps a button, you will receive a turn explicitly framed as
+"The user tapped the option \`<value>\` out of the options you displayed.",
+so you can distinguish taps from typed input. Use this for structured prompts
+like yes/no, multiple-choice, or confirm/cancel.
+
+Per-button value must be at most 58 UTF-8 bytes; labels must be non-empty; at
+least one row with at least one button is required; at most 100 buttons total.`;
+const textResult = (text) => ({
+    content: [{ type: "text", text }],
+    details: undefined,
+});
+export const registerTelegramTools = (pi, deps) => {
+    pi.registerTool({
+        name: "send_telegram_file",
+        label: "Send Telegram file",
+        description: SEND_FILE_DESCRIPTION,
+        promptSnippet: "Send a file from disk to the user via Telegram",
+        promptGuidelines: [
+            "Use send_telegram_file to deliver files (images, audio, video, documents) to the user instead of pasting their contents.",
+        ],
+        parameters: SendFileParams,
+        async execute(_toolCallId, params) {
+            return textResult(await handleSendFile(deps, params));
+        },
+    });
+    pi.registerTool({
+        name: "react_to_message",
+        label: "React to message",
+        description: REACT_DESCRIPTION,
+        promptSnippet: "React to a Telegram message with an emoji",
+        promptGuidelines: [
+            "Use react_to_message for lightweight acknowledgements (e.g. 👍 on a quick confirmation) instead of a full reply.",
+        ],
+        parameters: ReactParams,
+        async execute(_toolCallId, params) {
+            return textResult(await handleReactToMessage(deps, params));
+        },
+    });
+    pi.registerTool({
+        name: "pin_message",
+        label: "Pin message",
+        description: PIN_DESCRIPTION,
+        promptSnippet: "Pin the most recent response message in the Telegram chat",
+        promptGuidelines: [
+            "Use pin_message when the user should be able to find the last response again easily (reminders, important info).",
+        ],
+        parameters: Type.Object({}),
+        async execute() {
+            return textResult(await handlePinMessage(deps));
+        },
+    });
+    pi.registerTool({
+        name: "unpin_message",
+        label: "Unpin message",
+        description: UNPIN_DESCRIPTION,
+        promptSnippet: "Unpin a previously pinned Telegram message",
+        promptGuidelines: ["Use unpin_message when a pinned message is no longer relevant."],
+        parameters: UnpinParams,
+        async execute(_toolCallId, params) {
+            return textResult(await handleUnpinMessage(deps, params));
+        },
+    });
+    pi.registerTool({
+        name: "send_message_with_buttons",
+        label: "Send message with buttons",
+        description: BUTTONS_DESCRIPTION,
+        promptSnippet: "Present tappable inline buttons to the user via Telegram",
+        promptGuidelines: [
+            "Use send_message_with_buttons for structured choices (yes/no, multiple-choice, confirm/cancel) instead of asking the user to type an option.",
+        ],
+        parameters: ButtonsParams,
+        async execute(_toolCallId, params) {
+            return textResult(await handleSendMessageWithButtons(deps, params));
+        },
+    });
+};
+//# sourceMappingURL=tools.js.map

package/dist/extensions/telegram/tools.js.map

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

package/dist/extensions/workflows/cleanup.d.ts

@@ -0,0 +1,10 @@
+import type { PostProcessor } from "../api.ts";
+import type { WorkflowStateRepository } from "./repository.ts";
+export declare const DEFAULT_STALE_HOURS = 24;
+export type StaleRepository = Pick<WorkflowStateRepository, "listStale" | "softDelete">;
+/**
+ * Post-processor that expires workflow instances abandoned across sessions:
+ * soft-deletes records untouched for longer than the threshold and removes
+ * their scratchpad files.
+ */
+export declare const createStaleWorkflowCleanup: (repository: StaleRepository, staleHours?: number) => PostProcessor;