theorum 1.0.0 → 1.1.3

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

@@ -5,101 +5,78 @@
  */
 import { mintCanary } from '../../guardrails/canary.js';
 import { TheorumError } 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 { clampThinkingLevel, requireModelSpec } from './catalog.js';
+import { requireModelBinding } from './catalog.js';
 import { assertOutputMode, assertSpeechRole, resolveImageFormat, resolveInputParts, } from './ingress.js';
 import { getProfile } from './profiles.js';
+import { soleModelId } from './sole-model.js';
+import { resolveTurnSystemPrompt } from './system-prompt.js';
 import { providerUsesKeySlots, resolveKeySlot } from './vault.js';
-function firstSelectKey(selectMap) {
-    const [key] = Object.keys(selectMap);
-    return key;
-}
-function lookupSelectId(profile, select) {
-    const { select: selectMap } = profile.model;
-    if (!selectMap) {
-        return undefined;
-    }
-    let key = select;
-    if (!key) {
-        key = firstSelectKey(selectMap);
-    }
-    if (!key) {
-        return undefined;
+/** Narrow to a model-binding profile; `host` never runs a model. */
+function requireModelProfile(profile, door) {
+    if (profile.type === 'host') {
+        throw new TheorumError(`Profile ${profile.id}: type 'host' never runs a model — ${door} is not supported; execute tools with invokeTool`);
     }
-    return selectMap[key];
+    return profile;
 }
-function pickModel(profile, select) {
-    if (profile.model.select) {
-        const id = lookupSelectId(profile, select);
-        if (!(id && profile.model.allow.includes(id))) {
-            let label = '';
-            if (select) {
-                label = select;
-            }
-            throw new TheorumError(`Unknown model select '${label}' for ${profile.id}`);
+function pickModel(profile, requested) {
+    if (requested) {
+        if (!profile.allowModelSelect) {
+            throw new TheorumError(`Profile ${profile.id} does not allow model selection`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
         }
-        return id;
-    }
-    const [only] = profile.model.allow;
-    if (!only) {
-        throw new TheorumError(`Profile ${profile.id} has no models`);
-    }
-    return only;
-}
-function thinkingFromControl(spec, thinkingOn) {
-    if (!spec.thinking) {
-        throw new TheorumError('model.config thinking map is required when controls include thinking');
+        if (!profile.models[requested]) {
+            throw new TheorumError(`Unknown model '${requested}' for ${profile.id}`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        }
+        return requested;
     }
-    if (thinkingOn) {
-        return spec.thinking.on;
+    const defaultId = profile.defaultModel ?? soleModelId(profile.models);
+    if (!defaultId || !profile.models[defaultId]) {
+        throw new TheorumError(`Profile ${profile.id} has no default model`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
     }
-    return spec.thinking.off;
+    return defaultId;
 }
-function pinnedLevel(pinned, key) {
-    if (!key) {
+function resolveEffort(profile, binding, modelId, requested) {
+    const efforts = binding.efforts;
+    if (!efforts || Object.keys(efforts).length === 0) {
+        if (requested) {
+            throw new TheorumError(`Profile ${profile.id} model '${modelId}' has no selectable efforts`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        }
         return undefined;
     }
-    return pinned[key];
-}
-function thinkingFromPin(profile, select) {
-    const pinned = profile.model.thinking;
-    if (typeof pinned === 'string') {
-        return pinned;
-    }
-    if (!pinned) {
-        throw new TheorumError(`Profile ${profile.id} must pin thinking or list it in controls`);
-    }
-    const fromSelect = pinnedLevel(pinned, select);
-    if (fromSelect) {
-        return fromSelect;
+    const keys = Object.keys(efforts);
+    if (requested) {
+        if (!binding.allowEffortSelect) {
+            throw new TheorumError(`Profile ${profile.id} model '${modelId}' does not allow effort selection`);
+        }
+        const level = efforts[requested];
+        if (!level) {
+            throw new TheorumError(`Unknown effort '${requested}' for ${profile.id} model '${modelId}'`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        }
+        return level;
     }
-    const fromFirst = pinnedLevel(pinned, firstSelectKey(profile.model.select ?? {}));
-    if (fromFirst) {
-        return fromFirst;
+    const alias = binding.defaultEffort ?? (keys.length === 1 ? keys[0] : undefined);
+    if (!alias) {
+        throw new TheorumError(`Profile ${profile.id} model '${modelId}' must set defaultEffort when more than one effort is declared`);
     }
-    throw new TheorumError(`Profile ${profile.id} must pin thinking or list it in controls`);
-}
-function resolveThinking(profile, spec, thinkingOn, select) {
-    const raw = profile.model.controls?.includes('thinking')
-        ? thinkingFromControl(spec, thinkingOn)
-        : thinkingFromPin(profile, select);
-    return clampThinkingLevel(spec, raw);
+    return efforts[alias];
 }
-function resolveSummaries(profile, spec, thinkingOn) {
-    if (!spec.summaries) {
-        return undefined;
+function resolveSummaries(binding) {
+    if (binding.summaries === true) {
+        return 'auto';
     }
-    if (profile.model.controls?.includes('thinking')) {
-        if (thinkingOn) {
-            return spec.summaries.on;
-        }
-        return spec.summaries.off;
+    if (binding.summaries === false) {
+        return 'none';
     }
-    return spec.summaries.on;
+    return undefined;
 }
 function resolveStructured(profile, slots) {
+    if (profile.type === 'live') {
+        return null;
+    }
     const structured = profile.outputs?.structured;
     if (!structured) {
         return null;
@@ -121,88 +98,98 @@ function resolveStructured(profile, slots) {
  * Explicit `'buffered'` opts out; `'sse'` (or omit) yields `stream: true`.
  */
 function resolveStreamFlag(profile) {
+    if (profile.type === 'live') {
+        return true;
+    }
     return profile.outputs?.streaming?.mode !== 'buffered';
 }
-function resolveStore(spec, reqStore) {
+function resolveStore(binding, reqStore) {
     if (reqStore !== undefined) {
         return reqStore;
     }
-    return spec.store;
+    return binding.store;
+}
+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 TheorumError(`Profile ${profile.id}: type 'live' uses live.sessionResumption, not turnResumption/continueFrom`);
+        throw new TheorumError(`Profile ${profile.id}: type 'live' uses live.sessionResumption, not turnBehaviour.resumption/continueFrom`);
     }
-    const policy = profile.turnResumption;
+    const policy = profileTurnResumption(profile);
     const max = policy?.maxContinues;
     if (max === undefined) {
         return;
     }
     const attempt = req.continuation;
     if (attempt === undefined) {
-        throw new TheorumError(`Profile ${profile.id}: continueFrom requires TurnRequest.continuation when turnResumption.maxContinues is set`);
+        throw new TheorumError(`Profile ${profile.id}: continueFrom requires TurnRequest.continuation when turnBehaviour.resumption.maxContinues is set`);
     }
     if (attempt < 1) {
-        throw new TheorumError(`Profile ${profile.id}: continuation must be >= 1`);
+        throw new TheorumError(`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 TheorumError(`Profile ${profile.id}: continuation ${attempt} exceeds turnResumption.maxContinues (${max})`);
+        throw new TheorumError(`Profile ${profile.id}: continuation ${attempt} exceeds turnBehaviour.resumption.maxContinues (${max})`);
     }
 }
 /** Resolve a host `TurnRequest` into provider-ready generation state. */
 function resolveTurn(req) {
     const safe = sanitizeTurnRequest(req);
     const input = safe.input ?? {};
-    const profile = getProfile(safe.profile);
+    const profile = requireModelProfile(getProfile(safe.profile), 'resolveTurn');
     assertTurnResumption(profile, safe);
-    const model = pickModel(profile, safe.select);
-    const spec = requireModelSpec(profile, model);
-    const thinkingOn = safe.thinking === true;
+    const model = pickModel(profile, safe.model);
+    const binding = requireModelBinding(profile, model);
     const toolSnapshot = resolveTurnTools(profile, safe, model);
     const builtins = toolSnapshot.builtins;
     const structured = resolveStructured(profile, input.slots);
     assertOutputMode(profile, structured);
     assertSpeechRole(profile);
-    const pinnedKey = profile.model.key ?? spec.key;
-    const keySlot = providerUsesKeySlots(profile.model.provider)
-        ? resolveKeySlot(pinnedKey, spec, builtins, profile.model.provider === 'google')
+    const pinnedKey = profile.key ?? binding.key;
+    const keySlot = providerUsesKeySlots(binding.provider)
+        ? resolveKeySlot(pinnedKey, binding, builtins, binding.provider === 'google')
         : undefined;
-    const transport = profile.type === 'live'
-        ? 'geminiLive'
-        : profile.model.protocol === 'geminiInteractions' && profile.model.provider === 'google'
-            ? 'interactions'
-            : 'openAiCompat';
-    const previousInteractionId = spec.persistViaInteractionId === false ? undefined : safe.previousInteractionId;
+    const previousInteractionId = binding.persistViaInteractionId === false ? undefined : safe.previousInteractionId;
     return {
         profile,
         generation: {
             model,
-            apiId: spec.apiId,
-            transport,
+            apiId: binding.apiId,
+            transport: resolveTransport(profile, binding),
             previousInteractionId,
-            store: resolveStore(spec, safe.store),
+            store: resolveStore(binding, safe.store),
             stream: resolveStreamFlag(profile),
-            thinking: resolveThinking(profile, spec, thinkingOn, safe.select),
-            summaries: resolveSummaries(profile, spec, thinkingOn),
-            maxOutputTokens: spec.maxOutputTokens,
-            temperature: spec.temperature,
+            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.model.maxSteps,
+            maxSteps: profile.maxSteps,
             structured,
             image: resolveImageFormat(profile),
             speech: profile.type === 'speech' ? profile.speech : undefined,
             live: profile.type === 'live' ? profile.live : undefined,
             input: resolveInputParts(profile, model, safe),
             keySlot,
-            canary: profile.guardrails?.canary === true ? mintCanary() : '',
+            canary: resolveGuardrailPolicy(profile.guardrails).canary ? mintCanary() : '',
             sessionResumptionHandle: safe.sessionResumptionHandle ?? input.sessionResumptionHandle,
+            resolvedSystem: resolveTurnSystemPrompt(profile, safe),
+            host: safe.host,
         },
     };
 }
@@ -210,23 +197,29 @@ function primaryImageSpec(profile) {
     return profile.type === 'image' ? profile.image : null;
 }
 function profileInputsOrNull(profile) {
-    if (profile.type === 'speech') {
+    if (profile.type === 'speech' || profile.type === 'live') {
         return null;
     }
     return profile.inputs ?? null;
 }
 /** Project a profile object into a safe host/UI inspection object. */
-function projectProfileObject(profile) {
-    const { model, identity, outputs } = profile;
+function projectProfileObject(input) {
+    const profile = requireModelProfile(input, 'projectProfile');
+    const { identity } = profile;
     const inputs = profileInputsOrNull(profile);
+    const outputs = profile.type === 'live' ? null : (profile.outputs ?? null);
     return {
         id: profile.id,
         type: profile.type,
         handle: identity.handle,
-        model,
+        models: profile.models,
+        defaultModel: profile.defaultModel,
+        allowModelSelect: profile.allowModelSelect,
+        maxSteps: profile.maxSteps,
+        key: profile.key,
         tools: projectTools(profile),
         inputs,
-        outputs: outputs ?? null,
+        outputs,
         image: primaryImageSpec(profile),
         speech: profile.type === 'speech' ? profile.speech : null,
         live: profile.type === 'live' ? profile.live : null,
@@ -236,12 +229,4 @@ function projectProfileObject(profile) {
 function projectProfile(id) {
     return projectProfileObject(getProfile(id));
 }
-function pickSystemRole(profile, requested) {
-    const { identity } = profile;
-    const { handle, systemByRole } = identity;
-    if (requested && systemByRole && Object.hasOwn(systemByRole, requested)) {
-        return requested;
-    }
-    return handle;
-}
-export { pickModel, pickSystemRole, projectProfile, projectProfileObject, resolveTurn };
+export { pickModel, projectProfile, projectProfileObject, requireModelProfile, resolveTurn };

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

@@ -16,7 +16,7 @@ function registerStructured(id, spec) {
 function getStructured(id) {
     const spec = schemas.get(id);
     if (!spec) {
-        throw new TheorumError(`Unknown structured schema '${id}'`);
+        throw new TheorumError(`Unknown structured schema '${id}'`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
     }
     return spec;
 }

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

@@ -0,0 +1,8 @@
+/**
+ * Shared model-id helpers for profile registration and resolution.
+ *
+ * @module
+ */
+import type { ModelBinding, ModelId } from '../types.js';
+/** When exactly one model is declared, that id is the implicit default. */
+export declare function soleModelId(models: Record<ModelId, ModelBinding>): ModelId | undefined;

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

@@ -0,0 +1,10 @@
+/**
+ * Shared model-id helpers for profile registration and resolution.
+ *
+ * @module
+ */
+/** When exactly one model is declared, that id is the implicit default. */
+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,10 @@
+/**
+ * Synchronous system-prompt resolution for a turn or session.
+ * Snapshotted in `resolveTurn` before any async work — never mutate registry per request.
+ *
+ * @module
+ */
+import type { ModelProfile, TurnRequest } from '../types.js';
+/** Merge profile + host turn system synchronously at resolve time. */
+declare function resolveTurnSystemPrompt(profile: ModelProfile, req: TurnRequest): string;
+export { resolveTurnSystemPrompt };

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

@@ -0,0 +1,40 @@
+/**
+ * Synchronous system-prompt resolution for a turn or session.
+ * Snapshotted in `resolveTurn` before any async work — never mutate registry per request.
+ *
+ * @module
+ */
+import { lexiconText } from '../../guardrails/lexicon.js';
+import { detectionForTrust, resolveGuardrailPolicy } from '../../guardrails/policy.js';
+import { sanitizeText } from '../../guardrails/sanitize.js';
+import { profileTurnResumption } from '../stop.js';
+import { pickSystemRole } from './system-role.js';
+/**
+ * Author-time system text for a role (handle or `systemByRole`).
+ *
+ * Routed through the guardrail policy at `trust: 'trusted'` so the exemption is
+ * declared at the point it applies rather than implied by never calling the
+ * sanitizer. Trusted resolves to no detection, so the text reaches the provider
+ * verbatim — `req.system`, which the host assembles per turn, is handled as
+ * `assembled` in `sanitizeTurnRequest` and is not exempt.
+ */
+function systemFromProfile(profile, role) {
+    const { identity } = profile;
+    const { systemByRole, system } = identity;
+    const text = systemByRole?.[role] || system || '';
+    if (!text) {
+        return '';
+    }
+    const policy = resolveGuardrailPolicy(profile.guardrails);
+    return sanitizeText(text, detectionForTrust(policy, 'trusted'));
+}
+/** Merge profile + host turn system synchronously at resolve time. */
+function resolveTurnSystemPrompt(profile, req) {
+    const role = pickSystemRole(profile, req.input?.role);
+    // Profile override wins; otherwise the registered lexicon default.
+    const continueSys = req.continueFrom
+        ? lexiconText('continue.instruction', {}, profileTurnResumption(profile)?.continueInstruction)
+        : '';
+    return [systemFromProfile(profile, role), req.system, continueSys].filter(Boolean).join('\n\n');
+}
+export { resolveTurnSystemPrompt };

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

@@ -0,0 +1,8 @@
+/**
+ * Resolve which `systemByRole` key (or handle) applies for a turn.
+ *
+ * @module
+ */
+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,14 @@
+/**
+ * Resolve which `systemByRole` key (or handle) applies for a turn.
+ *
+ * @module
+ */
+function pickSystemRole(profile, requested) {
+    const { identity } = profile;
+    const { handle, systemByRole } = identity;
+    if (requested && systemByRole && Object.hasOwn(systemByRole, requested)) {
+        return requested;
+    }
+    return handle;
+}
+export { pickSystemRole };

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

@@ -3,7 +3,7 @@
  *
  * @module
  */
-import type { BuiltinToolId, KeySlot, ModelSpec, Provider } from '../types.js';
+import type { BuiltinToolId, KeySlot, ModelBinding, Provider } from '../types.js';
 /** Providers that resolve a vault `keySlot` on each turn. */
 export declare function providerUsesKeySlots(provider: Provider): boolean;
 /**
@@ -12,5 +12,5 @@ export declare function providerUsesKeySlots(provider: Provider): boolean;
  * When `required` is false and nothing pins a slot, returns `undefined` so hosts
  * can use a single flat `apiKey` (OpenRouter without a vault).
  */
-declare function resolveKeySlot(profileKey: KeySlot | undefined, spec: ModelSpec, builtins: BuiltinToolId[], required: boolean): KeySlot | undefined;
+declare function resolveKeySlot(profileKey: KeySlot | undefined, binding: ModelBinding, builtins: BuiltinToolId[], required: boolean): KeySlot | undefined;
 export { resolveKeySlot };

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

@@ -22,9 +22,9 @@ export function providerUsesKeySlots(provider) {
  * When `required` is false and nothing pins a slot, returns `undefined` so hosts
  * can use a single flat `apiKey` (OpenRouter without a vault).
  */
-function resolveKeySlot(profileKey, spec, builtins, required) {
-    if (spec.key) {
-        return spec.key;
+function resolveKeySlot(profileKey, binding, builtins, required) {
+    if (binding.key) {
+        return binding.key;
     }
     if (builtins.some((id) => builtinForcesPaid(id))) {
         return 'paid';
@@ -33,7 +33,7 @@ function resolveKeySlot(profileKey, spec, builtins, required) {
         return profileKey;
     }
     if (required) {
-        throw new TheorumError('Profile must set model.key or model.config.*.key');
+        throw new TheorumError('Profile must set key or models.*.key'); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
     }
     return undefined;
 }

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

@@ -7,8 +7,11 @@
  *
  * @module
  */
+/** lexicon-exempt-file: authoring field-meta / closed unions — not runtime user or model copy (P2) */
+import { EGRESS_ON_BLOCK, type EgressOnBlock } from '../guardrails/types.js';
+export { EGRESS_ON_BLOCK, type EgressOnBlock };
 /** Primary profile archetype. Discriminated union key for `ProfileDefinition` and `Profile`. */
-export declare const PROFILE_TYPES: readonly ["text", "image", "speech", "live"];
+export declare const PROFILE_TYPES: readonly ["text", "image", "speech", "live", "host"];
 export type ProfileType = (typeof PROFILE_TYPES)[number];
 /** Model reasoning effort level normalized across provider adapters. */
 export declare const THINKING_LEVELS: readonly ["none", "minimal", "low", "medium", "high", "xhigh", "max"];
@@ -30,13 +33,15 @@ export declare const PROTOCOL_PROVIDERS: {
 };
 /**
  * Legal wire protocols for each profile archetype.
- * 'live' profiles require 'geminiLive'; turn-based archetypes require turn protocols.
+ * 'live' profiles require 'geminiLive'; turn-based archetypes require turn protocols;
+ * 'host' never runs a model and binds no protocol.
  */
 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 host: readonly [];
 };
 export type ProfileTypeProtocol<T extends ProfileType> = (typeof PROFILE_TYPE_PROTOCOLS)[T][number];
 /** Protocols allowed for a profile archetype (`type`). */
@@ -52,8 +57,6 @@ export type OverflowKeySlot = (typeof OVERFLOW_KEY_SLOTS)[number];
 /** Host vault: one optional credential string per key slot. */
 export type KeyVault = Record<KeySlot, string | undefined>;
 /** Profile-level control a caller may toggle at turn time. */
-export declare const CONTROL_IDS: readonly ["thinking"];
-export type ControlId = (typeof CONTROL_IDS)[number];
 /** Normalized multimodal part category. */
 export declare const MEDIA_INPUT_KIND_VALUES: readonly ["image", "audio", "video", "document"];
 export type MediaInputKind = (typeof MEDIA_INPUT_KIND_VALUES)[number];
@@ -66,6 +69,11 @@ export type StreamMode = (typeof STREAM_MODES)[number];
 /** Audio container for speech generation output. */
 export declare const SPEECH_AUDIO_FORMATS: readonly ["pcm", "mp3"];
 export type SpeechAudioFormat = (typeof SPEECH_AUDIO_FORMATS)[number];
+/** Speech `format` values legal for a wire protocol (`assertSpeechRole` / UI). */
+export declare function speechFormatsForProtocol(protocol: Protocol): readonly SpeechAudioFormat[];
+export declare function isSpeechFormatAllowedForProtocol(protocol: Protocol, format: SpeechAudioFormat): boolean;
+/** Snap an illegal or omitted format to the first legal value for the protocol. */
+export declare function coerceSpeechFormat(protocol: Protocol, format: SpeechAudioFormat | undefined): SpeechAudioFormat;
 /** Live session activity handling (barge-in behavior). */
 export declare const LIVE_ACTIVITY_HANDLINGS: readonly ["START_OF_ACTIVITY_INTERRUPTS", "NO_INTERRUPTION"];
 export type LiveActivityHandling = (typeof LIVE_ACTIVITY_HANDLINGS)[number];
@@ -84,24 +92,100 @@ export type CompactionMeter = (typeof COMPACTION_METERS)[number];
 /** When compaction runs relative to the primary turn. */
 export declare const COMPACTION_TIMINGS: readonly ["before", "after"];
 export type CompactionTiming = (typeof COMPACTION_TIMINGS)[number];
-/** Egress block handling. */
-export declare const EGRESS_ON_BLOCK: readonly ["reject_to_agent", "refuse_to_user"];
-export type EgressOnBlock = (typeof EGRESS_ON_BLOCK)[number];
+/** OpenRouter prompt-cache mode (models.*.cache.mode). */
+export declare const CACHE_MODES: readonly ["automatic", "system"];
+export type CacheMode = (typeof CACHE_MODES)[number];
+/** OpenRouter ephemeral cache TTL (models.*.cache.ttl). */
+export declare const CACHE_TTLS: readonly ["5m", "1h"];
+export type CacheTtl = (typeof CACHE_TTLS)[number];
 /** Why a turn ended (provider-neutral). */
-export declare const TURN_STOP_KINDS: readonly ["completed", "length", "tool", "filtered", "provider_error", "cancelled", "stream_incomplete", "interrupted", "generation_complete"];
+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];
+/**
+ * Stop kinds eligible for `continueFrom` / resumption allowlists.
+ * Excludes terminal-success, user abort, tool/gate suspension, filter, and live-only
+ * boundaries — those use other host paths (or are not resumeable).
+ */
+export declare const CONTINUE_STOP_KINDS: readonly ["length", "stream_incomplete", "provider_error"];
+export type ContinueStopKind = (typeof CONTINUE_STOP_KINDS)[number];
+/**
+ * Turn / utterance-cycle timeline stages (`docs/contracts/stages.md`).
+ * Replaces the former steer barriers (`pre_llm` / `pre_tool_followup`).
+ */
+export declare const TURN_STAGES: readonly ["pre_turn", "pre_tool", "post_tool", "before_end", "post_turn"];
+export type TurnStage = (typeof TURN_STAGES)[number];
+/** True when `value` is a known `TurnStage`. */
+export declare function isTurnStage(value: unknown): value is TurnStage;
+/** Stages where inject is physically meaningful (still requires inject gate). */
+export declare const TURN_INJECT_STAGES: readonly ["pre_turn", "post_tool", "before_end"];
+export type TurnInjectStage = (typeof TURN_INJECT_STAGES)[number];
+/** True when inject is physically meaningful at this stage (gate still required). */
+export declare function isTurnInjectStage(value: unknown): value is TurnInjectStage;
+/** `pre_tool` gate kinds — confirm-to-run / permission / auth. Not awaiting. */
+export declare const TOOL_GATE_KINDS: readonly ["confirmation", "permission", "auth"];
+export type ToolGateKind = (typeof TOOL_GATE_KINDS)[number];
+/** True when `value` is a known tool-gate kind. */
+export declare function isToolGateKind(value: unknown): value is ToolGateKind;
+/** `awaiting_user_input.kind` — harness ask_user / human-as-product completions. */
+export declare const AWAITING_USER_INPUT_KINDS: readonly ["confirm", "choice", "text"];
+export type AwaitingUserInputKind = (typeof AWAITING_USER_INPUT_KINDS)[number];
+/** Discriminator on tool output for awaiting completions. */
+export declare const AWAITING_USER_INPUT_STATUS: "awaiting_user_input";
 /** Per-tool visibility tier — 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];
+/** HTTP verbs supported by declarative HTTP tools. */
+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 ["pause", "report_to_model"];
+export type AuthUnauthenticatedPolicy = (typeof AUTH_UNAUTHENTICATED_POLICIES)[number];
 /** Registered tool discriminant (`registerTool`). */
-export declare const TOOL_TYPES: readonly ["builtin", "function"];
+export declare const TOOL_TYPES: readonly ["builtin", "function", "http", "mcp"];
 /** Semantic access level — host policy / UI; not enforced by execute. */
 export declare const TOOL_ACCESS: readonly ["read-only", "read-write", "destructive"];
 export type ToolAccess = (typeof TOOL_ACCESS)[number];
 /** Execution authorization tier for registered tools. */
 export declare const TOOL_PERMISSION: readonly ["auto", "session_consent", "always_confirm"];
 export type ToolPermission = (typeof TOOL_PERMISSION)[number];
-/** MIME essence → normalized media part category (shared ingress map). */
+/** Credential attachment modes for HTTP and MCP tools (`auth.type`). */
+export declare const TOOL_AUTH_TYPES: readonly ["bearer", "api_key", "oauth2"];
+export type ToolAuthType = (typeof TOOL_AUTH_TYPES)[number];
+/** Playground auth select — includes UI-only `none` (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];
+/** Custom registerTool discriminants (excludes provider builtins). */
+export type CustomToolType = Exclude<ToolType, 'builtin'>;
+/**
+ * MIME essence → normalized media part category.
+ *
+ * This table is the complete media-input vocabulary of the package: every MIME
+ * any supported transport may carry on a turn appears here exactly once, and
+ * nothing else is a media input type. `assertMediaMime` (`registry/ingress.ts`)
+ * refuses anything absent from it, so hosts declare what they accept in
+ * `inputs.attachments.accept` / `inputs.voice.accept` and keep no second table.
+ *
+ * Contents are the union of the documented provider input lists:
+ * - Google Interactions / Live (image, audio, video, document lists verified
+ *   2026-09-12) — the widest of the three and therefore the table's shape. The
+ *   document row is Google's document-understanding list in full: PDF, plain
+ *   text, HTML, CSS, Markdown (`text/md`), CSV, XML, RTF, JavaScript
+ *   (`text/javascript`, `application/x-javascript`) and Python
+ *   (`text/x-python`, `application/x-python`); `application/json` is an
+ *   established row alongside it. TypeScript, `application/xml` and
+ *   `application/rtf` are NOT on Google's list and are therefore not rows.
+ * - OpenRouter / OpenAI-compat (`providers/openrouter/openai/compat.ts`,
+ *   `sdk-messages.ts`): the adapters wire every `MediaInputKind` (image →
+ *   `image_url`/`image`, audio → `input_audio`, video and document → `file`)
+ *   and forward the part's MIME verbatim, so their accepted set is open-ended
+ *   and adds no rows. What they cannot carry — a `uri` reference part — is
+ *   refused at request time with `TheorumError`, not by a second MIME list.
+ *
+ * Alias essences that providers also emit (`image/jpg`, `video/mov`,
+ * `audio/x-wav`, `video/x-ms-wmv`, …) are rows here; `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/*"];
@@ -129,7 +213,7 @@ export type FieldMeta = {
 };
 /**
  * Parents whose next key is a host-owned map key (model id, slot name, …).
- * The annotator substitutes `*` so `model.config.flash.apiId` → `model.config.*.apiId`.
+ * The annotator substitutes `*` so `models.flash.apiId` → `models.*.apiId`.
  */
 export declare const DYNAMIC_FIELD_PARENTS: ReadonlySet<string>;
 /** Resolve a key stack from authored source into a catalog path. */
@@ -143,3 +227,5 @@ export declare const PROFILE_FIELDS: Record<string, FieldMeta>;
 export declare const EXTRA_FIELDS: Record<string, FieldMeta>;
 /** Look up hover metadata for a dotted path (profile first, then extra). */
 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';