@easynet-run/node 0.36.9 → 0.39.29

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 [
         // -----------------------------------------------------------------
@@ -95,6 +129,7 @@ export function remoteControlToolSpecs() {
                     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"],
             },
@@ -122,6 +157,7 @@ export function remoteControlToolSpecs() {
                     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"],
             },
@@ -148,6 +184,7 @@ export function remoteControlToolSpecs() {
                     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"],
             },
@@ -167,5 +204,105 @@ export function remoteControlToolSpecs() {
                 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"],
+            },
+        },
     ];
 }