@schlessera/brain-ui-server 0.16.0 → 0.18.0

package/src/ws/connection.ts

@@ -2,6 +2,45 @@ import { upgradeWebSocket, websocket } from "hono/bun";
 import { PROTOCOL_REV } from "@schlessera/brain-ui-sdk/protocol";
 import { parseClientMessage } from "@schlessera/brain-ui-sdk/schemas";
 import { withTurnScope } from "./frames.js";
+import type { WSContext as WSContextType } from "./clients.js";
+
+/**
+ * Re-send every pending approval and ask-user card to a client that just
+ * connected. These survive disconnects (see drainClientBoundForTurn) precisely
+ * so this re-delivery can happen: a phone that dropped its socket at screen
+ * lock reconnects and finds the card waiting instead of a dead turn. The
+ * frames carry their original turn scope, so answering them resolves the
+ * correct turn's promise through the normal dispatch path.
+ */
+function resendPendingInteractive(host: WsHost, ws: WSContextType): void {
+  const { coordinator } = host;
+  for (const p of coordinator.pendingApprovals.values()) {
+    host.sendMessage(
+      ws,
+      withTurnScope(
+        {
+          type: "tool_approval_request",
+          toolUseId: p.request.toolUseId,
+          toolName: p.request.toolName,
+          input: p.request.input,
+          description: p.request.description,
+        },
+        p.turn,
+        p.turnId
+      )
+    );
+  }
+  for (const p of coordinator.pendingAskUser.values()) {
+    host.sendMessage(
+      ws,
+      withTurnScope(
+        { type: "ask_user_request", requestId: p.requestId, questions: p.questions },
+        p.turn,
+        p.turnId
+      )
+    );
+  }
+}
 import { sendSessionHistory } from "./history.js";
 import { handleClientMessage, type ConnectionState } from "./dispatch.js";
 import type { WsHost } from "./host.js";
@@ -88,6 +127,7 @@ export function createWsHandlers(host: WsHost) {
               turn
             )
           );
+          resendPendingInteractive(host, ws);
         }
         return;
       }
@@ -98,6 +138,7 @@ export function createWsHandlers(host: WsHost) {
         status: "idle",
         detail: `Connected to ${host.appName}`,
       });
+      resendPendingInteractive(host, ws);
     },
 
     onMessage(evt: MessageEvent, ws: WSContext) {
@@ -141,7 +182,7 @@ export function createWsHandlers(host: WsHost) {
       // handleClientMessage is async — a rejection must not escape as an
       // unhandled rejection with no frame sent.
       void Promise.resolve()
-        .then(() => handleClientMessage(host, ws, parsed.message))
+        .then(() => handleClientMessage(host, ws, parsed.message, connection))
         .catch((err) => {
           // This used to swallow the cause entirely: the client got a generic
           // frame and the server kept no record of what threw.
@@ -161,15 +202,27 @@ export function createWsHandlers(host: WsHost) {
         });
     },
 
-    onClose(_evt: CloseEvent, ws: WSContext) {
+    onClose(evt: CloseEvent, ws: WSContext) {
       host.log.emit({ severityText: "INFO", body: "client disconnected" });
+      // No onError here on purpose: hono's Bun adapter never dispatches it
+      // (only open/message/close reach these handlers), so a transport failure
+      // is only visible as an abnormal close code. 1000/1001 are the two
+      // clean endings (normal closure, going away); anything else — before it
+      // was recorded — looked exactly like a clean disconnect.
+      const code = (evt as { code?: unknown }).code;
+      if (typeof code === "number" && code !== 1000 && code !== 1001) {
+        host.reportAbnormalClose(code);
+      }
       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
-      // can still answer them.
+      // Turns keep running in the background. Once the LAST client leaves,
+      // reject only the requests that need a live client RIGHT NOW (location,
+      // mask). Approvals and ask-user cards survive the disconnect and are
+      // re-delivered on reconnect — a phone drops its socket at every screen
+      // lock, and denying pending approvals on that signal killed real work.
+      // The turn timeout remains their upper bound.
       if (host.clients.hasClients()) return;
       for (const turn of host.coordinator.running) {
-        host.coordinator.drainPendingForTurn(turn, "Client disconnected");
+        host.coordinator.drainClientBoundForTurn(turn, "Client disconnected");
       }
     },
   };

package/src/ws/dispatch.ts

@@ -202,10 +202,12 @@ export async function handleClientMessage(
           ...(runningTurn ? { turnId: runningTurn.turnId } : {}),
         });
       } catch (err) {
+        const message = err instanceof Error ? err.message : "Failed to load session";
+        host.reportTurnFailed("SESSION_LOAD_ERROR", { sessionId: msg.sessionId }, message);
         host.sendMessage(ws, {
           type: "error",
           code: "SESSION_LOAD_ERROR",
-          message: err instanceof Error ? err.message : "Failed to load session",
+          message,
           sessionId: msg.sessionId,
         });
       }

