@theoremjs/agents 0.3.0 → 0.3.1

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

@@ -1,19 +1,23 @@
-import { hitRules, runEnforcer, WITHHELD_REASON } from '../../../guardrails/egress.js';
+import { scopeOf } from '../../../guardrails/detect-at.js';
+import { readReply, refusalAfter, replyAfter, standingBlock, TURN_REPLY, } from '../../../guardrails/detect-reply.js';
+import { WITHHELD_REASON } from '../../../guardrails/egress.js';
 import { TheoremError, throwIfAborted, toErrorEvent } from '../../../guardrails/error.js';
-import { guardrailFromVerdict } from '../../../guardrails/events.js';
-import { lexiconText } from '../../../guardrails/lexicon.js';
+import { guardrailFromHits, guardrailTurnEvent } from '../../../guardrails/events.js';
+import { retryRejection } from '../../../guardrails/hints.js';
+import { labelText } from '../../../guardrails/labels.js';
 import { resolveGuardrailPolicy } from '../../../guardrails/policy.js';
+import { replyIsJudged } from '../../../guardrails/progressive-yield.js';
 import { sanitizeTurnRequest } from '../../../guardrails/sanitize.js';
 import { resolveInputParts } from '../../registry/ingress.js';
 import { profileTurnOutputs } from '../../registry/profile-outputs.js';
 import { injectWouldExceedMaxSteps } from '../../stages.js';
 import { findLast } from '../../util/find-last.js';
 import { guardrailCheckAttributes } from '../turn-trace.js';
-import { collectValidationFailures, formatValidationFailures } from './schema-validation.js';
+import { collectItemFailures, collectValidationFailures, formatValidationFailures, itemSchemaAt, valueAt, withListAt, } from './schema-validation.js';
 import { applyTurnStage } from './stages.js';
-import { appendUserInput } from './state.js';
+import { appendUserInput, } from './state.js';
 import { executeAttempt } from './steps.js';
-import { isWithheldOnBlock } from './stream.js';
+import { isWithheldOnBlock, shownToHost } from './stream.js';
 /** A turn whose final output the egress check blocked (withheld or replaced by policy copy). */
 const EGRESS_FILTERED_STOP = { kind: 'filtered', native: 'egress' };
 /** Reply text only: thoughts are not guarded output (`isGuardedOutput`). */
@@ -26,7 +30,7 @@ function collectAttemptText(events) {
     }
     return parts.join('');
 }
-// Structured output travels with the text so `outputs.structured` meets egress rather than passing unexamined.
+// why: Structured output travels with the text so `outputs.structured` meets egress rather than passing unexamined.
 function projectOutbound(events) {
     const structured = findLast(events, (e) => e.type === 'structured')?.structured;
     return {
@@ -47,56 +51,61 @@ function buildRepairRequest(safe, previousOutput, rejection, repairGuidance) {
         },
     };
 }
