Documentation

Get started with Helix

Wrap any async function. PCEC handles classification, repair, and learning. The Repair Graph remembers — every fix makes the next one faster.

Install

bash
$ npm install @helix-agent/core

Also available: pip install helix-agent-sdk (Python), Docker image at adrianhihi/helix-server.

Quickstart

30 seconds. One line. Zero config.

TypeScriptagent.ts
import { wrap } from '@helix-agent/core'
 
// Wrap any async function — RPC calls, API requests, anything.
const safeCall = wrap(myFunction, { mode: 'auto' })
 
// On failure: PCEC classifies -> Repair Graph lookup -> applies fix -> retries.
// On success after repair: pattern is committed back to the Repair Graph.
const result = await safeCall(args)

wrap() returns an identical function signature. TypeScript types are preserved. Your tests don’t change. Your calling code doesn’t change.

Configuration

Optional. wrap() works without any config — but here’s the full surface:

JSONhelix.config.json
{
"projectName": "my-agent",
"mode": "auto", // "auto" | "gated"
"maxRetries": 3,
"timeoutMs": 30000,
"telemetry": true, // submit repair patterns to managed Repair Graph
"repairGraphPath": "./helix-graph.db",
"adapter": "evm" // "evm" | "solana" | "x402" | "http"
}

mode: ‘auto’ applies repairs above q-value threshold automatically. Use ‘gated’ to require human approval for low-confidence repairs.

telemetry: false disables cross-tenant Repair Graph submission. Self-hosted runs locally with full isolation.

wrap() — zero config

The fastest integration. Wrap any async function — the call site is unchanged.

TypeScript
import { wrap } from '@helix-agent/core'
 
const safeCall = wrap(myFunction, { mode: 'auto' })
 
const result = await safeCall(args)
// Identical signature, identical return type. Your tests don't change.

createEngine() — manual control

Use this when you want to inspect repair results before retrying, or pass rich context to PCEC.

TypeScript
import { createEngine } from '@helix-agent/core'
 
const { engine, repairGraph } = createEngine({
projectName: 'payments-agent',
repairGraphPath: './repair-graph.db',
})
 
try {
await sendPayment(invoice)
} catch (error) {
const result = await engine.repair(error, {
agentId: 'payments-agent',
context: { /* whatever your repair logic needs */ },
})
 
if (result.success) {
console.log('Repaired via ' + result.winner.strategy + ' in ' + result.totalMs + 'ms')
await sendPayment(invoice)
} else {
notifyOperator(result.failure)
}
}
 
// Inspect engine stats
const stats = engine.getStats()
// { repairs: 47, savedRevenue: 12500, immuneHits: 31, patternCount: 12 }

PCEC primitives — full control

Each PCEC step exported individually for maximum flexibility. Build custom repair pipelines or audit trails.

TypeScript
import { perceive, construct, evaluate, commit } from '@helix-agent/core'
import { RepairGraph } from '@helix-agent/core'
 
const graph = new RepairGraph('./repair-graph.db')
 
// P — Perceive: classify the failure
const failure = perceive(error, context)
// { code: 'rate-limited-429', category: 'rpc', severity: 0.6, ... }
 
// Check Repair Graph (immunity)
const known = graph.lookup(failure.code, failure.category)
if (known) {
// Skip C+E, apply known fix
}
 
// C — Construct: generate repair candidates
const candidates = construct(failure, graph)
 
// E — Evaluate: score and rank
const ranked = evaluate(candidates, failure)
 
// C — Commit: execute the winner
const result = await commit(ranked[0], failure, context)
 
if (result.success) {
graph.store({
failureCode: failure.code,
category: failure.category,
strategy: ranked[0].strategy,
q: 0.7,
})
}

Repair Graph API

Query, inspect, and store repair patterns directly. SQLite-backed by default; bring your own storage adapter for production.

TypeScript
import { RepairGraph } from '@helix-agent/core'
 
const graph = new RepairGraph('./repair-graph.db')
 
// Query
graph.lookup('rate-limited-429', 'rpc') // -> RepairPattern | null
graph.list() // -> RepairPattern[]
graph.immuneCount() // -> number of patterns
graph.getSuccessRate('rate-limited-429', 'endpoint_fallback') // -> 0.94
 
// Store
graph.store({
failureCode: 'rate-limited-429',
category: 'rpc',
strategy: 'endpoint_fallback',
params: { fallback: 'secondary-rpc' },
q: 0.7,
})
 
graph.close()

TypeScript types

All public types exported from @helix-agent/core.

TypeScript
// What wrap() returns
type WrappedFunction<T> = (...args: Parameters<T>) => ReturnType<T>
 
// What engine.repair() returns
interface RepairResult {
success: boolean
failure: FailureClassification
candidates: RepairCandidate[]
winner: RepairCandidate | null
pattern: RepairPattern | null
immune: boolean // true = Repair Graph hit, instant fix
totalMs: number
}
 
interface FailureClassification {
code: string // 'rate-limited-429' | 'nonce-conflict' | ...
category: string // 'rpc' | 'auth' | 'gas' | ...
severity: number // 0–1
details: string
timestamp: number
}
 
interface RepairCandidate {
id: string
strategy: string
description: string
score: number // 0–100
q: number // from Repair Graph history
}
 
interface RepairPattern {
failureCode: string
category: string
strategy: string
params: Record<string, unknown>
q: number // Bayesian confidence, 0–1
usedBy: number // how many agents have applied this
}

Adapters

EVM

bash
$ npm install @helix-agent/adapter-evm

Supports Base, Ethereum, Arbitrum, Optimism. Auto-handles nonce conflicts, gas estimation failures, RPC rate limits, revert classification.

Solana

bash
$ npm install @helix-agent/adapter-solana

RPC failover, Jupiter aggregator routing on swap failures, blockhash refresh on transaction expiry.

x402

bash
$ npm install @helix-agent/adapter-x402

Coinbase Agent Payments (x402) integration. Handles payment-insufficient, session expiry, currency mismatch.

CLI

Helix ships a helix CLI for local development, telemetry inspection, and Repair Graph management.

CommandDescription
npx helix initInteractive setup wizard, generates helix.config.json
npx helix statusLive PCEC event stream (colored P→C→E→C)
npx helix dashStart local dashboard server on :7842
npx helix graph listList all local Repair Patterns
npx helix graph syncSync local graph with managed Repair Graph

Full API reference and source code on GitHub.

View on GitHub →Back to home