@schlessera/brain-ui-server 0.15.0 → 0.16.0

package/src/observability/types.ts

@@ -0,0 +1,101 @@
+/**
+ * Shapes the observability consumers expose for inspection.
+ *
+ * These exist so that "what did the server report?" is answerable as DATA — by
+ * a test, by `/api/status`, by a future exporter — rather than by scraping
+ * stdout. Every consumer in this directory implements a standard OpenTelemetry
+ * provider interface, so swapping one for another is an argument change and
+ * never a change to instrumentation.
+ */
+import type { Attributes } from "@opentelemetry/api";
+import type { LogRecord } from "@opentelemetry/api-logs";
+
+/**
+ * Attributes as this package retains them.
+ *
+ * Log attributes upstream are `AnyValue` — nested maps, arrays, null. Metric
+ * attributes are narrower. Both are normalized to scalars on capture so one
+ * query shape works over either, `/api/status` stays JSON-safe, and a
+ * formatted line never prints `[object Object]`.
+ */
+export type FlatAttributes = Record<string, string | number | boolean>;
+
+/** Coerce either attribute flavour to scalars, dropping empty values. */
+export function flattenAttributes(attributes: unknown): FlatAttributes {
+  const flat: FlatAttributes = {};
+  if (!attributes || typeof attributes !== "object") return flat;
+  for (const [key, value] of Object.entries(attributes as Record<string, unknown>)) {
+    if (value === undefined || value === null) continue;
+    if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+      flat[key] = value;
+    } else {
+      flat[key] = JSON.stringify(value);
+    }
+  }
+  return flat;
+}
+
+/** Severities this codebase uses, ordered. Anything below the configured
+ *  threshold is dropped by the console consumer before it is formatted. */
+export const SEVERITIES = ["TRACE", "DEBUG", "INFO", "WARN", "ERROR", "FATAL"] as const;
+export type Severity = (typeof SEVERITIES)[number];
+
+export function severityRank(severity: string | undefined): number {
+  const index = SEVERITIES.indexOf((severity ?? "INFO") as Severity);
+  return index === -1 ? SEVERITIES.indexOf("INFO") : index;
+}
+
+/** One emitted record, with the scope that produced it. */
+export interface CapturedLog {
+  /** Instrumentation scope — the `[ws]` / `[auth]` prefix this repo already uses. */
+  scope: string;
+  severity: Severity;
+  body: string;
+  attributes: FlatAttributes;
+  /** Wall clock at emit, in ms. */
+  timestamp: number;
+}
+
+/** A query over captured logs. Every field is an AND, every field optional. */
+export interface LogQuery {
+  scope?: string;
+  severity?: Severity;
+  /** Minimum severity, inclusive. */
+  minSeverity?: Severity;
+  /** Substring match against the body. */
+  body?: string;
+  /** Every listed attribute must be present and equal. */
+  attributes?: FlatAttributes;
+}
+
+/** One counter/histogram series: an instrument plus one attribute combination. */
+export interface MetricPoint {
+  name: string;
+  /** The attribute set that identifies this series. */
+  attributes: FlatAttributes;
+  /** Sum for counters, count of observations for histograms. */
+  value: number;
+  kind: "counter" | "updowncounter" | "histogram" | "gauge";
+}
+
+/** Serializable metric state, for `/api/status` and for assertions. */
+export type MetricSnapshot = MetricPoint[];
+
+/**
+ * Stable key for a series. Attributes are sorted, so two calls with the same
+ * attributes in a different literal order land on the same series.
+ */
+export function seriesKey(name: string, attributes: Attributes | undefined): string {
+  const entries = Object.entries(attributes ?? {})
+    .filter(([, v]) => v !== undefined)
+    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+    .map(([k, v]) => `${k}=${String(v)}`);
+  return entries.length ? `${name}|${entries.join(",")}` : name;
+}
+
+/** Convert a `LogRecord` body — typed as unknown-ish upstream — to a string. */
+export function bodyToString(body: LogRecord["body"]): string {
+  if (typeof body === "string") return body;
+  if (body === undefined || body === null) return "";
+  return typeof body === "object" ? JSON.stringify(body) : String(body);
+}

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,5 +1,7 @@
 import { Hono } from "hono";
 
+import type { MetricSnapshot } from "../observability/index.js";
+
 const startTime = Date.now();
 
 // Public liveness probe. Deliberately minimal: no version/commit, no cron
@@ -18,6 +20,8 @@ export interface StatusDeps {
   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 +35,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
@@ -116,7 +119,7 @@ export function createShareRoutes(deps: ShareRoutesDeps): Hono {
     // 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);
+      log?.emit({ severityText: "ERROR", body: "share staging prune failed", attributes: { error: err instanceof Error ? err.message : String(err) } });
     });
   }
 
