@theoremjs/agents 0.0.0-stage → 0.3.0

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

@@ -0,0 +1,28 @@
+import type { ModelId, ModelProfile, Profile, ProfileToolsSpec, ToolId, TurnRequest } from '../types.js';
+import type { ToolRegistry } from './registry.js';
+import type { PromoteLoadedResult, RegisteredTool, ToolFailure, TurnToolSnapshot, WireFunctionTool } from './types.js';
+export declare function pathMatches(catalogPaths?: string[], turnPath?: string): boolean;
+export declare function applyBuiltinMutualExclusions(tools: ToolRegistry, requested: string[]): string[];
+export declare function profileToolAllow(profile: Profile): readonly ToolId[];
+export declare function profileToolsSpec(profile: Profile): ProfileToolsSpec | undefined;
+export declare function resolveAllowedCustomToolIds(tools: ToolRegistry, profile: Profile, req: TurnRequest): ToolId[];
+export declare function resolveModelBuiltinIds(tools: ToolRegistry, profile: ModelProfile, req: TurnRequest, modelId: ModelId): ToolId[];
+export declare function wireForTool(tools: ToolRegistry, name: string): WireFunctionTool | undefined;
+export declare function buildWire(tools: ToolRegistry, visible: ToolId[]): WireFunctionTool[];
+export declare function promoteTool(tools: ToolRegistry, state: TurnToolSnapshot, id: ToolId): void;
+export declare function promoteBuiltin(tools: ToolRegistry, state: TurnToolSnapshot, id: ToolId): void;
+/** Live declarations are fixed at session setup, so every allowed tool there is effectively T0. */
+export declare function initialVisible(tools: ToolRegistry, profile: Profile, gated: ToolId[]): ToolId[];
+export declare function initialBuiltins(tools: ToolRegistry, profile: Profile, gated: ToolId[]): ToolId[];
+export declare function resolveTurnTools(tools: ToolRegistry, profile: Profile, req: TurnRequest, modelId: ModelId | undefined): TurnToolSnapshot;
+export declare function prepareTurnToolSnapshot(tools: ToolRegistry, profile: Profile, req: TurnRequest, modelId: ModelId | undefined): Promise<TurnToolSnapshot>;
+/** So concurrent host invokes do not share mutable state. */
+export declare function cloneTurnToolSnapshot(state: TurnToolSnapshot): TurnToolSnapshot;
+export declare function expandT1Policy(tools: ToolRegistry, state: TurnToolSnapshot, profile: Profile, req: TurnRequest): Promise<void>;
+export declare function extractLoadedIds(output: unknown): string[] | undefined;
+export declare function promoteLoadedTools(tools: ToolRegistry, state: TurnToolSnapshot, loaded: string[], profile: Profile): PromoteLoadedResult;
+export declare function promotionTarget(tools: ToolRegistry, id: string, profile: Profile): {
+    tool: RegisteredTool;
+} | {
+    failure: ToolFailure;
+};

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

