theorum 0.1.4 → 0.1.6

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

@@ -0,0 +1,156 @@
+import { TheorumError } from '../../guardrails/error.js';
+import { injectionSpans } from '../../guardrails/injection.js';
+import { sensitiveSpans } from '../../guardrails/sensitive.js';
+import { applySpans } from '../../observability/spans.js';
+import { getProfile } from './profiles.js';
+const B64_PAD = 2;
+const B64_WORD = 4;
+const B64_TRIPLET = 3;
+const CSV_FORMULA = /(^|,)(\s*)("?)(?:([=@])|([+-])(?![0-9."]))/gm;
+const B64_BODY = /^[A-Za-z0-9+/]*={0,2}$/;
+const TEXT_MIMES = new Set(['text/csv', 'text/plain', 'text/markdown']);
+const BYTES_PER_KIB = 1024;
+function formatMb(bytes) {
+    const mb = bytes / (BYTES_PER_KIB * BYTES_PER_KIB);
+    return Number.isInteger(mb) ? `${String(mb)} MB` : `${mb.toFixed(1)} MB`;
+}
+function tooManyFilesMessage(maxFiles) {
+    return maxFiles === 1
+        ? 'Only 1 file per message.'
+        : `Only ${String(maxFiles)} files per message.`;
+}
+function fileTooLargeMessage(maxBytes) {
+    return `Each file must be ${formatMb(maxBytes)} or smaller.`;
+}
+function turnTooLargeMessage(maxTurnBytes) {
+    return `Those files together are too large for one message (${formatMb(maxTurnBytes)} max).`;
+}
+function mediaLimits(inputs) {
+    const { maxFiles, maxBytes, maxTurnBytes, limitsByMime } = inputs;
+    if (maxFiles && maxBytes && maxTurnBytes) {
+        return { maxFiles, maxBytes, maxTurnBytes, limitsByMime };
+    }
+    return undefined;
+}
+function maxBytesForMime(mimeType, limits) {
+    if (limits.limitsByMime) {
+        const cleanMime = mimeType.split(';')[0]?.trim().toLowerCase() ?? '';
+        if (limits.limitsByMime[cleanMime]) {
+            return limits.limitsByMime[cleanMime];
+        }
+        const [category] = cleanMime.split('/');
+        const wildCard = `${category}/*`;
+        if (limits.limitsByMime[wildCard]) {
+            return limits.limitsByMime[wildCard];
+        }
+    }
+    return limits.maxBytes;
+}
+function requireMediaLimits(profile) {
+    const limits = mediaLimits(profile.inputs);
+    if (!limits) {
+        throw new TheorumError(`Profile ${profile.id} must set maxFiles, maxBytes, and maxTurnBytes`);
+    }
+    return limits;
+}
+function b64DecodedLen(data) {
+    let pad = 0;
+    if (data.endsWith('==')) {
+        pad = B64_PAD;
+    }
+    else if (data.endsWith('=')) {
+        pad = 1;
+    }
+    return Math.floor((data.length * B64_TRIPLET) / B64_WORD) - pad;
+}
+function decodeB64(data) {
+    const binary = atob(data);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i += 1) {
+        bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes;
+}
+function encodeB64(bytes) {
+    let binary = '';
+    for (const byte of bytes) {
+        binary += String.fromCharCode(byte);
+    }
+    return btoa(binary);
+}
+function decodeText(bytes) {
+    try {
+        return new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+    }
+    catch {
+        return new TextDecoder('latin1').decode(bytes);
+    }
+}
+function sanitizeCsvText(text) {
+    return text.replace(CSV_FORMULA, (_full, ...groups) => {
+        const [a, b, c, d, e] = groups;
+        return `${a}${b}${c}'${d ?? ''}${e ?? ''}`;
+    });
+}
+function sanitizeTextBytes(mime, bytes) {
+    let text = decodeText(bytes);
+    if (mime === 'text/csv') {
+        text = sanitizeCsvText(text);
+    }
+    return new TextEncoder().encode(applySpans(text, [...injectionSpans(text), ...sensitiveSpans(text)]));
+}
+function assertAttachmentLimits(blobs, limits) {
+    if (blobs.length > limits.maxFiles) {
+        throw new TheorumError(tooManyFilesMessage(limits.maxFiles));
+    }
+    let total = 0;
+    for (const blob of blobs) {
+        const { data, mimeType } = blob;
+        if (!B64_BODY.test(data)) {
+            throw new TheorumError('attachment data must be base64');
+        }
+        const size = b64DecodedLen(data);
+        const maxAllowed = maxBytesForMime(mimeType, limits);
+        if (size > maxAllowed) {
+            throw new TheorumError(fileTooLargeMessage(maxAllowed));
+        }
+        total += size;
+    }
+    if (total > limits.maxTurnBytes) {
+        throw new TheorumError(turnTooLargeMessage(limits.maxTurnBytes));
+    }
+}
+function sanitizeAttachment(blob) {
+    const { mimeType, data } = blob;
+    if (!TEXT_MIMES.has(mimeType.split(';')[0]?.trim().toLowerCase() ?? '')) {
+        return blob;
+    }
+    const bytes = sanitizeTextBytes(mimeType, decodeB64(data));
+    return { mimeType, data: encodeB64(bytes) };
+}
+function hasTurnBlobs(attachments, voice) {
+    return (attachments?.length ?? 0) > 0 || (voice?.length ?? 0) > 0;
+}
+function sanitizeTurnBlobs(attachments, voice, limits) {
+    if (!hasTurnBlobs(attachments, voice)) {
+        return { attachments, voice };
+    }
+    const files = attachments ?? [];
+    const clips = voice ?? [];
+    if (!limits) {
+        throw new TheorumError('This profile does not accept files.');
+    }
+    assertAttachmentLimits([...files, ...clips], limits);
+    return {
+        attachments: files.length > 0 ? files.map(sanitizeAttachment) : attachments,
+        voice: clips.length > 0 ? clips.map(sanitizeAttachment) : voice,
+    };
+}
+function sanitizeTurnBlobsForProfile(profileId, attachments, voice) {
+    if (!hasTurnBlobs(attachments, voice)) {
+        return { attachments, voice };
+    }
+    const limits = requireMediaLimits(getProfile(profileId));
+    return sanitizeTurnBlobs(attachments, voice, limits);
+}
+export { assertAttachmentLimits, fileTooLargeMessage, requireMediaLimits, sanitizeCsvText, sanitizeTurnBlobs, sanitizeTurnBlobsForProfile, tooManyFilesMessage, turnTooLargeMessage, };

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

