paracosm 0.4.346 → 0.4.377

package/README.md

@@ -38,9 +38,11 @@ Same seed, same starting conditions, different leaders, different civilizations.
 ## Quickstart
 
 ```bash
-npm install paracosm
+npm install paracosm      # also works: pnpm add paracosm / bun add paracosm
 ```
 
+Paracosm ships as pure ESM with subpath exports (`paracosm/compiler`, `paracosm/runtime`, `paracosm/mars`, `paracosm/lunar`, `paracosm/core`). Node 20+, Bun 1.x, and any TypeScript runner with ESM + import-attributes support (`tsx`, `ts-node --esm`) resolve them out of the box. If `import ... from 'paracosm/compiler'` fails with a module-not-found error, the dependency was never installed in that project — `cd` into the right directory and run one of the commands above.
+
 ### 1. Define your world
 
 Every scenario declares its own vocabulary via `labels.populationNoun`
@@ -118,7 +120,7 @@ bounded collective under a leader's decisions.
 ```typescript
 import { compileScenario } from 'paracosm/compiler';
 import { runSimulation } from 'paracosm/runtime';
-import worldJson from './my-world.json';
+import worldJson from './my-world.json' with { type: 'json' };
 
 // Compile JSON into a runnable scenario (~$0.10, cached to disk)
 const scenario = await compileScenario(worldJson, {
@@ -162,6 +164,19 @@ const results = await Promise.all(
     })
   )
 );
+
+// The return value is a full run artifact. A few of the fields most
+// consumers want right away:
+for (const r of results) {
+  console.log(r.leader.name, '→', r.fingerprint);
+  console.log('  cost   $', r.cost.totalCostUSD.toFixed(2), `(${r.cost.llmCalls} LLM calls)`);
+  console.log('  final    ', r.finalState.colony);        // population, morale, foodMonthsReserve, powerKw, …
+  console.log('  tools    ', r.forgedToolbox.length,      // deduped forge ledger
+               'citations', r.citationCatalog.length);     // DOI-linked references
+  if (r.providerError) {
+    console.error('  provider error:', r.providerError.kind, r.providerError.message);
+  }
+}
 ```
 
 Each call to `runSimulation` takes one leader. Run one, two, or twenty. The dashboard runs two side-by-side for comparison, but the API has no limit. Leaders don't need to be people. They can model competing strategies, policy frameworks, organizational philosophies, or autonomous systems responding to the same events with different decision profiles.
@@ -177,6 +192,34 @@ npm run dashboard      # opens http://localhost:3456
 
 The dashboard includes a scenario editor where you can write, import, compile, and run custom worlds from the browser.
 
+### 4. Or run the standalone CLI
+
+After `npm install paracosm` you get two binaries:
+
+```bash
+paracosm                # run one leader once; prints turn-by-turn narrative
+paracosm-dashboard 6    # start the web dashboard and run a 6-turn sim
+```
+
+Both CLIs look for `leaders.json` in this order:
+
+1. `--leaders <path>` flag (explicit)
+2. `./leaders.json` in your current directory
+3. `./config/leaders.json` in your current directory
+4. A bundled `config/leaders.example.json` (so commands work out of the box)
+
+Copy the example to start customizing:
+
+```bash
+# Option 1: in your project root
+cp node_modules/paracosm/config/leaders.example.json leaders.json
+
+# Option 2: organized in a config/ folder
+mkdir -p config && cp node_modules/paracosm/config/leaders.example.json config/leaders.json
+```
+
+Then edit the HEXACO sliders and `instructions` fields to describe your own leaders — the simulation picks up the file on the next run.
+
 ## Scenario Compiler
 
 The compiler turns your JSON into a runnable scenario by generating TypeScript hooks via LLM calls:
@@ -189,19 +232,148 @@ npm run compile -- scenarios/submarine.json \
 
 Options: `--seed-text`, `--seed-url`, `--no-web-search`, `--max-searches`. Compiled scenarios appear in the dashboard selector. Cost is roughly $0.10 per compile, cached to disk after first generation.
 
