Adds Agent Swarms
* feat: streaming container mode, IPC messaging, agent teams support
Major architectural shift from single-shot container runs to long-lived
streaming containers with IPC-based message injection.
- Agent runner: query loop with AsyncIterable prompt to keep stdin open
for agent teams (fixes isSingleUserTurn premature shutdown)
- New standalone stdio MCP server (ipc-mcp-stdio.ts) inheritable by
subagents, with send_message and schedule_task tools
- Streaming output: parse OUTPUT_START/END markers in real-time, send
results to WhatsApp as they arrive
- IPC file-based messaging: host writes to ipc/{group}/input/, agent
polls for follow-up messages without respawning containers
- Per-group settings.json with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
- SDK bumped to 0.2.34 for TeamCreate tool support
- Container idle timeout (30min) with _close sentinel for shutdown
- Orphaned container cleanup on startup
- alwaysRespond flag for groups that skip trigger pattern check
- Uncaught exception/rejection handlers with timestamps in logger
- Combined SDK documentation into single deep dive reference
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* chore: remove unused ipc-mcp.ts (replaced by ipc-mcp-stdio.ts)
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: clarify agent communication model in docs and tool descriptions
- CLAUDE.md (main + global): split communication instructions into
"responding to messages" vs "scheduled tasks" sections
- send_message tool: note that scheduled task output is not sent to user
- Remove structured output (outputFormat) — not needed with current flow
- Regular output is sent to WhatsApp; scheduled task output is only logged
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* chore: ignore dynamic group data while preserving base structure
Only track groups/main/CLAUDE.md and groups/global/CLAUDE.md. All other
group directories and files are ignored to prevent tracking user-specific
session data.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: resolve critical bugs in streaming container mode
Bug 1 (scheduled task hang): Task scheduler now passes onOutput callback
with idle timer that writes _close sentinel after IDLE_TIMEOUT, so
containers exit cleanly instead of blocking queue slots for 30 minutes.
Scheduled tasks stay alive for interactive follow-up via IPC.
Bug 2 (timeout disabled): Remove resetTimeout() from stderr handler.
SDK writes debug logs continuously, resetting the timer on every line.
Timeout now only resets on actual output markers in stdout.
Bug 3 (trigger bypass): Piped messages in startMessageLoop now check
trigger pattern for non-main groups. Non-trigger messages accumulate in
DB and are pulled as context via getMessagesSince when a trigger arrives.
Bug 7 (non-atomic IPC writes): GroupQueue.sendMessage uses temp file +
rename for atomic writes, matching ipc-mcp-stdio.ts pattern.
Also: flip isVerbose back to false (debug leftover), add isScheduledTask
to host-side ContainerInput interface.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: idle timer not starting + scheduled task groupFolder missing
Two bugs that prevented the scheduled task idle timeout fix from working:
1. onOutput was only called when parsed.result !== null, but session
update markers have result: null. The idle timer never started for
"silent" query completions, leaving containers parked at
waitForIpcMessage until hard timeout.
2. Scheduler's onProcess callback didn't pass groupFolder to
queue.registerProcess, so closeStdin no-oped (groupFolder was null).
The _close sentinel was never written even when the idle timer fired.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: duplicate messages and timestamp rollback in piping path
Two bugs introduced by the trigger context accumulation change:
1. processGroupMessages didn't advance lastAgentTimestamp until after
the container finished. The piping path's getMessagesSince(lastAgent
Timestamp) re-fetched messages already sent as the initial prompt,
causing duplicates.
2. processGroupMessages overwrote lastAgentTimestamp with the original
batch timestamp on completion, rolling back any advancement made by
the piping path while the container was running.
Fix: advance lastAgentTimestamp immediately after building the prompt,
before starting the container. This matches the piping path behavior
and eliminates both the overlap and the rollback.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: container idles 30 extra minutes after _close during query
When _close was detected during pollIpcDuringQuery, it was consumed
(deleted) and stream.end() was called. But after runQuery returned,
main() still emitted a session-update marker (resetting the host's idle
timer) and called waitForIpcMessage (which polled forever since _close
was already gone). The container had to wait for a second _close.
Fix: runQuery now returns closedDuringQuery. When true, main() skips
the session-update marker and waitForIpcMessage, exiting immediately.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: resume branching, internal tags, and output forwarding
- Fix resume branching: pass resumeSessionAt with last assistant UUID
to anchor each query loop resume to the correct conversation tree
position. Prevents agent responses landing on invisible branches
when agent teams subagents create parallel JSONL entries.
- Add <internal> tag stripping: agent can wrap internal reasoning in
<internal> tags which are logged but not sent to WhatsApp. Prevents
duplicate messages and internal monologue reaching users.
- Forward scheduled task output: scheduled tasks now send result text
to WhatsApp (with <internal> stripping), matching regular message
behavior. No more special-case instructions.
- Update Communication guidance in CLAUDE.md: simplified to "your
output is sent to the user or group" with soft guidance on
<internal> tags and send_message usage.
- Add messaging behavior docs to schedule_task tool: prompts the
scheduling agent to include guidance on whether the task should
always/conditionally/never message the user.
- Mount security: containerPath now optional, defaults to basename
of hostPath.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: cursor rollback on error, flush guard, verbose logging
- Roll back lastAgentTimestamp on container error so retries can
re-process the messages instead of silently losing them.
- Add guard flag to flushOutgoingQueue to prevent duplicate sends
from concurrent flushes during rapid WA reconnects.
- Revert isVerbose from hardcoded false back to env-based check
(LOG_LEVEL=debug|trace).
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: orphan container cleanup was silently failing
The startup cleanup used `container ls --format {{.Names}}` which is
Docker Go-template syntax. Apple Container only supports `--format json`
or `--format table`. The command errored with exit code 64, but the
catch block silently swallowed it — orphan containers were never cleaned
up on restart.
Fixed to use `--format json` and parse `configuration.id` from the
JSON output. Also filters by `status: running` and logs a warning on
failure instead of silently catching.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* docs: add Discord badge and community section
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: idle timer reset on null results and flush queue message loss
- Only reset idle timer on actual results (non-null), not session-update
markers. Prevents containers staying alive 30 extra minutes after the
agent finishes work.
- flushOutgoingQueue now uses shift() instead of splice(0) so unattempted
messages stay in the queue if an unexpected error bails the loop.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* docs: add Agent Swarms to README
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: update Telegram skill for current architecture
Rewrite integration instructions to match the per-group queue/SQLite
architecture: remove onMessage callback pattern (store to DB, let
message loop pick up), fix startSchedulerLoop signature, add
TELEGRAM_ONLY service startup, SQLite registration, data/env/env sync,
@mention-to-trigger translation, and BotFather group privacy docs.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: Telegram skill message chunking, media placeholders, chat discovery
- Split long messages at Telegram's 4096 char limit to prevent silent
send failures
- Store placeholder text for non-text messages (photos, voice, stickers,
etc.) so the agent knows media was sent
- Update getAvailableGroups filter to include tg: chats so the agent can
discover and register Telegram chats via IPC
- Fix removal step numbering
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* docs: update REQUIREMENTS.md and SPEC.md for SQLite architecture
- Replace all registered_groups.json / sessions.json / router_state.json
references with SQLite equivalents
- Fix CONTAINER_TIMEOUT default (300000 → 1800000)
- Add missing config exports (IDLE_TIMEOUT, MAX_CONCURRENT_CONTAINERS)
- Update folder structure: add missing src files (logger, group-queue,
mount-security), remove non-existent utils.ts, list all skills
- Fix agent-runner entry (ipc-mcp.ts → ipc-mcp-stdio.ts)
- Update startup sequence to reflect per-group queue architecture
- Fix env mounting description (data/env/env, not extracted vars)
- Update troubleshooting to use sqlite3 commands
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* docs: fix README architecture description, revert SPEC.md env error
- README: update architecture blurb to mention per-group queue, add
group-queue.ts to key files, update file descriptions
- SPEC.md: restore correct credential filtering description (only auth
vars are extracted from .env, not the full file)
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
gavrielc
@@ -52,6 +52,21 @@ Tell the user:
|
||||
> 2. Send any message
|
||||
> 3. Use the `/chatid` command in the group
|
||||
|
||||
### 4. Disable Group Privacy (for group chats)
|
||||
|
||||
Tell the user:
|
||||
|
||||
> **Important for group chats**: By default, Telegram bots in groups only receive messages that @mention the bot or are commands. To let the bot see all messages (needed for `requiresTrigger: false` or trigger-word detection):
|
||||
>
|
||||
> 1. Open Telegram and search for `@BotFather`
|
||||
> 2. Send `/mybots` and select your bot
|
||||
> 3. Go to **Bot Settings** > **Group Privacy**
|
||||
> 4. Select **Turn off**
|
||||
>
|
||||
> Without this, the bot will only see messages that directly @mention it.
|
||||
|
||||
This step is optional if the user only wants trigger-based responses via @mentioning the bot.
|
||||
|
||||
## Questions to Ask
|
||||
|
||||
Before making changes, ask:
|
||||
@@ -61,8 +76,8 @@ Before making changes, ask:
|
||||
- If alongside: Both will run
|
||||
|
||||
2. **Chat behavior**: Should this chat respond to all messages or only when @mentioned?
|
||||
- Main chat: Responds to all
|
||||
- Other chats: Can configure `respondToAll: true` in registered_groups.json
|
||||
- Main chat: Responds to all (set `requiresTrigger: false`)
|
||||
- Other chats: Default requires trigger (`requiresTrigger: true`)
|
||||
|
||||
## Implementation
|
||||
|
||||
@@ -108,44 +123,51 @@ export function storeMessageDirect(msg: {
|
||||
}
|
||||
```
|
||||
|
||||
Also update the db.ts exports to include `storeMessageDirect`.
|
||||
This uses the existing `db` instance from `db.ts`. No additional imports needed.
|
||||
|
||||
### Step 3: Create Telegram Module
|
||||
|
||||
Create `src/telegram.ts` with this content:
|
||||
Create `src/telegram.ts`. The Telegram module is a thin layer that stores incoming messages to the database. It does NOT call the agent directly — the existing `startMessageLoop()` in `src/index.ts` polls all registered group JIDs and picks up Telegram messages automatically.
|
||||
|
||||
```typescript
|
||||
import { Bot } from "grammy";
|
||||
import pino from "pino";
|
||||
import {
|
||||
ASSISTANT_NAME,
|
||||
TRIGGER_PATTERN,
|
||||
MAIN_GROUP_FOLDER,
|
||||
} from "./config.js";
|
||||
import { RegisteredGroup, NewMessage } from "./types.js";
|
||||
import { storeChatMetadata, storeMessageDirect } from "./db.js";
|
||||
|
||||
const logger = pino({
|
||||
level: process.env.LOG_LEVEL || "info",
|
||||
transport: { target: "pino-pretty", options: { colorize: true } },
|
||||
});
|
||||
|
||||
export interface TelegramCallbacks {
|
||||
onMessage: (
|
||||
msg: NewMessage,
|
||||
group: RegisteredGroup,
|
||||
) => Promise<string | null>;
|
||||
getRegisteredGroups: () => Record<string, RegisteredGroup>;
|
||||
}
|
||||
import {
|
||||
getAllRegisteredGroups,
|
||||
storeChatMetadata,
|
||||
storeMessageDirect,
|
||||
} from "./db.js";
|
||||
import { logger } from "./logger.js";
|
||||
|
||||
let bot: Bot | null = null;
|
||||
let callbacks: TelegramCallbacks | null = null;
|
||||
|
||||
export async function connectTelegram(
|
||||
botToken: string,
|
||||
cbs: TelegramCallbacks,
|
||||
): Promise<void> {
|
||||
callbacks = cbs;
|
||||
/** Store a placeholder message for non-text content (photos, voice, etc.) */
|
||||
function storeNonTextMessage(ctx: any, placeholder: string): void {
|
||||
const chatId = `tg:${ctx.chat.id}`;
|
||||
const registeredGroups = getAllRegisteredGroups();
|
||||
if (!registeredGroups[chatId]) return;
|
||||
|
||||
const timestamp = new Date(ctx.message.date * 1000).toISOString();
|
||||
const senderName =
|
||||
ctx.from?.first_name || ctx.from?.username || ctx.from?.id?.toString() || "Unknown";
|
||||
const caption = ctx.message.caption ? ` ${ctx.message.caption}` : "";
|
||||
|
||||
storeChatMetadata(chatId, timestamp);
|
||||
storeMessageDirect({
|
||||
id: ctx.message.message_id.toString(),
|
||||
chat_jid: chatId,
|
||||
sender: ctx.from?.id?.toString() || "",
|
||||
sender_name: senderName,
|
||||
content: `${placeholder}${caption}`,
|
||||
timestamp,
|
||||
is_from_me: false,
|
||||
});
|
||||
}
|
||||
|
||||
export async function connectTelegram(botToken: string): Promise<void> {
|
||||
bot = new Bot(botToken);
|
||||
|
||||
// Command to get chat ID (useful for registration)
|
||||
@@ -173,7 +195,7 @@ export async function connectTelegram(
|
||||
if (ctx.message.text.startsWith("/")) return;
|
||||
|
||||
const chatId = `tg:${ctx.chat.id}`;
|
||||
const content = ctx.message.text;
|
||||
let content = ctx.message.text;
|
||||
const timestamp = new Date(ctx.message.date * 1000).toISOString();
|
||||
const senderName =
|
||||
ctx.from?.first_name ||
|
||||
@@ -189,11 +211,31 @@ export async function connectTelegram(
|
||||
? senderName
|
||||
: (ctx.chat as any).title || chatId;
|
||||
|
||||
// Translate Telegram @bot_username mentions into TRIGGER_PATTERN format.
|
||||
// Telegram @mentions (e.g., @andy_ai_bot) won't match TRIGGER_PATTERN
|
||||
// (e.g., ^@Andy\b), so we prepend the trigger when the bot is @mentioned.
|
||||
const botUsername = ctx.me?.username?.toLowerCase();
|
||||
if (botUsername) {
|
||||
const entities = ctx.message.entities || [];
|
||||
const isBotMentioned = entities.some((entity) => {
|
||||
if (entity.type === "mention") {
|
||||
const mentionText = content
|
||||
.substring(entity.offset, entity.offset + entity.length)
|
||||
.toLowerCase();
|
||||
return mentionText === `@${botUsername}`;
|
||||
}
|
||||
return false;
|
||||
});
|
||||
if (isBotMentioned && !TRIGGER_PATTERN.test(content)) {
|
||||
content = `@${ASSISTANT_NAME} ${content}`;
|
||||
}
|
||||
}
|
||||
|
||||
// Store chat metadata for discovery
|
||||
storeChatMetadata(chatId, timestamp, chatName);
|
||||
|
||||
// Check if this chat is registered
|
||||
const registeredGroups = callbacks!.getRegisteredGroups();
|
||||
const registeredGroups = getAllRegisteredGroups();
|
||||
const group = registeredGroups[chatId];
|
||||
|
||||
if (!group) {
|
||||
@@ -204,7 +246,7 @@ export async function connectTelegram(
|
||||
return;
|
||||
}
|
||||
|
||||
// Store message for registered chats
|
||||
// Store message — startMessageLoop() will pick it up
|
||||
storeMessageDirect({
|
||||
id: msgId,
|
||||
chat_jid: chatId,
|
||||
@@ -215,59 +257,28 @@ export async function connectTelegram(
|
||||
is_from_me: false,
|
||||
});
|
||||
|
||||
const isMain = group.folder === MAIN_GROUP_FOLDER;
|
||||
const respondToAll = (group as any).respondToAll === true;
|
||||
|
||||
// Check if bot is @mentioned in the message (Telegram native mention)
|
||||
const botUsername = ctx.me?.username?.toLowerCase();
|
||||
const entities = ctx.message.entities || [];
|
||||
const isBotMentioned = entities.some((entity) => {
|
||||
if (entity.type === "mention") {
|
||||
const mentionText = content
|
||||
.substring(entity.offset, entity.offset + entity.length)
|
||||
.toLowerCase();
|
||||
return mentionText === `@${botUsername}`;
|
||||
}
|
||||
return false;
|
||||
});
|
||||
|
||||
// Respond if: main group, respondToAll group, bot is @mentioned, or trigger pattern matches
|
||||
if (
|
||||
!isMain &&
|
||||
!respondToAll &&
|
||||
!isBotMentioned &&
|
||||
!TRIGGER_PATTERN.test(content)
|
||||
) {
|
||||
return;
|
||||
}
|
||||
|
||||
logger.info(
|
||||
{ chatId, chatName, sender: senderName },
|
||||
"Processing Telegram message",
|
||||
"Telegram message stored",
|
||||
);
|
||||
|
||||
// Send typing indicator
|
||||
await ctx.replyWithChatAction("typing");
|
||||
|
||||
const msg: NewMessage = {
|
||||
id: msgId,
|
||||
chat_jid: chatId,
|
||||
sender,
|
||||
sender_name: senderName,
|
||||
content,
|
||||
timestamp,
|
||||
};
|
||||
|
||||
try {
|
||||
const response = await callbacks!.onMessage(msg, group);
|
||||
if (response) {
|
||||
await ctx.reply(`${ASSISTANT_NAME}: ${response}`);
|
||||
}
|
||||
} catch (err) {
|
||||
logger.error({ err, chatId }, "Error processing Telegram message");
|
||||
}
|
||||
});
|
||||
|
||||
// Handle non-text messages with placeholders so the agent knows something was sent
|
||||
bot.on("message:photo", (ctx) => storeNonTextMessage(ctx, "[Photo]"));
|
||||
bot.on("message:video", (ctx) => storeNonTextMessage(ctx, "[Video]"));
|
||||
bot.on("message:voice", (ctx) => storeNonTextMessage(ctx, "[Voice message]"));
|
||||
bot.on("message:audio", (ctx) => storeNonTextMessage(ctx, "[Audio]"));
|
||||
bot.on("message:document", (ctx) => {
|
||||
const name = ctx.message.document?.file_name || "file";
|
||||
storeNonTextMessage(ctx, `[Document: ${name}]`);
|
||||
});
|
||||
bot.on("message:sticker", (ctx) => {
|
||||
const emoji = ctx.message.sticker?.emoji || "";
|
||||
storeNonTextMessage(ctx, `[Sticker ${emoji}]`);
|
||||
});
|
||||
bot.on("message:location", (ctx) => storeNonTextMessage(ctx, "[Location]"));
|
||||
bot.on("message:contact", (ctx) => storeNonTextMessage(ctx, "[Contact]"));
|
||||
|
||||
// Handle errors gracefully
|
||||
bot.catch((err) => {
|
||||
logger.error({ err: err.message }, "Telegram bot error");
|
||||
@@ -298,15 +309,33 @@ export async function sendTelegramMessage(
|
||||
}
|
||||
|
||||
try {
|
||||
// Remove tg: prefix if present
|
||||
const numericId = chatId.replace(/^tg:/, "");
|
||||
await bot.api.sendMessage(numericId, text);
|
||||
|
||||
// Telegram has a 4096 character limit per message — split if needed
|
||||
const MAX_LENGTH = 4096;
|
||||
if (text.length <= MAX_LENGTH) {
|
||||
await bot.api.sendMessage(numericId, text);
|
||||
} else {
|
||||
for (let i = 0; i < text.length; i += MAX_LENGTH) {
|
||||
await bot.api.sendMessage(numericId, text.slice(i, i + MAX_LENGTH));
|
||||
}
|
||||
}
|
||||
logger.info({ chatId, length: text.length }, "Telegram message sent");
|
||||
} catch (err) {
|
||||
logger.error({ chatId, err }, "Failed to send Telegram message");
|
||||
}
|
||||
}
|
||||
|
||||
export async function setTelegramTyping(chatId: string): Promise<void> {
|
||||
if (!bot) return;
|
||||
try {
|
||||
const numericId = chatId.replace(/^tg:/, "");
|
||||
await bot.api.sendChatAction(numericId, "typing");
|
||||
} catch (err) {
|
||||
logger.debug({ chatId, err }, "Failed to send Telegram typing indicator");
|
||||
}
|
||||
}
|
||||
|
||||
export function isTelegramConnected(): boolean {
|
||||
return bot !== null;
|
||||
}
|
||||
@@ -315,120 +344,140 @@ export function stopTelegram(): void {
|
||||
if (bot) {
|
||||
bot.stop();
|
||||
bot = null;
|
||||
callbacks = null;
|
||||
logger.info("Telegram bot stopped");
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Key differences from WhatsApp message handling:
|
||||
- No `onMessage` callback — messages are stored to DB and the existing message loop picks them up
|
||||
- Registration check uses `getAllRegisteredGroups()` from `db.ts` directly
|
||||
- Trigger matching is handled by `startMessageLoop()` / `processGroupMessages()`, not the Telegram module
|
||||
|
||||
### Step 4: Update Main Application
|
||||
|
||||
Modify `src/index.ts`:
|
||||
|
||||
1. Add imports at the top:
|
||||
1. **Add imports** at the top:
|
||||
|
||||
```typescript
|
||||
import {
|
||||
connectTelegram,
|
||||
sendTelegramMessage,
|
||||
isTelegramConnected,
|
||||
setTelegramTyping,
|
||||
stopTelegram,
|
||||
} from "./telegram.js";
|
||||
import { TELEGRAM_BOT_TOKEN, TELEGRAM_ONLY } from "./config.js";
|
||||
```
|
||||
|
||||
2. Update `sendMessage` function to route by channel. Find the `sendMessage` function and replace it with:
|
||||
2. **Update `sendMessage` function** to route Telegram messages. Find the `sendMessage` function and add a `tg:` prefix check before the WhatsApp path:
|
||||
|
||||
```typescript
|
||||
async function sendMessage(jid: string, text: string): Promise<void> {
|
||||
// Route Telegram messages directly (no outgoing queue needed)
|
||||
if (jid.startsWith("tg:")) {
|
||||
await sendTelegramMessage(jid, text);
|
||||
} else {
|
||||
try {
|
||||
await sock.sendMessage(jid, { text });
|
||||
logger.info({ jid, length: text.length }, "Message sent");
|
||||
} catch (err) {
|
||||
logger.error({ jid, err }, "Failed to send message");
|
||||
}
|
||||
return;
|
||||
}
|
||||
|
||||
// WhatsApp path (with outgoing queue for reconnection)
|
||||
if (!waConnected) {
|
||||
outgoingQueue.push({ jid, text });
|
||||
logger.info({ jid, length: text.length, queueSize: outgoingQueue.length }, 'WA disconnected, message queued');
|
||||
return;
|
||||
}
|
||||
try {
|
||||
await sock.sendMessage(jid, { text });
|
||||
logger.info({ jid, length: text.length }, 'Message sent');
|
||||
} catch (err) {
|
||||
outgoingQueue.push({ jid, text });
|
||||
logger.warn({ jid, err, queueSize: outgoingQueue.length }, 'Failed to send, message queued');
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
3. Update `main()` function. Find the `main()` function and update it to support Telegram. Add this before the `connectWhatsApp()` call:
|
||||
3. **Update `setTyping` function** to route Telegram typing indicators:
|
||||
|
||||
```typescript
|
||||
const hasTelegram = !!TELEGRAM_BOT_TOKEN;
|
||||
|
||||
if (hasTelegram) {
|
||||
await connectTelegram(TELEGRAM_BOT_TOKEN, {
|
||||
onMessage: async (msg, group) => {
|
||||
// Get messages since last agent interaction for context
|
||||
const sinceTimestamp = lastAgentTimestamp[msg.chat_jid] || "";
|
||||
const missedMessages = getMessagesSince(
|
||||
msg.chat_jid,
|
||||
sinceTimestamp,
|
||||
ASSISTANT_NAME,
|
||||
);
|
||||
|
||||
const lines = missedMessages.map((m) => {
|
||||
const escapeXml = (s: string) =>
|
||||
s
|
||||
.replace(/&/g, "&")
|
||||
.replace(/</g, "<")
|
||||
.replace(/>/g, ">")
|
||||
.replace(/"/g, """);
|
||||
return `<message sender="${escapeXml(m.sender_name)}" time="${m.timestamp}">${escapeXml(m.content)}</message>`;
|
||||
});
|
||||
const prompt = `<messages>\n${lines.join("\n")}\n</messages>`;
|
||||
|
||||
const group = registeredGroups[msg.chat_jid];
|
||||
const isMain = group.folder === MAIN_GROUP_FOLDER;
|
||||
|
||||
const output = await runContainerAgent(group, {
|
||||
prompt,
|
||||
sessionId: sessions[group.folder],
|
||||
groupFolder: group.folder,
|
||||
chatJid: msg.chat_jid,
|
||||
isMain,
|
||||
isScheduledTask: false,
|
||||
});
|
||||
|
||||
if (output.newSessionId) {
|
||||
sessions[group.folder] = output.newSessionId;
|
||||
saveJson(path.join(DATA_DIR, "sessions.json"), sessions);
|
||||
}
|
||||
|
||||
lastAgentTimestamp[msg.chat_jid] = msg.timestamp;
|
||||
saveState();
|
||||
|
||||
return output.status === "success" ? output.result : null;
|
||||
},
|
||||
getRegisteredGroups: () => registeredGroups,
|
||||
});
|
||||
async function setTyping(jid: string, isTyping: boolean): Promise<void> {
|
||||
if (jid.startsWith("tg:")) {
|
||||
if (isTyping) await setTelegramTyping(jid);
|
||||
return;
|
||||
}
|
||||
try {
|
||||
await sock.sendPresenceUpdate(isTyping ? 'composing' : 'paused', jid);
|
||||
} catch (err) {
|
||||
logger.debug({ jid, err }, 'Failed to update typing status');
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
4. Wrap the `connectWhatsApp()` call to support Telegram-only mode. Replace:
|
||||
4. **Update `main()` function**. Add Telegram startup before `connectWhatsApp()` and wrap WhatsApp in a `TELEGRAM_ONLY` check:
|
||||
|
||||
```typescript
|
||||
await connectWhatsApp();
|
||||
async function main(): Promise<void> {
|
||||
ensureContainerSystemRunning();
|
||||
initDatabase();
|
||||
logger.info('Database initialized');
|
||||
loadState();
|
||||
|
||||
// Graceful shutdown handlers
|
||||
const shutdown = async (signal: string) => {
|
||||
logger.info({ signal }, 'Shutdown signal received');
|
||||
stopTelegram();
|
||||
await queue.shutdown(10000);
|
||||
process.exit(0);
|
||||
};
|
||||
process.on('SIGTERM', () => shutdown('SIGTERM'));
|
||||
process.on('SIGINT', () => shutdown('SIGINT'));
|
||||
|
||||
// Start Telegram bot if configured (independent of WhatsApp)
|
||||
const hasTelegram = !!TELEGRAM_BOT_TOKEN;
|
||||
if (hasTelegram) {
|
||||
await connectTelegram(TELEGRAM_BOT_TOKEN);
|
||||
}
|
||||
|
||||
if (!TELEGRAM_ONLY) {
|
||||
await connectWhatsApp();
|
||||
} else {
|
||||
// Telegram-only mode: start all services that WhatsApp's connection.open normally starts
|
||||
startSchedulerLoop({
|
||||
registeredGroups: () => registeredGroups,
|
||||
getSessions: () => sessions,
|
||||
queue,
|
||||
onProcess: (groupJid, proc, containerName, groupFolder) =>
|
||||
queue.registerProcess(groupJid, proc, containerName, groupFolder),
|
||||
sendMessage,
|
||||
assistantName: ASSISTANT_NAME,
|
||||
});
|
||||
startIpcWatcher();
|
||||
queue.setProcessMessagesFn(processGroupMessages);
|
||||
recoverPendingMessages();
|
||||
startMessageLoop();
|
||||
logger.info(
|
||||
`NanoClaw running (Telegram-only, trigger: @${ASSISTANT_NAME})`,
|
||||
);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
With:
|
||||
Note: When running alongside WhatsApp, the `connection.open` handler in `connectWhatsApp()` already starts the scheduler, IPC watcher, queue, and message loop — no duplication needed.
|
||||
|
||||
5. **Update `getAvailableGroups` function** to include Telegram chats. The current filter only shows WhatsApp groups (`@g.us`). Update it to also include `tg:` chats so the agent can discover and register Telegram chats via IPC:
|
||||
|
||||
```typescript
|
||||
if (!TELEGRAM_ONLY) {
|
||||
await connectWhatsApp();
|
||||
} else {
|
||||
// Telegram-only mode: start scheduler and IPC without WhatsApp
|
||||
startSchedulerLoop({
|
||||
sendMessage,
|
||||
registeredGroups: () => registeredGroups,
|
||||
getSessions: () => sessions,
|
||||
});
|
||||
startIpcWatcher();
|
||||
logger.info(
|
||||
`NanoClaw running (Telegram-only, trigger: @${ASSISTANT_NAME})`,
|
||||
);
|
||||
function getAvailableGroups(): AvailableGroup[] {
|
||||
const chats = getAllChats();
|
||||
const registeredJids = new Set(Object.keys(registeredGroups));
|
||||
|
||||
return chats
|
||||
.filter((c) => c.jid !== '__group_sync__' && (c.jid.endsWith('@g.us') || c.jid.startsWith('tg:')))
|
||||
.map((c) => ({
|
||||
jid: c.jid,
|
||||
name: c.name,
|
||||
lastActivity: c.last_message_time,
|
||||
isRegistered: registeredJids.has(c.jid),
|
||||
}));
|
||||
}
|
||||
```
|
||||
|
||||
@@ -443,44 +492,47 @@ TELEGRAM_BOT_TOKEN=YOUR_BOT_TOKEN_HERE
|
||||
# TELEGRAM_ONLY=true
|
||||
```
|
||||
|
||||
**Important**: After modifying `.env`, sync to the container environment:
|
||||
|
||||
```bash
|
||||
cp .env data/env/env
|
||||
```
|
||||
|
||||
The container reads environment from `data/env/env`, not `.env` directly.
|
||||
|
||||
### Step 6: Register a Telegram Chat
|
||||
|
||||
After installing and starting the bot, tell the user:
|
||||
|
||||
> 1. Send `/chatid` to your bot (in private chat or in a group)
|
||||
> 2. Copy the chat ID (e.g., `tg:123456789` or `tg:-1001234567890`)
|
||||
> 3. I'll add it to registered_groups.json
|
||||
> 3. I'll register it for you
|
||||
|
||||
Then update `data/registered_groups.json`:
|
||||
Registration uses the `registerGroup()` function in `src/index.ts`, which writes to SQLite and creates the group folder structure. Call it like this (or add a one-time script):
|
||||
|
||||
For private chat:
|
||||
```typescript
|
||||
// For private chat (main group):
|
||||
registerGroup("tg:123456789", {
|
||||
name: "Personal",
|
||||
folder: "main",
|
||||
trigger: `@${ASSISTANT_NAME}`,
|
||||
added_at: new Date().toISOString(),
|
||||
requiresTrigger: false, // main group responds to all messages
|
||||
});
|
||||
|
||||
```json
|
||||
{
|
||||
"tg:123456789": {
|
||||
"name": "Personal",
|
||||
"folder": "main",
|
||||
"trigger": "@Andy",
|
||||
"added_at": "2026-02-05T12:00:00.000Z"
|
||||
}
|
||||
}
|
||||
// For group chat (note negative ID for Telegram groups):
|
||||
registerGroup("tg:-1001234567890", {
|
||||
name: "My Telegram Group",
|
||||
folder: "telegram-group",
|
||||
trigger: `@${ASSISTANT_NAME}`,
|
||||
added_at: new Date().toISOString(),
|
||||
requiresTrigger: true, // only respond when triggered
|
||||
});
|
||||
```
|
||||
|
||||
For group chat (note the negative ID for groups):
|
||||
The `RegisteredGroup` type requires a `trigger` string field and has an optional `requiresTrigger` boolean (defaults to `true`). Set `requiresTrigger: false` for chats that should respond to all messages.
|
||||
|
||||
```json
|
||||
{
|
||||
"tg:-1001234567890": {
|
||||
"name": "My Telegram Group",
|
||||
"folder": "telegram-group",
|
||||
"trigger": "@Andy",
|
||||
"added_at": "2026-02-05T12:00:00.000Z",
|
||||
"respondToAll": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Set `respondToAll: true` if you want the bot to respond to all messages in that chat (not just when @mentioned or triggered).
|
||||
Alternatively, if the agent is already running in the main group, it can register new groups via IPC using the `register_group` task type.
|
||||
|
||||
### Step 7: Build and Restart
|
||||
|
||||
@@ -511,8 +563,10 @@ Tell the user:
|
||||
If user wants Telegram-only:
|
||||
|
||||
1. Set `TELEGRAM_ONLY=true` in `.env`
|
||||
2. The WhatsApp connection code is automatically skipped
|
||||
3. Optionally remove `@whiskeysockets/baileys` dependency (but it's harmless to keep)
|
||||
2. Run `cp .env data/env/env` to sync to container
|
||||
3. The WhatsApp connection code is automatically skipped
|
||||
4. All services (scheduler, IPC watcher, queue, message loop) start independently
|
||||
5. Optionally remove `@whiskeysockets/baileys` dependency (but it's harmless to keep)
|
||||
|
||||
## Features
|
||||
|
||||
@@ -524,10 +578,13 @@ If user wants Telegram-only:
|
||||
### Trigger Options
|
||||
|
||||
The bot responds when:
|
||||
1. Message is in the main chat (folder: "main")
|
||||
2. Chat has `respondToAll: true` in registered_groups.json
|
||||
3. Bot is @mentioned using native Telegram mention (e.g., @your_bot_username)
|
||||
4. Message matches TRIGGER_PATTERN (e.g., starts with @Andy)
|
||||
1. Chat has `requiresTrigger: false` in its registration (e.g., main group)
|
||||
2. Bot is @mentioned in Telegram (translated to TRIGGER_PATTERN automatically)
|
||||
3. Message matches TRIGGER_PATTERN directly (e.g., starts with @Andy)
|
||||
|
||||
Telegram @mentions (e.g., `@andy_ai_bot`) are automatically translated: if the bot is @mentioned and the message doesn't already match TRIGGER_PATTERN, the trigger prefix is prepended before storing. This ensures @mentioning the bot always triggers a response.
|
||||
|
||||
**Group Privacy**: The bot must have Group Privacy disabled in BotFather to see non-mention messages in groups. See Prerequisites step 4.
|
||||
|
||||
### Commands
|
||||
|
||||
@@ -539,11 +596,18 @@ The bot responds when:
|
||||
### Bot not responding
|
||||
|
||||
Check:
|
||||
1. `TELEGRAM_BOT_TOKEN` is set in `.env`
|
||||
2. Chat is registered in `data/registered_groups.json` with `tg:` prefix
|
||||
3. For non-main chats: message includes trigger or @mention
|
||||
1. `TELEGRAM_BOT_TOKEN` is set in `.env` AND synced to `data/env/env`
|
||||
2. Chat is registered in SQLite (check with: `sqlite3 store/messages.db "SELECT * FROM registered_groups WHERE jid LIKE 'tg:%'"`)
|
||||
3. For non-main chats: message includes trigger pattern
|
||||
4. Service is running: `launchctl list | grep nanoclaw`
|
||||
|
||||
### Bot only responds to @mentions in groups
|
||||
|
||||
The bot has Group Privacy enabled (default). It can only see messages that @mention it or are commands. To fix:
|
||||
1. Open `@BotFather` in Telegram
|
||||
2. `/mybots` > select bot > **Bot Settings** > **Group Privacy** > **Turn off**
|
||||
3. Remove and re-add the bot to the group (required for the change to take effect)
|
||||
|
||||
### Getting chat ID
|
||||
|
||||
If `/chatid` doesn't work:
|
||||
@@ -566,9 +630,12 @@ To remove Telegram integration:
|
||||
|
||||
1. Delete `src/telegram.ts`
|
||||
2. Remove Telegram imports from `src/index.ts`
|
||||
3. Remove `sendTelegramMessage` logic from `sendMessage()` function
|
||||
4. Remove `connectTelegram()` call from `main()`
|
||||
5. Remove `storeMessageDirect` from `src/db.ts`
|
||||
6. Remove Telegram config from `src/config.ts`
|
||||
7. Uninstall: `npm uninstall grammy`
|
||||
8. Rebuild: `npm run build && launchctl kickstart -k gui/$(id -u)/com.nanoclaw`
|
||||
3. Remove `sendTelegramMessage` / `setTelegramTyping` routing from `sendMessage()` and `setTyping()` functions
|
||||
4. Remove `connectTelegram()` / `stopTelegram()` calls from `main()`
|
||||
5. Remove `TELEGRAM_ONLY` conditional in `main()`
|
||||
6. Revert `getAvailableGroups()` filter to only include `@g.us` chats
|
||||
7. Remove `storeMessageDirect` from `src/db.ts`
|
||||
8. Remove Telegram config (`TELEGRAM_BOT_TOKEN`, `TELEGRAM_ONLY`) from `src/config.ts`
|
||||
9. Remove Telegram registrations from SQLite: `sqlite3 store/messages.db "DELETE FROM registered_groups WHERE jid LIKE 'tg:%'"`
|
||||
10. Uninstall: `npm uninstall grammy`
|
||||
11. Rebuild: `npm run build && launchctl kickstart -k gui/$(id -u)/com.nanoclaw`
|
||||
|
||||
Reference in New Issue
Block a user