kompass-sdk 0.1.0

package/scripts/bootstrap-agents.mjs

@@ -0,0 +1,246 @@
+import "dotenv/config";
+import { createPublicClient, createWalletClient, http } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+import { baseSepolia } from "viem/chains";
+
+const PROVIDER_NODE = "0x5911e072e7bfa6e0e7b169372a608d2418d358dcb44de82c3e98f339c02346de";
+const EVALUATOR_NODE = "0x475c4b427ef8efb13b7107f791462e2d5a0ebd0e325215c29049d875e83d05d0";
+
+const resolverAbi = [
+  {
+    type: "function",
+    name: "setText",
+    stateMutability: "nonpayable",
+    inputs: [
+      { name: "node", type: "bytes32" },
+      { name: "key", type: "string" },
+      { name: "value", type: "string" },
+    ],
+    outputs: [],
+  },
+] ;
+
+const registryAbi = [
+  {
+    type: "function",
+    name: "isRegistered",
+    stateMutability: "view",
+    inputs: [{ name: "agent", type: "address" }],
+    outputs: [{ name: "", type: "bool" }],
+  },
+  {
+    type: "function",
+    name: "registerAgent",
+    stateMutability: "nonpayable",
+    inputs: [{ name: "ensNode", type: "bytes32" }],
+    outputs: [],
+  },
+] ;
+
+function requireEnv(name) {
+  const value = process.env[name];
+  if (!value) {
+    throw new Error(`Missing required environment variable: ${name}`);
+  }
+  return value;
+}
+
+function createClients(privateKey, rpcUrl) {
+  const account = privateKeyToAccount(privateKey);
+  return {
+    account,
+    publicClient: createPublicClient({
+      chain: baseSepolia,
+      transport: http(rpcUrl),
+    }),
+    walletClient: createWalletClient({
+      account,
+      chain: baseSepolia,
+      transport: http(rpcUrl),
+    }),
+  };
+}
+
+async function writeContractWithNonce({
+  publicClient,
+  walletClient,
+  nonceState,
+  request,
+}) {
+  const hash = await walletClient.writeContract({
+    ...request,
+    nonce: nonceState.value,
+  });
+  nonceState.value += 1;
+  await publicClient.waitForTransactionReceipt({ hash });
+  return hash;
+}
+
+async function writeTextRecords({ label, node, resolverAddress, records, publicClient, walletClient, nonceState }) {
+  for (const [key, value] of records) {
+    if (!value) {
+      continue;
+    }
+
+    const hash = await writeContractWithNonce({
+      publicClient,
+      walletClient,
+      nonceState,
+      request: {
+        address: resolverAddress,
+        abi: resolverAbi,
+        functionName: "setText",
+        args: [node, key, value],
+      },
+    });
+    console.log(`${label}: set ${key} (${hash})`);
+  }
+}
+
+async function ensureRegistered({ label, node, registryAddress, publicClient, walletClient, account, nonceState }) {
+  const isRegistered = await publicClient.readContract({
+    address: registryAddress,
+    abi: registryAbi,
+    functionName: "isRegistered",
+    args: [account.address],
+  });
+
+  if (isRegistered) {
+    console.log(`${label}: already registered (${account.address})`);
+    return;
+  }
+
+  const hash = await writeContractWithNonce({
+    publicClient,
+    walletClient,
+    nonceState,
+    request: {
+      address: registryAddress,
+      abi: registryAbi,
+      functionName: "registerAgent",
+      args: [node],
+    },
+  });
+  console.log(`${label}: registered (${hash})`);
+}
+
+async function bootstrapAgent({ label, privateKey, node, profile, resolverAddress, registryAddress, rpcUrl }) {
+  const { account, publicClient, walletClient } = createClients(privateKey, rpcUrl);
+  const nonceState = {
+    value: await publicClient.getTransactionCount({
+      address: account.address,
+      blockTag: "pending",
+    }),
+  };
+  const verificationKey = `agent-registration[${registryAddress.toLowerCase()}][${account.address.toLowerCase()}]`;
+  const records = [
+    ["com.kompass.identity.name", profile.ensName],
+    ["com.kompass.type", profile.agentType],
+    ["com.kompass.categories", profile.categories],
+    ["com.kompass.erc8004.id", profile.erc8004Id],
+    ["com.kompass.identity.verification", verificationKey],
+    [verificationKey, "verified"],
+    ["com.kompass.payment.mode", profile.paymentMode],
+    ["com.kompass.pricing.model", profile.pricingModel],
+    ["com.kompass.pricing.rate", profile.pricingRate],
+    ["com.kompass.pricing.token", profile.pricingToken],
+    ["com.kompass.endpoint.mcp", profile.endpointMcp],
+    ["com.kompass.endpoint.a2a", profile.endpointA2a],
+    ["com.kompass.endpoint.x402", profile.endpointX402],
+    ["com.kompass.evaluator.domains", profile.evaluatorDomains],
+    ["com.kompass.description", profile.description],
+  ];
+
+  console.log(`${label}: bootstrapping ${account.address}`);
+  await writeTextRecords({
+    label,
+    node,
+    resolverAddress,
+    records,
+    publicClient,
+    walletClient,
+    nonceState,
+  });
+  await ensureRegistered({
+    label,
+    node,
+    registryAddress,
+    publicClient,
+    walletClient,
+    account,
+    nonceState,
+  });
+}
+
+async function main() {
+  const selection = process.argv
+    .find((arg) => arg.startsWith("--agent="))
+    ?.split("=")[1];
+  const rpcUrl = requireEnv("BASE_SEPOLIA_RPC");
+  const registryAddress = requireEnv("REGISTRY_ADDRESS");
+  const resolverAddress = requireEnv("ENS_L2_RESOLVER");
+  const usdcAddress = requireEnv("USDC_ADDRESS");
+  const providerKey = requireEnv("AGENT_A_PRIVATE_KEY");
+  const evaluatorKey = requireEnv("AGENT_B_PRIVATE_KEY");
+
+  const agents = [
+    {
+      label: "provider",
+      privateKey: providerKey,
+      node: PROVIDER_NODE,
+      profile: {
+        ensName: "kompassprovider.base.eth",
+        agentType: "provider",
+        categories: "defi,analytics,research,yield,data,signals,swap",
+        erc8004Id: "",
+        paymentMode: "hybrid",
+        pricingModel: "fixed",
+        pricingRate: "500000",
+        pricingToken: usdcAddress,
+        endpointMcp: "",
+        endpointA2a: "",
+        endpointX402: "",
+        evaluatorDomains: "",
+        description: "Kompass DeFi strategy, premium data, and execution provider on Base.",
+      },
+    },
+    {
+      label: "evaluator",
+      privateKey: evaluatorKey,
+      node: EVALUATOR_NODE,
+      profile: {
+        ensName: "kompassevaluator.base.eth",
+        agentType: "evaluator",
+        categories: "risk,security,defi,evaluation",
+        erc8004Id: "",
+        paymentMode: "escrow",
+        pricingModel: "fixed",
+        pricingRate: "300000",
+        pricingToken: usdcAddress,
+        endpointMcp: "",
+        endpointA2a: "",
+        endpointX402: "",
+        evaluatorDomains: "yield-risk,execution-safety,data-quality",
+        description: "Kompass evaluator for DeFi risk, execution safety, and data quality.",
+      },
+    },
+  ];
+
+  for (const agent of agents) {
+    if (selection && selection !== agent.label) {
+      continue;
+    }
+
+    await bootstrapAgent({
+      ...agent,
+      resolverAddress,
+      registryAddress,
+      rpcUrl,
+    });
+  }
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : error);
+  process.exitCode = 1;
+});

