@owloops/browserbird 1.0.0

package/src/db/logs.ts

@@ -0,0 +1,64 @@
+/** @fileoverview Structured log persistence: queryable via web UI. */
+
+import type { PaginatedResult } from './core.ts';
+import { getDb, paginate, DEFAULT_PER_PAGE } from './core.ts';
+
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+
+export interface LogRow {
+  id: number;
+  level: LogLevel;
+  source: string;
+  message: string;
+  channel_id: string | null;
+  created_at: string;
+}
+
+export function insertLog(
+  level: LogLevel,
+  source: string,
+  message: string,
+  channelId?: string,
+): void {
+  getDb()
+    .prepare(`INSERT INTO logs (level, source, message, channel_id) VALUES (?, ?, ?, ?)`)
+    .run(level, source, message, channelId ?? null);
+}
+
+const LOG_SORT_COLUMNS = new Set(['id', 'level', 'source', 'created_at']);
+const LOG_SEARCH_COLUMNS = ['message', 'source'] as const;
+
+export function getRecentLogs(
+  page = 1,
+  perPage = DEFAULT_PER_PAGE,
+  level?: string,
+  source?: string,
+  sort?: string,
+  search?: string,
+): PaginatedResult<LogRow> {
+  const conditions: string[] = [];
+  const params: (string | number)[] = [];
+  if (level) {
+    conditions.push('level = ?');
+    params.push(level);
+  }
+  if (source) {
+    conditions.push('source = ?');
+    params.push(source);
+  }
+  const where = conditions.join(' AND ');
+  return paginate<LogRow>('logs', page, perPage, {
+    where,
+    params,
+    defaultSort: 'created_at DESC',
+    sort,
+    search,
+    allowedSortColumns: LOG_SORT_COLUMNS,
+    searchColumns: LOG_SEARCH_COLUMNS,
+  });
+}
+
+export function deleteOldLogs(retentionDays: number): number {
+  const stmt = getDb().prepare(`DELETE FROM logs WHERE created_at < datetime('now', ? || ' days')`);
+  return Number(stmt.run(`-${retentionDays}`).changes);
+}

package/src/db/messages.ts

@@ -0,0 +1,79 @@
+/** @fileoverview Message logging: message audit trail and token tracking. */
+
+import { getDb } from './core.ts';
+
+export interface MessageRow {
+  id: number;
+  channel_id: string;
+  thread_id: string | null;
+  user_id: string;
+  direction: 'in' | 'out';
+  content: string | null;
+  tokens_in: number | null;
+  tokens_out: number | null;
+  created_at: string;
+}
+
+export function logMessage(
+  channelId: string,
+  threadId: string | null,
+  userId: string,
+  direction: 'in' | 'out',
+  content?: string,
+  tokensIn?: number,
+  tokensOut?: number,
+): void {
+  const stmt = getDb().prepare(
+    `INSERT INTO messages (channel_id, thread_id, user_id, direction, content, tokens_in, tokens_out)
+     VALUES (?, ?, ?, ?, ?, ?, ?)`,
+  );
+  stmt.run(
+    channelId,
+    threadId ?? null,
+    userId,
+    direction,
+    content ?? null,
+    tokensIn ?? null,
+    tokensOut ?? null,
+  );
+}
+
+export function getLastInboundMessage(
+  channelId: string,
+  threadId: string | null,
+): { content: string; timestamp: string } | undefined {
+  const row = getDb()
+    .prepare(
+      `SELECT content, created_at FROM messages
+       WHERE channel_id = ? AND thread_id IS ? AND direction = 'in' AND content IS NOT NULL
+       ORDER BY created_at DESC LIMIT 1`,
+    )
+    .get(channelId, threadId) as unknown as { content: string; created_at: string } | undefined;
+  if (!row) return undefined;
+  return { content: row.content, timestamp: row.created_at };
+}
+
+export function deleteOldMessages(retentionDays: number): number {
+  const stmt = getDb().prepare(
+    `DELETE FROM messages WHERE created_at < datetime('now', ? || ' days')`,
+  );
+  const result = stmt.run(`-${retentionDays}`);
+  return Number(result.changes);
+}
+
+export function getMessageStats(): {
+  totalMessages: number;
+  totalTokensIn: number;
+  totalTokensOut: number;
+} {
+  const row = getDb()
+    .prepare(
+      `SELECT
+         COUNT(*) as totalMessages,
+         COALESCE(SUM(tokens_in), 0) as totalTokensIn,
+         COALESCE(SUM(tokens_out), 0) as totalTokensOut
+       FROM messages`,
+    )
+    .get() as unknown as { totalMessages: number; totalTokensIn: number; totalTokensOut: number };
+  return row;
+}

