paracosm 0.7.409 → 0.7.431

package/README.md

@@ -5,7 +5,7 @@
 <h1 align="center">PARACOSM</h1>
 
 <p align="center">
-  <em>The structured world model for AI agents. Reproducible counterfactual simulations from JSON.</em>
+  <em>From prompt to world model to forked futures. Structured counterfactual simulations for AI agents.</em>
 </p>
 
 <p align="center">
@@ -27,13 +27,15 @@
 
 ## What paracosm is
 
-A JSON file describes a world. A leader with a HEXACO personality profile runs it. A deterministic kernel drives state, time, and randomness. An LLM generates events, specialist analyses, and the leader's decisions. Specialists can forge new computational tools at runtime inside a V8 sandbox; an LLM judge approves each forge before it enters the decision pipeline. The kernel applies consequences. Personality traits drift. One turn ends, the next begins.
+Paracosm starts from a prompt, brief, URL, or hand-written scenario draft; every path compiles down to an LLM-readable world contract before simulation. The durable contract is still JSON: a typed `ScenarioPackage` with five state bags, labels, departments, metrics, setup defaults, and generated hooks. A leader with a HEXACO personality profile runs that world. A deterministic kernel drives state, time, and randomness. An LLM generates events, specialist analyses, and the leader's decisions. Specialists can forge new computational tools at runtime inside a V8 sandbox; an LLM judge approves each forge before it enters the decision pipeline. The kernel applies consequences. Personality traits drift. One turn ends, the next begins.
+
+**JSON is the contract, not the product boundary.** Today, `compileScenario()` accepts a scenario JSON draft and can ground it with `seedText` or `seedUrl`. The next API layer should be a one-call prompt/document wrapper that asks an LLM to propose that same JSON contract, validates it, then compiles and runs it. It should not bypass the schema, the kernel, or the artifact.
 
 **Same seed. Different leader. Different world.**
 
-Two runs against an identical seed, starting from the same JSON, produce measurably divergent trajectories when you swap one variable: the leader's personality. The kernel's side is reproducible. The divergence comes from the LLM stages reading HEXACO profiles and deciding differently. That structural contrast is the product.
+Two runs against an identical seed, starting from the same compiled world contract, produce measurably divergent trajectories when you swap one variable: the leader's personality. The kernel's side is reproducible. The divergence comes from the LLM stages reading HEXACO profiles and deciding differently. That structural contrast is the product.
 
