@mulmobridge/protocol 1.0.0 → 1.1.0

package/README.md

@@ -98,6 +98,13 @@ Part of the [`@mulmobridge/*`](https://www.npmjs.com/~mulmobridge) package famil
 - [`@mulmobridge/xmpp`](https://www.npmjs.com/package/@mulmobridge/xmpp) — XMPP / Jabber
 - [`@mulmobridge/zulip`](https://www.npmjs.com/package/@mulmobridge/zulip) — Zulip
 
+## Related projects
+
+Published from the MulmoClaude monorepo by [Receptron](https://github.com/receptron).
+
+- **[MulmoClaude](https://github.com/receptron/mulmoclaude)** — an open-source AI assistant platform that runs on your own computer. Claude Code as the engine, a personal wiki for long-term memory, schema-driven collections for your data, and chat that summons the right GUI (markdown, charts, forms, spreadsheets, wikis) for each task.
+- **[MulmoTerminal](https://github.com/receptron/mulmoterminal)** — a terminal-first cockpit for running many AI coding agents in parallel. One roster showing every session's summary and PR status, tmux-backed session persistence, git-worktree isolation, one-click PRs, and mobile push with remote reply.
+- **[MulmoTerminal manual](https://receptron.github.io/mulmoterminal/)** — setup, workflows, feature reference, configuration, mobile notifications, and alternative / local model providers. Available in English and Japanese.
 
 ## License
 

package/dist/index.d.ts

@@ -2,3 +2,4 @@ export { EVENT_TYPES, type EventType, GENERATION_KINDS, type GenerationKind, typ
 export { CHAT_SOCKET_PATH, CHAT_SOCKET_EVENTS, type ChatSocketEvent, type BridgeHandshakeAuth, type BridgeOptions } from "./socket.js";
 export { type Attachment } from "./attachment.js";
 export { CHAT_SERVICE_ROUTES } from "./routes.js";
+export { DEFAULT_REPLY_TIMEOUT_MS, ACK_TIMEOUT_MARGIN_MS, MAX_REPLY_TIMEOUT_MS, type ReplyTimeoutResolution, resolveReplyTimeoutMs, ackTimeoutMsFor, } from "./replyTimeout.js";

package/dist/index.js

@@ -5,7 +5,8 @@
 //   - The chat-service (server-side socket.io + REST)
 //   - External bridges (CLI, Telegram, future platforms)
 //
-// No runtime dependencies. Types + const-only.
+// No runtime dependencies. Types, constants, and small pure helpers.
 export { EVENT_TYPES, GENERATION_KINDS, generationKey } from "./events.js";
 export { CHAT_SOCKET_PATH, CHAT_SOCKET_EVENTS } from "./socket.js";
 export { CHAT_SERVICE_ROUTES } from "./routes.js";
+export { DEFAULT_REPLY_TIMEOUT_MS, ACK_TIMEOUT_MARGIN_MS, MAX_REPLY_TIMEOUT_MS, resolveReplyTimeoutMs, ackTimeoutMsFor, } from "./replyTimeout.js";

package/dist/replyTimeout.d.ts

@@ -0,0 +1,19 @@
+export declare const DEFAULT_REPLY_TIMEOUT_MS: number;
+/** How much longer the bridge waits for the ack than the server waits for the reply. */
+export declare const ACK_TIMEOUT_MARGIN_MS: number;
+export declare const MAX_REPLY_TIMEOUT_MS: number;
+export interface ReplyTimeoutResolution {
+    replyTimeoutMs: number;
+    /** Set when the configured value was unusable and something else was used. */
+    warning?: string;
+}
+/**
+ * Turn `bridgeOptions.replyTimeoutMs` into the limit to use.
+ *
+ * Absent or empty means the default with no warning. Anything that is not a
+ * positive whole number of milliseconds falls back to the default, and a value
+ * past the timer ceiling is clamped — both with a warning naming the value.
+ */
+export declare function resolveReplyTimeoutMs(raw: unknown): ReplyTimeoutResolution;
+/** The bridge client's ack limit for a given reply limit. */
+export declare function ackTimeoutMsFor(replyTimeoutMs: number): number;

package/dist/replyTimeout.js

@@ -0,0 +1,58 @@
+// How long a relayed turn may take, shared by both ends of the wire.
+//
+// The chat-service stops collecting the agent's reply after the reply
+// timeout; the bridge client stops waiting for the ack a margin later. The
+// margin is the whole contract: if the client gave up first, the server's
+// partial reply would arrive at a socket that had already reported a timeout.
+// Both ends read the SAME `bridgeOptions.replyTimeoutMs`, so the order holds
+// whatever the user sets.
+const ONE_MINUTE_MS = 60 * 1000;
+export const DEFAULT_REPLY_TIMEOUT_MS = 5 * ONE_MINUTE_MS;
+/** How much longer the bridge waits for the ack than the server waits for the reply. */
+export const ACK_TIMEOUT_MARGIN_MS = ONE_MINUTE_MS;
+// Node fires a timer longer than 2^31-1 ms after 1 ms instead, which would turn
+// "wait longer" into "give up at once". The client adds the margin, so the
+// reply limit stops short of the ceiling by exactly that much.
+const SET_TIMEOUT_CEILING_MS = 2 ** 31 - 1;
+export const MAX_REPLY_TIMEOUT_MS = SET_TIMEOUT_CEILING_MS - ACK_TIMEOUT_MARGIN_MS;
+const POSITIVE_INTEGER = /^[1-9]\d*$/;
+function parseConfigured(raw) {
+    // Not `isSafeInteger`: a huge integer is still a request for "as long as possible", and the caller clamps it.
+    if (typeof raw === "number")
+        return Number.isInteger(raw) && raw > 0 ? raw : null;
+    return POSITIVE_INTEGER.test(raw) ? Number(raw) : null;
+}
+/** For the warning only. `JSON.stringify` throws on a bigint or a circular object. */
+function describeRaw(raw) {
+    if (typeof raw === "string")
+        return JSON.stringify(raw);
+    if (typeof raw === "number" || typeof raw === "boolean" || typeof raw === "bigint")
+        return String(raw);
+    return `<${Array.isArray(raw) ? "array" : typeof raw}>`;
+}
+/**
+ * Turn `bridgeOptions.replyTimeoutMs` into the limit to use.
+ *
+ * Absent or empty means the default with no warning. Anything that is not a
+ * positive whole number of milliseconds falls back to the default, and a value
+ * past the timer ceiling is clamped — both with a warning naming the value.
+ */
+export function resolveReplyTimeoutMs(raw) {
+    if (raw === undefined || raw === null || raw === "")
+        return { replyTimeoutMs: DEFAULT_REPLY_TIMEOUT_MS };
+    const configured = typeof raw === "string" || typeof raw === "number" ? parseConfigured(raw) : null;
+    if (configured === null) {
+        return {
+            replyTimeoutMs: DEFAULT_REPLY_TIMEOUT_MS,
+            warning: `replyTimeoutMs=${describeRaw(raw)} is not a positive whole number of milliseconds; using ${DEFAULT_REPLY_TIMEOUT_MS}`,
+        };
+    }
+    if (configured > MAX_REPLY_TIMEOUT_MS) {
+        return { replyTimeoutMs: MAX_REPLY_TIMEOUT_MS, warning: `replyTimeoutMs=${configured} exceeds the maximum; using ${MAX_REPLY_TIMEOUT_MS}` };
+    }
+    return { replyTimeoutMs: configured };
+}
+/** The bridge client's ack limit for a given reply limit. */
+export function ackTimeoutMsFor(replyTimeoutMs) {
+    return replyTimeoutMs + ACK_TIMEOUT_MARGIN_MS;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mulmobridge/protocol",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Shared types and constants for the MulmoBridge protocol",
   "type": "module",
   "main": "./dist/index.js",
@@ -20,7 +20,7 @@
   "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"
   },
@@ -28,5 +28,22 @@
   "author": "Receptron Team",
   "devDependencies": {
     "typescript": "^6.0.3"
+  },
+  "homepage": "https://github.com/receptron/mulmoclaude/tree/main/packages/protocol#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/receptron/mulmoclaude.git",
+    "directory": "packages/protocol"
+  },
+  "keywords": [
+    "mulmobridge",
+    "protocol",
+    "socket.io",
+    "chat",
+    "ai-agent",
+    "types"
+  ],
+  "bugs": {
+    "url": "https://github.com/receptron/mulmoclaude/issues"
   }
 }