@theoremjs/agents 0.3.0 → 0.3.1

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

@@ -0,0 +1,212 @@
+import { z } from 'zod';
+import { TheoremError } from '../../guardrails/error.js';
+import { interactionPartSchema, keptReply, sourceSchema } from '../turn-events.js';
+import { findLast } from '../util/find-last.js';
+import { profileToolAllow } from './resolve.js';
+/** A call that settled without a reply; the model reads `failure`. */
+class AgentCallFailed extends Error {
+    failure;
+    constructor(failure) {
+        super(failure.message);
+        this.failure = failure;
+    }
+}
+/** The agents an agent tool can run: each has a turn that takes text. */
+const AGENT_TOOL_TYPES = new Set(['text', 'image', 'speech']);
+// why: Bytes that are not base64, or a text of only spaces, would be refused inside the called turn as the host's error and end the caller's turn; checked here, the model reads a failed call.
+const textInput = z.string().regex(/\S/);
+const blobInput = z.strictObject({
+    mimeType: z.string(),
+    data: z.base64(),
+    name: z.string().optional(),
+});
+const mediaRefInput = z.strictObject({
+    mimeType: z.string(),
+    uri: z.string(),
+    name: z.string().optional(),
+});
+const speechInput = z.strictObject({
+    voice: z.string().optional(),
+    style: z.string().optional(),
+    speed: z.number().positive().optional(),
+});
+/** One choice per declared slot; a slot or a value the profile does not declare is refused. */
+function slotsInput(slots) {
+    return z.strictObject(Object.fromEntries(Object.entries(slots).map(([slot, choices]) => [slot, z.enum(choices).optional()])));
+}
+/** The fields an agent tool's input can carry to the called agent; a host field takes none of these names. */
+const AGENT_INPUT_FIELDS = new Set([
+    'text',
+    'attachments',
+    'voice',
+    'slots',
+    'speech',
+]);
+/**
+ * What the model sent, split into what goes to the called agent and what only the host reads.
+ *
+ * why: A host field is the host's own word for something (an id it resolves); the called profile does not take it, so it never reaches the agent's turn.
+ */
+function splitHostInput(tool, input) {
+    if (!tool.hostFields)
+        return { sent: input };
+    const all = { ...input };
+    const hostInput = {};
+    for (const field of Object.keys(tool.hostFields)) {
+        if (all[field] !== undefined)
+            hostInput[field] = all[field];
+    }
+    const { text, attachments, voice, slots, speech } = input;
+    return {
+        sent: {
+            text,
+            ...(attachments ? { attachments } : {}),
+            ...(voice ? { voice } : {}),
+            ...(slots ? { slots } : {}),
+            ...(speech ? { speech } : {}),
+        },
+        hostInput,
+    };
+}
+/**
+ * The input of an agent tool that runs `agent`: text, and each channel the
+ * profile's `inputs` declares. Anything else is refused, never dropped. The
+ * called turn's own ingress checks MIME types and sizes.
+ */
+function agentToolInputFor(agent, tool) {
+    const { inputs } = agent;
+    const shape = { text: textInput };
+    if (inputs?.attachments) {
+        shape.attachments = z.array(z.union([blobInput, mediaRefInput])).optional();
+    }
+    if (inputs?.voice)
+        shape.voice = z.array(blobInput).optional();
+    if (inputs?.slots)
+        shape.slots = slotsInput(inputs.slots).optional();
+    if (agent.type === 'speech')
+        shape.speech = speechInput.optional();
+    for (const channel of tool?.hostOnly ?? []) {
+        if (!shape[channel]) {
+            throw new TheoremError('config', `Tool '${tool?.name}' keeps '${channel}' for the host, which its profile does not take`);
+        }
+        delete shape[channel];
+    }
+    for (const [field, text] of Object.entries(tool?.fieldText ?? {})) {
+        const schema = shape[field];
+        if (!schema) {
+            throw new TheoremError('config', `Tool '${tool?.name}' describes '${field}', which its profile does not take`);
+        }
+        shape[field] = schema.describe(text);
+    }
+    for (const [field, schema] of Object.entries(tool?.hostFields ?? {})) {
+        if (AGENT_INPUT_FIELDS.has(field)) {
+            throw new TheoremError('config', `Tool '${tool?.name}' declares the host field '${field}', which is a field of every agent tool`);
+        }
+        shape[field] = schema;
+    }
+    // why: The shape is built key by key from the profile, which zod cannot type; each key is an `AgentToolInput` field.
+    return z.strictObject(shape);
+}
+const agentToolOutput = z.object({
+    text: z.string().optional(),
+    structured: z.unknown().optional(),
+    removed: z
+        .array(z.object({ path: z.string(), reason: z.string(), item: z.unknown() }))
+        .optional(),
+    parts: z.array(interactionPartSchema).optional(),
+    sources: z.array(sourceSchema).optional(),
+});
+function profileTakesText(profile) {
+    if (profile.type === 'speech')
+        return true;
+    return (profile.type === 'text' || profile.type === 'image') && profile.inputs.text !== false;
+}
+/** A tool that can stop the turn on a gate: a gate inside the called agent has no one to answer it. */
+function toolCanGate(tool) {
+    if (tool.type === 'builtin')
+        return false;
+    if (tool.permission !== 'auto')
+        return true;
+    return ('auth' in tool && tool.auth !== undefined && (tool.auth.onUnauthenticated ?? 'gate') === 'gate');
+}
+/** Why `profile` can't be run by an agent tool, or `undefined` when it can. */
+function agentProfileProblem(profile, find) {
+    if (!AGENT_TOOL_TYPES.has(profile.type)) {
+        return `it is a ${profile.type} profile; an agent tool runs a text, image, or speech profile`; // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+    if (!profileTakesText(profile))
+        return 'it does not take text'; // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    for (const id of profileToolAllow(profile)) {
+        const tool = find(id);
+        if (!tool)
+            return `its tool '${id}' is not registered; register it first`; // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        if (toolCanGate(tool)) {
+            return `its tool '${id}' can stop on a gate; give it permission 'auto' and no sign-in`; // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        }
+    }
+    return undefined;
+}
+/** The profile an agent tool runs; throws `config` when the tool can't run it. */
+function agentToolProfile(def, findProfile, findTool) {
+    const tag = `Agent tool "${def.name}"`; // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    const max = def.maxCallsPerTurn;
+    if (max !== undefined && !(Number.isInteger(max) && max > 0)) {
+        throw new TheoremError('config', `${tag}: maxCallsPerTurn must be a whole number above 0`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+    const profile = findProfile(def.profile);
+    if (!profile) {
+        throw new TheoremError('config', `${tag}: profile '${def.profile}' must be registered before the tool`);
+    }
+    const problem = agentProfileProblem(profile, findTool);
+    if (problem) {
+        throw new TheoremError('config', `${tag} can't run '${def.profile}': ${problem}`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+    return profile;
+}
+/** An agent with no tools of its own read only what it was sent; one with tools may have read outside content. */
+function agentToolOrigin(profile) {
+    if (!profile)
+        return 'delegated';
+    const builtins = 'models' in profile
+        ? Object.values(profile.models).some((binding) => (binding.builtInTools?.length ?? 0) > 0)
+        : false;
+    return profileToolAllow(profile).length === 0 && !builtins ? 'local' : 'delegated';
+}
+/**
+ * The called agent's reply: its text or its last structured reply, its media as parts, and what it cited.
+ *
+ * why: A structured reply's text is the same JSON as a string, so returning both would have the caller's model read the answer twice.
+ */
+function agentToolOutputOf(turn) {
+    const events = keptReply(turn);
+    const text = events.flatMap((e) => (e.type === 'text' ? [e.text] : [])).join('');
+    const reply = findLast(events, (e) => e.type === 'structured');
+    const structured = reply?.structured;
+    const parts = events.flatMap((e) => e.type === 'media'
+        ? [
+            {
+                type: e.media.mimeType.startsWith('audio/') ? 'audio' : 'image',
+                mimeType: e.media.mimeType,
+                data: e.media.data,
+            },
+        ]
+        : []);
+    const sources = events.flatMap((e) => (e.type === 'citation' ? e.sources : []));
+    return {
+        ...(structured === undefined ? { text } : { structured }),
+        ...(reply?.removed?.length ? { removed: reply.removed } : {}),
+        ...(parts.length > 0 ? { parts } : {}),
+        ...(sources.length > 0 ? { sources } : {}),
+    };
+}
+function normalizeAgent(def, input, schemas) {
+    return {
+        ...def,
+        type: 'agent',
+        input,
+        output: agentToolOutput,
+        sources: (output) => output.sources ?? [],
+        ...schemas,
+    };
+}
+export { AgentCallFailed, agentProfileProblem, agentToolInputFor, agentToolOrigin, agentToolOutput, agentToolOutputOf, agentToolProfile, normalizeAgent, splitHostInput, };

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

@@ -0,0 +1,4 @@
+import type { TurnEvent } from '../types.js';
+import type { ToolExecuteSettlement } from './execute.js';
+import { type ToolExecutionCoordinator, type ToolOperationClaim, type ToolOperationIdentity, type ToolOperationOutcome } from './operation.js';
+export declare function coordinateTool(coordinator: ToolExecutionCoordinator | undefined, identity: Omit<ToolOperationIdentity, 'invocationHash'>, invocation: unknown, signal: AbortSignal | undefined, run: (beginBody?: (preparedInput: unknown) => Promise<ToolOperationClaim | undefined>) => AsyncGenerator<TurnEvent, ToolExecuteSettlement>, authorizeReplay?: (outcome: ToolOperationOutcome) => void | Promise<void>): AsyncGenerator<TurnEvent, ToolExecuteSettlement>;

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

@@ -0,0 +1,165 @@
+import { TheoremError, throwIfAborted } from '../../guardrails/error.js';
+import { labelText } from '../../guardrails/labels.js';
+import { jsonObjectSchema } from '../json.js';
+import { operationUnavailable, operationWireValue, toolInvocationHash, toolOperationOutcomeSchema, } from './operation.js';
+class ReplayedOperation {
+    outcome;
+    constructor(outcome) {
+        this.outcome = outcome;
+    }
+}
+function uncertainError(cause) {
+    return new TheoremError('unavailable', labelText('tool.execution_uncertain'), {
+        copy: { key: 'tool.execution_uncertain' },
+        cause,
+    });
+}
+class CoordinatedExecution {
+    coordinator;
+    operation;
+    accepted;
+    signal;
+    claim;
+    committed = false;
+    writeFailed = false;
+    terminal;
+    constructor(coordinator, operation, accepted, signal) {
+        this.coordinator = coordinator;
+        this.operation = operation;
+        this.accepted = accepted;
+        this.signal = signal;
+    }
+    async beginBody(preparedInput) {
+        throwIfAborted(this.signal);
+        const operation = {
+            ...this.operation,
+            invocation: { accepted: this.accepted, preparedInput: operationWireValue(preparedInput) },
+        };
+        const result = await this.coordinator.begin(operation);
+        if (result.kind === 'settled')
+            throw new ReplayedOperation(result.outcome);
+        if (result.kind === 'running' || result.kind === 'uncertain')
+            throw uncertainError();
+        if (result.kind !== 'acquired' || typeof result.claimToken !== 'string' || !result.claimToken)
+            throw operationUnavailable();
+        this.claim = { ...operation, claimToken: result.claimToken };
+        throwIfAborted(this.signal);
+        return this.claim;
+    }
+    observe(event) {
+        if (event.type !== 'tool')
+            return true;
+        if (event.tool.phase === 'complete' || event.tool.phase === 'error') {
+            this.terminal = { ...event, tool: event.tool };
+            return false;
+        }
+        if (this.claim && event.tool.phase === 'gate')
+            throw uncertainError();
+        return true;
+    }
+    async finish(settlement) {
+        if (settlement.gated) {
+            if (this.claim)
+                throw uncertainError();
+            return undefined;
+        }
+        if (!this.terminal)
+            throw operationUnavailable();
+        const { modelResult, outputRaw, failure, awaiting, denied, callNotStarted, aborted, pendingInject, } = settlement;
+        const effects = this.claim ? (failure ? 'unknown' : 'completed') : 'not_started';
+        const outcome = {
+            event: this.terminal,
+            effects,
+            replay: {
+                modelResult,
+                outputRaw,
+                failure,
+                awaiting,
+                denied,
+                callNotStarted,
+                aborted,
+                pendingInject,
+            },
+        };
+        this.writeFailed = true;
+        const saved = toolOperationOutcomeSchema.parse(operationWireValue(outcome));
+        if (this.claim)
+            await this.coordinator.settle(this.claim, saved);
+        else
+            await this.coordinator.settleNotStarted(this.operation, saved);
+        this.committed = true;
+        return saved.event;
+    }
+    replay(error) {
+        const saved = toolOperationOutcomeSchema.parse(operationWireValue(error.outcome));
+        const { operationId, callId, toolId } = this.operation;
+        if (saved.event.tool.operationId !== operationId ||
+            saved.event.tool.callId !== callId ||
+            saved.event.tool.name !== toolId)
+            throw operationUnavailable();
+        this.committed = true;
+        return saved;
+    }
+    failure(error) {
+        return this.claim && !this.committed ? uncertainError(error) : error;
+    }
+    async close() {
+        if (this.claim && !this.committed) {
+            await this.coordinator.markUncertain(this.claim, this.writeFailed ? 'settlement_write_failed' : 'execution_interrupted');
+        }
+    }
+}
+export async function* coordinateTool(coordinator, identity, invocation, signal, run, authorizeReplay) {
+    if (!coordinator)
+        return yield* run();
+    const accepted = jsonObjectSchema.parse(operationWireValue(invocation));
+    const operation = { ...identity, invocationHash: await toolInvocationHash(accepted) };
+    const execution = new CoordinatedExecution(coordinator, operation, accepted, signal);
+    throwIfAborted(signal);
+    const existing = await coordinator.lookup(operation);
+    throwIfAborted(signal);
+    if (existing?.kind === 'running' || existing?.kind === 'uncertain')
+        throw uncertainError();
+    if (existing?.kind === 'settled') {
+        if (!authorizeReplay)
+            throw operationUnavailable();
+        const saved = execution.replay(new ReplayedOperation(existing.outcome));
+        await authorizeReplay(saved);
+        throwIfAborted(signal);
+        yield saved.event;
+        return saved.replay;
+    }
+    const iterator = run((input) => execution.beginBody(input));
+    try {
+        for (;;) {
+            const next = await iterator.next();
+            if (next.done) {
+                const terminal = await execution.finish(next.value);
+                if (terminal)
+                    yield terminal;
+                return next.value;
+            }
+            if (execution.observe(next.value))
+                yield next.value;
+        }
+    }
+    catch (error) {
+        if (error instanceof ReplayedOperation) {
+            if (!authorizeReplay)
+                throw operationUnavailable();
+            const saved = execution.replay(error);
+            await authorizeReplay(saved);
+            yield saved.event;
+            return saved.replay;
+        }
+        throw execution.failure(error);
+    }
+    finally {
+        try {
+            await execution.close();
+        }
+        finally {
+            await iterator.return({});
+        }
+    }
+}

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

@@ -1,32 +1,47 @@
 import type { z } from 'zod';
+import { type LabelOverrides } from '../../guardrails/labels.js';
 import type { GuardrailEvent, NetworkGuardrailSpec } from '../../guardrails/types.js';
 import type { SpanHandle } from '../../observability/trace-span.js';
 import { type Source } from '../turn-events.js';
 import type { TurnEvent, TurnEventOf } from '../types.js';
+import type { ToolOperationClaim } from './operation.js';
 import type { ToolCallRequest, ToolContext, ToolFailure, ToolLabels, ToolPhaseEvent } from './types.js';
-export type ToolCallBase = Pick<ToolPhaseEvent, 'name' | 'callId'>;
+export type ToolCallBase = Pick<ToolPhaseEvent, 'name' | 'callId'> & {
+    operationId?: string;
+    /** The call's failed label, from {@linkcode failedActivity}; absent, a failure names the tool. */
+    activityFailed?: string;
+};
 export type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
 export type ToolPhasePatch = DistributiveOmit<ToolPhaseEvent, keyof ToolCallBase | 'at'>;
 export declare function toolEvent(base: ToolCallBase, patch: ToolPhasePatch): TurnEventOf<'tool'>;
+/**
+ * The label a failed call shows: the tool's own, filled from the input the model sent, else the
+ * labels' line naming the tool in words.
+ */
+export declare function failedActivity(name: string, profileLabels?: LabelOverrides, labels?: ToolLabels, input?: unknown): string;
+/** The failed label of the call `base` names. */
+export declare function failedActivityOf(base: ToolCallBase): string;
 /** `readBack` is passed when the call's result guard already wrote the model's text. */
 export declare function failureEvent(base: ToolCallBase, failure: ToolFailure, readBack?: string): TurnEventOf<'tool'>;
 /** The first event of every call. */
-export declare function toolCallRequestEvent(base: ToolCallBase, args: Record<string, unknown>, { thoughtSignature, stepId }?: Pick<ToolCallRequest, 'thoughtSignature' | 'stepId'>): TurnEventOf<'tool'>;
+export declare function toolCallRequestEvent(base: ToolCallBase, args: Record<string, unknown>, { reasoning, stepId, stepCallCount, }?: Pick<ToolCallRequest, 'reasoning' | 'stepId' | 'stepCallCount'>): TurnEventOf<'tool'>;
 /** Unique: readers join a call's events by it. */
 export declare function newCallId(name: string): string;
 export declare function toolCallArguments(safeInput: unknown): Record<string, unknown>;
 export declare function messageOf(err: unknown): string;
 export declare function sourceEvents(base: ToolCallBase, sources: (output: unknown) => Source[], output: unknown): Generator<TurnEvent>;
-/** `{ ok: false }` comes after the failure event is emitted, so callers only bail. */
+export declare function dispatchToolBody(tool: {
+    labels?: ToolLabels;
+}, input: unknown, ctx: ToolContext, base: ToolCallBase, beginBody?: (preparedInput: unknown) => Promise<ToolOperationClaim | undefined>): AsyncGenerator<TurnEvent, ToolOperationClaim | undefined>;
 export declare function startToolExecution<T>(tool: {
     input: z.ZodType<T>;
-    labels?: ToolLabels;
-}, rawInput: unknown, ctx: ToolContext, base: ToolCallBase): Generator<TurnEvent, {
+}, rawInput: unknown, ctx: ToolContext): {
     ok: true;
     data: T;
 } | {
     ok: false;
-}>;
+    failure: ToolFailure;
+};
 export declare function networkBlockedEvent(): GuardrailEvent;
 export declare function networkBlocked(err: unknown, guardrail?: GuardrailEvent): Generator<TurnEvent, ToolFailure>;
 /**

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

@@ -1,32 +1,58 @@
 import { throwIfAborted } from '../../guardrails/error.js';
+import { labelText } from '../../guardrails/labels.js';
 import { assertSafeUrl } from '../../guardrails/network.js';
 import { resolveGuardrailPolicy } from '../../guardrails/policy.js';
 import { NETWORK_RULES } from '../../guardrails/rules.js';
 import { recordToolCheck } from '../engine/tool-trace.js';
 import { sourceSchema } from '../turn-events.js';
 import { isRecord } from '../util/record.js';
-import { fillActivityLabel } from './activity-label.js';
+import { fillActivityLabel, toolNameInWords } from './activity-label.js';
 import { formatToolFailureForModel, formatToolResult } from './model-text.js';
 export function toolEvent(base, patch) {
     return {
         type: 'tool',
-        tool: { ...patch, name: base.name, callId: base.callId, at: Date.now() },
+        tool: {
+            ...patch,
+            name: base.name,
+            callId: base.callId,
+            ...(base.operationId ? { operationId: base.operationId } : {}),
+            at: Date.now(),
+        },
     };
 }
+/**
+ * The label a failed call shows: the tool's own, filled from the input the model sent, else the
+ * labels' line naming the tool in words.
+ */
+export function failedActivity(name, profileLabels, labels, input) {
+    return (fillActivityLabel(labels?.activityFailed, { input }) ??
+        labelText('tool.activity_failed', { tool: toolNameInWords(name) }, profileLabels));
+}
+/** The failed label of the call `base` names. */
+export function failedActivityOf(base) {
+    return base.activityFailed ?? failedActivity(base.name);
+}
 /** `readBack` is passed when the call's result guard already wrote the model's text. */
 export function failureEvent(base, failure, readBack = formatToolResult(formatToolFailureForModel(failure))) {
-    return toolEvent(base, { phase: 'error', failure, readBack });
+    return toolEvent(base, {
+        phase: 'error',
+        failure,
+        readBack,
+        activityPast: failedActivityOf(base),
+    });
 }
 /** The first event of every call. */
-export function toolCallRequestEvent(base, args, { thoughtSignature, stepId } = {}) {
+export function toolCallRequestEvent(base, args, { reasoning, stepId, stepCallCount, } = {}) {
     return {
         type: 'tool',
         tool: {
             name: base.name,
             callId: base.callId,
+            ...(base.operationId ? { operationId: base.operationId } : {}),
             arguments: args,
-            ...(thoughtSignature ? { thoughtSignature } : {}),
+            ...(reasoning?.length ? { reasoning } : {}),
             ...(stepId ? { stepId } : {}),
+            ...(stepCallCount ? { stepCallCount } : {}),
         },
     };
 }
@@ -54,11 +80,11 @@ export function* sourceEvents(base, sources, output) {
         listed = sources(output);
     }
     catch (err) {
-        yield sourcesInvalid(base, `sources threw: ${messageOf(err)}`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        yield sourcesInvalid(base, `sources threw: ${messageOf(err)}`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
         return;
     }
     if (!Array.isArray(listed)) {
-        yield sourcesInvalid(base, 'sources must return an array'); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        yield sourcesInvalid(base, 'sources must return an array'); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
         return;
     }
     const cited = [];
@@ -71,30 +97,39 @@ export function* sourceEvents(base, sources, output) {
             invalid.push(`[${String(index)}] ${parsed.error.issues.map((i) => `${i.path.join('.') || 'source'}: ${i.message}`).join('; ')}`);
     });
     if (invalid.length > 0) {
-        yield sourcesInvalid(base, `sources not cited: ${invalid.join(' | ')}`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        yield sourcesInvalid(base, `sources not cited: ${invalid.join(' | ')}`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
     }
     if (cited.length > 0)
         yield { type: 'citation', sources: cited, callId: base.callId };
 }
-/** `{ ok: false }` comes after the failure event is emitted, so callers only bail. */
-export function* startToolExecution(tool, rawInput, ctx, base) {
+function toolRunningEvent(tool, rawInput, ctx, base) {
     const edited = ctx.resume?.edited;
     const activity = fillActivityLabel(tool.labels?.activity, { input: rawInput });
-    yield toolEvent(base, {
+    return toolEvent(base, {
         phase: 'running',
         ...(edited ? { edited: { from: edited.from, to: toolCallArguments(rawInput) } } : {}),
         ...(activity ? { activity } : {}),
     });
+}
+export async function* dispatchToolBody(tool, input, ctx, base, beginBody) {
+    const claim = await beginBody?.(input);
+    throwIfAborted(ctx.signal);
+    yield toolRunningEvent(tool, input, ctx, base);
+    return claim;
+}
+export function startToolExecution(tool, rawInput, ctx) {
     throwIfAborted(ctx.signal);
     const parsed = tool.input.safeParse(rawInput);
     if (!parsed.success) {
-        yield failureEvent(base, {
-            code: 'invalid_input',
-            kind: 'bad_response',
-            message: 'Tool input validation failed', // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
-            details: parsed.error.flatten(),
-        });
-        return { ok: false };
+        return {
+            ok: false,
+            failure: {
+                code: 'invalid_input',
+                kind: 'bad_response',
+                message: labelText('tool.input_invalid', {}, ctx.profile.labels),
+                details: parsed.error.flatten(),
+            },
+        };
     }
     return { ok: true, data: parsed.data };
 }

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

@@ -1,20 +1,28 @@
-import { type LexiconOverrides } from '../../guardrails/lexicon.js';
+import { type ToolBoundary } from '../../guardrails/boundaries.js';
+import { type DetectScope } from '../../guardrails/detect-at.js';
+import { type LabelOverrides } from '../../guardrails/labels.js';
 import type { SpanHandle, TraceAttributes } from '../../observability/trace-span.js';
 import { type ToolCallEnd } from '../engine/tool-trace.js';
-import { type InjectUnit } from '../stages.js';
+import type { InjectUnit } from '../stages.js';
 import type { InteractionPart, Profile, TurnEvent } from '../types.js';
+import { type AgentCaller } from './agent.js';
 import { startToolExecution, type ToolCallBase } from './events.js';
+import type { ToolExecutionCoordinator, ToolOperationClaim, ToolOperationOutcome } from './operation.js';
 import type { ToolRegistry } from './registry.js';
 import { type ToolStageSupport } from './stage-run.js';
-import type { FunctionToolDef, ModelToolResult, ToolContext, ToolFailure, ToolGate, ToolStreamEvent, TurnToolSnapshot } from './types.js';
+import type { FunctionToolDef, ModelToolResult, RegisteredAgentTool, ToolContext, ToolFailure, ToolGate, TurnToolSnapshot } from './types.js';
 export { checkPermission, isGateResumeGranted, isResumeContinuation, permissionGranted, } from './permission.js';
+/**
+ * The boundary a call of `name` is read at before its tool gets it: none for a provider builtin,
+ * whose text the kernel never reads. A call no tool takes is read as a function tool's.
+ */
+export declare function toolArgumentsBoundary(tools: ToolRegistry, name: string): ToolBoundary | undefined;
 /** Invalid entries are dropped. */
 export declare function coerceToolResultParts(raw: unknown): InteractionPart[] | undefined;
+/** A tool's output without its `parts` key, which carries media the model receives separately; any other value is returned as it is. */
 export declare function leanToolResultData(output: unknown): unknown;
-export declare function yieldHandlerSideEvent(base: ToolCallBase, event: Exclude<ToolStreamEvent, {
-    kind: 'complete';
-}>): Generator<TurnEvent>;
-export declare function projectForModel(tool: FunctionToolDef, output: unknown, lexicon?: LexiconOverrides): ModelToolResult;
+/** What the model is told of a function tool's output: a fixed finding for a hidden tool, a finding plus the output for an awaiting-user result, otherwise the tool's own summary or finding and its data. */
+export declare function projectForModel(tool: FunctionToolDef, output: unknown, labels?: LabelOverrides): ModelToolResult;
 export type ToolExecuteSettlement = {
     modelResult?: ModelToolResult;
     gated?: ToolGate;
@@ -32,33 +40,61 @@ export type ToolExecuteSettlement = {
     /** Landed after the provider tool result is recorded: the Interactions continuation must exist first. */
     pendingInject?: InjectUnit[];
 };
-export declare function executeFunction(tools: ToolRegistry, tool: FunctionToolDef, rawInput: unknown, ctx: ToolContext, base: ToolCallBase, snapshot?: TurnToolSnapshot, stages?: ToolStageSupport): AsyncGenerator<TurnEvent, ToolExecuteSettlement>;
+export declare function executeFunction(tools: ToolRegistry, tool: FunctionToolDef, rawInput: unknown, ctx: ToolContext, base: ToolCallBase, snapshot?: TurnToolSnapshot, stages?: ToolStageSupport, 
+/** Set when `tool` runs an agent tool: its trust, and its handler's failures and faults. */
+agent?: RegisteredAgentTool, beginBody?: (preparedInput: unknown) => Promise<ToolOperationClaim | undefined>): AsyncGenerator<TurnEvent, ToolExecuteSettlement>;
+/** Names the profile's loader when it can load the tool, so the model knows which call comes first. */
 export declare function notLoadedMessage(tool: {
     name: string;
     loadTier?: string;
-}, lexicon?: LexiconOverrides): string;
+}, profile: Profile): string;
 export declare function executeBuiltin(tool: {
     name: string;
 }, ctx: ToolContext, base: ToolCallBase, snapshot: TurnToolSnapshot): AsyncGenerator<TurnEvent, ToolExecuteSettlement>;
+export declare function authorizeToolReplay(args: {
+    tools: ToolRegistry;
+    profile: Profile;
+    name: string;
+    resume: ToolContext['resume'];
+    snapshot?: TurnToolSnapshot;
+    outcome?: ToolOperationOutcome;
+}): void;
 interface RegisteredToolCall {
+    execution?: ToolExecutionCoordinator;
+    invocation?: unknown;
+    onDispatch?: () => void;
+    beginBody?: (preparedInput: unknown) => Promise<ToolOperationClaim | undefined>;
     tools: ToolRegistry;
     profile: Profile;
     name: string;
     input: unknown;
     callId: string;
-    ctx: Omit<ToolContext, 'callId' | 'profile'>;
+    ctx: Omit<ToolContext, 'callId' | 'profile' | 'operationId'> & {
+        operationId?: string;
+    };
     snapshot?: TurnToolSnapshot;
     stages?: ToolStageSupport;
     /** Omitted: the call is not traced. The span is handed to the tool as `ctx.traceparent`. */
     openSpan?: (name: string, attributes: TraceAttributes) => SpanHandle;
     /** Defaults to `turnReadBack`; a transport that sends something else (Live's `functionResponse`) passes its own. */
     readBack?: (settlement: ToolExecuteSettlement) => ToolCallEnd['result'];
+    /** Runs agent tool calls; without it an agent tool fails as a type the transport can't run. */
+    agents?: AgentCaller;
+    /** The canary and system instruction of the turn the model called from, read for in the arguments. */
+    scope?: DetectScope;
 }
 /**
  * A gate nobody answered: a sign-in for `expiredService` whose link expired, or any other gate
  * left behind. Both settle as `cancelled`.
  */
-export declare function lapsedGateFailure(toolName: string, expiredService: string | undefined, lexicon: LexiconOverrides | undefined): ToolFailure;
+export declare function lapsedGateFailure(toolName: string, expiredService: string | undefined, labels: LabelOverrides | undefined): ToolFailure;
+/** Runs one registered tool call as a stream of turn events and returns how it settled; when `openSpan` is given the call is recorded as a tool span that ends with the outcome. */
+/**
+ * A call's arguments as its tool gets them, which is what the call's first
+ * event shows the host: a detector's placeholder where it redacts, and none
+ * when the call is stopped. A call no tool takes is read as a function tool's.
+ */
+export declare function shownToolArguments(call: Pick<RegisteredToolCall, 'tools' | 'profile' | 'name' | 'input' | 'scope'>): Record<string, unknown>;
 export declare function executeRegisteredTool(args: RegisteredToolCall): AsyncGenerator<TurnEvent, ToolExecuteSettlement>;
 export type { RegisteredToolCall, ToolStageSupport };
 export { startToolExecution };