@mutirolabs/openclaw-brain 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,50 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-04-18
+
+### Added
+
+- Initial OpenClaw channel plugin for the Mutiro `chatbridge` protocol.
+- NDJSON envelope codec ported from `pi-brain`.
+- 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`,
+  `message.forward`, `media.upload`, `signal.emit`, `recall.search`, `recall.get`,
+  `turn.end`.
+- Live call handoff via `task.request` and `session.snapshot`.
+- Agent tools: `mutiro_send_voice_message`, `mutiro_send_card`, `mutiro_forward_message`.
+- Signal forwarder: 26-entry OpenClaw-tool → Mutiro signal-enum map with
+  rich intent labels from `onItemEvent`.
+- Channel setup wizard: detects the Mutiro CLI, validates the agent directory,
+  runs `mutiro auth whoami`, and writes `channels.mutiro.accounts.<id>.agentDir`.
+  Launched via `openclaw channels add` (no flags — passing `--channel mutiro`
+  falls through to the non-interactive adapter and never reaches the wizard).
+- Host stderr (slog JSON) wrapped into the OpenClaw channel logger so log
+  output matches the rest of the gateway stream.
+- `docs/guides/use-openclaw-as-brain.md` — end-to-end setup walkthrough.
+- `docs/guides/manage-allowlist.md` — paste-into-AI prompt for managing the
+  Mutiro server-side allowlist; the setup wizard's completion note points here
+  so users know the Mutiro and OpenClaw allowlist layers are separate.
+- README + setup guide document `--dangerously-force-unsafe-install`: the
+  plugin legitimately spawns `mutiro agent host --mode=bridge`, so OpenClaw's
+  install scanner correctly flags `child_process` usage and requires the flag
+  as explicit acknowledgement. Install instructions show the flag with a note
+  telling users to verify the source before passing it.
+- `@sinclair/typebox` declared as a runtime dependency so OpenClaw's
+  `npm install --omit=dev` in the installed plugin directory picks it up;
+  without this, plugin registration fails with "Cannot find module
+  '@sinclair/typebox'" when loading `src/agent-tools.ts`.
+- README Prerequisites section: checklist of Mutiro-side state the plugin
+  requires (CLI installed, signed in, agent created, built-in brain stopped)
+  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
+[0.1.0]: https://github.com/mutirolabs/openclaw-brain/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 Mutiro Labs
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,266 @@
+# Mutiro OpenClaw Channel Reference
+
+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.
+
+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.
+
+## Prerequisites
+
+This plugin assumes you already have a working Mutiro agent. Before the Quick
+Start below, confirm each of these passes:
+
+| 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.
+
+## Quick Start
+
+### 1. Install this plugin into OpenClaw
+
+```bash
+openclaw plugins install --dangerously-force-unsafe-install @mutirolabs/openclaw-brain
+```
+
+Or, for local development:
+
+```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):
+
+```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
+```
+
+### 3. Run the OpenClaw 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:
+
+- **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:
+
+```bash
+mutiro user message send <agent-username> "Hello! Who are you?"
+```
+
+### 5. Allow Mutiro-specific agent tools
+
+To let the OpenClaw agent send voice messages, interactive cards, or forward
+messages through Mutiro, add `mutiro*` to your agent's `tools.alsoAllow`:
+
+```yaml
+tools:
+  profile: messaging
+  alsoAllow:
+    - "mutiro*"
+```
+
+See [`docs/guides/use-openclaw-as-brain.md`](./docs/guides/use-openclaw-as-brain.md)
+for a full walkthrough.
+
+### 6. Share the agent with other users
+
+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:
+
+```bash
+mutiro agents allowlist get <agent-username>
+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
+
+## What Is Here
+
+- `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
+
+## Why This Exists
+
+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.
+
+## Type Checking
+
+```bash
+npm run check
+```
+
+It runs with `skipLibCheck` because the OpenClaw plugin SDK's dependency tree includes external type issues that are not specific to this reference code.
+
+## What To Copy
+
+If you are integrating another gateway-shaped runtime, the most useful pieces to copy are:
+
+- 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

package/docs/guides/manage-allowlist.md

