zubo 0.1.0

package/src/util/logger.ts

@@ -0,0 +1,73 @@
+import { appendFileSync, existsSync, mkdirSync } from "fs";
+import { dirname } from "path";
+import { paths } from "../config/paths";
+
+type LogLevel = "debug" | "info" | "warn" | "error";
+
+const LEVELS: Record<LogLevel, number> = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+};
+
+let currentLevel: LogLevel = "info";
+let fileLogging = false;
+
+export function setLogLevel(level: LogLevel) {
+  currentLevel = level;
+}
+
+export function enableFileLogging() {
+  const dir = dirname(paths.logFile);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  fileLogging = true;
+}
+
+const SENSITIVE_KEYS = ["value", "secret", "password", "token", "key", "credential", "apikey", "api_key", "input"];
+
+function sanitizeLogData(data: Record<string, unknown>): Record<string, unknown> {
+  const sanitized: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(data)) {
+    const lower = k.toLowerCase();
+    if (SENSITIVE_KEYS.some((s) => lower.includes(s)) && typeof v === "string" && v.length > 20) {
+      sanitized[k] = v.slice(0, 8) + "…[REDACTED]";
+    } else if (typeof v === "object" && v !== null && !Array.isArray(v)) {
+      sanitized[k] = sanitizeLogData(v as Record<string, unknown>);
+    } else {
+      sanitized[k] = v;
+    }
+  }
+  return sanitized;
+}
+
+function log(level: LogLevel, msg: string, data?: Record<string, unknown>) {
+  if (LEVELS[level] < LEVELS[currentLevel]) return;
+  const ts = new Date().toISOString();
+  const prefix = `[${ts}] [${level.toUpperCase()}]`;
+  const safeData = data ? sanitizeLogData(data) : undefined;
+  const line = safeData
+    ? `${prefix} ${msg} ${JSON.stringify(safeData)}`
+    : `${prefix} ${msg}`;
+
+  console.log(line);
+
+  if (fileLogging) {
+    try {
+      appendFileSync(paths.logFile, line + "\n");
+    } catch {
+      // don't crash if log write fails
+    }
+  }
+}
+
+export const logger = {
+  debug: (msg: string, data?: Record<string, unknown>) =>
+    log("debug", msg, data),
+  info: (msg: string, data?: Record<string, unknown>) =>
+    log("info", msg, data),
+  warn: (msg: string, data?: Record<string, unknown>) =>
+    log("warn", msg, data),
+  error: (msg: string, data?: Record<string, unknown>) =>
+    log("error", msg, data),
+};

package/src/util/perf-collector.ts

@@ -0,0 +1,35 @@
+import { statSync } from "fs";
+import { onHeartbeat } from "../scheduler/heartbeat";
+import { getDb } from "../db/connection";
+import { paths } from "../config/paths";
+import { logger } from "./logger";
+
+/**
+ * Register a heartbeat handler that records performance snapshots.
+ */
+export function initPerfCollector(): void {
+  onHeartbeat(async () => {
+    try {
+      const db = getDb();
+      const memUsage = process.memoryUsage();
+      const rssMb = Math.round((memUsage.rss / 1_048_576) * 100) / 100;
+      const heapMb = Math.round((memUsage.heapUsed / 1_048_576) * 100) / 100;
+
+      let dbSizeMb = 0;
+      try {
+        const stat = statSync(paths.db);
+        dbSizeMb = Math.round((stat.size / 1_048_576) * 100) / 100;
+      } catch (err: any) {
+        logger.warn("Failed to stat database file for perf snapshot", { error: (err as Error).message });
+      }
+
+      db.prepare(
+        "INSERT INTO perf_snapshots (rss_mb, heap_mb, db_size_mb) VALUES (?, ?, ?)"
+      ).run(rssMb, heapMb, dbSizeMb);
+    } catch (err: any) {
+      logger.debug("Perf snapshot failed", { error: err.message });
+    }
+  });
+
+  logger.info("Performance collector initialized");
+}