@@ -180,7 +183,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) => {
@@ -410,11 +417,13 @@ 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: [],

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.

package/src/ws/connection.ts

@@ -3,16 +3,32 @@ import { PROTOCOL_REV } from "@schlessera/brain-ui-sdk/protocol";
 import { parseClientMessage } from "@schlessera/brain-ui-sdk/schemas";
 import { withTurnScope } from "./frames.js";
 import { sendSessionHistory } from "./history.js";
-import { handleClientMessage } from "./dispatch.js";
+import { handleClientMessage, type ConnectionState } from "./dispatch.js";
 import type { WsHost } from "./host.js";
+import type { WSContext } from "./clients.js";
 
 export { websocket };
 
-/** Build the Hono WebSocket upgrade handler bound to one host. */
-export function createWsUpgrade(host: WsHost) {
-  return upgradeWebSocket(() => ({
-    async onOpen(_evt, ws) {
-      console.log("[ws] Client connected");
+/**
+ * The socket lifecycle handlers for one host, separate from the Hono upgrade
+ * that wraps them.
+ *
+ * Split out so the real frame path is reachable from a test without standing
+ * up an HTTP server: `createWsHandlers(host).onMessage(...)` runs exactly what
+ * production runs, which is what makes an assertion about a dropped frame an
+ * assertion about the shipped code rather than about a re-implementation.
+ */
+export function createWsHandlers(host: WsHost) {
+  // One bucket per connection, created here so it lives and dies with the
+  // socket rather than in a map keyed by something a peer controls.
+  const limiter = host.newRateLimiter();
+  // Per-connection negotiation state: what revision this client declared.
+  // Lives with the socket, like the limiter.
+  const connection: ConnectionState = {};
+
+  return {
+    async onOpen(_evt: Event, ws: WSContext) {
+      host.log.emit({ severityText: "INFO", body: "client connected" });
       const { coordinator, catalog } = host;
 
       // Handshake first (rev 2, additive): protocol revision + coarse
@@ -53,7 +69,11 @@ export function createWsUpgrade(host: WsHost) {
           const history = await backend.getHistory(sid);
           if (history.length > 0) sendSessionHistory(ws, sid, history);
         } catch (err) {
-          console.error("[ws] snapshot-on-connect failed:", err);
+          host.log.emit({
+            severityText: "ERROR",
+            body: "snapshot-on-connect failed",
+            attributes: { error: err instanceof Error ? err.message : String(err) },
+          });
         } finally {
           host.clients.add(ws);
           host.sendMessage(
@@ -80,7 +100,7 @@ export function createWsUpgrade(host: WsHost) {
       });
     },
 
-    onMessage(evt, ws) {
+    onMessage(evt: MessageEvent, ws: WSContext) {
       // Boundary validation (rev 2): byte cap + JSON decode + schema, in one
       // place. No more casting client JSON to ClientMessage.
       //
@@ -88,8 +108,21 @@ export function createWsUpgrade(host: WsHost) {
       // underlying POOLED ArrayBuffer (byteOffset/byteLength discarded), so a
       // binary frame cannot be decoded correctly here. The protocol is JSON
       // text; reject anything else rather than parse a slab.
+      // Metered BEFORE parsing: the point is to bound work an unmetered peer
+      // can make this process do, and parsing is most of that work.
+      if (limiter && !limiter.take().allowed) {
+        host.reportDroppedFrame("rate_limited");
+        host.sendMessage(ws, {
+          type: "error",
+          code: "RATE_LIMITED",
+          message: "Too many frames; slow down.",
+        });
+        return;
+      }
+
       const raw = evt.data;
       if (typeof raw !== "string") {
+        host.reportDroppedFrame("binary_frame");
         host.sendMessage(ws, {
           type: "error",
           code: "PARSE_ERROR",
@@ -99,6 +132,9 @@ export function createWsUpgrade(host: WsHost) {
       }
       const parsed = parseClientMessage(raw);
       if (!parsed.ok) {
+        // The reason is the parser's own bounded message, never the frame:
+        // the payload is caller-supplied and capped at 12 MB.
+        host.reportDroppedFrame("parse_error", parsed.error);
         host.sendMessage(ws, { type: "error", code: "PARSE_ERROR", message: parsed.error });
         return;
       }
@@ -106,7 +142,17 @@ export function createWsUpgrade(host: WsHost) {
       // unhandled rejection with no frame sent.
       void Promise.resolve()
         .then(() => handleClientMessage(host, ws, parsed.message))
-        .catch(() => {
+        .catch((err) => {
+          // This used to swallow the cause entirely: the client got a generic
+          // frame and the server kept no record of what threw.
+          host.log.emit({
+            severityText: "ERROR",
+            body: "client message handler failed",
+            attributes: {
+              "frame.type": parsed.message.type,
+              error: err instanceof Error ? err.message : String(err),
+            },
+          });
           host.sendMessage(ws, {
             type: "error",
             code: "INTERNAL_ERROR",
@@ -115,8 +161,8 @@ export function createWsUpgrade(host: WsHost) {
         });
     },
 
-    onClose(_evt, ws) {
-      console.log("[ws] Client disconnected");
+    onClose(_evt: CloseEvent, ws: WSContext) {
+      host.log.emit({ severityText: "INFO", body: "client disconnected" });
       host.clients.remove(ws);
       // Turns keep running in the background. Only reject pending interactive
       // requests once the LAST client leaves — while another client remains it
@@ -126,5 +172,10 @@ export function createWsUpgrade(host: WsHost) {
         host.coordinator.drainPendingForTurn(turn, "Client disconnected");
       }
     },
-  }));
+  };
+}
+
+/** Build the Hono WebSocket upgrade handler bound to one host. */
+export function createWsUpgrade(host: WsHost) {
+  return upgradeWebSocket(() => createWsHandlers(host));
 }