package/src/ws/host.ts

@@ -67,6 +67,25 @@ export interface WsHostOptions {
   wsRate?: { ratePerSecond: number; burst: number };
 }
 
+/** Identity of one turn, as it appears on a log record. */
+export interface TurnLogContext {
+  sessionId?: string | null;
+  turnId?: string | null;
+  providerId?: string | null;
+}
+
+/**
+ * Log attributes for one turn. Null fields are omitted rather than stringified
+ * — a new session has no sessionId until `session_info` names it.
+ */
+export function turnLogAttributes(turn: TurnLogContext): Record<string, string> {
+  return {
+    ...(turn.sessionId ? { "session.id": turn.sessionId } : {}),
+    ...(turn.turnId ? { "turn.id": turn.turnId } : {}),
+    ...(turn.providerId ? { profile: turn.providerId } : {}),
+  };
+}
+
 /**
  * Everything one WebSocket coordinator instance owns: turn state, the session
  * catalog, the backend registry, the attached client sockets, branding copy,
@@ -88,6 +107,18 @@ export class WsHost {
   private readonly framesDropped: ReturnType<
     ReturnType<Observability["meter"]>["createCounter"]
   >;
+  private readonly turnsStarted: ReturnType<
+    ReturnType<Observability["meter"]>["createCounter"]
+  >;
+  private readonly turnsCompleted: ReturnType<
+    ReturnType<Observability["meter"]>["createCounter"]
+  >;
+  private readonly turnsFailed: ReturnType<
+    ReturnType<Observability["meter"]>["createCounter"]
+  >;
+  private readonly wsErrors: ReturnType<
+    ReturnType<Observability["meter"]>["createCounter"]
+  >;
 
   constructor(options: WsHostOptions) {
     this.registry = options.registry;
@@ -100,11 +131,22 @@ export class WsHost {
     this.wsRate =
       options.wsRate && options.wsRate.ratePerSecond > 0 ? options.wsRate : null;
     this.log = this.observability.logger("ws");
-    this.framesDropped = this.observability
-      .meter("ws")
-      .createCounter("ws.frames.dropped", {
-        description: "Inbound frames refused before reaching a handler",
-      });
+    const meter = this.observability.meter("ws");
+    this.framesDropped = meter.createCounter("ws.frames.dropped", {
+      description: "Inbound frames refused before reaching a handler",
+    });
+    this.turnsStarted = meter.createCounter("turns.started", {
+      description: "Turns handed to a backend",
+    });
+    this.turnsCompleted = meter.createCounter("turns.completed", {
+      description: "Turns whose backend call resolved without throwing",
+    });
+    this.turnsFailed = meter.createCounter("turns.failed", {
+      description: "Turn failures surfaced to the client, by error code",
+    });
+    this.wsErrors = meter.createCounter("ws.errors", {
+      description: "Transport errors reported by the socket layer",
+    });
     this.coordinator.log = this.log;
   }
 
@@ -130,9 +172,76 @@ export class WsHost {
     });
   }
 
+  /** A turn began executing: counted, and logged with its correlation ids. */
+  reportTurnStarted(turn: TurnLogContext): void {
+    this.turnsStarted.add(1);
+    this.log.emit({
+      severityText: "INFO",
+      body: "turn started",
+      attributes: turnLogAttributes(turn),
+    });
+  }
+
+  /** A turn's backend call resolved: counted, and logged with its duration. */
+  reportTurnCompleted(turn: TurnLogContext, durationMs: number): void {
+    this.turnsCompleted.add(1);
+    this.log.emit({
+      severityText: "INFO",
+      body: "turn completed",
+      attributes: { ...turnLogAttributes(turn), "duration.ms": durationMs },
+    });
+  }
+
+  /**
+   * Record a turn failure the client is being told about. Before this existed
+   * every such failure was an error FRAME only — visible on one phone screen,
+   * absent from the server's own record.
+   *
+   * `code` is the bounded error-frame code (it feeds a counter attribute);
+   * `error` is the thrown message and rides only on the log record — never a
+   * caller-supplied frame body, per the reportDroppedFrame model.
+   */
+  reportTurnFailed(code: string, turn: TurnLogContext, error?: string): void {
+    this.turnsFailed.add(1, { code });
+    this.log.emit({
+      // A busy session is the client racing itself; everything else is a
+      // failure the operator should see.
+      severityText: code === "SESSION_BUSY" ? "WARN" : "ERROR",
+      body: "turn failed",
+      attributes: {
+        code,
+        ...turnLogAttributes(turn),
+        ...(error ? { error } : {}),
+      },
+    });
+  }
+
+  /**
+   * Record a socket that closed abnormally. This is the transport-error signal
+   * available on Bun: hono's Bun adapter dispatches only open/message/close
+   * (never WSEvents.onError, and Bun's ServerWebSocket has no error callback),
+   * so a transport failure surfaces as a close with an abnormal code.
+   */
+  reportAbnormalClose(code: number): void {
+    this.wsErrors.add(1, { "close.code": code });
+    this.log.emit({
+      severityText: "WARN",
+      body: "websocket closed abnormally",
+      attributes: { "close.code": code },
+    });
+  }
+
   /** Fan a frame out to every attached client (size-bounded per frame). */
   sendToClients(msg: ServerMessage): void {
-    this.clients.broadcast(msg);
+    this.clients.broadcast(msg, () => {
+      // Outbound counterpart of reportDroppedFrame: the peer never saw this
+      // frame. Counted only — a dead socket would otherwise WARN per frame
+      // until its onClose prunes it.
+      this.framesDropped.add(1, {
+        reason: "broadcast_send_failed",
+        direction: "outbound",
+      });
+    });
   }
 
   /** Send a frame to one specific socket (size-bounded). */

