ada-agent 0.3.1 → 0.5.0

package/README.md

@@ -158,9 +158,10 @@ shows in the prompt line. In **ask** mode each gated tool prompts with what it w
 **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 catalog [provider]` (offline model/price catalog) · `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.
+`ada catalog [provider]` (offline model/price catalog) · `ada serve` (HTTP API — one-shot **and**
+Cursor-style streaming sessions for building ada into your own IDE) · `ada share` (view a session) ·
+`ada acp` (editor bridge). See [docs/integrations.md](docs/integrations.md) for the HTTP API
+(including live SSE sessions with approval gating), 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`

package/docs/integrations.md

@@ -9,20 +9,80 @@ build, an IdP) are described with what they'd take — they can't be "live" with
 ```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)
+- `GET /health` → `{ ok, model, sessions }`
+- `POST /v1/prompt` `{ "text": "...", "model"?: "..." }` → `{ text, usage }` — **one-shot**: a fresh
+  agent + fresh session per call, no memory between calls. Good for a "generate this" button, not a
+  chat panel.
+
+### Building a Cursor-style agent panel (an IDE integration)
+
+For a real agent panel — persistent conversation, live streamed output, visible tool calls, and
+edits that pause for **your own** approval UI instead of auto-running — use the **interactive
+session** endpoints instead. This is the intended integration point for a custom IDE/editor, in any
+language, over plain HTTP + Server-Sent Events:
+
+```
+GET  /v1/sessions                        → { sessions: [{ file, title, mtime, parent? }, …] }
+POST /v1/sessions {"resume"?: "latest"|"<file>"} → { sessionId, model, file, resumed }
+POST /v1/sessions/:id/prompt {"text":…, "images"?: [dataURL|https…]}
+                                         → SSE stream of events (see below), until "done"
+                                           (409 if a turn is already running on this session)
+POST /v1/sessions/:id/approve {"id":…, "decision":"yes"|"all"|"no"}
+POST /v1/sessions/:id/abort              → cancel the running turn ("stop generating"); also
+                                           denies any approval it was parked on
+POST /v1/sessions/:id/steer {"text":…}   → queue a mid-turn user message (409 when idle)
+PATCH /v1/sessions/:id {"mode":"ask"|"plan"|"auto"} → switch the permission mode live
+DELETE /v1/sessions/:id                  → free the session (does not delete the transcript)
+```
+
+The session holds one persistent `Agent` — history, model, and skill/tool state carry across every
+`/prompt` call. Each `/prompt` call streams one event per SSE frame (`data: {...}\n\n`):
+
+| `type` | Fields | Meaning |
+|---|---|---|
+| `text` | `delta` | A chunk of the assistant's reply |
+| `tool_call` | `name`, `detail` | A tool is about to run |
+| `tool_result` | `name`, `output`, `isError` | It finished |
+| `approval_request` | `id`, `name`, `summary` | **Blocks** until you POST `.../approve` with this `id` — this is where your IDE shows its own "allow this edit?" UI |
+| `done` | `text`, `usage` | Turn complete |
+| `error` | `message` | The turn failed (e.g. upstream unreachable) |
+
+Sessions default to `autoApprove: false` (unlike the one-shot `/v1/prompt`, which auto-approves
+everything) — every gated tool call (file writes, destructive shell, …) fires `approval_request` and
+waits for your response. If no `/prompt` stream is currently open when an approval is needed, it's
+declined (fails closed, never runs silently).
+
+**Resuming after a restart.** Sessions live in memory, so a `sessionId` doesn't survive `ada serve`
+restarting — but every session's conversation is also persisted to an on-disk transcript
+(`.ada/sessions/*.jsonl`), same as the CLI's own sessions. `GET /v1/sessions` lists them (newest
+first); pass `resume: "latest"` or a specific `file` from that list to `POST /v1/sessions` to spin up
+a **new** in-memory session seeded with that history — the conversation picks up right where it left
+off. Verified live: kill `ada serve` mid-conversation, restart it, resume, and the model still recalls
+what was said before the restart.
 
 ## Typed SDK — `src/sdk`
 
 ```ts
 import { createClient } from "ada-agent/sdk"; // in-repo: "./src/sdk/index.ts"
 const ada = createClient("http://localhost:8788");
-console.log(await ada.health());
+
+// one-shot
 const { text } = await ada.prompt("list the files in this project");
+
+// interactive — the IDE integration point
+const session = await ada.session({ model: "claude-opus-4-8" });
+await session.prompt("refactor foo.ts to use async/await", (e) => {
+  if (e.type === "text") process.stdout.write(e.delta);
+  if (e.type === "tool_call") console.log(`→ ${e.name} ${e.detail}`);
+  if (e.type === "approval_request") session.approve(e.id, myOwnConfirmUi(e) ? "yes" : "no");
+  if (e.type === "done") console.log("\n" + e.usage);
+});
+await session.close();
 ```
 
-It's a ~30-line `fetch` wrapper over the HTTP API above — if you'd rather not pull in the source,
-just POST to `/v1/prompt` directly.
+It's a `fetch`-based wrapper (manual SSE parsing, no dependency) over the HTTP API above — if you'd
+rather not pull in the source, or your IDE isn't Node/TypeScript, talk to the same endpoints directly
+from any HTTP client that can read a chunked response (Java, Python, Rust, a browser, …).
 
 ## ACP bridge — `ada acp`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ada-agent",
-  "version": "0.3.1",
+  "version": "0.5.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",

package/src/client/agent-server.ts

@@ -0,0 +1,53 @@
+// Pure helpers for ada's HTTP+SSE agent service (the session endpoints on `ada serve`). Kept
+// separate from cli.ts's route wiring so the tricky bits — SSE framing, id generation, and
+// approval correlation — are unit-testable offline, with no live model required.
+
+import type { ApprovalDecision } from "./agent.ts";
+
+/** Format one Server-Sent Events frame for a JSON-serializable event. */
+export function sseFrame(event: unknown): string {
+  return `data: ${JSON.stringify(event)}\n\n`;
+}
+
+let seq = 0;
+/** A short, process-unique id (session id, approval-request id, …). */
+export function newId(prefix: string): string {
+  seq++;
+  return `${prefix}_${Date.now().toString(36)}${seq.toString(36)}`;
+}
+
+/**
+ * Correlates a mid-turn approval request with the IDE's later response. `wait()` is called from
+ * inside the Agent's onApprove callback (which is blocked on the returned promise); `settle()` is
+ * called from the POST .../approve handler once the IDE's user has decided.
+ */
+export class ApprovalRegistry {
+  private pending = new Map<string, (d: ApprovalDecision) => void>();
+
+  wait(): { id: string; promise: Promise<ApprovalDecision> } {
+    const id = newId("appr");
+    const promise = new Promise<ApprovalDecision>((resolve) => this.pending.set(id, resolve));
+    return { id, promise };
+  }
+
+  /** Resolve a pending approval by id. False if the id is unknown (already settled, or bogus). */
+  settle(id: string, decision: ApprovalDecision): boolean {
+    const resolve = this.pending.get(id);
+    if (!resolve) return false;
+    this.pending.delete(id);
+    resolve(decision);
+    return true;
+  }
+
+  /** Deny every pending approval — an aborted turn must not stay parked on an unanswered prompt. */
+  abortAll(): number {
+    const n = this.pending.size;
+    for (const resolve of this.pending.values()) resolve("no");
+    this.pending.clear();
+    return n;
+  }
+
+  get size(): number {
+    return this.pending.size;
+  }
+}