-Paracosm is a **structured world model** in the sense of [Xing 2025](https://arxiv.org/abs/2507.05169) and the [ACM CSUR 2025 world-model survey](https://dl.acm.org/doi/full/10.1145/3746449): a simulator for *actionable possibilities*, not a video generator. It is also a **counterfactual world simulation model** ([Kirfel et al, 2025](https://link.springer.com/article/10.1007/s43681-025-00718-4)): a substrate for replaying an event with one variable changed and surfacing the effect. Full taxonomy mapping in [`docs/positioning/world-model-mapping.md`](docs/positioning/world-model-mapping.md).
+Paracosm is a **structured world model** in the sense of [Xing 2025](https://arxiv.org/abs/2507.05169) and the [ACM CSUR 2025 world-model survey](https://dl.acm.org/doi/full/10.1145/3746449): a simulator for *actionable possibilities*, not a video generator. It is also a **counterfactual world simulation model** ([Kirfel et al, 2025](https://link.springer.com/article/10.1007/s43681-025-00718-4)): a substrate for replaying an event with one variable changed and surfacing the effect. The closest LLM-world-model implementation anchor is [Yang et al, 2026](https://openreview.net/forum?id=XmYCERErcD), which evaluates LLM-based world models through policy verification, action proposal, and policy planning. Paracosm takes the safe product version of that idea: externalize the world into schema, citations, tools, snapshots, and seeded transitions, then let the LLM reason over that structure. Full taxonomy mapping in [`docs/positioning/world-model-mapping.md`](docs/positioning/world-model-mapping.md).
 
 ### Not these things
 
@@ -47,7 +49,7 @@ Leaders can be colony commanders, CEOs, generals, ship captains, department head
 
 ### Counterfactual simulations with `WorldModel.fork()`
 
-The CWSM positioning is operationalized through `WorldModel.fork()`: run a simulation with snapshots enabled, then branch at any past turn with a different leader or seed, and compare.
+The CWSM positioning is operationalized through `WorldModel.fork()`: run a simulation with snapshots enabled, then branch at any past turn with a different leader or seed, and compare. On resumed runs, `maxTurns` remains the absolute final turn index. To run three additional turns from turn 3, pass `maxTurns: 6`.
 
 ```typescript
 import { WorldModel } from 'paracosm/world-model';
@@ -64,7 +66,7 @@ const trunk = await wm.simulate(visionaryLeader, {
 // the forked kernel resumes from the captured state.
 const branch = await (await wm.forkFromArtifact(trunk, 3)).simulate(
   pragmatistLeader,
-  { maxTurns: 3, seed: 42 },
+  { maxTurns: 6, seed: 42 },
 );
 
 console.log(trunk.metadata.runId);        // parent run-id
@@ -74,7 +76,48 @@ console.log(trunk.fingerprint, branch.fingerprint); // divergent futures from th
 
 The kernel round-trips through `JSON.stringify`, so snapshots persist to disk cleanly for later replay or audit. `captureSnapshots` defaults to `false` to keep normal artifacts lean; set it when you want fork capability.
 
-## Quickstart
+The paracosm dashboard exposes the same mechanism end-to-end. Every UI-initiated run captures snapshots by default, so the Reports tab shows a `↳ Fork at {Time} N` button on each completed turn. Clicking it opens a fork modal (leader override, optional seed, optional custom events), POSTs to `/setup` with the full parent artifact, and routes the user to a new **Branches** tab where all forks launched from the current parent accumulate as cards with per-metric deltas rendered live as each branch streams to completion.
+
+### Replay any run for audit
+
+```typescript
+const replay = await wm.replay(storedArtifact);
+console.log(replay.matches);     // true when the kernel produces byte-equal output
+console.log(replay.divergence);  // first-mismatch JSON pointer when matches=false
+```
+
+The kernel's between-turn progression hook re-runs deterministically from each recorded snapshot; LLM stages are not invoked, so replay is free and fast. Use it for regression testing (replay golden artifacts in CI) or forensic comparison (find the first kernel-state divergence between two versions of paracosm). Pillar 2 (Reproducible) becomes verifiable in code rather than promised in copy.
+
+### Subpath for digital-twin use cases
+
+```typescript
+import { DigitalTwin, type SubjectConfig, type InterventionConfig } from 'paracosm/digital-twin';
+
+const twin = await DigitalTwin.fromJson(scenarioJson);
+const artifact = await twin.simulateIntervention(subject, intervention, leader);
+```
+
+`DigitalTwin` is an alias of `WorldModel`; the subpath names the use case in the import path. The new `simulateIntervention()` sugar populates `RunArtifact.subject` and `RunArtifact.intervention` for traceability.
+
+### Quickstart: prompt or document to running simulation
+
+`WorldModel.fromPrompt` compiles a scenario from seed source material (paste, URL, or extracted PDF text), then `wm.quickstart` generates N contextual HEXACO leaders and runs them in parallel. Every prompt/document path validates against `DraftScenarioSchema` and routes into the existing `compileScenario` pipeline: the canonical `ScenarioPackage` contract is never bypassed.
+
+```typescript
+import { WorldModel } from 'paracosm/world-model';
+
+const wm = await WorldModel.fromPrompt({
+  seedText: 'Q3 board brief: the company must decide between...',
+  domainHint: 'corporate strategic decision',
+});
+
+const { leaders, artifacts } = await wm.quickstart({ leaderCount: 3 });
+artifacts.forEach((a, i) => console.log(leaders[i].name, a.fingerprint));
+```
+
+In the dashboard, the Quickstart tab is the default landing view. A user pastes a brief (or drops a PDF, or supplies a URL) and receives three streaming-live leaders plus per-card Download JSON, Copy shareable link, and Fork-in-Branches actions within a minute of first click. A curated library of 10 HEXACO archetypes is exported at `paracosm/leader-presets` for programmatic `runBatch` sweeps or Swap-leader controls in downstream UIs.
+
+## Install
 
 ```bash
 npm install paracosm      # also works: pnpm add paracosm / bun add paracosm
@@ -84,6 +127,8 @@ Paracosm ships as pure ESM with subpath exports (`paracosm/compiler`, `paracosm/
 
 ### 1. Define your world
 
+The canonical authoring contract is JSON because JSON can be validated, diffed, cached, snapshotted, and exported as schema. You can write that draft directly, or ground it with natural-language source material through `seedText` / `seedUrl` during compilation. A future prompt-only wrapper should generate this same contract first, then compile it.
+
 Every scenario declares its own vocabulary via `labels.populationNoun`
 (plural, e.g. `"colonists"` / `"crew"` / `"citizens"`) and
 `labels.settlementNoun` (singular, e.g. `"colony"` / `"habitat"` /
@@ -164,7 +209,7 @@ import { compileScenario } from 'paracosm/compiler';
 import { runSimulation } from 'paracosm/runtime';
 import worldJson from './my-world.json' with { type: 'json' };
 
-// Compile JSON into a runnable scenario (~$0.10, cached to disk)
+// Compile a typed world draft into a runnable scenario (~$0.10, cached to disk)
 const scenario = await compileScenario(worldJson, {
   provider: 'anthropic',
   model: 'claude-sonnet-4-6',
@@ -333,7 +378,7 @@ Then edit the HEXACO sliders and `instructions` fields to describe your own lead
 
 ## Scenario Compiler
 
-The compiler turns your JSON into a runnable scenario by generating TypeScript hooks via LLM calls:
+The compiler turns a typed world draft plus optional prompt/document/URL grounding into a runnable scenario by generating TypeScript hooks via LLM calls:
 
 ```bash
 npm run compile -- scenarios/submarine.json \
@@ -341,7 +386,7 @@ npm run compile -- scenarios/submarine.json \
   --no-web-search
 ```
 
-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.
+Options: `--seed-text`, `--seed-url`, `--no-web-search`, `--max-searches`. Use `--seed-text` for a pasted brief or prompt, and `--seed-url` for a report, paper, or web page. The JSON file remains the contract that gets validated and cached; seed material grounds the world before hook generation. Compiled scenarios appear in the dashboard selector. Cost is roughly $0.10 per compile, cached to disk after first generation.
 
 ### Programmatic compiler options
 
@@ -400,6 +445,26 @@ The orchestrator's `runSimulation()` returns a `cost` field with token counts, L
 
 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/`.
 
+## One-shot HTTP API: `POST /simulate`
+
+Non-SSE consumers (curl, Python integrations, third-party dashboards) can run a simulation through a plain request-response endpoint. Gated behind `PARACOSM_ENABLE_SIMULATE_ENDPOINT=true` so the hosted demo's SSE-first path stays the default; self-hosted deployments flip the flag on.
+
+```bash
+export PARACOSM_ENABLE_SIMULATE_ENDPOINT=true
+npx paracosm serve   # or bring up your own server via createMarsServer
+
+curl -s -X POST http://localhost:5188/simulate \
+  -H 'Content-Type: application/json' \
+  -H 'X-Anthropic-Key: sk-ant-...' \
+  -d '{
+    "scenario": { "id": "submarine-habitat", "labels": { "name": "Deep Ocean Habitat", "populationNoun": "crew", "settlementNoun": "habitat", "timeUnitNoun": "day" }, "setup": { "defaultTurns": 4, "defaultPopulation": 25, "defaultStartTime": 2040 }, "departments": [...], "metrics": [...] },
+    "leader": { "name": "Captain Reyes", "archetype": "The Pragmatist", "unit": "Deep Ocean Habitat", "hexaco": { "openness": 0.4, "conscientiousness": 0.9, "extraversion": 0.3, "agreeableness": 0.6, "emotionality": 0.5, "honestyHumility": 0.8 }, "instructions": "" },
+    "options": { "maxTurns": 4, "seed": 42, "captureSnapshots": true, "provider": "anthropic" }
+  }' | jq '.artifact.fingerprint'
+```
+
+The request body accepts either a pre-compiled `ScenarioPackage` (has `.hooks`) or a raw scenario draft the compiler accepts; raw drafts are auto-compiled server-side with optional `options.seedText` / `options.seedUrl` grounding. The response body is `{ artifact: RunArtifact, scenario: ScenarioPackage, durationMs: number }`. Rate limiting shares the same IP bucket as `/setup`; request-body size uses the same 5 MiB cap.
+
 ## Programmatic API
 
 Everything the dashboard does is also available as library calls. The exports fall into five buckets:
@@ -693,7 +758,7 @@ Each turn represents a configurable time period. Mars and Lunar tick in years (M
 3. DEPARTMENT ANALYSIS   All active departments analyze the event in parallel.
                          Each department head (promoted at turn 0) uses their
                          personality and tools. Departments can forge new
-                         computational tools at runtime (sandboxed V8, LLM-judged).
+                         computational tools at runtime (hardened node:vm, LLM-judged).
 
 4. COMMANDER DECISION    Reads all department reports. Selects an option.
                          Personality shapes risk tolerance and priority weighting.
@@ -729,7 +794,7 @@ Department heads are LLM agents with domain-specific instructions, access to res
 
 - Analyze the event against their department's research knowledge
 - Cite relevant scientific literature (DOI-linked)
-- Forge computational tools (e.g., a radiation dose calculator) in a sandboxed V8 environment
+- Forge computational tools (e.g., a radiation dose calculator) in a hardened node:vm sandbox
 - An LLM judge reviews each tool for safety and correctness
 - Produce a structured report: summary, risks, recommended actions, proposed colony state changes
 
@@ -741,7 +806,7 @@ The commander sees all department reports and makes a decision. Different comman
 src/
   engine/         the npm package
     core/         deterministic kernel (RNG, state, progression, personality drift)
-    compiler/     JSON -> ScenarioPackage compiler
+    compiler/     scenario draft + source grounding -> ScenarioPackage compiler
     mars/         Mars Genesis scenario
     lunar/        Lunar Outpost scenario
 
@@ -782,7 +847,7 @@ Paracosm uses [AgentOS](https://agentos.sh) for agent orchestration, LLM calls,
 |------------|----------|
 | `agent()` | Commander, department, and Event Director agents |
 | `generateText()` | LLM calls for event generation and tool evaluation |
-| `EmergentCapabilityEngine` | Runtime tool forging in sandboxed V8 |
+| `EmergentCapabilityEngine` | Runtime tool forging in a hardened node:vm sandbox |
 | `EmergentJudge` | LLM-as-judge safety review of forged tools |
 
 ## Links

package/dist/cli/compile.d.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * CLI: Compile a scenario JSON into a runnable ScenarioPackage.
+ * CLI: Compile a scenario JSON draft into a runnable ScenarioPackage.
  *
  * Usage:
  *   npx tsx src/cli/compile.ts scenarios/submarine.json

package/dist/cli/compile.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * CLI: Compile a scenario JSON into a runnable ScenarioPackage.
+ * CLI: Compile a scenario JSON draft into a runnable ScenarioPackage.
  *
  * Usage:
  *   npx tsx src/cli/compile.ts scenarios/submarine.json
@@ -16,7 +16,7 @@ async function main() {
     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
+paracosm compile - Generate runtime hooks for a scenario JSON draft
 
 Usage:
   npx tsx src/cli/compile.ts <scenario.json> [options]
@@ -26,8 +26,8 @@ Options:
   --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
+  --seed-text <text>      Ground the scenario with an inline prompt, brief, or document
+  --seed-url <url>        Ground the scenario with 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

package/dist/cli/fetch-seed-url.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Shared URL fetcher for CLI init + dashboard quickstart flows.
+ *
+ * AgentOS exposes WebSearchService from the `@framers/agentos/web-search`
+ * subpath. The package root does not export it, and the service is a
+ * search API rather than a single-URL scraper. This helper uses the real
+ * search API when provider keys are configured, then falls back to direct
+ * text/HTML fetch for ordinary public URLs.
+ *
+ * @module paracosm/cli/fetch-seed-url
+ */
+export interface FetchedSeedUrl {
+    text: string;
+    title: string;
+    sourceUrl: string;
+}
+export interface WebSearchResultLike {
+    url: string;
+    title: string;
+    snippet: string;
+    content?: string;
+}
+export interface WebSearchClient {
+    registerProvider: (provider: any) => void;
+    hasProviders: () => boolean;
+    search: (query: string, options?: {
+        maxResults?: number;
+        rerank?: boolean;
+    }) => Promise<WebSearchResultLike[]>;
+}
+export type WebSearchServiceCtor = new (opts?: any) => WebSearchClient;
+export type WebSearchProviderCtor = new (apiKey: string) => unknown;
+export interface WebSearchModule {
+    WebSearchService: WebSearchServiceCtor;
+    FirecrawlProvider: WebSearchProviderCtor;
+    TavilyProvider: WebSearchProviderCtor;
+    SerperProvider: WebSearchProviderCtor;
+    BraveProvider: WebSearchProviderCtor;
+}
+export type WebSearchImporter = () => Promise<WebSearchModule>;
+export interface FetchSeedFromUrlOptions {
+    importWebSearch?: WebSearchImporter;
+    env?: NodeJS.ProcessEnv | Record<string, string | undefined>;
+    fetchImpl?: typeof fetch;
+}
+export declare function loadWebSearchModule(importWebSearch?: WebSearchImporter): Promise<WebSearchModule>;
+export declare function fetchSeedFromUrl(url: string, options?: FetchSeedFromUrlOptions): Promise<FetchedSeedUrl>;
+//# sourceMappingURL=fetch-seed-url.d.ts.map

package/dist/cli/fetch-seed-url.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch-seed-url.d.ts","sourceRoot":"","sources":["../../src/cli/fetch-seed-url.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,mBAAmB;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,eAAe;IAC9B,gBAAgB,EAAE,CAAC,QAAQ,EAAE,GAAG,KAAK,IAAI,CAAC;IAC1C,YAAY,EAAE,MAAM,OAAO,CAAC;IAC5B,MAAM,EAAE,CACN,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,KAChD,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAAC;CACrC;AAED,MAAM,MAAM,oBAAoB,GAAG,KAAK,IAAI,CAAC,EAAE,GAAG,KAAK,eAAe,CAAC;AACvE,MAAM,MAAM,qBAAqB,GAAG,KAAK,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC;AAEpE,MAAM,WAAW,eAAe;IAC9B,gBAAgB,EAAE,oBAAoB,CAAC;IACvC,iBAAiB,EAAE,qBAAqB,CAAC;IACzC,cAAc,EAAE,qBAAqB,CAAC;IACtC,cAAc,EAAE,qBAAqB,CAAC;IACtC,aAAa,EAAE,qBAAqB,CAAC;CACtC;AAED,MAAM,MAAM,iBAAiB,GAAG,MAAM,OAAO,CAAC,eAAe,CAAC,CAAC;AAE/D,MAAM,WAAW,uBAAuB;IACtC,eAAe,CAAC,EAAE,iBAAiB,CAAC;IACpC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IAC7D,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAED,wBAAsB,mBAAmB,CACvC,eAAe,GAAE,iBAA+D,GAC/E,OAAO,CAAC,eAAe,CAAC,CAE1B;AAiGD,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,cAAc,CAAC,CASzB"}

package/dist/cli/fetch-seed-url.js

@@ -0,0 +1,109 @@
+/**
+ * Shared URL fetcher for CLI init + dashboard quickstart flows.
+ *
+ * AgentOS exposes WebSearchService from the `@framers/agentos/web-search`
+ * subpath. The package root does not export it, and the service is a
+ * search API rather than a single-URL scraper. This helper uses the real
+ * search API when provider keys are configured, then falls back to direct
+ * text/HTML fetch for ordinary public URLs.
+ *
+ * @module paracosm/cli/fetch-seed-url
+ */
+export async function loadWebSearchModule(importWebSearch = () => import('@framers/agentos/web-search')) {
+    return importWebSearch();
+}
+function registerConfiguredProviders(service, mod, env) {
+    if (env.FIRECRAWL_API_KEY)
+        service.registerProvider(new mod.FirecrawlProvider(env.FIRECRAWL_API_KEY));
+    if (env.TAVILY_API_KEY)
+        service.registerProvider(new mod.TavilyProvider(env.TAVILY_API_KEY));
+    if (env.SERPER_API_KEY)
+        service.registerProvider(new mod.SerperProvider(env.SERPER_API_KEY));
+    if (env.BRAVE_API_KEY)
+        service.registerProvider(new mod.BraveProvider(env.BRAVE_API_KEY));
+}
+function normalizeUrlForCompare(raw) {
+    try {
+        const url = new URL(raw);
+        url.hash = '';
+        return url.toString().replace(/\/$/, '');
+    }
+    catch {
+        return raw.replace(/\/$/, '');
+    }
+}
+async function fetchViaAgentOSSearch(url, options) {
+    const mod = await loadWebSearchModule(options.importWebSearch);
+    const service = new mod.WebSearchService({ maxResults: 5 });
+    registerConfiguredProviders(service, mod, options.env ?? process.env);
+    if (!service.hasProviders())
+        return null;
+    const results = await service.search(url, { maxResults: 5, rerank: false });
+    if (results.length === 0)
+        return null;
+    const wanted = normalizeUrlForCompare(url);
+    const exact = results.find((result) => normalizeUrlForCompare(result.url) === wanted);
+    const withContent = results.find((result) => typeof result.content === 'string' && result.content.trim().length > 0);
+    const result = exact ?? withContent ?? results[0];
+    const text = (result.content || result.snippet || '').trim();
+    if (!text)
+        return null;
+    return {
+        text,
+        title: result.title || '',
+        sourceUrl: url,
+    };
+}
+function decodeBasicHtmlEntities(text) {
+    return text
+        .replace(/ /g, ' ')
+        .replace(/&/g, '&')
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&quot;/g, '"')
+        .replace(/&#39;/g, "'");
+}
+function extractTitleFromHtml(html) {
+    const match = html.match(/<title[^>]*>([\s\S]*?)<\/title>/i);
+    return match ? decodeBasicHtmlEntities(match[1].replace(/\s+/g, ' ').trim()) : '';
+}
+function stripHtmlToText(html) {
+    return decodeBasicHtmlEntities(html
+        .replace(/<head[\s\S]*?<\/head>/gi, ' ')
+        .replace(/<script[\s\S]*?<\/script>/gi, ' ')
+        .replace(/<style[\s\S]*?<\/style>/gi, ' ')
+        .replace(/<noscript[\s\S]*?<\/noscript>/gi, ' ')
+        .replace(/<[^>]+>/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim());
+}
+async function fetchDirectly(url, fetchImpl = fetch) {
+    const res = await fetchImpl(url, {
+        headers: { Accept: 'text/html,text/plain,application/xhtml+xml;q=0.9,*/*;q=0.1' },
+        signal: AbortSignal.timeout(15_000),
+    });
+    if (!res.ok) {
+        throw new Error(`HTTP ${res.status}`);
+    }
+    const contentType = res.headers.get('content-type') || '';
+    const raw = await res.text();
+    const isHtml = /\bhtml\b/i.test(contentType) || /<html[\s>]/i.test(raw);
+    return {
+        text: isHtml ? stripHtmlToText(raw) : raw.trim(),
+        title: isHtml ? extractTitleFromHtml(raw) : '',
+        sourceUrl: url,
+    };
+}
+export async function fetchSeedFromUrl(url, options = {}) {
+    try {
+        const viaSearch = await fetchViaAgentOSSearch(url, options);
+        if (viaSearch)
+            return viaSearch;
+    }
+    catch {
+        // Fall through to direct fetch. Some AgentOS providers are search-only
+        // and may reject exact URL lookups; public URLs can still be fetched.
+    }
+    return fetchDirectly(url, options.fetchImpl);
+}
+//# sourceMappingURL=fetch-seed-url.js.map

package/dist/cli/fetch-seed-url.js.map

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

package/dist/cli/fork-preconditions.d.ts

@@ -0,0 +1,17 @@
+import { type RunArtifact } from '../engine/schema/index.js';
+export type ForkPreconditionResult = {
+    ok: true;
+    parentArtifact: RunArtifact;
+} | {
+    ok: false;
+    statusCode: 400 | 409;
+    error: string;
+    issues?: string[];
+};
+export declare function validateForkSetupPreconditions(input: {
+    parentArtifact: unknown;
+    atTurn: number;
+    activeScenarioId: string;
+    activeRunInProgress: boolean;
+}): ForkPreconditionResult;
+//# sourceMappingURL=fork-preconditions.d.ts.map

package/dist/cli/fork-preconditions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fork-preconditions.d.ts","sourceRoot":"","sources":["../../src/cli/fork-preconditions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,KAAK,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAEhF,MAAM,MAAM,sBAAsB,GAC9B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,cAAc,EAAE,WAAW,CAAA;CAAE,GACzC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,UAAU,EAAE,GAAG,GAAG,GAAG,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAE3E,wBAAgB,8BAA8B,CAAC,KAAK,EAAE;IACpD,cAAc,EAAE,OAAO,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,gBAAgB,EAAE,MAAM,CAAC;IACzB,mBAAmB,EAAE,OAAO,CAAC;CAC9B,GAAG,sBAAsB,CAoDzB"}

package/dist/cli/fork-preconditions.js

@@ -0,0 +1,51 @@
+import { RunArtifactSchema } from '../engine/schema/index.js';
+export function validateForkSetupPreconditions(input) {
+    const parentResult = RunArtifactSchema.safeParse(input.parentArtifact);
+    if (!parentResult.success) {
+        return {
+            ok: false,
+            statusCode: 400,
+            error: 'Fork parent artifact is not a valid RunArtifact.',
+            issues: parentResult.error.issues.slice(0, 5).map(issue => issue.message),
+        };
+    }
+    const parent = parentResult.data;
+    const parentScenarioId = parent.metadata.scenario.id;
+    if (parentScenarioId !== input.activeScenarioId) {
+        return {
+            ok: false,
+            statusCode: 400,
+            error: `Fork parent scenario '${parentScenarioId}' does not match active scenario '${input.activeScenarioId}'. Cross-scenario forks are not supported.`,
+        };
+    }
+    const snapshots = parent.scenarioExtensions
+        ?.kernelSnapshotsPerTurn;
+    if (!Array.isArray(snapshots) || snapshots.length === 0) {
+        return {
+            ok: false,
+            statusCode: 400,
+            error: 'Fork parent has no embedded kernel snapshots. Re-run the parent simulation with `captureSnapshots: true` to enable forking.',
+        };
+    }
+    const hasRequestedSnapshot = snapshots.some(snapshot => {
+        if (!snapshot || typeof snapshot !== 'object')
+            return false;
+        return snapshot.turn === input.atTurn;
+    });
+    if (!hasRequestedSnapshot) {
+        return {
+            ok: false,
+            statusCode: 400,
+            error: `Fork parent has no kernel snapshot for turn ${input.atTurn}.`,
+        };
+    }
+    if (input.activeRunInProgress) {
+        return {
+            ok: false,
+            statusCode: 409,
+            error: 'Cannot fork while another simulation is running. Wait for the current run to finish or stop it first.',
+        };
+    }
+    return { ok: true, parentArtifact: parent };
+}
+//# sourceMappingURL=fork-preconditions.js.map

package/dist/cli/fork-preconditions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fork-preconditions.js","sourceRoot":"","sources":["../../src/cli/fork-preconditions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAoB,MAAM,2BAA2B,CAAC;AAMhF,MAAM,UAAU,8BAA8B,CAAC,KAK9C;IACC,MAAM,YAAY,GAAG,iBAAiB,CAAC,SAAS,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;IACvE,IAAI,CAAC,YAAY,CAAC,OAAO,EAAE,CAAC;QAC1B,OAAO;YACL,EAAE,EAAE,KAAK;YACT,UAAU,EAAE,GAAG;YACf,KAAK,EAAE,kDAAkD;YACzD,MAAM,EAAE,YAAY,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC;SAC1E,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,YAAY,CAAC,IAAI,CAAC;IACjC,MAAM,gBAAgB,GAAG,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;IACrD,IAAI,gBAAgB,KAAK,KAAK,CAAC,gBAAgB,EAAE,CAAC;QAChD,OAAO;YACL,EAAE,EAAE,KAAK;YACT,UAAU,EAAE,GAAG;YACf,KAAK,EAAE,yBAAyB,gBAAgB,qCAAqC,KAAK,CAAC,gBAAgB,4CAA4C;SACxJ,CAAC;IACJ,CAAC;IAED,MAAM,SAAS,GAAI,MAAM,CAAC,kBAAyE;QACjG,EAAE,sBAAsB,CAAC;IAC3B,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxD,OAAO;YACL,EAAE,EAAE,KAAK;YACT,UAAU,EAAE,GAAG;YACf,KAAK,EAAE,6HAA6H;SACrI,CAAC;IACJ,CAAC;IAED,MAAM,oBAAoB,GAAG,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE;QACrD,IAAI,CAAC,QAAQ,IAAI,OAAO,QAAQ,KAAK,QAAQ;YAAE,OAAO,KAAK,CAAC;QAC5D,OAAQ,QAA+B,CAAC,IAAI,KAAK,KAAK,CAAC,MAAM,CAAC;IAChE,CAAC,CAAC,CAAC;IACH,IAAI,CAAC,oBAAoB,EAAE,CAAC;QAC1B,OAAO;YACL,EAAE,EAAE,KAAK;YACT,UAAU,EAAE,GAAG;YACf,KAAK,EAAE,+CAA+C,KAAK,CAAC,MAAM,GAAG;SACtE,CAAC;IACJ,CAAC;IAED,IAAI,KAAK,CAAC,mBAAmB,EAAE,CAAC;QAC9B,OAAO;YACL,EAAE,EAAE,KAAK;YACT,UAAU,EAAE,GAAG;YACf,KAAK,EAAE,uGAAuG;SAC/G,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,EAAE,CAAC;AAC9C,CAAC"}

package/dist/cli/init-templates.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Pure renderer functions for the files emitted by `paracosm init`.
+ * Each function takes a small input record and returns the file contents
+ * as a string. No I/O, no dependencies on the caller's environment.
+ *
+ * Kept separate from init.ts so the renderers snapshot-test trivially.
+ *
+ * @module paracosm/cli/init-templates
+ */
+export interface PackageJsonInput {
+    name: string;
+    paracosmVersion: string;
+}
+export declare function renderPackageJson(input: PackageJsonInput): string;
+export type SimulationMode = 'turn-loop' | 'batch-trajectory' | 'batch-point';
+/**
+ * Render the entry script for a paracosm-init scaffolded project.
+ *
+ * The script imports `runSimulation` from `paracosm/runtime` and runs the
+ * leader at index 0 against a turn-loop simulation. Mode is intentionally
+ * NOT a runtime input: it is a property of the produced
+ * `RunArtifact.metadata`, surfaced after the run completes. Batch-trajectory
+ * and batch-point modes are produced by `runBatch` (different entry point,
+ * different config shape); a future spec adds a separate `renderRunMjsBatch`
+ * for those modes.
+ */
+export declare function renderRunMjs(): string;
+export interface ReadmeInput {
+    name: string;
+    domain: string;
+    mode: SimulationMode;
+    leaders: number;
+}
+export declare function renderReadme(input: ReadmeInput): string;
+export declare function renderEnvExample(): string;
+export declare function renderGitignore(): string;
+/**
+ * Slug-normalize a project name. Lowercase ASCII, dashes between words,
+ * strips everything else, max 50 chars. If empty after stripping,
+ * returns 'paracosm-app'.
+ */
+export declare function slugifyName(raw: string): string;
+//# sourceMappingURL=init-templates.d.ts.map

package/dist/cli/init-templates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init-templates.d.ts","sourceRoot":"","sources":["../../src/cli/init-templates.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,gBAAgB,GAAG,MAAM,CAcjE;AAED,MAAM,MAAM,cAAc,GAAG,WAAW,GAAG,kBAAkB,GAAG,aAAa,CAAC;AAE9E;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAqCrC;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,cAAc,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CA8BvD;AAED,wBAAgB,gBAAgB,IAAI,MAAM,CAWzC;AAED,wBAAgB,eAAe,IAAI,MAAM,CAQxC;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAS/C"}