@easynet-run/node 0.27.14

package/src/presets/remote_control/kit.js

@@ -0,0 +1,72 @@
+import { ensureRemoteControlNativeLibEnv, ensureNativeLibEnv, loadConfigFromEnv, loadRemoteControlConfigFromEnv, } from "./config.js";
+import { resolveTenant } from "./descriptor.js";
+import { handleCallRemoteTool, handleDeployAbility, handleDeployAbilityPackage, handleDiscoverNodes, handleDisconnectDevice, handleExecuteCommand, handleListRemoteTools, handlePackageAbility, handleUninstallAbility, } from "./handlers.js";
+import { remoteControlToolSpecs } from "./specs.js";
+import { buildOrchestrator } from "./orchestrator.js";
+export class RemoteControlCaseKit {
+    config;
+    orchestratorFactory;
+    constructor(config, orchestratorFactory = buildOrchestrator) {
+        this.config = config;
+        this.orchestratorFactory = orchestratorFactory;
+    }
+    static loadConfigFromEnv() {
+        return loadConfigFromEnv();
+    }
+    static loadRemoteControlConfigFromEnv() {
+        return loadRemoteControlConfigFromEnv();
+    }
+    static ensureNativeLibEnv() {
+        ensureNativeLibEnv();
+    }
+    static ensureRemoteControlNativeLibEnv() {
+        ensureRemoteControlNativeLibEnv();
+    }
+    toolSpecs() {
+        return remoteControlToolSpecs();
+    }
+    handleToolCall(name, args) {
+        const tenant = resolveTenant(args.tenant_id, this.config.tenant);
+        return this.withOrchestrator(tenant, (orchestrator) => this.dispatch(name, args, orchestrator, tenant));
+    }
+    dispatch(name, args, orchestrator, tenant) {
+        switch (name) {
+            case "discover_nodes":
+                return this.toolResultWithPayload(handleDiscoverNodes(orchestrator, tenant));
+            case "list_remote_tools":
+                return this.toolResultWithPayload(handleListRemoteTools(orchestrator, tenant, args));
+            case "call_remote_tool":
+                return this.toolResultWithPayload(handleCallRemoteTool(orchestrator, tenant, args));
+            case "disconnect_device":
+                return this.toolResultWithPayload(handleDisconnectDevice(orchestrator, tenant, args));
+            case "uninstall_ability":
+                return this.toolResultWithPayload(handleUninstallAbility(orchestrator, tenant, args));
+            case "package_ability":
+                return this.toolResultWithPayload(handlePackageAbility(tenant, args, this.config.signatureBase64));
+            case "deploy_ability_package":
+                return this.toolResultWithPayload(handleDeployAbilityPackage(orchestrator, tenant, args, this.config.signatureBase64));
+            case "deploy_ability":
+                return this.toolResultWithPayload(handleDeployAbility(orchestrator, tenant, args, this.config.signatureBase64));
+            case "execute_command":
+                return this.toolResultWithPayload(handleExecuteCommand(orchestrator, tenant, args, this.config.signatureBase64));
+            default:
+                return this.toolResult(true, { ok: false, tenant_id: tenant, error: `unknown tool: ${name}` });
+        }
+    }
+    withOrchestrator(tenant, invoke) {
+        const orchestrator = this.orchestratorFactory(this.config, tenant);
+        try {
+            return invoke(orchestrator);
+        }
+        finally {
+            orchestrator.close();
+        }
+    }
+    toolResult(isError, payload) {
+        return { payload, isError };
+    }
+    toolResultWithPayload(payload) {
+        const ok = payload.ok !== false;
+        return this.toolResult(!ok, payload);
+    }
+}

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

