@theoremjs/agents 0.0.0-stage → 0.3.0

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

@@ -0,0 +1,211 @@
+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 { 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']);
+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;
+}
+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
+    }
+    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') {
+        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) {
+    let text = decodeText(bytes);
+    if (mime === 'text/csv') {
+        text = sanitizeCsvText(text);
+    }
+    return new TextEncoder().encode(applySpans(text, [...injectionSpans(text), ...sensitiveSpans(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',
+    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',
+};
+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 };
+}
+function attachmentIssueText(issue, lexicon) {
+    const copy = attachmentIssueCopy(issue);
+    return lexiconText(copy.key, copy.params, lexicon);
+}
+function attachmentsRefused(issues) {
+    return new TheoremError('input', 
+    // lexicon-exempt: internal diagnostic; the user reads the copy lines
+    `attachments refused: ${issues.map((issue) => issue.code).join(', ')}`, { copy: issues.map(attachmentIssueCopy) });
+}
+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);
+    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) {
+    if (isTurnMediaRef(blob)) {
+        return blob;
+    }
+    const { mimeType, data } = blob;
+    if (!TEXT_MIMES.has(mimeEssence(mimeType))) {
+        return blob;
+    }
+    const bytes = sanitizeTextBytes(mimeType, base64ToBytes(data));
+    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) {
+    assertTurnAttachments(profile, attachments, voice);
+    return {
+        attachments: attachments?.length ? attachments.map(sanitizeAttachment) : attachments,
+        voice: voice?.length ? voice.map(sanitizeAttachment) : voice,
+    };
+}
+export { assertTurnAttachments, attachmentIssueCopy, attachmentIssues, attachmentIssueText, attachmentsRefused, isTurnMediaRef, maxBytesForMime, requireMediaLimits, resolveMediaLimits, sanitizeCsvText, sanitizeTurnBlobs, };

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

@@ -0,0 +1,19 @@
+import type { MediaInputKind, ModelBinding, ModelId, ModelProfile, Profile, ProfileInputsSpec, ThinkingLevel } from '../types.js';
+import { mimeEssence } from '../util/mime.js';
+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;
+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;
+declare function requireModelBinding(profile: ModelProfile, modelId: ModelId): ModelBinding;
+declare function clampThinkingLevel(binding: ModelBinding, level: ThinkingLevel): ThinkingLevel;
+declare function modelEntryByApiId(bindings: Record<string, ModelBinding>, apiId: string): ModelBinding | undefined;
+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,78 @@
+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;
+    });
+}
+function mediaKindForMime(mime) {
+    return MEDIA_INPUT_KINDS[mimeEssence(mime)];
+}
+function profileInputs(profile) {
+    return profile.type === 'text' || profile.type === 'image' ? 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;
+}
+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)
+    }
+    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;
+}
+function clampThinkingLevel(binding, level) {
+    return clampLevels(binding, level);
+}
+function modelEntryByApiId(bindings, apiId) {
+    return Object.values(bindings).find((m) => m.apiId === apiId);
+}
+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/ingress.d.ts

@@ -0,0 +1,8 @@
+import type { ImageResponseFormat, InteractionPart, Profile, 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;
+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, };

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

