@theoremjs/agents 0.3.0 → 0.3.1

package/esm/src/kernel/tools/operation.js

@@ -0,0 +1,100 @@
+import { z } from 'zod';
+import { publicError, TheoremError } from '../../guardrails/error.js';
+import { errorKindSchema, guardrailHit, provenance } from '../../guardrails/event-schemas.js';
+import { jsonObjectSchema, jsonValueSchema } from '../json.js';
+import { interactionPartSchema, TURN_EVENT_SCHEMAS, turnHistoryMessageSchema, } from '../turn-events.js';
+export const savedToolInvocationSchema = z.strictObject({
+    accepted: jsonObjectSchema,
+    preparedInput: jsonValueSchema,
+});
+export function operationUnavailable() {
+    const error = new TheoremError('unavailable', '');
+    error.message = publicError(error);
+    return error;
+}
+export async function toolInvocationHash(value) {
+    const ordered = (item) => {
+        if (Array.isArray(item))
+            return item.map(ordered);
+        if (item && typeof item === 'object') {
+            return Object.fromEntries(Object.entries(item)
+                .filter(([, entry]) => entry !== undefined)
+                .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+                .map(([key, entry]) => [key, ordered(entry)]));
+        }
+        return item;
+    };
+    const data = jsonValueSchema.parse(ordered(operationWireValue(value)));
+    const hash = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(JSON.stringify(data)));
+    return Array.from(new Uint8Array(hash), (byte) => byte.toString(16).padStart(2, '0')).join('');
+}
+const terminalSchema = TURN_EVENT_SCHEMAS.tool.transform((event, ctx) => {
+    if (event.tool.phase === 'complete' || event.tool.phase === 'error') {
+        return { ...event, tool: event.tool };
+    }
+    ctx.addIssue({ code: 'custom' });
+    return z.NEVER;
+});
+export const toolOperationOutcomeSchema = z.strictObject({
+    event: terminalSchema,
+    effects: z.enum(['not_started', 'completed', 'unknown']),
+    replay: z.strictObject({
+        modelResult: z
+            .strictObject({
+            finding: z.string(),
+            data: jsonValueSchema.optional(),
+            parts: z.array(interactionPartSchema).optional(),
+            modelText: z.string().optional(),
+            provenance: provenance.optional(),
+            suspicious: z.array(guardrailHit).optional(),
+        })
+            .optional(),
+        outputRaw: jsonValueSchema.optional(),
+        failure: z
+            .strictObject({
+            code: z.string(),
+            kind: errorKindSchema,
+            message: z.string(),
+            error: z.string().optional(),
+            details: jsonValueSchema.optional(),
+        })
+            .optional(),
+        awaiting: z.boolean().optional(),
+        denied: z.literal(true).optional(),
+        callNotStarted: z.boolean().optional(),
+        aborted: z.union([z.boolean(), z.strictObject({ reason: z.string().optional() })]).optional(),
+        pendingInject: z
+            .array(z.strictObject({ id: z.string().optional(), messages: z.array(turnHistoryMessageSchema) }))
+            .optional(),
+    }),
+});
+export function operationWireValue(value) {
+    const ancestors = new Set();
+    const normalize = (item) => {
+        if (!item || typeof item !== 'object')
+            return item;
+        if (ancestors.has(item))
+            throw operationUnavailable();
+        const prototype = Object.getPrototypeOf(item);
+        if (!Array.isArray(item) && prototype !== Object.prototype && prototype !== null) {
+            throw operationUnavailable();
+        }
+        if (Object.hasOwn(item, '__proto__'))
+            throw operationUnavailable();
+        ancestors.add(item);
+        try {
+            if (Array.isArray(item))
+                return item.map(normalize);
+            const entries = Object.entries(Object.getOwnPropertyDescriptors(item));
+            if (entries.some(([, descriptor]) => descriptor.get || descriptor.set))
+                throw operationUnavailable();
+            return Object.fromEntries(entries
+                .filter(([, descriptor]) => descriptor.enumerable && descriptor.value !== undefined)
+                .map(([key, descriptor]) => [key, normalize(descriptor.value)]));
+        }
+        finally {
+            ancestors.delete(item);
+        }
+    };
+    return jsonValueSchema.parse(normalize(value));
+}