@@ -0,0 +1,31 @@
+/**
+ * Tool catalog and MIME helpers.
+ *
+ * Model wire metadata is host-owned on `profile.model.config`. This module only
+ * keeps builtin/custom tool descriptors and shared MIME utilities.
+ *
+ * @module
+ */
+import type { BuiltinToolId, Catalog, GeminiInputKind, ModelId, ModelSpec, Profile, ThinkingLevel, ToolCatalogEntry, ToolId } from '../types.js';
+/** Live tool catalog. Starts with harness tools; presets/hosts register more. */
+declare const CATALOG: Catalog;
+/** Register or replace tool descriptors (idempotent per id). */
+declare function registerTools(entries: Record<string, ToolCatalogEntry>): void;
+/** Look up one registered tool descriptor. */
+declare function getTool(id: ToolId): ToolCatalogEntry | undefined;
+/** Ids of all registered provider builtins. */
+declare function listBuiltinIds(): BuiltinToolId[];
+/** Restore harness-only tools (tests / host reloads). */
+declare function resetTools(): void;
+declare function mimeEssence(mime: string): string;
+declare function mimeAllowed(accept: string[], mime: string): boolean;
+declare function geminiKindForMime(mime: string): GeminiInputKind | undefined;
+/** Require a host-declared model spec for an allowed profile model id. */
+declare function requireModelSpec(profile: Profile, modelId: ModelId): ModelSpec;
+/** Clamp a requested thinking level to what the model spec accepts. */
+declare function clampThinkingLevel(spec: ModelSpec, level: ThinkingLevel): ThinkingLevel;
+/** Look up a model spec by provider-native API id within a host specs map. */
+declare function modelEntryByApiId(specs: Record<string, ModelSpec>, apiId: string): ModelSpec | undefined;
+/** Clamp thinking level using a provider-native API id within a host specs map. */
+declare function clampThinkingLevelForApiId(specs: Record<string, ModelSpec>, apiId: string, level: ThinkingLevel): ThinkingLevel;
+export { CATALOG, clampThinkingLevel, clampThinkingLevelForApiId, geminiKindForMime, getTool, listBuiltinIds, mimeAllowed, mimeEssence, modelEntryByApiId, registerTools, requireModelSpec, resetTools, };

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

