@inceptionstack/roundhouse 0.4.2 → 0.4.4

package/README.md

@@ -58,7 +58,8 @@ When you run `roundhouse setup`, the following are installed automatically:
 
 - **30+ Skills** (agent knowledge): Synced from [loki-skills](https://github.com/inceptionstack/loki-skills) (AWS, infrastructure, DevOps patterns)
 - **CLI Tools**: `mcporter` (MCP server bridge), `@playwright/cli` (browser automation), `uv`/`uvx` (Python package runner)
-- **Extensions** (shipped in npm, auto-discovered by pi): `web-search` (Tavily API integration)
+- **Extensions** (copied to `~/.pi/agent/extensions/` if not present; never overwrites user copies): `web-search` (Tavily)
+- **Extension packages** (registered in `settings.json`): `pi-hard-no` (code review), `pi-branch-enforcer` (branch protection)
 - **Config**: MCP server definitions copied to `~/.mcporter/mcporter.json`
 
 This gives the agent access to:
@@ -429,24 +430,30 @@ pi install git:github.com/inceptionstack/pi-autoreview
 
 ## 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
+1. Create `src/agents/myagent/myagent-adapter.ts` extending `BaseAdapter`
+2. Register in `src/agents/registry.ts`
+3. Set `"agent": { "type": "myagent" }` in config
 
 ```typescript
-import type { AgentAdapter, AgentAdapterFactory } from "../types";
-
-export const createKiroAgentAdapter: AgentAdapterFactory = (config) => {
-  return {
-    name: "kiro",
-    async prompt(threadId, message) {
-      // message.text contains user text
-      // message.attachments contains saved file metadata
-      return { text: "response" };
-    },
-    async dispose() {},
-  };
-};
+import type { AgentAdapterFactory, AgentMessage, AgentResponse, AgentStreamEvent } from "../../types.js";
+import { BaseAdapter } from "../base-adapter.js";
+
+class MyAgentAdapter extends BaseAdapter {
+  readonly name = "myagent";
+
+  async prompt(threadId: string, message: AgentMessage): Promise<AgentResponse> {
+    return { text: "response" };
+  }
+
+  async *promptStream(threadId: string, message: AgentMessage): AsyncIterable<AgentStreamEvent> {
+    yield { type: "text_delta", text: "response" };
+    yield { type: "agent_end" };
+  }
+
+  async dispose(): Promise<void> {}
+}
+
+export const createMyAgentAdapter: AgentAdapterFactory = (config) => new MyAgentAdapter();
 ```
 
 ## Adding a new chat platform
@@ -480,7 +487,9 @@ No other changes needed — the gateway's unified handler covers all platforms.
 | `src/cron/` | Cron scheduler, runner, store, schedule, template, format |
 | `src/cron/helpers.ts` | Shared cron constants and utilities |
 | `src/notify/telegram.ts` | Shared Telegram Bot API sender |
-| `src/agents/pi.ts` | Pi agent adapter (persistent sessions via pi SDK) |
+| `src/agents/pi/pi-adapter.ts` | Pi agent adapter (persistent sessions via pi SDK) |
+| `src/agents/kiro/kiro-adapter.ts` | Kiro CLI agent adapter (ACP over stdio) |
+| `src/agents/base-adapter.ts` | Abstract base class — adapter interface contract |
 | `src/agents/registry.ts` | Agent type → factory registry |
 | `src/config.ts` | Shared config loading, defaults, env overrides |
 | `test/` | Unit tests (vitest, 75 passing) |

package/architecture.md

@@ -143,16 +143,22 @@ interface AttachmentTranscript {
 }
 
 interface AgentAdapter {
-  name: string;
-  prompt(threadId: string, message: AgentMessage): Promise<AgentResponse>;
-  promptStream?(threadId: string, message: AgentMessage): AsyncIterable<AgentStreamEvent>;
+  readonly name: string;
+  prompt(threadId: string, message: AgentMessage): Promise<AgentResponse>;        // required
+  promptStream(threadId: string, message: AgentMessage): AsyncIterable<AgentStreamEvent>; // required
+  dispose(): Promise<void>;                                                       // required
+  promptWithModel?(threadId: string, message: AgentMessage, modelId: string): Promise<AgentResponse>;
   restart?(threadId: string): Promise<void>;
   compact?(threadId: string): Promise<{ tokensBefore: number; tokensAfter: number | null } | null>;
+  compactWithModel?(threadId: string, modelId: string): Promise<{ tokensBefore: number; tokensAfter: number | null } | null>;
   abort?(threadId: string): Promise<void>;
   getInfo?(threadId?: string): Record<string, unknown>;
-  dispose(): Promise<void>;
 }
 
+// New adapters extend BaseAdapter (src/agents/base-adapter.ts) which
+// provides default implementations for optional methods.
+// Each adapter lives in its own directory: pi/pi-adapter.ts, kiro/kiro-adapter.ts
+
 interface AgentResponse {
   text: string;
   metadata?: Record<string, unknown>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inceptionstack/roundhouse",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "type": "module",
   "description": "Multi-platform chat gateway that routes messages through a configured AI agent",
   "license": "MIT",
@@ -48,10 +48,5 @@
   },
   "devDependencies": {
     "vitest": "^4.1.5"
-  },
-  "pi": {
-    "extensions": [
-      "./pi/extensions"
-    ]
   }
 }

