@hazeljs/organism 2.0.6

package/src/economy/utility-engine.ts

@@ -0,0 +1,103 @@
+import type {
+  AgentOutcomeReport,
+  AgentReputation,
+  RuntimeAgentRecord,
+  UtilityScore,
+  UtilityWeights,
+} from '../types/organism.types';
+import { DEFAULT_UTILITY_WEIGHTS as WEIGHTS } from '../types/organism.types';
+import { OrganismEventEmitter, OrganismEventType } from '../events/organism-events';
+
+export class UtilityEngine {
+  constructor(
+    private readonly events: OrganismEventEmitter,
+    private readonly organismId: string,
+    private readonly weights: UtilityWeights = WEIGHTS
+  ) {}
+
+  evaluate(agent: RuntimeAgentRecord, report?: AgentOutcomeReport): UtilityScore {
+    const valueGenerated = report?.metrics?.valueGenerated ?? agent.valueGenerated;
+    const cost = report?.metrics?.cost ?? agent.costConsumed;
+    const riskPenalty = report?.metrics?.riskPenalty ?? 0;
+    const confidence = report?.metrics?.confidence ?? agent.utility.confidence;
+
+    const missionContribution = clamp(
+      valueGenerated / Math.max(1, valueGenerated + cost * 10),
+      0,
+      1
+    );
+    const efficiency = cost <= 0 ? 1 : clamp(valueGenerated / (valueGenerated + cost * 50), 0, 1);
+    const reliability = clamp(agent.reputation.dimensions.reliability, 0, 1);
+    const policyCompliance = clamp(agent.reputation.dimensions.policyCompliance, 0, 1);
+    const collaboration = clamp(agent.reputation.dimensions.collaboration, 0, 1);
+
+    const score =
+      missionContribution * this.weights.missionContribution +
+      reliability * this.weights.reliability +
+      efficiency * this.weights.efficiency +
+      policyCompliance * this.weights.policyCompliance +
+      collaboration * this.weights.collaboration -
+      riskPenalty;
+
+    const utility: UtilityScore = {
+      score: clamp(score, 0, 1),
+      valueGenerated,
+      cost,
+      riskPenalty,
+      confidence: clamp(confidence, 0, 1),
+    };
+
+    void this.events.emit(OrganismEventType.ORGANISM_UTILITY_CALCULATED, this.organismId, {
+      agentId: agent.id,
+      utility,
+    });
+
+    return utility;
+  }
+}
+
+export class ReputationEngine {
+  constructor(
+    private readonly events: OrganismEventEmitter,
+    private readonly organismId: string
+  ) {}
+
+  update(agent: RuntimeAgentRecord, report: AgentOutcomeReport): AgentReputation {
+    const value = report.metrics?.valueGenerated ?? 0;
+    const confidence = report.metrics?.confidence ?? 0.5;
+    const cost = report.metrics?.cost ?? 0;
+
+    const usefulnessDelta = clamp(value / 1000, -0.1, 0.15);
+    const efficiencyDelta = cost > value * 0.1 ? -0.05 : 0.03;
+    const reliabilityDelta = confidence >= 0.7 ? 0.04 : -0.03;
+
+    const dims = { ...agent.reputation.dimensions };
+    dims.usefulness = clamp(dims.usefulness + usefulnessDelta, 0, 1);
+    dims.efficiency = clamp(dims.efficiency + efficiencyDelta, 0, 1);
+    dims.reliability = clamp(dims.reliability + reliabilityDelta, 0, 1);
+
+    const score =
+      dims.usefulness * 0.3 +
+      dims.reliability * 0.25 +
+      dims.efficiency * 0.2 +
+      dims.policyCompliance * 0.15 +
+      dims.collaboration * 0.1;
+
+    const reputation: AgentReputation = {
+      agentId: agent.id,
+      score: clamp(score, 0, 1),
+      dimensions: dims,
+    };
+
+    void this.events.emit(OrganismEventType.ORGANISM_REPUTATION_CHANGED, this.organismId, {
+      agentId: agent.id,
+      reputation,
+    });
+
+    return reputation;
+  }
+}
+
+function clamp(n: number, min: number, max: number): number {
+  return Math.max(min, Math.min(max, n));
+}

