@inceptionstack/roundhouse 0.2.2 → 0.3.1

package/src/memory/prompts.ts

@@ -0,0 +1,42 @@
+/**
+ * memory/prompts.ts — Memory flush prompts for maintenance turns
+ */
+
+import type { MemoryMode } from "./types";
+
+/**
+ * Build a memory flush prompt based on mode and urgency.
+ */
+export function buildFlushPrompt(mode: MemoryMode, level: "soft" | "hard" | "emergency"): string {
+  const urgency = level === "emergency"
+    ? "URGENT: Context is nearly full. "
+    : level === "hard"
+      ? "Context is filling up. "
+      : "";
+
+  if (mode === "complement") {
+    // Agent has its own memory extension — only ask for narrative context
+    return [
+      `Roundhouse maintenance: ${urgency}Before context compaction, save important narrative context:`,
+      ``,
+      `- Project decisions, architecture choices, investigation status → ~/MEMORY.md`,
+      `- Today's notable events, open loops, task progress → today's daily note`,
+      ``,
+      `Do NOT save individual preferences or corrections — your memory extension handles those automatically.`,
+      `Only write facts worth preserving. Do not summarize the whole conversation.`,
+      `When done, reply with a one-line confirmation of what you saved.`,
+    ].join("\n");
+  }
+
+  // Full mode — agent has no memory extension, save everything
+  return [
+    `Roundhouse maintenance: ${urgency}Before context compaction, update your durable memory files:`,
+    ``,
+    `- User preferences, project conventions, stable facts → ~/MEMORY.md`,
+    `- Today's notable events, decisions, open loops → today's daily note`,
+    `- Corrections or lessons learned → ~/MEMORY.md`,
+    ``,
+    `Only write facts worth preserving. Do not summarize the whole conversation.`,
+    `When done, reply with a one-line confirmation of what you saved.`,
+  ].join("\n");
+}

package/src/memory/state.ts

@@ -0,0 +1,43 @@
+/**
+ * memory/state.ts — Per-thread memory state persistence
+ *
+ * State lives in ~/.roundhouse/memory-state/<thread-dir>.json
+ * Outside the agent workspace so the agent can't accidentally corrupt it.
+ */
+
+import { readFile, writeFile, mkdir, rename, unlink } from "node:fs/promises";
+import { resolve, dirname } from "node:path";
+import { randomBytes } from "node:crypto";
+import { ROUNDHOUSE_DIR } from "../config";
+import { threadIdToDir } from "../util";
+import type { ThreadMemoryState } from "./types";
+
+const STATE_DIR = resolve(ROUNDHOUSE_DIR, "memory-state");
+
+function stateFilePath(threadId: string): string {
+  return resolve(STATE_DIR, `${threadIdToDir(threadId)}.json`);
+}
+
+/** Load per-thread memory state (returns empty state if none exists) */
+export async function loadThreadMemoryState(threadId: string): Promise<ThreadMemoryState> {
+  try {
+    const raw = await readFile(stateFilePath(threadId), "utf8");
+    return JSON.parse(raw) as ThreadMemoryState;
+  } catch {
+    return {};
+  }
+}
+
+/** Save per-thread memory state (atomic write to prevent corruption) */
+export async function saveThreadMemoryState(threadId: string, state: ThreadMemoryState): Promise<void> {
+  const path = stateFilePath(threadId);
+  await mkdir(dirname(path), { recursive: true });
+  const tmp = `${path}.tmp.${randomBytes(4).toString("hex")}`;
+  try {
+    await writeFile(tmp, JSON.stringify(state, null, 2) + "\n");
+    await rename(tmp, path);
+  } catch (err) {
+    try { await unlink(tmp); } catch {}
+    throw err;
+  }
+}

package/src/memory/types.ts

