@inceptionstack/roundhouse 0.5.22 → 0.5.26

package/src/gateway/gateway.ts

@@ -20,44 +20,38 @@ 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 { 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 { handleModel, handleModelAction, MODEL_ACTION_ID } from "./model-command";
 import { handleLater } from "./later-command";
-import { handleTopic, applyTopicOverride } from "./topic-command";
+import { handleTopic, handleTopicAction, TOPIC_ACTION_ID, applyTopicOverride } from "./topic-command";
+import {
+  type CommandDescriptor,
+  type CommandInvocation,
+  collectAndValidateActions,
+  isPreTurn,
+  matchesDescriptor,
+} from "./command-registry";
 import { TelegramAdapter } from "../transports";
 import type { TransportAdapter } from "../transports";
 import { SubAgentOrchestratorImpl, SubAgentWatcher } from "../subagents";
 import type { RunStatus, RoutingInfo } from "../subagents";
 import { hostname } from "node:os";
 import { join } from "node:path";
+import { readFile } from "node:fs/promises";
 import { injectToolsSection } from "./tools-inject";
 import { injectPersonaSection, loadPersona } from "./persona-inject";
 import { checkVersionChange } from "./whats-new";
 
+/** Limits */
+const MAX_SUBAGENT_STDOUT_CHARS = 3000;
+const MAX_MESSAGE_CHUNK = 4000;
+const MAX_ERROR_PREVIEW = 200;
+
 /** 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);
-}
-
-/** Match a command that accepts subcommands (e.g. /crons trigger <id>) */
-function isCommandWithArgs(text: string, cmd: string): boolean {
-  return _isCmdArgs(text, cmd, _botUsername);
-}
-
-function getSystemResources() {
-  return _getSysRes();
-}
-
-
-function resolveAgentThreadId(thread: any, message: any): string {
-  return _resolveThread(thread, message);
-}
-
 // ── Chat SDK adapter factories ───────────────────────
 // Lazy-imported so we don't crash if an adapter package isn't installed.
 
@@ -76,10 +70,6 @@ async function buildChatAdapters(
   return adapters;
 }
 
-async function saveAttachments(threadId: string, attachments: any[]): Promise<AttachmentResult> {
-  return _saveAttachments(threadId, attachments);
-}
-
 // ── Gateway ──────────────────────────────────────────
 
 export class Gateway {
@@ -93,6 +83,10 @@ export class Gateway {
   private ipcServer: IpcServer | null = null;
   private subagentOrchestrator: SubAgentOrchestratorImpl | null = null;
   private subagentWatcher: SubAgentWatcher | null = null;
+  private verboseThreads = new Set<string>();
+  private threadLocks = new Map<string, Promise<void>>();
+  private abortControllers = new Map<string, AbortController>();
+  private flushInProgress = new Set<string>();
 
   constructor(router: AgentRouter, config: GatewayConfig) {
     this.router = router;
@@ -210,17 +204,32 @@ export class Gateway {
     }
 
     // Per-thread verbose toggle (shows tool_start messages)
-    const verboseThreads = new Set<string>();
+    const verboseThreads = this.verboseThreads;
 
     // Per-thread abort signal for /stop
-    const abortControllers = new Map<string, AbortController>();
+    const abortControllers = this.abortControllers;
 
     // Per-thread lock to serialize prompts (concurrent mode lets /stop through)
-    const threadLocks = new Map<string, Promise<void>>();
+    const threadLocks = this.threadLocks;
+
+    // ── Build command descriptors ──────────────────────
+    // Each descriptor self-describes its triggers, dispatch stage, and
+    // optional inline-keyboard callbacks. The gateway iterates this list
+    // to wire everything — no more per-command if-blocks or onAction calls.
+    // Adding a new command = one more entry here + (optionally) a new module.
+    const allDescriptors = this.buildCommandDescriptors({
+      allowedUsers, allowedUserIds, verboseThreads, threadLocks, abortControllers,
+    });
+    const preTurnCommands = allDescriptors.filter(isPreTurn);
+    const inTurnCommands = allDescriptors.filter(d => !isPreTurn(d));
+    const matchers = {
+      isCommand: (t: string, c: string) => _isCmd(t, c, _botUsername),
+      isCommandWithArgs: (t: string, c: string) => _isCmdArgs(t, c, _botUsername),
+    };
 
-    // ── Unified handler ────────────────────────────
+    // ── Unified handler ──────────────────────────────
     const handle = async (thread: any, message: any) => {
-      let agentThreadId = applyTopicOverride(resolveAgentThreadId(thread, message), thread);
+      const agentThreadId = applyTopicOverride(_resolveThread(thread, message), thread);
       const userText = message.text ?? "";
       const authorName = message.author?.userName ?? message.author?.userId ?? "?";
       const rawAttachments = message.attachments ?? [];
@@ -240,75 +249,39 @@ export class Gateway {
         return;
       }
 
-      if (isCommand(userText, "/start")) return;
+      if (_isCmd(userText, "/start", _botUsername)) return;
       if (!userText.trim() && !rawAttachments.length) return;
 
-      // ── Command dispatch (registry-based) ───
+      // ── Command dispatch (in-turn stage) ───
       const trimmed = userText.trim();
-
-      // Commands using standard CommandContext
-      const COMMAND_REGISTRY: Record<string, (ctx: CommandContext) => Promise<void>> = {
-        "/new": handleNew,
-        "/restart": handleRestart,
-        "/update": handleUpdate,
-        "/compact": handleCompact,
-        "/status": handleStatus,
-      };
-
-      for (const [cmd, handler] of Object.entries(COMMAND_REGISTRY)) {
-        if (isCommand(trimmed, cmd)) {
-          await handler(this.buildCommandContext(thread, message, agentThreadId, authorName, allowedUsers, allowedUserIds, verboseThreads, threadLocks));
+      const inv: CommandInvocation = { thread, message, text: trimmed, agentThreadId };
+      for (const desc of inTurnCommands) {
+        if (matchesDescriptor(desc, trimmed, matchers)) {
+          await desc.invoke(inv);
           return;
         }
       }
 
-      // Commands with custom context (accept args)
-      if (isCommandWithArgs(trimmed, "/model") || isCommand(trimmed, "/model")) {
-        await handleModel({ thread, text: trimmed, postWithFallback: (t, txt) => this.postWithFallback(t, txt) });
-        return;
-      }
-      if (isCommandWithArgs(trimmed, "/later") || isCommand(trimmed, "/later")) {
-        await handleLater({ thread, text: trimmed, postWithFallback: (t, txt) => this.postWithFallback(t, txt) });
-        return;
-      }
-
-      if (isCommandWithArgs(trimmed, "/topic") || isCommand(trimmed, "/topic")) {
-        await handleTopic({ thread, text: trimmed, postWithFallback: (t, txt) => this.postWithFallback(t, txt) });
-        return;
-      }
-
       // Dispatch to agent turn handler
       await this.handleAgentTurn(thread, agentThreadId, userText, rawAttachments, verboseThreads, threadLocks, abortControllers);
     };
 
     // ── Wire Chat SDK events ───────────────────────
     const handleOrAbort = async (thread: any, message: any) => {
-      let agentThreadId = applyTopicOverride(resolveAgentThreadId(thread, message), thread);
+      const agentThreadId = applyTopicOverride(_resolveThread(thread, message), thread);
       const text = (message.text ?? "").trim();
-      // /stop — abort the in-flight agent run immediately
-      if (isCommand(text, "/stop")) {
-        if (!isAllowed(message, allowedUsers, allowedUserIds)) return;
-        await handleStop({ thread, agentThreadId, agent: this.router.resolve(agentThreadId), abortControllers });
-        return;
-      }
-      // /verbose — toggle verbose mode immediately
-      if (isCommand(text, "/verbose")) {
-        if (!isAllowed(message, allowedUsers, allowedUserIds)) return;
-        await handleVerbose({ thread, agentThreadId, verboseThreads });
-        return;
-      }
-      // /doctor — run health checks immediately
-      if (isCommand(text, "/doctor")) {
-        if (!isAllowed(message, allowedUsers, allowedUserIds)) return;
-        await handleDoctor({ thread, runDoctor, createDoctorContext, formatDoctorTelegram, postWithFallback: (t, txt) => this.postWithFallback(t, txt) });
-        return;
-      }
-      // /crons manages scheduled jobs
-      if (isCommandWithArgs(text, "/crons") || isCommandWithArgs(text, "/jobs")) {
-        if (!isAllowed(message, allowedUsers, allowedUserIds)) return;
-        await handleCrons({ thread, text, cronScheduler: this.cronScheduler, postWithFallback: (t, txt) => this.postWithFallback(t, txt) });
-        return;
+
+      // Pre-turn commands fire before the main handler (and before the
+      // session-pressure gate), so /stop etc. still interrupt a mid-run
+      // agent. Allowlist is enforced here for all pre-turn handlers.
+      for (const desc of preTurnCommands) {
+        if (matchesDescriptor(desc, text, matchers)) {
+          if (!isAllowed(message, allowedUsers, allowedUserIds)) return;
+          await desc.invoke({ thread, message, text, agentThreadId });
+          return;
+        }
       }
+
       await handle(thread, message);
     };
 
@@ -330,9 +303,15 @@ export class Gateway {
     loadPersona();
 
     // ── Handle inline keyboard callbacks ───
-    this.chat.onAction(MODEL_ACTION_ID, async (event: any) => {
-      await handleModelAction({ value: event.value, thread: event.thread });
-    });
+    // ── Register inline-keyboard action handlers from all descriptors ───
+    // `collectAndValidateActions` throws if two descriptors claim the same
+    // action id — duplicates would silently misbehave on chat.onAction, so
+    // fail fast at startup.
+    for (const { actionId, handler } of collectAndValidateActions(allDescriptors)) {
+      this.chat.onAction(actionId, async (event: any) => {
+        await handler({ value: event.value, thread: event.thread });
+      });
+    }
 
     await this.chat.initialize();
 
@@ -368,6 +347,13 @@ export class Gateway {
 
     // Start sub-agent orchestrator + watcher
     this.subagentOrchestrator = new SubAgentOrchestratorImpl();
+    this.subagentOrchestrator.onSpawn(async (status) => {
+      const chatId = Number(status.routing?.chatId);
+      if (chatId) {
+        const msg = `🔬 **Sub-agent launched** (${status.role})\nrun: \`${status.runId.slice(0, 8)}\``;
+        try { await this.transport.notify([chatId], msg); } catch {}
+      }
+    });
     this.subagentWatcher = new SubAgentWatcher(
       this.subagentOrchestrator,
       async (status, routing) => {
@@ -453,6 +439,27 @@ export class Gateway {
 
       stopTyping = startTypingLoop(thread);
 
+      // Pre-turn recovery: if a prior turn failed to compact (state has
+      // pendingCompact === "emergency"), the live session is almost certainly
+      // still over the model's context limit, so calling agent.prompt() now
+      // will throw with "prompt is too long" before our post-turn pressure
+      // handler ever runs — perpetuating the loop. Run the pressure handler
+      // BEFORE the agent call to recover. Best-effort: if it fails, fall
+      // through to the normal turn (which will then post the error and let
+      // the user see something is wrong).
+      if (memoryPrepared?.pendingCompact === "emergency") {
+        console.log(`[roundhouse] pre-turn recovery: pendingCompact=emergency, compacting before agent.prompt for thread=${agentThreadId}`);
+        try {
+          await this.handleContextPressure(thread, agentThreadId, agent, memoryRoot, "emergency");
+          // Clear the pending flag in our prepared snapshot so the post-turn
+          // pressure logic doesn't double-up on a redundant emergency pass.
+          memoryPrepared.pendingCompact = undefined;
+        } catch (err) {
+          console.error(`[roundhouse] pre-turn emergency compact failed:`, (err as Error).message);
+        }
+      }
+
+      let deferredSoftFlush: { thread: any; agentThreadId: string; agent: AgentAdapter; memoryRoot: string } | undefined;
       try {
         let turnUsedTools = false;
         if (agent.promptStream) {
@@ -481,7 +488,12 @@ export class Gateway {
             agent, memoryRoot, this.config.memory,
           );
           const effectivePressure = maxPressure(memoryPrepared?.pendingCompact, pressure);
-          if (effectivePressure !== "none") {
+          if (effectivePressure === "soft") {
+            // Soft flush deferred to OUTSIDE the lock (no memory state invariants affected)
+            deferredSoftFlush = { thread, agentThreadId, agent, memoryRoot };
+          } else if (effectivePressure !== "none") {
+            // Hard/emergency: must run INSIDE the lock (compact changes session state,
+            // prepareMemoryForTurn on next turn needs post-compact reinjection)
             try {
               await this.handleContextPressure(thread, agentThreadId, agent, memoryRoot, effectivePressure);
             } catch (err) {
@@ -493,7 +505,7 @@ export class Gateway {
         }
       } catch (err) {
         const errMsg = err instanceof Error ? err.message : String(err);
-        const safeMsg = errMsg.split('\n')[0].slice(0, 200);
+        const safeMsg = errMsg.split('\n')[0].slice(0, MAX_ERROR_PREVIEW);
         console.error(`[roundhouse] agent error:`, err);
         try {
           await thread.post(`⚠️ Error: ${safeMsg}`);
@@ -507,6 +519,22 @@ export class Gateway {
         threadLocks.delete(agentThreadId);
       }
     }
+
+    // Soft flush runs OUTSIDE the thread lock.
+    // Soft flush only prompts the agent to save facts to MEMORY.md — no compact,
+    // no session state change, no force-reinject needed. Safe to run concurrently.
+    if (deferredSoftFlush && !this.flushInProgress.has(deferredSoftFlush.agentThreadId)) {
+      const { thread: t, agentThreadId: tid, agent: a, memoryRoot: mr } = deferredSoftFlush;
+      this.flushInProgress.add(tid);
+      console.log(`[roundhouse] soft flush for thread=${tid} (lock released, running async)`);
+      try {
+        await this.handleContextPressure(t, tid, a, mr, "soft");
+      } catch (err) {
+        console.error(`[roundhouse] soft flush error:`, (err as Error).message);
+      } finally {
+        this.flushInProgress.delete(tid);
+      }
+    }
   }
 
   /**
@@ -632,18 +660,19 @@ export class Gateway {
 
   /**
    * Handle context pressure — flush memory and/or compact.
-   * Runs inside the thread lock after a turn completes.
+   * Soft: runs OUTSIDE the thread lock (non-blocking to user messages).
+   * Hard/emergency: runs INSIDE the thread lock (memory state invariants).
    */
   private async handleContextPressure(thread: any, agentThreadId: string, agent: AgentAdapter, memoryRoot: string, pressure: PressureLevel) {
     if (pressure === "none") return;
 
-    console.log(`[roundhouse] context pressure: ${pressure} for thread=${thread.id} agentThread=${agentThreadId}`);
-
     if (pressure === "soft") {
       // Soft: prompt agent to save facts, no compact
       // Cooldown is checked inside flushMemoryThenCompact (returns null if skipped)
       try {
-        await flushMemoryThenCompact(agentThreadId, agent, memoryRoot, "soft", this.config.memory);
+        const result = await flushMemoryThenCompact(agentThreadId, agent, memoryRoot, "soft", this.config.memory);
+        // result is null if cooldown skipped OR if soft flush ran (soft always returns null)
+        // Log only — don't message user for soft flush (it's background housekeeping)
       } catch (err) {
         console.error(`[roundhouse] soft flush error:`, (err as Error).message);
       }
@@ -700,6 +729,111 @@ export class Gateway {
     };
   }
 
+  /**
+   * Build the full list of command descriptors.
+   *
+   * Each descriptor self-describes its triggers, dispatch stage, argument
+   * acceptance, and optional inline-keyboard action handlers. The gateway
+   * iterates this list — no per-command branching in the message handler.
+   *
+   * Stage:
+   *   - "in-turn" (default): runs after allowlist + pairing inside handle()
+   *   - "pre-turn": runs first in handleOrAbort() so commands like /stop
+   *     can interrupt an in-flight agent turn
+   *
+   * Per-request state (thread, message, text) comes in via CommandInvocation;
+   * long-lived deps (cronScheduler, verboseThreads, abortControllers, …) are
+   * captured here from the surrounding start() closure.
+   */
+  private buildCommandDescriptors(deps: {
+    allowedUsers: string[];
+    allowedUserIds: number[];
+    verboseThreads: Set<string>;
+    threadLocks: Map<string, Promise<void>>;
+    abortControllers: Map<string, AbortController>;
+  }): CommandDescriptor[] {
+    const { allowedUsers, allowedUserIds, verboseThreads, threadLocks, abortControllers } = deps;
+    const post = (t: any, txt: string) => this.postWithFallback(t, txt);
+
+    // Shorthand: wrap a standard-CommandContext handler as a descriptor invoker.
+    const withCtx = (handler: (ctx: CommandContext) => Promise<void>) =>
+      async ({ thread, message, agentThreadId }: CommandInvocation) => {
+        const authorName = message.author?.userName ?? message.author?.userId ?? "?";
+        await handler(this.buildCommandContext(
+          thread, message, agentThreadId, authorName,
+          allowedUsers, allowedUserIds, verboseThreads, threadLocks,
+        ));
+      };
+
+    return [
+      // ── Standard CommandContext commands (in-turn, no args) ──
+      { triggers: ["/new"],     invoke: withCtx(handleNew) },
+      { triggers: ["/restart"], invoke: withCtx(handleRestart) },
+      { triggers: ["/update"],  invoke: withCtx(handleUpdate) },
+      { triggers: ["/compact"], invoke: withCtx(handleCompact) },
+      { triggers: ["/status"],  invoke: withCtx(handleStatus) },
+
+      // ── In-turn commands that accept args ──
+      {
+        triggers: ["/model"],
+        acceptsArgs: true,
+        invoke: ({ thread, text }) => handleModel({ thread, text, postWithFallback: post }),
+        actions: {
+          [MODEL_ACTION_ID]: (ev) => handleModelAction({ value: ev.value, thread: ev.thread }),
+        },
+      },
+      {
+        triggers: ["/later"],
+        acceptsArgs: true,
+        invoke: ({ thread, text }) => handleLater({ thread, text, postWithFallback: post }),
+      },
+      {
+        triggers: ["/topic"],
+        acceptsArgs: true,
+        invoke: ({ thread, text }) => handleTopic({ thread, text, postWithFallback: post }),
+        actions: {
+          [TOPIC_ACTION_ID]: (ev) => handleTopicAction({ value: ev.value, thread: ev.thread }),
+        },
+      },
+
+      // ── Pre-turn commands (abort-style; fire even during agent turn) ──
+      {
+        triggers: ["/stop"],
+        stage: "pre-turn",
+        invoke: ({ thread, agentThreadId }) => handleStop({
+          thread, agentThreadId,
+          agent: this.router.resolve(agentThreadId),
+          abortControllers,
+        }),
+      },
+      {
+        triggers: ["/verbose"],
+        stage: "pre-turn",
+        invoke: ({ thread, agentThreadId }) => handleVerbose({
+          thread, agentThreadId, verboseThreads,
+        }),
+      },
+      {
+        triggers: ["/doctor"],
+        stage: "pre-turn",
+        invoke: ({ thread }) => handleDoctor({
+          thread, runDoctor, createDoctorContext, formatDoctorTelegram,
+          postWithFallback: post,
+        }),
+      },
+      {
+        triggers: ["/crons", "/jobs"],
+        stage: "pre-turn",
+        acceptsArgs: true,
+        invoke: ({ thread, text }) => handleCrons({
+          thread, text,
+          cronScheduler: this.cronScheduler,
+          postWithFallback: post,
+        }),
+      },
+    ];
+  }
+
   private async handleStreaming(thread: any, stream: AsyncIterable<AgentStreamEvent>, verbose: boolean, signal?: AbortSignal): Promise<{ usedTools: boolean }> {
     return _handleStream(stream, {
       thread,
@@ -715,7 +849,7 @@ export class Gateway {
       await this.transport.postMessage(thread, text);
       return;
     }
-    for (const chunk of splitMessage(text, 4000)) {
+    for (const chunk of splitMessage(text, MAX_MESSAGE_CHUNK)) {
       try {
         await thread.post({ markdown: chunk });
       } catch {
@@ -754,7 +888,7 @@ export class Gateway {
     const now = new Date().toISOString().replace("T", " ").slice(0, 19) + " UTC";
     const nodeVer = process.version;
     const memMB = (process.memoryUsage.rss() / 1024 / 1024).toFixed(1);
-    const sys = getSystemResources();
+    const sys = _getSysRes();
 
     // Get agent info if available (use first resolve — SingleAgentRouter always returns same agent)
     let agentInfo = "";
@@ -843,21 +977,44 @@ export class Gateway {
     console.log("[roundhouse] stopped");
   }
 
-  /** Handle sub-agent completion — post result to originating thread */
+  /** Handle sub-agent completion — notify user AND inject result into agent session */
   private async handleSubagentCompletion(status: RunStatus, routing: RoutingInfo): Promise<void> {
+    const chatId = Number(routing.chatId);
+    if (!chatId) return;
+
+    await this.notifySubagentResult(status, chatId);
+    await this.injectSubagentResult(status, chatId);
+  }
+
+  /** Notify user of sub-agent completion via transport */
+  private async notifySubagentResult(status: RunStatus, chatId: number): Promise<void> {
     const emoji = status.status === "complete" ? "✅" : status.status === "timeout" ? "⏰" : "❌";
     const duration = status.completedAt && status.startedAt
       ? Math.round((Date.parse(status.completedAt) - Date.parse(status.startedAt)) / 1000)
       : 0;
-    const summary = `${emoji} <b>Sub-agent ${status.status}</b> (${status.role})\n⏱ ${duration}s | run: <code>${status.runId.slice(0, 8)}</code>`;
-
+    const summary = `${emoji} **Sub-agent ${status.status}** (${status.role})\n⏱ ${duration}s | run: \`${status.runId.slice(0, 8)}\``;
     try {
-      const chatId = Number(routing.chatId);
-      if (chatId) {
-        await this.transport.notify([chatId], summary, { parseMode: "HTML" });
-      }
+      await this.transport.notify([chatId], summary);
     } catch (err) {
       console.error("[roundhouse] sub-agent completion notification failed:", err);
     }
   }
+
+  /** Inject sub-agent output into agent session as synthetic turn */
+  private async injectSubagentResult(status: RunStatus, chatId: number): Promise<void> {
+    try {
+      const runDir = join(process.env.HOME || "/home/ec2-user", ".roundhouse", "subagents", status.runId);
+      let stdout = "";
+      try { stdout = await readFile(join(runDir, "stdout.log"), "utf-8"); } catch {}
+
+      const resultText = stdout.trim()
+        ? `[Sub-agent ${status.role} completed (${status.status})]\n\nResult:\n${stdout.trim().slice(0, MAX_SUBAGENT_STDOUT_CHARS)}`
+        : `[Sub-agent ${status.role} ${status.status} — no output]`;
+
+      const syntheticThread = this.transport.createThread(chatId);
+      await this.handleAgentTurn(syntheticThread, "main", resultText, [], this.verboseThreads, this.threadLocks, this.abortControllers);
+    } catch (err) {
+      console.error("[roundhouse] sub-agent result injection failed:", err);
+    }
+  }
 }

package/src/gateway/inline-keyboard.ts

@@ -0,0 +1,64 @@
+/**
+ * gateway/inline-keyboard.ts — Shared helpers for Telegram inline keyboards
+ *
+ * Centralizes the callback-data protocol used by @chat-adapter/telegram so
+ * that commands like /model and /topic stay in sync. If the adapter's prefix
+ * ever changes, update it here once and every command keeps working.
+ */
+
+/**
+ * Callback data prefix used by @chat-adapter/telegram.
+ *
+ * COUPLING: this must match the prefix the adapter listens for when routing
+ * `callback_query` events to `chat.onAction(...)`. If the adapter package
+ * changes this protocol, buttons silently stop working — watch this constant
+ * during adapter upgrades.
+ */
+export const CALLBACK_PREFIX = "chat:";
+
+export interface InlineButton {
+  text: string;
+  callback_data: string;
+}
+
+export interface InlineKeyboard {
+  inline_keyboard: InlineButton[][];
+}
+
+/** Encode an action+value pair into a Telegram `callback_data` string. */
+export function encodeCallbackData(actionId: string, value: string): string {
+  return `${CALLBACK_PREFIX}${JSON.stringify({ a: actionId, v: value })}`;
+}
+
+/**
+ * Chunk a flat list of buttons into rows for a compact keyboard layout.
+ * Default is 2 columns, matching /model and /topic.
+ */
+export function toKeyboardRows(buttons: InlineButton[], columns = 2): InlineKeyboard {
+  const rows: InlineButton[][] = [];
+  for (let i = 0; i < buttons.length; i += columns) {
+    rows.push(buttons.slice(i, i + columns));
+  }
+  return { inline_keyboard: rows };
+}
+
+/**
+ * Minimal shape of a thread passed to command handlers. Captures just the
+ * fields both /model and /topic need — avoids `any` without dragging in
+ * the full Chat SDK types.
+ */
+export interface ChatThreadLike {
+  id?: string;
+  platformThreadId?: string;
+  /** Present on Telegram threads; undefined on other transports. */
+  adapter?: {
+    telegramFetch?: (method: string, payload: Record<string, unknown>) => Promise<unknown>;
+  };
+  /** Post a message back to the thread; accepts raw text or `{ markdown }`. */
+  post?: (arg: string | { markdown: string }) => Promise<unknown>;
+}
+
+/** Extract the numeric Telegram chat id from a thread's id string. */
+export function extractTelegramChatId(thread: ChatThreadLike | undefined): string | undefined {
+  return thread?.platformThreadId?.split(":")?.[1] ?? thread?.id?.split(":")?.[1];
+}

package/src/gateway/model-command.ts

@@ -11,6 +11,13 @@
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import {
+  encodeCallbackData,
+  toKeyboardRows,
+  extractTelegramChatId,
+  type InlineButton,
+  type InlineKeyboard,
+} from "./inline-keyboard";
 
 /** Known model aliases → Bedrock model IDs */
 export const MODEL_ALIASES: Record<string, { provider: string; model: string; label: string }> = {
@@ -40,9 +47,6 @@ export const MODEL_ACTION_ID = "model_select";
 
 const SETTINGS_PATH = join(homedir(), ".pi", "agent", "settings.json");
 
-/** Callback data prefix used by @chat-adapter/telegram (coupled: if adapter changes this, buttons break) */
-const CALLBACK_PREFIX = "chat:";
-
 export interface ModelCommandContext {
   thread: any;
   text: string;
@@ -71,24 +75,16 @@ function getCurrentModel(settings: Record<string, any>): string {
   return `${model}`;
 }
 
-function encodeCallbackData(actionId: string, value: string): string {
-  return `${CALLBACK_PREFIX}${JSON.stringify({ a: actionId, v: value })}`;
-}
-
-function buildInlineKeyboard(): { inline_keyboard: Array<Array<{ text: string; callback_data: string }>> } {
+function buildInlineKeyboard(): InlineKeyboard {
   // Layout: 2 buttons per row for compact display
-  const buttons = KEYBOARD_MODELS.map(alias => {
+  const buttons: InlineButton[] = KEYBOARD_MODELS.map(alias => {
     const info = MODEL_ALIASES[alias];
     return {
       text: info.label,
       callback_data: encodeCallbackData(MODEL_ACTION_ID, alias),
     };
   });
-  const rows: Array<Array<{ text: string; callback_data: string }>> = [];
-  for (let i = 0; i < buttons.length; i += 2) {
-    rows.push(buttons.slice(i, i + 2));
-  }
-  return { inline_keyboard: rows };
+  return toKeyboardRows(buttons);
 }
 
 export async function handleModel(ctx: ModelCommandContext): Promise<void> {
@@ -106,7 +102,7 @@ export async function handleModel(ctx: ModelCommandContext): Promise<void> {
     // Try to send with inline keyboard via telegramFetch
     const adapter = thread?.adapter;
     if (adapter?.telegramFetch) {
-      const chatId = thread?.platformThreadId?.split(":")?.[1] ?? thread?.id?.split(":")?.[1];
+      const chatId = extractTelegramChatId(thread);
       if (chatId) {
         try {
           await adapter.telegramFetch("sendMessage", {