theorum 1.0.0 → 1.1.3

package/esm/src/kernel/auth/types.d.ts

@@ -0,0 +1,133 @@
+/**
+ * OAuth 2.1 and Model Context Protocol authorization types.
+ *
+ * Implements current July 28, 2026 MCP specification requirements:
+ * - RFC 9728: Protected Resource Metadata
+ * - RFC 8414 & OpenID Connect: Authorization Server Metadata
+ * - RFC 9207: Authorization Server Issuer Identification (`iss` validation)
+ * - RFC 8707: Resource Indicators
+ * - RFC 7636: PKCE with S256
+ *
+ * @module
+ */
+/** RFC 9728 Protected Resource Metadata */
+export interface ProtectedResourceMetadata {
+    resource: string;
+    authorization_servers: string[];
+    scopes_supported?: string[];
+    bearer_methods_supported?: string[];
+    resource_documentation?: string;
+    [key: string]: unknown;
+}
+/** RFC 8414 / OpenID Connect Discovery Metadata */
+export interface AuthorizationServerMetadata {
+    issuer: string;
+    authorization_endpoint: string;
+    token_endpoint: string;
+    registration_endpoint?: string;
+    scopes_supported?: string[];
+    response_types_supported?: string[];
+    grant_types_supported?: string[];
+    code_challenge_methods_supported?: string[];
+    authorization_response_iss_parameter_supported?: boolean;
+    client_id_metadata_document_supported?: boolean;
+    [key: string]: unknown;
+}
+/** Standard OAuth 2.1 token response */
+export interface OAuthTokens {
+    access_token: string;
+    token_type?: string;
+    expires_in?: number;
+    refresh_token?: string;
+    scope?: string;
+    /** Custom extra parameters returned by AS */
+    [key: string]: unknown;
+}
+/** Normalized OAuth credential for storage / pass-through in TurnRequest */
+export interface OAuth2Credential {
+    type: 'oauth2';
+    issuer: string;
+    resource?: string;
+    accessToken: string;
+    refreshToken?: string;
+    expiresAt?: number;
+    tokenEndpoint: string;
+    clientId: string;
+    scope?: string;
+}
+/** Bearer token credential */
+export interface BearerCredential {
+    type: 'bearer';
+    token: string;
+}
+/** API key credential */
+export interface ApiKeyCredential {
+    type: 'api_key';
+    key: string;
+    headerName?: string;
+    headerPrefix?: string;
+}
+/** Universal union of supported tool credentials */
+export type ToolCredential = OAuth2Credential | BearerCredential | ApiKeyCredential;
+/** Options for creating an OAuth 2.1 PKCE authorization flow */
+export interface CreatePkceFlowOptions {
+    /** Target resource server URL (e.g. MCP server URL) or direct AS URL */
+    resourceServerUrl: string;
+    /** The OAuth client id or Client ID Metadata Document HTTPS URL */
+    clientId: string;
+    /** Redirect URI registered with the OAuth client */
+    redirectUri: string;
+    /** Desired scopes */
+    scopes?: string[];
+    /** Secret string used to HMAC-sign the stateless state envelope */
+    signingSecret: string;
+    /** State envelope TTL in milliseconds (default: 10 minutes) */
+    stateTtlMs?: number;
+    /** Optional pre-resolved discovery metadata to bypass runtime fetch */
+    preResolved?: {
+        issuer?: string;
+        authorizationEndpoint?: string;
+        tokenEndpoint?: string;
+        resource?: string;
+    };
+    /** Optional fetch function for testing or proxying */
+    fetchFn?: typeof fetch;
+}
+/** Result of initiating a PKCE flow */
+export interface PkceFlowResult {
+    authorizationUrl: string;
+    state: string;
+    codeVerifier: string;
+    codeChallenge: string;
+    issuer: string;
+    resource?: string;
+}
+/** Options for exchanging an authorization code */
+export interface ExchangePkceCodeOptions {
+    code: string;
+    state: string;
+    /** `iss` parameter returned in the authorization response query (RFC 9207) */
+    iss?: string;
+    /** Redirect URI matching the authorization request */
+    redirectUri: string;
+    /** Secret used to sign the state envelope */
+    signingSecret: string;
+    /** Optional token endpoint override (defaults to discovered AS token_endpoint) */
+    tokenEndpoint?: string;
+    fetchFn?: typeof fetch;
+}
+/** Result of token exchange */
+export interface ExchangePkceCodeResult {
+    tokens: OAuthTokens;
+    credential: OAuth2Credential;
+}
+/** Options for refreshing an expired OAuth token */
+export interface RefreshOAuthTokenOptions {
+    refreshToken: string;
+    tokenEndpoint: string;
+    clientId: string;
+    resource?: string;
+    scope?: string;
+    issuer: string;
+    fetchFn?: typeof fetch;
+}

