Add native in-process SimpleX transport (mode: "native")

[lundog]

Note / correction to an earlier draft: a previous version of this
description implied mode: "external" was on a deprecated path. That was my
misreading of SimpleX's announcement. What's deprecated is the standalone
@simplex-chat/webrtc-client
TypeScript WebSocket client library — not the simplex-chat CLI's
WebSocket-server mode (-p) that external mode relies on, which remains fully
supported (and which this plugin talks to via its own ws client, not that
library). Nothing here deprecates or changes external mode or the sidecar/service
architecture. Native is purely an additive, opt-in alternative transport.

Scope / happy to split: the inbound-file fixes below (file-receive race,
media/inbound staging, and --files-folder path resolution via
connection.filesFolder) are transport-agnostic and improve external mode too.
If you'd rather evaluate native on its own, I'm glad to pull those into a
separate PR so they can land independently.

Why

SimpleX now ships a native simplex-chat
Node.js library that embeds the SimpleX core in-process — an alternative to
running the CLI as a separate WebSocket service. This PR exposes that embedded
core as an opt-in transport (mode: "native") for operators who'd rather
not run a sidecar, while leaving the existing external WebSocket-runtime mode
completely unchanged and fully supported.

The win for that use case: a bot can run with no sidecar — no
separately-managed simplex-chat process, no Docker/systemd, no wsUrl. Set
mode: "native" and the plugin runs the core itself. For anyone happy with the
service/sidecar setup, nothing changes — this only adds a second option behind a
flag.

What's included

• Native transport (mode: "native") — embedded simplex-chat core; speaks
  the same command/event protocol as the WS runtime, so everything above the
  transport layer is unchanged.
• Clean transport seam — extracted a SimplexTransport interface;
  SimplexWsClient (external) and new SimplexCoreClient (native) both
  implement it; SimplexClient selects by mode. External mode is
  byte-for-byte unchanged.
• AGPL isolation — simplex-chat is not a dependency of the plugin. It
  is installed manually, and loaded lazily at runtime via dynamic import.
  Default and external-mode installs stay pure-JS/MIT and never fetch it.
• Additive config — connection.mode gains "native", plus db
  (filePrefix/encryptionKey), profile
  (displayName/fullName/image/peerType), addressSettings
  (autoAccept/welcomeMessage/businessAddress), servers (smp/xftp),
  and filesFolder (external mode — see Inbound file fixes below). Backward
  compatible; manifest regenerated.
• Custom SMP/XFTP servers (native) — connection.servers.smp/.xftp route
  the embedded core over specific servers instead of the presets (applied via
  the core's /smp//xftp commands, space-separated). A rejected configuration
  fails startup rather than silently falling back to the defaults, since
  selecting custom servers means opting out of the presets. Verified end-to-end
  against a self-hosted SMP server.
• Zero-config DB path — defaults to
  <OPENCLAW_STATE_DIR|~/.openclaw>/simplex/<accountId>, per-account.
• Bot profile management — account-level display name / avatar / peer type,
  reconciled on connect; avatar auto-downscaled to a small JPEG (with the
  image/jpg media type SimpleX requires); address auto-created with welcome
  message + auto-accept, also reconciled on change.
• Safety guards — a single embedded core per account (refuses to open a
  second connection to the same SQLite, e.g. from a CLI/probe), and a startup
  check rejecting two native accounts that share a db.filePrefix.
• Native-aware CLI — the openclaw simplex … commands (invite, address,
  requests, groups, files, connect, runtime) transparently dispatch to the
  running gateway in native mode (so they reach the in-process core) with the
  same terminal QR/output; external behavior untouched.
• Operational visibility — startup logs the resolved profile and the bot's
  connection link.
• Inbound file fixes (transport-agnostic) — fixes a file-receive race and
  stages received media into OpenClaw's media/inbound store. Received files are
  located correctly across deployments: absolute paths (no --files-folder;
  native core) are read directly, while a runtime started with --files-folder
  reports names only and they are resolved against connection.filesFolder
  (default ~/.simplex/files) — which also bridges a shared volume mounted at
  different paths across separate sidecar/OpenClaw containers. A startup
  diagnostic logs each reported path (absolute vs. relative).
• Tests & docs — unit tests for the transport guard, core
  lifecycle/profile/address reconcile, account defaults and duplicate-prefix
  guard; a native-setup guide covering config, profile, address settings, and
  a DB-durability/reset runbook.

Compatibility & licensing

• Backward compatible: existing mode: "external" configs are unaffected;
  the native fields are additive.
• Licensing: simplex-chat is AGPL-3.0 while this plugin is MIT. It is
  not declared as a dependency, so default and external-mode installs never
  fetch it; enabling native mode is an explicit operator opt-in
  (npm install simplex-chat in the plugin's project). Whether to
  document/endorse that opt-in AGPL path is ultimately a maintainer decision.

Testing

Validated end-to-end on macOS and a StartOS (containerized) deployment:

• Native mode: connect, send/receive, avatar, welcome message, auto-accept +
  manual contact-request approval, and business-address (group) connections.
• Custom SMP/XFTP servers: applied to the embedded core against a
  self-hosted SMP server and verified inbound + outbound; confirmed a malformed
  server URI fails startup (no silent fallback to presets).
• Inbound files: verified across deployments —
  • external sidecar without --files-folder → absolute path (Downloads on
    macOS, /tmp in containers), read directly;
  • external sidecar with --files-folder → name-only path resolved against
    connection.filesFolder, including a shared Docker volume mounted at
    different paths in the sidecar and OpenClaw containers;
  • native on StartOS → absolute /tmp path, read directly.
• tsc, biome, and vitest all green.

Co-Authored-By: Claude Opus 4.8

[lundog]

Hi @dangoldbj, I bumped ws from 8.20.0 to 8.21.0 to fix the vulnerability scan. Thanks for taking a look at this!

[lundog]

Quick correction on my earlier framing: I'd implied mode: "external" was on a deprecated path — that was my misreading of the SimpleX announcement. What's deprecated is only the standalone @simplex-chat/webrtc-client TypeScript WS client library, not the simplex-chat CLI's -p WebSocket-server mode that external mode uses (and which this plugin talks to via its own ws client). I've reworded the PR description accordingly. Native here is purely additive/opt-in — it doesn't touch the external transport or the service architecture you've built.

Also, to keep this respectful of how you've scoped the project: the inbound-file fixes in this PR — the file-receive race fix, staging received media into media/inbound, and resolving --files-folder paths via the new connection.filesFolder — are transport-agnostic and improve external mode on their own. If you'd rather evaluate native mode separately (or not at all), I'm happy to split those fixes into their own PR so they can land independently.

[lundog]

Closing to split.