pi-sdk-web 0.5.15 → 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;
@@ -91,12 +121,10 @@ export class PiWebServer {
         this.runtime = runtime;
         this.port = options.port ?? DEFAULT_PORT;
         this.staticDir = options.staticDir ?? STATIC_DIR;
-        this.uiContext = new WebUIContext((obj) => this.broadcast(obj), {
-            // Dialog timeout tier: with a browser attached the user may step away,
-            // so dialogs wait long; with none attached they settle after a short
-            // grace period instead of blocking the agent loop forever.
-            hasClients: () => this.clients.size > 0,
-        });
+        // Dialog timeouts follow client presence (see WebUIContext): attached ->
+        // wait indefinitely (TUI parity), detached -> fallback guard so a closed
+        // tab cannot block the agent loop. handleConnection / ws close update it.
+        this.uiContext = new WebUIContext((obj) => this.broadcast(obj));
     }
     // ------------------------------------------------------------------
     // Lifecycle
@@ -235,17 +263,65 @@ 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);
             }
             catch {
                 // One broken client must not block delivery to the others
                 this.clients.delete(client);
+                if (this.clients.size === 0)
+                    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 {
@@ -306,8 +382,17 @@ export class PiWebServer {
     // ------------------------------------------------------------------
     handleConnection(ws) {
         this.clients.add(ws);
-        ws.on("close", () => this.clients.delete(ws));
-        ws.on("error", () => this.clients.delete(ws));
+        // A browser is watching again: pending dialogs stop counting down (see
+        // WebUIContext.setBrowserAttached) - the user gets unlimited time.
+        this.uiContext.setBrowserAttached(true);
+        const onGone = () => {
+            this.clients.delete(ws);
+            // Last browser left: arm the fallback so dialogs cannot block the loop.
+            if (this.clients.size === 0)
+                this.uiContext.setBrowserAttached(false);
+        };
+        ws.on("close", onGone);
+        ws.on("error", onGone);
         ws.on("message", (data) => this.handleClientMessage(ws, String(data)));
         // Initial state (state + history), mirroring the Python bridge
         this.sendJson(ws, { type: "state", data: this.buildState() });
@@ -339,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/dist/static/app.js

@@ -204,6 +204,8 @@ class PiWebClient {
     this.modalList = document.getElementById('modal-list');
     this.modalClose = document.getElementById('modal-close');
     this.modalMode = null; // 'model' | 'thinking'
+    this.dialogCountdownTimer = null; // extension dialog countdown (TUI parity)
+    this.dialogCountdownBase = '';
     this.hasConnectedBefore = false;
     this.commandMenuIndex = -1;
     this.extStatus = {};
@@ -1794,6 +1796,7 @@ class PiWebClient {
 
   openModal(title, mode) {
     this.modalMode = mode;
+    this.stopDialogCountdown();
     this.modalTitle.textContent = title;
     this.modalSearch.value = '';
     this.modalList.innerHTML = '';
@@ -1801,6 +1804,29 @@ class PiWebClient {
     this.modalSearch.focus();
   }
 
+  /** Countdown for extension dialogs that carry a deadline (an extension's own
+   * opts.timeout). TUI shows the same "(Ns)" ticker; without a deadline the
+   * dialog waits indefinitely while a browser is attached. */
+  startDialogCountdown(req) {
+    this.stopDialogCountdown();
+    if (!req || typeof req.deadline !== 'number') return;
+    this.dialogCountdownBase = this.modalTitle.textContent || '';
+    const tick = () => {
+      const remain = Math.max(0, Math.ceil((req.deadline - Date.now()) / 1000));
+      this.modalTitle.textContent = `${this.dialogCountdownBase} (${remain}s)`;
+      if (remain <= 0) this.stopDialogCountdown();
+    };
+    tick();
+    this.dialogCountdownTimer = setInterval(tick, 1000);
+  }
+
+  stopDialogCountdown() {
+    if (this.dialogCountdownTimer) {
+      clearInterval(this.dialogCountdownTimer);
+      this.dialogCountdownTimer = null;
+    }
+  }
+
   closeModal() {
     // If an extension dialog (select/confirm/input/editor) was open, notify
     // the server that it was cancelled - otherwise the extension's promise
@@ -1814,6 +1840,7 @@ class PiWebClient {
     this.modalSearch.style.display = 'block';
     this.modalMode = null;
     this.currentExtRequest = null;
+    this.stopDialogCountdown();
     this.inputEl.focus();
   }
 
@@ -1920,6 +1947,7 @@ class PiWebClient {
   openExtensionSelect(req) {
     this.openModal(req.title || 'Select', 'extension-select');
     this.currentExtRequest = req;
+    this.startDialogCountdown(req);
     this.modalSearch.style.display = 'block';
     const items = (req.options || []).map((opt) => ({ name: opt, desc: '', value: opt }));
     this.renderModalItems(items, (item) => {
@@ -1930,6 +1958,7 @@ class PiWebClient {
   openExtensionConfirm(req) {
     this.openModal(req.title || 'Confirm', 'extension-confirm');
     this.currentExtRequest = req;
+    this.startDialogCountdown(req);
     this.modalSearch.style.display = 'none';
     this.modalList.innerHTML = `
       <div class="modal-message">${this.escapeHtml(req.message || '')}</div>
@@ -1950,6 +1979,7 @@ class PiWebClient {
   openExtensionInput(req) {
     this.openModal(req.title || 'Input', 'extension-input');
     this.currentExtRequest = req;
+    this.startDialogCountdown(req);
     this.modalSearch.style.display = 'none';
     this.modalList.innerHTML = `
       <div class="modal-message">${this.escapeHtml(req.message || '')}</div>
@@ -1979,6 +2009,7 @@ class PiWebClient {
   openExtensionEditor(req) {
     this.openModal(req.title || 'Editor', 'extension-editor');
     this.currentExtRequest = req;
+    this.startDialogCountdown(req);
     this.modalSearch.style.display = 'none';
     this.modalList.innerHTML = `
       <div class="modal-message">${this.escapeHtml(req.title || '')}</div>

package/dist/ui-context.js

@@ -3,21 +3,24 @@ import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 /**
- * Default dialog timeouts (pi-web specific guard).
+ * Fallback dialog timeout (pi-web specific guard).
  *
- * TUI and RPC block until the client answers - the user is at the terminal, or
- * the RPC client owns the timeout. A browser tab can be closed mid-turn, so a
- * dialog nobody can see would block the agent loop forever. Two tiers:
+ * TUI and RPC wait for an answer indefinitely - the user is at the terminal,
+ * or the RPC client owns the timeout. With a browser attached pi-web does the
+ * same: a dialog waits forever, so an answer is never taken away from the user
+ * just because they were busy elsewhere.
  *
- * - browser attached: the user may have stepped away; wait long, then settle
- *   with the dialog's default value (confirm -> false, others -> undefined);
- * - no browser attached: a closed tab must not stall the loop, but a page
- *   reload/reconnect takes a moment - short grace period, not instant.
+ * The one case that needs a guard is a browser that is NOT attached (tab
+ * closed mid-turn): nobody can answer, and an extension awaiting the dialog
+ * would block the agent loop forever. Then - and only then - the dialog
+ * settles after this grace period with its default value (confirm -> false,
+ * others -> undefined). Reconnecting cancels the fallback, so a user who comes
+ * back gets as much time as they need.
  *
- * Extensions that pass their own `timeout` (ms) keep it.
+ * Extensions that pass their own `timeout` (ms) keep it exactly (that timer is
+ * their decision, never cancelled here).
  */
-const DIALOG_TIMEOUT_MS = 10 * 60_000;
-const DIALOG_TIMEOUT_NO_CLIENT_MS = 60_000;
+const DIALOG_FALLBACK_TIMEOUT_MS = 10 * 60_000;
 /**
  * Load a Pi theme (dark.json/light.json colors) so extensions calling
  * ui.theme.fg("accent", text) / .bg(...) get REAL ANSI escapes — identical
@@ -85,18 +88,16 @@ export class WebUIContext {
     /** Latest setWidget lines per key (persistent widgets, e.g. TodoOverlay):
      * replayed to late-connecting browsers like setStatus snapshots. */
     widgetMap = new Map();
-    hasClients;
-    dialogTimeoutMs;
-    dialogTimeoutNoClientMs;
+    fallbackTimeoutMs;
+    /** Whether a browser is attached right now (updated by the server). */
+    browserAttached = false;
     /** Current widget snapshot (key -> lines) for new connections. */
     getWidgetSnapshot() {
         return Object.fromEntries(this.widgetMap);
     }
     constructor(sink, options = {}) {
         this.sink = sink;
-        this.hasClients = options.hasClients ?? (() => false);
-        this.dialogTimeoutMs = options.dialogTimeoutMs ?? DIALOG_TIMEOUT_MS;
-        this.dialogTimeoutNoClientMs = options.dialogTimeoutNoClientMs ?? DIALOG_TIMEOUT_NO_CLIENT_MS;
+        this.fallbackTimeoutMs = options.fallbackTimeoutMs ?? DIALOG_FALLBACK_TIMEOUT_MS;
         // Pi's ExtensionRunner wraps the ui context with `{...ui}` (a shallow
         // spread) when building the extension ctx - class prototype members
         // (methods AND the theme getter) would be LOST by that spread (only own
@@ -163,6 +164,40 @@ export class WebUIContext {
     dismissDialog(id, reason) {
         this.sink({ type: "dialog_dismissed", id, reason });
     }
+    /**
+     * Browser presence changed (WS connect/disconnect). Only dialogs without an
+     * extension timeout are affected: while a browser is attached they wait
+     * forever (TUI parity - never take an answer away from the user), while no
+     * browser is attached a fallback timer keeps a closed tab from blocking the
+     * agent loop. Reconnecting cancels the fallback.
+     */
+    setBrowserAttached(attached) {
+        if (this.browserAttached === attached)
+            return;
+        this.browserAttached = attached;
+        for (const [id, entry] of [...this.pending.entries()]) {
+            if (entry.extensionTimeout !== undefined)
+                continue; // extension's own timer
+            if (attached) {
+                if (entry.fallbackTimer && entry.timer) {
+                    clearTimeout(entry.timer);
+                    entry.timer = undefined;
+                    entry.fallbackTimer = false;
+                }
+            }
+            else if (!entry.timer) {
+                this.armFallbackTimer(id, entry);
+            }
+        }
+    }
+    /** Arm the no-browser fallback (settles with the dialog default). */
+    armFallbackTimer(id, entry) {
+        entry.fallbackTimer = true;
+        entry.timer = setTimeout(() => {
+            entry.resolve(undefined);
+            this.dismissDialog(id, "timeout");
+        }, this.fallbackTimeoutMs);
+    }
     createDialog(request, opts, defaultValue, parse) {
         const id = crypto.randomUUID();
         // Same as Pi's RPC/TUI: an already-aborted dialog settles immediately.
@@ -187,30 +222,36 @@ export class WebUIContext {
                 cleanup();
                 resolve(useDefault ? defaultValue : parse(value));
             };
-            // Extension timeout (ms) wins; otherwise the web guard applies so a
-            // closed browser cannot block the agent loop forever.
-            const timeoutMs = typeof opts?.timeout === "number"
-                ? opts.timeout
-                : this.hasClients()
-                    ? this.dialogTimeoutMs
-                    : this.dialogTimeoutNoClientMs;
-            const timer = setTimeout(() => {
-                settle(undefined, true);
-                this.dismissDialog(id, "timeout");
-            }, timeoutMs);
             const onAbort = () => {
                 settle(undefined, true);
                 this.dismissDialog(id, "aborted");
             };
             opts?.signal?.addEventListener("abort", onAbort, { once: true });
-            this.pending.set(id, {
+            const extensionTimeout = typeof opts?.timeout === "number" && opts.timeout > 0 ? opts.timeout : undefined;
+            const deadline = extensionTimeout !== undefined ? Date.now() + extensionTimeout : undefined;
+            const entry = {
                 resolve: (value) => settle(value, false),
-                request: { ...request, id },
-                timer,
+                // `deadline` lets the browser show the same countdown TUI does.
+                request: deadline !== undefined ? { ...request, id, deadline } : { ...request, id },
+                deadline,
+                extensionTimeout,
+                fallbackTimer: false,
                 signal: opts?.signal,
                 onAbort,
-            });
-            this.sink({ type: "extension_ui_request", id, ...request });
+            };
+            this.pending.set(id, entry);
+            if (extensionTimeout !== undefined) {
+                // The extension asked for this deadline - honour it exactly (TUI
+                // shows the same countdown and auto-dismisses on expiry).
+                entry.timer = setTimeout(() => {
+                    settle(undefined, true);
+                    this.dismissDialog(id, "timeout");
+                }, extensionTimeout);
+            }
+            else if (!this.browserAttached) {
+                this.armFallbackTimer(id, entry);
+            }
+            this.sink({ type: "extension_ui_request", id, ...request, ...(deadline !== undefined ? { deadline } : {}) });
         });
     }
     // ------------------------------------------------------------------

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-sdk-web",
-  "version": "0.5.15",
+  "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": {