@amanm/openpaw 0.1.0

package/gateway/telegram/adapter.ts

@@ -0,0 +1,290 @@
+/**
+ * Telegram channel for the OpenPaw gateway: wires a grammy `Bot` to gateway
+ * commands, per-chat message serialization, chat preferences, and streaming
+ * assistant replies via `deliverStreamingReply` and `runtime.runTurn`.
+ *
+ * Exports `createTelegramChannelAdapter` for the multi-channel gateway and
+ * `runTelegramGateway` as a standalone long-polling entrypoint.
+ */
+import { Bot } from "grammy";
+import { createGatewayContext, type OpenPawGatewayContext } from "../bootstrap";
+import type { ChannelAdapter } from "../channel-adapter";
+import {
+  getTelegramPersistenceSessionId,
+  setActiveTelegramSession,
+  startNewTelegramThread,
+} from "./active-thread-store";
+import { createTelegramMessageQueue } from "./message-queue";
+import { registerOpenPawBotCommands } from "./bot-commands";
+import {
+  firstCommandToken,
+  shouldForwardTextToAgent,
+  shouldReportUnknownOpenPawSlashCommand,
+} from "./reserved-command-filter";
+import { formatAvailableOpenPawSlashCommandsForUser } from "../slash-command-tokens";
+import { replyWithSessionsList } from "./sessions-list-reply";
+import { telegramSessionKey } from "./session-key";
+import { listTelegramSessionsForChat } from "./session-file-discovery";
+import { formatTelegramSessionLabel } from "./session-label";
+import {
+  getTelegramChatPreferences,
+  setTelegramChatPreferences,
+} from "./chat-preferences";
+import { deliverStreamingReply } from "./stream-delivery";
+
+/**
+ * Registers Telegram handlers: session management (`/new`, `/sessions`, `/resume`),
+ * display prefs (`/reasoning`, `/tool_calls`), sandbox (`/sandbox on|off`),
+ * unknown OpenPaw slash-command help,
+ * and plain text forwarded to the agent. Work for each chat/topic is serialized
+ * through the per-key message queue.
+ */
+function wireTelegramBot(bot: Bot, ctx: OpenPawGatewayContext): void {
+  const { runtime } = ctx;
+  const runNext = createTelegramMessageQueue();
+
+  bot.command("new", async (grammyCtx) => {
+    const chatId = grammyCtx.chat?.id;
+    if (chatId === undefined) {
+      return;
+    }
+    const queueKey = telegramSessionKey(grammyCtx);
+    await runNext(queueKey, async () => {
+      try {
+        await startNewTelegramThread(chatId);
+        await grammyCtx.reply("Started a new conversation.");
+      } catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        await grammyCtx.reply(`OpenPaw error: ${msg}`);
+      }
+    });
+  });
+
+  bot.command("sessions", async (grammyCtx) => {
+    const chatId = grammyCtx.chat?.id;
+    if (chatId === undefined) {
+      return;
+    }
+    const queueKey = telegramSessionKey(grammyCtx);
+    await runNext(queueKey, async () => {
+      try {
+        await replyWithSessionsList(grammyCtx, chatId);
+      } catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        await grammyCtx.reply(`OpenPaw error: ${msg}`);
+      }
+    });
+  });
+
+  bot.command("reasoning", async (grammyCtx) => {
+    const chatId = grammyCtx.chat?.id;
+    if (chatId === undefined) {
+      return;
+    }
+    const queueKey = telegramSessionKey(grammyCtx);
+    await runNext(queueKey, async () => {
+      try {
+        const arg = String(grammyCtx.match ?? "").trim().toLowerCase();
+        if (arg !== "show" && arg !== "hide") {
+          await grammyCtx.reply("Usage: /reasoning show — or — /reasoning hide");
+          return;
+        }
+        const showReasoning = arg === "show";
+        await setTelegramChatPreferences(chatId, { showReasoning });
+        await grammyCtx.reply(
+          showReasoning
+            ? "Reasoning will appear as separate messages."
+            : "Reasoning messages are hidden (session still saves them).",
+        );
+      } catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        await grammyCtx.reply(`OpenPaw error: ${msg}`);
+      }
+    });
+  });
+
+  bot.command("tool_calls", async (grammyCtx) => {
+    const chatId = grammyCtx.chat?.id;
+    if (chatId === undefined) {
+      return;
+    }
+    const queueKey = telegramSessionKey(grammyCtx);
+    await runNext(queueKey, async () => {
+      try {
+        const arg = String(grammyCtx.match ?? "").trim().toLowerCase();
+        if (arg !== "show" && arg !== "hide") {
+          await grammyCtx.reply("Usage: /tool_calls show — or — /tool_calls hide");
+          return;
+        }
+        const showToolCalls = arg === "show";
+        await setTelegramChatPreferences(chatId, { showToolCalls });
+        await grammyCtx.reply(
+          showToolCalls
+            ? "Tool call status lines will be shown."
+            : "Tool call status lines are hidden (session still saves them).",
+        );
+      } catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        await grammyCtx.reply(`OpenPaw error: ${msg}`);
+      }
+    });
+  });
+
+  bot.command("sandbox", async (grammyCtx) => {
+    const chatId = grammyCtx.chat?.id;
+    if (chatId === undefined) {
+      return;
+    }
+    const queueKey = telegramSessionKey(grammyCtx);
+    await runNext(queueKey, async () => {
+      try {
+        const arg = String(grammyCtx.match ?? "").trim().toLowerCase();
+        if (arg !== "on" && arg !== "off") {
+          await grammyCtx.reply("Usage: /sandbox on — or — /sandbox off");
+          return;
+        }
+        const sandboxRestricted = arg === "on";
+        await setTelegramChatPreferences(chatId, { sandboxRestricted });
+        if (sandboxRestricted) {
+          await grammyCtx.reply(
+            "Filesystem sandbox is on: file_editor and bash are limited to the workspace.",
+          );
+        } else {
+          await grammyCtx.reply(
+            "Filesystem sandbox is off. The agent can read/write outside the workspace and run shell commands with cwd in your home directory. Use only if you trust this chat.",
+          );
+        }
+      } catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        await grammyCtx.reply(`OpenPaw error: ${msg}`);
+      }
+    });
+  });
+
+  bot.command("resume", async (grammyCtx) => {
+    const chatId = grammyCtx.chat?.id;
+    if (chatId === undefined) {
+      return;
+    }
+    const queueKey = telegramSessionKey(grammyCtx);
+    await runNext(queueKey, async () => {
+      try {
+        const arg = String(grammyCtx.match ?? "").trim();
+        if (!/^\d+$/.test(arg)) {
+          await grammyCtx.reply("Usage: /resume 1 — use /sessions to see numbers.");
+          return;
+        }
+        const n = Number.parseInt(arg, 10);
+        if (n < 1) {
+          await grammyCtx.reply("Usage: /resume 1 — use /sessions to see numbers.");
+          return;
+        }
+        const entries = await listTelegramSessionsForChat(chatId);
+        if (entries.length === 0) {
+          await grammyCtx.reply("No saved sessions yet.");
+          return;
+        }
+        if (n > entries.length) {
+          await grammyCtx.reply(`No session ${n}. Run /sessions (1–${entries.length}).`);
+          return;
+        }
+        const chosen = entries[n - 1]!;
+        await setActiveTelegramSession(chatId, chosen.sessionId);
+        const label = formatTelegramSessionLabel(chosen.sessionId, chatId);
+        await grammyCtx.reply(`Resumed session ${n} (${label}).`);
+      } catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        await grammyCtx.reply(`OpenPaw error: ${msg}`);
+      }
+    });
+  });
+
+  bot
+    .on("message:text")
+    .filter(shouldReportUnknownOpenPawSlashCommand, async (grammyCtx) => {
+      const chatId = grammyCtx.chat?.id;
+      if (chatId === undefined) {
+        return;
+      }
+      const text = grammyCtx.message.text ?? "";
+      const queueKey = telegramSessionKey(grammyCtx);
+      const token = firstCommandToken(text) ?? "/?";
+      const available = formatAvailableOpenPawSlashCommandsForUser();
+      await runNext(queueKey, async () => {
+        await grammyCtx.reply(
+          `Unknown command ${token}. Available: ${available}.`,
+        );
+      });
+    });
+
+  bot.on("message:text").filter(shouldForwardTextToAgent, async (grammyCtx) => {
+    const text = grammyCtx.message.text;
+    if (!text?.trim()) {
+      return;
+    }
+
+    const queueKey = telegramSessionKey(grammyCtx);
+    const chatId = grammyCtx.chat?.id;
+    if (chatId === undefined) {
+      return;
+    }
+
+    const persistenceId = await getTelegramPersistenceSessionId(chatId);
+    const prefs = await getTelegramChatPreferences(chatId);
+
+    await runNext(queueKey, async () => {
+      try {
+        await deliverStreamingReply(grammyCtx, prefs, async (handlers) => {
+          await runtime.runTurn({
+            sessionId: persistenceId,
+            userText: text,
+            surface: "telegram",
+            sandboxRestricted: prefs.sandboxRestricted,
+            onTextDelta: handlers.onTextDelta,
+            onReasoningDelta: handlers.onReasoningDelta,
+            onToolStatus: handlers.onToolStatus,
+          });
+        });
+      } catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        try {
+          await grammyCtx.reply(`OpenPaw error: ${msg}`);
+        } catch {
+          // ignore double failure
+        }
+      }
+    });
+  });
+}
+
+/**
+ * Builds a {@link ChannelAdapter} that starts the Telegram bot with registered
+ * commands and long polling. Requires `channels.telegram.botToken` in config.
+ */
+export function createTelegramChannelAdapter(ctx: OpenPawGatewayContext): ChannelAdapter {
+  const token = ctx.config.channels?.telegram?.botToken;
+  if (!token) {
+    throw new Error(
+      "Telegram bot token missing. Add channels.telegram.botToken to ~/.openpaw/config.yaml",
+    );
+  }
+
+  return {
+    id: "telegram",
+    run: async () => {
+      const bot = new Bot(token);
+      await registerOpenPawBotCommands(bot);
+      wireTelegramBot(bot, ctx);
+      console.log("OpenPaw Telegram channel starting (long polling)…");
+      await bot.start();
+    },
+  };
+}
+
+/**
+ * Run only the Telegram channel (single-adapter entrypoint).
+ */
+export async function runTelegramGateway(): Promise<void> {
+  const ctx = await createGatewayContext();
+  await createTelegramChannelAdapter(ctx).run();
+}

