theorum 0.1.3 → 0.1.4

package/{esm/mod.d.ts → mod.ts}

@@ -36,18 +36,60 @@
  *
  * @module
  */
-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 { CATALOG, clampThinkingLevel, clampThinkingLevelForApiId, getTool, listBuiltinIds, modelEntryByApiId, registerTools, requireModelSpec, resetTools, } from './src/kernel/registry/catalog.js';
-export type { ProfileDefinition } from './src/kernel/registry/profiles.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 type * from './src/kernel/types.js';
-export { jsonlSink, memorySink, noopSink, resolveTraceDir, sinkFromDir, writeTrace, } from './src/observability/trace.js';
-export type { TraceRecord } from './src/observability/trace-record.js';
-export type { CreateProviderOptions, GeminiTransport, GeminiVault } from './src/providers/mod.js';
-export { createProvider } from './src/providers/mod.js';
+
+export { publicError, TheorumError } from './src/guardrails/error.ts';
+export type { QuotaSlotStatus } from './src/guardrails/quota.ts';
+export {
+  clientIp,
+  quotaMessage,
+  releaseSlot,
+  resetSlots,
+  skipQuota,
+  takeSlot,
+} from './src/guardrails/quota.ts';
+export {
+  PROJECT_ID_MAX,
+  sanitizeProjectId,
+  sanitizeText,
+  sanitizeTurnRequest,
+} from './src/guardrails/sanitize.ts';
+export { runTurn } from './src/kernel/engine/runner.ts';
+export {
+  CATALOG,
+  clampThinkingLevel,
+  clampThinkingLevelForApiId,
+  geminiKindForMime,
+  getTool,
+  listBuiltinIds,
+  mimeAllowed,
+  mimeEssence,
+  modelEntryByApiId,
+  registerTools,
+  requireModelSpec,
+  resetTools,
+} from './src/kernel/registry/catalog.ts';
+export type { ProfileDefinition } from './src/kernel/registry/profiles.ts';
+export {
+  clearProfiles,
+  defineProfile,
+  getProfile,
+  hasProfile,
+  listProfiles,
+  registerProfile,
+  registerProfiles,
+} from './src/kernel/registry/profiles.ts';
+export { projectProfile, resolveTurn } from './src/kernel/registry/resolve.ts';
+export { getStructured, registerStructured } from './src/kernel/registry/schemas.ts';
+export { executeTool } from './src/kernel/registry/tools.ts';
+export type * from './src/kernel/types.ts';
+export {
+  jsonlSink,
+  memorySink,
+  noopSink,
+  resolveTraceDir,
+  sinkFromDir,
+  writeTrace,
+} from './src/observability/trace.ts';
+export type { TraceRecord } from './src/observability/trace-record.ts';
+export type { CreateProviderOptions, GeminiTransport, GeminiVault } from './src/providers/mod.ts';
+export { createProvider } from './src/providers/mod.ts';

package/package.json

@@ -1,7 +1,9 @@
 {
   "name": "theorum",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "A flat TypeScript agent kernel for typed profiles, deterministic turn execution, dynamic tools, provider adapters, guardrails, and host-injected traces.",
+  "license": "MIT",
+  "type": "module",
   "keywords": [
     "agent",
     "ai",
@@ -13,53 +15,42 @@
     "openrouter",
     "gemini"
   ],
-  "license": "MIT",
-  "module": "./esm/mod.js",
   "exports": {
-    ".": {
-      "import": "./esm/mod.js"
-    },
-    "./kernel": {
-      "import": "./esm/src/kernel/mod.js"
-    },
-    "./providers": {
-      "import": "./esm/src/providers/mod.js"
-    },
-    "./openrouter": {
-      "import": "./esm/src/providers/openrouter-mod.js"
-    },
-    "./guardrails": {
-      "import": "./esm/src/guardrails/mod.js"
-    },
-    "./observability": {
-      "import": "./esm/src/observability/mod.js"
-    },
-    "./host": {
-      "import": "./esm/src/host/mod.js"
-    },
-    "./cli": {
-      "import": "./esm/src/cli/index.js"
-    },
-    "./presets": {
-      "import": "./esm/src/presets/mod.js"
-    },
-    "./presets/google": {
-      "import": "./esm/src/presets/google.js"
-    }
-  },
-  "scripts": {},
-  "bin": {
-    "theorum": "esm/src/cli/index.js"
+    ".": "./mod.ts",
+    "./kernel": "./src/kernel/mod.ts",
+    "./providers": "./src/providers/mod.ts",
+    "./openrouter": "./src/providers/openrouter-mod.ts",
+    "./guardrails": "./src/guardrails/mod.ts",
+    "./observability": "./src/observability/mod.ts",
+    "./host": "./src/host/mod.ts",
+    "./cli": "./src/cli/index.ts",
+    "./presets": "./src/presets/mod.ts",
+    "./presets/google": "./src/presets/google.ts"
   },
-  "type": "module",
-  "sideEffects": false,
+  "files": [
+    "README.md",
+    "deno.json",
+    "deno.lock",
+    "docs/",
+    "mod.ts",
+    "src/"
+  ],
   "dependencies": {
     "@openrouter/ai-sdk-provider": "1.5.4",
-    "ai": "5.0.244",
-    "@deno/shim-deno": "~0.18.0"
+    "ai": "5.0.244"
   },
-  "devDependencies": {
-    "@types/node": "^20.9.0"
+  "scripts": {
+    "build:npm": "deno run --allow-read --allow-write --allow-env --allow-net --allow-run=npm scripts/build-npm.ts",
+    "test": "deno test --allow-read --allow-write --allow-net",
+    "coverage": "rm -rf coverage && deno test --allow-read --allow-write --allow-net --coverage=coverage tests/ && deno coverage coverage --lcov --output=coverage/lcov.info && node scripts/lcov-to-istanbul.mjs",
+    "lint:biome": "biome check .",
+    "lint:ast-grep": "ast-grep scan",
+    "lint:fallow": "npm run coverage && fallow audit && fallow health && fallow dupes && fallow dead-code",
+    "lint": "npm run lint:biome && npm run lint:ast-grep && npm run lint:fallow"
   },
-  "_generatedBy": "dnt@0.43.2"
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.8",
+    "@ast-grep/cli": "^0.41.0",
+    "fallow": "3.17.0"
+  }
 }