package/esm/src/kernel/tools/page-answer.d.ts

@@ -0,0 +1,8 @@
+import type { ToolHandler } from './types.js';
+/**
+ * The handler of a function tool the page answers (`answeredBy: 'page'`): it returns what the
+ * page sent for the call (`ctx.page.output`), which the tool's `output` schema then checks. A
+ * call the page never answered fails to the model. A call run with no answer at all never
+ * reaches here: it is held at a `page` gate.
+ */
+export declare function pageAnswerHandler(name: string): ToolHandler<unknown, unknown>;

package/esm/src/kernel/tools/page-answer.js

@@ -0,0 +1,19 @@
+import { labelText } from '../../guardrails/labels.js';
+import { uncheckedOutput } from './unchecked-output.js';
+/**
+ * The handler of a function tool the page answers (`answeredBy: 'page'`): it returns what the
+ * page sent for the call (`ctx.page.output`), which the tool's `output` schema then checks. A
+ * call the page never answered fails to the model. A call run with no answer at all never
+ * reaches here: it is held at a `page` gate.
+ */
+export function pageAnswerHandler(name) {
+    return (_input, ctx) => {
+        const { page } = ctx;
+        if (page && 'output' in page)
+            return uncheckedOutput(page.output);
+        const { labels } = ctx.profile;
+        if (page?.timedOut)
+            throw new Error(labelText('tool.page_timed_out', {}, labels));
+        throw new Error(labelText('tool.page_no_answer', { tool: name }, labels));
+    };
+}

package/esm/src/kernel/tools/permission.d.ts

@@ -1,6 +1,15 @@
-import type { InvokeToolResume, ToolGate, ToolPermission } from './types.js';
+import type { ToolAccess } from '../schema.js';
+import type { ToolGateBase } from '../turn-events.js';
+import type { InvokeToolResume, ToolGate, ToolLabels, ToolPermission } from './types.js';
 export declare function isResumeContinuation(resume?: InvokeToolResume): boolean;
 export declare function isGateResumeGranted(resume?: InvokeToolResume): boolean;
 export declare function isGateResumeDenied(resume?: InvokeToolResume): boolean;
 export declare function permissionGranted(toolName: string, sessionPermissions?: string[]): boolean;
-export declare function checkPermission(toolName: string, permission: ToolPermission, sessionPermissions?: string[], resume?: InvokeToolResume): ToolGate | null;
+/** What a gate says about the call beyond its kind: the tool's access and its filled request. */
+export type GateDetails = Pick<ToolGateBase, 'access' | 'request'>;
+/** What an approval card says about a call: what it would do, and what the tool can change. */
+export declare function gateDetails(tool: {
+    access: ToolAccess;
+    labels?: ToolLabels;
+}, input: unknown): GateDetails;
+export declare function checkPermission(toolName: string, permission: ToolPermission, sessionPermissions?: string[], resume?: InvokeToolResume, details?: GateDetails): ToolGate | null;

package/esm/src/kernel/tools/permission.js

@@ -1,3 +1,4 @@
+import { fillActivityLabel } from './activity-label.js';
 export function isResumeContinuation(resume) {
     return typeof resume?.granted === 'boolean';
 }
@@ -13,26 +14,25 @@ export function permissionGranted(toolName, sessionPermissions) {
     }
     return sessionPermissions.includes('*') || sessionPermissions.includes(toolName);
 }
