@schlessera/brain-ui-server 0.15.0 → 0.17.0

package/src/routes/brain.ts

@@ -118,6 +118,15 @@ export function createBrainRoutes(deps: BrainRoutesDeps): Hono {
           env: subprocessEnv({ NO_COLOR: "1" }),
         });
 
+        // Start draining stderr NOW, not after the process exits.
+        //
+        // The stdout loop below can run for minutes. Meanwhile stderr fills an
+        // OS pipe buffer that nothing is reading — and once it is full the
+        // child blocks on write, never exits, and `await proc.exited` never
+        // resolves. A chatty run deadlocked the request; a quiet one looked
+        // fine, which is why this survived.
+        const stderrText = new Response(proc.stderr).text();
+
         const reader = proc.stdout.getReader();
         const decoder = new TextDecoder();
         let buffer = "";
@@ -139,7 +148,7 @@ export function createBrainRoutes(deps: BrainRoutesDeps): Hono {
 
         const exitCode = await proc.exited;
 
-        const stderr = await new Response(proc.stderr).text();
+        const stderr = await stderrText;
         if (stderr.trim()) {
           for (const line of stderr.split("\n")) {
             if (line.trim()) await send({ type: "progress", text: line });

package/src/routes/files.ts

@@ -1,3 +1,4 @@
+import type { Logger } from "@opentelemetry/api-logs";
 import { Hono } from "hono";
 import {
   listDirectory,
@@ -12,7 +13,7 @@ import {
 
 const WIKILINK_TTL_MS = 30_000;
 
-function errorResponse(err: unknown): { body: { error: string; size?: number }; status: 400 | 404 | 413 | 500 } {
+function errorResponse(err: unknown, log?: Logger): { body: { error: string; size?: number }; status: 400 | 404 | 413 | 500 } {
   if (err instanceof PathEscapeError) {
     return { body: { error: "invalid_path" }, status: 400 };
   }
@@ -22,12 +23,12 @@ function errorResponse(err: unknown): { body: { error: string; size?: number };
   if (err instanceof TooLargeError) {
     return { body: { error: "file_too_large", size: err.size }, status: 413 };
   }
-  console.error("[files]", err);
+  log?.emit({ severityText: "ERROR", body: "file request failed", attributes: { error: err instanceof Error ? err.message : String(err) } });
   return { body: { error: err instanceof Error ? err.message : "internal_error" }, status: 500 };
 }
 
-export function createFilesRoutes(deps: { brainRoot: string }): Hono {
-  const { brainRoot } = deps;
+export function createFilesRoutes(deps: { brainRoot: string; log?: Logger }): Hono {
+  const { brainRoot, log } = deps;
   let wikilinkCache: { generatedAt: number; map: Record<string, string> } | null = null;
   return new Hono()
   .get("/files/tree", async (c) => {
@@ -36,7 +37,7 @@ export function createFilesRoutes(deps: { brainRoot: string }): Hono {
       const entries = await listDirectory(path, brainRoot);
       return c.json({ path, entries });
     } catch (err) {
-      const { body, status } = errorResponse(err);
+      const { body, status } = errorResponse(err, log);
       return c.json(body, status);
     }
   })
@@ -64,7 +65,7 @@ export function createFilesRoutes(deps: { brainRoot: string }): Hono {
       const result = await readFileContent(path, brainRoot);
       return c.json({ path, ...result });
     } catch (err) {
-      const { body, status } = errorResponse(err);
+      const { body, status } = errorResponse(err, log);
       return c.json(body, status);
     }
   })
@@ -76,7 +77,7 @@ export function createFilesRoutes(deps: { brainRoot: string }): Hono {
       const result = await resolveAncestors(path, brainRoot);
       return c.json({ path, ...result });
     } catch (err) {
-      const { body, status } = errorResponse(err);
+      const { body, status } = errorResponse(err, log);
       return c.json(body, status);
     }
   })
@@ -95,7 +96,7 @@ export function createFilesRoutes(deps: { brainRoot: string }): Hono {
         slugs: wikilinkCache.map,
       });
     } catch (err) {
-      const { body, status } = errorResponse(err);
+      const { body, status } = errorResponse(err, log);
       return c.json(body, status);
     }
   });

package/src/routes/graph.ts

@@ -1,3 +1,4 @@
+import type { Logger } from "@opentelemetry/api-logs";
 import { Hono } from "hono";
 import {
   DEFAULT_STALE_DAYS,
@@ -18,7 +19,7 @@ import {
  * subgraph endpoints instead refuse with 503 rather than returning an empty
  * graph that would read as "your repo has no links".
  */
-function errorResponse(err: unknown): {
+function errorResponse(err: unknown, log?: Logger): {
   body: { error: string; reason?: string; param?: string };
   status: 400 | 404 | 503 | 500;
 } {
@@ -28,7 +29,7 @@ function errorResponse(err: unknown): {
   if (err instanceof GraphNotFoundError) {
     return { body: { error: "not_found" }, status: 404 };
   }
-  console.error("[graph]", err);
+  log?.emit({ severityText: "ERROR", body: "graph request failed", attributes: { error: err instanceof Error ? err.message : String(err) } });
   return { body: { error: err instanceof Error ? err.message : "internal_error" }, status: 500 };
 }
 
@@ -49,8 +50,8 @@ function invalid(param: string) {
   return { error: "invalid_param", param } as const;
 }
 
-export function createGraphRoutes(deps: { brainRoot: string }): Hono {
-  const { brainRoot } = deps;
+export function createGraphRoutes(deps: { brainRoot: string; log?: Logger }): Hono {
+  const { brainRoot, log } = deps;
   return new Hono()
   .get("/graph/meta", (c) => c.json(getGraphMeta({ brainPath: brainRoot })))
 
@@ -65,7 +66,7 @@ export function createGraphRoutes(deps: { brainRoot: string }): Hono {
     try {
       return c.json(getClusters({ brainPath: brainRoot, community, includeIsolates: c.req.query("isolates") === "1" }));
     } catch (err) {
-      const { body, status } = errorResponse(err);
+      const { body, status } = errorResponse(err, log);
       return c.json(body, status);
     }
   })
@@ -81,7 +82,7 @@ export function createGraphRoutes(deps: { brainRoot: string }): Hono {
     try {
       return c.json(getNeighborhood({ brainPath: brainRoot, center, depth, direction }));
     } catch (err) {
-      const { body, status } = errorResponse(err);
+      const { body, status } = errorResponse(err, log);
       return c.json(body, status);
     }
   })
@@ -96,7 +97,7 @@ export function createGraphRoutes(deps: { brainRoot: string }): Hono {
     try {
       return c.json(getDiscovery({ brainPath: brainRoot, root, direction, maxDepth }));
     } catch (err) {
-      const { body, status } = errorResponse(err);
+      const { body, status } = errorResponse(err, log);
       return c.json(body, status);
     }
   })
@@ -108,7 +109,7 @@ export function createGraphRoutes(deps: { brainRoot: string }): Hono {
     try {
       return c.json(getMaintenance({ brainPath: brainRoot, staleDays }));
     } catch (err) {
-      const { body, status } = errorResponse(err);
+      const { body, status } = errorResponse(err, log);
       return c.json(body, status);
     }
   });

package/src/routes/health.ts

@@ -1,23 +1,43 @@
 import { Hono } from "hono";
+import type { Database } from "bun:sqlite";
+
+import type { MetricSnapshot } from "../observability/index.js";
 
 const startTime = Date.now();
 
 // Public liveness probe. Deliberately minimal: no version/commit, no cron
 // detail, no session oracle — this route sits in front of the auth guard and
 // is reachable by anyone on the origin.
-export const healthRoutes = new Hono().get("/health", (c) => {
-  return c.json({
-    status: "healthy",
-    uptime: Date.now() - startTime,
-    timestamp: new Date().toISOString(),
+//
+// "Healthy" means the app's own SQLite handle answers a real read, not merely
+// that the process accepts connections: the Docker healthcheck gates on this
+// route, and a wedged database previously kept reporting healthy while every
+// stateful route failed. The probe reads sqlite_master rather than a bare
+// SELECT 1 — a constant expression touches no page of the database file, so it
+// cannot notice a locked or corrupted one. The unhealthy body carries no
+// detail — the route is public.
+export function createHealthRoutes(deps: { db: Database }): Hono {
+  return new Hono().get("/health", (c) => {
+    try {
+      deps.db.query("SELECT name FROM sqlite_master LIMIT 1").get();
+    } catch {
+      return c.json({ status: "unhealthy" }, 503);
+    }
+    return c.json({
+      status: "healthy",
+      uptime: Date.now() - startTime,
+      timestamp: new Date().toISOString(),
+    });
   });
-});
+}
 
 export interface StatusDeps {
   /** Git SHA baked at build time (SOURCE_COMMIT), "dev" when unset. */
   sourceCommit: string;
   getCronStatus(): unknown;
   isTurnActive(): boolean;
+  /** Recorded counters; undefined when the consumer cannot be read back. */
+  getMetrics?(): MetricSnapshot | undefined;
 }
 
 // Operational status. Registered BEHIND the auth guard: it exposes the git SHA,
@@ -31,6 +51,9 @@ export function createStatusRoutes(deps: StatusDeps): Hono {
       version: deps.sourceCommit,
       cronJobs: deps.getCronStatus(),
       activeSession: deps.isTurnActive(),
+      // Counters the server recorded this process lifetime — dropped frames,
+      // handler failures. Behind the auth guard with everything else here.
+      metrics: deps.getMetrics?.() ?? [],
     });
   });
 }

package/src/routes/models.ts

@@ -5,6 +5,7 @@
 // with its visibility, plus discovery freshness so the UI can say when the list
 // was last refreshed and why it might be stale.
 
+import type { Logger } from "@opentelemetry/api-logs";
 import { Hono } from "hono";
 import type { Database } from "bun:sqlite";
 import type {
@@ -17,6 +18,8 @@ import { getHiddenModelIds, setHiddenModelIds } from "../db/settings.js";
 export function createModelRoutes(deps: {
   registry: BackendRegistry;
   db: Database;
+  /** Where refresh failures are reported. */
+  log?: Logger;
 }): Hono {
   const { registry, db } = deps;
 
@@ -77,11 +80,11 @@ export function createModelRoutes(deps: {
     } catch (err) {
       // The previous roster is still served; report the failure in the payload
       // rather than 500ing, so the settings screen can show it inline.
-      console.warn(
-        `[models] Refresh failed: ${
-          err instanceof Error ? err.message : String(err)
-        }`
-      );
+      deps.log?.emit({
+        severityText: "WARN",
+        body: "model roster refresh failed; serving the previous roster",
+        attributes: { error: err instanceof Error ? err.message : String(err) },
+      });
     }
     registry.invalidateProfiles();
     return c.json(await buildCatalog());

package/src/routes/render.ts

@@ -1,3 +1,4 @@
+import type { Logger } from "@opentelemetry/api-logs";
 import { Hono } from "hono";
 import { z } from "zod";
 import type { RenderRequest } from "@schlessera/brain-ui-sdk/protocol";
@@ -30,7 +31,7 @@ const bodySchema = z.object({
   title: z.string().max(200).optional(),
 }) satisfies z.ZodType<RenderRequest>;
 
-export function createRenderRoutes(renderer?: AppRenderer) {
+export function createRenderRoutes(renderer?: AppRenderer, log?: Logger) {
   return new Hono().post("/render", async (c) => {
     if (!renderer) {
       return c.json(
@@ -65,7 +66,7 @@ export function createRenderRoutes(renderer?: AppRenderer) {
         },
       });
     } catch (err) {
-      console.error("[render]", err);
+      log?.emit({ severityText: "ERROR", body: "render failed", attributes: { error: err instanceof Error ? err.message : String(err) } });
       return c.json(
         { error: "render_failed", detail: err instanceof Error ? err.message : String(err) },
         500

package/src/routes/share.ts

@@ -1,3 +1,4 @@
+import type { Logger } from "@opentelemetry/api-logs";
 import { Hono } from "hono";
 import {
   SHARE_MAX_CONCURRENT_INTAKE,
@@ -93,10 +94,12 @@ export interface ShareRoutesDeps {
   brainRoot: string;
   /** ALLOWED_ORIGINS — the same-origin check's split-topology allowlist. */
   allowedOrigins: string[];
+  /** Where failures are reported; absent means silence. */
+  log?: Logger;
 }
 
 export function createShareRoutes(deps: ShareRoutesDeps): Hono {
-  const { brainRoot, allowedOrigins } = deps;
+  const { brainRoot, allowedOrigins, log } = deps;
 
   /**
    * In-flight intakes. Each one holds its whole payload in memory while the
@@ -115,8 +118,8 @@ export function createShareRoutes(deps: ShareRoutesDeps): Hono {
     lastPrune = now;
     // Deliberately not awaited: pruning is housekeeping, and the client is
     // waiting on the staging result, not on it.
-    void pruneShareStaging(brainRoot).catch((err) => {
-      console.error("[share] prune failed:", err);
+    void pruneShareStaging(brainRoot, Date.now(), log).catch((err) => {
+      log?.emit({ severityText: "ERROR", body: "share staging prune failed", attributes: { error: err instanceof Error ? err.message : String(err) } });
     });
   }
 
@@ -164,12 +167,16 @@ export function createShareRoutes(deps: ShareRoutesDeps): Hono {
 
   inFlight += 1;
   try {
-    const result = await stageShare(brainRoot, {
-      title: firstString(form, "title"),
-      text: firstString(form, "text"),
-      url: firstString(form, "url"),
-      files,
-    });
+    const result = await stageShare(
+      brainRoot,
+      {
+        title: firstString(form, "title"),
+        text: firstString(form, "text"),
+        url: firstString(form, "url"),
+        files,
+      },
+      log
+    );
 
     maybePrune();
     return c.json(result, 201);
@@ -180,7 +187,7 @@ export function createShareRoutes(deps: ShareRoutesDeps): Hono {
     if (err instanceof ShareTooLargeError) {
       return c.json({ error: err.reason, limit: err.limit }, 413);
     }
-    console.error("[share]", err);
+    log?.emit({ severityText: "ERROR", body: "share request failed", attributes: { error: err instanceof Error ? err.message : String(err) } });
     return c.json({ error: "share_failed" }, 500);
   } finally {
     inFlight -= 1;

package/src/share/staging.ts

@@ -1,3 +1,4 @@
+import type { Logger } from "@opentelemetry/api-logs";
 import { mkdir, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import {
@@ -271,7 +272,8 @@ async function countStaged(root: string): Promise<number> {
  */
 export async function stageShare(
   brainPath: string,
-  input: ShareInput
+  input: ShareInput,
+  log?: Logger
 ): Promise<ShareIntakeResult> {
   const title = cleanTextField(input.title);
   const rawUrl = cleanTextField(input.url);
@@ -341,7 +343,11 @@ export async function stageShare(
         // One unwritable file (ENOSPC, a stricter filesystem) must not throw
         // away the other four. Record it and carry on; the share is only lost
         // if nothing at all survives.
-        console.error(`[share] could not stage ${name}:`, err);
+        log?.emit({
+          severityText: "ERROR",
+          body: "could not stage a shared file",
+          attributes: { name, error: err instanceof Error ? err.message : String(err) },
+        });
         skipped.push(name);
         continue;
       }
@@ -394,7 +400,11 @@ export async function stageShare(
  * deployment can sweep at boot too — scheduling belongs to the container
  * crontab, and this sweep is cheap and bounded.
  */
-export async function pruneShareStaging(brainPath: string, now = Date.now()): Promise<number> {
+export async function pruneShareStaging(
+  brainPath: string,
+  now = Date.now(),
+  log?: Logger
+): Promise<number> {
   const root = shareStagingRoot(brainPath);
   let entries;
   try {
@@ -404,7 +414,11 @@ export async function pruneShareStaging(brainPath: string, now = Date.now()): Pr
     // problem, a file where the directory should be — must not masquerade as
     // "nothing to do", or pruning stops forever and silently.
     if ((err as NodeJS.ErrnoException).code !== "ENOENT") {
-      console.error("[share] cannot read the staging root:", err);
+      log?.emit({
+        severityText: "ERROR",
+        body: "cannot read the share staging root",
+        attributes: { error: err instanceof Error ? err.message : String(err) },
+      });
     }
     return 0;
   }

package/src/voice/keyterm-builder.ts

@@ -1,3 +1,4 @@
+import type { Logger } from "@opentelemetry/api-logs";
 import type { Database } from "bun:sqlite";
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from "fs";
 import { join, dirname } from "path";
@@ -15,6 +16,8 @@ export interface KeytermSettings {
   cacheDir: string;
   /** Maximum vocabulary size (VOICE_KEYTERM_LIMIT). */
   limit: number;
+  /** Where degradation is reported; absent means silence. */
+  log?: Logger;
 }
 
 // Bump whenever the extractor logic, scoring, or stoplists change so that
@@ -359,7 +362,7 @@ function dedupeAndRank(terms: Keyterm[], limit: number): string[] {
   return sorted.slice(0, limit).map((k) => k.term);
 }
 
-export function loadOverrides(brainPath: string): PronunciationOverride[] {
+export function loadOverrides(brainPath: string, log?: Logger): PronunciationOverride[] {
   const path = overridesPath(brainPath);
   if (!existsSync(path)) return [];
   try {
@@ -375,13 +378,17 @@ export function loadOverrides(brainPath: string): PronunciationOverride[] {
     }
     return out;
   } catch (err) {
-    console.warn("[voice] Failed to load overrides:", err);
+    log?.emit({
+      severityText: "WARN",
+      body: "failed to load pronunciation overrides",
+      attributes: { error: err instanceof Error ? err.message : String(err) },
+    });
     return [];
   }
 }
 
 export function buildKeyterms(settings: KeytermSettings): KeytermsCache {
-  const { brainPath, limit } = settings;
+  const { brainPath, limit, log } = settings;
 
   try {
     return withBrainDb(brainPath, {}, (db) => {
@@ -398,7 +405,7 @@ export function buildKeyterms(settings: KeytermSettings): KeytermsCache {
         keyterms,
         generatedAt: Date.now(),
         count: keyterms.length,
-        overrides: loadOverrides(brainPath),
+        overrides: loadOverrides(brainPath, log),
       };
     });
   } catch (err) {
@@ -410,17 +417,19 @@ export function buildKeyterms(settings: KeytermSettings): KeytermsCache {
       // Schema too old for this package's SQL: degrade to no custom
       // vocabulary rather than breaking voice entirely. Pronunciation
       // overrides live in markdown, so they survive.
-      console.warn(
-        `[voice] brain.db schema_version=${err.schemaVersion} is older than this ` +
-          "server's keyterm SQL; serving an empty custom vocabulary until the " +
-          "repo is re-indexed."
-      );
+      log?.emit({
+        severityText: "WARN",
+        body:
+          "brain.db schema is older than this server's keyterm SQL; serving an " +
+          "empty custom vocabulary until the repo is re-indexed",
+        attributes: { "schema.version": err.schemaVersion },
+      });
       return {
         version: CACHE_VERSION,
         keyterms: [],
         generatedAt: Date.now(),
         count: 0,
-        overrides: loadOverrides(brainPath),
+        overrides: loadOverrides(brainPath, log),
         degraded: true,
       };
     }

package/src/ws/bridge.ts

@@ -23,10 +23,14 @@ export function makeBridge(
   // field would attribute those to the NEXT turn.
   const turnId = turn.turnId;
   return {
-    emit: (msg) => {
+    emit: (message) => {
+      let msg = message;
       if (msg.type === "session_info") {
         turn.sessionId = msg.sessionId;
         if (msg.providerId) turn.providerId = msg.providerId;
+        // Echo the client's correlation id, so it can recognise which
+        // announcement is its own rather than adopting the first to arrive.
+        if (turn.draftId) msg = { ...msg, draftId: turn.draftId };
         coordinator.bySession.set(msg.sessionId, turn);
         // Persist ownership the moment the identity exists — a turn that
         // later fails or is cancelled must not leave an unowned transcript.
@@ -34,6 +38,16 @@ export function makeBridge(
       }
       host.sendToClients(withTurnScope(msg, turn, turnId));
       if (msg.type === "result") {
+        // Only the live turn's own result may set its disposition — a late
+        // frame through a previous turn's bridge must not relabel this one.
+        if (turn.turnId === turnId) {
+          turn.lastResult =
+            msg.isError || msg.outcome === "error"
+              ? "error"
+              : msg.outcome === "cancelled"
+                ? "cancelled"
+                : "success";
+        }
         catalog.persistSession(msg, promptText, turn.providerId, backendId);
       }
     },
@@ -140,8 +154,10 @@ export function makeBridge(
 
 export function emitTurnError(host: WsHost, turn: RunningTurn, err: unknown): void {
   // startTurn resolves for runtime failures (it emits its own error frame); it
-  // only rejects for caller errors.
+  // only rejects for caller errors. Each rejection is reported server-side
+  // too — the frame alone leaves no trace once the browser tab is gone.
   if (err instanceof BackendBusyError) {
+    host.reportTurnFailed("SESSION_BUSY", turn);
     host.sendToClients(
       withTurnScope(
         { type: "error", code: "SESSION_BUSY", message: "That session already has a running turn." },
@@ -149,15 +165,15 @@ export function emitTurnError(host: WsHost, turn: RunningTurn, err: unknown): vo
       )
     );
   } else if (err instanceof BackendRequestError) {
+    host.reportTurnFailed("BACKEND_REQUEST_ERROR", turn, err.message);
     host.sendToClients(
       withTurnScope({ type: "error", code: "BACKEND_REQUEST_ERROR", message: err.message }, turn)
     );
   } else {
+    const message = err instanceof Error ? err.message : String(err);
+    host.reportTurnFailed("BACKEND_ERROR", turn, message);
     host.sendToClients(
-      withTurnScope(
-        { type: "error", code: "BACKEND_ERROR", message: err instanceof Error ? err.message : String(err) },
-        turn
-      )
+      withTurnScope({ type: "error", code: "BACKEND_ERROR", message }, turn)
     );
   }
 }

package/src/ws/clients.ts

@@ -1,8 +1,15 @@
 import type { ServerMessage } from "@schlessera/brain-ui-sdk/protocol";
 import { shrinkForReplication } from "./shrink.js";
 
-/** Minimal structural view of a live socket — all we need to write to it. */
-export type WSContext = { send: (data: string) => void };
+/**
+ * Minimal structural view of a live socket — all we need to write to it.
+ * `raw` is the underlying Bun ServerWebSocket when hono's Bun adapter built
+ * the context; its `send` RETURNS a status instead of throwing.
+ */
+export type WSContext = {
+  send: (data: string) => void;
+  raw?: { send?: (data: string) => number } | undefined;
+};
 
 /** Serialize + size-bound a frame, then send it to one specific socket. */
 export function sendTo(ws: WSContext, msg: ServerMessage): void {
@@ -38,16 +45,27 @@ export class ClientSet {
   /**
    * Broadcast a frame to every attached client. Serializes once. A failing
    * socket is skipped (its `onClose` will prune it) so one dead peer can't
-   * block delivery to the others.
+   * block delivery to the others; `onSendError` lets the owner count the skip.
    */
-  broadcast(msg: ServerMessage): void {
+  broadcast(msg: ServerMessage, onSendError?: (err: unknown) => void): void {
     if (this.clients.size === 0) return;
     const payload = JSON.stringify(shrinkForReplication(msg));
     for (const ws of this.clients) {
       try {
-        ws.send(payload);
-      } catch {
+        // Bun's ServerWebSocket reports a dropped write by RETURNING 0 (closed
+        // connection) rather than throwing, and hono's WSContext.send discards
+        // that status — so write through the raw socket where one exists. -1
+        // is backpressure: the frame is queued, not lost.
+        if (typeof ws.raw?.send === "function") {
+          if (ws.raw.send(payload) === 0) {
+            onSendError?.(new Error("send dropped: connection closed"));
+          }
+        } else {
+          ws.send(payload);
+        }
+      } catch (err) {
         // Drop; the socket's onClose handler removes it from the set.
+        onSendError?.(err);
       }
     }
   }