helix-sdk

Client SDK for the Helix Evolution Protocol — connect any agent to Helix for experience reporting and Genome bootstrapping.

Installation

npm install helix-sdk

Quick Start

const { HelixClient } = require('helix-sdk');

const client = new HelixClient({
  baseUrl: 'https://helix-protocol-633071805876.us-central1.run.app',
  token: process.env.HELIX_TOKEN,
});

// Now you can use the client methods

Methods

reportExperience(report)

Reports an experience (e.g., a completed task, a user interaction) to the Helix server to influence future genome generation.

• Signature: reportExperience(report: object): Promise<object>
• Example:

  await client.reportExperience({
    trigger: 'user_feedback',
    outcome: 'positive',
    details: { rating: 5, comment: 'Great job!' },
  });

syncCapabilities(sinceTimestamp)

Fetches the latest capabilities (the "genome") from the Helix server. You can provide an optional timestamp to only receive capabilities updated since that time.

• Signature: syncCapabilities(sinceTimestamp?: number): Promise<object>
• Example:

  const lastSync = Date.now() - (60 * 60 * 1000); // 1 hour ago
  const updates = await client.syncCapabilities(lastSync);
  console.log('Updated capabilities:', updates);

registerWebhook(url)

Registers a webhook to receive real-time updates and commands from the Helix server.

• Signature: registerWebhook(url: string): Promise<object>
• Example:

  await client.registerWebhook('https://my-agent.ngrok.io/helix-updates');

Publishing

This package is published to npm via a GitHub Actions workflow. When you push a tag matching sdk-v* (e.g., sdk-v0.1.0), the workflow automatically builds and publishes the package.

Before your first publish, add an NPM_TOKEN secret to the GitHub repo settings:

1. Generate an npm access token at npmjs.com → Access Tokens
2. Go to GitHub repo → Settings → Secrets and variables → Actions
3. Create a new repository secret named NPM_TOKEN with your token value

Without this secret, the sdk-v* tag workflow will fail on the publish step.

Authentication

The SDK requires a HELIX_TOKEN to authenticate with the Helix server. You can pass it directly to the constructor or set it as an environment variable.

// Direct
const client = new HelixClient({
  baseUrl: '...',
  token: 'your-secret-token',
});

// Environment variable (recommended)
const client = new HelixClient({
  baseUrl: '...',
  token: process.env.HELIX_TOKEN,
});