package/src/a2a/agent-card.ts

@@ -0,0 +1,66 @@
+/**
+ * Kompass Agent Card Generator
+ * Creates an A2A-compatible agent card for Kompass discovery + coordination
+ */
+
+import type { AgentCard } from "@a2a-js/sdk";
+
+export interface KompassAgentCardOptions {
+  url: string;
+  name?: string;
+  description?: string;
+  version?: string;
+}
+
+export function createKompassAgentCard(options: KompassAgentCardOptions): AgentCard {
+  return {
+    name: options.name ?? "Kompass",
+    description:
+      options.description ??
+      "Universal agent discovery + coordination. Searches ACP, MCP, x402, ERC-8004, A2A, L402 registries in one query. Bridges non-A2A agents to A2A protocol.",
+    url: options.url,
+    provider: {
+      organization: "Kompass Protocol",
+      url: "https://github.com/kompass-protocol",
+    },
+    version: options.version ?? "1.0.0",
+    capabilities: {
+      streaming: true,
+      pushNotifications: false,
+    },
+    skills: [
+      {
+        id: "universal-discovery",
+        name: "Universal Agent Discovery",
+        description:
+          "Search for agents across 8+ registries (ACP, MCP Registry, ERC-8004, x402, A2A, L402, ADP). Returns ranked results with reputation scores.",
+        inputModes: ["text"],
+        outputModes: ["text", "data"],
+      },
+      {
+        id: "cross-protocol-hire",
+        name: "Cross-Protocol Agent Hiring",
+        description:
+          "Hire any agent regardless of protocol. Kompass bridges ACP, x402, MCP, and A2A automatically.",
+        inputModes: ["text"],
+        outputModes: ["text", "data"],
+      },
+      {
+        id: "multi-agent-coordination",
+        name: "Multi-Agent Coordination",
+        description:
+          "Coordinate multiple agents across different protocols into a pipeline. Discovers agents, assigns roles, manages task dependencies.",
+        inputModes: ["text"],
+        outputModes: ["text", "data"],
+      },
+      {
+        id: "reputation-check",
+        name: "Agent Reputation Check",
+        description:
+          "Check an agent's on-chain reputation via ERC-8004. Aggregates trust signals across protocols.",
+        inputModes: ["text"],
+        outputModes: ["data"],
+      },
+    ],
+  } as AgentCard;
+}

