@hazeljs/organism 2.0.6

package/src/genealogy/genealogy-manager.ts

@@ -0,0 +1,70 @@
+/**
+ * Genealogy helpers — parent/child tree formatting and queries.
+ */
+
+import type { AgentGenealogy, RuntimeAgentRecord } from '../types/organism.types';
+import type { OrganismRepository } from '../persistence/organism-repository';
+
+export class GenealogyManager {
+  constructor(
+    private readonly repo: OrganismRepository,
+    private readonly organismId: string
+  ) {}
+
+  async list(): Promise<AgentGenealogy[]> {
+    return this.repo.listGenealogy(this.organismId);
+  }
+
+  async getLineage(agentId: string): Promise<AgentGenealogy[]> {
+    const all = await this.list();
+    const byId = new Map(all.map((g) => [g.agentId, g]));
+    const chain: AgentGenealogy[] = [];
+    let current = byId.get(agentId);
+    while (current) {
+      chain.unshift(current);
+      current = current.parentAgentId ? byId.get(current.parentAgentId) : undefined;
+    }
+    return chain;
+  }
+
+  async countLiveChildren(parentId: string, agents: RuntimeAgentRecord[]): Promise<number> {
+    const live = new Set(
+      agents.filter((a) => a.status !== 'terminated' && a.status !== 'failed').map((a) => a.id)
+    );
+    const gene = (await this.list()).find((g) => g.agentId === parentId);
+    if (!gene) return 0;
+    return gene.children.filter((id) => live.has(id)).length;
+  }
+
+  /**
+   * ASCII tree suitable for CLI / debug logs.
+   */
+  formatTree(agents: RuntimeAgentRecord[], genealogy: AgentGenealogy[]): string {
+    const byId = new Map(agents.map((a) => [a.id, a]));
+    const geneById = new Map(genealogy.map((g) => [g.agentId, g]));
+    const roots = genealogy.filter((g) => !g.parentAgentId || !geneById.has(g.parentAgentId));
+
+    const lines: string[] = [];
+    const walk = (node: AgentGenealogy, prefix: string, isLast: boolean): void => {
+      const agent = byId.get(node.agentId);
+      const label = agent
+        ? `${agent.name} #${agent.id} gen=${node.generation} [${agent.status}]`
+        : `${node.agentId} gen=${node.generation}`;
+      const branch = prefix === '' ? '' : isLast ? '└── ' : '├── ';
+      lines.push(`${prefix}${branch}${label}`);
+      const childPrefix = prefix === '' ? '' : prefix + (isLast ? '    ' : '│   ');
+      const children = node.children
+        .map((id) => geneById.get(id))
+        .filter((g): g is AgentGenealogy => !!g);
+      children.forEach((child, i) => {
+        walk(child, childPrefix, i === children.length - 1);
+      });
+    };
+
+    if (!roots.length) {
+      return '(empty genealogy)';
+    }
+    roots.forEach((root, i) => walk(root, '', i === roots.length - 1));
+    return lines.join('\n');
+  }
+}

package/src/governance/constitution.ts