package/src/cli/commands/profile.ts

@@ -0,0 +1,57 @@
+import { getProfile, listProfiles } from '../../kernel/registry/profiles.ts';
+import type { Profile } from '../../kernel/types.ts';
+
+function formatProfileInputs(p: Profile): string {
+  const inputs: string[] = [];
+  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: Profile): void {
+  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(): void {
+  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: string): void {
+  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/src/cli/commands/run.ts

@@ -0,0 +1,66 @@
+import { runTurn } from '../../kernel/engine/runner.ts';
+import { getProfile } from '../../kernel/registry/profiles.ts';
+import type { ModelProvider, TurnEvent, TurnRequest } from '../../kernel/types.ts';
+
+export interface RunOptions {
+  profile: string;
+  prompt?: string;
+  mode?: string;
+  search?: boolean;
+  map?: boolean;
+  provider?: ModelProvider;
+}
+
+function handleRunEvent(event: TurnEvent): void {
+  if (event.type === 'thought' && event.text) {
+    Deno.stdout.write(new TextEncoder().encode(`\x1b[2m${event.text}\x1b[0m`));
+  } else if (event.type === 'text' && event.text) {
+    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: RunOptions): Promise<void> {
+  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: Record<string, boolean> = {};
+  if (options.search) tools.googleSearch = true;
+  if (options.map) tools.googleMaps = true;
+
+  const req: TurnRequest = {
+    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/src/cli/commands/test.ts

@@ -0,0 +1,195 @@
+import { runTurn } from '../../kernel/engine/runner.ts';
+import { getProfile, listProfiles } from '../../kernel/registry/profiles.ts';
+import type { ModelProvider, Profile, TurnEvent, TurnRequest } from '../../kernel/types.ts';
+import {
+  buildCustomTurnRequest,
+  type MatrixOptions,
+  synthesizeMatrixCombos,
+} from '../matrix/synthesizer.ts';
+
+export interface TestRunResult {
+  passed: boolean;
+  name: string;
+  durationSec: number;
+  tokensTotal?: number;
+  error?: string;
+}
+
+interface TestExecutionAccumulator {
+  totalTokens: number;
+  hasError: boolean;
+  errorMessage: string;
+}
+
+function printTestHeader(req: TurnRequest, testName: string): void {
+  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: TurnEvent, acc: TestExecutionAccumulator): void {
+  if (event.type === 'thought' && event.text) {
+    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: boolean,
+  durationSec: number,
+  acc: TestExecutionAccumulator,
+): void {
+  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: TurnRequest,
+  testName: string,
+  provider?: ModelProvider,
+): Promise<TestRunResult> {
+  const start = Date.now();
+  getProfile(req.profile);
+  printTestHeader(req, testName);
+
+  const acc: TestExecutionAccumulator = {
+    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: string | undefined,
+  all: boolean | undefined,
+): Profile[] | null {
+  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: Profile,
+  provider?: ModelProvider,
+): Promise<TestRunResult[]> {
+  const results: TestRunResult[] = [];
+  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: Profile,
+  options: MatrixOptions,
+  provider?: ModelProvider,
+): Promise<TestRunResult> {
+  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: TestRunResult[]): boolean {
+  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?: string,
+  options: MatrixOptions & { all?: boolean; matrix?: boolean; provider?: ModelProvider } = {},
+): Promise<boolean> {
+  const targetProfiles = resolveTargetProfiles(profileId, options.all);
+  if (!targetProfiles || targetProfiles.length === 0) {
+    return false;
+  }
+
+  const results: TestRunResult[] = [];
+  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/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();
+}