package/src/client/agent.ts

@@ -15,7 +15,14 @@ import { routeConfident, routeSkills } from "./skills.ts";
 import { Session } from "./session.ts";
 
 type Msg = OpenAI.Chat.Completions.ChatCompletionMessageParam;
-type SendCtrl = { signal?: AbortSignal; steer?: string[]; quiet?: boolean; images?: string[]; onReplyStart?: () => void };
+/** Structured turn events — for a caller (e.g. an IDE service) that wants more than plain text.
+ *  When `onEvent` is set on SendCtrl, `send()` emits these instead of writing to stdout. */
+export type AgentEvent =
+  | { type: "text"; delta: string }
+  | { type: "tool_call"; callId: string; name: string; detail: string }
+  | { type: "tool_result"; callId: string; name: string; output: string; isError: boolean }
+  | { type: "done"; text: string; usage: string };
+type SendCtrl = { signal?: AbortSignal; steer?: string[]; quiet?: boolean; images?: string[]; onReplyStart?: () => void; onEvent?: (e: AgentEvent) => void };
 type ToolCall = { id: string; name: string; args: string };
 type StepResult = { content: string; toolCalls: ToolCall[] };
 type ToolDef = OpenAI.Chat.Completions.ChatCompletionTool;
@@ -493,6 +500,10 @@ export class Agent {
   async send(input: string, ctrl?: SendCtrl): Promise<string> {
     let replyStarted = false;
     const say = (s: string): void => {
+      if (ctrl?.onEvent) {
+        if (s.trim()) ctrl.onEvent({ type: "text", delta: s });
+        return;
+      }
       if (ctrl?.quiet) return;
       if (!replyStarted && s.trim()) {
         replyStarted = true;
@@ -539,6 +550,7 @@ export class Agent {
 
     const engine = this.makeEngine(ctrl, say, interrupted, drainSteer);
     await (ORCHESTRATORS[this.strategy] ?? reAct).run(engine);
+    ctrl?.onEvent?.({ type: "done", text: this.lastAssistant, usage: this.usageReport() });
     return this.lastAssistant;
   }
 
@@ -642,6 +654,7 @@ export class Agent {
               calls[tc.index] = entry;
             }
             if (tc.id) entry.id = tc.id;
+            else if (!entry.id) entry.id = `call_${tc.index}`; // some backends omit streamed ids — consumers key events on callId
             if (tc.function?.name) entry.name += tc.function.name;
             if (tc.function?.arguments) entry.args += tc.function.arguments;
           }
@@ -687,12 +700,14 @@ export class Agent {
    *  append one tool message per call. */
   private async execTools(toolCalls: ToolCall[], ctrl: SendCtrl | undefined, say: (s: string) => void): Promise<void> {
     const signal = ctrl?.signal;
-    const printCall = (name: string, args: Record<string, unknown>): void => {
+    const printCall = (callId: string, name: string, args: Record<string, unknown>): void => {
       const d = describeCall(name, args);
       const detail = d.detail ? ` ${d.detail.length > 100 ? `${d.detail.slice(0, 99)}…` : d.detail}` : "";
+      ctrl?.onEvent?.({ type: "tool_call", callId, name, detail: d.detail });
       say(`\n\x1b[2m• ${name}${detail}\x1b[0m\n`);
     };
-    const printResult = (r: ToolResult): void => {
+    const printResult = (callId: string, name: string, r: ToolResult): void => {
+      ctrl?.onEvent?.({ type: "tool_result", callId, name, output: r.output, isError: !!r.isError });
       if (r.display) say(`${r.display}\n`);
       else if (r.isError) say(`\x1b[31m  ${r.output.split("\n")[0]}\x1b[0m\n`);
     };
@@ -720,15 +735,15 @@ export class Agent {
         continue;
       }
       if (!tool) {
-        printCall(c.name, args);
+        printCall(c.id, c.name, args);
         results[i] = { output: `Unknown tool: ${c.name}`, isError: true };
         continue;
       }
       const perm = permissionFor(c.name, summarize(args)); // configured allow/ask/deny rule, if any
       if (perm === "deny") {
-        printCall(c.name, args);
+        printCall(c.id, c.name, args);
         results[i] = { output: "Denied by permission policy.", isError: true };
-        printResult(results[i]!);
+        printResult(c.id, c.name, results[i]!);
         continue;
       }
       if (!tool.needsApproval && perm !== "ask") {
@@ -736,10 +751,10 @@ export class Agent {
         continue;
       }
       // gated tool (or a rule forces "ask") → sequential (so prompts and same-file writes don't race)
-      printCall(c.name, args);
+      printCall(c.id, c.name, args);
       if (this.planMode && tool.needsApproval) {
         results[i] = { output: "Plan mode: not executing — finish the plan; the user approves with /run." };
-        printResult(results[i]!);
+        printResult(c.id, c.name, results[i]!);
         continue;
       }
       const forceConfirm = c.name === "bash" && isDestructive(String(args.command ?? ""));
@@ -757,15 +772,15 @@ export class Agent {
           results[i] = await runTool(tool, c.name, args);
         }
       }
-      printResult(results[i]!);
+      printResult(c.id, c.name, results[i]!);
     }
     await Promise.all(
       parallel.map(async (i) => {
         const c = toolCalls[i]!;
         const args = argsOf(c.args);
-        printCall(c.name, args);
+        printCall(c.id, c.name, args);
         results[i] = await runTool(toolByName.get(c.name)!, c.name, args);
-        printResult(results[i]!);
+        printResult(c.id, c.name, results[i]!);
       }),
     );
     for (let i = 0; i < toolCalls.length; i++) {

package/src/client/cli.ts

@@ -7,7 +7,8 @@ import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { stdin, stdout } from "node:process";
 import OpenAI from "openai";
-import { Agent, type ApprovalDecision, type OnApprove } from "./agent.ts";
+import { Agent, type AgentEvent, type ApprovalDecision, type OnApprove } from "./agent.ts";
+import { ApprovalRegistry, newId, sseFrame } from "./agent-server.ts";
 import { expandPrompt, loadPrompts } from "./prompts.ts";
 import { Session, list, type SessionMeta } from "./session.ts";
 import { deleteCredential, getCredential, listCredentials } from "../server/credentials.ts";
@@ -501,6 +502,11 @@ const NO_BACKEND = new Set(["mcp", "skill", "worktree", "wt", "catalog", "share"
 
 async function main(): Promise<void> {
   const sub = process.argv[2];
+  if (sub === "--version" || sub === "-v" || sub === "version") {
+    // Before anything else — must not auto-start a backend just to print a version.
+    console.log(`ada ${adaVersion()}`);
+    return;
+  }
   if (sub === "login" || sub === "logout") {
     await authCommand(sub, process.argv[3]);
     return;
@@ -642,9 +648,10 @@ async function main(): Promise<void> {
     return;
   }
   if (sub === "acp") {
-    // Minimal Agent Client Protocol bridge over stdio (JSON-RPC 2.0, newline-delimited). Scaffold:
-    // handles initialize + prompt so an ACP-aware editor can drive ada. Extend method names/framing
-    // to match your client's ACP version.
+    // Agent Client Protocol bridge over stdio (JSON-RPC 2.0, newline-delimited). Handles
+    // initialize / session/new / session/prompt, and streams session/update notifications
+    // (agent_message_chunk + tool_call/tool_call_update) while a turn runs — the shape ACP editors
+    // like Zed render live. Still experimental until exercised against a real ACP client.
     const trusted = isTrusted(process.cwd());
     const settings = loadSettings(trusted);
     await loadExtensions(trusted);
@@ -661,6 +668,9 @@ async function main(): Promise<void> {
     }
     const agent = new Agent({ client, model, session: Session.create(), onApprove: async (): Promise<ApprovalDecision> => "yes", autoApprove: true, project: trusted, compactAt: settings.compactAt });
     const send = (msg: object): void => void stdout.write(`${JSON.stringify(msg)}\n`);
+    const ACP_SESSION = newId("acp");
+    const update = (update: object): void => send({ jsonrpc: "2.0", method: "session/update", params: { sessionId: ACP_SESSION, update } });
+    let acpCtrl: AbortController | null = null; // the in-flight prompt's abort handle (session/cancel)
     let buf = "";
     stdin.on("data", async (d) => {
       buf += d.toString("utf8");
@@ -676,16 +686,29 @@ async function main(): Promise<void> {
           continue;
         }
         if (msg.method === "initialize") send({ jsonrpc: "2.0", id: msg.id, result: { protocolVersion: 1, agentCapabilities: { promptCapabilities: {} } } });
-        else if (msg.method === "session/new" || msg.method === "newSession") send({ jsonrpc: "2.0", id: msg.id, result: { sessionId: "ada" } });
-        else if (msg.method === "session/prompt" || msg.method === "prompt") {
+        else if (msg.method === "session/new" || msg.method === "newSession") send({ jsonrpc: "2.0", id: msg.id, result: { sessionId: ACP_SESSION } });
+        else if (msg.method === "session/cancel" || msg.method === "cancel") {
+          acpCtrl?.abort();
+          if (msg.id != null) send({ jsonrpc: "2.0", id: msg.id, result: {} });
+        } else if (msg.method === "session/prompt" || msg.method === "prompt") {
           const p = msg.params ?? {};
           const blocks = (p.prompt ?? p.text) as unknown;
           const text = Array.isArray(blocks) ? blocks.map((b) => (b as { text?: string }).text ?? "").join("") : String(blocks ?? "");
+          acpCtrl = new AbortController();
           try {
-            const out = await agent.send(text, { quiet: true });
-            send({ jsonrpc: "2.0", id: msg.id, result: { stopReason: "end_turn", content: [{ type: "text", text: out }] } });
+            await agent.send(text, {
+              signal: acpCtrl.signal,
+              onEvent: (e: AgentEvent) => {
+                if (e.type === "text") update({ sessionUpdate: "agent_message_chunk", content: { type: "text", text: e.delta } });
+                else if (e.type === "tool_call") update({ sessionUpdate: "tool_call", toolCallId: e.callId, title: `${e.name} ${e.detail}`.trim(), status: "in_progress" });
+                else if (e.type === "tool_result") update({ sessionUpdate: "tool_call_update", toolCallId: e.callId, status: e.isError ? "failed" : "completed" });
+              },
+            });
+            send({ jsonrpc: "2.0", id: msg.id, result: { stopReason: acpCtrl.signal.aborted ? "cancelled" : "end_turn" } });
           } catch (e) {
             send({ jsonrpc: "2.0", id: msg.id, error: { code: -32000, message: e instanceof Error ? e.message : String(e) } });
+          } finally {
+            acpCtrl = null;
           }
         } else if (msg.id != null) send({ jsonrpc: "2.0", id: msg.id, result: {} });
       }
@@ -727,13 +750,54 @@ async function main(): Promise<void> {
       }
     }
     const port = Number(process.env.ADA_HTTP_PORT) || 8788;
+
+    // Interactive sessions — for driving ada like an IDE agent panel (live text/tool-call events,
+    // and edits pause for YOUR approval UI instead of auto-running). See docs/integrations.md.
+    interface AgentSession {
+      agent: Agent;
+      registry: ApprovalRegistry;
+      emit: ((frame: string) => void) | null; // set only while a /prompt request's SSE stream is open
+      file: string; // the on-disk transcript — survives an `ada serve` restart; resume with it
+      ctrl: AbortController | null; // set while a turn runs — doubles as the busy flag
+      steer: string[]; // queued mid-turn user messages, drained by the agent between steps
+      mode: "ask" | "plan" | "auto";
+    }
+    const sessions = new Map<string, AgentSession>();
+    // `resumeFile` reattaches to an existing on-disk transcript (e.g. after `ada serve` restarted) —
+    // its history replays into the new in-memory Agent so the conversation picks up where it left off.
+    const makeSession = (m: string, resumeFile?: string): { id: string; rec: AgentSession } => {
+      const session = resumeFile ? Session.open(resumeFile) : Session.create();
+      const history = resumeFile ? (session.load() as unknown as Msg[]) : undefined;
+      const rec: AgentSession = { agent: undefined as unknown as Agent, registry: new ApprovalRegistry(), emit: null, file: session.file, ctrl: null, steer: [], mode: "ask" };
+      rec.agent = new Agent({
+        client,
+        model: m,
+        session,
+        history,
+        project: trusted,
+        compactAt: settings.compactAt,
+        autoApprove: false,
+        onApprove: async (toolName, summary): Promise<ApprovalDecision> => {
+          if (!rec.emit) return "no"; // no open stream to ask through — fail closed, don't silently run
+          const { id, promise } = rec.registry.wait();
+          rec.emit(sseFrame({ type: "approval_request", id, name: toolName, summary }));
+          return promise;
+        },
+      });
+      const id = newId("sess");
+      sessions.set(id, rec);
+      return { id, rec };
+    };
+
     const { createServer } = await import("node:http");
     createServer((req, res) => {
-      if (req.method === "GET" && (req.url === "/health" || req.url === "/")) {
-        res.writeHead(200, { "content-type": "application/json" }).end(JSON.stringify({ ok: true, model }));
+      const url = new URL(req.url ?? "/", "http://localhost");
+      if (req.method === "GET" && (url.pathname === "/health" || url.pathname === "/")) {
+        res.writeHead(200, { "content-type": "application/json" }).end(JSON.stringify({ ok: true, model, sessions: sessions.size }));
         return;
       }
-      if (req.method === "POST" && req.url === "/v1/prompt") {
+      // One-shot, no memory between calls — good for a "generate this" action, not a chat panel.
+      if (req.method === "POST" && url.pathname === "/v1/prompt") {
         let body = "";
         req.on("data", (c) => (body += c));
         req.on("end", async () => {
@@ -748,8 +812,207 @@ async function main(): Promise<void> {
         });
         return;
       }
+      // Interactive: persistent session, streamed events, approval round-trip.
+      // List on-disk transcripts (survive an `ada serve` restart) so an IDE can offer "resume".
+      if (req.method === "GET" && url.pathname === "/v1/sessions") {
+        res.writeHead(200, { "content-type": "application/json" }).end(JSON.stringify({ sessions: list() }));
+        return;
+      }
+      if (req.method === "POST" && url.pathname === "/v1/sessions") {
+        let body = "";
+        req.on("data", (c) => (body += c));
+        req.on("end", () => {
+          let m = model;
+          let resume: string | undefined;
+          try {
+            const j = JSON.parse(body || "{}") as { model?: string; resume?: string };
+            m = j.model || model;
+            // "latest" picks the most recently modified transcript; otherwise resume expects one of
+            // the `file` values from GET /v1/sessions (a restarted `ada serve` has no memory of which
+            // in-memory sessionIds existed before, so the IDE re-resolves by transcript file instead).
+            if (j.resume === "latest") resume = list()[0]?.file;
+            else if (j.resume && list().some((s) => s.file === j.resume)) resume = j.resume;
+          } catch {
+            /* ignore, use default model + no resume */
+          }
+          if (resume) {
+            // A live in-memory session may still be appending to that transcript (e.g. the IDE lost
+            // its SSE stream and *assumed* a restart) — two Agents on one JSONL interleave twin
+            // conversations. Point the caller at the live session instead of forking the file.
+            const live = [...sessions.entries()].find(([, r]) => r.file === resume);
+            if (live) {
+              res.writeHead(409, { "content-type": "application/json" }).end(JSON.stringify({ error: "that transcript belongs to a live session — reuse it (or DELETE it first)", sessionId: live[0], busy: !!live[1].ctrl }));
+              return;
+            }
+          }
+          const { id, rec } = makeSession(m, resume);
+          res.writeHead(200, { "content-type": "application/json" }).end(JSON.stringify({ sessionId: id, model: m, file: rec.file, resumed: !!resume }));
+        });
+        return;
+      }
+      const promptMatch = req.method === "POST" && url.pathname.match(/^\/v1\/sessions\/([^/]+)\/prompt$/);
+      if (promptMatch) {
+        const rec = sessions.get(promptMatch[1]!);
+        if (!rec) {
+          res.writeHead(404, { "content-type": "application/json" }).end(JSON.stringify({ error: "unknown session" }));
+          return;
+        }
+        if (rec.ctrl) {
+          // One turn at a time per session — two interleaved prompts would corrupt one conversation.
+          res.writeHead(409, { "content-type": "application/json" }).end(JSON.stringify({ error: "a turn is already running on this session — abort it or wait for done" }));
+          return;
+        }
+        rec.ctrl = new AbortController(); // claim the session before any await, so a racing second prompt sees busy
+        // If the client dies MID-BODY (e.g. a dropped multi-MB image upload), 'end' never fires and
+        // the claim above would brick the session with a permanent 409 — release it on 'close'.
+        req.on("close", () => {
+          if (!req.complete) {
+            rec.ctrl = null;
+            rec.steer.length = 0;
+          }
+        });
+        let body = "";
+        req.on("data", (c) => (body += c));
+        req.on("end", async () => {
+          let text = "";
+          let images: string[] | undefined;
+          try {
+            const j = JSON.parse(body || "{}") as { text?: string; images?: string[] };
+            text = String(j.text ?? "");
+            if (Array.isArray(j.images) && j.images.length) images = j.images.map(String);
+          } catch {
+            /* empty prompt */
+          }
+          res.writeHead(200, { "content-type": "text/event-stream", "cache-control": "no-cache", connection: "keep-alive" });
+          // If the client drops the SSE stream mid-turn (IDE reload/crash), abort the turn — else it
+          // runs headless, and in ask mode parks forever on an approval no one can see or answer.
+          res.on("close", () => {
+            if (!res.writableEnded) {
+              rec.ctrl?.abort();
+              rec.registry.abortAll();
+            }
+          });
+          rec.emit = (frame) => res.write(frame);
+          try {
+            await rec.agent.send(text, { signal: rec.ctrl!.signal, steer: rec.steer, images, onEvent: (e: AgentEvent) => res.write(sseFrame(e)) });
+          } catch (e) {
+            res.write(sseFrame({ type: "error", message: e instanceof Error ? e.message : String(e) }));
+          } finally {
+            rec.emit = null;
+            rec.ctrl = null;
+            rec.steer.length = 0;
+            res.end();
+          }
+        });
+        return;
+      }
+      const abortMatch = req.method === "POST" && url.pathname.match(/^\/v1\/sessions\/([^/]+)\/abort$/);
+      if (abortMatch) {
+        const rec = sessions.get(abortMatch[1]!);
+        if (!rec) {
+          res.writeHead(404, { "content-type": "application/json" }).end(JSON.stringify({ error: "unknown session" }));
+          return;
+        }
+        const wasRunning = !!rec.ctrl;
+        rec.ctrl?.abort();
+        rec.registry.abortAll(); // a turn parked on an unanswered approval must not stay stuck
+        res.writeHead(200, { "content-type": "application/json" }).end(JSON.stringify({ ok: true, wasRunning }));
+        return;
+      }
+      const steerMatch = req.method === "POST" && url.pathname.match(/^\/v1\/sessions\/([^/]+)\/steer$/);
+      if (steerMatch) {
+        const rec = sessions.get(steerMatch[1]!);
+        if (!rec) {
+          res.writeHead(404, { "content-type": "application/json" }).end(JSON.stringify({ error: "unknown session" }));
+          return;
+        }
+        let body = "";
+        req.on("data", (c) => (body += c));
+        req.on("end", () => {
+          let text = "";
+          try {
+            text = String((JSON.parse(body || "{}") as { text?: string }).text ?? "");
+          } catch {
+            /* stays empty */
+          }
+          if (!text || !rec.ctrl) {
+            // steering only makes sense mid-turn; when idle, just send the next prompt instead
+            res.writeHead(409, { "content-type": "application/json" }).end(JSON.stringify({ ok: false, error: rec.ctrl ? "empty text" : "no turn running — send a prompt instead" }));
+            return;
+          }
+          rec.steer.push(text);
+          res.writeHead(200, { "content-type": "application/json" }).end(JSON.stringify({ ok: true }));
+        });
+        return;
+      }
+      const modeMatch = req.method === "PATCH" && url.pathname.match(/^\/v1\/sessions\/([^/]+)$/);
+      if (modeMatch) {
+        const rec = sessions.get(modeMatch[1]!);
+        if (!rec) {
+          res.writeHead(404, { "content-type": "application/json" }).end(JSON.stringify({ error: "unknown session" }));
+          return;
+        }
+        let body = "";
+        req.on("data", (c) => (body += c));
+        req.on("end", () => {
+          let mode: string | undefined;
+          try {
+            mode = (JSON.parse(body || "{}") as { mode?: string }).mode;
+          } catch {
+            /* stays undefined */
+          }
+          if (mode !== "ask" && mode !== "plan" && mode !== "auto") {
+            res.writeHead(400, { "content-type": "application/json" }).end(JSON.stringify({ error: 'mode must be "ask" | "plan" | "auto"' }));
+            return;
+          }
+          rec.mode = mode;
+          rec.agent.setPlanMode(mode === "plan");
+          rec.agent.setAutoApprove(mode === "auto");
+          res.writeHead(200, { "content-type": "application/json" }).end(JSON.stringify({ ok: true, mode }));
+        });
+        return;
+      }
+      const approveMatch = req.method === "POST" && url.pathname.match(/^\/v1\/sessions\/([^/]+)\/approve$/);
+      if (approveMatch) {
+        const rec = sessions.get(approveMatch[1]!);
+        if (!rec) {
+          res.writeHead(404, { "content-type": "application/json" }).end(JSON.stringify({ error: "unknown session" }));
+          return;
+        }
+        let body = "";
+        req.on("data", (c) => (body += c));
+        req.on("end", () => {
+          let ok = false;
+          try {
+            const { id, decision } = JSON.parse(body || "{}") as { id?: string; decision?: ApprovalDecision };
+            if (id && decision) ok = rec.registry.settle(id, decision);
+          } catch {
+            /* ok stays false */
+          }
+          res.writeHead(ok ? 200 : 404, { "content-type": "application/json" }).end(JSON.stringify({ ok }));
+        });
+        return;
+      }
+      const delMatch = req.method === "DELETE" && url.pathname.match(/^\/v1\/sessions\/([^/]+)$/);
+      if (delMatch) {
+        const rec = sessions.get(delMatch[1]!);
+        rec?.ctrl?.abort(); // don't orphan a running turn
+        rec?.registry.abortAll();
+        const existed = sessions.delete(delMatch[1]!);
+        res.writeHead(existed ? 200 : 404, { "content-type": "application/json" }).end(JSON.stringify({ ok: existed }));
+        return;
+      }
       res.writeHead(404).end();
-    }).listen(port, () => console.log(`ada HTTP API on http://localhost:${port}  ·  POST /v1/prompt {"text":"…"}  ·  model ${model || "(none — set one)"}`));
+    }).listen(port, () =>
+      console.log(
+        `ada HTTP API on http://localhost:${port}  ·  model ${model || "(none — set one)"}\n` +
+          `  one-shot:    POST /v1/prompt {"text":"…"}\n` +
+          `  interactive: POST /v1/sessions → {sessionId}   (GET lists resumable transcripts)\n` +
+          `               POST /v1/sessions/:id/prompt {"text":"…","images"?:[…]}  (SSE: text/tool_call/tool_result/approval_request/done)\n` +
+          `               POST /v1/sessions/:id/approve {"id":"…","decision":"yes"|"all"|"no"}\n` +
+          `               POST /v1/sessions/:id/abort · /steer {"text":"…"} · PATCH /v1/sessions/:id {"mode":"ask"|"plan"|"auto"}`,
+      ),
+    );
     await new Promise(() => {}); // keep the process alive for the server
     return;
   }

package/src/client/skill-router.ts

@@ -64,16 +64,28 @@ export function rankSkills(query: string, items: RankItem[], n = 5): { name: str
 
 /**
  * The single clearly-dominant skill for a query, or null when the match is weak/ambiguous.
- * Three gates, all required: a score floor, dominance over the runner-up, and — crucially — an
- * EXACT whole-token overlap with the skill NAME. That last gate is the precision guard against
- * lexical false positives: "make a powerpoint" prefix-matches "low-power" and even dominates, but
- * "powerpoint" never equals the name token "power", so it's correctly rejected.
+ * Four gates, all required:
+ *  1. a score floor;
+ *  2. dominance over the runner-up;
+ *  3. an EXACT whole-token overlap with the skill NAME — the guard against prefix false positives
+ *     ("make a powerpoint" prefix-matches "low-power" and even dominates, but "powerpoint" never
+ *     equals the name token "power", so it's rejected);
+ *  4. query COVERAGE — strictly more than a third of the query's content tokens must EXACTLY match
+ *     the skill's tokens. A conversational sentence that merely *contains* one skill-y keyword
+ *     ("remember this: the secret word is X" → secret-scan, observed live) is about something else;
+ *     a short task-like command ("describe the project" → project-overview) matches nearly all its
+ *     tokens. Exact equality here on purpose — matches()'s 4-char prefixing is right for recall in
+ *     rankSkills but inflates coverage ("remember" prefix-matches "remediate"), re-opening the leak.
  */
 export function confidentSkill(query: string, items: RankItem[]): string | null {
   const ranked = rankSkills(query, items, 2);
   const top = ranked[0];
   if (!top || top.score < 4) return null;
-  if (ranked[1] && top.score < ranked[1].score * 1.3) return null; // reject ties/near-ties; the name-exact gate below is the real precision guard
-  const q = new Set(tokenize(query));
-  return tokenize(top.name).some((t) => q.has(t)) ? top.name : null;
+  if (ranked[1] && top.score < ranked[1].score * 1.3) return null; // reject ties/near-ties
+  const q = [...new Set(tokenize(query))];
+  if (!tokenize(top.name).some((t) => q.includes(t))) return null;
+  const item = items.find((it) => it.name === top.name);
+  const doc = new Set(tokenize(`${top.name} ${item?.description ?? ""} ${item?.category ?? ""}`));
+  const covered = q.filter((qt) => doc.has(qt)).length;
+  return covered / q.length > 1 / 3 ? top.name : null;
 }

package/src/sdk/index.ts

@@ -1,21 +1,98 @@
-// Typed client SDK for the ada HTTP API (started with `ada serve`). Drive ada programmatically:
+// Typed client SDK for the ada HTTP API (started with `ada serve`). Two ways to drive ada:
 //
-//   import { createClient } from "ada/sdk";
+//   import { createClient } from "ada-agent/sdk"; // or "./src/sdk/index.ts" in-repo
 //   const ada = createClient("http://localhost:8788");
+//
+// One-shot (no memory between calls — a "generate this" action, not a chat panel):
 //   const { text } = await ada.prompt("list the files in this project");
+//
+// Interactive (a Cursor-style agent panel — persistent session, live events, edits pause for your
+// own approval UI instead of auto-running):
+//   const session = await ada.session();
+//   await session.prompt("refactor foo.ts", (e) => {
+//     if (e.type === "text") process.stdout.write(e.delta);
+//     if (e.type === "tool_call") console.log(`→ ${e.name} ${e.detail}`);
+//     if (e.type === "approval_request") session.approve(e.id, myOwnConfirmUi(e.name, e.summary) ? "yes" : "no");
+//   });
 
 export interface PromptResult {
   text: string;
   usage?: string;
 }
 
+/** One event from an interactive session's prompt stream. */
+export type SessionEvent =
+  | { type: "text"; delta: string }
+  | { type: "tool_call"; callId: string; name: string; detail: string }
+  | { type: "tool_result"; callId: string; name: string; output: string; isError: boolean }
+  | { type: "approval_request"; id: string; name: string; summary: string }
+  | { type: "done"; text: string; usage: string }
+  | { type: "error"; message: string };
+
+export interface AdaSession {
+  readonly id: string;
+  /** The on-disk transcript backing this session — survives an `ada serve` restart. Pass this (or
+   *  `"latest"`) as `resume` to a later `session()` call to reattach after one. */
+  readonly file: string;
+  /** True if this session's history was seeded from an existing transcript. */
+  readonly resumed: boolean;
+  /** Send a prompt; `onEvent` fires for every event as the turn streams. Resolves once it's done.
+   *  `images` are data: or https: URLs attached to the message. 409s if a turn is already running. */
+  prompt(text: string, onEvent: (e: SessionEvent) => void, opts?: { images?: string[] }): Promise<void>;
+  /** Answer a pending `approval_request` event by its id. */
+  approve(id: string, decision: "yes" | "all" | "no"): Promise<void>;
+  /** Cancel the currently-running turn (the "stop generating" button). Safe when idle. */
+  abort(): Promise<void>;
+  /** Queue a mid-turn user message — the agent folds it in between steps (the "steer" box). */
+  steer(text: string): Promise<void>;
+  /** Switch the session's permission mode: ask (gate every edit), plan (read-only), auto (run freely). */
+  setMode(mode: "ask" | "plan" | "auto"): Promise<void>;
+  /** Free the session's resources server-side. (Does not delete the on-disk transcript.) */
+  close(): Promise<void>;
+}
+
+/** One on-disk session transcript, as returned by `listSessions()`. */
+export interface SessionMeta {
+  file: string;
+  mtime: number;
+  title: string;
+  parent?: string;
+}
+
 export interface AdaClient {
-  /** Send a prompt; runs a fresh agent turn server-side and returns its final text. */
+  /** One-shot: runs a fresh agent turn server-side (no memory between calls) and returns its final text. */
   prompt(text: string, opts?: { model?: string }): Promise<PromptResult>;
+  /**
+   * Start a persistent, streaming session — the Cursor-style integration point for an IDE.
+   * Pass `resume: "latest"` or a `file` from `listSessions()` to reattach an existing conversation
+   * (e.g. after `ada serve` restarted and the old in-memory sessionId is gone).
+   */
+  session(opts?: { model?: string; resume?: string }): Promise<AdaSession>;
+  /** On-disk session transcripts, newest first — for building a "resume which conversation?" picker. */
+  listSessions(): Promise<SessionMeta[]>;
   /** Server health + the default model. */
   health(): Promise<{ ok: boolean; model?: string }>;
 }
 
+async function streamSse(res: Response, onEvent: (e: SessionEvent) => void): Promise<void> {
+  if (!res.ok || !res.body) throw new Error(`ada ${res.status}: ${await res.text().catch(() => res.statusText)}`);
+  const reader = res.body.getReader();
+  const decoder = new TextDecoder();
+  let buf = "";
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    buf += decoder.decode(value, { stream: true });
+    let idx: number;
+    while ((idx = buf.indexOf("\n\n")) >= 0) {
+      const frame = buf.slice(0, idx);
+      buf = buf.slice(idx + 2);
+      const line = frame.split("\n").find((l) => l.startsWith("data: "));
+      if (line) onEvent(JSON.parse(line.slice(6)) as SessionEvent);
+    }
+  }
+}
+
 export function createClient(baseUrl = "http://localhost:8788"): AdaClient {
   const url = baseUrl.replace(/\/+$/, "");
   return {
@@ -28,6 +105,64 @@ export function createClient(baseUrl = "http://localhost:8788"): AdaClient {
       if (!res.ok) throw new Error(`ada ${res.status}: ${await res.text().catch(() => res.statusText)}`);
       return (await res.json()) as PromptResult;
     },
+    async session(opts) {
+      const res = await fetch(`${url}/v1/sessions`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ model: opts?.model, resume: opts?.resume }),
+      });
+      if (!res.ok) throw new Error(`ada ${res.status}: ${await res.text().catch(() => res.statusText)}`);
+      const { sessionId, file, resumed } = (await res.json()) as { sessionId: string; file: string; resumed: boolean };
+      return {
+        id: sessionId,
+        file,
+        resumed,
+        async prompt(text, onEvent, opts) {
+          const r = await fetch(`${url}/v1/sessions/${sessionId}/prompt`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ text, images: opts?.images }),
+          });
+          await streamSse(r, onEvent);
+        },
+        async approve(id, decision) {
+          const r = await fetch(`${url}/v1/sessions/${sessionId}/approve`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ id, decision }),
+          });
+          if (!r.ok) throw new Error(`ada ${r.status}: could not settle approval ${id}`);
+        },
+        async abort() {
+          const r = await fetch(`${url}/v1/sessions/${sessionId}/abort`, { method: "POST" });
+          if (!r.ok) throw new Error(`ada ${r.status}: abort failed`);
+        },
+        async steer(text) {
+          const r = await fetch(`${url}/v1/sessions/${sessionId}/steer`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ text }),
+          });
+          if (!r.ok) throw new Error(`ada ${r.status}: steer failed (is a turn running?)`);
+        },
+        async setMode(mode) {
+          const r = await fetch(`${url}/v1/sessions/${sessionId}`, {
+            method: "PATCH",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ mode }),
+          });
+          if (!r.ok) throw new Error(`ada ${r.status}: could not set mode`);
+        },
+        async close() {
+          await fetch(`${url}/v1/sessions/${sessionId}`, { method: "DELETE" });
+        },
+      };
+    },
+    async listSessions() {
+      const res = await fetch(`${url}/v1/sessions`);
+      if (!res.ok) throw new Error(`ada ${res.status}: ${await res.text().catch(() => res.statusText)}`);
+      return ((await res.json()) as { sessions: SessionMeta[] }).sessions;
+    },
     async health() {
       const res = await fetch(`${url}/health`);
       return (await res.json()) as { ok: boolean; model?: string };

package/src/selfcheck.ts

@@ -11,7 +11,7 @@ import { expandPrompt } from "./client/prompts.ts";
 import { MarkdownStreamer, highlight, renderEditDiff } from "./client/render.ts";
 import { Session, list } from "./client/session.ts";
 import { loadSkills, registerSkillTool, routeConfident } from "./client/skills.ts";
-import { describeCall, parseTextToolCalls, permPhrase, readIntegrationDocs, soleIntegration, writeProjectSkills } from "./client/agent.ts";
+import { Agent, describeCall, parseTextToolCalls, permPhrase, readIntegrationDocs, soleIntegration, writeProjectSkills } from "./client/agent.ts";
 import { userBar } from "./client/tui.ts";
 import { configuredServers, listConnectors, loadMcpServers } from "./client/mcp.ts";
 import { confidentSkill, rankSkills } from "./client/skill-router.ts";
@@ -117,6 +117,18 @@ async function main(): Promise<void> {
   rmSync(parent.file, { force: true });
   rmSync(branch.file, { force: true });
 
+  // --- resume: a session's on-disk history seeds a fresh Agent's context (no live model needed) ---
+  {
+    const s = Session.create();
+    s.append({ role: "user", content: "remember: the secret word is PINEAPPLE97" });
+    s.append({ role: "assistant", content: "got it" });
+    const history = s.load() as never[];
+    const bare = new Agent({ client: {} as never, model: "x", session: Session.create(), onApprove: async () => "yes" });
+    const resumed = new Agent({ client: {} as never, model: "x", session: s, onApprove: async () => "yes", history });
+    assert.ok(resumed.contextTokens() > bare.contextTokens(), "resuming with history seeds more context than a bare session");
+    rmSync(s.file, { force: true });
+  }
+
   // --- router prefix mapping ---
   assert.equal(route("gpt-4o"), "openai");
   assert.equal(route("o3-mini"), "openai");
@@ -281,6 +293,16 @@ async function main(): Promise<void> {
     assert.equal(route("anything-else"), "openrouter", "unmatched → openrouter");
   }
 
+  // --- `ada --version` prints the version and exits WITHOUT auto-starting a backend ---
+  {
+    const { spawnSync } = await import("node:child_process");
+    const { fileURLToPath } = await import("node:url");
+    const bin = fileURLToPath(new URL("../bin/ada.mjs", import.meta.url));
+    const r = spawnSync(process.execPath, [bin, "--version"], { encoding: "utf8", timeout: 30_000 });
+    assert.match(r.stdout, /^ada \d+\.\d+\.\d+/, `--version prints the version (got: ${JSON.stringify(r.stdout)} / ${JSON.stringify(r.stderr?.slice(0, 120))})`);
+    assert.ok(!/starting ada-server/.test(r.stderr ?? ""), "--version must not auto-start the backend");
+  }
+
   // --- autostart helpers: URL classification + /health derivation ---
   {
     const { isLocalBackend, healthUrl } = await import("./client/autostart.ts");
@@ -299,6 +321,31 @@ async function main(): Promise<void> {
   const jid = startJob("selfcheck job", async () => "job-done-ok");
   await new Promise((r) => setTimeout(r, 30));
   assert.ok(renderJobs().includes(jid) && /job-done-ok/.test(renderJobs()), "background job runs and reports its result");
+
+  // --- agent-server helpers: SSE framing, id uniqueness, approval correlation (no live model needed) ---
+  {
+    const { sseFrame, newId, ApprovalRegistry } = await import("./client/agent-server.ts");
+    assert.equal(sseFrame({ type: "done", text: "hi" }), 'data: {"type":"done","text":"hi"}\n\n', "sseFrame formats one data: frame");
+    const a = newId("sess");
+    const b = newId("sess");
+    assert.ok(a.startsWith("sess_") && a !== b, "newId is prefixed and unique");
+
+    const registry = new ApprovalRegistry();
+    const { id, promise } = registry.wait();
+    assert.equal(registry.size, 1, "wait() tracks one pending approval");
+    assert.ok(registry.settle(id, "yes"), "settle() resolves a known pending approval");
+    assert.equal(await promise, "yes", "the waiting promise resolves with the decision");
+    assert.equal(registry.size, 0, "settle() clears the pending entry");
+    assert.equal(registry.settle("nope", "no"), false, "settle() on an unknown id returns false");
+
+    // abortAll: an aborted turn must not stay parked on unanswered approvals
+    const a1 = registry.wait();
+    const a2 = registry.wait();
+    assert.equal(registry.abortAll(), 2, "abortAll reports how many were pending");
+    assert.equal(await a1.promise, "no", "aborted approvals resolve to 'no'");
+    assert.equal(await a2.promise, "no", "all of them");
+    assert.equal(registry.size, 0, "abortAll clears the registry");
+  }
   assert.equal((await toolByName.get("web_fetch")!.run({ url: "http://127.0.0.1/x" })).isError, true, "web_fetch blocks loopback (SSRF guard)");
 
   // --- destructive classifier: real dangers flagged; everyday redirects are not (2>/dev/null bug) ---
@@ -352,6 +399,18 @@ async function main(): Promise<void> {
   assert.equal(confidentSkill("draw an architecture diagram of this project", allSkills), "architecture-diagram", "confident: → architecture-diagram");
   assert.equal(confidentSkill("make a powerpoint about Q3 results", allSkills), null, "precision guard: 'powerpoint' must NOT auto-apply 'low-power'");
   assert.equal(confidentSkill("what is 2 + 2", allSkills), null, "ambiguous query → no auto-apply");
+  // Coverage gate — a long sentence merely CONTAINING a skill-y keyword must not auto-apply
+  // (observed live: this exact prompt pulled in secret-scan and derailed a small model).
+  assert.equal(
+    confidentSkill("Remember this fact for later: the secret word is PINEAPPLE97. Just confirm you will remember it, do not do anything else.", allSkills),
+    null,
+    "coverage gate: incidental 'secret' must NOT auto-apply secret-scan",
+  );
+  assert.equal(confidentSkill("I was talking to my friend about docker yesterday and she mentioned kubernetes", allSkills), null, "coverage gate: conversational mention of docker");
+  // Short rephrasings of the same incident — prefix-matching must not inflate coverage
+  // ("remember" prefix-matches "remediate"), and 1/3 exactly must not pass the strict gate.
+  assert.equal(confidentSkill("remember this: the secret word is X", allSkills), null, "coverage gate: short secret-word phrasing");
+  assert.equal(confidentSkill("remember the secret word", allSkills), null, "coverage gate: shortest secret-word phrasing");
   // LOADED was set by registerSkillTool(allSkills) above, so routeConfident/skillBody resolve a body.
   const applied = routeConfident("describe the project");
   assert.ok(applied?.name === "project-overview" && /purpose/i.test(applied.body), "routeConfident returns the skill body to inject");

package/src/server/config.ts

@@ -23,9 +23,9 @@ export const PROVIDERS: Record<ProviderName, ProviderDef> = {
     baseURL: process.env.DASHSCOPE_BASE_URL ?? "https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
     keyEnv: "DASHSCOPE_API_KEY",
   },
-  // GitHub Copilot — OpenAI-compatible chat endpoint. COPILOT_API_KEY must be a Copilot *bearer*
-  // token (exchanged from a GitHub OAuth token at /copilot_internal/v2/token — that exchange is not
-  // implemented here; it needs a Copilot subscription). Required headers are added in the adapter.
+  // GitHub Copilot — OpenAI-compatible chat endpoint. Set COPILOT_API_KEY (a Copilot bearer you
+  // already have) OR COPILOT_GITHUB_TOKEN (a GitHub token with Copilot access — the adapter runs
+  // the /copilot_internal/v2/token exchange and caches/refreshes the bearer; see copilot-token.ts).
   copilot: { baseURL: process.env.COPILOT_BASE_URL ?? "https://api.githubcopilot.com", keyEnv: "COPILOT_API_KEY" },
   // Cloudflare Workers AI / AI Gateway — OpenAI-compatible. Workers AI: set CLOUDFLARE_ACCOUNT_ID +
   // CLOUDFLARE_API_TOKEN (default URL). AI Gateway: point CLOUDFLARE_BASE_URL at the gateway URL.
@@ -57,6 +57,8 @@ export function providerKey(p: ProviderName): string | undefined {
 
 /** A provider is usable if it's keyless, its key env var is set, or a credential is stored. */
 export function isConfigured(p: ProviderName): boolean {
+  // Copilot has a second way in: a GitHub token the adapter exchanges for a bearer (copilot-token.ts).
+  if (p === "copilot" && process.env.COPILOT_GITHUB_TOKEN) return true;
   return PROVIDERS[p].keyEnv === "" || !!process.env[PROVIDERS[p].keyEnv] || !!getCredential(p);
 }
 

package/src/server/providers/copilot-token.ts

@@ -0,0 +1,35 @@
+// GitHub Copilot bearer-token exchange. Copilot's endpoint doesn't take a GitHub token directly —
+// you exchange one at /copilot_internal/v2/token for a short-lived bearer. Ways in, in order:
+//   COPILOT_API_KEY      — you already have a bearer (pasted from another tool); used as-is.
+//   COPILOT_GITHUB_TOKEN — a GitHub OAuth token with Copilot access; exchanged + cached here,
+//                          refreshed automatically before expiry.
+//   stored credential    — whatever `ada login`-style credential storage holds for copilot.
+// Untested against a live subscription (needs one) — the exchange shape matches the documented
+// flow used by editor integrations; failures surface as a normal upstream error to the client.
+
+import { providerKey } from "../config.ts";
+
+let cached: { token: string; expiresAt: number } | null = null;
+
+/** Drop the cached bearer (e.g. after an upstream 401 — revoked token or clock skew). */
+export function invalidateCopilotBearer(): void {
+  cached = null;
+}
+
+/** The bearer to send to api.githubcopilot.com, or "" if no Copilot credentials are configured. */
+export async function copilotBearer(): Promise<string> {
+  const direct = process.env.COPILOT_API_KEY;
+  if (direct) return direct;
+  const gh = process.env.COPILOT_GITHUB_TOKEN;
+  if (!gh) return providerKey("copilot") ?? ""; // stored credential, or unconfigured
+  if (cached && Date.now() < cached.expiresAt - 60_000) return cached.token;
+  const res = await fetch("https://api.github.com/copilot_internal/v2/token", {
+    headers: { authorization: `token ${gh}`, "user-agent": "ada" },
+    signal: AbortSignal.timeout(10_000),
+  });
+  if (!res.ok) throw new Error(`Copilot token exchange failed: HTTP ${res.status} — is COPILOT_GITHUB_TOKEN a GitHub token on an account with a Copilot subscription?`);
+  const j = (await res.json()) as { token?: string; expires_at?: number };
+  if (!j.token) throw new Error("Copilot token exchange returned no token");
+  cached = { token: j.token, expiresAt: (j.expires_at ?? Math.floor(Date.now() / 1000) + 600) * 1000 };
+  return cached.token;
+}

package/src/server/providers/openai-compat.ts

@@ -4,17 +4,35 @@
 // that format, this adapter just swaps in the upstream base URL + key and streams the
 // response straight back — no translation needed.
 
+import { readFileSync } from "node:fs";
 import type { ProviderName } from "../../shared/types.ts";
 import { PROVIDERS, providerKey } from "../config.ts";
 import { SSE_HEADERS } from "../sse.ts";
 import type { Adapter, ChatRequest } from "./adapter.ts";
+import { copilotBearer, invalidateCopilotBearer } from "./copilot-token.ts";
 
-function authHeaders(provider: ProviderName): Record<string, string> {
+const ADA_VERSION = (() => {
+  try {
+    return (JSON.parse(readFileSync(new URL("../../../package.json", import.meta.url), "utf8")) as { version?: string }).version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+})();
+
+async function authHeaders(provider: ProviderName): Promise<Record<string, string>> {
+  // GitHub Copilot: bearer comes from the token exchange (or COPILOT_API_KEY), plus the
+  // editor-identification headers its endpoint requires.
+  if (provider === "copilot") {
+    const bearer = await copilotBearer();
+    return {
+      ...(bearer ? { authorization: `Bearer ${bearer}` } : {}),
+      "Copilot-Integration-Id": "vscode-chat",
+      "Editor-Version": `ada/${ADA_VERSION}`,
+      "Editor-Plugin-Version": `ada/${ADA_VERSION}`,
+    };
+  }
   const key = providerKey(provider);
-  const base: Record<string, string> = key ? { authorization: `Bearer ${key}` } : {};
-  // GitHub Copilot's endpoint requires these editor-identification headers.
-  if (provider === "copilot") return { ...base, "Copilot-Integration-Id": "vscode-chat", "Editor-Version": "ada/0.0.1", "Editor-Plugin-Version": "ada/0.0.1" };
-  return base;
+  return key ? { authorization: `Bearer ${key}` } : {};
 }
 
 export const openAICompatAdapter: Adapter = {
@@ -28,7 +46,7 @@ export const openAICompatAdapter: Adapter = {
     try {
       upstream = await fetch(`${def.baseURL}/chat/completions`, {
         method: "POST",
-        headers: { "content-type": "application/json", ...authHeaders(provider) },
+        headers: { "content-type": "application/json", ...(await authHeaders(provider)) },
         body: JSON.stringify(outBody),
       });
     } catch (e) {
@@ -42,6 +60,8 @@ export const openAICompatAdapter: Adapter = {
     }
 
     if (!upstream.ok || !upstream.body) {
+      // A dead exchanged bearer (revoked / clock skew) would otherwise be reused until local expiry.
+      if (provider === "copilot" && upstream.status === 401) invalidateCopilotBearer();
       const text = await upstream.text().catch(() => "");
       res.writeHead(upstream.status || 502, { "content-type": "application/json" });
       res.end(text || JSON.stringify({ error: { message: `upstream error ${upstream.status}` } }));
@@ -67,7 +87,7 @@ export const openAICompatAdapter: Adapter = {
   async listModels(provider: ProviderName): Promise<string[]> {
     const def = PROVIDERS[provider];
     try {
-      const r = await fetch(`${def.baseURL}/models`, { headers: authHeaders(provider) });
+      const r = await fetch(`${def.baseURL}/models`, { headers: await authHeaders(provider) });
       if (!r.ok) return [];
       const j = (await r.json()) as { data?: Array<{ id?: unknown }> };
       return (j.data ?? []).map((m) => m.id).filter((x): x is string => typeof x === "string");