@mutirolabs/openclaw-brain 0.1.0

package/src/setup-surface.ts

@@ -0,0 +1,281 @@
+// Setup wizard + adapter. The wizard runs when the user invokes `openclaw
+// channels add` with no flags and picks `mutiro` from the selection list
+// (passing `--channel mutiro` falls through to the non-interactive adapter
+// path, not the wizard). The wizard detects the `mutiro` CLI,
+// collects the agent directory path, validates that it looks like a real
+// Mutiro agent workspace, and checks that auth is configured before writing
+// `channels.mutiro.accounts.<id>.agentDir` into the OpenClaw config.
+
+import fs from "node:fs";
+import path from "node:path";
+
+import {
+  createStandardChannelSetupStatus,
+  DEFAULT_ACCOUNT_ID,
+  formatDocsLink,
+  normalizeAccountId,
+  setSetupChannelEnabled,
+  type ChannelSetupAdapter,
+  type ChannelSetupWizard,
+  type OpenClawConfig,
+} from "openclaw/plugin-sdk/setup";
+import { runPluginCommandWithTimeout } from "openclaw/plugin-sdk/run-command";
+import { detectBinary } from "openclaw/plugin-sdk/setup-tools";
+
+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 MUTIRO_INTRO_LINES = [
+  "Point OpenClaw at an existing Mutiro agent directory.",
+  "Mutiro stays the messaging surface; OpenClaw becomes the brain.",
+  "",
+  "Before continuing:",
+  `  1. Create a Mutiro agent: ${CREATE_AGENT_GUIDE}`,
+  "  2. Stop the built-in Mutiro brain for that agent — do not run two brains.",
+  "",
+  `Docs: ${formatDocsLink("/channels/mutiro", "channels/mutiro")}`,
+];
+
+type MutiroAccountSection = {
+  agentDir?: string;
+  clientName?: string;
+  enabled?: boolean;
+  name?: string;
+};
+
+type MutiroSection = {
+  accounts?: Record<string, MutiroAccountSection>;
+  agentDir?: string;
+  clientName?: string;
+  enabled?: boolean;
+};
+
+function getSection(cfg: OpenClawConfig): MutiroSection {
+  const channels = (cfg as { channels?: Record<string, unknown> }).channels;
+  return (channels?.mutiro as MutiroSection | undefined) ?? {};
+}
+
+function isConfigured(cfg: OpenClawConfig, accountId: string): boolean {
+  const dir = resolveMutiroAccount(cfg, accountId).config.agentDir;
+  if (!dir) return false;
+  try {
+    return fs.statSync(dir).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function patchAccount(params: {
+  cfg: OpenClawConfig;
+  accountId: string;
+  patch: Record<string, unknown>;
+  enabled?: boolean;
+}): OpenClawConfig {
+  const section = getSection(params.cfg);
+
+  // Single-account shorthand: keep `agentDir` at the top-level section as long
+  // as no named accounts exist. This matches the plugin's config shape.
+  if (params.accountId === DEFAULT_ACCOUNT_ID && !section.accounts) {
+    return {
+      ...params.cfg,
+      channels: {
+        ...params.cfg.channels,
+        [channel]: {
+          ...section,
+          ...(params.enabled ? { enabled: true } : {}),
+          ...params.patch,
+        },
+      },
+    } as OpenClawConfig;
+  }
+
+  const accounts: Record<string, MutiroAccountSection> = { ...(section.accounts ?? {}) };
+  accounts[params.accountId] = {
+    ...(accounts[params.accountId] ?? {}),
+    ...params.patch,
+  };
+
+  return {
+    ...params.cfg,
+    channels: {
+      ...params.cfg.channels,
+      [channel]: {
+        ...section,
+        ...(params.enabled ? { enabled: true } : {}),
+        accounts,
+      },
+    },
+  } as OpenClawConfig;
+}
+
+function validateAgentDir(raw: string): string | undefined {
+  const trimmed = raw.trim();
+  if (!trimmed) return "Agent directory is required.";
+
+  const resolved = path.resolve(trimmed);
+  try {
+    const stat = fs.statSync(resolved);
+    if (!stat.isDirectory()) return "Path is not a directory.";
+  } catch {
+    return "Directory does not exist. Create the Mutiro agent first.";
+  }
+
+  const manifest = path.join(resolved, ".mutiro-agent.yaml");
+  if (!fs.existsSync(manifest)) {
+    return ".mutiro-agent.yaml not found. Is this the correct agent directory?";
+  }
+
+  return undefined;
+}
+
+export const mutiroSetupAdapter: ChannelSetupAdapter = {
+  resolveAccountId: ({ accountId }) => normalizeAccountId(accountId) ?? DEFAULT_ACCOUNT_ID,
+  validateInput: ({ input }) => {
+    const raw = input.authDir?.trim();
+    if (!raw) {
+      return "Mutiro requires --auth-dir (path to the Mutiro agent directory).";
+    }
+    return validateAgentDir(raw) ?? null;
+  },
+  applyAccountConfig: ({ cfg, accountId, input }) =>
+    patchAccount({
+      cfg,
+      accountId,
+      enabled: true,
+      patch: { agentDir: path.resolve((input.authDir ?? "").trim()) },
+    }),
+};
+
+export const mutiroSetupWizard: ChannelSetupWizard = {
+  channel,
+  status: createStandardChannelSetupStatus({
+    channelLabel: "Mutiro",
+    configuredLabel: "configured",
+    unconfiguredLabel: "needs agent directory",
+    configuredHint: "agent directory set",
+    unconfiguredHint: "point at a Mutiro agent dir",
+    configuredScore: 1,
+    unconfiguredScore: 0,
+    includeStatusLine: true,
+    resolveConfigured: ({ cfg, accountId }) =>
+      accountId
+        ? isConfigured(cfg, accountId)
+        : listMutiroAccountIds(cfg).some((id) => isConfigured(cfg, id)),
+    resolveExtraStatusLines: ({ cfg }) => [`Accounts: ${listMutiroAccountIds(cfg).length || 0}`],
+  }),
+  introNote: {
+    title: "Mutiro chatbridge setup",
+    lines: MUTIRO_INTRO_LINES,
+  },
+  prepare: async ({ prompter }) => {
+    const cliDetected = await detectBinary("mutiro");
+    if (cliDetected) return undefined;
+
+    await prompter.note(
+      [
+        "mutiro CLI not found on PATH.",
+        "",
+        "Install it:",
+        `  curl -sSL ${INSTALL_URL} | bash`,
+        "",
+        "Then log in and create (or pick) an agent:",
+        "  mutiro auth login <email>",
+        '  mutiro agents create <username> "<Display Name>" --engine genie --bio "<bio>"',
+        "",
+        `Guide: ${CREATE_AGENT_GUIDE}`,
+      ].join("\n"),
+      "Mutiro CLI required",
+    );
+    return undefined;
+  },
+  credentials: [],
+  textInputs: [
+    {
+      inputKey: "authDir",
+      message: "Path to your Mutiro agent directory",
+      placeholder: "/Users/you/agents/my-agent",
+      required: true,
+      helpTitle: "Mutiro agent directory",
+      helpLines: [
+        "The folder that contains `.mutiro-agent.yaml` for the agent OpenClaw",
+        "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>"',
+        `Guide: ${CREATE_AGENT_GUIDE}`,
+      ],
+      currentValue: ({ cfg, accountId }) =>
+        resolveMutiroAccount(cfg, accountId).config.agentDir,
+      keepPrompt: (value) => `Agent directory set (${value}). Keep it?`,
+      validate: ({ value }) => validateAgentDir(value),
+      normalizeValue: ({ value }) => path.resolve(value.trim()),
+      applySet: async ({ cfg, accountId, value }) =>
+        patchAccount({
+          cfg,
+          accountId,
+          enabled: true,
+          patch: { agentDir: path.resolve(value.trim()) },
+        }),
+    },
+  ],
+  finalize: async ({ cfg, accountId, prompter }) => {
+    const dir = resolveMutiroAccount(cfg, accountId).config.agentDir;
+    if (!dir) return undefined;
+
+    const whoami = await runPluginCommandWithTimeout({
+      argv: ["mutiro", "auth", "whoami"],
+      timeoutMs: 5_000,
+      cwd: dir,
+    });
+
+    if (whoami.code !== 0) {
+      await prompter.note(
+        [
+          "Could not confirm `mutiro auth whoami`.",
+          "",
+          "Finish Mutiro-side setup 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"),
+        "Mutiro agent readiness",
+      );
+    }
+
+    return undefined;
+  },
+  completionNote: {
+    title: "Mutiro bridge configured",
+    lines: [
+      "Next steps:",
+      "  1. Stop the built-in Mutiro brain for this agent (don't run two brains).",
+      "  2. Allow Mutiro tools on the OpenClaw agent by adding `mutiro*` to",
+      "     `tools.alsoAllow` (or enable individually: mutiro_send_voice_message,",
+      "     mutiro_send_card, mutiro_forward_message).",
+      "  3. Start the gateway:  openclaw gateway run",
+      "",
+      "Once the gateway is running, talk to your agent:",
+      "  Web:     https://app.mutiro.com",
+      "  CLI:     mutiro chat",
+      "  Mobile:  Mutiro app (iOS / Android)",
+      "  Desktop: Mutiro desktop app (macOS / Windows / Linux)",
+      "",
+      "Sharing the agent with other users:",
+      "  Mutiro has its own server-side allowlist — denied users are blocked",
+      "  before their messages ever reach OpenClaw. Manage it with:",
+      "    mutiro agents allowlist get <agent-username>",
+      "    mutiro agents allow <agent-username> <username>",
+      "  Full guide (paste into your AI assistant):",
+      "    https://github.com/mutirolabs/openclaw-brain/blob/main/docs/guides/manage-allowlist.md",
+      "",
+      `Docs: ${formatDocsLink("/channels/mutiro", "channels/mutiro")}`,
+    ],
+  },
+  disable: (cfg) => setSetupChannelEnabled(cfg, channel, false),
+};

package/src/signal-forwarder.ts

@@ -0,0 +1,153 @@
+// 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).
+
+import type { BridgeSession } from "./bridge-session.js";
+import type { MutiroOutboundTarget } from "./outbound.js";
+
+const REASONING_DEBOUNCE_MS = 500;
+const TOOL_DETAIL_MAX_CHARS = 120;
+
+// Tool-name → Mutiro signal + human-readable "intent" label. The signal
+// type drives the UI pill style; the intent is the detail_text prefix
+// the user actually reads. Tools without a dedicated SIGNAL_TYPE still
+// get a readable intent ("Reading file: src/x.ts") via CUSTOM so the
+// user sees what's happening rather than the raw tool name.
+type ToolSignalSpec = { signal: string; intent: string };
+const TOOL_SIGNAL_MAP: Record<string, ToolSignalSpec> = {
+  // 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: string): string => {
+  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 type SignalForwarder = {
+  thinking: () => void;
+  typing: () => void;
+  reasoning: () => void;
+  toolStart: (name?: string, phase?: string) => void;
+  itemStart: (params: { name?: string; title?: string; phase?: string }) => void;
+  compactionStart: () => void;
+  compactionEnd: () => void;
+  planUpdate: (title?: string) => void;
+  custom: (detail: string) => void;
+  turnComplete: () => void;
+};
+
+export const createSignalForwarder = (
+  session: BridgeSession,
+  target: MutiroOutboundTarget,
+): SignalForwarder => {
+  let lastReasoningAt = 0;
+  const emit = (signalType: string, detail?: string) => {
+    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"),
+  };
+};