@inceptionstack/roundhouse 0.5.5 → 0.5.8

package/README.md

@@ -188,7 +188,6 @@ Without a config file, defaults are used with env vars (`TELEGRAM_BOT_TOKEN`, `B
 | `chat.notifyChatIds` | Telegram chat IDs to notify on startup (env: `NOTIFY_CHAT_IDS`) |
 | `chat.adapters.telegram` | `{ "mode": "polling" \| "webhook" \| "auto" }` |
 | `voice.stt.enabled` | Enable automatic voice transcription (default: off unless configured) |
-| `voice.stt.autoInstall` | Auto-install whisper via pip3 if missing (default: false) |
 | `voice.stt.chain` | STT provider chain, e.g. `["whisper"]` |
 | `voice.stt.providers.whisper` | `{ "model": "small", "timeoutMs": 30000 }` |
 
@@ -307,7 +306,7 @@ Roundhouse can automatically transcribe voice messages using [OpenAI Whisper](ht
 pip install openai-whisper
 ```
 
-Or set `autoInstall: true` in config to have roundhouse install whisper automatically on first voice message.
+If whisper/ffmpeg aren't installed when a voice message arrives, roundhouse automatically injects a prompt into the agent's turn asking it to install the missing dependencies. The user is notified that setup is in progress.
 
 **Enable in config:**
 ```json
@@ -316,7 +315,6 @@ Or set `autoInstall: true` in config to have roundhouse install whisper automati
     "stt": {
       "enabled": true,
       "mode": "on",
-      "autoInstall": true,
       "chain": ["whisper"],
       "autoTranscribe": {
         "voiceMessages": true,

package/architecture.md

@@ -192,7 +192,6 @@ gateway.config.json
     └── stt
         ├── enabled: true
         ├── mode: "on" | "off"
-        ├── autoInstall: false   # auto-install whisper via pip3
         ├── chain: ["whisper"]    # Provider chain (try in order)
         ├── autoTranscribe
         │   ├── voiceMessages: true

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inceptionstack/roundhouse",
-  "version": "0.5.5",
+  "version": "0.5.8",
   "type": "module",
   "description": "Multi-platform chat gateway that routes messages through a configured AI agent",
   "license": "MIT",

package/src/cli/cli.ts

@@ -155,6 +155,11 @@ async function cmdUpdate() {
     return;
   }
 
+  if (result.action === "error") {
+    console.error(`[roundhouse] Update failed: ${result.error}`);
+    process.exit(1);
+  }
+
   console.log(`[roundhouse] Updated to v${result.latestVersion}`);
 
   const svc = getServiceManager();
@@ -365,6 +370,7 @@ Commands:
   doctor [--fix]       Check system health and configuration
                        Options: --fix, --json, --verbose
   cron <command>       Manage scheduled jobs (add, list, trigger, etc.)
+  message "text"       Send a message to active transports via gateway
 
 Config:
   ~/.roundhouse/gateway.config.json
@@ -383,6 +389,7 @@ import { cmdDoctor } from "./doctor";
 import { cmdAgent } from "./agent-command";
 import { cmdCron } from "./cron";
 import { cmdSetup, cmdPair } from "./setup";
+import { cmdMessage } from "./message";
 
 const command = process.argv[2];
 
@@ -402,6 +409,7 @@ const commands: Record<string, () => void | Promise<void>> = {
   tui: cmdTui,
   doctor: () => cmdDoctor(process.argv.slice(3)),
   cron: () => cmdCron(process.argv.slice(3)),
+  message: () => cmdMessage(process.argv.slice(3)),
   agent: cmdAgent,
 };
 

package/src/cli/doctor/checks/system.ts

@@ -34,7 +34,7 @@ export const systemChecks: DoctorCheck[] = [
     return {
       id: "pip3", category: "system", name: "pip3", summary: ver ? ver.split(" ")[1] ?? ver : "not found",
       status: ver ? "pass" : "warn",
-      details: !ver ? ["Needed for whisper STT auto-install"] : undefined,
+      details: !ver ? ["Used by agent to install whisper for STT"] : undefined,
     };
   }),
 

package/src/cli/message.ts

@@ -0,0 +1,41 @@
+/**
+ * cli/message.ts — Send a message to the running gateway via IPC
+ *
+ * Usage:
+ *   roundhouse message "Hello from CLI"
+ *   roundhouse message --session main "Hello"
+ */
+
+import { sendIpc } from "../ipc";
+
+export async function cmdMessage(args: string[]): Promise<void> {
+  let session: string | undefined;
+  const positional: string[] = [];
+
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--session" && args[i + 1]) {
+      session = args[++i];
+    } else {
+      positional.push(args[i]);
+    }
+  }
+
+  const text = positional.join(" ").trim();
+  if (!text) {
+    console.error('Usage: roundhouse message [--session <name>] "<message>"');
+    process.exit(1);
+  }
+
+  try {
+    const response = await sendIpc({ type: "notify", text, session });
+    if (response.ok) {
+      console.log("✅ Message delivered to gateway");
+    } else {
+      console.error(`❌ ${response.error}`);
+      process.exit(1);
+    }
+  } catch (err: any) {
+    console.error(`❌ ${err.message}`);
+    process.exit(1);
+  }
+}

package/src/cli/setup/steps.ts

@@ -603,8 +603,8 @@ export async function stepPostflight(logger: StepLog): Promise<void> {
 
   if (platform() === "linux" || process.env.ROUNDHOUSE_VOICE === "1") {
     if (!whichSync("whisper")) {
-      logger.warn("whisper not found — STT will auto-install on first voice message");
-      logger.log("    Pre-install: pip3 install openai-whisper");
+      logger.warn("whisper not found — agent will be prompted to install on first voice message");
+      logger.log("    Or pre-install manually: pip3 install --user openai-whisper");
     } else {
       logger.ok("whisper available");
     }

package/src/cli/update.ts

@@ -10,14 +10,20 @@ import { execSync } from "node:child_process";
 import { readFileSync, writeFileSync } from "node:fs";
 import { provisionBundle } from "../provisioning/bundle";
 
+const GLOBAL_PI_EXTENSION_PACKAGES = [
+  "@inceptionstack/pi-hard-no",
+  "@inceptionstack/pi-branch-enforcer",
+];
+
 export interface UpdateProgress {
   update(text: string): Promise<void>;
 }
 
 export interface UpdateResult {
-  action: "already-latest" | "updated";
+  action: "already-latest" | "updated" | "error";
   currentVersion: string;
   latestVersion?: string;
+  error?: string;
 }
 
 /**
@@ -30,21 +36,57 @@ export async function performUpdate(progress: UpdateProgress): Promise<UpdateRes
   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();
+  let latestVersion: string;
+  try {
+    latestVersion = execSync("npm view @inceptionstack/roundhouse version 2>/dev/null", {
+      timeout: 30_000,
+      encoding: "utf8",
+    }).trim();
+  } catch (e) {
+    // Update extensions anyway, but flag that version check failed
+    latestVersion = "";
+    console.warn("[roundhouse] npm view failed:", e instanceof Error ? e.message : e);
+  }
 
-  if (!latestVersion || latestVersion === currentVersion) {
+  // Always update extensions (even if roundhouse is already latest)
+  if (!latestVersion) {
+    await progress.update(`⚠️ Version check failed — updating extensions only`);
+  }
+  for (const extensionPackage of GLOBAL_PI_EXTENSION_PACKAGES) {
+    await progress.update(`📦 Updating extension: ${extensionPackage}...`);
+
+    try {
+      execSync(`npm install -g ${extensionPackage}@latest 2>&1`, {
+        timeout: 60_000,
+        encoding: "utf8",
+      });
+      await progress.update(`✅ ${extensionPackage} updated`);
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e);
+      console.warn(`[roundhouse] failed to update extension ${extensionPackage}:`, msg);
+      await progress.update(`⚠️ Failed to update ${extensionPackage}: ${msg.slice(0, 150)}`);
+    }
+  }
+
+  if (!latestVersion) {
+    return { action: "error", currentVersion, error: "Version check failed (extensions updated)" };
+  }
+  if (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",
-  });
+  try {
+    execSync("npm install -g @inceptionstack/roundhouse@latest 2>&1", {
+      timeout: 120_000,
+      encoding: "utf8",
+    });
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    console.warn("[roundhouse] self-update failed:", msg);
+    return { action: "error", currentVersion, error: `Self-update failed: ${msg}` };
+  }
 
   // Provision bundle (skills sync + CLI tools + config)
   try {

package/src/gateway/commands.ts

@@ -75,6 +75,8 @@ export async function handleUpdate(ctx: CommandContext): Promise<void> {
     const result = await performUpdate(progress);
     if (result.action === "already-latest") {
       await progress.update(`✅ Already on latest (v${result.currentVersion})`);
+    } else if (result.action === "error") {
+      await progress.update(`⚠️ ${(result.error ?? "Update failed").slice(0, 200)}`);
     } else if (result.action === "updated") {
       await progress.update(`✅ Updated v${result.currentVersion} → v${result.latestVersion}. Restarting...`);
       console.log(`[roundhouse] updated ${result.currentVersion} -> ${result.latestVersion}, restarting`);
@@ -161,15 +163,37 @@ export async function handleStatus(ctx: CommandContext): Promise<void> {
   const nodeVer = process.version;
   const memMB = (process.memoryUsage.rss() / 1024 / 1024).toFixed(1);
 
+  // Check for available update (async, non-blocking)
+  let updateAvailable = "";
+  try {
+    const { exec } = await import("node:child_process");
+    const { promisify } = await import("node:util");
+    const execAsync = promisify(exec);
+    const { stdout } = await execAsync("npm view @inceptionstack/roundhouse version 2>/dev/null", { timeout: 10_000 });
+    const latest = stdout.trim().split("\n").pop()!.trim();
+    if (latest && /^\d+\.\d+\.\d+$/.test(latest) && latest !== ROUNDHOUSE_VERSION) {
+      // Simple semver comparison: split and compare numerically
+      const [lM, lm, lp] = latest.split(".").map(Number);
+      const [cM, cm, cp] = ROUNDHOUSE_VERSION.split(".").map(Number);
+      if (lM > cM || (lM === cM && lm > cm) || (lM === cM && lm === cm && lp > cp)) {
+        updateAvailable = latest;
+      }
+    }
+  } catch { /* network unavailable — skip */ }
+
   const info = agent.getInfo ? agent.getInfo(agentThreadId) : {};
   const agentVersion = info.version ? `v${info.version}` : "";
   const agentLabel = agentVersion ? `\`${agent.name}\` (${agentVersion})` : `\`${agent.name}\``;
 
+  const versionLine = updateAvailable
+    ? `📦 Roundhouse: v${ROUNDHOUSE_VERSION} → ⬆️ v${updateAvailable} available (/update)`
+    : `📦 Roundhouse: v${ROUNDHOUSE_VERSION}`;
+
   const lines = [
     `📊 *Roundhouse Status*`,
     ``,
     `🎫 Session: \`${agentThreadId}\``,
-    `📦 Roundhouse: v${ROUNDHOUSE_VERSION}`,
+    versionLine,
     `🤖 Agent: ${agentLabel}`,
   ];
 

package/src/gateway/gateway.ts

@@ -13,6 +13,7 @@ import { SttService, enrichAttachmentsWithTranscripts, DEFAULT_STT_CONFIG } from
 import { runDoctor, formatDoctorTelegram, createDoctorContext } from "../cli/doctor/runner";
 import { ROUNDHOUSE_DIR, ROUNDHOUSE_VERSION } from "../config";
 import { CronSchedulerService } from "../cron/scheduler";
+import { IpcServer, type IpcRequest } from "../ipc";
 import { prepareMemoryForTurn, finalizeMemoryForTurn, flushMemoryThenCompact } from "../memory/lifecycle";
 import { maxPressure } from "../memory/policy";
 import type { PressureLevel } from "../memory/types";
@@ -26,6 +27,7 @@ import { TelegramAdapter } from "../transports";
 import type { TransportAdapter } from "../transports";
 import { hostname } from "node:os";
 import { join } from "node:path";
+import { injectToolsSection } from "./tools-inject";
 
 /** Bot username for command suffix validation (set during gateway init) */
 let _botUsername = "";
@@ -81,6 +83,7 @@ export class Gateway {
   private pairingComplete = false;
   private sttService: SttService | null = null;
   private cronScheduler: CronSchedulerService | null = null;
+  private ipcServer: IpcServer | null = null;
 
   constructor(router: AgentRouter, config: GatewayConfig) {
     this.router = router;
@@ -166,7 +169,7 @@ export class Gateway {
     };
     if (sttConfig.enabled && sttConfig.mode !== "off") {
       this.sttService = new SttService(sttConfig);
-      console.log(`[roundhouse] STT enabled (chain: ${sttConfig.chain.join(" -> ")}, autoInstall: ${sttConfig.autoInstall ?? false})`);
+      console.log(`[roundhouse] STT enabled (chain: ${sttConfig.chain.join(" -> ")})`);
       // Prepare providers in background (install + warm model if needed)
       void this.sttService.prepareInBackground();
     }
@@ -329,6 +332,41 @@ export class Gateway {
       console.error("[roundhouse] cron scheduler start failed:", (err as Error).message);
     }
 
+    // Start IPC server for CLI → gateway communication
+    this.ipcServer = new IpcServer(async (req: IpcRequest) => {
+      if (req.type === "ping") return { ok: true };
+      if (req.type === "notify") {
+        const allChatIds = this.config.chat.notifyChatIds ?? [];
+        if (allChatIds.length === 0) return { ok: false, error: "No notifyChatIds configured" };
+
+        // Session routing:
+        //   "main" = first notifyChatId (primary user chat)
+        //   numeric string = that specific chat ID
+        //   anything else / undefined = broadcast to all notifyChatIds
+        let targetIds: number[];
+        if (req.session === "main") {
+          targetIds = [allChatIds[0]];
+        } else if (req.session && /^-?\d+$/.test(req.session)) {
+          targetIds = [Number(req.session)];
+        } else {
+          targetIds = allChatIds; // broadcast to all
+        }
+
+        try {
+          await this.transport.notify(targetIds, req.text);
+          return { ok: true };
+        } catch (e: any) {
+          return { ok: false, error: e.message };
+        }
+      }
+      return { ok: false, error: "Unknown request type" };
+    });
+    try {
+      await this.ipcServer.start();
+    } catch (err) {
+      console.error("[roundhouse] IPC server start failed:", (err as Error).message);
+    }
+
     // Send startup notification (after cron init so we can include job counts)
     await this.notifyStartup(platforms);
   }
@@ -371,6 +409,11 @@ export class Gateway {
         await this.enrichWithStt(thread, agentMessage);
       }
 
+      // Inject tools section (after STT enrichment so voice-only messages get it too)
+      if (agentMessage.text) {
+        agentMessage.text = injectToolsSection(agentMessage.text);
+      }
+
       // Let the agent adapter apply platform-specific message transforms
       if (agent.prepareMessage) {
         try {
@@ -455,19 +498,42 @@ export class Gateway {
   /**
    * Enrich audio attachments with speech-to-text transcripts.
    * Updates agentMessage.text for voice-only messages.
+   * If STT deps are missing, injects an install-prompt for the agent.
    */
   private async enrichWithStt(thread: any, agentMessage: AgentMessage): Promise<void> {
     if (!this.sttService || !agentMessage.attachments?.length) return;
     try {
       await enrichAttachmentsWithTranscripts(agentMessage.attachments, this.sttService, (text) => thread.post(text));
+
+      // Check if any audio attachments failed transcription
+      const hasFailedAudio = agentMessage.attachments.some(
+        (a) => a.mediaType === "audio" && a.transcript?.status === "failed",
+      );
+
       if (!agentMessage.text) {
         const transcripts = agentMessage.attachments
           .filter((a) => a.transcript?.status === "completed" && a.transcript.text)
           .map((a) => a.transcript!.text);
         if (transcripts.length > 0) {
           agentMessage.text = `Voice message transcript: ${transcripts.join(" ")}`;
-        } else if (agentMessage.attachments.some((a) => a.mediaType === "audio")) {
-          agentMessage.text = "Voice message attached, but automatic transcription failed.";
+        } else if (hasFailedAudio) {
+          // STT failed — check if deps are missing and inject agent prompt
+          const missing = await this.sttService.getMissingDeps();
+          if (missing.length > 0) {
+            await thread.post(`🎤 Voice transcription not available yet (missing: ${missing.join(", ")}). Asking agent to install...`);
+            agentMessage.text = this.buildSttInstallPrompt(missing, agentMessage.attachments);
+          } else {
+            agentMessage.text = "Voice message attached, but automatic transcription failed.";
+          }
+        }
+      } else if (hasFailedAudio) {
+        // User sent text + audio, but audio transcription failed
+        const missing = await this.sttService.getMissingDeps();
+        if (missing.length > 0) {
+          await thread.post(`🎤 Voice transcription not available yet (missing: ${missing.join(", ")}). Asking agent to install...`);
+          agentMessage.text += "\n\n" + this.buildSttInstallPrompt(missing, agentMessage.attachments);
+        } else {
+          agentMessage.text += "\n\n(Note: a voice message was also attached but automatic transcription failed.)";
         }
       }
     } catch (err) {
@@ -475,6 +541,37 @@ export class Gateway {
     }
   }
 
+  /**
+   * Build a prompt instructing the agent to install missing STT dependencies.
+   */
+  private buildSttInstallPrompt(missing: string[], attachments: any[]): string {
+    const audioFile = attachments.find((a: any) => a.mediaType === "audio");
+    const audioPath = audioFile?.localPath ?? "(audio file path from attachment)";
+
+    const parts: string[] = [
+      "The user sent a voice message but speech-to-text transcription failed because dependencies are missing.",
+      "",
+      `Missing: ${missing.join(", ")}`,
+      "",
+      "Please install the missing dependencies:",
+    ];
+
+    if (missing.includes("ffmpeg")) {
+      parts.push("- ffmpeg: Install to ~/.local/bin/ffmpeg (try: curl static binary from johnvansickle.com for Linux, or `brew install ffmpeg` on macOS)");
+    }
+    if (missing.includes("whisper")) {
+      parts.push("- whisper: Install via `pip3 install --user openai-whisper` or `uv tool install openai-whisper`");
+    }
+
+    parts.push("");
+    parts.push("After installing, verify with `whisper --help` and `ffmpeg -version`, then transcribe the voice message:");
+    parts.push(`  whisper ${JSON.stringify(audioPath)} --model small --language en --output_format txt --output_dir /tmp`);
+    parts.push("");
+    parts.push("Send the transcription text back to the user. If installation fails, let the user know what went wrong.");
+
+    return parts.join("\n");
+  }
+
   /**
    * Save attachments, notify skipped, and build the AgentMessage.
    * Returns null if there's nothing to send (empty text + failed attachments).
@@ -686,6 +783,9 @@ export class Gateway {
   }
 
   async stop() {
+    if (this.ipcServer) {
+      this.ipcServer.stop();
+    }
     if (this.cronScheduler) {
       try { await this.cronScheduler.stop(); } catch (e) { console.warn("[roundhouse] cron stop error:", e); }
     }

package/src/gateway/tools-inject.ts

@@ -0,0 +1,45 @@
+/**
+ * gateway/tools-inject.ts — Inject <tools> section into agent prompts
+ *
+ * Reads tools.md (bundled or user-customized) and appends it as a
+ * structured section so the agent knows what shell tools are available.
+ */
+
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { ROUNDHOUSE_DIR } from "../config";
+
+let cachedToolsContent: string | null = null;
+
+function loadToolsContent(): string {
+  if (cachedToolsContent !== null) return cachedToolsContent;
+
+  // Try user-customized tools.md first, then bundled
+  const userPath = join(ROUNDHOUSE_DIR, "tools.md");
+  const bundledPath = join(dirname(fileURLToPath(import.meta.url)), "tools.md");
+
+  try {
+    cachedToolsContent = readFileSync(userPath, "utf8");
+  } catch {
+    try {
+      cachedToolsContent = readFileSync(bundledPath, "utf8");
+    } catch {
+      // Don't cache failure — retry next call
+      return "";
+    }
+  }
+  return cachedToolsContent;
+}
+
+/**
+ * Append a <tools> section to the prompt text.
+ * Only injects if tools.md has content.
+ */
+export function injectToolsSection(text: string): string {
+  const tools = loadToolsContent();
+  if (!tools) return text;
+  // Escape any tags that could break the XML structure
+  const sanitized = tools.trim().replace(/<\/?tools>/gi, (m) => m.replace(/</g, "&lt;").replace(/>/g, "&gt;"));
+  return `${text}\n\n<tools>\n${sanitized}\n</tools>`;
+}

package/src/gateway/tools.md

@@ -0,0 +1,54 @@
+# Tools
+
+Available tools that can be invoked via shell commands during agent turns.
+
+## roundhouse cron add
+
+Schedule recurring or one-shot jobs. The user may ask you to "remind me", "check every X", "do Y later", or "schedule Z".
+
+**Usage:**
+```bash
+roundhouse cron add <job-id> --prompt "..." --every "6h"
+roundhouse cron add <job-id> --prompt "..." --cron "0 8 * * *" --tz "America/New_York"
+roundhouse cron add <job-id> --prompt "..." --at "30m"
+```
+
+**Flags:**
+- `--prompt "..."` — What the agent should do when the job fires (required)
+- `--cron "..."` — Cron expression (e.g. "0 9 * * 1-5" = weekdays at 9am)
+- `--every "..."` — Interval (e.g. "6h", "30m", "1d")
+- `--at "..."` — One-shot timer (e.g. "30m", "2h", or ISO datetime)
+- `--tz "..."` — Timezone (default: UTC)
+- `--telegram "..."` — Telegram chat IDs to notify (comma-separated)
+- `--description "..."` — Human-readable description
+- `--timeout "..."` — Max runtime (e.g. "5m", default: 10m)
+
+**Examples:**
+```bash
+# Remind user every morning
+roundhouse cron add morning-checkin --prompt "Good morning! Here's a summary of yesterday's work and today's plan." --cron "0 8 * * *" --tz "Asia/Jerusalem"
+
+# Check something every 6 hours
+roundhouse cron add monitor-deploy --prompt "Check if the deployment at https://example.com is healthy. Report any issues." --every "6h"
+
+# One-shot reminder in 30 minutes
+roundhouse cron add reminder-123 --prompt "Remind the user: 'Call the dentist'" --at "30m"
+```
+
+**Management:**
+```bash
+roundhouse cron list          # Show all jobs
+roundhouse cron pause <id>    # Disable a job
+roundhouse cron resume <id>   # Re-enable a job
+roundhouse cron delete <id>   # Remove a job
+roundhouse cron trigger <id>  # Run immediately
+roundhouse cron runs <id>     # Show run history
+```
+
+## roundhouse cron (via /crons chat command)
+
+Users can also manage jobs via Telegram:
+- `/crons` — list all jobs
+- `/crons trigger <id>` — run now
+- `/crons pause <id>` — disable
+- `/crons resume <id>` — enable

package/src/ipc/client.ts

@@ -0,0 +1,59 @@
+/**
+ * ipc/client.ts — CLI client to send messages to the running gateway
+ *
+ * Connects to ~/.roundhouse/gateway.sock, sends JSON, reads response, closes.
+ */
+
+import { createConnection } from "node:net";
+import { SOCKET_PATH } from "./server";
+import type { IpcRequest, IpcResponse } from "./types";
+
+/**
+ * Send a request to the running gateway via IPC.
+ * Returns the response, or throws if gateway is unreachable.
+ */
+export async function sendIpc(request: IpcRequest, opts?: { timeoutMs?: number; socketPath?: string }): Promise<IpcResponse> {
+  const { timeoutMs = 5000, socketPath = SOCKET_PATH } = opts ?? {};
+  return new Promise((resolve, reject) => {
+    const conn = createConnection(socketPath);
+    let data = "";
+    let done = false;
+    let timer: ReturnType<typeof setTimeout>;
+
+    const finish = (result: IpcResponse | Error) => {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      conn.destroy();
+      if (result instanceof Error) reject(result);
+      else resolve(result);
+    };
+
+    conn.on("connect", () => {
+      conn.write(JSON.stringify(request) + "\n");
+    });
+
+    conn.on("data", (chunk) => {
+      data += chunk.toString();
+      const newlineIdx = data.indexOf("\n");
+      if (newlineIdx === -1) return;
+      try {
+        finish(JSON.parse(data.slice(0, newlineIdx)));
+      } catch {
+        finish(new Error("Invalid response from gateway"));
+      }
+    });
+
+    conn.on("error", (err: NodeJS.ErrnoException) => {
+      if (err.code === "ENOENT" || err.code === "ECONNREFUSED") {
+        finish(new Error("Gateway is not running. Start with: roundhouse start"));
+      } else {
+        finish(err);
+      }
+    });
+
+    conn.on("close", () => finish(new Error("Connection closed without response")));
+
+    timer = setTimeout(() => finish(new Error("IPC timeout")), timeoutMs);
+  });
+}

package/src/ipc/index.ts

@@ -0,0 +1,3 @@
+export { IpcServer, SOCKET_PATH } from "./server";
+export { sendIpc } from "./client";
+export type { IpcRequest, IpcResponse } from "./types";

package/src/ipc/server.ts

@@ -0,0 +1,102 @@
+/**
+ * ipc/server.ts — Unix socket server for gateway IPC
+ *
+ * Listens on ~/.roundhouse/gateway.sock.
+ * Protocol: newline-delimited JSON (one request, one response, close).
+ */
+
+import { createServer, type Server } from "node:net";
+import { unlinkSync, chmodSync, existsSync } from "node:fs";
+import { ROUNDHOUSE_DIR } from "../config";
+import { resolve } from "node:path";
+import type { IpcRequest, IpcResponse } from "./types";
+
+export const SOCKET_PATH = resolve(ROUNDHOUSE_DIR, "gateway.sock");
+
+export type IpcHandler = (request: IpcRequest) => Promise<IpcResponse>;
+
+export class IpcServer {
+  private server: Server | null = null;
+  private socketPath: string;
+
+  constructor(private handler: IpcHandler, socketPath?: string) {
+    this.socketPath = socketPath ?? SOCKET_PATH;
+  }
+
+  getSocketPath(): string { return this.socketPath; }
+
+  async start(): Promise<void> {
+    // Remove stale socket if present (TOCTOU race acknowledged — no fix without flock)
+    if (existsSync(this.socketPath)) {
+      const { createConnection } = await import("node:net");
+      const alive = await new Promise<boolean>((res) => {
+        const conn = createConnection(this.socketPath);
+        const timer = setTimeout(() => { conn.destroy(); res(false); }, 500);
+        conn.on("connect", () => { clearTimeout(timer); conn.end(); res(true); });
+        conn.on("error", () => { clearTimeout(timer); res(false); });
+      });
+      if (alive) {
+        throw new Error("Another gateway is already running (socket in use)");
+      }
+      try { unlinkSync(this.socketPath); } catch {}
+    }
+
+    this.server = createServer((conn) => {
+      let data = "";
+      let handled = false;
+      const MAX_BYTES = 64 * 1024; // 64KB
+
+      conn.on("data", (chunk) => {
+        if (handled) return;
+        data += chunk.toString();
+        if (data.length > MAX_BYTES) {
+          conn.destroy();
+          return;
+        }
+        const newlineIdx = data.indexOf("\n");
+        if (newlineIdx === -1) return;
+
+        handled = true;
+        const line = data.slice(0, newlineIdx);
+
+        let request: IpcRequest;
+        try {
+          request = JSON.parse(line);
+        } catch {
+          conn.end(JSON.stringify({ ok: false, error: "Invalid JSON" }) + "\n");
+          return;
+        }
+
+        this.handler(request).then((response) => {
+          conn.end(JSON.stringify(response) + "\n");
+        }).catch((err) => {
+          conn.end(JSON.stringify({ ok: false, error: err.message }) + "\n");
+        });
+      });
+
+      // Timeout connections that send nothing
+      conn.setTimeout(5000, () => conn.destroy());
+    });
+
+    await new Promise<void>((resolve, reject) => {
+      const onError = (err: Error) => reject(err);
+      this.server!.on("error", onError);
+      this.server!.listen(this.socketPath, () => {
+        this.server!.removeListener("error", onError);
+        this.server!.on("error", (e) => console.error("[roundhouse] IPC server error:", e.message));
+        // Restrict permissions: owner only
+        chmodSync(this.socketPath, 0o600);
+        console.log(`[roundhouse] IPC listening on ${this.socketPath}`);
+        resolve();
+      });
+    });
+  }
+
+  stop(): void {
+    if (this.server) {
+      this.server.close();
+      this.server = null;
+    }
+    try { unlinkSync(this.socketPath); } catch {}
+  }
+}

package/src/ipc/types.ts

@@ -0,0 +1,13 @@
+/**
+ * ipc/types.ts — Shared types for the IPC protocol
+ */
+
+/** Messages the CLI can send to the gateway */
+export type IpcRequest =
+  | { type: "notify"; text: string; session?: string }
+  | { type: "ping" };
+
+/** Responses the gateway sends back */
+export type IpcResponse =
+  | { ok: true }
+  | { ok: false; error: string };

package/src/provisioning/bundle.ts

@@ -226,6 +226,7 @@ export function provisionBundle(opts: ProvisionOpts = {}): void {
   provisionMcporterConfig(opts);
   provisionExtensionFiles(opts);
   provisionExtensions(opts);
+  provisionWorkspaceFiles(opts);
 }
 
 /**
@@ -306,3 +307,33 @@ export function provisionExtensions(opts: ProvisionOpts = {}): void {
     log.warn(`extensions provisioning failed: ${err.message}`);
   }
 }
+
+/**
+ * Copy workspace files (tools.md, etc.) to ~/.roundhouse/ if not already present.
+ * Never overwrites — user's customized version always wins.
+ */
+export function provisionWorkspaceFiles(opts: ProvisionOpts = {}): void {
+  const { force = false, log = consoleLog } = opts;
+  const roundhouseDir = resolve(homedir(), ".roundhouse");
+  const bundledDir = resolve(dirname(fileURLToPath(import.meta.url)), "..", "gateway");
+
+  // Files to provision: [bundled filename, target filename]
+  const files: [string, string][] = [
+    ["tools.md", "tools.md"],
+  ];
+
+  try {
+    mkdirSync(roundhouseDir, { recursive: true });
+
+    for (const [src, dest] of files) {
+      const srcPath = resolve(bundledDir, src);
+      const destPath = resolve(roundhouseDir, dest);
+      if (!existsSync(srcPath)) continue;
+      if (existsSync(destPath) && !force) continue; // never overwrite unless forced
+      copyFileSync(srcPath, destPath);
+      log.ok(`${dest} provisioned to ~/.roundhouse/`);
+    }
+  } catch (err: any) {
+    log.warn(`workspace files provisioning failed: ${err.message}`);
+  }
+}

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;