@mulmobridge/chat-service 0.1.2 → 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

@@ -10,7 +10,7 @@ export interface RelayParams {
      *  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. */
+     *  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

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, bridgeOptions } = 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
@@ -40,7 +41,15 @@ export function createRelay(deps) {
         }
         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,

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";
 /**

package/dist/types.d.ts

@@ -99,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.2",
+  "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",