@easynet-run/node 0.36.9 → 0.39.29

package/src/presets/remote_control/kit.test.js

@@ -1,7 +1,33 @@
+// EasyNet Axon for AgentNet
+// =========================
+//
+// File: sdk/node/src/presets/remote_control/kit.test.js
+// Description: Node remote-control preset regression tests for tool dispatch, streaming cleanup, and lifecycle behavior.
+//
+// Protocol Responsibility:
+// - Exercises public runtime behavior for the corresponding service surface under success and failure scenarios.
+// - Guards regressions in tenant isolation, terminal states, and typed error shaping.
+//
+// Implementation Approach:
+// - Builds in-memory runtimes and drives tonic service methods directly for deterministic assertions.
+// - Uses focused fixtures instead of full external environments so protocol invariants stay easy to localize.
+//
+// Usage Contract:
+// - Add new assertions here before changing runtime behavior for the covered service area.
+// - Prefer explicit value checks over timing-sensitive or order-fragile expectations.
+//
+// Architectural Position:
+// - Runtime verification boundary protecting public contract stability.
+//
+// Author: Silan.Hu
+// Email: silan.hu@u.nus.edu
+// Copyright (c) 2026-2027 easynet. All rights reserved.
+
 import { describe, it } from "node:test";
 import assert from "node:assert/strict";
 
 import { RemoteControlCaseKit } from "./kit.js";
+import { buildDescriptor, sanitizeId } from "./descriptor.js";
 import { remoteControlToolSpecs } from "./specs.js";
 import { consumeStream } from "../../mcp/server.js";
 import { DEFAULT_MCP_TOOL_STREAM_TIMEOUT_MS } from "./config.js";
@@ -18,6 +44,7 @@ function makeOrchestrator() {
       },
     }),
     disconnectDevice: (nodeId, reason) => ({ node_id: nodeId, reason }),
