@clawling/clawchat-plugin-openclaw 2026.5.12-28

package/src/outbound.ts

@@ -0,0 +1,803 @@
+import { MessageSendError, type Envelope, type Fragment, type MentionFragment, type MessageAckPayload, type MessageErrorPayload } from "./protocol-types.ts";
+import type { ClawlingChatClient } from "./ws-client.ts";
+import {
+  createAttachedChannelResultAdapter,
+  type ChannelOutboundAdapter,
+} from "openclaw/plugin-sdk/channel-send-result";
+import { chunkMarkdownText } from "openclaw/plugin-sdk/reply-runtime";
+import type { ChatType } from "./client.ts";
+import { createOpenclawClawlingApiClient } from "./api-client.ts";
+import { CHANNEL_ID, resolveOpenclawClawlingAccount, type ResolvedOpenclawClawlingAccount } from "./config.ts";
+import {
+  applyTextMentionLabels,
+  buildMentionMessageFragments,
+  normalizeMentionTargets,
+  textToFragments,
+  type MentionTarget,
+} from "./message-mapper.ts";
+import { uploadOutboundMedia, type ClawlingMediaFragment } from "./media-runtime.ts";
+import { isClawChatNoopResponseText } from "./profile-prompt.ts";
+import {
+  getOpenclawClawlingClient,
+  getOpenclawClawlingRuntime,
+  waitForOpenclawClawlingClient,
+} from "./runtime.ts";
+import {
+  clawChatDbPathForStateDir,
+  getClawChatStore,
+  type ClawChatStore,
+} from "./storage.ts";
+import { createAlignedWsQueue, type WsLogContext } from "./ws-alignment.ts";
+import { formatWsLog } from "./ws-log.ts";
+
+export interface OutboundTarget {
+  chatId: string;
+  chatType: ChatType;
+}
+
+export interface OutboundReplyCtx {
+  replyToMessageId: string;
+  replyPreviewChatId?: string;
+  replyPreviewSenderId?: string;
+  replyPreviewNickName?: string;
+  replyPreviewText?: string;
+}
+
+export interface LogSink {
+  info?: (m: string) => void;
+  error?: (m: string) => void;
+}
+
+export interface SendParams {
+  client: ClawlingChatClient;
+  account: ResolvedOpenclawClawlingAccount;
+  to: OutboundTarget;
+  text: string;
+  replyCtx?: OutboundReplyCtx;
+  richFragments?: Fragment[];
+  mediaFragments?: ClawlingMediaFragment[];
+  mentions?: MentionFragment[];
+  messageId?: string;
+  log?: LogSink;
+}
+
+export interface SendResult {
+  messageId: string;
+  acceptedAt: number;
+}
+
+export interface SendMentionMessageParams {
+  client: ClawlingChatClient;
+  account: ResolvedOpenclawClawlingAccount;
+  to: OutboundTarget;
+  text?: string;
+  mentions: MentionTarget[];
+  replyCtx?: OutboundReplyCtx;
+  messageId?: string;
+  log?: LogSink;
+}
+
+export interface SendMentionMessageResult extends SendResult {
+  mentions: string[];
+}
+
+const alignedOutboundQueues = new WeakMap<object, ReturnType<typeof createAlignedWsQueue>>();
+const alignedOutboundContexts = new WeakMap<object, () => WsLogContext>();
+const alignedOutboundMessageErrorTrackers = new WeakMap<object, {
+  pending: Set<string>;
+  listener: (env: Envelope) => void;
+}>();
+type AlignedOutboundClose = { code?: unknown; reason?: unknown } | undefined;
+type AlignedOutboundCloseHandler = (close?: AlignedOutboundClose) => void;
+type AlignedOutboundState = { to?: unknown } | undefined;
+type AlignedOutboundStateHandler = (state?: AlignedOutboundState) => void;
+const alignedOutboundCloseHandlers = new WeakMap<
+  object,
+  { handlers: Set<AlignedOutboundCloseHandler>; listener: AlignedOutboundCloseHandler }
+>();
+const alignedOutboundStateHandlers = new WeakMap<
+  object,
+  { handlers: Set<AlignedOutboundStateHandler>; listener: AlignedOutboundStateHandler }
+>();
+
+function addAlignedOutboundCloseHandler(
+  client: ClawlingChatClient,
+  handler: AlignedOutboundCloseHandler,
+): () => void {
+  const key = client as object;
+  let entry = alignedOutboundCloseHandlers.get(key);
+  if (!entry) {
+    const handlers = new Set<AlignedOutboundCloseHandler>();
+    const listener: AlignedOutboundCloseHandler = (close) => {
+      for (const current of [...handlers]) current(close);
+    };
+    entry = { handlers, listener };
+    alignedOutboundCloseHandlers.set(key, entry);
+    client.on("close", listener);
+  }
+  entry.handlers.add(handler);
+  return () => {
+    entry?.handlers.delete(handler);
+  };
+}
+
+function addAlignedOutboundStateHandler(
+  client: ClawlingChatClient,
+  handler: AlignedOutboundStateHandler,
+): () => void {
+  const key = client as object;
+  let entry = alignedOutboundStateHandlers.get(key);
+  if (!entry) {
+    const handlers = new Set<AlignedOutboundStateHandler>();
+    const listener: AlignedOutboundStateHandler = (state) => {
+      for (const current of [...handlers]) current(state);
+    };
+    entry = { handlers, listener };
+    alignedOutboundStateHandlers.set(key, entry);
+    client.on("state", listener);
+  }
+  entry.handlers.add(handler);
+  return () => {
+    entry?.handlers.delete(handler);
+  };
+}
+
+function getAlignedOutboundQueue(
+  client: ClawlingChatClient,
+  account: ResolvedOpenclawClawlingAccount,
+  log: LogSink | undefined,
+) {
+  const existing = alignedOutboundQueues.get(client as object);
+  if (existing) return existing;
+  const queue = createAlignedWsQueue({
+    accountId: account.accountId,
+    log: (msg) => log?.info?.(msg),
+    maxSize: 128,
+    context: () => alignedOutboundContexts.get(client as object)?.() ?? {
+      attempt: 1,
+      reconnectCount: 0,
+      state: "ready",
+    },
+  });
+  alignedOutboundQueues.set(client as object, queue);
+  return queue;
+}
+
+function getAlignedMessageErrorTracker(
+  client: ClawlingChatClient,
+  account: ResolvedOpenclawClawlingAccount,
+  log: LogSink | undefined,
+) {
+  const key = client as object;
+  const existing = alignedOutboundMessageErrorTrackers.get(key);
+  if (existing) return existing;
+  const pending = new Set<string>();
+  const listener = (env: Envelope) => {
+    if (env.event !== "message.error") return;
+    if (pending.has(env.trace_id)) {
+      (client as { markMessageErrorHandled?: (traceId: string) => void }).markMessageErrorHandled?.(env.trace_id);
+      return;
+    }
+    if ((client as { hasPendingAckTrace?: (traceId: string) => boolean }).hasPendingAckTrace?.(env.trace_id)) {
+      return;
+    }
+    const context = alignedOutboundContexts.get(key)?.() ?? {
+      attempt: 1,
+      reconnectCount: 0,
+      state: client.transportState === "open" ? "ready" : "reconnecting",
+    };
+    if (log?.info) {
+      log.info(
+        formatWsLog({
+          event: "ack_unmatched",
+          accountId: account.accountId,
+          attempt: context.attempt,
+          reconnectCount: context.reconnectCount,
+          state: context.state,
+          action: "ignore",
+          fields: [
+            ["trace_id", env.trace_id],
+            ["chat_id", env.chat_id],
+          ],
+        }),
+      );
+      (client as { markMessageErrorHandled?: (traceId: string) => void }).markMessageErrorHandled?.(env.trace_id);
+    }
+  };
+  client.on("raw", listener);
+  const tracker = { pending, listener };
+  alignedOutboundMessageErrorTrackers.set(key, tracker);
+  return tracker;
+}
+
+export function setAlignedOutboundLogContext(
+  client: ClawlingChatClient,
+  context: () => WsLogContext,
+): void {
+  alignedOutboundContexts.set(client as object, context);
+}
+
+export function flushAlignedOutboundQueue(client: ClawlingChatClient): void {
+  const queue = alignedOutboundQueues.get(client as object);
+  queue?.flush((wire) => client.sendWire(wire));
+}
+
+export function getAlignedOutboundQueueSize(client: ClawlingChatClient): number {
+  return alignedOutboundQueues.get(client as object)?.snapshot().length ?? 0;
+}
+
+async function sendAlignedAckableEnvelope(params: {
+  client: ClawlingChatClient;
+  account: ResolvedOpenclawClawlingAccount;
+  eventName: "message.send" | "message.reply";
+  chatId: string;
+  payload: object;
+  log?: LogSink;
+}): Promise<Envelope<MessageAckPayload>> {
+  const traceId = params.client.nextTraceId();
+  const env = {
+    version: "2" as const,
+    event: params.eventName,
+    trace_id: traceId,
+    emitted_at: Date.now(),
+    chat_id: params.chatId,
+    payload: params.payload,
+  };
+  const wire = JSON.stringify(env);
+  const queue = getAlignedOutboundQueue(params.client, params.account, params.log);
+  const messageErrorTracker = getAlignedMessageErrorTracker(params.client, params.account, params.log);
+  const isReady = () => {
+    const state = (params.client as { state?: string }).state;
+    return params.client.transportState === "open" && (!state || state === "connected");
+  };
+  const isDisconnected = () => (params.client as { state?: string }).state === "disconnected";
+
+  type AckableSendState = "queued" | "written_waiting_ack" | "acked" | "failed";
+
+  return await new Promise<Envelope<MessageAckPayload>>((resolve, reject) => {
+    let state: AckableSendState = "queued";
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    let rawListenerRegistered = false;
+    let removeCloseListener: (() => void) | undefined;
+    let removeStateListener: (() => void) | undefined;
+
+    const clearAckTimer = () => {
+      if (!timer) return;
+      clearTimeout(timer);
+      timer = undefined;
+    };
+
+    const removeRawListener = () => {
+      if (!rawListenerRegistered) return;
+      params.client.off("raw", onRaw);
+      rawListenerRegistered = false;
+    };
+
+    const cleanup = () => {
+      messageErrorTracker.pending.delete(traceId);
+      clearAckTimer();
+      removeRawListener();
+      removeCloseListener?.();
+      removeCloseListener = undefined;
+      removeStateListener?.();
+      removeStateListener = undefined;
+    };
+
+    const fail = (err: Error) => {
+      if (state === "acked" || state === "failed") return;
+      state = "failed";
+      cleanup();
+      reject(err);
+    };
+
+    const logAck = (
+      event: "ack_received" | "ack_timeout",
+      action: "resolve" | "reject_no_reconnect",
+      fields: Array<[string, string | number | boolean | null | undefined]>,
+    ) => {
+      params.log?.info?.(
+        formatWsLog({
+          event,
+          accountId: params.account.accountId,
+          ...(
+            alignedOutboundContexts.get(params.client as object)?.() ?? {
+              attempt: 1,
+              reconnectCount: 0,
+              state: isReady() ? "ready" : "reconnecting",
+            }
+          ),
+          action,
+          fields: [
+            ["event_name", params.eventName],
+            ["trace_id", traceId],
+            ["chat_id", params.chatId],
+            ...fields,
+          ],
+        }),
+      );
+    };
+
+    function onRaw(ack: Envelope) {
+      if (ack.trace_id !== traceId) return;
+      if (ack.event === "message.error") {
+        if (state === "acked" || state === "failed") return;
+        const payload = ack.payload as Partial<MessageErrorPayload>;
+        const code = typeof payload.code === "string" && payload.code ? payload.code : "unknown";
+        const message = typeof payload.message === "string" && payload.message ? payload.message : "message send failed";
+        fail(new MessageSendError(traceId, code, message, ack.chat_id));
+        return;
+      }
+      if (ack.event !== "message.ack") return;
+      if (state === "acked" || state === "failed") return;
+      state = "acked";
+      cleanup();
+      const payload = ack.payload as MessageAckPayload;
+      logAck("ack_received", "resolve", [["message_id", payload.message_id]]);
+      resolve(ack as Envelope<MessageAckPayload>);
+    }
+
+    const startAckTimer = () => {
+      if (state === "acked" || state === "failed") return;
+      state = "written_waiting_ack";
+      messageErrorTracker.pending.add(traceId);
+      clearAckTimer();
+      removeRawListener();
+      params.client.on("raw", onRaw);
+      rawListenerRegistered = true;
+      timer = setTimeout(() => {
+        logAck("ack_timeout", "reject_no_reconnect", [["timeout_ms", params.account.ack.timeout]]);
+        fail(new Error(`ack timeout after ${params.account.ack.timeout}ms for trace_id=${traceId}`));
+      }, params.account.ack.timeout);
+    };
+
+    const item = {
+      eventName: params.eventName,
+      traceId,
+      chatId: params.chatId,
+      wire,
+      onWrite: startAckTimer,
+      onDrop: () => {
+        fail(new Error(`send queue full; dropped ${params.eventName} before write for trace_id=${traceId}`));
+      },
+    };
+
+    function isTerminalClose(close: AlignedOutboundClose): boolean {
+      return close?.code === 1000 || close?.reason === "client close" || close?.reason === "auth failed";
+    }
+
+    function onClose(close?: AlignedOutboundClose) {
+      if (state === "acked" || state === "failed") return;
+      if (isTerminalClose(close)) {
+        const reason = typeof close?.reason === "string" && close.reason ? close.reason : "websocket closed";
+        queue.remove(item);
+        fail(new Error(`send cancelled because ${reason}`));
+        return;
+      }
+      if (state !== "written_waiting_ack") return;
+      clearAckTimer();
+      removeRawListener();
+      state = "queued";
+      queue.enqueue(item);
+    }
+
+    function onState(next?: AlignedOutboundState) {
+      if (state === "acked" || state === "failed" || next?.to !== "disconnected") return;
+      queue.remove(item);
+      fail(new Error("send cancelled because client disconnected"));
+    }
+
+    removeCloseListener = addAlignedOutboundCloseHandler(params.client, onClose);
+    removeStateListener = addAlignedOutboundStateHandler(params.client, onState);
+
+    if (!isReady()) {
+      if (isDisconnected()) {
+        fail(new Error("send cancelled because client disconnected"));
+        return;
+      }
+      queue.enqueue(item);
+      return;
+    }
+
+    try {
+      queue.enqueue(item);
+      queue.flush((queuedWire) => params.client.sendWire(queuedWire));
+    } catch {
+      // The queue keeps the failed frame at the head for reconnect retry, so
+      // keep this promise pending until the frame is written+acked, dropped, or timed out.
+    }
+  });
+}
+
+/**
+ * Parse an agent-initiated outbound recipient string into the new-protocol
+ * `chat_id` + `chat_type` pair.
+ *
+ * Accepted forms (case-insensitive prefix):
+ *   - `cc:{chat_id}`                  → direct
+ *   - `clawchat:{chat_id}`            → direct
+ *   - `clawchat-plugin-openclaw:{chat_id}`   → direct
+ *   - `cc:direct:{chat_id}`           → direct
+ *   - `cc:group:{chat_id}`            → group
+ *   - `clawchat:direct:{chat_id}`     → direct
+ *   - `clawchat:group:{chat_id}`      → group
+ *   - `clawchat-plugin-openclaw:direct:{chat_id}` → direct
+ *   - `clawchat-plugin-openclaw:group:{chat_id}`  → group
+ *   - `direct:{chat_id}`              → direct (host-normalized)
+ *   - `group:{chat_id}`               → group (host-normalized)
+ *   - bare `{chat_id}`                → direct (backward compat)
+ */
+export function parseOpenclawRecipient(to: string): { chatId: string; chatType: ChatType } {
+  const raw = (to ?? "").trim();
+  if (!raw) throw new Error("clawchat-plugin-openclaw: outbound `to` is empty");
+
+  const firstColon = raw.indexOf(":");
+  if (firstColon < 0) return { chatId: raw, chatType: "direct" };
+
+  const scheme = raw.slice(0, firstColon).toLowerCase();
+  const rest = raw.slice(firstColon + 1);
+  if (scheme === "direct" || scheme === "group") {
+    const chatId = rest.trim();
+    if (!chatId) throw new Error(`clawchat-plugin-openclaw: missing chat_id in "${to}"`);
+    return { chatId, chatType: scheme };
+  }
+  if (scheme !== "cc" && scheme !== "clawchat" && scheme !== CHANNEL_ID) {
+    return { chatId: raw, chatType: "direct" };
+  }
+
+  const secondColon = rest.indexOf(":");
+  if (secondColon >= 0) {
+    const typeToken = rest.slice(0, secondColon).toLowerCase();
+    const chatId = rest.slice(secondColon + 1).trim();
+    if ((typeToken === "direct" || typeToken === "group") && chatId) {
+      return { chatId, chatType: typeToken };
+    }
+  }
+  const chatId = rest.trim();
+  if (!chatId) throw new Error(`clawchat-plugin-openclaw: missing chat_id in "${to}"`);
+  return { chatId, chatType: "direct" };
+}
+
+export async function sendOpenclawClawlingText(params: SendParams): Promise<SendResult | null> {
+  const text = (params.text ?? "").trim();
+  const richFragments = params.richFragments ?? [];
+  const mediaFragments = params.mediaFragments ?? [];
+  if (
+    isClawChatNoopResponseText(text) &&
+    richFragments.length === 0 &&
+    mediaFragments.length === 0
+  ) {
+    params.log?.info?.(
+      `[${params.account.accountId}] clawchat-plugin-openclaw outbound suppressed: silent response`,
+    );
+    return null;
+  }
+  if (!text && richFragments.length === 0 && mediaFragments.length === 0) {
+    params.log?.info?.(
+      `[${params.account.accountId}] clawchat-plugin-openclaw outbound suppressed: empty text and no media`,
+    );
+    return null;
+  }
+
+  const mentions = params.mentions ?? [];
+  const textFragments = text ? textToFragments(text) : [];
+  // Each MediaItem object is structurally compatible
+  // with one of the local narrow Fragment members (ImageFragment / FileFragment /
+  // AudioFragment / VideoFragment) based on its runtime `kind`. The wide local
+  // shape lets us build a single uniform array without a per-kind switch.
+  const fragments = [...textFragments, ...richFragments, ...mediaFragments] as Fragment[];
+
+  const useReply = Boolean(
+    params.replyCtx?.replyPreviewSenderId
+      && params.replyCtx.replyPreviewNickName
+      && params.replyCtx.replyPreviewText,
+  );
+  const messageId = params.messageId;
+
+  let ack: Envelope<MessageAckPayload>;
+  let mode: "send" | "reply";
+  if (useReply && params.replyCtx) {
+    mode = "reply";
+    const payload = {
+      ...(messageId ? { message_id: messageId } : {}),
+      message_mode: "normal",
+      message: {
+        body: { fragments },
+        context: {
+          mentions,
+          reply: {
+            reply_to_msg_id: params.replyCtx.replyToMessageId,
+            reply_preview: {
+              id: params.replyCtx.replyPreviewSenderId,
+              nick_name: params.replyCtx.replyPreviewNickName,
+              fragments: [{ kind: "text", text: params.replyCtx.replyPreviewText }],
+            },
+          },
+        },
+      },
+    };
+    ack = await sendAlignedAckableEnvelope({
+      client: params.client,
+      account: params.account,
+      eventName: "message.reply",
+      chatId: params.to.chatId,
+      payload,
+      ...(params.log ? { log: params.log } : {}),
+    });
+  } else {
+    mode = "send";
+    const reply = params.replyCtx
+      ? {
+          reply_to_msg_id: params.replyCtx.replyToMessageId,
+          reply_preview: null,
+        }
+      : null;
+    const payload = {
+      ...(messageId ? { message_id: messageId } : {}),
+      message_mode: "normal",
+      message: {
+        body: { fragments },
+        context: { mentions, reply },
+      },
+    };
+    ack = await sendAlignedAckableEnvelope({
+      client: params.client,
+      account: params.account,
+      eventName: "message.send",
+      chatId: params.to.chatId,
+      payload,
+      ...(params.log ? { log: params.log } : {}),
+    });
+  }
+  if (messageId && ack.payload.message_id !== messageId) {
+    throw new Error(
+      `ack message_id mismatch: expected ${messageId} got ${ack.payload.message_id}`,
+    );
+  }
+  params.log?.info?.(
+    `[${params.account.accountId}] clawchat-plugin-openclaw outbound mode=${mode} msg=${ack.payload.message_id} text_len=${text.length} media=${mediaFragments.length} trace=${ack.trace_id}`,
+  );
+  return {
+    messageId: ack.payload.message_id,
+    acceptedAt: ack.payload.accepted_at,
+  };
+}
+
+export async function sendOpenclawClawlingMentionMessage(
+  params: SendMentionMessageParams,
+): Promise<SendMentionMessageResult | null> {
+  const normalized = normalizeMentionTargets(params.mentions);
+  const prepared = applyTextMentionLabels(normalized, params.text);
+  const fragments = buildMentionMessageFragments({
+    mentions: prepared.mentions,
+    ...(prepared.text ? { text: prepared.text } : {}),
+  });
+  const contextMentions: MentionFragment[] = prepared.mentions.map((mention) => ({
+    kind: "mention",
+    user_id: mention.userId,
+    ...(mention.display ? { display: mention.display } : {}),
+  }));
+  const mentionIds = prepared.mentions.map((mention) => mention.userId);
+  const result = await sendOpenclawClawlingText({
+    client: params.client,
+    account: params.account,
+    to: params.to,
+    text: "",
+    richFragments: fragments,
+    mentions: contextMentions,
+    ...(params.messageId ? { messageId: params.messageId } : {}),
+    ...(params.replyCtx ? { replyCtx: params.replyCtx } : {}),
+    ...(params.log ? { log: params.log } : {}),
+  });
+  if (!result) return null;
+  return { ...result, mentions: mentionIds };
+}
+
+export interface SendMediaParams {
+  client: ClawlingChatClient;
+  account: ResolvedOpenclawClawlingAccount;
+  to: OutboundTarget;
+  mediaFragments: ClawlingMediaFragment[];
+  /** Optional caption alongside the media. */
+  text?: string;
+  replyCtx?: OutboundReplyCtx;
+  mentions?: MentionFragment[];
+  messageId?: string;
+  log?: LogSink;
+}
+
+/**
+ * Send one or more media fragments (image / file / audio / video) to the
+ * given target, with an optional text caption.
+ *
+ * Validates that mediaFragments is non-empty (returns null + info log
+ * otherwise) and delegates to {@link sendOpenclawClawlingText} for the
+ * actual envelope construction. Reuses the existing replyCtx-downgrade,
+ * ack backfill, and log shape.
+ */
+export async function sendOpenclawClawlingMedia(
+  params: SendMediaParams,
+): Promise<SendResult | null> {
+  if (params.mediaFragments.length === 0) {
+    params.log?.info?.(
+      `[${params.account.accountId}] clawchat-plugin-openclaw sendMedia called with empty mediaFragments; suppressed`,
+    );
+    return null;
+  }
+  return await sendOpenclawClawlingText({
+    client: params.client,
+    account: params.account,
+    to: params.to,
+    text: params.text ?? "",
+    mediaFragments: params.mediaFragments,
+    ...(params.messageId ? { messageId: params.messageId } : {}),
+    ...(params.replyCtx ? { replyCtx: params.replyCtx } : {}),
+    ...(params.mentions ? { mentions: params.mentions } : {}),
+    ...(params.log ? { log: params.log } : {}),
+  });
+}
+
+type OutboundClaimStore = Pick<ClawChatStore, "claimMessageOnce" | "markMessageAcknowledged">;
+
+function mintOutboundMessageId(account: ResolvedOpenclawClawlingAccount): string {
+  return `${account.userId}-msg-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+}
+
+function resolveChannelOutboundStore(): OutboundClaimStore | null {
+  try {
+    const runtime = getOpenclawClawlingRuntime();
+    const stateDir = runtime.state?.resolveStateDir?.();
+    return getClawChatStore({
+      ...(stateDir ? { dbPath: clawChatDbPathForStateDir(stateDir) } : {}),
+    });
+  } catch {
+    return null;
+  }
+}
+
+function claimChannelOutbound(params: {
+  account: ResolvedOpenclawClawlingAccount;
+  target: OutboundTarget;
+  messageId: string;
+  text: string;
+  raw: unknown;
+}): true | false | null {
+  const store = resolveChannelOutboundStore();
+  if (!store) return null;
+  try {
+    return store.claimMessageOnce({
+      platform: "openclaw",
+      accountId: params.account.accountId,
+      kind: "message",
+      direction: "outbound",
+      eventType: "message.send",
+      chatId: params.target.chatId,
+      messageId: params.messageId,
+      text: params.text,
+      raw: params.raw,
+    });
+  } catch {
+    return null;
+  }
+}
+
+function markChannelOutboundAcknowledged(params: {
+  account: ResolvedOpenclawClawlingAccount;
+  messageId: string;
+  result: SendResult | null;
+}): void {
+  const store = resolveChannelOutboundStore();
+  if (!store || !params.result?.messageId) return;
+  try {
+    store.markMessageAcknowledged?.({
+      accountId: params.account.accountId,
+      kind: "message",
+      direction: "outbound",
+      messageId: params.messageId,
+      protocolMessageId: params.result.messageId,
+      ackedAt: params.result.acceptedAt ?? Date.now(),
+    });
+  } catch {
+    // Best-effort diagnostics only; ack has already succeeded.
+  }
+}
+
+export const openclawClawlingOutbound: ChannelOutboundAdapter = {
+  deliveryMode: "direct",
+  chunker: (text, limit) => chunkMarkdownText(text, limit),
+  chunkerMode: "markdown",
+  textChunkLimit: 4000,
+  ...createAttachedChannelResultAdapter({
+    channel: CHANNEL_ID,
+    sendText: async ({ cfg, to, text }) => {
+      const account = resolveOpenclawClawlingAccount(cfg);
+      const client =
+        getOpenclawClawlingClient(account.accountId) ??
+        (await waitForOpenclawClawlingClient(account.accountId));
+      const target = parseOpenclawRecipient(to);
+      const messageId = mintOutboundMessageId(account);
+      const trimmedText = text.trim();
+      if (!trimmedText) {
+        throw new Error("clawchat-plugin-openclaw sendText requires non-empty text");
+      }
+      const claimed = claimChannelOutbound({
+        account,
+        target,
+        messageId,
+        text: trimmedText,
+        raw: { target, mode: "channel-sendText" },
+      });
+      if (claimed === false) {
+        throw new Error("clawchat-plugin-openclaw outbound duplicate claim; message not sent");
+      }
+      if (claimed === null) {
+        throw new Error("clawchat-plugin-openclaw outbound message claim failed");
+      }
+      const result = await sendOpenclawClawlingText({
+        client,
+        account,
+        to: target,
+        text,
+        messageId,
+      });
+      markChannelOutboundAcknowledged({ account, messageId, result });
+      return {
+        to,
+        messageId: result?.messageId ?? messageId,
+      };
+    },
+    sendMedia: async ({ cfg, to, text, mediaUrl, mediaAccess, mediaLocalRoots, mediaReadFile }) => {
+      const account = resolveOpenclawClawlingAccount(cfg);
+      const client =
+        getOpenclawClawlingClient(account.accountId) ??
+        (await waitForOpenclawClawlingClient(account.accountId));
+      if (!mediaUrl?.trim()) {
+        throw new Error("clawchat-plugin-openclaw sendMedia requires mediaUrl");
+      }
+      const runtime = getOpenclawClawlingRuntime();
+      const apiClient = createOpenclawClawlingApiClient({
+        baseUrl: account.baseUrl,
+        token: account.token,
+        userId: account.userId,
+      });
+      const mediaFragments = await uploadOutboundMedia([mediaUrl.trim()], {
+        apiClient,
+        runtime,
+        ...(mediaAccess ? { mediaAccess } : {}),
+        ...(mediaLocalRoots ? { mediaLocalRoots } : {}),
+        ...(mediaReadFile ? { mediaReadFile } : {}),
+      });
+      if (mediaFragments.length === 0) {
+        throw new Error(`clawchat-plugin-openclaw failed to upload media: ${mediaUrl}`);
+      }
+      const target = parseOpenclawRecipient(to);
+      const messageId = mintOutboundMessageId(account);
+      const claimText = (text ?? "").trim();
+      const claimed = claimChannelOutbound({
+        account,
+        target,
+        messageId,
+        text: claimText,
+        raw: { target, mode: "channel-sendMedia", mediaCount: mediaFragments.length },
+      });
+      if (claimed === false) {
+        throw new Error("clawchat-plugin-openclaw outbound duplicate claim; message not sent");
+      }
+      if (claimed === null) {
+        throw new Error("clawchat-plugin-openclaw outbound message claim failed");
+      }
+      const result = await sendOpenclawClawlingMedia({
+        client,
+        account,
+        to: target,
+        text,
+        mediaFragments,
+        messageId,
+      });
+      markChannelOutboundAcknowledged({ account, messageId, result });
+      return {
+        to,
+        messageId: result?.messageId ?? messageId,
+      };
+    },
+  }),
+};