package/gateway/telegram/assistant-markdown.ts

@@ -0,0 +1,48 @@
+/**
+ * Wraps {@link https://www.npmjs.com/package/tg-markdown-converter tg-markdown-converter}
+ * for assistant replies: CommonMark/GFM → Telegram MarkdownV2 (no post-processing).
+ */
+import { converter } from "tg-markdown-converter";
+
+/** Options passed to {@link converter} (no `splitAt`: streaming layer chunks source markdown first). */
+const TELEGRAM_MARKDOWN_CONVERTER_OPTIONS = {
+  olSeparator: ")" as const,
+  ulMarker: "-",
+  imgMarker: "🎨",
+  thematicBreak: "* * *",
+  headingEmojis: {
+    h1: '',
+    h2: '',
+    h3: '',
+    h4: '',
+    h5: '',
+    h6: '',
+  } as const,
+};
+
+/** Body to send and whether Telegram should parse it as MarkdownV2 (omit for plain text). */
+export type AssistantTelegramPayload = {
+  body: string;
+  parseMode: "MarkdownV2" | undefined;
+};
+
+/**
+ * Converts model markdown for the main assistant bubble (streaming edits and finalize).
+ * On success returns MarkdownV2; on converter failure returns plain text with no parse_mode
+ * so Telegram does not treat `_*[]()` as formatting.
+ */
+export function formatAssistantMarkdownForTelegram(markdown: string): AssistantTelegramPayload {
+  if (!markdown) {
+    return { body: markdown, parseMode: undefined };
+  }
+  try {
+    const body = converter(markdown, TELEGRAM_MARKDOWN_CONVERTER_OPTIONS);
+    return { body, parseMode: "MarkdownV2" };
+  } catch (e) {
+    console.warn(
+      "OpenPaw Telegram: MarkdownV2 conversion failed (tg-markdown-converter), sending plain text",
+      e,
+    );
+    return { body: markdown.slice(0, 4096), parseMode: undefined };
+  }
+}

