theorum 0.1.2 → 0.1.3

package/esm/mod.js

@@ -11,7 +11,20 @@
  *
  * const profile = defineProfile({
  *   id: "assistant.basic",
- *   model: { allow: ["gemini35FlashLite"] },
+ *   model: {
+ *     allow: ["gemini35FlashLite"],
+ *     config: {
+ *       gemini35FlashLite: {
+ *         apiId: "gemini-3.5-flash-lite",
+ *         thinking: { on: "high", off: "minimal" },
+ *         thinkingLevels: ["minimal", "low", "medium", "high"],
+ *         summaries: { on: "auto", off: "none" },
+ *         maxOutputTokens: 8192,
+ *         temperature: 1,
+ *         keyBuiltins: [],
+ *       },
+ *     },
+ *   },
  *   tools: { allow: [] },
  *   inputs: { text: true },
  *   outputs: {},
@@ -27,9 +40,10 @@ import "./_dnt.polyfills.js";
 export { publicError, TheorumError } from './src/guardrails/error.js';
 export { PROJECT_ID_MAX, sanitizeProjectId, sanitizeText, sanitizeTurnRequest, } from './src/guardrails/sanitize.js';
 export { runTurn } from './src/kernel/engine/runner.js';
-export { defineProfile, getProfile, hasProfile, listProfiles, registerProfile, registerProfiles, } from './src/kernel/registry/profiles.js';
+export { CATALOG, clampThinkingLevel, clampThinkingLevelForApiId, getTool, listBuiltinIds, modelEntryByApiId, registerTools, requireModelSpec, resetTools, } from './src/kernel/registry/catalog.js';
+export { clearProfiles, defineProfile, getProfile, hasProfile, listProfiles, registerProfile, registerProfiles, } from './src/kernel/registry/profiles.js';
 export { projectProfile, resolveTurn } from './src/kernel/registry/resolve.js';
 export { getStructured, registerStructured } from './src/kernel/registry/schemas.js';
 export { executeTool } from './src/kernel/registry/tools.js';
 export { jsonlSink, memorySink, noopSink, resolveTraceDir, sinkFromDir, writeTrace, } from './src/observability/trace.js';
-export { createInteractionsProvider, createOpenRouterProvider, createOpenRouterTtsProvider, resolveOpenRouterApiKey, resolveOpenRouterModel, streamOpenRouterTts, toOpenRouterPayload, wrapPcmAsWav, } from './src/providers/mod.js';
+export { createProvider } from './src/providers/mod.js';

package/esm/src/cli/commands/profile.d.ts

@@ -0,0 +1,2 @@
+export declare function listProfilesCommand(): void;
+export declare function showProfileCommand(profileId: string): void;

package/esm/src/cli/commands/profile.js

@@ -0,0 +1,53 @@
+import { getProfile, listProfiles } from '../../kernel/registry/profiles.js';
+function formatProfileInputs(p) {
+    const inputs = [];
+    if (p.inputs.text !== false)
+        inputs.push('text');
+    if (p.inputs.voice)
+        inputs.push('voice');
+    if (p.inputs.attachments)
+        inputs.push(`attachments [${p.inputs.attachments.accept?.join(', ')}]`);
+    return inputs.join(' | ');
+}
+function printProfileCard(p) {
+    const tools = p.tools.allow?.length ? p.tools.allow.join(', ') : 'none';
+    const models = p.model.allow?.join(', ') || 'default';
+    const structured = typeof p.outputs.structured === 'string'
+        ? p.outputs.structured
+        : p.outputs.structured
+            ? 'custom'
+            : 'none';
+    console.log(` • Profile: ${p.id.padEnd(16)} (handle: ${p.identity.handle})`);
+    console.log(`   - Models:     ${models}`);
+    console.log(`   - Inputs:     ${formatProfileInputs(p)}`);
+    console.log(`   - Tools:      ${tools}`);
+    console.log(`   - Structured: ${structured}`);
+    console.log(`   - Key Bucket: ${p.model.key ?? 'freeA'}`);
+    console.log('-'.repeat(70));
+}
+export function listProfilesCommand() {
+    const profiles = listProfiles();
+    console.log('\n Registered Theorum Profiles:');
+    console.log('='.repeat(70));
+    if (profiles.length === 0) {
+        console.log('  (No profiles registered in runtime)');
+        console.log(`${'='.repeat(70)}\n`);
+        return;
+    }
+    for (const p of profiles) {
+        printProfileCard(p);
+    }
+    console.log(`Total: ${profiles.length} profiles registered.\n`);
+}
+export function showProfileCommand(profileId) {
+    try {
+        const profile = getProfile(profileId);
+        console.log(`\n Profile Details: ${profileId}`);
+        console.log('='.repeat(70));
+        console.log(JSON.stringify(profile, null, 2));
+        console.log(`${'='.repeat(70)}\n`);
+    }
+    catch (err) {
+        console.error(`\n Error: ${err instanceof Error ? err.message : String(err)}\n`);
+    }
+}

package/esm/src/cli/commands/run.d.ts

@@ -0,0 +1,10 @@
+import type { ModelProvider } from '../../kernel/types.js';
+export interface RunOptions {
+    profile: string;
+    prompt?: string;
+    mode?: string;
+    search?: boolean;
+    map?: boolean;
+    provider?: ModelProvider;
+}
+export declare function runCommand(options: RunOptions): Promise<void>;

package/esm/src/cli/commands/run.js

@@ -0,0 +1,55 @@
+import * as dntShim from "../../../_dnt.shims.js";
+import { runTurn } from '../../kernel/engine/runner.js';
+import { getProfile } from '../../kernel/registry/profiles.js';
+function handleRunEvent(event) {
+    if (event.type === 'thought' && event.text) {
+        dntShim.Deno.stdout.write(new TextEncoder().encode(`\x1b[2m${event.text}\x1b[0m`));
+    }
+    else if (event.type === 'text' && event.text) {
+        dntShim.Deno.stdout.write(new TextEncoder().encode(event.text));
+    }
+    else if (event.type === 'tool' && event.tool) {
+        console.log(`\n\x1b[33m⚡ [Tool Call] ${event.tool.name}\x1b[0m:`, event.tool.arguments);
+    }
+    else if (event.type === 'structured' && event.structured) {
+        console.log('\n\x1b[32m✓ [Structured Output]\x1b[0m:');
+        console.log(JSON.stringify(event.structured, null, 2));
+    }
+    else if (event.type === 'media' && event.media) {
+        console.log(`\n\x1b[34m🖼 [Media Output]\x1b[0m (${event.media.mimeType})`);
+    }
+    else if (event.type === 'error' && event.error) {
+        console.error(`\n\x1b[31m✗ Error\x1b[0m: ${event.error}`);
+    }
+}
+export async function runCommand(options) {
+    getProfile(options.profile);
+    const provider = options.provider;
+    if (!provider) {
+        console.error('\n\x1b[31mExecution Failed\x1b[0m: Theorum CLI does not create providers or read keys. Run turns from a host app with an explicit ModelProvider.\n');
+        return;
+    }
+    const prompt = options.prompt || 'Hello! Please introduce your capabilities.';
+    const tools = {};
+    if (options.search)
+        tools.googleSearch = true;
+    if (options.map)
+        tools.googleMaps = true;
+    const req = {
+        profile: options.profile,
+        select: options.mode,
+        tools: Object.keys(tools).length > 0 ? tools : undefined,
+        input: { text: prompt },
+    };
+    console.log(`\n▶ [RUNNING TURN] Profile: ${options.profile} (${options.mode ?? 'default'})`);
+    console.log(`Prompt: "${prompt}"\n`);
+    try {
+        for await (const event of runTurn(req, provider)) {
+            handleRunEvent(event);
+        }
+        console.log('\n');
+    }
+    catch (err) {
+        console.error(`\n\x1b[31mExecution Failed\x1b[0m: ${err instanceof Error ? err.message : String(err)}\n`);
+    }
+}

package/esm/src/cli/commands/test.d.ts

@@ -0,0 +1,15 @@
+import type { ModelProvider, TurnRequest } from '../../kernel/types.js';
+import { type MatrixOptions } from '../matrix/synthesizer.js';
+export interface TestRunResult {
+    passed: boolean;
+    name: string;
+    durationSec: number;
+    tokensTotal?: number;
+    error?: string;
+}
+export declare function executeSingleTest(req: TurnRequest, testName: string, provider?: ModelProvider): Promise<TestRunResult>;
+export declare function testProfileCommand(profileId?: string, options?: MatrixOptions & {
+    all?: boolean;
+    matrix?: boolean;
+    provider?: ModelProvider;
+}): Promise<boolean>;

package/esm/src/cli/commands/test.js

@@ -0,0 +1,140 @@
+import * as dntShim from "../../../_dnt.shims.js";
+import { runTurn } from '../../kernel/engine/runner.js';
+import { getProfile, listProfiles } from '../../kernel/registry/profiles.js';
+import { buildCustomTurnRequest, synthesizeMatrixCombos, } from '../matrix/synthesizer.js';
+function printTestHeader(req, testName) {
+    const activeTools = Object.entries(req.tools ?? {})
+        .filter(([, v]) => Boolean(v))
+        .map(([k]) => k)
+        .join(', ');
+    console.log(`\n▶ [THEORUM TEST] ${testName}`);
+    console.log(`  Profile:     ${req.profile} (Mode: ${req.select ?? 'default'})`);
+    console.log(`  Tools:       ${activeTools || 'none'}`);
+    console.log(`  Attachments: ${req.input?.attachments?.length ?? 0} file(s) | Voice: ${req.input?.voice?.length ? 'yes' : 'no'}`);
+    console.log(`  ${'-'.repeat(60)}`);
+}
+function processTestEvent(event, acc) {
+    if (event.type === 'thought' && event.text) {
+        dntShim.Deno.stdout.write(new TextEncoder().encode('.'));
+    }
+    else if (event.type === 'tool' && event.tool) {
+        console.log(`\n  ⚡ [Tool Dispatched] ${event.tool.name}(${JSON.stringify(event.tool.arguments ?? {})})`);
+    }
+    else if (event.type === 'structured') {
+        console.log(`\n  ✓ [Structured Schema Validated]`);
+    }
+    else if (event.type === 'media') {
+        console.log(`\n  ✓ [Media Generated] (${event.media?.mimeType})`);
+    }
+    else if (event.type === 'tokens' && event.tokens) {
+        acc.totalTokens = event.tokens.total;
+    }
+    else if (event.type === 'error' && event.error) {
+        acc.hasError = true;
+        acc.errorMessage = event.error;
+        console.error(`\n  [Test Error Detail]: ${event.error}`);
+    }
+}
+function printTestResult(passed, durationSec, acc) {
+    if (passed) {
+        console.log(`\n  ✓ STATUS: PASSED (took ${durationSec.toFixed(2)}s, ${acc.totalTokens ? `${acc.totalTokens} tokens` : 'ok'})`);
+    }
+    else {
+        console.log(`\n  ✗ STATUS: FAILED: ${acc.errorMessage} (${durationSec.toFixed(2)}s)`);
+    }
+}
+export async function executeSingleTest(req, testName, provider) {
+    const start = Date.now();
+    getProfile(req.profile);
+    printTestHeader(req, testName);
+    const acc = {
+        totalTokens: 0,
+        hasError: false,
+        errorMessage: '',
+    };
+    try {
+        if (!provider) {
+            throw new Error('Theorum CLI does not create providers or read keys. Pass an explicit ModelProvider from the host app.');
+        }
+        for await (const event of runTurn(req, provider)) {
+            processTestEvent(event, acc);
+        }
+    }
+    catch (err) {
+        acc.hasError = true;
+        acc.errorMessage = err instanceof Error ? err.message : String(err);
+    }
+    const durationSec = (Date.now() - start) / 1000;
+    const passed = !acc.hasError;
+    printTestResult(passed, durationSec, acc);
+    return {
+        passed,
+        name: testName,
+        durationSec,
+        tokensTotal: acc.totalTokens,
+        error: acc.errorMessage,
+    };
+}
+function resolveTargetProfiles(profileId, all) {
+    if (all) {
+        return listProfiles();
+    }
+    if (profileId) {
+        try {
+            return [getProfile(profileId)];
+        }
+        catch (err) {
+            console.error(`\n Error: ${err instanceof Error ? err.message : String(err)}\n`);
+            return null;
+        }
+    }
+    console.error('Error: Please specify a profile ID (e.g. `theorum test --profile your-profile`) or `--all`.');
+    return null;
+}
+async function runProfileMatrix(profile, provider) {
+    const results = [];
+    const combos = synthesizeMatrixCombos(profile);
+    for (const combo of combos) {
+        const res = await executeSingleTest(combo.req, `${profile.id} [${combo.name}]`, provider);
+        results.push(res);
+    }
+    return results;
+}
+async function runProfileSingle(profile, options, provider) {
+    const req = buildCustomTurnRequest(profile, options);
+    const testName = options.lite ? `${profile.id} [Lite]` : `${profile.id} [Stress Combo]`;
+    return await executeSingleTest(req, testName, provider);
+}
+function printSummaryReport(results) {
+    console.log(`\n${'='.repeat(70)}`);
+    console.log(' TEST SUMMARY:');
+    console.log('='.repeat(70));
+    let allPassed = true;
+    for (const r of results) {
+        const status = r.passed ? '✓ PASSED' : '✗ FAILED';
+        console.log(`  ${status.padEnd(10)} ${r.name.padEnd(45)} (${r.durationSec.toFixed(2)}s)`);
+        if (!r.passed) {
+            allPassed = false;
+            if (r.error)
+                console.log(`             Reason: ${r.error}`);
+        }
+    }
+    console.log(`${'='.repeat(70)}\n`);
+    return allPassed;
+}
+export async function testProfileCommand(profileId, options = {}) {
+    const targetProfiles = resolveTargetProfiles(profileId, options.all);
+    if (!targetProfiles || targetProfiles.length === 0) {
+        return false;
+    }
+    const results = [];
+    for (const profile of targetProfiles) {
+        if (options.matrix) {
+            results.push(...(await runProfileMatrix(profile, options.provider)));
+        }
+        else {
+            results.push(await runProfileSingle(profile, options, options.provider));
+        }
+    }
+    return printSummaryReport(results);
+}

package/esm/src/cli/index.d.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import "../../_dnt.polyfills.js";
+import "../../_dnt.polyfills.js";
+export declare function main(cliArgs?: string[]): Promise<void>;

package/esm/src/cli/index.js

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+import "../../_dnt.polyfills.js";
+import "../../_dnt.polyfills.js";
+import * as dntShim from "../../_dnt.shims.js";
+import { listProfilesCommand, showProfileCommand } from './commands/profile.js';
+import { runCommand } from './commands/run.js';
+import { testProfileCommand } from './commands/test.js';
+function printHelp() {
+    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
+`);
+}
+function parseLongFlag(arg, nextArg, flags) {
+    const key = arg.slice(2);
+    if (nextArg && !nextArg.startsWith('-')) {
+        flags[key] = nextArg;
+        return 1;
+    }
+    flags[key] = true;
+    return 0;
+}
+function parseShortFlag(arg, nextArg, flags) {
+    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) {
+    const flags = { _: [] };
+    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) {
+    if (typeof flags.profile === 'string')
+        return flags.profile;
+    if (typeof flags.p === 'string')
+        return flags.p;
+    return undefined;
+}
+async function handleTest(flags) {
+    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) {
+        dntShim.Deno.exit(1);
+    }
+}
+async function handleRun(flags) {
+    const profile = extractProfileId(flags);
+    if (!profile) {
+        console.error('Error: Profile ID required (e.g. `theorum run --profile your-profile`)');
+        dntShim.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) {
+    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`)');
+        dntShim.Deno.exit(1);
+    }
+    showProfileCommand(id);
+}
+export async function main(cliArgs = dntShim.Deno.args) {
+    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 (globalThis[Symbol.for("import-meta-ponyfill-esmodule")](import.meta).main) {
+    await main();
+}

package/esm/src/cli/matrix/fixtures.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Built-in synthetic media fixtures for zero-dependency matrix testing.
+ */
+export declare const FIXTURE_PNG_BASE64 = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==";
+export declare const FIXTURE_PDF_BASE64: string;
+export declare function createSyntheticWavBase64(durationSec?: number, sampleRate?: number): string;
+export declare const FIXTURE_WAV_BASE64: string;
+export declare const FIXTURE_CSV_BASE64: string;
+export declare const FIXTURE_TEXT_BASE64: string;
+export declare function getFixtureForMime(mime: string): {
+    data: string;
+    mimeType: string;
+} | undefined;

package/esm/src/cli/matrix/fixtures.js

@@ -0,0 +1,77 @@
+/**
+ * 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) {
+    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) {
+    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/esm/src/cli/matrix/synthesizer.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 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 type { Profile, ToolId, TurnRequest } from '../../kernel/types.js';
+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 declare function synthesizeLiteCombo(profile: Profile): TurnRequest;
+export declare function synthesizeStressCombo(profile: Profile, options?: {
+    preferTool?: ToolId;
+}): TurnRequest;
+export declare function synthesizeMatrixCombos(profile: Profile): Array<{
+    name: string;
+    req: TurnRequest;
+}>;
+export declare function buildCustomTurnRequest(profile: Profile, options: MatrixOptions): TurnRequest;