fix(gateway/weixin): correct aes_key encoding and upload_full_url CDN path

[longsizhuo]

What does this PR do?

Fixes three bugs in the Weixin (iLink Bot) adapter's outbound media pipeline that caused bot-sent images to appear as a grey placeholder in the WeChat client — the image is delivered but cannot be opened or decrypted.

Root cause: image_item.media.aes_key was encoded as base64(raw_16_bytes), but the WeChat client's decode chain is:

base64_decode(aes_key)  →  32 ASCII hex chars  →  bytes.fromhex()  →  16-byte AES key

Sending base64(raw_bytes) produced 16 decoded bytes that couldn't be parsed as hex, so the client derived the wrong key and AES-128-ECB decryption failed silently, leaving the user with an unusable grey image.

Two follow-on bugs in the same _send_file() path were fixed at the same time because they blocked the image from ever reaching the client correctly:

1. upload_full_url (returned by newer iLink API instances) requires HTTP POST, not PUT. The old code only tried PUT and got 404 from the CDN.
2. The encrypted_query_param query argument embedded inside upload_full_url is an upload-auth token, not the download key. The real download key is returned by the CDN in the x-encrypted-param response header after a successful upload — the old code used the wrong value, which produced an encrypted reference the client could not resolve.

Related Issue

Fixes #7529

Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue)
• ✨ New feature (non-breaking change that adds functionality)
• 🔒 Security fix
• 📝 Documentation update
• ✅ Tests (adding or improving test coverage)
• ♻️ Refactor (no behavior change)
• 🎯 New skill (bundled or hub)

Changes Made

All changes are in gateway/platforms/weixin.py:

• _send_file() — aes_key encoding (root cause). Changed base64.b64encode(aes_key).decode("ascii") → base64.b64encode(aes_key.hex().encode("ascii")).decode("ascii"), with a comment documenting the client's decode chain.
• _send_file() — upload_full_url CDN method. Replaced the single-PUT call with a POST-first, PUT-on-404 fallback loop so both current and legacy CDN endpoints work.
• _send_file() — encrypted_query_param source. The download key is now taken from the x-encrypted-param response header returned by the CDN after the ciphertext upload, not from the query string of upload_full_url. Falls back to filekey if the header is missing. A clear RuntimeError is raised if both methods fail.
• send_image_file() — parameter name. Renamed path → image_path to match the base adapter signature (gateway/platforms/base.py:1058). Accepts legacy path= kwarg for backwards compatibility, and returns SendResult(success=False, error=...) if neither is provided instead of letting Path("").read_bytes() raise IsADirectoryError deep in the stack.
• _outbound_media_builder() — removed unused aes_key_hex kwarg plumbing (review feedback: it was passed to item_builder(...) but none of the lambdas read it).

How to Test

Reproducing the original bug (before this PR):

1. Configure a Weixin account (hermes gateway setup, scan QR, confirm login).
2. Start the gateway: hermes gateway.
3. DM the bot from the WeChat mobile client and ask it to send an image (e.g., 拍一张照片 or any prompt that triggers a local image file response).
4. Observe: the bot's reply contains an image bubble that renders as an opaque grey square; tapping it shows no preview.

Verifying the fix (with this PR):

1. Repeat steps 1–3 on the branch.
2. The image now renders correctly in the WeChat mobile client — tap-to-preview works, the full photo loads, and long-press / save works as expected.

Code-level sanity check of the aes_key encoding fix:

import base64, secrets
aes_key = secrets.token_bytes(16)
aes_key_b64 = base64.b64encode(aes_key.hex().encode("ascii")).decode("ascii")

# Simulate the WeChat client's decode chain:
decoded = base64.b64decode(aes_key_b64)       # 32 bytes (ASCII hex chars)
assert len(decoded) == 32
recovered = bytes.fromhex(decoded.decode("ascii"))
assert recovered == aes_key                   # Round-trip matches