@@ -0,0 +1,135 @@
+/**
+ * Tool catalog and MIME helpers.
+ *
+ * Model wire metadata is host-owned on `profile.model.config`. This module only
+ * keeps builtin/custom tool descriptors and shared MIME utilities.
+ *
+ * @module
+ */
+import { TheorumError } from '../../guardrails/error.js';
+const ASK_USER_SCHEMA = {
+    type: 'object',
+    properties: {
+        kind: { type: 'string', enum: ['confirm', 'choice', 'text'] },
+        prompt: { type: 'string' },
+        options: { type: 'array', items: { type: 'string' } },
+    },
+    required: ['kind', 'prompt'],
+};
+/** Harness tools that always ship with THEORUM. */
+const HARNESS_TOOLS = {
+    askUser: { kind: 'custom', ui: true, schema: ASK_USER_SCHEMA },
+};
+/** Live tool catalog. Starts with harness tools; presets/hosts register more. */
+const CATALOG = {
+    tools: { ...HARNESS_TOOLS },
+};
+/** Register or replace tool descriptors (idempotent per id). */
+function registerTools(entries) {
+    Object.assign(CATALOG.tools, entries);
+}
+/** Look up one registered tool descriptor. */
+function getTool(id) {
+    return CATALOG.tools[id];
+}
+/** Ids of all registered provider builtins. */
+function listBuiltinIds() {
+    return Object.entries(CATALOG.tools)
+        .filter(([, entry]) => entry.kind === 'builtin')
+        .map(([id]) => id);
+}
+/** Restore harness-only tools (tests / host reloads). */
+function resetTools() {
+    for (const id of Object.keys(CATALOG.tools)) {
+        delete CATALOG.tools[id];
+    }
+    Object.assign(CATALOG.tools, HARNESS_TOOLS);
+}
+/** Gemini Interactions inline MIME → part type (adapter wire map). */
+const GEMINI_INPUT_KINDS = {
+    'image/png': 'image',
+    'image/jpeg': 'image',
+    'image/jpg': 'image',
+    'image/webp': 'image',
+    'image/heic': 'image',
+    'image/heif': 'image',
+    'audio/wav': 'audio',
+    'audio/x-wav': 'audio',
+    'audio/mpeg': 'audio',
+    'audio/mp3': 'audio',
+    'audio/aiff': 'audio',
+    'audio/aac': 'audio',
+    'audio/ogg': 'audio',
+    'audio/flac': 'audio',
+    'audio/webm': 'audio',
+    'audio/mp4': 'audio',
+    'audio/pcm': 'audio',
+    'video/mp4': 'video',
+    'video/mpeg': 'video',
+    'video/quicktime': 'video',
+    'video/x-msvideo': 'video',
+    'video/x-flv': 'video',
+    'video/mpg': 'video',
+    'video/webm': 'video',
+    'video/wmv': 'video',
+    'video/x-ms-wmv': 'video',
+    'video/3gpp': 'video',
+    'application/pdf': 'document',
+    'text/plain': 'document',
+    'text/csv': 'document',
+    'text/markdown': 'document',
+    'text/html': 'document',
+    'application/json': 'document',
+};
+function mimeEssence(mime) {
+    const [base] = mime.split(';');
+    return (base ?? '').trim().toLowerCase();
+}
+function mimeAllowed(accept, mime) {
+    const actual = mimeEssence(mime);
+    return accept.some((rule) => {
+        const allowed = mimeEssence(rule);
+        if (allowed.endsWith('/*')) {
+            return actual.startsWith(allowed.slice(0, -1));
+        }
+        return allowed === actual;
+    });
+}
+function geminiKindForMime(mime) {
+    return GEMINI_INPUT_KINDS[mimeEssence(mime)];
+}
+/** Require a host-declared model spec for an allowed profile model id. */
+function requireModelSpec(profile, modelId) {
+    const spec = profile.model.config[modelId];
+    if (!spec) {
+        throw new TheorumError(`Profile ${profile.id} has no model spec for '${modelId}'`);
+    }
+    return spec;
+}
+function clampLevels(entry, level) {
+    if (!entry?.thinkingLevels || entry.thinkingLevels.length === 0) {
+        return level;
+    }
+    if (entry.thinkingLevels.includes(level)) {
+        return level;
+    }
+    const fallback = entry.thinking.off;
+    if (entry.thinkingLevels.includes(fallback)) {
+        return fallback;
+    }
+    const first = entry.thinkingLevels[0];
+    return first ?? level;
+}
+/** Clamp a requested thinking level to what the model spec accepts. */
+function clampThinkingLevel(spec, level) {
+    return clampLevels(spec, level);
+}
+/** Look up a model spec by provider-native API id within a host specs map. */
+function modelEntryByApiId(specs, apiId) {
+    return Object.values(specs).find((m) => m.apiId === apiId);
+}
+/** Clamp thinking level using a provider-native API id within a host specs map. */
+function clampThinkingLevelForApiId(specs, apiId, level) {
+    return clampLevels(modelEntryByApiId(specs, apiId), level);
+}
+export { CATALOG, clampThinkingLevel, clampThinkingLevelForApiId, geminiKindForMime, getTool, listBuiltinIds, mimeAllowed, mimeEssence, modelEntryByApiId, registerTools, requireModelSpec, resetTools, };

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

