ADR 0010 — AI assistant architecture
Context
Section titled “Context”Restura ships a chat assistant that can read the current request/response context and talk to OpenAI, Anthropic, or OpenRouter (bring-your-own-key). Two constraints shape the design. First, the assistant must never leak secrets or full URLs to a third-party model — the same secret surface ADR 0007 protects. Second, the providers have different wire shapes and streaming formats, but the orchestration (build prompt, attach context, stream tokens, allow cancel) is identical across them.
Decision
Section titled “Decision”Make the AI path Electron-first and provider-agnostic, with the orchestrator in the shared layer.
- Transport — the renderer streams over the IPC bridge:
window.electron.ai→ai:chat/ai:chat:cancel, with per-call event channelsai:chat:chunk:<id>/ai:chat:end:<id>→electron/main/ai-handler.ts→shared/protocol/ai/ai-proxy.ts. The renderer’sstreamConsumer.tsmust subscribe to the chunk channel before invokingchat, or it drops the first tokens. - Provider-agnostic core —
ai-proxy.tsorchestrates and emits raw SSE bytes downstream. Per-provider wire shapes live inprovider-routes.ts; decoders inproviders/{openai,anthropic,openrouter}.ts, each paired with a fixture test. - Redaction — the renderer captures context via
lib/contextSnapshot.ts(method, path, protocol, redacted headers/body, response, active env name) andredaction.tsscrubs secrets (sensitive headers, body tokens, environment-variable values) before anything leaves the machine. The request URL is included as written; host redaction was part of the original design but was never implemented. - No
/api/aiWorker route exists yet. The web build is not wired through the proxy. Platform parity must be confirmed, not assumed — the main reason this feature is marked “active development.”
Amendment (2026-10-31): URL host redaction was never implemented
Section titled “Amendment (2026-10-31): URL host redaction was never implemented”The original Decision and Consequences said the context snapshot’s URLs are redacted. That was the design intent, but it was never built, and the user docs repeated the claim (issue #977); the Redaction bullet above and the matching Consequences bullet were corrected in place. What the code does:
contextSnapshot.tscaptures the full request URL (scheme, host, path, query) andpromptBuilder.tssends it as written. Nothing replaces the host.- In default mode,
promptBuilder.tsreplaces environment-variable values of 8+ characters with[REDACTED]wherever they appear in the URL, headers or bodies. The ENVIRONMENT block masks every value. shared/protocol/ai/redaction.tsmasks sensitive header names and token-shaped body values.- The composer’s Send raw (skip redaction) switch turns all of this off for one message.
So internal hostnames and URL paths reach the provider. The decision is otherwise unchanged.
Consequences
Section titled “Consequences”Positive
- Adding a provider is a decoder + fixture, not an orchestration rewrite.
- Secrets are redacted at the renderer boundary, so the main process and the provider never see them. URLs (including hostnames) are not redacted and are visible to the provider.
- Streaming + cancel reuse the same IPC event-channel pattern as the other streaming protocols.
Negative
- Web has no AI path today; the capability is desktop-only until a Worker route is added (recorded in the capability matrix).
- The “subscribe before invoke” ordering is an easy bug to reintroduce.
- BYOK means key-handling quality depends on each provider’s key storage path.
Related
Section titled “Related”- Source:
docs/adr/0010-ai-assistant-architecture.md - User guide: AI assistant.
- Related: ADR 0007, ADR 0012.