theorum 0.1.5 → 0.1.6

package/docs/AGENT_PROFILE_CONTRACT.md

@@ -169,8 +169,8 @@ export interface Profile {
 - `outputs.structured`: Structured JSON schema specification (or slot-based schema routing).
 - `outputs.image`: Pins for an image-role profile (`aspectRatio`, `size`, `mimeType`, optional `allowsGrounding`, `maxInputImages`). The image model itself is selected via `model.allow` / `model.config`. Slot overrides use `slots.aspectRatio` / `slots.size` when the profile lists allowlists under `inputs.slots`. Adapters map `size` to provider wire keys (e.g. Google Interactions `imageSize`).
 - `outputs.speech`: Pins for a speech-role profile (`voice`, optional `format: 'pcm' | 'mp3'`). The speech model itself is selected via `model.allow` / `model.config`. Bind with `createProvider(profile, …)` — same door as chat/image. `geminiInteractions` uses Interactions (`response_format: audio` + `speech_config`); `openAi`/`openrouter` speech roles use `/audio/speech` with the same `openRouter` credentials. `format: 'pcm'` (default) yields WAV media on both. `format: 'mp3'` is only valid on `openAi` speech — Interactions rejects it at resolve.
-- `outputs.validation`: In-harness auto-correction validator (`validate`, optional `extract`, `maxRetries`, `repairGuidance`). If `extract` is omitted, the structured output itself is validated.
-- `outputs.streaming`: SSE streaming behaviors (`streamThoughts`, `gateMedia`). `gateMedia` controls whether stream `media` events are held until validation/egress — unrelated to a profile output flag.
+- `outputs.validation`: Schema-driven in-harness auto-correction. Required vs optional comes only from the structured JSON Schema. Host `fields` validators (dotted paths such as `diagram.mermaid`) run for required paths and for optional paths that are present. Omitted optional paths are skipped. Setting `validation` without a structured `jsonSchema` is an error.
+- `outputs.streaming`: SSE streaming behaviors (`streamThoughts`, `gateMedia`). `gateMedia` holds stream `media` events until validation/egress. With validation only, thought and text still stream live (structured is held until accepted). With egress enforcement, user-visible thought/text stay buffered until the egress gate passes.
 
 ### `guardrails`
 - `guardrails.quota.perDay`: Optional daily turn quota enforced per client IP. If omitted, quota enforcement is explicitly `not_configured`.

package/esm/mod.d.ts

@@ -37,7 +37,7 @@
  * @module
  */
 import "./_dnt.polyfills.js";
-export { publicError, describeError, TheorumError, toErrorEvent } from './src/guardrails/error.js';
+export { describeError, publicError, TheorumError, toErrorEvent } from './src/guardrails/error.js';
 export type { QuotaSlotStatus } from './src/guardrails/quota.js';
 export { clientIp, quotaMessage, releaseSlot, resetSlots, skipQuota, takeSlot, } from './src/guardrails/quota.js';
 export { PROJECT_ID_MAX, sanitizeProjectId, sanitizeText, sanitizeTurnRequest, } from './src/guardrails/sanitize.js';

package/esm/mod.js

@@ -37,7 +37,7 @@
  * @module
  */
 import "./_dnt.polyfills.js";
-export { publicError, describeError, TheorumError, toErrorEvent } from './src/guardrails/error.js';
+export { describeError, publicError, TheorumError, toErrorEvent } from './src/guardrails/error.js';
 export { clientIp, quotaMessage, releaseSlot, resetSlots, skipQuota, takeSlot, } from './src/guardrails/quota.js';
 export { PROJECT_ID_MAX, sanitizeProjectId, sanitizeText, sanitizeTurnRequest, } from './src/guardrails/sanitize.js';
 export { runTurn } from './src/kernel/engine/runner.js';

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

@@ -42,4 +42,4 @@ declare function toErrorEvent(err: unknown): {
     error: string;
     errorInternal: string;
 };
-export { PUBLIC_ACTION, PUBLIC_CANARY, PUBLIC_FILE_COUNT, PUBLIC_FILE_SIZE, PUBLIC_FILE_TYPE, PUBLIC_GENERIC, PUBLIC_IMAGE_SIZE, PUBLIC_UNAVAILABLE, describeError, publicError, TheorumError, toErrorEvent, UPSTREAM_FAILED, };
+export { describeError, PUBLIC_ACTION, PUBLIC_CANARY, PUBLIC_FILE_COUNT, PUBLIC_FILE_SIZE, PUBLIC_FILE_TYPE, PUBLIC_GENERIC, PUBLIC_IMAGE_SIZE, PUBLIC_UNAVAILABLE, publicError, TheorumError, toErrorEvent, UPSTREAM_FAILED, };

package/esm/src/guardrails/error.js

@@ -146,4 +146,4 @@ function toErrorEvent(err) {
         errorInternal: describeError(err),
     };
 }