package/pi/extensions/web-search.ts

@@ -31,8 +31,7 @@ export default function (pi: ExtensionAPI) {
       const startTime = Date.now();
       const controller = new AbortController();
       const timeout = setTimeout(() => controller.abort(), 30_000);
-      if (signal?.aborted) controller.abort();
-      else if (signal) signal.addEventListener("abort", () => controller.abort(), { once: true });
+      if (signal) signal.addEventListener("abort", () => controller.abort());
 
       let response: Response;
       try {
@@ -47,13 +46,6 @@ export default function (pi: ExtensionAPI) {
           }),
           signal: controller.signal,
         });
-      } catch (err: any) {
-        clearTimeout(timeout);
-        const msg = err.name === "AbortError" ? "Request timed out or was cancelled" : err.message;
-        return {
-          content: [{ type: "text", text: `Web search failed: ${msg}` }],
-          details: { query: params.query, error: msg },
-        };
       } finally {
         clearTimeout(timeout);
       }

package/src/agents/base-adapter.ts

@@ -0,0 +1,92 @@
+/**
+ * agents/base-adapter.ts — Abstract base class for agent adapters.
+ *
+ * Defines the fixed interface contract that every adapter must fulfill.
+ * Required methods are abstract; optional capabilities have default
+ * implementations that callers can rely on.
+ *
+ * Each concrete adapter (PiAdapter, KiroAdapter) extends this class
+ * and lives in its own directory with no cross-adapter imports.
+ */
+
+import type { AgentAdapter, AgentMessage, AgentResponse, AgentStreamEvent, AdapterInfo } from "../types.js";
+export type { AdapterInfo } from "../types.js";
+
+/**
+ * Abstract base class for all agent adapters.
+ *
+ * Subclasses MUST implement:
+ *   - name (property)
+ *   - prompt()
+ *   - promptStream()
+ *   - dispose()
+ *
+ * Subclasses MAY override:
+ *   - promptWithModel()  — defaults to prompt() ignoring model
+ *   - restart()          — defaults to no-op
+ *   - compact()          — defaults to null (not supported)
+ *   - compactWithModel() — defaults to compact() ignoring model
+ *   - abort()            — defaults to no-op
+ *   - getInfo()          — defaults to empty object
+ */
+export abstract class BaseAdapter implements AgentAdapter {
+  /** Unique agent type identifier, e.g. "pi", "kiro" */
+  abstract readonly name: string;
+
+  // ── Required: every adapter must implement these ─────
+
+  /** Send a user message and return the full assistant response. */
+  abstract prompt(threadId: string, message: AgentMessage): Promise<AgentResponse>;
+
+  /** Send a user message and stream back events in real time. */
+  abstract promptStream(threadId: string, message: AgentMessage): AsyncIterable<AgentStreamEvent>;
+
+  /** Tear down all sessions and release resources. */
+  abstract dispose(): Promise<void>;
+
+  // ── Optional: override for adapter-specific behavior ─
+
+  /**
+   * Send a prompt using a specific model (e.g. Haiku for memory flush).
+   * Default: ignores modelId, delegates to prompt().
+   */
+  async promptWithModel(threadId: string, message: AgentMessage, _modelId: string): Promise<AgentResponse> {
+    return this.prompt(threadId, message);
+  }
+
+  /**
+   * Dispose the session for a thread and start fresh on next prompt.
+   * Default: no-op.
+   */
+  async restart(_threadId: string): Promise<void> {}
+
+  /**
+   * Compact the session context for a thread.
+   * Default: returns null (not supported).
+   */
+  async compact(_threadId: string): Promise<{ tokensBefore: number; tokensAfter: number | null } | null> {
+    return null;
+  }
+
+  /**
+   * Compact with a specific model.
+   * Default: ignores modelId, delegates to compact().
+   */
+  async compactWithModel(threadId: string, _modelId: string): Promise<{ tokensBefore: number; tokensAfter: number | null } | null> {
+    return this.compact(threadId);
+  }
+
+  /**
+   * Abort the current agent run for a thread.
+   * Default: no-op.
+   */
+  async abort(_threadId: string): Promise<void> {}
+
+  /**
+   * Return runtime info about the agent (model, version, context usage, etc.).
+   * Default: returns empty object.
+   */
+  getInfo(_threadId?: string): AdapterInfo {
+    return {};
+  }
+}