package/src/ws/run-session.ts

@@ -5,7 +5,13 @@ import { makeBridge, emitTurnError } from "./bridge.js";
 import { resolveTurnTarget } from "./routing.js";
 import type { QueuedFollowUp, RunningTurn } from "./turns.js";
 import { queuedBytes, queuedFollowUpBytes } from "./turns.js";
-import { MAX_SESSION_QUEUE, QUEUE_MAX_BYTES, QUEUE_WARN_BYTES, type WsHost } from "./host.js";
+import {
+  MAX_SESSION_QUEUE,
+  QUEUE_MAX_BYTES,
+  QUEUE_WARN_BYTES,
+  turnLogAttributes,
+  type WsHost,
+} from "./host.js";
 
 /**
  * Run one session slot: the initial turn, then any queued follow-up turns in
@@ -30,10 +36,14 @@ export async function runSession(
   try {
     target = await resolveTurnTarget(host.registry, host.catalog, initial.sessionId, initial.providerId);
   } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    // No turn exists yet — routing failed before one was minted — so the
+    // report carries only the session identity the client asked for.
+    host.reportTurnFailed("BACKEND_ERROR", { sessionId: initial.sessionId }, message);
     host.sendToClients({
       type: "error",
       code: "BACKEND_ERROR",
-      message: err instanceof Error ? err.message : String(err),
+      message,
       ...(initial.sessionId ? { sessionId: initial.sessionId } : {}),
     });
     return;
@@ -66,6 +76,7 @@ export async function runSession(
     timeoutHandle: setTimeout(() => {}, 0),
     queue: [],
     cancelled: false,
+    lastResult: null,
   };
   clearTimeout(turn.timeoutHandle);
   coordinator.running.add(turn);
@@ -90,7 +101,9 @@ export async function runSession(
         host.log.emit({
           severityText: "WARN",
           body: "turn timed out",
-          attributes: { "timeout.ms": host.turnTimeoutMs },
+          // Read from the live turn: session_info may have named the session
+          // after this timer was armed.
+          attributes: { ...turnLogAttributes(turn), "timeout.ms": host.turnTimeoutMs },
         });
         abortController.abort();
         // Reject any pending interactive request for this turn too. A bridge
@@ -102,6 +115,8 @@ export async function runSession(
       turn.timeoutHandle = timeoutHandle;
 
       const bridge = makeBridge(host, turn, text, backend.id);
+      const startedAt = Date.now();
+      host.reportTurnStarted(turn);
       try {
         await backend.startTurn({
           prompt: text,
@@ -109,9 +124,21 @@ export async function runSession(
           sessionId: resumeId,
           profileId,
           signal: abortController.signal,
+          // The budget this very timer enforces, so the backend can put the
+          // real number in front of the model instead of it finding the cap
+          // mid-flight.
+          turnBudgetMs: host.turnTimeoutMs,
           bridge,
           ...(client ? { client } : {}),
         });
+        // A resolved startTurn is not a successful turn: backends resolve for
+        // runtime failures and report them on the terminal result frame, which
+        // the bridge recorded on the turn.
+        if (turn.lastResult === "error") {
+          host.reportTurnFailed("BACKEND_RESULT_ERROR", turn);
+        } else {
+          host.reportTurnCompleted(turn, Date.now() - startedAt);
+        }
       } catch (err) {
         emitTurnError(host, turn, err);
       } finally {
@@ -127,8 +154,10 @@ export async function runSession(
 
       if (!turn.cancelled && turn.queue.length > 0) {
         next = turn.queue.shift()!;
-        // A queued follow-up is its own turn — give it a fresh identity.
+        // A queued follow-up is its own turn — give it a fresh identity, and
+        // its own terminal disposition.
         turn.turnId = crypto.randomUUID();
+        turn.lastResult = null;
       }
     }
   } finally {
@@ -168,11 +197,10 @@ export async function handleChatMessage(
       // device snapshot is deliberately not forwarded: a follow-up joins a
       // turn whose system prompt was already built and cannot be revised.
       backend.followUp({ sessionId, prompt: text, attachments }).catch((err) => {
+        const message = err instanceof Error ? err.message : String(err);
+        host.reportTurnFailed("FOLLOWUP_FAILED", runningTurn, message);
         host.sendToClients(
-          withTurnScope(
-            { type: "error", code: "FOLLOWUP_FAILED", message: err instanceof Error ? err.message : String(err) },
-            runningTurn
-          )
+          withTurnScope({ type: "error", code: "FOLLOWUP_FAILED", message }, runningTurn)
         );
       });
     } else {

package/src/ws/session-catalog.ts

@@ -1,4 +1,5 @@
 import type { Database } from "bun:sqlite";
+import type { Logger } from "@opentelemetry/api-logs";
 import type { ServerResultMessage } from "@schlessera/brain-ui-sdk/protocol";
 
 /**
@@ -42,7 +43,20 @@ const UPSERT_SESSION_SQL = `INSERT INTO sessions (id, title, created_at, last_ac
      backend_id = COALESCE(excluded.backend_id, backend_id)`;
 
 /** SQLite-backed catalog over the app's own database (injected by createApp). */
