@agent-e/core 1.1.2 → 1.2.0

package/README.md

@@ -17,7 +17,7 @@ const agent = new AgentE({
   adapter: {
     getState: () => ({
       tick: currentTick,
-      agentBalances: { /* id → gold */ },
+      agentBalances: { /* id → balance */ },
       agentRoles: { /* id → role */ },
       agentInventories: { /* id → { resource → qty } */ },
       marketPrices: { /* resource → price */ },
@@ -58,15 +58,29 @@ Organized across 15 categories: supply chain, incentives, population, currency f
 
 Each principle has a `check(metrics, thresholds)` function that returns either `{ violated: false }` or a violation with severity, evidence, suggested action, confidence, and estimated lag.
 
+## Tick Configuration
+
+```typescript
+const agent = new AgentE({
+  adapter: yourAdapter,
+  tickConfig: {
+    duration: 5,          // one tick = 5 seconds
+    unit: 'second',
+    mediumWindow: 12,     // medium metrics = every 12 ticks (60s)
+    coarseWindow: 120,    // coarse metrics = every 120 ticks (10min)
+  },
+});
+```
+
 ## Developer API
 
 ```typescript
 // Lock a parameter from automated adjustment
-agent.lock('craftingCost');
-agent.unlock('craftingCost');
+agent.lock('productionCost');
+agent.unlock('productionCost');
 
 // Constrain a parameter to a range
-agent.constrain('auctionFee', { min: 0.01, max: 0.50 });
+agent.constrain('transactionFee', { min: 0.01, max: 0.50 });
 
 // Add a custom principle
 agent.addPrinciple(myPrinciple);
@@ -96,21 +110,21 @@ import type { Principle } from '@agent-e/core';
 
 const myRule: Principle = {
   id: 'MY_01',
-  name: 'Healer Population Floor',
+  name: 'Support Role Population Floor',
   category: 'population',
-  description: 'Healer share below 5% is a crisis',
+  description: 'Support role share below 5% is a crisis',
   check(metrics, thresholds) {
-    const share = metrics.roleShares['Healer'] ?? 0;
+    const share = metrics.roleShares['support'] ?? 0;
     if (share < 0.05) {
       return {
         violated: true,
         severity: 8,
         evidence: { share },
         suggestedAction: {
-          parameter: 'healerReward',
+          parameter: 'supportReward',
           direction: 'increase',
           magnitude: 0.25,
-          reasoning: 'Healer population critically low.',
+          reasoning: 'Support role population critically low.',
         },
         confidence: 0.90,
         estimatedLag: 10,

package/dist/index.d.mts

@@ -184,8 +184,8 @@ interface Thresholds {
     replacementRateMultiplier: number;
     maxAdjustmentPercent: number;
     cooldownTicks: number;
-    arenaWinRate: number;
-    arenaHouseCut: number;
+    poolWinRate: number;
+    poolHouseCut: number;
     roleSwitchFrictionMax: number;
     poolCapPercent: number;
     poolDecayRate: number;
@@ -204,12 +204,23 @@ interface Thresholds {
     giftTradeFilterRatio: number;
     disposalTradeWeightDiscount: number;
 }
+interface TickConfig {
+    /** How many real-world units one tick represents. Default: 1 */
+    duration: number;
+    /** The unit of time. Default: 'tick' (abstract). Examples: 'second', 'minute', 'block', 'frame' */
+    unit: string;
+    /** Medium-resolution metric window in ticks. Default: 10 */
+    mediumWindow?: number;
+    /** Coarse-resolution metric window in ticks. Default: 100 */
+    coarseWindow?: number;
+}
 type AgentEMode = 'autonomous' | 'advisor';
 interface AgentEConfig {
-    adapter: EconomyAdapter | 'game' | 'defi' | 'marketplace';
+    adapter: EconomyAdapter;
     mode?: AgentEMode;
     dominantRoles?: string[];
     idealDistribution?: Record<string, number>;
+    tickConfig?: Partial<TickConfig>;
     gracePeriod?: number;
     checkInterval?: number;
     maxAdjustmentPercent?: number;
@@ -219,7 +230,7 @@ interface AgentEConfig {
     onAlert?: (diagnosis: Diagnosis) => void;
     onRollback?: (plan: ActionPlan, reason: string) => void;
 }
-type PersonaType = 'Gamer' | 'Trader' | 'Collector' | 'Speculator' | 'Earner' | 'Builder' | 'Social' | 'Whale' | 'Influencer';
+type PersonaType = 'Active' | 'Trader' | 'Collector' | 'Speculator' | 'Earner' | 'Builder' | 'Social' | 'Whale' | 'Influencer';
 interface PersonaProfile {
     type: PersonaType;
     share: number;
@@ -278,14 +289,17 @@ declare class DecisionLog {
 declare class MetricStore {
     /** Fine: last 200 ticks, one entry per tick */
     private fine;
-    /** Medium: last 200 windows of 10 ticks */
+    /** Medium: last 200 windows */
     private medium;
-    /** Coarse: last 200 epochs of 100 ticks */
+    /** Coarse: last 200 epochs */
     private coarse;
+    private mediumWindow;
+    private coarseWindow;
     private ticksSinceLastMedium;
     private ticksSinceLastCoarse;
     private mediumAccumulator;
     private coarseAccumulator;
+    constructor(tickConfig?: Partial<TickConfig>);
     record(metrics: EconomyMetrics): void;
     latest(resolution?: MetricResolution): EconomyMetrics;
     query(q: MetricQuery): MetricQueryResult;
@@ -354,6 +368,8 @@ declare class Observer {
     private previousPrices;
     private customMetricFns;
     private anchorBaseline;
+    private tickConfig;
+    constructor(tickConfig?: Partial<TickConfig>);
     registerCustomMetric(name: string, fn: (state: EconomyState) => number): void;
     compute(state: EconomyState, recentEvents: EconomicEvent[]): EconomyMetrics;
 }
@@ -530,4 +546,4 @@ 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 };
+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, type TickConfig, emptyMetrics };

package/dist/index.d.ts

@@ -184,8 +184,8 @@ interface Thresholds {
     replacementRateMultiplier: number;
     maxAdjustmentPercent: number;
     cooldownTicks: number;
-    arenaWinRate: number;
-    arenaHouseCut: number;
+    poolWinRate: number;
+    poolHouseCut: number;
     roleSwitchFrictionMax: number;
     poolCapPercent: number;
     poolDecayRate: number;
@@ -204,12 +204,23 @@ interface Thresholds {
     giftTradeFilterRatio: number;
     disposalTradeWeightDiscount: number;
 }
+interface TickConfig {
+    /** How many real-world units one tick represents. Default: 1 */
+    duration: number;
+    /** The unit of time. Default: 'tick' (abstract). Examples: 'second', 'minute', 'block', 'frame' */
+    unit: string;
+    /** Medium-resolution metric window in ticks. Default: 10 */
+    mediumWindow?: number;
+    /** Coarse-resolution metric window in ticks. Default: 100 */
+    coarseWindow?: number;
+}
 type AgentEMode = 'autonomous' | 'advisor';
 interface AgentEConfig {
-    adapter: EconomyAdapter | 'game' | 'defi' | 'marketplace';
+    adapter: EconomyAdapter;
     mode?: AgentEMode;
     dominantRoles?: string[];
     idealDistribution?: Record<string, number>;
+    tickConfig?: Partial<TickConfig>;
     gracePeriod?: number;
     checkInterval?: number;
     maxAdjustmentPercent?: number;
@@ -219,7 +230,7 @@ interface AgentEConfig {
     onAlert?: (diagnosis: Diagnosis) => void;
     onRollback?: (plan: ActionPlan, reason: string) => void;
 }
-type PersonaType = 'Gamer' | 'Trader' | 'Collector' | 'Speculator' | 'Earner' | 'Builder' | 'Social' | 'Whale' | 'Influencer';
+type PersonaType = 'Active' | 'Trader' | 'Collector' | 'Speculator' | 'Earner' | 'Builder' | 'Social' | 'Whale' | 'Influencer';
 interface PersonaProfile {
     type: PersonaType;
     share: number;
@@ -278,14 +289,17 @@ declare class DecisionLog {
 declare class MetricStore {
     /** Fine: last 200 ticks, one entry per tick */
     private fine;
-    /** Medium: last 200 windows of 10 ticks */
+    /** Medium: last 200 windows */
     private medium;
-    /** Coarse: last 200 epochs of 100 ticks */
+    /** Coarse: last 200 epochs */
     private coarse;
+    private mediumWindow;
+    private coarseWindow;
     private ticksSinceLastMedium;
     private ticksSinceLastCoarse;
     private mediumAccumulator;
     private coarseAccumulator;
+    constructor(tickConfig?: Partial<TickConfig>);
     record(metrics: EconomyMetrics): void;
     latest(resolution?: MetricResolution): EconomyMetrics;
     query(q: MetricQuery): MetricQueryResult;
@@ -354,6 +368,8 @@ declare class Observer {
     private previousPrices;
     private customMetricFns;
     private anchorBaseline;
+    private tickConfig;
+    constructor(tickConfig?: Partial<TickConfig>);
     registerCustomMetric(name: string, fn: (state: EconomyState) => number): void;
     compute(state: EconomyState, recentEvents: EconomicEvent[]): EconomyMetrics;
 }
@@ -530,4 +546,4 @@ 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 };
+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, type TickConfig, emptyMetrics };