@inceptionstack/roundhouse 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 InceptionStack
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,164 @@
+# roundhouse
+
+A multi-platform chat gateway that routes messages through a single configured AI agent.
+
+One gateway instance = one agent target (pi, Kiro, etc.), configured at install time.
+Multiple chat inputs (Telegram, Slack, Discord via [Vercel Chat SDK](https://chat-sdk.dev)) all feed into that same agent.
+
+## Architecture
+
+```
+ ┌─────────────────────────────────────────────────┐
+ │                 Vercel Chat SDK                  │
+ │  ┌───────────┐ ┌───────────┐ ┌──────────────┐   │
+ │  │ Telegram  │ │   Slack   │ │   Discord    │   │
+ │  └─────┬─────┘ └─────┬─────┘ └──────┬───────┘   │
+ │        └──────────────┼──────────────┘            │
+ └───────────────────────┬──────────────────────────┘
+                         │
+               ┌─────────┴──────────┐
+               │      Gateway       │
+               │                    │
+               │  • user allowlist  │
+               │  • message split   │
+               │  • typing indicator│
+               └─────────┬──────────┘
+                         │
+               ┌─────────┴──────────┐
+               │    AgentRouter     │
+               │                    │
+               │  today: single     │
+               │  agent pass-through│
+               │                    │
+               │  future: per-thread│
+               │  multi-agent, etc. │
+               └─────────┬──────────┘
+                         │
+               ┌─────────┴──────────┐
+               │   AgentAdapter     │  ← ONE, configured at install time
+               │                    │
+               │  e.g. Pi agent on  │
+               │  THIS machine with │
+               │  persistent        │
+               │  sessions on disk  │
+               └────────────────────┘
+```
+
+### Design decisions
+
+- **One gateway = one agent target.** The `agent` block in config picks the type and its settings. All chat inputs route to this single agent instance.
+- **Multiple chat inputs into the same agent.** Telegram and Slack messages go to the same agent, each on their own session thread (`telegram:<id>`, `slack:<id>`).
+- **AgentRouter is a seam.** Today it's `SingleAgentRouter` (hardcoded pass-through). The interface exists so we can later swap in per-thread routing, multi-agent, or load-balanced strategies without changing the gateway or adapters.
+- **AgentAdapter is the only abstraction we own.** The chat side is Vercel Chat SDK — we don't wrap it. The agent side is our `AgentAdapter` interface: `prompt(threadId, text) → AgentResponse`.
+- **Config-driven.** `gateway.config.json` (or `--config` flag, or env vars) determines everything at startup. No runtime reconfiguration.
+- **Persistent sessions.** Each thread gets its own session file on disk. Gateway restarts resume from the same file. Pi CLI can join the same session.
+
+## Quick start
+
+```bash
+npm install
+export TELEGRAM_BOT_TOKEN="your-token"
+export ALLOWED_USERS="your_telegram_username"
+npm start
+```
+
+## Config
+
+Place `gateway.config.json` in the project root, or use `--config path`:
+
+```json
+{
+  "agent": {
+    "type": "pi",
+    "cwd": "/home/you/project"
+  },
+  "chat": {
+    "botUsername": "my_bot",
+    "allowedUsers": ["your_username"],
+    "adapters": {
+      "telegram": { "mode": "polling" }
+    }
+  }
+}
+```
+
+Without a config file, defaults are used with env vars (`TELEGRAM_BOT_TOKEN`, `BOT_USERNAME`, `ALLOWED_USERS`).
+
+### Config reference
+
+| Field | Description |
+|-------|-------------|
+| `agent.type` | Agent backend: `"pi"` (more coming) |
+| `agent.cwd` | Working directory for the agent |
+| `agent.sessionDir` | Override session storage path |
+| `chat.botUsername` | Bot display name for Chat SDK |
+| `chat.allowedUsers` | Telegram usernames / user IDs allowed (empty = allow all) |
+| `chat.adapters.telegram` | `{ "mode": "polling" \| "webhook" \| "auto" }` |
+
+Secrets stay in env vars: `TELEGRAM_BOT_TOKEN`, `ANTHROPIC_API_KEY`, etc.
+
+## Joining a session from pi CLI
+
+Sessions are stored at `~/.pi/agent/gateway-sessions/<thread>/`. Resume from CLI:
+
+```bash
+pi --resume ~/.pi/agent/gateway-sessions/<thread_dir>/<session>.jsonl
+```
+
+Messages from Telegram/Slack and from the CLI share the same context.
+
+## Adding a new agent backend
+
+1. Create `src/agents/kiro.ts` implementing `AgentAdapter`
+2. Register in `src/agents/registry.ts`: `registry.set("kiro", createKiroAgentAdapter)`
+3. Set `"agent": { "type": "kiro" }` in config
+
+```typescript
+// src/agents/kiro.ts
+import type { AgentAdapter, AgentAdapterFactory } from "../types";
+
+export const createKiroAgentAdapter: AgentAdapterFactory = (config) => {
+  return {
+    name: "kiro",
+    async prompt(threadId, text) {
+      // your implementation
+      return { text: "response" };
+    },
+    async dispose() {},
+  };
+};
+```
+
+## Adding a new chat platform
+
+Add the Chat SDK adapter package and wire it in `gateway.ts`:
+
+```typescript
+// In buildChatAdapters():
+if (config.slack) {
+  const { createSlackAdapter } = await import("@chat-adapter/slack");
+  adapters.slack = createSlackAdapter();
+}
+```
+
+No other changes needed — the gateway's unified handler covers all platforms.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `src/index.ts` | Entry point, config loading, startup |
+| `src/gateway.ts` | Owns Chat SDK, wires events → router → agent |
+| `src/router.ts` | `AgentRouter` interface + `SingleAgentRouter` |
+| `src/types.ts` | Core interfaces: `AgentAdapter`, `AgentRouter`, `GatewayConfig` |
+| `src/util.ts` | Pure utilities: `splitMessage`, `isAllowed`, `threadIdToDir` |
+| `src/agents/pi.ts` | Pi agent adapter (persistent sessions via pi SDK) |
+| `src/agents/registry.ts` | Agent type → factory registry |
+| `test/` | Unit tests (vitest, 32 passing) |
+
+## Testing
+
+```bash
+npm test          # run once
+npm run test:watch # watch mode
+```

package/architecture.md

@@ -0,0 +1,214 @@
+# Architecture
+
+## Overview
+
+Roundhouse is a gateway that sits between **chat platforms** (Telegram, Slack, Discord) and a **single AI agent backend** (pi, Kiro, etc.).
+
+One gateway instance is configured for exactly one agent target at install time. Multiple chat platforms can feed into that same agent simultaneously.
+
+## System diagram
+
+```
+                    ┌─────────────────────────────────────────────────────┐
+                    │                   Vercel Chat SDK                   │
+                    │                                                     │
+                    │   ┌────────────┐  ┌────────────┐  ┌─────────────┐  │
+  Telegram users ──▶│   │  Telegram  │  │   Slack    │  │   Discord   │  │◀── Discord users
+                    │   │  Adapter   │  │  Adapter   │  │   Adapter   │  │
+  Slack users ─────▶│   └─────┬──────┘  └─────┬──────┘  └──────┬──────┘  │
+                    │         │               │                │         │
+                    │         └───────────────┼────────────────┘         │
+                    │                         │                          │
+                    │    onDirectMessage / onNewMention /                 │
+                    │    onSubscribedMessage                              │
+                    └─────────────────────────┬──────────────────────────┘
+                                              │
+                                              ▼
+                                  ┌───────────────────────┐
+                                  │       Gateway          │
+                                  │                        │
+                                  │  • User allowlist      │
+                                  │  • Message splitting   │
+                                  │  • Typing indicators   │
+                                  │  • Error handling      │
+                                  └───────────┬────────────┘
+                                              │
+                                              ▼
+                                  ┌───────────────────────┐
+                                  │     AgentRouter        │
+                                  │                        │
+                                  │  SingleAgentRouter     │
+                                  │  (pass-through today)  │
+                                  │                        │
+                                  │  Future:               │
+                                  │  • MultiAgentRouter    │
+                                  │  • UserChoiceRouter    │
+                                  │  • FallbackRouter      │
+                                  └───────────┬────────────┘
+                                              │
+                                              ▼
+                                  ┌───────────────────────┐
+                                  │     AgentAdapter       │
+                                  │                        │
+                                  │  Configured at install │
+                                  │  time via config file  │
+                                  │                        │
+                                  │  ┌─────────────────┐   │
+                                  │  │   Pi Agent      │   │
+                                  │  │                 │   │
+                                  │  │  • pi SDK       │   │
+                                  │  │  • persistent   │   │
+                                  │  │    .jsonl       │   │
+                                  │  │    sessions     │   │
+                                  │  │  • per-thread   │   │
+                                  │  │    isolation    │   │
+                                  │  └─────────────────┘   │
+                                  │                        │
+                                  │  (or Kiro, Raw LLM,    │
+                                  │   custom agent, etc.)  │
+                                  └────────────────────────┘
+                                              │
+                                              ▼
+                                  ┌────────────────────────┐
+                                  │   Session storage       │
+                                  │                         │
+                                  │  ~/.pi/agent/           │
+                                  │    gateway-sessions/    │
+                                  │      telegram_c<id>/    │
+                                  │        <session>.jsonl  │
+                                  │      slack_c<id>/       │
+                                  │        <session>.jsonl  │
+                                  └────────────────────────┘
+```
+
+## Data flow
+
+```
+User sends "list files" on Telegram
+         │
+         ▼
+┌─ Vercel Chat SDK ────────────────────────────────────────────┐
+│  Telegram adapter receives update via polling                │
+│  Normalizes to: { thread.id, message.text, message.author } │
+│  Fires onDirectMessage(thread, message)                      │
+└──────────────────────────────┬───────────────────────────────┘
+                               │
+                               ▼
+┌─ Gateway ────────────────────────────────────────────────────┐
+│  1. Check isAllowed(message.author, allowedUsers)            │
+│  2. Resolve agent via router.resolve(thread.id)              │
+│  3. thread.startTyping()                                     │
+│  4. agent.prompt(thread.id, "list files")                    │
+│     └─▶ Pi SDK creates/resumes session                       │
+│         └─▶ LLM processes, tools execute                     │
+│         └─▶ Returns AgentResponse { text: "..." }            │
+│  5. splitMessage(response.text, 4000)                        │
+│  6. thread.post(chunk) for each chunk                        │
+└──────────────────────────────────────────────────────────────┘
+                               │
+                               ▼
+            User receives reply on Telegram
+```
+
+## Key interfaces
+
+```typescript
+interface AgentAdapter {
+  name: string;
+  prompt(threadId: string, text: string): Promise<AgentResponse>;
+  dispose(): Promise<void>;
+}
+
+interface AgentResponse {
+  text: string;
+  metadata?: Record<string, unknown>;
+}
+
+interface AgentRouter {
+  resolve(threadId: string): AgentAdapter;
+  dispose(): Promise<void>;
+}
+```
+
+## Config model
+
+```
+gateway.config.json
+├── agent                     # Exactly ONE agent target
+│   ├── type: "pi"            # Selects factory from registry
+│   ├── cwd: "/home/user"     # Agent working directory
+│   └── sessionDir: "..."     # Override session storage
+│
+└── chat                      # Multiple chat inputs
+    ├── botUsername: "my_bot"
+    ├── allowedUsers: [...]   # Auth filter (userName or userId)
+    └── adapters
+        ├── telegram: { mode: "polling" }
+        ├── slack: { ... }    # (future)
+        └── discord: { ... }  # (future)
+```
+
+Secrets (`TELEGRAM_BOT_TOKEN`, `ANTHROPIC_API_KEY`) are always env vars, never in config.
+
+## Startup sequence
+
+```
+1. Load config (--config flag → gateway.config.json → env var defaults)
+2. Look up agent.type in registry → get factory function
+3. factory(agentConfig) → AgentAdapter instance
+4. Wrap in SingleAgentRouter
+5. Create Gateway(router, config)
+6. gateway.start():
+   a. Build Chat SDK adapters from config (lazy import)
+   b. Create Chat instance with all adapters
+   c. Wire onDirectMessage / onNewMention / onSubscribedMessage → handle()
+   d. chat.initialize() — starts polling / webhooks
+7. Running. Ctrl+C → gateway.stop() → router.dispose() → agent.dispose()
+```
+
+## Session threading
+
+Each chat platform thread gets its own agent session:
+
+```
+Telegram DM with Alice    →  threadId = "telegram:123456789"  →  session A
+Slack DM with Alice       →  threadId = "slack:U12345"         →  session B
+Telegram group mention  →  threadId = "telegram:-100123456"  →  session C
+```
+
+These are **separate sessions** by design. Cross-platform session unification (mapping multiple platform identities to one session) is a future capability.
+
+Sessions persist as `.jsonl` files. The gateway resumes them on restart. Pi CLI can join any session with:
+
+```bash
+pi --resume ~/.pi/agent/gateway-sessions/<thread_dir>/<session>.jsonl
+```
+
+## Router extensibility
+
+The `AgentRouter` interface is a seam for future multi-agent routing:
+
+| Router | Behavior |
+|--------|----------|
+| `SingleAgentRouter` | All threads → one agent (current) |
+| `MultiAgentRouter` | Map thread prefixes to different agents |
+| `UserChoiceRouter` | User sends `/agent kiro` to switch |
+| `FallbackRouter` | Try primary agent, fall back to secondary |
+| `RoundRobinRouter` | Load balance across agent instances |
+
+The gateway and agent adapters don't change — only the router.
+
+## Module dependency graph
+
+```
+index.ts
+  ├── agents/registry.ts
+  │     └── agents/pi.ts
+  │           └── util.ts (threadIdToDir)
+  ├── router.ts
+  ├── gateway.ts
+  │     └── util.ts (splitMessage, isAllowed)
+  └── types.ts (shared interfaces)
+```
+
+No circular dependencies. `util.ts` and `types.ts` are leaf modules.

package/bin/roundhouse.mjs

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import("tsx/esm/api").then(({ register }) => {
+  register();
+  import("../src/cli/cli.ts");
+});

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@inceptionstack/roundhouse",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Multi-platform chat gateway that routes messages through a configured AI agent",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/inceptionstack/roundhouse.git"
+  },
+  "keywords": [
+    "chat",
+    "gateway",
+    "telegram",
+    "slack",
+    "discord",
+    "ai",
+    "agent",
+    "pi",
+    "bot"
+  ],
+  "bin": {
+    "roundhouse": "bin/roundhouse.mjs"
+  },
+  "scripts": {
+    "start": "tsx src/index.ts",
+    "dev": "tsx watch src/index.ts",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "files": [
+    "src/",
+    "bin/",
+    "LICENSE",
+    "README.md",
+    "architecture.md"
+  ],
+  "dependencies": {
+    "@chat-adapter/state-memory": "latest",
+    "@chat-adapter/telegram": "latest",
+    "@mariozechner/pi-coding-agent": "latest",
+    "chat": "latest",
+    "tsx": "^4.0.0"
+  },
+  "devDependencies": {
+    "vitest": "^4.1.5"
+  }
+}

package/src/agents/pi.ts

@@ -0,0 +1,154 @@
+/**
+ * agents/pi.ts — Pi agent adapter
+ *
+ * Wraps pi's SDK (createAgentSession) as an AgentAdapter.
+ * One persistent session per thread, stored at:
+ *   ~/.pi/agent/gateway-sessions/<thread_id>/<session>.jsonl
+ */
+
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+import {
+  AuthStorage,
+  createAgentSession,
+  ModelRegistry,
+  SessionManager,
+  type AgentSession,
+  type AgentSessionEvent,
+} from "@mariozechner/pi-coding-agent";
+
+import type { AgentAdapter, AgentAdapterFactory, AgentResponse } from "../types";
+import { threadIdToDir } from "../util";
+
+interface SessionEntry {
+  session: AgentSession;
+  lastUsed: number;
+}
+
+const DEFAULT_SESSIONS_DIR = join(
+  homedir(),
+  ".pi",
+  "agent",
+  "gateway-sessions"
+);
+const DEFAULT_MAX_IDLE_MS = 30 * 60 * 1000;
+
+export const createPiAgentAdapter: AgentAdapterFactory = (config) => {
+  const cwd = (config.cwd as string) ?? process.cwd();
+  const sessionsDir =
+    (config.sessionDir as string) ?? DEFAULT_SESSIONS_DIR;
+  const maxIdleMs =
+    (config.maxIdleMs as number) ?? DEFAULT_MAX_IDLE_MS;
+
+  const authStorage = AuthStorage.create();
+  const modelRegistry = ModelRegistry.create(authStorage);
+  const sessions = new Map<string, SessionEntry>();
+  // Track in-flight session creation to prevent races
+  const creating = new Map<string, Promise<SessionEntry>>();
+  let reapInterval: ReturnType<typeof setInterval> | undefined;
+
+  async function createSession(threadId: string): Promise<SessionEntry> {
+    const threadDir = join(sessionsDir, threadIdToDir(threadId));
+    await mkdir(threadDir, { recursive: true });
+
+    let sessionManager: InstanceType<typeof SessionManager>;
+
+    try {
+      sessionManager = SessionManager.continueRecent(cwd, threadDir);
+      console.log(
+        `[pi-agent] resuming session for ${threadId}: ${sessionManager.getSessionFile()}`
+      );
+    } catch {
+      sessionManager = SessionManager.create(cwd, threadDir);
+      console.log(
+        `[pi-agent] new session for ${threadId}: ${sessionManager.getSessionFile()}`
+      );
+    }
+
+    const result = await createAgentSession({
+      cwd,
+      sessionManager,
+      authStorage,
+      modelRegistry,
+    });
+
+    if (result.modelFallbackMessage) {
+      console.log(`[pi-agent] model fallback: ${result.modelFallbackMessage}`);
+    }
+
+    const entry: SessionEntry = { session: result.session, lastUsed: Date.now() };
+    sessions.set(threadId, entry);
+    return entry;
+  }
+
+  async function getOrCreate(threadId: string): Promise<SessionEntry> {
+    // Fast path: already created
+    const existing = sessions.get(threadId);
+    if (existing) return existing;
+
+    // Prevent concurrent creation for the same threadId
+    let pending = creating.get(threadId);
+    if (pending) return pending;
+
+    pending = createSession(threadId).finally(() => {
+      creating.delete(threadId);
+    });
+    creating.set(threadId, pending);
+    return pending;
+  }
+
+  function reap() {
+    const now = Date.now();
+    for (const [id, entry] of sessions) {
+      if (now - entry.lastUsed > maxIdleMs) {
+        entry.session.dispose();
+        sessions.delete(id);
+        console.log(`[pi-agent] reaped idle handle for ${id}`);
+      }
+    }
+  }
+
+  // Start reaper (unref so it doesn't prevent Node from exiting)
+  reapInterval = setInterval(reap, 60_000);
+  reapInterval.unref();
+
+  const adapter: AgentAdapter = {
+    name: "pi",
+
+    async prompt(threadId: string, text: string): Promise<AgentResponse> {
+      const entry = await getOrCreate(threadId);
+      entry.lastUsed = Date.now();
+
+      let fullText = "";
+      const unsub = entry.session.subscribe((event: AgentSessionEvent) => {
+        if (
+          event.type === "message_update" &&
+          event.assistantMessageEvent.type === "text_delta"
+        ) {
+          fullText += event.assistantMessageEvent.delta;
+        }
+      });
+
+      try {
+        await entry.session.prompt(text);
+      } finally {
+        unsub();
+      }
+
+      return { text: fullText };
+    },
+
+    async dispose(): Promise<void> {
+      if (reapInterval) clearInterval(reapInterval);
+      for (const [, entry] of sessions) {
+        entry.session.dispose();
+      }
+      sessions.clear();
+      creating.clear();
+    },
+  };
+
+  return adapter;
+};

package/src/agents/registry.ts

@@ -0,0 +1,25 @@
+/**
+ * agents/registry.ts — Agent adapter registry
+ *
+ * Maps agent type names to their factory functions.
+ * Add new agents here.
+ */
+
+import type { AgentAdapterFactory } from "../types";
+import { createPiAgentAdapter } from "./pi";
+
+const registry = new Map<string, AgentAdapterFactory>();
+
+registry.set("pi", createPiAgentAdapter);
+// registry.set("kiro", createKiroAgentAdapter);
+
+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}`
+    );
+  }
+  return factory;
+}