-async function evaluateEgressOutcome(args) {
-    const { egress, attemptEvents, generation, request, profile, canRetry, promptLeaks, givenUrls } = args;
-    const payload = projectOutbound(attemptEvents);
-    const context = {
-        stage: 'output_final',
-        trust: 'untrusted',
-        profileId: profile.id,
-        ...(profile.lexicon ? { lexicon: profile.lexicon } : {}),
-        ...(generation.canary ? { canary: generation.canary } : {}),
-        ...(request.input?.slots ? { slots: request.input.slots } : {}),
-        ...(request.input?.role ? { role: request.input.role } : {}),
-        givenUrls,
-    };
-    // The host policy adds checks; it never releases a system-prompt leak.
-    const verdict = promptLeaks?.length
-        ? {
-            action: 'block',
-            hits: promptLeaks,
-            rejection: lexiconText('egress.rejection', { rules: hitRules(promptLeaks).join(', ') }, profile.lexicon),
+/** The verdict on an attempt's reply, as `guardrails.detect` reads it whole. */
+function evaluateEgressOutcome(args) {
+    const { attemptEvents, request, profile, canRetry, promptLeaks } = args;
+    const { detect, blockedReply } = args.policy;
+    const written = projectOutbound(attemptEvents);
+    const scope = scopeOf(args.policy, {
+        canary: args.generation.canary,
+        canaryGiven: args.canaryGiven,
+        privateSystem: args.privateSystem,
+        givenUrls: args.givenUrls,
+        ...(args.ownTools ? { ownTools: args.ownTools } : {}),
+        ...(profile.labels ? { labels: profile.labels } : {}),
+    });
+    const read = readReply(written, detect, {
+        boundary: 'reply',
+        ...(args.withheld ? { reportedTo: args.released.length } : {}),
+        scope,
+    });
+    const { payload } = read;
+    /** Text that takes the written reply's place, as the host receives it. */
+    const replacement = (text) => ({
+        action: 'refusal',
+        event: { type: 'text', text },
+    });
+    const stopped = standingBlock(read, promptLeaks);
+    // why: A detector's block is reported by its own event, which names the boundary.
+    const judged = stopped && stopped !== read.blocked
+        ? guardrailFromHits('output_final', 'untrusted', stopped, 'block')
+        : undefined;
+    const guardrails = [...read.events.map(guardrailTurnEvent), ...(judged ? [judged] : [])];
+    if (!stopped) {
+        if (read.rewritten) {
+            // why: Text the stream could not replace as it went: the reply goes out replaced, whole.
+            return { outcome: replacement(replyAfter(args.shown, payload.text)), guardrails };
         }
-        : await runEnforcer(egress.enforce, payload, context);
-    const guardrail = guardrailFromVerdict('output_final', 'untrusted', verdict);
-    // `flag` is advisory: the hit is recorded, the turn still releases.
-    if (verdict.action === 'allow' || verdict.action === 'flag') {
-        return { outcome: { action: 'pass' }, guardrail };
-    }
-    // The policy supplied safe replacement prose — release that instead.
-    if (verdict.action === 'redact') {
+        const replaced = payload.structured !== written.structured;
         return {
-            outcome: {
-                action: 'refusal',
-                event: { type: 'text', text: verdict.text },
-            },
-            guardrail,
+            outcome: { action: 'pass' },
+            guardrails,
+            ...(replaced ? { structured: payload.structured } : {}),
         };
     }
-    if (egress.onBlock === 'refuse_to_user') {
-        const text = lexiconText('egress.refusal', {}, profile.lexicon);
-        return { outcome: { action: 'refusal', event: { type: 'text', text } }, guardrail };
+    if (blockedReply.onBlock === 'refuse') {
+        return { outcome: replacement(refusalAfter(args.shown, profile.labels)), guardrails };
     }
     if (canRetry) {
-        const nextRequest = buildRepairRequest(request, payload.text, verdict.rejection, lexiconText('egress.default_repair_guidance', {}, profile.lexicon));
-        return { outcome: { action: 'retry', nextRequest }, guardrail };
+        const nextRequest = buildRepairRequest(request, payload.text, retryRejection(stopped, detect, profile.labels), labelText('egress.default_repair_guidance', {}, profile.labels));
+        return { outcome: { action: 'retry', nextRequest }, guardrails };
     }
     return {
         outcome: {
             action: 'withhold',
             event: toErrorEvent(new TheoremError('safety', WITHHELD_REASON.egress)),
         },
-        guardrail,
+        guardrails,
     };
 }
 async function evaluateValidationOutcome(args) {
@@ -109,34 +118,31 @@ async function evaluateValidationOutcome(args) {
         throw new TheoremError('config', 'outputs.validation requires outputs.structured with a JSON Schema');
     }
     const failures = await collectValidationFailures(structured.jsonSchema, latestStructured, validation.fields, request.input?.slots);
-    if (failures.length === 0) {
+    if (failures.length === 0)
         return { action: 'pass' };
-    }
-    const error = formatValidationFailures(failures);
-    if (canRetry) {
-        const nextRequest = buildRepairRequest(request, latestStructured, error);
-        return { action: 'retry', nextRequest };
-    }
-    return {
-        action: 'accept',
-        event: { type: 'structured', structured: latestStructured },
-    };
+    if (!canRetry)
+        return { action: 'pass', failed: failures };
+    const nextRequest = buildRepairRequest(request, latestStructured, formatValidationFailures(failures));
+    return { action: 'retry', nextRequest };
 }
-function* yieldBufferedAttemptEvents(events, alreadyStreamedUserVisible) {
+function* yieldBufferedAttemptEvents(events, alreadyStreamedUserVisible, generation) {
     for (const ev of events) {
         if (ev.type === 'tokens') {
             continue;
         }
-        // Thoughts always streamed live; text and media did unless the attempt withheld them.
+        // why: Thoughts always streamed live; text and media did unless the attempt withheld them.
         if (ev.type === 'thought' || (alreadyStreamedUserVisible && isWithheldOnBlock(ev))) {
             continue;
         }
-        yield ev;
+        // why: A held structured reply was judged whole; its drafts are the JSON before that check, so the `structured` event alone shows it.
+        const shown = shownToHost(ev, { ...generation, stream: false });
+        if (shown)
+            yield shown;
     }
 }
 /**
  * Start the next attempt with the repair added. The turn is not resolved again:
- * the retry keeps attempt 1's canary, tools and system prompt, and only the
+ * the retry keeps attempt 1's canary, tools, and system prompt, and only the
  * repair prompt is new.
  */
 function updateFlowForRetry(flow, state, profile, nextReq, reason) {
@@ -146,34 +152,68 @@ function updateFlowForRetry(flow, state, profile, nextReq, reason) {
     flow.currentReq = nextReq;
     const safe = sanitizeTurnRequest(nextReq, profile);
     if (profile.type === 'text') {
-        // The conversation is already in turn history: the repair is its next user message.
+        // why: The conversation is already in turn history: the repair is its next user message.
+        const before = state.currentHistory.length;
         appendUserInput(state, resolveInputParts(profile, { ...safe, input: { repair: safe.input?.repair } }));
-        return;
+        for (const message of state.currentHistory.slice(before))
+            quotesOwnReply(state, message);
     }
-    // An image or speech call reads only its input: the repair replaces the prompt.
-    flow.currentGen = { ...flow.currentGen, input: resolveInputParts(profile, safe) };
+    else {
+        // why: An image or speech call reads only its input: the repair replaces the prompt.
+        const input = resolveInputParts(profile, safe);
+        quotesOwnReply(state, input);
+        flow.currentGen = { ...flow.currentGen, input };
+    }
+    const event = { type: 'attempt', attempt: flow.currentAttempt, reason };
+    state.allEmittedEvents.push(event);
+    return event;
+}
+/**
+ * A repair hands the stopped reply back, and the model wrote that reply. What
+ * carries it gives the model nothing: a canary or a URL in it is still a leak
+ * on the next attempt.
+ */
+function quotesOwnReply(state, carrier) {
+    state.canaryScanned.add(carrier);
+    state.givenUrls.own.add(carrier);
+}
+/** Whether an attempt holds its reply text to its end: one validated and not streamed. */
+function holdsVisible(profile, generation) {
+    return profileTurnOutputs(profile)?.validation !== undefined && generation.stream === false;
 }
-async function* handleEgressGate(egress, flow, state, profile, maxRetries) {
-    const canRetry = flow.currentAttempt < maxRetries;
+async function* handleEgressGate(policy, flow, state, profile, privateSystem) {
+    const canRetry = flow.currentAttempt < policy.blockedReply.maxRetries;
     const checkStart = performance.now();
-    const { outcome, guardrail } = await evaluateEgressOutcome({
-        egress,
+    const { outcome, guardrails, structured } = await evaluateEgressOutcome({
+        policy,
         attemptEvents: state.attemptEvents,
+        withheld: state.withheldVisible === true,
+        released: state.released,
+        shown: holdsVisible(profile, flow.currentGen) ? '' : state.released,
         generation: flow.currentGen,
         request: flow.currentReq,
         profile,
         canRetry,
         ...(state.promptLeaks ? { promptLeaks: state.promptLeaks } : {}),
         givenUrls: state.givenUrls,
+        canaryGiven: state.canaryGiven,
+        privateSystem,
+        ...(state.ownTools ? { ownTools: state.ownTools } : {}),
     });
-    state.trace.root.event('theorem.guardrail', guardrailCheckAttributes('egress', performance.now() - checkStart, guardrail?.guardrail, {
+    state.trace.root.event('theorem.guardrail', guardrailCheckAttributes('egress', performance.now() - checkStart, guardrails.at(-1)?.guardrail, {
         stage: 'output_final',
         trust: 'untrusted',
     }));
-    if (guardrail) {
+    for (const guardrail of guardrails) {
         state.allEmittedEvents.push(guardrail);
         yield guardrail;
     }
+    if (structured !== undefined) {
+        // why: What validation reads and the host receives is the structured output as replaced.
+        const held = findLast(state.attemptEvents, (event) => event.type === 'structured');
+        if (held)
+            state.attemptEvents[state.attemptEvents.indexOf(held)] = { ...held, structured };
+    }
     if (outcome.action === 'refusal') {
         state.lastStop = EGRESS_FILTERED_STOP;
         state.allEmittedEvents.push(outcome.event);
@@ -186,34 +226,175 @@ async function* handleEgressGate(egress, flow, state, profile, maxRetries) {
         return 'terminal';
     }
     if (outcome.action === 'retry') {
-        updateFlowForRetry(flow, state, profile, outcome.nextRequest, 'egress');
+        yield updateFlowForRetry(flow, state, profile, outcome.nextRequest, 'egress');
         return 'continue';
     }
     return 'pass';
 }
-async function* handleValidationGate(validation, flow, state, profile, latestStructured, maxRetries) {
-    const canRetry = flow.currentAttempt < maxRetries;
+/** The refused items of each list, in the reply's own shape and order. */
+function refusedLists(refused) {
+    let lists = {};
+    for (const path of new Set(refused.map((failure) => failure.path))) {
+        const items = refused.filter((failure) => failure.path === path).map(({ item }) => item);
+        lists = withListAt(lists, path, items);
+    }
+    return lists;
+}
+/**
+ * The schema a rewrite of refused items answers under: the reply's shape, holding
+ * only the lists that had a refused item.
+ *
+ * why: Under the reply's own schema the model would write the whole reply again to change one item.
+ */
+function fixSchemaFor(jsonSchema, paths) {
+    const root = { type: 'object', properties: {}, required: [] };
+    // why: An item schema may point into the reply schema's definitions.
+    if (jsonSchema.$defs !== undefined)
+        root.$defs = jsonSchema.$defs;
+    for (const path of paths) {
+        const items = itemSchemaAt(jsonSchema, path);
+        if (!items)
+            continue;
+        const keys = path.split('.');
+        let node = root;
+        for (const [depth, key] of keys.entries()) {
+            if (!node.required.includes(key))
+                node.required.push(key);
+            if (depth === keys.length - 1) {
+                node.properties[key] = { type: 'array', items };
+                break;
+            }
+            const next = node.properties[key];
+            const child = next?.type === 'object' ? next : { type: 'object', properties: {}, required: [] };
+            node.properties[key] = child;
+            node = child;
+        }
+    }
+    return root;
+}
+/** `fix.reply` with each refused item replaced by its rewrite, matched by position; one with no rewrite stays as it was. */
+function withRewrittenItems(fix, rewrite) {
+    let reply = fix.reply;
+    for (const path of new Set(fix.refused.map((failure) => failure.path))) {
+        const list = valueAt(reply, path);
+        const rewritten = valueAt(rewrite, path);
+        if (!Array.isArray(list) || !Array.isArray(rewritten))
+            continue;
+        const next = [...list];
+        const refusedHere = fix.refused.filter((failure) => failure.path === path);
+        for (const [position, failure] of refusedHere.entries()) {
+            if (position < rewritten.length)
+                next[failure.index] = rewritten[position];
+        }
+        reply = withListAt(reply, path, next);
+    }
+    return reply;
+}
+/** `reply` without its refused items. */
+function withoutItems(reply, refused) {
+    let next = reply;
+    for (const path of new Set(refused.map((failure) => failure.path))) {
+        const list = valueAt(next, path);
+        if (!Array.isArray(list))
+            continue;
+        const gone = new Set(refused.filter((failure) => failure.path === path).map(({ index }) => index));
+        next = withListAt(next, path, list.filter((_, index) => !gone.has(index)));
+    }
+    return next;
+}
+/**
+ * Makes `reply` the attempt's structured output, with what the item rules removed.
+ *
+ * why: The buffered text is the model's own JSON, which no longer matches; held text goes out as the reply that is kept, and streamed text is skipped at release as it always is.
+ */
+function holdReply(state, reply, removed, failed) {
+    const event = {
+        type: 'structured',
+        structured: reply,
+        ...(removed.length
+            ? { removed: removed.map(({ path, reason, item }) => ({ path, reason, item })) }
+            : {}),
+        ...(failed ? { failed } : {}),
+    };
+    state.attemptEvents = [
+        ...state.attemptEvents.filter((held) => held.type !== 'structured' && held.type !== 'text'),
+        { type: 'text', text: JSON.stringify(reply) },
+        event,
+    ];
+}
+/** The next attempt rewrites only the refused items, under a schema that holds only their lists. */
+function startItemFix(args) {
+    const { flow, state, profile, reply, refused, structured } = args;
+    const positions = new Map();
+    const rejection = refused
+        .map(({ path, reason }) => {
+        const position = positions.get(path) ?? 0;
+        positions.set(path, position + 1);
+        return `${path}[${position}]: ${reason}`;
+    })
+        .join('\n');
+    const nextRequest = buildRepairRequest(flow.currentReq, refusedLists(refused), rejection, labelText('repair.items_guidance', {}, profile.labels));
+    flow.pendingItemFix = { reply, refused, structured };
+    const attempt = updateFlowForRetry(flow, state, profile, nextRequest, 'validation');
+    flow.currentGen = {
+        ...flow.currentGen,
+        structured: {
+            id: structured.id,
+            jsonSchema: fixSchemaFor(structured.jsonSchema, refused.map(({ path }) => path)),
+        },
+    };
+    return attempt;
+}
+async function handleValidationGate(validation, flow, state, profile, latestStructured) {
+    const canRetry = flow.currentAttempt < (validation.maxRetries ?? 0);
+    const fix = flow.pendingItemFix;
+    let reply = latestStructured;
+    if (fix) {
+        // why: The attempt that just ended answered under the fix schema; the reply is the one the items were refused in, with the rewrites put back.
+        flow.pendingItemFix = undefined;
+        flow.currentGen = { ...flow.currentGen, structured: fix.structured };
+        reply = withRewrittenItems(fix, latestStructured);
+        holdReply(state, reply, []);
+    }
     const outcome = await evaluateValidationOutcome({
         validation,
         generation: flow.currentGen,
-        latestStructured,
+        latestStructured: reply,
         request: flow.currentReq,
         canRetry,
     });
     if (outcome.action === 'retry') {
-        updateFlowForRetry(flow, state, profile, outcome.nextRequest, 'validation');
-        return 'continue';
+        return updateFlowForRetry(flow, state, profile, outcome.nextRequest, 'validation');
     }
-    if (outcome.action === 'accept') {
-        state.allEmittedEvents.push(outcome.event);
-        yield outcome.event;
-        return 'terminal';
+    if (reply === undefined)
+        return 'pass';
+    if (outcome.failed)
+        markFailed(state, outcome.failed);
+    const slots = flow.currentReq.input?.slots;
+    const refused = await collectItemFailures(reply, validation.items, {
+        ...(slots ? { slots } : {}),
+        toolResults: state.toolResults,
+    });
+    if (refused.length === 0)
+        return 'pass';
+    const fixable = refused.filter((failure) => failure.onFail === 'fix');
+    const structured = flow.currentGen.structured;
+    // invariant: Refused items get one rewrite. Refused again, they are removed.
+    if (fixable.length > 0 && canRetry && !fix && structured) {
+        return startItemFix({ flow, state, profile, reply, refused: fixable, structured });
     }
+    holdReply(state, withoutItems(reply, refused), refused, outcome.failed);
     return 'pass';
 }
-function gateStatusToAction(status, terminalStatus = 'terminal') {
+/** Puts on the attempt's structured output the fields that still failed. */
+function markFailed(state, failed) {
+    const held = findLast(state.attemptEvents, (event) => event.type === 'structured');
+    if (held)
+        state.attemptEvents[state.attemptEvents.indexOf(held)] = { ...held, failed };
+}
+function gateStatusToAction(status) {
     if (status === 'terminal') {
-        return { status: terminalStatus };
+        return { status: 'terminal' };
     }
     if (status === 'continue') {
         return { status: 'continue' };
@@ -221,16 +402,17 @@ function gateStatusToAction(status, terminalStatus = 'terminal') {
     return null;
 }
 async function* executeSingleAttemptCycle(args) {
-    const { flow, state, profile, system, provider, maxRetries } = args;
+    const { flow, state, profile, system, provider } = args;
     const validation = profileTurnOutputs(profile)?.validation;
-    const egress = resolveGuardrailPolicy(profile.guardrails).egress;
-    // Fresh maxSteps budget per validation/egress attempt. before_end inject
+    const policy = resolveGuardrailPolicy(profile.guardrails);
+    const judged = replyIsJudged(policy, TURN_REPLY);
+    // invariant: Fresh maxSteps budget per validation/egress attempt. before_end inject
     // re-entry inside this cycle still accumulates stepCount (do not reset there).
     state.stepCount = 0;
     let latestStructured;
-    // before_end may inject and re-enter the step loop under maxSteps.
     for (;;) {
         state.attemptEvents = [];
+        state.released = '';
         state.withheldVisible = false;
         state.promptLeaks = undefined;
         const attempt = yield* executeAttempt({
@@ -242,8 +424,10 @@ async function* executeSingleAttemptCycle(args) {
             state,
         });
         latestStructured = attempt.latestStructured;
-        // Tool / gate suspension — do not before_end; finalize with that stop.
-        if (state.lastStop?.kind === 'tool' || state.lastStop?.kind === 'gate') {
+        // why: Tool / gate suspension, or no answer to check — do not before_end; finalize with that stop.
+        if (state.lastStop?.kind === 'tool' ||
+            state.lastStop?.kind === 'gate' ||
+            state.lastStop?.kind === 'step_limit') {
             break;
         }
         if (state.lastStop?.kind === 'cancelled') {
@@ -270,35 +454,38 @@ async function* executeSingleAttemptCycle(args) {
             return { status: 'terminal' };
         }
         if (beforeEnd.injectCount > 0) {
-            // Host extended the turn — another provider step under maxSteps.
             continue;
         }
         break;
     }
-    if (egress?.enforce) {
-        const status = yield* handleEgressGate(egress, flow, state, profile, maxRetries);
-        const action = gateStatusToAction(status, 'terminal');
+    if (judged) {
+        const status = yield* handleEgressGate(policy, flow, state, profile, system.private);
+        const action = gateStatusToAction(status);
         if (action) {
             return action;
         }
+        latestStructured = projectOutbound(state.attemptEvents).structured ?? latestStructured;
     }
     if (validation) {
-        const status = yield* handleValidationGate(validation, flow, state, profile, latestStructured, maxRetries);
-        const action = gateStatusToAction(status, 'success');
-        if (action) {
-            return action;
+        const status = await handleValidationGate(validation, flow, state, profile, latestStructured);
+        if (status !== 'pass') {
+            yield status;
+            return { status: 'continue' };
         }
     }
-    if (validation || egress?.enforce) {
-        // Progressive-yield already released text and media live under egress — unless it
+    if (validation || judged) {
+        // why: Progressive-yield already released text and media live under egress — unless it
         // withheld them mid-stream. A passing final verdict on the full text supersedes
         // that partial-window decision, so the buffer is released instead of dropped.
-        yield* yieldBufferedAttemptEvents(state.attemptEvents, !state.withheldVisible);
+        const heldVisible = state.withheldVisible || holdsVisible(profile, flow.currentGen);
+        yield* yieldBufferedAttemptEvents(state.attemptEvents, !heldVisible, flow.currentGen);
     }
     return { status: 'success' };
 }
 async function* runAttemptsWithValidation(safe, profile, generation, system, provider, state) {
-    const maxRetries = Math.max(profileTurnOutputs(profile)?.validation?.maxRetries ?? 0, resolveGuardrailPolicy(profile.guardrails).egress?.maxRetries ?? 0);
+    const { blockedReply } = resolveGuardrailPolicy(profile.guardrails);
+    // why: Each gate counts the attempts against its own cap; the turn runs while either has one left.
+    const maxRetries = Math.max(profileTurnOutputs(profile)?.validation?.maxRetries ?? 0, blockedReply.onBlock === 'retry' ? blockedReply.maxRetries : 0);
     const flow = {
         currentAttempt: 0,
         currentGen: generation,
@@ -312,7 +499,6 @@ async function* runAttemptsWithValidation(safe, profile, generation, system, pro
             profile,
             system,
             provider,
-            maxRetries,
         });
         if (step.status === 'terminal' || step.status === 'success') {
             break;

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

@@ -1,15 +1,29 @@
 import type { TraceSink } from '../../../observability/trace-sink.js';
+import type { ProviderHostOptions } from '../../protocols/runtime.js';
 import type { KernelRegistry } from '../../registry/kernel-registry.js';
-import type { CompactHistoryRequest, CompactionResult, ModelProvider, TurnEvent, TurnRequest } from '../../types.js';
+import type { AgentCaller } from '../../tools/agent.js';
+import type { InvokeToolRequest } from '../../tools/types.js';
+import type { CompactHistoryRequest, CompactionResult, SessionRequest, TurnEvent, TurnModel, TurnRequest } from '../../types.js';
 /**
  * The trace record is written however the turn ends, including when the host stops reading early;
  * spans still open then close as `ERROR` / `unclosed`.
  */
-declare function runTurnInRegistry(registry: KernelRegistry, req: TurnRequest, provider: ModelProvider, sinkOverride?: TraceSink): AsyncGenerator<TurnEvent>;
+declare function runTurnInRegistry(registry: KernelRegistry, req: TurnRequest, provider: TurnModel, sinkOverride?: TraceSink): AsyncGenerator<TurnEvent>;
+/**
+ * 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`.
+ */
+declare function invokeAgentCaller(registry: KernelRegistry, request: InvokeToolRequest, canaries: string[]): AgentCaller;
+/**
+ * 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`.
+ */
+declare function sessionAgentCaller(registry: KernelRegistry, req: Pick<SessionRequest, 'onAgentCall' | 'metadata'>, options: ProviderHostOptions & Pick<TurnRequest, 'execution'>, canaries: string[]): AgentCaller;
 /**
  * `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.
  */
-declare function compactHistoryInRegistry(registry: KernelRegistry, req: CompactHistoryRequest, provider: ModelProvider, sinkOverride?: TraceSink): Promise<CompactionResult | undefined>;
-export { compactHistoryInRegistry, runTurnInRegistry };
+declare function compactHistoryInRegistry(registry: KernelRegistry, req: CompactHistoryRequest, provider: TurnModel, sinkOverride?: TraceSink): Promise<CompactionResult | undefined>;
+export { compactHistoryInRegistry, invokeAgentCaller, runTurnInRegistry, sessionAgentCaller };