@rowger_go/chatu 0.1.3

package/dist/index.js

@@ -0,0 +1,1381 @@
+"use strict";
+/**
+ * OpenClaw Chatu Channel Plugin
+ *
+ * This plugin enables OpenClaw to communicate with Chatu/WebHub services
+ * via HTTP polling (inbound) and HTTP POST (outbound).
+ *
+ * Architecture:
+ *   User (browser) → WebHub service (POST /api/webhub/channels/:id/messages)
+ *   Plugin polls    → GET /api/channel/messages/pending
+ *   Plugin dispatches → OpenClaw AI
+ *   AI responds     → plugin outbound.sendText → POST /api/channel/messages
+ *   WebHub service  → WebSocket push → browser
+ *
+ * @see https://docs.openclaw.ai/channels/chatu
+ * @see https://github.com/chatu-ai/openclaw-web-hub-channel
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = default_1;
+exports.computeBackoffMs = computeBackoffMs;
+exports.relayCrossChannelMessage = relayCrossChannelMessage;
+exports.relayStreamChunk = relayStreamChunk;
+exports.relayStreamDone = relayStreamDone;
+const promises_1 = __importDefault(require("fs/promises"));
+const path_1 = __importDefault(require("path"));
+const os_1 = __importDefault(require("os"));
+const package_json_1 = __importDefault(require("../package.json"));
+const websocket_1 = require("./sdk/adapters/websocket");
+const cache_1 = require("./sdk/adapters/cache");
+const CHANNEL_ID = 'chatu';
+const POLL_INTERVAL_MS = 2000;
+const MAX_BACKOFF_MS = 30000;
+const DEFAULT_TIMEOUT_MS = 30000;
+const DEFAULT_CHUNK_LIMIT = 4000;
+// ─────────────────────────────────────────────────────────────────────────────
+// Plugin Entry Point
+// ─────────────────────────────────────────────────────────────────────────────
+function default_1(api) {
+    // ── Config helpers ──────────────────────────────────────────────────────────
+    api.logger.info('[chatu] Initializing channel plugin');
+    // ── T015 Plugin-Channel Realtime: per-account outbound message caches ───────
+    /** Stores failed AI replies for retry on reconnect. One per account. */
+    const accountCaches = new Map();
+    /**
+     * Bridges before_message_write → deliver callback so both relay and direct
+     * delivery paths carry the same dedupId (the OpenClaw internal message ID).
+     * Key: sessionKey, Value: OpenClaw msg.id
+     */
+    const pendingRelayIds = new Map();
+    function getAccountCache(accountId) {
+        if (!accountCaches.has(accountId)) {
+            accountCaches.set(accountId, new cache_1.MessageCache({
+                logger: api.logger,
+                maxCapacity: process.env.CHATU_CACHE_MAX ? parseInt(process.env.CHATU_CACHE_MAX, 10) : 1000,
+                filePath: process.env.CHATU_CACHE_FILE
+                    ? `${process.env.CHATU_CACHE_FILE}.${accountId}.json`
+                    : undefined,
+            }));
+        }
+        return accountCaches.get(accountId);
+    }
+    // ── Config helpers ──────────────────────────────────────────────────────────
+    /** Resolve per-account config, falling back to channel-level then plugin-level. */
+    function getAccountConfig(accountId) {
+        const pluginCfg = api.config?.plugins?.entries?.chatu?.config ?? {};
+        const channelCfg = api.config?.channels?.chatu ?? {};
+        const accounts = channelCfg.accounts ?? {};
+        const acctCfg = accountId && accounts[accountId] ? accounts[accountId] : {};
+        return {
+            apiUrl: acctCfg.apiUrl ?? channelCfg.apiUrl ?? pluginCfg.apiUrl ?? '',
+            channelId: acctCfg.channelId ?? channelCfg.channelId ?? pluginCfg.channelId ?? '',
+            secret: acctCfg.secret ?? channelCfg.secret ?? pluginCfg.secret ?? '',
+            accessToken: acctCfg.accessToken ?? channelCfg.accessToken ?? pluginCfg.accessToken ?? '',
+            timeout: acctCfg.timeout ?? channelCfg.timeout ?? pluginCfg.timeout ?? DEFAULT_TIMEOUT_MS,
+        };
+    }
+    // ── HTTP helpers ─────────────────────────────────────────────────────────────
+    async function timedFetch(url, init, timeoutMs) {
+        const ctrl = new AbortController();
+        const id = setTimeout(() => ctrl.abort(), timeoutMs);
+        try {
+            return await fetch(url, { ...init, signal: ctrl.signal });
+        }
+        finally {
+            clearTimeout(id);
+        }
+    }
+    // ── Lifecycle: register + connect ─────────────────────────────────────────────
+    /**
+     * T023 Plugin-Channel Realtime: If CHATU_KEY and CHATU_URL env vars are set,
+     * call POST /api/channel/quick-register to obtain credentials automatically.
+     * This runs BEFORE registerAndConnect so WS setup (T012) can use the credentials.
+     * Skipped if channelId + accessToken are already configured.
+     */
+    async function quickRegisterIfNeeded(accountId) {
+        const key = process.env.CHATU_KEY;
+        const apiUrl = process.env.CHATU_URL ?? process.env.CHATU_API_URL;
+        if (!key || !apiUrl)
+            return;
+        // If already have credentials, skip
+        const cfg = getAccountConfig(accountId);
+        if (cfg.channelId && cfg.accessToken)
+            return;
+        try {
+            const resp = await timedFetch(`${apiUrl}/api/channel/quick-register`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ key, url: apiUrl }),
+            }, DEFAULT_TIMEOUT_MS);
+            if (resp.ok) {
+                const data = await resp.json();
+                const channelId = data?.data?.channelId;
+                const accessToken = data?.data?.accessToken;
+                if (channelId && accessToken) {
+                    const base = accountId
+                        ? `channels.chatu.accounts.${accountId}`
+                        : 'channels.chatu';
+                    try {
+                        await api.config?.set?.(`${base}.channelId`, channelId);
+                        await api.config?.set?.(`${base}.accessToken`, accessToken);
+                        await api.config?.set?.(`${base}.apiUrl`, apiUrl);
+                    }
+                    catch (_) { /* config persistence optional */ }
+                    api.logger.info(`[chatu] Quick-registered via CHATU_KEY (channelId=${channelId}, account=${accountId ?? 'default'})`);
+                }
+            }
+            else {
+                api.logger.warn(`[chatu] Quick-register returned HTTP ${resp.status} — check CHATU_KEY/CHATU_URL`);
+            }
+        }
+        catch (err) {
+            api.logger.warn(`[chatu] Quick-register failed: ${String(err)}`);
+        }
+    }
+    async function registerAndConnect(accountId) {
+        const cfg = getAccountConfig(accountId);
+        if (!cfg.apiUrl)
+            return;
+        // Connect directly using accessToken (secret-based registration removed;
+        // credentials are obtained via quick-register or manual config).
+        const refreshed = getAccountConfig(accountId);
+        if (refreshed.accessToken && refreshed.channelId) {
+            try {
+                const resp = await timedFetch(`${refreshed.apiUrl}/api/channel/connect`, {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                        'x-access-token': refreshed.accessToken,
+                    },
+                    body: JSON.stringify({
+                        channelId: refreshed.channelId,
+                        pluginVersion: package_json_1.default.version,
+                        workingDir: os_1.default.homedir(),
+                    }),
+                }, refreshed.timeout);
+                if (resp.ok) {
+                    api.logger.info(`[chatu] Channel connected (channelId=${refreshed.channelId}, v${package_json_1.default.version}, workingDir=${os_1.default.homedir()})`);
+                }
+            }
+            catch (err) {
+                api.logger.warn(`[chatu] Connect request failed: ${String(err)}`);
+            }
+        }
+    }
+    async function disconnectAccount(accountId) {
+        const cfg = getAccountConfig(accountId);
+        if (!cfg.apiUrl || !cfg.accessToken || !cfg.channelId)
+            return;
+        try {
+            await timedFetch(`${cfg.apiUrl}/api/channel/disconnect`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'x-access-token': cfg.accessToken,
+                },
+                body: JSON.stringify({ channelId: cfg.channelId }),
+            }, cfg.timeout);
+        }
+        catch (_) { /* best-effort */ }
+    }
+    // ── Inbound: deliver AI reply back to service ────────────────────────────────
+    async function deliverOutbound(params) {
+        const cfg = getAccountConfig(params.accountId);
+        if (!cfg.apiUrl || !cfg.accessToken) {
+            return { ok: false, error: 'Missing apiUrl or accessToken' };
+        }
+        const messageId = `msg_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+        const payload = {
+            messageId,
+            target: { type: 'user', id: params.target },
+            content: { text: params.text, format: 'plain' },
+            timestamp: Date.now(),
+        };
+        if (params.replyTo)
+            payload.replyTo = { id: params.replyTo };
+        if (params.mediaUrl) {
+            payload.media = [{ type: params.mediaType ?? 'file', url: params.mediaUrl }];
+        }
+        if (params.messageType)
+            payload.messageType = params.messageType;
+        if (params.metadata)
+            payload.metadata = params.metadata;
+        // Phase 11 T049: always stamp role:'ai' so the service can persist the correct author role
+        payload.role = 'ai';
+        if (params.raw !== undefined)
+            payload.raw = params.raw;
+        try {
+            const resp = await timedFetch(`${cfg.apiUrl}/api/channel/messages`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'X-Channel-Token': cfg.accessToken,
+                    'X-Channel-ID': cfg.channelId,
+                },
+                body: JSON.stringify(payload),
+            }, cfg.timeout);
+            if (!resp.ok) {
+                const errorText = await resp.text();
+                return { ok: false, error: `HTTP ${resp.status}: ${errorText}` };
+            }
+            const result = await resp.json();
+            return { ok: true, messageId: result.messageId ?? messageId };
+        }
+        catch (err) {
+            return { ok: false, error: String(err?.message ?? err) };
+        }
+    }
+    // ── Streaming relay helpers (T042) ────────────────────────────────────────
+    /**
+     * Relay a single streaming chunk to the WebHub API.
+     * Called by the outbound.sendStreamChunk handler when OpenClaw AI streams.
+     */
+    async function deliverStreamChunk(params) {
+        const cfg = getAccountConfig(params.accountId);
+        if (!cfg.apiUrl || !cfg.accessToken) {
+            return { ok: false, error: 'Missing apiUrl or accessToken' };
+        }
+        try {
+            const resp = await timedFetch(`${cfg.apiUrl}/api/channel/stream/chunk`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: `Bearer ${cfg.accessToken}`,
+                },
+                body: JSON.stringify({ messageId: params.messageId, seq: params.seq, delta: params.delta }),
+            }, cfg.timeout);
+            if (!resp.ok) {
+                const errorText = await resp.text();
+                return { ok: false, error: `HTTP ${resp.status}: ${errorText}` };
+            }
+            return { ok: true };
+        }
+        catch (err) {
+            return { ok: false, error: String(err?.message ?? err) };
+        }
+    }
+    /**
+     * Signal streaming completion to the WebHub API.
+     * Called by the outbound.sendStreamDone handler when OpenClaw AI finishes.
+     */
+    async function deliverStreamDone(params) {
+        const cfg = getAccountConfig(params.accountId);
+        if (!cfg.apiUrl || !cfg.accessToken) {
+            return { ok: false, error: 'Missing apiUrl or accessToken' };
+        }
+        try {
+            const resp = await timedFetch(`${cfg.apiUrl}/api/channel/stream/done`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: `Bearer ${cfg.accessToken}`,
+                },
+                body: JSON.stringify({ messageId: params.messageId, totalSeq: params.totalSeq }),
+            }, cfg.timeout);
+            if (!resp.ok) {
+                const errorText = await resp.text();
+                return { ok: false, error: `HTTP ${resp.status}: ${errorText}` };
+            }
+            return { ok: true };
+        }
+        catch (err) {
+            return { ok: false, error: String(err?.message ?? err) };
+        }
+    }
+    // ── T011 US3: Cross-channel relay helpers ────────────────────────────────────
+    /**
+     * Forward a message that arrived on another OpenClaw channel (e.g. TUI,
+     * WhatsApp, Telegram) to this ChatU WebHub channel so the conversation
+     * appears in the frontend with a cross-channel badge.
+     *
+     * Call this from any OpenClaw integration point that has access to the
+     * per-channel message — for example from an OpenClaw `before_message_write`
+     * hook (when it becomes available in the SDK), or from a custom relay script.
+     *
+     * @param params.sourceChannel  Originating channel id (e.g. 'tui', 'whatsapp')
+     * @param params.direction      'inbound' (AI reply) or 'outbound' (user message)
+     * @param params.senderName     Display name of the sender
+     * @param params.content        Text content of the message
+     * @param params.sessionKey     Session key in the originating channel
+     * @param params.accountId      ChatU account id (defaults to 'default')
+     */
+    async function relayCrossChannelMessage(params) {
+        const cfg = getAccountConfig(params.accountId);
+        if (!cfg.apiUrl || !cfg.accessToken) {
+            return { ok: false, error: 'Missing apiUrl or accessToken for cross-channel relay' };
+        }
+        try {
+            const resp = await timedFetch(`${cfg.apiUrl}/api/channel/cross-channel-messages`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'X-Access-Token': cfg.accessToken,
+                },
+                body: JSON.stringify({
+                    sourceChannel: params.sourceChannel,
+                    direction: params.direction,
+                    sender: params.sender,
+                    content: params.content,
+                    sessionKey: params.sessionKey,
+                    ...(params.dedupId ? { dedupId: params.dedupId } : {}),
+                    ...(params.raw !== undefined ? { raw: params.raw } : {}),
+                }),
+            }, cfg.timeout);
+            if (!resp.ok) {
+                const errorText = await resp.text();
+                api.logger.warn(`[chatu] cross-channel relay failed (source=${params.sourceChannel}): HTTP ${resp.status} ${errorText}`);
+                return { ok: false, error: `HTTP ${resp.status}: ${errorText}` };
+            }
+            const result = await resp.json();
+            api.logger.info(`[chatu] cross_channel_relay_ok (source=${params.sourceChannel}, id=${result.id}, direction=${params.direction})`);
+            return { ok: true, id: result.id };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            api.logger.error(`[chatu] cross-channel relay error: ${message}`);
+            return { ok: false, error: message };
+        }
+    }
+    // ── Gateway: poll + dispatch inbound user messages ───────────────────────────
+    /**
+     * Dispatch a single user message from the web client to the OpenClaw AI
+     * pipeline using the PluginRuntime API.
+     */
+    async function dispatchUserMessage(params) {
+        const { id, content, sender, timestamp, accountId, cfg } = params;
+        const senderId = sender.id ?? 'user';
+        const senderName = sender.name;
+        if (!content?.trim())
+            return;
+        const runtime = api.runtime;
+        if (!runtime?.channel?.reply?.dispatchReplyWithBufferedBlockDispatcher) {
+            api.logger.warn(`[chatu] api.runtime not available; cannot dispatch inbound message (id=${id})`);
+            return;
+        }
+        const to = `chatu:${senderId}`;
+        const fromLabel = senderName ? `${senderName} (${senderId})` : senderId;
+        try {
+            const route = runtime.channel.routing.resolveAgentRoute({
+                cfg,
+                channel: CHANNEL_ID,
+                accountId,
+                peer: { kind: 'direct', id: senderId },
+            });
+            const ctxPayload = runtime.channel.reply.finalizeInboundContext({
+                Body: content,
+                BodyForAgent: content,
+                RawBody: content,
+                CommandBody: content,
+                From: `chatu:${senderId}`,
+                To: to,
+                SessionKey: route.sessionKey,
+                AccountId: route.accountId,
+                ChatType: 'direct',
+                ConversationLabel: fromLabel,
+                SenderName: senderName ?? senderId,
+                SenderId: senderId,
+                Provider: CHANNEL_ID,
+                Surface: CHANNEL_ID,
+                MessageSid: id,
+                Timestamp: timestamp ?? Date.now(),
+                OriginatingChannel: CHANNEL_ID,
+                OriginatingTo: to,
+                WasMentioned: true,
+                // Authorize slash-commands (messages starting with '/'); regular messages remain unauthorized.
+                CommandAuthorized: content.trim().startsWith('/'),
+            });
+            api.logger.info(`[chatu] Dispatching user message to AI (id=${id}, sender=${senderId})`);
+            await runtime.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
+                ctx: ctxPayload,
+                cfg,
+                dispatcherOptions: {
+                    deliver: async (payload) => {
+                        const text = payload.text ?? '';
+                        if (!text)
+                            return;
+                        // Retrieve the dedupId stored by before_message_write for this session.
+                        const dedupId = pendingRelayIds.get(route.sessionKey);
+                        if (dedupId)
+                            pendingRelayIds.delete(route.sessionKey);
+                        const result = await deliverOutbound({
+                            text,
+                            target: senderId,
+                            accountId,
+                            replyTo: payload.replyToId ?? id,
+                            metadata: dedupId ? { dedupId } : undefined,
+                            raw: payload,
+                        });
+                        if (!result.ok) {
+                            api.logger.error(`[chatu] Failed to deliver AI reply (target=${senderId}): ${result.error}`);
+                            // T015 Plugin-Channel Realtime: cache failed delivery for retry on reconnect
+                            const cfg2 = getAccountConfig(accountId);
+                            const cache = getAccountCache(accountId);
+                            const cacheId = result.messageId ?? `retry_${Date.now()}_${Math.random().toString(36).slice(2, 7)}`;
+                            cache.enqueue({
+                                id: cacheId,
+                                channelId: cfg2.channelId,
+                                content: { text, target: senderId, replyTo: payload.replyToId ?? id },
+                                enqueuedAt: Date.now(),
+                                status: 'pending',
+                            });
+                        }
+                    },
+                    onError: (err, info) => {
+                        api.logger.error(`[chatu] ${info.kind} reply failed: ${String(err)}`);
+                    },
+                },
+                replyOptions: {},
+            });
+        }
+        catch (err) {
+            api.logger.error(`[chatu] Exception dispatching user message (id=${id}): ${String(err)}`);
+        }
+    }
+    /**
+     * Acknowledge that a message has been processed by the plugin.
+     */
+    async function ackMessage(apiUrl, accessToken, messageId, timeout) {
+        try {
+            await timedFetch(`${apiUrl}/api/channel/messages/${messageId}/ack`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'X-Channel-Token': accessToken,
+                },
+            }, timeout);
+        }
+        catch (_) { /* best-effort */ }
+    }
+    // ── T012 display-sender-session: resolveSessionKey helper ──────────────────
+    /**
+     * Derive the OpenClaw sessionKey for a senderId using the same routing logic
+     * as dispatchUserMessage. This is deterministic and requires no lookup table.
+     */
+    function resolveSessionKey(senderId, accountId, cfg) {
+        const runtime = api.runtime;
+        const route = runtime.channel.routing.resolveAgentRoute({
+            cfg,
+            channel: CHANNEL_ID,
+            accountId,
+            peer: { kind: 'direct', id: senderId },
+        });
+        return route.sessionKey;
+    }
+    // ── T011 display-sender-session: session command processor ─────────────────
+    /**
+     * Fetch and execute pending session commands for this channel.
+     * Called at the end of each poll loop iteration.
+     * Each command is acked (success or failure) before moving to the next.
+     */
+    async function processCommands(cfg, accountId) {
+        if (!cfg.accessToken)
+            return;
+        const resp = await timedFetch(`${cfg.apiUrl}/api/channel/commands?channelId=${encodeURIComponent(cfg.channelId)}`, {
+            method: 'GET',
+            headers: {
+                'X-Channel-Token': cfg.accessToken,
+                'X-Channel-ID': cfg.channelId,
+            },
+        }, cfg.timeout);
+        if (!resp.ok)
+            return;
+        const data = await resp.json();
+        const commands = data?.data?.commands ?? [];
+        for (const cmd of commands) {
+            let ackSuccess = false;
+            let ackError;
+            try {
+                const freshCfg = api.config ?? {};
+                const sessionKey = resolveSessionKey(cmd.senderId, accountId, freshCfg);
+                if (cmd.commandType === 'reset') {
+                    // Resolve the sessions store directory and derive the transcript path
+                    const storePath = api.runtime.channel.session.resolveStorePath(freshCfg?.session?.store);
+                    const transcriptPath = path_1.default.join(storePath, `${sessionKey}.jsonl`);
+                    try {
+                        await promises_1.default.unlink(transcriptPath);
+                        api.logger.info(`[chatu] Session reset: deleted transcript (key=${sessionKey})`);
+                    }
+                    catch (e) {
+                        if (e.code !== 'ENOENT')
+                            throw e;
+                        // ENOENT = already empty/non-existent, treat as success
+                    }
+                    ackSuccess = true;
+                }
+                else if (cmd.commandType === 'switch') {
+                    const targetSessionKey = cmd.payload?.targetSessionKey;
+                    if (!targetSessionKey)
+                        throw new Error('Missing targetSessionKey');
+                    const storePath = api.runtime.channel.session.resolveStorePath(freshCfg?.session?.store);
+                    const currentPath = path_1.default.join(storePath, `${sessionKey}.jsonl`);
+                    const targetPath = path_1.default.join(storePath, `${targetSessionKey}.jsonl`);
+                    // Restore target session as the current session
+                    await promises_1.default.copyFile(targetPath, currentPath);
+                    api.logger.info(`[chatu] Session switched to ${targetSessionKey} (sender=${cmd.senderId})`);
+                    ackSuccess = true;
+                }
+            }
+            catch (e) {
+                ackError = String(e);
+                api.logger.error(`[chatu] Command ${cmd.id} (${cmd.commandType}) failed: ${ackError}`);
+            }
+            // Ack regardless of outcome
+            try {
+                await timedFetch(`${cfg.apiUrl}/api/channel/commands/${cmd.id}/ack`, {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                        'X-Channel-Token': cfg.accessToken,
+                    },
+                    body: JSON.stringify({
+                        success: ackSuccess,
+                        error: ackError,
+                        channelId: cfg.channelId,
+                    }),
+                }, cfg.timeout);
+            }
+            catch (_) { /* best-effort */ }
+        }
+    }
+    /**
+     * Plugin-Channel Realtime (T012): WebSocket-based gateway loop.
+     * Replaces HTTP polling. Connects to /api/channel/ws via WebSocketAdapter
+     * and dispatches inbound messages to the OpenClaw AI pipeline.
+     * Reconnects automatically with infinite exponential back-off (T009).
+     *
+     * Runs until `abortSignal` fires.
+     */
+    async function wsConnectionLoop(ctx) {
+        const cfg = getAccountConfig(ctx.accountId);
+        if (!cfg.apiUrl) {
+            ctx.log?.error?.(`[${ctx.accountId}] chatu: missing apiUrl for WS connection`);
+            return;
+        }
+        if (!cfg.accessToken || !cfg.channelId) {
+            ctx.log?.error?.(`[${ctx.accountId}] chatu: missing accessToken/channelId for WS connection`);
+            return;
+        }
+        // Convert HTTP URL to WebSocket URL scheme
+        const wsBase = cfg.apiUrl
+            .replace(/^https:\/\//, 'wss://')
+            .replace(/^http:\/\//, 'ws://');
+        const adapter = new websocket_1.WebSocketAdapter({
+            channelId: cfg.channelId,
+            accessToken: cfg.accessToken,
+            webhubUrl: `${wsBase}/api/channel/ws`,
+        });
+        // Register inbound message handler — dispatches user messages to AI
+        adapter.onMessage(async (msg) => {
+            const text = msg.content?.text?.trim() ?? '';
+            if (!text)
+                return;
+            const freshCfg = api.config ?? {};
+            // Phase 11 T048 (fixed): role:agent frames come from the human operator via the
+            // webhub frontend.  api.dispatch() does not exist in the OpenClaw plugin SDK;
+            // instead we re-use dispatchUserMessage so the agent message appears in OpenClaw's
+            // conversation context (sender = 'webhub-agent').  OpenClaw AI may reply; if it does,
+            // the reply is delivered via deliverOutbound → /api/channel/messages → frontend.
+            const senderId = msg.role === 'agent'
+                ? (msg.sender?.id ?? 'webhub-agent')
+                : msg.sender.id;
+            const senderName = msg.role === 'agent'
+                ? (msg.sender?.displayName ?? 'Agent')
+                : msg.sender.displayName;
+            await dispatchUserMessage({
+                id: msg.id,
+                content: text,
+                sender: { id: senderId, name: senderName ?? undefined },
+                timestamp: msg.timestamp,
+                accountId: ctx.accountId,
+                cfg: freshCfg,
+            });
+        });
+        // Track connection status → surface to OpenClaw gateway
+        adapter.onStatusChange((status, err) => {
+            if (status === 'connected') {
+                ctx.setStatus({ accountId: ctx.accountId, connected: true });
+                ctx.log?.info?.(`[${ctx.accountId}] chatu: WebSocket connected`);
+            }
+            else if (status === 'disconnected') {
+                ctx.setStatus({ accountId: ctx.accountId, connected: false });
+            }
+            else if (status === 'error') {
+                ctx.setStatus({
+                    accountId: ctx.accountId,
+                    connected: false,
+                    lastError: err?.message ?? 'WS error',
+                });
+            }
+        });
+        // T015 Plugin-Channel Realtime: flush cached failed deliveries on reconnect
+        adapter.onReconnected(async () => {
+            const cache = getAccountCache(ctx.accountId);
+            if (cache.pendingCount === 0)
+                return;
+            api.logger.info(`[chatu] Reconnected — flushing ${cache.pendingCount} cached messages (account=${ctx.accountId})`);
+            await cache.flush(async (cachedMsg) => {
+                const payload = cachedMsg.content;
+                const result = await deliverOutbound({
+                    text: payload.text ?? '',
+                    target: payload.target ?? '',
+                    accountId: ctx.accountId,
+                    replyTo: payload.replyTo,
+                });
+                if (!result.ok) {
+                    throw new Error(result.error ?? 'Cached delivery failed');
+                }
+                cache.ack(cachedMsg.id);
+            });
+        });
+        ctx.setStatus({ accountId: ctx.accountId, connected: false });
+        ctx.log?.info?.(`[${ctx.accountId}] chatu: starting WebSocket connection to ${wsBase}/api/channel/ws`);
+        // Attempt initial connect (adapter auto-reconnects indefinitely on failure)
+        try {
+            await adapter.connect();
+        }
+        catch (err) {
+            api.logger.warn(`[chatu] Initial WS connect failed (account=${ctx.accountId}): ${String(err)}`);
+            // Adapter will keep retrying — proceed to wait for abort
+        }
+        // Hold until the gateway signals shutdown
+        await new Promise((resolve) => {
+            if (ctx.abortSignal.aborted) {
+                resolve();
+                return;
+            }
+            ctx.abortSignal.addEventListener('abort', () => resolve(), { once: true });
+        });
+        ctx.log?.info?.(`[${ctx.accountId}] chatu: WebSocket connection stopping`);
+        await adapter.disconnect();
+        ctx.setStatus({ accountId: ctx.accountId, connected: false });
+    }
+    /**
+     * @deprecated Use wsConnectionLoop instead (Plugin-Channel Realtime T012).
+     * Long-running poll loop for the gateway.
+     * Polls the WebHub service for new user messages and dispatches them to OpenClaw AI.
+     * Runs until `abortSignal` fires.
+     */
+    async function pollLoop(ctx) {
+        const { accountId, abortSignal } = ctx;
+        // Pre-flight check
+        const initCfg = getAccountConfig(accountId);
+        if (!initCfg.apiUrl) {
+            ctx.log?.error?.(`[${accountId}] chatu: missing apiUrl for polling`);
+            return;
+        }
+        let lastCursor = '';
+        let consecutiveErrors = 0;
+        const MAX_ERRORS = 10;
+        // Track processed message IDs to handle same-millisecond createdAt duplicates
+        const processedIds = new Set();
+        const MAX_PROCESSED_IDS = 500;
+        ctx.setStatus({ accountId: ctx.accountId, connected: true });
+        ctx.log?.info?.(`[${accountId}] chatu: polling started`);
+        while (!abortSignal.aborted) {
+            // Exponential back-off: 2s → 4s → 8s → … capped at 30s on consecutive errors
+            const backoffMs = Math.min(POLL_INTERVAL_MS * Math.pow(2, consecutiveErrors), MAX_BACKOFF_MS);
+            await new Promise((resolve) => {
+                const timer = setTimeout(resolve, backoffMs);
+                abortSignal.addEventListener('abort', () => { clearTimeout(timer); resolve(); }, { once: true });
+            });
+            if (abortSignal.aborted)
+                break;
+            try {
+                // Re-read config each iteration so a refreshed accessToken is picked up
+                const cfg = getAccountConfig(accountId);
+                if (!cfg.accessToken) {
+                    consecutiveErrors++;
+                    api.logger.warn(`[chatu] No accessToken yet (account=${accountId}), retrying...`);
+                    continue;
+                }
+                const url = `${cfg.apiUrl}/api/channel/messages/pending` +
+                    `?channelId=${encodeURIComponent(cfg.channelId)}` +
+                    `&after=${encodeURIComponent(lastCursor)}`;
+                const resp = await timedFetch(url, {
+                    method: 'GET',
+                    headers: {
+                        'X-Channel-Token': cfg.accessToken,
+                        'X-Channel-ID': accountId,
+                    },
+                }, cfg.timeout);
+                if (!resp.ok) {
+                    consecutiveErrors++;
+                    if (consecutiveErrors >= MAX_ERRORS) {
+                        ctx.setStatus({ accountId: ctx.accountId, connected: false, lastError: `HTTP ${resp.status}` });
+                    }
+                    continue;
+                }
+                consecutiveErrors = 0;
+                ctx.setStatus({ accountId: ctx.accountId, connected: true });
+                const data = await resp.json();
+                const messages = data?.data ?? [];
+                for (const msg of messages) {
+                    // Advance ISO timestamp cursor so next poll fetches only newer messages
+                    if (msg.createdAt)
+                        lastCursor = msg.createdAt;
+                    // Skip messages already processed in-memory (handles same-ms duplicates)
+                    if (processedIds.has(msg.id))
+                        continue;
+                    processedIds.add(msg.id);
+                    // Bound set growth
+                    if (processedIds.size > MAX_PROCESSED_IDS) {
+                        const first = processedIds.values().next().value;
+                        if (first !== undefined)
+                            processedIds.delete(first);
+                    }
+                    // Ack first (idempotency)
+                    await ackMessage(cfg.apiUrl, cfg.accessToken, msg.id, cfg.timeout);
+                    // T099: send typing indicator before dispatching to AI
+                    const typingChannelId = msg.channelId ?? cfg.channelId;
+                    if (typingChannelId) {
+                        timedFetch(`${cfg.apiUrl}/api/channel/typing`, {
+                            method: 'POST',
+                            headers: { 'Content-Type': 'application/json', 'X-Channel-Token': cfg.accessToken },
+                            body: JSON.stringify({ channelId: typingChannelId }),
+                        }, 3000).catch(() => { });
+                    }
+                    const freshCfg = api.config ?? {};
+                    await dispatchUserMessage({
+                        id: msg.id,
+                        content: msg.content ?? msg.text ?? '',
+                        sender: {
+                            id: msg.sender?.id ?? 'user',
+                            name: msg.sender?.name,
+                        },
+                        timestamp: msg.createdAt
+                            ? new Date(msg.createdAt).getTime()
+                            : Date.now(),
+                        accountId,
+                        cfg: freshCfg,
+                    });
+                }
+                // T011 display-sender-session: process pending session commands
+                await processCommands(cfg, accountId).catch((e) => {
+                    api.logger.warn(`[chatu] processCommands error (account=${accountId}): ${String(e)}`);
+                });
+            }
+            catch (err) {
+                consecutiveErrors++;
+                api.logger.warn(`[chatu] Poll failed (account=${accountId}, errors=${consecutiveErrors}): ${String(err)}`);
+                if (consecutiveErrors >= MAX_ERRORS) {
+                    ctx.setStatus({ accountId: ctx.accountId, connected: false, lastError: String(err) });
+                }
+            }
+        }
+        ctx.setStatus({ accountId: ctx.accountId, connected: false });
+        ctx.log?.info?.(`[${accountId}] chatu: polling stopped`);
+    }
+    // ── Channel Plugin Definition ────────────────────────────────────────────────
+    const chatuChannel = {
+        id: CHANNEL_ID,
+        // ── Metadata ──────────────────────────────────────────────────────────────
+        meta: {
+            id: CHANNEL_ID,
+            label: 'Chatu',
+            selectionLabel: 'Chatu (HTTP/WebSocket)',
+            docsPath: '/channels/chatu',
+            blurb: 'Connect to any website via HTTP/WebSocket (WebHub service)',
+            aliases: ['chatu', 'http-channel', 'webhub'],
+        },
+        // ── Capabilities ──────────────────────────────────────────────────────────
+        capabilities: {
+            chatTypes: ['direct', 'group'],
+            reply: true,
+            edit: true,
+            unsend: true,
+            reactions: true,
+            polls: false,
+            media: true,
+            threads: true,
+            blockStreaming: false,
+        },
+        defaults: { queue: { debounceMs: 0 } },
+        // ── Config Schema (UI hints) ───────────────────────────────────────────────
+        configSchema: {
+            schema: {
+                type: 'object',
+                properties: {
+                    apiUrl: { type: 'string', description: 'WebHub service base URL' },
+                    channelId: { type: 'string', description: 'Channel ID from WebHub' },
+                    secret: { type: 'string', description: 'Channel secret (wh_secret_...)' },
+                    accessToken: { type: 'string', description: 'Access token' },
+                    timeout: { type: 'number', description: 'Request timeout in ms' },
+                },
+            },
+            uiHints: {
+                apiUrl: {
+                    label: 'API URL',
+                    placeholder: 'https://your-webhub-service.example.com',
+                    help: 'Base URL of the Chatu WebHub service',
+                },
+                channelId: {
+                    label: 'Channel ID',
+                    placeholder: 'wh_ch_xxxxxx',
+                    help: 'Channel ID from the WebHub service',
+                },
+                secret: {
+                    label: 'Channel Secret',
+                    sensitive: true,
+                    placeholder: 'wh_secret_xxxxxxxxxx',
+                },
+                accessToken: {
+                    label: 'Access Token',
+                    sensitive: true,
+                    placeholder: 'wh_xxxxxxxxxxxxxxxx',
+                    advanced: true,
+                },
+                timeout: { label: 'Timeout (ms)', placeholder: '30000', advanced: true },
+            },
+        },
+        // ── Setup (CLI) ───────────────────────────────────────────────────────────
+        setup: {
+            applyAccountConfig: ({ cfg, accountId, input }) => {
+                const chatInput = input;
+                const next = { ...cfg };
+                if (!next['channels'])
+                    next['channels'] = {};
+                if (!next['channels'].chatu)
+                    next['channels'].chatu = {};
+                if (!next['channels'].chatu.accounts)
+                    next['channels'].chatu.accounts = {};
+                if (!next['channels'].chatu.accounts[accountId]) {
+                    next['channels'].chatu.accounts[accountId] = {};
+                }
+                const acct = next['channels'].chatu.accounts[accountId];
+                if (chatInput.apiUrl)
+                    acct.apiUrl = chatInput.apiUrl;
+                if (chatInput.channelId)
+                    acct.channelId = chatInput.channelId;
+                if (chatInput.secret)
+                    acct.secret = chatInput.secret;
+                if (input.accessToken)
+                    acct.accessToken = input.accessToken;
+                return next;
+            },
+            validateInput: ({ input }) => {
+                const chatInput = input;
+                if (!chatInput.apiUrl)
+                    return 'apiUrl is required';
+                if (!chatInput.channelId)
+                    return 'channelId is required';
+                if (!chatInput.secret && !input.accessToken)
+                    return 'Either secret or accessToken is required';
+                return null;
+            },
+        },
+        // ── Config ────────────────────────────────────────────────────────────────
+        config: {
+            listAccountIds: (cfg) => {
+                const accounts = cfg?.channels?.chatu?.accounts ?? {};
+                const ids = Object.keys(accounts);
+                if (ids.length === 0 &&
+                    (cfg?.channels?.chatu?.apiUrl || cfg?.channels?.chatu?.channelId)) {
+                    return ['default'];
+                }
+                return ids;
+            },
+            resolveAccount: (cfg, accountId) => {
+                const accounts = cfg?.channels?.chatu?.accounts ?? {};
+                const channelCfg = cfg?.channels?.chatu ?? {};
+                const id = accountId ?? 'default';
+                const acct = accounts[id] ?? {};
+                return {
+                    accountId: id,
+                    apiUrl: acct.apiUrl ?? channelCfg.apiUrl ?? '',
+                    channelId: acct.channelId ?? channelCfg.channelId ?? '',
+                    secret: acct.secret ?? channelCfg.secret,
+                    accessToken: acct.accessToken ?? channelCfg.accessToken,
+                    timeout: acct.timeout ?? channelCfg.timeout ?? DEFAULT_TIMEOUT_MS,
+                };
+            },
+            isConfigured: (account, _cfg) => Boolean(account?.apiUrl &&
+                account?.channelId &&
+                (account?.accessToken || account?.secret)),
+            unconfiguredReason: (account, _cfg) => {
+                if (!account?.apiUrl)
+                    return 'apiUrl not configured';
+                if (!account?.channelId)
+                    return 'channelId not configured';
+                if (!account?.accessToken && !account?.secret)
+                    return 'accessToken or secret not configured';
+                return 'Not configured';
+            },
+            isEnabled: (account, cfg) => {
+                if (cfg?.channels?.chatu?.enabled === false)
+                    return false;
+                return Boolean(account?.apiUrl);
+            },
+            disabledReason: (_account, cfg) => {
+                if (cfg?.channels?.chatu?.enabled === false)
+                    return 'Channel disabled in config';
+                return 'Not enabled';
+            },
+            describeAccount: (account, _cfg) => ({
+                accountId: account.accountId,
+                name: `Chatu (${account.channelId || account.accountId || 'unknown'})`,
+                connected: Boolean(account.accessToken),
+                baseUrl: account.apiUrl || undefined,
+            }),
+        },
+        // ── Pairing ───────────────────────────────────────────────────────────────
+        pairing: {
+            idLabel: 'Channel ID',
+            normalizeAllowEntry: (entry) => entry.trim().toLowerCase(),
+        },
+        // ── Security ──────────────────────────────────────────────────────────────
+        security: {
+            resolveDmPolicy: () => null, // WebHub controls access
+        },
+        // ── Groups ────────────────────────────────────────────────────────────────
+        groups: {
+            resolveRequireMention: () => false,
+        },
+        // ── Streaming ─────────────────────────────────────────────────────────────
+        streaming: {
+            blockStreamingCoalesceDefaults: { minChars: 40, idleMs: 300 },
+        },
+        // ── Threading ─────────────────────────────────────────────────────────────
+        threading: {
+            resolveReplyToMode: () => 'first',
+            allowExplicitReplyTagsWhenOff: true,
+        },
+        // ── Messaging ─────────────────────────────────────────────────────────────
+        messaging: {
+            normalizeTarget: (raw) => raw?.trim().replace(/^chatu:/i, '').toLowerCase() || undefined,
+            targetResolver: {
+                looksLikeId: (raw) => Boolean(raw?.trim()),
+                hint: 'User ID or channel ID from the WebHub service',
+            },
+        },
+        // ── Status ────────────────────────────────────────────────────────────────
+        status: {
+            probeAccount: async ({ account, timeoutMs }) => {
+                const cfg = getAccountConfig(account?.accountId);
+                if (!cfg.apiUrl || !cfg.accessToken) {
+                    return { ok: false, error: 'Not configured' };
+                }
+                try {
+                    const resp = await timedFetch(`${cfg.apiUrl}/api/channel/status`, {
+                        headers: {
+                            'x-access-token': cfg.accessToken,
+                            'X-Channel-ID': account?.accountId ?? cfg.channelId,
+                        },
+                    }, Math.min(timeoutMs, 5000));
+                    if (resp.ok) {
+                        const data = await resp.json();
+                        return { ok: true, status: data?.data?.status ?? 'unknown' };
+                    }
+                    return { ok: false, error: `HTTP ${resp.status}` };
+                }
+                catch (err) {
+                    return { ok: false, error: String(err?.message ?? err) };
+                }
+            },
+            buildAccountSnapshot: ({ account, probe }) => {
+                const p = probe;
+                return {
+                    accountId: account.accountId,
+                    connected: p?.ok === true,
+                    lastError: p?.ok ? null : (p?.error ?? null),
+                    baseUrl: account.apiUrl || undefined,
+                    name: `Chatu (${account.channelId || account.accountId})`,
+                };
+            },
+        },
+        // ── Heartbeat ─────────────────────────────────────────────────────────────
+        heartbeat: {
+            checkReady: async ({ accountId }) => {
+                const aid = accountId ?? 'default';
+                const cfg = getAccountConfig(aid);
+                if (!cfg.apiUrl)
+                    return { ok: false, reason: 'apiUrl not configured' };
+                if (!cfg.accessToken)
+                    return { ok: false, reason: 'accessToken not configured' };
+                try {
+                    const resp = await timedFetch(`${cfg.apiUrl}/health`, {}, 5000);
+                    if (resp.ok)
+                        return { ok: true, reason: 'Service reachable' };
+                    return { ok: false, reason: `Service returned HTTP ${resp.status}` };
+                }
+                catch (err) {
+                    return {
+                        ok: false,
+                        reason: `Cannot reach service: ${String(err?.message ?? err)}`,
+                    };
+                }
+            },
+        },
+        // ── Gateway (long-running per-account connection) ─────────────────────────
+        gateway: {
+            startAccount: async (ctx) => {
+                api.logger.info(`[chatu] WebHub channel plugin v${package_json_1.default.version} starting`);
+                // T023: quick-register via env vars if no credentials configured
+                await quickRegisterIfNeeded(ctx.accountId);
+                await registerAndConnect(ctx.accountId);
+                // Plugin-Channel Realtime (T012): use WebSocket instead of HTTP polling
+                await wsConnectionLoop({
+                    accountId: ctx.accountId,
+                    abortSignal: ctx.abortSignal,
+                    setStatus: ctx.setStatus,
+                    log: ctx.log,
+                });
+            },
+            stopAccount: async (ctx) => {
+                await disconnectAccount(ctx.accountId);
+            },
+            logoutAccount: async (ctx) => {
+                const { accountId } = ctx;
+                const cfgKey = accountId === 'default'
+                    ? 'channels.chatu.accessToken'
+                    : `channels.chatu.accounts.${accountId}.accessToken`;
+                try {
+                    await api.config?.set?.(cfgKey, '');
+                }
+                catch (_) { /* ok */ }
+                await disconnectAccount(accountId);
+                return { cleared: true, loggedOut: true };
+            },
+        },
+        // ── Outbound ──────────────────────────────────────────────────────────────
+        outbound: {
+            deliveryMode: 'direct',
+            textChunkLimit: DEFAULT_CHUNK_LIMIT,
+            resolveTarget: (params) => {
+                const raw = params?.to ?? params?.accountId ?? 'default';
+                const normalized = String(raw).trim().replace(/^chatu:/i, '');
+                if (!normalized) {
+                    return { ok: false, error: new Error('Empty target') };
+                }
+                return { ok: true, to: normalized };
+            },
+            sendText: async (ctx) => {
+                const { to, text, accountId, replyToId, silent } = ctx;
+                if (silent)
+                    return { channel: CHANNEL_ID, messageId: 'silent' };
+                const result = await deliverOutbound({ text, target: to, accountId, replyTo: replyToId, raw: ctx });
+                if (!result.ok) {
+                    api.logger.error(`[chatu] Failed to send text (to=${to}): ${result.error}`);
+                    throw new Error(result.error ?? 'sendText failed');
+                }
+                api.logger.info(`[chatu] Text sent (to=${to}, messageId=${result.messageId})`);
+                return { channel: CHANNEL_ID, messageId: result.messageId ?? '' };
+            },
+            sendMedia: async (ctx) => {
+                const { to, mediaUrl, text, accountId, replyToId } = ctx;
+                // Infer mediaType from URL extension since ChannelOutboundContext has no mediaType field
+                const inferMediaType = (url) => {
+                    if (!url)
+                        return 'file';
+                    const ext = url.split('?')[0].split('.').pop()?.toLowerCase() ?? '';
+                    if (['jpg', 'jpeg', 'png', 'gif', 'webp', 'bmp', 'svg', 'ico'].includes(ext))
+                        return 'image';
+                    if (['mp4', 'webm', 'mov', 'avi', 'mkv'].includes(ext))
+                        return 'video';
+                    if (['mp3', 'wav', 'aac', 'flac', 'm4a'].includes(ext))
+                        return 'audio';
+                    return 'file';
+                };
+                const result = await deliverOutbound({
+                    text: text ?? '',
+                    target: to,
+                    accountId,
+                    replyTo: replyToId,
+                    mediaUrl,
+                    mediaType: inferMediaType(mediaUrl),
+                    raw: ctx,
+                });
+                if (!result.ok) {
+                    api.logger.error(`[chatu] Failed to send media (to=${to}): ${result.error}`);
+                    throw new Error(result.error ?? 'sendMedia failed');
+                }
+                return { channel: CHANNEL_ID, messageId: result.messageId ?? '' };
+            },
+            // T098: send a rich payload (richCard, structured content)
+            sendPayload: async (ctx) => {
+                const { to, accountId, replyToId, messageType, metadata, text } = ctx;
+                const result = await deliverOutbound({
+                    text: text ?? '',
+                    target: to,
+                    accountId,
+                    replyTo: replyToId,
+                    messageType,
+                    metadata,
+                    raw: ctx,
+                });
+                if (!result.ok) {
+                    api.logger.error(`[chatu] Failed to send payload (to=${to}): ${result.error}`);
+                    throw new Error(result.error ?? 'sendPayload failed');
+                }
+                return { channel: CHANNEL_ID, messageId: result.messageId ?? '' };
+            },
+            // T098: send a poll message
+            sendPoll: async (ctx) => {
+                const { to, accountId, replyToId, question, options, multiple } = ctx;
+                const result = await deliverOutbound({
+                    text: question ?? 'Poll',
+                    target: to,
+                    accountId,
+                    replyTo: replyToId,
+                    messageType: 'poll',
+                    metadata: { poll: { question, options, multiple: multiple ?? false } },
+                    raw: ctx,
+                });
+                if (!result.ok) {
+                    api.logger.error(`[chatu] Failed to send poll (to=${to}): ${result.error}`);
+                    throw new Error(result.error ?? 'sendPoll failed');
+                }
+                return { channel: CHANNEL_ID, messageId: result.messageId ?? '' };
+            },
+            // T042: streaming relay — forward AI stream chunks/done to WebHub API
+            // Cast to any: sendStreamChunk/sendStreamDone are chatu-specific extensions
+            // not yet in the openclaw plugin-sdk ChannelOutboundAdapter type.
+            ...({
+                sendStreamChunk: async (ctx) => {
+                    const { messageId, seq, delta, accountId } = ctx;
+                    const result = await deliverStreamChunk({ messageId, seq, delta, accountId });
+                    if (!result.ok) {
+                        api.logger.warn(`[chatu] stream chunk relay failed (messageId=${messageId}): ${result.error}`);
+                    }
+                    return result;
+                },
+                sendStreamDone: async (ctx) => {
+                    const { messageId, totalSeq, accountId } = ctx;
+                    const result = await deliverStreamDone({ messageId, totalSeq, accountId });
+                    if (!result.ok) {
+                        api.logger.warn(`[chatu] stream done relay failed (messageId=${messageId}): ${result.error}`);
+                    }
+                    return result;
+                },
+            }),
+        },
+    };
+    // ── Register channel with OpenClaw ─────────────────────────────────────────
+    api.registerChannel({ plugin: chatuChannel });
+    // ── T011 US3: Cross-channel relay via before_message_write hook ─────────────
+    //
+    // Every time OpenClaw writes a message to any session transcript, this hook
+    // fires synchronously. We relay messages from channels OTHER than ChatU so
+    // they show up in the ChatU frontend with a cross-channel badge.
+    //
+    // The hook MUST be synchronous. Async relay is fired-and-forgotten (.catch).
+    api.on('before_message_write', (event, ctx) => {
+        const sessionKey = ctx.sessionKey ?? '';
+        // Skip ChatU's own channel sessions to prevent relay loops.
+        // ChatU session keys always contain the CHANNEL_ID token 'chatu'.
+        if (!sessionKey || sessionKey.includes('chatu'))
+            return;
+        const msg = event.message;
+        const role = msg?.role ?? '';
+        // Only relay user (outbound) and assistant (inbound) messages; skip tool/system.
+        if (role !== 'user' && role !== 'assistant')
+            return;
+        const direction = role === 'assistant' ? 'inbound' : 'outbound';
+        // Extract plain-text content from the AgentMessage (string or content-block array).
+        let content = '';
+        if (typeof msg.content === 'string') {
+            content = msg.content;
+        }
+        else if (Array.isArray(msg.content)) {
+            content = msg.content
+                .filter((b) => b?.type === 'text')
+                .map((b) => b.text ?? '')
+                .join('\n');
+        }
+        // Strip OpenClaw system metadata prefix and extract embedded metadata.
+        // Pattern: "Conversation info (untrusted metadata): ```json\n{...}\n``` [date] actual_message"
+        const metaPrefixMatch = content.match(/^Conversation info \(untrusted metadata\):\s*```(?:json)?\s*([\s\S]*?)```\s*(?:\[[^\]]*\])?\s*/);
+        if (metaPrefixMatch) {
+            // Parse the embedded metadata to detect the sender channel.
+            try {
+                const embeddedMeta = JSON.parse(metaPrefixMatch[1].trim());
+                // If the message originated from our own webhub frontend, skip relay to avoid duplicates.
+                // OpenClaw injects sender_id="webhub" for messages forwarded from the chatu channel plugin.
+                const embeddedSender = embeddedMeta?.sender_id ?? embeddedMeta?.sender ?? '';
+                if (embeddedSender === 'webhub' || embeddedSender.startsWith('chatu'))
+                    return;
+            }
+            catch { /* ignore parse errors */ }
+            // Strip the whole prefix regardless of parse success.
+            content = content.replace(/^Conversation info \(untrusted metadata\):[\s\S]*?```[\s\S]*?```\s*(?:\[[^\]]*\])?\s*/, '').trim();
+        }
+        if (!content.trim())
+            return; // skip empty or tool-only messages
+        // Derive source channel from session key.
+        // Session key format: "{agentId}:{channel}:{peerId}" (approx.)
+        // 'main' channel = TUI / CLI direct mode → label as 'tui'.
+        const parts = sessionKey.split(':');
+        const channelPart = parts[1] || parts[0] || 'tui';
+        const rawSource = channelPart === 'main' ? 'tui' : channelPart;
+        // Sanitize to match backend /^[a-z0-9_-]{1,64}$/ validation.
+        const sourceChannel = rawSource
+            .replace(/[^a-z0-9_-]/g, '-')
+            .replace(/^-+|-+$/g, '')
+            .slice(0, 64) || 'tui';
+        const senderName = direction === 'inbound' ? 'OpenClaw' : sourceChannel;
+        // Store the OpenClaw message ID so the deliver callback (deliverOutbound path)
+        // can retrieve and attach it as dedupId, making both write paths carry the
+        // same identifier for reliable ID-based dedup on the backend.
+        const ocMsgId = msg.id ?? '';
+        if (ocMsgId)
+            pendingRelayIds.set(sessionKey, ocMsgId);
+        // Fire-and-forget with a short delay so that the direct deliverOutbound path
+        // (which calls POST /api/channel/messages) has time to complete first.
+        const RELAY_DEDUP_DELAY_MS = 500;
+        setTimeout(() => {
+            relayCrossChannelMessage({
+                sourceChannel,
+                direction,
+                sender: { name: senderName },
+                content: content.trim(),
+                sessionKey,
+                accountId: null,
+                dedupId: ocMsgId || undefined,
+                raw: msg,
+            }).catch((err) => {
+                api.logger.warn(`[chatu] before_message_write relay failed (source=${sourceChannel}, dir=${direction}): ${String(err)}`);
+            });
+        }, RELAY_DEDUP_DELAY_MS);
+        // Return undefined → don't block the message write.
+    });
+    api.logger.info('[chatu] Channel plugin loaded');
+    // Return plugin lifecycle
+    return {
+        name: 'chatu-channel',
+        async dispose() {
+            api.logger.info('[chatu] Disposing channel plugin');
+            await disconnectAccount();
+        },
+    };
+}
+// ── Testable utility exports ────────────────────────────────────────────────
+/**
+ * Computes the exponential back-off wait time in milliseconds.
+ * On each consecutive error the wait doubles starting from baseMs, capped at maxMs.
+ *
+ * consecutiveErrors=0 → baseMs (normal interval, no back-off)
+ * consecutiveErrors=1 → baseMs * 2
+ * consecutiveErrors=2 → baseMs * 4
+ * ...
+ *
+ * @param consecutiveErrors - Number of consecutive failures so far
+ * @param baseMs            - Base interval in milliseconds (default 2000)
+ * @param maxMs             - Maximum allowed wait in milliseconds (default 30000)
+ */
+function computeBackoffMs(consecutiveErrors, baseMs = POLL_INTERVAL_MS, maxMs = MAX_BACKOFF_MS) {
+    return Math.min(baseMs * Math.pow(2, consecutiveErrors), maxMs);
+}
+/**
+ * T011 US3 testable export: forward a cross-channel message to the ChatU WebHub
+ * service so it appears in the frontend with a source-channel badge.
+ *
+ * Can be called from OpenClaw pipeline hooks (e.g. `before_message_write`) or
+ * from standalone relay scripts that have access to the channel credentials.
+ *
+ * @param apiUrl         - WebHub service base URL
+ * @param accessToken    - Channel access token (`X-Access-Token`)
+ * @param sourceChannel  - Originating channel id  (e.g. 'tui', 'whatsapp')
+ * @param direction      - 'inbound' (AI reply) or 'outbound' (user message)
+ * @param sender         - Sender object: name required, id optional (cross-channel may lack user ID)
+ * @param content        - Text content of the message
+ * @param sessionKey     - Session key in the originating channel
+ * @param timeoutMs      - Fetch timeout in milliseconds (default 30 s)
+ */
+async function relayCrossChannelMessage(apiUrl, accessToken, sourceChannel, direction, sender, content, sessionKey, timeoutMs = 30000) {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+    try {
+        const resp = await fetch(`${apiUrl}/api/channel/cross-channel-messages`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'X-Access-Token': accessToken,
+            },
+            body: JSON.stringify({ sourceChannel, direction, sender, content, sessionKey }),
+            signal: ctrl.signal,
+        });
+        clearTimeout(timer);
+        if (!resp.ok) {
+            const errorText = await resp.text();
+            return { ok: false, error: `HTTP ${resp.status}: ${errorText}` };
+        }
+        const result = await resp.json();
+        return { ok: true, id: result.id };
+    }
+    catch (err) {
+        clearTimeout(timer);
+        return { ok: false, error: err instanceof Error ? err.message : String(err) };
+    }
+}
+/**
+ * T042 testable export: relay a streaming AI chunk to the WebHub API.
+ *
+ * @param apiUrl      - WebHub service base URL
+ * @param accessToken - Channel access token (Bearer)
+ * @param messageId   - Unique ID for the streaming message
+ * @param seq         - 0-based sequential chunk index
+ * @param delta       - Text delta for this chunk
+ * @param timeoutMs   - Fetch timeout in milliseconds
+ */
+async function relayStreamChunk(apiUrl, accessToken, messageId, seq, delta, timeoutMs = 30000) {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+    try {
+        const resp = await fetch(`${apiUrl}/api/channel/stream/chunk`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${accessToken}`,
+            },
+            body: JSON.stringify({ messageId, seq, delta }),
+            signal: ctrl.signal,
+        });
+        clearTimeout(timer);
+        if (!resp.ok) {
+            const errorText = await resp.text();
+            return { ok: false, error: `HTTP ${resp.status}: ${errorText}` };
+        }
+        return { ok: true };
+    }
+    catch (err) {
+        clearTimeout(timer);
+        return { ok: false, error: String(err?.message ?? err) };
+    }
+}
+/**
+ * T042 testable export: signal streaming completion to the WebHub API.
+ *
+ * @param apiUrl      - WebHub service base URL
+ * @param accessToken - Channel access token (Bearer)
+ * @param messageId   - Unique ID for the streaming message
+ * @param totalSeq    - Total number of chunks sent
+ * @param timeoutMs   - Fetch timeout in milliseconds
+ */
+async function relayStreamDone(apiUrl, accessToken, messageId, totalSeq, timeoutMs = 30000) {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+    try {
+        const resp = await fetch(`${apiUrl}/api/channel/stream/done`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${accessToken}`,
+            },
+            body: JSON.stringify({ messageId, totalSeq }),
+            signal: ctrl.signal,
+        });
+        clearTimeout(timer);
+        if (!resp.ok) {
+            const errorText = await resp.text();
+            return { ok: false, error: `HTTP ${resp.status}: ${errorText}` };
+        }
+        return { ok: true };
+    }
+    catch (err) {
+        clearTimeout(timer);
+        return { ok: false, error: String(err?.message ?? err) };
+    }
+}
+//# sourceMappingURL=index.js.map