@mulmobridge/client 1.0.2 → 1.1.0

package/README.md

@@ -17,7 +17,8 @@ yarn add @mulmobridge/client
 | `createBridgeClient(opts)` | Create a connected socket.io client with auth |
 | `requireBearerToken()` | Read the bearer token or exit with a helpful message |
 | `readBridgeToken()` | Read the bearer token (returns `null` if absent) |
-| `TOKEN_FILE_PATH` | Path to `~/mulmoclaude/.session-token` |
+| `TOKEN_FILE_PATH` | Path to the workspace's `.session-token` |
+| `resolveApiUrl(explicit?)` | Resolve the server URL a bridge should connect to |
 | `mimeFromExtension(ext)` | Map file extension to MIME type |
 | `isImageMime(mime)` | Check if MIME is an image type |
 | `isPdfMime(mime)` | Check if MIME is PDF |
@@ -47,6 +48,39 @@ client.onPush((ev) => {
 });
 ```
 
+## Which server it connects to
+
+The MulmoClaude server is **not pinned to port 3001**. It honours `PORT`, and an
+implicit default that is already busy walks forward (`Port 3001 busy → using 3002
+instead`). Whatever it ends up binding, it publishes to `<workspace>/.server-port`
+— the file every out-of-process reader uses to find it.
+
+`createBridgeClient()` resolves the address in this order:
+
+1. `opts.apiUrl` — an explicit value always wins
+2. `$MULMOCLAUDE_API_URL`
+3. `http://127.0.0.1:<port>` from `<workspace>/.server-port`
+4. `http://localhost:3001`
+
+The workspace itself is `$MULMOCLAUDE_WORKSPACE_PATH`, or `~/mulmoclaude` when
+that is unset — the same rule the server applies, and the same root the bearer
+token is read from.
+
+Only `process.env` is consulted. A `.env` file reaches this library through the
+bridge's own `import "dotenv/config"`, which resolves `.env` against the
+process's **current working directory** — so a bridge launched from somewhere
+else does not see a `MULMOCLAUDE_WORKSPACE_PATH` that lives only in the repo's
+`.env`, exactly as it would not see `MULMOCLAUDE_AUTH_TOKEN` there. Export the
+variable, or run the bridge from the directory holding the `.env`.
+
+| Export | Resolves |
+|---|---|
+| `readBridgeToken()` / `tokenFilePath()` | at call time |
+| `TOKEN_FILE_PATH` | at import time — a snapshot, kept for compatibility |
+
+The port is read once, when the client is created. A server that restarts onto a
+*different* port after that still needs the bridge restarted.
+
 ## Ecosystem
 
 Part of the [`@mulmobridge/*`](https://www.npmjs.com/~mulmobridge) package family.

package/dist/apiUrl.d.ts

@@ -0,0 +1,32 @@
+/** Used only when nothing has been published and nothing was configured. */
+export declare const DEFAULT_API_URL = "http://localhost:3001";
+/**
+ * The published port, or `null` for anything that is not one.
+ *
+ * Decimal digits only. The writer is `formatServerPort()`, which emits
+ * `${port}\n` and nothing else, so there is no lenient shape worth
+ * accepting — while `Number.parseInt` would read `3002abc` as 3002 and send
+ * the bridge to a port a corrupted file never meant.
+ */
+export declare function parsePublishedPort(raw: string | null): number | null;
+/**
+ * The origin the running server published, or `null` if it published none.
+ *
+ * `127.0.0.1` rather than `localhost`: the server binds the IPv4 loopback
+ * explicitly (`app.listen(port, "127.0.0.1")`), while `localhost` resolves
+ * to `::1` first on a dual-stack host. Usually that still works — nothing
+ * holds `::1`, the connection is refused and Node falls back to IPv4 — but
+ * when something IS there the client reaches it and never falls back, which
+ * is the silent misdirection this module exists to remove (#2981).
+ */
+export declare function readPublishedApiUrl(): string | null;
+/**
+ * Resolution order: explicit argument → `MULMOCLAUDE_API_URL` → the port the
+ * server published → `DEFAULT_API_URL`.
+ *
+ * An explicit value still wins, so nothing that already sets one changes.
+ * An EMPTY value falls through instead of being used verbatim, matching how
+ * `readBridgeToken` treats an empty `MULMOCLAUDE_AUTH_TOKEN` — an empty
+ * string reached `io("")` before this.
+ */
+export declare function resolveApiUrl(explicit?: string): string;

package/dist/apiUrl.js

@@ -0,0 +1,70 @@
+// Which server a bridge talks to (#3078).
+//
+// The server is not pinned to 3001. `server/index.ts` walks forward off a
+// busy default (`Port 3001 busy → using 3002 instead`) and honours `PORT`,
+// then publishes whatever it actually bound to `<workspace>/.server-port`.
+// A client that does not read that file either connects to nothing (case A:
+// `PORT=3099` and nobody on 3001) or — worse — connects cleanly to a
+// DIFFERENT instance that happens to hold 3001 (case B), which with a shared
+// `MULMOCLAUDE_AUTH_TOKEN` authenticates without a single error.
+//
+// This is the same class as #2650 (Vite's proxy target) and #2981
+// (`wait-for-backend`); both were fixed by reading the published port.
+//
+// A leftover `.server-port` cannot mislead here the way it can mislead
+// `yarn dev`: the file is not removed on shutdown, but the server REWRITES it
+// on every startup, so a running server's entry is always current — and with
+// no server running, the old hardcoded 3001 was just as dead.
+import { readSidecarFile, SIDECAR_FILES } from "./workspace.js";
+/** Used only when nothing has been published and nothing was configured. */
+export const DEFAULT_API_URL = "http://localhost:3001";
+const MIN_PORT = 1;
+const MAX_PORT = 65_535;
+/**
+ * The published port, or `null` for anything that is not one.
+ *
+ * Decimal digits only. The writer is `formatServerPort()`, which emits
+ * `${port}\n` and nothing else, so there is no lenient shape worth
+ * accepting — while `Number.parseInt` would read `3002abc` as 3002 and send
+ * the bridge to a port a corrupted file never meant.
+ */
+export function parsePublishedPort(raw) {
+    if (raw === null)
+        return null;
+    const trimmed = raw.trim();
+    if (!/^\d+$/.test(trimmed))
+        return null;
+    const port = Number.parseInt(trimmed, 10);
+    return port >= MIN_PORT && port <= MAX_PORT ? port : null;
+}
+/**
+ * The origin the running server published, or `null` if it published none.
+ *
+ * `127.0.0.1` rather than `localhost`: the server binds the IPv4 loopback
+ * explicitly (`app.listen(port, "127.0.0.1")`), while `localhost` resolves
+ * to `::1` first on a dual-stack host. Usually that still works — nothing
+ * holds `::1`, the connection is refused and Node falls back to IPv4 — but
+ * when something IS there the client reaches it and never falls back, which
+ * is the silent misdirection this module exists to remove (#2981).
+ */
+export function readPublishedApiUrl() {
+    const port = parsePublishedPort(readSidecarFile(SIDECAR_FILES.port));
+    return port === null ? null : `http://127.0.0.1:${port}`;
+}
+/**
+ * Resolution order: explicit argument → `MULMOCLAUDE_API_URL` → the port the
+ * server published → `DEFAULT_API_URL`.
+ *
+ * An explicit value still wins, so nothing that already sets one changes.
+ * An EMPTY value falls through instead of being used verbatim, matching how
+ * `readBridgeToken` treats an empty `MULMOCLAUDE_AUTH_TOKEN` — an empty
+ * string reached `io("")` before this.
+ */
+export function resolveApiUrl(explicit) {
+    if (typeof explicit === "string" && explicit.length > 0)
+        return explicit;
+    const fromEnv = process.env.MULMOCLAUDE_API_URL;
+    if (typeof fromEnv === "string" && fromEnv.length > 0)
+        return fromEnv;
+    return readPublishedApiUrl() ?? DEFAULT_API_URL;
+}

package/dist/client.d.ts

@@ -14,7 +14,9 @@ export interface BridgeClientOptions {
     /** Required. Identifier for this bridge in the handshake.
      *  Matches `handshake.auth.transportId` server-side. */
     transportId: string;
-    /** Defaults to `$MULMOCLAUDE_API_URL` or `http://localhost:3001`. */
+    /** Defaults to `$MULMOCLAUDE_API_URL`, then the port the server
+     *  published to `<workspace>/.server-port`, then
+     *  `http://localhost:3001` (#3078). */
     apiUrl?: string;
     /** Flat primitive bag forwarded to the host app's startChat
      *  callback via the handshake (`BridgeOptions` from the

package/dist/client.js

@@ -13,12 +13,12 @@
 // minimal non-Node equivalent.
 import { io } from "socket.io-client";
 import { CHAT_SOCKET_EVENTS, CHAT_SOCKET_PATH } from "@mulmobridge/protocol";
-import { readBridgeToken, TOKEN_FILE_PATH } from "./token.js";
+import { readBridgeToken, tokenFilePath } from "./token.js";
 import { readBridgeEnvOptions } from "./options.js";
+import { resolveApiUrl } from "./apiUrl.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;
-const DEFAULT_API_URL = "http://localhost:3001";
 /**
  * Resolve the bearer token from the workspace / env var, exit with
  * a clear error if absent. Kept separate so bridges that want to
@@ -29,16 +29,29 @@ export function requireBearerToken() {
     const token = readBridgeToken();
     if (token !== null)
         return token;
+    // `tokenFilePath()` rather than `TOKEN_FILE_PATH`, which is fixed at module
+    // load: a bridge that imports this before `dotenv/config` would otherwise be
+    // told to look somewhere the token was never going to be.
     process.stderr.write(`No bearer token found. The MulmoClaude server writes one to\n` +
-        `  ${TOKEN_FILE_PATH}\n` +
+        `  ${tokenFilePath()}\n` +
         `at startup (mode 0600). Start the server with \`yarn dev\` (or\n` +
         `\`npm run dev\`) first, or set MULMOCLAUDE_AUTH_TOKEN to the\n` +
         `same value the server is using.\n`);
     return process.exit(1);
 }
 export function createBridgeClient(opts) {
-    const apiUrl = opts.apiUrl ?? process.env.MULMOCLAUDE_API_URL ?? DEFAULT_API_URL;
+    // Token BEFORE port. A restart rewrites both files and nothing marks them as
+    // one generation, so a bridge starting mid-restart can read a torn pair in
+    // either order. What the order decides is WHICH tear it gets. Port first
+    // yields a NEW token with an OLD port — a fresh credential sent to the port
+    // the server has just left, retried in silence because the socket's URL is
+    // fixed at construction. Token first mostly yields the opposite, an OLD token
+    // with a NEW port, which the right server answers `invalid token` and the
+    // connect handler explains; the dangerous pairing survives only in the narrow
+    // window where BOTH reads fall between the token write and the port publish.
+    // Closing it needs a shared generation marker on the sidecars (Codex, #3082).
     const token = requireBearerToken();
+    const apiUrl = resolveApiUrl(opts.apiUrl);
     // `opts.options === undefined` → scrape env automatically.
     // `opts.options === {}` → opt out of the scrape explicitly.
     const options = opts.options ?? readBridgeEnvOptions(opts.transportId, process.env);

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export { createBridgeClient, requireBearerToken, type MessageAck, type PushEvent, type BridgeClientOptions, type BridgeClient } from "./client.js";
-export { readBridgeToken, TOKEN_FILE_PATH } from "./token.js";
+export { readBridgeToken, tokenFilePath, TOKEN_FILE_PATH } from "./token.js";
+export { resolveApiUrl } from "./apiUrl.js";
 export { readBridgeEnvOptions } from "./options.js";
 export { chunkText } from "./text.js";
 export { frameText } from "./frame.js";

package/dist/index.js

@@ -1,6 +1,7 @@
 // @mulmobridge/client — shared socket.io client for all MulmoBridge bridges.
 export { createBridgeClient, requireBearerToken } from "./client.js";
-export { readBridgeToken, TOKEN_FILE_PATH } from "./token.js";
+export { readBridgeToken, tokenFilePath, TOKEN_FILE_PATH } from "./token.js";
+export { resolveApiUrl } from "./apiUrl.js";
 export { readBridgeEnvOptions } from "./options.js";
 export { chunkText } from "./text.js";
 export { frameText } from "./frame.js";

package/dist/token.d.ts

@@ -1,2 +1,15 @@
+/**
+ * Where the token file is, resolved NOW.
+ *
+ * Prefer this over `TOKEN_FILE_PATH` for anything that reads, writes, or
+ * reports the path: the constant freezes the workspace root at import time, so
+ * it disagrees with `readBridgeToken()` for any process that sets
+ * `MULMOCLAUDE_WORKSPACE_PATH` after importing this package (Codex, #3078).
+ */
+export declare function tokenFilePath(): string;
+/** Public since #272, so it stays. It now honours `MULMOCLAUDE_WORKSPACE_PATH`
+ *  (#3078) instead of hardcoding `<homedir>/mulmoclaude`, but it is a snapshot
+ *  taken at import time — use `tokenFilePath()` unless you specifically want
+ *  the value as it stood when the module loaded. */
 export declare const TOKEN_FILE_PATH: string;
 export declare function readBridgeToken(): string | null;

package/dist/token.js

@@ -4,26 +4,34 @@
 // Resolution order:
 //   1. `MULMOCLAUDE_AUTH_TOKEN` env var (useful for parallel shells,
 //      CI, or when the user runs the bridge against a different
-//      workspace than ~/mulmoclaude/)
-//   2. `<homedir>/mulmoclaude/.session-token` — the file the server
-//      writes at startup. Same path the Vite dev plugin reads from.
+//      workspace than the server's)
+//   2. `<workspace>/.session-token` — the file the server writes at
+//      startup. Same path the Vite dev plugin reads from, and the
+//      pair of `.server-port` (see `workspace.ts`).
 //
 // Returns null if neither source yields a non-empty string — the
 // caller decides how to react (exit with a helpful message, in the
 // bridge's case).
-import fs from "fs";
-import os from "os";
-import path from "path";
-export const TOKEN_FILE_PATH = path.join(os.homedir(), "mulmoclaude", ".session-token");
+import { readSidecarFile, SIDECAR_FILES, sidecarPath } from "./workspace.js";
+/**
+ * Where the token file is, resolved NOW.
+ *
+ * Prefer this over `TOKEN_FILE_PATH` for anything that reads, writes, or
+ * reports the path: the constant freezes the workspace root at import time, so
+ * it disagrees with `readBridgeToken()` for any process that sets
+ * `MULMOCLAUDE_WORKSPACE_PATH` after importing this package (Codex, #3078).
+ */
+export function tokenFilePath() {
+    return sidecarPath(SIDECAR_FILES.token);
+}
+/** Public since #272, so it stays. It now honours `MULMOCLAUDE_WORKSPACE_PATH`
+ *  (#3078) instead of hardcoding `<homedir>/mulmoclaude`, but it is a snapshot
+ *  taken at import time — use `tokenFilePath()` unless you specifically want
+ *  the value as it stood when the module loaded. */
+export const TOKEN_FILE_PATH = sidecarPath(SIDECAR_FILES.token);
 export function readBridgeToken() {
     const fromEnv = process.env.MULMOCLAUDE_AUTH_TOKEN;
     if (typeof fromEnv === "string" && fromEnv.length > 0)
         return fromEnv;
-    try {
-        const raw = fs.readFileSync(TOKEN_FILE_PATH, "utf-8").trim();
-        return raw.length > 0 ? raw : null;
-    }
-    catch {
-        return null;
-    }
+    return readSidecarFile(SIDECAR_FILES.token);
 }

package/dist/workspace.d.ts

@@ -0,0 +1,23 @@
+/** Sidecar files the server rewrites on every startup. */
+export declare const SIDECAR_FILES: {
+    readonly token: ".session-token";
+    readonly port: ".server-port";
+};
+/**
+ * The workspace root the server is using.
+ *
+ * Same rule as the server's own `workspacePath`
+ * (`server/workspace/paths.ts`): `MULMOCLAUDE_WORKSPACE_PATH` wins,
+ * otherwise `<homedir>/mulmoclaude`. The server's extra test-env
+ * branch is deliberately not mirrored — it isolates the server's own
+ * integration runs and means nothing to a bridge process.
+ */
+export declare function workspaceRoot(): string;
+/** Absolute path of one sidecar file inside the workspace. */
+export declare function sidecarPath(fileName: string): string;
+/**
+ * Sidecar contents, trimmed. `null` when the file is absent,
+ * unreadable, or holds nothing but whitespace — all of which mean the
+ * same thing to a caller: the server has not told us this yet.
+ */
+export declare function readSidecarFile(fileName: string): string | null;

package/dist/workspace.js

@@ -0,0 +1,54 @@
+// Where a bridge looks for the sidecar files the server writes on every
+// startup (#3078).
+//
+// The server publishes two files into its workspace root at boot:
+// `.session-token` (the bearer token the bridge presents) and
+// `.server-port` (the port it actually bound, which is NOT always the
+// one it was asked for — see `server/workspace/serverPort.ts`). They
+// are a PAIR, rewritten together on every restart, so both are
+// resolved from one root here rather than each growing its own idea of
+// where the workspace is. Reading only one of them is how the bridges
+// ended up following the token across restarts while still addressing
+// a hardcoded `localhost:3001`.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+const DEFAULT_WORKSPACE_DIR = "mulmoclaude";
+/** Sidecar files the server rewrites on every startup. */
+export const SIDECAR_FILES = {
+    token: ".session-token",
+    port: ".server-port",
+};
+/**
+ * The workspace root the server is using.
+ *
+ * Same rule as the server's own `workspacePath`
+ * (`server/workspace/paths.ts`): `MULMOCLAUDE_WORKSPACE_PATH` wins,
+ * otherwise `<homedir>/mulmoclaude`. The server's extra test-env
+ * branch is deliberately not mirrored — it isolates the server's own
+ * integration runs and means nothing to a bridge process.
+ */
+export function workspaceRoot() {
+    const configured = process.env.MULMOCLAUDE_WORKSPACE_PATH;
+    if (typeof configured === "string" && configured.length > 0)
+        return configured;
+    return path.join(os.homedir(), DEFAULT_WORKSPACE_DIR);
+}
+/** Absolute path of one sidecar file inside the workspace. */
+export function sidecarPath(fileName) {
+    return path.join(workspaceRoot(), fileName);
+}
+/**
+ * Sidecar contents, trimmed. `null` when the file is absent,
+ * unreadable, or holds nothing but whitespace — all of which mean the
+ * same thing to a caller: the server has not told us this yet.
+ */
+export function readSidecarFile(fileName) {
+    try {
+        const raw = fs.readFileSync(sidecarPath(fileName), "utf-8").trim();
+        return raw.length > 0 ? raw : null;
+    }
+    catch {
+        return null;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mulmobridge/client",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "Socket.io client library for MulmoBridge — shared by all bridge implementations",
   "type": "module",
   "main": "./dist/index.js",
@@ -46,11 +46,11 @@
   "author": "Receptron Team",
   "dependencies": {
     "@mulmobridge/protocol": "^1.0.1",
-    "@mulmoclaude/common": "^1.1.2",
+    "@mulmoclaude/common": "^1.2.0",
     "socket.io-client": "^4.0.0"
   },
   "devDependencies": {
-    "@types/node": "^26.1.2",
+    "@types/node": "^26.4.1",
     "typescript": "^6.0.3"
   },
   "homepage": "https://github.com/receptron/mulmoclaude/tree/main/packages/client#readme",