@mulmobridge/chat-service 0.1.1 → 0.1.3

package/README.md

@@ -73,6 +73,47 @@ chatService.attachSocket(httpServer);
 | [@mulmobridge/cli](https://www.npmjs.com/package/@mulmobridge/cli) | CLI bridge |
 | [@mulmobridge/telegram](https://www.npmjs.com/package/@mulmobridge/telegram) | Telegram bridge |
 
+## Ecosystem
+
+Part of the [`@mulmobridge/*`](https://www.npmjs.com/~mulmobridge) package family.
+
+**Shared libraries:**
+
+- [`@mulmobridge/client`](https://www.npmjs.com/package/@mulmobridge/client) — socket.io client library used by every bridge below
+- [`@mulmobridge/protocol`](https://www.npmjs.com/package/@mulmobridge/protocol) — wire types and constants
+- [`@mulmobridge/chat-service`](https://www.npmjs.com/package/@mulmobridge/chat-service) — server-side relay + session store  ← **this package**
+- [`@mulmobridge/relay`](https://www.npmjs.com/package/@mulmobridge/relay) — Cloudflare Workers webhook proxy
+- [`@mulmobridge/mock-server`](https://www.npmjs.com/package/@mulmobridge/mock-server) — mock server for local bridge development
+
+**Bridges** (one npm package per platform):
+
+- [`@mulmobridge/bluesky`](https://www.npmjs.com/package/@mulmobridge/bluesky) — Bluesky DMs over atproto
+- [`@mulmobridge/chatwork`](https://www.npmjs.com/package/@mulmobridge/chatwork) — Chatwork (Japanese business chat)
+- [`@mulmobridge/cli`](https://www.npmjs.com/package/@mulmobridge/cli) — interactive terminal bridge
+- [`@mulmobridge/discord`](https://www.npmjs.com/package/@mulmobridge/discord) — Discord bot via Gateway
+- [`@mulmobridge/email`](https://www.npmjs.com/package/@mulmobridge/email) — IMAP poll + SMTP reply, threading preserved
+- [`@mulmobridge/google-chat`](https://www.npmjs.com/package/@mulmobridge/google-chat) — Google Chat via MulmoBridge relay
+- [`@mulmobridge/irc`](https://www.npmjs.com/package/@mulmobridge/irc) — IRC (Libera, Freenode, custom)
+- [`@mulmobridge/line`](https://www.npmjs.com/package/@mulmobridge/line) — LINE Messaging API via MulmoBridge relay
+- [`@mulmobridge/line-works`](https://www.npmjs.com/package/@mulmobridge/line-works) — LINE Works (enterprise LINE)
+- [`@mulmobridge/mastodon`](https://www.npmjs.com/package/@mulmobridge/mastodon) — Mastodon DMs + mentions
+- [`@mulmobridge/matrix`](https://www.npmjs.com/package/@mulmobridge/matrix) — Matrix / Element
+- [`@mulmobridge/mattermost`](https://www.npmjs.com/package/@mulmobridge/mattermost) — Mattermost
+- [`@mulmobridge/messenger`](https://www.npmjs.com/package/@mulmobridge/messenger) — Facebook Messenger via MulmoBridge relay
+- [`@mulmobridge/nostr`](https://www.npmjs.com/package/@mulmobridge/nostr) — Nostr NIP-04 encrypted DMs
+- [`@mulmobridge/rocketchat`](https://www.npmjs.com/package/@mulmobridge/rocketchat) — Rocket.Chat
+- [`@mulmobridge/signal`](https://www.npmjs.com/package/@mulmobridge/signal) — Signal via signal-cli-rest-api
+- [`@mulmobridge/slack`](https://www.npmjs.com/package/@mulmobridge/slack) — Slack Socket Mode
+- [`@mulmobridge/teams`](https://www.npmjs.com/package/@mulmobridge/teams) — Microsoft Teams via Bot Framework
+- [`@mulmobridge/telegram`](https://www.npmjs.com/package/@mulmobridge/telegram) — Telegram bot
+- [`@mulmobridge/twilio-sms`](https://www.npmjs.com/package/@mulmobridge/twilio-sms) — SMS via Twilio Programmable Messaging
+- [`@mulmobridge/viber`](https://www.npmjs.com/package/@mulmobridge/viber) — Viber Public Account bots
+- [`@mulmobridge/webhook`](https://www.npmjs.com/package/@mulmobridge/webhook) — generic HTTP webhook bridge
+- [`@mulmobridge/whatsapp`](https://www.npmjs.com/package/@mulmobridge/whatsapp) — WhatsApp Cloud API via MulmoBridge relay
+- [`@mulmobridge/xmpp`](https://www.npmjs.com/package/@mulmobridge/xmpp) — XMPP / Jabber
+- [`@mulmobridge/zulip`](https://www.npmjs.com/package/@mulmobridge/zulip) — Zulip
+
+
 ## License
 
 MIT — [Receptron Team](https://github.com/receptron)

package/dist/commands.d.ts

@@ -1,8 +1,13 @@
-import type { Role, SessionSummary } from "./types.js";
+import type { BridgeSkillSummary, Role, SessionSummary } from "./types.js";
 import type { ChatStateStore, TransportChatState } from "./chat-state.js";
 export interface CommandResult {
     reply: string;
     nextState?: TransportChatState;
+    /** When set, the relay must NOT short-circuit with `reply`. It
+     *  adopts `nextState` as the active chat state and forwards
+     *  `forwardAs` to the agent as the user message. Used by the
+     *  `//{skill}` shortcut: reset + run skill in one bridge turn. */
+    forwardAs?: string;
 }
 export type CommandHandler = (text: string, transportId: string, chatState: TransportChatState) => Promise<CommandResult | null>;
 export declare function createCommandHandler(opts: {
@@ -27,4 +32,10 @@ export declare function createCommandHandler(opts: {
         }>;
         total: number;
     }>;
+    /** Lists the skills the bridge command handler should expose.
+     *  Drives both the slash-command allowlist (only matching names
+     *  are forwarded to the agent) and the "Skills:" section in the
+     *  `/help` reply. When omitted, every unknown slash is rejected
+     *  and `/help` shows only the built-in commands. */
+    listRegisteredSkills?: () => Promise<BridgeSkillSummary[]>;
 }): CommandHandler;

package/dist/commands.js

@@ -24,7 +24,7 @@ function formatRelativeTime(isoDate) {
 }
 // ── Factory ──────────────────────────────────────────────────
 export function createCommandHandler(opts) {
-    const { loadAllRoles, getRole, resetChatState, connectSession, listSessions, getSessionHistory } = opts;
+    const { loadAllRoles, getRole, resetChatState, connectSession, listSessions, getSessionHistory, listRegisteredSkills } = 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.
@@ -51,19 +51,30 @@ export function createCommandHandler(opts) {
         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",
-        "  /status — Show current session info",
-        "",
-        "Send any other text to chat with the assistant.",
-    ].join("\n");
+    // Built each time so `/help` reflects the live skill list. The
+    // `skills` argument is fetched once per command turn (see the
+    // `default:` branch and `case "/help"`) so we don't fs-scan twice
+    // when the handler both checks membership and renders help.
+    const buildHelpText = (skills) => {
+        const lines = [
+            "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",
+            "  /status — Show current session info",
+        ];
+        if (skills.length > 0) {
+            lines.push("", "Skills:", ...skills.map((s) => `  /${s.name} — ${s.description}`));
+            lines.push("", "Tip: //<skill> [args...] starts a fresh session and runs the skill in one shot.");
+        }
+        lines.push("", "Send any other text to chat with the assistant.");
+        return lines.join("\n");
+    };
+    const fetchSkills = async () => (listRegisteredSkills ? await listRegisteredSkills() : []);
     const handleReset = async (transportId, chatState) => {
         const nextState = await resetChatState(transportId, chatState.externalChatId, chatState.roleId);
         return {
@@ -211,6 +222,25 @@ export function createCommandHandler(opts) {
     const handleCommand = async (text, transportId, chatState) => {
         if (!text.startsWith("/"))
             return null;
+        // `//{skill} [args...]` shortcut — start a new session AND run
+        // the skill in one bridge turn. Args after the skill name are
+        // forwarded verbatim, so `//mag2 https://x.com/post` resets and
+        // runs `/mag2 https://x.com/post`.
+        if (text.startsWith("//")) {
+            const skills = await fetchSkills();
+            const [head, ...rest] = text.split(/\s+/);
+            const skillName = head.slice(2);
+            if (skillName && skills.some((s) => s.name === skillName)) {
+                const nextState = await resetChatState(transportId, chatState.externalChatId, chatState.roleId);
+                const forwardAs = rest.length > 0 ? `/${skillName} ${rest.join(" ")}` : `/${skillName}`;
+                return {
+                    reply: `Session reset. Running ${forwardAs}`,
+                    nextState,
+                    forwardAs,
+                };
+            }
+            return { reply: `Unknown command: ${text}\n\n${buildHelpText(skills)}` };
+        }
         const [command, ...args] = text.split(/\s+/);
         switch (command) {
             case "/reset":
@@ -222,15 +252,27 @@ export function createCommandHandler(opts) {
             case "/history":
                 return handleHistory(chatState, args[0]);
             case "/help":
-                return { reply: getHelpText() };
+                return { reply: buildHelpText(await fetchSkills()) };
             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()}` };
+            default: {
+                // Forward to the agent only if the command names a registered
+                // skill; otherwise reply with the standard "Unknown command"
+                // help. We deliberately do NOT pass arbitrary slash text
+                // through, so a typo can't accidentally invoke the agent and
+                // a slash that doesn't match anything stays a transport-level
+                // error. Reuse the same skill list for the membership check
+                // and the help text to avoid scanning the skills dir twice.
+                const skills = await fetchSkills();
+                const skillName = command.slice(1);
+                if (skillName && skills.some((s) => s.name === skillName))
+                    return null;
+                return { reply: `Unknown command: ${command}\n\n${buildHelpText(skills)}` };
+            }
         }
     };
     return handleCommand;

package/dist/index.js

@@ -42,6 +42,7 @@ export function createChatService(deps) {
         connectSession: store.connectSession,
         listSessions: deps.listSessions,
         getSessionHistory: deps.getSessionHistory,
+        listRegisteredSkills: deps.listRegisteredSkills,
     });
     const relay = createRelay({
         store,

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/done/feat-bridge-options-passthrough.md. */
+    bridgeOptions?: Readonly<Record<string, string | number | boolean>>;
     /** Called for each text chunk as the agent generates it. Used by
      *  the socket transport to stream text to the bridge in real time
      *  (Phase C of #268). */
@@ -30,3 +36,4 @@ export interface RelayDeps {
     logger: Logger;
 }
 export declare function createRelay(deps: RelayDeps): RelayFn;
+export declare function resolveDefaultRole(bridgeOptions: Readonly<Record<string, string | number | boolean>> | undefined, getRole: (roleId: string) => Role, fallbackRoleId: string, logger: Logger, transportId: string): string;

package/dist/relay.js

@@ -13,7 +13,8 @@ const REPLY_TIMEOUT_MS = 5 * 60 * 1000;
 export function createRelay(deps) {
     const { store, handleCommand, startChat, onSessionEvent, getRole, defaultRoleId, logger } = deps;
     return async function relayMessage(params) {
-        const { transportId, externalChatId, text, attachments } = params;
+        const { transportId, externalChatId, attachments, bridgeOptions } = params;
+        let { text } = params;
         // Log attachment summary (count + mimeTypes) — NEVER log raw
         // base64 data (performance, log size, information leak risk).
         const attachmentSummary = attachments
@@ -30,12 +31,25 @@ 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) {
-            return { kind: "ok", reply: commandResult.reply };
+            // `forwardAs` means "reset/mutate state AND continue into the
+            // agent with rewritten text" (see //{skill} shortcut). Without
+            // it, short-circuit with the canned reply.
+            if (!commandResult.forwardAs) {
+                return { kind: "ok", reply: commandResult.reply };
+            }
+            if (commandResult.nextState)
+                chatState = commandResult.nextState;
+            text = commandResult.forwardAs;
         }
         const result = await startChat({
             message: text,
@@ -43,6 +57,9 @@ export function createRelay(deps) {
             chatSessionId: chatState.sessionId,
             attachments,
             origin: "bridge",
+            // Host app may use other keys (e.g. a future `defaultModel`);
+            // we forward the whole bag untouched.
+            bridgeOptions,
         });
         if (result.kind === "error") {
             const status = result.status ?? 500;
@@ -90,6 +107,28 @@ export function createRelay(deps) {
     };
 }
 // ── Internals ────────────────────────────────────────────────
+// Resolve the role id to seed a NEW bridge chat state with. Prefers
+// `bridgeOptions.defaultRole` when the bridge sent one and it names
+// a role the host app actually has. Falls back to the host-app
+// default on absence / unknown id (with a warn log so an env-var
+// typo is traceable). Exported for direct unit testing.
+export function resolveDefaultRole(bridgeOptions, getRole, fallbackRoleId, logger, transportId) {
+    const requested = bridgeOptions?.defaultRole;
+    if (typeof requested !== "string" || requested.length === 0)
+        return fallbackRoleId;
+    // `getRole` on an unknown id silently returns the first built-in
+    // role — compare ids to catch that before we commit to it.
+    const resolved = getRole(requested);
+    if (resolved.id !== requested) {
+        logger.warn("chat-service", "bridge requested unknown default role; falling back", {
+            transportId,
+            requested,
+            fallback: fallbackRoleId,
+        });
+        return fallbackRoleId;
+    }
+    return resolved.id;
+}
 // Kept out of the factory closure so future packaging doesn't need
 // to re-capture anything; `onSessionEvent` arrives as a plain param.
 function collectAgentReply(onSessionEvent, chatSessionId, onChunk) {

package/dist/socket.d.ts

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

package/dist/socket.js

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

package/dist/types.d.ts

@@ -25,6 +25,14 @@ export interface StartChatParams {
     attachments?: Attachment[];
     /** Session origin — application-defined (e.g. "human", "bridge") */
     origin?: string;
+    /** Flat primitive bag forwarded from the bridge handshake. Chat-
+     *  service sanitises to string / number / boolean values only
+     *  before this point — nested objects are dropped at the socket
+     *  boundary so a downstream merge can't reintroduce prototype-
+     *  pollution. The host app is free to look up its own keys
+     *  (e.g. `defaultRole`). Empty object when the bridge didn't
+     *  send any. */
+    bridgeOptions?: Readonly<Record<string, string | number | boolean>>;
 }
 export type StartChatResult = {
     kind: "started";
@@ -91,4 +99,26 @@ export interface ChatServiceDeps {
         }>;
         total: number;
     }>;
+    /**
+     * Return the skills the bridge command handler should expose. The
+     * handler uses the result for two things:
+     *   (1) Decide whether an unknown bridge slash command (e.g. `/foo`
+     *       from Telegram) names a registered skill — only matching
+     *       names are forwarded to the agent so the Claude CLI's
+     *       slash-command resolver runs the skill. Non-matches stay a
+     *       transport-level "Unknown command" reply.
+     *   (2) Render a "Skills:" section in the bridge `/help` text and
+     *       in the "Unknown command" fallback so a bridge user can
+     *       discover what skills exist without leaving the chat.
+     * When omitted, every unknown slash is rejected and `/help` shows
+     * only the built-in commands.
+     */
+    listRegisteredSkills?: () => Promise<BridgeSkillSummary[]>;
+}
+/** Minimal skill info the bridge command handler needs to render the
+ *  `/help` text and decide whether a slash command should be forwarded
+ *  to the agent. Sourced from SKILL.md frontmatter on the host side. */
+export interface BridgeSkillSummary {
+    name: string;
+    description: string;
 }

package/package.json

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