@mulmobridge/chat-service 0.1.0 → 0.1.1

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.js

@@ -11,7 +11,7 @@ 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;
         // Log attachment summary (count + mimeTypes) — NEVER log raw
@@ -42,6 +42,7 @@ export function createRelay(deps) {
             roleId: chatState.roleId,
             chatSessionId: chatState.sessionId,
             attachments,
+            origin: "bridge",
         });
         if (result.kind === "error") {
             const status = result.status ?? 500;
@@ -96,8 +97,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 +114,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.js

@@ -156,8 +156,7 @@ function validateHandshake(auth, tokenProvider) {
         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();
@@ -184,9 +183,7 @@ 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,8 @@ export interface StartChatParams {
     chatSessionId: string;
     selectedImageData?: string;
     attachments?: Attachment[];
+    /** Session origin — application-defined (e.g. "human", "bridge") */
+    origin?: string;
 }
 export type StartChatResult = {
     kind: "started";
@@ -35,6 +37,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 +65,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.1",
   "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.3"
   },
   "peerDependencies": {
     "express": "^5.0.0",