@easynet-run/node 0.27.14 → 0.39.29

package/src/mcp/server.js

@@ -8,6 +8,7 @@ export class StdioMcpServer {
     serverName;
     serverVersion;
     _closed = false;
+    _pendingWrite = Promise.resolve();
     constructor(provider, options = {}) {
         this.provider = provider;
         this.protocolVersion = options.protocolVersion?.trim() || DEFAULT_PROTOCOL_VERSION;
@@ -20,11 +21,11 @@ export class StdioMcpServer {
     run(input, output) {
         let cache = "";
         input.setEncoding("utf8");
+        const writeFn = (payload) => this.enqueueWrite(output, payload);
         input.on("error", (error) => {
             if (this._closed)
                 return;
-            const payload = jsonrpcError(null, -32000, `stream error: ${String(error)}`);
-            write(output, payload);
+            void writeFn(jsonrpcError(null, -32000, `stream error: ${String(error)}`));
         });
         input.on("close", () => {
             // no-op: caller controls lifecycle
@@ -34,7 +35,7 @@ export class StdioMcpServer {
                 return;
             cache += chunk.toString();
             if (cache.length > MAX_LINE_LENGTH && !cache.includes("\n")) {
-                write(output, jsonrpcError(null, -32000, `input line exceeds maximum length (${MAX_LINE_LENGTH} bytes)`));
+                void writeFn(jsonrpcError(null, -32000, `input line exceeds maximum length (${MAX_LINE_LENGTH} bytes)`));
                 cache = "";
                 return;
             }
@@ -47,31 +48,52 @@ export class StdioMcpServer {
                 if (this._closed)
                     break;
                 if (raw.length > MAX_LINE_LENGTH) {
-                    write(output, jsonrpcError(null, -32000, `input line exceeds maximum length (${MAX_LINE_LENGTH} bytes)`));
+                    void writeFn(jsonrpcError(null, -32000, `input line exceeds maximum length (${MAX_LINE_LENGTH} bytes)`));
                     continue;
                 }
                 const requestId = parseJson(raw)?.id ?? null;
-                const response = this.handleRawLine(raw);
-                if (response !== null) {
-                    if (typeof response.then === "function") {
-                        response.then((resolved) => { if (resolved !== null)
-                            write(output, resolved); }, (error) => { write(output, jsonrpcError(requestId, -32000, String(error))); });
-                    }
-                    else {
-                        write(output, response);
-                    }
-                }
+                void this.dispatchRequest(raw, writeFn, requestId);
+            }
+        });
+    }
+    async dispatchRequest(raw, writeFn, fallbackId) {
+        try {
+            const response = await this.handleRawLine(raw, writeFn);
+            if (response !== null && !this._closed) {
+                await writeFn(response);
+            }
+        }
+        catch (error) {
+            if (!this._closed) {
+                await writeFn(jsonrpcError(fallbackId, -32000, String(error)));
+            }
+        }
+    }
+    enqueueWrite(output, payload) {
+        this._pendingWrite = this._pendingWrite
+            .catch(() => undefined)
+            .then(async () => {
+            if (this._closed) {
+                return;
+            }
+            try {
+                await write(output, payload);
+            }
+            catch {
+                this._closed = true;
+                throw new Error("failed to write MCP response");
             }
         });
+        return this._pendingWrite;
     }
-    handleRawLine(raw) {
+    handleRawLine(raw, writeFn) {
         const request = parseJson(raw);
         if (request === null) {
             return jsonrpcError(null, -32700, "parse error");
         }
-        return this.handleRequest(request);
+        return this.handleRequest(request, writeFn);
     }
-    handleRequest(request) {
+    handleRequest(request, writeFn) {
         const id = request.id;
         const method = typeof request.method === "string" ? request.method : "";
         const params = asMap(request.params);
@@ -114,6 +136,28 @@ export class StdioMcpServer {
                 args = {};
             }
             const typedArgs = args;
+            // Try streaming path first.  When a writeFn is available, chunks are
+            // forwarded to the client as JSON-RPC notifications in real time.
+            // Otherwise the stream is buffered into a single response (fallback).
+            let streamHandle = null;
+            try {
+                streamHandle = this.provider.handleToolCallStream?.(name, typedArgs) ?? null;
+            }
+            catch (error) {
+                return jsonrpcSuccess(id, toolResponse({
+                    payload: { ok: false, error: String(error) },
+                    isError: true,
+                }));
+            }
+            if (streamHandle !== null) {
+                const maxBytes = resolveMaxBytes(typedArgs.max_bytes);
+                if (writeFn) {
+                    return streamToClient(streamHandle, id, writeFn, maxBytes);
+                }
+                return consumeStream(streamHandle, maxBytes)
+                    .then((result) => jsonrpcSuccess(id, toolResponse(result)))
+                    .catch((error) => jsonrpcSuccess(id, toolResponse(toolErrorResult(error))));
+            }
             let maybeResult;
             try {
                 maybeResult = this.provider.handleToolCall(name, typedArgs);
@@ -166,7 +210,34 @@ function asString(value) {
     return value.trim();
 }
 function write(stream, payload) {
-    stream.write(`${JSON.stringify(payload)}\n`);
+    return new Promise((resolve, reject) => {
+        const text = `${JSON.stringify(payload)}\n`;
+        const onDrain = () => {
+            cleanup();
+            resolve();
+        };
+        const onError = (error) => {
+            cleanup();
+            reject(error);
+        };
+        const cleanup = () => {
+            stream.removeListener("drain", onDrain);
+            stream.removeListener("error", onError);
+        };
+        try {
+            if (stream.write(text)) {
+                cleanup();
+                resolve();
+                return;
+            }
+            stream.once("drain", onDrain);
+            stream.once("error", onError);
+        }
+        catch (error) {
+            cleanup();
+            reject(error);
+        }
+    });
 }
 function toolResponse(result) {
     const payload = {
@@ -174,6 +245,12 @@ function toolResponse(result) {
     };
     return result.isError ? { ...payload, isError: true } : payload;
 }
+function toolErrorResult(error) {
+    return {
+        payload: { ok: false, error: String(error) },
+        isError: true,
+    };
+}
 function jsonrpcSuccess(id, result) {
     return {
         jsonrpc: "2.0",
@@ -188,3 +265,126 @@ function jsonrpcError(id, code, message) {
         error: { code, message },
     };
 }
+function jsonrpcNotification(method, params) {
+    return { jsonrpc: "2.0", method, params };
+}
+/** Default maximum total bytes (64 MiB) accepted from a single streamed MCP tool call. */
+const DEFAULT_MAX_STREAM_BYTES = 64 * 1024 * 1024; // 64 MiB
+/** Resolve a per-call max_bytes override. 0 or absent → default. */
+function resolveMaxBytes(raw) {
+    if (typeof raw === "number" && raw > 0)
+        return raw;
+    return DEFAULT_MAX_STREAM_BYTES;
+}
+function formatBytes(n) {
+    if (n >= 1024 * 1024 * 1024)
+        return `${(n / (1024 * 1024 * 1024)).toFixed(0)} GiB`;
+    if (n >= 1024 * 1024)
+        return `${(n / (1024 * 1024)).toFixed(0)} MiB`;
+    if (n >= 1024)
+        return `${(n / 1024).toFixed(0)} KiB`;
+    return `${n} bytes`;
+}
+/**
+ * Common helper that iterates a stream handle, converts each chunk to UTF-8,
+ * validates encoding, enforces a byte limit, and closes the handle when done.
+ *
+ * - **Streaming mode** (`onChunk` provided): calls `onChunk` for each decoded
+ *   chunk and does NOT accumulate chunks in memory.
+ * - **Buffer mode** (`onChunk` omitted): accumulates all decoded chunks into
+ *   the returned `chunks` array.
+ */
+async function processStream(handle, maxBytes, onChunk) {
+    const result = {
+        hadError: null,
+        hadInvalidUtf8: false,
+        chunkCount: 0,
+        chunks: [],
+    };
+    let totalBytes = 0;
+    try {
+        for await (const raw of handle.stream) {
+            const buf = Buffer.from(raw);
+            const text = buf.toString("utf8");
+            if (!result.hadInvalidUtf8 && buf.length > 0 && text.includes('\uFFFD')) {
+                result.hadInvalidUtf8 = true;
+            }
+            totalBytes += buf.length;
+            if (totalBytes > maxBytes) {
+                const suffix = onChunk ? "limit" : "buffer limit";
+                result.hadError = `stream output exceeded ${formatBytes(maxBytes)} ${suffix}`;
+                break;
+            }
+            if (onChunk) {
+                await onChunk(text, result.chunkCount);
+            }
+            else {
+                result.chunks.push(text);
+            }
+            result.chunkCount++;
+        }
+    }
+    catch (error) {
+        result.hadError = String(error);
+    }
+    finally {
+        try {
+            handle.close();
+        }
+        catch (e) {
+            console.error("mcp: stream close failed:", e);
+        }
+    }
+    return result;
+}
+/**
+ * Stream tool output to the client in real time using JSON-RPC notifications.
+ *
+ * Each chunk is sent as an `axon/streamChunk` notification as soon as it
+ * arrives from the underlying stream.  After the stream completes (or on
+ * error) a final JSON-RPC response is returned with a summary.
+ *
+ * Clients that do not understand `axon/streamChunk` simply ignore the
+ * notifications and still receive the final summary response.
+ */
+async function streamToClient(handle, requestId, writeFn, maxBytes = DEFAULT_MAX_STREAM_BYTES) {
+    const result = await processStream(handle, maxBytes, async (decoded, seq) => {
+        await writeFn(jsonrpcNotification("axon/streamChunk", {
+            requestId,
+            seq,
+            chunk: decoded,
+        }));
+    });
+    const summary = {
+        ok: result.hadError === null,
+        chunk_count: result.chunkCount,
+        streamed: true,
+    };
+    if (result.hadError)
+        summary.error = result.hadError;
+    if (result.hadInvalidUtf8)
+        summary.contains_invalid_utf8 = true;
+    return jsonrpcSuccess(requestId, toolResponse({
+        payload: summary,
+        isError: result.hadError !== 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 async function consumeStream(handle, maxBytes = DEFAULT_MAX_STREAM_BYTES) {
+    const result = await processStream(handle, maxBytes);
+    if (result.hadError !== null) {
+        return {
+            payload: { ok: false, chunk_count: result.chunks.length, chunks: result.chunks, error: result.hadError },
+            isError: true,
+        };
+    }
+    const payload = { ok: true, chunk_count: result.chunks.length, chunks: result.chunks };
+    if (result.hadInvalidUtf8) {
+        payload.contains_invalid_utf8 = true;
+    }
+    return { payload, isError: false };
+}

package/src/mcp/server.test.js

@@ -0,0 +1,100 @@
+// EasyNet Axon for AgentNet
+// =========================
+//
+// File: sdk/node/src/mcp/server.test.js
+// Description: JavaScript runtime mirror for `sdk/node/src/mcp/server.test.js` in the published Node SDK artifact set.
+//
+// Protocol Responsibility:
+// - Preserves the exported API surface generated from the canonical TypeScript source module.
+// - Keeps the distributable Node package consistent for consumers that import built artifacts directly.
+//
+// Implementation Approach:
+// - Mirrors the canonical `.ts` module output and should not diverge semantically from source.
+// - Exists as a distribution artifact so package consumers do not need the TypeScript authoring tree at runtime.
+//
+// Usage Contract:
+// - Update this file through the Node SDK build pipeline when the corresponding TypeScript source changes.
+// - Treat manual edits here as temporary at most; source-of-truth behavior lives in the `.ts` module.
+//
+// Architectural Position:
+// - Published artifact boundary for the Node SDK distribution.
+//
+// Author: Silan.Hu
+// Email: silan.hu@u.nus.edu
+// Copyright (c) 2026-2027 easynet. All rights reserved.
+
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { PassThrough } from "node:stream";
+
+import { StdioMcpServer } from "./server.js";
+
+describe("StdioMcpServer", () => {
+  it("keeps buffered stream responses intact when close throws", async () => {
+    const originalConsoleError = console.error;
+    const consoleErrors = [];
+    console.error = (...args) => {
+      consoleErrors.push(args);
+    };
+
+    const server = new StdioMcpServer({
+      toolSpecs: () => [],
+      handleToolCall: () => ({ payload: { ok: true }, isError: false }),
+      handleToolCallStream: () => ({
+        stream: {
+          async *[Symbol.asyncIterator]() {
+            yield Buffer.from("chunk-1");
+          },
+        },
+        close() {
+          throw new Error("close failed");
+        },
+      }),
+    });
+
+    try {
+      const response = await server.handleRequest({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "tools/call",
+        params: {
+          name: "streamed_tool",
+          arguments: {},
+        },
+      });
+
+      assert.equal(response.jsonrpc, "2.0");
+      const payload = JSON.parse(response.result.content[0].text);
+      assert.equal(payload.ok, true);
+      assert.deepEqual(payload.chunks, ["chunk-1"]);
+      assert.equal(response.result.isError, undefined);
+      assert.equal(consoleErrors.length, 1);
+    } finally {
+      console.error = originalConsoleError;
+    }
+  });
+
+  it("serializes writes through drain backpressure", async () => {
+    const input = new PassThrough();
+    const chunks = [];
+    const output = new PassThrough({ highWaterMark: 1 });
+    output.on("data", (chunk) => {
+      chunks.push(chunk.toString("utf8"));
+    });
+    const server = new StdioMcpServer({
+      toolSpecs: () => [],
+      handleToolCall: () => ({ payload: { ok: true }, isError: false }),
+    });
+
+    server.run(input, output);
+    input.write('{"jsonrpc":"2.0","id":1,"method":"ping"}\n');
+    input.write('{"jsonrpc":"2.0","id":2,"method":"ping"}\n');
+    input.end();
+
+    await new Promise((resolve) => setTimeout(resolve, 25));
+
+    assert.equal(chunks.length, 2);
+    assert.match(chunks[0], /"id":1/);
+    assert.match(chunks[1], /"id":2/);
+  });
+});

package/src/presets/ability_dispatch/workflow.js

@@ -24,9 +24,9 @@
 // Copyright (c) 2026-2027 easynet. All rights reserved.
 // Node server flow: publish/install/activate media capability on selected client and invoke tasks.
 import { Orchestrator } from "./orchestrator.js";
-import { existsSync, mkdirSync, readFileSync } from "node:fs";
-import { dirname, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
+import { resolveLibraryPath } from "../../dendrite_bridge/ffi.js";
+import { mkdirSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
 import { parseArgs, parsePositiveInt } from "./args.js";
 import { readBundleVersion, resolveBundlePath, sha256Prefixed } from "./bundle.js";
 import { decodeMediaBase64, defaultOutputDir, persistMediaFile } from "./media.js";
@@ -53,36 +53,14 @@ function resolveConfig(cfg) {
         taskPayloadBuilder: cfg?.taskPayloadBuilder ?? mediaCaptureTaskPayload,
     };
 }
-function defaultBridgeLibName() {
-    if (process.platform === "darwin")
-        return "libaxon_dendrite_bridge.dylib";
-    if (process.platform === "win32")
-        return "axon_dendrite_bridge.dll";
-    return "libaxon_dendrite_bridge.so";
-}
-function findRepoRootForBridge(startDir) {
-    let current = resolve(startDir);
-    for (let steps = 0; steps < 10; steps += 1) {
-        const candidate = resolve(current, "core/runtime-rs/dendrite-bridge/target/release", defaultBridgeLibName());
-        if (existsSync(candidate)) {
-            return current;
-        }
-        const parent = dirname(current);
-        if (parent === current) {
-            break;
-        }
-        current = parent;
-    }
-    return "";
-}
 function ensureBridgeLibEnv() {
     if (process.env.EASYNET_DENDRITE_BRIDGE_LIB)
         return;
-    const here = dirname(fileURLToPath(import.meta.url));
-    const repoRoot = findRepoRootForBridge(here) || process.cwd();
-    const candidate = resolve(repoRoot, "core/runtime-rs/dendrite-bridge/target/release", defaultBridgeLibName());
-    if (existsSync(candidate)) {
-        process.env.EASYNET_DENDRITE_BRIDGE_LIB = candidate;
+    try {
+        process.env.EASYNET_DENDRITE_BRIDGE_LIB = resolveLibraryPath();
+    }
+    catch {
+        // Non-fatal: library may be resolved later by the bridge constructor.
     }
 }
 function extractInstallId(lifecycle) {

package/src/presets/remote_control/config.d.ts

@@ -8,9 +8,12 @@ export declare const DEFAULT_SIGNATURE = "__AXON_EPHEMERAL_DO_NOT_USE_IN_PROD__"
 export declare const DEFAULT_VERSION = "1.0.0";
 export declare const DEFAULT_INSTALL_TIMEOUT_SECONDS = 45;
 export declare const DEFAULT_EXECUTION_MODE = "sandbox_first";
+export { DEFAULT_MCP_TOOL_STREAM_TIMEOUT_MS } from "../../dendrite_bridge/ffi.js";
 export declare function loadRemoteControlConfigFromEnv(): RemoteControlRuntimeConfig;
 export declare function loadConfigFromEnv(): RemoteControlRuntimeConfig;
 export declare function ensureRemoteControlNativeLibEnv(): void;
 export declare function ensureNativeLibEnv(): void;
 export declare function parsePositiveInt(raw: string | undefined, fallback: number): number;
 export declare function asString(raw: unknown, fallback?: string): string;
+export declare function asBool(raw: unknown): boolean;
+export declare function asNumber(raw: unknown): number;

package/src/presets/remote_control/config.js

@@ -1,20 +1,18 @@
 // EasyNet Axon for AgentNet
 // =========================
 //
-// File: sdk/node/src/presets/remote_control/config.js
-// Description: AUTO-GENERATED — compiled from config.ts. Runtime configuration for the remote-control preset.
+// File: sdk/node/src/presets/remote_control/config.ts
+// Description: Runtime configuration and constants for the remote-control preset.
 //
 // Author: Silan.Hu
 // Email: silan.hu@u.nus.edu
 // Copyright (c) 2026-2027 easynet. All rights reserved.
-
-import { existsSync } from "node:fs";
-import { dirname, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
+import { resolveLibraryPath } from "../../dendrite_bridge/ffi.js";
 export const DEFAULT_SIGNATURE = "__AXON_EPHEMERAL_DO_NOT_USE_IN_PROD__";
 export const DEFAULT_VERSION = "1.0.0";
 export const DEFAULT_INSTALL_TIMEOUT_SECONDS = 45;
 export const DEFAULT_EXECUTION_MODE = "sandbox_first";
+export { DEFAULT_MCP_TOOL_STREAM_TIMEOUT_MS } from "../../dendrite_bridge/ffi.js";
 export function loadRemoteControlConfigFromEnv() {
     return {
         endpoint: process.env.AXON_ENDPOINT ?? "http://127.0.0.1:50051",
@@ -30,16 +28,11 @@ export function ensureRemoteControlNativeLibEnv() {
     if (process.env.EASYNET_DENDRITE_BRIDGE_LIB) {
         return;
     }
-    const moduleDir = dirname(fileURLToPath(import.meta.url));
-    const candidates = [
-        resolve(moduleDir, "..", "..", "core", "runtime-rs", "dendrite-bridge", "target", "release", defaultNativeLibName()),
-        resolve(moduleDir, "..", "..", "core", "runtime-rs", "dendrite-bridge", "target", "debug", defaultNativeLibName()),
-    ];
-    for (const candidate of candidates) {
-        if (existsSync(candidate)) {
-            process.env.EASYNET_DENDRITE_BRIDGE_LIB = candidate;
-            return;
-        }
+    try {
+        process.env.EASYNET_DENDRITE_BRIDGE_LIB = resolveLibraryPath();
+    }
+    catch {
+        // Non-fatal: library may be resolved later by the bridge constructor.
     }
 }
 export function ensureNativeLibEnv() {
@@ -52,12 +45,17 @@ export function parsePositiveInt(raw, fallback) {
 export function asString(raw, fallback = "") {
     return raw == null ? fallback : String(raw).trim() || fallback;
 }
-function defaultNativeLibName() {
-    if (process.platform === "darwin") {
-        return "libaxon_dendrite_bridge.dylib";
-    }
-    if (process.platform === "win32") {
-        return "axon_dendrite_bridge.dll";
-    }
-    return "libaxon_dendrite_bridge.so";
+export function asBool(raw) {
+    if (typeof raw === "boolean")
+        return raw;
+    if (typeof raw === "number")
+        return raw !== 0;
+    const normalized = String(raw ?? "").trim().toLowerCase();
+    return normalized === "true" || normalized === "1" || normalized === "yes" || normalized === "on";
+}
+export function asNumber(raw) {
+    if (typeof raw === "number")
+        return raw;
+    const value = Number.parseInt(String(raw ?? "0"), 10);
+    return Number.isFinite(value) ? value : 0;
 }

package/src/presets/remote_control/descriptor.d.ts

@@ -1,3 +1,25 @@
+export type AbilityTarget = "claude" | "codex" | "openclaw" | "agent_skills";
+export interface AbilityDescriptorLite {
+    name: string;
+    toolName: string;
+    description: string;
+    commandTemplate: string;
+    inputSchema: JsonRecord;
+    outputSchema: JsonRecord;
+    version: string;
+    tags: string[];
+    resourceUri: string;
+    instructions: string;
+    inputExamples: JsonRecord[];
+    prerequisites: string[];
+    contextBindings: Record<string, string>;
+    category: string;
+}
+export interface AbilityExportResult {
+    abilityName: string;
+    abilityMd: string;
+    invokeScript: string;
+}
 export interface JsonRecord {
     [key: string]: unknown;
 }
@@ -31,4 +53,18 @@ export declare function defaultOutputSchema(): JsonRecord;
 export declare function serializeDescriptor(descriptor: AbilityPackageDescriptor): JsonRecord;
 export declare function requireString(payload: JsonRecord, key: string): string;
 export declare function parseDescriptor(raw: unknown): AbilityPackageDescriptor;
+/**
+ * Build an `AbilityPackageDescriptor` from handler arguments.
+ *
+ * Normalises names, generates a package ID, encodes the command template
+ * into Base64 package bytes, and serialises agent extension properties
+ * (instructions, input_examples, prerequisites, context_bindings, category)
+ * into the metadata map under the `mcp.*` prefix.
+ *
+ * @throws {Error} If `ability_name`, `command_template`, or `signature_base64` is missing.
+ */
 export declare function buildDescriptor(args: JsonRecord, defaultSignature: string): AbilityPackageDescriptor;
+export declare function createAbilityDescriptor(args: JsonRecord): AbilityDescriptorLite;
+declare function parseAbilityTarget(raw: string): AbilityTarget;
+export declare function exportAbilitySkill(descriptor: AbilityDescriptorLite, target?: AbilityTarget, axonEndpoint?: string): AbilityExportResult;
+export { parseAbilityTarget };