theorum 0.1.15 → 1.1.3

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

@@ -1,126 +1,83 @@
 /**
  * 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 { resolveGuardrailPolicy } from '../../guardrails/policy.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 { profileTurnResumption } from '../stop.js';
+import { projectTools } from '../tools/project.js';
+import { resolveTurnTools } from '../tools/resolve.js';
+import { requireModelBinding } 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));
-    });
-}
-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;
-    }
-    return selectMap[key];
-}
-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}`);
+import { soleModelId } from './sole-model.js';
+import { resolveTurnSystemPrompt } from './system-prompt.js';
+import { providerUsesKeySlots, resolveKeySlot } from './vault.js';
+/** 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 profile;
+}
+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`);
+        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;
     }
-    return only;
-}
-function thinkingFromControl(spec, thinkingOn) {
-    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 fromFirst = pinnedLevel(pinned, firstSelectKey(profile.model.select ?? {}));
-    if (fromFirst) {
-        return fromFirst;
-    }
-    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);
-}
-function resolveSummaries(profile, spec, thinkingOn) {
-    if (profile.model.controls?.includes('thinking')) {
-        if (thinkingOn) {
-            return spec.summaries.on;
+    const keys = Object.keys(efforts);
+    if (requested) {
+        if (!binding.allowEffortSelect) {
+            throw new TheorumError(`Profile ${profile.id} model '${modelId}' does not allow effort selection`);
         }
-        return spec.summaries.off;
+        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;
     }
-    return spec.summaries.on;
-}
-function isGatedOn(requested, id) {
-    if (!requested) {
-        return false;
+    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`);
     }
-    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));
+    return efforts[alias];
 }
-function assertToolAllowed(profile, name) {
-    if (!profile.tools.allow.includes(name)) {
-        throw new TheorumError(`Tool '${name}' is not allowed on ${profile.id}`);
+function resolveSummaries(binding) {
+    if (binding.summaries === true) {
+        return 'auto';
     }
+    if (binding.summaries === false) {
+        return 'none';
+    }
+    return undefined;
 }
 function resolveStructured(profile, slots) {
-    const { structured } = profile.outputs;
+    if (profile.type === 'live') {
+        return null;
+    }
+    const structured = profile.outputs?.structured;
     if (!structured) {
         return null;
     }
@@ -136,82 +93,140 @@ 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) {
+    if (profile.type === 'live') {
+        return true;
+    }
+    return profile.outputs?.streaming?.mode !== 'buffered';
+}
+function resolveStore(binding, reqStore) {
+    if (reqStore !== undefined) {
+        return reqStore;
+    }
+    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 turnBehaviour.resumption/continueFrom`);
+    }
+    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 turnBehaviour.resumption.maxContinues is set`);
+    }
+    if (attempt < 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 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 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 profile = requireModelProfile(getProfile(safe.profile), 'resolveTurn');
+    assertTurnResumption(profile, safe);
+    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 geminiBucket = profile.model.provider === 'google'
-        ? resolveGeminiBucket(profile.model.key ?? 'freeA', spec, builtins)
+    const pinnedKey = profile.key ?? binding.key;
+    const keySlot = providerUsesKeySlots(binding.provider)
+        ? resolveKeySlot(pinnedKey, binding, builtins, binding.provider === 'google')
         : undefined;
+    const previousInteractionId = binding.persistViaInteractionId === false ? undefined : safe.previousInteractionId;
     return {
         profile,
         generation: {
             model,
-            apiId: spec.apiId,
-            openRouterId: spec.openRouterId,
-            previousInteractionId: safe.previousInteractionId,
-            store: safe.store,
-            thinking: resolveThinking(profile, spec, thinkingOn, safe.select),
-            summaries: resolveSummaries(profile, spec, thinkingOn),
-            maxOutputTokens: spec.maxOutputTokens,
-            temperature: spec.temperature,
+            apiId: binding.apiId,
+            transport: resolveTransport(profile, binding),
+            previousInteractionId,
+            store: resolveStore(binding, safe.store),
+            stream: resolveStreamFlag(profile),
+            thinking: resolveEffort(profile, binding, model, safe.effort),
+            summaries: resolveSummaries(binding),
+            maxOutputTokens: binding.maxOutputTokens,
+            temperature: binding.temperature,
             builtins,
-            custom: resolveCustom(profile, safe.tools),
-            dynamicTools: safe.dynamicTools,
-            dynamicToolLoader: safe.dynamicToolLoader,
+            googleMapsLocation: safe.googleMapsLocation,
+            cache: binding.cache,
+            sessionId: safe.sessionId,
+            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.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: resolveGuardrailPolicy(profile.guardrails).canary ? mintCanary() : '',
+            sessionResumptionHandle: safe.sessionResumptionHandle ?? input.sessionResumptionHandle,
+            resolvedSystem: resolveTurnSystemPrompt(profile, safe),
+            host: safe.host,
         },
     };
 }
 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' || profile.type === 'live') {
+        return null;
+    }
+    return profile.inputs ?? null;
+}
+/** Project a profile object into a safe host/UI inspection object. */
+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,
-        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,
+        models: profile.models,
+        defaultModel: profile.defaultModel,
+        allowModelSelect: profile.allowModelSelect,
+        maxSteps: profile.maxSteps,
+        key: profile.key,
+        tools: projectTools(profile),
         inputs,
-        slots: slots ?? {},
         outputs,
         image: primaryImageSpec(profile),
+        speech: profile.type === 'speech' ? profile.speech : null,
+        live: profile.type === 'live' ? profile.live : null,
     };
 }
-function pickSystemRole(profile, requested) {
-    const { identity } = profile;
-    const { handle, systemByRole } = identity;
-    if (requested && systemByRole && Object.hasOwn(systemByRole, requested)) {
-        return requested;
-    }
-    return handle;
+/** Project a registered profile into a safe host/UI inspection object. */
+function projectProfile(id) {
+    return projectProfileObject(getProfile(id));
 }
-export { assertToolAllowed, pickSystemRole, projectProfile, 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

@@ -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, ModelBinding, 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, binding: ModelBinding, 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) {
-    if (spec.key) {
-        return spec.key;
+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;
     }
-    if (builtins.some((id) => !spec.keyBuiltins.includes(id))) {
+    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, binding, builtins, required) {
+    if (binding.key) {
+        return binding.key;
+    }
+    if (builtins.some((id) => builtinForcesPaid(id))) {
         return 'paid';
     }
-    return profileKey;
+    if (profileKey) {
+        return profileKey;
+    }
+    if (required) {
+        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;
 }
-export { resolveGeminiBucket };
+export { resolveKeySlot };