package/src/economy/utility-forecaster.ts

@@ -0,0 +1,88 @@
+/**
+ * Phase 4 — utility forecasting and opportunity-cost estimates.
+ */
+
+import type {
+  OpportunityCostEstimate,
+  OrganismRecord,
+  ResourceRequest,
+  RuntimeAgentRecord,
+  UtilityForecast,
+} from '../types/organism.types';
+import { OrganismEventEmitter, OrganismEventType } from '../events/organism-events';
+
+export class UtilityForecaster {
+  constructor(
+    private readonly events: OrganismEventEmitter,
+    private readonly organismId: string
+  ) {}
+
+  /**
+   * Deterministic forecast: expected value × confidence − opportunity cost,
+   * adjusted by reputation and scarcity.
+   */
+  forecast(input: {
+    agent: RuntimeAgentRecord;
+    record: OrganismRecord;
+    requested: ResourceRequest;
+    expectedValue: number;
+    confidence: number;
+    urgency?: number;
+  }): UtilityForecast {
+    const { agent, record, requested, expectedValue, confidence } = input;
+    const urgency = input.urgency ?? 0.5;
+    const opportunity = this.opportunityCost(record, requested);
+    const reputationBoost = 0.5 + agent.reputation.score * 0.5;
+    const adjustedValue = expectedValue * clamp(confidence, 0, 1) * reputationBoost;
+    const estimatedCost =
+      (requested.tokens ?? 0) * 0.00001 + (requested.money ?? 0) + opportunity.total * 0.1;
+    const netExpectedValue = adjustedValue - opportunity.total - estimatedCost;
+    const expectedUtility = clamp(
+      (netExpectedValue / Math.max(1, expectedValue + opportunity.total)) * (0.5 + urgency * 0.5),
+      0,
+      1
+    );
+
+    const forecast: UtilityForecast = {
+      agentId: agent.id,
+      expectedUtility,
+      expectedValue,
+      estimatedCost,
+      opportunityCost: opportunity.total,
+      netExpectedValue,
+      confidence: clamp(confidence, 0, 1),
+      reasoningSummary: `net=${netExpectedValue.toFixed(2)} (value=${adjustedValue.toFixed(2)} - opp=${opportunity.total.toFixed(2)} - cost=${estimatedCost.toFixed(2)}); scarcity=${opportunity.scarcityMultiplier.toFixed(2)}`,
+    };
+
+    void this.events.emit(OrganismEventType.ORGANISM_UTILITY_FORECAST, this.organismId, forecast);
+    return forecast;
+  }
+
+  opportunityCost(record: OrganismRecord, requested: ResourceRequest): OpportunityCostEstimate {
+    const tokenBudget = Math.max(
+      1,
+      (record.resources.tokenBudget ?? record.pool.tokensRemaining) || 1
+    );
+    const moneyBudget = Math.max(
+      1,
+      (record.resources.monthlyBudget?.amount ?? record.pool.moneyRemaining.amount) || 1
+    );
+    const tokenUtil = 1 - record.pool.tokensRemaining / tokenBudget;
+    const moneyUtil = 1 - record.pool.moneyRemaining.amount / moneyBudget;
+    const utilization = Math.max(tokenUtil, moneyUtil);
+    const scarcityMultiplier = utilization < 0.7 ? 1 : 1 + (utilization - 0.7) * 5;
+
+    const tokens = (requested.tokens ?? 0) * 0.00002 * scarcityMultiplier;
+    const money = (requested.money ?? 0) * scarcityMultiplier;
+    return {
+      tokens,
+      money,
+      scarcityMultiplier,
+      total: tokens + money,
+    };
+  }
+}
+
+function clamp(n: number, min: number, max: number): number {
+  return Math.max(min, Math.min(max, n));
+}

package/src/errors/organism.errors.ts

