# Local Cloud-Agent Simulation

Status: Phase 180.C.14.06 reference procedure.

This document defines the local simulation used before Hetzner or AWS deployment
exists. It models a cloud agent as a separate local process that talks only to
the Bellona MCP gateway surface. The simulated agent must not connect to the
remote host, Blender, Chrome/CDP, desktop fallback helpers, or same-LAN host
ports directly.

## Topology

| Role                 | Local Simulation Process                        | Authority Boundary                         |
| -------------------- | ----------------------------------------------- | ------------------------------------------ |
| Cloud agent          | Any MCP-capable client process or test harness  | Calls MCP tools/resources only             |
| MCP gateway process  | `pnpm nx stdio @bellona/mcp-gateway`            | Auth/session binding plus MCP translation  |
| Remote Gateway state | In-process structural gateway wiring for now    | Device/session/command/audit authority     |
| Remote Host          | Existing fake/fixture host state for this stage | No direct connection from simulated agent  |
| Adapters             | Gateway-dispatched command targets only         | No direct LAN, CDP, Blender, or desktop IO |

The local simulation intentionally treats the MCP process as if it were a cloud
edge client. The only allowed command path is:

1. Cloud-agent MCP client.
2. Bellona MCP gateway tool/resource.
3. Bellona Remote Gateway structural boundary.
4. Gateway policy, approval, revocation, schema, session, command, and audit
   controls.
5. Host/adapters after gateway dispatch.

## Prerequisites

- `pnpm install` has already completed for the workspace.
- `pnpm nx test @bellona/mcp-gateway --skip-nx-cache --verbose` passes.
- The MCP gateway is configured with `remoteControlAuthSession.mode: "required"`
  for any remote/cloud transport.
- The simulated client receives an MCP `authInfo` payload with:
  - `resource` set to the MCP gateway resource identifier.
  - `clientId` for the cloud agent.
  - Required scopes for the action being tested.
  - Gateway-bound `participantId`, `sessionId`, and `allowedSessionIds`.

## Local Stdio Harness

The first-stage local harness is stdio because `180.C.14` has not yet added a
Streamable HTTP transport target. Use it to prove agent routing, tool/resource
shape, auth/session binding, and gateway failure behavior before cloud
deployment.

```sh
pnpm nx stdio @bellona/mcp-gateway
```

A separate MCP client process should connect to that stdio process and run this
minimal sequence:

```text
resources/list
resources/read bellona://remote-control/devices/active/capabilities
tools/call device.list
tools/call session.start
tools/call blender.scene.info
tools/call browser.navigate
tools/call desktop.screenshot
resources/read bellona://remote-control/commands/last-result
tools/call session.stop
```

For local automated proof, `libs/bellona/mcp-gateway` unit tests already
exercise this path over MCP SDK in-memory transports:

- `remote-control-tools.test.ts` proves tool registration, gateway dispatch, and
  auth-bound client/session propagation.
- `remote-control-resources.test.ts` proves resource listing and reads through
  gateway state methods.
- `remote-control-bypass.test.ts` proves schema failures and gateway
  policy/approval/revocation errors remain MCP tool errors.

## No Direct LAN Rule

During this simulation, the cloud-agent process must not:

- Open Blender localhost ports, Chrome/CDP ports, desktop fallback helpers, or
  host WebSocket connections directly.
- Use same-LAN host addresses or mDNS names.
- Read or write Remote Gateway persistent store files directly.
- Reuse host pairing or host-token credentials.
- Set `clientId` tool arguments to impersonate another MCP client.

The MCP gateway auth binding overrides tool-supplied `clientId` values when a
remote/cloud client is authenticated. A simulation that succeeds only by direct
LAN access is invalid for Phase 180.

## Expected Evidence

Record the following for a local cloud-agent simulation run:

- MCP server command line and commit SHA.
- Auth mode, resource audience, client id, participant id, and bound session id.
- `resources/list` output showing all four Phase 180 MCP resources.
- `tools/list` output showing all eight Phase 180 MCP tools.
- The session id returned by `session.start`.
- The command ids and idempotency keys returned by command dispatches.
- The last-result resource after at least one command result.
- The `session.stop` result.
- Confirmation that no direct LAN adapter endpoint was opened by the agent.

## Promotion Path

This local simulation is intentionally not the final cloud deployment. The next
items promote the same flow:

- `180.C.14.07`: Hetzner reference deployment notes.
- `180.C.14.08`: AWS reference deployment notes.
- `180.C.14.09`: Cloud-agent MVP smoke flow using the deployed gateway path.

The same no-direct-LAN rule remains in force for those stages.
