Fix inbound file handling and add cross-container file exchange

[lundog]

Why

Makes SimpleX file transfer reliable in external mode, including the common case where the simplex-chat runtime runs in a container (a filesystem OpenClaw doesn't share) while OpenClaw runs on the host or in its own container. It's transport-agnostic — no native-mode code — and everything is additive and backward compatible (unset config = today's behavior).

This is the file-exchange half of the earlier native-mode PR, split out per that PR's discussion so it can be reviewed and land on its own. A native-transport PR follows, stacked on top of this branch.

What

Inbound

• Fix a file-receive race: queue the pending file and retry the accept on rcvFileDescrReady, cancelling on timeout — a not-yet-ready XFTP descriptor no longer drops the file.
• Stage received files into OpenClaw's media/inbound store so media tools and sandboxed workspaces can read them.
• Resolve relative inbound paths against a new connection.filesFolder (default ~/.simplex/files, matching the bundled runtime service). When the runtime runs with --files-folder it reports a bare file name, which is joined to filesFolder; without it, the runtime reports absolute paths and they're read directly.
• Log the reported inbound path (absolute vs. relative) for diagnosability.

Outbound

• Add connection.outboundFolder. When set, outbound media is staged there before sending, and the staged path — valid on the runtime's side — is what travels over the WebSocket. Staged files are reclaimed by a short-lived per-file timer after staging — not on the send path, since the runtime reads and uploads the file asynchronously after the send call returns, so deleting eagerly could race that read. Unset = the local path is passed as-is (single-filesystem default).
• Add connection.outboundFolderOnClient for split-path deployments where the two sides mount the shared directory at different paths: the plugin stages into outboundFolder but rewrites the directory prefix to this before sending, so no verbatim/matching path is required. No effect without outboundFolder.
• Resolve media://<subdir>/<id> store references to a physical path on send (e.g. re-sending a received file).

Housekeeping

• Bump ws to ^8.21.0 (dependency-audit fix).
• Consolidate the expandHome helper (was copy-pasted in four modules) into a single src/fs-paths.ts.

Config connection gains filesFolder, outboundFolder, and outboundFolderOnClient (types, Zod schema, regenerated manifest). Adds unit tests for inbound resolution, outbound staging + timer-based reaping (fake timers), the readable-path guard, and media reference handling; documents the settings in the config reference and the runtime-setup guide (symmetric inbound/outbound sections).

Compatibility

Additive and backward compatible: existing configs are unaffected, and with filesFolder/outboundFolder unset the plugin behaves exactly as before.

Testing

Validated end-to-end against a containerized simplex-chat runtime with OpenClaw on the host, sharing an inbound volume and a non-verbatim outbound mount (the two sides mount the shared directory at different paths, bridged by outboundFolderOnClient):

• Inbound: received files from a mobile client — reported name-only, resolved against filesFolder, staged into media/inbound.
• Outbound: the bot sent files sourced three ways — a local path, a media:// store reference, and an http(s) URL — each staged into the shared outbound dir, path-translated to the runtime's view, and delivered. Observed the runtime copy the source into its --temp-folder (an xftp-prefixed dir) within seconds and then remove it, confirming the source is safe to reclaim well before the TTL.
• tsc, biome, and vitest all green.

[dangoldbj]

@lundog LGTM! 🚀 Thanks for opening this PR.

Heads up, these all depend on each other so they need to go in together, roughly in this order:

• add the new src/fs-paths.ts file first
• then apply the inline suggestions
• then fold in the two existing expandHome copies.

New file: src/fs-paths.ts

Create a new file which is just a single home for expandHome, which right now is copy-pasted in four places:

import os from "node:os";
import path from "node:path";

/**
 * Expand a leading `~`, `~/`, or `~\` in a local path to the current user's home
 * directory. Only meaningful for OpenClaw-local paths, never apply it to a path
 * that is resolved on the runtime's side (e.g. `outboundFolderOnClient`).
 */
export function expandHome(value: string): string {
  if (value === "~") {
    return os.homedir();
  }
  if (value.startsWith("~/") || value.startsWith("~\\")) {
    return path.join(os.homedir(), value.slice(2));
  }
  return value;
}

Remove expandHome copies

• src/simplex/runtime/db-path.ts: delete the local function expandHome and add import { expandHome } from "../../fs-paths.js";
• src/cli/runtime-service.ts: delete the local function expandHome and add import { expandHome } from "../fs-paths.js";. The shared version also handles a bare ~ and ~\, which this copy didn't, so it's a small upgrade.

[lundog]

Thank you for all your help on this. I’m sorry I haven’t had time to follow up, I was away for a few days. I will get to work on the things you mentioned in the next few days.

[dangoldbj]

@lundog LGTM! Thanks!