@inceptionstack/roundhouse 0.5.2 → 0.5.3

package/architecture.md

@@ -258,37 +258,99 @@ The gateway and agent adapters don't change — only the router.
 ## Module dependency graph
 
 ```
-index.ts
-  ├── config.ts (loadConfig, applyEnvOverrides)
-  ├── agents/registry.ts
-  │     └── agents/pi.ts
-  │           └── util.ts (threadIdToDir)
-  ├── router.ts
-  ├── gateway.ts
-  │     └── util.ts (splitMessage, isAllowed, threadIdToDir, generateAttachmentId)
-  │     └── voice/stt-service.ts
-  │           └── voice/providers/whisper.ts
-  │           └── voice/types.ts
-  └── types.ts (shared interfaces, pure types only)
-
-cli/cli.ts
-  ├── config.ts (DEFAULT_CONFIG, CONFIG_PATH, loadConfig, etc.)
-  ├── agents/registry.ts (getAgentSdkPackage)
-  ├── cli/env-file.ts (parseEnvFile, serializeEnvFile, envQuote)
-  ├── cli/systemd.ts (resolveExecStart, generateUnit, writeServiceUnit, systemctl, etc.)
-  ├── cli/launchd.ts (generatePlist, installLaunchAgent, uninstallLaunchAgent, isLaunchAgentRunning)
-  ├── cli/doctor.ts → cli/doctor/runner.ts → cli/doctor/checks/*
-  ├── cli/cron.ts → cron/store.ts, cron/runner.ts, cron/helpers.ts
-  └── cli/setup.ts → cli/env-file.ts, cli/systemd.ts, cli/launchd.ts, cli/setup-telegram.ts, bundle.ts
-
-gateway.ts also imports:
-  → commands/update.ts → bundle.ts (bundle provisioning)
-  → cli/doctor/runner.ts for /doctor command
-  → cron/scheduler.ts → cron/runner.ts → cron/store.ts
-  → cron/helpers.ts, cron/format.ts
-  → notify/telegram.ts
+src/
+├── index.ts                         # Entry: loads config → creates agent → starts gateway
+│   ├── config.ts                    # loadConfig, applyEnvOverrides, path constants
+│   ├── router.ts                    # SingleAgentRouter (future: Multi/Fallback/UserChoice)
+│   ├── types.ts                     # AgentAdapter, AgentMessage, AgentStreamEvent interfaces
+│   └── agents/
+│       ├── registry.ts              # Agent factory lookup, adapter definitions
+│       ├── base-adapter.ts          # BaseAdapter abstract class (shared defaults)
+│       ├── index.ts                 # Barrel re-export
+│       ├── pi/
+│       │   ├── pi-adapter.ts        # Pi factory: sessions, prompt/stream, lifecycle
+│       │   └── message-format.ts    # Pure: formatMessage, extractCustomMessage
+│       └── kiro/
+│           ├── kiro-adapter.ts      # Kiro class: ACP protocol, tool dispatch
+│           ├── session.ts           # Session lifecycle
+│           ├── tool-names.ts        # Tool name mapping
+│           └── acp/                 # Agent Communication Protocol client
+│               ├── client.ts
+│               ├── process.ts
+│               ├── types.ts
+│               └── index.ts
+│
+├── gateway.ts                       # Gateway class: chat SDK wiring, handleAgentTurn
+│   ├── gateway/
+│   │   ├── commands.ts              # 9 Telegram 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
+│   │   └── 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
+│
+├── cli/
+│   ├── cli.ts                       # CLI dispatcher: start/stop/status/logs/doctor/cron/setup
+│   ├── agent-command.ts             # `roundhouse agent` — one-shot prompt pipeline
+│   ├── service-manager.ts           # ServiceManager interface + Launchd/Systemd impls
+│   ├── shell.ts                     # Shell execution utilities
+│   ├── cron.ts                      # Thin dispatcher → cron-commands.ts
+│   ├── cron-commands.ts             # 10 cron command handlers (add/list/show/trigger/...)
+│   ├── detect.ts                    # Agent environment detection
+│   ├── env-file.ts                  # .env parser/serializer
+│   ├── systemd.ts                   # systemd unit generation, systemctl wrappers
+│   ├── launchd.ts                   # macOS plist generation, launchctl wrappers
+│   ├── 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
+│   │   ├── args.ts                  # Argument parser
+│   │   ├── helpers.ts               # Atomic writes, exec wrappers
+│   │   ├── types.ts                 # SetupOptions, StepLog interface
+│   │   └── 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)
+│
+├── cron/                            # Cron job engine
+│   ├── store.ts                     # Job CRUD, run history persistence
+│   ├── runner.ts                    # Execute job → agent prompt → record result
+│   ├── scheduler.ts                 # Tick loop with catch-up
+│   ├── schedule.ts, durations.ts    # Parsing: cron expressions, intervals
+│   ├── template.ts                  # Variable substitution in prompts
+│   ├── format.ts, helpers.ts        # Display formatting, validation
+│   ├── constants.ts, types.ts       # Shared constants and interfaces
+│
+├── memory/                          # Roundhouse-managed session memory
+│   ├── lifecycle.ts                 # Flush/compact orchestration
+│   ├── policy.ts                    # Pressure detection, token thresholds
+│   ├── prompts.ts                   # LLM prompts for summarization
+│   ├── files.ts                     # Memory file I/O
+│   ├── 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
+└── util.ts                          # Runtime helpers (crypto, path)
 ```
 
