@automatalabs/acp-agents 2.0.0 → 3.0.0

package/dist/agent/acp-agent.js

@@ -1,18 +1,24 @@
 import { CANCEL_NOT_HONORED_GRACE_MS, PooledConnection, isChildCleanupError, } from "../acp-client.js";
 import { validateClientHandlers } from "../client-handlers.js";
 import { appendPromptImages, buildRunPrompt, mergeTurnMeta, validatePromptImages } from "../prompt.js";
-import { assertNoModelConfigOption, resolveModelRoute } from "../routing.js";
+import { assertNoModelConfigOption } from "../routing.js";
 import { sessionRefFor } from "../session-ref.js";
+import { repairPromptText } from "../structured-output.js";
 import { StructuredOutputToolHost } from "../structured-tool.js";
 import { assertSystemPromptSupported } from "../system-prompt.js";
-import { agentClosedError, agentTurnError, agentValidationError, mapAgentError } from "./errors.js";
+import { describeBackendTraits } from "../traits.js";
+import { agentClosedError, agentTurnError, agentValidationError, mapAgentError, validateArguments, } from "./errors.js";
 import { AgentEventBus } from "./events.js";
 import { acquireForkedSession, forkTraitFor } from "./fork.js";
+import { MessageFolder, copyMessage } from "./messages.js";
 import { probeCatalog } from "./probe.js";
 import { releaseOnExit, retainOnExit } from "./process-registry.js";
 import { SerialQueue } from "./queue.js";
