@inceptionstack/roundhouse 0.5.3 → 0.5.5

package/src/transports/telegram/telegram-adapter.ts

@@ -0,0 +1,111 @@
+/**
+ * transports/telegram/telegram-adapter.ts — Telegram transport adapter
+ *
+ * Implements TransportAdapter for Telegram, composing existing
+ * utility modules (format, html, progress, notify, bot-commands).
+ */
+
+import type { TransportAdapter, ChatThread, IncomingMessage, PairingResult } from "../types";
+import { isTelegramThread, postTelegramHtml } from "./html";
+import { sendTelegramToMany } from "./notify";
+import { BOT_COMMANDS } from "./bot-commands";
+import { readPendingPairing, completePendingPairing, clearPendingPairing, isStartForNonce } from "./pairing";
+
+const TELEGRAM_FORMAT_HINT = "[Format your final answer to be telegram-friendly.]";
+
+export class TelegramAdapter implements TransportAdapter {
+  readonly name = "telegram";
+
+  enrichPrompt(text: string): string {
+    return `${text}\n\n${TELEGRAM_FORMAT_HINT}`;
+  }
+
+  async postMessage(thread: ChatThread, text: string): Promise<void> {
+    if (!isTelegramThread(thread as any)) {
+      throw new Error("TelegramAdapter.postMessage called with non-Telegram thread");
+    }
+    await postTelegramHtml(thread as any, text);
+  }
+
+  async registerCommands(token: string): Promise<void> {
+    if (!token) return;
+    try {
+      const res = await fetch(`https://api.telegram.org/bot${token}/setMyCommands`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ commands: BOT_COMMANDS }),
+      });
+      if (res.ok) {
+        console.log(`[roundhouse] registered ${BOT_COMMANDS.length} bot commands with Telegram`);
+      } else {
+        const body = await res.text().catch(() => "");
+        console.warn(`[roundhouse] failed to register bot commands (${res.status}): ${body.slice(0, 200)}`);
+      }
+    } catch (err) {
+      console.warn(`[roundhouse] bot command registration error:`, (err as Error).message);
+    }
+  }
+
+  ownsThread(thread: ChatThread): boolean {
+    return isTelegramThread(thread as any);
+  }
+
+  async notify(chatIds: number[], text: string): Promise<void> {
+    if (!process.env.TELEGRAM_BOT_TOKEN) {
+      console.warn("[roundhouse] TELEGRAM_BOT_TOKEN not set — skipping notification");
+      return;
+    }
+    await sendTelegramToMany(chatIds, text);
+  }
+
+  async isPairingPending(): Promise<boolean> {
+    const pending = await readPendingPairing();
+    return pending?.status === "pending";
+  }
+
+  async handlePairing(thread: ChatThread, message: IncomingMessage): Promise<PairingResult | null> {
+    const text = (message.text ?? "").trim();
+    if (!text) return null;
+
+    const pending = await readPendingPairing();
+    if (!pending || pending.status !== "pending" || !isStartForNonce(text, pending.nonce)) {
+      return null;
+    }
+
+    // Verify author is allowed
+    const authorName = (message.author?.userName ?? message.author?.name ?? "").toLowerCase();
+    const originalName = message.author?.userName ?? message.author?.name ?? "";
+    const allowed = pending.allowedUsers.map(u => u.toLowerCase());
+    if (!authorName || !allowed.includes(authorName)) {
+      console.log(`[roundhouse] Pairing nonce from unauthorized user @${originalName}`);
+      return null;
+    }
+
+    // Extract Telegram-specific IDs
+    const msg = message as any;
+    const chatId = typeof msg.chatId === "number"
+      ? msg.chatId
+      : typeof thread.id === "string" && thread.id.startsWith("telegram:")
+        ? parseInt(thread.id.split(":")[1], 10)
+        : undefined;
+
+    const rawUserId = msg.author?.userId ?? msg.author?.id ?? msg.raw?.from?.id;
+    const userId = typeof rawUserId === "number"
+      ? rawUserId
+      : typeof rawUserId === "string"
+        ? parseInt(rawUserId, 10)
+        : undefined;
+
+    if (chatId == null || Number.isNaN(chatId) || userId == null || Number.isNaN(userId)) {
+      console.error(`[roundhouse] Pairing nonce matched but could not extract IDs: chatId=${chatId} userId=${userId} (raw: msg.chatId=${message.chatId}, thread.id=${thread.id}, author.userId=${message.author?.userId}, author.id=${message.author?.id}, raw.from.id=${message.raw?.from?.id})`);
+      await clearPendingPairing();
+      await thread.post("⚠️ Pairing failed — could not capture your Telegram IDs. Run: roundhouse setup --telegram");
+      return null;
+    }
+
+    // Mark pairing complete in transport state
+    await completePendingPairing({ chatId, userId, username: originalName });
+
+    return { threadId: chatId, userId, username: originalName };
+  }
+}

