@agent-wechat/agent-wechat 1.0.0-beta.5 → 1.0.0-beta.6

package/README.md

@@ -16,7 +16,7 @@ Configure plugin defaults under `plugins.entries.agent-wechat.config` (or the sa
     "endpoint": "http://127.0.0.1:6174",
     "token": { "source": "env", "provider": "default", "id": "AGENT_WECHAT_TOKEN" },
     "consumerStateDir": "/private/openclaw-native-consumer",
-    "readPolicy": "on_model_dispatch"
+    "readPolicy": "on_inbound"
   }
 }
 ```
@@ -50,15 +50,90 @@ Keep `dataDir` and `consumerStateDir` on separate explicit persistent mounts. Th
 
 The adapter consumes account-scoped SSE using bearer headers and decimal-string journal cursors. It persists custody before acknowledging a cursor; acknowledgement is independent of unread state. Only explicitly live, incoming, committed resources can enter the model. Supported images, short voice, video, files and eligible stickers pass through bounded media retrieval and hash verification into OpenClaw-managed storage. Pending media retains custody without model dispatch or a read receipt. Expired/unsupported attachments retain an explicit status; raw XML never becomes an attachment. Catch-up/import/raw pending sync batches, unknown origin and outgoing messages do not become automatic model inputs. Group admission uses structured exact self-mention facts; unknown metadata or displayed `@names` never satisfy a mention gate. Contacts and groups use their separate catalogs.
 
-The prepared-run callback records the selected model input before marking its whole thread read. This also clears earlier unread messages in that thread, including messages the model did not receive. The daemon freezes the latest local message boundary, checks the expected version, updates local unread state and submits one native cross-device notification. A lost notification response remains `needs_review` and is never automatically resubmitted. `readPolicy: "never"` disables both local and cross-device marking. Crashes during an unconfirmed dispatch retain `needs_review`; the plugin does not automatically duplicate model turns or uncertain outgoing sends.
+Every ready attachment supplies its original OpenClaw-managed path in the message body and `Attachments` metadata, including images. File references wrap paths in angle brackets, such as `[Image file: <path>]` or `[Local file: <path>]`, so OpenClaw does not automatically load an original or a file with an image extension when scanning prompt text. A separately prepared image preview may occupy `MediaPath` while the original file remains accessible by its own path. Files, voice and video retain explicit local references; an available path does not claim that the model analyzed the file.
 
-OpenClaw **2026.10.2** lacks `onPreparedAgentRunStart`, so its released public hooks provide a bounded compatibility path. Before dispatch, the adapter persists an immutable manifest binding the exact new message ID/version/content hash, policy hash, source and supplied asset hashes, and context roles. Text requires the exact current input and host-created message/account/session facts plus a matching `model_call_started`. Media additionally waits for the same run's `agent_end` snapshot and source-turn identity. Image bytes/MIME/length must match the frozen supplied representation; file/video/voice references must appear in the exact current body. Image count, model selection and reply delivery alone cannot mark a message read. Unknown, omitted, rewritten, merged or ambiguous inputs remain unconfirmed.
+In groups requiring a mention, sender-admitted unmentioned messages are retained as context without retrieval, transcription, a model turn or a read notification. The next admitted non-command message includes that context after checking the current sender policy again. `messages.groupChat.historyLimit` controls the per-group window (default 50, maximum 200; zero disables it). The consumer store retains at most 1,000 buffered group messages overall. Context survives a Gateway restart. At dispatch, the selected context is consumed atomically with the durable turn record, so an uncertain turn is not offered again automatically. Original mention facts remain unchanged; history is recorded separately from the triggering message.
 
-The compatibility path requires the operator's explicit host permission, `plugins.entries.agent-wechat.hooks.allowConversationAccess: true`. It observes only run IDs issued by this adapter and never enables that permission itself. Without the grant, or on an unsupported host, messages remain unread and status reports `handoffUnconfirmed`. The older `onAgentRunStart` also reports direct tools and early lifecycle phases and is never used as proof. `readPolicy: "never"` preserves the handoff receipt while disabling read projection. Late confirmed receipts can mark their thread independently of new SSE traffic. Access and mention gates still precede model dispatch; a rejected message does not itself trigger a read.
+Group catch-up retrieves media with at most three workers, keeps every verified original path and selects only the latest ready image's prepared representation for vision. Pending or unavailable historical attachments remain explicit statuses and do not block the current mention. The triggering attachment, when still pending, continues to hold its own dispatch. Voice transcription runs only after admission and activation. Commands do not drain buffered context.
 
-Images exceeding the host's bounded representation, or formats requiring conversion, receive a separately stored JPEG still preview using the public SDK image processor. The original stays intact; both hashes are recorded and the model input labels the preview. Prepared images fit within 5 MiB and at most 1200 pixels per side (or a smaller configured limit). Files and videos can be supplied as available local references; this does not claim their contents were analyzed. Voice retains its verified file and includes configured transcription output or an explicit unavailable status. Pending, expired, unsupported and failed-integrity media never gains a read receipt from a placeholder.
+By default, `readPolicy: "on_inbound"` marks a whole thread read after its incoming message has been durably stored, passed sender/group/mention checks and completed normal OpenClaw inbound handling. Built-in commands also qualify when no model is called. This policy does not inspect model inputs or require `hooks.allowConversationAccess`. Ignored messages, pending media and failed handling do not initiate a read. Read means handled by the integration; it does not claim that a model analyzed an attachment.
 
-Run `node scripts/native-model-smoke.mjs` and `node scripts/native-media-model-smoke.mjs` after installing workspace dependencies. They use the actual pinned Gateway, a local model and synthetic daemon/files. Checks cover current provider input, image hashes and prepared previews, reference/transcription delivery, whole-thread read requests, lost-response/reopen recovery, duplicate prevention, omitted images on a text-only model, permission, never-read policy and group routing behavior. Transcription uses the real SDK with an explicitly configured local deterministic CLI; it does not test speech recognition accuracy. Concurrent text inputs were serialized into distinct model turns; merged-input refusal has unit coverage. These checks establish the prepared runtime boundary, not external provider acceptance, semantic analysis or consumption.
+A whole-thread read also clears earlier unread messages in that thread, including messages the model did not receive. The daemon freezes the latest local message boundary, checks the expected version, updates local unread state and submits one native read-status notification. Server acceptance alone does not prove that a phone badge changed. A lost notification response remains `needs_review` and is never automatically resubmitted. Pending reads survive a Gateway restart and retry independently of model execution or new SSE traffic. `readPolicy: "never"` disables both local and remote marking, including previously queued reads. Crashes during an unfinished dispatch retain `needs_review`; the plugin does not automatically duplicate model turns or uncertain outgoing sends.
+
+The optional `readPolicy: "on_model_dispatch"` instead requires a confirmed model handoff. OpenClaw **2026.10.2** lacks `onPreparedAgentRunStart`, so its released public hooks provide a bounded compatibility path. Before dispatch, the adapter persists an immutable manifest binding the exact new message ID/version/content hash, policy hash, source and supplied asset hashes, and context roles. Text requires the exact current input and host-created message/account/session facts plus a matching `model_call_started`. Media additionally waits for the same run's `agent_end` snapshot and source-turn identity. Image bytes/MIME/length must match the frozen supplied representation; file/video/voice references must appear in the exact current body. Image count, model selection and reply delivery alone cannot confirm a model handoff. Unknown, omitted, rewritten, merged or ambiguous inputs remain unconfirmed. Host/provider history formats can prevent confirmation even when a reply was delivered; use `on_inbound` for ordinary bot read behavior.
+
+The model-handoff compatibility path requires the operator's explicit host permission, `plugins.entries.agent-wechat.hooks.allowConversationAccess: true`. It observes only run IDs issued by this adapter and never enables that permission itself. Without the grant, or on an unsupported host, the explicit `on_model_dispatch` policy leaves messages unread and status reports `handoffUnconfirmed`. The older `onAgentRunStart` also reports direct tools and early lifecycle phases and is never used as proof. Access and mention gates still precede model dispatch; a rejected message does not itself trigger a read.
+
+Images exceeding the host's bounded representation, or formats requiring conversion, receive a separately stored JPEG still preview using the public SDK image processor. The original stays intact; both hashes are recorded and the model input labels the preview. Prepared images fit within 5 MiB and at most 1200 pixels per side (or a smaller configured limit). Files and videos can be supplied as available local references; this does not claim their contents were analyzed. Voice retains its verified file and includes configured transcription output or an explicit unavailable status. A placeholder does not confirm a model handoff under `on_model_dispatch`; default `on_inbound` can mark a thread after successfully handling an explicit expired/unsupported status.
+
+## Stored-history tools
+
+The agent can look beyond the recent inbound buffer using the selected native account's local profile:
+
+| Tool | Inputs (`?` means optional) | Output |
+| --- | --- | --- |
+| `wechat_history` | `{ limit?, cursor? }` | Stored messages, newest first, with `nextCursor`, `sourceGeneration` and `coverage` |
+| `wechat_search` | `{ query, limit?, cursor? }` | Same page shape, filtered by case-insensitive substring |
+| `wechat_message` | `{ messageId }` | One stored message |
+| `wechat_media` | `{ messageId, download?, quality? }` | Media status, optional verified file path and image content |
+
+A stored message includes `id`, `threadId`, nullable `serverId`, `senderId`, `direction` and `createdAt`, numeric `type`, bounded `body`, and `bodyTruncated`. Its optional `attachment` descriptor contains `kind`, `messageId` and `retrievalTool: "wechat_media"`. Message IDs and server IDs remain strings; use the opaque `id` for exact lookup and media retrieval.
+
+A media result includes `messageId`, `threadId`, `status` and `retryable`, with optional `attachment`, actual `variant`, `jobId`, `reason` and display `body`. A ready attachment has `kind`, `filename`, verified local `path` and `mime`; image quality may be `full`, `standard` or `thumbnail`. Unavailable results never claim a local path. OpenClaw wraps structured outputs in `details` and text `content`; a ready image additionally supplies an image content block.
+
+For example, the agent can call `wechat_search` with `{"query":"project notes"}` in the current conversation. These four default tools are restricted to the current WeChat account and thread derived from trusted OpenClaw context. Owners and agents with archive access have the same restriction when invoking a default tool. Default tools accept no thread/account selector, and the plugin rejects messages or assets from another conversation or account. Requester and historical sender policy are rechecked. Missing or conflicting trusted conversation context hides the default tools; webchat and other channels cannot use them.
+
+History/search return opaque string message IDs, a bounded text preview, coverage metadata and `nextCursor`. Pass the cursor back with the same tool, query and thread to continue; the page limit is 1–50 (default 20). Search queries are limited to 256 UTF-8 bytes. Long message bodies are labeled as truncated. A sender-filtered page may be empty and still have a continuation. Search covers locally stored history and does not fetch missing remote history or maintain an official FTS index. Media messages receive a type/status description; these tools do not return raw transport XML or download attachments. History, search and exact-message lookup are read-only. Their attachment descriptions name `wechat_media` and the exact message ID without automatically retrieving media. None of these tools mark a conversation read, send messages or modify the inbound consumer cursor. Lookup requires the selected account's API `read` scope and remains subject to normal OpenClaw tool policy. With OpenClaw's compact tool catalog, the agent discovers history/search/message lookup through `tool_search` and invokes the returned tool with `tool_call`. The media tool stays directly callable as `wechat_media`: the pinned host's generic wrapper serializes nested image blocks as JSON text, while direct invocation preserves image content for vision.
+
+`wechat_media` accepts `{"messageId":"<returned opaque ID>"}`. It verifies message/thread/sender admission before accessing assets, uses cached bytes first, checks identity, hash and size, and saves verified bytes to OpenClaw's managed media store. Files, videos and voice return local paths; images also return a bounded prepared preview as image content for vision. This retrieval does not itself transcribe voice or analyze files/videos. Cached bytes remain usable after CDN expiry.
+
+Missing media requests a durable daemon transfer by default, with a two-second bounded wait. A pending result includes its `jobId` when known and no claimed local path; call the same tool with the same message ID later to check. The daemon owns and deduplicates the transfer, so cancelling a tool invocation does not cancel submitted work. Use `download: false` for cached media only. `quality` defaults to `best` (best cached image, normal video or decoded voice); explicit `original`, `standard`, `thumbnail`, `normal` and `encoded` variants are strict and may be unavailable. Results report the actual variant and explicit pending, expired, unsupported, unavailable or too-large status. Never automatically retry `retryable: false` or confirmed expiry. The media tool requires account-scoped API `read` and `media` permission, including for download requests. Raw XML, signed transport URLs and keys are never returned.
+
+`node scripts/native-history-model-smoke.mjs` exercises the pinned Gateway with local account/media/model fixtures: durable group context, original file paths, one preview with a verified hash, a PNG sent as a file remaining a reference, direct image delivery, actual tool discovery, two paginated search calls, rejection of another thread's attachment before media access, one requested image download whose exact image bytes reach vision, and a cached file path reaching the provider. CI runs this check on both Linux architectures.
+
+When asset metadata identifies an existing download job, retrieval polls that scoped job instead of submitting another transfer. A terminal job's reason and retryability are preserved, including in cache-only mode; this tool does not automatically retry failed jobs. A service rejection alone is not classified as expiry.
+
+### Privileged archive tools
+
+Five optional tools read across every thread in the configured native WeChat account:
+
+| Tool | Inputs (`?` means optional) | Output |
+| --- | --- | --- |
+| `wechat_archive_threads` | `{ query?, limit?, cursor? }` | Thread page: `id`, `peerId`, `kind`, `displayName`, `unreadCount`, plus pagination and coverage |
+| `wechat_archive_search` | `{ query, threadId?, limit?, cursor? }` | Message page across all threads; optional `threadId` narrows it |
+| `wechat_archive_history` | `{ threadId, limit?, cursor? }` | Message page for any selected thread, newest first |
+| `wechat_archive_message` | `{ messageId }` | One message from any thread |
+| `wechat_archive_media` | `{ messageId, download?, quality? }` | Verified attachment status/path and image content from any thread |
+
+Message/page/media output shapes, bounds and download behavior match the default tools above. Archive attachment descriptors name `wechat_archive_media` as their retrieval tool. Thread queries match locally stored IDs and display names. Search uses the daemon's account-wide `GET /v1/accounts/{accountId}/messages?query=...` endpoint; its opaque cursor binds the account, query and thread selection and retains membership/order across local edits, deletions and new arrivals. Search reads the local profile with bounded snapshot capacity; it does not backfill remote history. An older daemon without that endpoint must be upgraded for account-wide search.
+
+Configure access in OpenClaw's `~/.openclaw/openclaw.json`, merging into your existing named agent entries:
+
+```json
+{
+  "agents": {
+    "ownership": "explicit",
+    "entries": {
+      "main": {
+        "tools": { "alsoAllow": ["wechat_archive_*"] }
+      },
+      "group-bot": {
+        "tools": { "deny": ["wechat_archive_*"] }
+      }
+    }
+  }
+}
+```
+
+OpenClaw enforces these policies for tool execution and catalog discovery. The `main` name has no implicit privilege. Use individual tool names to grant a subset. If an agent already has `tools.allow`, add the archive names to that list instead of combining `allow` and `alsoAllow`. A global deny still wins over a per-agent allow. Optional tools are absent without a selecting policy, but `profile: "full"`, `*`, `group:plugins`, or an allow for the entire `agent-wechat` plugin also selects them; add an explicit per-agent deny for agents that should retain only current-thread access.
+
+There is no plugin permission list, owner exception or archive sender/thread filter. A host-authorized archive invocation can read the configured account from any channel, including a group invocation. Use OpenClaw's sender policies or route group traffic to an agent without archive tools when those runs should have narrower access. Archive tools stay bound to the configured account and verify message/asset identities, hashes and sizes. They never accept arbitrary file paths or another account selector. Normal account/token scope checks and invocation cancellation fences still apply.
+
+History/search/message/thread reads never send messages, mark threads read or change the inbound cursor. Archive media can submit the same bounded, deduplicated download jobs as `wechat_media`; it stays directly callable so actual image blocks reach vision.
+
+Run `node scripts/native-archive-tools-smoke.mjs` to check the pinned Gateway with three separately routed agents: no optional-tool grant, a full profile with an explicit deny, and an archive grant. It checks discovery and guessed-name invocation denial, cross-thread search pagination, other-sender history/media, unchanged default-tool scope, verified image bytes in provider input and a cached file path. All messages, account data and model responses in this test are synthetic. CI runs it on Linux x64 and ARM64.
+
+Run `node scripts/native-model-smoke.mjs` and `node scripts/native-media-model-smoke.mjs` after installing workspace dependencies. They use the actual pinned Gateway, a local model and synthetic daemon/files. Checks cover default inbound reads without conversation permission, commands without a model call, current provider input, image hashes and prepared previews, reference/transcription delivery, whole-thread read requests, lost-response/reopen recovery, duplicate prevention, omitted images on a text-only model, explicit model-handoff permission, never-read policy and group routing behavior. Transcription uses the real SDK with an explicitly configured local deterministic CLI; it does not test speech recognition accuracy. Concurrent text inputs were serialized into distinct model turns; merged-input refusal has unit coverage for the explicit model policy. These checks establish local runtime behavior, not external provider acceptance, semantic analysis or consumption.
 
 Native text/media sends retain daemon intent/job identity and caller idempotency. Text waits for accepted submission; media jobs preserve partial and uncertain outcomes rather than resending. Ordinary audio remains a file; only explicit `audioAsVoice` requests independently encoded voice. Sender/group/mention gates run before retrieval/transcription. Verified voice may use the configured OpenClaw transcription runtime after admission. Native QR login uses a durable daemon operation and authenticated PNG retrieval. Logout commits local inhibition before at most one authenticated native logout, reporting the remote outcome separately; saved-device revocation remains unverified. Explicitly confirmed forgetting removes local auth while retaining history; disconnect retains reusable trust.
 

package/dist/index.js

@@ -322,8 +322,8 @@ var NativeWeChatClient = class {
   groups(accountId, options) {
     return this.request(`v1/accounts/${id(accountId)}/groups${listQuery(options)}`);
   }
-  thread(accountId, threadId) {
-    return this.request(`v1/accounts/${id(accountId)}/threads/${id(threadId)}`);
+  thread(accountId, threadId2) {
+    return this.request(`v1/accounts/${id(accountId)}/threads/${id(threadId2)}`);
   }
   contact(accountId, username) {
     return this.request(`v1/accounts/${id(accountId)}/contacts/${id(username)}`);
@@ -361,12 +361,12 @@ var NativeWeChatClient = class {
   syncGroups(accountId) {
     return this.request(`v1/accounts/${id(accountId)}/group-sync`, { method: "POST", body: "{}" });
   }
-  async messages(accountId, threadId, options) {
-    const result = await this.request(`v1/accounts/${id(accountId)}/threads/${id(threadId)}/messages${listQuery(options)}`);
+  async messages(accountId, threadId2, options) {
+    const result = await this.request(`v1/accounts/${id(accountId)}/threads/${id(threadId2)}/messages${listQuery(options)}`);
     for (const msg of result.items) {
       if (isNativeTombstone(msg))
         continue;
-      if (typeof msg.id !== "string" || msg.accountId !== accountId || msg.threadId !== threadId || msg.serverId != null && (typeof msg.serverId !== "string" || !/^\d+$/.test(msg.serverId)))
+      if (typeof msg.id !== "string" || msg.accountId !== accountId || msg.threadId !== threadId2 || msg.serverId != null && (typeof msg.serverId !== "string" || !/^\d+$/.test(msg.serverId)))
         throw new Error("Invalid native message identity");
     }
     return result;
@@ -377,10 +377,21 @@ var NativeWeChatClient = class {
       throw new Error("Invalid native message identity");
     return message;
   }
-  sendText(accountId, threadId, text, idempotencyKey) {
+  /** Account-wide local search, with the daemon's query-bound opaque cursor. */
+  async searchMessages(accountId, options) {
+    const result = await this.request(`v1/accounts/${id(accountId)}/messages${listQuery(options)}`);
+    for (const message of result.items) {
+      if (isNativeTombstone(message))
+        continue;
+      if (typeof message.id !== "string" || message.accountId !== accountId || typeof message.threadId !== "string" || !message.threadId || message.serverId != null && (typeof message.serverId !== "string" || !/^\d+$/.test(message.serverId)))
+        throw new Error("Invalid native archive message identity");
+    }
+    return result;
+  }
+  sendText(accountId, threadId2, text, idempotencyKey) {
     if (!idempotencyKey || /[\r\n]/.test(idempotencyKey))
       throw new Error("An idempotency key is required");
-    return this.request(`v1/accounts/${id(accountId)}/sends`, { method: "POST", headers: { "Idempotency-Key": idempotencyKey }, body: JSON.stringify({ threadId, text }) });
+    return this.request(`v1/accounts/${id(accountId)}/sends`, { method: "POST", headers: { "Idempotency-Key": idempotencyKey }, body: JSON.stringify({ threadId: threadId2, text }) });
   }
   send(accountId, sendId, signal) {
     return this.request(`v1/accounts/${id(accountId)}/sends/${id(sendId)}`, { signal });
@@ -440,10 +451,10 @@ var NativeWeChatClient = class {
     }
     return { bytes: await this.readBounded(response, max), contentType: response.headers.get("content-type") ?? "application/octet-stream", etag: response.headers.get("etag"), contentRange: response.headers.get("content-range"), status: response.status };
   }
-  markRead(accountId, threadId, expectedVersion) {
+  markRead(accountId, threadId2, expectedVersion) {
     if (typeof expectedVersion !== "string" || !expectedVersion || expectedVersion.length > 128)
       throw new Error("Read version is required");
-    return this.request(`v1/accounts/${id(accountId)}/threads/${id(threadId)}/read-state`, { method: "POST", body: JSON.stringify({ expectedVersion }) });
+    return this.request(`v1/accounts/${id(accountId)}/threads/${id(threadId2)}/read-state`, { method: "POST", body: JSON.stringify({ expectedVersion }) });
   }
   events(accountId, after = "0", limit = 100) {
     if (!Number.isInteger(limit) || limit < 1 || limit > 200)
@@ -1024,17 +1035,18 @@ function renderAttachmentBody(originalBody, attachment, exposeNonVisualPath = tr
   if (attachment.kind === "file") {
     const prefix = originalBody.trim() === name ? "" : originalBody;
     return appendReference(prefix, `[File: ${name}]
