@schlessera/brain-ui-server 0.15.0 → 0.16.0

package/dist/ws/connection.js

@@ -5,11 +5,25 @@ import { withTurnScope } from "./frames.js";
 import { sendSessionHistory } from "./history.js";
 import { handleClientMessage } from "./dispatch.js";
 export { websocket };
-/** Build the Hono WebSocket upgrade handler bound to one host. */
-export function createWsUpgrade(host) {
-    return upgradeWebSocket(() => ({
+/**
+ * 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) {
+    // 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 = {};
+    return {
         async onOpen(_evt, ws) {
-            console.log("[ws] Client connected");
+            host.log.emit({ severityText: "INFO", body: "client connected" });
             const { coordinator, catalog } = host;
             // Handshake first (rev 2, additive): protocol revision + coarse
             // capabilities, so the client can gate behavior instead of sniffing.
@@ -43,7 +57,11 @@ export function createWsUpgrade(host) {
                         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);
@@ -71,8 +89,20 @@ export function createWsUpgrade(host) {
             // 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",
@@ -82,6 +112,9 @@ export function createWsUpgrade(host) {
             }
             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;
             }
@@ -89,7 +122,17 @@ export function createWsUpgrade(host) {
             // 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",
@@ -98,7 +141,7 @@ export function createWsUpgrade(host) {
             });
         },
         onClose(_evt, ws) {
-            console.log("[ws] Client disconnected");
+            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
@@ -109,6 +152,10 @@ export function createWsUpgrade(host) {
                 host.coordinator.drainPendingForTurn(turn, "Client disconnected");
             }
         },
-    }));
+    };
+}
+/** Build the Hono WebSocket upgrade handler bound to one host. */
+export function createWsUpgrade(host) {
+    return upgradeWebSocket(() => createWsHandlers(host));
 }
 //# sourceMappingURL=connection.js.map

package/dist/ws/connection.js.map

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

package/dist/ws/dispatch.d.ts

@@ -1,5 +1,26 @@
 import type { ClientMessage } from "@schlessera/brain-ui-sdk/protocol";
 import type { WSContext } from "./clients.js";
 import type { WsHost } from "./host.js";
-export declare function handleClientMessage(host: WsHost, ws: WSContext, msg: ClientMessage): Promise<void>;
+/** Per-connection negotiation state, owned by the socket handler. */
+export interface ConnectionState {
+    /** Revision the client declared via `client_hello`; absent means rev 2. */
+    protocolRev?: number;
+}
+/**
+ * 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`.
+ */
+export declare function turnIdMatches(pending: {
+    turnId: string;
+}, echoed: string | undefined, requireEcho: boolean): boolean;
+export declare function handleClientMessage(host: WsHost, ws: WSContext, msg: ClientMessage, connection?: ConnectionState): Promise<void>;
 //# sourceMappingURL=dispatch.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"dispatch.d.ts","sourceRoot":"","sources":["../../src/ws/dispatch.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mCAAmC,CAAC;AACvE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAK9C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAYxC,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,SAAS,EACb,GAAG,EAAE,aAAa,GACjB,OAAO,CAAC,IAAI,CAAC,CAmKf"}
+{"version":3,"file":"dispatch.d.ts","sourceRoot":"","sources":["../../src/ws/dispatch.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mCAAmC,CAAC;AACvE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAK9C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAExC,qEAAqE;AACrE,MAAM,WAAW,eAAe;IAC9B,2EAA2E;IAC3E,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,EAC3B,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,WAAW,EAAE,OAAO,GACnB,OAAO,CAGT;AAED,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,SAAS,EACb,GAAG,EAAE,aAAa,EAClB,UAAU,GAAE,eAAoB,GAC/B,OAAO,CAAC,IAAI,CAAC,CA4Kf"}

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 });
             }

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,6 +43,22 @@ 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;
+    };
 }
 /**
  * Everything one WebSocket coordinator instance owns: turn state, the session
@@ -56,7 +74,26 @@ 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;
     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;
     /** 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":"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;AAC3D,OAAO,EAA6B,KAAK,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC1F,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAQnD;;;;;;;;;;;;;;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;IACrC;;;;;OAKG;IACH,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B;;;;OAIG;IACH,MAAM,CAAC,EAAE;QAAE,aAAa,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CACnD;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;IACpC,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;IACtC,QAAQ,CAAC,MAAM,EAAE;QAAE,aAAa,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IACjE,6EAA6E;IAC7E,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC,CAAC;IAClD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAE5B;gBAEU,OAAO,EAAE,aAAa;IAmBlC,8EAA8E;IAC9E,cAAc,IAAI,gBAAgB,GAAG,IAAI;IAIzC;;;;;;;OAOG;IACH,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI;IASzD,yEAAyE;IACzE,aAAa,CAAC,GAAG,EAAE,aAAa,GAAG,IAAI;IAIvC,0DAA0D;IAC1D,WAAW,CAAC,EAAE,EAAE,SAAS,EAAE,GAAG,EAAE,aAAa,GAAG,IAAI;CAGrD"}

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). */
@@ -41,6 +43,11 @@ export class WsHost {
     appName;
     turnTimeoutMs;
     maxConcurrentSessions;
+    observability;
+    wsRate;
+    /** Scoped instruments, resolved once — `[ws]` is the existing log prefix. */
+    log;
+    framesDropped;
     constructor(options) {
         this.registry = options.registry;
         this.catalog = options.catalog;
@@ -48,6 +55,36 @@ 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");
+        this.framesDropped = this.observability
+            .meter("ws")
+            .createCounter("ws.frames.dropped", {
+            description: "Inbound frames refused before reaching a handler",
+        });
+        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 },
+        });
     }
     /** Fan a frame out to every attached client (size-bounded per frame). */
     sendToClients(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,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;IAC3B,4EAA4E;IAC5E,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GACA,OAAO,CAAC,IAAI,CAAC,CAiHf;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,CAmGf"}