@easynet-run/node 0.27.14 → 0.39.29

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

@@ -1,3 +1,4 @@
+import { DendriteServerStream } from "../../dendrite_bridge.js";
 import type { JsonRecord, AbilityPackageDescriptor } from "./descriptor.js";
 export type { JsonRecord };
 export type OrchestratorFactory = (config: {
@@ -10,6 +11,11 @@ export interface RemoteOrchestrator {
     listNodes(ownerId?: string): JsonRecord[];
     listMcpTools(namePattern?: string, tags?: string[], nodeId?: string): JsonRecord[];
     callMcpTool(toolName: string, targetNodeId: string, argumentsJson: JsonRecord): JsonRecord;
+    /** Call an MCP tool on a remote node and return a stream of incremental response chunks. */
+    callMcpToolStream(toolName: string, targetNodeId: string, argumentsJson: JsonRecord, options?: {
+        timeoutMs?: number;
+    }): DendriteServerStream;
+    drainNode(nodeId: string, reason: string): JsonRecord;
     disconnectDevice(nodeId: string, reason: string): JsonRecord;
     uninstallAbility(nodeId: string, installId: string, reason: string): JsonRecord;
     deployAbilityPackage(descriptor: AbilityPackageDescriptor, nodeId: string, cleanupOnActivateFailure: boolean): JsonRecord;

package/src/presets/remote_control/orchestrator.js

@@ -1,4 +1,28 @@
-import { DendriteBridge } from "../../dendrite_bridge.js";
+// EasyNet Axon for AgentNet
+// =========================
+//
+// File: sdk/node/src/presets/remote_control/orchestrator.ts
+// Description: Node remote-control orchestrator adapter that translates preset calls into DendriteBridge operations.
+//
+// Protocol Responsibility:
+// - Wraps low-level bridge operations in remote-control terminology such as ability, device, and tool workflows.
+// - Centralizes publish, install, invoke, cleanup, and list flows shared by remote-control handlers.
+//
+// Implementation Approach:
+// - Keeps bridge semantics explicit while translating internal capability and node naming into public preset APIs.
+// - Holds connection and timeout policy close to the transport boundary so handler code stays declarative.
+//
+// Usage Contract:
+// - Callers should construct or reuse orchestrators with valid endpoint, tenant, and native-library context.
+// - Close or release orchestrator resources when the preset is no longer serving requests.
+//
+// Architectural Position:
+// - Mid-layer adapter between remote-control handlers and bridge or client transport implementations.
+//
+// Author: Silan.Hu
+// Email: silan.hu@u.nus.edu
+// Copyright (c) 2026-2027 easynet. All rights reserved.
+import { DendriteBridge, } from "../../dendrite_bridge.js";
 import { DEFAULT_EXECUTION_MODE, DEFAULT_INSTALL_TIMEOUT_SECONDS } from "./config.js";
 export function buildOrchestrator(config, tenant) {
     return new OrchestratorAdapter(config, tenant);
@@ -26,6 +50,17 @@ class OrchestratorAdapter {
         const options = { targetNodeId, argumentsJson };
         return this.bridge.callMcpTool(this.tenant, toolName, options);
     }
+    callMcpToolStream(toolName, targetNodeId, argumentsJson = {}, options = {}) {
+        const streamOptions = {
+            targetNodeId,
+            argumentsJson,
+            timeoutMs: options.timeoutMs,
+        };
+        return this.bridge.callMcpToolStream(this.tenant, toolName, streamOptions);
+    }
+    drainNode(nodeId, reason) {
+        return this.bridge.drainNode(this.tenant, nodeId, reason);
+    }
     disconnectDevice(nodeId, reason) {
         return this.bridge.deregisterNode(this.tenant, nodeId, reason);
     }

package/src/presets/remote_control/specs.js

@@ -1,3 +1,37 @@
+// EasyNet Axon for AgentNet
+// =========================
+//
+// File: sdk/node/src/presets/remote_control/specs.ts
+// Description: Node definitions for the canonical remote-control MCP tool catalog and JSON schemas.
+//
+// Protocol Responsibility:
+// - Publishes the canonical remote-control MCP tool catalog, descriptions, and input schemas for agents.
+// - Keeps tool names and schema-visible behavior aligned across all first-party SDK implementations.
+//
+// Implementation Approach:
+// - Represents tool contracts as static data builders plus small helper combinators for shared schema fragments.
+// - Favors explicit schema literals so parity checks can diff outputs deterministically across languages.
+//
+// Usage Contract:
+// - Any rename or schema change here must be mirrored across SDKs and covered by parity tests.
+// - Consumers should treat these definitions as externally visible protocol metadata, not UI-only hints.
+//
+// Architectural Position:
+// - Contract catalog layer for the remote-control preset.
+//
+// Author: Silan.Hu
+// Email: silan.hu@u.nus.edu
+// Copyright (c) 2026-2027 easynet. All rights reserved.
+/** Shared agent-extension properties reused across deploy/package tool specs. */
+function agentExtensionProperties() {
+    return {
+        instructions: { type: "string", description: "Full operational instructions for AI agents (SKILL.md equivalent, <5000 tokens). Explain what the tool does, when to use it, step-by-step usage, and error handling." },
+        input_examples: { type: "array", items: { type: "object" }, description: "Example input objects conforming to input_schema. Helps agents understand invocation patterns." },
+        prerequisites: { type: "array", items: { type: "string" }, description: "Requirements before calling this tool (e.g. 'Must call session_start first')." },
+        context_bindings: { type: "object", description: "Context bindings declaring what this ability accesses (e.g. env.PYTHON_PATH, resource.camera)." },
+        category: { type: "string", description: "Tool category for grouping (e.g. 'session', 'filesystem', 'network', 'system')." },
+    };
+}
 export function remoteControlToolSpecs() {
     return [
         // -----------------------------------------------------------------
@@ -5,61 +39,77 @@ export function remoteControlToolSpecs() {
         // -----------------------------------------------------------------
         {
             name: "discover_nodes",
-            description: "Discover online nodes registered with Axon Runtime.",
+            description: "Discover online nodes registered with Axon Runtime. Use this first to find available devices before calling other tools. Returns a list of nodes with their online status.",
             inputSchema: {
                 type: "object",
-                properties: { tenant_id: { type: "string", description: "Tenant ID (default AXON_TENANT)" } },
+                properties: { tenant_id: { type: "string", description: "Tenant ID (default AXON_TENANT)." } },
             },
         },
         {
             name: "list_remote_tools",
-            description: "List MCP tools visible for a tenant.",
+            description: "List MCP tools visible for a tenant. Use after discover_nodes to see what tools are available on a specific node or across all nodes.",
             inputSchema: {
                 type: "object",
                 properties: {
-                    tenant_id: { type: "string" },
-                    node_id: { type: "string" },
-                    name_pattern: { type: "string" },
+                    tenant_id: { type: "string", description: "Tenant ID (default AXON_TENANT)." },
+                    node_id: { type: "string", description: "Filter tools by a specific node." },
+                    name_pattern: { type: "string", description: "Glob pattern to filter tool names (e.g. 'session_*')." },
                 },
             },
         },
         {
             name: "call_remote_tool",
-            description: "Call an MCP tool on a selected node.",
+            description: "Call an MCP tool on a selected node and return the full result. Use for quick operations that return a single response. For long-running or streaming tools, prefer call_remote_tool_stream.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    tenant_id: { type: "string", description: "Tenant ID (default AXON_TENANT)." },
+                    tool_name: { type: "string", description: "Name of the MCP tool to invoke." },
+                    node_id: { type: "string", description: "Target node ID (from discover_nodes)." },
+                    arguments: { type: "object", description: "Tool-specific arguments passed to the remote tool." },
+                },
+                required: ["tool_name", "node_id"],
+            },
+        },
+        {
+            name: "call_remote_tool_stream",
+            description: "Call an MCP tool on a selected node and stream incremental response chunks. Prefer this for long-running or incremental-output tools instead of call_remote_tool. Falls back to buffered response when streaming is unavailable.",
             inputSchema: {
                 type: "object",
                 properties: {
-                    tenant_id: { type: "string" },
-                    tool_name: { type: "string" },
-                    node_id: { type: "string" },
-                    arguments: { type: "object" },
+                    tenant_id: { type: "string", description: "Tenant ID (default AXON_TENANT)." },
+                    tool_name: { type: "string", description: "Name of the MCP tool to invoke." },
+                    node_id: { type: "string", description: "Target node ID (from discover_nodes)." },
+                    arguments: { type: "object", description: "Tool-specific arguments passed to the remote tool." },
+                    timeout_ms: { type: "integer", description: "Per-chunk timeout in milliseconds for streaming reads (default 60000)." },
+                    max_bytes: { type: "integer", description: "Maximum total bytes accepted from the stream (default 64 MiB). Set higher for large transfers." },
                 },
                 required: ["tool_name", "node_id"],
             },
         },
         {
             name: "disconnect_device",
-            description: "Deregister a remote device from the Axon Runtime, closing its connection.",
+            description: "Deregister a remote device from the Axon Runtime, closing its connection. Use when a device should be removed from the active node list.",
             inputSchema: {
                 type: "object",
                 properties: {
-                    tenant_id: { type: "string" },
-                    node_id: { type: "string" },
-                    reason: { type: "string" },
+                    tenant_id: { type: "string", description: "Tenant ID (default AXON_TENANT)." },
+                    node_id: { type: "string", description: "Node ID of the device to disconnect." },
+                    reason: { type: "string", description: "Human-readable reason for disconnection." },
                 },
                 required: ["node_id"],
             },
         },
         {
             name: "uninstall_ability",
-            description: "Uninstall a deployed ability from a device by deactivating and removing it.",
+            description: "Uninstall a deployed ability from a device by deactivating and removing it. Use to clean up abilities that are no longer needed.",
             inputSchema: {
                 type: "object",
                 properties: {
-                    tenant_id: { type: "string" },
-                    node_id: { type: "string" },
-                    install_id: { type: "string" },
-                    reason: { type: "string" },
+                    tenant_id: { type: "string", description: "Tenant ID (default AXON_TENANT)." },
+                    node_id: { type: "string", description: "Target node ID." },
+                    install_id: { type: "string", description: "Installation ID returned by deploy_ability or deploy_ability_package." },
+                    reason: { type: "string", description: "Human-readable reason for uninstallation." },
                 },
                 required: ["node_id", "install_id"],
             },
@@ -69,15 +119,17 @@ export function remoteControlToolSpecs() {
         // -----------------------------------------------------------------
         {
             name: "deploy_ability",
-            description: "Deploy a command-backed MCP ability.",
+            description: "Deploy a simple command-backed MCP ability to a device. This is the easiest way to make a command available as a remote tool. For advanced deployment options (custom schemas, versioning, signatures), use deploy_ability_package instead.",
             inputSchema: {
                 type: "object",
                 properties: {
-                    tenant_id: { type: "string" },
-                    node_id: { type: "string" },
-                    tool_name: { type: "string" },
-                    description: { type: "string" },
-                    command_template: { type: "string" },
+                    tenant_id: { type: "string", description: "Tenant ID (default AXON_TENANT)." },
+                    node_id: { type: "string", description: "Target node ID to deploy the ability to." },
+                    tool_name: { type: "string", description: "Name for the new MCP tool (auto-generated if omitted)." },
+                    description: { type: "string", description: "Human-readable description of what this tool does." },
+                    command_template: { type: "string", description: "Shell command template to execute on the device." },
+                    metadata: { type: "object", description: "Additional metadata for the ability." },
+                    ...agentExtensionProperties(),
                 },
                 required: ["node_id", "command_template"],
             },
@@ -87,48 +139,52 @@ export function remoteControlToolSpecs() {
         // -----------------------------------------------------------------
         {
             name: "package_ability",
-            description: "Build a native ability package descriptor.",
+            description: "Build a native ability package descriptor without deploying. Use this to prepare a package for later deployment with deploy_ability_package, or to inspect the descriptor before committing.",
             inputSchema: {
                 type: "object",
                 properties: {
-                    tenant_id: { type: "string" },
-                    ability_name: { type: "string" },
-                    tool_name: { type: "string" },
-                    description: { type: "string" },
-                    command_template: { type: "string" },
-                    input_schema: { type: "object" },
-                    output_schema: { type: "object" },
-                    version: { type: "string" },
-                    tags: { type: "array", items: { type: "string" } },
-                    package_id: { type: "string" },
-                    capability_name: { type: "string" },
-                    signature_base64: { type: "string" },
-                    digest: { type: "string" },
+                    tenant_id: { type: "string", description: "Tenant ID (default AXON_TENANT)." },
+                    ability_name: { type: "string", description: "Unique name for the ability." },
+                    tool_name: { type: "string", description: "MCP tool name exposed after deployment." },
+                    description: { type: "string", description: "Human-readable description." },
+                    command_template: { type: "string", description: "Shell command template to execute." },
+                    input_schema: { type: "object", description: "JSON Schema for tool input validation." },
+                    output_schema: { type: "object", description: "JSON Schema for tool output." },
+                    version: { type: "string", description: "Semantic version (default '1.0.0')." },
+                    tags: { type: "array", items: { type: "string" }, description: "Tags for categorization." },
+                    metadata: { type: "object", description: "Additional metadata." },
+                    package_id: { type: "string", description: "Custom package identifier." },
+                    capability_name: { type: "string", description: "Override capability name in the registry." },
+                    signature_base64: { type: "string", description: "Base64-encoded deployment signature." },
+                    digest: { type: "string", description: "Content digest for integrity verification." },
+                    ...agentExtensionProperties(),
                 },
                 required: ["ability_name", "command_template"],
             },
         },
         {
             name: "deploy_ability_package",
-            description: "Deploy a native ability package by publish/install/activate.",
+            description: "Deploy a native ability package through the full publish/install/activate pipeline. Use this for advanced deployments with custom schemas, versioning, or pre-built package descriptors. For simple command deployments, prefer deploy_ability.",
             inputSchema: {
                 type: "object",
                 properties: {
-                    tenant_id: { type: "string" },
-                    node_id: { type: "string" },
-                    package: { type: "object" },
-                    ability_name: { type: "string" },
-                    tool_name: { type: "string" },
-                    description: { type: "string" },
-                    command_template: { type: "string" },
-                    input_schema: { type: "object" },
-                    output_schema: { type: "object" },
-                    version: { type: "string" },
-                    tags: { type: "array", items: { type: "string" } },
-                    package_id: { type: "string" },
-                    capability_name: { type: "string" },
-                    signature_base64: { type: "string" },
-                    cleanup_on_activate_failure: { type: "boolean" },
+                    tenant_id: { type: "string", description: "Tenant ID (default AXON_TENANT)." },
+                    node_id: { type: "string", description: "Target node ID to deploy to." },
+                    package: { type: "object", description: "Pre-built package descriptor (from package_ability). If provided, other descriptor fields are ignored." },
+                    ability_name: { type: "string", description: "Unique name for the ability." },
+                    tool_name: { type: "string", description: "MCP tool name exposed after deployment." },
+                    description: { type: "string", description: "Human-readable description." },
+                    command_template: { type: "string", description: "Shell command template to execute." },
+                    input_schema: { type: "object", description: "JSON Schema for tool input validation." },
+                    output_schema: { type: "object", description: "JSON Schema for tool output." },
+                    version: { type: "string", description: "Semantic version (default '1.0.0')." },
+                    tags: { type: "array", items: { type: "string" }, description: "Tags for categorization." },
+                    metadata: { type: "object", description: "Additional metadata." },
+                    package_id: { type: "string", description: "Custom package identifier." },
+                    capability_name: { type: "string", description: "Override capability name in the registry." },
+                    signature_base64: { type: "string", description: "Base64-encoded deployment signature." },
+                    cleanup_on_activate_failure: { type: "boolean", description: "Auto-cleanup on activation failure (default true)." },
+                    ...agentExtensionProperties(),
                 },
                 required: ["node_id"],
             },
@@ -136,17 +192,117 @@ export function remoteControlToolSpecs() {
         // AI-AGENT PRESET: one-shot command execution
         {
             name: "execute_command",
-            description: "One-shot command execution via temporary MCP ability.",
+            description: "One-shot command execution on a remote device. Deploys a temporary ability, runs the command, returns the output, and cleans up. Use for ad-hoc commands that don't need a persistent tool.",
             inputSchema: {
                 type: "object",
                 properties: {
-                    tenant_id: { type: "string" },
-                    node_id: { type: "string" },
-                    command: { type: "string" },
-                    cleanup: { type: "boolean" },
+                    tenant_id: { type: "string", description: "Tenant ID (default AXON_TENANT)." },
+                    node_id: { type: "string", description: "Target node ID to execute on." },
+                    command: { type: "string", description: "Shell command to execute on the device." },
+                    cleanup: { type: "boolean", description: "Remove the temporary ability after execution (default true)." },
                 },
                 required: ["node_id", "command"],
             },
         },
+        // -----------------------------------------------------------------
+        // DEVICE MANAGEMENT & ABILITY LIFECYCLE TOOLS
+        // Ported from Rust SDK for cross-SDK parity.
+        // -----------------------------------------------------------------
+        {
+            name: "drain_device",
+            description: "Drain a remote device — stop accepting new invocations while finishing in-flight ones.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    tenant_id: { type: "string", description: "Tenant ID (default AXON_TENANT)." },
+                    node_id: { type: "string", description: "Target device node ID." },
+                    reason: { type: "string", description: "Reason for draining." },
+                },
+                required: ["node_id"],
+            },
+        },
+        {
+            name: "build_ability_descriptor",
+            description: "Build an AbilityDescriptor locally without deploying it.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    name: { type: "string", description: "Ability name." },
+                    description: { type: "string", description: "Ability description." },
+                    command_template: { type: "string", description: "Shell command template to back the ability." },
+                    input_schema: { type: "object", description: "Input JSON schema." },
+                    output_schema: { type: "object", description: "Output JSON schema." },
+                    version: { type: "string", description: "Ability version." },
+                    tags: { type: "array", items: { type: "string" }, description: "Ability tags." },
+                    resource_uri: { type: "string", description: "Resource URI." },
+                    ...agentExtensionProperties(),
+                },
+                required: ["name", "command_template"],
+            },
+        },
+        {
+            name: "export_ability_skill",
+            description: "Export an AbilityDescriptor as an Agent Skills SKILL.md and invoke.sh.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    name: { type: "string", description: "Ability name." },
+                    description: { type: "string", description: "Ability description." },
+                    command_template: { type: "string", description: "Shell command template to back the ability." },
+                    input_schema: { type: "object", description: "Input JSON schema." },
+                    output_schema: { type: "object", description: "Output JSON schema." },
+                    version: { type: "string", description: "Ability version." },
+                    tags: { type: "array", items: { type: "string" }, description: "Ability tags." },
+                    resource_uri: { type: "string", description: "Resource URI." },
+                    target: { type: "string", description: "Ability target: claude, codex, openclaw, agent_skills." },
+                    axon_endpoint: { type: "string", description: "Axon endpoint for invoke script." },
+                    ...agentExtensionProperties(),
+                },
+                required: ["name", "command_template"],
+            },
+        },
+        {
+            name: "redeploy_ability",
+            description: "Redeploy an ability to a device by rebuilding and replacing its full package.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    tenant_id: { type: "string", description: "Tenant ID (default AXON_TENANT)." },
+                    node_id: { type: "string", description: "Target device node ID." },
+                    tool_name: { type: "string", description: "Existing tool name to update." },
+                    description: { type: "string", description: "New description." },
+                    command_template: { type: "string", description: "New command template." },
+                    input_schema: { type: "object", description: "New input schema." },
+                    output_schema: { type: "object", description: "New output schema." },
+                },
+                required: ["node_id", "tool_name", "command_template"],
+            },
+        },
+        {
+            name: "list_abilities",
+            description: "List locally deployed abilities on a device (filters out non-installable MCP entries).",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    tenant_id: { type: "string", description: "Tenant ID (default AXON_TENANT)." },
+                    node_id: { type: "string", description: "Target device node ID." },
+                },
+                required: ["node_id"],
+            },
+        },
+        {
+            name: "forget_all",
+            description: "Remove ALL deployed abilities from a device. Destructive — requires confirm: true unless dry_run: true.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    tenant_id: { type: "string", description: "Tenant ID (default AXON_TENANT)." },
+                    node_id: { type: "string", description: "Target device node ID." },
+                    confirm: { type: "boolean", description: "Must be true to confirm this destructive operation. Can be omitted when dry_run is true." },
+                    dry_run: { type: "boolean", description: "When true, list abilities that would be removed without uninstalling." },
+                },
+                required: ["node_id"],
+            },
+        },
     ];
 }

package/src/receipt.js

@@ -1,8 +1,11 @@
-// sdk/node/src/receipt.ts — Lifecycle phase receipts for observability and evaluation.
+// EasyNet Axon for AgentNet
+// =========================
 //
-// Every phase transition in the Axon ability lifecycle emits a structured
-// PhaseReceipt. Mirrors the Rust reference: sdk/rust/src/receipt.rs
+// File: sdk/node/src/receipt.ts
+// Description: Lifecycle phase receipts for observability and evaluation.
 //
+// Author: Silan.Hu
+// Email: silan.hu@u.nus.edu
 // Copyright (c) 2026-2027 easynet. All rights reserved.
 /** In-progress receipt builder. */
 export class PhaseReceiptBuilder {