theorum 0.1.2 → 0.1.3

package/esm/src/cli/matrix/synthesizer.js

@@ -0,0 +1,187 @@
+/**
+ * Stress / matrix turn synthesis for the THEORUM CLI.
+ *
+ * Tool enabling walks the profile allowlist and registered catalog metadata
+ * (`conflictsWith`). Google `--search` / `--map` flags remain as convenience
+ * aliases for `googleSearch` / `googleMaps` when those ids are allowed.
+ *
+ * @module
+ */
+import { getTool } from '../../kernel/registry/catalog.js';
+import { FIXTURE_PNG_BASE64, FIXTURE_WAV_BASE64, getFixtureForMime } from './fixtures.js';
+export function synthesizeLiteCombo(profile) {
+    const select = profile.model.select?.fast ? 'fast' : undefined;
+    return {
+        profile: profile.id,
+        select,
+        tools: {},
+        input: {
+            text: `Ping test for profile ${profile.id}. Respond concisely with confirmation.`,
+        },
+    };
+}
+function resolveStressReasoning(profile) {
+    if (profile.model.select?.smart) {
+        return 'smart';
+    }
+    if (profile.model.select) {
+        const keys = Object.keys(profile.model.select);
+        return keys[keys.length - 1];
+    }
+    return undefined;
+}
+function isEnabled(active, id) {
+    return active[id] === true;
+}
+/** Drop tools whose registered `conflictsWith` siblings are also enabled. */
+function applyRegisteredConflicts(allowed, active) {
+    for (const id of allowed) {
+        if (!isEnabled(active, id)) {
+            continue;
+        }
+        const conflicts = getTool(id)?.conflictsWith ?? [];
+        if (conflicts.some((other) => isEnabled(active, other))) {
+            active[id] = false;
+        }
+    }
+}
+/**
+ * Enable allowlisted tools, optionally forcing one preferred tool and clearing
+ * what it conflicts with (and tools that conflict with it).
+ */
+function resolveStressTools(allowed, prefer) {
+    const active = {};
+    for (const t of allowed) {
+        active[t] = true;
+    }
+    if (prefer && allowed.includes(prefer)) {
+        active[prefer] = true;
+        for (const c of getTool(prefer)?.conflictsWith ?? []) {
+            if (allowed.includes(c)) {
+                active[c] = false;
+            }
+        }
+        for (const t of allowed) {
+            if (t === prefer) {
+                continue;
+            }
+            const otherConflicts = getTool(t)?.conflictsWith ?? [];
+            if (otherConflicts.includes(prefer)) {
+                active[t] = false;
+            }
+        }
+    }
+    applyRegisteredConflicts(allowed, active);
+    return active;
+}
+/** Builtins on the allowlist that declare conflicts (candidates for matrix variants). */
+function conflictingAllowlistedTools(allowed) {
+    return allowed.filter((id) => {
+        const entry = getTool(id);
+        return entry?.kind === 'builtin' && (entry.conflictsWith?.length ?? 0) > 0;
+    });
+}
+function resolveStressAttachments(profile) {
+    const attachments = [];
+    const accept = profile.inputs.attachments?.accept;
+    if (accept && accept.length > 0) {
+        const preferredMimes = ['image/png', 'application/pdf', 'text/plain'];
+        const chosenMime = preferredMimes.find((m) => accept.includes(m)) ?? accept[0];
+        const fixture = getFixtureForMime(chosenMime);
+        if (fixture) {
+            attachments.push(fixture);
+        }
+        else {
+            attachments.push({ mimeType: 'image/png', data: FIXTURE_PNG_BASE64 });
+        }
+    }
+    return attachments;
+}
+function resolveStressVoice(profile) {
+    const voice = [];
+    if (profile.inputs.voice?.accept && profile.inputs.voice.accept.length > 0) {
+        voice.push({ mimeType: 'audio/wav', data: FIXTURE_WAV_BASE64 });
+    }
+    return voice;
+}
+export function synthesizeStressCombo(profile, options = {}) {
+    const select = resolveStressReasoning(profile);
+    const activeTools = resolveStressTools(profile.tools.allow ?? [], options.preferTool);
+    const attachments = resolveStressAttachments(profile);
+    const voice = resolveStressVoice(profile);
+    const promptText = `Execute comprehensive test turn for profile ${profile.id}. Validate all instructions and produce required outputs.`;
+    return {
+        profile: profile.id,
+        select,
+        tools: activeTools,
+        input: {
+            text: promptText,
+            attachments: attachments.length > 0 ? attachments : undefined,
+            voice: voice.length > 0 ? voice : undefined,
+        },
+    };
+}
+export function synthesizeMatrixCombos(profile) {
+    const combos = [];
+    const allowed = profile.tools.allow ?? [];
+    combos.push({
+        name: 'Lite (connectivity)',
+        req: synthesizeLiteCombo(profile),
+    });
+    const primary = synthesizeStressCombo(profile);
+    combos.push({
+        name: 'Stress (all modalities + primary tools)',
+        req: primary,
+    });
+    // Variants: each allowlisted conflicting builtin that the primary pass dropped.
+    for (const id of conflictingAllowlistedTools(allowed)) {
+        if (primary.tools?.[id] === true) {
+            continue;
+        }
+        const variant = synthesizeStressCombo(profile, { preferTool: id });
+        if (variant.tools?.[id] !== true) {
+            continue;
+        }
+        combos.push({
+            name: `Conflict variant (${id} preferred)`,
+            req: variant,
+        });
+    }
+    return combos;
+}
+/** Map legacy Google CLI flags onto tool ids when the profile allowlists them. */
+function applyGoogleFlagAliases(active, allowed, options) {
+    if (options.search !== undefined && allowed.includes('googleSearch')) {
+        active.googleSearch = options.search;
+    }
+    if (options.map !== undefined && allowed.includes('googleMaps')) {
+        active.googleMaps = options.map;
+    }
+}
+function applyExplicitToolOverrides(base, profile, options) {
+    const allowed = profile.tools.allow ?? [];
+    base.tools = base.tools ?? {};
+    applyGoogleFlagAliases(base.tools, allowed, options);
+    // If map was explicitly requested on, prefer it against its registered conflicts.
+    if (options.map === true && allowed.includes('googleMaps')) {
+        const preferred = resolveStressTools(allowed, 'googleMaps');
+        for (const id of allowed) {
+            base.tools[id] = preferred[id] === true;
+        }
+        return;
+    }
+    applyRegisteredConflicts(allowed, base.tools);
+}
+export function buildCustomTurnRequest(profile, options) {
+    if (options.lite) {
+        return synthesizeLiteCombo(profile);
+    }
+    const base = synthesizeStressCombo(profile);
+    if (options.mode) {
+        base.select = options.mode;
+    }
+    if (options.search !== undefined || options.map !== undefined) {
+        applyExplicitToolOverrides(base, profile, options);
+    }
+    return base;
+}

