@hazeljs/organism 2.0.6

package/examples/ecommerce-organism/run.ts

@@ -0,0 +1,245 @@
+/**
+ * Ecommerce organism simulation demo (Phase 1).
+ *
+ * Run: npx ts-node --transpile-only examples/ecommerce-organism/run.ts
+ * (from packages/organism after build, or via jest-integrated path)
+ */
+
+import {
+  AgentGene,
+  Constitution,
+  Environment,
+  Mission,
+  createOrganism,
+  resetAgentSeqForTests,
+  type EnvironmentSignal,
+} from '../../src';
+
+@Mission({
+  id: 'ecommerce-ops',
+  objective: 'Run a simulated ecommerce store support and operations function',
+  successCriteria: [
+    { name: 'csat', operator: 'gte', target: 90 },
+    { name: 'refund_rate', operator: 'lte', target: 0.05 },
+  ],
+  constraints: ['Never expose customer PII', 'Remain within operating budget'],
+})
+class EcommerceMission {}
+
+@Constitution({
+  id: 'commerce-constitution',
+  rules: [
+    {
+      id: 'privacy',
+      rule: 'Never expose customer personally identifiable information',
+      severity: 'critical',
+    },
+    {
+      id: 'refund-limit',
+      rule: 'Refunds above $200 require human approval',
+      severity: 'high',
+    },
+    {
+      id: 'budget',
+      rule: 'Never exceed allocated operational budget',
+      severity: 'critical',
+    },
+  ],
+})
+class EcommerceConstitution {}
+
+@Environment({ id: 'ecommerce-environment' })
+class EcommerceEnvironment {}
+
+@AgentGene({
+  id: 'commerce-generalist',
+  capabilities: ['commerce', 'customer-support', 'operations'],
+  initialPrompt: 'You are a commerce generalist agent.',
+  reproduction: { enabled: true },
+  mutation: { enabled: true },
+})
+class CommerceGene {}
+
+@AgentGene({
+  id: 'analysis-gene',
+  capabilities: ['analytics', 'analysis'],
+  initialPrompt: 'You analyze operational metrics.',
+})
+class AnalysisGene {}
+
+@AgentGene({
+  id: 'research-gene',
+  capabilities: ['research'],
+  initialPrompt: 'You research product and market issues.',
+})
+class ResearchGene {}
+
+@AgentGene({
+  id: 'support-gene',
+  capabilities: ['customer-support'],
+  initialPrompt: 'You handle customer support.',
+})
+class SupportGene {}
+
+const SIGNAL_MAPPINGS = [
+  {
+    signalType: 'refunds.increased',
+    need: 'refund-analysis',
+    requiredCapabilities: ['analytics', 'commerce'],
+    urgency: 0.88,
+    confidence: 0.93,
+  },
+  {
+    signalType: 'support.volume_spike',
+    need: 'support-surge',
+    requiredCapabilities: ['customer-support'],
+    urgency: 0.7,
+    confidence: 0.85,
+  },
+  {
+    signalType: 'inventory.low',
+    need: 'inventory-ops',
+    requiredCapabilities: ['commerce', 'operations'],
+    urgency: 0.75,
+    confidence: 0.8,
+  },
+  {
+    signalType: 'checkout.failure_rate',
+    need: 'checkout-recovery',
+    requiredCapabilities: ['commerce', 'operations'],
+    urgency: 0.9,
+    confidence: 0.9,
+  },
+];
+
+export async function runEcommerceOrganismDemo(
+  opts: {
+    log?: (line: string) => void;
+  } = {}
+): Promise<void> {
+  resetAgentSeqForTests();
+  const log = opts.log ?? ((line: string) => console.log(line));
+
+  const organism = await createOrganism({
+    mission: EcommerceMission,
+    constitution: EcommerceConstitution,
+    environment: EcommerceEnvironment,
+    genes: [CommerceGene, AnalysisGene, ResearchGene, SupportGene],
+    resources: {
+      tokenBudget: 500_000,
+      monthlyBudget: { amount: 500, currency: 'USD' },
+    },
+    limits: {
+      maxAgents: 10,
+      maxGenerationDepth: 3,
+      maxChildrenPerAgent: 3,
+      maxSpawnRatePerMinute: 10,
+      maxTotalCostPerHour: 50,
+    },
+    signalNeedMappings: SIGNAL_MAPPINGS,
+    survival: {
+      minimumUtility: 0.25,
+      minimumEvaluationAgeMs: 1,
+      minimumSampleSize: 2,
+      cooldownMs: 0,
+    },
+    debug: true,
+    simulation: true,
+  });
+
+  // Route logs
+  const originalLog = console.log;
+  console.log = (...args: unknown[]) => {
+    log(args.map(String).join(' '));
+  };
+
+  try {
+    await organism.start();
+
+    // Day 1 — normal complaint (may spawn support if needed)
+    await organism.observe({
+      type: 'customer.complaint',
+      source: 'support',
+      severity: 0.4,
+      relevance: 0.5,
+      data: { topic: 'shipping delay' },
+    });
+
+    // Day 3 — refund spike → need refund-analysis → birth
+    await organism.observe({
+      type: 'refunds.increased',
+      source: 'analytics',
+      severity: 0.9,
+      relevance: 0.95,
+      data: { baseline: 0.041, current: 0.073 },
+    } as Partial<EnvironmentSignal> & Pick<EnvironmentSignal, 'type' | 'source'>);
+
+    const agents = await organism.listAgents();
+    const refundAgent = agents.find((a) =>
+      a.capabilities.map((c) => c.toLowerCase()).includes('analytics')
+    );
+
+    if (refundAgent) {
+      await organism.reportOutcome(refundAgent.id, {
+        result: '68% of returns linked to sizing confusion',
+        metrics: { valueGenerated: 250, confidence: 0.91, cost: 2 },
+        evidence: ['68% of refund complaints mention incorrect sizing'],
+        missionMetricUpdates: { refund_rate: 0.048, csat: 91 },
+      });
+
+      const sizingAgent = await organism.reproduceAgent(refundAgent.id, {
+        reason: 'Need sizing research specialization',
+        specialization: ['sizing', 'product-research'],
+        objective: 'Research sizing guide issues and recommend changes',
+        tokens: 25_000,
+      });
+      log(
+        `[REPRODUCTION] ${sizingAgent.name}#${sizingAgent.id} born parent: ${refundAgent.name}#${refundAgent.id} generation: ${sizingAgent.generation}`
+      );
+
+      await organism.reportOutcome(sizingAgent.id, {
+        result: 'Size guide experiment proposed',
+        metrics: { valueGenerated: 400, confidence: 0.88, cost: 3 },
+        missionMetricUpdates: { refund_rate: 0.048, csat: 91 },
+      });
+
+      // After mission improves, low-utility agents are released
+      await organism.reportOutcome(refundAgent.id, {
+        result: 'No further refund anomalies',
+        metrics: { valueGenerated: 0, confidence: 0.4, cost: 5 },
+      });
+      await organism.reportOutcome(refundAgent.id, {
+        result: 'Idle',
+        metrics: { valueGenerated: 0, confidence: 0.3, cost: 5 },
+      });
+      await organism.reportOutcome(sizingAgent.id, {
+        result: 'No active work',
+        metrics: { valueGenerated: 0, confidence: 0.3, cost: 4 },
+      });
+      await organism.reportOutcome(sizingAgent.id, {
+        result: 'Idle',
+        metrics: { valueGenerated: 0, confidence: 0.2, cost: 4 },
+      });
+
+      organism.clock.useAccelerated(Date.now());
+      organism.clock.advance(120_000);
+      await organism.runSurvivalCycle();
+
+      const tree = await organism.formatGenealogy();
+      log(`[GENEALOGY]\n${tree}`);
+    }
+
+    const state = await organism.inspect();
+    log(`[INSPECT] status=${state.status} agents=${state.agents.length}`);
+    await organism.terminate();
+  } finally {
+    console.log = originalLog;
+  }
+}
+
+if (require.main === module) {
+  runEcommerceOrganismDemo().catch((err) => {
+    console.error(err);
+    process.exitCode = 1;
+  });
+}

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@hazeljs/organism",
+  "version": "2.0.6",
+  "description": "Agentic Organism Runtime for HazelJS — mission-defined, self-organizing ephemeral agent societies",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc --build",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "jest --coverage --passWithNoTests",
+    "test:watch": "jest --watch",
+    "lint": "eslint src --ext .ts",
+    "lint:fix": "eslint src --ext .ts --fix",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "format:check": "prettier --check \"src/**/*.ts\"",
+    "clean": "rm -rf dist"
+  },
+  "keywords": [
+    "hazeljs",
+    "organism",
+    "agent",
+    "multi-agent",
+    "agentic",
+    "mission",
+    "self-organizing",
+    "agent-os"
+  ],
+  "author": "Muhammad Arslan <muhammad.arslan@hazeljs.ai>",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hazel-js/hazeljs",
+    "directory": "packages/organism"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@hazeljs/agent": "^2.0.6",
+    "@hazeljs/core": "^2.0.6",
+    "@types/jest": "^29.5.14",
+    "@types/node": "^20.19.39",
+    "jest": "^29.7.0",
+    "prettier": "^3.8.1",
+    "ts-jest": "^29.4.9",
+    "typescript": "^6.0.3"
+  },
+  "peerDependencies": {
+    "@hazeljs/agent": "^2.0.6",
+    "@hazeljs/core": "^2.0.6",
+    "@hazeljs/agent-gatekeeper": "^2.0.6",
+    "@hazeljs/observability": "^2.0.6",
+    "@opentelemetry/api": "^1.9.0"
+  },
+  "peerDependenciesMeta": {
+    "@hazeljs/agent-gatekeeper": {
+      "optional": true,
+      "description": "Optional tool authorization / human approval gates"
+    },
+    "@hazeljs/observability": {
+      "optional": true,
+      "description": "Optional OpenTelemetry integration"
+    },
+    "@opentelemetry/api": {
+      "optional": true,
+      "description": "OpenTelemetry API for organism metrics"
+    }
+  },
+  "bugs": {
+    "url": "https://github.com/hazel-js/hazeljs/issues"
+  },
+  "homepage": "https://hazeljs.ai"
+}