@@ -0,0 +1,13 @@
+/**
+ * Kernel ingress: input parts, image pins, and speech-role checks.
+ *
+ * Owned by the kernel so `resolveTurn` does not import provider adapters.
+ *
+ * @module
+ */
+import type { BuiltinToolId, ImageResponseFormat, InteractionPart, ModelId, Profile, TurnRequest } from '../types.js';
+declare function assertSpeechRole(profile: Profile): void;
+declare function resolveImageFormat(profile: Profile, _model: ModelId, slots?: Record<string, string>): ImageResponseFormat | null;
+declare function resolveInputParts(profile: Profile, model: ModelId, req: TurnRequest): InteractionPart[];
+declare function assertImageGrounding(profile: Profile, model: ModelId, builtins: BuiltinToolId[]): void;
+export { assertImageGrounding, assertSpeechRole, resolveImageFormat, resolveInputParts };

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

@@ -0,0 +1,163 @@
+/**
+ * Kernel ingress: input parts, image pins, and speech-role checks.
+ *
+ * Owned by the kernel so `resolveTurn` does not import provider adapters.
+ *
+ * @module
+ */
+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 { geminiKindForMime, 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;
+    }
+    return undefined;
+}
+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;
+    }
+    if (pin === undefined) {
+        return undefined;
+    }
+    const fromPin = listedValue(allow, pin);
+    if (!fromPin) {
+        throw new TheorumError(`Unknown image ${label} for ${profileId}`);
+    }
+    return fromPin;
+}
+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`);
+    }
+    assertExclusiveNativeOutput(profile, 'image');
+    return pins;
+}
+function assertSpeechRole(profile) {
+    if (!profile.outputs.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' ` +
+            `(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) {
+        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}`);
+    }
+    return {
+        type: 'image',
+        mimeType: pins.mimeType ?? 'image/jpeg',
+        aspectRatio,
+        size,
+    };
+}
+function assertGeminiMime(mime) {
+    const kind = geminiKindForMime(mime);
+    if (!kind) {
+        throw new TheorumError(`MIME '${mime}' is not a Gemini input type`);
+    }
+    return kind;
+}
+function mediaParts(profile, model, blobs, channel) {
+    const accept = channel === 'voice' ? profile.inputs.voice?.accept : profile.inputs.attachments?.accept;
+    if (!accept) {
+        throw new TheorumError(`Profile ${profile.id} does not accept ${channel}`);
+    }
+    const maxInputImages = profile.outputs.image?.maxInputImages;
+    const imageCount = blobs.filter((blob) => geminiKindForMime(blob.mimeType) === 'image').length;
+    if (maxInputImages !== undefined && imageCount > maxInputImages) {
+        throw new TheorumError(`At most ${maxInputImages} reference images on ${model}`);
+    }
+    return blobs.map((blob) => {
+        const kind = assertGeminiMime(blob.mimeType);
+        if (!mimeAllowed(accept, blob.mimeType)) {
+            throw new TheorumError(`MIME '${blob.mimeType}' is not accepted on ${profile.id}`);
+        }
+        const essence = mimeEssence(blob.mimeType);
+        return {
+            type: kind,
+            mimeType: essence === 'image/jpg' ? 'image/jpeg' : essence,
+            data: blob.data,
+        };
+    });
+}
+function extractTextPart(profile, req) {
+    const { text, repair, history } = req.input ?? {};
+    if (profile.inputs.text === false) {
+        if (text) {
+            throw new TheorumError(`Profile ${profile.id} does not accept text input`);
+        }
+        return null;
+    }
+    let promptText = text;
+    if (repair) {
+        promptText = synthesizeRepairPrompt({ profile, repair, history });
+    }
+    if (!promptText) {
+        return null;
+    }
+    return { type: 'text', text: wrapUserData(promptText) };
+}
+function extractMediaParts(profile, model, req) {
+    const { attachments, voice } = req.input ?? {};
+    const files = attachments ?? [];
+    const clips = voice ?? [];
+    if (files.length + clips.length > 0) {
+        assertAttachmentLimits([...files, ...clips], requireMediaLimits(profile));
+    }
+    const parts = [];
+    if (files.length > 0) {
+        parts.push(...mediaParts(profile, model, files, 'attachments'));
+    }
+    if (clips.length > 0) {
+        parts.push(...mediaParts(profile, model, clips, 'voice'));
+    }
+    return parts;
+}
+function resolveInputParts(profile, model, req) {
+    const parts = [];
+    const textPart = extractTextPart(profile, req);
+    if (textPart) {
+        parts.push(textPart);
+    }
+    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 };

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

