@aroha-sdk/langchain-bridge 1.0.0

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@aroha-sdk/langchain-bridge",
+  "version": "1.0.0",
+  "description": "Aroha ↔ LangChain/AutoGen/Semantic Kernel bridge — use Aroha as transport for any agent framework",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run --passWithNoTests",
+    "dev": "tsc -p tsconfig.json --watch"
+  },
+  "dependencies": {
+    "@aroha-sdk/core": "^1.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.5",
+    "vitest": "^1.6.0",
+    "@types/node": "^20.14.0"
+  }
+}

package/src/bridge.test.ts

@@ -0,0 +1,257 @@
+import { describe, it, expect, vi } from "vitest";
+import {
+  arohaCapabilityToLangChainTool,
+  arohaCapabilityToOpenAITool,
+  langChainToolsToCapabilities,
+  langChainAgentToArohaProvider,
+} from "./bridge.js";
+import type { LangChainToolLike } from "./types.js";
+import { ArohaClient, ArohaServer, generateDID } from "@aroha-sdk/core";
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+function makeTool(
+  name: string,
+  description = "A test tool",
+  result = "tool result"
+): LangChainToolLike {
+  return {
+    name,
+    description,
+    call: vi.fn().mockResolvedValue(result),
+  };
+}
+
+// ─── langChainToolsToCapabilities ────────────────────────────────────────────
+
+describe("langChainToolsToCapabilities", () => {
+  it("maps each tool to a ArohaCapabilityDescriptor", () => {
+    const tools = [
+      makeTool("search-flights", "Search for available flights"),
+      makeTool("search-hotels", "Search for hotels"),
+    ];
+    const caps = langChainToolsToCapabilities(tools);
+
+    expect(caps).toHaveLength(2);
+    expect(caps[0].capabilityId).toBe("search-flights");
+    expect(caps[0].description).toBe("Search for available flights");
+    expect(caps[1].capabilityId).toBe("search-hotels");
+  });
+
+  it("passes through the tool schema when present", () => {
+    const schema = { type: "object", properties: { q: { type: "string" } } };
+    const tools = [{ name: "search", description: "d", schema, call: vi.fn() }];
+    const caps = langChainToolsToCapabilities(tools);
+    expect(caps[0].inputSchema).toEqual(schema);
+  });
+
+  it("sets inputSchema to undefined when the tool has no schema", () => {
+    const caps = langChainToolsToCapabilities([makeTool("no-schema")]);
+    expect(caps[0].inputSchema).toBeUndefined();
+  });
+
+  it("returns an empty array for an empty tool list", () => {
+    expect(langChainToolsToCapabilities([])).toEqual([]);
+  });
+});
+
+// ─── arohaCapabilityToLangChainTool ────────────────────────────────────────────
+
+describe("arohaCapabilityToLangChainTool", () => {
+  it("returns a tool with the correct name (sanitised to word-chars)", () => {
+    const tool = arohaCapabilityToLangChainTool("search-flights", {
+      endpoint: "http://localhost:3001",
+      agentDID: "did:aroha:remote",
+      callerDID: "did:aroha:caller",
+      callerPrivateKey: new Uint8Array(32),
+      description: "Search flights",
+      client: { send: vi.fn() } as unknown as ArohaClient,
+    });
+    // Hyphens are replaced with underscores by the sanitiser
+    expect(tool.name).toMatch(/^[a-zA-Z0-9_-]+$/);
+  });
+
+  it("returns the provided description", () => {
+    const tool = arohaCapabilityToLangChainTool("cap", {
+      endpoint: "http://localhost:3001",
+      agentDID: "did:aroha:remote",
+      callerDID: "did:aroha:caller",
+      callerPrivateKey: new Uint8Array(32),
+      description: "Does something useful",
+      client: { send: vi.fn() } as unknown as ArohaClient,
+    });
+    expect(tool.description).toBe("Does something useful");
+  });
+
+  it("passes through the schema option", () => {
+    const schema = { type: "object" };
+    const tool = arohaCapabilityToLangChainTool("cap", {
+      endpoint: "http://localhost:3001",
+      agentDID: "did:aroha:remote",
+      callerDID: "did:aroha:caller",
+      callerPrivateKey: new Uint8Array(32),
+      description: "d",
+      schema,
+      client: { send: vi.fn() } as unknown as ArohaClient,
+    });
+    expect(tool.schema).toEqual(schema);
+  });
+
+  it("returns the result string from a successful ArohaResponse", async () => {
+    const identity = await generateDID("caller", "http://localhost:3001");
+    const mockSend = vi.fn().mockResolvedValue({
+      type: "ArohaResponse",
+      body: { capability: "greet", result: { greeting: "hello" } },
+    });
+
+    const tool = arohaCapabilityToLangChainTool("greet", {
+      endpoint: "http://localhost:3002",
+      agentDID: "did:aroha:remote",
+      callerDID: identity.did,
+      callerPrivateKey: identity.privateKey,
+      description: "Greet",
+      client: { send: mockSend } as unknown as ArohaClient,
+    });
+
+    const result = await tool.call({ name: "World" });
+    expect(result).toBe(JSON.stringify({ greeting: "hello" }));
+    expect(mockSend).toHaveBeenCalledTimes(1);
+  });
+
+  it("returns a plain string result as-is", async () => {
+    const identity = await generateDID("caller", "http://localhost:3001");
+    const mockSend = vi.fn().mockResolvedValue({
+      type: "ArohaResponse",
+      body: { capability: "echo", result: "pong" },
+    });
+
+    const tool = arohaCapabilityToLangChainTool("echo", {
+      endpoint: "http://localhost:3002",
+      agentDID: "did:aroha:remote",
+      callerDID: identity.did,
+      callerPrivateKey: identity.privateKey,
+      description: "Echo",
+      client: { send: mockSend } as unknown as ArohaClient,
+    });
+
+    const result = await tool.call("{}");
+    expect(result).toBe("pong");
+  });
+
+  it("throws when the response is a ArohaError", async () => {
+    const identity = await generateDID("caller", "http://localhost:3001");
+    const mockSend = vi.fn().mockResolvedValue({
+      type: "ArohaError",
+      body: { code: "Aroha_UNKNOWN_CAPABILITY", message: "No such capability" },
+    });
+
+    const tool = arohaCapabilityToLangChainTool("missing-cap", {
+      endpoint: "http://localhost:3002",
+      agentDID: "did:aroha:remote",
+      callerDID: identity.did,
+      callerPrivateKey: identity.privateKey,
+      description: "d",
+      client: { send: mockSend } as unknown as ArohaClient,
+    });
+
+    await expect(tool.call({})).rejects.toThrow("No such capability");
+  });
+
+  it("throws when the client returns no response", async () => {
+    const identity = await generateDID("caller", "http://localhost:3001");
+    const mockSend = vi.fn().mockResolvedValue(null);
+
+    const tool = arohaCapabilityToLangChainTool("cap", {
+      endpoint: "http://localhost:3002",
+      agentDID: "did:aroha:remote",
+      callerDID: identity.did,
+      callerPrivateKey: identity.privateKey,
+      description: "d",
+      client: { send: mockSend } as unknown as ArohaClient,
+    });
+
+    await expect(tool.call({})).rejects.toThrow(/No response/);
+  });
+
+  it("accepts string input and parses it as JSON", async () => {
+    const identity = await generateDID("caller", "http://localhost:3001");
+    const mockSend = vi.fn().mockResolvedValue({
+      type: "ArohaResponse",
+      body: { capability: "cap", result: { ok: true } },
+    });
+
+    const tool = arohaCapabilityToLangChainTool("cap", {
+      endpoint: "http://localhost:3002",
+      agentDID: "did:aroha:remote",
+      callerDID: identity.did,
+      callerPrivateKey: identity.privateKey,
+      description: "d",
+      client: { send: mockSend } as unknown as ArohaClient,
+    });
+
+    await tool.call('{"key":"value"}');
+    // Should not throw — the string input is parsed and used as params
+    expect(mockSend).toHaveBeenCalledTimes(1);
+  });
+});
+
+// ─── arohaCapabilityToOpenAITool ───────────────────────────────────────────────
+
+describe("arohaCapabilityToOpenAITool", () => {
+  it("returns an OpenAI-shaped function tool", () => {
+    const tool = arohaCapabilityToOpenAITool("greet", {
+      endpoint: "http://localhost:3002",
+      agentDID: "did:aroha:remote",
+      callerDID: "did:aroha:caller",
+      callerPrivateKey: new Uint8Array(32),
+      description: "Greet a user",
+      client: { send: vi.fn() } as unknown as ArohaClient,
+    });
+
+    expect(tool.type).toBe("function");
+    expect(tool.function).toBeDefined();
+    expect(tool.function.description).toBe("Greet a user");
+    expect(typeof tool.invoke).toBe("function");
+  });
+
+  it("invoke() parses a JSON string result back to an object", async () => {
+    const identity = await generateDID("caller", "http://localhost:3001");
+    const mockSend = vi.fn().mockResolvedValue({
+      type: "ArohaResponse",
+      body: { capability: "greet", result: { msg: "hi" } },
+    });
+
+    const tool = arohaCapabilityToOpenAITool("greet", {
+      endpoint: "http://localhost:3002",
+      agentDID: "did:aroha:remote",
+      callerDID: identity.did,
+      callerPrivateKey: identity.privateKey,
+      description: "d",
+      client: { send: mockSend } as unknown as ArohaClient,
+    });
+
+    const result = await tool.invoke({ name: "World" });
+    expect(result).toEqual({ msg: "hi" });
+  });
+});
+
+// ─── langChainAgentToArohaProvider ─────────────────────────────────────────────
+
+describe("langChainAgentToArohaProvider", () => {
+  it("returns a ArohaServer instance without starting it", async () => {
+    const identity = await generateDID("lc-bridge", "http://localhost:3099");
+
+    const server = langChainAgentToArohaProvider(
+      [makeTool("search-flights"), makeTool("book-hotel")],
+      {
+        agentDID: identity.did,
+        agentPrivateKey: identity.privateKey,
+        port: 3099,
+        didDocument: identity.document,
+        resolvePublicKey: async () => null,
+      }
+    );
+
+    expect(server).toBeInstanceOf(ArohaServer);
+  });
+});