-No circular dependencies. `types.ts` and `config.ts` are pure leaf modules.
-`util.ts` is a leaf module with runtime helpers (`node:crypto` for attachment IDs).
-`bundle.ts` is a pure leaf module (only `node:*` imports) consumed by `cli/setup.ts` and `commands/update.ts`.
+**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)
+- Agent adapters depend on their SDK + `../../types`, `../../config`, `../../util`

package/package.json

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

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

@@ -12,7 +12,7 @@
 
 import { homedir } from "node:os";
 import { resolve } from "node:path";
-import type { AgentAdapterFactory, AgentMessage, AgentResponse, AgentStreamEvent, AdapterInfo } from "../../types.js";
+import type { AgentAdapterFactory, AgentMessage, AgentResponse, AgentStreamEvent, AdapterInfo, MessageContext } from "../../types.js";
 import { ROUNDHOUSE_VERSION } from "../../config.js";
 import { BaseAdapter } from "../base-adapter.js";
 import { spawnKiroCli, shutdownProcess, getKiroCliVersion, type AcpProcess, type InitializeResult, type SessionNewResult } from "./acp/index.js";
@@ -180,6 +180,13 @@ 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.]" };
+    }
+    return message;
+  }
+
   // ── Private: process lifecycle ───────────────────────
 
   private async ensureProcess(): Promise<AcpProcess> {

package/src/agents/pi/message-format.ts

@@ -0,0 +1,87 @@
+/**
+ * agents/pi/message-format.ts — Message formatting utilities for Pi adapter
+ *
+ * Pure functions that transform AgentMessage → pi prompt text
+ * and extract custom messages from session events.
+ */
+
+import type { AgentMessage } from "../../types";
+import type { AgentSessionEvent } from "@mariozechner/pi-coding-agent";
+
+/**
+ * Convert custom message content (string or array of parts) to plain text.
+ */
+export function customContentToText(content: unknown): string {
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) {
+    return content
+      .filter((part): part is { type: "text"; text: string } =>
+        !!part && typeof part === "object" && (part as any).type === "text"
+      )
+      .map((part) => part.text)
+      .join("");
+  }
+  return "";
+}
+
+/**
+ * Extract displayable text from a session event if it is an extension custom
+ * message (e.g. pi-lgtm review) with display=true. Returns null otherwise.
+ */
+export function extractCustomMessage(event: AgentSessionEvent): { customType: string; content: string } | null {
+  if (event.type !== "message_end") return null;
+  const message = (event as any).message;
+  if (!message || message.role !== "custom" || !message.display) return null;
+  const content = customContentToText(message.content);
+  if (!content.trim()) return null;
+  const customType = message.customType ?? "";
+  return { customType, content };
+}
+
+/**
+ * Format an AgentMessage into the text string that pi's session.prompt() expects.
+ * Handles attachment manifests with transcription data.
+ */
+export function formatMessage(message: AgentMessage): string {
+  let text = message.text;
+  if (message.attachments?.length) {
+    const manifest = JSON.stringify(
+      message.attachments.map((a) => {
+        const entry: Record<string, unknown> = {
+          id: a.id,
+          type: a.mediaType,
+          name: a.name,
+          localPath: a.localPath,
+          mime: a.mime,
+          sizeBytes: a.sizeBytes,
+          untrusted: true,
+        };
+        if (a.transcript?.status === "completed" && a.transcript.text) {
+          entry.transcript = {
+            text: a.transcript.text,
+            language: a.transcript.language,
+            provider: a.transcript.provider,
+            approximate: true,
+          };
+        } else if (a.transcript?.status === "failed") {
+          entry.transcript = {
+            status: "failed",
+            error: a.transcript.error,
+            approximate: true,
+          };
+        }
+        return entry;
+      }),
+      null,
+      2,
+    );
+    const block = [
+      "Chat attachments saved locally. Inspect files with tools before making claims. Transcripts are approximate; use the raw file if exact wording matters.",
+      "```json",
+      manifest,
+      "```",
+    ].join("\n");
+    text = text ? `${text}\n\n${block}` : block;
+  }
+  return text;
+}

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

