@ricsam/r5d-worker 0.0.68 → 0.0.70

package/dist/cjs/main.cjs

@@ -62,6 +62,7 @@ var import_cli_update = require("./cli-update.cjs");
 var import_git_identity = require("./git-identity.cjs");
 var import_heartbeat = require("./heartbeat.cjs");
 var import_process_tree = require("./process-tree.cjs");
+var import_pty_output_coalescer = require("./pty-output-coalescer.cjs");
 var import_port_forward_client = require("./port-forward-client.cjs");
 var import_workspace_incident_state = require("./workspace-incident-state.cjs");
 var import_workspace_command_sync_policy = require("./workspace-command-sync-policy.cjs");
@@ -2308,6 +2309,15 @@ async function openPty(input) {
   }) : {};
   const targetProcessEnv = targetIdentityEnv(input.resolvedTarget.target);
   const shell = resolveHostShell(input.message.command);
+  const outputCoalescer = (0, import_pty_output_coalescer.createPtyOutputCoalescer)({
+    send: (data) => {
+      sendWorkerMessage(input.ws, {
+        type: "pty_output",
+        ptyId: input.message.ptyId,
+        data
+      });
+    }
+  });
   const ptyProcess = createNodePtyBridge({
     file: shell.file,
     args: shell.args,
@@ -2332,13 +2342,10 @@ async function openPty(input) {
       });
     },
     onOutput: (data) => {
-      sendWorkerMessage(input.ws, {
-        type: "pty_output",
-        ptyId: input.message.ptyId,
-        data
-      });
+      outputCoalescer.push(data);
     },
     onExit: (event) => {
+      outputCoalescer.flush();
       input.releaseWorkspaceMutation?.();
       activePtys.delete(input.message.ptyId);
       input.onTerminal?.();
@@ -2350,6 +2357,7 @@ async function openPty(input) {
       });
     },
     onError: (error) => {
+      outputCoalescer.flush();
       input.releaseWorkspaceMutation?.();
       activePtys.delete(input.message.ptyId);
       input.onTerminal?.();

package/dist/cjs/package.json

@@ -1,5 +1,5 @@
 {
   "name": "@ricsam/r5d-worker",
-  "version": "0.0.68",
+  "version": "0.0.70",
   "type": "commonjs"
 }

package/dist/cjs/port-forward-client.cjs

@@ -36,6 +36,7 @@ var import_ws = __toESM(require("ws"), 1);
 const RELAY_FRAME_BYTES = 64 * 1024;
 const RELAY_PAUSE_BYTES = 1024 * 1024;
 const RELAY_RESUME_BYTES = 256 * 1024;
+const LOOPBACK_HOSTS = ["127.0.0.1", "::1"];
 function relayUrl(baseUrl, label, forwardId, relayConnectionId) {
   const url = new URL("/worker/port-forward/ws", baseUrl);
   url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
@@ -44,42 +45,59 @@ function relayUrl(baseUrl, label, forwardId, relayConnectionId) {
   url.searchParams.set("connection", relayConnectionId);
   return url.toString();
 }
+function loopbackAddress(host, port) {
+  return host.includes(":") ? `[${host}]:${port}` : `${host}:${port}`;
+}
 function rawDataBuffer(data) {
   if (Buffer.isBuffer(data)) return data;
   if (Array.isArray(data)) return Buffer.concat(data);
   return Buffer.from(data);
 }
 function openWorkerPortForwardRelay(options) {
-  const socket = import_node_net.default.createConnection({ host: "127.0.0.1", port: options.workerPort, allowHalfOpen: true });
-  socket.pause();
-  socket.setNoDelay(true);
   const relay = new import_ws.default(relayUrl(options.baseUrl, options.label, options.forwardId, options.relayConnectionId), {
     headers: { Authorization: `Bearer ${options.token}` },
     perMessageDeflate: false
   });
+  let socket;
   let relayReady = false;
   let targetReady = false;
+  let targetEndRequested = false;
+  let targetFailure;
   const pendingChunks = [];
   let pendingBytes = 0;
+  const pendingWrites = [];
+  let pendingWriteBytes = 0;
   let closing = false;
   let resumeTimer;
   const maybeResume = () => {
-    if (relayReady && targetReady && !resumeTimer) socket.resume();
+    if (relayReady && targetReady && !resumeTimer) socket?.resume();
   };
   const cleanup = () => {
     if (closing) return;
     closing = true;
     if (resumeTimer) clearInterval(resumeTimer);
-    socket.destroy();
+    socket?.destroy();
     if (relay.readyState === import_ws.default.OPEN || relay.readyState === import_ws.default.CONNECTING) relay.close();
   };
   const sendError = (message) => {
-    if (relay.readyState === import_ws.default.OPEN) relay.send(JSON.stringify({ type: "error", error: message }));
+    if (closing) return;
+    const payload = JSON.stringify({ type: "error", error: message });
+    if (relay.readyState === import_ws.default.CONNECTING) {
+      closing = true;
+      if (resumeTimer) clearInterval(resumeTimer);
+      socket?.destroy();
+      relay.once("open", () => {
+        relay.send(payload);
+        relay.close();
+      });
+      return;
+    }
+    if (relay.readyState === import_ws.default.OPEN) relay.send(payload);
     cleanup();
   };
   const waitForRelayDrain = () => {
     if (resumeTimer || relay.bufferedAmount <= RELAY_PAUSE_BYTES) return;
-    socket.pause();
+    socket?.pause();
     resumeTimer = setInterval(() => {
       if (relay.readyState !== import_ws.default.OPEN) return cleanup();
       if (relay.bufferedAmount > RELAY_RESUME_BYTES) return;
@@ -94,25 +112,53 @@ function openWorkerPortForwardRelay(options) {
     }
     waitForRelayDrain();
   };
-  socket.once("connect", () => {
+  const adoptTarget = (target, host) => {
+    if (closing) return target.destroy();
+    socket = target;
+    target.on("data", (chunk) => {
+      if (!relayReady || relay.readyState !== import_ws.default.OPEN) {
+        pendingBytes += chunk.byteLength;
+        if (pendingBytes > RELAY_PAUSE_BYTES) return cleanup();
+        pendingChunks.push(Buffer.from(chunk));
+        target.pause();
+        return;
+      }
+      sendChunk(chunk);
+    });
+    target.on("end", () => {
+      if (relay.readyState === import_ws.default.OPEN) relay.send(JSON.stringify({ type: "end" }));
+    });
+    target.on("error", (error) => sendError(`Connection to ${loopbackAddress(host, options.workerPort)} failed: ${error.message}`));
+    target.on("close", cleanup);
+    target.pause();
     targetReady = true;
+    for (const chunk of pendingWrites.splice(0)) target.write(chunk);
+    pendingWriteBytes = 0;
+    if (targetFailure) return void target.destroy(targetFailure);
+    if (targetEndRequested) target.end();
     maybeResume();
-  });
-  socket.on("data", (chunk) => {
-    if (!relayReady || relay.readyState !== import_ws.default.OPEN) {
-      pendingBytes += chunk.byteLength;
-      if (pendingBytes > RELAY_PAUSE_BYTES) return cleanup();
-      pendingChunks.push(Buffer.from(chunk));
-      socket.pause();
-      return;
-    }
-    sendChunk(chunk);
-  });
-  socket.on("end", () => {
-    if (relay.readyState === import_ws.default.OPEN) relay.send(JSON.stringify({ type: "end" }));
-  });
-  socket.on("error", (error) => sendError(`Could not connect to 127.0.0.1:${options.workerPort}: ${error.message}`));
-  socket.on("close", cleanup);
+  };
+  const dialFailures = [];
+  const dialTarget = (host, fallbackHosts2) => {
+    if (closing) return;
+    const candidate = import_node_net.default.createConnection({ host, port: options.workerPort, allowHalfOpen: true });
+    candidate.pause();
+    candidate.setNoDelay(true);
+    const onDialError = (error) => {
+      candidate.destroy();
+      dialFailures.push(`${loopbackAddress(host, options.workerPort)} (${error.code ?? error.message})`);
+      const [nextHost, ...rest] = fallbackHosts2;
+      if (nextHost) return dialTarget(nextHost, rest);
+      sendError(
+        `Could not connect to ${dialFailures.join(" or ")} on the worker. Nothing is listening on either loopback address for port ${options.workerPort} \u2014 make sure the server is running and bound to a loopback or wildcard host.`
+      );
+    };
+    candidate.once("error", onDialError);
+    candidate.once("connect", () => {
+      candidate.off("error", onDialError);
+      adoptTarget(candidate, host);
+    });
+  };
   relay.on("message", (data, isBinary) => {
     if (!isBinary) {
       let control;
@@ -123,24 +169,36 @@ function openWorkerPortForwardRelay(options) {
       }
       if (control.type === "ready") {
         relayReady = true;
-        for (const chunk of pendingChunks.splice(0)) sendChunk(chunk);
+        for (const chunk2 of pendingChunks.splice(0)) sendChunk(chunk2);
         pendingBytes = 0;
         maybeResume();
       } else if (control.type === "end") {
-        socket.end();
+        if (socket) socket.end();
+        else targetEndRequested = true;
       } else if (control.type === "error") {
-        socket.destroy(new Error(control.error || "Port-forward relay failed."));
+        const failure = new Error(control.error || "Port-forward relay failed.");
+        if (socket) socket.destroy(failure);
+        else targetFailure = failure;
       }
       return;
     }
-    if (!socket.write(rawDataBuffer(data))) {
+    const chunk = rawDataBuffer(data);
+    if (!socket) {
+      pendingWriteBytes += chunk.byteLength;
+      if (pendingWriteBytes > RELAY_PAUSE_BYTES) return cleanup();
+      pendingWrites.push(Buffer.from(chunk));
+      return;
+    }
+    const target = socket;
+    if (!target.write(chunk)) {
       relay.pause();
-      socket.once("drain", () => relay.resume());
+      target.once("drain", () => relay.resume());
     }
   });
   relay.on("error", cleanup);
   relay.once("close", cleanup);
-  socket.pause();
+  const [primaryHost, ...fallbackHosts] = LOOPBACK_HOSTS;
+  dialTarget(primaryHost, fallbackHosts);
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/cjs/pty-output-coalescer.cjs

@@ -0,0 +1,87 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var pty_output_coalescer_exports = {};
+__export(pty_output_coalescer_exports, {
+  DEFAULT_PTY_OUTPUT_FLUSH_INTERVAL_MS: () => DEFAULT_PTY_OUTPUT_FLUSH_INTERVAL_MS,
+  DEFAULT_PTY_OUTPUT_MAX_BUFFER_BYTES: () => DEFAULT_PTY_OUTPUT_MAX_BUFFER_BYTES,
+  createPtyOutputCoalescer: () => createPtyOutputCoalescer
+});
+module.exports = __toCommonJS(pty_output_coalescer_exports);
+const DEFAULT_PTY_OUTPUT_FLUSH_INTERVAL_MS = 8;
+const DEFAULT_PTY_OUTPUT_MAX_BUFFER_BYTES = 64 * 1024;
+function defaultSchedule(callback, delayMs) {
+  const timer = setTimeout(callback, delayMs);
+  timer.unref();
+  return () => clearTimeout(timer);
+}
+function createPtyOutputCoalescer(options) {
+  const flushIntervalMs = options.flushIntervalMs ?? DEFAULT_PTY_OUTPUT_FLUSH_INTERVAL_MS;
+  const maxBufferBytes = options.maxBufferBytes ?? DEFAULT_PTY_OUTPUT_MAX_BUFFER_BYTES;
+  const now = options.now ?? Date.now;
+  const schedule = options.schedule ?? defaultSchedule;
+  let buffer = "";
+  let bufferedBytes = 0;
+  let cancelScheduledFlush = null;
+  let lastSendAt = Number.NEGATIVE_INFINITY;
+  const sendNow = (data) => {
+    lastSendAt = now();
+    options.send(data);
+  };
+  const flush = () => {
+    if (cancelScheduledFlush) {
+      cancelScheduledFlush();
+      cancelScheduledFlush = null;
+    }
+    if (bufferedBytes === 0) {
+      return;
+    }
+    const data = buffer;
+    buffer = "";
+    bufferedBytes = 0;
+    sendNow(data);
+  };
+  const push = (data) => {
+    if (data.length === 0) {
+      return;
+    }
+    if (bufferedBytes === 0 && now() - lastSendAt >= flushIntervalMs) {
+      sendNow(data);
+      return;
+    }
+    buffer += data;
+    bufferedBytes += Buffer.byteLength(data, "utf8");
+    if (bufferedBytes >= maxBufferBytes) {
+      flush();
+      return;
+    }
+    if (!cancelScheduledFlush) {
+      cancelScheduledFlush = schedule(() => {
+        cancelScheduledFlush = null;
+        flush();
+      }, flushIntervalMs);
+    }
+  };
+  return { push, flush };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DEFAULT_PTY_OUTPUT_FLUSH_INTERVAL_MS,
+  DEFAULT_PTY_OUTPUT_MAX_BUFFER_BYTES,
+  createPtyOutputCoalescer
+});

package/dist/mjs/main.mjs

@@ -12,6 +12,7 @@ import {
   WORKER_HEARTBEAT_INTERVAL_MS
 } from "./heartbeat.mjs";
 import { terminateProcessTree } from "./process-tree.mjs";
+import { createPtyOutputCoalescer } from "./pty-output-coalescer.mjs";
 import { openWorkerPortForwardRelay } from "./port-forward-client.mjs";
 import { applyWorkspaceIncidentUpdate, releasePendingWorkspaceHead, WorkspaceIncidentOrderingFence } from "./workspace-incident-state.mjs";
 import { acquireWorkspaceCommandMutation, runWorkspaceCommand } from "./workspace-command-sync-policy.mjs";
@@ -2279,6 +2280,15 @@ async function openPty(input) {
   }) : {};
   const targetProcessEnv = targetIdentityEnv(input.resolvedTarget.target);
   const shell = resolveHostShell(input.message.command);
+  const outputCoalescer = createPtyOutputCoalescer({
+    send: (data) => {
+      sendWorkerMessage(input.ws, {
+        type: "pty_output",
+        ptyId: input.message.ptyId,
+        data
+      });
+    }
+  });
   const ptyProcess = createNodePtyBridge({
     file: shell.file,
     args: shell.args,
@@ -2303,13 +2313,10 @@ async function openPty(input) {
       });
     },
     onOutput: (data) => {
-      sendWorkerMessage(input.ws, {
-        type: "pty_output",
-        ptyId: input.message.ptyId,
-        data
-      });
+      outputCoalescer.push(data);
     },
     onExit: (event) => {
+      outputCoalescer.flush();
       input.releaseWorkspaceMutation?.();
       activePtys.delete(input.message.ptyId);
       input.onTerminal?.();
@@ -2321,6 +2328,7 @@ async function openPty(input) {
       });
     },
     onError: (error) => {
+      outputCoalescer.flush();
       input.releaseWorkspaceMutation?.();
       activePtys.delete(input.message.ptyId);
       input.onTerminal?.();

package/dist/mjs/package.json

@@ -1,5 +1,5 @@
 {
   "name": "@ricsam/r5d-worker",
-  "version": "0.0.68",
+  "version": "0.0.70",
   "type": "module"
 }

package/dist/mjs/port-forward-client.mjs

@@ -3,6 +3,7 @@ import WebSocket, {} from "ws";
 const RELAY_FRAME_BYTES = 64 * 1024;
 const RELAY_PAUSE_BYTES = 1024 * 1024;
 const RELAY_RESUME_BYTES = 256 * 1024;
+const LOOPBACK_HOSTS = ["127.0.0.1", "::1"];
 function relayUrl(baseUrl, label, forwardId, relayConnectionId) {
   const url = new URL("/worker/port-forward/ws", baseUrl);
   url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
@@ -11,42 +12,59 @@ function relayUrl(baseUrl, label, forwardId, relayConnectionId) {
   url.searchParams.set("connection", relayConnectionId);
   return url.toString();
 }
+function loopbackAddress(host, port) {
+  return host.includes(":") ? `[${host}]:${port}` : `${host}:${port}`;
+}
 function rawDataBuffer(data) {
   if (Buffer.isBuffer(data)) return data;
   if (Array.isArray(data)) return Buffer.concat(data);
   return Buffer.from(data);
 }
 function openWorkerPortForwardRelay(options) {
-  const socket = net.createConnection({ host: "127.0.0.1", port: options.workerPort, allowHalfOpen: true });
-  socket.pause();
-  socket.setNoDelay(true);
   const relay = new WebSocket(relayUrl(options.baseUrl, options.label, options.forwardId, options.relayConnectionId), {
     headers: { Authorization: `Bearer ${options.token}` },
     perMessageDeflate: false
   });
+  let socket;
   let relayReady = false;
   let targetReady = false;
+  let targetEndRequested = false;
+  let targetFailure;
   const pendingChunks = [];
   let pendingBytes = 0;
+  const pendingWrites = [];
+  let pendingWriteBytes = 0;
   let closing = false;
   let resumeTimer;
   const maybeResume = () => {
-    if (relayReady && targetReady && !resumeTimer) socket.resume();
+    if (relayReady && targetReady && !resumeTimer) socket?.resume();
   };
   const cleanup = () => {
     if (closing) return;
     closing = true;
     if (resumeTimer) clearInterval(resumeTimer);
-    socket.destroy();
+    socket?.destroy();
     if (relay.readyState === WebSocket.OPEN || relay.readyState === WebSocket.CONNECTING) relay.close();
   };
   const sendError = (message) => {
-    if (relay.readyState === WebSocket.OPEN) relay.send(JSON.stringify({ type: "error", error: message }));
+    if (closing) return;
+    const payload = JSON.stringify({ type: "error", error: message });
+    if (relay.readyState === WebSocket.CONNECTING) {
+      closing = true;
+      if (resumeTimer) clearInterval(resumeTimer);
+      socket?.destroy();
+      relay.once("open", () => {
+        relay.send(payload);
+        relay.close();
+      });
+      return;
+    }
+    if (relay.readyState === WebSocket.OPEN) relay.send(payload);
     cleanup();
   };
   const waitForRelayDrain = () => {
     if (resumeTimer || relay.bufferedAmount <= RELAY_PAUSE_BYTES) return;
-    socket.pause();
+    socket?.pause();
     resumeTimer = setInterval(() => {
       if (relay.readyState !== WebSocket.OPEN) return cleanup();
       if (relay.bufferedAmount > RELAY_RESUME_BYTES) return;
@@ -61,25 +79,53 @@ function openWorkerPortForwardRelay(options) {
     }
     waitForRelayDrain();
   };
-  socket.once("connect", () => {
+  const adoptTarget = (target, host) => {
+    if (closing) return target.destroy();
+    socket = target;
+    target.on("data", (chunk) => {
+      if (!relayReady || relay.readyState !== WebSocket.OPEN) {
+        pendingBytes += chunk.byteLength;
+        if (pendingBytes > RELAY_PAUSE_BYTES) return cleanup();
+        pendingChunks.push(Buffer.from(chunk));
+        target.pause();
+        return;
+      }
+      sendChunk(chunk);
+    });
+    target.on("end", () => {
+      if (relay.readyState === WebSocket.OPEN) relay.send(JSON.stringify({ type: "end" }));
+    });
+    target.on("error", (error) => sendError(`Connection to ${loopbackAddress(host, options.workerPort)} failed: ${error.message}`));
+    target.on("close", cleanup);
+    target.pause();
     targetReady = true;
+    for (const chunk of pendingWrites.splice(0)) target.write(chunk);
+    pendingWriteBytes = 0;
+    if (targetFailure) return void target.destroy(targetFailure);
+    if (targetEndRequested) target.end();
     maybeResume();
-  });
-  socket.on("data", (chunk) => {
-    if (!relayReady || relay.readyState !== WebSocket.OPEN) {
-      pendingBytes += chunk.byteLength;
-      if (pendingBytes > RELAY_PAUSE_BYTES) return cleanup();
-      pendingChunks.push(Buffer.from(chunk));
-      socket.pause();
-      return;
-    }
-    sendChunk(chunk);
-  });
-  socket.on("end", () => {
-    if (relay.readyState === WebSocket.OPEN) relay.send(JSON.stringify({ type: "end" }));
-  });
-  socket.on("error", (error) => sendError(`Could not connect to 127.0.0.1:${options.workerPort}: ${error.message}`));
-  socket.on("close", cleanup);
+  };
+  const dialFailures = [];
+  const dialTarget = (host, fallbackHosts2) => {
+    if (closing) return;
+    const candidate = net.createConnection({ host, port: options.workerPort, allowHalfOpen: true });
+    candidate.pause();
+    candidate.setNoDelay(true);
+    const onDialError = (error) => {
+      candidate.destroy();
+      dialFailures.push(`${loopbackAddress(host, options.workerPort)} (${error.code ?? error.message})`);
+      const [nextHost, ...rest] = fallbackHosts2;
+      if (nextHost) return dialTarget(nextHost, rest);
+      sendError(
+        `Could not connect to ${dialFailures.join(" or ")} on the worker. Nothing is listening on either loopback address for port ${options.workerPort} \u2014 make sure the server is running and bound to a loopback or wildcard host.`
+      );
+    };
+    candidate.once("error", onDialError);
+    candidate.once("connect", () => {
+      candidate.off("error", onDialError);
+      adoptTarget(candidate, host);
+    });
+  };
   relay.on("message", (data, isBinary) => {
     if (!isBinary) {
       let control;
@@ -90,24 +136,36 @@ function openWorkerPortForwardRelay(options) {
       }
       if (control.type === "ready") {
         relayReady = true;
-        for (const chunk of pendingChunks.splice(0)) sendChunk(chunk);
+        for (const chunk2 of pendingChunks.splice(0)) sendChunk(chunk2);
         pendingBytes = 0;
         maybeResume();
       } else if (control.type === "end") {
-        socket.end();
+        if (socket) socket.end();
+        else targetEndRequested = true;
       } else if (control.type === "error") {
-        socket.destroy(new Error(control.error || "Port-forward relay failed."));
+        const failure = new Error(control.error || "Port-forward relay failed.");
+        if (socket) socket.destroy(failure);
+        else targetFailure = failure;
       }
       return;
     }
-    if (!socket.write(rawDataBuffer(data))) {
+    const chunk = rawDataBuffer(data);
+    if (!socket) {
+      pendingWriteBytes += chunk.byteLength;
+      if (pendingWriteBytes > RELAY_PAUSE_BYTES) return cleanup();
+      pendingWrites.push(Buffer.from(chunk));
+      return;
+    }
+    const target = socket;
+    if (!target.write(chunk)) {
       relay.pause();
-      socket.once("drain", () => relay.resume());
+      target.once("drain", () => relay.resume());
     }
   });
   relay.on("error", cleanup);
   relay.once("close", cleanup);
-  socket.pause();
+  const [primaryHost, ...fallbackHosts] = LOOPBACK_HOSTS;
+  dialTarget(primaryHost, fallbackHosts);
 }
 export {
   openWorkerPortForwardRelay

package/dist/mjs/pty-output-coalescer.mjs

@@ -0,0 +1,61 @@
+const DEFAULT_PTY_OUTPUT_FLUSH_INTERVAL_MS = 8;
+const DEFAULT_PTY_OUTPUT_MAX_BUFFER_BYTES = 64 * 1024;
+function defaultSchedule(callback, delayMs) {
+  const timer = setTimeout(callback, delayMs);
+  timer.unref();
+  return () => clearTimeout(timer);
+}
+function createPtyOutputCoalescer(options) {
+  const flushIntervalMs = options.flushIntervalMs ?? DEFAULT_PTY_OUTPUT_FLUSH_INTERVAL_MS;
+  const maxBufferBytes = options.maxBufferBytes ?? DEFAULT_PTY_OUTPUT_MAX_BUFFER_BYTES;
+  const now = options.now ?? Date.now;
+  const schedule = options.schedule ?? defaultSchedule;
+  let buffer = "";
+  let bufferedBytes = 0;
+  let cancelScheduledFlush = null;
+  let lastSendAt = Number.NEGATIVE_INFINITY;
+  const sendNow = (data) => {
+    lastSendAt = now();
+    options.send(data);
+  };
+  const flush = () => {
+    if (cancelScheduledFlush) {
+      cancelScheduledFlush();
+      cancelScheduledFlush = null;
+    }
+    if (bufferedBytes === 0) {
+      return;
+    }
+    const data = buffer;
+    buffer = "";
+    bufferedBytes = 0;
+    sendNow(data);
+  };
+  const push = (data) => {
+    if (data.length === 0) {
+      return;
+    }
+    if (bufferedBytes === 0 && now() - lastSendAt >= flushIntervalMs) {
+      sendNow(data);
+      return;
+    }
+    buffer += data;
+    bufferedBytes += Buffer.byteLength(data, "utf8");
+    if (bufferedBytes >= maxBufferBytes) {
+      flush();
+      return;
+    }
+    if (!cancelScheduledFlush) {
+      cancelScheduledFlush = schedule(() => {
+        cancelScheduledFlush = null;
+        flush();
+      }, flushIntervalMs);
+    }
+  };
+  return { push, flush };
+}
+export {
+  DEFAULT_PTY_OUTPUT_FLUSH_INTERVAL_MS,
+  DEFAULT_PTY_OUTPUT_MAX_BUFFER_BYTES,
+  createPtyOutputCoalescer
+};

package/dist/types/pty-output-coalescer.d.ts

@@ -0,0 +1,20 @@
+export interface PtyOutputCoalescerOptions {
+    send: (data: string) => void;
+    flushIntervalMs?: number;
+    maxBufferBytes?: number;
+    now?: () => number;
+    schedule?: (callback: () => void, delayMs: number) => () => void;
+}
+export interface PtyOutputCoalescer {
+    push(data: string): void;
+    flush(): void;
+}
+export declare const DEFAULT_PTY_OUTPUT_FLUSH_INTERVAL_MS = 8;
+export declare const DEFAULT_PTY_OUTPUT_MAX_BUFFER_BYTES: number;
+/**
+ * Batches PTY output into fewer, larger relay messages. An isolated chunk
+ * (an interactive keystroke echo) is sent immediately so coalescing adds no
+ * input latency; only sustained bursts (build logs, `cat` of a large file)
+ * are buffered, bounded by the flush interval and the buffer byte cap.
+ */
+export declare function createPtyOutputCoalescer(options: PtyOutputCoalescerOptions): PtyOutputCoalescer;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ricsam/r5d-worker",
-  "version": "0.0.68",
+  "version": "0.0.70",
   "type": "module",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/mjs/main.mjs",