@easynet-run/node 0.27.14 → 0.39.29

package/README.md

@@ -33,6 +33,43 @@ 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 locally from the TypeScript sources with `tsc`, but they are intentionally gitignored and must not be committed.
+Edit `src/**/*.ts`, then run:
+
+```bash
+npm run build
+npm run generated:check
+```
+
+`npm pack` and git-based installs run `prepare`/`prepack`, so published tarballs still include the generated runtime files.
+
 ## Quick Start
 
 ### Expose an ability
@@ -94,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()`
@@ -119,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,15 +1,15 @@
 {
-  "dendrite_bridge_version": "0.27.14",
+  "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": "48d24b376d4c233a4d836f01ad6ede4dd38677a63fd6b687eeabc6a387ee910b"
+    "sha256": "65e28058d2937cc457b28eb52e86c8f0ad376ce00c0e524cd49eac3372fb8ddf"
   },
   "header": {
     "path": "native/include/axon_dendrite_bridge.h",
-    "sha256": "b54e9ce0898c95276e5a2f5752cf7c09255ab04d0ff6c50b1da86f194faf6b75"
+    "sha256": "bb6fdce765a6b1c2fb91a1cee037d00f7ec4297c9a1fd03b39fb829edf2d0fc4"
   },
   "protocol_coverage": {
     "rpc_shapes": ["unary", "server_stream", "client_stream", "bidi_stream"],
@@ -29,10 +29,11 @@
     "axon_dendrite_deploy_mcp_list_dir_json",
     "axon_dendrite_list_mcp_tools_json",
     "axon_dendrite_call_mcp_tool_json",
+    "axon_dendrite_call_mcp_tool_stream_open_json",
     "axon_dendrite_uninstall_capability_json",
     "axon_dendrite_update_mcp_list_dir_json",
     "axon_dendrite_protocol_coverage_json",
     "axon_dendrite_string_free"
   ],
-  "generated_at_utc": "2026-03-19T17:45:33Z"
+  "generated_at_utc": "2026-03-30T16:23:47Z"
 }

package/native/dendrite-bridge.json

@@ -1,6 +1,6 @@
 {
   "language": "node",
-  "dendrite_bridge_version": "0.27.14",
+  "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/native/include/axon_dendrite_bridge.h

@@ -251,6 +251,20 @@ char *axon_dendrite_list_mcp_tools_json(uint64_t handle,
 char *axon_dendrite_call_mcp_tool_json(uint64_t handle,
                                        const char *request_json);
 
+// Control helper: open streaming MCP tool call. Returns {"stream_handle": <u64>}.
+// Chunks are read via axon_dendrite_stream_next_json.
+// IMPORTANT: Caller MUST call axon_dendrite_stream_close_json on the returned
+// stream_handle to release the background task and channel. Failure to close
+// will leak resources until the session itself is closed.
+// timeout_ms is split as follows:
+//   - setup: min(timeout_ms, 30000) — capped at 30s for stream open
+//   - per-chunk: timeout_ms — each stream_next call waits up to this value
+// Per-session limit: max 16 concurrent MCP tool streams.
+// input JSON:
+// {"tenant_id":"...","tool_name":"...","target_node_id":"...","arguments_json":{},"timeout_ms":60000}
+char *axon_dendrite_call_mcp_tool_stream_open_json(uint64_t handle,
+                                                    const char *request_json);
+
 // Control helper: deactivate (optional) and uninstall installed capability.
 // input JSON:
 // {
@@ -392,8 +406,8 @@ char *axon_dendrite_voice_watch_transport_events_json(uint64_t handle,
 //   "path":"/axon.v1.Invocation/WatchInvocation",
 //   "request_base64":"...",
 //   "metadata":{"x-foo":"bar"},
-//   "timeout_ms":10000,
-//   "chunk_timeout_ms":30000,
+//   "timeout_ms":10000,        // setup/open timeout
+//   "chunk_timeout_ms":30000,  // per-chunk wait timeout
 //   "chunk_buffer_size":64
 // }
 // output JSON:
@@ -426,8 +440,8 @@ char *axon_dendrite_stream_close_json(uint64_t stream_handle);
 //   "request_base64":"...",
 //   "request_chunks_base64":["..."],
 //   "metadata":{"x-foo":"bar"},
-//   "timeout_ms":10000,
-//   "chunk_timeout_ms":30000,
+//   "timeout_ms":10000,        // setup/open timeout
+//   "chunk_timeout_ms":30000,  // per-chunk wait timeout
 //   "chunk_buffer_size":64,
 //   "request_buffer_size":64
 // }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@easynet-run/node",
-  "version": "0.27.14",
+  "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,12 +15,16 @@
   },
   "type": "module",
   "scripts": {
-    "build": "tsc",
-    "check": "tsc --noEmit",
+    "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 && test -f dist/types/index.d.ts && test -f dist/types/dendrite_bridge.d.ts",
-    "types": "npm run types:check && npm run types:verify"
+    "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",
+    "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.27.14",
+  "runtime_version": "0.39.29",
   "target": "x86_64-unknown-linux-gnu",
   "os": "linux",
   "arch": "x86_64",
   "artifact": {
-    "path": "runtime/easynet-runtime-rs-0.27.14-x86_64-unknown-linux-gnu.tar.gz",
-    "sha256": "382b54020ba9caa97e175fdec8e99a45f52209e40d36214f33efc741482e2072",
+    "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-19T17:45:33Z"
+  "generated_at_utc": "2026-03-30T16:23:47Z"
 }

package/runtime/runtime-bridge.json

@@ -1,9 +1,9 @@
 {
   "language": "node",
-  "runtime_version": "0.27.14",
+  "runtime_version": "0.39.29",
   "target": "x86_64-unknown-linux-gnu",
-  "runtime_artifact_path": "runtime/easynet-runtime-rs-0.27.14-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.27.14-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

@@ -3,6 +3,7 @@ import { type DeployTrace } from "./receipt.js";
 import type { ToolSpec } from "./tool_adapter.js";
 export interface AbilityDescriptor {
     name: string;
+    toolName: string;
     description: string;
     commandTemplate: string;
     inputSchema: Record<string, unknown>;
@@ -10,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 {
@@ -71,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;
@@ -80,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

@@ -1,5 +1,26 @@
-// sdk/node/src/ability_lifecycle.ts — Ability lifecycle API: create, deploy, and export as Agent Skills.
+// EasyNet Axon for AgentNet
+// =========================
 //
+// File: sdk/node/src/ability_lifecycle.ts
+// 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
 // Copyright (c) 2026-2027 easynet. All rights reserved.
 import { spawn } from "node:child_process";
 import { webcrypto } from "node:crypto";
@@ -8,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";
@@ -33,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) {
@@ -209,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())
@@ -219,6 +243,7 @@ export function createAbility(opts) {
     const token = normalizeAbilityName(opts.name);
     return {
         name: opts.name,
+        toolName: token,
         description: opts.description,
         commandTemplate: opts.commandTemplate,
         inputSchema: opts.inputSchema ?? { type: "object", properties: {} },
@@ -226,15 +251,19 @@ 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 ?? "",
     };
 }
 // ---------------------------------------------------------------------------
 // toToolSpec
 // ---------------------------------------------------------------------------
 export function toToolSpec(descriptor) {
-    const token = normalizeAbilityName(descriptor.name);
     return {
-        name: token,
+        name: descriptor.toolName,
         description: descriptor.description,
         resourceUri: descriptor.resourceUri,
         parameters: descriptor.inputSchema,
@@ -244,7 +273,7 @@ export function toToolSpec(descriptor) {
 // exportAbility
 // ---------------------------------------------------------------------------
 export function exportAbility(descriptor, target = "agent_skills", axonEndpoint) {
-    const token = normalizeAbilityName(descriptor.name);
+    const token = descriptor.toolName;
     const endpoint = axonEndpoint ?? `http://127.0.0.1:${DEFAULT_AXON_PORT}`;
     const invokeScript = generateInvokeScript(descriptor.resourceUri, endpoint);
     const abilityMd = generateAbilityMd(descriptor, target, token);