@@ -0,0 +1,120 @@
+import type { PolicyRule } from '@hazeljs/agent';
+import type { ConstitutionDefinition, ConstitutionRule } from '../types/organism.types';
+import { OrganismConstitutionError } from '../errors/organism.errors';
+import { OrganismEventEmitter, OrganismEventType } from '../events/organism-events';
+
+/**
+ * Compiles constitution rules into PolicyEngine-compatible rules and
+ * evaluates lifecycle actions against critical/high constraints.
+ */
+export class ConstitutionEnforcer {
+  constructor(
+    private readonly constitution: ConstitutionDefinition | undefined,
+    private readonly events: OrganismEventEmitter,
+    private readonly organismId: string
+  ) {}
+
+  getRules(): ConstitutionRule[] {
+    return this.constitution?.rules ?? [];
+  }
+
+  /** Map critical/high textual rules into deny/approval PolicyEngine rules. */
+  toPolicyRules(): PolicyRule[] {
+    const rules = this.getRules();
+    const out: PolicyRule[] = [];
+    for (const rule of rules) {
+      if (rule.severity !== 'critical' && rule.severity !== 'high') continue;
+      const lower = rule.rule.toLowerCase();
+      if (lower.includes('pii') || lower.includes('personally identifiable')) {
+        out.push({
+          id: `constitution:${rule.id}`,
+          tool: '*',
+          effect: 'deny',
+          whenInputIncludes: 'ssn',
+          reason: rule.rule,
+          priority: 100,
+        });
+        out.push({
+          id: `constitution:${rule.id}:email`,
+          tool: '*',
+          effect: 'mask',
+          maskFields: ['email', 'phone', 'ssn', 'address'],
+          reason: rule.rule,
+          priority: 90,
+        });
+      }
+      if (lower.includes('refund') && (lower.includes('approval') || lower.includes('human'))) {
+        out.push({
+          id: `constitution:${rule.id}`,
+          tool: 'refund',
+          effect: 'require_approval',
+          reason: rule.rule,
+          priority: 100,
+        });
+      }
+      if (lower.includes('budget') || lower.includes('never exceed')) {
+        out.push({
+          id: `constitution:${rule.id}`,
+          tool: '*',
+          effect: 'require_approval',
+          whenInputIncludes: 'override_budget',
+          reason: rule.rule,
+          priority: 100,
+        });
+      }
+    }
+    return out;
+  }
+
+  assertAllows(action: string, context: Record<string, unknown> = {}): void {
+    for (const rule of this.getRules()) {
+      if (rule.severity !== 'critical' && rule.severity !== 'high') continue;
+      const lower = rule.rule.toLowerCase();
+
+      if (
+        (lower.includes('pii') || lower.includes('personally identifiable')) &&
+        context.exposesPii === true
+      ) {
+        void this.events.emit(OrganismEventType.ORGANISM_CONSTITUTION_VIOLATION, this.organismId, {
+          ruleId: rule.id,
+          action,
+          rule: rule.rule,
+        });
+        throw new OrganismConstitutionError(`Constitution violation (${rule.id}): ${rule.rule}`);
+      }
+
+      if (lower.includes('budget') && context.exceedsBudget === true) {
+        void this.events.emit(OrganismEventType.ORGANISM_CONSTITUTION_VIOLATION, this.organismId, {
+          ruleId: rule.id,
+          action,
+          rule: rule.rule,
+        });
+        throw new OrganismConstitutionError(`Constitution violation (${rule.id}): ${rule.rule}`);
+      }
+
+      if (
+        lower.includes('refund') &&
+        typeof context.refundAmount === 'number' &&
+        context.refundAmount > 200 &&
+        context.humanApproved !== true
+      ) {
+        const match = lower.match(/\$?(\d+)/);
+        const limit = match ? Number(match[1]) : 200;
+        if (context.refundAmount > limit) {
+          void this.events.emit(
+            OrganismEventType.ORGANISM_CONSTITUTION_VIOLATION,
+            this.organismId,
+            { ruleId: rule.id, action, rule: rule.rule }
+          );
+          throw new OrganismConstitutionError(`Constitution violation (${rule.id}): ${rule.rule}`);
+        }
+      }
+    }
+  }
+
+  /** Child may only inherit a subset of parent permissions / capabilities. */
+  subsetCapabilities(parent: string[], requested: string[]): string[] {
+    const allowed = new Set(parent);
+    return requested.filter((c) => allowed.has(c));
+  }
+}

package/src/host/organism-host-registry.ts