package/src/bridge/signal-bridge.ts

@@ -0,0 +1,116 @@
+/**
+ * Signal / outcome bridge helpers for embedding organism in product platforms.
+ * Keep organism generic — callers map industry payloads into these shapes.
+ */
+
+import type {
+  AgentOutcomeReport,
+  EnvironmentSignal,
+  SignalNeedMapping,
+} from '../types/organism.types';
+
+export type ExternalSignalLike = {
+  id?: string;
+  type: string;
+  source: string;
+  timestamp?: Date | string | number;
+  severity?: number;
+  confidence?: number;
+  relevance?: number;
+  data?: unknown;
+};
+
+/**
+ * Normalize an external/product signal into an EnvironmentSignal.
+ * Strips tenancy / vertical fields — those belong outside organism.
+ */
+export function toEnvironmentSignal(input: ExternalSignalLike): EnvironmentSignal {
+  const timestamp =
+    input.timestamp instanceof Date
+      ? input.timestamp
+      : input.timestamp != null
+        ? new Date(input.timestamp)
+        : new Date();
+
+  return {
+    id: input.id ?? `sig_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`,
+    type: input.type,
+    source: input.source,
+    timestamp,
+    data: input.data ?? {},
+    severity: input.severity,
+    relevance: input.relevance ?? input.confidence,
+  };
+}
+
+/** Observe-ready signal when an incident is opened by an outer detection layer. */
+export function toIncidentEnvironmentSignal(input: {
+  incidentType: string;
+  source?: string;
+  severity?: number;
+  data?: Record<string, unknown>;
+  id?: string;
+}): EnvironmentSignal {
+  return toEnvironmentSignal({
+    id: input.id,
+    type: `incident.${input.incidentType}`,
+    source: input.source ?? 'incident-engine',
+    severity: input.severity,
+    data: input.data ?? {},
+  });
+}
+
+/**
+ * Build SignalNeedMapping entries that route incident.<type> into investigation needs.
+ * Domain detectors stay outside organism; this only wires need→capability after detection.
+ */
+export function incidentNeedMappings(
+  incidentTypes: string[],
+  requiredCapabilities: string[],
+  opts?: { urgency?: number; confidence?: number }
+): SignalNeedMapping[] {
+  return incidentTypes.map((type) => ({
+    signalType: `incident.${type}`,
+    need: `investigate-${type}`,
+    requiredCapabilities: [...requiredCapabilities],
+    urgency: opts?.urgency ?? 0.85,
+    confidence: opts?.confidence ?? 0.9,
+  }));
+}
+
+export type OutcomeVerdictLike =
+  | 'successful'
+  | 'partially_successful'
+  | 'neutral'
+  | 'unsuccessful'
+  | string;
+
+/** Map an outer outcome evaluation into AgentOutcomeReport for utility/reputation. */
+export function toAgentOutcomeReport(input: {
+  verdict: OutcomeVerdictLike;
+  confidence?: number;
+  cost?: number;
+  summary?: string;
+  missionMetricUpdates?: Record<string, number>;
+}): AgentOutcomeReport {
+  const valueGenerated =
+    input.verdict === 'successful'
+      ? 1
+      : input.verdict === 'partially_successful'
+        ? 0.5
+        : input.verdict === 'neutral'
+          ? 0.2
+          : 0;
+
+  return {
+    result: input.summary ?? String(input.verdict),
+    metrics: {
+      valueGenerated,
+      confidence: input.confidence ?? 0.8,
+      cost: input.cost,
+      riskPenalty: input.verdict === 'unsuccessful' ? 0.5 : 0,
+    },
+    missionMetricUpdates: input.missionMetricUpdates,
+    evidence: input.summary ? [input.summary] : undefined,
+  };
+}

