@moltzap/openclaw-channel 2026.511.0 → 2026.519.0

package/dist/openclaw-entry.js

@@ -4,7 +4,7 @@
  * Wraps the existing MoltZapWsClient + mapping modules into the
  * ChannelPlugin shape expected by OpenClaw's api.registerChannel().
  *
- * Installed via: openclaw plugin install @moltzap/openclaw-channel
+ * Installed via: openclaw plugin install `@moltzap/openclaw-channel`
  * Config:        channels.moltzap.accounts[].{apiKey, serverUrl, agentName}
  *
  * OpenClaw's plugin interface imposes Promise-based contracts at the boundary
@@ -13,10 +13,9 @@
  * `Effect.runPromise` tax at the plugin surface.
  */
 import { MoltZapChannelCore, MoltZapService, } from "@moltzap/client";
+import { LeaseAlreadyConsumed, LeaseGuard, catchLeaseInvalid, formatCrossConv, getGroupFields, } from "@moltzap/client/channel-base";
 import { Config, ConfigProvider, Data, Effect, Option } from "effect";
-import { formatCrossConvOpenClaw } from "./format-cross-conv.js";
-import { writeOpenClawContextLog } from "./context-log.js";
-import { extractConversationCreated, extractConversationUpdated, extractContactRequest, extractContactAccepted, extractPresenceChanged, } from "./mapping.js";
+import { writeOpenClawContextLog, } from "./context-log.js";
 import { AgentsLookup, ContactsList, ConversationsList, } from "@moltzap/protocol";
 import { TaskClosedError } from "@moltzap/protocol/task";
 import { RpcServerError } from "@moltzap/protocol/transport";
@@ -24,7 +23,6 @@ const DEFAULT_ACCOUNT_ID = "default";
 const CHANNEL_ID = "moltzap";
 const TARGET_PREFIX_AGENT = "agent:";
 const TARGET_PREFIX_CONV = "conv:";
-const OPENCLAW_STRUCTURED_LOG_MIN_ARGS = 2;
 const INBOUND_LOG_PREVIEW_CHARS = 80;
 const BODY_FOR_AGENT_LOG_PREVIEW_CHARS = 500;
 const OUTBOUND_LOG_PREVIEW_CHARS = 80;
@@ -41,19 +39,30 @@ class MoltZapClientNotConnectedError extends Data.TaggedError("MoltZapClientNotC
         return `MoltZap client not connected for account ${this.accountId}`;
     }
 }
