# Yuanxu × FunsClaw Windows bridge

This is the isolated integration boundary between the Yuanxu Windows Flutter
client and the existing FunsClaw Windows service. It does not copy or merge the
FunsClaw backend. The Flutter app exchanges its authenticated Yuanxu session
for a short-lived bridge token, then talks only to this bridge.

## Environment

- `FUNSCLAW_API_URL` (default `http://127.0.0.1:8080`)
- `FUNSCLAW_API_TOKEN` (permanent FunsClaw token; server-side only)
- `FUNSCLAW_CONFIG_PATH` (the active FunsClaw desktop YAML; used to list
  enabled models without making slow discovery calls to disabled providers)
- `BRIDGE_DB_PATH` (default `./data/funsclaw_bridge.sqlite3`)
- `BRIDGE_AUTO_GRANT_IMPORTED_AGENTS` (default `false`; only enable for isolated development fixtures. Production agents require platform-to-enterprise authorization.)
- `YUANXU_TLS_VERIFY` (`true` in production; `false` is only for a private IP lab)
- `BRIDGE_ALLOW_REMOTE_EXCHANGE` (`false` by default)

Never put a provider key or a permanent FunsClaw token in Flutter source,
bootstrap JSON, screenshots, logs, or this directory.

## Start

```powershell
python -m pip install -r requirements.txt
$env:FUNSCLAW_API_TOKEN = '<server-side token>'
$env:FUNSCLAW_CONFIG_PATH = 'D:\FunsClaw\config\local.yaml'
python -m uvicorn app:app --host 127.0.0.1 --port 18080
```

The desktop app uses `http://127.0.0.1:18080` only when the Yuanxu server has
not supplied a managed `tokenExchangePath` and `gatewayBaseUrl`.

## Implemented platform controls

- tenant/user isolated conversations and files;
- server-side agent import with immutable version snapshots;
- automatic model routing without a client model selector;
- enterprise wallet, ledger, request reservation and usage records;
- enterprise agent grants and employee agent grants;
- permission-gated conversation audit;
- message-level agent/version/model metadata;
- public agent metadata only: prompts, knowledge paths and provider secrets are
  never returned to Flutter.

The current local upstream FunsClaw chat credential still returns HTTP 401.
Until that credential is repaired, bridge and Flutter tests validate the
contract, isolation, routing and accounting paths, but do not prove a real
provider response or real desktop tool execution.
