theorum 0.1.2 → 0.1.4

package/src/cli/index.ts

@@ -0,0 +1,161 @@
+import { listProfilesCommand, showProfileCommand } from './commands/profile.ts';
+import { runCommand } from './commands/run.ts';
+import { testProfileCommand } from './commands/test.ts';
+
+function printHelp(): void {
+  console.log(`
+Theorum CLI - Profile Testing and Profile Inspection
+
+USAGE:
+  theorum <command> [options]
+
+COMMANDS:
+  test                 Run stress matrix or custom profile tests
+    --profile, -p <id> Target profile ID registered by your host app
+    --all, -a          Test all registered profiles
+    --lite             Minimal fast-path connectivity ping
+    --matrix           Run all valid permutations for the profile
+    --mode <fast|smart> Reasoning mode override
+    --search           Optional: set tool id googleSearch when allowlisted
+    --map              Optional: set tool id googleMaps when allowlisted
+
+  run                  Execute a turn with real-time streaming output
+    --profile, -p <id> Target profile ID
+    --prompt <text>    User prompt string
+    --mode <fast|smart> Reasoning mode
+    --search           Optional: set tool id googleSearch when allowlisted
+    --map              Optional: set tool id googleMaps when allowlisted
+
+  profile              Inspect registered profile blueprints
+    list               List all registered profiles
+    show <id>          Show detailed JSON profile specification
+
+  help, --help, -h     Show this help message
+`);
+}
+
+interface ParsedFlags {
+  _: string[];
+  profile?: string;
+  p?: string;
+  prompt?: string;
+  mode?: string;
+  all?: boolean;
+  a?: boolean;
+  lite?: boolean;
+  matrix?: boolean;
+  search?: boolean;
+  map?: boolean;
+  help?: boolean;
+  [key: string]: unknown;
+}
+
+function parseLongFlag(arg: string, nextArg: string | undefined, flags: ParsedFlags): number {
+  const key = arg.slice(2);
+  if (nextArg && !nextArg.startsWith('-')) {
+    flags[key] = nextArg;
+    return 1;
+  }
+  flags[key] = true;
+  return 0;
+}
+
+function parseShortFlag(arg: string, nextArg: string | undefined, flags: ParsedFlags): number {
+  const key = arg.slice(1);
+  if (key === 'p' && nextArg) {
+    flags.profile = nextArg;
+    return 1;
+  }
+  if (key === 'a') flags.all = true;
+  else if (key === 'h') flags.help = true;
+  else flags[key] = true;
+  return 0;
+}
+
+function parseFlags(args: string[]): ParsedFlags {
+  const flags: ParsedFlags = { _: [] };
+  let i = 0;
+  while (i < args.length) {
+    const arg = args[i];
+    const next = args[i + 1];
+    if (arg.startsWith('--')) {
+      i += 1 + parseLongFlag(arg, next, flags);
+    } else if (arg.startsWith('-')) {
+      i += 1 + parseShortFlag(arg, next, flags);
+    } else {
+      flags._.push(arg);
+      i += 1;
+    }
+  }
+  return flags;
+}
+
+function extractProfileId(flags: ParsedFlags): string | undefined {
+  if (typeof flags.profile === 'string') return flags.profile;
+  if (typeof flags.p === 'string') return flags.p;
+  return undefined;
+}
+
+async function handleTest(flags: ParsedFlags): Promise<void> {
+  const profile = extractProfileId(flags);
+  const success = await testProfileCommand(profile, {
+    all: Boolean(flags.all || flags.a),
+    lite: Boolean(flags.lite),
+    matrix: Boolean(flags.matrix),
+    mode: typeof flags.mode === 'string' ? flags.mode : undefined,
+    search: flags.search ? true : undefined,
+    map: flags.map ? true : undefined,
+  });
+  if (!success) {
+    Deno.exit(1);
+  }
+}
+
+async function handleRun(flags: ParsedFlags): Promise<void> {
+  const profile = extractProfileId(flags);
+  if (!profile) {
+    console.error('Error: Profile ID required (e.g. `theorum run --profile your-profile`)');
+    Deno.exit(1);
+  }
+  const prompt = typeof flags.prompt === 'string' ? flags.prompt : flags._.slice(1).join(' ');
+  await runCommand({
+    profile,
+    prompt,
+    mode: typeof flags.mode === 'string' ? flags.mode : undefined,
+    search: Boolean(flags.search),
+    map: Boolean(flags.map),
+  });
+}
+
+function handleProfile(flags: ParsedFlags): void {
+  const sub = flags._[1] || 'list';
+  if (sub === 'list') {
+    listProfilesCommand();
+    return;
+  }
+  const id = sub === 'show' ? flags._[2] || flags.profile : sub;
+  if (typeof id !== 'string' || !id) {
+    console.error('Error: Profile ID required (e.g. `theorum profile show your-profile`)');
+    Deno.exit(1);
+  }
+  showProfileCommand(id);
+}
+
+export async function main(cliArgs = Deno.args): Promise<void> {
+  const flags = parseFlags(cliArgs);
+  const command = flags._[0] || (flags.help ? 'help' : 'help');
+
+  if (command === 'test') {
+    await handleTest(flags);
+  } else if (command === 'run') {
+    await handleRun(flags);
+  } else if (command === 'profile') {
+    handleProfile(flags);
+  } else {
+    printHelp();
+  }
+}
+
+if (import.meta.main) {
+  await main();
+}

