@theoremjs/agents 0.0.0-stage → 0.3.1

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

@@ -0,0 +1,143 @@
+import { getProfile, listProfiles, runTurn } from '../../kernel/default-scope.js';
+import { sumTokens } from '../../kernel/engine/usage.js';
+import { isModelProfile, requireModelProfile } from '../../kernel/registry/resolve.js';
+import { profileToolAllow } from '../../kernel/tools/resolve.js';
+import { createCliTraceCapture, printTestEvent, printTraceRecord } from '../event-log.js';
+import { buildCustomTurnRequest, synthesizeMatrixCombos, } from '../matrix/synthesizer.js';
+function printTestHeader(req, testName) {
+    const profile = requireModelProfile(getProfile(req.profile), 'agents test');
+    const modelId = req.model && profile.models[req.model] ? req.model : (Object.keys(profile.models)[0] ?? '');
+    const customs = profileToolAllow(profile).join(', ') || 'none';
+    const builtins = (profile.models[modelId]?.builtInTools ?? []).join(', ') || 'none';
+    console.log(`\n▶ [THEOREM TEST] ${testName}`);
+    console.log(`  Profile:     ${req.profile} (Model: ${req.model ?? 'default'})`);
+    console.log(`  Custom:      ${customs}`);
+    console.log(`  Builtins:    ${builtins}`);
+    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, options) {
+    if (event.type === 'tokens' && event.tokens) {
+        acc.calls.push(event.tokens);
+    }
+    if (event.type === 'error' && event.error) {
+        acc.hasError = true;
+        acc.errorMessage = event.error;
+    }
+    printTestEvent(event, { verbose: options.verbose });
+}
+function printTestResult(passed, durationSec, tokens, errorMessage) {
+    if (passed) {
+        const estimates = tokens?.estimated ? ', includes estimates' : '';
+        console.log(`\n  ✓ STATUS: PASSED (took ${durationSec.toFixed(2)}s, ${tokens?.total ? `${tokens.total} tokens${estimates}` : 'ok'})`);
+    }
+    else {
+        console.log(`\n  ✗ STATUS: FAILED: ${errorMessage} (${durationSec.toFixed(2)}s)`);
+    }
+}
+export async function executeSingleTest(req, testName, provider, cliOptions = {}) {
+    const start = Date.now();
+    getProfile(req.profile);
+    printTestHeader(req, testName);
+    const acc = {
+        calls: [],
+        hasError: false,
+        errorMessage: '',
+    };
+    try {
+        if (!provider) {
+            throw new Error('Theorem CLI does not create providers or read keys. Pass an explicit ProviderHostOptions from the host app.');
+        }
+        const traceCapture = cliOptions.trace ? createCliTraceCapture(cliOptions.traceDir) : undefined;
+        for await (const event of runTurn(req, provider, traceCapture?.sink)) {
+            processTestEvent(event, acc, cliOptions);
+        }
+        if (cliOptions.trace) {
+            printTraceRecord(traceCapture?.records.at(-1), cliOptions.verbose === true);
+        }
+    }
+    catch (err) {
+        acc.hasError = true;
+        acc.errorMessage = err instanceof Error ? err.message : String(err);
+    }
+    const durationSec = (Date.now() - start) / 1000;
+    const passed = !acc.hasError;
+    const tokens = sumTokens(acc.calls);
+    printTestResult(passed, durationSec, tokens, acc.errorMessage);
+    return {
+        passed,
+        name: testName,
+        durationSec,
+        ...(tokens ? { tokens } : {}),
+        error: acc.errorMessage,
+    };
+}
+function resolveTargetProfiles(profileId, all) {
+    if (all) {
+        // why: Host and decision profiles run no model turn, so they have no turn matrix.
+        return listProfiles().filter(isModelProfile);
+    }
+    if (profileId) {
+        try {
+            return [requireModelProfile(getProfile(profileId), 'agents test')];
+        }
+        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. `agents test --profile your-profile`) or `--all`.');
+    return null;
+}
+async function runProfileMatrix(profile, provider, cliOptions = {}) {
+    const results = [];
+    const combos = synthesizeMatrixCombos(profile);
+    for (const combo of combos) {
+        const res = await executeSingleTest(combo.req, `${profile.id} [${combo.name}]`, provider, cliOptions);
+        results.push(res);
+    }
+    return results;
+}
+async function runProfileSingle(profile, options, provider, cliOptions = {}) {
+    const req = buildCustomTurnRequest(profile, options);
+    const testName = options.lite ? `${profile.id} [Lite]` : `${profile.id} [Stress Combo]`;
+    return await executeSingleTest(req, testName, provider, cliOptions);
+}
+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 cliOptions = {
+        verbose: options.verbose,
+        trace: options.trace,
+        traceDir: options.traceDir,
+    };
+    const results = [];
+    for (const profile of targetProfiles) {
+        if (options.matrix) {
+            results.push(...(await runProfileMatrix(profile, options.provider, cliOptions)));
+        }
+        else {
+            results.push(await runProfileSingle(profile, options, options.provider, cliOptions));
+        }
+    }
+    return printSummaryReport(results);
+}