-[Local file: ${attachment.path}]`);
+[Local file: <${attachment.path}>]`);
   }
   if (exposeNonVisualPath) {
     if (attachment.kind === "audio") {
-      return appendReference(originalBody || "<media:audio>", `[Voice message file: ${attachment.path}]`);
+      return appendReference(originalBody || "<media:audio>", `[Voice message file: <${attachment.path}>]`);
     }
     if (attachment.kind === "video") {
-      return appendReference(originalBody || "<media:video>", `[Video file: ${attachment.path}]`);
+      return appendReference(originalBody || "<media:video>", `[Video file: <${attachment.path}>]`);
     }
   }
-  const body = originalBody || (attachment.kind === "image" ? "<media:image>" : originalBody);
+  let body = originalBody || (attachment.kind === "image" ? "<media:image>" : originalBody);
+  if (attachment.kind === "image") body = appendReference(body, `[Image file: <${attachment.path}>]`);
   if (attachment.kind === "image" && attachment.quality === "thumbnail") {
     return appendReference(body, "[Image preview only: thumbnail quality]");
   }
@@ -1046,26 +1058,30 @@ function kind(type) {
   return type === 3 || type === 47 ? "image" : type === 34 ? "audio" : type === 43 ? "video" : type === 49 ? "file" : void 0;
 }
 var terminalJobs = /* @__PURE__ */ new Set(["accepted", "completed", "succeeded", "available", "failed", "cancelled", "expired", "needs_review"]);
