@mulmobridge/chat-service 0.1.1 → 0.1.2

package/dist/relay.d.ts

@@ -6,6 +6,12 @@ export interface RelayParams {
     externalChatId: string;
     text: string;
     attachments?: Attachment[];
+    /** Flat primitive bag captured at handshake time (string /
+     *  number / boolean values only — see socket.ts sanitiser).
+     *  Forwarded to the host app's startChat callback as
+     *  `bridgeOptions`. Empty when the bridge didn't send any.
+     *  See plans/feat-bridge-options-passthrough.md. */
+    bridgeOptions?: Readonly<Record<string, string | number | boolean>>;
     /** Called for each text chunk as the agent generates it. Used by
      *  the socket transport to stream text to the bridge in real time
      *  (Phase C of #268). */
@@ -30,3 +36,4 @@ export interface RelayDeps {
     logger: Logger;
 }
 export declare function createRelay(deps: RelayDeps): RelayFn;
+export declare function resolveDefaultRole(bridgeOptions: Readonly<Record<string, string | number | boolean>> | undefined, getRole: (roleId: string) => Role, fallbackRoleId: string, logger: Logger, transportId: string): string;

package/dist/relay.js

@@ -13,7 +13,7 @@ const REPLY_TIMEOUT_MS = 5 * 60 * 1000;
 export function createRelay(deps) {
     const { store, handleCommand, startChat, onSessionEvent, getRole, defaultRoleId, logger } = deps;
     return async function relayMessage(params) {
-        const { transportId, externalChatId, text, attachments } = params;
+        const { transportId, externalChatId, text, attachments, bridgeOptions } = params;
         // Log attachment summary (count + mimeTypes) — NEVER log raw
         // base64 data (performance, log size, information leak risk).
         const attachmentSummary = attachments
@@ -30,8 +30,13 @@ export function createRelay(deps) {
         });
         let chatState = await store.getChatState(transportId, externalChatId);
         if (!chatState) {
-            const defaultRole = getRole(defaultRoleId);
-            chatState = await store.resetChatState(transportId, externalChatId, defaultRole.id);
+            // Only on FIRST contact do we honour `bridgeOptions.defaultRole`
+            // — once the session exists, whatever role the user / command
+            // handler settled on is the source of truth. An unknown role
+            // id silently falls back to the host-app default (we log it so
+            // a typo in the bridge's env var is discoverable).
+            const resolved = resolveDefaultRole(bridgeOptions, getRole, defaultRoleId, logger, transportId);
+            chatState = await store.resetChatState(transportId, externalChatId, resolved);
         }
         const commandResult = await handleCommand(text, transportId, chatState);
         if (commandResult) {
@@ -43,6 +48,9 @@ export function createRelay(deps) {
             chatSessionId: chatState.sessionId,
             attachments,
             origin: "bridge",
+            // Host app may use other keys (e.g. a future `defaultModel`);
+            // we forward the whole bag untouched.
+            bridgeOptions,
         });
         if (result.kind === "error") {
             const status = result.status ?? 500;
@@ -90,6 +98,28 @@ export function createRelay(deps) {
     };
 }
 // ── Internals ────────────────────────────────────────────────
+// Resolve the role id to seed a NEW bridge chat state with. Prefers
+// `bridgeOptions.defaultRole` when the bridge sent one and it names
+// a role the host app actually has. Falls back to the host-app
+// default on absence / unknown id (with a warn log so an env-var
+// typo is traceable). Exported for direct unit testing.
+export function resolveDefaultRole(bridgeOptions, getRole, fallbackRoleId, logger, transportId) {
+    const requested = bridgeOptions?.defaultRole;
+    if (typeof requested !== "string" || requested.length === 0)
+        return fallbackRoleId;
+    // `getRole` on an unknown id silently returns the first built-in
+    // role — compare ids to catch that before we commit to it.
+    const resolved = getRole(requested);
+    if (resolved.id !== requested) {
+        logger.warn("chat-service", "bridge requested unknown default role; falling back", {
+            transportId,
+            requested,
+            fallback: fallbackRoleId,
+        });
+        return fallbackRoleId;
+    }
+    return resolved.id;
+}
 // Kept out of the factory closure so future packaging doesn't need
 // to re-capture anything; `onSessionEvent` arrives as a plain param.
 function collectAgentReply(onSessionEvent, chatSessionId, onChunk) {

package/dist/socket.d.ts

@@ -39,5 +39,8 @@ export interface ChatSocketHandle {
      *  joiner. */
     pushToBridge: PushFn;
 }
+type BridgeOptions = Readonly<Record<string, string | number | boolean>>;
 export declare function bridgeRoom(transportId: string): string;
 export declare function attachChatSocket(server: http.Server, deps: ChatSocketDeps): ChatSocketHandle;
+export declare function sanitiseOptions(raw: unknown): BridgeOptions;
+export {};

package/dist/socket.js

@@ -63,6 +63,9 @@ export function attachChatSocket(server, deps) {
             return;
         }
         socket.data.transportId = result.transportId;
+        // Stash options on the socket so every subsequent message from
+        // this bridge inherits the same config without re-sending it.
+        socket.data.bridgeOptions = result.options;
         next();
     });
     io.on("connection", (socket) => {
@@ -116,6 +119,10 @@ export function attachChatSocket(server, deps) {
                 externalChatId: parsed.externalChatId,
                 text: parsed.text,
                 attachments: parsed.attachments,
+                // Options captured at handshake time (see io.use). Empty
+                // object when the bridge didn't send any — the host app
+                // treats absence and empty identically.
+                bridgeOptions: socket.data.bridgeOptions ?? {},
                 // Stream text chunks to this bridge socket in real time
                 // (Phase C of #268). The ack still returns the full text
                 // for backward compatibility.
@@ -151,6 +158,36 @@ export function attachChatSocket(server, deps) {
     };
     return { io, pushToBridge };
 }
+// `options` on the handshake is reduced to a FLAT PRIMITIVE bag:
+// string / number / boolean only. This serves two purposes —
+//   1. Rejects nested objects / arrays / functions so a downstream
+//      merge in the host app can't reintroduce prototype-pollution
+//      via a deeply-nested `__proto__` (top-level `__proto__` is
+//      stripped separately as a belt-and-braces guard).
+//   2. Makes the wire contract explicit: every value the host sees
+//      is something you could put in an env var.
+// Anything else (objects, arrays, null, undefined, functions,
+// symbols, bigints) is dropped silently. The bridge author is
+// responsible for flattening complex config into primitives before
+// sending.
+export function sanitiseOptions(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return {};
+    const out = {};
+    for (const [key, value] of Object.entries(raw)) {
+        if (key === "__proto__" || key === "prototype" || key === "constructor")
+            continue;
+        if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+            // Drop non-finite numbers (NaN / Infinity) — they serialise
+            // oddly and the host app shouldn't be asked to distinguish
+            // "valid zero" from "broken input".
+            if (typeof value === "number" && !Number.isFinite(value))
+                continue;
+            out[key] = value;
+        }
+    }
+    return out;
+}
 function validateHandshake(auth, tokenProvider) {
     if (!auth || typeof auth !== "object") {
         return { ok: false, error: "handshake auth is required" };
@@ -160,8 +197,9 @@ function validateHandshake(auth, tokenProvider) {
         return { ok: false, error: "transportId is required" };
     }
     const transportId = transportIdRaw.trim();
+    const options = sanitiseOptions(auth.options);
     if (!tokenProvider) {
-        return { ok: true, transportId };
+        return { ok: true, transportId, options };
     }
     const expected = tokenProvider();
     if (expected === null || expected.length === 0) {
@@ -177,7 +215,7 @@ function validateHandshake(auth, tokenProvider) {
     if (provided !== expected) {
         return { ok: false, error: "invalid token" };
     }
-    return { ok: true, transportId };
+    return { ok: true, transportId, options };
 }
 function parseMessagePayload(payload) {
     if (!payload || typeof payload !== "object") {

package/dist/types.d.ts

@@ -25,6 +25,14 @@ export interface StartChatParams {
     attachments?: Attachment[];
     /** Session origin — application-defined (e.g. "human", "bridge") */
     origin?: string;
+    /** Flat primitive bag forwarded from the bridge handshake. Chat-
+     *  service sanitises to string / number / boolean values only
+     *  before this point — nested objects are dropped at the socket
+     *  boundary so a downstream merge can't reintroduce prototype-
+     *  pollution. The host app is free to look up its own keys
+     *  (e.g. `defaultRole`). Empty object when the bridge didn't
+     *  send any. */
+    bridgeOptions?: Readonly<Record<string, string | number | boolean>>;
 }
 export type StartChatResult = {
     kind: "started";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mulmobridge/chat-service",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Server-side chat service for MulmoBridge — socket.io + REST bridge to Claude Code agents",
   "type": "module",
   "main": "./dist/index.js",
@@ -27,7 +27,7 @@
   "license": "MIT",
   "author": "Receptron Team",
   "dependencies": {
-    "@mulmobridge/protocol": "^0.1.3"
+    "@mulmobridge/protocol": "^0.1.4"
   },
   "peerDependencies": {
     "express": "^5.0.0",