wolli 0.0.1 → 0.0.3

package/built-in/plugins/telegram/README.md

@@ -0,0 +1,153 @@
+# Telegram
+
+Connect a wolli agent to Telegram. The bot runs over Telegram's long-polling API,
+gives each chat its own wolli session, and replies in place. Setup is one message to
+[@BotFather](https://t.me/BotFather) plus a single token prompt — no public URL or
+TLS is required.
+
+## How the bot behaves
+
+Before setup, here's the part most people want to know: this bot answers **every
+text message it receives**. There is no `@mention` gate.
+
+| Context | Behavior |
+|---------|----------|
+| **Private chats** | Responds to every text message. |
+| **Group chats** | Responds to every text message it can see in any chat. No `@mention` required. Scope where it listens with `allowedChatIds`. |
+| **Its own messages** | Ignored. The bot skips messages it sent itself, so it can't loop. |
+| **Non-text messages** | Skipped. Photos, stickers, voice, and other media are not handled — only text messages reach the agent. |
+| **Slash commands** | `/new`, `/status`, `/help` are handled locally and never sent to the model (see [Commands](#commands)). |
+
+While a turn runs, the bot shows Telegram's **typing…** indicator and re-sends it
+every ~4 seconds (Telegram clears the state on its own) until the reply lands.
+
+Replies are chunked at **4096 characters** (Telegram's per-message limit) and each
+chunk is sent with the configured **parse mode** (`MarkdownV2` by default). Telegram,
+unlike Discord, needs a parse mode to render formatting — and if it rejects a chunk's
+formatting, that chunk is **re-sent as plain text**, so a stray markdown character
+never silently drops the reply.
+
+If a new message arrives while the agent is mid-reply, it is **queued as a follow-up**
+and answered after the current turn finishes — it does not interrupt the in-flight
+response.
+
+## Commands
+
+These commands are registered as the bot's command menu via BotFather on startup and
+are handled by the integration directly, not forwarded to the model:
+
+| Command | Action |
+|---------|--------|
+| `/new` | Start a fresh session for this chat. The new session becomes the active one; the previous session stays addressable but new messages route to the new one. |
+| `/status` | Show the current session name and the model used in the last reply. |
+| `/help` | List the available commands. |
+
+Any other `/command` returns `Unknown command: /<name>. Try /help.`
+
+## Session model
+
+Each chat gets its **own wolli session**, bound by a `telegram:chat` tag:
+
+- **Inbound** — an incoming message is routed to the session tagged for its chat. If
+  none exists yet, one is created and tagged on the spot. Histories never bleed across
+  chats, and two chats can run in parallel.
+- **Outbound** — the reply rides the producing session's tag, so the answer always
+  returns to the chat that started the turn — not to whoever messaged most recently.
+
+`/new` creates a fresh session tagged for the chat; because it becomes the newest
+match for that tag, subsequent messages route to it.
+
+## Setup
+
+### 1. Create a bot with BotFather
+
+Open [@BotFather](https://t.me/BotFather) in Telegram and send `/newbot`. Pick a name
+and a username; BotFather replies with a **bot token** like `123456:ABC-DEF...`. Copy
+it — you'll paste it in the next step. Keep it secret.
+
+### 2. Install and onboard in wolli
+
+```bash
+wolli <agent> plugins install ./built-in/plugins/telegram
+```
+
+In an interactive terminal this runs onboarding immediately: it prints the BotFather
+walkthrough, then prompts you to **paste the bot token**. Paste the token from step 1.
+Wolli verifies it with a live `getMe()` call and stores it. That single token is the
+only value you enter.
+
+If you installed non-interactively, onboard later with:
+
+```bash
+wolli <agent> plugins configure telegram
+```
+
+### 3. Restart the agent
+
+```bash
+wolli restart <agent>
+```
+
+This starts the long-poll producer that connects to Telegram. After onboarding a
+fresh integration its producer starts only on the next daemon start, so restart the
+agent once for the bot to come online and begin responding.
+
+## Configuration reference
+
+Configuration lives per agent in `~/.wolli/agents/<name>/integrations.json` under
+`telegram.default`:
+
+```json
+{
+  "telegram": {
+    "default": {
+      "botToken": "123456:ABC-DEF...",
+      "allowedChatIds": [123456789],
+      "parseMode": "MarkdownV2"
+    }
+  }
+}
+```
+
+| Field | Required | Default | Purpose |
+|-------|----------|---------|---------|
+| `botToken` | Yes | — | The BotFather token. Onboarding stores it raw; a `$ENV` / `!cmd` reference placed here by hand also resolves on read. |
+| `allowedChatIds` | No | *(any chat)* | Allowlist of chat IDs the bot will respond in. Empty or absent accepts **any** chat (logged as a warning at startup). |
+| `parseMode` | No | `MarkdownV2` | Outbound formatting: `"MarkdownV2"`, `"HTML"`, or `"plain"` (disables parse mode). |
+
+Telegram chat IDs are **numbers** — keep them unquoted in JSON, unlike Discord's
+quoted snowflakes.
+
+`allowedChatIds` and `parseMode` are not asked during onboarding — edit
+`integrations.json` to set them.
+
+## Not supported
+
+The bot is deliberately focused on text chat. It does not provide:
+
+- A durable cursor — on start it calls `deleteWebhook({ drop_pending_updates: true })`,
+  so a restart never replays a backlog but also drops messages sent while the bot was
+  offline.
+- Inbound media or images — only text messages are handled.
+- Webhook mode — the transport is long polling only.
+- Callback queries or inline keyboards.
+- Outbound rate-limit throttling.
+- Mention-gating, or per-user / per-role allowlists — chat-level `allowedChatIds` is
+  the only scope control.
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---------|-----|
+| No reply right after the first install/onboard | Restart the agent (`wolli restart <agent>`) so the long-poll producer starts. |
+| Bot ignores messages sent while it was offline | Expected — `deleteWebhook({ drop_pending_updates: true })` clears the backlog on start. The bot only sees messages that arrive while it is running. |
+| Formatting looks broken, or a message seems to drop | A chunk that fails parse-mode parsing is re-sent as plain text. Set `parseMode: "plain"` to disable formatting entirely. |
+
+## Security
+
+- `allowedChatIds` is the only access gate. With it empty, **any** chat is accepted —
+  set it to lock the bot to known chats.
+- There is no per-user gate beyond that. Anyone who can post in an allowed chat can
+  drive the agent, so keep the bot in trusted chats.
+- The bot token grants full control of the bot account — never commit it or share it.
+  Wolli writes `integrations.json` with mode `0600`.

package/built-in/plugins/telegram/index.ts

@@ -0,0 +1,311 @@
+/**
+ * Telegram chat integration — the transport half (self-contained package).
+ *
+ * This integration faces the network, holds the bot token, and emits a `message`
+ * event per inbound Telegram message. It does not touch sessions or the agent; the
+ * paired extension (`telegram-chat.ts`, declared under `wolli.extensions`) maps those
+ * events into a chat loop and is resolved in place by the package manager. See
+ * `INTEGRATION.md` for the transport-vs-mapping split.
+ *
+ * Transport is grammY long polling (`@grammyjs/runner`'s `run`), so no public URL
+ * or TLS is needed. The package brings its OWN grammy + @grammyjs/runner deps.
+ *
+ * ## Install + configure
+ *
+ *   wolli <agent> plugins install ./built-in/plugins/telegram
+ *   # then paste the BotFather token into the guided prompt — that's it.
+ *
+ * Onboarding asks for the BotFather token directly, verifies it with a live `getMe()`,
+ * and stores the raw token in `~/.wolli/agents/<name>/integrations.json`:
+ *
+ *   { "telegram": { "default": { "botToken": "123456:ABC..." } } }
+ *
+ * `botToken` is still resolved on read, so a `$ENV` / `!cmd` reference placed there by
+ * hand keeps working — onboarding just stores the literal token. `allowedChatIds` is an
+ * allowlist — empty/absent means "allow any chat" (logged as a warning). `parseMode`
+ * is how outbound text is formatted (default `"MarkdownV2"`; `"plain"` disables it).
+ * `allowedChatIds`/`parseMode` are not asked during onboarding — edit integrations.json
+ * to set them.
+ *
+ * ## Known v1 limitations
+ *  - No durable cursor: `run()` calls `deleteWebhook({ drop_pending_updates: true })`
+ *    on start, so a restart never replays a backlog — but it also drops messages
+ *    sent while the bot was offline. Acceptable for v1.
+ *  - No inbound media/images, no webhook mode, no callback queries / inline keyboards.
+ *  - No outbound throttling (add `@grammyjs/transformer-throttler` if rate limits bite).
+ */
+
+import { run } from "@grammyjs/runner";
+// The integration types are host-provided via the loader's VIRTUAL_MODULES / aliases, so
+// @opsyhq/wolli is a peerDependency, not a dependency.
+import type { IntegrationOnboardContext, IntegrationsAPI } from "@opsyhq/wolli";
+import { Bot, GrammyError } from "grammy";
+import { Type } from "typebox";
+
+/** Telegram caps a single message at 4096 UTF-16 code units. */
+const TELEGRAM_MAX_LENGTH = 4096;
+
+/** BotFather walkthrough shown on the onboarding guide screen. */
+const ONBOARD_GUIDE = [
+	"## Connect Telegram",
+	"",
+	"1. Open [@BotFather](https://t.me/BotFather) in Telegram and send `/newbot`.",
+	"2. Pick a name and username; BotFather replies with a **bot token** like",
+	"   `123456:ABC-DEF...`.",
+	"3. Copy that token and paste it on the next screen.",
+	"",
+	"Wolli verifies the token and stores it for this agent.",
+].join("\n");
+
+type ParseMode = "MarkdownV2" | "HTML" | "plain";
+
+interface TelegramAccount {
+	botToken: string;
+	allowedChatIds?: number[];
+	parseMode?: ParseMode;
+}
+
+/**
+ * One `Bot` instance per token, shared between the long-poll producer (`run`) and
+ * the request/response actions so they reuse a single `bot.api`. A `Bot` is lazy —
+ * constructing it makes no network call — so this is safe to build on first use.
+ */
+const bots = new Map<string, Bot>();
+function getBot(token: string): Bot {
+	let bot = bots.get(token);
+	if (!bot) {
+		bot = new Bot(token);
+		bots.set(token, bot);
+	}
+	return bot;
+}
+
+/**
+ * Split `text` into ≤4096-code-unit chunks without cutting a surrogate pair. JS
+ * string length is already in UTF-16 code units, which is exactly Telegram's unit.
+ */
+function chunkText(text: string, max = TELEGRAM_MAX_LENGTH): string[] {
+	if (text.length <= max) return [text];
+	const chunks: string[] = [];
+	let i = 0;
+	while (i < text.length) {
+		let end = Math.min(i + max, text.length);
+		if (end < text.length) {
+			// If the boundary lands on a high surrogate, push it into the next chunk.
+			const code = text.charCodeAt(end - 1);
+			if (code >= 0xd800 && code <= 0xdbff) end -= 1;
+		}
+		chunks.push(text.slice(i, end));
+		i = end;
+	}
+	return chunks;
+}
+
+/** A Telegram API error caused by parse-mode entity parsing (not e.g. a bad chat id). */
+function isParseError(err: unknown): boolean {
+	return err instanceof GrammyError && err.error_code === 400 && /can't parse|can't find|entit/i.test(err.description);
+}
+
+/**
+ * Send one already-chunked message. Tries the configured parse mode first and, if
+ * Telegram rejects the formatting, resends the same text as plain (no parse mode) so
+ * a stray `*` or `_` from the model never silently drops the reply.
+ */
+async function sendChunk(
+	bot: Bot,
+	chatId: number,
+	text: string,
+	parseMode: ParseMode,
+	replyToMessageId: number | undefined,
+): Promise<number> {
+	const reply = replyToMessageId ? { reply_parameters: { message_id: replyToMessageId } } : {};
+	try {
+		const other = parseMode === "plain" ? { ...reply } : { parse_mode: parseMode, ...reply };
+		const sent = await bot.api.sendMessage(chatId, text, other);
+		return sent.message_id;
+	} catch (err) {
+		if (parseMode === "plain" || !isParseError(err)) throw err;
+		const sent = await bot.api.sendMessage(chatId, text, { ...reply });
+		return sent.message_id;
+	}
+}
+
+/**
+ * Guided setup: show the BotFather walkthrough, collect the bot token directly, verify
+ * it with a live `getMe()`, and return the raw token to store. Returns `undefined`
+ * (cancelled) if the user dismisses a step, submits nothing, or verification fails.
+ */
+async function onboard(ctx: IntegrationOnboardContext): Promise<{ botToken: string } | undefined> {
+	// Guide text — onboarding renders over the wire (the daemon is the single writer), so the BotFather
+	// walkthrough prints as a notification ahead of the token prompt rather than a custom guide screen.
+	ctx.ui.notify(ONBOARD_GUIDE, "info");
+
+	// undefined = cancelled. The pasted value is the raw token itself, not a reference.
+	const entered = await ctx.ui.input("Paste the bot token from BotFather");
+	if (entered === undefined) return undefined; // cancelled
+	const token = entered.trim();
+	if (!token) {
+		ctx.ui.notify("No token entered.", "error");
+		return undefined;
+	}
+
+	try {
+		const me = await new Bot(token).api.getMe();
+		ctx.ui.notify(`Verified bot @${me.username}.`, "info");
+	} catch (err) {
+		ctx.ui.notify(`Could not verify the token: ${err instanceof Error ? err.message : String(err)}`, "error");
+		return undefined;
+	}
+
+	return { botToken: token };
+}
+
+export default function (wolli: IntegrationsAPI) {
+	wolli.registerIntegration({
+		name: "telegram",
+		account: Type.Object({
+			/** BotFather token. Onboarding stores it raw; a `$ENV`/`!cmd` reference also works. */
+			botToken: Type.String(),
+			/** Allowlist of chat ids. Empty/absent = allow all (logged as a warning). */
+			allowedChatIds: Type.Optional(Type.Array(Type.Number())),
+			/** Outbound formatting; `"plain"` disables parse mode. */
+			parseMode: Type.Optional(
+				Type.Union([Type.Literal("MarkdownV2"), Type.Literal("HTML"), Type.Literal("plain")]),
+			),
+		}),
+		events: {
+			message: Type.Object({
+				chatId: Type.Number(),
+				messageId: Type.Number(),
+				text: Type.String(),
+				from: Type.Object({
+					id: Type.Number(),
+					username: Type.Optional(Type.String()),
+					firstName: Type.Optional(Type.String()),
+				}),
+				chatType: Type.String(),
+				date: Type.Number(),
+			}),
+		},
+		onboard,
+		actions: {
+			sendMessage: {
+				description: "Send a text message to a chat (chunked at 4096, with plain-text fallback).",
+				parameters: Type.Object({
+					chatId: Type.Number(),
+					text: Type.String(),
+					replyToMessageId: Type.Optional(Type.Number()),
+				}),
+				execute: async (params, ctx) => {
+					const { chatId, text, replyToMessageId } = params as {
+						chatId: number;
+						text: string;
+						replyToMessageId?: number;
+					};
+					const account = ctx.account as TelegramAccount;
+					const parseMode = account.parseMode ?? "MarkdownV2";
+					const bot = getBot(account.botToken);
+
+					const messageIds: number[] = [];
+					// Reply-to applies only to the first chunk; later chunks just continue.
+					let replyTo = replyToMessageId;
+					for (const chunk of chunkText(text)) {
+						messageIds.push(await sendChunk(bot, chatId, chunk, parseMode, replyTo));
+						replyTo = undefined;
+					}
+					return { messageIds };
+				},
+			},
+			sendChatAction: {
+				description: "Show a chat action (e.g. the 'typing…' indicator).",
+				parameters: Type.Object({
+					chatId: Type.Number(),
+					action: Type.String(),
+				}),
+				execute: async (params, ctx) => {
+					const { chatId, action } = params as { chatId: number; action: string };
+					const account = ctx.account as TelegramAccount;
+					const bot = getBot(account.botToken);
+					// grammY types `action` as a union; the runtime accepts any valid string.
+					await bot.api.sendChatAction(chatId, action as "typing");
+					return { ok: true };
+				},
+			},
+			setCommands: {
+				description: "Register the bot's slash-command menu (BotFather command list).",
+				parameters: Type.Object({
+					commands: Type.Array(
+						Type.Object({
+							command: Type.String(),
+							description: Type.String(),
+						}),
+					),
+				}),
+				execute: async (params, ctx) => {
+					const { commands } = params as { commands: { command: string; description: string }[] };
+					const account = ctx.account as TelegramAccount;
+					const bot = getBot(account.botToken);
+					await bot.api.setMyCommands(commands);
+					return { ok: true };
+				},
+			},
+		},
+		run(ctx) {
+			const account = ctx.account as TelegramAccount;
+			const { botToken, allowedChatIds } = account;
+			const allowAll = !allowedChatIds || allowedChatIds.length === 0;
+			if (allowAll) {
+				console.warn("[telegram] no allowedChatIds configured — accepting messages from ANY chat.");
+			}
+
+			const bot = getBot(botToken);
+
+			bot.on("message:text", (c) => {
+				// Ignore our own messages and anything outside the allowlist.
+				if (c.from?.id === c.me.id) return;
+				const chatId = c.chat.id;
+				if (!allowAll && !allowedChatIds?.includes(chatId)) return;
+
+				ctx.emit("message", {
+					chatId,
+					messageId: c.msg.message_id,
+					text: c.msg.text,
+					from: {
+						id: c.from?.id ?? 0,
+						username: c.from?.username,
+						firstName: c.from?.first_name,
+					},
+					chatType: c.chat.type,
+					date: c.msg.date,
+				});
+			});
+
+			// Swallow producer-side errors so a transient poll failure can't crash the host.
+			bot.catch((err) => {
+				console.error("[telegram] bot error:", err.message);
+			});
+
+			// Fire-and-forget startup: drop any webhook + backlog, then start long polling.
+			// The runner never resolves, so we must NOT await it.
+			let runner: ReturnType<typeof run> | undefined;
+			void bot.api
+				.deleteWebhook({ drop_pending_updates: true })
+				.then(() => {
+					if (ctx.signal.aborted) return;
+					runner = run(bot);
+				})
+				.catch((err) => {
+					console.error("[telegram] failed to start long polling:", err instanceof Error ? err.message : err);
+				});
+
+			// Belt and suspenders: stop the runner on abort and via the returned disposer.
+			// The stop-before-start swap on reload relies on this to avoid Telegram's 409
+			// ("two pollers on one token") conflict.
+			const dispose = () => {
+				if (runner?.isRunning()) void runner.stop();
+			};
+			ctx.signal.addEventListener("abort", dispose);
+			return dispose;
+		},
+	});
+}

package/built-in/plugins/telegram/package.json

@@ -0,0 +1,17 @@
+{
+	"name": "wolli-integration-telegram",
+	"private": true,
+	"version": "1.0.0",
+	"type": "module",
+	"wolli": {
+		"integrations": ["./index.ts"],
+		"extensions": ["./telegram-chat.ts"]
+	},
+	"dependencies": {
+		"grammy": "1.44.0",
+		"@grammyjs/runner": "2.0.3"
+	},
+	"peerDependencies": {
+		"@opsyhq/wolli": "*"
+	}
+}

package/built-in/plugins/telegram/telegram-chat.ts

@@ -0,0 +1,169 @@
+/**
+ * Telegram chat extension — the mapping half (paired with `index.ts`).
+ *
+ * The integration (`index.ts`) is the transport (long-poll, token, `message` events);
+ * this extension maps that transport onto a Wolli session:
+ *
+ *   - inbound:  `telegram.on("message")` routes the text into this chat's own session by
+ *               `wolli.findSessions({ "telegram:chat": <id> })` → `openSession` the match (or
+ *               `createSession` + tag a fresh one) → `session.sendUserMessage(text)`
+ *   - outbound: `wolli.on("agent_end")` reads the PRODUCING session's tag off
+ *               `ctx.session.getTags()` → final assistant text → `sendMessage`
+ *   - typing:   `agent_start`/`agent_end` toggle the Telegram "typing…" indicator
+ *   - commands: `/new`, `/status`, `/help` are handled here, not sent to the model
+ *
+ * Session binding via tags: each chat gets its OWN Wolli session, bound by a `{ "telegram:chat":
+ * <id> }` tag. `findSessions` locates (and `createSession` lazily creates) the chat's session, so two
+ * chats run in parallel and a reply returns to the chat that started the turn — located by any
+ * extension with `wolli.findSessions({ "telegram:chat": <id> })`.
+ *
+ * This file is declared under the package's `wolli.extensions` and is resolved in place by the
+ * package manager when the integration is onboarded
+ * (`wolli <agent> plugins configure telegram`); it activates on the next launch.
+ */
+
+import type { AgentMessage } from "@opsyhq/agent";
+import type { ExtensionAPI } from "@opsyhq/wolli";
+
+const TYPING_INTERVAL_MS = 4000;
+
+const COMMANDS = [
+	{ command: "new", description: "Start a fresh session" },
+	{ command: "status", description: "Show the current session and model" },
+	{ command: "help", description: "List available commands" },
+];
+
+interface TelegramMessage {
+	chatId: number;
+	messageId: number;
+	text: string;
+	from: { id: number; username?: string; firstName?: string };
+	chatType: string;
+	date: number;
+}
+
+/** Concatenate the text blocks of the last assistant message; "" for a pure tool-call turn. */
+function finalAssistantText(messages: AgentMessage[]): string {
+	for (let i = messages.length - 1; i >= 0; i--) {
+		const m = messages[i];
+		if (m.role !== "assistant") continue;
+		return m.content
+			.filter((c): c is { type: "text"; text: string } => c.type === "text")
+			.map((c) => c.text)
+			.join("")
+			.trim();
+	}
+	return "";
+}
+
+export default function (wolli: ExtensionAPI) {
+	const tg = wolli.getIntegration("telegram", "default");
+
+	// Model id from the most recent turn, surfaced by /status.
+	let lastModel: string | undefined;
+	let typingTimer: ReturnType<typeof setInterval> | undefined;
+
+	const reply = async (chatId: number, text: string): Promise<void> => {
+		await tg.call("sendMessage", { chatId, text });
+	};
+
+	// Register the BotFather slash-command menu on startup.
+	void tg.call("setCommands", { commands: COMMANDS }).catch((err) => {
+		console.error("[telegram-chat] setCommands failed:", err instanceof Error ? err.message : err);
+	});
+
+	// Slash commands are handled locally instead of being sent to the model.
+	async function handleCommand(chatId: number, text: string): Promise<void> {
+		// Strip a leading "/" and an optional "@botname" suffix (groups append it).
+		const command = text.slice(1).split(/\s+/)[0].split("@")[0].toLowerCase();
+		switch (command) {
+			case "new": {
+				// A fresh session tagged with this chat becomes the newest match, so future messages
+				// route to it (the prior session stays addressable but is no longer the newest).
+				await wolli.createSession({
+					setup: async (sessionManager) => {
+						await sessionManager.appendTags({ "telegram:chat": String(chatId) });
+					},
+				});
+				await reply(chatId, "Started a fresh session.");
+				return;
+			}
+			case "status": {
+				const matches = await wolli.findSessions({ "telegram:chat": String(chatId) });
+				const name = (matches[0] && wolli.getSession(matches[0].id)?.getSessionName()) ?? "(unnamed)";
+				const model = lastModel ?? "(unknown until first reply)";
+				await reply(chatId, `Session: ${name}\nModel: ${model}`);
+				return;
+			}
+			case "help": {
+				const lines = COMMANDS.map((c) => `/${c.command} — ${c.description}`).join("\n");
+				await reply(chatId, `Commands:\n${lines}`);
+				return;
+			}
+			default:
+				await reply(chatId, `Unknown command: /${command}. Try /help.`);
+		}
+	}
+
+	tg.on("message", async (data) => {
+		const m = data as TelegramMessage;
+
+		if (m.text.startsWith("/")) {
+			await handleCommand(m.chatId, m.text);
+			return;
+		}
+
+		// Route into this chat's own session: rehydrate the tag-bound one, or create + tag a fresh one.
+		const chatTag = { "telegram:chat": String(m.chatId) };
+		const [match] = await wolli.findSessions(chatTag);
+		const session = match
+			? await wolli.openSession(match.id)
+			: await wolli.createSession({
+					setup: async (sessionManager) => {
+						await sessionManager.appendTags(chatTag);
+					},
+				});
+
+		// followUp so a message arriving mid-stream queues cleanly instead of interrupting.
+		void session.sendUserMessage(m.text, { deliverAs: "followUp" });
+	});
+
+	// Typing indicator: kept alive on a timer while a turn runs (Telegram clears the
+	// "typing…" state after a few seconds, so it must be re-sent).
+	const stopTyping = (): void => {
+		if (typingTimer) {
+			clearInterval(typingTimer);
+			typingTimer = undefined;
+		}
+	};
+
+	wolli.on("agent_start", async (_event, ctx) => {
+		const chat = ctx.session.getTags()["telegram:chat"];
+		if (!chat) return; // not a telegram-bound session
+		const chatId = Number(chat);
+		const sendTyping = () => {
+			void tg.call("sendChatAction", { chatId, action: "typing" }).catch(() => {});
+		};
+		sendTyping();
+		stopTyping();
+		typingTimer = setInterval(sendTyping, TYPING_INTERVAL_MS);
+	});
+
+	wolli.on("agent_end", async ({ messages }, ctx) => {
+		stopTyping();
+
+		const assistantMsgs = messages as AgentMessage[];
+		for (const m of assistantMsgs) {
+			if (m.role === "assistant") lastModel = m.model;
+		}
+
+		// Reply rides the producing session's binding, so the answer returns to the chat that
+		// started this turn — not whoever messaged last.
+		const chat = ctx.session.getTags()["telegram:chat"];
+		if (!chat) return; // not a telegram-bound session
+
+		const text = finalAssistantText(assistantMsgs);
+		if (!text) return; // pure tool-call turn — nothing to send
+		await reply(Number(chat), text);
+	});
+}