@theoremjs/agents 0.3.0 → 0.3.1

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

@@ -1,32 +1,57 @@
-import { errorKind, isAbortError, throwIfAborted } from '../../guardrails/error.js';
-import { lexiconText } from '../../guardrails/lexicon.js';
+import { toolBoundary } from '../../guardrails/boundaries.js';
+import { checkDestinationGate } from '../../guardrails/destinations.js';
+import { scopeOf } from '../../guardrails/detect-at.js';
+import { errorKind, isAbortError, TheoremError, throwIfAborted } from '../../guardrails/error.js';
+import { labelText } from '../../guardrails/labels.js';
 import { resolveGuardrailPolicy } from '../../guardrails/policy.js';
-import { resolveSensitive } from '../../guardrails/sensitive.js';
-import { checkTaintGate, guardToolFailureText, guardToolResult, inspectToolArguments, toolCallEvent, } from '../../guardrails/tool-result.js';
+import { checkTaintGate, guardShownValue, guardToolFailureText, guardToolResult, inspectToolArguments, toolCallEvent, } from '../../guardrails/tool-result.js';
 import { recordToolCheck, startToolTrace, } from '../engine/tool-trace.js';
-import { isAwaitingUserInput } from '../stages.js';
+import { jsonObjectSchema } from '../json.js';
+import { isAwaitingUserInput } from '../turn-events.js';
 import { isRecord } from '../util/record.js';
 import { fillActivityLabel } from './activity-label.js';
-import { failureEvent, messageOf, networkBlocked, networkBlockedEvent, requestChecks, sourceEvents, startToolExecution, toolCallArguments, toolEvent, } from './events.js';
-import { formatToolFailureForModel, formatToolResult } from './model-text.js';
-import { checkPermission, isGateResumeDenied, isGateResumeGranted, isResumeContinuation, } from './permission.js';
+import { AgentCallFailed, agentToolOrigin } from './agent.js';
+import { coordinateTool } from './coordinate.js';
+import { dispatchToolBody, failedActivity, failedActivityOf, failureEvent, messageOf, networkBlocked, networkBlockedEvent, requestChecks, sourceEvents, startToolExecution, toolCallArguments, toolEvent, } from './events.js';
+import { HandlerEvents } from './handler-events.js';
+import { formatToolFailureForModel, formatToolResult, frameToolFailure } from './model-text.js';
+import { operationUnavailable, operationWireValue } from './operation.js';
+import { checkPermission, gateDetails, isGateResumeDenied, isGateResumeGranted, isResumeContinuation, } from './permission.js';
 import { executeHttpTool, executeMcpTool, failureWithoutSecret, modelResultFromOutput, omitSecret, outcomeFromUnauth, parseToolOutput, refusedCredentialOutcome, resolveToolAuth, withMedia, } from './remote.js';
 import { extractLoadedIds, profileToolAllow, profileToolsSpec, promoteLoadedTools, } from './resolve.js';
 import { plainToolInput } from './schema.js';
 import { CredentialRefusedError, signedInFetch } from './signed-in-fetch.js';
 import { emitGateSettlement, runPostToolStages, runPreToolPipeline, } from './stage-run.js';
 export { checkPermission, isGateResumeGranted, isResumeContinuation, permissionGranted, } from './permission.js';