package/esm/src/cli/event-log.d.ts

@@ -0,0 +1,15 @@
+import type { TurnEvent } from '../kernel/turn-events.js';
+import { type TraceRecord } from '../observability/trace-record.js';
+import type { TraceSink } from '../observability/trace-sink.js';
+export interface CliEventLogOptions {
+    verbose?: boolean;
+}
+export interface CliTraceCapture {
+    sink: TraceSink;
+    records: TraceRecord[];
+}
+declare function createCliTraceCapture(traceDir?: string): CliTraceCapture;
+declare function printRunEvent(event: TurnEvent, options?: CliEventLogOptions): void;
+declare function printTestEvent(event: TurnEvent, options?: CliEventLogOptions): void;
+declare function printTraceRecord(record: TraceRecord | undefined, verbose: boolean): void;
+export { createCliTraceCapture, printRunEvent, printTestEvent, printTraceRecord };

package/esm/src/cli/event-log.js

@@ -0,0 +1,136 @@
+import { stdout } from 'node:process';
+import { jsonlSink } from '../observability/jsonl.js';
+import { memorySink } from '../observability/trace.js';
+import { inlineContent } from '../observability/trace-record.js';
+function createCliTraceCapture(traceDir) {
+    const records = [];
+    const sinks = [memorySink(records)];
+    if (traceDir?.trim()) {
+        sinks.push(jsonlSink(traceDir.trim()));
+    }
+    return {
+        records,
+        sink: {
+            write: async (record, context) => {
+                for (const sink of sinks) {
+                    await sink.write(record, context);
+                }
+            },
+        },
+    };
+}
+function printVerboseEvidence(event) {
+    const e = event.evidence;
+    if (e.raw) {
+        console.log('\n\x1b[2m[verbose evidence.raw]\x1b[0m');
+        console.log(JSON.stringify(e.raw, null, 2));
+    }
+}
+function printVerboseError(event) {
+    if (event.type !== 'error' || !event.errorInternal) {
+        return;
+    }
+    console.error(`\n\x1b[2m[verbose errorInternal]\x1b[0m ${event.errorInternal}`);
+}
+function printRunEvidence(event, verbose) {
+    const e = event.evidence;
+    if (e.kind === 'code_execution_call') {
+        console.log(`\n\x1b[36m🐍 [code_execution_call]\x1b[0m\n${e.code}`);
+    }
+    else if (e.kind === 'code_execution_result') {
+        console.log(`\n\x1b[36m🐍 [code_execution_result]\x1b[0m isError=${String(e.isError)}\n${e.result ?? ''}`);
+    }
+    else {
+        console.log(`\n\x1b[36m📎 [evidence]\x1b[0m ${e.kind}`);
+    }
+    if (verbose) {
+        printVerboseEvidence(event);
+    }
+}
+function printRunEvent(event, options = {}) {
+    const verbose = options.verbose === true;
+    if (event.type === 'thought' && event.text) {
+        stdout.write(`\x1b[2m${event.text}\x1b[0m`);
+    }
+    else if (event.type === 'text' && event.text) {
+        stdout.write(event.text);
+    }
+    else if (event.type === 'tool' && event.tool.phase === undefined) {
+        stdout.write(`\n\x1b[33m⚡ [Tool Call] ${event.tool.name}\x1b[0m: `);
+        console.log(event.tool.arguments);
+    }
+    else if (event.type === 'evidence') {
+        printRunEvidence(event, verbose);
+    }
+    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}`);
+        if (verbose) {
+            printVerboseError(event);
+        }
+    }
+}
+function printTestEvidence(event, verbose) {
+    const e = event.evidence;
+    if (e.kind === 'code_execution_call') {
+        const preview = e.code.replaceAll('\n', ' ').slice(0, 80);
+        console.log(`\n  🐍 [code_execution_call] ${preview || e.id}`);
+    }
+    else if (e.kind === 'code_execution_result') {
+        const preview = (e.result ?? '').replaceAll('\n', ' ').slice(0, 80);
+        console.log(`\n  🐍 [code_execution_result] isError=${String(e.isError)} ${preview}`);
+    }
+    else {
+        console.log(`\n  📎 [evidence] ${e.kind}`);
+    }
+    if (verbose) {
+        printVerboseEvidence(event);
+    }
+}
+function printTestEvent(event, options = {}) {
+    const verbose = options.verbose === true;
+    if (event.type === 'thought' && event.text) {
+        stdout.write('.');
+    }
+    else if (event.type === 'tool' && event.tool.phase === undefined) {
+        console.log(`\n  ⚡ [Tool Dispatched] ${event.tool.name}(${JSON.stringify(event.tool.arguments)})`);
+    }
+    else if (event.type === 'evidence') {
+        printTestEvidence(event, verbose);
+    }
+    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 === 'error' && event.error) {
+        console.error(`\n  [Test Error Detail]: ${event.error}`);
+        if (verbose) {
+            printVerboseError(event);
+        }
+    }
+}
+function upstreamRows(record) {
+    return record.spans.flatMap((span) => span.events.flatMap((event) => event.name === 'theorem.upstream.row' ? [inlineContent(record, event.attributes.row)] : []));
+}
+function printTraceRecord(record, verbose) {
+    if (!record) {
+        console.error('\n\x1b[33m[trace]\x1b[0m No trace record captured for this turn.');
+        return;
+    }
+    console.log('\n\x1b[35m════ TRACE RECORD ════\x1b[0m');
+    console.log(JSON.stringify(record, null, 2));
+    const rows = verbose ? upstreamRows(record) : [];
+    if (rows.length > 0) {
+        console.log('\n\x1b[35m════ UPSTREAM LOG ════\x1b[0m');
+        console.log(JSON.stringify(rows, null, 2));
+    }
+}
+export { createCliTraceCapture, printRunEvent, printTestEvent, printTraceRecord };

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

@@ -0,0 +1,10 @@
+/**
+ * Command-line entrypoint for inspecting registered profiles, running turns, and
+ * exercising the kernel's guardrail and performance tools. It reads profiles
+ * registered by the embedding host; it does not supply application profiles.
+ *
+ * @module
+ */
+import "../../_dnt.polyfills.js";
+/** Unknown or omitted commands print help; a command that cannot continue exits 1. */
+export declare function main(cliArgs?: string[]): Promise<void>;

package/esm/src/cli/index.js

@@ -0,0 +1,267 @@
+/**
+ * Command-line entrypoint for inspecting registered profiles, running turns, and
+ * exercising the kernel's guardrail and performance tools. It reads profiles
+ * registered by the embedding host; it does not supply application profiles.
+ *
+ * @module
+ */
+import "../../_dnt.polyfills.js";
+import { argv, exit } from 'node:process';
+import { benchCommand } from './commands/bench.js';
+import { detectCompileCommand } from './commands/detect-compile.js';
+import { evalCommand } from './commands/eval.js';
+import { fuzzCanaryCommand } from './commands/fuzz-canary.js';
+import { fuzzGuardrailsCommand } from './commands/fuzz-guardrails.js';
+import { listProfilesCommand, showProfileCommand } from './commands/profile.js';
+import { runCommand } from './commands/run.js';
+import { testProfileCommand } from './commands/test.js';
+function printHelp() {
+    console.log(`
+Theorem CLI - Profile Testing and Profile Inspection
+
+USAGE:
+  agents <command> [options]
+
+COMMANDS:
+  bench                Synthetic kernel performance benchmark
+    --chunks <n>       Text chunks per mock turn (default: 200)
+    --iterations <n>   Measurement iterations (default: 50)
+    --warmup <n>       Warmup iterations (default: 5)
+
+  detect-compile <module>  Compile the patterns in a module's detect setting
+    --export <name>    The export holding the setting (default: detect)
+    --out <path>       Where to write the compiled module
+
+  eval <suite>         Run an eval suite live or over recorded traces
+    --recorded <path>  Grade a JSONL file or directory of trace records instead of running
+    --trials <k>       Trials per case, overriding the suite
+    --concurrency <n>  Trials in flight at once (default: 1)
+    --max-cost-usd <n> Stop starting trials once the run's cost passes this
+    --threshold <f>    Fraction of cases that must pass for exit 0 (default 1)
+    --trace-dir <path> Append trial and run records as JSONL under this directory
+    --json             Print the run as one JSON document
+
+  fuzz                 Adversarial inbound sanitization fuzzer
+  fuzz-canary          Adversarial canary egress fuzzer (stream + Live gates)
+
+  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           Requires googleSearch on the selected model's builtInTools
+    --map              Requires googleMaps on the selected model's builtInTools
+    --verbose, -v      Print errorInternal and evidence.raw while running
+    --trace            Capture a TraceRecord and print it after the turn
+    --trace-dir <path> Also append trace JSONL under this directory
+
+  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           Requires googleSearch on the selected model's builtInTools
+    --map              Requires googleMaps on the selected model's builtInTools
+    --verbose, -v      Print errorInternal and evidence.raw while running
+    --trace            Capture a TraceRecord and print it after each turn
+    --trace-dir <path> Also append trace JSONL under this directory
+
+  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 cliDiagnostics(flags) {
+    return {
+        verbose: Boolean(flags.verbose || flags.v),
+        trace: Boolean(flags.trace),
+        traceDir: typeof flags['trace-dir'] === 'string' ? flags['trace-dir'] : undefined,
+    };
+}
+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 if (key === 'v')
+        flags.verbose = 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 diagnostics = cliDiagnostics(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,
+        verbose: diagnostics.verbose,
+        trace: diagnostics.trace,
+        traceDir: diagnostics.traceDir,
+    });
+    if (!success) {
+        exit(1);
+    }
+}
+async function handleRun(flags) {
+    const profile = extractProfileId(flags);
+    if (!profile) {
+        console.error('Error: Profile ID required (e.g. `agents run --profile your-profile`)');
+        exit(1);
+    }
+    const prompt = typeof flags.prompt === 'string' ? flags.prompt : flags._.slice(1).join(' ');
+    const diagnostics = cliDiagnostics(flags);
+    await runCommand({
+        profile,
+        prompt,
+        mode: typeof flags.mode === 'string' ? flags.mode : undefined,
+        search: Boolean(flags.search),
+        map: Boolean(flags.map),
+        verbose: diagnostics.verbose,
+        trace: diagnostics.trace,
+        traceDir: diagnostics.traceDir,
+    });
+}
+function numberFlag(flags, key) {
+    return typeof flags[key] === 'string' ? Number(flags[key]) : undefined;
+}
+async function handleEval(flags) {
+    const suite = flags._[1];
+    if (!suite) {
+        console.error('Error: Suite module required (e.g. `agents eval ./evals/suite.ts`)');
+        exit(1);
+    }
+    const ok = await evalCommand({
+        suite,
+        recorded: typeof flags.recorded === 'string' ? flags.recorded : undefined,
+        trials: numberFlag(flags, 'trials'),
+        concurrency: numberFlag(flags, 'concurrency'),
+        maxCostUsd: numberFlag(flags, 'max-cost-usd'),
+        threshold: numberFlag(flags, 'threshold'),
+        traceDir: cliDiagnostics(flags).traceDir,
+        json: Boolean(flags.json),
+    });
+    if (!ok) {
+        exit(1);
+    }
+}
+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. `agents profile show your-profile`)');
+        exit(1);
+    }
+    showProfileCommand(id);
+}
+async function handleDetectCompile(flags) {
+    const module = flags._[1];
+    if (!module || typeof flags.out !== 'string') {
+        console.error('Error: usage `agents detect-compile <module> --out <path> [--export <name>]`');
+        exit(1);
+    }
+    try {
+        const detectors = await detectCompileCommand({
+            module,
+            exportName: typeof flags.export === 'string' ? flags.export : undefined,
+            out: flags.out,
+        });
+        console.log(`Compiled the patterns of ${detectors.join(', ') || 'no detector'} to ${flags.out}`);
+    }
+    catch (err) {
+        console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
+        exit(1);
+    }
+}
+/** Unknown or omitted commands print help; a command that cannot continue exits 1. */
+export async function main(cliArgs = argv.slice(2)) {
+    const flags = parseFlags(cliArgs);
+    const command = flags._[0] || (flags.help ? 'help' : 'help');
+    if (command === 'fuzz') {
+        const ok = fuzzGuardrailsCommand();
+        if (!ok) {
+            exit(1);
+        }
+    }
+    else if (command === 'fuzz-canary') {
+        const ok = await fuzzCanaryCommand();
+        if (!ok) {
+            exit(1);
+        }
+    }
+    else if (command === 'detect-compile') {
+        await handleDetectCompile(flags);
+    }
+    else if (command === 'bench') {
+        await benchCommand({
+            chunks: typeof flags.chunks === 'string' ? Number(flags.chunks) : undefined,
+            iterations: typeof flags.iterations === 'string' ? Number(flags.iterations) : undefined,
+            warmup: typeof flags.warmup === 'string' ? Number(flags.warmup) : undefined,
+        });
+    }
+    else if (command === 'test') {
+        await handleTest(flags);
+    }
+    else if (command === 'run') {
+        await handleRun(flags);
+    }
+    else if (command === 'eval') {
+        await handleEval(flags);
+    }
+    else if (command === 'profile') {
+        handleProfile(flags);
+    }
+    else {
+        printHelp();
+    }
+}

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

