@easynet-run/node 0.27.14 → 0.39.29

package/src/dendrite_bridge/bridge.js

@@ -2,28 +2,27 @@
 // =========================
 //
 // 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
 // Copyright (c) 2026-2027 easynet. All rights reserved.
-import { callJson, loadDendriteLib, resolveLibraryPath, requireBridgeFn, DendriteError, DEFAULT_TIMEOUT_MS, DEFAULT_CONNECT_TIMEOUT_MS, } from "./ffi.js";
+import { callJson, loadDendriteLib, resolveLibraryPath, requireBridgeFn, DendriteError, DEFAULT_TIMEOUT_MS, DEFAULT_CONNECT_TIMEOUT_MS, DEFAULT_MCP_TOOL_STREAM_TIMEOUT_MS, } from "./ffi.js";
 const STREAMING_UNSUPPORTED = "incremental streaming not supported by loaded native library";
 import { validatePublishCapabilityRequest, buildPublishCapabilityPayload, validateInstallCapabilityRequest, buildInstallCapabilityPayload, validateDeployMcpListDirRequest, buildDeployMcpListDirPayload, validateUpdateMcpListDirRequest, buildUpdateMcpListDirPayload, buildUninstallCapabilityPayload, } from "../capability_request.js";
 export class DendriteBridge {
@@ -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");
@@ -304,6 +316,37 @@ export class DendriteBridge {
         });
         return callJson(this.lib.axon_dendrite_call_mcp_tool_json, this.handle, req);
     }
