@inceptionstack/roundhouse 0.3.17 → 0.3.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inceptionstack/roundhouse",
-  "version": "0.3.17",
+  "version": "0.3.18",
   "type": "module",
   "description": "Multi-platform chat gateway that routes messages through a configured AI agent",
   "license": "MIT",
@@ -42,6 +42,7 @@
     "chat": "^4.26.0",
     "croner": "^10.0.1",
     "p-queue": "^9.2.0",
+    "qrcode-terminal": "^0.12.0",
     "tsx": "^4.0.0"
   },
   "devDependencies": {

package/src/agents/registry.ts

@@ -1,33 +1,126 @@
 /**
  * agents/registry.ts — Agent adapter registry
  *
- * Maps agent type names to their factory functions.
- * Add new agents here.
+ * Maps agent type names to their definitions including factory, install
+ * requirements, config defaults, and doctor checks.
  */
 
 import type { AgentAdapterFactory } from "../types";
 import { createPiAgentAdapter } from "./pi";
+import { homedir } from "node:os";
+import { resolve } from "node:path";
 
-const registry = new Map<string, AgentAdapterFactory>();
-const sdkPackages = new Map<string, string>();
+// ── Types ────────────────────────────────────────────
 
-registry.set("pi", createPiAgentAdapter);
-sdkPackages.set("pi", "@mariozechner/pi-coding-agent");
-// registry.set("kiro", createKiroAgentAdapter);
-// sdkPackages.set("kiro", "@kiro/...");
+export interface AgentPackageRequirement {
+  /** Human-readable label (defaults to packageName) */
+  name?: string;
+  /** npm package to install */
+  packageName: string;
+  /** Install scope */
+  install: "global" | "local";
+  /** Executable that proves the package is installed */
+  binary?: string;
+}
+
+export interface AgentSetupContext {
+  provider: string;
+  model: string;
+  cwd: string;
+  force: boolean;
+  psst: boolean;
+  extensions: string[];
+}
+
+export interface AgentDefinition {
+  /** Stable config/CLI type, e.g. "pi" */
+  type: string;
+  /** Display name, e.g. "Pi" */
+  name: string;
+  /** Runtime adapter factory */
+  factory?: AgentAdapterFactory;
+  /** Can users select this today? */
+  available: boolean;
+  /** Packages setup should install */
+  packages: AgentPackageRequirement[];
+  /** Package used for version display */
+  sdkPackage?: string;
+  /** Default config merged into gatewayConfig.agent */
+  configDefaults: Record<string, unknown>;
+  /** Dirs to create during preflight */
+  configDirs?: string[];
+  /** Agent-specific config writer */
+  configure?: (ctx: AgentSetupContext) => Promise<void>;
+  /** Agent-specific extension installer */
+  installExtension?: (ext: string) => Promise<void>;
+  /** Agent-specific doctor checks (future: loaded dynamically by doctor runner) */
+  doctorChecks?: unknown[];
+}
+
+// ── Pi Definition ────────────────────────────────────
+
+
+const piDefinition: AgentDefinition = {
+  type: "pi",
+  name: "Pi",
+  factory: createPiAgentAdapter,
+  available: true,
+  packages: [
+    {
+      name: "Pi coding agent",
+      packageName: "@mariozechner/pi-coding-agent",
+      install: "global",
+      binary: "pi",
+    },
+  ],
+  sdkPackage: "@mariozechner/pi-coding-agent",
+  configDefaults: {},
+  configDirs: [resolve(homedir(), ".pi", "agent")],
+  // configure and installExtension are set by setup.ts since they need
+  // setup-specific helpers (execOrFail, atomicWriteJson, etc.)
+};
+
+// ── Registry ─────────────────────────────────────────
+
+const definitions = new Map<string, AgentDefinition>();
+definitions.set("pi", piDefinition);
+
+// Future:
+// definitions.set("kiro", kiroDefinition);
+
+// ── Public API ───────────────────────────────────────
+
+export function getAgentDefinition(type: string): AgentDefinition {
+  const def = definitions.get(type);
+  if (!def) {
+    const available = listAvailableAgentTypes().join(", ");
+    throw new Error(`Unknown agent type "${type}". Available: ${available}`);
+  }
+  if (!def.available) {
+    throw new Error(`Agent type "${type}" is not yet available.`);
+  }
+  return def;
+}
+
+export function listAvailableAgentTypes(): string[] {
+  return [...definitions.values()].filter(d => d.available).map(d => d.type);
+}
+
+/** Check if an agent type is registered (for future plugin validation) */
+export function isKnownAgentType(type: string): boolean {
+  return definitions.has(type);
+}
 
+/** Get the runtime adapter factory for an agent type */
 export function getAgentFactory(type: string): AgentAdapterFactory {
-  const factory = registry.get(type);
-  if (!factory) {
-    const available = [...registry.keys()].join(", ");
-    throw new Error(
-      `Unknown agent type "${type}". Available: ${available}`
-    );
+  const def = getAgentDefinition(type);
+  if (!def.factory) {
+    throw new Error(`Agent type "${type}" has no runtime adapter.`);
   }
-  return factory;
+  return def.factory;
 }
 
 /** Get the npm package name for an agent type's SDK (for version display) */
 export function getAgentSdkPackage(type: string): string | undefined {
-  return sdkPackages.get(type);
+  return definitions.get(type)?.sdkPackage;
 }

package/src/cli/qr.ts

@@ -0,0 +1,24 @@
+/**
+ * cli/qr.ts — Terminal QR code rendering.
+ * Wraps qrcode-terminal with graceful fallback.
+ */
+
+export type QrMode = "auto" | "always" | "never";
+
+/**
+ * Print a QR code to stdout if conditions allow.
+ * Falls back silently if the terminal can't render it.
+ */
+export function printQr(url: string, mode: QrMode = "auto"): void {
+  if (mode === "never") return;
+  if (mode === "auto" && !process.stdout.isTTY) return;
+
+  try {
+    // Dynamic import to keep it optional
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const qrcode = require("qrcode-terminal") as { generate: (text: string, opts: { small: boolean }, cb?: (code: string) => void) => void };
+    qrcode.generate(url, { small: true });
+  } catch {
+    // Package not available — skip silently
+  }
+}

package/src/cli/setup-logger.ts

@@ -0,0 +1,142 @@
+/**
+ * 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.
+ */
+
+export interface SetupLogger {
+  step(n: number, total: number, event: string, message: string, context?: Record<string, unknown>): void;
+  info(event: string, message: string, context?: Record<string, unknown>): void;
+  warn(event: string, message: string, context?: Record<string, unknown>): void;
+  error(event: string, message: string, context?: Record<string, unknown>): void;
+  ok(message: string): void;
+  fail(message: string): void;
+}
+
+const STEP_EMOJI = ["①", "②", "③", "④", "⑤", "⑥", "⑦", "⑧", "⑨", "⑩"];
+
+function stepLabel(n: number): string {
+  return STEP_EMOJI[n - 1] ?? `(${n})`;
+}
+
+function ts(): string {
+  return new Date().toISOString();
+}
+
+/**
+ * Redact token-like strings from messages and context values.
+ * Catches patterns like "123456:AAH..." (Telegram bot tokens).
+ */
+function redact(s: string): string {
+  return s.replace(/\d{8,}:[A-Za-z0-9_-]{20,}/g, (m) => {
+    const parts = m.split(":");
+    return `${parts[0].slice(0, 4)}...${parts[1]?.slice(-4) ?? ""}`;
+  });
+}
+
+function redactContext(ctx?: Record<string, unknown>): Record<string, unknown> | undefined {
+  if (!ctx) return undefined;
+  return JSON.parse(redact(JSON.stringify(ctx)));
+}
+
+export function createTextLogger(): SetupLogger {
+  return {
+    step(n, _total, _event, message) {
+      console.log(`\n${stepLabel(n)} ${redact(message)}`);
+    },
+    info(_event, message) {
+      console.log(`   ${redact(message)}`);
+    },
+    warn(_event, message) {
+      console.log(`   ⚠ ${redact(message)}`);
+    },
+    error(_event, message) {
+      console.error(`   ❌ ${redact(message)}`);
+    },
+    ok(message) {
+      console.log(`   ✓ ${redact(message)}`);
+    },
+    fail(message) {
+      console.error(`   ✗ ${redact(message)}`);
+    },
+  };
+}
+
+export function createJsonLogger(): SetupLogger {
+  function emit(level: string, event: string, message: string, extra?: Record<string, unknown>) {
+    const line: Record<string, unknown> = {
+      ts: ts(),
+      level,
+      event,
+      message: redact(message),
+      ...redactContext(extra),
+    };
+    console.log(JSON.stringify(line));
+  }
+
+  return {
+    step(n, total, event, message, context) {
+      emit("info", event, message, { step: n, total, ...context });
+    },
+    info(event, message, context) {
+      emit("info", event, message, context);
+    },
+    warn(event, message, context) {
+      emit("warn", event, message, context);
+    },
+    error(event, message, context) {
+      emit("error", event, message, context);
+    },
+    ok(message) {
+      emit("info", "ok", message);
+    },
+    fail(message) {
+      emit("error", "fail", message);
+    },
+  };
+}
+
+/**
+ * Collect diagnostic info for error output.
+ */
+export interface SetupDiagnostics {
+  node: string;
+  platform: string;
+  arch: string;
+  cwd: string;
+  roundhouseDir: string;
+  configExists: boolean;
+  envExists: boolean;
+  pairingStatus: string;
+  serviceState: string;
+  error: { name: string; message: string; stack?: string };
+}
+
+export function printDiagnosticError(diag: SetupDiagnostics, headless: boolean): void {
+  if (headless) {
+    console.error(JSON.stringify({
+      ts: ts(),
+      level: "error",
+      event: "setup.failed",
+      diagnostics: {
+        ...diag,
+        error: {
+          ...diag.error,
+          message: redact(diag.error.message),
+          stack: diag.error.stack ? redact(diag.error.stack) : undefined,
+        },
+      },
+    }));
+  } else {
+    console.error(`\n━━━━━━━━━━━━━━━━━━━`);
+    console.error(`❌ Setup failed: ${redact(diag.error.message)}`);
+    console.error(`\nDiagnostics:`);
+    console.error(`  Node: ${diag.node}`);
+    console.error(`  Platform: ${diag.platform} ${diag.arch}`);
+    console.error(`  Config: ${diag.configExists ? "exists" : "missing"}`);
+    console.error(`  Env file: ${diag.envExists ? "exists" : "missing"}`);
+    console.error(`  Pairing: ${diag.pairingStatus}`);
+    console.error(`  Service: ${diag.serviceState}`);
+  }
+}

package/src/cli/setup-prompts.ts

@@ -0,0 +1,78 @@
+/**
+ * cli/setup-prompts.ts — Interactive prompts using only Node built-in readline.
+ * No external dependencies.
+ */
+import { createInterface, Interface } from "node:readline";
+
+/**
+ * Prompt the user for text input with optional default.
+ */
+export async function promptText(
+  question: string,
+  options?: { defaultValue?: string },
+): Promise<string> {
+  const suffix = options?.defaultValue ? ` (${options.defaultValue})` : "";
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    return await new Promise<string>((resolve, reject) => {
+      let settled = false;
+      rl.question(`${question}${suffix}: `, (answer) => {
+        settled = true;
+        resolve(answer.trim() || options?.defaultValue || "");
+      });
+      rl.on("close", () => { if (!settled) reject(new Error("Input cancelled")); });
+    });
+  } finally {
+    rl.close();
+  }
+}
+
+/**
+ * Prompt for secret input — characters are not echoed to the terminal.
+ * Uses readline with _writeToOutput override to suppress echo.
+ */
+export async function promptMasked(question: string): Promise<string> {
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    terminal: true,
+  });
+
+  // Suppress character echo after the prompt is written
+  let prompted = false;
+  const originalWrite = (rl as unknown as { _writeToOutput: (s: string) => void })._writeToOutput;
+  (rl as unknown as { _writeToOutput: (s: string) => void })._writeToOutput = function (s: string) {
+    if (!prompted) {
+      originalWrite.call(rl, s);
+      if (s.includes(question)) prompted = true;
+    }
+    // After prompt is shown, swallow all output (no echo)
+  };
+
+  try {
+    return await new Promise<string>((resolve, reject) => {
+      let settled = false;
+      rl.question(`${question}: `, (answer) => {
+        settled = true;
+        process.stdout.write("\n");
+        resolve(answer.trim());
+      });
+      rl.on("close", () => { if (!settled) reject(new Error("Input cancelled")); });
+    });
+  } finally {
+    rl.close();
+  }
+}
+
+/**
+ * Prompt for yes/no confirmation. Returns true for yes.
+ */
+export async function promptConfirm(
+  question: string,
+  options?: { defaultYes?: boolean },
+): Promise<boolean> {
+  const hint = options?.defaultYes ? "[Y/n]" : "[y/N]";
+  const answer = await promptText(`${question} ${hint}`);
+  if (!answer) return !!options?.defaultYes;
+  return answer.toLowerCase().startsWith("y");
+}

