@theoremjs/agents 0.3.0 → 0.3.1

package/esm/src/kernel/engine/runner/mod.js

@@ -1,7 +1,7 @@
-import { canaryNote, userDataNote } from '../../../guardrails/canary.js';
-import { isAbortError, TheoremError, throwIfAborted, withPublicWording, } from '../../../guardrails/error.js';
+import { canaryNote, contextNote, profileCanary, userDataNote, } from '../../../guardrails/canary.js';
+import { isAbortError, TheoremError, throwIfAborted, withPublicLabels, } from '../../../guardrails/error.js';
 import { projectGuardrailTurnEvent } from '../../../guardrails/events.js';
-import { lexiconText } from '../../../guardrails/lexicon.js';
+import { labelText } from '../../../guardrails/labels.js';
 import { sanitizeTurnRequestWithEvents } from '../../../guardrails/sanitize.js';
 import { resolveTraceWriter } from '../../../observability/policy.js';
 import { resolveObservabilityPolicy } from '../../../observability/resolve-policy.js';
@@ -9,17 +9,18 @@ import { writeTrace } from '../../../observability/trace.js';
 import { buildRecord } from '../../../observability/trace-record.js';
 import { startTrace, traceContent, } from '../../../observability/trace-span.js';
 import { profileTypesForField } from '../../profile-scope.js';
-import { requireModelBinding } from '../../registry/catalog.js';
+import { hostAgentModel, nestedTurnModel } from '../../provider-dispatch.js';
+import { profileInputs, requireModelBinding } from '../../registry/catalog.js';
 import { resolveTurnInRegistry } from '../../registry/resolve.js';
 import { bindSystem } from '../../system-parts.js';
 import { cloneTurnToolSnapshot, expandT1Policy } from '../../tools/resolve.js';
-import { turnDoneOf } from '../../turn-events.js';
+import { keptReply, turnDoneOf } from '../../turn-events.js';
 import { findLast } from '../../util/find-last.js';
 import { compactionMeter, compactionResult, compactorHistory, resolveCompactionTokens, shouldCompact, splitForCompaction, } from '../compaction.js';
-import { mediaTokenFamily } from '../token-estimate.js';
 import { endThrownSpan, endTurnSpan, guardrailAttributes, guardrailCheckAttributes, OutputFold, turnSpanOptions, } from '../turn-trace.js';
-import { sumEventTokens } from '../usage.js';
+import { sumEventTokens, sumTurnTokens } from '../usage.js';
 import { runAttemptsWithValidation } from './gates.js';
+import { createAgentCaller, NESTED_THROWS, turnError } from './nested.js';
 import { applyTurnStage } from './stages.js';
 import { openTurnState } from './state.js';
 import { shouldSkipStreamEvent } from './stream.js';