package/gateway/telegram/bot-commands.ts

@@ -0,0 +1,40 @@
+import type { Bot } from "grammy";
+import { OPENPAW_SLASH_COMMAND_NAMES } from "../slash-command-tokens";
+
+const OPENPAW_COMMAND_DESCRIPTIONS: Record<(typeof OPENPAW_SLASH_COMMAND_NAMES)[number], string> =
+  {
+    new: "Start a fresh conversation",
+    sessions: "List saved sessions for this chat",
+    resume: "Resume a session by number from /sessions",
+    reasoning: "show or hide — reasoning bubbles in Telegram",
+    tool_calls: "show or hide — tool status lines in Telegram",
+    sandbox: "on or off — restrict file editor and shell to the workspace",
+  };
+
+const OPENPAW_COMMANDS = OPENPAW_SLASH_COMMAND_NAMES.map((command) => ({
+  command,
+  description: OPENPAW_COMMAND_DESCRIPTIONS[command],
+}));
+
+/**
+ * Telegram keeps separate command lists per {@link https://core.telegram.org/bots/api#botcommandscope}.
+ * Without `all_group_chats`, supergroups still show BotFather/old menu entries while handlers work.
+ */
+const COMMAND_SCOPES = [
+  { type: "default" as const },
+  { type: "all_private_chats" as const },
+  { type: "all_group_chats" as const },
+];
+
+export async function registerOpenPawBotCommands(bot: Bot): Promise<void> {
+  for (const scope of COMMAND_SCOPES) {
+    try {
+      await bot.api.setMyCommands(OPENPAW_COMMANDS, { scope });
+    } catch (e) {
+      console.warn(
+        `OpenPaw: setMyCommands failed (scope=${scope.type}). Menu may be wrong in some chats:`,
+        e instanceof Error ? e.message : e,
+      );
+    }
+  }
+}

