@fickydev/pigent 0.1.23 → 0.1.24

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## Unreleased
+
+## 0.1.24 - 2026-05-19
+
+### Added
+
+- Added Telegram working status UX with `sendChatAction` typing heartbeats and an editable `Working…` message while agent runs execute.
+
 ## 0.1.23 - 2026-05-18
 
 ### Fixed

package/TODO.md

@@ -90,6 +90,8 @@
 - [ ] Implement `TelegramApi`
   - [x] `getUpdates`
   - [x] `sendMessage`
+  - [x] `editMessageText`
+  - [x] `sendChatAction`
   - [x] error handling
   - [x] retry/backoff
   - [x] `answerCallbackQuery`
@@ -100,6 +102,7 @@
   - [x] offset tracking
   - [x] graceful stop
   - [x] update normalization
+  - [x] visible working status with typing indicator and editable status message
 - [x] Persist Telegram offset in DB
 
 ## Routing

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fickydev/pigent",
-  "version": "0.1.23",
+  "version": "0.1.24",
   "private": false,
   "type": "module",
   "description": "Autonomous multi-agent daemon using Pi as core execution engine.",

package/src/channels/telegram/TelegramApi.ts

@@ -1,7 +1,9 @@
 import type {
   TelegramAnswerCallbackQueryResponse,
+  TelegramEditMessageTextResponse,
   TelegramGetMeResponse,
   TelegramGetUpdatesResponse,
+  TelegramSendChatActionResponse,
   TelegramSendMessageResponse,
   TelegramSetMyCommandsResponse,
   TelegramUpdate,
@@ -68,14 +70,39 @@ export class TelegramApi {
     text: string;
     threadId?: string | null;
     inlineKeyboard?: InlineKeyboardButton[][];
-  }): Promise<void> {
-    await this.request<TelegramSendMessageResponse>("sendMessage", {
+  }): Promise<number | null> {
+    const response = await this.request<TelegramSendMessageResponse>("sendMessage", {
       chat_id: input.chatId,
       text: input.text,
       message_thread_id: input.threadId ? Number(input.threadId) : undefined,
       disable_web_page_preview: true,
       reply_markup: input.inlineKeyboard ? toTelegramInlineKeyboard(input.inlineKeyboard) : undefined,
     });
+
+    return response.result?.message_id ?? null;
+  }
+
+  async editMessageText(input: {
+    chatId: string;
+    messageId: number;
+    text: string;
+    inlineKeyboard?: InlineKeyboardButton[][];
+  }): Promise<void> {
+    await this.request<TelegramEditMessageTextResponse>("editMessageText", {
+      chat_id: input.chatId,
+      message_id: input.messageId,
+      text: input.text,
+      disable_web_page_preview: true,
+      reply_markup: input.inlineKeyboard ? toTelegramInlineKeyboard(input.inlineKeyboard) : undefined,
+    });
+  }
+
+  async sendChatAction(input: { chatId: string; action: "typing"; threadId?: string | null }): Promise<void> {
+    await this.request<TelegramSendChatActionResponse>("sendChatAction", {
+      chat_id: input.chatId,
+      action: input.action,
+      message_thread_id: input.threadId ? Number(input.threadId) : undefined,
+    });
   }
 
   async answerCallbackQuery(input: { callbackQueryId: string; text?: string }): Promise<void> {

package/src/channels/telegram/TelegramPollingAdapter.ts

@@ -1,6 +1,6 @@
 import type { RuntimeKvRepository } from "../../db/repositories/RuntimeKvRepository";
 import { logger } from "../../logging/logger";
-import type { ChannelAdapter, InboundMessage, MessageHandler, OutboundMessage } from "../types";
+import type { ChannelAdapter, InboundMessage, MessageHandler, OutboundMessage, RunStatusHandle } from "../types";
 import { TelegramApi, type TelegramBotCommand } from "./TelegramApi";
 import type { TelegramCallbackQuery, TelegramMessage, TelegramUpdate } from "./types";
 
@@ -63,6 +63,14 @@ export class TelegramPollingAdapter implements ChannelAdapter {
     });
   }
 
