@easynet-run/node 0.27.14

package/src/capability_request.js

@@ -0,0 +1,247 @@
+// EasyNet Axon for AgentNet
+// =========================
+//
+// File: sdk/node/src/capability_request.ts
+// Description: Source file for Node SDK bridge and capability request implementation; keeps behavior explicit and interoperable across language/runtime boundaries.
+//
+// Protocol Responsibility:
+// - Implements Node SDK bridge and capability request implementation contracts required by current Axon service and SDK surfaces.
+// - Preserves stable request/response semantics and error mapping for capability_request.ts call paths.
+//
+// Implementation Approach:
+// - Uses small typed helpers and explicit control flow to avoid hidden side effects.
+// - Keeps protocol translation and transport details close to this module boundary.
+//
+// Usage Contract:
+// - Callers should provide valid tenant/resource/runtime context before invoking exported APIs.
+// - Errors should be treated as typed protocol/runtime outcomes rather than silently ignored.
+//
+// Architectural Position:
+// - Part of the Node SDK bridge and capability request implementation layer.
+// - Should not embed unrelated orchestration logic outside this file's responsibility.
+//
+// Author: Silan.Hu
+// Email: silan.hu@u.nus.edu
+// Copyright (c) 2026-2027 easynet. All rights reserved.
+import { AxonConfigError } from "./errors.js";
+// DendriteError kept for backward compatibility; validation now uses AxonConfigError.
+export class DendriteError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "DendriteError";
+    }
+}
+const defaultDeploySignatureSentinelBase64 = "__AXON_EPHEMERAL_DO_NOT_USE_IN_PROD__";
+const digestPrefix = "sha256:";
+let placeholderDeploySignatureWarningEmitted = false;
+const DEFAULT_TARGET_PATH = "/client";
+function warnPlaceholderDeploySignatureOnce() {
+    if (placeholderDeploySignatureWarningEmitted) {
+        return;
+    }
+    placeholderDeploySignatureWarningEmitted = true;
+    console.warn("warning: AXON_ALLOW_PLACEHOLDER_DEPLOY_SIGNATURE is enabled; the placeholder deploy signature is for local development only and must not be used in production");
+}
+function resolveTargetPath(raw) {
+    const trimmed = raw?.trim();
+    return trimmed || DEFAULT_TARGET_PATH;
+}
+function requireNonBlank(field, value) {
+    if (!value || !value.trim()) {
+        throw new AxonConfigError(`${field} is required`);
+    }
+}
+function validateDigestPrefix(field, value) {
+    const trimmed = value?.trim();
+    if (!trimmed) {
+        return;
+    }
+    if (!trimmed.startsWith(digestPrefix) || trimmed.length === digestPrefix.length) {
+        throw new AxonConfigError(`${field} must start with 'sha256:' (e.g. sha256:<hex>)`);
+    }
+}
+function putOptionalNonBlank(payload, key, value) {
+    if (value !== undefined && value !== null) {
+        const trimmed = value.trim();
+        if (trimmed) {
+            payload[key] = trimmed;
+        }
+    }
+}
+/**
+ * Add key only when value is positive; zero is treated as absent to avoid
+ * accidental proof-size pinning when callers omit an explicit payload size.
+ */
+function putOptionalPayloadSize(payload, key, value) {
+    if (value === undefined || value === null)
+        return;
+    if (value < 0) {
+        throw new AxonConfigError(`${key} must be >= 0`);
+    }
+    if (value > 0) {
+        payload[key] = value;
+    }
+}
+function resolveDeploySignatureBase64(signatureBase64) {
+    if (signatureBase64 && signatureBase64.trim()) {
+        return signatureBase64.trim();
+    }
+    const fromEnv = process.env.AXON_DEPLOY_SIGNATURE_BASE64;
+    if (fromEnv && fromEnv.trim()) {
+        return fromEnv.trim();
+    }
+    const allowPlaceholder = process.env.AXON_ALLOW_PLACEHOLDER_DEPLOY_SIGNATURE?.trim().toLowerCase();
+    if (allowPlaceholder === "1" || allowPlaceholder === "true" || allowPlaceholder === "yes") {
+        warnPlaceholderDeploySignatureOnce();
+        return defaultDeploySignatureSentinelBase64;
+    }
+    throw new AxonConfigError("deploy signature required: set signatureBase64, AXON_DEPLOY_SIGNATURE_BASE64, or explicitly enable AXON_ALLOW_PLACEHOLDER_DEPLOY_SIGNATURE");
+}
+export function validatePublishCapabilityRequest(tenantId, packageId, capabilityName, options) {
+    requireNonBlank("tenantId", tenantId);
+    requireNonBlank("packageId", packageId);
+    requireNonBlank("capabilityName", capabilityName);
+    requireNonBlank("version", options.version);
+    validateDigestPrefix("digest", options.digest);
+    requireNonBlank("signatureBase64", options.signatureBase64);
+    if ((!options.payloadUri || !options.payloadUri.trim()) &&
+        (!options.packageBytesBase64 || !options.packageBytesBase64.trim())) {
+        throw new AxonConfigError("payloadUri or packageBytesBase64 is required");
+    }
+    if (options.payloadSizeBytes !== undefined && options.payloadSizeBytes < 0) {
+        throw new AxonConfigError("payloadSizeBytes must be >= 0");
+    }
+}
+export function buildPublishCapabilityPayload(tenantId, packageId, capabilityName, options) {
+    const payload = {
+        tenant_id: tenantId.trim(),
+        package_id: packageId.trim(),
+        capability_name: capabilityName.trim(),
+        tags: options.tags ?? [],
+        requirements: options.requirements ?? {},
+        metadata: options.metadata ?? {},
+    };
+    payload.version = options.version.trim();
+    putOptionalNonBlank(payload, "digest", options.digest);
+    payload.signature_base64 = options.signatureBase64.trim();
+    putOptionalNonBlank(payload, "payload_uri", options.payloadUri);
+    putOptionalPayloadSize(payload, "payload_size_bytes", options.payloadSizeBytes);
+    putOptionalNonBlank(payload, "package_bytes_base64", options.packageBytesBase64);
+    putOptionalNonBlank(payload, "signature_fingerprint", options.signatureFingerprint);
+    putOptionalNonBlank(payload, "package_fingerprint", options.packageFingerprint);
+    if (options.publisherKeyVersion !== undefined && options.publisherKeyVersion > 0) {
+        payload.publisher_key_version = options.publisherKeyVersion;
+    }
+    return payload;
+}
+export function validateInstallCapabilityRequest(tenantId, nodeId, packageId, options) {
+    requireNonBlank("tenantId", tenantId);
+    requireNonBlank("nodeId", nodeId);
+    requireNonBlank("packageId", packageId);
+    requireNonBlank("version", options.version);
+    validateDigestPrefix("digest", options.digest);
+    validateDigestPrefix("payloadDigest", options.payloadDigest);
+    if ((!options.digest || !options.digest.trim()) &&
+        (!options.payloadDigest || !options.payloadDigest.trim())) {
+        throw new AxonConfigError("digest or payloadDigest is required");
+    }
+    if (options.payloadSizeBytes !== undefined && options.payloadSizeBytes < 0) {
+        throw new AxonConfigError("payloadSizeBytes must be >= 0");
+    }
+}
+export function buildInstallCapabilityPayload(tenantId, nodeId, packageId, options) {
+    const payload = {
+        tenant_id: tenantId.trim(),
+        node_id: nodeId.trim(),
+        package_id: packageId.trim(),
+    };
+    payload.version = options.version.trim();
+    putOptionalNonBlank(payload, "digest", options.digest);
+    putOptionalNonBlank(payload, "payload_digest", options.payloadDigest);
+    putOptionalPayloadSize(payload, "payload_size_bytes", options.payloadSizeBytes);
+    putOptionalNonBlank(payload, "signature_fingerprint", options.signatureFingerprint);
+    putOptionalNonBlank(payload, "package_fingerprint", options.packageFingerprint);
+    if (options.requireConsent !== undefined) {
+        payload.require_consent = options.requireConsent;
+    }
+    if (options.allowTransferredCode !== undefined) {
+        payload.allow_transferred_code = options.allowTransferredCode;
+    }
+    putOptionalNonBlank(payload, "execution_mode", options.executionMode);
+    if (options.installTimeoutSeconds !== undefined) {
+        payload.install_timeout_seconds = options.installTimeoutSeconds;
+    }
+    return payload;
+}
+export function validateDeployMcpListDirRequest(tenantId, nodeId, options = {}) {
+    requireNonBlank("tenantId", tenantId);
+    requireNonBlank("nodeId", nodeId);
+    const targetPath = resolveTargetPath(options.targetPath);
+    requireNonBlank("targetPath", targetPath);
+    requireNonBlank("commandTemplate", options.commandTemplate);
+    validateDigestPrefix("digest", options.digest);
+}
+export function buildDeployMcpListDirPayload(tenantId, nodeId, options = {}) {
+    const targetPath = resolveTargetPath(options.targetPath);
+    const payload = {
+        tenant_id: tenantId.trim(),
+        node_id: nodeId.trim(),
+        target_path: targetPath,
+        command_template: options.commandTemplate?.trim(),
+        signature_base64: resolveDeploySignatureBase64(options.signatureBase64),
+    };
+    putOptionalNonBlank(payload, "package_id", options.packageId);
+    putOptionalNonBlank(payload, "capability_name", options.capabilityName);
+    putOptionalNonBlank(payload, "tool_name", options.toolName);
+    putOptionalNonBlank(payload, "version", options.version);
+    putOptionalNonBlank(payload, "digest", options.digest);
+    putOptionalNonBlank(payload, "package_bytes_base64", options.packageBytesBase64);
+    return payload;
+}
+export function validateUpdateMcpListDirRequest(tenantId, nodeId, options = {}) {
+    requireNonBlank("tenantId", tenantId);
+    requireNonBlank("nodeId", nodeId);
+    const targetPath = resolveTargetPath(options.targetPath);
+    requireNonBlank("targetPath", targetPath);
+    requireNonBlank("commandTemplate", options.commandTemplate);
+    validateDigestPrefix("digest", options.digest);
+}
+export function buildUpdateMcpListDirPayload(tenantId, nodeId, options = {}) {
+    const targetPath = resolveTargetPath(options.targetPath);
+    const payload = {
+        tenant_id: tenantId.trim(),
+        node_id: nodeId.trim(),
+        deactivate_old: options.deactivateOld ?? true,
+        uninstall_old: options.uninstallOld ?? true,
+        force_uninstall: options.forceUninstall ?? false,
+        target_path: targetPath,
+        command_template: options.commandTemplate?.trim(),
+        signature_base64: resolveDeploySignatureBase64(options.signatureBase64),
+    };
+    putOptionalNonBlank(payload, "existing_install_id", options.existingInstallId);
+    putOptionalNonBlank(payload, "deactivate_reason", options.deactivateReason);
+    putOptionalNonBlank(payload, "package_id", options.packageId);
+    putOptionalNonBlank(payload, "capability_name", options.capabilityName);
+    putOptionalNonBlank(payload, "tool_name", options.toolName);
+    putOptionalNonBlank(payload, "version", options.version);
+    putOptionalNonBlank(payload, "digest", options.digest);
+    putOptionalNonBlank(payload, "package_bytes_base64", options.packageBytesBase64);
+    return payload;
+}
+export function validateUninstallCapabilityRequest(tenantId, nodeId, installId) {
+    requireNonBlank("tenantId", tenantId);
+    requireNonBlank("nodeId", nodeId);
+    requireNonBlank("installId", installId);
+}
+export function buildUninstallCapabilityPayload(tenantId, nodeId, installId, options = {}) {
+    validateUninstallCapabilityRequest(tenantId, nodeId, installId);
+    const payload = {
+        tenant_id: tenantId.trim(),
+        node_id: nodeId.trim(),
+        install_id: installId.trim(),
+        deactivate_first: options.deactivateFirst ?? true,
+        force: options.force ?? false,
+    };
+    putOptionalNonBlank(payload, "deactivate_reason", options.deactivateReason);
+    return payload;
+}