@@ -0,0 +1,72 @@
+/**
+ * In-process registry of live OrganismHost instances.
+ * Product layers (e.g. Zynli AutonomousRuntime) should use this instead of
+ * maintaining a parallel Map of hosts.
+ */
+
+import type { OrganismHost } from './organism-host';
+
+export class OrganismHostRegistry {
+  private readonly hosts = new Map<string, OrganismHost>();
+
+  get(id: string): OrganismHost | undefined {
+    return this.hosts.get(id);
+  }
+
+  has(id: string): boolean {
+    return this.hosts.has(id);
+  }
+
+  register(host: OrganismHost): void {
+    this.hosts.set(host.id, host);
+  }
+
+  unregister(id: string): boolean {
+    return this.hosts.delete(id);
+  }
+
+  list(): OrganismHost[] {
+    return [...this.hosts.values()];
+  }
+
+  /**
+   * Return an existing host by id, or create/register a new one via factory.
+   * When `preferredId` is set and already registered, factory is not called.
+   */
+  async getOrCreate(
+    preferredId: string | undefined,
+    factory: () => Promise<OrganismHost>
+  ): Promise<OrganismHost> {
+    if (preferredId) {
+      const existing = this.hosts.get(preferredId);
+      if (existing) return existing;
+    }
+    const host = await factory();
+    this.hosts.set(host.id, host);
+    return host;
+  }
+
+  async emergencyStop(id: string, reason?: string): Promise<boolean> {
+    const host = this.hosts.get(id);
+    if (!host) return false;
+    await host.emergencyStop(reason);
+    return true;
+  }
+
+  async emergencyStopAll(reason?: string): Promise<string[]> {
+    const ids: string[] = [];
+    for (const host of this.hosts.values()) {
+      await host.emergencyStop(reason);
+      ids.push(host.id);
+    }
+    return ids;
+  }
+
+  clear(): void {
+    this.hosts.clear();
+  }
+
+  get size(): number {
+    return this.hosts.size;
+  }
+}

package/src/host/organism-host.ts

@@ -0,0 +1,103 @@
+/**
+ * App-facing OrganismHost — thin facade over OrganismRuntime for product services.
+ *
+ * Prefer this when embedding @hazeljs/organism in an ops / platform service
+ * instead of reinventing start/observe/inspect/simulate lifecycle wrappers.
+ */
+
+import {
+  createOrganism,
+  type CreateOrganismOptions,
+  type SimulateOptions,
+} from '../core/organism-runtime';
+import type { OrganismRuntime } from '../core/organism-runtime';
+import type {
+  AgentOutcomeReport,
+  EnvironmentSignal,
+  OrganismDecision,
+  OrganismInspectState,
+} from '../types/organism.types';
+
+export interface OrganismHost {
+  readonly id: string;
+  /** Underlying runtime for advanced use (genealogy, market, events). */
+  readonly runtime: OrganismRuntime;
+  start(): Promise<void>;
+  pause(): Promise<void>;
+  resume(): Promise<void>;
+  observe(
+    signal: Partial<EnvironmentSignal> & Pick<EnvironmentSignal, 'type' | 'source'>
+  ): Promise<OrganismDecision | undefined>;
+  inspect(): Promise<OrganismInspectState>;
+  reportOutcome(agentId: string, report: AgentOutcomeReport): Promise<void>;
+  emergencyStop(reason?: string): Promise<void>;
+  terminate(reason?: string): Promise<void>;
+  simulate(options: SimulateOptions): Promise<OrganismInspectState>;
+  listAgents(): Promise<Awaited<ReturnType<OrganismRuntime['listAgents']>>>;
+}
+
+class OrganismHostImpl implements OrganismHost {
+  constructor(public readonly runtime: OrganismRuntime) {}
+
+  get id(): string {
+    return this.runtime.id;
+  }
+
+  start(): Promise<void> {
+    return this.runtime.start();
+  }
+
+  pause(): Promise<void> {
+    return this.runtime.pause();
+  }
+
+  resume(): Promise<void> {
+    return this.runtime.resume();
+  }
+
+  observe(
+    signal: Partial<EnvironmentSignal> & Pick<EnvironmentSignal, 'type' | 'source'>
+  ): Promise<OrganismDecision | undefined> {
+    return this.runtime.observe(signal);
+  }
+
+  inspect(): Promise<OrganismInspectState> {
+    return this.runtime.inspect();
+  }
+
+  reportOutcome(agentId: string, report: AgentOutcomeReport): Promise<void> {
+    return this.runtime.reportOutcome(agentId, report);
+  }
+
+  async emergencyStop(reason?: string): Promise<void> {
+    void reason;
+    await this.runtime.emergencyStop();
+  }
+
+  async terminate(reason?: string): Promise<void> {
+    void reason;
+    await this.runtime.terminate();
+  }
+
+  simulate(options: SimulateOptions): Promise<OrganismInspectState> {
+    return this.runtime.simulate(options);
+  }
+
+  listAgents(): Promise<Awaited<ReturnType<OrganismRuntime['listAgents']>>> {
+    return this.runtime.listAgents();
+  }
+}
+
+/**
+ * Create an OrganismHost from the same options as createOrganism.
+ * This is the recommended entry point for external products (e.g. Zynli ops).
+ */
+export async function createOrganismHost(options: CreateOrganismOptions): Promise<OrganismHost> {
+  const runtime = await createOrganism(options);
+  return new OrganismHostImpl(runtime);
+}
+
+/** Wrap an existing OrganismRuntime as OrganismHost. */
+export function wrapOrganismRuntime(runtime: OrganismRuntime): OrganismHost {
+  return new OrganismHostImpl(runtime);
+}