@@ -0,0 +1,87 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+
+import { RemoteControlCaseKit } from "./kit.js";
+import { remoteControlToolSpecs } from "./specs.js";
+
+function makeOrchestrator() {
+  return {
+    listNodes: () => [],
+    listMcpTools: () => [],
+    callMcpTool: () => ({ ok: true, state: 5, is_error: false }),
+    disconnectDevice: (nodeId, reason) => ({ node_id: nodeId, reason }),
+    uninstallAbility: (nodeId, installId, reason) => ({
+      node_id: nodeId,
+      install_id: installId,
+      reason,
+    }),
+    deployAbilityPackage: () => ({ install_id: "install-1", tool_name: "tool-1" }),
+    cleanupInstalls: () => ({ attempted: 0, succeeded: 0, failed: 0, results: [], ok: true }),
+    close: () => {},
+  };
+}
+
+describe("RemoteControlCaseKit", () => {
+  it("publishes lifecycle parity tools in the spec list", () => {
+    const names = remoteControlToolSpecs().map((spec) => String(spec.name));
+    assert.ok(names.includes("disconnect_device"));
+    assert.ok(names.includes("uninstall_ability"));
+  });
+
+  it("dispatches disconnect_device", () => {
+    const kit = new RemoteControlCaseKit(
+      {
+        endpoint: "http://127.0.0.1:50051",
+        tenant: "tenant-a",
+        connectTimeoutMs: 5000,
+        signatureBase64: "sig",
+      },
+      () => makeOrchestrator(),
+    );
+
+    const result = kit.handleToolCall("disconnect_device", { node_id: "node-a" });
+
+    assert.equal(result.isError, false);
+    assert.deepEqual(result.payload, {
+      ok: true,
+      tenant_id: "tenant-a",
+      node_id: "node-a",
+      status: "disconnected",
+      response: {
+        node_id: "node-a",
+        reason: "disconnect_device: requested by agent",
+      },
+    });
+  });
+
+  it("dispatches uninstall_ability", () => {
+    const kit = new RemoteControlCaseKit(
+      {
+        endpoint: "http://127.0.0.1:50051",
+        tenant: "tenant-a",
+        connectTimeoutMs: 5000,
+        signatureBase64: "sig",
+      },
+      () => makeOrchestrator(),
+    );
+
+    const result = kit.handleToolCall("uninstall_ability", {
+      node_id: "node-a",
+      install_id: "install-9",
+    });
+
+    assert.equal(result.isError, false);
+    assert.deepEqual(result.payload, {
+      ok: true,
+      tenant_id: "tenant-a",
+      node_id: "node-a",
+      install_id: "install-9",
+      status: "uninstalled",
+      response: {
+        node_id: "node-a",
+        install_id: "install-9",
+        reason: "uninstall_ability: requested by agent",
+      },
+    });
+  });
+});

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

@@ -0,0 +1,28 @@
+import type { JsonRecord, AbilityPackageDescriptor } from "./descriptor.js";
+export type { JsonRecord };
+export type OrchestratorFactory = (config: {
+    endpoint: string;
+    tenant: string;
+    connectTimeoutMs: number;
+    signatureBase64: string;
+}, tenant: string) => RemoteOrchestrator;
+export interface RemoteOrchestrator {
+    listNodes(ownerId?: string): JsonRecord[];
+    listMcpTools(namePattern?: string, tags?: string[], nodeId?: string): JsonRecord[];
+    callMcpTool(toolName: string, targetNodeId: string, argumentsJson: JsonRecord): JsonRecord;
+    disconnectDevice(nodeId: string, reason: string): JsonRecord;
+    uninstallAbility(nodeId: string, installId: string, reason: string): JsonRecord;
+    deployAbilityPackage(descriptor: AbilityPackageDescriptor, nodeId: string, cleanupOnActivateFailure: boolean): JsonRecord;
+    cleanupInstalls(installs: Array<{
+        mode: string;
+        nodeId: string;
+        installId: string;
+    }>): JsonRecord;
+    close(): void;
+}
+export declare function buildOrchestrator(config: {
+    endpoint: string;
+    tenant: string;
+    connectTimeoutMs: number;
+    signatureBase64: string;
+}, tenant: string): RemoteOrchestrator;

package/src/presets/remote_control/orchestrator.js

