@mulmobridge/chat-service 0.1.3 → 0.1.6

package/dist/chat-state.d.ts

@@ -11,7 +11,15 @@ 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>;
+    /** Repoint the persisted chat state at another session. `roleId` is
+     *  optional: when omitted, the existing state's roleId is preserved
+     *  (the old default, kept for HTTP `/connect` callers that only know
+     *  the session ID). Callers that DO know the target session's role —
+     *  notably the `/switch` command, which already has `SessionSummary.roleId`
+     *  from `/sessions` — MUST pass it, otherwise the file-backed state
+     *  drifts into a stale-role / new-session pair and the next relay's
+     *  `startChat` uses the mismatched pair (issue #1888). */
+    connectSession(transportId: string, externalChatId: string, chatSessionId: string, roleId?: string): Promise<TransportChatState | null>;
     generateSessionId(transportId: string, externalChatId: string): string;
 }
 export declare function createChatStateStore(opts: {

package/dist/chat-state.js

@@ -57,13 +57,18 @@ export function createChatStateStore(opts) {
         });
         return state;
     };
-    const connectSession = async (transportId, externalChatId, chatSessionId) => {
+    const connectSession = async (transportId, externalChatId, chatSessionId, roleId) => {
         const existing = await getChatState(transportId, externalChatId);
         if (!existing)
             return null;
         const updated = {
             ...existing,
             sessionId: chatSessionId,
+            // A missing `roleId` arg means "preserve the current role" (that's
+            // the HTTP `/connect` route, which doesn't know the target's role);
+            // when the caller passes one (`/switch`), take theirs so state and
+            // downstream `startChat` agree on which role runs the resumed session.
+            ...(roleId !== undefined ? { roleId } : {}),
             updatedAt: new Date().toISOString(),
         };
         await setChatState(transportId, updated);
@@ -71,6 +76,7 @@ export function createChatStateStore(opts) {
             transportId,
             externalChatId,
             sessionId: chatSessionId,
+            roleId: updated.roleId,
         });
         return updated;
     };

package/dist/commands.d.ts

@@ -10,6 +10,32 @@ export interface CommandResult {
     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;

package/dist/commands.js

@@ -22,6 +22,40 @@ 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, listRegisteredSkills } = opts;
@@ -177,7 +211,12 @@ export function createCommandHandler(opts) {
                 };
             }
         }
-        const updated = await connectSession(transportId, chatState.externalChatId, target.id);
+        // Pass `target.roleId` so the persisted state's role tracks the session
+        // we just repointed at. Without this, `connectSession` would swap the
+        // sessionId but leave the previous role in place, and the next relay's
+        // `startChat` would run the resumed session under the wrong role
+        // (issue #1888).
+        const updated = await connectSession(transportId, chatState.externalChatId, target.id, target.roleId);
         if (!updated) {
             return { reply: "Failed to switch session." };
         }
@@ -224,15 +263,16 @@ export function createCommandHandler(opts) {
             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`.
+        // 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 [head, ...rest] = text.split(/\s+/);
-            const skillName = head.slice(2);
+            const { skillName, argsVerbatim } = parseSkillShortcut(text);
             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}`;
+                const forwardAs = argsVerbatim.length > 0 ? `/${skillName} ${argsVerbatim}` : `/${skillName}`;
                 return {
                     reply: `Session reset. Running ${forwardAs}`,
                     nextState,

package/dist/index.js

@@ -97,7 +97,31 @@ export function createChatService(deps) {
             badRequest(res, "chatSessionId is required");
             return;
         }
-        const updated = await store.connectSession(transportId, externalChatId, chatSessionId);
+        // Resolve the target session's role BEFORE calling connectSession so the
+        // persisted state's `roleId` tracks the new session's role — otherwise the
+        // next relay's `startChat` would resume the new session under the previous
+        // role (#1888 / #1894). Three fallback paths all treated as "preserve
+        // existing role":
+        //   1. No `getSessionRole` wired at all (backward compat for older hosts).
+        //   2. Resolver returns null (unknown / corrupt session metadata).
+        //   3. Resolver throws (host bug / timeout / IO error) — catch here so
+        //      the route can never bubble the failure as a 500 to the API caller
+        //      (codex review on #1895; the MulmoClaude host's resolver is
+        //      hardened but the DI contract doesn't require hosts to be).
+        let resolvedRole = null;
+        if (deps.getSessionRole) {
+            try {
+                resolvedRole = await deps.getSessionRole(chatSessionId);
+            }
+            catch (err) {
+                logger.warn("chat-service", "getSessionRole threw; falling back to preserving existing role", {
+                    chatSessionId,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+                resolvedRole = null;
+            }
+        }
+        const updated = await store.connectSession(transportId, externalChatId, chatSessionId, resolvedRole ?? undefined);
         if (!updated) {
             notFound(res, "No chat state found for this transport");
             return;

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.js

@@ -7,104 +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, 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),
-            }
-            : 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 };
-            }
-            if (commandResult.nextState)
-                chatState = commandResult.nextState;
-            text = commandResult.forwardAs;
+    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 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 };
+        : 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 };
         }
-        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

@@ -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,6 +122,17 @@ export interface ChatServiceDeps {
         }>;
         total: number;
     }>;
+    /**
+     * Resolve the roleId a given session was started with. Used by the HTTP
+     * `/connect` route so the persisted bridge state's role tracks the target
+     * session's role after a repoint — same drift-fix as bridge `/switch`
+     * (issue #1888 / #1894), but for API callers that only supply a session ID.
+     * Returns null when the session isn't found OR when its role isn't known;
+     * on null the route falls back to the previous "preserve current role"
+     * behaviour (safe default). Omit this dep entirely to keep the old
+     * session-id-only semantics.
+     */
+    getSessionRole?: (sessionId: string) => Promise<string | null>;
     /**
      * Return the skills the bridge command handler should expose. The
      * handler uses the result for two things:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mulmobridge/chat-service",
-  "version": "0.1.3",
+  "version": "0.1.6",
   "description": "Server-side chat service for MulmoBridge — socket.io + REST bridge to Claude Code agents",
   "type": "module",
   "main": "./dist/index.js",