@@ -0,0 +1,47 @@
+/**
+ * @hazeljs/organism errors
+ */
+
+export class OrganismError extends Error {
+  readonly code: string;
+  constructor(message: string, code = 'ORGANISM_ERROR') {
+    super(message);
+    this.name = 'OrganismError';
+    this.code = code;
+  }
+}
+
+export class OrganismLimitError extends OrganismError {
+  constructor(message: string) {
+    super(message, 'ORGANISM_LIMIT');
+    this.name = 'OrganismLimitError';
+  }
+}
+
+export class OrganismResourceDeniedError extends OrganismError {
+  constructor(message: string) {
+    super(message, 'ORGANISM_RESOURCE_DENIED');
+    this.name = 'OrganismResourceDeniedError';
+  }
+}
+
+export class OrganismConstitutionError extends OrganismError {
+  constructor(message: string) {
+    super(message, 'ORGANISM_CONSTITUTION');
+    this.name = 'OrganismConstitutionError';
+  }
+}
+
+export class OrganismStateError extends OrganismError {
+  constructor(message: string) {
+    super(message, 'ORGANISM_STATE');
+    this.name = 'OrganismStateError';
+  }
+}
+
+export class OrganismNotFoundError extends OrganismError {
+  constructor(message: string) {
+    super(message, 'ORGANISM_NOT_FOUND');
+    this.name = 'OrganismNotFoundError';
+  }
+}

package/src/events/organism-events.ts

@@ -0,0 +1,122 @@
+/**
+ * Organism domain events (namespaced; separate from AgentEventType).
+ */
+
+export enum OrganismEventType {
+  ORGANISM_CREATED = 'organism.created',
+  ORGANISM_RESTORED = 'organism.restored',
+  ORGANISM_STARTED = 'organism.started',
+  ORGANISM_PAUSED = 'organism.paused',
+  ORGANISM_RESUMED = 'organism.resumed',
+  ORGANISM_COMPLETED = 'organism.completed',
+  ORGANISM_TERMINATED = 'organism.terminated',
+  ORGANISM_EMERGENCY_STOP = 'organism.emergency_stop',
+
+  ENVIRONMENT_SIGNAL_RECEIVED = 'environment.signal.received',
+  ORGANISM_NEED_DETECTED = 'organism.need.detected',
+
+  ORGANISM_AGENT_BORN = 'organism.agent.born',
+  ORGANISM_AGENT_SPECIALIZED = 'organism.agent.specialized',
+  ORGANISM_AGENT_REPRODUCED = 'organism.agent.reproduced',
+  ORGANISM_AGENT_MUTATED = 'organism.agent.mutated',
+  ORGANISM_AGENT_SUSPENDED = 'organism.agent.suspended',
+  ORGANISM_AGENT_TERMINATED = 'organism.agent.terminated',
+
+  ORGANISM_RESOURCE_ALLOCATED = 'organism.resource.allocated',
+  ORGANISM_RESOURCE_DENIED = 'organism.resource.denied',
+  ORGANISM_RESOURCE_BID = 'organism.resource.bid',
+  ORGANISM_MARKET_CLEARED = 'organism.market.cleared',
+  ORGANISM_NEGOTIATION = 'organism.negotiation',
+  ORGANISM_UTILITY_FORECAST = 'organism.utility.forecast',
+
+  ORGANISM_REPUTATION_CHANGED = 'organism.reputation.changed',
+  ORGANISM_UTILITY_CALCULATED = 'organism.utility.calculated',
+
+  ORGANISM_GENERATION_CREATED = 'organism.generation.created',
+  ORGANISM_STRATEGY_PROMOTED = 'organism.strategy.promoted',
+
+  ORGANISM_CONSTITUTION_VIOLATION = 'organism.constitution.violation',
+  ORGANISM_MISSION_PROGRESS = 'organism.mission.progress',
+  ORGANISM_MISSION_COMPLETED = 'organism.mission.completed',
+
+  ORGANISM_DECISION = 'organism.decision',
+}
+
+export interface OrganismEvent<T = unknown> {
+  type: OrganismEventType;
+  organismId: string;
+  timestamp: Date;
+  data: T;
+  metadata?: Record<string, unknown>;
+}
+
+type EventHandler<T = unknown> = (event: OrganismEvent<T>) => void | Promise<void>;
+
+export class OrganismEventEmitter {
+  private handlers = new Map<OrganismEventType, Set<EventHandler>>();
+  private wildcardHandlers = new Set<EventHandler>();
+  private history: OrganismEvent[] = [];
+  private maxHistory: number;
+
+  constructor(options: { maxHistory?: number } = {}) {
+    this.maxHistory = options.maxHistory ?? 500;
+  }
+
+  on<T = unknown>(type: OrganismEventType, handler: EventHandler<T>): void {
+    if (!this.handlers.has(type)) {
+      this.handlers.set(type, new Set());
+    }
+    this.handlers.get(type)!.add(handler as EventHandler);
+  }
+
+  onAny(handler: EventHandler): void {
+    this.wildcardHandlers.add(handler);
+  }
+
+  off(type: OrganismEventType, handler: EventHandler): void {
+    this.handlers.get(type)?.delete(handler);
+  }
+
+  offAny(handler: EventHandler): void {
+    this.wildcardHandlers.delete(handler);
+  }
+
+  async emit<T = unknown>(
+    type: OrganismEventType,
+    organismId: string,
+    data: T,
+    metadata?: Record<string, unknown>
+  ): Promise<OrganismEvent<T>> {
+    const event: OrganismEvent<T> = {
+      type,
+      organismId,
+      timestamp: new Date(),
+      data,
+      metadata,
+    };
+    this.history.push(event as OrganismEvent);
+    if (this.history.length > this.maxHistory) {
+      this.history.splice(0, this.history.length - this.maxHistory);
+    }
+
+    const typed = this.handlers.get(type);
+    if (typed) {
+      for (const handler of typed) {
+        await handler(event);
+      }
+    }
+    for (const handler of this.wildcardHandlers) {
+      await handler(event as OrganismEvent);
+    }
+    return event;
+  }
+
+  getHistory(limit?: number): OrganismEvent[] {
+    if (limit == null) return [...this.history];
+    return this.history.slice(-limit);
+  }
+
+  clearHistory(): void {
+    this.history = [];
+  }
+}