package/gateway/telegram/chat-preferences.ts

@@ -0,0 +1,100 @@
+import { existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { getSessionsDir } from "../../config/paths";
+import { TELEGRAM_CHAT_PREFERENCES_FILENAME } from "./constants";
+
+/**
+ * Per-chat Telegram display flags and tool sandbox. Session persistence is unchanged;
+ * display flags only affect live delivery; sandbox affects file_editor and bash per turn.
+ */
+export type TelegramChatPreferences = {
+  /** When false, reasoning phases are not sent as separate Telegram messages. */
+  showReasoning: boolean;
+  /** When false, tool status lines are not sent as Telegram messages. */
+  showToolCalls: boolean;
+  /**
+   * When true (default), file_editor and bash are scoped to the workspace; when false,
+   * file_editor may access the broader filesystem and bash uses $HOME as cwd.
+   */
+  sandboxRestricted: boolean;
+};
+
+const DEFAULT_PREFS: TelegramChatPreferences = {
+  showReasoning: true,
+  showToolCalls: true,
+  sandboxRestricted: true,
+};
+
+type PrefsFile = Record<
+  string,
+  { showReasoning?: boolean; showToolCalls?: boolean; sandboxRestricted?: boolean }
+>;
+
+function prefsPath(): string {
+  return join(getSessionsDir(), TELEGRAM_CHAT_PREFERENCES_FILENAME);
+}
+
+async function readAllPrefs(): Promise<PrefsFile> {
+  const path = prefsPath();
+  if (!existsSync(path)) {
+    return {};
+  }
+  try {
+    const raw = await Bun.file(path).text();
+    const parsed = JSON.parse(raw) as unknown;
+    if (typeof parsed !== "object" || parsed === null) {
+      return {};
+    }
+    return parsed as PrefsFile;
+  } catch {
+    return {};
+  }
+}
+
+async function writeAllPrefs(data: PrefsFile): Promise<void> {
+  const dir = getSessionsDir();
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  await Bun.write(prefsPath(), JSON.stringify(data, null, 2));
+}
+
+/**
+ * Returns persisted preferences for a Telegram chat, merged with defaults.
+ */
+export async function getTelegramChatPreferences(chatId: number): Promise<TelegramChatPreferences> {
+  const all = await readAllPrefs();
+  const row = all[String(chatId)];
+  return {
+    showReasoning: row?.showReasoning ?? DEFAULT_PREFS.showReasoning,
+    showToolCalls: row?.showToolCalls ?? DEFAULT_PREFS.showToolCalls,
+    sandboxRestricted: row?.sandboxRestricted ?? DEFAULT_PREFS.sandboxRestricted,
+  };
+}
+
+/**
+ * Updates one or both flags for a chat and persists to disk.
+ */
+export async function setTelegramChatPreferences(
+  chatId: number,
+  patch: Partial<
+    Pick<TelegramChatPreferences, "showReasoning" | "showToolCalls" | "sandboxRestricted">
+  >,
+): Promise<TelegramChatPreferences> {
+  const all = await readAllPrefs();
+  const key = String(chatId);
+  const prev = all[key] ?? {};
+  const next: TelegramChatPreferences = {
+    showReasoning: patch.showReasoning ?? prev.showReasoning ?? DEFAULT_PREFS.showReasoning,
+    showToolCalls: patch.showToolCalls ?? prev.showToolCalls ?? DEFAULT_PREFS.showToolCalls,
+    sandboxRestricted:
+      patch.sandboxRestricted ?? prev.sandboxRestricted ?? DEFAULT_PREFS.sandboxRestricted,
+  };
+  all[key] = {
+    showReasoning: next.showReasoning,
+    showToolCalls: next.showToolCalls,
+    sandboxRestricted: next.sandboxRestricted,
+  };
+  await writeAllPrefs(all);
+  return next;
+}

package/gateway/telegram/constants.ts

@@ -0,0 +1,5 @@
+/** Persisted map of Telegram chat → active thread UUID (`~/.openpaw/workspace/sessions/`). */
+export const TELEGRAM_ACTIVE_THREADS_FILENAME = "telegram-active-threads.json";
+
+/** Per-chat UI preferences (reasoning/tool visibility in Telegram). */
+export const TELEGRAM_CHAT_PREFERENCES_FILENAME = "telegram-chat-preferences.json";

package/gateway/telegram/index.ts

@@ -0,0 +1,4 @@
+export { createTelegramChannelAdapter, runTelegramGateway } from "./adapter";
+export { telegramSessionKey } from "./session-key";
+export { deliverStreamingReply } from "./stream-delivery";
+export type { TelegramSessionListEntry } from "./session-file-discovery";

package/gateway/telegram/message-html.ts

@@ -0,0 +1,138 @@
+/**
+ * Builds Telegram Bot API HTML bodies (parse_mode: HTML) for reasoning and tool lines.
+ * @see https://core.telegram.org/bots/api#html-style
+ */
+
+import { truncateJson } from "../../agent/tool-stream-format";
+import { toolInputToYamlLike, toolOutputToYamlLike } from "../../agent/tool-yaml-like";
+import type { ToolStreamEvent } from "../../agent/types";
+
+const TELEGRAM_MAX = 4096;
+
+/** Shown after the reasoning block while the model is still streaming. */
+const STREAMING_CURSOR_PLAIN = " ▉";
+
+/**
+ * Escapes text for Telegram HTML mode (outside of tags you control).
+ */
+export function escapeTelegramHtml(text: string): string {
+  return text
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}
+
+function truncateInner(s: string, reserve: number): string {
+  const max = Math.max(0, TELEGRAM_MAX - reserve);
+  if (s.length <= max) {
+    return s;
+  }
+  return `${s.slice(0, max - 1)}…`;
+}
+
+/**
+ * Full HTML message for a reasoning phase (expandable blockquote for visual separation).
+ */
+export function formatReasoningPhaseHtml(
+  plain: string,
+  showCursor: boolean,
+): string {
+  const trimmed = plain.trimEnd();
+  if (!trimmed) {
+    return "";
+  }
+  const inner = truncateInner(escapeTelegramHtml(trimmed), 200);
+  const block = `<blockquote expandable>${inner}</blockquote>`;
+  return showCursor ? `${block}${STREAMING_CURSOR_PLAIN}` : block;
+}
+
+function formatToolInputBlock(toolName: string, input: unknown): string {
+  const yaml = truncateInner(toolInputToYamlLike(toolName, input), 220);
+  const body = escapeTelegramHtml(yaml);
+  return `<b>Tool · ${escapeTelegramHtml(toolName)}</b>\n<pre><code class="language-yaml">${body}</code></pre>`;
+}
+
+/**
+ * HTML for the tool-invocation half only (before the result is appended).
+ */
+export function formatToolInputOnlyHtml(toolName: string, input: unknown): string {
+  return formatToolInputBlock(toolName, input);
+}
+
+function formatToolOutputBlock(toolName: string, output: unknown): string {
+  const raw =
+    typeof output === "string"
+      ? output
+      : truncateJson(output, TELEGRAM_MAX - 400);
+  const inner = truncateInner(escapeTelegramHtml(raw), 220);
+  return `<b>→ ${escapeTelegramHtml(toolName)}</b>\n<pre><code class="language-json">${inner}</code></pre>`;
+}
+
+/**
+ * Full tool bubble: input block plus a Result section (after execution).
+ */
+export function formatToolCallCompleteHtml(
+  toolName: string,
+  input: unknown,
+  result: ToolStreamEvent,
+): string {
+  const head = formatToolInputBlock(toolName, input);
+  let tail = "";
+  switch (result.type) {
+    case "tool_output": {
+      const yaml = truncateInner(toolOutputToYamlLike(result.output), 600);
+      tail = `<b>Result</b>\n<pre><code class="language-yaml">${escapeTelegramHtml(yaml)}</code></pre>`;
+      break;
+    }
+    case "tool_error":
+      tail = `<b>Result</b>\n<blockquote>${escapeTelegramHtml(truncateInner(result.errorText, 400))}</blockquote>`;
+      break;
+    case "tool_denied":
+      tail = "<b>Result</b>\n<i>denied</i>";
+      break;
+    default:
+      return head;
+  }
+  const combined = `${head}\n${tail}`;
+  if (combined.length <= TELEGRAM_MAX) {
+    return combined;
+  }
+  const reserve = tail.length + 80;
+  const shrunkYaml = truncateInner(toolInputToYamlLike(toolName, input), reserve);
+  const shrunkHead = `<b>Tool · ${escapeTelegramHtml(toolName)}</b>\n<pre><code class="language-yaml">${escapeTelegramHtml(shrunkYaml)}</code></pre>`;
+  return `${shrunkHead}\n${tail}`.slice(0, TELEGRAM_MAX);
+}
+
+/**
+ * When no matching tool_input message exists, send the result alone (HTML).
+ */
+export function formatStandaloneToolResultHtml(ev: ToolStreamEvent): string {
+  switch (ev.type) {
+    case "tool_output":
+      return formatToolOutputBlock(ev.toolName, ev.output);
+    case "tool_error":
+      return `<b>⚠ ${escapeTelegramHtml(ev.toolName)}</b>\n<blockquote>${escapeTelegramHtml(truncateInner(ev.errorText, 120))}</blockquote>`;
+    case "tool_denied":
+      return `<b>⛔ ${escapeTelegramHtml(ev.toolName)}</b>\n<i>denied</i>`;
+    default:
+      return "";
+  }
+}
+
+/**
+ * Single Telegram HTML message for a streamed tool event (input-only or legacy standalone).
+ */
+export function formatToolStreamEventHtml(ev: ToolStreamEvent): string {
+  switch (ev.type) {
+    case "tool_input":
+      return formatToolInputBlock(ev.toolName, ev.input);
+    case "tool_output":
+      return formatToolOutputBlock(ev.toolName, ev.output);
+    case "tool_error":
+      return `<b>⚠ ${escapeTelegramHtml(ev.toolName)}</b>\n<blockquote>${escapeTelegramHtml(truncateInner(ev.errorText, 120))}</blockquote>`;
+    case "tool_denied":
+      return `<b>⛔ ${escapeTelegramHtml(ev.toolName)}</b>\n<i>denied</i>`;
+    default:
+      return "";
+  }
+}

package/gateway/telegram/message-queue.ts

@@ -0,0 +1,19 @@
+/**
+ * Serializes async work per queue key (one chain per Telegram chat queue id).
+ */
+export function createTelegramMessageQueue() {
+  const chains = new Map<string, Promise<unknown>>();
+
+  return function runSerialized<T>(queueKey: string, task: () => Promise<T>): Promise<T> {
+    const prev = chains.get(queueKey) ?? Promise.resolve();
+    const result = prev.then(() => task());
+    chains.set(
+      queueKey,
+      result.then(
+        () => {},
+        () => {},
+      ),
+    );
+    return result;
+  };
+}

package/gateway/telegram/reserved-command-filter.ts

@@ -0,0 +1,33 @@
+import type { Context } from "grammy";
+import { firstCommandToken, RESERVED_SLASH_COMMANDS } from "../slash-command-tokens";
+
+export { firstCommandToken };
+
+/**
+ * True when this text message should be handled by the OpenPaw agent.
+ * Messages whose first token looks like a Telegram slash command (`/…`) are never forwarded;
+ * they are handled by {@link shouldReportUnknownOpenPawSlashCommand} or grammy `bot.command` handlers.
+ */
+export function shouldForwardTextToAgent(ctx: Context): boolean {
+  const text = ctx.message?.text;
+  if (!text?.trim()) {
+    return false;
+  }
+  const token = firstCommandToken(text);
+  return token !== undefined && !token.startsWith("/");
+}
+
+/**
+ * True when the user sent a slash-prefixed first token that is not a known OpenPaw command
+ * (e.g. `/start`, `/help`, or a typo). Reply instead of invoking the model.
+ */
+export function shouldReportUnknownOpenPawSlashCommand(ctx: Context): boolean {
+  const text = ctx.message?.text;
+  if (!text?.trim()) {
+    return false;
+  }
+  const token = firstCommandToken(text);
+  return (
+    token !== undefined && token.startsWith("/") && !RESERVED_SLASH_COMMANDS.has(token)
+  );
+}