@@ -0,0 +1,90 @@
+/**
+ * memory/types.ts — Memory system types
+ */
+
+/** Memory operating mode */
+export type MemoryMode = "full" | "complement" | "unknown";
+
+/** Memory configuration (in gateway.config.json) */
+export interface MemoryConfig {
+  /** Enable memory system (default: true) */
+  enabled?: boolean;
+  /** Root directory for memory files (default: agent cwd) */
+  rootDir?: string;
+  /** Main durable memory file (default: "MEMORY.md") */
+  mainFile?: string;
+  /** Daily notes directory (default: "daily") */
+  dailyDir?: string;
+  /** Injection settings */
+  inject?: {
+    /** Include today's daily note (default: true) */
+    includeToday?: boolean;
+    /** Number of recent days to include (default: 1 = yesterday) */
+    includeRecentDays?: number;
+    /** Max bytes to inject (default: 48000) */
+    maxBytes?: number;
+  };
+  /** Compaction settings (active in BOTH modes) */
+  compact?: {
+    /** Enable proactive compaction (default: true) */
+    enabled?: boolean;
+    /** Soft flush threshold: percent of context (default: 0.45) */
+    softPercent?: number;
+    /** Soft flush threshold: absolute tokens (default: 180000) */
+    softTokens?: number;
+    /** Hard compact threshold: percent (default: 0.50) */
+    hardPercent?: number;
+    /** Hard compact threshold: absolute tokens (default: 200000) */
+    hardTokens?: number;
+    /** Emergency: compact when remaining tokens < this (default: 32768) */
+    emergencyThresholdTokens?: number;
+    /** Min time between soft flushes in ms (default: 600000 = 10min) */
+    cooldownMs?: number;
+  };
+}
+
+/** Per-thread memory tracking state */
+export interface ThreadMemoryState {
+  /** Hash of memory files when last injected into this thread */
+  lastInjectedDigest?: string;
+  /** Hash of memory files after last agent turn (may differ if agent wrote memory) */
+  lastKnownDigest?: string;
+  /** When memory was last injected */
+  lastInjectedAt?: string;
+  /** Local date when memory was last injected (detects day boundary) */
+  lastSeenLocalDate?: string;
+  /** Force re-injection on next turn */
+  forceInjectReason?: "new-session" | "after-compact" | "manual";
+  /** When last compaction happened */
+  lastCompactAt?: string;
+  /** Pending compaction level (from interrupted flush) */
+  pendingCompact?: "soft" | "hard" | "emergency";
+  /** When last soft flush happened (for cooldown) */
+  lastSoftFlushAt?: string;
+}
+
+/** Resolved memory file set to inject */
+export interface MemoryFileSet {
+  files: Array<{ label: string; path: string }>;
+}
+
+/** Snapshot of memory file contents */
+export interface MemorySnapshot {
+  entries: Array<{ label: string; content: string }>;
+  digest: string;
+}
+
+/** Context pressure classification */
+export type PressureLevel = "none" | "soft" | "hard" | "emergency";
+
+/** Result of preparing memory for a turn */
+export interface PreparedTurn {
+  /** Message to send (may have memory prepended) */
+  message: import("../types").AgentMessage;
+  /** Digest before the turn (for finalize) */
+  beforeDigest: string | null;
+  /** Whether memory was injected */
+  injected: boolean;
+  /** Pending compact level from a previously interrupted flush */
+  pendingCompact?: "soft" | "hard" | "emergency";
+}

package/src/notify/telegram.ts

@@ -0,0 +1,48 @@
+/**
+ * notify/telegram.ts — Shared Telegram Bot API sender
+ *
+ * Used by gateway startup notifications, cron notifications, etc.
+ */
+
+const DEFAULT_TIMEOUT = 15_000;
+
+/** Send a text message via Telegram Bot API */
+export async function sendTelegramMessage(
+  chatId: string | number,
+  text: string,
+  options?: { parseMode?: string; timeout?: number },
+): Promise<boolean> {
+  const token = process.env.TELEGRAM_BOT_TOKEN;
+  if (!token) return false;
+
+  try {
+    const body: Record<string, unknown> = { chat_id: chatId, text };
+    if (options?.parseMode) body.parse_mode = options.parseMode;
+
+    const res = await fetch(`https://api.telegram.org/bot${token}/sendMessage`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(options?.timeout ?? DEFAULT_TIMEOUT),
+    });
+    if (!res.ok) {
+      const errBody = await res.text().catch(() => "");
+      console.warn(`[telegram] sendMessage to ${chatId} failed (${res.status}): ${errBody.slice(0, 200)}`);
+    }
+    return res.ok;
+  } catch (err) {
+    console.warn(`[telegram] sendMessage to ${chatId} failed:`, (err as Error).message);
+    return false;
+  }
+}
+
+/** Send a message to multiple chat IDs */
+export async function sendTelegramToMany(
+  chatIds: (string | number)[],
+  text: string,
+  options?: { parseMode?: string },
+): Promise<void> {
+  for (const chatId of chatIds) {
+    await sendTelegramMessage(chatId, text, options);
+  }
+}

package/src/types.ts

@@ -2,14 +2,73 @@
  * types.ts — Core abstractions for roundhouse
  */
 
+// ── Attachments ──────────────────────────────────────
+
+/** A file attachment received from a chat platform and saved locally */
+export interface MessageAttachment {
+  /** Stable attachment ID (e.g. "att_a1b2c3d4") */
+  id: string;
+  /** Attachment type from the chat platform */
+  mediaType: "audio" | "image" | "file" | "video";
+  /** Sanitized filename */
+  name: string;
+  /** Absolute local path where the file was saved */
+  localPath: string;
+  /** MIME type (from platform metadata or fallback) */
+  mime: string;
+  /** File size in bytes */
+  sizeBytes: number;
+  /** Whether this is user-provided (untrusted) content */
+  untrusted: true;
+  /** Transcript of audio content (populated by STT service) */
+  transcript?: import("./voice/types").AttachmentTranscript;
+}
+
 // ── Agent adapter ────────────────────────────────────
 
