ada-agent 0.2.0 → 0.3.0

package/docs/architecture.md

@@ -1,163 +1,163 @@
-# Architecture
-
-ada is two programs in one repo: a thin **client** (the coding agent) and a **backend** (the
-router that holds provider keys). They communicate in one wire format — OpenAI Chat Completions.
-
-![ada architecture](architecture.svg)
-
-```
- ada (client)                    ada backend                         upstream providers
- ────────────                    ───────────                         ──────────────────
- agentic loop  ──── HTTP  ───▶   auth (client key)
- tools                           router: model id → provider
- sessions                        adapter: provider → wire format ──▶  Anthropic / OpenAI / …
- approval/TUI   ◀── SSE  ────    normalize back to OpenAI SSE
-```
-
-Why split it: the backend is the **one control point**. Provider keys, auth, rate limits, and
-billing all belong in one place; the client carries only an ada client key. Same shape as Cursor.
-
-## Request flow
-
-1. The client sends an OpenAI-format chat request (model, messages, tools) to `ADA_BACKEND_URL`
-   with its client key as the bearer.
-2. The backend authenticates the key (`ADA_CLIENT_KEYS`, or open in dev mode), then `router.ts`
-   maps the model id → a provider.
-3. The matching **adapter** calls the upstream with the server-held provider key — a pass-through
-   for OpenAI-compatible providers, a translation for Anthropic.
-4. The backend streams normalized OpenAI SSE chunks back; the client renders text and runs tool
-   calls, appending one `{role:"tool", tool_call_id, content}` per call and looping.
-
-## The agent loop
-
-![ada agent loop](agent-loop.svg)
-
-Each turn streams the model's reply; if it contains tool calls, gated ones go through the
-**permission mode**, the tools run, and one `{role:"tool", tool_call_id, content}` per call is
-appended before control returns to the model — looping until the model stops calling tools.
-
-**Permission modes** (`/ask` · `/plan` · `/auto`, or `/mode` to cycle; shown in the prompt):
-
-- **ask** (default) — each gated tool shows a plain-words prompt ("ada wants to run a shell command…")
-  and one key: `[y]es` · `[a]uto` · `[p]lan` · `[n]o`. Destructive `bash` always confirms.
-- **plan** — read-only: ada plans but won't edit; `/run` approves and executes.
-- **auto** — runs tools without asking (still confirms destructive `bash`). `--yolo` starts here.
-
-**Skills.** ~285 bundled `SKILL.md` instructions load only on demand. A lexical router
-(`client/skill-router.ts`) ranks every request; on a confident, name-exact match ada **auto-applies**
-the skill (injects its procedure, announced `↳ skill: <name>`), otherwise it suggests them. The model
-can also `list_skills` / `find_skill` / `use_skill`. See [orchestration.md](orchestration.md) for the
-strategies (`react`/`plan`/`multi`/`toolsmith`) layered on the same loop.
-
-**Programmatic surfaces.** Beyond the REPL/TUI, the same agent drives an HTTP API (`ada serve`), a
-typed SDK, an ACP editor bridge (`ada acp`), and read-only session sharing (`ada share`) — see
-[integrations.md](integrations.md). And it can run **SWE-bench Verified** via [bench/](../bench/).
-
-## Sign in (device flow)
-
-![ada login device flow](login-flow.svg)
-
-GitHub/Google login uses the OAuth 2.0 device authorization grant (RFC 8628) — no password ever
-reaches ada. The token is stored locally and sent as the bearer; the backend verifies identity in
-`server/identity.ts`. The GitHub `client_id` is baked in (public, like `gh`), so the client needs
-zero config.
-
-## One adapter per wire format
-
-The key design decision: adapters are keyed by **wire format**, not by provider or model.
-
-- Most providers speak the OpenAI format and share **`openai-compat.ts`** (a pass-through that just
-  swaps in the right base URL + key).
-- Only a divergent format gets its own adapter — **`anthropic.ts`** translates OpenAI ⇄ Anthropic
-  Messages and re-emits Anthropic events as OpenAI SSE.
-
-Consequences:
-
-| Change | Cost |
-|---|---|
-| A new model | **0 code** (routing is by id) |
-| A new OpenAI-compatible provider | **2 lines** in `config.ts` (base URL + key env) |
-| A brand-new wire format | **1 adapter** + one line in `registry.ts` |
-
-Vendor SDKs load **lazily** (pi-style): a `type`-only import plus a dynamic `import()`, so e.g.
-`@anthropic-ai/sdk` never loads unless a Claude request actually arrives.
-
-## Routing
-
-`router.ts` maps a model id to a provider:
-
-- a model id containing `:` (e.g. `qwen2.5-coder:latest`) → local **Ollama**;
-- otherwise by prefix (`gpt*`/`o*` → openai, `claude*` → anthropic, `gemini*` → google,
-  `mistral*` → mistral, `grok*` → xai, …);
-- an explicit `provider` field on the request always wins;
-- anything unmatched falls through to **OpenRouter**.
-
-## Context compaction
-
-The client estimates context size (≈ chars / 4) and, when it crosses `ADA_COMPACT_AT` (default
-100k) or a request overflows, summarizes older turns into one compact summary and keeps the recent
-ones. `/compact` forces it; `/context` shows the current estimate.
-
-## Tool-call recovery
-
-Some providers (notably **Ollama over a streaming connection**) fail to parse a model's tool call
-into the structured `tool_calls` field and leak it into the text as raw JSON. The client detects a
-reply that *is* a JSON tool call (plain, ```` ```json ```` fenced, or `<tool_call>`-wrapped) for a
-real tool and runs it instead of printing the JSON. Hallucinated tools (no such tool) are left as
-text. See `parseTextToolCalls` in `client/agent.ts`.
-
-## File layout
-
-```
-bin/
-  ada.mjs             launcher: register tsx loader → run client/cli.ts
-  ada-server.mjs      launcher: register tsx loader → run server/index.ts
-
-src/
-  shared/
-    types.ts          provider/model types shared by client and server
-
-  server/             the routing backend                 (ada-server | npm run server)
-    index.ts          HTTP entry: auth → route → dispatch to an adapter (+ /v1/models, /v1/whoami)
-    config.ts         providers, base URLs, key env vars, port, client-key auth
-    router.ts         model id → provider
-    sse.ts            Server-Sent Events helpers
-    identity.ts       verify GitHub/Google tokens; allowlist
-    oauth.ts          RFC 8628 device-flow login (built-in GitHub client id)
-    credentials.ts    local credential store
-    providers/
-      adapter.ts      the Adapter interface               ← one adapter per WIRE FORMAT
-      registry.ts     provider → adapter map
-      openai-compat.ts pass-through OpenAI-compatible adapter
-      anthropic.ts    native Anthropic adapter (lazy @anthropic-ai/sdk)
-
-  client/             the terminal agent                  (ada | npm start)
-    cli.ts            REPL: flags, model picker, slash commands, ask/plan/auto modes + approval
-    agent.ts          the agentic loop (stream → tool calls → feed back → repeat) + orchestrators
-    tools.ts          read_file/write_file/edit_file · apply_patch · bash (PTY) · ls/glob/grep (rg)
-                      · web_fetch/web_search · lsp_diagnostics · ask_user; protected paths;
-                      destructive detection; trust-gated auto-format
-    tui.ts            inline TUI engine (composer, spinner, user bar)
-    tui-mode.ts       the TUI loop
-    session.ts        append-only JSONL session store (.ada/sessions/)
-    compaction.ts     context summarization
-    checkpoint.ts · snapshot.ts   undo (revert edits) · whole-tree git snapshot/restore
-    skills.ts · skill-router.ts   skills + the relevance router (auto-apply)
-    mcp.ts · prompts.ts · background.ts · models-dev.ts · lsp.ts   connectors, templates,
-                      background jobs, models.dev catalog, LSP client
-    todos.ts · hooks.ts · extensions.ts   tasks; extension hooks + tools + commands
-    settings.ts · platform.ts · render.ts · image.ts · telemetry.ts · pkg.ts
-
-  sdk/index.ts        typed client for the HTTP API (`ada serve`)
-  selfcheck.ts        offline checks (tools, sessions, routing, parsers, TUI, classifiers)
-
-bench/
-  swebench.mjs        SWE-bench Verified prediction generator (scored by the official harness)
-```
-
-## No build step
-
-Everything runs through `tsx` — TypeScript with no compile. The `bin/*.mjs` launchers register the
-tsx ESM loader in-process, then import the relevant `.ts` entrypoint (which self-runs). `tsx` is a
-runtime dependency so the global `ada` command works after `npx ada-agent`, `npm install -g ada-agent`,
-or `npm link` from a clone. (`node-pty` is the one native dep, so a C toolchain is needed at install.)
+# Architecture
+
+ada is two programs in one repo: a thin **client** (the coding agent) and a **backend** (the
+router that holds provider keys). They communicate in one wire format — OpenAI Chat Completions.
+
+![ada architecture](architecture.svg)
+
+```
+ ada (client)                    ada backend                         upstream providers
+ ────────────                    ───────────                         ──────────────────
+ agentic loop  ──── HTTP  ───▶   auth (client key)
+ tools                           router: model id → provider
+ sessions                        adapter: provider → wire format ──▶  Anthropic / OpenAI / …
+ approval/TUI   ◀── SSE  ────    normalize back to OpenAI SSE
+```
+
+Why split it: the backend is the **one control point**. Provider keys, auth, rate limits, and
+billing all belong in one place; the client carries only an ada client key. Same shape as Cursor.
+
+## Request flow
+
+1. The client sends an OpenAI-format chat request (model, messages, tools) to `ADA_BACKEND_URL`
+   with its client key as the bearer.
+2. The backend authenticates the key (`ADA_CLIENT_KEYS`, or open in dev mode), then `router.ts`
+   maps the model id → a provider.
+3. The matching **adapter** calls the upstream with the server-held provider key — a pass-through
+   for OpenAI-compatible providers, a translation for Anthropic.
+4. The backend streams normalized OpenAI SSE chunks back; the client renders text and runs tool
+   calls, appending one `{role:"tool", tool_call_id, content}` per call and looping.
+
+## The agent loop
+
+![ada agent loop](agent-loop.svg)
+
+Each turn streams the model's reply; if it contains tool calls, gated ones go through the
+**permission mode**, the tools run, and one `{role:"tool", tool_call_id, content}` per call is
+appended before control returns to the model — looping until the model stops calling tools.
+
+**Permission modes** (`/ask` · `/plan` · `/auto`, or `/mode` to cycle; shown in the prompt):
+
+- **ask** (default) — each gated tool shows a plain-words prompt ("ada wants to run a shell command…")
+  and one key: `[y]es` · `[a]uto` · `[p]lan` · `[n]o`. Destructive `bash` always confirms.
+- **plan** — read-only: ada plans but won't edit; `/run` approves and executes.
+- **auto** — runs tools without asking (still confirms destructive `bash`). `--yolo` starts here.
+
+**Skills.** ~285 bundled `SKILL.md` instructions load only on demand. A lexical router
+(`client/skill-router.ts`) ranks every request; on a confident, name-exact match ada **auto-applies**
+the skill (injects its procedure, announced `↳ skill: <name>`), otherwise it suggests them. The model
+can also `list_skills` / `find_skill` / `use_skill`. See [orchestration.md](orchestration.md) for the
+strategies (`react`/`plan`/`multi`/`toolsmith`) layered on the same loop.
+
+**Programmatic surfaces.** Beyond the REPL/TUI, the same agent drives an HTTP API (`ada serve`), a
+typed SDK, an ACP editor bridge (`ada acp`), and read-only session sharing (`ada share`) — see
+[integrations.md](integrations.md). And it can run **SWE-bench Verified** via [bench/](../bench/).
+
+## Sign in (device flow)
+
+![ada login device flow](login-flow.svg)
+
+GitHub/Google login uses the OAuth 2.0 device authorization grant (RFC 8628) — no password ever
+reaches ada. The token is stored locally and sent as the bearer; the backend verifies identity in
+`server/identity.ts`. The GitHub `client_id` is baked in (public, like `gh`), so the client needs
+zero config.
+
+## One adapter per wire format
+
+The key design decision: adapters are keyed by **wire format**, not by provider or model.
+
+- Most providers speak the OpenAI format and share **`openai-compat.ts`** (a pass-through that just
+  swaps in the right base URL + key).
+- Only a divergent format gets its own adapter — **`anthropic.ts`** translates OpenAI ⇄ Anthropic
+  Messages and re-emits Anthropic events as OpenAI SSE.
+
+Consequences:
+
+| Change | Cost |
+|---|---|
+| A new model | **0 code** (routing is by id) |
+| A new OpenAI-compatible provider | **2 lines** in `config.ts` (base URL + key env) |
+| A brand-new wire format | **1 adapter** + one line in `registry.ts` |
+
+Vendor SDKs load **lazily** (pi-style): a `type`-only import plus a dynamic `import()`, so e.g.
+`@anthropic-ai/sdk` never loads unless a Claude request actually arrives.
+
+## Routing
+
+`router.ts` maps a model id to a provider:
+
+- a model id containing `:` (e.g. `qwen2.5-coder:latest`) → local **Ollama**;
+- otherwise by prefix (`gpt*`/`o*` → openai, `claude*` → anthropic, `gemini*` → google,
+  `mistral*` → mistral, `grok*` → xai, …);
+- an explicit `provider` field on the request always wins;
+- anything unmatched falls through to **OpenRouter**.
+
+## Context compaction
+
+The client estimates context size (≈ chars / 4) and, when it crosses `ADA_COMPACT_AT` (default
+100k) or a request overflows, summarizes older turns into one compact summary and keeps the recent
+ones. `/compact` forces it; `/context` shows the current estimate.
+
+## Tool-call recovery
+
+Some providers (notably **Ollama over a streaming connection**) fail to parse a model's tool call
+into the structured `tool_calls` field and leak it into the text as raw JSON. The client detects a
+reply that *is* a JSON tool call (plain, ```` ```json ```` fenced, or `<tool_call>`-wrapped) for a
+real tool and runs it instead of printing the JSON. Hallucinated tools (no such tool) are left as
+text. See `parseTextToolCalls` in `client/agent.ts`.
+
+## File layout
+
+```
+bin/
+  ada.mjs             launcher: register tsx loader → run client/cli.ts
+  ada-server.mjs      launcher: register tsx loader → run server/index.ts
+
+src/
+  shared/
+    types.ts          provider/model types shared by client and server
+
+  server/             the routing backend                 (ada-server | npm run server)
+    index.ts          HTTP entry: auth → route → dispatch to an adapter (+ /v1/models, /v1/whoami)
+    config.ts         providers, base URLs, key env vars, port, client-key auth
+    router.ts         model id → provider
+    sse.ts            Server-Sent Events helpers
+    identity.ts       verify GitHub/Google tokens; allowlist
+    oauth.ts          RFC 8628 device-flow login (built-in GitHub client id)
+    credentials.ts    local credential store
+    providers/
+      adapter.ts      the Adapter interface               ← one adapter per WIRE FORMAT
+      registry.ts     provider → adapter map
+      openai-compat.ts pass-through OpenAI-compatible adapter
+      anthropic.ts    native Anthropic adapter (lazy @anthropic-ai/sdk)
+
+  client/             the terminal agent                  (ada | npm start)
+    cli.ts            REPL: flags, model picker, slash commands, ask/plan/auto modes + approval
+    agent.ts          the agentic loop (stream → tool calls → feed back → repeat) + orchestrators
+    tools.ts          read_file/write_file/edit_file · apply_patch · bash (PTY) · ls/glob/grep (rg)
+                      · web_fetch/web_search · lsp_diagnostics · ask_user; protected paths;
+                      destructive detection; trust-gated auto-format
+    tui.ts            inline TUI engine (composer, spinner, user bar)
+    tui-mode.ts       the TUI loop
+    session.ts        append-only JSONL session store (.ada/sessions/)
+    compaction.ts     context summarization
+    checkpoint.ts · snapshot.ts   undo (revert edits) · whole-tree git snapshot/restore
+    skills.ts · skill-router.ts   skills + the relevance router (auto-apply)
+    mcp.ts · prompts.ts · background.ts · models-dev.ts · lsp.ts   connectors, templates,
+                      background jobs, models.dev catalog, LSP client
+    todos.ts · hooks.ts · extensions.ts   tasks; extension hooks + tools + commands
+    settings.ts · platform.ts · render.ts · image.ts · telemetry.ts · pkg.ts
+
+  sdk/index.ts        typed client for the HTTP API (`ada serve`)
+  selfcheck.ts        offline checks (tools, sessions, routing, parsers, TUI, classifiers)
+
+bench/
+  swebench.mjs        SWE-bench Verified prediction generator (scored by the official harness)
+```
+
+## No build step
+
+Everything runs through `tsx` — TypeScript with no compile. The `bin/*.mjs` launchers register the
+tsx ESM loader in-process, then import the relevant `.ts` entrypoint (which self-runs). `tsx` is a
+runtime dependency so the global `ada` command works after `npx ada-agent`, `npm install -g ada-agent`,
+or `npm link` from a clone. (`node-pty` is the one native dep, so a C toolchain is needed at install.)

package/docs/architecture.svg

@@ -1,73 +1,73 @@
-<svg viewBox="0 0 920 470" xmlns="http://www.w3.org/2000/svg" font-family="ui-sans-serif, system-ui, sans-serif" role="img" aria-labelledby="t d">
-  <title id="t">ada architecture</title>
-  <desc id="d">The ada terminal client sends OpenAI Chat Completions over HTTP to the ada backend, which authenticates the client key, routes by model id, adapts to each provider's wire format, and streams normalized SSE back. The backend holds every provider key and reaches Anthropic via a native adapter and all other providers via a shared OpenAI-compatible adapter.</desc>
-
-  <defs>
-    <marker id="fwd" markerWidth="9" markerHeight="9" refX="7" refY="4.5" orient="auto"><path d="M0,0 L9,4.5 L0,9 z" fill="#ffaf00"/></marker>
-    <marker id="back" markerWidth="9" markerHeight="9" refX="7" refY="4.5" orient="auto"><path d="M0,0 L9,4.5 L0,9 z" fill="#3fb950"/></marker>
-  </defs>
-
-  <!-- panel -->
-  <rect x="6" y="6" width="908" height="458" rx="16" fill="#0d0f12" stroke="#262b33"/>
-  <rect x="34" y="34" width="14" height="14" rx="4" transform="rotate(45 41 41)" fill="#ffaf00"/>
-  <text x="60" y="40" fill="#ffaf00" font-size="17" font-weight="700">ada · architecture</text>
-  <text x="60" y="60" fill="#9aa3af" font-size="12">terminal client → routing backend → providers · one wire format throughout</text>
-
-  <!-- request / response lanes -->
-  <g font-family="ui-monospace, monospace" font-size="10.5">
-    <!-- top: request (gold, →) -->
-    <line x1="226" y1="200" x2="340" y2="200" stroke="#ffaf00" stroke-width="1.6" marker-end="url(#fwd)"/>
-    <text x="283" y="190" fill="#c5cdd6" text-anchor="middle">OpenAI Chat</text>
-    <text x="283" y="178" fill="#9aa3af" text-anchor="middle" font-size="9">Completions · HTTP</text>
-    <line x1="652" y1="200" x2="710" y2="200" stroke="#ffaf00" stroke-width="1.6" marker-end="url(#fwd)"/>
-    <text x="683" y="190" fill="#c5cdd6" text-anchor="middle">+ key</text>
-
-    <!-- bottom: response (green, ←) -->
-    <line x1="710" y1="320" x2="652" y2="320" stroke="#3fb950" stroke-width="1.6" marker-end="url(#back)"/>
-    <text x="683" y="338" fill="#7ee08a" text-anchor="middle">SSE</text>
-    <line x1="340" y1="320" x2="226" y2="320" stroke="#3fb950" stroke-width="1.6" marker-end="url(#back)"/>
-    <text x="283" y="338" fill="#7ee08a" text-anchor="middle">normalized OpenAI SSE</text>
-  </g>
-
-  <!-- client card -->
-  <rect x="42" y="138" width="184" height="212" rx="12" fill="#14171c" stroke="#262b33"/>
-  <text x="134" y="166" fill="#ffaf00" font-size="16" font-weight="700" text-anchor="middle">ada client</text>
-  <text x="134" y="183" fill="#9aa3af" font-size="10.5" text-anchor="middle">the terminal</text>
-  <g font-family="ui-monospace, monospace" font-size="11" fill="#c5cdd6" text-anchor="middle">
-    <text x="134" y="207">agentic loop · tools</text>
-    <text x="134" y="226">285 skills · MCP</text>
-    <text x="134" y="245">ask · plan · auto</text>
-    <text x="134" y="264">REPL · TUI · sessions</text>
-    <text x="134" y="283" fill="#6b7480">serve · SDK · ACP</text>
-  </g>
-  <rect x="80" y="303" width="108" height="22" rx="11" fill="#0d0f12" stroke="#262b33"/>
-  <text x="134" y="318" fill="#6b7480" font-size="10" text-anchor="middle" font-family="ui-monospace, monospace">holds no keys</text>
-
-  <!-- backend card -->
-  <rect x="346" y="118" width="306" height="244" rx="12" fill="#101318" stroke="#262b33"/>
-  <text x="499" y="146" fill="#ffaf00" font-size="15" font-weight="700" text-anchor="middle">ada backend</text>
-  <text x="499" y="163" fill="#9aa3af" font-size="10" text-anchor="middle">the one control point — holds every key</text>
-  <g font-family="ui-monospace, monospace" font-size="11.5">
-    <g><rect x="366" y="176" width="266" height="30" rx="8" fill="#14171c" stroke="#262b33"/><text x="380" y="195" fill="#e6e9ee"><tspan fill="#ffaf00">1</tspan>  auth · client key</text></g>
-    <g><rect x="366" y="214" width="266" height="30" rx="8" fill="#14171c" stroke="#262b33"/><text x="380" y="233" fill="#e6e9ee"><tspan fill="#ffaf00">2</tspan>  route · model id → provider</text></g>
-    <g><rect x="366" y="252" width="266" height="30" rx="8" fill="#14171c" stroke="#262b33"/><text x="380" y="271" fill="#e6e9ee"><tspan fill="#ffaf00">3</tspan>  adapt · one per wire format</text></g>
-    <g><rect x="366" y="290" width="266" height="30" rx="8" fill="#14171c" stroke="#262b33"/><text x="380" y="309" fill="#e6e9ee"><tspan fill="#ffaf00">4</tspan>  normalize → OpenAI SSE</text></g>
-  </g>
-
-  <!-- providers card -->
-  <rect x="716" y="150" width="162" height="180" rx="12" fill="#14171c" stroke="#262b33"/>
-  <text x="797" y="180" fill="#e6e9ee" font-size="13" font-weight="700" text-anchor="middle">providers</text>
-  <text x="797" y="202" fill="#ff7a59" font-size="12" font-weight="700" text-anchor="middle" font-family="ui-monospace, monospace">Anthropic <tspan fill="#6b7480" font-weight="400" font-size="9">native</tspan></text>
-  <line x1="732" y1="214" x2="862" y2="214" stroke="#262b33"/>
-  <g font-family="ui-monospace, monospace" font-size="10.5" fill="#c5cdd6" text-anchor="middle">
-    <text x="797" y="234">OpenAI · Gemini · Groq</text>
-    <text x="797" y="252">Mistral · DeepSeek · xAI</text>
-    <text x="797" y="270">Together · DashScope</text>
-    <text x="797" y="288">Ollama · OpenRouter</text>
-  </g>
-  <text x="797" y="312" fill="#ffaf00" font-size="9.5" text-anchor="middle" font-family="ui-monospace, monospace">all but Anthropic: openai-compat</text>
-
-  <!-- footer note -->
-  <text x="460" y="406" fill="#9aa3af" font-size="11" text-anchor="middle" font-family="ui-monospace, monospace">a new model = 0 code   ·   a new OpenAI-compatible provider = 2 lines   ·   a new wire format = 1 adapter</text>
-  <text x="460" y="430" fill="#6b7480" font-size="10" text-anchor="middle">vendor SDKs load lazily — the Anthropic SDK never loads unless a Claude request arrives</text>
-</svg>
+<svg viewBox="0 0 920 470" xmlns="http://www.w3.org/2000/svg" font-family="ui-sans-serif, system-ui, sans-serif" role="img" aria-labelledby="t d">
+  <title id="t">ada architecture</title>
+  <desc id="d">The ada terminal client sends OpenAI Chat Completions over HTTP to the ada backend, which authenticates the client key, routes by model id, adapts to each provider's wire format, and streams normalized SSE back. The backend holds every provider key and reaches Anthropic via a native adapter and all other providers via a shared OpenAI-compatible adapter.</desc>
+
+  <defs>
+    <marker id="fwd" markerWidth="9" markerHeight="9" refX="7" refY="4.5" orient="auto"><path d="M0,0 L9,4.5 L0,9 z" fill="#ffaf00"/></marker>
+    <marker id="back" markerWidth="9" markerHeight="9" refX="7" refY="4.5" orient="auto"><path d="M0,0 L9,4.5 L0,9 z" fill="#3fb950"/></marker>
+  </defs>
+
+  <!-- panel -->
+  <rect x="6" y="6" width="908" height="458" rx="16" fill="#0d0f12" stroke="#262b33"/>
+  <rect x="34" y="34" width="14" height="14" rx="4" transform="rotate(45 41 41)" fill="#ffaf00"/>
+  <text x="60" y="40" fill="#ffaf00" font-size="17" font-weight="700">ada · architecture</text>
+  <text x="60" y="60" fill="#9aa3af" font-size="12">terminal client → routing backend → providers · one wire format throughout</text>
+
+  <!-- request / response lanes -->
+  <g font-family="ui-monospace, monospace" font-size="10.5">
+    <!-- top: request (gold, →) -->
+    <line x1="226" y1="200" x2="340" y2="200" stroke="#ffaf00" stroke-width="1.6" marker-end="url(#fwd)"/>
+    <text x="283" y="190" fill="#c5cdd6" text-anchor="middle">OpenAI Chat</text>
+    <text x="283" y="178" fill="#9aa3af" text-anchor="middle" font-size="9">Completions · HTTP</text>
+    <line x1="652" y1="200" x2="710" y2="200" stroke="#ffaf00" stroke-width="1.6" marker-end="url(#fwd)"/>
+    <text x="683" y="190" fill="#c5cdd6" text-anchor="middle">+ key</text>
+
+    <!-- bottom: response (green, ←) -->
+    <line x1="710" y1="320" x2="652" y2="320" stroke="#3fb950" stroke-width="1.6" marker-end="url(#back)"/>
+    <text x="683" y="338" fill="#7ee08a" text-anchor="middle">SSE</text>
+    <line x1="340" y1="320" x2="226" y2="320" stroke="#3fb950" stroke-width="1.6" marker-end="url(#back)"/>
+    <text x="283" y="338" fill="#7ee08a" text-anchor="middle">normalized OpenAI SSE</text>
+  </g>
+
+  <!-- client card -->
+  <rect x="42" y="138" width="184" height="212" rx="12" fill="#14171c" stroke="#262b33"/>
+  <text x="134" y="166" fill="#ffaf00" font-size="16" font-weight="700" text-anchor="middle">ada client</text>
+  <text x="134" y="183" fill="#9aa3af" font-size="10.5" text-anchor="middle">the terminal</text>
+  <g font-family="ui-monospace, monospace" font-size="11" fill="#c5cdd6" text-anchor="middle">
+    <text x="134" y="207">agentic loop · tools</text>
+    <text x="134" y="226">285 skills · MCP</text>
+    <text x="134" y="245">ask · plan · auto</text>
+    <text x="134" y="264">REPL · TUI · sessions</text>
+    <text x="134" y="283" fill="#6b7480">serve · SDK · ACP</text>
+  </g>
+  <rect x="80" y="303" width="108" height="22" rx="11" fill="#0d0f12" stroke="#262b33"/>
+  <text x="134" y="318" fill="#6b7480" font-size="10" text-anchor="middle" font-family="ui-monospace, monospace">holds no keys</text>
+
+  <!-- backend card -->
+  <rect x="346" y="118" width="306" height="244" rx="12" fill="#101318" stroke="#262b33"/>
+  <text x="499" y="146" fill="#ffaf00" font-size="15" font-weight="700" text-anchor="middle">ada backend</text>
+  <text x="499" y="163" fill="#9aa3af" font-size="10" text-anchor="middle">the one control point — holds every key</text>
+  <g font-family="ui-monospace, monospace" font-size="11.5">
+    <g><rect x="366" y="176" width="266" height="30" rx="8" fill="#14171c" stroke="#262b33"/><text x="380" y="195" fill="#e6e9ee"><tspan fill="#ffaf00">1</tspan>  auth · client key</text></g>
+    <g><rect x="366" y="214" width="266" height="30" rx="8" fill="#14171c" stroke="#262b33"/><text x="380" y="233" fill="#e6e9ee"><tspan fill="#ffaf00">2</tspan>  route · model id → provider</text></g>
+    <g><rect x="366" y="252" width="266" height="30" rx="8" fill="#14171c" stroke="#262b33"/><text x="380" y="271" fill="#e6e9ee"><tspan fill="#ffaf00">3</tspan>  adapt · one per wire format</text></g>
+    <g><rect x="366" y="290" width="266" height="30" rx="8" fill="#14171c" stroke="#262b33"/><text x="380" y="309" fill="#e6e9ee"><tspan fill="#ffaf00">4</tspan>  normalize → OpenAI SSE</text></g>
+  </g>
+
+  <!-- providers card -->
+  <rect x="716" y="150" width="162" height="180" rx="12" fill="#14171c" stroke="#262b33"/>
+  <text x="797" y="180" fill="#e6e9ee" font-size="13" font-weight="700" text-anchor="middle">providers</text>
+  <text x="797" y="202" fill="#ff7a59" font-size="12" font-weight="700" text-anchor="middle" font-family="ui-monospace, monospace">Anthropic <tspan fill="#6b7480" font-weight="400" font-size="9">native</tspan></text>
+  <line x1="732" y1="214" x2="862" y2="214" stroke="#262b33"/>
+  <g font-family="ui-monospace, monospace" font-size="10.5" fill="#c5cdd6" text-anchor="middle">
+    <text x="797" y="234">OpenAI · Gemini · Groq</text>
+    <text x="797" y="252">Mistral · DeepSeek · xAI</text>
+    <text x="797" y="270">Together · DashScope</text>
+    <text x="797" y="288">Ollama · OpenRouter</text>
+  </g>
+  <text x="797" y="312" fill="#ffaf00" font-size="9.5" text-anchor="middle" font-family="ui-monospace, monospace">all but Anthropic: openai-compat</text>
+
+  <!-- footer note -->
+  <text x="460" y="406" fill="#9aa3af" font-size="11" text-anchor="middle" font-family="ui-monospace, monospace">a new model = 0 code   ·   a new OpenAI-compatible provider = 2 lines   ·   a new wire format = 1 adapter</text>
+  <text x="460" y="430" fill="#6b7480" font-size="10" text-anchor="middle">vendor SDKs load lazily — the Anthropic SDK never loads unless a Claude request arrives</text>
+</svg>