@@ -0,0 +1,118 @@
+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);
+}
+class OrchestratorAdapter {
+    config;
+    bridge;
+    tenant;
+    constructor(config, tenant) {
+        this.config = config;
+        this.tenant = tenant;
+        this.bridge = new DendriteBridge({
+            endpoint: config.endpoint,
+            connectTimeoutMs: config.connectTimeoutMs,
+        });
+    }
+    listNodes(ownerId = "") {
+        return this.bridge.listNodes(this.tenant, { ownerId });
+    }
+    listMcpTools(namePattern = "", tags = [], nodeId = "") {
+        const options = { namePattern, tags, nodeId };
+        return this.bridge.listMcpTools(this.tenant, options);
+    }
+    callMcpTool(toolName, targetNodeId, argumentsJson = {}) {
+        const options = { targetNodeId, argumentsJson };
+        return this.bridge.callMcpTool(this.tenant, toolName, options);
+    }
+    disconnectDevice(nodeId, reason) {
+        return this.bridge.deregisterNode(this.tenant, nodeId, reason);
+    }
+    uninstallAbility(nodeId, installId, reason) {
+        return this.bridge.uninstallCapability(this.tenant, nodeId, installId, {
+            deactivateFirst: true,
+            deactivateReason: reason,
+        });
+    }
+    deployAbilityPackage(descriptor, nodeId, cleanupOnActivateFailure) {
+        const publish = this.bridge.publishCapability(this.tenant, descriptor.packageId, descriptor.capabilityName, {
+            version: descriptor.version,
+            digest: descriptor.digest,
+            signatureBase64: descriptor.signatureBase64,
+            tags: descriptor.tags,
+            metadata: descriptor.metadata,
+            packageBytesBase64: descriptor.packageBytesBase64,
+        });
+        const packageRef = publish.package_ref ?? {};
+        const digest = String(packageRef.digest || descriptor.digest);
+        const install = this.bridge.installCapability(this.tenant, nodeId, descriptor.packageId, {
+            version: descriptor.version,
+            digest,
+            requireConsent: false,
+            allowTransferredCode: true,
+            executionMode: DEFAULT_EXECUTION_MODE,
+            installTimeoutSeconds: DEFAULT_INSTALL_TIMEOUT_SECONDS,
+        });
+        const installId = String(install.install_id || "").trim();
+        if (!installId) {
+            throw new Error("deploy_ability_package missing install_id after install");
+        }
+        try {
+            const activate = this.bridge.activateCapability(this.tenant, nodeId, installId);
+            return {
+                ok: true,
+                package_id: descriptor.packageId,
+                tool_name: descriptor.toolName,
+                capability_name: descriptor.capabilityName,
+                publish,
+                install,
+                activate,
+                install_id: installId,
+            };
+        }
+        catch (error) {
+            const cleanup = cleanupOnActivateFailure ? this.cleanupInstalls([{ mode: "publish_install_activate", nodeId, installId }]) : { attempted: false, ok: false, reason: "cleanup disabled" };
+            throw new Error(JSON.stringify({
+                message: "activate failed",
+                error: String(error),
+                install_id: installId,
+                cleanup,
+            }));
+        }
+    }
+    cleanupInstalls(installs) {
+        const results = [];
+        let attempted = 0;
+        let succeeded = 0;
+        let failed = 0;
+        const ordered = [...installs].reverse();
+        for (const install of ordered) {
+            attempted += 1;
+            if (!install.nodeId || !install.installId) {
+                failed += 1;
+                results.push({
+                    mode: install.mode,
+                    node_id: install.nodeId,
+                    install_id: install.installId,
+                    ok: false,
+                    error: "missing node_id or install_id",
+                });
+                continue;
+            }
+            try {
+                const response = this.bridge.uninstallCapability(this.tenant, install.nodeId, install.installId, { deactivateFirst: true, deactivateReason: "sdk cleanup" });
+                succeeded += 1;
+                results.push({ mode: install.mode, node_id: install.nodeId, install_id: install.installId, ok: true, response });
+            }
+            catch (error) {
+                failed += 1;
+                results.push({ mode: install.mode, node_id: install.nodeId, install_id: install.installId, ok: false, error: String(error) });
+            }
+        }
+        return { attempted, succeeded, failed, results, ok: failed === 0 };
+    }
+    close() {
+        this.bridge.close();
+    }
+}

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

@@ -0,0 +1,2 @@
+import type { JsonRecord } from "./descriptor.js";
+export declare function remoteControlToolSpecs(): JsonRecord[];

package/src/presets/remote_control/specs.js