package/esm/src/guardrails/error.d.ts

@@ -30,6 +30,4 @@ declare const PUBLIC_FILE_COUNT = "Too many files for one message.";
 declare const PUBLIC_IMAGE_SIZE = "That image size isn't supported.";
 /** Convert an unknown thrown value or internal message to user-safe text. */
 declare function publicError(err: unknown): string;
-/** Backwards-compatible alias for `publicError`. */
-declare function errorMessage(err: unknown): string;
-export { errorMessage, PUBLIC_ACTION, PUBLIC_CANARY, PUBLIC_FILE_COUNT, PUBLIC_FILE_SIZE, PUBLIC_FILE_TYPE, PUBLIC_GENERIC, PUBLIC_IMAGE_SIZE, PUBLIC_UNAVAILABLE, publicError, TheorumError, UPSTREAM_FAILED, };
+export { PUBLIC_ACTION, PUBLIC_CANARY, PUBLIC_FILE_COUNT, PUBLIC_FILE_SIZE, PUBLIC_FILE_TYPE, PUBLIC_GENERIC, PUBLIC_IMAGE_SIZE, PUBLIC_UNAVAILABLE, publicError, TheorumError, UPSTREAM_FAILED, };

package/esm/src/guardrails/error.js

@@ -47,7 +47,9 @@ const EXACT = {
 };
 const RULES = [
     {
-        match: (t) => /^(Gemini|OpenRouter|TTS|OpenRouter TTS) HTTP/.test(t) || t.includes('TTS HTTP'),
+        match: (t) => /^(Gemini|OpenRouter|TTS|OpenRouter TTS|Speech) HTTP/.test(t) ||
+            t.includes('TTS HTTP') ||
+            t.includes('Speech HTTP'),
         resolve: () => PUBLIC_UNAVAILABLE,
     },
     {
@@ -109,8 +111,4 @@ function publicError(err) {
     }
     return PUBLIC_UNAVAILABLE;
 }
-/** Backwards-compatible alias for `publicError`. */
-function errorMessage(err) {
-    return publicError(err);
-}
-export { errorMessage, PUBLIC_ACTION, PUBLIC_CANARY, PUBLIC_FILE_COUNT, PUBLIC_FILE_SIZE, PUBLIC_FILE_TYPE, PUBLIC_GENERIC, PUBLIC_IMAGE_SIZE, PUBLIC_UNAVAILABLE, publicError, TheorumError, UPSTREAM_FAILED, };
+export { PUBLIC_ACTION, PUBLIC_CANARY, PUBLIC_FILE_COUNT, PUBLIC_FILE_SIZE, PUBLIC_FILE_TYPE, PUBLIC_GENERIC, PUBLIC_IMAGE_SIZE, PUBLIC_UNAVAILABLE, publicError, TheorumError, UPSTREAM_FAILED, };

package/esm/src/guardrails/mod.d.ts

@@ -8,7 +8,7 @@
  * @module
  */
 import "../../_dnt.polyfills.js";
-export { errorMessage, PUBLIC_ACTION, PUBLIC_CANARY, PUBLIC_FILE_COUNT, PUBLIC_FILE_SIZE, PUBLIC_FILE_TYPE, PUBLIC_GENERIC, PUBLIC_IMAGE_SIZE, PUBLIC_UNAVAILABLE, publicError, TheorumError, UPSTREAM_FAILED, } from './error.js';
+export { PUBLIC_ACTION, PUBLIC_CANARY, PUBLIC_FILE_COUNT, PUBLIC_FILE_SIZE, PUBLIC_FILE_TYPE, PUBLIC_GENERIC, PUBLIC_IMAGE_SIZE, PUBLIC_UNAVAILABLE, publicError, TheorumError, UPSTREAM_FAILED, } from './error.js';
 export { injectionSpans } from './injection.js';
 export { PROJECT_ID_MAX, sanitizeProjectId, sanitizeText, sanitizeTurnRequest, } from './sanitize.js';
 export { sensitiveSpans } from './sensitive.js';

package/esm/src/guardrails/mod.js

@@ -8,7 +8,7 @@
  * @module
  */
 import "../../_dnt.polyfills.js";
-export { errorMessage, PUBLIC_ACTION, PUBLIC_CANARY, PUBLIC_FILE_COUNT, PUBLIC_FILE_SIZE, PUBLIC_FILE_TYPE, PUBLIC_GENERIC, PUBLIC_IMAGE_SIZE, PUBLIC_UNAVAILABLE, publicError, TheorumError, UPSTREAM_FAILED, } from './error.js';
+export { PUBLIC_ACTION, PUBLIC_CANARY, PUBLIC_FILE_COUNT, PUBLIC_FILE_SIZE, PUBLIC_FILE_TYPE, PUBLIC_GENERIC, PUBLIC_IMAGE_SIZE, PUBLIC_UNAVAILABLE, publicError, TheorumError, UPSTREAM_FAILED, } from './error.js';
 export { injectionSpans } from './injection.js';
 export { PROJECT_ID_MAX, sanitizeProjectId, sanitizeText, sanitizeTurnRequest, } from './sanitize.js';
 export { sensitiveSpans } from './sensitive.js';

package/esm/src/guardrails/sanitize.js

@@ -8,9 +8,9 @@
  * @module
  */
 import { mapStrings } from '../kernel/engine/tree.js';
+import { sanitizeTurnBlobsForProfile } from '../kernel/registry/attachments.js';
 import { getProfile } from '../kernel/registry/profiles.js';
 import { applySpans } from '../observability/spans.js';
-import { sanitizeTurnBlobsForProfile } from '../providers/attachments.js';
 import { injectionSpans } from './injection.js';
 import { sensitiveSpans } from './sensitive.js';
 /** Sanitize one text value using prompt-injection and sensitive-data detectors. */

package/esm/src/host/mint-trace.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Host cutout-trace helpers for apps that mint a final audit row after an
+ * upstream side effect (for example image cutout).
+ *
+ * Prefer importing from `theorum/host`.
+ *
+ * @module
+ */
+import { type TraceSink } from '../observability/trace.js';
+import type { TraceRecord } from '../observability/trace-record.js';
+interface CutoutTape {
+    ok: boolean;
+    ms: number;
+    url?: string;
+    inSha256?: string;
+    outSha256?: string;
+    http?: unknown;
+    error?: string;
+}
+declare function flushMintTrace(args: {
+    held: TraceRecord[];
+    app: Record<string, unknown>;
+    cutout: CutoutTape;
+    sink?: TraceSink;
+}): Promise<void>;
+export type { CutoutTape };
+export { flushMintTrace };

package/esm/src/host/mint-trace.js

@@ -0,0 +1,33 @@
+/**
+ * Host cutout-trace helpers for apps that mint a final audit row after an
+ * upstream side effect (for example image cutout).
+ *
+ * Prefer importing from `theorum/host`.
+ *
+ * @module
+ */
+import { publicError, UPSTREAM_FAILED } from '../guardrails/error.js';
+import { noopSink, writeTrace } from '../observability/trace.js';
+function attachMint(row, app, cutout) {
+    row.app = app;
+    row.cutout = cutout;
+    row.ms = Date.now() - row.ts;
+    if (!cutout.ok) {
+        row.ok = false;
+        const { error: cutoutError } = cutout;
+        let error = cutoutError;
+        if (!error) {
+            error = publicError(UPSTREAM_FAILED);
+        }
+        row.error = error;
+    }
+}
+async function flushMintTrace(args) {
+    const [row] = args.held;
+    if (!row) {
+        return;
+    }
+    attachMint(row, args.app, args.cutout);
+    await writeTrace(args.sink ?? noopSink(), Promise.resolve(row));
+}
+export { flushMintTrace };

package/esm/src/host/mod.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Optional host-application helpers.
+ *
+ * These are not part of the turn kernel. They exist for Deno HTTP hosts that
+ * want shared reply status mapping and cutout-trace flushing without re-
+ * implementing the same glue in every app route.
+ *
+ * @module
+ */
+import "../../_dnt.polyfills.js";
+export type { CutoutTape } from './mint-trace.js';
+export { flushMintTrace } from './mint-trace.js';
+export { caughtStatus, HTTP_BUSY, HTTP_METHOD, HTTP_NOT_FOUND, HTTP_OK, json, } from './reply.js';

package/esm/src/host/mod.js

@@ -0,0 +1,12 @@
+/**
+ * Optional host-application helpers.
+ *
+ * These are not part of the turn kernel. They exist for Deno HTTP hosts that
+ * want shared reply status mapping and cutout-trace flushing without re-
+ * implementing the same glue in every app route.
+ *
+ * @module
+ */
+import "../../_dnt.polyfills.js";
+export { flushMintTrace } from './mint-trace.js';
+export { caughtStatus, HTTP_BUSY, HTTP_METHOD, HTTP_NOT_FOUND, HTTP_OK, json, } from './reply.js';

package/esm/src/host/reply.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Optional Deno HTTP reply helpers for host applications.
+ *
+ * Not part of the turn kernel. Prefer importing from `theorum/host`.
+ *
+ * @module
+ */
+declare const HTTP_BUSY = 429;
+declare const HTTP_OK = 200;
+declare const HTTP_NOT_FOUND = 404;
+declare const HTTP_METHOD = 405;
+declare function json(status: number, body: unknown, cors: Record<string, string>): Response;
+declare function caughtStatus(err: unknown): number;
+export { caughtStatus, HTTP_BUSY, HTTP_METHOD, HTTP_NOT_FOUND, HTTP_OK, json };

package/esm/src/host/reply.js

@@ -0,0 +1,27 @@
+/**
+ * Optional Deno HTTP reply helpers for host applications.
+ *
+ * Not part of the turn kernel. Prefer importing from `theorum/host`.
+ *
+ * @module
+ */
+import { TheorumError } from '../guardrails/error.js';
+const HTTP_BAD = 400;
+const HTTP_BUSY = 429;
+const HTTP_ERR = 500;
+const HTTP_OK = 200;
+const HTTP_NOT_FOUND = 404;
+const HTTP_METHOD = 405;
+function json(status, body, cors) {
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: { ...cors, 'Content-Type': 'application/json' },
+    });
+}
+function caughtStatus(err) {
+    if (err instanceof TheorumError) {
+        return HTTP_BAD;
+    }
+    return HTTP_ERR;
+}
+export { caughtStatus, HTTP_BUSY, HTTP_METHOD, HTTP_NOT_FOUND, HTTP_OK, json };

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

