@mulmobridge/client 1.3.0 → 1.4.0

package/README.md

@@ -108,6 +108,30 @@ One case is outside this: a server-initiated disconnect (`io server disconnect`)
 is the one reason socket.io does not retry, so no connection failure follows it.
 The chat-service never issues one, so there is nothing to recover from today.
 
+## How long `send()` waits
+
+The server gives the agent **5 minutes** per turn, then replies with whatever
+text has streamed so far — anything the agent produces after that is dropped.
+`send()` waits one minute longer than that, so the server's reply always wins
+over a client-side timeout.
+
+To give long turns more time, set the limit in milliseconds on the bridge:
+
+```bash
+BRIDGE_REPLY_TIMEOUT_MS=1800000          # every bridge: 30 minutes
+DISCORD_BRIDGE_REPLY_TIMEOUT_MS=1800000  # this bridge only (wins over the shared form)
+```
+
+It travels to the server in the handshake options, so the server and `send()`
+always use the same value — nothing to keep in step by hand. A value that is not
+a positive whole number is ignored with a warning (the default applies); one
+past Node's timer ceiling (about 24.8 days) is clamped with a warning.
+
+While a turn is running, the next message in the same chat waits for it, so a
+longer limit can also mean a longer wait for the message after it. Upgrade the
+bridge together with the server: an older client keeps its fixed 6-minute wait
+and gives up before a longer server limit ends.
+
 ## Ecosystem
 
 Part of the [`@mulmobridge/*`](https://www.npmjs.com/~mulmobridge) package family.

package/dist/ackTimeout.d.ts

@@ -0,0 +1,5 @@
+import { type BridgeOptions } from "@mulmobridge/protocol";
+/** How long `send()` waits for the ack. Read from the same option the handshake
+ *  sends the server, so it always outlasts the server's reply limit and the
+ *  server's timeout surfaces as a reply, not a client-side cancellation. */
+export declare function resolveAckTimeoutMs(options: BridgeOptions, warn: (message: string) => void): number;

package/dist/ackTimeout.js

@@ -0,0 +1,10 @@
+import { ackTimeoutMsFor, resolveReplyTimeoutMs } from "@mulmobridge/protocol";
+/** How long `send()` waits for the ack. Read from the same option the handshake
+ *  sends the server, so it always outlasts the server's reply limit and the
+ *  server's timeout surfaces as a reply, not a client-side cancellation. */
+export function resolveAckTimeoutMs(options, warn) {
+    const { replyTimeoutMs, warning } = resolveReplyTimeoutMs(options.replyTimeoutMs);
+    if (warning)
+        warn(`[bridge] ${warning}`);
+    return ackTimeoutMsFor(replyTimeoutMs);
+}

package/dist/client.js

@@ -13,13 +13,11 @@
 // minimal non-Node equivalent.
 import { io } from "socket.io-client";
 import { CHAT_SOCKET_EVENTS, CHAT_SOCKET_PATH } from "@mulmobridge/protocol";
+import { resolveAckTimeoutMs } from "./ackTimeout.js";
 import { readBridgeToken, tokenFilePath } from "./token.js";
 import { readBridgeEnvOptions } from "./options.js";
 import { DEFAULT_API_URL, resolvePublishedApiUrl } from "./apiUrl.js";
 import { backoffMs, credentialsChanged } from "./supervisor.js";
-// 6 min > the server's REPLY_TIMEOUT_MS (5 min) so the server's
-// timeout surfaces as a reply, not a client-side cancellation.
-const REPLY_TIMEOUT_MS = 6 * 60 * 1000;
 /**
  * Resolve the bearer token from the workspace / env var, exit with
  * a clear error if absent. Kept separate so bridges that want to
@@ -69,7 +67,10 @@ export function createBridgeClient(opts) {
     const token = requireBearerToken();
     // `opts.options === undefined` → scrape env automatically.
     // `opts.options === {}` → opt out of the scrape explicitly.
-    const options = opts.options ?? readBridgeEnvOptions(opts.transportId, process.env);
+    // A copy: every reconnect re-sends it, and the ack limit below is fixed from it
+    // once, so a caller mutating their object later must not move one without the other.
+    const options = { ...(opts.options ?? readBridgeEnvOptions(opts.transportId, process.env)) };
+    const ackTimeoutMs = resolveAckTimeoutMs(options, console.error);
     const subscriptions = emptySubscriptions();
     const pending = new Set();
     const published = resolvePublishedApiUrl(opts.apiUrl);
@@ -191,7 +192,7 @@ export function createBridgeClient(opts) {
         live.retry = setTimeout(reresolve, backoffMs(live.attempt));
     }
     return {
-        send: (externalChatId, text, attachments) => sendMessage(live.socket, pending, externalChatId, text, attachments),
+        send: (externalChatId, text, attachments) => sendMessage({ socket: live.socket, pending, ackTimeoutMs }, externalChatId, text, attachments),
         onPush: (handler) => {
             subscriptions.push.push(handler);
             live.socket.on(CHAT_SOCKET_EVENTS.push, handler);
@@ -222,7 +223,8 @@ export function createBridgeClient(opts) {
         },
     };
 }
-function sendMessage(socket, pending, externalChatId, text, attachments) {
+function sendMessage(channel, externalChatId, text, attachments) {
+    const { socket, pending, ackTimeoutMs } = channel;
     const payload = { externalChatId, text };
     if (attachments && attachments.length > 0)
         payload.attachments = attachments;
@@ -231,7 +233,7 @@ function sendMessage(socket, pending, externalChatId, text, attachments) {
         // CANCELLABLE. socket.io arms its ack timer at emit time and keeps it armed
         // on a socket that is closed underneath it, so a send abandoned by a rebuild
         // left a six-minute timer behind per send — measured: the test process exited
-        // at 6:00.45, exactly REPLY_TIMEOUT_MS, long after every assertion had passed
+        // at 6:00.45, exactly the ack timeout, long after every assertion had passed
         // (Codex, #3078). `settle` clears it, so `abandon` clears it too.
         const state = {};
         const settle = (ack) => {
@@ -240,7 +242,7 @@ function sendMessage(socket, pending, externalChatId, text, attachments) {
             clearTimeout(state.timer);
             resolve(ack);
         };
-        state.timer = setTimeout(() => settle({ ok: false, error: `timeout: no ack within ${REPLY_TIMEOUT_MS}ms` }), REPLY_TIMEOUT_MS);
+        state.timer = setTimeout(() => settle({ ok: false, error: `timeout: no ack within ${ackTimeoutMs}ms` }), ackTimeoutMs);
         pending.add(settle);
         socket.emit(CHAT_SOCKET_EVENTS.message, payload, (ack) => {
             settle(ack ?? { ok: false, error: "no ack from server" });
@@ -253,8 +255,8 @@ function sendMessage(socket, pending, externalChatId, text, attachments) {
  * socket.io settles an IN-FLIGHT ack immediately when its socket closes, but a
  * send issued while the socket was already disconnected is queued for a
  * reconnection that will never happen here — the socket is being replaced, not
- * reconnected — so its callback would sit for the full 6-minute ack timeout
- * (measured, Codex). The bridge's user would wait six minutes for a message the
+ * reconnected — so its callback would sit for the full ack timeout
+ * (measured, Codex). The bridge's user would wait that whole time for a message the
  * client already knows it cannot deliver.
  */
 function abandon(pending, reason) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mulmobridge/client",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Socket.io client library for MulmoBridge — shared by all bridge implementations",
   "type": "module",
   "main": "./dist/index.js",
@@ -38,19 +38,19 @@
   "scripts": {
     "build": "tsc",
     "prepack": "yarn build",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc -p tsconfig.typecheck.json",
     "test": "tsx --test test/test_*.ts",
     "lint": "eslint src test"
   },
   "license": "MIT",
   "author": "Receptron Team",
   "dependencies": {
-    "@mulmobridge/protocol": "^1.0.1",
+    "@mulmobridge/protocol": "^1.1.0",
     "@mulmoclaude/common": "^1.3.0",
     "socket.io-client": "^4.0.0"
   },
   "devDependencies": {
-    "@types/node": "^26.5.1",
+    "@types/node": "^26.6.3",
     "typescript": "^6.0.3"
   },
   "homepage": "https://github.com/receptron/mulmoclaude/tree/main/packages/client#readme",