@inceptionstack/roundhouse 0.5.4 → 0.5.7

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/voice/providers/whisper.ts

@@ -2,7 +2,7 @@
  * voice/providers/whisper.ts — Local Whisper STT provider
  *
  * Runs the whisper CLI via child_process. Auto-detects language.
- * Can auto-install whisper via pip3 and warm the model on first use.
+ * Reports missing dependencies so the agent can install them.
  */
 
 import { execFile } from "node:child_process";
@@ -21,6 +21,12 @@ const WHISPER_PATHS = [
   "/usr/bin/whisper",
 ];
 
+const FFMPEG_PATHS = [
+  join(homedir(), ".local", "bin", "ffmpeg"),
+  "/usr/local/bin/ffmpeg",
+  "/usr/bin/ffmpeg",
+];
+
 let cachedBinaryPath: string | null | undefined; // undefined = not checked yet
 
 async function findWhisperBinary(): Promise<string | null> {
@@ -33,80 +39,22 @@ async function findWhisperBinary(): Promise<string | null> {
       return p;
     } catch {}
   }
-  cachedBinaryPath = null;
+  // Don't cache null — allows detection after agent installs whisper
   return null;
 }
 
-/** Reset cached path so next findWhisperBinary() re-scans */
-function invalidateCache(): void {
-  cachedBinaryPath = undefined;
-}
-
-// ── Auto-install ─────────────────────────────────────
-
-let pipAvailable: boolean | undefined;
-
-async function checkPip(): Promise<boolean> {
-  if (pipAvailable !== undefined) return pipAvailable;
-  return new Promise<boolean>((resolve) => {
-    execFile("pip3", ["--version"], { timeout: 5000 }, (err) => {
-      pipAvailable = !err;
-      resolve(pipAvailable);
-    });
-  });
-}
-
-/**
- * Install whisper via pip3 --user. Returns the binary path or null on failure.
- */
-async function installWhisperWithPip(): Promise<string | null> {
-  if (!(await checkPip())) {
-    console.warn("[stt/whisper] pip3 not available — cannot auto-install whisper");
-    return null;
+async function findFfmpeg(): Promise<string | null> {
+  for (const p of FFMPEG_PATHS) {
+    try {
+      await access(p, constants.X_OK);
+      return p;
+    } catch {}
   }
+  return null;
+}
 
-  console.log("[stt/whisper] installing openai-whisper via pip3...");
-  return new Promise<string | null>((resolve) => {
-    execFile(
-      "pip3",
-      ["install", "--user", "openai-whisper"],
-      {
-        timeout: 300_000, // 5 min for install
-        maxBuffer: 10 * 1024 * 1024, // 10MB for pip output
-        env: { ...process.env },
-      },
-      async (err, stdout, stderr) => {
-        if (err) {
-          console.error("[stt/whisper] pip3 install failed:", err.message);
-          if (stderr) console.error("[stt/whisper] stderr:", stderr.slice(0, 500));
-          resolve(null);
-          return;
-        }
-        console.log("[stt/whisper] pip3 install succeeded");
-
-        // Re-discover binary
-        invalidateCache();
-        const binary = await findWhisperBinary();
-        if (!binary) {
-          console.error("[stt/whisper] installed but binary not found in expected paths");
-          resolve(null);
-          return;
-        }
 
-        // Validate with --help
-        execFile(binary, ["--help"], { timeout: 10_000 }, (helpErr) => {
-          if (helpErr) {
-            console.error("[stt/whisper] binary found but --help failed:", helpErr.message);
-            resolve(null);
-          } else {
-            console.log(`[stt/whisper] validated binary at ${binary}`);
-            resolve(binary);
-          }
-        });
-      },
-    );
-  });
-}
+// ── Model warmup ─────────────────────────────────────
 
 /**
  * Warm the whisper model by running a tiny transcription.
@@ -171,19 +119,15 @@ async function warmWhisperModel(binary: string, model: string): Promise<boolean>
 
 // ── Provider ─────────────────────────────────────────
 
-/** Extended provider with install capability */
+/** Extended provider that reports missing dependencies */
 export interface InstallableWhisperProvider extends SttProvider {
   ensureInstalled(): Promise<boolean>;
+  getMissingDeps(): Promise<string[]>;
 }
 
-// Singleton promises to prevent concurrent installs
-let installPromise: Promise<string | null> | null = null;
-let installFailed = false; // sticky failure to prevent retry spam
-
 export function createWhisperProvider(config: SttProviderConfig): InstallableWhisperProvider {
   const model = (config.model as string) ?? "small";
   const timeoutMs = config.timeoutMs ?? 30000;
-  const autoInstall = config.autoInstall === true; // explicit opt-in only
   let modelWarmed = false;
   let warmFailed = false; // sticky failure to prevent warmup retry spam
   let warmPromise: Promise<boolean> | null = null;
@@ -191,24 +135,14 @@ export function createWhisperProvider(config: SttProviderConfig): InstallableWhi
   const WHISPER_LANGS = new Set(["af","am","ar","as","az","ba","be","bg","bn","bo","br","bs","ca","cs","cy","da","de","el","en","es","et","eu","fa","fi","fo","fr","gl","gu","ha","haw","he","hi","hr","ht","hu","hy","id","is","it","ja","jw","ka","kk","km","kn","ko","la","lb","ln","lo","lt","lv","mg","mi","mk","ml","mn","mr","ms","mt","my","ne","nl","nn","no","oc","pa","pl","ps","pt","ro","ru","sa","sd","si","sk","sl","sn","so","sq","sr","su","sv","sw","ta","te","tg","th","tk","tl","tr","tt","uk","ur","uz","vi","yi","yo","yue","zh"]);
 
   async function getBinary(): Promise<string | null> {
-    // Check if already available
     const existing = await findWhisperBinary();
-    if (existing) return existing;
-
-    // Try auto-install
-    if (!autoInstall) return null;
-    if (installFailed) return null; // sticky failure — don't retry every message
-
-    // Singleton: join existing install or start new one
-    if (!installPromise) {
-      installPromise = installWhisperWithPip().then((result) => {
-        if (!result) installFailed = true;
-        return result;
-      }).finally(() => {
-        installPromise = null;
-      });
-    }
-    return installPromise;
+    if (!existing) return null;
+
+    // Also need ffmpeg
+    const ffmpeg = await findFfmpeg();
+    if (!ffmpeg) return null;
+
+    return existing;
   }
 
   return {
@@ -218,6 +152,15 @@ export function createWhisperProvider(config: SttProviderConfig): InstallableWhi
       return input.mime.startsWith("audio/");
     },
 
+    async getMissingDeps(): Promise<string[]> {
+      const missing: string[] = [];
+      const whisper = await findWhisperBinary();
+      if (!whisper) missing.push("whisper");
+      const ffmpeg = await findFfmpeg();
+      if (!ffmpeg) missing.push("ffmpeg");
+      return missing;
+    },
+
     async ensureInstalled(): Promise<boolean> {
       const binary = await getBinary();
       if (!binary) return false;
@@ -236,7 +179,7 @@ export function createWhisperProvider(config: SttProviderConfig): InstallableWhi
               }
             } catch {}
 
-            // Run warmup — catch everything so it never rejects
+            // Run warmup
             try {
               const ok = await warmWhisperModel(binary, model);
               if (!ok) warmFailed = true;
@@ -258,7 +201,7 @@ export function createWhisperProvider(config: SttProviderConfig): InstallableWhi
     async transcribe(input: SttInput): Promise<TranscriptionResult> {
       const binary = await getBinary();
       if (!binary) {
-        throw new Error("whisper not available and auto-install failed");
+        throw new Error("whisper or ffmpeg not available");
       }
 
       const outputDir = join(homedir(), ".roundhouse", "whisper-tmp", randomBytes(6).toString("hex"));

package/src/voice/stt-service.ts

@@ -19,7 +19,6 @@ export class SttService {
   private config: SttConfig;
   private initPromise: Promise<void> | null = null;
   private activeStt: Promise<void> = Promise.resolve(); // global concurrency: 1 at a time
-  private installNoticeSent = false;
 
   constructor(config: SttConfig) {
     this.config = config;
@@ -52,12 +51,7 @@ export class SttService {
       }
 
       try {
-        // Pass autoInstall from service-level config into provider config
-        const mergedProviderConfig = {
-          ...providerConfig,
-          autoInstall: providerConfig.autoInstall ?? this.config.autoInstall ?? false,
-        };
-        this.providers.push(factory(mergedProviderConfig));
+        this.providers.push(factory(providerConfig));
         console.log(`[stt] loaded provider: ${providerName} (${type})`);
       } catch (err) {
         console.warn(`[stt] failed to create provider "${providerName}":`, (err as Error).message);
@@ -97,6 +91,34 @@ export class SttService {
     }
   }
 
+  /**
+   * Check which STT dependencies are missing.
+   * Returns empty array if everything is installed, or names like ["whisper", "ffmpeg"].
+   * Note: returns assumed deps when no providers loaded (safe fallback for default config).
+   */
+  async getMissingDeps(): Promise<string[]> {
+    try {
+      await this.ensureInitialized();
+    } catch {
+      return ["whisper", "ffmpeg"]; // Can't initialize = assume all missing
+    }
+
+    if (this.providers.length === 0) {
+      // No providers loaded — most likely whisper not installed (default config uses whisper).
+      // Config typos are logged during doInit(); agent install prompt is a safe fallback.
+      return ["whisper", "ffmpeg"];
+    }
+
+    // Returns deps from first provider that supports getMissingDeps (single-provider today)
+    for (const provider of this.providers) {
+      const installable = provider as InstallableWhisperProvider;
+      if (installable.getMissingDeps && typeof installable.getMissingDeps === "function") {
+        return installable.getMissingDeps();
+      }
+    }
+    return [];
+  }
+
   /** Should this attachment be auto-transcribed? */
   shouldTranscribe(attachment: MessageAttachment): boolean {
     if (!this.config.enabled || this.config.mode === "off") return false;
@@ -141,7 +163,7 @@ export class SttService {
         const duration = await getAudioDuration(attachment.localPath);
         if (duration !== null && duration > maxDuration) {
           console.log(`[stt] skipping ${attachment.name}: duration ${duration.toFixed(1)}s exceeds ${maxDuration}s limit`);
-          return null;
+          return { text: "", provider: "none", approximate: true as const, status: "skipped" as const, error: `Duration ${duration.toFixed(0)}s exceeds ${maxDuration}s limit` };
         }
       } catch {}
     }
@@ -169,18 +191,12 @@ export class SttService {
       for (const provider of this.providers) {
         if (!provider.canTranscribe(input)) continue;
 
-        // Ensure provider is installed (with one-time user notification)
+        // Ensure provider is installed
         const installable = provider as InstallableWhisperProvider;
         if (installable.ensureInstalled && typeof installable.ensureInstalled === "function") {
           try {
             const isReady = await installable.ensureInstalled();
-            if (!isReady) {
-              if (!this.installNoticeSent && notify) {
-                this.installNoticeSent = true;
-                try { await notify("🎤 Voice transcription not available. Whisper install or model download failed."); } catch {}
-              }
-              continue;
-            }
+            if (!isReady) continue;
           } catch {
             continue;
           }
@@ -239,6 +255,9 @@ export async function enrichAttachmentsWithTranscripts(
       const transcript = await sttService.tryTranscribe(att, undefined, notify);
       if (transcript) {
         att.transcript = transcript;
+      } else if (att.mediaType === "audio" && sttService.shouldTranscribe(att)) {
+        // Mark as failed so gateway can detect and act
+        att.transcript = { text: "", provider: "none", approximate: true, status: "failed", error: "No STT provider available" };
       }
     } catch (err) {
       console.error(`[stt] unexpected error transcribing ${att.name}:`, (err as Error).message);
@@ -267,7 +286,6 @@ async function getAudioDuration(filePath: string): Promise<number | null> {
 export const DEFAULT_STT_CONFIG: SttConfig = {
   enabled: true,
   mode: "on",
-  autoInstall: true,
   chain: ["whisper"],
   autoTranscribe: {
     voiceMessages: true,

package/src/voice/types.ts

@@ -35,7 +35,7 @@ export interface AttachmentTranscript {
   language?: string;
   confidence?: number;
   approximate: true;
-  status: "completed" | "failed";
+  status: "completed" | "failed" | "skipped";
   error?: string;
   durationMs?: number;
 }
@@ -45,14 +45,12 @@ export interface AttachmentTranscript {
 export interface SttProviderConfig {
   type: string;
   timeoutMs?: number;
-  autoInstall?: boolean;
   [key: string]: unknown;
 }
 
 export interface SttConfig {
   enabled: boolean;
   mode: "on" | "off";
-  autoInstall?: boolean;
   chain: string[];
   autoTranscribe: {
     voiceMessages: boolean;

package/src/commands/update.ts

@@ -1,69 +0,0 @@
-/**
- * commands/update.ts — Handle the /update command
- *
- * Transport-agnostic: receives a ProgressReporter interface,
- * not a Telegram-specific thread object.
- */
-
-import { homedir } from "node:os";
-import { execSync } from "node:child_process";
-import { readFileSync, writeFileSync } from "node:fs";
-import { provisionBundle } from "../bundle";
-
-export interface UpdateProgress {
-  update(text: string): Promise<void>;
-}
-
-export interface UpdateResult {
-  action: "already-latest" | "updated";
-  currentVersion: string;
-  latestVersion?: string;
-}
-
-/**
- * Check for updates, install if newer, provision bundle, patch settings.
- * Returns the result — caller decides how to present it and whether to restart.
- */
-export async function performUpdate(progress: UpdateProgress): Promise<UpdateResult> {
-  // Get current version
-  const pkg = await import("../../package.json", { with: { type: "json" } });
-  const currentVersion = pkg.default?.version ?? "unknown";
-
-  // Check latest version on npm
-  const latestVersion = execSync("npm view @inceptionstack/roundhouse version 2>/dev/null", {
-    timeout: 30_000,
-    encoding: "utf8",
-  }).trim();
-
-  if (!latestVersion || latestVersion === currentVersion) {
-    return { action: "already-latest", currentVersion };
-  }
-
-  await progress.update(`📦 Updating v${currentVersion} → v${latestVersion}...`);
-
-  execSync("npm install -g @inceptionstack/roundhouse@latest 2>&1", {
-    timeout: 120_000,
-    encoding: "utf8",
-  });
-
-  // Provision bundle (skills sync + CLI tools + config)
-  try {
-    provisionBundle();
-  } catch (e) {
-    console.warn("[roundhouse] bundle provisioning failed:", e instanceof Error ? e.message : e);
-  }
-
-  // Ensure settings.json includes roundhouse package (for pre-bundle upgrades)
-  try {
-    const settingsPath = `${homedir()}/.pi/agent/settings.json`;
-    const settings = JSON.parse(readFileSync(settingsPath, "utf8"));
-    const selfPkg = "npm:@inceptionstack/roundhouse";
-    if (!Array.isArray(settings.packages)) settings.packages = [];
-    if (!settings.packages.includes(selfPkg)) {
-      settings.packages.push(selfPkg);
-      writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
-    }
-  } catch { /* settings.json may not exist yet — fine, setup will create it */ }
-
-  return { action: "updated", currentVersion, latestVersion };
-}