@inceptionstack/roundhouse 0.5.4 → 0.5.5

package/src/cli/setup.ts

@@ -10,7 +10,7 @@
  */
 
 import { readFile } from "node:fs/promises";
-import { BOT_COMMANDS } from "../commands";
+import { BOT_COMMANDS } from "../transports/telegram/bot-commands";
 import { atomicWriteJson, execSafe } from "./setup/helpers";
 import { type SetupOptions } from "./setup/types";
 import { parseSetupArgs } from "./setup/args";
@@ -27,7 +27,7 @@ import {
 import {
   validateBotToken,
   pairTelegram,
-} from "./setup-telegram";
+} from "./setup/telegram";
 import {
   stepPreflight,
   stepValidateToken,
@@ -42,7 +42,7 @@ import {
   stepPostflight,
 } from "./setup/steps";
 import { resolveAgentForSetup, textLog, textStepLog } from "./setup/runtime";
-import { runInteractiveTelegramSetup, runHeadlessTelegramSetup } from "./setup/flows";
+import { runInteractiveTelegramSetup, runNonInteractiveTelegramSetup } from "./setup/flows";
 
 // ── Orchestrator ─────────────────────────────────────
 
@@ -63,8 +63,8 @@ export async function cmdSetup(argv: string[]): Promise<void> {
 
   // Route to --telegram flows
   if (opts.telegram) {
-    if (opts.headless) {
-      await runHeadlessTelegramSetup(opts);
+    if (opts.nonInteractive) {
+      await runNonInteractiveTelegramSetup(opts);
     } else {
       await runInteractiveTelegramSetup(opts);
     }
@@ -258,12 +258,12 @@ function printSetupHelp(): void {
   console.log(`
 Usage:
   roundhouse setup --telegram                     Interactive wizard (recommended)
-  TELEGRAM_BOT_TOKEN=... roundhouse setup \\\n    --telegram --headless --user USERNAME          Headless automation (SSM/cloud-init)
+  TELEGRAM_BOT_TOKEN=... roundhouse setup \\\n    --telegram --non-interactive --user USERNAME   Non-interactive automation (SSM/cloud-init)
   TELEGRAM_BOT_TOKEN=... roundhouse setup \\\n    --user USERNAME                                Legacy (non-wizard) setup
 
 Modes:
-  --telegram                 Telegram-focused setup (wizard or headless)
-  --headless                 Non-interactive automation (implies --non-interactive)
+  --telegram                 Telegram-focused setup (wizard or non-interactive)
+  --non-interactive           Suppress all prompts (for automation/SSM/cloud-init)
                              Requires TELEGRAM_BOT_TOKEN env var and --user
 
 Required (or prompted in interactive --telegram):

package/src/cli/systemd.ts

@@ -127,6 +127,8 @@ WorkingDirectory=${home}
 ExecStart=${opts.execStart}
 Restart=on-failure
 RestartSec=5
+TimeoutStopSec=15
+KillMode=mixed
 EnvironmentFile=-${envFilePath}
 Environment=ROUNDHOUSE_CONFIG=${CONFIG_PATH}
 Environment=NODE_ENV=production

package/src/{commands → cli}/update.ts

@@ -8,7 +8,7 @@
 import { homedir } from "node:os";
 import { execSync } from "node:child_process";
 import { readFileSync, writeFileSync } from "node:fs";
-import { provisionBundle } from "../bundle";
+import { provisionBundle } from "../provisioning/bundle";
 
 export interface UpdateProgress {
   update(text: string): Promise<void>;

package/src/cron/runner.ts

@@ -6,7 +6,8 @@
  */
 
 import { getAgentFactory } from "../agents/registry";
-import { sendTelegramToMany } from "../notify/telegram";
+// TODO: route through TransportAdapter.notify() when multi-transport lands
+import { sendTelegramToMany } from "../transports/telegram/notify";
 import { CronStore, generateRunId } from "./store";
 import { buildTemplateContext, renderTemplate } from "./template";
 import type { CronJobConfig, CronRunRecord } from "./types";

package/src/gateway/commands.ts

@@ -1,5 +1,5 @@
 /**
- * gateway/commands.ts — Telegram command handlers
+ * gateway/commands.ts — Chat command handlers
  *
  * Each handler is a standalone async function that receives a CommandContext.
  * Extracted from Gateway.start() to reduce method size and enable unit testing.
@@ -9,7 +9,8 @@ import type { AgentAdapter, AgentStreamEvent, GatewayConfig } from "../types";
 import { ROUNDHOUSE_VERSION } from "../config";
 import { startTypingLoop } from "../util";
 import { prepareMemoryForTurn, finalizeMemoryForTurn, flushMemoryThenCompact, determineMemoryMode } from "../memory/lifecycle";
-import { createProgressMessage } from "../telegram-progress";
+// TODO: move progress into TransportAdapter when multi-transport lands
+import { createProgressMessage } from "../transports/telegram/progress";
 import { getSystemResources } from "./helpers";
 
 // ── Types ────────────────────────────────────────────
@@ -70,7 +71,7 @@ export async function handleUpdate(ctx: CommandContext): Promise<void> {
   console.log(`[roundhouse] /update requested by @${authorName} in thread=${thread.id}`);
   const progress = await createProgressMessage(thread, "📦 Checking for updates...");
   try {
-    const { performUpdate } = await import("../commands/update");
+    const { performUpdate } = await import("../cli/update");
     const result = await performUpdate(progress);
     if (result.action === "already-latest") {
       await progress.update(`✅ Already on latest (v${result.currentVersion})`);

package/src/{gateway.ts → gateway/gateway.ts}

@@ -7,29 +7,30 @@
 
 import { Chat } from "chat";
 import { createMemoryState } from "@chat-adapter/state-memory";
-import type { AgentAdapter, AgentMessage, AgentRouter, AgentStreamEvent, GatewayConfig } from "./types";
-import { splitMessage, isAllowed, startTypingLoop } from "./util";
-import { isTelegramThread, postTelegramHtml } from "./telegram-html";
-import { SttService, enrichAttachmentsWithTranscripts, DEFAULT_STT_CONFIG } from "./voice/stt-service";
-import { sendTelegramToMany } from "./notify/telegram";
-import { runDoctor, formatDoctorTelegram, createDoctorContext } from "./cli/doctor/runner";
-import { ROUNDHOUSE_DIR, ROUNDHOUSE_VERSION } from "./config";
-import { CronSchedulerService } from "./cron/scheduler";
-import { BOT_COMMANDS } from "./commands";
-import { prepareMemoryForTurn, finalizeMemoryForTurn, flushMemoryThenCompact, determineMemoryMode } from "./memory/lifecycle";
-import { maxPressure } from "./memory/policy";
-import type { PressureLevel, CompactResult } from "./memory/types";
-import { readPendingPairing, completePendingPairing, isStartForNonce } from "./pairing";
-import { createProgressMessage } from "./telegram-progress";
-import { isCommand as _isCmd, isCommandWithArgs as _isCmdArgs, resolveAgentThreadId as _resolveThread, getSystemResources as _getSysRes, toolIcon as _toolIcon } from "./gateway/helpers";
-import { saveAttachments as _saveAttachments, type AttachmentResult } from "./gateway/attachments";
-import { handleStreaming as _handleStream, type StreamResult } from "./gateway/streaming";
-import { handleNew, handleRestart, handleUpdate, handleCompact, handleStatus, handleStop, handleVerbose, handleDoctor, handleCrons, type CommandContext, type StopContext, type VerboseContext, type DoctorContext, type CronsContext } from "./gateway/commands";
-
-/** Match a Telegram command, handling optional @botname suffix */
+import type { AgentAdapter, AgentMessage, AgentRouter, AgentStreamEvent, GatewayConfig } from "../types";
+import { splitMessage, isAllowed, startTypingLoop } from "../util";
+import { SttService, enrichAttachmentsWithTranscripts, DEFAULT_STT_CONFIG } from "../voice/stt-service";
+import { runDoctor, formatDoctorTelegram, createDoctorContext } from "../cli/doctor/runner";
+import { ROUNDHOUSE_DIR, ROUNDHOUSE_VERSION } from "../config";
+import { CronSchedulerService } from "../cron/scheduler";
+import { prepareMemoryForTurn, finalizeMemoryForTurn, flushMemoryThenCompact } from "../memory/lifecycle";
+import { maxPressure } from "../memory/policy";
+import type { PressureLevel } from "../memory/types";
+// TODO: move progress into TransportAdapter when multi-transport lands
+import { createProgressMessage } from "../transports/telegram/progress";
+import { isCommand as _isCmd, isCommandWithArgs as _isCmdArgs, resolveAgentThreadId as _resolveThread, getSystemResources as _getSysRes } from "./helpers";
+import { saveAttachments as _saveAttachments, type AttachmentResult } from "./attachments";
+import { handleStreaming as _handleStream } from "./streaming";
+import { handleNew, handleRestart, handleUpdate, handleCompact, handleStatus, handleStop, handleVerbose, handleDoctor, handleCrons, type CommandContext } from "./commands";
+import { TelegramAdapter } from "../transports";
+import type { TransportAdapter } from "../transports";
+import { hostname } from "node:os";
+import { join } from "node:path";
+
 /** Bot username for command suffix validation (set during gateway init) */
 let _botUsername = "";
 
+/** Match a bot command, handling optional @botname suffix */
 function isCommand(text: string, cmd: string): boolean {
   return _isCmd(text, cmd, _botUsername);
 }
@@ -38,12 +39,10 @@ function isCommand(text: string, cmd: string): boolean {
 function isCommandWithArgs(text: string, cmd: string): boolean {
   return _isCmdArgs(text, cmd, _botUsername);
 }
-import { hostname } from "node:os";
 
 function getSystemResources() {
   return _getSysRes();
 }
-import { join } from "node:path";
 
 
 function resolveAgentThreadId(thread: any, message: any): string {
@@ -68,11 +67,6 @@ async function buildChatAdapters(
   return adapters;
 }
 
-function toolIcon(name: string): string {
-  return _toolIcon(name);
-}
-
-
 async function saveAttachments(threadId: string, attachments: any[]): Promise<AttachmentResult> {
   return _saveAttachments(threadId, attachments);
 }
@@ -83,6 +77,7 @@ export class Gateway {
   private chat!: Chat;
   private router: AgentRouter;
   private config: GatewayConfig;
+  private transport: TransportAdapter;
   private pairingComplete = false;
   private sttService: SttService | null = null;
   private cronScheduler: CronSchedulerService | null = null;
@@ -90,62 +85,41 @@ export class Gateway {
   constructor(router: AgentRouter, config: GatewayConfig) {
     this.router = router;
     this.config = config;
+    this.transport = new TelegramAdapter();
     _botUsername = config.chat.botUsername || "";
   }
 
-  /** Handle pending Telegram pairing from headless setup. Returns true if handled. */
+  /** Handle pending pairing via transport adapter. Returns true if handled. */
   private async handlePendingPairing(
-    text: string,
     message: any,
     thread: any,
-    authorName: string,
   ): Promise<boolean> {
     try {
-      const pending = await readPendingPairing();
-      if (!pending || pending.status !== "pending" || !isStartForNonce(text, pending.nonce)) {
-        return false;
-      }
+      const result = await this.transport.handlePairing(thread, message);
+      if (!result) return false;
 
-      const fromUser = authorName.toLowerCase();
-      const allowed = pending.allowedUsers.map(u => u.toLowerCase());
-      if (!fromUser || !allowed.includes(fromUser)) {
-        console.log(`[roundhouse] Pairing nonce from unauthorized user @${authorName}`);
-        return false;
-      }
+      const { threadId: rawThreadId, userId: rawUserId, username } = result;
+      // Config arrays are currently number[] — coerce with guard.
+      // When a string-ID transport (Slack/Discord) arrives, widen config types too.
+      const threadId = typeof rawThreadId === "string" ? Number(rawThreadId) : rawThreadId;
+      const userId = typeof rawUserId === "string" ? Number(rawUserId) : rawUserId;
 
-      // Extract IDs from the chat adapter message
-      const chatId = typeof message.chatId === "number"
-        ? message.chatId
-        : typeof thread.id === "string" && thread.id.startsWith("telegram:")
-          ? parseInt(thread.id.split(":")[1], 10)
-          : undefined;
-      // Chat SDK Telegram adapter provides userId (not id)
-      const rawUserId = message.author?.userId ?? message.author?.id ?? message.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}. Pairing left pending.`);
-        await thread.post("⚠️ Pairing nonce accepted but could not capture your Telegram IDs. Try sending /start again, or run: roundhouse pair");
-        return true;
+      if (!Number.isFinite(threadId) || !Number.isFinite(userId)) {
+        console.error(`[roundhouse] Pairing returned non-numeric IDs: threadId=${rawThreadId} userId=${rawUserId}`);
+        return false;
       }
 
-      await completePendingPairing({ chatId, userId, username: authorName });
-
       // Update in-memory config
       if (!this.config.chat.allowedUserIds) this.config.chat.allowedUserIds = [];
       if (!this.config.chat.allowedUserIds.includes(userId)) {
         this.config.chat.allowedUserIds.push(userId);
       }
       if (!this.config.chat.notifyChatIds) this.config.chat.notifyChatIds = [];
-      if (!this.config.chat.notifyChatIds.includes(chatId)) {
-        this.config.chat.notifyChatIds.push(chatId);
+      if (!this.config.chat.notifyChatIds.includes(threadId)) {
+        this.config.chat.notifyChatIds.push(threadId);
       }
 
-      // Atomic config file update
+      // Persist config atomically
       try {
         const { readFile: rf, rename: mvf, writeFile: wf, unlink: ulf } = await import("node:fs/promises");
         const { randomBytes: rb } = await import("node:crypto");
@@ -155,7 +129,7 @@ export class Gateway {
         if (!configRaw.chat.allowedUserIds) configRaw.chat.allowedUserIds = [];
         if (!configRaw.chat.allowedUserIds.includes(userId)) configRaw.chat.allowedUserIds.push(userId);
         if (!configRaw.chat.notifyChatIds) configRaw.chat.notifyChatIds = [];
-        if (!configRaw.chat.notifyChatIds.includes(chatId)) configRaw.chat.notifyChatIds.push(chatId);
+        if (!configRaw.chat.notifyChatIds.includes(threadId)) configRaw.chat.notifyChatIds.push(threadId);
         const tmp = `${cfgPath}.tmp.${rb(4).toString("hex")}`;
         await wf(tmp, JSON.stringify(configRaw, null, 2) + "\n");
         await mvf(tmp, cfgPath).catch(async (e) => { try { await ulf(tmp); } catch {} throw e; });
@@ -163,7 +137,7 @@ export class Gateway {
         console.error("[roundhouse] failed to update config after pairing:", cfgErr);
       }
 
-      console.log(`[roundhouse] Telegram pairing complete: @${authorName} chatId=${chatId} userId=${userId}`);
+      console.log(`[roundhouse] Pairing complete: @${username} threadId=${threadId} userId=${userId}`);
       this.pairingComplete = true;
       await thread.post("✅ Roundhouse paired successfully!\n\nSend /status to verify everything is working.");
       return true;
@@ -243,9 +217,9 @@ export class Gateway {
         `[roundhouse] ${thread.id} -> ${agentThreadId} @${authorName}: "${userText.slice(0, 120)}"${rawAttachments.length ? ` +${rawAttachments.length} attachment(s)` : ""}`
       );
 
-      // Check for pending Telegram pairing (headless setup)
-      if (userText.trim().startsWith("/start ") && !this.pairingComplete) {
-        const handled = await this.handlePendingPairing(userText.trim(), message, thread, authorName ?? "");
+      // Check for pending pairing via transport adapter
+      if (!this.pairingComplete && await this.transport.isPairingPending()) {
+        const handled = await this.handlePendingPairing(message, thread);
         if (handled) return;
       }
 
@@ -385,14 +359,23 @@ export class Gateway {
     try {
       console.log(`[roundhouse] → ${agent.name} | thread=${agentThreadId}`);
 
-      // Enrich audio attachments with transcripts (STT)
-      await this.enrichWithStt(thread, agentMessage);
+      // Enrich audio attachments with transcripts (STT) — show typing while processing
+      if (agentMessage.attachments?.some((a: any) => a.mediaType === "audio")) {
+        const sttTyping = startTypingLoop(thread);
+        try {
+          await this.enrichWithStt(thread, agentMessage);
+        } finally {
+          sttTyping();
+        }
+      } else {
+        await this.enrichWithStt(thread, agentMessage);
+      }
 
       // Let the agent adapter apply platform-specific message transforms
       if (agent.prepareMessage) {
         try {
           agentMessage = agent.prepareMessage(agentThreadId, agentMessage, {
-            platform: "telegram",
+            platform: this.transport.name,
             hasAttachments: !!(agentMessage.attachments?.length),
           });
         } catch (err) {
@@ -528,6 +511,11 @@ export class Gateway {
       return null;
     }
 
+    // Enrich prompt via transport adapter
+    if (agentMessage.text) {
+      agentMessage.text = this.transport.enrichPrompt(agentMessage.text);
+    }
+
     return agentMessage;
   }
 
@@ -612,9 +600,8 @@ export class Gateway {
 
   /** Post text with markdown, falling back to plain text */
   private async postWithFallback(thread: any, text: string) {
-    // Telegram: send as HTML for proper markdown rendering
-    if (isTelegramThread(thread)) {
-      await postTelegramHtml(thread, text);
+    if (this.transport.ownsThread(thread)) {
+      await this.transport.postMessage(thread, text);
       return;
     }
     for (const chunk of splitMessage(text, 4000)) {
@@ -636,25 +623,9 @@ export class Gateway {
    */
   private async registerBotCommands() {
     if (!this.config.chat.adapters.telegram) return;
-
     const token = process.env.TELEGRAM_BOT_TOKEN;
     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] failed to register bot commands:`, (err as Error).message);
-    }
+    await this.transport.registerCommands(token);
   }
 
   /**
@@ -666,11 +637,6 @@ export class Gateway {
     const chatIds = this.config.chat.notifyChatIds;
     if (!chatIds?.length) return;
 
-    if (!process.env.TELEGRAM_BOT_TOKEN) {
-      console.warn("[roundhouse] notifyChatIds configured but TELEGRAM_BOT_TOKEN not set — skipping startup notification");
-      return;
-    }
-
     const bootTime = process.uptime();
     const host = hostname();
     const agentName = this.config.agent.type;
@@ -715,7 +681,7 @@ export class Gateway {
         `  Process: ${memMB} MB RSS`,
       ].filter(line => line != null).join("\n");
 
-      await sendTelegramToMany([chatId], perChatText);
+      await this.transport.notify([chatId], perChatText);
     }
   }
 

package/src/gateway/helpers.ts

@@ -10,7 +10,7 @@ import { hostname, loadavg, totalmem, freemem, cpus } from "node:os";
 // ── Command Matching ─────────────────────────────────
 
 /**
- * Match a Telegram command, handling optional @botname suffix.
+ * Match a bot command, handling optional @botname suffix.
  */
 export function isCommand(text: string, cmd: string, botUsername: string): boolean {
   if (text === cmd) return true;

package/src/gateway/index.ts

@@ -1,11 +1,8 @@
 /**
- * gateway/index.ts — Barrel export for gateway sub-modules
- *
- * Re-exports helpers, attachments, streaming, and commands for
- * external consumers. The Gateway class itself lives at src/gateway.ts
- * and is imported directly (not through this barrel).
+ * gateway/index.ts — Barrel export for gateway module
  */
 
+export { Gateway } from "./gateway";
 export { isCommand, isCommandWithArgs, resolveAgentThreadId, getSystemResources, toolIcon } from "./helpers";
 export { saveAttachments } from "./attachments";
 export { handleStreaming } from "./streaming";

package/src/gateway/streaming.ts

@@ -10,7 +10,7 @@
 
 import type { AgentStreamEvent } from "../types";
 import { READ_ONLY_TOOLS } from "../memory/types";
-import { isTelegramThread, handleTelegramHtmlStream } from "../telegram-html";
+import { isTelegramThread, handleTelegramHtmlStream } from "../transports/telegram/html";
 import { DEBUG_STREAM } from "../util";
 import { toolIcon } from "./helpers";
 

package/src/{bundle.ts → provisioning/bundle.ts}

@@ -182,12 +182,44 @@ export function provisionMcporterConfig(opts: ProvisionOpts = {}): void {
   }
 }
 
+/**
+ * Sync bundled skills that ship with roundhouse (additive, overwrites on each provision).
+ */
+export function syncBundledSkills(opts: ProvisionOpts = {}): void {
+  const log = opts.log ?? consoleLog;
+  // Resolves to <package-root>/skills/ (two levels up from src/provisioning/)
+  const bundledDir = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", "skills");
+  if (!existsSync(bundledDir)) return;
+
+  const entries = readdirSync(bundledDir, { withFileTypes: true })
+    .filter(e => e.isDirectory() && !e.name.startsWith("."));
+  if (entries.length === 0) return;
+
+  mkdirSync(SKILLS_DIR, { recursive: true });
+  let count = 0;
+  for (const entry of entries) {
+    const src = resolve(bundledDir, entry.name);
+    const dest = resolve(SKILLS_DIR, entry.name);
+    if (!dest.startsWith(SKILLS_DIR + "/")) continue;
+    try {
+      execFileSync("rm", ["-rf", dest], { stdio: "pipe", timeout: 10_000 });
+      execFileSync("cp", ["-r", src, dest], { stdio: "pipe", timeout: 30_000 });
+      count++;
+    } catch (e: any) {
+      log.warn(`Failed to copy bundled skill '${entry.name}': ${e.message}`);
+    }
+  }
+  if (count > 0) log.ok(`${count} bundled skill(s) synced`);
+}
+
 /**
  * Provision all bundle dependencies (skills + CLI tools + config + extensions).
  * Non-fatal — logs warnings on failure but never throws.
  */
 export function provisionBundle(opts: ProvisionOpts = {}): void {
   syncSkillsFromRepo(opts);
+  // Must run after syncSkillsFromRepo so bundled skills take precedence on name collision
+  syncBundledSkills(opts);
   provisionMcporter(opts);
   provisionPlaywright(opts);
   provisionUvx(opts);

package/src/transports/index.ts

@@ -0,0 +1,6 @@
+/**
+ * transports/index.ts — Transport adapter registry
+ */
+
+export type { TransportAdapter, ChatThread, IncomingMessage, PairingResult } from "./types";
+export { TelegramAdapter } from "./telegram/telegram-adapter";

package/src/{telegram-html.ts → transports/telegram/html.ts}

@@ -8,8 +8,8 @@
  * typing indicators, command handling, authorization, message history.
  */
 
-import { markdownToTelegramHtml, truncateHtmlSafe } from "./telegram-format";
-import { splitMessage } from "./util";
+import { markdownToTelegramHtml, truncateHtmlSafe } from "./format";
+import { splitMessage } from "../../util";
 
 /** Max Telegram message length */
 const TELEGRAM_LIMIT = 4096;

package/src/{pairing.ts → transports/telegram/pairing.ts}

@@ -8,7 +8,7 @@
 import { readFile, writeFile, rename, unlink, mkdir } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 import { randomBytes } from "node:crypto";
-import { ROUNDHOUSE_DIR } from "./config";
+import { ROUNDHOUSE_DIR } from "../../config";
 
 export interface PendingPairing {
   version: 1;

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 };
+  }
+}