@hazeljs/organism 2.0.6

package/src/lifecycle/birth-engine.ts

@@ -0,0 +1,225 @@
+import { createAgentClassFromDna, exportAgentDna, type AgentRuntime } from '@hazeljs/agent';
+import type {
+  AgentBirthProposal,
+  AgentGeneDefinition,
+  AgentGenealogy,
+  AgentReputation,
+  RuntimeAgentRecord,
+  UtilityScore,
+} from '../types/organism.types';
+import { createEmptyWallet } from '../economy/resource-allocator';
+import { OrganismEventEmitter, OrganismEventType } from '../events/organism-events';
+import type { OrganismRepository } from '../persistence/organism-repository';
+import { CapabilityRegistry } from '../core/capability-registry';
+import type { AgentResourceWallet } from '../types/organism.types';
+
+let agentSeq = 0;
+
+function nextAgentId(): string {
+  agentSeq += 1;
+  return `A${agentSeq}`;
+}
+
+export function resetAgentSeqForTests(): void {
+  agentSeq = 0;
+}
+
+function defaultReputation(agentId: string): AgentReputation {
+  return {
+    agentId,
+    score: 0.5,
+    dimensions: {
+      usefulness: 0.5,
+      reliability: 0.5,
+      efficiency: 0.5,
+      policyCompliance: 1,
+      collaboration: 0.5,
+    },
+  };
+}
+
+function defaultUtility(): UtilityScore {
+  return {
+    score: 0.5,
+    valueGenerated: 0,
+    cost: 0,
+    riskPenalty: 0,
+    confidence: 0.5,
+  };
+}
+
+/**
+ * Birth engine — compiles gene + proposal into DNA and registers with AgentRuntime.
+ */
+export class BirthEngine {
+  constructor(
+    private readonly events: OrganismEventEmitter,
+    private readonly repo: OrganismRepository,
+    private readonly capabilities: CapabilityRegistry,
+    private readonly organismId: string,
+    private readonly agentRuntime?: AgentRuntime
+  ) {}
+
+  async spawn(input: {
+    proposal: AgentBirthProposal;
+    gene: AgentGeneDefinition;
+    wallet: AgentResourceWallet;
+    generation?: number;
+    parentAgentId?: string;
+    nameHint?: string;
+  }): Promise<RuntimeAgentRecord> {
+    const id = nextAgentId();
+    const generation = input.generation ?? 1;
+    const specialize = input.proposal.specialize ?? [];
+    const capabilities = Array.from(
+      new Set([...input.gene.capabilities, ...specialize, ...input.proposal.requiredCapabilities])
+    );
+    const nameHint =
+      input.nameHint ??
+      `${input.proposal.needId
+        .split(/[-_]/)
+        .map((p) => p.charAt(0).toUpperCase() + p.slice(1))
+        .join('')}Agent`;
+    const dnaAgentName = `${nameHint}_${id}`;
+    const objective = input.proposal.expectedOutcome;
+
+    const dna = exportAgentDna({
+      name: dnaAgentName,
+      description: input.gene.description ?? input.proposal.reason,
+      systemPrompt:
+        input.gene.initialPrompt ??
+        `You are ${dnaAgentName}. Objective: ${objective}. Capabilities: ${capabilities.join(', ')}.`,
+      tools: [],
+      policies: input.gene.policies,
+      mission: { goal: objective },
+      metadata: {
+        capabilities,
+        organismId: this.organismId,
+        geneId: input.gene.id,
+        needId: input.proposal.needId,
+        terminationCriteria: input.proposal.terminationCriteria,
+      },
+      version: '1.0.0',
+    });
+
+    if (this.agentRuntime) {
+      const AgentClass = createAgentClassFromDna(dna);
+      this.agentRuntime.registerAgent(AgentClass);
+    }
+
+    const agent: RuntimeAgentRecord = {
+      id,
+      name: nameHint,
+      objective,
+      capabilities,
+      geneId: input.gene.id,
+      parentAgentId: input.parentAgentId ?? input.proposal.parentAgentId,
+      generation,
+      status: 'active',
+      reputation: defaultReputation(id),
+      utility: defaultUtility(),
+      wallet: { ...input.wallet },
+      birthProposal: input.proposal,
+      terminationCriteria: input.proposal.terminationCriteria ?? [],
+      createdAt: new Date(),
+      evaluationCount: 0,
+      criticalResponsibility: false,
+      costConsumed: 0,
+      tokensConsumed: 0,
+      valueGenerated: 0,
+      specialize,
+      dnaAgentName,
+      systemPrompt: dna.systemPrompt,
+      permissions: [...capabilities],
+      strategyConfig: {},
+      modelConfig: {},
+      mutations: [],
+      strategyId: `${input.gene.id}:g${generation}`,
+    };
+
+    const genealogy: AgentGenealogy = {
+      agentId: id,
+      parentAgentId: agent.parentAgentId,
+      rootGeneId: input.gene.id,
+      generation,
+      children: [],
+      createdAt: agent.createdAt,
+    };
+
+    await this.repo.saveAgent(this.organismId, agent);
+    await this.repo.saveGenealogy(this.organismId, genealogy);
+
+    if (agent.parentAgentId) {
+      const parentGene = (await this.repo.listGenealogy(this.organismId)).find(
+        (g) => g.agentId === agent.parentAgentId
+      );
+      if (parentGene) {
+        parentGene.children = [...parentGene.children, id];
+        await this.repo.saveGenealogy(this.organismId, parentGene);
+      }
+    }
+
+    this.capabilities.register(id, capabilities);
+
+    await this.events.emit(OrganismEventType.ORGANISM_AGENT_BORN, this.organismId, {
+      organismId: this.organismId,
+      agentId: id,
+      parentAgentId: agent.parentAgentId,
+      reason: input.proposal.reason,
+      generation,
+      geneId: input.gene.id,
+      needId: input.proposal.needId,
+      name: nameHint,
+    });
+
+    return agent;
+  }
+}
+
+/**
+ * Termination engine — release resources, retain genealogy, emit death event.
+ */
+export class TerminationEngine {
+  constructor(
+    private readonly events: OrganismEventEmitter,
+    private readonly repo: OrganismRepository,
+    private readonly capabilities: CapabilityRegistry,
+    private readonly organismId: string,
+    private readonly releaseWallet: (agent: RuntimeAgentRecord) => void
+  ) {}
+
+  async terminate(agentId: string, reason: string): Promise<RuntimeAgentRecord | undefined> {
+    const agent = await this.repo.getAgent(this.organismId, agentId);
+    if (!agent || agent.status === 'terminated') return agent;
+
+    agent.status = 'termination-pending';
+    await this.repo.saveAgent(this.organismId, agent);
+
+    this.releaseWallet(agent);
+    this.capabilities.unregister(agentId);
+
+    agent.status = 'terminated';
+    agent.terminatedAt = new Date();
+    await this.repo.saveAgent(this.organismId, agent);
+
+    const genealogy = (await this.repo.listGenealogy(this.organismId)).find(
+      (g) => g.agentId === agentId
+    );
+    if (genealogy) {
+      genealogy.terminatedAt = agent.terminatedAt;
+      await this.repo.saveGenealogy(this.organismId, genealogy);
+    }
+
+    await this.events.emit(OrganismEventType.ORGANISM_AGENT_TERMINATED, this.organismId, {
+      agentId,
+      reason,
+      finalScore: agent.utility.score,
+      totalCost: agent.costConsumed,
+      totalValue: agent.valueGenerated,
+    });
+
+    return agent;
+  }
+}
+
+export { createEmptyWallet };