@@ -35,6 +35,18 @@ function eventsFromImage(delta) {
     }
     return [];
 }
+function eventsFromAudio(delta) {
+    const media = deltaMedia(delta);
+    if (media) {
+        return [media];
+    }
+    // Google TTS deltas may ship data without a mime; treat as raw PCM.
+    const { data } = delta;
+    if (typeof data === 'string' && data) {
+        return [{ type: 'media', media: { mimeType: 'audio/pcm', data } }];
+    }
+    return [];
+}
 function eventsFromDelta(deltaValue) {
     const delta = asRecord(deltaValue);
     if (!delta) {
@@ -50,6 +62,9 @@ function eventsFromDelta(deltaValue) {
     if (deltaType === 'image') {
         return eventsFromImage(delta);
     }
+    if (deltaType === 'audio' || deltaType === 'output_audio') {
+        return eventsFromAudio(delta);
+    }
     return [];
 }
 function mediaFromRecord(rec) {
@@ -65,7 +80,7 @@ function mediaFromOutputItem(item) {
     if (!rec) {
         return undefined;
     }
-    if (rec.type !== 'image' && rec.type !== 'media') {
+    if (rec.type !== 'image' && rec.type !== 'media' && rec.type !== 'audio') {
         return undefined;
     }
     return mediaFromRecord(rec);
@@ -84,13 +99,25 @@ function mediaFromOutputs(outputs) {
 }
 function mediaFromComplete(event) {
     const interaction = asRecord(event.interaction) ?? event;
-    const direct = asRecord(interaction.output_image);
-    if (direct) {
-        const media = mediaFromRecord(direct);
+    const directImage = asRecord(interaction.output_image);
+    if (directImage) {
+        const media = mediaFromRecord(directImage);
         if (media) {
             return media;
         }
     }
+    const directAudio = asRecord(interaction.output_audio);
+    if (directAudio) {
+        const media = mediaFromRecord(directAudio);
+        if (media) {
+            return media;
+        }
+        // Google TTS convenience field: base64 PCM without mime.
+        const { data } = directAudio;
+        if (typeof data === 'string' && data) {
+            return { type: 'media', media: { mimeType: 'audio/pcm', data } };
+        }
+    }
     return mediaFromOutputs(interaction.outputs);
 }
 function sourceFromMaps(maps) {

package/esm/src/kernel/engine/repair.d.ts

@@ -1,9 +1,7 @@
 import type { Profile, TurnHistoryMessage, TurnRepairRequest } from '../types.js';
-declare const MAX_REPAIR_HISTORY_EXCHANGES = 2;
-declare function scopeHistory(history: TurnHistoryMessage[] | undefined): TurnHistoryMessage[];
 declare function synthesizeRepairPrompt(args: {
     profile: Profile;
     repair: TurnRepairRequest;
     history?: TurnHistoryMessage[];
 }): string;
-export { MAX_REPAIR_HISTORY_EXCHANGES, scopeHistory, synthesizeRepairPrompt };
+export { synthesizeRepairPrompt };

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

@@ -35,4 +35,4 @@ function synthesizeRepairPrompt(args) {
     prompt += `3. Return only the corrected assistant output required by the active profile.`;
     return prompt;
 }
-export { MAX_REPAIR_HISTORY_EXCHANGES, scopeHistory, synthesizeRepairPrompt };
+export { synthesizeRepairPrompt };

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

@@ -0,0 +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>;
+export { runAttemptsWithValidation };

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

@@ -0,0 +1,206 @@
+import { publicError } from '../../../guardrails/error.js';
+import { sanitizeTurnRequest } from '../../../guardrails/sanitize.js';
+import { resolveTurn } from '../../registry/resolve.js';
+import { executeAttempt } from './steps.js';
+function collectAttemptText(events) {
+    return events
+        .filter((e) => e.type === 'text' && e.text)
+        .map((e) => e.text)
+        .join('');
+}
+function buildRepairRequest(safe, previousOutput, rejection, repairGuidance) {
+    return {
+        ...safe,
+        input: {
+            ...safe.input,
+            repair: {
+                previousOutput: typeof previousOutput === 'string' ? previousOutput : JSON.stringify(previousOutput),
+                rejection,
+                guidance: repairGuidance,
+            },
+        },
+    };
+}
+function hasValidatableOutput(validation, latestStructured) {
+    if (!validation || latestStructured === undefined) {
+        return false;
+    }
+    const candidateOutput = validation.extract?.(latestStructured) ?? latestStructured;
+    return candidateOutput !== undefined && candidateOutput !== null;
+}
+async function evaluateValidationAttempt(validation, latestStructured, slots) {
+    const candidateOutput = validation.extract?.(latestStructured) ?? latestStructured;
+    const check = await validation.validate(candidateOutput, slots);
+    const error = check.error || check.finding || 'Validation failed';
+    return { candidateOutput, isValid: Boolean(check.isValid), error };
+}
+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' };
+    }
+    if (egress.onBlock === 'refuse_to_user') {
+        return { action: 'refusal', event: { type: 'text', text: result.text } };
+    }
+    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 };
+    }
+    return {
+        action: 'withhold',
+        event: {
+            type: 'error',
+            error: publicError('Turn withheld: egress disclosure violation'),
+        },
+    };
+}
+async function evaluateValidationOutcome(args) {
+    const { validation, latestStructured, request, canRetry } = args;
+    if (!hasValidatableOutput(validation, latestStructured)) {
+        return { action: 'pass' };
+    }
+    const { candidateOutput, isValid, error } = await evaluateValidationAttempt(validation, latestStructured, request.input?.slots);
+    if (isValid) {
+        return { action: 'pass' };
+    }
+    if (canRetry) {
+        const nextRequest = buildRepairRequest(request, candidateOutput, error, validation.repairGuidance);
+        return { action: 'retry', nextRequest };
+    }
+    return {
+        action: 'accept',
+        event: { type: 'structured', structured: latestStructured },
+    };
+}
+function* yieldBufferedAttemptEvents(events) {
+    for (const ev of events) {
+        if (ev.type !== 'tokens') {
+            yield ev;
+        }
+    }
+}
+function updateFlowForRetry(flow, nextReq) {
+    flow.currentAttempt++;
+    flow.currentReq = nextReq;
+    flow.currentGen = resolveTurn(sanitizeTurnRequest(nextReq)).generation;
+}
+async function* handleEgressGate(egress, flow, state, profile, maxRetries) {
+    const canRetry = flow.currentAttempt < maxRetries;
+    const outcome = await evaluateEgressOutcome({
+        egress,
+        attemptEvents: state.attemptEvents,
+        generation: flow.currentGen,
+        request: flow.currentReq,
+        profile,
+        canRetry,
+    });
+    if (outcome.action === 'refusal') {
+        state.allEmittedEvents.push(outcome.event);
+        yield outcome.event;
+        return 'terminal';
+    }
+    if (outcome.action === 'withhold') {
+        yield outcome.event;
+        return 'terminal';
+    }
+    if (outcome.action === 'retry') {
+        updateFlowForRetry(flow, outcome.nextRequest);
+        return 'continue';
+    }
+    return 'pass';
+}
+async function* handleValidationGate(validation, flow, state, latestStructured, maxRetries) {
+    const canRetry = flow.currentAttempt < maxRetries;
+    const outcome = await evaluateValidationOutcome({
+        validation,
+        latestStructured,
+        request: flow.currentReq,
+        canRetry,
+    });
+    if (outcome.action === 'retry') {
+        updateFlowForRetry(flow, outcome.nextRequest);
+        return 'continue';
+    }
+    if (outcome.action === 'accept') {
+        state.allEmittedEvents.push(outcome.event);
+        yield outcome.event;
+        return 'terminal';
+    }
+    return 'pass';
+}
+function gateStatusToAction(status, terminalStatus = 'terminal') {
+    if (status === 'terminal') {
+        return { status: terminalStatus };
+    }
+    if (status === 'continue') {
+        return { status: 'continue' };
+    }
+    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,
+    });
+    if (egress?.enforce) {
+        const status = yield* handleEgressGate(egress, flow, state, profile, maxRetries);
+        const action = gateStatusToAction(status, 'terminal');
+        if (action) {
+            return action;
+        }
+    }
+    if (validation) {
+        const status = yield* handleValidationGate(validation, flow, state, latestStructured, maxRetries);
+        const action = gateStatusToAction(status, 'success');
+        if (action) {
+            return action;
+        }
+    }
+    if (validation || egress?.enforce) {
+        yield* yieldBufferedAttemptEvents(state.attemptEvents);
+    }
+    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);
+    const flow = {
+        currentAttempt: 0,
+        currentGen: generation,
+        currentReq: safe,
+    };
+    while (flow.currentAttempt <= maxRetries) {
+        const step = yield* executeSingleAttemptCycle({
+            flow,
+            state,
+            profile,
+            system,
+            provider,
+            gemini,
+            maxRetries,
+        });
+        if (step.status === 'terminal' || step.status === 'success') {
+            break;
+        }
+    }
+}
+export { runAttemptsWithValidation };