package/esm/src/kernel/auth/types.js

@@ -0,0 +1,13 @@
+/**
+ * OAuth 2.1 and Model Context Protocol authorization types.
+ *
+ * Implements current July 28, 2026 MCP specification requirements:
+ * - RFC 9728: Protected Resource Metadata
+ * - RFC 8414 & OpenID Connect: Authorization Server Metadata
+ * - RFC 9207: Authorization Server Issuer Identification (`iss` validation)
+ * - RFC 8707: Resource Indicators
+ * - RFC 7636: PKCE with S256
+ *
+ * @module
+ */
+export {};

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

@@ -770,6 +770,20 @@ const INTERMEDIATE_KEYS = [
     'intermediateTokens',
     'intermediate',
 ];
+const CACHED_KEYS = [
+    'total_cached_tokens',
+    'totalCachedTokens',
+    'cached_tokens',
+    'cachedTokens',
+    'cached',
+];
+const CACHE_WRITE_KEYS = [
+    'cache_write_tokens',
+    'cacheWriteTokens',
+    'cache_creation_input_tokens',
+    'cacheCreationInputTokens',
+    'cacheWrite',
+];
 const TOTAL_KEYS = [
     'total_tokens',
     'totalTokens',
@@ -789,18 +803,43 @@ function pickNumericField(record, keys) {
     }
     return 0;
 }
