theorum 0.1.14 → 1.0.0

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

@@ -1,24 +1,17 @@
 /**
  * Profile resolution for THEORUM turns.
  *
- * This module validates caller overrides, selects models and tools, normalizes
- * input parts, and produces the provider request state consumed by `runTurn`.
- *
  * @module
  */
+import { mintCanary } from '../../guardrails/canary.js';
 import { TheorumError } from '../../guardrails/error.js';
 import { sanitizeTurnRequest } from '../../guardrails/sanitize.js';
-import { mintCanary } from '../engine/boundary.js';
-import { CATALOG, clampThinkingLevel, getTool, listBuiltinIds, requireModelSpec, } from './catalog.js';
-import { assertImageGrounding, assertSpeechRole, resolveImageFormat, resolveInputParts, } from './ingress.js';
+import { projectTools } from '../tools/project.js';
+import { resolveTurnTools } from '../tools/resolve.js';
+import { clampThinkingLevel, requireModelSpec } from './catalog.js';
+import { assertOutputMode, assertSpeechRole, resolveImageFormat, resolveInputParts, } from './ingress.js';
 import { getProfile } from './profiles.js';
-import { resolveGeminiBucket } from './vault.js';
-function applyBuiltinMutualExclusions(requested) {
-    return requested.filter((id) => {
-        const conflicts = getTool(id)?.conflictsWith ?? [];
-        return !conflicts.some((other) => requested.includes(other));
-    });
-}
+import { providerUsesKeySlots, resolveKeySlot } from './vault.js';
 function firstSelectKey(selectMap) {
     const [key] = Object.keys(selectMap);
     return key;
@@ -56,6 +49,9 @@ function pickModel(profile, select) {
     return only;
 }
 function thinkingFromControl(spec, thinkingOn) {
+    if (!spec.thinking) {
+        throw new TheorumError('model.config thinking map is required when controls include thinking');
+    }
     if (thinkingOn) {
         return spec.thinking.on;
     }
@@ -92,6 +88,9 @@ function resolveThinking(profile, spec, thinkingOn, select) {
     return clampThinkingLevel(spec, raw);
 }
 function resolveSummaries(profile, spec, thinkingOn) {
+    if (!spec.summaries) {
+        return undefined;
+    }
     if (profile.model.controls?.includes('thinking')) {
         if (thinkingOn) {
             return spec.summaries.on;
@@ -100,27 +99,8 @@ function resolveSummaries(profile, spec, thinkingOn) {
     }
     return spec.summaries.on;
 }
-function isGatedOn(requested, id) {
-    if (!requested) {
-        return false;
-    }
-    return requested[id] === true;
-}
-function resolveBuiltins(profile, requested) {
-    const allowed = profile.tools.allow.filter((id) => CATALOG.tools[id]?.kind === 'builtin');
-    const picked = listBuiltinIds().filter((id) => allowed.includes(id) && isGatedOn(requested, id));
-    return applyBuiltinMutualExclusions(picked);
-}
-function resolveCustom(profile, requested) {
-    return profile.tools.allow.filter((id) => CATALOG.tools[id]?.kind === 'custom' && isGatedOn(requested, id));
-}
-function assertToolAllowed(profile, name) {
-    if (!profile.tools.allow.includes(name)) {
-        throw new TheorumError(`Tool '${name}' is not allowed on ${profile.id}`);
-    }
-}
 function resolveStructured(profile, slots) {
-    const { structured } = profile.outputs;
+    const structured = profile.outputs?.structured;
     if (!structured) {
         return null;
     }
@@ -136,76 +116,126 @@ function resolveStructured(profile, slots) {
     }
     return structured.fallback;
 }
+/**
+ * THEORUM prefers SSE when the host omits `outputs.streaming.mode`.
+ * Explicit `'buffered'` opts out; `'sse'` (or omit) yields `stream: true`.
+ */
+function resolveStreamFlag(profile) {
+    return profile.outputs?.streaming?.mode !== 'buffered';
+}
+function resolveStore(spec, reqStore) {
+    if (reqStore !== undefined) {
+        return reqStore;
+    }
+    return spec.store;
+}
+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`);
+    }
+    const policy = profile.turnResumption;
+    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`);
+    }
+    if (attempt < 1) {
+        throw new TheorumError(`Profile ${profile.id}: continuation must be >= 1`);
+    }
+    if (attempt > max) {
+        throw new TheorumError(`Profile ${profile.id}: continuation ${attempt} exceeds turnResumption.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);
+    assertTurnResumption(profile, safe);
     const model = pickModel(profile, safe.select);
     const spec = requireModelSpec(profile, model);
     const thinkingOn = safe.thinking === true;
-    const builtins = resolveBuiltins(profile, safe.tools);
-    assertImageGrounding(profile, model, builtins);
+    const toolSnapshot = resolveTurnTools(profile, safe, model);
+    const builtins = toolSnapshot.builtins;
+    const structured = resolveStructured(profile, input.slots);
+    assertOutputMode(profile, structured);
     assertSpeechRole(profile);
-    const geminiBucket = profile.model.provider === 'google'
-        ? resolveGeminiBucket(profile.model.key ?? 'freeA', spec, builtins)
+    const pinnedKey = profile.model.key ?? spec.key;
+    const keySlot = providerUsesKeySlots(profile.model.provider)
+        ? resolveKeySlot(pinnedKey, spec, builtins, profile.model.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;
     return {
         profile,
         generation: {
             model,
             apiId: spec.apiId,
-            openRouterId: spec.openRouterId,
-            previousInteractionId: safe.previousInteractionId,
-            store: safe.store,
+            transport,
+            previousInteractionId,
+            store: resolveStore(spec, safe.store),
+            stream: resolveStreamFlag(profile),
             thinking: resolveThinking(profile, spec, thinkingOn, safe.select),
             summaries: resolveSummaries(profile, spec, thinkingOn),
             maxOutputTokens: spec.maxOutputTokens,
             temperature: spec.temperature,
             builtins,
-            custom: resolveCustom(profile, safe.tools),
-            dynamicTools: safe.dynamicTools,
-            dynamicToolLoader: safe.dynamicToolLoader,
+            googleMapsLocation: safe.googleMapsLocation,
+            tools: toolSnapshot,
             sessionPermissions: safe.sessionPermissions,
             history: input.history,
-            maxSteps: profile.model.maxSteps ?? 1,
-            structured: resolveStructured(profile, input.slots),
-            image: resolveImageFormat(profile, model, input.slots),
-            speech: profile.outputs.speech,
+            maxSteps: profile.model.maxSteps,
+            structured,
+            image: resolveImageFormat(profile),
+            speech: profile.type === 'speech' ? profile.speech : undefined,
+            live: profile.type === 'live' ? profile.live : undefined,
             input: resolveInputParts(profile, model, safe),
-            geminiBucket,
-            canary: profile.guardrails.canary !== false ? mintCanary() : '',
+            keySlot,
+            canary: profile.guardrails?.canary === true ? mintCanary() : '',
+            sessionResumptionHandle: safe.sessionResumptionHandle ?? input.sessionResumptionHandle,
         },
     };
 }
 function primaryImageSpec(profile) {
-    return profile.outputs.image;
+    return profile.type === 'image' ? profile.image : null;
 }
-/** Project a registered profile into a safe host/UI inspection object. */
-function projectProfile(id) {
-    const profile = getProfile(id);
-    const { model, identity, tools, inputs, outputs } = profile;
-    const { select, allow, maxSteps, controls } = model;
-    const { handle, chat } = identity;
-    const { slots } = inputs;
+function profileInputsOrNull(profile) {
+    if (profile.type === 'speech') {
+        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;
+    const inputs = profileInputsOrNull(profile);
     return {
         id: profile.id,
-        handle,
-        chat: chat !== false,
-        maxSteps: maxSteps ?? 1,
-        models: allow,
-        select: select ?? null,
-        controls: controls ?? [],
-        tools: tools.allow.map((name) => ({
-            name,
-            ...(CATALOG.tools[name] ?? { kind: 'custom', ui: true }),
-        })),
+        type: profile.type,
+        handle: identity.handle,
+        model,
+        tools: projectTools(profile),
         inputs,
-        slots: slots ?? {},
-        outputs,
+        outputs: outputs ?? null,
         image: primaryImageSpec(profile),
+        speech: profile.type === 'speech' ? profile.speech : null,
+        live: profile.type === 'live' ? profile.live : null,
     };
 }
+/** Project a registered profile into a safe host/UI inspection object. */
+function projectProfile(id) {
+    return projectProfileObject(getProfile(id));
+}
 function pickSystemRole(profile, requested) {
     const { identity } = profile;
     const { handle, systemByRole } = identity;
@@ -214,4 +244,4 @@ function pickSystemRole(profile, requested) {
     }
     return handle;
 }
-export { assertToolAllowed, pickSystemRole, projectProfile, resolveTurn };
+export { pickModel, pickSystemRole, projectProfile, projectProfileObject, resolveTurn };

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

@@ -1,11 +1,16 @@
 /**
- * Gemini vault slot selection for Google Interactions transport.
- *
- * Host-owned policy over `ModelSpec.key` / `keyBuiltins`. Pure; no network.
+ * Vault key-slot selection for credentialed transports (Google, OpenRouter, …).
  *
  * @module
  */
-import type { BuiltinToolId, GeminiBucket, GeminiFreeBucket, ModelSpec } from '../types.js';
-/** Pick the vault slot for a turn from profile key, model pin, and builtins. */
-declare function resolveGeminiBucket(profileKey: GeminiFreeBucket, spec: ModelSpec, builtins: BuiltinToolId[]): GeminiBucket;
-export { resolveGeminiBucket };
+import type { BuiltinToolId, KeySlot, ModelSpec, Provider } from '../types.js';
+/** Providers that resolve a vault `keySlot` on each turn. */
+export declare function providerUsesKeySlots(provider: Provider): boolean;
+/**
+ * Pick the key slot for a turn from profile key, model pin, and enabled builtins.
+ *
+ * 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;
+export { resolveKeySlot };

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

@@ -1,18 +1,40 @@
 /**
- * Gemini vault slot selection for Google Interactions transport.
- *
- * Host-owned policy over `ModelSpec.key` / `keyBuiltins`. Pure; no network.
+ * Vault key-slot selection for credentialed transports (Google, OpenRouter, …).
  *
  * @module
  */
-/** Pick the vault slot for a turn from profile key, model pin, and builtins. */
-function resolveGeminiBucket(profileKey, spec, builtins) {
+import { TheorumError } from '../../guardrails/error.js';
+import { getTool } from '../tools/registry.js';
+function builtinForcesPaid(id) {
+    const tool = getTool(id);
+    if (tool?.type !== 'builtin') {
+        return false;
+    }
+    return tool.forcePaidKey === true;
+}
+/** Providers that resolve a vault `keySlot` on each turn. */
+export function providerUsesKeySlots(provider) {
+    return provider === 'google' || provider === 'openrouter';
+}
+/**
+ * Pick the key slot for a turn from profile key, model pin, and enabled builtins.
+ *
+ * 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;
     }
-    if (builtins.some((id) => !spec.keyBuiltins.includes(id))) {
+    if (builtins.some((id) => builtinForcesPaid(id))) {
         return 'paid';
     }
-    return profileKey;
+    if (profileKey) {
+        return profileKey;
+    }
+    if (required) {
+        throw new TheorumError('Profile must set model.key or model.config.*.key');
+    }
+    return undefined;
 }
-export { resolveGeminiBucket };
+export { resolveKeySlot };

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

@@ -0,0 +1,145 @@
+/**
+ * Runtime vocabulary and field catalog for THEORUM profile types.
+ *
+ * Closed unions live here as `as const` arrays; TypeScript types are derived
+ * from those arrays. Host UIs and docs import this module (no Deno APIs) so
+ * dropdowns and hover tips stay in lockstep with the kernel.
+ *
+ * @module
+ */
+/** Primary profile archetype. Discriminated union key for `ProfileDefinition` and `Profile`. */
+export declare const PROFILE_TYPES: readonly ["text", "image", "speech", "live"];
+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"];
+export type ThinkingLevel = (typeof THINKING_LEVELS)[number];
+/** Wire protocol for a profile. */
+export declare const PROTOCOLS: readonly ["geminiInteractions", "geminiLive", "openAi"];
+export type Protocol = (typeof PROTOCOLS)[number];
+/** Transport provider for a profile. */
+export declare const PROVIDERS: readonly ["google", "openrouter", "local"];
+export type Provider = (typeof PROVIDERS)[number];
+/**
+ * Legal `createProvider` pairs. Keep this table in lockstep with the factory.
+ * Keys are protocols; values are the providers that protocol may bind.
+ */
+export declare const PROTOCOL_PROVIDERS: {
+    readonly geminiInteractions: readonly ["google"];
+    readonly geminiLive: readonly ["google"];
+    readonly openAi: readonly ["openrouter", "local"];
+};
+/**
+ * Legal wire protocols for each profile archetype.
+ * 'live' profiles require 'geminiLive'; turn-based archetypes require turn protocols.
+ */
+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"];
+};
+export type ProfileTypeProtocol<T extends ProfileType> = (typeof PROFILE_TYPE_PROTOCOLS)[T][number];
+/** Protocols allowed for a profile archetype (`type`). */
+export declare function protocolsForProfileType(type: ProfileType): readonly Protocol[];
+/** True when the protocol is valid for the given profile archetype. */
+export declare function isValidProfileProtocol(type: ProfileType, protocol: Protocol): boolean;
+/** Named vault key slots for host-supplied credentials (provider-neutral). */
+export declare const KEY_SLOTS: readonly ["slotA", "slotB", "slotC", "paid"];
+export type KeySlot = (typeof KEY_SLOTS)[number];
+/** Key slots that may overflow to `paid` after quota backoff. */
+export declare const OVERFLOW_KEY_SLOTS: readonly ["slotA", "slotB", "slotC"];
+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];
+/** Provider thinking-summary behavior. */
+export declare const SUMMARY_MODES: readonly ["auto", "none"];
+export type SummaryMode = (typeof SUMMARY_MODES)[number];
+/** Stream delivery mode. */
+export declare const STREAM_MODES: readonly ["sse", "buffered"];
+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];
+/** 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];
+/** Live session voice activity detection sensitivity. */
+export declare const LIVE_SPEECH_SENSITIVITIES: readonly ["START_SENSITIVITY_LOW", "START_SENSITIVITY_HIGH", "END_SENSITIVITY_LOW", "END_SENSITIVITY_HIGH"];
+export type LiveSpeechSensitivity = (typeof LIVE_SPEECH_SENSITIVITIES)[number];
+/** Live session context window compression mode. */
+export declare const LIVE_CONTEXT_COMPRESSIONS: readonly ["slidingWindow", "none"];
+export type LiveContextCompression = (typeof LIVE_CONTEXT_COMPRESSIONS)[number];
+/** Structured-output enforcement mode. */
+export declare const SCHEMA_ENFORCEMENTS: readonly ["responseFormat", "prompt"];
+export type SchemaEnforcement = (typeof SCHEMA_ENFORCEMENTS)[number];
+/** Compaction threshold meter. */
+export declare const COMPACTION_METERS: readonly ["history", "input"];
+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];
+/** 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 type TurnStopKind = (typeof TURN_STOP_KINDS)[number];
+/** 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];
+/** Registered tool discriminant (`registerTool`). */
+export declare const TOOL_TYPES: readonly ["builtin", "function"];
+/** 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). */
+export declare const MEDIA_INPUT_KINDS: Record<string, MediaInputKind>;
+/** Type-prefix wildcards accepted by `mimeAllowed`. */
+export declare const MEDIA_WILDCARDS: readonly ["image/*", "audio/*", "video/*"];
+/** Attachment `accept` values the kernel can classify (wildcards + known types). */
+export declare const ATTACHMENT_ACCEPT_MIMES: readonly string[];
+/** Voice `accept` values the kernel can classify (wildcard + known audio types). */
+export declare const VOICE_ACCEPT_MIMES: readonly string[];
+/** Providers allowed for a protocol. */
+export declare function providersFor(protocol: Protocol): readonly Provider[];
+/** Protocols allowed for a 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;
+/** Metadata for one profile (or adjacent) field, used by docs/UI hover. */
+export type FieldMeta = {
+    type: string;
+    doc: string;
+    options?: readonly string[];
+    optionDescriptions?: Record<string, string>;
+    optionNote?: string;
+};
+/**
+ * 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`.
+ */
+export declare const DYNAMIC_FIELD_PARENTS: ReadonlySet<string>;
+/** Resolve a key stack from authored source into a catalog path. */
+export declare function catalogPathFor(keys: readonly string[]): string;
+/**
+ * Authoring-surface catalog for `Profile` / `defineProfile`.
+ * Hover UIs look up dotted paths. Adding a profile field? Add it here.
+ */
+export declare const PROFILE_FIELDS: Record<string, FieldMeta>;
+/** Adjacent tool catalog fields that appear next to profile examples. */
+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;