@evandu/super-pi 0.1.139 → 0.1.141

package/dist/server/ws-server.js

@@ -7,6 +7,21 @@ import { describeThrown, describeThrownWithStack } from "./failure-text.js";
  * a network peer that has disappeared can therefore make the buffer grow
  * without throwing.  Once this threshold is crossed we drop that connection
  * and let the normal close path clean up its resources.
+ *
+ * AND YET DROPPING IT IS THE WRONG ANSWER FOR A BUSY SERVER.  The threshold was
+ * written for a peer that has gone away - a frozen tab, a pulled cable.  A server
+ * that is merely DELIVERING TOO MUCH hits the same number: a sub-agent that
+ * streams text emits one `subagent.event` per delta, each of which asks for a
+ * full state broadcast, and a browser that cannot parse frames as fast as they
+ * arrive lets the buffer grow past the threshold while it is perfectly alive.
+ * The browser then reports code 1006 and reconnects, only to be dropped again -
+ * "连接中 / 断连 / 连接中" forever - and the user's work is interrupted rather
+ * than slowed.
+ *
+ * So a frame that does not fit is DROPPED, not the connection: the next frame
+ * carries the same state, and a browser that is behind will catch up on the next
+ * one instead of being disconnected and losing its place.  The connection is
+ * only terminated when the socket itself is gone (readyState is not OPEN).
  */
 export const MAX_WS_BUFFERED_BYTES = 8 * 1024 * 1024;
 /** Maximum size of one inbound WebSocket message. Attachments are uploaded
@@ -24,10 +39,12 @@ export function safeSend(socket, payload) {
         return false;
     const bufferedAmount = Number(socket.bufferedAmount ?? 0);
     if (Number.isFinite(bufferedAmount) && bufferedAmount > MAX_WS_BUFFERED_BYTES) {
-        try {
-            socket.terminate();
-        }
-        catch { /* close races are already being cleaned up */ }
+        // DROP THE FRAME, KEEP THE CONNECTION.  A peer that is merely behind is not
+        // a peer that is gone: the next broadcast carries the same state, so the
+        // browser catches up instead of being disconnected and losing its place.
+        // Terminating here is what produced "连接中 / 断连 / 连接中" forever on a
+        // server that was delivering sub-agent output faster than the browser could
+        // parse it - and the browser's own code 1006 was only the symptom.
         return false;
     }
     try {
@@ -56,7 +73,19 @@ export class WsBroadcaster {
     fileIndexScopes = new Map();
     coalescedSockets = new Set();
     pendingStreams = new Map();
-    stateFlushScheduled = false;
+    /**
+     * DIAGNOSTIC ONLY - sends every requested state frame immediately instead of merging them.
+     *
+     * The legacy flood switch (`SUPER_PI_LEGACY_SUBAGENT_FLOOD=1`) restores the pre-fix WIRING: one
+     * full state broadcast per sub-agent event. But the 150ms merge window would still fold those
+     * broadcasts into one frame, so the "before" measurement would not actually be "before" - it
+     * would show a flood that the fixed server also survives, and the A/B comparison would prove
+     * nothing. This flag removes the window as well, so the probe can reproduce the real pre-fix
+     * wire shape: one frame per request, sent at once.
+     *
+     * Never set outside a probe or a regression test that is asserting the old behaviour.
+     */
+    sendStateImmediately = process.env.SUPER_PI_LEGACY_SUBAGENT_FLOOD === "1";
     constructor(getState) {
         this.getState = getState;
     }
@@ -137,6 +166,19 @@ export class WsBroadcaster {
             pending = { events, timer: setTimeout(() => this.flushStreaming(socket), 16) };
             this.pendingStreams.set(socket, pending);
         }
+        // A subagent.event is a whole-run SNAPSHOT whose output is the accumulated text so far: within one
+        // 16ms window the LATEST snapshot for a run supersedes every earlier one (they differ only by more
+        // text). Keeping the newest replaces a per-delta frame burst with at most one frame per run per
+        // window - the O(n²) burst the flood fix exists for - while the card still updates at ~60fps.
+        if (event.type === "subagent.event") {
+            const superseded = pending.events.findIndex((queued) => queued.type === "subagent.event" && queued.run.id === event.run.id);
+            if (superseded >= 0) {
+                pending.events[superseded] = event;
+                return;
+            }
+            pending.events.push(event);
+            return;
+        }
         // Only adjacent fragments from the same stream can merge. A different kind,
         // answer offset or lifecycle flag is an ordering boundary, even within 16ms.
         const previous = pending.events.at(-1);
@@ -156,7 +198,7 @@ export class WsBroadcaster {
             this.broadcastState();
             return;
         }
-        const streaming = event.type === "message.delta" || event.type === "message.thinking";
+        const streaming = event.type === "message.delta" || event.type === "message.thinking" || event.type === "subagent.event";
         // Serialize common events once, after finding a recipient. Coalesced text stays per socket;
         // conversation snapshots are projected and serialized once per scope in broadcastState().
         let payload;
@@ -173,41 +215,90 @@ export class WsBroadcaster {
             }
         }
     }