@@ -32,8 +33,8 @@ const MS_PER_S = 1000;
  * through here, so it is where an error gets the user's wording.
  */
 function deliver(ctx, event) {
-    const out = withPublicWording(event, ctx.known?.lexicon);
-    if (out.type === 'text' && !ctx.shownText) {
+    const out = withPublicLabels(event, ctx.known?.labels);
+    if ((out.type === 'text' || out.type === 'structured_draft') && !ctx.shownText) {
         ctx.shownText = true;
         ctx.root.set({ 'theorem.turn.time_to_first_text': ctx.root.msSinceStart() / MS_PER_S });
     }
@@ -50,19 +51,27 @@ function* emitObservedStage(ctx, stageEv, profile) {
 function getCompactionSpec(profile, modelId) {
     return profile.models[modelId]?.compaction;
 }
-/** Errors only the host can fix: the compactor throws them rather than failing quietly every turn. */
 /** A turn's tools when it offers none: an agent summarising its own history. */
 function noTools() {
     return { builtins: [], gated: [], visible: [], executable: [], wire: [] };
 }
-const COMPACTOR_THROWS = new Set(['config', 'request', 'auth', 'internal']);
-function turnError(events) {
-    return events.find((e) => e.type === 'error');
+/**
+ * Run `req` as a turn under `parent`: its spans join that record, it writes
+ * none of its own, and it shares the record's canaries. A compactor's turn and
+ * an agent tool's call both run here.
+ */
+function runNestedTurn(args) {
+    const ctx = newTraceCtx(args.registry, args.req, args.parent.child(`invoke_agent ${args.req.profile}`, turnSpanOptions(args.req)), args.canaries);
+    ctx.agentDepth = args.agentDepth;
+    if (args.compacting)
+        ctx.compacting = args.compacting;
+    ctx.observability = resolveObservabilityPolicy(ctx.known?.observability);
+    return runTracedTurn(ctx, nestedTurnModel(args.provider, args.req.profile, args.req.model, args.req));
 }
 /**
  * Run the compaction profile as a turn under `span`: its spans join that
  * record and it writes none of its own. Anything short of a completed,
- * non-empty summary is a failure; the host's abort and `COMPACTOR_THROWS`
+ * non-empty summary is a failure; the host's abort and `NESTED_THROWS`
  * errors are thrown. With no `spec.profile` the owner compacts itself, on the
  * model it is compacting for and with no tools.
  */
@@ -75,24 +84,29 @@ async function runCompactor(args) {
         return { droppedMedia, failure: { unreadable: true } };
     const req = {
         profile: compactorId,
-        // The turn already passed model selection; its default needs no naming.
+        // why: The turn already passed model selection; its default needs no naming.
         ...(self && args.model !== compactor.defaultModel ? { model: args.model } : {}),
-        input: { text: lexiconText('compaction.request', {}, compactor.lexicon), history },
+        input: { text: labelText('compaction.request', {}, compactor.labels), history },
         signal: args.signal,
     };
-    const ctx = newTraceCtx(args.registry, req, args.parent.child(`invoke_agent ${req.profile}`, turnSpanOptions(req)), args.canaries);
-    ctx.compacting = self ? 'self' : 'other';
-    ctx.observability = resolveObservabilityPolicy(ctx.known?.observability);
     const events = [];
     try {
-        for await (const event of runTracedTurn(ctx, args.provider)) {
+        for await (const event of runNestedTurn({
+            registry: args.registry,
+            req,
+            provider: args.provider,
+            parent: args.parent,
+            canaries: args.canaries,
+            agentDepth: 0,
+            compacting: self ? 'self' : 'other',
+        })) {
             events.push(event);
         }
     }
     catch (err) {
         throwIfAborted(args.signal);
         const error = err instanceof TheoremError ? err.kind : 'internal';
-        if (COMPACTOR_THROWS.has(error))
+        if (NESTED_THROWS.has(error))
             throw err;
         return { droppedMedia, failure: { error } };
     }
@@ -101,7 +115,7 @@ async function runCompactor(args) {
     const usage = tokens ? { tokens } : {};
     const stop = findLast(events, (e) => e.type === 'done')?.stop.kind;
     const reported = turnError(events);
-    if (reported && COMPACTOR_THROWS.has(reported.errorKind)) {
+    if (reported && NESTED_THROWS.has(reported.errorKind)) {
         throw new TheoremError(reported.errorKind, `Compactor '${compactorId}' failed: ${reported.errorInternal ?? reported.error}`);
     }
     const error = reported?.errorKind;
@@ -112,9 +126,10 @@ async function runCompactor(args) {
             ...usage,
         };
     }
-    const structured = findLast(events, (e) => e.type === 'structured')?.structured;
+    const reply = keptReply(events);
+    const structured = findLast(reply, (e) => e.type === 'structured')?.structured;
     const summary = structured === undefined
-        ? events.flatMap((e) => (e.type === 'text' ? [e.text] : [])).join('')
+        ? reply.flatMap((e) => (e.type === 'text' ? [e.text] : [])).join('')
         : JSON.stringify(structured);
     if (!summary.trim()) {
         return { droppedMedia, failure: { stop, empty: true }, ...usage };
@@ -157,7 +172,6 @@ async function compactHistoryBeforeTurn(args) {
     const decision = await resolveCompactionTokens({
         spec: args.spec,
         input: args.input,
-        family: args.family,
     });
     const needed = decision !== undefined && (await shouldCompact(decision, args.spec));
     const attributes = compactionDecision(args.spec, decision, needed);
@@ -165,7 +179,7 @@ async function compactHistoryBeforeTurn(args) {
         args.parent.event('theorem.compaction', attributes);
         return undefined;
     }
-    const split = await splitForCompaction(args.history, args.spec, args.family);
+    const split = await splitForCompaction(args.history, args.spec);
     if (split.toCompact.length === 0) {
         args.parent.event('theorem.compaction', attributes);
         return undefined;
@@ -195,7 +209,6 @@ async function attachAfterCompaction(event, args) {
         spec: args.spec,
         input: args.input,
         prompt,
-        family: args.family,
     });
     const needed = decision !== undefined && (await shouldCompact(decision, args.spec));
     args.span.event('theorem.compaction', compactionDecision(args.spec, decision, needed));
@@ -222,7 +235,7 @@ async function* emitTurn(args) {
         profile,
         generation,
         trace: args.trace,
-        mediaFamily: args.mediaFamily,
+        ...(args.agents ? { agents: args.agents } : {}),
     });
     args.outState.state = state;
     const pre = yield* applyTurnStage({
@@ -257,9 +270,14 @@ async function* emitTurn(args) {
         return;
     }
     yield* runAttemptsWithValidation(safe, profile, generation, system, provider, state);
-    const tokens = sumEventTokens(state.allEmittedEvents);
+    const tokens = sumTurnTokens(state.allEmittedEvents);
     const done = turnDoneOf({
         stop: state.lastStop ?? { kind: 'completed' },
+        ...(state.providerState &&
+            !('providerContinuation' in profile && profile.providerContinuation?.history === 'stateless') &&
+            (!state.lastStop || ['completed', 'tool', 'gate'].includes(state.lastStop.kind))
+            ? { providerState: state.providerState }
+            : {}),
         traceparent: state.trace.root.traceparent(),
         ...(tokens ? { tokens } : {}),
     }, cloneTurnToolSnapshot(generation.tools));
@@ -277,7 +295,7 @@ async function* streamTurnEvents(ctx, profile, gen, provider, compactionSpec) {
         system: ctx.system,
         provider,
         trace: ctx.trace,
-        mediaFamily: ctx.mediaFamily,
+        agents: ctx.agents,
         outState: ctx,
     })) {
         const attached = await maybeAttachAfter(event, ctx, gen, compactionSpec);
@@ -285,7 +303,7 @@ async function* streamTurnEvents(ctx, profile, gen, provider, compactionSpec) {
         if (!shouldSkipStreamEvent(out, profile))
             yield deliver(ctx, out);
         if (out.type === 'done' && ctx.state) {
-            // Skip duplicate post_turn when pre_turn abort already emitted it inside emitTurn.
+            // why: Skip duplicate post_turn when pre_turn abort already emitted it inside emitTurn.
             const alreadyPost = ctx.state.allEmittedEvents.some((e) => e.type === 'stage' && e.stage === 'post_turn');
             if (!alreadyPost) {
                 for await (const stageEv of applyTurnStage({
@@ -314,6 +332,7 @@ function newTraceCtx(registry, req, root, canaries) {
         delivered: new OutputFold(),
         root,
         compacting: false,
+        agentDepth: 0,
         canary: '',
         canaries,
     };
@@ -357,6 +376,7 @@ async function* runTurnInRegistry(registry, req, provider, sinkOverride) {
     const { sink, policy } = resolveTraceWriter({
         override: sinkOverride,
         observability: ctx.known?.observability,
+        guardrails: ctx.known?.guardrails,
     });
     ctx.observability = policy;
     try {
@@ -383,14 +403,13 @@ async function* emitCancelledDoneAfterAbort(ctx) {
     const gen = ctx.generation;
     if (!(profile && gen && ctx.safe && ctx.trace))
         return;
-    // The turn's own state when it got that far, so post_turn sees the history the model saw.
+    // why: The turn's own state when it got that far, so post_turn sees the history the model saw.
     const state = ctx.state ??
         openTurnState({
             tools: ctx.registry.tools,
             profile,
             generation: gen,
             trace: ctx.trace,
-            mediaFamily: ctx.mediaFamily,
             allEmittedEvents: [...ctx.seen],
         });
     for await (const stageEv of applyTurnStage({
@@ -412,7 +431,7 @@ async function* runTurnBody(ctx, provider) {
     const checkMs = performance.now() - checkStart;
     ctx.safe = sanitized.request;
     const hits = sanitized.events.filter((event) => event.type === 'guardrail');
-    // The check's time rides on its last decision, or on a pass when it found nothing.
+    // why: The check's time rides on its last decision, or on a pass when it found nothing.
     if (hits.length === 0) {
         ctx.root.event('theorem.guardrail', guardrailCheckAttributes('input', checkMs, undefined, { stage: 'input', trust: 'untrusted' }));
     }
@@ -424,48 +443,82 @@ async function* runTurnBody(ctx, provider) {
         }
         yield deliver(ctx, projectForObs(event, ctx.observability));
     }
+    if (sanitized.refusal)
+        throw sanitized.refusal;
     const { profile, generation: gen } = resolveTurnInRegistry(ctx.registry, ctx.safe);
     await expandT1Policy(ctx.registry.tools, gen.tools, profile, ctx.safe);
     if (ctx.compacting === 'self')
         gen.tools = noTools();
     gen.builtins = gen.tools.builtins;
+    if (gen.canary)
+        gen.canary = await profileCanary(profile.id, gen.resolvedSystem);
     ctx.generation = gen;
     ctx.canary = gen.canary;
     ctx.canaries.push(gen.canary);
     const binding = profile.models[gen.model];
-    ctx.mediaFamily = binding ? mediaTokenFamily(binding) : undefined;
     ctx.trace = { root: ctx.root, attempt: 0, calls: 0, binding };
+    if (!ctx.compacting)
+        ctx.agents = agentCallerFor(ctx, provider, binding);
     throwIfAborted(ctx.safe.signal);
     const compactionSpec = ctx.compacting ? undefined : getCompactionSpec(profile, gen.model);
     const compaction = await maybeCompactBefore(ctx, profile, gen, compactionSpec, provider);
     if (compaction)
         yield deliver(ctx, projectForObs(compaction, ctx.observability));
     ctx.system = bindSystem(gen.resolvedSystem, [
-        canaryNote(ctx.canary, profile.lexicon),
+        canaryNote(ctx.canary, profile.labels),
         profileTypesForField('identity.system').includes(profile.type)
-            ? userDataNote(profile.lexicon)
+            ? userDataNote(profile.labels)
             : '',
+        profileInputs(profile)?.context ? contextNote(profile.labels) : '',
     ]);
     yield* streamTurnEvents(ctx, profile, gen, provider, compactionSpec);
 }
+/** The turn's agent tool calls: each runs nested under its tool's span, in this record. */
+function agentCallerFor(ctx, provider, own) {
+    return createAgentCaller({
+        registry: ctx.registry,
+        req: ctx.safe ?? ctx.req,
+        provider,
+        own,
+        depth: ctx.agentDepth,
+        runNested: (nested) => runNestedTurn({ ...nested, registry: ctx.registry, canaries: ctx.canaries }),
+    });
+}
+/**
+ * A host's own call's agent tools: the host's provider, or the one `onAgentCall`
+ * returns, runs each. Its nested turns bind their canaries into `canaries`.
+ */
+function invokeAgentCaller(registry, request, canaries) {
+    return createAgentCaller({
+        registry,
+        req: request,
+        provider: request.provider ? hostAgentModel(registry, request.provider) : undefined,
+        own: undefined,
+        depth: 0,
+        runNested: (nested) => runNestedTurn({ ...nested, registry, canaries }),
+    });
+}
+/**
+ * A live session's agent tools: the session's own provider options, or those
+ * `onAgentCall` returns, run each. Its nested turns bind their canaries into
+ * `canaries`.
+ */
+function sessionAgentCaller(registry, req, options, canaries) {
+    return createAgentCaller({
+        registry,
+        req: { ...req, execution: options.execution },
+        provider: hostAgentModel(registry, options),
+        own: undefined,
+        depth: 0,
+        runNested: (nested) => runNestedTurn({ ...nested, registry, canaries }),
+    });
+}
 /**
  * The turn's provider runs the compactor only when it is the one the compactor
  * would get: a text profile on the same protocol and provider.
  */
 function compactorProvider(ctx, profile, spec, provider) {
-    if (ctx.req.compactionProvider)
-        return ctx.req.compactionProvider;
-    if (spec.profile === undefined)
-        return provider;
-    const compactor = ctx.registry.profiles.get(spec.profile);
-    const own = ctx.trace?.binding;
-    const theirs = compactor.models[compactor.defaultModel];
-    if (profile.type !== 'text' ||
-        own?.provider !== theirs?.provider ||
-        own?.protocol !== theirs?.protocol) {
-        throw new TheoremError('config', `Profile ${profile.id} compacts with '${spec.profile}', which this turn's provider cannot run; pass compactionProvider`);
-    }
-    return provider;
+    return nestedTurnModel(provider, spec.profile ?? profile.id, spec.profile ? undefined : ctx.req.model);
 }
 async function maybeCompactBefore(ctx, profile, gen, compactionSpec, provider) {
     if (!(compactionSpec?.timing === 'before' && ctx.safe))
@@ -478,7 +531,6 @@ async function maybeCompactBefore(ctx, profile, gen, compactionSpec, provider) {
         owner: profile.id,
         model: gen.model,
         spec: compactionSpec,
-        family: ctx.mediaFamily,
         history: gen.history,
         input: ctx.safe.input,
         provider: compactor,
@@ -496,7 +548,6 @@ async function maybeAttachAfter(event, ctx, gen, compactionSpec) {
     }
     return await attachAfterCompaction(event, {
         spec: compactionSpec,
-        family: ctx.mediaFamily,
         history: gen.history ?? [],
         input: ctx.safe.input,
         seen: ctx.seen,
@@ -505,7 +556,7 @@ async function maybeAttachAfter(event, ctx, gen, compactionSpec) {
 }
 /**
  * `timing: 'after'`: run the compactor on the history `done.compaction` carried,
- * with the same split, failure rules and trace as `before`. `provider` runs the
+ * with the same split, failure rules, and trace as `before`. `provider` runs the
  * compactor. `undefined` when the split leaves nothing to compact.
  */
 async function compactHistoryInRegistry(registry, req, provider, sinkOverride) {
@@ -516,8 +567,7 @@ async function compactHistoryInRegistry(registry, req, provider, sinkOverride) {
     if (!spec) {
         throw new TheoremError('config', `Profile ${profile.id} model '${model}' has no compaction`);
     }
-    const family = mediaTokenFamily(binding);
-    const split = await splitForCompaction(req.history, spec, family);
+    const split = await splitForCompaction(req.history, spec);
     if (split.toCompact.length === 0)
         return undefined;
     const turnReq = {
@@ -532,6 +582,7 @@ async function compactHistoryInRegistry(registry, req, provider, sinkOverride) {
     const { sink, policy } = resolveTraceWriter({
         override: sinkOverride,
         observability: profile.observability,
+        guardrails: profile.guardrails,
     });
     const canaries = [];
     try {
@@ -571,4 +622,4 @@ async function compactHistoryInRegistry(registry, req, provider, sinkOverride) {
         }), policy);
     }
 }
-export { compactHistoryInRegistry, runTurnInRegistry };
+export { compactHistoryInRegistry, invokeAgentCaller, runTurnInRegistry, sessionAgentCaller };

package/esm/src/kernel/engine/runner/nested.d.ts

@@ -0,0 +1,32 @@
+import type { ErrorKind } from '../../../guardrails/error.js';
+import type { SpanHandle } from '../../../observability/trace-span.js';
+import type { KernelRegistry } from '../../registry/kernel-registry.js';
+import { type AgentCaller } from '../../tools/agent.js';
+import type { ModelBinding, TurnEvent, TurnEventOf, TurnModel, TurnRequest } from '../../types.js';
+/** Errors only the host can fix: a nested turn throws them rather than failing quietly every call. */
+declare const NESTED_THROWS: ReadonlySet<ErrorKind>;
+declare function turnError(events: readonly TurnEvent[]): TurnEventOf<'error'> | undefined;
+/** Runs one turn of a profile under a parent span, sharing the parent's record and canaries. */
+type RunNestedTurn = (args: {
+    req: TurnRequest;
+    provider: TurnModel;
+    parent: SpanHandle;
+    agentDepth: number;
+}) => AsyncGenerator<TurnEvent>;
+/**
+ * Agent tool calls for one turn. `own` is the turn's model binding: its
+ * provider runs a called agent on the same provider and protocol, and the
+ * host's hook supplies any other. Without `own` (an invoke) the provider is
+ * the host's own choice and runs as given.
+ */
+declare function createAgentCaller(args: {
+    registry: KernelRegistry;
+    req: Pick<TurnRequest, 'onAgentCall' | 'metadata' | 'execution' | 'pageExecution'>;
+    provider: TurnModel | undefined;
+    own: ModelBinding | undefined;
+    /** 0 for the host's own turn or invoke. */
+    depth: number;
+    runNested: RunNestedTurn;
+}): AgentCaller;
+export type { RunNestedTurn };
+export { createAgentCaller, NESTED_THROWS, turnError };

package/esm/src/kernel/engine/runner/nested.js

@@ -0,0 +1,134 @@
+import { errorCopyText, isAbortError, TheoremError, throwIfAborted, toErrorEvent, } from '../../../guardrails/error.js';
+import { labelText } from '../../../guardrails/labels.js';
+import { nestedTurnModel, resolveRegisteredTurnModel } from '../../provider-dispatch.js';
+import { agentProfileProblem, agentToolOutputOf, splitHostInput, } from '../../tools/agent.js';
+import { findLast } from '../../util/find-last.js';
+import { sumEventTokens } from '../usage.js';
+/** Errors only the host can fix: a nested turn throws them rather than failing quietly every call. */
+const NESTED_THROWS = new Set(['config', 'request', 'auth', 'internal']);
+function turnError(events) {
+    return events.find((e) => e.type === 'error');
+}
+/**
+ * Agent tool calls for one turn. `own` is the turn's model binding: its
+ * provider runs a called agent on the same provider and protocol, and the
+ * host's hook supplies any other. Without `own` (an invoke) the provider is
+ * the host's own choice and runs as given.
+ */
+function createAgentCaller(args) {
+    const calls = new Map();
+    const { registry, req } = args;
+    return {
+        async *run({ tool, callId, input, caller, span, signal }) {
+            const labels = caller.labels;
+            const settled = (code, kind, message) => ({
+                failure: { code, kind, message },
+            });
+            const made = calls.get(tool.name) ?? 0;
+            if (tool.maxCallsPerTurn !== undefined && made >= tool.maxCallsPerTurn) {
+                return settled('call_limit', 'declined', labelText('tool.agent_call_limit', { tool: tool.name }, labels));
+            }
+            calls.set(tool.name, made + 1);
+            const profile = registry.profiles.get(tool.profile);
+            const problem = agentProfileProblem(profile, (name) => registry.tools.get(name));
+            if (problem) {
+                throw new TheoremError('config', `Agent tool "${tool.name}" can't run '${tool.profile}': ${problem}`);
+            }
+            const { sent: modelInput, hostInput } = splitHostInput(tool, input);
+            if (hostInput && !req.onAgentCall) {
+                throw new TheoremError('config', `Agent tool "${tool.name}" declares host fields, which need the request's onAgentCall`);
+            }
+            const shaped = await req.onAgentCall?.({
+                tool: tool.name,
+                callId,
+                profile: tool.profile,
+                input: modelInput,
+                ...(hostInput ? { hostInput } : {}),
+                caller: caller.id,
+                depth: args.depth + 1,
+                ...(req.metadata ? { metadata: req.metadata } : {}),
+                ...(signal ? { signal } : {}),
+            });
+            if (shaped && 'refuse' in shaped) {
+                return settled('refused_by_host', 'declined', shaped.refuse);
+            }
+            const { provider: hostProvider, ...fields } = shaped ?? {};
+            const provider = agentProvider(args, profile.id, fields.model, hostProvider);
+            if (!span) {
+                throw new TheoremError('internal', `Agent tool "${tool.name}" ran without a span`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+            }
+            const { speech, ...sent } = modelInput;
+            const events = [];
+            try {
+                for await (const event of args.runNested({
+                    req: {
+                        ...(speech ? { speech } : {}),
+                        ...fields,
+                        profile: tool.profile,
+                        execution: req.execution,
+                        pageExecution: req.pageExecution,
+                        input: fields.input ?? sent,
+                        ...(signal ? { signal } : {}),
+                        ...(req.onAgentCall ? { onAgentCall: req.onAgentCall } : {}),
+                    },
+                    provider,
+                    parent: span,
+                    agentDepth: args.depth + 1,
+                })) {
+                    events.push(event);
+                    yield event;
+                }
+            }
+            catch (err) {
+                // why: A turn refused before it starts (a file the agent does not take) throws; the caller's model reads it like any other failed call.
+                if (!(err instanceof TheoremError) || NESTED_THROWS.has(err.kind) || isAbortError(err)) {
+                    throw err;
+                }
+                events.push(toErrorEvent(err));
+            }
+            throwIfAborted(signal);
+            return agentRunOf(events, tool.name, tool.profile, labels);
+        },
+    };
+}
+/** The provider an agent's turn runs on: the host's for this call, else the caller's, else the registry's. */
+function agentProvider(from, profileId, model, hostProvider) {
+    if (hostProvider)
+        return resolveRegisteredTurnModel(from.registry, profileId, model, hostProvider);
+    if (from.provider)
+        return nestedTurnModel(from.provider, profileId, model);
+    return resolveRegisteredTurnModel(from.registry, profileId, model, {});
+}
+/** The agent's reply, or why there is none. Errors only the host can fix are thrown. */
+function agentRunOf(events, toolName, profileId, labels) {
+    const done = findLast(events, (e) => e.type === 'done');
+    const tokens = done?.tokens ?? sumEventTokens(events);
+    const usage = tokens ? { tokens } : {};
+    const reported = turnError(events);
+    if (reported && NESTED_THROWS.has(reported.errorKind)) {
+        throw new TheoremError(reported.errorKind, `Agent '${profileId}' failed: ${reported.errorInternal ?? reported.error}`);
+    }
+    const stop = done?.stop.kind;
+    if (stop !== 'completed' || reported) {
+        const failed = labelText('tool.agent_failed', { tool: toolName }, labels);
+        // why: Reasons the agent's turn named (a file it does not take, a model that is busy) let the caller's model correct the call or say why.
+        const reason = reported?.errorCopy
+            ? errorCopyText(reported.errorCopy, labels)
+            : reported?.error;
+        return {
+            failure: {
+                code: 'agent_failed',
+                kind: reported?.errorKind ?? 'failed',
+                message: reason ? `${failed}\n${reason}` : failed,
+                details: {
+                    agent: profileId,
+                    ...(stop ? { stop } : {}),
+                    ...(reported?.errorCopy ? { reasons: reported.errorCopy } : {}),
+                },
+            },
+            ...usage,
+        };
+    }
+    return { output: agentToolOutputOf(events), ...usage };
+}
+export { createAgentCaller, NESTED_THROWS, turnError };

package/esm/src/kernel/engine/runner/schema-validation.d.ts

@@ -1,4 +1,4 @@
-import type { ProfileValidator } from '../../types.js';
+import type { ItemCheckTurn, ProfileItemRule, ProfileValidator } from '../../types.js';
 interface ValidationFailure {
     path: string;
     error: string;
@@ -9,6 +9,27 @@ declare function isAbsent(value: unknown): boolean;
  * paths and for optional paths that are present. Throws when the root is not an object schema.
  */
 declare function collectValidationFailures(jsonSchema: Record<string, unknown>, structured: unknown, fields: Record<string, ProfileValidator> | undefined, slots?: Record<string, string>): Promise<ValidationFailure[]>;
+/**
+ * Whether a validator keyed by `path` can run against `jsonSchema`: each segment is a
+ * property or required key of an object schema, as `collectValidationFailures` walks it.
+ */
+declare function schemaReaches(jsonSchema: Record<string, unknown>, path: string): boolean;
 declare function formatValidationFailures(failures: ValidationFailure[]): string;
-export type { ValidationFailure };
-export { collectValidationFailures, formatValidationFailures, isAbsent };
+/** One list item an item rule refused: where it sat, the item, and why. */
+interface ItemFailure {
+    path: string;
+    index: number;
+    item: unknown;
+    reason: string;
+    onFail: ProfileItemRule['onFail'];
+}
+/** The value at a dotted path, reached through object properties only. */
+declare function valueAt(structured: unknown, path: string): unknown;
+/** `structured` with the list at `path` replaced; every object on the way is copied. */
+declare function withListAt(structured: unknown, path: string, list: unknown[]): unknown;
+/** Each item an item rule refuses, in the reply's own order. A path with no list has no items. */
+declare function collectItemFailures(structured: unknown, items: Record<string, ProfileItemRule> | undefined, turn: ItemCheckTurn): Promise<ItemFailure[]>;
+/** The schema of one item of the list at `path`, or `undefined` when the path reaches no list with one. */
+declare function itemSchemaAt(jsonSchema: Record<string, unknown>, path: string): Record<string, unknown> | undefined;
+export type { ItemFailure, ValidationFailure };
+export { collectItemFailures, collectValidationFailures, formatValidationFailures, isAbsent, itemSchemaAt, schemaReaches, valueAt, withListAt, };