@inceptionstack/roundhouse 0.5.7 → 0.5.9

package/package.json

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

package/src/cli/cli.ts

@@ -370,6 +370,7 @@ Commands:
   doctor [--fix]       Check system health and configuration
                        Options: --fix, --json, --verbose
   cron <command>       Manage scheduled jobs (add, list, trigger, etc.)
+  message "text"       Send a message to active transports via gateway
 
 Config:
   ~/.roundhouse/gateway.config.json
@@ -388,6 +389,7 @@ import { cmdDoctor } from "./doctor";
 import { cmdAgent } from "./agent-command";
 import { cmdCron } from "./cron";
 import { cmdSetup, cmdPair } from "./setup";
+import { cmdMessage } from "./message";
 
 const command = process.argv[2];
 
@@ -407,6 +409,7 @@ const commands: Record<string, () => void | Promise<void>> = {
   tui: cmdTui,
   doctor: () => cmdDoctor(process.argv.slice(3)),
   cron: () => cmdCron(process.argv.slice(3)),
+  message: () => cmdMessage(process.argv.slice(3)),
   agent: cmdAgent,
 };
 

package/src/cli/cron-commands.ts

@@ -105,9 +105,23 @@ export async function cronAdd(store: CronStore, positional: string[], flags: Rec
 }
 
 export async function cronList(store: CronStore, _positional: string[], flags: Record<string, string>): Promise<void> {
-  const jobs = await store.listJobs();
+  let jobs = await store.listJobs();
+
+  // Hide completed one-shot jobs unless --all flag is set
+  if (!flags.all) {
+    const filtered: typeof jobs = [];
+    for (const j of jobs) {
+      if (j.schedule.type === "once") {
+        const state = await store.getState(j.id);
+        if (state.totalRuns > 0) continue;
+      }
+      filtered.push(j);
+    }
+    jobs = filtered;
+  }
+
   if (jobs.length === 0) {
-    console.log("No cron jobs configured.");
+    console.log("No active cron jobs.");
     return;
   }
   if (flags.json) {

package/src/cli/message.ts

@@ -0,0 +1,41 @@
+/**
+ * cli/message.ts — Send a message to the running gateway via IPC
+ *
+ * Usage:
+ *   roundhouse message "Hello from CLI"
+ *   roundhouse message --session main "Hello"
+ */
+
+import { sendIpc } from "../ipc";
+
+export async function cmdMessage(args: string[]): Promise<void> {
+  let session: string | undefined;
+  const positional: string[] = [];
+
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--session" && args[i + 1]) {
+      session = args[++i];
+    } else {
+      positional.push(args[i]);
+    }
+  }
+
+  const text = positional.join(" ").trim();
+  if (!text) {
+    console.error('Usage: roundhouse message [--session <name>] "<message>"');
+    process.exit(1);
+  }
+
+  try {
+    const response = await sendIpc({ type: "notify", text, session });
+    if (response.ok) {
+      console.log("✅ Message delivered to gateway");
+    } else {
+      console.error(`❌ ${response.error}`);
+      process.exit(1);
+    }
+  } catch (err: any) {
+    console.error(`❌ ${err.message}`);
+    process.exit(1);
+  }
+}

package/src/cron/runner.ts

@@ -6,8 +6,8 @@
  */
 
 import { getAgentFactory } from "../agents/registry";
-// TODO: route through TransportAdapter.notify() when multi-transport lands
 import { sendTelegramToMany } from "../transports/telegram/notify";
+import { sendIpc } from "../ipc";
 import { CronStore, generateRunId } from "./store";
 import { buildTemplateContext, renderTemplate } from "./template";
 import type { CronJobConfig, CronRunRecord } from "./types";