+/** A user message with optional attachments */
+export interface AgentMessage {
+  /** User's text (may be empty for attachment-only messages) */
+  text: string;
+  /** File attachments saved locally by the gateway */
+  attachments?: MessageAttachment[];
+}
+
+/** Events yielded by the streaming prompt interface */
+export type AgentStreamEvent =
+  | { type: "text_delta"; text: string }
+  | { type: "tool_start"; toolName: string; toolCallId: string }
+  | { type: "tool_end"; toolName: string; toolCallId: string; isError: boolean }
+  | { type: "turn_end" }
+  | { type: "draining" }
+  | { type: "drain_complete" }
+  | { type: "agent_end" }
+  | { type: "custom_message"; customType: string; content: string };
+
 export interface AgentAdapter {
   /** Unique agent name, e.g. "pi", "kiro" */
   name: string;
 
   /** Send a user message and return the full assistant response */
-  prompt(threadId: string, text: string): Promise<AgentResponse>;
+  prompt(threadId: string, message: AgentMessage): Promise<AgentResponse>;
+
+  /**
+   * Send a user message and stream back events in real time.
+   * Falls back to prompt() if not implemented.
+   */
+  promptStream?(threadId: string, message: AgentMessage): AsyncIterable<AgentStreamEvent>;
+
+  /** Dispose the session for a thread and start fresh on next prompt */
+  restart?(threadId: string): Promise<void>;
+
+  /** Compact the session context for a thread */
+  compact?(threadId: string): Promise<{ tokensBefore: number; tokensAfter: number | null } | null>;
+
+  /** Abort the current agent run for a thread */
+  abort?(threadId: string): Promise<void>;
+
+  /** Return runtime info about the agent (model, version, etc.) */
+  getInfo?(threadId?: string): Record<string, unknown>;
 
   /** Tear down all sessions */
   dispose(): Promise<void>;
@@ -46,6 +105,10 @@ export interface GatewayConfig {
   chat: {
     botUsername: string;
     allowedUsers?: string[];
+    /** Immutable Telegram user IDs (paired during setup) */
+    allowedUserIds?: number[];
+    /** Telegram chat IDs to notify on startup */
+    notifyChatIds?: number[];
     adapters: {
       telegram?: Record<string, unknown>;
       slack?: Record<string, unknown>;
@@ -53,4 +116,8 @@ export interface GatewayConfig {
       [key: string]: Record<string, unknown> | undefined;
     };
   };
+  voice?: {
+    stt?: import("./voice/types").SttConfig;
+  };
+  memory?: import("./memory/types").MemoryConfig;
 }

package/src/util.ts

@@ -2,6 +2,16 @@
  * util.ts — Pure utility functions for roundhouse
  */
 
+import { randomBytes } from "node:crypto";
+
+/**
+ * Debug flag for per-event stream logging. Enabled via
+ * ROUNDHOUSE_DEBUG_STREAM=1 in the roundhouse env file. Evaluated once at
+ * module load so the hot path (subscription callbacks, event loops) is a
+ * single boolean check rather than an env read on every event.
+ */
+export const DEBUG_STREAM = process.env.ROUNDHOUSE_DEBUG_STREAM === "1";
+
 /**
  * Split a long message into chunks that fit within maxLen.
  * Prefers splitting at newline boundaries.
@@ -36,10 +46,19 @@ export function splitMessage(text: string, maxLen: number): string[] {
  */
 export function isAllowed(
   message: { author?: { userName?: string; userId?: string; fullName?: string } },
-  allowedUsers: string[]
+  allowedUsers: string[],
+  allowedUserIds?: number[],
 ): boolean {
-  if (allowedUsers.length === 0) return true;
+  if (allowedUsers.length === 0 && (!allowedUserIds || allowedUserIds.length === 0)) return true;
   const author = message.author ?? {};
+
+  // Check immutable numeric user ID first
+  if (allowedUserIds?.length && author.userId) {
+    const numericId = parseInt(author.userId, 10);
+    if (!isNaN(numericId) && allowedUserIds.includes(numericId)) return true;
+  }
+
+  // Fall back to username check
   const candidates = [author.userName, author.userId]
     .filter(Boolean)
     .map((s) => String(s).toLowerCase());
@@ -85,3 +104,10 @@ export function threadIdToDir(threadId: string): string {
     .replace(/:/g, "_c")    // encode colons
     .replace(/[^a-zA-Z0-9_-]/g, "_x"); // encode everything else
 }
+
+/**
+ * Generate a short random attachment ID (e.g. "att_a1b2c3d4").
+ */
+export function generateAttachmentId(): string {
+  return `att_${randomBytes(4).toString("hex")}`;
+}