@agent-e/core 1.1.0

package/dist/index.d.mts

@@ -0,0 +1,532 @@
+type EconomicEventType = 'trade' | 'mint' | 'burn' | 'transfer' | 'produce' | 'consume' | 'role_change' | 'spawn' | 'churn';
+interface EconomicEvent {
+    type: EconomicEventType;
+    timestamp: number;
+    actor: string;
+    role?: string;
+    resource?: string;
+    amount?: number;
+    price?: number;
+    from?: string;
+    to?: string;
+    metadata?: Record<string, unknown>;
+}
+type PinchPointStatus = 'optimal' | 'oversupplied' | 'scarce';
+interface EconomyMetrics {
+    tick: number;
+    timestamp: number;
+    totalSupply: number;
+    netFlow: number;
+    velocity: number;
+    inflationRate: number;
+    populationByRole: Record<string, number>;
+    roleShares: Record<string, number>;
+    totalAgents: number;
+    churnRate: number;
+    churnByRole: Record<string, number>;
+    personaDistribution: Record<string, number>;
+    giniCoefficient: number;
+    medianBalance: number;
+    meanBalance: number;
+    top10PctShare: number;
+    meanMedianDivergence: number;
+    priceIndex: number;
+    productionIndex: number;
+    capacityUsage: number;
+    prices: Record<string, number>;
+    priceVolatility: Record<string, number>;
+    supplyByResource: Record<string, number>;
+    demandSignals: Record<string, number>;
+    pinchPoints: Record<string, PinchPointStatus>;
+    avgSatisfaction: number;
+    blockedAgentCount: number;
+    timeToValue: number;
+    faucetVolume: number;
+    sinkVolume: number;
+    tapSinkRatio: number;
+    poolSizes: Record<string, number>;
+    anchorRatioDrift: number;
+    extractionRatio: number;
+    newUserDependency: number;
+    smokeTestRatio: number;
+    currencyInsulation: number;
+    sharkToothPeaks: number[];
+    sharkToothValleys: number[];
+    eventCompletionRate: number;
+    arbitrageIndex: number;
+    contentDropAge: number;
+    giftTradeRatio: number;
+    disposalTradeRatio: number;
+    custom: Record<string, number>;
+}
+declare function emptyMetrics(tick?: number): EconomyMetrics;
+type PrincipleCategory = 'supply_chain' | 'incentive' | 'population' | 'currency' | 'bootstrap' | 'feedback' | 'regulator' | 'market_dynamics' | 'measurement' | 'wealth_distribution' | 'resource' | 'system_design' | 'player_experience' | 'statistical' | 'system_dynamics' | 'open_economy' | 'liveops';
+interface PrincipleViolation {
+    violated: true;
+    severity: number;
+    evidence: Record<string, unknown>;
+    suggestedAction: SuggestedAction;
+    confidence: number;
+    estimatedLag?: number;
+}
+interface PrincipleOk {
+    violated: false;
+}
+type PrincipleResult = PrincipleViolation | PrincipleOk;
+interface Principle {
+    id: string;
+    name: string;
+    category: PrincipleCategory;
+    description: string;
+    check: (metrics: EconomyMetrics, thresholds: Thresholds) => PrincipleResult;
+}
+interface SuggestedAction {
+    parameter: string;
+    direction: 'increase' | 'decrease' | 'set';
+    magnitude?: number;
+    absoluteValue?: number;
+    reasoning: string;
+}
+interface ActionPlan {
+    id: string;
+    diagnosis: Diagnosis;
+    parameter: string;
+    currentValue: number;
+    targetValue: number;
+    maxChangePercent: number;
+    cooldownTicks: number;
+    rollbackCondition: RollbackCondition;
+    simulationResult: SimulationResult;
+    estimatedLag: number;
+    appliedAt?: number;
+}
+interface RollbackCondition {
+    metric: keyof EconomyMetrics | string;
+    direction: 'above' | 'below';
+    threshold: number;
+    checkAfterTick: number;
+}
+interface Diagnosis {
+    principle: Principle;
+    violation: PrincipleViolation;
+    tick: number;
+}
+interface SimulationOutcome {
+    p10: EconomyMetrics;
+    p50: EconomyMetrics;
+    p90: EconomyMetrics;
+    mean: EconomyMetrics;
+}
+interface SimulationResult {
+    proposedAction: SuggestedAction;
+    iterations: number;
+    forwardTicks: number;
+    outcomes: SimulationOutcome;
+    netImprovement: boolean;
+    noNewProblems: boolean;
+    confidenceInterval: [number, number];
+    estimatedEffectTick: number;
+    overshootRisk: number;
+}
+type DecisionResult = 'applied' | 'skipped_cooldown' | 'skipped_simulation_failed' | 'skipped_locked' | 'skipped_override' | 'rolled_back';
+interface DecisionEntry {
+    id: string;
+    tick: number;
+    timestamp: number;
+    diagnosis: Diagnosis;
+    plan: ActionPlan;
+    result: DecisionResult;
+    reasoning: string;
+    metricsSnapshot: EconomyMetrics;
+}
+interface EconomyState {
+    tick: number;
+    roles: string[];
+    resources: string[];
+    currency: string;
+    agentBalances: Record<string, number>;
+    agentRoles: Record<string, string>;
+    agentInventories: Record<string, Record<string, number>>;
+    agentSatisfaction?: Record<string, number>;
+    marketPrices: Record<string, number>;
+    recentTransactions: EconomicEvent[];
+    poolSizes?: Record<string, number>;
+    customData?: Record<string, unknown>;
+}
+interface EconomyAdapter {
+    /** Return current full state snapshot */
+    getState(): EconomyState | Promise<EconomyState>;
+    /** Apply a parameter change to the host system */
+    setParam(key: string, value: number): void | Promise<void>;
+    /** Optional: adapter pushes events as they happen */
+    onEvent?: (handler: (event: EconomicEvent) => void) => void;
+}
+interface Thresholds {
+    meanMedianDivergenceMax: number;
+    simulationMinIterations: number;
+    personaMonocultureMax: number;
+    personaMinClusters: number;
+    extractionRatioYellow: number;
+    extractionRatioRed: number;
+    smokeTestWarning: number;
+    smokeTestCritical: number;
+    currencyInsulationMax: number;
+    timeBudgetRatio: number;
+    payPowerRatioMax: number;
+    payPowerRatioTarget: number;
+    sharkToothPeakDecay: number;
+    sharkToothValleyDecay: number;
+    eventCompletionMin: number;
+    eventCompletionMax: number;
+    lagMultiplierMin: number;
+    lagMultiplierMax: number;
+    complexityBudgetMax: number;
+    replacementRateMultiplier: number;
+    maxAdjustmentPercent: number;
+    cooldownTicks: number;
+    arenaWinRate: number;
+    arenaHouseCut: number;
+    roleSwitchFrictionMax: number;
+    poolCapPercent: number;
+    poolDecayRate: number;
+    stampedeProfitRatio: number;
+    blockedAgentMaxFraction: number;
+    giniWarnThreshold: number;
+    giniRedThreshold: number;
+    churnWarnRate: number;
+    netFlowWarnThreshold: number;
+    arbitrageIndexWarning: number;
+    arbitrageIndexCritical: number;
+    contentDropCooldownTicks: number;
+    postDropArbitrageMax: number;
+    relativePriceConvergenceTarget: number;
+    priceDiscoveryWindowTicks: number;
+    giftTradeFilterRatio: number;
+    disposalTradeWeightDiscount: number;
+}
+type AgentEMode = 'autonomous' | 'advisor';
+interface AgentEConfig {
+    adapter: EconomyAdapter | 'game' | 'defi' | 'marketplace';
+    mode?: AgentEMode;
+    dominantRoles?: string[];
+    idealDistribution?: Record<string, number>;
+    gracePeriod?: number;
+    checkInterval?: number;
+    maxAdjustmentPercent?: number;
+    cooldownTicks?: number;
+    thresholds?: Partial<Thresholds>;
+    onDecision?: (entry: DecisionEntry) => void;
+    onAlert?: (diagnosis: Diagnosis) => void;
+    onRollback?: (plan: ActionPlan, reason: string) => void;
+}
+type PersonaType = 'Gamer' | 'Trader' | 'Collector' | 'Speculator' | 'Earner' | 'Builder' | 'Social' | 'Whale' | 'Influencer';
+interface PersonaProfile {
+    type: PersonaType;
+    share: number;
+    healthyRangeMin: number;
+    healthyRangeMax: number;
+}
+type MetricResolution = 'fine' | 'medium' | 'coarse';
+interface MetricQuery {
+    metric: keyof EconomyMetrics | string;
+    from?: number;
+    to?: number;
+    resolution?: MetricResolution;
+}
+interface MetricQueryResult {
+    metric: string;
+    resolution: MetricResolution;
+    points: Array<{
+        tick: number;
+        value: number;
+    }>;
+}
+
+declare class Diagnoser {
+    private principles;
+    constructor(principles: Principle[]);
+    addPrinciple(principle: Principle): void;
+    removePrinciple(id: string): void;
+    /**
+     * Run all principles against current metrics.
+     * Returns violations sorted by severity (highest first).
+     * Only one action is taken per cycle — the highest severity violation.
+     */
+    diagnose(metrics: EconomyMetrics, thresholds: Thresholds): Diagnosis[];
+    getPrinciples(): Principle[];
+}
+
+declare class DecisionLog {
+    private entries;
+    private maxEntries;
+    constructor(maxEntries?: number);
+    record(diagnosis: Diagnosis, plan: ActionPlan, result: DecisionResult, metrics: EconomyMetrics): DecisionEntry;
+    recordSkip(diagnosis: Diagnosis, result: DecisionResult, metrics: EconomyMetrics, reason: string): void;
+    query(filter?: {
+        since?: number;
+        until?: number;
+        issue?: string;
+        parameter?: string;
+        result?: DecisionResult;
+    }): DecisionEntry[];
+    latest(n?: number): DecisionEntry[];
+    export(format?: 'json' | 'text'): string;
+    private buildReasoning;
+    private stubPlan;
+}
+
+declare class MetricStore {
+    /** Fine: last 200 ticks, one entry per tick */
+    private fine;
+    /** Medium: last 200 windows of 10 ticks */
+    private medium;
+    /** Coarse: last 200 epochs of 100 ticks */
+    private coarse;
+    private ticksSinceLastMedium;
+    private ticksSinceLastCoarse;
+    private mediumAccumulator;
+    private coarseAccumulator;
+    record(metrics: EconomyMetrics): void;
+    latest(resolution?: MetricResolution): EconomyMetrics;
+    query(q: MetricQuery): MetricQueryResult;
+    /** Check if fine and coarse resolution metrics diverge significantly */
+    divergenceDetected(): boolean;
+    private bufferFor;
+    private aggregate;
+}
+
+type EventName = 'decision' | 'alert' | 'rollback' | 'beforeAction' | 'afterAction';
+declare class AgentE {
+    private readonly config;
+    private readonly thresholds;
+    private adapter;
+    private mode;
+    private observer;
+    private diagnoser;
+    private simulator;
+    private planner;
+    private executor;
+    readonly log: DecisionLog;
+    readonly store: MetricStore;
+    private personaTracker;
+    private params;
+    private eventBuffer;
+    private isRunning;
+    private isPaused;
+    private currentTick;
+    private handlers;
+    constructor(config: AgentEConfig);
+    connect(adapter: EconomyAdapter): this;
+    start(): this;
+    pause(): void;
+    resume(): void;
+    stop(): void;
+    tick(state?: EconomyState): Promise<void>;
+    /** Apply a plan manually (for advisor mode) */
+    apply(plan: ActionPlan): Promise<void>;
+    lock(param: string): void;
+    unlock(param: string): void;
+    constrain(param: string, bounds: {
+        min: number;
+        max: number;
+    }): void;
+    addPrinciple(principle: Principle): void;
+    removePrinciple(id: string): void;
+    registerCustomMetric(name: string, fn: (state: EconomyState) => number): void;
+    getDecisions(filter?: Parameters<DecisionLog['query']>[0]): DecisionEntry[];
+    getPrinciples(): Principle[];
+    getActivePlans(): ActionPlan[];
+    /** Access to the metric time-series store */
+    readonly metrics: {
+        query: (q: MetricQuery) => MetricQueryResult;
+        latest: (resolution?: "fine" | "medium" | "coarse") => EconomyMetrics;
+    };
+    on(event: EventName, handler: (...args: unknown[]) => unknown): this;
+    off(event: EventName, handler: (...args: unknown[]) => unknown): this;
+    private emit;
+    diagnoseNow(): ReturnType<Diagnoser['diagnose']>;
+    getHealth(): number;
+    ingest(event: EconomicEvent): void;
+}
+
+declare class Observer {
+    private previousMetrics;
+    private previousPrices;
+    private customMetricFns;
+    private anchorBaseline;
+    registerCustomMetric(name: string, fn: (state: EconomyState) => number): void;
+    compute(state: EconomyState, recentEvents: EconomicEvent[]): EconomyMetrics;
+}
+
+declare class Simulator {
+    private diagnoser;
+    /**
+     * Simulate the effect of applying `action` to the current economy forward `forwardTicks`.
+     * Runs `iterations` Monte Carlo trials and returns the outcome distribution.
+     *
+     * The inner model is intentionally lightweight — it models how key metrics evolve
+     * under a parameter change using simplified dynamics. This is not a full agent simulation;
+     * it is a fast inner model that catches obvious over/under-corrections.
+     */
+    simulate(action: SuggestedAction, currentMetrics: EconomyMetrics, thresholds: Thresholds, iterations?: number, forwardTicks?: number): SimulationResult;
+    /**
+     * Lightweight forward model: apply action then project key metrics forward.
+     * Uses simplified dynamics — not a full agent replay.
+     */
+    private runForward;
+    private actionMultiplier;
+    private flowEffect;
+    private checkImprovement;
+    private averageMetrics;
+}
+
+interface ParameterConstraint {
+    min: number;
+    max: number;
+}
+declare class Planner {
+    private lockedParams;
+    private constraints;
+    private cooldowns;
+    private activePlanCount;
+    lock(param: string): void;
+    unlock(param: string): void;
+    constrain(param: string, constraint: ParameterConstraint): void;
+    /**
+     * Convert a diagnosis into an ActionPlan.
+     * Returns null if:
+     * - parameter is locked
+     * - parameter is still in cooldown
+     * - simulation result failed
+     * - complexity budget exceeded
+     */
+    plan(diagnosis: Diagnosis, metrics: EconomyMetrics, simulationResult: SimulationResult, currentParams: Record<string, number>, thresholds: Thresholds): ActionPlan | null;
+    recordApplied(plan: ActionPlan, tick: number): void;
+    recordRolledBack(_plan: ActionPlan): void;
+    isOnCooldown(param: string, currentTick: number, cooldownTicks: number): boolean;
+    /** Reset all cooldowns (useful for testing) */
+    resetCooldowns(): void;
+}
+
+declare class Executor {
+    private activePlans;
+    apply(plan: ActionPlan, adapter: EconomyAdapter, currentParams: Record<string, number>): Promise<void>;
+    /**
+     * Check all active plans for rollback conditions.
+     * Called every tick after metrics are computed.
+     * Returns list of plans that were rolled back.
+     */
+    checkRollbacks(metrics: EconomyMetrics, adapter: EconomyAdapter): Promise<ActionPlan[]>;
+    private getMetricValue;
+    getActivePlans(): ActionPlan[];
+}
+
+declare class PersonaTracker {
+    private agentHistory;
+    /** Ingest a state snapshot and update agent signal history */
+    update(state: EconomyState): void;
+    /** Classify all agents and return persona distribution */
+    getDistribution(): Record<string, number>;
+    private classify;
+}
+
+declare const DEFAULT_THRESHOLDS: Thresholds;
+declare const PERSONA_HEALTHY_RANGES: Record<string, {
+    min: number;
+    max: number;
+}>;
+
+declare const P1_ProductionMatchesConsumption: Principle;
+declare const P2_ClosedLoopsNeedDirectHandoff: Principle;
+declare const P3_BootstrapCapitalCoversFirstTransaction: Principle;
+declare const P4_MaterialsFlowFasterThanCooldown: Principle;
+declare const P60_SurplusDisposalAsymmetry: Principle;
+declare const SUPPLY_CHAIN_PRINCIPLES: Principle[];
+
+declare const P5_ProfitabilityIsCompetitive: Principle;
+declare const P6_CrowdingMultiplierOnAllRoles: Principle;
+declare const P7_NonSpecialistsSubsidiseSpecialists: Principle;
+declare const P8_RegulatorCannotFightDesign: Principle;
+declare const INCENTIVE_PRINCIPLES: Principle[];
+
+declare const P9_RoleSwitchingNeedsFriction: Principle;
+declare const P10_SpawnWeightingUsesInversePopulation: Principle;
+declare const P11_TwoTierPressure: Principle;
+declare const P46_PersonaDiversity: Principle;
+declare const POPULATION_PRINCIPLES: Principle[];
+
+declare const P12_OnePrimaryFaucet: Principle;
+declare const P13_PotsAreZeroSumAndSelfRegulate: Principle;
+declare const P14_TrackActualInjection: Principle;
+declare const P15_PoolsNeedCapAndDecay: Principle;
+declare const P16_WithdrawalPenaltyScales: Principle;
+declare const P32_VelocityAboveSupply: Principle;
+declare const P58_NoNaturalNumeraire: Principle;
+declare const CURRENCY_FLOW_PRINCIPLES: Principle[];
+
+declare const P17_GracePeriodBeforeIntervention: Principle;
+declare const P18_FirstProducerNeedsStartingInventory: Principle;
+declare const P19_StartingSupplyExceedsDemand: Principle;
+declare const BOOTSTRAP_PRINCIPLES: Principle[];
+
+declare const P20_DecayPreventsAccumulation: Principle;
+declare const P21_PriceFromGlobalSupply: Principle;
+declare const P22_MarketAwarenessPreventsSurplus: Principle;
+declare const P23_ProfitabilityFactorsFeasibility: Principle;
+declare const P24_BlockedAgentsDecayFaster: Principle;
+declare const FEEDBACK_LOOP_PRINCIPLES: Principle[];
+
+declare const P25_CorrectLeversForCorrectProblems: Principle;
+declare const P26_ContinuousPressureBeatsThresholdCuts: Principle;
+declare const P27_AdjustmentsNeedCooldowns: Principle;
+declare const P28_StructuralDominanceIsNotPathological: Principle;
+declare const P38_CommunicationPreventsRevolt: Principle;
+declare const REGULATOR_PRINCIPLES: Principle[];
+
+declare const P29_PinchPoint: Principle;
+declare const P30_MovingPinchPoint: Principle;
+declare const P57_CombinatorialPriceSpace: Principle;
+declare const MARKET_DYNAMICS_PRINCIPLES: Principle[];
+
+declare const P31_AnchorValueTracking: Principle;
+declare const P41_MultiResolutionMonitoring: Principle;
+declare const P55_ArbitrageThermometer: Principle;
+declare const P59_GiftEconomyNoise: Principle;
+declare const MEASUREMENT_PRINCIPLES: Principle[];
+
+declare const P42_TheMedianPrinciple: Principle;
+declare const P43_SimulationMinimum: Principle;
+declare const STATISTICAL_PRINCIPLES: Principle[];
+
+declare const P39_TheLagPrinciple: Principle;
+declare const P44_ComplexityBudget: Principle;
+declare const SYSTEM_DYNAMICS_PRINCIPLES: Principle[];
+
+declare const P35_DestructionCreatesValue: Principle;
+declare const P40_ReplacementRate: Principle;
+declare const P49_IdleAssetTax: Principle;
+declare const RESOURCE_MGMT_PRINCIPLES: Principle[];
+
+declare const P33_FairNotEqual: Principle;
+declare const P36_MechanicFrictionDetector: Principle;
+declare const P37_LatecommerProblem: Principle;
+declare const P45_TimeBudget: Principle;
+declare const P50_PayPowerRatio: Principle;
+declare const PLAYER_EXPERIENCE_PRINCIPLES: Principle[];
+
+declare const P34_ExtractionRatio: Principle;
+declare const P47_SmokeTest: Principle;
+declare const P48_CurrencyInsulation: Principle;
+declare const OPEN_ECONOMY_PRINCIPLES: Principle[];
+
+declare const P51_SharkTooth: Principle;
+declare const P52_EndowmentEffect: Principle;
+declare const P53_EventCompletionRate: Principle;
+declare const P54_LiveOpsCadence: Principle;
+declare const P56_ContentDropShock: Principle;
+declare const LIVEOPS_PRINCIPLES: Principle[];
+
+/** All 60 built-in principles in priority order (supply chain → liveops) */
+declare const ALL_PRINCIPLES: Principle[];
+
+export { ALL_PRINCIPLES, type ActionPlan, AgentE, type AgentEConfig, type AgentEMode, BOOTSTRAP_PRINCIPLES, CURRENCY_FLOW_PRINCIPLES, DEFAULT_THRESHOLDS, type DecisionEntry, DecisionLog, type DecisionResult, Diagnoser, type Diagnosis, type EconomicEvent, type EconomicEventType, type EconomyAdapter, type EconomyMetrics, type EconomyState, Executor, FEEDBACK_LOOP_PRINCIPLES, INCENTIVE_PRINCIPLES, LIVEOPS_PRINCIPLES, MARKET_DYNAMICS_PRINCIPLES, MEASUREMENT_PRINCIPLES, type MetricQuery, type MetricQueryResult, type MetricResolution, MetricStore, OPEN_ECONOMY_PRINCIPLES, Observer, P10_SpawnWeightingUsesInversePopulation, P11_TwoTierPressure, P12_OnePrimaryFaucet, P13_PotsAreZeroSumAndSelfRegulate, P14_TrackActualInjection, P15_PoolsNeedCapAndDecay, P16_WithdrawalPenaltyScales, P17_GracePeriodBeforeIntervention, P18_FirstProducerNeedsStartingInventory, P19_StartingSupplyExceedsDemand, P1_ProductionMatchesConsumption, P20_DecayPreventsAccumulation, P21_PriceFromGlobalSupply, P22_MarketAwarenessPreventsSurplus, P23_ProfitabilityFactorsFeasibility, P24_BlockedAgentsDecayFaster, P25_CorrectLeversForCorrectProblems, P26_ContinuousPressureBeatsThresholdCuts, P27_AdjustmentsNeedCooldowns, P28_StructuralDominanceIsNotPathological, P29_PinchPoint, P2_ClosedLoopsNeedDirectHandoff, P30_MovingPinchPoint, P31_AnchorValueTracking, P32_VelocityAboveSupply, P33_FairNotEqual, P34_ExtractionRatio, P35_DestructionCreatesValue, P36_MechanicFrictionDetector, P37_LatecommerProblem, P38_CommunicationPreventsRevolt, P39_TheLagPrinciple, P3_BootstrapCapitalCoversFirstTransaction, P40_ReplacementRate, P41_MultiResolutionMonitoring, P42_TheMedianPrinciple, P43_SimulationMinimum, P44_ComplexityBudget, P45_TimeBudget, P46_PersonaDiversity, P47_SmokeTest, P48_CurrencyInsulation, P49_IdleAssetTax, P4_MaterialsFlowFasterThanCooldown, P50_PayPowerRatio, P51_SharkTooth, P52_EndowmentEffect, P53_EventCompletionRate, P54_LiveOpsCadence, P55_ArbitrageThermometer, P56_ContentDropShock, P57_CombinatorialPriceSpace, P58_NoNaturalNumeraire, P59_GiftEconomyNoise, P5_ProfitabilityIsCompetitive, P60_SurplusDisposalAsymmetry, P6_CrowdingMultiplierOnAllRoles, P7_NonSpecialistsSubsidiseSpecialists, P8_RegulatorCannotFightDesign, P9_RoleSwitchingNeedsFriction, PERSONA_HEALTHY_RANGES, PLAYER_EXPERIENCE_PRINCIPLES, POPULATION_PRINCIPLES, type PersonaProfile, PersonaTracker, type PersonaType, type PinchPointStatus, Planner, type Principle, type PrincipleCategory, type PrincipleOk, type PrincipleResult, type PrincipleViolation, REGULATOR_PRINCIPLES, RESOURCE_MGMT_PRINCIPLES, type RollbackCondition, STATISTICAL_PRINCIPLES, SUPPLY_CHAIN_PRINCIPLES, SYSTEM_DYNAMICS_PRINCIPLES, type SimulationOutcome, type SimulationResult, Simulator, type SuggestedAction, type Thresholds, emptyMetrics };