-function adaptOpenClawLogger(logMethod) {
-    return (...args) => {
-        if (!logMethod)
-            return;
-        if (args.length >= OPENCLAW_STRUCTURED_LOG_MIN_ARGS &&
-            typeof args[0] === "object" &&
-            args[0] !== null &&
-            typeof args[1] === "string") {
-            logMethod(args[1], args[0]);
-            return;
-        }
-        logMethod(...args);
-    };
+class MoltZapAgentTargetUnsupportedError extends Data.TaggedError("MoltZapAgentTargetUnsupportedError") {
+    get message() {
+        return `MoltZap client for account ${this.accountId} cannot resolve agent targets`;
+    }
+}
+class OpenClawTargetResolved extends Data.TaggedClass("OpenClawTargetResolved") {
+    ok = true;
+}
+class OpenClawTargetRejected extends Data.TaggedClass("OpenClawTargetRejected") {
+    ok = false;
+}
+class OpenClawSendTextSuccess extends Data.TaggedClass("OpenClawSendTextSuccess") {
+    ok = true;
+}
+class OpenClawSendTextFailure extends Data.TaggedClass("OpenClawSendTextFailure") {
+    ok = false;
+}
+function logContextLogWriteFailure(log, error) {
+    return Effect.sync(() => {
+        log?.warn?.(`MoltZap: failed to write OpenClaw context log: ${error instanceof Error ? error.message : String(error)}`);
+    });
+}
+function writeContextLogOrWarn(log, input) {
+    return writeOpenClawContextLog(input).pipe(Effect.catchAll((error) => logContextLogWriteFailure(log, error)));
 }
 function resolveAccountList(cfg) {
     const section = cfg.channels?.moltzap;
@@ -80,402 +89,552 @@ const waitForAbort = (signal) => Effect.async((resume) => {
     }
     signal.addEventListener("abort", () => resume(Effect.void), { once: true });
 });
-/**
- * Factory: returns a fresh plugin object whose `activeClients` map lives in
- * this closure. `register(api)` calls this so each registration gets its own
- * per-plugin state, eliminating module-level mutable globals.
- */
-// eslint-disable-next-line agent-code-guard/manual-result -- OpenClaw plugin factory returns the channel object shape, not a reusable Result/Either algebra.
-export function createMoltzapChannelPlugin() {
-    const activeClients = new Map();
+function contactAgentIds(contact) {
+    return (contact.agents ?? []).map((agent) => agent.id);
+}
+function logOutboundReply(log, conversationId, text) {
+    return Effect.sync(() => {
+        log?.info?.(`MoltZap: outbound reply to ${conversationId}: ${text.slice(0, OUTBOUND_LOG_PREVIEW_CHARS)}`);
+    });
+}
+function isTaskClosedRpcError(err) {
+    return err instanceof RpcServerError && err.code === TaskClosedError.code;
+}
+function handleReplyFailure(log, conversationId, err) {
+    return Effect.sync(() => {
+        if (isTaskClosedRpcError(err)) {
+            log?.warn?.({
+                conversationId,
+                code: err.code,
+                msg: err.message,
+            }, "MoltZap: send rejected; task closed, dropping without retry");
+            return true;
+        }
+        log?.error?.(`MoltZap: failed to send reply: ${err}`);
+        return false;
+    });
+}
+function sendDeliveredReply(params) {
+    return params.core
+        .sendReply(params.conversationId, params.text, params.leaseId !== undefined
+        ? { dispatchLeaseId: params.leaseId }
+        : undefined)
+        .pipe(catchLeaseInvalid(params.leaseId !== undefined ? { leaseId: params.leaseId } : undefined), 
+    // Stamp the guard only on a successful `core.sendReply` (matches the
+    // pre-refactor `markConsumed` ordering). Transient send failures fall
+    // through to `Effect.catchAll` below WITHOUT stamping, so a retried
+    // deliver call still exercises the lease — see
+    // `openclaw-entry.delivery.test.ts → "lease guard stays unconsumed on
+    // transient send failure"` regression test.
+    Effect.tap(() => params.guard.consume()), Effect.tap(() => logOutboundReply(params.log, params.conversationId, params.text)), Effect.map(() => true), Effect.catchAll((err) => handleDeliverFailure({
+        log: params.log,
+        conversationId: params.conversationId,
+        onLeaseConsumed: params.onLeaseConsumed,
+        err,
+    })));
+}
+function handleDeliverFailure(params) {
+    const { log, conversationId, onLeaseConsumed, err } = params;
+    if (err instanceof LeaseAlreadyConsumed) {
+        return Effect.sync(() => {
+            log?.warn?.(`MoltZap: lease ${err.leaseId} already consumed for ${conversationId} at ts=${err.consumedAt.toString()}; surfacing via onLeaseConsumed`);
+            onLeaseConsumed?.(err);
+            // Deliver contract: PromiseLike<boolean>. False signals "not delivered"
+            // without violating the type.
+            return false;
+        });
+    }
+    return handleReplyFailure(log, conversationId, err);
+}
+function createLeaseConsumingDeliver(params) {
+    // One LeaseGuard per inbound message: stamped exactly once, on the FIRST
+    // successful `core.sendReply`. Replaces the pre-refactor
+    // `consumedLeaseAt: number | null` closure.
+    //
+    // Ordering matters: pre-check `guard.consumedAt` BEFORE sending so duplicate
+    // delivers are short-circuited; the actual stamp happens inside
+    // `sendDeliveredReply` via `Effect.tap(() => guard.consume())` AFTER
+    // `core.sendReply` succeeds. A transient send failure therefore leaves the
+    // guard unconsumed, and a retried deliver call still exercises the lease —
+    // matching pre-refactor behavior (`markConsumed` in the success tap).
+    const guard = new LeaseGuard();
+    return (payload, info) => {
+        if (info?.kind !== "final")
+            return Promise.resolve(true);
+        const text = payload.text ?? payload.body;
+        if (!text)
+            return Promise.resolve(true);
+        return Effect.runPromise(Effect.gen(function* () {
+            const stamped = yield* guard.consumedAt;
+            if (Option.isSome(stamped)) {
+                params.log?.warn?.(`MoltZap: duplicate-reply rejected for ${params.enriched.conversationId} (lease already consumed at ts=${stamped.value.toString()})`);
+                return false;
+            }
+            return yield* sendDeliveredReply({
+                core: params.core,
+                conversationId: params.enriched.conversationId,
+                text,
+                leaseId: params.enriched.dispatchLeaseId,
+                log: params.log,
+                onLeaseConsumed: params.onLeaseConsumed,
+                guard,
+            });
+        }));
+    };
+}
+function buildInboundDispatchContext(input) {
+    return {
+        Body: input.enriched.text,
+        BodyForAgent: input.bodyForAgent,
+        From: input.fromId,
+        To: input.account.agentName ?? input.accountId,
+        SessionKey: `agent:main:moltzap:${input.chatType === "group" ? "group" : "dm"}:${input.enriched.conversationId}`,
+        AccountId: input.accountId,
+        Provider: CHANNEL_ID,
+        Surface: CHANNEL_ID,
+        OriginatingChannel: CHANNEL_ID,
+        OriginatingTo: input.enriched.conversationId,
+        ChatType: input.chatType,
+        ...(input.groupSubject ? { GroupSubject: input.groupSubject } : {}),
+        ...(input.groupMembers ? { GroupMembers: input.groupMembers } : {}),
+        ...(input.enriched.conversationMeta?.name
+            ? { ConversationLabel: input.enriched.conversationMeta.name }
+            : {}),
+        SenderName: input.enriched.sender.name,
+    };
+}
+function logDispatchError(log, err) {
+    return Effect.sync(() => {
+        log?.error?.(`MoltZap: dispatch error: ${err}`);
+        return null;
+    });
+}
+function dispatchInboundReply(params) {
+    return Effect.tryPromise({
+        try: () => params.dispatch({
+            ctx: buildInboundDispatchContext(params.input),
+            cfg: params.input.cfg,
+            dispatcherOptions: {
+                deliver: createLeaseConsumingDeliver({
+                    core: params.core,
+                    enriched: params.input.enriched,
+                    log: params.log,
+                    onLeaseConsumed: params.onLeaseConsumed,
+                }),
+            },
+        }),
+        catch: (err) => err,
+    }).pipe(Effect.catchAll((err) => logDispatchError(params.log, err)));
+}
+function disconnectCoreOnAbort(core, activeClients, accountId) {
+    Effect.runFork(core
+        .disconnect()
+        .pipe(Effect.ensuring(Effect.sync(() => activeClients.delete(accountId)))));
+}
+function createPluginMeta() {
     return {
         id: CHANNEL_ID,
-        meta: {
-            id: CHANNEL_ID,
-            label: "MoltZap",
-            selectionLabel: "MoltZap (agent messaging)",
-            docsPath: "/channels/moltzap",
-            docsLabel: "moltzap",
-            blurb: "Agent-to-agent messaging via the MoltZap protocol.",
-            detailLabel: "MoltZap",
-            aliases: ["mz"],
-            order: 200,
+        label: "MoltZap",
+        selectionLabel: "MoltZap (agent messaging)",
+        docsPath: "/channels/moltzap",
+        docsLabel: "moltzap",
+        blurb: "Agent-to-agent messaging via the MoltZap protocol.",
+        detailLabel: "MoltZap",
+        aliases: ["mz"],
+        order: 200,
+    };
+}
+function createMessagingSection() {
+    return {
+        targetResolver: {
+            looksLikeId(raw) {
+                return isMoltZapTarget(raw);
+            },
+            hint: 'Use "agent:<name>" for DMs or "conv:<id>" for existing conversations',
+            resolveTarget(params) {
+                const { normalized } = params;
+                if (!isMoltZapTarget(normalized))
+                    return Promise.resolve(null);
+                const kind = normalized.startsWith(TARGET_PREFIX_CONV)
+                    ? "group"
+                    : "user";
+                return Promise.resolve({
+                    to: normalized,
+                    kind,
+                    display: normalized.split(":").slice(1).join(":"),
+                    source: "normalized",
+                });
+            },
         },
-        capabilities: {
-            chatTypes: ["dm", "group"],
+    };
+}
+function createDirectorySection(activeClients) {
+    return {
+        listPeers(params) {
+            return Effect.runPromise(listPeersEffect(activeClients, params));
         },
-        messaging: {
-            targetResolver: {
-                looksLikeId(raw) {
-                    return isMoltZapTarget(raw);
-                },
-                hint: 'Use "agent:<name>" for DMs or "conv:<id>" for existing conversations',
-                resolveTarget(params) {
-                    const { normalized } = params;
-                    if (!isMoltZapTarget(normalized))
-                        return Promise.resolve(null);
-                    // "user" = DM target (agent:*), "group" = conversation target (conv:*)
-                    const kind = normalized.startsWith(TARGET_PREFIX_CONV)
-                        ? "group"
-                        : "user";
-                    return Promise.resolve({
-                        to: normalized,
-                        kind,
-                        display: normalized.split(":").slice(1).join(":"),
-                        source: "normalized",
-                    });
-                },
-            },
+        listGroups(params) {
+            return Effect.runPromise(listGroupsEffect(activeClients, params));
         },
-        directory: {
-            listPeers(params) {
-                const effect = Effect.gen(function* () {
-                    const service = activeClients.get(params.accountId ?? DEFAULT_ACCOUNT_ID);
-                    if (!service)
-                        return [];
-                    const { contacts } = (yield* service.sendRpc(ContactsList, {}));
-                    const agentIds = contacts.flatMap((c) => (c.agents ?? []).map((a) => a.id));
-                    if (agentIds.length === 0)
-                        return [];
-                    const { agents } = (yield* service.sendRpc(AgentsLookup, {
-                        agentIds,
-                    }));
-                    return agents.map((a) => ({
-                        id: `agent:${a.name}`,
-                        name: a.displayName ?? a.name,
-                        kind: "user",
-                    }));
-                }).pipe(Effect.catchAll(() => Effect.succeed([])));
-                return Effect.runPromise(effect);
-            },
-            listGroups(params) {
-                const effect = Effect.gen(function* () {
-                    const service = activeClients.get(params.accountId ?? DEFAULT_ACCOUNT_ID);
-                    if (!service)
-                        return [];
-                    const { conversations } = (yield* service.sendRpc(ConversationsList, {}));
-                    return conversations
-                        .filter((c) => c.type === "group" && c.name)
-                        .map((c) => ({
-                        id: `conv:${c.id}`,
-                        name: c.name,
-                        kind: "group",
-                    }));
-                }).pipe(Effect.catchAll(() => Effect.succeed([])));
-                return Effect.runPromise(effect);
-            },
+    };
+}
+function getActiveService(activeClients, accountId) {
+    return activeClients.get(accountId ?? DEFAULT_ACCOUNT_ID);
+}
+function listPeersEffect(activeClients, params) {
+    return Effect.gen(function* () {
+        const service = getActiveService(activeClients, params.accountId);
+        if (!service?.sendRpc)
+            return [];
+        const { contacts } = (yield* service.sendRpc(ContactsList, {}));
+        const agentIds = contacts.flatMap(contactAgentIds);
+        if (agentIds.length === 0)
+            return [];
+        const { agents } = (yield* service.sendRpc(AgentsLookup, { agentIds }));
+        return agents.map((agent) => ({
+            id: `agent:${agent.name}`,
+            name: agent.displayName ?? agent.name,
+            kind: "user",
+        }));
+    }).pipe(Effect.withSpan("createMoltzapChannelPlugin.listPeers"), Effect.catchAll(() => Effect.succeed([])));
+}
+function listGroupsEffect(activeClients, params) {
+    return Effect.gen(function* () {
+        const service = getActiveService(activeClients, params.accountId);
+        if (!service?.sendRpc)
+            return [];
+        const { conversations } = (yield* service.sendRpc(ConversationsList, {}));
+        return conversations.filter(isNamedGroup).map((conversation) => ({
+            id: `conv:${conversation.id}`,
+            name: conversation.name,
+            kind: "group",
+        }));
+    }).pipe(Effect.withSpan("createMoltzapChannelPlugin.listGroups"), Effect.catchAll(() => Effect.succeed([])));
+}
+function isNamedGroup(conversation) {
+    return conversation.type === "group" && conversation.name !== undefined;
+}
+function createConfigSection() {
+    return {
+        listAccountIds(cfg) {
+            const accounts = resolveAccountList(cfg);
+            return accounts.length > 0
+                ? accounts.map((account) => account.id || DEFAULT_ACCOUNT_ID)
+                : [];
         },
-        config: {
-            listAccountIds(cfg) {
-                const accounts = resolveAccountList(cfg);
-                return accounts.length > 0
-                    ? accounts.map((a) => a.id || DEFAULT_ACCOUNT_ID)
-                    : [];
-            },
-            resolveAccount(cfg, accountId) {
-                return resolveAccount(cfg, accountId);
-            },
-            isConfigured(account) {
-                return Boolean(account.apiKey && account.serverUrl);
-            },
-            unconfiguredReason() {
-                return "missing apiKey or serverUrl";
-            },
-            isEnabled(account) {
-                return account.enabled !== false;
-            },
+        resolveAccount(cfg, accountId) {
+            return resolveAccount(cfg, accountId ?? DEFAULT_ACCOUNT_ID);
         },
-        gateway: {
-            startAccount(ctx) {
-                const { accountId, account, abortSignal, log, setStatus } = ctx;
-                const contextLogDir = readOpenClawContextLogDir();
-                if (!account.apiKey || !account.serverUrl) {
-                    log?.error?.("MoltZap: missing apiKey or serverUrl");
-                    return Promise.resolve();
-                }
-                log?.info?.(`MoltZap: connecting as ${account.agentName} to ${account.serverUrl}`);
-                const wsLogger = log
-                    ? {
-                        info: adaptOpenClawLogger(log.info),
-                        warn: adaptOpenClawLogger(log.warn),
-                        error: adaptOpenClawLogger(log.error),
-                    }
-                    : undefined;
-                const service = new MoltZapService({
-                    serverUrl: account.serverUrl,
-                    agentKey: account.apiKey,
-                    logger: wsLogger,
-                });
-                const core = new MoltZapChannelCore({ service, logger: wsLogger });
-                core.onInbound((enriched) => Effect.gen(function* () {
-                    const chatType = enriched.conversationMeta?.type === "group" ? "group" : "direct";
-                    const fromId = `agent:${enriched.sender.id}`;
-                    log?.info?.(`MoltZap: inbound from ${fromId}: ${enriched.text.slice(0, INBOUND_LOG_PREVIEW_CHARS)}`);
-                    setStatus({
-                        accountId,
-                        lastInboundAt: Date.now(),
-                        lastEventAt: Date.now(),
-                    });
-                    const crossConvBlock = formatCrossConvOpenClaw(enriched.contextBlocks.crossConversationMessages ?? [], { ownAgentId: service.ownAgentId ?? "" });
-                    const crossConversationMessages = enriched.contextBlocks.crossConversationMessages ?? [];
-                    const bodyForAgent = crossConvBlock
-                        ? `${crossConvBlock}\n\n${enriched.text}`
-                        : enriched.text;
-                    try {
-                        writeOpenClawContextLog({
-                            logDir: contextLogDir,
-                            accountId,
-                            accountAgentName: account.agentName,
-                            ownAgentId: service.ownAgentId,
-                            conversationId: enriched.conversationId,
-                            conversationName: enriched.conversationMeta?.name,
-                            conversationType: chatType,
-                            from: fromId,
-                            to: account.agentName ?? accountId,
-                            body: enriched.text,
-                            bodyForAgent,
-                            crossConversationMessages,
-                        });
-                    }
-                    catch (error) {
-                        log?.warn?.(`MoltZap: failed to write OpenClaw context log: ${error instanceof Error ? error.message : String(error)}`);
-                    }
-                    if (crossConvBlock) {
-                        log?.info?.(`MoltZap: BodyForAgent has cross-conv context (${crossConversationMessages.length} msgs) for ${enriched.conversationId}: ${bodyForAgent.slice(0, BODY_FOR_AGENT_LOG_PREVIEW_CHARS)}`);
-                    }
-                    const dispatch = ctx.channelRuntime?.reply
-                        ?.dispatchReplyWithBufferedBlockDispatcher;
-                    if (!dispatch) {
-                        log?.warn?.(`MoltZap: no OpenClaw reply dispatcher for ${enriched.conversationId}`);
-                        return;
-                    }
-                    const groupSubject = enriched.conversationMeta?.name;
-                    const groupMembers = enriched.conversationMeta?.type === "group"
-                        ? enriched.conversationMeta.participants.join(",")
-                        : undefined;
-                    // Bridge OpenClaw's Promise-shaped dispatch into Effect, then
-                    // catchAll back to a logged no-op so a single failed reply doesn't
-                    // crash the consumer fiber.
-                    log?.info?.(`MoltZap: dispatch start for ${enriched.conversationId} message ${enriched.id}`);
-                    const result = yield* Effect.tryPromise({
-                        try: () => dispatch({
-                            ctx: {
-                                Body: enriched.text,
-                                BodyForAgent: bodyForAgent,
-                                From: fromId,
-                                To: account.agentName ?? accountId,
-                                SessionKey: `agent:main:moltzap:${chatType === "group" ? "group" : "dm"}:${enriched.conversationId}`,
-                                AccountId: accountId,
-                                Provider: CHANNEL_ID,
-                                Surface: CHANNEL_ID,
-                                OriginatingChannel: CHANNEL_ID,
-                                OriginatingTo: enriched.conversationId,
-                                ChatType: chatType,
-                                ...(groupSubject ? { GroupSubject: groupSubject } : {}),
-                                ...(groupMembers ? { GroupMembers: groupMembers } : {}),
-                                ...(enriched.conversationMeta?.name
-                                    ? { ConversationLabel: enriched.conversationMeta.name }
-                                    : {}),
-                                SenderName: enriched.sender.name,
-                            },
-                            cfg: ctx.cfg,
-                            dispatcherOptions: {
-                                // Cutover #533 — single-use lease semantics. The
-                                // first `final` delivery consumes the dispatch
-                                // lease via core.sendReply; any subsequent `final`
-                                // delivery is rejected at this adapter boundary
-                                // with `OpenclawDuplicateReplyError` and surfaced
-                                // to OpenClaw as `false` (delivery failure).
-                                // OpenClaw's retry policy under "delivery failed
-                                // because lease consumed" is OQ-2 in the architect
-                                // plan; the recommended default (SURFACE as false)
-                                // is what we ship.
-                                deliver: (() => {
-                                    let consumedLeaseAt = null;
-                                    return (payload, info) => {
-                                        if (info?.kind !== "final")
-                                            return Promise.resolve(true);
-                                        const text = payload.text ?? payload.body;
-                                        if (!text)
-                                            return Promise.resolve(true);
-                                        if (consumedLeaseAt !== null) {
-                                            log?.warn?.(`MoltZap: duplicate-reply rejected for ${enriched.conversationId} (lease already consumed at ts=${consumedLeaseAt.toString()})`);
-                                            return Promise.resolve(false);
-                                        }
-                                        // core.sendReply is Effect-native; run it at
-                                        // the OpenClaw boundary which demands a
-                                        // Promise.
-                                        const deliverEffect = core
-                                            .sendReply(enriched.conversationId, text)
-                                            .pipe(Effect.tap(() => Effect.sync(() => {
-                                            consumedLeaseAt = Date.now();
-                                            log?.info?.(`MoltZap: outbound reply to ${enriched.conversationId}: ${text.slice(0, OUTBOUND_LOG_PREVIEW_CHARS)}`);
-                                        })), Effect.map(() => true), Effect.catchTag("RpcServerError", (err) => Effect.sync(() => {
-                                            if (err.code === TaskClosedError.code) {
-                                                // Task is closed — message is terminal.
-                                                // Signal consumed (true) so the caller
-                                                // does not retry delivery.
-                                                log?.warn?.({
-                                                    conversationId: enriched.conversationId,
-                                                    code: err.code,
-                                                    msg: err.message,
-                                                }, "MoltZap: send rejected — task closed, dropping without retry");
-                                                return true;
-                                            }
-                                            log?.error?.(`MoltZap: failed to send reply: ${err}`);
-                                            return false;
-                                        })), Effect.catchAll((err) => Effect.sync(() => {
-                                            log?.error?.(`MoltZap: failed to send reply: ${err}`);
-                                            return false;
-                                        })));
-                                        return Effect.runPromise(deliverEffect);
-                                    };
-                                })(),
-                            },
-                        }),
-                        catch: (err) => err,
-                    }).pipe(Effect.catchAll((err) => Effect.sync(() => {
-                        log?.error?.(`MoltZap: dispatch error: ${err}`);
-                        return null;
-                    })));
-                    log?.info?.(`MoltZap: dispatch finished for ${enriched.conversationId} message ${enriched.id}`);
-                    if (result && !result.queuedFinal) {
-                        log?.debug?.(`MoltZap: dispatch completed without final reply for ${enriched.conversationId}`);
-                    }
-                }));
-                // Forward non-message events for status/logging.
-                // Sync dispatcher: log + setStatus only.
-                service.on("rawNotification", (event) => {
-                    const created = extractConversationCreated(event);
-                    if (created) {
-                        log?.debug?.(`MoltZap: conversation created ${created.conversation.id}`);
-                        setStatus({ accountId, lastEventAt: Date.now() });
-                        return;
-                    }
-                    const updated = extractConversationUpdated(event);
-                    if (updated) {
-                        log?.debug?.(`MoltZap: conversation updated ${updated.conversation.id}`);
-                        setStatus({ accountId, lastEventAt: Date.now() });
-                        return;
-                    }
-                    const contactRequest = extractContactRequest(event);
-                    if (contactRequest) {
-                        log?.debug?.(`MoltZap: contact request from ${contactRequest.contact.contactUserId}`);
-                        setStatus({ accountId, lastEventAt: Date.now() });
-                        return;
-                    }
-                    const contactAccepted = extractContactAccepted(event);
-                    if (contactAccepted) {
-                        log?.debug?.(`MoltZap: contact accepted ${contactAccepted.contact.id}`);
-                        setStatus({ accountId, lastEventAt: Date.now() });
-                        return;
-                    }
-                    const presence = extractPresenceChanged(event);
-                    if (presence) {
-                        log?.debug?.(`MoltZap: ${presence.agentId} is now ${presence.status}`);
-                        setStatus({ accountId, lastEventAt: Date.now() });
-                    }
-                });
-                core.onDisconnect(() => {
-                    log?.warn?.("MoltZap: disconnected");
-                    setStatus({
-                        accountId,
-                        connected: false,
-                        lastDisconnect: { at: Date.now() },
-                    });
-                });
-                core.onReconnect(() => {
-                    log?.info?.("MoltZap: reconnected");
-                    setStatus({
-                        accountId,
-                        connected: true,
-                        lastConnectedAt: Date.now(),
-                    });
-                });
-                activeClients.set(accountId, service);
-                if (abortSignal.aborted) {
-                    return Effect.runPromise(core
-                        .disconnect()
-                        .pipe(Effect.tap(() => Effect.sync(() => activeClients.delete(accountId)))));
-                }
-                abortSignal.addEventListener("abort", () => {
-                    void Effect.runPromise(core.disconnect());
-                    activeClients.delete(accountId);
-                }, { once: true });
-                return Effect.runPromise(core.connect().pipe(Effect.tap(() => Effect.sync(() => {
-                    service.startSocketServer();
-                    log?.info?.(`MoltZap: connected as ${account.agentName} (${service.ownAgentId})`);
-                    setStatus({
-                        accountId,
-                        connected: true,
-                        lastConnectedAt: Date.now(),
-                    });
-                })), Effect.zipRight(waitForAbort(abortSignal)), Effect.catchAll((err) => Effect.sync(() => {
-                    log?.error?.(`MoltZap: connection failed: ${err}`);
-                }).pipe(Effect.zipRight(Effect.fail(err))))));
-            },
-            stopAccount(ctx) {
-                const service = activeClients.get(ctx.accountId);
-                if (service) {
-                    ctx.log?.info?.("MoltZap: stopping");
-                    service.close();
-                    activeClients.delete(ctx.accountId);
-                }
-                return Promise.resolve();
-            },
+        isConfigured(account) {
+            return Boolean(account.apiKey && account.serverUrl);
         },
-        outbound: {
-            deliveryMode: "gateway",
-            resolveTarget(params) {
-                const to = params.to?.trim();
-                if (!to) {
-                    return {
-                        ok: false,
-                        error: new Error("MoltZap: target is required"),
-                    };
-                }
-                if (to.includes(":") && !isMoltZapTarget(to)) {
-                    return {
-                        ok: false,
-                        error: new Error(`MoltZap: unsupported target format "${to}" — use agent:<name> or conv:<id>`),
-                    };
-                }
-                return { ok: true, to };
-            },
-            sendText(ctx) {
-                const effect = Effect.gen(function* () {
-                    const accountId = ctx.accountId ?? DEFAULT_ACCOUNT_ID;
-                    const service = activeClients.get(accountId);
-                    if (!service) {
-                        return yield* Effect.fail(new MoltZapClientNotConnectedError({ accountId }));
-                    }
-                    if (ctx.to.startsWith(TARGET_PREFIX_AGENT)) {
-                        const agentName = ctx.to.slice(TARGET_PREFIX_AGENT.length);
-                        yield* service.sendToAgent(agentName, ctx.text, {
-                            replyTo: ctx.replyToId,
-                        });
-                    }
-                    else {
-                        const conversationId = ctx.to.startsWith(TARGET_PREFIX_CONV)
-                            ? ctx.to.slice(TARGET_PREFIX_CONV.length)
-                            : ctx.to;
-                        yield* service.send(conversationId, ctx.text, {
-                            replyTo: ctx.replyToId,
-                        });
-                    }
-                    return { ok: true };
-                }).pipe(Effect.match({
-                    onSuccess: (ok) => ok,
-                    onFailure: (err) => ({
-                        ok: false,
-                        error: err instanceof Error ? err : new Error(String(err)),
-                    }),
-                }));
-                return Effect.runPromise(effect);
-            },
+        unconfiguredReason() {
+            return "missing apiKey or serverUrl";
+        },
+        isEnabled(account) {
+            return account.enabled !== false;
+        },
+    };
+}
+function createGatewaySection(activeClients, deps) {
+    return {
+        startAccount(ctx) {
+            return startGatewayAccount(ctx, activeClients, deps);
+        },
+        stopAccount(ctx) {
+            return stopGatewayAccount(ctx, activeClients);
+        },
+    };
+}
+function startGatewayAccount(ctx, activeClients, deps) {
+    const { accountId, account, abortSignal, log, setStatus } = ctx;
+    const contextLogDir = readOpenClawContextLogDir();
+    if (isMissingAccountConfig(account)) {
+        log?.error?.("MoltZap: missing apiKey or serverUrl");
+        return Promise.resolve();
+    }
+    log?.info?.(`MoltZap: connecting as ${account.agentName} to ${account.serverUrl}`);
+    const service = createGatewayService(account, deps);
+    const core = createGatewayCore(service, deps);
+    registerInboundHandler({
+        core,
+        ctx,
+        service,
+        contextLogDir,
+        onLeaseConsumed: deps.onLeaseConsumed,
+    });
+    registerConnectionStatus(core, ctx);
+    activeClients.set(accountId, service);
+    if (abortSignal.aborted) {
+        return Effect.runPromise(disconnectAndRemove(core, activeClients, accountId));
+    }
+    abortSignal.addEventListener("abort", () => disconnectCoreOnAbort(core, activeClients, accountId), { once: true });
+    return Effect.runPromise(connectGatewayCore(core, service, ctx, setStatus));
+}
+function isMissingAccountConfig(account) {
+    return !account.apiKey || !account.serverUrl;
+}
+function createGatewayService(account, deps) {
+    if (deps.createService)
+        return deps.createService(account);
+    return new MoltZapService({
+        serverUrl: account.serverUrl,
+        agentKey: account.apiKey,
+    });
+}
+function createGatewayCore(service, deps) {
+    if (deps.createCore)
+        return deps.createCore(service);
+    return new MoltZapChannelCore({ service });
+}
+function disconnectAndRemove(core, activeClients, accountId) {
+    return core
+        .disconnect()
+        .pipe(Effect.tap(() => Effect.sync(() => activeClients.delete(accountId))));
+}
+function registerInboundHandler(params) {
+    params.core.onInbound((enriched) => handleInboundMessage({
+        ctx: params.ctx,
+        core: params.core,
+        service: params.service,
+        contextLogDir: params.contextLogDir,
+        enriched,
+        onLeaseConsumed: params.onLeaseConsumed,
+    }).pipe(Effect.withSpan("createMoltzapChannelPlugin.inboundDispatch")));
+}
+function handleInboundMessage(params) {
+    return Effect.gen(function* () {
+        const data = inboundRuntimeData(params.enriched, params.service);
+        logInboundMessage(params.ctx.log, params.enriched, data.fromId);
+        touchInboundStatus(params.ctx);
+        yield* writeInboundContextLog(params, data);
+        logCrossConversationContext(params.ctx.log, params.enriched, data);
+        const dispatch = params.ctx.channelRuntime?.reply
+            ?.dispatchReplyWithBufferedBlockDispatcher;
+        if (!dispatch) {
+            logMissingDispatcher(params.ctx.log, params.enriched.conversationId);
+            return;
+        }
+        const result = yield* dispatchInboundReply({
+            dispatch,
+            input: inboundDispatchInput(params.ctx, params.enriched, data),
+            core: params.core,
+            log: params.ctx.log,
+            onLeaseConsumed: params.onLeaseConsumed,
+        });
+        logDispatchFinished(params.ctx.log, params.enriched);
+        logUnqueuedDispatch(params.ctx.log, params.enriched, result);
+    });
+}
+function inboundRuntimeData(enriched, service) {
+    const groupFields = getGroupFields(enriched.conversationMeta);
+    const crossConversationMessages = crossConversationMessagesFor(enriched);
+    const crossConvBlock = formatCrossConv(crossConversationMessages, {
+        ownAgentId: service.ownAgentId ?? "",
+        markup: "json-header",
+    });
+    return {
+        chatType: groupFields !== null ? "group" : "direct",
+        fromId: `agent:${enriched.sender.id}`,
+        crossConvBlock,
+        crossConversationMessages,
+        bodyForAgent: bodyForAgent(enriched.text, crossConvBlock),
+        groupSubject: groupFields?.name,
+        groupMembers: groupMembersFor(groupFields),
+    };
+}
+function crossConversationMessagesFor(enriched) {
+    return enriched.contextBlocks.crossConversationMessages ?? [];
+}
+function bodyForAgent(text, crossConvBlock) {
+    return crossConvBlock ? `${crossConvBlock}\n\n${text}` : text;
+}
+// P3 #608 resolution: `groupMembersFor` stays openclaw-local because the
+// comma-joined string format is openclaw-specific (the `GroupMembers`
+// dispatch-context field shape). Channel-base's `getGroupFields` provides
+// the narrowing; this helper does the openclaw-side join.
+function groupMembersFor(fields) {
+    if (fields === null)
+        return undefined;
+    return fields.participants.join(",");
+}
+function logInboundMessage(log, enriched, fromId) {
+    log?.info?.(`MoltZap: inbound from ${fromId}: ${enriched.text.slice(0, INBOUND_LOG_PREVIEW_CHARS)}`);
+}
+function touchInboundStatus(ctx) {
+    ctx.setStatus({
+        accountId: ctx.accountId,
+        lastInboundAt: Date.now(),
+        lastEventAt: Date.now(),
+    });
+}
+function writeInboundContextLog(params, data) {
+    return writeContextLogOrWarn(params.ctx.log, {
+        logDir: params.contextLogDir,
+        accountId: params.ctx.accountId,
+        accountAgentName: params.ctx.account.agentName,
+        ownAgentId: params.service.ownAgentId,
+        conversationId: params.enriched.conversationId,
+        conversationName: params.enriched.conversationMeta?.name,
+        conversationType: data.chatType,
+        from: data.fromId,
+        to: params.ctx.account.agentName ?? params.ctx.accountId,
+        body: params.enriched.text,
+        bodyForAgent: data.bodyForAgent,
+        crossConversationMessages: data.crossConversationMessages,
+    });
+}
+function logCrossConversationContext(log, enriched, data) {
+    if (!data.crossConvBlock)
+        return;
+    log?.info?.(`MoltZap: BodyForAgent has cross-conv context (${data.crossConversationMessages.length} msgs) for ${enriched.conversationId}: ${data.bodyForAgent.slice(0, BODY_FOR_AGENT_LOG_PREVIEW_CHARS)}`);
+}
+function logMissingDispatcher(log, conversationId) {
+    log?.warn?.(`MoltZap: no OpenClaw reply dispatcher for ${conversationId}`);
+}
+function inboundDispatchInput(ctx, enriched, data) {
+    return {
+        accountId: ctx.accountId,
+        account: ctx.account,
+        cfg: ctx.cfg,
+        chatType: data.chatType,
+        fromId: data.fromId,
+        bodyForAgent: data.bodyForAgent,
+        groupMembers: data.groupMembers,
+        groupSubject: data.groupSubject,
+        enriched,
+    };
+}
+function logDispatchFinished(log, enriched) {
+    log?.info?.(`MoltZap: dispatch finished for ${enriched.conversationId} message ${enriched.id}`);
+}
+function logUnqueuedDispatch(log, enriched, result) {
+    if (!result || result.queuedFinal)
+        return;
+    log?.debug?.(`MoltZap: dispatch completed without final reply for ${enriched.conversationId}`);
+}
+function registerConnectionStatus(core, ctx) {
+    core.onDisconnect(() => {
+        ctx.log?.warn?.("MoltZap: disconnected");
+        ctx.setStatus({
+            accountId: ctx.accountId,
+            connected: false,
+            lastDisconnect: { at: Date.now() },
+        });
+    });
+    core.onReconnect(() => {
+        ctx.log?.info?.("MoltZap: reconnected");
+        ctx.setStatus({
+            accountId: ctx.accountId,
+            connected: true,
+            lastConnectedAt: Date.now(),
+        });
+    });
+}
+function connectGatewayCore(core, service, ctx, setStatus) {
+    return core.connect().pipe(Effect.tap(() => reportConnected(service, ctx, setStatus)), Effect.zipRight(waitForAbort(ctx.abortSignal)), Effect.catchAll((err) => logConnectionFailure(ctx.log, err)));
+}
+function reportConnected(service, ctx, setStatus) {
+    return Effect.sync(() => {
+        ctx.log?.info?.(`MoltZap: connected as ${ctx.account.agentName} (${service.ownAgentId})`);
+        setStatus({
+            accountId: ctx.accountId,
+            connected: true,
+            lastConnectedAt: Date.now(),
+        });
+    });
+}
+function logConnectionFailure(log, err) {
+    return Effect.sync(() => {
+        log?.error?.(`MoltZap: connection failed: ${err}`);
+    }).pipe(Effect.zipRight(Effect.fail(err)));
+}
+function stopGatewayAccount(ctx, activeClients) {
+    const service = activeClients.get(ctx.accountId);
+    if (service) {
+        ctx.log?.info?.("MoltZap: stopping");
+        service.close();
+        activeClients.delete(ctx.accountId);
+    }
+    return Promise.resolve();
+}
+function createOutboundSection(activeClients) {
+    return {
+        deliveryMode: "gateway",
+        resolveTarget(params) {
+            return resolveOutboundTarget(params.to);
+        },
+        sendText(ctx) {
+            return Effect.runPromise(sendTextEffect(activeClients, ctx));
         },
     };
 }
+function resolveOutboundTarget(toInput) {
+    const to = toInput?.trim();
+    if (!to) {
+        return new OpenClawTargetRejected({
+            error: new Error("MoltZap: target is required"),
+        });
+    }
+    if (to.includes(":") && !isMoltZapTarget(to)) {
+        return new OpenClawTargetRejected({
+            error: new Error(`MoltZap: unsupported target format "${to}" — use agent:<name> or conv:<id>`),
+        });
+    }
+    return new OpenClawTargetResolved({ to });
+}
+function sendTextEffect(activeClients, ctx) {
+    const effect = Effect.gen(function* () {
+        const accountId = ctx.accountId ?? DEFAULT_ACCOUNT_ID;
+        const service = activeClients.get(accountId);
+        if (!service) {
+            return yield* Effect.fail(new MoltZapClientNotConnectedError({ accountId }));
+        }
+        if (ctx.to.startsWith(TARGET_PREFIX_AGENT)) {
+            if (!service.sendToAgent) {
+                return yield* Effect.fail(new MoltZapAgentTargetUnsupportedError({ accountId }));
+            }
+            yield* service.sendToAgent(ctx.to.slice(TARGET_PREFIX_AGENT.length), ctx.text, {
+                replyTo: ctx.replyToId,
+            });
+        }
+        else {
+            yield* service.send(conversationTarget(ctx.to), ctx.text, {
+                replyTo: ctx.replyToId,
+            });
+        }
+        return new OpenClawSendTextSuccess();
+    }).pipe(Effect.withSpan("createMoltzapChannelPlugin.sendText"), Effect.match({
+        onSuccess: (ok) => ok,
+        onFailure: (err) => new OpenClawSendTextFailure({
+            error: err instanceof Error ? err : new Error(String(err)),
+        }),
+    }));
+    return effect;
+}
+function conversationTarget(to) {
+    return to.startsWith(TARGET_PREFIX_CONV)
+        ? to.slice(TARGET_PREFIX_CONV.length)
+        : to;
+}
+/**
+ * Factory: returns a fresh plugin object whose `activeClients` map lives in
+ * this closure. `register(api)` calls this so each registration gets its own
+ * per-plugin state, eliminating module-level mutable globals.
+ */
+export function createMoltzapChannelPlugin(deps = {}) {
+    const activeClients = new Map();
+    return {
+        id: CHANNEL_ID,
+        meta: createPluginMeta(),
+        capabilities: { chatTypes: ["dm", "group"] },
+        messaging: createMessagingSection(),
+        directory: createDirectorySection(activeClients),
+        config: createConfigSection(),
+        gateway: createGatewaySection(activeClients, deps),
+        outbound: createOutboundSection(activeClients),
+    };
+}
 /**
  * Shared singleton so a single registration reuses the same `activeClients`
  * closure across `startAccount` and `sendText`. Tests import this directly