package/src/cli/setup-telegram.ts

@@ -24,12 +24,12 @@ export interface PairResult {
 
 // ── API helper ───────────────────────────────────────
 
-function redactToken(token: string): string {
+export function redactToken(token: string): string {
   if (token.length < 10) return "***";
   return token.slice(0, 4) + "..." + token.slice(-4);
 }
 
-async function telegramApi(
+export async function telegramApi(
   token: string,
   method: string,
   params?: Record<string, unknown>,
@@ -78,6 +78,9 @@ export async function sendMessage(token: string, chatId: number, text: string):
 /**
  * Pair with a Telegram user — wait for them to send /start <nonce>.
  * Returns the user's chat ID and numeric user ID, or null on timeout.
+ *
+ * If opts.nonce is provided, use it instead of generating a new one.
+ * If opts.showLink is false, skip printing the pairing instructions.
  */
 export async function pairTelegram(
   token: string,
@@ -85,8 +88,9 @@ export async function pairTelegram(
   allowedUsers: string[],
   timeoutMs = 300_000,
   log: (msg: string) => void = console.log,
+  opts?: { nonce?: string; showLink?: boolean },
 ): Promise<PairResult | null> {
-  const nonce = `rh-${randomBytes(3).toString("hex")}`;
+  const nonce = opts?.nonce ?? `rh-${randomBytes(8).toString("hex")}`;
   const normalizedUsers = allowedUsers.map((u) => u.replace(/^@/, "").toLowerCase());
 
   // Clear stale updates — advance offset past existing
@@ -101,8 +105,11 @@ export async function pairTelegram(
     // If getUpdates fails, start from 0
   }
 
-  log(`   Open https://t.me/${botUsername} and send: /start ${nonce}`);
-  log(`   Waiting... (Ctrl+C to skip)\n`);
+  if (opts?.showLink !== false) {
+    log(`   Open https://t.me/${botUsername}?start=${nonce} and tap Start`);
+    log(`   Or send /start ${nonce} to @${botUsername}`);
+    log(`   Waiting... (Ctrl+C to skip)\n`);
+  }
 
   const deadline = Date.now() + timeoutMs;
   while (Date.now() < deadline) {