@schlessera/brain-ui-server 0.13.0 → 0.14.0

package/src/app.ts

@@ -1,38 +1,62 @@
 import { Hono } from "hono";
 import type { Context } from "hono";
+import type { Database } from "bun:sqlite";
 import { logger } from "hono/logger";
 import { cors } from "hono/cors";
 import { serveStatic } from "hono/bun";
 import { join } from "path";
-import { healthRoutes, statusRoutes } from "./routes/health.js";
-import { brainRoutes } from "./routes/brain.js";
-import { sessionRoutes } from "./routes/sessions.js";
-import { voiceRoutes } from "./routes/voice.js";
-import { filesRoutes } from "./routes/files.js";
-import { shareRoutes, shareTargetFallbackRoutes } from "./routes/share.js";
+import { resolveServerConfig, type ServerConfig } from "./config/env.js";
+import { healthRoutes, createStatusRoutes } from "./routes/health.js";
+import { createBrainRoutes } from "./routes/brain.js";
+import { createSessionRoutes } from "./routes/sessions.js";
+import { createVoiceRoutes } from "./routes/voice.js";
+import { createFilesRoutes } from "./routes/files.js";
+import { createShareRoutes, shareTargetFallbackRoutes } from "./routes/share.js";
 import { createRenderRoutes, type AppRenderer } from "./routes/render.js";
-import { providerRoutes } from "./routes/providers.js";
-import { modelRoutes } from "./routes/models.js";
-import { graphRoutes } from "./routes/graph.js";
+import { createProviderRoutes } from "./routes/providers.js";
+import { createModelRoutes } from "./routes/models.js";
+import { createGraphRoutes } from "./routes/graph.js";
 import {
   resolveAuthMode,
   assertAuthConfig,
   authGuard,
   authRoutes,
   isWsAuthorized,
+  type AuthMode,
+  type AuthRuntime,
 } from "./middleware/auth.js";
 import {
   passkeyPublicRoutes,
   passkeyManagementRoutes,
   passwordLoginDisabled,
   assertPasskeyConfig,
+  type PasskeyContext,
 } from "./middleware/passkeys.js";
-import { configureDb } from "./db/client.js";
-import { configureWsHost, wsUpgrade, websocket } from "./ws/handler.js";
+import { createUiDb } from "./db/client.js";
+import { getHiddenModelIds } from "./db/settings.js";
+import {
+  assertBackendResolvable,
+  createBackendRegistry,
+  type BackendRegistry,
+} from "./agent/backend.js";
+import { createBrainClient } from "./brain/client.js";
+import { createCronScheduler } from "./cron/scheduler.js";
+import { WsHost } from "./ws/host.js";
+import { createWsUpgrade, websocket } from "./ws/connection.js";
+import { createSessionCatalog } from "./ws/session-catalog.js";
+import type { KeytermSettings } from "./voice/keyterm-builder.js";
 
 export type { AppRenderer };
 
 export interface CreateAppOptions {
+  /**
+   * Fully-resolved configuration. When omitted, `createApp` resolves it from
+   * the process environment ONCE, here at the edge — nothing deeper in the
+   * package touches the ambient environment. Pass an explicit object (e.g. from
+   * `resolveServerConfig(customEnv)`) to run two differently-configured apps
+   * in one process or to vary configuration in tests without env mutation.
+   */
+  config?: ServerConfig;
   /**
    * Directory of a built SPA to serve at `/*` with an index.html fallback.
    * The deployment shell decides whether (and what) to serve — the package
@@ -41,7 +65,11 @@ export interface CreateAppOptions {
   staticRoot?: string;
   /** Display name used in connection/status copy. Default "Brain UI". */
   appName?: string;
-  /** SQLite path override; falls back to DB_PATH, then ./brain-ui.db. */
+  /**
+   * SQLite path override; folded into the effective config, so `app.config.dbPath`
+   * always names the database actually opened. Falls back to config.dbPath
+   * (DB_PATH, ./brain-ui.db).
+   */
   dbPath?: string;
   /**
    * PNG/PDF renderer for `POST /api/render`. The deployment owns the actual
@@ -51,6 +79,32 @@ export interface CreateAppOptions {
   renderer?: AppRenderer;
   /** Per-turn timeout in ms (default 10 minutes). */
   turnTimeoutMs?: number;
+  /** Backend registry override (tests/embedders); default is built from config. */
+  registry?: BackendRegistry;
+}
+
+/** What `createApp` hands back to the deployment shell. */
+export interface BrainUiApp {
+  fetch: Hono["fetch"];
+  websocket: typeof websocket;
+  /** The configuration this instance runs on (resolved or injected). */
+  config: ServerConfig;
+  /**
+   * The auth mode this instance resolved and validated at boot — so the
+   * deployment shell can log it without re-deriving the AuthRuntime that
+   * resolveAuthMode needs.
+   */
+  authMode: AuthMode;
+  /** The app's own SQLite handle (sessions, passkeys, settings). */
+  db: Database;
+  /** The WebSocket coordinator (turn state, clients, catalog, registry). */
+  wsHost: WsHost;
+  /** True while any session has a running turn. */
+  isTurnActive(): boolean;
+  /** Cancel every running turn (used on shutdown). Returns true if any was. */
+  cancelActiveTurns(): boolean;
+  /** Release process-held resources (the SQLite handle). */
+  close(): void;
 }
 
 // Cross-site WebSocket hijacking (CSWSH) defense. CORS does not apply to the WS
