theorum 0.1.5 → 0.1.7

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`.
@@ -181,6 +181,7 @@ export interface Profile {
 
 ### Per-turn Interactions state
 - `TurnRequest.input`: Optional turn input object. If omitted, Theorum normalizes it to an empty input and still runs the profile/provider turn.
+- `TurnRequest.signal`: Optional `AbortSignal`. When aborted, THEORUM stops the turn and cancels in-flight provider HTTP (Gemini fetch, OpenRouter `abortSignal`, speech fetch). Traces mark `cancelled: true`.
 - `TurnRequest.previousInteractionId`: Optional Google Interactions server-side conversation pointer. Theorum passes it through as `previous_interaction_id` for profiles using `geminiInteractions`.
 - `TurnRequest.store`: Optional Google Interactions storage override. If omitted, Theorum does not send `store`; provider/project policy remains the authority. If supplied, Theorum serializes the explicit boolean.
 

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, isAbortError, publicError, TheorumError, throwIfAborted, 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, isAbortError, publicError, TheorumError, throwIfAborted, 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

@@ -28,6 +28,12 @@ declare const PUBLIC_FILE_SIZE = "That file is too large.";
 declare const PUBLIC_FILE_COUNT = "Too many files for one message.";
 /** Safe copy for unsupported generated image dimensions. */
 declare const PUBLIC_IMAGE_SIZE = "That image size isn't supported.";
+/** Safe copy when the host aborts a turn. */
+declare const PUBLIC_CANCELLED = "Cancelled.";
+/** True when `err` is an abort (DOMException or Error named AbortError). */
+declare function isAbortError(err: unknown): boolean;
+/** Throw if `signal` is already aborted. */
+declare function throwIfAborted(signal?: AbortSignal): void;
 /** Convert an unknown thrown value or internal message to user-safe text. */
 declare function publicError(err: unknown): string;
 /** Raw diagnostic text for hosts, traces, and logs (never shown to end users). */
@@ -42,4 +48,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, isAbortError, PUBLIC_ACTION, PUBLIC_CANARY, PUBLIC_CANCELLED, PUBLIC_FILE_COUNT, PUBLIC_FILE_SIZE, PUBLIC_FILE_TYPE, PUBLIC_GENERIC, PUBLIC_IMAGE_SIZE, PUBLIC_UNAVAILABLE, publicError, TheorumError, throwIfAborted, toErrorEvent, UPSTREAM_FAILED, };

package/esm/src/guardrails/error.js

@@ -31,10 +31,33 @@ const PUBLIC_FILE_SIZE = 'That file is too large.';
 const PUBLIC_FILE_COUNT = 'Too many files for one message.';
 /** Safe copy for unsupported generated image dimensions. */
 const PUBLIC_IMAGE_SIZE = "That image size isn't supported.";
+/** Safe copy when the host aborts a turn. */
+const PUBLIC_CANCELLED = 'Cancelled.';
+/** True when `err` is an abort (DOMException or Error named AbortError). */
+function isAbortError(err) {
+    if (!err || typeof err !== 'object') {
+        return false;
+    }
+    const name = err.name;
+    return name === 'AbortError';
+}
+/** Throw if `signal` is already aborted. */
+function throwIfAborted(signal) {
+    if (!signal?.aborted) {
+        return;
+    }
+    const { reason } = signal;
+    if (isAbortError(reason)) {
+        throw reason;
+    }
+    throw new DOMException('The operation was aborted.', 'AbortError');
+}
 const EXACT = {
     [UPSTREAM_FAILED]: PUBLIC_UNAVAILABLE,
     'empty Gemini stream': PUBLIC_UNAVAILABLE,
     'canary leaked': PUBLIC_CANARY,
+    'The operation was aborted.': PUBLIC_CANCELLED,
+    'This operation was aborted': PUBLIC_CANCELLED,
     'Turn withheld: egress disclosure violation': PUBLIC_CANARY,
     'expected JSON object': 'Something was wrong with that request.',
     'user input cannot be placed in the system block': PUBLIC_GENERIC,
@@ -98,8 +121,12 @@ const ALREADY_PUBLIC = new Set([
     PUBLIC_FILE_SIZE,
     PUBLIC_FILE_COUNT,
     PUBLIC_IMAGE_SIZE,
+    PUBLIC_CANCELLED,
 ]);
 function publicText(text) {
+    if (/aborted/i.test(text)) {
+        return PUBLIC_CANCELLED;
+    }
     if (ALREADY_PUBLIC.has(text)) {
         return text;
     }
@@ -116,6 +143,9 @@ function publicText(text) {
 }
 /** Convert an unknown thrown value or internal message to user-safe text. */
 function publicError(err) {
+    if (isAbortError(err)) {
+        return PUBLIC_CANCELLED;
+    }
     if (typeof err === 'string') {
         return publicText(err);
     }
@@ -146,4 +176,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, isAbortError, PUBLIC_ACTION, PUBLIC_CANARY, PUBLIC_CANCELLED, PUBLIC_FILE_COUNT, PUBLIC_FILE_SIZE, PUBLIC_FILE_TYPE, PUBLIC_GENERIC, PUBLIC_IMAGE_SIZE, PUBLIC_UNAVAILABLE, publicError, TheorumError, throwIfAborted, 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, isAbortError, PUBLIC_ACTION, PUBLIC_CANARY, PUBLIC_CANCELLED, PUBLIC_FILE_COUNT, PUBLIC_FILE_SIZE, PUBLIC_FILE_TYPE, PUBLIC_GENERIC, PUBLIC_IMAGE_SIZE, PUBLIC_UNAVAILABLE, publicError, TheorumError, throwIfAborted, 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, isAbortError, PUBLIC_ACTION, PUBLIC_CANARY, PUBLIC_CANCELLED, PUBLIC_FILE_COUNT, PUBLIC_FILE_SIZE, PUBLIC_FILE_TYPE, PUBLIC_GENERIC, PUBLIC_IMAGE_SIZE, PUBLIC_UNAVAILABLE, publicError, TheorumError, throwIfAborted, 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, throwIfAborted, 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' };
 }
@@ -186,6 +191,7 @@ async function* runAttemptsWithValidation(safe, profile, generation, system, pro
         currentReq: safe,
     };
     while (flow.currentAttempt <= maxRetries) {
+        throwIfAborted(safe.signal);
         const step = yield* executeSingleAttemptCycle({
             flow,
             state,

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

@@ -7,6 +7,7 @@
  *
  * @module
  */
+import { throwIfAborted } from '../../../guardrails/error.js';
 import { sanitizeTurnRequest } from '../../../guardrails/sanitize.js';
 import { noopSink, writeTrace } from '../../../observability/trace.js';
 import { buildRecord } from '../../../observability/trace-record.js';
@@ -47,6 +48,7 @@ async function* runTurn(req, provider, sink = noopSink()) {
     let generation;
     try {
         const safe = sanitizeTurnRequest(req);
+        throwIfAborted(safe.signal);
         const { profile, generation: gen } = resolveTurn(safe);
         generation = gen;
         const { model: resolvedModel, geminiBucket, canary: turnCanary } = gen;
@@ -67,12 +69,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

@@ -1,3 +1,4 @@
+import { throwIfAborted } from '../../../guardrails/error.js';
 import { recordStepEvent } from './state.js';
 import { yieldProviderEvents } from './stream.js';
 import { executeDynamicDeclaration, findDynamicDeclaration, formatToolFinding, isActionableDynamicDeclaration, } from './tools.js';
@@ -7,8 +8,11 @@ function isStepLimitReached(step, maxSteps) {
     }
     return step >= maxSteps;
 }
-async function* executeAutonomousStep(args, state, bufferOutputs = false) {
-    const { profile, generation, system, provider, gemini } = args;
+async function* executeAutonomousStep(args, state, buffer = {
+    holdLate: false,
+    holdUserVisible: false,
+}) {
+    const { profile, generation, system, provider, gemini, signal } = args;
     const genForStep = { ...generation, history: state.currentHistory };
     const pendingTools = [];
     let latestStructured;
@@ -18,6 +22,7 @@ async function* executeAutonomousStep(args, state, bufferOutputs = false) {
         system,
         provider,
         gemini,
+        signal,
     })) {
         if (event.type === 'structured') {
             latestStructured = event.structured;
@@ -30,7 +35,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 +106,13 @@ 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)) {
+        throwIfAborted(args.safe.signal);
         stepInAttempt++;
         state.stepCount++;
-        const stepResult = yield* executeAutonomousStep({ profile, generation, system, provider, gemini }, state, shouldBuffer);
+        const stepResult = yield* executeAutonomousStep({ profile, generation, system, provider, gemini, signal: args.safe.signal }, state, { holdLate, holdUserVisible });
         if (stepResult.latestStructured !== undefined) {
             latestStructured = stepResult.latestStructured;
         }

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

@@ -7,5 +7,6 @@ declare function yieldProviderEvents(args: {
     system: string;
     provider: ModelProvider;
     gemini: Record<string, unknown>[];
+    signal?: AbortSignal;
 }): AsyncGenerator<TurnEvent>;
 export { shouldSkipStreamEvent, systemFromProfile, yieldProviderEvents };

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

@@ -1,4 +1,4 @@
-import { publicError, toErrorEvent } from '../../../guardrails/error.js';
+import { publicError, throwIfAborted, toErrorEvent } from '../../../guardrails/error.js';
 import { providerCompleteRequest } from '../../registry/provider-request.js';
 import { eventHasCanary, redactCanary } from '../boundary.js';
 import { dispatchModelTool } from './tools.js';
@@ -51,14 +51,17 @@ function* processNormalEvent(event, profile, generation) {
     }
 }
 async function* yieldProviderEvents(args) {
-    const { profile, generation, system, provider, gemini } = args;
+    const { profile, generation, system, provider, gemini, signal } = args;
     const { canary } = generation;
+    throwIfAborted(signal);
     for await (const event of provider.complete({
         ...providerCompleteRequest(generation, system),
+        signal,
         tapGemini: (row) => {
             gemini.push(row);
         },
     })) {
+        throwIfAborted(signal);
         if (canary && eventHasCanary(event, canary)) {
             yield redactCanary(event, canary);
             yield toErrorEvent('canary leaked');

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;
 }
@@ -383,6 +387,11 @@ export interface TurnRequest {
     dynamicToolLoader?: DynamicToolLoader;
     /** Host-owned metadata preserved for traces; the kernel does not interpret it. */
     metadata?: Record<string, unknown>;
+    /**
+     * Optional abort signal. When aborted, THEORUM stops the turn and cancels
+     * in-flight provider HTTP where the adapter supports it.
+     */
+    signal?: AbortSignal;
     input?: TurnInput;
     toolInvoke?: {
         name: CustomToolId;
@@ -517,6 +526,8 @@ export interface ProviderCompleteRequest extends ProviderGenerationConfig {
     geminiBucket?: GeminiBucket;
     /** Scrubbed SSE / HTTP rows for traces. */
     tapGemini?: (row: Record<string, unknown>) => void;
+    /** Host abort signal — adapters should pass this into fetch / SDK calls. */
+    signal?: AbortSignal;
 }
 /** Minimal adapter contract every model provider must implement. */
 export interface ModelProvider {

package/esm/src/observability/trace-record.js

@@ -6,7 +6,7 @@
  *
  * @module
  */
-import { publicError } from '../guardrails/error.js';
+import { isAbortError, publicError } from '../guardrails/error.js';
 import { sanitizeText, sanitizeTurnRequest } from '../guardrails/sanitize.js';
 import { OMIT_CANARY } from '../kernel/engine/boundary.js';
 import { sha256 } from '../kernel/engine/hash.js';
@@ -109,14 +109,15 @@ async function buildRecord(args) {
     const lastErr = [...snapped].reverse().find((row) => row.type === 'error');
     const done = completedInteraction(gemini);
     const status = done?.status;
-    const ok = !(thrown || lastErr) && status !== 'cancelled';
+    const aborted = isAbortError(thrown);
+    const ok = !(thrown || lastErr) && status !== 'cancelled' && !aborted;
     const record = {
         v: TRACE_VERSION,
         id: crypto.randomUUID(),
         ts: started,
         ms: Date.now() - started,
         streamed: true,
-        cancelled: status === 'cancelled',
+        cancelled: status === 'cancelled' || aborted,
         previousInteractionId: safe.previousInteractionId ?? null,
         store: safe.store ?? null,
         profile: safe.profile,

package/esm/src/providers/keys.js

@@ -6,7 +6,7 @@
  *
  * @module
  */
-import { TheorumError, UPSTREAM_FAILED } from '../guardrails/error.js';
+import { isAbortError, TheorumError, UPSTREAM_FAILED } from '../guardrails/error.js';
 const ATTEMPTS = 3;
 const LAST_ATTEMPT = ATTEMPTS - 1;
 const BACKOFF_FIRST_MS = 1000;
@@ -39,6 +39,9 @@ function isTransientHttp(status) {
         status === HTTP_GATEWAY_TIMEOUT);
 }
 function isTransientThrown(err) {
+    if (isAbortError(err)) {
+        return false;
+    }
     return TRANSIENT_THROWN_RE.test(String(err));
 }
 function requireKey(vault, bucket) {
@@ -56,7 +59,9 @@ async function runWithBackoff(apiKey, run, wait, attempt) {
         return await run(apiKey);
     }
     catch (err) {
-        if (!(isQuota(err) || isTransientThrown(err)) || attempt === LAST_ATTEMPT) {
+        if (isAbortError(err) ||
+            !(isQuota(err) || isTransientThrown(err)) ||
+            attempt === LAST_ATTEMPT) {
             throw err;
         }
         await wait(backoffMs(attempt));
@@ -103,11 +108,16 @@ async function fetchWithBackoff(args) {
         if (!isTransientHttp(last.status) || args.attempt === LAST_ATTEMPT) {
             return last;
         }
+        if (args.init.signal?.aborted) {
+            throw args.init.signal.reason instanceof Error
+                ? args.init.signal.reason
+                : new DOMException('The operation was aborted.', 'AbortError');
+        }
         await wait(backoffMs(args.attempt));
         return fetchWithBackoff({ ...args, attempt: args.attempt + 1 });
     }
     catch (err) {
-        if (!isTransientThrown(err) || args.attempt === LAST_ATTEMPT) {
+        if (isAbortError(err) || !isTransientThrown(err) || args.attempt === LAST_ATTEMPT) {
             throw err;
         }
         await wait(backoffMs(args.attempt));

package/esm/src/providers/openrouter.js

@@ -9,7 +9,7 @@
  */
 import { createOpenRouter } from '@openrouter/ai-sdk-provider';
 import { jsonSchema, streamText, tool, } from 'ai';
-import { toErrorEvent } from '../guardrails/error.js';
+import { isAbortError, toErrorEvent } from '../guardrails/error.js';
 import { tryStructured } from '../kernel/engine/delta.js';
 import { getTool } from '../kernel/registry/catalog.js';
 import { resolveOpenRouterModel, toOpenRouterPayload, } from './openrouter-payload.js';
@@ -499,6 +499,7 @@ function streamTextOptions(req, context) {
         tools: buildTools(req.dynamicTools),
         providerOptions: providerOptionsFor(req),
         includeRawChunks: true,
+        abortSignal: req.signal,
         onError: () => undefined,
     };
 }
@@ -544,6 +545,9 @@ async function* streamOpenRouter(req, config) {
         yield* finalEvents(req, acc);
     }
     catch (err) {
+        if (isAbortError(err)) {
+            throw err;
+        }
         yield* yieldCapturedRawEventsUnchecked(context);
         yield toErrorEvent(err);
     }

package/esm/src/providers/provider.js

@@ -8,7 +8,7 @@
  *
  * @module
  */
-import { TheorumError, toErrorEvent } from '../guardrails/error.js';
+import { isAbortError, TheorumError, toErrorEvent } from '../guardrails/error.js';
 import { eventsFromComplete, eventsFromDelta, extractTokenEvent, groundingFromEvent, tryStructured, } from '../kernel/engine/delta.js';
 import { tapFetch } from './google-tap.js';
 import { toInteractionsBody } from './interactions.js';
@@ -121,7 +121,7 @@ async function* streamComplete(req, transport) {
         yield toErrorEvent('missing Gemini vault bucket for Interactions');
         return;
     }
-    const res = await fetchGemini(INTERACTIONS_URL, { method: 'POST', body: JSON.stringify(toInteractionsBody(req)) }, req.geminiBucket, withTap(req, transport));
+    const res = await fetchGemini(INTERACTIONS_URL, { method: 'POST', body: JSON.stringify(toInteractionsBody(req)), signal: req.signal }, req.geminiBucket, withTap(req, transport));
     if (res.status !== HTTP_OK) {
         const errorBody = await res.text().catch(() => '');
         yield toErrorEvent(`Gemini HTTP ${String(res.status)}: ${errorBody}`);
@@ -148,6 +148,9 @@ async function* streamGuarded(req, transport) {
         yield* streamComplete(req, transport);
     }
     catch (err) {
+        if (isAbortError(err)) {
+            throw err;
+        }
         yield toErrorEvent(err);
     }
 }

package/esm/src/providers/speech.js

@@ -68,6 +68,7 @@ async function requestSpeech(apiKey, text, req, config) {
         method: 'POST',
         headers: buildHeaders(apiKey, config),
         body: JSON.stringify(buildPayload(req, text, req.speech, config.voice)),
+        signal: req.signal,
     });
 }
 function* yieldSpeechSuccess(rawBytes, text, format) {

package/package.json

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