@@ -0,0 +1,152 @@
+export function remoteControlToolSpecs() {
+    return [
+        // -----------------------------------------------------------------
+        // GENERIC TOOLS -- core remote-control primitives
+        // -----------------------------------------------------------------
+        {
+            name: "discover_nodes",
+            description: "Discover online nodes registered with Axon Runtime.",
+            inputSchema: {
+                type: "object",
+                properties: { tenant_id: { type: "string", description: "Tenant ID (default AXON_TENANT)" } },
+            },
+        },
+        {
+            name: "list_remote_tools",
+            description: "List MCP tools visible for a tenant.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    tenant_id: { type: "string" },
+                    node_id: { type: "string" },
+                    name_pattern: { type: "string" },
+                },
+            },
+        },
+        {
+            name: "call_remote_tool",
+            description: "Call an MCP tool on a selected node.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    tenant_id: { type: "string" },
+                    tool_name: { type: "string" },
+                    node_id: { type: "string" },
+                    arguments: { type: "object" },
+                },
+                required: ["tool_name", "node_id"],
+            },
+        },
+        {
+            name: "disconnect_device",
+            description: "Deregister a remote device from the Axon Runtime, closing its connection.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    tenant_id: { type: "string" },
+                    node_id: { type: "string" },
+                    reason: { type: "string" },
+                },
+                required: ["node_id"],
+            },
+        },
+        {
+            name: "uninstall_ability",
+            description: "Uninstall a deployed ability from a device by deactivating and removing it.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    tenant_id: { type: "string" },
+                    node_id: { type: "string" },
+                    install_id: { type: "string" },
+                    reason: { type: "string" },
+                },
+                required: ["node_id", "install_id"],
+            },
+        },
+        // -----------------------------------------------------------------
+        // AI-AGENT PRESET TOOLS -- convenience wrappers for AI agents
+        // -----------------------------------------------------------------
+        {
+            name: "deploy_ability",
+            description: "Deploy a command-backed MCP ability.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    tenant_id: { type: "string" },
+                    node_id: { type: "string" },
+                    tool_name: { type: "string" },
+                    description: { type: "string" },
+                    command_template: { type: "string" },
+                },
+                required: ["node_id", "command_template"],
+            },
+        },
+        // -----------------------------------------------------------------
+        // GENERIC TOOLS (continued) -- ability packaging and deployment
+        // -----------------------------------------------------------------
+        {
+            name: "package_ability",
+            description: "Build a native ability package descriptor.",
+            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" },
+                },
+                required: ["ability_name", "command_template"],
+            },
+        },
+        {
+            name: "deploy_ability_package",
+            description: "Deploy a native ability package by publish/install/activate.",
+            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" },
+                },
+                required: ["node_id"],
+            },
+        },
+        // AI-AGENT PRESET: one-shot command execution
+        {
+            name: "execute_command",
+            description: "One-shot command execution via temporary MCP ability.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    tenant_id: { type: "string" },
+                    node_id: { type: "string" },
+                    command: { type: "string" },
+                    cleanup: { type: "boolean" },
+                },
+                required: ["node_id", "command"],
+            },
+        },
+    ];
+}

package/src/presets/remote_control_case.d.ts

@@ -0,0 +1,7 @@
+export { RemoteControlCaseKit, } from "./remote_control/kit.js";
+export type { RemoteControlRuntimeConfig } from "./remote_control/config.js";
+export type { RemoteOrchestratorFactory } from "./remote_control/kit.js";
+export type { OrchestratorFactory } from "./remote_control/orchestrator.js";
+export type { AbilityPackageDescriptor } from "./remote_control/descriptor.js";
+export { DEFAULT_SIGNATURE, DEFAULT_VERSION, DEFAULT_INSTALL_TIMEOUT_SECONDS, DEFAULT_EXECUTION_MODE, } from "./remote_control/config.js";
+export { loadRemoteControlConfigFromEnv, loadConfigFromEnv, ensureRemoteControlNativeLibEnv, ensureNativeLibEnv, } from "./remote_control/config.js";

package/src/presets/remote_control_case.js

@@ -0,0 +1,3 @@
+export { RemoteControlCaseKit, } from "./remote_control/kit.js";
+export { DEFAULT_SIGNATURE, DEFAULT_VERSION, DEFAULT_INSTALL_TIMEOUT_SECONDS, DEFAULT_EXECUTION_MODE, } from "./remote_control/config.js";
+export { loadRemoteControlConfigFromEnv, loadConfigFromEnv, ensureRemoteControlNativeLibEnv, ensureNativeLibEnv, } from "./remote_control/config.js";

package/src/receipt.d.ts