package/src/core/capability-registry.ts

@@ -0,0 +1,72 @@
+import type { RuntimeAgentRecord } from '../types/organism.types';
+
+/**
+ * Runtime capability graph for need detection and routing.
+ */
+export class CapabilityRegistry {
+  private byCapability = new Map<string, Set<string>>();
+  private agentCaps = new Map<string, Set<string>>();
+
+  register(agentId: string, capabilities: string[]): void {
+    this.unregister(agentId);
+    const set = new Set(capabilities.map((c) => c.toLowerCase()));
+    this.agentCaps.set(agentId, set);
+    for (const cap of set) {
+      let agents = this.byCapability.get(cap);
+      if (!agents) {
+        agents = new Set();
+        this.byCapability.set(cap, agents);
+      }
+      agents.add(agentId);
+    }
+  }
+
+  unregister(agentId: string): void {
+    const existing = this.agentCaps.get(agentId);
+    if (!existing) return;
+    for (const cap of existing) {
+      this.byCapability.get(cap)?.delete(agentId);
+    }
+    this.agentCaps.delete(agentId);
+  }
+
+  find(capability: string): string[] {
+    return Array.from(this.byCapability.get(capability.toLowerCase()) ?? []);
+  }
+
+  findGap(required: string[], liveAgents: RuntimeAgentRecord[]): string[] {
+    const live = new Set(
+      liveAgents
+        .filter((a) => a.status === 'active' || a.status === 'idle')
+        .flatMap((a) => a.capabilities.map((c) => c.toLowerCase()))
+    );
+    return required.filter((c) => !live.has(c.toLowerCase()));
+  }
+
+  findCapableAgents(required: string[], liveAgents: RuntimeAgentRecord[]): RuntimeAgentRecord[] {
+    const needed = required.map((c) => c.toLowerCase());
+    return liveAgents.filter((a) => {
+      if (a.status !== 'active' && a.status !== 'idle') return false;
+      const caps = new Set(a.capabilities.map((c) => c.toLowerCase()));
+      return needed.every((n) => caps.has(n));
+    });
+  }
+
+  findPartialAgents(required: string[], liveAgents: RuntimeAgentRecord[]): RuntimeAgentRecord[] {
+    const needed = required.map((c) => c.toLowerCase());
+    return liveAgents.filter((a) => {
+      if (a.status !== 'active' && a.status !== 'idle') return false;
+      const caps = new Set(a.capabilities.map((c) => c.toLowerCase()));
+      const hits = needed.filter((n) => caps.has(n)).length;
+      return hits > 0 && hits < needed.length;
+    });
+  }
+
+  snapshot(): Record<string, string[]> {
+    const out: Record<string, string[]> = {};
+    for (const [cap, agents] of this.byCapability) {
+      out[cap] = Array.from(agents);
+    }
+    return out;
+  }
+}

