@automatalabs/acp-agents 1.2.6 → 1.3.0

package/dist/agent/routing.js

@@ -0,0 +1,87 @@
+// Agent-facing routing over ../routing.js: the registry read (malformed → SCRIPT_VALIDATION_ERROR),
+// the runner's model-spec grammar for `new AcpAgent({ model })`, the ref-driven route the cold
+// statics use (never the default backend), cwd validation that fails BEFORE a process spawns, and
+// the fresh-Backend-instance rule a fork child needs.
+import { isAbsolute } from "node:path";
+import { statSync } from "node:fs";
+import { builtinBackend } from "../backends/builtins.js";
+import { CustomAcpBackend } from "../backends/custom.js";
+import { resolveBackendRegistry } from "../registry.js";
+import { asciiLowercase, resolveModelRoute } from "../routing.js";
+import { agentValidationError } from "./errors.js";
+/** The custom-backend registry for an agent: `backends` merged over `AGENTPRISM_BACKENDS`. A
+ *  malformed registry is a caller error (SCRIPT_VALIDATION_ERROR), mirroring the runner's wrap. */
+export function resolveAgentRegistry(backends, label) {
+    try {
+        return resolveBackendRegistry(backends);
+    }
+    catch (error) {
+        throw agentValidationError(error instanceof Error ? error.message : String(error), label);
+    }
+}
+/** The runner's routing grammar applied to `new AcpAgent({ model })`. */
+export function resolveAgentRoute(options, registry) {
+    return resolveModelRoute(options.model, registry);
+}
+/**
+ * Route a cold reopen from a session ref. `ref.backendId` must name a registered custom backend
+ * (wins, like `resolveModelRoute`) or a built-in — NEVER the default backend; the ref's `poolKey`
+ * must match the currently resolved `poolKey ?? id` (the runner's silent `backend-mismatch` skip,
+ * made loud); an optional `model` must stay on the ref's backend: `<ref.backendId>/<inner>` strips
+ * the prefix, a spec routing to another known backend is rejected, and an unrouted spec goes
+ * VERBATIM to the ref's backend (the same unrouted rule as the runner, applied to this backend).
+ */
+export function resolveRefRoute(ref, model, registry, label) {
+    const backend = backendNamed(ref.backendId, registry);
+    if (!backend) {
+        throw agentValidationError(`session ref names backend "${ref.backendId}" which is neither a built-in nor a registered custom backend`, label);
+    }
+    const expected = backend.poolKey ?? backend.id;
+    if (ref.poolKey !== undefined && ref.poolKey !== expected) {
+        throw agentValidationError(`session ref pool key "${ref.poolKey}" does not match the currently resolved "${expected}" for "${ref.backendId}"`, label);
+    }
+    if (model === undefined)
+        return { backend, modelSpec: undefined };
+    const slash = model.indexOf("/");
+    const first = asciiLowercase(slash >= 0 ? model.slice(0, slash) : model);
+    const inner = slash >= 0 ? model.slice(slash + 1) : undefined;
+    if (first === ref.backendId)
+        return { backend, modelSpec: inner };
+    if (registry.get(first) || builtinBackend(first)) {
+        throw agentValidationError(`model "${model}" routes to "${first}" but the session ref belongs to "${ref.backendId}"`, label);
+    }
+    return { backend, modelSpec: model };
+}
+/** A fresh `Backend` instance with the same identity as `backend` (a registered name wins, as in
+ *  routing; else the built-in of that id). A fork child must own its own instance — pooling identity
+ *  is `poolKey ?? id`, never the object. */
+export function freshBackendFor(backend, registry) {
+    return backendNamed(backend.id, registry) ?? backend;
+}
+function backendNamed(name, registry) {
+    const custom = registry.get(name);
+    if (custom)
+        return new CustomAcpBackend(custom);
+    return builtinBackend(name);
+}
+/** Stricter than the runner's interactive check and equal to the Claude adapter's own: absolute,
+ *  existing, and a directory — so the failure happens before a process spawns. */
+export function validateAgentCwd(cwd, label, method) {
+    if (typeof cwd !== "string" || cwd.trim() === "" || !isAbsolute(cwd)) {
+        throw agentValidationError(`${method} requires cwd to be a non-empty absolute path`, label);
+    }
+    let stat;
+    try {
+        stat = statSync(cwd, { throwIfNoEntry: false });
+    }
+    catch (error) {
+        // `throwIfNoEntry` only suppresses ENOENT; EACCES / ELOOP / ENOTDIR on a parent are caller
+        // errors too, not raw Node errors.
+        const code = error.code;
+        const detail = typeof code === "string" ? code : error instanceof Error ? error.message : String(error);
+        throw agentValidationError(`${method} cwd is not accessible: ${cwd} (${detail})`, label);
+    }
+    if (stat?.isDirectory() !== true) {
+        throw agentValidationError(`${method} cwd does not exist or is not a directory: ${cwd}`, label);
+    }
+}

