@agent-wechat/agent-wechat 1.0.0-beta.11 → 1.0.0-beta.13

package/README.md

@@ -23,6 +23,12 @@ 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 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.
 
+## Login tool
+
+`wechat_login` is available to configured agents through OpenClaw's tool policy, including from other channels while WeChat is offline. Use `{"action":"status"}` to inspect the account, `{"action":"start"}` to start or resume login and display the returned QR image, then `{"action":"wait","timeoutMs":30000}` to check scan/approval completion. Repeated starts reuse the pending operation. For a new operation, `force: true` uses QR instead of saved trust. Waits are bounded and report the operation ID and state. Cancelling a tool call leaves the submitted login operation available for a later call.
+
+The tool also accepts `disconnect` (retain saved trust), `logout` (durable native logout) and `forget` with `confirm: true` (remove local authentication, retain history). It stays bound to the configured daemon/account. Apply OpenClaw tool allow/deny policies to control which agents can manage login. The tool is directly callable so the daemon's PNG reaches the model as image content.
+
 ## Native managed mode
 
 ```json
@@ -80,6 +86,8 @@ Native text, image, file, video and voice delivery results return actual stored
 
 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.
 
+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.
+
 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.
 
 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.
@@ -159,6 +167,36 @@ Run `node scripts/native-model-smoke.mjs` and `node scripts/native-media-model-s
 
 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.
 
+## Outgoing attachment sizes
+
+`channels.agent-wechat.mediaMaxMb` limits both incoming retained attachments and
+outgoing sources in MiB. Outgoing sources must also fit the selected kind's
+native limit: ordinary files have a 512 MiB ceiling (536,870,912 bytes);
+video sources allow 50 MiB; images and voice retain 26,214,383 bytes. Native File Transfer PDFs passed
+acceptance, recipient opening and cold byte verification at 32 MiB and 50 MiB.
+Full-client 512 MiB send validation remains pending. The 50 MiB file also passed
+real OpenClaw storage; see the [native capability checklist](../native-client-rust/FEATURES.md).
+Raising `mediaMaxMb` cannot extend the kind-specific limit. Kind selection occurs
+before staging, using the local extension or HTTP content type. Ordinary audio
+is a file unless `audioAsVoice` selects voice.
+
+For ordinary files above 26,214,383 bytes, the adapter polls the same submitted
+job for up to an hour, allowing upload and exact readback before final
+message submission. A timeout or status-poll failure preserves the job ID and idempotency key and never
+automatically sends another copy. Unsupported cache-hit responses or uncertain
+reservations/submissions require inspection. See [Send attachments](https://thisnick.github.io/agent-wechat/use/media/)
+for CLI, HTTP API and SDK examples.
+
+Video sends default to a prepared H.264/AAC playback copy and thumbnail. For one
+video attachment, the regular message tool accepts
+`channelData: { "agent-wechat": { "videoQuality": "original" } }` to include the
+unchanged source too; `"normal"` selects playback only. Set `mediaMaxMb` to allow
+the source size. `forceDocument` (or host alias `asDocument`) sends the media as
+an ordinary file and cannot be combined with video quality. Video jobs poll the
+same job for up to an hour. See the native capability checklist for separate
+server, recipient and local-writeback validation.
+
+
 ## Optional Gateway facade
 
 Set `native.gatewayFacade: {"enabled": true}` to register `/plugins/agent-wechat/native` on the Gateway. The default is disabled. A custom prefix must remain namespaced under `/plugins/...`; changing daemon configuration requires a Gateway reload.