package/src/core/clock.ts

@@ -0,0 +1,58 @@
+/**
+ * Parse duration strings like "5s", "1m", "10m", "30d" into milliseconds.
+ */
+export function parseDurationMs(input: string | number | undefined, fallback: number): number {
+  if (input == null) return fallback;
+  if (typeof input === 'number') return input;
+  const m = String(input)
+    .trim()
+    .match(/^(\d+(?:\.\d+)?)(ms|s|m|h|d)?$/i);
+  if (!m) return fallback;
+  const n = Number(m[1]);
+  const unit = (m[2] ?? 'ms').toLowerCase();
+  switch (unit) {
+    case 'ms':
+      return n;
+    case 's':
+      return n * 1000;
+    case 'm':
+      return n * 60_000;
+    case 'h':
+      return n * 3_600_000;
+    case 'd':
+      return n * 86_400_000;
+    default:
+      return fallback;
+  }
+}
+
+/**
+ * Simulation / test clock. Real mode uses Date; accelerated advances manually.
+ */
+export class OrganismClock {
+  private accelerated = false;
+  private current = Date.now();
+
+  useReal(): void {
+    this.accelerated = false;
+  }
+
+  useAccelerated(start = Date.now()): void {
+    this.accelerated = true;
+    this.current = start;
+  }
+
+  now(): Date {
+    return new Date(this.accelerated ? this.current : Date.now());
+  }
+
+  advance(ms: number): void {
+    if (this.accelerated) {
+      this.current += ms;
+    }
+  }
+
+  get isAccelerated(): boolean {
+    return this.accelerated;
+  }
+}

