Eve library

Bellona Remote Creative Control Plane — end-to-end examples

Other

Revision 1

On this page

TODO 180.C.29.07 — runnable examples driving the remote gateway through the Bellona remote SDKs.

These examples drive a remote creative host (Blender / Unreal / a managed browser / a desktop) through the Bellona remote gateway (apps/bellona/remote-gateway) using the typed SDKs:

Each example is a real script: it builds validated command envelopes (the SDK enforces the protocol's id-format / command-name / risk / approval / rollback / dry-run invariants client-side, mirrored from @bellona/remote-protocol) and submits them to the gateway's REST API (/v1/sessions, /v1/commands, /v1/artifacts, /v1/approvals, /v1/timeline, …). None of them fabricate a result: where a step needs a live Blender / Unreal / Mac host that is not on this box, the script is still correct and would run against a live host — it documents the prerequisite honestly and fails loud (e.g. a gateway 409 "no connected host") rather than pretending the work happened.

The five flows#

# Flow Python TypeScript
1 Blender create → render → export (+ fetch & verify the artifact) python/blender_create_render_export.py typescript/blender-create-render-export.ts
2 Unreal import → place → capture (map create, asset transfer, spawn + transform, world query, save) python/unreal_import_place_capture.py typescript/unreal-import-place-capture.ts
3 Browser production-board update (launch, navigate, DOM click/type/submit, screenshot) python/browser_production_board.py typescript/browser-production-board.ts
4 Cloud-agent control — drive a session via the cloud-gateway tunnel as an orchestrator agent (operator→agent delegation chain) python/cloud_agent_control.py typescript/cloud-agent-control.ts
5 Desktop fallback dialog handling — drive a native OS dialog with privileged desktop.* commands + the human-approval gate python/desktop_dialog_fallback.py typescript/desktop-dialog-fallback.ts

Running the Python examples#

The Python examples run here, with no live host, against an in-process DemoGatewayTransport (a labelled test double at the SDK's RemoteTransport seam — the same role as httpx.MockTransport in the SDK tests). The SDK code path (envelope construction + validation + result parsing) is exercised for real; only the gateway+host are simulated, and the simulation echoes the submitted command rather than inventing host work.

bash
# No live host needed (demo mode):
python3 examples/bellona-remote/python/blender_create_render_export.py --demo

# Against a real gateway + paired host:
python3 examples/bellona-remote/python/blender_create_render_export.py \
    --gateway http://localhost:4100 --host-token "bellona-host-token-v1.…"

The example code is byte-identical between demo and live — only the transport differs (--gateway builds a real httpx client; --demo injects the double).

(The SDK is added to sys.path automatically from the repo checkout; for an installed SDK, cd libs/bellona/sdk-python && poetry install first.)

Running the TypeScript examples#

The TS examples talk to a real gateway over HTTP (the 29.04 SDK's HttpRemoteTransport). They require a running gateway and a paired host; supply the URL + host token via env vars:

bash
BELLONA_GATEWAY_URL=http://localhost:4100 \
BELLONA_HOST_TOKEN="bellona-host-token-v1.…" \
npx tsx examples/bellona-remote/typescript/blender-create-render-export.ts

Without a connected host the gateway rejects the command (HTTP 409) and the script prints a clean ✗ gateway error and exits non-zero — it does not fabricate success.

What each example needs#

Flow Live prerequisite (beyond the gateway)
1 Blender a paired host running Blender + the Bellona host app / Blender adapter
2 Unreal a paired host running Unreal Editor 5.x with the Bellona Unreal adapter / Remote Control enabled
3 Browser a paired host with the Bellona browser adapter + a managed Chromium
4 Cloud-agent a host paired in cloud-gateway network mode (reachable over the relay tunnel)
5 Desktop a paired host with the desktop adapter + macOS Accessibility / Screen-Recording (or Windows UIA) permissions, and a human approver for the privileged commands

Verifying the examples#

bash
# Python: every example compiles and runs in demo mode.
python3 -m py_compile examples/bellona-remote/python/*.py
for f in examples/bellona-remote/python/*_*.py; do python3 "$f" --demo; done

# TypeScript: every example typechecks against the real SDK types.
cd examples/bellona-remote/typescript && npx tsc --noEmit -p tsconfig.json