@mulmobridge/chat-service

Server-side chat service for MulmoBridge — provides socket.io + REST endpoints that connect external bridges (CLI, Telegram, etc.) to a Claude Code agent.

Install

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.

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,    // required: the current bearer token the /ws/chat handshake must carry
});

// Mount the Express router
app.use(chatService.router);

// Attach socket.io to the HTTP server
chatService.attachSocket(httpServer);

tokenProvider returns the current bearer token, or null while the host has none yet; every handshake is refused until it returns one. A refused token answers connect_error with the generic unauthorized — the same message /api/* sends — never with which part failed. The wire contract is in docs/bridge-protocol.md in the repository.

Architecture

┌─────────────┐     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 | Wire protocol types and constants | | @mulmobridge/chat-service | Server-side chat service (this package) | | @mulmobridge/client | Bridge client library | | @mulmobridge/cli | CLI bridge | | @mulmobridge/telegram | Telegram bridge |

Ecosystem

Part of the @mulmobridge/* package family.

Shared libraries:

• @mulmobridge/client — socket.io client library used by every bridge below
• @mulmobridge/protocol — wire types and constants
• @mulmobridge/chat-service — server-side relay + session store ← this package
• @mulmobridge/relay — Cloudflare Workers webhook proxy
• @mulmobridge/mock-server — mock server for local bridge development

Bridges (one npm package per platform):

• @mulmobridge/bluesky — Bluesky DMs over atproto
• @mulmobridge/chatwork — Chatwork (Japanese business chat)
• @mulmobridge/cli — interactive terminal bridge
• @mulmobridge/discord — Discord bot via Gateway
• @mulmobridge/email — IMAP poll + SMTP reply, threading preserved
• @mulmobridge/google-chat — Google Chat via MulmoBridge relay
• @mulmobridge/irc — IRC (Libera, Freenode, custom)
• @mulmobridge/line — LINE Messaging API via MulmoBridge relay
• @mulmobridge/line-works — LINE Works (enterprise LINE)
• @mulmobridge/mastodon — Mastodon DMs + mentions
• @mulmobridge/matrix — Matrix / Element
• @mulmobridge/mattermost — Mattermost
• @mulmobridge/messenger — Facebook Messenger via MulmoBridge relay
• @mulmobridge/nostr — Nostr NIP-04 encrypted DMs
• @mulmobridge/rocketchat — Rocket.Chat
• @mulmobridge/signal — Signal via signal-cli-rest-api
• @mulmobridge/slack — Slack Socket Mode
• @mulmobridge/teams — Microsoft Teams via Bot Framework
• @mulmobridge/telegram — Telegram bot
• @mulmobridge/twilio-sms — SMS via Twilio Programmable Messaging
• @mulmobridge/viber — Viber Public Account bots
• @mulmobridge/webhook — generic HTTP webhook bridge
• @mulmobridge/whatsapp — WhatsApp Cloud API via MulmoBridge relay
• @mulmobridge/xmpp — XMPP / Jabber
• @mulmobridge/zulip — Zulip

Related projects

Published from the MulmoClaude monorepo by Receptron.

• MulmoClaude — an open-source AI assistant platform that runs on your own computer. Claude Code as the engine, a personal wiki for long-term memory, schema-driven collections for your data, and chat that summons the right GUI (markdown, charts, forms, spreadsheets, wikis) for each task.
• MulmoTerminal — a terminal-first cockpit for running many AI coding agents in parallel. One roster showing every session's summary and PR status, tmux-backed session persistence, git-worktree isolation, one-click PRs, and mobile push with remote reply.
• MulmoTerminal manual — setup, workflows, feature reference, configuration, mobile notifications, and alternative / local model providers. Available in English and Japanese.

License

MIT — Receptron Team