@theoremjs/agents 0.3.4-next.484.g20d8b9d → 0.3.4-next.522.g9e684cd

package/esm/src/kernel/engine/decision.js

@@ -5,7 +5,8 @@ import { guardedCall } from '../provider-runtime.js';
 import { soleModelId } from '../registry/sole-model.js';
 import { isRecord } from '../util/record.js';
 import { tracedCall } from './call-trace.js';
-/** Where the provider takes decision requests, as its preset states. */
+import { referencedAssets } from './decision-references.js';
+/** Each decision failure code, and the error kind it reads as. */
 const DECISION_ERROR_KINDS = {
     invalid_request: 'request',
     authentication: 'auth',
@@ -65,7 +66,8 @@ function distribution(value, labels, path) {
     for (const label of labels)
         out[label] = finite(value[label], `${path}.${label}`);
     const total = Object.values(out).reduce((sum, item) => sum + item, 0);
-    if (Math.abs(total - 1) > 0.001) {
+    // why: Answers come rounded to hundredths, so each label may be off by half of one.
+    if (Math.abs(total - 1) > 0.005 * labels.length + 1e-9) {
         throw new DecisionError('malformed_response', `${path} must sum to one`); // labels-exempt: upstream contract error
     }
     return out;
@@ -310,19 +312,19 @@ function isDecisionEntry(value) {
     }
     return true;
 }
-async function enforceDisclosure(profile, model, provider, request) {
+async function enforceDisclosure(profile, model, provider, request, assets) {
     const verdict = await profile.guardrails?.disclosure?.enforce(request.state, {
         destination: provider,
         profileId: profile.id,
         model,
         questionIds: Object.keys(request.questions),
-        ...(request.assets ? { assets: request.assets } : {}),
+        ...(assets ? { assets } : {}),
     });
     if (verdict?.action === 'block') {
         throw new DecisionError('disclosure_blocked', 'Decision disclosure was blocked'); // labels-exempt: developer contract error
     }
 }
-function decisionSpanAttributes(profile, modelId, binding, request) {
+function decisionSpanAttributes(profile, modelId, binding, request, assets) {
     return {
         'gen_ai.operation.name': 'decide',
         'gen_ai.provider.name': binding.provider,
@@ -332,10 +334,10 @@ function decisionSpanAttributes(profile, modelId, binding, request) {
         'theorem.decision.contract': profile.decision.contract,
         'theorem.decision.state': traceJson(request.state),
         'theorem.decision.questions': traceJson(request.questions),
-        ...(request.assets
+        ...(assets
             ? {
                 // invariant: Image bytes never reach a trace; it keeps each image's type and size.
-                'theorem.decision.assets': traceJson(Object.fromEntries(Object.entries(request.assets).map(([reference, { mimeType, data }]) => [
+                'theorem.decision.assets': traceJson(Object.fromEntries(Object.entries(assets).map(([reference, { mimeType, data }]) => [
                     reference,
                     { mimeType, bytes: data.length },
                 ]))),
@@ -384,25 +386,38 @@ function decisionProviderError(error) {
     // why: A framework failure's message holds no response body, and says what stopped the decision.
     error instanceof TheoremError ? error.message : labelText('provider.decision_failed'), isRecord(error) && typeof error.status === 'number' ? error.status : undefined, { cause: error });
 }
-async function decide(registry, profile, [modelId, binding], request, options) {
+/** What the provider gets: each box's image said in its instructions, and only the images a string references. */
+function sentCall(request) {
+    const questions = Object.fromEntries(Object.entries(request.questions).map(([id, question]) => [
+        id,
+        providerQuestion(question, request.assets),
+    ]));
+    const assets = request.assets
+        ? referencedAssets([
+            request.state,
+            ...Object.values(questions).flatMap((question) => [
+                question.instructions,
+                'criteria' in question ? question.criteria : undefined,
+            ]),
+        ], request.assets)
+        : {};
+    return {
+        state: request.state,
+        questions,
+        ...(Object.keys(assets).length ? { assets } : {}),
+    };
+}
+async function decide(registry, profile, [modelId, binding], request, sent, options) {
     throwIfAborted(request.signal);
     const provider = registry.providers.require(binding.provider, binding.apiId);
-    await enforceDisclosure(profile, modelId, binding.provider, request);
+    await enforceDisclosure(profile, modelId, binding.provider, request, sent.assets);
     throwIfAborted(request.signal);
     try {
         const call = guardedCall(provider, binding, 'decision', options, {
             ...(request.signal ? { signal: request.signal } : {}),
             ...(binding.timeoutMs ? { timeoutMs: binding.timeoutMs } : {}),
         });
-        const result = await call.decide({
-            apiId: binding.apiId,
-            state: request.state,
-            questions: Object.fromEntries(Object.entries(request.questions).map(([id, question]) => [
-                id,
-                providerQuestion(question, request.assets),
-            ])),
-            ...(request.assets ? { assets: request.assets } : {}),
-        });
+        const result = await call.decide({ apiId: binding.apiId, ...sent });
         if (typeof result.model !== 'string' || !result.model.trim())
             throw new DecisionError('malformed_response', labelText('provider.decision_model_missing'));
         return { ...result, answers: validateAnswers(result.answers, request.questions) };
@@ -414,17 +429,18 @@ async function decide(registry, profile, [modelId, binding], request, options) {
     }
 }
 /**
- * Exactly one decision request, traced however it ends. An ambiguous POST is never retried,
- * and a trace write failure never changes the decision's outcome.
+ * One decision, traced however it ends. A transient failure (408, 429, a 5xx gateway or a network
+ * error) is retried within five seconds; a trace write failure never changes the decision's outcome.
  */
 export async function runDecisionInRegistry(registry, request, options) {
     const profile = requireDecisionProfile(registry, request.profile);
     validateDecisionRequest(request, profile);
     const model = decisionModel(profile);
     const [modelId, binding] = model;
+    const sent = sentCall(request);
     return await tracedCall({
         name: `decide ${binding.apiId}`,
-        attributes: decisionSpanAttributes(profile, modelId, binding, request),
+        attributes: decisionSpanAttributes(profile, modelId, binding, request, sent.assets),
         traceparent: request.traceparent,
         metadata: request.metadata,
         writer: {
@@ -433,7 +449,7 @@ export async function runDecisionInRegistry(registry, request, options) {
             guardrails: profile.guardrails,
         },
     }, async (root) => {
-        const result = await decide(registry, profile, model, request, options);
+        const result = await decide(registry, profile, model, request, sent, options);
         recordResult(root, result);
         return result;
     });

package/esm/src/kernel/engine/embedding.js

@@ -1,4 +1,3 @@
-import { refuseOverlong } from '../../guardrails/detect-at.js';
 import { TheoremError, throwIfAborted } from '../../guardrails/error.js';
 import { protocolOf } from '../protocols/binding.js';
 import { guardedCall } from '../provider-runtime.js';
@@ -47,7 +46,6 @@ function validateInputs(profile, modelId, inputs, model) {
         const files = [];
         for (const part of parts) {
             if (part.type === 'text') {
-                refuseOverlong(part.text, 'embedding input');
                 if (!rules.text)
                     throw new TheoremError('unsupported', `Profile ${profile.id} does not accept text embedding input`);
                 continue;

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

@@ -8,6 +8,7 @@ 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 { ANSWER_TOOL, answersByTool } from '../../answer-tool.js';
 import { resolveInputParts } from '../../registry/ingress.js';
 import { profileTurnOutputs } from '../../registry/profile-outputs.js';
 import { injectWouldExceedMaxSteps } from '../../stages.js';
@@ -15,7 +16,7 @@ import { findLast } from '../../util/find-last.js';
 import { guardrailCheckAttributes } from '../turn-trace.js';
 import { collectItemFailures, collectValidationFailures, formatValidationFailures, itemSchemaAt, valueAt, withListAt, } from './schema-validation.js';
 import { applyTurnStage } from './stages.js';
-import { appendUserInput, } from './state.js';
+import { appendUserInput, recordStepEvent, } from './state.js';
 import { executeAttempt } from './steps.js';
 import { isWithheldOnBlock, shownToHost } from './stream.js';
 /** A turn whose final output the egress check blocked (withheld or replaced by policy copy). */
@@ -152,7 +153,8 @@ function updateFlowForRetry(flow, state, profile, nextReq, reason) {
     flow.currentReq = nextReq;
     const safe = sanitizeTurnRequest(nextReq, profile);
     if (profile.type === 'text') {
-        // why: The conversation is already in turn history: the repair is its next user message.
+        // why: The repair is the turn's next user message, and the retry reads this turn alone.
+        state.turnOnly = true;
         const before = state.currentHistory.length;
         appendUserInput(state, resolveInputParts(profile, { ...safe, input: { repair: safe.input?.repair } }));
         for (const message of state.currentHistory.slice(before))
@@ -386,6 +388,31 @@ async function handleValidationGate(validation, flow, state, profile, latestStru
     holdReply(state, withoutItems(reply, refused), refused, outcome.failed);
     return 'pass';
 }
+/**
+ * An attempt on a turn that answers by tool, ended without calling the answer tool: a repair while
+ * `outputs.validation` has a retry left, else a `bad_response` failure.
+ */
+function* handleMissingAnswer(flow, state, profile, latestStructured, 
+/** True when the attempt's events go out at its end (`yieldBufferedAttemptEvents`). */
+held) {
+    if (latestStructured !== undefined || state.lastStop?.kind !== 'completed')
+        return 'pass';
+    if (!answersByTool(flow.currentGen))
+        return 'pass';
+    const validation = profileTurnOutputs(profile)?.validation;
+    if (validation && flow.currentAttempt < (validation.maxRetries ?? 0)) {
+        const rejection = labelText('structured.answer_missing', { tool: ANSWER_TOOL }, profile.labels);
+        const nextRequest = buildRepairRequest(flow.currentReq, collectAttemptText(state.attemptEvents), rejection);
+        yield updateFlowForRetry(flow, state, profile, nextRequest, 'validation');
+        return 'continue';
+    }
+    const failure = toErrorEvent(new TheoremError('bad_response', `the model ended without calling ${ANSWER_TOOL}`));
+    recordStepEvent(failure, state);
+    state.lastStop = { kind: 'provider_error' };
+    if (!held)
+        yield failure;
+    return 'pass';
+}
 /** 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');
@@ -403,9 +430,6 @@ function gateStatusToAction(status) {
 }
 async function* executeSingleAttemptCycle(args) {
     const { flow, state, profile, system, provider } = args;
-    const validation = profileTurnOutputs(profile)?.validation;
-    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;
@@ -465,6 +489,14 @@ async function* executeSingleAttemptCycle(args) {
         }
         break;
     }
+    return yield* checkAttemptReply(flow, state, profile, system, latestStructured);
+}
+/** The checks on an attempt's finished reply: the egress judge, the answer, then validation. */
+async function* checkAttemptReply(flow, state, profile, system, structured) {
+    const validation = profileTurnOutputs(profile)?.validation;
+    const policy = resolveGuardrailPolicy(profile.guardrails);
+    const judged = replyIsJudged(policy, TURN_REPLY);
+    let latestStructured = structured;
     if (judged) {
         const status = yield* handleEgressGate(policy, flow, state, profile, system.private);
         const action = gateStatusToAction(status);
@@ -473,6 +505,9 @@ async function* executeSingleAttemptCycle(args) {
         }
         latestStructured = projectOutbound(state.attemptEvents).structured ?? latestStructured;
     }
+    if ((yield* handleMissingAnswer(flow, state, profile, latestStructured, Boolean(validation) || judged)) === 'continue') {
+        return { status: 'continue' };
+    }
     if (validation) {
         const status = await handleValidationGate(validation, flow, state, profile, latestStructured);
         if (status !== 'pass') {

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

@@ -1,5 +1,5 @@
 import { canaryNote, contextNote, profileCanary, userDataNote, } from '../../../guardrails/canary.js';
-import { isAbortError, TheoremError, throwIfAborted, withPublicLabels, } from '../../../guardrails/error.js';
+import { describeError, errorKind, 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';
@@ -22,7 +22,7 @@ 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 { cutConversation, openTurnState, } from './state.js';
 import { shouldSkipStreamEvent } from './stream.js';
 function projectForObs(event, policy) {
     return projectGuardrailTurnEvent(event, policy?.include.guardrailMatchPreview ?? false);
@@ -105,10 +105,10 @@ async function runCompactor(args) {
     }
     catch (err) {
         throwIfAborted(args.signal);
-        const error = err instanceof TheoremError ? err.kind : 'internal';
+        const error = errorKind(err);
         if (NESTED_THROWS.has(error))
             throw err;
-        return { droppedMedia, failure: { error } };
+        return { droppedMedia, failure: { error, errorInternal: describeError(err) } };
     }
     throwIfAborted(args.signal);
     const tokens = sumEventTokens(events);
@@ -122,7 +122,11 @@ async function runCompactor(args) {
     if (stop !== 'completed' || error) {
         return {
             droppedMedia,
-            failure: { ...(stop ? { stop } : {}), ...(error ? { error } : {}) },
+            failure: {
+                ...(stop ? { stop } : {}),
+                ...(error ? { error } : {}),
+                ...(reported?.errorInternal ? { errorInternal: reported.errorInternal } : {}),
+            },
             ...usage,
         };
     }
@@ -163,6 +167,9 @@ function compactionOutcome(result, messagesBefore) {
         dropped_media: result.droppedMedia,
         ...(result.failure?.stop ? { failure_stop: result.failure.stop } : {}),
         ...(result.failure?.error ? { failure_error: result.failure.error } : {}),
+        ...(result.failure?.errorInternal
+            ? { failure_reason: traceContent(result.failure.errorInternal) }
+            : {}),
         ...(result.failure?.empty ? { failure_empty: true } : {}),
         ...(result.failure?.unreadable ? { failure_unreadable: true } : {}),
         ...(result.summary === undefined ? {} : { summary: traceContent(result.summary) }),
@@ -274,6 +281,7 @@ async function* emitTurn(args) {
     const done = turnDoneOf({
         stop: state.lastStop ?? { kind: 'completed' },
         ...(state.providerState &&
+            !cutConversation(state) &&
             !('providerContinuation' in profile && profile.providerContinuation?.history === 'stateless') &&
             (!state.lastStop || ['completed', 'tool', 'gate'].includes(state.lastStop.kind))
             ? { providerState: state.providerState }

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

@@ -23,6 +23,10 @@ interface StepExecutionState {
     agents?: AgentCaller;
     trace: TurnTraceState;
     currentHistory: TurnHistoryMessage[];
+    /** Where this turn begins in `currentHistory`: what came before is the conversation the host passed. */
+    turnStart: number;
+    /** Set by a retry: from then on the model reads this turn only, from `turnStart`. */
+    turnOnly?: boolean;
     stepCount: number;
     /** Model calls sent again this turn under the profile's resumption (`executeResumedStep`). */
     resumes: number;
@@ -106,5 +110,9 @@ declare function openTurnState(args: {
     allEmittedEvents?: TurnEvent[];
     agents?: AgentCaller;
 }): StepExecutionState;
+/** The history the next model call reads: this turn alone once a retry has cut it. */
+declare function modelHistory(state: StepExecutionState): TurnHistoryMessage[];
+/** Whether the turn's checkpoint covers less than the conversation the host keeps. */
+declare function cutConversation(state: StepExecutionState): boolean;
 export type { AttemptFlowState, PendingItemFix, StepExecutionState, TurnTraceState };
-export { appendUserInput, openTurnState, recordStepEvent };
+export { appendUserInput, cutConversation, modelHistory, openTurnState, recordStepEvent };

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

@@ -28,6 +28,7 @@ function openTurnState(args) {
         tools: args.tools,
         trace: args.trace,
         currentHistory: [...(generation.history ?? [])],
+        turnStart: generation.history?.length ?? 0,
         stepCount: 0,
         resumes: 0,
         toolResults: [],
@@ -49,4 +50,12 @@ function openTurnState(args) {
     }
     return state;
 }
-export { appendUserInput, openTurnState, recordStepEvent };
+/** The history the next model call reads: this turn alone once a retry has cut it. */
+function modelHistory(state) {
+    return state.turnOnly ? state.currentHistory.slice(state.turnStart) : state.currentHistory;
+}
+/** Whether the turn's checkpoint covers less than the conversation the host keeps. */
+function cutConversation(state) {
+    return state.turnOnly === true && state.turnStart > 0;
+}
+export { appendUserInput, cutConversation, modelHistory, openTurnState, recordStepEvent };

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

@@ -7,6 +7,7 @@ import { resolveGuardrailPolicy } from '../../../guardrails/policy.js';
 import { replyIsJudged } from '../../../guardrails/progressive-yield.js';
 import { recordTaint } from '../../../guardrails/tool-result.js';
 import { waitDefault } from '../../../providers/shared/retry.js';
+import { ANSWER_TOOL, answersByTool, withAnswerTool } from '../../answer-tool.js';
 import { stepReplyMessages } from '../../interaction-parts.js';
 import { profileTurnOutputs } from '../../registry/profile-outputs.js';
 import { providerCompleteRequest } from '../../registry/provider-request.js';
@@ -20,7 +21,7 @@ import { findLast } from '../../util/find-last.js';
 import { startToolTrace } from '../tool-trace.js';
 import { startCallTrace } from '../turn-trace.js';
 import { applyStageInjects, recordReply } from './stages.js';
-import { recordStepEvent } from './state.js';
+import { modelHistory, recordStepEvent } from './state.js';
 import { inStep, runSideBySide, stepOrder } from './step-order.js';
 import { isWithheldOnBlock, StructuredDrafts, yieldProviderEvents, } from './stream.js';
 import { callTokensEvent, observeCallEvent, startCallUsage } from './usage.js';
@@ -29,7 +30,7 @@ function isStepLimitReached(step, maxSteps) {
 }
 /** The step's generation: the turn's history so far, and no tools when the step must answer. */
 function generationForProviderStep(generation, state, answerOnly) {
-    const forStep = { ...generation, history: state.currentHistory };
+    const forStep = { ...generation, history: modelHistory(state) };
     if (!answerOnly)
         return forStep;
     return { ...forStep, builtins: [], tools: { ...generation.tools, wire: [] } };
@@ -60,14 +61,14 @@ function holdModelCall(calls, tool) {
     return true;
 }
 /** The step's request, with what it gives the model noted on `state`, and its call's usage and trace. */
-function startProviderCall(generation, system, state, answerOnly) {
+function startProviderCall(generation, system, state, answerOnly, labels) {
     const usage = startCallUsage(system.text, {
-        history: state.currentHistory,
+        history: modelHistory(state),
         input: generation.input,
     });
     state.lastCall = usage;
     const genForStep = generationForProviderStep(generation, state, answerOnly);
-    const request = providerCompleteRequest(state.tools, genForStep, system.text);
+    const request = withAnswerTool(providerCompleteRequest(state.tools, genForStep, system.text), generation, labels);
     addRequestUrls(state.givenUrls, request);
     addRequestDestinations(state.destinations, request, state.givenUrls.own);
     if (generation.canary && !state.canaryGiven) {
@@ -118,6 +119,42 @@ function tallyCallEvent(event, tally, call) {
         tally.replied = true;
     return false;
 }
+/**
+ * The structured output the call gave through the answer tool, shown as the step's, with the answer
+ * tool's calls taken out of the step's calls. An answer ends the turn, so the step's other calls do
+ * not run, and the call that gave it completed.
+ */
+async function* showAnswer(shown, tally, step) {
+    if (!answersByTool(step.generation))
+        return;
+    const answer = tally.calls.find((call) => call.name === ANSWER_TOOL && !call.failure);
+    tally.calls = answer ? [] : tally.calls.filter((call) => call.name !== ANSWER_TOOL);
+    if (!answer)
+        return;
+    if (tally.stop?.kind === 'tool') {
+        tally.stop = { kind: 'completed' };
+        step.state.lastStop = tally.stop;
+    }
+    const event = { type: 'structured', structured: answer.arguments };
+    if (tallyCallEvent(event, tally, step.call))
+        return;
+    if (releasesNow(event, step.control, step.state, step.buffer))
+        yield* shown.show(event);
+}
+/**
+ * A tool call's preview. The answer tool's streams as the structured reply's draft.
+ *
+ * why: A preview of the call that follows, which owns the arguments: not the turn's record. It streams
+ * as the reply's text does, through its own gate, and like that text is held only when delivery is buffered.
+ */
+async function* showToolDraft(event, shown, generation, buffer) {
+    if (buffer.holdVisible)
+        return;
+    if (event.name === ANSWER_TOOL && answersByTool(generation))
+        yield* shown.draft(event.text);
+    else
+        yield event;
+}
 /** What sets one model call's text apart from the reply text before it: a blank line. */
 const CALL_BREAK = '\n\n';
 /**
@@ -130,7 +167,8 @@ function withCallBreak(event, tally, state, generation) {
     if (tally.text)
         return event;
     const before = state.replyText;
-    const breaks = before && generation.structured === null && !/\s$/.test(before) && !/^\s/.test(event.text);
+    const prose = generation.structured === null || answersByTool(generation);
+    const breaks = before && prose && !/\s$/.test(before) && !/^\s/.test(event.text);
     tally.replyAt = before.length + (breaks ? CALL_BREAK.length : 0);
     return breaks ? { ...event, text: `${CALL_BREAK}${event.text}` } : event;
 }
@@ -194,7 +232,7 @@ async function* executeAutonomousStep(args, state, buffer = {
     holdVisible: false,
 }) {
     const { profile, generation, system, provider, signal } = args;
-    const { usage, genForStep, request, call } = startProviderCall(generation, system, state, isAnswerOnlyStep(profile, generation, state.stepCount));
+    const { usage, genForStep, request, call } = startProviderCall(generation, system, state, isAnswerOnlyStep(profile, generation, state.stepCount), profile.labels);
     const tally = { calls: [], reasoning: [], text: '', failures: [], replied: false };
     const control = {
         withholdVisible: false,
@@ -209,7 +247,7 @@ async function* executeAutonomousStep(args, state, buffer = {
         canaryGiven: state.canaryGiven,
         ...(state.ownTools ? { ownTools: state.ownTools } : {}),
     };
-    const shown = new StructuredDrafts(seen);
+    const shown = new StructuredDrafts({ ...seen, generation });
     try {
         for await (const event of yieldProviderEvents({
             ...seen,
@@ -219,6 +257,7 @@ async function* executeAutonomousStep(args, state, buffer = {
             signal,
             control,
             tools: state.tools,
+            answerTool: answersByTool(generation),
         })) {
             if (observeCallEvent(usage, event))
                 continue;
@@ -234,14 +273,11 @@ async function* executeAutonomousStep(args, state, buffer = {
                 continue;
             }
             if (event.type === 'tool_draft') {
-                // why: A preview of the call that follows, which owns the arguments: not the turn's record. It streams
-                // as the reply's text does, through its own gate, and like that text is held only when delivery is buffered.
-                if (!buffer.holdVisible)
-                    yield event;
+                yield* showToolDraft(event, shown, generation, buffer);
                 continue;
             }
             // why: The model's history keeps what it wrote; only the reply the host gets is set apart.
-            const next = event.type === 'text' ? withCallBreak(event, tally, state, genForStep) : event;
+            const next = event.type === 'text' ? withCallBreak(event, tally, state, generation) : event;
             if (tallyCallEvent(event, tally, call))
                 continue;
             if (!releasesNow(next, control, state, buffer))
@@ -254,6 +290,7 @@ async function* executeAutonomousStep(args, state, buffer = {
         throw err;
     }
     yield* shown.end();
+    yield* showAnswer(shown, tally, { generation, state, control, buffer, call });
     keepStreamCarry(state, control);
     const resume = resumeOf(args.mayResume, profile, tally);
     if (!resume) {

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

@@ -24,18 +24,20 @@ interface OutboundStreamControl {
 declare function shouldSkipStreamEvent(event: ModelEvent, profile: Profile): boolean;
 /** Host-visible output a mid-stream block withholds. A thought is never withheld, only omitted from. */
 declare function isWithheldOnBlock(event: ModelEvent): boolean;
+export type ShownGeneration = Pick<ResolvedGeneration, 'structured' | 'stream' | 'tools'>;
 /**
- * An event as the host gets it, or nothing. The text of a call that asked for structured output is
- * that output's JSON: under `sse` it goes out as `structured_draft`, and under `buffered` not at all,
- * since the `structured` event is the reply whole. The turn keeps it as text, which its checks,
- * repairs and history read.
+ * An event as the host gets it, or nothing. On a turn that answers through a response format, the
+ * text is that output's JSON: under `sse` it goes out as `structured_draft`, and under `buffered`
+ * not at all, since the `structured` event is the reply whole. The turn keeps it as text, which its
+ * checks, repairs and history read. On a turn that answers by tool, the text is progress.
  */
-declare function shownToHost(event: TurnEvent, generation: Pick<ResolvedGeneration, 'structured' | 'stream'>): TurnEvent | undefined;
+declare function shownToHost(event: TurnEvent, generation: ShownGeneration): TurnEvent | undefined;
 /**
  * A step's events as the host gets them (`shownToHost`), with a structured reply's drafts read
- * first at `reply_structured`, where the whole is read. The reply's text has already passed the
- * `reply` gate; a match at `reply_structured` stops the drafts, and the `structured` event still
- * arrives as that check leaves it. The held tail is read and released when the step's stream ends.
+ * first at `reply_structured`, where the whole is read. The drafts are the reply's text, or the
+ * answer tool's arguments as the model writes them. Text has already passed the `reply` gate; a
+ * match at `reply_structured` stops the drafts, and the `structured` event still arrives as that
+ * check leaves it. The held tail is read and released when the step's stream ends.
  */
 declare class StructuredDrafts {
     private readonly drafts;
@@ -43,6 +45,8 @@ declare class StructuredDrafts {
     /** Reads the stream's own checks off what the step knows of the turn. */
     constructor(seen: Pick<StreamArgs, 'profile' | 'generation' | 'privateSystem' | 'givenUrls' | 'canaryGiven' | 'ownTools'>);
     show(event: TurnEvent): AsyncGenerator<TurnEvent>;
+    /** Part of the structured output's JSON, as the model writes it. */
+    draft(json: string): AsyncGenerator<TurnEvent>;
     /** The drafts' tail the gate still holds, once the step's stream has ended. */
     end(): Generator<TurnEvent>;
 }
@@ -65,6 +69,8 @@ interface StreamArgs {
     ownTools?: OwnTools;
     /** The turn's tools: a draft is read at the boundary its tool's calls are. */
     tools: ToolRegistry;
+    /** True when the turn answers through the answer tool (`answersByTool`). */
+    answerTool?: boolean;
 }
 declare function yieldProviderEvents(args: StreamArgs): AsyncGenerator<StreamEvent>;
 export type { OutboundStreamControl, StreamArgs };

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

@@ -7,6 +7,7 @@ import { resolveGuardrailPolicy } from '../../../guardrails/policy.js';
 import { createDraftGate, createOutboundProgressiveGate, DraftReader, } from '../../../guardrails/progressive-yield.js';
 import { EGRESS_RULES } from '../../../guardrails/rules.js';
 import { thoughtGuardFor, } from '../../../guardrails/thought-guard.js';
+import { ANSWER_TOOL, answersByTool } from '../../answer-tool.js';
 import { profileTurnOutputs } from '../../registry/profile-outputs.js';
 import { toolArgumentsBoundary } from '../../tools/execute.js';
 function shouldSkipStreamEvent(event, profile) {
@@ -69,21 +70,22 @@ function isWithheldOnBlock(event) {
     return event.type === 'text' || event.type === 'media';
 }
 /**
- * An event as the host gets it, or nothing. The text of a call that asked for structured output is
- * that output's JSON: under `sse` it goes out as `structured_draft`, and under `buffered` not at all,
- * since the `structured` event is the reply whole. The turn keeps it as text, which its checks,
- * repairs and history read.
+ * An event as the host gets it, or nothing. On a turn that answers through a response format, the
+ * text is that output's JSON: under `sse` it goes out as `structured_draft`, and under `buffered`
+ * not at all, since the `structured` event is the reply whole. The turn keeps it as text, which its
+ * checks, repairs and history read. On a turn that answers by tool, the text is progress.
  */
 function shownToHost(event, generation) {
-    if (!generation.structured || event.type !== 'text')
+    if (!generation.structured || answersByTool(generation) || event.type !== 'text')
         return event;
     return generation.stream === false ? undefined : { type: 'structured_draft', text: event.text };
 }
 /**
  * A step's events as the host gets them (`shownToHost`), with a structured reply's drafts read
- * first at `reply_structured`, where the whole is read. The reply's text has already passed the
- * `reply` gate; a match at `reply_structured` stops the drafts, and the `structured` event still
- * arrives as that check leaves it. The held tail is read and released when the step's stream ends.
+ * first at `reply_structured`, where the whole is read. The drafts are the reply's text, or the
+ * answer tool's arguments as the model writes them. Text has already passed the `reply` gate; a
+ * match at `reply_structured` stops the drafts, and the `structured` event still arrives as that
+ * check leaves it. The held tail is read and released when the step's stream ends.
  */
 class StructuredDrafts {
     drafts;
@@ -102,9 +104,15 @@ class StructuredDrafts {
                 yield shown;
             return;
         }
-        const text = await this.drafts.read(shown.text);
+        yield* this.draft(shown.text);
+    }
+    /** Part of the structured output's JSON, as the model writes it. */
+    async *draft(json) {
+        if (this.generation.stream === false)
+            return;
+        const text = await this.drafts.read(json);
         if (text)
-            yield { ...shown, text };
+            yield { type: 'structured_draft', text };
     }
     /** The drafts' tail the gate still holds, once the step's stream has ended. */
     *end() {
@@ -131,11 +139,13 @@ class ToolDrafts {
     policy;
     context;
     tools;
+    answerTool;
     drafts = new Map();
-    constructor(policy, context, tools) {
+    constructor(policy, context, tools, answerTool) {
         this.policy = policy;
         this.context = context;
         this.tools = tools;
+        this.answerTool = answerTool;
     }
     /**
      * Shows `event` when it is a draft and says whether it was; any other event closes its call's
@@ -178,7 +188,9 @@ class ToolDrafts {
             this.drafts.delete(event.tool.callId);
     }
     async open(event) {
-        const boundary = toolArgumentsBoundary(this.tools, event.name);
+        // why: The answer's drafts are the structured output's, read at `reply_structured` by `StructuredDrafts`.
+        const answer = this.answerTool && event.name === ANSWER_TOOL;
+        const boundary = answer ? undefined : toolArgumentsBoundary(this.tools, event.name);
         const gate = boundary ? await createDraftGate(this.policy, this.context, boundary) : null;
         const draft = { name: event.name, gate };
         this.drafts.set(event.callId, draft);
@@ -216,7 +228,7 @@ async function* yieldProviderEvents(args) {
     const { canaryCarry, thoughtCarry } = control ?? {};
     const gate = await createOutboundProgressiveGate(policy, context, 'reply', canaryCarry);
     const thoughts = await thoughtGuardFor(policy, context, thoughtCarry);
-    const drafts = new ToolDrafts(policy, context, args.tools);
+    const drafts = new ToolDrafts(policy, context, args.tools, args.answerTool === true);
     /** The streamed event whose reply sits in the gate's lookback; released tails keep its shape. */
     let pendingStream = null;
     let withholdVisible = false;

package/esm/src/kernel/engine/turn-trace.js

@@ -1,4 +1,4 @@
-import { errorKind } from '../../guardrails/error.js';
+import { describeError, errorKind } from '../../guardrails/error.js';
 import { traceBytes, traceContent, traceJson, } from '../../observability/trace-span.js';
 import { historyMessageParts } from '../interaction-parts.js';
 import { isFailedStopKind } from '../stop.js';
@@ -597,7 +597,7 @@ function errorName(err) {
 function recordException(span, err) {
     span.event('exception', {
         'exception.type': errorName(err),
-        'exception.message': traceContent(err instanceof Error ? err.message : String(err)),
+        'exception.message': traceContent(describeError(err)),
         ...(err instanceof Error && err.stack
             ? { 'exception.stacktrace': traceContent(err.stack) }
             : {}),