skip to content
iii / worker
$worker

bridge

v0.1.3

Bridge two iii engines — expose local functions on a remote engine and invoke/forward remote functions locally.

iiiverified
14 installs0 in 7d0 today
install
$iii worker add bridge@0.1.3
binarybridgeremotewebsocketfederationengine
  • macOS: arm64 · x64
  • Linux: arm64 · armv7 · x64
  • Windows: arm64 · x64 · x86
3functions0triggers1skills1depsv0.1.3version
repoiii-hq/workers

exact versions are immutable; binary and bundle artifacts are digest-pinned.

agent-ready brief for v0.1.3
install + config + dependencies + readme + api reference, all in one place. fetch as agent-context.md for an llm to consume.

full markdown

open as agent-context.md
the same content rendered as discrete blocks below is exposed as a single markdown document at /workers/bridge.md?version=0.1.3. paste it into an llm prompt or pipe it through curl from a worker.

install

install
$iii worker add bridge@0.1.3

configuration

iii-config.yaml
- expose:

  forward:

  url: ws://0.0.0.0:49134

dependencies

dependencies1
configuration^0.19.0

readme

README.md

bridge

Connects a local iii engine to a remote iii instance over a long-lived iii-sdk WebSocket connection so functions on either side can call across the boundary. expose entries make a local function callable from the remote engine; forward/invoke entries make a remote function callable from this engine. There are no trigger types.

Install

iii worker add bridge

iii worker add fetches the binary, writes a config block into ~/.iii/config.yaml, and the engine starts the worker on the next iii start.

Function surface

Function Input Output
bridge.invoke { function_id, data?, timeout_ms? } remote function's return value, waits up to timeout_ms (default 30000)
bridge.invoke_async { function_id, data?, timeout_ms? } null, immediately — fire-and-forget; timeout_ms is ignored
forward entry (local_function) whatever the remote remote_function expects remote function's return value, waits up to the entry's timeout_ms (default 30000)
expose entry (registered on the remote, name defaults to local_function) whatever the local local_function expects local function's return value; a local failure's real code/message/stacktrace is forwarded untouched

bridge.invoke/bridge.invoke_async/forward calls collapse any remote-side failure to code: "bridge_error" — the underlying remote error code is never surfaced through those three paths. A malformed bridge.invoke* input (missing function_id) fails with code: "deserialization_error" instead.

Configuration

Configuration is owned by the configuration worker — edit it from the console (Configuration → Workers → bridge) or seed it once via --config .yaml on first boot:

Field Default Description
url ws://0.0.0.0:49134 Remote engine WebSocket URL. Fallback chain: config.url → III_URL env var → the default above.
expose[] [] { local_function, remote_function? } — local functions the remote engine may call; remote_function is the name registered on the remote (defaults to local_function).
forward[] [] { local_function, remote_function, timeout_ms? } — local aliases that proxy outbound to a remote function; timeout_ms overrides the per-call default (30000).

Hot-reload semantics: a url change connects a new remote client, re-registers every expose entry on it, then swaps it in and gracefully shuts the old client down — no restart needed. An unchanged url with new expose/forward entries registers just the additions live. Removing a forward/expose entry does not un-register its handler — the SDK has no unregister — so the function id stays live but its handler returns bridge_error until the worker is restarted.

Requires removing the built-in iii-bridge worker

The built-in iii-bridge worker registers the same function ids (bridge.invoke, bridge.invoke_async, plus any configured forward/expose names). Two workers registering the same function id on one engine collide — whichever registers last wins — so this worker requires iii-bridge to be absent: omit it from the engine's config.yaml (a config that doesn't list a worker won't run it). This is a duplicate-function-id collision, not a trigger type conflict — bridge registers no trigger types.

On boot, this worker queries the engine for connected workers and refuses to start with a clear error if iii-bridge is still active, so a stale config fails loudly instead of silently racing the built-in worker for ownership of bridge.invoke/bridge.invoke_async.

The engine's own state/queue/stream/configuration bridge adapters are unaffected by this worker or by removing iii-bridge: those adapters open their own direct SDK connections to bridge engine-internal subsystems and never depended on the iii-bridge worker.

Parity vs builtin

Behavior Builtin This worker
bridge.invoke / bridge.invoke_async exact paths, codes deserialization_error/bridge_error same
Default timeout 30s (timeout_ms overrides) same
invoke_async result NoResult (absent) null (SDK functions must return a value)
Forward functions one local function per entry, description Forward to remote function {id} same
Expose functions registered on the remote engine, name defaults to local, real error body forwarded same
Remote URL config.url → III_URL env → ws://0.0.0.0:49134 same
Trigger types none none
Config source engine config.yaml (restart to change) configuration worker entry bridge, hot-reload
Removing forward/expose entries restart re-registers cleanly entry disabled (handler errors); full removal needs worker restart

api reference (json)

agent-api-reference.json
{
  "functions": [
    {
      "description": "Invoke a function on the remote III instance",
      "metadata": {},
      "name": "bridge.invoke",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "description": "Exact parity with the builtin's `InvokeInput` (mod.rs:50-57).",
        "properties": {
          "data": {
            "default": null,
            "description": "Payload passed to the remote function, forwarded verbatim."
          },
          "function_id": {
            "description": "Id of the function to invoke on the remote iii instance.",
            "type": "string"
          },
          "timeout_ms": {
            "default": null,
            "description": "Milliseconds to wait for the result. `bridge.invoke` defaults to 30s when omitted; `bridge.invoke_async` ignores this field (fire-and-forget).",
            "format": "uint64",
            "minimum": 0,
            "type": [
              "integer",
              "null"
            ]
          }
        },
        "required": [
          "function_id"
        ],
        "title": "InvokeInput",
        "type": "object"
      },
      "response_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "description": "Raw JSON value returned or forwarded without validation.",
        "title": "RawValue",
        "type": [
          "null",
          "boolean",
          "number",
          "string",
          "array",
          "object"
        ]
      }
    },
    {
      "description": "Fire-and-forget invoke on the remote III instance",
      "metadata": {},
      "name": "bridge.invoke_async",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "description": "Exact parity with the builtin's `InvokeInput` (mod.rs:50-57).",
        "properties": {
          "data": {
            "default": null,
            "description": "Payload passed to the remote function, forwarded verbatim."
          },
          "function_id": {
            "description": "Id of the function to invoke on the remote iii instance.",
            "type": "string"
          },
          "timeout_ms": {
            "default": null,
            "description": "Milliseconds to wait for the result. `bridge.invoke` defaults to 30s when omitted; `bridge.invoke_async` ignores this field (fire-and-forget).",
            "format": "uint64",
            "minimum": 0,
            "type": [
              "integer",
              "null"
            ]
          }
        },
        "required": [
          "function_id"
        ],
        "title": "InvokeInput",
        "type": "object"
      },
      "response_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "title": "NullResult",
        "type": "null"
      }
    },
    {
      "description": "Internal: reload bridge configuration from the authoritative store on change.",
      "metadata": {},
      "name": "bridge::on-config-change",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "title": "ConfigChangeRequest",
        "type": "object"
      },
      "response_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "properties": {
          "ok": {
            "type": "boolean"
          }
        },
        "required": [
          "ok"
        ],
        "title": "ConfigChangeAck",
        "type": "object"
      }
    }
  ],
  "triggers": []
}