+    /**
+     * 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, toolName, options = {}) {
+        if (this.handle <= 0n)
+            throw new DendriteError("dendrite bridge already closed");
+        const streamOpen = requireBridgeFn(this.lib.axon_dendrite_call_mcp_tool_stream_open_json, STREAMING_UNSUPPORTED);
+        requireBridgeFn(this.lib.axon_dendrite_stream_next_json, STREAMING_UNSUPPORTED);
+        const timeoutMs = typeof options.timeoutMs === "number" && options.timeoutMs > 0
+            ? options.timeoutMs
+            : DEFAULT_MCP_TOOL_STREAM_TIMEOUT_MS;
+        const req = JSON.stringify({
+            tenant_id: tenantId,
+            tool_name: toolName,
+            target_node_id: options.targetNodeId ?? "",
+            arguments_json: options.argumentsJson ?? {},
+            arguments_base64: options.argumentsBase64,
+            timeout_ms: timeoutMs,
+        });
+        const resp = callJson(streamOpen, this.handle, req);
+        if (resp.stream_handle == null || resp.stream_handle === "") {
+            throw new DendriteError(`failed to open mcp tool stream: missing stream_handle in ${JSON.stringify(resp)}`);
+        }
+        const streamHandle = BigInt(resp.stream_handle);
+        if (streamHandle <= 0n) {
+            throw new DendriteError(`failed to open mcp tool stream: ${JSON.stringify(resp)}`);
+        }
+        return new DendriteServerStream(this.lib, streamHandle, timeoutMs);
+    }
     uninstallCapability(tenantId, nodeId, installId, options = {}) {
         if (this.handle <= 0n)
             throw new DendriteError("dendrite bridge already closed");
@@ -596,16 +639,20 @@ export class DendriteBridge {
         return new DendriteBidiStream(this.lib, streamHandle);
     }
 }
+/** Maximum consecutive timeout results before aborting iteration (matches Python/Go/Java/Swift). */
+const MAX_CONSECUTIVE_TIMEOUT_RETRIES = 3;
 export class DendriteServerStream {
     lib;
     streamHandle;
+    defaultChunkTimeoutMs;
     done = false;
     nativeClosed = false;
-    constructor(lib, streamHandle) {
+    constructor(lib, streamHandle, defaultChunkTimeoutMs = DEFAULT_TIMEOUT_MS) {
         this.lib = lib;
         this.streamHandle = streamHandle;
+        this.defaultChunkTimeoutMs = defaultChunkTimeoutMs > 0 ? defaultChunkTimeoutMs : DEFAULT_TIMEOUT_MS;
     }
-    next(timeoutMs = DEFAULT_TIMEOUT_MS) {
+    next(timeoutMs = this.defaultChunkTimeoutMs) {
         if (this.done)
             return { chunk: null, done: true };
         const streamNext = requireBridgeFn(this.lib.axon_dendrite_stream_next_json, STREAMING_UNSUPPORTED);
@@ -630,13 +677,20 @@ export class DendriteServerStream {
         }
     }
     async *[Symbol.asyncIterator]() {
+        let consecutiveTimeouts = 0;
         try {
             while (true) {
                 const { chunk, done, timeout } = this.next();
                 if (done)
                     break;
-                if (timeout)
+                if (timeout) {
+                    consecutiveTimeouts++;
+                    if (consecutiveTimeouts >= MAX_CONSECUTIVE_TIMEOUT_RETRIES) {
+                        throw new DendriteError(`stream timed out after ${consecutiveTimeouts} consecutive retries`);
+                    }
                     continue;
+                }
+                consecutiveTimeouts = 0;
                 if (chunk)
                     yield chunk;
             }
@@ -694,13 +748,20 @@ export class DendriteBidiStream {
         }
     }
     async *[Symbol.asyncIterator]() {
+        let consecutiveTimeouts = 0;
         try {
             while (true) {
                 const { chunk, done, timeout } = this.recv();
                 if (done)
                     break;
-                if (timeout)
+                if (timeout) {
+                    consecutiveTimeouts++;
+                    if (consecutiveTimeouts >= MAX_CONSECUTIVE_TIMEOUT_RETRIES) {
+                        throw new DendriteError(`stream timed out after ${consecutiveTimeouts} consecutive retries`);
+                    }
                     continue;
+                }
+                consecutiveTimeouts = 0;
                 if (chunk)
                     yield chunk;
             }

package/src/dendrite_bridge/ffi.d.ts

@@ -1,6 +1,7 @@
 import { DendriteError } from "../capability_request.js";
 export declare const DEFAULT_TIMEOUT_MS = 30000;
 export declare const DEFAULT_CONNECT_TIMEOUT_MS = 5000;
+export declare const DEFAULT_MCP_TOOL_STREAM_TIMEOUT_MS = 60000;
 interface DendriteBridgeJson {
     ok: boolean;
     [key: string]: unknown;
@@ -20,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]>;
@@ -30,6 +32,8 @@ export type DendriteBridgeLib = {
     axon_dendrite_deploy_mcp_list_dir_json: DendriteJsonFn<[bigint, string]>;
     axon_dendrite_list_mcp_tools_json: DendriteJsonFn<[bigint, string]>;
     axon_dendrite_call_mcp_tool_json: DendriteJsonFn<[bigint, string]>;
+    /** FFI binding to open a streaming MCP tool call. Returns a stream_handle. Optional — unavailable in older native libraries. */
+    axon_dendrite_call_mcp_tool_stream_open_json?: DendriteJsonFn<[bigint, string]>;
     axon_dendrite_uninstall_capability_json: DendriteJsonFn<[bigint, string]>;
     axon_dendrite_update_mcp_list_dir_json: DendriteJsonFn<[bigint, string]>;
     axon_dendrite_voice_create_call_json: DendriteJsonFn<[bigint, string]>;

package/src/dendrite_bridge/ffi.js

@@ -2,29 +2,28 @@
 // =========================
 //
 // File: sdk/node/src/dendrite_bridge/ffi.ts
-// Description: FFI loading and JSON calling layer for the Dendrite native bridge; resolves the shared library, binds koffi function pointers, and provides the callJson helper.
+// Description: Node FFI loader and raw JSON-call bindings for the native Axon dendrite bridge.
 //
 // Protocol Responsibility:
-// - Loads the native dendrite bridge shared library and exposes typed function bindings.
-// - Provides the low-level callJson helper that handles JSON serialization/error mapping.
+// - Loads the native dendrite shared library and exposes the raw JSON-call symbol set to Node code.
+// - Normalizes low-level FFI failures into stable Node-side error contracts.
 //
 // Implementation Approach:
-// - Uses koffi for native FFI binding.
-// - Keeps library resolution and error handling explicit.
+// - Keeps library path resolution, symbol binding, and JSON marshalling isolated from higher-level SDK classes.
+// - Defines timeout and transport constants close to the native boundary for consistent reuse.
 //
 // Usage Contract:
-// - Callers should use loadDendriteLib to obtain function bindings, then callJson to invoke them.
-// - Errors are surfaced as DendriteError instances.
+// - Treat this module as the lowest-level Node native binding layer and avoid embedding application logic here.
+// - Regenerate or update bindings here before adding new native bridge capabilities to higher layers.
 //
 // Architectural Position:
-// - Part of the Node SDK dendrite_bridge submodule layer.
-// - Should not embed class or interface logic outside FFI concerns.
+// - Native binding boundary underneath the Node SDK bridge facade.
 //
 // Author: Silan.Hu
 // Email: silan.hu@u.nus.edu
 // Copyright (c) 2026-2027 easynet. All rights reserved.
 import { createRequire } from "node:module";
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { DendriteError } from "../capability_request.js";
@@ -32,23 +31,198 @@ const require = createRequire(import.meta.url);
 const koffi = require("koffi");
 export const DEFAULT_TIMEOUT_MS = 30000;
 export const DEFAULT_CONNECT_TIMEOUT_MS = 5000;
+export const DEFAULT_MCP_TOOL_STREAM_TIMEOUT_MS = 60_000;
 export { DendriteError };
+function bridgeDebugLog(tried) {
+    if ((process.env.EASYNET_DENDRITE_BRIDGE_DEBUG || "").trim() === "1") {
+        process.stderr.write(`[dendrite-bridge] tried ${tried.length} candidate(s):\n`);
+        for (const p of tried) {
+            process.stderr.write(`  - ${p}\n`);
+        }
+    }
+}
 export function resolveLibraryPath(explicitPath) {
     if (explicitPath)
         return explicitPath;
     if (process.env.EASYNET_DENDRITE_BRIDGE_LIB)
         return process.env.EASYNET_DENDRITE_BRIDGE_LIB;
-    const here = dirname(fileURLToPath(import.meta.url));
-    const candidates = [
-        resolve(here, "../../native/libaxon_dendrite_bridge.dylib"),
-        resolve(here, "../../native/libaxon_dendrite_bridge.so"),
-        resolve(here, "../../native/axon_dendrite_bridge.dll"),
-    ];
-    for (const c of candidates) {
+    const names = libraryFileNames();
+    const versions = sdkVersionCandidates();
+    const tried = [];
+    for (const c of homeLibraryCandidates(names, versions)) {
+        tried.push(c);
+        if (existsSync(c))
+            return c;
+    }
+    if (useLocalSource()) {
+        for (const c of sourceLibraryCandidates(names, versions)) {
+            tried.push(c);
+            if (existsSync(c))
+                return c;
+        }
+    }
+    for (const c of packageLibraryCandidates(names, versions)) {
+        tried.push(c);
         if (existsSync(c))
             return c;
     }
-    throw new DendriteError("dendrite bridge library not found; set EASYNET_DENDRITE_BRIDGE_LIB or ensure package contains native/libaxon_dendrite_bridge.*");
+    bridgeDebugLog(tried);
+    throw new DendriteError("dendrite bridge library not found; set EASYNET_DENDRITE_BRIDGE_LIB or EASYNET_DENDRITE_BRIDGE_HOME — run with EASYNET_DENDRITE_BRIDGE_DEBUG=1 for candidate details");
+}
+function dedupeCandidates(values) {
+    const seen = new Set();
+    const out = [];
+    for (const value of values) {
+        if (seen.has(value)) {
+            continue;
+        }
+        seen.add(value);
+        out.push(value);
+    }
+    return out;
+}
+function libraryFileNames() {
+    const rawHint = (process.env.EASYNET_DENDRITE_BRIDGE_PLATFORM || "").trim().toLowerCase();
+    if (rawHint === "ios") {
+        return [
+            "libaxon_dendrite_bridge.dylib",
+            "libaxon_dendrite_bridge.so",
+            "axon_dendrite_bridge.dll",
+        ];
+    }
+    if (["android", "linux", "linux-gnu"].includes(rawHint)) {
+        return [
+            "libaxon_dendrite_bridge.so",
+            "libaxon_dendrite_bridge.dylib",
+            "axon_dendrite_bridge.dll",
+        ];
+    }
+    if (["macos", "darwin", "mac"].includes(rawHint)) {
+        return [
+            "libaxon_dendrite_bridge.dylib",
+            "libaxon_dendrite_bridge.so",
+            "axon_dendrite_bridge.dll",
+        ];
+    }
+    if (["windows", "win", "win32", "win64"].includes(rawHint)) {
+        return [
+            "axon_dendrite_bridge.dll",
+            "libaxon_dendrite_bridge.dylib",
+            "libaxon_dendrite_bridge.so",
+        ];
+    }
+    const primary = process.platform === "win32"
+        ? "axon_dendrite_bridge.dll"
+        : process.platform === "darwin"
+            ? "libaxon_dendrite_bridge.dylib"
+            : "libaxon_dendrite_bridge.so";
+    const all = [
+        "libaxon_dendrite_bridge.dylib",
+        "libaxon_dendrite_bridge.so",
+        "axon_dendrite_bridge.dll",
+    ];
+    return [primary, ...all.filter((n) => n !== primary)];
+}
+function projectRoot() {
+    let cursor = process.cwd();
+    for (let depth = 0; depth < 12; depth += 1) {
+        if (existsSync(resolve(cursor, "core/runtime-rs"))) {
+            return cursor;
+        }
+        const parent = dirname(cursor);
+        if (parent === cursor)
+            break;
+        cursor = parent;
+    }
+    return undefined;
+}
+function sdkVersionCandidates() {
+    const versions = [];
+    const envVersion = (process.env.SDK_VERSION || "").trim();
+    if (envVersion) {
+        versions.push(envVersion);
+    }
+    const root = projectRoot();
+    if (root) {
+        try {
+            const raw = readFileSync(resolve(root, "VERSION"), "utf8").trim();
+            if (raw) {
+                versions.push(raw.split("\n")[0].trim());
+            }
+        }
+        catch {
+            // no-op
+        }
+    }
+    if (versions.length === 0) {
+        if ((process.env.EASYNET_DENDRITE_BRIDGE_DEBUG || "").trim() === "1") {
+            console.error("warning: no SDK version detected, falling back to 0.1.0");
+        }
+    }
+    versions.push("0.1.0");
+    return dedupeCandidates(versions).filter(Boolean);
+}
+function addLibraryCandidates(targets, names, roots) {
+    for (const root of roots) {
+        for (const name of names) {
+            targets.push(resolve(root, name));
+        }
+    }
+}
+function homeLibraryCandidates(names, versions) {
+    const raw = (process.env.EASYNET_DENDRITE_BRIDGE_HOME || "").trim();
+    if (!raw)
+        return [];
+    const homeRoot = resolve(raw);
+    const candidateRoots = [
+        homeRoot,
+        resolve(homeRoot, "native"),
+        ...versions.map((version) => resolve(homeRoot, "dist", "sdk-packs", version, "native")),
+    ];
+    const candidates = [];
+    addLibraryCandidates(candidates, names, candidateRoots);
+    return dedupeCandidates(candidates);
+}
+function useLocalSource() {
+    const raw = (process.env.EASYNET_DENDRITE_BRIDGE_SOURCE || "").trim().toLowerCase();
+    return new Set(["1", "true", "yes", "on", "local", "source"]).has(raw);
+}
+function sourceLibraryCandidates(names, versions) {
+    const root = projectRoot();
+    if (!root)
+        return [];
+    const candidates = [];
+    // Versioned dist paths
+    for (const version of versions) {
+        addLibraryCandidates(candidates, names, [resolve(root, "dist", "sdk-packs", version, "native")]);
+    }
+    // Build artifacts
+    const bridgeTarget = resolve(root, "core/runtime-rs/dendrite-bridge/target");
+    const roots = [
+        resolve(bridgeTarget, "release"),
+        resolve(bridgeTarget, "debug"),
+    ];
+    const sdkTarget = (process.env.SDK_TARGET || "").trim();
+    if (sdkTarget) {
+        roots.push(resolve(bridgeTarget, sdkTarget, "release"));
+        roots.push(resolve(bridgeTarget, sdkTarget, "debug"));
+    }
+    addLibraryCandidates(candidates, names, roots);
+    return dedupeCandidates(candidates);
+}
+function packageLibraryCandidates(names, versions) {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const pkgBase = resolve(here, "../..");
+    const roots = [
+        pkgBase,
+        resolve(pkgBase, "native"),
+    ];
+    for (const version of versions) {
+        roots.push(resolve(pkgBase, "dist", "sdk-packs", version, "native"));
+    }
+    const candidates = [];
+    addLibraryCandidates(candidates, names, roots);
+    return dedupeCandidates(candidates);
 }
 export function loadDendriteLib(libraryPath) {
     const lib = koffi.load(libraryPath);
@@ -78,6 +252,7 @@ export function loadDendriteLib(libraryPath) {
         axon_dendrite_list_nodes_json: lib.func("axon_dendrite_list_nodes_json", bridgeString, ["uint64_t", "str"]),
         axon_dendrite_register_node_json: lib.func("axon_dendrite_register_node_json", bridgeString, ["uint64_t", "str"]),
         axon_dendrite_deregister_node_json: optionalJsonFn("axon_dendrite_deregister_node_json", ["uint64_t", "str"]),
+        axon_dendrite_drain_node_json: optionalJsonFn("axon_dendrite_drain_node_json", ["uint64_t", "str"]),
         axon_dendrite_heartbeat_json: lib.func("axon_dendrite_heartbeat_json", bridgeString, ["uint64_t", "str"]),
         axon_dendrite_publish_capability_json: lib.func("axon_dendrite_publish_capability_json", bridgeString, ["uint64_t", "str"]),
         axon_dendrite_install_capability_json: lib.func("axon_dendrite_install_capability_json", bridgeString, ["uint64_t", "str"]),
@@ -88,6 +263,7 @@ export function loadDendriteLib(libraryPath) {
         axon_dendrite_deploy_mcp_list_dir_json: lib.func("axon_dendrite_deploy_mcp_list_dir_json", bridgeString, ["uint64_t", "str"]),
         axon_dendrite_list_mcp_tools_json: lib.func("axon_dendrite_list_mcp_tools_json", bridgeString, ["uint64_t", "str"]),
         axon_dendrite_call_mcp_tool_json: lib.func("axon_dendrite_call_mcp_tool_json", bridgeString, ["uint64_t", "str"]),
+        axon_dendrite_call_mcp_tool_stream_open_json: optionalJsonFn("axon_dendrite_call_mcp_tool_stream_open_json", ["uint64_t", "str"]),
         axon_dendrite_uninstall_capability_json: lib.func("axon_dendrite_uninstall_capability_json", bridgeString, ["uint64_t", "str"]),
         axon_dendrite_update_mcp_list_dir_json: lib.func("axon_dendrite_update_mcp_list_dir_json", bridgeString, ["uint64_t", "str"]),
         axon_dendrite_voice_create_call_json: lib.func("axon_dendrite_voice_create_call_json", bridgeString, ["uint64_t", "str"]),

package/src/dendrite_bridge/types.d.ts

@@ -84,6 +84,10 @@ export interface DendriteCallMcpToolOptions {
     argumentsJson?: unknown;
     argumentsBase64?: string;
 }
+export interface DendriteCallMcpToolStreamOptions extends DendriteCallMcpToolOptions {
+    /** Per-chunk timeout in milliseconds for streaming reads. Default: 60,000 ms. */
+    timeoutMs?: number;
+}
 export interface DendriteUninstallCapabilityOptions {
     deactivateFirst?: boolean;
     deactivateReason?: string;

package/src/errors.js

@@ -1,4 +1,12 @@
-// sdk/node/src/errors.ts — Canonical error taxonomy for the Axon SDK.
+// EasyNet Axon for AgentNet
+// =========================
+//
+// File: sdk/node/src/errors.ts
+// Description: Canonical error taxonomy for the Axon SDK.
+//
+// Author: Silan.Hu
+// Email: silan.hu@u.nus.edu
+// Copyright (c) 2026-2027 easynet. All rights reserved.
 //
 // Terminology:
 //   Ability  — network-addressable governed execution contract
@@ -7,8 +15,6 @@
 //
 // Each error class exposes a `code` property for cross-SDK mapping.
 // See the Rust reference: sdk/rust/src/error.rs
-//
-// Copyright (c) 2026-2027 easynet. All rights reserved.
 /** Base error for all Axon SDK errors. */
 export class AxonError extends Error {
     /** Canonical error code for cross-SDK mapping. */

package/src/index.d.ts

@@ -1,5 +1,5 @@
 export { validateUninstallCapabilityRequest, buildUninstallCapabilityPayload, } from "./capability_request.js";
-export type { McpToolProvider, McpToolResult, } from "./mcp/server.js";
+export type { McpToolProvider, McpToolResult, McpToolStreamHandle, } from "./mcp/server.js";
 export { StdioMcpServer } from "./mcp/server.js";
 export type JsonValue = string | number | boolean | null | JsonValue[] | {
     [k: string]: JsonValue;
@@ -48,8 +48,8 @@ export declare class Client {
     callRaw(payload: JsonValue): Promise<Record<string, unknown>>;
 }
 export declare function client(transport?: Transport): Client;
-export { createAbility, exportAbility, deployToNode, listAbilities, invokeAbility, uninstallAbility, discoverNodes, executeCommand, forgetAll, disconnectDevice, drainDevice, listRemoteTools, buildDeployPackage, deployPackage, startServer, toToolSpec, type AbilityDescriptor, type AbilityTarget, type AbilityExportResult, type ServerHandle, type BridgeInterface, type ForgetAllResult, type ForgetAllFailure, type DeployResult, } from "./ability_lifecycle.js";
+export { buildAbilityDescriptor, exportAbility, deployToNode, listAbilities, invokeAbility, uninstallAbility, discoverNodes, executeCommand, forgetAll, disconnectDevice, drainDevice, listRemoteTools, buildDeployPackage, deployPackage, startServer, toToolSpec, type AbilityDescriptor, type AbilityTarget, type AbilityExportResult, type ServerHandle, type BridgeInterface, type ForgetAllResult, type ForgetAllFailure, type DeployResult, } from "./ability_lifecycle.js";
 export { AxonError, AxonConfigError, AxonBridgeError, AxonNotInstalledError, AxonNotActivatedError, AxonInvocationError, AxonStreamError, AxonPolicyDeniedError, AxonMcpError, AxonPartialSuccessError, AxonJsonError, AxonIoError, AxonSymbolNotFoundError, } from "./errors.js";
 export { beginPhase, skippedReceipt, buildDeployTrace, phaseFromTrace, PhaseReceiptBuilder, type Phase, type PhaseStatus, type PhaseReceipt, type DeployTrace, } from "./receipt.js";
 export { AbilityToolAdapter, type ToolSpec as AdapterToolSpec, type OpenAITool, type OpenAIChatTool, type AnthropicTool, type ToolParameters, type LocalHandler, type RegisterOptions, type AbilityToolAdapterOptions, } from "./tool_adapter.js";
-export { DendriteBridge, DendriteServerStream, DendriteBidiStream, type DendriteBridgeOptions, DendriteError, type DendriteUnaryCallOptions, type DendriteAbilityCallOptions, type DendriteStreamCallOptions, type DendriteClientStreamCallOptions, type DendriteBidiStreamCallOptions, type DendriteListNodesOptions, type DendriteRegisterNodeOptions, type DendritePublishCapabilityOptions, type DendriteInstallCapabilityOptions, type DendriteListA2aAgentsOptions, type DendriteSendA2aTaskOptions, type DendriteDeployMcpListDirOptions, type DendriteListMcpToolsOptions, type DendriteCallMcpToolOptions, type DendriteUninstallCapabilityOptions, type DendriteUpdateMcpListDirOptions, type DendriteVoiceCodecProfileOptions, type DendriteVoiceMetricsOptions, type DendriteVoiceDescriptionOptions, type DendriteVoiceCandidateOptions, type DendriteVoiceCreateCallOptions, type DendriteVoiceJoinCallOptions, type DendriteVoiceUpdateMediaPathOptions, type DendriteVoiceEndCallOptions, type DendriteVoiceWatchOptions, type DendriteVoiceCreateTransportSessionOptions, type DendriteVoiceEndTransportSessionOptions, type DendriteProtocolInvokeOptions, } from "./dendrite_bridge.js";
+export { DendriteBridge, DendriteServerStream, DendriteBidiStream, type DendriteBridgeOptions, DendriteError, type DendriteUnaryCallOptions, type DendriteAbilityCallOptions, type DendriteStreamCallOptions, type DendriteClientStreamCallOptions, type DendriteBidiStreamCallOptions, type DendriteListNodesOptions, type DendriteRegisterNodeOptions, type DendritePublishCapabilityOptions, type DendriteInstallCapabilityOptions, type DendriteListA2aAgentsOptions, type DendriteSendA2aTaskOptions, type DendriteDeployMcpListDirOptions, type DendriteListMcpToolsOptions, type DendriteCallMcpToolOptions, type DendriteCallMcpToolStreamOptions, type DendriteUninstallCapabilityOptions, type DendriteUpdateMcpListDirOptions, type DendriteVoiceCodecProfileOptions, type DendriteVoiceMetricsOptions, type DendriteVoiceDescriptionOptions, type DendriteVoiceCandidateOptions, type DendriteVoiceCreateCallOptions, type DendriteVoiceJoinCallOptions, type DendriteVoiceUpdateMediaPathOptions, type DendriteVoiceEndCallOptions, type DendriteVoiceWatchOptions, type DendriteVoiceCreateTransportSessionOptions, type DendriteVoiceEndTransportSessionOptions, type DendriteProtocolInvokeOptions, } from "./dendrite_bridge.js";

package/src/index.js

@@ -2,23 +2,22 @@
 // =========================
 //
 // File: sdk/node/src/index.ts
-// Description: Source file for Node SDK facade and Dendrite integration; keeps behavior explicit and interoperable across language/runtime boundaries with tenant/principal fluent context.
+// Description: Node SDK package-root facade for tenant-aware clients, sidecar transport, MCP helpers, and bridge exports.
 //
 // Protocol Responsibility:
-// - Implements Node SDK facade and Dendrite integration contracts required by current Axon service and SDK surfaces.
-// - Preserves stable request/response semantics and error mapping for index.ts call paths.
+// - Defines the package-root SDK facade and re-export surface consumed by application code.
+// - Keeps tenant-aware client, bridge, and tool APIs reachable through one stable import boundary.
 //
 // Implementation Approach:
-// - Uses small typed helpers and explicit control flow to avoid hidden side effects.
-// - Keeps protocol translation and transport details close to this module boundary.
+// - Composes smaller modules rather than re-implementing transport or protocol logic at the package root.
+// - Uses explicit exports so public surface changes remain auditable.
 //
 // Usage Contract:
-// - Callers should provide valid tenant/resource/runtime context before invoking exported APIs; principal context is optional and, when provided, is mapped to EasyNet subject context.
-// - Errors should be treated as typed protocol/runtime outcomes rather than silently ignored.
+// - Prefer importing from this boundary when consuming the SDK from application code.
+// - Public export changes here should be synchronized with language-specific packaging and documentation.
 //
 // Architectural Position:
-// - Part of the Node SDK facade and Dendrite integration layer.
-// - Should not embed unrelated orchestration logic outside this file's responsibility.
+// - Top-level SDK package boundary for application-facing imports.
 //
 // Author: Silan.Hu
 // Email: silan.hu@u.nus.edu
@@ -157,7 +156,7 @@ export class Client {
 export function client(transport) {
     return new Client(transport);
 }
-export { createAbility, exportAbility, deployToNode, listAbilities, invokeAbility, uninstallAbility, discoverNodes, executeCommand, forgetAll, disconnectDevice, drainDevice, listRemoteTools, buildDeployPackage, deployPackage, startServer, toToolSpec, } from "./ability_lifecycle.js";
+export { buildAbilityDescriptor, exportAbility, deployToNode, listAbilities, invokeAbility, uninstallAbility, discoverNodes, executeCommand, forgetAll, disconnectDevice, drainDevice, listRemoteTools, buildDeployPackage, deployPackage, startServer, toToolSpec, } from "./ability_lifecycle.js";
 export { AxonError, AxonConfigError, AxonBridgeError, AxonNotInstalledError, AxonNotActivatedError, AxonInvocationError, AxonStreamError, AxonPolicyDeniedError, AxonMcpError, AxonPartialSuccessError, AxonJsonError, AxonIoError, AxonSymbolNotFoundError, } from "./errors.js";
 export { beginPhase, skippedReceipt, buildDeployTrace, phaseFromTrace, PhaseReceiptBuilder, } from "./receipt.js";
 export { AbilityToolAdapter, } from "./tool_adapter.js";

package/src/mcp/server.d.ts

@@ -2,9 +2,20 @@ export interface McpToolResult {
     payload: Record<string, unknown>;
     isError: boolean;
 }
+/** Handle returned by streaming MCP tool providers. Consumers iterate `stream` and must call `close()` when done. */
+export interface McpToolStreamHandle {
+    stream: AsyncIterable<Uint8Array>;
+    close(): void;
+}
 export interface McpToolProvider {
     toolSpecs(): Array<Record<string, unknown>>;
     handleToolCall(name: string, args: Record<string, unknown>): McpToolResult | Promise<McpToolResult>;
+    /**
+     * Optional streaming handler. Return a `McpToolStreamHandle` to stream incremental chunks,
+     * or `null` to fall back to the unary `handleToolCall` path.
+     * When called via a non-streaming transport, the server buffers chunks into a single response.
+     */
+    handleToolCallStream?(name: string, args: Record<string, unknown>): McpToolStreamHandle | null;
 }
 interface McpTransportOptions {
     protocolVersion?: string;
@@ -14,16 +25,27 @@ interface McpTransportOptions {
 interface JsonMessage {
     [key: string]: unknown;
 }
+/** Callback used by the MCP server to write JSON-RPC messages to the transport. */
+export type McpWriteFn = (payload: JsonMessage) => Promise<void>;
 export declare class StdioMcpServer {
     private readonly provider;
     private readonly protocolVersion;
     private readonly serverName;
     private readonly serverVersion;
     private _closed;
+    private _pendingWrite;
     constructor(provider: McpToolProvider, options?: McpTransportOptions);
     close(): void;
     run(input: NodeJS.ReadableStream, output: NodeJS.WritableStream): void;
-    handleRawLine(raw: string): JsonMessage | Promise<JsonMessage> | null;
-    handleRequest(request: JsonMessage): JsonMessage | Promise<JsonMessage> | null;
+    private dispatchRequest;
+    private enqueueWrite;
+    handleRawLine(raw: string, writeFn?: McpWriteFn): JsonMessage | Promise<JsonMessage | null> | null;
+    handleRequest(request: JsonMessage, writeFn?: McpWriteFn): JsonMessage | Promise<JsonMessage | null> | null;
 }
+/**
+ * Buffer all chunks from a streaming MCP tool handle into a single result.
+ * Stops accumulating after `maxBytes` (default 64 MiB) to prevent unbounded
+ * memory growth.  Always closes the handle when done, even on error.
+ */
+export declare function consumeStream(handle: McpToolStreamHandle, maxBytes?: number): Promise<McpToolResult>;
 export {};