@mutirolabs/openclaw-brain 0.1.1 → 0.2.1

package/dist/src/signal-forwarder.js

@@ -0,0 +1,119 @@
+// Bridges OpenClaw's mid-turn reply-dispatch hooks into Mutiro's
+// signal.emit envelopes so the user sees a live "typing / searching /
+// remembering" indicator while the agent works. Fire-and-forget: signals
+// are transient UI chrome, not messages. No correlation required.
+//
+// Maps OpenClaw callbacks (from GetReplyOptions) to Mutiro's signal
+// vocabulary (SIGNAL_TYPE_* in spec/protobuf/shared/signal.proto).
+const REASONING_DEBOUNCE_MS = 500;
+const TOOL_DETAIL_MAX_CHARS = 120;
+const TOOL_SIGNAL_MAP = {
+    // Web
+    web_search: { signal: "SIGNAL_TYPE_WEB_SEARCHING", intent: "Searching web" },
+    web_fetch: { signal: "SIGNAL_TYPE_WEB_FETCHING", intent: "Fetching" },
+    fetch: { signal: "SIGNAL_TYPE_WEB_FETCHING", intent: "Fetching" },
+    // Memory / recall
+    recall: { signal: "SIGNAL_TYPE_RECALLING", intent: "Recalling" },
+    memory_search: { signal: "SIGNAL_TYPE_RECALLING", intent: "Searching memory" },
+    memory: { signal: "SIGNAL_TYPE_READING_MEMORY", intent: "Reading memory" },
+    memory_remember: { signal: "SIGNAL_TYPE_WRITING_MEMORY", intent: "Saving memory" },
+    memory_write: { signal: "SIGNAL_TYPE_WRITING_MEMORY", intent: "Saving memory" },
+    // Media
+    image_generate: { signal: "SIGNAL_TYPE_CREATING_IMAGE", intent: "Creating image" },
+    image: { signal: "SIGNAL_TYPE_CREATING_IMAGE", intent: "Working with image" },
+    // Scheduling / planning
+    cron: { signal: "SIGNAL_TYPE_SCHEDULING", intent: "Scheduling" },
+    update_plan: { signal: "SIGNAL_TYPE_CUSTOM", intent: "Updating plan" },
+    // Mutiro-native channel tools
+    mutiro_send_voice_message: { signal: "SIGNAL_TYPE_SENDING_VOICE", intent: "Sending voice" },
+    mutiro_send_card: { signal: "SIGNAL_TYPE_ATTACHING_FILE", intent: "Preparing card" },
+    mutiro_forward_message: { signal: "SIGNAL_TYPE_CUSTOM", intent: "Forwarding message" },
+    // File operations (coding profile). Mutiro has no dedicated SIGNAL_TYPE_*
+    // for file I/O; use CUSTOM + readable intent so the user still sees the
+    // action. Phase (e.g. the path being touched) is appended when present.
+    read: { signal: "SIGNAL_TYPE_CUSTOM", intent: "Reading file" },
+    write: { signal: "SIGNAL_TYPE_CUSTOM", intent: "Writing file" },
+    edit: { signal: "SIGNAL_TYPE_CUSTOM", intent: "Editing file" },
+    apply_patch: { signal: "SIGNAL_TYPE_CUSTOM", intent: "Applying patch" },
+    // Shell / process
+    exec: { signal: "SIGNAL_TYPE_CUSTOM", intent: "Running command" },
+    bash: { signal: "SIGNAL_TYPE_CUSTOM", intent: "Running command" },
+    process: { signal: "SIGNAL_TYPE_CUSTOM", intent: "Managing process" },
+    // UI surfaces
+    canvas: { signal: "SIGNAL_TYPE_CUSTOM", intent: "Updating canvas" },
+    browser: { signal: "SIGNAL_TYPE_CUSTOM", intent: "Browsing" },
+    // Sessions / control plane
+    sessions_list: { signal: "SIGNAL_TYPE_CUSTOM", intent: "Listing sessions" },
+    sessions_history: { signal: "SIGNAL_TYPE_CUSTOM", intent: "Reading history" },
+    sessions_send: { signal: "SIGNAL_TYPE_CUSTOM", intent: "Sending to session" },
+    session_status: { signal: "SIGNAL_TYPE_CUSTOM", intent: "Checking status" },
+    message: { signal: "SIGNAL_TYPE_CUSTOM", intent: "Messaging" },
+};
+const truncateDetail = (raw) => {
+    const collapsed = raw.replace(/\s+/g, " ").trim();
+    if (collapsed.length <= TOOL_DETAIL_MAX_CHARS)
+        return collapsed;
+    return `${collapsed.slice(0, TOOL_DETAIL_MAX_CHARS - 1).trimEnd()}…`;
+};
+export const createSignalForwarder = (session, target) => {
+    let lastReasoningAt = 0;
+    const emit = (signalType, detail) => {
+        session.outbound.emitSignal(target, signalType, detail ?? "");
+    };
+    return {
+        thinking: () => emit("SIGNAL_TYPE_THINKING", "Processing…"),
+        typing: () => emit("SIGNAL_TYPE_TYPING", "Writing response…"),
+        reasoning: () => {
+            // onReasoningStream fires per-token; throttle so we ship at most one
+            // REASONING pulse every REASONING_DEBOUNCE_MS to avoid spamming the
+            // host + Mutiro clients.
+            const now = Date.now();
+            if (now - lastReasoningAt < REASONING_DEBOUNCE_MS)
+                return;
+            lastReasoningAt = now;
+            emit("SIGNAL_TYPE_REASONING", "Thinking…");
+        },
+        toolStart: (name, _phase) => {
+            const trimmedName = (name ?? "").trim();
+            if (!trimmedName) {
+                emit("SIGNAL_TYPE_TOOL_RUNNING");
+                return;
+            }
+            // `onToolStart.phase` is a lifecycle marker ("start"/"update"/"end"),
+            // not semantic payload — ignore it. Tools with args (read, write,
+            // exec, etc.) fire a follow-up `onItemEvent` whose `title` carries
+            // the real detail (e.g. "read src/x.ts"); itemEvent() refines the
+            // pill to that value. For tools that never emit an item event, the
+            // intent label alone is still meaningful.
+            const spec = TOOL_SIGNAL_MAP[trimmedName];
+            const intent = spec?.intent ?? trimmedName;
+            emit(spec?.signal ?? "SIGNAL_TYPE_CUSTOM", truncateDetail(intent));
+        },
+        itemStart: (params) => {
+            // Higher-fidelity source than toolStart: title resolves tool args
+            // into a display ("read src/x.ts", "exec pytest -k foo", etc.) via
+            // OpenClaw's inferToolMetaFromArgs. When we have both the tool
+            // signal type AND the rich title, emit with the specific signal
+            // type so the UI still shows the right pill style.
+            const name = (params.name ?? "").trim();
+            const title = (params.title ?? "").trim();
+            if (!name && !title)
+                return;
+            const spec = name ? TOOL_SIGNAL_MAP[name] : undefined;
+            const detail = truncateDetail(title || spec?.intent || name);
+            emit(spec?.signal ?? "SIGNAL_TYPE_CUSTOM", detail);
+        },
+        compactionStart: () => emit("SIGNAL_TYPE_REMEMBERING", "Organizing context…"),
+        compactionEnd: () => {
+            // No explicit clear — the next signal (or TURN_COMPLETE) replaces the
+            // visible pill on Mutiro clients.
+        },
+        planUpdate: (title) => {
+            const detail = (title ?? "").trim();
+            emit("SIGNAL_TYPE_CUSTOM", detail ? `Planning: ${truncateDetail(detail)}` : "Planning…");
+        },
+        custom: (detail) => emit("SIGNAL_TYPE_CUSTOM", truncateDetail(detail)),
+        turnComplete: () => emit("SIGNAL_TYPE_TURN_COMPLETE"),
+    };
+};
+//# sourceMappingURL=signal-forwarder.js.map