-import { freshBackendFor, resolveAgentRegistry, resolveAgentRoute, resolveRefRoute, validateAgentCwd, } from "./routing.js";
-import { assertPerTurnSchemaAllowed, planStructured } from "./structured.js";
+import { TurnStream } from "./stream.js";
+import { freshBackendFor, resolveAgentRegistry, resolveAgentRoute, resolveModelSwitch, resolveRefRoute, resolveSameBackendModel, validateAgentCwd, } from "./routing.js";
+import { assertPerTurnSchemaAllowed, planStructured, validateSchemaRetries } from "./structured.js";
+import { AgentToolHost } from "./tool-host.js";
+import { planTools, validateToolDefinitions } from "./tools.js";
 import { TurnCollector, buildTurn } from "./turn.js";
 import { ZERO_USAGE, } from "./types.js";
 /** Handed to the constructor by `AcpAgent.#seeded` only. Set and consumed SYNCHRONOUSLY (the
@@ -90,27 +96,29 @@ function assertSessionRef(ref, label, method) {
 /**
  * One ACP agent session on its own dedicated backend process.
  *
- * Lazy: the constructor validates (cwd, `configOptions`, the registry, `clientHandlers`) and
- * routes the backend synchronously but spawns nothing; the first queued operation (an explicit
- * `ready()` or an implicit `prompt()`) opens the session. `state` walks
- * `idle → opening → ready ⇄ busy → closed`.
+ * Lazy: the constructor validates (cwd, `configOptions`, the registry, `clientHandlers`, the
+ * function-tool definitions, `schemaRetries`) and routes the backend synchronously but spawns nothing; the first
+ * queued operation (an explicit `ready()` or an implicit `prompt()`) opens the session. `state`
+ * walks `idle → opening → ready ⇄ busy → closed`.
  */
 export class AcpAgent {
     /** The session's absolute working directory (sent on session/new|fork|resume|load). */
     cwd;
     /** The human label stamped on event contexts and error `agentLabel`; never on the wire. */
     label;
-    /** The model this agent selects at open, as a routing spec that leads back to the same backend
-     *  (`<backendId>/<model id>`, e.g. `"claude/opus[1m]"`), or `undefined` when no model was
-     *  selected (the backend's default). Inherited by forks. An `AgentSessionRef` carries no model,
-     *  so a cold reopen keeps it only when told: `AcpAgent.resume(agent.sessionRef!, { model: agent.model })`. */
-    model;
     #options;
     #seed;
     #registry;
     #backend;
+    /** The verbatim model id this agent is on (what open sends and a switch replaces); `undefined`
+     *  = no selection. Read by open's post-open apply and by `fork()` for the child's seed. */
     #modelSpec;
+    /** `#modelSpec` in its routed spec form (`<backendId>/<id>`) — what the `model` getter returns. */
+    #model;
     #schema;
+    /** The default repair budget (`schemaRetries`, validated in the constructor); a per-turn value wins. */
+    #schemaRetries;
+    #tools;
     #retainHistory;
     #raw;
     #signal;
@@ -124,11 +132,22 @@ export class AcpAgent {
     #handle;
     #plan;
     #structuredHost;
+    /** The `agent_tools` host, created lazily by the first open that injects it; disposed on close. */
+    #toolHost;
+    /** The collector of the turn on the wire — what a function tool's `toolCallId` is correlated against. */
+    #activeCollector;
     #sessionId;
     #sessionRef;
     #sessionUsage = ZERO_USAGE;
     #historySeed = [];
     #textSeed = "";
+    #messagesSeed = [];
+    /** The retained transcript as messages — the same updates the handle's accumulator folds into
+     *  `history`/`text`, folded per message. Live once the session is registered; a `load` replay
+     *  is folded from `#replay` at that point (the accumulator saw it too); a fork's pre-response
+     *  replay is not (the accumulator never saw it — it lands in `replay` only). */
+    #transcript = new MessageFolder();
+    #transcriptLive = false;
     #collectingReplay = false;
     #activeTurn;
     #closePromise;
@@ -140,40 +159,54 @@ export class AcpAgent {
     #forkCount = 0;
     #removeAbort;
     /**
-     * Lazy: validates cwd/configOptions/registry/clientHandlers synchronously, routes the backend,
-     * spawns nothing. This is the ONLY public constructor signature — seeded agents (forks, cold
-     * reopen) are built by the statics through a module-private factory.
+     * Lazy: validates cwd/configOptions/registry/clientHandlers/tools/schemaRetries synchronously,
+     * routes the backend, spawns nothing. This is the ONLY public constructor signature — seeded agents (forks,
+     * cold reopen) are built by the statics through a module-private factory.
      */
     constructor(options) {
         const label = options.label;
-        validateAgentCwd(options.cwd, label, "AcpAgent");
-        assertNoModelConfigOption(options.configOptions, label);
-        try {
-            validateClientHandlers(options.clientHandlers);
-        }
-        catch (error) {
-            throw agentValidationError(error instanceof Error ? error.message : String(error), label);
-        }
-        const seed = constructionSeed ?? resolveNewSeed(options);
+        // Every pre-spawn guard speaks INVALID_ARGUMENT: the SDK's own throw it directly, a shared
+        // validator's SCRIPT_VALIDATION_ERROR is re-coded here at the boundary.
+        const { seed, tools, schemaRetries } = validateArguments(() => {
+            validateAgentCwd(options.cwd, label, "AcpAgent");
+            assertNoModelConfigOption(options.configOptions, label);
+            try {
+                validateClientHandlers(options.clientHandlers);
+            }
+            catch (error) {
+                throw agentValidationError(error instanceof Error ? error.message : String(error), label);
+            }
+            const tools = validateToolDefinitions(options.tools, label);
+            const schemaRetries = validateSchemaRetries(options.schemaRetries, label, "AcpAgent");
+            return { seed: constructionSeed ?? resolveNewSeed(options), tools, schemaRetries };
+        });
         this.#options = { ...options };
+        this.#tools = tools;
+        this.#schemaRetries = schemaRetries;
         this.#seed = seed;
         this.#registry = seed.registry;
         this.#backend = seed.backend;
         this.#modelSpec = seed.modelSpec;
         this.cwd = options.cwd;
         this.label = label;
-        this.model = seed.modelSpec === undefined ? undefined : `${seed.backend.id}/${seed.modelSpec}`;
+        this.#model = seed.modelSpec === undefined ? undefined : `${seed.backend.id}/${seed.modelSpec}`;
         this.#schema = options.schema;
         this.#retainHistory = options.retainHistory ?? true;
         this.#raw = options.raw ?? true;
         this.#signal = options.signal;
         // Verbatim session/update records received before the session was ready (a load's replay, a
         // fork's pre-response replay) — adopted from the acquisition buffer, observable as `replay`.
+        // Once the session is registered, every update is folded into the message transcript.
         this.#bus.tap((name, event) => {
-            if (name !== "session_update" || !this.#collectingReplay)
+            if (name !== "session_update")
                 return;
             const { update } = event;
-            this.#replay.push({ update: structuredClone(update), receivedAt: Date.now() });
+            if (this.#collectingReplay) {
+                this.#replay.push({ update: structuredClone(update), receivedAt: Date.now() });
+            }
+            else if (this.#transcriptLive) {
+                this.#transcript.apply(structuredClone(update), Date.now());
+            }
         });
         if (options.signal) {
             const signal = options.signal;
@@ -218,6 +251,17 @@ export class AcpAgent {
     static probe(options = {}) {
         return probeCatalog(options);
     }
+    /** The table-based traits of the backend `spec` routes to — exactly the constructor's routing
+     *  (`backends` merged over `AGENTPRISM_BACKENDS`, a registered name wins, an unrouted spec goes
+     *  to the default backend) — without spawning anything. The instance getter refines the same
+     *  shape with the live initialize advertisements once the agent is open. */
+    static traits(spec, options = {}) {
+        return validateArguments(() => {
+            const registry = resolveAgentRegistry(options.backends);
+            const route = resolveAgentRoute({ model: spec }, registry);
+            return describeBackendTraits(route.backend, registry);
+        });
+    }
     /** `session/resume` of `ref.sessionId` on a fresh dedicated process of `ref.backendId`
      *  (routed by name — never the default backend — and pool-key checked). `cwd` defaults to
      *  `ref.cwd`; `model` must stay on the ref's backend. */
@@ -230,33 +274,34 @@ export class AcpAgent {
     static load(ref, options = {}) {
         return AcpAgent.#reopen("load", ref, options);
     }
-    /** Cold fork of a recorded session: the trait-driven choreography without a history seed
-     *  (`history` starts empty on id-only backends unless the reattach fell back to `session/load`).
-     *  To seed the fork with the transcript: `const src = await AcpAgent.load(ref); await src.fork()`. */
+    /** Cold fork of a recorded session: the trait-driven choreography with no parent to seed from,
+     *  so on an id-only backend the reattach PREFERS `session/load` — the agent replays the forked
+     *  transcript and it lands in the child's `history`/`text`/`messages`/`replay` — and takes
+     *  `session/resume` (an empty transcript) only when load is not advertised. On a live backend the
+     *  fork handle is the session and the child's transcript is whatever the agent streams. */
     static fork(ref, options = {}) {
         return AcpAgent.#reopen("fork", ref, options);
     }
     static async #reopen(kind, ref, options) {
         const label = options.label;
         const method = `AcpAgent.${kind}`;
-        assertSessionRef(ref, label, method);
-        const cwd = options.cwd ?? ref.cwd;
-        validateAgentCwd(cwd, label, method);
-        const registry = resolveAgentRegistry(options.backends, label);
-        const route = resolveRefRoute(ref, options.model, registry, label);
-        assertSystemPromptSupported(route.backend, options.systemPrompt, label);
-        const base = { registry, backend: route.backend, modelSpec: route.modelSpec };
-        let seed;
-        if (kind === "fork") {
-            const trait = forkTraitFor(route.backend, registry);
-            if (trait.cwd === "source-only" && cwd !== ref.cwd) {
-                throw agentValidationError(`fork on ${route.backend.id} must keep the source cwd (${ref.cwd})`, label);
+        const { cwd, seed } = validateArguments(() => {
+            assertSessionRef(ref, label, method);
+            const cwd = options.cwd ?? ref.cwd;
+            validateAgentCwd(cwd, label, method);
+            const registry = resolveAgentRegistry(options.backends, label);
+            const route = resolveRefRoute(ref, options.model, registry, label);
+            assertSystemPromptSupported(route.backend, options.systemPrompt, label);
+            const base = { registry, backend: route.backend, modelSpec: route.modelSpec };
+            if (kind === "fork") {
+                const trait = forkTraitFor(route.backend, registry);
+                if (trait.cwd === "source-only" && cwd !== ref.cwd) {
+                    throw agentValidationError(`fork on ${route.backend.id} must keep the source cwd (${ref.cwd})`, label);
+                }
+                return { cwd, seed: { kind, sourceSessionId: ref.sessionId, reattach: "load", ...base } };
             }
-            seed = { kind, sourceSessionId: ref.sessionId, ...base };
-        }
-        else {
-            seed = { kind, sessionId: ref.sessionId, ...base };
-        }
+            return { cwd, seed: { kind, sessionId: ref.sessionId, ...base } };
+        });
         return AcpAgent.#opened(AcpAgent.#seeded({ ...options, cwd }, seed));
     }
     // ── Getters (all readable after close; they return retained values) ──
@@ -264,6 +309,15 @@ export class AcpAgent {
     get backendId() {
         return this.#backend.id;
     }
+    /** The model this agent is on, as a routing spec that leads back to the same backend
+     *  (`<backendId>/<model id>`, e.g. `"claude/opus[1m]"`): the constructor's `model` until a
+     *  `setModel()` or a per-turn `model` applied, then the switched one; `undefined` when nothing
+     *  was ever selected (the backend's default). Inherited by forks taken after the switch. An
+     *  `AgentSessionRef` carries no model, so a cold reopen keeps it only when told:
+     *  `AcpAgent.resume(agent.sessionRef!, { model: agent.model })`. */
+    get model() {
+        return this.#model;
+    }
     /** `idle` → `opening` → `ready` ⇄ `busy` → `closed` (set the instant `close()` is called,
      *  the constructor signal aborts, or the process dies). */
     get state() {
@@ -285,6 +339,12 @@ export class AcpAgent {
     get capabilities() {
         return this.#connection?.capabilities;
     }
+    /** This backend's traits (`describeBackendTraits`): the tables before open, refined by the live
+     *  initialize advertisements once the connection is up (retained after close). A fresh frozen
+     *  object per read. */
+    get traits() {
+        return describeBackendTraits(this.#backend, this.#registry, this.#connection?.capabilities);
+    }
     /** The latest echoed session config-option catalog (verbatim ACP wire shapes). */
     get configOptions() {
         return this.#handle?.advertisedConfigOptions ?? [];
@@ -312,6 +372,13 @@ export class AcpAgent {
     get text() {
         return [this.#textSeed, this.#handle?.foldedText() ?? ""].filter((part) => part !== "").join("\n\n");
     }
+    /** The retained transcript as messages (`AcpAgentMessage`, copies on read): `[...seed, ...this
+     *  session's messages]` — the same retained log `history`/`text` describe, folded per message
+     *  with the turn fold's boundary, a `load` replay included, seeded from the parent's snapshot on
+     *  a live fork, and holding only the latest turn under `retainHistory: false`. */
+    get messages() {
+        return [...this.#messagesSeed.map(copyMessage), ...this.#transcript.snapshot()];
+    }
     /** Running per-field sum of every turn this agent ran; `ZERO_USAGE` before the first turn. */
     get usage() {
         return this.#sessionUsage;
@@ -347,103 +414,224 @@ export class AcpAgent {
      * cancelled included). Rejects only on a wire rejection (mapped like the runner), validation,
      * abort (`signal.reason` untouched), a closed agent, or a typed session failure (the mapped
      * `WorkflowError` carrying the complete turn as `error.turn`; see `isAcpAgentTurnError`).
-     * `configOptions`/`mode` are applied before the turn and stick for the session. To stop a
-     * specific turn use `options.signal`: it rejects while queued or before the turn reached the
-     * wire (nothing is sent) and sends one `session/cancel` once in flight — `cancel()` reaches only
-     * a turn already on the wire.
+     * `model`/`configOptions`/`mode` are applied before the turn, in that order, and stick for the
+     * session. With a schema active and a `schemaRetries` budget > 0 (constructor or per turn), an
+     * `end_turn` that left `structured` absent is followed by up to that many repair turns inside
+     * this same operation; the resolved turn is the final attempt's with `structuredAttempts`. To
+     * stop a specific turn use `options.signal`: it rejects while queued or before the turn reached
+     * the wire (nothing is sent) and sends one `session/cancel` once in flight — `cancel()` reaches
+     * only a turn already on the wire (a repair turn included).
      */
     prompt(content, options = {}) {
-        return this.#enqueue(async () => {
-            await this.#ensureOpen();
-            options.signal?.throwIfAborted();
-            this.#signal?.throwIfAborted();
-            const handle = this.#handle;
-            const plan = this.#plan;
-            const backend = this.#backend;
-            const label = this.label;
+        return this.#enqueue(() => this.#promptTurn(content, options, "prompt"), options.signal);
+    }
+    /**
+     * The same turn as `prompt()`, observed as an async iterable of this turn's events: every bus
+     * event emitted while the turn's operation runs — from the instant it is dequeued (a lazy
+     * open's `session_open`, a per-turn `mode`'s `current_mode_update` included) until the wire
+     * settles — each tagged `{ type: <event name>, ...payload }` (an update once, under its kind;
+     * never the `session_update` catch-all; a concurrent `steer()`'s `steering` event and the
+     * permission / elicitation / raw_message events included), then the terminal
+     * `{ type: "turn", turn }` with exactly the `AcpAgentTurn` `prompt()` would have resolved.
+     * The turn is queued (FIFO) by this call, exactly like `prompt()`; events are buffered without
+     * dropping until consumed. When the turn rejects, the iterator yields the buffered events, then
+     * throws that same error. Leaving early — `break`, `return()`, `throw()` — aborts the turn's
+     * per-call signal: a turn still queued or not yet on the wire is dropped with nothing sent, a
+     * turn in flight gets the one `session/cancel` (and the agent's escalation), and the call
+     * resolves only once the turn settled, so no turn keeps running unobserved.
+     */
+    stream(content, options = {}) {
+        // The consumer's exit is not an error: the turn rejects with this marker, which never leaves
+        // the stream (a caller's own `options.signal` reason does — the iterator throws it).
+        const left = new Error("AcpAgent.stream(): the consumer stopped iterating");
+        const controller = new AbortController();
+        const outer = options.signal;
+        const forward = () => controller.abort(outer?.reason);
+        if (outer?.aborted)
+            controller.abort(outer.reason);
+        else
+            outer?.addEventListener("abort", forward, { once: true });
+        const stream = new TurnStream(() => {
+            controller.abort(left);
+            return settled.then(noop, noop);
+        });
+        // The tap is attached INSIDE the queued operation, the instant this turn is dequeued: from
+        // outside the queue it would observe the previous turn's events too.
+        const settled = this.#enqueue(async () => {
+            const untap = this.#bus.tap((name, event) => {
+                if (name === "session_update")
+                    return;
+                stream.push({ type: name, ...event });
+            });
+            try {
+                const turn = await this.#promptTurn(content, { ...options, signal: controller.signal }, "stream");
+                stream.push({ type: "turn", turn });
+                return turn;
+            }
+            finally {
+                untap();
+            }
+        }, controller.signal);
+        void settled.then(() => stream.end(), (error) => {
+            if (error === left)
+                stream.end();
+            else
+                stream.fail(error);
+        });
+        void settled.then(noop, noop).finally(() => outer?.removeEventListener("abort", forward));
+        return stream;
+    }
+    /** The body of one turn — runs inside the FIFO (`prompt()` queues it directly, `stream()` under
+     *  its tap). `options.signal` is the per-call signal; `stream()` hands in its own combined one.
+     *  `entry` is the public method the caller used, so a refused per-turn option names it. */
+    async #promptTurn(content, options, entry) {
+        await this.#ensureOpen();
+        options.signal?.throwIfAborted();
+        this.#signal?.throwIfAborted();
+        const handle = this.#handle;
+        const plan = this.#plan;
+        const backend = this.#backend;
+        const label = this.label;
+        // Every per-turn option is validated up front — a rejected turn sends nothing, not even the
+        // options that would have passed.
+        const { modelSwitch, schemaRetries } = validateArguments(() => {
             validatePromptImages(options.images, label);
             assertPerTurnSchemaAllowed(backend, options.schema, label);
             assertNoModelConfigOption(options.configOptions, label);
             assertKnownConfigOptionIds(options.configOptions, handle.advertisedConfigOptions, this.backendId, label);
-            try {
-                if (options.configOptions) {
-                    await handle.setConfigOptions(options.configOptions);
-                    options.signal?.throwIfAborted();
-                    this.#signal?.throwIfAborted();
-                }
-                if (options.mode !== undefined) {
-                    await handle.setMode(options.mode);
-                    options.signal?.throwIfAborted();
-                    this.#signal?.throwIfAborted();
-                }
-            }
-            catch (error) {
-                throw mapAgentError(error, this.#errorContext(), options.signal?.aborted ? options.signal : this.#signal);
-            }
-            const turnSchema = options.schema ?? this.#schema;
-            // Same request shaping as the runner: a generic backend whose agent may ignore the `_meta`
-            // forward gets the contract stated in-band; backend turn meta wins only direct collisions.
-            const shaped = typeof content === "string" && turnSchema !== undefined && backend.embedSchemaInPrompt
-                ? buildRunPrompt(content, {}, turnSchema, backend, plan.toolActive)
-                : content;
-            const turnContent = appendPromptImages(shaped, options.images);
-            const promptMeta = mergeTurnMeta(options.meta, backend.promptMeta(turnSchema));
-            // SYNCHRONOUSLY before the wire call: the collector's tap sees every update of the turn.
-            const collector = new TurnCollector(this.#bus, handle, { retainHistory: this.#retainHistory });
-            // A capture left by a turn that rejected (wire error/abort) must not leak into this turn.
-            plan.registration?.takeCaptured();
-            const outcome = handle.promptOutcome(turnContent, promptMeta);
-            const active = { ended: outcome.then(noop, noop), aborted: false };
-            this.#activeTurn = active;
-            const callSignal = options.signal;
-            const onCallAbort = () => {
-                active.aborted = true;
-                active.abortReason = callSignal?.reason;
-                void this.#cancelTurn().catch(noop);
+            return {
+                modelSwitch: options.model === undefined
+                    ? undefined
+                    : resolveModelSwitch(options.model, backend, this.#registry, label, `AcpAgent.${entry}({ model })`),
+                schemaRetries: options.schemaRetries === undefined
+                    ? this.#schemaRetries
+                    : validateSchemaRetries(options.schemaRetries, label, `AcpAgent.${entry}({ schemaRetries })`),
             };
-            callSignal?.addEventListener("abort", onCallAbort, { once: true });
-            let response;
-            let failure;
-            try {
-                ({ response, failure } = await outcome);
+        });
+        try {
+            // The open's order, verbatim: model, config options, mode.
+            if (modelSwitch) {
+                await this.#applyModelSwitch(handle, modelSwitch);
+                options.signal?.throwIfAborted();
+                this.#signal?.throwIfAborted();
             }
-            catch (error) {
-                if (active.aborted)
-                    throw active.abortReason;
-                if (this.#signal?.aborted)
-                    throw this.#signal.reason;
-                throw mapAgentError(error, this.#errorContext());
+            if (options.configOptions) {
+                await handle.setConfigOptions(options.configOptions);
+                options.signal?.throwIfAborted();
+                this.#signal?.throwIfAborted();
             }
-            finally {
-                collector.stop();
-                callSignal?.removeEventListener("abort", onCallAbort);
-                if (this.#activeTurn === active)
-                    this.#activeTurn = undefined;
+            if (options.mode !== undefined) {
+                await handle.setMode(options.mode);
+                options.signal?.throwIfAborted();
+                this.#signal?.throwIfAborted();
             }
-            // An abort observed in flight rejects with the reason even when the agent answered
-            // `stopReason: "cancelled"` — abort is never a resolved turn.
+        }
+        catch (error) {
+            throw mapAgentError(error, this.#errorContext(), options.signal?.aborted ? options.signal : this.#signal);
+        }
+        const turnSchema = options.schema ?? this.#schema;
+        // Same request shaping as the runner: a generic backend whose agent may ignore the `_meta`
+        // forward gets the contract stated in-band; backend turn meta wins only direct collisions.
+        const shaped = typeof content === "string" && turnSchema !== undefined && backend.embedSchemaInPrompt
+            ? buildRunPrompt(content, {}, turnSchema, backend, plan.toolActive)
+            : content;
+        const turnContent = appendPromptImages(shaped, options.images);
+        const promptMeta = mergeTurnMeta(options.meta, backend.promptMeta(turnSchema));
+        let attempt = await this.#runTurn(turnContent, promptMeta, turnSchema, options.signal);
+        if (turnSchema === undefined) {
+            if (attempt.failure)
+                throw agentTurnError(attempt.failure, attempt.turn, this.#errorContext());
+            return attempt.turn;
+        }
+        // The opt-in repair ladder (`schemaRetries`, default 0): re-prompt the SAME session with the
+        // runner's repair prompt — the StructuredOutput-tool variant when the tool is active, else
+        // the JSON one, plus the attempt's validation failure — and the same turn `_meta`, so the
+        // native channel stays authoritative (Codex's per-turn `outputSchema` rides the repair too).
+        // Text only, like the runner's repair turns: no images, no re-embedded contract. Only an
+        // `end_turn` miss is repaired — a cancelled, refused, or truncated attempt (or a walled one)
+        // ends the ladder where it stands; a per-call or agent abort between attempts rejects.
+        let attempts = 1;
+        while (attempts <= schemaRetries &&
+            attempt.failure === undefined &&
+            attempt.turn.structured === undefined &&
+            attempt.turn.stopReason === "end_turn") {
+            options.signal?.throwIfAborted();
+            this.#signal?.throwIfAborted();
+            const repair = repairPromptText({ toolActive: plan.toolActive, reason: attempt.turn.structuredError });
+            attempt = await this.#runTurn(repair, promptMeta, turnSchema, options.signal);
+            attempts += 1;
+        }
+        const turn = { ...attempt.turn, structuredAttempts: attempts };
+        if (attempt.failure)
+            throw agentTurnError(attempt.failure, turn, this.#errorContext());
+        return turn;
+    }
+    /** ONE `session/prompt` on the wire and its fold: the collector's tap is attached synchronously
+     *  before the call, the turn is the agent's active turn for `cancel()`/`steer()`/tool
+     *  correlation while it flies, an abort observed in flight rejects with the reason (never a
+     *  resolved `cancelled` turn), and the turn's tokens are added to the session sum whether or
+     *  not it was walled. `#promptTurn` runs it once, plus once per repair. */
+    async #runTurn(content, promptMeta, schema, callSignal) {
+        const handle = this.#handle;
+        const plan = this.#plan;
+        // SYNCHRONOUSLY before the wire call: the collector's tap sees every update of the turn, and
+        // the transcript marks the turn boundary exactly where the handle's accumulator does
+        // (`SessionState.beginTurn()` inside `promptOutcome`) — nothing can interleave.
+        const collector = new TurnCollector(this.#bus, handle, { retainHistory: this.#retainHistory });
+        this.#transcript.beginTurn(this.#retainHistory);
+        // A capture left by a turn that rejected (wire error/abort) must not leak into this turn.
+        plan.registration?.takeCaptured();
+        const outcome = handle.promptOutcome(content, promptMeta);
+        const active = { ended: outcome.then(noop, noop), aborted: false };
+        this.#activeTurn = active;
+        this.#activeCollector = collector;
+        const onCallAbort = () => {
+            active.aborted = true;
+            active.abortReason = callSignal?.reason;
+            void this.#cancelTurn(callSignal?.reason).catch(noop);
+        };
+        callSignal?.addEventListener("abort", onCallAbort, { once: true });
+        let response;
+        let failure;
+        try {
+            ({ response, failure } = await outcome);
+        }
+        catch (error) {
             if (active.aborted)
                 throw active.abortReason;
             if (this.#signal?.aborted)
                 throw this.#signal.reason;
-            const turn = buildTurn({
-                response,
-                collector,
-                handle,
-                backend,
-                schema: turnSchema,
-                captured: plan.registration?.takeCaptured(),
-                sessionBefore: this.#sessionUsage,
-            });
-            // A walled turn still counts the tokens it burned.
-            this.#sessionUsage = turn.usage.session;
-            if (failure)
-                throw agentTurnError(failure, turn, this.#errorContext());
-            return turn;
-        }, options.signal);
+            throw mapAgentError(error, this.#errorContext());
+        }
+        finally {
+            collector.stop();
+            callSignal?.removeEventListener("abort", onCallAbort);
+            if (this.#activeTurn === active)
+                this.#activeTurn = undefined;
+            if (this.#activeCollector === collector)
+                this.#activeCollector = undefined;
+        }
+        // An abort observed in flight rejects with the reason even when the agent answered
+        // `stopReason: "cancelled"` — abort is never a resolved turn.
+        if (active.aborted)
+            throw active.abortReason;
+        if (this.#signal?.aborted)
+            throw this.#signal.reason;
+        const turn = buildTurn({
+            response,
+            collector,
+            handle,
+            backend: this.#backend,
+            schema,
+            captured: plan.registration?.takeCaptured(),
+            sessionBefore: this.#sessionUsage,
+        });
+        // A walled turn still counts the tokens it burned.
+        this.#sessionUsage = turn.usage.session;
+        return failure ? { turn, failure } : { turn };
     }
     /** Inject content into the turn in flight (`_session/steering`). Overlaps the FIFO; requires a
-     *  `prompt()` in flight (SCRIPT_VALIDATION_ERROR otherwise). The complete raw response is returned. */
+     *  `prompt()` in flight (INVALID_ARGUMENT otherwise). The complete raw response is returned. */
     async steer(content, options = {}) {
         this.#signal?.throwIfAborted();
         if (this.#closed)
@@ -452,7 +640,7 @@ export class AcpAgent {
         if (!this.#activeTurn || !handle) {
             throw agentValidationError("AcpAgent.steer() requires a prompt() in flight", this.label);
         }
-        validatePromptImages(options.images, this.label);
+        validateArguments(() => validatePromptImages(options.images, this.label));
         try {
             return await handle.steer(appendPromptImages(content, options.images), options.meta);
         }
@@ -466,11 +654,11 @@ export class AcpAgent {
      *  grace period ends in process disposal WITHOUT a wire `session/close` (the session stays
      *  re-openable through `sessionRef`); the turn then rejects and the agent is closed. Queued
      *  turns are untouched, and so is a turn that has started (`state === "busy"`) but has not
-     *  reached the wire yet — the lazy first open, or its per-turn `configOptions`/`mode` — a
-     *  `cancel()` in that window is a no-op the turn never sees. A per-call `signal` covers every
+     *  reached the wire yet — the lazy first open, or its per-turn `model`/`configOptions`/`mode` —
+     *  a `cancel()` in that window is a no-op the turn never sees. A per-call `signal` covers every
      *  window (rejects with the reason before anything is sent; `session/cancel` once in flight). */
     cancel() {
-        return this.#cancelTurn();
+        return this.#cancelTurn(new Error("AcpAgent.cancel(): the turn was cancelled"));
     }
     /**
      * Fork this agent onto a NEW dedicated process (queued: it runs only when no turn is in flight,
@@ -505,35 +693,73 @@ export class AcpAgent {
                 providerStore: this.#options.providerStore,
                 clientHandlers: this.#options.clientHandlers,
             };
-            validateAgentCwd(cwd, this.label, "AcpAgent.fork");
-            if (trait.cwd === "source-only" && cwd !== this.cwd) {
-                throw agentValidationError(`fork on ${this.backendId} must keep the source cwd (${this.cwd})`, this.label);
-            }
-            let route;
-            if (overrides.model !== undefined) {
-                route = resolveModelRoute(overrides.model, this.#registry);
-                const samePool = (route.backend.poolKey ?? route.backend.id) === (this.#backend.poolKey ?? this.backendId);
-                if (route.backend.id !== this.backendId || !samePool) {
-                    throw agentValidationError(`fork model "${overrides.model}" must stay on backend "${this.backendId}"`, this.label);
+            const route = validateArguments(() => {
+                validateAgentCwd(cwd, this.label, "AcpAgent.fork");
+                if (trait.cwd === "source-only" && cwd !== this.cwd) {
+                    throw agentValidationError(`fork on ${this.backendId} must keep the source cwd (${this.cwd})`, this.label);
                 }
-            }
-            assertNoModelConfigOption(merged.configOptions, label);
-            // The backend is fixed by the parent, so an inherited value already passed; an override
-            // is validated here, before the child's process spawns.
-            assertSystemPromptSupported(this.#backend, merged.systemPrompt, label);
+                let route;
+                if (overrides.model !== undefined) {
+                    route = resolveSameBackendModel(overrides.model, this.#backend, this.#registry, this.label, "AcpAgent.fork()");
+                }
+                assertNoModelConfigOption(merged.configOptions, label);
+                // The backend is fixed by the parent, so an inherited value already passed; an override
+                // is validated here, before the child's process spawns.
+                assertSystemPromptSupported(this.#backend, merged.systemPrompt, label);
+                return route;
+            });
             const child = AcpAgent.#seeded(merged, {
                 kind: "fork",
                 sourceSessionId: handle.sessionId,
+                // The parent's snapshot seeds the child: reattach without a replay (load is the fallback).
+                reattach: "resume",
                 registry: this.#registry,
                 backend: route?.backend ?? freshBackendFor(this.#backend, this.#registry),
+                // The model the parent is on NOW (a `setModel` / per-turn switch included), not its
+                // constructor option — `merged.model` is never read for a seeded child.
                 modelSpec: route ? route.modelSpec : this.#modelSpec,
                 historySeed: this.history.map((entry) => ({ ...entry })),
                 textSeed: this.text,
+                messagesSeed: [...this.messages],
             });
             return AcpAgent.#opened(child);
         });
     }
-    /** `session/set_mode` (queued; strict — an unadvertised id is a SCRIPT_VALIDATION_ERROR). */
+    /**
+     * Switch the session's model (queued, FIFO like `setMode`; sticky). `spec` is resolved with the
+     * fork rule — the runner's routing grammar, and it must land on this agent's backend and poolKey
+     * (`"<backendId>/<model id>"`; an unrouted spec goes to the default backend and passes only when
+     * that is this one) — otherwise INVALID_ARGUMENT naming both backends. The route is checked
+     * BEFORE the operation is queued, so a refused spec sends nothing and, on an agent that has not
+     * opened yet, spawns nothing (the agent stays `idle`). A backend-only spec is INVALID_ARGUMENT
+     * too: there is no wire form for "unselect". Applied exactly like open's selection —
+     * `session/set_config_option { configId: "model" }` with the routed remainder verbatim; no
+     * aliases, coercion, catalog matching, or fallback; the agent's catalog and validation are
+     * authoritative and a wire rejection maps through the normal error path with `model` unchanged.
+     * On success `model` becomes the routed spec, so later forks and a cold reopen passing
+     * `agent.model` back inherit the switch. `"model"` stays reserved in `configOptions`; this is
+     * the one way to move it after open.
+     */
+    setModel(spec) {
+        let modelSwitch;
+        try {
+            modelSwitch = validateArguments(() => resolveModelSwitch(spec, this.#backend, this.#registry, this.label, "AcpAgent.setModel()"));
+        }
+        catch (error) {
+            return Promise.reject(error);
+        }
+        return this.#enqueue(async () => {
+            await this.#ensureOpen();
+            this.#signal?.throwIfAborted();
+            try {
+                await this.#applyModelSwitch(this.#handle, modelSwitch);
+            }
+            catch (error) {
+                throw mapAgentError(error, this.#errorContext(), this.#signal);
+            }
+        });
+    }
+    /** `session/set_mode` (queued; strict — an unadvertised id is INVALID_ARGUMENT). */
     setMode(modeId) {
         return this.#enqueue(async () => {
             await this.#ensureOpen();
@@ -553,8 +779,10 @@ export class AcpAgent {
             await this.#ensureOpen();
             this.#signal?.throwIfAborted();
             const handle = this.#handle;
-            assertNoModelConfigOption(options, this.label);
-            assertKnownConfigOptionIds(options, handle.advertisedConfigOptions, this.backendId, this.label);
+            validateArguments(() => {
+                assertNoModelConfigOption(options, this.label);
+                assertKnownConfigOptionIds(options, handle.advertisedConfigOptions, this.backendId, this.label);
+            });
             try {
                 await handle.setConfigOptions(options);
             }
@@ -567,8 +795,9 @@ export class AcpAgent {
      * Close: `state` becomes `closed` immediately (no new work is admitted), the teardown waits
      * behind queued work, releases the session (`keep: true` skips the wire `session/close` so the
      * agent-persisted session stays re-openable via `sessionRef`), disposes the dedicated process,
-     * and releases the structured-output tool. Idempotent (same promise); never throws for an
-     * already-dead process; rethrows only a `child_cleanup_error` (mapped, non-recoverable).
+     * releases the structured-output tool, and closes the function-tool host (aborting any running
+     * `execute`). Idempotent (same promise); never throws for an already-dead process; rethrows
+     * only a `child_cleanup_error` (mapped, non-recoverable).
      */
     close(options = {}) {
         this.#closeKeep ??= options.keep === true;
@@ -624,7 +853,7 @@ export class AcpAgent {
         return {
             cwd: this.cwd,
             schema: this.#schema,
-            policy: options.tools ?? {},
+            policy: options.permissions ?? {},
             permissionResolver: options.onPermissionRequest,
             enforceToolPolicyBeforePermissionResolver: false,
             elicitationResolver: options.onElicitation,
@@ -637,13 +866,46 @@ export class AcpAgent {
             retainSessionLog: this.#retainHistory,
         };
     }
-    #planStructured(connection) {
-        return planStructured({
+    /** After initialize (the capabilities are known): the structured-output injection, then the
+     *  function-tool injection appended to the same `mcpServers` — or the INVALID_ARGUMENT refusal
+     *  when the agent does not advertise HTTP MCP for the tools it was given. */
+    async #planSession(connection) {
+        const structured = await planStructured({
             schema: this.#schema,
             backend: this.#backend,
             mcpServers: this.#options.mcpServers,
             host: () => (this.#structuredHost ??= new StructuredOutputToolHost()),
         }, connection);
+        const mcpServers = await planTools({
+            tools: this.#tools,
+            backendId: this.backendId,
+            label: this.label,
+            mcpServers: structured.mcpServers,
+            host: () => (this.#toolHost ??= new AgentToolHost(this.#tools, () => this.#toolContext())),
+        }, connection);
+        return { ...structured, mcpServers };
+    }
+    #toolContext() {
+        return {
+            sessionId: this.#sessionId,
+            backendId: this.backendId,
+            label: this.label,
+            resolveToolCallId: (toolName) => this.#resolveToolCallId(toolName),
+        };
+    }
+    /** Best-effort: the latest unsettled `tool_call` of the turn in flight whose standard `name`
+     *  (or `title`) is the tool's name or ends in `__<name>` (pi's `mcp__agent_tools__<name>`). */
+    #resolveToolCallId(toolName) {
+        const calls = this.#activeCollector?.toolCalls ?? [];
+        for (let index = calls.length - 1; index >= 0; index -= 1) {
+            const call = calls[index];
+            if (call.status === "completed" || call.status === "failed")
+                continue;
+            const names = [call.name, call.title].filter((value) => typeof value === "string");
+            if (names.some((name) => name === toolName || name.endsWith(`__${toolName}`)))
+                return call.toolCallId;
+        }
+        return undefined;
     }
     async #open() {
         let handle;
@@ -662,18 +924,18 @@ export class AcpAgent {
             if (seed.kind === "new") {
                 // `prepare` runs after initialize, so the injection decision sees the capabilities.
                 handle = await connection.openPreparedSession(async (ready) => {
-                    plan = await this.#planStructured(ready);
+                    plan = await this.#planSession(ready);
                     return this.#sessionOptions(plan);
                 });
             }
             else {
                 // The cheapest "await initialize": the injection decision needs the capabilities.
                 await connection.authMethods();
-                plan = await this.#planStructured(connection);
+                plan = await this.#planSession(connection);
                 const opts = this.#sessionOptions(plan);
                 if (seed.kind === "fork") {
                     const trait = forkTraitFor(this.#backend, this.#registry);
-                    const acquired = await acquireForkedSession(connection, seed.sourceSessionId, opts, trait);
+                    const acquired = await acquireForkedSession(connection, seed.sourceSessionId, opts, trait, seed.reattach);
                     handle = acquired.handle;
                     replayed = acquired.method === "load";
                 }
@@ -694,10 +956,19 @@ export class AcpAgent {
             this.#sessionId = handle.sessionId;
             this.#bus.endAcquisition(handle.sessionId);
             this.#collectingReplay = false;
+            // The transcript follows the handle's accumulator: a replay the registered session applied
+            // (`session/load`, the id-only fork's load fallback) is folded from the adopted records; a
+            // pre-response fork replay was never applied there and stays in `replay` alone. Live from
+            // here on — synchronously, so no later update can slip between the two.
+            if (replayed) {
+                for (const { update, receivedAt } of this.#replay)
+                    this.#transcript.apply(structuredClone(update), receivedAt);
+            }
+            this.#transcriptLive = true;
             this.#signal?.throwIfAborted();
             await this.#applyPostOpen(handle);
             if (seed.kind === "fork")
-                this.#seedHistory(seed.historySeed, seed.textSeed, handle);
+                this.#seedHistory(seed, handle);
             this.#sessionRef = sessionRefFor(handle, this.#backend, this.cwd);
             this.#sessionUsage = ZERO_USAGE;
         }
@@ -713,6 +984,14 @@ export class AcpAgent {
             throw this.#signal?.aborted ? this.#signal.reason : mapAgentError(error, this.#errorContext());
         }
     }
+    /** The one mechanism behind every model selection after open (`setModel`, a per-turn `model`):
+     *  `SessionHandle.selectModel` — the same call open makes — then `model` moves to the routed
+     *  spec. Nothing moves when the wire rejects. */
+    async #applyModelSwitch(handle, next) {
+        await handle.selectModel(next.modelSpec);
+        this.#modelSpec = next.modelSpec;
+        this.#model = next.model;
+    }
     /** Re-apply model selection, config options and the mode on the LIVE handle (fork/resume/load
      *  responses replace the catalog). The mode rule is the runner's, verbatim. */
     async #applyPostOpen(handle) {
@@ -731,20 +1010,25 @@ export class AcpAgent {
         }
         this.#signal?.throwIfAborted();
     }
-    /** Seed a live fork's history/text from the parent's snapshot — only when the child's own
-     *  accumulator is empty (a `session/load` fallback already replayed the transcript). */
-    #seedHistory(seed, text, handle) {
-        if (!seed || handle.history.length > 0)
+    /** Seed a live fork's history/text/messages from the parent's snapshot — only when the child's
+     *  own accumulator is empty (a `session/load` reattach already replayed the transcript). The
+     *  cold static carries no seed: its transcript is the load replay, or empty after a resume. */
+    #seedHistory(seed, handle) {
+        if (!seed.historySeed || handle.history.length > 0)
             return;
-        this.#historySeed = seed;
-        this.#textSeed = text ?? "";
+        this.#historySeed = seed.historySeed;
+        this.#textSeed = seed.textSeed ?? "";
+        this.#messagesSeed = seed.messagesSeed ?? [];
     }
-    #cancelTurn() {
+    /** `reason` is what a running function tool's `ctx.signal` aborts with. */
+    #cancelTurn(reason) {
         const active = this.#activeTurn;
         const connection = this.#connection;
         const sessionId = this.#sessionId;
         if (!active || !connection || sessionId === undefined)
             return Promise.resolve();
+        // A function tool running for this turn stops with it.
+        this.#toolHost?.abortInFlight(reason);
         // Settles pending permissions/elicitations + ONE session/cancel notify.
         active.cancelRequested ??= connection.cancelSession(sessionId);
         active.escalation ??= active.cancelRequested.then(async () => {
@@ -760,7 +1044,8 @@ export class AcpAgent {
         const reason = this.#signal?.reason;
         this.#closed = true;
         this.#queue.drain(reason);
-        void this.#cancelTurn().catch(noop);
+        this.#toolHost?.abortInFlight(reason);
+        void this.#cancelTurn(reason).catch(noop);
         // An open/fork/reattach in flight: dispose the process so the raced wire call rejects.
         if (this.#handle === undefined && this.#connection)
             void this.#connection.dispose().catch(noop);
@@ -808,6 +1093,7 @@ export class AcpAgent {
         const connection = this.#connection;
         const plan = this.#plan;
         const host = this.#structuredHost;
+        const toolHost = this.#toolHost;
         let cleanupError;
         try {
             if (handle)
@@ -818,8 +1104,8 @@ export class AcpAgent {
                 cleanupError = error;
         }
         plan?.registration?.release();
-        // The process BEFORE the tool host (the runner's order: pool, then tools): the agent process
-        // holds keep-alive sockets to the host's HTTP server, and `server.close()` waits for idle
+        // The process BEFORE the tool hosts (the runner's order: pool, then tools): the agent process
+        // holds keep-alive sockets to the hosts' HTTP servers, and `server.close()` waits for idle
         // sockets to time out (seconds) unless the peer is gone first.
         if (connection) {
             await connection.dispose().catch(noop);
@@ -827,6 +1113,8 @@ export class AcpAgent {
         }
         if (host)
             await host.dispose().catch(noop);
+        if (toolHost)
+            await toolHost.dispose().catch(noop);
         this.#removeAbort?.();
         this.#removeAbort = undefined;
         // Last, so the agent's own `session_close` (emitted by the release above) was delivered.