@mulmobridge/protocol 0.1.3 → 1.0.0

package/README.md

@@ -18,7 +18,7 @@ npm install @mulmobridge/protocol
 | `CHAT_SOCKET_PATH` | Socket.io endpoint path (`"/ws/chat"`) |
 | `ChatSocketEvent` | Union type of socket event names |
 | `CHAT_SERVICE_ROUTES` | REST endpoint patterns for the bridge API |
-| `Attachment` | File attachment interface (`mimeType` + base64 `data` + optional `filename`) |
+| `Attachment` | File attachment interface — either inline base64 `data` or workspace `path`, with optional `mimeType`/`filename` |
 
 ## Usage
 
@@ -58,6 +58,47 @@ const attachment: Attachment = {
 | [@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  ← **this package**
+- [`@mulmobridge/chat-service`](https://www.npmjs.com/package/@mulmobridge/chat-service) — server-side relay + session store
+- [`@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/attachment.d.ts

@@ -1,8 +1,15 @@
 export interface Attachment {
-    /** IANA media type, e.g. "image/png". */
-    mimeType: string;
-    /** Raw base64-encoded payload (no `data:` prefix, no whitespace). */
-    data: string;
+    /** IANA media type, e.g. "image/png". Optional when only `path` is
+     *  set — the server infers the type from the path extension. */
+    mimeType?: string;
+    /** Raw base64-encoded payload (no `data:` prefix, no whitespace).
+     *  Required when `path` is not set. */
+    data?: string;
+    /** Workspace-relative path to a file the server can read. Required
+     *  when `data` is not set. Must live under one of the allowed roots
+     *  (e.g. `artifacts/images/...`, `data/attachments/...`); the
+     *  server enforces this with `safeResolve`. */
+    path?: string;
     /** Optional original filename. Untrusted — sanitise before use on disk. */
     filename?: string;
 }

package/dist/attachment.js

@@ -1,2 +1,18 @@
 // File attachment schema for chat messages (images, documents, etc.).
+//
+// One of `data` (inline base64 bytes) or `path` (workspace-relative
+// path) MUST be set. The two carriers exist because:
+//
+//   - Bridge clients (Telegram, LINE, Mastodon, ...) ship raw bytes
+//     over the wire, so they populate `data`.
+//   - The Vue UI uploads paste/drop and sidebar-pick images to disk
+//     before send (so the data layer is path-first), so it populates
+//     `path`. The server reads bytes from disk on receipt.
+//
+// Server-internal normalisation (e.g. `prepareRequestExtras` in the
+// agent route) loads bytes for path-only entries before downstream
+// consumers see the array, so anything reading `data` after that
+// boundary can rely on it being present. Outside that boundary
+// (i.e. when first received), readers MUST runtime-check which
+// carrier is set and handle the path case explicitly.
 export {};

package/dist/events.d.ts

@@ -1,10 +1,10 @@
 export declare const EVENT_TYPES: {
     readonly status: "status";
     readonly text: "text";
+    readonly skill: "skill";
     readonly toolCall: "tool_call";
     readonly toolCallResult: "tool_call_result";
     readonly toolResult: "tool_result";
-    readonly switchRole: "switch_role";
     readonly error: "error";
     readonly claudeSessionId: "claude_session_id";
     readonly sessionFinished: "session_finished";
@@ -27,6 +27,7 @@ export declare const GENERATION_KINDS: {
     readonly characterImage: "characterImage";
     readonly beatAudio: "beatAudio";
     readonly movie: "movie";
+    readonly pdf: "pdf";
 };
 export type GenerationKind = (typeof GENERATION_KINDS)[keyof typeof GENERATION_KINDS];
 export interface GenerationEvent {

package/dist/events.js

@@ -6,10 +6,18 @@
 export const EVENT_TYPES = {
     status: "status",
     text: "text",
+    // #1218 — assistant text whose content is the body of an invoked
+    // SKILL.md, synthesised by Claude CLI when the model calls the
+    // `Skill` tool. Tagged separately from `text` so the canvas can
+    // collapse it (skill bodies are huge and not actual prose).
+    // Detected server-side via the preceding tool_call's
+    // toolName === "Skill" (structural — survives Claude CLI body-text
+    // changes), then enriched with `skillName` / `skillScope` /
+    // `skillPath` resolved against `discoverSkills()`.
+    skill: "skill",
     toolCall: "tool_call",
     toolCallResult: "tool_call_result",
     toolResult: "tool_result",
-    switchRole: "switch_role",
     error: "error",
     claudeSessionId: "claude_session_id",
     sessionFinished: "session_finished",
@@ -31,6 +39,7 @@ export const GENERATION_KINDS = {
     characterImage: "characterImage",
     beatAudio: "beatAudio",
     movie: "movie",
+    pdf: "pdf",
 };
 /**
  * Stable map-key for a generation: the triple (kind, filePath, key).

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 export { EVENT_TYPES, type EventType, GENERATION_KINDS, type GenerationKind, type GenerationEvent, type PendingGeneration, generationKey } from "./events.js";
-export { CHAT_SOCKET_PATH, CHAT_SOCKET_EVENTS, type ChatSocketEvent } from "./socket.js";
+export { CHAT_SOCKET_PATH, CHAT_SOCKET_EVENTS, type ChatSocketEvent, type BridgeHandshakeAuth, type BridgeOptions } from "./socket.js";
 export { type Attachment } from "./attachment.js";
 export { CHAT_SERVICE_ROUTES } from "./routes.js";

package/dist/socket.d.ts

@@ -9,3 +9,30 @@ export declare const CHAT_SOCKET_EVENTS: {
     readonly textChunk: "textChunk";
 };
 export type ChatSocketEvent = (typeof CHAT_SOCKET_EVENTS)[keyof typeof CHAT_SOCKET_EVENTS];
+/**
+ * Bridge → host-app option bag carried on the handshake.
+ *
+ * Values are restricted to flat primitives (string / number /
+ * boolean). The restriction serves two purposes:
+ *
+ *   1. The wire contract is explicit — no surprise nested objects
+ *      slip through to the host app's callback where a downstream
+ *      merge might reintroduce prototype-pollution risk.
+ *   2. The scrape-from-env path produces strings anyway, so the
+ *      ceiling is already flat primitives in practice.
+ *
+ * Protocol does not interpret any keys — bridges and host apps agree
+ * on names (`defaultRole`, …) out of band.
+ */
+export type BridgeOptions = Readonly<Record<string, string | number | boolean>>;
+/**
+ * Shape of `socket.handshake.auth` on the bridge chat socket. The
+ * server validates `transportId` + `token`; `options` is the opaque-
+ * but-primitive bag forwarded to the host application's startChat
+ * callback. See `plans/done/feat-bridge-options-passthrough.md`.
+ */
+export interface BridgeHandshakeAuth {
+    transportId: string;
+    token?: string;
+    options?: BridgeOptions;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mulmobridge/protocol",
-  "version": "0.1.3",
+  "version": "1.0.0",
   "description": "Shared types and constants for the MulmoBridge protocol",
   "type": "module",
   "main": "./dist/index.js",