-export { PUBLIC_ACTION, PUBLIC_CANARY, PUBLIC_FILE_COUNT, PUBLIC_FILE_SIZE, PUBLIC_FILE_TYPE, PUBLIC_GENERIC, PUBLIC_IMAGE_SIZE, PUBLIC_UNAVAILABLE, describeError, publicError, TheorumError, toErrorEvent, UPSTREAM_FAILED, };
+export { describeError, PUBLIC_ACTION, PUBLIC_CANARY, PUBLIC_FILE_COUNT, PUBLIC_FILE_SIZE, PUBLIC_FILE_TYPE, PUBLIC_GENERIC, PUBLIC_IMAGE_SIZE, PUBLIC_UNAVAILABLE, publicError, TheorumError, toErrorEvent, UPSTREAM_FAILED, };

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

@@ -8,7 +8,7 @@
  * @module
  */
 import "../../_dnt.polyfills.js";
-export { PUBLIC_ACTION, PUBLIC_CANARY, PUBLIC_FILE_COUNT, PUBLIC_FILE_SIZE, PUBLIC_FILE_TYPE, PUBLIC_GENERIC, PUBLIC_IMAGE_SIZE, PUBLIC_UNAVAILABLE, describeError, publicError, TheorumError, toErrorEvent, UPSTREAM_FAILED, } from './error.js';
+export { describeError, PUBLIC_ACTION, PUBLIC_CANARY, PUBLIC_FILE_COUNT, PUBLIC_FILE_SIZE, PUBLIC_FILE_TYPE, PUBLIC_GENERIC, PUBLIC_IMAGE_SIZE, PUBLIC_UNAVAILABLE, publicError, TheorumError, toErrorEvent, UPSTREAM_FAILED, } from './error.js';
 export { injectionSpans } from './injection.js';
 export type { QuotaSlotStatus } from './quota.js';
 export { clientIp, quotaMessage, releaseSlot, resetSlots, skipQuota, takeSlot, } from './quota.js';

package/esm/src/guardrails/mod.js

@@ -8,7 +8,7 @@
  * @module
  */
 import "../../_dnt.polyfills.js";
-export { PUBLIC_ACTION, PUBLIC_CANARY, PUBLIC_FILE_COUNT, PUBLIC_FILE_SIZE, PUBLIC_FILE_TYPE, PUBLIC_GENERIC, PUBLIC_IMAGE_SIZE, PUBLIC_UNAVAILABLE, describeError, publicError, TheorumError, toErrorEvent, UPSTREAM_FAILED, } from './error.js';
+export { describeError, PUBLIC_ACTION, PUBLIC_CANARY, PUBLIC_FILE_COUNT, PUBLIC_FILE_SIZE, PUBLIC_FILE_TYPE, PUBLIC_GENERIC, PUBLIC_IMAGE_SIZE, PUBLIC_UNAVAILABLE, publicError, TheorumError, toErrorEvent, UPSTREAM_FAILED, } from './error.js';
 export { injectionSpans } from './injection.js';
 export { clientIp, quotaMessage, releaseSlot, resetSlots, skipQuota, takeSlot, } from './quota.js';
 export { PROJECT_ID_MAX, sanitizeProjectId, sanitizeText, sanitizeTurnRequest, } from './sanitize.js';

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

