@clawling/clawchat-plugin-openclaw 2026.8.14-2 → 2026.8.22-1

package/dist/src/media-runtime.js

@@ -1,4 +1,5 @@
 import { buildOutboundMediaLoadOptions, } from "openclaw/plugin-sdk/media-runtime";
+import { ClawlingApiError } from "./api-types.js";
 export function inferMediaKindFromMime(mime) {
     if (!mime)
         return "file";
@@ -10,7 +11,178 @@ export function inferMediaKindFromMime(mime) {
         return "video";
     return "file";
 }
-const DEFAULT_MEDIA_MAX_BYTES = 20 * 1024 * 1024;
+/**
+ * Single-file ceiling of the upstream msghub media service — its
+ * `media.max_size_bytes` is `104857600` in every shipped upstream config, and a
+ * larger body is rejected with HTTP 413 / business code `41301`. The plugin
+ * mirrors the server capability rather than under-reporting it: a lower local
+ * cap silently fails attachments the service would accept.
+ */
+export const CLAWCHAT_MEDIA_MAX_BYTES = 100 * 1024 * 1024;
+const DEFAULT_MEDIA_MAX_BYTES = CLAWCHAT_MEDIA_MAX_BYTES;
+/** Three attempts per attachment = the initial upload plus two backoff retries. */
+export const DEFAULT_UPLOAD_RETRY_POLICY = {
+    maxAttempts: 3,
+    baseDelayMs: 300,
+    maxDelayMs: 2_000,
+};
+/** Bounded exponential backoff for the wait AFTER 1-based `attempt`. */
+export function uploadRetryDelayMs(attempt, policy = DEFAULT_UPLOAD_RETRY_POLICY) {
+    return Math.min(policy.baseDelayMs * 2 ** Math.max(0, attempt - 1), policy.maxDelayMs);
+}
+/**
+ * Media-service business codes that reject THIS payload on its merits:
+ * missing file part, empty upload, bad token, too large, disallowed MIME.
+ * Re-sending identical bytes produces an identical rejection, so these never
+ * retry regardless of status.
+ */
+const PERMANENT_BUSINESS_CODES = new Set([40001, 40002, 40101, 41301, 41501]);
+/**
+ * Socket/DNS/timeout signatures for throws that never made it through the API
+ * client's own wrapping (e.g. an `AbortError` surfaced by the host fetch).
+ */
+const TRANSIENT_ERROR_PATTERN = /(econnreset|econnrefused|econnaborted|etimedout|epipe|ehostunreach|enetunreach|enetdown|eai_again|enotfound|socket hang up|network error|fetch failed|timed out|timeout|aborted)/i;
+function isRetryableHttpStatus(status) {
+    // 408 request timeout, 425 too early, 429 rate limited, plus every 5xx.
+    return status === 408 || status === 425 || status === 429 || status >= 500;
+}
+const API_ERROR_KINDS = ["auth", "api", "transport", "validation"];
+function asClawlingApiError(err) {
+    if (err instanceof ClawlingApiError)
+        return err;
+    // Structural fallback: a duck-typed error from a mocked client still carries
+    // the diagnostics we must log, and misreading it as `unknown` would lose them.
+    if (err instanceof Error &&
+        API_ERROR_KINDS.includes(err.kind)) {
+        return err;
+    }
+    return undefined;
+}
+function isRetryableFailure(detail) {
+    // Local pre-flight failures and credential rejections do not get better by
+    // trying again with the same bytes and the same token.
+    if (detail.kind === "validation" || detail.kind === "auth")
+        return false;
+    if (typeof detail.code === "number" && PERMANENT_BUSINESS_CODES.has(detail.code))
+        return false;
+    if (typeof detail.status === "number")
+        return isRetryableHttpStatus(detail.status);
+    // `transport` without a status is a failure before any response existed —
+    // DNS, connection reset, timeout: the transient case this retry loop is for.
+    if (detail.kind === "transport")
+        return true;
+    // `api` without a status is a server-declared business rejection.
+    return false;
+}
+/** Classify a thrown upload error into structured diagnostics + a retry verdict. */
+export function classifyUploadError(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    const api = asClawlingApiError(err);
+    if (!api) {
+        return { kind: "unknown", message, retryable: TRANSIENT_ERROR_PATTERN.test(message) };
+    }
+    const detail = {
+        kind: api.kind,
+        message,
+        retryable: false,
+        ...(typeof api.meta?.status === "number" ? { status: api.meta.status } : {}),
+        ...(typeof api.meta?.code === "number" ? { code: api.meta.code } : {}),
+        ...(api.meta?.path ? { path: api.meta.path } : {}),
+        ...(api.meta?.data !== undefined ? { data: api.meta.data } : {}),
+    };
+    detail.retryable = isRetryableFailure(detail);
+    return detail;
+}
+const BEARER_PATTERN = /\b(bearer)\s+[A-Za-z0-9._~+/=-]+/gi;
+const JWT_PATTERN = /\beyJ[A-Za-z0-9._~+/=-]{10,}/g;
+const SECRET_FIELD_PATTERN = /("?\b(?:authorization|access[_-]?token|refresh[_-]?token|token|api[_-]?key|apikey|password|passwd|secret|signature|x-amz-signature|x-amz-credential)\b"?\s*[:=]\s*)"?[^"',\s&}]+"?/gi;
+/**
+ * Strip anything credential-shaped out of a diagnostic string. Upload failures
+ * are logged with the server's `msg`/`data` verbatim, and neither is under this
+ * plugin's control — a backend that echoes a header or a presigned URL must not
+ * turn a log line into a token leak.
+ */
+export function redactMediaDiagnostics(text) {
+    return text
+        .replace(BEARER_PATTERN, "$1 [redacted]")
+        .replace(SECRET_FIELD_PATTERN, '$1"[redacted]"')
+        .replace(JWT_PATTERN, "[redacted]");
+}
+/**
+ * Reduce an outbound media source to something safe to log: presigned HTTP(S)
+ * URLs carry their credential in the query string, so only origin + path
+ * survive. Local paths are kept (they are the only way to identify the
+ * attachment) but never their contents.
+ */
+export function sanitizeMediaSource(source) {
+    try {
+        const parsed = new URL(source);
+        if (parsed.protocol === "http:" || parsed.protocol === "https:") {
+            const trimmed = `${parsed.origin}${parsed.pathname}`;
+            return parsed.search || parsed.hash ? `${trimmed} (query redacted)` : trimmed;
+        }
+    }
+    catch {
+        // Not a URL — a local path. Fall through to plain redaction.
+    }
+    return redactMediaDiagnostics(source);
+}
+function serializeDiagnosticValue(value, limit = 300) {
+    let text;
+    try {
+        text = typeof value === "string" ? value : (JSON.stringify(value) ?? String(value));
+    }
+    catch {
+        text = "[unserializable]";
+    }
+    const redacted = redactMediaDiagnostics(text);
+    return redacted.length > limit ? `${redacted.slice(0, limit)}…` : redacted;
+}
+/**
+ * Render a failure as `key=value` diagnostics: error kind, HTTP status,
+ * business code, request path, response data, plus file name / size / MIME.
+ * Everything passes through {@link redactMediaDiagnostics} first — no token,
+ * `Authorization` header, or local file content ever reaches a log line.
+ */
+export function formatOutboundMediaFailure(failure) {
+    const { detail } = failure;
+    return [
+        `source=${failure.source}`,
+        ...(failure.fileName ? [`file=${serializeDiagnosticValue(failure.fileName, 120)}`] : []),
+        ...(typeof failure.size === "number" ? [`size=${failure.size}`] : []),
+        ...(failure.mime ? [`mime=${failure.mime}`] : []),
+        `stage=${failure.stage}`,
+        `attempts=${failure.attempts}`,
+        `retryable=${detail.retryable}`,
+        `kind=${detail.kind}`,
+        ...(typeof detail.status === "number" ? [`status=${detail.status}`] : []),
+        ...(typeof detail.code === "number" ? [`code=${detail.code}`] : []),
+        ...(detail.path ? [`path=${detail.path}`] : []),
+        ...(detail.data !== undefined ? [`data=${serializeDiagnosticValue(detail.data)}`] : []),
+        `error=${serializeDiagnosticValue(detail.message)}`,
+    ].join(" ");
+}
+function buildFailure(input) {
+    const failure = { ...input, summary: "" };
+    failure.summary = formatOutboundMediaFailure(failure);
+    return failure;
+}
+/**
+ * Build the send-blocking error message for a batch that lost attachments.
+ *
+ * Both call sites (the `sendMedia` adapter and the reply dispatcher) reject the
+ * whole send on a shortfall, so this is the only text the agent sees: it must
+ * name every failed attachment with its reason instead of a generic
+ * "upload failed" that leaves the operator with nothing to act on.
+ */
+export function describeOutboundMediaShortfall(result, requested) {
+    const missing = Math.max(requested - result.fragments.length, result.failures.length);
+    const outcome = result.fragments.length > 0 ? "partial success" : "all failed";
+    const reasons = result.failures.map((f, i) => `[${i + 1}] ${f.summary}`).join(" | ");
+    return (`clawchat-plugin-openclaw failed to upload ${missing}/${requested} outbound media ` +
+        `attachment(s) (${outcome}, ${result.fragments.length}/${requested} uploaded); ` +
+        `message not sent${reasons ? `: ${reasons}` : ""}`);
+}
 /**
  * Fetch each remote URL via the shared media runtime, persist to a local
  * cache, and return the list of local paths.
@@ -33,53 +205,113 @@ export async function fetchInboundMedia(items, ctx) {
             paths.push(saved.path);
         }
         catch (err) {
-            ctx.log?.info?.(`clawchat-plugin-openclaw inbound media skipped: ${item.url} (${err instanceof Error ? err.message : String(err)})`);
+            ctx.log?.info?.(`clawchat-plugin-openclaw inbound media skipped: ${sanitizeMediaSource(item.url)} (${redactMediaDiagnostics(err instanceof Error ? err.message : String(err))})`);
         }
     }
     return paths;
 }
 /**
  * Upload each URL (remote or local path) to /media/upload via the api
- * client and return a fragment ready to splice into `body.fragments`.
+ * client and return fragments ready to splice into `body.fragments`, plus a
+ * structured failure record for every attachment that did not make it.
  *
  * Uses the host runtime's `runtime.media.loadWebMedia`, so local-root
  * enforcement and media-loading policy stay aligned with the current
  * OpenClaw runtime instead of a directly imported helper.
  *
- * Single-upload failures log at error and are dropped; the remaining
- * fragments still come back so a partially-failing batch still sends the
- * working media.
+ * Transient upload faults (network/timeout, HTTP 5xx, 429/408) are retried
+ * with bounded exponential backoff per {@link DEFAULT_UPLOAD_RETRY_POLICY};
+ * local validation, auth, and definitive business rejections fail on the first
+ * attempt. One attachment giving up never aborts the batch — every remaining
+ * URL is still loaded and uploaded, and its fragment comes back — so the
+ * caller can distinguish partial success from a total failure and report why.
  */
 export async function uploadOutboundMedia(urls, ctx) {
+    const result = { fragments: [], failures: [] };
     if (urls.length === 0)
-        return [];
+        return result;
     const maxBytes = ctx.maxBytes ?? DEFAULT_MEDIA_MAX_BYTES;
-    const out = [];
+    const policy = { ...DEFAULT_UPLOAD_RETRY_POLICY, ...(ctx.retry ?? {}) };
+    const sleep = ctx.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
     for (const url of urls) {
+        const source = sanitizeMediaSource(url);
+        let loaded;
         try {
-            const loaded = await ctx.runtime.media.loadWebMedia(url, buildOutboundMediaLoadOptions({
+            loaded = await ctx.runtime.media.loadWebMedia(url, buildOutboundMediaLoadOptions({
                 maxBytes,
                 ...(ctx.mediaAccess ? { mediaAccess: ctx.mediaAccess } : {}),
                 ...(ctx.mediaLocalRoots ? { mediaLocalRoots: ctx.mediaLocalRoots } : {}),
                 ...(ctx.mediaReadFile ? { mediaReadFile: ctx.mediaReadFile } : {}),
             }));
-            const uploaded = await ctx.apiClient.uploadMedia({
-                buffer: loaded.buffer,
-                filename: loaded.fileName ?? "upload.bin",
-                mime: loaded.contentType,
-            });
-            const fragment = {
-                kind: uploaded.kind,
-                url: uploaded.url,
-                name: uploaded.name,
-                mime: uploaded.mime,
-                size: uploaded.size,
-            };
-            out.push(fragment);
         }
         catch (err) {
-            ctx.log?.error?.(`clawchat-plugin-openclaw outbound media upload failed: ${url} (${err instanceof Error ? err.message : String(err)})`);
+            // Loading is host policy plus a one-shot read (missing path, outside the
+            // allowed roots, over `maxBytes`). Nothing here is transient, so it is
+            // never retried — and the bytes never reached the media service.
+            const failure = buildFailure({
+                source,
+                stage: "load",
+                attempts: 1,
+                detail: { ...classifyUploadError(err), retryable: false },
+            });
+            result.failures.push(failure);
+            ctx.log?.error?.(`clawchat-plugin-openclaw outbound media load failed: ${failure.summary}`);
+            continue;
+        }
+        const fileName = loaded.fileName ?? "upload.bin";
+        const size = loaded.buffer.byteLength;
+        const mime = loaded.contentType;
+        let pending;
+        let attempts = 0;
+        for (let attempt = 1; attempt <= policy.maxAttempts; attempt += 1) {
+            attempts = attempt;
+            try {
+                const uploaded = await ctx.apiClient.uploadMedia({
+                    buffer: loaded.buffer,
+                    filename: fileName,
+                    ...(mime ? { mime } : {}),
+                });
+                result.fragments.push({
+                    kind: uploaded.kind,
+                    url: uploaded.url,
+                    name: uploaded.name,
+                    mime: uploaded.mime,
+                    size: uploaded.size,
+                });
+                pending = undefined;
+                break;
+            }
+            catch (err) {
+                pending = classifyUploadError(err);
+                if (!pending.retryable || attempt >= policy.maxAttempts)
+                    break;
+                const delayMs = uploadRetryDelayMs(attempt, policy);
+                const attemptFailure = buildFailure({
+                    source,
+                    stage: "upload",
+                    attempts: attempt,
+                    fileName,
+                    size,
+                    ...(mime ? { mime } : {}),
+                    detail: pending,
+                });
+                ctx.log?.info?.(`clawchat-plugin-openclaw outbound media upload retry ${attempt}/${policy.maxAttempts - 1} in ${delayMs}ms: ${attemptFailure.summary}`);
+                await sleep(delayMs);
+            }
+        }
+        if (pending) {
+            const failure = buildFailure({
+                source,
+                stage: "upload",
+                attempts,
+                fileName,
+                size,
+                ...(mime ? { mime } : {}),
+                detail: pending,
+            });
+            result.failures.push(failure);
+            ctx.log?.error?.(`clawchat-plugin-openclaw outbound media upload failed: ${failure.summary}`);
         }
     }
-    return out;
+    return result;
 }

package/dist/src/outbound.js

@@ -6,7 +6,7 @@ import { chunkMarkdownText } from "openclaw/plugin-sdk/reply-runtime";
 import { createOpenclawClawlingApiClient } from "./api-client.js";
 import { CHANNEL_ID, resolveOpenclawClawlingAccount } from "./config.js";
 import { applyTextMentionLabels, buildMentionMessageFragments, normalizeMentionTargets, textToFragments, } from "./message-mapper.js";
-import { uploadOutboundMedia } from "./media-runtime.js";
+import { describeOutboundMediaShortfall, uploadOutboundMedia, } from "./media-runtime.js";
 import { isClawChatNoopResponseText } from "./profile-prompt.js";
 import { stripNoReplyTokens } from "./no-reply.js";
 import { getOpenclawClawlingClient, getOpenclawClawlingRuntime, waitForOpenclawClawlingClient, } from "./runtime.js";
@@ -723,16 +723,20 @@ export const openclawClawlingOutbound = {
                 token: account.token,
                 userId: account.userId,
             });
-            const mediaFragments = await uploadOutboundMedia([mediaUrl.trim()], {
+            const uploadResult = 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}`);
+            // Single-attachment path, so "shortfall" is always a total failure here;
+            // the message still carries the structured, redacted reason instead of a
+            // bare "failed to upload" the operator cannot act on.
+            if (uploadResult.fragments.length === 0) {
+                throw new Error(describeOutboundMediaShortfall(uploadResult, 1));
             }
+            const mediaFragments = uploadResult.fragments;
             const target = parseOpenclawRecipient(to);
             const messageId = mintOutboundMessageId(account);
             const claimText = (text ?? "").trim();

package/dist/src/protocol-types.js

@@ -8,6 +8,7 @@ export const EVENT = {
     MESSAGE_ERROR: "message.error",
     MESSAGE_REPLY: "message.reply",
     MESSAGE_REACTION: "message.reaction",
+    MESSAGE_RECALL: "message.recall",
     MESSAGE_CREATED: "message.created",
     MESSAGE_ADD: "message.add",
     MESSAGE_DONE: "message.done",
@@ -90,3 +91,20 @@ export class StateError extends Error {
 export function isBusinessDispatchEvent(event) {
     return event === EVENT.MESSAGE_SEND || event === EVENT.MESSAGE_REPLY;
 }
+/**
+ * Pull the id to delete out of a `message.recall` payload.
+ *
+ * Exists as a pure function, apart from the socket, for the same reason the
+ * mistake it guards is worth guarding: `payload.message_id` is right there and
+ * looks like the answer, but it is the `rcl:` slot. Deleting by it removes
+ * nothing and reads exactly like working code.
+ *
+ * Answers `null` for anything unusable, so a recall we cannot resolve deletes
+ * nothing rather than something adjacent.
+ */
+export function recallTargetMessageId(payload) {
+    if (!payload || typeof payload !== "object")
+        return null;
+    const target = payload.target_message_id;
+    return typeof target === "string" && target.length > 0 ? target : null;
+}

package/dist/src/reply-dispatcher.js

@@ -2,7 +2,7 @@ import { interactiveReplyToPresentation, renderMessagePresentationFallbackText,
 import { resolveOutboundMediaUrls } from "openclaw/plugin-sdk/reply-payload";
 import { createOpenclawClawlingApiClient } from "./api-client.js";
 import { effectiveOutputVisibility, } from "./config.js";
-import { uploadOutboundMedia } from "./media-runtime.js";
+import { describeOutboundMediaShortfall, uploadOutboundMedia, } from "./media-runtime.js";
 import { mintMessageId, sendOpenclawClawlingText, } from "./outbound.js";
 import { isClawChatNoopResponseText } from "./profile-prompt.js";
 import { consumeTerminalClawChatSend } from "./terminal-send.js";
@@ -293,15 +293,19 @@ export function createOpenclawClawlingReplyDispatcher(options) {
             log?.info?.(`[${account.accountId}] clawchat-plugin-openclaw outbound media skipped: baseUrl not configured`);
             return [];
         }
-        const fragments = await uploadOutboundMedia(urls, { apiClient, runtime, log });
-        if (fragments.length < urls.length) {
-            // uploadOutboundMedia drops a failed item with only a log line. A shortfall
-            // means an attachment never reached the media service; surfacing it (parity
-            // with the adapter path in outbound.ts and with the Hermes plugin) stops a
-            // text-only frame from going out and reading as a successful send.
-            throw new Error(`clawchat-plugin-openclaw failed to upload ${urls.length - fragments.length}/${urls.length} outbound media attachment(s); message not sent`);
+        const result = await uploadOutboundMedia(urls, { apiClient, runtime, log });
+        if (result.fragments.length < urls.length) {
+            // uploadOutboundMedia never aborts the batch: every URL is attempted and
+            // the successful fragments still come back. A shortfall — partial success
+            // or total failure alike — means at least one attachment never reached
+            // the media service, so the whole send is rejected (parity with the
+            // adapter path in outbound.ts and with the Hermes plugin) rather than
+            // letting a text-only frame go out reading as a successful send. The
+            // thrown message carries each failure's structured, redacted diagnostics
+            // so the agent is not left with a reasonless generic error.
+            throw new Error(describeOutboundMediaShortfall(result, urls.length));
         }
-        return fragments;
+        return result.fragments;
     }
     // ----- Reply state ------------------------------------------------------
     let reasoningText = "";

package/dist/src/runtime.js

@@ -1,4 +1,4 @@
-import { AckTimeoutError, AuthError, ProtocolError, StateError, TransportError, EVENT, } from "./protocol-types.js";
+import { AckTimeoutError, AuthError, ProtocolError, StateError, TransportError, EVENT, recallTargetMessageId, } from "./protocol-types.js";
 import { waitUntilAbort } from "openclaw/plugin-sdk/channel-lifecycle";
 import { hasControlCommand } from "openclaw/plugin-sdk/command-detection";
 import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
@@ -16,7 +16,7 @@ import { CHANNEL_ID, effectiveOutputVisibility, effectiveGroupCommandMode, effec
 import { isValidChatId } from "./ws-client.js";
 import { dispatchOpenclawClawlingInbound } from "./inbound.js";
 import { PendingConsentStore, cleanupTombstonedManagedSkills, handleOwnerConsentReply, managedSkillExists, readLocalSkillState, resolveBundledSkillsDir, resolveManagedSkillsDir, runSkillUpdateCheck, } from "./skill-update.js";
-import { fetchInboundMedia } from "./media-runtime.js";
+import { CLAWCHAT_MEDIA_MAX_BYTES, fetchInboundMedia } from "./media-runtime.js";
 import { createOpenclawClawlingReplyDispatcher } from "./reply-dispatcher.js";
 import { runWithTerminalClawChatSendScope } from "./terminal-send.js";
 import { flushAlignedOutboundQueue, getAlignedOutboundQueueSize, sendOpenclawClawlingText, setAlignedOutboundLogContext, } from "./outbound.js";
@@ -2440,7 +2440,7 @@ export async function startOpenclawClawlingGateway(params) {
             ? await fetchInboundMedia(turn.mediaItems, {
                 runtime,
                 log,
-                maxBytes: 20 * 1024 * 1024,
+                maxBytes: CLAWCHAT_MEDIA_MAX_BYTES,
             })
             : [];
         if (inboundPaths.length > 0) {
@@ -2907,6 +2907,33 @@ export async function startOpenclawClawlingGateway(params) {
             await handleInboundEnvelope(env);
         })();
     });
+    // `message.recall` — the sender withdrew a message. Erase our own ledger row
+    // so the "Prior group context" block above (MENTION_CONTEXT_N rows, no time
+    // predicate, no retention) can never read it back into a turn.
+    //
+    // Ids only: the frame carries no content, and `payload.message_id` is the
+    // server's `rcl:<target>` slot — the id to delete is `target_message_id`.
+    //
+    // Synchronous and fire-and-forget on purpose. There is no ack to send (the
+    // frame is BestEffort and non-ackable), and no tombstone to write: a Kafka
+    // redelivery of the original can resurrect the row, which is an accepted
+    // known limitation rather than a fourth reimplementation of the mobile
+    // client's tombstone table.
+    client.on("message:recall", (env) => {
+        const target = recallTargetMessageId(env.payload);
+        if (!target) {
+            log?.info?.(`[${accountId}] clawchat-plugin-openclaw recall ignored (no target_message_id) chat_id=${String(env.chat_id ?? "")}`);
+            return;
+        }
+        const removed = store?.deleteMessagesByMessageId?.({
+            platform: "openclaw",
+            accountId,
+            messageId: target,
+        });
+        const rowsLabel = typeof removed === "number" ? String(removed) : "unavailable";
+        const logFn = typeof removed === "number" ? log?.info : log?.error;
+        logFn?.(`[${accountId}] clawchat-plugin-openclaw recall purged chat_id=${String(env.chat_id ?? "")} msg=${target} rows=${rowsLabel}`);
+    });
     // Initial pull of per-group agent settings at startup (best-effort; errors are
     // logged). `bypassRefresh: true` (Finding 4) keeps this pre-connect pull from
     // rotating `account.token` out from under the already-constructed WS client.

package/dist/src/storage.js

@@ -443,6 +443,38 @@ export class ClawChatStore {
                 .run(input.eventType, input.traceId ?? null, input.chatId ?? null, input.text ?? null, toJson(input.raw), input.accountId, input.kind, input.direction, input.messageId);
         });
     }
+    /**
+     * Erase every ledger row for one `message_id` — the local half of a
+     * server-authorised recall (`message.recall`, docs/client-integration.md §9.8).
+     *
+     * **The only DELETE in this store, and deliberately so.** There is no prune
+     * and no retention on `clawchat_messages`: without this, a message recalled
+     * ninety seconds after it was sent stays one @-mention away from being read
+     * back aloud under "Prior group context" for as long as the group is quiet.
+     *
+     * Scoped to `(platform, account_id)` so one account's recall cannot reach
+     * another's rows, and matched on `message_id`, which seeks via the
+     * single-column `idx_clawchat_messages_message_id` before the `platform` /
+     * `account_id` filter is applied — so this is a lookup, not a table scan.
+     *
+     * Answers the number of rows removed. `0` is a normal outcome, not a failure:
+     * the row may never have been stored (a message that arrived before this
+     * account was paired, or one dropped by the inbound filter). `null` means the
+     * store is unavailable.
+     */
+    deleteMessagesByMessageId(input) {
+        // An empty id would match every row whose message_id is '' — deleting
+        // everything the store never managed to key. Refuse rather than guess.
+        if (!input.messageId)
+            return 0;
+        return this.write(() => {
+            const result = this.requireDb()
+                .prepare(`DELETE FROM clawchat_messages
+            WHERE platform = ? AND account_id = ? AND message_id = ?`)
+                .run(input.platform, input.accountId, input.messageId);
+            return Number(result.changes);
+        });
+    }
     startConnection(input) {
         return this.write(() => {
             const now = input.connectStartedAt ?? Date.now();

package/dist/src/ws-client.js

@@ -558,6 +558,11 @@ export class ClawChatClient extends EventEmitter {
             return this.onMessageError(env);
         if (isBusinessDispatchEvent(env.event))
             this.emit("message", env);
+        // Deliberately NOT a business dispatch event: `message` feeds the turn
+        // pipeline, and a recall has no body to turn into a prompt. It is an
+        // instruction to delete, so it gets its own emitter and its own consumer.
+        if (env.event === EVENT.MESSAGE_RECALL)
+            this.emit("message:recall", env);
         if (env.event === EVENT.MESSAGE_CREATED)
             this.emit("message:created", env);
         if (env.event === EVENT.MESSAGE_ADD)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawling/clawchat-plugin-openclaw",
-  "version": "2026.8.14-2",
+  "version": "2026.8.22-1",
   "description": "OpenClaw ClawChat channel plugin",
   "license": "MIT",
   "author": "CLAWLING PTE. LTD.",

package/src/media-runtime.ts

@@ -5,6 +5,7 @@ import {
   type OutboundMediaReadFile,
 } from "openclaw/plugin-sdk/media-runtime";
 import type { OpenclawClawlingApiClient } from "./api-client.ts";
+import { ClawlingApiError, type ClawlingApiErrorKind } from "./api-types.ts";
 
 /**
  * Local structural superset of the protocol media fragment narrow types.
@@ -50,6 +51,10 @@ export interface UploadOutboundCtx {
   mediaLocalRoots?: readonly string[] | "any";
   /** Host-provided read bridge for sandbox/allowed local media paths. */
   mediaReadFile?: OutboundMediaReadFile;
+  /** Overrides for the transient-failure retry budget. Merged over the default policy. */
+  retry?: Partial<UploadRetryPolicy>;
+  /** Test seam for the backoff wait. Defaults to `setTimeout`. */
+  sleep?: (ms: number) => Promise<void>;
 }
 
 export function inferMediaKindFromMime(mime: string | undefined): MediaItem["kind"] {
@@ -60,7 +65,250 @@ export function inferMediaKindFromMime(mime: string | undefined): MediaItem["kin
   return "file";
 }
 
-const DEFAULT_MEDIA_MAX_BYTES = 20 * 1024 * 1024;
+/**
+ * Single-file ceiling of the upstream msghub media service — its
+ * `media.max_size_bytes` is `104857600` in every shipped upstream config, and a
+ * larger body is rejected with HTTP 413 / business code `41301`. The plugin
+ * mirrors the server capability rather than under-reporting it: a lower local
+ * cap silently fails attachments the service would accept.
+ */
+export const CLAWCHAT_MEDIA_MAX_BYTES = 100 * 1024 * 1024;
+
+const DEFAULT_MEDIA_MAX_BYTES = CLAWCHAT_MEDIA_MAX_BYTES;
+
+export interface UploadRetryPolicy {
+  /** Total attempts per attachment, including the first one. */
+  maxAttempts: number;
+  /** Wait after the first failed attempt; doubled per further attempt. */
+  baseDelayMs: number;
+  /** Upper bound on any single wait, so the backoff stays bounded. */
+  maxDelayMs: number;
+}
+
+/** Three attempts per attachment = the initial upload plus two backoff retries. */
+export const DEFAULT_UPLOAD_RETRY_POLICY: UploadRetryPolicy = {
+  maxAttempts: 3,
+  baseDelayMs: 300,
+  maxDelayMs: 2_000,
+};
+
+/** Bounded exponential backoff for the wait AFTER 1-based `attempt`. */
+export function uploadRetryDelayMs(
+  attempt: number,
+  policy: UploadRetryPolicy = DEFAULT_UPLOAD_RETRY_POLICY,
+): number {
+  return Math.min(policy.baseDelayMs * 2 ** Math.max(0, attempt - 1), policy.maxDelayMs);
+}
+
+/** Structured, credential-free diagnostics for one failed upload attempt. */
+export interface UploadErrorDetail {
+  /** `ClawlingApiError.kind`, or `"unknown"` for a non-API throw. */
+  kind: ClawlingApiErrorKind | "unknown";
+  /** HTTP status, when the failure carried a response. */
+  status?: number;
+  /** Business `code` from the `{ code, msg, data }` envelope. */
+  code?: number;
+  /** Request path the failure came from (e.g. `/media/upload`). */
+  path?: string;
+  /** Response `data` payload, when the envelope carried one. */
+  data?: unknown;
+  message: string;
+  retryable: boolean;
+}
+
+/**
+ * Media-service business codes that reject THIS payload on its merits:
+ * missing file part, empty upload, bad token, too large, disallowed MIME.
+ * Re-sending identical bytes produces an identical rejection, so these never
+ * retry regardless of status.
+ */
+const PERMANENT_BUSINESS_CODES = new Set([40001, 40002, 40101, 41301, 41501]);
+
+/**
+ * Socket/DNS/timeout signatures for throws that never made it through the API
+ * client's own wrapping (e.g. an `AbortError` surfaced by the host fetch).
+ */
+const TRANSIENT_ERROR_PATTERN =
+  /(econnreset|econnrefused|econnaborted|etimedout|epipe|ehostunreach|enetunreach|enetdown|eai_again|enotfound|socket hang up|network error|fetch failed|timed out|timeout|aborted)/i;
+
+function isRetryableHttpStatus(status: number): boolean {
+  // 408 request timeout, 425 too early, 429 rate limited, plus every 5xx.
+  return status === 408 || status === 425 || status === 429 || status >= 500;
+}
+
+const API_ERROR_KINDS: readonly string[] = ["auth", "api", "transport", "validation"];
+
+function asClawlingApiError(err: unknown): ClawlingApiError | undefined {
+  if (err instanceof ClawlingApiError) return err;
+  // Structural fallback: a duck-typed error from a mocked client still carries
+  // the diagnostics we must log, and misreading it as `unknown` would lose them.
+  if (
+    err instanceof Error &&
+    API_ERROR_KINDS.includes((err as { kind?: unknown }).kind as string)
+  ) {
+    return err as ClawlingApiError;
+  }
+  return undefined;
+}
+
+function isRetryableFailure(detail: UploadErrorDetail): boolean {
+  // Local pre-flight failures and credential rejections do not get better by
+  // trying again with the same bytes and the same token.
+  if (detail.kind === "validation" || detail.kind === "auth") return false;
+  if (typeof detail.code === "number" && PERMANENT_BUSINESS_CODES.has(detail.code)) return false;
+  if (typeof detail.status === "number") return isRetryableHttpStatus(detail.status);
+  // `transport` without a status is a failure before any response existed —
+  // DNS, connection reset, timeout: the transient case this retry loop is for.
+  if (detail.kind === "transport") return true;
+  // `api` without a status is a server-declared business rejection.
+  return false;
+}
+
+/** Classify a thrown upload error into structured diagnostics + a retry verdict. */
+export function classifyUploadError(err: unknown): UploadErrorDetail {
+  const message = err instanceof Error ? err.message : String(err);
+  const api = asClawlingApiError(err);
+  if (!api) {
+    return { kind: "unknown", message, retryable: TRANSIENT_ERROR_PATTERN.test(message) };
+  }
+  const detail: UploadErrorDetail = {
+    kind: api.kind,
+    message,
+    retryable: false,
+    ...(typeof api.meta?.status === "number" ? { status: api.meta.status } : {}),
+    ...(typeof api.meta?.code === "number" ? { code: api.meta.code } : {}),
+    ...(api.meta?.path ? { path: api.meta.path } : {}),
+    ...(api.meta?.data !== undefined ? { data: api.meta.data } : {}),
+  };
+  detail.retryable = isRetryableFailure(detail);
+  return detail;
+}
+
+const BEARER_PATTERN = /\b(bearer)\s+[A-Za-z0-9._~+/=-]+/gi;
+const JWT_PATTERN = /\beyJ[A-Za-z0-9._~+/=-]{10,}/g;
+const SECRET_FIELD_PATTERN =
+  /("?\b(?:authorization|access[_-]?token|refresh[_-]?token|token|api[_-]?key|apikey|password|passwd|secret|signature|x-amz-signature|x-amz-credential)\b"?\s*[:=]\s*)"?[^"',\s&}]+"?/gi;
+
+/**
+ * Strip anything credential-shaped out of a diagnostic string. Upload failures
+ * are logged with the server's `msg`/`data` verbatim, and neither is under this
+ * plugin's control — a backend that echoes a header or a presigned URL must not
+ * turn a log line into a token leak.
+ */
+export function redactMediaDiagnostics(text: string): string {
+  return text
+    .replace(BEARER_PATTERN, "$1 [redacted]")
+    .replace(SECRET_FIELD_PATTERN, '$1"[redacted]"')
+    .replace(JWT_PATTERN, "[redacted]");
+}
+
+/**
+ * Reduce an outbound media source to something safe to log: presigned HTTP(S)
+ * URLs carry their credential in the query string, so only origin + path
+ * survive. Local paths are kept (they are the only way to identify the
+ * attachment) but never their contents.
+ */
+export function sanitizeMediaSource(source: string): string {
+  try {
+    const parsed = new URL(source);
+    if (parsed.protocol === "http:" || parsed.protocol === "https:") {
+      const trimmed = `${parsed.origin}${parsed.pathname}`;
+      return parsed.search || parsed.hash ? `${trimmed} (query redacted)` : trimmed;
+    }
+  } catch {
+    // Not a URL — a local path. Fall through to plain redaction.
+  }
+  return redactMediaDiagnostics(source);
+}
+
+function serializeDiagnosticValue(value: unknown, limit = 300): string {
+  let text: string;
+  try {
+    text = typeof value === "string" ? value : (JSON.stringify(value) ?? String(value));
+  } catch {
+    text = "[unserializable]";
+  }
+  const redacted = redactMediaDiagnostics(text);
+  return redacted.length > limit ? `${redacted.slice(0, limit)}…` : redacted;
+}
+
+/** Which step of the outbound pipeline gave up on this attachment. */
+export type OutboundMediaFailureStage = "load" | "upload";
+
+export interface OutboundMediaFailure {
+  /** Redacted source URL / local path the attachment came from. */
+  source: string;
+  stage: OutboundMediaFailureStage;
+  /** Attempts actually made, including the first. */
+  attempts: number;
+  fileName?: string;
+  /** Byte length of the loaded payload. */
+  size?: number;
+  mime?: string;
+  detail: UploadErrorDetail;
+  /** One-line redacted diagnostic — the same text written to the error log. */
+  summary: string;
+}
+
+export interface OutboundMediaUploadResult {
+  /** Fragments for every attachment that uploaded successfully. */
+  fragments: ClawlingMediaFragment[];
+  /** One entry per attachment that did not, in request order. */
+  failures: OutboundMediaFailure[];
+}
+
+/**
+ * Render a failure as `key=value` diagnostics: error kind, HTTP status,
+ * business code, request path, response data, plus file name / size / MIME.
+ * Everything passes through {@link redactMediaDiagnostics} first — no token,
+ * `Authorization` header, or local file content ever reaches a log line.
+ */
+export function formatOutboundMediaFailure(failure: OutboundMediaFailure): string {
+  const { detail } = failure;
+  return [
+    `source=${failure.source}`,
+    ...(failure.fileName ? [`file=${serializeDiagnosticValue(failure.fileName, 120)}`] : []),
+    ...(typeof failure.size === "number" ? [`size=${failure.size}`] : []),
+    ...(failure.mime ? [`mime=${failure.mime}`] : []),
+    `stage=${failure.stage}`,
+    `attempts=${failure.attempts}`,
+    `retryable=${detail.retryable}`,
+    `kind=${detail.kind}`,
+    ...(typeof detail.status === "number" ? [`status=${detail.status}`] : []),
+    ...(typeof detail.code === "number" ? [`code=${detail.code}`] : []),
+    ...(detail.path ? [`path=${detail.path}`] : []),
+    ...(detail.data !== undefined ? [`data=${serializeDiagnosticValue(detail.data)}`] : []),
+    `error=${serializeDiagnosticValue(detail.message)}`,
+  ].join(" ");
+}
+
+function buildFailure(input: Omit<OutboundMediaFailure, "summary">): OutboundMediaFailure {
+  const failure: OutboundMediaFailure = { ...input, summary: "" };
+  failure.summary = formatOutboundMediaFailure(failure);
+  return failure;
+}
+
+/**
+ * Build the send-blocking error message for a batch that lost attachments.
+ *
+ * Both call sites (the `sendMedia` adapter and the reply dispatcher) reject the
+ * whole send on a shortfall, so this is the only text the agent sees: it must
+ * name every failed attachment with its reason instead of a generic
+ * "upload failed" that leaves the operator with nothing to act on.
+ */
+export function describeOutboundMediaShortfall(
+  result: OutboundMediaUploadResult,
+  requested: number,
+): string {
+  const missing = Math.max(requested - result.fragments.length, result.failures.length);
+  const outcome = result.fragments.length > 0 ? "partial success" : "all failed";
+  const reasons = result.failures.map((f, i) => `[${i + 1}] ${f.summary}`).join(" | ");
+  return (
+    `clawchat-plugin-openclaw failed to upload ${missing}/${requested} outbound media ` +
+    `attachment(s) (${outcome}, ${result.fragments.length}/${requested} uploaded); ` +
+    `message not sent${reasons ? `: ${reasons}` : ""}`
+  );
+}
 
 /**
  * Fetch each remote URL via the shared media runtime, persist to a local
@@ -92,7 +340,7 @@ export async function fetchInboundMedia(
       paths.push(saved.path);
     } catch (err) {
       ctx.log?.info?.(
-        `clawchat-plugin-openclaw inbound media skipped: ${item.url} (${err instanceof Error ? err.message : String(err)})`,
+        `clawchat-plugin-openclaw inbound media skipped: ${sanitizeMediaSource(item.url)} (${redactMediaDiagnostics(err instanceof Error ? err.message : String(err))})`,
       );
     }
   }
@@ -101,26 +349,34 @@ export async function fetchInboundMedia(
 
 /**
  * Upload each URL (remote or local path) to /media/upload via the api
- * client and return a fragment ready to splice into `body.fragments`.
+ * client and return fragments ready to splice into `body.fragments`, plus a
+ * structured failure record for every attachment that did not make it.
  *
  * Uses the host runtime's `runtime.media.loadWebMedia`, so local-root
  * enforcement and media-loading policy stay aligned with the current
  * OpenClaw runtime instead of a directly imported helper.
  *
- * Single-upload failures log at error and are dropped; the remaining
- * fragments still come back so a partially-failing batch still sends the
- * working media.
+ * Transient upload faults (network/timeout, HTTP 5xx, 429/408) are retried
+ * with bounded exponential backoff per {@link DEFAULT_UPLOAD_RETRY_POLICY};
+ * local validation, auth, and definitive business rejections fail on the first
+ * attempt. One attachment giving up never aborts the batch — every remaining
+ * URL is still loaded and uploaded, and its fragment comes back — so the
+ * caller can distinguish partial success from a total failure and report why.
  */
 export async function uploadOutboundMedia(
   urls: string[],
   ctx: UploadOutboundCtx,
-): Promise<ClawlingMediaFragment[]> {
-  if (urls.length === 0) return [];
+): Promise<OutboundMediaUploadResult> {
+  const result: OutboundMediaUploadResult = { fragments: [], failures: [] };
+  if (urls.length === 0) return result;
   const maxBytes = ctx.maxBytes ?? DEFAULT_MEDIA_MAX_BYTES;
-  const out: ClawlingMediaFragment[] = [];
+  const policy: UploadRetryPolicy = { ...DEFAULT_UPLOAD_RETRY_POLICY, ...(ctx.retry ?? {}) };
+  const sleep = ctx.sleep ?? ((ms: number) => new Promise<void>((r) => setTimeout(r, ms)));
   for (const url of urls) {
+    const source = sanitizeMediaSource(url);
+    let loaded: Awaited<ReturnType<PluginRuntime["media"]["loadWebMedia"]>>;
     try {
-      const loaded = await ctx.runtime.media.loadWebMedia(
+      loaded = await ctx.runtime.media.loadWebMedia(
         url,
         buildOutboundMediaLoadOptions({
           maxBytes,
@@ -129,24 +385,74 @@ export async function uploadOutboundMedia(
           ...(ctx.mediaReadFile ? { mediaReadFile: ctx.mediaReadFile } : {}),
         }),
       );
-      const uploaded = await ctx.apiClient.uploadMedia({
-        buffer: loaded.buffer,
-        filename: loaded.fileName ?? "upload.bin",
-        mime: loaded.contentType,
-      });
-      const fragment: ClawlingMediaFragment = {
-        kind: uploaded.kind,
-        url: uploaded.url,
-        name: uploaded.name,
-        mime: uploaded.mime,
-        size: uploaded.size,
-      };
-      out.push(fragment);
     } catch (err) {
-      ctx.log?.error?.(
-        `clawchat-plugin-openclaw outbound media upload failed: ${url} (${err instanceof Error ? err.message : String(err)})`,
-      );
+      // Loading is host policy plus a one-shot read (missing path, outside the
+      // allowed roots, over `maxBytes`). Nothing here is transient, so it is
+      // never retried — and the bytes never reached the media service.
+      const failure = buildFailure({
+        source,
+        stage: "load",
+        attempts: 1,
+        detail: { ...classifyUploadError(err), retryable: false },
+      });
+      result.failures.push(failure);
+      ctx.log?.error?.(`clawchat-plugin-openclaw outbound media load failed: ${failure.summary}`);
+      continue;
+    }
+    const fileName = loaded.fileName ?? "upload.bin";
+    const size = loaded.buffer.byteLength;
+    const mime = loaded.contentType;
+    let pending: UploadErrorDetail | undefined;
+    let attempts = 0;
+    for (let attempt = 1; attempt <= policy.maxAttempts; attempt += 1) {
+      attempts = attempt;
+      try {
+        const uploaded = await ctx.apiClient.uploadMedia({
+          buffer: loaded.buffer,
+          filename: fileName,
+          ...(mime ? { mime } : {}),
+        });
+        result.fragments.push({
+          kind: uploaded.kind,
+          url: uploaded.url,
+          name: uploaded.name,
+          mime: uploaded.mime,
+          size: uploaded.size,
+        });
+        pending = undefined;
+        break;
+      } catch (err) {
+        pending = classifyUploadError(err);
+        if (!pending.retryable || attempt >= policy.maxAttempts) break;
+        const delayMs = uploadRetryDelayMs(attempt, policy);
+        const attemptFailure = buildFailure({
+          source,
+          stage: "upload",
+          attempts: attempt,
+          fileName,
+          size,
+          ...(mime ? { mime } : {}),
+          detail: pending,
+        });
+        ctx.log?.info?.(
+          `clawchat-plugin-openclaw outbound media upload retry ${attempt}/${policy.maxAttempts - 1} in ${delayMs}ms: ${attemptFailure.summary}`,
+        );
+        await sleep(delayMs);
+      }
+    }
+    if (pending) {
+      const failure = buildFailure({
+        source,
+        stage: "upload",
+        attempts,
+        fileName,
+        size,
+        ...(mime ? { mime } : {}),
+        detail: pending,
+      });
+      result.failures.push(failure);
+      ctx.log?.error?.(`clawchat-plugin-openclaw outbound media upload failed: ${failure.summary}`);
     }
   }
-  return out;
+  return result;
 }

package/src/outbound.ts

@@ -16,7 +16,11 @@ import {
   textToFragments,
   type MentionTarget,
 } from "./message-mapper.ts";
-import { uploadOutboundMedia, type ClawlingMediaFragment } from "./media-runtime.ts";
+import {
+  describeOutboundMediaShortfall,
+  uploadOutboundMedia,
+  type ClawlingMediaFragment,
+} from "./media-runtime.ts";
 import { isClawChatNoopResponseText } from "./profile-prompt.ts";
 import { stripNoReplyTokens } from "./no-reply.ts";
 import {
@@ -947,16 +951,20 @@ export const openclawClawlingOutbound: ChannelOutboundAdapter = {
         token: account.token,
         userId: account.userId,
       });
-      const mediaFragments = await uploadOutboundMedia([mediaUrl.trim()], {
+      const uploadResult = 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}`);
+      // Single-attachment path, so "shortfall" is always a total failure here;
+      // the message still carries the structured, redacted reason instead of a
+      // bare "failed to upload" the operator cannot act on.
+      if (uploadResult.fragments.length === 0) {
+        throw new Error(describeOutboundMediaShortfall(uploadResult, 1));
       }
+      const mediaFragments = uploadResult.fragments;
       const target = parseOpenclawRecipient(to);
       const messageId = mintOutboundMessageId(account);
       const claimText = (text ?? "").trim();

package/src/protocol-types.ts

@@ -8,6 +8,7 @@ export const EVENT = {
   MESSAGE_ERROR: "message.error",
   MESSAGE_REPLY: "message.reply",
   MESSAGE_REACTION: "message.reaction",
+  MESSAGE_RECALL: "message.recall",
   MESSAGE_CREATED: "message.created",
   MESSAGE_ADD: "message.add",
   MESSAGE_DONE: "message.done",
@@ -361,3 +362,39 @@ export class StateError extends Error {
 export function isBusinessDispatchEvent(event: string): boolean {
   return event === EVENT.MESSAGE_SEND || event === EVENT.MESSAGE_REPLY;
 }
+
+/**
+ * `message.recall` downlink payload (docs/client-integration.md §9.8).
+ *
+ * **Ids only, never content.** The frame relays an instruction to delete, not
+ * a copy of what is being deleted — which is what makes it compatible with the
+ * feature's "no trace anywhere" requirement.
+ */
+export interface MessageRecallPayload {
+  /**
+   * The server's deterministic slot id, `rcl:<target_message_id>`. Present so
+   * the marker can occupy one durable inbox row per recalled message. It is
+   * NOT the id to delete.
+   */
+  message_id: string;
+
+  /** The id of the message being erased. This is the one to delete by. */
+  target_message_id: string;
+}
+
+/**
+ * Pull the id to delete out of a `message.recall` payload.
+ *
+ * Exists as a pure function, apart from the socket, for the same reason the
+ * mistake it guards is worth guarding: `payload.message_id` is right there and
+ * looks like the answer, but it is the `rcl:` slot. Deleting by it removes
+ * nothing and reads exactly like working code.
+ *
+ * Answers `null` for anything unusable, so a recall we cannot resolve deletes
+ * nothing rather than something adjacent.
+ */
+export function recallTargetMessageId(payload: unknown): string | null {
+  if (!payload || typeof payload !== "object") return null;
+  const target = (payload as { target_message_id?: unknown }).target_message_id;
+  return typeof target === "string" && target.length > 0 ? target : null;
+}

package/src/reply-dispatcher.ts

@@ -17,7 +17,11 @@ import {
   effectiveOutputVisibility,
   type ResolvedOpenclawClawlingAccount,
 } from "./config.ts";
-import { uploadOutboundMedia, type ClawlingMediaFragment } from "./media-runtime.ts";
+import {
+  describeOutboundMediaShortfall,
+  uploadOutboundMedia,
+  type ClawlingMediaFragment,
+} from "./media-runtime.ts";
 import {
   mintMessageId,
   sendOpenclawClawlingText,
@@ -439,17 +443,19 @@ export function createOpenclawClawlingReplyDispatcher(options: ReplyDispatcherOp
       );
       return [];
     }
-    const fragments = await uploadOutboundMedia(urls, { apiClient, runtime, log });
-    if (fragments.length < urls.length) {
-      // uploadOutboundMedia drops a failed item with only a log line. A shortfall
-      // means an attachment never reached the media service; surfacing it (parity
-      // with the adapter path in outbound.ts and with the Hermes plugin) stops a
-      // text-only frame from going out and reading as a successful send.
-      throw new Error(
-        `clawchat-plugin-openclaw failed to upload ${urls.length - fragments.length}/${urls.length} outbound media attachment(s); message not sent`,
-      );
+    const result = await uploadOutboundMedia(urls, { apiClient, runtime, log });
+    if (result.fragments.length < urls.length) {
+      // uploadOutboundMedia never aborts the batch: every URL is attempted and
+      // the successful fragments still come back. A shortfall — partial success
+      // or total failure alike — means at least one attachment never reached
+      // the media service, so the whole send is rejected (parity with the
+      // adapter path in outbound.ts and with the Hermes plugin) rather than
+      // letting a text-only frame go out reading as a successful send. The
+      // thrown message carries each failure's structured, redacted diagnostics
+      // so the agent is not left with a reasonless generic error.
+      throw new Error(describeOutboundMediaShortfall(result, urls.length));
     }
-    return fragments;
+    return result.fragments;
   }
 
   // ----- Reply state ------------------------------------------------------

package/src/runtime.ts

@@ -5,6 +5,7 @@ import {
   StateError,
   TransportError,
   EVENT,
+  recallTargetMessageId,
   type Envelope,
   type Transport,
 } from "./protocol-types.ts";
@@ -52,7 +53,7 @@ import {
   resolveManagedSkillsDir,
   runSkillUpdateCheck,
 } from "./skill-update.ts";
-import { fetchInboundMedia } from "./media-runtime.ts";
+import { CLAWCHAT_MEDIA_MAX_BYTES, fetchInboundMedia } from "./media-runtime.ts";
 import { createOpenclawClawlingReplyDispatcher } from "./reply-dispatcher.ts";
 import { runWithTerminalClawChatSendScope } from "./terminal-send.ts";
 import {
@@ -123,6 +124,7 @@ type RuntimeConnectionStore = Pick<
       | "getActivationConversation"
       | "getLastResolvedDeviceId"
       | "listRecentGroupMessages"
+      | "deleteMessagesByMessageId"
       | "upsertOwnerProfile"
     >
   >;
@@ -2907,7 +2909,7 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
         ? await fetchInboundMedia(turn.mediaItems, {
             runtime,
             log,
-            maxBytes: 20 * 1024 * 1024,
+            maxBytes: CLAWCHAT_MEDIA_MAX_BYTES,
           })
         : [];
     if (inboundPaths.length > 0) {
@@ -3447,6 +3449,38 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
     })();
   });
 
+  // `message.recall` — the sender withdrew a message. Erase our own ledger row
+  // so the "Prior group context" block above (MENTION_CONTEXT_N rows, no time
+  // predicate, no retention) can never read it back into a turn.
+  //
+  // Ids only: the frame carries no content, and `payload.message_id` is the
+  // server's `rcl:<target>` slot — the id to delete is `target_message_id`.
+  //
+  // Synchronous and fire-and-forget on purpose. There is no ack to send (the
+  // frame is BestEffort and non-ackable), and no tombstone to write: a Kafka
+  // redelivery of the original can resurrect the row, which is an accepted
+  // known limitation rather than a fourth reimplementation of the mobile
+  // client's tombstone table.
+  client.on("message:recall", (env: Envelope) => {
+    const target = recallTargetMessageId(env.payload);
+    if (!target) {
+      log?.info?.(
+        `[${accountId}] clawchat-plugin-openclaw recall ignored (no target_message_id) chat_id=${String(env.chat_id ?? "")}`,
+      );
+      return;
+    }
+    const removed = store?.deleteMessagesByMessageId?.({
+      platform: "openclaw",
+      accountId,
+      messageId: target,
+    });
+    const rowsLabel = typeof removed === "number" ? String(removed) : "unavailable";
+    const logFn = typeof removed === "number" ? log?.info : log?.error;
+    logFn?.(
+      `[${accountId}] clawchat-plugin-openclaw recall purged chat_id=${String(env.chat_id ?? "")} msg=${target} rows=${rowsLabel}`,
+    );
+  });
+
   // Initial pull of per-group agent settings at startup (best-effort; errors are
   // logged). `bypassRefresh: true` (Finding 4) keeps this pre-connect pull from
   // rotating `account.token` out from under the already-constructed WS client.

package/src/storage.ts

@@ -802,6 +802,44 @@ export class ClawChatStore {
     });
   }
 
+  /**
+   * Erase every ledger row for one `message_id` — the local half of a
+   * server-authorised recall (`message.recall`, docs/client-integration.md §9.8).
+   *
+   * **The only DELETE in this store, and deliberately so.** There is no prune
+   * and no retention on `clawchat_messages`: without this, a message recalled
+   * ninety seconds after it was sent stays one @-mention away from being read
+   * back aloud under "Prior group context" for as long as the group is quiet.
+   *
+   * Scoped to `(platform, account_id)` so one account's recall cannot reach
+   * another's rows, and matched on `message_id`, which seeks via the
+   * single-column `idx_clawchat_messages_message_id` before the `platform` /
+   * `account_id` filter is applied — so this is a lookup, not a table scan.
+   *
+   * Answers the number of rows removed. `0` is a normal outcome, not a failure:
+   * the row may never have been stored (a message that arrived before this
+   * account was paired, or one dropped by the inbound filter). `null` means the
+   * store is unavailable.
+   */
+  deleteMessagesByMessageId(input: {
+    platform: string;
+    accountId: string;
+    messageId: string;
+  }): number | null {
+    // An empty id would match every row whose message_id is '' — deleting
+    // everything the store never managed to key. Refuse rather than guess.
+    if (!input.messageId) return 0;
+    return this.write(() => {
+      const result = this.requireDb()
+        .prepare(
+          `DELETE FROM clawchat_messages
+            WHERE platform = ? AND account_id = ? AND message_id = ?`,
+        )
+        .run(input.platform, input.accountId, input.messageId);
+      return Number(result.changes);
+    });
+  }
+
   startConnection(input: StartConnectionInput): number | null {
     return this.write(() => {
       const now = input.connectStartedAt ?? Date.now();

package/src/ws-client.ts

@@ -651,6 +651,10 @@ export class ClawChatClient extends EventEmitter {
     if (env.event === EVENT.MESSAGE_ACK) return this.onAck(env as Envelope<MessageAckPayload>);
     if (env.event === EVENT.MESSAGE_ERROR) return this.onMessageError(env as Envelope<MessageErrorPayload>);
     if (isBusinessDispatchEvent(env.event)) this.emit("message", env);
+    // Deliberately NOT a business dispatch event: `message` feeds the turn
+    // pipeline, and a recall has no body to turn into a prompt. It is an
+    // instruction to delete, so it gets its own emitter and its own consumer.
+    if (env.event === EVENT.MESSAGE_RECALL) this.emit("message:recall", env);
     if (env.event === EVENT.MESSAGE_CREATED) this.emit("message:created", env);
     if (env.event === EVENT.MESSAGE_ADD) this.emit("message:add", env);
     if (env.event === EVENT.MESSAGE_DONE) this.emit("message:done", env);

package/dist/src/friend-request-turn.js

@@ -1,83 +0,0 @@
-/**
- * Synthetic reasoning-turn builder for `friend.request` notify.signal events.
- *
- * When the server fires a `friend.request` signal the runtime dispatches one
- * deduped synthetic `message.send` envelope so the agent can reason about the
- * pending request. The prompt text varies by the current "friend.add" permission
- * policy state: a deny policy yields a decline/inform prompt; ask or allow
- * yields a prompt that instructs the agent to review the request via the
- * `clawchat_list_friend_requests` tool.
- */
-import { EVENT } from "./protocol-types.js";
-/**
- * Returns canned prompt text for a friend-request reasoning turn based on the
- * current "friend.add" permission policy state.
- *
- * - `deny`  → inform the agent it should decline; no accept instruction.
- * - `ask` / `allow` → instruct the agent to review the pending request.
- *
- * The requester's user id is embedded so the agent does not go looking up the
- * synthetic sender ("clawchat-friend-request" is not a real user).
- */
-export function friendRequestPromptFor(state, requesterUserId) {
-    const arrived = requesterUserId
-        ? `A new friend request has arrived from user ${requesterUserId}.`
-        : "A new friend request has arrived.";
-    if (state === "deny") {
-        return [
-            arrived,
-            "Your current friend-add policy is set to deny.",
-            "Do not add this contact.",
-            "You may inform the requester that you cannot add them at this time.",
-        ].join(" ");
-    }
-    return [
-        arrived,
-        "Please review the pending request by calling `clawchat_list_friend_requests`",
-        "and decide whether to accept it.",
-    ].join(" ");
-}
-/**
- * Builds a synthetic `message.send` envelope that triggers one agent reasoning
- * turn for a pending friend request. The envelope shape mirrors the
- * activation-bootstrap envelope; it targets the owner's direct conversation so
- * the agent has context about who it is reasoning for.
- */
-export function buildFriendRequestEnvelope(params) {
-    const { account, state, entityId, ownerConversationId } = params;
-    const text = friendRequestPromptFor(state, entityId);
-    const now = Date.now();
-    // Fall back to ownerUserId only when no activation conversation is recorded:
-    // the turn still runs (the agent can act via tools, e.g. accept the request),
-    // but its in-chat replies will not be deliverable until activation records
-    // the owner conversation.
-    return {
-        version: "2",
-        event: EVENT.MESSAGE_SEND,
-        trace_id: `clawchat-plugin-openclaw-friend-request-${entityId}-${now}`,
-        emitted_at: now,
-        chat_id: ownerConversationId ?? account.ownerUserId,
-        chat_type: "direct",
-        to: { id: account.userId, type: "direct" },
-        sender: {
-            id: "clawchat-friend-request",
-            type: "direct",
-            nick_name: "ClawChat",
-        },
-        payload: {
-            message_id: `clawchat-plugin-openclaw-friend-request-${entityId}-${now}`,
-            message_mode: "normal",
-            message: {
-                body: { fragments: [{ kind: "text", text }] },
-                context: { mentions: [], reply: null },
-                streaming: {
-                    status: "static",
-                    sequence: 0,
-                    mutation_policy: "sealed",
-                    started_at: null,
-                    completed_at: null,
-                },
-            },
-        },
-    };
-}