@mutirolabs/openclaw-brain 0.1.0

package/src/channel.runtime.ts

@@ -0,0 +1,454 @@
+// Heavy runtime surface for the Mutiro channel plugin. Owns the registry of
+// active BridgeSession instances keyed by account and serves inbound/outbound
+// calls from the plugin's gateway and outbound adapters.
+//
+// Keeping this file separate from `channel.ts` means the light plugin entry
+// does not pull the NDJSON + child_process machinery into gateway startup.
+
+import type { ChannelOutboundAdapter } from "openclaw/plugin-sdk/core";
+import type { ChannelGatewayContext } from "openclaw/plugin-sdk/channel-contract";
+import { recordInboundSession } from "openclaw/plugin-sdk/conversation-runtime";
+import { recordInboundSessionAndDispatchReply } from "openclaw/plugin-sdk/inbound-reply-dispatch";
+import {
+  dispatchReplyWithBufferedBlockDispatcher,
+  finalizeInboundContext,
+} from "openclaw/plugin-sdk/reply-dispatch-runtime";
+import { resolveAgentRoute } from "openclaw/plugin-sdk/routing";
+import { resolveStorePath } from "openclaw/plugin-sdk/session-store-runtime";
+
+type ChannelOutboundContext = Parameters<NonNullable<ChannelOutboundAdapter["sendText"]>>[0];
+type OutboundDeliveryResult = Awaited<
+  ReturnType<NonNullable<ChannelOutboundAdapter["sendText"]>>
+>;
+
+import { startBridgeSession, type BridgeSession } from "./bridge-session.js";
+import type { ResolvedMutiroAccount } from "./config.js";
+import type { InboundDeliver, InboundMessage } from "./inbound.js";
+import { normalizeOutputText } from "./bridge-messages.js";
+
+type StartContext = ChannelGatewayContext<ResolvedMutiroAccount>;
+
+const sessions = new Map<string, BridgeSession>();
+
+const sessionKey = (channel: string, accountId: string) => `${channel}:${accountId}`;
+
+const requireSessionForAccount = (accountId: string | null | undefined): BridgeSession => {
+  const session = sessions.get(sessionKey("mutiro", accountId ?? "default"));
+  if (!session) {
+    throw new Error(
+      `mutiro channel: no active bridge session for account "${accountId ?? "default"}". gateway.startAccount must run first.`,
+    );
+  }
+  return session;
+};
+
+// Public accessor used by agent tools that need to reach the active bridge
+// session without throwing when the channel is not running yet.
+export const getMutiroBridgeSession = (
+  accountId: string | null | undefined,
+): BridgeSession | undefined =>
+  sessions.get(sessionKey("mutiro", accountId ?? "default"));
+
+/**
+ * Runs the agent against a delegated task prompt and returns the
+ * accumulated reply text. Used by `task.request`, which — unlike
+ * `message.observed` — expects the full reply text inside the
+ * `ChatBridgeTaskResult` envelope instead of on the outbound bridge.
+ *
+ * We reuse the same reply-dispatch path as buildDeliverBridge but swap
+ * the deliver callback: instead of shipping chunks via bridge.message.send
+ * we accumulate them into a buffer the caller returns to the host.
+ *
+ * Tool side-effects (mutiro_send_voice_message, mutiro_send_card, etc.)
+ * still fire normally through their own execute() paths — only the
+ * agent's plain reply text is captured for the task result.
+ */
+const buildResolveTaskRequest = (ctx: StartContext) =>
+  async (params: {
+    conversationId: string;
+    accountId: string;
+    username?: string;
+    prompt: string;
+    promptData?: Record<string, string>;
+    metadata?: Record<string, string>;
+    timeoutMs?: number;
+    requestId?: string;
+  }): Promise<string> => {
+    const senderUsername = (params.username ?? "").trim() || "system";
+    const route = resolveAgentRoute({
+      cfg: ctx.cfg,
+      channel: "mutiro",
+      accountId: params.accountId,
+      peer: { kind: "direct", id: senderUsername },
+    });
+    const storePath = resolveStorePath(ctx.cfg.session?.store, { agentId: route.agentId });
+    const messageSid = params.requestId ?? `task-${Date.now()}`;
+    const ctxPayload = finalizeInboundContext({
+      Body: params.prompt,
+      BodyForAgent: params.prompt,
+      RawBody: params.prompt,
+      CommandBody: params.prompt,
+      From: senderUsername,
+      To: params.conversationId,
+      SessionKey: route.sessionKey,
+      AccountId: route.accountId ?? params.accountId,
+      ChatType: "direct",
+      ConversationLabel: params.conversationId,
+      SenderId: senderUsername,
+      Provider: "mutiro",
+      Surface: "mutiro",
+      MessageSid: messageSid,
+      MessageSidFull: messageSid,
+      Timestamp: Date.now(),
+      OriginatingChannel: "mutiro",
+      OriginatingTo: params.conversationId,
+    });
+
+    const accumulator: string[] = [];
+    const dispatchPromise = recordInboundSessionAndDispatchReply({
+      cfg: ctx.cfg,
+      channel: "mutiro",
+      accountId: params.accountId,
+      agentId: route.agentId,
+      routeSessionKey: route.sessionKey,
+      storePath,
+      ctxPayload,
+      recordInboundSession,
+      dispatchReplyWithBufferedBlockDispatcher,
+      deliver: async (payload) => {
+        const chunk = String(payload.text ?? "");
+        if (chunk) accumulator.push(chunk);
+      },
+      onRecordError: (err) =>
+        ctx.log?.warn?.(`mutiro: task record error: ${formatError(err)}`),
+      onDispatchError: (err, info) =>
+        ctx.log?.warn?.(`mutiro: task dispatch error (${info.kind}): ${formatError(err)}`),
+    });
+
+    // Honor timeout_ms: whichever finishes first, use what accumulated.
+    // If the dispatch ran past the deadline we return partial output and
+    // let the background promise drain; the host already has its answer.
+    if (params.timeoutMs && params.timeoutMs > 0) {
+      await Promise.race([
+        dispatchPromise,
+        new Promise<void>((resolve) => setTimeout(resolve, params.timeoutMs)),
+      ]);
+    } else {
+      await dispatchPromise;
+    }
+
+    return normalizeOutputText(accumulator.join(""));
+  };
+
+const buildDeliverBridge = (ctx: StartContext): InboundDeliver =>
+  async (inbound: InboundMessage) => {
+    const session = requireSessionForAccount(inbound.accountId);
+
+    // Resolve the routing / session / ctxPayload pieces directly from the
+    // public plugin-sdk helpers rather than relying on `ctx.channelRuntime`
+    // to carry the full runtime surface (it does not for bundled channels).
+    const route = resolveAgentRoute({
+      cfg: ctx.cfg,
+      channel: "mutiro",
+      accountId: inbound.accountId,
+      peer: { kind: "direct", id: inbound.senderUsername },
+    });
+    const storePath = resolveStorePath(ctx.cfg.session?.store, { agentId: route.agentId });
+
+    const target = {
+      conversationId: inbound.conversationId,
+      replyToMessageId: inbound.messageId,
+    };
+    const { createSignalForwarder } = await import("./signal-forwarder.js");
+    const signals = createSignalForwarder(session, target);
+    // Fire a THINKING pulse immediately so the user sees feedback while
+    // dispatch warms up (model selection, memory loads, etc.). Subsequent
+    // on* callbacks replace it with more specific signals.
+    signals.thinking();
+
+    const mediaPaths = inbound.mediaPaths ?? [];
+    const mediaTypes = inbound.mediaTypes ?? [];
+    const ctxPayload = finalizeInboundContext({
+      Body: inbound.text,
+      BodyForAgent: inbound.text,
+      RawBody: inbound.text,
+      CommandBody: inbound.text,
+      From: inbound.senderUsername,
+      To: inbound.conversationId,
+      SessionKey: route.sessionKey,
+      AccountId: route.accountId ?? inbound.accountId,
+      ChatType: "direct",
+      ConversationLabel: inbound.conversationId,
+      SenderId: inbound.senderUsername,
+      Provider: "mutiro",
+      Surface: "mutiro",
+      MessageSid: inbound.messageId,
+      MessageSidFull: inbound.messageId,
+      Timestamp: Date.now(),
+      OriginatingChannel: "mutiro",
+      OriginatingTo: inbound.conversationId,
+      ...(mediaPaths.length > 0
+        ? {
+            MediaPath: mediaPaths[0],
+            MediaPaths: mediaPaths,
+            MediaType: mediaTypes[0],
+            MediaTypes: mediaTypes,
+          }
+        : {}),
+    });
+
+    await recordInboundSessionAndDispatchReply({
+      cfg: ctx.cfg,
+      channel: "mutiro",
+      accountId: inbound.accountId,
+      agentId: route.agentId,
+      routeSessionKey: route.sessionKey,
+      storePath,
+      ctxPayload,
+      recordInboundSession,
+      dispatchReplyWithBufferedBlockDispatcher,
+      deliver: async (payload) => {
+        const text = normalizeOutputText(String(payload.text ?? ""));
+        if (!text) return;
+        await session.outbound.sendText(target, text);
+      },
+      // replyOptions taps OpenClaw's mid-turn hooks to forward progress
+      // into Mutiro's signal stream. Each on* callback maps to a specific
+      // SIGNAL_TYPE_* so the user sees "searching web", "remembering",
+      // "writing response" pills instead of a single static "thinking".
+      replyOptions: {
+        onAssistantMessageStart: () => signals.typing(),
+        onReasoningStream: () => signals.reasoning(),
+        onToolStart: (payload) => signals.toolStart(payload.name, payload.phase),
+        // onItemEvent carries richer detail than onToolStart — `title` is
+        // resolved from tool args (e.g. "read src/x.ts"). Refine only on
+        // the start phase; "end"/"update" would thrash the pill.
+        onItemEvent: (payload) => {
+          if (payload.phase && payload.phase !== "start") return;
+          signals.itemStart({
+            name: payload.name,
+            title: payload.title,
+            phase: payload.phase,
+          });
+        },
+        onCompactionStart: () => signals.compactionStart(),
+        onCompactionEnd: () => signals.compactionEnd(),
+        onPlanUpdate: (payload) => signals.planUpdate(payload.title),
+      },
+      onRecordError: (err) => ctx.log?.warn?.(`mutiro: record session error: ${formatError(err)}`),
+      onDispatchError: (err, info) =>
+        ctx.log?.warn?.(`mutiro: dispatch error (${info.kind}): ${formatError(err)}`),
+    });
+
+    // Close the signal stream and the host-owned turn lifecycle.
+    // TURN_COMPLETE clears any lingering pill in the Mutiro UI; endTurn
+    // releases the host-side pending turn regardless of whether visible
+    // replies were emitted.
+    signals.turnComplete();
+    session.outbound.endTurn(target);
+  };
+
+export const startMutiroAccount = async (ctx: StartContext) => {
+  const key = sessionKey("mutiro", ctx.accountId);
+  const existing = sessions.get(key);
+  if (existing) {
+    return;
+  }
+
+  const { account } = ctx;
+  if (!account.configured || !account.config.agentDir) {
+    ctx.log?.warn?.(`mutiro: account "${ctx.accountId}" is not configured (missing agentDir)`);
+    return;
+  }
+
+  // The gateway expects startAccount to stay pending for the lifetime of the
+  // channel. Resolving early is interpreted as "channel exited" and triggers
+  // an auto-restart loop. We block on exit-or-abort via this deferred.
+  let settleLifecycle: () => void = () => {};
+  const lifecycle = new Promise<void>((resolve) => {
+    settleLifecycle = resolve;
+  });
+
+  const session = await startBridgeSession({
+    accountId: ctx.accountId,
+    agentDir: account.config.agentDir,
+    clientName: account.config.clientName,
+    requestedOptionalCapabilities: account.config.requestedOptionalCapabilities,
+    deliver: buildDeliverBridge(ctx),
+    resolveTaskRequest: buildResolveTaskRequest(ctx),
+    resolveLiveSnapshot: async (params) => {
+      // Lazy-load the snapshot module so startup stays clean and the
+      // plugin-sdk/config-runtime surface is only touched when the host
+      // actually requests a live handoff (i.e. a voice call starts).
+      const { buildLiveSnapshot } = await import("./live-snapshot.js");
+      return buildLiveSnapshot({
+        cfg: ctx.cfg,
+        accountId: params.accountId,
+        conversationId: params.conversationId,
+        callerUsername: params.username,
+        callId: params.callId,
+        agentUsername: session?.getAgentUsername() ?? "",
+      });
+    },
+    logger: ctx.log
+      ? {
+          info: ctx.log.info,
+          warn: ctx.log.warn,
+          error: ctx.log.error,
+        }
+      : undefined,
+    onHostExit: (code) => {
+      sessions.delete(key);
+      ctx.log?.info?.(`mutiro: host (${ctx.accountId}) exited with code ${code}`);
+      ctx.setStatus({
+        ...ctx.getStatus(),
+        running: false,
+        connected: false,
+        lastDisconnect: { at: Date.now(), status: code ?? undefined },
+      });
+      settleLifecycle();
+    },
+  });
+
+  sessions.set(key, session);
+  ctx.setStatus({
+    ...ctx.getStatus(),
+    running: true,
+    connected: true,
+    lastConnectedAt: Date.now(),
+    lastStartAt: Date.now(),
+  });
+
+  const onAbort = () => {
+    void stopSession(key).finally(settleLifecycle);
+  };
+  if (ctx.abortSignal.aborted) {
+    onAbort();
+  } else {
+    ctx.abortSignal.addEventListener("abort", onAbort, { once: true });
+  }
+
+  await lifecycle;
+};
+
+export const stopMutiroAccount = async (ctx: StartContext) => {
+  await stopSession(sessionKey("mutiro", ctx.accountId));
+  ctx.setStatus({
+    ...ctx.getStatus(),
+    running: false,
+    connected: false,
+    lastStopAt: Date.now(),
+  });
+};
+
+const stopSession = async (key: string) => {
+  const session = sessions.get(key);
+  if (!session) return;
+  sessions.delete(key);
+  await session.shutdown();
+};
+
+export const sendMutiroText = async (
+  ctx: ChannelOutboundContext,
+): Promise<OutboundDeliveryResult> => {
+  const session = requireSessionForAccount(ctx.accountId);
+  await session.outbound.sendText(
+    {
+      conversationId: ctx.to,
+      replyToMessageId: ctx.replyToId ?? ctx.threadId?.toString() ?? "",
+    },
+    ctx.text,
+  );
+  return {
+    channel: "mutiro",
+    messageId: ctx.replyToId ?? `mutiro-${Date.now()}`,
+    conversationId: ctx.to,
+  };
+};
+
+export const sendMutiroMedia = async (
+  ctx: ChannelOutboundContext,
+): Promise<OutboundDeliveryResult> => {
+  if (!ctx.mediaUrl) {
+    throw new Error("sendMedia called without mediaUrl");
+  }
+  const session = requireSessionForAccount(ctx.accountId);
+  await session.outbound.sendFile(
+    {
+      conversationId: ctx.to,
+      replyToMessageId: ctx.replyToId ?? ctx.threadId?.toString() ?? "",
+    },
+    {
+      filePath: ctx.mediaUrl,
+      caption: ctx.text,
+    },
+  );
+  return {
+    channel: "mutiro",
+    messageId: ctx.replyToId ?? `mutiro-${Date.now()}`,
+    conversationId: ctx.to,
+  };
+};
+
+const formatError = (err: unknown) =>
+  err instanceof Error ? err.message : JSON.stringify(err);
+
+// Dispatcher for ChannelMessageActionAdapter.handleAction. Declared here so
+// the heavy runtime does the bridge work, and the light `actions.ts` file
+// stays a pure control-plane adapter that loads this lazily.
+export const handleMutiroMessageAction = async (params: {
+  action: string;
+  params: Record<string, unknown>;
+  accountId?: string;
+  readStringArg: (params: Record<string, unknown>, ...keys: string[]) => string | undefined;
+}) => {
+  const session = requireSessionForAccount(params.accountId);
+
+  if (params.action === "react") {
+    const messageId = params.readStringArg(params.params, "messageId", "message_id", "to");
+    const emoji = params.readStringArg(params.params, "emoji", "reaction");
+    if (!messageId) {
+      return {
+        content: [{ type: "text" as const, text: "react requires a messageId." }],
+        details: { ok: false, reason: "missing_message_id" },
+      };
+    }
+    if (!emoji) {
+      return {
+        content: [{ type: "text" as const, text: "react requires an emoji." }],
+        details: { ok: false, reason: "missing_emoji" },
+      };
+    }
+    try {
+      const raw = await session.outbound.react({ messageId, emoji });
+      return {
+        content: [{ type: "text" as const, text: `Reacted ${emoji} to ${messageId}.` }],
+        details: { ok: true, raw },
+      };
+    } catch (err) {
+      const message = formatError(err);
+      return {
+        content: [{ type: "text" as const, text: `Failed to react: ${message}` }],
+        details: { ok: false, reason: "bridge_error", error: message },
+      };
+    }
+  }
+
+  return {
+    content: [
+      {
+        type: "text" as const,
+        text: `Unsupported Mutiro message action: ${params.action}`,
+      },
+    ],
+    details: { ok: false, reason: "unsupported_action", action: params.action },
+  };
+};
+
+// Barrel export consumed by the plugin entry via `loadBundledEntryExportSync`.
+export const mutiroChannelRuntime = {
+  startMutiroAccount,
+  stopMutiroAccount,
+  sendMutiroText,
+  sendMutiroMedia,
+};