package/src/lifecycle/decision-engine.ts

@@ -0,0 +1,158 @@
+import type {
+  AgentBirthProposal,
+  DetectedNeed,
+  OrganismDecision,
+  RuntimeAgentRecord,
+} from '../types/organism.types';
+import { CapabilityRegistry } from '../core/capability-registry';
+import type { AgentGeneDefinition } from '../types/organism.types';
+
+/**
+ * Deterministic decision engine: reuse → specialize → spawn → observe.
+ */
+export class DecisionEngine {
+  constructor(private readonly capabilities: CapabilityRegistry) {}
+
+  decide(input: {
+    need: DetectedNeed;
+    liveAgents: RuntimeAgentRecord[];
+    genes: AgentGeneDefinition[];
+    canSpawn: boolean;
+    spawnBlockReason?: string;
+  }): OrganismDecision {
+    const { need, liveAgents, genes, canSpawn, spawnBlockReason } = input;
+
+    const capable = this.capabilities.findCapableAgents(need.requiredCapabilities, liveAgents);
+    if (capable.length > 0) {
+      const best = capable.sort((a, b) => b.reputation.score - a.reputation.score)[0];
+      return {
+        action: 'delegate',
+        reasoningSummary: `Capable agent ${best.id} already covers ${need.requiredCapabilities.join(', ')}`,
+        confidence: Math.min(0.95, need.confidence + 0.05),
+        targetAgentId: best.id,
+        requiredCapabilities: need.requiredCapabilities,
+        needId: need.need,
+      };
+    }
+
+    const partial = this.capabilities.findPartialAgents(need.requiredCapabilities, liveAgents);
+    const gene = this.selectGene(need.requiredCapabilities, genes);
+
+    if (partial.length > 0 && gene) {
+      const parent = partial[0];
+      const missing = need.requiredCapabilities.filter(
+        (c) => !parent.capabilities.map((x) => x.toLowerCase()).includes(c.toLowerCase())
+      );
+      if (!canSpawn) {
+        return {
+          action: 'observe',
+          reasoningSummary: `Would specialize for ${need.need} but spawn blocked: ${spawnBlockReason}`,
+          confidence: 0.4,
+          needId: need.need,
+        };
+      }
+      const proposal: AgentBirthProposal = {
+        reason: need.reason,
+        needId: need.need,
+        requiredCapabilities: need.requiredCapabilities,
+        expectedOutcome: `Address need ${need.need}`,
+        estimatedCost: 1,
+        expectedUtility: need.urgency,
+        terminationCriteria: [
+          `Need ${need.need} resolved`,
+          'Utility score below 0.2 after 5 evaluations',
+          'No related tasks for evaluation window',
+        ],
+        confidence: need.confidence,
+        geneId: gene.id,
+        specialize: missing,
+        parentAgentId: parent.id,
+      };
+      return {
+        action: 'specialize',
+        reasoningSummary: `Partial agent ${parent.id} exists; spawn specialized agent for missing ${missing.join(', ')}`,
+        confidence: need.confidence,
+        targetAgentId: parent.id,
+        requiredCapabilities: need.requiredCapabilities,
+        resourceRequest: { tokens: 50_000 },
+        birthProposal: proposal,
+        needId: need.need,
+      };
+    }
+
+    if (!gene) {
+      return {
+        action: 'observe',
+        reasoningSummary: `No gene covers required capabilities ${need.requiredCapabilities.join(', ')}`,
+        confidence: 0.5,
+        requiredCapabilities: need.requiredCapabilities,
+        needId: need.need,
+      };
+    }
+
+    if (!canSpawn) {
+      return {
+        action: 'observe',
+        reasoningSummary: `Need ${need.need} requires spawn but blocked: ${spawnBlockReason}`,
+        confidence: 0.4,
+        needId: need.need,
+      };
+    }
+
+    const proposal: AgentBirthProposal = {
+      reason: need.reason,
+      needId: need.need,
+      requiredCapabilities: need.requiredCapabilities,
+      expectedOutcome: `Address need ${need.need}`,
+      estimatedCost: 1,
+      expectedUtility: need.urgency,
+      terminationCriteria: [
+        `Need ${need.need} resolved`,
+        'Utility score below 0.2 after 5 evaluations',
+        'No related tasks for evaluation window',
+      ],
+      confidence: need.confidence,
+      geneId: gene.id,
+      specialize: need.requiredCapabilities.filter(
+        (c) => !gene.capabilities.map((g) => g.toLowerCase()).includes(c.toLowerCase())
+      ),
+    };
+
+    return {
+      action: 'spawn',
+      reasoningSummary: `No capable agent for ${need.need}; spawning from gene ${gene.id}`,
+      confidence: need.confidence,
+      requiredCapabilities: need.requiredCapabilities,
+      resourceRequest: { tokens: 50_000 },
+      birthProposal: proposal,
+      needId: need.need,
+    };
+  }
+
+  selectGene(required: string[], genes: AgentGeneDefinition[]): AgentGeneDefinition | undefined {
+    if (!genes.length) return undefined;
+    const needed = required.map((c) => c.toLowerCase());
+    let best: AgentGeneDefinition | undefined;
+    let bestScore = -1;
+    let bestRatio = -1;
+    let bestPrimaryHit = false;
+    const primary = needed[0];
+    for (const gene of genes) {
+      const caps = new Set(gene.capabilities.map((c) => c.toLowerCase()));
+      const score = needed.filter((n) => caps.has(n)).length;
+      const ratio = score / Math.max(1, gene.capabilities.length);
+      const primaryHit = primary ? caps.has(primary) : false;
+      const better =
+        score > bestScore ||
+        (score === bestScore && ratio > bestRatio) ||
+        (score === bestScore && ratio === bestRatio && primaryHit && !bestPrimaryHit);
+      if (better) {
+        bestScore = score;
+        bestRatio = ratio;
+        bestPrimaryHit = primaryHit;
+        best = gene;
+      }
+    }
+    return best ?? genes[0];
+  }
+}