package/src/util/rate-limiter.ts

@@ -0,0 +1,70 @@
+/**
+ * Sliding-window rate limiter with per-key tracking.
+ * Used for HTTP endpoints (per-IP) and channels (per-userId).
+ */
+export class RateLimiter {
+  private static readonly MAX_KEYS = 10_000;
+  private windows = new Map<string, number[]>();
+  private maxRequests: number;
+  private windowMs: number;
+  private pruneTimer: ReturnType<typeof setInterval>;
+
+  constructor(maxRequests: number, windowMs: number) {
+    this.maxRequests = maxRequests;
+    this.windowMs = windowMs;
+
+    // Auto-prune expired entries every 60s
+    this.pruneTimer = setInterval(() => this.prune(), 60_000);
+    // Allow process to exit without waiting for timer
+    if (this.pruneTimer.unref) this.pruneTimer.unref();
+  }
+
+  check(key: string): { allowed: boolean; retryAfterMs?: number } {
+    const now = Date.now();
+    const cutoff = now - this.windowMs;
+
+    // Evict oldest entry if map is at capacity and this is a new key
+    if (this.windows.size >= RateLimiter.MAX_KEYS && !this.windows.has(key)) {
+      const firstKey = this.windows.keys().next().value;
+      if (firstKey !== undefined) this.windows.delete(firstKey);
+    }
+
+    let timestamps = this.windows.get(key);
+    if (!timestamps) {
+      timestamps = [];
+      this.windows.set(key, timestamps);
+    }
+
+    // Remove expired timestamps
+    while (timestamps.length > 0 && timestamps[0] <= cutoff) {
+      timestamps.shift();
+    }
+
+    if (timestamps.length >= this.maxRequests) {
+      const oldestValid = timestamps[0];
+      const retryAfterMs = oldestValid + this.windowMs - now;
+      return { allowed: false, retryAfterMs: Math.max(retryAfterMs, 1) };
+    }
+
+    timestamps.push(now);
+    return { allowed: true };
+  }
+
+  private prune(): void {
+    const now = Date.now();
+    const cutoff = now - this.windowMs;
+    for (const [key, timestamps] of this.windows) {
+      while (timestamps.length > 0 && timestamps[0] <= cutoff) {
+        timestamps.shift();
+      }
+      if (timestamps.length === 0) {
+        this.windows.delete(key);
+      }
+    }
+  }
+
+  destroy(): void {
+    clearInterval(this.pruneTimer);
+    this.windows.clear();
+  }
+}

package/src/util/tokens.ts

@@ -0,0 +1,17 @@
+/**
+ * Rough token count estimation.
+ * ~4 chars per token for English text (GPT/Claude approximation).
+ */
+export function estimateTokens(text: string): number {
+  return Math.ceil(text.length / 4);
+}
+
+export function estimateMessagesTokens(
+  messages: Array<{ role: string; content: string }>
+): number {
+  let total = 0;
+  for (const msg of messages) {
+    total += estimateTokens(msg.content) + 4; // overhead per message
+  }
+  return total;
+}

package/src/voice/stt.ts