package/src/agents/index.ts

@@ -0,0 +1,7 @@
+/**
+ * agents/index.ts — Public API for the agents subsystem.
+ */
+
+export { BaseAdapter } from "./base-adapter.js";
+export { getAgentDefinition, getAgentFactory, listAvailableAgentTypes, isKnownAgentType, getAgentSdkPackage } from "./registry.js";
+export type { AgentDefinition, AgentPackageRequirement, AgentSetupContext } from "./registry.js";

package/src/agents/kiro/acp/client.ts

@@ -0,0 +1,117 @@
+/**
+ * acp/client.ts — JSON-RPC stdio transport for kiro-cli ACP
+ *
+ * Handles request/response correlation and notification dispatch.
+ * Does NOT manage process lifecycle — that's acp/process.ts.
+ */
+
+import { EventEmitter } from "node:events";
+import type { ChildProcessWithoutNullStreams } from "node:child_process";
+
+export interface PendingRequest {
+  resolve: (value: unknown) => void;
+  reject: (error: unknown) => void;
+  timer: ReturnType<typeof setTimeout>;
+}
+
+export class AcpClient extends EventEmitter {
+  private buf = "";
+  private pending = new Map<number, PendingRequest>();
+  private nextId = 1;
+  private closed = false;
+
+  constructor(private proc: ChildProcessWithoutNullStreams, private requestTimeoutMs = 60_000) {
+    super();
+    this.proc.stdout.on("data", (chunk: Buffer) => this.onData(chunk));
+    this.proc.on("exit", (code) => {
+      this.closed = true;
+      this.rejectAll(new Error(`kiro-cli exited with code ${code}`));
+      this.emit("exit", code);
+    });
+  }
+
+  /** Send a JSON-RPC request and await its response. */
+  async call<T = unknown>(method: string, params?: unknown): Promise<T> {
+    if (this.closed) throw new Error("ACP client is closed");
+
+    const id = this.nextId++;
+    const payload = JSON.stringify({ jsonrpc: "2.0", id, method, params: params ?? {} });
+    this.proc.stdin.write(payload + "\n");
+
+    return new Promise<T>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error(`ACP call "${method}" timed out after ${this.requestTimeoutMs}ms`));
+      }, this.requestTimeoutMs);
+
+      this.pending.set(id, { resolve: resolve as (v: unknown) => void, reject, timer });
+    });
+  }
+
+  /** Send a JSON-RPC notification (no response expected). */
+  notify(method: string, params?: unknown): void {
+    if (this.closed) return;
+    const payload = JSON.stringify({ jsonrpc: "2.0", method, params: params ?? {} });
+    this.proc.stdin.write(payload + "\n");
+  }
+
+  /** Gracefully close — reject pending requests. */
+  close(): void {
+    this.closed = true;
+    this.rejectAll(new Error("ACP client closed"));
+  }
+
+  get isClosed(): boolean {
+    return this.closed;
+  }
+
+  // ── Private ──────────────────────────────────────────
+
+  private onData(chunk: Buffer): void {
+    this.buf += chunk.toString("utf8");
+    let idx: number;
+    while ((idx = this.buf.indexOf("\n")) >= 0) {
+      const line = this.buf.slice(0, idx).trim();
+      this.buf = this.buf.slice(idx + 1);
+      if (!line) continue;
+      this.parseLine(line);
+    }
+  }
+
+  private parseLine(line: string): void {
+    let msg: Record<string, unknown>;
+    try {
+      msg = JSON.parse(line);
+    } catch (e) {
+      this.emit("parse_error", e, line);
+      return;
+    }
+
+    // Response to a pending request
+    if ("id" in msg && typeof msg.id === "number" && this.pending.has(msg.id)) {
+      const { resolve, reject, timer } = this.pending.get(msg.id)!;
+      clearTimeout(timer);
+      this.pending.delete(msg.id);
+      if (msg.error) reject(msg.error);
+      else resolve(msg.result);
+      return;
+    }
+
+    // Notification from kiro-cli
+    if ("method" in msg && typeof msg.method === "string") {
+      this.emit(msg.method, msg.params);
+      this.emit("notification", msg.method, msg.params);
+      return;
+    }
+
+    this.emit("unknown_message", msg);
+  }
+
+  private rejectAll(error: Error): void {
+    for (const [id, { reject, timer }] of this.pending) {
+      clearTimeout(timer);
+      reject(error);
+    }
+    this.pending.clear();
+  }
+}

