@easynet-run/node 0.27.14

package/src/tool_adapter.d.ts

@@ -0,0 +1,90 @@
+import type { Transport, JsonValue } from "./index.js";
+export interface ToolParameters {
+    type: "object";
+    properties: Record<string, JsonValue>;
+    required?: string[];
+    [key: string]: JsonValue | undefined;
+}
+export interface ToolSpec {
+    name: string;
+    description: string;
+    resourceUri: string;
+    parameters: ToolParameters;
+}
+export interface OpenAITool {
+    type: "function";
+    name: string;
+    description: string;
+    parameters: ToolParameters;
+}
+export interface OpenAIChatTool {
+    type: "function";
+    function: {
+        name: string;
+        description: string;
+        parameters: ToolParameters;
+    };
+}
+export interface AnthropicTool {
+    name: string;
+    description: string;
+    input_schema: ToolParameters;
+}
+export interface ToolDict {
+    name: string;
+    description: string;
+    resource_uri: string;
+    parameters: ToolParameters;
+}
+export type LocalHandler = (args: Record<string, JsonValue>) => JsonValue | Promise<JsonValue>;
+export interface RegisterOptions {
+    description?: string;
+    resourceUri?: string;
+    parameters?: ToolParameters;
+}
+export interface AbilityToolAdapterOptions {
+    principalId?: string;
+}
+export declare class AbilityToolAdapter {
+    readonly tenantId: string;
+    private readonly transport;
+    private readonly principalId;
+    private readonly _specs;
+    private readonly localHandlers;
+    private fallbackTransport;
+    constructor(tenantId: string, transport?: Transport, options?: AbilityToolAdapterOptions);
+    /**
+     * Register a local handler function as both a tool definition and executor.
+     * When {@link execute} is called, the local handler runs directly (no network round-trip).
+     */
+    register(name: string, handler: LocalHandler, options?: RegisterOptions): this;
+    /**
+     * Register a remote ability as a tool (no local handler — calls go over the network).
+     */
+    registerAbility(name: string, resourceUri: string, options?: {
+        description?: string;
+        parameters?: ToolParameters;
+    }): this;
+    specs(): ToolSpec[];
+    asOpenAITools(names?: string[]): OpenAITool[];
+    asOpenAIChatTools(names?: string[]): OpenAIChatTool[];
+    asAnthropicTools(names?: string[]): AnthropicTool[];
+    asDicts(names?: string[]): ToolDict[];
+    private iterSpecs;
+    /**
+     * Execute a tool call by name.
+     *
+     * If a local handler was registered, it is called directly.
+     * Otherwise the call is dispatched to the remote ability via the transport.
+     */
+    execute(name: string, args: Record<string, JsonValue> | string): Promise<JsonValue>;
+    /**
+     * Execute and return the result as a JSON string (convenience for LLM output construction).
+     */
+    executeToJson(name: string, args: Record<string, JsonValue> | string): Promise<string>;
+    /**
+     * Close the internally cached fallback transport (if any).
+     * Call this when the adapter is no longer needed to release native resources.
+     */
+    close(): void;
+}

package/src/tool_adapter.js

