paracosm 0.4.146 → 0.4.148

package/dist/src/runtime/orchestrator.js

@@ -3,8 +3,10 @@ import { resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { webSearchTool, createEmergentEngine, createCallForgedTool, wrapForgeTool, } from './emergent-setup.js';
 import { humanizeToolName, parseDeptReport, parseCmdDecision, emptyReport, emptyDecision, decisionToPolicy, } from './parsers.js';
-import { buildPriceForSite, getDefaultPricing } from './pricing.js';
-import { buildAvailableToolsBlock } from './tool-ledger.js';
+import { createCostTracker } from './cost-tracker.js';
+import { buildPersonalityCue, buildCommanderBootstrap, runDepartmentPromotions, } from './commander-setup.js';
+import { buildAvailableToolsBlock, buildForgedToolbox } from './tool-ledger.js';
+import { buildCitationCatalog } from './citations-catalog.js';
 import { SeededRng } from '../engine/core/rng.js';
 import { classifyOutcome, classifyOutcomeById } from '../engine/core/progression.js';
 import { SimulationKernel } from '../engine/core/kernel.js';
@@ -16,7 +18,7 @@ import { EventDirector } from './director.js';
 import { generateAgentReactions } from './agent-reactions.js';
 import { recordReactionMemory, consolidateMemory, updateRelationshipsFromReactions } from './agent-memory.js';
 import { DEFAULT_EXECUTION, resolveSimulationModels, } from '../cli/sim-config.js';
-import { applyCustomEventToCrisis, buildPromotionPrompt, buildYearSchedule } from './runtime-helpers.js';
+import { applyCustomEventToCrisis, buildYearSchedule } from './runtime-helpers.js';
 import { classifyProviderError, shouldAbortRun } from './provider-errors.js';
 import { EffectRegistry } from '../engine/effect-registry.js';
 import { marsScenario } from '../engine/mars/index.js';
@@ -30,128 +32,20 @@ export async function runSimulation(leader, keyPersonnel, opts = {}) {
     const sid = `${sc.labels.shortName}-v2-${leader.archetype.toLowerCase().replace(/\s+/g, '-')}`;
     const modelConfig = resolveSimulationModels(provider, opts.models);
     // Cost tracking: accumulate token usage and estimated cost across all LLM calls
-    let totalTokens = 0;
-    let totalCostUSD = 0;
-    let llmCalls = 0;
-    /**
-     * Run-wide prompt-cache accounting. Tracks cache-tier token counts
-     * returned by AgentOS on Anthropic calls (and OpenAI's automatic
-     * caching when it eventually exposes them). Surfaces as proof that
-     * the prompt-caching wiring actually hit — a run with `cacheReadTokens
-     * = 0` despite configured cache breakpoints means caching didn't work
-     * and the reported cost is not reflecting the savings we expected.
-     *
-     * Reported via `_cost` on every SSE emit so the dashboard breakdown
-     * modal can display cache hit rate and estimated savings.
-     */
-    let cacheReadTokens = 0;
-    let cacheCreationTokens = 0;
-    const newBucket = () => ({
-        totalTokens: 0, totalCostUSD: 0, calls: 0,
-        cacheReadTokens: 0, cacheCreationTokens: 0,
-    });
-    const costBySite = {
-        director: newBucket(),
-        commander: newBucket(),
-        departments: newBucket(),
-        judge: newBucket(),
-        reactions: newBucket(),
-        other: newBucket(),
-    };
-    // Pricing comes from pricing.ts so MODEL_PRICING has one home.
-    const defaultPricing = getDefaultPricing(modelConfig);
-    const priceForSite = buildPriceForSite(modelConfig);
-    /**
-     * Record token/cost usage from a single LLM call.
-     *
-     * @param result The result object from generateText / session.send(),
-     *        which carries an optional `usage` field populated by AgentOS.
-     * @param site Which pipeline stage made the call. Used to build the
-     *        per-site cost breakdown the dashboard StatsBar can drill into.
-     *        Defaults to 'other' when a call-site isn't tagged (harmless
-     *        fallback, but tag every new call site so the breakdown stays
-     *        meaningful).
-     */
-    function trackUsage(result, site = 'other') {
-        if (!result?.usage)
-            return;
-        const tokensThisCall = result.usage.totalTokens ?? 0;
-        const callCacheRead = result.usage.cacheReadTokens ?? 0;
-        const callCacheCreate = result.usage.cacheCreationTokens ?? 0;
-        let costThisCall;
-        if (typeof result.usage.costUSD === 'number') {
-            // Provider returned a cost that already accounts for cache tiers.
-            costThisCall = result.usage.costUSD;
-        }
-        else {
-            // Fallback: compute a cache-aware estimate using commander-tier
-            // pricing as an approximation. Cache reads billed at 0.1×, cache
-            // creations at 1.25× input rate. Previous estimate ignored cache
-            // entirely so a run with heavy caching would UNDER-report the
-            // billed amount by ~10-15%.
-            const input = result.usage.promptTokens ?? 0;
-            const output = result.usage.completionTokens ?? 0;
-            costThisCall =
-                (input * defaultPricing.input / 1_000_000)
-                    + (output * defaultPricing.output / 1_000_000)
-                    + (callCacheRead * defaultPricing.input * 0.10 / 1_000_000)
-                    + (callCacheCreate * defaultPricing.input * 1.25 / 1_000_000);
-        }
-        totalTokens += tokensThisCall;
-        totalCostUSD += costThisCall;
-        llmCalls++;
-        cacheReadTokens += callCacheRead;
-        cacheCreationTokens += callCacheCreate;
-        const bucket = costBySite[site];
-        bucket.totalTokens += tokensThisCall;
-        bucket.totalCostUSD += costThisCall;
-        bucket.calls++;
-        bucket.cacheReadTokens += callCacheRead;
-        bucket.cacheCreationTokens += callCacheCreate;
-    }
+    // Cost tracker: per-site buckets + cache-aware fallback estimation.
+    // Lives in cost-tracker.ts so the math has one home and the turn loop
+    // reads as dispatch. trackUsage(result, site) is called at every LLM
+    // call site with a site tag; buildCostPayload() is called before each
+    // SSE emit so the dashboard breakdown modal sees live data.
+    const costTracker = createCostTracker(modelConfig);
+    const trackUsage = costTracker.trackUsage;
     const emit = (type, data) => {
-        // Per-site cache savings math: estimate USD saved vs a hypothetical
-        // no-caching run. Anthropic bills cache_read at 0.10x input rate
-        // (saves 0.90x) and cache_creation at 1.25x (costs +0.25x). So net
-        // savings per site = (reads × 0.90 - creates × 0.25) × inputPrice.
-        // A fresh creation on turn 1 is a net COST relative to no-cache
-        // (the run hasn't amortized the 1.25x overhead yet). By turn 3+
-        // with reads dominating, savings are substantial.
-        let runCacheSavingsUSD = 0;
-        const breakdown = {};
-        for (const [k, v] of Object.entries(costBySite)) {
-            if (v.calls > 0) {
-                const sitePricing = priceForSite(k);
-                const siteSavings = ((v.cacheReadTokens * 0.90) - (v.cacheCreationTokens * 0.25))
-                    * sitePricing.input / 1_000_000;
-                runCacheSavingsUSD += siteSavings;
-                breakdown[k] = {
-                    totalTokens: v.totalTokens,
-                    totalCostUSD: Math.round(v.totalCostUSD * 10000) / 10000,
-                    calls: v.calls,
-                    ...(v.cacheReadTokens > 0 ? { cacheReadTokens: v.cacheReadTokens } : {}),
-                    ...(v.cacheCreationTokens > 0 ? { cacheCreationTokens: v.cacheCreationTokens } : {}),
-                    ...(Math.abs(siteSavings) >= 0.0001
-                        ? { cacheSavingsUSD: Math.round(siteSavings * 10000) / 10000 }
-                        : {}),
-                };
-            }
-        }
         opts.onEvent?.({
             type,
             leader: leader.name,
             data: {
                 ...data,
-                _cost: {
-                    totalTokens,
-                    totalCostUSD: Math.round(totalCostUSD * 10000) / 10000,
-                    llmCalls,
-                    cacheReadTokens,
-                    cacheCreationTokens,
-                    /** Run-wide USD saved by prompt caching vs a no-cache run. */
-                    cacheSavingsUSD: Math.round(runCacheSavingsUSD * 10000) / 10000,
-                    breakdown,
-                },
+                _cost: costTracker.buildCostPayload(),
             },
         });
     };
@@ -263,100 +157,31 @@ export async function runSimulation(leader, keyPersonnel, opts = {}) {
         maxSteps: opts.execution?.commanderMaxSteps ?? DEFAULT_EXECUTION.commanderMaxSteps,
     });
     const cmdSess = commander.session(`${sid}-cmd`);
-    // Bootstrap commander session. The HEXACO traits passed to agent() above
-    // already shape the LLM's voice; this kickoff message reinforces that
-    // decisions should be visibly personality-driven so two extreme leaders
-    // produce visibly different timelines, not centrist convergent choices.
-    const personalityCue = (() => {
-        const h = leader.hexaco;
-        const cues = [];
-        if (h.openness > 0.7)
-            cues.push('You favor novel, untested approaches over proven ones');
-        if (h.openness < 0.3)
-            cues.push('You favor proven protocols over experiments');
-        if (h.conscientiousness > 0.7)
-            cues.push('You demand evidence and contingency plans before committing');
-        if (h.conscientiousness < 0.3)
-            cues.push('You move fast and accept ambiguity');
-        if (h.emotionality > 0.7)
-            cues.push('You weigh human cost heavily — even small mortality risks deter you');
-        if (h.emotionality < 0.3)
-            cues.push('You will accept casualties for strategic gain');
-        if (h.agreeableness < 0.4)
-            cues.push('You override department consensus when you see a better path');
-        if (h.honestyHumility < 0.4)
-            cues.push('You leverage information asymmetries when useful');
-        return cues.length ? `Your decision style: ${cues.join('. ')}.` : '';
-    })();
-    // Bootstrap the commander. This is the FIRST LLM call in the run, so if
-    // the user's API key is invalid or credits are exhausted, this is where
-    // we find out. Report it through the classifier so the dashboard banner
-    // fires before we burn compute launching a sim that has no hope of
-    // producing valid output.
+    // Bootstrap the commander with a HEXACO-derived personality cue. This
+    // is the FIRST LLM call in the run, so if the user's key is invalid
+    // or credits are exhausted, the classifier fires here before we burn
+    // compute on a run that has no hope of producing valid output.
     try {
-        trackUsage(await cmdSess.send(`You are the colony commander. You receive department reports and make strategic decisions. ` +
-            `${personalityCue} ` +
-            `Your personality MUST visibly shape your choices — do not converge on a centrist option just because ` +
-            `it sounds reasonable. If your traits push you toward the risky option, take it; if they push you toward ` +
-            `the safe option, take it. The simulation's value is in how different leaders produce different outcomes ` +
-            `from the same starting state. ` +
-            `When the crisis includes options with IDs, you MUST include selectedOptionId in your JSON response. ` +
-            `Return JSON with selectedOptionId, decision, rationale, selectedPolicies, rejectedPolicies, ` +
-            `expectedTradeoffs, watchMetricsNextTurn. Acknowledge.`), 'commander');
+        trackUsage(await cmdSess.send(buildCommanderBootstrap(buildPersonalityCue(leader.hexaco))), 'commander');
     }
     catch (err) {
         reportProviderError(err, 'commander-bootstrap');
-        // If this is a terminal provider error, `isAborted()` is now true and
-        // the turn loop below will skip all LLM work. Continue into the turn
-        // loop anyway so the normal end-of-run cleanup path runs and the user
-        // gets a proper `complete` SSE event (with the `provider_error` event
-        // already sent above).
-    }
-    // Turn 0: Commander promotes department heads from agent roster
-    console.log('  [Turn 0] Commander evaluating roster for promotions...');
-    const promotionDepts = sc.departments.map(d => d.id);
-    const roleNames = Object.fromEntries(sc.departments.map(d => [d.id, d.role]));
-    const candidateSummaries = promotionDepts.map(dept => {
-        const candidates = kernel.getCandidates(dept, 5);
-        return `## ${dept.toUpperCase()} — Top 5 Candidates:\n${candidates.map(c => {
-            const age = startYear - c.core.birthYear;
-            const h = c.hexaco;
-            return `- ${c.core.name} (${c.core.id}), age ${age}, spec: ${c.career.specialization}, O:${h.openness.toFixed(2)} C:${h.conscientiousness.toFixed(2)} E:${h.extraversion.toFixed(2)} A:${h.agreeableness.toFixed(2)} Em:${h.emotionality.toFixed(2)} HH:${h.honestyHumility.toFixed(2)}`;
-        }).join('\n')}`;
-    }).join('\n\n');
-    const promoResult = await cmdSess.send(buildPromotionPrompt(candidateSummaries));
-    // Promotion is a commander-session call, so it lands in the commander bucket.
-    trackUsage(promoResult, 'commander');
-    const promoMatch = promoResult.text.match(/\{[\s\S]*"promotions"[\s\S]*\}/);
-    if (promoMatch) {
-        try {
-            const pd = JSON.parse(promoMatch[0]);
-            for (const p of pd.promotions || []) {
-                try {
-                    kernel.promoteAgent(p.agentId, p.department, p.role, leader.name);
-                    console.log(`  ✦ ${p.agentId} → ${p.role}: ${p.reason?.slice(0, 80)}`);
-                    emit('promotion', { agentId: p.agentId, department: p.department, role: p.role, reason: p.reason?.slice(0, 120) });
-                }
-                catch (err) {
-                    console.log(`  ✦ Promotion failed: ${err}`);
-                }
-            }
-        }
-        catch (e) {
-            console.warn('  [promotion] Failed to parse promotion JSON:', e);
-        }
-    }
-    // Fallback: promote top candidate per dept if commander didn't produce valid JSON
-    for (const dept of promotionDepts) {
-        const hasLeader = kernel.getState().agents.some(c => c.promotion?.department === dept);
-        if (!hasLeader) {
-            const top = kernel.getCandidates(dept, 1)[0];
-            if (top) {
-                kernel.promoteAgent(top.core.id, dept, roleNames[dept] || `Head of ${dept}`, leader.name);
-                console.log(`  ✦ [fallback] ${top.core.name} → ${roleNames[dept]}`);
-            }
-        }
+        // If this is a terminal provider error, isAborted() is now true; the
+        // turn loop skips LLM work but continues so the end-of-run cleanup
+        // path runs and the user gets a proper `complete` SSE event.
     }
+    // Turn 0: commander promotes department heads from the kernel's
+    // candidate roster. Any dept the commander skips gets its top
+    // candidate promoted via fallback so turn 1 starts with a full cabinet.
+    await runDepartmentPromotions({
+        kernel,
+        scenario: sc,
+        leader,
+        startYear,
+        sendToCommander: (prompt) => cmdSess.send(prompt),
+        trackUsage,
+        emit,
+    });
     // Captured forge events keyed by department. Each `wrapForgeTool` push
     // here on every successful or failed forge; we drain the dept's bucket
     // around each `dept_done` emit to attribute forges to the right event.
@@ -1343,89 +1168,13 @@ Respond with valid JSON ONLY (no markdown, no prose outside the JSON):
         ? sc.hooks.fingerprintHook(final, outcomeLog, leader, toolRegs, maxTurns)
         : {};
     const fingerprint = { ...generic, ...scenarioOverlay };
-    // Build the canonical Forged Toolbox: deduplicate forge attempts by
-    // tool name, keep the first-forge metadata + accumulated reuse count.
-    // Includes the full input/output JSON Schemas pulled from the
-    // EmergentToolRegistry on first forge — the same data the dashboard's
-    // ToolboxSection renders, now available to programmatic consumers.
-    // Build the canonical Forged Toolbox from the forgedLedger (which has
-    // the authoritative history). allForges is the raw stream of judge
-    // calls; the ledger.history captures every USE (forge or reuse).
-    const forgedToolbox = (() => {
-        const out = [];
-        for (const [name, entry] of forgedLedger) {
-            // Find the original forge metadata (description, mode) from the
-            // first matching captured forge if available; fall back to history.
-            const firstForge = allForges.find(f => f.name === name);
-            const departments = new Set();
-            let approved = false;
-            let maxConfidence = 0;
-            let sampleOutput = null;
-            let reforgeCount = 0;
-            let rejectedReforges = 0;
-            for (const h of entry.history) {
-                departments.add(h.department);
-                if (!h.rejected)
-                    approved = true;
-                if (typeof h.confidence === 'number' && h.confidence > maxConfidence)
-                    maxConfidence = h.confidence;
-                if (h.output)
-                    sampleOutput = h.output;
-                if (h.isReforge) {
-                    reforgeCount++;
-                    if (h.rejected)
-                        rejectedReforges++;
-                }
-            }
-            const totalUses = entry.history.length;
-            out.push({
-                name,
-                description: firstForge?.description || name,
-                mode: firstForge?.mode || 'sandbox',
-                firstForgedTurn: entry.firstForgedTurn,
-                firstForgedDepartment: entry.firstForgedDepartment,
-                firstForgedEventTitle: entry.firstForgedEventTitle,
-                departments: [...departments],
-                reuseCount: Math.max(0, totalUses - 1),
-                totalUses,
-                reforgeCount,
-                rejectedReforges,
-                approved: approved || (firstForge?.approved ?? false),
-                // Use the highest judge confidence across this tool's invocations.
-                // If the tool was never approved (only failed forges), confidence
-                // is 0 — never fabricate an 0.85 default that misrepresents
-                // rejected tools as borderline-passable.
-                confidence: maxConfidence || (firstForge?.approved ? firstForge.confidence : 0),
-                inputSchema: entry.inputSchema,
-                outputSchema: entry.outputSchema,
-                sampleOutput,
-                history: entry.history.slice(),
-            });
-        }
-        return out.sort((a, b) => a.firstForgedTurn - b.firstForgedTurn);
-    })();
-    // Flat unique citation list across all department reports.
-    const citationCatalog = (() => {
-        const byKey = new Map();
-        for (const { turn: t, report } of allDepartmentReports) {
-            for (const c of report.citations) {
-                const key = (c.url || '').trim() || `text:${(c.text || '').trim()}`;
-                if (!key)
-                    continue;
-                let entry = byKey.get(key);
-                if (!entry) {
-                    entry = { text: c.text || c.url || '', url: c.url || '', doi: c.doi, departments: new Set(), turns: new Set() };
-                    byKey.set(key, entry);
-                }
-                if (report.department)
-                    entry.departments.add(report.department);
-                entry.turns.add(t);
-                if (!entry.doi && c.doi)
-                    entry.doi = c.doi;
-            }
-        }
-        return [...byKey.values()].map(e => ({ ...e, departments: [...e.departments], turns: [...e.turns].sort((a, b) => a - b) }));
-    })();
+    // Canonical Forged Toolbox: deduplicated by tool name with first-forge
+    // metadata, full invocation history, and reuse/rejection rollups.
+    // Matches the data the dashboard's ToolboxSection renders.
+    const forgedToolbox = buildForgedToolbox(forgedLedger, allForges);
+    // Flat unique citation list across all department reports. URL is the
+    // dedup key; each entry carries the departments + turns that cited it.
+    const citationCatalog = buildCitationCatalog(allDepartmentReports);
     const output = {
         simulation: `${sc.id}-v3`,
         leader: { name: leader.name, archetype: leader.archetype, colony: leader.colony, hexaco: leader.hexaco },
@@ -1451,7 +1200,7 @@ Respond with valid JSON ONLY (no markdown, no prose outside the JSON):
         /** Per-turn agent reactions with mood + quote + memory snippets. */
         agentReactions: allAgentReactions,
         /** Cost telemetry for the run. */
-        cost: { totalTokens, totalCostUSD: Math.round(totalCostUSD * 10000) / 10000, llmCalls },
+        cost: costTracker.finalCost(),
         /**
          * When a terminal provider error (quota exhausted, invalid API key)
          * was hit during the run, this carries the classified reason. `null`