Skip to content

Soul-driven AI agent with permission-hardened tools, token budgets, and multi-channel access. Runs 24/7 from CLI, Telegram or More.

feat: implement real-time Telegram response streaming with toggleable /stream command

Salman Qureshieada56e4336c
diff --git a/README.md b/README.md
index 96108101..c4201cb2 100644
--- a/README.md
+++ b/README.md
@@ -125,6 +125,8 @@ Type these during a conversation — they don't consume API tokens. Work on both
| `/status` | Show agent config, budget, and usage |
| `/tools` | List all loaded tools |
| `/skills` | List installed skills |
+| `/stream` | Toggle Telegram text streaming |
+| `/stream off` | Disable streaming (single message) |
| `/budget` | Show token budget status |
| `/budget override` | Override budget for one request |
| `/budget reset` | Reset usage to zero |
diff --git a/docs/docs.html b/docs/docs.html
index 1ca7eadb..b303747b 100644
--- a/docs/docs.html
+++ b/docs/docs.html
@@ -438,6 +438,14 @@
<td>/skills</td>
<td>List installed skills</td>
</tr>
+ <tr>
+ <td>/stream</td>
+ <td>Toggle Telegram text streaming (on/off)</td>
+ </tr>
+ <tr>
+ <td>/stream off</td>
+ <td>Disable streaming — responses arrive as single message</td>
+ </tr>
<tr>
<td>/budget</td>
<td>Show token budget status</td>
diff --git a/src/channels/telegram.ts b/src/channels/telegram.ts
index 7a286499..0aa1bb2c 100644
--- a/src/channels/telegram.ts
+++ b/src/channels/telegram.ts
@@ -15,11 +15,16 @@ export class TelegramChannel extends BaseChannel {
private bot: Bot | null = null;
private ownerChatId: number | null = null;
private typingInterval: NodeJS.Timeout | null = null;
+ private chatCommandContext?: import('../capabilities/registry.js').ChatCommandContext;
constructor(private config: MercuryConfig) {
super();
}
+ setChatCommandContext(ctx: import('../capabilities/registry.js').ChatCommandContext): void {
+ this.chatCommandContext = ctx;
+ }
+
async start(): Promise<void> {
const token = this.config.channels.telegram.botToken;
if (!token) {
@@ -57,13 +62,37 @@ export class TelegramChannel extends BaseChannel {
this.bot = bot;
await bot.start({
- onStart: (info) => {
+ onStart: async (info) => {
logger.info({ bot: info.username }, 'Telegram bot started — long polling active');
this.ready = true;
+ await this.registerCommands();
},
});
}
+ private async registerCommands(): Promise<void> {
+ if (!this.bot) return;
+
+ const commands = [
+ { command: 'help', description: 'Show capabilities and commands manual' },
+ { command: 'status', description: 'Show agent config, budget, and uptime' },
+ { command: 'tools', description: 'List all loaded tools' },
+ { command: 'skills', description: 'List installed skills' },
+ { command: 'budget', description: 'Show token budget status' },
+ { command: 'budget_override', description: 'Override budget for one request' },
+ { command: 'budget_reset', description: 'Reset token usage to zero' },
+ { command: 'budget_set', description: 'Set new daily token budget' },
+ { command: 'stream', description: 'Toggle text streaming on/off' },
+ ];
+
+ try {
+ await this.bot.api.setMyCommands(commands);
+ logger.info({ count: commands.length }, 'Telegram bot commands registered');
+ } catch (err: any) {
+ logger.warn({ err: err.message }, 'Failed to register Telegram commands (non-critical)');
+ }
+ }
+
async stop(): Promise<void> {
this.bot?.stop();
this.ready = false;
@@ -166,25 +195,80 @@ export class TelegramChannel extends BaseChannel {
}
}
- async sendStreamToChat(chatId: number, textStream: AsyncIterable<string>): Promise<void> {
- if (!this.bot) return;
+ async sendStreamToChat(chatId: number, textStream: AsyncIterable<string>): Promise<string> {
+ if (!this.bot) return '';
+
+ const STREAM_EDIT_INTERVAL = 1500;
+ const STREAM_MIN_LENGTH = 20;
+
this.startTypingLoop(chatId);
+
try {
let full = '';
+ let messageId: number | null = null;
+ let lastEditTime = 0;
+ let lastEditLength = 0;
+
for await (const chunk of textStream) {
full += chunk;
+
+ const now = Date.now();
+ const timeSinceLastEdit = now - lastEditTime;
+ const charsSinceLastEdit = full.length - lastEditLength;
+
+ if (messageId === null && full.length >= STREAM_MIN_LENGTH) {
+ try {
+ const msg = await this.bot.api.sendMessage(chatId, this.escapeHtml(full) + ' ▌', { parse_mode: 'HTML' });
+ messageId = msg.message_id;
+ lastEditTime = now;
+ lastEditLength = full.length;
+ } catch {
+ messageId = null;
+ }
+ } else if (messageId !== null && timeSinceLastEdit >= STREAM_EDIT_INTERVAL && charsSinceLastEdit >= 20) {
+ try {
+ await this.bot.api.editMessageText(chatId, messageId, this.escapeHtml(full) + ' ▌', { parse_mode: 'HTML' });
+ lastEditTime = now;
+ lastEditLength = full.length;
+ } catch {
+ // edit failed — rate limited or message unchanged, skip
+ }
+ }
}
- const html = mdToTelegram(full);
- try {
- await this.bot.api.sendMessage(chatId, html, { parse_mode: 'HTML' });
- } catch {
- await this.bot.api.sendMessage(chatId, this.stripHtml(html));
+
+ if (messageId !== null) {
+ const html = mdToTelegram(full);
+ try {
+ await this.bot.api.editMessageText(chatId, messageId, html, { parse_mode: 'HTML' });
+ } catch {
+ try {
+ await this.bot.api.editMessageText(chatId, messageId, this.stripHtml(html));
+ } catch {
+ // final edit failed
+ }
+ }
+ } else {
+ const html = mdToTelegram(full);
+ try {
+ await this.bot.api.sendMessage(chatId, html, { parse_mode: 'HTML' });
+ } catch {
+ await this.bot.api.sendMessage(chatId, this.stripHtml(html));
+ }
}
+
+ return full;
} finally {
this.stopTypingLoop();
}
}
+ private escapeHtml(text: string): string {
+ return text
+ .replace(/&/g, '&amp;')
+ .replace(/</g, '&lt;')
+ .replace(/>/g, '&gt;');
+ }
+
private splitMessage(text: string, maxLen: number): string[] {
if (text.length <= maxLen) return [text];
const chunks: string[] = [];
diff --git a/src/core/agent.ts b/src/core/agent.ts
index 7f4a7944..25ed1461 100644
--- a/src/core/agent.ts
+++ b/src/core/agent.ts
@@ -21,6 +21,7 @@ export class Agent {
private running = false;
private messageQueue: ChannelMessage[] = [];
private processing = false;
+ private telegramStreaming: boolean;
constructor(
private config: MercuryConfig,
@@ -37,6 +38,7 @@ export class Agent {
this.lifecycle = new Lifecycle();
this.scheduler = scheduler;
this.capabilities = capabilities;
+ this.telegramStreaming = config.channels.telegram.streaming ?? true;
this.scheduler.setOnScheduledTask(async (manifest) => this.handleScheduledTask(manifest));
@@ -118,6 +120,37 @@ export class Agent {
return;
}
+ if (trimmed === '/budget_override') {
+ await this.handleBudgetCommand('override', msg.channelType, msg.channelId);
+ this.lifecycle.transition('idle');
+ return;
+ }
+ if (trimmed === '/budget_reset') {
+ await this.handleBudgetCommand('reset', msg.channelType, msg.channelId);
+ this.lifecycle.transition('idle');
+ return;
+ }
+ if (trimmed.startsWith('/budget_set')) {
+ const args = trimmed.slice('/budget_set'.length).trim();
+ await this.handleBudgetCommand('set ' + args, msg.channelType, msg.channelId);
+ this.lifecycle.transition('idle');
+ return;
+ }
+ if (trimmed.startsWith('/stream')) {
+ const sub = trimmed.slice('/stream'.length).trim().toLowerCase();
+ if (sub === 'off') {
+ this.telegramStreaming = false;
+ const ch = this.channels.get(msg.channelType as any);
+ if (ch) await ch.send('Telegram streaming disabled. Responses will arrive as a single message.', msg.channelId);
+ } else {
+ this.telegramStreaming = true;
+ const ch = this.channels.get(msg.channelType as any);
+ if (ch) await ch.send('Telegram streaming enabled. Responses will appear progressively.', msg.channelId);
+ }
+ this.lifecycle.transition('idle');
+ return;
+ }
+
if (await this.handleChatCommand(trimmed, msg.channelType, msg.channelId)) {
this.lifecycle.transition('idle');
return;
@@ -184,7 +217,7 @@ export class Agent {
let lastError: any = null;
let streamedText = '';
- const canStream = msg.channelType === 'cli';
+ const canStream = msg.channelType === 'cli' || (msg.channelType === 'telegram' && this.telegramStreaming);
for (const provider of fallbackIterator) {
try {
@@ -206,7 +239,25 @@ export class Agent {
},
});
- const fullText = await channel.stream(streamResult.textStream, msg.channelId);
+ let fullText: string;
+
+ if (msg.channelType === 'telegram') {
+ const tgChannel = this.channels.get('telegram');
+ if (tgChannel && 'sendStreamToChat' in tgChannel) {
+ const chatId = msg.channelId.startsWith('telegram:')
+ ? Number(msg.channelId.split(':')[1])
+ : Number(msg.channelId);
+ if (!isNaN(chatId)) {
+ fullText = await (tgChannel as any).sendStreamToChat(chatId, streamResult.textStream);
+ } else {
+ fullText = await channel.stream(streamResult.textStream, msg.channelId);
+ }
+ } else {
+ fullText = await channel.stream(streamResult.textStream, msg.channelId);
+ }
+ } else {
+ fullText = await channel.stream(streamResult.textStream, msg.channelId);
+ }
const [usage] = await Promise.all([
streamResult.usage,
@@ -550,6 +601,18 @@ export class Agent {
return true;
}
+ if (cmd === '/stream' || cmd === '/stream on') {
+ this.telegramStreaming = true;
+ await channel.send('Telegram streaming enabled. Responses will appear progressively.', channelId);
+ return true;
+ }
+
+ if (cmd === '/stream off') {
+ this.telegramStreaming = false;
+ await channel.send('Telegram streaming disabled. Responses will arrive as a single message.', channelId);
+ return true;
+ }
+
return false;
}
}
\ No newline at end of file
diff --git a/src/index.ts b/src/index.ts
index 2fd408c4..933012a6 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -12,6 +12,7 @@ import { Agent } from './core/agent.js';
import { Scheduler } from './core/scheduler.js';
import { ChannelRegistry } from './channels/registry.js';
import { CLIChannel } from './channels/cli.js';
+import { TelegramChannel } from './channels/telegram.js';
import { TokenBudget } from './utils/tokens.js';
import { CapabilityRegistry } from './capabilities/registry.js';
import { SkillLoader } from './skills/loader.js';
diff --git a/src/utils/config.ts b/src/utils/config.ts
index c9ce1cf2..16a5af40 100644
--- a/src/utils/config.ts
+++ b/src/utils/config.ts
@@ -38,6 +38,7 @@ export interface MercuryConfig {
botToken: string;
webhookUrl?: string;
allowedChatIds?: number[];
+ streaming?: boolean;
};
};
memory: {
@@ -109,6 +110,7 @@ export function getDefaultConfig(): MercuryConfig {
.split(',')
.filter(Boolean)
.map(Number),
+ streaming: getEnvBool('TELEGRAM_STREAMING', true),
},
},
memory: {
diff --git a/src/utils/manual.ts b/src/utils/manual.ts
index d7d328db..b370ad6a 100644
--- a/src/utils/manual.ts
+++ b/src/utils/manual.ts
@@ -79,6 +79,9 @@ export function getManual(): string {
['/status', 'Show config and budget info'],
['/tools', 'List currently loaded tools'],
['/skills', 'List installed skills'],
+ ['/stream', 'Toggle text streaming on/off (Telegram)'],
+ ['/stream on', 'Enable streaming (live text updates)'],
+ ['/stream off', 'Disable streaming (single message)'],
];
for (const [cmd, desc] of chat) {