package/src/evolution/evolution-engine.ts

@@ -0,0 +1,167 @@
+/**
+ * Phase 3 — generation evaluation and strategy promotion.
+ */
+
+import type {
+  EvolutionaryHistoryEntry,
+  GenerationEvaluationResult,
+  GenerationMemberScore,
+  RuntimeAgentRecord,
+  UtilityWeights,
+} from '../types/organism.types';
+import { DEFAULT_UTILITY_WEIGHTS } from '../types/organism.types';
+import { OrganismEventEmitter, OrganismEventType } from '../events/organism-events';
+import type { OrganismRepository } from '../persistence/organism-repository';
+import { MutationEngine, type MutationRequest } from './mutation-engine';
+import type { AgentGeneDefinition } from '../types/organism.types';
+
+export class GenerationManager {
+  private history: EvolutionaryHistoryEntry[] = [];
+  private populations = new Map<string, string[]>();
+
+  registerPopulation(populationId: string, agentIds: string[]): void {
+    this.populations.set(populationId, [...agentIds]);
+  }
+
+  getPopulation(populationId: string): string[] {
+    return [...(this.populations.get(populationId) ?? [])];
+  }
+
+  record(entry: EvolutionaryHistoryEntry): void {
+    this.history.push(entry);
+    if (this.history.length > 200) {
+      this.history.splice(0, this.history.length - 200);
+    }
+  }
+
+  getHistory(limit = 50): EvolutionaryHistoryEntry[] {
+    return this.history.slice(-limit);
+  }
+}
+
+export class EvolutionEngine {
+  constructor(
+    private readonly events: OrganismEventEmitter,
+    private readonly repo: OrganismRepository,
+    private readonly generations: GenerationManager,
+    private readonly mutationEngine: MutationEngine,
+    private readonly organismId: string,
+    private readonly weights: UtilityWeights = DEFAULT_UTILITY_WEIGHTS,
+    private readonly now: () => Date = () => new Date()
+  ) {}
+
+  scoreAgent(agent: RuntimeAgentRecord): number {
+    const missionContribution = clamp(agent.utility.score, 0, 1);
+    const reliability = agent.reputation.dimensions.reliability;
+    const efficiency = agent.reputation.dimensions.efficiency;
+    const policyCompliance = agent.reputation.dimensions.policyCompliance;
+    const collaboration = agent.reputation.dimensions.collaboration;
+    return (
+      missionContribution * this.weights.missionContribution +
+      reliability * this.weights.reliability +
+      efficiency * this.weights.efficiency +
+      policyCompliance * this.weights.policyCompliance +
+      collaboration * this.weights.collaboration
+    );
+  }
+
+  async evaluateGeneration(input: {
+    population: string[];
+    populationId?: string;
+  }): Promise<GenerationEvaluationResult> {
+    const populationId = input.populationId ?? `pop_${Date.now().toString(36)}`;
+    this.generations.registerPopulation(populationId, input.population);
+
+    const members: GenerationMemberScore[] = [];
+    const scores: Record<string, number> = {};
+
+    for (const agentId of input.population) {
+      const agent = await this.repo.getAgent(this.organismId, agentId);
+      if (!agent || agent.status === 'terminated') continue;
+      const score = this.scoreAgent(agent);
+      scores[agentId] = score;
+      members.push({
+        agentId,
+        score,
+        utility: agent.utility.score,
+        reputation: agent.reputation.score,
+        cost: agent.costConsumed,
+        policyCompliance: agent.reputation.dimensions.policyCompliance,
+      });
+    }
+
+    if (!members.length) {
+      return {
+        populationId,
+        winner: input.population[0] ?? '',
+        scores,
+        members,
+      };
+    }
+
+    members.sort((a, b) => b.score - a.score);
+    const winner = members[0].agentId;
+    const winnerAgent = await this.repo.getAgent(this.organismId, winner);
+    const promotedStrategyId = winnerAgent?.strategyId;
+
+    const result: GenerationEvaluationResult = {
+      populationId,
+      winner,
+      scores,
+      members,
+      promotedStrategyId,
+    };
+
+    this.generations.record({
+      at: this.now(),
+      populationId,
+      winnerAgentId: winner,
+      scores: { ...scores },
+      promotedStrategyId,
+    });
+
+    await this.events.emit(OrganismEventType.ORGANISM_GENERATION_CREATED, this.organismId, {
+      populationId,
+      population: input.population,
+    });
+    await this.events.emit(OrganismEventType.ORGANISM_STRATEGY_PROMOTED, this.organismId, {
+      winner,
+      promotedStrategyId,
+      scores,
+      populationId,
+    });
+
+    return result;
+  }
+
+  /**
+   * Promote winner strategy into a loser via controlled mutation (safe config only).
+   */
+  async promoteStrategy(input: {
+    winnerId: string;
+    targetId: string;
+    gene: AgentGeneDefinition;
+    reason?: string;
+  }): Promise<RuntimeAgentRecord> {
+    const winner = await this.repo.getAgent(this.organismId, input.winnerId);
+    const target = await this.repo.getAgent(this.organismId, input.targetId);
+    if (!winner || !target) {
+      throw new Error('Winner or target agent not found');
+    }
+
+    const request: MutationRequest = {
+      reason: input.reason ?? `Promote strategy from ${winner.id}`,
+      mutation: {
+        strategyConfig: { ...winner.strategyConfig, promotedFrom: winner.id },
+        modelConfig: { ...winner.modelConfig },
+        promptChanges: [`Adopt winning strategy patterns from ${winner.name}#${winner.id}`],
+      },
+    };
+
+    return this.mutationEngine.mutate(target, request, input.gene);
+  }
+}
+
+function clamp(n: number, min: number, max: number): number {
+  return Math.max(min, Math.min(max, n));
+}