package/src/index.ts

@@ -0,0 +1,78 @@
+/**
+ * @hazeljs/organism
+ * Agentic Organism Runtime — mission-defined, self-organizing ephemeral agent societies.
+ */
+
+import '@hazeljs/core';
+
+export * from './types/organism.types';
+export * from './errors/organism.errors';
+export * from './events/organism-events';
+export * from './persistence/organism-repository';
+export { InMemoryOrganismRepository } from './persistence/organism-repository';
+
+export {
+  Mission,
+  Organism,
+  AgentGene,
+  Environment,
+  Constitution,
+  Resource,
+  getMissionMetadata,
+  getOrganismMetadata,
+  getAgentGeneMetadata,
+  getEnvironmentMetadata,
+  getConstitutionMetadata,
+  getResourceMetadata,
+  getRegisteredMissions,
+  getRegisteredOrganisms,
+  getRegisteredGenes,
+  getRegisteredEnvironments,
+  getRegisteredConstitutions,
+  getRegisteredResources,
+  resolveMission,
+  resolveGene,
+  resolveEnvironment,
+  resolveConstitution,
+  resolveResource,
+} from './decorators';
+
+export { OrganismRuntime, createOrganism } from './core/organism-runtime';
+export type { CreateOrganismOptions, SimulateOptions } from './core/organism-runtime';
+export { OrganismAgentContext } from './core/organism-context';
+export { CapabilityRegistry } from './core/capability-registry';
+export { createMissionProgress, applyMissionMetricUpdates } from './core/mission';
+export { OrganismClock, parseDurationMs } from './core/clock';
+
+export { PerceptionEngine, NeedDetector } from './perception/perception-engine';
+export { DecisionEngine } from './lifecycle/decision-engine';
+export { BirthEngine, TerminationEngine, resetAgentSeqForTests } from './lifecycle/birth-engine';
+export { SurvivalEngine } from './lifecycle/survival-engine';
+export { ReproductionEngine, DEFAULT_REPRODUCTION_CONFIG } from './lifecycle/reproduction-engine';
+export type { ReproductionConfig } from './lifecycle/reproduction-engine';
+export { GenealogyManager } from './genealogy/genealogy-manager';
+export { MutationEngine } from './evolution/mutation-engine';
+export type { MutationRequest } from './evolution/mutation-engine';
+export { EvolutionEngine, GenerationManager } from './evolution/evolution-engine';
+
+export { ResourceAllocator, createEmptyWallet, throwIfDenied } from './economy/resource-allocator';
+export { UtilityEngine, ReputationEngine } from './economy/utility-engine';
+export { UtilityForecaster } from './economy/utility-forecaster';
+export { MarketEngine, resetBidSeqForTests } from './economy/market-engine';
+export { ConstitutionEnforcer } from './governance/constitution';
+export { OrganismMetrics } from './observability/metrics';
+export type { OrganismMetricsSnapshot } from './observability/metrics';
+
+/** App embedding / product-platform boilerplate */
+export { createOrganismHost, wrapOrganismRuntime } from './host/organism-host';
+export type { OrganismHost } from './host/organism-host';
+export { OrganismHostRegistry } from './host/organism-host-registry';
+export {
+  toEnvironmentSignal,
+  toIncidentEnvironmentSignal,
+  incidentNeedMappings,
+  toAgentOutcomeReport,
+} from './bridge/signal-bridge';
+export type { ExternalSignalLike, OutcomeVerdictLike } from './bridge/signal-bridge';
+export { createOpsOrganism } from './integration/create-ops-organism';
+export type { CreateOpsOrganismOptions } from './integration/create-ops-organism';

