@hed-hog/core 0.0.387 → 0.0.390

package/src/ai-instruction/ai-prompt-resolver.service.ts

@@ -0,0 +1,295 @@
+import { forwardRef, Inject, Injectable, Logger } from '@nestjs/common';
+import { AiInstructionService } from './ai-instruction.service';
+import { getAiPromptDefinition } from './ai-prompt-registry';
+import {
+  PromptTemplateError,
+  renderTemplate,
+  type TemplateVars,
+} from './ai-prompt-template.util';
+import type { AiInstructionRecord } from './types/ai-instruction.types';
+
+export type PromptSource =
+  /** Stored content was used. */
+  | 'db'
+  /** No usable row (missing, inactive or empty) — code constant was used. */
+  | 'fallback'
+  /** Stored content was rejected (guard phrases gone or template broken). */
+  | 'fallback-guard'
+  /** Database read failed — code constant was used. */
+  | 'fallback-error';
+
+export type ResolvedPrompt = {
+  slug: string;
+  /** Already interpolated and ready to send. */
+  content: string;
+  source: PromptSource;
+  /** Only populated when `source === 'db'`; otherwise the caller keeps its own default. */
+  model: string | null;
+  temperature: number | null;
+  maxTokens: number | null;
+};
+
+export type ResolvePromptInput = {
+  slug: string;
+  /** Overrides the registry fallback. Rarely needed — the registry is the source of truth. */
+  fallback?: string;
+  variables?: TemplateVars;
+};
+
+export type ModelParams = Pick<ResolvedPrompt, 'model' | 'temperature' | 'maxTokens'>;
+
+const WARN_INTERVAL_MS = 5 * 60 * 1000;
+
+const EMPTY_PARAMS: ModelParams = { model: null, temperature: null, maxTokens: null };
+
+/**
+ * Resolves task prompts from `ai_instruction`, falling back to the constant
+ * declared in code.
+ *
+ * `resolve()` never throws: a misconfigured or missing prompt must degrade to
+ * the shipped behaviour, not break the AI flow that depends on it.
+ */
+@Injectable()
+export class AiPromptResolverService {
+  private readonly logger = new Logger(AiPromptResolverService.name);
+  /** Last warning timestamp per `slug|reason`, to keep hot paths out of the log. */
+  private readonly lastWarnedAt = new Map<string, number>();
+
+  constructor(
+    @Inject(forwardRef(() => AiInstructionService))
+    private readonly instructionService: AiInstructionService,
+  ) {}
+
+  async resolve(input: ResolvePromptInput): Promise<ResolvedPrompt> {
+    let record: AiInstructionRecord | null = null;
+    let readFailed = false;
+
+    try {
+      record = await this.instructionService.getRecordBySlug(input.slug);
+    } catch (error) {
+      readFailed = true;
+      this.warnOnce(input.slug, 'error', `Failed to read AI prompt: ${error}`);
+    }
+
+    return this.build(input, record, readFailed);
+  }
+
+  /**
+   * One database round-trip for pipelines that need several prompts. The essay
+   * grading flow resolves six per correction.
+   */
+  async resolveMany(inputs: ResolvePromptInput[]): Promise<Record<string, ResolvedPrompt>> {
+    let records = new Map<string, AiInstructionRecord | null>();
+    let readFailed = false;
+
+    try {
+      records = await this.instructionService.getRecordsBySlugs(inputs.map((i) => i.slug));
+    } catch (error) {
+      readFailed = true;
+      this.warnOnce(inputs.map((i) => i.slug).join(','), 'error', `Failed to read AI prompts: ${error}`);
+    }
+
+    const result: Record<string, ResolvedPrompt> = {};
+    for (const input of inputs) {
+      result[input.slug] = this.build(input, records.get(input.slug) || null, readFailed);
+    }
+    return result;
+  }
+
+  private build(
+    input: ResolvePromptInput,
+    record: AiInstructionRecord | null,
+    readFailed: boolean,
+  ): ResolvedPrompt {
+    const definition = getAiPromptDefinition(input.slug);
+    const fallback = input.fallback ?? definition?.fallback ?? '';
+    const variables = input.variables || {};
+
+    const { template, source } = this.pickTemplate(input.slug, record, readFailed, fallback);
+
+    try {
+      return {
+        slug: input.slug,
+        content: renderTemplate(template, variables),
+        source,
+        ...(source === 'db' ? this.modelParamsOf(record) : EMPTY_PARAMS),
+      };
+    } catch (error) {
+      // Only a stored template can be malformed — the code constants are covered
+      // by tests. Render the fallback instead of sending half a prompt.
+      const reason = error instanceof PromptTemplateError ? error.message : String(error);
+      this.logger.error(
+        `Stored AI prompt "${input.slug}" is malformed (${reason}); using code fallback.`,
+      );
+
+      return {
+        slug: input.slug,
+        content: renderTemplate(fallback, variables),
+        source: 'fallback-guard',
+        ...EMPTY_PARAMS,
+      };
+    }
+  }
+
+  private pickTemplate(
+    slug: string,
+    record: AiInstructionRecord | null,
+    readFailed: boolean,
+    fallback: string,
+  ): { template: string; source: PromptSource } {
+    if (readFailed) return { template: fallback, source: 'fallback-error' };
+
+    if (!record) {
+      this.warnOnce(slug, 'missing', `AI prompt "${slug}" has no row; using code fallback.`);
+      return { template: fallback, source: 'fallback' };
+    }
+    if (!record.is_active) {
+      this.warnOnce(slug, 'inactive', `AI prompt "${slug}" is inactive; using code fallback.`);
+      return { template: fallback, source: 'fallback' };
+    }
+    if (!record.content?.trim()) {
+      this.warnOnce(slug, 'empty', `AI prompt "${slug}" is empty; using code fallback.`);
+      return { template: fallback, source: 'fallback' };
+    }
+
+    const requiredPhrases = getAiPromptDefinition(slug)?.requiredPhrases;
+    if (requiredPhrases?.length) {
+      const hasAny = requiredPhrases.some((phrase) => record.content.includes(phrase));
+      if (!hasAny) {
+        // Not rate-limited: a security-sensitive prompt losing every guard
+        // phrase should be loud on every single call.
+        this.logger.error(
+          `AI prompt "${slug}" lost all of its required safety phrases ` +
+            `(${requiredPhrases.join(' | ')}); using code fallback.`,
+        );
+        return { template: fallback, source: 'fallback-guard' };
+      }
+    }
+
+    return { template: record.content, source: 'db' };
+  }
+
+  private modelParamsOf(record: AiInstructionRecord | null): ModelParams {
+    if (!record) return EMPTY_PARAMS;
+    return {
+      model: record.model ?? null,
+      temperature: record.temperature ?? null,
+      maxTokens: record.max_tokens ?? null,
+    };
+  }
+
+  /**
+   * Without rate limiting, a single missing slug floods the log — task prompts
+   * are resolved on every LLM call.
+   */
+  private warnOnce(slug: string, reason: string, message: string) {
+    const key = `${slug}|${reason}`;
+    const now = Date.now();
+    const last = this.lastWarnedAt.get(key);
+
+    if (last && now - last < WARN_INTERVAL_MS) {
+      this.logger.debug(message);
+      return;
+    }
+
+    this.lastWarnedAt.set(key, now);
+    this.logger.warn(message);
+  }
+}
+
+/**
+ * Precedence, implemented here only: explicit argument > `ai_instruction` row >
+ * integration profile / code default.
+ *
+ * When a flow has a system and a user prompt, the system prompt's params win —
+ * it is the one that represents the call.
+ */
+export function mergeModelParams(...resolved: Array<ResolvedPrompt | null | undefined>): ModelParams {
+  const merged: ModelParams = { ...EMPTY_PARAMS };
+
+  for (const prompt of resolved) {
+    if (!prompt) continue;
+    if (merged.model === null && prompt.model !== null) merged.model = prompt.model;
+    if (merged.temperature === null && prompt.temperature !== null) {
+      merged.temperature = prompt.temperature;
+    }
+    if (merged.maxTokens === null && prompt.maxTokens !== null) merged.maxTokens = prompt.maxTokens;
+  }
+
+  return merged;
+}
+
+export type OpenAiParamDefaults = {
+  model: string;
+  temperature?: number;
+  maxTokens?: number;
+  jsonObject?: boolean;
+};
+
+/**
+ * Applies model params to an OpenAI chat completions body.
+ *
+ * Keys are only written when there is a value, because the current bodies must
+ * stay byte-identical when nothing is configured — some newer models reject
+ * `temperature` and `max_tokens` outright.
+ */
+export function applyOpenAiModelParams(
+  body: Record<string, unknown>,
+  params: ModelParams,
+  defaults: OpenAiParamDefaults,
+): Record<string, unknown> {
+  const model = params.model || defaults.model;
+  const temperature = params.temperature ?? defaults.temperature;
+  const maxTokens = params.maxTokens ?? defaults.maxTokens;
+
+  const result: Record<string, unknown> = { model, ...body };
+
+  if (temperature != null) result.temperature = temperature;
+  if (maxTokens != null) {
+    // Reasoning models and the gpt-5 family renamed this parameter.
+    const key = /^(o\d|gpt-5)/.test(model) ? 'max_completion_tokens' : 'max_tokens';
+    result[key] = maxTokens;
+  }
+  if (defaults.jsonObject) result.response_format = { type: 'json_object' };
+
+  return result;
+}
+
+export function applyGeminiModelParams(
+  payload: Record<string, unknown>,
+  params: ModelParams,
+  defaults: { temperature?: number; maxTokens?: number; jsonObject?: boolean },
+): Record<string, unknown> {
+  const temperature = params.temperature ?? defaults.temperature;
+  const maxTokens = params.maxTokens ?? defaults.maxTokens;
+
+  const generationConfig: Record<string, unknown> = {
+    ...((payload.generationConfig as Record<string, unknown>) || {}),
+  };
+
+  if (temperature != null) generationConfig.temperature = temperature;
+  if (maxTokens != null) generationConfig.maxOutputTokens = maxTokens;
+  if (defaults.jsonObject) generationConfig.responseMimeType = 'application/json';
+
+  if (!Object.keys(generationConfig).length) return payload;
+  return { ...payload, generationConfig };
+}
+
+export function applyClaudeModelParams(
+  body: Record<string, unknown>,
+  params: ModelParams,
+  defaults: { model: string; temperature?: number; maxTokens: number },
+): Record<string, unknown> {
+  const temperature = params.temperature ?? defaults.temperature;
+
+  const result: Record<string, unknown> = {
+    model: params.model || defaults.model,
+    // Anthropic requires max_tokens, so there is always a value here.
+    max_tokens: params.maxTokens ?? defaults.maxTokens,
+    ...body,
+  };
+
+  if (temperature != null) result.temperature = temperature;
+
+  return result;
+}

