@mulmobridge/client 1.2.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/dist/inProcess.d.ts

@@ -0,0 +1,34 @@
+import type { Attachment, BridgeOptions } from "@mulmobridge/protocol";
+import type { BridgeClient, PushEvent } from "./client.js";
+/** Shape of `chat-service`'s `RelayResult`, restated so this package does not
+ *  import the server package. Kept structural on purpose: the host passes its
+ *  own function and TypeScript checks the two agree. */
+export type InProcessRelayResult = {
+    kind: "ok";
+    reply: string;
+} | {
+    kind: "error";
+    status: number;
+    message: string;
+};
+export type InProcessRelayFn = (params: {
+    transportId: string;
+    externalChatId: string;
+    text: string;
+    attachments?: Attachment[] | undefined;
+    bridgeOptions?: Readonly<Record<string, string | number | boolean>> | undefined;
+    onChunk?: ((text: string) => void) | undefined;
+}) => Promise<InProcessRelayResult>;
+/** Registers this bridge to receive server → bridge pushes. Returns the
+ *  unregister function, which `close()` calls. */
+export type RegisterInProcessPush = (transportId: string, handler: (event: PushEvent) => void) => () => void;
+export interface InProcessBridgeClientOptions {
+    transportId: string;
+    relay: InProcessRelayFn;
+    registerPush: RegisterInProcessPush;
+    /** Forwarded to the host's `startChat` exactly as the handshake bag is on the
+     *  socket path. Defaults to `{}` — an in-process bridge is configured by the
+     *  host, so there is no env to scrape on its behalf. */
+    options?: BridgeOptions;
+}
+export declare function createInProcessBridgeClient(opts: InProcessBridgeClientOptions): BridgeClient;

package/dist/inProcess.js

@@ -0,0 +1,77 @@
+// A `BridgeClient` that talks to a chat service living in the SAME process,
+// with no socket, no port and no bearer token (#3080).
+//
+// `packages/chat-service/src/relay.ts` calls itself "the shared core of the
+// bridge chat flow ... HTTP (router) and socket.io transports both call the
+// `RelayFn` this factory returns". This is the third caller of that same core,
+// so nothing new is introduced server-side — only a different way in.
+//
+// The relay and the push registration arrive as callbacks rather than imports:
+// `@mulmobridge/client` sits BELOW the server in the dependency direction and
+// must not import `@mulmoclaude/chat-service`.
+export function createInProcessBridgeClient(opts) {
+    const bridgeOptions = opts.options ?? {};
+    const pushHandlers = [];
+    const chunkHandlers = [];
+    let unregisterPush = null;
+    let closed = false;
+    const deliverPush = (event) => {
+        for (const handler of pushHandlers) {
+            try {
+                handler(event);
+            }
+            catch (err) {
+                // Per subscriber, so one bad handler does not stop the ones after it
+                // from seeing the push — and does not reach the server's stack.
+                console.error(`[${opts.transportId}] push handler threw: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    };
+    const send = async (externalChatId, text, attachments) => {
+        if (closed)
+            return { ok: false, error: "bridge client is closed" };
+        const result = await opts.relay({
+            transportId: opts.transportId,
+            externalChatId,
+            text,
+            attachments,
+            bridgeOptions,
+            // Only subscribe the relay to chunks when someone is listening, so the
+            // serialiser is not paying for a stream nobody reads.
+            onChunk: chunkHandlers.length > 0 ? (chunk) => chunkHandlers.forEach((handler) => handler(chunk)) : undefined,
+        });
+        return result.kind === "ok" ? { ok: true, reply: result.reply } : { ok: false, error: result.message, status: result.status };
+    };
+    return {
+        send,
+        onPush(handler) {
+            pushHandlers.push(handler);
+            // Registered on the FIRST subscriber so a bridge that never listens costs
+            // the host nothing, and only once however many handlers are added.
+            unregisterPush ??= opts.registerPush(opts.transportId, deliverPush);
+        },
+        onTextChunk(handler) {
+            chunkHandlers.push(handler);
+        },
+        // There is no socket, so there is no connection to gain or lose. An
+        // in-process bridge is connected from the moment it is constructed.
+        onConnect(handler) {
+            handler();
+        },
+        onDisconnect() { },
+        close() {
+            closed = true;
+            unregisterPush?.();
+            unregisterPush = null;
+            pushHandlers.length = 0;
+            chunkHandlers.length = 0;
+        },
+        get socket() {
+            // Deliberately loud rather than null. Measured across all 25 bridges: none
+            // reads `.socket`, so the first caller to do so is writing new code against
+            // an assumption that does not hold here, and a null would surface as an
+            // unrelated TypeError somewhere downstream.
+            throw new Error("in-process bridge client has no socket — see packages/client/src/inProcess.ts");
+        },
+    };
+}

package/dist/index.d.ts

@@ -8,3 +8,4 @@ export { asJsonRecord, fetchJsonRecord, type JsonRecord } from "./http.js";
 export { formatAckReply } from "./reply.js";
 export { mimeFromExtension, isImageMime, isPdfMime, isSupportedAttachmentMime, isNativeAttachmentMime, parseDataUrl, buildDataUrl, type ParsedDataUrl, } from "./mime.js";
 export { installProcessGuards, SHUTDOWN_GRACE_MS, type ProcessGuardOptions, type ShutdownTask } from "./processGuards.js";
+export { createInProcessBridgeClient, type InProcessBridgeClientOptions, type InProcessRelayFn, type InProcessRelayResult, type RegisterInProcessPush, } from "./inProcess.js";

package/dist/index.js

@@ -9,3 +9,4 @@ export { asJsonRecord, fetchJsonRecord } from "./http.js";
 export { formatAckReply } from "./reply.js";
 export { mimeFromExtension, isImageMime, isPdfMime, isSupportedAttachmentMime, isNativeAttachmentMime, parseDataUrl, buildDataUrl, } from "./mime.js";
 export { installProcessGuards, SHUTDOWN_GRACE_MS } from "./processGuards.js";
+export { createInProcessBridgeClient, } from "./inProcess.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mulmobridge/client",
-  "version": "1.2.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.4.1",
+    "@types/node": "^26.6.3",
     "typescript": "^6.0.3"
   },
   "homepage": "https://github.com/receptron/mulmoclaude/tree/main/packages/client#readme",