theorum 0.1.2

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

@@ -0,0 +1,235 @@
+/**
+ * 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 { TheorumError } from '../../guardrails/error.js';
+import { resolveGeminiBucket } from '../../guardrails/keys.js';
+import { sanitizeTurnRequest } from '../../guardrails/sanitize.js';
+import { assertImageGrounding, resolveImageFormat, resolveInputParts, } from '../../providers/media.js';
+import { mintCanary } from '../engine/boundary.js';
+import { CATALOG, clampThinkingLevel, modelEntry } from './catalog.js';
+import { getProfile } from './profiles.js';
+const BUILTINS = ['googleSearch', 'googleMaps', 'urlContext'];
+function applyBuiltinMutualExclusions(requested) {
+    const search = requested.includes('googleSearch');
+    const maps = requested.includes('googleMaps');
+    const urlContext = requested.includes('urlContext');
+    // Google Interactions API: google_maps cannot be combined with google_search or url_context
+    if (maps && (search || urlContext)) {
+        return requested.filter((id) => id !== 'googleMaps');
+    }
+    return requested;
+}
+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}`);
+        }
+        return id;
+    }
+    const [only] = profile.model.allow;
+    if (!only) {
+        throw new TheorumError(`Profile ${profile.id} has no models`);
+    }
+    return only;
+}
+function thinkingFromControl(modelId, thinkingOn) {
+    const catalog = modelEntry(modelId);
+    if (thinkingOn) {
+        return catalog.thinking.on;
+    }
+    return catalog.thinking.off;
+}
+function pinnedLevel(pinned, key) {
+    if (!key) {
+        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, modelId, thinkingOn, select) {
+    const raw = profile.model.controls?.includes('thinking')
+        ? thinkingFromControl(modelId, thinkingOn)
+        : thinkingFromPin(profile, select);
+    return clampThinkingLevel(modelId, raw);
+}
+function resolveSummaries(profile, modelId, thinkingOn) {
+    const override = profile.model.override?.[modelId]?.summaries;
+    if (override) {
+        return override;
+    }
+    const entry = modelEntry(modelId);
+    if (profile.model.controls?.includes('thinking')) {
+        if (thinkingOn) {
+            return entry.summaries.on;
+        }
+        return entry.summaries.off;
+    }
+    return entry.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 = BUILTINS.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;
+    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 generationLimits(profile, model) {
+    const catalog = modelEntry(model);
+    const ov = profile.model.override?.[model];
+    return {
+        maxOutputTokens: ov?.maxOutputTokens ?? catalog.maxOutputTokens,
+        temperature: ov?.temperature ?? catalog.temperature,
+    };
+}
+/** 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 thinkingOn = safe.thinking === true;
+    const limits = generationLimits(profile, model);
+    const builtins = resolveBuiltins(profile, safe.tools);
+    assertImageGrounding(model, builtins);
+    return {
+        profile,
+        generation: {
+            model,
+            previousInteractionId: safe.previousInteractionId,
+            store: safe.store,
+            thinking: resolveThinking(profile, model, thinkingOn, safe.select),
+            summaries: resolveSummaries(profile, model, thinkingOn),
+            maxOutputTokens: limits.maxOutputTokens,
+            temperature: limits.temperature,
+            builtins,
+            custom: resolveCustom(profile, safe.tools),
+            dynamicTools: safe.dynamicTools,
+            dynamicToolLoader: safe.dynamicToolLoader,
+            sessionPermissions: safe.sessionPermissions,
+            history: input.history,
+            maxSteps: profile.model.maxSteps ?? 1,
+            structured: resolveStructured(profile, input.slots),
+            image: resolveImageFormat(profile, model, input.slots),
+            voice: profile.outputs.voice,
+            input: resolveInputParts(profile, model, safe),
+            geminiBucket: resolveGeminiBucket(profile.model.key ?? 'freeA', model, builtins),
+            canary: profile.guardrails.canary !== false ? mintCanary() : '',
+        },
+    };
+}
+function primaryImageSpec(allow) {
+    const [primary] = allow;
+    if (!primary) {
+        return undefined;
+    }
+    return modelEntry(primary).image;
+}
+/** UI projection: catalog ∩ profile. Swatches are not included. */
+/** 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;
+    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 }),
+        })),
+        inputs,
+        slots: slots ?? {},
+        outputs,
+        image: primaryImageSpec(allow),
+    };
+}
+function pickSystemRole(profile, requested) {
+    const { identity } = profile;
+    const { handle, systemByRole } = identity;
+    if (requested && systemByRole && Object.hasOwn(systemByRole, requested)) {
+        return requested;
+    }
+    return handle;
+}
+export { assertToolAllowed, pickSystemRole, projectProfile, resolveTurn };

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

@@ -0,0 +1,14 @@
+/**
+ * Runtime structured-output schema registry.
+ *
+ * Host apps register schemas by id, then reference those ids from profile output
+ * declarations.
+ *
+ * @module
+ */
+import type { StructuredSpec } from '../types.js';
+/** Register a host-owned structured output schema. */
+declare function registerStructured(id: string, spec: StructuredSpec): void;
+/** Fetch a registered structured output schema or throw a `TheorumError`. */
+declare function getStructured(id: string): StructuredSpec;
+export { getStructured, registerStructured };

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