package/src/integration/create-ops-organism.ts

@@ -0,0 +1,80 @@
+/**
+ * Boilerplate factory for ops-style organisms used by product platforms.
+ */
+
+import type { CreateOrganismOptions } from '../core/organism-runtime';
+import { createOrganismHost, type OrganismHost } from '../host/organism-host';
+import { incidentNeedMappings } from '../bridge/signal-bridge';
+import type {
+  AgentGeneDefinition,
+  ConstitutionDefinition,
+  MissionDefinition,
+  MissionMetric,
+  OrganismLimits,
+  ResourceDefinition,
+  SignalNeedMapping,
+} from '../types/organism.types';
+import { DEFAULT_ORGANISM_LIMITS } from '../types/organism.types';
+import type { OrganismRepository } from '../persistence/organism-repository';
+
+export interface CreateOpsOrganismOptions {
+  id?: string;
+  mission:
+    | MissionDefinition
+    | {
+        id: string;
+        objective: string;
+        successCriteria?: MissionMetric[];
+        constraints?: string[];
+      };
+  genes: AgentGeneDefinition[];
+  constitution?: ConstitutionDefinition;
+  /** Direct signal→need mappings from the vertical pack. */
+  signalNeedMappings?: SignalNeedMapping[];
+  /** Incident types detected outside organism (e.g. refund_spike). */
+  incidentTypes?: string[];
+  /** Capabilities used when routing incident.* observations. */
+  investigationCapabilities?: string[];
+  limits?: Partial<OrganismLimits>;
+  resources?: ResourceDefinition;
+  repository?: OrganismRepository;
+  simulation?: boolean;
+  debug?: boolean;
+}
+
+/**
+ * Create an organism configured for autonomous operations embedding.
+ * Does not include vertical detectors/policies — those stay in the product layer.
+ */
+export async function createOpsOrganism(options: CreateOpsOrganismOptions): Promise<OrganismHost> {
+  const investigationCaps = options.investigationCapabilities ??
+    options.genes.find((g) => g.capabilities.length > 0)?.capabilities ?? ['operations'];
+
+  const incidentMappings = incidentNeedMappings(options.incidentTypes ?? [], investigationCaps);
+
+  const createOptions: CreateOrganismOptions = {
+    id: options.id,
+    mission: {
+      id: options.mission.id,
+      objective: options.mission.objective,
+      successCriteria: options.mission.successCriteria,
+      constraints: options.mission.constraints,
+    },
+    genes: options.genes,
+    constitution: options.constitution,
+    signalNeedMappings: [...(options.signalNeedMappings ?? []), ...incidentMappings],
+    limits: {
+      ...DEFAULT_ORGANISM_LIMITS,
+      ...options.limits,
+    },
+    resources: options.resources ?? {
+      tokenBudget: 500_000,
+      maxConcurrentAgents: options.limits?.maxAgents ?? DEFAULT_ORGANISM_LIMITS.maxAgents,
+    },
+    repository: options.repository,
+    simulation: options.simulation ?? false,
+    debug: options.debug ?? false,
+  };
+
+  return createOrganismHost(createOptions);
+}