Skip to content

ADR 0010 — AI assistant architecture

Accepted · active development · 2026-02-04

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.

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 channels ai:chat:chunk:<id> / ai:chat:end:<id> → electron/main/ai-handler.ts → shared/protocol/ai/ai-proxy.ts. The renderer’s streamConsumer.ts must subscribe to the chunk channel before invoking chat, or it drops the first tokens.
  • Provider-agnostic core — ai-proxy.ts orchestrates and emits raw SSE bytes downstream. Per-provider wire shapes live in provider-routes.ts; decoders in providers/{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) and redaction.ts scrubs 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/ai Worker 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.ts captures the full request URL (scheme, host, path, query) and promptBuilder.ts sends it as written. Nothing replaces the host.
  • In default mode, promptBuilder.ts replaces 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.ts masks 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.

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.