package/src/transports/types.ts

@@ -0,0 +1,71 @@
+/**
+ * transports/types.ts — Transport adapter interface
+ *
+ * Defines the contract for platform-specific transport adapters.
+ * The gateway uses this interface to remain transport-agnostic.
+ */
+
+/** Minimal thread interface (subset of Chat SDK thread) */
+export interface ChatThread {
+  id: string;
+  post(text: string): Promise<void>;
+  [key: string]: unknown;
+}
+
+/** Minimal incoming message interface */
+export interface IncomingMessage {
+  text?: string;
+  author?: { userName?: string; name?: string; userId?: string | number; id?: string };
+  chatId?: number;
+  raw?: { from?: { id?: number } };
+  [key: string]: unknown;
+}
+
+/** Result of a successful transport pairing */
+export interface PairingResult {
+  /** Thread/channel ID for notifications */
+  threadId: string | number;
+  /** User ID for allowlist */
+  userId: string | number;
+  /** Display name */
+  username: string;
+}
+
+/**
+ * TransportAdapter — platform-specific behavior contract.
+ *
+ * Encapsulates all concerns specific to a messaging platform
+ * (Telegram, Slack, Discord, etc.), keeping the gateway transport-agnostic.
+ */
+export interface TransportAdapter {
+  /** Transport name (e.g. "telegram") */
+  readonly name: string;
+
+  /** Enrich prompt text before sending to agent (e.g. formatting hints) */
+  enrichPrompt(text: string): string;
+
+  /** Post a message using platform-native formatting */
+  postMessage(thread: ChatThread, text: string): Promise<void>;
+
+  /** Register bot commands with the platform */
+  registerCommands(token: string): Promise<void>;
+
+  /** Check if a thread belongs to this transport */
+  ownsThread(thread: ChatThread): boolean;
+
+  /** Send notifications to configured recipients */
+  notify(chatIds: number[], text: string): Promise<void>;
+
+  /**
+   * Check if a pairing flow is pending.
+   * Gateway uses this to decide whether to attempt pairing on incoming messages.
+   */
+  isPairingPending(): Promise<boolean>;
+
+  /**
+   * Try to handle an incoming message as a pairing attempt.
+   * Returns PairingResult on success, null if not a pairing message.
+   * Transport manages its own state (nonce files, OAuth tokens, etc.)
+   */
+  handlePairing(thread: ChatThread, message: IncomingMessage): Promise<PairingResult | null>;
+}

package/src/types.ts

@@ -43,7 +43,8 @@ export type AgentStreamEvent =
   | { type: "draining" }
   | { type: "drain_complete" }
   | { type: "agent_end" }
-  | { type: "custom_message"; customType: string; content: string };
+  | { type: "custom_message"; customType: string; content: string }
+  | { type: "model_error"; message: string };
 
 // ── AdapterInfo ──────────────────────────────────────