# Backend Integration and History Bridge

This engine uses adapter-based backend integration so core runtime logic can run
with or without an external backend service.

## Runtime Modes

Configure with environment variables:

- `BACKEND_MODE=auto|http|disabled`
- `BACKEND_URL`
- `BACKEND_TIMEOUT_SEC`
- `ASSISTANT_LOCAL_CONFIG_DIR` (default: `engine/config/agents`)
- `HISTORY_ENABLED=true|false`

Mode behavior:

- `auto`: use HTTP backend adapter only when `BACKEND_URL` is set.
- `http`: force HTTP backend adapter (falls back to null adapter when URL is missing).
- `disabled`: force null adapter and run engine-only.

Assistant config source behavior:

- If `BACKEND_URL` exists and backend mode is enabled, fetch assistant config from backend.
- If `BACKEND_URL` is missing (or backend mode is disabled), load assistant config from local YAML.
- `assistant_id` query parameter is still required and maps to `engine/config/agents/<assistant_id>.yaml` when local YAML source is active.

## Architecture

- Ports: `core/ports/control_plane.py`
- Adapters: `app/backend_adapters.py`

`Session` and `DuplexPipeline` receive backend capabilities via injected adapter
methods instead of hard-coding backend client imports.

## Async History Writes

Session history persistence is handled by `core/history_bridge.py`.

Design:

- transcript writes are queued with `put_nowait` (non-blocking turn path)
- background worker drains queue
- failed writes retry with exponential backoff
- finalize waits briefly for queue drain before sending call finalize
- finalize is idempotent

Related settings:

- `HISTORY_QUEUE_MAX_SIZE`
- `HISTORY_RETRY_MAX_ATTEMPTS`
- `HISTORY_RETRY_BACKOFF_SEC`
- `HISTORY_FINALIZE_DRAIN_TIMEOUT_SEC`