The old base64.b64encode(aes_key).decode("ascii") produces 16 decoded bytes that are not valid ASCII hex, so bytes.fromhex(...) on the client side fails to recover the key.

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits (fix(gateway/weixin): ...)
• I searched for existing PRs to make sure this isn't a duplicate
• My PR contains only changes related to this fix (the adapter's outbound media path)
• I've run pytest tests/ -q and all tests pass — not yet re-run after the latest revert; will re-run before merge
• I've added tests for my changes — not yet; planning to add unit tests mocking aiohttp.ClientSession to cover the POST→PUT fallback, the x-encrypted-param header read, and the base64(hex) aes_key encoding in a follow-up commit on this branch
• I've tested on my platform: Ubuntu (Linux 6.8), against a live iLink Bot API account and the WeChat mobile client

Documentation & Housekeeping

• I've updated relevant documentation — N/A (no public API change; website/docs/user-guide/messaging/weixin.md already describes the encrypted CDN pipeline at the correct level of abstraction)
• I've updated cli-config.yaml.example if I added/changed config keys — N/A (no config changes)
• I've updated CONTRIBUTING.md or AGENTS.md — N/A (no architectural/workflow change)
• I've considered cross-platform impact — N/A (pure network/protocol code; no file-system, process, or terminal handling)
• I've updated tool descriptions/schemas — N/A (no tool signature change; send_image_file(image_path=...) now matches the base adapter signature, which is a fix, not a breaking change)

Screenshots / Logs

Before: image bubble renders as a grey placeholder in the WeChat mobile client; tap-to-preview does nothing.

After: image renders correctly, preview and long-press actions work as expected.

Screenshots showing the before/after can be added on request; they contain personal chat context so they are not attached inline.

[Copilot]

Pull request overview

Fixes Weixin/iLink outbound media uploads so bot-sent images decrypt/display correctly in WeChat, and extends agent configuration to support per-model max_tokens under custom_providers.

Changes:

• Correct Weixin outbound media message construction (AES key encoding) and improve upload_full_url upload behavior (POST-first with PUT fallback; use CDN header for download key).
• Fix Weixin adapter send_image_file() to accept image_path and legacy path.
• Read max_tokens from custom_providers per-model config in run_agent.py.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.

File	Description
gateway/platforms/weixin.py	Fixes outbound media upload path and AES key encoding for WeChat client compatibility; updates image send API surface.
run_agent.py	Adds support for per-model max_tokens under custom_providers during agent initialization.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[poorld]

good

[moonaries90]

Great catch on the aes_key encoding — the round-trip test in the PR description was exactly the smoking gun I was chasing in my own debug pass last night.

One thing I ran into while testing this locally: the same signature mismatch exists in send_document (not just send_image_file), so non-image file sends still fail on main even with the fixes in this PR.

Repro: ask the bot to send a .md / .txt / .pdf. The gateway's auto-forward code in base.py:1677 calls:

media_result = await self.send_document(
    chat_id=event.source.chat_id,
    file_path=media_path,
    metadata=_thread_metadata,
)

but WeixinAdapter.send_document declares the argument as path, so it raises:

TypeError: WeixinAdapter.send_document() got an unexpected keyword argument 'file_path'

The minimal fix mirrors what you already did for send_image_file:

async def send_document(
    self,
    chat_id: str,
    path: Optional[str] = None,
    caption: str = "",
    file_path: Optional[str] = None,
    metadata: Optional[Dict[str, Any]] = None,
) -> SendResult:
    if not self._session or not self._token:
        return SendResult(success=False, error="Not connected")
    target = path if path is not None else file_path
    if target is None:
        return SendResult(
            success=False,
            error="send_document requires 'file_path' (or legacy 'path')",
        )
    try:
        message_id = await self._send_file(chat_id, target, caption)
        return SendResult(success=True, message_id=message_id)
    except Exception as exc:
        logger.error(
            "[%s] send_document failed to=%s: %s",
            self.name, _safe_id(chat_id), exc,
        )
        return SendResult(success=False, error=str(exc))

Happy to either fold this into your PR or open a small follow-up after this one lands — whichever is easier for the maintainers.

[longsizhuo]

Thanks @moonaries90 — nice catch. Verified locally that WeixinAdapter.send_document does raise TypeError: got an unexpected keyword argument 'file_path' when called via the auto-forward path in gateway/platforms/base.py:1676, and that every other platform adapter (base + 12 others) already uses file_path. So this is a strict Weixin-side inconsistency.

Folded the fix into this PR in ee3f32d1, with you as co-author. I took the signature a bit further than your snippet to fully match the base class — the new signature accepts file_path, file_name, reply_to, metadata, and trailing **kwargs, while still honoring a legacy path= kwarg for backwards compat. Empty calls now return a clear SendResult error instead of blowing up inside _send_file.

Checked that no internal caller passes path= as a kwarg (only positional or file_path=), so the rename is safe.

[bennywan]

Validated this against a real Weixin/iLink personal-account setup and a real WeChat client.

I reproduced three separate outbound attachment problems on current main:

1. WeixinAdapter.send_document / send_image_file signature mismatch with the base gateway call sites

   • generic media delivery passes file_path / image_path
   • Weixin adapter still accepted path
   • this caused:
     TypeError: WeixinAdapter.send_document() got an unexpected keyword argument 'file_path'

2. upload_full_url branch used the wrong HTTP method

   • PUT returned 404 from the CDN
   • POST succeeded

3. aes_key encoding in outbound media payload was not compatible with the WeChat client

   • after fixing send/signature + upload method, the file bubble could be delivered
   • but the attachment stayed stuck downloading / could not open
   • after switching aes_key to base64(hex-string-bytes), download and open both worked correctly

After applying those fixes together, I verified end-to-end that a bot-sent document attachment:

• is delivered to WeChat
• downloads successfully
• opens successfully in the client

So from a real-user validation standpoint, this PR fixes not only grey image / media issues, but also practical document attachment usability on Weixin.

[longsizhuo]

@teknium1 Hey, just a heads-up on this one:

1. CI is waiting on first-time contributor approval: the 3 workflows need a manual approve before they can run. Would appreciate it if you could unblock those when you get a chance.

2. Independent validation: @bennywan tested end-to-end on a real iLink personal account and confirmed all three fixes work (signature mismatch, POST vs PUT, aes_key encoding). See his comment above.

3. Related fix(weixin): update parameter names for image and document senders #8144: looks like @Astral-Yang also opened a PR addressing the parameter naming issue, which shows this is a real pain point for Weixin users. There's some overlap, happy to coordinate however works best for you.

No rush, just flagging so it doesn't get buried. Thanks!

[teknium1]

Merged via PR #8665 which synthesizes the best fixes from ~25 community PRs into a single consolidated change. Your contribution (aes_key encoding + upload_full_url CDN path fix) was reviewed and informed the final implementation. Thank you @longsizhuo for your work on this!