package/src/ai-instruction/ai-prompt-template.util.spec.ts

@@ -0,0 +1,162 @@
+import {
+  PromptTemplateError,
+  estimateTokens,
+  extractPlaceholders,
+  renderTemplate,
+  validateTemplate,
+} from './ai-prompt-template.util';
+
+describe('renderTemplate', () => {
+  it('substitui {{var}} pelo valor', () => {
+    expect(renderTemplate('Olá {{nome}}!', { nome: 'Ana' })).toBe('Olá Ana!');
+  });
+
+  it('mantém o placeholder literal quando a variável não foi informada', () => {
+    // Apagar o texto silenciosamente é pior que deixar o placeholder visível.
+    expect(renderTemplate('Olá {{nome}}!', {})).toBe('Olá {{nome}}!');
+  });
+
+  it('trata null e undefined como string vazia quando a chave existe', () => {
+    expect(renderTemplate('[{{a}}][{{b}}]', { a: null, b: undefined })).toBe('[][{{b}}]');
+  });
+
+  it('converte números e booleanos', () => {
+    expect(renderTemplate('{{n}} / {{b}}', { n: 42, b: true })).toBe('42 / true');
+  });
+
+  it('renderiza bloco {{#var}} quando a variável é truthy', () => {
+    expect(renderTemplate('a{{#x}}SIM{{/x}}b', { x: true })).toBe('aSIMb');
+    expect(renderTemplate('a{{#x}}SIM{{/x}}b', { x: false })).toBe('ab');
+  });
+
+  it('renderiza bloco {{^var}} quando a variável é falsy', () => {
+    expect(renderTemplate('a{{^x}}NAO{{/x}}b', { x: false })).toBe('aNAOb');
+    expect(renderTemplate('a{{^x}}NAO{{/x}}b', { x: true })).toBe('ab');
+  });
+
+  it('trata as strings "false" e "0" como falsy', () => {
+    // Valores vindos de query string / form chegam como string.
+    expect(renderTemplate('{{#x}}SIM{{/x}}', { x: 'false' })).toBe('');
+    expect(renderTemplate('{{#x}}SIM{{/x}}', { x: '0' })).toBe('');
+    expect(renderTemplate('{{#x}}SIM{{/x}}', { x: '   ' })).toBe('');
+    expect(renderTemplate('{{#x}}SIM{{/x}}', { x: 0 })).toBe('');
+  });
+
+  it('substitui variáveis dentro de um bloco mantido', () => {
+    expect(renderTemplate('{{#tem}}Tom: {{tom}}{{/tem}}', { tem: true, tom: 'formal' })).toBe(
+      'Tom: formal',
+    );
+  });
+
+  it('não substitui variáveis dentro de um bloco descartado', () => {
+    expect(renderTemplate('{{#tem}}Tom: {{tom}}{{/tem}}fim', { tem: false, tom: 'formal' })).toBe(
+      'fim',
+    );
+  });
+
+  it('resolve blocos irmãos independentes', () => {
+    const template = '{{#a}}A{{/a}}{{^a}}nao-A{{/a}}|{{#b}}B{{/b}}';
+    expect(renderTemplate(template, { a: true, b: false })).toBe('A|');
+    expect(renderTemplate(template, { a: false, b: true })).toBe('nao-A|B');
+  });
+
+  it('lança quando um bloco não é fechado', () => {
+    // Um {{#x}} sem {{/x}} engoliria o resto do prompt.
+    expect(() => renderTemplate('inicio {{#x}}corpo sem fim', { x: true })).toThrow(
+      PromptTemplateError,
+    );
+  });
+
+  it('preserva chaves de JSON no corpo do prompt', () => {
+    const template = 'Retorne {"isCorrect": boolean, "score": number} para {{aluno}}';
+    expect(renderTemplate(template, { aluno: 'Ana' })).toBe(
+      'Retorne {"isCorrect": boolean, "score": number} para Ana',
+    );
+  });
+
+  it('preserva chaves triplas e chaves soltas', () => {
+    expect(renderTemplate('{{{x}}}', { x: 'v' })).toBe('{v}');
+    expect(renderTemplate('{ nao é placeholder }', {})).toBe('{ nao é placeholder }');
+  });
+
+  it('não interpreta placeholders com hífen ou ponto', () => {
+    expect(renderTemplate('{{a-b}} {{a.b}}', { 'a-b': 'x' })).toBe('{{a-b}} {{a.b}}');
+  });
+});
+
+describe('extractPlaceholders', () => {
+  it('separa substituições de blocos', () => {
+    const result = extractPlaceholders('{{a}} {{#b}}{{c}}{{/b}} {{^d}}{{/d}}');
+    expect(result.substitutions.sort()).toEqual(['a', 'c']);
+    expect(result.blocks.sort()).toEqual(['b', 'd']);
+    expect(result.unbalanced).toEqual([]);
+  });
+
+  it('detecta bloco aberto sem fechamento', () => {
+    expect(extractPlaceholders('{{#a}}texto').unbalanced).toEqual(['a']);
+  });
+
+  it('detecta fechamento sem abertura', () => {
+    expect(extractPlaceholders('texto{{/a}}').unbalanced).toEqual(['a']);
+  });
+
+  it('não duplica nomes repetidos', () => {
+    expect(extractPlaceholders('{{a}} {{a}}').substitutions).toEqual(['a']);
+  });
+});
+
+describe('validateTemplate', () => {
+  const schema = {
+    version: 1 as const,
+    variables: {
+      obrigatoria: { type: 'string' as const, required: true },
+      opcional: { type: 'string' as const },
+      condicional: { type: 'boolean' as const, required: true, conditional: true },
+    },
+  };
+
+  it('aceita um template que usa todas as obrigatórias', () => {
+    const result = validateTemplate('{{obrigatoria}} {{#condicional}}x{{/condicional}}', schema);
+    expect(result.missingRequired).toEqual([]);
+    expect(result.unknownPlaceholders).toEqual([]);
+    expect(result.unbalancedBlocks).toEqual([]);
+  });
+
+  it('reporta obrigatória removida', () => {
+    const result = validateTemplate('{{#condicional}}x{{/condicional}}', schema);
+    expect(result.missingRequired).toEqual(['obrigatoria']);
+  });
+
+  it('aceita a condicional usada apenas como bloco', () => {
+    const result = validateTemplate('{{obrigatoria}}{{^condicional}}y{{/condicional}}', schema);
+    expect(result.missingRequired).toEqual([]);
+  });
+
+  it('reporta placeholder desconhecido', () => {
+    const result = validateTemplate('{{obrigatoria}} {{#condicional}}{{/condicional}} {{typo}}', schema);
+    expect(result.unknownPlaceholders).toEqual(['typo']);
+  });
+
+  it('reporta bloco não balanceado', () => {
+    const result = validateTemplate('{{obrigatoria}} {{#condicional}}sem fim', schema);
+    expect(result.unbalancedBlocks).toEqual(['condicional']);
+  });
+
+  it('não reporta desconhecidos quando não há schema declarado', () => {
+    const result = validateTemplate('{{qualquer}}', null);
+    expect(result.unknownPlaceholders).toEqual([]);
+    expect(result.missingRequired).toEqual([]);
+  });
+
+  it('aceita um mapa de variáveis sem o envelope version/variables', () => {
+    const result = validateTemplate('{{a}}', { a: { type: 'string', required: true } });
+    expect(result.missingRequired).toEqual([]);
+  });
+});
+
+describe('estimateTokens', () => {
+  it('estima aproximadamente 4 caracteres por token', () => {
+    expect(estimateTokens('12345678')).toBe(2);
+    expect(estimateTokens('')).toBe(0);
+  });
+});

