ada-agent 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aditya
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,256 @@
+# ada
+
+[![npm](https://img.shields.io/npm/v/ada-agent)](https://www.npmjs.com/package/ada-agent)
+[![CI](https://github.com/black141312/ada/actions/workflows/ci.yml/badge.svg)](https://github.com/black141312/ada/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Node ≥ 18](https://img.shields.io/badge/node-%E2%89%A518-green.svg)](package.json)
+
+A coding agent built from zero — a terminal client in the spirit of pi / Codex / Cursor,
+that holds every provider key and speaks one wire
+format to the client.
+
+![ada architecture](docs/architecture.svg)
+
+The client talks **only** OpenAI Chat Completions to the backend. The backend routes each request
+to the right provider by model id and normalizes every provider back to that one format — so a new
+model is **zero code**, and a new OpenAI-compatible provider is **two lines**.
+
+---
+
+## Features
+
+- **Agentic loop** — streams, calls tools, feeds results back, repeats until done.
+- **Tools** — `read_file`, `write_file`, `edit_file` (exact-match), `apply_patch` (multi-file),
+  `bash`, `ls`, `grep` (uses `rg` if present), `glob`, `web_fetch`, `web_search`, `lsp_diagnostics`,
+  `ask_user` (clarifying questions).
+- **Auto-format on edit** — written files are formatted with the project's formatter
+  (prettier/gofmt/rustfmt/ruff/shfmt) in trusted projects; off via `ADA_NO_FORMAT`.
+- **LSP diagnostics** — `lsp_diagnostics` runs a language server (typescript-language-server,
+  pyright, gopls, rust-analyzer) and returns errors/warnings; servers are reused, trusted-project only.
+- **Real PTY shell** — `bash` runs in a pseudo-terminal (node-pty), so TTY-only programs, colour, and
+  progress output behave; ANSI is stripped from what the model sees.
+- **Two front-ends** — a classic readline REPL and an inline **TUI** (`--tui`) with a live "thinking"
+  spinner and Claude-style turn markers.
+- **Permission modes — ask / plan / auto** — `/ask` confirms each tool, `/plan` is read-only (ada
+  plans, `/run` to execute), `/auto` runs freely (destructive `bash` still confirms). Each approval
+  states in plain words what it wants ("ada wants to run a shell command…") instead of raw args.
+- **Skills that actually fire** — ~285 built-in skills; ada routes every request and **auto-applies**
+  a clearly-matching one (injecting its procedure), or suggests skills to load. See [Skills](#skills).
+- **todos**, **checkpoint/undo** (revert the agent's edits), **protected paths**, **git worktrees**,
+  **workspace snapshots** (`/snapshot` `/restore`), **named agents**, and **subagents** (`spawn_agent`).
+- **Sessions** — every turn is persisted; `--continue` / `--resume` to pick up where you left off.
+- **Context compaction** — summarizes old turns automatically as context grows.
+- **Sign in with GitHub or Google** (RFC 8628 device flow) — zero client config.
+- **Extensible** — extensions (tools + hooks + commands), prompt templates, skills, and MCP servers.
+- **No build step** — TypeScript run through `tsx`.
+
+## Providers
+
+The backend proxies any OpenAI-compatible upstream and translates the one that isn't (Anthropic):
+
+| Provider | Models | Key env var |
+|---|---|---|
+| OpenAI | `gpt-*`, `o*` | `OPENAI_API_KEY` |
+| Anthropic | `claude-*` | `ANTHROPIC_API_KEY` |
+| Google Gemini | `gemini-*` | `GEMINI_API_KEY` |
+| Mistral | `mistral-*` | `MISTRAL_API_KEY` |
+| Groq | — | `GROQ_API_KEY` |
+| DeepSeek | `deepseek-*` | `DEEPSEEK_API_KEY` |
+| Together | — | `TOGETHER_API_KEY` |
+| xAI (Grok) | `grok-*` | `XAI_API_KEY` |
+| DashScope (Qwen) | — | `DASHSCOPE_API_KEY` |
+| OpenRouter | everything else | `OPENROUTER_API_KEY` |
+| **Ollama (local)** | `name:tag` (e.g. `qwen2.5-coder:latest`) | *keyless* |
+
+Routing: a model id containing `:` → local Ollama; otherwise by prefix; an explicit `provider`
+field always wins. Set only the keys you have — the rest stay dormant (vendor SDKs load lazily).
+
+---
+
+## Install
+
+Requires **Node ≥ 18** (and a C toolchain, since `node-pty` builds natively).
+
+**Run it without installing — `npx`:**
+
+```bash
+npx ada-agent                      # the client   (published to npm)
+npx -p ada-agent ada-server        # the backend  (second bin in the same package)
+# straight from source, no publish needed:
+npx github:black141312/ada
+```
+
+**Install globally** (puts `ada` and `ada-server` on your PATH):
+
+```bash
+npm install -g ada-agent
+ada
+```
+
+**From a clone** (for hacking on it):
+
+```bash
+git clone https://github.com/black141312/ada.git
+cd ada && npm install
+npm link            # global `ada` / `ada-server`  ·  or `npm start`
+```
+
+> The published-npm commands work once a maintainer has run `npm publish`; the `github:` form works
+> against the repo today.
+
+## Quickstart
+
+ada is two processes: a **backend** (holds keys, routes) and the **`ada`** client.
+
+**Option A — local, no keys (Ollama):**
+
+```bash
+# terminal 1: backend
+ada-server                              # → http://localhost:8787
+
+# terminal 2: the agent
+ada                                     # pick a local model and chat
+```
+
+**Option B — a cloud provider:**
+
+```bash
+# terminal 1
+export ANTHROPIC_API_KEY=sk-ant-...     # and/or OPENAI_API_KEY, GEMINI_API_KEY, …
+ada-server
+
+# terminal 2
+ada --model claude-opus-4-8
+```
+
+Windows PowerShell: `$env:ANTHROPIC_API_KEY="sk-ant-..."`.
+
+---
+
+## Using `ada`
+
+```bash
+ada                      # interactive; pick a model on first run
+ada --tui                # inline TUI front-end
+ada --model <id>         # start on a specific model
+ada --list-models        # everything your keys can reach (via the backend)
+ada --continue           # resume the most recent session
+ada --resume             # pick a session to resume
+ada --yolo               # auto-approve tool calls (skip prompts)
+ada -p "fix the build"   # one-shot: print the answer and exit
+```
+
+**Slash commands** (in a session): `/ask` · `/plan` · `/auto` · `/mode` (cycle the permission mode) ·
+`/run` · `/model [id]` · `/models` · `/reasoning low|medium|high|off` ·
+`/strategy react|single|plan|multi|toolsmith` · `/agent [name]` · `/todos` · `/undo` · `/snapshot` ·
+`/restore` · `/jobs` · `/fork` · `/tree` · `/rewind` · `/compact` · `/context` · `/cost` ·
+`/image <path>` · `/paste` · `/login` · `/logout` · `/exit`.
+
+**Permission modes** — switch with `/ask` · `/plan` · `/auto` (or `/mode` to cycle); the current mode
+shows in the prompt line. In **ask** mode each gated tool prompts with what it wants in plain words
+(`ada wants to run a shell command…`) and one key: `[y]es` · `[a]uto` (run the rest without asking) ·
+`[p]lan` · `[n]o`. **plan** is read-only — ada plans but won't edit; `/run` approves and executes.
+**auto** runs tools without asking (destructive `bash` still confirms). `--yolo` starts in **auto**.
+
+**Subcommands:** `ada mcp …` (connectors) · `ada skill add <url>` · `ada worktree add <name>` ·
+`ada serve` (HTTP API) · `ada share` (view a session) · `ada acp` (editor bridge). See
+[docs/integrations.md](docs/integrations.md) for the HTTP API, the typed SDK, and ACP.
+
+**Orchestration strategies** — the harness runs pluggable agent architectures (`--strategy <name>`
+or `/strategy`): `react` (default loop), `single` (one shot), `plan` (plan→execute), `multi`
+(sub-agent fan-out), and `toolsmith` (read a connected integration's docs and have sub-agents author
+skills for it). See [docs/orchestration.md](docs/orchestration.md).
+
+**Sign in** (optional — identifies you to the backend): run `/login`, choose GitHub or Google, and
+enter the device code in your browser. The token is stored locally and sent as your client key.
+
+## Skills
+
+ada ships with **~285 built-in skills** across ~30 categories — specialized instructions the model
+pulls in only when a task needs them (progressive disclosure). ada **routes** every request with a
+relevance ranker over names + descriptions: when one skill clearly fits, ada **auto-applies** it —
+injecting its procedure so even a weak model follows it (announced as `↳ skill: <name>`); when the
+match is ambiguous it just suggests them. The model can also browse with **`list_skills`** (by
+`category`/`filter`), search with **`find_skill`** (ranked), and load one with **`use_skill`** — so
+nothing bloats the prompt until it's used. A sample of the categories:
+
+`git` · `review` · `testing` · `debugging` · `refactoring` · `docs` · `security` · `ci-cd` ·
+`performance` · `database` · `api` · `frontend` · `ui-design` · `html` · `pptx` · `image` ·
+`graphics` · `languages` · `frameworks` · `mobile` · `cloud` · `observability` · `data-ml` ·
+`agent-llm` · `web3` · `networking` · `shell` · `connectors` · `compliance` · …
+
+Examples: `commit`, `code-review`, `dockerize`, `migration`, `react-hooks`, `terraform-module`,
+`rag-pipeline`, `security-audit`, `project-overview`, `architecture-diagram`, `graphify`, `ponytail`.
+
+Add your own as `SKILL.md` files under `.ada/skills/<name>/` (project) or `~/.ada/skills/<name>/`
+(global) — `---\ndescription: …\ncategory: …\n---` front-matter is all that's required. Project
+skills override global, which override the built-ins. Install remote ones with
+`ada skill add <url>` (a `SKILL.md` or a JSON index); `ada skill list` shows them.
+
+## Connectors (MCP)
+
+ada reaches external tools and data through MCP servers. Browse the catalog and add one:
+
+```bash
+ada mcp                  # list the catalog (filesystem, github, postgres, slack, sentry, …)
+ada mcp add github       # write it into .ada/mcp.json, then set the token it prints
+```
+
+Both **local stdio** servers (`{ command, args }`) and **remote HTTP** servers (`{ url, headers }`)
+are supported; their tools appear as `<server>__<tool>`, approval-gated, in trusted projects. See
+[docs/connectors.md](docs/connectors.md), or the `connectors` skill category for per-connector setup.
+
+## Configuration
+
+**Client** (`ada`):
+
+| Env var | Default | Purpose |
+|---|---|---|
+| `ADA_BACKEND_URL` | `http://localhost:8787/v1` | Where the backend lives |
+| `ADA_CLIENT_KEY` | stored login token, else `dev` | Bearer sent to the backend |
+| `ADA_MODEL` | — | Default model id |
+| `ADA_COMPACT_AT` | `100000` | Token estimate that triggers compaction |
+| `ADA_AUTO_APPROVE` | — | `1` ⇒ behave like `--yolo` |
+| `NO_COLOR` / `ADA_THEME` | — | Disable color / theme overrides |
+
+**Backend** (`ada-server`):
+
+| Env var | Default | Purpose |
+|---|---|---|
+| `ADA_PORT` | `8787` | Listen port |
+| `ADA_CLIENT_KEYS` | *(unset = dev/no-auth)* | Comma-separated allowed client keys |
+| `ADA_REQUIRE_LOGIN` / `ADA_ALLOWED_USERS` | — | Gate access to verified GitHub/Google users |
+| `OLLAMA_BASE_URL` | `http://localhost:11434/v1` | Local Ollama endpoint |
+| *(provider keys)* | — | See the [Providers](#providers) table |
+
+---
+
+## Develop
+
+```bash
+npm run typecheck        # tsc --noEmit
+npm run selfcheck        # offline checks (tools, sessions, routing, parsers, TUI)
+npm start                # run the client from source
+npm run server           # run the backend from source
+```
+
+See **[docs/architecture.md](docs/architecture.md)** for the design (adapters, routing, request
+flow, file layout), **[docs/orchestration.md](docs/orchestration.md)** for the agent strategies, and
+**[docs/integrations.md](docs/integrations.md)** for the HTTP API / SDK / ACP.
+
+## Benchmarks
+
+ada can run **SWE-bench Verified** — it generates patches for real GitHub issues (one isolated repo
+clone per task), emitting an official-format `predictions.jsonl` that the official `swebench` Docker
+harness scores. `node bench/swebench.mjs --dataset … --model … --out runs/x`. See
+**[bench/README.md](bench/README.md)** for the full flow (dataset, prereqs, scoring command).
+
+## Contributing
+
+Issues and PRs welcome — it's a small, no-build codebase. Run `npm run typecheck && npm run selfcheck`
+before a PR and keep changes lean. See **[CONTRIBUTING.md](CONTRIBUTING.md)**; report vulnerabilities
+via **[SECURITY.md](SECURITY.md)**.
+
+## License
+
+[MIT](LICENSE) © 2026 Aditya

package/bench/README.md

@@ -0,0 +1,88 @@
+# Benchmarking ada on SWE-bench Verified
+
+ada can run **SWE-bench Verified** — give the agent a real GitHub issue, let it edit the repo, and
+score whether the repo's test suite passes. This directory has the **generation** half (ada produces
+patches); **scoring** is the official `swebench` Docker harness — we don't reimplement it, because
+that's the only way to get correct, comparable numbers.
+
+```
+ dataset (issues) ──▶ bench/swebench.mjs ──▶ predictions.jsonl ──▶ official swebench eval ──▶ resolved %
+                        (ada edits the repo,                         (Docker: apply patch +
+                         per isolated clone)                          test_patch, run tests)
+```
+
+## Prerequisites
+
+- **ada-server running with provider keys** — the harness drives `ada -p`, which needs the backend:
+  ```bash
+  export ANTHROPIC_API_KEY=sk-ant-...      # and/or OPENAI_API_KEY, etc.
+  ada-server                                # http://localhost:8787
+  ```
+- `git` + network (the harness clones each task repo; clones are cached under `~/.cache/ada-swebench`).
+- For scoring: **Docker** and the **`swebench`** Python package (`pip install swebench`). Allow plenty
+  of disk — the official images are large.
+
+## 1. Get the dataset
+
+SWE-bench Verified (500 instances) lives on Hugging Face. Export it to JSONL once:
+
+```python
+# pip install datasets
+from datasets import load_dataset
+load_dataset("princeton-nlp/SWE-bench_Verified", split="test").to_json("swe-bench-verified.jsonl")
+```
+
+## 2. Generate predictions with ada
+
+```bash
+# smoke test on 5 instances first
+node bench/swebench.mjs --dataset swe-bench-verified.jsonl --model claude-opus-4-8 \
+     --out runs/opus --limit 5 --concurrency 2
+
+# a specific instance, or the whole set
+node bench/swebench.mjs --dataset swe-bench-verified.jsonl --model claude-opus-4-8 \
+     --out runs/opus --instances astropy__astropy-12907
+```
+
+For each instance it clones the repo at `base_commit` into an isolated dir, hands ada the issue text
+(`ada -p … --json`, auto-approve), captures `git diff` as the model patch, and appends an
+official-format line to `runs/opus/predictions.jsonl`:
+
+```json
+{"instance_id": "...", "model_name_or_path": "claude-opus-4-8", "model_patch": "diff --git ..."}
+```
+
+It also writes `meta.jsonl` (seconds, patch size, token/cost usage per instance). Re-running **resumes**
+— instances already in `predictions.jsonl` are skipped. Flags: `--limit N`, `--instances a,b`,
+`--concurrency` (default 2), `--timeout` seconds per instance (default 1200), `--out <dir>`.
+
+Swap `--model` to compare models on the same tasks (`gpt-...`, `qwen2.5-coder:latest`, …) — ada routes
+each to the right provider.
+
+## 3. Score with the official harness
+
+```bash
+python -m swebench.harness.run_evaluation \
+  --dataset_name princeton-nlp/SWE-bench_Verified \
+  --predictions_path runs/opus/predictions.jsonl \
+  --max_workers 4 --run_id ada-opus
+```
+
+It applies each patch + the held-out `test_patch` in Docker, runs the `FAIL_TO_PASS` / `PASS_TO_PASS`
+tests, and reports the **resolved rate** plus a per-instance breakdown.
+
+## Notes & honest caveats
+
+- ada is told **not to touch tests** (the grader supplies its own); the patch is whatever ada changed
+  in the source.
+- An empty patch (ada gave up / errored) is still recorded — it just counts as unresolved.
+- This measures ada's default `react` loop. Try `ADA_MODEL`, a different `--model`, or wire a
+  `--strategy` into the harness to compare setups.
+- Other benchmarks (HumanEval, Aider polyglot) fit the same generate-then-score shape; ask and we'll
+  add a sibling script.
+
+## Quick check
+
+```bash
+node bench/swebench.mjs --selftest     # offline: validates the prompt/prediction/arg helpers
+```

package/bench/swebench.mjs

@@ -0,0 +1,242 @@
+#!/usr/bin/env node
+// SWE-bench (Verified) prediction generator, driven by ada.
+//
+// This produces an **official-format** predictions.jsonl. It does NOT score — scoring is done by the
+// official `swebench` harness in Docker (the only way to get correct, comparable numbers). See
+// bench/README.md for the full flow (dataset, prereqs, the scoring command).
+//
+// For each instance: clone the task repo at its base commit into an isolated dir, hand ada the issue
+// text (headless `ada -p --json`, auto-approve), then capture `git diff` as the model patch.
+//
+//   node bench/swebench.mjs --dataset swe-bench-verified.jsonl --model claude-opus-4-8 \
+//        --out runs/opus [--limit 5] [--instances id1,id2] [--concurrency 2] [--timeout 1200]
+//   node bench/swebench.mjs --selftest      # offline checks of the pure helpers
+//
+// Prereqs: a running `ada-server` with provider keys, `git`, network (clones the task repos).
+
+import { spawn, spawnSync } from "node:child_process";
+import { appendFileSync, existsSync, mkdirSync, readFileSync, rmSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import assert from "node:assert/strict";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const ADA_BIN = resolve(HERE, "..", "bin", "ada.mjs");
+const CACHE = process.env.ADA_SWEBENCH_CACHE || join(homedir(), ".cache", "ada-swebench");
+
+// ---------- pure helpers (covered by --selftest) ----------
+
+export function parseArgs(argv) {
+  const f = { concurrency: 2, timeout: 1200, out: "runs/ada" };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--selftest") f.selftest = true;
+    else if (a === "--dataset") f.dataset = argv[++i];
+    else if (a === "--model") f.model = argv[++i];
+    else if (a === "--out") f.out = argv[++i];
+    else if (a === "--limit") f.limit = Number(argv[++i]);
+    else if (a === "--instances") f.instances = String(argv[++i]).split(",").map((s) => s.trim()).filter(Boolean);
+    else if (a === "--concurrency") f.concurrency = Math.max(1, Number(argv[++i]) || 1);
+    else if (a === "--timeout") f.timeout = Number(argv[++i]);
+    else if (a === "--ada") f.ada = argv[++i];
+  }
+  return f;
+}
+
+export function buildPrompt(repo, problemStatement) {
+  return `The repository \`${repo}\` is checked out in the current directory at the commit where this issue was filed. Resolve the issue by editing the source code.
+
+ISSUE:
+${problemStatement}
+
+Guidelines:
+- Make the smallest change that fixes the issue.
+- Edit only library/source files. Do NOT add or modify tests — the grader supplies its own.
+- When the fix is complete and self-consistent, stop.`;
+}
+
+export function predictionLine(instanceId, model, patch) {
+  return JSON.stringify({ instance_id: instanceId, model_name_or_path: model, model_patch: patch });
+}
+
+function loadJsonl(path) {
+  return readFileSync(path, "utf8")
+    .split("\n")
+    .map((l) => l.trim())
+    .filter(Boolean)
+    .map((l) => JSON.parse(l));
+}
+
+export function doneIds(predPath) {
+  if (!existsSync(predPath)) return new Set();
+  const ids = new Set();
+  for (const row of loadJsonl(predPath)) if (row.instance_id) ids.add(row.instance_id);
+  return ids;
+}
+
+export function selectInstances(all, { instances, limit }) {
+  let xs = all;
+  if (instances?.length) {
+    const want = new Set(instances);
+    xs = xs.filter((x) => want.has(x.instance_id));
+  }
+  if (limit && limit > 0) xs = xs.slice(0, limit);
+  return xs;
+}
+
+// ---------- git + ada (impure) ----------
+
+const cloneLocks = new Map(); // repo → in-flight clone promise (don't clone the same repo twice)
+function git(args, opts = {}) {
+  return spawnSync("git", args, { encoding: "utf8", ...opts });
+}
+
+async function ensureCache(repo) {
+  const bare = join(CACHE, `${repo.replace("/", "__")}.git`);
+  if (existsSync(bare)) return bare;
+  if (!cloneLocks.has(repo)) {
+    mkdirSync(CACHE, { recursive: true });
+    cloneLocks.set(
+      repo,
+      new Promise((res, rej) => {
+        const p = spawn("git", ["clone", "--bare", `https://github.com/${repo}.git`, bare], { stdio: "inherit" });
+        p.on("exit", (code) => (code === 0 ? res(bare) : rej(new Error(`clone ${repo} failed (${code})`))));
+        p.on("error", rej);
+      }),
+    );
+  }
+  return cloneLocks.get(repo);
+}
+
+async function prepInstance(repo, baseCommit, dir) {
+  const bare = await ensureCache(repo);
+  rmSync(dir, { recursive: true, force: true });
+  // --shared: instance dirs reuse the cache's objects (cheap, isolated working trees). Safe because
+  // we delete each dir before the cache is ever pruned.
+  let r = git(["clone", "--shared", "--no-checkout", bare, dir]);
+  if (r.status !== 0) throw new Error(`clone --shared failed: ${r.stderr}`);
+  r = git(["-C", dir, "checkout", "--detach", baseCommit]);
+  if (r.status !== 0) throw new Error(`checkout ${baseCommit.slice(0, 8)} failed: ${r.stderr}`);
+}
+
+function diffPatch(dir) {
+  git(["-C", dir, "add", "-A"]);
+  const r = git(["-C", dir, "diff", "--cached", "--no-color"]);
+  return r.stdout ?? "";
+}
+
+function runAda(adaBin, prompt, cwd, model, timeoutMs) {
+  return new Promise((res) => {
+    const child = spawn(process.execPath, [adaBin, "-p", prompt, "--model", model, "--json"], { cwd, env: process.env });
+    let out = "";
+    let err = "";
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      child.kill("SIGKILL");
+    }, timeoutMs);
+    child.stdout.on("data", (d) => (out += d));
+    child.stderr.on("data", (d) => (err += d));
+    child.on("exit", (code) => {
+      clearTimeout(timer);
+      let usage = "";
+      const line = out.split("\n").reverse().find((l) => l.trim().startsWith("{"));
+      try {
+        usage = line ? JSON.parse(line).usage ?? "" : "";
+      } catch {
+        /* ignore */
+      }
+      res({ code, timedOut, usage, err: err.slice(-500) });
+    });
+    child.on("error", (e) => {
+      clearTimeout(timer);
+      res({ code: -1, timedOut, usage: "", err: String(e) });
+    });
+  });
+}
+
+// ---------- run ----------
+
+async function pool(items, n, worker) {
+  const q = [...items.entries()];
+  const runners = Array.from({ length: Math.min(n, q.length) }, async () => {
+    for (;;) {
+      const next = q.shift();
+      if (!next) return;
+      await worker(next[1], next[0]);
+    }
+  });
+  await Promise.all(runners);
+}
+
+async function main(f) {
+  if (!f.dataset || !f.model) {
+    console.error("usage: node bench/swebench.mjs --dataset <verified.jsonl> --model <id> [--out dir] [--limit N] [--instances a,b] [--concurrency 2] [--timeout 1200]");
+    process.exit(2);
+  }
+  const adaBin = f.ada || ADA_BIN;
+  const outDir = resolve(f.out);
+  mkdirSync(outDir, { recursive: true });
+  const predPath = join(outDir, "predictions.jsonl");
+  const metaPath = join(outDir, "meta.jsonl");
+
+  const already = doneIds(predPath);
+  const todo = selectInstances(loadJsonl(f.dataset), f).filter((x) => !already.has(x.instance_id));
+  console.error(`ada SWE-bench · model=${f.model} · ${todo.length} instances (${already.size} already done) · concurrency=${f.concurrency} → ${outDir}`);
+
+  let done = 0;
+  let nonEmpty = 0;
+  await pool(todo, f.concurrency, async (inst) => {
+    const dir = join(CACHE, "wt", inst.instance_id);
+    const t0 = Date.now();
+    let patch = "";
+    let note = "";
+    try {
+      await prepInstance(inst.repo, inst.base_commit, dir);
+      const r = await runAda(adaBin, buildPrompt(inst.repo, inst.problem_statement), dir, f.model, f.timeout * 1000);
+      patch = diffPatch(dir);
+      note = r.timedOut ? "timeout" : r.code === 0 ? `usage:${r.usage}` : `exit ${r.code}: ${r.err}`;
+    } catch (e) {
+      note = `error: ${e instanceof Error ? e.message : e}`;
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+    appendFileSync(predPath, `${predictionLine(inst.instance_id, f.model, patch)}\n`);
+    appendFileSync(metaPath, `${JSON.stringify({ instance_id: inst.instance_id, seconds: Math.round((Date.now() - t0) / 1000), patch_bytes: patch.length, note })}\n`);
+    done++;
+    if (patch.trim()) nonEmpty++;
+    console.error(`  [${done}/${todo.length}] ${inst.instance_id} · ${patch.length}B patch · ${note.slice(0, 60)}`);
+  });
+
+  console.error(`\nwrote ${predPath}\n${done} run, ${nonEmpty} produced a non-empty patch. Score with the official harness — see bench/README.md.`);
+}
+
+// ---------- selftest ----------
+
+function runSelftest() {
+  const a = parseArgs(["--dataset", "d.jsonl", "--model", "m", "--limit", "3", "--instances", "x,y", "--concurrency", "4"]);
+  assert.equal(a.dataset, "d.jsonl");
+  assert.equal(a.model, "m");
+  assert.equal(a.limit, 3);
+  assert.deepEqual(a.instances, ["x", "y"]);
+  assert.equal(a.concurrency, 4);
+
+  const p = buildPrompt("django/django", "Boom on empty queryset.");
+  assert.ok(p.includes("django/django") && p.includes("Boom on empty queryset.") && /do not add or modify tests/i.test(p), "prompt includes repo, issue, no-tests rule");
+
+  const line = predictionLine("django__django-123", "claude-opus-4-8", "diff --git a b");
+  const obj = JSON.parse(line);
+  assert.deepEqual(Object.keys(obj).sort(), ["instance_id", "model_name_or_path", "model_patch"]);
+  assert.equal(obj.instance_id, "django__django-123");
+
+  const all = [{ instance_id: "a" }, { instance_id: "b" }, { instance_id: "c" }];
+  assert.deepEqual(selectInstances(all, { instances: ["b", "c"], limit: 1 }).map((x) => x.instance_id), ["b"]);
+  assert.deepEqual(selectInstances(all, { limit: 2 }).map((x) => x.instance_id), ["a", "b"]);
+
+  console.log("swebench selftest OK");
+}
+
+const flags = parseArgs(process.argv.slice(2));
+if (flags.selftest) runSelftest();
+else await main(flags);

package/bin/ada-server.mjs

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+// ada backend — the routing server that holds provider keys. Same no-build launcher.
+import { register } from "tsx/esm/api";
+
+register();
+await import(new URL("../src/server/index.ts", import.meta.url));

package/bin/ada.mjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+// ada — terminal coding agent. Registers the tsx loader so the TypeScript client
+// runs with no build step, then hands off to the CLI entrypoint (which self-runs).
+import { register } from "tsx/esm/api";
+
+register();
+await import(new URL("../src/client/cli.ts", import.meta.url));