@easynet-run/node 0.27.14

package/src/ability_lifecycle.js

@@ -0,0 +1,525 @@
+// sdk/node/src/ability_lifecycle.ts — Ability lifecycle API: create, deploy, and export as Agent Skills.
+//
+// Copyright (c) 2026-2027 easynet. All rights reserved.
+import { spawn } from "node:child_process";
+import { webcrypto } from "node:crypto";
+import { createServer, createConnection } from "node:net";
+import { existsSync, mkdirSync, openSync } from "node:fs";
+import { hostname as localHostname } from "node:os";
+import { join, dirname } from "node:path";
+import { env } from "node:process";
+import { buildPythonSubprocessTemplate } from "./presets/remote_control/descriptor.js";
+import { AxonConfigError, AxonBridgeError, AxonInvocationError, AxonPartialSuccessError } from "./errors.js";
+import { DEFAULT_SIGNATURE } from "./presets/remote_control/config.js";
+import { beginPhase, buildDeployTrace } from "./receipt.js";
+/** Placeholder signature for ephemeral/temporary skill deployments.
+ *  Canonical constant lives in presets/remote_control/config.ts.
+ */
+const EPHEMERAL_SIGNATURE = DEFAULT_SIGNATURE;
+/** Default Axon runtime port. */
+const DEFAULT_AXON_PORT = 50051;
+/** Generate a random hex string for unique tool name suffixes. */
+function randomHex(bytes) {
+    const arr = new Uint8Array(bytes);
+    webcrypto.getRandomValues(arr);
+    return Array.from(arr, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function normalizeAbilityName(raw) {
+    const result = raw
+        .toLowerCase()
+        .replace(/[^a-z0-9_\-]/g, "-")
+        .replace(/-{2,}/g, "-")
+        .replace(/^-+|-+$/g, "");
+    return result || "ability";
+}
+function firstNonEmpty(...values) {
+    for (const value of values) {
+        const trimmed = value?.trim();
+        if (trimmed)
+            return trimmed;
+    }
+    return undefined;
+}
+// ---------------------------------------------------------------------------
+// Server lifecycle — start / connect / stop
+// ---------------------------------------------------------------------------
+const DEFAULT_LOG_DIR = join(env.HOME ?? env.USERPROFILE ?? "/tmp", ".easynet", "logs");
+function cliLog(msg) {
+    const ts = new Date().toLocaleTimeString("en-GB", { hour12: false });
+    process.stderr.write(`[axon ${ts}] ${msg}\n`);
+}
+function findRuntimeBinary() {
+    const envBin = env.AXON_RUNTIME_BIN;
+    if (envBin && existsSync(envBin))
+        return envBin;
+    // Fall back to PATH lookup
+    return "axon-runtime";
+}
+function findFreePort() {
+    return new Promise((resolve, reject) => {
+        const srv = createServer();
+        srv.listen(0, "127.0.0.1", () => {
+            const addr = srv.address();
+            if (addr && typeof addr === "object") {
+                const port = addr.port;
+                srv.close(() => resolve(port));
+            }
+            else {
+                srv.close(() => reject(new AxonBridgeError("failed to get free port")));
+            }
+        });
+        srv.on("error", reject);
+    });
+}
+function waitForPort(host, port, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    return new Promise((res) => {
+        function tryConnect() {
+            if (Date.now() > deadline) {
+                res(false);
+                return;
+            }
+            const sock = createConnection({ host, port, timeout: 500 }, () => {
+                sock.destroy();
+                res(true);
+            });
+            sock.on("error", () => { sock.destroy(); setTimeout(tryConnect, 100); });
+        }
+        tryConnect();
+    });
+}
+function parseEndpoint(endpoint) {
+    const raw = endpoint.trim();
+    if (raw.startsWith("axon://")) {
+        const authority = raw.slice("axon://".length).split("/")[0];
+        if (!authority || authority === "localhost")
+            return { host: "127.0.0.1", port: DEFAULT_AXON_PORT };
+        if (authority.startsWith("localhost:"))
+            return { host: "127.0.0.1", port: parseInt(authority.split(":")[1], 10) || DEFAULT_AXON_PORT };
+        const idx = authority.lastIndexOf(":");
+        if (idx > 0)
+            return { host: authority.slice(0, idx), port: parseInt(authority.slice(idx + 1), 10) || DEFAULT_AXON_PORT };
+        return { host: authority, port: DEFAULT_AXON_PORT };
+    }
+    const url = raw.replace(/^https?:\/\//, "").split("/")[0];
+    const idx = url.lastIndexOf(":");
+    if (idx > 0)
+        return { host: url.slice(0, idx), port: parseInt(url.slice(idx + 1), 10) || DEFAULT_AXON_PORT };
+    return { host: url, port: DEFAULT_AXON_PORT };
+}
+function normalizeHubEndpoint(endpoint) {
+    const trimmed = endpoint?.trim();
+    if (!trimmed)
+        return undefined;
+    if (trimmed.startsWith("axon://")) {
+        const { host, port } = parseEndpoint(trimmed);
+        return `http://${host}:${port}`;
+    }
+    return trimmed;
+}
+/**
+ * Start or connect to an Axon runtime.
+ *
+ * @example
+ * // Auto-start a local server (zero config):
+ * const srv = await startServer();
+ *
+ * // Connect via axon:// transport URI:
+ * const srv = await startServer("axon://localhost");
+ * const srv = await startServer("axon://10.0.0.5:50084");
+ *
+ * // Federation mode — connect the local runtime to a Hub:
+ * const srv = await startServer(undefined, { hub: "axon://hub.easynet.run:50084" });
+ */
+export async function startServer(endpoint, options = {}) {
+    const timeoutMs = options.timeoutMs ?? 10000;
+    // Resolve from env if not provided
+    if (!endpoint) {
+        endpoint = env.EASYNET_AXON_ENDPOINT;
+    }
+    // --- Connect to existing server ---
+    if (endpoint) {
+        cliLog(`connecting to ${endpoint}`);
+        const { host, port } = parseEndpoint(endpoint);
+        const ok = await waitForPort(host, port, timeoutMs);
+        if (!ok)
+            throw new AxonBridgeError(`cannot reach server at ${endpoint}`);
+        cliLog(`connected to ${endpoint}`);
+        return { endpoint, process: null, logFile: null, stop() { } };
+    }
+    // --- Spawn local server ---
+    const port = await findFreePort();
+    const host = "127.0.0.1";
+    const bindAddr = `${host}:${port}`;
+    const endpointUrl = `http://${bindAddr}`;
+    const binary = findRuntimeBinary();
+    const logDir = DEFAULT_LOG_DIR;
+    const logFile = options.logFile ?? join(logDir, "axon-runtime.log");
+    mkdirSync(dirname(logFile), { recursive: true });
+    const logFd = openSync(logFile, "a");
+    const childEnv = {
+        ...process.env,
+        AXON_BIND: bindAddr,
+        AXON_ENFORCE_MTLS: (options.insecure ?? true) ? "false" : "true",
+    };
+    const hubEndpoint = normalizeHubEndpoint(firstNonEmpty(options.hub, env.AXON_HUB));
+    if (hubEndpoint) {
+        childEnv.AXON_HUB = hubEndpoint;
+        childEnv.AXON_FEDERATION_TENANT = firstNonEmpty(options.hubTenant, env.AXON_FEDERATION_TENANT, "default");
+        childEnv.AXON_FEDERATION_LABEL = firstNonEmpty(options.hubLabel, env.AXON_FEDERATION_LABEL, localHostname());
+        const hubJoinToken = firstNonEmpty(options.hubJoinToken, env.AXON_HUB_JOIN_TOKEN, env.AXON_FEDERATION_JOIN_TOKEN);
+        if (hubJoinToken) {
+            childEnv.AXON_HUB_JOIN_TOKEN = hubJoinToken;
+        }
+        cliLog(`federation: will connect to hub at ${hubEndpoint}`);
+    }
+    cliLog(`starting axon-runtime on ${bindAddr} (log: ${logFile})`);
+    const child = spawn(binary, [], {
+        env: childEnv,
+        stdio: ["ignore", logFd, logFd],
+    });
+    const ready = await waitForPort(host, port, timeoutMs);
+    if (!ready) {
+        child.kill();
+        throw new AxonBridgeError(`axon-runtime not ready within ${timeoutMs}ms on ${bindAddr} (see ${logFile})`);
+    }
+    cliLog(`axon-runtime ready → ${endpointUrl}`);
+    return {
+        endpoint: endpointUrl,
+        process: child,
+        logFile,
+        stop() {
+            if (child.exitCode === null) {
+                cliLog(`stopping axon-runtime (pid ${child.pid})`);
+                child.kill("SIGTERM");
+                const timer = setTimeout(() => {
+                    if (child.exitCode === null)
+                        child.kill("SIGKILL");
+                }, 5000);
+                timer.unref();
+                child.once("exit", () => {
+                    clearTimeout(timer);
+                    cliLog("axon-runtime stopped");
+                });
+            }
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// create
+// ---------------------------------------------------------------------------
+export function createAbility(opts) {
+    if (!opts.name?.trim())
+        throw new AxonConfigError("ability name cannot be empty");
+    if (!opts.commandTemplate?.trim())
+        throw new AxonConfigError("command_template cannot be empty");
+    const token = normalizeAbilityName(opts.name);
+    return {
+        name: opts.name,
+        description: opts.description,
+        commandTemplate: opts.commandTemplate,
+        inputSchema: opts.inputSchema ?? { type: "object", properties: {} },
+        outputSchema: opts.outputSchema ?? { type: "object", properties: {} },
+        version: opts.version ?? "1.0.0",
+        tags: opts.tags ?? [],
+        resourceUri: opts.resourceUri ?? `easynet:///r/org/${token}`,
+    };
+}
+// ---------------------------------------------------------------------------
+// toToolSpec
+// ---------------------------------------------------------------------------
+export function toToolSpec(descriptor) {
+    const token = normalizeAbilityName(descriptor.name);
+    return {
+        name: token,
+        description: descriptor.description,
+        resourceUri: descriptor.resourceUri,
+        parameters: descriptor.inputSchema,
+    };
+}
+// ---------------------------------------------------------------------------
+// exportAbility
+// ---------------------------------------------------------------------------
+export function exportAbility(descriptor, target = "agent_skills", axonEndpoint) {
+    const token = normalizeAbilityName(descriptor.name);
+    const endpoint = axonEndpoint ?? `http://127.0.0.1:${DEFAULT_AXON_PORT}`;
+    const invokeScript = generateInvokeScript(descriptor.resourceUri, endpoint);
+    const abilityMd = generateAbilityMd(descriptor, target, token);
+    return { abilityMd, invokeScript, abilityName: token };
+}
+// ---------------------------------------------------------------------------
+// deployToNode
+// ---------------------------------------------------------------------------
+/**
+ * Deploy an AbilityDescriptor to a node via the MCP deploy pipeline.
+ *
+ * The underlying bridge call executes a three-phase pipeline
+ * (Publish → Install → Activate).  This function wraps the entire
+ * pipeline in a single {@link DeployTrace} receipt so callers get
+ * wall-clock timing and error codes even on failure.
+ *
+ * On failure an {@link AxonInvocationError} is thrown with its `trace`
+ * field set to the collected {@link DeployTrace}:
+ *
+ * ```ts
+ * try { await deployToNode(bridge, tenant, nodeId, desc, sig); }
+ * catch (e) { if (e instanceof AxonInvocationError) console.log(e.trace); }
+ * ```
+ */
+export async function deployToNode(bridge, tenant, nodeId, descriptor, signature) {
+    const token = normalizeAbilityName(descriptor.name);
+    const abilityId = token;
+    const pkg = buildDeployPackage({
+        ability_name: descriptor.name,
+        tool_name: token,
+        description: descriptor.description,
+        command_template: descriptor.commandTemplate,
+        version: descriptor.version,
+        input_schema: descriptor.inputSchema,
+        output_schema: descriptor.outputSchema,
+        tags: descriptor.tags.length > 0 ? descriptor.tags : undefined,
+    }, signature);
+    const builder = beginPhase("deploy", tenant, nodeId, abilityId);
+    try {
+        const result = await bridge.deployAbilityPackage(tenant, nodeId, pkg);
+        const installId = String(result.install_id ?? "");
+        const receipt = builder.finishOk(installId || undefined);
+        const trace = buildDeployTrace([receipt]);
+        return { result, trace };
+    }
+    catch (e) {
+        const err = e instanceof Error ? e : new Error(String(e));
+        const receipt = builder.finishErr(err);
+        const trace = buildDeployTrace([receipt]);
+        throw new AxonInvocationError(err.message, { install_id: abilityId }, trace);
+    }
+}
+// ---------------------------------------------------------------------------
+// listAbilities
+// ---------------------------------------------------------------------------
+export async function listAbilities(bridge, tenant, nodeId) {
+    const result = await bridge.listMcpTools(tenant, "", nodeId);
+    return (Array.isArray(result) ? result : []);
+}
+// ---------------------------------------------------------------------------
+// invokeAbility
+// ---------------------------------------------------------------------------
+export async function invokeAbility(bridge, tenant, nodeId, toolName, args = {}) {
+    return await bridge.callMcpToolWithArgs(tenant, toolName, nodeId, args);
+}
+// ---------------------------------------------------------------------------
+// uninstallAbility
+// ---------------------------------------------------------------------------
+export async function uninstallAbility(bridge, tenant, nodeId, installId, reason) {
+    return await bridge.uninstallAbilityWithReason(tenant, nodeId, installId, reason ?? "ability lifecycle: uninstall");
+}
+// ---------------------------------------------------------------------------
+// discoverNodes
+// ---------------------------------------------------------------------------
+export async function discoverNodes(bridge, tenant) {
+    const result = await bridge.listNodes(tenant, null);
+    return (Array.isArray(result) ? result : []);
+}
+// ---------------------------------------------------------------------------
+// executeCommand
+// ---------------------------------------------------------------------------
+export async function executeCommand(bridge, tenant, nodeId, command) {
+    const toolName = `cmd_${Date.now()}_${randomHex(4)}`;
+    const wrapped = buildPythonSubprocessTemplate(command);
+    const deployResult = await bridge.deployAbilityPackage(tenant, nodeId, {
+        ability_name: toolName,
+        tool_name: toolName,
+        description: `execute: ${command}`,
+        command_template: wrapped,
+        signature_base64: EPHEMERAL_SIGNATURE,
+        tags: ["ephemeral", "auto-cleanup"],
+    });
+    const result = await bridge.callMcpToolWithArgs(tenant, toolName, nodeId, {});
+    let cleanupOk = true;
+    let cleanupError;
+    const installId = String(deployResult.install_id ?? "");
+    if (installId) {
+        try {
+            await bridge.uninstallAbilityWithReason(tenant, nodeId, installId, "execute_command cleanup");
+        }
+        catch (e) {
+            process.stderr.write(`[axon] execute_command cleanup failed for ${installId}: ${e}\n`);
+            cleanupOk = false;
+            cleanupError = String(e);
+        }
+    }
+    return { ...result, cleanup: { ok: cleanupOk, error: cleanupError } };
+}
+/**
+ * Remove all deployed abilities from a device.
+ * Requires `confirm = true` as a safety gate (destructive operation).
+ *
+ * When `options.dryRun` is `true`, the function lists all abilities that would
+ * be removed without performing any uninstalls.  The `confirm` parameter is
+ * ignored for dry-run calls since no data is modified.
+ *
+ * @throws {AxonPartialSuccessError} When any uninstall fails (partial or total failure).
+ * @throws {AxonConfigError} When `confirm` is not `true` and `dryRun` is not set.
+ */
+export async function forgetAll(bridge, tenant, nodeId, confirm = false, options = {}) {
+    const dryRun = options.dryRun ?? false;
+    if (!confirm && !dryRun) {
+        throw new AxonConfigError("forget_all requires confirm = true (destructive operation)");
+    }
+    const tools = await listAbilities(bridge, tenant, nodeId);
+    // Dry-run mode: collect the list of abilities that would be removed
+    // without performing any uninstalls.
+    if (dryRun) {
+        const wouldRemove = [];
+        for (const tool of tools) {
+            const installId = String(tool.install_id ?? "");
+            const toolName = String(tool.tool_name ?? "");
+            if (!installId)
+                continue;
+            wouldRemove.push(toolName);
+        }
+        return { removed: wouldRemove, removed_count: wouldRemove.length, failed: [], failed_count: 0 };
+    }
+    const removed = [];
+    const failed = [];
+    for (const tool of tools) {
+        const installId = String(tool.install_id ?? "");
+        const toolName = String(tool.tool_name ?? "");
+        if (!installId)
+            continue;
+        try {
+            await bridge.uninstallAbilityWithReason(tenant, nodeId, installId, "forget_all");
+            removed.push(toolName);
+        }
+        catch (e) {
+            process.stderr.write(`[axon] forget_all: failed to uninstall ${toolName}: ${e}\n`);
+            failed.push({ tool_name: toolName, error: String(e) });
+        }
+    }
+    const result = { removed, removed_count: removed.length, failed, failed_count: failed.length };
+    if (failed.length > 0) {
+        throw new AxonPartialSuccessError(`forget_all: ${removed.length} succeeded, ${failed.length} failed`, removed.length, failed.length, { removed, failed, result });
+    }
+    return result;
+}
+// ---------------------------------------------------------------------------
+// disconnectDevice
+// ---------------------------------------------------------------------------
+export async function disconnectDevice(bridge, tenant, nodeId, reason) {
+    return await bridge.deregisterNode(tenant, nodeId, reason ?? "sdk: disconnect_device");
+}
+// ---------------------------------------------------------------------------
+// drainDevice
+// ---------------------------------------------------------------------------
+export async function drainDevice(bridge, tenant, nodeId, reason) {
+    return await bridge.drainNode(tenant, nodeId, reason ?? "sdk: drain_device");
+}
+// ---------------------------------------------------------------------------
+// listRemoteTools
+// ---------------------------------------------------------------------------
+export async function listRemoteTools(bridge, tenant, namePattern = "", nodeId = "") {
+    const result = await bridge.listMcpTools(tenant, namePattern, nodeId);
+    return (Array.isArray(result) ? result : []);
+}
+// ---------------------------------------------------------------------------
+// buildDeployPackage
+// ---------------------------------------------------------------------------
+export function buildDeployPackage(args, signature) {
+    const abilityName = String(args.ability_name ?? "");
+    const toolName = String(args.tool_name ?? abilityName);
+    return {
+        ability_name: abilityName,
+        tool_name: toolName,
+        description: args.description ?? "",
+        command_template: args.command_template ?? "",
+        input_schema: args.input_schema ?? { type: "object", properties: {} },
+        output_schema: args.output_schema ?? { type: "object", properties: {} },
+        version: args.version ?? "1.0.0",
+        tags: args.tags ?? [],
+        signature_base64: signature,
+    };
+}
+// ---------------------------------------------------------------------------
+// deployPackage
+// ---------------------------------------------------------------------------
+export async function deployPackage(bridge, tenant, nodeId, packageDescriptor) {
+    return await bridge.deployAbilityPackage(tenant, nodeId, packageDescriptor);
+}
+// ---------------------------------------------------------------------------
+// Internal generators
+// ---------------------------------------------------------------------------
+function generateInvokeScript(resourceUri, endpoint) {
+    return `#!/usr/bin/env bash
+set -euo pipefail
+AXON_ENDPOINT="\${AXON_ENDPOINT:-${endpoint}}"
+TENANT="\${AXON_TENANT:-default}"
+RESOURCE_URI="${resourceUri}"
+ARGS="\${1:-{}}"
+curl -sS -X POST "\${AXON_ENDPOINT}/v1/invoke" \\
+  -H "Content-Type: application/json" \\
+  -d "{\\"tenant_id\\":\\"\${TENANT}\\",\\"resource_uri\\":\\"\${RESOURCE_URI}\\",\\"payload\\":\${ARGS}}"
+`;
+}
+function pushMetadata(lines, version, resourceUri) {
+    lines.push("metadata:");
+    lines.push("  author: easynet-axon");
+    lines.push(`  version: "${version}"`);
+    lines.push(`  axon-resource-uri: "${resourceUri}"`);
+}
+function generateAbilityMd(descriptor, target, token) {
+    const lines = [];
+    lines.push("---");
+    lines.push(`name: ${token}`);
+    lines.push(`description: ${descriptor.description}`);
+    lines.push("compatibility: Requires network access to Axon runtime");
+    pushMetadata(lines, descriptor.version, descriptor.resourceUri);
+    if (target === "claude") {
+        lines.push("allowed-tools: Bash(*)");
+    }
+    else if (target === "openclaw") {
+        lines.push("  openclaw:");
+        lines.push('    emoji: "⚡"');
+        lines.push("    requires:");
+        lines.push("      network: true");
+        lines.push("    command-dispatch: tool");
+    }
+    lines.push("---");
+    lines.push("");
+    lines.push(`# ${descriptor.name}`);
+    lines.push("");
+    lines.push(descriptor.description);
+    lines.push("");
+    lines.push("## Parameters");
+    lines.push("");
+    lines.push("| Name | Type | Required | Description |");
+    lines.push("|------|------|----------|-------------|");
+    const props = (descriptor.inputSchema.properties ?? {});
+    const required = (descriptor.inputSchema.required ?? []);
+    for (const [name, schema] of Object.entries(props)) {
+        const propType = schema.type ?? "string";
+        const propDesc = schema.description ?? "";
+        const isRequired = required.includes(name) ? "Yes" : "No";
+        lines.push(`| ${name} | ${propType} | ${isRequired} | ${propDesc} |`);
+    }
+    lines.push("");
+    lines.push("## Invoke");
+    lines.push("");
+    lines.push("Run the bundled script with a JSON argument:");
+    lines.push("");
+    const skillDirVar = target === "claude" ? "CLAUDE_SKILL_DIR"
+        : target === "codex" ? "CODEX_SKILL_DIR"
+            : "SKILL_DIR";
+    lines.push("```bash");
+    lines.push(`\${${skillDirVar}}/scripts/invoke.sh '{"param": "value"}'`);
+    lines.push("```");
+    lines.push("");
+    lines.push("## Axon Resource");
+    lines.push("");
+    lines.push(`- **URI**: \`${descriptor.resourceUri}\``);
+    lines.push(`- **Version**: ${descriptor.version}`);
+    lines.push("");
+    return lines.join("\n");
+}

package/src/capability_request.d.ts

@@ -0,0 +1,14 @@
+export declare class DendriteError extends Error {
+    constructor(message: string);
+}
+import type { DendritePublishCapabilityOptions, DendriteInstallCapabilityOptions, DendriteDeployMcpListDirOptions, DendriteUpdateMcpListDirOptions, DendriteUninstallCapabilityOptions } from "./dendrite_bridge/types.js";
+export declare function validatePublishCapabilityRequest(tenantId: string, packageId: string, capabilityName: string, options: DendritePublishCapabilityOptions): void;
+export declare function buildPublishCapabilityPayload(tenantId: string, packageId: string, capabilityName: string, options: DendritePublishCapabilityOptions): Record<string, unknown>;
+export declare function validateInstallCapabilityRequest(tenantId: string, nodeId: string, packageId: string, options: DendriteInstallCapabilityOptions): void;
+export declare function buildInstallCapabilityPayload(tenantId: string, nodeId: string, packageId: string, options: DendriteInstallCapabilityOptions): Record<string, unknown>;
+export declare function validateDeployMcpListDirRequest(tenantId: string, nodeId: string, options?: DendriteDeployMcpListDirOptions): void;
+export declare function buildDeployMcpListDirPayload(tenantId: string, nodeId: string, options?: DendriteDeployMcpListDirOptions): Record<string, unknown>;
+export declare function validateUpdateMcpListDirRequest(tenantId: string, nodeId: string, options?: DendriteUpdateMcpListDirOptions): void;
+export declare function buildUpdateMcpListDirPayload(tenantId: string, nodeId: string, options?: DendriteUpdateMcpListDirOptions): Record<string, unknown>;
+export declare function validateUninstallCapabilityRequest(tenantId: string, nodeId: string, installId: string): void;
+export declare function buildUninstallCapabilityPayload(tenantId: string, nodeId: string, installId: string, options?: DendriteUninstallCapabilityOptions): Record<string, unknown>;