@inceptionstack/roundhouse 0.5.4 → 0.5.7

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

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

package/src/gateway/helpers.ts

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

package/src/gateway/index.ts

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

package/src/gateway/streaming.ts

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

package/src/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/{bundle.ts → provisioning/bundle.ts}

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

package/src/transports/index.ts

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

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

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

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

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