+### Programmatic compiler options
+
+Every CLI flag has a matching programmatic option on `compileScenario`. The compiler caches per-hook on the scenario hash + model + schema version, and separately caches the seed bundle on the seed signature (text/URL + `webSearch` + `maxSearches`), so re-running the same call is free after the first hit.
+
+```typescript
+import { compileScenario } from 'paracosm/compiler';
+
+const scenario = await compileScenario(worldJson, {
+  provider: 'anthropic',             // 'openai' (default) or 'anthropic'
+  model: 'claude-sonnet-4-6',        // omit → provider default (gpt-5.4-mini / claude-sonnet-4-6)
+  cache: true,                       // default. Set false to force regeneration.
+  cacheDir: '.paracosm/cache',       // default. Change per project / per CI run.
+  seedUrl: 'https://ntrs.nasa.gov/citations/20210018970',  // or: seedText: '…inline markdown…'
+  webSearch: true,                   // fan out to Firecrawl/Tavily/Serper/Brave
+  maxSearches: 5,
+  onProgress(hookName, status) {
+    // 'generating' | 'cached' | 'done' | 'fallback'
+    console.log(`  [${status.padEnd(10)}] ${hookName}`);
+  },
+});
+```
+
+Cache hits show up as `cached` in the progress callback. First-run cost is roughly $0.10; cached re-runs are free. If neither `OPENAI_API_KEY` nor `ANTHROPIC_API_KEY` is set, the compiler throws `ProviderKeyMissingError` before making any calls — see [Error handling](#error-handling).
+
 ## Cost Envelope
 
-Running a simulation calls real LLM APIs against your key. Typical spend per run on provider defaults (6 turns, 5 departments, 100 agents, up to 3 events per turn):
+Running a simulation calls real LLM APIs against your key. Typical spend per run on provider defaults (6 turns, 5 departments, 100 agents, up to 3 events per turn). Paracosm assigns a different tier per role so flagship cost only lands where it earns its keep (forge-code correctness):
 
-| Provider | Commander / Departments / Director | Judge | Reactions | Per-run total |
-|----------|-------------------------------------|-------|-----------|---------------|
-| OpenAI   | `gpt-5.4`              | `gpt-4o-mini`              | `gpt-4o-mini`              | ~$1-3  |
-| Anthropic| `claude-sonnet-4-6`    | `claude-haiku-4-5-20251001`| `claude-haiku-4-5-20251001`| ~$3-7  |
+| Provider  | Departments (flagship) | Commander / Director / Judge (mid-tier) | Reactions (cheapest) | Per-run total |
+|-----------|------------------------|------------------------------------------|----------------------|---------------|
+| OpenAI    | `gpt-5.4`              | `gpt-5.4-mini`                           | `gpt-5.4-nano`       | ~$1-3  |
+| Anthropic | `claude-sonnet-4-6`    | `claude-haiku-4-5-20251001`              | `claude-haiku-4-5-20251001` | ~$3-7  |
 
-The single biggest lever is the judge model — it runs once per forge attempt (easily 60+ calls per 6-turn run) so keeping it on the cheap tier is what makes the run affordable. Running the judge on a flagship model triples the total.
+The single biggest lever is the judge model — it runs once per forge attempt (easily 60+ calls per 6-turn run) so keeping it on the mid-tier is what makes the run affordable. Promoting the judge to flagship triples the total. Override any role via `models` on `RunOptions`: `{ models: { judge: 'gpt-5.4' } }` if you want to pay for stricter review.
 
 The orchestrator's `runSimulation()` returns a `cost` field with token counts, LLM call counts, and USD spend aggregated from every tracked call (director, departments, commander, judge, agent reactions). The dashboard StatsBar shows this live.
 
+### Prompt caching
+
+Every LLM call site on both providers routes its stable system prefix through a `cacheBreakpoint: true` block (director instructions, department prompts, reaction batches, compile-time hook generators). On Anthropic, turn 2+ of every run serves the shared prefix from the provider's prompt cache at 0.1× input cost. On OpenAI, any prompt ≥ 1024 tokens auto-caches. The `cost.caches` field reports read / creation tokens and USD saved per run, and `/retry-stats` rolls the numbers up across the last 100 runs so you can verify the cache is actually hitting. No configuration required — the `system: Array<{ text; cacheBreakpoint }>` shape is built into the validated-call wrappers in `src/engine/compiler/llm-invocations/` and `src/runtime/llm-invocations/`.
+
+## Programmatic API
+
+Everything the dashboard does is also available as library calls. The exports fall into five buckets:
+
+| Import | Surface |
+|--------|---------|
+| `paracosm/compiler` | `compileScenario`, `ingestSeed`, `ingestFromUrl`, type `CompileOptions` |
+| `paracosm/runtime`  | `runSimulation`, `runBatch`, `EventDirector`, `generateAgentReactions`, memory helpers |
+| `paracosm`          | `ProviderKeyMissingError`, `SeededRng`, `SimulationKernel`, all `Scenario*` types |
+| `paracosm/core`     | Kernel state types (`Agent`, `WorldState`, `HexacoProfile`, …) |
+| `paracosm/mars`, `paracosm/lunar` | Pre-built `ScenarioPackage` constants to use or fork |
+
+### Batch runner — N scenarios × M leaders
+
+```typescript
+import { runBatch } from 'paracosm/runtime';
+import { marsScenario, lunarScenario } from 'paracosm';
+
+const manifest = await runBatch({
+  scenarios: [marsScenario, lunarScenario],
+  leaders,                // LeaderConfig[] — same shape as runSimulation
+  turns: 6,
+  seed: 950,
+  maxConcurrency: 2,      // how many sims to run in parallel
+  provider: 'anthropic',
+});
+
+// manifest.results[i] carries { scenarioId, leader, fingerprint, output, duration }
+// manifest.timestamp + manifest.config is a reproducible audit trail
+```
+
+### Seed ingestion from a URL or inline text
+
+The compiler grounds agents in real sources. Pass `seedText` for inline markdown / PDFs you already have, or `seedUrl` to let Firecrawl extract clean markdown from any public page. The bundle is cached separately from the hook cache, keyed on the seed signature, so the same URL never re-extracts.
+
+```typescript
+const scenario = await compileScenario(worldJson, {
+  seedUrl: 'https://ntrs.nasa.gov/citations/20210018970',
+  webSearch: true,        // also fan out to Tavily/Serper/Brave for more citations
+  maxSearches: 5,
+});
+// Every department prompt, Event Director batch, and report.citations[] entry
+// at runtime will draw from this bundle.
+```
+
+### Cancellation via AbortSignal
+
+The server wires this to a cancel-on-disconnect watchdog; any programmatic consumer can do the same. When `.aborted` flips to true, the turn loop short-circuits at the next turn boundary, emits a `sim_aborted` event, and returns the partial result accumulated so far with `output.aborted === true`.
+
+```typescript
+const ctrl = new AbortController();
+setTimeout(() => ctrl.abort(), 60_000);            // kill after 60s wall time
+
+const output = await runSimulation(leader, [], {
+  scenario, maxTurns: 8, seed: 42,
+  signal: ctrl.signal,
+});
+
+if (output.aborted) console.log('partial result; turns completed:', output.turnArtifacts.length);
+```
+
+### Custom events injected at specific turns
+
+When you want a scripted event at a fixed turn (smoke tests, pedagogical demos, reproducing a scenario from a paper), supply `customEvents`:
+
+```typescript
+await runSimulation(leader, [], {
+  scenario, maxTurns: 8, seed: 42,
+  customEvents: [
+    { turn: 3, title: 'Dust storm', description: 'A 72-hour planetary dust storm cuts solar output by 80%.' },
+    { turn: 6, title: 'Supply drop', description: 'Earth relief mission delivers 3 months of food reserves.' },
+  ],
+});
+```
+
+### Error handling
+
+```typescript
+import { runSimulation, ProviderKeyMissingError } from 'paracosm';
+
+try {
+  const output = await runSimulation(leader, [], { scenario, maxTurns: 8, seed: 42 });
+  if (output.providerError) {
+    // Terminal provider failure (invalid key, quota exhausted) — the run
+    // aborted mid-way. turnArtifacts / finalState are partial.
+    console.error(output.providerError.kind,        // 'auth' | 'quota' | 'rate_limit' | 'network' | 'unknown'
+                  output.providerError.provider,
+                  output.providerError.message,
+                  output.providerError.actionUrl);
+  }
+} catch (err) {
+  if (err instanceof ProviderKeyMissingError) {
+    console.error('set OPENAI_API_KEY or ANTHROPIC_API_KEY before running');
+    process.exit(1);
+  }
+  throw err;
+}
+```
+
+The resolver inspects `process.env` once up front, so a missing key fails loudly at the top of the run instead of retrying silently on every LLM call.
+
 ## Seed Enrichment & Citation Flow
 
 Pass real-world source material into the compiler and Paracosm grounds the scenario in citations that flow all the way through to department reports.
@@ -334,12 +506,12 @@ src/
 
 | Import | What |
 |--------|------|
-| `paracosm` | Engine types, registries, kernel |
-| `paracosm/compiler` | `compileScenario()` |
-| `paracosm/runtime` | `runSimulation()`, `runBatch()` |
-| `paracosm/mars` | Mars Genesis scenario |
-| `paracosm/lunar` | Lunar Outpost scenario |
-| `paracosm/core` | Kernel state types |
+| `paracosm` | Engine types, registries, `SimulationKernel`, `SeededRng`, scenario packages, `ProviderKeyMissingError` |
+| `paracosm/compiler` | `compileScenario()`, `ingestSeed()`, `ingestFromUrl()` |
+| `paracosm/runtime` | `runSimulation()`, `runBatch()`, `EventDirector`, `generateAgentReactions()`, memory helpers |
+| `paracosm/mars` | Mars Genesis `ScenarioPackage` |
+| `paracosm/lunar` | Lunar Outpost `ScenarioPackage` |
+| `paracosm/core` | Kernel state types (`Agent`, `WorldState`, `HexacoProfile`) |
 
 ## Built on AgentOS
 

package/config/leaders.example.json

@@ -0,0 +1,32 @@
+{
+  "leaders": [
+    {
+      "name": "Aria Chen",
+      "archetype": "The Visionary",
+      "colony": "Ares Horizon",
+      "hexaco": {
+        "openness": 0.95,
+        "conscientiousness": 0.35,
+        "extraversion": 0.85,
+        "agreeableness": 0.55,
+        "emotionality": 0.30,
+        "honestyHumility": 0.65
+      },
+      "instructions": "You are Commander Aria Chen. Bold expansion, calculated risks. Favor higher upside even when riskier. Respond with JSON."
+    },
+    {
+      "name": "Dietrich Voss",
+      "archetype": "The Engineer",
+      "colony": "Meridian Base",
+      "hexaco": {
+        "openness": 0.25,
+        "conscientiousness": 0.97,
+        "extraversion": 0.30,
+        "agreeableness": 0.45,
+        "emotionality": 0.70,
+        "honestyHumility": 0.90
+      },
+      "instructions": "You are Commander Dietrich Voss. Engineering discipline, safety margins. Favor lower risk. Respond with JSON."
+    }
+  ]
+}

package/config/leaders.json

@@ -0,0 +1,32 @@
+{
+  "leaders": [
+    {
+      "name": "Aria Chen",
+      "archetype": "The Visionary",
+      "colony": "Ares Horizon",
+      "hexaco": {
+        "openness": 0.95,
+        "conscientiousness": 0.35,
+        "extraversion": 0.85,
+        "agreeableness": 0.55,
+        "emotionality": 0.30,
+        "honestyHumility": 0.65
+      },
+      "instructions": "You are Commander Aria Chen. Bold expansion, calculated risks. Favor higher upside even when riskier. Respond with JSON."
+    },
+    {
+      "name": "Dietrich Voss",
+      "archetype": "The Engineer",
+      "colony": "Meridian Base",
+      "hexaco": {
+        "openness": 0.25,
+        "conscientiousness": 0.97,
+        "extraversion": 0.30,
+        "agreeableness": 0.45,
+        "emotionality": 0.70,
+        "honestyHumility": 0.90
+      },
+      "instructions": "You are Commander Dietrich Voss. Engineering discipline, safety margins. Demand data before decisions. Favor lower risk. Respond with JSON."
+    }
+  ]
+}

package/dist/cli/cli-run-options.d.ts

@@ -0,0 +1,11 @@
+import type { LlmProvider, SimulationModelConfig } from './sim-config.js';
+export interface CliRunOptions {
+    maxTurns?: number;
+    seed?: number;
+    startYear?: number;
+    liveSearch: boolean;
+    provider?: LlmProvider;
+    models?: Partial<SimulationModelConfig>;
+}
+export declare function parseCliRunOptions(argv: string[]): CliRunOptions;
+//# sourceMappingURL=cli-run-options.d.ts.map

package/dist/cli/cli-run-options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-run-options.d.ts","sourceRoot":"","sources":["../../src/cli/cli-run-options.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAE1E,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,OAAO,CAAC;IACpB,QAAQ,CAAC,EAAE,WAAW,CAAC;IACvB,MAAM,CAAC,EAAE,OAAO,CAAC,qBAAqB,CAAC,CAAC;CACzC;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,aAAa,CAwChE"}

package/dist/cli/cli-run-options.js

@@ -0,0 +1,39 @@
+export function parseCliRunOptions(argv) {
+    const options = { liveSearch: false };
+    for (let index = 0; index < argv.length; index++) {
+        const arg = argv[index];
+        if (!arg.startsWith('--') && options.maxTurns === undefined) {
+            const turns = Number.parseInt(arg, 10);
+            if (Number.isFinite(turns))
+                options.maxTurns = turns;
+            continue;
+        }
+        switch (arg) {
+            case '--live':
+                options.liveSearch = true;
+                break;
+            case '--seed':
+                options.seed = Number.parseInt(argv[++index] ?? '', 10);
+                break;
+            case '--start-year':
+                options.startYear = Number.parseInt(argv[++index] ?? '', 10);
+                break;
+            case '--provider':
+                options.provider = argv[++index];
+                break;
+            case '--commander-model':
+                options.models = { ...(options.models ?? {}), commander: argv[++index] };
+                break;
+            case '--department-model':
+                options.models = { ...(options.models ?? {}), departments: argv[++index] };
+                break;
+            case '--judge-model':
+                options.models = { ...(options.models ?? {}), judge: argv[++index] };
+                break;
+            default:
+                break;
+        }
+    }
+    return options;
+}
+//# sourceMappingURL=cli-run-options.js.map

package/dist/cli/cli-run-options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-run-options.js","sourceRoot":"","sources":["../../src/cli/cli-run-options.ts"],"names":[],"mappings":"AAWA,MAAM,UAAU,kBAAkB,CAAC,IAAc;IAC/C,MAAM,OAAO,GAAkB,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC;IAErD,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC;QACjD,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC;QAExB,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,OAAO,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC5D,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;YACvC,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;gBAAE,OAAO,CAAC,QAAQ,GAAG,KAAK,CAAC;YACrD,SAAS;QACX,CAAC;QAED,QAAQ,GAAG,EAAE,CAAC;YACZ,KAAK,QAAQ;gBACX,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;gBAC1B,MAAM;YACR,KAAK,QAAQ;gBACX,OAAO,CAAC,IAAI,GAAG,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;gBACxD,MAAM;YACR,KAAK,cAAc;gBACjB,OAAO,CAAC,SAAS,GAAG,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;gBAC7D,MAAM;YACR,KAAK,YAAY;gBACf,OAAO,CAAC,QAAQ,GAAI,IAAI,CAAC,EAAE,KAAK,CAA6B,CAAC;gBAC9D,MAAM;YACR,KAAK,mBAAmB;gBACtB,OAAO,CAAC,MAAM,GAAG,EAAE,GAAG,CAAC,OAAO,CAAC,MAAM,IAAI,EAAE,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,EAAE,KAAK,CAAC,EAAE,CAAC;gBACzE,MAAM;YACR,KAAK,oBAAoB;gBACvB,OAAO,CAAC,MAAM,GAAG,EAAE,GAAG,CAAC,OAAO,CAAC,MAAM,IAAI,EAAE,CAAC,EAAE,WAAW,EAAE,IAAI,CAAC,EAAE,KAAK,CAAC,EAAE,CAAC;gBAC3E,MAAM;YACR,KAAK,eAAe;gBAClB,OAAO,CAAC,MAAM,GAAG,EAAE,GAAG,CAAC,OAAO,CAAC,MAAM,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,EAAE,KAAK,CAAC,EAAE,CAAC;gBACrE,MAAM;YACR;gBACE,MAAM;QACV,CAAC;IACH,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/cli/compile-cli-options.d.ts

@@ -0,0 +1,14 @@
+import type { LlmProvider } from '../engine/types.js';
+export interface CompileCliOptions {
+    scenarioPath?: string;
+    provider: LlmProvider;
+    model: string;
+    cache: boolean;
+    cacheDir: string;
+    seedText?: string;
+    seedUrl?: string;
+    webSearch: boolean;
+    maxSearches?: number;
+}
+export declare function parseCompileCliOptions(argv: string[]): CompileCliOptions;
+//# sourceMappingURL=compile-cli-options.d.ts.map

package/dist/cli/compile-cli-options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compile-cli-options.d.ts","sourceRoot":"","sources":["../../src/cli/compile-cli-options.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD,MAAM,WAAW,iBAAiB;IAChC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,WAAW,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,OAAO,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,iBAAiB,CAkDxE"}

package/dist/cli/compile-cli-options.js

@@ -0,0 +1,48 @@
+export function parseCompileCliOptions(argv) {
+    const options = {
+        provider: 'anthropic',
+        model: 'claude-sonnet-4-6',
+        cache: true,
+        cacheDir: '.paracosm/cache',
+        webSearch: true,
+    };
+    for (let index = 0; index < argv.length; index++) {
+        const arg = argv[index];
+        if (!arg.startsWith('--') && !options.scenarioPath) {
+            options.scenarioPath = arg;
+            continue;
+        }
+        switch (arg) {
+            case '--provider':
+                options.provider = argv[++index] ?? options.provider;
+                break;
+            case '--model':
+                options.model = argv[++index] ?? options.model;
+                break;
+            case '--no-cache':
+                options.cache = false;
+                break;
+            case '--cache-dir':
+                options.cacheDir = argv[++index] ?? options.cacheDir;
+                break;
+            case '--seed-text':
+                options.seedText = argv[++index];
+                break;
+            case '--seed-url':
+                options.seedUrl = argv[++index];
+                break;
+            case '--no-web-search':
+                options.webSearch = false;
+                break;
+            case '--max-searches': {
+                const value = Number.parseInt(argv[++index] ?? '', 10);
+                options.maxSearches = Number.isFinite(value) ? value : undefined;
+                break;
+            }
+            default:
+                break;
+        }
+    }
+    return options;
+}
+//# sourceMappingURL=compile-cli-options.js.map

package/dist/cli/compile-cli-options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compile-cli-options.js","sourceRoot":"","sources":["../../src/cli/compile-cli-options.ts"],"names":[],"mappings":"AAcA,MAAM,UAAU,sBAAsB,CAAC,IAAc;IACnD,MAAM,OAAO,GAAsB;QACjC,QAAQ,EAAE,WAAW;QACrB,KAAK,EAAE,mBAAmB;QAC1B,KAAK,EAAE,IAAI;QACX,QAAQ,EAAE,iBAAiB;QAC3B,SAAS,EAAE,IAAI;KAChB,CAAC;IAEF,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC;QACjD,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC;QAExB,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,YAAY,EAAE,CAAC;YACnD,OAAO,CAAC,YAAY,GAAG,GAAG,CAAC;YAC3B,SAAS;QACX,CAAC;QAED,QAAQ,GAAG,EAAE,CAAC;YACZ,KAAK,YAAY;gBACf,OAAO,CAAC,QAAQ,GAAI,IAAI,CAAC,EAAE,KAAK,CAA6B,IAAI,OAAO,CAAC,QAAQ,CAAC;gBAClF,MAAM;YACR,KAAK,SAAS;gBACZ,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC,EAAE,KAAK,CAAC,IAAI,OAAO,CAAC,KAAK,CAAC;gBAC/C,MAAM;YACR,KAAK,YAAY;gBACf,OAAO,CAAC,KAAK,GAAG,KAAK,CAAC;gBACtB,MAAM;YACR,KAAK,aAAa;gBAChB,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,EAAE,KAAK,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAC;gBACrD,MAAM;YACR,KAAK,aAAa;gBAChB,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,EAAE,KAAK,CAAC,CAAC;gBACjC,MAAM;YACR,KAAK,YAAY;gBACf,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,EAAE,KAAK,CAAC,CAAC;gBAChC,MAAM;YACR,KAAK,iBAAiB;gBACpB,OAAO,CAAC,SAAS,GAAG,KAAK,CAAC;gBAC1B,MAAM;YACR,KAAK,gBAAgB,CAAC,CAAC,CAAC;gBACtB,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;gBACvD,OAAO,CAAC,WAAW,GAAG,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;gBACjE,MAAM;YACR,CAAC;YACD;gBACE,MAAM;QACV,CAAC;IACH,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/cli/compile.d.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+/**
+ * CLI: Compile a scenario JSON into a runnable ScenarioPackage.
+ *
+ * Usage:
+ *   npx tsx src/cli/compile.ts scenarios/submarine.json
+ *   npx tsx src/cli/compile.ts scenarios/submarine.json --provider anthropic --model claude-sonnet-4-6
+ *   npx tsx src/cli/compile.ts scenarios/submarine.json --no-cache
+ */
+export {};
+//# sourceMappingURL=compile.d.ts.map

package/dist/cli/compile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compile.d.ts","sourceRoot":"","sources":["../../src/cli/compile.ts"],"names":[],"mappings":";AACA;;;;;;;GAOG"}

package/dist/cli/compile.js

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+/**
+ * CLI: Compile a scenario JSON into a runnable ScenarioPackage.
+ *
+ * Usage:
+ *   npx tsx src/cli/compile.ts scenarios/submarine.json
+ *   npx tsx src/cli/compile.ts scenarios/submarine.json --provider anthropic --model claude-sonnet-4-6
+ *   npx tsx src/cli/compile.ts scenarios/submarine.json --no-cache
+ */
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { compileScenario } from '../engine/compiler/index.js';
+import { parseCompileCliOptions } from './compile-cli-options.js';
+async function main() {
+    const rawArgs = process.argv.slice(2);
+    const options = parseCompileCliOptions(rawArgs);
+    if (rawArgs.length === 0 || rawArgs.includes('--help') || rawArgs.includes('-h')) {
+        console.log(`
+paracosm compile — Generate runtime hooks for a scenario JSON
+
+Usage:
+  npx tsx src/cli/compile.ts <scenario.json> [options]
+
+Options:
+  --provider <provider>   LLM provider: openai | anthropic (default: anthropic)
+  --model <model>         Model name (default: claude-sonnet-4-6)
+  --no-cache              Skip disk cache
+  --cache-dir <dir>       Cache directory (default: .paracosm/cache)
+  --seed-text <text>      Seed scenario knowledge from inline text before hook generation
+  --seed-url <url>        Seed scenario knowledge from a URL before hook generation
+  --no-web-search         Skip live citation grounding during seed ingestion
+  --max-searches <n>      Cap the number of live grounding searches during seed ingestion
+  -h, --help              Show this help
+`);
+        process.exit(0);
+    }
+    if (!options.scenarioPath) {
+        console.error('  Scenario JSON path required. Run with --help for usage.');
+        process.exit(1);
+    }
+    const jsonPath = resolve(options.scenarioPath);
+    console.log(`\n  Compiling scenario: ${jsonPath}`);
+    console.log(`  Provider: ${options.provider} | Model: ${options.model} | Cache: ${options.cache}`);
+    if (options.seedUrl) {
+        console.log(`  Seed URL: ${options.seedUrl} | Web search: ${options.webSearch} | Max searches: ${options.maxSearches ?? 5}`);
+    }
+    else if (options.seedText) {
+        console.log(`  Seed text: ${Math.min(options.seedText.length, 160)} chars | Web search: ${options.webSearch} | Max searches: ${options.maxSearches ?? 5}`);
+    }
+    console.log();
+    let scenarioJson;
+    try {
+        scenarioJson = JSON.parse(readFileSync(jsonPath, 'utf-8'));
+    }
+    catch (err) {
+        console.error(`  Error reading ${jsonPath}: ${err}`);
+        process.exit(1);
+    }
+    const scenario = await compileScenario(scenarioJson, {
+        provider: options.provider,
+        model: options.model,
+        cache: options.cache,
+        cacheDir: options.cacheDir,
+        seedText: options.seedText,
+        seedUrl: options.seedUrl,
+        webSearch: options.webSearch,
+        maxSearches: options.maxSearches,
+        onProgress(hookName, status) {
+            const icons = {
+                generating: '...',
+                cached: '(cached)',
+                done: 'done',
+                fallback: 'FALLBACK',
+            };
+            if (status === 'generating') {
+                process.stdout.write(`  Generating ${hookName}... `);
+            }
+            else {
+                console.log(icons[status] ?? status);
+            }
+        },
+    });
+    console.log(`\n  Scenario compiled: ${scenario.id} v${scenario.version}`);
+    console.log(`  Departments: ${scenario.departments.map(d => d.id).join(', ')}`);
+    console.log(`  Hooks: ${Object.keys(scenario.hooks).filter(k => scenario.hooks[k]).join(', ')}`);
+    console.log(`  Ready for: runSimulation(leader, personnel, { scenario })\n`);
+}
+main().catch((err) => {
+    console.error('Compile failed:', err);
+    process.exit(1);
+});
+//# sourceMappingURL=compile.js.map

package/dist/cli/compile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compile.js","sourceRoot":"","sources":["../../src/cli/compile.ts"],"names":[],"mappings":"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"}

package/dist/cli/custom-scenarios.d.ts

@@ -0,0 +1,10 @@
+import type { ScenarioPackage } from '../engine/types.js';
+export type CustomScenarioSource = 'memory' | 'disk' | 'compiled' | 'builtin';
+export interface CustomScenarioEntry {
+    scenario: ScenarioPackage;
+    source: CustomScenarioSource;
+}
+export declare function isRunnableScenarioPackage(value: unknown): value is ScenarioPackage;
+export declare function loadDiskCustomScenarios(scenarioDir: string): Map<string, CustomScenarioEntry>;
+export declare function describeCustomScenarioSource(source: CustomScenarioSource): string;
+//# sourceMappingURL=custom-scenarios.d.ts.map

package/dist/cli/custom-scenarios.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"custom-scenarios.d.ts","sourceRoot":"","sources":["../../src/cli/custom-scenarios.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAE1D,MAAM,MAAM,oBAAoB,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,GAAG,SAAS,CAAC;AAE9E,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,eAAe,CAAC;IAC1B,MAAM,EAAE,oBAAoB,CAAC;CAC9B;AAcD,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,eAAe,CAwClF;AAED,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAmB7F;AAED,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,oBAAoB,GAAG,MAAM,CAKjF"}