@inceptionstack/roundhouse 0.3.17 → 0.3.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inceptionstack/roundhouse",
-  "version": "0.3.17",
+  "version": "0.3.19",
   "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/pi.ts

@@ -3,10 +3,10 @@
  *
  * Wraps pi's SDK (createAgentSession) as an AgentAdapter.
  * One persistent session per thread, stored at:
- *   ~/.pi/agent/gateway-sessions/<thread_id>/<session>.jsonl
+ *   ~/.roundhouse/sessions/<thread_id>/<session>.jsonl
  */
 
-import { mkdir, stat } from "node:fs/promises";
+import { mkdir } from "node:fs/promises";
 import { readFileSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { homedir } from "node:os";
@@ -24,19 +24,16 @@ import {
 } from "@mariozechner/pi-coding-agent";
 
 import type { AgentAdapter, AgentAdapterFactory, AgentMessage, AgentResponse, AgentStreamEvent } from "../types";
-import { DEBUG_STREAM, threadIdToDir, threadIdToDirLegacy } from "../util";
+import { SESSIONS_DIR } from "../config";
+import { DEBUG_STREAM, threadIdToDir } from "../util";
 
 interface SessionEntry {
   session: AgentSession;
   lastUsed: number;
+  inFlight: number;
 }
 
-const DEFAULT_SESSIONS_DIR = join(
-  homedir(),
-  ".pi",
-  "agent",
-  "gateway-sessions"
-);
+const DEFAULT_SESSIONS_DIR = SESSIONS_DIR;
 const DEFAULT_MAX_IDLE_MS = 30 * 60 * 1000;
 
 export const createPiAgentAdapter: AgentAdapterFactory = (config) => {
@@ -107,72 +104,65 @@ export const createPiAgentAdapter: AgentAdapterFactory = (config) => {
   }
 
   async function runPromptAndFollowUps(entry: SessionEntry, text: string, onDraining?: () => void, onDrainComplete?: () => void): Promise<void> {
-    await entry.session.prompt(text);
-    await drainSessionEvents(entry.session);
-
-    // Check for pending follow-up work AFTER drainSessionEvents — that's
-    // where agent_end extension handlers run and queue follow-up messages
-    // (e.g. pi-lgtm calls sendMessage with deliverAs: "followUp").
-    // The actual long wait is in the while loop's waitForIdle() below.
-    let notifiedDraining = false;
-    if (onDraining && (entry.session.isStreaming || entry.session.agent.hasQueuedMessages())) {
-      onDraining();
-      notifiedDraining = true;
-    }
+    entry.inFlight++;
+    try {
+      await entry.session.prompt(text);
+      await drainSessionEvents(entry.session);
 
-    // Loop until the session is fully idle. Two separate conditions can keep
-    // work in flight after the initial prompt resolves:
-    //
-    //  (a) `hasQueuedMessages()` — an extension called `pi.sendMessage(...,
-    //      { triggerTurn: true, deliverAs: "followUp" })` *while isStreaming
-    //      was true* — pi queued onto `agent.followUp()`, so we manually
-    //      drain it with `continue()`.
-    //
-    //  (b) `isStreaming === true` — an extension called the same sendMessage
-    //      *after isStreaming became false*. In that path pi's
-    //      `sendCustomMessage` skips the queue entirely and calls
-    //      `agent.prompt(appMessage)` directly as fire-and-forget, kicking
-    //      off a brand-new agent run. `hasQueuedMessages()` returns false
-    //      for this run, but `isStreaming` is true — we have to
-    //      `waitForIdle()` so subscribers see the new run's events (e.g. the
-    //      agent's reply to a pi-lgtm code review) before we unsubscribe.
-    //
-    // Without (b), pi CLI works (its subscriber stays attached across runs)
-    // but roundhouse delivers the review bubble then goes silent.
-    while (true) {
-      if (entry.session.isStreaming) {
-        await entry.session.agent.waitForIdle();
-        await drainSessionEvents(entry.session);
-        continue;
+      // Check for pending follow-up work AFTER drainSessionEvents — that's
+      // where agent_end extension handlers run and queue follow-up messages
+      // (e.g. pi-lgtm calls sendMessage with deliverAs: "followUp").
+      // The actual long wait is in the while loop's waitForIdle() below.
+      let notifiedDraining = false;
+      if (onDraining && (entry.session.isStreaming || entry.session.agent.hasQueuedMessages())) {
+        onDraining();
+        notifiedDraining = true;
       }
-      if (entry.session.agent.hasQueuedMessages()) {
-        await entry.session.agent.continue();
-        await drainSessionEvents(entry.session);
-        continue;
+
+      // Loop until the session is fully idle. Two separate conditions can keep
+      // work in flight after the initial prompt resolves:
+      //
+      //  (a) `hasQueuedMessages()` — an extension called `pi.sendMessage(...,
+      //      { triggerTurn: true, deliverAs: "followUp" })` *while isStreaming
+      //      was true* — pi queued onto `agent.followUp()`, so we manually
+      //      drain it with `continue()`.
+      //
+      //  (b) `isStreaming === true` — an extension called the same sendMessage
+      //      *after isStreaming became false*. In that path pi's
+      //      `sendCustomMessage` skips the queue entirely and calls
+      //      `agent.prompt(appMessage)` directly as fire-and-forget, kicking
+      //      off a brand-new agent run. `hasQueuedMessages()` returns false
+      //      for this run, but `isStreaming` is true — we have to
+      //      `waitForIdle()` so subscribers see the new run's events (e.g. the
+      //      agent's reply to a pi-lgtm code review) before we unsubscribe.
+      //
+      // Without (b), pi CLI works (its subscriber stays attached across runs)
+      // but roundhouse delivers the review bubble then goes silent.
+      while (true) {
+        if (entry.session.isStreaming) {
+          await entry.session.agent.waitForIdle();
+          await drainSessionEvents(entry.session);
+          continue;
+        }
+        if (entry.session.agent.hasQueuedMessages()) {
+          await entry.session.agent.continue();
+          await drainSessionEvents(entry.session);
+          continue;
+        }
+        break;
       }
-      break;
-    }
 
-    if (notifiedDraining && onDrainComplete) {
-      onDrainComplete();
+      if (notifiedDraining && onDrainComplete) {
+        onDrainComplete();
+      }
+    } finally {
+      entry.inFlight--;
+      entry.lastUsed = Date.now();
     }
   }
 
   async function createSession(threadId: string): Promise<SessionEntry> {
-    let dirName = threadIdToDir(threadId);
-    const newPath = join(sessionsDir, dirName);
-    const legacyPath = join(sessionsDir, threadIdToDirLegacy(threadId));
-    // Migrate: if legacy dir exists but new doesn't, use legacy
-    if (dirName !== threadIdToDirLegacy(threadId)) {
-      try {
-        await stat(legacyPath);
-        // Legacy exists — check if new exists
-        try { await stat(newPath); } catch {
-          // New doesn't exist, use legacy to preserve session history
-          dirName = threadIdToDirLegacy(threadId);
-        }
-      } catch { /* legacy doesn't exist either, use new */ }
-    }
+    const dirName = threadIdToDir(threadId);
     const threadDir = join(sessionsDir, dirName);
     await mkdir(threadDir, { recursive: true });
 
@@ -214,7 +204,7 @@ export const createPiAgentAdapter: AgentAdapterFactory = (config) => {
       console.log(`[pi-agent] model fallback: ${result.modelFallbackMessage}`);
     }
 
-    const entry: SessionEntry = { session: result.session, lastUsed: Date.now() };
+    const entry: SessionEntry = { session: result.session, lastUsed: Date.now(), inFlight: 0 };
     sessions.set(threadId, entry);
 
     // Detect memory capabilities from loaded extensions (first session only)
@@ -260,6 +250,7 @@ export const createPiAgentAdapter: AgentAdapterFactory = (config) => {
   function reap() {
     const now = Date.now();
     for (const [id, entry] of sessions) {
+      if (entry.inFlight > 0) continue; // skip busy sessions
       if (now - entry.lastUsed > maxIdleMs) {
         entry.session.dispose();
         sessions.delete(id);

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/cli.ts

@@ -5,10 +5,9 @@
  */
 
 import { resolve, dirname } from "node:path";
-import { homedir } from "node:os";
 import { readFile, writeFile, mkdir } from "node:fs/promises";
 import { readdirSync, statSync } from "node:fs";
-import { execSync, spawn } from "node:child_process";
+import { execSync, execFileSync, spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
 
 import {
@@ -16,12 +15,14 @@ import {
   CONFIG_PATH,
   ENV_FILE_PATH,
   DEFAULT_CONFIG,
+  SESSIONS_DIR,
   SERVICE_NAME,
   fileExists,
   loadConfig,
   resolveEnvFilePath,
 } from "../config";
 import { getAgentSdkPackage } from "../agents/registry";
+import { threadIdToDir } from "../util";
 import { parseEnvFile, serializeEnvFile, envQuote } from "./env-file";
 import {
   SERVICE_PATH,
@@ -40,6 +41,11 @@ const __dirname = dirname(__filename);
 
 // ── Shell helpers ───────────────────────────────────
 
+/**
+ * Shell helper — WARNING: passes `cmd` through the system shell.
+ * Only call with trusted/hardcoded strings. Any dynamic segments must be
+ * validated (e.g. `/^\d+$/.test(pid)`) before interpolation.
+ */
 function run(cmd: string, opts?: { silent?: boolean }): string {
   try {
     return execSync(cmd, { encoding: "utf8", stdio: opts?.silent ? "pipe" : "inherit" }).trim();
@@ -79,10 +85,10 @@ async function cmdRun() {
     await import(jsPath);
   } else {
     const tsxPath = resolve(__dirname, "..", "..", "node_modules", "tsx", "dist", "cli.mjs");
-    execSync(
-      `node ${tsxPath} ${indexPath}`,
-      { stdio: "inherit", env: { ...process.env, ROUNDHOUSE_CONFIG: CONFIG_PATH } },
-    );
+    execFileSync(process.execPath, [tsxPath, indexPath], {
+      stdio: "inherit",
+      env: { ...process.env, ROUNDHOUSE_CONFIG: CONFIG_PATH },
+    });
   }
 }
 
@@ -279,87 +285,30 @@ async function cmdTui() {
     process.exit(1);
   }
 
-  const sessionsBase = (config.agent as any)?.sessionDir
-    ?? resolve(homedir(), ".pi", "agent", "gateway-sessions");
-
-  let threadDirs: string[] = [];
+  const threadArg = process.argv[3];
+  const threadId = threadArg || "main";
+  const threadDir = threadIdToDir(threadId);
+  const threadPath = resolve(SESSIONS_DIR, threadDir);
+  let candidates: Array<{ sessionFile: string; mtime: number }> = [];
   try {
-    threadDirs = readdirSync(sessionsBase)
-      .filter((d) => { try { return statSync(resolve(sessionsBase, d)).isDirectory(); } catch { return false; } })
-      .sort();
+    candidates = readdirSync(threadPath)
+      .filter((f) => f.endsWith(".jsonl"))
+      .map((f) => {
+        const sessionFile = resolve(threadPath, f);
+        return { sessionFile, mtime: statSync(sessionFile).mtimeMs };
+      })
+      .sort((a, b) => b.mtime - a.mtime);
   } catch {
-    console.error(`No gateway sessions found at ${sessionsBase}`);
+    console.error(`No session directory found at ${threadPath}.`);
     process.exit(1);
   }
 
-  if (threadDirs.length === 0) {
-    console.error("No gateway sessions found. Send a message via Telegram/Slack first.");
-    process.exit(1);
-  }
-
-  const threadArg = process.argv[3];
-
-  interface SessionCandidate { threadDir: string; sessionFile: string; mtime: number; }
-
-  const candidates: SessionCandidate[] = [];
-  for (const dir of threadDirs) {
-    if (threadArg && !dir.includes(threadArg)) continue;
-    const threadPath = resolve(sessionsBase, dir);
-    try {
-      for (const f of readdirSync(threadPath).filter((f) => f.endsWith(".jsonl"))) {
-        const fullPath = resolve(threadPath, f);
-        candidates.push({ threadDir: dir, sessionFile: fullPath, mtime: statSync(fullPath).mtimeMs });
-      }
-    } catch {}
-  }
-
   if (candidates.length === 0) {
-    if (threadArg) {
-      console.error(`No sessions found matching "${threadArg}".`);
-      console.log("Available threads:");
-      for (const d of threadDirs) console.log(`  ${d}`);
-    } else {
-      console.error("No session files found.");
-    }
+    console.error(`No session files found at ${threadPath}.`);
     process.exit(1);
   }
 
-  candidates.sort((a, b) => b.mtime - a.mtime);
-
-  let selected: SessionCandidate;
-  const uniqueThreads = [...new Set(candidates.map((c) => c.threadDir))];
-
-  if (uniqueThreads.length === 1 || threadArg) {
-    selected = candidates[0];
-  } else {
-    console.log("Available sessions (most recent first):\n");
-    const shown: SessionCandidate[] = [];
-    const seen = new Set<string>();
-    for (const c of candidates) {
-      if (seen.has(c.threadDir)) continue;
-      seen.add(c.threadDir);
-      shown.push(c);
-    }
-    for (let i = 0; i < shown.length; i++) {
-      const age = Math.round((Date.now() - shown[i].mtime) / 60000);
-      const ageStr = age < 60 ? `${age}m ago` : `${Math.round(age / 60)}h ago`;
-      console.log(`  [${i + 1}] ${shown[i].threadDir}  (${ageStr})`);
-    }
-    console.log();
-
-    const readline = await import("node:readline");
-    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-    const answer = await new Promise<string>((r) => {
-      rl.question("Pick a session [1]: ", (ans) => { rl.close(); r(ans.trim() || "1"); });
-    });
-
-    const idx = parseInt(answer, 10) - 1;
-    if (isNaN(idx) || idx < 0 || idx >= shown.length) {
-      console.error("Invalid selection.");
-      process.exit(1);
-    }
-    selected = candidates.find((c) => c.threadDir === shown[idx].threadDir)!;
-  }
+  const selected = candidates[0];
 
   console.log(`\nOpening: ${selected.sessionFile}\n`);
 
@@ -394,7 +343,7 @@ Commands:
   config              Show config path and contents
   agent <message>     Send a message to the agent and print response
                        Options: --thread <id>, --stdin, --timeout <sec>,
-                                --no-timeout, --verbose
+                                --no-timeout, --verbose, --ephemeral
   doctor [--fix]       Check system health and configuration
                        Options: --fix, --json, --verbose
   cron <command>       Manage scheduled jobs (add, list, trigger, etc.)
@@ -414,6 +363,7 @@ Environment:
 async function cmdAgent() {
   // Usage: roundhouse agent <message>
   //        roundhouse agent --thread <id> <message>
+  //        roundhouse agent --ephemeral <message>
   //        echo "message" | roundhouse agent --stdin
   const args = process.argv.slice(3);
   let threadId = "";
@@ -421,6 +371,7 @@ async function cmdAgent() {
   let useStdin = false;
   let timeoutMs = 120_000;
   let verbose = false;
+  let ephemeral = false;
 
   for (let i = 0; i < args.length; i++) {
     if (args[i] === "--thread" && args[i + 1]) {
@@ -435,6 +386,8 @@ async function cmdAgent() {
       timeoutMs = 0;
     } else if (args[i] === "--verbose") {
       verbose = true;
+    } else if (args[i] === "--ephemeral") {
+      ephemeral = true;
     } else if (args[i].startsWith("-")) {
       console.error(`Unknown flag: ${args[i]}`);
       process.exit(1);
@@ -468,13 +421,20 @@ async function cmdAgent() {
     console.error("       echo \"message\" | roundhouse agent --stdin");
     console.error("       roundhouse agent --timeout 60 <message>");
     console.error("       roundhouse agent --verbose <message>");
+    console.error("       roundhouse agent --ephemeral <message>");
+    process.exit(1);
+  }
+
+  if (threadId && ephemeral) {
+    console.error("--thread and --ephemeral cannot be used together");
     process.exit(1);
   }
 
-  // Default: ephemeral thread ID (no session persistence across invocations)
-  // --thread <id> opts into persistent/shared sessions
+  // Default: shared main session. --ephemeral restores one-off CLI behavior.
   if (!threadId) {
-    threadId = `cli-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    threadId = ephemeral
+      ? `cli-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`
+      : "main";
   }
 
   // Suppress debug/info logs unless --verbose

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

@@ -2,15 +2,15 @@
  * Disk and directory checks
  */
 
-import { access, stat, readdir, constants } from "node:fs/promises";
+import { access, readdir, constants } from "node:fs/promises";
 import { join } from "node:path";
 import { homedir } from "node:os";
 import { mkdirSync } from "node:fs";
 import type { DoctorCheck } from "../types";
 import { run } from "../shell";
+import { SESSIONS_DIR } from "../../../config";
 
 const INCOMING_DIR = process.env.ROUNDHOUSE_INCOMING_DIR ?? join(homedir(), ".roundhouse", "incoming");
-const SESSIONS_DIR = join(homedir(), ".pi", "agent", "gateway-sessions");
 
 export const diskChecks: DoctorCheck[] = [
   {

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
+  }
+}