@mulmobridge/protocol 0.1.4 → 1.0.1

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,54 @@ 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
+
+## Related projects
+
+Published from the MulmoClaude monorepo by [Receptron](https://github.com/receptron).
+
+- **[MulmoClaude](https://github.com/receptron/mulmoclaude)** — an open-source AI assistant platform that runs on your own computer. Claude Code as the engine, a personal wiki for long-term memory, schema-driven collections for your data, and chat that summons the right GUI (markdown, charts, forms, spreadsheets, wikis) for each task.
+- **[MulmoTerminal](https://github.com/receptron/mulmoterminal)** — a terminal-first cockpit for running many AI coding agents in parallel. One roster showing every session's summary and PR status, tmux-backed session persistence, git-worktree isolation, one-click PRs, and mobile push with remote reply.
+- **[MulmoTerminal manual](https://receptron.github.io/mulmoterminal/)** — setup, workflows, feature reference, configuration, mobile notifications, and alternative / local model providers. Available in English and Japanese.
+
 ## 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/socket.d.ts

@@ -29,7 +29,7 @@ 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/feat-bridge-options-passthrough.md`.
+ * callback. See `plans/done/feat-bridge-options-passthrough.md`.
  */
 export interface BridgeHandshakeAuth {
     transportId: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mulmobridge/protocol",
-  "version": "0.1.4",
+  "version": "1.0.1",
   "description": "Shared types and constants for the MulmoBridge protocol",
   "type": "module",
   "main": "./dist/index.js",
@@ -28,5 +28,22 @@
   "author": "Receptron Team",
   "devDependencies": {
     "typescript": "^6.0.3"
+  },
+  "homepage": "https://github.com/receptron/mulmoclaude/tree/main/packages/protocol#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/receptron/mulmoclaude.git",
+    "directory": "packages/protocol"
+  },
+  "keywords": [
+    "mulmobridge",
+    "protocol",
+    "socket.io",
+    "chat",
+    "ai-agent",
+    "types"
+  ],
+  "bugs": {
+    "url": "https://github.com/receptron/mulmoclaude/issues"
   }
 }