@@ -0,0 +1,46 @@
+import type { AxonError } from "./errors.js";
+/** A phase in the Axon ability lifecycle. */
+export type Phase = "publish" | "install" | "activate" | "invoke" | "deactivate" | "uninstall" | "deploy";
+/** Outcome of a lifecycle phase transition. */
+export type PhaseStatus = "ok" | "error" | "skipped";
+/** Structured record of a single lifecycle phase transition. */
+export interface PhaseReceipt {
+    phase: Phase;
+    status: PhaseStatus;
+    started_ms: number;
+    ended_ms: number;
+    duration_ms: number;
+    tenant_id: string;
+    node_id: string;
+    ability_id: string;
+    install_id?: string;
+    error?: string;
+    error_code?: string;
+    metadata?: Record<string, unknown>;
+}
+/** In-progress receipt builder. */
+export declare class PhaseReceiptBuilder {
+    private readonly phase;
+    private readonly startedMs;
+    private readonly tenantId;
+    private readonly nodeId;
+    private readonly abilityId;
+    constructor(phase: Phase, tenantId: string, nodeId: string, abilityId: string);
+    finishOk(installId?: string, metadata?: Record<string, unknown>): PhaseReceipt;
+    finishErr(error: AxonError | Error): PhaseReceipt;
+    finishSkipped(reason: string): PhaseReceipt;
+}
+/** Begin timing a lifecycle phase. */
+export declare function beginPhase(phase: Phase, tenantId: string, nodeId: string, abilityId: string): PhaseReceiptBuilder;
+/** Create a receipt for a skipped phase. */
+export declare function skippedReceipt(phase: Phase, tenantId: string, nodeId: string, abilityId: string): PhaseReceipt;
+/** Aggregated trace of a full deploy operation (publish → install → activate). */
+export interface DeployTrace {
+    receipts: PhaseReceipt[];
+    total_ms: number;
+    ok: boolean;
+}
+/** Build a DeployTrace from a sequence of receipts. */
+export declare function buildDeployTrace(receipts: PhaseReceipt[]): DeployTrace;
+/** Get a receipt for a specific phase from a trace. */
+export declare function phaseFromTrace(trace: DeployTrace, phase: Phase): PhaseReceipt | undefined;

package/src/receipt.js

@@ -0,0 +1,98 @@
+// sdk/node/src/receipt.ts — Lifecycle phase receipts for observability and evaluation.
+//
+// Every phase transition in the Axon ability lifecycle emits a structured
+// PhaseReceipt. Mirrors the Rust reference: sdk/rust/src/receipt.rs
+//
+// Copyright (c) 2026-2027 easynet. All rights reserved.
+/** In-progress receipt builder. */
+export class PhaseReceiptBuilder {
+    phase;
+    startedMs;
+    tenantId;
+    nodeId;
+    abilityId;
+    constructor(phase, tenantId, nodeId, abilityId) {
+        this.phase = phase;
+        this.startedMs = Date.now();
+        this.tenantId = tenantId;
+        this.nodeId = nodeId;
+        this.abilityId = abilityId;
+    }
+    finishOk(installId, metadata) {
+        const ended = Date.now();
+        return {
+            phase: this.phase,
+            status: "ok",
+            started_ms: this.startedMs,
+            ended_ms: ended,
+            duration_ms: ended - this.startedMs,
+            tenant_id: this.tenantId,
+            node_id: this.nodeId,
+            ability_id: this.abilityId,
+            install_id: installId,
+            metadata,
+        };
+    }
+    finishErr(error) {
+        const ended = Date.now();
+        const code = error && typeof error === "object" && "code" in error && typeof error.code === "string"
+            ? error.code
+            : "UNKNOWN";
+        return {
+            phase: this.phase,
+            status: "error",
+            started_ms: this.startedMs,
+            ended_ms: ended,
+            duration_ms: ended - this.startedMs,
+            tenant_id: this.tenantId,
+            node_id: this.nodeId,
+            ability_id: this.abilityId,
+            error: error.message,
+            error_code: code,
+        };
+    }
+    finishSkipped(reason) {
+        const ended = Date.now();
+        return {
+            phase: this.phase,
+            status: "skipped",
+            started_ms: this.startedMs,
+            ended_ms: ended,
+            duration_ms: ended - this.startedMs,
+            tenant_id: this.tenantId,
+            node_id: this.nodeId,
+            ability_id: this.abilityId,
+            metadata: { skip_reason: reason },
+        };
+    }
+}
+/** Begin timing a lifecycle phase. */
+export function beginPhase(phase, tenantId, nodeId, abilityId) {
+    return new PhaseReceiptBuilder(phase, tenantId, nodeId, abilityId);
+}
+/** Create a receipt for a skipped phase. */
+export function skippedReceipt(phase, tenantId, nodeId, abilityId) {
+    const now = Date.now();
+    return {
+        phase,
+        status: "skipped",
+        started_ms: now,
+        ended_ms: now,
+        duration_ms: 0,
+        tenant_id: tenantId,
+        node_id: nodeId,
+        ability_id: abilityId,
+    };
+}
+/** Build a DeployTrace from a sequence of receipts. */
+export function buildDeployTrace(receipts) {
+    const ok = !receipts.some((r) => r.status === "error");
+    const total = receipts.length > 0
+        ? receipts[receipts.length - 1].ended_ms - receipts[0].started_ms
+        : 0;
+    return { receipts, total_ms: total, ok };
+}
+/** Get a receipt for a specific phase from a trace. */
+export function phaseFromTrace(trace, phase) {
+    return trace.receipts.find((r) => r.phase === phase);
+}