@@ -26,7 +26,8 @@ import {
   type AgentSessionEvent,
 } from "@mariozechner/pi-coding-agent";
 
-import type { AgentAdapter, AgentAdapterFactory, AgentMessage, AgentResponse, AgentStreamEvent } from "../../types";
+import type { AgentAdapter, AgentAdapterFactory, AgentMessage, AgentResponse, AgentStreamEvent, MessageContext } from "../../types";
+import { formatMessage, extractCustomMessage, customContentToText } from "./message-format";
 import { SESSIONS_DIR } from "../../config";
 import { DEBUG_STREAM, threadIdToDir } from "../../util";
 
@@ -78,33 +79,6 @@ export const createPiAgentAdapter: AgentAdapterFactory = (config) => {
     }
   }
 
-  function customContentToText(content: unknown): string {
-    if (typeof content === "string") return content;
-    if (Array.isArray(content)) {
-      return content
-        .filter((part): part is { type: "text"; text: string } =>
-          !!part && typeof part === "object" && (part as any).type === "text"
-        )
-        .map((part) => part.text)
-        .join("");
-    }
-    return "";
-  }
-
-  /**
-   * Extract displayable text from a session event if it is an extension custom
-   * message (e.g. pi-lgtm review) with display=true. Returns null otherwise.
-   * Shared helper so promptStream() and doPrompt() use identical filter logic.
-   */
-  function extractCustomMessage(event: AgentSessionEvent): { customType: string; content: string } | null {
-    if (event.type !== "message_end") return null;
-    const message = (event as any).message;
-    if (!message || message.role !== "custom" || !message.display) return null;
-    const content = customContentToText(message.content);
-    if (!content.trim()) return null;
-    const customType = message.customType ?? "";
-    return { customType, content };
-  }
 
   async function runPromptAndFollowUps(entry: SessionEntry, text: string, onDraining?: () => void, onDrainComplete?: () => void): Promise<void> {
     entry.inFlight++;
@@ -283,50 +257,6 @@ export const createPiAgentAdapter: AgentAdapterFactory = (config) => {
    * Format an AgentMessage into the text string sent to the Pi session.
    * Attachments are rendered as a fenced JSON manifest appended to the user text.
    */
-  function formatMessage(message: AgentMessage): string {
-    let text = message.text;
-    if (message.attachments?.length) {
-      const manifest = JSON.stringify(
-        message.attachments.map((a) => {
-          const entry: Record<string, unknown> = {
-            id: a.id,
-            type: a.mediaType,
-            name: a.name,
-            localPath: a.localPath,
-            mime: a.mime,
-            sizeBytes: a.sizeBytes,
-            untrusted: true,
-          };
-          if (a.transcript?.status === "completed" && a.transcript.text) {
-            entry.transcript = {
-              text: a.transcript.text,
-              language: a.transcript.language,
-              provider: a.transcript.provider,
-              approximate: true,
-            };
-          } else if (a.transcript?.status === "failed") {
-            entry.transcript = {
-              status: "failed",
-              error: a.transcript.error,
-              approximate: true,
-            };
-          }
-          return entry;
-        }),
-        null,
-        2,
-      );
-      const block = [
-        "Chat attachments saved locally. Inspect files with tools before making claims. Transcripts are approximate; use the raw file if exact wording matters.",
-        "```json",
-        manifest,
-        "```",
-      ].join("\n");
-      text = text ? `${text}\n\n${block}` : block;
-    }
-    return text;
-  }
-
   const adapter: AgentAdapter = {
     name: "pi",
 
@@ -621,6 +551,13 @@ export const createPiAgentAdapter: AgentAdapterFactory = (config) => {
         extensions: memoryCapabilities?.extensions ?? [],
       };
     },
+
+    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.]" };
+      }
+      return message;
+    },
   };
 
   async function doPrompt(threadId: string, text: string): Promise<AgentResponse> {

package/src/cli/agent-command.ts

@@ -0,0 +1,210 @@
+/**
+ * cli/agent-command.ts — `roundhouse agent` implementation
+ *
+ * Extracted from cli.ts for single responsibility.
+ * Each sub-concern is a small, testable function.
+ */
+
+import { loadConfig } from "../config";
+import type { AgentAdapter } from "../types";
+
+// ── Types ────────────────────────────────────────────
+
+export interface AgentOptions {
+  threadId: string;
+  messageText: string;
+  timeoutMs: number;
+  verbose: boolean;
+}
+
+// ── Arg Parsing ──────────────────────────────────────
+
+/**
+ * Parse `roundhouse agent` CLI arguments into structured options.
+ * Exits the process on invalid input.
+ */
+export function parseAgentArgs(argv: string[]): { options: AgentOptions; useStdin: boolean } {
+  let threadId = "";
+  let messageText = "";
+  let useStdin = false;
+  let timeoutMs = 120_000;
+  let verbose = false;
+  let ephemeral = false;
+
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === "--thread" && argv[i + 1]) {
+      threadId = argv[++i];
+    } else if (argv[i] === "--stdin") {
+      useStdin = true;
+    } else if (argv[i] === "--timeout" && argv[i + 1]) {
+      const val = parseInt(argv[++i], 10);
+      if (isNaN(val) || val <= 0) {
+        console.error("--timeout must be a positive number (seconds)");
+        process.exit(1);
+      }
+      timeoutMs = val * 1000;
+    } else if (argv[i] === "--no-timeout") {
+      timeoutMs = 0;
+    } else if (argv[i] === "--verbose") {
+      verbose = true;
+    } else if (argv[i] === "--ephemeral") {
+      ephemeral = true;
+    } else if (argv[i].startsWith("-")) {
+      console.error(`Unknown flag: ${argv[i]}`);
+      process.exit(1);
+    } else {
+      messageText = argv.slice(i).join(" ");
+      break;
+    }
+  }
+
+  if (threadId && ephemeral) {
+    console.error("--thread and --ephemeral cannot be used together");
+    process.exit(1);
+  }
+
+  if (!threadId) {
+    threadId = ephemeral
+      ? `cli-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`
+      : "main";
+  }
+
+  return { options: { threadId, messageText, timeoutMs, verbose }, useStdin };
+}
+
+// ── Stdin Reader ─────────────────────────────────────
+
+const MAX_STDIN_BYTES = 1024 * 1024; // 1 MB
+
+/**
+ * Read stdin with a size limit. Returns the text content.
+ * Exits the process if input exceeds limit.
+ */
+export async function readStdinWithLimit(): Promise<string> {
+  const chunks: Buffer[] = [];
+  let totalBytes = 0;
+
+  for await (const chunk of process.stdin) {
+    totalBytes += chunk.length;
+    if (totalBytes > MAX_STDIN_BYTES) {
+      console.error(`Input exceeds ${MAX_STDIN_BYTES / 1024}KB limit. Use a file instead.`);
+      process.exit(1);
+    }
+    chunks.push(chunk);
+  }
+
+  let raw = Buffer.concat(chunks).toString("utf8");
+  // Strip single trailing newline (shell echo adds one)
+  if (raw.endsWith("\n")) raw = raw.slice(0, -1);
+  return raw;
+}
+
+// ── Agent Runner ─────────────────────────────────────
+
+/**
+ * Run the agent with timeout and signal handling.
+ * Streams output to stdout if streaming is available.
+ */
+export async function runAgentWithTimeout(opts: AgentOptions): Promise<void> {
+  const { threadId, messageText, timeoutMs, verbose } = opts;
+
+  // Suppress logs unless verbose
+  const origLog = console.log;
+  const origWarn = console.warn;
+  const origError = console.error;
+  if (!verbose) {
+    console.log = () => {};
+    console.warn = () => {};
+  }
+
+  let agent: AgentAdapter | undefined;
+  let aborted = false;
+
+  const handleSignal = async () => {
+    if (aborted) return;
+    aborted = true;
+    console.log = origLog;
+    console.warn = origWarn;
+    console.error = origError;
+    try { await agent?.abort?.(threadId); } catch {}
+    try { await agent?.dispose(); } catch {}
+    process.exit(130);
+  };
+  process.on("SIGINT", handleSignal);
+  process.on("SIGTERM", handleSignal);
+
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timeoutPromise = timeoutMs > 0
+    ? new Promise<never>((_, reject) => {
+        timer = setTimeout(async () => {
+          aborted = true;
+          try { await agent?.abort?.(threadId); } catch {}
+          reject(new Error(`Timeout after ${timeoutMs / 1000}s`));
+        }, timeoutMs);
+      })
+    : null;
+
+  try {
+    const config = await loadConfig();
+    const { getAgentFactory } = await import("../agents/registry");
+    const factory = getAgentFactory(config.agent.type);
+    agent = factory(config.agent);
+
+    const run = async () => {
+      if (agent!.promptStream) {
+        for await (const event of agent!.promptStream(threadId, { text: messageText })) {
+          if (event.type === "text_delta") {
+            process.stdout.write(event.text);
+          }
+        }
+        process.stdout.write("\n");
+      } else {
+        const response = await agent!.prompt(threadId, { text: messageText });
+        origLog(response.text);
+      }
+    };
+
+    if (timeoutPromise) {
+      await Promise.race([run(), timeoutPromise]);
+    } else {
+      await run();
+    }
+  } catch (err: any) {
+    console.error = origError;
+    console.error(`Error: ${err.message}`);
+    process.exit(aborted ? 124 : 1);
+  } finally {
+    if (timer) clearTimeout(timer);
+    process.off("SIGINT", handleSignal);
+    process.off("SIGTERM", handleSignal);
+    console.log = origLog;
+    console.warn = origWarn;
+    console.error = origError;
+    if (!aborted) await agent?.dispose();
+  }
+}
+
+// ── Entry Point ──────────────────────────────────────
+
+/**
+ * Main entry for `roundhouse agent` command.
+ */
+export async function cmdAgent(): Promise<void> {
+  const { options, useStdin } = parseAgentArgs(process.argv.slice(3));
+
+  if (useStdin) {
+    options.messageText = await readStdinWithLimit();
+  }
+
+  if (!options.messageText) {
+    console.error("Usage: roundhouse agent <message>");
+    console.error("       roundhouse agent --thread <id> <message>");
+    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);
+  }
+
+  await runAgentWithTimeout(options);
+}