package/src/evolution/mutation-engine.ts

@@ -0,0 +1,110 @@
+/**
+ * Phase 3 — constrained, auditable mutation (no arbitrary source rewrite).
+ */
+
+import type {
+  AgentGeneDefinition,
+  AgentMutation,
+  AgentMutationRecord,
+  RuntimeAgentRecord,
+} from '../types/organism.types';
+import { OrganismLimitError, OrganismStateError } from '../errors/organism.errors';
+import { OrganismEventEmitter, OrganismEventType } from '../events/organism-events';
+import type { OrganismRepository } from '../persistence/organism-repository';
+
+export interface MutationRequest {
+  reason: string;
+  mutation: AgentMutation;
+}
+
+const DEFAULT_ALLOWED = [
+  'promptChanges',
+  'addedCapabilities',
+  'removedCapabilities',
+  'modelConfig',
+  'strategyConfig',
+];
+
+export class MutationEngine {
+  constructor(
+    private readonly events: OrganismEventEmitter,
+    private readonly repo: OrganismRepository,
+    private readonly organismId: string,
+    private readonly now: () => Date = () => new Date()
+  ) {}
+
+  assertAllowed(gene: AgentGeneDefinition, mutation: AgentMutation): void {
+    if (gene.mutation && gene.mutation.enabled === false) {
+      throw new OrganismLimitError(`Gene ${gene.id} has mutation disabled`);
+    }
+    const allowed = new Set(gene.mutation?.allowedProperties ?? DEFAULT_ALLOWED);
+    for (const key of Object.keys(mutation) as Array<keyof AgentMutation>) {
+      if (mutation[key] !== undefined && !allowed.has(key)) {
+        throw new OrganismLimitError(
+          `Mutation property "${key}" is not allowed for gene ${gene.id}`
+        );
+      }
+    }
+  }
+
+  apply(
+    agent: RuntimeAgentRecord,
+    request: MutationRequest,
+    gene: AgentGeneDefinition
+  ): RuntimeAgentRecord {
+    if (agent.status === 'terminated' || agent.status === 'failed') {
+      throw new OrganismStateError(`Cannot mutate agent ${agent.id} in status ${agent.status}`);
+    }
+    this.assertAllowed(gene, request.mutation);
+
+    const m = request.mutation;
+    if (m.promptChanges?.length) {
+      const appendix = m.promptChanges.map((c) => `- ${c}`).join('\n');
+      agent.systemPrompt = `${agent.systemPrompt ?? ''}\n## Mutation\n${appendix}`.trim();
+    }
+    if (m.addedCapabilities?.length) {
+      agent.capabilities = Array.from(new Set([...agent.capabilities, ...m.addedCapabilities]));
+    }
+    if (m.removedCapabilities?.length) {
+      const remove = new Set(m.removedCapabilities.map((c) => c.toLowerCase()));
+      agent.capabilities = agent.capabilities.filter((c) => !remove.has(c.toLowerCase()));
+    }
+    if (m.modelConfig) {
+      agent.modelConfig = { ...agent.modelConfig, ...m.modelConfig };
+    }
+    if (m.strategyConfig) {
+      agent.strategyConfig = { ...agent.strategyConfig, ...m.strategyConfig };
+    }
+
+    const resultingStrategyId = `${agent.strategyId ?? agent.geneId}:m${agent.mutations.length + 1}`;
+    const record: AgentMutationRecord = {
+      id: `mut_${Date.now()}_${Math.random().toString(36).slice(2, 7)}`,
+      at: this.now(),
+      mutation: { ...m },
+      reason: request.reason,
+      parentStrategyId: agent.strategyId,
+      resultingStrategyId,
+    };
+    agent.mutations = [...agent.mutations, record];
+    agent.strategyId = resultingStrategyId;
+    agent.lastMutationAt = record.at;
+
+    return agent;
+  }
+
+  async mutate(
+    agent: RuntimeAgentRecord,
+    request: MutationRequest,
+    gene: AgentGeneDefinition
+  ): Promise<RuntimeAgentRecord> {
+    const updated = this.apply({ ...agent, mutations: [...agent.mutations] }, request, gene);
+    await this.repo.saveAgent(this.organismId, updated);
+    await this.events.emit(OrganismEventType.ORGANISM_AGENT_MUTATED, this.organismId, {
+      agentId: updated.id,
+      reason: request.reason,
+      mutation: request.mutation,
+      strategyId: updated.strategyId,
+    });
+    return updated;
+  }
+}