@schlessera/brain-ui-server 0.4.0

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

@@ -0,0 +1 @@
+{"version":3,"file":"attachments.d.ts","sourceRoot":"","sources":["../../src/ws/attachments.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mCAAmC,CAAC;AAQ7E,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAQ/D;AAED,wBAAgB,mBAAmB,CACjC,WAAW,EAAE,OAAO,GACnB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,WAAW,EAAE,mBAAmB,EAAE,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAiElF"}

package/dist/ws/attachments.js

@@ -0,0 +1,63 @@
+import { ALLOWED_IMAGE_MEDIA_TYPES, MAX_IMAGE_BYTES, MAX_IMAGES_PER_MESSAGE, MAX_TOTAL_IMAGE_BYTES, } from "@schlessera/brain-ui-sdk/protocol";
+export function estimateDecodedBase64Bytes(data) {
+    const normalized = data.replace(/\s/g, "");
+    const padding = normalized.endsWith("==")
+        ? 2
+        : normalized.endsWith("=")
+            ? 1
+            : 0;
+    return Math.floor((normalized.length * 3) / 4) - padding;
+}
+export function validateAttachments(attachments) {
+    if (attachments === undefined) {
+        return { ok: true, attachments: [] };
+    }
+    if (!Array.isArray(attachments)) {
+        return { ok: false, reason: "Attachments must be an array" };
+    }
+    if (attachments.length > MAX_IMAGES_PER_MESSAGE) {
+        return {
+            ok: false,
+            reason: `Too many images attached; maximum is ${MAX_IMAGES_PER_MESSAGE}`,
+        };
+    }
+    let totalBytes = 0;
+    const validated = [];
+    for (const attachment of attachments) {
+        if (!attachment ||
+            typeof attachment !== "object" ||
+            typeof attachment.data !== "string") {
+            return { ok: false, reason: "Each attachment must include base64 image data" };
+        }
+        const data = attachment.data;
+        if (data.length === 0 ||
+            data.length % 4 !== 0 ||
+            !/^[A-Za-z0-9+/]+={0,2}$/.test(data)) {
+            return { ok: false, reason: "Attachment data is not valid base64" };
+        }
+        const mediaType = attachment.mediaType;
+        if (!ALLOWED_IMAGE_MEDIA_TYPES.includes(mediaType)) {
+            return {
+                ok: false,
+                reason: `Unsupported image type: ${String(mediaType)}`,
+            };
+        }
+        const bytes = estimateDecodedBase64Bytes(attachment.data);
+        if (bytes > MAX_IMAGE_BYTES) {
+            return {
+                ok: false,
+                reason: `Image is too large; maximum decoded size is ${MAX_IMAGE_BYTES} bytes`,
+            };
+        }
+        totalBytes += bytes;
+        if (totalBytes > MAX_TOTAL_IMAGE_BYTES) {
+            return {
+                ok: false,
+                reason: `Attached images are too large; maximum total decoded size is ${MAX_TOTAL_IMAGE_BYTES} bytes`,
+            };
+        }
+        validated.push(attachment);
+    }
+    return { ok: true, attachments: validated };
+}
+//# sourceMappingURL=attachments.js.map

package/dist/ws/attachments.js.map

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

package/dist/ws/bridge.d.ts

@@ -0,0 +1,7 @@
+import type { BackendBridge } from "@schlessera/brain-ui-sdk/server";
+import type { RunningTurn } from "./turns.js";
+import type { WsHost } from "./host.js";
+/** Build the per-turn bridge the backend drives. */
+export declare function makeBridge(host: WsHost, turn: RunningTurn, promptText: string, backendId: string): BackendBridge;
+export declare function emitTurnError(host: WsHost, turn: RunningTurn, err: unknown): void;
+//# sourceMappingURL=bridge.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"bridge.d.ts","sourceRoot":"","sources":["../../src/ws/bridge.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,aAAa,EAId,MAAM,iCAAiC,CAAC;AAIzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAExC,oDAAoD;AACpD,wBAAgB,UAAU,CACxB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,WAAW,EACjB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,GAChB,aAAa,CAgGf;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,GAAG,EAAE,OAAO,GAAG,IAAI,CAsBjF"}

package/dist/ws/bridge.js

@@ -0,0 +1,86 @@
+import { BackendBusyError, BackendRequestError } from "@schlessera/brain-ui-sdk/server";
+import { hasClients } from "./clients.js";
+import { withTurnScope } from "./frames.js";
+/** Build the per-turn bridge the backend drives. */
+export function makeBridge(host, turn, promptText, backendId) {
+    const { coordinator, catalog } = host;
+    // Capture the turn identity at construction: the slot's turnId is re-minted
+    // for each queued follow-up, and a backend can still emit late frames
+    // through this bridge after its startTurn resolved. Stamping from the live
+    // field would attribute those to the NEXT turn.
+    const turnId = turn.turnId;
+    return {
+        emit: (msg) => {
+            if (msg.type === "session_info") {
+                turn.sessionId = msg.sessionId;
+                if (msg.providerId)
+                    turn.providerId = msg.providerId;
+                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.
+                catalog.persistSessionStub(msg.sessionId, promptText, turn.providerId, backendId);
+            }
+            host.sendToClients(withTurnScope(msg, turn, turnId));
+            if (msg.type === "result") {
+                catalog.persistSession(msg, promptText, turn.providerId, backendId);
+            }
+        },
+        requestPermission: (req) => {
+            host.sendToClients(withTurnScope({
+                type: "tool_approval_request",
+                toolUseId: req.toolUseId,
+                toolName: req.toolName,
+                input: req.input,
+                description: req.description,
+            }, turn, turnId));
+            host.sendToClients(withTurnScope({ type: "status", status: "tool_executing", detail: `Waiting for approval: ${req.toolName}` }, turn, turnId));
+            return new Promise((resolve) => {
+                if (coordinator.collidesAcrossTurns(coordinator.pendingApprovals, req.toolUseId, turn)) {
+                    resolve({ behavior: "deny", message: "Duplicate tool-approval id" });
+                    return;
+                }
+                coordinator.pendingApprovals.set(req.toolUseId, { turn, turnId, resolve });
+            });
+        },
+        askUser: (requestId, questions) => {
+            host.sendToClients(withTurnScope({ type: "ask_user_request", requestId, questions }, turn, turnId));
+            host.sendToClients(withTurnScope({ type: "status", status: "tool_executing", detail: "Waiting for your input" }, turn, turnId));
+            return new Promise((resolve, reject) => {
+                if (coordinator.collidesAcrossTurns(coordinator.pendingAskUser, requestId, turn)) {
+                    reject(new Error("Duplicate ask-user request id"));
+                    return;
+                }
+                coordinator.pendingAskUser.set(requestId, { turn, turnId, resolve, reject });
+            });
+        },
+        getLocation: (options) => {
+            if (!hasClients()) {
+                return Promise.reject(new Error(`No ${host.appName} client is connected to read the location from.`));
+            }
+            const requestId = coordinator.nextLocationRequestId();
+            host.sendToClients(withTurnScope({ type: "location_request", requestId, options }, turn, turnId));
+            host.sendToClients(withTurnScope({ type: "status", status: "tool_executing", detail: "Requesting your location" }, turn, turnId));
+            return new Promise((resolve, reject) => {
+                if (coordinator.collidesAcrossTurns(coordinator.pendingLocation, requestId, turn)) {
+                    reject(new Error("Duplicate location request id"));
+                    return;
+                }
+                coordinator.pendingLocation.set(requestId, { turn, turnId, resolve, reject });
+            });
+        },
+    };
+}
+export function emitTurnError(host, turn, err) {
+    // startTurn resolves for runtime failures (it emits its own error frame); it
+    // only rejects for caller errors.
+    if (err instanceof BackendBusyError) {
+        host.sendToClients(withTurnScope({ type: "error", code: "SESSION_BUSY", message: "That session already has a running turn." }, turn));
+    }
+    else if (err instanceof BackendRequestError) {
+        host.sendToClients(withTurnScope({ type: "error", code: "BACKEND_REQUEST_ERROR", message: err.message }, turn));
+    }
+    else {
+        host.sendToClients(withTurnScope({ type: "error", code: "BACKEND_ERROR", message: err instanceof Error ? err.message : String(err) }, turn));
+    }
+}
+//# sourceMappingURL=bridge.js.map

package/dist/ws/bridge.js.map

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

package/dist/ws/clients.d.ts

@@ -0,0 +1,20 @@
+import type { ServerMessage } from "@schlessera/brain-ui-sdk/protocol";
+/** Minimal structural view of a live socket — all we need to write to it. */
+export type WSContext = {
+    send: (data: string) => void;
+};
+export declare function addClient(ws: WSContext): void;
+export declare function removeClient(ws: WSContext): void;
+export declare function clientCount(): number;
+export declare function hasClients(): boolean;
+/** Test-only: drop all registered sockets. */
+export declare function resetClientsForTests(): void;
+/** Serialize + size-bound a frame, then send it to one specific socket. */
+export declare function sendTo(ws: WSContext, msg: ServerMessage): void;
+/**
+ * Broadcast a frame to every attached client. Serializes once. A failing
+ * socket is skipped (its `onClose` will prune it) so one dead peer can't
+ * block delivery to the others.
+ */
+export declare function broadcast(msg: ServerMessage): void;
+//# sourceMappingURL=clients.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"clients.d.ts","sourceRoot":"","sources":["../../src/ws/clients.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mCAAmC,CAAC;AAGvE,6EAA6E;AAC7E,MAAM,MAAM,SAAS,GAAG;IAAE,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;CAAE,CAAC;AAWzD,wBAAgB,SAAS,CAAC,EAAE,EAAE,SAAS,GAAG,IAAI,CAE7C;AAED,wBAAgB,YAAY,CAAC,EAAE,EAAE,SAAS,GAAG,IAAI,CAEhD;AAED,wBAAgB,WAAW,IAAI,MAAM,CAEpC;AAED,wBAAgB,UAAU,IAAI,OAAO,CAEpC;AAED,8CAA8C;AAC9C,wBAAgB,oBAAoB,IAAI,IAAI,CAE3C;AAED,2EAA2E;AAC3E,wBAAgB,MAAM,CAAC,EAAE,EAAE,SAAS,EAAE,GAAG,EAAE,aAAa,GAAG,IAAI,CAE9D;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,aAAa,GAAG,IAAI,CAUlD"}

package/dist/ws/clients.js

@@ -0,0 +1,48 @@
+import { shrinkForReplication } from "./shrink.js";
+/**
+ * Every currently-attached client socket. The active agent turn is a
+ * process-global singleton (server/src/ws/handler.ts), so all sockets observe
+ * the same conversation; streamed output fans out to all of them.
+ * Previously the server held a single `activeWs`, so a second connection
+ * silently orphaned the first (it stayed open but never received output).
+ */
+const clients = new Set();
+export function addClient(ws) {
+    clients.add(ws);
+}
+export function removeClient(ws) {
+    clients.delete(ws);
+}
+export function clientCount() {
+    return clients.size;
+}
+export function hasClients() {
+    return clients.size > 0;
+}
+/** Test-only: drop all registered sockets. */
+export function resetClientsForTests() {
+    clients.clear();
+}
+/** Serialize + size-bound a frame, then send it to one specific socket. */
+export function sendTo(ws, msg) {
+    ws.send(JSON.stringify(shrinkForReplication(msg)));
+}
+/**
+ * Broadcast a frame to every attached client. Serializes once. A failing
+ * socket is skipped (its `onClose` will prune it) so one dead peer can't
+ * block delivery to the others.
+ */
+export function broadcast(msg) {
+    if (clients.size === 0)
+        return;
+    const payload = JSON.stringify(shrinkForReplication(msg));
+    for (const ws of clients) {
+        try {
+            ws.send(payload);
+        }
+        catch {
+            // Drop; the socket's onClose handler removes it from the set.
+        }
+    }
+}
+//# sourceMappingURL=clients.js.map

package/dist/ws/clients.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clients.js","sourceRoot":"","sources":["../../src/ws/clients.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAKnD;;;;;;GAMG;AACH,MAAM,OAAO,GAAG,IAAI,GAAG,EAAa,CAAC;AAErC,MAAM,UAAU,SAAS,CAAC,EAAa;IACrC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;AAClB,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,EAAa;IACxC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;AACrB,CAAC;AAED,MAAM,UAAU,WAAW;IACzB,OAAO,OAAO,CAAC,IAAI,CAAC;AACtB,CAAC;AAED,MAAM,UAAU,UAAU;IACxB,OAAO,OAAO,CAAC,IAAI,GAAG,CAAC,CAAC;AAC1B,CAAC;AAED,8CAA8C;AAC9C,MAAM,UAAU,oBAAoB;IAClC,OAAO,CAAC,KAAK,EAAE,CAAC;AAClB,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,MAAM,CAAC,EAAa,EAAE,GAAkB;IACtD,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,oBAAoB,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;AACrD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAC,GAAkB;IAC1C,IAAI,OAAO,CAAC,IAAI,KAAK,CAAC;QAAE,OAAO;IAC/B,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,oBAAoB,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1D,KAAK,MAAM,EAAE,IAAI,OAAO,EAAE,CAAC;QACzB,IAAI,CAAC;YACH,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACnB,CAAC;QAAC,MAAM,CAAC;YACP,8DAA8D;QAChE,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/ws/connection.d.ts

@@ -0,0 +1,8 @@
+import { websocket } from "hono/bun";
+import type { WsHost } from "./host.js";
+export { websocket };
+/** Build the Hono WebSocket upgrade handler bound to one host. */
+export declare function createWsUpgrade(host: WsHost): import("hono").MiddlewareHandler<any, string, {
+    outputFormat: "ws";
+}>;
+//# sourceMappingURL=connection.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../../src/ws/connection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoB,SAAS,EAAE,MAAM,UAAU,CAAC;AAQvD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAExC,OAAO,EAAE,SAAS,EAAE,CAAC;AAErB,kEAAkE;AAClE,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM;;GAsH3C"}

package/dist/ws/connection.js

@@ -0,0 +1,116 @@
+import { upgradeWebSocket, websocket } from "hono/bun";
+import { PROTOCOL_REV } from "@schlessera/brain-ui-sdk/protocol";
+import { parseClientMessage } from "@schlessera/brain-ui-sdk/schemas";
+import { getBackendForSession } from "../agent/backend.js";
+import { addClient, removeClient, hasClients } from "./clients.js";
+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(() => ({
+        async onOpen(_evt, ws) {
+            console.log("[ws] Client connected");
+            const { coordinator, catalog } = host;
+            // Handshake first (rev 2, additive): protocol revision + coarse
+            // capabilities, so the client can gate behavior instead of sniffing.
+            host.sendMessage(ws, {
+                type: "server_hello",
+                protocolRev: PROTOCOL_REV,
+                capabilities: { multiSession: true, askUser: true, location: true },
+            });
+            // Snapshot-on-connect only for the single-running-session case (backward
+            // compatible). With zero or several running sessions the client rehydrates
+            // itself per-session via session_resume, and live frames (sessionId-scoped)
+            // fan out to it once it joins the broadcast set.
+            const runningTurns = [...coordinator.running].filter((t) => t.sessionId);
+            if (runningTurns.length === 1) {
+                const turn = runningTurns[0];
+                const sid = turn.sessionId;
+                host.sendMessage(ws, 
+                // Stamp the live turn identity: a reconnecting client must learn the
+                // current turnId, or the correlation guarantee dies at the reconnect
+                // it exists for.
+                withTurnScope({
+                    type: "session_info",
+                    sessionId: sid,
+                    isNew: false,
+                    providerId: turn.providerId ?? catalog.getStoredProviderId(sid) ?? undefined,
+                }, turn));
+                try {
+                    const backend = await getBackendForSession(catalog.getStoredBackendId(sid) ?? turn.backend.id);
+                    const history = await backend.getHistory(sid);
+                    if (history.length > 0)
+                        sendSessionHistory(ws, sid, history);
+                }
+                catch (err) {
+                    console.error("[ws] snapshot-on-connect failed:", err);
+                }
+                finally {
+                    addClient(ws);
+                    host.sendMessage(ws, withTurnScope({
+                        type: "status",
+                        status: "thinking",
+                        detail: "Session in progress",
+                        sessionId: sid,
+                    }, turn));
+                }
+                return;
+            }
+            addClient(ws);
+            host.sendMessage(ws, {
+                type: "status",
+                status: "idle",
+                detail: `Connected to ${host.appName}`,
+            });
+        },
+        onMessage(evt, ws) {
+            // Boundary validation (rev 2): byte cap + JSON decode + schema, in one
+            // place. No more casting client JSON to ClientMessage.
+            //
+            // Text frames only: hono's Bun adapter hands binary frames over as the
+            // 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.
+            const raw = evt.data;
+            if (typeof raw !== "string") {
+                host.sendMessage(ws, {
+                    type: "error",
+                    code: "PARSE_ERROR",
+                    message: "Binary frames are not supported; send JSON text",
+                });
+                return;
+            }
+            const parsed = parseClientMessage(raw);
+            if (!parsed.ok) {
+                host.sendMessage(ws, { type: "error", code: "PARSE_ERROR", message: parsed.error });
+                return;
+            }
+            // 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))
+                .catch(() => {
+                host.sendMessage(ws, {
+                    type: "error",
+                    code: "INTERNAL_ERROR",
+                    message: "Failed to handle message",
+                });
+            });
+        },
+        onClose(_evt, ws) {
+            console.log("[ws] Client disconnected");
+            removeClient(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.
+            if (hasClients())
+                return;
+            for (const turn of host.coordinator.running) {
+                host.coordinator.drainPendingForTurn(turn, "Client disconnected");
+            }
+        },
+    }));
+}
+//# sourceMappingURL=connection.js.map

package/dist/ws/connection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection.js","sourceRoot":"","sources":["../../src/ws/connection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,MAAM,mCAAmC,CAAC;AACjE,OAAO,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AACtE,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AACnE,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAGpD,OAAO,EAAE,SAAS,EAAE,CAAC;AAErB,kEAAkE;AAClE,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,OAAO,gBAAgB,CAAC,GAAG,EAAE,CAAC,CAAC;QAC7B,KAAK,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE;YACnB,OAAO,CAAC,GAAG,CAAC,uBAAuB,CAAC,CAAC;YACrC,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;YAEtC,gEAAgE;YAChE,qEAAqE;YACrE,IAAI,CAAC,WAAW,CAAC,EAAE,EAAE;gBACnB,IAAI,EAAE,cAAc;gBACpB,WAAW,EAAE,YAAY;gBACzB,YAAY,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE;aACpE,CAAC,CAAC;YAEH,yEAAyE;YACzE,2EAA2E;YAC3E,4EAA4E;YAC5E,iDAAiD;YACjD,MAAM,YAAY,GAAG,CAAC,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;YACzE,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBAC9B,MAAM,IAAI,GAAG,YAAY,CAAC,CAAC,CAAC,CAAC;gBAC7B,MAAM,GAAG,GAAG,IAAI,CAAC,SAAU,CAAC;gBAC5B,IAAI,CAAC,WAAW,CACd,EAAE;gBACF,qEAAqE;gBACrE,qEAAqE;gBACrE,iBAAiB;gBACjB,aAAa,CACX;oBACE,IAAI,EAAE,cAAc;oBACpB,SAAS,EAAE,GAAG;oBACd,KAAK,EAAE,KAAK;oBACZ,UAAU,EAAE,IAAI,CAAC,UAAU,IAAI,OAAO,CAAC,mBAAmB,CAAC,GAAG,CAAC,IAAI,SAAS;iBAC7E,EACD,IAAI,CACL,CACF,CAAC;gBACF,IAAI,CAAC;oBACH,MAAM,OAAO,GAAG,MAAM,oBAAoB,CACxC,OAAO,CAAC,kBAAkB,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,EAAE,CACnD,CAAC;oBACF,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;oBAC9C,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC;wBAAE,kBAAkB,CAAC,EAAE,EAAE,GAAG,EAAE,OAAO,CAAC,CAAC;gBAC/D,CAAC;gBAAC,OAAO,GAAG,EAAE,CAAC;oBACb,OAAO,CAAC,KAAK,CAAC,kCAAkC,EAAE,GAAG,CAAC,CAAC;gBACzD,CAAC;wBAAS,CAAC;oBACT,SAAS,CAAC,EAAE,CAAC,CAAC;oBACd,IAAI,CAAC,WAAW,CACd,EAAE,EACF,aAAa,CACX;wBACE,IAAI,EAAE,QAAQ;wBACd,MAAM,EAAE,UAAU;wBAClB,MAAM,EAAE,qBAAqB;wBAC7B,SAAS,EAAE,GAAG;qBACf,EACD,IAAI,CACL,CACF,CAAC;gBACJ,CAAC;gBACD,OAAO;YACT,CAAC;YAED,SAAS,CAAC,EAAE,CAAC,CAAC;YACd,IAAI,CAAC,WAAW,CAAC,EAAE,EAAE;gBACnB,IAAI,EAAE,QAAQ;gBACd,MAAM,EAAE,MAAM;gBACd,MAAM,EAAE,gBAAgB,IAAI,CAAC,OAAO,EAAE;aACvC,CAAC,CAAC;QACL,CAAC;QAED,SAAS,CAAC,GAAG,EAAE,EAAE;YACf,uEAAuE;YACvE,uDAAuD;YACvD,EAAE;YACF,uEAAuE;YACvE,wEAAwE;YACxE,sEAAsE;YACtE,uDAAuD;YACvD,MAAM,GAAG,GAAG,GAAG,CAAC,IAAI,CAAC;YACrB,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;gBAC5B,IAAI,CAAC,WAAW,CAAC,EAAE,EAAE;oBACnB,IAAI,EAAE,OAAO;oBACb,IAAI,EAAE,aAAa;oBACnB,OAAO,EAAE,iDAAiD;iBAC3D,CAAC,CAAC;gBACH,OAAO;YACT,CAAC;YACD,MAAM,MAAM,GAAG,kBAAkB,CAAC,GAAG,CAAC,CAAC;YACvC,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;gBACf,IAAI,CAAC,WAAW,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC;gBACpF,OAAO;YACT,CAAC;YACD,mEAAmE;YACnE,0CAA0C;YAC1C,KAAK,OAAO,CAAC,OAAO,EAAE;iBACnB,IAAI,CAAC,GAAG,EAAE,CAAC,mBAAmB,CAAC,IAAI,EAAE,EAAE,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;iBACzD,KAAK,CAAC,GAAG,EAAE;gBACV,IAAI,CAAC,WAAW,CAAC,EAAE,EAAE;oBACnB,IAAI,EAAE,OAAO;oBACb,IAAI,EAAE,gBAAgB;oBACtB,OAAO,EAAE,0BAA0B;iBACpC,CAAC,CAAC;YACL,CAAC,CAAC,CAAC;QACP,CAAC;QAED,OAAO,CAAC,IAAI,EAAE,EAAE;YACd,OAAO,CAAC,GAAG,CAAC,0BAA0B,CAAC,CAAC;YACxC,YAAY,CAAC,EAAE,CAAC,CAAC;YACjB,wEAAwE;YACxE,yEAAyE;YACzE,yBAAyB;YACzB,IAAI,UAAU,EAAE;gBAAE,OAAO;YACzB,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,WAAW,CAAC,OAAO,EAAE,CAAC;gBAC5C,IAAI,CAAC,WAAW,CAAC,mBAAmB,CAAC,IAAI,EAAE,qBAAqB,CAAC,CAAC;YACpE,CAAC;QACH,CAAC;KACF,CAAC,CAAC,CAAC;AACN,CAAC"}

package/dist/ws/dispatch.d.ts

@@ -0,0 +1,5 @@
+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>;
+//# sourceMappingURL=dispatch.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch.d.ts","sourceRoot":"","sources":["../../src/ws/dispatch.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mCAAmC,CAAC;AAEvE,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,CA0If"}

package/dist/ws/dispatch.js

@@ -0,0 +1,139 @@
+import { getBackendForSession } from "../agent/backend.js";
+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.
+ */
+function turnIdMatches(pending, echoed) {
+    return echoed === undefined || echoed === pending.turnId;
+}
+export async function handleClientMessage(host, ws, msg) {
+    const { coordinator, catalog } = host;
+    switch (msg.type) {
+        case "chat_message": {
+            const attachmentResult = validateAttachments(msg.attachments);
+            if (!attachmentResult.ok) {
+                host.sendMessage(ws, {
+                    type: "error",
+                    code: "ATTACHMENT_REJECTED",
+                    message: attachmentResult.reason,
+                    ...(msg.sessionId ? { sessionId: msg.sessionId } : {}),
+                });
+                return;
+            }
+            await handleChatMessage(host, ws, msg.text, msg.sessionId, attachmentResult.attachments, msg.providerId);
+            break;
+        }
+        case "ask_user_response": {
+            const pending = coordinator.pendingAskUser.get(msg.requestId);
+            if (pending && turnIdMatches(pending, msg.turnId)) {
+                coordinator.pendingAskUser.delete(msg.requestId);
+                pending.resolve({ answers: msg.answers, annotations: msg.annotations });
+            }
+            break;
+        }
+        case "ask_user_cancel": {
+            const pending = coordinator.pendingAskUser.get(msg.requestId);
+            if (pending && turnIdMatches(pending, msg.turnId)) {
+                coordinator.pendingAskUser.delete(msg.requestId);
+                pending.reject(new Error(msg.reason || "User cancelled the question"));
+            }
+            break;
+        }
+        case "location_response": {
+            const pending = coordinator.pendingLocation.get(msg.requestId);
+            if (pending && turnIdMatches(pending, msg.turnId)) {
+                coordinator.pendingLocation.delete(msg.requestId);
+                pending.resolve({ coords: msg.coords, timestamp: msg.timestamp });
+            }
+            break;
+        }
+        case "location_error": {
+            const pending = coordinator.pendingLocation.get(msg.requestId);
+            if (pending && turnIdMatches(pending, msg.turnId)) {
+                coordinator.pendingLocation.delete(msg.requestId);
+                pending.reject(new Error(locationErrorText(msg.code, msg.message)));
+            }
+            break;
+        }
+        case "tool_approval": {
+            const pending = coordinator.pendingApprovals.get(msg.toolUseId);
+            if (pending && turnIdMatches(pending, msg.turnId)) {
+                coordinator.pendingApprovals.delete(msg.toolUseId);
+                pending.resolve(msg.updatedInput
+                    ? { behavior: "allow", updatedInput: msg.updatedInput }
+                    : { behavior: "allow" });
+            }
+            break;
+        }
+        case "tool_denial": {
+            const pending = coordinator.pendingApprovals.get(msg.toolUseId);
+            if (pending && turnIdMatches(pending, msg.turnId)) {
+                coordinator.pendingApprovals.delete(msg.toolUseId);
+                pending.resolve({ behavior: "deny", message: msg.message });
+            }
+            break;
+        }
+        case "cancel": {
+            if (msg.sessionId) {
+                const turn = coordinator.bySession.get(msg.sessionId);
+                if (turn)
+                    coordinator.cancelTurn(turn, "Cancelled by user");
+                return;
+            }
+            // No sessionId: cancel the sole running session; ambiguous if several run.
+            if (coordinator.running.size === 0)
+                return;
+            if (coordinator.running.size > 1) {
+                host.sendMessage(ws, {
+                    type: "error",
+                    code: "CANCEL_AMBIGUOUS",
+                    message: "Several sessions are running — specify which to cancel.",
+                });
+                return;
+            }
+            coordinator.cancelTurn([...coordinator.running][0], "Cancelled by user");
+            break;
+        }
+        case "session_resume": {
+            host.sendMessage(ws, {
+                type: "session_info",
+                sessionId: msg.sessionId,
+                isNew: false,
+                providerId: catalog.getStoredProviderId(msg.sessionId) ?? undefined,
+            });
+            try {
+                const backend = await getBackendForSession(catalog.getStoredBackendId(msg.sessionId));
+                const messages = await backend.getHistory(msg.sessionId);
+                sendSessionHistory(ws, msg.sessionId, messages);
+                // A resume of a RUNNING session (reattach) must not report idle: idle
+                // would clear the client's running badge and finish its streaming
+                // message mid-turn. Mirror the snapshot-on-connect status instead.
+                const runningTurn = coordinator.bySession.get(msg.sessionId);
+                host.sendMessage(ws, {
+                    type: "status",
+                    ...(runningTurn
+                        ? { status: "thinking", detail: "Session in progress" }
+                        : { status: "idle", detail: "Session loaded" }),
+                    sessionId: msg.sessionId,
+                    ...(runningTurn ? { turnId: runningTurn.turnId } : {}),
+                });
+            }
+            catch (err) {
+                host.sendMessage(ws, {
+                    type: "error",
+                    code: "SESSION_LOAD_ERROR",
+                    message: err instanceof Error ? err.message : "Failed to load session",
+                    sessionId: msg.sessionId,
+                });
+            }
+            break;
+        }
+    }
+}
+//# sourceMappingURL=dispatch.js.map

package/dist/ws/dispatch.js.map

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

package/dist/ws/frames.d.ts

@@ -0,0 +1,17 @@
+import type { ServerMessage } from "@schlessera/brain-ui-sdk/protocol";
+import type { RunningTurn } from "./turns.js";
+/**
+ * Stamp a session-scoped frame with a sessionId for client demux. Every
+ * ServerMessage is session-scoped (or carries its own sessionId), so this only
+ * fills in a missing id and never overwrites one the backend already set.
+ */
+export declare function withSessionId(msg: ServerMessage, sessionId: string | null): ServerMessage;
+/**
+ * Stamp a frame with the turn's session AND turn identity (rev 2). turnId lets
+ * the client correlate interactive round-trips (approvals / ask-user /
+ * location) with the exact turn that raised them, even across a reconnect.
+ */
+export declare function withTurnScope(msg: ServerMessage, turn: RunningTurn, turnId?: string): ServerMessage;
+/** Human-readable reason for a GeolocationPositionError code. */
+export declare function locationErrorText(code: number, fallback: string): string;
+//# sourceMappingURL=frames.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"frames.d.ts","sourceRoot":"","sources":["../../src/ws/frames.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mCAAmC,CAAC;AACvE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,aAAa,CAIzF;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,GAAG,EAAE,aAAa,EAClB,IAAI,EAAE,WAAW,EACjB,MAAM,GAAE,MAAoB,GAC3B,aAAa,CAIf;AAED,iEAAiE;AACjE,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAWxE"}

package/dist/ws/frames.js

@@ -0,0 +1,37 @@
+/**
+ * Stamp a session-scoped frame with a sessionId for client demux. Every
+ * ServerMessage is session-scoped (or carries its own sessionId), so this only
+ * fills in a missing id and never overwrites one the backend already set.
+ */
+export function withSessionId(msg, sessionId) {
+    if (!sessionId)
+        return msg;
+    if (msg.sessionId)
+        return msg;
+    return { ...msg, sessionId };
+}
+/**
+ * Stamp a frame with the turn's session AND turn identity (rev 2). turnId lets
+ * the client correlate interactive round-trips (approvals / ask-user /
+ * location) with the exact turn that raised them, even across a reconnect.
+ */
+export function withTurnScope(msg, turn, turnId = turn.turnId) {
+    const scoped = withSessionId(msg, turn.sessionId);
+    if (scoped.turnId)
+        return scoped;
+    return { ...scoped, turnId };
+}
+/** Human-readable reason for a GeolocationPositionError code. */
+export function locationErrorText(code, fallback) {
+    switch (code) {
+        case 1:
+            return "The user denied permission to share their location.";
+        case 2:
+            return "The user's location is currently unavailable.";
+        case 3:
+            return "Timed out while retrieving the user's location.";
+        default:
+            return fallback || "Failed to retrieve the user's location.";
+    }
+}
+//# sourceMappingURL=frames.js.map

package/dist/ws/frames.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frames.js","sourceRoot":"","sources":["../../src/ws/frames.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,GAAkB,EAAE,SAAwB;IACxE,IAAI,CAAC,SAAS;QAAE,OAAO,GAAG,CAAC;IAC3B,IAAK,GAA8B,CAAC,SAAS;QAAE,OAAO,GAAG,CAAC;IAC1D,OAAO,EAAE,GAAG,GAAG,EAAE,SAAS,EAAmB,CAAC;AAChD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAC3B,GAAkB,EAClB,IAAiB,EACjB,SAAiB,IAAI,CAAC,MAAM;IAE5B,MAAM,MAAM,GAAG,aAAa,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;IAClD,IAAK,MAA8B,CAAC,MAAM;QAAE,OAAO,MAAM,CAAC;IAC1D,OAAO,EAAE,GAAG,MAAM,EAAE,MAAM,EAAmB,CAAC;AAChD,CAAC;AAED,iEAAiE;AACjE,MAAM,UAAU,iBAAiB,CAAC,IAAY,EAAE,QAAgB;IAC9D,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,CAAC;YACJ,OAAO,qDAAqD,CAAC;QAC/D,KAAK,CAAC;YACJ,OAAO,+CAA+C,CAAC;QACzD,KAAK,CAAC;YACJ,OAAO,iDAAiD,CAAC;QAC3D;YACE,OAAO,QAAQ,IAAI,yCAAyC,CAAC;IACjE,CAAC;AACH,CAAC"}