package/dist/agent/structured.d.ts

@@ -0,0 +1,47 @@
+import type { TSchema } from "typebox";
+import type { McpServerConfig } from "@automatalabs/shared-types";
+import type { PooledConnection } from "../acp-client.js";
+import type { Backend, StructuredSource } from "../backend.js";
+import { type StructuredOutputToolHost, type StructuredOutputToolRegistration } from "../structured-tool.js";
+export interface StructuredPlan {
+    readonly schema: TSchema | undefined;
+    /** An injected StructuredOutput tool is on this session. */
+    readonly toolActive: boolean;
+    /** The caller's `mcpServers` (+ the injected http server when `toolActive`). */
+    readonly mcpServers: McpServerConfig[] | undefined;
+    readonly host?: StructuredOutputToolHost;
+    readonly registration?: StructuredOutputToolRegistration;
+}
+/** What `planStructured` reads from the agent (kept as a small seam so it needs no class access). */
+export interface StructuredPlanInputs {
+    readonly schema: TSchema | undefined;
+    readonly backend: Backend;
+    readonly mcpServers: McpServerConfig[] | undefined;
+    /** The agent's lazily created tool host (one per agent, disposed on close). */
+    readonly host: () => StructuredOutputToolHost;
+}
+/** `structured_output`, then `structured_output_2`, `_3`, … — never colliding with a caller's server. */
+export declare function availableMcpServerName(base: string, servers: readonly McpServerConfig[] | undefined): string;
+/** Decide (after initialize, so the capabilities are known) whether this session gets the injected
+ *  tool, and register it on the agent's host when it does. */
+export declare function planStructured(inputs: StructuredPlanInputs, connection: PooledConnection): Promise<StructuredPlan>;
+/** A per-turn schema is allowed only where the backend carries the schema on the turn and does not
+ *  embed it in the prompt (Codex among the built-ins). */
+export declare function assertPerTurnSchemaAllowed(backend: Backend, schema: TSchema | undefined, label: string | undefined): void;
+/** The slice of a SessionHandle the result ladder reads. */
+export type StructuredHandle = StructuredSource;
+/**
+ * The no-repair ladder for one turn: this turn's StructuredOutput capture (already validated by
+ * the tool host) → the backend's native result, validated → a validated JSON block in the final
+ * assistant message → otherwise `structuredError` naming every channel that applied.
+ */
+export declare function resolveTurnStructured(args: {
+    schema: TSchema;
+    handle: StructuredHandle;
+    backend: Backend;
+    captured: unknown;
+}): {
+    structured?: unknown;
+    structuredError?: string;
+};
+//# sourceMappingURL=structured.d.ts.map

