@easynet-run/node 0.27.14

package/src/dendrite_bridge/ffi.d.ts

@@ -0,0 +1,60 @@
+import { DendriteError } from "../capability_request.js";
+export declare const DEFAULT_TIMEOUT_MS = 30000;
+export declare const DEFAULT_CONNECT_TIMEOUT_MS = 5000;
+interface DendriteBridgeJson {
+    ok: boolean;
+    [key: string]: unknown;
+}
+export { DendriteError };
+export type DendriteJsonFn<TArgs extends unknown[] = unknown[]> = (...args: TArgs) => string | null;
+export type DendriteBridgeLib = {
+    axon_dendrite_client_open_json: DendriteJsonFn<[string]>;
+    axon_dendrite_client_close_json: DendriteJsonFn<[bigint]>;
+    axon_dendrite_unary_call_json: DendriteJsonFn<[bigint, string]>;
+    axon_dendrite_server_stream_call_json: DendriteJsonFn<[bigint, string]>;
+    axon_dendrite_client_stream_call_json: DendriteJsonFn<[bigint, string]>;
+    axon_dendrite_bidi_stream_call_json: DendriteJsonFn<[bigint, string]>;
+    axon_dendrite_invoke_ability_json: DendriteJsonFn<[bigint, string]>;
+    axon_dendrite_protocol_catalog_json: DendriteJsonFn<[]>;
+    axon_dendrite_invoke_protocol_json: DendriteJsonFn<[bigint, string]>;
+    axon_dendrite_list_nodes_json: DendriteJsonFn<[bigint, string]>;
+    axon_dendrite_register_node_json: DendriteJsonFn<[bigint, string]>;
+    axon_dendrite_deregister_node_json?: DendriteJsonFn<[bigint, string]>;
+    axon_dendrite_heartbeat_json: DendriteJsonFn<[bigint, string]>;
+    axon_dendrite_publish_capability_json: DendriteJsonFn<[bigint, string]>;
+    axon_dendrite_install_capability_json: DendriteJsonFn<[bigint, string]>;
+    axon_dendrite_activate_capability_json: DendriteJsonFn<[bigint, string]>;
+    axon_dendrite_list_a2a_agents_json: DendriteJsonFn<[bigint, string]>;
+    axon_dendrite_get_a2a_agent_card_json: DendriteJsonFn<[bigint, string]>;
+    axon_dendrite_send_a2a_task_json: DendriteJsonFn<[bigint, string]>;
+    axon_dendrite_deploy_mcp_list_dir_json: DendriteJsonFn<[bigint, string]>;
+    axon_dendrite_list_mcp_tools_json: DendriteJsonFn<[bigint, string]>;
+    axon_dendrite_call_mcp_tool_json: DendriteJsonFn<[bigint, string]>;
+    axon_dendrite_uninstall_capability_json: DendriteJsonFn<[bigint, string]>;
+    axon_dendrite_update_mcp_list_dir_json: DendriteJsonFn<[bigint, string]>;
+    axon_dendrite_voice_create_call_json: DendriteJsonFn<[bigint, string]>;
+    axon_dendrite_voice_get_call_json: DendriteJsonFn<[bigint, string]>;
+    axon_dendrite_voice_join_call_json: DendriteJsonFn<[bigint, string]>;
+    axon_dendrite_voice_leave_call_json: DendriteJsonFn<[bigint, string]>;
+    axon_dendrite_voice_update_media_path_json: DendriteJsonFn<[bigint, string]>;
+    axon_dendrite_voice_report_call_metrics_json: DendriteJsonFn<[bigint, string]>;
+    axon_dendrite_voice_end_call_json: DendriteJsonFn<[bigint, string]>;
+    axon_dendrite_voice_watch_call_events_json: DendriteJsonFn<[bigint, string]>;
+    axon_dendrite_voice_create_transport_session_json: DendriteJsonFn<[bigint, string]>;
+    axon_dendrite_voice_get_transport_session_json: DendriteJsonFn<[bigint, string]>;
+    axon_dendrite_voice_set_transport_description_json: DendriteJsonFn<[bigint, string]>;
+    axon_dendrite_voice_add_transport_candidate_json: DendriteJsonFn<[bigint, string]>;
+    axon_dendrite_voice_refresh_transport_lease_json: DendriteJsonFn<[bigint, string]>;
+    axon_dendrite_voice_end_transport_session_json: DendriteJsonFn<[bigint, string]>;
+    axon_dendrite_voice_watch_transport_events_json: DendriteJsonFn<[bigint, string]>;
+    axon_dendrite_server_stream_open_json?: DendriteJsonFn<[bigint, string]>;
+    axon_dendrite_stream_next_json?: DendriteJsonFn<[bigint, string]>;
+    axon_dendrite_stream_close_json?: DendriteJsonFn<[bigint]>;
+    axon_dendrite_bidi_stream_open_json?: DendriteJsonFn<[bigint, string]>;
+    axon_dendrite_bidi_stream_send_json?: DendriteJsonFn<[bigint, string]>;
+    axon_dendrite_protocol_coverage_json: DendriteJsonFn<[]>;
+};
+export declare function resolveLibraryPath(explicitPath?: string): string;
+export declare function loadDendriteLib(libraryPath: string): DendriteBridgeLib;
+export declare function requireBridgeFn<TArgs extends unknown[]>(fn: DendriteJsonFn<TArgs> | undefined, featureMessage: string): DendriteJsonFn<TArgs>;
+export declare function callJson<TArgs extends unknown[]>(fn: DendriteJsonFn<TArgs>, ...args: TArgs): DendriteBridgeJson;

