Fix inbound media handling, file-receive race, and add shared-directory support

[lundog]

Fix inbound media handling, file-receive race, and add shared-directory support

Summary

Inbound files were not fully usable by the agent: received media never reached OpenClaw's shared media store, the initial /freceive raced the XFTP file description and caused messages to dispatch without their attachment, and media:// references produced by the agent couldn't be sent back out. This PR fixes those, and adds an opt-in pair of config keys for deployments where OpenClaw and simplex-chat don't share a filesystem.

1. Comply with OpenClaw media requirements

Stage inbound files into the shared media store. The plugin passed the raw path from the SimpleX runtime directly into the inbound context as MediaPath/MediaUrl. Files outside ~/.openclaw/media/ are rejected by the image tool and invisible to sandboxed workspaces, so attachments failed with errors like:

[tools] image failed: Local media file not found: /Users/.../workspace/IMG_x.jpg

finalizePendingFile() now reads the received file and stages it via core.channel.media.saveMediaBuffer(buffer, mime, "inbound", maxBytes, fileName) — the same pattern as other bundled channels — and passes the saved store path into the context. If staging fails, it logs and falls back to the raw path.

Resolve relative paths from the WS API. rcvFileComplete reports fileSource.filePath relative to the runtime's --files-folder (typically just the bare file name, e.g. "IMG_x.jpg"). The plugin now resolves relative paths against the new files.inboundDir setting, defaulting to /tmp — where simplex-chat saves files when started without --files-folder.

Follow the inbound context envelope. Added MediaPaths (array form) alongside MediaPath, and the original fileName from the chat item is now used when saving (MIME/extension fallback).

Resolve media:// references on send. When the agent echoes an attachment back (e.g. "send me that file"), it passes media://inbound/<id> as mediaUrl. The plugin treated this as a literal filesystem path:

ENOENT: no such file or directory, copyfile 'media://inbound/IMG_x---<uuid>.jpg' -> ...

resolveMediaPath() now resolves media://<subdir>/<id> to its physical path via the SDK's resolveMediaBufferPath() (the documented read-side counterpart to saveMediaBuffer, with built-in path-traversal protection) before the normal local-path flow.

2. Fix the inbound file receive race

The plugin issued /freceive immediately on newChatItems, but for XFTP transfers the file description usually isn't ready yet, so the accept fails (SimpleX receive file failed: Error: IMG_x.jpg). Because the pending file was only queued after a successful accept, this had two compounding effects: the message dispatched immediately with no media, and when the retry on rcvFileDescrReady did download the file, the rcvFileComplete path was dropped because nothing was queued.

Now:

• The pending file is queued before the first accept attempt; an early failure is tolerated.
• rcvFileDescrReady retries the accept, but only for queued files not yet accepted (shouldRetryFileAccept/markFileAccepted) — previously it accepted unconditionally, including files skipped as oversize.
• Dispatch happens on rcvFileComplete with the actual downloaded path. The existing 90s pending-file timeout still dispatches without media (and cancels the transfer) if the download never completes.

3. Optional shared-directory support (cross-container deployments)

When OpenClaw and simplex-chat run in separate containers (or otherwise don't share a filesystem), local paths on one side are meaningless on the other. Two new optional keys under the channel (or per-account) config make file exchange work across a shared directory/volume:

"files": {
  "inboundDir": "/path/simplex/saves/received/files/to",
  "outboundDir": "/path/both/sides/can/access"
}

• inboundDir — the runtime's --files-folder; used to resolve the relative paths from §1 (defaults to /tmp).
• outboundDir — when set, outbound media (fetched remote URLs, media:// references, and local files simplex-chat can't read) is staged into this directory with UUID-prefixed names before the send command is issued, so the fileSource.filePath passed to simplex-chat is readable by it. Staged files are tracked and deleted after the send completes; only files this plugin staged are ever deleted.

With both keys unset, behavior is unchanged apart from the bug fixes above — single-filesystem deployments need no configuration.

Testing

• pnpm typecheck, pnpm check (biome), and pnpm vitest run (151 tests, including a new test for the accept-retry tracking) all pass.
• openclaw.plugin.json regenerated via pnpm manifest:sync.
• Manually verified end-to-end on a deployment with simplex-chat in a separate container sharing a mounted volume: image receive → agent image tool reads the staged store file; agent echo round-trip (media://inbound/<id> → staged to the shared dir → sent → cleaned up); plus outbound remote-URL media.