@helix-agent/core

Self-healing infrastructure for AI agent payments.

Every payment failure only needs to be solved once. wrap() makes any async function self-healing.

Install

# One-line install
curl -sSL https://helix-cnj.pages.dev/install.sh | bash

# Or npm
npm install @helix-agent/core

# Python
pip install helix-agent-sdk

# Docker
docker run -d -p 7842:7842 adrianhihi/helix-server

Quick Start

import { wrap } from '@helix-agent/core';

const safePay = wrap(myPaymentFunction, { mode: 'auto' });
const result = await safePay({ to: '0x...', amount: 100 });
// If it fails → Helix diagnoses → repairs → retries → you get the result

That's it. One line. Your agent now self-heals.

How It Works

Error → PERCEIVE → CONSTRUCT → EVALUATE → COMMIT → VERIFY → GENE MAP
                                                              ↓
Next time: Error → Gene Map hit → IMMUNE ⚡ (<1ms)

When your function throws, Helix:

1. Perceives — classifies the error (nonce? balance? rate limit?)
2. Constructs — generates repair candidates from all platform adapters
3. Evaluates — scores by cost, speed, and historical success (Q-value)
4. Commits — executes the winning strategy
5. Verifies — confirms the fix actually worked
6. Stores Gene — next time → instant IMMUNE fix

Three Layers of Intelligence

LLM is optional. Works without it. Enable with:

export ANTHROPIC_API_KEY=sk-ant-...

When LLM classifies an unknown error, the result is cached in Gene Map. Next time → IMMUNE, no LLM, $0.

Three Safety Modes

wrap(fn, { mode: 'observe' })  // Diagnose only. Zero risk. Default.
wrap(fn, { mode: 'auto' })     // Retry + param fix. No fund movement.
wrap(fn, { mode: 'full' })     // All repairs including chain writes.

Platform Coverage

31+ scenarios. 26 strategies. 4 platforms. 442+ tests. Schema v8.

Python SDK

Coinbase AgentKit, LangChain, CrewAI are Python. We have a native SDK:

# Option A: Docker (no Node.js needed)
docker run -d -p 7842:7842 adrianhihi/helix-server
pip install helix-agent-sdk

# Option B: Node.js
npx helix serve --port 7842
pip install helix-agent-sdk

from helix_agent import HelixClient, helix_wrap, helix_guard

# Method 1: Explicit client
client = HelixClient(platform="coinbase")
result = client.repair("AA25 invalid account nonce")

# Method 2: Decorator (auto-retry on failure)
@helix_wrap(platform="coinbase", max_retries=3)
def send_payment(to, amount):
    return agent.transfer(to, amount)

# Method 3: Context manager
with helix_guard("tempo") as guard:
    repair = guard.repair("nonce too low")

PyPI: https://pypi.org/project/helix-agent-sdk/

Docker

docker run -d -p 7842:7842 adrianhihi/helix-server

Or with docker-compose:

docker-compose up -d

REST API

npx helix serve --port 7842 --mode observe

curl -X POST http://localhost:7842/repair \
  -H 'Content-Type: application/json' \
  -d '{"error":"AA25 invalid account nonce","platform":"coinbase"}'

Gene Telemetry

Every LLM discovery is optionally reported (anonymized) to improve seed genes for all users:

wrap(fn, {
  mode: 'auto',
  llm: { provider: 'anthropic', enabled: true },
  telemetry: { enabled: true },
});

Opt-in only. No addresses, keys, or amounts sent. Default: disabled.

Gene Dream

Background memory consolidation — inspired by human REM sleep and Claude Code's Auto Dream.

When your agent is idle, Gene Dream automatically:

1. Clusters similar genes by error similarity
2. Prunes failed strategies (Q < 0.15, 3+ consecutive failures)
3. Consolidates duplicate genes into stronger meta-genes
4. Enriches context (cross-platform coverage)
5. Reindexes for faster lookups

npx helix dream                                    # Manual trigger
curl -X POST http://localhost:7842/dream -d '{"force":true}'  # Via API

Idle Scheduler: auto-triggers after 5min inactivity (light) or 30min (full dream).

