@automatalabs/acp-agents 2.0.0 → 3.0.1

package/dist/agent/stream.js

@@ -0,0 +1,93 @@
+const DONE = { value: undefined, done: true };
+export class TurnStream {
+    #buffer = [];
+    #waiters = [];
+    #stop;
+    /** Nothing more will be pushed: the turn settled (either way) or the consumer left. */
+    #closed = false;
+    /** The turn's rejection, thrown to the consumer once the buffer has drained. */
+    #failure;
+    #stopping;
+    /** `stop` aborts the turn and resolves once it settled; called at most once. */
+    constructor(stop) {
+        this.#stop = stop;
+    }
+    /** Buffer an event, or hand it straight to a waiting `next()`. Ignored once closed. */
+    push(event) {
+        if (this.#closed)
+            return;
+        const waiter = this.#waiters.shift();
+        if (waiter)
+            waiter.resolve({ value: event, done: false });
+        else
+            this.#buffer.push(event);
+    }
+    /** The turn resolved; the terminal event is already buffered. */
+    end() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        this.#settleWaiters();
+    }
+    /** The turn rejected: buffered events are still delivered, then `error` is thrown once. */
+    fail(error) {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        this.#failure = { error, thrown: false };
+        this.#settleWaiters();
+    }
+    next() {
+        const buffered = this.#buffer.shift();
+        if (buffered !== undefined)
+            return Promise.resolve({ value: buffered, done: false });
+        if (this.#closed)
+            return this.#terminal();
+        return new Promise((resolve, reject) => {
+            this.#waiters.push({ resolve, reject });
+        });
+    }
+    /** The consumer left early: abort the turn, wait for it to settle, then report `done`. */
+    async return() {
+        await this.#leave();
+        return DONE;
+    }
+    /** Same as `return()`, then rethrow `error` to the caller (async-generator semantics). */
+    async throw(error) {
+        await this.#leave();
+        throw error;
+    }
+    [Symbol.asyncIterator]() {
+        return this;
+    }
+    #terminal() {
+        if (this.#failure && !this.#failure.thrown) {
+            this.#failure.thrown = true;
+            return Promise.reject(this.#failure.error);
+        }
+        return Promise.resolve(DONE);
+    }
+    /** Waiters exist only while the buffer is empty, so they get the terminal outcome directly. */
+    #settleWaiters() {
+        for (const waiter of this.#waiters.splice(0)) {
+            if (this.#failure && !this.#failure.thrown) {
+                this.#failure.thrown = true;
+                waiter.reject(this.#failure.error);
+            }
+            else {
+                waiter.resolve(DONE);
+            }
+        }
+    }
+    #leave() {
+        this.#stopping ??= this.#stop();
+        // Undelivered events are the consumer's to discard; a pending `next()` sees `done`, never a
+        // rejection — an early exit is not an error (generator `return()` semantics).
+        this.#closed = true;
+        this.#failure = undefined;
+        this.#buffer.length = 0;
+        for (const waiter of this.#waiters.splice(0))
+            waiter.resolve(DONE);
+        return this.#stopping;
+    }
+}

package/dist/agent/structured.d.ts

@@ -28,12 +28,16 @@ export declare function planStructured(inputs: StructuredPlanInputs, connection:
 /** 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;
+/** `schemaRetries` (constructor or per turn): an integer ≥ 0, or INVALID_ARGUMENT naming `where`.
+ *  `undefined` is the default budget, 0. */
+export declare function validateSchemaRetries(value: unknown, label: string | undefined, where: string): number;
 /** 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.
+ * The result resolution for ONE turn (no re-prompt here): 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. The same three channels the runner's `resolveStructuredOutput` tries per attempt.
  */
 export declare function resolveTurnStructured(args: {
     schema: TSchema;

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

@@ -1 +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"}
+{"version":3,"file":"structured.d.ts","sourceRoot":"","sources":["../../src/agent/structured.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AACvC,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,EAGL,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;4CAC4C;AAC5C,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAStG;AAcD,4DAA4D;AAC5D,MAAM,MAAM,gBAAgB,GAAG,gBAAgB,CAAC;AAEhD;;;;;GAKG;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

@@ -1,6 +1,5 @@
-import { Convert, Errors } from "typebox/value";
 import { extractValidated, validateValue } from "../structured-output.js";
-import { STRUCTURED_OUTPUT_SERVER_NAME, } from "../structured-tool.js";
+import { STRUCTURED_OUTPUT_SERVER_NAME, describeSchemaErrors, } 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) {
@@ -52,23 +51,34 @@ export function assertPerTurnSchemaAllowed(backend, schema, label) {
     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;
+/** `schemaRetries` (constructor or per turn): an integer ≥ 0, or INVALID_ARGUMENT naming `where`.
+ *  `undefined` is the default budget, 0. */
+export function validateSchemaRetries(value, label, where) {
+    if (value === undefined)
+        return 0;
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 0) {
+        throw agentValidationError(`${where}: schemaRetries must be an integer >= 0 (the number of extra repair turns), got ${describeValue(value)}`, label);
+    }
+    return value;
+}
+/** The offending value for the message. `JSON.stringify` renders NaN and ±Infinity as `null`,
+ *  so numbers go through `String`; so does anything JSON cannot serialize (undefined, a symbol,
+ *  a bigint). */
+function describeValue(value) {
+    if (typeof value === "number")
+        return String(value);
     try {
-        converted = Convert(schema, value);
+        return JSON.stringify(value) ?? String(value);
     }
     catch {
-        converted = value;
+        return String(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.
+ * The result resolution for ONE turn (no re-prompt here): 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. The same three channels the runner's `resolveStructuredOutput` tries per attempt.
  */
 export function resolveTurnStructured(args) {
     const { schema, handle, backend, captured } = args;
@@ -80,7 +90,7 @@ export function resolveTurnStructured(args) {
         const validated = validateValue(native, schema);
         if (validated !== undefined)
             return { structured: validated };
-        reasons.push(`native result rejected: ${describeErrors(schema, native)}`);
+        reasons.push(`native result rejected: ${describeSchemaErrors(schema, native)}`);
     }
     const extracted = extractValidated(handle.finalMessageText(), schema);
     if (extracted !== undefined)

package/dist/agent/tool-host.d.ts

@@ -0,0 +1,34 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { LocalMcpHttpHost } from "../local-mcp-host.js";
+import type { AcpAgentToolDefinition } from "./types.js";
+/** The injected `mcpServers` entry name (`agent_tools_2`, … when a caller's server holds it). */
+export declare const AGENT_TOOLS_SERVER_NAME = "agent_tools";
+/** What the agent hands the host at call time (the session id exists only once the session is
+ *  open, and the host must be listening before `session/new` carries its URL). */
+export interface AgentToolHostContext {
+    readonly sessionId: string | undefined;
+    readonly backendId: string;
+    readonly label?: string;
+    /** Best-effort ACP `tool_call` correlation for the call the agent is making right now. */
+    readonly resolveToolCallId?: (toolName: string) => string | undefined;
+}
+export declare class AgentToolHost extends LocalMcpHttpHost {
+    #private;
+    protected readonly hostName = "agent_tools";
+    constructor(tools: readonly AcpAgentToolDefinition[], context: () => AgentToolHostContext);
+    /** Bind (once) and return the token URL the `mcpServers` entry points at. */
+    listen(): Promise<string>;
+    /** The token URL once `listen()` resolved. */
+    get url(): string | undefined;
+    /** The names served, in definition order. */
+    get toolNames(): readonly string[];
+    /** `execute` calls currently running. */
+    get inFlight(): number;
+    /** Abort every running `execute` with `reason` (turn cancellation, the agent's abort, close). */
+    abortInFlight(reason?: unknown): void;
+    /** Abort what is running, stop listening. Idempotent. */
+    dispose(): Promise<void>;
+    protected mcpServerFor(token: string, _req: IncomingMessage, res: ServerResponse): Server | undefined;
+}
+//# sourceMappingURL=tool-host.d.ts.map

package/dist/agent/tool-host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-host.d.ts","sourceRoot":"","sources":["../../src/agent/tool-host.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AACjE,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAUnE,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAGxD,OAAO,KAAK,EAAuB,sBAAsB,EAAsB,MAAM,YAAY,CAAC;AAElG,iGAAiG;AACjG,eAAO,MAAM,uBAAuB,gBAAgB,CAAC;AAErD;kFACkF;AAClF,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,0FAA0F;IAC1F,QAAQ,CAAC,iBAAiB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;CACvE;AAMD,qBAAa,aAAc,SAAQ,gBAAgB;;IACjD,SAAS,CAAC,QAAQ,CAAC,QAAQ,iBAAiB;gBAShC,KAAK,EAAE,SAAS,sBAAsB,EAAE,EAAE,OAAO,EAAE,MAAM,oBAAoB;IAWzF,6EAA6E;IACvE,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC;IAO/B,8CAA8C;IAC9C,IAAI,GAAG,IAAI,MAAM,GAAG,SAAS,CAE5B;IAED,6CAA6C;IAC7C,IAAI,SAAS,IAAI,SAAS,MAAM,EAAE,CAEjC;IAED,yCAAyC;IACzC,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED,iGAAiG;IACjG,aAAa,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,IAAI;IAIrC,yDAAyD;IACnD,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAM9B,SAAS,CAAC,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,EAAE,GAAG,EAAE,cAAc,GAAG,MAAM,GAAG,SAAS;CAyDtG"}

package/dist/agent/tool-host.js

@@ -0,0 +1,138 @@
+// The per-agent local tool host: one in-process Streamable HTTP MCP server on 127.0.0.1 behind an
+// unguessable token path (the `StructuredOutputToolHost` pattern), serving `tools/list` and
+// `tools/call` for every `AcpAgentToolDefinition` the agent was given. Arguments are validated
+// against the definition's typebox schema (Convert + Check) before `execute` runs; a validation
+// failure or a thrown `execute` comes back as an MCP result with `isError: true` and the message —
+// never a transport or protocol error, so the agent can read it and recover. Every in-flight
+// `execute` gets an AbortSignal the agent wires to its own abort, turn cancellation, and close.
+import { randomBytes } from "node:crypto";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, McpError, } from "@modelcontextprotocol/sdk/types.js";
+import { LocalMcpHttpHost } from "../local-mcp-host.js";
+import { validateValue } from "../structured-output.js";
+import { describeSchemaErrors, structuredToolInputSchema } from "../structured-tool.js";
+/** The injected `mcpServers` entry name (`agent_tools_2`, … when a caller's server holds it). */
+export const AGENT_TOOLS_SERVER_NAME = "agent_tools";
+export class AgentToolHost extends LocalMcpHttpHost {
+    hostName = "agent_tools";
+    #token = randomBytes(16).toString("hex");
+    #tools;
+    #advertised;
+    #context;
+    #inFlight = new Set();
+    #url;
+    #disposed = false;
+    constructor(tools, context) {
+        super();
+        this.#tools = new Map(tools.map((tool) => [tool.name, tool]));
+        this.#advertised = tools.map((tool) => ({
+            name: tool.name,
+            description: tool.description,
+            inputSchema: structuredToolInputSchema(tool.inputSchema),
+        }));
+        this.#context = context;
+    }
+    /** Bind (once) and return the token URL the `mcpServers` entry points at. */
+    async listen() {
+        if (this.#disposed)
+            throw new Error("agent_tools MCP host is disposed");
+        const port = await this.ensureListening();
+        this.#url ??= this.urlFor(this.#token, port);
+        return this.#url;
+    }
+    /** The token URL once `listen()` resolved. */
+    get url() {
+        return this.#url;
+    }
+    /** The names served, in definition order. */
+    get toolNames() {
+        return this.#advertised.map((tool) => tool.name);
+    }
+    /** `execute` calls currently running. */
+    get inFlight() {
+        return this.#inFlight.size;
+    }
+    /** Abort every running `execute` with `reason` (turn cancellation, the agent's abort, close). */
+    abortInFlight(reason) {
+        for (const call of this.#inFlight)
+            call.controller.abort(reason);
+    }
+    /** Abort what is running, stop listening. Idempotent. */
+    async dispose() {
+        this.#disposed = true;
+        this.abortInFlight(new Error("AcpAgent closed while the tool call was running"));
+        await this.closeServer();
+    }
+    mcpServerFor(token, _req, res) {
+        if (this.#disposed || token !== this.#token)
+            return undefined;
+        return this.#createMcpServer(res);
+    }
+    #createMcpServer(res) {
+        const server = new Server({ name: "agentprism-agent-tools", version: "0.1.0" }, { capabilities: { tools: {} } });
+        server.setRequestHandler(ListToolsRequestSchema, () => ({ tools: this.#advertised }));
+        server.setRequestHandler(CallToolRequestSchema, async (request) => {
+            const tool = this.#tools.get(request.params.name);
+            if (!tool) {
+                throw new McpError(ErrorCode.InvalidParams, `Unknown tool: ${request.params.name}`);
+            }
+            return this.#call(tool, request.params.arguments ?? {}, res);
+        });
+        return server;
+    }
+    async #call(tool, args, res) {
+        const input = validateValue(args, tool.inputSchema);
+        if (input === undefined) {
+            return errorResult(`Invalid arguments for tool "${tool.name}": ${describeSchemaErrors(tool.inputSchema, args) || "arguments do not match the input schema"}`);
+        }
+        const context = this.#context();
+        if (context.sessionId === undefined) {
+            return errorResult(`Tool "${tool.name}" was called before the agent's session was open`);
+        }
+        const controller = new AbortController();
+        const call = { controller };
+        this.#inFlight.add(call);
+        // The backend gave up on the request (process death, its own timeout): stop the work.
+        const onResponseClosed = () => {
+            if (!res.writableFinished)
+                controller.abort(new Error("the agent dropped the tool call before it completed"));
+        };
+        res.once("close", onResponseClosed);
+        const ctx = {
+            sessionId: context.sessionId,
+            backendId: context.backendId,
+            ...(context.label !== undefined ? { label: context.label } : {}),
+            ...(() => {
+                const toolCallId = context.resolveToolCallId?.(tool.name);
+                return toolCallId !== undefined ? { toolCallId } : {};
+            })(),
+            signal: controller.signal,
+        };
+        try {
+            const result = await tool.execute(input, ctx);
+            return normalizeResult(tool.name, result);
+        }
+        catch (error) {
+            return errorResult(error instanceof Error ? error.message : String(error));
+        }
+        finally {
+            res.off("close", onResponseClosed);
+            this.#inFlight.delete(call);
+        }
+    }
+}
+function errorResult(text) {
+    return { content: [{ type: "text", text }], isError: true };
+}
+/** Shape `execute`'s return into a `CallToolResult`; anything outside the contract is an
+ *  `isError` result naming the tool (JavaScript callers can return `undefined` by mistake). */
+function normalizeResult(name, result) {
+    if (typeof result === "string")
+        return { content: [{ type: "text", text: result }] };
+    if (Array.isArray(result))
+        return { content: result };
+    if (result !== null && typeof result === "object" && Array.isArray(result.content)) {
+        return { content: result.content, ...(result.isError === true ? { isError: true } : {}) };
+    }
+    return errorResult(`Tool "${name}" returned ${result === null ? "null" : typeof result}; expected a string, an array of content blocks, or { content, isError? }`);
+}

package/dist/agent/tools.d.ts

@@ -0,0 +1,26 @@
+import type { McpServerConfig } from "@automatalabs/shared-types";
+import type { TSchema } from "typebox";
+import type { PooledConnection } from "../acp-client.js";
+import { type AgentToolHost } from "./tool-host.js";
+import type { AcpAgentToolDefinition } from "./types.js";
+/** The tool-name grammar: MCP-safe, 1–64 characters of `[A-Za-z0-9_-]`. */
+export declare const AGENT_TOOL_NAME_PATTERN: RegExp;
+/** Identity helper that infers `Static<typeof inputSchema>` for `execute`'s input. */
+export declare function defineTool<TInput extends TSchema>(tool: AcpAgentToolDefinition<TInput>): AcpAgentToolDefinition<TInput>;
+/** Constructor-time validation (INVALID_ARGUMENT): an array of well-formed definitions with
+ *  MCP-safe, unique names and an object-typed `inputSchema`. `undefined` and `[]` are both "no
+ *  tools". */
+export declare function validateToolDefinitions(tools: unknown, label: string | undefined): AcpAgentToolDefinition[];
+export interface ToolPlanInputs {
+    readonly tools: readonly AcpAgentToolDefinition[];
+    readonly backendId: string;
+    readonly label: string | undefined;
+    /** The servers decided so far (the caller's, plus an injected `structured_output`). */
+    readonly mcpServers: McpServerConfig[] | undefined;
+    /** The agent's lazily created host (one per agent, disposed on close). */
+    readonly host: () => AgentToolHost;
+}
+/** After initialize: append the `agent_tools` entry when the agent advertises HTTP MCP, or refuse
+ *  the open. No tools → the servers pass through untouched and no host is created. */
+export declare function planTools(inputs: ToolPlanInputs, connection: PooledConnection): Promise<McpServerConfig[] | undefined>;
+//# sourceMappingURL=tools.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../src/agent/tools.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAClE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAGzD,OAAO,EAA2B,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC7E,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAEzD,2EAA2E;AAC3E,eAAO,MAAM,uBAAuB,QAA0B,CAAC;AAE/D,sFAAsF;AACtF,wBAAgB,UAAU,CAAC,MAAM,SAAS,OAAO,EAAE,IAAI,EAAE,sBAAsB,CAAC,MAAM,CAAC,GAAG,sBAAsB,CAAC,MAAM,CAAC,CAEvH;AAED;;cAEc;AACd,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,sBAAsB,EAAE,CAiC3G;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,EAAE,SAAS,sBAAsB,EAAE,CAAC;IAClD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,uFAAuF;IACvF,QAAQ,CAAC,UAAU,EAAE,eAAe,EAAE,GAAG,SAAS,CAAC;IACnD,0EAA0E;IAC1E,QAAQ,CAAC,IAAI,EAAE,MAAM,aAAa,CAAC;CACpC;AAED;sFACsF;AACtF,wBAAsB,SAAS,CAAC,MAAM,EAAE,cAAc,EAAE,UAAU,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,EAAE,GAAG,SAAS,CAAC,CAe5H"}

package/dist/agent/tools.js

@@ -0,0 +1,62 @@
+import { agentValidationError } from "./errors.js";
+import { availableMcpServerName } from "./structured.js";
+import { AGENT_TOOLS_SERVER_NAME } from "./tool-host.js";
+/** The tool-name grammar: MCP-safe, 1–64 characters of `[A-Za-z0-9_-]`. */
+export const AGENT_TOOL_NAME_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
+/** Identity helper that infers `Static<typeof inputSchema>` for `execute`'s input. */
+export function defineTool(tool) {
+    return tool;
+}
+/** Constructor-time validation (INVALID_ARGUMENT): an array of well-formed definitions with
+ *  MCP-safe, unique names and an object-typed `inputSchema`. `undefined` and `[]` are both "no
+ *  tools". */
+export function validateToolDefinitions(tools, label) {
+    if (tools === undefined)
+        return [];
+    if (!Array.isArray(tools))
+        throw agentValidationError("AcpAgent `tools` must be an array of tool definitions", label);
+    const seen = new Set();
+    tools.forEach((tool, index) => {
+        const at = `tools[${index}]`;
+        if (tool === null || typeof tool !== "object")
+            throw agentValidationError(`${at} must be a tool definition object`, label);
+        const { name, description, inputSchema, execute } = tool;
+        if (typeof name !== "string" || !AGENT_TOOL_NAME_PATTERN.test(name)) {
+            throw agentValidationError(`${at}.name must match ${AGENT_TOOL_NAME_PATTERN.source} (got ${JSON.stringify(name)})`, label);
+        }
+        if (seen.has(name))
+            throw agentValidationError(`duplicate tool name "${name}" (tool names must be unique)`, label);
+        seen.add(name);
+        if (typeof description !== "string")
+            throw agentValidationError(`tool "${name}" needs a string description`, label);
+        if (inputSchema === null || typeof inputSchema !== "object") {
+            throw agentValidationError(`tool "${name}" needs an inputSchema (a typebox schema object)`, label);
+        }
+        // MCP `tools/call` arguments are an object and `tools/list` advertises `inputSchema` as
+        // `type: "object"`: a schema of any other top-level type could never be satisfied by a call,
+        // so it is refused here rather than advertised.
+        const schemaType = inputSchema.type;
+        if (schemaType !== "object") {
+            throw agentValidationError(`tool "${name}" inputSchema must be an object schema (typebox Type.Object(...), type: "object"); got type ${JSON.stringify(schemaType) ?? "undefined"}`, label);
+        }
+        if (typeof execute !== "function")
+            throw agentValidationError(`tool "${name}" needs an execute function`, label);
+    });
+    return tools;
+}
+/** After initialize: append the `agent_tools` entry when the agent advertises HTTP MCP, or refuse
+ *  the open. No tools → the servers pass through untouched and no host is created. */
+export async function planTools(inputs, connection) {
+    const { tools, mcpServers } = inputs;
+    if (tools.length === 0)
+        return mcpServers;
+    if (connection.capabilities?.agent.mcpCapabilities?.http !== true) {
+        throw agentValidationError(`function tools need HTTP MCP, but backend "${inputs.backendId}" does not advertise mcpCapabilities.http ` +
+            `(${tools.length} tool${tools.length === 1 ? "" : "s"} configured: ${tools.map((tool) => tool.name).join(", ")})`, inputs.label);
+    }
+    const url = await inputs.host().listen();
+    return [
+        ...(mcpServers ?? []),
+        { type: "http", name: availableMcpServerName(AGENT_TOOLS_SERVER_NAME, mcpServers), url, headers: [] },
+    ];
+}

package/dist/agent/turn.d.ts

@@ -6,7 +6,7 @@ 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";
+import type { AcpAgentMessage, 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[];
@@ -31,6 +31,8 @@ export declare class TurnCollector {
     });
     /** The folded tool calls in first-seen order (copies). */
     get toolCalls(): AcpAgentToolCall[];
+    /** This turn's messages so far (copies). */
+    get messages(): AcpAgentMessage[];
     stop(): void;
 }
 /**
@@ -59,7 +61,8 @@ export interface BuildTurnArgs {
     /** 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. */
+/** Assemble the turn: verbatim response, folded text, the messages folded from the turn's update
+ *  records, 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

@@ -1 +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"}
+{"version":3,"file":"turn.d.ts","sourceRoot":"","sources":["../../src/agent/turn.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC/D,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;AAEjD,OAAO,EAAyB,KAAK,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAC/E,OAAO,KAAK,EACV,eAAe,EACf,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;AAED,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;IAMlD;;sGAEkG;gBACtF,GAAG,EAAE,IAAI,CAAC,aAAa,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,GAAE;QAAE,aAAa,CAAC,EAAE,OAAO,CAAA;KAAO;IA8B1G,0DAA0D;IAC1D,IAAI,SAAS,IAAI,gBAAgB,EAAE,CAElC;IAED,4CAA4C;IAC5C,IAAI,QAAQ,IAAI,eAAe,EAAE,CAEhC;IAED,IAAI,IAAI,IAAI;CAIb;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;;+DAE+D;AAC/D,wBAAgB,SAAS,CAAC,IAAI,EAAE,aAAa,GAAG,YAAY,CA0B3D"}

package/dist/agent/turn.js

@@ -1,9 +1,5 @@
+import { MessageFolder } from "./messages.js";
 import { resolveTurnStructured } from "./structured.js";
-function record(value) {
-    return value !== null && typeof value === "object" && !Array.isArray(value)
-        ? value
-        : undefined;
-}
 export class TurnCollector {
     historyStart;
     gaugeBefore;
@@ -11,7 +7,8 @@ export class TurnCollector {
     raw = [];
     permissions = [];
     elicitations = [];
-    #toolCalls = new Map();
+    /** This turn's messages and tool calls — one fold, fed every update record as it is stored. */
+    #messages = new MessageFolder();
     #active = true;
     #untap;
     /** Registers the tap SYNCHRONOUSLY — construct before the wire call so nothing is missed.
@@ -26,8 +23,9 @@ export class TurnCollector {
             switch (name) {
                 case "session_update": {
                     const update = structuredClone(event.update);
-                    this.updates.push({ update, receivedAt: Date.now() });
-                    this.#foldToolCall(update);
+                    const receivedAt = Date.now();
+                    this.updates.push({ update, receivedAt });
+                    this.#messages.apply(update, receivedAt);
                     return;
                 }
                 case "raw_message": {
@@ -48,68 +46,16 @@ export class TurnCollector {
     }
     /** The folded tool calls in first-seen order (copies). */
     get toolCalls() {
-        return [...this.#toolCalls.values()].map((call) => ({ ...call }));
+        return this.#messages.toolCalls;
+    }
+    /** This turn's messages so far (copies). */
+    get messages() {
+        return this.#messages.snapshot();
     }
     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
@@ -157,8 +103,9 @@ export function addUsage(prev, turn, gaugeAfter) {
         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. */
+/** Assemble the turn: verbatim response, folded text, the messages folded from the turn's update
+ *  records, 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();
@@ -173,6 +120,7 @@ export function buildTurn(args) {
         updates: collector.updates,
         raw: collector.raw,
         toolCalls: collector.toolCalls,
+        messages: collector.messages,
         permissions: collector.permissions,
         elicitations: collector.elicitations,
         usage: {