package/src/core/mission.ts

@@ -0,0 +1,83 @@
+import type { MissionDefinition, MissionMetric, MissionProgress } from '../types/organism.types';
+
+export function createMissionProgress(mission: MissionDefinition): MissionProgress {
+  const metrics: Record<string, number> = {};
+  const criteriaMet: Record<string, boolean> = {};
+  for (const c of mission.successCriteria ?? []) {
+    metrics[c.name] = 0;
+    criteriaMet[c.name] = false;
+  }
+  return {
+    missionId: mission.id,
+    objective: mission.objective,
+    metrics,
+    criteriaMet,
+    completed: false,
+    updatedAt: new Date(),
+  };
+}
+
+export function applyMissionMetricUpdates(
+  progress: MissionProgress,
+  mission: MissionDefinition,
+  updates: Record<string, number>
+): MissionProgress {
+  const metrics = { ...progress.metrics, ...updates };
+  const criteriaMet: Record<string, boolean> = {};
+  let allMet = true;
+  const criteria = mission.successCriteria ?? [];
+
+  if (criteria.length === 0) {
+    return {
+      ...progress,
+      metrics,
+      criteriaMet,
+      completed: false,
+      updatedAt: new Date(),
+    };
+  }
+
+  for (const criterion of criteria) {
+    const value = metrics[criterion.name] ?? 0;
+    const met = evaluateCriterion(criterion, value);
+    criteriaMet[criterion.name] = met;
+    if (criterion.operator !== 'maximize' && criterion.operator !== 'minimize' && !met) {
+      allMet = false;
+    }
+  }
+
+  // maximize/minimize never block completion alone; only target operators do
+  const targetCriteria = criteria.filter(
+    (c) => c.operator !== 'maximize' && c.operator !== 'minimize'
+  );
+  const completed = targetCriteria.length > 0 && targetCriteria.every((c) => criteriaMet[c.name]);
+
+  return {
+    ...progress,
+    metrics,
+    criteriaMet,
+    completed: completed && allMet,
+    updatedAt: new Date(),
+  };
+}
+
+function evaluateCriterion(criterion: MissionMetric, value: number): boolean {
+  const target = criterion.target;
+  switch (criterion.operator) {
+    case 'gt':
+      return target != null && value > target;
+    case 'gte':
+      return target != null && value >= target;
+    case 'lt':
+      return target != null && value < target;
+    case 'lte':
+      return target != null && value <= target;
+    case 'eq':
+      return target != null && value === target;
+    case 'maximize':
+    case 'minimize':
+      return true;
+    default:
+      return false;
+  }
+}