@mulmobridge/chat-service 0.1.0

package/README.md

@@ -0,0 +1,78 @@
+# @mulmobridge/chat-service
+
+Server-side chat service for [MulmoBridge](https://github.com/receptron/mulmoclaude) — provides socket.io + REST endpoints that connect external bridges (CLI, Telegram, etc.) to a Claude Code agent.
+
+## Install
+
+```bash
+npm install @mulmobridge/chat-service express socket.io
+```
+
+> `express` and `socket.io` are peer dependencies.
+
+## Overview
+
+The chat-service is a **DI-pure factory** — all host-app concerns (agent runner, session events, role lookup, file persistence, logger) are injected via `ChatServiceDeps`. No direct imports from the host application.
+
+```typescript
+import { createChatService } from "@mulmobridge/chat-service";
+
+const chatService = createChatService({
+  startChat,        // your agent entry point
+  onSessionEvent,   // session event subscriber
+  loadAllRoles,     // role list provider
+  getRole,          // single role lookup
+  defaultRoleId,    // fallback role
+  transportsDir,    // directory for transport state files
+  logger,           // structured logger ({ error, warn, info, debug })
+  tokenProvider,    // optional: bearer token for socket.io auth
+});
+
+// Mount the Express router
+app.use(chatService.router);
+
+// Attach socket.io to the HTTP server
+chatService.attachSocket(httpServer);
+```
+
+## Architecture
+
+```text
+┌─────────────┐     socket.io      ┌──────────────────┐
+│ CLI bridge   │ ◄──────────────► │  chat-service     │
+│ TG bridge    │    /ws/chat       │  (this package)   │
+│ ...          │                   │                   │
+└─────────────┘     REST           │  ┌─────────────┐ │
+                  /api/transports  │  │ relay.ts     │ │ ──► startChat()
+                                   │  │ socket.ts    │ │ ──► onSessionEvent()
+                                   │  │ chat-state   │ │ ──► file persistence
+                                   │  │ commands.ts  │ │ ──► /reset, /role
+                                   │  │ push-queue   │ │ ──► server→bridge push
+                                   │  └─────────────┘ │
+                                   └──────────────────┘
+```
+
+## Exports
+
+| Export | Description |
+|---|---|
+| `createChatService(deps)` | Factory — returns `{ router, attachSocket, pushToBridge }` |
+| `createRelay(deps)` | Core relay logic (HTTP + socket.io both call this) |
+| `CHAT_SOCKET_EVENTS` | Re-exported from `@mulmobridge/protocol` |
+| `ChatServiceDeps` | Dependency injection interface |
+| `StartChatFn` / `StartChatParams` / `StartChatResult` | Agent entry point types |
+| `Attachment` | File attachment interface |
+
+## Part of the MulmoBridge ecosystem
+
+| Package | Description |
+|---|---|
+| [@mulmobridge/protocol](https://www.npmjs.com/package/@mulmobridge/protocol) | Wire protocol types and constants |
+| **@mulmobridge/chat-service** | Server-side chat service (this package) |
+| [@mulmobridge/client](https://www.npmjs.com/package/@mulmobridge/client) | Bridge client library |
+| [@mulmobridge/cli](https://www.npmjs.com/package/@mulmobridge/cli) | CLI bridge |
+| [@mulmobridge/telegram](https://www.npmjs.com/package/@mulmobridge/telegram) | Telegram bridge |
+
+## License
+
+MIT — [Receptron Team](https://github.com/receptron)

package/dist/atomic-write.d.ts

@@ -0,0 +1 @@
+export declare function writeFileAtomic(filePath: string, content: string): Promise<void>;

package/dist/atomic-write.js

@@ -0,0 +1,21 @@
+// Lightweight atomic write — write to a sibling tmp file, then rename.
+//
+// Inlined in this package (not imported from the host app) so
+// @mulmobridge/chat-service stays dependency-free beyond protocol.
+// Same contract as the host's writeFileAtomic: readers always see
+// either the old file or the new file — never a half-written one.
+import { writeFile, rename, unlink, mkdir } from "fs/promises";
+import path from "path";
+import { randomUUID } from "crypto";
+export async function writeFileAtomic(filePath, content) {
+    const tmp = `${filePath}.${randomUUID()}.tmp`;
+    await mkdir(path.dirname(filePath), { recursive: true });
+    try {
+        await writeFile(tmp, content, "utf-8");
+        await rename(tmp, filePath);
+    }
+    catch (err) {
+        await unlink(tmp).catch(() => { });
+        throw err;
+    }
+}

package/dist/chat-state.d.ts

@@ -0,0 +1,20 @@
+import type { Logger } from "./types.js";
+export interface TransportChatState {
+    externalChatId: string;
+    sessionId: string;
+    roleId: string;
+    claudeSessionId?: string;
+    startedAt: string;
+    updatedAt: string;
+}
+export interface ChatStateStore {
+    getChatState(transportId: string, externalChatId: string): Promise<TransportChatState | null>;
+    setChatState(transportId: string, state: TransportChatState): Promise<void>;
+    resetChatState(transportId: string, externalChatId: string, roleId: string): Promise<TransportChatState>;
+    connectSession(transportId: string, externalChatId: string, chatSessionId: string): Promise<TransportChatState | null>;
+    generateSessionId(transportId: string, externalChatId: string): string;
+}
+export declare function createChatStateStore(opts: {
+    transportsDir: string;
+    logger: Logger;
+}): ChatStateStore;

package/dist/chat-state.js

@@ -0,0 +1,84 @@
+// @package-contract — see ./types.ts
+//
+// Persists per-transport chat state (which session a given
+// external chat id currently points at, which role, timestamps).
+// Kept DI-pure so the module can be extracted as a standalone npm
+// package: the transports directory path and logger arrive via the
+// factory, never through a direct `../workspace-paths.js` import.
+import { mkdir, readFile } from "fs/promises";
+import path from "path";
+import { writeFileAtomic } from "./atomic-write.js";
+// ── Path / id helpers ────────────────────────────────────────
+// Allow alphanumeric, hyphen, underscore, dot. Rejects empty
+// strings and anything >200 chars so we never let a transport id
+// escape the transports directory via path traversal.
+function isSafeId(id) {
+    return /^[\w.-]+$/.test(id) && id.length > 0 && id.length <= 200;
+}
+// ── Factory ──────────────────────────────────────────────────
+export function createChatStateStore(opts) {
+    const { transportsDir, logger } = opts;
+    const transportDir = (transportId) => path.join(transportsDir, transportId, "chats");
+    const statePath = (transportId, externalChatId) => path.join(transportDir(transportId), `${externalChatId}.json`);
+    const generateSessionId = (transportId, externalChatId) => `${transportId}-${externalChatId}-${Date.now()}`;
+    const getChatState = async (transportId, externalChatId) => {
+        if (!isSafeId(transportId) || !isSafeId(externalChatId))
+            return null;
+        try {
+            const raw = await readFile(statePath(transportId, externalChatId), "utf-8");
+            const parsed = JSON.parse(raw);
+            return parsed;
+        }
+        catch {
+            return null;
+        }
+    };
+    const setChatState = async (transportId, state) => {
+        if (!isSafeId(transportId) || !isSafeId(state.externalChatId)) {
+            throw new Error("Invalid transport or chat ID");
+        }
+        await mkdir(transportDir(transportId), { recursive: true });
+        await writeFileAtomic(statePath(transportId, state.externalChatId), JSON.stringify(state, null, 2));
+    };
+    const resetChatState = async (transportId, externalChatId, roleId) => {
+        const now = new Date().toISOString();
+        const state = {
+            externalChatId,
+            sessionId: generateSessionId(transportId, externalChatId),
+            roleId,
+            startedAt: now,
+            updatedAt: now,
+        };
+        await setChatState(transportId, state);
+        logger.info("chat-state", "reset", {
+            transportId,
+            externalChatId,
+            sessionId: state.sessionId,
+        });
+        return state;
+    };
+    const connectSession = async (transportId, externalChatId, chatSessionId) => {
+        const existing = await getChatState(transportId, externalChatId);
+        if (!existing)
+            return null;
+        const updated = {
+            ...existing,
+            sessionId: chatSessionId,
+            updatedAt: new Date().toISOString(),
+        };
+        await setChatState(transportId, updated);
+        logger.info("chat-state", "connected", {
+            transportId,
+            externalChatId,
+            sessionId: chatSessionId,
+        });
+        return updated;
+    };
+    return {
+        getChatState,
+        setChatState,
+        resetChatState,
+        connectSession,
+        generateSessionId,
+    };
+}

package/dist/commands.d.ts

@@ -0,0 +1,12 @@
+import type { Role } from "./types.js";
+import type { ChatStateStore, TransportChatState } from "./chat-state.js";
+export interface CommandResult {
+    reply: string;
+    nextState?: TransportChatState;
+}
+export type CommandHandler = (text: string, transportId: string, chatState: TransportChatState) => Promise<CommandResult | null>;
+export declare function createCommandHandler(opts: {
+    loadAllRoles: () => Role[];
+    getRole: (roleId: string) => Role;
+    resetChatState: ChatStateStore["resetChatState"];
+}): CommandHandler;

package/dist/commands.js

@@ -0,0 +1,75 @@
+// @package-contract — see ./types.ts
+//
+// Parses and executes slash commands (/reset, /help, /roles, /role,
+// /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.
+// ── Factory ──────────────────────────────────────────────────
+export function createCommandHandler(opts) {
+    const { loadAllRoles, getRole, resetChatState } = opts;
+    const getRolesText = () => [
+        "Available roles:",
+        ...loadAllRoles().map((r) => `  ${r.id} — ${r.name}`),
+    ].join("\n");
+    const getHelpText = () => [
+        "Commands:",
+        "  /reset  — Start a new session",
+        "  /help   — Show this help",
+        "  /roles  — List available roles",
+        "  /role <id> — Switch role",
+        "  /status — Show current session info",
+        "",
+        "Send any other text to chat with the assistant.",
+    ].join("\n");
+    const handleReset = async (transportId, chatState) => {
+        const nextState = await resetChatState(transportId, chatState.externalChatId, chatState.roleId);
+        return {
+            reply: `Session reset. Role: ${nextState.roleId}`,
+            nextState,
+        };
+    };
+    const handleRole = async (transportId, chatState, requestedRoleId) => {
+        if (!requestedRoleId) {
+            return { reply: `Usage: /role <id>\n\n${getRolesText()}` };
+        }
+        const role = loadAllRoles().find((r) => r.id === requestedRoleId);
+        if (!role) {
+            return { reply: `Unknown role: ${requestedRoleId}\n\n${getRolesText()}` };
+        }
+        const nextState = await resetChatState(transportId, chatState.externalChatId, role.id);
+        return {
+            reply: `Switched to ${role.name} (${role.id}). New session started.`,
+            nextState,
+        };
+    };
+    const handleStatus = (chatState) => {
+        const role = getRole(chatState.roleId);
+        return {
+            reply: [
+                `Role: ${role.name} (${role.id})`,
+                `Session: ${chatState.sessionId}`,
+                `Last activity: ${chatState.updatedAt}`,
+            ].join("\n"),
+        };
+    };
+    const handleCommand = async (text, transportId, chatState) => {
+        if (!text.startsWith("/"))
+            return null;
+        const [command, ...args] = text.split(/\s+/);
+        switch (command) {
+            case "/reset":
+                return handleReset(transportId, chatState);
+            case "/help":
+                return { reply: getHelpText() };
+            case "/roles":
+                return { reply: getRolesText() };
+            case "/role":
+                return handleRole(transportId, chatState, args[0]);
+            case "/status":
+                return handleStatus(chatState);
+            default:
+                return { reply: `Unknown command: ${command}\n\n${getHelpText()}` };
+        }
+    };
+    return handleCommand;
+}

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+import type http from "http";
+import { Router } from "express";
+import type { RelayFn } from "./relay.js";
+import type { PushFn } from "./socket.js";
+import type { ChatServiceDeps } from "./types.js";
+export interface ChatService {
+    router: Router;
+    /** Relay used by the HTTP router. Exposed so alternate transports
+     *  or tests can share the same flow without going through HTTP. */
+    relay: RelayFn;
+    /** Mount the socket.io transport at `/ws/chat` on the host HTTP server. */
+    attachSocket(httpServer: http.Server): void;
+    /** Server → bridge async push (Phase B of #268). Safe to call
+     *  before `attachSocket`: the message is queued and flushes on
+     *  the next bridge connection for that transport. */
+    pushToBridge: PushFn;
+}
+export declare function createChatService(deps: ChatServiceDeps): ChatService;
+export type { ChatServiceDeps, StartChatFn, OnSessionEventFn, } from "./types.js";
+export { writeFileAtomic } from "./atomic-write.js";

package/dist/index.js

@@ -0,0 +1,120 @@
+// @package-contract — see ./types.ts
+//
+// Factory for the transport chat bridge. `createChatService(deps)`
+// returns:
+//   - an Express `Router` for the legacy HTTP transport
+//   - an `attachSocket(httpServer)` helper that mounts the socket.io
+//     transport at `/ws/chat` (Phase A of #268)
+//   - the shared `relay` function both transports dispatch through
+//   - `pushToBridge(transportId, chatId, message)` for server→bridge
+//     async push (Phase B of #268). Before `attachSocket` is called
+//     pushes go straight to the in-memory queue; once a bridge is
+//     connected they emit live and the queue drains on join.
+//
+// All host-app dependencies arrive via `deps`; the module has no
+// direct imports from `../routes/…`, `../roles.js`,
+// `../session-store/…`, or `../logger/…` so it can be lifted into a
+// standalone npm package without internal edits. See #269 / #305.
+import { Router } from "express";
+import { CHAT_SERVICE_ROUTES } from "@mulmobridge/protocol";
+import { createChatStateStore } from "./chat-state.js";
+import { createCommandHandler } from "./commands.js";
+import { createRelay } from "./relay.js";
+import { createPushQueue } from "./push-queue.js";
+import { attachChatSocket } from "./socket.js";
+// Inlined (not imported from `../utils/httpError.js`) so the module
+// has no outbound dependency on the host app's utility modules.
+// See `@package-contract` in ./types.ts.
+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 logger = deps.logger;
+    const store = createChatStateStore({
+        transportsDir: deps.transportsDir,
+        logger,
+    });
+    const handleCommand = createCommandHandler({
+        loadAllRoles,
+        getRole,
+        resetChatState: store.resetChatState,
+    });
+    const relay = createRelay({
+        store,
+        handleCommand,
+        startChat,
+        onSessionEvent,
+        getRole,
+        defaultRoleId,
+        logger,
+    });
+    const queue = createPushQueue();
+    // Until `attachSocket` runs, `livePush` is null and pushes go
+    // straight to the queue. After attach, this reference flips to
+    // the real emitter so live bridges get the message immediately.
+    // The queue is shared with the socket layer so any pushes
+    // enqueued during the pre-attach window flush on first connect.
+    let livePush = null;
+    const pushToBridge = (transportId, chatId, message) => {
+        if (livePush) {
+            livePush(transportId, chatId, message);
+            return;
+        }
+        queue.enqueue(transportId, { chatId, message, enqueuedAt: Date.now() });
+        logger.info("chat-service", "push queued (socket not attached yet)", {
+            transportId,
+            chatId,
+            queueSize: queue.sizeFor(transportId),
+        });
+    };
+    const router = Router();
+    // POST /api/transports/:transportId/chats/:externalChatId — send text, get a reply.
+    router.post(CHAT_SERVICE_ROUTES.message, async (req, res) => {
+        const { transportId, externalChatId } = req.params;
+        const text = typeof req.body?.text === "string" ? req.body.text.trim() : "";
+        if (!text) {
+            badRequest(res, "text is required");
+            return;
+        }
+        const result = await relay({ transportId, externalChatId, text });
+        if (result.kind === "ok") {
+            res.json({ reply: result.reply });
+            return;
+        }
+        res.status(result.status).json({ reply: result.message });
+    });
+    // POST /api/transports/:transportId/chats/:externalChatId/connect —
+    // 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()
+            : "";
+        if (!chatSessionId) {
+            badRequest(res, "chatSessionId is required");
+            return;
+        }
+        const updated = await store.connectSession(transportId, externalChatId, chatSessionId);
+        if (!updated) {
+            notFound(res, "No chat state found for this transport");
+            return;
+        }
+        res.json({ ok: true });
+    });
+    return {
+        router,
+        relay,
+        attachSocket: (httpServer) => {
+            const handle = attachChatSocket(httpServer, {
+                relay,
+                queue,
+                logger,
+                tokenProvider,
+            });
+            livePush = handle.pushToBridge;
+        },
+        pushToBridge,
+    };
+}
+export { writeFileAtomic } from "./atomic-write.js";

package/dist/push-queue.d.ts

@@ -0,0 +1,14 @@
+export interface PushMessage {
+    chatId: string;
+    message: string;
+    enqueuedAt: number;
+}
+export interface PushQueue {
+    /** Append a message to the transport's queue. */
+    enqueue(transportId: string, message: PushMessage): void;
+    /** Remove and return all queued messages for `transportId`. */
+    drainFor(transportId: string): PushMessage[];
+    /** How many messages are currently queued for `transportId` (test aid). */
+    sizeFor(transportId: string): number;
+}
+export declare function createPushQueue(): PushQueue;

package/dist/push-queue.js

@@ -0,0 +1,37 @@
+// @package-contract — see ./types.ts
+//
+// In-memory FIFO queue for server→bridge pushes that fire while no
+// bridge socket is connected. One queue per transportId. On socket
+// reconnect, the attaching socket's handler drains its transport's
+// queue and emits the messages to that specific socket.
+//
+// Kept DI-free: no host-app imports, no fs writes. A future Phase
+// B.2 can swap this out for a durable queue with the same interface.
+//
+// Not bounded — bridges reconnect quickly enough in normal operation
+// that the steady state is zero. An adversarial producer could OOM
+// the process; revisit if that threat model changes.
+export function createPushQueue() {
+    const queues = new Map();
+    return {
+        enqueue(transportId, message) {
+            const existing = queues.get(transportId);
+            if (existing) {
+                existing.push(message);
+            }
+            else {
+                queues.set(transportId, [message]);
+            }
+        },
+        drainFor(transportId) {
+            const existing = queues.get(transportId);
+            if (!existing)
+                return [];
+            queues.delete(transportId);
+            return existing;
+        },
+        sizeFor(transportId) {
+            return queues.get(transportId)?.length ?? 0;
+        },
+    };
+}

package/dist/relay.d.ts

@@ -0,0 +1,32 @@
+import type { ChatStateStore } from "./chat-state.js";
+import type { CommandHandler } from "./commands.js";
+import type { Attachment, Logger, OnSessionEventFn, Role, StartChatFn } from "./types.js";
+export interface RelayParams {
+    transportId: string;
+    externalChatId: string;
+    text: string;
+    attachments?: Attachment[];
+    /** 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). */
+    onChunk?: (text: string) => void;
+}
+export type RelayResult = {
+    kind: "ok";
+    reply: string;
+} | {
+    kind: "error";
+    status: number;
+    message: string;
+};
+export type RelayFn = (params: RelayParams) => Promise<RelayResult>;
+export interface RelayDeps {
+    store: ChatStateStore;
+    handleCommand: CommandHandler;
+    startChat: StartChatFn;
+    onSessionEvent: OnSessionEventFn;
+    getRole: (roleId: string) => Role;
+    defaultRoleId: string;
+    logger: Logger;
+}
+export declare function createRelay(deps: RelayDeps): RelayFn;

package/dist/relay.js

@@ -0,0 +1,122 @@
+// @package-contract — see ./types.ts
+//
+// Shared core of the bridge chat flow. HTTP (router) and socket.io
+// transports both call the `RelayFn` this factory returns. DI-pure:
+// all host-app concerns (state store, command handler, agent entry
+// point, session events, role lookup, logger) arrive through
+// `createRelay(deps)` so the module has no direct imports from the
+// host.
+import { EVENT_TYPES } from "@mulmobridge/protocol";
+// ── Constants ────────────────────────────────────────────────
+const REPLY_TIMEOUT_MS = 5 * 60 * 1000;
+// ── Factory ──────────────────────────────────────────────────
+export function createRelay(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
+        // base64 data (performance, log size, information leak risk).
+        const attachmentSummary = attachments
+            ? {
+                count: attachments.length,
+                mimeTypes: attachments.map((a) => a.mimeType),
+            }
+            : undefined;
+        logger.info("chat-service", "message received", {
+            transportId,
+            externalChatId,
+            textLength: text.length,
+            ...(attachmentSummary ? { attachments: attachmentSummary } : {}),
+        });
+        let chatState = await store.getChatState(transportId, externalChatId);
+        if (!chatState) {
+            const defaultRole = getRole(defaultRoleId);
+            chatState = await store.resetChatState(transportId, externalChatId, defaultRole.id);
+        }
+        const commandResult = await handleCommand(text, transportId, chatState);
+        if (commandResult) {
+            return { kind: "ok", reply: commandResult.reply };
+        }
+        const result = await startChat({
+            message: text,
+            roleId: chatState.roleId,
+            chatSessionId: chatState.sessionId,
+            attachments,
+        });
+        if (result.kind === "error") {
+            const status = result.status ?? 500;
+            if (status === 409) {
+                // Session busy — tell the bridge to retry. Keep the HTTP
+                // response shape the old handler returned (status 409 on
+                // the HTTP side, "ok" reply text on the socket side — both
+                // layers decide how to serialise).
+                return {
+                    kind: "ok",
+                    reply: "A previous message is still being processed. Please wait.",
+                };
+            }
+            logger.error("chat-service", "startChat failed", {
+                transportId,
+                externalChatId,
+                error: result.error,
+            });
+            return {
+                kind: "error",
+                status,
+                message: `Error: ${result.error}`,
+            };
+        }
+        try {
+            const reply = await collectAgentReply(onSessionEvent, chatState.sessionId, params.onChunk);
+            await store.setChatState(transportId, {
+                ...chatState,
+                updatedAt: new Date().toISOString(),
+            });
+            return { kind: "ok", reply };
+        }
+        catch (err) {
+            logger.error("chat-service", "reply collection failed", {
+                transportId,
+                externalChatId,
+                error: String(err),
+            });
+            return {
+                kind: "error",
+                status: 500,
+                message: "Error: failed to collect agent reply",
+            };
+        }
+    };
+}
+// ── Internals ────────────────────────────────────────────────
+// 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) {
+    return new Promise((resolve) => {
+        const textChunks = [];
+        const timer = setTimeout(() => {
+            unsubscribe();
+            resolve(textChunks.join("") ||
+                "The request timed out before a reply was generated.");
+        }, REPLY_TIMEOUT_MS);
+        const unsubscribe = onSessionEvent(chatSessionId, (event) => {
+            const type = event.type;
+            if (type === EVENT_TYPES.text) {
+                const chunk = event.message;
+                textChunks.push(chunk);
+                onChunk?.(chunk);
+            }
+            if (type === EVENT_TYPES.error) {
+                clearTimeout(timer);
+                unsubscribe();
+                resolve(`Error: ${event.message}`);
+            }
+            if (type === EVENT_TYPES.sessionFinished) {
+                clearTimeout(timer);
+                unsubscribe();
+                resolve(textChunks.join("") ||
+                    "The assistant completed the request but produced no text reply.");
+            }
+        });
+    });
+}

package/dist/socket.d.ts

@@ -0,0 +1,43 @@
+import type http from "http";
+import { Server as SocketServer } from "socket.io";
+import type { RelayFn } from "./relay.js";
+import type { PushQueue } from "./push-queue.js";
+import type { Logger } from "./types.js";
+export declare const CHAT_SOCKET_PATH = "/ws/chat";
+/**
+ * Custom socket.io events the chat transport defines. Keys mirror
+ * values so grep-and-rename is safe; the union type is what every
+ * on/emit site should reference instead of raw string literals.
+ * Socket.io built-ins (`connect`, `disconnect`, `connect_error`) are
+ * intentionally omitted — those are part of socket.io's own contract,
+ * not ours to rename.
+ */
+export declare const CHAT_SOCKET_EVENTS: {
+    /** bridge → server request (body: `{ externalChatId, text }`); ack
+     *  carries `{ ok, reply, error?, status? }`. */
+    readonly message: "message";
+    /** server → bridge async push (Phase B of #268); body:
+     *  `{ chatId, message }`. */
+    readonly push: "push";
+    /** server → bridge streaming text chunk (Phase C of #268). */
+    readonly textChunk: "textChunk";
+};
+export type ChatSocketEvent = (typeof CHAT_SOCKET_EVENTS)[keyof typeof CHAT_SOCKET_EVENTS];
+export type PushFn = (transportId: string, chatId: string, message: string) => void;
+export interface ChatSocketDeps {
+    relay: RelayFn;
+    queue: PushQueue;
+    logger: Logger;
+    /** Current bearer token the handshake must carry. Null means
+     *  bootstrap in progress — reject everything. Omit to disable. */
+    tokenProvider?: () => string | null;
+}
+export interface ChatSocketHandle {
+    io: SocketServer;
+    /** Fire-and-forget push to every bridge in `bridge:${transportId}`.
+     *  If none are connected, the message is queued for the next
+     *  joiner. */
+    pushToBridge: PushFn;
+}
+export declare function bridgeRoom(transportId: string): string;
+export declare function attachChatSocket(server: http.Server, deps: ChatSocketDeps): ChatSocketHandle;

package/dist/socket.js

@@ -0,0 +1,232 @@
+// @package-contract — see ./types.ts
+//
+// Socket.io transport for the bridge chat flow.
+//
+// Phase A (#268) — bridge → server req/res:
+//   handshake.auth: { transportId: string; token?: string }
+//   emit("message", { externalChatId, text }, ack)
+//     ack receives { ok: true, reply }
+//                 | { ok: false, error, status? }
+//
+// Phase B (#268) — server → bridge async push:
+//   Each connected bridge joins room `bridge:${transportId}`.
+//   Server emits `push` { chatId, message } to that room via the
+//   `pushToBridge(transportId, chatId, message)` helper this module
+//   returns. If no sockets are in the room at push time, the
+//   message goes to an in-memory queue; the next socket that joins
+//   the room drains its transport's queue on connect.
+//
+// Auth: when `tokenProvider` is supplied, the handshake is rejected
+// unless `auth.token` equals `tokenProvider()`. When omitted (tests,
+// unauth environments) only `transportId` is validated.
+//
+// Future phases:
+//   C — streaming text chunks via `reply.chunk`
+//   D — HTTP endpoint deprecation
+//
+// See plans/feat-chat-socketio.md and plans/feat-chat-socketio-phase-b.md.
+import { Server as SocketServer } from "socket.io";
+export const CHAT_SOCKET_PATH = "/ws/chat";
+/**
+ * Custom socket.io events the chat transport defines. Keys mirror
+ * values so grep-and-rename is safe; the union type is what every
+ * on/emit site should reference instead of raw string literals.
+ * Socket.io built-ins (`connect`, `disconnect`, `connect_error`) are
+ * intentionally omitted — those are part of socket.io's own contract,
+ * not ours to rename.
+ */
+export const CHAT_SOCKET_EVENTS = {
+    /** bridge → server request (body: `{ externalChatId, text }`); ack
+     *  carries `{ ok, reply, error?, status? }`. */
+    message: "message",
+    /** server → bridge async push (Phase B of #268); body:
+     *  `{ chatId, message }`. */
+    push: "push",
+    /** server → bridge streaming text chunk (Phase C of #268). */
+    textChunk: "textChunk",
+};
+export function bridgeRoom(transportId) {
+    return `bridge:${transportId}`;
+}
+export function attachChatSocket(server, deps) {
+    const { relay, queue, logger, tokenProvider } = deps;
+    const io = new SocketServer(server, {
+        path: CHAT_SOCKET_PATH,
+        // Loopback-only deployment; skip long-polling negotiation for
+        // the same reason `/ws/pubsub` does (#311).
+        transports: ["websocket"],
+    });
+    io.use((socket, next) => {
+        const result = validateHandshake(socket.handshake.auth, tokenProvider);
+        if (!result.ok) {
+            next(new Error(result.error));
+            return;
+        }
+        socket.data.transportId = result.transportId;
+        next();
+    });
+    io.on("connection", (socket) => {
+        const transportId = socket.data.transportId;
+        const room = bridgeRoom(transportId);
+        socket.join(room);
+        // Flush any messages queued while this transport had no live
+        // socket. Emit only to *this* socket, not the room, so a
+        // second bridge joining seconds later doesn't re-receive the
+        // already-drained messages.
+        const queued = queue.drainFor(transportId);
+        if (queued.length > 0) {
+            logger.info("chat-service", "flushing push queue", {
+                socketId: socket.id,
+                transportId,
+                count: queued.length,
+            });
+            for (const item of queued) {
+                socket.emit(CHAT_SOCKET_EVENTS.push, {
+                    chatId: item.chatId,
+                    message: item.message,
+                });
+            }
+        }
+        logger.info("chat-service", "socket connected", {
+            socketId: socket.id,
+            transportId,
+        });
+        socket.on("disconnect", (reason) => {
+            logger.info("chat-service", "socket disconnected", {
+                socketId: socket.id,
+                transportId,
+                reason,
+            });
+        });
+        socket.on(CHAT_SOCKET_EVENTS.message, async (payload, ack) => {
+            if (typeof ack !== "function") {
+                logger.warn("chat-service", "socket message missing ack", {
+                    socketId: socket.id,
+                    transportId,
+                });
+                return;
+            }
+            const parsed = parseMessagePayload(payload);
+            if (!parsed.ok) {
+                ack({ ok: false, error: parsed.error, status: 400 });
+                return;
+            }
+            const result = await relay({
+                transportId,
+                externalChatId: parsed.externalChatId,
+                text: parsed.text,
+                attachments: parsed.attachments,
+                // Stream text chunks to this bridge socket in real time
+                // (Phase C of #268). The ack still returns the full text
+                // for backward compatibility.
+                onChunk: (text) => {
+                    socket.emit(CHAT_SOCKET_EVENTS.textChunk, { text });
+                },
+            });
+            if (result.kind === "ok") {
+                ack({ ok: true, reply: result.reply });
+            }
+            else {
+                ack({ ok: false, error: result.message, status: result.status });
+            }
+        });
+    });
+    const pushToBridge = (transportId, chatId, message) => {
+        const room = bridgeRoom(transportId);
+        // `io.sockets.adapter.rooms` is the authoritative view of which
+        // rooms have members right now. Using it here (vs. a separate
+        // membership counter we'd have to maintain) keeps us honest
+        // about what socket.io actually knows.
+        const hasLive = (io.sockets.adapter.rooms.get(room)?.size ?? 0) > 0;
+        if (hasLive) {
+            io.to(room).emit(CHAT_SOCKET_EVENTS.push, { chatId, message });
+            return;
+        }
+        queue.enqueue(transportId, { chatId, message, enqueuedAt: Date.now() });
+        logger.info("chat-service", "push queued (no live bridge)", {
+            transportId,
+            chatId,
+            queueSize: queue.sizeFor(transportId),
+        });
+    };
+    return { io, pushToBridge };
+}
+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) {
+        return { ok: false, error: "transportId is required" };
+    }
+    const transportId = transportIdRaw.trim();
+    if (!tokenProvider) {
+        return { ok: true, transportId };
+    }
+    const expected = tokenProvider();
+    if (expected === null || expected.length === 0) {
+        // Server auth not bootstrapped yet, or token absent. Reject so
+        // the bridge falls back to its connect-error path instead of
+        // silently succeeding.
+        return { ok: false, error: "server auth not ready" };
+    }
+    const provided = auth.token;
+    if (typeof provided !== "string" || provided.length === 0) {
+        return { ok: false, error: "token is required" };
+    }
+    if (provided !== expected) {
+        return { ok: false, error: "invalid token" };
+    }
+    return { ok: true, transportId };
+}
+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 text = typeof payload.text === "string" ? payload.text.trim() : "";
+    if (!externalChatId) {
+        return { ok: false, error: "externalChatId is required" };
+    }
+    if (!text) {
+        return { ok: false, error: "text is required" };
+    }
+    const attachments = parseAttachments(payload.attachments);
+    return { ok: true, externalChatId, text, attachments };
+}
+// Hard limits to prevent oversized payloads from bridges (DoS /
+// accidental misconfiguration). Express's JSON body limit (50 MB)
+// is the outer gate; these are tighter, attachment-specific caps.
+const MAX_ATTACHMENT_COUNT = 10;
+const MAX_ATTACHMENT_TOTAL_BYTES = 20 * 1024 * 1024; // 20 MB base64
+function parseAttachments(raw) {
+    if (!Array.isArray(raw) || raw.length === 0)
+        return undefined;
+    const valid = [];
+    let totalBytes = 0;
+    for (const item of raw) {
+        if (valid.length >= MAX_ATTACHMENT_COUNT)
+            break;
+        if (item &&
+            typeof item === "object" &&
+            typeof item.mimeType === "string" &&
+            typeof item.data === "string") {
+            const data = item.data;
+            totalBytes += data.length;
+            if (totalBytes > MAX_ATTACHMENT_TOTAL_BYTES)
+                break;
+            const entry = {
+                mimeType: item.mimeType,
+                data,
+            };
+            const fn = item.filename;
+            if (typeof fn === "string" && fn.length > 0)
+                entry.filename = fn;
+            valid.push(entry);
+        }
+    }
+    return valid.length > 0 ? valid : undefined;
+}