+  createRunStatus(message: OutboundMessage): RunStatusHandle {
+    if (message.channel !== "telegram") {
+      throw new Error(`unsupported channel for telegram adapter: ${message.channel}`);
+    }
+
+    return new TelegramRunStatusHandle(this.options.api, message);
+  }
+
   private async poll(handler: MessageHandler): Promise<void> {
     while (this.running) {
       try {
@@ -161,6 +169,84 @@ function normalizeTelegramCallbackQuery(updateId: number, callbackQuery: Telegra
   };
 }
 
+class TelegramRunStatusHandle implements RunStatusHandle {
+  private messageId: number | null = null;
+  private typingTimer: ReturnType<typeof setInterval> | null = null;
+
+  constructor(
+    private readonly api: TelegramApi,
+    private readonly message: OutboundMessage,
+  ) {}
+
+  async start(): Promise<void> {
+    await this.sendTyping();
+    this.messageId = await this.api.sendMessage({
+      chatId: this.message.chatId,
+      threadId: this.message.threadId,
+      text: this.message.text,
+    });
+
+    this.typingTimer = setInterval(() => {
+      void this.sendTyping();
+    }, 4000);
+  }
+
+  async complete(message: OutboundMessage): Promise<void> {
+    await this.stopAndPublish(message);
+  }
+
+  async fail(message: OutboundMessage): Promise<void> {
+    await this.stopAndPublish(message);
+  }
+
+  private async stopAndPublish(message: OutboundMessage): Promise<void> {
+    this.stopTyping();
+
+    if (this.messageId) {
+      try {
+        await this.api.editMessageText({
+          chatId: message.chatId,
+          messageId: this.messageId,
+          text: message.text,
+          inlineKeyboard: message.inlineKeyboard,
+        });
+        return;
+      } catch (error) {
+        logger.warn("telegram status edit failed; sending final message", {
+          error: error instanceof Error ? error.message : String(error),
+        });
+      }
+    }
+
+    await this.api.sendMessage({
+      chatId: message.chatId,
+      threadId: message.threadId,
+      text: message.text,
+      inlineKeyboard: message.inlineKeyboard,
+    });
+  }
+
+  private async sendTyping(): Promise<void> {
+    try {
+      await this.api.sendChatAction({
+        chatId: this.message.chatId,
+        threadId: this.message.threadId,
+        action: "typing",
+      });
+    } catch (error) {
+      logger.debug("telegram typing indicator failed", {
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  private stopTyping(): void {
+    if (!this.typingTimer) return;
+    clearInterval(this.typingTimer);
+    this.typingTimer = null;
+  }
+}
+
 function sleep(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }

package/src/channels/telegram/types.ts

@@ -63,6 +63,18 @@ export type TelegramAnswerCallbackQueryResponse = {
   description?: string;
 };
 
+export type TelegramEditMessageTextResponse = {
+  ok: boolean;
+  result?: TelegramMessage | boolean;
+  description?: string;
+};
+
+export type TelegramSendChatActionResponse = {
+  ok: boolean;
+  result: boolean;
+  description?: string;
+};
+
 export type TelegramSetMyCommandsResponse = {
   ok: boolean;
   result: boolean;

package/src/channels/types.ts

@@ -30,9 +30,16 @@ export type OutboundMessage = {
 
 export type MessageHandler = (message: InboundMessage) => Promise<void>;
 
+export interface RunStatusHandle {
+  start(): Promise<void>;
+  complete(message: OutboundMessage): Promise<void>;
+  fail(message: OutboundMessage): Promise<void>;
+}
+
 export interface ChannelAdapter {
   readonly id: ChannelId;
   start(handler: MessageHandler): Promise<void>;
   stop(): Promise<void>;
   send(message: OutboundMessage): Promise<void>;
+  createRunStatus?(message: OutboundMessage): RunStatusHandle;
 }

package/src/daemon/AgentDaemon.ts

@@ -117,18 +117,54 @@ export class AgentDaemon {
       return;
     }
 
-    const response = await this.runner.run({
-      agentId: route.agentId,
-      text: route.text,
-      message,
-    });
-
-    await this.send({
+    const status = this.createRunStatus({
       channel: message.channel,
       chatId: message.chatId,
       threadId: message.threadId,
-      text: response,
+      text: "Working…",
     });
+
+    await status?.start();
+
+    try {
+      const response = await this.runner.run({
+        agentId: route.agentId,
+        text: route.text,
+        message,
+      });
+
+      const outbound = {
+        channel: message.channel,
+        chatId: message.chatId,
+        threadId: message.threadId,
+        text: response,
+      };
+
+      if (status) {
+        await status.complete(outbound);
+      } else {
+        await this.send(outbound);
+      }
+    } catch (error) {
+      const failure = {
+        channel: message.channel,
+        chatId: message.chatId,
+        threadId: message.threadId,
+        text: "Agent failed to respond. Please try again later.",
+      };
+
+      if (status) {
+        await status.fail(failure);
+      } else {
+        await this.send(failure);
+      }
+
+      logger.error("agent run failed", {
+        channel: message.channel,
+        chatId: message.chatId,
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
   }
 
   private async autoConfigureChat(message: InboundMessage): Promise<void> {
@@ -142,13 +178,25 @@ export class AgentDaemon {
   }
 
   private async send(message: OutboundMessage): Promise<void> {
-    const adapter = this.adapters.find((candidate) => candidate.id === message.channel);
+    const adapter = this.findAdapter(message.channel);
+    if (!adapter) return;
+
+    await adapter.send(message);
+  }
+
+  private createRunStatus(message: OutboundMessage) {
+    const adapter = this.findAdapter(message.channel);
+    return adapter?.createRunStatus?.(message) ?? null;
+  }
+
+  private findAdapter(channel: OutboundMessage["channel"]): ChannelAdapter | null {
+    const adapter = this.adapters.find((candidate) => candidate.id === channel);
     if (!adapter) {
-      logger.warn("no adapter available for outbound message", { channel: message.channel });
-      return;
+      logger.warn("no adapter available for outbound message", { channel });
+      return null;
     }
 
-    await adapter.send(message);
+    return adapter;
   }
 }