@theoremjs/agents 0.0.0-stage → 0.3.1

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

@@ -0,0 +1,220 @@
+import { TheoremError } from '../../guardrails/error.js';
+import { labelText, } from '../../guardrails/labels.js';
+import { base64ToBytes, bytesToBase64 } from '../util/base64.js';
+import { mimeEssence } from '../util/mime.js';
+import { mimeAllowed, profileAccept } from './catalog.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']);
+/** The media limits an inputs spec sets, or `undefined` unless it sets `maxFiles`, `maxBytes`, and `maxTurnBytes`. */
+function resolveMediaLimits(inputs) {
+    const { maxFiles, maxBytes, maxTurnBytes, limitsByMime } = inputs;
+    if (maxFiles && maxBytes && maxTurnBytes) {
+        return { maxFiles, maxBytes, maxTurnBytes, limitsByMime };
+    }
+    return undefined;
+}
+/** A MIME-specific cap, then its category wildcard, then the global cap. */
+function maxBytesForMime(mimeType, limits) {
+    if (limits.limitsByMime) {
+        const cleanMime = mimeEssence(mimeType);
+        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 isTurnMediaRef(item) {
+    return 'uri' in item;
+}
+/** The profile's media limits; throws when it takes no media. */
+function requireMediaLimits(profile) {
+    if (profile.type === 'speech') {
+        throw new TheoremError('request', `Profile ${profile.id} (speech) does not accept media input`); // labels-exempt: developer contract error
+    }
+    if (profile.type === 'live') {
+        throw new TheoremError('request', `Profile ${profile.id} (live) does not accept turn attachment input`);
+    }
+    if (profile.type === 'host' || profile.type === 'decision' || profile.type === 'embedding') {
+        throw new TheoremError('request', `Profile ${profile.id} (${profile.type}) does not accept turn input`);
+    }
+    const limits = resolveMediaLimits(profile.inputs ?? {});
+    if (!limits) {
+        throw new TheoremError('config', `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 decodeText(bytes) {
+    try {
+        return new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+    }
+    catch {
+        return new TextDecoder('latin1').decode(bytes);
+    }
+}
+/** CSV formula injection: formula-like cells get an apostrophe before they reach a model. */
+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, reader) {
+    let text = decodeText(bytes);
+    if (mime === 'text/csv') {
+        text = sanitizeCsvText(text);
+    }
+    return new TextEncoder().encode(reader.read(text));
+}
+function named(issue, name) {
+    return name ? { ...issue, fileName: name } : issue;
+}
+function mimeIssues(accept, files, channel) {
+    return files
+        .filter((file) => !mimeAllowed(accept, file.mimeType))
+        .map((file) => named({ code: 'mime_not_allowed', params: { mimeType: file.mimeType, channel } }, file.name));
+}
+function limitIssues(files, limits) {
+    const issues = [];
+    if (files.length > limits.maxFiles) {
+        issues.push({ code: 'too_many_files', params: { maxFiles: limits.maxFiles } });
+    }
+    let total = 0;
+    for (const file of files) {
+        if (file.sizeBytes === undefined)
+            continue;
+        const maxAllowed = maxBytesForMime(file.mimeType, limits);
+        if (file.sizeBytes > maxAllowed) {
+            issues.push(named({ code: 'file_too_large', params: { maxBytes: maxAllowed } }, file.name));
+        }
+        total += file.sizeBytes;
+    }
+    if (total > limits.maxTurnBytes) {
+        issues.push({ code: 'turn_too_large', params: { maxTurnBytes: limits.maxTurnBytes } });
+    }
+    return issues;
+}
+/** The one attachment check: the kernel throws on it at ingress and the headless interface runs it before a send. */
+function attachmentIssues(rules, files, clips) {
+    const issues = [];
+    if (files.length > 0 && !rules.attachments) {
+        issues.push({ code: 'attachments_not_accepted', params: { channel: 'attachment' } });
+    }
+    if (clips.length > 0 && !rules.voice) {
+        issues.push({ code: 'voice_not_accepted', params: { channel: 'voice' } });
+    }
+    if (issues.length > 0)
+        return issues;
+    if (files.length === 0 && clips.length === 0)
+        return issues;
+    if (rules.attachments)
+        issues.push(...mimeIssues(rules.attachments, files, 'attachment'));
+    if (rules.voice)
+        issues.push(...mimeIssues(rules.voice, clips, 'voice'));
+    if (!rules.limits)
+        return [...issues, { code: 'limits_unconfigured' }];
+    return [...issues, ...limitIssues([...files, ...clips], rules.limits)];
+}
+const ISSUE_KEYS = {
+    mime_not_allowed: 'attachments.mime_not_allowed',
+    too_many_files: 'attachments.too_many_files',
+    too_many_of_kind: 'attachments.too_many_of_kind',
+    file_too_large: 'attachments.file_too_large',
+    turn_too_large: 'attachments.turn_too_large',
+    attachments_not_accepted: 'attachments.not_accepted',
+    voice_not_accepted: 'attachments.not_accepted',
+    limits_unconfigured: 'attachments.limits_unconfigured',
+};
+/** The user-facing wording key and params for an attachment issue. */
+function attachmentIssueCopy(issue) {
+    const params = {};
+    for (const [key, value] of Object.entries(issue.params ?? {})) {
+        if (value !== undefined)
+            params[key] = value;
+    }
+    if (issue.fileName !== undefined)
+        params.fileName = issue.fileName;
+    return { key: ISSUE_KEYS[issue.code], params };
+}
+/** The user-facing text for an attachment issue. */
+function attachmentIssueText(issue, labels) {
+    const copy = attachmentIssueCopy(issue);
+    return labelText(copy.key, copy.params, labels);
+}
+/** The error for a turn whose attachments were refused. */
+function attachmentsRefused(issues) {
+    return new TheoremError('input', 
+    // labels-exempt: internal diagnostic; the user reads the copy lines
+    `attachments refused: ${issues.map((issue) => issue.code).join(', ')}`, { copy: issues.map(attachmentIssueCopy) });
+}
+/** The decoded size of inline base64 data; throws when it is not base64. */
+function base64Bytes(data) {
+    if (!B64_BODY.test(data)) {
+        // labels-exempt: developer-facing wire-format diagnostic, not product copy
+        throw new TheoremError('request', 'attachment data must be base64');
+    }
+    return b64DecodedLen(data);
+}
+function factsOf(item) {
+    const facts = { mimeType: item.mimeType, name: item.name };
+    if (isTurnMediaRef(item))
+        return facts;
+    facts.sizeBytes = base64Bytes(item.data);
+    return facts;
+}
+/** Provider references are checked for MIME and count; byte limits apply to inline blobs only. */
+function assertTurnAttachments(profile, attachments, voice) {
+    if (!hasTurnBlobs(attachments, voice))
+        return;
+    const limits = requireMediaLimits(profile);
+    const issues = attachmentIssues({
+        attachments: profileAccept(profile, 'attachments'),
+        voice: profileAccept(profile, 'voice'),
+        limits,
+    }, (attachments ?? []).map(factsOf), (voice ?? []).map(factsOf));
+    if (issues.length > 0)
+        throw attachmentsRefused(issues);
+}
+function sanitizeAttachment(blob, reader) {
+    if (isTurnMediaRef(blob)) {
+        return blob;
+    }
+    const { mimeType, data } = blob;
+    if (!TEXT_MIMES.has(mimeEssence(mimeType))) {
+        return blob;
+    }
+    const bytes = sanitizeTextBytes(mimeType, base64ToBytes(data), reader);
+    return { ...blob, data: bytesToBase64(bytes) };
+}
+function hasTurnBlobs(attachments, voice) {
+    return (attachments?.length ?? 0) > 0 || (voice?.length ?? 0) > 0;
+}
+/** Provider file references pass through unsanitized: the kernel has no bytes to scan. */
+function sanitizeTurnBlobs(profile, attachments, voice, at) {
+    assertTurnAttachments(profile, attachments, voice);
+    return {
+        attachments: attachments?.length
+            ? attachments.map((blob) => sanitizeAttachment(blob, at.attachment))
+            : attachments,
+        voice: voice?.length ? voice.map((blob) => sanitizeAttachment(blob, at.voice)) : voice,
+    };
+}
+export { assertTurnAttachments, attachmentIssueCopy, attachmentIssues, attachmentIssueText, attachmentsRefused, base64Bytes, isTurnMediaRef, maxBytesForMime, requireMediaLimits, resolveMediaLimits, sanitizeCsvText, sanitizeTurnBlobs, };

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

@@ -0,0 +1,25 @@
+import type { MediaInputKind, ModelBinding, ModelId, ModelProfile, Profile, ProfileInputsSpec, ThinkingLevel } from '../types.js';
+import { mimeEssence } from '../util/mime.js';
+/** Where a media input arrives: as an attachment or as voice. */
+type MediaInputChannel = 'attachments' | 'voice';
+/** Rules support a subtype wildcard such as `image/*`; parameter values are ignored. */
+declare function mimeAllowed(accept: readonly string[], mime: string): boolean;
+/** The kind of media a MIME type is, or `undefined` when it is not accepted. */
+declare function mediaKindForMime(mime: string): MediaInputKind | undefined;
+declare function profileInputs(profile: Profile): ProfileInputsSpec | undefined;
+declare function profileAccept(profile: Profile, channel: MediaInputChannel): string[] | undefined;
+/**
+ * `undefined` when the profile accepts it nowhere or the kernel cannot classify it. Hosts route
+ * files with this instead of their own MIME table: the profile's `accept` lists are the whole declaration.
+ */
+declare function mediaChannelForMime(profile: Profile, mime: string): MediaInputChannel | undefined;
+/** The profile's binding for the model id; throws when there is none. */
+declare function requireModelBinding(profile: ModelProfile, modelId: ModelId): ModelBinding;
+/** The level if the binding accepts it, else the binding's default effort level, else its first listed level. */
+declare function clampThinkingLevel(binding: ModelBinding, level: ThinkingLevel): ThinkingLevel;
+/** The binding whose provider model id is `apiId`, or `undefined`. */
+declare function modelEntryByApiId(bindings: Record<string, ModelBinding>, apiId: string): ModelBinding | undefined;
+/** The level if the binding for this provider model id accepts it, else that binding's default effort level, else its first listed level. */
+declare function clampThinkingLevelForApiId(bindings: Record<string, ModelBinding>, apiId: string, level: ThinkingLevel): ThinkingLevel;
+export type { MediaInputChannel };
+export { clampThinkingLevel, clampThinkingLevelForApiId, mediaChannelForMime, mediaKindForMime, mimeAllowed, mimeEssence, modelEntryByApiId, profileAccept, profileInputs, requireModelBinding, };

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

@@ -0,0 +1,85 @@
+import { TheoremError } from '../../guardrails/error.js';
+import { MEDIA_INPUT_KINDS } from '../schema.js';
+import { mimeEssence } from '../util/mime.js';
+/** Rules support a subtype wildcard such as `image/*`; parameter values are ignored. */
+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;
+    });
+}
+/** The kind of media a MIME type is, or `undefined` when it is not accepted. */
+function mediaKindForMime(mime) {
+    return MEDIA_INPUT_KINDS[mimeEssence(mime)];
+}
+function profileInputs(profile) {
+    return profile.type === 'text' || profile.type === 'image' || profile.type === 'live'
+        ? profile.inputs
+        : undefined;
+}
+function profileAccept(profile, channel) {
+    const inputs = profileInputs(profile);
+    return channel === 'voice' ? inputs?.voice?.accept : inputs?.attachments?.accept;
+}
+/**
+ * `undefined` when the profile accepts it nowhere or the kernel cannot classify it. Hosts route
+ * files with this instead of their own MIME table: the profile's `accept` lists are the whole declaration.
+ */
+function mediaChannelForMime(profile, mime) {
+    if (!mediaKindForMime(mime)) {
+        return undefined;
+    }
+    for (const channel of ['attachments', 'voice']) {
+        const accept = profileAccept(profile, channel);
+        if (accept && mimeAllowed(accept, mime)) {
+            return channel;
+        }
+    }
+    return undefined;
+}
+/** The profile's binding for the model id; throws when there is none. */
+function requireModelBinding(profile, modelId) {
+    const binding = profile.models[modelId];
+    if (!binding) {
+        throw new TheoremError('config', `Profile ${profile.id} has no model binding for '${modelId}'`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+    return binding;
+}
+function effortLevels(binding) {
+    if (!binding?.efforts) {
+        return [];
+    }
+    return Object.values(binding.efforts);
+}
+function clampLevels(binding, level) {
+    const legal = effortLevels(binding);
+    if (legal.length === 0) {
+        return level;
+    }
+    if (legal.includes(level)) {
+        return level;
+    }
+    const fallbackAlias = binding?.defaultEffort;
+    const fallback = fallbackAlias ? binding?.efforts?.[fallbackAlias] : undefined;
+    if (fallback && legal.includes(fallback)) {
+        return fallback;
+    }
+    return legal[0] ?? level;
+}
+/** The level if the binding accepts it, else the binding's default effort level, else its first listed level. */
+function clampThinkingLevel(binding, level) {
+    return clampLevels(binding, level);
+}
+/** The binding whose provider model id is `apiId`, or `undefined`. */
+function modelEntryByApiId(bindings, apiId) {
+    return Object.values(bindings).find((m) => m.apiId === apiId);
+}
+/** The level if the binding for this provider model id accepts it, else that binding's default effort level, else its first listed level. */
+function clampThinkingLevelForApiId(bindings, apiId, level) {
+    return clampLevels(modelEntryByApiId(bindings, apiId), level);
+}
+export { clampThinkingLevel, clampThinkingLevelForApiId, mediaChannelForMime, mediaKindForMime, mimeAllowed, mimeEssence, modelEntryByApiId, profileAccept, profileInputs, requireModelBinding, };

package/esm/src/kernel/registry/embedding-rules.d.ts

@@ -0,0 +1,28 @@
+import type { EmbeddingModelLimits } from '../protocols/protocol.js';
+import type { AttachmentValidationIssue, MimeInputs } from '../types.js';
+import { type AttachmentFacts } from './attachments.js';
+/**
+ * What one embedding request may carry: the profile's inputs held to its model's limits. File
+ * counts are per input, sizes per file and across the request.
+ */
+export interface EmbeddingRules {
+    text: boolean;
+    attachments?: {
+        accept: string[];
+    };
+    maxFiles?: number;
+    maxBytes?: number;
+    maxTurnBytes?: number;
+    limitsByMime?: Record<string, number>;
+    /** Inputs one request may carry. */
+    maxInputs?: number;
+    /** The model's caps on one kind of media in one input. */
+    perInput?: {
+        accept: string[];
+        max: number;
+    }[];
+}
+/** The profile's inputs held to what its model takes; without the model's limits, the profile's alone. */
+export declare function embeddingRules(inputs: MimeInputs, model?: EmbeddingModelLimits): EmbeddingRules;
+/** The one embedding media check, input by input: the kernel throws on it and the client runs it before a send. */
+export declare function embeddingMediaIssues(rules: EmbeddingRules, media: readonly (readonly AttachmentFacts[])[]): AttachmentValidationIssue[];

package/esm/src/kernel/registry/embedding-rules.js

@@ -0,0 +1,66 @@
+import { mimeEssence } from '../util/mime.js';
+import { attachmentIssues, resolveMediaLimits } from './attachments.js';
+import { mimeAllowed } from './catalog.js';
+/** The types both lists take, each as narrow as the narrower list names it. */
+function bothAccept(profile, model) {
+    return [
+        ...new Set([
+            ...model.filter((mime) => mimeAllowed(profile, mime)),
+            ...profile.filter((mime) => mimeAllowed(model, mime)),
+        ]),
+    ];
+}
+/** The profile's inputs held to what its model takes; without the model's limits, the profile's alone. */
+export function embeddingRules(inputs, model) {
+    const accept = inputs.attachments
+        ? model
+            ? bothAccept(inputs.attachments.accept, model.media.flatMap((kind) => kind.accept))
+            : [...inputs.attachments.accept]
+        : [];
+    const perInput = (model?.media ?? []).flatMap((kind) => kind.maxPerInput === undefined ? [] : [{ accept: [...kind.accept], max: kind.maxPerInput }]);
+    return {
+        text: inputs.text !== false,
+        ...(accept.length > 0 ? { attachments: { accept } } : {}),
+        ...(inputs.maxFiles === undefined ? {} : { maxFiles: inputs.maxFiles }),
+        ...(inputs.maxBytes === undefined ? {} : { maxBytes: inputs.maxBytes }),
+        ...(inputs.maxTurnBytes === undefined ? {} : { maxTurnBytes: inputs.maxTurnBytes }),
+        ...(inputs.limitsByMime === undefined ? {} : { limitsByMime: { ...inputs.limitsByMime } }),
+        ...(model?.maxInputs === undefined ? {} : { maxInputs: model.maxInputs }),
+        ...(perInput.length > 0 ? { perInput } : {}),
+    };
+}
+/** How the user reads a kind of media: PDF, or its top-level type. */
+function kindName(accept) {
+    const first = mimeEssence(accept[0] ?? '');
+    return first === 'application/pdf' ? 'PDF' : (first.split('/')[0] ?? first);
+}
+/** The one embedding media check, input by input: the kernel throws on it and the client runs it before a send. */
+export function embeddingMediaIssues(rules, media) {
+    const limits = resolveMediaLimits(rules);
+    const issues = attachmentIssues({
+        attachments: rules.attachments?.accept,
+        ...(limits ? { limits: { ...limits, maxFiles: Number.MAX_SAFE_INTEGER } } : {}),
+    }, media.flat(), []);
+    if (limits) {
+        for (const files of media) {
+            if (files.length > limits.maxFiles)
+                issues.push({ code: 'too_many_files', params: { maxFiles: limits.maxFiles } });
+            for (const kind of rules.perInput ?? []) {
+                const count = files.filter((file) => mimeAllowed(kind.accept, file.mimeType)).length;
+                if (count > kind.max)
+                    issues.push({
+                        code: 'too_many_of_kind',
+                        params: { maxFiles: kind.max, kind: kindName(kind.accept) },
+                    });
+            }
+        }
+    }
+    const seen = new Set();
+    return issues.filter((issue) => {
+        const key = JSON.stringify(issue);
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}

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

@@ -0,0 +1,12 @@
+import type { ImageResponseFormat, InteractionPart, Profile, ProfileSpeechSpec, TurnRequest } from '../types.js';
+/** Typed profiles already make mixed wire formats unrepresentable; this is a safety net. */
+declare function assertOutputMode(profile: Profile, structuredId: string | null): void;
+declare function assertSpeechRole(profile: Profile, req: TurnRequest): void;
+/** The profile's speech settings with this turn's laid over them. */
+declare function resolveSpeech(profile: Profile, req: TurnRequest): ProfileSpeechSpec | undefined;
+declare function resolveImageFormat(profile: Profile): ImageResponseFormat | null;
+declare function resolveInputParts(profile: Profile, req: TurnRequest): InteractionPart[];
+declare function assertTurnSlots(profile: Profile, req: TurnRequest): void;
+/** Refuses context from a sender the profile's `inputs.context` does not list, and a package over its `maxChars`. */
+declare function assertTurnContext(profile: Profile, req: TurnRequest): void;
+export { assertOutputMode, assertSpeechRole, assertTurnContext, assertTurnSlots, resolveImageFormat, resolveInputParts, resolveSpeech, };

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

@@ -0,0 +1,179 @@
+import { wrapContext, wrapUserData } from '../../guardrails/canary.js';
+import { TheoremError } from '../../guardrails/error.js';
+import { labelText } from '../../guardrails/labels.js';
+import { contextText } from '../../guardrails/sanitize.js';
+import { synthesizeRepairPrompt } from '../engine/repair.js';
+import { CONTEXT_SENDERS } from '../schema.js';
+import { CONTINUE_INSTRUCTION_TYPES } from '../stop.js';
+import { isTurnMediaRef } from './attachments.js';
+import { mediaKindForMime, mimeEssence, profileInputs } from './catalog.js';
+function activePrimaryOutputModes(profile, structuredId) {
+    const modes = [];
+    if (structuredId) {
+        modes.push('structured');
+    }
+    if (profile.type === 'image') {
+        modes.push('image');
+    }
+    if (profile.type === 'speech') {
+        modes.push('speech');
+    }
+    return modes;
+}
+/** Typed profiles already make mixed wire formats unrepresentable; this is a safety net. */
+function assertOutputMode(profile, structuredId) {
+    const active = activePrimaryOutputModes(profile, structuredId);
+    if (active.length <= 1) {
+        return;
+    }
+    throw new TheoremError('config', `Profile ${profile.id} declares multiple output wire formats (${active.join(', ')}). ` + // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        'Only one of a structured JSON schema (outputs.structured), image, or speech may be active.');
+}
+function assertSpeechRole(profile, req) {
+    if (profile.type !== 'speech') {
+        if (req.speech) {
+            throw new TheoremError('request', `Profile ${profile.id} (${profile.type}) takes no speech settings — only a speech profile speaks`);
+        }
+        return;
+    }
+    if (req.system) {
+        throw new TheoremError('config', `Profile ${profile.id} (speech) takes no system prompt — the input text is the transcript`);
+    }
+}
+/** The profile's speech settings with this turn's laid over them. */
+function resolveSpeech(profile, req) {
+    return profile.type === 'speech'
+        ? { ...profile.speech, ...definedFields(req.speech) }
+        : undefined;
+}
+function definedFields(speech) {
+    return Object.fromEntries(Object.entries(speech ?? {}).filter(([, value]) => value !== undefined));
+}
+function resolveImageFormat(profile) {
+    if (profile.type !== 'image') {
+        return null;
+    }
+    const pins = profile.image;
+    return {
+        type: 'image',
+        mimeType: pins.mimeType,
+        aspectRatio: pins.aspectRatio,
+        resolution: pins.resolution,
+        quality: pins.quality,
+        background: pins.background,
+        n: pins.n,
+        seed: pins.seed,
+        outputCompression: pins.outputCompression,
+        includeText: pins.includeText === true,
+    };
+}
+function assertMediaMime(mime) {
+    const kind = mediaKindForMime(mime);
+    if (!kind) {
+        throw new TheoremError('input', `MIME '${mime}' is not a supported media input type`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+    return kind;
+}
+/** Runs after `assertTurnAttachments`. A reference's uri passes untouched: the host owns the upload. */
+function mediaParts(blobs) {
+    return blobs.map((blob) => {
+        const kind = assertMediaMime(blob.mimeType);
+        const essence = mimeEssence(blob.mimeType);
+        const mimeType = essence === 'image/jpg' ? 'image/jpeg' : essence;
+        if (isTurnMediaRef(blob)) {
+            return { type: kind, mimeType, uri: blob.uri };
+        }
+        return { type: kind, mimeType, data: blob.data };
+    });
+}
+function extractTextPart(profile, req) {
+    const { text, repair, history } = req.input ?? {};
+    if (profile.type === 'speech' && !text?.trim()) {
+        throw new TheoremError('request', `Profile ${profile.id} (speech) requires text input`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+    if (profileInputs(profile)?.text === false && text) {
+        throw new TheoremError('request', `Profile ${profile.id} does not accept text input`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+    // why: A repair is the kernel's, not the user's, so it applies even when the profile takes no user text.
+    const promptText = repair
+        ? synthesizeRepairPrompt({ profile, repair, history })
+        : (continueText(profile, req) ?? text);
+    // why: A speech model reads its input aloud, fence and all; it follows no instruction, so none needs fencing.
+    if (profile.type === 'speech') {
+        return promptText ? { type: 'text', text: promptText } : null;
+    }
+    const blocks = [...contextBlocks(req), ...(promptText ? [wrapUserData(promptText)] : [])];
+    return blocks.length > 0 ? { type: 'text', text: blocks.join('\n\n') } : null;
+}
+/** Each sender's context in its own fence, the host's first: the model reads it before the user's message. */
+function contextBlocks(req) {
+    const context = req.input?.context ?? {};
+    return [...CONTEXT_SENDERS]
+        .reverse()
+        .filter((sender) => context[sender] !== undefined)
+        .map((sender) => wrapContext(sender, contextText(context[sender])));
+}
+/** Image and speech get none: their continue re-sends the host's request unchanged. */
+function continueText(profile, req) {
+    if (!req.continueFrom || !CONTINUE_INSTRUCTION_TYPES.includes(profile.type)) {
+        return undefined;
+    }
+    if (req.input?.text) {
+        throw new TheoremError('request', `Profile ${profile.id}: a continueFrom turn takes no input.text — its user message is the continue instruction`);
+    }
+    return labelText('continue.instruction', {}, profile.labels);
+}
+function pinnedReferenceParts(profile) {
+    return profile.type === 'image' && profile.image.references
+        ? mediaParts(profile.image.references)
+        : [];
+}
+/** `sanitizeTurnRequest` has already checked the blobs against the profile's limits and accept lists. */
+function extractMediaParts(profile, req) {
+    const files = req.input?.attachments ?? [];
+    const clips = req.input?.voice ?? [];
+    return [...pinnedReferenceParts(profile), ...mediaParts(files), ...mediaParts(clips)];
+}
+function resolveInputParts(profile, req) {
+    const parts = [];
+    const textPart = extractTextPart(profile, req);
+    if (textPart) {
+        parts.push(textPart);
+    }
+    parts.push(...extractMediaParts(profile, req));
+    return parts;
+}
+function assertTurnSlots(profile, req) {
+    const slots = req.input?.slots;
+    if (!slots)
+        return;
+    const declared = profileInputs(profile)?.slots ?? {};
+    for (const [key, value] of Object.entries(slots)) {
+        const choices = Object.hasOwn(declared, key) ? declared[key] : undefined;
+        if (!choices) {
+            throw new TheoremError('request', `Profile ${profile.id} has no slot '${key}'`);
+        }
+        if (!choices.includes(value)) {
+            throw new TheoremError('request', `Profile ${profile.id}: slot '${key}' takes ${choices.join(', ')}, not '${value}'`);
+        }
+    }
+}
+/** Refuses context from a sender the profile's `inputs.context` does not list, and a package over its `maxChars`. */
+function assertTurnContext(profile, req) {
+    const context = req.input?.context;
+    if (!context)
+        return;
+    const spec = profileInputs(profile)?.context;
+    for (const [sender, value] of Object.entries(context)) {
+        if (value === undefined)
+            continue;
+        const allowed = CONTEXT_SENDERS.includes(sender);
+        if (!allowed || !spec?.from.some((from) => from === sender)) {
+            throw new TheoremError('request', `Profile ${profile.id} takes no context from '${sender}'`);
+        }
+        if (contextText(value).length > spec.maxChars) {
+            throw new TheoremError('request', `Profile ${profile.id}: context from '${sender}' is over inputs.context.maxChars (${String(spec.maxChars)})`);
+        }
+    }
+}
+export { assertOutputMode, assertSpeechRole, assertTurnContext, assertTurnSlots, resolveImageFormat, resolveInputParts, resolveSpeech, };

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

@@ -0,0 +1,15 @@
+import { type ProviderRegistry } from '../protocols/provider.js';
+import { type ToolRegistry } from '../tools/registry.js';
+import { type ProfileRegistry } from './profiles.js';
+import { type SchemaRegistry } from './schemas.js';
+/** Every run takes one explicitly; nothing reads a registry it was not handed. */
+interface KernelRegistry {
+    readonly providers: ProviderRegistry;
+    readonly tools: ToolRegistry;
+    readonly profiles: ProfileRegistry;
+    readonly schemas: SchemaRegistry;
+}
+/** Creates an empty registry of tools, profiles, and schemas, wired so a tool that names a profile can find it. */
+declare function createKernelRegistry(): KernelRegistry;
+export type { KernelRegistry };
+export { createKernelRegistry };

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

@@ -0,0 +1,15 @@
+import { createProviderRegistry } from '../protocols/provider.js';
+import { createToolRegistry } from '../tools/registry.js';
+import { createProfileRegistry } from './profiles.js';
+import { createSchemaRegistry } from './schemas.js';
+/** Creates an empty registry of tools, profiles, and schemas, wired so a tool that names a profile can find it. */
+function createKernelRegistry() {
+    // why: An agent tool names a profile, and a profile allows tools: each registry reads
+    // the other. Tools look profiles up only when one registers, after both exist.
+    const tools = createToolRegistry((id) => profiles.find(id));
+    const schemas = createSchemaRegistry();
+    const providers = createProviderRegistry();
+    const profiles = createProfileRegistry(tools, schemas, providers);
+    return { tools, profiles, schemas, providers };
+}
+export { createKernelRegistry };

package/esm/src/kernel/registry/profile-outputs.d.ts

@@ -0,0 +1,3 @@
+import type { Profile, ProfileOutputsSpec } from '../types.js';
+declare function profileTurnOutputs(profile: Profile): ProfileOutputsSpec | undefined;
+export { profileTurnOutputs };

package/esm/src/kernel/registry/profile-outputs.js

@@ -0,0 +1,10 @@
+function profileTurnOutputs(profile) {
+    if (profile.type === 'live' ||
+        profile.type === 'host' ||
+        profile.type === 'decision' ||
+        profile.type === 'embedding') {
+        return undefined;
+    }
+    return profile.outputs;
+}
+export { profileTurnOutputs };