ada-agent 0.3.0 → 0.4.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,74 @@ 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":…}  → SSE stream of events (see below), until "done"
+POST /v1/sessions/:id/approve {"id":…, "decision":"yes"|"all"|"no"}
+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.0",
+  "version": "0.4.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",
@@ -29,6 +29,7 @@
   ],
   "bin": {
     "ada": "bin/ada.mjs",
+    "ada-agent": "bin/ada.mjs",
     "ada-server": "bin/ada-server.mjs"
   },
   "files": [

package/src/client/agent-server.ts

@@ -0,0 +1,45 @@
+// 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;
+  }
+
+  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"; name: string; detail: string }
+  | { type: "tool_result"; 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;
   }
 
@@ -690,9 +702,11 @@ export class Agent {
     const printCall = (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", name, detail: d.detail });
       say(`\n\x1b[2m• ${name}${detail}\x1b[0m\n`);
     };
-    const printResult = (r: ToolResult): void => {
+    const printResult = (name: string, r: ToolResult): void => {
+      ctrl?.onEvent?.({ type: "tool_result", 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`);
     };
@@ -728,7 +742,7 @@ export class Agent {
       if (perm === "deny") {
         printCall(c.name, args);
         results[i] = { output: "Denied by permission policy.", isError: true };
-        printResult(results[i]!);
+        printResult(c.name, results[i]!);
         continue;
       }
       if (!tool.needsApproval && perm !== "ask") {
@@ -739,7 +753,7 @@ export class Agent {
       printCall(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.name, results[i]!);
         continue;
       }
       const forceConfirm = c.name === "bash" && isDestructive(String(args.command ?? ""));
@@ -757,7 +771,7 @@ export class Agent {
           results[i] = await runTool(tool, c.name, args);
         }
       }
-      printResult(results[i]!);
+      printResult(c.name, results[i]!);
     }
     await Promise.all(
       parallel.map(async (i) => {
@@ -765,7 +779,7 @@ export class Agent {
         const args = argsOf(c.args);
         printCall(c.name, args);
         results[i] = await runTool(toolByName.get(c.name)!, c.name, args);
-        printResult(results[i]!);
+        printResult(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";
@@ -727,13 +728,51 @@ 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
+    }
+    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 };
+      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 +787,100 @@ 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 */
+          }
+          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;
+        }
+        let body = "";
+        req.on("data", (c) => (body += c));
+        req.on("end", async () => {
+          let text = "";
+          try {
+            text = String((JSON.parse(body || "{}") as { text?: string }).text ?? "");
+          } catch {
+            /* empty prompt */
+          }
+          res.writeHead(200, { "content-type": "text/event-stream", "cache-control": "no-cache", connection: "keep-alive" });
+          rec.emit = (frame) => res.write(frame);
+          try {
+            await rec.agent.send(text, { 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;
+            res.end();
+          }
+        });
+        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 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}\n` +
+          `               POST /v1/sessions/:id/prompt {"text":"…"}  (SSE: text/tool_call/tool_result/approval_request/done)\n` +
+          `               POST /v1/sessions/:id/approve {"id":"…","decision":"yes"|"all"|"no"}`,
+      ),
+    );
     await new Promise(() => {}); // keep the process alive for the server
     return;
   }

package/src/sdk/index.ts

@@ -1,21 +1,91 @@
-// 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"; name: string; detail: string }
+  | { type: "tool_result"; 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. */
+  prompt(text: string, onEvent: (e: SessionEvent) => void): Promise<void>;
+  /** Answer a pending `approval_request` event by its id. */
+  approve(id: string, decision: "yes" | "all" | "no"): 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 +98,44 @@ 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) {
+          const r = await fetch(`${url}/v1/sessions/${sessionId}/prompt`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ text }),
+          });
+          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 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");
@@ -299,6 +311,23 @@ 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");
+  }
   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) ---