-export function createSessionCatalog(db: () => Database): SessionCatalog {
+export function createSessionCatalog(db: () => Database, log?: Logger): SessionCatalog {
+  // Persistence stays non-throwing — losing one accounting row must not kill
+  // the turn — but never silent: a full disk or locked database would
+  // otherwise drop every session record with nothing anywhere.
+  const reportWriteFailure = (sessionId: string, err: unknown): void => {
+    log?.emit({
+      severityText: "WARN",
+      body: "session persistence failed",
+      attributes: {
+        "session.id": sessionId,
+        error: err instanceof Error ? err.message : String(err),
+      },
+    });
+  };
   return {
     getStoredProviderId(sessionId) {
       const row = db()
@@ -72,7 +86,9 @@ export function createSessionCatalog(db: () => Database): SessionCatalog {
             providerId,
             backendId
           );
-      } catch {}
+      } catch (err) {
+        reportWriteFailure(sessionId, err);
+      }
     },
 
     persistSession(msg, promptText, providerId, backendId) {
@@ -90,7 +106,9 @@ export function createSessionCatalog(db: () => Database): SessionCatalog {
             providerId,
             backendId
           );
-      } catch {}
+      } catch (err) {
+        reportWriteFailure(msg.sessionId, err);
+      }
     },
   };
 }