package/src/a2a/bridge.ts

@@ -0,0 +1,168 @@
+/**
+ * Kompass A2A Bridge
+ * Translates between A2A tasks and non-A2A protocols (ACP, x402, MCP)
+ * Makes every agent A2A-compatible through Kompass
+ */
+
+import type { UnifiedAgent } from "../sources/types.js";
+import { KompassA2AClient, type A2ATaskResult } from "./client.js";
+import { ProtocolBridge } from "../bridge.js";
+
+export class A2ABridge {
+  private a2aClient: KompassA2AClient;
+  private protocolBridge: ProtocolBridge;
+
+  constructor(protocolBridge: ProtocolBridge) {
+    this.a2aClient = new KompassA2AClient();
+    this.protocolBridge = protocolBridge;
+  }
+
+  /**
+   * Send a task to any agent, regardless of protocol.
+   * If A2A-native → direct A2A task
+   * If not → bridge through protocol-specific path, wrap result as A2A
+   */
+  async sendTask(agent: UnifiedAgent, task: string, contextId?: string): Promise<A2ATaskResult> {
+    // Check if agent has an A2A endpoint
+    if (agent.protocol === "a2a" && agent.endpoints.a2a) {
+      // Direct A2A communication
+      return this.a2aClient.sendTask({
+        agentUrl: agent.endpoints.a2a,
+        message: task,
+        contextId,
+      });
+    }
+
+    // Bridge non-A2A agents
+    const bridgeResult = await this.protocolBridge.hire(agent, { task });
+
+    // Wrap the result as an A2A-compatible response
+    return {
+      taskId: bridgeResult.jobId ?? `kompass-bridge-${Date.now()}`,
+      state: bridgeResult.success ? "completed" : "failed",
+      artifacts: bridgeResult.deliverable
+        ? [
+            {
+              type: "data",
+              parts: [
+                {
+                  type: "text",
+                  text:
+                    typeof bridgeResult.deliverable === "string"
+                      ? bridgeResult.deliverable
+                      : JSON.stringify(bridgeResult.deliverable),
+                },
+              ],
+              metadata: {
+                bridgedFrom: agent.protocol,
+                source: agent.source,
+                agentName: agent.name,
+                txHash: bridgeResult.txHash,
+              },
+            },
+          ]
+        : [],
+      messages: [],
+      error: bridgeResult.error,
+    };
+  }
+
+  /**
+   * Coordinate a multi-step pipeline across protocols.
+   * Each step: discover → send task (A2A or bridged) → pass result to next step.
+   */
+  async coordinate(
+    steps: CoordinationStep[],
+    findAgent: (query: string) => Promise<UnifiedAgent | null>
+  ): Promise<CoordinationResult> {
+    const results: StepResult[] = [];
+    const context = new Map<string, unknown>();
+
+    for (const step of steps) {
+      // Wait for dependencies
+      if (step.dependsOn) {
+        const depResult = results.find((r) => r.stepId === step.dependsOn);
+        if (depResult && !depResult.success) {
+          results.push({
+            stepId: step.id,
+            role: step.role,
+            success: false,
+            error: `Dependency "${step.dependsOn}" failed`,
+            skipped: true,
+          });
+          continue;
+        }
+      }
+
+      // Find agent for this step
+      const agent = step.agent ?? (await findAgent(step.query ?? step.role));
+      if (!agent) {
+        results.push({
+          stepId: step.id,
+          role: step.role,
+          success: false,
+          error: `No agent found for role: ${step.role}`,
+          skipped: true,
+        });
+        continue;
+      }
+
+      // Build task with context from previous steps
+      let taskMessage = step.task ?? step.query ?? step.role;
+      if (step.dependsOn && context.has(step.dependsOn)) {
+        const prevData = context.get(step.dependsOn);
+        taskMessage += `\n\nContext from previous step:\n${JSON.stringify(prevData, null, 2).slice(0, 2000)}`;
+      }
+
+      // Send task via A2A (or bridge)
+      const taskResult = await this.sendTask(agent, taskMessage);
+
+      const success = taskResult.state === "completed";
+      if (success && taskResult.artifacts.length > 0) {
+        context.set(step.id, taskResult.artifacts);
+      }
+
+      results.push({
+        stepId: step.id,
+        role: step.role,
+        agent: { name: agent.name, source: agent.source, protocol: agent.protocol },
+        success,
+        result: taskResult,
+        error: taskResult.error,
+      });
+    }
+
+    return {
+      steps: results,
+      completedCount: results.filter((r) => r.success).length,
+      totalCount: steps.length,
+      context: Object.fromEntries(context),
+    };
+  }
+}
+
+export interface CoordinationStep {
+  id: string;
+  role: string;
+  query?: string;
+  task?: string;
+  agent?: UnifiedAgent;
+  dependsOn?: string;
+}
+
+export interface StepResult {
+  stepId: string;
+  role: string;
+  agent?: { name: string; source: string; protocol: string };
+  success: boolean;
+  result?: A2ATaskResult;
+  error?: string;
+  skipped?: boolean;
+}
+
+export interface CoordinationResult {
+  steps: StepResult[];
+  completedCount: number;
+  totalCount: number;
+  context: Record<string, unknown>;
+}

