@inceptionstack/roundhouse 0.5.3 → 0.5.5

package/architecture.md

@@ -282,15 +282,13 @@ src/
 │
 ├── gateway.ts                       # Gateway class: chat SDK wiring, handleAgentTurn
 │   ├── gateway/
-│   │   ├── commands.ts              # 9 Telegram command handlers (/new, /stop, /status, etc.)
+│   │   ├── commands.ts              # 9 command handlers (/new, /stop, /status, etc.)
 │   │   ├── streaming.ts            # Agent event → Telegram message stream mapper
 │   │   ├── attachments.ts          # File save, validation, size limits
-│   │   ├── helpers.ts              # Pure utils: splitMessage, isAllowed, threadIdToDir
+│   │   ├── helpers.ts              # isCommand, resolveAgentThreadId, getSystemResources, toolIcon
 │   │   └── index.ts                # Barrel re-export
-│   ├── commands/update.ts           # /update handler → bundle provisioning
 │   ├── cron/scheduler.ts            # Tick loop, catch-up, job dispatch
 │   ├── memory/                      # Session memory hooks (flush, compact, inject)
-│   ├── notify/telegram.ts           # Startup/error notifications
 │   └── voice/
 │       ├── stt-service.ts           # STT orchestration (provider chain)
 │       └── providers/whisper.ts     # Whisper CLI provider
@@ -309,15 +307,15 @@ src/
 │   ├── setup.ts                     # Setup dispatcher (300 lines): cmdSetup, cmdPair, help
 │   ├── setup/
 │   │   ├── steps.ts                 # 11 step functions (preflight → postflight)
-│   │   ├── flows.ts                 # Interactive + headless orchestrators
-│   │   ├── runtime.ts               # Logger factories, agent resolution
+│   │   ├── flows.ts                 # Interactive + non-interactive orchestrators
+│   │   ├── runtime.ts               # Agent resolution, StepLog bridge
 │   │   ├── args.ts                  # Argument parser
 │   │   ├── helpers.ts               # Atomic writes, exec wrappers
 │   │   ├── types.ts                 # SetupOptions, StepLog interface
+│   │   ├── prompts.ts               # TTY prompt helpers (text, masked, choice)
+│   │   ├── logger.ts                # JSON/text logger for non-interactive diagnostics
+│   │   ├── telegram.ts              # Telegram API: validate token, pair, register commands
 │   │   └── index.ts                 # Barrel export
-│   ├── setup-telegram.ts            # Telegram API: validate token, pair, register commands
-│   ├── setup-prompts.ts             # TTY prompt helpers
-│   ├── setup-logger.ts              # JSON/text logger for headless diagnostics
 │   ├── qr.ts                        # QR code generation for pairing links
 │   └── doctor/                      # Health checks (8 check modules + runner)
 │
@@ -338,19 +336,40 @@ src/
 │   ├── bootstrap.ts, inject.ts      # Session bootstrapping, context injection
 │   ├── state.ts, types.ts           # State tracking, interfaces
 │