@@ -72,20 +126,63 @@ function isAllowedWsOrigin(c: Context, allowedOrigins: string[]): boolean {
   }
 }
 
-export function createApp(options: CreateAppOptions = {}) {
+export function createApp(options: CreateAppOptions = {}): BrainUiApp {
+  // The edge: ambient environment becomes explicit configuration exactly once.
+  // options.dbPath folds into the config here, so the handle's `config` and
+  // the database actually opened can never disagree.
+  const resolved = options.config ?? resolveServerConfig();
+  // Checked against undefined, not truthiness: SQLite treats "" as a valid
+  // anonymous temporary database, and an explicit empty override must not
+  // silently fall back to the resolved path.
+  const config: ServerConfig =
+    options.dbPath !== undefined ? { ...resolved, dbPath: options.dbPath } : resolved;
+  const auth: AuthRuntime = { ...config.auth, host: config.host };
+
   const app = new Hono();
-  const authMode = resolveAuthMode();
+  const authMode = resolveAuthMode(auth);
   // Validate inside the factory, not the bin entry: every consumer of the app
   // (a deployment bin, tests, another embedder) gets the same refuse-to-boot
   // guarantee on an unsafe auth configuration.
-  assertAuthConfig(authMode);
-  assertPasskeyConfig();
+  assertAuthConfig(authMode, auth);
+  assertPasskeyConfig(config.webauthn);
+  // A missing (or unrecognized) agent backend refuses to boot HERE, not on the
+  // first turn — otherwise /api/health reports healthy while every turn is
+  // guaranteed to fail. Resolution only; the module still loads lazily.
+  // Skipped when the embedder injects its own registry.
+  if (!options.registry) assertBackendResolvable(config.agent);
 
-  if (options.dbPath) configureDb(options.dbPath);
-  configureWsHost({
+  // Per-instance state: the app's own database, the brain CLI wrapper, the
+  // backend registry, and the WebSocket host. No module-level singletons —
+  // two apps with different configuration coexist in one process.
+  const db = createUiDb(config.dbPath);
+  const brain = createBrainClient({ brainPath: config.brainPath });
+  const cron = createCronScheduler({ db, brain });
+  const registry =
+    options.registry ??
+    createBackendRegistry({
+      brainPath: config.brainPath,
+      agent: config.agent,
+      getHiddenModelIds: () => getHiddenModelIds(db),
+    });
+  const host = new WsHost({
+    registry,
+    catalog: createSessionCatalog(() => db),
     ...(options.appName ? { appName: options.appName } : {}),
     ...(options.turnTimeoutMs ? { turnTimeoutMs: options.turnTimeoutMs } : {}),
+    maxConcurrentSessions: () => config.maxConcurrentSessions,
   });
+  const wsUpgrade = createWsUpgrade(host);
+  const passkeyCtx: PasskeyContext = {
+    db,
+    webauthn: config.webauthn,
+    auth,
+    allowedOrigins: config.allowedOrigins,
+  };
+  const keyterms: KeytermSettings = {
+    brainPath: config.brainPath,
+    cacheDir: config.voice.cacheDir,
+    limit: config.voice.keytermLimit,
+  };
 
   // Middleware
   app.use("*", logger());
@@ -94,10 +191,7 @@ export function createApp(options: CreateAppOptions = {}) {
   // different origin than the API. ALLOWED_ORIGINS is a comma-separated
   // allowlist; empty/unset means same-origin (the default), so the CORS
   // middleware is skipped entirely.
-  const allowedOrigins = (process.env.ALLOWED_ORIGINS ?? "")
-    .split(",")
-    .map((origin) => origin.trim())
-    .filter(Boolean);
+  const allowedOrigins = config.allowedOrigins;
   if (allowedOrigins.length > 0) {
     app.use(
       "/api/*",
@@ -118,27 +212,45 @@ export function createApp(options: CreateAppOptions = {}) {
   // Not under /api, and not behind the guard: this is where a system share
   // lands when no service worker was around to intercept it. See the route.
   app.route("/", shareTargetFallbackRoutes);
-  app.route("/api", authRoutes(authMode, { passwordDisabled: passwordLoginDisabled }));
-  app.route("/api", passkeyPublicRoutes(authMode));
+  app.route(
+    "/api",
+    authRoutes(authMode, auth, {
+      passwordDisabled: (c) => passwordLoginDisabled(c, passkeyCtx),
+    })
+  );
+  app.route("/api", passkeyPublicRoutes(authMode, passkeyCtx));
 
   // Auth guard for every other /api/* route. The probe below is intentionally
   // behind it: an unauthenticated client gets 401 (password/proxy) or 403
   // (tailscale) from /api/vpn-check and shows the login / VPN screen.
-  app.use("/api/*", authGuard(authMode));
+  app.use("/api/*", authGuard(authMode, auth));
   app.get("/api/vpn-check", (c) => c.json({ vpn: true }));
   // Passkey registration/management: after the guard, so a session is required
   // by mount position (the public assertion routes are registered above).
-  app.route("/api", passkeyManagementRoutes(authMode));
-  app.route("/api", statusRoutes);
-  app.route("/api", brainRoutes);
-  app.route("/api", sessionRoutes);
-  app.route("/api", voiceRoutes);
-  app.route("/api", filesRoutes);
-  app.route("/api", shareRoutes);
+  app.route("/api", passkeyManagementRoutes(authMode, passkeyCtx));
+  app.route(
+    "/api",
+    createStatusRoutes({
+      sourceCommit: config.sourceCommit,
+      getCronStatus: () => cron.getCronStatus(),
+      isTurnActive: () => host.coordinator.isTurnActive(),
+    })
+  );
+  app.route(
+    "/api",
+    createBrainRoutes({ brain, brainPath: config.brainPath, keyterms })
+  );
+  app.route("/api", createSessionRoutes({ registry, db }));
+  app.route("/api", createVoiceRoutes({ voice: config.voice, keyterms }));
+  app.route("/api", createFilesRoutes({ brainRoot: config.brainPath }));
+  app.route(
+    "/api",
+    createShareRoutes({ brainRoot: config.brainPath, allowedOrigins })
+  );
   app.route("/api", createRenderRoutes(options.renderer));
-  app.route("/api", providerRoutes);
-  app.route("/api", modelRoutes);
-  app.route("/api", graphRoutes);
+  app.route("/api", createProviderRoutes({ registry }));
+  app.route("/api", createModelRoutes({ registry, db }));
+  app.route("/api", createGraphRoutes({ brainRoot: config.brainPath }));
 
   // WebSocket endpoint. Browsers can't set headers on the WS handshake, so the
   // upgrade authenticates via the session cookie (or IP/proxy header) INSIDE
@@ -147,7 +259,7 @@ export function createApp(options: CreateAppOptions = {}) {
     if (!isAllowedWsOrigin(c, allowedOrigins)) {
       return c.json({ error: "Cross-origin WebSocket rejected" }, 403);
     }
-    if (!(await isWsAuthorized(c, authMode))) {
+    if (!(await isWsAuthorized(c, authMode, auth))) {
       return c.json({ error: "Authentication required" }, 401);
     }
     return wsUpgrade(c, next);
@@ -164,5 +276,14 @@ export function createApp(options: CreateAppOptions = {}) {
   return {
     fetch: app.fetch,
     websocket,
+    config,
+    authMode,
+    db,
+    wsHost: host,
+    isTurnActive: () => host.coordinator.isTurnActive(),
+    cancelActiveTurns: () => host.coordinator.cancelAll("Server shutting down"),
+    close: () => {
+      db.close();
+    },
   };
 }

package/src/brain/client.ts

@@ -1,5 +1,6 @@
 import { existsSync } from "fs";
 import { join } from "path";
+import { subprocessEnv } from "../config/env.js";
 import type {
   BrainSearchResult,
   BrainSearchResponse,
@@ -8,179 +9,201 @@ import type {
   BrainSyncResult,
 } from "./types.js";
 
-const BRAIN_PATH = process.env.BRAIN_PATH || join(process.env.HOME || "/root", "brain");
+/**
+ * Wrapper around the brain CLI, bound to one brain repo. Constructed by
+ * `createApp()` (or an embedder) with the resolved brain path — no ambient
+ * environment, so two clients against different repos can coexist.
+ */
+export interface BrainClient {
+  /** argv prefix for invoking the brain CLI inside the repo. */
+  cliCommand(): string[];
+  search(
+    query: string,
+    opts?: { type?: string; tag?: string; limit?: number; mode?: string }
+  ): Promise<BrainSearchResponse>;
+  briefing(): Promise<string>;
+  stats(): Promise<BrainStats>;
+  list(opts?: {
+    type?: string;
+    tag?: string;
+    status?: string;
+    relevance?: string;
+    limit?: number;
+  }): Promise<BrainDocument[]>;
+  read(path: string): Promise<string>;
+  sync(): Promise<BrainSyncResult>;
+  add(
+    content: string,
+    opts?: { type?: string; title?: string; tags?: string[] }
+  ): Promise<void>;
+  index(opts?: { force?: boolean }): Promise<void>;
+  validate(): Promise<string>;
+}
+
+interface ExecResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
 
 /**
- * argv prefix for invoking the brain CLI inside BRAIN_PATH.
+ * argv prefix for invoking the brain CLI inside `brainPath`.
  *
  * Two brain-repo layouts exist and both must work: a repo that depends on
  * `@schlessera/brain` gets a real bin at `node_modules/.bin/brain`, while the
  * legacy layout vendors `scripts/brain-cli.ts`. Prefer the packaged bin.
  *
- * Resolved per call (a bare `existsSync` stat) rather than at import time: in
+ * Resolved per call (a bare `existsSync` stat) rather than at construction: in
  * the container the brain repo is cloned and `bun install`ed by entrypoint.sh,
  * and a repo can gain the dependency without restarting this server. The same
  * preference order is mirrored in `scripts/entrypoint.sh`, which links whichever
  * it finds onto PATH for cron.
  */
-export function brainCliCommand(): string[] {
-  const packaged = join(BRAIN_PATH, "node_modules", ".bin", "brain");
+export function brainCliCommand(brainPath: string): string[] {
+  const packaged = join(brainPath, "node_modules", ".bin", "brain");
   if (existsSync(packaged)) return [packaged];
   return ["bun", "scripts/brain-cli.ts"];
 }
 
-interface ExecResult {
-  stdout: string;
-  stderr: string;
-  exitCode: number;
-}
+export function createBrainClient(opts: { brainPath: string }): BrainClient {
+  const { brainPath } = opts;
 
-async function execBrain(args: string[]): Promise<ExecResult> {
-  const proc = Bun.spawn([...brainCliCommand(), ...args], {
-    cwd: BRAIN_PATH,
-    stdout: "pipe",
-    stderr: "pipe",
-    env: {
-      ...process.env,
+  async function execBrain(args: string[]): Promise<ExecResult> {
+    const proc = Bun.spawn([...brainCliCommand(brainPath), ...args], {
+      cwd: brainPath,
+      stdout: "pipe",
+      stderr: "pipe",
       // Force JSON output when not a TTY
-      NO_COLOR: "1",
-    },
-  });
+      env: subprocessEnv({ NO_COLOR: "1" }),
+    });
 
-  const [stdout, stderr] = await Promise.all([
-    new Response(proc.stdout).text(),
-    new Response(proc.stderr).text(),
-  ]);
-  const exitCode = await proc.exited;
+    const [stdout, stderr] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+    ]);
+    const exitCode = await proc.exited;
 
-  return { stdout, stderr, exitCode };
-}
-
-function parseJsonOutput<T>(result: ExecResult): T {
-  if (result.exitCode !== 0) {
-    throw new Error(
-      `brain CLI failed (exit ${result.exitCode}): ${result.stderr || result.stdout}`
-    );
+    return { stdout, stderr, exitCode };
   }
-  try {
-    return JSON.parse(result.stdout);
-  } catch {
-    // Some commands output plain text, not JSON
-    return result.stdout as unknown as T;
+
+  function parseJsonOutput<T>(result: ExecResult): T {
+    if (result.exitCode !== 0) {
+      throw new Error(
+        `brain CLI failed (exit ${result.exitCode}): ${result.stderr || result.stdout}`
+      );
+    }
+    try {
+      return JSON.parse(result.stdout);
+    } catch {
+      // Some commands output plain text, not JSON
+      return result.stdout as unknown as T;
+    }
   }
-}
 
-export async function brainSearch(
-  query: string,
-  opts?: { type?: string; tag?: string; limit?: number; mode?: string }
-): Promise<BrainSearchResponse> {
-  const args = ["search", query];
-  if (opts?.type) args.push("--type", opts.type);
-  if (opts?.tag) args.push("--tag", opts.tag);
-  if (opts?.limit) args.push("--limit", String(opts.limit));
-  if (opts?.mode) args.push("--mode", opts.mode);
-
-  const result = await execBrain(args);
-  const parsed = parseJsonOutput<BrainSearchResponse | BrainSearchResult[]>(result);
-  // brain returns {results, warnings} since 22e82e1; tolerate the old bare array
-  return Array.isArray(parsed) ? { results: parsed, warnings: [] } : parsed;
-}
+  return {
+    cliCommand() {
+      return brainCliCommand(brainPath);
+    },
 
-export async function brainBriefing(): Promise<string> {
-  const result = await execBrain(["briefing"]);
-  if (result.exitCode !== 0) {
-    throw new Error(`brain briefing failed: ${result.stderr}`);
-  }
-  return result.stdout;
-}
+    async search(query, opts) {
+      const args = ["search", query];
+      if (opts?.type) args.push("--type", opts.type);
+      if (opts?.tag) args.push("--tag", opts.tag);
+      if (opts?.limit) args.push("--limit", String(opts.limit));
+      if (opts?.mode) args.push("--mode", opts.mode);
+
+      const result = await execBrain(args);
+      const parsed = parseJsonOutput<BrainSearchResponse | BrainSearchResult[]>(result);
+      // brain returns {results, warnings} since 22e82e1; tolerate the old bare array
+      return Array.isArray(parsed) ? { results: parsed, warnings: [] } : parsed;
+    },
 
-export async function brainStats(): Promise<BrainStats> {
-  const result = await execBrain(["stats"]);
-  return parseJsonOutput(result);
-}
+    async briefing() {
+      const result = await execBrain(["briefing"]);
+      if (result.exitCode !== 0) {
+        throw new Error(`brain briefing failed: ${result.stderr}`);
+      }
+      return result.stdout;
+    },
 
-export async function brainList(opts?: {
-  type?: string;
-  tag?: string;
-  status?: string;
-  relevance?: string;
-  limit?: number;
-}): Promise<BrainDocument[]> {
-  const args = ["list"];
-  if (opts?.type) args.push("--type", opts.type);
-  if (opts?.tag) args.push("--tag", opts.tag);
-  if (opts?.status) args.push("--status", opts.status);
-  if (opts?.relevance) args.push("--relevance", opts.relevance);
-  if (opts?.limit) args.push("--limit", String(opts.limit));
-
-  const result = await execBrain(args);
-  return parseJsonOutput(result);
-}
+    async stats() {
+      const result = await execBrain(["stats"]);
+      return parseJsonOutput(result);
+    },
 
-export async function brainRead(path: string): Promise<string> {
-  const result = await execBrain(["read", path]);
-  if (result.exitCode !== 0) {
-    throw new Error(`brain read failed: ${result.stderr}`);
-  }
-  return result.stdout;
-}
+    async list(opts) {
+      const args = ["list"];
+      if (opts?.type) args.push("--type", opts.type);
+      if (opts?.tag) args.push("--tag", opts.tag);
+      if (opts?.status) args.push("--status", opts.status);
+      if (opts?.relevance) args.push("--relevance", opts.relevance);
+      if (opts?.limit) args.push("--limit", String(opts.limit));
 
-export async function brainSync(): Promise<BrainSyncResult> {
-  // Note: brain sync spawns Claude Code internally via the /sync skill.
-  // For cron jobs, we use a simpler git-based sync instead.
-  const result = await execBrain(["sync"]);
-  if (result.exitCode !== 0) {
-    return {
-      success: false,
-      commits: 0,
-      conflicts: 0,
-      message: result.stderr || result.stdout,
-    };
-  }
-  try {
-    return parseJsonOutput(result);
-  } catch {
-    return {
-      success: true,
-      commits: 0,
-      conflicts: 0,
-      message: result.stdout,
-    };
-  }
-}
+      const result = await execBrain(args);
+      return parseJsonOutput(result);
+    },
 
-export async function brainAdd(
-  content: string,
-  opts?: { type?: string; title?: string; tags?: string[] }
-): Promise<void> {
-  const args = ["add", content];
-  if (opts?.type) args.push("--type", opts.type);
-  if (opts?.title) args.push("--title", opts.title);
-  if (opts?.tags) args.push("--tags", opts.tags.join(","));
-
-  const result = await execBrain(args);
-  if (result.exitCode !== 0) {
-    throw new Error(`brain add failed: ${result.stderr}`);
-  }
-}
+    async read(path) {
+      const result = await execBrain(["read", path]);
+      if (result.exitCode !== 0) {
+        throw new Error(`brain read failed: ${result.stderr}`);
+      }
+      return result.stdout;
+    },
 
-export async function brainIndex(opts?: {
-  /** Full rebuild; indexing is incremental by default since brain 22e82e1. */
-  force?: boolean;
-}): Promise<void> {
-  const args = ["index"];
-  if (opts?.force) args.push("--force");
+    async sync() {
+      // Note: brain sync spawns Claude Code internally via the /sync skill.
+      // For cron jobs, we use a simpler git-based sync instead.
+      const result = await execBrain(["sync"]);
+      if (result.exitCode !== 0) {
+        return {
+          success: false,
+          commits: 0,
+          conflicts: 0,
+          message: result.stderr || result.stdout,
+        };
+      }
+      try {
+        return parseJsonOutput(result);
+      } catch {
+        return {
+          success: true,
+          commits: 0,
+          conflicts: 0,
+          message: result.stdout,
+        };
+      }
+    },
 
-  const result = await execBrain(args);
-  if (result.exitCode !== 0) {
-    throw new Error(`brain index failed: ${result.stderr}`);
-  }
-}
+    async add(content, opts) {
+      const args = ["add", content];
+      if (opts?.type) args.push("--type", opts.type);
+      if (opts?.title) args.push("--title", opts.title);
+      if (opts?.tags) args.push("--tags", opts.tags.join(","));
 
-export async function brainValidate(): Promise<string> {
-  const result = await execBrain(["validate"]);
-  if (result.exitCode !== 0) {
-    throw new Error(`brain validate failed: ${result.stderr}`);
-  }
-  return result.stdout;
+      const result = await execBrain(args);
+      if (result.exitCode !== 0) {
+        throw new Error(`brain add failed: ${result.stderr}`);
+      }
+    },
+
+    async index(opts) {
+      const args = ["index"];
+      // Full rebuild; indexing is incremental by default since brain 22e82e1.
+      if (opts?.force) args.push("--force");
+
+      const result = await execBrain(args);
+      if (result.exitCode !== 0) {
+        throw new Error(`brain index failed: ${result.stderr}`);
+      }
+    },
+
+    async validate() {
+      const result = await execBrain(["validate"]);
+      if (result.exitCode !== 0) {
+        throw new Error(`brain validate failed: ${result.stderr}`);
+      }
+      return result.stdout;
+    },
+  };
 }