What is this?

This is the Node.js surface for Axon, a protocol-level control plane that treats agent capabilities as first-class network objects. Every ability you expose carries its own schema, trust posture, scheduling contract, and tenant isolation rules — enforced atomically at invocation time.

Axon collapses tenant isolation, rate limiting, policy evaluation, node selection, concurrency admission, and circuit breaking into a single atomic decision against the same state snapshot. No race window between policy check and routing.

The SDK ships a native Dendrite bridge binary (loaded via koffi) that provides protocol-complete Axon gRPC calls without gRPC codegen in JavaScript.

Install

npm install @easynet-run/node

Development

Runtime .js files and package-facing .d.ts files under src/ are generated from the TypeScript sources with tsc. Edit src/**/*.ts, then run:

npm run build
npm run generated:check

Do not hand-edit generated src/**/*.js or src/**/*.d.ts files.

Quick Start

Expose an ability

import { ability, serve } from "@easynet-run/node";

ability("easynet:///r/org/reg/agent.quote-bot/abilities/order.quote@1?tenant_id=tenant-test")
  .handle(async ({ sku, qty = 1 }) => ({ sku, price: 19.9 * qty }))
  .expose();

await serve("agent.quote-bot");

Invoke an ability

import { client } from "@easynet-run/node";

const res = await client()
  .tenant("tenant-test")
  .ability("easynet:///r/org/reg/agent.quote-bot/abilities/order.quote@1?tenant_id=tenant-test")
  .call({ sku: "A1", qty: 2 });

call() returns business payload (result_json). Use callAny() or callRaw() for stream/media-oriented non-object payloads.

Bootstrap a local runtime behind NAT

import { startServer } from "@easynet-run/node";

const srv = await startServer(undefined, {
  hub: "axon://hub.easynet.run:50084",
  hubTenant: "tenant-test",
  hubLabel: "alice-macbook",
});

No public IP required — the local runtime connects outbound to the Hub and receives federated invocations over that channel.

Sub-exports

| Path | Purpose | |---|---| | @easynet-run/node/presets/remote-control | Remote device orchestration presets | | @easynet-run/node/mcp | MCP stdio server and tool provider | | @easynet-run/node/tool-adapter | Ability → LLM tool schema conversion |

Capabilities

Core Protocol

• Fluent builders — .tenant() → .principal() → .ability() → .call() are immutable and chainable.
• Native Dendrite bridge — DendriteBridge loads the platform C ABI via koffi; all Axon gRPC shapes (unary, server-stream, client-stream, bidi-stream) available without gRPC codegen.
• Subject binding — .principal(...) scopes invocation to a subject identity with automatic URI visibility mapping.

Ability Lifecycle

Full lifecycle management — not just invocation:

• createAbility() / exportAbility() — define and register abilities with schemas
• deployToNode() — install + activate on target nodes
• listAbilities() / invokeAbility() / uninstallAbility()
• discoverNodes() / executeCommand() / disconnectDevice() / drainDevice()
• buildDeployPackage() / deployPackage() — packaging and deployment workflows

MCP & A2A Protocols

• MCP server — StdioMcpServer hosts JSON-RPC 2.0 tool endpoints over stdio.
• MCP operations — deploy, list, call, and update MCP tools on remote nodes.
• A2A agent protocol — inter-agent discovery and task dispatch.
• Tool adapter — AbilityToolAdapter converts abilities to OpenAI/Anthropic/generic tool definitions; supports local handler registration with zero network overhead.

Voice & Media Signaling

First-class voice call lifecycle and transport negotiation (19+ FFI bindings):

• Call management: create, join, leave, end, watch events, report metrics
• Transport sessions: create, set description, add ICE candidates, refresh lease
• Media path updates and codec negotiation

Federation

• startServer() spawns a local Axon runtime and joins the Hub — all traffic is outbound.
• Federated node discovery and cross-network invocation dispatch.

Remote Control & Orchestration

• Subprocess template building, descriptor parsing, orchestrator factory.
• Ability dispatch workflows with bundle reading and media persistence.
• Deploy trace lifecycle tracking (Phase → PhaseReceipt).

License

Apache-2.0 — see LICENSE.

Author

Silan Hu · [email protected]