pi-sdk-web 0.5.16 → 0.5.17

package/dist/cli.js

@@ -9,7 +9,10 @@
  */
 import { SettingsManager, createAgentSessionFromServices, createAgentSessionRuntime, createAgentSessionServices, getAgentDir, resolveModelScopeWithDiagnostics, } from "@earendil-works/pi-coding-agent";
 import { existsSync } from "node:fs";
+import { spawn } from "node:child_process";
+import { totalmem } from "node:os";
 import { fileURLToPath } from "node:url";
+import { getHeapStatistics } from "node:v8";
 import { dirname, join } from "node:path";
 import { findSessionByName, listSessions, loadBuiltinExtensions } from "./session.js";
 import { PiWebServer } from "./server.js";
@@ -43,6 +46,68 @@ if (PI_CLI_ENTRY && process.argv[1] !== PI_CLI_ENTRY) {
     process.argv[1] = PI_CLI_ENTRY;
 }
 const DEFAULT_PORT = 4080;
+// ---------------------------------------------------------------------------
+// Heap headroom for long sessions.
+//
+// A large session plus in-process extensions (magic-context's local embedding
+// model, historians, indexes) can outgrow Node's default old-space limit -
+// ~2.2GB on a 15GB host - and abort the server mid-turn with
+// "FATAL ERROR: Reached heap limit". pi-web therefore restarts itself once
+// with a larger --max-old-space-size, but only for the long-running `r`
+// command and only when the host has memory to spare.
+//
+// Override the target with PI_WEB_MAX_OLD_SPACE_MB=<mb>. An explicit
+// --max-old-space-size in NODE_OPTIONS / argv is always respected untouched,
+// and the restart happens at most once (PI_WEB_HEAP_REEXEC guard).
+// ---------------------------------------------------------------------------
+const DEFAULT_MAX_OLD_SPACE_MB = 4096;
+/** Current V8 old-space limit in MB (what the crash log calls the heap limit). */
+function heapLimitMb() {
+    return getHeapStatistics().heap_size_limit / (1024 * 1024);
+}
+function requestedHeapMb() {
+    const raw = Number(process.env.PI_WEB_MAX_OLD_SPACE_MB);
+    if (Number.isFinite(raw) && raw >= 512 && raw <= 32_768)
+        return Math.floor(raw);
+    return DEFAULT_MAX_OLD_SPACE_MB;
+}
+/** Did the user (or a wrapper) already choose a heap size themselves? */
+function hasExplicitHeapFlag() {
+    const fromEnv = (process.env.NODE_OPTIONS ?? "").split(/\s+/);
+    return [...process.execArgv, ...fromEnv].some((arg) => /^--max[-_]old[-_]space[-_]size(=|$)/.test(arg));
+}
+/**
+ * Re-exec with a larger heap when needed. Returns true when a child has been
+ * started (the caller must stop: this process only waits for it).
+ */
+function ensureHeapHeadroom() {
+    if (process.env.PI_WEB_HEAP_REEXEC === "1")
+        return false; // already restarted
+    if (hasExplicitHeapFlag())
+        return false; // user decided - leave it alone
+    const target = requestedHeapMb();
+    if (heapLimitMb() >= target * 0.95)
+        return false; // close enough already
+    const totalMb = totalmem() / (1024 * 1024);
+    if (totalMb < target * 2) {
+        console.log(`heap: keeping the default limit (${heapLimitMb().toFixed(0)}MB) - ` +
+            `raising it to ${target}MB needs ~${target * 2}MB of RAM, host has ${totalMb.toFixed(0)}MB`);
+        return false;
+    }
+    console.log(`heap: restarting with --max-old-space-size=${target} (current limit ${heapLimitMb().toFixed(0)}MB)`);
+    const child = spawn(process.execPath, [`--max-old-space-size=${target}`, fileURLToPath(import.meta.url), ...process.argv.slice(2)], { stdio: "inherit", env: { ...process.env, PI_WEB_HEAP_REEXEC: "1" } });
+    // Stay alive without acting on the signal ourselves: the child is in the
+    // same process group and runs its own graceful shutdown, and we exit with
+    // its status once it is done.
+    process.on("SIGINT", () => { });
+    process.on("SIGTERM", () => { });
+    child.on("exit", (code, signal) => process.exit(signal ? 1 : (code ?? 1)));
+    child.on("error", (err) => {
+        console.error(`heap: failed to restart with a larger heap: ${err.message}`);
+        process.exit(1);
+    });
+    return true;
+}
 const DOC = `pi-web - browser Web access for Pi (via Pi SDK)
 
 Usage:
@@ -122,6 +187,7 @@ async function cmdResume(name, port) {
     const server = new PiWebServer(runtime, { port });
     await server.start();
     console.log(`server at http://127.0.0.1:${port}/ (session: ${info.name ?? info.id})`);
