@easynet-run/node 0.36.9 → 0.39.29

package/README.md

@@ -33,9 +33,34 @@ The SDK ships a native Dendrite bridge binary (loaded via `koffi`) that provides
 npm install @easynet-run/node
 ```
 
+## Platform / Native Bundle Notes
+
+- The published npm artifact currently comes from the Linux x86_64 SDK pack, so the embedded native file is host-matched to that pack.
+- If you need other native targets (iOS/Android/macOS/Linux arm64/Windows), use the target SDK pack from GitHub Releases:
+  - `sdk-packs-<target>.tar.gz`
+  - extract the `node/` directory and install the `*.tgz` artifact from that directory.
+- For local source development:
+  - `SDK_VERSION=<version>` (optional; resolver checks this and then fallback `0.1.0` in the same root)
+  - `EASYNET_DENDRITE_BRIDGE_LIB` can force an explicit native path.
+  - `EASYNET_DENDRITE_BRIDGE_HOME=<pack-root>` can be set to a shared extracted SDK pack path that contains `native/`.
+  - set `EASYNET_DENDRITE_BRIDGE_SOURCE=local` if you want preset/CLI helpers to auto-probe local source-tree bridge artifacts.
+  - `EASYNET_DENDRITE_BRIDGE_PLATFORM=ios|android|linux|windows|macos` if host/build target mismatch (for example macOS host + iOS pack).
+- For macOS-hosted iOS dev workflows, prefer a pack-native `.a` and explicit `EASYNET_DENDRITE_BRIDGE_LIB` path binding.
+
+Target examples:
+
+- macOS arm64: `sdk-packs-aarch64-apple-darwin.tar.gz`
+- macOS x86_64: `sdk-packs-x86_64-apple-darwin.tar.gz`
+- iOS arm64 simulator/device: `sdk-packs-aarch64-apple-ios.tar.gz`
+- iOS x86_64 simulator: `sdk-packs-x86_64-apple-ios.tar.gz`
+- Android arm64: `sdk-packs-aarch64-linux-android.tar.gz`
+- Linux arm64: `sdk-packs-aarch64-unknown-linux-gnu.tar.gz`
+- Linux x86_64: `sdk-packs-x86_64-unknown-linux-gnu.tar.gz`
+- Windows x64: `sdk-packs-x86_64-pc-windows-msvc.tar.gz`
+
 ## Development
 
-Runtime `.js` files and package-facing `.d.ts` files under `src/` are generated from the TypeScript sources with `tsc`.
+Runtime `.js` files and package-facing `.d.ts` files under `src/` are generated locally from the TypeScript sources with `tsc`, but they are intentionally gitignored and must not be committed.
 Edit `src/**/*.ts`, then run:
 
 ```bash