@@ -1,6 +1,8 @@
-import { toErrorEvent } from '../../../guardrails/error.js';
+import { TheorumError, toErrorEvent } from '../../../guardrails/error.js';
 import { sanitizeTurnRequest } from '../../../guardrails/sanitize.js';
 import { resolveTurn } from '../../registry/resolve.js';
+import { getStructured } from '../../registry/schemas.js';
+import { collectValidationFailures, formatValidationFailures } from './schema-validation.js';
 import { executeAttempt } from './steps.js';
 function collectAttemptText(events) {
     return events
@@ -21,19 +23,6 @@ function buildRepairRequest(safe, previousOutput, rejection, 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);
@@ -63,16 +52,25 @@ async function evaluateEgressOutcome(args) {
     };
 }
 async function evaluateValidationOutcome(args) {
-    const { validation, latestStructured, request, canRetry } = args;
-    if (!hasValidatableOutput(validation, latestStructured)) {
+    const { validation, generation, latestStructured, request, canRetry } = args;
+    if (latestStructured === undefined) {
         return { action: 'pass' };
     }
-    const { candidateOutput, isValid, error } = await evaluateValidationAttempt(validation, latestStructured, request.input?.slots);
-    if (isValid) {
+    const structuredId = generation.structured;
+    if (!structuredId) {
+        throw new TheorumError('outputs.validation requires outputs.structured with a JSON Schema');
+    }
+    const spec = getStructured(structuredId);
+    if (!spec.jsonSchema) {
+        throw new TheorumError(`structured schema '${structuredId}' has no jsonSchema for validation`);
+    }
+    const failures = await collectValidationFailures(spec.jsonSchema, latestStructured, validation.fields, request.input?.slots);
+    if (failures.length === 0) {
         return { action: 'pass' };
     }
+    const error = formatValidationFailures(failures);
     if (canRetry) {
-        const nextRequest = buildRepairRequest(request, candidateOutput, error, validation.repairGuidance);
+        const nextRequest = buildRepairRequest(request, latestStructured, error, validation.repairGuidance);
         return { action: 'retry', nextRequest };
     }
     return {
@@ -80,11 +78,16 @@ async function evaluateValidationOutcome(args) {
         event: { type: 'structured', structured: latestStructured },
     };
 }
-function* yieldBufferedAttemptEvents(events) {
+function* yieldBufferedAttemptEvents(events, alreadyStreamedUserVisible) {
     for (const ev of events) {
-        if (ev.type !== 'tokens') {
-            yield ev;
+        if (ev.type === 'tokens') {
+            continue;
+        }
+        // When validation-only, thought/text already streamed live.
+        if (alreadyStreamedUserVisible && (ev.type === 'thought' || ev.type === 'text')) {
+            continue;
         }
+        yield ev;
     }
 }
 function updateFlowForRetry(flow, nextReq) {
@@ -121,6 +124,7 @@ async function* handleValidationGate(validation, flow, state, latestStructured,
     const canRetry = flow.currentAttempt < maxRetries;
     const outcome = await evaluateValidationOutcome({
         validation,
+        generation: flow.currentGen,
         latestStructured,
         request: flow.currentReq,
         canRetry,
@@ -174,7 +178,8 @@ async function* executeSingleAttemptCycle(args) {
         }
     }
     if (validation || egress?.enforce) {
-        yield* yieldBufferedAttemptEvents(state.attemptEvents);
+        const alreadyStreamedUserVisible = !egress?.enforce;
+        yield* yieldBufferedAttemptEvents(state.attemptEvents, alreadyStreamedUserVisible);
     }
     return { status: 'success' };
 }

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

@@ -67,12 +67,6 @@ async function* runTurn(req, provider, sink = noopSink()) {
             gemini,
         })) {
             seen.push(event);
-            if (event.type === 'error') {
-                const detail = event.errorInternal ?? event.error;
-                if (detail) {
-                    console.error(`[theorum] turn error (${req.profile}): ${detail}`);
-                }
-            }
             if (shouldSkipStreamEvent(event, profile)) {
                 continue;
             }

package/esm/src/kernel/engine/runner/schema-validation.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Schema-driven structured-output validation.
+ *
+ * Required vs optional comes only from the JSON Schema. Host field validators
+ * run for required paths and for optional paths that are present.
+ *
+ * @module
+ */
+import type { ProfileValidator } from '../../types.js';
+interface ValidationFailure {
+    path: string;
+    error: string;
+}
+declare function isAbsent(value: unknown): boolean;
+/**
+ * Collect schema presence failures and host field-validator failures.
+ * Throws when the root schema is not an object schema.
+ */
+declare function collectValidationFailures(jsonSchema: Record<string, unknown>, structured: unknown, fields: Record<string, ProfileValidator> | undefined, slots?: Record<string, string>): Promise<ValidationFailure[]>;
+declare function formatValidationFailures(failures: ValidationFailure[]): string;
+export type { ValidationFailure };
+export { collectValidationFailures, formatValidationFailures, isAbsent };

package/esm/src/kernel/engine/runner/schema-validation.js

@@ -0,0 +1,113 @@
+/**
+ * Schema-driven structured-output validation.
+ *
+ * Required vs optional comes only from the JSON Schema. Host field validators
+ * run for required paths and for optional paths that are present.
+ *
+ * @module
+ */
+import { TheorumError } from '../../../guardrails/error.js';
+function isAbsent(value) {
+    return value === undefined || value === null;
+}
+function asRecord(value) {
+    if (isAbsent(value) || typeof value !== 'object' || Array.isArray(value)) {
+        return null;
+    }
+    return value;
+}
+function asObjectSchema(schema) {
+    const rec = asRecord(schema);
+    if (!rec) {
+        return null;
+    }
+    if (rec.type !== undefined && rec.type !== 'object') {
+        return null;
+    }
+    return rec;
+}
+function requiredKeys(schema) {
+    const raw = schema.required;
+    if (!Array.isArray(raw)) {
+        return [];
+    }
+    return raw.filter((k) => typeof k === 'string');
+}
+function propertySchemas(schema) {
+    const props = schema.properties;
+    return asRecord(props) ?? {};
+}
+function joinPath(prefix, key) {
+    return prefix ? `${prefix}.${key}` : key;
+}
+function pushMissing(path, failures) {
+    failures.push({ path, error: `required field '${path}' is missing` });
+}
+async function runFieldValidator(path, value, validator, slots, failures) {
+    if (!validator) {
+        return;
+    }
+    const check = await validator(value, slots);
+    if (check.isValid) {
+        return;
+    }
+    failures.push({
+        path,
+        error: check.error || check.finding || `Validation failed for '${path}'`,
+    });
+}
+async function visitProperty(args) {
+    const { path, propSchema, child, isRequired, fields, slots, failures } = args;
+    if (isAbsent(child)) {
+        if (isRequired) {
+            pushMissing(path, failures);
+        }
+        return;
+    }
+    await runFieldValidator(path, child, fields?.[path], slots, failures);
+    const nested = asObjectSchema(propSchema);
+    const nestedValue = nested ? asRecord(child) : null;
+    if (nested && nestedValue) {
+        await walkObject(nested, nestedValue, path, fields, slots, failures);
+    }
+}
+async function walkObject(schema, value, pathPrefix, fields, slots, failures) {
+    const props = propertySchemas(schema);
+    const required = new Set(requiredKeys(schema));
+    const keys = new Set([...Object.keys(props), ...required]);
+    const record = asRecord(value);
+    for (const key of keys) {
+        await visitProperty({
+            path: joinPath(pathPrefix, key),
+            propSchema: props[key],
+            child: record?.[key],
+            isRequired: required.has(key),
+            fields,
+            slots,
+            failures,
+        });
+    }
+}
+/**
+ * Collect schema presence failures and host field-validator failures.
+ * Throws when the root schema is not an object schema.
+ */
+async function collectValidationFailures(jsonSchema, structured, fields, slots) {
+    const root = asObjectSchema(jsonSchema);
+    if (!root) {
+        throw new TheorumError('structured validation requires a JSON Schema object root');
+    }
+    const failures = [];
+    if (!asRecord(structured)) {
+        for (const key of requiredKeys(root)) {
+            pushMissing(key, failures);
+        }
+        return failures;
+    }
+    await walkObject(root, structured, '', fields, slots, failures);
+    return failures;
+}
+function formatValidationFailures(failures) {
+    return failures.map((f) => f.error).join('; ');
+}
+export { collectValidationFailures, formatValidationFailures, isAbsent };

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

@@ -7,7 +7,10 @@ function isStepLimitReached(step, maxSteps) {
     }
     return step >= maxSteps;
 }
-async function* executeAutonomousStep(args, state, bufferOutputs = false) {
+async function* executeAutonomousStep(args, state, buffer = {
+    holdLate: false,
+    holdUserVisible: false,
+}) {
     const { profile, generation, system, provider, gemini } = args;
     const genForStep = { ...generation, history: state.currentHistory };
     const pendingTools = [];
@@ -30,7 +33,11 @@ async function* executeAutonomousStep(args, state, bufferOutputs = false) {
             continue;
         }
         recordStepEvent(event, state);
-        if (!bufferOutputs || event.type === 'tokens') {
+        const isUserVisible = event.type === 'thought' || event.type === 'text';
+        // Egress must not stream user-visible text before the gate runs.
+        // Validation-only may stream thought/text live and only hold structured.
+        const streamNow = !buffer.holdLate || event.type === 'tokens' || (isUserVisible && !buffer.holdUserVisible);
+        if (streamNow) {
             yield event;
         }
     }
@@ -97,11 +104,12 @@ async function* executeAttempt(args) {
     let latestStructured;
     let pendingTools = [];
     let stepInAttempt = 0;
-    const shouldBuffer = Boolean(profile.outputs.validation) || Boolean(profile.guardrails.egress?.enforce);
+    const holdUserVisible = Boolean(profile.guardrails.egress?.enforce);
+    const holdLate = Boolean(profile.outputs.validation) || holdUserVisible;
     while (!isStepLimitReached(stepInAttempt, generation.maxSteps)) {
         stepInAttempt++;
         state.stepCount++;
-        const stepResult = yield* executeAutonomousStep({ profile, generation, system, provider, gemini }, state, shouldBuffer);
+        const stepResult = yield* executeAutonomousStep({ profile, generation, system, provider, gemini }, state, { holdLate, holdUserVisible });
         if (stepResult.latestStructured !== undefined) {
             latestStructured = stepResult.latestStructured;
         }

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

@@ -140,8 +140,12 @@ export interface ValidationResult {
 export type ProfileValidator = (candidate: unknown, slots?: Record<string, string>) => ValidationResult | Promise<ValidationResult>;
 /** Profile output validation and deterministic repair configuration. */
 export interface ProfileValidationSpec {
-    extract?: (structured: unknown) => unknown;
-    validate: ProfileValidator;
+    /**
+     * Host domain validators keyed by dotted paths into structured output
+     * (e.g. `diagram.mermaid`). Presence/required is owned by the JSON Schema;
+     * these run only for required paths and for optional paths that are present.
+     */
+    fields?: Record<string, ProfileValidator>;
     maxRetries?: number;
     repairGuidance?: string;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "theorum",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "A flat TypeScript agent kernel for typed profiles, deterministic turn execution, dynamic tools, provider adapters, guardrails, and host-injected traces.",
   "keywords": [
     "agent",