package/dist/agent/structured.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structured.d.ts","sourceRoot":"","sources":["../../src/agent/structured.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAEvC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAClE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACzD,OAAO,KAAK,EAAE,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAE/D,OAAO,EAEL,KAAK,wBAAwB,EAC7B,KAAK,gCAAgC,EACtC,MAAM,uBAAuB,CAAC;AAG/B,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,SAAS,CAAC;IACrC,4DAA4D;IAC5D,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,gFAAgF;IAChF,QAAQ,CAAC,UAAU,EAAE,eAAe,EAAE,GAAG,SAAS,CAAC;IACnD,QAAQ,CAAC,IAAI,CAAC,EAAE,wBAAwB,CAAC;IACzC,QAAQ,CAAC,YAAY,CAAC,EAAE,gCAAgC,CAAC;CAC1D;AAED,qGAAqG;AACrG,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,SAAS,CAAC;IACrC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,eAAe,EAAE,GAAG,SAAS,CAAC;IACnD,+EAA+E;IAC/E,QAAQ,CAAC,IAAI,EAAE,MAAM,wBAAwB,CAAC;CAC/C;AAWD,yGAAyG;AACzG,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,eAAe,EAAE,GAAG,SAAS,GAAG,MAAM,CAS5G;AAED;8DAC8D;AAC9D,wBAAsB,cAAc,CAAC,MAAM,EAAE,oBAAoB,EAAE,UAAU,EAAE,gBAAgB,GAAG,OAAO,CAAC,cAAc,CAAC,CAsBxH;AAED;0DAC0D;AAC1D,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAG,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAQzH;AAED,4DAA4D;AAC5D,MAAM,MAAM,gBAAgB,GAAG,gBAAgB,CAAC;AAehD;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE;IAC1C,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,gBAAgB,CAAC;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,OAAO,CAAC;CACnB,GAAG;IAAE,UAAU,CAAC,EAAE,OAAO,CAAC;IAAC,eAAe,CAAC,EAAE,MAAM,CAAA;CAAE,CAcrD"}

package/dist/agent/structured.js

@@ -0,0 +1,90 @@
+import { Convert, Errors } from "typebox/value";
+import { extractValidated, validateValue } from "../structured-output.js";
+import { STRUCTURED_OUTPUT_SERVER_NAME, } from "../structured-tool.js";
+import { agentValidationError } from "./errors.js";
+/** The runner's injection rule: the backend opts in AND the initialized agent advertises HTTP MCP. */
+function shouldInjectStructuredOutputTool(schema, backend, capabilities) {
+    return Boolean(schema && backend.injectStructuredOutputTool && capabilities?.agent.mcpCapabilities?.http === true);
+}
+/** `structured_output`, then `structured_output_2`, `_3`, … — never colliding with a caller's server. */
+export function availableMcpServerName(base, servers) {
+    const used = new Set((servers ?? []).map((server) => server.name));
+    let candidate = base;
+    let suffix = 2;
+    while (used.has(candidate)) {
+        candidate = `${base}_${suffix}`;
+        suffix += 1;
+    }
+    return candidate;
+}
+/** Decide (after initialize, so the capabilities are known) whether this session gets the injected
+ *  tool, and register it on the agent's host when it does. */
+export async function planStructured(inputs, connection) {
+    const { schema, backend, mcpServers } = inputs;
+    if (!shouldInjectStructuredOutputTool(schema, backend, connection.capabilities)) {
+        return { schema, toolActive: false, mcpServers };
+    }
+    const host = inputs.host();
+    const registration = await host.register(schema);
+    return {
+        schema,
+        toolActive: true,
+        mcpServers: [
+            ...(mcpServers ?? []),
+            {
+                type: "http",
+                name: availableMcpServerName(STRUCTURED_OUTPUT_SERVER_NAME, mcpServers),
+                url: registration.url,
+                headers: [],
+            },
+        ],
+        host,
+        registration,
+    };
+}
+/** A per-turn schema is allowed only where the backend carries the schema on the turn and does not
+ *  embed it in the prompt (Codex among the built-ins). */
+export function assertPerTurnSchemaAllowed(backend, schema, label) {
+    if (schema === undefined)
+        return;
+    if (backend.promptMeta(schema) !== undefined && backend.embedSchemaInPrompt !== true)
+        return;
+    throw agentValidationError(`per-turn schema is not supported on backend "${backend.id}" (its schema is bound at session open); ` +
+        "pass `schema` to the AcpAgent constructor instead", label);
+}
+function describeErrors(schema, value) {
+    let converted;
+    try {
+        converted = Convert(schema, value);
+    }
+    catch {
+        converted = value;
+    }
+    return Errors(schema, converted)
+        .slice(0, 3)
+        .map((error) => `${error.instancePath || "/"} ${error.message}`)
+        .join("; ");
+}
+/**
+ * The no-repair ladder for one turn: this turn's StructuredOutput capture (already validated by
+ * the tool host) → the backend's native result, validated → a validated JSON block in the final
+ * assistant message → otherwise `structuredError` naming every channel that applied.
+ */
+export function resolveTurnStructured(args) {
+    const { schema, handle, backend, captured } = args;
+    if (captured !== undefined)
+        return { structured: captured };
+    const reasons = ["no StructuredOutput capture"];
+    const native = backend.nativeStructured?.(handle);
+    if (native !== undefined && native !== null) {
+        const validated = validateValue(native, schema);
+        if (validated !== undefined)
+            return { structured: validated };
+        reasons.push(`native result rejected: ${describeErrors(schema, native)}`);
+    }
+    const extracted = extractValidated(handle.finalMessageText(), schema);
+    if (extracted !== undefined)
+        return { structured: extracted };
+    reasons.push("no JSON object in the final message");
+    return { structuredError: reasons.join("; ") };
+}

