@theoremjs/agents 0.0.0-stage → 0.3.1

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

@@ -0,0 +1,625 @@
+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 { labelText } from '../../../guardrails/labels.js';
+import { sanitizeTurnRequestWithEvents } from '../../../guardrails/sanitize.js';
+import { resolveTraceWriter } from '../../../observability/policy.js';
+import { resolveObservabilityPolicy } from '../../../observability/resolve-policy.js';
+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 { 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 { keptReply, turnDoneOf } from '../../turn-events.js';
+import { findLast } from '../../util/find-last.js';
+import { compactionMeter, compactionResult, compactorHistory, resolveCompactionTokens, shouldCompact, splitForCompaction, } from '../compaction.js';
+import { endThrownSpan, endTurnSpan, guardrailAttributes, guardrailCheckAttributes, OutputFold, turnSpanOptions, } from '../turn-trace.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';
+function projectForObs(event, policy) {
+    return projectGuardrailTurnEvent(event, policy?.include.guardrailMatchPreview ?? false);
+}
+const MS_PER_S = 1000;
+/**
+ * Record an event as delivered to the host; every yield to the host passes
+ * through here, so it is where an error gets the user's wording.
+ */
+function deliver(ctx, event) {
+    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 });
+    }
+    ctx.seen.push(out);
+    ctx.delivered.add(out, ctx.root.nowUnixNano());
+    return out;
+}
+function* emitObservedStage(ctx, stageEv, profile) {
+    const stageOut = projectForObs(stageEv, ctx.observability);
+    if (shouldSkipStreamEvent(stageOut, profile))
+        return;
+    yield deliver(ctx, stageOut);
+}
+function getCompactionSpec(profile, modelId) {
+    return profile.models[modelId]?.compaction;
+}
+/** A turn's tools when it offers none: an agent summarising its own history. */
+function noTools() {
+    return { builtins: [], gated: [], visible: [], executable: [], wire: [] };
+}
+/**
+ * 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 `NESTED_THROWS`
+ * errors are thrown. With no `spec.profile` the owner compacts itself, on the
+ * model it is compacting for and with no tools.
+ */
+async function runCompactor(args) {
+    const self = args.spec.profile === undefined;
+    const compactorId = args.spec.profile ?? args.owner;
+    const compactor = args.registry.profiles.get(compactorId);
+    const { history, droppedMedia } = compactorHistory(args.toCompact, compactor);
+    if (history.length === 0)
+        return { droppedMedia, failure: { unreadable: true } };
+    const req = {
+        profile: compactorId,
+        // why: The turn already passed model selection; its default needs no naming.
+        ...(self && args.model !== compactor.defaultModel ? { model: args.model } : {}),
+        input: { text: labelText('compaction.request', {}, compactor.labels), history },
+        signal: args.signal,
+    };
+    const events = [];
+    try {
+        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 (NESTED_THROWS.has(error))
+            throw err;
+        return { droppedMedia, failure: { error } };
+    }
+    throwIfAborted(args.signal);
+    const tokens = sumEventTokens(events);
+    const usage = tokens ? { tokens } : {};
+    const stop = findLast(events, (e) => e.type === 'done')?.stop.kind;
+    const reported = turnError(events);
+    if (reported && NESTED_THROWS.has(reported.errorKind)) {
+        throw new TheoremError(reported.errorKind, `Compactor '${compactorId}' failed: ${reported.errorInternal ?? reported.error}`);
+    }
+    const error = reported?.errorKind;
+    if (stop !== 'completed' || error) {
+        return {
+            droppedMedia,
+            failure: { ...(stop ? { stop } : {}), ...(error ? { error } : {}) },
+            ...usage,
+        };
+    }
+    const reply = keptReply(events);
+    const structured = findLast(reply, (e) => e.type === 'structured')?.structured;
+    const summary = structured === undefined
+        ? reply.flatMap((e) => (e.type === 'text' ? [e.text] : [])).join('')
+        : JSON.stringify(structured);
+    if (!summary.trim()) {
+        return { droppedMedia, failure: { stop, empty: true }, ...usage };
+    }
+    return { summary, droppedMedia, ...usage };
+}
+function lastTokensFromEvents(events) {
+    return findLast(events, (e) => e.type === 'tokens')?.tokens;
+}
+/**
+ * One compaction decision as `theorem.compaction` attributes. The metered count
+ * is absent when it is unknown (meter `input` with no count to read).
+ */
+function compactionDecision(spec, decision, needed) {
+    return {
+        timing: spec.timing,
+        meter: compactionMeter(spec),
+        budget: spec.maxTokens,
+        threshold: spec.compactAt,
+        ...(spec.trigger ? { trigger: 'custom' } : {}),
+        ...(decision ? { tokens_before: decision.tokens, unknown_media: decision.unknownMedia } : {}),
+        needed,
+    };
+}
+/** A compaction that ran, as `theorem.compaction` attributes beside its decision. */
+function compactionOutcome(result, messagesBefore) {
+    return {
+        outcome: result.outcome,
+        messages_before: messagesBefore,
+        messages_after: result.history.length,
+        dropped_media: result.droppedMedia,
+        ...(result.failure?.stop ? { failure_stop: result.failure.stop } : {}),
+        ...(result.failure?.error ? { failure_error: result.failure.error } : {}),
+        ...(result.failure?.empty ? { failure_empty: true } : {}),
+        ...(result.failure?.unreadable ? { failure_unreadable: true } : {}),
+        ...(result.summary === undefined ? {} : { summary: traceContent(result.summary) }),
+    };
+}
+async function compactHistoryBeforeTurn(args) {
+    const decision = await resolveCompactionTokens({
+        spec: args.spec,
+        input: args.input,
+    });
+    const needed = decision !== undefined && (await shouldCompact(decision, args.spec));
+    const attributes = compactionDecision(args.spec, decision, needed);
+    if (!(needed && decision)) {
+        args.parent.event('theorem.compaction', attributes);
+        return undefined;
+    }
+    const split = await splitForCompaction(args.history, args.spec);
+    if (split.toCompact.length === 0) {
+        args.parent.event('theorem.compaction', attributes);
+        return undefined;
+    }
+    const run = await runCompactor({ ...args, toCompact: split.toCompact });
+    const { toCompact: _compacted, ...result } = compactionResult(split, run, decision.tokens, args.spec);
+    args.parent.event('theorem.compaction', {
+        ...attributes,
+        ...compactionOutcome(result, args.history.length),
+    });
+    return {
+        type: 'compaction',
+        timing: 'before',
+        meter: decision.meter,
+        tokensBefore: decision.tokens,
+        unknownMedia: decision.unknownMedia,
+        messagesBefore: args.history.length,
+        messagesAfter: result.history.length,
+        ...result,
+    };
+}
+async function attachAfterCompaction(event, args) {
+    if (args.history.length === 0)
+        return event;
+    const prompt = lastTokensFromEvents(args.seen);
+    const decision = await resolveCompactionTokens({
+        spec: args.spec,
+        input: args.input,
+        prompt,
+    });
+    const needed = decision !== undefined && (await shouldCompact(decision, args.spec));
+    args.span.event('theorem.compaction', compactionDecision(args.spec, decision, needed));
+    if (!(needed && decision))
+        return event;
+    const signal = {
+        needed: true,
+        meter: decision.meter,
+        tokens: decision.tokens,
+        unknownMedia: decision.unknownMedia,
+        history: args.history,
+    };
+    if (prompt && prompt.input > 0) {
+        signal.promptTokens = prompt.input;
+        if (prompt.estimated?.includes('input'))
+            signal.promptTokensEstimated = true;
+    }
+    return { ...event, compaction: signal };
+}
+async function* emitTurn(args) {
+    const { safe, profile, generation, system, provider } = args;
+    const state = openTurnState({
+        tools: args.registry.tools,
+        profile,
+        generation,
+        trace: args.trace,
+        ...(args.agents ? { agents: args.agents } : {}),
+    });
+    args.outState.state = state;
+    const pre = yield* applyTurnStage({
+        profile,
+        generation,
+        state,
+        stage: 'pre_turn',
+        step: 1,
+        onStage: safe.onStage,
+        signal: safe.signal,
+        host: generation.host,
+    });
+    if (pre.abort) {
+        const stop = {
+            kind: 'cancelled',
+            ...(typeof pre.abort === 'object' && pre.abort.reason ? { native: pre.abort.reason } : {}),
+        };
+        const done = { type: 'done', stop, traceparent: state.trace.root.traceparent() };
+        state.allEmittedEvents.push(done);
+        yield done;
+        yield* applyTurnStage({
+            profile,
+            generation,
+            state,
+            stage: 'post_turn',
+            step: 1,
+            onStage: safe.onStage,
+            signal: safe.signal,
+            stop,
+            host: generation.host,
+        });
+        return;
+    }
+    yield* runAttemptsWithValidation(safe, profile, generation, system, provider, state);
+    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));
+    state.allEmittedEvents.push(done);
+    yield done;
+}
+async function* streamTurnEvents(ctx, profile, gen, provider, compactionSpec) {
+    if (!ctx.safe || ctx.system === undefined || !ctx.trace)
+        return;
+    for await (const event of emitTurn({
+        registry: ctx.registry,
+        safe: ctx.safe,
+        profile,
+        generation: gen,
+        system: ctx.system,
+        provider,
+        trace: ctx.trace,
+        agents: ctx.agents,
+        outState: ctx,
+    })) {
+        const attached = await maybeAttachAfter(event, ctx, gen, compactionSpec);
+        const out = projectForObs(attached, ctx.observability);
+        if (!shouldSkipStreamEvent(out, profile))
+            yield deliver(ctx, out);
+        if (out.type === 'done' && ctx.state) {
+            // 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({
+                    profile,
+                    generation: gen,
+                    state: ctx.state,
+                    stage: 'post_turn',
+                    step: Math.max(ctx.state.stepCount, 1),
+                    onStage: ctx.safe.onStage,
+                    signal: ctx.safe.signal,
+                    stop: out.stop,
+                    host: gen.host,
+                })) {
+                    yield* emitObservedStage(ctx, stageEv, profile);
+                }
+            }
+        }
+    }
+}
+function newTraceCtx(registry, req, root, canaries) {
+    return {
+        registry,
+        req,
+        known: registry.profiles.find(req.profile),
+        seen: [],
+        delivered: new OutputFold(),
+        root,
+        compacting: false,
+        agentDepth: 0,
+        canary: '',
+        canaries,
+    };
+}
+function endTurn(ctx, thrown) {
+    const calls = ctx.trace?.calls ?? 0;
+    endTurnSpan(ctx.root, {
+        seen: ctx.seen,
+        delivered: ctx.delivered,
+        attempts: calls > 0 ? (ctx.trace?.attempt ?? 0) + 1 : 0,
+        calls,
+        ...(thrown === undefined ? {} : { thrown }),
+    });
+}
+/** Run a turn under `ctx.root` and close it; an abort ends as a cancelled `done`. */
+async function* runTracedTurn(ctx, provider) {
+    try {
+        yield* runTurnBody(ctx, provider);
+    }
+    catch (err) {
+        if (isAbortError(err)) {
+            yield* emitCancelledDoneAfterAbort(ctx);
+            endTurn(ctx);
+            return;
+        }
+        endTurn(ctx, err);
+        throw err;
+    }
+    endTurn(ctx);
+}
+/**
+ * The trace record is written however the turn ends, including when the host stops reading early;
+ * spans still open then close as `ERROR` / `unclosed`.
+ */
+async function* runTurnInRegistry(registry, req, provider, sinkOverride) {
+    const tree = startTrace(`invoke_agent ${req.profile}`, {
+        ...turnSpanOptions(req),
+        ...(req.traceparent ? { traceparent: req.traceparent } : {}),
+    });
+    const ctx = newTraceCtx(registry, req, tree.root, []);
+    const { sink, policy } = resolveTraceWriter({
+        override: sinkOverride,
+        observability: ctx.known?.observability,
+        guardrails: ctx.known?.guardrails,
+    });
+    ctx.observability = policy;
+    try {
+        yield* runTracedTurn(ctx, provider);
+    }
+    finally {
+        await writeTrace(sink, buildRecord({
+            spans: tree.collect(),
+            policy,
+            canaries: ctx.canaries,
+            ...(req.metadata ? { metadata: req.metadata } : {}),
+        }), policy);
+    }
+}
+/** A host abort ends with a cancelled `done` + `post_turn`, not a bare throw. */
+async function* emitCancelledDoneAfterAbort(ctx) {
+    if (ctx.seen.some((e) => e.type === 'done'))
+        return;
+    const stop = { kind: 'cancelled' };
+    const done = { type: 'done', stop, traceparent: ctx.root.traceparent() };
+    const outDone = projectForObs(done, ctx.observability);
+    yield deliver(ctx, outDone);
+    const profile = ctx.known;
+    const gen = ctx.generation;
+    if (!(profile && gen && ctx.safe && ctx.trace))
+        return;
+    // 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,
+            allEmittedEvents: [...ctx.seen],
+        });
+    for await (const stageEv of applyTurnStage({
+        profile,
+        generation: gen,
+        state,
+        stage: 'post_turn',
+        step: Math.max(state.stepCount, 1),
+        onStage: ctx.safe.onStage,
+        stop,
+        host: gen.host,
+    })) {
+        yield* emitObservedStage(ctx, stageEv, profile);
+    }
+}
+async function* runTurnBody(ctx, provider) {
+    const checkStart = performance.now();
+    const sanitized = sanitizeTurnRequestWithEvents(ctx.req, ctx.registry.profiles.get(ctx.req.profile));
+    const checkMs = performance.now() - checkStart;
+    ctx.safe = sanitized.request;
+    const hits = sanitized.events.filter((event) => event.type === 'guardrail');
+    // 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' }));
+    }
+    for (const event of sanitized.events) {
+        if (event.type === 'guardrail') {
+            ctx.root.event('theorem.guardrail', event === hits.at(-1)
+                ? guardrailCheckAttributes('input', checkMs, event.guardrail, event.guardrail)
+                : guardrailAttributes(event.guardrail));
+        }
+        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.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.labels),
+        profileTypesForField('identity.system').includes(profile.type)
+            ? 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) {
+    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))
+        return undefined;
+    const compactor = compactorProvider(ctx, profile, compactionSpec, provider);
+    if (!gen.history?.length)
+        return undefined;
+    const compaction = await compactHistoryBeforeTurn({
+        registry: ctx.registry,
+        owner: profile.id,
+        model: gen.model,
+        spec: compactionSpec,
+        history: gen.history,
+        input: ctx.safe.input,
+        provider: compactor,
+        parent: ctx.root,
+        canaries: ctx.canaries,
+        signal: ctx.safe.signal,
+    });
+    if (compaction)
+        gen.history = compaction.history;
+    return compaction;
+}
+async function maybeAttachAfter(event, ctx, gen, compactionSpec) {
+    if (!(event.type === 'done' && compactionSpec?.timing === 'after' && ctx.safe)) {
+        return event;
+    }
+    return await attachAfterCompaction(event, {
+        spec: compactionSpec,
+        history: gen.history ?? [],
+        input: ctx.safe.input,
+        seen: ctx.seen,
+        span: ctx.root,
+    });
+}
+/**
+ * `timing: 'after'`: run the compactor on the history `done.compaction` carried,
+ * 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) {
+    const profile = registry.profiles.get(req.profile);
+    const model = req.model ?? profile.defaultModel;
+    const binding = requireModelBinding(profile, model);
+    const spec = binding.compaction;
+    if (!spec) {
+        throw new TheoremError('config', `Profile ${profile.id} model '${model}' has no compaction`);
+    }
+    const split = await splitForCompaction(req.history, spec);
+    if (split.toCompact.length === 0)
+        return undefined;
+    const turnReq = {
+        profile: req.profile,
+        input: {},
+        ...(req.conversationId ? { conversationId: req.conversationId } : {}),
+    };
+    const tree = startTrace(`invoke_agent ${req.profile}`, {
+        ...turnSpanOptions(turnReq),
+        ...(req.traceparent ? { traceparent: req.traceparent } : {}),
+    });
+    const { sink, policy } = resolveTraceWriter({
+        override: sinkOverride,
+        observability: profile.observability,
+        guardrails: profile.guardrails,
+    });
+    const canaries = [];
+    try {
+        const run = await runCompactor({
+            registry,
+            owner: profile.id,
+            model,
+            toCompact: split.toCompact,
+            spec,
+            provider,
+            parent: tree.root,
+            canaries,
+            ...(req.signal ? { signal: req.signal } : {}),
+        });
+        const result = compactionResult(split, run, req.tokens, spec);
+        tree.root.event('theorem.compaction', {
+            timing: spec.timing,
+            meter: compactionMeter(spec),
+            budget: spec.maxTokens,
+            threshold: spec.compactAt,
+            tokens_before: req.tokens,
+            ...compactionOutcome(result, req.history.length),
+        });
+        tree.root.end();
+        return result;
+    }
+    catch (err) {
+        endThrownSpan(tree.root, err);
+        throw err;
+    }
+    finally {
+        await writeTrace(sink, buildRecord({
+            spans: tree.collect(),
+            policy,
+            canaries,
+            ...(req.metadata ? { metadata: req.metadata } : {}),
+        }), policy);
+    }
+}
+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 };