package/src/cli/matrix/fixtures.ts

@@ -0,0 +1,96 @@
+/**
+ * Built-in synthetic media fixtures for zero-dependency matrix testing.
+ */
+
+// 1x1 pixel PNG (base64)
+export const FIXTURE_PNG_BASE64 =
+  'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==';
+
+// Minimal valid PDF-1.4 document (base64)
+export const FIXTURE_PDF_BASE64 = btoa(
+  '%PDF-1.4\n1 0 obj<</Type/Catalog/Pages 2 0 R>>endobj\n2 0 obj<</Type/Pages/Count 1/Kids[3 0 R]>>endobj\n3 0 obj<</Type/Page/MediaBox[0 0 612 792]/Parent 2 0 R/Resources<<>>>>endobj\nxref\n0 4\n0000000000 65535 f \n0000000009 00000 n \n0000000056 00000 n \n0000000111 00000 n \ntrailer<</Size 4/Root 1 0 R>>\nstartxref\n188\n%%EOF\n',
+);
+
+// Minimal valid 16kHz 16-bit mono PCM/WAV (0.1s tone) (base64)
+export function createSyntheticWavBase64(durationSec = 0.1, sampleRate = 16000): string {
+  const numSamples = Math.floor(sampleRate * durationSec);
+  const dataSize = numSamples * 2; // 16-bit = 2 bytes per sample
+  const buffer = new ArrayBuffer(44 + dataSize);
+  const view = new DataView(buffer);
+
+  // RIFF identifier
+  view.setUint8(0, 0x52); // R
+  view.setUint8(1, 0x49); // I
+  view.setUint8(2, 0x46); // F
+  view.setUint8(3, 0x46); // F
+  view.setUint32(4, 36 + dataSize, true); // file size - 8
+  view.setUint8(8, 0x57); // W
+  view.setUint8(9, 0x41); // A
+  view.setUint8(10, 0x56); // V
+  view.setUint8(11, 0x45); // E
+
+  // fmt subchunk
+  view.setUint8(12, 0x66); // f
+  view.setUint8(13, 0x6d); // m
+  view.setUint8(14, 0x74); // t
+  view.setUint8(15, 0x20); // ' '
+  view.setUint32(16, 16, true); // Subchunk1Size (16 for PCM)
+  view.setUint16(20, 1, true); // AudioFormat (1 = PCM)
+  view.setUint16(22, 1, true); // NumChannels (1 = Mono)
+  view.setUint32(24, sampleRate, true); // SampleRate
+  view.setUint32(28, sampleRate * 2, true); // ByteRate (SampleRate * NumChannels * BitsPerSample/8)
+  view.setUint16(32, 2, true); // BlockAlign (NumChannels * BitsPerSample/8)
+  view.setUint16(34, 16, true); // BitsPerSample (16 bits)
+
+  // data subchunk
+  view.setUint8(36, 0x64); // d
+  view.setUint8(37, 0x61); // a
+  view.setUint8(38, 0x74); // t
+  view.setUint8(39, 0x61); // a
+  view.setUint32(40, dataSize, true);
+
+  // Write a simple sine wave (440Hz)
+  const freq = 440;
+  for (let i = 0; i < numSamples; i++) {
+    const t = i / sampleRate;
+    const sample = Math.sin(2 * Math.PI * freq * t) * 0.2 * 32767;
+    view.setInt16(44 + i * 2, sample, true);
+  }
+
+  const bytes = new Uint8Array(buffer);
+  let binary = '';
+  for (let i = 0; i < bytes.byteLength; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  return btoa(binary);
+}
+
+export const FIXTURE_WAV_BASE64 = createSyntheticWavBase64(0.1, 16000);
+
+export const FIXTURE_CSV_BASE64 = btoa(
+  'item_id,label,category,score\nitem_1,Alpha,test,0.95\nitem_2,Beta,test,0.88\n',
+);
+
+export const FIXTURE_TEXT_BASE64 = btoa(
+  'This is a synthetic fixture text document for Theorum validation testing.\n',
+);
+
+export function getFixtureForMime(mime: string): { data: string; mimeType: string } | undefined {
+  const m = mime.toLowerCase().trim();
+  if (m.startsWith('image/')) {
+    return { data: FIXTURE_PNG_BASE64, mimeType: 'image/png' };
+  }
+  if (m === 'application/pdf') {
+    return { data: FIXTURE_PDF_BASE64, mimeType: 'application/pdf' };
+  }
+  if (m === 'audio/wav' || m === 'audio/x-wav' || m.startsWith('audio/')) {
+    return { data: FIXTURE_WAV_BASE64, mimeType: 'audio/wav' };
+  }
+  if (m === 'text/csv') {
+    return { data: FIXTURE_CSV_BASE64, mimeType: 'text/csv' };
+  }
+  if (m === 'text/plain') {
+    return { data: FIXTURE_TEXT_BASE64, mimeType: 'text/plain' };
+  }
+  return undefined;
+}

package/src/cli/matrix/synthesizer.ts

@@ -0,0 +1,240 @@
+/**
+ * Stress / matrix turn synthesis for the THEORUM CLI.
+ *
+ * Tool enabling walks the profile allowlist and registered catalog metadata
+ * (`conflictsWith`). Google `--search` / `--map` flags remain as convenience
+ * aliases for `googleSearch` / `googleMaps` when those ids are allowed.
+ *
+ * @module
+ */
+
+import { getTool } from '../../kernel/registry/catalog.ts';
+import type { Profile, ToolId, TurnBlob, TurnRequest } from '../../kernel/types.ts';
+import { FIXTURE_PNG_BASE64, FIXTURE_WAV_BASE64, getFixtureForMime } from './fixtures.ts';
+
+export interface MatrixOptions {
+  lite?: boolean;
+  /** Convenience alias for enabling/disabling `googleSearch` when allowed. */
+  search?: boolean;
+  /** Convenience alias for enabling/disabling `googleMaps` when allowed. */
+  map?: boolean;
+  mode?: string;
+  attachmentPaths?: string[];
+  voicePath?: string;
+}
+
+export function synthesizeLiteCombo(profile: Profile): TurnRequest {
+  const select = profile.model.select?.fast ? 'fast' : undefined;
+  return {
+    profile: profile.id,
+    select,
+    tools: {},
+    input: {
+      text: `Ping test for profile ${profile.id}. Respond concisely with confirmation.`,
+    },
+  };
+}
+
+function resolveStressReasoning(profile: Profile): string | undefined {
+  if (profile.model.select?.smart) {
+    return 'smart';
+  }
+  if (profile.model.select) {
+    const keys = Object.keys(profile.model.select);
+    return keys[keys.length - 1];
+  }
+  return undefined;
+}
+
+function isEnabled(active: Partial<Record<ToolId, boolean>>, id: ToolId): boolean {
+  return active[id] === true;
+}
+
+/** Drop tools whose registered `conflictsWith` siblings are also enabled. */
+function applyRegisteredConflicts(
+  allowed: ToolId[],
+  active: Partial<Record<ToolId, boolean>>,
+): void {
+  for (const id of allowed) {
+    if (!isEnabled(active, id)) {
+      continue;
+    }
+    const conflicts = getTool(id)?.conflictsWith ?? [];
+    if (conflicts.some((other) => isEnabled(active, other))) {
+      active[id] = false;
+    }
+  }
+}
+
+/**
+ * Enable allowlisted tools, optionally forcing one preferred tool and clearing
+ * what it conflicts with (and tools that conflict with it).
+ */
+function resolveStressTools(allowed: ToolId[], prefer?: ToolId): Partial<Record<ToolId, boolean>> {
+  const active: Partial<Record<ToolId, boolean>> = {};
+  for (const t of allowed) {
+    active[t] = true;
+  }
+
+  if (prefer && allowed.includes(prefer)) {
+    active[prefer] = true;
+    for (const c of getTool(prefer)?.conflictsWith ?? []) {
+      if (allowed.includes(c)) {
+        active[c] = false;
+      }
+    }
+    for (const t of allowed) {
+      if (t === prefer) {
+        continue;
+      }
+      const otherConflicts: ToolId[] = getTool(t)?.conflictsWith ?? [];
+      if (otherConflicts.includes(prefer)) {
+        active[t] = false;
+      }
+    }
+  }
+
+  applyRegisteredConflicts(allowed, active);
+  return active;
+}
+
+/** Builtins on the allowlist that declare conflicts (candidates for matrix variants). */
+function conflictingAllowlistedTools(allowed: ToolId[]): ToolId[] {
+  return allowed.filter((id) => {
+    const entry = getTool(id);
+    return entry?.kind === 'builtin' && (entry.conflictsWith?.length ?? 0) > 0;
+  });
+}
+
+function resolveStressAttachments(profile: Profile): TurnBlob[] {
+  const attachments: TurnBlob[] = [];
+  const accept = profile.inputs.attachments?.accept;
+  if (accept && accept.length > 0) {
+    const preferredMimes = ['image/png', 'application/pdf', 'text/plain'];
+    const chosenMime = preferredMimes.find((m) => accept.includes(m)) ?? accept[0];
+    const fixture = getFixtureForMime(chosenMime);
+    if (fixture) {
+      attachments.push(fixture);
+    } else {
+      attachments.push({ mimeType: 'image/png', data: FIXTURE_PNG_BASE64 });
+    }
+  }
+  return attachments;
+}
+
+function resolveStressVoice(profile: Profile): TurnBlob[] {
+  const voice: TurnBlob[] = [];
+  if (profile.inputs.voice?.accept && profile.inputs.voice.accept.length > 0) {
+    voice.push({ mimeType: 'audio/wav', data: FIXTURE_WAV_BASE64 });
+  }
+  return voice;
+}
+
+export function synthesizeStressCombo(
+  profile: Profile,
+  options: { preferTool?: ToolId } = {},
+): TurnRequest {
+  const select = resolveStressReasoning(profile);
+  const activeTools = resolveStressTools(profile.tools.allow ?? [], options.preferTool);
+  const attachments = resolveStressAttachments(profile);
+  const voice = resolveStressVoice(profile);
+  const promptText = `Execute comprehensive test turn for profile ${profile.id}. Validate all instructions and produce required outputs.`;
+
+  return {
+    profile: profile.id,
+    select,
+    tools: activeTools,
+    input: {
+      text: promptText,
+      attachments: attachments.length > 0 ? attachments : undefined,
+      voice: voice.length > 0 ? voice : undefined,
+    },
+  };
+}
+
+export function synthesizeMatrixCombos(
+  profile: Profile,
+): Array<{ name: string; req: TurnRequest }> {
+  const combos: Array<{ name: string; req: TurnRequest }> = [];
+  const allowed = profile.tools.allow ?? [];
+
+  combos.push({
+    name: 'Lite (connectivity)',
+    req: synthesizeLiteCombo(profile),
+  });
+
+  const primary = synthesizeStressCombo(profile);
+  combos.push({
+    name: 'Stress (all modalities + primary tools)',
+    req: primary,
+  });
+
+  // Variants: each allowlisted conflicting builtin that the primary pass dropped.
+  for (const id of conflictingAllowlistedTools(allowed)) {
+    if (primary.tools?.[id] === true) {
+      continue;
+    }
+    const variant = synthesizeStressCombo(profile, { preferTool: id });
+    if (variant.tools?.[id] !== true) {
+      continue;
+    }
+    combos.push({
+      name: `Conflict variant (${id} preferred)`,
+      req: variant,
+    });
+  }
+
+  return combos;
+}
+
+/** Map legacy Google CLI flags onto tool ids when the profile allowlists them. */
+function applyGoogleFlagAliases(
+  active: Partial<Record<ToolId, boolean>>,
+  allowed: ToolId[],
+  options: MatrixOptions,
+): void {
+  if (options.search !== undefined && allowed.includes('googleSearch')) {
+    active.googleSearch = options.search;
+  }
+  if (options.map !== undefined && allowed.includes('googleMaps')) {
+    active.googleMaps = options.map;
+  }
+}
+
+function applyExplicitToolOverrides(
+  base: TurnRequest,
+  profile: Profile,
+  options: MatrixOptions,
+): void {
+  const allowed = profile.tools.allow ?? [];
+  base.tools = base.tools ?? {};
+  applyGoogleFlagAliases(base.tools, allowed, options);
+
+  // If map was explicitly requested on, prefer it against its registered conflicts.
+  if (options.map === true && allowed.includes('googleMaps')) {
+    const preferred = resolveStressTools(allowed, 'googleMaps');
+    for (const id of allowed) {
+      base.tools[id] = preferred[id] === true;
+    }
+    return;
+  }
+
+  applyRegisteredConflicts(allowed, base.tools);
+}
+
+export function buildCustomTurnRequest(profile: Profile, options: MatrixOptions): TurnRequest {
+  if (options.lite) {
+    return synthesizeLiteCombo(profile);
+  }
+
+  const base = synthesizeStressCombo(profile);
+  if (options.mode) {
+    base.select = options.mode;
+  }
+
+  if (options.search !== undefined || options.map !== undefined) {
+    applyExplicitToolOverrides(base, profile, options);
+  }
+
+  return base;
+}

package/src/guardrails/error.ts

@@ -0,0 +1,142 @@
+/**
+ * Public-safe error mapping for THEORUM.
+ *
+ * Kernel internals may contain provider status text, tool names, or exception
+ * details. This module maps those failures to stable user-safe strings.
+ *
+ * @module
+ */
+
+/** Error class used for expected THEORUM contract failures. */
+class TheorumError extends Error {
+  constructor(message = '', options?: ErrorOptions) {
+    super(message, options);
+    this.name = 'TheorumError';
+  }
+}
+
+/** Internal marker for provider or transport failure. */
+const UPSTREAM_FAILED = 'upstream failed';
+/** Generic safe fallback shown when details must not be surfaced. */
+const PUBLIC_GENERIC = 'Something went wrong. Try again.';
+/** Safe copy for transient provider unavailability. */
+const PUBLIC_UNAVAILABLE = 'The model is unavailable. Try again.';
+/** Safe copy for canary or egress disclosure violations. */
+const PUBLIC_CANARY = "That reply wasn't safe to show. Try again.";
+/** Safe copy for tool or permission denials. */
+const PUBLIC_ACTION = "That action isn't available.";
+/** Safe copy for unsupported MIME types. */
+const PUBLIC_FILE_TYPE = "That file type isn't supported.";
+/** Safe copy for oversized files. */
+const PUBLIC_FILE_SIZE = 'That file is too large.';
+/** Safe copy for too many files in one turn. */
+const PUBLIC_FILE_COUNT = 'Too many files for one message.';
+/** Safe copy for unsupported generated image dimensions. */
+const PUBLIC_IMAGE_SIZE = "That image size isn't supported.";
+
+const EXACT: Record<string, string> = {
+  [UPSTREAM_FAILED]: PUBLIC_UNAVAILABLE,
+  'empty Gemini stream': PUBLIC_UNAVAILABLE,
+  'canary leaked': PUBLIC_CANARY,
+  'Turn withheld: egress disclosure violation': PUBLIC_CANARY,
+  'expected JSON object': 'Something was wrong with that request.',
+  'user input cannot be placed in the system block': PUBLIC_GENERIC,
+  'attachment data must be base64': PUBLIC_FILE_TYPE,
+  'attachment is too large': PUBLIC_FILE_SIZE,
+  'attachments exceed the per-turn budget': PUBLIC_FILE_SIZE,
+  'askUser.kind must be confirm, choice, or text': "That question isn't valid.",
+  'askUser.prompt is required': 'That question needs a prompt.',
+  'This profile does not accept text input': PUBLIC_ACTION,
+};
+
+interface ErrorRule {
+  match: (text: string) => boolean;
+  resolve: (text: string) => string;
+}
+
+const RULES: ErrorRule[] = [
+  {
+    match: (t) =>
+      /^(Gemini|OpenRouter|TTS|OpenRouter TTS|Speech) HTTP/.test(t) ||
+      t.includes('TTS HTTP') ||
+      t.includes('Speech HTTP'),
+    resolve: () => PUBLIC_UNAVAILABLE,
+  },
+  {
+    match: (t) =>
+      t.includes('not gated') ||
+      t.includes('not allowed') ||
+      t.includes('has no kernel executor') ||
+      t.includes('Unknown model select') ||
+      t.includes('Grounding tools'),
+    resolve: () => PUBLIC_ACTION,
+  },
+  {
+    match: (t) =>
+      t.includes('MIME') ||
+      t.includes('does not accept attachments') ||
+      t.includes('does not accept voice'),
+    resolve: () => PUBLIC_FILE_TYPE,
+  },
+  {
+    match: (t) => t.startsWith('At most'),
+    resolve: () => PUBLIC_FILE_COUNT,
+  },
+  {
+    match: (t) =>
+      (t.startsWith('Only ') && t.includes('file')) ||
+      t.startsWith('Each file must be') ||
+      t.startsWith('Those files together'),
+    resolve: (t) => t,
+  },
+  {
+    match: (t) => t.includes('attachment'),
+    resolve: () => PUBLIC_FILE_SIZE,
+  },
+  {
+    match: (t) => t.includes('aspect or size'),
+    resolve: () => PUBLIC_IMAGE_SIZE,
+  },
+  {
+    match: (t) => t.includes('must pin thinking') || t.includes('has no models'),
+    resolve: () => PUBLIC_GENERIC,
+  },
+];
+
+function publicText(text: string): string {
+  const exact = EXACT[text];
+  if (exact) {
+    return exact;
+  }
+  for (const rule of RULES) {
+    if (rule.match(text)) {
+      return rule.resolve(text);
+    }
+  }
+  return PUBLIC_GENERIC;
+}
+
+/** Convert an unknown thrown value or internal message to user-safe text. */
+function publicError(err: unknown): string {
+  if (typeof err === 'string') {
+    return publicText(err);
+  }
+  if (err instanceof TheorumError) {
+    return publicText(err.message);
+  }
+  return PUBLIC_UNAVAILABLE;
+}
+
+export {
+  PUBLIC_ACTION,
+  PUBLIC_CANARY,
+  PUBLIC_FILE_COUNT,
+  PUBLIC_FILE_SIZE,
+  PUBLIC_FILE_TYPE,
+  PUBLIC_GENERIC,
+  PUBLIC_IMAGE_SIZE,
+  PUBLIC_UNAVAILABLE,
+  publicError,
+  TheorumError,
+  UPSTREAM_FAILED,
+};