@@ -0,0 +1,10 @@
+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,67 @@
+export const FIXTURE_PNG_BASE64 = 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==';
+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');
+export function createSyntheticWavBase64(durationSec = 0.1, sampleRate = 16000) {
+    const numSamples = Math.floor(sampleRate * durationSec);
+    const dataSize = numSamples * 2;
+    const buffer = new ArrayBuffer(44 + dataSize);
+    const view = new DataView(buffer);
+    view.setUint8(0, 0x52);
+    view.setUint8(1, 0x49);
+    view.setUint8(2, 0x46);
+    view.setUint8(3, 0x46);
+    view.setUint32(4, 36 + dataSize, true);
+    view.setUint8(8, 0x57);
+    view.setUint8(9, 0x41);
+    view.setUint8(10, 0x56);
+    view.setUint8(11, 0x45);
+    view.setUint8(12, 0x66);
+    view.setUint8(13, 0x6d);
+    view.setUint8(14, 0x74);
+    view.setUint8(15, 0x20);
+    view.setUint32(16, 16, true);
+    view.setUint16(20, 1, true);
+    view.setUint16(22, 1, true);
+    view.setUint32(24, sampleRate, true);
+    view.setUint32(28, sampleRate * 2, true);
+    view.setUint16(32, 2, true);
+    view.setUint16(34, 16, true);
+    view.setUint8(36, 0x64);
+    view.setUint8(37, 0x61);
+    view.setUint8(38, 0x74);
+    view.setUint8(39, 0x61);
+    view.setUint32(40, dataSize, true);
+    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 Theorem 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,18 @@
+import type { ModelProfile, TurnRequest } from '../../kernel/types.js';
+export interface MatrixOptions {
+    lite?: boolean;
+    /** Requires googleSearch on the selected model's builtInTools. */
+    search?: boolean;
+    /** Requires googleMaps on the selected model's builtInTools. */
+    map?: boolean;
+    mode?: string;
+    attachmentPaths?: string[];
+    voicePath?: string;
+}
+export declare function synthesizeLiteCombo(profile: ModelProfile): TurnRequest;
+export declare function synthesizeStressCombo(profile: ModelProfile): TurnRequest;
+export declare function synthesizeMatrixCombos(profile: ModelProfile): Array<{
+    name: string;
+    req: TurnRequest;
+}>;
+export declare function buildCustomTurnRequest(profile: ModelProfile, options: MatrixOptions): TurnRequest;