package/src/dendrite_bridge/bridge.d.ts

@@ -0,0 +1,98 @@
+import type { DendriteBridgeOptions, DendriteUnaryCallOptions, DendriteAbilityCallOptions, DendriteStreamCallOptions, DendriteClientStreamCallOptions, DendriteBidiStreamCallOptions, DendriteListNodesOptions, DendriteRegisterNodeOptions, DendritePublishCapabilityOptions, DendriteInstallCapabilityOptions, DendriteListA2aAgentsOptions, DendriteSendA2aTaskOptions, DendriteDeployMcpListDirOptions, DendriteListMcpToolsOptions, DendriteCallMcpToolOptions, DendriteUninstallCapabilityOptions, DendriteUpdateMcpListDirOptions, DendriteVoiceCreateCallOptions, DendriteVoiceJoinCallOptions, DendriteVoiceUpdateMediaPathOptions, DendriteVoiceMetricsOptions, DendriteVoiceEndCallOptions, DendriteVoiceWatchOptions, DendriteVoiceCreateTransportSessionOptions, DendriteVoiceDescriptionOptions, DendriteVoiceCandidateOptions, DendriteVoiceEndTransportSessionOptions, DendriteProtocolInvokeOptions } from "./types.js";
+import type { DendriteBridgeLib } from "./ffi.js";
+export declare class DendriteBridge {
+    private readonly lib;
+    private handle;
+    constructor(options: DendriteBridgeOptions);
+    close(): void;
+    protocolCoverage(): Record<string, unknown>;
+    protocolCatalog(): Record<string, unknown>;
+    invokeProtocol(options?: DendriteProtocolInvokeOptions): Record<string, unknown>;
+    unaryCall(path: string, requestBytes: Uint8Array, options?: DendriteUnaryCallOptions): Uint8Array;
+    serverStreamCall(path: string, requestBytes: Uint8Array, options?: DendriteStreamCallOptions): {
+        chunks: Uint8Array[];
+        truncated: boolean;
+    };
+    clientStreamCall(path: string, requestChunks: Uint8Array[], options?: DendriteClientStreamCallOptions): Uint8Array;
+    bidiStreamCall(path: string, requestChunks: Uint8Array[], options?: DendriteBidiStreamCallOptions): {
+        chunks: Uint8Array[];
+        truncated: boolean;
+    };
+    abilityCall(tenantId: string, resourceUri: string, payload: unknown, options?: DendriteAbilityCallOptions): Record<string, unknown>;
+    abilityCallRaw(tenantId: string, resourceUri: string, payload: unknown, options?: DendriteAbilityCallOptions): Record<string, unknown>;
+    listNodes(tenantId: string, options?: DendriteListNodesOptions): Record<string, unknown>[];
+    registerNode(tenantId: string, nodeId: string, options?: DendriteRegisterNodeOptions): Record<string, unknown>;
+    deregisterNode(tenantId: string, nodeId: string, reason?: string): Record<string, unknown>;
+    heartbeat(tenantId: string, nodeId: string): Record<string, unknown>;
+    publishCapability(tenantId: string, packageId: string, capabilityName: string, options: DendritePublishCapabilityOptions): Record<string, unknown>;
+    installCapability(tenantId: string, nodeId: string, packageId: string, options: DendriteInstallCapabilityOptions): Record<string, unknown>;
+    activateCapability(tenantId: string, nodeId: string, installId: string): Record<string, unknown>;
+    listA2aAgents(tenantId: string, options?: DendriteListA2aAgentsOptions): Record<string, unknown>[];
+    getA2aAgentCard(tenantId: string, nodeId: string): Record<string, unknown>;
+    sendA2aTask(tenantId: string, targetAgentId: string, skillId: string, options?: DendriteSendA2aTaskOptions): Record<string, unknown>;
+    deployMcpListDir(tenantId: string, nodeId: string, options?: DendriteDeployMcpListDirOptions): Record<string, unknown>;
+    listMcpTools(tenantId: string, options?: DendriteListMcpToolsOptions): Record<string, unknown>[];
+    callMcpTool(tenantId: string, toolName: string, options?: DendriteCallMcpToolOptions): Record<string, unknown>;
+    uninstallCapability(tenantId: string, nodeId: string, installId: string, options?: DendriteUninstallCapabilityOptions): Record<string, unknown>;
+    updateMcpListDir(tenantId: string, nodeId: string, options?: DendriteUpdateMcpListDirOptions): Record<string, unknown>;
+    createVoiceCall(tenantId: string, options?: DendriteVoiceCreateCallOptions): Record<string, unknown>;
+    getVoiceCall(tenantId: string, callId: string): Record<string, unknown>;
+    joinVoiceCall(tenantId: string, callId: string, options?: DendriteVoiceJoinCallOptions): Record<string, unknown>;
+    leaveVoiceCall(tenantId: string, callId: string, participantId: string, reason?: string): Record<string, unknown>;
+    updateVoiceMediaPath(tenantId: string, callId: string, participantId: string, options?: DendriteVoiceUpdateMediaPathOptions): Record<string, unknown>;
+    reportVoiceCallMetrics(tenantId: string, callId: string, participantId: string, metrics?: DendriteVoiceMetricsOptions): Record<string, unknown>;
+    endVoiceCall(tenantId: string, callId: string, options?: DendriteVoiceEndCallOptions): Record<string, unknown>;
+    watchVoiceCallEvents(tenantId: string, callId: string, options?: DendriteVoiceWatchOptions): Record<string, unknown>;
+    createVoiceTransportSession(tenantId: string, callId: string, participantId: string, options?: DendriteVoiceCreateTransportSessionOptions): Record<string, unknown>;
+    getVoiceTransportSession(tenantId: string, callId: string, transportSessionId: string): Record<string, unknown>;
+    setVoiceTransportDescription(tenantId: string, callId: string, transportSessionId: string, side: number, description: DendriteVoiceDescriptionOptions): Record<string, unknown>;
+    addVoiceTransportCandidate(tenantId: string, callId: string, transportSessionId: string, side: number, candidate: DendriteVoiceCandidateOptions): Record<string, unknown>;
+    refreshVoiceTransportLease(tenantId: string, callId: string, transportSessionId: string, requestedTtlSeconds?: number): Record<string, unknown>;
+    endVoiceTransportSession(tenantId: string, callId: string, transportSessionId: string, options?: DendriteVoiceEndTransportSessionOptions): Record<string, unknown>;
+    watchVoiceTransportEvents(tenantId: string, callId: string, transportSessionId: string, options?: DendriteVoiceWatchOptions): Record<string, unknown>;
+    serverStreamOpen(path: string, requestBytes: Uint8Array, options?: {
+        metadata?: Record<string, string>;
+        timeoutMs?: number;
+        chunkTimeoutMs?: number;
+        chunkBufferSize?: number;
+    }): DendriteServerStream;
+    bidiStreamOpen(path: string, options?: {
+        requestBytes?: Uint8Array;
+        requestChunks?: Uint8Array[];
+        metadata?: Record<string, string>;
+        timeoutMs?: number;
+        chunkTimeoutMs?: number;
+        chunkBufferSize?: number;
+        requestBufferSize?: number;
+    }): DendriteBidiStream;
+}
+export declare class DendriteServerStream implements AsyncIterable<Uint8Array> {
+    private readonly lib;
+    private readonly streamHandle;
+    private done;
+    private nativeClosed;
+    constructor(lib: DendriteBridgeLib, streamHandle: bigint);
+    next(timeoutMs?: number): {
+        chunk: Uint8Array | null;
+        done: boolean;
+        timeout?: boolean;
+    };
+    close(): void;
+    [Symbol.asyncIterator](): AsyncIterator<Uint8Array>;
+}
+export declare class DendriteBidiStream implements AsyncIterable<Uint8Array> {
+    private readonly lib;
+    private readonly streamHandle;
+    private done;
+    private nativeClosed;
+    constructor(lib: DendriteBridgeLib, streamHandle: bigint);
+    send(chunk: Uint8Array): boolean;
+    finishSend(): boolean;
+    recv(timeoutMs?: number): {
+        chunk: Uint8Array | null;
+        done: boolean;
+        timeout?: boolean;
+    };
+    close(): void;
+    [Symbol.asyncIterator](): AsyncIterator<Uint8Array>;
+}