package/dist/src/signal-forwarder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"signal-forwarder.js","sourceRoot":"","sources":["../../src/signal-forwarder.ts"],"names":[],"mappings":"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"}

package/docs/guides/manage-allowlist.md

@@ -15,9 +15,9 @@ Copy the prompt below into your AI assistant (Claude, Cursor, Windsurf, or simil
 
 ````
 You are helping me manage who can message my Mutiro agent. My agent is driven
-by OpenClaw over `chatbridge`, so there are two allowlists. The Mutiro backend
-allowlist is the authoritative gate — denied users are blocked at the server.
-The OpenClaw allowFrom is a second filter on top.
+by OpenClaw via the Mutiro Channel extension, so there are two allowlists.
+The Mutiro backend allowlist is the authoritative gate — denied users are
+blocked at the server. The OpenClaw `allowFrom` is a second filter on top.
 
 Be proactive — inspect current state before changing anything, and confirm
 destructive changes (especially `set` calls that replace the whole list).

package/docs/guides/use-openclaw-as-brain.md

@@ -1,11 +1,11 @@
 # Use OpenClaw as the Brain for Your Mutiro Agent
 
-Copy the prompt below into your AI assistant (Claude, Cursor, Windsurf, or similar) and it will walk you through pointing [OpenClaw](https://openclaw.ai) at a [Mutiro](https://mutiro.com) agent through `chatbridge`. Mutiro stays the messaging platform; OpenClaw becomes the brain.
+Copy the prompt below into your AI assistant (Claude, Cursor, Windsurf, or similar) and it will walk you through pointing [OpenClaw](https://openclaw.ai) at a [Mutiro](https://mutiro.com) agent via the Mutiro Channel extension. Mutiro stays the messaging platform; OpenClaw becomes the brain.
 
 ## The Prompt
 
 ````
-You are helping me run an existing Mutiro agent with OpenClaw as its brain over `chatbridge`. Mutiro keeps the agent identity, connectivity, messaging, auth, and media plumbing. OpenClaw becomes the thinking layer and drives outbound replies through the bridge.
+You are helping me run an existing Mutiro agent with OpenClaw as its brain, connected through the Mutiro Channel extension for OpenClaw. Mutiro keeps the agent identity, connectivity, messaging, auth, and media plumbing. OpenClaw becomes the thinking layer and drives outbound replies through the Mutiro Channel.
 
 Walk me through this step by step. Be proactive — run commands, check outputs, and make smart decisions based on what you find. Don't ask me things you can figure out by running a command. Only pause to ask when you genuinely need my input (like which LLM provider to use or what personality I want). When you need my input, ask me directly and wait for my response.
 
@@ -17,7 +17,7 @@ Walk me through this step by step. Be proactive — run commands, check outputs,
 
 This guide assumes I already have a working Mutiro agent directory. If I don't, stop and point me at the Mutiro create-agent guide first:
 
-> https://www.mutiro.com/docs/guides/create-agent.md
+> https://www.mutiro.com/docs/guides/create-agent
 
 Check what's already set up:
 
@@ -84,9 +84,9 @@ openclaw doctor
 
 ---
 
-### Step 4: Install the openclaw-brain Plugin
+### Step 4: Install the Mutiro Channel extension
 
-This plugin is the piece that lets OpenClaw speak Mutiro's `chatbridge`. It spawns `mutiro agent host --mode=bridge` as a subprocess and translates NDJSON envelopes into OpenClaw inbound messages and outbound send/react/forward/voice/card/forward calls.
+This extension is the piece that lets OpenClaw drive a Mutiro agent. It spawns `mutiro agent host --mode=bridge` as a subprocess and translates the Mutiro Channel protocol into OpenClaw inbound messages and outbound send/react/forward/voice/card calls.
 
 Install from the published package:
 
@@ -105,15 +105,15 @@ cd ~/src/openclaw-brain
 openclaw plugins install --dangerously-force-unsafe-install "file:$(pwd)"
 ```
 
-**About `--dangerously-force-unsafe-install`**: this plugin legitimately
-spawns `mutiro agent host --mode=bridge` as a subprocess — that is the
-entire `chatbridge` adapter. OpenClaw's install scanner correctly flags any
-plugin that uses `child_process` as sensitive and requires this flag as an
-explicit acknowledgement. Before you pass it, confirm you are installing
-from the signed [`mutirolabs/openclaw-brain`](https://github.com/mutirolabs/openclaw-brain)
+**About `--dangerously-force-unsafe-install`**: this extension legitimately
+spawns `mutiro agent host --mode=bridge` as a subprocess — that is how the
+Mutiro Channel carries traffic. OpenClaw's install scanner correctly flags
+any extension that uses `child_process` as sensitive and requires this flag
+as an explicit acknowledgement. Before you pass it, confirm you are
+installing from the signed [`mutirolabs/openclaw-brain`](https://github.com/mutirolabs/openclaw-brain)
 source (or the `@mutirolabs/openclaw-brain` npm package). Review the
 `spawn` call at [`src/bridge-client.ts`](https://github.com/mutirolabs/openclaw-brain/blob/main/src/bridge-client.ts)
-if you want to see exactly what the plugin executes.
+if you want to see exactly what the extension executes.
 
 Verify OpenClaw sees the channel:
 
@@ -320,9 +320,9 @@ Restart with `openclaw gateway run` after any config change.
 
 ### Step 12: Signals and Live Call Handoff
 
-OpenClaw's tool activity is forwarded to Mutiro as bridge signals, so Mutiro surfaces "thinking", "web searching", "recalling", "sending voice", etc. in real time while the agent works. The plugin maps 26 OpenClaw tool names to Mutiro `SignalType` enums; anything outside the map falls back to `SIGNAL_TYPE_CUSTOM` with a detail label.
+OpenClaw's tool activity is forwarded to Mutiro as channel signals, so Mutiro surfaces "thinking", "web searching", "recalling", "sending voice", etc. in real time while the agent works. The extension maps 26 OpenClaw tool names to Mutiro `SignalType` enums; anything outside the map falls back to `SIGNAL_TYPE_CUSTOM` with a detail label.
 
-For live voice calls, Mutiro sends `task.request` with a compact observed-turn payload and expects a plain-text result. The plugin handles this by accumulating the agent's reply text and returning it as `ChatBridgeTaskResult.text`. It also answers `session.snapshot` from recent messages cached per-conversation so Mutiro can bootstrap the live lane.
+For live voice calls, Mutiro sends `task.request` with a compact observed-turn payload and expects a plain-text result. The extension accumulates the agent's reply text and returns it as the task result. It also answers `session.snapshot` from recent messages cached per-conversation so Mutiro can bootstrap the live lane.
 
 Voice call **summaries** flow as normal `message.observed` envelopes tagged `live_call`. OpenClaw treats them as regular inbound turns — nothing extra to configure.
 
@@ -396,6 +396,6 @@ Help me review OpenClaw's `tools.profile` / `tools.alsoAllow` and the Mutiro `al
 **Docs:**
 - OpenClaw: https://openclaw.ai
 - Mutiro: https://mutiro.com
-- Create a Mutiro agent: https://www.mutiro.com/docs/guides/create-agent.md
+- Create a Mutiro agent: https://www.mutiro.com/docs/guides/create-agent
 - openclaw-brain repo: https://github.com/mutirolabs/openclaw-brain
 ````

package/index.ts

@@ -12,7 +12,7 @@ import { defineBundledChannelEntry } from "openclaw/plugin-sdk/channel-entry-con
 export default defineBundledChannelEntry({
   id: "mutiro",
   name: "Mutiro",
-  description: "Mutiro chatbridge channel plugin",
+  description: "The official Mutiro Channel extension for OpenClaw.",
   importMetaUrl: import.meta.url,
   plugin: {
     specifier: "./src/channel.js",

package/openclaw.plugin.json

@@ -1,9 +1,6 @@
 {
   "id": "mutiro",
   "channels": ["mutiro"],
-  "channelEnvVars": {
-    "mutiro": ["MUTIRO_AGENT_API_KEY"]
-  },
   "configSchema": {
     "type": "object",
     "additionalProperties": false,
@@ -24,6 +21,11 @@
       "enabled": {
         "type": "boolean"
       },
+      "replyToMode": {
+        "type": "string",
+        "enum": ["off", "first", "all", "batched"],
+        "description": "How the agent's outbound messages thread under the inbound one. Default: \"first\" (quote the inbound on the first agent reply, then free-standing follow-ups)."
+      },
       "accounts": {
         "type": "object",
         "additionalProperties": {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mutirolabs/openclaw-brain",
-  "version": "0.1.1",
-  "description": "OpenClaw channel plugin that drives a Mutiro agent over chatbridge. OpenClaw becomes the brain; Mutiro stays the messaging surface.",
+  "version": "0.2.1",
+  "description": "The official Mutiro Channel extension for OpenClaw. OpenClaw is the brain; Mutiro is the messaging surface, identity, and state.",
   "type": "module",
   "license": "ISC",
   "repository": {
@@ -14,21 +14,23 @@
   },
   "scripts": {
     "check": "tsc -p tsconfig.json --noEmit",
+    "clean": "rm -rf dist",
+    "build": "npm run clean && tsc -p tsconfig.build.json",
     "gateway": "openclaw gateway run",
-    "prepublishOnly": "npm run check"
+    "prepublishOnly": "npm run check && npm run build"
   },
   "publishConfig": {
     "access": "public"
   },
   "keywords": [
     "mutiro",
-    "chatbridge",
     "openclaw",
     "channel",
-    "plugin",
+    "extension",
     "agent"
   ],
   "files": [
+    "dist",
     "index.ts",
     "src",
     "docs",
@@ -63,10 +65,10 @@
     "channel": {
       "id": "mutiro",
       "label": "Mutiro",
-      "selectionLabel": "Mutiro (plugin)",
+      "selectionLabel": "Mutiro",
       "docsPath": "/channels/mutiro",
       "docsLabel": "mutiro",
-      "blurb": "chatbridge channel; configure a Mutiro agent directory to enable.",
+      "blurb": "Official Mutiro Channel for OpenClaw. Point at a Mutiro agent directory to enable.",
       "order": 80,
       "quickstartAllowFrom": true
     },

package/src/agent-tools.ts

@@ -1,7 +1,7 @@
 // Channel-owned agent tools. Exposed to OpenClaw's agent loop via
-// `ChannelPlugin.agentTools`. The first one mirrors pi-brain's
-// `send_voice_message`: a text-to-speech voice message delivered through the
-// bridge's `message.send_voice` command (host-side TTS, not client-side).
+// `ChannelPlugin.agentTools`. The first one is a text-to-speech voice
+// message delivered through the bridge's `message.send_voice` command
+// (host-side TTS, not client-side).
 
 import { Type } from "@sinclair/typebox";
 import type { ChannelAgentTool } from "openclaw/plugin-sdk/channel-contract";

package/src/bridge-client.ts

@@ -1,6 +1,5 @@
 // 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
+// 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";

package/src/bridge-messages.ts

@@ -1,5 +1,5 @@
-// Message normalization helpers ported from pi-brain/mutiro-pi-bridge.ts.
-// The host delivers `envelope.payload.message` as a pre-normalized bag of parts;
+// Message normalization helpers for inbound bridge envelopes. 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.
 

package/src/bridge-protocol.ts

@@ -1,6 +1,6 @@
 // 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.
+// These type URLs and helpers mirror the Mutiro bridge's protobuf surface
+// envelope-for-envelope.
 
 export const PROTOCOL_VERSION = "mutiro.agent.bridge.v1";
 

package/src/bridge-session.ts

@@ -1,7 +1,7 @@
 // Long-lived bridge session: owns the subprocess, performs the handshake,
 // dispatches inbound envelopes, and keeps a narrow per-conversation cache for
-// `session.snapshot`. Ported from pi-brain's `main()` but restructured so the
-// OpenClaw plugin runtime can start/stop it per configured account.
+// `session.snapshot`. Structured so the OpenClaw plugin runtime can
+// start/stop one session per configured Mutiro account.
 
 import type { ChildProcessWithoutNullStreams } from "node:child_process";
 

package/src/channel.runtime.ts

@@ -30,6 +30,16 @@ type StartContext = ChannelGatewayContext<ResolvedMutiroAccount>;
 
 const sessions = new Map<string, BridgeSession>();
 
+// Crash-backoff state per account. Repeated crashes escalate the delay so we
+// don't thrash the gateway's restart loop when the host is consistently
+// failing (bad config, missing credential, host crash on boot, etc.). The
+// streak resets when the last crash is older than `CRASH_STREAK_RESET_MS`,
+// so a host that ran healthy for a while then crashed once starts over at
+// the shortest backoff.
+const CRASH_BACKOFF_MS = [1_000, 2_000, 5_000, 15_000, 60_000];
+const CRASH_STREAK_RESET_MS = 5 * 60_000;
+const crashState = new Map<string, { count: number; lastCrashAt: number }>();
+
 const sessionKey = (channel: string, accountId: string) => `${channel}:${accountId}`;
 
 const requireSessionForAccount = (accountId: string | null | undefined): BridgeSession => {
@@ -299,14 +309,55 @@ export const startMutiroAccount = async (ctx: StartContext) => {
       : undefined,
     onHostExit: (code) => {
       sessions.delete(key);
-      ctx.log?.info?.(`mutiro: host (${ctx.accountId}) exited with code ${code}`);
+      const now = Date.now();
+      const isAbort = ctx.abortSignal.aborted;
+      const isCleanExit = code === 0 || isAbort;
+
+      if (isCleanExit) {
+        crashState.delete(ctx.accountId);
+        ctx.log?.info?.(
+          `mutiro: host (${ctx.accountId}) exited with code ${code}${isAbort ? " (abort)" : ""}`,
+        );
+        ctx.setStatus({
+          ...ctx.getStatus(),
+          running: false,
+          connected: false,
+          lastDisconnect: { at: now, status: code ?? undefined },
+        });
+        settleLifecycle();
+        return;
+      }
+
+      // Unexpected exit: track the streak, compute backoff, and hold the
+      // lifecycle promise until the delay elapses. The gateway's restart
+      // loop won't fire until we settle, so this delay is the effective
+      // backoff without touching gateway internals.
+      const prior = crashState.get(ctx.accountId);
+      const streak =
+        prior && now - prior.lastCrashAt < CRASH_STREAK_RESET_MS ? prior.count + 1 : 1;
+      crashState.set(ctx.accountId, { count: streak, lastCrashAt: now });
+
+      const delayMs = CRASH_BACKOFF_MS[Math.min(streak - 1, CRASH_BACKOFF_MS.length - 1)];
+      ctx.log?.warn?.(
+        `mutiro: host (${ctx.accountId}) exited unexpectedly with code ${code}; ` +
+          `restarting in ${Math.round(delayMs / 1000)}s (attempt ${streak})`,
+      );
       ctx.setStatus({
         ...ctx.getStatus(),
         running: false,
         connected: false,
-        lastDisconnect: { at: Date.now(), status: code ?? undefined },
+        restartPending: true,
+        reconnectAttempts: streak,
+        lastDisconnect: {
+          at: now,
+          status: code ?? undefined,
+          error: `exit_code=${code ?? "null"}`,
+        },
       });
-      settleLifecycle();
+
+      setTimeout(() => {
+        settleLifecycle();
+      }, delayMs);
     },
   });
 

package/src/channel.ts

@@ -8,10 +8,13 @@
 import type {
   ChannelOutboundAdapter,
   ChannelPlugin,
+  OpenClawConfig,
 } from "openclaw/plugin-sdk/core";
 import { createChatChannelPlugin } from "openclaw/plugin-sdk/core";
 import { createLazyRuntimeNamedExport } from "openclaw/plugin-sdk/lazy-runtime";
 
+type ReplyToMode = "off" | "first" | "all" | "batched";
+
 import { mutiroMessageActions } from "./actions.js";
 import { mutiroAgentTools } from "./agent-tools.js";
 import { mutiroConfigAdapter, type ResolvedMutiroAccount } from "./config.js";
@@ -43,6 +46,23 @@ const outbound: ChannelOutboundAdapter = {
   },
 };
 
+// Read `channels.mutiro.replyToMode` as an override; otherwise default to
+// `"first"` so the agent's first reply in a turn threads under the inbound
+// message. Mutiro clients render reply-to as a visible quoted pill, so this
+// anchors context nicely in groups without being noisy in DMs. Set
+// `channels.mutiro.replyToMode` to `"off"`, `"all"`, or `"batched"` in the
+// OpenClaw config to override.
+const resolveMutiroReplyToMode = ({ cfg }: { cfg: OpenClawConfig }): ReplyToMode => {
+  const section = (cfg as { channels?: Record<string, unknown> }).channels?.mutiro as
+    | { replyToMode?: unknown }
+    | undefined;
+  const configured = section?.replyToMode;
+  if (configured === "off" || configured === "first" || configured === "all" || configured === "batched") {
+    return configured;
+  }
+  return "first";
+};
+
 export const mutiroPlugin: ChannelPlugin<ResolvedMutiroAccount> = createChatChannelPlugin<
   ResolvedMutiroAccount
 >({
@@ -51,10 +71,10 @@ export const mutiroPlugin: ChannelPlugin<ResolvedMutiroAccount> = createChatChan
     meta: {
       id: "mutiro",
       label: "Mutiro",
-      selectionLabel: "Mutiro (plugin)",
+      selectionLabel: "Mutiro",
       docsPath: "/channels/mutiro",
       docsLabel: "mutiro",
-      blurb: "chatbridge channel; configure a Mutiro agent directory to enable.",
+      blurb: "Official Mutiro Channel for OpenClaw. Point at a Mutiro agent directory to enable.",
       order: 80,
       quickstartAllowFrom: true,
       markdownCapable: true,
@@ -125,6 +145,45 @@ export const mutiroPlugin: ChannelPlugin<ResolvedMutiroAccount> = createChatChan
         await runtime.stopMutiroAccount(ctx);
       },
     },
+
+    // Status adapter: answers `openclaw channels status mutiro`. The runtime
+    // already updates `running` / `connected` / `lastConnectedAt` /
+    // `reconnectAttempts` via `ctx.setStatus()` when the bridge subprocess
+    // starts, handshakes, exits, or is in backoff. Here we just enrich the
+    // snapshot with Mutiro-specific context (agent workspace path, bridge
+    // mode, derived health string).
+    status: {
+      buildAccountSnapshot: ({ account, runtime }) => {
+        const base = runtime ?? { accountId: account.accountId };
+        const running = base.running ?? false;
+        const connected = base.connected ?? false;
+        const restartPending = base.restartPending ?? false;
+        const healthState = !running
+          ? restartPending
+            ? "restarting"
+            : "stopped"
+          : connected
+            ? "healthy"
+            : "connecting";
+        return {
+          ...base,
+          accountId: account.accountId,
+          configured: account.configured,
+          enabled: account.enabled,
+          mode: "bridge",
+          healthState,
+          dbPath: account.config.agentDir ?? null,
+        };
+      },
+    },
+  },
+  // Threading adapter: Mutiro natively supports `reply_to_message_id`, so wire
+  // OpenClaw's reply-dispatch into it. `allowExplicitReplyTagsWhenOff` keeps
+  // agent-directed reply markers working even when the user has disabled
+  // automatic reply-threading.
+  threading: {
+    resolveReplyToMode: resolveMutiroReplyToMode,
+    allowExplicitReplyTagsWhenOff: true,
   },
   outbound,
 });

package/src/outbound.ts

@@ -1,8 +1,7 @@
 // Outbound adapter that translates OpenClaw reply-dispatch calls into
-// bridge-local commands. Mirrors pi-brain's tool surface (send_message,
-// send_voice_message, send_card, react_to_message, send_file_message,
-// forward_message, recall, recall_get) but reshaped so OpenClaw's
-// ChannelOutboundAdapter is the consumer instead of a Pi tool runtime.
+// bridge-local commands: send_message, send_voice_message, send_card,
+// react_to_message, send_file_message, forward_message, recall,
+// recall_get. Shaped around OpenClaw's ChannelOutboundAdapter contract.
 
 import * as path from "node:path";
 
@@ -112,9 +111,8 @@ const buildCardJson = (
 
   return {
     // Field names must match Mutiro's CardPart protobuf schema (see
-    // spec/protobuf/shared/messaging.proto). pi-brain uses stale names
-    // (`json_data` / `version`) which the host's strict JSON-to-proto
-    // decoder rejects as unknown fields.
+    // spec/protobuf/shared/messaging.proto). The host's strict JSON-to-proto
+    // decoder rejects unknown field names like `json_data` / `version`.
     a2ui_json: lines.join("\n"),
     schema_version: "0.8",
     card_id: cardId || `openclaw-card-${Math.random().toString(36).slice(2, 10)}`,

package/src/setup-surface.ts

@@ -26,7 +26,7 @@ import { listMutiroAccountIds, resolveMutiroAccount } from "./config.js";
 
 const channel = "mutiro" as const;
 const INSTALL_URL = "https://mutiro.com/downloads/install.sh";
-const CREATE_AGENT_GUIDE = "https://www.mutiro.com/docs/guides/create-agent.md";
+const CREATE_AGENT_GUIDE = "https://www.mutiro.com/docs/guides/create-agent";
 
 const MUTIRO_INTRO_LINES = [
   "Point OpenClaw at an existing Mutiro agent directory.",
@@ -167,7 +167,7 @@ export const mutiroSetupWizard: ChannelSetupWizard = {
     resolveExtraStatusLines: ({ cfg }) => [`Accounts: ${listMutiroAccountIds(cfg).length || 0}`],
   }),
   introNote: {
-    title: "Mutiro chatbridge setup",
+    title: "Mutiro Channel setup",
     lines: MUTIRO_INTRO_LINES,
   },
   prepare: async ({ prompter }) => {
@@ -225,25 +225,53 @@ export const mutiroSetupWizard: ChannelSetupWizard = {
     const dir = resolveMutiroAccount(cfg, accountId).config.agentDir;
     if (!dir) return undefined;
 
+    const issues: string[] = [];
+
     const whoami = await runPluginCommandWithTimeout({
       argv: ["mutiro", "auth", "whoami"],
       timeoutMs: 5_000,
       cwd: dir,
     });
-
     if (whoami.code !== 0) {
-      await prompter.note(
+      issues.push(
         [
-          "Could not confirm `mutiro auth whoami`.",
-          "",
-          "Finish Mutiro-side setup before starting the gateway:",
+          "Mutiro auth not confirmed. Log in before starting the gateway:",
           `  cd ${dir}`,
           "  mutiro auth login <email>",
-          "",
-          "Also make sure the built-in Mutiro brain is NOT running for this agent —",
-          "running two brains at once will fight over the same conversations:",
-          "  mutiro agent doctor",
         ].join("\n"),
+      );
+    }
+
+    // Built-in brain check: `mutiro agent host status` exits 0 when a host
+    // process is already running for this agent. Starting OpenClaw's gateway
+    // on top of a running host would put two brains on one agent and make
+    // them race on every turn. `host doctor` (setup validation) is separate
+    // from `host status` (runtime liveness) — we want the latter here.
+    const hostStatus = await runPluginCommandWithTimeout({
+      argv: ["mutiro", "agent", "host", "status"],
+      timeoutMs: 5_000,
+      cwd: dir,
+    });
+    if (hostStatus.code === 0) {
+      issues.push(
+        [
+          "A Mutiro agent host is already running for this agent.",
+          "Stop it before starting OpenClaw — two brains on one agent will",
+          "race on every turn:",
+          "  pkill -f 'mutiro agent host'   # or stop whichever process started it",
+        ].join("\n"),
+      );
+    }
+
+    if (issues.length > 0) {
+      await prompter.note(
+        [
+          "Readiness checks flagged the following:",
+          "",
+          ...issues.flatMap((issue) => [issue, ""]),
+        ]
+          .join("\n")
+          .trimEnd(),
         "Mutiro agent readiness",
       );
     }