theorum 0.1.14 → 1.0.0

package/esm/src/kernel/registry/ingress.js

@@ -5,82 +5,72 @@
  *
  * @module
  */
+import { wrapUserData } from '../../guardrails/canary.js';
 import { TheorumError } from '../../guardrails/error.js';
-import { wrapUserData } from '../engine/boundary.js';
 import { synthesizeRepairPrompt } from '../engine/repair.js';
 import { assertAttachmentLimits, requireMediaLimits } from './attachments.js';
 import { mediaKindForMime, mimeAllowed, mimeEssence } from './catalog.js';
-function listedValue(allowed, value) {
-    if (!value) {
-        return undefined;
-    }
-    if (!allowed || allowed.length === 0) {
-        return value;
-    }
-    if (allowed.includes(value)) {
-        return value;
+import { getStructured } from './schemas.js';
+function usesStructuredResponseFormat(structuredId) {
+    if (!structuredId) {
+        return false;
     }
-    return undefined;
+    const spec = getStructured(structuredId);
+    return spec.enforced === 'responseFormat' && spec.jsonSchema != null;
 }
-function resolveSlotOrPin(profileId, label, slotValue, pin, allow) {
-    if (slotValue !== undefined) {
-        const fromSlot = listedValue(allow, slotValue);
-        if (!fromSlot) {
-            throw new TheorumError(`Unknown image ${label} for ${profileId}`);
-        }
-        return fromSlot;
+function activePrimaryOutputModes(profile, structuredId) {
+    const modes = [];
+    if (usesStructuredResponseFormat(structuredId)) {
+        modes.push('structured');
     }
-    if (pin === undefined) {
-        return undefined;
+    if (profile.type === 'image') {
+        modes.push('image');
+    }
+    if (profile.type === 'speech') {
+        modes.push('speech');
     }
-    const fromPin = listedValue(allow, pin);
-    if (!fromPin) {
-        throw new TheorumError(`Unknown image ${label} for ${profileId}`);
+    return modes;
+}
+/**
+ * Provider wire formats (JSON schema, image, speech) are mutually exclusive.
+ * Typed profiles make illegal mixes unrepresentable; this remains a safety net
+ * for responseFormat structured on text vs accidental dual modes.
+ */
+function assertOutputMode(profile, structuredId) {
+    const active = activePrimaryOutputModes(profile, structuredId);
+    if (active.length <= 1) {
+        return;
     }
-    return fromPin;
+    throw new TheorumError(`Profile ${profile.id} declares multiple output wire formats (${active.join(', ')}). ` +
+        `Only one of responseFormat JSON schema (outputs.structured with enforced ` +
+        `'responseFormat'), image, or speech may be active.`);
 }
-function assertImageRole(profile) {
-    const pins = profile.outputs.image;
-    if (!pins) {
-        throw new TheorumError(`Profile ${profile.id} requests image output but does not set outputs.image`);
+function assertImagePins(profile) {
+    if (profile.type !== 'image') {
+        throw new TheorumError(`Profile ${profile.id} is not type 'image'`);
     }
-    assertExclusiveNativeOutput(profile, 'image');
-    return pins;
+    return profile.image;
 }
 function assertSpeechRole(profile) {
-    if (!profile.outputs.speech) {
+    if (profile.type !== 'speech') {
         return;
     }
-    assertExclusiveNativeOutput(profile, 'speech');
-    if (profile.outputs.speech.format === 'mp3' && profile.model.protocol === 'geminiInteractions') {
-        throw new TheorumError(`Profile ${profile.id}: outputs.speech.format 'mp3' requires protocol 'openAi' ` +
+    if (profile.speech.format === 'mp3' && profile.model.protocol === 'geminiInteractions') {
+        throw new TheorumError(`Profile ${profile.id}: speech.format 'mp3' requires protocol 'openAi' ` +
             `(geminiInteractions speech returns PCM and emits WAV)`);
     }
 }
-function assertExclusiveNativeOutput(profile, kind) {
-    const other = kind === 'image' ? 'speech' : 'image';
-    if (profile.outputs[other]) {
-        throw new TheorumError(`Profile ${profile.id} cannot mix outputs.${kind} with outputs.${other}`);
-    }
-    if (profile.outputs.structured !== null && profile.outputs.structured !== undefined) {
-        throw new TheorumError(`Profile ${profile.id} cannot mix structured JSON with native ${kind} output`);
-    }
-}
-function resolveImageFormat(profile, _model, slots) {
-    if (!profile.outputs.image) {
+function resolveImageFormat(profile) {
+    if (profile.type !== 'image') {
         return null;
     }
-    const pins = assertImageRole(profile);
-    const aspectRatio = resolveSlotOrPin(profile.id, 'aspect', slots?.aspectRatio, pins.aspectRatio, profile.inputs.slots?.aspectRatio);
-    const size = resolveSlotOrPin(profile.id, 'size', slots?.size, pins.size, profile.inputs.slots?.size);
-    if (!(aspectRatio && size)) {
-        throw new TheorumError(`Unknown image aspect or size for ${profile.id}`);
-    }
+    const pins = assertImagePins(profile);
     return {
         type: 'image',
-        mimeType: pins.mimeType ?? 'image/jpeg',
-        aspectRatio,
-        size,
+        mimeType: pins.mimeType,
+        aspectRatio: pins.aspectRatio,
+        size: pins.size,
+        includeText: pins.includeText === true,
     };
 }
 function assertMediaMime(mime) {
@@ -90,12 +80,19 @@ function assertMediaMime(mime) {
     }
     return kind;
 }
+function profileInputs(profile) {
+    if (profile.type === 'speech') {
+        return undefined;
+    }
+    return profile.inputs;
+}
 function mediaParts(profile, model, blobs, channel) {
-    const accept = channel === 'voice' ? profile.inputs.voice?.accept : profile.inputs.attachments?.accept;
+    const inputs = profileInputs(profile);
+    const accept = channel === 'voice' ? inputs?.voice?.accept : inputs?.attachments?.accept;
     if (!accept) {
         throw new TheorumError(`Profile ${profile.id} does not accept ${channel}`);
     }
-    const maxInputImages = profile.outputs.image?.maxInputImages;
+    const maxInputImages = profile.type === 'image' ? profile.image.maxInputImages : undefined;
     const imageCount = blobs.filter((blob) => mediaKindForMime(blob.mimeType) === 'image').length;
     if (maxInputImages !== undefined && imageCount > maxInputImages) {
         throw new TheorumError(`At most ${maxInputImages} reference images on ${model}`);
@@ -115,7 +112,18 @@ function mediaParts(profile, model, blobs, channel) {
 }
 function extractTextPart(profile, req) {
     const { text, repair, history } = req.input ?? {};
-    if (profile.inputs.text === false) {
+    if (profile.type === 'speech') {
+        if (!text?.trim()) {
+            throw new TheorumError(`Profile ${profile.id} (speech) requires text input`);
+        }
+        let promptText = text;
+        if (repair) {
+            promptText = synthesizeRepairPrompt({ profile, repair, history });
+        }
+        return { type: 'text', text: wrapUserData(promptText) };
+    }
+    const inputs = profileInputs(profile);
+    if (inputs?.text === false) {
         if (text) {
             throw new TheorumError(`Profile ${profile.id} does not accept text input`);
         }
@@ -131,6 +139,13 @@ function extractTextPart(profile, req) {
     return { type: 'text', text: wrapUserData(promptText) };
 }
 function extractMediaParts(profile, model, req) {
+    if (profile.type === 'speech') {
+        const { attachments, voice } = req.input ?? {};
+        if ((attachments?.length ?? 0) + (voice?.length ?? 0) > 0) {
+            throw new TheorumError(`Profile ${profile.id} (speech) does not accept media input`);
+        }
+        return [];
+    }
     const { attachments, voice } = req.input ?? {};
     const files = attachments ?? [];
     const clips = voice ?? [];
@@ -155,9 +170,4 @@ function resolveInputParts(profile, model, req) {
     parts.push(...extractMediaParts(profile, model, req));
     return parts;
 }
-function assertImageGrounding(profile, model, builtins) {
-    if (profile.outputs.image?.allowsGrounding === false && builtins.length > 0) {
-        throw new TheorumError(`Grounding tools are not valid on ${model}`);
-    }
-}
-export { assertImageGrounding, assertSpeechRole, resolveImageFormat, resolveInputParts };
+export { assertOutputMode, assertSpeechRole, resolveImageFormat, resolveInputParts };

package/esm/src/kernel/registry/profiles.d.ts

@@ -1,23 +1,46 @@
 /**
  * Runtime profile registry for host-owned THEORUM profiles.
  *
- * THEORUM ships profile types and defaults, not application profiles. Host apps
- * register their profiles at process startup or test setup.
+ * THEORUM ships profile types — not application profiles and not invented defaults.
+ * Hosts must pass required fields explicitly (`type`, `model.protocol`, `model.provider`, …).
  *
  * @module
  */
-import type { Profile } from '../types.js';
-/** Host-authored profile definition, with defaults applied to omitted sections. */
-export type ProfileDefinition = {
+import type { ImageProfile, LiveProfile, LiveProfileModelSpec, Profile, ProfileGuardrailsSpec, ProfileIdentity, ProfileInputsSpec, ProfileModelSpec, ProfileOutputsSpec, ProfileToolsSpec, ProfileTurnResumptionSpec, SpeechProfile, TurnProfileModelSpec } from '../types.js';
+export type ProfileDefinitionBase<P extends ProfileModelSpec = ProfileModelSpec> = {
     id: Profile['id'];
-    identity?: Partial<Profile['identity']>;
-    model: Partial<Profile['model']> & Pick<Profile['model'], 'allow' | 'config'>;
-    tools?: Partial<Profile['tools']>;
-    inputs?: Partial<Profile['inputs']>;
-    outputs?: Partial<Profile['outputs']>;
-    guardrails?: Partial<Profile['guardrails']>;
+    identity: ProfileIdentity;
+    model: P;
+    outputs?: ProfileOutputsSpec;
+    guardrails?: ProfileGuardrailsSpec;
 };
-/** Define a typed profile with stable defaults for optional properties. */
+export type TextProfileDefinition = ProfileDefinitionBase<TurnProfileModelSpec> & {
+    type: 'text';
+    tools: ProfileToolsSpec;
+    inputs: ProfileInputsSpec;
+    turnResumption?: ProfileTurnResumptionSpec;
+};
+export type ImageProfileDefinition = ProfileDefinitionBase<TurnProfileModelSpec> & {
+    type: 'image';
+    image: NonNullable<ImageProfile['image']>;
+    tools: ProfileToolsSpec;
+    inputs: ProfileInputsSpec;
+    turnResumption?: ProfileTurnResumptionSpec;
+};
+export type SpeechProfileDefinition = ProfileDefinitionBase<TurnProfileModelSpec> & {
+    type: 'speech';
+    speech: NonNullable<SpeechProfile['speech']>;
+    turnResumption?: ProfileTurnResumptionSpec;
+};
+export type LiveProfileDefinition = ProfileDefinitionBase<LiveProfileModelSpec> & {
+    type: 'live';
+    live: NonNullable<LiveProfile['live']>;
+    tools: ProfileToolsSpec;
+    inputs?: ProfileInputsSpec;
+};
+/** Host-authored profile definition — discriminated on `type`. No THEORUM defaults. */
+export type ProfileDefinition = TextProfileDefinition | ImageProfileDefinition | SpeechProfileDefinition | LiveProfileDefinition;
+/** Define a typed profile. Required fields must be set explicitly; optional fields stay optional. */
 declare function defineProfile(input: ProfileDefinition): Profile;
 /** Register one host-owned profile in the process-local registry. */
 declare function registerProfile(profileInput: Profile | ProfileDefinition): void;

package/esm/src/kernel/registry/profiles.js

@@ -1,12 +1,14 @@
 /**
  * Runtime profile registry for host-owned THEORUM profiles.
  *
- * THEORUM ships profile types and defaults, not application profiles. Host apps
- * register their profiles at process startup or test setup.
+ * THEORUM ships profile types — not application profiles and not invented defaults.
+ * Hosts must pass required fields explicitly (`type`, `model.protocol`, `model.provider`, …).
  *
  * @module
  */
 import { TheorumError } from '../../guardrails/error.js';
+import { isValidPair, isValidProfileProtocol, protocolsForProfileType } from '../schema.js';
+import { getTool } from '../tools/registry.js';
 const profiles = new Map();
 function assertModelSpecs(profileId, allow, config) {
     for (const id of allow) {
@@ -15,69 +17,96 @@ function assertModelSpecs(profileId, allow, config) {
         }
     }
 }
-function buildDefaultIdentity(id, identity) {
-    return {
-        handle: identity?.handle ?? id,
-        chat: identity?.chat,
-        system: identity?.system,
-        systemByRole: identity?.systemByRole,
-    };
-}
-function buildDefaultModel(profileId, model) {
-    assertModelSpecs(profileId, model.allow, model.config);
-    return {
-        protocol: model.protocol ?? 'geminiInteractions',
-        provider: model.provider ?? 'google',
-        allow: model.allow,
-        config: model.config,
-        thinking: model.thinking ?? 'minimal',
-        controls: model.controls ?? [],
-        maxSteps: model.maxSteps ?? 1,
-        key: model.key ?? 'freeA',
-        select: model.select,
-    };
-}
-function buildDefaultInputs(inputs) {
-    return {
-        text: inputs?.text ?? true,
-        attachments: inputs?.attachments,
-        voice: inputs?.voice,
-        maxFiles: inputs?.maxFiles,
-        maxBytes: inputs?.maxBytes,
-        maxTurnBytes: inputs?.maxTurnBytes,
-        limitsByMime: inputs?.limitsByMime,
-        slots: inputs?.slots,
-    };
-}
-function buildDefaultOutputs(outputs) {
-    return {
-        structured: outputs?.structured ?? null,
-        image: outputs?.image,
-        speech: outputs?.speech,
-        validation: outputs?.validation,
-        streaming: outputs?.streaming,
-    };
+function assertProtocolProvider(profileId, model) {
+    if (!model.protocol) {
+        throw new TheorumError(`Profile ${profileId} must set model.protocol`);
+    }
+    if (!model.provider) {
+        throw new TheorumError(`Profile ${profileId} must set model.provider`);
+    }
+    if (!isValidPair(model.protocol, model.provider)) {
+        throw new TheorumError(`Profile ${profileId}: protocol '${model.protocol}' is not valid for provider '${model.provider}'`);
+    }
 }
-function buildDefaultGuardrails(guardrails) {
-    return {
-        quota: guardrails?.quota,
-        canary: guardrails?.canary ?? true,
-        sanitizeInput: guardrails?.sanitizeInput ?? true,
-        redactSensitive: guardrails?.redactSensitive ?? true,
-        egress: guardrails?.egress,
-    };
+function assertTypeProtocol(profile) {
+    const protocol = profile.model.protocol;
+    if (isValidProfileProtocol(profile.type, protocol))
+        return;
+    const valid = protocolsForProfileType(profile.type).join(', ');
+    throw new TheorumError(`Profile ${profile.id}: type '${profile.type}' cannot use protocol '${protocol}'. Supported: ${valid}`);
 }
-/** Define a typed profile with stable defaults for optional properties. */
+/** Define a typed profile. Required fields must be set explicitly; optional fields stay optional. */
 function defineProfile(input) {
-    return {
-        id: input.id,
-        identity: buildDefaultIdentity(input.id, input.identity),
-        model: buildDefaultModel(input.id, input.model),
-        tools: { allow: input.tools?.allow ?? [] },
-        inputs: buildDefaultInputs(input.inputs),
-        outputs: buildDefaultOutputs(input.outputs),
-        guardrails: buildDefaultGuardrails(input.guardrails),
+    assertProtocolProvider(input.id, input.model);
+    assertModelSpecs(input.id, input.model.allow, input.model.config);
+    const identity = {
+        handle: input.identity.handle,
+        system: input.identity.system,
+        systemByRole: input.identity.systemByRole,
     };
+    const outputs = input.outputs;
+    const guardrails = input.guardrails;
+    let profile;
+    switch (input.type) {
+        case 'text':
+            profile = {
+                type: 'text',
+                id: input.id,
+                identity,
+                model: input.model,
+                tools: input.tools,
+                inputs: input.inputs,
+                outputs,
+                turnResumption: input.turnResumption,
+                guardrails,
+            };
+            break;
+        case 'image':
+            profile = {
+                type: 'image',
+                id: input.id,
+                identity,
+                model: input.model,
+                image: input.image,
+                tools: input.tools,
+                inputs: input.inputs,
+                outputs,
+                turnResumption: input.turnResumption,
+                guardrails,
+            };
+            break;
+        case 'speech':
+            profile = {
+                type: 'speech',
+                id: input.id,
+                identity,
+                model: input.model,
+                speech: input.speech,
+                outputs,
+                turnResumption: input.turnResumption,
+                guardrails,
+            };
+            break;
+        case 'live':
+            profile = {
+                type: 'live',
+                id: input.id,
+                identity,
+                model: input.model,
+                live: input.live,
+                tools: input.tools,
+                inputs: input.inputs,
+                outputs,
+                guardrails,
+            };
+            break;
+        default: {
+            const _exhaustive = input;
+            throw new TheorumError(`Unknown profile type '${String(_exhaustive)}'`);
+        }
+    }
+    assertTypeProtocol(profile);
+    return profile;
 }
 function assertCompactionSpec(profileId, modelId, spec) {
     const tag = `Profile ${profileId} model ${modelId} compaction`;
@@ -111,16 +140,80 @@ function assertCompactionRetain(tag, spec) {
         throw new TheorumError(`${tag}: previousExchanges >= 1 must be an integer`);
     }
 }
-/** Register one host-owned profile in the process-local registry. */
-function registerProfile(profileInput) {
-    const profile = defineProfile(profileInput);
-    assertModelSpecs(profile.id, profile.model.allow, profile.model.config);
-    const { attachments, voice, maxFiles, maxBytes, maxTurnBytes } = profile.inputs;
+function profileToolsAllow(profile) {
+    if (profile.type === 'speech') {
+        return [];
+    }
+    return profile.tools.allow;
+}
+function assertCustomToolsOnly(profile) {
+    for (const id of profileToolsAllow(profile)) {
+        const tool = getTool(id);
+        if (tool?.type === 'builtin') {
+            throw new TheorumError(`Profile ${profile.id} lists builtin '${id}' in tools.allow — declare it on model.config.*.builtInTools instead`);
+        }
+    }
+}
+function assertProfileToolLoader(profile) {
+    if (profile.type === 'speech') {
+        return;
+    }
+    const loaderId = profile.tools.t2Loader;
+    if (!loaderId) {
+        return;
+    }
+    if (!profile.tools.allow.includes(loaderId)) {
+        throw new TheorumError(`Profile ${profile.id} tools.t2Loader '${loaderId}' must also be listed in tools.allow`);
+    }
+    const tool = getTool(loaderId);
+    if (tool?.type !== 'function') {
+        throw new TheorumError(`Profile ${profile.id} tools.t2Loader '${loaderId}' must be a registered type: 'function' tool`);
+    }
+}
+function assertModelBuiltInTools(profile) {
+    for (const [modelId, spec] of Object.entries(profile.model.config)) {
+        for (const id of spec.builtInTools ?? []) {
+            const tool = getTool(id);
+            if (tool?.type !== 'builtin') {
+                throw new TheorumError(`Profile ${profile.id} model '${modelId}' lists '${id}' in builtInTools — not a registered builtin`);
+            }
+        }
+    }
+}
+function assertCompactionOnlyOnText(profile) {
+    if (profile.type === 'text') {
+        return;
+    }
+    for (const [modelId, spec] of Object.entries(profile.model.config)) {
+        if (spec.compaction) {
+            throw new TheorumError(`Profile ${profile.id} model '${modelId}': compaction is only valid on type 'text'`);
+        }
+    }
+}
+function assertMediaLimits(profile) {
+    if (profile.type === 'speech') {
+        return;
+    }
+    const inputs = profile.inputs;
+    if (!inputs) {
+        return;
+    }
+    const { attachments, voice, maxFiles, maxBytes, maxTurnBytes } = inputs;
     if (attachments || voice) {
         if (!(maxFiles && maxBytes && maxTurnBytes)) {
             throw new TheorumError(`Profile ${profile.id} must set maxFiles, maxBytes, and maxTurnBytes`);
         }
     }
+}
+/** Register one host-owned profile in the process-local registry. */
+function registerProfile(profileInput) {
+    const profile = defineProfile(profileInput);
+    assertModelSpecs(profile.id, profile.model.allow, profile.model.config);
+    assertCustomToolsOnly(profile);
+    assertProfileToolLoader(profile);
+    assertModelBuiltInTools(profile);
+    assertCompactionOnlyOnText(profile);
+    assertMediaLimits(profile);
     for (const [modelId, spec] of Object.entries(profile.model.config)) {
         if (spec.compaction) {
             assertCompactionSpec(profile.id, modelId, spec.compaction);

package/esm/src/kernel/registry/provider-request.js

@@ -1,25 +1,29 @@
 /** Build the provider request projection shared by execution and tracing. */
 function providerCompleteRequest(generation, system) {
+    const isInteractions = generation.transport === 'interactions';
     return {
         model: generation.model,
         apiId: generation.apiId,
-        openRouterId: generation.openRouterId,
-        previousInteractionId: generation.previousInteractionId,
-        store: generation.store,
+        previousInteractionId: isInteractions ? generation.previousInteractionId : undefined,
+        store: isInteractions ? generation.store : undefined,
+        stream: isInteractions ? generation.stream : undefined,
         thinking: generation.thinking,
-        summaries: generation.summaries,
+        summaries: isInteractions ? generation.summaries : undefined,
         maxOutputTokens: generation.maxOutputTokens,
         temperature: generation.temperature,
         builtins: generation.builtins,
+        googleMapsLocation: isInteractions ? generation.googleMapsLocation : undefined,
         system,
         input: generation.input,
         history: generation.history,
-        dynamicTools: generation.dynamicTools,
-        dynamicToolLoader: generation.dynamicToolLoader,
+        interactionOnlyInput: isInteractions ? generation.interactionOnlyInput : undefined,
+        wireTools: generation.tools.wire,
         structured: generation.structured,
         image: generation.image,
         speech: generation.speech,
-        geminiBucket: generation.geminiBucket,
+        live: generation.live,
+        sessionResumptionHandle: generation.sessionResumptionHandle,
+        keySlot: generation.keySlot,
     };
 }
 export { providerCompleteRequest };

package/esm/src/kernel/registry/resolve.d.ts

@@ -1,19 +1,18 @@
 /**
  * Profile resolution for THEORUM turns.
  *
- * This module validates caller overrides, selects models and tools, normalizes
- * input parts, and produces the provider request state consumed by `runTurn`.
- *
  * @module
  */
-import type { Profile, ProjectedProfile, ResolvedGeneration, ToolId, TurnRequest } from '../types.js';
-declare function assertToolAllowed(profile: Profile, name: ToolId): void;
+import type { ModelId, Profile, ProjectedProfile, ResolvedGeneration, TurnRequest } from '../types.js';
+declare function pickModel(profile: Profile, select?: string): ModelId;
 /** Resolve a host `TurnRequest` into provider-ready generation state. */
 declare function resolveTurn(req: TurnRequest): {
     profile: Profile;
     generation: ResolvedGeneration;
 };
+/** Project a profile object into a safe host/UI inspection object. */
+declare function projectProfileObject(profile: Profile): ProjectedProfile;
 /** Project a registered profile into a safe host/UI inspection object. */
 declare function projectProfile(id: Profile['id']): ProjectedProfile;
 declare function pickSystemRole(profile: Profile, requested?: string): string;
-export { assertToolAllowed, pickSystemRole, projectProfile, resolveTurn };
+export { pickModel, pickSystemRole, projectProfile, projectProfileObject, resolveTurn };