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

package/README.md

@@ -21,7 +21,7 @@ Configure plugin defaults under `plugins.entries.agent-wechat.config` (or the sa
 }
 ```
 
-The external service remains independently owned. Plugin stop closes its stream and never stops/logs out the daemon or cancels its sends. Remote endpoints require verified HTTPS or an encrypted tunnel terminating at loopback. Set `AGENT_WECHAT_TOKEN` in the Gateway process environment, or use a configured OpenClaw secret provider. The plugin resolves `native.token` through the pinned OpenClaw SDK; `native.tokenFile` is removed. Tokens contain 32–1024 printable ASCII bytes without spaces. An explicit unresolved reference fails startup without falling back to another token. The API token needs read/media/send/login for the selected account, plus read-state only when automatic local read projection is enabled; do not grant admin solely to run the plugin. Normal sender/DM/group/mention policy remains in `channels.agent-wechat`; defaults remain closed.
+The external service remains independently owned. Plugin stop closes its stream and never stops/logs out the daemon or cancels its sends. Remote endpoints require verified HTTPS or an encrypted tunnel terminating at loopback. Set `AGENT_WECHAT_TOKEN` in the Gateway process environment, or use a configured OpenClaw secret provider. The plugin resolves `native.token` through the pinned OpenClaw SDK; `native.tokenFile` is removed. Tokens contain 32–1024 printable ASCII bytes without spaces. An explicit unresolved reference fails startup without falling back to another token. The API token needs read/media/send/login for the selected account, plus read-state only when automatic whole-thread read marking is enabled; do not grant admin solely to run the plugin. Normal sender/DM/group/mention policy remains in `channels.agent-wechat`; defaults remain closed.
 
 ## Native managed mode
 
@@ -50,15 +50,15 @@ 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 synchronously writes a bounded durable receipt for the exact selected new message IDs before a separate retryable read projection. Read CAS retries preserve the same sparse IDs and never widen to the largest ID or clear concurrent arrivals. `readPolicy: "never"` disables automatic reads. Crashes during an unconfirmed dispatch retain `needs_review`; the plugin does not automatically duplicate model turns or uncertain outgoing sends.
+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.
 
 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.
 
-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 retry their exact sparse reads independently of new SSE traffic.
+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.
 
 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.
 
-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, exact sparse reads, lost-read-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.
+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.
 
 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

@@ -22,7 +22,7 @@ var nativeConfigSchema = {
       }
     }] },
     consumerStateDir: { type: "string" },
-    readPolicy: { type: "string", enum: ["never", "on_model_dispatch"] },
+    readPolicy: { type: "string", enum: ["never", "on_inbound", "on_model_dispatch"] },
     gatewayFacade: { type: "object", additionalProperties: false, required: ["enabled"], properties: { enabled: { type: "boolean" }, prefix: { type: "string" } } }
   }
 };
@@ -169,6 +169,7 @@ var NativeWeChatClient = class {
   token;
   fetchImpl;
   timeoutMs;
+  streamIdleTimeoutMs;
   constructor(options) {
     this.baseUrl = validateNativeBaseUrl(options.baseUrl);
     const nodeEnvironment = globalThis.process?.env;
@@ -179,6 +180,9 @@ var NativeWeChatClient = class {
     this.token = options.token;
     this.fetchImpl = options.fetch ?? fetch;
     this.timeoutMs = options.timeoutMs ?? 3e4;
+    this.streamIdleTimeoutMs = options.streamIdleTimeoutMs ?? 45e3;
+    if (!Number.isInteger(this.streamIdleTimeoutMs) || this.streamIdleTimeoutMs < 1 || this.streamIdleTimeoutMs > 3e5)
+      throw new Error("Invalid native stream idle timeout");
   }
   async response(path, init = {}, stream = false) {
     const headers = new Headers(init.headers);
@@ -436,16 +440,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, messageIds, expectedVersion) {
-    if (!messageIds.length || messageIds.length > 200 || messageIds.some((value) => typeof value !== "string" || !value) || typeof expectedVersion !== "string")
-      throw new Error("Invalid exact-ID read projection");
-    return this.request(`v1/accounts/${id(accountId)}/threads/${id(threadId)}/read-state`, { method: "POST", body: JSON.stringify({ messageIds: [...new Set(messageIds)], expectedVersion }) });
-  }
-  markReadThrough(accountId, threadId, throughMessageId, expectedVersion) {
-    id(throughMessageId);
-    if (typeof expectedVersion !== "string" || !expectedVersion)
+  markRead(accountId, threadId, 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({ throughMessageId, expectedVersion }) });
+    return this.request(`v1/accounts/${id(accountId)}/threads/${id(threadId)}/read-state`, { method: "POST", body: JSON.stringify({ expectedVersion }) });
   }
   events(accountId, after = "0", limit = 100) {
     if (!Number.isInteger(limit) || limit < 1 || limit > 200)
@@ -456,12 +454,27 @@ var NativeWeChatClient = class {
     return this.request(`v1/accounts/${id(accountId)}/consumers/${id(consumerId)}/ack`, { method: "POST", body: JSON.stringify({ cursor: decimal(cursor) }) });
   }
   async *watch(accountId, after = "0", signal) {
-    const response = await this.response(`v1/accounts/${id(accountId)}/events/stream?after=${decimal(after)}`, { signal, headers: { Accept: "text/event-stream" } }, true);
-    if (!response.headers.get("content-type")?.startsWith("text/event-stream"))
-      throw new Error("Expected native SSE response");
-    const reader = response.body?.getReader();
-    if (!reader)
-      throw new Error("Native SSE has no body");
+    const connection = new AbortController();
+    const streamSignal = signal ? AbortSignal.any([signal, connection.signal]) : connection.signal;
+    const bounded = async (work, milliseconds, reason) => {
+      if (streamSignal.aborted)
+        throw streamSignal.reason;
+      let timer;
+      let onAbort = () => {
+      };
+      const interrupted = new Promise((_resolve, reject) => {
+        onAbort = () => reject(streamSignal.reason ?? new Error("Native SSE cancelled"));
+        streamSignal.addEventListener("abort", onAbort, { once: true });
+        timer = setTimeout(() => connection.abort(new Error(reason)), milliseconds);
+      });
+      try {
+        return await Promise.race([work(), interrupted]);
+      } finally {
+        clearTimeout(timer);
+        streamSignal.removeEventListener("abort", onAbort);
+      }
+    };
+    let reader;
     const decoder = new TextDecoder();
     let buffer = "";
     let data = [];
@@ -469,8 +482,17 @@ var NativeWeChatClient = class {
     let eventCursor = "";
     let eventType = "";
     try {
+      const response = await bounded(() => this.response(`v1/accounts/${id(accountId)}/events/stream?after=${decimal(after)}`, { signal: streamSignal, headers: { Accept: "text/event-stream" } }, true), this.timeoutMs, "Native SSE connection timeout");
+      if (!response.headers.get("content-type")?.startsWith("text/event-stream")) {
+        await response.body?.cancel();
+        throw new Error("Expected native SSE response");
+      }
+      reader = response.body?.getReader();
+      if (!reader)
+        throw new Error("Native SSE has no body");
       while (true) {
-        const { value, done } = await reader.read();
+        const activeReader = reader;
+        const { value, done } = await bounded(() => activeReader.read(), this.streamIdleTimeoutMs, "Native SSE idle timeout");
         if (done)
           break;
         buffer += decoder.decode(value, { stream: true });
@@ -510,9 +532,12 @@ var NativeWeChatClient = class {
         }
       }
     } finally {
-      await reader.cancel().catch(() => {
-      });
-      reader.releaseLock();
+      connection.abort();
+      if (reader) {
+        await reader.cancel().catch(() => {
+        });
+        reader.releaseLock();
+      }
     }
   }
 };
@@ -709,7 +734,7 @@ function collectWeChatStatusIssues(accounts) {
         accountId: snapshot.accountId,
         kind: "runtime",
         message: "Prepared model handoff was not confirmed by this OpenClaw host; automatic read state remains unchanged.",
-        fix: "Use a compatible prepared-run SDK hook, or select native.readPolicy=never while retaining explicit local read control."
+        fix: "Select native.readPolicy=on_inbound to mark successfully handled conversations read without model hooks, or use a compatible prepared-run SDK hook."
       });
     }
     if ((snapshot.needsReview ?? 0) > 0) {
@@ -1333,7 +1358,7 @@ 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 && ["completed", "ignored"].includes(item.state));
+        const completed = Object.entries(this.value.items).filter(([, item]) => !item.readPending && 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" };
@@ -1548,14 +1573,16 @@ function nativeWasMentioned(message) {
   return message.mentions?.state === "known" && message.mentions.self === true;
 }
 async function projectNativeRead(client, accountId, state) {
-  for (const item of state.items().filter((value) => value.readPending && value.runId)) {
+  const pending2 = state.items().filter((value) => value.readPending);
+  const threads = [...new Set(pending2.map((item) => item.message.threadId))];
+  for (const threadId 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 === item.message.threadId);
+        thread = page.items.find((value) => !isNativeTombstone(value) && value.id === threadId);
         if (thread || !page.nextCursor) break;
         if (seen.has(page.nextCursor)) throw new Error("Native thread pagination did not advance");
         seen.add(page.nextCursor);
@@ -1563,8 +1590,10 @@ async function projectNativeRead(client, accountId, state) {
       }
       if (!thread) break;
       try {
-        await client.markRead(accountId, thread.id, [item.message.id], thread.readStateVersion);
-        state.update(item.message.id, { readPending: false });
+        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 });
         break;
       } catch (error) {
         if (error instanceof NativeApiError && error.status === 409 && attempt === 0) continue;
@@ -1575,6 +1604,7 @@ async function projectNativeRead(client, accountId, state) {
 }
 async function dispatchNativeMessage(params) {
   const { client, state, account, message, cfg, core } = params;
+  const readPolicy = account.native?.readPolicy ?? "on_inbound";
   const custody = state.get(message.id);
   if (!custody || custody.state !== "received") return "needs_review";
   if (custody.origin !== "live" || message.direction !== "incoming" || ![1, 3, 34, 43, 47, 49].includes(message.type) || message.type === 1 && !message.body || !message.senderId) {
@@ -1669,7 +1699,7 @@ async function dispatchNativeMessage(params) {
     assets: preparedMedia.suppliedAssets ?? []
   });
   state.update(message.id, { state: "dispatching", dispatchManifest });
-  const callback = message.type === 1 || preparedMedia.attachment?.status === "ready" && preparedMedia.suppliedAssets?.length ? state.preparedCallback([message.id], account.native?.readPolicy ?? "on_model_dispatch") : void 0;
+  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;
   let delivery = 0;
@@ -1691,6 +1721,7 @@ async function dispatchNativeMessage(params) {
             const key = createHash8("sha256").update(`${account.native.accountId}\0${message.id}\0${delivery++}`).digest("hex");
             await submitNativeText(client, account.native.accountId, message.threadId, payload.text, key);
           }
+          if (urls.length || payload.text) params.onDelivered?.();
         },
         onError: () => {
           failed = true;
@@ -1702,8 +1733,12 @@ async function dispatchNativeMessage(params) {
       // and media-snapshot bridge; unsupported or ambiguous handoffs leave reads unchanged.
       replyOptions: { runId: dispatchManifest.runId, onModelSelected, onPreparedAgentRunStart: callback }
     });
-    const prepared = Boolean(state.get(message.id)?.runId);
-    state.update(message.id, { state: failed ? "needs_review" : "completed", handoffUnconfirmed: !prepared });
+    const readPending = readPolicy === "on_inbound" && !failed && ingress.ingress.admission === "dispatch" ? true : state.get(message.id)?.readPending;
+    state.update(message.id, {
+      state: failed ? "needs_review" : "completed",
+      readPending,
+      handoffUnconfirmed: readPolicy === "on_model_dispatch" && !state.get(message.id)?.runId
+    });
     return failed ? "needs_review" : "completed";
   } catch {
     state.update(message.id, { state: "needs_review" });
@@ -1737,23 +1772,34 @@ async function startNativeMonitor(opts) {
   const core = getWeChatRuntime();
   let backoff = 250;
   let readTask;
-  const flushRead = () => readTask ??= projectNativeRead(host2.client, native.accountId, state).finally(() => {
-    readTask = void 0;
-  });
+  const flushRead = () => {
+    if (native.readPolicy === "never") return Promise.resolve();
+    return readTask ??= projectNativeRead(host2.client, native.accountId, state).finally(() => {
+      readTask = void 0;
+    });
+  };
   const process2 = async () => {
     const cfg = core.config.current();
     const account = resolveWeChatAccount(cfg, opts.account.accountId) ?? opts.account;
     if (account.backend !== "native" || JSON.stringify(account.native) !== JSON.stringify(native)) throw new Error("Native service configuration changed; restart required before processing");
     for (const item of state.items().filter((value) => value.state === "received")) {
-      await dispatchNativeMessage({ client: host2.client, state, account, message: item.message, cfg, core });
+      await dispatchNativeMessage({
+        client: host2.client,
+        state,
+        account,
+        message: item.message,
+        cfg,
+        core,
+        onDelivered: () => opts.setStatus({ accountId: account.accountId, lastOutboundAt: Date.now() })
+      });
     }
     try {
       await flushRead();
     } catch {
-      opts.log?.error?.("Native read projection is pending; exact input IDs retained for retry");
+      opts.log?.error?.("Native read projection is pending; thread read receipt retained for retry");
     }
-    const needsReview = state.items().filter((value) => value.state === "needs_review").length;
-    const handoffUnconfirmed = native.readPolicy !== "never" && state.items().some((value) => value.handoffUnconfirmed);
+    const needsReview = state.items().filter((value) => value.state === "needs_review" || value.phoneReadState === "needs_review" || value.phoneReadState === "rejected").length;
+    const handoffUnconfirmed = native.readPolicy === "on_model_dispatch" && state.items().some((value) => value.handoffUnconfirmed);
     const accountStatus = await host2.client.account(native.accountId);
     opts.setStatus({
       accountId: account.accountId,
@@ -1769,9 +1815,9 @@ async function startNativeMonitor(opts) {
     await flushRead();
     if (!opts.abortSignal.aborted) opts.setStatus({
       accountId: opts.account.accountId,
-      handoffUnconfirmed: native.readPolicy !== "never" && state.items().some((value) => value.handoffUnconfirmed)
+      handoffUnconfirmed: native.readPolicy === "on_model_dispatch" && state.items().some((value) => value.handoffUnconfirmed)
     });
-  }, () => opts.log?.error?.("Native read projection remains pending; exact input IDs retained"));
+  }, () => opts.log?.error?.("Native read projection remains pending; thread read receipts retained"));
   try {
     while (!opts.abortSignal.aborted) {
       try {
@@ -1785,6 +1831,7 @@ async function startNativeMonitor(opts) {
             if (message.threadId !== event.data.threadId) throw new Error("Native committed message thread identity mismatch");
           }
           state.accept(event.cursor, message, typeof event.data.origin === "string" ? event.data.origin : "unknown");
+          if (message?.direction === "incoming" && event.data.origin === "live") opts.setStatus({ accountId: opts.account.accountId, lastInboundAt: Date.now() });
           await host2.client.ack(native.accountId, "openclaw", state.cursor);
           await process2();
           backoff = 250;
@@ -2322,7 +2369,8 @@ var plugin = {
     api.registerChannel({ plugin: wechatPlugin });
     const stopFacade = selected?.native ? registerNativeFacade(api, selected.native) : () => {
     };
-    const stopPreparedBoundary = registerNativePreparedBoundary(api);
+    const stopPreparedBoundary = selected?.native?.readPolicy && selected.native.readPolicy !== "on_inbound" ? registerNativePreparedBoundary(api) : () => {
+    };
     api.registerService({
       id: "agent-wechat-native",
       reload: { configPrefixes: ["plugins.entries.agent-wechat.config", "channels.agent-wechat", "secrets"] },

package/openclaw.plugin.json

@@ -95,6 +95,7 @@
             "type": "string",
             "enum": [
               "never",
+              "on_inbound",
               "on_model_dispatch"
             ]
           },
@@ -274,6 +275,7 @@
                 "type": "string",
                 "enum": [
                   "never",
+                  "on_inbound",
                   "on_model_dispatch"
                 ]
               },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-wechat/agent-wechat",
-  "version": "1.0.0-beta.3",
+  "version": "1.0.0-beta.5",
   "type": "module",
   "files": [
     "dist",
@@ -11,7 +11,7 @@
     "esbuild": "^0.25.0",
     "openclaw": "2026.10.2",
     "typescript": "^5.4.5",
-    "@agent-wechat/shared": "1.0.0-beta.0"
+    "@agent-wechat/shared": "1.0.0-beta.1"
   },
   "openclaw": {
     "extensions": [
@@ -183,6 +183,7 @@
                   "type": "string",
                   "enum": [
                     "never",
+                    "on_inbound",
                     "on_model_dispatch"
                   ]
                 },