Use decoupled way for backend client

docs/backend_integration.md

@@ -0,0 +1,47 @@
+# 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`
+- `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.
+
+## Architecture
+
+- Ports: `core/ports/backend.py`
+- Adapters: `app/backend_adapters.py`
+- Compatibility wrappers: `app/backend_client.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`