theorum 0.1.2 → 0.1.4

package/src/kernel/registry/resolve.ts

@@ -0,0 +1,290 @@
+/**
+ * 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.ts';
+import { sanitizeTurnRequest } from '../../guardrails/sanitize.ts';
+import { mintCanary } from '../engine/boundary.ts';
+import type {
+  BuiltinToolId,
+  CustomToolId,
+  ModelId,
+  ModelSpec,
+  Profile,
+  ProjectedProfile,
+  ResolvedGeneration,
+  StructuredSchemaId,
+  ThinkingLevel,
+  ToolId,
+  TurnRequest,
+} from '../types.ts';
+import {
+  CATALOG,
+  clampThinkingLevel,
+  getTool,
+  listBuiltinIds,
+  requireModelSpec,
+} from './catalog.ts';
+import {
+  assertImageGrounding,
+  assertSpeechRole,
+  resolveImageFormat,
+  resolveInputParts,
+} from './ingress.ts';
+import { getProfile } from './profiles.ts';
+import { resolveGeminiBucket } from './vault.ts';
+
+function applyBuiltinMutualExclusions(requested: BuiltinToolId[]): BuiltinToolId[] {
+  return requested.filter((id) => {
+    const conflicts = getTool(id)?.conflictsWith ?? [];
+    return !conflicts.some((other) => requested.includes(other));
+  });
+}
+
+function firstSelectKey(selectMap: Record<string, ModelId>): string | undefined {
+  const [key] = Object.keys(selectMap);
+  return key;
+}
+
+function lookupSelectId(profile: Profile, select?: string): ModelId | undefined {
+  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: Profile, select?: string): ModelId {
+  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(spec: ModelSpec, thinkingOn: boolean | undefined): ThinkingLevel {
+  if (thinkingOn) {
+    return spec.thinking.on;
+  }
+  return spec.thinking.off;
+}
+
+function pinnedLevel(
+  pinned: Record<string, ThinkingLevel>,
+  key: string | undefined,
+): ThinkingLevel | undefined {
+  if (!key) {
+    return undefined;
+  }
+  return pinned[key];
+}
+
+function thinkingFromPin(profile: Profile, select?: string): ThinkingLevel {
+  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: Profile,
+  spec: ModelSpec,
+  thinkingOn: boolean | undefined,
+  select?: string,
+): ThinkingLevel {
+  const raw = profile.model.controls?.includes('thinking')
+    ? thinkingFromControl(spec, thinkingOn)
+    : thinkingFromPin(profile, select);
+  return clampThinkingLevel(spec, raw);
+}
+
+function resolveSummaries(
+  profile: Profile,
+  spec: ModelSpec,
+  thinkingOn: boolean | undefined,
+): 'auto' | 'none' {
+  if (profile.model.controls?.includes('thinking')) {
+    if (thinkingOn) {
+      return spec.summaries.on;
+    }
+    return spec.summaries.off;
+  }
+  return spec.summaries.on;
+}
+
+function isGatedOn(requested: Partial<Record<ToolId, boolean>> | undefined, id: ToolId): boolean {
+  if (!requested) {
+    return false;
+  }
+  return requested[id] === true;
+}
+
+function resolveBuiltins(
+  profile: Profile,
+  requested?: Partial<Record<ToolId, boolean>>,
+): BuiltinToolId[] {
+  const allowed = profile.tools.allow.filter(
+    (id): id is BuiltinToolId => CATALOG.tools[id]?.kind === 'builtin',
+  );
+  const picked = listBuiltinIds().filter((id) => allowed.includes(id) && isGatedOn(requested, id));
+  return applyBuiltinMutualExclusions(picked);
+}
+
+function resolveCustom(
+  profile: Profile,
+  requested?: Partial<Record<ToolId, boolean>>,
+): CustomToolId[] {
+  return profile.tools.allow.filter(
+    (id): id is CustomToolId => CATALOG.tools[id]?.kind === 'custom' && isGatedOn(requested, id),
+  );
+}
+
+function assertToolAllowed(profile: Profile, name: ToolId): void {
+  if (!profile.tools.allow.includes(name)) {
+    throw new TheorumError(`Tool '${name}' is not allowed on ${profile.id}`);
+  }
+}
+
+function resolveStructured(
+  profile: Profile,
+  slots?: Record<string, string>,
+): StructuredSchemaId | null {
+  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;
+}
+
+/** Resolve a host `TurnRequest` into provider-ready generation state. */
+function resolveTurn(req: TurnRequest): {
+  profile: Profile;
+  generation: ResolvedGeneration;
+} {
+  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);
+  assertSpeechRole(profile);
+  const geminiBucket =
+    profile.model.provider === 'google'
+      ? resolveGeminiBucket(profile.model.key ?? 'freeA', spec, builtins)
+      : undefined;
+  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,
+      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),
+      speech: profile.outputs.speech,
+      input: resolveInputParts(profile, model, safe),
+      geminiBucket,
+      canary: profile.guardrails.canary !== false ? mintCanary() : '',
+    },
+  };
+}
+
+function primaryImageSpec(profile: Profile) {
+  return profile.outputs.image;
+}
+
+/** Project a registered profile into a safe host/UI inspection object. */
+function projectProfile(id: Profile['id']): ProjectedProfile {
+  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' as const, ui: true }),
+    })),
+    inputs,
+    slots: slots ?? {},
+    outputs,
+    image: primaryImageSpec(profile),
+  };
+}
+
+function pickSystemRole(profile: Profile, requested?: string): string {
+  const { identity } = profile;
+  const { handle, systemByRole } = identity;
+  if (requested && systemByRole && Object.hasOwn(systemByRole, requested)) {
+    return requested;
+  }
+  return handle;
+}
+
+export { assertToolAllowed, pickSystemRole, projectProfile, resolveTurn };

