replica-bridge 0.3.5 → 0.3.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "replica-bridge",
-  "version": "0.3.5",
+  "version": "0.3.8",
   "description": "Lets the ChatReplica iPhone app use Codex on this computer through a relay, end-to-end encrypted.",
   "type": "module",
   "bin": {
@@ -11,7 +11,7 @@
   },
   "dependencies": {
     "qrcode": "1.5.4",
-    "ws": "8.18.3"
+    "ws": "8.22.0"
   },
   "license": "UNLICENSED"
 }

package/src/bridge/install.js

@@ -1,6 +1,7 @@
 // Keeping the bridge running after its terminal closes, the way Codex keeps its app-server: a per-user background
 // service that starts at login and restarts when it fails. macOS: a launchd agent. Linux: a systemd user service.
-// Windows: a Task Scheduler task at logon that runs a hidden script, which restarts the bridge when it exits.
+// Windows: a Task Scheduler task at logon (and checked every minute) that runs a hidden script, which restarts the
+// bridge when it exits.
 // The service runs a copy installed under ~/.config/replica-bridge/app, not the npx cache, which npm may clear.
 import fs from "node:fs";
 import os from "node:os";
@@ -24,10 +25,15 @@ export const PACKAGE_VERSION         = JSON.parse(fs.readFileSync(path.resolve(i
               
                                                                  
                 
+                                                                                             
+                   
+                                                                                      
+             
  
 
                               
-                                             
+                                                                                             
+                                                                   
                                                                                    
                                                                      
                                                                        
@@ -39,6 +45,7 @@ export const serviceLabel = () => process.env.REPLICA_BRIDGE_LABEL ?? "replica-b
 export const logPath = (home = bridgeHome()) => path.join(home, "bridge.log");
 const infoPath = () => path.join(bridgeHome(), "service.json");
 const pidPath = () => path.join(bridgeHome(), "bridge.pid");
+const pausedPath = () => path.join(bridgeHome(), "service-paused");
 
 const xml = (text        ) => text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
 /** systemd unit-file quoting: specifiers (%) doubled, backslashes and quotes escaped. */
@@ -126,6 +133,7 @@ WantedBy=default.target
     }
     case "win32": {
       const script = path.join(spec.bridgeHome, "run-bridge.vbs");
+      const task = path.join(spec.bridgeHome, "replica-bridge-task.xml");
       // wscript shows no window; the loop brings the bridge back ten seconds after it fails. Exit code 0 means another
       // bridge took this computer over (or it was told to stop), so the loop ends.
       const content = [
@@ -139,11 +147,42 @@ WantedBy=default.target
         `Loop`,
         "",
       ].join("\r\n");
+      // `schtasks /SC ONLOGON` left Task Scheduler's defaults, which stopped the bridge on a laptop that went on battery
+      // (and never started it on one), stopped it after three days, and started it again only at the next login: the
+      // computer went offline for the phones until someone logged in. The task XML turns those off, retries a failed
+      // start, and checks every minute that the task runs (IgnoreNew: never a second copy while one runs). The logon
+      // trigger is this account's alone; one for every user needs an elevated terminal.
+      const user = spec.account ? `<UserId>${xml(spec.account)}</UserId>` : "";
+      // Without a zone Task Scheduler reads it as local time; a UTC one would delay the first check by the offset.
+      const now = spec.now ?? new Date();
+      const start = new Date(now.getTime() - now.getTimezoneOffset() * 60_000).toISOString().slice(0, 19);
+      const taskXML = `<?xml version="1.0" encoding="UTF-16"?>
+<!-- Elements in the order Task Scheduler exports them. -->
+<Task version="1.2" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">
+  <RegistrationInfo><Description>replica-bridge: ChatReplica phones use Codex on this computer. Made by "replica-bridge install".</Description></RegistrationInfo>
+  <Triggers>
+    <LogonTrigger><Enabled>true</Enabled>${user}</LogonTrigger>
+    <TimeTrigger><Repetition><Interval>PT1M</Interval><StopAtDurationEnd>false</StopAtDurationEnd></Repetition><StartBoundary>${start}</StartBoundary><Enabled>true</Enabled></TimeTrigger>
+  </Triggers>
+  <Principals><Principal id="Author">${user}<LogonType>InteractiveToken</LogonType><RunLevel>LeastPrivilege</RunLevel></Principal></Principals>
+  <Settings>
+    <MultipleInstancesPolicy>IgnoreNew</MultipleInstancesPolicy>
+    <DisallowStartIfOnBatteries>false</DisallowStartIfOnBatteries>
+    <StopIfGoingOnBatteries>false</StopIfGoingOnBatteries>
+    <StartWhenAvailable>true</StartWhenAvailable>
+    <IdleSettings><StopOnIdleEnd>false</StopOnIdleEnd><RestartOnIdle>false</RestartOnIdle></IdleSettings>
+    <Enabled>true</Enabled>
+    <ExecutionTimeLimit>PT0S</ExecutionTimeLimit>
+    <RestartOnFailure><Interval>PT1M</Interval><Count>3</Count></RestartOnFailure>
+  </Settings>
+  <Actions Context="Author"><Exec><Command>wscript.exe</Command><Arguments>${xml(`"${script}"`)}</Arguments></Exec></Actions>
+</Task>
+`;
       return {
-        files: [{ path: script, content }],
+        files: [{ path: script, content }, { path: task, content: taskXML, encoding: "utf16le" }],
         install: [
           { command: "schtasks", args: ["/End", "/TN", spec.label], optional: true },
-          { command: "schtasks", args: ["/Create", "/F", "/TN", spec.label, "/SC", "ONLOGON", "/RL", "LIMITED", "/TR", `wscript.exe "${script}"`] },
+          { command: "schtasks", args: ["/Create", "/F", "/TN", spec.label, "/XML", task] },
           { command: "schtasks", args: ["/Run", "/TN", spec.label] },
         ],
         uninstall: [
@@ -242,7 +281,8 @@ export function readServiceInfo()                     {
 
 function spec(program          )              {
   const { uid, username } = os.userInfo();
-  return { platform: process.platform, label: serviceLabel(), home: os.homedir(), bridgeHome: bridgeHome(), program, env: serviceEnv(), uid, user: username };
+  const account = process.env.USERDOMAIN ? `${process.env.USERDOMAIN}\\${username}` : username;
+  return { platform: process.platform, label: serviceLabel(), home: os.homedir(), bridgeHome: bridgeHome(), program, env: serviceEnv(), uid, user: username, account };
 }
 
 /** Installs (or replaces) the background service and starts it. `startArgs` are the options `start` keeps. */
@@ -254,8 +294,9 @@ export function installService(startArgs          , say                        )
   fs.mkdirSync(bridgeHome(), { recursive: true, mode: 0o700 });
   for (const file of plan.files) {
     fs.mkdirSync(path.dirname(file.path), { recursive: true });
-    fs.writeFileSync(file.path, file.content);
+    fs.writeFileSync(file.path, file.encoding === "utf16le" ? Buffer.concat([Buffer.from([0xff, 0xfe]), Buffer.from(file.content, "utf16le")]) : file.content);
   }
+  fs.rmSync(pausedPath(), { force: true });
   run(plan.install);
   const info              = { platform: process.platform, label: serviceLabel(), version: PACKAGE_VERSION, program, installedAt: new Date().toISOString() };
   fs.writeFileSync(infoPath(), JSON.stringify(info, null, 2) + "\n");
@@ -306,6 +347,20 @@ export function runningPid()                {
   try { process.kill(pid, 0); return pid; } catch (error) { return (error                         ).code === "EPERM" ? pid : null; }
 }
 
+/**
+ * Another bridge took this computer over at the relay. The Windows task's every-minute check would start this one
+ * again, and the two would take turns kicking each other off; this marks the service stopped until the next install
+ * or the next boot, the way launchd and systemd leave a service that exited 0.
+ */
+export function pauseService() {
+  fs.mkdirSync(bridgeHome(), { recursive: true, mode: 0o700 });
+  fs.writeFileSync(pausedPath(), new Date().toISOString() + "\n");
+}
+
+export function servicePaused()          {
+  try { return !writtenBeforeBoot(fs.statSync(pausedPath()).mtimeMs); } catch { return false; }
+}
+
 /** The service manager stops its own process; on Windows the loop's bridge is left, so it goes by pid. */
 function stopRunning() {
   const pid = runningPid();

package/src/bridge/main.js

@@ -18,7 +18,7 @@ import { parseArgs, format } from "node:util";
 import { relayRequest } from "../http.js";
 import { spawnCommandSync } from "./command.js";
 import { defaultRelayURL, enroll, ensureEnrolled, ensureRelay } from "./enroll.js";
-import { PACKAGE_VERSION, clearPid, installService, logPath, readServiceInfo, runningPid, servicePlan, uninstallService, writePid } from "./install.js";
+import { PACKAGE_VERSION, clearPid, installService, logPath, pauseService, readServiceInfo, runningPid, servicePaused, servicePlan, uninstallService, writePid } from "./install.js";
 import { pair, publicRelayURL } from "./pair.js";
 import { BridgeService } from "./service.js";
 import { loadState, saveState } from "./state.js";
@@ -73,7 +73,12 @@ function startArgs()           {
 
 function startBridge()                {
   // Exit 0: the background services restart the bridge only when it fails, so the newer bridge keeps the computer.
-  const service = new BridgeService({ codexPath: values.codex, loginShell: !values["no-login-shell"], streamTTLSeconds: Number(values["stream-ttl"]), onReplaced: () => process.exit(0) });
+  // The Windows task also checks every minute, so there the service is marked paused first.
+  const onReplaced = () => {
+    if (process.env.REPLICA_BRIDGE_SERVICE === "1" && process.platform === "win32") pauseService();
+    process.exit(0);
+  };
+  const service = new BridgeService({ codexPath: values.codex, loginShell: !values["no-login-shell"], streamTTLSeconds: Number(values["stream-ttl"]), onReplaced });
   service.start();
   return service;
 }
@@ -210,6 +215,10 @@ async function main() {
     case "start": {
       await ensureEnrolled(values.relay, console.log, values.name);
       const asService = process.env.REPLICA_BRIDGE_SERVICE === "1";
+      if (asService && servicePaused()) {
+        console.log(`another bridge took this computer over; the background service stays stopped until "npx replica-bridge install" or the next restart`);
+        return;
+      }
       if (runningPid()) throw new Error(`a bridge already runs for this computer (pid ${runningPid()})${asService ? "" : '; "npx replica-bridge uninstall" stops the background one'}`);
       const bridge = startBridge();
       if (asService) { writePid(); process.on("exit", clearPid); }

package/src/bridge/service.js

@@ -10,7 +10,7 @@ import { Duplex } from "node:stream";
 import { WebSocket } from "ws";
                                   
 import {
-  CloseCode, FrameCipher, MAX_FRAME_BYTES, RELAY_REPLY_LIMIT, StreamBuffer, b64url, fromB64url, generateKeyPair, hostSessionKeys,
+  CloseCode, FrameCipher, ChunkAssembler, MAX_FRAME_BYTES, REASSEMBLED_MAX_BYTES, RELAY_REPLY_LIMIT, StreamBuffer, encodeLine, b64url, fromB64url, generateKeyPair, hostSessionKeys,
 } from "../protocol.js";
                                                                             
 import { relaySocketURL } from "../http.js";
@@ -37,6 +37,8 @@ import { annotateWriterError } from "./writer.js";
                           
                                                                                           
                                                             
+                                                                                                                          
+                            
  
 
                   
@@ -50,6 +52,12 @@ import { annotateWriterError } from "./writer.js";
                                   
                                                                                                                        
                          
+                                                                                                     
+                     
+                                                  
+                         
+                                                                                                                            
+                              
  
 
                 
@@ -94,7 +102,18 @@ export class BridgeService {
     const state = loadState();
     const ws = new WebSocket(relaySocketURL(state.relay, "/v1/host"), { headers: { authorization: `Bearer ${state.hostToken}` }, maxPayload: MAX_FRAME_BYTES + 4096, perMessageDeflate: false });
     this.relay = ws;
-    ws.on("open", () => { this.retry = 0; this.log(`connected to relay ${state.relay} as ${state.hostId}`); });
+    // A laptop that sleeps or changes networks keeps a socket the relay dropped long ago, and nothing here would
+    // notice until the bridge sent something: the computer stayed offline for the phones. A missed pong ends it.
+    let answered = true;
+    const ping = setInterval(() => {
+      if (!answered) { this.log("relay did not answer a ping; reconnecting"); return ws.terminate(); }
+      answered = false;
+      // Still connecting counts as a missed pong too, so a handshake that never finishes ends at the next tick.
+      if (ws.readyState === WebSocket.OPEN) ws.ping();
+    }, (this.options.relayPingSeconds ?? 30) * 1000);
+    ws.on("pong", () => { answered = true; });
+    ws.on("ping", () => { answered = true; });
+    ws.on("open", () => { answered = true; this.retry = 0; this.log(`connected to relay ${state.relay} as ${state.hostId}`); });
     ws.on("message", (data         ) => {
       let envelope              ;
       try { envelope = JSON.parse(data.toString()); } catch { return; }
@@ -110,6 +129,7 @@ export class BridgeService {
     });
     ws.on("error", (error) => this.log(`relay connection error: ${error.message}`));
     ws.on("close", (code) => {
+      clearInterval(ping);
       if (ws !== this.relay) return; // a socket this bridge already replaced itself
       for (const conn of this.conns.values()) this.detach(conn);
       this.conns.clear();
@@ -125,6 +145,14 @@ export class BridgeService {
     });
   }
 
+  /**
+   * Waits while the relay socket has more than a few chunks queued, so a long message goes out at the network's pace
+   * instead of tens of MiB piling up in memory ahead of everything else on this computer's socket.
+   */
+          async drained() {
+    while (this.relay?.readyState === WebSocket.OPEN && this.relay.bufferedAmount > RELAY_SEND_QUEUE_BYTES) await new Promise((resolve) => setTimeout(resolve, 10));
+  }
+
           sendEnvelope(envelope              ) {
     if (this.relay?.readyState === WebSocket.OPEN) this.relay.send(JSON.stringify(envelope));
   }
@@ -191,12 +219,20 @@ export class BridgeService {
     const message = conn.cipher.openFrame(frame);
     if (message.t === "resume") {
       if (conn.stream) throw new Error("second resume");
-      await this.resume(conn, message.stream, message.ack);
+      await this.resume(conn, message.stream, message.ack, message.seg === 1);
     } else if (message.t === "msg") {
       const stream = conn.stream;
       if (!stream) throw new Error("message before resume");
       if (!stream.in.accept(message.seq)) return;
-      if (stream.appServer.readyState === WebSocket.OPEN) stream.appServer.send(message.line);
+      if (stream.chunks.busy) throw new Error("message in the middle of a chunked one");
+      this.sendToAppServer(stream, message.line);
+      this.scheduleAck(stream);
+    } else if (message.t === "chunk") {
+      const stream = conn.stream;
+      if (!stream) throw new Error("message before resume");
+      if (!stream.in.accept(message.seq)) return;
+      const line = stream.chunks.take(message);
+      if (line !== null) this.sendToAppServer(stream, line);
       this.scheduleAck(stream);
     } else if (message.t === "ack") {
       conn.stream?.out.ack(message.seq);
@@ -209,7 +245,7 @@ export class BridgeService {
 
   // MARK: - Streams
 
-          async resume(conn      , streamId               , peerAck        ) {
+          async resume(conn      , streamId               , peerAck        , segmented         ) {
     let stream = streamId ? this.streams.get(streamId) : undefined;
     const resumed = !!stream && stream.deviceId === conn.deviceId;
     if (!resumed) {
@@ -219,31 +255,40 @@ export class BridgeService {
     if (s.conn && s.conn !== conn) this.closeConn(s.conn, "resumed elsewhere");
     if (s.expiry) { clearTimeout(s.expiry); s.expiry = null; }
     s.conn = conn;
+    s.segmented = segmented;
     conn.stream = s;
-    this.sendInner(conn, { t: "ready", stream: s.id, resumed, ack: s.in.received });
+    this.sendInner(conn, { t: "ready", stream: s.id, resumed, ack: s.in.received, seg: 1 });
     // A new stream's sequence numbers start over, whatever the phone acknowledged on its old one.
     const after = resumed ? peerAck : 0;
     s.out.ack(after);
-    for (const item of s.out.pending(after)) this.sendInner(conn, { t: "msg", seq: item.seq, line: item.line });
+    for (const message of s.out.pending(after)) this.sendInner(conn, message);
     this.log(`${resumed ? "resumed" : "opened"} stream ${s.id} for ${conn.deviceId}`);
   }
 
           async openStream(deviceId        )                  {
-    const appServer = await this.connectAppServer();
-    const stream         = { id: crypto.randomBytes(12).toString("base64url"), deviceId, appServer, out: new StreamBuffer(), in: new StreamBuffer(), conn: null, expiry: null, ackTimer: null, relayed: Promise.resolve() };
+    const { ws: appServer, frameBytes } = await this.connectAppServer();
+    const stream         = {
+      id: crypto.randomBytes(12).toString("base64url"), deviceId, appServer, out: new StreamBuffer(STREAM_BUFFER_BYTES), in: new StreamBuffer(STREAM_BUFFER_BYTES),
+      conn: null, expiry: null, ackTimer: null, relayed: Promise.resolve(), segmented: false, chunks: new ChunkAssembler(), appServerFrameBytes: frameBytes,
+    };
     this.streams.set(stream.id, stream);
     appServer.on("message", (data         ) => {
       const text = data.toString();
-      const fitted = fitLine(text);
+      const segmented = stream.segmented;
+      const fitted = fitLine(text, segmented ? REASSEMBLED_MAX_BYTES : RELAY_REPLY_LIMIT);
       if (fitted === null) return this.log(`stream ${stream.id}: dropped a ${text.length}-byte app-server notification too large for the relay`);
       if (fitted !== text) this.log(`stream ${stream.id}: answered a ${text.length}-byte app-server reply too large for the relay with an error`);
       const annotated = annotateWriterError(fitted, this.options.findWriter);
       stream.relayed = stream.relayed.then(async () => {
         const line = await annotated;
-        if (!this.streams.has(stream.id)) return;
-        let item;
-        try { item = stream.out.push(line); } catch { return this.endStream(stream, "the phone stayed away too long and the buffer filled up"); }
-        if (stream.conn) this.sendInner(stream.conn, { t: "msg", seq: item.seq, line: item.line });
+        const parts = segmented ? await encodeLine(line) : [line];
+        for (const part of parts) {
+          if (!this.streams.has(stream.id)) return;
+          let message;
+          try { message = stream.out.push(part); } catch { return this.endStream(stream, "the phone stayed away too long and the buffer filled up"); }
+          if (stream.conn) this.sendInner(stream.conn, message);
+          if (parts.length > 1) await this.drained();
+        }
       });
     });
     appServer.on("close", () => this.endStream(stream, "codex app-server closed the connection"));
@@ -282,11 +327,22 @@ export class BridgeService {
 
   // MARK: - codex app-server
 
+  /** Sends a line to the app-server, as WebSocket fragments when it is longer than the app-server takes in one frame. */
+          sendToAppServer(stream        , line        ) {
+    const ws = stream.appServer;
+    if (ws.readyState !== WebSocket.OPEN) return;
+    const bytes = Buffer.from(line, "utf8");
+    if (bytes.length <= stream.appServerFrameBytes) return ws.send(line);
+    for (let at = 0; at < bytes.length; at += stream.appServerFrameBytes) {
+      ws.send(bytes.subarray(at, at + stream.appServerFrameBytes), { binary: false, fin: at + stream.appServerFrameBytes >= bytes.length });
+    }
+  }
+
   /**
    * One `codex app-server proxy` per stream, with WebSocket over its stdin and stdout. The proxy only relays bytes to
    * the app-server's control socket, wherever Codex keeps it; it exits at once when no app-server is running.
    */
-          openProxy()                     {
+          openProxy()                                                 {
     return new Promise((resolve, reject) => {
       const child               = spawnCommand(this.options.codexPath ?? "codex", ["app-server", "proxy"], { stdio: ["pipe", "pipe", "pipe"] });
       let stderr = "";
@@ -297,13 +353,18 @@ export class BridgeService {
       // Read app-server messages well past what one relay frame holds, so fitLine answers a big reply with an error
       // rather than the oversized message closing the app-server connection.
       const ws = new WebSocket("ws://localhost/", { createConnection: () => pipe         , perMessageDeflate: false, maxPayload: APP_SERVER_MAX_MESSAGE_BYTES });
+      let frameBytes = APP_SERVER_FRAME_BYTES;
+      ws.once("upgrade", (res) => {
+        const advertised = Number(res.headers["x-codex-websocket-max-unfragmented-message-bytes"]);
+        if (Number.isInteger(advertised) && advertised >= 64 * 1024) frameBytes = advertised;
+      });
       const fail = (why        ) => { ws.removeAllListeners("open"); killCommand(child); reject(new Error(why)); };
       child.once("error", (error) => fail(`could not run codex: ${error.message}`));
       child.once("exit", (code) => { if (ws.readyState !== WebSocket.OPEN) fail(`codex app-server proxy exited (${code})${stderr ? `: ${stderr.trim()}` : ""}`); });
       ws.once("error", (error) => { if (ws.readyState !== WebSocket.OPEN) fail(error.message); });
       ws.once("open", () => {
         ws.on("close", () => killCommand(child));
-        resolve(ws);
+        resolve({ ws, frameBytes });
       });
     });
   }
@@ -318,7 +379,7 @@ export class BridgeService {
     });
   }
 
-          async connectAppServer()                     {
+          async connectAppServer()                                                 {
     try {
       return await this.openProxy();
     } catch (error) {
@@ -349,16 +410,24 @@ export class BridgeService {
 /** Largest app-server message the bridge reads before refusing it. */
 const APP_SERVER_MAX_MESSAGE_BYTES = 256 * 1024 * 1024;
 
+/** What the bridge keeps per direction for a phone that is away: room for a REASSEMBLED_MAX_BYTES line deflate could not shrink. */
+const STREAM_BUFFER_BYTES = 128 * 1024 * 1024;
+/** Chunks queued on the relay socket before the next one waits. */
+const RELAY_SEND_QUEUE_BYTES = 1024 * 1024;
+/** What codex-cli 0.163.0 sends in x-codex-websocket-max-unfragmented-message-bytes, for an app-server that sends none. */
+const APP_SERVER_FRAME_BYTES = 16 * 1024 * 1024;
+
 /**
- * An app-server line as it can cross the relay: unchanged when it fits RELAY_REPLY_LIMIT, a JSON-RPC error with the
- * same id when it is a reply that does not (`error.data.replicaTooLarge: {bytes, limit}`, PROTOCOL.md), and null for a
- * notification that does not, which has no one to answer.
+ * An app-server line as it can cross the relay: unchanged when it fits `limit` (RELAY_REPLY_LIMIT, or
+ * REASSEMBLED_MAX_BYTES for a phone that takes chunks), a JSON-RPC error with the same id when it is a reply that does
+ * not (`error.data.replicaTooLarge: {bytes, limit}`, PROTOCOL.md), and null for a notification that does not, which
+ * has no one to answer.
  */
-export function fitLine(line        )                {
+export function fitLine(line        , limit = RELAY_REPLY_LIMIT)                {
   const bytes = Buffer.byteLength(line, "utf8");
-  if (bytes <= RELAY_REPLY_LIMIT) return line;
+  if (bytes <= limit) return line;
   let id         ;
   try { id = (JSON.parse(line)                    ).id; } catch { return null; }
   if (id === undefined || id === null) return null;
-  return JSON.stringify({ id, error: { code: -32010, message: `the reply is ${bytes} bytes, more than the relay carries (${RELAY_REPLY_LIMIT})`, data: { replicaTooLarge: { bytes, limit: RELAY_REPLY_LIMIT } } } });
+  return JSON.stringify({ id, error: { code: -32010, message: `the reply is ${bytes} bytes, more than the relay carries (${limit})`, data: { replicaTooLarge: { bytes, limit } } } });
 }

package/src/protocol.js

@@ -2,6 +2,8 @@
 // Everything here is plain Node: X25519, HKDF-SHA256, ChaCha20-Poly1305 and HMAC-SHA256 match CryptoKit's
 // Curve25519.KeyAgreement, HKDF<SHA256>, ChaChaPoly and HMAC<SHA256>, so the Swift side can follow the same steps.
 import crypto from "node:crypto";
+import zlib from "node:zlib";
+import { promisify } from "node:util";
 
 export const PROTOCOL = "chatreplica-relay-v1";
 export const LINK_SCHEME = "chatreplica:";
@@ -15,6 +17,17 @@ export const MAX_FRAME_BYTES = 16 * 1024 * 1024;
  * of a big file) come back as a JSON-RPC error instead of a frame the relay would refuse by closing the connection.
  */
 export const RELAY_REPLY_LIMIT = 11 * 1024 * 1024;
+/**
+ * Long messages, the way Codex remote-control splits them (openai/codex app-server-transport remote_control/segment.rs):
+ * when both sides say `seg` (the phone in resume, the bridge in ready), a line over SEGMENT_BYTES goes as `chunk`
+ * messages of at most SEGMENT_BYTES each, at most SEGMENT_COUNT_MAX of them, up to REASSEMBLED_MAX_BYTES; the receiver
+ * checks every chunk's segment, count and size. Unlike remote-control the payload is raw deflate of the line (`z`),
+ * since the relay's frames are encrypted and nothing on the way can compress them. A chunk travels sealed and
+ * base64url encoded in about 180 KiB of frame, so pings still get through while a long message is on its way.
+ */
+export const SEGMENT_BYTES = 100 * 1024;
+export const SEGMENT_COUNT_MAX = 1024;
+export const REASSEMBLED_MAX_BYTES = 100 * 1024 * 1024;
 
 export const b64url = (data            )         => Buffer.from(data).toString("base64url");
 export const fromB64url = (text        )         => Buffer.from(text, "base64url");
@@ -208,12 +221,78 @@ export class FrameCipher {
 
 /** What is inside a data frame. */
                           
-                                                       
-                                                                 
-                                           
+                                                                
+                                                                          
+              
+                
                              
                                     
 
+                                                                 
+/** One segment of a long line: `data` is base64 of bytes [segment * chunk size, …) of the payload, `size` its length. */
+                                                                                                                             
+                                                        
+/** What a StreamBuffer keeps until the peer acknowledges it. */
+                                                 
+
+/** The payload cut into chunks: SEGMENT_BYTES each, or larger only to stay within SEGMENT_COUNT_MAX. */
+export function chunkParts(payload        , z         , segmentBytes = SEGMENT_BYTES)              {
+  const size = payload.length;
+  const chunkSize = Math.max(segmentBytes, Math.ceil(size / SEGMENT_COUNT_MAX));
+  const segments = Math.max(1, Math.ceil(size / chunkSize));
+  return Array.from({ length: segments }, (_, segment) => ({
+    segment, segments, size, ...(z ? { z: 1          } : {}), data: payload.subarray(segment * chunkSize, (segment + 1) * chunkSize).toString("base64"),
+  }));
+}
+
+const deflateRaw = promisify(zlib.deflateRaw);
+
+/** A line as a `seg` peer takes it: as it is up to SEGMENT_BYTES, otherwise deflated and in chunks. */
+export async function encodeLine(line        )                                  {
+  const bytes = Buffer.from(line, "utf8");
+  if (bytes.length <= SEGMENT_BYTES) return [line];
+  return chunkParts(await deflateRaw(bytes), true);
+}
+
+/** encodeLine without yielding, for the test phone. */
+export function encodeLineSync(line        )                         {
+  const bytes = Buffer.from(line, "utf8");
+  if (bytes.length <= SEGMENT_BYTES) return [line];
+  return chunkParts(zlib.deflateRawSync(bytes), true);
+}
+
+/**
+ * Puts one stream's chunks back together. Chunks arrive in seq order, so a line's segments are consecutive; anything
+ * else (a skipped segment, a changed count or size, more bytes than announced, a `msg` in the middle) is a protocol
+ * error, since the peer is authenticated and only a bug would send it.
+ */
+export class ChunkAssembler {
+          parts           = [];
+          received = 0;
+          first                   = null;
+
+  get busy() { return this.first !== null; }
+
+  take(message           )                {
+    const { segment, segments, size } = message;
+    if (!Number.isInteger(segments) || segments < 1 || segments > SEGMENT_COUNT_MAX || !Number.isInteger(size) || size < 1 || size > REASSEMBLED_MAX_BYTES) {
+      throw new Error("chunk count or size out of range");
+    }
+    const first = this.first ?? message;
+    if (segment !== this.parts.length || first.segments !== segments || first.size !== size || first.z !== message.z) throw new Error(`chunk ${segment} out of order`);
+    const data = Buffer.from(message.data, "base64");
+    this.received += data.length;
+    if (data.length === 0 || this.received > size) throw new Error("chunk carries more than its size");
+    this.first = first;
+    this.parts.push(data);
+    if (segment < segments - 1) return null;
+    if (this.received !== size) throw new Error("chunks carry less than their size");
+    const payload = Buffer.concat(this.parts);
+    this.parts = []; this.received = 0; this.first = null;
+    return (message.z ? zlib.inflateRawSync(payload, { maxOutputLength: REASSEMBLED_MAX_BYTES }) : payload).toString("utf8");
+  }
+}
+
 /** Relay ↔ host multiplexing: one host WebSocket carries every phone connection. */
                           
                                                   
@@ -236,26 +315,28 @@ export const CloseCode = {
 export class StreamBuffer {
   nextSeq = 1;
   received = 0;
-          unacked                                                = [];
+          unacked                                        = [];
           bytes = 0;
 
                    maxBytes        ;
   constructor(maxBytes = 32 * 1024 * 1024) { this.maxBytes = maxBytes; }
 
-  push(line        )                                {
-    const item = { seq: this.nextSeq++, line, size: Buffer.byteLength(line) };
+  push(part                    )           {
+    const seq = this.nextSeq++;
+    const message           = typeof part === "string" ? { t: "msg", seq, line: part } : { t: "chunk", seq, ...part };
+    const item = { message, size: Buffer.byteLength(message.t === "msg" ? message.line : message.data) };
     this.unacked.push(item);
     this.bytes += item.size;
     if (this.bytes > this.maxBytes) throw new Error("unacknowledged buffer full");
-    return item;
+    return message;
   }
 
   ack(seq        ) {
-    while (this.unacked.length && this.unacked[0].seq <= seq) this.bytes -= this.unacked.shift() .size;
+    while (this.unacked.length && this.unacked[0].message.seq <= seq) this.bytes -= this.unacked.shift() .size;
   }
 
-  pending(after        )                                  {
-    return this.unacked.filter((item) => item.seq > after);
+  pending(after        )             {
+    return this.unacked.filter((item) => item.message.seq > after).map((item) => item.message);
   }
 
   /** True when the line is new; duplicates from a resend are dropped. Gaps cannot happen on one ordered socket. */