package/src/agents/kiro/acp/index.ts

@@ -0,0 +1,8 @@
+/**
+ * kiro/acp/index.ts — Barrel export for ACP module
+ */
+
+export { AcpClient } from "./client.js";
+export { spawnKiroCli, shutdownProcess, getKiroCliVersion } from "./process.js";
+export type { AcpProcess, SpawnOptions } from "./process.js";
+export type * from "./types.js";

package/src/agents/kiro/acp/process.ts

@@ -0,0 +1,111 @@
+/**
+ * acp/process.ts — kiro-cli process lifecycle management
+ *
+ * Handles spawning, stderr capture, orphan guards, and graceful shutdown.
+ * One process per agent config (main or flush).
+ */
+
+import { spawn, execFileSync, type ChildProcessWithoutNullStreams } from "node:child_process";
+import { AcpClient } from "./client.js";
+
+export interface SpawnOptions {
+  agentName: string;
+  cwd: string;
+  env?: Record<string, string>;
+  /** Max stderr buffer in bytes (default 1MB) */
+  maxStderrBytes?: number;
+}
+
+export interface AcpProcess {
+  client: AcpClient;
+  proc: ChildProcessWithoutNullStreams;
+  stderr: string[];
+  kill(signal?: NodeJS.Signals): void;
+  killGroup(): void;
+}
+
+/**
+ * Spawn kiro-cli in ACP mode and return the wrapped process + client.
+ * Throws if the binary is not found.
+ */
+export function spawnKiroCli(opts: SpawnOptions): AcpProcess {
+  const { agentName, cwd, env, maxStderrBytes = 1_048_576 } = opts;
+
+  const proc = spawn("kiro-cli", ["chat", "--agent", agentName, "--acp"], {
+    cwd,
+    env: { ...process.env, ...env },
+    stdio: ["pipe", "pipe", "pipe"],
+    detached: true, // own process group for clean kill
+  });
+
+  // Handle spawn failures (e.g. ENOENT if kiro-cli not on PATH)
+  proc.on("error", (err) => {
+    console.error(`[kiro] failed to spawn kiro-cli: ${err.message}`);
+    // Emit exit so AcpClient rejects pending requests immediately
+    proc.emit("exit", 1);
+  });
+
+  // Buffer stderr for diagnostics (capped)
+  const stderr: string[] = [];
+  let stderrBytes = 0;
+  proc.stderr.on("data", (chunk: Buffer) => {
+    const str = chunk.toString("utf8");
+    stderrBytes += chunk.length;
+    if (stderrBytes <= maxStderrBytes) {
+      stderr.push(str);
+    }
+  });
+
+  const client = new AcpClient(proc);
+
+  return {
+    client,
+    proc,
+    stderr,
+    kill(signal: NodeJS.Signals = "SIGTERM") {
+      try { proc.kill(signal); } catch {}
+    },
+    killGroup() {
+      if (proc.pid) {
+        try { process.kill(-proc.pid, "SIGKILL"); } catch {}
+      }
+    },
+  };
+}
+
+/**
+ * Gracefully shutdown a kiro-cli process:
+ * SIGTERM → wait up to `gracePeriodMs` → SIGKILL the process group.
+ */
+export async function shutdownProcess(acpProc: AcpProcess, gracePeriodMs = 5_000): Promise<void> {
+  acpProc.client.close();
+  acpProc.kill("SIGTERM");
+
+  await new Promise<void>((resolve) => {
+    const timer = setTimeout(() => {
+      acpProc.killGroup();
+      resolve();
+    }, gracePeriodMs);
+
+    acpProc.proc.on("exit", () => {
+      clearTimeout(timer);
+      resolve();
+    });
+  });
+}
+
+/**
+ * Check if kiro-cli is available on PATH.
+ * Returns the version string or null if not found.
+ */
+export function getKiroCliVersion(): string | null {
+  try {
+    const output = execFileSync("kiro-cli", ["--version"], {
+      encoding: "utf8",
+      timeout: 5_000,
+    }).trim();
+    return output || null;
+  } catch {
+    return null;
+  }
+}