-function originOfTool(type) {
-    if (type === 'http')
+import { UncheckedOutput } from './unchecked-output.js';
+function originOfTool(tool, tools) {
+    if (tool.type === 'agent')
+        return agentToolOrigin(tools.findProfile(tool.profile));
+    if (tool.type === 'http')
         return 'http';
-    if (type === 'mcp')
+    if (tool.type === 'mcp')
         return 'mcp';
-    if (type === 'builtin')
+    if (tool.type === 'builtin')
         return 'builtin';
     return 'local';
 }
-function provenanceFor(tool, depth = 1) {
-    return { origin: originOfTool(tool.type), tool: tool.name, depth };
+/** The kind whose boundaries a tool's calls cross. A provider builtin crosses none. */
+function toolKindOf(tool) {
+    return tool.type === 'builtin' ? undefined : tool.type;
+}
+/**
+ * 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 function toolArgumentsBoundary(tools, name) {
+    const tool = tools.get(name);
+    const kind = tool ? toolKindOf(tool) : 'function';
+    return kind && toolBoundary('tool_arguments', kind);
+}
+/** A delegated reply is one hop past the called agent's own tools. */
+function provenanceFor(tool, tools) {
+    const origin = originOfTool(tool, tools);
+    return { origin, tool: tool.name, depth: origin === 'delegated' ? 2 : 1 };
 }
 function isStreamHandler(handler) {
     return (typeof handler === 'function' &&
@@ -59,27 +84,14 @@ export function coerceToolResultParts(raw) {
     }
     return parts.length > 0 ? parts : 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 function leanToolResultData(output) {
     if (!isRecord(output))
         return output;
     const { parts: _parts, ...rest } = output;
     return rest;
 }
-export function* yieldHandlerSideEvent(base, event) {
-    if (event.kind === 'progress') {
-        yield toolEvent(base, { phase: 'progress', data: event.data });
-    }
-    else if (event.kind === 'trace') {
-        yield toolEvent(base, { phase: 'trace', step: event.step });
-    }
-    else if (event.kind === 'artifact') {
-        yield toolEvent(base, { phase: 'artifact', artifact: event.artifact });
-    }
-    else if (event.kind === 'warning') {
-        yield toolEvent(base, { phase: 'warning', warning: event.warning });
-    }
-}
-async function* runHandler(handler, input, ctx, base) {
+async function* runHandler(handler, input, ctx, shown) {
     if (isStreamHandler(handler)) {
         let output;
         const gen = handler(input, ctx);
@@ -89,20 +101,22 @@ async function* runHandler(handler, input, ctx, base) {
                 output = event.output;
                 continue;
             }
-            yield* yieldHandlerSideEvent(base, event);
+            yield* shown.show(event);
         }
+        yield* shown.end();
         return output;
     }
     const output = await handler(input, ctx);
-    return output;
+    return output instanceof UncheckedOutput ? output.value : output;
 }
-export function projectForModel(tool, output, lexicon) {
+/** 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 function projectForModel(tool, output, labels) {
     if (tool.exposeToModel === false) {
-        return { finding: lexiconText('tool.completed_hidden', {}, lexicon) };
+        return { finding: labelText('tool.completed_hidden', {}, labels) };
     }
     if (isAwaitingUserInput(output)) {
         return {
-            finding: lexiconText('tool.awaiting_user', { kind: output.kind, prompt: output.prompt }, lexicon),
+            finding: labelText('tool.awaiting_user', { kind: output.kind, prompt: output.prompt }, labels),
             data: leanToolResultData(output),
         };
     }
@@ -131,7 +145,7 @@ function applyT2LoaderPromotion(tools, tool, checkedData, ctx, snapshot) {
             failure: {
                 code: 'invalid_output',
                 kind: 'bad_response',
-                message: lexiconText('tool.t2_loader_needs_snapshot', { tool: tool.name }, ctx.profile.lexicon),
+                message: labelText('tool.t2_loader_needs_snapshot', { tool: tool.name }, ctx.profile.labels),
             },
         };
     }
@@ -142,7 +156,7 @@ function applyT2LoaderPromotion(tools, tool, checkedData, ctx, snapshot) {
             failure: {
                 code: 'invalid_output',
                 kind: 'bad_response',
-                message: lexiconText('tool.t2_loader_shape', { tool: tool.name }, ctx.profile.lexicon),
+                message: labelText('tool.t2_loader_shape', { tool: tool.name }, ctx.profile.labels),
             },
         };
     }
@@ -158,7 +172,7 @@ function applyT2LoaderPromotion(tools, tool, checkedData, ctx, snapshot) {
             failure: {
                 code: 'invalid_output',
                 kind: 'bad_response',
-                message: lexiconText('tool.t2_loader_output_invalid', {}, ctx.profile.lexicon),
+                message: labelText('tool.t2_loader_output_invalid', {}, ctx.profile.labels),
                 details: rechecked.error.flatten(),
             },
         };
@@ -176,7 +190,7 @@ function* reviseAfterStages(post, guard, reproject) {
         return {
             failure,
             outputRaw: undefined,
-            modelResult: yield* guard.failure(failure),
+            modelResult: (yield* guard.failure(failure)).modelResult,
             awaiting: false,
         };
     }
@@ -187,22 +201,33 @@ function* reviseAfterStages(post, guard, reproject) {
         return {
             failure: next.failure,
             outputRaw: undefined,
-            modelResult: yield* guard.failure(next.failure),
+            modelResult: (yield* guard.failure(next.failure)).modelResult,
+            awaiting: false,
+        };
+    }
+    const guarded = yield* guard.result(next.modelResult);
+    if (guarded.withheld) {
+        return {
+            failure: guarded.withheld,
+            outputRaw: undefined,
+            modelResult: guarded.modelResult,
             awaiting: false,
         };
     }
     return {
         outputRaw: next.outputRaw,
-        modelResult: yield* guard.result(next.modelResult),
+        modelResult: guarded.modelResult,
         awaiting: isAwaitingUserInput(next.outputRaw),
     };
 }
+function pastActivity(labels, input, output) {
+    return fillActivityLabel(labels?.activityPast, { input, output });
+}
 function completeEvent(base, settled) {
     const { input, outputRaw, modelResult } = settled;
-    const activityPast = fillActivityLabel(settled.labels?.activityPast, {
-        input,
-        output: outputRaw,
-    });
+    const activityPast = settled.labelFailed
+        ? failedActivityOf(base)
+        : pastActivity(settled.labels, input, outputRaw);
     return toolEvent(base, {
         phase: 'complete',
         output: outputRaw,
@@ -217,16 +242,18 @@ function completeEvent(base, settled) {
  */
 async function* settleToolCall(args) {
     const { base, toolName, callId, input, stages, provisional, guard, reproject, sources } = args;
-    let modelResult = yield* 'failure' in provisional
+    const guarded = yield* 'failure' in provisional
         ? guard.failure(provisional.failure)
         : guard.result(provisional.modelResult);
-    let failure = 'failure' in provisional ? provisional.failure : undefined;
-    let outputRaw = 'outputRaw' in provisional ? provisional.outputRaw : undefined;
+    let modelResult = guarded.modelResult;
+    let failure = 'failure' in provisional ? provisional.failure : guarded.withheld;
+    let outputRaw = 'outputRaw' in provisional && !failure ? provisional.outputRaw : undefined;
     const callNotStarted = 'callNotStarted' in provisional ? provisional.callNotStarted : undefined;
     let denied = 'denied' in provisional ? provisional.denied : undefined;
     let awaiting = !failure && isAwaitingUserInput(outputRaw);
     let post;
     if (stages) {
+        const activityPast = failure ? undefined : pastActivity(args.labels, input, outputRaw);
         post = yield* runPostToolStages({
             stages,
             toolName,
@@ -235,6 +262,8 @@ async function* settleToolCall(args) {
             callNotStarted,
             outputRaw,
             outputModel: modelResult,
+            ...(activityPast ? { activityPast } : {}),
+            activityFailed: failedActivityOf(base),
             failure,
             awaiting: awaiting || undefined,
             mutable: !failure && reproject !== undefined,
@@ -249,14 +278,26 @@ async function* settleToolCall(args) {
     if (!failure && sources)
         yield* sourceEvents(base, sources, outputRaw);
     yield failure
-        ? failureEvent(base, failure, formatToolResult(modelResult))
-        : completeEvent(base, { input, outputRaw, modelResult, labels: args.labels });
+        ? failureEvent(base, { ...failure, message: String(yield* guard.shown(failure.message)) }, formatToolResult(modelResult))
+        : completeEvent(base, {
+            input,
+            outputRaw: yield* guard.shown(outputRaw),
+            modelResult,
+            labels: args.labels,
+            ...(post?.labelFailed ? { labelFailed: true } : {}),
+        });
     return {
         modelResult,
         ...(failure ? { failure } : { outputRaw }),
         ...(denied ? { denied } : {}),
         ...(callNotStarted ? { callNotStarted: true } : {}),
         ...(awaiting ? { awaiting: true } : {}),
+        ...stageSettlement(post),
+    };
+}
+/** What the after-call stages add to a settlement: a turn to stop, input to hand the model. */
+function stageSettlement(post) {
+    return {
         ...(post?.abort !== undefined ? { aborted: post.abort } : {}),
         ...(post?.inject.length ? { pendingInject: post.inject } : {}),
     };
@@ -276,16 +317,52 @@ function settleToolFailure(guard, base, failure, stages, args) {
         },
     });
 }
-function resultGuard(tool, ctx, snapshot, span) {
-    const provenance = provenanceFor(tool);
+function resultGuard(tools, tool, ctx, snapshot, span) {
+    const provenance = provenanceFor(tool, tools);
     const policy = resolveGuardrailPolicy(ctx.profile.guardrails);
     const callableTools = snapshot?.executable ?? [];
-    const inputs = { provenance, policy, callableTools, lexicon: ctx.profile.lexicon, span };
+    const inputs = {
+        provenance,
+        policy,
+        kind: toolKindOf(tool),
+        callableTools,
+        labels: ctx.profile.labels,
+        span,
+    };
+    const { kind } = inputs;
+    const handlerEvents = (drafts) => kind && {
+        profileId: ctx.profile.id,
+        provenance,
+        policy,
+        boundary: toolBoundary('tool_output', kind),
+        shown: toolBoundary('tool_shown', kind),
+        callableTools,
+        drafts,
+    };
+    const shown = (value) => showValue(value, inputs);
+    const service = isGateResumeGranted(ctx.resume) ? signInService(tool, ctx.resume) : undefined;
+    if (!service) {
+        return {
+            result: (result) => guardResult(result, inputs),
+            failure: (failure) => guardFailure(failure, inputs),
+            handlerEvents,
+            shown,
+        };
+    }
+    const note = labelText('sign_in.done', { service }, ctx.profile.labels);
     return {
-        result: (result) => guardResult(result, inputs),
-        failure: (failure) => guardFailure(failure, inputs),
+        result: (result) => afterSignIn(note, guardResult(result, inputs)),
+        failure: (failure) => afterSignIn(note, guardFailure(failure, inputs)),
+        handlerEvents,
+        shown,
     };
 }
+/** A call the person signed in for tells the model so before what it read back. */
+function* afterSignIn(note, guarded) {
+    const read = yield* guarded;
+    const modelText = `${note}\n\n${formatToolResult(read.modelResult)}`;
+    return { ...read, modelResult: { ...read.modelResult, modelText } };
+}
 async function* runFunctionPreBodyStages(args) {
     const { tool, base, stages, guard } = args;
     const pre = yield* runPreToolPipeline(args);
@@ -305,7 +382,7 @@ async function* runFunctionPreBodyStages(args) {
         ...(pre.denied ? { denied: true } : {}),
     });
 }
-function makeReproject(parse, project, lexicon) {
+function makeReproject(parse, project, labels) {
     return (output) => {
         const checked = parse(output);
         if (!checked.success) {
@@ -314,7 +391,7 @@ function makeReproject(parse, project, lexicon) {
                 failure: {
                     code: 'invalid_output',
                     kind: 'bad_response',
-                    message: lexiconText('tool.output_invalid_after_mutate', {}, lexicon),
+                    message: labelText('tool.output_invalid_after_mutate', {}, labels),
                     details: checked.error.flatten(),
                 },
             };
@@ -333,31 +410,64 @@ async function* resolveFunctionSignIn(tool, ctx, base) {
     return {
         prepared: {
             authHeaders: resolved.headers,
+            ...(resolved.query ? { query: resolved.query } : {}),
             ...(resolved.audience ? { audience: resolved.audience } : {}),
         },
         ...(resolved.secret ? { secret: resolved.secret } : {}),
     };
 }
-export async function* executeFunction(tools, tool, rawInput, ctx, base, snapshot, stages) {
-    const guard = resultGuard(tool, ctx, snapshot, stages?.span);
+function functionHandlerFailure(error) {
+    return {
+        code: 'handler_error',
+        kind: error instanceof TheoremError ? error.kind : 'failed',
+        message: messageOf(error),
+    };
+}
+function waitsForPage(tool, ctx) {
+    return tool.answeredBy === 'page' && ctx.page === undefined && !ctx.pageExecution;
+}
+async function* receivePageAnswer(tool, ctx, claim, base) {
+    const execution = ctx.pageExecution;
+    if (tool.answeredBy !== 'page' || !execution)
+        return ctx;
+    if (!claim?.invocation)
+        throw operationUnavailable();
+    const argumentsForPage = jsonObjectSchema.parse(operationWireValue(claim.invocation.preparedInput));
+    const dispatch = await execution.dispatch(claim, ctx.signal);
+    throwIfAborted(ctx.signal);
+    if (!dispatch.grantId)
+        throw operationUnavailable();
+    yield toolEvent(base, {
+        phase: 'dispatch',
+        grantId: dispatch.grantId,
+        arguments: argumentsForPage,
+    });
+    ctx = { ...ctx, page: await dispatch.result };
+    throwIfAborted(ctx.signal);
+    return ctx;
+}
+export async function* executeFunction(tools, tool, rawInput, ctx, base, snapshot, stages, 
+/** Set when `tool` runs an agent tool: its trust, and its handler's failures and faults. */
+agent, beginBody) {
+    const guard = resultGuard(tools, agent ?? tool, ctx, snapshot, stages?.span);
     const callId = base.callId;
-    const parsed = yield* startToolExecution(tool, rawInput, ctx, base);
+    const parsed = startToolExecution(tool, rawInput, ctx);
     if (!parsed.ok) {
-        return yield* settleToolFailure(guard, base, {
-            code: 'invalid_input',
-            kind: 'bad_response',
-            message: lexiconText('tool.input_invalid', {}, ctx.profile.lexicon),
-        }, stages, { toolName: tool.name, callId, callNotStarted: true });
+        return yield* settleToolFailure(guard, base, parsed.failure, stages, {
+            toolName: tool.name,
+            callId,
+            callNotStarted: true,
+        });
     }
     let input = parsed.data;
-    const permissionGate = checkPermission(tool.name, tool.permission, ctx.sessionPermissions, ctx.resume);
+    const permissionGate = checkPermission(tool.name, tool.permission, ctx.sessionPermissions, ctx.resume, gateDetails(tool, input));
     if (permissionGate) {
         yield* emitGateSettlement({
             base,
             gate: permissionGate,
             callId,
             toolName: tool.name,
-            lexicon: ctx.profile.lexicon,
+            labels: ctx.profile.labels,
         });
         return { gated: permissionGate, callNotStarted: true };
     }
@@ -370,7 +480,7 @@ export async function* executeFunction(tools, tool, rawInput, ctx, base, snapsho
         safeInput: input,
         stages,
         guard,
-        lexicon: ctx.profile.lexicon,
+        labels: ctx.profile.labels,
     });
     const signedIn = yield* resolveFunctionSignIn(tool, ctx, base);
     if (signedIn.outcome)
@@ -380,7 +490,21 @@ export async function* executeFunction(tools, tool, rawInput, ctx, base, snapsho
         return preBody;
     }
     input = preBody.input;
+    if (waitsForPage(tool, ctx)) {
+        // why: Last of the checks, so the page is asked only for a call every guardrail and gate let through.
+        const gate = { kind: 'page', tool: tool.name, ...gateDetails(tool, input) };
+        yield* emitGateSettlement({
+            base,
+            gate,
+            callId,
+            toolName: tool.name,
+            labels: ctx.profile.labels,
+        });
+        return { gated: gate, callNotStarted: true };
+    }
     throwIfAborted(ctx.signal);
+    const claim = yield* dispatchToolBody(tool, input, ctx, base, beginBody);
+    ctx = yield* receivePageAnswer(tool, ctx, claim, base);
     const { secret } = signedIn;
     const fail = (failure) => settleToolFailure(guard, base, secret ? failureWithoutSecret(failure, secret) : failure, stages, { toolName: tool.name, callId, input });
     const checks = requestChecks(stages?.span);
@@ -389,13 +513,20 @@ export async function* executeFunction(tools, tool, rawInput, ctx, base, snapsho
         : ctx;
     let output;
     try {
-        output = yield* runHandler(tool.handler, input, handlerCtx, base);
+        const shown = new HandlerEvents(base, guard.handlerEvents(stages?.drafts === true));
+        output = yield* runHandler(tool.handler, input, handlerCtx, shown);
         checks.record();
     }
     catch (err) {
+        if (agent) {
+            // why: Anything but a settled failure is the host's to fix, as a compactor's is.
+            if (err instanceof AgentCallFailed)
+                return yield* fail(err.failure);
+            throw err;
+        }
         if (signedIn.prepared && err instanceof CredentialRefusedError) {
             checks.record();
-            const refused = yield* refusedCredentialOutcome(tool, err.refusal, signedIn.prepared.authHeaders, ctx, base);
+            const refused = yield* refusedCredentialOutcome(tool, err.refusal, signedIn.secret !== undefined, ctx, base);
             if (refused)
                 return yield* settleOutcome(refused);
         }
@@ -404,7 +535,7 @@ export async function* executeFunction(tools, tool, rawInput, ctx, base, snapsho
             checks.record(blocked);
             return yield* fail(yield* networkBlocked(err, blocked));
         }
-        return yield* fail({ code: 'handler_error', kind: 'failed', message: messageOf(err) });
+        return yield* fail(functionHandlerFailure(err));
     }
     if (secret)
         output = omitSecret(output, secret);
@@ -412,7 +543,7 @@ export async function* executeFunction(tools, tool, rawInput, ctx, base, snapsho
         return yield* fail({
             code: 'invalid_output',
             kind: 'bad_response',
-            message: lexiconText('tool.handler_no_output', {}, ctx.profile.lexicon),
+            message: labelText('tool.handler_no_output', {}, ctx.profile.labels),
         });
     }
     const checked = tool.output.safeParse(output);
@@ -420,7 +551,7 @@ export async function* executeFunction(tools, tool, rawInput, ctx, base, snapsho
         return yield* fail({
             code: 'invalid_output',
             kind: 'bad_response',
-            message: lexiconText('tool.output_invalid', {}, ctx.profile.lexicon),
+            message: labelText('tool.output_invalid', {}, ctx.profile.labels),
             details: checked.error.flatten(),
         });
     }
@@ -428,7 +559,7 @@ export async function* executeFunction(tools, tool, rawInput, ctx, base, snapsho
     if (!promoted.ok) {
         return yield* fail(promoted.failure);
     }
-    // The T2 loader's output drives the snapshot, so the host may not mutate it.
+    // why: The T2 loader's output drives the snapshot, so the host may not mutate it.
     const ownsOutput = loadsT2(tool, ctx);
     return yield* settleToolCall({
         base,
@@ -439,25 +570,24 @@ export async function* executeFunction(tools, tool, rawInput, ctx, base, snapsho
         guard,
         provisional: {
             outputRaw: promoted.output,
-            modelResult: projectForModel(tool, promoted.output, ctx.profile.lexicon),
+            modelResult: projectForModel(tool, promoted.output, ctx.profile.labels),
         },
         sources: tool.sources,
         labels: tool.labels,
         ...(ownsOutput
             ? {}
             : {
-                reproject: makeReproject((v) => tool.output.safeParse(v), (data) => projectForModel(tool, data, ctx.profile.lexicon), ctx.profile.lexicon),
+                reproject: makeReproject((v) => tool.output.safeParse(v), (data) => projectForModel(tool, data, ctx.profile.labels), ctx.profile.labels),
             }),
     });
 }
-export function notLoadedMessage(tool, lexicon) {
-    if (tool.loadTier === 'T1') {
-        return lexiconText('tool.not_wired_t1', { tool: tool.name }, lexicon);
-    }
-    if (tool.loadTier === 'T2') {
-        return lexiconText('tool.not_loaded_t2', { tool: tool.name }, lexicon);
+/** Names the profile's loader when it can load the tool, so the model knows which call comes first. */
+export function notLoadedMessage(tool, profile) {
+    const loader = profileToolsSpec(profile)?.t2Loader;
+    if (tool.loadTier === 'T2' && loader) {
+        return labelText('tool.not_loaded_t2', { tool: tool.name, loader }, profile.labels);
     }
-    return lexiconText('tool.not_visible', { tool: tool.name }, lexicon);
+    return labelText('tool.not_visible', { tool: tool.name }, profile.labels);
 }
 function earlyFailure(failure) {
     return { failure, callNotStarted: true, modelResult: formatToolFailureForModel(failure) };
@@ -469,7 +599,7 @@ export async function* executeBuiltin(tool, ctx, base, snapshot) {
         const failure = {
             code: 'not_loaded',
             kind: 'request',
-            message: lexiconText('tool.builtin_not_enabled', { tool: tool.name }, ctx.profile.lexicon),
+            message: labelText('tool.builtin_not_enabled', { tool: tool.name }, ctx.profile.labels),
         };
         yield failureEvent(base, failure);
         return earlyFailure(failure);
@@ -477,7 +607,7 @@ export async function* executeBuiltin(tool, ctx, base, snapshot) {
     const failure = {
         code: 'provider_native',
         kind: 'request',
-        message: lexiconText('tool.provider_native', { tool: tool.name }, ctx.profile.lexicon),
+        message: labelText('tool.provider_native', { tool: tool.name }, ctx.profile.labels),
     };
     yield failureEvent(base, failure);
     return earlyFailure(failure);
@@ -488,7 +618,7 @@ function registeredEligibilityFailure(args) {
         return {
             code: 'not_allowed',
             kind: 'blocked',
-            message: lexiconText('tool.not_allowed', { tool: name, profile: profile.id }, profile.lexicon),
+            message: labelText('tool.not_allowed', { tool: name, profile: profile.id }, profile.labels),
         };
     }
     if (!snapshot)
@@ -498,24 +628,46 @@ function registeredEligibilityFailure(args) {
         return {
             code: 'not_gated',
             kind: 'request',
-            message: lexiconText('tool.not_eligible', { tool: name }, profile.lexicon),
+            message: labelText('tool.not_eligible', { tool: name }, profile.labels),
         };
     }
-    if (!snapshot.visible.includes(name)) {
+    if (!(args.visible ?? snapshot.visible).includes(name)) {
         const skipLoadCheck = continuing && tool.loadTier === 'T0';
         if (!skipLoadCheck) {
             return {
                 code: 'not_loaded',
                 kind: 'request',
-                message: notLoadedMessage(tool, profile.lexicon),
+                message: notLoadedMessage(tool, profile),
             };
         }
     }
     return undefined;
 }
+export function authorizeToolReplay(args) {
+    const tool = args.tools.get(args.name);
+    if (!tool || tool.type === 'builtin') {
+        throw new TheoremError('blocked', labelText('error.blocked'));
+    }
+    const failure = registeredEligibilityFailure({ ...args, tool });
+    if (failure)
+        throw new TheoremError(failure.kind, failure.message);
+    if (args.outcome)
+        authorizeSavedDisclosure(args, tool, args.outcome);
+}
+function authorizeSavedDisclosure(args, tool, outcome) {
+    const blocked = () => new TheoremError('blocked', labelText('detect.output_blocked', {}, args.profile.labels));
+    const result = outcome.replay.modelResult;
+    if (tool.type === 'function' &&
+        tool.exposeToModel === false &&
+        result?.finding !== labelText('tool.completed_hidden', {}, args.profile.labels))
+        throw blocked();
+    const guard = guardToolResult(outcome.event.tool.readBack ?? '', { event: outcome.event, output: outcome.replay.outputRaw }, provenanceFor(tool, args.tools), resolveGuardrailPolicy(args.profile.guardrails), tool.type === 'builtin' ? undefined : toolBoundary('tool_output', tool.type), args.snapshot?.executable ?? [], args.profile.labels);
+    if (guard.event?.action === 'block' || guard.event?.action === 'redact')
+        throw blocked();
+}
 /** Settles an outcome the kernel reached without a handler's own result: a remote body, or a sign-in. */
 async function* settleBodyOutcome(args) {
-    const { outcome, tool, base, callId, safeInput, stages, guard, lexicon } = args;
+    const { outcome, tool, base, callId, safeInput, stages, guard, labels } = args;
     const name = tool.name;
     if (outcome.kind === 'gated') {
         if (outcome.gate.kind === 'confirmation') {
@@ -526,7 +678,7 @@ async function* settleBodyOutcome(args) {
             gate: outcome.gate,
             callId,
             toolName: name,
-            lexicon,
+            labels,
         });
         return { gated: outcome.gate, callNotStarted: true, ...(gateReadBack ? { gateReadBack } : {}) };
     }
@@ -553,8 +705,8 @@ async function* settleBodyOutcome(args) {
         sources: tool.sources,
         labels: tool.labels,
         reproject: makeReproject((v) => parseToolOutput(tool.output, v), 
-        // A hook's edit replaces the value; the media the tool returned stays.
-        (data) => withMedia(modelResultFromOutput(data), outcome.modelResult.parts), lexicon),
+        // why: A hook's edit replaces the value; the media the tool returned stays.
+        (data) => withMedia(modelResultFromOutput(data), outcome.modelResult.parts), labels),
     });
 }
 function turnReadBack({ modelResult }) {
@@ -562,9 +714,9 @@ function turnReadBack({ modelResult }) {
         ? { text: formatToolResult(modelResult), parts: modelResult.parts }
         : undefined;
 }
-/** The service a refused sign-in names, from the tool's own auth config. */
-function refusedSignInService(tool, resume) {
-    if (!resume?.signIn || tool.type === 'builtin')
+/** The service a sign-in gate's answer names, from the tool's own auth config. */
+function signInService(tool, resume) {
+    if (!resume?.signIn || tool.type === 'builtin' || tool.type === 'agent')
         return undefined;
     return tool.auth?.service;
 }
@@ -572,34 +724,34 @@ function refusedSignInService(tool, resume) {
  * A gate nobody answered: a sign-in for `expiredService` whose link expired, or any other gate
  * left behind. Both settle as `cancelled`.
  */
-export function lapsedGateFailure(toolName, expiredService, lexicon) {
+export function lapsedGateFailure(toolName, expiredService, labels) {
     if (expiredService) {
         return {
             code: 'expired',
             kind: 'cancelled',
-            message: lexiconText('sign_in.expired', { service: expiredService }, lexicon),
+            message: labelText('sign_in.expired', { service: expiredService }, labels),
         };
     }
     return {
         code: 'cancelled',
         kind: 'cancelled',
-        message: lexiconText('session.abandon_gated', { tool: toolName }, lexicon),
+        message: labelText('session.abandon_gated', { tool: toolName }, labels),
     };
 }
 /** `abandoned` and `expired` settle as `cancelled`. */
-function refusalFailure(tool, resume, lexicon) {
-    const service = refusedSignInService(tool, resume);
+function refusalFailure(tool, resume, labels) {
+    const service = signInService(tool, resume);
     const cause = resume?.cause ?? 'declined';
     if (cause === 'declined') {
         return {
             code: 'denied',
             kind: 'declined',
             message: service
-                ? lexiconText('sign_in.declined', { service }, lexicon)
-                : lexiconText('session.tool_denied', { tool: tool.name }, lexicon),
+                ? labelText('sign_in.declined', { service }, labels)
+                : labelText('session.tool_denied', { tool: tool.name }, labels),
         };
     }
-    return lapsedGateFailure(tool.name, cause === 'expired' ? service : undefined, lexicon);
+    return lapsedGateFailure(tool.name, cause === 'expired' ? service : undefined, labels);
 }
 function resumeApproval(resume) {
     if (isGateResumeGranted(resume))
@@ -629,7 +781,53 @@ function toolCallEnd(settlement, readBack) {
         ...(failure ? { failure } : {}),
     };
 }
+/** 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 function shownToolArguments(call) {
+    const tool = call.tools.get(call.name);
+    const policy = resolveGuardrailPolicy(call.profile.guardrails);
+    const inspected = inspectToolArguments(plainToolInput(call.input), tool ? provenanceFor(tool, call.tools) : { origin: 'local', tool: call.name, depth: 1 }, policy, toolArgumentsBoundary(call.tools, call.name), scopeOf(policy, call.scope ?? {}));
+    const { args } = inspected;
+    return args !== null && typeof args === 'object' && !Array.isArray(args)
+        ? args
+        : {};
+}
 export async function* executeRegisteredTool(args) {
+    args = {
+        ...args,
+        ctx: { ...args.ctx, operationId: args.ctx.operationId ?? crypto.randomUUID() },
+    };
+    return yield* coordinateTool(args.execution, {
+        operationId: args.ctx.operationId ?? crypto.randomUUID(),
+        callId: args.callId,
+        profileId: args.profile.id,
+        toolId: args.name,
+    }, {
+        input: args.input,
+        resume: args.ctx.resume,
+        snapshot: args.snapshot,
+        context: args.invocation,
+    }, args.ctx.signal, (beginBody) => executeTracedTool({
+        ...args,
+        beginBody: async (input) => {
+            const claim = (await beginBody?.(input)) ?? (await args.beginBody?.(input));
+            args.onDispatch?.();
+            return claim;
+        },
+    }), (outcome) => authorizeToolReplay({
+        outcome,
+        tools: args.tools,
+        profile: args.profile,
+        name: args.name,
+        resume: args.ctx.resume,
+        snapshot: args.snapshot,
+    }));
+}
+async function* executeTracedTool(args) {
     const tool = args.tools.get(args.name);
     if (!args.openSpan) {
         return yield* runRegisteredTool(args, tool);
@@ -638,7 +836,7 @@ export async function* executeRegisteredTool(args) {
         name: args.name,
         callId: args.callId,
         call: { arguments: toolCallArguments(plainToolInput(args.input)) },
-        origin: tool ? originOfTool(tool.type) : undefined,
+        origin: tool ? originOfTool(tool, args.tools) : undefined,
         permission: tool && 'permission' in tool ? tool.permission : undefined,
         approved: resumeApproval(args.ctx.resume),
         step: args.ctx.turn?.step,
@@ -664,7 +862,7 @@ export async function* executeRegisteredTool(args) {
         throw err;
     }
     finally {
-        // The host stopped reading mid-call.
+        // why: The host stopped reading mid-call.
         if (!trace.span.ended) {
             trace.end({ outcome: 'cancelled' });
             await exec.return({});
@@ -674,12 +872,18 @@ export async function* executeRegisteredTool(args) {
 async function* runRegisteredTool(args, tool) {
     const { profile, name, input, callId, ctx, snapshot, stages } = args;
     const safeInput = plainToolInput(input);
-    const base = { name, callId };
+    const operationId = ctx.operationId ?? crypto.randomUUID();
+    const base = {
+        name,
+        callId,
+        operationId,
+        activityFailed: failedActivity(name, profile.labels, tool?.labels, safeInput),
+    };
     if (!tool) {
         const failure = {
             code: 'unknown_tool',
             kind: 'request',
-            message: lexiconText('tool.not_registered', { tool: name }, profile.lexicon),
+            message: labelText('tool.not_registered', { tool: name }, profile.labels),
         };
         yield failureEvent(base, failure);
         return earlyFailure(failure);
@@ -689,12 +893,12 @@ async function* runRegisteredTool(args, tool) {
             const failure = {
                 code: 'provider_native',
                 kind: 'request',
-                message: lexiconText('tool.builtin_needs_snapshot', { tool: name }, profile.lexicon),
+                message: labelText('tool.builtin_needs_snapshot', { tool: name }, profile.labels),
             };
             yield failureEvent(base, failure);
             return earlyFailure(failure);
         }
-        const fullCtx = { ...ctx, callId, profile };
+        const fullCtx = { ...ctx, callId, profile, operationId };
         return yield* executeBuiltin(tool, fullCtx, base, snapshot);
     }
     const eligibility = registeredEligibilityFailure({
@@ -703,25 +907,36 @@ async function* runRegisteredTool(args, tool) {
         name,
         resume: ctx.resume,
         snapshot,
+        visible: ctx.turn?.visible,
     });
     if (eligibility) {
         yield failureEvent(base, eligibility);
         return earlyFailure(eligibility);
     }
     if (isGateResumeDenied(ctx.resume)) {
-        return yield* settleToolFailure(resultGuard(tool, { ...ctx, callId, profile }, snapshot, stages?.span), base, refusalFailure(tool, ctx.resume, profile.lexicon), stages, { toolName: name, callId, input: safeInput, callNotStarted: true, denied: true });
+        return yield* settleToolFailure(resultGuard(args.tools, tool, { ...ctx, callId, profile, operationId }, snapshot, stages?.span), base, refusalFailure(tool, ctx.resume, profile.labels), stages, { toolName: name, callId, input: safeInput, callNotStarted: true, denied: true });
     }
-    const fullCtx = { ...ctx, callId, profile };
+    const fullCtx = { ...ctx, callId, profile, operationId };
     const policy = resolveGuardrailPolicy(profile.guardrails);
-    const provenance = provenanceFor(tool);
+    const provenance = provenanceFor(tool, args.tools);
     const argsStart = performance.now();
-    const argEvent = toolCallEvent(inspectToolArguments(safeInput, policy), provenance);
-    recordToolCheck(stages?.span, 'tool_arguments', performance.now() - argsStart, argEvent);
-    if (argEvent) {
-        yield { type: 'guardrail', guardrail: argEvent };
+    const kind = toolKindOf(tool);
+    const inspected = inspectToolArguments(safeInput, provenance, policy, kind && toolBoundary('tool_arguments', kind), scopeOf(policy, args.scope ?? {}));
+    recordToolCheck(stages?.span, 'tool_arguments', performance.now() - argsStart, inspected.event);
+    if (inspected.event) {
+        yield { type: 'guardrail', guardrail: inspected.event };
+    }
+    if (!('args' in inspected)) {
+        const failure = {
+            code: 'arguments_blocked',
+            kind: 'blocked',
+            message: labelText('detect.call_blocked', {}, profile.labels),
+        };
+        yield failureEvent(base, failure);
+        return { ...earlyFailure(failure), denied: true };
     }
     const taintStart = performance.now();
-    const taintVerdict = checkTaintGate(ctx.turn?.taint, tool.access, policy, profile.lexicon);
+    const taintVerdict = checkTaintGate(ctx.turn?.taint, tool.access, policy, profile.labels);
     const taintEvent = toolCallEvent(taintVerdict, provenance);
     recordToolCheck(stages?.span, 'taint', performance.now() - taintStart, taintEvent);
     if (taintEvent) {
@@ -736,23 +951,155 @@ async function* runRegisteredTool(args, tool) {
         yield failureEvent(base, failure);
         return { ...earlyFailure(failure), denied: true };
     }
-    return yield* settleByType(args.tools, tool, safeInput, fullCtx, base, snapshot, stages);
+    const stopped = yield* settleRemoteDestination({
+        tool,
+        input: inspected.args,
+        ctx: fullCtx,
+        base,
+        provenance,
+        policy,
+        span: stages?.span,
+    });
+    if (stopped)
+        return stopped;
+    return yield* settleByType(args.tools, tool, inspected.args, fullCtx, base, snapshot, stages, args.agents, args.beginBody);
+}
+/** The call's settlement when a destination in its arguments stops it: refused, or held for the user's answer. */
+async function* settleRemoteDestination(args) {
+    const { tool, input, ctx, base } = args;
+    const { labels } = ctx.profile;
+    const start = performance.now();
+    const { verdict, confirm } = checkDestinationGate(ctx.turn?.destinations, input, args.policy, labels);
+    const event = toolCallEvent(verdict, args.provenance);
+    recordToolCheck(args.span, 'destination', performance.now() - start, event);
+    if (event) {
+        yield { type: 'guardrail', guardrail: event };
+    }
+    if (verdict.action === 'block') {
+        const failure = {
+            code: 'remote_destination',
+            kind: 'blocked',
+            message: verdict.rejection,
+        };
+        yield failureEvent(base, failure);
+        return { ...earlyFailure(failure), denied: true };
+    }
+    if (!confirm || isGateResumeGranted(ctx.resume))
+        return undefined;
+    const gate = {
+        kind: 'confirmation',
+        tool: tool.name,
+        summary: confirm,
+        ...gateDetails(tool, input),
+    };
+    yield* emitGateSettlement({
+        base,
+        gate,
+        callId: ctx.callId,
+        toolName: tool.name,
+        labels,
+    });
+    return { gated: gate, callNotStarted: true };
+}
+/**
+ * An agent tool runs as a function tool whose handler is the called agent's
+ * turn, so input checks, gates, stages, and the result guard are the same. The
+ * agent's reply streams as the call's drafts and its other events as its
+ * `progress`, and its usage rides on the call's last phase.
+ */
+async function* executeAgentTool(args) {
+    const { tool, ctx, base, agents } = args;
+    if (!agents) {
+        const failure = {
+            code: 'unknown_tool',
+            kind: 'unsupported',
+            message: labelText('tool.unsupported_type', { tool: tool.name }, ctx.profile.labels),
+        };
+        yield failureEvent(base, failure);
+        return earlyFailure(failure);
+    }
+    let tokens;
+    const span = args.stages?.span;
+    const handler = async function* (input, handlerCtx) {
+        const run = agents.run({
+            tool,
+            callId: handlerCtx.callId,
+            // why: Checked against the tool's input schema before the handler runs.
+            input: input,
+            caller: handlerCtx.profile,
+            ...(span ? { span } : {}),
+            ...(handlerCtx.signal ? { signal: handlerCtx.signal } : {}),
+        });
+        // why: A retry throws away the reply drafted so far; the drafts stop there, and the output arrives whole.
+        let retried = false;
+        for (;;) {
+            const next = await run.next();
+            if (next.done) {
+                tokens = next.value.tokens;
+                if ('failure' in next.value)
+                    throw new AgentCallFailed(next.value.failure);
+                yield { kind: 'complete', output: next.value.output };
+                return;
+            }
+            const event = next.value;
+            if (event.type === 'attempt')
+                retried = true;
+            if (event.type === 'text' || event.type === 'structured_draft') {
+                if (!retried)
+                    yield { kind: 'draft', text: event.text };
+                continue;
+            }
+            yield { kind: 'progress', data: { agent: tool.profile, event } };
+        }
+    };
+    // why: Its hooks take `AgentToolInput`, which the input schema has already checked.
+    const asFunction = { ...tool, type: 'function', handler };
+    const exec = executeFunction(args.tools, asFunction, args.safeInput, ctx, base, args.snapshot, args.stages, tool, args.beginBody);
+    for (;;) {
+        const next = await exec.next();
+        if (next.done)
+            return next.value;
+        yield withAgentTokens(next.value, base.callId, tokens);
+    }
+}
+/** The called agent's usage on the call's `complete` or `error` phase. */
+function withAgentTokens(event, callId, tokens) {
+    if (!tokens || event.type !== 'tool' || event.tool.callId !== callId)
+        return event;
+    const { tool } = event;
+    if (tool.phase !== 'complete' && tool.phase !== 'error')
+        return event;
+    return { ...event, tool: { ...tool, tokens } };
 }
-async function* settleByType(tools, tool, safeInput, fullCtx, base, snapshot, stages) {
+async function* settleByType(tools, tool, safeInput, fullCtx, base, snapshot, stages, agents, beginBody) {
     const { name } = tool;
     if (tool.type === 'function') {
-        return yield* executeFunction(tools, tool, safeInput, fullCtx, base, snapshot, stages);
+        return yield* executeFunction(tools, tool, safeInput, fullCtx, base, snapshot, stages, undefined, beginBody);
+    }
+    if (tool.type === 'agent') {
+        return yield* executeAgentTool({
+            tools,
+            tool,
+            safeInput,
+            ctx: fullCtx,
+            base,
+            snapshot,
+            stages,
+            agents,
+            beginBody,
+        });
     }
     if (tool.type !== 'http' && tool.type !== 'mcp') {
         return earlyFailure({
             code: 'unknown_tool',
             kind: 'request',
-            message: lexiconText('tool.unsupported_type', { tool: name }, fullCtx.profile.lexicon),
+            message: labelText('tool.unsupported_type', { tool: name }, fullCtx.profile.labels),
         });
     }
+    const guard = resultGuard(tools, tool, fullCtx, snapshot, stages?.span);
     const remoteOutcome = tool.type === 'http'
-        ? yield* executeHttpTool(tool, safeInput, fullCtx, base, stages)
-        : yield* executeMcpTool(tool, safeInput, fullCtx, base, stages, tools.mcpSessions);
+        ? yield* executeHttpTool(tool, safeInput, fullCtx, base, stages, beginBody, new HandlerEvents(base, guard.handlerEvents(stages?.drafts === true)))
+        : yield* executeMcpTool(tool, safeInput, fullCtx, base, stages, tools.mcpSessions, beginBody);
     return yield* settleBodyOutcome({
         outcome: remoteOutcome,
         tool,
@@ -760,37 +1107,62 @@ async function* settleByType(tools, tool, safeInput, fullCtx, base, snapshot, st
         callId: base.callId,
         safeInput,
         stages,
-        guard: resultGuard(tool, fullCtx, snapshot, stages?.span),
-        lexicon: fullCtx.profile.lexicon,
+        guard,
+        labels: fullCtx.profile.labels,
     });
 }
 /**
- * A failure's message is redacted under full detection, whatever the profile
- * enables: the kernel frames it for the model as a system report, and a remote
- * server writes its own error strings. What it changed is a decision like any
- * other, reported and timed; the framed message is then guarded as a result.
+ * A remote server writes its own error strings, so a failure's message is read
+ * at `tool_failure_<kind>` before the kernel frames it for the model as a system
+ * report. A blocked message is replaced by the labels' words. The framed
+ * report is the kernel's own text and is not read again.
  */
 function* guardFailure(failure, guard) {
     const start = performance.now();
-    const checked = guardToolFailureText(failure.message, guard.provenance, {
-        ...guard.policy,
-        sanitizeInput: true,
-        redactSensitive: resolveSensitive(true),
-    });
+    const checked = guardToolFailureText(failure.message, guard.provenance, guard.policy, guard.kind && toolBoundary('tool_failure', guard.kind));
     recordToolCheck(guard.span, 'tool_failure', performance.now() - start, checked.event);
     if (checked.event) {
         yield { type: 'guardrail', guardrail: checked.event };
     }
-    return yield* guardResult(formatToolFailureForModel({ ...failure, message: checked.text }), guard);
+    const message = checked.text ?? labelText('detect.output_blocked', {}, guard.labels);
+    return { modelResult: yield* reportFailure({ ...failure, message }, guard) };
 }
+/** A failure framed for the model in the kernel's own words, fenced and labelled like any result. */
+function* reportFailure(failure, guard) {
+    const framed = frameToolFailure(failure);
+    return (yield* readBack(framed, guard, undefined)) ?? framed;
+}
+/** A result read at `tool_output_<kind>`. A blocked one settles as a failed call the model is told about. */
 function* guardResult(result, guard) {
+    const read = yield* readBack(result, guard, guard.kind && toolBoundary('tool_output', guard.kind));
+    if (read)
+        return { modelResult: read };
+    const withheld = {
+        code: 'output_blocked',
+        kind: 'blocked',
+        message: labelText('detect.output_blocked', {}, guard.labels),
+    };
+    return { modelResult: yield* reportFailure(withheld, guard), withheld };
+}
+/** What the person is shown of `value`, read at `tool_shown_<kind>`; a blocked one is the labels' words. */
+function* showValue(value, guard) {
+    const boundary = guard.kind && toolBoundary('tool_shown', guard.kind);
+    const shown = guardShownValue(value, guard.provenance, guard.policy, boundary);
+    if (shown.event)
+        yield { type: 'guardrail', guardrail: shown.event };
+    return 'value' in shown ? shown.value : labelText('detect.shown_blocked', {}, guard.labels);
+}
+/** What the model reads of `result`, or `undefined` when a match at `boundary` blocks it. */
+function* readBack(result, guard, boundary) {
     const { provenance, span } = guard;
     const start = performance.now();
-    const guarded = guardToolResult(result.finding, result.data, provenance, guard.policy, guard.callableTools, guard.lexicon);
+    const guarded = guardToolResult(result.finding, result.data, provenance, guard.policy, boundary, guard.callableTools, guard.labels);
     recordToolCheck(span, 'tool_result', performance.now() - start, guarded.event);
     if (guarded.event) {
         yield { type: 'guardrail', guardrail: guarded.event };
     }
+    if (guarded.text === undefined)
+        return undefined;
     return {
         ...result,
         modelText: guarded.text,