package/src/ws/turns.ts

@@ -2,10 +2,15 @@ import type { Logger } from "@opentelemetry/api-logs";
 import type {
   AgentBackend,
   PermissionDecision,
+  PermissionRequest,
   AskUserResult,
   LocationFix,
 } from "@schlessera/brain-ui-sdk/server";
-import type { ChatImageAttachment, ClientEnvironment } from "@schlessera/brain-ui-sdk/protocol";
+import type {
+  AskUserQuestion,
+  ChatImageAttachment,
+  ClientEnvironment,
+} from "@schlessera/brain-ui-sdk/protocol";
 
 export interface QueuedFollowUp {
   text: string;
@@ -55,6 +60,14 @@ export interface RunningTurn {
   timeoutHandle: ReturnType<typeof setTimeout>;
   queue: QueuedFollowUp[];
   cancelled: boolean;
+  /**
+   * Terminal disposition of the CURRENT turn's `result` frame, when one has
+   * streamed. Backends RESOLVE startTurn for runtime failures (the failure
+   * rides the result frame as outcome "error"), so completion accounting must
+   * read this — a resolved startTurn alone does not mean the turn succeeded.
+   * Reset when a queued follow-up becomes the next turn.
+   */
+  lastResult: "success" | "error" | "cancelled" | null;
   /**
    * Correlation id the client minted for this NEW conversation, echoed back on
    * `session_info` so the client can tell its own turn's identity from a
@@ -69,12 +82,21 @@ export interface RunningTurn {
 export interface PendingApproval {
   turn: RunningTurn;
   turnId: string;
+  /**
+   * The original request, kept so the card can be RE-DELIVERED to a client
+   * that connects later. On a phone the socket drops every time the screen
+   * locks; an approval must survive that and reappear, not silently die.
+   */
+  request: PermissionRequest;
   resolve: (decision: PermissionDecision) => void;
 }
 
 export interface PendingAskUser {
   turn: RunningTurn;
   turnId: string;
+  /** Kept for re-delivery on reconnect, like PendingApproval.request. */
+  requestId: string;
+  questions: AskUserQuestion[];
   resolve: (result: AskUserResult) => void;
   reject: (err: Error) => void;
 }
@@ -160,6 +182,20 @@ export class TurnCoordinator {
       p.reject(new Error(reason));
       this.pendingAskUser.delete(id);
     }
+    this.drainClientBoundForTurn(turn, reason);
+  }
+
+  /**
+   * Reject only the requests that NEED a live client at this instant —
+   * location and mask, whose sibling handlers already fail fast with no
+   * client attached. Approvals and ask-user cards deliberately survive a
+   * disconnect: on a phone the socket drops at every screen lock, and before
+   * this split a pending approval was silently denied the moment the screen
+   * went dark ("Client disconnected") while one raised DURING the dark parked
+   * until the turn timeout. Both now hold, bounded by the turn timeout, and
+   * re-deliver on reconnect.
+   */
+  drainClientBoundForTurn(turn: RunningTurn, reason: string): void {
     for (const [id, p] of this.pendingLocation) {
       if (p.turn !== turn) continue;
       p.reject(new Error(reason));