@schlessera/brain-ui-server 0.15.0 → 0.17.0

package/dist/ws/dispatch.js

@@ -1,19 +1,37 @@
+import { PROTOCOL_REV_CLIENT_ECHO } from "@schlessera/brain-ui-sdk/protocol";
 import { locationErrorText } from "./frames.js";
 import { sendSessionHistory } from "./history.js";
 import { validateAttachments } from "./attachments.js";
 import { handleChatMessage } from "./run-session.js";
 /**
- * A client MAY echo the request's turnId (rev 2). When it does, it must match
- * the turn that raised the request — a stale echo from before a reconnect or
- * a follow-up would otherwise resolve the wrong turn's pending promise.
- * Absent turnId stays valid: the field is optional on the wire.
+ * Does this reply's echoed turnId identify the turn that raised the request?
+ *
+ * A wrong id is always refused: a stale echo from before a reconnect or a
+ * follow-up would resolve a different turn's pending promise.
+ *
+ * A MISSING id depends on who is speaking. A client that declared rev 3
+ * promised to echo, so silence means the reply cannot be correlated and is
+ * refused. A client that declared nothing is rev 2, where the field is
+ * optional, and is still tolerated — that tolerance is the deprecation window,
+ * and it is what lets this be enforced at all without breaking clients that
+ * predate `client_hello`.
  */