@@ -127,11 +127,6 @@ export class CronRunner {
   }
 
   private async notify(job: CronJobConfig, record: CronRunRecord): Promise<void> {
-    const tg = job.notify?.telegram;
-    if (!tg?.chatIds?.length) return;
-
-    if (!shouldNotify(tg.onlyOn, record.status)) return;
-
     const icon = runStatusIcon(record.status);
     const dur = `${(record.durationMs / 1000).toFixed(1)}s`;
     const header = `${icon} Cron: ${job.id}\nStatus: ${record.status} (${dur})`;
@@ -145,6 +140,20 @@ export class CronRunner {
       body = `${header}\nError: ${record.error.slice(0, NOTIFY_MAX_ERROR_CHARS)}`;
     }
 
-    await sendTelegramToMany(tg.chatIds, body);
+    // Route 1: Explicit Telegram chat IDs configured on the job
+    const tg = job.notify?.telegram;
+    if (tg?.chatIds?.length) {
+      if (!shouldNotify(tg.onlyOn, record.status)) return;
+      await sendTelegramToMany(tg.chatIds, body);
+      return;
+    }
+
+    // Route 2: Broadcast via IPC to all active transports (default)
+    try {
+      await sendIpc({ type: "notify", text: body });
+    } catch {
+      // Gateway not running or IPC unavailable — log and continue
+      console.warn(`[cron] ${job.id} IPC notify failed (gateway not running?)`);
+    }
   }
 }

package/src/cron/scheduler.ts