package/src/channel.ts

@@ -0,0 +1,130 @@
+// OpenClaw channel plugin definition. This file is the "hot" import path
+// loaded during gateway startup and plugin discovery, so it stays narrow:
+// manifest metadata plus a lazy handle into the heavier runtime module.
+//
+// The runtime (`channel.runtime.ts`) owns subprocess lifecycle, envelope
+// dispatch, and the per-account bridge session registry.
+
+import type {
+  ChannelOutboundAdapter,
+  ChannelPlugin,
+} from "openclaw/plugin-sdk/core";
+import { createChatChannelPlugin } from "openclaw/plugin-sdk/core";
+import { createLazyRuntimeNamedExport } from "openclaw/plugin-sdk/lazy-runtime";
+
+import { mutiroMessageActions } from "./actions.js";
+import { mutiroAgentTools } from "./agent-tools.js";
+import { mutiroConfigAdapter, type ResolvedMutiroAccount } from "./config.js";
+import { mutiroSetupAdapter, mutiroSetupWizard } from "./setup-surface.js";
+
+const loadMutiroChannelRuntime = createLazyRuntimeNamedExport(
+  () => import("./channel.runtime.js"),
+  "mutiroChannelRuntime",
+);
+
+const outbound: ChannelOutboundAdapter = {
+  deliveryMode: "direct",
+
+  // `sendText` is called whenever OpenClaw wants to push a text reply into a
+  // Mutiro conversation. The `accountId` selects which active bridge session
+  // to route through; `to` is the Mutiro `conversation_id`; `replyToId` is the
+  // message the reply threads under.
+  async sendText(ctx) {
+    const runtime = await loadMutiroChannelRuntime();
+    return runtime.sendMutiroText(ctx);
+  },
+
+  // `sendMedia` is the single-shot media path. The channel runtime uses the
+  // bridge-local `media.upload` command to stage the file, then attaches it
+  // to a `message.send`.
+  async sendMedia(ctx) {
+    const runtime = await loadMutiroChannelRuntime();
+    return runtime.sendMutiroMedia(ctx);
+  },
+};
+
+export const mutiroPlugin: ChannelPlugin<ResolvedMutiroAccount> = createChatChannelPlugin<
+  ResolvedMutiroAccount
+>({
+  base: {
+    id: "mutiro",
+    meta: {
+      id: "mutiro",
+      label: "Mutiro",
+      selectionLabel: "Mutiro (plugin)",
+      docsPath: "/channels/mutiro",
+      docsLabel: "mutiro",
+      blurb: "chatbridge channel; configure a Mutiro agent directory to enable.",
+      order: 80,
+      quickstartAllowFrom: true,
+      markdownCapable: true,
+    },
+    capabilities: {
+      chatTypes: ["direct", "group"],
+      reactions: true,
+      reply: true,
+      media: true,
+    },
+    config: mutiroConfigAdapter,
+    agentTools: mutiroAgentTools,
+    actions: mutiroMessageActions,
+
+    // Setup surfaces: `setup` is the non-interactive adapter path
+    // (`openclaw channels add --channel mutiro [flags]`); `setupWizard` is what
+    // runs when the user invokes `openclaw channels add` with no flags and
+    // picks `mutiro` from the selection list.
+    setup: mutiroSetupAdapter,
+    setupWizard: mutiroSetupWizard,
+
+    // Messaging adapter: teaches OpenClaw how to recognize a Mutiro target.
+    // Without it, reactions/forwards/cross-channel sends fail with
+    // "Unknown target" because the core resolver can't match a
+    // `conv_<uuid>` conversation id or a leading-@ username against any
+    // directory/id pattern it knows about.
+    messaging: {
+      normalizeTarget: (raw: string) => {
+        const trimmed = raw.trim();
+        if (!trimmed) return undefined;
+        // Strip a leading @ on usernames so downstream comparisons and the
+        // bridge's `to_username` field see the raw handle.
+        return trimmed.startsWith("@") ? trimmed.slice(1) : trimmed;
+      },
+      targetResolver: {
+        hint: "Use a Mutiro conversation id (e.g. conv_<uuid>) or @username.",
+        looksLikeId: (raw: string, normalized?: string) => {
+          const value = (normalized ?? raw).trim();
+          if (!value) return false;
+          // conv_<...> = conversation id; bare @handle or a plain alphanumeric
+          // username both route to message.send_voice / react / etc.
+          return /^conv_/i.test(value) || /^@/.test(raw) || /^[A-Za-z0-9_.-]+$/.test(value);
+        },
+        resolveTarget: async ({ input, normalized }) => {
+          const value = (normalized || input).trim().replace(/^@/, "");
+          if (!value) return null;
+          const isConversation = /^conv_/i.test(value);
+          return {
+            to: value,
+            kind: isConversation ? "group" : "user",
+            display: isConversation ? value : `@${value}`,
+            source: "normalized",
+          };
+        },
+      },
+    },
+
+    // Gateway lifecycle: startAccount spawns the bridge subprocess for this
+    // account and wires inbound observed messages into OpenClaw's reply
+    // dispatcher. stopAccount tears the subprocess down.
+    gateway: {
+      async startAccount(ctx) {
+        const runtime = await loadMutiroChannelRuntime();
+        return runtime.startMutiroAccount(ctx);
+      },
+      async stopAccount(ctx) {
+        const runtime = await loadMutiroChannelRuntime();
+        await runtime.stopMutiroAccount(ctx);
+      },
+    },
+  },
+  outbound,
+});