-├── telegram-format.ts               # Markdown → Telegram HTML converter
-├── telegram-html.ts                 # HTML entity utilities
-├── telegram-progress.ts             # Typing indicator + progress edits
-├── bundle.ts                        # Skill/extension bundle provisioning
-├── pairing.ts                       # Nonce-based Telegram pairing protocol
-├── commands.ts                      # Bot command definitions
+├── transports/                      # Transport adapter layer
+│   ├── types.ts                     # TransportAdapter interface + PairingResult
+│   ├── index.ts                     # Barrel export
+│   └── telegram/                    # Telegram implementation
+│       ├── telegram-adapter.ts      # TelegramAdapter (implements TransportAdapter)
+│       ├── format.ts                # Markdown → Telegram HTML converter
+│       ├── html.ts                  # HTML streaming + entity utilities
+│       ├── progress.ts              # Typing indicator + progress edits
+│       ├── bot-commands.ts          # Bot command definitions
+│       ├── pairing.ts               # Nonce-based Telegram pairing protocol
+│       └── notify.ts                # Send messages to notify chat IDs
+│
+├── provisioning/
+│   └── bundle.ts                    # Skill/extension bundle provisioning
+│
 └── util.ts                          # Runtime helpers (crypto, path)
 ```
 
+**Repo-root directories (outside `src/`):**
+```
+skills/                              # Bundled skills (shipped in package)
+├── roundhouse-cron/SKILL.md         # Cron job skill for pi
+└── pr-merge-discipline/SKILL.md    # PR merge workflow skill
+```
+
 **Dependency rules:**
 - No circular dependencies
 - `types.ts`, `config.ts`, `util.ts` are pure leaf modules
-- `bundle.ts` is a leaf (only `node:*` imports)
-- Gateway modules (`gateway/*.ts`) import from `../types`, `../config`, `../util`, `../memory/*`, `../telegram-*`
-- CLI modules never import from `gateway.ts` (separation of concerns)
+- `provisioning/bundle.ts` is a leaf (only `node:*` imports)
+- Gateway modules (`gateway/*.ts`) import from `../transports` (via TransportAdapter interface), `../types`, `../config`, `../util`, `../memory/*`
+- Gateway holds a `TransportAdapter` instance — all platform-specific operations go through this interface
+- `transports/telegram/progress.ts` is still imported directly by gateway (deferred from adapter extraction)
+- `gateway/streaming.ts` imports `transports/telegram/html.ts` directly (deferred — streaming is tightly coupled to Telegram HTML wire format)
+- `cron/runner.ts` imports `transports/telegram/notify` directly (deferred — will route through adapter when multi-transport lands)
+- CLI modules never import from `gateway/` (separation of concerns)
+- CLI setup modules (`cli/setup/*.ts`) import from `transports/telegram/` directly (by design — setup is inherently transport-specific)
 - Agent adapters depend on their SDK + `../../types`, `../../config`, `../../util`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inceptionstack/roundhouse",
-  "version": "0.5.3",
+  "version": "0.5.5",
   "type": "module",
   "description": "Multi-platform chat gateway that routes messages through a configured AI agent",
   "license": "MIT",
@@ -31,6 +31,7 @@
   "files": [
     "src/",
     "bin/",
+    "skills/",
     "LICENSE",
     "README.md",
     "architecture.md",

package/skills/pr-merge-discipline/SKILL.md

@@ -0,0 +1,36 @@
+# PR Merge Discipline
+
+Never merge a PR without checking for review comments first.
+
+## When to Use
+
+Activate this skill when:
+- About to merge a PR
+- Using `gh pr merge`
+- PR has been approved or CI passed
+
+## Rules
+
+1. **Always check PR comments before merging**: `gh pr view <number> --comments`
+2. **If there are unresolved comments**, read and address them first
+3. **If there are review requests**, wait for or acknowledge them
+4. **Only merge when**: CI green + no unresolved comments + no pending reviews
+5. **After merge**: pull main and verify clean state
+
+## Workflow
+
+```bash
+# Before any merge:
+gh pr view <number> --comments
+gh pr checks <number>
+
+# Only then:
+gh pr merge <number> --squash --admin
+```
+
+## Anti-Patterns
+
+- ❌ Merging immediately after CI passes without checking comments
+- ❌ Using `sleep && gh pr merge` without a comment check in between
+- ❌ Force-merging over unresolved review feedback
+- ❌ Assuming "no issues found" from automated review means no human comments exist

package/skills/roundhouse-cron/SKILL.md

@@ -0,0 +1,136 @@
+# Roundhouse Cron Jobs
+
+Schedule tasks, add cron jobs, trigger actions at specific times or intervals using the `roundhouse cron` CLI.
+
+## When to Use
+
+Activate this skill when the user asks to:
+- Add a scheduled job or cron job
+- Run something every X minutes/hours/days
+- Trigger something at a specific time
+- List, edit, pause, resume, or delete scheduled jobs
+- Check job run history
+
+## CLI Reference
+
+### Add a job
+
+```bash
+roundhouse cron add <id> --prompt "..." --cron "0 8 * * *"
+roundhouse cron add <id> --prompt "..." --every "6h"
+roundhouse cron add <id> --prompt "..." --at "30m"
+```
+
+**Required flags:**
+- `--prompt "..."` — The prompt sent to the agent when the job fires
+- One schedule type (pick one):
+  - `--cron "0 8 * * *"` — Standard cron expression
+  - `--every "6h"` — Interval (e.g., `30m`, `2h`, `1d`)
+  - `--at "..."` — One-shot (e.g., `30m` from now, or ISO date `2026-05-10T14:00:00Z`)
+
+**Optional flags:**
+- `--tz "Asia/Jerusalem"` — Timezone (default: system timezone)
+- `--telegram "123456,789012"` — Notify these Telegram chat IDs
+- `--notify-on "always|success|failure"` — When to send notifications
+- `--var "key=value,key2=value2"` — Template variables for the prompt
+- `--timeout "30m"` — Max execution time
+- `--description "..."` — Human-readable description
+- `--replace` — Overwrite existing job with same ID
+- `--json` — Output job config as JSON
+
+### List jobs
+
+```bash
+roundhouse cron list
+roundhouse cron list --json
+```
+
+### Show job details
+
+```bash
+roundhouse cron show <id>
+roundhouse cron show <id> --json
+```
+
+### Trigger a job manually
+
+```bash
+roundhouse cron trigger <id>
+```
+
+### View run history
+
+```bash
+roundhouse cron runs <id>
+roundhouse cron runs <id> --limit 20
+```
+
+### Edit a job
+
+```bash
+roundhouse cron edit <id> --prompt "new prompt"
+roundhouse cron edit <id> --every "12h"
+roundhouse cron edit <id> --cron "0 */4 * * *" --tz "UTC"
+```
+
+### Pause / Resume
+
+```bash
+roundhouse cron pause <id>
+roundhouse cron resume <id>
+```
+
+### Delete a job
+
+```bash
+roundhouse cron delete <id>
+```
+
+## Rules
+
+1. **Always use `roundhouse cron` CLI** — do not edit cron files directly
+2. **Job IDs** must be lowercase alphanumeric with hyphens (e.g., `daily-report`, `check-ssl`)
+3. **Prompts** are sent to the agent as-is — write them as clear instructions
+4. **Template variables** use `{{var}}` syntax in prompts (e.g., `--prompt "Check {{url}}" --var "url=https://example.com"`)
+5. **One-shot jobs** (`--at`) run once and stay in history — delete them after if not needed
+6. **Built-in jobs** (prefixed `_`) cannot be edited or deleted
+
+## Examples
+
+### Daily morning briefing at 8am
+```bash
+roundhouse cron add morning-brief \
+  --prompt "Give me a summary of overnight alerts, pending PRs, and today's calendar" \
+  --cron "0 8 * * *" \
+  --tz "America/New_York" \
+  --telegram "123456" \
+  --description "Morning briefing"
+```
+
+### Check SSL expiry every 12 hours
+```bash
+roundhouse cron add check-ssl \
+  --prompt "Check SSL certificate expiry for {{domain}} and alert if < 14 days" \
+  --every "12h" \
+  --var "domain=loki.run" \
+  --telegram "123456" \
+  --notify-on "failure"
+```
+
+### Run a one-shot reminder in 30 minutes
+```bash
+roundhouse cron add remind-standup \
+  --prompt "Reminder: standup starts now!" \
+  --at "30m" \
+  --telegram "123456"
+```
+
+### Weekly dependency audit
+```bash
+roundhouse cron add weekly-deps \
+  --prompt "Run npm audit on all repos in ~/repos/ and report any high/critical vulnerabilities" \
+  --cron "0 9 * * 1" \
+  --tz "UTC" \
+  --timeout "10m" \
+  --description "Monday dependency audit"
+```

package/src/agents/kiro/kiro-adapter.ts

@@ -180,10 +180,7 @@ class KiroAdapter extends BaseAdapter {
     };
   }
 
-  prepareMessage(_threadId: string, message: AgentMessage, context: MessageContext): AgentMessage {
-    if (context.platform === "telegram" && message.text) {
-      return { ...message, text: message.text + "\n\n[Format your final answer for Telegram: concise, use markdown sparingly, avoid long code blocks.]" };
-    }
+  prepareMessage(_threadId: string, message: AgentMessage, _context: MessageContext): AgentMessage {
     return message;
   }
 

package/src/agents/pi/pi-adapter.ts

@@ -205,6 +205,23 @@ export const createPiAgentAdapter: AgentAdapterFactory = (config) => {
       } else {
         console.log(`[pi-agent] no memory extension detected — roundhouse memory will manage`);
       }
+
+      // Warn about pi extensions that bridge a chat platform directly.
+      // They hijack agent_start/message_update/agent_end and short-circuit
+      // Roundhouse's streaming pipeline — Telegram shows "typing" forever.
+      const conflicting = extNames.filter((n) => /pi-telegram(\b|[\/\\])/i.test(n));
+      if (conflicting.length > 0) {
+        const lines = [
+          "",
+          "\u26a0\ufe0f  CONFLICT: detected pi extension(s) that bridge a chat platform directly:",
+          ...conflicting.map((n) => `   - ${n}`),
+          "   Roundhouse already drives Telegram. Loading a bridge extension inside",
+          "   the pi session causes lost replies (typing indicator without text).",
+          "   Remove the extension from ~/.pi/agent/extensions or pi config and restart.",
+          "",
+        ];
+        for (const line of lines) console.warn(line);
+      }
     }
 
     return entry;
@@ -353,6 +370,13 @@ export const createPiAgentAdapter: AgentAdapterFactory = (config) => {
                   streamEvent = { type: "tool_end", toolName: event.toolName, toolCallId: event.toolCallId, isError: event.isError };
                 } else if (event.type === "turn_end") {
                   streamEvent = { type: "turn_end" };
+                } else if (event.type === "message_end") {
+                  // Pi records provider failures (auth, throttling, etc.) on the
+                  // assistant message instead of throwing — surface them.
+                  const msg = (event as any).message;
+                  if (msg?.role === "assistant" && msg.stopReason === "error" && msg.errorMessage) {
+                    streamEvent = { type: "model_error", message: msg.errorMessage };
+                  }
                 }
               }
 
@@ -552,10 +576,7 @@ export const createPiAgentAdapter: AgentAdapterFactory = (config) => {
       };
     },
 
-    prepareMessage(_threadId: string, message: AgentMessage, context: MessageContext): AgentMessage {
-      if (context.platform === "telegram" && message.text) {
-        return { ...message, text: message.text + "\n\n[Format your final answer for Telegram: concise, use markdown sparingly, avoid long code blocks.]" };
-      }
+    prepareMessage(_threadId: string, message: AgentMessage, _context: MessageContext): AgentMessage {
       return message;
     },
   };

package/src/cli/cli.ts

@@ -9,7 +9,7 @@ import { readFile } from "node:fs/promises";
 import { readdirSync, statSync } from "node:fs";
 import { execSync, execFileSync, spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
-import { performUpdate } from "../commands/update";
+import { performUpdate } from "./update";
 
 import {
   CONFIG_PATH,

package/src/cli/setup/args.ts

@@ -18,11 +18,10 @@ export function parseSetupArgs(argv: string[]): SetupOptions {
     systemd: platform() === "linux",
     voice: platform() === "linux",  // Default off on macOS (whisper install is heavy)
     psst: false,
-    nonInteractive: false,
     force: false,
     dryRun: false,
     telegram: false,
-    headless: false,
+    nonInteractive: false,
     qr: "auto",
     agent: "pi",
   };
@@ -46,9 +45,9 @@ export function parseSetupArgs(argv: string[]): SetupOptions {
       case "--no-voice": opts.voice = false; break;
       case "--with-psst": opts.psst = true; break;
       case "--non-interactive": opts.nonInteractive = true; break;
+      case "--headless": opts.nonInteractive = true; break;  // alias
       case "--telegram": opts.telegram = true; break;
-      case "--headless": opts.headless = true; opts.nonInteractive = true; break;
-      case "--agent": opts.agent = next().toLowerCase(); break;
+      case "--agent": opts.agent = next().toLowerCase(); opts._agentExplicit = true; break;
       case "--qr": opts.qr = "always"; break;
       case "--no-qr": opts.qr = "never"; break;
       case "--force": opts.force = true; break;
@@ -64,11 +63,11 @@ export function parseSetupArgs(argv: string[]): SetupOptions {
     opts.botToken = process.env.TELEGRAM_BOT_TOKEN ?? "";
   }
 
-  // Headless: reject --bot-token (argv visible in process listings)
-  if (opts.headless && argv.some((a) => a === "--bot-token")) {
+  // Non-interactive: warn about --bot-token (argv visible in process listings)
+  if (opts.nonInteractive && argv.some((a) => a === "--bot-token")) {
     throw new Error(
-      "--bot-token is not accepted in --headless mode (argv visible in process listings).\n" +
-      "Use: TELEGRAM_BOT_TOKEN=... roundhouse setup --telegram --headless --user USERNAME",
+      "--bot-token is not accepted in --non-interactive mode (argv visible in process listings).\n" +
+      "Use: TELEGRAM_BOT_TOKEN=... roundhouse setup --telegram --non-interactive --user USERNAME",
     );
   }
 
@@ -80,7 +79,7 @@ export function parseSetupArgs(argv: string[]): SetupOptions {
   }
 
   // Interactive --telegram defers token/user prompting to the wizard
-  const isInteractiveTelegram = opts.telegram && !opts.headless && !opts.nonInteractive && process.stdin.isTTY;
+  const isInteractiveTelegram = opts.telegram && !opts.nonInteractive && process.stdin.isTTY;
 
   // Validate
   if (!opts.botToken && !opts.dryRun && !isInteractiveTelegram) {

package/src/cli/setup/flows.ts

@@ -1,8 +1,8 @@
 import { platform } from "node:os";
 import { execFileSync } from "node:child_process";
 import { type SetupOptions } from "./types";
-import { promptText, promptMasked } from "../setup-prompts";
-import { createJsonLogger, type SetupDiagnostics, printDiagnosticError } from "../setup-logger";
+import { promptText, promptMasked, promptChoice } from "./prompts";
+import { createJsonLogger, type SetupDiagnostics, printDiagnosticError } from "./logger";
 import { printQr } from "../qr";
 import {
   createPairingNonce,
@@ -10,10 +10,11 @@ import {
   readPendingPairing,
   writePendingPairing,
   type PendingPairing,
-} from "../../pairing";
+} from "../../transports/telegram/pairing";
 import { detectEnvironment, formatDetectionResults } from "../detect";
+import { listAvailableAgentTypes } from "../../agents/registry";
 import { fileExists, ROUNDHOUSE_DIR, CONFIG_PATH, ENV_FILE_PATH as ENV_PATH } from "../../config";
-import { pairTelegram } from "../setup-telegram";
+import { pairTelegram } from "./telegram";
 import {
   stepPreflight,
   stepValidateToken,
@@ -30,7 +31,7 @@ import { resolveAgentForSetup, textLog, textStepLog, createStepLog } from "./run
 
 export async function runInteractiveTelegramSetup(opts: SetupOptions): Promise<void> {
   const logger = textStepLog;
-  const agent = resolveAgentForSetup(opts, logger);
+  let agent = resolveAgentForSetup(opts, logger);
   textLog("\n🔧 Roundhouse Telegram Setup");
   textLog("━━━━━━━━━━━━━━━━━━━━━━━━━━━");
 
@@ -44,14 +45,37 @@ export async function runInteractiveTelegramSetup(opts: SetupOptions): Promise<v
       for (const line of formatDetectionResults(env)) {
         logger.ok(line);
       }
-      if (!opts.force) {
-        const selected = env.agents.find(a => a.type === opts.agent);
-        if (selected?.configured) {
-          opts._skipAgentInstall = true;
-        }
+    }
+
+    // Agent chooser: only prompt if kiro is available and --agent not explicit
+    if (!opts._agentExplicit && !opts.nonInteractive) {
+      const availableTypes = listAvailableAgentTypes();
+      const kiroDetected = env.agents.some(a => a.type === "kiro" && availableTypes.includes(a.type));
+      if (kiroDetected && availableTypes.length > 1) {
+        const choices = availableTypes.map((t, i) => ({
+          label: t,
+          hint: env.agents.find(a => a.type === t)?.configured ? "configured" : i === 0 ? "default" : undefined,
+        }));
+        textLog("");
+        textLog("  Kiro CLI detected. Choose agent backend:");
+        const idx = await promptChoice(choices, { defaultIndex: 0 });
+        opts.agent = availableTypes[idx];
+        logger.ok(`Using ${opts.agent}`);
+      }
+      // else: no kiro detected, silently use default (pi)
+    }
+
+    // Determine if agent install can be skipped (based on final opts.agent)
+    if (!opts.force) {
+      const selected = env.agents.find(a => a.type === opts.agent);
+      if (selected?.configured) {
+        opts._skipAgentInstall = true;
       }
     }
 
+    // Re-resolve agent definition if chooser changed it
+    agent = resolveAgentForSetup(opts, logger);
+
     if (!opts.botToken) {
       textLog("");
       printBotFatherGuide();
@@ -127,18 +151,18 @@ export async function runInteractiveTelegramSetup(opts: SetupOptions): Promise<v
   }
 }
 
-export async function runHeadlessTelegramSetup(opts: SetupOptions): Promise<void> {
+export async function runNonInteractiveTelegramSetup(opts: SetupOptions): Promise<void> {
   const logger = createJsonLogger();
   const stepLogger = createStepLog(logger);
   const agent = resolveAgentForSetup(opts, stepLogger);
 
   try {
     if (!opts.botToken) {
-      logger.error("validation.failed", "TELEGRAM_BOT_TOKEN env var required for --headless");
+      logger.error("validation.failed", "TELEGRAM_BOT_TOKEN env var required for --non-interactive");
       process.exit(2);
     }
     if (opts.users.length === 0) {
-      logger.error("validation.failed", "--user is required for --headless");
+      logger.error("validation.failed", "--user is required for --non-interactive");
       process.exit(2);
     }
 
@@ -146,6 +170,15 @@ export async function runHeadlessTelegramSetup(opts: SetupOptions): Promise<void
     await stepPreflight(stepLogger, opts, agent);
     logger.ok("Preflight passed");
 
+    // Detect existing agent to skip redundant install
+    const env = detectEnvironment();
+    if (!opts.force) {
+      const selected = env.agents.find(a => a.type === opts.agent);
+      if (selected?.configured) {
+        opts._skipAgentInstall = true;
+      }
+    }
+
     logger.step(2, 9, "telegram.validate", "Validating Telegram bot token");
     const botInfo = await stepValidateToken(stepLogger, opts);
     logger.ok(`Bot: @${botInfo.username} (id: ${botInfo.id})`);
@@ -225,7 +258,7 @@ export async function runHeadlessTelegramSetup(opts: SetupOptions): Promise<void
       }
     }
 
-    logger.info("setup.complete", "Headless setup complete", {
+    logger.info("setup.complete", "Non-interactive setup complete", {
       botUsername: botInfo.username,
       pairingLink,
       pairingStatus: "pending",

package/src/cli/{setup-logger.ts → setup/logger.ts}

@@ -1,8 +1,8 @@
 /**
- * cli/setup-logger.ts — Structured logging for setup.
+ * cli/setup/logger.ts — Structured logging for setup.
  *
  * Interactive mode: human-friendly text with step numbers and emoji.
- * Headless mode: JSON lines for SSM/cloud-init/Docker log parsing.
+ * Non-interactive mode: JSON lines for SSM/cloud-init/Docker log parsing.
  */
 
 export interface SetupLogger {
@@ -113,8 +113,8 @@ export interface SetupDiagnostics {
   error: { name: string; message: string; stack?: string };
 }
 
-export function printDiagnosticError(diag: SetupDiagnostics, headless: boolean): void {
-  if (headless) {
+export function printDiagnosticError(diag: SetupDiagnostics, nonInteractive: boolean): void {
+  if (nonInteractive) {
     console.error(JSON.stringify({
       ts: ts(),
       level: "error",

package/src/cli/{setup-prompts.ts → setup/prompts.ts}

@@ -1,8 +1,8 @@
 /**
- * cli/setup-prompts.ts — Interactive prompts using only Node built-in readline.
+ * cli/setup/prompts.ts — Interactive prompts using only Node built-in readline.
  * No external dependencies.
  */
-import { createInterface, Interface } from "node:readline";
+import { createInterface } from "node:readline";
 
 /**
  * Prompt the user for text input with optional default.
@@ -76,3 +76,24 @@ export async function promptConfirm(
   if (!answer) return !!options?.defaultYes;
   return answer.toLowerCase().startsWith("y");
 }
+
+/**
+ * Prompt user to pick from a numbered list of choices.
+ * Returns the index of the selected item (0-based).
+ */
+export async function promptChoice(
+  items: { label: string; hint?: string }[],
+  options?: { defaultIndex?: number },
+): Promise<number> {
+  if (items.length === 0) throw new Error("promptChoice: items must not be empty");
+  const def = Math.min(Math.max(0, options?.defaultIndex ?? 0), items.length - 1);
+  for (let i = 0; i < items.length; i++) {
+    const marker = i === def ? "*" : " ";
+    const hint = items[i].hint ? ` (${items[i].hint})` : "";
+    console.log(`   ${marker} ${i + 1}. ${items[i].label}${hint}`);
+  }
+  const answer = await promptText(`  Select`, { defaultValue: String(def + 1) });
+  const num = parseInt(answer || String(def + 1), 10);
+  if (isNaN(num) || num < 1 || num > items.length) return def;
+  return num - 1;
+}

package/src/cli/setup/runtime.ts

@@ -7,7 +7,7 @@ import {
   type AgentDefinition,
   type AgentSetupContext,
 } from "../../agents/registry";
-import { type SetupLogger } from "../setup-logger";
+import { type SetupLogger } from "./logger";
 
 export function resolveAgentForSetup(opts: SetupOptions, logger: StepLog): AgentDefinition {
   const agent = { ...getAgentDefinition(opts.agent) };

package/src/cli/setup/steps.ts

@@ -3,8 +3,8 @@ import { resolve } from "node:path";
 import { readFile, writeFile, mkdir, unlink, realpath, stat } from "node:fs/promises";
 import { execFileSync } from "node:child_process";
 import { randomBytes } from "node:crypto";
-import { BOT_COMMANDS } from "../../commands";
-import { provisionBundle, type ProvisionLog } from "../../bundle";
+import { BOT_COMMANDS } from "../../transports/telegram/bot-commands";
+import { provisionBundle, type ProvisionLog } from "../../provisioning/bundle";
 import {
   ROUNDHOUSE_DIR,
   CONFIG_PATH,
@@ -33,7 +33,7 @@ import {
   sendMessage,
   type BotInfo,
   type PairResult,
-} from "../setup-telegram";
+} from "./telegram";
 
 export async function stepPreflight(logger: StepLog, opts: SetupOptions, agent: AgentDefinition): Promise<void> {
   logger.step("①", "Preflight checks...");

package/src/cli/{setup-telegram.ts → setup/telegram.ts}

@@ -1,12 +1,12 @@
 /**
- * cli/setup-telegram.ts — Telegram API helpers for setup
+ * cli/setup/telegram.ts — Telegram API helpers for setup
  *
  * Zero-dependency Telegram Bot API client using global fetch.
  * Token is never logged — redacted in all error messages.
  */
 
-import { randomBytes } from "node:crypto";
-import { BOT_COMMANDS } from "../commands";
+import { createPairingNonce } from "../../transports/telegram/pairing";
+import { BOT_COMMANDS } from "../../transports/telegram/bot-commands";
 
 // ── Types ────────────────────────────────────────────
 
@@ -90,7 +90,7 @@ export async function pairTelegram(
   log: (msg: string) => void = console.log,
   opts?: { nonce?: string; showLink?: boolean },
 ): Promise<PairResult | null> {
-  const nonce = opts?.nonce ?? `rh-${randomBytes(8).toString("hex")}`;
+  const nonce = opts?.nonce ?? createPairingNonce();
   const normalizedUsers = allowedUsers.map((u) => u.replace(/^@/, "").toLowerCase());
 
   // Clear stale updates — advance offset past existing

package/src/cli/setup/types.ts

@@ -18,17 +18,18 @@ export interface SetupOptions {
   systemd: boolean;
   voice: boolean;
   psst: boolean;
-  nonInteractive: boolean;
   force: boolean;
   dryRun: boolean;
   /** Telegram-focused setup flow */
   telegram: boolean;
-  /** Fully headless automation (no TTY prompts) */
-  headless: boolean;
+  /** Non-interactive mode (no TTY prompts) */
+  nonInteractive: boolean;
   /** QR code display mode */
   qr: "auto" | "always" | "never";
   /** Agent type (default: pi) */
   agent: string;
+  /** Whether --agent was explicitly passed on CLI */
+  _agentExplicit?: boolean;
   /** Set by detection: skip agent package install if already configured */
   _skipAgentInstall?: boolean;
 }