-function turnIdMatches(pending, echoed) {
-    return echoed === undefined || echoed === pending.turnId;
+export function turnIdMatches(pending, echoed, requireEcho) {
+    if (echoed === undefined)
+        return !requireEcho;
+    return echoed === pending.turnId;
 }
-export async function handleClientMessage(host, ws, msg) {
+export async function handleClientMessage(host, ws, msg, connection = {}) {
     const { coordinator, catalog } = host;
+    const requireEcho = (connection.protocolRev ?? 2) >= PROTOCOL_REV_CLIENT_ECHO;
     switch (msg.type) {
+        case "client_hello": {
+            // Record what this connection speaks. Never rejected on version: a
+            // future client declaring rev 9 is simply held to the rules this host
+            // knows, and an unknown capability flag is ignored.
+            connection.protocolRev = msg.protocolRev;
+            return;
+        }
         case "chat_message": {
             const attachmentResult = validateAttachments(msg.attachments);
             if (!attachmentResult.ok) {
@@ -36,7 +54,7 @@ export async function handleClientMessage(host, ws, msg) {
         }
         case "ask_user_response": {
             const pending = coordinator.pendingAskUser.get(msg.requestId);
-            if (pending && turnIdMatches(pending, msg.turnId)) {
+            if (pending && turnIdMatches(pending, msg.turnId, requireEcho)) {
                 coordinator.pendingAskUser.delete(msg.requestId);
                 pending.resolve({ answers: msg.answers, annotations: msg.annotations });
             }
@@ -44,7 +62,7 @@ export async function handleClientMessage(host, ws, msg) {
         }
         case "ask_user_cancel": {
             const pending = coordinator.pendingAskUser.get(msg.requestId);
-            if (pending && turnIdMatches(pending, msg.turnId)) {
+            if (pending && turnIdMatches(pending, msg.turnId, requireEcho)) {
                 coordinator.pendingAskUser.delete(msg.requestId);
                 pending.reject(new Error(msg.reason || "User cancelled the question"));
             }
@@ -52,7 +70,7 @@ export async function handleClientMessage(host, ws, msg) {
         }
         case "location_response": {
             const pending = coordinator.pendingLocation.get(msg.requestId);
-            if (pending && turnIdMatches(pending, msg.turnId)) {
+            if (pending && turnIdMatches(pending, msg.turnId, requireEcho)) {
                 coordinator.pendingLocation.delete(msg.requestId);
                 pending.resolve({ coords: msg.coords, timestamp: msg.timestamp });
             }
@@ -60,7 +78,7 @@ export async function handleClientMessage(host, ws, msg) {
         }
         case "location_error": {
             const pending = coordinator.pendingLocation.get(msg.requestId);
-            if (pending && turnIdMatches(pending, msg.turnId)) {
+            if (pending && turnIdMatches(pending, msg.turnId, requireEcho)) {
                 coordinator.pendingLocation.delete(msg.requestId);
                 pending.reject(new Error(locationErrorText(msg.code, msg.message)));
             }
@@ -68,7 +86,7 @@ export async function handleClientMessage(host, ws, msg) {
         }
         case "mask_response": {
             const pending = coordinator.pendingMask.get(msg.requestId);
-            if (pending && turnIdMatches(pending, msg.turnId)) {
+            if (pending && turnIdMatches(pending, msg.turnId, requireEcho)) {
                 coordinator.pendingMask.delete(msg.requestId);
                 // Decoded here rather than in the tool: the boundary already validated
                 // the base64 and its size, so the backend gets bytes it can trust.
@@ -78,7 +96,7 @@ export async function handleClientMessage(host, ws, msg) {
         }
         case "mask_error": {
             const pending = coordinator.pendingMask.get(msg.requestId);
-            if (pending && turnIdMatches(pending, msg.turnId)) {
+            if (pending && turnIdMatches(pending, msg.turnId, requireEcho)) {
                 coordinator.pendingMask.delete(msg.requestId);
                 pending.reject(new Error(msg.code === "cancelled"
                     ? `The user did not mark an area${msg.message ? `: ${msg.message}` : ""}`
@@ -88,7 +106,7 @@ export async function handleClientMessage(host, ws, msg) {
         }
         case "tool_approval": {
             const pending = coordinator.pendingApprovals.get(msg.toolUseId);
-            if (pending && turnIdMatches(pending, msg.turnId)) {
+            if (pending && turnIdMatches(pending, msg.turnId, requireEcho)) {
                 coordinator.pendingApprovals.delete(msg.toolUseId);
                 pending.resolve(msg.updatedInput
                     ? { behavior: "allow", updatedInput: msg.updatedInput }
@@ -98,7 +116,7 @@ export async function handleClientMessage(host, ws, msg) {
         }
         case "tool_denial": {
             const pending = coordinator.pendingApprovals.get(msg.toolUseId);
-            if (pending && turnIdMatches(pending, msg.turnId)) {
+            if (pending && turnIdMatches(pending, msg.turnId, requireEcho)) {
                 coordinator.pendingApprovals.delete(msg.toolUseId);
                 pending.resolve({ behavior: "deny", message: msg.message });
             }
@@ -150,10 +168,12 @@ export async function handleClientMessage(host, ws, msg) {
                 });
             }
             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/dist/ws/dispatch.js.map

@@ -1 +1 @@
-{"version":3,"file":"dispatch.js","sourceRoot":"","sources":["../../src/ws/dispatch.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"dispatch.js","sourceRoot":"","sources":["../../src/ws/dispatch.ts"],"names":[],"mappings":"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"}

package/dist/ws/host.d.ts

@@ -3,6 +3,8 @@ import { ClientSet, type WSContext } from "./clients.js";
 import { TurnCoordinator } from "./turns.js";
 import type { SessionCatalog } from "./session-catalog.js";
 import type { BackendRegistry } from "../agent/backend.js";
+import { type Observability } from "../observability/index.js";
+import { FrameRateLimiter } from "./rate-limit.js";
 /**
  * Budget for the host-side follow-up queue of ONE session (backends without a
  * native `followUp`; with one, messages go into the running turn and none of
@@ -41,7 +43,34 @@ export interface WsHostOptions {
      * it dynamic; createApp passes the resolved config value.
      */
     maxConcurrentSessions?: () => number;
+    /**
+     * Where this coordinator reports. Injected rather than reached for, so two
+     * apps in one process report separately and a test can assert on what the
+     * socket layer actually said. Defaults to silence: an embedder that never
+     * passes one gets no output, not a surprise stream on stdout.
+     */
+    observability?: Observability;
+    /**
+     * Inbound frame metering policy, per connection. Omitted (or a rate of 0)
+     * means no metering — which is what a test wants, and what an embedder
+     * fronting the socket with its own limiter wants.
+     */
+    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 declare function turnLogAttributes(turn: TurnLogContext): Record<string, string>;
 /**
  * Everything one WebSocket coordinator instance owns: turn state, the session
  * catalog, the backend registry, the attached client sockets, branding copy,
@@ -56,7 +85,51 @@ export declare class WsHost {
     appName: string;
     turnTimeoutMs: number;
     maxConcurrentSessions: () => number;
+    readonly observability: Observability;
+    readonly wsRate: {
+        ratePerSecond: number;
+        burst: number;
+    } | null;
+    /** Scoped instruments, resolved once — `[ws]` is the existing log prefix. */
+    readonly log: ReturnType<Observability["logger"]>;
+    private readonly framesDropped;
+    private readonly turnsStarted;
+    private readonly turnsCompleted;
+    private readonly turnsFailed;
+    private readonly wsErrors;
     constructor(options: WsHostOptions);
+    /** A metering bucket for one new connection, or null when metering is off. */
+    newRateLimiter(): FrameRateLimiter | null;
+    /**
+     * Record a frame this server refused, and say so.
+     *
+     * Before this existed, every rejection answered the client and vanished:
+     * `parseClientMessage` failures were never logged, so the validation we
+     * already shipped had no observability at all. `reason` is a bounded token,
+     * never the frame body — the payload is caller-supplied and can be 12 MB.
+     */
+    reportDroppedFrame(reason: string, detail?: string): void;
+    /** A turn began executing: counted, and logged with its correlation ids. */
+    reportTurnStarted(turn: TurnLogContext): void;
+    /** A turn's backend call resolved: counted, and logged with its duration. */
+    reportTurnCompleted(turn: TurnLogContext, durationMs: number): void;
+    /**
+     * 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;
+    /**
+     * 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;
     /** Fan a frame out to every attached client (size-bounded per frame). */
     sendToClients(msg: ServerMessage): void;
     /** Send a frame to one specific socket (size-bounded). */

package/dist/ws/host.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"host.d.ts","sourceRoot":"","sources":["../../src/ws/host.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mCAAmC,CAAC;AACvE,OAAO,EAAE,SAAS,EAAU,KAAK,SAAS,EAAE,MAAM,cAAc,CAAC;AACjE,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAQ3D;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,gBAAgB,QAAmB,CAAC;AACjD,eAAO,MAAM,eAAe,QAAmB,CAAC;AAEhD;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,KAAK,CAAC;AAEpC,MAAM,WAAW,aAAa;IAC5B,sEAAsE;IACtE,QAAQ,EAAE,eAAe,CAAC;IAC1B,+DAA+D;IAC/D,OAAO,EAAE,cAAc,CAAC;IACxB,mDAAmD;IACnD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mDAAmD;IACnD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,qBAAqB,CAAC,EAAE,MAAM,MAAM,CAAC;CACtC;AAED;;;;;GAKG;AACH,qBAAa,MAAM;IACjB,QAAQ,CAAC,WAAW,kBAAyB;IAC7C,QAAQ,CAAC,OAAO,YAAmB;IACnC,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;IACnC,OAAO,EAAE,cAAc,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,qBAAqB,EAAE,MAAM,MAAM,CAAC;gBAExB,OAAO,EAAE,aAAa;IASlC,yEAAyE;IACzE,aAAa,CAAC,GAAG,EAAE,aAAa,GAAG,IAAI;IAIvC,0DAA0D;IAC1D,WAAW,CAAC,EAAE,EAAE,SAAS,EAAE,GAAG,EAAE,aAAa,GAAG,IAAI;CAGrD"}
+{"version":3,"file":"host.d.ts","sourceRoot":"","sources":["../../src/ws/host.ts"],"names":[],"mappings":"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"}

package/dist/ws/host.js

@@ -1,5 +1,7 @@
 import { ClientSet, sendTo } from "./clients.js";
 import { TurnCoordinator } from "./turns.js";
+import { createSilentObservability } from "../observability/index.js";
+import { FrameRateLimiter } from "./rate-limit.js";
 /** Host-side turn timeout. The backend no longer times out — the host owns it. */
 const DEFAULT_TIMEOUT_MS = 10 * 60 * 1000; // 10 minutes
 /** Default cap on concurrently RUNNING sessions (MAX_CONCURRENT_SESSIONS). */
@@ -27,6 +29,17 @@ export const QUEUE_MAX_BYTES = 50 * 1024 * 1024;
  * and would run the session for days. Not the limit anyone should hit.
  */
 export const MAX_SESSION_QUEUE = 50;
+/**
+ * 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) {
+    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,
@@ -41,6 +54,15 @@ export class WsHost {
     appName;
     turnTimeoutMs;
     maxConcurrentSessions;
+    observability;
+    wsRate;
+    /** Scoped instruments, resolved once — `[ws]` is the existing log prefix. */
+    log;
+    framesDropped;
+    turnsStarted;
+    turnsCompleted;
+    turnsFailed;
+    wsErrors;
     constructor(options) {
         this.registry = options.registry;
         this.catalog = options.catalog;
@@ -48,10 +70,114 @@ export class WsHost {
         this.turnTimeoutMs = options.turnTimeoutMs ?? DEFAULT_TIMEOUT_MS;
         this.maxConcurrentSessions =
             options.maxConcurrentSessions ?? (() => DEFAULT_MAX_CONCURRENT_SESSIONS);
+        this.observability = options.observability ?? createSilentObservability();
+        this.wsRate =
+            options.wsRate && options.wsRate.ratePerSecond > 0 ? options.wsRate : null;
+        this.log = this.observability.logger("ws");
+        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;
+    }
+    /** A metering bucket for one new connection, or null when metering is off. */
+    newRateLimiter() {
+        return this.wsRate ? new FrameRateLimiter(this.wsRate) : null;
+    }
+    /**
+     * Record a frame this server refused, and say so.
+     *
+     * Before this existed, every rejection answered the client and vanished:
+     * `parseClientMessage` failures were never logged, so the validation we
+     * already shipped had no observability at all. `reason` is a bounded token,
+     * never the frame body — the payload is caller-supplied and can be 12 MB.
+     */
+    reportDroppedFrame(reason, detail) {
+        this.framesDropped.add(1, { reason, direction: "inbound" });
+        this.log.emit({
+            severityText: "WARN",
+            body: "inbound frame rejected",
+            attributes: detail ? { reason, detail } : { reason },
+        });
+    }
+    /** A turn began executing: counted, and logged with its correlation ids. */
+    reportTurnStarted(turn) {
+        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, durationMs) {
+        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, turn, error) {
+        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) {
+        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) {
-        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). */
     sendMessage(ws, msg) {

package/dist/ws/host.js.map

@@ -1 +1 @@
-{"version":3,"file":"host.js","sourceRoot":"","sources":["../../src/ws/host.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,EAAkB,MAAM,cAAc,CAAC;AACjE,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAI7C,kFAAkF;AAClF,MAAM,kBAAkB,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,aAAa;AAExD,8EAA8E;AAC9E,MAAM,+BAA+B,GAAG,CAAC,CAAC;AAE1C;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC;AACjD,MAAM,CAAC,MAAM,eAAe,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC;AAEhD;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,EAAE,CAAC;AAmBpC;;;;;GAKG;AACH,MAAM,OAAO,MAAM;IACR,WAAW,GAAG,IAAI,eAAe,EAAE,CAAC;IACpC,OAAO,GAAG,IAAI,SAAS,EAAE,CAAC;IAC1B,QAAQ,CAAkB;IACnC,OAAO,CAAiB;IACxB,OAAO,CAAS;IAChB,aAAa,CAAS;IACtB,qBAAqB,CAAe;IAEpC,YAAY,OAAsB;QAChC,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;QACjC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;QAC/B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,UAAU,CAAC;QAC7C,IAAI,CAAC,aAAa,GAAG,OAAO,CAAC,aAAa,IAAI,kBAAkB,CAAC;QACjE,IAAI,CAAC,qBAAqB;YACxB,OAAO,CAAC,qBAAqB,IAAI,CAAC,GAAG,EAAE,CAAC,+BAA+B,CAAC,CAAC;IAC7E,CAAC;IAED,yEAAyE;IACzE,aAAa,CAAC,GAAkB;QAC9B,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;IAC9B,CAAC;IAED,0DAA0D;IAC1D,WAAW,CAAC,EAAa,EAAE,GAAkB;QAC3C,MAAM,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;IAClB,CAAC;CACF"}
+{"version":3,"file":"host.js","sourceRoot":"","sources":["../../src/ws/host.ts"],"names":[],"mappings":"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"}

package/dist/ws/rate-limit.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Per-connection inbound frame metering.
+ *
+ * Frames are already size-, cardinality- and depth-bounded, so the cheap CPU
+ * amplification is closed. What was left unmetered is VOLUME: a flood of
+ * individually valid frames behind the auth guard. That is a smaller threat
+ * than an unauthenticated one — it needs a session — but "the attacker had to
+ * log in first" is not a bound.
+ *
+ * A token bucket rather than a fixed window, because the traffic this protects
+ * is bursty by nature and a fixed window punishes the wrong thing. Opening the
+ * app fires a handful of frames at once (resume, environment, a first
+ * message); an approval storm during a busy turn is a dozen in a second. Both
+ * are legitimate and both fit in the burst. What does not fit is a sustained
+ * rate no human produces.
+ *
+ * Inbound traffic is naturally low-rate — deltas flow the other way — so the
+ * defaults are generous enough that no real client should ever see one of
+ * these, which is the property that makes it safe to turn on by default.
+ */
+/** Injected so tests need no real time. */
+export interface Clock {
+    now(): number;
+}
+export interface RateLimitOptions {
+    /** Sustained frames per second. */
+    ratePerSecond: number;
+    /** Frames absorbable in one burst before the sustained rate applies. */
+    burst: number;
+    clock?: Clock;
+}
+export interface RateLimitDecision {
+    allowed: boolean;
+    /** Tokens left after this decision, for reporting. */
+    remaining: number;
+}
+/**
+ * One bucket per connection. Not shared, and not keyed by anything
+ * user-supplied: a map keyed by session or IP is itself an unbounded
+ * allocation an attacker controls, which is the classic way a rate limiter
+ * becomes the memory-exhaustion bug it was added to prevent. This lives on the
+ * socket and dies with it.
+ */
+export declare class FrameRateLimiter {
+    private tokens;
+    private lastRefill;
+    private readonly ratePerMs;
+    private readonly burst;
+    private readonly clock;
+    /** Frames refused since the connection opened. */
+    private rejected;
+    constructor(options: RateLimitOptions);
+    /** Take one token. False means this frame should be refused. */
+    take(): RateLimitDecision;
+    /** How many frames this connection has had refused. */
+    get rejectedCount(): number;
+}
+//# sourceMappingURL=rate-limit.d.ts.map

package/dist/ws/rate-limit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.d.ts","sourceRoot":"","sources":["../../src/ws/rate-limit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,2CAA2C;AAC3C,MAAM,WAAW,KAAK;IACpB,GAAG,IAAI,MAAM,CAAC;CACf;AAID,MAAM,WAAW,gBAAgB;IAC/B,mCAAmC;IACnC,aAAa,EAAE,MAAM,CAAC;IACtB,wEAAwE;IACxE,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,KAAK,CAAC;CACf;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,OAAO,CAAC;IACjB,sDAAsD;IACtD,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;GAMG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAQ;IAC9B,kDAAkD;IAClD,OAAO,CAAC,QAAQ,CAAK;gBAET,OAAO,EAAE,gBAAgB;IAQrC,gEAAgE;IAChE,IAAI,IAAI,iBAAiB;IAczB,uDAAuD;IACvD,IAAI,aAAa,IAAI,MAAM,CAE1B;CACF"}

package/dist/ws/rate-limit.js

@@ -0,0 +1,62 @@
+/**
+ * Per-connection inbound frame metering.
+ *
+ * Frames are already size-, cardinality- and depth-bounded, so the cheap CPU
+ * amplification is closed. What was left unmetered is VOLUME: a flood of
+ * individually valid frames behind the auth guard. That is a smaller threat
+ * than an unauthenticated one — it needs a session — but "the attacker had to
+ * log in first" is not a bound.
+ *
+ * A token bucket rather than a fixed window, because the traffic this protects
+ * is bursty by nature and a fixed window punishes the wrong thing. Opening the
+ * app fires a handful of frames at once (resume, environment, a first
+ * message); an approval storm during a busy turn is a dozen in a second. Both
+ * are legitimate and both fit in the burst. What does not fit is a sustained
+ * rate no human produces.
+ *
+ * Inbound traffic is naturally low-rate — deltas flow the other way — so the
+ * defaults are generous enough that no real client should ever see one of
+ * these, which is the property that makes it safe to turn on by default.
+ */
+const realClock = { now: () => Date.now() };
+/**
+ * One bucket per connection. Not shared, and not keyed by anything
+ * user-supplied: a map keyed by session or IP is itself an unbounded
+ * allocation an attacker controls, which is the classic way a rate limiter
+ * becomes the memory-exhaustion bug it was added to prevent. This lives on the
+ * socket and dies with it.
+ */
+export class FrameRateLimiter {
+    tokens;
+    lastRefill;
+    ratePerMs;
+    burst;
+    clock;
+    /** Frames refused since the connection opened. */
+    rejected = 0;
+    constructor(options) {
+        this.burst = Math.max(1, options.burst);
+        this.ratePerMs = Math.max(0, options.ratePerSecond) / 1000;
+        this.clock = options.clock ?? realClock;
+        this.tokens = this.burst;
+        this.lastRefill = this.clock.now();
+    }
+    /** Take one token. False means this frame should be refused. */
+    take() {
+        const now = this.clock.now();
+        const elapsed = Math.max(0, now - this.lastRefill);
+        this.lastRefill = now;
+        this.tokens = Math.min(this.burst, this.tokens + elapsed * this.ratePerMs);
+        if (this.tokens < 1) {
+            this.rejected++;
+            return { allowed: false, remaining: 0 };
+        }
+        this.tokens -= 1;
+        return { allowed: true, remaining: Math.floor(this.tokens) };
+    }
+    /** How many frames this connection has had refused. */
+    get rejectedCount() {
+        return this.rejected;
+    }
+}
+//# sourceMappingURL=rate-limit.js.map

package/dist/ws/rate-limit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.js","sourceRoot":"","sources":["../../src/ws/rate-limit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAOH,MAAM,SAAS,GAAU,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC;AAgBnD;;;;;;GAMG;AACH,MAAM,OAAO,gBAAgB;IACnB,MAAM,CAAS;IACf,UAAU,CAAS;IACV,SAAS,CAAS;IAClB,KAAK,CAAS;IACd,KAAK,CAAQ;IAC9B,kDAAkD;IAC1C,QAAQ,GAAG,CAAC,CAAC;IAErB,YAAY,OAAyB;QACnC,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;QACxC,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAAG,IAAI,CAAC;QAC3D,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,SAAS,CAAC;QACxC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC;QACzB,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC;IACrC,CAAC;IAED,gEAAgE;IAChE,IAAI;QACF,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC;QAC7B,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC;QACnD,IAAI,CAAC,UAAU,GAAG,GAAG,CAAC;QACtB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC;QAE3E,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACpB,IAAI,CAAC,QAAQ,EAAE,CAAC;YAChB,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC;QAC1C,CAAC;QACD,IAAI,CAAC,MAAM,IAAI,CAAC,CAAC;QACjB,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;IAC/D,CAAC;IAED,uDAAuD;IACvD,IAAI,aAAa;QACf,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;CACF"}

package/dist/ws/run-session.d.ts

@@ -12,6 +12,8 @@ export declare function runSession(host: WsHost, initial: {
     attachments: ChatImageAttachment[];
     providerId?: string;
     client?: ClientEnvironment;
+    /** Client correlation id for a new conversation; echoed on session_info. */
+    draftId?: string;
 }): Promise<void>;
 /** Dispatch a chat_message: follow-up to a running session, or a new session. */
 export declare function handleChatMessage(host: WsHost, ws: WSContext, msg: {
@@ -20,5 +22,6 @@ export declare function handleChatMessage(host: WsHost, ws: WSContext, msg: {
     attachments: ChatImageAttachment[];
     providerId?: string;
     client?: ClientEnvironment;
+    draftId?: string;
 }): Promise<void>;
 //# sourceMappingURL=run-session.d.ts.map

package/dist/ws/run-session.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run-session.d.ts","sourceRoot":"","sources":["../../src/ws/run-session.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AAChG,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAM9C,OAAO,EAAwD,KAAK,MAAM,EAAE,MAAM,WAAW,CAAC;AAE9F;;;;GAIG;AACH,wBAAsB,UAAU,CAC9B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE;IACP,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,mBAAmB,EAAE,CAAC;IACnC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,iBAAiB,CAAC;CAC5B,GACA,OAAO,CAAC,IAAI,CAAC,CA0Gf;AAOD,iFAAiF;AACjF,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,SAAS,EACb,GAAG,EAAE;IACH,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,mBAAmB,EAAE,CAAC;IACnC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,iBAAiB,CAAC;CAC5B,GACA,OAAO,CAAC,IAAI,CAAC,CA0Ff"}
+{"version":3,"file":"run-session.d.ts","sourceRoot":"","sources":["../../src/ws/run-session.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AAChG,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAM9C,OAAO,EAKL,KAAK,MAAM,EACZ,MAAM,WAAW,CAAC;AAEnB;;;;GAIG;AACH,wBAAsB,UAAU,CAC9B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE;IACP,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,mBAAmB,EAAE,CAAC;IACnC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAC3B,4EAA4E;IAC5E,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GACA,OAAO,CAAC,IAAI,CAAC,CAoIf;AAOD,iFAAiF;AACjF,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,SAAS,EACb,GAAG,EAAE;IACH,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,mBAAmB,EAAE,CAAC;IACnC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GACA,OAAO,CAAC,IAAI,CAAC,CAkGf"}