package/src/db/path.ts

@@ -0,0 +1,30 @@
+/** @fileoverview Database path resolution: CLI flag, env var, or default. */
+
+import { resolve } from 'node:path';
+
+const DEFAULT_DB_PATH = resolve('.browserbird', 'browserbird.db');
+
+/**
+ * Resolves the database file path.
+ * Priority: explicit value > BROWSERBIRD_DB env var > default.
+ */
+export function resolveDbPath(explicit?: string): string {
+  if (explicit) return resolve(explicit);
+
+  const envValue = process.env['BROWSERBIRD_DB'];
+  if (envValue) return resolve(envValue);
+
+  return DEFAULT_DB_PATH;
+}
+
+/**
+ * Extracts --db value from a raw argv array, then resolves.
+ * Used by CLI command handlers that receive argv directly.
+ */
+export function resolveDbPathFromArgv(argv: string[]): string {
+  const idx = argv.indexOf('--db');
+  if (idx !== -1 && idx + 1 < argv.length) {
+    return resolveDbPath(argv[idx + 1]);
+  }
+  return resolveDbPath();
+}

package/src/db/sessions.ts

@@ -0,0 +1,165 @@
+/** @fileoverview Session persistence: channel-to-agent session mapping. */
+
+import type { PaginatedResult } from './core.ts';
+import type { MessageRow } from './messages.ts';
+import {
+  getDb,
+  paginate,
+  parseSort,
+  buildSearchClause,
+  DEFAULT_PER_PAGE,
+  MAX_PER_PAGE,
+} from './core.ts';
+import { generateUid, UID_PREFIX } from '../core/uid.ts';
+
+export interface SessionRow {
+  uid: string;
+  channel_id: string;
+  thread_id: string | null;
+  agent_id: string;
+  provider_session_id: string;
+  created_at: string;
+  last_active: string;
+  message_count: number;
+}
+
+export function findSession(channelId: string, threadId: string | null): SessionRow | undefined {
+  const stmt = getDb().prepare('SELECT * FROM sessions WHERE channel_id = ? AND thread_id IS ?');
+  return stmt.get(channelId, threadId) as unknown as SessionRow | undefined;
+}
+
+export function createSession(
+  channelId: string,
+  threadId: string | null,
+  agentId: string,
+  providerSessionId: string,
+): SessionRow {
+  const uid = generateUid(UID_PREFIX.session);
+  const stmt = getDb().prepare(
+    `INSERT INTO sessions (uid, channel_id, thread_id, agent_id, provider_session_id)
+     VALUES (?, ?, ?, ?, ?)
+     RETURNING *`,
+  );
+  return stmt.get(uid, channelId, threadId, agentId, providerSessionId) as unknown as SessionRow;
+}
+
+export function touchSession(uid: string, messageCountDelta = 1): void {
+  const stmt = getDb().prepare(
+    `UPDATE sessions SET last_active = datetime('now'), message_count = message_count + ? WHERE uid = ?`,
+  );
+  stmt.run(messageCountDelta, uid);
+}
+
+const SESSION_SORT_COLUMNS = new Set([
+  'uid',
+  'channel_id',
+  'agent_id',
+  'message_count',
+  'last_active',
+  'created_at',
+]);
+const SESSION_SEARCH_COLUMNS = ['channel_id', 'thread_id', 'agent_id'] as const;
+
+export function listSessions(
+  page = 1,
+  perPage = DEFAULT_PER_PAGE,
+  sort?: string,
+  search?: string,
+): PaginatedResult<SessionRow> {
+  return paginate<SessionRow>('sessions', page, perPage, {
+    defaultSort: 'last_active DESC',
+    sort,
+    search,
+    allowedSortColumns: SESSION_SORT_COLUMNS,
+    searchColumns: SESSION_SEARCH_COLUMNS,
+  });
+}
+
+export function getSession(uid: string): SessionRow | undefined {
+  return getDb().prepare('SELECT * FROM sessions WHERE uid = ?').get(uid) as unknown as
+    | SessionRow
+    | undefined;
+}
+
+const MESSAGE_SORT_COLUMNS = new Set(['id', 'created_at', 'direction', 'user_id']);
+const MESSAGE_SEARCH_COLUMNS = ['content', 'user_id'] as const;
+
+export function getSessionMessages(
+  channelId: string,
+  threadId: string | null,
+  page = 1,
+  perPage = DEFAULT_PER_PAGE,
+  sort?: string,
+  search?: string,
+): PaginatedResult<MessageRow> {
+  const pp = Math.min(Math.max(perPage, 1), MAX_PER_PAGE);
+  const p = Math.max(page, 1);
+  const offset = (p - 1) * pp;
+
+  const conditions = ['channel_id = ? AND thread_id IS ?'];
+  const allParams: (string | number)[] = [channelId, threadId as string];
+
+  if (search) {
+    const sc = buildSearchClause(search, MESSAGE_SEARCH_COLUMNS);
+    if (sc.sql) {
+      conditions.push(sc.sql);
+      allParams.push(...sc.params);
+    }
+  }
+
+  const where = conditions.join(' AND ');
+  const orderBy = parseSort(sort, MESSAGE_SORT_COLUMNS, 'created_at ASC, id ASC');
+
+  const countRow = getDb()
+    .prepare(`SELECT COUNT(*) as count FROM messages WHERE ${where}`)
+    .get(...allParams) as unknown as { count: number };
+
+  const totalItems = countRow.count;
+  const totalPages = Math.max(Math.ceil(totalItems / pp), 1);
+
+  const items = getDb()
+    .prepare(
+      `SELECT * FROM messages
+       WHERE ${where}
+       ORDER BY ${orderBy}
+       LIMIT ? OFFSET ?`,
+    )
+    .all(...allParams, pp, offset) as unknown as MessageRow[];
+
+  return { items, page: p, perPage: pp, totalItems, totalPages };
+}
+
+export function getSessionTokenStats(
+  channelId: string,
+  threadId: string | null,
+): { totalTokensIn: number; totalTokensOut: number } {
+  return getDb()
+    .prepare(
+      `SELECT COALESCE(SUM(tokens_in), 0) as totalTokensIn,
+              COALESCE(SUM(tokens_out), 0) as totalTokensOut
+       FROM messages
+       WHERE channel_id = ? AND thread_id IS ?`,
+    )
+    .get(channelId, threadId) as unknown as { totalTokensIn: number; totalTokensOut: number };
+}
+
+export function getSessionCount(): number {
+  const row = getDb().prepare('SELECT COUNT(*) as count FROM sessions').get() as unknown as {
+    count: number;
+  };
+  return row.count;
+}
+
+export function deleteStaleSessions(ttlHours: number): number {
+  const stmt = getDb().prepare(
+    `DELETE FROM sessions WHERE last_active < datetime('now', ? || ' hours')`,
+  );
+  const result = stmt.run(`-${ttlHours}`);
+  return Number(result.changes);
+}
+
+export function updateSessionProviderId(uid: string, providerSessionId: string): void {
+  getDb()
+    .prepare('UPDATE sessions SET provider_session_id = ? WHERE uid = ?')
+    .run(providerSessionId, uid);
+}