package/dist/agent/turn.d.ts

@@ -0,0 +1,65 @@
+import type { PromptResponse } from "@agentclientprotocol/sdk";
+import type { AgentHistoryEntry, AgentUsage } from "@automatalabs/shared-types";
+import type { TSchema } from "typebox";
+import type { Backend } from "../backend.js";
+import type { AcpElicitationEvent, AcpPermissionEvent } from "../events.js";
+import type { UsageBaseline } from "../usage.js";
+import type { AgentEventBus } from "./events.js";
+import { type StructuredHandle } from "./structured.js";
+import type { AcpAgentRawRecord, AcpAgentToolCall, AcpAgentTurn, AcpAgentTurnUsage, AcpAgentUpdateRecord } from "./types.js";
+/** The slice of a SessionHandle the collector and builder read (duck-typed for unit tests). */
+export interface TurnHandle extends StructuredHandle {
+    readonly history: AgentHistoryEntry[];
+    readonly usage: {
+        baseline(): UsageBaseline;
+    };
+    foldedTurnText(): string;
+}
+export declare class TurnCollector {
+    #private;
+    readonly historyStart: number;
+    readonly gaugeBefore: UsageBaseline;
+    readonly updates: AcpAgentUpdateRecord[];
+    readonly raw: AcpAgentRawRecord[];
+    readonly permissions: AcpPermissionEvent[];
+    readonly elicitations: AcpElicitationEvent[];
+    /** Registers the tap SYNCHRONOUSLY — construct before the wire call so nothing is missed.
+     *  `retainHistory: false` (the session's `retainSessionLog: false`) means the handle CLEARS its
+     *  accumulator at `beginTurn()`, so this turn's slice starts at 0, not at the previous length. */
+    constructor(bus: Pick<AgentEventBus, "tap">, handle: TurnHandle, options?: {
+        retainHistory?: boolean;
+    });
+    /** The folded tool calls in first-seen order (copies). */
+    get toolCalls(): AcpAgentToolCall[];
+    stop(): void;
+}
+/**
+ * THIS turn's usage. `response.usage` is PER-TURN on every installed adapter (Claude, Codex and pi
+ * all report the turn — `PROMPT_USAGE_SCOPES`), so it maps straight to `AgentUsage`; `cost` is the
+ * clamped delta of the cumulative `usage_update` cost gauge across the turn (the one channel that
+ * IS cumulative), and a response without `usage` falls back to the context-token gauge delta —
+ * exactly `UsageAccumulator.delta()`'s two rules. Never a before/after subtraction of accumulator
+ * snapshots (the accumulator REPLACES its prompt usage per turn, so that arithmetic would be garbage).
+ */
+export declare function turnUsageOf(response: PromptResponse, gaugeBefore: UsageBaseline, gaugeAfter: UsageBaseline): {
+    turn: AgentUsage;
+    response?: AcpAgentTurnUsage["response"];
+};
+/** Fold one turn into the agent's running session sum; `cost` is the latest cumulative gauge. */
+export declare function addUsage(prev: AgentUsage, turn: AgentUsage, gaugeAfter: UsageBaseline): AgentUsage;
+export interface BuildTurnArgs {
+    readonly response: PromptResponse;
+    readonly collector: TurnCollector;
+    readonly handle: TurnHandle;
+    readonly backend: Backend;
+    /** The schema active for THIS turn (per-turn override or the session schema), if any. */
+    readonly schema: TSchema | undefined;
+    /** The injected StructuredOutput capture taken for this turn, if any (`takeCaptured()`). */
+    readonly captured: unknown;
+    /** The agent's running session sum BEFORE this turn. */
+    readonly sessionBefore: AgentUsage;
+}
+/** Assemble the turn: verbatim response, folded text, the turn's history slice (copies), usage
+ *  per the per-turn model above (with the session sum AFTER this turn), and the structured result. */
+export declare function buildTurn(args: BuildTurnArgs): AcpAgentTurn;
+//# sourceMappingURL=turn.d.ts.map

