ada-agent 0.1.0

package/docs/agent-loop.svg

@@ -0,0 +1,66 @@
+<svg viewBox="0 0 900 430" 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 agent loop</title>
+  <desc id="d">A turn: your message goes to the model, which streams a reply. If it has no tool calls the turn is done. If it does, gated tools prompt for approval, the tools run (read, edit, bash, grep), their results are appended as tool messages, and control returns to the model — repeating until the model stops calling tools.</desc>
+
+  <defs>
+    <marker id="a" markerWidth="9" markerHeight="9" refX="7" refY="4.5" orient="auto"><path d="M0,0 L9,4.5 L0,9 z" fill="#ffaf00"/></marker>
+  </defs>
+
+  <rect x="6" y="6" width="888" height="418" rx="16" fill="#0d0f12" stroke="#262b33"/>
+  <rect x="34" y="32" width="13" height="13" rx="4" transform="rotate(45 40 38)" fill="#ffaf00"/>
+  <text x="58" y="38" fill="#ffaf00" font-size="16" font-weight="700">ada · agent loop</text>
+  <text x="58" y="57" fill="#9aa3af" font-size="11.5">stream → call tools → feed results back → repeat until done</text>
+
+  <!-- arrows -->
+  <g stroke="#ffaf00" stroke-width="1.6" fill="none">
+    <line x1="192" y1="123" x2="248" y2="123" marker-end="url(#a)"/>
+    <line x1="412" y1="123" x2="498" y2="123" marker-end="url(#a)"/>
+    <line x1="622" y1="123" x2="710" y2="123" marker-end="url(#a)"/>
+    <path d="M560,165 V198 H765 V230" marker-end="url(#a)"/>
+    <line x1="690" y1="262" x2="622" y2="262" marker-end="url(#a)"/>
+    <line x1="470" y1="262" x2="412" y2="262" marker-end="url(#a)"/>
+    <path d="M330,230 V152" marker-end="url(#a)"/>
+  </g>
+  <g font-family="ui-monospace, monospace" font-size="10" fill="#9aa3af">
+    <text x="666" y="113" text-anchor="middle" fill="#7ee08a">no</text>
+    <text x="600" y="190" fill="#ffaf00">yes · tool_calls</text>
+    <text x="338" y="195" fill="#9aa3af">append {role: tool}</text>
+  </g>
+
+  <!-- top row -->
+  <g>
+    <rect x="42" y="95" width="150" height="56" rx="11" fill="#14171c" stroke="#262b33"/>
+    <text x="117" y="120" fill="#e6e9ee" font-size="13" font-weight="600" text-anchor="middle">user message</text>
+    <text x="117" y="138" fill="#9aa3af" font-size="10" text-anchor="middle" font-family="ui-monospace, monospace">your prompt</text>
+
+    <rect x="250" y="95" width="162" height="56" rx="11" fill="#101318" stroke="#262b33"/>
+    <text x="331" y="120" fill="#ffaf00" font-size="13" font-weight="700" text-anchor="middle">model</text>
+    <text x="331" y="138" fill="#9aa3af" font-size="10" text-anchor="middle" font-family="ui-monospace, monospace">stream tokens</text>
+
+    <path d="M560,81 L622,123 L560,165 L498,123 Z" fill="#14171c" stroke="#ffaf00"/>
+    <text x="560" y="120" fill="#e6e9ee" font-size="12" font-weight="600" text-anchor="middle">tool</text>
+    <text x="560" y="135" fill="#e6e9ee" font-size="12" font-weight="600" text-anchor="middle">calls?</text>
+
+    <rect x="712" y="95" width="150" height="56" rx="11" fill="#14171c" stroke="#3fb950"/>
+    <text x="787" y="120" fill="#7ee08a" font-size="13" font-weight="700" text-anchor="middle">reply</text>
+    <text x="787" y="138" fill="#9aa3af" font-size="10" text-anchor="middle" font-family="ui-monospace, monospace">turn done</text>
+  </g>
+
+  <!-- bottom row -->
+  <g>
+    <rect x="250" y="234" width="162" height="56" rx="11" fill="#14171c" stroke="#262b33"/>
+    <text x="331" y="259" fill="#e6e9ee" font-size="13" font-weight="600" text-anchor="middle">feed results</text>
+    <text x="331" y="277" fill="#9aa3af" font-size="10" text-anchor="middle" font-family="ui-monospace, monospace">one per tool call</text>
+
+    <rect x="470" y="234" width="152" height="56" rx="11" fill="#14171c" stroke="#262b33"/>
+    <text x="546" y="259" fill="#e6e9ee" font-size="13" font-weight="600" text-anchor="middle">run tools</text>
+    <text x="546" y="277" fill="#9aa3af" font-size="10" text-anchor="middle" font-family="ui-monospace, monospace">read·edit·bash·grep</text>
+
+    <rect x="690" y="234" width="152" height="56" rx="11" fill="#14171c" stroke="#ff7a59"/>
+    <text x="766" y="259" fill="#ff7a59" font-size="13" font-weight="700" text-anchor="middle">approve</text>
+    <text x="766" y="277" fill="#9aa3af" font-size="10" text-anchor="middle" font-family="ui-monospace, monospace">[y/a/N] · gated</text>
+  </g>
+
+  <text x="450" y="345" fill="#9aa3af" font-size="11" text-anchor="middle" font-family="ui-monospace, monospace">read-only tools never prompt · --yolo auto-approves · only the model's tool_calls drive the loop</text>
+  <text x="450" y="372" fill="#6b7480" font-size="10" text-anchor="middle">a tool call leaked into text as JSON (Ollama-over-stream) is recovered and run, not printed</text>
+</svg>