package/src/jobs.ts

@@ -0,0 +1,140 @@
+/** @fileoverview Background job queue with handler registry, polling worker, and retry logic. */
+
+import type { CreateJobOptions, JobRow, JobPriority } from './db/index.ts';
+import {
+  createJob,
+  claimNextJob,
+  completeJob,
+  failJob,
+  failStaleJobs,
+  insertLog,
+  updateCronJobStatus,
+  getCronJob,
+  createCronRun,
+  completeCronRun,
+} from './db/index.ts';
+import { logger } from './core/logger.ts';
+import { broadcastSSE } from './server/index.ts';
+
+type JobHandler = (payload: unknown) => Promise<string | void> | string | void;
+
+const handlers = new Map<string, JobHandler>();
+
+const POLL_INTERVAL_MS = 1000;
+const STALE_CHECK_INTERVAL_MS = 5 * 60 * 1000;
+
+export function registerHandler(name: string, handler: JobHandler): void {
+  handlers.set(name, handler);
+}
+
+export interface QueueOptions {
+  priority?: JobPriority;
+  maxAttempts?: number;
+  timeout?: number;
+  delaySeconds?: number;
+  cronJobUid?: string;
+}
+
+export function enqueue(name: string, payload?: unknown, options?: QueueOptions): JobRow {
+  const jobOptions: CreateJobOptions = {
+    name,
+    payload,
+    priority: options?.priority,
+    maxAttempts: options?.maxAttempts,
+    timeout: options?.timeout,
+    delaySeconds: options?.delaySeconds,
+    cronJobUid: options?.cronJobUid,
+  };
+  const job = createJob(jobOptions);
+  logger.debug(`enqueued job ${job.id}: ${name}`);
+  return job;
+}
+
+async function processJob(job: JobRow): Promise<void> {
+  const handler = handlers.get(job.name);
+  if (!handler) {
+    failJob(job.id, `no handler registered for "${job.name}"`);
+    logger.warn(`job ${job.id}: no handler for "${job.name}"`);
+    return;
+  }
+
+  const isCronRun = job.cron_job_uid != null;
+  const cronRun = isCronRun ? createCronRun(job.cron_job_uid!) : null;
+
+  let finalStatus = 'completed';
+  let resultText: string | undefined;
+  let errorText: string | undefined;
+  try {
+    const payload = job.payload ? (JSON.parse(job.payload) as unknown) : undefined;
+    const result = await handler(payload);
+    resultText = typeof result === 'string' ? result : undefined;
+    completeJob(job.id, resultText);
+    logger.debug(`job ${job.id} completed: ${job.name}`);
+  } catch (err) {
+    finalStatus = 'failed';
+    errorText = err instanceof Error ? err.message : String(err);
+    failJob(job.id, errorText);
+    logger.warn(`job ${job.id} failed (attempt ${job.attempts}/${job.max_attempts}): ${errorText}`);
+    insertLog('error', 'cron', errorText);
+  } finally {
+    if (cronRun != null) {
+      completeCronRun(
+        cronRun.uid,
+        finalStatus === 'completed' ? 'success' : 'error',
+        resultText,
+        errorText,
+      );
+    }
+    if (isCronRun && job.cron_job_uid != null) {
+      const cronJob = getCronJob(job.cron_job_uid);
+      if (cronJob != null) {
+        const newFailureCount =
+          finalStatus === 'failed' ? cronJob.failure_count + 1 : cronJob.failure_count;
+        updateCronJobStatus(job.cron_job_uid, finalStatus, newFailureCount);
+      }
+    }
+    const resource = isCronRun ? 'birds' : 'sessions';
+    const invalidatePayload: { resource: string; cronJobUid?: string } = { resource };
+    if (job.cron_job_uid != null) invalidatePayload.cronJobUid = job.cron_job_uid;
+    broadcastSSE('invalidate', invalidatePayload);
+  }
+}
+
+/**
+ * Starts the job worker loop. Polls for pending jobs, processes them one at a time.
+ * Checks for stale running jobs every 5 minutes.
+ */
+export function startWorker(signal: AbortSignal): void {
+  let pollTimer: ReturnType<typeof setTimeout> | null = null;
+
+  const pollTick = async () => {
+    if (signal.aborted) return;
+
+    const job = claimNextJob();
+    if (job) {
+      await processJob(job);
+      if (!signal.aborted) pollTick();
+      return;
+    }
+
+    pollTimer = setTimeout(pollTick, POLL_INTERVAL_MS);
+  };
+
+  const staleCheck = () => {
+    if (signal.aborted) return;
+    const stale = failStaleJobs();
+    if (stale > 0) {
+      logger.info(`timed out ${stale} stale job(s)`);
+    }
+  };
+
+  staleCheck();
+  const staleTimer = setInterval(staleCheck, STALE_CHECK_INTERVAL_MS);
+
+  signal.addEventListener('abort', () => {
+    if (pollTimer) clearTimeout(pollTimer);
+    clearInterval(staleTimer);
+  });
+
+  pollTick();
+}