package/dist/types.d.ts

@@ -0,0 +1,59 @@
+export interface Role {
+    id: string;
+    name: string;
+}
+export interface Logger {
+    error(prefix: string, message: string, data?: Record<string, unknown>): void;
+    warn(prefix: string, message: string, data?: Record<string, unknown>): void;
+    info(prefix: string, message: string, data?: Record<string, unknown>): void;
+    debug(prefix: string, message: string, data?: Record<string, unknown>): void;
+}
+/** A file attached to a bridge message. Generic enough for images,
+ *  PDFs, documents, videos, etc. The server decides what to do with
+ *  each based on mimeType — images become vision content blocks,
+ *  unsupported types are ignored with a log. */
+export interface Attachment {
+    mimeType: string;
+    data: string;
+    filename?: string;
+}
+export interface StartChatParams {
+    message: string;
+    roleId: string;
+    chatSessionId: string;
+    selectedImageData?: string;
+    attachments?: Attachment[];
+}
+export type StartChatResult = {
+    kind: "started";
+    chatSessionId: string;
+} | {
+    kind: "error";
+    error: string;
+    status?: number;
+};
+export type StartChatFn = (params: StartChatParams) => Promise<StartChatResult>;
+export type SessionEventListener = (event: Record<string, unknown>) => void;
+export type OnSessionEventFn = (sessionId: string, listener: SessionEventListener) => () => void;
+export interface ChatServiceDeps {
+    /** Relay a user turn into the agent loop. */
+    startChat: StartChatFn;
+    /** Subscribe to a session's event stream; returns an unsubscribe function. */
+    onSessionEvent: OnSessionEventFn;
+    /** All roles (built-in + custom). */
+    loadAllRoles: () => Role[];
+    /** Look up a single role by id; MUST fall back to default if unknown. */
+    getRole: (roleId: string) => Role;
+    /** Id used when a fresh transport chat has no role selected yet. */
+    defaultRoleId: string;
+    /** Absolute path to the transports workspace dir (one subdir per transportId). */
+    transportsDir: string;
+    logger: Logger;
+    /**
+     * Returns the current bearer token the socket transport should
+     * accept at handshake, or null if auth isn't bootstrapped yet.
+     * Omit in tests / unauth environments to skip the check. See
+     * `attachChatSocket` in ./socket.ts.
+     */
+    tokenProvider?: () => string | null;
+}

