iii-bridge

name	iii-bridge
description	Connect this engine to another iii engine over a long-lived WebSocket so functions call across the boundary. Wire stable ids with `forward:`/`expose:`; `bridge.invoke` is the ad-hoc escape hatch.

iii-bridge

The iii-bridge worker connects this iii engine to another iii instance over iii-sdk so functions on either side can call across the boundary. It opens a single outbound WebSocket to the configured url, registers with the remote using service_id, and stays open for the engine's lifetime — bridging is request/response over that long-lived connection. There are no trigger types.

The worker is configuration-driven. The primary surface is two list-shaped config fields (forward: and expose:) that wire stable function ids on both sides; once configured, callers reach across the bridge by invoking those stable ids with the normal iii.trigger({ function_id, payload }) — no bridge-specific call shape. Two functions (bridge.invoke, bridge.invoke_async) are also registered as ad-hoc escape hatches for the rare case where the remote function id is dynamic at runtime.

When to Use

• Two iii engines need to call each other's functions over a stable, long-lived connection.
• You want a remote function to appear as a local id (forward:) so the bridge is invisible at the call site.
• You want to expose specific local functions to a remote engine (expose:).
• The remote function id is dynamic, or you are prototyping / probing connectivity — reach for the ad-hoc bridge.invoke functions.

Boundaries

• Prefer forward: / expose: aliases over bridge.invoke; the escape hatches are for dynamic ids and one-offs, not the default path.
• bridge.invoke_async is fire-and-forget — it ignores timeout_ms, returns no value, and a later remote rejection is logged but never surfaced to the caller.
• Forward aliases and exposed ids are operator-wired per deployment in iii-config.yaml; they are not stable across deployments and are documented alongside the worker config, not here.
• Failures return a FunctionResult::Failure with a stable code (deserialization_error or bridge_error); a successful async return only means the message was queued, not that the remote ran.

Functions

• bridge.invoke — call a remote function_id and wait for its return value (returned directly, no envelope); honors an optional timeout_ms (default 30000).
• bridge.invoke_async — hand a remote call to the WebSocket send queue and return immediately; timeout_ms is ignored and no remote response is surfaced.

Both take { function_id, data?, timeout_ms? }. Reach for them only when a forward: alias is wrong or impossible; for repeated calls to the same (local, remote) pair, configure a forward: alias and call the local id instead.

Configuration

• url — WebSocket URL of the remote iii instance (default ${III_URL:ws://0.0.0.0:49134}).
• service_id / service_name — identifier (and human-readable name) registered with the remote.
• expose: [{ local_function, remote_function? }] — functions on this engine the remote may call; remote_function is the path the remote invokes (defaults to local_function). Registered with the remote at initialize time.
• forward: [{ local_function, remote_function, timeout_ms? }] — local aliases that proxy outbound to a remote function. The worker registers local_function on this engine so any caller reaches the remote's remote_function; timeout_ms overrides the per-call deadline (default 30000).