@theoremjs/agents 0.3.0 → 0.3.2

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

@@ -1,8 +1,5 @@
 import { TheoremError } from '../../guardrails/error.js';
-import { injectionSpans } from '../../guardrails/injection.js';
-import { lexiconText, } from '../../guardrails/lexicon.js';
-import { sensitiveSpans } from '../../guardrails/sensitive.js';
-import { applySpans } from '../../observability/spans.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';
@@ -12,6 +9,7 @@ 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) {
@@ -37,14 +35,15 @@ function maxBytesForMime(mimeType, limits) {
 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`); // lexicon-exempt: developer contract error
+        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') {
+    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 ?? {});
@@ -78,12 +77,12 @@ function sanitizeCsvText(text) {
         return `${a}${b}${c}'${d ?? ''}${e ?? ''}`;
     });
 }
-function sanitizeTextBytes(mime, bytes) {
+function sanitizeTextBytes(mime, bytes, reader) {
     let text = decodeText(bytes);
     if (mime === 'text/csv') {
         text = sanitizeCsvText(text);
     }
-    return new TextEncoder().encode(applySpans(text, [...injectionSpans(text), ...sensitiveSpans(text)]));
+    return new TextEncoder().encode(reader.read(text));
 }
 function named(issue, name) {
     return name ? { ...issue, fileName: name } : issue;
@@ -137,12 +136,14 @@ function attachmentIssues(rules, files, clips) {
 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 ?? {})) {
@@ -153,24 +154,30 @@ function attachmentIssueCopy(issue) {
         params.fileName = issue.fileName;
     return { key: ISSUE_KEYS[issue.code], params };
 }
-function attachmentIssueText(issue, lexicon) {
+/** The user-facing text for an attachment issue. */
+function attachmentIssueText(issue, labels) {
     const copy = attachmentIssueCopy(issue);
-    return lexiconText(copy.key, copy.params, lexicon);
+    return labelText(copy.key, copy.params, labels);
 }
+/** The error for a turn whose attachments were refused. */
 function attachmentsRefused(issues) {
     return new TheoremError('input', 
-    // lexicon-exempt: internal diagnostic; the user reads the copy lines
+    // 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;
-    if (!B64_BODY.test(item.data)) {
-        // lexicon-exempt: developer-facing wire-format diagnostic, not product copy
-        throw new TheoremError('request', 'attachment data must be base64');
-    }
-    facts.sizeBytes = b64DecodedLen(item.data);
+    facts.sizeBytes = base64Bytes(item.data);
     return facts;
 }
 /** Provider references are checked for MIME and count; byte limits apply to inline blobs only. */
@@ -186,7 +193,7 @@ function assertTurnAttachments(profile, attachments, voice) {
     if (issues.length > 0)
         throw attachmentsRefused(issues);
 }
-function sanitizeAttachment(blob) {
+function sanitizeAttachment(blob, reader) {
     if (isTurnMediaRef(blob)) {
         return blob;
     }
@@ -194,18 +201,20 @@ function sanitizeAttachment(blob) {
     if (!TEXT_MIMES.has(mimeEssence(mimeType))) {
         return blob;
     }
-    const bytes = sanitizeTextBytes(mimeType, base64ToBytes(data));
+    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) {
+function sanitizeTurnBlobs(profile, attachments, voice, at) {
     assertTurnAttachments(profile, attachments, voice);
     return {
-        attachments: attachments?.length ? attachments.map(sanitizeAttachment) : attachments,
-        voice: voice?.length ? voice.map(sanitizeAttachment) : voice,
+        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, isTurnMediaRef, maxBytesForMime, requireMediaLimits, resolveMediaLimits, sanitizeCsvText, sanitizeTurnBlobs, };
+export { assertTurnAttachments, attachmentIssueCopy, attachmentIssues, attachmentIssueText, attachmentsRefused, base64Bytes, isTurnMediaRef, maxBytesForMime, requireMediaLimits, resolveMediaLimits, sanitizeCsvText, sanitizeTurnBlobs, };

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

@@ -1,8 +1,10 @@
 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;
@@ -11,9 +13,13 @@ declare function profileAccept(profile: Profile, channel: MediaInputChannel): st
  * 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

@@ -12,11 +12,14 @@ function mimeAllowed(accept, mime) {
         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.inputs : undefined;
+    return profile.type === 'text' || profile.type === 'image' || profile.type === 'live'
+        ? profile.inputs
+        : undefined;
 }
 function profileAccept(profile, channel) {
     const inputs = profileInputs(profile);
@@ -38,10 +41,11 @@ function mediaChannelForMime(profile, mime) {
     }
     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}'`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        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;
 }
@@ -66,12 +70,15 @@ function clampLevels(binding, level) {
     }
     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);
 }

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

@@ -1,8 +1,12 @@
-import type { ImageResponseFormat, InteractionPart, Profile, TurnRequest } from '../types.js';
+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;
-export { assertOutputMode, assertSpeechRole, assertTurnSlots, resolveImageFormat, resolveInputParts, };
+/** 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

@@ -1,7 +1,9 @@
-import { wrapUserData } from '../../guardrails/canary.js';
+import { wrapContext, wrapUserData } from '../../guardrails/canary.js';
 import { TheoremError } from '../../guardrails/error.js';
-import { lexiconText } from '../../guardrails/lexicon.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';
@@ -24,17 +26,29 @@ function assertOutputMode(profile, structuredId) {
     if (active.length <= 1) {
         return;
     }
-    throw new TheoremError('config', `Profile ${profile.id} declares multiple output wire formats (${active.join(', ')}). ` + // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    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;
@@ -56,7 +70,7 @@ function resolveImageFormat(profile) {
 function assertMediaMime(mime) {
     const kind = mediaKindForMime(mime);
     if (!kind) {
-        throw new TheoremError('input', `MIME '${mime}' is not a supported media input type`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        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;
 }
@@ -75,16 +89,29 @@ function mediaParts(blobs) {
 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`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        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`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        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)
     }
-    // A repair is the kernel's, not the user's, so it applies even when the profile takes no user text.
+    // 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);
-    return promptText ? { type: 'text', text: wrapUserData(promptText) } : null;
+    // 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) {
@@ -94,7 +121,7 @@ function continueText(profile, req) {
     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 lexiconText('continue.instruction', {}, profile.lexicon);
+    return labelText('continue.instruction', {}, profile.labels);
 }
 function pinnedReferenceParts(profile) {
     return profile.type === 'image' && profile.image.references
@@ -131,4 +158,22 @@ function assertTurnSlots(profile, req) {
         }
     }
 }
-export { assertOutputMode, assertSpeechRole, assertTurnSlots, resolveImageFormat, resolveInputParts, };
+/** 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

@@ -1,12 +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

@@ -1,8 +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() {
-    const tools = createToolRegistry();
-    return { tools, profiles: createProfileRegistry(tools), schemas: createSchemaRegistry() };
+    // 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.js

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

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

@@ -1,29 +1,38 @@
-import { type LexiconOverrides } from '../../guardrails/lexicon.js';
-import type { DecisionGuardrailsSpec, HostGuardrailsSpec, ProfileGuardrailsSpec } from '../../guardrails/types.js';
+import { type LabelOverrides } from '../../guardrails/labels.js';
+import { type DecisionGuardrailsSpec, type HostGuardrailsSpec, type ProfileGuardrailsSpec } from '../../guardrails/types.js';
 import type { ProfileObservabilitySpec } from '../../observability/types.js';
+import type { ProviderRegistry } from '../protocols/provider.js';
 import type { ToolRegistry } from '../tools/registry.js';
-import type { DecisionModelBinding, DecisionProfile, HostProfile, HostProfileToolsSpec, ImageInputsSpec, ImageProfile, LiveProfile, LiveProfileToolsSpec, MediaTurnBehaviourSpec, ModelBinding, ModelId, Profile, ProfileIdentity, ProfileInputsSpec, ProfileModelFields, ProfileOutputsSpec, ProfileToolsSpec, ProfileTurnBehaviourSpec, SpeechGuardrailsSpec, SpeechProfile, TextProfile } from '../types.js';
+import type { DecisionModelBinding, DecisionProfile, EmbeddingProfile, HostProfile, HostProfileToolsSpec, ImageInputsSpec, ImageProfile, LiveProfile, LiveProfileToolsSpec, MediaTurnBehaviourSpec, ModelBinding, ModelId, Profile, ProfileIdentity, ProfileInputsSpec, ProfileOutputsSpec, ProfileToolsSpec, ProfileTurnBehaviourSpec, SpeechProfile, TextProfile } from '../types.js';
+import type { SchemaRegistry } from './schemas.js';
 /** Not shared by host profiles, which invoke tools without a model turn. */
 export type ProfileDefinitionBase = {
     id: Profile['id'];
     identity: ProfileIdentity;
     models: Record<ModelId, ModelBinding>;
+    providerContinuation?: import('../checkpoint.js').ProviderContinuationPolicy;
     defaultModel?: ModelId;
     allowModelSelect?: boolean;
     maxSteps?: number;
-    key?: ProfileModelFields['key'];
-    fallbackKey?: ProfileModelFields['fallbackKey'];
     outputs?: ProfileOutputsSpec;
     guardrails?: ProfileGuardrailsSpec;
     observability?: ProfileObservabilitySpec;
-    lexicon?: LexiconOverrides;
+    labels?: LabelOverrides;
 };
+/** What a host writes to define an embedding profile. */
+export type EmbeddingProfileDefinition = Omit<ProfileDefinitionBase, 'identity' | 'outputs' | 'maxSteps'> & {
+    type: 'embedding';
+    identity: Pick<ProfileIdentity, 'handle'>;
+    inputs: EmbeddingProfile['inputs'];
+};
+/** What a host writes to define a text profile. */
 export type TextProfileDefinition = ProfileDefinitionBase & {
     type: 'text';
     tools: ProfileToolsSpec;
     inputs: ProfileInputsSpec;
     turnBehaviour?: ProfileTurnBehaviourSpec;
 };
+/** What a host writes to define an image profile. */
 export type ImageProfileDefinition = ProfileDefinitionBase & {
     type: 'image';
     image: NonNullable<ImageProfile['image']>;
@@ -31,33 +40,36 @@ export type ImageProfileDefinition = ProfileDefinitionBase & {
     inputs: ImageInputsSpec;
     turnBehaviour?: MediaTurnBehaviourSpec;
 };
-export type SpeechProfileDefinition = Omit<ProfileDefinitionBase, 'identity' | 'guardrails'> & {
+/** What a host writes to define a speech profile. */
+export type SpeechProfileDefinition = Omit<ProfileDefinitionBase, 'identity'> & {
     type: 'speech';
     identity: SpeechProfile['identity'];
-    guardrails?: SpeechGuardrailsSpec;
     speech: NonNullable<SpeechProfile['speech']>;
     turnBehaviour?: MediaTurnBehaviourSpec;
 };
+/** What a host writes to define a live profile. */
 export type LiveProfileDefinition = ProfileDefinitionBase & {
     type: 'live';
     live: NonNullable<LiveProfile['live']>;
+    inputs?: LiveProfile['inputs'];
     tools: LiveProfileToolsSpec;
     /** Inject gate only — resumption is `live.sessionResumption`. */
     turnBehaviour?: Pick<ProfileTurnBehaviourSpec, 'allowSteering'>;
 };
+/** What a host writes to define a decision profile. */
 export type DecisionProfileDefinition = {
     type: 'decision';
     id: Profile['id'];
     identity: Pick<ProfileIdentity, 'handle'>;
     /** Exactly one model. */
     models: Record<ModelId, DecisionModelBinding>;
-    key?: import('../types.js').KeySlot;
     inputs: DecisionProfile['inputs'];
     decision: DecisionProfile['decision'];
     guardrails?: DecisionGuardrailsSpec;
     observability?: ProfileObservabilitySpec;
-    lexicon?: LexiconOverrides;
+    labels?: LabelOverrides;
 };
+/** What a host writes to define a host profile, which runs tools and no model. */
 export type HostProfileDefinition = {
     type: 'host';
     id: Profile['id'];
@@ -65,17 +77,29 @@ export type HostProfileDefinition = {
     /** Only the guards that fire on the `invokeTool` path. */
     guardrails?: HostGuardrailsSpec;
     observability?: ProfileObservabilitySpec;
-    lexicon?: LexiconOverrides;
+    labels?: LabelOverrides;
 };
-export type ProfileDefinition = TextProfileDefinition | ImageProfileDefinition | SpeechProfileDefinition | LiveProfileDefinition | DecisionProfileDefinition | HostProfileDefinition;
+/** Any profile definition, discriminated by `type`. */
+export type ProfileDefinition = TextProfileDefinition | ImageProfileDefinition | SpeechProfileDefinition | LiveProfileDefinition | DecisionProfileDefinition | EmbeddingProfileDefinition | HostProfileDefinition;
+/** Validate a definition and return the profile; throws on a malformed one. */
 declare function defineProfile(input: TextProfileDefinition): TextProfile;
+/** Validate an image definition and return the profile. */
 declare function defineProfile(input: ImageProfileDefinition): ImageProfile;
+/** Validate a speech definition and return the profile. */
 declare function defineProfile(input: SpeechProfileDefinition): SpeechProfile;
+/** Validate a live definition and return the profile. */
 declare function defineProfile(input: LiveProfileDefinition): LiveProfile;
+/** Validate a decision definition and return the profile. */
 declare function defineProfile(input: DecisionProfileDefinition): DecisionProfile;
+/** Validate a host definition and return the profile. */
 declare function defineProfile(input: HostProfileDefinition): HostProfile;
+/** Validate an embedding definition and return the profile. */
+declare function defineProfile(input: EmbeddingProfileDefinition): EmbeddingProfile;
+/** Validate a definition of any type except live and host, and return the profile. */
 declare function defineProfile(input: Exclude<ProfileDefinition, LiveProfileDefinition | HostProfileDefinition>): Exclude<Profile, LiveProfile | HostProfile>;
+/** Validate any definition and return the profile. */
 declare function defineProfile(input: ProfileDefinition): Profile;
+/** A set of registered profiles, kept by id. */
 interface ProfileRegistry {
     register(profileInput: Profile | ProfileDefinition): void;
     registerMany(profilesList: Array<Profile | ProfileDefinition>): void;
@@ -86,7 +110,7 @@ interface ProfileRegistry {
     list(): Profile[];
     clear(): void;
 }
-/** Profiles are checked against `tools`, so register a scope's tools before its profiles. */
-declare function createProfileRegistry(tools: ToolRegistry): ProfileRegistry;
+/** Profiles are checked against `tools` and `schemas`, so register a scope's tools and schemas before its profiles. */
+declare function createProfileRegistry(tools: ToolRegistry, schemas: SchemaRegistry, providers?: ProviderRegistry): ProfileRegistry;
 export type { ProfileRegistry };
 export { createProfileRegistry, defineProfile };