theorum 0.1.15 → 1.1.3

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

@@ -0,0 +1,31 @@
+/**
+ * Live realtime inbound text — same sanitize + user_data fence as runTurn ingress.
+ *
+ * @module
+ */
+import { wrapUserData } from '../../guardrails/canary.js';
+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 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.d.ts

@@ -1,4 +1,4 @@
 import type { ModelProvider, Profile, ResolvedGeneration, TurnEvent, TurnRequest } from '../../types.js';
 import type { StepExecutionState } from './state.js';
-declare function runAttemptsWithValidation(safe: TurnRequest, profile: Profile, generation: ResolvedGeneration, system: string, provider: ModelProvider, gemini: Record<string, unknown>[], state: StepExecutionState): AsyncGenerator<TurnEvent>;
+declare function runAttemptsWithValidation(safe: TurnRequest, profile: Profile, generation: ResolvedGeneration, system: string, provider: ModelProvider, upstream: Record<string, unknown>[], state: StepExecutionState): AsyncGenerator<TurnEvent>;
 export { runAttemptsWithValidation };

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;
@@ -150,19 +194,60 @@ function gateStatusToAction(status, terminalStatus = 'terminal') {
     return null;
 }
 async function* executeSingleAttemptCycle(args) {
-    const { flow, state, profile, system, provider, gemini, 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,
-        gemini,
-        state,
-    });
+    const { flow, state, profile, system, provider, upstream, maxRetries } = args;
+    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, gemini, state) {
-    const maxRetries = Math.max(profile.outputs.validation?.maxRetries ?? 0, profile.guardrails.egress?.maxRetries ?? 2);
+async function* runAttemptsWithValidation(safe, profile, generation, system, provider, upstream, state) {
+    const maxRetries = Math.max(profileTurnOutputs(profile)?.validation?.maxRetries ?? 0, resolveGuardrailPolicy(profile.guardrails).egress?.maxRetries ?? 0);
     const flow = {
         currentAttempt: 0,
         currentGen: generation,
@@ -198,7 +285,7 @@ async function* runAttemptsWithValidation(safe, profile, generation, system, pro
             profile,
             system,
             provider,
-            gemini,
+            upstream,
             maxRetries,
         });
         if (step.status === 'terminal' || step.status === 'success') {

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 };