@@ -43,7 +68,7 @@ npm run build
 npm run generated:check
 ```
 
-Do not hand-edit generated `src/**/*.js` or `src/**/*.d.ts` files.
+`npm pack` and git-based installs run `prepare`/`prepack`, so published tarballs still include the generated runtime files.
 
 ## Quick Start
 
@@ -106,7 +131,7 @@ No public IP required — the local runtime connects outbound to the Hub and rec
 
 Full lifecycle management — not just invocation:
 
-- `createAbility()` / `exportAbility()` — define and register abilities with schemas
+- `buildAbilityDescriptor()` / `exportAbility()` — define and register abilities with schemas
 - `deployToNode()` — install + activate on target nodes
 - `listAbilities()` / `invokeAbility()` / `uninstallAbility()`
 - `discoverNodes()` / `executeCommand()` / `disconnectDevice()` / `drainDevice()`
@@ -131,6 +156,7 @@ First-class voice call lifecycle and transport negotiation (19+ FFI bindings):
 
 - `startServer()` spawns a local Axon runtime and joins the Hub — all traffic is outbound.
 - Federated node discovery and cross-network invocation dispatch.
+- Preset status: the dedicated federation preset helper is currently Python-only; Node exposes federation through runtime bootstrap and transport-facing APIs.
 
 ### Remote Control & Orchestration
 

package/native/dendrite-bridge-manifest.json

@@ -1,11 +1,11 @@
 {
-  "dendrite_bridge_version": "0.36.9",
+  "dendrite_bridge_version": "0.39.29",
   "target": "x86_64-unknown-linux-gnu",
   "os": "linux",
   "arch": "x86_64",
   "library": {
     "path": "native/libaxon_dendrite_bridge.so",
-    "sha256": "e802bd6d15684b1b3f4c7fd2fc7159b591aaa93c58de78c369cac5d0315f7688"
+    "sha256": "65e28058d2937cc457b28eb52e86c8f0ad376ce00c0e524cd49eac3372fb8ddf"
   },
   "header": {
     "path": "native/include/axon_dendrite_bridge.h",
@@ -35,5 +35,5 @@
     "axon_dendrite_protocol_coverage_json",
     "axon_dendrite_string_free"
   ],
-  "generated_at_utc": "2026-03-27T17:24:23Z"
+  "generated_at_utc": "2026-03-30T16:23:47Z"
 }

package/native/dendrite-bridge.json

@@ -1,6 +1,6 @@
 {
   "language": "node",
-  "dendrite_bridge_version": "0.36.9",
+  "dendrite_bridge_version": "0.39.29",
   "target": "x86_64-unknown-linux-gnu",
   "dendrite_manifest_path": "native/dendrite-bridge-manifest.json",
   "dendrite_library_path": "native/libaxon_dendrite_bridge.so",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@easynet-run/node",
-  "version": "0.36.9",
+  "version": "0.39.29",
   "description": "EasyNet Axon Node.js SDK (sidecar-first with Dendrite bridge payload).",
   "license": "Apache-2.0",
   "homepage": "https://easynet.run",
@@ -15,14 +15,16 @@
   },
   "type": "module",
   "scripts": {
-    "build": "tsc -p tsconfig.json",
+    "build": "node ./scripts/clean-generated.mjs && tsc -p tsconfig.json",
     "check": "tsc -p tsconfig.json --noEmit",
     "types:check": "tsc -p tsconfig.types.json --noEmit",
     "types:build": "tsc -p tsconfig.types.json",
     "types:verify": "npm run types:build && node ./scripts/verify-dist-types.mjs",
     "generated:check": "npm run build && node ./scripts/verify-generated.mjs",
     "types": "npm run check && npm run types:verify",
-    "verify": "npm run types && npm run generated:check"
+    "verify": "npm run types && npm run generated:check",
+    "prepare": "npm run build",
+    "prepack": "npm run build"
   },
   "main": "src/index.js",
   "types": "src/index.d.ts",

package/runtime/runtime-bridge-manifest.json

@@ -1,11 +1,11 @@
 {
-  "runtime_version": "0.36.9",
+  "runtime_version": "0.39.29",
   "target": "x86_64-unknown-linux-gnu",
   "os": "linux",
   "arch": "x86_64",
   "artifact": {
-    "path": "runtime/easynet-runtime-rs-0.36.9-x86_64-unknown-linux-gnu.tar.gz",
-    "sha256": "6d4c56411bae31ed11ec94face402c170d7a44d7f0686bac601440d25a9e98b2",
+    "path": "runtime/easynet-runtime-rs-0.39.29-x86_64-unknown-linux-gnu.tar.gz",
+    "sha256": "6234d8b5fa7d71e918c3648e8b627b93d767271f6486a003ffe836fb5ea3bfd1",
     "binary_name": "axon-runtime"
   },
   "language_bridge_descriptors": [
@@ -16,5 +16,5 @@
     "java/runtime-bridge.json",
     "swift/runtime-bridge.json"
   ],
-  "generated_at_utc": "2026-03-27T17:24:23Z"
+  "generated_at_utc": "2026-03-30T16:23:47Z"
 }

package/runtime/runtime-bridge.json

@@ -1,9 +1,9 @@
 {
   "language": "node",
-  "runtime_version": "0.36.9",
+  "runtime_version": "0.39.29",
   "target": "x86_64-unknown-linux-gnu",
-  "runtime_artifact_path": "runtime/easynet-runtime-rs-0.36.9-x86_64-unknown-linux-gnu.tar.gz",
+  "runtime_artifact_path": "runtime/easynet-runtime-rs-0.39.29-x86_64-unknown-linux-gnu.tar.gz",
   "binary_relative_path": "axon-runtime",
-  "recommended_extract": "tar -xzf runtime/easynet-runtime-rs-0.36.9-x86_64-unknown-linux-gnu.tar.gz -C <runtime_dir>",
+  "recommended_extract": "tar -xzf runtime/easynet-runtime-rs-0.39.29-x86_64-unknown-linux-gnu.tar.gz -C <runtime_dir>",
   "recommended_launch": "AXON_ENFORCE_MTLS=false <runtime_dir>/axon-runtime"
 }

package/src/ability_lifecycle.d.ts

@@ -11,6 +11,11 @@ export interface AbilityDescriptor {
     version: string;
     tags: string[];
     resourceUri: string;
+    instructions: string;
+    inputExamples: unknown[];
+    prerequisites: string[];
+    contextBindings: Record<string, string>;
+    category: string;
 }
 export type AbilityTarget = "claude" | "codex" | "openclaw" | "agent_skills";
 export interface AbilityExportResult {
@@ -72,7 +77,7 @@ export declare function startServer(endpoint?: string, options?: {
     /** Pre-shared join token used for outbound federation authentication. */
     hubJoinToken?: string;
 }): Promise<ServerHandle>;
-export declare function createAbility(opts: {
+export declare function buildAbilityDescriptor(opts: {
     name: string;
     description: string;
     commandTemplate: string;
@@ -81,6 +86,11 @@ export declare function createAbility(opts: {
     version?: string;
     tags?: string[];
     resourceUri?: string;
+    instructions?: string;
+    inputExamples?: unknown[];
+    prerequisites?: string[];
+    contextBindings?: Record<string, string>;
+    category?: string;
 }): AbilityDescriptor;
 export declare function toToolSpec(descriptor: AbilityDescriptor): ToolSpec;
 export declare function exportAbility(descriptor: AbilityDescriptor, target?: AbilityTarget, axonEndpoint?: string): AbilityExportResult;

package/src/ability_lifecycle.js

@@ -2,7 +2,22 @@
 // =========================
 //
 // File: sdk/node/src/ability_lifecycle.ts
-// Description: Ability lifecycle API: create, deploy, invoke, and export as Agent Skills.
+// Description: Node SDK ability lifecycle API for descriptor creation, deployment, invocation, and skill export workflows.
+//
+// Protocol Responsibility:
+// - Defines typed ability descriptors, export targets, and deployment helpers exposed to SDK users.
+// - Keeps cross-language ability naming, resource-uri, and tool-spec semantics aligned.
+//
+// Implementation Approach:
+// - Separates pure descriptor/export helpers from bridge-backed deployment and invocation flows.
+// - Uses explicit validation and stable defaults so generated ability artifacts stay deterministic.
+//
+// Usage Contract:
+// - Callers must provide valid command templates, schema objects, and runtime context for deployment helpers.
+// - Returned descriptors and exported skill artifacts should be treated as stable SDK-level contracts.
+//
+// Architectural Position:
+// - High-level SDK facade above preset/orchestrator layers and below application examples.
 //
 // Author: Silan.Hu
 // Email: silan.hu@u.nus.edu
@@ -14,7 +29,7 @@ import { existsSync, mkdirSync, openSync } from "node:fs";
 import { hostname as localHostname } from "node:os";
 import { join, dirname } from "node:path";
 import { env } from "node:process";
-import { buildPythonSubprocessTemplate } from "./presets/remote_control/descriptor.js";
+import { buildDescriptor as buildRemotePackageDescriptor, buildPythonSubprocessTemplate, serializeDescriptor as serializeRemotePackageDescriptor, } from "./presets/remote_control/descriptor.js";
 import { AxonConfigError, AxonBridgeError, AxonInvocationError, AxonPartialSuccessError } from "./errors.js";
 import { DEFAULT_SIGNATURE } from "./presets/remote_control/config.js";
 import { beginPhase, buildDeployTrace } from "./receipt.js";
@@ -39,7 +54,10 @@ function normalizeAbilityName(raw) {
         .replace(/[^a-z0-9_\-]/g, "-")
         .replace(/-{2,}/g, "-")
         .replace(/^-+|-+$/g, "");
-    return result || "ability";
+    if (!result) {
+        throw new AxonConfigError(`identifier contains no valid characters: ${JSON.stringify(raw)}`);
+    }
+    return result;
 }
 function firstNonEmpty(...values) {
     for (const value of values) {
@@ -215,9 +233,9 @@ export async function startServer(endpoint, options = {}) {
     };
 }
 // ---------------------------------------------------------------------------
-// create
+// build
 // ---------------------------------------------------------------------------
-export function createAbility(opts) {
+export function buildAbilityDescriptor(opts) {
     if (!opts.name?.trim())
         throw new AxonConfigError("ability name cannot be empty");
     if (!opts.commandTemplate?.trim())
@@ -233,6 +251,11 @@ export function createAbility(opts) {
         version: opts.version ?? "1.0.0",
         tags: opts.tags ?? [],
         resourceUri: opts.resourceUri ?? `easynet:///r/org/${token}`,
