@agent-wechat/agent-wechat 2.7.0 → 2.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +11 -9
  2. package/dist/index.js +749 -310
  3. package/package.json +2 -2
package/README.md CHANGED
@@ -50,7 +50,7 @@ Provision the native executable and account registration separately. Omitting `e
50
50
 
51
51
  Managed startup sends the resolved token through a private stdin pipe; it creates no token file and does not put the token in arguments or the daemon environment. A managed `serverConfig` must omit `tokenFile`. Reload/restart the Gateway to change credentials or secret-provider configuration.
52
52
 
53
- Keep `dataDir` and `consumerStateDir` on separate explicit persistent mounts. The daemon owns official-format profile/sidecar data; the consumer directory holds private intake/deduplication/model-handoff/read receipts bound to server and account identities. Executable upgrades do not remove either. One configured OpenClaw account maps to one selected native daemon account in this increment, while the daemon itself supports independent account slots.
53
+ Keep `dataDir` and `consumerStateDir` on separate explicit persistent mounts. The daemon owns official-format profile/sidecar data; the consumer directory holds the event cursor, the identities of messages still being handled, pending thread reads and each group's context boundary, bound to server and account identities. It stores no message content. The first start after an upgrade converts a file written by an earlier release: it keeps the cursor, pending reads and group context position, keeps queued messages only under the catch-up rules below, reports interrupted turns without repeating them, and leaves the original file beside the new one with a `.v1-backup` suffix. That backup still holds the earlier release's message copies; delete it once the upgrade is settled. An earlier release cannot read the converted file. Executable upgrades do not remove either. One configured OpenClaw account maps to one selected native daemon account in this increment, while the daemon itself supports independent account slots.
54
54
 
55
55
  ## Calling
56
56
 
@@ -68,17 +68,19 @@ for connections and limits.
68
68
 
69
69
  ## Native messaging lifecycle and validation limits
70
70
 
71
- 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.
71
+ The adapter consumes account-scoped SSE using bearer headers and decimal-string journal cursors. The cursor is its record of which events it has seen: the daemon commits each message once, so finished messages are not kept. It persists the cursor and any queued work before acknowledging; acknowledgement is independent of unread state. Only explicitly live, incoming, committed resources can enter the model, and only messages that were sent and reached the daemon within the last 24 hours. Only messages the current sender, group, mention and command policy would answer are queued. Queued work stores message identities only; each message is read from the daemon when it is handled, and one older than 24 hours by then is skipped. 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 never start an automatic model turn. Group context is read from saved messages, which do not record how a message arrived, so incoming synced or imported messages can appear there for a later mention, up to `historyLimit`. 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.
72
72
 
73
73
  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.
74
74
 
75
- 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.
75
+ In groups requiring a mention, unmentioned messages get no retrieval, transcription, model turn or read notification. When an admitted non-command message triggers a turn, the adapter reads the group's earlier messages from the daemon, newest first, back to the last message it handed to the model in that group. It keeps incoming messages from senders the current policy admits and leaves out messages still queued for their own turn, commands, the account's own messages and recalled messages. `messages.groupChat.historyLimit` controls the per-group window (default 50, maximum 200; zero disables it). The boundary moves in the same durable write as the turn record, so an uncertain turn's context is not offered again automatically. Original mention facts remain unchanged; history is recorded separately from the triggering message.
76
76
 
77
- 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.
77
+ After a restart, the adapter reads the events it missed from its cursor and answers at most the newest 100 messages the current policy would answer, counting messages that were already queued. The limit is applied before each acknowledgement. Group messages that need a mention and have none are not queued; they remain available as context. A new consumer directory, or a cursor older than the daemon's retained event log, resumes at the first event of the last 24 hours instead of replaying the log. Skipped messages are logged.
78
+
79
+ 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 neither receive nor use up group context.
78
80
 
79
81
  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.
80
82
 
81
- 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.
83
+ 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. A turn that was in progress when the Gateway stopped is logged and dropped at the next start; the plugin does not automatically duplicate model turns or uncertain outgoing sends.
82
84
 
83
85
  The optional `readPolicy: "on_model_dispatch"` instead requires a confirmed model handoff. On OpenClaw **2026.11.4**, the host calls `onPreparedAgentRunStart` for the run that contains the dispatched message once its transcript is prepared, and that call confirms the handoff. It does not need `hooks.allowConversationAccess`. It happens before the provider request and before the host drops images for a text-only model, so it shows that the run started with the message, not that the model received every image. Built-in commands, rejected messages, and media without a ready supplied asset are never confirmed, and status reports `handoffUnconfirmed`.
84
86
 
@@ -100,17 +102,17 @@ Every target gets a stable idempotency key and a durable operation. Only an exac
100
102
 
101
103
  Native text, image, file, video and voice delivery results return actual stored message IDs after account/thread/server-identity verification. `meta.messageIds` preserves each verified receipt for split voice notes, alongside the durable send/job ID. Accepted media jobs may publish their stored receipts slightly later; the adapter inspects the same job for up to ten seconds and requires every accepted voice chunk's receipt. If stored receipts remain unavailable, the result leaves `messageId` empty and reports `receiptState: "needs_review"` with `retryable: false`; acceptance is not a reason to resend. Failed, partial and uncertain jobs do not enter that receipt wait.
102
104
 
103
- Incoming `message.recalled` events are consumed independently of slow media and model work, including recalls of own or unmentioned messages. The consumer persists the event cursor together with a tombstone, removes recalled body/quote content and attachment references from its custody records, and invalidates pending model proofs. Tombstones survive restart and suppress a late original. Attachment retrieval, transcription, model dispatch and later automatic reply delivery recheck the selected messages so late work cannot reinsert recalled input. A quote's unrelated comment remains available after its recalled original is removed.
105
+ Incoming `message.recalled` events are consumed independently of slow media and model work, including recalls of own or unmentioned messages. The consumer persists the event cursor together with the recall's effect: a queued target is dropped, a queued message quoting it is read again, and an in-flight turn that used it is invalidated along with its pending model proofs. It keeps no tombstones: the daemon applies recalls to the official profile, including a recall that arrives before its original, so later reads already show the recalled state. Attachment retrieval, transcription, model dispatch and later automatic reply delivery recheck the selected messages so late work cannot reinsert recalled input. A quote's unrelated comment remains available after its recalled original is removed.
104
106
 
105
107
  Received quotes use the parsed embedded content delivered by WeChat's server protocol and included in the normal message response's `quote` field. Text and link details render immediately; image metadata can retrieve verified bytes under the reply's own message ID. Other quoted media keeps the current comment and an unavailable attachment status. Local recall suppression and quoted-author admission still apply, including in history tools. A stored original never replaces the embedded excerpt; quote display needs no separate quote endpoint.
106
108
 
107
- If a source-local message ID later names a different exact thread/server target, the consumer admits that new message with a separate host turn and reply key. Completion callbacks, media results and read receipts captured for the old target cannot overwrite the new custody record.
109
+ If a source-local message ID later names a different exact thread/server target, the consumer admits that new message with a separate host turn and reply key. Completion callbacks, media results and read receipts captured for the old target cannot overwrite the new custody record, and replies built on a context message that changed identity are held.
108
110
 
109
111
  Stored-history tools return a recalled placeholder; media tools return terminal `status: "recalled"`, `reason: "message_recalled"`, `retryable: false` without attachment paths or image blocks. Recall does not erase an already submitted model input, an existing OpenClaw transcript, a completed action, or attachment bytes retained by OpenClaw's storage policy. An affected in-flight turn is held for review and its later automatic reply is suppressed; the plugin does not claim retroactive transcript correction.
110
112
 
111
113
  Old media handles whose stored source changed, or whose source identity cannot be verified, return terminal `unavailable` with `media_source_changed` or `media_identity_unavailable`. They expose no cached path and are not retried automatically. Fresh stored-message discovery can select the intended current message and its bound cached asset without resending a WeChat message.
112
114
 
113
- `node packages/openclaw-extension/test/smoke/recall-model.mjs` builds the actual plugin and runs the pinned Gateway against synthetic native HTTP/SSE and a local provider. It checks registered tool discovery and exact-target execution, stable repeated keys, another thread's rejection, recall intake while provider/media requests are blocked, late-output suppression, out-of-order recall custody and one dispatch for a new exact occupant of a reused source ID. It makes no real account or native protocol exchange.
115
+ `node packages/openclaw-extension/test/smoke/recall-model.mjs` builds the actual plugin and runs the pinned Gateway against synthetic native HTTP/SSE and a local provider. It checks registered tool discovery and exact-target execution, stable repeated keys, another thread's rejection, recall intake while provider/media requests are blocked, late-output suppression, out-of-order recall suppression, one dispatch for a new exact occupant of a reused source ID, and no repeat after a stream reconnect. It makes no real account or native protocol exchange.
114
116
 
115
117
  ## Stored-history tools
116
118
 
@@ -135,7 +137,7 @@ History/search return opaque string message IDs, a bounded text preview, coverag
135
137
 
136
138
  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.
137
139
 
138
- `node packages/openclaw-extension/test/smoke/history-model.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.
140
+ `node packages/openclaw-extension/test/smoke/history-model.mjs` exercises the pinned Gateway with local account/media/model fixtures: group context read back from saved messages after a restart, 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.
139
141
 
140
142
  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.
141
143