paracosm 0.4.377 → 0.4.378

package/README.md

@@ -160,7 +160,18 @@ const results = await Promise.all(
       scenario,
       maxTurns: 8,
       seed: 42,
-      onEvent(e) { console.log(leader.name, e.type, e.data?.title); },
+      // ~15 event types fire per turn (dept_start, forge_attempt, drift…).
+      // Filter to the ones that tell the story end-to-end so the console
+      // stays readable. See the SimEvent type for the full list.
+      onEvent(e) {
+        const turn = e.turn ?? (e.data?.turn as number | undefined);
+        if (e.type === 'event_start')
+          console.log(leader.name, `T${turn}`, 'event:', e.data?.title);
+        else if (e.type === 'outcome')
+          console.log(leader.name, `T${turn}`, e.data?.outcome, `(${e.data?.category})`);
+        else if (e.type === 'turn_done')
+          console.log(leader.name, `T${turn}`, 'complete');
+      },
     })
   )
 );
@@ -374,6 +385,18 @@ try {
 
 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.
 
+### Where run output lands
+
+Every finished run writes a JSON snapshot to `<cwd>/output/v3-<archetype>-<timestamp>.json` — the same payload `runSimulation` returns, persisted so you can diff runs, reload them into the dashboard, or feed them into downstream tooling. Set `PARACOSM_OUTPUT_DIR` to redirect (absolute path, or relative to cwd). The directory is created on first write if it doesn't exist.
+
+```bash
+# Default: ./output/v3-the-pragmatist-2026-04-21T16-02-41-550Z.json
+bun src/index.ts
+
+# Custom location
+PARACOSM_OUTPUT_DIR=./artifacts/run-001 bun src/index.ts
+```
+
 ## 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.

package/dist/runtime/output-writer.d.ts

@@ -9,9 +9,10 @@
  * @module paracosm/runtime/output-writer
  */
 /**
- * Write a simulation result payload to `<repo>/output/v3-<tag>-<ts>.json`
- * and log a one-screen summary to stdout. Ensures the output dir exists
- * before writing. Returns the absolute path of the written file.
+ * Write a simulation result payload to `<cwd>/output/v3-<tag>-<ts>.json`
+ * (or `$PARACOSM_OUTPUT_DIR/...`) and log a one-screen summary to stdout.
+ * Ensures the output dir exists before writing. Returns the absolute
+ * path of the written file.
  *
  * The tag slot comes from the leader's archetype so side-by-side runs
  * get distinguishable filenames even when they start in the same

package/dist/runtime/output-writer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"output-writer.d.ts","sourceRoot":"","sources":["../../src/runtime/output-writer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAQH;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE;IACN,cAAc,EAAE,MAAM,CAAC;IACvB,gBAAgB,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE;QAAE,MAAM,EAAE;YAAE,UAAU,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,CAAC;CAChE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC3B,IAAI,EAAE;IACJ,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;CACpC,GACA,MAAM,CAiBR"}
+{"version":3,"file":"output-writer.d.ts","sourceRoot":"","sources":["../../src/runtime/output-writer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAkCH;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE;IACN,cAAc,EAAE,MAAM,CAAC;IACvB,gBAAgB,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE;QAAE,MAAM,EAAE;YAAE,UAAU,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,CAAC;CAChE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC3B,IAAI,EAAE;IACJ,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;CACpC,GACA,MAAM,CAiBR"}

package/dist/runtime/output-writer.js

@@ -9,20 +9,47 @@
  * @module paracosm/runtime/output-writer
  */
 import { mkdirSync, writeFileSync } from 'node:fs';
-import { resolve, dirname } from 'node:path';
-import { fileURLToPath } from 'node:url';
-const __dirname = dirname(fileURLToPath(import.meta.url));
+import { resolve } from 'node:path';
 /**
- * Write a simulation result payload to `<repo>/output/v3-<tag>-<ts>.json`
- * and log a one-screen summary to stdout. Ensures the output dir exists
- * before writing. Returns the absolute path of the written file.
+ * Resolve the output directory to write run snapshots into.
+ *
+ * Priority order:
+ *   1. `PARACOSM_OUTPUT_DIR` env var — absolute or cwd-relative, lets
+ *      hosting / CI write outside the project tree without a code change.
+ *   2. `<cwd>/output` — the user's current working directory when they
+ *      invoked the process. This is the right default both for the
+ *      in-repo CLI (`npm run smoke` from the paracosm repo root writes
+ *      to `<repo>/output`) AND for library consumers (`bun src/index.ts`
+ *      from their project root writes to `<their project>/output`).
+ *
+ * The previous default resolved `output/` relative to the installed
+ * module location (`__dirname/../..`). That landed inside the package
+ * install directory — fine during local development of paracosm itself,
+ * but on any downstream consumer it wrote to
+ * `node_modules/paracosm/output/` (or worse, a pnpm virtual-store path
+ * like `node_modules/.pnpm/paracosm@x.y.z_hash/node_modules/paracosm/output/`),
+ * which is impossible to find, invisible to git, and gets nuked on
+ * `rm -rf node_modules`.
+ */
+function resolveOutputDir() {
+    const override = process.env.PARACOSM_OUTPUT_DIR;
+    if (override && override.trim().length > 0) {
+        return resolve(process.cwd(), override);
+    }
+    return resolve(process.cwd(), 'output');
+}
+/**
+ * Write a simulation result payload to `<cwd>/output/v3-<tag>-<ts>.json`
+ * (or `$PARACOSM_OUTPUT_DIR/...`) and log a one-screen summary to stdout.
+ * Ensures the output dir exists before writing. Returns the absolute
+ * path of the written file.
  *
  * The tag slot comes from the leader's archetype so side-by-side runs
  * get distinguishable filenames even when they start in the same
  * millisecond (e.g. `v3-the-engineer-...` vs `v3-the-visionary-...`).
  */
 export function writeRunOutput(output, args) {
-    const outDir = resolve(__dirname, '..', '..', 'output');
+    const outDir = resolveOutputDir();
     mkdirSync(outDir, { recursive: true });
     const ts = new Date().toISOString().replace(/[:.]/g, '-');
     const tag = args.leaderArchetype.toLowerCase().replace(/\s+/g, '-');

package/dist/runtime/output-writer.js.map

@@ -1 +1 @@
-{"version":3,"file":"output-writer.js","sourceRoot":"","sources":["../../src/runtime/output-writer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAE1D;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAC5B,MAI2B,EAC3B,IAKC;IAED,MAAM,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;IACxD,SAAS,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACvC,MAAM,EAAE,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;IAC1D,MAAM,GAAG,GAAG,IAAI,CAAC,eAAe,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACpE,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,EAAE,OAAO,CAAC,CAAC;IACrD,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IAErD,OAAO,CAAC,GAAG,CAAC,KAAK,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IACnC,OAAO,CAAC,GAAG,CAAC,gBAAgB,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC;IAC/C,OAAO,CAAC,GAAG,CAAC,aAAa,IAAI,EAAE,CAAC,CAAC;IACjC,OAAO,CAAC,GAAG,CAAC,YAAY,IAAI,CAAC,KAAK,iBAAiB,MAAM,CAAC,cAAc,aAAa,MAAM,CAAC,gBAAgB,EAAE,CAAC,CAAC;IAChH,OAAO,CAAC,GAAG,CAAC,gBAAgB,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,UAAU,aAAa,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,MAAM,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;IAClI,OAAO,CAAC,GAAG,CAAC,iBAAiB,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;IAC9D,OAAO,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC;IAEnC,OAAO,IAAI,CAAC;AACd,CAAC"}
+{"version":3,"file":"output-writer.js","sourceRoot":"","sources":["../../src/runtime/output-writer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,SAAS,gBAAgB;IACvB,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC;IACjD,IAAI,QAAQ,IAAI,QAAQ,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC3C,OAAO,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,QAAQ,CAAC,CAAC;IAC1C,CAAC;IACD,OAAO,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,QAAQ,CAAC,CAAC;AAC1C,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,cAAc,CAC5B,MAI2B,EAC3B,IAKC;IAED,MAAM,MAAM,GAAG,gBAAgB,EAAE,CAAC;IAClC,SAAS,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACvC,MAAM,EAAE,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;IAC1D,MAAM,GAAG,GAAG,IAAI,CAAC,eAAe,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACpE,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,EAAE,OAAO,CAAC,CAAC;IACrD,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IAErD,OAAO,CAAC,GAAG,CAAC,KAAK,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IACnC,OAAO,CAAC,GAAG,CAAC,gBAAgB,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC;IAC/C,OAAO,CAAC,GAAG,CAAC,aAAa,IAAI,EAAE,CAAC,CAAC;IACjC,OAAO,CAAC,GAAG,CAAC,YAAY,IAAI,CAAC,KAAK,iBAAiB,MAAM,CAAC,cAAc,aAAa,MAAM,CAAC,gBAAgB,EAAE,CAAC,CAAC;IAChH,OAAO,CAAC,GAAG,CAAC,gBAAgB,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,UAAU,aAAa,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,MAAM,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;IAClI,OAAO,CAAC,GAAG,CAAC,iBAAiB,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;IAC9D,OAAO,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC;IAEnC,OAAO,IAAI,CAAC;AACd,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paracosm",
-  "version": "0.4.377",
+  "version": "0.4.378",
   "description": "AI agent swarm simulation engine with emergent crises, runtime tool forging, HEXACO personality drift, and deterministic kernels. Built on AgentOS.",
   "type": "module",
   "main": "dist/engine/index.js",