+function detailsRecord(raw) {
+    for (const key of [
+        'prompt_tokens_details',
+        'promptTokensDetails',
+        'input_tokens_details',
+        'inputTokensDetails',
+    ]) {
+        const value = raw[key];
+        if (value && typeof value === 'object' && !Array.isArray(value)) {
+            return value;
+        }
+    }
+    return undefined;
+}
 function extractUsageTokens(raw) {
     if (!raw || typeof raw !== 'object') {
         return undefined;
     }
     const r = raw;
+    const details = detailsRecord(r);
     const input = pickNumericField(r, INPUT_KEYS);
     const output = pickNumericField(r, OUTPUT_KEYS);
     const thinking = pickNumericField(r, THINKING_KEYS);
     const toolUse = pickNumericField(r, TOOL_KEYS);
     const intermediate = pickNumericField(r, INTERMEDIATE_KEYS);
+    const cached = pickNumericField(r, CACHED_KEYS) || (details ? pickNumericField(details, CACHED_KEYS) : 0);
+    const cacheWrite = pickNumericField(r, CACHE_WRITE_KEYS) ||
+        (details ? pickNumericField(details, CACHE_WRITE_KEYS) : 0);
     const total = pickNumericField(r, TOTAL_KEYS) || input + output + thinking + toolUse + intermediate;
-    if (input > 0 || output > 0 || thinking > 0 || toolUse > 0 || intermediate > 0 || total > 0) {
+    if (input > 0 ||
+        output > 0 ||
+        thinking > 0 ||
+        toolUse > 0 ||
+        intermediate > 0 ||
+        cached > 0 ||
+        cacheWrite > 0 ||
+        total > 0) {
         return {
             input,
             output,
@@ -808,6 +847,8 @@ function extractUsageTokens(raw) {
             toolUse,
             total,
             ...(intermediate > 0 ? { intermediate } : {}),
+            ...(cached > 0 ? { cached } : {}),
+            ...(cacheWrite > 0 ? { cacheWrite } : {}),
         };
     }
     return undefined;
@@ -896,7 +937,7 @@ function parseStructuredOutput(text) {
         return { ok: true, structured: JSON.parse(text) };
     }
     catch {
-        return { ok: false, error: 'structured output was not valid JSON' };
+        return { ok: false, error: 'structured output was not valid JSON' }; // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
     }
 }
 export { codeExecutionEvidence, codeExecutionStepKey, eventsFromComplete, eventsFromDelta, eventsFromInteractionSteps, extractTokenEvent, extractUsageTokens, googleBuiltinEvidence, groundingFromEvent, isCodeExecutionType, isGoogleBuiltinStepType, mergeCodeExecutionPayload, parseStructuredOutput, };

package/esm/src/kernel/engine/live-inbound.d.ts

@@ -3,7 +3,19 @@
  *
  * @module
  */
-import type { Profile } from '../types.js';
-/** Sanitize profile-controlled inbound text and wrap with user_data fencing. */
-declare function prepareLiveInboundText(profile: Profile, text: string): string;
+import type { Profile, TurnEvent } from '../types.js';
+export interface LiveInboundPrepareResult {
+    text: string;
+    /** Present when inbound sanitize redacted spans. */
+    guardrail?: TurnEvent;
+}
+/**
+ * Sanitize profile-controlled inbound text and wrap with user_data fencing.
+ *
+ * Resolves through the shared policy so Live ingress and the turn engine cannot
+ * drift apart on what an unset switch means. Returns an optional guardrail event
+ * for the session stream when redaction ran. Match previews follow
+ * `observability.include.guardrailMatchPreview`.
+ */
+declare function prepareLiveInboundText(profile: Profile, text: string): LiveInboundPrepareResult;
 export { prepareLiveInboundText };

package/esm/src/kernel/engine/live-inbound.js

@@ -4,14 +4,28 @@
  * @module
  */
 import { wrapUserData } from '../../guardrails/canary.js';
-import { sanitizeText } from '../../guardrails/sanitize.js';
-/** Sanitize profile-controlled inbound text and wrap with user_data fencing. */
+import { guardrailFromHits, projectGuardrailTurnEvent } from '../../guardrails/events.js';
+import { detectionForTrust, resolveGuardrailPolicy } from '../../guardrails/policy.js';
+import { detectText } from '../../guardrails/sanitize.js';
+import { resolveObservabilityPolicy } from '../../observability/resolve-policy.js';
+/**
+ * Sanitize profile-controlled inbound text and wrap with user_data fencing.
+ *
+ * Resolves through the shared policy so Live ingress and the turn engine cannot
+ * drift apart on what an unset switch means. Returns an optional guardrail event
+ * for the session stream when redaction ran. Match previews follow
+ * `observability.include.guardrailMatchPreview`.
+ */
 function prepareLiveInboundText(profile, text) {
-    const guardrails = profile.guardrails;
-    const safe = sanitizeText(text, {
-        sanitizeInput: guardrails?.sanitizeInput === true,
-        redactSensitive: guardrails?.redactSensitive === true,
-    });
-    return wrapUserData(safe);
+    const policy = resolveGuardrailPolicy(profile.guardrails);
+    const detected = detectText(text, detectionForTrust(policy, 'untrusted'));
+    const raw = guardrailFromHits('live_inbound', 'untrusted', detected.hits, 'redact');
+    const includeMatch = resolveObservabilityPolicy(profile.observability).include
+        .guardrailMatchPreview;
+    const guardrail = raw ? projectGuardrailTurnEvent(raw, includeMatch) : undefined;
+    return {
+        text: wrapUserData(detected.text),
+        ...(guardrail ? { guardrail } : {}),
+    };
 }
 export { prepareLiveInboundText };

package/esm/src/kernel/engine/live-ingress.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Live realtime ingress — profile gates for sendAudio / sendVideo / sendText.
+ *
+ * @module
+ */
+import type { LiveIngressSpec, Profile } from '../types.js';
+export type LiveIngressChannel = keyof LiveIngressSpec;
+/** Default when `live.ingress.<channel>` is omitted — mic and camera on, typed text off. */
+export declare function liveIngressChannelDefault(channel: LiveIngressChannel): boolean;
+/** Resolve one channel from an ingress spec object (no profile wrapper). */
+export declare function liveIngressEnabledFromSpec(ingress: LiveIngressSpec | undefined, channel: LiveIngressChannel): boolean;
+/** Whether a realtime ingress channel is enabled on the profile. */
+export declare function liveIngressEnabled(profile: Profile, channel: LiveIngressChannel): boolean;
+/** True when at least one realtime ingress channel is enabled. */
+export declare function hasAnyLiveIngress(profile: Profile): boolean;
+/** Reject profiles with every ingress channel disabled. */
+export declare function assertLiveIngressConfigured(profile: Profile): void;
+/** Reject send* calls when the profile disabled that ingress channel. */
+export declare function assertLiveIngress(profile: Profile, channel: LiveIngressChannel): void;

package/esm/src/kernel/engine/live-ingress.js

@@ -0,0 +1,47 @@
+/**
+ * Live realtime ingress — profile gates for sendAudio / sendVideo / sendText.
+ *
+ * @module
+ */
+import { TheorumError } from '../../guardrails/error.js';
+const LIVE_INGRESS_CHANNELS = ['audio', 'video', 'text'];
+function assertLiveProfile(profile) {
+    if (profile.type !== 'live') {
+        throw new TheorumError(`Profile '${profile.id}' is not type 'live'`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+    return profile;
+}
+/** Default when `live.ingress.<channel>` is omitted — mic and camera on, typed text off. */
+export function liveIngressChannelDefault(channel) {
+    return channel !== 'text';
+}
+/** Resolve one channel from an ingress spec object (no profile wrapper). */
+export function liveIngressEnabledFromSpec(ingress, channel) {
+    const value = ingress?.[channel];
+    if (value === undefined)
+        return liveIngressChannelDefault(channel);
+    return value;
+}
+/** Whether a realtime ingress channel is enabled on the profile. */
+export function liveIngressEnabled(profile, channel) {
+    const live = assertLiveProfile(profile);
+    return liveIngressEnabledFromSpec(live.live.ingress, channel);
+}
+/** True when at least one realtime ingress channel is enabled. */
+export function hasAnyLiveIngress(profile) {
+    const live = assertLiveProfile(profile);
+    return LIVE_INGRESS_CHANNELS.some((channel) => liveIngressEnabledFromSpec(live.live.ingress, channel));
+}
+/** Reject profiles with every ingress channel disabled. */
+export function assertLiveIngressConfigured(profile) {
+    const live = assertLiveProfile(profile);
+    if (hasAnyLiveIngress(live))
+        return;
+    throw new TheorumError(`Profile '${live.id}': at least one live.ingress channel (audio, video, text) must be enabled`);
+}
+/** Reject send* calls when the profile disabled that ingress channel. */
+export function assertLiveIngress(profile, channel) {
+    if (liveIngressEnabled(profile, channel))
+        return;
+    throw new TheorumError(`Profile '${profile.id}' live.ingress.${channel} is disabled — cannot send on this channel`);
+}

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

@@ -1,3 +1,5 @@
+import { lexiconText } from '../../guardrails/lexicon.js';
+import { profileTurnOutputs } from '../registry/profile-outputs.js';
 const MAX_REPAIR_HISTORY_EXCHANGES = 2;
 const MAX_REPAIR_HISTORY_MESSAGES = MAX_REPAIR_HISTORY_EXCHANGES * 2;
 function scopeHistory(history) {
@@ -11,28 +13,27 @@ function formatHistoryBlock(messages) {
         return '';
     }
     const lines = messages.map((m) => `${m.role === 'user' ? 'User' : 'Assistant'}: ${m.content}`);
-    return `### RECENT CONVERSATION CONTEXT (LAST ${messages.length} TURNS)\n${lines.join('\n')}\n\n`;
+    const heading = lexiconText('repair.history_heading', { count: messages.length });
+    return `${heading}\n${lines.join('\n')}\n\n`;
 }
 function synthesizeRepairPrompt(args) {
     const { profile, repair, history } = args;
     const guidance = repair.guidance ||
-        profile.outputs?.validation?.repairGuidance ||
-        'Revise the previous output so it satisfies the validator rejection. Preserve the intended user-facing substance unless the guidance says otherwise.';
+        profileTurnOutputs(profile)?.validation?.repairGuidance ||
+        lexiconText('repair.default_guidance');
     const historyBlock = formatHistoryBlock(scopeHistory(history));
-    let prompt = `## OUTPUT REPAIR REQUEST\n\n`;
-    prompt += `The previous assistant output was rejected by a host validator and must be revised.\n\n`;
-    prompt += `### PREVIOUS OUTPUT\n\`\`\`\n${repair.previousOutput.trim()}\n\`\`\`\n\n`;
-    prompt += `### VALIDATOR REJECTION\n${repair.rejection.trim()}\n\n`;
+    let prompt = `${lexiconText('repair.prompt_header')}\n\n`;
+    prompt += `${lexiconText('repair.prompt_intro')}\n\n`;
+    prompt += `${lexiconText('repair.section_previous_output')}\n\`\`\`\n${repair.previousOutput.trim()}\n\`\`\`\n\n`;
+    prompt += `${lexiconText('repair.section_validator_rejection')}\n${repair.rejection.trim()}\n\n`;
     if (guidance.trim()) {
-        prompt += `### REPAIR GUIDANCE\n${guidance.trim()}\n\n`;
+        prompt += `${lexiconText('repair.section_repair_guidance')}\n${guidance.trim()}\n\n`;
     }
     if (historyBlock) {
         prompt += historyBlock;
     }
-    prompt += `### INSTRUCTIONS\n`;
-    prompt += `1. Inspect the previous output and validator rejection.\n`;
-    prompt += `2. Apply the repair guidance without inventing unsupported facts.\n`;
-    prompt += `3. Return only the corrected assistant output required by the active profile.`;
+    prompt += `${lexiconText('repair.section_instructions')}\n`;
+    prompt += lexiconText('repair.prompt_instructions');
     return prompt;
 }
 export { synthesizeRepairPrompt };

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

@@ -1,14 +1,40 @@
+import { runEnforcer } from '../../../guardrails/egress.js';
 import { TheorumError, throwIfAborted, toErrorEvent } from '../../../guardrails/error.js';
+import { guardrailFromVerdict } from '../../../guardrails/events.js';
+import { lexiconText } from '../../../guardrails/lexicon.js';
+import { resolveGuardrailPolicy } from '../../../guardrails/policy.js';
 import { sanitizeTurnRequest } from '../../../guardrails/sanitize.js';
+import { profileTurnOutputs } from '../../registry/profile-outputs.js';
 import { resolveTurn } from '../../registry/resolve.js';
 import { getStructured } from '../../registry/schemas.js';
+import { injectWouldExceedMaxSteps } from '../../stages.js';
+import { findLast } from '../../util/find-last.js';
 import { collectValidationFailures, formatValidationFailures } from './schema-validation.js';
+import { applyTurnStage } from './stages.js';
 import { executeAttempt } from './steps.js';
+/** Internal reason recorded when a turn is withheld; mapped to public copy on emit. */
+const WITHHELD = 'Turn withheld: egress disclosure violation'; // lexicon-exempt: internal marker mapped by publicError
 function collectAttemptText(events) {
-    return events
-        .filter((e) => e.type === 'text' && e.text)
-        .map((e) => e.text)
-        .join('');
+    const parts = [];
+    for (const event of events) {
+        if (event.type === 'text' && event.text) {
+            parts.push(event.text);
+        }
+    }
+    return parts.join('');
+}
+/**
+ * Project attempt events into the egress payload.
+ *
+ * Structured output travels alongside text so a profile with `outputs.structured`
+ * is covered by its own egress policy rather than passing unexamined.
+ */
+function projectOutbound(events) {
+    const structured = findLast(events, (e) => e.type === 'structured')?.structured;
+    return {
+        text: collectAttemptText(events),
+        ...(structured !== undefined ? { structured } : {}),
+    };
 }
 function buildRepairRequest(safe, previousOutput, rejection, repairGuidance) {
     return {
@@ -25,31 +51,45 @@ function buildRepairRequest(safe, previousOutput, rejection, repairGuidance) {
 }
 async function evaluateEgressOutcome(args) {
     const { egress, attemptEvents, generation, request, profile, canRetry } = args;
-    const attemptText = collectAttemptText(attemptEvents);
-    const result = await egress.enforce({
-        text: attemptText,
-        canary: generation.canary,
-        slots: request.input?.slots,
-        profile,
-        role: request.input?.role,
-    });
-    if (!result.blocked) {
-        return { action: 'pass' };
+    const payload = projectOutbound(attemptEvents);
+    const context = {
+        stage: 'output_final',
+        trust: 'untrusted',
+        profileId: profile.id,
+        ...(generation.canary ? { canary: generation.canary } : {}),
+        ...(request.input?.slots ? { slots: request.input.slots } : {}),
+        ...(request.input?.role ? { role: request.input.role } : {}),
+    };
+    const verdict = 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') {
+        return {
+            outcome: { action: 'refusal', event: { type: 'text', text: verdict.text } },
+            guardrail,
+        };
     }
     if (egress.onBlock === 'refuse_to_user') {
-        return { action: 'refusal', event: { type: 'text', text: result.text } };
+        // Only emit a text turn when the policy supplied copy. Without it the kernel
+        // has nothing to say — an empty text event reads as a successful empty reply —
+        // so fall back to the same withheld error the exhausted-retry path uses.
+        return {
+            outcome: verdict.refusal
+                ? { action: 'refusal', event: { type: 'text', text: verdict.refusal } }
+                : { action: 'withhold', event: toErrorEvent(WITHHELD) },
+            guardrail,
+        };
     }
     if (canRetry) {
-        const rejectionMsg = result.rejectionMessage || 'Egress disclosure violation detected.';
-        const repairGuidance = egress.repairGuidance ||
-            'Rewrite the message as corrected user-visible prose only. Keep the same helpful substance; scrub all internal tool names, leak phrases, and disclosure markers.';
-        const nextRequest = buildRepairRequest(request, attemptText, rejectionMsg, repairGuidance);
-        return { action: 'retry', nextRequest };
+        const repairGuidance = egress.repairGuidance || lexiconText('egress.default_repair_guidance');
+        const nextRequest = buildRepairRequest(request, payload.text, verdict.rejection, repairGuidance);
+        return { outcome: { action: 'retry', nextRequest }, guardrail };
     }
-    return {
-        action: 'withhold',
-        event: toErrorEvent('Turn withheld: egress disclosure violation'),
-    };
+    return { outcome: { action: 'withhold', event: toErrorEvent(WITHHELD) }, guardrail };
 }
 async function evaluateValidationOutcome(args) {
     const { validation, generation, latestStructured, request, canRetry } = args;
@@ -97,7 +137,7 @@ function updateFlowForRetry(flow, nextReq) {
 }
 async function* handleEgressGate(egress, flow, state, profile, maxRetries) {
     const canRetry = flow.currentAttempt < maxRetries;
-    const outcome = await evaluateEgressOutcome({
+    const { outcome, guardrail } = await evaluateEgressOutcome({
         egress,
         attemptEvents: state.attemptEvents,
         generation: flow.currentGen,
@@ -105,6 +145,10 @@ async function* handleEgressGate(egress, flow, state, profile, maxRetries) {
         profile,
         canRetry,
     });
+    if (guardrail) {
+        state.allEmittedEvents.push(guardrail);
+        yield guardrail;
+    }
     if (outcome.action === 'refusal') {
         state.allEmittedEvents.push(outcome.event);
         yield outcome.event;
@@ -151,18 +195,59 @@ function gateStatusToAction(status, terminalStatus = 'terminal') {
 }
 async function* executeSingleAttemptCycle(args) {
     const { flow, state, profile, system, provider, upstream, maxRetries } = args;
-    const validation = profile.outputs?.validation;
-    const egress = profile.guardrails?.egress;
-    state.attemptEvents = [];
-    const { latestStructured } = yield* executeAttempt({
-        safe: flow.currentReq,
-        profile,
-        generation: flow.currentGen,
-        system,
-        provider,
-        upstream,
-        state,
-    });
+    const validation = profileTurnOutputs(profile)?.validation;
+    const egress = resolveGuardrailPolicy(profile.guardrails).egress;
+    // 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.withheldVisible = false;
+        const attempt = yield* executeAttempt({
+            safe: flow.currentReq,
+            profile,
+            generation: flow.currentGen,
+            system,
+            provider,
+            upstream,
+            state,
+        });
+        latestStructured = attempt.latestStructured;
+        // Tool / gate suspension — do not before_end; finalize with that stop.
+        if (state.lastStop?.kind === 'tool' || state.lastStop?.kind === 'gate') {
+            break;
+        }
+        if (state.lastStop?.kind === 'cancelled') {
+            return { status: 'terminal' };
+        }
+        const beforeEnd = yield* applyTurnStage({
+            profile,
+            generation: flow.currentGen,
+            state,
+            stage: 'before_end',
+            step: Math.max(state.stepCount, 1),
+            onStage: flow.currentReq.onStage,
+            signal: flow.currentReq.signal,
+            host: flow.currentGen.host,
+            injectWouldExceedMaxSteps: injectWouldExceedMaxSteps(state.stepCount, flow.currentGen.maxSteps),
+        });
+        if (beforeEnd.abort) {
+            state.lastStop = {
+                kind: 'cancelled',
+                ...(typeof beforeEnd.abort === 'object' && beforeEnd.abort.reason
+                    ? { native: beforeEnd.abort.reason }
+                    : {}),
+            };
+            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');
@@ -178,13 +263,15 @@ async function* executeSingleAttemptCycle(args) {
         }
     }
     if (validation || egress?.enforce) {
-        const alreadyStreamedUserVisible = !egress?.enforce;
-        yield* yieldBufferedAttemptEvents(state.attemptEvents, alreadyStreamedUserVisible);
+        // Progressive-yield already released text/thought 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);
     }
     return { status: 'success' };
 }
 async function* runAttemptsWithValidation(safe, profile, generation, system, provider, upstream, state) {
-    const maxRetries = Math.max(profile.outputs?.validation?.maxRetries ?? 0, profile.guardrails?.egress?.maxRetries ?? 0);
+    const maxRetries = Math.max(profileTurnOutputs(profile)?.validation?.maxRetries ?? 0, resolveGuardrailPolicy(profile.guardrails).egress?.maxRetries ?? 0);
     const flow = {
         currentAttempt: 0,
         currentGen: generation,

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

@@ -7,8 +7,10 @@
  *
  * @module
  */
-import { type TraceSink } from '../../../observability/trace.js';
-import type { ModelProvider, TurnEvent, TurnRequest } from '../../types.js';
+import type { TraceSink } from '../../../observability/trace-sink.js';
+import type { ModelProvider, TurnEvent, TurnHistoryMessage, TurnRequest } from '../../types.js';
+/** Fold one history message to a compaction transcript line (media → markers). */
+declare function compactionTranscriptLine(m: TurnHistoryMessage): string;
 /** Execute one host turn against a provider adapter. */
-declare function runTurn(req: TurnRequest, provider: ModelProvider, sink?: TraceSink): AsyncGenerator<TurnEvent>;
-export { runTurn };
+declare function runTurn(req: TurnRequest, provider: ModelProvider, sinkOverride?: TraceSink): AsyncGenerator<TurnEvent>;
+export { compactionTranscriptLine, runTurn };