@@ -0,0 +1,34 @@
+/**
+ * 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.
+ *
+ * @module
+ */
+import type { Profile } from '../types.js';
+/** Host-authored profile definition, with defaults applied to omitted sections. */
+export type ProfileDefinition = {
+    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']>;
+};
+/** Define a typed profile with stable defaults for optional properties. */
+declare function defineProfile(input: ProfileDefinition): Profile;
+/** Register one host-owned profile in the process-local registry. */
+declare function registerProfile(profileInput: Profile | ProfileDefinition): void;
+/** Register several host-owned profiles in order. */
+declare function registerProfiles(profilesList: Array<Profile | ProfileDefinition>): void;
+/** Return whether a profile id is currently registered. */
+declare function hasProfile(id: string): boolean;
+/** List all currently registered profiles. */
+declare function listProfiles(): Profile[];
+/** Clear the process-local registry; intended for tests and host reloads. */
+declare function clearProfiles(): void;
+/** Fetch a registered profile or throw a `TheorumError`. */
+declare function getProfile(id: string): Profile;
+export { clearProfiles, defineProfile, getProfile, hasProfile, listProfiles, registerProfile, registerProfiles, };

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

@@ -0,0 +1,120 @@
+/**
+ * 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.
+ *
+ * @module
+ */
+import { TheorumError } from '../../guardrails/error.js';
+const profiles = new Map();
+function assertModelSpecs(profileId, allow, config) {
+    for (const id of allow) {
+        if (!config[id]) {
+            throw new TheorumError(`Profile ${profileId} allowlists '${id}' without a model spec`);
+        }
+    }
+}
+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 buildDefaultGuardrails(guardrails) {
+    return {
+        quota: guardrails?.quota,
+        canary: guardrails?.canary ?? true,
+        sanitizeInput: guardrails?.sanitizeInput ?? true,
+        redactSensitive: guardrails?.redactSensitive ?? true,
+        egress: guardrails?.egress,
+    };
+}
+/** Define a typed profile with stable defaults for optional properties. */
+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),
+    };
+}
+/** 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;
+    if (attachments || voice) {
+        if (!(maxFiles && maxBytes && maxTurnBytes)) {
+            throw new TheorumError(`Profile ${profile.id} must set maxFiles, maxBytes, and maxTurnBytes`);
+        }
+    }
+    profiles.set(profile.id, profile);
+}
+/** Register several host-owned profiles in order. */
+function registerProfiles(profilesList) {
+    for (const p of profilesList) {
+        registerProfile(p);
+    }
+}
+/** Return whether a profile id is currently registered. */
+function hasProfile(id) {
+    return profiles.has(id);
+}
+/** List all currently registered profiles. */
+function listProfiles() {
+    return Array.from(profiles.values());
+}
+/** Clear the process-local registry; intended for tests and host reloads. */
+function clearProfiles() {
+    profiles.clear();
+}
+/** Fetch a registered profile or throw a `TheorumError`. */
+function getProfile(id) {
+    const profile = profiles.get(id);
+    if (!profile) {
+        throw new TheorumError(`Unknown profile '${id}'`);
+    }
+    return profile;
+}
+export { clearProfiles, defineProfile, getProfile, hasProfile, listProfiles, registerProfile, registerProfiles, };