@@ -0,0 +1,169 @@
+// EasyNet Axon for AgentNet
+// =========================
+//
+// File: sdk/node/src/tool_adapter.ts
+// Description: Tool adapter that bridges LLM tool-call interfaces (OpenAI, Anthropic, etc.) with Axon ability invocations; enables abilities to be used as native LLM tools without protocol knowledge.
+//
+// Protocol Responsibility:
+// - Converts between LLM tool-call schemas (OpenAI function-calling, Anthropic tool-use) and Axon ability request/response envelopes.
+// - Preserves ability identity via resource URI mapping and invocation semantics.
+//
+// Implementation Approach:
+// - Uses explicit ToolSpec registration with JSON Schema parameters.
+// - Provides format-specific output (OpenAI, Anthropic, generic) from a unified ToolSpec model.
+// - Delegates execution to the existing Client/Transport layer.
+//
+// Usage Contract:
+// - Callers register abilities with schema metadata, then export tool definitions for their LLM of choice.
+// - Execution dispatch routes tool calls back through the Axon ability invoke path.
+//
+// Architectural Position:
+// - Sits above the Client/Transport facade; does not touch DendriteBridge directly.
+// - Should not embed LLM-specific conversation logic beyond schema translation.
+//
+// Author: Silan.Hu
+// Email: silan.hu@u.nus.edu
+// Copyright (c) 2026-2027 easynet. All rights reserved.
+function specToOpenAI(spec) {
+    return {
+        type: "function",
+        name: spec.name,
+        description: spec.description,
+        parameters: spec.parameters,
+    };
+}
+function specToOpenAIChat(spec) {
+    return {
+        type: "function",
+        function: {
+            name: spec.name,
+            description: spec.description,
+            parameters: spec.parameters,
+        },
+    };
+}
+function specToAnthropic(spec) {
+    return {
+        name: spec.name,
+        description: spec.description,
+        input_schema: spec.parameters,
+    };
+}
+function specToDict(spec) {
+    return {
+        name: spec.name,
+        description: spec.description,
+        resource_uri: spec.resourceUri,
+        parameters: spec.parameters,
+    };
+}
+export class AbilityToolAdapter {
+    tenantId;
+    transport;
+    principalId;
+    _specs = new Map();
+    localHandlers = new Map();
+    fallbackTransport;
+    constructor(tenantId, transport, options = {}) {
+        this.tenantId = tenantId;
+        this.transport = transport;
+        this.principalId = options.principalId;
+    }
+    // -- Registration -------------------------------------------------------
+    /**
+     * Register a local handler function as both a tool definition and executor.
+     * When {@link execute} is called, the local handler runs directly (no network round-trip).
+     */
+    register(name, handler, options = {}) {
+        const spec = {
+            name,
+            description: options.description ?? "",
+            resourceUri: options.resourceUri ?? `easynet:///r/org/${name}`,
+            parameters: options.parameters ?? { type: "object", properties: {} },
+        };
+        this._specs.set(name, spec);
+        this.localHandlers.set(name, handler);
+        return this;
+    }
+    /**
+     * Register a remote ability as a tool (no local handler — calls go over the network).
+     */
+    registerAbility(name, resourceUri, options = {}) {
+        const spec = {
+            name,
+            description: options.description ?? "",
+            resourceUri,
+            parameters: options.parameters ?? { type: "object", properties: {} },
+        };
+        this._specs.set(name, spec);
+        this.localHandlers.delete(name);
+        return this;
+    }
+    // -- Export --------------------------------------------------------------
+    specs() {
+        return [...this._specs.values()];
+    }
+    asOpenAITools(names) {
+        return this.iterSpecs(names).map(specToOpenAI);
+    }
+    asOpenAIChatTools(names) {
+        return this.iterSpecs(names).map(specToOpenAIChat);
+    }
+    asAnthropicTools(names) {
+        return this.iterSpecs(names).map(specToAnthropic);
+    }
+    asDicts(names) {
+        return this.iterSpecs(names).map(specToDict);
+    }
+    iterSpecs(names) {
+        if (!names)
+            return [...this._specs.values()];
+        return names.filter((n) => this._specs.has(n)).map((n) => this._specs.get(n));
+    }
+    // -- Execution -----------------------------------------------------------
+    /**
+     * Execute a tool call by name.
+     *
+     * If a local handler was registered, it is called directly.
+     * Otherwise the call is dispatched to the remote ability via the transport.
+     */
+    async execute(name, args) {
+        const parsed = typeof args === "string" ? JSON.parse(args) : args;
+        // Local handler path
+        const handler = this.localHandlers.get(name);
+        if (handler) {
+            return handler(parsed);
+        }
+        // Remote ability path
+        const spec = this._specs.get(name);
+        if (!spec) {
+            throw new Error(`unknown tool: ${name}`);
+        }
+        // Lazy import to avoid loading koffi/DendriteBridge when only using local handlers
+        if (!this.transport && !this.fallbackTransport) {
+            const { SidecarTransport } = await import("./index.js");
+            this.fallbackTransport = new SidecarTransport();
+        }
+        const transport = this.transport ?? this.fallbackTransport;
+        const { Client } = await import("./index.js");
+        const client = new Client(transport, this.tenantId, spec.resourceUri, this.principalId ?? "");
+        return client.call(parsed);
+    }
+    /**
+     * Execute and return the result as a JSON string (convenience for LLM output construction).
+     */
+    async executeToJson(name, args) {
+        const result = await this.execute(name, args);
+        return JSON.stringify(result);
+    }
+    /**
+     * Close the internally cached fallback transport (if any).
+     * Call this when the adapter is no longer needed to release native resources.
+     */
+    close() {
+        if (this.fallbackTransport && "close" in this.fallbackTransport) {
+            this.fallbackTransport.close();
+            this.fallbackTransport = undefined;
+        }
+    }
+}