package/src/bridge.ts

@@ -0,0 +1,220 @@
+/**
+ * Aroha ↔ LangChain/AutoGen Bridge
+ *
+ * Aroha is the transport and identity layer. Your existing agent framework
+ * (LangChain, AutoGen, Semantic Kernel, LlamaIndex) keeps its reasoning,
+ * memory, and tool-calling logic unchanged.
+ *
+ * This bridge lets you:
+ *   1. Expose LangChain tools as Aroha capabilities (so other Aroha agents
+ *      can discover and call your tools with signed envelopes).
+ *   2. Wrap Aroha capabilities as LangChain tools (so your LangChain agent
+ *      can call remote Aroha agents transparently).
+ */
+
+import {
+  ArohaClient,
+  ArohaServer,
+  buildEnvelope,
+  newCorrelationId,
+  type ArohaEnvelope,
+  type ArohaServerOptions,
+  type MessageHandler,
+  type ArohaRequestBody,
+  type ArohaResponseBody,
+} from "@aroha-sdk/core";
+import {
+  type LangChainToolLike,
+  type OpenAIFunctionLike,
+  type ArohaCapabilityDescriptor,
+} from "./types.js";
+
+// ─── Aroha capability → LangChain tool ────────────────────────────────────────
+
+export interface ArohaCapabilityToToolOptions {
+  /** The Aroha endpoint URL of the remote agent. */
+  endpoint: string;
+  /** The DID of the remote agent (the "to" field). */
+  agentDID: string;
+  /** DID of the calling agent (the "from" field). */
+  callerDID: string;
+  /** Ed25519 private key of the calling agent for signing envelopes. */
+  callerPrivateKey: Uint8Array;
+  /** Human-readable description used by the LLM to decide when to call this tool. */
+  description: string;
+  /** JSON Schema for the capability's params. Optional. */
+  schema?: Record<string, unknown>;
+  client?: ArohaClient;
+}
+
+/**
+ * Wrap a single Aroha capability as a LangChain-compatible tool.
+ *
+ * The returned tool sends a signed ArohaRequest to the remote agent and
+ * returns the JSON-serialised result as a string (what LangChain expects).
+ */
+export function arohaCapabilityToLangChainTool(
+  capabilityId: string,
+  opts: ArohaCapabilityToToolOptions
+): LangChainToolLike {
+  const client = opts.client ?? new ArohaClient();
+
+  return {
+    name: capabilityId.replace(/[^a-zA-Z0-9_-]/g, "_"),
+    description: opts.description,
+    schema: opts.schema,
+
+    async call(input: string | Record<string, unknown>): Promise<string> {
+      const params: Record<string, unknown> =
+        typeof input === "string" ? JSON.parse(input) : input;
+
+      const body: ArohaRequestBody = { capability: capabilityId, params };
+      const correlationId = newCorrelationId();
+      const envelope = await buildEnvelope(
+        "ArohaRequest",
+        opts.callerDID,
+        opts.agentDID,
+        body,
+        correlationId,
+        opts.callerPrivateKey
+      );
+
+      const response = await client.send(opts.endpoint, envelope);
+      if (!response) throw new Error(`No response from ${opts.agentDID}`);
+      if (response.type === "ArohaError") {
+        throw new Error((response.body as { message: string }).message);
+      }
+
+      const result = (response.body as ArohaResponseBody).result;
+      return typeof result === "string" ? result : JSON.stringify(result);
+    },
+  };
+}
+
+/**
+ * Wrap a single Aroha capability as an OpenAI function tool.
+ * Compatible with AutoGen, Semantic Kernel, and GPT-4 tool calling.
+ */
+export function arohaCapabilityToOpenAITool(
+  capabilityId: string,
+  opts: ArohaCapabilityToToolOptions
+): OpenAIFunctionLike {
+  const langChainTool = arohaCapabilityToLangChainTool(capabilityId, opts);
+  return {
+    type: "function",
+    function: {
+      name: langChainTool.name,
+      description: langChainTool.description,
+      parameters: opts.schema,
+    },
+    async invoke(args: Record<string, unknown>): Promise<unknown> {
+      const result = await langChainTool.call(args);
+      try { return JSON.parse(result); } catch { return result; }
+    },
+  };
+}
+
+// ─── LangChain tools → Aroha provider ─────────────────────────────────────────
+
+export interface LangChainAgentToArohaOptions {
+  agentDID: string;
+  agentPrivateKey: Uint8Array;
+  port: number;
+  resolvePublicKey: ArohaServerOptions["resolvePublicKey"];
+  didDocument: ArohaServerOptions["didDocument"];
+}
+
+/**
+ * Expose a set of LangChain tools as a Aroha provider agent.
+ *
+ * Each tool becomes a Aroha capability. Inbound ArohaRequest envelopes are
+ * routed to the matching tool. The tool's string result is returned as a
+ * ArohaResponse.
+ *
+ * Returns the ArohaServer — call .start() to begin accepting connections.
+ */
+export function langChainAgentToArohaProvider(
+  tools: LangChainToolLike[],
+  opts: LangChainAgentToArohaOptions
+): ArohaServer {
+  const toolMap = new Map(tools.map((t) => [t.name, t]));
+
+  const onMessage: MessageHandler = async (envelope, respond) => {
+    if (envelope.type !== "ArohaRequest") return;
+
+    const body = envelope.body as ArohaRequestBody;
+    const tool = toolMap.get(body.capability);
+
+    if (!tool) {
+      const errEnvelope = await buildEnvelope(
+        "ArohaError",
+        opts.agentDID,
+        envelope.from,
+        {
+          code: "Aroha_UNKNOWN_CAPABILITY" as never,
+          message: `Unknown capability: ${body.capability}`,
+          retryable: false,
+        },
+        envelope.correlationId,
+        opts.agentPrivateKey
+      );
+      respond(errEnvelope);
+      return;
+    }
+
+    try {
+      const rawResult = await tool.call(body.params);
+      let result: Record<string, unknown>;
+      try { result = JSON.parse(rawResult); } catch { result = { output: rawResult }; }
+
+      const responseBody: ArohaResponseBody = { capability: body.capability, result };
+      const reply = await buildEnvelope(
+        "ArohaResponse",
+        opts.agentDID,
+        envelope.from,
+        responseBody,
+        envelope.correlationId,
+        opts.agentPrivateKey
+      );
+      respond(reply);
+    } catch (err) {
+      const errEnvelope = await buildEnvelope(
+        "ArohaError",
+        opts.agentDID,
+        envelope.from,
+        {
+          code: "Aroha_INTERNAL_ERROR" as never,
+          message: String(err),
+          retryable: true,
+        },
+        envelope.correlationId,
+        opts.agentPrivateKey
+      );
+      respond(errEnvelope);
+    }
+  };
+
+  return new ArohaServer({
+    agentDID: opts.agentDID,
+    didDocument: opts.didDocument,
+    port: opts.port,
+    onMessage,
+    resolvePublicKey: opts.resolvePublicKey,
+  });
+}
+
+// ─── Describe Aroha capabilities ──────────────────────────────────────────────
+
+/**
+ * Convert a LangChain tool list to Aroha capability descriptors.
+ * Use these to register the agent in InMemoryRegistry or ArohaRegistry.
+ */
+export function langChainToolsToCapabilities(
+  tools: LangChainToolLike[]
+): ArohaCapabilityDescriptor[] {
+  return tools.map((t) => ({
+    capabilityId: t.name,
+    description: t.description,
+    inputSchema: t.schema,
+  }));
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from "./types.js";
+export * from "./bridge.js";

package/src/types.ts

@@ -0,0 +1,39 @@
+/**
+ * Duck-typed interfaces for LangChain, AutoGen, and Semantic Kernel tools.
+ *
+ * These interfaces are intentionally minimal — they match the public API surface
+ * that matters for Aroha bridging without requiring a hard dependency on any
+ * specific framework version.
+ */
+
+// ─── LangChain / LangGraph style ─────────────────────────────────────────────
+
+export interface LangChainToolLike {
+  name: string;
+  description: string;
+  /** JSON Schema for the tool's input. Optional — used for agent auto-binding. */
+  schema?: Record<string, unknown>;
+  /** Invoke the tool. Input may be a JSON string or an object. */
+  call(input: string | Record<string, unknown>): Promise<string>;
+}
+
+// ─── OpenAI function / tool style (AutoGen, Semantic Kernel, GPT-4 tools) ────
+
+export interface OpenAIFunctionLike {
+  type: "function";
+  function: {
+    name: string;
+    description: string;
+    parameters?: Record<string, unknown>;
+  };
+  /** Invoke the function. */
+  invoke(args: Record<string, unknown>): Promise<unknown>;
+}
+
+// ─── Aroha capability descriptor (for converting tools → Aroha capabilities) ───
+
+export interface ArohaCapabilityDescriptor {
+  capabilityId: string;
+  description: string;
+  inputSchema?: Record<string, unknown>;
+}

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist",
+    "declarationDir": "dist"
+  },
+  "include": ["src/**/*"]
+}