+    drainNode: (nodeId, reason) => ({ node_id: nodeId, status: "drained", reason }),
     uninstallAbility: (nodeId, installId, reason) => ({
       node_id: nodeId,
       install_id: installId,
@@ -35,6 +62,8 @@ describe("RemoteControlCaseKit", () => {
     assert.ok(names.includes("disconnect_device"));
     assert.ok(names.includes("uninstall_ability"));
     assert.ok(names.includes("call_remote_tool_stream"));
+    assert.ok(names.includes("build_ability_descriptor"));
+    assert.ok(names.includes("redeploy_ability"));
   });
 
   it("dispatches disconnect_device", () => {
@@ -94,6 +123,93 @@ describe("RemoteControlCaseKit", () => {
     });
   });
 
+  it("rejects forget_all without confirm when dry_run is false", () => {
+    const kit = new RemoteControlCaseKit(
+      {
+        endpoint: "http://127.0.0.1:50051",
+        tenant: "tenant-a",
+        connectTimeoutMs: 5000,
+        signatureBase64: "sig",
+      },
+      () => makeOrchestrator(),
+    );
+
+    const result = kit.handleToolCall("forget_all", { node_id: "node-a" });
+
+    assert.equal(result.isError, true);
+    assert.equal(result.payload.error, "forget_all requires confirm: true (destructive operation)");
+  });
+
+  it("rejects build_ability_descriptor when name is empty", () => {
+    const kit = new RemoteControlCaseKit(
+      {
+        endpoint: "http://127.0.0.1:50051",
+        tenant: "tenant-a",
+        connectTimeoutMs: 5000,
+        signatureBase64: "sig",
+      },
+      () => makeOrchestrator(),
+    );
+
+    const result = kit.handleToolCall("build_ability_descriptor", {
+      command_template: "echo hi",
+    });
+
+    assert.equal(result.isError, true);
+    assert.equal(result.payload.error, "name is required");
+  });
+
+  it("rejects redeploy_ability when tool_name is missing", () => {
+    const kit = new RemoteControlCaseKit(
+      {
+        endpoint: "http://127.0.0.1:50051",
+        tenant: "tenant-a",
+        connectTimeoutMs: 5000,
+        signatureBase64: "sig",
+      },
+      () => makeOrchestrator(),
+    );
+
+    const result = kit.handleToolCall("redeploy_ability", {
+      node_id: "node-a",
+      command_template: "echo hi",
+    });
+
+    assert.equal(result.isError, true);
+    assert.equal(result.payload.error, "tool_name is required");
+  });
+
+  it("filters list_abilities to entries with install_id", () => {
+    const kit = new RemoteControlCaseKit(
+      {
+        endpoint: "http://127.0.0.1:50051",
+        tenant: "tenant-a",
+        connectTimeoutMs: 5000,
+        signatureBase64: "sig",
+      },
+      () => ({
+        ...makeOrchestrator(),
+        listMcpTools: () => [
+          { tool_name: "keep-me", description: "ok", capability_name: "cap.keep", install_id: "install-1" },
+          { tool_name: "skip-me", description: "synthetic", capability_name: "cap.skip", install_id: "" },
+        ],
+      }),
+    );
+
+    const result = kit.handleToolCall("list_abilities", { node_id: "node-a" });
+
+    assert.equal(result.isError, false);
+    assert.equal(result.payload.count, 1);
+    assert.deepEqual(result.payload.abilities, [
+      {
+        tool_name: "keep-me",
+        description: "ok",
+        capability_name: "cap.keep",
+        install_id: "install-1",
+      },
+    ]);
+  });
+
   it("closes the orchestrator when a streaming handle is closed", () => {
     let streamClosed = 0;
     let orchestratorClosed = 0;
@@ -502,6 +618,435 @@ describe("RemoteControlCaseKit", () => {
     assert.deepEqual(payload.chunks, ["stream-chunk-1", "stream-chunk-2"]);
   });
 
+  // -----------------------------------------------------------------
+  // drain_device tests
+  // -----------------------------------------------------------------
+  it("dispatches drain_device happy path", () => {
+    const kit = new RemoteControlCaseKit(
+      {
+        endpoint: "http://127.0.0.1:50051",
+        tenant: "tenant-a",
+        connectTimeoutMs: 5000,
+        signatureBase64: "sig",
+      },
+      () => makeOrchestrator(),
+    );
+
+    const result = kit.handleToolCall("drain_device", {
+      node_id: "node-a",
+      reason: "maintenance window",
+    });
+
+    assert.equal(result.isError, false);
+    assert.equal(result.payload.ok, true);
+    assert.equal(result.payload.tenant_id, "tenant-a");
+    assert.equal(result.payload.node_id, "node-a");
+    assert.equal(result.payload.status, "draining");
+    assert.equal(result.payload.response.node_id, "node-a");
+    assert.equal(result.payload.response.reason, "maintenance window");
+  });
+
+  it("rejects drain_device with missing node_id", () => {
+    const kit = new RemoteControlCaseKit(
+      {
+        endpoint: "http://127.0.0.1:50051",
+        tenant: "tenant-a",
+        connectTimeoutMs: 5000,
+        signatureBase64: "sig",
+      },
+      () => makeOrchestrator(),
+    );
+
+    const result = kit.handleToolCall("drain_device", { node_id: "" });
+
+    assert.equal(result.isError, true);
+    assert.equal(result.payload.error, "node_id is required");
+  });
+
+  // -----------------------------------------------------------------
+  // build_ability_descriptor tests
+  // -----------------------------------------------------------------
+  it("dispatches build_ability_descriptor happy path", () => {
+    const kit = new RemoteControlCaseKit(
+      {
+        endpoint: "http://127.0.0.1:50051",
+        tenant: "tenant-a",
+        connectTimeoutMs: 5000,
+        signatureBase64: "sig",
+      },
+      () => makeOrchestrator(),
+    );
+
+    const result = kit.handleToolCall("build_ability_descriptor", {
+      name: "screenshot",
+      command_template: "screencapture -x /tmp/shot.png",
+      description: "Capture a screenshot",
+    });
+
+    assert.equal(result.isError, false);
+    assert.equal(result.payload.ok, true);
+    const descriptor = result.payload.descriptor;
+    assert.ok(descriptor);
+    assert.equal(descriptor.name, "screenshot");
+    assert.match(descriptor.toolName, /^ability_screenshot$/);
+    assert.equal(descriptor.description, "Capture a screenshot");
+    assert.equal(descriptor.commandTemplate, "screencapture -x /tmp/shot.png");
+  });
+
+  it("dispatches build_ability_descriptor with agent extensions", () => {
+    const kit = new RemoteControlCaseKit(
+      {
+        endpoint: "http://127.0.0.1:50051",
+        tenant: "tenant-a",
+        connectTimeoutMs: 5000,
+        signatureBase64: "sig",
+      },
+      () => makeOrchestrator(),
+    );
+
+    const result = kit.handleToolCall("build_ability_descriptor", {
+      name: "gpu-info",
+      command_template: "nvidia-smi --query-gpu=name --format=csv",
+      instructions: "Use this to query GPU status on the device.",
+      input_examples: [{ query: "temperature" }],
+      prerequisites: ["GPU driver installed"],
+      context_bindings: { "env.CUDA_HOME": "/usr/local/cuda" },
+      category: "system",
+    });
+
+    assert.equal(result.isError, false);
+    const d = result.payload.descriptor;
+    assert.equal(d.instructions, "Use this to query GPU status on the device.");
+    assert.deepEqual(d.inputExamples, [{ query: "temperature" }]);
+    assert.deepEqual(d.prerequisites, ["GPU driver installed"]);
+    assert.deepEqual(d.contextBindings, { "env.CUDA_HOME": "/usr/local/cuda" });
+    assert.equal(d.category, "system");
+  });
+
+  it("buildDescriptor stores prerequisites as a JSON array", () => {
+    const descriptor = buildDescriptor({
+      ability_name: "gpu-info",
+      command_template: "nvidia-smi --query-gpu=name --format=csv",
+      prerequisites: ["GPU, driver installed", "session_start"],
+    }, "sig");
+
+    assert.equal(
+      descriptor.metadata["mcp.prerequisites"],
+      JSON.stringify(["GPU, driver installed", "session_start"]),
+    );
+  });
+
+  it("sanitizeId rejects names that normalize to empty", () => {
+    assert.throws(() => sanitizeId("数据分析"), /identifier contains no valid characters/);
+  });
+
+  // -----------------------------------------------------------------
+  // export_ability_skill tests
+  // -----------------------------------------------------------------
+  it("dispatches export_ability_skill and generates SKILL.md", () => {
+    const kit = new RemoteControlCaseKit(
+      {
+        endpoint: "http://127.0.0.1:50051",
+        tenant: "tenant-a",
+        connectTimeoutMs: 5000,
+        signatureBase64: "sig",
+      },
+      () => makeOrchestrator(),
+    );
+
+    const result = kit.handleToolCall("export_ability_skill", {
+      name: "disk-usage",
+      command_template: "df -h",
+      target: "claude",
+    });
+
+    assert.equal(result.isError, false);
+    assert.equal(result.payload.ok, true);
+    assert.ok(typeof result.payload.ability_md === "string");
+    assert.ok(typeof result.payload.invoke_script === "string");
+    assert.ok(result.payload.ability_md.length > 0);
+    assert.ok(result.payload.invoke_script.length > 0);
+    // Claude target should include allowed-tools
+    assert.ok(result.payload.ability_md.includes("allowed-tools"));
+    // Invoke script should be a bash script
+    assert.ok(result.payload.invoke_script.includes("#!/usr/bin/env bash"));
+  });
+
+  it("rejects export_ability_skill with shell-unsafe endpoint", () => {
+    const kit = new RemoteControlCaseKit(
+      {
+        endpoint: "http://127.0.0.1:50051",
+        tenant: "tenant-a",
+        connectTimeoutMs: 5000,
+        signatureBase64: "sig",
+      },
+      () => makeOrchestrator(),
+    );
+
+    const result = kit.handleToolCall("export_ability_skill", {
+      name: "probe",
+      command_template: "echo hello",
+      axon_endpoint: "http://evil.com`rm -rf /`",
+    });
+
+    assert.equal(result.isError, true);
+    assert.ok(result.payload.error);
+    assert.match(result.payload.error, /disallowed shell characters/);
+  });
+
+  it("rejects export_ability_skill with carriage-return endpoint", () => {
+    const kit = new RemoteControlCaseKit(
+      {
+        endpoint: "http://127.0.0.1:50051",
+        tenant: "tenant-a",
+        connectTimeoutMs: 5000,
+        signatureBase64: "sig",
+      },
+      () => makeOrchestrator(),
+    );
+
+    const result = kit.handleToolCall("export_ability_skill", {
+      name: "probe",
+      command_template: "echo hello",
+      axon_endpoint: "http://evil.com/\rprobe",
+    });
+
+    assert.equal(result.isError, true);
+    assert.ok(result.payload.error);
+    assert.match(result.payload.error, /disallowed shell characters/);
+  });
+
+  // -----------------------------------------------------------------
+  // forget_all tests
+  // -----------------------------------------------------------------
+  it("dispatches forget_all dry_run and returns would-remove list", () => {
+    const kit = new RemoteControlCaseKit(
+      {
+        endpoint: "http://127.0.0.1:50051",
+        tenant: "tenant-a",
+        connectTimeoutMs: 5000,
+        signatureBase64: "sig",
+      },
+      () => ({
+        ...makeOrchestrator(),
+        listMcpTools: () => [
+          { tool_name: "tool-with-id", description: "ok", capability_name: "cap.a", install_id: "inst-1" },
+          { tool_name: "tool-without-id", description: "synthetic", capability_name: "cap.b", install_id: "" },
+        ],
+      }),
+    );
+
+    const result = kit.handleToolCall("forget_all", {
+      node_id: "node-a",
+      dry_run: true,
+    });
+
+    assert.equal(result.isError, false);
+    assert.equal(result.payload.ok, true);
+    assert.equal(result.payload.dry_run, true);
+    assert.deepEqual(result.payload.removed, ["tool-with-id"]);
+    assert.equal(result.payload.removed_count, 1);
+    assert.equal(result.payload.failed_count, 1);
+    assert.equal(result.payload.failed[0].tool_name, "tool-without-id");
+  });
+
+  it("dispatches forget_all with confirm and removes abilities", () => {
+    let uninstallCalls = [];
+    const kit = new RemoteControlCaseKit(
+      {
+        endpoint: "http://127.0.0.1:50051",
+        tenant: "tenant-a",
+        connectTimeoutMs: 5000,
+        signatureBase64: "sig",
+      },
+      () => ({
+        ...makeOrchestrator(),
+        listMcpTools: () => [
+          { tool_name: "my-tool", description: "test", capability_name: "cap.x", install_id: "inst-7" },
+        ],
+        uninstallAbility: (nodeId, installId, reason) => {
+          uninstallCalls.push({ nodeId, installId, reason });
+          return { node_id: nodeId, install_id: installId, reason };
+        },
+      }),
+    );
+
+    const result = kit.handleToolCall("forget_all", {
+      node_id: "node-a",
+      confirm: true,
+    });
+
+    assert.equal(result.isError, false);
+    assert.equal(result.payload.ok, true);
+    assert.equal(result.payload.dry_run, false);
+    assert.deepEqual(result.payload.removed, ["my-tool"]);
+    assert.equal(result.payload.removed_count, 1);
+    assert.equal(result.payload.failed_count, 0);
+    assert.equal(uninstallCalls.length, 1);
+    assert.equal(uninstallCalls[0].installId, "inst-7");
+  });
+
+  // -----------------------------------------------------------------
+  // redeploy_ability tests
+  // -----------------------------------------------------------------
+  it("dispatches redeploy_ability happy path", () => {
+    const kit = new RemoteControlCaseKit(
+      {
+        endpoint: "http://127.0.0.1:50051",
+        tenant: "tenant-a",
+        connectTimeoutMs: 5000,
+        signatureBase64: "sig",
+      },
+      () => ({
+        ...makeOrchestrator(),
+        deployAbilityPackage: () => ({ install_id: "inst-99", tool_name: "my-tool" }),
+      }),
+    );
+
+    const result = kit.handleToolCall("redeploy_ability", {
+      node_id: "node-a",
+      tool_name: "my-tool",
+      command_template: "echo updated",
+    });
+
+    assert.equal(result.isError, false);
+    assert.equal(result.payload.ok, true);
+    assert.equal(result.payload.status, "redeployed");
+    assert.equal(result.payload.node_id, "node-a");
+    assert.equal(result.payload.tool_name, "my-tool");
+    assert.equal(result.payload.install_id, "inst-99");
+  });
+
+  // -----------------------------------------------------------------
+  // export_ability_skill verifies SKILL.md structure
+  // -----------------------------------------------------------------
+  it("export_ability_skill verifies SKILL.md structure", () => {
+    const kit = new RemoteControlCaseKit(
+      {
+        endpoint: "http://127.0.0.1:50051",
+        tenant: "tenant-a",
+        connectTimeoutMs: 5000,
+        signatureBase64: "sig",
+      },
+      () => makeOrchestrator(),
+    );
+
+    const result = kit.handleToolCall("export_ability_skill", {
+      name: "my-skill",
+      command_template: "echo hello",
+      target: "claude",
+    });
+
+    assert.equal(result.isError, false);
+    assert.ok(result.payload.ability_md.includes("---\nname:"), "ability_md should contain frontmatter start");
+    assert.ok(result.payload.ability_md.includes("## Parameters"), "ability_md should contain Parameters section");
+    assert.ok(result.payload.ability_md.includes("| Name |"), "ability_md should contain parameter table header");
+    assert.ok(result.payload.invoke_script.includes("curl -sS -X POST"), "invoke_script should contain curl POST");
+  });
+
+  // -----------------------------------------------------------------
+  // build_ability_descriptor with Unicode name
+  // -----------------------------------------------------------------
+  it("build_ability_descriptor with Unicode name", () => {
+    const kit = new RemoteControlCaseKit(
+      {
+        endpoint: "http://127.0.0.1:50051",
+        tenant: "tenant-a",
+        connectTimeoutMs: 5000,
+        signatureBase64: "sig",
+      },
+      () => makeOrchestrator(),
+    );
+
+    const result = kit.handleToolCall("build_ability_descriptor", {
+      name: "数据分析",
+      command_template: "python3 analyze.py",
+    });
+
+    // Unicode-only names are rejected by sanitizeId (ASCII identifiers only).
+    assert.equal(result.isError, true);
+    assert.ok(result.payload.error);
+  });
+
+  // -----------------------------------------------------------------
+  // forget_all confirmed removes and reports failures
+  // -----------------------------------------------------------------
+  it("forget_all confirmed removes and reports failures", () => {
+    let uninstallCalls = [];
+    const kit = new RemoteControlCaseKit(
+      {
+        endpoint: "http://127.0.0.1:50051",
+        tenant: "tenant-a",
+        connectTimeoutMs: 5000,
+        signatureBase64: "sig",
+      },
+      () => ({
+        ...makeOrchestrator(),
+        listMcpTools: () => [
+          { tool_name: "tool-a", description: "ok", capability_name: "cap.a", install_id: "inst-1" },
+          { tool_name: "tool-b", description: "no id", capability_name: "cap.b", install_id: "" },
+          { tool_name: "tool-c", description: "whitespace id", capability_name: "cap.c", install_id: "   " },
+        ],
+        uninstallAbility: (nodeId, installId, reason) => {
+          uninstallCalls.push({ nodeId, installId, reason });
+          return { node_id: nodeId, install_id: installId, reason };
+        },
+      }),
+    );
+
+    const result = kit.handleToolCall("forget_all", {
+      node_id: "node-a",
+      confirm: true,
+    });
+
+    assert.equal(result.isError, false);
+    assert.equal(result.payload.ok, true);
+    assert.equal(result.payload.removed.length, 1);
+    assert.equal(result.payload.failed.length, 2);
+    assert.equal(uninstallCalls.length, 1);
+    assert.equal(uninstallCalls[0].installId, "inst-1");
+  });
+
+  // -----------------------------------------------------------------
+  // build_ability_descriptor rejects empty command_template
+  // -----------------------------------------------------------------
+  it("build_ability_descriptor rejects empty command_template", () => {
+    const kit = new RemoteControlCaseKit(
+      {
+        endpoint: "http://127.0.0.1:50051",
+        tenant: "tenant-a",
+        connectTimeoutMs: 5000,
+        signatureBase64: "sig",
+      },
+      () => makeOrchestrator(),
+    );
+
+    const result = kit.handleToolCall("build_ability_descriptor", {
+      name: "test",
+    });
+
+    assert.equal(result.isError, true);
+    assert.ok(result.payload.error);
+  });
+
+  // -----------------------------------------------------------------
+  // Spec validation tests
+  // -----------------------------------------------------------------
+  it("all tool specs have unique names", () => {
+    const specs = remoteControlToolSpecs();
+    const names = specs.map((s) => s.name);
+    const unique = new Set(names);
+    assert.equal(names.length, unique.size, `Duplicate spec names found: ${names.filter((n, i) => names.indexOf(n) !== i)}`);
+  });
+
+  it("all specs have required inputSchema fields", () => {
+    const specs = remoteControlToolSpecs();
+    for (const spec of specs) {
+      assert.ok(spec.inputSchema, `spec ${spec.name} is missing inputSchema`);
+      assert.equal(spec.inputSchema.type, "object", `spec ${spec.name} inputSchema.type should be "object"`);
+    }
+  });
+
   it("uses default timeout when timeout_ms is missing", () => {
     let capturedOptions = null;
     const kit = new RemoteControlCaseKit(

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

@@ -15,6 +15,7 @@ export interface RemoteOrchestrator {
     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,3 +1,27 @@
+// 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) {
@@ -34,6 +58,9 @@ class OrchestratorAdapter {
         };
         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);
     }