package/docs/architecture.md

@@ -0,0 +1,139 @@
+# 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 prompt for approval,
+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.
+
+## 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, approval prompt
+    agent.ts          the agentic loop (stream → tool calls → feed back → repeat)
+    tools.ts          read/write/edit/bash/ls/grep/glob; protected paths; destructive detection
+    tui.ts            inline TUI engine (composer, spinner, user bar)
+    tui-mode.ts       the TUI loop
+    session.ts        append-only JSONL session store (.cos0/sessions/)
+    compaction.ts     context summarization
+    checkpoint.ts     undo: snapshot files before edits, restore on /undo
+    todos.ts          task tracking + render
+    hooks.ts          extension hooks (before/after tool, input transform)
+    extensions.ts     load extensions (tools + hooks + commands)
+    skills.ts · mcp.ts · prompts.ts   skills, MCP servers, prompt templates
+    settings.ts · platform.ts · render.ts · image.ts · telemetry.ts · pkg.ts
+
+  selfcheck.ts        offline checks (tools, sessions, routing, parsers, TUI)
+```
+
+## 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 `npm link` / `npm install -g`.

package/docs/architecture.svg

@@ -0,0 +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>

package/docs/connectors.md

@@ -0,0 +1,48 @@
+# Connectors (MCP)
+
+ada connects to external tools and data through the **Model Context Protocol (MCP)**. Each connector
+is an MCP server; ada spawns or calls it, lists its tools, and registers them as ada tools named
+`<server>__<tool>` — approval-gated, and only loaded for **trusted projects**.
+
+## Quick start
+
+```bash
+ada mcp                       # list the connector catalog (● configured · ○ available)
+ada mcp add github            # write the github entry into .ada/mcp.json
+ada mcp remove github         # remove it
+```
+
+After `add`, set any env vars it prints (e.g. `GITHUB_PERSONAL_ACCESS_TOKEN`), then start `ada` in
+that project — the connector's tools appear automatically.
+
+## Catalog
+
+`filesystem` · `github` · `git` · `postgres` · `sqlite` · `fetch` · `brave-search` · `puppeteer` ·
+`slack` · `memory` · `sentry`. Run `ada mcp` for the live list and which env vars each needs.
+
+## Config: `.ada/mcp.json`
+
+`ada mcp add` edits this file, but you can also write entries by hand. Two transports:
+
+```jsonc
+{
+  "servers": {
+    // local stdio server (a subprocess)
+    "fs":     { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "."] },
+    // remote server over Streamable HTTP
+    "remote": { "url": "https://mcp.example.com/v1", "headers": { "Authorization": "Bearer <token>" } }
+  }
+}
+```
+
+- **stdio** — `{ command, args, env }`: ada launches the process and speaks JSON-RPC over stdin/stdout.
+- **http** — `{ url, headers }`: ada POSTs JSON-RPC and reads a JSON or SSE response (Streamable HTTP).
+
+## Notes
+
+- MCP servers run code / reach the network, so they load **only in trusted projects** (the same trust
+  gate as `.ada` prompts and settings). Untrusted projects skip them.
+- Every MCP tool is **approval-gated** — ada prompts before each call.
+- Secrets come from **env vars** (referenced in the server's `env`), never committed to `.ada/mcp.json`.
+- See the `connectors` skill category (`list_skills {category: "connectors"}`) for per-connector setup
+  walk-throughs, and the `mcp-server` skill to build your own.

package/docs/integrations.md

@@ -0,0 +1,59 @@
+# Integrating with ada
+
+ada exposes a few programmatic surfaces so other tools can drive it. The buildable foundations are
+shipped; the product surfaces that need *external* infrastructure (a Slack app, hosting, an Electron
+build, an IdP) are described with what they'd take — they can't be "live" without your accounts.
+
+## HTTP API — `ada serve`
+
+```bash
+ada serve            # → http://localhost:8788  (ADA_HTTP_PORT to change)
+```
+- `GET /health` → `{ ok, model }`
+- `POST /v1/prompt` `{ "text": "...", "model"?: "..." }` → `{ text, usage }` (runs a fresh agent turn)
+
+## Typed SDK — `src/sdk`
+
+```ts
+import { createClient } from "ada/sdk"; // or "./src/sdk/index.ts" in-repo
+const ada = createClient("http://localhost:8788");
+console.log(await ada.health());
+const { text } = await ada.prompt("list the files in this project");
+```
+
+## ACP bridge — `ada acp`
+
+A minimal Agent Client Protocol bridge over stdio (JSON-RPC 2.0, newline-delimited): handles
+`initialize` and `session/prompt`, so an ACP-aware editor can drive ada. It's a **scaffold** — method
+names and framing may need adjusting to your client's ACP version.
+
+## Session share — `ada share`
+
+```bash
+ada share              # serve the latest session as a read-only web page (localhost)
+ada share <name|file>  # a specific session
+```
+Local and read-only. A *public* share link would need a hosted backend to receive and serve the
+transcript (see below).
+
+---
+
+## Needs your infrastructure (foundations are here; the rest is your accounts/hosting)
+
+These are all buildable **on top of the HTTP API / SDK above** — what's missing is the external
+service, which only you can provision.
+
+- **Slack bot** — a [Slack Bolt](https://slack.dev/bolt-js) app that, per thread, calls
+  `createClient().prompt(message)` and posts the reply. Needs a **Slack app + bot token** (`SLACK_BOT_TOKEN`)
+  and a running process. ~30 lines on top of the SDK.
+- **Web console** — a single page that POSTs to `/v1/prompt` and renders the reply (the `ada share`
+  server is a minimal read-only version). Needs **hosting** + CORS if cross-origin.
+- **Desktop app** — an Electron shell that spawns `ada serve` and points a webview at it. Needs the
+  **Electron build/packaging** pipeline (you already have the separate `ada-ide` VS Code fork).
+- **Public session sharing** — `ada share` is local; a public link needs a **hosted endpoint** to
+  receive the transcript and a viewer (like opencode's `console.opncd.ai`).
+- **Enterprise / identity / teams** — multi-tenant accounts + SSO need an **IdP and a control plane**;
+  out of scope for a single-binary CLI.
+- **SQLite session store** — ada uses append-only JSONL (`.ada/sessions/*.jsonl`) by design (no native
+  dep, greppable, trivially portable). Node 24 ships an experimental `node:sqlite`; a SQLite backend is
+  a drop-in for `session.ts` if you want indexed queries — say the word and it's a small module.

package/docs/login-flow.svg

@@ -0,0 +1,56 @@
+<svg viewBox="0 0 580 500" 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 login — device flow</title>
+  <desc id="d">Signing in with GitHub or Google uses the OAuth 2.0 device authorization grant (RFC 8628). The client requests a device code, shows you a user code and a URL, you approve in your browser, and the client polls until it receives an access token, which it stores locally and sends as the bearer for the backend to verify your identity.</desc>
+
+  <defs>
+    <marker id="a" markerWidth="9" markerHeight="9" refX="7" refY="4.5" orient="auto"><path d="M0,0 L9,4.5 L0,9 z" fill="#ffaf00"/></marker>
+  </defs>
+
+  <rect x="6" y="6" width="568" height="488" rx="16" fill="#0d0f12" stroke="#262b33"/>
+  <rect x="30" y="30" width="13" height="13" rx="4" transform="rotate(45 36 36)" fill="#ffaf00"/>
+  <text x="54" y="36" fill="#ffaf00" font-size="16" font-weight="700">ada · sign in</text>
+  <text x="54" y="55" fill="#9aa3af" font-size="11.5">device flow (RFC 8628) — no password ever touches ada</text>
+
+  <!-- connector spine -->
+  <g stroke="#ffaf00" stroke-width="1.6" fill="none">
+    <line x1="60" y1="118" x2="60" y2="150" marker-end="url(#a)"/>
+    <line x1="60" y1="196" x2="60" y2="228" marker-end="url(#a)"/>
+    <line x1="60" y1="288" x2="60" y2="320" marker-end="url(#a)"/>
+    <line x1="60" y1="366" x2="60" y2="398" marker-end="url(#a)"/>
+  </g>
+
+  <g font-family="ui-monospace, monospace">
+    <!-- 1 -->
+    <circle cx="60" cy="92" r="13" fill="#14171c" stroke="#ffaf00"/><text x="60" y="96" fill="#ffaf00" font-size="12" font-weight="700" text-anchor="middle">1</text>
+    <rect x="92" y="74" width="456" height="38" rx="9" fill="#14171c" stroke="#262b33"/>
+    <text x="108" y="91" fill="#e6e9ee" font-size="12">ada · <tspan fill="#ffaf00">/login</tspan> → choose GitHub or Google</text>
+    <text x="108" y="105" fill="#9aa3af" font-size="9.5">client POSTs a device-code request</text>
+
+    <!-- 2 -->
+    <circle cx="60" cy="172" r="13" fill="#14171c" stroke="#ffaf00"/><text x="60" y="176" fill="#ffaf00" font-size="12" font-weight="700" text-anchor="middle">2</text>
+    <rect x="92" y="154" width="456" height="42" rx="9" fill="#14171c" stroke="#262b33"/>
+    <text x="108" y="172" fill="#e6e9ee" font-size="12">ada shows a <tspan fill="#ffaf00" font-weight="700">user code</tspan> + a verification URL</text>
+    <text x="108" y="188" fill="#9aa3af" font-size="9.5">e.g. 8447-AB0E · https://github.com/login/device</text>
+
+    <!-- 3 (human / browser) -->
+    <circle cx="60" cy="258" r="13" fill="#14171c" stroke="#ff7a59"/><text x="60" y="262" fill="#ff7a59" font-size="12" font-weight="700" text-anchor="middle">3</text>
+    <rect x="92" y="234" width="456" height="54" rx="9" fill="#14171c" stroke="#ff7a59"/>
+    <text x="108" y="254" fill="#ff7a59" font-size="12" font-weight="700">↗ you open the URL in a browser</text>
+    <text x="108" y="271" fill="#e6e9ee" font-size="11">enter the code, sign in, approve</text>
+    <text x="108" y="284" fill="#9aa3af" font-size="9.5">meanwhile ada polls the token endpoint</text>
+
+    <!-- 4 -->
+    <circle cx="60" cy="342" r="13" fill="#14171c" stroke="#ffaf00"/><text x="60" y="346" fill="#ffaf00" font-size="12" font-weight="700" text-anchor="middle">4</text>
+    <rect x="92" y="324" width="456" height="42" rx="9" fill="#14171c" stroke="#262b33"/>
+    <text x="108" y="342" fill="#e6e9ee" font-size="12">provider returns an <tspan fill="#7ee08a" font-weight="700">access token</tspan></text>
+    <text x="108" y="358" fill="#9aa3af" font-size="9.5">stored locally in ~/.ada/credentials.json (file-locked)</text>
+
+    <!-- 5 -->
+    <circle cx="60" cy="422" r="13" fill="#14171c" stroke="#3fb950"/><text x="60" y="426" fill="#7ee08a" font-size="12" font-weight="700" text-anchor="middle">5</text>
+    <rect x="92" y="404" width="456" height="44" rx="9" fill="#14171c" stroke="#3fb950"/>
+    <text x="108" y="423" fill="#e6e9ee" font-size="12">token sent as the <tspan fill="#7ee08a" font-weight="700">bearer</tspan>; backend verifies identity</text>
+    <text x="108" y="439" fill="#9aa3af" font-size="9.5">server/identity.ts: GitHub /user · Google userinfo · allowlist</text>
+  </g>
+
+  <text x="290" y="476" fill="#6b7480" font-size="10" text-anchor="middle" font-family="ui-monospace, monospace">GitHub client_id is baked in (public, like gh) — zero client config</text>
+</svg>

package/docs/orchestration.md

@@ -0,0 +1,45 @@
+# Orchestration strategies
+
+ada's harness splits into two roles so the *control flow* is pluggable:
+
+- **Engine** — the harness primitives, in one place (`client/agent.ts`): `step()` (one model turn —
+  stream, collect content + tool calls, recover leaked calls, push the assistant message),
+  `runTools()`, `spawn()` (a headless sub-agent), plus `readDocs()` / `writeSkills()` /
+  `soleIntegration()`. It owns streaming, tool-call recovery, compaction, approval, and sessions.
+- **Orchestrator** — a Strategy that only decides *when* to call those primitives. An agent
+  architecture is one small orchestrator; the engine never changes.
+
+```ts
+interface Engine { step(opts?): Promise<StepResult|null>; runTools(calls); spawn(prompt); … }
+interface Orchestrator { name: string; run(e: Engine): Promise<void>; }
+```
+
+## Built-in strategies
+
+| Strategy | Architecture |
+|---|---|
+| `react` (default) | reason → act → observe → repeat (the classic loop) |
+| `single` | one model turn, no tools — quick Q&A |
+| `plan` | a read-only plan first, then execute it |
+| `multi` | decompose → fan out to sub-agents → synthesize |
+| `toolsmith` | read the lone integration's docs → sub-agents author skills for it |
+
+Select with `--strategy <name>` or the `/strategy [name]` command (default `react`).
+
+## toolsmith — self-extending from an integration's docs
+
+When **exactly one** connector is configured (`ada mcp add <name>`), `toolsmith`:
+
+1. reads that integration's "docs" — the descriptions + schemas of its registered `<name>__*` tools;
+2. a planning `step()` lists the capability **areas** (products, orders, payments, …);
+3. fans out one **sub-agent per area** (`Engine.spawn`), each authoring a `SKILL.md` from the docs;
+4. writes them to `.ada/skills/<name>-<area>/SKILL.md` under category `integration-<name>`.
+
+```bash
+ada mcp add epicmerch          # the only connector
+ada --strategy toolsmith -p go # reads epicmerch's tools, writes epicmerch-* skills
+```
+
+The model then discovers them with `list_skills category=integration-epicmerch` and loads one with
+`use_skill`. Adding a new agent architecture is one new `Orchestrator` in `agent.ts` — zero changes
+to streaming, tools, or sessions. (Same discipline as the backend's *one adapter per wire format*.)

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "ada-agent",
+  "version": "0.1.0",
+  "description": "A from-zero terminal coding agent with a Cursor-style routing backend, ~285 skills, MCP connectors, and ask/plan/auto modes",
+  "type": "module",
+  "license": "MIT",
+  "author": "Aditya",
+  "homepage": "https://github.com/black141312/ada#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/black141312/ada.git"
+  },
+  "bugs": {
+    "url": "https://github.com/black141312/ada/issues"
+  },
+  "keywords": [
+    "coding-agent",
+    "ai-agent",
+    "llm",
+    "cli",
+    "terminal",
+    "tui",
+    "mcp",
+    "openai",
+    "anthropic",
+    "ollama",
+    "agentic",
+    "developer-tools"
+  ],
+  "bin": {
+    "ada": "bin/ada.mjs",
+    "ada-server": "bin/ada-server.mjs"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "skills/",
+    "docs/",
+    "bench/",
+    "tsconfig.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "start": "tsx src/client/cli.ts",
+    "server": "tsx src/server/index.ts",
+    "typecheck": "tsc --noEmit",
+    "selfcheck": "tsx src/selfcheck.ts",
+    "bench:swebench": "node bench/swebench.mjs"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.106.0",
+    "node-pty": "^1.1.0",
+    "openai": "^6.45.0",
+    "tsx": "^4.22.4"
+  },
+  "devDependencies": {
+    "@types/node": "^26.0.1",
+    "typescript": "^6.0.3"
+  }
+}

package/skills/accessibility/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: accessibility
+description: Audit and fix a11y issues — semantics, ARIA, contrast, keyboard nav, focus, and labels
+category: frontend
+---
+
+# Accessibility
+
+Use when a component or page needs an a11y pass: failing audits, keyboard traps, missing labels, or low contrast.
+
+1. Start with semantics: replace `div`/`span` clickables with `button`, `a`, `nav`, `main`, `ul`, headings in order — native elements give you roles and keyboard support for free.
+2. Label every interactive and form control: visible `<label htmlFor>`, or `aria-label`/`aria-labelledby`; give icon-only buttons an accessible name and decorative images `alt=""`.
+3. Verify keyboard flow: Tab order is logical, every action is reachable and operable via Enter/Space, focus is visible, and modals trap focus and restore it on close.
+4. Add ARIA only to fill gaps native HTML can't (`aria-expanded`, `aria-current`, `role="alert"`, `aria-live` for dynamic updates) — and remove redundant or wrong ARIA.
+5. Check color contrast against WCAG AA (4.5:1 text, 3:1 large text / UI), and ensure state isn't conveyed by color alone (add icon/text).
+6. Re-run an automated checker (axe/Lighthouse) plus a manual keyboard + screen-reader sweep, and fix what tooling flags.
+
+## Rules
+- Prefer native semantic HTML over ARIA; a wrong `role` is worse than none.
+- Never remove focus outlines without providing an equally visible replacement.
+- Every form input needs a programmatically associated label, not just placeholder text.
+- Don't rely on color alone to communicate errors, status, or required fields.
+- Announce async changes (toasts, validation, loading) via `aria-live` so screen readers catch them.

package/skills/add-logging/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: add-logging
+description: Add strategic temporary logging to isolate an issue, read the output, then remove it cleanly
+category: debugging
+---
+
+# Add Logging
+
+Reach for this when you can't see what the code is doing and a debugger isn't practical (async flows, production-like runs, fast loops). Logging buys visibility — but it's scaffolding, not a deliverable.
+
+1. Decide what you need to confirm: which branch was taken, what a value is, whether a function ran, or how long something took.
+2. Place logs at decision points and boundaries — function entry/exit, before/after the suspect call, inside each branch of the `if`.
+3. Log identifying context with each value: a label, the variable name, and a correlation id if multiple requests interleave.
+4. Run the repro, read the output, and narrow: each pass should let you delete some logs and add more around the surviving suspect.
+5. Once the root cause is confirmed, apply the fix.
+6. Remove every temporary log (grep for your unique marker), and re-run to confirm the fix holds without them.
+
+## Rules
+- Tag temporary logs with a unique searchable string (e.g. `XDEBUG`) so you can find and delete all of them.
+- Log values, not just "got here" — `console.log('count', count)` beats `console.log('here')`.
+- For loops or hot paths, gate logging or log only the boundary case so output stays readable.
+- Don't commit debug logs; if a log is genuinely worth keeping, promote it to a real logger at the right level deliberately.
+- Beware that logging can mask timing bugs — see the heisenbug skill if the bug vanishes once logs are added.

package/skills/add-metrics/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: add-metrics
+description: Instrument code with Prometheus/OpenTelemetry metrics for counters, gauges, histograms
+category: observability
+---
+
+# Add Metrics
+
+Reach for this when you need to measure rates, throughput, latency, or resource levels — request counts, error rates, queue depth, job durations.
+
+1. Pick the client matching the stack (prom-client for Node, prometheus-client for Python, OTel SDK for vendor-neutral) and add it as a dependency.
+2. Choose the right instrument per signal: counter for monotonic totals (requests, errors), gauge for point-in-time values (in-flight, queue size), histogram for distributions (latency, payload size).
+3. Define metrics once at module scope with a stable `name`, `help` text, and low-cardinality labels; never recreate them per request.
+4. Increment/observe at the call site — wrap handlers or middleware so every request records duration and outcome (`status`, `route`).
+5. Expose a `/metrics` endpoint (Prometheus) or wire an OTLP exporter (OpenTelemetry) and confirm it scrapes with `curl localhost:PORT/metrics`.
+6. Add a histogram for the critical path latency using sensible buckets (e.g. `0.005..10` seconds) rather than the defaults.
+
+## Rules
+- Keep label cardinality bounded — never put user IDs, request IDs, emails, or raw URLs in labels; normalize routes to templates (`/users/:id`).
+- Use base units and suffixes Prometheus expects: seconds (not ms), bytes, `_total` for counters, `_seconds` for durations.
+- Initialize counters to 0 for all known label sets so absence vs. zero is distinguishable.
+- Record duration in a `finally` block so errors still get measured.
+- Don't block the request path on metric export; exporters must be async/buffered.