@mulmobridge/chat-service 0.1.2 → 0.1.4

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,10 +1,41 @@
-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>;
+/**
+ * Split a `//{skill} [args...]` shortcut into the skill name and the
+ * verbatim argument text.
+ *
+ * The separator between the skill name and args is the FIRST run of
+ * whitespace (a single space, multiple spaces, a tab, a CRLF — the
+ * bridge can't disambiguate "long separator" from "short separator
+ * plus leading whitespace in args", so the simple choice is to drop
+ * the whole leading run as one logical separator). Whitespace INSIDE
+ * the args (after the first run) is preserved verbatim, so doubled
+ * spaces, tabs, and newlines pasted into a multi-line prompt all
+ * survive.
+ *
+ * Exported for unit tests; callers in the handler use it directly.
+ *
+ * Examples:
+ *   "//mag2"               → { skillName: "mag2", argsVerbatim: "" }
+ *   "//mag2 url"           → { skillName: "mag2", argsVerbatim: "url" }
+ *   "//mag2  url"          → { skillName: "mag2", argsVerbatim: "url" }
+ *   "//mag2\r\nurl"        → { skillName: "mag2", argsVerbatim: "url" }
+ *   "//mag2 a  b\tc"       → { skillName: "mag2", argsVerbatim: "a  b\tc" }
+ */
+export declare function parseSkillShortcut(text: string): {
+    skillName: string;
+    argsVerbatim: string;
+};
 export declare function createCommandHandler(opts: {
     loadAllRoles: () => Role[];
     getRole: (roleId: string) => Role;
@@ -27,4 +58,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

@@ -22,9 +22,43 @@ function formatRelativeTime(isoDate) {
     const days = Math.floor(diffMs / ONE_DAY_MS);
     return `${days}d ago`;
 }
+/**
+ * Split a `//{skill} [args...]` shortcut into the skill name and the
+ * verbatim argument text.
+ *
+ * The separator between the skill name and args is the FIRST run of
+ * whitespace (a single space, multiple spaces, a tab, a CRLF — the
+ * bridge can't disambiguate "long separator" from "short separator
+ * plus leading whitespace in args", so the simple choice is to drop
+ * the whole leading run as one logical separator). Whitespace INSIDE
+ * the args (after the first run) is preserved verbatim, so doubled
+ * spaces, tabs, and newlines pasted into a multi-line prompt all
+ * survive.
+ *
+ * Exported for unit tests; callers in the handler use it directly.
+ *
+ * Examples:
+ *   "//mag2"               → { skillName: "mag2", argsVerbatim: "" }
+ *   "//mag2 url"           → { skillName: "mag2", argsVerbatim: "url" }
+ *   "//mag2  url"          → { skillName: "mag2", argsVerbatim: "url" }
+ *   "//mag2\r\nurl"        → { skillName: "mag2", argsVerbatim: "url" }
+ *   "//mag2 a  b\tc"       → { skillName: "mag2", argsVerbatim: "a  b\tc" }
+ */
+export function parseSkillShortcut(text) {
+    const sepIdx = text.search(/\s/);
+    if (sepIdx < 0)
+        return { skillName: text.slice(2), argsVerbatim: "" };
+    const head = text.slice(0, sepIdx);
+    // Strip the full leading whitespace run — \s in JS already matches
+    // \r, \n, \t, \v, \f, NBSP (U+00A0), and the rest of Unicode whitespace,
+    // so CRLF separators collapse to nothing instead of leaving an orphan
+    // \n in argsVerbatim (Codex review iter-1).
+    const argsVerbatim = text.slice(sepIdx).replace(/^\s+/, "");
+    return { skillName: head.slice(2), argsVerbatim };
+}
 // ── 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 +85,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 +256,26 @@ 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 — split at the FIRST whitespace character
+        // and preserve everything after it (including doubled spaces /
+        // tabs) so payloads like a URL with internal whitespace, or
+        // multi-paragraph prompts, aren't silently rewritten.
+        if (text.startsWith("//")) {
+            const skills = await fetchSkills();
+            const { skillName, argsVerbatim } = parseSkillShortcut(text);
+            if (skillName && skills.some((s) => s.name === skillName)) {
+                const nextState = await resetChatState(transportId, chatState.externalChatId, chatState.roleId);
+                const forwardAs = argsVerbatim.length > 0 ? `/${skillName} ${argsVerbatim}` : `/${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 +287,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/keyed-serializer.d.ts

@@ -0,0 +1,4 @@
+export interface KeyedSerializer {
+    run<T>(key: string, task: () => Promise<T>): Promise<T>;
+}
+export declare function createKeyedSerializer(): KeyedSerializer;

package/dist/keyed-serializer.js

@@ -0,0 +1,33 @@
+// @package-contract — see ./types.ts
+//
+// Per-key serialization primitive. `run(key, task)` guarantees that
+// for any single key, tasks execute one-at-a-time in call order;
+// tasks under different keys run concurrently. The bridge relay uses
+// it to serialize all turns for one external chat so two concurrent
+// first messages can't each create a separate session (#1878).
+//
+// In-memory and DI-free, matching push-queue.ts: a single server
+// process owns every relay turn. Each per-key chain entry is dropped
+// once its tail settles, so the map doesn't grow without bound.
+export function createKeyedSerializer() {
+    const tails = new Map();
+    return {
+        run(key, task) {
+            // `prev` is a swallowed tail that never rejects, so the next
+            // task always starts regardless of how the previous one settled.
+            const prev = tails.get(key) ?? Promise.resolve();
+            const result = prev.then(() => task());
+            // Swallow the outcome (so the chain never breaks), then drop the
+            // map entry — but only when no later task has chained onto this
+            // tail, so unrelated keys never leave stale entries behind.
+            const tail = result
+                .then(() => { }, () => { })
+                .then(() => {
+                if (tails.get(key) === tail)
+                    tails.delete(key);
+            });
+            tails.set(key, tail);
+            return result;
+        },
+    };
+}

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

@@ -7,95 +7,114 @@
 // `createRelay(deps)` so the module has no direct imports from the
 // host.
 import { EVENT_TYPES } from "@mulmobridge/protocol";
+import { createKeyedSerializer } from "./keyed-serializer.js";
 // ── Constants ────────────────────────────────────────────────
 const REPLY_TIMEOUT_MS = 5 * 60 * 1000;
 // ── Factory ──────────────────────────────────────────────────
 export function createRelay(deps) {
+    const serialize = createKeyedSerializer();
+    return function relayMessage(params) {
+        // Serialize every turn for one external chat. Without this, two
+        // concurrent first messages each read "no state", create separate
+        // sessions, and split the conversation across them (#1878). The
+        // JSON pair is an unambiguous composite key for the two ids.
+        const key = JSON.stringify([params.transportId, params.externalChatId]);
+        return serialize.run(key, () => processRelayMessage(deps, params));
+    };
+}
+async function processRelayMessage(deps, params) {
     const { store, handleCommand, startChat, onSessionEvent, getRole, defaultRoleId, logger } = deps;
-    return async function relayMessage(params) {
-        const { transportId, externalChatId, text, attachments, bridgeOptions } = 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) {
-            // 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 { 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
+        ? {
+            count: attachments.length,
+            mimeTypes: attachments.map((a) => a.mimeType),
         }
-        const commandResult = await handleCommand(text, transportId, chatState);
-        if (commandResult) {
+        : undefined;
+    logger.info("chat-service", "message received", {
+        transportId,
+        externalChatId,
+        textLength: text.length,
+        ...(attachmentSummary ? { attachments: attachmentSummary } : {}),
+    });
+    let chatState = await store.getChatState(transportId, externalChatId);
+    if (!chatState) {
+        // 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) {
+        // `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 };
         }
-        const result = await startChat({
-            message: text,
-            roleId: chatState.roleId,
-            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;
-            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),
-            });
+        if (commandResult.nextState)
+            chatState = commandResult.nextState;
+        text = commandResult.forwardAs;
+    }
+    const result = await startChat({
+        message: text,
+        roleId: chatState.roleId,
+        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;
+        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: "error",
-                status: 500,
-                message: "Error: failed to collect agent reply",
+                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 ────────────────────────────────────────────────
 // Resolve the role id to seed a NEW bridge chat state with. Prefers

package/dist/socket.d.ts

@@ -2,7 +2,7 @@ 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";
+import type { Attachment, Logger } from "./types.js";
 export declare const CHAT_SOCKET_PATH = "/ws/chat";
 /**
  * Custom socket.io events the chat transport defines. Keys mirror
@@ -43,4 +43,6 @@ 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 declare function parseAttachments(raw: unknown): Attachment[] | undefined;
+export declare function parseOneAttachment(item: unknown): Attachment | null;
 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";
 /**
@@ -237,7 +237,7 @@ function parseMessagePayload(payload) {
 // 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) {
+export function parseAttachments(raw) {
     if (!Array.isArray(raw) || raw.length === 0)
         return undefined;
     const valid = [];
@@ -245,23 +245,61 @@ function parseAttachments(raw) {
     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;
+        const entry = parseOneAttachment(item);
+        if (!entry)
+            continue;
+        if (entry.data) {
+            totalBytes += entry.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);
         }
+        valid.push(entry);
     }
     return valid.length > 0 ? valid : undefined;
 }
+// Accept either the inline `{ data, mimeType }` shape (bridges
+// shipping raw bytes) or the path-only `{ path }` shape (Vue UI and
+// any bridge that uploads to `data/attachments/` first). Either is
+// valid per the exported `Attachment` type. The earlier parser only
+// recognised the first shape, so a typed `{ path }` payload from a
+// socket client passed type-check but got silently dropped at the
+// wire boundary (#1050 review).
+//
+// Wire-boundary path guard: a malicious bridge can ship arbitrary
+// strings as `path`. The downstream `isAttachmentPath` enforcement
+// in the server is the authoritative gate, but defence-in-depth at
+// each layer is required for external code (#1099 review). Reject
+// absolute paths and any traversal segment up front so a payload
+// like `path: "../../etc/passwd"` never reaches the relay.
+// Windows-style drive-letter absolute path (`C:\…` or `C:/…`).
+// `isSafeAttachmentPath` rejects these too — a malicious bridge
+// can't ship a host-absolute path under any platform convention
+// (#1099 review iter-2).
+const WINDOWS_DRIVE_PATH_RE = /^[A-Za-z]:[\\/]/;
+function isSafeAttachmentPath(value) {
+    if (value.length === 0)
+        return false;
+    if (value.startsWith("/") || value.startsWith("\\"))
+        return false;
+    if (WINDOWS_DRIVE_PATH_RE.test(value))
+        return false;
+    for (const segment of value.split(/[/\\]/)) {
+        if (segment === "..")
+            return false;
+    }
+    return true;
+}
+export function parseOneAttachment(item) {
+    if (!item || typeof item !== "object")
+        return null;
+    const record = item;
+    const filename = typeof record.filename === "string" && record.filename.length > 0 ? record.filename : undefined;
+    if (typeof record.mimeType === "string" && typeof record.data === "string") {
+        return { mimeType: record.mimeType, data: record.data, ...(filename ? { filename } : {}) };
+    }
+    if (typeof record.path === "string" && isSafeAttachmentPath(record.path)) {
+        const mimeType = typeof record.mimeType === "string" ? record.mimeType : undefined;
+        return { path: record.path, ...(mimeType ? { mimeType } : {}), ...(filename ? { filename } : {}) };
+    }
+    return null;
+}

package/dist/types.d.ts

@@ -8,19 +8,42 @@ export interface Logger {
     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. */
+/** A file attached to a bridge or UI 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.
+ *
+ *  Either `data` (inline base64 bytes) or `path` (workspace-relative
+ *  path the server can read) MUST be set:
+ *
+ *    - Bridges over the socket transport ship raw bytes, so they
+ *      populate `data` (and usually `mimeType`).
+ *    - The Vue UI uploads paste/drop and sidebar-pick files to disk
+ *      before sending and populates `path`; the server reads bytes
+ *      from disk and infers `mimeType` from the extension.
+ *
+ *  Mirrors `@mulmobridge/protocol`'s `Attachment` (kept structurally
+ *  duplicated here per the package-contract rules in this file). */
 export interface Attachment {
-    mimeType: string;
-    data: string;
+    mimeType?: string;
+    data?: string;
+    path?: string;
     filename?: string;
 }
 export interface StartChatParams {
     message: string;
     roleId: string;
     chatSessionId: string;
+    /** Bridge-only legacy carrier for "the user picked this image".
+     *  No in-tree bridge populates this today; the field stays on the
+     *  type so external bridge clients on older protocol versions still
+     *  type-check. Only workspace paths are accepted — `data:` URLs
+     *  are no longer supported and the host app drops them with a
+     *  warn. Bridges that need to ship raw bytes should use the
+     *  modern `attachments[]` field with `{ mimeType, data }` entries;
+     *  the host app persists those to `data/attachments/YYYY/MM/`
+     *  server-side and rewrites them as path-bearing attachments
+     *  before any other processing. */
     selectedImageData?: string;
     attachments?: Attachment[];
     /** Session origin — application-defined (e.g. "human", "bridge") */
@@ -99,4 +122,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.4",
   "description": "Server-side chat service for MulmoBridge — socket.io + REST bridge to Claude Code agents",
   "type": "module",
   "main": "./dist/index.js",