@@ -0,0 +1,57 @@
+import { logger } from "../util/logger";
+
+export interface SttProvider {
+  transcribe(audioBuffer: Buffer, format?: string): Promise<string>;
+}
+
+export class WhisperApiProvider implements SttProvider {
+  private apiKey: string;
+  private model: string;
+
+  constructor(apiKey: string, model: string = "whisper-1") {
+    this.apiKey = apiKey;
+    this.model = model;
+  }
+
+  async transcribe(audioBuffer: Buffer, format: string = "webm"): Promise<string> {
+    const formData = new FormData();
+    const blob = new Blob([new Uint8Array(audioBuffer)], { type: `audio/${format}` });
+    formData.append("file", blob, `audio.${format}`);
+    formData.append("model", this.model);
+
+    const res = await fetch("https://api.openai.com/v1/audio/transcriptions", {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${this.apiKey}`,
+      },
+      body: formData,
+    });
+
+    if (!res.ok) {
+      const text = await res.text();
+      throw new Error(`Whisper API error ${res.status}: ${text}`);
+    }
+
+    const data = (await res.json()) as { text: string };
+    logger.debug("STT transcription", { length: data.text.length });
+    return data.text;
+  }
+}
+
+let sttProvider: SttProvider | null = null;
+
+export function initStt(config: { provider: string; apiKey: string; model?: string }): void {
+  switch (config.provider) {
+    case "whisper":
+    case "openai":
+      sttProvider = new WhisperApiProvider(config.apiKey, config.model);
+      logger.info("STT initialized: Whisper API");
+      break;
+    default:
+      logger.warn(`Unknown STT provider: ${config.provider}`);
+  }
+}
+
+export function getSttProvider(): SttProvider | null {
+  return sttProvider;
+}

package/src/voice/tts.ts

@@ -0,0 +1,103 @@
+import { logger } from "../util/logger";
+
+export interface TtsProvider {
+  synthesize(text: string): Promise<Buffer>;
+  format: string;
+}
+
+export class OpenAiTtsProvider implements TtsProvider {
+  private apiKey: string;
+  private model: string;
+  private voice: string;
+  format = "mp3";
+
+  constructor(apiKey: string, voice: string = "alloy", model: string = "tts-1") {
+    this.apiKey = apiKey;
+    this.voice = voice;
+    this.model = model;
+  }
+
+  async synthesize(text: string): Promise<Buffer> {
+    const res = await fetch("https://api.openai.com/v1/audio/speech", {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${this.apiKey}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        model: this.model,
+        input: text,
+        voice: this.voice,
+        response_format: "mp3",
+      }),
+    });
+
+    if (!res.ok) {
+      const errText = await res.text();
+      throw new Error(`OpenAI TTS error ${res.status}: ${errText}`);
+    }
+
+    const arrayBuffer = await res.arrayBuffer();
+    logger.debug("TTS synthesis complete", { bytes: arrayBuffer.byteLength });
+    return Buffer.from(arrayBuffer);
+  }
+}
+
+export class ElevenLabsTtsProvider implements TtsProvider {
+  private apiKey: string;
+  private voice: string;
+  format = "mp3";
+
+  constructor(apiKey: string, voice: string = "21m00Tcm4TlvDq8ikWAM") {
+    this.apiKey = apiKey;
+    this.voice = voice;
+  }
+
+  async synthesize(text: string): Promise<Buffer> {
+    const res = await fetch(
+      `https://api.elevenlabs.io/v1/text-to-speech/${this.voice}`,
+      {
+        method: "POST",
+        headers: {
+          "xi-api-key": this.apiKey,
+          "Content-Type": "application/json",
+          Accept: "audio/mpeg",
+        },
+        body: JSON.stringify({
+          text,
+          model_id: "eleven_monolingual_v1",
+        }),
+      }
+    );
+
+    if (!res.ok) {
+      const errText = await res.text();
+      throw new Error(`ElevenLabs TTS error ${res.status}: ${errText}`);
+    }
+
+    const arrayBuffer = await res.arrayBuffer();
+    logger.debug("ElevenLabs TTS complete", { bytes: arrayBuffer.byteLength });
+    return Buffer.from(arrayBuffer);
+  }
+}
+
+let ttsProvider: TtsProvider | null = null;
+
+export function initTts(config: { provider: string; apiKey: string; voice?: string }): void {
+  switch (config.provider) {
+    case "openai":
+      ttsProvider = new OpenAiTtsProvider(config.apiKey, config.voice);
+      logger.info("TTS initialized: OpenAI");
+      break;
+    case "elevenlabs":
+      ttsProvider = new ElevenLabsTtsProvider(config.apiKey, config.voice);
+      logger.info("TTS initialized: ElevenLabs");
+      break;
+    default:
+      logger.warn(`Unknown TTS provider: ${config.provider}`);
+  }
+}
+
+export function getTtsProvider(): TtsProvider | null {
+  return ttsProvider;
+}

package/tests/agent/session.test.ts

@@ -0,0 +1,109 @@
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import { mkdtempSync, rmSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+
+// Override paths.sessions before importing session module
+import { paths } from "../../src/config/paths";
+
+let tempDir: string;
+
+// Patch the sessions path to a temp directory before each test
+beforeEach(() => {
+  tempDir = mkdtempSync(join(tmpdir(), "orba-session-test-"));
+  (paths as any).sessions = tempDir;
+});
+
+afterEach(() => {
+  rmSync(tempDir, { recursive: true, force: true });
+});
+
+// Import after paths is available (the module reads paths at call time, not import time)
+import { appendMessage, loadSession, sessionExists } from "../../src/agent/session";
+import type { SessionMessage } from "../../src/agent/session";
+
+describe("session management", () => {
+  test("appendMessage creates a session file and appends a message", () => {
+    const msg: SessionMessage = {
+      role: "user",
+      content: "Hello",
+      timestamp: new Date().toISOString(),
+    };
+
+    appendMessage("test-session", msg);
+    expect(sessionExists("test-session")).toBe(true);
+  });
+
+  test("loadSession returns messages in order", () => {
+    const messages: SessionMessage[] = [
+      { role: "user", content: "First", timestamp: "2025-01-01T00:00:00Z" },
+      { role: "assistant", content: "Second", timestamp: "2025-01-01T00:00:01Z" },
+      { role: "user", content: "Third", timestamp: "2025-01-01T00:00:02Z" },
+    ];
+
+    for (const msg of messages) {
+      appendMessage("ordered-session", msg);
+    }
+
+    const loaded = loadSession("ordered-session");
+    expect(loaded).toHaveLength(3);
+    expect(loaded[0].content).toBe("First");
+    expect(loaded[1].content).toBe("Second");
+    expect(loaded[2].content).toBe("Third");
+  });
+
+  test("loadSession respects the limit parameter", () => {
+    for (let i = 0; i < 10; i++) {
+      appendMessage("limited-session", {
+        role: "user",
+        content: `Message ${i}`,
+        timestamp: new Date().toISOString(),
+      });
+    }
+
+    const loaded = loadSession("limited-session", 3);
+    expect(loaded).toHaveLength(3);
+    // Should return the last 3 messages
+    expect(loaded[0].content).toBe("Message 7");
+    expect(loaded[1].content).toBe("Message 8");
+    expect(loaded[2].content).toBe("Message 9");
+  });
+
+  test("loadSession returns empty array for nonexistent session", () => {
+    const loaded = loadSession("does-not-exist");
+    expect(loaded).toEqual([]);
+  });
+
+  test("session ID validation rejects path traversal attempts", () => {
+    expect(() => {
+      appendMessage("../../etc/passwd", {
+        role: "user",
+        content: "malicious",
+        timestamp: new Date().toISOString(),
+      });
+    }).toThrow("Invalid session ID");
+  });
+
+  test("session ID validation rejects slashes", () => {
+    expect(() => {
+      appendMessage("foo/bar", {
+        role: "user",
+        content: "malicious",
+        timestamp: new Date().toISOString(),
+      });
+    }).toThrow("Invalid session ID");
+  });
+
+  test("session ID allows colons for channel:userId format", () => {
+    const msg: SessionMessage = {
+      role: "user",
+      content: "Hello from channel",
+      timestamp: new Date().toISOString(),
+    };
+
+    appendMessage("discord:user123", msg);
+    const loaded = loadSession("discord:user123");
+    expect(loaded).toHaveLength(1);
+    expect(loaded[0].content).toBe("Hello from channel");
+  });
+});

package/tests/agent-loop.test.ts

@@ -0,0 +1,54 @@
+import { describe, it, expect, beforeEach, afterEach, mock } from "bun:test";
+import { createMockLlm, textResponse, toolCallResponse } from "./helpers/mock-llm";
+import { createTestDb } from "./helpers/test-db";
+
+// We need to mock the DB and session before importing the agent loop
+// Since Bun's module system caches imports, we test the logic indirectly
+
+describe("Agent Loop", () => {
+  it("should return text response when LLM returns text", async () => {
+    const llm = createMockLlm([textResponse("Hello, world!")]);
+    const response = await llm.chat({ system: "test", messages: [{ role: "user", content: "Hi" }] });
+    expect(response.content[0].type).toBe("text");
+    expect(response.content[0].text).toBe("Hello, world!");
+    expect(response.stopReason).toBe("end_turn");
+  });
+
+  it("should return tool_use when LLM wants to call a tool", async () => {
+    const llm = createMockLlm([
+      toolCallResponse("memory_write", "tc1", { content: "test" }),
+      textResponse("Done!"),
+    ]);
+
+    const response1 = await llm.chat({ system: "test", messages: [{ role: "user", content: "remember this" }] });
+    expect(response1.content[0].type).toBe("tool_use");
+    expect(response1.content[0].name).toBe("memory_write");
+    expect(response1.stopReason).toBe("tool_use");
+
+    const response2 = await llm.chat({ system: "test", messages: [] });
+    expect(response2.content[0].type).toBe("text");
+    expect(response2.content[0].text).toBe("Done!");
+  });
+
+  it("should handle multiple tool rounds", async () => {
+    const llm = createMockLlm([
+      toolCallResponse("memory_search", "tc1", { query: "test" }),
+      toolCallResponse("memory_write", "tc2", { content: "found" }),
+      textResponse("All done"),
+    ]);
+
+    let response = await llm.chat({ system: "", messages: [] });
+    expect(response.content[0].name).toBe("memory_search");
+    response = await llm.chat({ system: "", messages: [] });
+    expect(response.content[0].name).toBe("memory_write");
+    response = await llm.chat({ system: "", messages: [] });
+    expect(response.content[0].text).toBe("All done");
+  });
+
+  it("should track usage correctly", async () => {
+    const llm = createMockLlm([textResponse("test")]);
+    const response = await llm.chat({ system: "", messages: [] });
+    expect(response.usage.inputTokens).toBe(100);
+    expect(response.usage.outputTokens).toBe(50);
+  });
+});

package/tests/auth.test.ts

@@ -0,0 +1,89 @@
+import { describe, it, expect, beforeEach } from "bun:test";
+import { Database } from "bun:sqlite";
+import {
+  generateApiKey,
+  hashApiKey,
+  initAuth,
+  createApiKey,
+  listApiKeys,
+  deleteApiKey,
+  validateRequest,
+  generateSessionToken,
+  validateSessionToken,
+} from "../src/util/auth";
+
+describe("Auth", () => {
+  let db: Database;
+
+  beforeEach(() => {
+    db = new Database(":memory:");
+    initAuth(db);
+  });
+
+  it("should generate a 64-character hex API key", () => {
+    const key = generateApiKey();
+    expect(key).toHaveLength(64);
+    expect(/^[a-f0-9]{64}$/.test(key)).toBe(true);
+  });
+
+  it("should hash an API key deterministically", () => {
+    const key = "abc123";
+    const hash1 = hashApiKey(key);
+    const hash2 = hashApiKey(key);
+    expect(hash1).toBe(hash2);
+    expect(hash1).not.toBe(key);
+    expect(hash1).toHaveLength(64); // SHA-256 hex
+  });
+
+  it("should validate a valid Bearer token", () => {
+    const result = createApiKey(db, "test-key");
+    const req = new Request("http://localhost/api/chat", {
+      headers: { Authorization: `Bearer ${result.key}` },
+    });
+    expect(validateRequest(db, req)).toBe(true);
+  });
+
+  it("should reject a missing token", () => {
+    const req = new Request("http://localhost/api/chat");
+    expect(validateRequest(db, req)).toBe(false);
+  });
+
+  it("should reject an invalid token", () => {
+    createApiKey(db, "real-key");
+    const req = new Request("http://localhost/api/chat", {
+      headers: { Authorization: "Bearer invalidtoken123" },
+    });
+    expect(validateRequest(db, req)).toBe(false);
+  });
+
+  it("should create, list, and delete keys", () => {
+    const k1 = createApiKey(db, "key-1");
+    const k2 = createApiKey(db, "key-2");
+
+    const keys = listApiKeys(db);
+    expect(keys).toHaveLength(2);
+    expect(keys[0].label).toBe("key-1");
+    expect(keys[1].label).toBe("key-2");
+
+    const deleted = deleteApiKey(db, k1.id);
+    expect(deleted).toBe(true);
+
+    const remaining = listApiKeys(db);
+    expect(remaining).toHaveLength(1);
+    expect(remaining[0].id).toBe(k2.id);
+  });
+
+  it("should handle dashboard session tokens", () => {
+    const token = generateSessionToken();
+    expect(typeof token).toBe("string");
+
+    // Valid on first use
+    expect(validateSessionToken(token)).toBe(true);
+    // Invalid on second use (single-use)
+    expect(validateSessionToken(token)).toBe(false);
+  });
+
+  it("should reject invalid session tokens", () => {
+    expect(validateSessionToken("nonexistent-token")).toBe(false);
+  });
+});

package/tests/channels.test.ts

@@ -0,0 +1,67 @@
+import { describe, it, expect } from "bun:test";
+import { splitMessage } from "../src/channels/utils";
+
+describe("Channel Utilities", () => {
+  describe("splitMessage", () => {
+    it("should return single chunk for short messages", () => {
+      const result = splitMessage("Hello world", 100);
+      expect(result).toEqual(["Hello world"]);
+    });
+
+    it("should split at newlines when possible", () => {
+      const msg = "Line 1\nLine 2\nLine 3";
+      const result = splitMessage(msg, 14);
+      expect(result.length).toBeGreaterThan(1);
+      // Each chunk should be within limit
+      for (const chunk of result) {
+        expect(chunk.length).toBeLessThanOrEqual(14);
+      }
+    });
+
+    it("should force-split long lines without newlines", () => {
+      const msg = "A".repeat(100);
+      const result = splitMessage(msg, 30);
+      expect(result.length).toBeGreaterThan(1);
+    });
+
+    it("should handle empty string", () => {
+      const result = splitMessage("", 100);
+      expect(result).toEqual([""]);
+    });
+
+    it("should handle exact boundary length", () => {
+      const msg = "A".repeat(50);
+      const result = splitMessage(msg, 50);
+      expect(result).toEqual([msg]);
+    });
+  });
+});
+
+describe("Router", () => {
+  it("should export createRouter function", async () => {
+    const { createRouter } = await import("../src/channels/router");
+    expect(typeof createRouter).toBe("function");
+  });
+
+  it("should handle addAdapter and stopAll", async () => {
+    const { createRouter } = await import("../src/channels/router");
+    const { createMockLlm, textResponse } = await import("./helpers/mock-llm");
+    const { createTestDb } = await import("./helpers/test-db");
+
+    const llm = createMockLlm([textResponse("hello")]);
+    const db = createTestDb();
+    const router = createRouter(llm, db);
+
+    let stopped = false;
+    const mockAdapter = {
+      channelName: "test",
+      start() {},
+      stop() { stopped = true; },
+      async sendMessage() {},
+    };
+
+    router.addAdapter(mockAdapter);
+    router.stopAll();
+    expect(stopped).toBe(true);
+  });
+});