package/src/provider/claude.test.ts

@@ -0,0 +1,95 @@
+/** @fileoverview Tests for the Claude CLI stream parser. */
+
+import { describe, it } from 'node:test';
+import { deepStrictEqual, strictEqual } from 'node:assert';
+import { claude } from './claude.ts';
+
+describe('claude parseStreamLine', () => {
+  it('parses system event into init', () => {
+    const events = claude.parseStreamLine(
+      '{"type":"system","session_id":"abc-123","model":"claude-sonnet-4-20250514"}',
+    );
+    strictEqual(events.length, 1);
+    deepStrictEqual(events[0], {
+      type: 'init',
+      sessionId: 'abc-123',
+      model: 'claude-sonnet-4-20250514',
+    });
+  });
+
+  it('parses assistant text content', () => {
+    const events = claude.parseStreamLine(
+      '{"type":"assistant","message":{"content":[{"type":"text","text":"4"}]}}',
+    );
+    strictEqual(events.length, 1);
+    deepStrictEqual(events[0], { type: 'text_delta', delta: '4' });
+  });
+
+  it('parses result into completion with full metrics', () => {
+    const events = claude.parseStreamLine(
+      JSON.stringify({
+        type: 'result',
+        subtype: 'success',
+        result: '4',
+        session_id: 'abc-123',
+        is_error: false,
+        usage: {
+          input_tokens: 100,
+          output_tokens: 5,
+          cache_creation_input_tokens: 50,
+          cache_read_input_tokens: 10,
+        },
+        total_cost_usd: 0.001,
+        duration_ms: 1500,
+        num_turns: 3,
+      }),
+    );
+    strictEqual(events.length, 1);
+    const c = events[0]!;
+    strictEqual(c.type, 'completion');
+    if (c.type === 'completion') {
+      strictEqual(c.subtype, 'success');
+      strictEqual(c.tokensIn, 100);
+      strictEqual(c.tokensOut, 5);
+      strictEqual(c.cacheCreationTokens, 50);
+      strictEqual(c.cacheReadTokens, 10);
+      strictEqual(c.costUsd, 0.001);
+      strictEqual(c.durationMs, 1500);
+      strictEqual(c.numTurns, 3);
+    }
+  });
+
+  it('parses error event', () => {
+    const events = claude.parseStreamLine('{"type":"error","error":"something broke"}');
+    strictEqual(events.length, 1);
+    deepStrictEqual(events[0], { type: 'error', error: 'something broke' });
+  });
+
+  it('returns empty for blank lines', () => {
+    strictEqual(claude.parseStreamLine('').length, 0);
+    strictEqual(claude.parseStreamLine('   ').length, 0);
+  });
+
+  it('returns empty for non-json', () => {
+    strictEqual(claude.parseStreamLine('not json at all').length, 0);
+  });
+
+  it('ignores tool_use content blocks', () => {
+    const events = claude.parseStreamLine(
+      '{"type":"assistant","message":{"content":[{"type":"tool_use","id":"toolu_1","name":"bash","input":{}}]}}',
+    );
+    strictEqual(events.length, 0);
+  });
+
+  it('parses rate_limit_event', () => {
+    const events = claude.parseStreamLine(
+      '{"type":"rate_limit_event","rate_limit_info":{"status":"rate_limited","resetsAt":1700000000}}',
+    );
+    strictEqual(events.length, 1);
+    deepStrictEqual(events[0], {
+      type: 'rate_limit',
+      status: 'rate_limited',
+      resetsAt: 1700000000,
+    });
+  });
+});