@@ -0,0 +1,184 @@
+# Manage Who Can Message Your Mutiro Agent
+
+When OpenClaw is the brain, there are **two allowlists** at play and they do different things:
+
+| Layer | What it gates | Where it lives | How to manage |
+|-------|--------------|----------------|---------------|
+| **Mutiro backend allowlist** | Whether a user's message even reaches your agent. Denied users are blocked at the server — the message never hits the bridge. | Mutiro servers (per agent) | `mutiro agents allowlist …` |
+| **OpenClaw `allowFrom`** | Whether your OpenClaw agent *responds* to a message that did reach it. | Your local OpenClaw config | `openclaw config set channels.mutiro.accounts.<id>.allowFrom …` |
+
+If the Mutiro allowlist denies a user, the OpenClaw `allowFrom` never even gets consulted. Tighten whichever layer gives you the semantics you want, but **do not skip the Mutiro layer** — it is the only one that actually prevents delivery.
+
+Copy the prompt below into your AI assistant (Claude, Cursor, Windsurf, or similar) when you want to share or restrict your agent.
+
+## The Prompt
+
+````
+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.
+
+Be proactive — inspect current state before changing anything, and confirm
+destructive changes (especially `set` calls that replace the whole list).
+
+---
+
+### Step 1: Figure out which agent
+
+If I haven't told you the agent username, ask me or check what agents I own:
+
+```bash
+mutiro agents list
+```
+
+Agent usernames end in a Mutiro-assigned suffix (e.g., `my_bot_X1W1`). Use the
+full username in every command below.
+
+---
+
+### Step 2: Show the current Mutiro allowlist
+
+Always start by inspecting current state:
+
+```bash
+mutiro agents allowlist get <agent-username>
+```
+
+Output tells you one of three states:
+
+- Only the owner (me) — no one else can message the agent yet.
+- A specific list of usernames — only those users plus me.
+- `*` — open to everyone on Mutiro.
+
+Report it back to me before changing anything.
+
+---
+
+### Step 3: Make the change I asked for
+
+Map the request to the right command. Do not guess — match exactly:
+
+**Add one user:**
+```bash
+mutiro agents allowlist add <agent-username> <username>
+```
+
+**Remove one user:**
+```bash
+mutiro agents allowlist remove <agent-username> <username>
+```
+
+**Shorthand for a single allow (same as `allowlist add`):**
+```bash
+mutiro agents allow <agent-username> <username>
+```
+
+**Shorthand for a single deny (same as `allowlist remove`):**
+```bash
+mutiro agents deny <agent-username> <username>
+```
+
+**Replace the entire list** (destructive — confirm with me first):
+```bash
+mutiro agents allowlist set <agent-username> alice bob charlie
+```
+
+**Open to everyone** (destructive — confirm security posture first, see Step 5):
+```bash
+mutiro agents allowlist set <agent-username> "*"
+```
+
+**Reset to owner-only** (removes everyone else):
+```bash
+mutiro agents allowlist set <agent-username>
+```
+
+---
+
+### Step 4: Verify
+
+After any change, re-run `get` and tell me the new state:
+
+```bash
+mutiro agents allowlist get <agent-username>
+```
+
+---
+
+### Step 5: Security Check (especially for `set "*"` or large additions)
+
+Opening the agent up changes its threat model. Before you run `set "*"` or add
+more than a couple of users, walk me through this:
+
+**Exposure × blast radius.** Higher exposure + more powerful tools = more risk.
+
+- What tools does my OpenClaw agent have? Check the agent config. Tools like
+  `writeFile`, `memory_write`, `web_fetch`, or anything from the "Dangerous"
+  group (`bash`, `process`, `code`) multiply the blast radius of any prompt
+  injection.
+- Is the agent set up with per-user workspace isolation? Look for
+  `workspace: "./${USERNAME}"` in `.mutiro-agent.yaml`. If everyone shares a
+  workspace, one user can poison files for everyone.
+- Does the agent write to memory? `memory_write` persists across ALL future
+  conversations, so a single injection becomes permanent.
+
+If any of those look risky for open access, suggest tightening before setting
+`*` — either drop powerful tools, switch to per-user workspace, or keep the
+allowlist narrow.
+
+---
+
+### Step 6: Second layer (optional)
+
+If I want a second filter — for example, "Alice can message the agent at the
+server level but I want the OpenClaw agent to ignore her for now" — we can add
+her to OpenClaw's own `allowFrom` denylist or set a stricter OpenClaw DM
+policy. Ask me if that's needed; usually the Mutiro layer is enough.
+
+OpenClaw config lives at `channels.mutiro.accounts.<account-id>.allowFrom`
+and is managed via `openclaw config set` or the `openclaw channels add`
+wizard.
+
+---
+
+### Reference
+
+- `mutiro agents allowlist get <agent>` — list current allowlist
+- `mutiro agents allow <agent> <user>` — add one
+- `mutiro agents deny <agent> <user>` — remove one
+- `mutiro agents allowlist set <agent> user1 user2 ...` — replace whole list
+- `mutiro agents allowlist set <agent> "*"` — open to everyone
+- `mutiro agents allowlist set <agent>` — reset to owner-only
+- `mutiro agents allowlist add <agent> <user>` — same as `allow`
+- `mutiro agents allowlist remove <agent> <user>` — same as `deny`
+- `mutiro agents get <agent>` — agent details (owner, created-at, etc.)
+- `mutiro agent doctor` — diagnose the Mutiro side
+````
+
+## Quick Reference (Humans)
+
+If you don't want to use an AI assistant, the commands are the same:
+
+```bash
+# See who has access
+mutiro agents allowlist get <agent-username>
+
+# Allow one user
+mutiro agents allow <agent-username> <username>
+
+# Remove one user
+mutiro agents deny <agent-username> <username>
+
+# Replace the whole list
+mutiro agents allowlist set <agent-username> alice bob charlie
+
+# Open to everyone (read the security note in the prompt above first!)
+mutiro agents allowlist set <agent-username> "*"
+
+# Reset to owner-only
+mutiro agents allowlist set <agent-username>
+```
+
+**Remember:** the Mutiro backend allowlist is the authoritative server-side
+gate. A denied user's message never reaches your OpenClaw brain at all.