toolnexus 0.23.0 → 0.25.0

package/dist/toolkit.d.ts

@@ -7,8 +7,10 @@ import { type SkillDef } from "./skill.js";
 import { type BuiltinsConfig } from "./builtin.js";
 import { type Agent } from "./a2a.js";
 import { type A2AConfig, type OnTask, type ServeHandle } from "./serve.js";
-import { type MCPServeConfig, type OnCall } from "./mcpserve.js";
+import { type LocalMcpServer, type MCPServeConfig, type OnCall } from "./mcpserve.js";
+import { type McpHandler, type McpHandlerConfig } from "./mcphandler.js";
 import type { Client } from "./client.js";
+import type { Media } from "./media.js";
 export interface ToolkitOptions {
     mcpConfig?: string | object;
     skillsDir?: string | string[];
@@ -28,6 +30,8 @@ export interface ToolkitOptions {
     /** Sibling-file sample cap: 0 ⇒ default 10, n>0 ⇒ cap, -1 ⇒ omit <skill_files> (§3, S5). */
     skillSampleLimit?: number;
     extraTools?: Tool[];
+    /** Media generation (§7G): registers `media.tools()` (source "media"). */
+    media?: Media;
     /** Built-in tools (§4A). On by default. false | { disabled:true } | { enabled:false } ⇒ off. */
     builtins?: BuiltinsConfig;
     /** Remote A2A agents — each advertised skill becomes a tool (source:"a2a"). */
@@ -42,6 +46,10 @@ export interface ToolkitOptions {
     /** §2 Gap 3. Bounds the MCP load: each connect/list is capped by the server timeout and the
      * whole load aborts promptly if this signal fires. Omit ⇒ unbounded as before. */
     signal?: AbortSignal;
+    /** §2A.1a where MCP OAuth tokens live (default: in memory, per load). */
+    tokenStore?: import("./mcp2026/auth.js").TokenStore;
+    /** §2A.1a how `auto` MCP OAuth opens the authorization URL (default: the OS opener). */
+    openUrl?: (url: string) => unknown | Promise<unknown>;
 }
 export declare class Toolkit {
     private readonly mcp;
@@ -78,6 +86,20 @@ export declare class Toolkit {
         mcp?: MCPServeConfig;
         onCall?: OnCall;
     }): Promise<ServeHandle>;
+    /**
+     * §7C.1 (ADR 0039). An embeddable streamable-HTTP MCP server as a Node request listener
+     * `(req, res) => void` (+ `notifyToolsChanged()`), to mount on the host's own server/router
+     * behind its own TLS, CORS and OAuth. Every policy is a hook in `cfg`; `serve()` is unchanged.
+     * Without `cfg.listTools` it exposes this toolkit's tools.
+     */
+    mcpHandler(cfg?: McpHandlerConfig): McpHandler;
+    /**
+     * SPEC §8C. Serves this toolkit for a local agent to call: the §7C MCP mapping (tool names
+     * verbatim, `skill` stays `skill`, optional `config` filter) on `127.0.0.1:<ephemeral>/mcp`
+     * behind a fresh 64-hex bearer token. The caller builds whatever `mcpServers` entry its agent
+     * accepts from `{url, token}`; `close()` stops it (idempotent).
+     */
+    asMcpServer(config?: MCPServeConfig): Promise<LocalMcpServer>;
     execute(name: string, args: Record<string, unknown>, ctx?: ToolContext): Promise<ToolResult>;
     /** Markdown skill catalog for the system prompt. */
     skillsPrompt(): string;

package/dist/toolkit.js

@@ -3,6 +3,8 @@ import { loadSkills } from "./skill.js";
 import { selectBuiltins } from "./builtin.js";
 import { agentTools, parseAgentsConfig } from "./a2a.js";
 import { startA2AServer } from "./serve.js";
+import { serveLocalMcp } from "./mcpserve.js";
+import { createMcpHandler } from "./mcphandler.js";
 import { toAnthropic, toGemini, toOpenAI } from "./adapters.js";
 export class Toolkit {
     mcp;
@@ -39,12 +41,13 @@ export class Toolkit {
         }
     }
     static async create(opts = {}) {
-        const mcp = opts.mcpConfig !== undefined ? await loadMcp(opts.mcpConfig, { waitFor: opts.waitFor, signal: opts.signal }) : undefined;
+        const mcp = opts.mcpConfig !== undefined ? await loadMcp(opts.mcpConfig, { waitFor: opts.waitFor, signal: opts.signal, tokenStore: opts.tokenStore, openUrl: opts.openUrl, disableTools: opts.disableTools }) : undefined;
         // Skills come from directories, in-memory data, and/or a lazy provider (§3,
         // S1). The provider is resolved here (create() is async) and merged with the
         // data list; a provider failure is isolated so other sources still load.
         let skill;
-        if (opts.skillsDir !== undefined || opts.skills !== undefined || opts.skillProvider !== undefined) {
+        const mcpSkills = mcp?.skills ?? [];
+        if (opts.skillsDir !== undefined || opts.skills !== undefined || opts.skillProvider !== undefined || mcpSkills.length > 0) {
             let providerDefs = [];
             if (opts.skillProvider) {
                 try {
@@ -55,7 +58,8 @@ export class Toolkit {
                     providerDefs = [];
                 }
             }
-            const dataDefs = [...(opts.skills ?? []), ...providerDefs];
+            // §2.7 remote skills (MCP skills extension) join the same inventory, after local ones.
+            const dataDefs = [...(opts.skills ?? []), ...providerDefs, ...mcpSkills];
             // disableSkills is sugar over a skillsFilter drop-list: fold each name in as false
             // WITHOUT overriding an explicit skillsFilter entry (explicit entries win).
             const filter = opts.disableSkills && opts.disableSkills.length > 0
@@ -89,7 +93,7 @@ export class Toolkit {
             console.warn(`[toolnexus] A2A agent "${a.card}" failed: ${e instanceof Error ? e.message : String(e)}`);
             return [];
         })));
-        const agentToolsFlat = agentToolLists.flat();
+        const agentToolsFlat = [...agentToolLists.flat(), ...(opts.media ? opts.media.tools() : [])];
         // A2A inbound profile: a top-level `a2a` block on a parsed config object
         // (mirrors builtins/agents). serve() prefers its inline `a2a` over this.
         let a2aConfig;
@@ -157,6 +161,24 @@ export class Toolkit {
             onCall: opts.onCall,
         });
     }
+    /**
+     * §7C.1 (ADR 0039). An embeddable streamable-HTTP MCP server as a Node request listener
+     * `(req, res) => void` (+ `notifyToolsChanged()`), to mount on the host's own server/router
+     * behind its own TLS, CORS and OAuth. Every policy is a hook in `cfg`; `serve()` is unchanged.
+     * Without `cfg.listTools` it exposes this toolkit's tools.
+     */
+    mcpHandler(cfg = {}) {
+        return createMcpHandler(() => this.tools(), cfg);
+    }
+    /**
+     * SPEC §8C. Serves this toolkit for a local agent to call: the §7C MCP mapping (tool names
+     * verbatim, `skill` stays `skill`, optional `config` filter) on `127.0.0.1:<ephemeral>/mcp`
+     * behind a fresh 64-hex bearer token. The caller builds whatever `mcpServers` entry its agent
+     * accepts from `{url, token}`; `close()` stops it (idempotent).
+     */
+    asMcpServer(config) {
+        return serveLocalMcp(this.tools(), config);
+    }
     async execute(name, args, ctx) {
         const tool = this.byName.get(name);
         if (!tool) {

package/dist/types.d.ts

@@ -9,7 +9,7 @@ export type JSONSchema = {
     [k: string]: unknown;
 };
 import type { ContentPart } from "./content.js";
-export type ToolSource = "mcp" | "skill" | "builtin" | "native" | "http" | "a2a" | "custom";
+export type ToolSource = "mcp" | "skill" | "builtin" | "native" | "http" | "a2a" | "media" | "custom";
 export interface ToolResult {
     output: string;
     isError: boolean;
@@ -21,6 +21,21 @@ export interface ToolResult {
      */
     parts?: ContentPart[];
     metadata?: Record<string, unknown>;
+    /**
+     * Machine-readable result (MCP `structuredContent`, SPEC §1). Absent ⇒ byte-identical wire.
+     * When set and `output` is empty, MCP serve emits the JSON text of `structured` as the text block.
+     */
+    structured?: unknown;
+    /** Protocol metadata for the wire result (MCP `_meta`, SPEC §1). Absent ⇒ omitted. */
+    meta?: Record<string, unknown>;
+}
+/** MCP tool annotations (SPEC §1, §7C.1), sent verbatim on an MCP `tools/list` entry. */
+export interface ToolAnnotations {
+    title?: string;
+    readOnlyHint?: boolean;
+    destructiveHint?: boolean;
+    idempotentHint?: boolean;
+    openWorldHint?: boolean;
 }
 export interface ToolContext {
     signal?: AbortSignal;
@@ -30,6 +45,9 @@ export interface ToolContext {
     /** The model's id for this tool call, set by the client loop (§4C). A message's calls run
      * concurrently, so this is how a tool tells its sibling calls apart. Absent outside the loop. */
     callId?: string;
+    /** Set by `toolkit.mcpHandler` (§7C.1): the inbound MCP request this call serves. Read it with
+     * `identityFrom(ctx)` / `requestFrom(ctx)` / `mcpSessionIdFrom(ctx)` / `mcpRequestMetaFrom(ctx)`. */
+    mcp?: import("./mcphandler.js").McpContext;
 }
 /**
  * Advisory behavior hints (named after MCP tool annotations, §4C), for host permission gates
@@ -96,6 +114,13 @@ export interface Tool {
     /** What the tool may do (§4C). Builtins always carry hints; MCP tools carry them when the
      * server sends annotations. Advisory: a server can mislabel its tools. */
     hints?: ToolHints;
+    /** Decides per call whether this tool may run alongside other safe calls of the same model
+     * response (SPEC §8 "Tool scheduling"). Absent ⇒ safe only when `hints.readOnly`. */
+    concurrencySafe?: (args: Record<string, unknown>) => boolean;
+    /** JSON Schema of `ToolResult.structured` (SPEC §1); absent ⇒ omitted everywhere. */
+    outputSchema?: Record<string, unknown>;
+    /** MCP annotations (§7C.1), verbatim on the MCP wire; absent ⇒ derived from `hints`, else omitted. */
+    annotations?: ToolAnnotations;
 }
 export type McpStatus = "connected" | "disabled" | "failed";
 /** Replace anything outside [a-zA-Z0-9_-] with "_" (same as opencode). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolnexus",
-  "version": "0.23.0",
+  "version": "0.25.0",
   "description": "Dynamic MCP servers + agent skills as uniform tools for any LLM (opencode-style).",
   "type": "module",
   "main": "./dist/index.js",
@@ -17,11 +17,13 @@
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "test": "npm run build && node --experimental-strip-types --test test/unit.test.ts test/agents.test.ts test/agent-hooks.test.ts test/agent-inprocess.test.ts test/home.test.ts test/compaction.test.ts test/loop.test.ts test/in-process.test.ts test/translate.test.ts test/multimodal.test.ts test/classifier.test.ts test/acp.test.ts test/issues.test.ts test/host-boundary.test.ts test/judge.test.ts test/batteries.test.ts test/host-engine.test.ts test/host-turn-durability.test.ts test/host-engine-asks.test.ts test/examples.test.ts",
+    "test": "npm run build && node --experimental-strip-types --test test/unit.test.ts test/agents.test.ts test/agent-hooks.test.ts test/agent-inprocess.test.ts test/home.test.ts test/compaction.test.ts test/loop.test.ts test/in-process.test.ts test/translate.test.ts test/multimodal.test.ts test/classifier.test.ts test/acp.test.ts test/acp-client.test.ts test/issues.test.ts test/host-boundary.test.ts test/judge.test.ts test/batteries.test.ts test/host-engine.test.ts test/host-turn-durability.test.ts test/host-engine-asks.test.ts test/tool-concurrency.test.ts test/media.test.ts test/examples.test.ts test/mcphandler.test.ts test/mcphandler-conformance.test.ts test/mcp2026.test.ts",
     "example": "node --experimental-strip-types examples/basic.ts",
     "example:judge": "node --experimental-strip-types examples/judge.ts",
     "example:multimodal": "node --experimental-strip-types examples/multimodal.ts",
-    "example:prompt-cache": "node --experimental-strip-types examples/prompt_cache.ts"
+    "example:media": "node --experimental-strip-types examples/media.ts",
+    "example:prompt-cache": "node --experimental-strip-types examples/prompt_cache.ts",
+    "example:mcp-handler": "node --experimental-strip-types examples/mcp_handler.ts"
   },
   "keywords": [
     "mcp",

package/src/acp.ts

@@ -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` →
@@ -35,16 +34,16 @@
 import { spawn } from "node:child_process"
 import { createInterface } from "node:readline"
 import path from "node:path"
-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
@@ -60,6 +59,28 @@ 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
@@ -67,8 +88,17 @@ export interface ACPOptions {
  *  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
 }
 
 /** The literal marker every rendered prompt ends with, naming the current
@@ -126,7 +156,7 @@ function renderPrompt(request: InProcessRequest): string {
 /**
  * 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.
@@ -135,18 +165,59 @@ export async function loadACP(opts: ACPOptions): Promise<ACPClient> {
   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: string) => {
+      try {
+        opts.stderr!(d)
+      } catch {
+        // a host sink never breaks the session
+      }
+    })
+  }
 
   let closed = false
   let nextId = 0
-  const pending = new Map<string, (msg: RpcMessage) => void>()
+  const pending = new Map<string, { method: string; cb: (msg: RpcMessage) => void }>()
   let updateSink: ((params: any) => void) | null = null
+  let exited = false
+  let startError: Error | undefined
+  const childGone = new Promise<void>((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: string) =>
+    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) return
@@ -160,6 +231,7 @@ export async function loadACP(opts: ACPOptions): Promise<ACPClient> {
   })
 
   function write(msg: Record<string, unknown>): void {
+    if (exited || child.stdin!.destroyed) return
     child.stdin!.write(JSON.stringify(msg) + "\n")
   }
 
@@ -170,10 +242,27 @@ export async function loadACP(opts: ACPOptions): Promise<ACPClient> {
   function call(method: string, params: unknown): Promise<any> {
     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: NodeJS.Timeout | undefined
+      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 })
     })
   }
@@ -184,49 +273,100 @@ export async function loadACP(opts: ACPOptions): Promise<ACPClient> {
    *  server-initiated requests like `session/request_permission`. */
   function handleLine(msg: RpcMessage): void {
     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: RpcMessage): void {
+  async function answerPermission(req: RpcMessage): Promise<void> {
     const options: Array<{ optionId: string; kind?: string }> = req.params?.options ?? []
-    const chosen = options.find((o) => typeof o.kind === "string" && o.kind.startsWith("allow"))
+    let chosen: { optionId: string } | undefined
+    if (opts.onPermission) {
+      let picked: string | undefined
+      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: Record<string, unknown> = {
+    fs: { readTextFile: false, writeTextFile: false },
+    terminal: false,
+  }
+  if (opts.clientCapsMeta) clientCapabilities._meta = opts.clientCapsMeta
+  const step = async <T>(label: string, fn: () => Promise<T>): Promise<T> => {
+    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: Record<string, unknown> = { 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 as Error).message}; ${(e2 as Error).message}`)
+        }
+      }
+    })
   }
 
   // Serialises turns: one ACP session is one conversation, so concurrent
@@ -235,22 +375,61 @@ export async function loadACP(opts: ACPOptions): Promise<ACPClient> {
   // queue itself never rejects (a failed turn does not poison later ones).
   let turnQueue: Promise<unknown> = Promise.resolve()
 
-  async function promptOnce(request: InProcessRequest): Promise<InProcessResponse> {
+  async function promptOnce(request: InProcessRequest, emit?: (event: StreamEvent) => void): Promise<InProcessResponse> {
     const text = renderPrompt(request)
     const id = `c-${++nextId}`
 
     let content = ""
+    const toolNames = new Map<string, string>()
+    const send = (ev: StreamEvent) => {
+      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: any) => {
-      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: string = 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: string = u?.content?.text ?? ""
+          if (t) send({ type: "thought", delta: t, via: "acp" })
+          break
+        }
+        case "tool_call": {
+          const name: string = 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: string = 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<RpcMessage>((resolve) => pending.set(id, resolve))
+    if (exited) throw new Error(exitMessage("session/prompt"))
+    const replyPromise = new Promise<RpcMessage>((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: NodeJS.Timeout | undefined
@@ -263,6 +442,7 @@ export async function loadACP(opts: ACPOptions): Promise<ACPClient> {
 
     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 }
     } finally {
@@ -272,9 +452,9 @@ export async function loadACP(opts: ACPOptions): Promise<ACPClient> {
     }
   }
 
-  const generate = (request: InProcessRequest): Promise<InProcessResponse> => {
+  const generateStream = (request: InProcessRequest, emit?: (event: StreamEvent) => void): Promise<InProcessResponse> => {
     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,
@@ -282,27 +462,50 @@ export async function loadACP(opts: ACPOptions): Promise<ACPClient> {
     return turn
   }
 
-  const close = (): Promise<void> => {
-    if (closed) return Promise.resolve()
+  async function close(): Promise<void> {
+    if (closed) 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)
-    })
+    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 client: ACPClient = { generate, close }
+  const generate = (request: InProcessRequest): Promise<InProcessResponse> => generateStream(request)
+
+  const client: ACPClient = { 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: number, signal: NodeJS.Signals): void {
+  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: any): string {
+  if (!Array.isArray(content)) return ""
+  return content.map((p: any) => (typeof p?.content?.text === "string" ? p.content.text : "")).join("")
+}