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

> 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:

- **Python** — [`@bellona-remote`](../../libs/bellona/sdk-python) (TODO 180.C.29.05)
- **TypeScript** — [`@oshun/bellona-client` → `/remote`](../../libs/bellona/client/src/remote) (TODO 180.C.29.04)

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`](python/blender_create_render_export.py) | [`typescript/blender-create-render-export.ts`](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`](python/unreal_import_place_capture.py) | [`typescript/unreal-import-place-capture.ts`](typescript/unreal-import-place-capture.ts) |
| 3 | **Browser** production-board update (launch, navigate, DOM click/type/submit, screenshot) | [`python/browser_production_board.py`](python/browser_production_board.py) | [`typescript/browser-production-board.ts`](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`](python/cloud_agent_control.py) | [`typescript/cloud-agent-control.ts`](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`](python/desktop_dialog_fallback.py) | [`typescript/desktop-dialog-fallback.ts`](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
```