-async function waitNativeMediaJob(client, accountId, initial, timeoutMs = 65e3) {
+async function waitNativeMediaJob(client, accountId, initial, timeoutMs = 65e3, signal, assertCurrent) {
   const deadline = Date.now() + timeoutMs;
   let job = initial;
   let delay = 250;
   while (!terminalJobs.has(job.state) && Date.now() < deadline) {
+    signal?.throwIfAborted();
+    assertCurrent?.();
     await new Promise((resolve) => setTimeout(resolve, Math.min(delay, Math.max(0, deadline - Date.now()))));
     const remaining = deadline - Date.now();
     if (remaining <= 0) break;
-    job = await client.job(accountId, job.id, AbortSignal.timeout(remaining));
+    signal?.throwIfAborted();
+    assertCurrent?.();
+    job = await client.job(accountId, job.id, signal ? AbortSignal.any([signal, AbortSignal.timeout(remaining)]) : AbortSignal.timeout(remaining));
     delay = Math.min(delay * 2, 1e3);
   }
   return job;
 }
-function select(assets, type) {
+function select(assets, type, quality = "best") {
   const preferred = type === 34 ? ["normal"] : type === 43 ? ["normal", "original"] : ["original", "standard", "thumbnail", "encoded"];
   const rank = (asset) => {
     const index = preferred.indexOf(asset.actualVariant ?? asset.variant);
     return index < 0 ? preferred.length : index;
   };
-  return [...assets].sort((a, b) => rank(a) - rank(b)).find((asset) => asset.state === "available" && (type !== 34 || (asset.actualVariant ?? asset.variant) === "normal"));
+  return [...assets].sort((a, b) => rank(a) - rank(b)).find((asset) => asset.state === "available" && (quality === "best" ? type !== 34 || (asset.actualVariant ?? asset.variant) === "normal" : (asset.actualVariant ?? asset.variant) === quality));
 }
 async function prepareImageRepresentation(bytes, mime, cfg) {
   const configured = cfg?.agents?.defaults?.imageMaxDimensionPx;
@@ -1082,42 +1098,93 @@ async function prepareImageRepresentation(bytes, mime, cfg) {
 async function prepareNativeAttachment(params) {
   const { client, account, message, core } = params;
   const attachmentKind = kind(message.type);
+  const guard = () => {
+    params.signal?.throwIfAborted();
+    params.assertCurrent?.();
+  };
+  guard();
+  const authorize = async () => {
+    guard();
+    await params.beforeMediaAccess?.();
+    guard();
+  };
   if (!attachmentKind) return { body: message.type === 1 ? message.body ?? "" : `[Unsupported WeChat message type ${message.type}]`, pending: false };
   const accountId = account.native.accountId;
   const maxBytes = Math.min(account.mediaMaxMb * 1024 * 1024, 128 * 1024 * 1024);
   const scopedAssets = async () => {
+    await authorize();
     const items = (await client.mediaAssets(accountId, message.id)).items;
+    guard();
     if (items.some((asset2) => asset2.accountId !== accountId || asset2.messageId !== message.id)) throw Error("Native attachment identity does not match its message");
     return items;
   };
+  const quality = params.quality ?? "best";
+  const transferQuality = quality === "best" && (message.type === 34 || message.type === 43) ? "normal" : quality;
   let assets = await scopedAssets();
-  let asset = select(assets, message.type);
-  if (!asset && !assets.some((value) => ["expired", "unsupported"].includes(value.state))) {
+  let asset = select(assets, message.type, quality);
+  const relevant = () => assets.filter((value) => transferQuality === "best" || value.variant === transferQuality);
+  const transferCandidate = () => {
+    const order = ["original", "normal", "standard", "thumbnail", "encoded"];
+    return [...relevant()].sort((a, b) => order.indexOf(a.variant) - order.indexOf(b.variant))[0];
+  };
+  const initialCandidate = transferCandidate();
+  if (!asset && initialCandidate?.byteLength != null && initialCandidate.byteLength > maxBytes) {
+    const attachment2 = { kind: attachmentKind, filename: basename(initialCandidate.filename ?? "attachment"), status: "too_large" };
+    return { body: renderAttachmentBody("", attachment2), attachment: attachment2, pending: false, retryable: false };
+  }
+  let job;
+  let transferError;
+  if (!asset && initialCandidate?.jobId) {
+    await authorize();
+    job = await client.job(accountId, initialCandidate.jobId, params.signal);
+    guard();
+    if (job.accountId !== accountId || job.kind !== "download" || job.assetId != null && job.assetId !== initialCandidate.id) throw Error("Native download job identity does not match its attachment");
+    assets = await scopedAssets();
+    asset = select(assets, message.type, quality);
+    if (!asset && ["queued", "running"].includes(job.state)) return { body: `[${attachmentKind} pending]`, pending: true, jobId: job.id, retryable: true };
+  }
+  if (!asset && !job && params.download !== false && !["expired", "unsupported"].includes(transferCandidate()?.state ?? "")) {
     try {
-      const job = await client.transferMedia(accountId, { messageId: message.id, assetId: null, quality: message.type === 34 || message.type === 43 ? "normal" : "best" });
-      const completed = await waitNativeMediaJob(client, accountId, job, params.waitMs ?? 2e4);
-      if (["queued", "running"].includes(completed.state)) return { body: `[${attachmentKind} pending]`, pending: true };
-      assets = await scopedAssets();
-      asset = select(assets, message.type);
-    } catch {
-      return { body: `[${attachmentKind} pending: retrieval is unavailable]`, pending: true };
+      await authorize();
+      job = await client.transferMedia(accountId, { messageId: message.id, assetId: null, quality: transferQuality });
+      guard();
+      job = await waitNativeMediaJob(client, accountId, job, params.waitMs ?? 2e4, params.signal, guard);
+      guard();
+    } catch (error) {
+      guard();
+      if (!(error instanceof NativeApiError) || error.retryable) return { body: `[${attachmentKind} pending: retrieval is unavailable]`, pending: true, jobId: job?.id, retryable: true };
+      transferError = error;
     }
+    assets = await scopedAssets();
+    asset = select(assets, message.type, quality);
+    if (!asset && job && ["queued", "running"].includes(job.state)) return { body: `[${attachmentKind} pending]`, pending: true, jobId: job.id, retryable: true };
   }
-  const filename = basename(asset?.filename ?? `message-${createHash4("sha256").update(message.id).digest("hex").slice(0, 12)}.bin`).replace(/[\r\n\0]/g, "_");
+  const candidate = transferCandidate();
+  const filename = basename(asset?.filename ?? candidate?.filename ?? `message-${createHash4("sha256").update(message.id).digest("hex").slice(0, 12)}.bin`).replace(/[\r\n\0]/g, "_");
   if (!asset) {
-    const state = assets.find((value) => value.state === "expired") ? "expired" : assets.find((value) => value.state === "unsupported") ? "unsupported" : "unavailable";
-    const attachment2 = { kind: attachmentKind, filename, status: state };
-    return { body: renderAttachmentBody("", attachment2), attachment: attachment2, pending: false };
+    const state = candidate?.state === "expired" ? "expired" : candidate?.state === "unsupported" ? "unsupported" : "unavailable";
+    const attachment2 = { kind: attachmentKind, filename, status: state, expiresAt: candidate?.expiresAt ?? void 0 };
+    return {
+      body: renderAttachmentBody("", attachment2),
+      attachment: attachment2,
+      pending: false,
+      jobId: job?.id,
+      retryable: state === "expired" || state === "unsupported" ? false : transferError ? false : job?.retryable ?? params.download === false,
+      reason: transferError?.code ?? (job?.reason && /^[a-z0-9_]{1,80}$/.test(job.reason) ? job.reason : void 0)
+    };
   }
   if (asset.byteLength != null && asset.byteLength > maxBytes) {
     const attachment2 = { kind: attachmentKind, filename, status: "too_large" };
     return { body: renderAttachmentBody("", attachment2), attachment: attachment2, pending: false };
   }
-  const content = await client.mediaContent(accountId, asset.id, { maxBytes });
+  await authorize();
+  const content = await client.mediaContent(accountId, asset.id, { maxBytes, signal: params.signal });
+  guard();
   const mime = content.contentType.split(";", 1)[0].trim().toLowerCase();
   if (!/^[a-z0-9.+-]+\/[a-z0-9.+-]+$/.test(mime)) throw Error("Native attachment MIME type is unsupported");
   const hash = createHash4("sha256").update(content.bytes).digest("hex");
   if (!asset.sha256 || hash !== asset.sha256 || asset.byteLength != null && asset.byteLength !== content.bytes.length) throw new Error("Native attachment integrity did not verify");
+  await authorize();
   const saved = await saveManagedAttachment({ data: Buffer.from(content.bytes).toString("base64"), mime, filename, maxBytes, saveMediaBuffer: core.channel.media.saveMediaBuffer });
   const actual = asset.actualVariant ?? asset.variant;
   const attachment = {
@@ -1148,9 +1215,13 @@ async function prepareNativeAttachment(params) {
 [Model image: prepared still preview; original retained separately]`;
     }
   }
+  guard();
   return {
     body,
     attachment,
+    jobId: job?.id,
+    retryable: false,
+    variant: actual,
     suppliedAssets: [{
       id: asset.id,
       sha256: suppliedHash,
@@ -1171,7 +1242,7 @@ async function prepareNativeAttachment(params) {
     pending: false
   };
 }
-async function sendNativeAttachment(client, account, threadId, mediaUrl, audioAsVoice = false, key = randomUUID()) {
+async function sendNativeAttachment(client, account, threadId2, mediaUrl, audioAsVoice = false, key = randomUUID()) {
   const max = Math.min(account.mediaMaxMb * 1024 * 1024, NATIVE_MAX_SOURCE_BYTES);
   let bytes;
   let filename;
@@ -1237,15 +1308,15 @@ async function sendNativeAttachment(client, account, threadId, mediaUrl, audioAs
   if (audioAsVoice && !mime.startsWith("audio/")) throw new Error("Voice sending requires an explicit audio attachment");
   const accountId = account.native.accountId;
   const source = await client.upload(accountId, bytes, filename, mime);
-  const input = { threadId, kind: audioAsVoice ? "voice" : mime.startsWith("image/") ? "image" : mime.startsWith("video/") ? "video" : "file", sourceId: source.id, standardSourceId: null, thumbnailSourceId: null, playSeconds: null, durationMs: null };
+  const input = { threadId: threadId2, kind: audioAsVoice ? "voice" : mime.startsWith("image/") ? "image" : mime.startsWith("video/") ? "video" : "file", sourceId: source.id, standardSourceId: null, thumbnailSourceId: null, playSeconds: null, durationMs: null };
   const job = await waitNativeMediaJob(client, accountId, await client.sendMedia(accountId, input, key), audioAsVoice ? 25 * 6e4 : 65e3);
   if (!["accepted", "completed", "succeeded"].includes(job.state)) throw new Error(`Native media job ${job.id} requires inspection (${job.state}); retain completed items and do not automatically resend`);
   return `agent-wechat-native:${accountId}:${job.id}`;
 }
 
 // src/native-send.ts
-async function submitNativeText(client, accountId, threadId, text, key, options = {}) {
-  let intent = await client.sendText(accountId, threadId, text, key);
+async function submitNativeText(client, accountId, threadId2, text, key, options = {}) {
+  let intent = await client.sendText(accountId, threadId2, text, key);
   const deadline = Date.now() + Math.max(1, Math.min(options.timeoutMs ?? 65e3, 65e3));
   let delay = Math.max(1, Math.min(options.initialDelayMs ?? 250, 1e3));
   while (["queued", "submitting"].includes(intent.state) && Date.now() < deadline) {
@@ -1298,6 +1369,8 @@ var NativeConsumerState = class {
       if (parsed.schemaVersion !== 1 || parsed.serverId !== serverId || parsed.accountId !== accountId || !/^\d+$/.test(parsed.cursor) || !parsed.items || typeof parsed.items !== "object") throw new Error("Native consumer identity or schema mismatch; state was preserved");
       for (const [id2, item] of Object.entries(parsed.items)) {
         if (item.message?.id !== id2 || item.message.accountId !== accountId || typeof item.message.threadId !== "string" || !["received", "dispatching", "handed_off", "completed", "ignored", "needs_review"].includes(item.state)) throw new Error("Invalid native custody record; state was preserved");
+        if (item.cursor != null && !/^\d+$/.test(item.cursor) || item.groupContext != null && typeof item.groupContext !== "boolean") throw new Error("Invalid native group context record; state was preserved");
+        if (item.groupContext && (!item.cursor || item.origin !== "live" || item.state !== "ignored" || item.message.direction !== "incoming" || !item.message.threadId.endsWith("@chatroom"))) throw new Error("Invalid native buffered group context; state was preserved");
         if (item.state === "dispatching") item.state = "needs_review";
       }
       this.value = parsed;
@@ -1358,10 +1431,10 @@ var NativeConsumerState = class {
     if (message && (!message.id || message.accountId !== this.value.accountId)) throw new Error("Native journal message crosses account boundary");
     this.mutate(() => {
       if (message && !this.value.items[message.id]) {
-        const completed = Object.entries(this.value.items).filter(([, item]) => !item.readPending && item.phoneReadState !== "needs_review" && item.phoneReadState !== "rejected" && ["completed", "ignored"].includes(item.state));
+        const completed = Object.entries(this.value.items).filter(([, item]) => !item.readPending && !item.groupContext && item.phoneReadState !== "needs_review" && item.phoneReadState !== "rejected" && ["completed", "ignored"].includes(item.state));
         for (const [key] of completed.slice(0, Math.max(0, completed.length - 1e3))) delete this.value.items[key];
         if (Object.keys(this.value.items).length >= 5e3) throw new Error("Native custody queue is full; operator review required");
-        this.value.items[message.id] = { message, origin, state: "received" };
+        this.value.items[message.id] = { message, origin, state: "received", cursor };
       }
       this.value.cursor = cursor;
     });
@@ -1371,6 +1444,30 @@ var NativeConsumerState = class {
     if (!item) throw new Error("Unknown native custody message");
     this.mutate(() => Object.assign(this.value.items[messageId], update));
   }
+  groupHistory(threadId2, beforeId, limit) {
+    const before = this.value.items[beforeId]?.cursor;
+    if (!before || limit <= 0) return [];
+    return this.items().filter((item) => item.groupContext && item.state === "ignored" && item.origin === "live" && item.message.threadId === threadId2 && item.cursor && BigInt(item.cursor) < BigInt(before)).sort((a, b) => BigInt(a.cursor) < BigInt(b.cursor) ? -1 : BigInt(a.cursor) > BigInt(b.cursor) ? 1 : 0).slice(-limit);
+  }
+  bufferGroupMessage(messageId, limit) {
+    const item = this.value.items[messageId];
+    if (!item || item.state !== "received" || item.origin !== "live" || item.message.direction !== "incoming" || !item.cursor || !item.message.threadId.endsWith("@chatroom") || !Number.isInteger(limit) || limit < 0 || limit > 200) throw new Error("Invalid native group history admission");
+    this.mutate(() => {
+      Object.assign(this.value.items[messageId], { state: "ignored", groupContext: limit > 0 });
+      const history = this.items().filter((value) => value.groupContext).sort((a, b) => BigInt(a.cursor) < BigInt(b.cursor) ? -1 : 1);
+      const thread = history.filter((value) => value.message.threadId === item.message.threadId);
+      for (const value of thread.slice(0, Math.max(0, thread.length - limit))) value.groupContext = false;
+      const retained = history.filter((value) => value.groupContext);
+      for (const value of retained.slice(0, Math.max(0, retained.length - 1e3))) value.groupContext = false;
+    });
+  }
+  beginDispatch(messageId, dispatchManifest, historyIds = []) {
+    if (this.value.items[messageId]?.state !== "received" || historyIds.some((id2) => !this.value.items[id2]?.groupContext || this.value.items[id2].message.threadId !== this.value.items[messageId].message.threadId)) throw new Error("Invalid native context dispatch custody");
+    this.mutate(() => {
+      Object.assign(this.value.items[messageId], { state: "dispatching", dispatchManifest });
+      for (const id2 of historyIds) this.value.items[id2].groupContext = false;
+    });
+  }
   /** Synchronous bounded receipt at the SDK's prepared-run callback boundary. */
   preparedCallback(messageIds, readPolicy, previous) {
     if (!messageIds.length || messageIds.length > 1e3) throw new Error("Invalid native prepared input manifest");
@@ -1411,8 +1508,10 @@ function prune() {
   for (const [id2, item] of pending) if (item.expires < Date.now()) pending.delete(id2);
 }
 function nativeDispatchManifest(params) {
+  const history = params.history ?? [];
+  if (history.length > 200 || history.some((message) => message.accountId !== params.message.accountId || message.threadId !== params.message.threadId || message.id === params.message.id)) throw Error("Invalid native history manifest");
   const assets = Object.freeze((params.assets ?? []).map((asset) => {
-    if (typeof asset.id !== "string" || !asset.id || asset.id.length > 2048 || !/^[a-f0-9]{64}$/.test(asset.sha256) || !Number.isSafeInteger(asset.byteLength) || asset.byteLength < 1 || asset.byteLength > 128 * 1024 * 1024 || typeof asset.path !== "string" || !isAbsolute3(asset.path) || asset.path.length > 4096 || typeof asset.mime !== "string" || asset.mime.length > 128 || !/^[a-z0-9.+-]+\/[a-z0-9.+-]+$/.test(asset.mime) || !["image", "audio", "video", "file"].includes(asset.kind) || !["model_image", "file_reference"].includes(asset.role) || asset.role === "model_image" && (asset.kind !== "image" || !asset.mime.startsWith("image/") || !asset.runtimeMedia) || asset.contextRole !== "trigger") throw Error("Invalid native supplied asset manifest");
+    if (typeof asset.id !== "string" || !asset.id || asset.id.length > 2048 || !/^[a-f0-9]{64}$/.test(asset.sha256) || !Number.isSafeInteger(asset.byteLength) || asset.byteLength < 1 || asset.byteLength > 128 * 1024 * 1024 || typeof asset.path !== "string" || !isAbsolute3(asset.path) || asset.path.length > 4096 || typeof asset.mime !== "string" || asset.mime.length > 128 || !/^[a-z0-9.+-]+\/[a-z0-9.+-]+$/.test(asset.mime) || !["image", "audio", "video", "file"].includes(asset.kind) || !["model_image", "file_reference"].includes(asset.role) || asset.role === "model_image" && (asset.kind !== "image" || !asset.mime.startsWith("image/") || !asset.runtimeMedia) || !["trigger", "history"].includes(asset.contextRole) || asset.contextRole === "history" && !history.some((message) => message.id === asset.messageId)) throw Error("Invalid native supplied asset manifest");
     return Object.freeze({ ...asset });
   }));
   const messageSid = `wechat-native:${params.message.accountId}:${params.message.id}`;
@@ -1442,6 +1541,12 @@ function nativeDispatchManifest(params) {
       ])),
       role: "trigger"
     })]),
+    ...history.length ? { historyInputs: Object.freeze(history.map((message) => Object.freeze({
+      id: message.id,
+      version: message.version ?? "",
+      contentSha256: digest(JSON.stringify([message.id, message.version, message.senderId, message.type, message.body, message.mentions, message.serverId])),
+      role: "history"
+    }))) } : {},
     assets,
     policySha256: digest(JSON.stringify(params.policy ?? null)),
     // Exact released 2026.10.2 source-turn identity. Requiring it in the later
@@ -1568,6 +1673,93 @@ function registerNativePreparedBoundary(api) {
   };
 }
 
+// src/native-history.ts
+import { buildHistoryContextFromEntries, buildInboundHistoryFromEntries, DEFAULT_GROUP_HISTORY_LIMIT } from "openclaw/plugin-sdk/reply-history";
+function nativeGroupHistoryLimit(cfg) {
+  const limit = cfg?.messages?.groupChat?.historyLimit;
+  return Number.isInteger(limit) && limit >= 0 ? Math.min(limit, 200) : DEFAULT_GROUP_HISTORY_LIMIT;
+}
+async function transcribeNativeAttachment(prepared, core, cfg) {
+  const attachment = prepared.attachment;
+  if (attachment?.kind !== "audio" || attachment.status !== "ready" || !attachment.path) return prepared;
+  let transcript = "";
+  try {
+    transcript = (await core.mediaUnderstanding.transcribeAudioFile({ filePath: attachment.path, cfg, mime: attachment.mime })).text?.trim() ?? "";
+  } catch {
+  }
+  return { ...prepared, body: `${prepared.body}
+${transcript ? `[Voice transcript: ${transcript.slice(0, 1e4)}]` : "[Voice transcription unavailable]"}` };
+}
+async function prepareNativeHistory(messages, prepare) {
+  const result = new Array(messages.length);
+  let next = 0;
+  await Promise.all(Array.from({ length: Math.min(3, messages.length) }, async () => {
+    for (let index = next++; index < messages.length; index = next++) {
+      const message = messages[index];
+      let prepared;
+      try {
+        prepared = await prepare(message);
+      } catch {
+        prepared = { body: `[Attachment unavailable for message ${message.id}: retrieval or integrity verification failed]`, pending: false };
+      }
+      if (message.type === 1 && prepared.body.length > 4096) prepared = { ...prepared, body: `${prepared.body.slice(0, 4096)}
+[Message truncated; use wechat_history or wechat_search for the stored message]` };
+      result[index] = { message, prepared };
+    }
+  }));
+  return result;
+}
+function buildNativeContext(history, message, prepared) {
+  const all = [...history, { message, prepared }];
+  const image = history.length ? [...all].reverse().find((item) => item.prepared.attachment?.kind === "image" && item.prepared.attachment.status === "ready" && item.prepared.mediaPath) : void 0;
+  const selected = history.length ? image : all.at(-1);
+  const assets = all.flatMap((item) => (item.prepared.suppliedAssets ?? []).map((asset) => {
+    const contextRole = item.message.id === message.id ? "trigger" : "history";
+    if (item === selected) return { ...asset, contextRole, messageId: item.message.id };
+    return {
+      ...asset,
+      contextRole,
+      messageId: item.message.id,
+      runtimeMedia: false,
+      role: "file_reference",
+      path: asset.sourcePath ?? asset.path,
+      sha256: asset.sourceSha256 ?? asset.sha256,
+      byteLength: asset.sourceByteLength ?? asset.byteLength,
+      mime: asset.sourceMime ?? asset.mime
+    };
+  }));
+  const entries = history.map((item) => ({
+    sender: item.message.senderId,
+    body: item.prepared.body,
+    timestamp: item.message.createdAt ? Date.parse(item.message.createdAt) : void 0,
+    messageId: item.message.id
+  }));
+  const inputBody = entries.length ? buildHistoryContextFromEntries({
+    entries,
+    currentMessage: prepared.body,
+    excludeLast: false,
+    formatEntry: (entry) => `${entry.sender}: ${entry.body}`
+  }) : prepared.body;
+  const attachments = all.flatMap((item) => {
+    const attachment = item.prepared.attachment;
+    return attachment?.status === "ready" && attachment.path ? [{
+      path: attachment.path,
+      filename: attachment.filename,
+      kind: attachment.kind,
+      messageId: item.message.id,
+      sender: item.message.senderId
+    }] : [];
+  });
+  return {
+    inputBody,
+    attachments,
+    assets,
+    history: buildInboundHistoryFromEntries({ entries, limit: entries.length }),
+    mediaPath: selected?.prepared.mediaPath,
+    mediaMime: selected?.prepared.mediaMime
+  };
+}
+
 // src/native-monitor.ts
 function nativeWasMentioned(message) {
   return message.mentions?.state === "known" && message.mentions.self === true;
@@ -1575,14 +1767,14 @@ function nativeWasMentioned(message) {
 async function projectNativeRead(client, accountId, state) {
   const pending2 = state.items().filter((value) => value.readPending);
   const threads = [...new Set(pending2.map((item) => item.message.threadId))];
-  for (const threadId of threads) {
+  for (const threadId2 of threads) {
     for (let attempt = 0; attempt < 2; attempt++) {
       let cursor;
       let thread;
       const seen = /* @__PURE__ */ new Set();
       for (let pageIndex = 0; pageIndex < 100; pageIndex++) {
         const page = await client.threads(accountId, cursor);
-        thread = page.items.find((value) => !isNativeTombstone(value) && value.id === threadId);
+        thread = page.items.find((value) => !isNativeTombstone(value) && value.id === threadId2);
         if (thread || !page.nextCursor) break;
         if (seen.has(page.nextCursor)) throw new Error("Native thread pagination did not advance");
         seen.add(page.nextCursor);
@@ -1593,7 +1785,7 @@ async function projectNativeRead(client, accountId, state) {
         const receipt = await client.markRead(accountId, thread.id, thread.readStateVersion);
         const notification = receipt?.phoneNotification?.state;
         const phoneReadState = notification === "accepted" || notification === "rejected" || notification === "needs_review" ? notification : void 0;
-        for (const item of pending2.filter((item2) => item2.message.threadId === threadId)) state.update(item.message.id, { readPending: false, phoneReadState });
+        for (const item of pending2.filter((item2) => item2.message.threadId === threadId2)) state.update(item.message.id, { readPending: false, phoneReadState });
         break;
       } catch (error) {
         if (error instanceof NativeApiError && error.status === 409 && attempt === 0) continue;
@@ -1616,8 +1808,20 @@ async function dispatchNativeMessage(params) {
   const policy = resolveWeChatPolicyContext({ account, cfg, chatId: message.threadId });
   const allowTextCommands = core.channel.commands.shouldHandleTextCommands({ cfg, surface: "agent-wechat" });
   const commandBody = normalizeWeChatCommandBody(message.type === 1 ? message.body ?? "" : "", { isGroup, wasMentioned });
+  const hasControlCommand = allowTextCommands && core.channel.commands.isControlCommandMessage(commandBody, cfg);
+  const resolve = core.channel.inbound?.ingress?.resolveStable ?? resolveStableChannelMessageIngress;
+  const senderAdmission = (senderId) => resolveWeChatIngress({
+    resolve,
+    cfg,
+    accountId: account.accountId,
+    policy,
+    isGroup,
+    chatId: message.threadId,
+    senderId,
+    readStoreAllowFrom: async () => core.channel.pairing.readAllowFromStore({ channel: "agent-wechat", accountId: account.accountId, env: process.env }).catch(() => [])
+  });
   const ingress = await resolveWeChatIngress({
-    resolve: core.channel.inbound?.ingress?.resolveStable ?? resolveStableChannelMessageIngress,
+    resolve,
     cfg,
     accountId: account.accountId,
     policy,
@@ -1625,11 +1829,15 @@ async function dispatchNativeMessage(params) {
     chatId: message.threadId,
     senderId: message.senderId,
     readStoreAllowFrom: async () => core.channel.pairing.readAllowFromStore({ channel: "agent-wechat", accountId: account.accountId, env: process.env }).catch(() => []),
-    command: { allowTextCommands, hasControlCommand: allowTextCommands && core.channel.commands.isControlCommandMessage(commandBody, cfg) },
+    command: { allowTextCommands, hasControlCommand },
     mention: { wasMentioned, allowTextCommands }
   });
   const unauthorizedDirectCommand = !isGroup && ingress.ingress.reasonCode === "control_command_unauthorized";
   if (ingress.ingress.admission !== "dispatch" && !unauthorizedDirectCommand) {
+    if (isGroup && policy.requireMention && !wasMentioned && !hasControlCommand && (await senderAdmission(message.senderId)).ingress.admission === "dispatch") {
+      state.bufferGroupMessage(message.id, nativeGroupHistoryLimit(cfg));
+      return "ignored";
+    }
     state.update(message.id, { state: "ignored" });
     return "ignored";
   }
@@ -1641,17 +1849,19 @@ async function dispatchNativeMessage(params) {
     return "needs_review";
   }
   if (preparedMedia.pending) return "pending";
-  let inputBody = preparedMedia.body;
-  if (preparedMedia.attachment?.kind === "audio" && preparedMedia.attachment.status === "ready" && preparedMedia.attachment.path) {
-    try {
-      const transcript = await core.mediaUnderstanding.transcribeAudioFile({ filePath: preparedMedia.attachment.path, cfg, mime: preparedMedia.attachment.mime });
-      if (transcript.text?.trim()) inputBody += `
-[Voice transcript: ${transcript.text.trim().slice(0, 1e4)}]`;
-      else inputBody += "\n[Voice transcription unavailable]";
-    } catch {
-      inputBody += "\n[Voice transcription unavailable]";
-    }
-  }
+  preparedMedia = await transcribeNativeAttachment(preparedMedia, core, cfg);
+  const buffered = isGroup && !hasControlCommand ? state.groupHistory(message.threadId, message.id, nativeGroupHistoryLimit(cfg)) : [];
+  const admitted = [];
+  for (const item of buffered) {
+    if (item.message.senderId && (await senderAdmission(item.message.senderId)).ingress.admission === "dispatch") admitted.push(item.message);
+  }
+  const history = await prepareNativeHistory(admitted, async (historical) => transcribeNativeAttachment(
+    await (params.prepareAttachment ?? prepareNativeAttachment)({ client, account, message: historical, core, cfg }),
+    core,
+    cfg
+  ));
+  const context = buildNativeContext(history, message, preparedMedia);
+  const inputBody = context.inputBody;
   const route = core.channel.routing.resolveAgentRoute({
     cfg,
     channel: "agent-wechat",
@@ -1681,10 +1891,12 @@ async function dispatchNativeMessage(params) {
     Surface: "agent-wechat",
     MessageSid: `wechat-native:${account.native.accountId}:${message.id}`,
     WasMentioned: isGroup ? wasMentioned : void 0,
+    Attachments: context.attachments,
+    InboundHistory: context.history,
     CommandAuthorized: core.channel.commands.shouldComputeCommandAuthorized(commandBody, cfg) ? ingress.commandAccess.authorized : void 0,
     OriginatingChannel: "agent-wechat",
     OriginatingTo: `wechat:${message.threadId}`,
-    ...preparedMedia.mediaPath ? { MediaPath: preparedMedia.mediaPath, MediaUrl: preparedMedia.mediaPath, MediaType: preparedMedia.mediaMime } : {}
+    ...context.mediaPath ? { MediaPath: context.mediaPath, MediaUrl: context.mediaPath, MediaType: context.mediaMime } : {}
   });
   await core.channel.session.recordInboundSession({ storePath, sessionKey: route.sessionKey, ctx });
   const pipeline = (params.createPipeline ?? createChannelMessageReplyPipeline)({ cfg, agentId: route.agentId, channel: "agent-wechat", accountId: account.accountId });
@@ -1696,9 +1908,10 @@ async function dispatchNativeMessage(params) {
     agentId: route.agentId,
     channelAccountId: account.accountId,
     policy,
-    assets: preparedMedia.suppliedAssets ?? []
+    assets: context.assets,
+    history: admitted
   });
-  state.update(message.id, { state: "dispatching", dispatchManifest });
+  state.beginDispatch(message.id, dispatchManifest, buffered.map((item) => item.message.id));
   const callback = readPolicy !== "on_inbound" && (message.type === 1 || preparedMedia.attachment?.status === "ready" && preparedMedia.suppliedAssets?.length) ? state.preparedCallback([message.id], readPolicy) : void 0;
   if (callback) trackNativePreparedInput(dispatchManifest, callback);
   let failed = false;
@@ -1903,10 +2116,10 @@ async function nativeLoginWait(accountId, timeoutMs = 3e4, stopAtQr = false) {
   }
   return { connected: false, message: "Native login remains pending; wait on the same operation rather than starting a replacement" };
 }
-async function sendNativeText(account, threadId, text, key = randomUUID5()) {
+async function sendNativeText(account, threadId2, text, key = randomUUID5()) {
   const native = account.native;
   const { client } = await ensureNativeHost(native);
-  const send = await submitNativeText(client, native.accountId, threadId, text, key);
+  const send = await submitNativeText(client, native.accountId, threadId2, text, key);
   return `agent-wechat-native:${native.accountId}:${send.id}`;
 }
 function createNativeLoginTool(account) {
@@ -2357,6 +2570,236 @@ function registerNativeFacade(api, config) {
   return handler.stop;
 }
 
+// src/native-history-tools.ts
+import { resolveStableChannelMessageIngress as resolveStableChannelMessageIngress2 } from "openclaw/plugin-sdk/channel-ingress-runtime";
+import { imageResultFromFile } from "openclaw/plugin-sdk/channel-actions";
+var pageSchema = { limit: { type: "integer", minimum: 1, maximum: 50, default: 20 }, cursor: { type: "string", maxLength: 8192, description: "Opaque nextCursor from the same tool and query; do not invent one." } };
+var names = ["wechat_history", "wechat_search", "wechat_message", "wechat_media"];
+var archiveNames = ["wechat_archive_threads", "wechat_archive_search", "wechat_archive_history", "wechat_archive_message", "wechat_archive_media"];
+var messageIdSchema = { type: "string", minLength: 1, maxLength: 4096 };
+var qualities = ["best", "original", "standard", "thumbnail", "normal", "encoded"];
+function object(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw Error("Expected tool arguments");
+  return value;
+}
+function string(value, name, max = 4096) {
+  if (typeof value !== "string" || !value.trim() || value.length > max || /[\u0000-\u001f\u007f]/.test(value)) throw Error(`Invalid ${name}`);
+  return value.trim();
+}
+function threadId(value) {
+  return string(string(value, "thread ID").replace(/^(?:agent-)?wechat:(?:group:)?/i, ""), "thread ID");
+}
+function messageResult(message, retrievalTool = "wechat_media") {
+  const kind2 = message.type === 3 ? "image" : message.type === 47 ? "sticker" : message.type === 34 ? "voice" : message.type === 43 ? "video" : message.type === 49 ? "file" : "unsupported";
+  const body = message.type === 1 ? message.body ?? "" : `[WeChat ${kind2} message; attachment content has not been retrieved by this tool]`;
+  return {
+    id: message.id,
+    threadId: message.threadId,
+    serverId: message.serverId,
+    senderId: message.senderId,
+    direction: message.direction,
+    type: message.type,
+    createdAt: message.createdAt,
+    body: body.slice(0, 4e3),
+    bodyTruncated: body.length > 4e3,
+    attachment: message.type !== 1 && kind2 !== "unsupported" ? { kind: kind2, retrievalTool, messageId: message.id } : void 0
+  };
+}
+function createNativeHistoryTools(context, dependencies = {}) {
+  return createLookupTools(context, dependencies, false);
+}
+function createNativeArchiveTools(context, dependencies = {}) {
+  return createLookupTools(context, dependencies, true);
+}
+function createLookupTools(context, dependencies, archive) {
+  const currentConfig = () => context.getRuntimeConfig?.() ?? context.runtimeConfig ?? context.config;
+  if (!currentConfig()) return [];
+  const selected = resolveWeChatAccount(currentConfig());
+  if (!selected?.native || !selected.enabled) return [];
+  if (!archive && context.messageChannel !== "agent-wechat") return [];
+  if (!archive && context.agentAccountId && context.agentAccountId !== selected.accountId) return [];
+  if (!archive && context.deliveryContext?.channel === "agent-wechat" && context.deliveryContext.accountId && context.deliveryContext.accountId !== selected.accountId) return [];
+  let currentThread;
+  let requesterSenderId;
+  const target = context.deliveryContext?.channel === "agent-wechat" ? context.deliveryContext.to : void 0;
+  if (!archive) {
+    try {
+      if (context.nativeChannelId) currentThread = threadId(context.nativeChannelId);
+      if (target) {
+        const deliveryThread = threadId(target);
+        if (currentThread && currentThread !== deliveryThread) return [];
+        currentThread ??= deliveryThread;
+      }
+      requesterSenderId = string(context.requesterSenderId, "requester sender ID");
+    } catch {
+      return [];
+    }
+    if (!currentThread) return [];
+  }
+  const selectedId = selected.native.accountId;
+  const tool = (name, action, description, properties, required = []) => ({
+    name,
+    label: name.replaceAll("_", " "),
+    description,
+    // The pinned host's tool_call wrapper JSON-serializes image blocks. Its
+    // public direct-only surface preserves actual image content for vision.
+    ...action === "media" ? { catalogMode: "direct-only" } : {},
+    parameters: { type: "object", additionalProperties: false, properties, required },
+    execute: async (_callId, input, signal) => {
+      const args = object(input);
+      const guard = () => {
+        signal?.throwIfAborted();
+        context.assertInvocationCurrent?.();
+        const cfg2 = currentConfig();
+        const account2 = resolveWeChatAccount(cfg2);
+        if (!account2?.enabled || !account2.native || account2.native.accountId !== selectedId || account2.accountId !== selected.accountId) throw Error("WeChat account configuration changed; start a new turn");
+        return { cfg: cfg2, account: account2, native: account2.native };
+      };
+      const { cfg, account, native } = guard();
+      if (Object.keys(args).some((key) => !Object.hasOwn(properties, key))) throw Error(archive ? "Unknown archive lookup argument" : "Unknown lookup argument; WeChat history is restricted to the current conversation");
+      const limit = args.limit ?? 20;
+      if (!Number.isInteger(limit) || limit < 1 || limit > 50) throw Error("limit must be 1\u201350");
+      const cursor = args.cursor === void 0 ? void 0 : string(args.cursor, "cursor", 8192);
+      const query = args.query === void 0 ? void 0 : string(args.query, "query", 256);
+      if (query && Buffer.byteLength(query) > 256) throw Error("Search query exceeds 256 UTF-8 bytes");
+      if (action === "search" && !query) throw Error("A non-empty search query is required");
+      const conversation = archive ? args.threadId === void 0 ? void 0 : threadId(args.threadId) : currentThread;
+      if (action === "history" && !conversation) throw Error("A thread ID is required");
+      const messageId = Object.hasOwn(properties, "messageId") ? string(args.messageId, "message ID") : void 0;
+      if (args.download !== void 0 && typeof args.download !== "boolean") throw Error("download must be a boolean");
+      const quality = args.quality ?? "best";
+      if (!qualities.includes(quality)) throw Error("Invalid media quality");
+      const core = dependencies.core ?? getWeChatRuntime();
+      const allowed = async (sender) => {
+        if (archive) return true;
+        const { cfg: cfg2, account: account2 } = guard();
+        const result2 = await resolveWeChatIngress({
+          resolve: core.channel.inbound?.ingress?.resolveStable ?? resolveStableChannelMessageIngress2,
+          cfg: cfg2,
+          accountId: account2.accountId,
+          policy: resolveWeChatPolicyContext({ account: account2, cfg: cfg2, chatId: conversation }),
+          isGroup: conversation.endsWith("@chatroom"),
+          chatId: conversation,
+          senderId: sender,
+          readStoreAllowFrom: async () => core.channel.pairing.readAllowFromStore({ channel: "agent-wechat", accountId: account2.accountId, env: process.env }).catch(() => [])
+        });
+        return result2.ingress.admission === "dispatch";
+      };
+      if (!await allowed(requesterSenderId)) throw Error("WeChat conversation access is no longer allowed");
+      guard();
+      const { client } = await (dependencies.host ?? ensureNativeHost)(native);
+      guard();
+      const accountId = native.accountId;
+      let result;
+      if (action === "threads") {
+        const page = await client.threads(accountId, { limit, cursor, ...query ? { query } : {} });
+        const items = [];
+        for (const thread of page.items) {
+          if (isNativeTombstone(thread)) continue;
+          if (thread.accountId !== accountId) throw Error("Thread response crosses an account boundary");
+          items.push({ id: thread.id, peerId: thread.peerId, kind: thread.kind, displayName: thread.displayName, unreadCount: thread.unreadCount });
+        }
+        result = { ...page, items, scope: "local_profile", note: "Locally stored threads; coverage may be partial. This lookup does not mark threads read." };
+      } else if (action === "message" || action === "media") {
+        const message = await client.message(accountId, messageId);
+        guard();
+        if (!await allowed(requesterSenderId)) throw Error("WeChat conversation access is no longer allowed");
+        if (message.id !== messageId || message.accountId !== accountId || !archive && message.threadId !== conversation || message.direction !== "outgoing" && !await allowed(message.senderId ?? void 0)) throw Error("Message is outside the permitted conversation or sender policy");
+        result = messageResult(message, archive ? "wechat_archive_media" : "wechat_media");
+        if (action === "media") {
+          let prepared;
+          try {
+            prepared = await prepareNativeAttachment({
+              client,
+              account,
+              message,
+              core,
+              cfg,
+              quality,
+              download: args.download !== false,
+              waitMs: 2e3,
+              signal,
+              assertCurrent: guard,
+              beforeMediaAccess: async () => {
+                if (!await allowed(requesterSenderId) || message.direction !== "outgoing" && !await allowed(message.senderId ?? void 0)) throw Error("WeChat conversation access is no longer allowed");
+              }
+            });
+          } catch (error) {
+            guard();
+            if (!(error instanceof NativeApiError)) throw error;
+            const details2 = {
+              messageId: message.id,
+              threadId: message.threadId,
+              status: error.retryable ? "pending" : ["unsupported_profile", "unsupported_media", "unsupported_media_variant"].includes(error.code) ? "unsupported" : "unavailable",
+              retryable: error.retryable,
+              reason: error.code
+            };
+            return { content: [{ type: "text", text: JSON.stringify(details2) }], details: details2 };
+          }
+          guard();
+          if (!await allowed(requesterSenderId) || message.direction !== "outgoing" && !await allowed(message.senderId ?? void 0)) throw Error("WeChat conversation access is no longer allowed");
+          const details = {
+            messageId: message.id,
+            threadId: message.threadId,
+            status: prepared.pending ? "pending" : prepared.attachment?.status ?? "unsupported",
+            attachment: prepared.attachment,
+            variant: prepared.variant,
+            jobId: prepared.jobId,
+            retryable: prepared.retryable ?? false,
+            reason: prepared.reason,
+            body: prepared.body
+          };
+          const image = prepared.suppliedAssets?.find((asset) => asset.role === "model_image");
+          const output = image ? await imageResultFromFile({ label: "WeChat attachment", path: image.path, extraText: JSON.stringify(details), details }) : { content: [{ type: "text", text: JSON.stringify(details) }], details };
+          guard();
+          return output;
+        }
+      } else {
+        const options = { limit, cursor, ...action === "search" ? { query } : {} };
+        const page = conversation ? await client.messages(accountId, conversation, options) : await client.searchMessages(accountId, options);
+        const items = [];
+        for (const message of page.items) {
+          if (isNativeTombstone(message)) continue;
+          if (conversation && message.threadId !== conversation || message.accountId !== accountId) throw Error("WeChat history response crosses a conversation boundary");
+          if (message.direction === "outgoing" || await allowed(message.senderId ?? void 0)) items.push(messageResult(message, archive ? "wechat_archive_media" : "wechat_media"));
+        }
+        result = {
+          ...page,
+          items,
+          scope: "local_profile",
+          searchMode: action === "search" ? "case_insensitive_substring" : void 0,
+          note: archive ? "Account-wide local history may be partial. These reads do not mark threads read or download attachments." : "Local history may be partial. A filtered page can be empty with a nextCursor. These reads do not mark a conversation read or download attachments."
+        };
+      }
+      guard();
+      return { content: [{ type: "text", text: JSON.stringify(result) }], details: result };
+    }
+  });
+  const querySchema = { type: "string", minLength: 1, maxLength: 256 };
+  const mediaSchema = {
+    messageId: messageIdSchema,
+    download: { type: "boolean", default: true, description: "Set false to use cached media only without requesting a WeChat transfer." },
+    quality: { type: "string", enum: qualities, default: "best", description: "best uses the best cached image, normal video or decoded voice. Explicit variants are strict and may be unavailable." }
+  };
+  if (archive) return [
+    tool(archiveNames[0], "threads", "List or find locally stored threads across the configured WeChat account. Optional case-insensitive query matches thread IDs and display names. Includes groups and peers, with opaque pagination; no read marking.", { query: querySchema, ...pageSchema }),
+    tool(archiveNames[1], "search", "Search locally stored messages across every thread in the configured WeChat account, including other senders. Optional threadId narrows the search. Follow nextCursor with the same query and thread selection; no remote backfill or read marking.", { query: querySchema, threadId: messageIdSchema, ...pageSchema }, ["query"]),
+    tool(archiveNames[2], "history", "Read the locally stored history of any thread in the configured WeChat account, newest first, without sender filtering or read marking. Use wechat_archive_threads to find thread IDs.", { threadId: messageIdSchema, ...pageSchema }, ["threadId"]),
+    tool(archiveNames[3], "message", "Look up a stored message in any thread of the configured WeChat account by its exact opaque message ID. Use wechat_archive_media to retrieve its attachment.", { messageId: messageIdSchema }, ["messageId"]),
+    tool(archiveNames[4], "media", "Retrieve an attachment from any thread in the configured WeChat account by its message ID. Returns verified managed file paths and an image preview for vision. Cached bytes first; missing media requests a bounded server-owned download unless download=false. Preserve pending/expired/unavailable results and never automatically retry retryable=false. No sends or read marking.", mediaSchema, ["messageId"])
+  ];
+  return [
+    tool(names[0], "history", "Read the current WeChat conversation's locally stored messages, newest first, beyond the recent inbound buffer. Follow nextCursor for older history; no remote history backfill or read marking.", { ...pageSchema }),
+    tool(names[1], "search", "Search the current WeChat conversation's locally stored message text by case-insensitive substring, beyond buffered messages. Follow nextCursor with the same query in this conversation.", { query: querySchema, ...pageSchema }, ["query"]),
+    tool(names[2], "message", "Look up a stored message by its exact opaque message ID in the current WeChat conversation. Media is described without downloading it; use wechat_media to retrieve its attachment. Long text is bounded.", { messageId: messageIdSchema }, ["messageId"]),
+    tool(names[3], "media", "Retrieve a message attachment from the current WeChat conversation. Returns a verified local file path and an image preview for vision when applicable. Uses cached bytes first; download defaults to true and requests a bounded server-owned transfer if missing. Pending results may be checked again; never automatically retry confirmed expiry or retryable=false. Does not send messages or mark the thread read.", mediaSchema, ["messageId"])
+  ];
+}
+function registerNativeHistoryTools(api) {
+  api.registerTool({ contextVersion: 2, create: (context) => createNativeHistoryTools(context) }, { names });
+  api.registerTool({ contextVersion: 2, create: (context) => createNativeArchiveTools(context) }, { names: archiveNames, optional: true });
+}
+
 // index.ts
 var plugin = {
   id: "agent-wechat",
@@ -2367,6 +2810,7 @@ var plugin = {
     setWeChatRuntime(api.runtime);
     const selected = resolveWeChatAccount(api.config);
     api.registerChannel({ plugin: wechatPlugin });
+    registerNativeHistoryTools(api);
     const stopFacade = selected?.native ? registerNativeFacade(api, selected.native) : () => {
     };
     const stopPreparedBoundary = selected?.native?.readPolicy && selected.native.readPolicy !== "on_inbound" ? registerNativePreparedBoundary(api) : () => {

package/openclaw.plugin.json

@@ -1,5 +1,15 @@
 {
   "id": "agent-wechat",
+  "contracts": {
+    "tools": ["wechat_history", "wechat_search", "wechat_message", "wechat_media", "wechat_archive_threads", "wechat_archive_search", "wechat_archive_history", "wechat_archive_message", "wechat_archive_media"]
+  },
+  "toolMetadata": {
+    "wechat_archive_threads": { "optional": true },
+    "wechat_archive_search": { "optional": true },
+    "wechat_archive_history": { "optional": true },
+    "wechat_archive_message": { "optional": true },
+    "wechat_archive_media": { "optional": true }
+  },
   "legacyPluginIds": [
     "wechat"
   ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-wechat/agent-wechat",
-  "version": "1.0.0-beta.5",
+  "version": "1.0.0-beta.6",
   "type": "module",
   "files": [
     "dist",