package/src/agents/kiro/acp/types.ts

@@ -0,0 +1,83 @@
+/**
+ * acp/types.ts — ACP (Agent Control Protocol) type definitions
+ *
+ * Discriminated union of events received from kiro-cli over JSON-RPC stdio.
+ */
+
+// ── Stop reasons ─────────────────────────────────────
+
+export type StopReason = "end_turn" | "cancelled" | "max_turns" | "error";
+
+// ── ACP Events (notifications from kiro-cli) ─────────
+
+export interface AcpTextChunk {
+  type: "text_chunk";
+  text: string;
+}
+
+export interface AcpThinkingChunk {
+  type: "thinking_chunk";
+  text: string;
+}
+
+export interface AcpToolCall {
+  type: "tool_call";
+  tool_call_id: string;
+  title: string;
+  tool_name: string;
+  tool_input: Record<string, unknown>;
+  tool_kind?: string;
+}
+
+export interface AcpToolResult {
+  type: "tool_result";
+  tool_call_id: string;
+  output: string;
+  exit_code: number;
+}
+
+export interface AcpPermissionRequest {
+  type: "permission_request";
+  tool_call_id: string;
+  tool_name: string;
+  tool_input: Record<string, unknown>;
+  title?: string;
+}
+
+export interface AcpComplete {
+  type: "complete";
+  stop_reason: StopReason;
+  error?: string;
+}
+
+export interface AcpSessionUpdate {
+  type: "session/update";
+  context_tokens?: number;
+  context_window?: number;
+  model?: string;
+}
+
+export type AcpEvent =
+  | AcpTextChunk
+  | AcpThinkingChunk
+  | AcpToolCall
+  | AcpToolResult
+  | AcpPermissionRequest
+  | AcpComplete
+  | AcpSessionUpdate;
+
+// ── ACP method results ───────────────────────────────
+
+export interface InitializeResult {
+  protocolVersion: string;
+  capabilities: Record<string, unknown>;
+}
+
+export interface SessionNewResult {
+  sessionId: string;
+}
+
+export interface SessionLoadResult {
+  sessionId: string;
+  restored: boolean;
+}