toolnexus 0.24.0 → 0.26.0

package/README.md

@@ -93,7 +93,8 @@ tool. Runnable: `npm run example:prompt-cache` ([`examples/prompt_cache.ts`](exa
 - `agents.compactor({ onCompact })`, `agent.asToolWith(ctx => ({ hooks, waitFor }))`, runtime
   `waitFor`, `ctx.callId` on tools, `listModels(opts)`.
 
-ACP host hooks (permission choice, update stream, cancel, streaming) are Go-only for now.
+An in-process model streams for real when it is given as `generateStream(request, emit)`; a plain
+`generate` still refuses `stream()`.
 
 ## Simple judgments
 
@@ -135,6 +136,41 @@ const out = await gate(c, state, questions, [
   filter, content and model batteries into `hooks`. A `beforeLLM` hook may return `{ model }` to
   send another model for that turn only.
 
+### Backends, images, cache and helpers
+
+Every default below is a **proposed default, owner to confirm**
+(`openspec/changes/add-classifier-backends`).
+
+```ts
+import { createClassifier, judge, MemoryCache, validateDecision, thresholdBand, chunkQuestions } from "toolnexus"
+
+const c = createClassifier({ backend: "openrouter", cache: new MemoryCache(3_600_000, 1000) })
+const d = await c.state({ note: "listing", photo: { type: "image", mimeType: "image/png", data: b64 } })
+  .evaluate(judge.noul("red", "Is the object in `photo` red?"))         // fails closed on an invalid reply
+const rs = await c.states("a", "b").evaluate(judge.noul("q", "…"))      // [{ decision } | { error }], in order
+```
+
+- `backend`: `typesafe` (default) · `openrouter` (`typesafe/jev-1.14`) · `cloudflare` (`/ai/run`
+  envelope; `${CLOUDFLARE_ACCOUNT_ID}` in the URL expands at call time, errors name it unexpanded)
+  · `vercel` · `custom` (requires `baseUrl` and `supports`). The table is data:
+  `CLASSIFIER_BACKENDS`; `supports: { images }` overrides it per classifier.
+- Images (style `systemone` only): image parts in the state are lifted into `assets` (cloudflare:
+  data URLs). PNG/JPEG, 280–1568 px a side, ≤ 16 MiB each and 32 MiB per request — never resized.
+  A backend without image support throws `ClassifierUnsupported` before any request. A state with
+  no content part is sent byte-identically to before. JS has no distinct part type, so **any**
+  object shaped like a `ContentPart` (`{type:"text",text}`, `{type:"image",mimeType,…}`) inside a
+  systemone state is treated as a part.
+- `cache: { get(key), set(key, value) }` (sync or async, string values) — off when absent; only
+  valid replies are stored; keys follow the served model. A hit sets `decision.cached` and the
+  `classifier.evaluate` event's `cached`. Every such event also carries `questions` and
+  `questionsHash`.
+- Helpers: `validateDecision(questions, decision)` → `Error | undefined`; `thresholdBand(answer,
+  thresholds?)` with `DEFAULT_THRESHOLDS` 0.8 / 0.2 / 0.6 (inclusive; `Bands` stays the `ask`/`gate`
+  default); `chunkQuestions(questions, size)`.
+- Open union: `judge.raw(name, type, instructions, criteria?)` / `raw(...)`; an answer of an
+  unmodelled type decodes to `{ type, value }` (`decision.raw(key)`).
+- `style: "llm"` is **deprecated** — it still works unchanged, with no runtime warning.
+
 ## Media generation
 
 Generate images, video and speech (plus transcription, voice cloning and talking-head video)
@@ -158,6 +194,120 @@ const res = await agent.run("Draw a fox, then animate it.", { toolkit: tk })
 for (const f of res.files) console.log(f.from, f.mimeType, f.url)
 ```
 
+## MCP 2026-07-28 + OAuth
+
+`loadMcp` / `Toolkit.create({ mcpConfig })` now speak MCP **2026-07-28** first, with no MCP SDK on
+that path: every server (stdio and HTTP) gets `server/discover` before anything else. A pre-2026
+server answers it with an error, a 400/404/405, or (stdio) silence for `min(timeout, 5 s)`, and is
+then served by the unchanged SDK path. Tool names, result mapping, status, `tools` filters and
+`disableTools` are the same on both paths.
+
+```ts
+const toolkit = await Toolkit.create({
+  mcpConfig: {
+    mcpServers: {
+      docs: { url: "https://mcp.example.com/mcp", auth: { clientId: "my-registered-app" } },
+      big: { command: ["my-server"], toolSearch: true, description: "the billing API" },
+    },
+  },
+  waitFor,                 // answers MRTR input requests and `pause`-mode authorization
+  tokenStore,              // { load(resource), save(resource, token), delete(resource) }; default in memory
+  openUrl: (url) => open(url), // how `auto` OAuth opens the browser; default: the OS opener
+})
+```
+
+- **MRTR** (`input_required`) goes through `waitFor` (form ⇒ `kind:"input"` with `data.schema`,
+  URL ⇒ `kind:"authorization"`). Without `waitFor` the tool returns a §10 pending result; the
+  resumed call (with `ctx.answer`) sends that round once and is never re-asked.
+- **OAuth 2.1** on a 401: protected-resource metadata → AS metadata → a pre-registered `clientId`
+  (`clientIds` per issuer, optional `clientSecret`) or a Client ID Metadata Document
+  (`clientMetadataUrl`). **No dynamic client registration.** PKCE S256 + `resource`, `iss`/`state`
+  checks, refresh (single-flight; `omitRefreshResource` for Entra) and step-up on
+  `insufficient_scope`. `mode: "auto"` (loopback callback + `openUrl`) or `mode: "pause"` (needs
+  `redirectUri`; answer the `authorization` request with `data: { callbackUrl }`). Tokens are never
+  logged or put in error text.
+- **Old servers + OAuth:** the bearer is attached to the SDK transport through its `fetch` hook,
+  and a 401 there runs the same flow once.
+- **Skills over MCP:** a server advertising the skills extension contributes its skills to the
+  `skill` tool (base `skill://<name>/`).
+- **Tool search:** `toolSearch: true` replaces a server's tools with `<server>_search_tools` and
+  `<server>_call_tool`.
+- A failed `tools/call` (timeout, 5xx, dropped connection) is never re-sent.
+
+## Embeddable MCP server (`mcpHandler`)
+
+`serve(addr, { mcp })` owns a port and exposes one static tool list. `toolkit.mcpHandler(cfg)`
+returns a plain Node request listener `(req, res) => void` (plus `notifyToolsChanged()`) that you
+mount on **your** server or router, behind your own TLS, CORS and OAuth. Every policy is a hook:
+`authenticate` (+ `wwwAuthenticate` for the 401), `listTools` per request (a name outside it is never
+executed), `beforeCall` allow / deny / confirm (confirm uses MCP elicitation when the client supports
+it, otherwise returns your fallback `result`), `onCall` telemetry, `serverInfo`, resources/prompts,
+pluggable `sessionIds`, `stateless`, `protocolVersions`. Hooks and tools read the caller with
+`identityFrom(ctx)`, `requestFrom(ctx)`, `mcpSessionIdFrom(ctx)` and `mcpRequestMetaFrom(ctx)`.
+`ToolResult.structured` / `meta` and `Tool.outputSchema` / `annotations` go on the wire as
+`structuredContent` / `_meta` / `outputSchema` / `annotations`. SPEC §7C.1; runnable:
+`npm run example:mcp-handler`.
+
+```ts
+import http from "node:http"
+import { createToolkit, identityFrom } from "toolnexus"
+
+const tk = await createToolkit({ builtins: false })
+const mcp = tk.mcpHandler({
+  authenticate: (req) => verifyBearer(req.headers.authorization),   // throw ⇒ 401
+  listTools: (ctx) => toolsFor(identityFrom(ctx)),
+  beforeCall: (_ctx, tool) =>
+    tool.annotations?.destructiveHint ? { kind: "confirm", message: `Run ${tool.name}?` } : { kind: "allow" },
+})
+http.createServer((req, res) => (req.url?.startsWith("/mcp") ? mcp(req, res) : res.writeHead(404).end())).listen(8080)
+```
+
+### MCP 2026-07-28 (opt-in)
+
+List `"2026-07-28"` in `protocolVersions` to serve the stateless 2026 wire (`server/discover`,
+header validation, `resultType`, MRTR): `["2026-07-28"]` alone, or `["2026-07-28", "2025-06-18"]` for
+both wires on one mount. It is never a default and `initialize` never negotiates it. A `confirm`
+decision and a tool suspension (§10 `pending(...)`) leave as `input_required`; the client's retry
+reaches the tool as `ctx.answer`. `listSkills` publishes skills through the skills extension
+(`skills/list`, `skills/get`, `resources/read` of `skill://` URIs); `loadMcpSkills(dir)` builds that
+list from a skills folder. `McpServerAuth` makes the handler an OAuth protected resource: its
+`authenticate` verifies RS256 JWTs against the issuer's JWKS (or your `verify`), applies per-tool
+`scopes`, answers with exact `WWW-Authenticate` challenges, and returns an `McpPrincipal`;
+`metadata()` serves the RFC 9728 document. Bring your own authorization server; the
+auto-approving dev authorization server the suite uses is test tooling (`test/support`), not part of
+the package. SPEC §7C.2.
+
+```ts
+import { McpServerAuth, loadMcpSkills } from "toolnexus"
+
+const auth = new McpServerAuth({ issuer: "https://login.example", scopes: { "*": ["mcp"], wipe: ["mcp:admin"] } })
+const mcp = tk.mcpHandler({
+  protocolVersions: ["2026-07-28", "2025-06-18"],
+  authenticate: auth.authenticate,
+  listSkills: () => loadMcpSkills("./skills"),
+})
+const prm = auth.metadata() // mount at /.well-known/oauth-protected-resource[/mcp]
+```
+
+## Agents via ACP
+
+toolnexus ships no per-agent client. Three vendor-neutral pieces compose (SPEC §8C):
+`toolkit.asMcpServer()` serves the toolkit on `127.0.0.1` behind a bearer token (`{url, token,
+close}`); `loadACP({command, args, mcpServers, sessionMeta, clientCapsMeta, model})` drives any
+ACP agent, passing `mcpServers` verbatim; and its `generateStream` plugs into
+`createInProcessClient({ generateStream })` for incremental `stream()` (text, `thought`, and the
+agent's own `tool_call`/`tool_result` with `via: "acp"`).
+
+```ts
+const srv = await tk.asMcpServer()
+const acp = await loadACP({
+  command: "my-acp-agent",
+  mcpServers: [{ type: "http", name: "toolnexus", url: srv.url,
+                 headers: [{ name: "Authorization", value: `Bearer ${srv.token}` }] }],
+})
+const client = createInProcessClient({ generate: acp.generate, generateStream: acp.generateStream })
+```
+
 ## Documentation
 
 Everything else — the full surface, with runnable examples — lives on the docs site:

package/dist/acp.d.ts

@@ -1,12 +1,12 @@
-import type { InProcessRequest, InProcessResponse } from "./client.js";
+import type { InProcessRequest, InProcessResponse, StreamEvent } from "./client.js";
 /** Options for {@link loadACP}. `command`/`args` spawn the ACP agent as a child
  *  process; everything else tunes the session handshake. */
 export interface ACPOptions {
-    /** The ACP agent binary, e.g. `"devin"`. */
+    /** The ACP agent binary. */
     command: string;
-    /** Arguments to the agent, e.g. `["acp"]`. */
+    /** Arguments to the agent, passed untouched. */
     args?: string[];
-    /** Working directory for `session/new`. Real ACP agents (e.g. `devin acp`)
+    /** Working directory for `session/new`. Real ACP agents
      *  reject a relative `cwd` with `-32602 Invalid params` — this is always
      *  resolved to an absolute path before it is sent. Default: `process.cwd()`. */
     cwd?: string;
@@ -22,19 +22,50 @@ export interface ACPOptions {
     permissionTimeoutMs?: number;
     /** Optional `session/set_mode` sent once, right after `session/new`. */
     mode?: string;
+    /** Sent as `session/new` `mcpServers` VERBATIM and in order (absent ⇒ `[]`): toolnexus does
+     *  not validate, rename, reshape or pick between the http/stdio forms (SPEC §8C). */
+    mcpServers?: Record<string, unknown>[];
+    /** Sent as `session/new` `_meta`; the key is absent when unset. Opaque to toolnexus. */
+    sessionMeta?: Record<string, unknown>;
+    /** Sent as `initialize` `clientCapabilities._meta` (vendor flags). Opaque to toolnexus. */
+    clientCapsMeta?: Record<string, unknown>;
+    /** Passed through unchanged after `session/new`: `session/set_config_option`
+     *  `{configId:"model"}`, then `session/set_model` if the agent rejects that. Both failing
+     *  fails `loadACP`. */
+    model?: string;
+    /** Receives the agent's stderr (default: discarded). */
+    stderr?: (chunk: string) => void;
+    /** Decides each `session/request_permission`: return an `optionId` to select it, or
+     *  `""`/undefined to answer with the first `reject*` option. Absent ⇒ the first `allow*`
+     *  option, as before. */
+    onPermission?: (params: any) => string | undefined | Promise<string | undefined>;
+    /** Observes every raw `session/update` params object (must not throw). */
+    onUpdate?: (params: any) => void;
+    /** Bounds each handshake request (`initialize`, `session/new`, …). Absent ⇒ unbounded;
+     *  a request still fails at once when the agent exits. */
+    requestTimeoutMs?: number;
 }
 /** One warm ACP connection: one child process, one session, alive across many
  *  turns. `.generate` has exactly the shape {@link InProcessOptions.generate}
  *  wants, so it plugs straight into {@link createInProcessClient}. */
 export interface ACPClient {
     generate: (request: InProcessRequest) => Promise<InProcessResponse>;
-    /** Terminates the agent process. Idempotent — a second call is a no-op. */
+    /** {@link generate}, streaming: `emit` fires as each `session/update` arrives —
+     *  agent_message_chunk → `text`, agent_thought_chunk → `thought` (via "acp"),
+     *  tool_call → `tool_call` and a completed/failed tool_call_update → `tool_result`
+     *  (both via "acp": the agent's own tools, reported, never executed by the loop).
+     *  Shaped for {@link InProcessOptions.generateStream}. The returned content is the
+     *  message text only. */
+    generateStream: (request: InProcessRequest, emit: (event: StreamEvent) => void) => Promise<InProcessResponse>;
+    /** Terminates the agent's process group. Idempotent — a second call is a no-op. */
     close: () => Promise<void>;
+    /** The agent's raw `initialize` result. */
+    readonly initializeResult: any;
 }
 /**
  * Opens one ACP connection: spawns `command`, performs `initialize` →
  * `session/new` (with an absolute `cwd` and an `mcpServers` array — the exact
- * trap real `devin acp` enforces with `-32602` otherwise) → an optional
+ * trap real agents enforce with `-32602` otherwise) → an optional
  * `session/set_mode`, then returns a client whose `.generate` sends exactly
  * one `session/prompt` per call, accumulating only `agent_message_chunk`
  * text.

package/dist/acp.js

@@ -4,8 +4,7 @@
  * openspec/changes/add-acp-model-source.
  *
  * ACP is to *agents* what MCP is to *tools*: JSON-RPC 2.0, one object per line,
- * over a child process's stdin/stdout (`devin acp`, Gemini CLI, Zed's agents all
- * speak it). This file ships ACP as nothing more than a `generate` function —
+ * over a child process's stdin/stdout. This file ships ACP as nothing more than a `generate` function —
  * the exact shape {@link InProcessOptions.generate} already defines — so the
  * tool-calling loop, skills, MCP tools, adapters and sub-agents are entirely
  * untouched. `loadACP` opens the connection once (`initialize` → `session/new` →
@@ -81,7 +80,7 @@ function renderPrompt(request) {
 /**
  * Opens one ACP connection: spawns `command`, performs `initialize` →
  * `session/new` (with an absolute `cwd` and an `mcpServers` array — the exact
- * trap real `devin acp` enforces with `-32602` otherwise) → an optional
+ * trap real agents enforce with `-32602` otherwise) → an optional
  * `session/set_mode`, then returns a client whose `.generate` sends exactly
  * one `session/prompt` per call, accumulating only `agent_message_chunk`
  * text.
@@ -89,16 +88,56 @@ function renderPrompt(request) {
 export async function loadACP(opts) {
     const cwd = opts.cwd ? path.resolve(opts.cwd) : process.cwd();
     const permissionTimeoutMs = opts.permissionTimeoutMs ?? 30000;
+    // Its own process group (detached), so close() reaches an adapter's children too — an
+    // `npx …` launch is a tree, not one process.
     const child = spawn(opts.command, opts.args ?? [], {
         cwd,
         env: opts.env ? { ...process.env, ...opts.env } : process.env,
-        stdio: ["pipe", "pipe", "ignore"],
+        stdio: ["pipe", "pipe", opts.stderr ? "pipe" : "ignore"],
+        detached: process.platform !== "win32",
     });
+    if (opts.stderr) {
+        child.stderr.setEncoding("utf8");
+        child.stderr.on("data", (d) => {
+            try {
+                opts.stderr(d);
+            }
+            catch {
+                // a host sink never breaks the session
+            }
+        });
+    }
     let closed = false;
     let nextId = 0;
     const pending = new Map();
     let updateSink = null;
+    let exited = false;
+    let startError;
+    const childGone = new Promise((resolve) => {
+        child.once("exit", () => resolve());
+        child.once("error", () => resolve());
+    });
+    // Fail fast: a request still waiting when the agent's stdout closes fails at once
+    // instead of waiting out a timeout. setImmediate lets a spawn `error` land first.
+    const failPending = () => {
+        exited = true;
+        for (const [id, p] of pending) {
+            pending.delete(id);
+            p.cb({ error: { code: 0, message: exitMessage(p.method) } });
+        }
+    };
+    const exitMessage = (method) => startError
+        ? `toolnexus: acp: start ${JSON.stringify(opts.command)}: ${startError.message}`
+        : `toolnexus: acp: agent exited before replying to ${method}`;
+    child.on("error", (e) => {
+        startError = e;
+        setImmediate(failPending);
+    });
+    child.stdin.on("error", () => {
+        // EPIPE after the agent died: surfaced through failPending, never as a crash.
+    });
     const rl = createInterface({ input: child.stdout });
+    rl.on("close", () => setImmediate(failPending));
     rl.on("line", (raw) => {
         const line = raw.trim();
         if (!line)
@@ -113,6 +152,8 @@ export async function loadACP(opts) {
         handleLine(msg);
     });
     function write(msg) {
+        if (exited || child.stdin.destroyed)
+            return;
         child.stdin.write(JSON.stringify(msg) + "\n");
     }
     function reply(id, result) {
@@ -121,12 +162,30 @@ export async function loadACP(opts) {
     function call(method, params) {
         const id = `c-${++nextId}`;
         return new Promise((resolve, reject) => {
-            pending.set(id, (msg) => {
-                if (msg.error)
-                    reject(new Error(`toolnexus: ACP error ${msg.error.code}: ${msg.error.message}`));
-                else
-                    resolve(msg.result);
+            if (exited) {
+                reject(new Error(exitMessage(method)));
+                return;
+            }
+            let timer;
+            pending.set(id, {
+                method,
+                cb: (msg) => {
+                    clearTimeout(timer);
+                    if (msg.error && msg.error.code === 0)
+                        reject(new Error(msg.error.message));
+                    else if (msg.error)
+                        reject(new Error(`toolnexus: ACP error ${msg.error.code}: ${msg.error.message}`));
+                    else
+                        resolve(msg.result);
+                },
             });
+            if (opts.requestTimeoutMs && opts.requestTimeoutMs > 0) {
+                const ms = opts.requestTimeoutMs;
+                timer = setTimeout(() => {
+                    pending.delete(id);
+                    reject(new Error(`toolnexus: acp: ${method} timed out after ${ms}ms`));
+                }, ms);
+            }
             write({ jsonrpc: "2.0", id, method, params });
         });
     }
@@ -136,66 +195,167 @@ export async function loadACP(opts) {
      *  server-initiated requests like `session/request_permission`. */
     function handleLine(msg) {
         if (msg.method === undefined && msg.id !== undefined) {
-            const cb = pending.get(String(msg.id));
-            if (cb) {
+            const p = pending.get(String(msg.id));
+            if (p) {
                 pending.delete(String(msg.id));
-                cb(msg);
+                p.cb(msg);
             }
             return;
         }
         if (msg.method === "session/update") {
+            if (opts.onUpdate) {
+                try {
+                    opts.onUpdate(msg.params);
+                }
+                catch {
+                    // an observer never breaks the session
+                }
+            }
             updateSink?.(msg.params);
             return;
         }
         if (msg.method === "session/request_permission" && msg.id !== undefined) {
-            answerPermission(msg);
+            void answerPermission(msg);
             return;
         }
-        // An unhandled server->client request still needs a reply or a
-        // strict agent may itself hang waiting on one.
-        if (msg.id !== undefined)
-            reply(msg.id, {});
+        // An agent->client REQUEST we do not implement (fs/*, terminal/* — declared
+        // unsupported in clientCapabilities). Answer it, or the agent waits forever.
+        if (msg.id !== undefined) {
+            write({ jsonrpc: "2.0", id: msg.id, error: { code: -32601, message: `method not found: ${msg.method}` } });
+        }
     }
     /** Answers with the FIRST option whose `kind` starts with `allow` — an
      *  unanswered permission request hangs the turn forever (proven in
      *  spikes/acp). This runs the instant the request arrives, never waiting
      *  for anything else. */
-    function answerPermission(req) {
+    async function answerPermission(req) {
         const options = req.params?.options ?? [];
-        const chosen = options.find((o) => typeof o.kind === "string" && o.kind.startsWith("allow"));
+        let chosen;
+        if (opts.onPermission) {
+            let picked;
+            try {
+                picked = await opts.onPermission(req.params);
+            }
+            catch {
+                picked = undefined;
+            }
+            chosen = picked
+                ? { optionId: picked }
+                : options.find((o) => typeof o.kind === "string" && o.kind.startsWith("reject"));
+        }
+        else {
+            chosen = options.find((o) => typeof o.kind === "string" && o.kind.startsWith("allow"));
+        }
         const result = chosen
             ? { outcome: { outcome: "selected", optionId: chosen.optionId } }
             : { outcome: { outcome: "cancelled" } };
         reply(req.id, result);
     }
-    await call("initialize", {
-        protocolVersion: opts.protocolVersion ?? 1,
-        clientCapabilities: { fs: { readTextFile: false, writeTextFile: false } },
-    });
-    const sessionResult = await call("session/new", { cwd, mcpServers: [] });
+    const clientCapabilities = {
+        fs: { readTextFile: false, writeTextFile: false },
+        terminal: false,
+    };
+    if (opts.clientCapsMeta)
+        clientCapabilities._meta = opts.clientCapsMeta;
+    const step = async (label, fn) => {
+        try {
+            return await fn();
+        }
+        catch (e) {
+            await close();
+            const m = e instanceof Error ? e.message : String(e);
+            throw new Error(startError ? m : `toolnexus: acp: ${label}: ${m}`);
+        }
+    };
+    const initializeResult = await step("initialize", () => call("initialize", { protocolVersion: opts.protocolVersion ?? 1, clientCapabilities }));
+    const sessionParams = { cwd, mcpServers: opts.mcpServers ?? [] };
+    if (opts.sessionMeta)
+        sessionParams._meta = opts.sessionMeta;
+    const sessionResult = await step("session/new", () => call("session/new", sessionParams));
     const sessionId = sessionResult?.sessionId;
     if (opts.mode) {
-        await call("session/set_mode", { sessionId, modeId: opts.mode });
+        await step("session/set_mode", () => call("session/set_mode", { sessionId, modeId: opts.mode }));
+    }
+    if (opts.model) {
+        // Passed through unchanged. Stable ACP spelling first, then the older session/set_model.
+        const model = opts.model;
+        await step(`set model ${JSON.stringify(model)}`, async () => {
+            try {
+                await call("session/set_config_option", { sessionId, configId: "model", value: model });
+            }
+            catch (e1) {
+                try {
+                    await call("session/set_model", { sessionId, modelId: model });
+                }
+                catch (e2) {
+                    throw new Error(`${e1.message}; ${e2.message}`);
+                }
+            }
+        });
     }
     // Serialises turns: one ACP session is one conversation, so concurrent
     // prompts must not interleave into it. Idiomatic promise-chaining queue —
     // each generate() call attaches after whatever is already queued, and the
     // queue itself never rejects (a failed turn does not poison later ones).
     let turnQueue = Promise.resolve();
-    async function promptOnce(request) {
+    async function promptOnce(request, emit) {
         const text = renderPrompt(request);
         const id = `c-${++nextId}`;
         let content = "";
+        const toolNames = new Map();
+        const send = (ev) => {
+            try {
+                emit?.(ev);
+            }
+            catch {
+                // a consumer never breaks the session
+            }
+        };
+        // Runs from the stdout read loop, so every event is emitted the moment its
+        // notification is processed — never buffered to the end of the turn.
         updateSink = (params) => {
-            const update = params?.update;
-            if (update?.sessionUpdate === "agent_message_chunk") {
-                content += update?.content?.text ?? "";
+            const u = params?.update;
+            switch (u?.sessionUpdate) {
+                case "agent_message_chunk": {
+                    const t = u?.content?.text ?? "";
+                    content += t;
+                    if (t)
+                        send({ type: "text", delta: t });
+                    break;
+                }
+                // Thought and tool narration never reach the content — mixing them into
+                // the reply corrupts structured output a caller expects to parse.
+                case "agent_thought_chunk": {
+                    const t = u?.content?.text ?? "";
+                    if (t)
+                        send({ type: "thought", delta: t, via: "acp" });
+                    break;
+                }
+                case "tool_call": {
+                    const name = u.title || u.kind || "";
+                    toolNames.set(u.toolCallId ?? "", name);
+                    send({ type: "tool_call", id: u.toolCallId ?? "", name, args: u.rawInput ?? {}, via: "acp" });
+                    break;
+                }
+                case "tool_call_update": {
+                    if (u.status !== "completed" && u.status !== "failed")
+                        break;
+                    const name = u.title || toolNames.get(u.toolCallId ?? "") || "";
+                    send({
+                        type: "tool_result",
+                        id: u.toolCallId ?? "",
+                        name,
+                        output: acpToolContentText(u.content),
+                        isError: u.status === "failed",
+                        via: "acp",
+                    });
+                    break;
+                }
             }
-            // agent_thought_chunk and tool_call/tool_call_update narration are
-            // deliberately dropped — mixing them into the reply corrupts
-            // structured output a caller expects to parse.
         };
-        const replyPromise = new Promise((resolve) => pending.set(id, resolve));
+        if (exited)
+            throw new Error(exitMessage("session/prompt"));
+        const replyPromise = new Promise((resolve) => pending.set(id, { method: "session/prompt", cb: resolve }));
         write({ jsonrpc: "2.0", id, method: "session/prompt", params: { sessionId, prompt: [{ type: "text", text }] } });
         let timer;
         const timeout = new Promise((_, reject) => {
@@ -203,6 +363,8 @@ export async function loadACP(opts) {
         });
         try {
             const msg = await Promise.race([replyPromise, timeout]);
+            if (msg.error && msg.error.code === 0)
+                throw new Error(msg.error.message);
             if (msg.error)
                 throw new Error(`toolnexus: ACP error ${msg.error.code}: ${msg.error.message}`);
             return { content };
@@ -213,34 +375,59 @@ export async function loadACP(opts) {
             updateSink = null;
         }
     }
-    const generate = (request) => {
+    const generateStream = (request, emit) => {
         if (closed)
             return Promise.reject(new Error("toolnexus: ACP client is closed"));
-        const turn = turnQueue.then(() => promptOnce(request));
+        const turn = turnQueue.then(() => promptOnce(request, emit));
         turnQueue = turn.then(() => undefined, () => undefined);
         return turn;
     };
-    const close = () => {
+    async function close() {
         if (closed)
-            return Promise.resolve();
+            return;
         closed = true;
         rl.close();
-        return new Promise((resolve) => {
-            if (child.exitCode !== null || child.signalCode !== null) {
-                resolve();
-                return;
-            }
-            const done = () => resolve();
-            child.once("exit", done);
-            child.kill();
-            // Belt-and-braces: resolve even if the child never emits `exit` (e.g.
-            // already reaped), so close() itself never hangs.
-            setTimeout(done, 1000);
-        });
-    };
-    const client = { generate, close };
+        child.stdin.end();
+        if (startError || child.pid === undefined)
+            return;
+        if (child.exitCode !== null || child.signalCode !== null) {
+            killGroup(child.pid, "SIGKILL"); // reap any orphaned children of the group
+            return;
+        }
+        killGroup(child.pid, "SIGTERM");
+        const t = await Promise.race([childGone.then(() => "gone"), new Promise((r) => setTimeout(() => r("late"), 3000).unref())]);
+        killGroup(child.pid, "SIGKILL");
+        if (t === "late")
+            await Promise.race([childGone, new Promise((r) => setTimeout(r, 1000).unref())]);
+    }
+    const generate = (request) => generateStream(request);
+    const client = { generate, generateStream, close, initializeResult };
     // Non-enumerable, undocumented — internal test hook only, so the public
-    // ACPClient surface stays exactly {generate, close}.
+    // ACPClient surface stays exactly {generate, generateStream, close}.
     Object.defineProperty(client, "_pid", { value: child.pid, enumerable: false });
     return client;
 }
+/** Signals the child's whole process group (POSIX), else the child itself. Never throws. */
+function killGroup(pid, signal) {
+    if (process.platform !== "win32") {
+        try {
+            process.kill(-pid, signal);
+            return;
+        }
+        catch {
+            // group already gone; fall through to the pid itself
+        }
+    }
+    try {
+        process.kill(pid, signal);
+    }
+    catch {
+        // already gone
+    }
+}
+/** Joins the text of an ACP tool_call_update's `content` array ({content:{text}} parts). */
+function acpToolContentText(content) {
+    if (!Array.isArray(content))
+        return "";
+    return content.map((p) => (typeof p?.content?.text === "string" ? p.content.text : "")).join("");
+}