@@ -0,0 +1,23 @@
+/**
+ * Runtime structured-output schema registry.
+ *
+ * Host apps register schemas by id, then reference those ids from profile output
+ * declarations.
+ *
+ * @module
+ */
+import { TheorumError } from '../../guardrails/error.js';
+const schemas = new Map();
+/** Register a host-owned structured output schema. */
+function registerStructured(id, spec) {
+    schemas.set(id, spec);
+}
+/** Fetch a registered structured output schema or throw a `TheorumError`. */
+function getStructured(id) {
+    const spec = schemas.get(id);
+    if (!spec) {
+        throw new TheorumError(`Unknown structured schema '${id}'`);
+    }
+    return spec;
+}
+export { getStructured, registerStructured };

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

@@ -0,0 +1,12 @@
+/**
+ * Generic built-in custom tool executor.
+ *
+ * Static custom tools are intentionally minimal. Application-specific tools
+ * should be supplied as dynamic declarations with host-owned handlers.
+ *
+ * @module
+ */
+import type { CustomToolId, Profile, ToolEnvelope } from '../types.js';
+/** Execute a static tool after enforcing the profile allowlist. */
+declare function executeTool(profile: Profile, name: CustomToolId, args: Record<string, unknown>): ToolEnvelope;
+export { executeTool };

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

@@ -0,0 +1,36 @@
+/**
+ * Generic built-in custom tool executor.
+ *
+ * Static custom tools are intentionally minimal. Application-specific tools
+ * should be supplied as dynamic declarations with host-owned handlers.
+ *
+ * @module
+ */
+import { CATALOG } from './catalog.js';
+import { assertToolAllowed } from './resolve.js';
+function executeAskUser(args) {
+    const { kind, prompt } = args;
+    if (kind !== 'confirm' && kind !== 'choice' && kind !== 'text') {
+        return { status: 'error', finding: 'askUser.kind must be confirm, choice, or text' };
+    }
+    if (typeof prompt !== 'string' || !prompt.trim()) {
+        return { status: 'error', finding: 'askUser.prompt is required' };
+    }
+    return {
+        status: 'pause',
+        finding: prompt,
+        data: { ...args, schema: CATALOG.tools.askUser.schema },
+    };
+}
+/** Execute a static tool after enforcing the profile allowlist. */
+function executeTool(profile, name, args) {
+    assertToolAllowed(profile, name);
+    if (name === 'askUser') {
+        return executeAskUser(args);
+    }
+    return {
+        status: 'error',
+        finding: `Tool '${name}' has no kernel executor; pass a dynamic tool handler instead.`,
+    };
+}
+export { executeTool };