@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

npm install @helix-agent/core

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. 335 tests.

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"}'

Endpoints: POST /repair · GET /health · GET /genes · GET /status

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.

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)

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

Documentation

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

License

MIT