package/dist/agent/turn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn.d.ts","sourceRoot":"","sources":["../../src/agent/turn.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,cAAc,EAA+D,MAAM,0BAA0B,CAAC;AAC5H,OAAO,KAAK,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAChF,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,KAAK,EAAE,mBAAmB,EAAE,kBAAkB,EAAoB,MAAM,cAAc,CAAC;AAC9F,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAyB,KAAK,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAC/E,OAAO,KAAK,EACV,iBAAiB,EACjB,gBAAgB,EAChB,YAAY,EACZ,iBAAiB,EACjB,oBAAoB,EACrB,MAAM,YAAY,CAAC;AAEpB,+FAA+F;AAC/F,MAAM,WAAW,UAAW,SAAQ,gBAAgB;IAClD,QAAQ,CAAC,OAAO,EAAE,iBAAiB,EAAE,CAAC;IACtC,QAAQ,CAAC,KAAK,EAAE;QAAE,QAAQ,IAAI,aAAa,CAAA;KAAE,CAAC;IAC9C,cAAc,IAAI,MAAM,CAAC;CAC1B;AAqBD,qBAAa,aAAa;;IACxB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,WAAW,EAAE,aAAa,CAAC;IACpC,QAAQ,CAAC,OAAO,EAAE,oBAAoB,EAAE,CAAM;IAC9C,QAAQ,CAAC,GAAG,EAAE,iBAAiB,EAAE,CAAM;IACvC,QAAQ,CAAC,WAAW,EAAE,kBAAkB,EAAE,CAAM;IAChD,QAAQ,CAAC,YAAY,EAAE,mBAAmB,EAAE,CAAM;IAKlD;;sGAEkG;gBACtF,GAAG,EAAE,IAAI,CAAC,aAAa,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,GAAE;QAAE,aAAa,CAAC,EAAE,OAAO,CAAA;KAAO;IA6B1G,0DAA0D;IAC1D,IAAI,SAAS,IAAI,gBAAgB,EAAE,CAElC;IAED,IAAI,IAAI,IAAI;CAyCb;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CACzB,QAAQ,EAAE,cAAc,EACxB,WAAW,EAAE,aAAa,EAC1B,UAAU,EAAE,aAAa,GACxB;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,EAAE,iBAAiB,CAAC,UAAU,CAAC,CAAA;CAAE,CA0BhE;AAED,iGAAiG;AACjG,wBAAgB,QAAQ,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,EAAE,UAAU,EAAE,aAAa,GAAG,UAAU,CASlG;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAClC,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,yFAAyF;IACzF,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,SAAS,CAAC;IACrC,4FAA4F;IAC5F,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,wDAAwD;IACxD,QAAQ,CAAC,aAAa,EAAE,UAAU,CAAC;CACpC;AAED;sGACsG;AACtG,wBAAgB,SAAS,CAAC,IAAI,EAAE,aAAa,GAAG,YAAY,CAyB3D"}

