hermes - 💡(How to fix) Fix Feishu media uploads fail with urllib3-future HTTP/2 stream reset

Bug Description

Feishu/Lark image and file uploads can fail from the gateway with an HTTP/2 stream reset when the Python SDK upload path is backed by requests + urllib3-future.

The failing path is the native Feishu media upload flow in gateway/platforms/feishu.py:

• send_image_file() -> self._client.im.v1.image.create(...)
• _send_uploaded_file_message() -> self._client.im.v1.file.create(...)

Text messages continue to work. The failure is specific to multipart media uploads.

Steps to Reproduce

1. Configure the Feishu gateway and start it.
2. Use an environment where requests uses urllib3-future (observed urllib3==2.20.905, stack frames under urllib3/backend/hface.py).
3. Send a local image or file through Feishu, for example by returning a MEDIA:/path/to/image.png attachment from the agent or calling the adapter image/file send path.

Expected Behavior

The gateway uploads the image/file to Feishu IM storage, obtains an image_key/file_key, and sends the corresponding Feishu message.

Actual Behavior

The upload request fails before receiving a Feishu response. The gateway logs a requests.exceptions.ConnectionError caused by an HTTP/2 stream reset:

[Feishu] Failed to send image /root/cache/zimage-sdcpp/outputs/test_zimage_q3_512x512_seed43_notile.png: Stream 1 was reset by remote peer. Reason: 0x1.

Traceback (most recent call last):
  File "/root/.hermes/hermes-agent/venv/lib/python3.11/site-packages/requests/adapters.py", line 645, in send
    resp = conn.urlopen(
  File "/root/.hermes/hermes-agent/venv/lib/python3.11/site-packages/urllib3/connectionpool.py", line 1801, in urlopen
    response = self._make_request(
  File "/root/.hermes/hermes-agent/venv/lib/python3.11/site-packages/urllib3/connectionpool.py", line 1436, in _make_request
    response = conn.getresponse(
  File "/root/.hermes/hermes-agent/venv/lib/python3.11/site-packages/urllib3/backend/hface.py", line 1209, in __exchange_until
    raise ProtocolError(
urllib3.exceptions.ProtocolError: Stream 1 was reset by remote peer. Reason: 0x1.

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/root/.hermes/hermes-agent/gateway/platforms/feishu.py", line 2113, in send_image_file
    upload_response = await asyncio.to_thread(self._client.im.v1.image.create, request)
  File "/root/.hermes/hermes-agent/venv/lib/python3.11/site-packages/lark_oapi/api/im/v1/resource/image.py", line 36, in create
    resp: RawResponse = Transport.execute(self.config, request, option)
  File "/root/.hermes/hermes-agent/venv/lib/python3.11/site-packages/lark_oapi/core/http/transport.py", line 30, in execute
    response = requests.request(
requests.exceptions.ConnectionError: Stream 1 was reset by remote peer. Reason: 0x1.

The same pattern was observed for files:

File "/root/.hermes/hermes-agent/gateway/platforms/feishu.py", line 4265, in _send_uploaded_file_message
  upload_response = await asyncio.to_thread(self._client.im.v1.file.create, request)
File "/root/.hermes/hermes-agent/venv/lib/python3.11/site-packages/lark_oapi/api/im/v1/resource/file.py", line 36, in create
  resp: RawResponse = Transport.execute(self.config, request, option)
File "/root/.hermes/hermes-agent/venv/lib/python3.11/site-packages/lark_oapi/core/http/transport.py", line 30, in execute
  response = requests.request(
requests.exceptions.ConnectionError: Stream 1 was reset by remote peer. Reason: 0x1.

Environment

• OS: WSL2 Linux
• Hermes version: Hermes Agent v0.14.0 (2026.5.16)
• Local commit where reproduced: e3f391c1a
• Latest checked origin/main: b62af47da
• Python version: 3.11.15
• requests: 2.33.0
• urllib3: 2.20.905 (urllib3-future, stack includes urllib3/backend/hface.py)
• httpx: 0.28.1
• lark_oapi: installed, version attribute unavailable

Error Output

See stack trace above. Key indicator:

urllib3/backend/hface.py
urllib3.exceptions.ProtocolError: Stream 1 was reset by remote peer. Reason: 0x1.
requests.exceptions.ConnectionError: Stream 1 was reset by remote peer. Reason: 0x1.

Additional Context

A local workaround was tested successfully: upload images/files with raw Feishu OpenAPI calls using httpx.Client(http2=False, trust_env=False), then keep using the existing Feishu message send path with the returned image_key/file_key.

Tested raw HTTP/1.1 upload endpoints:

• POST /open-apis/auth/v3/tenant_access_token/internal
• POST /open-apis/im/v1/images
• POST /open-apis/im/v1/files

After forcing raw HTTP/1.1 for media uploads, both a ~567 KB PNG and a ~1.8 MB PNG were delivered successfully to Feishu.

Suggested fix direction:

• Either force the Feishu SDK/upload transport to HTTP/1.1 for multipart uploads, if possible; or
• Add a targeted raw HTTP/1.1 fallback for image.create/file.create when the SDK upload raises this stream reset error.

A config escape hatch may also be useful, e.g. platforms.feishu.extra.raw_http1_upload: true, for environments where the SDK path consistently negotiates a broken HTTP/2 upload path.