package/esm/src/kernel/registry/provider-request.d.ts

@@ -0,0 +1,4 @@
+import type { ProviderCompleteRequest, ResolvedGeneration } from '../types.js';
+/** Build the provider request projection shared by execution and tracing. */
+declare function providerCompleteRequest(generation: ResolvedGeneration, system: string): ProviderCompleteRequest;
+export { providerCompleteRequest };

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

@@ -0,0 +1,25 @@
+/** Build the provider request projection shared by execution and tracing. */
+function providerCompleteRequest(generation, system) {
+    return {
+        model: generation.model,
+        apiId: generation.apiId,
+        openRouterId: generation.openRouterId,
+        previousInteractionId: generation.previousInteractionId,
+        store: generation.store,
+        thinking: generation.thinking,
+        summaries: generation.summaries,
+        maxOutputTokens: generation.maxOutputTokens,
+        temperature: generation.temperature,
+        builtins: generation.builtins,
+        system,
+        input: generation.input,
+        history: generation.history,
+        dynamicTools: generation.dynamicTools,
+        dynamicToolLoader: generation.dynamicToolLoader,
+        structured: generation.structured,
+        image: generation.image,
+        speech: generation.speech,
+        geminiBucket: generation.geminiBucket,
+    };
+}
+export { providerCompleteRequest };