package/src/ai-instruction/ai-prompt-template.util.ts

@@ -0,0 +1,199 @@
+/**
+ * Minimal Mustache subset for AI prompt templates.
+ *
+ * Why not plain `{{var}}` replacement: about half of the prompts moved into
+ * `ai_instruction` build sections conditionally in TypeScript (`answers.tom ?
+ * `Tom: ${answers.tom}` : ''`). Without block syntax those prompts could not be
+ * represented faithfully in the database, and migrating them would silently
+ * change what the model receives.
+ *
+ * Supported:
+ *   {{var}}            substitution
+ *   {{#var}}…{{/var}}  render when truthy
+ *   {{^var}}…{{/var}}  render when falsy
+ *
+ * Not supported (deliberately — these are prompts, not a template language):
+ * nested blocks, loops over arrays, partials, filters, dotted paths.
+ */
+
+export type TemplateVars = Record<string, string | number | boolean | null | undefined>;
+
+export type VariableSpec = {
+  type: 'string' | 'number' | 'boolean';
+  required?: boolean;
+  /**
+   * Used only inside `{{#var}}`/`{{^var}}`. The validator will not demand a
+   * plain `{{var}}` occurrence for these.
+   */
+  conditional?: boolean;
+  description?: string;
+  sample?: string;
+};
+
+export type VariablesSchema = {
+  version: 1;
+  variables: Record<string, VariableSpec>;
+};
+
+export type TemplatePlaceholders = {
+  substitutions: string[];
+  blocks: string[];
+  /** Block names opened without a matching close tag, or closed without open. */
+  unbalanced: string[];
+};
+
+export type TemplateValidation = {
+  missingRequired: string[];
+  unknownPlaceholders: string[];
+  unbalancedBlocks: string[];
+};
+
+export class PromptTemplateError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'PromptTemplateError';
+  }
+}
+
+const SUBSTITUTION_RE = /\{\{(\w+)\}\}/g;
+const BLOCK_OPEN_RE = /\{\{([#^])(\w+)\}\}/g;
+const BLOCK_CLOSE_RE = /\{\{\/(\w+)\}\}/g;
+
+/**
+ * A value counts as truthy when it would have produced text in the original
+ * TypeScript ternary. `'false'` and `'0'` are falsy because these values arrive
+ * as strings from query params and form fields.
+ */
+function isTruthy(value: TemplateVars[string]): boolean {
+  if (value === undefined || value === null) return false;
+  if (typeof value === 'boolean') return value;
+  if (typeof value === 'number') return value !== 0;
+
+  const trimmed = value.trim();
+  if (!trimmed) return false;
+  return trimmed !== 'false' && trimmed !== '0';
+}
+
+function stringify(value: TemplateVars[string]): string {
+  if (value === undefined || value === null) return '';
+  return String(value);
+}
+
+/**
+ * Renders blocks first, then substitutions, so `{{#x}}text {{y}}{{/x}}` works.
+ *
+ * Throws `PromptTemplateError` on an unbalanced block: a `{{#x}}` without
+ * `{{/x}}` would silently swallow the rest of the prompt, which is far worse
+ * than failing. The resolver catches this and falls back to the code constant.
+ */
+export function renderTemplate(template: string, vars: TemplateVars = {}): string {
+  const rendered = renderBlocks(template, vars);
+
+  return rendered.replace(SUBSTITUTION_RE, (match, key: string) => {
+    const value = vars[key];
+    // Keep the placeholder literal when the variable was never provided, so a
+    // typo shows up in the output instead of deleting text silently.
+    return value === undefined ? match : stringify(value);
+  });
+}
+
+function renderBlocks(template: string, vars: TemplateVars): string {
+  let result = '';
+  let cursor = 0;
+
+  const openRe = new RegExp(BLOCK_OPEN_RE.source, 'g');
+  let open: RegExpExecArray | null;
+
+  while ((open = openRe.exec(template)) !== null) {
+    const [openTag, kind, name] = open;
+    const bodyStart = open.index + openTag.length;
+    const closeTag = `{{/${name}}}`;
+    const closeIndex = template.indexOf(closeTag, bodyStart);
+
+    if (closeIndex === -1) {
+      throw new PromptTemplateError(`Unclosed template block "{{${kind}${name}}}".`);
+    }
+
+    result += template.slice(cursor, open.index);
+
+    const body = template.slice(bodyStart, closeIndex);
+    const keep = kind === '#' ? isTruthy(vars[name]) : !isTruthy(vars[name]);
+    if (keep) result += body;
+
+    cursor = closeIndex + closeTag.length;
+    openRe.lastIndex = cursor;
+  }
+
+  return result + template.slice(cursor);
+}
+
+/**
+ * Lists every placeholder in the template. Used by the admin to show which
+ * variables a prompt references and to flag the ones it does not know about.
+ */
+export function extractPlaceholders(template: string): TemplatePlaceholders {
+  const substitutions = new Set<string>();
+  const blocks = new Set<string>();
+  const closes = new Set<string>();
+
+  for (const match of template.matchAll(new RegExp(BLOCK_OPEN_RE.source, 'g'))) {
+    blocks.add(match[2]);
+  }
+  for (const match of template.matchAll(new RegExp(BLOCK_CLOSE_RE.source, 'g'))) {
+    closes.add(match[1]);
+  }
+  for (const match of template.matchAll(new RegExp(SUBSTITUTION_RE.source, 'g'))) {
+    substitutions.add(match[1]);
+  }
+
+  const unbalanced = [
+    ...[...blocks].filter((name) => !closes.has(name)),
+    ...[...closes].filter((name) => !blocks.has(name)),
+  ];
+
+  return {
+    substitutions: [...substitutions],
+    blocks: [...blocks],
+    unbalanced: [...new Set(unbalanced)],
+  };
+}
+
+/**
+ * Checks a draft against its declared variables. The admin runs this locally on
+ * every keystroke and the API runs it again on save.
+ */
+export function validateTemplate(
+  content: string,
+  schema?: VariablesSchema | Record<string, VariableSpec> | null,
+): TemplateValidation {
+  const { substitutions, blocks, unbalanced } = extractPlaceholders(content);
+  const variables = normalizeVariables(schema);
+  const declared = new Set(Object.keys(variables));
+  const used = new Set([...substitutions, ...blocks]);
+
+  const missingRequired = Object.entries(variables)
+    .filter(([name, spec]) => spec.required && !used.has(name))
+    .map(([name]) => name);
+
+  const unknownPlaceholders = declared.size
+    ? [...used].filter((name) => !declared.has(name))
+    : [];
+
+  return { missingRequired, unknownPlaceholders, unbalancedBlocks: unbalanced };
+}
+
+/** Accepts both the `{version, variables}` envelope and a bare variables map. */
+export function normalizeVariables(
+  schema?: VariablesSchema | Record<string, VariableSpec> | null,
+): Record<string, VariableSpec> {
+  if (!schema) return {};
+  if ('variables' in schema && schema.variables && typeof schema.variables === 'object') {
+    return (schema as VariablesSchema).variables;
+  }
+  return schema as Record<string, VariableSpec>;
+}
+
+/** Rough enough to warn that a prompt doubled in size. Not a billing figure. */
+export function estimateTokens(text: string): number {
+  return Math.ceil(text.length / 4);
+}