package/src/config.ts

@@ -0,0 +1,100 @@
+// Mutiro channel configuration and per-account resolution.
+//
+// The channel supports one or more named accounts; each account pins a
+// specific Mutiro agent directory that `mutiro agent host --mode=bridge`
+// should run from. We reuse OpenClaw's `createScopedChannelConfigAdapter` so
+// the account lifecycle (list/default/resolve) flows through the same shape
+// the Plugin SDK already knows how to drive.
+
+import { DEFAULT_ACCOUNT_ID } from "openclaw/plugin-sdk/account-id";
+import type { ChannelPlugin, OpenClawConfig } from "openclaw/plugin-sdk/core";
+
+export { DEFAULT_ACCOUNT_ID };
+
+export type MutiroAccountConfig = {
+  agentDir: string;
+  clientName?: string;
+  requestedOptionalCapabilities?: string[];
+  enabled?: boolean;
+  name?: string;
+};
+
+export type ResolvedMutiroAccount = {
+  accountId: string;
+  enabled: boolean;
+  configured: boolean;
+  name?: string;
+  config: MutiroAccountConfig;
+};
+
+type MutiroChannelSection = {
+  accounts?: Record<string, MutiroAccountConfig & { name?: string; enabled?: boolean }>;
+  // Support single-account shorthand by keeping top-level fields too.
+  agentDir?: string;
+  clientName?: string;
+  requestedOptionalCapabilities?: string[];
+  enabled?: boolean;
+};
+
+const readMutiroSection = (cfg: OpenClawConfig): MutiroChannelSection | undefined => {
+  const channels = (cfg as { channels?: Record<string, unknown> }).channels;
+  return channels?.mutiro as MutiroChannelSection | undefined;
+};
+
+const resolveAccountConfig = (
+  cfg: OpenClawConfig,
+  accountId: string,
+): MutiroAccountConfig | undefined => {
+  const section = readMutiroSection(cfg);
+  if (!section) return undefined;
+
+  if (accountId === DEFAULT_ACCOUNT_ID && section.agentDir) {
+    return {
+      agentDir: section.agentDir,
+      clientName: section.clientName,
+      requestedOptionalCapabilities: section.requestedOptionalCapabilities,
+      enabled: section.enabled,
+    };
+  }
+
+  return section.accounts?.[accountId];
+};
+
+export const listMutiroAccountIds = (cfg: OpenClawConfig): string[] => {
+  const section = readMutiroSection(cfg);
+  const named = Object.keys(section?.accounts ?? {});
+  if (named.length > 0) return named;
+  return section?.agentDir ? [DEFAULT_ACCOUNT_ID] : [];
+};
+
+export const resolveDefaultMutiroAccountId = (cfg: OpenClawConfig): string => {
+  const ids = listMutiroAccountIds(cfg);
+  return ids[0] ?? DEFAULT_ACCOUNT_ID;
+};
+
+export const resolveMutiroAccount = (
+  cfg: OpenClawConfig,
+  accountId?: string | null,
+): ResolvedMutiroAccount => {
+  const id = accountId || resolveDefaultMutiroAccountId(cfg);
+  const base = resolveAccountConfig(cfg, id) ?? { agentDir: "" };
+  const configured = Boolean(base.agentDir);
+  return {
+    accountId: id,
+    enabled: base.enabled !== false,
+    configured,
+    name: base.name,
+    config: base,
+  };
+};
+
+// Build the ChannelConfigAdapter directly. The helpers in
+// `channel-config-helpers` expect allowlist and clear-base-field accessors
+// that Mutiro does not use, so we wire the two required hooks manually.
+export const mutiroConfigAdapter: ChannelPlugin<ResolvedMutiroAccount>["config"] = {
+  listAccountIds: listMutiroAccountIds,
+  resolveAccount: resolveMutiroAccount,
+  defaultAccountId: resolveDefaultMutiroAccountId,
+  isEnabled: (account: ResolvedMutiroAccount) => account.enabled,
+  isConfigured: (account: ResolvedMutiroAccount) => account.configured,
+};