@mutirolabs/openclaw-brain 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -7,12 +7,68 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-04-19
+
+### Added
+
+- Threading adapter: the agent's first reply in a turn threads under the
+  inbound message by default (visible quoted pill in every Mutiro client).
+  `channels.mutiro.replyToMode` overrides with `off` | `first` | `all` |
+  `batched`. `allowExplicitReplyTagsWhenOff: true` keeps agent-directed reply
+  markers working when the user opts out.
+- `replyToMode` exposed in `openclaw.plugin.json` configSchema.
+- Status adapter (`ChannelStatusAdapter.buildAccountSnapshot`):
+  `openclaw channels status mutiro` now reports `healthState` (stopped |
+  restarting | connecting | healthy), `mode: "bridge"`, and `dbPath`
+  pointing at the Mutiro agent workspace.
+- Bridge crash backoff: unexpected host exits track a per-account crash
+  streak with a 5-minute reset window and hold the gateway lifecycle promise
+  through an exponential delay (1s → 2s → 5s → 15s → 60s). Clean exits
+  (code 0 or abort) short-circuit immediately. Surfaces `restartPending`,
+  `reconnectAttempts`, and structured `lastDisconnect` on the snapshot.
+- Setup wizard pre-flight: runs `mutiro agent host status` and warns if a
+  Mutiro agent host is already running for this agent before starting the
+  gateway.
+
+### Changed
+
+- README rewrite: sharper tagline, hero screenshot (`docs/assets/mutiro-openclaw-ui.png`),
+  Prerequisites section folded into the setup wizard, `tools.alsoAllow`
+  switched from YAML hand-edit to
+  `openclaw config set tools.alsoAllow '["mutiro*"]'`, allowlist reframed
+  as an edge-enforced security feature, sibling link to `pi-brain`.
+- Doc links drop `.md` suffixes so they render as HTML; `/docs` replaced
+  with `/docs/manual` + `/docs/cli`.
+- Prerequisites "built-in brain stopped" check now references
+  `mutiro agent host status` (runtime liveness) instead of
+  `mutiro agent doctor` (which only validates config).
+- Internal cleanup: removed `pi-brain` references from source comments
+  and changelog.
+- User-facing metadata aligned with OpenClaw's "channel" + "extension"
+  language: npm `description`, `keywords`, channel `selectionLabel`,
+  `blurb`, plugin entry `description`, and the setup wizard title no
+  longer leak the internal `chatbridge` protocol name.
+
+### Removed
+
+- Unused `MUTIRO_AGENT_API_KEY` from `openclaw.plugin.json` `channelEnvVars`;
+  the chathost reads that env var, not this plugin.
+
+## [0.1.1] - 2026-04-18
+
+### Added
+
+- README prerequisites and wizard help text now suggest `--badge lobster` on
+  `mutiro agents create` so the agent shows the OpenClaw lobster badge in the
+  Mutiro UI. For existing agents, `mutiro agents update-profile <username>
+  --badge lobster` flips it on after the fact.
+
 ## [0.1.0] - 2026-04-18
 
 ### Added
 
-- Initial OpenClaw channel plugin for the Mutiro `chatbridge` protocol.
-- NDJSON envelope codec ported from `pi-brain`.
+- Initial OpenClaw Channel extension for Mutiro.
+- NDJSON envelope codec for `mutiro.agent.bridge.v1`.
 - Subprocess lifecycle for `mutiro agent host --mode=bridge`, one per configured account.
 - Inbound pipeline: `message.observed` → OpenClaw reply dispatch.
 - Outbound surface: `message.send`, `message.send_voice`, `message.react`,
@@ -46,5 +102,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   with concrete fix commands, plus the paste-into-AI prompt as an alternative
   for users who'd rather have their AI assistant drive the setup.
 
-[Unreleased]: https://github.com/mutirolabs/openclaw-brain/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/mutirolabs/openclaw-brain/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/mutirolabs/openclaw-brain/compare/v0.1.1...v0.2.0
+[0.1.1]: https://github.com/mutirolabs/openclaw-brain/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/mutirolabs/openclaw-brain/releases/tag/v0.1.0

package/README.md

