@theoremjs/agents 0.0.0-stage → 0.3.0

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

@@ -0,0 +1,6 @@
+import type { ToolRegistry } from '../tools/registry.js';
+import type { BuiltinToolId, ProviderBuiltin, ProviderCompleteRequest, ResolvedGeneration } from '../types.js';
+declare function providerBuiltins(tools: ToolRegistry, ids: readonly BuiltinToolId[]): ProviderBuiltin[];
+/** Shared by execution and tracing. */
+declare function providerCompleteRequest(tools: ToolRegistry, generation: ResolvedGeneration, system: string): ProviderCompleteRequest;
+export { providerBuiltins, providerCompleteRequest };

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

@@ -0,0 +1,42 @@
+import { TheoremError } from '../../guardrails/error.js';
+function providerBuiltins(tools, ids) {
+    return ids.map((id) => {
+        const tool = tools.get(id);
+        if (tool?.type !== 'builtin') {
+            throw new TheoremError('config', `Builtin '${id}' is not registered`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        }
+        return { id, wire: tool.wire };
+    });
+}
+/** Shared by execution and tracing. */
+function providerCompleteRequest(tools, generation, system) {
+    const isInteractions = generation.transport === 'interactions';
+    return {
+        model: generation.model,
+        apiId: generation.apiId,
+        previousInteractionId: isInteractions ? generation.previousInteractionId : undefined,
+        store: isInteractions ? generation.store : undefined,
+        stream: generation.stream,
+        thinking: generation.thinking,
+        summaries: generation.summaries,
+        maxOutputTokens: generation.maxOutputTokens,
+        temperature: generation.temperature,
+        builtins: providerBuiltins(tools, generation.builtins),
+        googleMapsLocation: isInteractions ? generation.googleMapsLocation : undefined,
+        cache: generation.cache,
+        sessionId: generation.sessionId,
+        system,
+        input: generation.input,
+        history: generation.history,
+        continuation: isInteractions ? generation.continuation : undefined,
+        wireTools: generation.tools.wire,
+        structured: generation.structured,
+        image: generation.image,
+        speech: generation.speech,
+        live: generation.live,
+        sessionResumptionHandle: generation.sessionResumptionHandle,
+        keySlot: generation.keySlot,
+        fallbackKeySlot: generation.fallbackKeySlot,
+    };
+}
+export { providerBuiltins, providerCompleteRequest };

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

@@ -0,0 +1,14 @@
+import type { ToolRegistry } from '../tools/registry.js';
+import type { ModelId, ModelProfile, Profile, ProjectedProfile, ResolvedGeneration, TurnRequest } from '../types.js';
+import type { KernelRegistry } from './kernel-registry.js';
+declare function isModelProfile(profile: Profile): profile is ModelProfile;
+declare function requireModelProfile(profile: Profile, door: string): ModelProfile;
+/** A request is honored only when selection is allowed; registration guarantees the default. */
+declare function pickModel(profile: ModelProfile, requested?: string): ModelId;
+declare function resolveTurnInRegistry(registry: KernelRegistry, req: TurnRequest): {
+    profile: ModelProfile;
+    generation: ResolvedGeneration;
+};
+declare function projectProfileObject(tools: ToolRegistry, input: Profile): ProjectedProfile;
+declare function projectProfileInRegistry(registry: KernelRegistry, id: Profile['id']): ProjectedProfile;
+export { isModelProfile, pickModel, projectProfileInRegistry, projectProfileObject, requireModelProfile, resolveTurnInRegistry, };

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

@@ -0,0 +1,237 @@
+import { mintCanary } from '../../guardrails/canary.js';
+import { TheoremError } from '../../guardrails/error.js';
+import { resolveGuardrailPolicy } from '../../guardrails/policy.js';
+import { sanitizeTurnRequest } from '../../guardrails/sanitize.js';
+import { profileTurnResumption } from '../stop.js';
+import { projectTools } from '../tools/project.js';
+import { resolveTurnTools } from '../tools/resolve.js';
+import { profileInputs, requireModelBinding } from './catalog.js';
+import { assertOutputMode, assertSpeechRole, assertTurnSlots, resolveImageFormat, resolveInputParts, } from './ingress.js';
+import { resolveTurnSystemPrompt } from './system-prompt.js';
+import { resolveKeySlot } from './vault.js';
+function isModelProfile(profile) {
+    return profile.type !== 'host' && profile.type !== 'decision';
+}
+function requireModelProfile(profile, door) {
+    if (isModelProfile(profile))
+        return profile;
+    if (profile.type === 'host') {
+        throw new TheoremError('request', `Profile ${profile.id}: type 'host' never runs a model — ${door} is not supported; execute tools with invokeTool`);
+    }
+    throw new TheoremError('request', `Profile ${profile.id}: type 'decision' runs through runDecision — ${door} is not supported`);
+}
+/** A request is honored only when selection is allowed; registration guarantees the default. */
+function pickModel(profile, requested) {
+    if (requested) {
+        if (!profile.allowModelSelect) {
+            throw new TheoremError('request', `Profile ${profile.id} does not allow model selection`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        }
+        if (!profile.models[requested]) {
+            throw new TheoremError('request', `Unknown model '${requested}' for ${profile.id}`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        }
+        return requested;
+    }
+    return profile.defaultModel;
+}
+function resolveEffort(profile, binding, modelId, requested) {
+    const efforts = binding.efforts;
+    if (!efforts || Object.keys(efforts).length === 0) {
+        if (requested) {
+            throw new TheoremError('request', `Profile ${profile.id} model '${modelId}' has no selectable efforts`);
+        }
+        return undefined;
+    }
+    const keys = Object.keys(efforts);
+    if (requested) {
+        if (!binding.allowEffortSelect) {
+            throw new TheoremError('request', `Profile ${profile.id} model '${modelId}' does not allow effort selection`);
+        }
+        const level = efforts[requested];
+        if (!level) {
+            throw new TheoremError('request', `Unknown effort '${requested}' for ${profile.id} model '${modelId}'`);
+        }
+        return level;
+    }
+    // Registration requires a default whenever more than one effort is declared.
+    return efforts[binding.defaultEffort ?? keys[0]];
+}
+function resolveSummaries(binding) {
+    if (binding.summaries === true) {
+        return 'auto';
+    }
+    if (binding.summaries === false) {
+        return 'none';
+    }
+    return undefined;
+}
+function resolveStructured(profile, slots) {
+    if (profile.type === 'live') {
+        return null;
+    }
+    const structured = profile.outputs?.structured;
+    if (!structured) {
+        return null;
+    }
+    if (typeof structured === 'string') {
+        return structured;
+    }
+    const value = slots?.[structured.by];
+    if (value) {
+        const mapped = structured.map[value];
+        if (mapped) {
+            return mapped;
+        }
+    }
+    return structured.fallback;
+}
+function resolveStreamFlag(profile) {
+    if (profile.type === 'live') {
+        return true;
+    }
+    return profile.outputs?.streaming?.mode !== 'buffered';
+}
+function resolveStore(binding, reqStore) {
+    if (reqStore !== undefined) {
+        return reqStore;
+    }
+    return binding.store;
+}
+/**
+ * A turn chains only on a binding that says so: an interaction id sent to one
+ * that does not, or a chaining turn that switches storage off, is a request error.
+ */
+function assertTurnChaining(profile, model, chains, req, store) {
+    if (req.previousInteractionId && !chains) {
+        throw new TheoremError('request', `Profile ${profile.id} model '${model}': previousInteractionId needs a binding with persistViaInteractionId: true`);
+    }
+    if (chains && store === false) {
+        throw new TheoremError('request', `Profile ${profile.id} model '${model}': store: false cannot apply to a binding with persistViaInteractionId: true — Google chains only from a stored interaction`);
+    }
+}
+function resolveTransport(profile, binding) {
+    if (profile.type === 'live') {
+        return 'geminiLive';
+    }
+    if (binding.protocol === 'geminiInteractions' && binding.provider === 'google') {
+        return 'interactions';
+    }
+    return 'openAiCompat';
+}
+function assertTurnResumption(profile, req) {
+    if (!req.continueFrom) {
+        return;
+    }
+    if (profile.type === 'live') {
+        throw new TheoremError('request', `Profile ${profile.id}: type 'live' uses live.sessionResumption, not turnBehaviour.resumption/continueFrom`);
+    }
+    const policy = profileTurnResumption(profile);
+    const max = policy?.maxContinues;
+    if (max === undefined) {
+        return;
+    }
+    const attempt = req.continuation;
+    if (attempt === undefined) {
+        throw new TheoremError('request', `Profile ${profile.id}: continueFrom requires TurnRequest.continuation when turnBehaviour.resumption.maxContinues is set`);
+    }
+    if (attempt < 1) {
+        throw new TheoremError('request', `Profile ${profile.id}: continuation must be >= 1`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+    if (attempt > max) {
+        throw new TheoremError('request', `Profile ${profile.id}: continuation ${attempt} exceeds turnBehaviour.resumption.maxContinues (${max})`);
+    }
+}
+/**
+ * A guarded Live profile (canary or `egress.enforce`) always transcribes its
+ * own speech: the outbound gate can only check audio through its transcript.
+ */
+function resolveLiveSpec(live, guardrails) {
+    const policy = resolveGuardrailPolicy(guardrails);
+    if (!policy.canary && !policy.egress?.enforce) {
+        return live;
+    }
+    return { ...live, transcription: { ...live?.transcription, output: true } };
+}
+function resolveTurnInRegistry(registry, req) {
+    const profile = requireModelProfile(registry.profiles.get(req.profile), 'resolveTurn');
+    assertTurnSlots(profile, req);
+    const safe = sanitizeTurnRequest(req, profile);
+    const input = safe.input ?? {};
+    assertTurnResumption(profile, safe);
+    const model = pickModel(profile, safe.model);
+    const binding = requireModelBinding(profile, model);
+    const toolSnapshot = resolveTurnTools(registry.tools, profile, safe, model);
+    const builtins = toolSnapshot.builtins;
+    const structuredId = resolveStructured(profile, input.slots);
+    assertOutputMode(profile, structuredId);
+    assertSpeechRole(profile, safe);
+    const keys = resolveKeySlot(profile, binding);
+    const transport = resolveTransport(profile, binding);
+    const chains = binding.persistViaInteractionId === true;
+    const store = resolveStore(binding, safe.store);
+    assertTurnChaining(profile, model, chains, safe, store);
+    return {
+        profile,
+        generation: {
+            model,
+            apiId: binding.apiId,
+            transport,
+            chains,
+            previousInteractionId: safe.previousInteractionId,
+            store,
+            stream: resolveStreamFlag(profile),
+            thinking: resolveEffort(profile, binding, model, safe.effort),
+            summaries: resolveSummaries(binding),
+            maxOutputTokens: binding.maxOutputTokens,
+            temperature: binding.temperature,
+            builtins,
+            googleMapsLocation: safe.googleMapsLocation,
+            cache: binding.cache,
+            sessionId: safe.sessionId,
+            tools: toolSnapshot,
+            sessionPermissions: safe.sessionPermissions,
+            history: input.history,
+            maxSteps: profile.maxSteps,
+            structured: structuredId
+                ? { id: structuredId, jsonSchema: registry.schemas.get(structuredId).jsonSchema }
+                : null,
+            image: resolveImageFormat(profile),
+            speech: profile.type === 'speech' ? profile.speech : undefined,
+            live: profile.type === 'live' ? resolveLiveSpec(profile.live, profile.guardrails) : undefined,
+            input: resolveInputParts(profile, safe),
+            ...keys,
+            canary: resolveGuardrailPolicy(profile.guardrails).canary ? mintCanary() : '',
+            sessionResumptionHandle: safe.sessionResumptionHandle ?? input.sessionResumptionHandle,
+            resolvedSystem: resolveTurnSystemPrompt(profile, safe),
+            host: safe.host,
+        },
+    };
+}
+function primaryImageSpec(profile) {
+    return profile.type === 'image' ? profile.image : null;
+}
+function projectProfileObject(tools, input) {
+    const profile = requireModelProfile(input, 'projectProfile');
+    const { identity } = profile;
+    const inputs = profileInputs(profile) ?? null;
+    const outputs = profile.type === 'live' ? null : (profile.outputs ?? null);
+    return {
+        id: profile.id,
+        type: profile.type,
+        handle: identity.handle,
+        models: profile.models,
+        defaultModel: profile.defaultModel,
+        allowModelSelect: profile.allowModelSelect,
+        maxSteps: profile.maxSteps,
+        key: profile.key,
+        tools: projectTools(tools, profile),
+        inputs,
+        outputs,
+        image: primaryImageSpec(profile),
+        speech: profile.type === 'speech' ? profile.speech : null,
+        live: profile.type === 'live' ? profile.live : null,
+    };
+}
+function projectProfileInRegistry(registry, id) {
+    return projectProfileObject(registry.tools, registry.profiles.get(id));
+}
+export { isModelProfile, pickModel, projectProfileInRegistry, projectProfileObject, requireModelProfile, resolveTurnInRegistry, };

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

@@ -0,0 +1,9 @@
+import type { StructuredSpec } from '../types.js';
+interface SchemaRegistry {
+    register(id: string, spec: StructuredSpec): void;
+    /** Throws when there is none. */
+    get(id: string): StructuredSpec;
+}
+declare function createSchemaRegistry(): SchemaRegistry;
+export type { SchemaRegistry };
+export { createSchemaRegistry };

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

@@ -0,0 +1,25 @@
+import { TheoremError } from '../../guardrails/error.js';
+function createSchemaRegistry() {
+    const schemas = new Map();
+    return {
+        register(id, spec) {
+            if ('enforced' in spec) {
+                throw new TheoremError('config', `registerStructured '${id}': enforced was removed; every structured schema is sent to the model as its response format`);
+            }
+            if (!spec.jsonSchema ||
+                typeof spec.jsonSchema !== 'object' ||
+                Array.isArray(spec.jsonSchema)) {
+                throw new TheoremError('config', `registerStructured '${id}': jsonSchema must be a JSON Schema object`);
+            }
+            schemas.set(id, spec);
+        },
+        get(id) {
+            const spec = schemas.get(id);
+            if (!spec) {
+                throw new TheoremError('config', `Unknown structured schema '${id}'`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+            }
+            return spec;
+        },
+    };
+}
+export { createSchemaRegistry };

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

@@ -0,0 +1,2 @@
+import type { ModelId } from '../types.js';
+export declare function soleModelId(models: Record<ModelId, unknown>): ModelId | undefined;

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

@@ -0,0 +1,4 @@
+export function soleModelId(models) {
+    const ids = Object.keys(models);
+    return ids.length === 1 ? ids[0] : undefined;
+}

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

@@ -0,0 +1,8 @@
+import type { ModelProfile, SystemPiece, TurnRequest } from '../types.js';
+/**
+ * Synchronous: snapshotted in `resolveTurn` before any async work. Each source
+ * keeps its own marks: a `{ private }` part in `req.system` leaves the
+ * profile's prompt as private as it was written.
+ */
+declare function resolveTurnSystemPrompt(profile: ModelProfile, req: TurnRequest): SystemPiece[];
+export { resolveTurnSystemPrompt };

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

@@ -0,0 +1,33 @@
+import { detectionForTrust, resolveGuardrailPolicy } from '../../guardrails/policy.js';
+import { sanitizeText } from '../../guardrails/sanitize.js';
+import { joinSystemPieces, mapSystemPrompt, systemPieces } from '../system-parts.js';
+import { pickSystemRole } from './system-role.js';
+/**
+ * Routed through the policy at `trust: 'trusted'` so the exemption is declared where it applies,
+ * not implied by skipping the sanitizer. `req.system` is `assembled` per turn and not exempt.
+ */
+function systemFromProfile(profile, role) {
+    if (profile.type === 'speech') {
+        return [];
+    }
+    const { systemByRole, system } = profile.identity;
+    const prompt = systemByRole?.[role] || system || '';
+    if (!prompt) {
+        return [];
+    }
+    const detection = detectionForTrust(resolveGuardrailPolicy(profile.guardrails), 'trusted');
+    return systemPieces(mapSystemPrompt(prompt, `Profile ${profile.id} identity.system`, (text) => sanitizeText(text, detection)));
+}
+/**
+ * Synchronous: snapshotted in `resolveTurn` before any async work. Each source
+ * keeps its own marks: a `{ private }` part in `req.system` leaves the
+ * profile's prompt as private as it was written.
+ */
+function resolveTurnSystemPrompt(profile, req) {
+    const role = pickSystemRole(profile, req.input?.role);
+    return joinSystemPieces([
+        systemFromProfile(profile, role),
+        req.system === undefined ? [] : systemPieces(req.system),
+    ]);
+}
+export { resolveTurnSystemPrompt };

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

@@ -0,0 +1,3 @@
+import type { ModelProfile } from '../types.js';
+declare function pickSystemRole(profile: ModelProfile, requested?: string): string;
+export { pickSystemRole };

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

@@ -0,0 +1,9 @@
+function pickSystemRole(profile, requested) {
+    const { handle } = profile.identity;
+    const systemByRole = profile.type === 'speech' ? undefined : profile.identity.systemByRole;
+    if (requested && systemByRole && Object.hasOwn(systemByRole, requested)) {
+        return requested;
+    }
+    return handle;
+}
+export { pickSystemRole };

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

@@ -0,0 +1,13 @@
+import type { KeySlot, ModelBinding } from '../types.js';
+/**
+ * The slots a model's calls use: its own, else the profile's. A local model uses only its own, so
+ * the profile's hosted key never reaches a local server; naming none, it sends no key.
+ */
+declare function resolveKeySlot(profile: {
+    key?: KeySlot;
+    fallbackKey?: KeySlot;
+}, binding: ModelBinding): {
+    keySlot?: KeySlot;
+    fallbackKeySlot?: KeySlot;
+};
+export { resolveKeySlot };

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

@@ -0,0 +1,14 @@
+/**
+ * The slots a model's calls use: its own, else the profile's. A local model uses only its own, so
+ * the profile's hosted key never reaches a local server; naming none, it sends no key.
+ */
+function resolveKeySlot(profile, binding) {
+    const inherited = binding.provider === 'local' ? {} : profile;
+    const keySlot = binding.key ?? inherited.key;
+    const fallbackKeySlot = binding.fallbackKey ?? inherited.fallbackKey;
+    return {
+        ...(keySlot ? { keySlot } : {}),
+        ...(fallbackKeySlot ? { fallbackKeySlot } : {}),
+    };
+}
+export { resolveKeySlot };

package/esm/src/kernel/schema.d.ts

@@ -0,0 +1,172 @@
+/**
+ * Closed unions and the profile field catalog. No Deno APIs, so host UIs and docs can import it.
+ *
+ * @module
+ */
+/** lexicon-exempt-file: authoring field-meta / closed unions — not runtime user or model copy (P2) */
+import "../../_dnt.polyfills.js";
+import { EGRESS_ON_BLOCK, type EgressOnBlock } from '../guardrails/types.js';
+export { EGRESS_ON_BLOCK, type EgressOnBlock };
+export declare const PROFILE_TYPES: readonly ["text", "image", "speech", "live", "decision", "host"];
+export type ProfileType = (typeof PROFILE_TYPES)[number];
+export declare const THINKING_LEVELS: readonly ["none", "minimal", "low", "medium", "high", "xhigh", "max"];
+export type ThinkingLevel = (typeof THINKING_LEVELS)[number];
+export declare const PROTOCOLS: readonly ["geminiInteractions", "geminiLive", "openAi", "decision"];
+export type Protocol = (typeof PROTOCOLS)[number];
+export declare const PROVIDERS: readonly ["google", "openrouter", "local", "typesafe"];
+export type Provider = (typeof PROVIDERS)[number];
+/** Turn pairs are handled by `createProvider`; decision pairs by `runDecision`. */
+export declare const PROTOCOL_PROVIDERS: {
+    readonly geminiInteractions: readonly ["google"];
+    readonly geminiLive: readonly ["google"];
+    readonly openAi: readonly ["openrouter", "local"];
+    readonly decision: readonly ["typesafe", "openrouter"];
+};
+export declare const PROFILE_TYPE_PROTOCOLS: {
+    readonly text: readonly ["geminiInteractions", "openAi"];
+    readonly image: readonly ["geminiInteractions", "openAi"];
+    readonly speech: readonly ["geminiInteractions", "openAi"];
+    readonly live: readonly ["geminiLive"];
+    readonly decision: readonly ["decision"];
+    readonly host: readonly [];
+};
+export type ProfileTypeProtocol<T extends ProfileType> = (typeof PROFILE_TYPE_PROTOCOLS)[T][number];
+export declare function protocolsForProfileType(type: ProfileType): readonly Protocol[];
+export declare function isValidProfileProtocol(type: ProfileType, protocol: Protocol): boolean;
+/** A vault slot's name, chosen by the host. The profile names slots; the host fills them with keys. */
+export type KeySlot = string;
+/** Letters, digits, `-` and `_`, up to 32 characters, starting with a letter or digit. */
+export declare const KEY_SLOT_NAME: RegExp;
+export declare function isKeySlotName(value: unknown): value is KeySlot;
+export type KeyVault = Readonly<Record<KeySlot, string | undefined>>;
+export declare const MEDIA_INPUT_KIND_VALUES: readonly ["image", "audio", "video", "document"];
+export type MediaInputKind = (typeof MEDIA_INPUT_KIND_VALUES)[number];
+export declare const SUMMARY_MODES: readonly ["auto", "none"];
+export type SummaryMode = (typeof SUMMARY_MODES)[number];
+export declare const STREAM_MODES: readonly ["sse", "buffered"];
+export type StreamMode = (typeof STREAM_MODES)[number];
+export declare const SPEECH_AUDIO_FORMATS: readonly ["pcm", "mp3"];
+export type SpeechAudioFormat = (typeof SPEECH_AUDIO_FORMATS)[number];
+export declare const LIVE_ACTIVITY_HANDLINGS: readonly ["START_OF_ACTIVITY_INTERRUPTS", "NO_INTERRUPTION"];
+export type LiveActivityHandling = (typeof LIVE_ACTIVITY_HANDLINGS)[number];
+export declare const LIVE_START_SENSITIVITIES: readonly ["START_SENSITIVITY_LOW", "START_SENSITIVITY_HIGH"];
+export type LiveStartSensitivity = (typeof LIVE_START_SENSITIVITIES)[number];
+export declare const LIVE_END_SENSITIVITIES: readonly ["END_SENSITIVITY_LOW", "END_SENSITIVITY_HIGH"];
+export type LiveEndSensitivity = (typeof LIVE_END_SENSITIVITIES)[number];
+export declare const COMPACTION_METERS: readonly ["history", "input"];
+export type CompactionMeter = (typeof COMPACTION_METERS)[number];
+export declare const COMPACTION_TIMINGS: readonly ["before", "after"];
+export type CompactionTiming = (typeof COMPACTION_TIMINGS)[number];
+/**
+ * - `compacted`: a summary replaced the compacted messages.
+ * - `deferred`: the compactor failed and the history still fits `maxTokens`, so it is kept whole.
+ * - `dropped`: the compactor failed over `maxTokens`, so the compacted messages were dropped.
+ */
+export declare const COMPACTION_OUTCOMES: readonly ["compacted", "deferred", "dropped"];
+export type CompactionOutcome = (typeof COMPACTION_OUTCOMES)[number];
+export declare const CACHE_MODES: readonly ["automatic", "system"];
+export type CacheMode = (typeof CACHE_MODES)[number];
+export declare const CACHE_TTLS: readonly ["5m", "1h"];
+export type CacheTtl = (typeof CACHE_TTLS)[number];
+export declare const TURN_STOP_KINDS: readonly ["completed", "length", "tool", "gate", "filtered", "provider_error", "cancelled", "stream_incomplete", "interrupted", "generation_complete"];
+export type TurnStopKind = (typeof TURN_STOP_KINDS)[number];
+/** Every other stop resumes by another host path, or not at all. */
+export declare const CONTINUE_STOP_KINDS: readonly ["length", "stream_incomplete", "provider_error"];
+export type ContinueStopKind = (typeof CONTINUE_STOP_KINDS)[number];
+export declare const TURN_STAGES: readonly ["pre_turn", "pre_tool", "post_tool", "before_end", "post_turn"];
+export type TurnStage = (typeof TURN_STAGES)[number];
+export declare function isTurnStage(value: unknown): value is TurnStage;
+/** Stages where an inject can land; the inject gate still applies. */
+export declare const TURN_INJECT_STAGES: readonly ["pre_turn", "post_tool", "before_end"];
+export type TurnInjectStage = (typeof TURN_INJECT_STAGES)[number];
+export declare function isTurnInjectStage(value: unknown): value is TurnInjectStage;
+/** `pre_tool` gates; not `awaiting_user_input`. */
+export declare const TOOL_GATE_KINDS: readonly ["confirmation", "permission", "auth"];
+export type ToolGateKind = (typeof TOOL_GATE_KINDS)[number];
+/** Why a refused gate settles: the user said no, walked away, or let it run out. */
+export declare const TOOL_RESUME_CAUSES: readonly ["declined", "abandoned", "expired"];
+export type ToolResumeCause = (typeof TOOL_RESUME_CAUSES)[number];
+export declare function isToolGateKind(value: unknown): value is ToolGateKind;
+export declare const AWAITING_USER_INPUT_KINDS: readonly ["confirm", "choice", "text"];
+export type AwaitingUserInputKind = (typeof AWAITING_USER_INPUT_KINDS)[number];
+export declare const STAGE_APPLY_WARNING_CODES: readonly ["affordance_not_allowed", "inject_not_allowed", "inject_rejected_max_steps", "inject_invalid_messages", "inject_id_invalid", "deny_invalid", "confirm_invalid", "mutate_invalid", "abort_invalid", "unknown_field", "result_invalid"];
+export type StageApplyWarningCode = (typeof STAGE_APPLY_WARNING_CODES)[number];
+export declare const AWAITING_USER_INPUT_STATUS: "awaiting_user_input";
+/** Enforced by the kernel at resolve time. */
+export declare const TOOL_LOAD_TIERS: readonly ["T0", "T1", "T2"];
+export type ToolLoadTier = (typeof TOOL_LOAD_TIERS)[number];
+export declare const HTTP_METHODS: readonly ["GET", "POST", "PUT", "PATCH", "DELETE"];
+export type HttpMethod = (typeof HTTP_METHODS)[number];
+/** When remote tool auth is missing or expired. */
+export declare const AUTH_UNAUTHENTICATED_POLICIES: readonly ["gate", "report_to_model"];
+export type AuthUnauthenticatedPolicy = (typeof AUTH_UNAUTHENTICATED_POLICIES)[number];
+export declare const TOOL_TYPES: readonly ["builtin", "function", "http", "mcp"];
+export declare const TOOL_ACCESS: readonly ["read-only", "read-write", "destructive"];
+export type ToolAccess = (typeof TOOL_ACCESS)[number];
+export declare const TOOL_PERMISSION: readonly ["auto", "session_consent", "always_confirm"];
+export type ToolPermission = (typeof TOOL_PERMISSION)[number];
+export declare const TOOL_AUTH_TYPES: readonly ["bearer", "api_key", "oauth2"];
+export type ToolAuthType = (typeof TOOL_AUTH_TYPES)[number];
+/** Adds UI-only `none`, which omits auth at compile time. */
+export declare const PLAYGROUND_AUTH_TYPES: readonly ["none", "bearer", "api_key", "oauth2"];
+export type PlaygroundAuthType = (typeof PLAYGROUND_AUTH_TYPES)[number];
+export type ToolType = (typeof TOOL_TYPES)[number];
+export type CustomToolType = Exclude<ToolType, 'builtin'>;
+/**
+ * The package's complete media-input vocabulary: `assertMediaMime` refuses any MIME not
+ * here, so hosts keep no second table. Rows follow Google Interactions / Live's documented
+ * lists (verified 2026-09-12), the widest provider; TypeScript, `application/xml` and
+ * `application/rtf` are not on Google's list. OpenAI-compat adapters forward the MIME
+ * verbatim and add no rows. Provider alias essences (`image/jpg`, `video/mov`, …) are rows;
+ * `resolveInputParts` canonicalizes `image/jpg` to `image/jpeg` on the wire.
+ */
+export declare const MEDIA_INPUT_KINDS: Record<string, MediaInputKind>;
+/** Type-prefix wildcards accepted by `mimeAllowed`. */
+export declare const MEDIA_WILDCARDS: readonly ["image/*", "audio/*", "video/*"];
+export declare const ATTACHMENT_ACCEPT_MIMES: readonly string[];
+/**
+ * The attachment `accept` values an image profile may list: images, video and
+ * PDF, the inputs image models document reading. Also the allowlist each of its
+ * `accept` entries must fall within.
+ */
+export declare const IMAGE_ATTACHMENT_ACCEPT_MIMES: readonly string[];
+export declare const VOICE_ACCEPT_MIMES: readonly string[];
+export declare function providersFor(protocol: Protocol): readonly Provider[];
+export declare function protocolsFor(provider: Provider): readonly Protocol[];
+/** True when `createProvider` will accept this pair. */
+export declare function isValidPair(protocol: Protocol, provider: Provider): boolean;
+/** When protocol changes, snap provider to a valid partner. */
+export declare function coerceProvider(protocol: Protocol, provider: Provider): Provider;
+/** When provider changes, snap protocol to a valid partner. */
+export declare function coerceProtocol(protocol: Protocol, provider: Provider): Protocol;
+export type FieldMeta = {
+    type: string;
+    doc: string;
+    options?: readonly string[];
+    optionDescriptions?: Record<string, string>;
+    optionNote?: string;
+    /** Types the field may be set on, when not every type; `defineProfile` rejects it elsewhere. */
+    profileTypes?: readonly ProfileType[];
+    /** Why the other types can't take it. */
+    profileTypesReason?: string;
+    /** The profile must set the field: always (`true`), or only in the case named. */
+    required?: true | string;
+    /** What leaving the field out does, as a short phrase a blank control can show. */
+    unset?: string;
+};
+/**
+ * Parents whose next key is a host-owned map key (model id, slot name, …).
+ * The annotator substitutes `*` so `models.flash.apiId` → `models.*.apiId`.
+ */
+export declare const DYNAMIC_FIELD_PARENTS: ReadonlySet<string>;
+export declare function catalogPathFor(keys: readonly string[]): string;
+/**
+ * Adding a profile field? Add it here; scope it in `PROFILE_FIELD_SCOPE` if only some types
+ * take it, and record it in `PROFILE_FIELD_PRESENCE` if it is required or its absence matters.
+ */
+export declare const PROFILE_FIELDS: Record<string, FieldMeta>;
+export declare const EXTRA_FIELDS: Record<string, FieldMeta>;
+/** `lexicon.<key>` resolves to `lexicon.*` with that key's own note. */
+export declare function fieldMeta(path: string): FieldMeta | undefined;
+export type { ProfileGraphEditor, ProfileGraphFacet, ProfileGraphFacetId, ProfileGraphRole, } from './profile-graph.js';
+export { PROFILE_GRAPH, profileGraphFacet, spineFacetsForProfileType } from './profile-graph.js';