@schlessera/brain-ui-server 0.16.0 → 0.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@schlessera/brain-ui-server",
-  "version": "0.16.0",
+  "version": "0.18.0",
   "description": "brain-kit chat-UI server: Hono app factory, WebSocket turn coordinator, auth (password/passkeys/tailscale/proxy), session catalog, and brain/files/voice routes",
   "license": "MIT",
   "keywords": [
@@ -23,7 +23,7 @@
     "access": "public"
   },
   "engines": {
-    "bun": ">=1.3.0"
+    "bun": ">=1.3.5"
   },
   "sideEffects": false,
   "type": "module",
@@ -32,7 +32,8 @@
       "bun": "./src/index.ts",
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
-    }
+    },
+    "./package.json": "./package.json"
   },
   "files": [
     "src",
@@ -41,14 +42,14 @@
     "README.md"
   ],
   "scripts": {
-    "test": "bun test tests",
+    "test": "bun test tests --timeout 30000",
     "prepublishOnly": "bun ../../scripts/check-dist.ts"
   },
   "dependencies": {
     "@opentelemetry/api": "^1.9.1",
     "@opentelemetry/api-logs": "0.221.0",
-    "@schlessera/brain-render-template": "0.16.0",
-    "@schlessera/brain-ui-sdk": "0.16.0",
+    "@schlessera/brain-render-template": "0.18.0",
+    "@schlessera/brain-ui-sdk": "0.18.0",
     "@simplewebauthn/server": "^13.3.2",
     "hono": "^4",
     "ignore": "^7.0.5",

package/src/agent/backend.ts

@@ -14,7 +14,7 @@ import type {
  * tests install fakes by constructing a registry, not by mutating a module.
  *
  * BOTH backend packages are optional peers loaded lazily (the same
- * `createRequire` path): a deployment installs the one its AGENT_BACKEND
+ * dynamic-import path): a deployment installs the one its AGENT_BACKEND
  * names, and the other never has to be present — at runtime AND at
  * type-check time (see the structural mirrors below).
  *
@@ -48,6 +48,33 @@ import type {
  * incompatible drift slide.
  */
 
+/**
+ * Mirror of the backends' `BackendLogFn` — the minimal log seam a backend
+ * accepts. A callback rather than a Logger so the backend packages carry no
+ * telemetry dependency; {@link toBackendLog} adapts the registry's Logger.
+ */
+export type BackendLogFn = (
+  level: "debug" | "info" | "warn" | "error",
+  message: string,
+  attrs?: Record<string, string | number | boolean>
+) => void;
+
+const LEVEL_SEVERITY = {
+  debug: "DEBUG",
+  info: "INFO",
+  warn: "WARN",
+  error: "ERROR",
+} as const;
+
+function toBackendLog(log: Logger): BackendLogFn {
+  return (level, message, attrs) =>
+    log.emit({
+      severityText: LEVEL_SEVERITY[level],
+      body: message,
+      ...(attrs ? { attributes: attrs } : {}),
+    });
+}
+
 /** Mirror of the Claude package's `InferenceProfileInput` (declarative shape). */
 export interface ClaudeProfileInput {
   id: string;
@@ -95,6 +122,8 @@ export interface ClaudeBackendModule {
     brainPath: string;
     claudeCodePath?: string;
     profiles?: ClaudeProfile[] | (() => ClaudeProfile[]);
+    confirmBashPatterns?: readonly string[];
+    log?: BackendLogFn;
   }) => AgentBackend;
   createModelSource: (options: {
     brainPath: string;
@@ -146,6 +175,12 @@ export interface BackendRegistryOptions {
    * sessions pinned to it. Defaults to "nothing hidden".
    */
   getHiddenModelIds?: () => string[];
+  /**
+   * Where the registry and its backends report. Adapted to the backends'
+   * minimal callback ({@link BackendLogFn}) before crossing the package
+   * boundary. Absent means silence.
+   */
+  log?: Logger;
 }
 
 export interface BackendRegistry {
@@ -258,6 +293,59 @@ function missingBackendError(primary: "claude" | "pi"): Error {
  * The `resolve` parameter exists for tests (simulating an absent package);
  * production callers pass nothing.
  */
+/** The specifier an ERR_MODULE_NOT_FOUND failed on, or null for any other error. */
+function moduleNotFoundSpecifier(error: unknown): string | null {
+  if (typeof error !== "object" || error === null) return null;
+  const { code, specifier, message } = error as {
+    code?: unknown;
+    specifier?: unknown;
+    message?: unknown;
+  };
+  if (code !== "ERR_MODULE_NOT_FOUND" && code !== "MODULE_NOT_FOUND") return null;
+  // Bun's ResolveMessage (not an Error instance) carries the failing
+  // specifier as a property; Node quotes it in the message instead.
+  if (typeof specifier === "string") return specifier;
+  if (typeof message === "string") {
+    const quoted = /Cannot find (?:package|module) '([^']+)'/.exec(message);
+    if (quoted) return quoted[1];
+  }
+  return null;
+}
+
+/**
+ * Load an optional backend package, mapping ONLY "the backend package itself
+ * is not installed" to the actionable install hint. Everything else — the
+ * backend missing one of its OWN transitive deps, a syntax error, a throwing
+ * top-level — is a different failure whose original error IS the diagnostic,
+ * so it is rethrown untouched. The distinction rides on ERR_MODULE_NOT_FOUND
+ * naming the specifier it failed on: a transitive miss names the transitive
+ * dep, not the backend, and must not read as "backend not installed".
+ *
+ * `await import()` rather than `createRequire()(...)`: the backend packages
+ * are ESM, and a CJS require of them under plain Node dies with
+ * ERR_REQUIRE_ESM — which the old blanket catch then reported as "not
+ * installed" on a machine where the package was sitting right there.
+ *
+ * The `importer` parameter exists for tests (simulating absent or broken
+ * packages); production callers pass nothing.
+ */
+export async function loadBackendModule(
+  // "claude" | "pi" spelled out, NOT keyof typeof BACKEND_SPECIFIERS: the
+  // keyof form drags the table's literal string types — the backend
+  // specifiers — into the emitted .d.ts, which the declaration-surface gate
+  // rightly refuses.
+  key: "claude" | "pi",
+  importer: (specifier: string) => Promise<unknown> = (specifier) => import(specifier)
+): Promise<unknown> {
+  const specifier = BACKEND_SPECIFIERS[key];
+  try {
+    return await importer(specifier);
+  } catch (error) {
+    if (moduleNotFoundSpecifier(error) === specifier) throw missingBackendError(key);
+    throw error;
+  }
+}
+
 export function assertBackendResolvable(
   agent: AgentConfig,
   resolve: (specifier: string) => void = (specifier) => {
@@ -279,6 +367,7 @@ export function createBackendRegistry(
 ): BackendRegistry {
   const { brainPath, agent } = options;
   const getHidden = options.getHiddenModelIds ?? (() => []);
+  const backendLog = options.log ? toBackendLog(options.log) : undefined;
 
   let cachedRegistry: Promise<RegistrySnapshot> | null = null;
   let modelSource: ClaudeModelSource | null = null;
@@ -392,18 +481,12 @@ export function createBackendRegistry(
   /**
    * NEITHER backend package is a hard dependency — a deployment installs the
    * one its AGENT_BACKEND names (both, if it switches). Loaded lazily through
-   * the same `createRequire` path so the server still boots without the unused
-   * one; when the configured backend's package is absent, fail with an
-   * actionable message.
+   * {@link loadBackendModule} so the server still boots without the unused
+   * one; only "the package is absent" maps to the actionable install hint,
+   * any other load failure surfaces as itself.
    */
-  function buildClaudeBackend(): AgentBackend {
-    const require = createRequire(import.meta.url);
-    let claude: ClaudeBackendModule;
-    try {
-      claude = require("@schlessera/brain-backend-claude");
-    } catch {
-      throw missingBackendError("claude");
-    }
+  async function buildClaudeBackend(): Promise<AgentBackend> {
+    const claude = (await loadBackendModule("claude")) as ClaudeBackendModule;
     if (typeof claude.createClaudeBackend !== "function") {
       throw new Error(
         '"@schlessera/brain-backend-claude" does not export createClaudeBackend.'
@@ -423,6 +506,12 @@ export function createBackendRegistry(
     return claude.createClaudeBackend({
       brainPath,
       claudeCodePath: agent.claudeCodePath,
+      ...(backendLog ? { log: backendLog } : {}),
+      // Omitted entirely when unconfigured, so the backend's own defaults
+      // apply; an explicit [] passes through and disables confirmation.
+      ...(agent.confirmBashPatterns !== null
+        ? { confirmBashPatterns: agent.confirmBashPatterns }
+        : {}),
       // A function, not an array: discovery refreshes in the background and the
       // new roster has to be visible without restarting the process.
       profiles: () =>
@@ -430,31 +519,30 @@ export function createBackendRegistry(
     });
   }
 
-  function buildPiBackend(): AgentBackend {
-    const require = createRequire(import.meta.url);
-    let mod: { createPiBackend?: (opts: { brainPath: string }) => AgentBackend };
-    try {
-      mod = require("@schlessera/brain-backend-pi");
-    } catch {
-      throw missingBackendError("pi");
-    }
+  async function buildPiBackend(): Promise<AgentBackend> {
+    const mod = (await loadBackendModule("pi")) as {
+      createPiBackend?: (opts: { brainPath: string; log?: BackendLogFn }) => AgentBackend;
+    };
     if (typeof mod.createPiBackend !== "function") {
       throw new Error(
         '"@schlessera/brain-backend-pi" does not export createPiBackend.'
       );
     }
-    return mod.createPiBackend({ brainPath });
+    return mod.createPiBackend({
+      brainPath,
+      ...(backendLog ? { log: backendLog } : {}),
+    });
   }
 
   async function buildRegistry(): Promise<RegistrySnapshot> {
     const primary = agent.backend || "claude";
 
     if (primary === "pi") {
-      const pi = buildPiBackend();
+      const pi = await buildPiBackend();
       return buildSnapshot([pi], pi.id);
     }
 
-    const backends = [buildClaudeBackend()];
+    const backends = [await buildClaudeBackend()];
 
     // AGENT_BACKEND must name a configured backend. The in-process options are
     // "claude" (default) and "pi" (handled above). An unrecognized value is a
@@ -471,10 +559,15 @@ export function createBackendRegistry(
     return cachedRegistry;
   }
 
-  return makeRegistry(getRegistry, getHidden, async () => {
-    await getRegistry();
-    return modelSource;
-  });
+  return makeRegistry(
+    getRegistry,
+    getHidden,
+    async () => {
+      await getRegistry();
+      return modelSource;
+    },
+    options.log
+  );
 }
 
 /**
@@ -486,13 +579,14 @@ export function createBackendRegistry(
 export function createStaticBackendRegistry(
   backends: AgentBackend[],
   defaultBackendId = backends[0]?.id ?? "",
-  options: { getHiddenModelIds?: () => string[] } = {}
+  options: { getHiddenModelIds?: () => string[]; log?: Logger } = {}
 ): BackendRegistry {
   const snapshot = buildSnapshot(backends, defaultBackendId);
   return makeRegistry(
     async () => snapshot,
     options.getHiddenModelIds ?? (() => []),
-    async () => null
+    async () => null,
+    options.log
   );
 }
 

package/src/app.ts

@@ -1,12 +1,11 @@
 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 { resolveServerConfig, type ServerConfig } from "./config/env.js";
-import { healthRoutes, createStatusRoutes } from "./routes/health.js";
+import { createHealthRoutes, createStatusRoutes } from "./routes/health.js";
 import { createBrainRoutes } from "./routes/brain.js";
 import { createSessionRoutes } from "./routes/sessions.js";
 import { createVoiceRoutes } from "./routes/voice.js";
@@ -168,7 +167,8 @@ export function createApp(options: CreateAppOptions = {}): BrainUiApp {
   // 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, { log: observability.logger("db") });
+  const dbLog = observability.logger("db");
+  const db = createUiDb(config.dbPath, { log: dbLog });
   const brain = createBrainClient({ brainPath: config.brainPath });
   const cron = createCronScheduler({ db, brain, log: observability.logger("cron") });
   const registry =
@@ -176,36 +176,63 @@ export function createApp(options: CreateAppOptions = {}): BrainUiApp {
     createBackendRegistry({
       brainPath: config.brainPath,
       agent: config.agent,
-      getHiddenModelIds: () => getHiddenModelIds(db),
+      getHiddenModelIds: () => getHiddenModelIds(db, dbLog),
+      log: observability.logger("agent"),
     });
   const host = new WsHost({
     registry,
     observability,
-    catalog: createSessionCatalog(() => db),
+    catalog: createSessionCatalog(() => db, dbLog),
     ...(options.appName ? { appName: options.appName } : {}),
-    ...(options.turnTimeoutMs ? { turnTimeoutMs: options.turnTimeoutMs } : {}),
+    // Explicit option wins; then the env-resolved config; then the host default.
+    ...(options.turnTimeoutMs ?? config.turnTimeoutMs
+      ? { turnTimeoutMs: (options.turnTimeoutMs ?? config.turnTimeoutMs)! }
+      : {}),
     maxConcurrentSessions: () => config.maxConcurrentSessions,
     wsRate: config.wsRate,
   });
   const wsUpgrade = createWsUpgrade(host);
+  // One instrument for every way a login can fail — passkey ceremonies and
+  // password logins land in the same series, split by attributes.
+  const authFailures = observability.meter("auth").createCounter("auth.failures", {
+    description: "Failed authentication ceremonies, by reason",
+  });
   const passkeyCtx: PasskeyContext = {
     db,
     webauthn: config.webauthn,
     auth,
     allowedOrigins: config.allowedOrigins,
     log: observability.logger("passkeys"),
-    failures: observability.meter("auth").createCounter("auth.failures", {
-      description: "Failed authentication ceremonies, by reason",
-    }),
+    failures: authFailures,
   };
   const keyterms: KeytermSettings = {
     brainPath: config.brainPath,
     cacheDir: config.voice.cacheDir,
     limit: config.voice.keytermLimit,
+    log: observability.logger("voice"),
   };
 
-  // Middleware
-  app.use("*", logger());
+  // Request logging through the observability layer, so BRAIN_UI_LOG_LEVEL
+  // governs it like every other emission (hono's logger() wrote raw console
+  // lines no threshold or consumer swap could touch). Path only — never the
+  // query string or body. /api/health is skipped: the Docker healthcheck
+  // polls it and would drown everything else out.
+  const httpLog = observability.logger("http");
+  app.use("*", async (c, next) => {
+    if (c.req.path === "/api/health") return next();
+    const startedAt = Date.now();
+    await next();
+    httpLog.emit({
+      severityText: "INFO",
+      body: "request",
+      attributes: {
+        method: c.req.method,
+        path: c.req.path,
+        status: c.res.status,
+        "duration.ms": Date.now() - startedAt,
+      },
+    });
+  });
 
   // CORS is only needed for a SPLIT topology where the client is served from a
   // different origin than the API. ALLOWED_ORIGINS is a comma-separated
@@ -228,7 +255,7 @@ export function createApp(options: CreateAppOptions = {}): BrainUiApp {
   // probe and the login/logout routes are reachable without a session.
   // /api/status is intentionally NOT here — it leaks the git SHA, cron errors,
   // and a session oracle, so it lives behind the guard below.
-  app.route("/api", healthRoutes);
+  app.route("/api", createHealthRoutes({ db }));
   // 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);
@@ -236,6 +263,8 @@ export function createApp(options: CreateAppOptions = {}): BrainUiApp {
     "/api",
     authRoutes(authMode, auth, {
       passwordDisabled: (c) => passwordLoginDisabled(c, passkeyCtx),
+      log: authLog,
+      failures: authFailures,
     })
   );
   app.route("/api", passkeyPublicRoutes(authMode, passkeyCtx));
@@ -265,15 +294,28 @@ export function createApp(options: CreateAppOptions = {}): BrainUiApp {
   );
   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 })
+    createFilesRoutes({ brainRoot: config.brainPath, log: observability.logger("files") })
+  );
+  app.route(
+    "/api",
+    createShareRoutes({
+      brainRoot: config.brainPath,
+      allowedOrigins,
+      log: observability.logger("share"),
+    })
   );
-  app.route("/api", createRenderRoutes(options.renderer));
+  app.route("/api", createRenderRoutes(options.renderer, observability.logger("render")));
   app.route("/api", createProviderRoutes({ registry }));
-  app.route("/api", createModelRoutes({ registry, db }));
-  app.route("/api", createGraphRoutes({ brainRoot: config.brainPath }));
+  app.route(
+    "/api",
+    createModelRoutes({ registry, db, log: observability.logger("models") })
+  );
+  app.route(
+    "/api",
+    createGraphRoutes({ brainRoot: config.brainPath, log: observability.logger("graph") })
+  );
 
   // WebSocket endpoint. Browsers can't set headers on the WS handshake, so the
   // upgrade authenticates via the session cookie (or IP/proxy header) INSIDE

package/src/config/env-core.ts

@@ -0,0 +1,93 @@
+/**
+ * Shared core of every package's environment chokepoint — a SYNC-ENFORCED
+ * COPY, not a package.
+ *
+ * This file exists byte-identically as `src/config/env-core.ts` in every
+ * package that has an env chokepoint (`src/config/env.ts`), and the root test
+ * `tests/env-core-sync.test.ts` fails the build when any copy differs. To
+ * change it: edit ONE copy, copy the file verbatim into every package that
+ * has one (each `src/config/env-core.ts`), and rerun the sync test.
+ *
+ * Why a copy and not a `@schlessera/brain-env` package: the repo adds a seam
+ * only where a second implementation is plausible (docs/extending/README.md),
+ * and a new package for four fields and three small functions would churn the
+ * release manifest and every dependent's dependency list. Byte-equality
+ * enforced by a test gives the same single-source-of-truth guarantee without
+ * the edge. (`scripts/env-docs.ts` imports the canonical copy in
+ * `packages/core` directly — it is a root script, not published code.)
+ *
+ * What belongs here: the descriptor contract the env-docs generator and the
+ * env-parity gate consume, the dynamic-read escape hatch, and the boolean
+ * parsing helpers. What does NOT belong here: `resolveEnv` — each package's
+ * resolver reads its own variables into its own shape and stays in that
+ * package's `env.ts`.
+ */
+
+/** One environment variable a package reads. */
+export interface EnvVarSpec {
+  /** Variable name as it appears in the environment. */
+  name: string;
+  /** What it controls. */
+  description: string;
+  /**
+   * Behaviour when the variable is unset. Omitted or null when there is no
+   * meaningful default to state.
+   */
+  default?: string | null;
+  /**
+   * `true` when the package cannot do its job at all without it, `false`
+   * when optional; a string states the CONDITION under which it becomes
+   * required (e.g. "AUTH_MODE=password") — flattening that to a boolean
+   * would lose the only part a reader needs.
+   */
+  required: boolean | string;
+}
+
+/** A family of reads whose variable NAME is data, not code. */
+export interface DynamicEnvReadSpec {
+  /** Where the variable name comes from. */
+  source: string;
+  /** What the value is used for. */
+  description: string;
+}
+
+/**
+ * Call-time read of a single variable whose name is data (see the package's
+ * `DYNAMIC_ENV_READS`) or whose presence gates a feature. Never cache the
+ * result at module scope.
+ */
+export function readEnvVar(
+  name: string,
+  env: NodeJS.ProcessEnv = process.env
+): string | undefined {
+  return env[name];
+}
+
+const TRUTHY_TOKENS: readonly string[] = ["1", "true", "on", "yes"];
+const FALSY_TOKENS: readonly string[] = ["0", "false", "off", "no"];
+
+/**
+ * The one way a token-valued boolean environment variable is parsed.
+ *
+ * Truthy: 1 / true / on / yes. Falsy: 0 / false / off / no. Matching is
+ * case-insensitive after trimming. Unset, empty, or any unrecognised token
+ * returns `defaultValue` — a typo in a flag must never silently flip a
+ * behaviour; it falls back to the documented default instead.
+ */
+export function envFlag(value: string | undefined, defaultValue: boolean): boolean {
+  if (value === undefined) return defaultValue;
+  const token = value.trim().toLowerCase();
+  if (TRUTHY_TOKENS.includes(token)) return true;
+  if (FALSY_TOKENS.includes(token)) return false;
+  return defaultValue;
+}
+
+/**
+ * Presence-based boolean: set to ANY non-empty value means on. This is the
+ * `NO_COLOR` convention (https://no-color.org) — `NO_COLOR=0` still disables
+ * color — so it must NOT go through `envFlag`. Use only for variables whose
+ * documented contract is presence, not a token.
+ */
+export function envPresent(value: string | undefined): boolean {
+  return value !== undefined && value !== "";
+}