+        instructions: opts.instructions ?? "",
+        inputExamples: opts.inputExamples ?? [],
+        prerequisites: opts.prerequisites ?? [],
+        contextBindings: opts.contextBindings ?? {},
+        category: opts.category ?? "",
     };
 }
 // ---------------------------------------------------------------------------
@@ -278,7 +301,7 @@ export function exportAbility(descriptor, target = "agent_skills", axonEndpoint)
 export async function deployToNode(bridge, tenant, nodeId, descriptor, signature) {
     const token = descriptor.toolName;
     const abilityId = token;
-    const pkg = buildDeployPackage({
+    const deployArgs = {
         ability_name: descriptor.name,
         tool_name: token,
         description: descriptor.description,
@@ -286,8 +309,20 @@ export async function deployToNode(bridge, tenant, nodeId, descriptor, signature
         version: descriptor.version,
         input_schema: descriptor.inputSchema,
         output_schema: descriptor.outputSchema,
-        tags: descriptor.tags.length > 0 ? descriptor.tags : undefined,
-    }, signature);
+    };
+    if (descriptor.tags.length > 0)
+        deployArgs.tags = descriptor.tags;
+    if (descriptor.instructions)
+        deployArgs.instructions = descriptor.instructions;
+    if (descriptor.inputExamples.length > 0)
+        deployArgs.input_examples = descriptor.inputExamples;
+    if (descriptor.prerequisites.length > 0)
+        deployArgs.prerequisites = descriptor.prerequisites;
+    if (Object.keys(descriptor.contextBindings).length > 0)
+        deployArgs.context_bindings = descriptor.contextBindings;
+    if (descriptor.category)
+        deployArgs.category = descriptor.category;
+    const pkg = buildDeployPackage(deployArgs, signature);
     const builder = beginPhase("deploy", tenant, nodeId, abilityId);
     try {
         const result = await bridge.deployAbilityPackage(tenant, nodeId, pkg);
@@ -380,14 +415,17 @@ export async function forgetAll(bridge, tenant, nodeId, confirm = false, options
     // without performing any uninstalls.
     if (dryRun) {
         const wouldRemove = [];
+        const wouldFail = [];
         for (const tool of tools) {
             const installId = String(tool.install_id ?? "");
-            const toolName = String(tool.tool_name ?? "");
-            if (!installId)
+            const toolName = String(tool.tool_name ?? "unknown");
+            if (!installId) {
+                wouldFail.push({ tool_name: toolName, error: "missing install_id" });
                 continue;
+            }
             wouldRemove.push(toolName);
         }
-        return { removed: wouldRemove, removed_count: wouldRemove.length, failed: [], failed_count: 0 };
+        return { removed: wouldRemove, removed_count: wouldRemove.length, failed: wouldFail, failed_count: wouldFail.length };
     }
     const removed = [];
     const failed = [];
@@ -434,19 +472,10 @@ export async function listRemoteTools(bridge, tenant, namePattern = "", nodeId =
 // buildDeployPackage
 // ---------------------------------------------------------------------------
 export function buildDeployPackage(args, signature) {
-    const abilityName = String(args.ability_name ?? "");
-    const toolName = String(args.tool_name ?? abilityName);
-    return {
-        ability_name: abilityName,
-        tool_name: toolName,
-        description: args.description ?? "",
-        command_template: args.command_template ?? "",
-        input_schema: args.input_schema ?? { type: "object", properties: {} },
-        output_schema: args.output_schema ?? { type: "object", properties: {} },
-        version: args.version ?? "1.0.0",
-        tags: args.tags ?? [],
-        signature_base64: signature,
-    };
+    return serializeRemotePackageDescriptor(buildRemotePackageDescriptor({
+        ...args,
+        signature_base64: args.signature_base64 ?? signature,
+    }, signature));
 }
 // ---------------------------------------------------------------------------
 // deployPackage
@@ -457,12 +486,21 @@ export async function deployPackage(bridge, tenant, nodeId, packageDescriptor) {
 // ---------------------------------------------------------------------------
 // Internal generators
 // ---------------------------------------------------------------------------
+const SHELL_UNSAFE_RE = /[`$\\"'\n\r;|&<>(){}!#\x00-\x1f]/;
+function sanitizeShellValue(value, label) {
+    if (SHELL_UNSAFE_RE.test(value)) {
+        throw new AxonConfigError(`${label} contains disallowed shell characters: ${value}`);
+    }
+    return value;
+}
 function generateInvokeScript(resourceUri, endpoint) {
+    const safeEP = sanitizeShellValue(endpoint, "endpoint");
+    const safeURI = sanitizeShellValue(resourceUri, "resource_uri");
     return `#!/usr/bin/env bash
 set -euo pipefail
-AXON_ENDPOINT="\${AXON_ENDPOINT:-${endpoint}}"
+AXON_ENDPOINT="\${AXON_ENDPOINT:-${safeEP}}"
 TENANT="\${AXON_TENANT:-default}"
-RESOURCE_URI="${resourceUri}"
+RESOURCE_URI="${safeURI}"
 ARGS="\${1:-{}}"
 curl -sS -X POST "\${AXON_ENDPOINT}/v1/invoke" \\
   -H "Content-Type: application/json" \\
@@ -498,6 +536,20 @@ function generateAbilityMd(descriptor, target, token) {
     lines.push("");
     lines.push(descriptor.description);
     lines.push("");
+    // Agent extension: instructions
+    if (descriptor.instructions) {
+        lines.push(descriptor.instructions);
+        lines.push("");
+    }
+    // Agent extension: prerequisites
+    if (descriptor.prerequisites.length > 0) {
+        lines.push("## Prerequisites");
+        lines.push("");
+        for (const p of descriptor.prerequisites) {
+            lines.push(`- ${p}`);
+        }
+        lines.push("");
+    }
     lines.push("## Parameters");
     lines.push("");
     lines.push("| Name | Type | Required | Description |");
@@ -510,6 +562,31 @@ function generateAbilityMd(descriptor, target, token) {
         const isRequired = required.includes(name) ? "Yes" : "No";
         lines.push(`| ${name} | ${propType} | ${isRequired} | ${propDesc} |`);
     }
+    // Agent extension: examples
+    if (descriptor.inputExamples.length > 0) {
+        lines.push("");
+        lines.push("## Examples");
+        lines.push("");
+        for (let i = 0; i < descriptor.inputExamples.length; i++) {
+            lines.push(`**Example ${i + 1}:**`);
+            lines.push("");
+            lines.push("```json");
+            lines.push(JSON.stringify(descriptor.inputExamples[i]));
+            lines.push("```");
+            lines.push("");
+        }
+    }
+    // Agent extension: context bindings
+    if (Object.keys(descriptor.contextBindings).length > 0) {
+        lines.push("## Context Bindings");
+        lines.push("");
+        lines.push("| Key | Value |");
+        lines.push("|-----|-------|");
+        for (const [k, v] of Object.entries(descriptor.contextBindings)) {
+            lines.push(`| \`${k}\` | ${v} |`);
+        }
+        lines.push("");
+    }
     lines.push("");
     lines.push("## Invoke");
     lines.push("");
@@ -526,6 +603,9 @@ function generateAbilityMd(descriptor, target, token) {
     lines.push("");
     lines.push(`- **URI**: \`${descriptor.resourceUri}\``);
     lines.push(`- **Version**: ${descriptor.version}`);
+    if (descriptor.category) {
+        lines.push(`- **Category**: ${descriptor.category}`);
+    }
     lines.push("");
     return lines.join("\n");
 }

package/src/dendrite_bridge/bridge.d.ts

@@ -23,6 +23,7 @@ export declare class DendriteBridge {
     listNodes(tenantId: string, options?: DendriteListNodesOptions): Record<string, unknown>[];
     registerNode(tenantId: string, nodeId: string, options?: DendriteRegisterNodeOptions): Record<string, unknown>;
     deregisterNode(tenantId: string, nodeId: string, reason?: string): Record<string, unknown>;
+    drainNode(tenantId: string, nodeId: string, reason?: string): Record<string, unknown>;
     heartbeat(tenantId: string, nodeId: string): Record<string, unknown>;
     publishCapability(tenantId: string, packageId: string, capabilityName: string, options: DendritePublishCapabilityOptions): Record<string, unknown>;
     installCapability(tenantId: string, nodeId: string, packageId: string, options: DendriteInstallCapabilityOptions): Record<string, unknown>;

package/src/dendrite_bridge/bridge.js

@@ -2,23 +2,22 @@
 // =========================
 //
 // File: sdk/node/src/dendrite_bridge/bridge.ts
-// Description: DendriteBridge class implementation; provides the high-level API surface for interacting with the native dendrite bridge over FFI/JSON.
+// Description: Node DendriteBridge implementation that exposes typed protocol methods over the native Axon bridge.
 //
 // Protocol Responsibility:
-// - Implements the DendriteBridge class with all RPC, capability, voice, and transport methods.
-// - Preserves stable request/response semantics and error mapping.
+// - Implements the high-level DendriteBridge API for Node callers across RPC, capability, interop, and voice surfaces.
+// - Preserves JSON request and error semantics expected by the Node SDK public API.
 //
 // Implementation Approach:
-// - Delegates FFI calls to the ffi submodule.
-// - Delegates validation/payload building to capability_request helpers.
+// - Delegates native symbol loading to the FFI layer while keeping method-level payload shaping near the class boundary.
+// - Uses typed options and explicit method families so transport intent remains readable at call sites.
 //
 // Usage Contract:
-// - Callers construct a DendriteBridge with endpoint options and invoke methods for each protocol surface.
-// - Errors are surfaced as DendriteError instances.
+// - Construct bridge instances with valid endpoint or library configuration before invoking protocol methods.
+// - Callers should prefer this layer over direct FFI usage unless they are extending native bindings.
 //
 // Architectural Position:
-// - Part of the Node SDK dendrite_bridge submodule layer.
-// - Should not embed FFI loading or type declarations outside this class's responsibility.
+// - Node SDK bridge facade above FFI bindings and below application or preset code.
 //
 // Author: Silan.Hu
 // Email: silan.hu@u.nus.edu
@@ -202,6 +201,19 @@ export class DendriteBridge {
         });
         return callJson(this.lib.axon_dendrite_deregister_node_json, this.handle, req);
     }
+    drainNode(tenantId, nodeId, reason = "") {
+        if (this.handle <= 0n)
+            throw new DendriteError("dendrite bridge already closed");
+        if (!this.lib.axon_dendrite_drain_node_json) {
+            throw new DendriteError("dendrite bridge symbol not available: axon_dendrite_drain_node_json");
+        }
+        const req = JSON.stringify({
+            tenant_id: tenantId,
+            node_id: nodeId,
+            reason,
+        });
+        return callJson(this.lib.axon_dendrite_drain_node_json, this.handle, req);
+    }
     heartbeat(tenantId, nodeId) {
         if (this.handle <= 0n)
             throw new DendriteError("dendrite bridge already closed");

package/src/dendrite_bridge/ffi.d.ts

@@ -21,6 +21,7 @@ export type DendriteBridgeLib = {
     axon_dendrite_list_nodes_json: DendriteJsonFn<[bigint, string]>;
     axon_dendrite_register_node_json: DendriteJsonFn<[bigint, string]>;
     axon_dendrite_deregister_node_json?: DendriteJsonFn<[bigint, string]>;
+    axon_dendrite_drain_node_json?: DendriteJsonFn<[bigint, string]>;
     axon_dendrite_heartbeat_json: DendriteJsonFn<[bigint, string]>;
     axon_dendrite_publish_capability_json: DendriteJsonFn<[bigint, string]>;
     axon_dendrite_install_capability_json: DendriteJsonFn<[bigint, string]>;