@@ -0,0 +1,134 @@
+import { wrapUserData } from '../../guardrails/canary.js';
+import { TheoremError } from '../../guardrails/error.js';
+import { lexiconText } from '../../guardrails/lexicon.js';
+import { synthesizeRepairPrompt } from '../engine/repair.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(', ')}). ` + // lexicon-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') {
+        return;
+    }
+    if (req.system) {
+        throw new TheoremError('config', `Profile ${profile.id} (speech) takes no system prompt — the input text is the transcript`);
+    }
+}
+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`); // lexicon-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`); // lexicon-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)
+    }
+    // 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;
+}
+/** 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 lexiconText('continue.instruction', {}, profile.lexicon);
+}
+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}'`);
+        }
+    }
+}
+export { assertOutputMode, assertSpeechRole, assertTurnSlots, resolveImageFormat, resolveInputParts, };

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

@@ -0,0 +1,12 @@
+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 tools: ToolRegistry;
+    readonly profiles: ProfileRegistry;
+    readonly schemas: SchemaRegistry;
+}
+declare function createKernelRegistry(): KernelRegistry;
+export type { KernelRegistry };
+export { createKernelRegistry };

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

@@ -0,0 +1,8 @@
+import { createToolRegistry } from '../tools/registry.js';
+import { createProfileRegistry } from './profiles.js';
+import { createSchemaRegistry } from './schemas.js';
+function createKernelRegistry() {
+    const tools = createToolRegistry();
+    return { tools, profiles: createProfileRegistry(tools), schemas: createSchemaRegistry() };
+}
+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,7 @@
+function profileTurnOutputs(profile) {
+    if (profile.type === 'live' || profile.type === 'host' || profile.type === 'decision') {
+        return undefined;
+    }
+    return profile.outputs;
+}
+export { profileTurnOutputs };

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

@@ -0,0 +1,92 @@
+import { type LexiconOverrides } from '../../guardrails/lexicon.js';
+import type { DecisionGuardrailsSpec, HostGuardrailsSpec, ProfileGuardrailsSpec } from '../../guardrails/types.js';
+import type { ProfileObservabilitySpec } from '../../observability/types.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';
+/** Not shared by host profiles, which invoke tools without a model turn. */
+export type ProfileDefinitionBase = {
+    id: Profile['id'];
+    identity: ProfileIdentity;
+    models: Record<ModelId, ModelBinding>;
+    defaultModel?: ModelId;
+    allowModelSelect?: boolean;
+    maxSteps?: number;
+    key?: ProfileModelFields['key'];
+    fallbackKey?: ProfileModelFields['fallbackKey'];
+    outputs?: ProfileOutputsSpec;
+    guardrails?: ProfileGuardrailsSpec;
+    observability?: ProfileObservabilitySpec;
+    lexicon?: LexiconOverrides;
+};
+export type TextProfileDefinition = ProfileDefinitionBase & {
+    type: 'text';
+    tools: ProfileToolsSpec;
+    inputs: ProfileInputsSpec;
+    turnBehaviour?: ProfileTurnBehaviourSpec;
+};
+export type ImageProfileDefinition = ProfileDefinitionBase & {
+    type: 'image';
+    image: NonNullable<ImageProfile['image']>;
+    tools: ProfileToolsSpec;
+    inputs: ImageInputsSpec;
+    turnBehaviour?: MediaTurnBehaviourSpec;
+};
+export type SpeechProfileDefinition = Omit<ProfileDefinitionBase, 'identity' | 'guardrails'> & {
+    type: 'speech';
+    identity: SpeechProfile['identity'];
+    guardrails?: SpeechGuardrailsSpec;
+    speech: NonNullable<SpeechProfile['speech']>;
+    turnBehaviour?: MediaTurnBehaviourSpec;
+};
+export type LiveProfileDefinition = ProfileDefinitionBase & {
+    type: 'live';
+    live: NonNullable<LiveProfile['live']>;
+    tools: LiveProfileToolsSpec;
+    /** Inject gate only — resumption is `live.sessionResumption`. */
+    turnBehaviour?: Pick<ProfileTurnBehaviourSpec, 'allowSteering'>;
+};
+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;
+};
+export type HostProfileDefinition = {
+    type: 'host';
+    id: Profile['id'];
+    tools: HostProfileToolsSpec;
+    /** Only the guards that fire on the `invokeTool` path. */
+    guardrails?: HostGuardrailsSpec;
+    observability?: ProfileObservabilitySpec;
+    lexicon?: LexiconOverrides;
+};
+export type ProfileDefinition = TextProfileDefinition | ImageProfileDefinition | SpeechProfileDefinition | LiveProfileDefinition | DecisionProfileDefinition | HostProfileDefinition;
+declare function defineProfile(input: TextProfileDefinition): TextProfile;
+declare function defineProfile(input: ImageProfileDefinition): ImageProfile;
+declare function defineProfile(input: SpeechProfileDefinition): SpeechProfile;
+declare function defineProfile(input: LiveProfileDefinition): LiveProfile;
+declare function defineProfile(input: DecisionProfileDefinition): DecisionProfile;
+declare function defineProfile(input: HostProfileDefinition): HostProfile;
+declare function defineProfile(input: Exclude<ProfileDefinition, LiveProfileDefinition | HostProfileDefinition>): Exclude<Profile, LiveProfile | HostProfile>;
+declare function defineProfile(input: ProfileDefinition): Profile;
+interface ProfileRegistry {
+    register(profileInput: Profile | ProfileDefinition): void;
+    registerMany(profilesList: Array<Profile | ProfileDefinition>): void;
+    /** Throws when there is none. */
+    get(id: string): Profile;
+    find(id: string): Profile | undefined;
+    has(id: string): boolean;
+    list(): Profile[];
+    clear(): void;
+}
+/** Profiles are checked against `tools`, so register a scope's tools before its profiles. */
+declare function createProfileRegistry(tools: ToolRegistry): ProfileRegistry;
+export type { ProfileRegistry };
+export { createProfileRegistry, defineProfile };