Data Versioning

Gene Map schema evolves across versions. Helix auto-migrates on startup:

v1 → Base schema (genes table + Q-value RL)
v2 → Gene Dream (gene_meta table + dream state)
v3 → Gene Telemetry (gene_discoveries table)

curl http://localhost:7842/schema     # Check migration status
npx helix migrate                    # Manual migrate

On major version jumps, old Q-values decay by 10% — strategies that worked on v1 may not be optimal on v3.

Key Features

• Gene Map — SQLite database of proven repairs. Bayesian Q ± σ scoring. Seed genes for day-1 immunity
• Cross-Platform Immunity — Fix learned on Tempo auto-heals same error on Coinbase
• Adaptive Learning Rate — New genes learn fast, old genes stay stable
• Strategy Chains — Multi-step repairs [refresh_nonce → speed_up_transaction]
• Predictive Failure Graph — Predicts next error, preloads Gene into cache
• Context-Aware Lookup — Q-value adjusted by gas price, time, chain ID
• Error Embedding — 28 known signatures, fuzzy matching when exact match fails
• A/B Testing — Controlled strategy experiments, 90/10 traffic split
• Gene Registry — Push/pull shared knowledge across instances
• OpenTelemetry — Optional tracing spans + metrics
• Audit Log — Every repair recorded, exportable for compliance
• Business Verify — Custom verification callbacks
• Failure Learning — Auto-distills defensive genes after repeated failures
• Multi-Dimensional Scoring — 6-dimension Q-value (accuracy, cost, latency, safety, transferability, reliability)
• Gene Dream — Background memory consolidation (cluster, prune, consolidate, enrich, reindex)
• Data Versioning — Schema migrations with Q-value decay on major upgrades
• Causal Repair Graph — predicts next errors before they happen
• Negative Knowledge — remembers why repairs failed, avoids repeating mistakes
• Meta-Learning — 3 similar repairs → learns pattern → 4th variant instant
• Conditional Genes — context-aware strategy selection (gas, platform, time)
• Adversarial Robustness — 4-layer defense against Gene poisoning
• Formal Safety Verification — 7 pre-execution safety constraints
• Self-Play Evolution — autonomous challenger/repair/verifier loop
• Federated Gene Learning — privacy-preserving distributed RL with differential privacy

API

import { wrap, createEngine, simulate } from '@helix-agent/core';

// wrap() — main API
const safeFn = wrap(fn, {
  mode: 'auto',
  agentId: 'my-agent',
  maxRepairCostUsd: 1.00,
  verify: (result, args) => result.amount === args[0].amount,
  otel: { tracer, meter },
  onRepair: (result) => console.log(result.winner?.strategy),
});

// createEngine() — advanced
const engine = createEngine({ mode: 'observe' });
const result = await engine.repair(new Error('nonce mismatch'));

// simulate() — CI testing
const diagnosis = simulate({ error: 'AA25 invalid account nonce' });

CLI

npx helix serve --port 7842 --mode observe  # REST API server
npx helix status                             # Gene Map health
npx helix simulate "AA25 invalid nonce"      # Dry-run diagnosis
npx helix audit                              # Repair audit log
npx helix gc                                 # Garbage collection
npx helix stats my-agent                     # Agent attribution
npx helix dream                              # Gene Dream consolidation
npx helix migrate                            # Schema migration check
npx helix scan ./src                         # Scan for payment patterns
npx helix self-play 10                       # Run 10 self-play rounds
npx helix federated                          # Federated learning round

Scan Your Codebase

# Find payment error patterns in your code
npx helix scan ./src

# JSON output
npx helix scan ./src --json

# GitHub Actions annotation format
npx helix scan ./src --format github

CI/CD Integration

# .github/workflows/helix-scan.yml
name: Helix Payment Safety
on: [pull_request]
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npm install -g @helix-agent/core
      - run: npx helix scan ./ --format github
        continue-on-error: true

Documentation

• GitHub — Source, examples, dashboard
• User Runbook — Install to production
• Benchmark — 90.3% recovery rate
• CONTRIBUTING — How to contribute

License

MIT