@@ -0,0 +1,259 @@
+import { TheoremError } from '../../guardrails/error.js';
+import { isRecord } from '../util/record.js';
+/** Callable by the host: registered, and not a provider-run builtin. */
+function isExecutable(tools, id) {
+    const tool = tools.get(id);
+    return tool !== undefined && tool.type !== 'builtin';
+}
+export function pathMatches(catalogPaths, turnPath) {
+    if (!catalogPaths || catalogPaths.includes('*')) {
+        return true;
+    }
+    if (!turnPath) {
+        return false;
+    }
+    return catalogPaths.includes(turnPath);
+}
+export function applyBuiltinMutualExclusions(tools, requested) {
+    return requested.filter((id) => {
+        const tool = tools.get(id);
+        if (tool?.type !== 'builtin') {
+            return true;
+        }
+        const conflicts = tool.conflictsWith ?? [];
+        return !conflicts.some((other) => requested.includes(other));
+    });
+}
+export function profileToolAllow(profile) {
+    return 'tools' in profile ? profile.tools.allow : [];
+}
+export function profileToolsSpec(profile) {
+    return profile.type === 'text' || profile.type === 'image' ? profile.tools : undefined;
+}
+export function resolveAllowedCustomToolIds(tools, profile, req) {
+    return profileToolAllow(profile).filter((id) => {
+        const tool = tools.get(id);
+        if (!tool || tool.type === 'builtin') {
+            return false;
+        }
+        return profile.type === 'host' || pathMatches(tool.paths, req.path);
+    });
+}
+export function resolveModelBuiltinIds(tools, profile, req, modelId) {
+    const spec = profile.models[modelId];
+    if (!spec) {
+        return [];
+    }
+    return (spec.builtInTools ?? []).filter((id) => {
+        const tool = tools.get(id);
+        if (tool?.type !== 'builtin') {
+            return false;
+        }
+        return pathMatches(tool.paths, req.path);
+    });
+}
+export function wireForTool(tools, name) {
+    const tool = tools.get(name);
+    if (!tool || tool.type === 'builtin') {
+        return undefined;
+    }
+    return {
+        type: 'function',
+        name: tool.name,
+        description: tool.description,
+        parameters: tool.inputSchema,
+    };
+}
+export function buildWire(tools, visible) {
+    const out = [];
+    for (const id of visible) {
+        const wire = wireForTool(tools, id);
+        if (wire) {
+            out.push(wire);
+        }
+    }
+    return out;
+}
+export function promoteTool(tools, state, id) {
+    if (state.visible.includes(id)) {
+        return;
+    }
+    state.visible.push(id);
+    const wire = wireForTool(tools, id);
+    if (wire && !state.wire.some((w) => w.name === id)) {
+        state.wire.push(wire);
+    }
+}
+export function promoteBuiltin(tools, state, id) {
+    if (state.builtins.includes(id)) {
+        return;
+    }
+    const tool = tools.get(id);
+    if (tool?.type !== 'builtin') {
+        return;
+    }
+    const conflicts = tool.conflictsWith ?? [];
+    state.builtins = state.builtins.filter((existing) => {
+        if (conflicts.includes(existing)) {
+            return false;
+        }
+        const existingTool = tools.get(existing);
+        return !(existingTool?.type === 'builtin' && existingTool.conflictsWith?.includes(id));
+    });
+    state.builtins.push(id);
+}
+/** Live declarations are fixed at session setup, so every allowed tool there is effectively T0. */
+export function initialVisible(tools, profile, gated) {
+    if (profile.type === 'live' || profile.type === 'host') {
+        return [...gated];
+    }
+    return gated.filter((id) => tools.get(id)?.loadTier === 'T0');
+}
+export function initialBuiltins(tools, profile, gated) {
+    return applyBuiltinMutualExclusions(tools, gated.filter((id) => {
+        const tool = tools.get(id);
+        return tool?.type === 'builtin' && (profile.type === 'live' || tool.loadTier === 'T0');
+    }));
+}
+export function resolveTurnTools(tools, profile, req, modelId) {
+    const customAllowed = resolveAllowedCustomToolIds(tools, profile, req);
+    const modelBuiltins = profile.type === 'host' || profile.type === 'decision' || modelId === undefined
+        ? []
+        : resolveModelBuiltinIds(tools, profile, req, modelId);
+    const gated = [...customAllowed, ...modelBuiltins];
+    const builtins = initialBuiltins(tools, profile, gated);
+    const visible = initialVisible(tools, profile, gated);
+    const executable = visible.filter((id) => isExecutable(tools, id));
+    return {
+        builtins,
+        gated,
+        visible,
+        executable,
+        path: req.path,
+        sessionPermissions: req.sessionPermissions,
+        wire: buildWire(tools, visible),
+    };
+}
+export async function prepareTurnToolSnapshot(tools, profile, req, modelId) {
+    const snapshot = resolveTurnTools(tools, profile, req, modelId);
+    await expandT1Policy(tools, snapshot, profile, req);
+    return snapshot;
+}
+/** So concurrent host invokes do not share mutable state. */
+export function cloneTurnToolSnapshot(state) {
+    return {
+        builtins: [...state.builtins],
+        gated: [...state.gated],
+        visible: [...state.visible],
+        executable: [...state.executable],
+        path: state.path,
+        sessionPermissions: state.sessionPermissions ? [...state.sessionPermissions] : undefined,
+        wire: state.wire.map((w) => ({ ...w, parameters: structuredClone(w.parameters) })),
+    };
+}
+export async function expandT1Policy(tools, state, profile, req) {
+    const t1Policy = profileToolsSpec(profile)?.t1Policy;
+    if (!t1Policy) {
+        return;
+    }
+    let selected;
+    try {
+        selected = await t1Policy({
+            profile,
+            input: req.input,
+            path: req.path,
+            sessionPermissions: req.sessionPermissions,
+            gated: state.gated,
+            host: req.host,
+        });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new TheoremError('config', `Profile '${profile.id}' tools.t1Policy rejected: ${msg}`, {
+            cause: err,
+        });
+    }
+    if (!Array.isArray(selected)) {
+        throw new TheoremError('config', `Profile '${profile.id}' tools.t1Policy must return ToolId[]`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+    for (const id of selected) {
+        if (!state.gated.includes(id)) {
+            continue;
+        }
+        const tool = tools.get(id);
+        if (!tool || tool.loadTier === 'T0') {
+            continue;
+        }
+        if (tool.type === 'builtin') {
+            promoteBuiltin(tools, state, id);
+        }
+        else {
+            promoteTool(tools, state, id);
+        }
+    }
+    state.executable = state.visible.filter((id) => isExecutable(tools, id));
+}
+const LOADED_ID_BLOCKLIST = new Set(['__proto__', 'constructor', 'prototype']);
+export function extractLoadedIds(output) {
+    if (!isRecord(output)) {
+        return undefined;
+    }
+    const { loaded } = output;
+    if (!Array.isArray(loaded) || !loaded.every((id) => typeof id === 'string')) {
+        return undefined;
+    }
+    return loaded;
+}
+export function promoteLoadedTools(tools, state, loaded, profile) {
+    if (profile.type === 'live' || profile.type === 'host') {
+        return { promoted: [] };
+    }
+    const toPromote = [];
+    for (const id of loaded) {
+        if (typeof id !== 'string' || LOADED_ID_BLOCKLIST.has(id)) {
+            return {
+                promoted: [],
+                failure: {
+                    code: 'invalid_output',
+                    kind: 'bad_response',
+                    message: 'tools.t2Loader loaded ids must be plain strings', // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+                },
+            };
+        }
+        const target = promotionTarget(tools, id, profile);
+        if ('failure' in target) {
+            return { promoted: [], failure: target.failure };
+        }
+        const { tool } = target;
+        if (!pathMatches(tool.paths, state.path) || !state.gated.includes(id)) {
+            continue;
+        }
+        toPromote.push(id);
+    }
+    const promoted = [];
+    for (const id of toPromote) {
+        promoteTool(tools, state, id);
+        promoted.push(id);
+    }
+    state.executable = state.visible.filter((id) => isExecutable(tools, id));
+    return { promoted };
+}
+function promotionRefused(message) {
+    return { failure: { code: 'invalid_output', kind: 'bad_response', message } };
+}
+export function promotionTarget(tools, id, profile) {
+    if (!profileToolAllow(profile).includes(id)) {
+        return promotionRefused(`tools.t2Loader attempted to promote tool '${id}' outside profile allow`);
+    }
+    const tool = tools.get(id);
+    if (!tool) {
+        return promotionRefused(`tools.t2Loader attempted to promote unknown tool '${id}'`);
+    }
+    if (tool.type === 'builtin') {
+        return promotionRefused(`tools.t2Loader attempted to promote builtin '${id}' — only custom tools may be promoted`);
+    }
+    if (tool.loadTier !== 'T2') {
+        return promotionRefused(`tools.t2Loader attempted to promote tool '${id}' with loadTier '${tool.loadTier}' — only T2 tools may be promoted`);
+    }
+    return { tool };
+}

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

@@ -0,0 +1,10 @@
+import { type ZodType } from 'zod';
+export type JsonSchema = Record<string, unknown>;
+declare function validateToolInputSchema(schema: JsonSchema, mode?: 'gemini' | 'structural'): void;
+declare function validateToolOutputSchema(schema: JsonSchema, mode?: 'gemini' | 'structural'): void;
+declare function jsonSchemaFromZod(schema: ZodType, io?: 'input' | 'output'): JsonSchema;
+export { jsonSchemaFromZod, validateToolInputSchema, validateToolOutputSchema };
+/** Strips prototype-pollution keys before validation. */
+export declare function plainToolInput(input: unknown): unknown;
+/** A placeholder in the scheme or authority would let tool input choose where the credential goes. */
+export declare function assertFixedEndpointOrigin(endpoint: string): void;

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

@@ -0,0 +1,174 @@
+import { z } from 'zod';
+import { TheoremError } from '../../guardrails/error.js';
+const GEMINI_SUPPORTED_SCHEMA_KEYS = [
+    'type',
+    'format',
+    'title',
+    'description',
+    'nullable',
+    'enum',
+    'default',
+    'example',
+    'items',
+    'minItems',
+    'maxItems',
+    'properties',
+    'required',
+    'propertyOrdering',
+    'minProperties',
+    'maxProperties',
+    'minimum',
+    'maximum',
+    'pattern',
+    'minLength',
+    'maxLength',
+    'anyOf',
+    'oneOf',
+];
+function validateGeminiKeys(schema, path, errors) {
+    for (const key of Object.keys(schema)) {
+        if (!GEMINI_SUPPORTED_SCHEMA_KEYS.includes(key)) {
+            errors.push(`${path}: unsupported Gemini schema key '${key}'`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        }
+    }
+}
+function validateSchemaShape(schema, path, mode, errors) {
+    if (!schema || typeof schema !== 'object' || Array.isArray(schema)) {
+        errors.push(`${path}: schema must be an object`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        return false;
+    }
+    const hasType = typeof schema.type === 'string' || Array.isArray(schema.type);
+    const hasCombinator = schema.anyOf !== undefined || schema.oneOf !== undefined;
+    if (!hasType && !hasCombinator) {
+        if (mode === 'structural' && path !== '$') {
+            return true;
+        }
+        errors.push(`${path}: missing type or combinator`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+    if (mode === 'gemini') {
+        validateGeminiKeys(schema, path, errors);
+    }
+    if (schema.type === 'array' && schema.items === undefined) {
+        errors.push(`${path}: array schema must define items`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+    return true;
+}
+function walkSchemaProperties(props, required, path, mode, errors) {
+    const reqList = Array.isArray(required) ? required : [];
+    for (const req of reqList) {
+        if (typeof req === 'string' && !(req in props)) {
+            errors.push(`${path}: required key '${req}' missing from properties`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        }
+    }
+    for (const [key, child] of Object.entries(props)) {
+        if (child && typeof child === 'object') {
+            walkSchema(child, `${path}.properties.${key}`, mode, errors);
+        }
+    }
+}
+function walkSchema(schema, path, mode, errors) {
+    if (!validateSchemaShape(schema, path, mode, errors))
+        return;
+    const props = schema.properties;
+    if (props && typeof props === 'object' && !Array.isArray(props)) {
+        walkSchemaProperties(props, schema.required, path, mode, errors);
+    }
+    if (schema.items && typeof schema.items === 'object' && !Array.isArray(schema.items)) {
+        walkSchema(schema.items, `${path}.items`, mode, errors);
+    }
+    for (const combinator of ['anyOf', 'oneOf']) {
+        const branch = schema[combinator];
+        if (Array.isArray(branch)) {
+            branch.forEach((entry, index) => {
+                if (entry && typeof entry === 'object') {
+                    walkSchema(entry, `${path}.${combinator}[${index}]`, mode, errors);
+                }
+            });
+        }
+    }
+}
+function validateToolWireSchema(schema, mode = 'gemini', label = 'input') {
+    const errors = [];
+    walkSchema(schema, '$', mode, errors);
+    if (errors.length > 0) {
+        throw new TheoremError('config', `Invalid tool ${label} schema: ${errors.join('; ')}`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+}
+function validateToolInputSchema(schema, mode = 'gemini') {
+    validateToolWireSchema(schema, mode, 'input');
+}
+function validateToolOutputSchema(schema, mode = 'structural') {
+    validateToolWireSchema(schema, mode, 'output');
+}
+function stripProperties(value) {
+    const props = {};
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+        for (const [propKey, propValue] of Object.entries(value)) {
+            if (propValue && typeof propValue === 'object') {
+                props[propKey] = stripUnsupportedGeminiKeys(propValue);
+            }
+        }
+    }
+    return props;
+}
+function stripBranches(branches) {
+    return branches.map((entry) => entry && typeof entry === 'object' ? stripUnsupportedGeminiKeys(entry) : entry);
+}
+function stripUnsupportedGeminiKeys(schema) {
+    const out = {};
+    for (const [key, value] of Object.entries(schema)) {
+        if (!GEMINI_SUPPORTED_SCHEMA_KEYS.includes(key)) {
+            continue;
+        }
+        if (key === 'properties') {
+            out.properties = stripProperties(value);
+            continue;
+        }
+        if (key === 'items' && value && typeof value === 'object' && !Array.isArray(value)) {
+            out.items = stripUnsupportedGeminiKeys(value);
+            continue;
+        }
+        if ((key === 'anyOf' || key === 'oneOf') && Array.isArray(value)) {
+            out[key] = stripBranches(value);
+            continue;
+        }
+        out[key] = value;
+    }
+    return out;
+}
+function jsonSchemaFromZod(schema, io = 'output') {
+    const json = z.toJSONSchema(schema, {
+        target: 'openApi3',
+        io,
+    });
+    delete json.$schema;
+    if (!json.type) {
+        json.type = 'object';
+    }
+    return stripUnsupportedGeminiKeys(json);
+}
+export { jsonSchemaFromZod, validateToolInputSchema, validateToolOutputSchema };
+/** Strips prototype-pollution keys before validation. */
+export function plainToolInput(input) {
+    if (input === null || typeof input !== 'object') {
+        return input;
+    }
+    if (Array.isArray(input)) {
+        return input.map(plainToolInput);
+    }
+    const out = {};
+    for (const key of Object.keys(input)) {
+        if (key === '__proto__' || key === 'constructor' || key === 'prototype') {
+            continue;
+        }
+        out[key] = plainToolInput(input[key]);
+    }
+    return out;
+}
+/** A placeholder in the scheme or authority would let tool input choose where the credential goes. */
+export function assertFixedEndpointOrigin(endpoint) {
+    const origin = /^[a-z][a-z0-9+.-]*:\/\/[^/?#]*/i.exec(endpoint)?.[0];
+    if (!origin || /[{}]/.test(origin)) {
+        throw new TheoremError('config', `Endpoint "${endpoint}" must start with a fixed scheme and host; placeholders belong in the path or query`);
+    }
+}

package/esm/src/kernel/tools/signed-in-fetch.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The signed-in fetch a function tool with `auth` gets as `ctx.signedInFetch`.
+ * The kernel holds the credential; the handler only makes requests that carry it.
+ *
+ * @module
+ */
+import type { RequestChecks } from './events.js';
+import { type CredentialRefusal } from './remote.js';
+import type { SignedInFetch, ToolContext } from './types.js';
+/** Thrown by a signed-in fetch when the service refuses the credential; the kernel settles it. */
+export declare class CredentialRefusedError extends Error {
+    readonly refusal: CredentialRefusal;
+    constructor(refusal: CredentialRefusal);
+}
+export declare function signedInFetch(prepared: {
+    authHeaders: Record<string, string>;
+    audience?: string;
+}, ctx: ToolContext, checks: RequestChecks): SignedInFetch;

package/esm/src/kernel/tools/signed-in-fetch.js

@@ -0,0 +1,45 @@
+/**
+ * The signed-in fetch a function tool with `auth` gets as `ctx.signedInFetch`.
+ * The kernel holds the credential; the handler only makes requests that carry it.
+ *
+ * @module
+ */
+import { fetchGuarded } from '../../guardrails/network.js';
+import { TheoremError } from '../../guardrails/theorem-error.js';
+import { toolNetworkPolicy } from './events.js';
+import { audienceMismatch, credentialRefusal, refusalAsksForSignIn, } from './remote.js';
+/** Thrown by a signed-in fetch when the service refuses the credential; the kernel settles it. */
+export class CredentialRefusedError extends Error {
+    refusal;
+    constructor(refusal) {
+        super(`The service refused the credential (HTTP ${refusal.status}).`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        this.name = 'CredentialRefusedError';
+        this.refusal = refusal;
+    }
+}
+export function signedInFetch(prepared, ctx, checks) {
+    return async (url, request = {}) => {
+        const target = new URL(url);
+        const mismatch = audienceMismatch(prepared.audience, target);
+        if (mismatch)
+            throw new TheoremError('config', mismatch);
+        const response = await fetchGuarded(target.href, {
+            method: request.method ?? 'GET',
+            headers: request.headers,
+            body: request.body,
+            signal: ctx.signal,
+        }, {
+            policy: toolNetworkPolicy(ctx),
+            followRedirects: true,
+            originBoundHeaders: prepared.authHeaders,
+            resolveHost: ctx.resolveHost,
+            onCheck: checks.onCheck,
+        });
+        const refusal = credentialRefusal(response);
+        if (refusal && refusalAsksForSignIn(refusal)) {
+            await response.body?.cancel();
+            throw new CredentialRefusedError(refusal);
+        }
+        return response;
+    };
+}

package/esm/src/kernel/tools/stage-run.d.ts

@@ -0,0 +1,93 @@
+import type { z } from 'zod';
+import { type LexiconOverrides } from '../../guardrails/lexicon.js';
+import type { SpanHandle } from '../../observability/trace-span.js';
+import { type InjectUnit, type StageHandler, type StageResult } from '../stages.js';
+import type { Profile, TurnEvent, TurnHistoryMessage } from '../types.js';
+import { type ToolCallBase } from './events.js';
+import type { ModelToolResult, ToolContext, ToolFailure, ToolGate } from './types.js';
+export interface ToolStageSupport {
+    /** In order: request `onStage`, then turn/session ambient. */
+    handlers: StageHandler[];
+    /** Its guardrails sanitize injects and its inject gate applies. */
+    profile: Profile;
+    step: number;
+    history: () => readonly TurnHistoryMessage[];
+    injectAllowed: boolean;
+    injectWouldExceedMaxSteps?: boolean;
+    host?: unknown;
+    signal?: AbortSignal;
+    span?: SpanHandle;
+}
+export type PreBodyOutcome = {
+    ok: true;
+    input: unknown;
+} | {
+    ok: false;
+    kind: 'aborted';
+    aborted: true | {
+        reason?: string;
+    };
+} | {
+    ok: false;
+    kind: 'gated';
+    gate: ToolGate;
+} | {
+    ok: false;
+    kind: 'failed';
+    failure: ToolFailure;
+    /** The host refused the call (`deny`), rather than it failing. */
+    denied?: true;
+};
+export type PostToolStageOutcome = {
+    abort?: boolean | {
+        reason?: string;
+    };
+    /** The caller lands these after recording the tool result. */
+    inject: InjectUnit[];
+    deny?: {
+        code: string;
+        message: string;
+    };
+    /** The caller re-validates and re-projects it. */
+    mutate?: {
+        output: unknown;
+    };
+};
+/** Tool `preTool` → host `pre_tool` → mutate re-parse. */
+export declare function runPreToolPipeline(args: {
+    tool: {
+        name: string;
+        input: {
+            safeParse: (value: unknown) => z.ZodSafeParseResult<unknown>;
+        };
+        preTool?: (input: never, ctx: ToolContext) => StageResult | undefined | Promise<StageResult | undefined>;
+    };
+    input: unknown;
+    ctx: ToolContext;
+    base: ToolCallBase;
+    stages?: ToolStageSupport;
+}): AsyncGenerator<TurnEvent, PreBodyOutcome>;
+export declare function runPostToolStages(args: {
+    stages: ToolStageSupport;
+    toolName: string;
+    callId: string;
+    input?: unknown;
+    callNotStarted?: boolean;
+    outputRaw?: unknown;
+    outputModel?: ModelToolResult;
+    failure?: ToolFailure;
+    awaiting?: boolean;
+    /** False when there is no completed output for `mutate` to replace. */
+    mutable: boolean;
+}): AsyncGenerator<TurnEvent, PostToolStageOutcome>;
+/**
+ * Returns the sign-in gate's `readBack`: what a transport that answers the call now (Live) tells
+ * the model while the person signs in. Other gates hold the call, and the model reads nothing yet.
+ */
+export declare function emitGateSettlement(args: {
+    base: ToolCallBase;
+    gate: ToolGate;
+    callId: string;
+    toolName: string;
+    lexicon: LexiconOverrides | undefined;
+}): AsyncGenerator<TurnEvent, string | undefined>;