package/src/a2a/client.ts

@@ -0,0 +1,92 @@
+/**
+ * Kompass A2A Client
+ * Sends tasks to A2A-compatible agents
+ */
+
+import { ClientFactory, JsonRpcTransportFactory, RestTransportFactory } from "@a2a-js/sdk/client";
+import type { Task, Message, Artifact, TaskState } from "@a2a-js/sdk";
+
+export interface A2ATaskOptions {
+  /** The A2A agent URL (where agent-card.json is hosted) */
+  agentUrl: string;
+  /** Task message text */
+  message: string;
+  /** Optional context from previous tasks */
+  contextId?: string;
+  /** Timeout in ms */
+  timeout?: number;
+}
+
+export interface A2ATaskResult {
+  taskId: string;
+  state: string;
+  artifacts: unknown[];
+  messages: unknown[];
+  error?: string;
+}
+
+export class KompassA2AClient {
+  private factory: ClientFactory;
+
+  constructor() {
+    this.factory = new ClientFactory({
+      transports: [new JsonRpcTransportFactory(), new RestTransportFactory()],
+    } as any);
+  }
+
+  /**
+   * Send a task to an A2A-compatible agent and wait for completion.
+   */
+  async sendTask(options: A2ATaskOptions): Promise<A2ATaskResult> {
+    try {
+      const client = await this.factory.createFromUrl(options.agentUrl);
+
+      // Send message and get task
+      const response = await client.sendMessage({
+        message: {
+          role: "user",
+          parts: [{ type: "text", text: options.message }],
+        },
+        configuration: {
+          blocking: true, // Wait for completion
+        },
+      } as any);
+
+      // Extract task info from response
+      const task = (response as any)?.result;
+
+      if (!task) {
+        return {
+          taskId: "unknown",
+          state: "failed",
+          artifacts: [],
+          messages: [],
+          error: "No task returned from agent",
+        };
+      }
+
+      return {
+        taskId: task.id ?? task.taskId ?? "unknown",
+        state: task.status?.state ?? task.state ?? "completed",
+        artifacts: task.artifacts ?? [],
+        messages: task.history ?? [],
+      };
+    } catch (err) {
+      return {
+        taskId: "error",
+        state: "failed",
+        artifacts: [],
+        messages: [],
+        error: err instanceof Error ? err.message : String(err),
+      };
+    }
+  }
+
+  /**
+   * Send a streaming task to an A2A agent and collect results.
+   */
+  async sendStreamingTask(options: A2ATaskOptions): Promise<A2ATaskResult> {
+    // Streaming falls back to blocking send for compatibility
+    return this.sendTask(options);
+  }
+}