package/dist/types.js

@@ -0,0 +1,17 @@
+// @package-contract
+//
+// This module is designed to be extractable as a standalone npm
+// package (e.g. `@mulmoclaude/chat-service`) at any time. To keep
+// that path open, the rules are:
+//
+//  1. NO raw imports from `../` outside this directory — all host
+//     dependencies MUST be passed through `ChatServiceDeps`.
+//  2. Types declared here are STRUCTURAL duplicates of what the
+//     host app uses. They look like the real `Role` / `Logger` /
+//     `StartChatParams` types so the same functions plug in, but
+//     they are defined here so the package has no compile-time
+//     link back to the host.
+//  3. When you add a new dependency, extend `ChatServiceDeps` and
+//     thread it through the factory functions — do NOT reach out
+//     to a module import. See #269 / #305 for the rationale.
+export {};

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@mulmobridge/chat-service",
+  "version": "0.1.0",
+  "description": "Server-side chat service for MulmoBridge — socket.io + REST bridge to Claude Code agents",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepack": "yarn build",
+    "typecheck": "tsc --noEmit",
+    "test": "tsx --test test/test_*.ts",
+    "lint": "eslint src test"
+  },
+  "license": "MIT",
+  "author": "Receptron Team",
+  "dependencies": {
+    "@mulmobridge/protocol": "^0.1.0"
+  },
+  "peerDependencies": {
+    "express": "^5.0.0",
+    "socket.io": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.0",
+    "typescript": "^6.0.3"
+  }
+}