replica-bridge 0.3.17 → 0.3.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "replica-bridge",
-  "version": "0.3.17",
+  "version": "0.3.19",
   "description": "Lets the ChatReplica iPhone app use Codex on this computer through a relay, end-to-end encrypted.",
   "type": "module",
   "bin": {

package/src/bridge/install.js

@@ -216,7 +216,7 @@ WantedBy=default.target
 function serviceEnv()                         {
   const env                         = {};
   for (const [key, value] of Object.entries(process.env)) {
-    if (value !== undefined && (key === "PATH" || key === "Path" || /^(CODEX_|REPLICA_|RELAY_ENV$|AGENS_BACKEND_PORT$)/.test(key)) && key !== "REPLICA_BRIDGE_LOG") env[key] = value;
+    if (value !== undefined && (key === "PATH" || key === "Path" || /^(CODEX_|REPLICA_|RELAY_ENV$|AGENS_BACKEND_PORT$|AGENS_WORKSPACE_ROOT$)/.test(key)) && key !== "REPLICA_BRIDGE_LOG") env[key] = value;
   }
   for (const key of ["PATH", "Path"]) if (env[key]) env[key] = servicePATH(env[key]);
   env.REPLICA_BRIDGE_SERVICE = "1";

package/src/bridge/main.js

@@ -83,12 +83,19 @@ function startBridge()                {
   return service;
 }
 
-/** Warns, without stopping, when Codex does not answer the way the bridge will run it (through the login shell). */
+/**
+ * Warns, without stopping, when Codex does not answer the way the bridge will run it (through the login shell).
+ * The shell is interactive (-i) so it reads the rc file where people put Codex on PATH, and an interactive shell that
+ * shares this terminal takes job control of it: zsh, and some bash set-ups, left the terminal to their own process
+ * group, so the next read of the terminal (the [Y/n] question, or "Allow?") stopped this process ("[1]+ Stopped
+ * npx replica-bridge", 2026-11-08) and with it the relay connection. `detached` starts it in its own session, with no
+ * terminal to take; it still reads the rc file.
+ */
 function checkCodex() {
   const codex = values.codex ?? "codex";
   const loginShell = process.platform !== "win32" && !values["no-login-shell"] && process.env.SHELL;
   const result = loginShell
-    ? spawnCommandSync(process.env.SHELL , ["-lic", `"$0" --version`, codex], { encoding: "utf8", timeout: 15_000 })
+    ? spawnCommandSync(process.env.SHELL , ["-lic", `"$0" --version`, codex], { encoding: "utf8", timeout: 15_000, detached: true })
     : spawnCommandSync(codex, ["--version"], { encoding: "utf8", timeout: 15_000 });
   if (result.status === 0) return;
   console.warn(`Codex did not answer "${codex} --version". Install it (npm install -g @openai/codex) and sign in (codex login); the phone cannot use this computer until then.`);
@@ -111,7 +118,55 @@ async function wantBackground()                   {
   return ask("Keep it running in the background and start it at login, so you can close this terminal? [Y/n] ");
 }
 
-function install()       {
+/** How long to wait for the relay socket before saying it has not connected; a working network takes well under a second. */
+const RELAY_WAIT_MS = Number(process.env.REPLICA_BRIDGE_RELAY_WAIT_MS ?? 10_000);
+
+/**
+ * Said when the bridge has not reached the relay. Enrolling and pairing are plain HTTPS requests, so they work on a
+ * network that blocks the WebSocket; then the phone pairs and shows the computer offline with no hint why
+ * (2026-11-08). The bridge keeps retrying, so this is a warning, not a stop.
+ */
+function relayWarning(relay        , problem               )         {
+  const socket = relay.replace(/^http/, "ws");
+  return [
+    `This computer has not connected to the relay yet${problem ? `: ${problem}` : ` (no answer within ${RELAY_WAIT_MS / 1000} s)`}.`,
+    "Until it does, the phone shows this computer offline. Pairing still works, since it uses plain HTTPS, and the bridge keeps trying.",
+    `A proxy or firewall that lets HTTPS through but blocks WebSocket connections to ${socket} causes exactly this.`,
+  ].join("\n");
+}
+
+/** Waits for this process's bridge to reach the relay and warns when it does not. */
+async function checkRelay(bridge               , relay        )                   {
+  if (await bridge.waitForRelay(RELAY_WAIT_MS)) return true;
+  console.warn(relayWarning(relay, bridge.relayProblem));
+  return false;
+}
+
+/** The background service's log past `offset` bytes, or "" before it exists. */
+function logSince(offset        )         {
+  try { return fs.readFileSync(logPath()).subarray(offset).toString("utf8"); } catch { return ""; }
+}
+
+function logSize()         {
+  try { return fs.statSync(logPath()).size; } catch { return 0; }
+}
+
+/** The background service is another process: its log is the only place that says whether it reached the relay. */
+async function checkServiceRelay(offset        , relay        ) {
+  for (let waited = 0; waited < RELAY_WAIT_MS; waited += 250) {
+    if (/ connected to relay /.test(logSince(offset))) return;
+    await new Promise((resolve) => setTimeout(resolve, 250));
+  }
+  const text = logSince(offset);
+  if (/ connected to relay /.test(text)) return;
+  const problems = [...text.matchAll(/relay connection error: (.*)|relay refused the host connection: (HTTP \d+)/g)];
+  const last = problems.at(-1);
+  console.warn(relayWarning(relay, last ? (last[1] ?? `${last[2]} instead of a WebSocket`) : null));
+  console.warn(`The background service keeps trying; its log is ${logPath()}.`);
+}
+
+async function install()                {
+  const offset = logSize();
   const plan = installService(startArgs(), console.log);
   // The service writes its pid once it has started; `status` right after the install said "not running" before that.
   for (let waited = 0; !runningPid() && waited < 10_000; waited += 200) Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 200);
@@ -122,6 +177,7 @@ function install()       {
   if (process.platform === "linux" && !fs.existsSync(`/var/lib/systemd/linger/${user}`)) {
     console.log(`To start it when the computer boots, before anyone logs in: sudo loginctl enable-linger ${user}`);
   }
+  await checkServiceRelay(offset, loadState().relay);
 }
 
 async function pairOrExplain() {
@@ -156,19 +212,20 @@ async function main() {
         // The background service serves the phone: restart it onto a new set-up or a newer version, then pair.
         if (moved) console.log("Restarting the background service with the new set-up.");
         else if (installed.version !== PACKAGE_VERSION) console.log(`Updating the background service from ${installed.version} to ${PACKAGE_VERSION}.`);
-        if (moved || values.install || installed.version !== PACKAGE_VERSION) install();
+        if (moved || values.install || installed.version !== PACKAGE_VERSION) await install();
         if (moved || values.pair || !state.devices.length) await pairOrExplain();
         else status();
         break;
       }
       if (runningPid()) throw new Error(`a bridge already runs for this computer (pid ${runningPid()}); stop it first`);
       let bridge = startBridge();
+      await checkRelay(bridge, state.relay);
       if (values.pair || !state.devices.length) await pairOrExplain();
       if (loadState().devices.length && await wantBackground()) {
         // One bridge per computer: the relay keeps only the newest connection for it.
         bridge.stop();
         try {
-          install();
+          await install();
           process.exit(0);
         } catch (error) {
           console.error(`replica-bridge: could not set up the background service: ${(error         ).message}`);
@@ -177,11 +234,12 @@ async function main() {
       }
       for (const signal of ["SIGINT", "SIGTERM"]         ) process.on(signal, () => { bridge.stop(); process.exit(0); });
       console.log(`Running in this terminal: paired phones can use Codex on ${state.hostName} until it closes (Ctrl-C stops it).`);
+      if (!(await bridge.waitForRelay(RELAY_WAIT_MS))) console.warn(`Still not connected to the relay${bridge.relayProblem ? ` (${bridge.relayProblem})` : ""}: the phone shows ${state.hostName} offline until it is.`);
       break;
     }
     case "install":
       await ensureRelay(values.relay, console.log, values.name);
-      install();
+      await install();
       break;
     case "uninstall": {
       const plan = uninstallService();
@@ -196,7 +254,7 @@ async function main() {
       const state = await enroll(relay, { name: values.name, publicRelay: values["public-url"] });
       console.log(`Set up ${state.hostName} as ${state.hostId}. Next: "npx replica-bridge".`);
       console.log("Nobody owns it yet: the first phone that scans its QR code and is approved here claims it.");
-      if (readServiceInfo()) { console.log("Restarting the background service with the new set-up."); install(); }
+      if (readServiceInfo()) { console.log("Restarting the background service with the new set-up."); await install(); }
       break;
     }
     case "config": {
@@ -209,7 +267,7 @@ async function main() {
     case "pair":
       if ((await ensureRelay(values.relay, console.log, values.name)).moved && readServiceInfo()) {
         console.log("Restarting the background service with the new set-up.");
-        install();
+        await install();
       }
       await pair({ confirm: values.confirm, yes: values.yes, timeoutSeconds: Number(values.timeout), pngPath: values.png });
       if (!runningPid()) console.log(`Nothing serves this computer right now: run "npx replica-bridge" so the phone can connect.`);

package/src/bridge/service.js

@@ -15,6 +15,7 @@ import {
                                                                             
 import { relaySocketURL } from "../http.js";
 import { BoardReader } from "./board.js";
+import { readWork, workDirectories } from "./work.js";
 import { killCommand, spawnCommand } from "./command.js";
 import { hostKeyPair, loadState } from "./state.js";
 import { annotateWriterError } from "./writer.js";
@@ -57,6 +58,8 @@ import { annotateWriterError } from "./writer.js";
                      
                                                                    
                             
+                                                                                              
+                             
  
 
                   
@@ -121,12 +124,42 @@ export class BridgeService {
 
   get streamCount() { return this.streams.size; }
 
+  /** The relay socket is open: phones see this computer online. */
+  get relayConnected() { return this.relay?.readyState === WebSocket.OPEN; }
+
+  /** Why the last attempt to reach the relay failed, while it has not connected since. */
+  get relayProblem() { return this.lastRelayProblem; }
+
+          lastRelayProblem                = null;
+                   relayWaiters = new Set            ();
+
+  /**
+   * Waits up to `ms` for the relay socket to open. Pairing goes over plain HTTPS, so a network that lets HTTPS through
+   * but not the WebSocket (2026-11-08: two computers paired, never once came online, and the phone showed both
+   * offline) pairs fine and leaves nothing for the phone to reach; the caller says so instead of looking finished.
+   */
+  async waitForRelay(ms        )                   {
+    if (this.relayConnected) return true;
+    await new Promise      ((resolve) => {
+      const done = () => { clearTimeout(timer); this.relayWaiters.delete(done); resolve(); };
+      const timer = setTimeout(done, ms);
+      this.relayWaiters.add(done);
+    });
+    return this.relayConnected;
+  }
+
+  /** Only an open socket ends the wait early: a first attempt that fails often succeeds on the retry a second later. */
+          relayChanged() {
+    for (const waiter of [...this.relayWaiters]) waiter();
+  }
+
   // MARK: - Relay connection
 
           connectRelay() {
     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;
+    let refused = false;
     // 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;
@@ -138,7 +171,14 @@ export class BridgeService {
     }, (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}`); this.options.onRelayConnected?.(true); });
+    ws.on("open", () => {
+      answered = true;
+      this.retry = 0;
+      this.lastRelayProblem = null;
+      this.log(`connected to relay ${state.relay} as ${state.hostId}`);
+      this.options.onRelayConnected?.(true);
+      this.relayChanged();
+    });
     ws.on("message", (data         ) => {
       let envelope              ;
       try { envelope = JSON.parse(data.toString()); } catch { return; }
@@ -149,10 +189,16 @@ export class BridgeService {
     // process ran out of work and exited 0, which the background services read as "replaced" and left stopped.
     // Ending the socket goes through close and the usual backoff instead.
     ws.on("unexpected-response", (_req, res) => {
+      refused = true;
+      this.lastRelayProblem = `HTTP ${res.statusCode} instead of a WebSocket`;
       this.log(`relay refused the host connection: HTTP ${res.statusCode}; retrying`);
       ws.terminate();
     });
-    ws.on("error", (error) => this.log(`relay connection error: ${error.message}`));
+    ws.on("error", (error) => {
+      // Ending a refused socket also reports "closed before the connection was established"; the status says more.
+      if (!refused) this.lastRelayProblem = describeSocketError(error);
+      this.log(`relay connection error: ${this.lastRelayProblem}`);
+    });
     ws.on("close", (code) => {
       clearInterval(ping);
       if (ws !== this.relay) return; // a socket this bridge already replaced itself
@@ -273,6 +319,9 @@ export class BridgeService {
       void this.board.post(message.path, message.body).then((answer) => this.sendInner(conn, { t: "board/res", id: message.id, ...answer }));
     } else if (message.t === "board/sub") {
       conn.boardUnsubscribe ??= this.board.subscribe((event) => this.sendInner(conn, event), message.after);
+    } else if (message.t === "work/get") {
+      // Read when asked, so a new main conversation started on the desktop is what the next question hears.
+      this.sendInner(conn, { t: "work/res", id: message.id, ...readWork(this.options.workDirectories ?? workDirectories()) });
     } else if (message.t === "board/unsub") {
       conn.boardUnsubscribe?.();
       conn.boardUnsubscribe = null;
@@ -420,9 +469,10 @@ export class BridgeService {
   }
 
   /** Runs a command to completion; true when it exits 0 within 30 s. Output is dropped (an rc file may print). */
-          run(command        , args          )                   {
+  /** `detached` for an interactive login shell, which would otherwise take the terminal of a bridge run in one (main.ts checkCodex). */
+          run(command        , args          , detached = false)                   {
     return new Promise((resolve, reject) => {
-      const child = spawnCommand(command, args, { stdio: "ignore" });
+      const child = spawnCommand(command, args, { stdio: "ignore", detached });
       const timer = setTimeout(() => { killCommand(child); resolve(false); }, 30_000);
       child.once("error", (error) => { clearTimeout(timer); reject(error); });
       child.once("exit", (code) => { clearTimeout(timer); resolve(code === 0); });
@@ -457,7 +507,7 @@ export class BridgeService {
     // (a SHELL from Git Bash is a POSIX path Node cannot run), so Codex is asked directly there.
     const shell = process.platform === "win32" ? null : process.env.SHELL || os.userInfo().shell;
     const started = this.options.loginShell !== false && shell
-      ? await this.run(shell, ["-lic", 'exec "$0" app-server daemon start', codex]).catch(() => false)
+      ? await this.run(shell, ["-lic", 'exec "$0" app-server daemon start', codex], true).catch(() => false)
       : false;
     if (!started && !(await this.run(codex, ["app-server", "daemon", "start"]).catch(() => false))) {
       throw new Error("codex app-server daemon start failed");
@@ -510,3 +560,13 @@ export function fitLine(line        , limit = RELAY_REPLY_LIMIT)
   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 (${limit})`, data: { replicaTooLarge: { bytes, limit } } } });
 }
+
+/**
+ * An error's message, or its code when Node leaves the message empty: a refused connection tried on both IPv4 and
+ * IPv6 is an AggregateError with message "" and the reasons in `errors`.
+ */
+export function describeSocketError(error       )         {
+  const parts = error instanceof AggregateError ? error.errors : [error];
+  const text = parts.map((e                           ) => e?.message || e?.code || String(e)).filter(Boolean);
+  return [...new Set(text)].join("; ") || error.name;
+}

package/src/bridge/work.js

@@ -0,0 +1,46 @@
+// Agens Work's main conversation (PROTOCOL.md "Work"), for agens-mobile's Work row. The Agens desktop keeps it in
+// agens-work.json in the Work workspace (AgensWorkDev agens/extensions/work-chat/main.cjs): AGENS_WORKSPACE_ROOT, else
+// ~/.agens-work/workspaces/assistant, and the first of those with a record is the one in use. The bridge only reads
+// that file when a phone asks, so it needs no hook into the desktop, and a computer without Agens Work simply says so.
+// Only whether Work is on and the conversation's id leave this computer, not the paths or anything else in the record.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+                                                 
+
+export const WORK_RECORD = "agens-work.json";
+/** A Codex thread id (a UUID); anything else in the record is not passed on. */
+const THREAD_ID = /^[A-Za-z0-9-]{1,64}$/;
+
+/**
+ * What the phone hears (WorkAnswer): on with the main conversation, or off and why. `none`: Agens Work was never agreed
+ * to here; `off`: switched off in its settings; `preparing`: agreed, but the main conversation is not made yet.
+ */
+
+/** Where the desktop looks for the record, in its order (main.cjs chooseWorkspace). */
+export function workDirectories(env                    = process.env, home = os.homedir())           {
+  const legacy = path.join(home, ".agens-work", "workspaces", "assistant");
+  return [...new Set([env.AGENS_WORKSPACE_ROOT || legacy, legacy])];
+}
+
+function readRecord(directory        )                                 {
+  try {
+    const record = JSON.parse(fs.readFileSync(path.join(directory, WORK_RECORD), "utf8"));
+    return record && typeof record === "object" && record.schema === 1 ? record : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Reads the record now, as the desktop would see it. */
+export function readWork(directories           = workDirectories())             {
+  for (const directory of directories) {
+    const record = readRecord(directory);
+    if (!record) continue;
+    // A record without `enabled` predates the desktop's switch, and means on (main.cjs enabled()).
+    if (record.enabled === false) return { on: false, reason: "off" };
+    const threadId = record.mainThreadId;
+    return typeof threadId === "string" && THREAD_ID.test(threadId) ? { on: true, threadId } : { on: false, reason: "preparing" };
+  }
+  return { on: false, reason: "none" };
+}

package/src/protocol.js

@@ -1,4 +1,4 @@
-// Shared protocol for replica-relay, replica-bridge and the test phone (Relay/PROTOCOL.md).
+// Shared protocol for replica-relay, replica-bridge and the test phone (PROTOCOL.md).
 // 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";
@@ -243,7 +243,12 @@ export class FrameCipher {
                                                   
                                       
                         
-               
+              
+                                 
+                                                 
+
+/** Agens Work's main conversation on this computer, or why there is none (PROTOCOL.md "Work", 0.3.19). */
+                                                                                                              
 
 /** A read or write of the optional board: the backend's status and body, or why there is none (PROTOCOL.md "看板"). */
                                                                                                                               
@@ -337,6 +342,8 @@ export const CloseCode = {
   replaced: 4409,
   protocolError: 4400,
   streamGone: 4410,
+  /** A desktop's computer used up its daily traffic; it may connect again after midnight UTC. */
+  quota: 4429,
 }         ;
 
 /**

package/src/relay/config.js

@@ -1,4 +1,4 @@
-// Reads ~/.config/replica-relay/relay.env (Relay/deploy/relay.env.example). Real environment variables win over
+// Reads ~/.config/replica-relay/relay.env (deploy/relay.env.example). Real environment variables win over
 // the file, so a systemd Environment= line or a one-off `RELAY_PORT=… node …` still works.
 import fs from "node:fs";
 import os from "node:os";
@@ -33,6 +33,13 @@ export function readEnvFile(file        )                         {
                
                               
                       
+                                                                                                                            
+                                
+                                                                                              
+                                           
+                                                                         
+                                   
+                                           
                   
                                                                           
                     
@@ -77,6 +84,18 @@ export function allowedIdsReader(config
   };
 }
 
+function desktopPairingMode(value        )                           {
+  if (value === "open" || value === "owned" || value === "off") return value;
+  throw new Error(`RELAY_DESKTOP_PAIRING takes open, owned or off, not "${value}"`);
+}
+
+function positiveNumber(name        , value               )                {
+  if (value === null) return null;
+  const number = Number(value);
+  if (!(number > 0)) throw new Error(`${name} takes a positive number, not "${value}"`);
+  return number;
+}
+
 const expandHome = (value        ) => (value.startsWith("~/") ? path.join(os.homedir(), value.slice(2)) : value);
 
 export function loadRelayConfig(envPath = defaultEnvPath())              {
@@ -87,11 +106,16 @@ export function loadRelayConfig(envPath = defaultEnvPath())              {
   };
   const origin = get("RELAY_PUBLIC_ORIGIN");
   if (origin && !/^https?:\/\/[^/]+\/?$/.test(origin)) throw new Error(`RELAY_PUBLIC_ORIGIN must look like https://host[:port], got ${origin}`);
+  const dailyMiB = positiveNumber("RELAY_DESKTOP_DAILY_MIB", get("RELAY_DESKTOP_DAILY_MIB"));
   return {
     listen: get("RELAY_LISTEN") ?? "127.0.0.1",
     port: Number(get("RELAY_PORT") ?? 8790),
     publicOrigin: origin?.replace(/\/$/, "") ?? null,
     trustProxy: get("RELAY_TRUST_PROXY") === "1",
+    clientIPHeader: get("RELAY_CLIENT_IP_HEADER"),
+    desktopPairing: desktopPairingMode(get("RELAY_DESKTOP_PAIRING") ?? "open"),
+    anonymousIdleDays: positiveNumber("RELAY_ANONYMOUS_IDLE_DAYS", get("RELAY_ANONYMOUS_IDLE_DAYS")),
+    desktopBytesPerHostPerDay: dailyMiB === null ? null : dailyMiB * 1024 * 1024,
     dataDir: expandHome(get("RELAY_DATA_DIR") ?? "~/.local/share/replica-relay"),
     devLogin: get("RELAY_DEV_LOGIN") === "1",
     githubClientId: get("GITHUB_CLIENT_ID"),