2.2 KiB
2.2 KiB
ADR-0005: Real AstrBot OpenAPI adapter over internal Desktop protocol
Status
Accepted for foundation work on 2026-07-20.
Context
P00/P01 defined a provisional Desktop Gateway contract (/desktop/v1) and dual Mock Gateway. Live probe of AstrBot 4.26.x on http://192.168.31.210:26285 showed the real server exposes Dashboard/OpenAPI routes under /api and /api/v1, with request-scoped chat SSE from POST /api/v1/chat, API Key or Dashboard JWT auth, and no Desktop-native long-lived event bus, ACK, tool.proposal, or server-info endpoints.
Rewriting the whole Desktop application around raw AstrBot internal APIs would discard working dual-slot isolation, Mock tests, and security boundaries.
Decision
- Keep the provisional Desktop Gateway event model as the internal normalized contract.
- Add a Rust-owned AstrBot OpenAPI adapter that translates:
- Desktop chat send intent →
POST /api/v1/chat - AstrBot SSE frames → Desktop
GatewayEvent(message.delta,message.completed, heartbeat, error)
- Desktop chat send intent →
- Add
TransportKindon ConnectionProfile:desktop-v1for Mock/provisional gatewayastrbot-openapifor real AstrBot
- Store secrets only in Windows Credential Manager; React may submit one-shot enrollment IPC but never receives stored secrets.
- Use derived
server_instance_idsubstitute (astrbot-<hash(base_url)>) until a stronger identity enrollment flow is approved. - Keep operations tool proposals Desktop-local; do not invent a fake server proposal channel.
Consequences
Positive
- Real chat connectivity can proceed without discarding Mock-based dual-slot tests.
- Security boundaries remain Rust-owned.
- UI and local storage continue to reason about normalized events and slots.
Negative / costs
- Adapter must tolerate missing terminal SSE frames and synthesize completion.
- Capability/discovery surfaces differ by transport.
- Certificate pinning and JWT login remain open follow-ups.
Follow-ups
- Live dual-slot chat UI rendering and history persistence
- Dashboard JWT login path
- Attachment upload (
/api/v1/file) - Optional WS chat path
- Stronger server identity enrollment (PD-0011) and TLS fingerprint binding (PD-0012)