package/src/lifecycle/reproduction-engine.ts

@@ -0,0 +1,289 @@
+/**
+ * Phase 2 — parent→child reproduction with explicit inheritance policy.
+ */
+
+import type {
+  AgentBirthProposal,
+  AgentGeneDefinition,
+  AgentResourceWallet,
+  InheritancePolicy,
+  OrganismLimits,
+  ReproduceRequest,
+  RuntimeAgentRecord,
+} from '../types/organism.types';
+import { DEFAULT_INHERITANCE_POLICY } 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';
+import { ConstitutionEnforcer } from '../governance/constitution';
+import { BirthEngine } from '../lifecycle/birth-engine';
+import { GenealogyManager } from '../genealogy/genealogy-manager';
+
+export interface ReproductionConfig {
+  cooldownMs: number;
+}
+
+export const DEFAULT_REPRODUCTION_CONFIG: ReproductionConfig = {
+  cooldownMs: 30_000,
+};
+
+export class ReproductionEngine {
+  constructor(
+    private readonly events: OrganismEventEmitter,
+    private readonly repo: OrganismRepository,
+    private readonly birth: BirthEngine,
+    private readonly genealogy: GenealogyManager,
+    private readonly constitution: ConstitutionEnforcer,
+    private readonly organismId: string,
+    private readonly now: () => Date = () => new Date(),
+    private readonly config: ReproductionConfig = DEFAULT_REPRODUCTION_CONFIG
+  ) {}
+
+  resolveInheritance(partial?: InheritancePolicy): InheritancePolicy {
+    return {
+      ...DEFAULT_INHERITANCE_POLICY,
+      ...partial,
+      memory: {
+        strategy:
+          partial?.memory?.strategy ??
+          DEFAULT_INHERITANCE_POLICY.memory?.strategy ??
+          'relevant-only',
+        maxItems: partial?.memory?.maxItems ?? DEFAULT_INHERITANCE_POLICY.memory?.maxItems,
+      },
+      resources: {
+        transferFraction:
+          partial?.resources?.transferFraction ??
+          DEFAULT_INHERITANCE_POLICY.resources?.transferFraction,
+      },
+    };
+  }
+
+  assertCanReproduce(input: {
+    parent: RuntimeAgentRecord;
+    gene: AgentGeneDefinition;
+    limits: OrganismLimits;
+    liveAgents: RuntimeAgentRecord[];
+    liveChildCount: number;
+  }): void {
+    const { parent, gene, limits, liveAgents, liveChildCount } = input;
+
+    if (parent.status === 'terminated' || parent.status === 'failed') {
+      throw new OrganismStateError(`Parent ${parent.id} is not active`);
+    }
+    if (gene.reproduction && gene.reproduction.enabled === false) {
+      throw new OrganismLimitError(`Gene ${gene.id} has reproduction disabled`);
+    }
+    if (parent.generation >= limits.maxGenerationDepth) {
+      throw new OrganismLimitError(
+        `maxGenerationDepth (${limits.maxGenerationDepth}) reached by parent`
+      );
+    }
+    const geneMax = gene.reproduction?.maxChildren;
+    const maxChildren =
+      geneMax != null ? Math.min(geneMax, limits.maxChildrenPerAgent) : limits.maxChildrenPerAgent;
+    if (liveChildCount >= maxChildren) {
+      throw new OrganismLimitError(
+        `maxChildrenPerAgent (${maxChildren}) reached for parent ${parent.id}`
+      );
+    }
+    if (liveAgents.length >= limits.maxAgents) {
+      throw new OrganismLimitError(`maxAgents (${limits.maxAgents}) reached`);
+    }
+    if (parent.lastReproductionAt) {
+      const elapsed = this.now().getTime() - parent.lastReproductionAt.getTime();
+      if (elapsed < this.config.cooldownMs) {
+        throw new OrganismLimitError(
+          `Reproduction cooldown active (${elapsed}ms < ${this.config.cooldownMs}ms)`
+        );
+      }
+    }
+  }
+
+  /**
+   * Build child capabilities: parent caps + specialization.
+   * Permissions must remain a subset of the parent's permission grants.
+   */
+  resolveChildCapabilities(
+    parent: RuntimeAgentRecord,
+    specialization: string[],
+    policy: InheritancePolicy
+  ): { capabilities: string[]; permissions: string[] } {
+    const capabilities = Array.from(new Set([...parent.capabilities, ...specialization]));
+    let permissions: string[];
+    if (policy.permissions === 'none') {
+      permissions = [];
+    } else {
+      // copy and subset both enforce ⊆ parent (never escalate)
+      permissions = [...parent.permissions];
+    }
+    return { capabilities, permissions };
+  }
+
+  transferResources(
+    parent: RuntimeAgentRecord,
+    policy: InheritancePolicy,
+    requestedTokens?: number
+  ): { childWallet: AgentResourceWallet; parentWallet: AgentResourceWallet } {
+    const fraction = policy.resources?.transferFraction ?? 0.25;
+    const parentTokens = parent.wallet.tokensRemaining ?? 0;
+    const parentMoney = parent.wallet.moneyRemaining?.amount ?? 0;
+    const currency = parent.wallet.moneyRemaining?.currency ?? 'USD';
+
+    let tokens = Math.floor(parentTokens * fraction);
+    if (requestedTokens != null) {
+      tokens = Math.min(tokens, requestedTokens, parentTokens);
+    }
+    const money = Math.floor(parentMoney * fraction);
+
+    const childWallet: AgentResourceWallet = {
+      tokensRemaining: tokens,
+      moneyRemaining: { amount: money, currency },
+      computeUnitsRemaining: Math.floor((parent.wallet.computeUnitsRemaining ?? 0) * fraction),
+      toolCallsRemaining: Math.floor((parent.wallet.toolCallsRemaining ?? 0) * fraction),
+    };
+
+    const parentWallet: AgentResourceWallet = {
+      tokensRemaining: parentTokens - tokens,
+      moneyRemaining: { amount: parentMoney - money, currency },
+      computeUnitsRemaining:
+        (parent.wallet.computeUnitsRemaining ?? 0) - (childWallet.computeUnitsRemaining ?? 0),
+      toolCallsRemaining:
+        (parent.wallet.toolCallsRemaining ?? 0) - (childWallet.toolCallsRemaining ?? 0),
+    };
+
+    return { childWallet, parentWallet };
+  }
+
+  buildProposal(
+    parent: RuntimeAgentRecord,
+    request: ReproduceRequest,
+    capabilities: string[]
+  ): AgentBirthProposal {
+    const specialization = request.specialization ?? [];
+    const needId = request.needId ?? `specialize-${specialization.join('-') || parent.id}`;
+    return {
+      reason: request.reason,
+      needId,
+      requiredCapabilities: capabilities,
+      expectedOutcome:
+        request.objective ??
+        `Specialized descendant of ${parent.name} for ${specialization.join(', ') || 'focused work'}`,
+      estimatedCost: 1,
+      expectedUtility: parent.utility.score,
+      terminationCriteria: request.terminationCriteria ?? [
+        `Specialization ${specialization.join(', ') || needId} complete`,
+        'Utility score below 0.2 after 5 evaluations',
+        'No related tasks for evaluation window',
+      ],
+      confidence: request.confidence ?? 0.8,
+      geneId: parent.geneId,
+      specialize: specialization,
+      parentAgentId: parent.id,
+    };
+  }
+
+  async reproduce(input: {
+    parent: RuntimeAgentRecord;
+    gene: AgentGeneDefinition;
+    request: ReproduceRequest;
+    limits: OrganismLimits;
+    liveAgents: RuntimeAgentRecord[];
+    /** When true, child wallet comes from organism pool allocation instead of parent. */
+    poolWallet?: AgentResourceWallet;
+  }): Promise<{ child: RuntimeAgentRecord; parent: RuntimeAgentRecord }> {
+    const policy = this.resolveInheritance(input.request.inheritance);
+    const liveChildCount = await this.genealogy.countLiveChildren(
+      input.parent.id,
+      input.liveAgents
+    );
+    this.assertCanReproduce({
+      parent: input.parent,
+      gene: input.gene,
+      limits: input.limits,
+      liveAgents: input.liveAgents,
+      liveChildCount,
+    });
+
+    this.constitution.assertAllows('reproduce', {});
+
+    const specialization = input.request.specialization ?? [];
+    const { capabilities, permissions } = this.resolveChildCapabilities(
+      input.parent,
+      specialization,
+      policy
+    );
+
+    let childWallet: AgentResourceWallet;
+    let parentWallet = input.parent.wallet;
+    if (input.poolWallet) {
+      childWallet = input.poolWallet;
+    } else {
+      const transfer = this.transferResources(input.parent, policy, input.request.tokens);
+      childWallet = transfer.childWallet;
+      parentWallet = transfer.parentWallet;
+    }
+
+    const proposal = this.buildProposal(input.parent, input.request, capabilities);
+    const generation = input.parent.generation + 1;
+
+    input.parent.status = 'reproducing';
+    await this.repo.saveAgent(this.organismId, input.parent);
+
+    const child = await this.birth.spawn({
+      proposal,
+      gene: input.gene,
+      wallet: childWallet,
+      generation,
+      parentAgentId: input.parent.id,
+      nameHint: specialization.length
+        ? `${specialization
+            .map((s) =>
+              s
+                .split(/[-_]/)
+                .map((p) => p.charAt(0).toUpperCase() + p.slice(1))
+                .join('')
+            )
+            .join('')}Agent`
+        : `${input.parent.name}Child`,
+    });
+
+    // Apply inheritance overlays
+    child.permissions = permissions;
+    child.systemPrompt =
+      policy.strategies !== false
+        ? [
+            input.parent.systemPrompt ?? input.gene.initialPrompt ?? '',
+            specialization.length ? `Specialization: ${specialization.join(', ')}` : '',
+          ]
+            .filter(Boolean)
+            .join('\n')
+        : input.gene.initialPrompt;
+    if (policy.strategies !== false) {
+      child.strategyConfig = { ...input.parent.strategyConfig };
+    }
+    if (policy.modelSettings !== false) {
+      child.modelConfig = { ...input.parent.modelConfig };
+    }
+    child.strategyId = input.parent.strategyId
+      ? `${input.parent.strategyId}:g${generation}`
+      : `${input.parent.geneId}:g${generation}`;
+
+    await this.repo.saveAgent(this.organismId, child);
+
+    input.parent.wallet = parentWallet;
+    input.parent.status = 'active';
+    input.parent.lastReproductionAt = this.now();
+    await this.repo.saveAgent(this.organismId, input.parent);
+
+    await this.events.emit(OrganismEventType.ORGANISM_AGENT_REPRODUCED, this.organismId, {
+      parentAgentId: input.parent.id,
+      childAgentId: child.id,
+      generation,
+      specialization,
+      reason: input.request.reason,
+      inheritance: policy,
+    });
+
+    return { child, parent: input.parent };
+  }
+}