+    console.log(`heap limit: ${heapLimitMb().toFixed(0)}MB`);
     let shuttingDown = false;
     const shutdown = async (signal) => {
         if (shuttingDown)
@@ -178,6 +244,10 @@ async function main() {
         }
         if (!name)
             throw new Error("usage: pi-web r <name> [--port <port>]");
+        // Before anything heavy (session open, extensions): make sure this process
+        // has enough heap. A restart here means the child takes over the command.
+        if (ensureHeapHeadroom())
+            return;
         await cmdResume(name, port ?? DEFAULT_PORT);
         return;
     }

package/dist/server.js

@@ -64,6 +64,31 @@ const STATS_REFRESH_EVENTS = new Set([
     "session_info_changed",
     "thinking_level_changed",
 ]);
+// ---------------------------------------------------------------------------
+// WebSocket backpressure guard.
+//
+// `ws.send()` queues in process memory without bound when the peer reads
+// slowly - a backgrounded/throttled tab is the common case. A long turn (LLM
+// deltas) or a long `!! … --follow` stream then grows the process until the
+// V8 heap dies (observed: FATAL ERROR: Reached heap limit after ~70 minutes).
+//
+// Two limits, per client:
+//   SOFT - above this, *self-healing* delta events are skipped rather than
+//          queued. They carry no unique information: message_update /
+//          tool_execution_update re-render from the full payload of the next
+//          event, and message_end / tool_execution_end / bash_result deliver
+//          the complete state.
+//   HARD - above this the client is treated as gone and terminated. The
+//          browser reconnects (static/app.js) and reloads, fetching fresh
+//          session history - so nothing is lost, and memory is bounded.
+// ---------------------------------------------------------------------------
+const WS_BUFFER_SOFT_LIMIT = 8 * 1024 * 1024;
+const WS_BUFFER_HARD_LIMIT = 64 * 1024 * 1024;
+const DROPPABLE_DELTA_EVENTS = new Set(["message_update", "tool_execution_update"]);
+/** RSS watermarks (MB) at which to log one diagnostic line: growth curve plus
+ * what each client has queued, so a future OOM report says where it went. */
+const MEMORY_LOG_THRESHOLDS_MB = [512, 1024, 1536, 2048];
+const MEMORY_LOG_INTERVAL_MS = 30_000;
 const MIME = {
     ".html": "text/html; charset=utf-8",
     ".css": "text/css; charset=utf-8",
@@ -83,6 +108,11 @@ export class PiWebServer {
     wsServer = null;
     clients = new Set();
     unsubscribe = null;
+    /** Clients currently over the soft buffer limit (delta skipping active). */
+    backpressured = new WeakSet();
+    /** Memory watermarks already logged (diagnostics), and throttle clock. */
+    memoryLogged = new Set();
+    lastMemoryCheck = 0;
     /** Current session (may change on /resume session switching). */
     get session() {
         return this.runtime.session;
@@ -233,9 +263,33 @@ export class PiWebServer {
         catch {
             return;
         }
-        for (const client of this.clients) {
+        const type = obj.type;
+        const droppable = typeof type === "string" && DROPPABLE_DELTA_EVENTS.has(type);
+        for (const client of [...this.clients]) {
             if (client.readyState !== WebSocket.OPEN)
                 continue;
+            const buffered = client.bufferedAmount;
+            if (buffered > WS_BUFFER_HARD_LIMIT) {
+                // Far beyond reading - treat as gone. The browser reconnects and
+                // reloads, so no state is lost, and memory stays bounded.
+                console.warn(`pi-web: client not reading (${(buffered / 1048576).toFixed(0)}MB queued) - closing it; ` +
+                    "the browser will reconnect and reload history");
+                this.backpressured.delete(client);
+                client.terminate();
+                continue;
+            }
+            if (droppable && buffered > WS_BUFFER_SOFT_LIMIT) {
+                if (!this.backpressured.has(client)) {
+                    this.backpressured.add(client);
+                    console.warn(`pi-web: client is behind (${(buffered / 1048576).toFixed(1)}MB queued) - ` +
+                        "skipping stream deltas until it catches up");
+                }
+                continue;
+            }
+            if (this.backpressured.has(client) && buffered < WS_BUFFER_SOFT_LIMIT / 2) {
+                this.backpressured.delete(client);
+                console.warn("pi-web: client caught up - stream deltas resumed");
+            }
             try {
                 client.send(message);
             }
@@ -246,6 +300,28 @@ export class PiWebServer {
                     this.uiContext.setBrowserAttached(false);
             }
         }
+        this.maybeLogMemory();
+    }
+    /**
+     * One diagnostic line per RSS watermark (plus what each client has queued),
+     * so a future out-of-memory report shows where the growth went. Throttled:
+     * `broadcast` runs per streaming delta and memoryUsage() is not free.
+     */
+    maybeLogMemory() {
+        const now = Date.now();
+        if (now - this.lastMemoryCheck < MEMORY_LOG_INTERVAL_MS)
+            return;
+        this.lastMemoryCheck = now;
+        const { rss, heapUsed, heapTotal } = process.memoryUsage();
+        const rssMb = rss / 1048576;
+        for (const threshold of MEMORY_LOG_THRESHOLDS_MB) {
+            if (rssMb < threshold || this.memoryLogged.has(threshold))
+                continue;
+            this.memoryLogged.add(threshold);
+            const queued = [...this.clients].map((c) => `${(c.bufferedAmount / 1048576).toFixed(1)}MB`).join(", ") || "no clients";
+            console.warn(`pi-web: memory ${rssMb.toFixed(0)}MB (heap ${(heapUsed / 1048576).toFixed(0)}/` +
+                `${(heapTotal / 1048576).toFixed(0)}MB), queued per client: ${queued}`);
+        }
     }
     broadcastStats() {
         try {
@@ -348,9 +424,17 @@ export class PiWebServer {
         }
     }
     sendJson(ws, obj) {
-        if (ws.readyState === WebSocket.OPEN) {
-            ws.send(JSON.stringify(obj));
+        if (ws.readyState !== WebSocket.OPEN)
+            return;
+        // Same hard limit as broadcast(): the initial state/history snapshot is
+        // the largest single payload, so a client that never reads it must not be
+        // allowed to queue forever.
+        if (ws.bufferedAmount > WS_BUFFER_HARD_LIMIT) {
+            console.warn("pi-web: client not reading its initial snapshot - closing it");
+            ws.terminate();
+            return;
         }
+        ws.send(JSON.stringify(obj));
     }
     buildState() {
         const state = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-sdk-web",
-  "version": "0.5.16",
+  "version": "0.5.17",
   "description": "Browser Web access for Pi (AI coding agent) via the Pi SDK - standalone module, zero modification to Pi itself",
   "type": "module",
   "bin": {