@@ -88,10 +88,19 @@ export class CronSchedulerService {
 
   async listJobs(): Promise<Array<{ job: CronJobConfig; state: CronJobState }>> {
     await this.reload();
-    return this.jobs.map((job) => ({
-      job,
-      state: this.states.get(job.id) ?? emptyState(job.id),
-    }));
+    return this.jobs
+      .filter((job) => {
+        // Hide completed one-shot jobs (already fired, won't run again)
+        if (job.schedule.type === "once") {
+          const state = this.states.get(job.id);
+          if (state && state.totalRuns > 0) return false;
+        }
+        return true;
+      })
+      .map((job) => ({
+        job,
+        state: this.states.get(job.id) ?? emptyState(job.id),
+      }));
   }
 
   async trigger(jobId: string): Promise<void> {

package/src/gateway/gateway.ts

@@ -13,6 +13,7 @@ import { SttService, enrichAttachmentsWithTranscripts, DEFAULT_STT_CONFIG } from
 import { runDoctor, formatDoctorTelegram, createDoctorContext } from "../cli/doctor/runner";
 import { ROUNDHOUSE_DIR, ROUNDHOUSE_VERSION } from "../config";
 import { CronSchedulerService } from "../cron/scheduler";
+import { IpcServer, type IpcRequest } from "../ipc";
 import { prepareMemoryForTurn, finalizeMemoryForTurn, flushMemoryThenCompact } from "../memory/lifecycle";
 import { maxPressure } from "../memory/policy";
 import type { PressureLevel } from "../memory/types";
@@ -82,6 +83,7 @@ export class Gateway {
   private pairingComplete = false;
   private sttService: SttService | null = null;
   private cronScheduler: CronSchedulerService | null = null;
+  private ipcServer: IpcServer | null = null;
 
   constructor(router: AgentRouter, config: GatewayConfig) {
     this.router = router;
@@ -330,6 +332,41 @@ export class Gateway {
       console.error("[roundhouse] cron scheduler start failed:", (err as Error).message);
     }
 
+    // Start IPC server for CLI → gateway communication
+    this.ipcServer = new IpcServer(async (req: IpcRequest) => {
+      if (req.type === "ping") return { ok: true };
+      if (req.type === "notify") {
+        const allChatIds = this.config.chat.notifyChatIds ?? [];
+        if (allChatIds.length === 0) return { ok: false, error: "No notifyChatIds configured" };
+
+        // Session routing:
+        //   "main" = first notifyChatId (primary user chat)
+        //   numeric string = that specific chat ID
+        //   anything else / undefined = broadcast to all notifyChatIds
+        let targetIds: number[];
+        if (req.session === "main") {
+          targetIds = [allChatIds[0]];
+        } else if (req.session && /^-?\d+$/.test(req.session)) {
+          targetIds = [Number(req.session)];
+        } else {
+          targetIds = allChatIds; // broadcast to all
+        }
+
+        try {
+          await this.transport.notify(targetIds, req.text);
+          return { ok: true };
+        } catch (e: any) {
+          return { ok: false, error: e.message };
+        }
+      }
+      return { ok: false, error: "Unknown request type" };
+    });
+    try {
+      await this.ipcServer.start();
+    } catch (err) {
+      console.error("[roundhouse] IPC server start failed:", (err as Error).message);
+    }
+
     // Send startup notification (after cron init so we can include job counts)
     await this.notifyStartup(platforms);
   }
@@ -746,6 +783,9 @@ export class Gateway {
   }
 
   async stop() {
+    if (this.ipcServer) {
+      this.ipcServer.stop();
+    }
     if (this.cronScheduler) {
       try { await this.cronScheduler.stop(); } catch (e) { console.warn("[roundhouse] cron stop error:", e); }
     }

package/src/gateway/tools.md

@@ -52,3 +52,117 @@ Users can also manage jobs via Telegram:
 - `/crons trigger <id>` — run now
 - `/crons pause <id>` — disable
 - `/crons resume <id>` — enable
+
+## roundhouse message
+
+Send a message to the user via all active transports (Telegram, etc.) without spawning an agent turn.
+
+**Usage:**
+```bash
+roundhouse message "Hello from the server!"
+roundhouse message --session main "Targeted to primary chat"
+```
+
+## Git & GitHub (gh CLI)
+
+Use `gh` CLI for all GitHub operations. It handles authentication automatically.
+
+**Common patterns:**
+```bash
+# Push branches
+git push origin <branch>
+
+# Create PRs
+gh pr create --base main --head <branch> --title "..." --body "..."
+
+# Merge PRs
+gh pr merge <number> --squash --admin
+
+# Check CI status
+gh pr checks <number>
+gh run list --limit 5
+
+# Create releases / tags
+git tag v1.2.3 && git push origin v1.2.3
+```
+
+**Prefer `gh` over raw git for:**
+- PR creation and merging
+- CI/workflow status checks
+- Release creation
+- Repository settings
+
+## mcporter (MCP Server CLI)
+
+Call tools from configured MCP servers (AWS APIs, docs, infrastructure).
+
+```bash
+mcporter list                          # show available servers
+mcporter list <server> --schema        # show tools + parameters
+mcporter call <server>.<tool> key=val   # call a tool
+```
+
+**Examples:**
+```bash
+mcporter call 'aws-mcp.sts_GetCallerIdentity()'
+mcporter call aws-mcp.s3_ListBuckets
+mcporter call 'aws-documentation.search(query: "Lambda timeout")'
+```
+
+> Ensure PATH includes `~/.local/bin` for `mcporter`/`uvx` discovery.
+
+## playwright-cli (Browser Automation)
+
+Headless browser automation for testing web UIs, scraping, screenshots.
+
+**Core workflow:** open → snapshot → interact → close
+
+```bash
+playwright-cli open "https://example.com"   # launch + navigate
+playwright-cli snapshot                      # accessibility tree with [ref=eN]
+playwright-cli click e5                      # click element by ref
+playwright-cli fill e3 "search query"        # type into input
+playwright-cli screenshot                    # save viewport PNG
+playwright-cli close                         # close browser
+```
+
+**Other commands:**
+```bash
+playwright-cli requests               # list network requests
+playwright-cli request <index>        # show request details
+playwright-cli cookie-list            # list cookies
+playwright-cli eval "document.title"   # run JS in page
+playwright-cli pdf                    # save page as PDF
+```
+
+**Use for:** E2E testing, visual verification, form automation, web scraping.
+**NOT for:** API-only testing (use curl), static file reading.
+
+## codex exec
+
+Delegate tasks to Codex CLI (architecture design, parallel research, code review).
+
+```bash
+codex exec "Design a retry mechanism with exponential backoff for this module"
+```
+
+Good for: brainstorming, getting a second opinion, architecture decisions, reducing bikeshedding.
+
+## Memory Management
+
+Durable state files the agent can read and update:
+
+- `~/MEMORY.md` — stable facts, preferences, project context (edit existing entries, don't append duplicates)
+- `~/daily/YYYY-MM-DD/front-page.md` — today's work log, decisions, open loops
+- `~/daily/YYYY-MM-DD/articles/` — detailed write-ups for durable topics
+
+## AWS CLI
+
+Full AWS access via instance role (us-east-1). No credentials needed.
+
+```bash
+aws sts get-caller-identity
+aws s3 ls
+aws logs tail /aws/lambda/<name> --since 1h
+aws cloudformation describe-stacks --stack-name <name>
+```

package/src/ipc/client.ts

@@ -0,0 +1,59 @@
+/**
+ * ipc/client.ts — CLI client to send messages to the running gateway
+ *
+ * Connects to ~/.roundhouse/gateway.sock, sends JSON, reads response, closes.
+ */
+
+import { createConnection } from "node:net";
+import { SOCKET_PATH } from "./server";
+import type { IpcRequest, IpcResponse } from "./types";
+
+/**
+ * Send a request to the running gateway via IPC.
+ * Returns the response, or throws if gateway is unreachable.
+ */
+export async function sendIpc(request: IpcRequest, opts?: { timeoutMs?: number; socketPath?: string }): Promise<IpcResponse> {
+  const { timeoutMs = 5000, socketPath = SOCKET_PATH } = opts ?? {};
+  return new Promise((resolve, reject) => {
+    const conn = createConnection(socketPath);
+    let data = "";
+    let done = false;
+    let timer: ReturnType<typeof setTimeout>;
+
+    const finish = (result: IpcResponse | Error) => {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      conn.destroy();
+      if (result instanceof Error) reject(result);
+      else resolve(result);
+    };
+
+    conn.on("connect", () => {
+      conn.write(JSON.stringify(request) + "\n");
+    });
+
+    conn.on("data", (chunk) => {
+      data += chunk.toString();
+      const newlineIdx = data.indexOf("\n");
+      if (newlineIdx === -1) return;
+      try {
+        finish(JSON.parse(data.slice(0, newlineIdx)));
+      } catch {
+        finish(new Error("Invalid response from gateway"));
+      }
+    });
+
+    conn.on("error", (err: NodeJS.ErrnoException) => {
+      if (err.code === "ENOENT" || err.code === "ECONNREFUSED") {
+        finish(new Error("Gateway is not running. Start with: roundhouse start"));
+      } else {
+        finish(err);
+      }
+    });
+
+    conn.on("close", () => finish(new Error("Connection closed without response")));
+
+    timer = setTimeout(() => finish(new Error("IPC timeout")), timeoutMs);
+  });
+}

package/src/ipc/index.ts

@@ -0,0 +1,3 @@
+export { IpcServer, SOCKET_PATH } from "./server";
+export { sendIpc } from "./client";
+export type { IpcRequest, IpcResponse } from "./types";

package/src/ipc/server.ts

@@ -0,0 +1,102 @@
+/**
+ * ipc/server.ts — Unix socket server for gateway IPC
+ *
+ * Listens on ~/.roundhouse/gateway.sock.
+ * Protocol: newline-delimited JSON (one request, one response, close).
+ */
+
+import { createServer, type Server } from "node:net";
+import { unlinkSync, chmodSync, existsSync } from "node:fs";
+import { ROUNDHOUSE_DIR } from "../config";
+import { resolve } from "node:path";
+import type { IpcRequest, IpcResponse } from "./types";
+
+export const SOCKET_PATH = resolve(ROUNDHOUSE_DIR, "gateway.sock");
+
+export type IpcHandler = (request: IpcRequest) => Promise<IpcResponse>;
+
+export class IpcServer {
+  private server: Server | null = null;
+  private socketPath: string;
+
+  constructor(private handler: IpcHandler, socketPath?: string) {
+    this.socketPath = socketPath ?? SOCKET_PATH;
+  }
+
+  getSocketPath(): string { return this.socketPath; }
+
+  async start(): Promise<void> {
+    // Remove stale socket if present (TOCTOU race acknowledged — no fix without flock)
+    if (existsSync(this.socketPath)) {
+      const { createConnection } = await import("node:net");
+      const alive = await new Promise<boolean>((res) => {
+        const conn = createConnection(this.socketPath);
+        const timer = setTimeout(() => { conn.destroy(); res(false); }, 500);
+        conn.on("connect", () => { clearTimeout(timer); conn.end(); res(true); });
+        conn.on("error", () => { clearTimeout(timer); res(false); });
+      });
+      if (alive) {
+        throw new Error("Another gateway is already running (socket in use)");
+      }
+      try { unlinkSync(this.socketPath); } catch {}
+    }
+
+    this.server = createServer((conn) => {
+      let data = "";
+      let handled = false;
+      const MAX_BYTES = 64 * 1024; // 64KB
+
+      conn.on("data", (chunk) => {
+        if (handled) return;
+        data += chunk.toString();
+        if (data.length > MAX_BYTES) {
+          conn.destroy();
+          return;
+        }
+        const newlineIdx = data.indexOf("\n");
+        if (newlineIdx === -1) return;
+
+        handled = true;
+        const line = data.slice(0, newlineIdx);
+
+        let request: IpcRequest;
+        try {
+          request = JSON.parse(line);
+        } catch {
+          conn.end(JSON.stringify({ ok: false, error: "Invalid JSON" }) + "\n");
+          return;
+        }
+
+        this.handler(request).then((response) => {
+          conn.end(JSON.stringify(response) + "\n");
+        }).catch((err) => {
+          conn.end(JSON.stringify({ ok: false, error: err.message }) + "\n");
+        });
+      });
+
+      // Timeout connections that send nothing
+      conn.setTimeout(5000, () => conn.destroy());
+    });
+
+    await new Promise<void>((resolve, reject) => {
+      const onError = (err: Error) => reject(err);
+      this.server!.on("error", onError);
+      this.server!.listen(this.socketPath, () => {
+        this.server!.removeListener("error", onError);
+        this.server!.on("error", (e) => console.error("[roundhouse] IPC server error:", e.message));
+        // Restrict permissions: owner only
+        chmodSync(this.socketPath, 0o600);
+        console.log(`[roundhouse] IPC listening on ${this.socketPath}`);
+        resolve();
+      });
+    });
+  }
+
+  stop(): void {
+    if (this.server) {
+      this.server.close();
+      this.server = null;
+    }
+    try { unlinkSync(this.socketPath); } catch {}
+  }
+}

package/src/ipc/types.ts

@@ -0,0 +1,13 @@
+/**
+ * ipc/types.ts — Shared types for the IPC protocol
+ */
+
+/** Messages the CLI can send to the gateway */
+export type IpcRequest =
+  | { type: "notify"; text: string; session?: string }
+  | { type: "ping" };
+
+/** Responses the gateway sends back */
+export type IpcResponse =
+  | { ok: true }
+  | { ok: false; error: string };

package/src/provisioning/bundle.ts

@@ -226,6 +226,7 @@ export function provisionBundle(opts: ProvisionOpts = {}): void {
   provisionMcporterConfig(opts);
   provisionExtensionFiles(opts);
   provisionExtensions(opts);
+  provisionWorkspaceFiles(opts);
 }
 
 /**
@@ -306,3 +307,33 @@ export function provisionExtensions(opts: ProvisionOpts = {}): void {
     log.warn(`extensions provisioning failed: ${err.message}`);
   }
 }
+
+/**
+ * Copy workspace files (tools.md, etc.) to ~/.roundhouse/ if not already present.
+ * Never overwrites — user's customized version always wins.
+ */
+export function provisionWorkspaceFiles(opts: ProvisionOpts = {}): void {
+  const { force = false, log = consoleLog } = opts;
+  const roundhouseDir = resolve(homedir(), ".roundhouse");
+  const bundledDir = resolve(dirname(fileURLToPath(import.meta.url)), "..", "gateway");
+
+  // Files to provision: [bundled filename, target filename]
+  const files: [string, string][] = [
+    ["tools.md", "tools.md"],
+  ];
+
+  try {
+    mkdirSync(roundhouseDir, { recursive: true });
+
+    for (const [src, dest] of files) {
+      const srcPath = resolve(bundledDir, src);
+      const destPath = resolve(roundhouseDir, dest);
+      if (!existsSync(srcPath)) continue;
+      if (existsSync(destPath) && !force) continue; // never overwrite unless forced
+      copyFileSync(srcPath, destPath);
+      log.ok(`${dest} provisioned to ~/.roundhouse/`);
+    }
+  } catch (err: any) {
+    log.warn(`workspace files provisioning failed: ${err.message}`);
+  }
+}