@mulmobridge/chat-service 0.1.0 → 0.1.2

package/dist/commands.d.ts

@@ -1,4 +1,4 @@
-import type { Role } from "./types.js";
+import type { Role, SessionSummary } from "./types.js";
 import type { ChatStateStore, TransportChatState } from "./chat-state.js";
 export interface CommandResult {
     reply: string;
@@ -9,4 +9,22 @@ export declare function createCommandHandler(opts: {
     loadAllRoles: () => Role[];
     getRole: (roleId: string) => Role;
     resetChatState: ChatStateStore["resetChatState"];
+    connectSession: ChatStateStore["connectSession"];
+    listSessions?: (opts: {
+        limit: number;
+        offset: number;
+    }) => Promise<{
+        sessions: SessionSummary[];
+        total: number;
+    }>;
+    getSessionHistory?: (sessionId: string, opts: {
+        limit: number;
+        offset: number;
+    }) => Promise<{
+        messages: Array<{
+            source: string;
+            text: string;
+        }>;
+        total: number;
+    }>;
 }): CommandHandler;

package/dist/commands.js

@@ -4,16 +4,59 @@
 // /status) for the transport chat bridge. Role lookups and state
 // reset arrive via the factory so this file has zero imports from
 // the host app — only sibling module types.
+// Mirror server/utils/time.ts names but declared locally since
+// the chat-service package must not import from the host app.
+const ONE_MINUTE_MS = 60_000;
+const ONE_HOUR_MS = 3_600_000;
+const ONE_DAY_MS = 86_400_000;
+function formatRelativeTime(isoDate) {
+    const diffMs = Date.now() - new Date(isoDate).getTime();
+    const minutes = Math.floor(diffMs / ONE_MINUTE_MS);
+    if (minutes < 1)
+        return "just now";
+    if (minutes < 60)
+        return `${minutes} min ago`;
+    const hours = Math.floor(diffMs / ONE_HOUR_MS);
+    if (hours < 24)
+        return `${hours}h ago`;
+    const days = Math.floor(diffMs / ONE_DAY_MS);
+    return `${days}d ago`;
+}
 // ── Factory ──────────────────────────────────────────────────
 export function createCommandHandler(opts) {
-    const { loadAllRoles, getRole, resetChatState } = opts;
-    const getRolesText = () => [
-        "Available roles:",
-        ...loadAllRoles().map((r) => `  ${r.id} — ${r.name}`),
-    ].join("\n");
+    const { loadAllRoles, getRole, resetChatState, connectSession, listSessions, getSessionHistory } = opts;
+    // Cache /sessions results per chat so /switch resolves to the correct list.
+    // Key: "transportId:externalChatId". Bounded with max entries + TTL.
+    // See docs/bridge-session-design.md for multi-user scaling plan.
+    const MAX_CACHE_ENTRIES = 1000;
+    const CACHE_TTL_MS = 5 * ONE_MINUTE_MS;
+    const sessionListCache = new Map();
+    const cacheKey = (transportId, externalChatId) => `${transportId}:${externalChatId}`;
+    function getCachedSessions(key) {
+        const entry = sessionListCache.get(key);
+        if (!entry)
+            return null;
+        if (Date.now() - entry.createdAt > CACHE_TTL_MS) {
+            sessionListCache.delete(key);
+            return null;
+        }
+        return entry.sessions;
+    }
+    function setCachedSessions(key, sessions) {
+        if (sessionListCache.size >= MAX_CACHE_ENTRIES) {
+            const oldest = sessionListCache.keys().next().value;
+            if (oldest !== undefined)
+                sessionListCache.delete(oldest);
+        }
+        sessionListCache.set(key, { sessions, createdAt: Date.now() });
+    }
+    const getRolesText = () => ["Available roles:", ...loadAllRoles().map((r) => `  ${r.id} — ${r.name}`)].join("\n");
     const getHelpText = () => [
         "Commands:",
         "  /reset  — Start a new session",
+        "  /sessions [page] — List recent sessions (e.g. /sessions 2)",
+        "  /switch <number|sessionId> — Switch to a session",
+        "  /history [page] — Show recent messages in current session",
         "  /help   — Show this help",
         "  /roles  — List available roles",
         "  /role <id> — Switch role",
@@ -45,13 +88,126 @@ export function createCommandHandler(opts) {
     const handleStatus = (chatState) => {
         const role = getRole(chatState.roleId);
         return {
-            reply: [
-                `Role: ${role.name} (${role.id})`,
-                `Session: ${chatState.sessionId}`,
-                `Last activity: ${chatState.updatedAt}`,
-            ].join("\n"),
+            reply: [`Role: ${role.name} (${role.id})`, `Session: ${chatState.sessionId}`, `Last activity: ${chatState.updatedAt}`].join("\n"),
         };
     };
+    const SESSIONS_PAGE_SIZE = 10;
+    const handleSessions = async (transportId, chatState, pageArg) => {
+        if (!listSessions) {
+            return { reply: "Session listing is not available." };
+        }
+        const page = Math.max(1, parseInt(pageArg ?? "1", 10) || 1);
+        const offset = (page - 1) * SESSIONS_PAGE_SIZE;
+        const { sessions, total } = await listSessions({
+            limit: SESSIONS_PAGE_SIZE,
+            offset,
+        });
+        if (sessions.length === 0 && total === 0) {
+            return { reply: "No sessions found." };
+        }
+        if (sessions.length === 0) {
+            return { reply: `No more sessions. Total: ${total}` };
+        }
+        // Cache full page for /switch (keyed by offset so numbers are absolute)
+        const key = cacheKey(transportId, chatState.externalChatId);
+        const existing = getCachedSessions(key) ?? [];
+        // Merge into cache at correct positions
+        const merged = [...existing];
+        sessions.forEach((s, i) => {
+            merged[offset + i] = s;
+        });
+        setCachedSessions(key, merged);
+        const totalPages = Math.ceil(total / SESSIONS_PAGE_SIZE);
+        const lines = sessions.map((s, i) => {
+            const num = offset + i + 1;
+            const preview = s.preview.length > 40 ? s.preview.slice(0, 40) + "..." : s.preview;
+            return `  ${num}. [${s.roleId}] ${preview || "(no title)"} — ${formatRelativeTime(s.updatedAt)}`;
+        });
+        const header = `Sessions (page ${page}/${totalPages}, total ${total}):`;
+        const parts = [header, ...lines];
+        if (page < totalPages) {
+            parts.push(`\n/sessions ${page + 1} for next page`);
+        }
+        parts.push("Use /switch <number> or /switch <sessionId> to connect.");
+        return { reply: parts.join("\n") };
+    };
+    const handleSwitch = async (transportId, chatState, arg) => {
+        if (!arg) {
+            return {
+                reply: "Usage: /switch <number|sessionId>\nRun /sessions first to see the list.",
+            };
+        }
+        const key = cacheKey(transportId, chatState.externalChatId);
+        const cached = getCachedSessions(key) ?? [];
+        let target;
+        if (/^\d+$/.test(arg)) {
+            // Numeric — index into cached list
+            const index = parseInt(arg, 10);
+            if (index < 1 || index > cached.length) {
+                return {
+                    reply: cached.length > 0 ? `Invalid number. Pick 1-${cached.length} from the /sessions list.` : "Run /sessions first to see available sessions.",
+                };
+            }
+            target = cached[index - 1];
+            // Guard against sparse cache (user loaded page 2 but not page 1)
+            if (!target) {
+                const page = Math.ceil(index / SESSIONS_PAGE_SIZE);
+                return {
+                    reply: `Run /sessions ${page} first to load that page.`,
+                };
+            }
+        }
+        else {
+            // Non-numeric — treat as session ID
+            target = cached.find((s) => s.id === arg);
+            if (!target) {
+                return {
+                    reply: `Session "${arg}" not found. Run /sessions to see available sessions.`,
+                };
+            }
+        }
+        const updated = await connectSession(transportId, chatState.externalChatId, target.id);
+        if (!updated) {
+            return { reply: "Failed to switch session." };
+        }
+        const role = getRole(target.roleId);
+        const preview = target.preview || "(no title)";
+        return {
+            reply: `Connected to "${preview}" (${role.name}). Send a message to continue.`,
+            nextState: updated,
+        };
+    };
+    const HISTORY_PAGE_SIZE = 5;
+    const MAX_MESSAGE_LENGTH = 200;
+    const handleHistory = async (chatState, pageArg) => {
+        if (!getSessionHistory) {
+            return { reply: "History is not available." };
+        }
+        const page = Math.max(1, parseInt(pageArg ?? "1", 10) || 1);
+        const offset = (page - 1) * HISTORY_PAGE_SIZE;
+        const { messages, total } = await getSessionHistory(chatState.sessionId, {
+            limit: HISTORY_PAGE_SIZE,
+            offset,
+        });
+        if (messages.length === 0 && total === 0) {
+            return { reply: "No messages in this session." };
+        }
+        if (messages.length === 0) {
+            return { reply: `No more messages. Total: ${total}` };
+        }
+        const totalPages = Math.ceil(total / HISTORY_PAGE_SIZE);
+        const lines = messages.map((m) => {
+            const label = m.source === "user" ? "You" : "AI";
+            const text = m.text.length > MAX_MESSAGE_LENGTH ? m.text.slice(0, MAX_MESSAGE_LENGTH) + "..." : m.text;
+            return `[${label}] ${text}`;
+        });
+        const header = `History (page ${page}/${totalPages}):`;
+        const parts = [header, "", ...lines];
+        if (page < totalPages) {
+            parts.push(`\n/history ${page + 1} for older messages`);
+        }
+        return { reply: parts.join("\n\n") };
+    };
     const handleCommand = async (text, transportId, chatState) => {
         if (!text.startsWith("/"))
             return null;
@@ -59,6 +215,12 @@ export function createCommandHandler(opts) {
         switch (command) {
             case "/reset":
                 return handleReset(transportId, chatState);
+            case "/sessions":
+                return handleSessions(transportId, chatState, args[0]);
+            case "/switch":
+                return handleSwitch(transportId, chatState, args[0]);
+            case "/history":
+                return handleHistory(chatState, args[0]);
             case "/help":
                 return { reply: getHelpText() };
             case "/roles":

package/dist/index.d.ts

@@ -16,5 +16,5 @@ export interface ChatService {
     pushToBridge: PushFn;
 }
 export declare function createChatService(deps: ChatServiceDeps): ChatService;
-export type { ChatServiceDeps, StartChatFn, OnSessionEventFn, } from "./types.js";
+export type { ChatServiceDeps, StartChatFn, OnSessionEventFn } from "./types.js";
 export { writeFileAtomic } from "./atomic-write.js";

package/dist/index.js

@@ -29,7 +29,7 @@ const badRequest = (res, error) => res.status(400).json({ error });
 const notFound = (res, error) => res.status(404).json({ error });
 // ── Factory ──────────────────────────────────────────────────
 export function createChatService(deps) {
-    const { startChat, onSessionEvent, loadAllRoles, getRole, defaultRoleId, tokenProvider, } = deps;
+    const { startChat, onSessionEvent, loadAllRoles, getRole, defaultRoleId, tokenProvider } = deps;
     const logger = deps.logger;
     const store = createChatStateStore({
         transportsDir: deps.transportsDir,
@@ -39,6 +39,9 @@ export function createChatService(deps) {
         loadAllRoles,
         getRole,
         resetChatState: store.resetChatState,
+        connectSession: store.connectSession,
+        listSessions: deps.listSessions,
+        getSessionHistory: deps.getSessionHistory,
     });
     const relay = createRelay({
         store,
@@ -88,9 +91,7 @@ export function createChatService(deps) {
     // reassign the active session pointer for a transport chat.
     router.post(CHAT_SERVICE_ROUTES.connect, async (req, res) => {
         const { transportId, externalChatId } = req.params;
-        const chatSessionId = typeof req.body?.chatSessionId === "string"
-            ? req.body.chatSessionId.trim()
-            : "";
+        const chatSessionId = typeof req.body?.chatSessionId === "string" ? req.body.chatSessionId.trim() : "";
         if (!chatSessionId) {
             badRequest(res, "chatSessionId is required");
             return;

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

@@ -11,9 +11,9 @@ import { EVENT_TYPES } from "@mulmobridge/protocol";
 const REPLY_TIMEOUT_MS = 5 * 60 * 1000;
 // ── Factory ──────────────────────────────────────────────────
 export function createRelay(deps) {
-    const { store, handleCommand, startChat, onSessionEvent, getRole, defaultRoleId, logger, } = 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) {
@@ -42,6 +47,10 @@ export function createRelay(deps) {
             roleId: chatState.roleId,
             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;
@@ -89,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) {
@@ -96,8 +127,7 @@ function collectAgentReply(onSessionEvent, chatSessionId, onChunk) {
         const textChunks = [];
         const timer = setTimeout(() => {
             unsubscribe();
-            resolve(textChunks.join("") ||
-                "The request timed out before a reply was generated.");
+            resolve(textChunks.join("") || "The request timed out before a reply was generated.");
         }, REPLY_TIMEOUT_MS);
         const unsubscribe = onSessionEvent(chatSessionId, (event) => {
             const type = event.type;
@@ -114,8 +144,7 @@ function collectAgentReply(onSessionEvent, chatSessionId, onChunk) {
             if (type === EVENT_TYPES.sessionFinished) {
                 clearTimeout(timer);
                 unsubscribe();
-                resolve(textChunks.join("") ||
-                    "The assistant completed the request but produced no text reply.");
+                resolve(textChunks.join("") || "The assistant completed the request but produced no text reply.");
             }
         });
     });

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,18 +158,48 @@ 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" };
     }
     const transportIdRaw = auth.transportId;
-    if (typeof transportIdRaw !== "string" ||
-        transportIdRaw.trim().length === 0) {
+    if (typeof transportIdRaw !== "string" || transportIdRaw.trim().length === 0) {
         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) {
@@ -178,15 +215,13 @@ 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") {
         return { ok: false, error: "payload must be an object" };
     }
-    const externalChatId = typeof payload.externalChatId === "string"
-        ? payload.externalChatId.trim()
-        : "";
+    const externalChatId = typeof payload.externalChatId === "string" ? payload.externalChatId.trim() : "";
     const text = typeof payload.text === "string" ? payload.text.trim() : "";
     if (!externalChatId) {
         return { ok: false, error: "externalChatId is required" };

package/dist/types.d.ts

@@ -23,6 +23,16 @@ export interface StartChatParams {
     chatSessionId: string;
     selectedImageData?: string;
     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";
@@ -35,6 +45,13 @@ export type StartChatResult = {
 export type StartChatFn = (params: StartChatParams) => Promise<StartChatResult>;
 export type SessionEventListener = (event: Record<string, unknown>) => void;
 export type OnSessionEventFn = (sessionId: string, listener: SessionEventListener) => () => void;
+/** Summary of a chat session — returned by listSessions. */
+export interface SessionSummary {
+    id: string;
+    roleId: string;
+    preview: string;
+    updatedAt: string;
+}
 export interface ChatServiceDeps {
     /** Relay a user turn into the agent loop. */
     startChat: StartChatFn;
@@ -56,4 +73,30 @@ export interface ChatServiceDeps {
      * `attachChatSocket` in ./socket.ts.
      */
     tokenProvider?: () => string | null;
+    /**
+     * List recent sessions from the server. Used by /sessions command.
+     * Omit if session listing is not available (command will reply
+     * "not available").
+     */
+    listSessions?: (opts: {
+        limit: number;
+        offset: number;
+    }) => Promise<{
+        sessions: SessionSummary[];
+        total: number;
+    }>;
+    /**
+     * Get recent messages from a session. Used by /history command.
+     * Returns newest-first array of {source, text} pairs.
+     */
+    getSessionHistory?: (sessionId: string, opts: {
+        limit: number;
+        offset: number;
+    }) => Promise<{
+        messages: Array<{
+            source: string;
+            text: string;
+        }>;
+        total: number;
+    }>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mulmobridge/chat-service",
-  "version": "0.1.0",
+  "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.0"
+    "@mulmobridge/protocol": "^0.1.4"
   },
   "peerDependencies": {
     "express": "^5.0.0",