pi-sdk-web 0.5.16 → 0.5.18

package/dist/cli.js

@@ -9,10 +9,14 @@
  */
 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";
+import { logError, logInfo } from "./log.js";
 // ---------------------------------------------------------------------------
 // Pretend to be Pi for in-process extensions.
 //
@@ -43,6 +47,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) {
+        logInfo(`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;
+    }
+    logInfo(`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) => {
+        logError(`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:
@@ -80,7 +146,7 @@ async function cmdResume(name, port) {
         }
         catch {
             // Session cwd no longer exists - keep current directory (same as pii)
-            console.error(`Session cwd not found (${cwd}), keeping current directory`);
+            logError(`Session cwd not found (${cwd}), keeping current directory`);
         }
     }
     // Create services the way Pi's CLI does: extensions (including built-in
@@ -121,13 +187,14 @@ async function cmdResume(name, port) {
     const { session } = runtime;
     const server = new PiWebServer(runtime, { port });
     await server.start();
-    console.log(`server at http://127.0.0.1:${port}/ (session: ${info.name ?? info.id})`);
+    logInfo(`server at http://127.0.0.1:${port}/ (session: ${info.name ?? info.id})`);
+    logInfo(`heap limit: ${heapLimitMb().toFixed(0)}MB`);
     let shuttingDown = false;
     const shutdown = async (signal) => {
         if (shuttingDown)
             return; // Repeated Ctrl+C must not re-enter teardown
         shuttingDown = true;
-        console.log(`\n${signal} received, shutting down...`);
+        logInfo(`${signal} received, shutting down...`);
         try {
             await server.stop();
         }
@@ -178,6 +245,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/log.js

@@ -0,0 +1,28 @@
+/**
+ * Timestamped logging for pi-web's own diagnostics.
+ *
+ * pi-web is a long-running server: its warnings (backpressure, memory
+ * watermarks, session issues) are read minutes to hours after the fact and
+ * mixed with other processes' output, so every line carries a local timestamp
+ * (`[2026-09-12 08:15:30] pi-web: …`).
+ *
+ * Only pi-web's own log lines go through here - command output (session
+ * lists, help text) stays plain so it can be piped or copied as-is.
+ */
+function timestamp(now) {
+    const pad = (n) => String(n).padStart(2, "0");
+    return (`${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())} ` +
+        `${pad(now.getHours())}:${pad(now.getMinutes())}:${pad(now.getSeconds())}`);
+}
+/** Informational line (startup, status) on stdout. */
+export function logInfo(message) {
+    console.log(`[${timestamp(new Date())}] ${message}`);
+}
+/** Diagnostic warning on stderr. */
+export function logWarn(message) {
+    console.warn(`[${timestamp(new Date())}] ${message}`);
+}
+/** Error line on stderr. */
+export function logError(message) {
+    console.error(`[${timestamp(new Date())}] ${message}`);
+}

package/dist/server.js

@@ -18,6 +18,7 @@ import { ModelRegistry, VERSION, } from "@earendil-works/pi-coding-agent";
 import { WebSocket, WebSocketServer } from "ws";
 import { listSessions } from "./session.js";
 import { WebUIContext } from "./ui-context.js";
+import { logError, logWarn } from "./log.js";
 const DEFAULT_PORT = 4080;
 // Static frontend: prefer the in-package copy (built by `npm run build` for
 // global installs), fall back to the repo-root static/ during development.
@@ -64,6 +65,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 +109,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;
@@ -172,7 +203,7 @@ export class PiWebServer {
                     process.chdir(cwd);
                 }
                 catch {
-                    console.error(`Session cwd not found (${cwd}), keeping current directory`);
+                    logError(`Session cwd not found (${cwd}), keeping current directory`);
                 }
             }
             this.broadcastState();
@@ -233,9 +264,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.
+                logWarn(`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);
+                    logWarn(`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);
+                logWarn("pi-web: client caught up - stream deltas resumed");
+            }
             try {
                 client.send(message);
             }
@@ -246,6 +301,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";
+            logWarn(`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 +425,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) {
+            logWarn("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.18",
   "description": "Browser Web access for Pi (AI coding agent) via the Pi SDK - standalone module, zero modification to Pi itself",
   "type": "module",
   "bin": {