package/dist/agent/turn.js

@@ -0,0 +1,187 @@
+import { resolveTurnStructured } from "./structured.js";
+function record(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+export class TurnCollector {
+    historyStart;
+    gaugeBefore;
+    updates = [];
+    raw = [];
+    permissions = [];
+    elicitations = [];
+    #toolCalls = new Map();
+    #active = true;
+    #untap;
+    /** Registers the tap SYNCHRONOUSLY — construct before the wire call so nothing is missed.
+     *  `retainHistory: false` (the session's `retainSessionLog: false`) means the handle CLEARS its
+     *  accumulator at `beginTurn()`, so this turn's slice starts at 0, not at the previous length. */
+    constructor(bus, handle, options = {}) {
+        this.historyStart = options.retainHistory === false ? 0 : handle.history.length;
+        this.gaugeBefore = handle.usage.baseline();
+        this.#untap = bus.tap((name, event) => {
+            if (!this.#active)
+                return;
+            switch (name) {
+                case "session_update": {
+                    const update = structuredClone(event.update);
+                    this.updates.push({ update, receivedAt: Date.now() });
+                    this.#foldToolCall(update);
+                    return;
+                }
+                case "raw_message": {
+                    const { method, message } = event;
+                    this.raw.push({ method, message: structuredClone(message), receivedAt: Date.now() });
+                    return;
+                }
+                case "permission_request":
+                    this.permissions.push({ ...event });
+                    return;
+                case "elicitation_request":
+                    this.elicitations.push({ ...event });
+                    return;
+                default:
+                    return;
+            }
+        });
+    }
+    /** The folded tool calls in first-seen order (copies). */
+    get toolCalls() {
+        return [...this.#toolCalls.values()].map((call) => ({ ...call }));
+    }
+    stop() {
+        this.#active = false;
+        this.#untap();
+    }
+    #foldToolCall(update) {
+        if (update.sessionUpdate === "tool_call") {
+            const existing = this.#toolCalls.get(update.toolCallId);
+            const meta = record(update._meta);
+            const entry = existing ?? { toolCallId: update.toolCallId, title: update.title, status: "pending" };
+            entry.title = update.title;
+            if (typeof update.name === "string")
+                entry.name = update.name;
+            if (update.kind !== undefined && update.kind !== null)
+                entry.kind = update.kind;
+            if (update.status !== undefined && update.status !== null)
+                entry.status = update.status;
+            if (update.rawInput !== undefined)
+                entry.rawInput = update.rawInput;
+            if (update.rawOutput !== undefined)
+                entry.rawOutput = update.rawOutput;
+            if (update.content !== undefined && update.content !== null)
+                entry.content = update.content;
+            if (update.locations !== undefined && update.locations !== null)
+                entry.locations = update.locations;
+            if (meta)
+                entry.meta = { ...(entry.meta ?? {}), ...meta };
+            if (!existing)
+                this.#toolCalls.set(update.toolCallId, entry);
+            return;
+        }
+        if (update.sessionUpdate !== "tool_call_update")
+            return;
+        const existing = this.#toolCalls.get(update.toolCallId);
+        const meta = record(update._meta);
+        const entry = existing ?? {
+            toolCallId: update.toolCallId,
+            title: typeof update.title === "string" ? update.title : "",
+            status: "pending",
+        };
+        if (typeof update.title === "string")
+            entry.title = update.title;
+        if (typeof update.name === "string")
+            entry.name = update.name;
+        if (update.kind !== undefined && update.kind !== null)
+            entry.kind = update.kind;
+        if (update.status !== undefined && update.status !== null)
+            entry.status = update.status;
+        if (update.rawInput !== undefined)
+            entry.rawInput = update.rawInput;
+        if (update.rawOutput !== undefined)
+            entry.rawOutput = update.rawOutput;
+        if (update.content !== undefined && update.content !== null)
+            entry.content = update.content;
+        if (update.locations !== undefined && update.locations !== null)
+            entry.locations = update.locations;
+        if (meta)
+            entry.meta = { ...(entry.meta ?? {}), ...meta };
+        if (!existing)
+            this.#toolCalls.set(update.toolCallId, entry);
+    }
+}
+/**
+ * THIS turn's usage. `response.usage` is PER-TURN on every installed adapter (Claude, Codex and pi
+ * all report the turn — `PROMPT_USAGE_SCOPES`), so it maps straight to `AgentUsage`; `cost` is the
+ * clamped delta of the cumulative `usage_update` cost gauge across the turn (the one channel that
+ * IS cumulative), and a response without `usage` falls back to the context-token gauge delta —
+ * exactly `UsageAccumulator.delta()`'s two rules. Never a before/after subtraction of accumulator
+ * snapshots (the accumulator REPLACES its prompt usage per turn, so that arithmetic would be garbage).
+ */
+export function turnUsageOf(response, gaugeBefore, gaugeAfter) {
+    const cost = Math.max(0, gaugeAfter.costAmount - gaugeBefore.costAmount);
+    const u = response.usage ?? undefined;
+    if (u) {
+        return {
+            turn: {
+                input: u.inputTokens ?? 0,
+                output: u.outputTokens ?? 0,
+                cacheRead: u.cachedReadTokens ?? 0,
+                cacheWrite: u.cachedWriteTokens ?? 0,
+                total: u.totalTokens ?? 0,
+                cost,
+            },
+            response: u,
+        };
+    }
+    return {
+        turn: {
+            input: 0,
+            output: 0,
+            cacheRead: 0,
+            cacheWrite: 0,
+            total: Math.max(0, gaugeAfter.contextUsedTokens - gaugeBefore.contextUsedTokens),
+            cost,
+        },
+    };
+}
+/** Fold one turn into the agent's running session sum; `cost` is the latest cumulative gauge. */
+export function addUsage(prev, turn, gaugeAfter) {
+    return {
+        input: prev.input + turn.input,
+        output: prev.output + turn.output,
+        cacheRead: prev.cacheRead + turn.cacheRead,
+        cacheWrite: prev.cacheWrite + turn.cacheWrite,
+        total: prev.total + turn.total,
+        cost: gaugeAfter.costAmount,
+    };
+}
+/** Assemble the turn: verbatim response, folded text, the turn's history slice (copies), usage
+ *  per the per-turn model above (with the session sum AFTER this turn), and the structured result. */
+export function buildTurn(args) {
+    const { response, collector, handle, backend, schema, captured, sessionBefore } = args;
+    const gaugeAfter = handle.usage.baseline();
+    const usage = turnUsageOf(response, collector.gaugeBefore, gaugeAfter);
+    const historyStart = Math.min(collector.historyStart, handle.history.length);
+    const history = handle.history.slice(historyStart).map((entry) => ({ ...entry }));
+    const structured = schema ? resolveTurnStructured({ schema, handle, backend, captured }) : {};
+    return {
+        response,
+        stopReason: response.stopReason,
+        text: handle.foldedTurnText(),
+        updates: collector.updates,
+        raw: collector.raw,
+        toolCalls: collector.toolCalls,
+        permissions: collector.permissions,
+        elicitations: collector.elicitations,
+        usage: {
+            turn: usage.turn,
+            session: addUsage(sessionBefore, usage.turn, gaugeAfter),
+            ...(usage.response !== undefined ? { response: usage.response } : {}),
+        },
+        ...(structured.structured !== undefined ? { structured: structured.structured } : {}),
+        ...(structured.structuredError !== undefined ? { structuredError: structured.structuredError } : {}),
+        history,
+    };
+}