@@ -1,131 +1,62 @@
-# Mutiro OpenClaw Channel Reference
+# Mutiro Channel for OpenClaw
 
-Use this repo if you want to plug [OpenClaw](https://openclaw.ai) into a Mutiro agent over `chatbridge`, so OpenClaw becomes the external brain and Mutiro becomes just another OpenClaw channel.
+The official Mutiro Channel extension for OpenClaw.
 
-This is the OpenClaw-shaped sibling of [`../pi-brain`](../pi-brain). The bridge codec is a faithful port of `mutiro-pi-bridge.ts`; the brain side is structured as an OpenClaw third-party channel plugin instead of a one-off standalone adapter.
+OpenClaw handles the cognition. Mutiro handles the messaging surface, identity, and state.
 
-## Prerequisites
+![Mutiro UI with OpenClaw Badge](docs/assets/mutiro-openclaw-ui.png)
 
-This plugin assumes you already have a working Mutiro agent. Before the Quick
-Start below, confirm each of these passes:
+## Why this exists
 
-| Check | Fix if it fails |
-|-------|-----------------|
-| `mutiro version` prints a version | `curl -sSL https://mutiro.com/downloads/install.sh \| bash` |
-| `mutiro auth whoami` prints your username | sign up: `mutiro auth signup <email> <username> "<Display Name>"` — or log in: `mutiro auth login <email>` |
-| `mutiro agents list` shows at least one agent you own | `mutiro agents create <username> "<Display>" --engine genie --bio "<short bio>"` |
-| The built-in Mutiro brain for that agent is **not** running | `mutiro agent doctor`, and stop any `mutiro agent run` / `mutiro start` process for that agent |
-
-Want an AI assistant to drive you through those steps instead? Paste this into
-Claude, Cursor, or Windsurf:
-
-```text
-Read this page from the Mutiro docs: https://mutiro.com/docs/guides/create-agent.md and help me create an agent step by step.
-```
-
-Canonical reference: [Mutiro create-agent guide](https://www.mutiro.com/docs/guides/create-agent.md).
-
-> **Two brains, one agent = trouble.** Mutiro ships its own built-in brain. If
-> you leave it running, it will race OpenClaw for the same conversations and
-> both will reply (or neither will, depending on ordering). Stop it before
-> starting the OpenClaw gateway.
+Sovereign intelligence deserves a professional interface. Hiding a powerful OpenClaw brain behind a generic Telegram bot or a clunky webview breaks the user experience and obscures ownership. This extension implements an OpenClaw Channel that connects your agent to Mutiro's native clients (Desktop, Mobile, Web, CLI), enforcing the `by @owner` accountability standard out of the box.
 
 ## Quick Start
 
-### 1. Install this plugin into OpenClaw
+Install the Mutiro channel using OpenClaw's native extension manager:
 
 ```bash
 openclaw plugins install --dangerously-force-unsafe-install @mutirolabs/openclaw-brain
 ```
 
-Or, for local development:
+> The flag is required because this extension launches a Mutiro host process to carry the channel. Install only from the signed [`@mutirolabs/openclaw-brain`](https://github.com/mutirolabs/openclaw-brain) source.
 
-```bash
-# Skip node_modules if you've run `npm install` here — the install scanner
-# walks the source tree and caps at 10k directories.
-rm -rf node_modules
-openclaw plugins install --dangerously-force-unsafe-install "file:$(pwd)"
-```
-
-> **Why the `--dangerously-force-unsafe-install` flag?**
-> This plugin legitimately spawns `mutiro agent host --mode=bridge` as a
-> subprocess — that is the entire point of the `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)
-> source** (or the `@mutirolabs/openclaw-brain` npm package). Review the
-> `spawn` call at [`src/bridge-client.ts`](./src/bridge-client.ts) if you want
-> to see exactly what the plugin executes.
-
-### 2. Configure the channel
-
-The plugin ships a setup wizard. Run the bare command (no `--channel` flag —
-passing one skips the wizard and falls through to the non-interactive adapter):
+Add the channel:
 
 ```bash
 openclaw channels add
 ```
 
-Pick `mutiro` from the list. The wizard will:
-
-- detect the `mutiro` CLI (and point you at the install command if missing)
-- ask for your Mutiro agent directory (the folder containing `.mutiro-agent.yaml`)
-- validate the directory and run `mutiro auth whoami`
-- remind you to stop the built-in Mutiro brain before starting the gateway
-
-Or set the config manually:
-
-```bash
-openclaw config set channels.mutiro.accounts.default.agentDir /path/to/agent-directory
-```
+Pick `mutiro` from the list. The setup wizard detects the Mutiro CLI, validates your agent directory, and confirms you are authenticated.
 
-### 3. Run the OpenClaw gateway
+Start the gateway:
 
 ```bash
 openclaw gateway run
 ```
 
-Or use the shortcut:
-
-```bash
-./run-brain.sh /path/to/agent-directory
-```
-
-### 4. Talk to your agent
-
-Once the gateway is running, your agent is reachable from any Mutiro surface:
+Your agent is now live on every Mutiro surface — Web, Desktop, Mobile, and CLI.
 
-- **Web app:** [https://app.mutiro.com](https://app.mutiro.com)
-- **CLI chat:** `mutiro chat`
-- **Mobile:** Mutiro app on iOS / Android
-- **Desktop:** Mutiro desktop app on macOS / Windows / Linux
-
-For a quick shell smoke test:
+Send a smoke-test message:
 
 ```bash
 mutiro user message send <agent-username> "Hello! Who are you?"
 ```
 
-### 5. Allow Mutiro-specific agent tools
+## Enable Mutiro-native tools
 
-To let the OpenClaw agent send voice messages, interactive cards, or forward
-messages through Mutiro, add `mutiro*` to your agent's `tools.alsoAllow`:
+Let your OpenClaw agent send voice messages, interactive cards, and forward messages through Mutiro by allowing the `mutiro*` tools:
 
-```yaml
-tools:
-  profile: messaging
-  alsoAllow:
-    - "mutiro*"
+```bash
+openclaw config set tools.alsoAllow '["mutiro*"]'
 ```
 
-See [`docs/guides/use-openclaw-as-brain.md`](./docs/guides/use-openclaw-as-brain.md)
-for a full walkthrough.
+If you already curate `tools.alsoAllow`, merge `"mutiro*"` into your existing list instead of overwriting — the command above replaces the array.
+
+## Access control, enforced at the edge
 
-### 6. Share the agent with other users
+Mutiro runs the allowlist on its servers — not in your agent. Denied users are rejected before their messages reach OpenClaw, so agent-side bugs can never leak access to someone who shouldn't have it. This is a stronger posture than in-agent filtering and a real differentiator over generic bot channels.
 
-Mutiro has a **server-side allowlist** that's separate from OpenClaw's own
-`allowFrom`. Denied users are blocked at the Mutiro server — their messages
-never reach OpenClaw at all. Manage it with the `mutiro` CLI:
+One extra CLI step buys you that posture:
 
 ```bash
 mutiro agents allowlist get <agent-username>
@@ -133,134 +64,37 @@ mutiro agents allow <agent-username> <username>
 mutiro agents deny <agent-username> <username>
 ```
 
-See [`docs/guides/manage-allowlist.md`](./docs/guides/manage-allowlist.md) for
-the full command reference and a paste-into-AI prompt you can hand to your
-assistant when you want help managing sharing and security posture.
-
-## What This Repo Is
-
-A small reference package showing how to plug OpenClaw into Mutiro `chatbridge` as a channel plugin. Pi is a good reference for swapping Mutiro's brain with a standalone runtime; this one shows the same shape routed through OpenClaw's channel plugin contract.
-
-- `mutiro agent host --mode=bridge` is spawned by the plugin, one process per configured Mutiro agent
-- NDJSON envelope traffic is translated into OpenClaw inbound messages and outbound send/react/forward actions
-- one subprocess per Mutiro agent, long-lived across conversations
-- all outbound chat actions go back through the bridge
+As adoption grows, we may expose the allowlist directly through the OpenClaw channel. For now it stays behind the `mutiro` CLI — a deliberate boundary that keeps access control outside the agent sandbox.
 
-## What Is Here
+## FAQ
 
-- `index.ts` — plugin entry via `defineBundledChannelEntry`
-- `src/bridge-protocol.ts` — NDJSON envelope constants and `@type` URLs
-- `src/bridge-messages.ts` — normalized message extraction and observed-turn assembly
-- `src/bridge-client.ts` — NDJSON envelope codec plus host subprocess spawn
-- `src/bridge-session.ts` — per-conversation observed/task/snapshot handlers
-- `src/inbound.ts` — bridge observed message → OpenClaw inbound envelope
-- `src/outbound.ts` — OpenClaw outbound adapter → `message.send` / `message.react` / `message.forward`
-- `src/channel.ts` — Mutiro channel plugin definition
-- `src/channel.runtime.ts` — runtime barrel consumed by the plugin entry
-- `src/setup-surface.ts` — setup wizard driven by `openclaw channels add` (pick `mutiro` from the list)
-- `src/agent-tools.ts` — `mutiro_send_voice_message`, `mutiro_send_card`, `mutiro_forward_message`
-- `src/signal-forwarder.ts` — OpenClaw tool events → Mutiro `signal.emit` (26-entry map)
-- `src/live-snapshot.ts` — `session.snapshot` + `task.request` handlers for live call handoff
-- `openclaw.plugin.json` — channel manifest
-- `run-brain.sh` — convenience launcher that boots OpenClaw's gateway against a Mutiro agent directory
-- `docs/guides/use-openclaw-as-brain.md` — end-to-end setup guide
-- `docs/guides/manage-allowlist.md` — paste-into-AI guide for Mutiro's server-side allowlist
+**How do I show the OpenClaw badge on my agent?**
 
-## Why This Exists
+Pass `--badge lobster` when creating the agent so every Mutiro client renders the lobster next to the avatar:
 
-Use this folder as a reference if you want to consume Mutiro's chatbridge from OpenClaw, or another gateway-shaped runtime that already owns its own channel/plugin contract.
-
-It shows how to:
-
-1. Spawn `mutiro agent host --mode=bridge` from inside an OpenClaw channel plugin
-2. Complete `ready → session.initialize → subscription.set`
-3. Receive `message.observed` and turn it into an OpenClaw inbound envelope
-4. Route OpenClaw outbound replies through bridge-local commands (`message.send`, `message.react`, `message.forward`, `media.upload`, `signal.emit`, `recall.search/get`)
-5. Finish turns with `turn.end`
-
-## Important Bridge Notes
-
-- `message.send` is a bridge-local command, not a raw backend `SendToConversationRequest`
-- the portable payload type is `mutiro.chatbridge.ChatBridgeSendMessageCommand`
-- `message.send_voice` is also bridge-local and keeps TTS inside the host
-- this reference usually replies by `conversation_id`
-- the bridge also supports `to_username` for direct sends
-
-## Adapter Model
-
-The plugin process is an OpenClaw channel. It:
-
-- spawns `mutiro agent host --mode=bridge` (one per configured Mutiro agent directory)
-- reads and writes bridge envelopes on stdio
-- delivers `message.observed` payloads as OpenClaw inbound messages
-- exposes outbound send/react/forward through the standard OpenClaw `ChannelOutboundAdapter`
-
-OpenClaw's agent runtime owns the brain layer. The plugin does not talk to Mutiro SDKs directly; everything portable flows through the chatbridge envelope.
-
-## Supported Bridge Operations
-
-This adapter exercises:
-
-- `message.send`
-- `message.send_voice`
-- `message.react`
-- `message.forward`
-- `media.upload`
-- `signal.emit`
-- `turn.end`
-- `recall.search`
-- `recall.get`
-
-## Session Model
-
-- one Mutiro `conversation_id` maps to one OpenClaw conversation binding
-- later turns in the same conversation reuse the same OpenClaw session, just as pi-brain reuses a Pi session
-- `session.snapshot` is answered from recent messages cached per-conversation in the plugin
-
-OpenClaw already owns transcript continuity across turns, so the plugin keeps its own cache narrow — just enough to answer `session.snapshot` for bridge consumers.
-
-## Handshake
-
-Startup flow:
-
-1. host sends `ready`
-2. plugin sends `session.initialize`
-3. plugin sends `subscription.set`
-4. host starts delivering `message.observed`
-
-Per turn:
-
-1. plugin acknowledges `message.observed`
-2. plugin dispatches the observed envelope into OpenClaw's inbound pipeline
-3. OpenClaw's reply-dispatch drives zero or more outbound bridge operations
-4. plugin sends `turn.end`
-
-## Debugging
-
-Useful signals while integrating:
-
-- `Handshake failed`
-  Bridge startup or negotiation problem.
-- `Host error`
-  A bridge request failed outside a pending request path.
-- `outbound bridge call failed`
-  The plugin reached the bridge and got a real host-side error.
+```bash
+mutiro agents create <username> "<Display>" --engine genie --badge lobster
+```
 
-## Type Checking
+For an agent that already exists, flip the badge on with:
 
 ```bash
-npm run check
+mutiro agents update-profile <agent-username> --badge lobster
 ```
 
-It runs with `skipLibCheck` because the OpenClaw plugin SDK's dependency tree includes external type issues that are not specific to this reference code.
+**I don't have a Mutiro agent yet — what's the fastest way to create one?**
+
+Paste this prompt into your AI assistant (Claude, Cursor, Windsurf, …):
+
+> Read https://mutiro.com/docs/guides/create-agent and help me create a Mutiro agent step by step. Use `--badge lobster` on `mutiro agents create` so the agent shows the OpenClaw badge.
 
-## What To Copy
+Or follow the [Mutiro create-agent guide](https://www.mutiro.com/docs/guides/create-agent) by hand.
 
-If you are integrating another gateway-shaped runtime, the most useful pieces to copy are:
+## Resources
 
-- bridge handshake flow (`src/bridge-session.ts` + `src/bridge-client.ts`)
-- pending-request correlation by `request_id`
-- `message.observed` acknowledgement behavior (ack delivery now, reply later)
-- per-conversation recent-message cache for `session.snapshot`
-- outbound operation wrappers (`src/outbound.ts`)
-- final `turn.end` behavior
+- [Use OpenClaw as brain](./docs/guides/use-openclaw-as-brain.md)
+- [Manage the Mutiro allowlist](./docs/guides/manage-allowlist.md)
+- [Mutiro manual](https://mutiro.com/docs/manual)
+- [Mutiro CLI reference](https://mutiro.com/docs/cli)
+- [OpenClaw documentation](https://openclaw.ai)
+- Sibling repo: [`pi-brain`](https://github.com/mutirolabs/pi-brain) — the Pi equivalent, a standalone bridge rather than an OpenClaw extension

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.0",
-  "description": "OpenClaw channel plugin that drives a Mutiro agent over chatbridge. OpenClaw becomes the brain; Mutiro stays the messaging surface.",
+  "version": "0.2.0",
+  "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": {
@@ -22,10 +22,9 @@
   },
   "keywords": [
     "mutiro",
-    "chatbridge",
     "openclaw",
     "channel",
-    "plugin",
+    "extension",
     "agent"
   ],
   "files": [
@@ -63,10 +62,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 }) => {
@@ -183,7 +183,7 @@ export const mutiroSetupWizard: ChannelSetupWizard = {
         "",
         "Then log in and create (or pick) an agent:",
         "  mutiro auth login <email>",
-        '  mutiro agents create <username> "<Display Name>" --engine genie --bio "<bio>"',
+        '  mutiro agents create <username> "<Display Name>" --engine genie --bio "<bio>" --badge lobster',
         "",
         `Guide: ${CREATE_AGENT_GUIDE}`,
       ].join("\n"),
@@ -204,7 +204,7 @@ export const mutiroSetupWizard: ChannelSetupWizard = {
         "should drive. Each configured account points to one agent directory.",
         "",
         "If you don't have one yet:",
-        '  mutiro agents create <username> "<Display Name>" --engine genie --bio "<bio>"',
+        '  mutiro agents create <username> "<Display Name>" --engine genie --bio "<bio>" --badge lobster',
         `Guide: ${CREATE_AGENT_GUIDE}`,
       ],
       currentValue: ({ cfg, accountId }) =>
@@ -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",
       );
     }