-export function checkPermission(toolName, permission, sessionPermissions, resume) {
+/** What an approval card says about a call: what it would do, and what the tool can change. */
+export function gateDetails(tool, input) {
+    const request = fillActivityLabel(tool.labels?.request, { input });
+    return { access: tool.access, ...(request ? { request } : {}) };
+}
+export function checkPermission(toolName, permission, sessionPermissions, resume, details) {
     if (permission === 'auto') {
         return null;
     }
-    if (permission === 'always_confirm') {
-        if (resume?.granted === true) {
-            return null;
-        }
-        return {
-            kind: 'permission',
-            tool: toolName,
-            permission,
-        };
-    }
-    if (permissionGranted(toolName, sessionPermissions)) {
+    const granted = permission === 'always_confirm'
+        ? resume?.granted === true
+        : permissionGranted(toolName, sessionPermissions);
+    if (granted) {
         return null;
     }
     return {
         kind: 'permission',
         tool: toolName,
         permission,
+        ...details,
     };
 }

package/esm/src/kernel/tools/project.d.ts

@@ -1,3 +1,4 @@
+import type { OwnTools } from '../../guardrails/tool-leak.js';
 import type { Profile, ToolId } from '../types.js';
 import type { ToolRegistry } from './registry.js';
 import type { RegisteredTool } from './types.js';
@@ -5,4 +6,6 @@ declare function projectTools(tools: ToolRegistry, profile: Profile): Array<Regi
     name: ToolId;
     missing: true;
 }>;
-export { projectTools };
+/** The names of the profile's tools and of their parameters (`GuardrailContext.ownTools`). */
+declare function ownToolsOf(tools: ToolRegistry, profile: Profile): OwnTools | undefined;
+export { ownToolsOf, projectTools };

package/esm/src/kernel/tools/project.js

@@ -8,7 +8,7 @@ function projectTool(tools, name) {
 }
 function builtInToolIds(profile) {
     const seen = new Set();
-    if (profile.type === 'host' || profile.type === 'decision') {
+    if (profile.type === 'host' || profile.type === 'decision' || profile.type === 'embedding') {
         return [];
     }
     for (const binding of Object.values(profile.models)) {
@@ -22,4 +22,34 @@ function projectTools(tools, profile) {
     const ids = [...profileToolAllow(profile), ...builtInToolIds(profile)];
     return ids.map((name) => projectTool(tools, name));
 }
-export { projectTools };
+/** Adds the name of every property `schema`, a JSON Schema, declares at any depth. */
+function addParams(schema, params) {
+    if (Array.isArray(schema)) {
+        for (const each of schema)
+            addParams(each, params);
+        return;
+    }
+    if (schema === null || typeof schema !== 'object')
+        return;
+    const { properties, ...rest } = schema;
+    if (properties !== null && typeof properties === 'object') {
+        for (const [name, property] of Object.entries(properties)) {
+            params.add(name);
+            addParams(property, params);
+        }
+    }
+    for (const each of Object.values(rest))
+        addParams(each, params);
+}
+/** The names of the profile's tools and of their parameters (`GuardrailContext.ownTools`). */
+function ownToolsOf(tools, profile) {
+    const projected = projectTools(tools, profile);
+    if (projected.length === 0)
+        return undefined;
+    const params = new Set();
+    for (const tool of projected)
+        if ('inputSchema' in tool)
+            addParams(tool.inputSchema, params);
+    return { names: projected.map(({ name }) => name), params: [...params] };
+}
+export { ownToolsOf, projectTools };

package/esm/src/kernel/tools/registry.d.ts

@@ -1,5 +1,7 @@
+import type { Profile, ProfileId } from '../types.js';
 import { type McpSessionCache } from './mcp-sessions.js';
 import type { RegisteredTool, ToolDefinitionInput } from './types.js';
+/** The tools a scope has registered: register, look up, and list them, find a profile for agent tools, and reset. */
 interface ToolRegistry {
     /** Replaces a tool of the same name. */
     register<TIn, TOut>(def: ToolDefinitionInput<TIn, TOut>): RegisteredTool<TIn, TOut>;
@@ -9,12 +11,17 @@ interface ToolRegistry {
     require(name: string): RegisteredTool;
     has(name: string): boolean;
     list(): RegisteredTool[];
+    /** A profile in this scope, for the agent tools that run one. */
+    findProfile(id: ProfileId): Profile | undefined;
     /** Also forgets the MCP sessions. */
     reset(): void;
     /** Sessions for this scope's MCP servers that require one; never shared across scopes. */
     readonly mcpSessions: McpSessionCache;
 }
-/** Registration is not synchronized: register a scope's tools before its turns or invokes run. */
-declare function createToolRegistry(): ToolRegistry;
+/**
+ * Registration is not synchronized: register a scope's tools before its turns or invokes run.
+ * `findProfile` is the scope's profiles, which an agent tool names; without it none registers.
+ */
+declare function createToolRegistry(findProfile?: (id: ProfileId) => Profile | undefined): ToolRegistry;
 export type { ToolRegistry };
 export { createToolRegistry };

package/esm/src/kernel/tools/registry.js

@@ -1,17 +1,22 @@
 import { TheoremError } from '../../guardrails/error.js';
+import { profileInputs } from '../registry/catalog.js';
 import { activityLabelProblem } from './activity-label.js';
+import { agentToolInputFor, agentToolOutput, agentToolProfile, normalizeAgent } from './agent.js';
 import { createMcpSessionCache } from './mcp-sessions.js';
-import { assertFixedEndpointOrigin, jsonSchemaFromZod, validateToolInputSchema, validateToolOutputSchema, } from './schema.js';
+import { pageAnswerHandler } from './page-answer.js';
+import { assertFixedEndpointOrigin, jsonSchemaFromZod, validateToolSchema } from './schema.js';
 function schemasFromZod(def) {
     const inputSchema = jsonSchemaFromZod(def.input, 'input');
-    validateToolInputSchema(inputSchema);
+    validateToolSchema(inputSchema, 'input');
     const outputSchema = jsonSchemaFromZod(def.output, 'output');
-    validateToolOutputSchema(outputSchema);
+    validateToolSchema(outputSchema, 'output');
     const labels = {
         activity: { input: inputSchema },
         activityPast: { input: inputSchema, output: outputSchema },
+        activityFailed: { input: inputSchema },
+        request: { input: inputSchema },
     };
-    for (const field of ['activity', 'activityPast']) {
+    for (const field of ['activity', 'activityPast', 'activityFailed', 'request']) {
         const template = def.labels?.[field];
         const problem = template ? activityLabelProblem(template, labels[field]) : undefined;
         if (problem) {
@@ -26,23 +31,73 @@ function assertAuthService(name, auth) {
         throw new TheoremError('config', `Tool "${name}" signs in with slot "${auth.slot}" but names no service`);
     }
 }
+/** A key in the URL goes in one named query parameter, and nowhere a header or the model's input could also put it. */
+function assertQueryParam(name, auth, inputQueryParams = []) {
+    if (auth?.queryParam === undefined)
+        return;
+    const problem = !auth.queryParam.trim()
+        ? 'is blank'
+        : auth.type !== 'api_key'
+            ? `is set on a '${auth.type}' sign-in; only an API key goes in the URL` // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+            : auth.headerName !== undefined || auth.headerPrefix !== undefined
+                ? 'is set with headerName or headerPrefix; the key goes in one place' // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+                : inputQueryParams.includes(auth.queryParam)
+                    ? `"${auth.queryParam}" is also one of mapping.queryParams` // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+                    : undefined;
+    if (problem) {
+        throw new TheoremError('config', `Tool "${name}" auth.queryParam ${problem}`);
+    }
+}
+/** A limit is a whole number of requests in a window of some time. */
+function assertLimit(name, limit) {
+    if (limit === undefined)
+        return;
+    const whole = Number.isInteger(limit.requests) && limit.requests > 0;
+    if (whole && Number.isFinite(limit.windowMs) && limit.windowMs > 0)
+        return;
+    throw new TheoremError('config', `Tool "${name}" limit needs a whole number of requests above 0 and a window above 0 ms`);
+}
+/** A timeout is some time: a finite number of ms above 0. */
+function assertTimeout(name, timeoutMs) {
+    if (timeoutMs === undefined || (Number.isFinite(timeoutMs) && timeoutMs > 0))
+        return;
+    throw new TheoremError('config', `Tool "${name}" timeoutMs needs a finite number of ms above 0`);
+}
 function normalizeHttp(def) {
     assertFixedEndpointOrigin(def.endpoint);
     assertAuthService(def.name, def.auth);
+    assertQueryParam(def.name, def.auth, def.mapping?.queryParams);
+    assertLimit(def.name, def.limit);
+    assertTimeout(def.name, def.timeoutMs);
     return { ...def, type: 'http', ...schemasFromZod(def) };
 }
 function normalizeMcp(def) {
     assertAuthService(def.name, def.auth);
+    assertQueryParam(def.name, def.auth);
     return { ...def, type: 'mcp', ...schemasFromZod(def) };
 }
 function normalizeFunction(def) {
     assertAuthService(def.name, def.auth);
-    return { ...def, type: 'function', ...schemasFromZod(def) };
+    assertQueryParam(def.name, def.auth);
+    const handler = def.answeredBy === 'page'
+        ? pageAnswerHandler(def.name)
+        : def.handler;
+    if (typeof handler !== 'function') {
+        throw new TheoremError('config', `Tool '${def.name}' needs a handler, or answeredBy: 'page'`);
+    }
+    return { ...def, handler, type: 'function', ...schemasFromZod(def) };
 }
-function normalizeToolDefinition(def) {
+function normalizeToolDefinition(def, findProfile, findTool) {
     if (def.type === 'builtin') {
         return def;
     }
+    if (def.type === 'agent') {
+        const profile = agentToolProfile(def, findProfile, findTool);
+        const inputs = profileInputs(profile);
+        const input = agentToolInputFor({ type: profile.type, ...(inputs ? { inputs } : {}) }, def);
+        const schemas = schemasFromZod({ ...def, input, output: agentToolOutput });
+        return normalizeAgent(def, input, schemas);
+    }
     if (def.type === 'http') {
         return normalizeHttp(def);
     }
@@ -51,13 +106,16 @@ function normalizeToolDefinition(def) {
     }
     return normalizeFunction(def);
 }
-/** Registration is not synchronized: register a scope's tools before its turns or invokes run. */
-function createToolRegistry() {
+/**
+ * Registration is not synchronized: register a scope's tools before its turns or invokes run.
+ * `findProfile` is the scope's profiles, which an agent tool names; without it none registers.
+ */
+function createToolRegistry(findProfile = () => undefined) {
     const tools = new Map();
     const mcpSessions = createMcpSessionCache();
     const get = (name) => tools.get(name);
     const register = (def) => {
-        const normalized = normalizeToolDefinition(def);
+        const normalized = normalizeToolDefinition(def, findProfile, get);
         tools.set(normalized.name, normalized);
         return normalized;
     };
@@ -68,12 +126,13 @@ function createToolRegistry() {
         require(name) {
             const tool = get(name);
             if (!tool) {
-                throw new TheoremError('config', `Tool '${name}' is not registered`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+                throw new TheoremError('config', `Tool '${name}' is not registered`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
             }
             return tool;
         },
         has: (name) => tools.has(name),
         list: () => [...tools.values()],
+        findProfile,
         reset: () => {
             tools.clear();
             mcpSessions.clear();

package/esm/src/kernel/tools/remote.d.ts

@@ -1,25 +1,50 @@
+import type { ApiKeyCredential, BearerCredential } from '../auth/types.js';
 import type { InteractionPart } from '../turn-events.js';
 import type { TurnEvent } from '../types.js';
 import { type ToolCallBase } from './events.js';
+import type { HandlerEvents } from './handler-events.js';
 import { type McpSessionCache } from './mcp-sessions.js';
+import type { ToolOperationClaim } from './operation.js';
 import { type ToolStageSupport } from './stage-run.js';
 import type { HttpToolDef, McpToolDef, ModelToolResult, ToolAuthConfig, ToolBodyOutcome, ToolContext, ToolFailure, ToolGate } from './types.js';
 export type AuthResolveResult = {
     headers: Record<string, string>;
+    /** An API key the URL carries in place of a header: the tool's `auth.queryParam` and the key. */
+    query?: CredentialQuery;
     /** The response is stripped of this before anyone reads it. */
     secret?: string;
     /** RFC 8707 resource an OAuth token was issued for; it goes nowhere else. */
     audience?: string;
     unauthenticated?: boolean;
     modelMessage?: string;
+    /** Why the call fails, under `onUnauthenticated: 'fail'`. */
+    failureMessage?: string;
     gate?: ToolGate;
 };
+/** A credential that goes in a query parameter of the URL a call is sent to. */
+export type CredentialQuery = {
+    name: string;
+    value: string;
+};
+/** `url` with the credential set in its query parameter; `url` itself is left as it was. */
+export declare function withCredentialQuery(url: URL, query: CredentialQuery | undefined): URL;
+/**
+ * Where a token or API key goes on a tool's requests: the query parameter the tool names, or a
+ * header, `Authorization: Bearer …` for a token and `Authorization: …` for a key unless the tool
+ * or the key names another.
+ */
+export declare function credentialPlacement(authConfig: Pick<ToolAuthConfig, 'headerName' | 'headerPrefix' | 'queryParam'>, credential: BearerCredential | ApiKeyCredential): {
+    headers: Record<string, string>;
+    query?: CredentialQuery;
+};
+/** Finds the auth headers for a call from the host's credential for the tool's slot, refreshing an OAuth token when needed; with no usable credential it returns a gate or a message for the model, per the tool's `onUnauthenticated`. */
 export declare function resolveToolAuth(toolName: string, authConfig: ToolAuthConfig | undefined, ctx: ToolContext, base: ToolCallBase): AsyncGenerator<TurnEvent, AuthResolveResult>;
 export type HttpToolMapping = NonNullable<HttpToolDef['mapping']>;
 export type HttpToolTarget = {
     url: string;
     body?: string;
 };
+/** The URL and, for anything but GET, the JSON body of an HTTP tool call: path parameters fill the endpoint, query parameters go on the URL, and the rest of the input (or `bodyParam`) is the body; throws when a path parameter is missing. */
 export declare function buildHttpToolTarget(endpoint: string, method: HttpToolDef['method'], input: Record<string, unknown>, mapping?: HttpToolMapping): HttpToolTarget;
 export declare function parseToolOutput<T>(schema: {
     safeParse: (data: unknown) => {
@@ -44,11 +69,13 @@ export declare function parseToolOutput<T>(schema: {
 export declare function modelResultFromOutput(data: unknown): ModelToolResult;
 /** The result with the media a tool returned beside its value, when it returned any. */
 export declare function withMedia(result: ModelToolResult, parts: InteractionPart[] | undefined): ModelToolResult;
+/** `sent`: the service refused a request the call already sent, so the call has started. */
 export declare function outcomeFromUnauth(authRes: {
     unauthenticated?: boolean;
     gate?: import('./types.js').ToolGate;
     modelMessage?: string;
-}): ToolBodyOutcome | undefined;
+    failureMessage?: string;
+}, sent?: boolean): ToolBodyOutcome | undefined;
 /** A 401 or 403 answer to a request that carried a credential. */
 export type CredentialRefusal = {
     status: number;
@@ -62,12 +89,13 @@ export declare function refusalAsksForSignIn(refusal: CredentialRefusal): boolea
  * the person signs in again. A 403 `insufficient_scope` asks for more access: a
  * sign-in can grant scopes the tool declares, and nothing else, so a request
  * outside them fails with `sign_in.out_of_scope` and the trace records what was
- * asked against what is declared. Any other refusal is the call's failure.
+ * asked against what is declared. Any other refusal is the call's failure. `carried` says the
+ * request went with a credential, in a header or in the URL.
  */
 export declare function refusedCredentialOutcome(tool: {
     name: string;
     auth?: ToolAuthConfig;
-}, refusal: CredentialRefusal | undefined, authHeaders: Record<string, string>, ctx: ToolContext, base: ToolCallBase): Generator<TurnEvent, ToolBodyOutcome | undefined>;
+}, refusal: CredentialRefusal | undefined, carried: boolean, ctx: ToolContext, base: ToolCallBase): Generator<TurnEvent, ToolBodyOutcome | undefined>;
 /** The most of a tool's response body the kernel reads; past it the call fails instead of exhausting the host's memory. */
 export declare const MAX_TOOL_RESPONSE_BYTES: number;
 /** Every string in `value` with the credential replaced. */
@@ -76,11 +104,16 @@ export declare function omitSecret(value: unknown, secret: string): unknown;
 export declare function failureWithoutSecret(failure: ToolFailure, secret: string): ToolFailure;
 /** Why an OAuth token issued for `audience` may not go to `url` (RFC 8707), or `undefined` when it may. */
 export declare function audienceMismatch(audience: string | undefined, url: URL): string | undefined;
-/** Order: schema → permission → auth → preTool/host stages → body. */
-export declare function executeHttpTool(tool: HttpToolDef, rawInput: unknown, ctx: ToolContext, base: ToolCallBase, stages?: ToolStageSupport): AsyncGenerator<TurnEvent, ToolBodyOutcome>;
+/**
+ * Order: schema → permission → auth → preTool/host stages → body. `shown` takes the body while it
+ * arrives, as a function tool's drafts.
+ */
+export declare function executeHttpTool(tool: HttpToolDef, rawInput: unknown, ctx: ToolContext, base: ToolCallBase, stages?: ToolStageSupport, beginBody?: (preparedInput: unknown) => Promise<ToolOperationClaim | undefined>, shown?: HandlerEvents): AsyncGenerator<TurnEvent, ToolBodyOutcome>;
 /** Preferred first. */
 export declare const MCP_PROTOCOL_VERSIONS: readonly ["2026-07-28", "2025-11-25", "2025-06-18", "2025-03-26"];
+/** An MCP protocol version the client can speak. */
 export type McpProtocolVersion = (typeof MCP_PROTOCOL_VERSIONS)[number];
+/** A JSON-RPC message from an MCP server: a result or an error. */
 export type McpRpcResponse = {
     jsonrpc?: string;
     id?: unknown;
@@ -103,8 +136,9 @@ export type McpRpcResponse = {
 };
 /** Accepts a JSON body or an SSE (`data:`) stream. */
 export declare function parseMcpRpcResponse(text: string): McpRpcResponse;
+/** True when an MCP error says the server does not accept the protocol version sent. */
 export declare function isUnsupportedMcpProtocolError(error: McpRpcResponse['error']): boolean;
 /** Streamable HTTP, spec revision 2026-07-28. Order: schema → permission → auth → preTool/host stages → body. */
 export declare function executeMcpTool(tool: McpToolDef, rawInput: unknown, ctx: ToolContext, base: ToolCallBase, stages?: ToolStageSupport, 
 /** The scope's sessions; without them a session lasts one call. */
-sessions?: McpSessionCache): AsyncGenerator<TurnEvent, ToolBodyOutcome>;
+sessions?: McpSessionCache, beginBody?: (preparedInput: unknown) => Promise<ToolOperationClaim | undefined>): AsyncGenerator<TurnEvent, ToolBodyOutcome>;