@@ -270,9 +299,9 @@ export function exportAbility(descriptor, target = "agent_skills", axonEndpoint)
  * ```
  */
 export async function deployToNode(bridge, tenant, nodeId, descriptor, signature) {
-    const token = normalizeAbilityName(descriptor.name);
+    const token = descriptor.toolName;
     const abilityId = token;
-    const pkg = buildDeployPackage({
+    const deployArgs = {
         ability_name: descriptor.name,
         tool_name: token,
         description: descriptor.description,
@@ -280,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);
@@ -308,7 +349,7 @@ export async function listAbilities(bridge, tenant, nodeId) {
 // invokeAbility
 // ---------------------------------------------------------------------------
 export async function invokeAbility(bridge, tenant, nodeId, toolName, args = {}) {
-    return await bridge.callMcpToolWithArgs(tenant, toolName, nodeId, args);
+    return await bridge.callMcpToolWithArgs(tenant, normalizeAbilityName(toolName), nodeId, args);
 }
 // ---------------------------------------------------------------------------
 // uninstallAbility
@@ -374,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 = [];
@@ -428,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
@@ -451,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" \\
@@ -492,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 |");
@@ -504,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("");
@@ -520,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/capability_request.js

@@ -23,8 +23,10 @@
 // Author: Silan.Hu
 // Email: silan.hu@u.nus.edu
 // Copyright (c) 2026-2027 easynet. All rights reserved.
+// DendriteError re-exported from errors.ts to break the circular dependency:
+// dendrite_bridge imports validate/build helpers from this module, so we
+// cannot import from dendrite_bridge here. errors.ts has no such dependency.
 import { AxonConfigError } from "./errors.js";
-// DendriteError kept for backward compatibility; validation now uses AxonConfigError.
 export class DendriteError extends Error {
     constructor(message) {
         super(message);

package/src/dendrite_bridge/bridge.d.ts

@@ -1,4 +1,4 @@
-import type { DendriteBridgeOptions, DendriteUnaryCallOptions, DendriteAbilityCallOptions, DendriteStreamCallOptions, DendriteClientStreamCallOptions, DendriteBidiStreamCallOptions, DendriteListNodesOptions, DendriteRegisterNodeOptions, DendritePublishCapabilityOptions, DendriteInstallCapabilityOptions, DendriteListA2aAgentsOptions, DendriteSendA2aTaskOptions, DendriteDeployMcpListDirOptions, DendriteListMcpToolsOptions, DendriteCallMcpToolOptions, DendriteUninstallCapabilityOptions, DendriteUpdateMcpListDirOptions, DendriteVoiceCreateCallOptions, DendriteVoiceJoinCallOptions, DendriteVoiceUpdateMediaPathOptions, DendriteVoiceMetricsOptions, DendriteVoiceEndCallOptions, DendriteVoiceWatchOptions, DendriteVoiceCreateTransportSessionOptions, DendriteVoiceDescriptionOptions, DendriteVoiceCandidateOptions, DendriteVoiceEndTransportSessionOptions, DendriteProtocolInvokeOptions } from "./types.js";
+import type { DendriteBridgeOptions, DendriteUnaryCallOptions, DendriteAbilityCallOptions, DendriteStreamCallOptions, DendriteClientStreamCallOptions, DendriteBidiStreamCallOptions, DendriteListNodesOptions, DendriteRegisterNodeOptions, DendritePublishCapabilityOptions, DendriteInstallCapabilityOptions, DendriteListA2aAgentsOptions, DendriteSendA2aTaskOptions, DendriteDeployMcpListDirOptions, DendriteListMcpToolsOptions, DendriteCallMcpToolOptions, DendriteCallMcpToolStreamOptions, DendriteUninstallCapabilityOptions, DendriteUpdateMcpListDirOptions, DendriteVoiceCreateCallOptions, DendriteVoiceJoinCallOptions, DendriteVoiceUpdateMediaPathOptions, DendriteVoiceMetricsOptions, DendriteVoiceEndCallOptions, DendriteVoiceWatchOptions, DendriteVoiceCreateTransportSessionOptions, DendriteVoiceDescriptionOptions, DendriteVoiceCandidateOptions, DendriteVoiceEndTransportSessionOptions, DendriteProtocolInvokeOptions } from "./types.js";
 import type { DendriteBridgeLib } from "./ffi.js";
 export declare class DendriteBridge {
     private readonly lib;
@@ -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>;
@@ -33,6 +34,12 @@ export declare class DendriteBridge {
     deployMcpListDir(tenantId: string, nodeId: string, options?: DendriteDeployMcpListDirOptions): Record<string, unknown>;
     listMcpTools(tenantId: string, options?: DendriteListMcpToolsOptions): Record<string, unknown>[];
     callMcpTool(tenantId: string, toolName: string, options?: DendriteCallMcpToolOptions): Record<string, unknown>;
+    /**
+     * Open a streaming MCP tool call that returns incremental response chunks.
+     * Requires native library support for streaming symbols.
+     * Uses DEFAULT_MCP_TOOL_STREAM_TIMEOUT_MS (60s) per chunk if no timeout specified.
+     */
+    callMcpToolStream(tenantId: string, toolName: string, options?: DendriteCallMcpToolStreamOptions): DendriteServerStream;
     uninstallCapability(tenantId: string, nodeId: string, installId: string, options?: DendriteUninstallCapabilityOptions): Record<string, unknown>;
     updateMcpListDir(tenantId: string, nodeId: string, options?: DendriteUpdateMcpListDirOptions): Record<string, unknown>;
     createVoiceCall(tenantId: string, options?: DendriteVoiceCreateCallOptions): Record<string, unknown>;
@@ -69,9 +76,10 @@ export declare class DendriteBridge {
 export declare class DendriteServerStream implements AsyncIterable<Uint8Array> {
     private readonly lib;
     private readonly streamHandle;
+    private readonly defaultChunkTimeoutMs;
     private done;
     private nativeClosed;
-    constructor(lib: DendriteBridgeLib, streamHandle: bigint);
+    constructor(lib: DendriteBridgeLib, streamHandle: bigint, defaultChunkTimeoutMs?: number);
     next(timeoutMs?: number): {
         chunk: Uint8Array | null;
         done: boolean;