js-evolution-engine

OADA (Observe → Analyze → Decide → Act → Verify) autonomous evolution engine for AI agents. A pluggable, host-agnostic framework with a three-pipeline architecture: Issue-driven decisions, queue-based execution, and risk-aware verification.

What it is

js-evolution-engine orchestrates an autonomous self-evolution loop for AI-driven projects. It separates what to do (the intelligence pipeline) from how to do it (the execution pipeline) and whether the result is safe to keep (the verify pipeline). Each pipeline can be invoked independently from the CLI, run on a schedule, or composed programmatically.

┌──────────────────────┐    ┌──────────────────────┐    ┌──────────────────────┐
│  Intelligence        │    │  Execution           │    │  Verify              │
│  Observe → Analyze   │ →  │  Claim → Dispatch    │ →  │  Audit → Policy      │
│        → Decide      │    │       → Modify       │    │       → (Auto-)Merge │
│  Output: Issues +    │    │  Source: Queue or    │    │  Source: GitHub PRs  │
│         Queue        │    │           GitHub     │    │       or local       │
└──────────────────────┘    └──────────────────────┘    └──────────────────────┘
        ↑                            ↑                            ↑
        └────── HostContext ─────────┴────── AI Client ───────────┘
                  (logger, notifier, action handlers,
                   intelligence store, analytics, …)

5-minute quickstart

npm install js-evolution-engine

Create oada.config.mjs in your project root:

import { MockAIClient, ActionTypeRegistry, ActionTypeSpec } from 'js-evolution-engine';

const actionRegistry = new ActionTypeRegistry();
actionRegistry.register(new ActionTypeSpec({
  name: 'send_email',
  description: 'Send a notification email',
  promptHint: 'Send an email (params: to, subject, body)',
  defaultRisk: 'low',
}));

export default async function ({ cwd }) {
  return {
    aiClient: new MockAIClient({ /* or your own AI subclass */ }),
    actionRegistry,
    host: {
      basePath: cwd,
      appName: 'my-agent',
      logger: console,
      actionHandlers: {
        send_email: async (action, ctx) => {
          // your real send-email logic here
          ctx.logger?.info(`would email ${action.params?.to}`);
          return { success: true, message: 'sent' };
        },
      },
    },
  };
}

Then:

npx oada intel              # observe + analyze + decide → queue actions
npx oada exec  --limit 5    # consume the queue
npx oada decisions          # inspect queue state
npx oada verify --auto      # (github mode) audit PRs + auto-merge low-risk

See examples/minimal-demo (from a git checkout) or node_modules/js-evolution-engine/examples/minimal-demo after npm install — only source files are published; run the demo to create data/ locally.

For an example of injecting external markdown via agentContextDocs, see examples/cyber-taoist-demo in the repo (node_modules/js-evolution-engine/examples/cyber-taoist-demo/ after install — sources only), and Injecting Agent Context Documents in the host-adapter guide. On npmjs.com, use the repo copy: examples/cyber-taoist-demo tree and HOST_ADAPTER.md on GitHub.

Documentation

• Architecture — pipelines, dataflow, file layout (view on GitHub)
• Host adapter guide — the HostContext contract (view on GitHub)
• Migration from js-moltbook — switching from the embedded module (view on GitHub)
• Changelog (view on GitHub)

Public API

import {
  // Engine + pipelines
  EvolutionEngine, IntelligencePipeline, ExecutionPipeline, VerifyPipeline,
  // Host abstractions
  NULL_HOST, normalizeHost,
  // AI
  BaseAIClient, MockAIClient, AIError,
  PromptBuilder, promptBuilder,
  // Registries
  ACTION_REGISTRY, ActionTypeRegistry, ActionTypeSpec,
  OBSERVATION_REGISTRY, ObservationSourceRegistry, ObservationSourceSpec,
  // Queues
  DecisionQueue, FeatureRequestQueue,
  // Adapters
  HumanGuidanceReader, EvolutionLogger,
  // Helpers
  scanProjectStructure, QueryResolver, GoalProvider,
  // GitHub integration
  GitHubIssueManager, OADA_LABEL_DEFS,
  // Time helpers (vendored)
  isoBeijing, todayBeijing, nowBeijing, nowBeijingStr,
} from 'js-evolution-engine';

Status

v0.2.0 — adds agentContextDocs for host-injected authoritative markdown, optional ActionTypeSpec.layer, and ships docs/ + examples/ in the npm tarball. Core flows remain covered by unit tests; CLI and demos run end-to-end. Advanced features (e.g. detailed PR auto-merge policies, sub-agent dispatch via OpenClaw Gateway) are still simplified vs. the original; see CHANGELOG.md.

License

MIT — see LICENSE.