package/src/kernel/registry/schemas.ts

@@ -0,0 +1,29 @@
+/**
+ * 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.ts';
+import type { StructuredSpec } from '../types.ts';
+
+const schemas = new Map<string, StructuredSpec>();
+
+/** Register a host-owned structured output schema. */
+function registerStructured(id: string, spec: StructuredSpec): void {
+  schemas.set(id, spec);
+}
+
+/** Fetch a registered structured output schema or throw a `TheorumError`. */
+function getStructured(id: string): StructuredSpec {
+  const spec = schemas.get(id);
+  if (!spec) {
+    throw new TheorumError(`Unknown structured schema '${id}'`);
+  }
+  return spec;
+}
+
+export { getStructured, registerStructured };

package/src/kernel/registry/tools.ts

@@ -0,0 +1,45 @@
+/**
+ * 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.ts';
+import { getTool } from './catalog.ts';
+import { assertToolAllowed } from './resolve.ts';
+
+function executeAskUser(args: Record<string, unknown>): ToolEnvelope {
+  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: getTool('askUser')?.schema },
+  };
+}
+
+/** Execute a static tool after enforcing the profile allowlist. */
+function executeTool(
+  profile: Profile,
+  name: CustomToolId,
+  args: Record<string, unknown>,
+): ToolEnvelope {
+  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 };

package/src/kernel/registry/vault.ts

@@ -0,0 +1,26 @@
+/**
+ * Gemini vault slot selection for Google Interactions transport.
+ *
+ * Host-owned policy over `ModelSpec.key` / `keyBuiltins`. Pure; no network.
+ *
+ * @module
+ */
+
+import type { BuiltinToolId, GeminiBucket, GeminiFreeBucket, ModelSpec } from '../types.ts';
+
+/** Pick the vault slot for a turn from profile key, model pin, and builtins. */
+function resolveGeminiBucket(
+  profileKey: GeminiFreeBucket,
+  spec: ModelSpec,
+  builtins: BuiltinToolId[],
+): GeminiBucket {
+  if (spec.key) {
+    return spec.key;
+  }
+  if (builtins.some((id) => !spec.keyBuiltins.includes(id))) {
+    return 'paid';
+  }
+  return profileKey;
+}
+
+export { resolveGeminiBucket };