@mutirolabs/openclaw-brain 0.1.0

package/src/bridge-client.ts

@@ -0,0 +1,236 @@
+// NDJSON envelope codec + subprocess manager for the Mutiro chatbridge.
+// Ported from pi-brain's `createHostProcess` and `createBridgeClient`, kept
+// transport-shaped so the rest of the plugin can treat the bridge as a
+// request/response channel regardless of which brain is on the other side.
+
+import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process";
+import * as readline from "node:readline";
+
+import {
+  type BridgeEnvelope,
+  type BridgeExtras,
+  type PendingRequest,
+  PROTOCOL_VERSION,
+  TYPE_URLS,
+  generateId,
+} from "./bridge-protocol.js";
+
+export type BridgeLogger = {
+  info: (msg: string) => void;
+  warn: (msg: string) => void;
+  error: (msg: string) => void;
+};
+
+const defaultLogger: BridgeLogger = {
+  info: (msg) => console.log(`[openclaw-mutiro] ${msg}`),
+  warn: (msg) => console.warn(`[openclaw-mutiro] ${msg}`),
+  error: (msg) => console.error(`[openclaw-mutiro] ${msg}`),
+};
+
+export type HostProcessOptions = {
+  agentDir: string;
+  env?: NodeJS.ProcessEnv;
+  logger?: BridgeLogger;
+  onExit?: (code: number | null) => void;
+};
+
+// In bridge mode the Mutiro host writes slog JSON records to stderr. Parse
+// each line and route it through the OpenClaw channel logger so the output
+// matches the rest of the gateway's log stream instead of leaking the raw
+// Go-side format.
+const HOST_ATTR_DROP = new Set(["time", "level", "msg", "component", "agent_username"]);
+
+const formatAttrValue = (value: unknown): string => {
+  if (value === null || value === undefined) return "";
+  if (typeof value === "string") return value;
+  if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") {
+    return String(value);
+  }
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return String(value);
+  }
+};
+
+type NormalizedHostLog = { level: "info" | "warn" | "error"; text: string };
+
+const normalizeHostLogLine = (raw: string): NormalizedHostLog => {
+  const trimmed = raw.trim();
+  if (trimmed.startsWith("{") && trimmed.endsWith("}")) {
+    try {
+      const parsed = JSON.parse(trimmed) as Record<string, unknown>;
+      if (parsed && typeof parsed.msg === "string") {
+        const rawLevel = typeof parsed.level === "string" ? parsed.level.toLowerCase() : "info";
+        const level: NormalizedHostLog["level"] =
+          rawLevel === "error"
+            ? "error"
+            : rawLevel === "warn" || rawLevel === "warning"
+              ? "warn"
+              : "info";
+        const attrs = Object.entries(parsed)
+          .filter(([key]) => !HOST_ATTR_DROP.has(key))
+          .map(([key, value]) => `${key}=${formatAttrValue(value)}`)
+          .filter((entry) => entry.length > `=`.length + 1);
+        const detail = attrs.length > 0 ? ` ${attrs.join(" ")}` : "";
+        return { level, text: `host: ${parsed.msg}${detail}` };
+      }
+    } catch {
+      // fall through to raw passthrough
+    }
+  }
+  return { level: "info", text: `host: ${trimmed}` };
+};
+
+export const createHostProcess = (options: HostProcessOptions) => {
+  const logger = options.logger ?? defaultLogger;
+  const hostProcess = spawn("mutiro", ["agent", "host", "--mode=bridge"], {
+    cwd: options.agentDir,
+    env: options.env ?? process.env,
+  });
+
+  const stderrReader = readline.createInterface({
+    input: hostProcess.stderr,
+    terminal: false,
+  });
+  stderrReader.on("line", (line) => {
+    if (!line.trim()) return;
+    const { level, text } = normalizeHostLogLine(line);
+    if (level === "error") logger.error(text);
+    else if (level === "warn") logger.warn(text);
+    else logger.info(text);
+  });
+
+  hostProcess.on("exit", (code) => {
+    stderrReader.close();
+    logger.info(`mutiro host exited with code ${code}`);
+    options.onExit?.(code ?? null);
+  });
+
+  return hostProcess;
+};
+
+export type BridgeClient = {
+  send: (type: string, payload: unknown, extras?: BridgeExtras) => void;
+  request: <T = unknown>(type: string, payload: unknown, extras?: BridgeExtras) => Promise<T>;
+  ack: (requestId: string, payloadType: string) => void;
+  resolveResponse: (requestId: string | undefined, payload: unknown) => boolean;
+  rejectResponse: (requestId: string | undefined, error: unknown) => boolean;
+  sendError: (
+    requestId: string | undefined,
+    code: string,
+    message: string,
+    extras?: BridgeExtras,
+  ) => void;
+};
+
+export const createBridgeClient = (
+  hostProcess: ChildProcessWithoutNullStreams,
+): BridgeClient => {
+  // Bridge requests are ordinary NDJSON envelopes with request/response
+  // correlation on request_id. Visible chat replies are *not* the response to
+  // message.observed; they are separate outbound bridge requests.
+  const pendingRequests = new Map<string, PendingRequest>();
+
+  const send = (type: string, payload: unknown, extras: BridgeExtras = {}) => {
+    const envelope = {
+      protocol_version: PROTOCOL_VERSION,
+      type,
+      request_id: extras.request_id || generateId(),
+      payload,
+      ...extras,
+    };
+    hostProcess.stdin.write(`${JSON.stringify(envelope)}\n`);
+  };
+
+  const request = <T = unknown>(type: string, payload: unknown, extras: BridgeExtras = {}) =>
+    new Promise<T>((resolve, reject) => {
+      const requestId = generateId();
+      pendingRequests.set(requestId, {
+        resolve: resolve as (value: unknown) => void,
+        reject,
+      });
+      send(type, payload, { ...extras, request_id: requestId });
+    });
+
+  const ack = (requestId: string, payloadType: string) => {
+    // Acknowledge host-owned request delivery. This is separate from sending a
+    // user-visible message back into Mutiro.
+    send(
+      "command_result",
+      {
+        "@type": TYPE_URLS.bridgeCommandResult,
+        ok: true,
+        response: { "@type": payloadType },
+      },
+      { request_id: requestId },
+    );
+  };
+
+  const resolveResponse = (requestId: string | undefined, payload: unknown) => {
+    if (!requestId || !pendingRequests.has(requestId)) return false;
+    const pending = pendingRequests.get(requestId)!;
+    const resolved =
+      payload && typeof payload === "object" && "response" in (payload as Record<string, unknown>)
+        ? (payload as { response: unknown }).response
+        : payload;
+    pending.resolve(resolved);
+    pendingRequests.delete(requestId);
+    return true;
+  };
+
+  const rejectResponse = (requestId: string | undefined, error: unknown) => {
+    if (!requestId || !pendingRequests.has(requestId)) return false;
+    pendingRequests.get(requestId)!.reject(error);
+    pendingRequests.delete(requestId);
+    return true;
+  };
+
+  const sendError = (
+    requestId: string | undefined,
+    code: string,
+    message: string,
+    extras: BridgeExtras = {},
+  ) => {
+    if (!requestId) return;
+    const envelope = {
+      protocol_version: PROTOCOL_VERSION,
+      type: "error",
+      request_id: requestId,
+      error: { code, message },
+      ...extras,
+    };
+    hostProcess.stdin.write(`${JSON.stringify(envelope)}\n`);
+  };
+
+  return {
+    ack,
+    rejectResponse,
+    request,
+    resolveResponse,
+    send,
+    sendError,
+  };
+};
+
+export type EnvelopeHandler = (envelope: BridgeEnvelope) => void | Promise<void>;
+
+export const attachEnvelopeReader = (
+  hostProcess: ChildProcessWithoutNullStreams,
+  handler: EnvelopeHandler,
+  logger: BridgeLogger = defaultLogger,
+) => {
+  const rl = readline.createInterface({ input: hostProcess.stdout, terminal: false });
+
+  rl.on("line", async (line) => {
+    if (!line.trim()) return;
+    try {
+      const envelope = JSON.parse(line) as BridgeEnvelope;
+      await handler(envelope);
+    } catch (err) {
+      logger.error(`error processing bridge line: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  });
+
+  return rl;
+};

package/src/bridge-messages.ts

@@ -0,0 +1,307 @@
+// Message normalization helpers ported from pi-brain/mutiro-pi-bridge.ts.
+// The host delivers `envelope.payload.message` as a pre-normalized bag of parts;
+// these helpers turn that into plain text for the brain and into structured
+// ObservedTurn records for downstream dispatch.
+
+import type { ObservedTurn } from "./bridge-protocol.js";
+import { generateId } from "./bridge-protocol.js";
+
+const shortMessageId = (value?: string) => {
+  const id = (value || "").trim();
+  return id.length <= 8 ? id : id.slice(-8);
+};
+
+/**
+ * Converts a normalized bridge message into plain text for the LLM.
+ *
+ * The host delivers messages as `envelope.payload.message` with the following shape:
+ *
+ *   { text?: string, parts?: ChatBridgeMessagePart[], reply_to_message_id?: string, ... }
+ *
+ * `parts` is an array of flat objects, each carrying a `type` string discriminator.
+ * The host digests the raw wire format into this clean shape before delivery, so
+ * brain implementations only need to care about the fields documented below.
+ *
+ * Attachment bytes for `image` and `file` parts are downloaded by the host into
+ * `{agent_workspace}/Downloads/` before delivery. The local paths are conveyed
+ * separately via `envelope.payload.attachment_context`; see `buildObservedTurn`.
+ *
+ * @see https://docs.mutiro.com/chatbridge-protocol
+ */
+const REACTION_QUOTE_MAX_CHARS = 160;
+
+const truncateReactionQuote = (raw: string): string => {
+  const collapsed = raw.replace(/\s+/g, " ").trim();
+  if (!collapsed) return "";
+  if (collapsed.length <= REACTION_QUOTE_MAX_CHARS) return collapsed;
+  return `${collapsed.slice(0, REACTION_QUOTE_MAX_CHARS - 1).trimEnd()}…`;
+};
+
+/**
+ * Optional context carried on the envelope that lets extractors render
+ * richer text. Today: `replyToMessagePreview` comes from
+ * `ChatBridgeMessageObserved.reply_to_message_preview` — a host-resolved
+ * quote of the message referenced by `reply_to_message_id`. Used to turn
+ * bare `[reacted 👍 to #abc12345]` placeholders into readable events the
+ * model can reason about.
+ */
+export type BridgeMessageExtractionContext = {
+  replyToMessagePreview?: string;
+};
+
+export const extractBridgeMessageText = (
+  message?: {
+    text?: string;
+    parts?: Array<Record<string, unknown>>;
+    reply_to_message_id?: string;
+  },
+  context?: BridgeMessageExtractionContext,
+) => {
+  if (!message) return "";
+  const replyPreview = (context?.replyToMessagePreview ?? "").trim();
+
+  const parts: string[] = [];
+  const push = (value?: string) => {
+    const trimmed = (value || "").trim();
+    if (trimmed) parts.push(trimmed);
+  };
+
+  push(message.text);
+
+  for (const part of Array.isArray(message.parts) ? message.parts : []) {
+    if (!part || typeof part !== "object") continue;
+
+    const partType = (part as { type?: string }).type;
+    switch (partType) {
+      case "text":
+        push((part as { text?: string }).text);
+        break;
+      case "audio":
+        push((part as { transcript?: string }).transcript);
+        break;
+      case "card": {
+        const cardId = (part as { card_id?: string }).card_id;
+        push(cardId ? `[Interactive card: ${cardId}]` : "[Interactive card]");
+        break;
+      }
+      case "card_action": {
+        const p = part as { card_id?: string; action_id?: string; data_json?: string };
+        push(
+          `[Card interaction: card=${p.card_id || ""} action=${p.action_id || ""} data=${p.data_json || ""}]`,
+        );
+        break;
+      }
+      case "contact": {
+        const meta = ((part as { metadata?: Record<string, string> }).metadata || {}) as Record<
+          string,
+          string
+        >;
+        const username = (meta.contact_username || "").trim();
+        if (!username) break;
+        const displayName = (meta.contact_display_name || "").trim();
+        const role = (meta.contact_member_type || "").trim() === "agent" ? "agent" : "user";
+        push(`[Shared contact: ${displayName || username} (@${username}, ${role})]`);
+        break;
+      }
+      case "reaction": {
+        const p = part as { reaction?: string; reaction_operation?: string };
+        const emoji = (p.reaction || "").trim();
+        if (!emoji) break;
+        const removed = (p.reaction_operation || "").trim().toLowerCase() === "removed";
+        const quote = truncateReactionQuote(replyPreview);
+        if (quote) {
+          push(
+            removed
+              ? `[reaction ${emoji} removed from message: "${quote}"]`
+              : `[reaction ${emoji} received on message: "${quote}"]`,
+          );
+        } else {
+          const target = shortMessageId(message.reply_to_message_id);
+          if (removed) {
+            push(
+              target
+                ? `[removed reaction ${emoji} from #${target}]`
+                : `[removed reaction ${emoji}]`,
+            );
+          } else {
+            push(target ? `[reacted ${emoji} to #${target}]` : `[reacted ${emoji}]`);
+          }
+        }
+        break;
+      }
+      case "live_call": {
+        const p = part as {
+          summary_text?: string;
+          action_items?: string[];
+          follow_ups?: string[];
+          call_id?: string;
+          end_reason?: string;
+        };
+        const summary = (p.summary_text || "").trim();
+        const actionItems = Array.isArray(p.action_items)
+          ? p.action_items.map((item) => item.trim()).filter(Boolean)
+          : [];
+        const followUps = Array.isArray(p.follow_ups)
+          ? p.follow_ups.map((item) => item.trim()).filter(Boolean)
+          : [];
+        // Always emit at least the header — the part existing signals the
+        // call ended, even when summarization produced no text. Skipping
+        // here produces an empty turn text, and downstream that becomes a
+        // "no extractable content" drop. Symmetric to the host-side fix in
+        // chatbridge/normalize.go.
+        const lines = [
+          `[Voice call summary (call_id=${(p.call_id || "").trim()}, end_reason=${(p.end_reason || "").trim()})]`,
+        ];
+        if (summary) lines.push(summary);
+        if (actionItems.length > 0)
+          lines.push(`Action items:\n${actionItems.map((item) => `- ${item}`).join("\n")}`);
+        if (followUps.length > 0)
+          lines.push(`Follow-ups:\n${followUps.map((item) => `- ${item}`).join("\n")}`);
+        push(lines.join("\n"));
+        break;
+      }
+      case "image": {
+        const caption = (
+          ((part as { metadata?: Record<string, string> }).metadata || {}).caption || ""
+        ).trim();
+        push(caption ? `[Image attachment: ${caption}]` : "[Image attachment]");
+        break;
+      }
+      case "file": {
+        const filename = ((part as { filename?: string }).filename || "").trim();
+        const caption = (
+          ((part as { metadata?: Record<string, string> }).metadata || {}).caption || ""
+        ).trim();
+        push(
+          caption
+            ? `[File attachment: ${filename || "attachment"} — ${caption}]`
+            : `[File attachment: ${filename || "attachment"}]`,
+        );
+        break;
+      }
+    }
+  }
+
+  return parts.join(" ").trim();
+};
+
+export const normalizeOutputText = (value: string) => {
+  const trimmed = (value || "").trim();
+  const lowered = trimmed.toLowerCase();
+  if (!trimmed) return "";
+  if (lowered === "noop" || lowered === "noop.") return "";
+  return trimmed;
+};
+
+const cloneJson = <T>(value: T): T => JSON.parse(JSON.stringify(value));
+
+export const trimRecentMessages = <T>(messages: T[], max: number) =>
+  messages.length > max ? messages.slice(-max) : messages;
+
+export const buildSyntheticBridgeMessage = (params: {
+  conversationId: string;
+  replyToMessageId?: string;
+  senderUsername: string;
+  text: string;
+  metadata?: Record<string, string>;
+}) => ({
+  id: `openclaw-${generateId()}`,
+  conversation_id: params.conversationId,
+  reply_to_message_id: params.replyToMessageId || "",
+  from: {
+    username: params.senderUsername,
+  },
+  text: params.text,
+  metadata: params.metadata || {},
+});
+
+export const cloneMessage = <T>(message: T): T => cloneJson(message);
+
+/**
+ * Assembles a promptable ObservedTurn from an inbound host envelope.
+ *
+ * `extractBridgeMessageText(envelope.payload.message)` converts each message
+ * part (text, audio transcript, card placeholder, etc.) into inline plain text
+ * for the body.
+ *
+ * We intentionally do NOT glue `envelope.payload.attachment_context` onto the
+ * body. The host-authored description can carry stale or wrong metadata (for
+ * example "0x0 pixels" when its image probe fails) and, once real bytes are
+ * staged via MediaPaths, mixing it into Body confuses the model more than it
+ * helps. Callers that need the raw description can read it separately via
+ * `InboundMessage.attachmentContext`.
+ *
+ * Returns null if conversation/message ids are missing, or when both the text
+ * body and any inline image attachments are empty.
+ */
+export const buildObservedTurn = (envelope: {
+  conversation_id?: string;
+  message_id?: string;
+  reply_to_message_id?: string;
+  payload?: {
+    message?: {
+      conversation_id?: string;
+      id?: string;
+      reply_to_message_id?: string;
+      from?: { username?: string };
+      text?: string;
+      parts?: Array<Record<string, unknown>>;
+    };
+    reply_to_message_id?: string;
+    attachment_context?: string;
+    reply_to_message_preview?: string;
+    images?: unknown[];
+  };
+}): ObservedTurn | null => {
+  const conversationId = envelope.conversation_id || envelope.payload?.message?.conversation_id;
+  const messageId = envelope.message_id || envelope.payload?.message?.id;
+  const text = extractBridgeMessageText(envelope.payload?.message, {
+    replyToMessagePreview: envelope.payload?.reply_to_message_preview,
+  });
+  const hasAttachments =
+    Array.isArray(envelope.payload?.images) && (envelope.payload.images?.length ?? 0) > 0;
+
+  if (!conversationId || !messageId || (!text && !hasAttachments)) {
+    return null;
+  }
+
+  return {
+    conversationId,
+    messageId,
+    replyToMessageId:
+      envelope.reply_to_message_id ||
+      envelope.payload?.reply_to_message_id ||
+      envelope.payload?.message?.reply_to_message_id,
+    senderUsername: envelope.payload?.message?.from?.username || "unknown",
+    text,
+  };
+};
+
+export const isSelfEventMessage = (
+  envelope: { payload?: { message?: { from?: { username?: string } } } },
+  agentUsername: string,
+) => {
+  const senderUsername = envelope.payload?.message?.from?.username;
+  const selfUsername = (agentUsername || "").trim();
+  return !senderUsername || (!!selfUsername && senderUsername === selfUsername);
+};
+
+export const applyVoiceLanguage = (voiceName: string, language: string) => {
+  const trimmedVoice = voiceName.trim();
+  const trimmedLanguage = language.trim();
+  if (!trimmedVoice || !trimmedLanguage) {
+    return trimmedVoice;
+  }
+
+  const languageParts = trimmedLanguage.split("-");
+  if (languageParts.length < 2) {
+    return trimmedVoice;
+  }
+
+  const voiceParts = trimmedVoice.split("-");
+  if (voiceParts.length < 4) {
+    return trimmedVoice;
+  }
+
+  return `${languageParts[0]}-${languageParts[1]}-${voiceParts.slice(2).join("-")}`;
+};

package/src/bridge-protocol.ts

@@ -0,0 +1,77 @@
+// NDJSON protocol constants used by the Mutiro chatbridge envelope.
+// Ported verbatim from pi-brain/mutiro-pi-bridge.ts so that behavior matches
+// the reference adapter envelope-for-envelope.
+
+export const PROTOCOL_VERSION = "mutiro.agent.bridge.v1";
+
+export const TYPE_URLS = {
+  addReactionRequest: "type.googleapis.com/mutiro.messaging.AddReactionRequest",
+  bridgeCommandResult: "type.googleapis.com/mutiro.chatbridge.ChatBridgeCommandResult",
+  bridgeInitializeCommand: "type.googleapis.com/mutiro.chatbridge.ChatBridgeInitializeCommand",
+  bridgeMediaUploadCommand: "type.googleapis.com/mutiro.chatbridge.ChatBridgeMediaUploadCommand",
+  bridgeSendMessageCommand: "type.googleapis.com/mutiro.chatbridge.ChatBridgeSendMessageCommand",
+  bridgeSendVoiceMessageCommand: "type.googleapis.com/mutiro.chatbridge.ChatBridgeSendVoiceMessageCommand",
+  bridgeMessageObservedResult: "type.googleapis.com/mutiro.chatbridge.ChatBridgeMessageObservedResult",
+  bridgeSessionObservedResult: "type.googleapis.com/mutiro.chatbridge.ChatBridgeSessionObservedResult",
+  bridgeSessionSnapshotResult: "type.googleapis.com/mutiro.chatbridge.ChatBridgeSessionSnapshotResult",
+  bridgeSubscriptionSetCommand: "type.googleapis.com/mutiro.chatbridge.ChatBridgeSubscriptionSetCommand",
+  bridgeTaskResult: "type.googleapis.com/mutiro.chatbridge.ChatBridgeTaskResult",
+  bridgeTurnEndCommand: "type.googleapis.com/mutiro.chatbridge.ChatBridgeTurnEndCommand",
+  forwardMessageRequest: "type.googleapis.com/mutiro.messaging.ForwardMessageRequest",
+  recallGetRequest: "type.googleapis.com/mutiro.recall.RecallGetRequest",
+  recallSearchRequest: "type.googleapis.com/mutiro.recall.RecallSearchRequest",
+  sendSignalRequest: "type.googleapis.com/mutiro.signal.SendSignalRequest",
+} as const;
+
+export const DEFAULT_OPTIONAL_CAPABILITIES = [
+  "message.send_voice",
+  "signal.emit",
+  "recall.search",
+  "recall.get",
+  "media.upload",
+  // Advertising session.snapshot opts us into the live-call handoff: the
+  // host only sends ChatBridgeSessionSnapshotRequest to brains that
+  // declare support. Without this, our resolver never fires and the live
+  // voice model starts the call with no persona, no transcript, no tools.
+  "session.snapshot",
+  // Advertising task.request lets the host delegate one-shot prompts to
+  // the brain (e.g. scheduled reminders, background lookups). Our
+  // resolver runs the prompt against OpenClaw's agent and returns the
+  // accumulated reply text in the ChatBridgeTaskResult envelope.
+  "task.request",
+];
+
+export const MAX_RECENT_MESSAGES = 30;
+
+export type BridgeExtras = {
+  request_id?: string;
+  conversation_id?: string;
+  message_id?: string;
+  reply_to_message_id?: string;
+};
+
+export type ObservedTurn = {
+  conversationId: string;
+  messageId: string;
+  replyToMessageId?: string;
+  senderUsername: string;
+  text: string;
+};
+
+export type PendingRequest = {
+  resolve: (value: unknown) => void;
+  reject: (error: unknown) => void;
+};
+
+export type BridgeEnvelope = {
+  protocol_version: string;
+  type: string;
+  request_id?: string;
+  conversation_id?: string;
+  message_id?: string;
+  reply_to_message_id?: string;
+  payload?: Record<string, unknown>;
+  error?: { code?: string; message?: string };
+};
+
+export const generateId = () => Math.random().toString(36).substring(2, 15);