package/src/dendrite_bridge/ffi.js

@@ -0,0 +1,139 @@
+// EasyNet Axon for AgentNet
+// =========================
+//
+// File: sdk/node/src/dendrite_bridge/ffi.ts
+// Description: FFI loading and JSON calling layer for the Dendrite native bridge; resolves the shared library, binds koffi function pointers, and provides the callJson helper.
+//
+// Protocol Responsibility:
+// - Loads the native dendrite bridge shared library and exposes typed function bindings.
+// - Provides the low-level callJson helper that handles JSON serialization/error mapping.
+//
+// Implementation Approach:
+// - Uses koffi for native FFI binding.
+// - Keeps library resolution and error handling explicit.
+//
+// Usage Contract:
+// - Callers should use loadDendriteLib to obtain function bindings, then callJson to invoke them.
+// - Errors are surfaced as DendriteError instances.
+//
+// Architectural Position:
+// - Part of the Node SDK dendrite_bridge submodule layer.
+// - Should not embed class or interface logic outside FFI concerns.
+//
+// Author: Silan.Hu
+// Email: silan.hu@u.nus.edu
+// Copyright (c) 2026-2027 easynet. All rights reserved.
+import { createRequire } from "node:module";
+import { existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { DendriteError } from "../capability_request.js";
+const require = createRequire(import.meta.url);
+const koffi = require("koffi");
+export const DEFAULT_TIMEOUT_MS = 30000;
+export const DEFAULT_CONNECT_TIMEOUT_MS = 5000;
+export { DendriteError };
+export function resolveLibraryPath(explicitPath) {
+    if (explicitPath)
+        return explicitPath;
+    if (process.env.EASYNET_DENDRITE_BRIDGE_LIB)
+        return process.env.EASYNET_DENDRITE_BRIDGE_LIB;
+    const here = dirname(fileURLToPath(import.meta.url));
+    const candidates = [
+        resolve(here, "../../native/libaxon_dendrite_bridge.dylib"),
+        resolve(here, "../../native/libaxon_dendrite_bridge.so"),
+        resolve(here, "../../native/axon_dendrite_bridge.dll"),
+    ];
+    for (const c of candidates) {
+        if (existsSync(c))
+            return c;
+    }
+    throw new DendriteError("dendrite bridge library not found; set EASYNET_DENDRITE_BRIDGE_LIB or ensure package contains native/libaxon_dendrite_bridge.*");
+}
+export function loadDendriteLib(libraryPath) {
+    const lib = koffi.load(libraryPath);
+    const freeString = lib.func("void axon_dendrite_string_free(void *ptr)");
+    const bridgeString = koffi.disposable("str", (ptr) => {
+        if (ptr)
+            freeString(ptr);
+    });
+    const optionalJsonFn = (name, argTypes) => {
+        try {
+            return lib.func(name, bridgeString, argTypes);
+        }
+        catch {
+            return undefined;
+        }
+    };
+    return {
+        axon_dendrite_client_open_json: lib.func("axon_dendrite_client_open_json", bridgeString, ["str"]),
+        axon_dendrite_client_close_json: lib.func("axon_dendrite_client_close_json", bridgeString, ["uint64_t"]),
+        axon_dendrite_unary_call_json: lib.func("axon_dendrite_unary_call_json", bridgeString, ["uint64_t", "str"]),
+        axon_dendrite_server_stream_call_json: lib.func("axon_dendrite_server_stream_call_json", bridgeString, ["uint64_t", "str"]),
+        axon_dendrite_client_stream_call_json: lib.func("axon_dendrite_client_stream_call_json", bridgeString, ["uint64_t", "str"]),
+        axon_dendrite_bidi_stream_call_json: lib.func("axon_dendrite_bidi_stream_call_json", bridgeString, ["uint64_t", "str"]),
+        axon_dendrite_invoke_ability_json: lib.func("axon_dendrite_invoke_ability_json", bridgeString, ["uint64_t", "str"]),
+        axon_dendrite_protocol_catalog_json: lib.func("axon_dendrite_protocol_catalog_json", bridgeString, []),
+        axon_dendrite_invoke_protocol_json: lib.func("axon_dendrite_invoke_protocol_json", bridgeString, ["uint64_t", "str"]),
+        axon_dendrite_list_nodes_json: lib.func("axon_dendrite_list_nodes_json", bridgeString, ["uint64_t", "str"]),
+        axon_dendrite_register_node_json: lib.func("axon_dendrite_register_node_json", bridgeString, ["uint64_t", "str"]),
+        axon_dendrite_deregister_node_json: optionalJsonFn("axon_dendrite_deregister_node_json", ["uint64_t", "str"]),
+        axon_dendrite_heartbeat_json: lib.func("axon_dendrite_heartbeat_json", bridgeString, ["uint64_t", "str"]),
+        axon_dendrite_publish_capability_json: lib.func("axon_dendrite_publish_capability_json", bridgeString, ["uint64_t", "str"]),
+        axon_dendrite_install_capability_json: lib.func("axon_dendrite_install_capability_json", bridgeString, ["uint64_t", "str"]),
+        axon_dendrite_activate_capability_json: lib.func("axon_dendrite_activate_capability_json", bridgeString, ["uint64_t", "str"]),
+        axon_dendrite_list_a2a_agents_json: lib.func("axon_dendrite_list_a2a_agents_json", bridgeString, ["uint64_t", "str"]),
+        axon_dendrite_get_a2a_agent_card_json: lib.func("axon_dendrite_get_a2a_agent_card_json", bridgeString, ["uint64_t", "str"]),
+        axon_dendrite_send_a2a_task_json: lib.func("axon_dendrite_send_a2a_task_json", bridgeString, ["uint64_t", "str"]),
+        axon_dendrite_deploy_mcp_list_dir_json: lib.func("axon_dendrite_deploy_mcp_list_dir_json", bridgeString, ["uint64_t", "str"]),
+        axon_dendrite_list_mcp_tools_json: lib.func("axon_dendrite_list_mcp_tools_json", bridgeString, ["uint64_t", "str"]),
+        axon_dendrite_call_mcp_tool_json: lib.func("axon_dendrite_call_mcp_tool_json", bridgeString, ["uint64_t", "str"]),
+        axon_dendrite_uninstall_capability_json: lib.func("axon_dendrite_uninstall_capability_json", bridgeString, ["uint64_t", "str"]),
+        axon_dendrite_update_mcp_list_dir_json: lib.func("axon_dendrite_update_mcp_list_dir_json", bridgeString, ["uint64_t", "str"]),
+        axon_dendrite_voice_create_call_json: lib.func("axon_dendrite_voice_create_call_json", bridgeString, ["uint64_t", "str"]),
+        axon_dendrite_voice_get_call_json: lib.func("axon_dendrite_voice_get_call_json", bridgeString, ["uint64_t", "str"]),
+        axon_dendrite_voice_join_call_json: lib.func("axon_dendrite_voice_join_call_json", bridgeString, ["uint64_t", "str"]),
+        axon_dendrite_voice_leave_call_json: lib.func("axon_dendrite_voice_leave_call_json", bridgeString, ["uint64_t", "str"]),
+        axon_dendrite_voice_update_media_path_json: lib.func("axon_dendrite_voice_update_media_path_json", bridgeString, ["uint64_t", "str"]),
+        axon_dendrite_voice_report_call_metrics_json: lib.func("axon_dendrite_voice_report_call_metrics_json", bridgeString, ["uint64_t", "str"]),
+        axon_dendrite_voice_end_call_json: lib.func("axon_dendrite_voice_end_call_json", bridgeString, ["uint64_t", "str"]),
+        axon_dendrite_voice_watch_call_events_json: lib.func("axon_dendrite_voice_watch_call_events_json", bridgeString, ["uint64_t", "str"]),
+        axon_dendrite_voice_create_transport_session_json: lib.func("axon_dendrite_voice_create_transport_session_json", bridgeString, ["uint64_t", "str"]),
+        axon_dendrite_voice_get_transport_session_json: lib.func("axon_dendrite_voice_get_transport_session_json", bridgeString, ["uint64_t", "str"]),
+        axon_dendrite_voice_set_transport_description_json: lib.func("axon_dendrite_voice_set_transport_description_json", bridgeString, ["uint64_t", "str"]),
+        axon_dendrite_voice_add_transport_candidate_json: lib.func("axon_dendrite_voice_add_transport_candidate_json", bridgeString, ["uint64_t", "str"]),
+        axon_dendrite_voice_refresh_transport_lease_json: lib.func("axon_dendrite_voice_refresh_transport_lease_json", bridgeString, ["uint64_t", "str"]),
+        axon_dendrite_voice_end_transport_session_json: lib.func("axon_dendrite_voice_end_transport_session_json", bridgeString, ["uint64_t", "str"]),
+        axon_dendrite_voice_watch_transport_events_json: lib.func("axon_dendrite_voice_watch_transport_events_json", bridgeString, ["uint64_t", "str"]),
+        // Incremental streaming
+        axon_dendrite_server_stream_open_json: optionalJsonFn("axon_dendrite_server_stream_open_json", ["uint64_t", "str"]),
+        axon_dendrite_stream_next_json: optionalJsonFn("axon_dendrite_stream_next_json", ["uint64_t", "str"]),
+        axon_dendrite_stream_close_json: optionalJsonFn("axon_dendrite_stream_close_json", ["uint64_t"]),
+        axon_dendrite_bidi_stream_open_json: optionalJsonFn("axon_dendrite_bidi_stream_open_json", ["uint64_t", "str"]),
+        axon_dendrite_bidi_stream_send_json: optionalJsonFn("axon_dendrite_bidi_stream_send_json", ["uint64_t", "str"]),
+        axon_dendrite_protocol_coverage_json: lib.func("axon_dendrite_protocol_coverage_json", bridgeString, []),
+    };
+}
+export function requireBridgeFn(fn, featureMessage) {
+    if (!fn) {
+        throw new DendriteError(featureMessage);
+    }
+    return fn;
+}
+export function callJson(fn, ...args) {
+    const raw = fn(...args);
+    if (typeof raw !== "string" || raw.length === 0) {
+        throw new DendriteError("dendrite bridge returned empty payload");
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new DendriteError(`dendrite bridge returned invalid JSON: ${err instanceof SyntaxError ? err.message : String(err)}`);
+    }
+    if (!parsed.ok) {
+        throw new DendriteError(String(parsed.error ?? "unknown dendrite bridge error"));
+    }
+    return parsed;
+}

package/src/dendrite_bridge/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./types.js";
+export { DendriteBridge, DendriteServerStream, DendriteBidiStream } from "./bridge.js";
+export { DendriteError } from "./ffi.js";

package/src/dendrite_bridge/index.js

@@ -0,0 +1,25 @@
+// EasyNet Axon for AgentNet
+// =========================
+//
+// File: sdk/node/src/dendrite_bridge/index.ts
+// Description: Barrel re-exports for the dendrite_bridge submodule; gathers types, FFI helpers, and the DendriteBridge class into a single entry point.
+//
+// Protocol Responsibility:
+// - Re-exports the public API surface of the dendrite_bridge submodule.
+//
+// Implementation Approach:
+// - Pure re-exports with no additional logic.
+//
+// Usage Contract:
+// - Import from this module (or from the parent dendrite_bridge.ts barrel) to access all public dendrite_bridge symbols.
+//
+// Architectural Position:
+// - Part of the Node SDK dendrite_bridge submodule layer.
+// - Should not embed logic beyond re-exports.
+//
+// Author: Silan.Hu
+// Email: silan.hu@u.nus.edu
+// Copyright (c) 2026-2027 easynet. All rights reserved.
+export * from "./types.js";
+export { DendriteBridge, DendriteServerStream, DendriteBidiStream } from "./bridge.js";
+export { DendriteError } from "./ffi.js";

package/src/dendrite_bridge/types.d.ts

@@ -0,0 +1,179 @@
+export interface DendriteBridgeOptions {
+    endpoint: string;
+    connectTimeoutMs?: number;
+    libraryPath?: string;
+}
+export interface DendriteUnaryCallOptions {
+    metadata?: Record<string, string>;
+    timeoutMs?: number;
+}
+export interface DendriteAbilityCallOptions extends DendriteUnaryCallOptions {
+    subjectId?: string;
+}
+export interface DendriteStreamCallOptions extends DendriteUnaryCallOptions {
+    maxChunks?: number;
+}
+export interface DendriteClientStreamCallOptions extends DendriteUnaryCallOptions {
+    maxRequestChunks?: number;
+}
+export interface DendriteBidiStreamCallOptions extends DendriteUnaryCallOptions {
+    maxRequestChunks?: number;
+    maxResponseChunks?: number;
+}
+export interface DendriteListNodesOptions {
+    ownerId?: string;
+}
+export interface DendriteRegisterNodeOptions {
+    displayName?: string;
+}
+export interface DendritePublishCapabilityOptions {
+    version: string;
+    digest?: string;
+    signatureBase64: string;
+    tags?: string[];
+    requirements?: Record<string, string>;
+    metadata?: Record<string, string>;
+    payloadUri?: string;
+    payloadSizeBytes?: number;
+    packageBytesBase64?: string;
+    signatureFingerprint?: string;
+    packageFingerprint?: string;
+    publisherKeyVersion?: number;
+}
+export interface DendriteInstallCapabilityOptions {
+    version: string;
+    digest?: string;
+    requireConsent?: boolean;
+    allowTransferredCode?: boolean;
+    executionMode?: string;
+    installTimeoutSeconds?: number;
+    payloadDigest?: string;
+    payloadSizeBytes?: number;
+    signatureFingerprint?: string;
+    packageFingerprint?: string;
+}
+export interface DendriteListA2aAgentsOptions {
+    tags?: string[];
+    ownerId?: string;
+    limit?: number;
+}
+export interface DendriteSendA2aTaskOptions {
+    inputJson?: unknown;
+    inputBase64?: string;
+    taskId?: string;
+    idempotencyKey?: string;
+}
+export interface DendriteDeployMcpListDirOptions {
+    targetPath?: string;
+    commandTemplate?: string;
+    packageId?: string;
+    capabilityName?: string;
+    toolName?: string;
+    version?: string;
+    digest?: string;
+    signatureBase64?: string;
+    packageBytesBase64?: string;
+}
+export interface DendriteListMcpToolsOptions {
+    namePattern?: string;
+    tags?: string[];
+    nodeId?: string;
+}
+export interface DendriteCallMcpToolOptions {
+    targetNodeId?: string;
+    argumentsJson?: unknown;
+    argumentsBase64?: string;
+}
+export interface DendriteUninstallCapabilityOptions {
+    deactivateFirst?: boolean;
+    deactivateReason?: string;
+    force?: boolean;
+}
+export interface DendriteUpdateMcpListDirOptions extends DendriteDeployMcpListDirOptions {
+    existingInstallId?: string;
+    deactivateOld?: boolean;
+    uninstallOld?: boolean;
+    forceUninstall?: boolean;
+    deactivateReason?: string;
+}
+export interface DendriteVoiceCodecProfileOptions {
+    codec?: string;
+    sampleRateHz?: number;
+    channels?: number;
+    ptimeMs?: number;
+    maxBitrateKbps?: number;
+    fecEnabled?: boolean;
+    dtxEnabled?: boolean;
+}
+export interface DendriteVoiceMetricsOptions {
+    rttMs?: number;
+    jitterMs?: number;
+    packetLossRatio?: number;
+    concealedSamples?: number;
+    audioLevelDbov?: number;
+}
+export interface DendriteVoiceDescriptionOptions {
+    sdpType?: number;
+    sdp?: string;
+    updatedAtUnixMs?: number;
+    revisionId?: string;
+}
+export interface DendriteVoiceCandidateOptions {
+    candidate?: string;
+    sdpMid?: string;
+    sdpMlineIndex?: number;
+    usernameFragment?: string;
+    gatheredAtUnixMs?: number;
+}
+export interface DendriteVoiceCreateCallOptions {
+    callId?: string;
+    displayName?: string;
+    participantLimit?: number;
+    preferredCodec?: DendriteVoiceCodecProfileOptions;
+    metadata?: Record<string, string>;
+}
+export interface DendriteVoiceJoinCallOptions {
+    participantId?: string;
+    nodeId?: string;
+    transport?: number;
+    streamSessionId?: string;
+    codecProfile?: DendriteVoiceCodecProfileOptions;
+    muted?: boolean;
+}
+export interface DendriteVoiceUpdateMediaPathOptions {
+    transport?: number;
+    streamSessionId?: string;
+    muted?: boolean;
+}
+export interface DendriteVoiceEndCallOptions {
+    endReason?: number;
+    detail?: string;
+}
+export interface DendriteVoiceWatchOptions {
+    fromSequence?: number;
+    maxEvents?: number;
+    timeoutMs?: number;
+}
+export interface DendriteVoiceCreateTransportSessionOptions {
+    transportSessionId?: string;
+    transport?: number;
+    localDescription?: DendriteVoiceDescriptionOptions;
+    requestedTtlSeconds?: number;
+    metadata?: Record<string, string>;
+}
+export interface DendriteVoiceEndTransportSessionOptions {
+    failed?: boolean;
+    reason?: string;
+}
+export interface DendriteProtocolInvokeOptions {
+    service?: string;
+    rpc?: string;
+    path?: string;
+    requestBytes?: Uint8Array;
+    requestChunks?: Uint8Array[];
+    metadata?: Record<string, string>;
+    timeoutMs?: number;
+    maxChunks?: number;
+    maxRequestChunks?: number;
+    maxResponseChunks?: number;
+}

package/src/dendrite_bridge/types.js

@@ -0,0 +1,23 @@
+// EasyNet Axon for AgentNet
+// =========================
+//
+// File: sdk/node/src/dendrite_bridge/types.ts
+// Description: Exported interface declarations for the DendriteBridge module; extracted from dendrite_bridge.ts to allow type-only imports without circular dependencies.
+//
+// Protocol Responsibility:
+// - Defines the option/contract interfaces used by DendriteBridge methods and consumed by capability_request.ts.
+//
+// Implementation Approach:
+// - Pure type declarations with no runtime code.
+//
+// Usage Contract:
+// - Import types from this module when you need DendriteBridge option shapes without pulling in FFI or class code.
+//
+// Architectural Position:
+// - Part of the Node SDK dendrite_bridge submodule layer.
+// - Should not embed runtime logic or side effects.
+//
+// Author: Silan.Hu
+// Email: silan.hu@u.nus.edu
+// Copyright (c) 2026-2027 easynet. All rights reserved.
+export {};

package/src/dendrite_bridge.d.ts

@@ -0,0 +1 @@
+export * from "./dendrite_bridge/index.js";

package/src/dendrite_bridge.js

@@ -0,0 +1,27 @@
+// EasyNet Axon for AgentNet
+// =========================
+//
+// File: sdk/node/src/dendrite_bridge.ts
+// Description: Source file for Node SDK facade and Dendrite integration; keeps behavior explicit and interoperable across language/runtime boundaries, including tenant/principal invocation context bridging.
+//
+// Protocol Responsibility:
+// - Implements Node SDK facade and Dendrite integration contracts required by current Axon service and SDK surfaces.
+// - Preserves stable request/response semantics and error mapping for dendrite_bridge.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; principal context is optional and, when provided, is mapped to EasyNet subject context.
+// - Errors should be treated as typed protocol/runtime outcomes rather than silently ignored.
+//
+// Architectural Position:
+// - Part of the Node SDK facade and Dendrite integration 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.
+// Barrel re-export — implementation lives in dendrite_bridge/ submodules.
+export * from "./dendrite_bridge/index.js";

package/src/errors.d.ts

@@ -0,0 +1,83 @@
+/** Base error for all Axon SDK errors. */
+export declare class AxonError extends Error {
+    /** Canonical error code for cross-SDK mapping. */
+    readonly code: string;
+    constructor(message: string);
+}
+/** Input validation or configuration error (before any network call). */
+export declare class AxonConfigError extends AxonError {
+    readonly code = "VALIDATION";
+    constructor(message: string);
+}
+/** Native bridge initialization or connection to the Axon runtime failed. */
+export declare class AxonBridgeError extends AxonError {
+    readonly code = "BRIDGE";
+    constructor(message: string);
+}
+/** The requested ability is not installed on the target node. */
+export declare class AxonNotInstalledError extends AxonError {
+    readonly code = "NOT_INSTALLED";
+    constructor(message: string);
+}
+/** The ability is installed but not yet activated. */
+export declare class AxonNotActivatedError extends AxonError {
+    readonly code = "NOT_ACTIVATED";
+    constructor(message: string);
+}
+/**
+ * Remote invocation or deploy operation failed.
+ *
+ * When thrown from a deploy pipeline the optional `trace` field carries the
+ * {@link DeployTrace} collected before the failure, so callers can inspect
+ * per-phase timing even on error:
+ *
+ * ```ts
+ * try { await deployToNode(bridge, tenant, nodeId, desc, sig); }
+ * catch (e) { if (e instanceof AxonInvocationError && e.trace) console.log(e.trace); }
+ * ```
+ */
+export declare class AxonInvocationError extends AxonError {
+    readonly code = "INVOCATION";
+    readonly remotePayload?: Record<string, unknown>;
+    /** Deploy trace collected before the failure (if available). */
+    readonly trace?: unknown;
+    constructor(message: string, remotePayload?: Record<string, unknown>, trace?: unknown);
+}
+/** Streaming transport was interrupted before completion. */
+export declare class AxonStreamError extends AxonError {
+    readonly code = "STREAM";
+    constructor(message: string);
+}
+/** A governance policy rejected the operation. */
+export declare class AxonPolicyDeniedError extends AxonError {
+    readonly code = "POLICY_DENIED";
+    constructor(message: string);
+}
+/** MCP transport or protocol error. */
+export declare class AxonMcpError extends AxonError {
+    readonly code = "MCP";
+    constructor(message: string);
+}
+/** Operation completed with partial failures (e.g. `forgetAll`). */
+export declare class AxonPartialSuccessError extends AxonError {
+    readonly code = "PARTIAL_SUCCESS";
+    readonly succeeded: number;
+    readonly failed: number;
+    readonly details?: unknown;
+    constructor(message: string, succeeded: number, failed: number, details?: unknown);
+}
+/** JSON serialization or deserialization error. */
+export declare class AxonJsonError extends AxonError {
+    readonly code = "JSON";
+    constructor(message: string);
+}
+/** Filesystem or general I/O error. */
+export declare class AxonIoError extends AxonError {
+    readonly code = "IO";
+    constructor(message: string);
+}
+/** A required FFI symbol was not found in the native library. */
+export declare class AxonSymbolNotFoundError extends AxonError {
+    readonly code = "SYMBOL_NOT_FOUND";
+    constructor(message: string);
+}