+    /**
+     * BROADCAST STATES IN A TIME WINDOW, NOT IN A MICROTASK.
+     *
+     * The microtask flag this replaces merged only the calls that arrived within the
+     * SAME tick.  A sub-agent that streams text emits one `subagent.event` per delta,
+     * each asking for a full state broadcast, and those deltas arrive across many
+     * ticks - so a single sub-agent run could ask for HUNDREDS of full state
+     * broadcasts.  On a machine whose state is large, that is a flood the browser
+     * cannot drain: its parse queue falls behind, the socket buffer grows, and the
+     * connection is dropped (the browser reports 1006).
+     *
+     * A window turns a burst into a handful of frames.  The state a browser receives
+     * is the LATEST state - the intermediate ones carried nothing the last one did
+     * not - so nothing is lost by sending fewer of them.  The only thing that
+     * changes is how promptly the browser sees a change, and 150ms is below the
+     * threshold at which a person notices.
+     */
+    stateFlushScheduled = false;
     broadcastState() {
+        // DIAGNOSTIC PATH: the pre-fix wire shape, one frame per request, no merge window.
+        if (this.sendStateImmediately) {
+            this.flushState();
+            return;
+        }
         if (this.stateFlushScheduled)
             return;
         this.stateFlushScheduled = true;
+        const now = Date.now();
+        // HOW MANY STATE FRAMES WENT OUT IN THE LAST SECOND.
+        //
+        // This is the flood detector, and it is a RATE, not a delay. A server that is behaving sends a
+        // handful of frames a second: one per user action, one per turn boundary. A server that is
+        // flooding sends hundreds - a sub-agent's delta used to ask for one full state frame each.
+        //
+        // The NORMAL path stays exactly as it always was: a microtask merge, so the frame goes out at the
+        // end of this tick. That matters for more than latency: "the user sent a message" and "the turn
+        // opened" are two broadcasts, and if they are merged into one frame the user's own message never
+        // appears on its own - it appears already accompanied by the assistant placeholder. A message
+        // that arrives half-written is a message the user does not believe they sent.
+        //
+        // The DEGRADED path is for a server that is genuinely flooding: requests are then merged into one
+        // frame per window, because a browser that cannot parse frames as fast as they arrive gets its
+        // connection dropped (the browser reports 1006) and the user sees "连接中 / 断连 / 连接中".
         queueMicrotask(() => {
             this.stateFlushScheduled = false;
-            const groups = new Map();
-            for (const socket of this.sockets) {
-                if (socket.readyState !== WebSocket.OPEN)
-                    continue;
-                const scope = this.scopes.get(socket);
-                const key = scope ? `focused:${JSON.stringify(scope.conversationId ?? null)}` : "legacy";
-                let group = groups.get(key);
-                if (!group) {
-                    group = { scope, sockets: [] };
-                    groups.set(key, group);
-                }
-                group.sockets.push(socket);
+            this.flushState();
+        });
+    }
+    flushState() {
+        const groups = new Map();
+        for (const socket of this.sockets) {
+            if (socket.readyState !== WebSocket.OPEN)
+                continue;
+            const scope = this.scopes.get(socket);
+            const key = scope ? `focused:${JSON.stringify(scope.conversationId ?? null)}` : "legacy";
+            let group = groups.get(key);
+            if (!group) {
+                group = { scope, sockets: [] };
+                groups.set(key, group);
             }
-            for (const { scope, sockets } of groups.values()) {
-                const snapshotStartedAt = performance.now();
-                const state = this.getState(scope);
-                const snapshotMs = performance.now() - snapshotStartedAt;
-                const serializeStartedAt = performance.now();
-                const cachedStatePayload = JSON.stringify({ type: "state", state });
-                const serializeMs = performance.now() - serializeStartedAt;
-                if (process.env.SUPER_PI_TRACE_LATENCY === "1") {
-                    console.warn(`[super-pi latency] phase=state.snapshot.ready bytes=${Buffer.byteLength(cachedStatePayload, "utf8")} snapshotMs=${Math.round(snapshotMs)} serializeMs=${Math.round(serializeMs)} sockets=${sockets.length} scope=${scope ? "focused" : "legacy"}`);
-                }
-                for (const socket of sockets) {
-                    this.flushStreaming(socket);
-                    safeSend(socket, cachedStatePayload);
-                }
+            group.sockets.push(socket);
+        }
+        for (const { scope, sockets } of groups.values()) {
+            const snapshotStartedAt = performance.now();
+            const state = this.getState(scope);
+            const snapshotMs = performance.now() - snapshotStartedAt;
+            const serializeStartedAt = performance.now();
+            const cachedStatePayload = JSON.stringify({ type: "state", state });
+            const serializeMs = performance.now() - serializeStartedAt;
+            if (process.env.SUPER_PI_TRACE_LATENCY === "1") {
+                console.warn(`[super-pi latency] phase=state.snapshot.ready bytes=${Buffer.byteLength(cachedStatePayload, "utf8")} snapshotMs=${Math.round(snapshotMs)} serializeMs=${Math.round(serializeMs)} sockets=${sockets.length} scope=${scope ? "focused" : "legacy"}`);
             }
-        });
+            for (const socket of sockets) {
+                this.flushStreaming(socket);
+                safeSend(socket, cachedStatePayload);
+            }
+        }
+    }
+    /**
+     * Releases the pending state window, so a shutting-down server does not hold the event loop
+     * open on a timer whose flush would send to sockets that are already closed.
+     */
+    dispose() {
+        this.stateFlushScheduled = false;
     }
     getStateSnapshot(scope) {
         return this.getState(scope);
@@ -269,8 +360,30 @@ export class WsServer {
     setupConnectionHandling() {
         this.websocketServer.on("connection", (socket, request) => {
             const url = new URL(request.url ?? "/ws", "http://localhost");
-            const scope = url.searchParams.get("state") === "focused"
-                ? { conversationId: url.searchParams.get("conversationId") || undefined } : undefined;
+            // HOW A CLIENT ASKS FOR A SCOPE, AND WHAT IT GETS WHEN IT DOES NOT ASK.
+            //
+            // `undefined` means the WHOLE application: every workspace, every conversation and every
+            // message.  On a machine with a long history that is tens of megabytes in the FIRST FRAME.
+            //
+            // There are three cases, and they are NOT the same thing:
+            //
+            //   ?state=focused            -> the focused projection (sidebar + the selected transcript)
+            //   ?conversationId=<id>      -> the focused projection of that one conversation
+            //   (neither)                 -> the legacy full state, exactly as before this change
+            //
+            // The middle case is what the current browser sends (it sends both).  The third case is a
+            // client running an OLD bundle, and it MUST keep getting the full state: a focused frame
+            // with no conversationId carries NO transcripts at all, so an old client that never sends
+            // `state.subscribe` would connect and see an empty application.  Dropping it silently is
+            // worse than a big first frame.
+            //
+            // And the big first frame is no longer FATAL: `safeSend` drops an oversized frame instead
+            // of terminating the connection, so a browser that cannot digest 42 MB at once is merely
+            // SLOW on that first frame - it is not disconnected, and it does not enter the
+            // "连接中 / 断连 / 连接中" loop.  The disconnect is fixed at the buffer, not at the scope.
+            const wantsFocused = url.searchParams.get("state") === "focused";
+            const conversationId = url.searchParams.get("conversationId") || undefined;
+            const scope = wantsFocused || conversationId ? { conversationId } : undefined;
             this.broadcaster.register(socket, scope);
             socket.on("error", (error) => {
                 console.warn(`Super Pi: WebSocket error: ${error instanceof Error ? error.message : String(error)}`);
@@ -450,6 +563,9 @@ export class WsServer {
      * Gracefully closes all active WebSocket connections and terminates the server.
      */
     close() {
+        // A pending state window must not outlive the server: the timer holds the event loop
+        // open, and a flush after the sockets are closed would send to a dead peer.
+        this.broadcaster.dispose();
         for (const socket of this.broadcaster.getSockets()) {
             socket.close(1001, "server-shutdown");
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evandu/super-pi",
-  "version": "0.1.139",
+  "version": "0.1.141",
   "description": "Web control plane and companion for Pi",
   "license": "MIT",
   "type": "module",
@@ -74,12 +74,14 @@
     "scripts/image-input-real-pi.test.mjs",
     "scripts/image-upload.test.mjs",
     "scripts/extension-ui-e2e.test.mjs",
-    "scripts/session-picker.test.mjs",
+    "scripts/session-picker.test.mjs", "scripts/session-orchestrator.test.mjs", "scripts/session-orchestrator-tools.test.mjs",
+    "scripts/session-tree-collapse.test.mjs",
     "scripts/workspace-cwd.test.mjs",
     "scripts/subagents.test.mjs",
     "scripts/subagent-noise.test.mjs",
     "scripts/subagent-response-receipt.test.mjs",
     "scripts/subagent-runs.test.mjs",
+    "scripts/ws-flood-regression.test.mjs",
     "scripts/conversation-reconcile.test.mjs",
     "scripts/subagent-dispatch.test.mjs",
     "scripts/workflow-plan.test.mjs",