kompass-sdk 0.1.0

package/src/sources/a2a-wellknown.ts

@@ -0,0 +1,120 @@
+/**
+ * A2A Agent Card Source Adapter
+ * Crawls .well-known/agent-card.json from known domains
+ * Google's A2A protocol — IANA registered well-known URI
+ */
+
+import type { SourceAdapter, UnifiedAgent, SourceSearchOptions } from "./types.js";
+
+// Seed list of domains known to support A2A agent cards
+const SEED_DOMAINS = [
+  "https://agents.google.com",
+  "https://agents.anthropic.com",
+  "https://agents.openai.com",
+  "https://api.langchain.com",
+  "https://agents.vercel.com",
+  "https://agent.coinbase.com",
+  "https://agents.stripe.com",
+  "https://agent.shopify.com",
+];
+
+interface AgentCard {
+  name: string;
+  description?: string;
+  url?: string;
+  provider?: { name: string; url?: string };
+  capabilities?: { streaming?: boolean; pushNotifications?: boolean };
+  authentication?: { type: string }[];
+  skills?: { id: string; name: string; description: string; inputModes?: string[]; outputModes?: string[] }[];
+}
+
+export const a2aWellknownAdapter: SourceAdapter = {
+  name: "a2a-wellknown",
+  displayName: "A2A Agent Cards (.well-known)",
+
+  async search(query: string, options?: SourceSearchOptions): Promise<UnifiedAgent[]> {
+    const timeout = options?.timeout ?? 3000;
+    const results: UnifiedAgent[] = [];
+
+    // Crawl all seed domains in parallel
+    const promises = SEED_DOMAINS.map(async (domain) => {
+      try {
+        const url = `${domain}/.well-known/agent-card.json`;
+        const res = await fetch(url, { signal: AbortSignal.timeout(timeout) });
+        if (!res.ok) return null;
+        const card: AgentCard = await res.json();
+        return mapAgentCard(card, domain);
+      } catch {
+        return null;
+      }
+    });
+
+    const settled = await Promise.allSettled(promises);
+    for (const result of settled) {
+      if (result.status === "fulfilled" && result.value) {
+        results.push(result.value);
+      }
+    }
+
+    // Filter by query
+    if (query) {
+      const lower = query.toLowerCase();
+      return results.filter((a) =>
+        a.name.toLowerCase().includes(lower) ||
+        a.description.toLowerCase().includes(lower) ||
+        a.categories.some((c) => c.toLowerCase().includes(lower))
+      );
+    }
+
+    return results.slice(0, options?.limit ?? 50);
+  },
+
+  async ping(): Promise<boolean> {
+    // Try to fetch at least one agent card
+    for (const domain of SEED_DOMAINS.slice(0, 3)) {
+      try {
+        const res = await fetch(`${domain}/.well-known/agent-card.json`, {
+          signal: AbortSignal.timeout(3000),
+        });
+        if (res.ok) return true;
+      } catch {
+        continue;
+      }
+    }
+    return false;
+  },
+};
+
+function mapAgentCard(card: AgentCard, domain: string): UnifiedAgent {
+  const skills = card.skills ?? [];
+  const categories = skills.flatMap((s) => extractSkillCategories(s.name, s.description));
+  const uniqueCats = [...new Set(categories)];
+
+  return {
+    id: `a2a-wellknown:${new URL(domain).hostname}`,
+    nativeId: new URL(domain).hostname,
+    name: card.name,
+    description: card.description ?? skills.map((s) => s.description).join(". "),
+    categories: uniqueCats.length > 0 ? uniqueCats : ["general"],
+    capabilities: skills.map((s) => `${s.name}: ${s.description}`),
+    source: "a2a-wellknown",
+    protocol: "a2a",
+    endpoints: {
+      a2a: card.url ?? domain,
+      http: domain,
+    },
+    pricing: { model: "unknown" },
+    verified: true,
+    raw: card,
+  };
+}
+
+function extractSkillCategories(name: string, description: string): string[] {
+  const text = `${name} ${description}`.toLowerCase();
+  const cats: string[] = [];
+  if (text.match(/search|research|data/)) cats.push("data");
+  if (text.match(/code|develop|build/)) cats.push("development");
+  if (text.match(/defi|yield|swap/)) cats.push("defi");
+  if (text.match(/write|content|generate/)) cats.push("content");
+  return cats;
+}

package/src/sources/acp.ts

@@ -0,0 +1,91 @@
+/**
+ * Virtuals ACP Source Adapter
+ * Searches the ACP marketplace via CLI (most reliable method)
+ */
+
+import { execSync } from "child_process";
+import type { SourceAdapter, UnifiedAgent, SourceSearchOptions } from "./types.js";
+
+const ACP_CLI_PATH = "/tmp/openclaw-acp";
+
+export const acpAdapter: SourceAdapter = {
+  name: "acp",
+  displayName: "Virtuals ACP Marketplace",
+
+  async search(query: string, options?: SourceSearchOptions): Promise<UnifiedAgent[]> {
+    try {
+      const result = execSync(
+        `cd ${ACP_CLI_PATH} && npx acp browse "${query}" --json 2>/dev/null`,
+        { timeout: options?.timeout ?? 30000, encoding: "utf-8" }
+      );
+
+      const agents: any[] = JSON.parse(result);
+      return agents.slice(0, options?.limit ?? 50).map(mapAcpAgent);
+    } catch {
+      return [];
+    }
+  },
+
+  async ping(): Promise<boolean> {
+    try {
+      execSync(`cd ${ACP_CLI_PATH} && npx acp whoami --json 2>/dev/null`, {
+        timeout: 10000,
+        encoding: "utf-8",
+      });
+      return true;
+    } catch {
+      return false;
+    }
+  },
+};
+
+function mapAcpAgent(agent: any): UnifiedAgent {
+  const offerings = agent.jobs ?? agent.jobOfferings ?? [];
+  const topOffering = offerings[0];
+
+  return {
+    id: `acp:${agent.id ?? agent.walletAddress}`,
+    nativeId: String(agent.id ?? agent.walletAddress),
+    name: agent.name ?? "Unknown ACP Agent",
+    description: agent.description ?? offerings.map((o: any) => o.description).join(". ") ?? "",
+    categories: extractAcpCategories(agent, offerings),
+    capabilities: offerings.map((o: any) => `${o.name}: ${o.description ?? ""}`),
+    source: "acp",
+    protocol: "acp",
+    endpoints: {
+      acp: {
+        walletAddress: agent.walletAddress ?? agent.contractAddress,
+        entityAddress: agent.entityAddress,
+      },
+    },
+    reputation: agent.metrics ? {
+      score: agent.metrics.successRate ?? 0,
+      count: agent.metrics.completedJobs ?? 0,
+      source: "acp",
+    } : undefined,
+    pricing: topOffering ? {
+      model: "escrow",
+      amount: String(topOffering.price ?? "0"),
+      currency: "USDC",
+    } : undefined,
+    verified: true, // ACP agents are registered
+    raw: agent,
+  };
+}
+
+function extractAcpCategories(agent: any, offerings: any[]): string[] {
+  const text = [
+    agent.name,
+    agent.description,
+    ...offerings.map((o: any) => `${o.name} ${o.description}`),
+  ].join(" ").toLowerCase();
+
+  const cats: string[] = [];
+  if (text.match(/defi|yield|swap|liquidity|pool/)) cats.push("defi");
+  if (text.match(/data|analyt|research|market/)) cats.push("data");
+  if (text.match(/trade|trading|price/)) cats.push("trading");
+  if (text.match(/risk|audit|security/)) cats.push("risk");
+  if (text.match(/content|image|video|write/)) cats.push("content");
+  if (text.match(/code|develop|build/)) cats.push("development");
+  return cats.length > 0 ? cats : ["general"];
+}

package/src/sources/adp.ts

@@ -0,0 +1,64 @@
+/**
+ * Agent Discovery Protocol (ADP) Source Adapter
+ * agentdiscovery.io — open protocol for autonomous agent commerce
+ */
+
+import type { SourceAdapter, UnifiedAgent, SourceSearchOptions } from "./types.js";
+
+const ADP_BASE = "https://agentdiscovery.io";
+
+export const adpAdapter: SourceAdapter = {
+  name: "adp",
+  displayName: "Agent Discovery Protocol",
+
+  async search(query: string, options?: SourceSearchOptions): Promise<UnifiedAgent[]> {
+    try {
+      // Try the ADP API
+      const res = await fetch(`${ADP_BASE}/api/agents?q=${encodeURIComponent(query)}&limit=${options?.limit ?? 20}`, {
+        signal: AbortSignal.timeout(options?.timeout ?? 5000),
+      });
+
+      if (!res.ok) return [];
+
+      const data = await res.json();
+      const agents = Array.isArray(data) ? data : data.agents ?? data.data ?? [];
+
+      return agents.map((agent: any) => ({
+        id: `adp:${agent.id ?? agent.address}`,
+        nativeId: String(agent.id ?? agent.address),
+        name: agent.name ?? "ADP Agent",
+        description: agent.description ?? "",
+        categories: agent.categories ?? agent.tags ?? ["general"],
+        capabilities: agent.capabilities ?? [agent.description ?? ""],
+        source: "adp" as const,
+        protocol: (agent.protocol ?? "http") as any,
+        endpoints: {
+          http: agent.endpoint ?? agent.url,
+          a2a: agent.a2aEndpoint,
+          x402: agent.x402Endpoint,
+        },
+        reputation: agent.reputation ? {
+          score: agent.reputation.score ?? 0,
+          count: agent.reputation.count ?? 0,
+          source: "adp",
+        } : undefined,
+        pricing: agent.pricing,
+        verified: agent.verified ?? false,
+        raw: agent,
+      }));
+    } catch {
+      return [];
+    }
+  },
+
+  async ping(): Promise<boolean> {
+    try {
+      const res = await fetch(`${ADP_BASE}/api/health`, {
+        signal: AbortSignal.timeout(3000),
+      });
+      return res.ok;
+    } catch {
+      return false;
+    }
+  },
+};

package/src/sources/erc8004.ts

@@ -0,0 +1,166 @@
+/**
+ * ERC-8004 On-Chain Source Adapter
+ * Indexes agent identities from the ERC-8004 Identity Registry on Base
+ */
+
+import { createPublicClient, http, type Address, parseAbiItem } from "viem";
+import { base, baseSepolia } from "viem/chains";
+import type { SourceAdapter, UnifiedAgent, SourceSearchOptions } from "./types.js";
+
+// ERC-8004 Identity Registry addresses
+const REGISTRY_ADDRESSES: Record<string, Address> = {
+  "base": "0x8004A818BFB912233c491871b3d84c89A494BD9e" as Address,
+  "base-sepolia": "0x8004A818BFB912233c491871b3d84c89A494BD9e" as Address,
+};
+
+const TRANSFER_EVENT = parseAbiItem(
+  "event Transfer(address indexed from, address indexed to, uint256 indexed tokenId)"
+);
+
+const TOKEN_URI_ABI = [
+  {
+    type: "function",
+    name: "tokenURI",
+    inputs: [{ name: "tokenId", type: "uint256" }],
+    outputs: [{ name: "", type: "string" }],
+    stateMutability: "view",
+  },
+] as const;
+
+export function createErc8004Adapter(network: "base" | "base-sepolia" = "base-sepolia"): SourceAdapter {
+  const chain = network === "base" ? base : baseSepolia;
+  const registryAddress = REGISTRY_ADDRESSES[network];
+
+  const client = createPublicClient({
+    chain,
+    transport: http(),
+  });
+
+  return {
+    name: "erc8004",
+    displayName: "ERC-8004 Identity Registry",
+
+    async search(query: string, options?: SourceSearchOptions): Promise<UnifiedAgent[]> {
+      const limit = options?.limit ?? 20;
+
+      try {
+        // Get recent Transfer events (minting = from 0x0)
+        const logs = await client.getLogs({
+          address: registryAddress,
+          event: TRANSFER_EVENT,
+          args: { from: "0x0000000000000000000000000000000000000000" as Address },
+          fromBlock: "earliest",
+          toBlock: "latest",
+        });
+
+        const agents: UnifiedAgent[] = [];
+
+        // Process most recent first
+        const recentLogs = logs.slice(-limit * 2).reverse();
+
+        for (const log of recentLogs) {
+          if (agents.length >= limit) break;
+
+          const tokenId = log.args.tokenId!;
+          const owner = log.args.to!;
+
+          try {
+            // Fetch tokenURI for agent metadata
+            const uri = await client.readContract({
+              address: registryAddress,
+              abi: TOKEN_URI_ABI,
+              functionName: "tokenURI",
+              args: [tokenId],
+            });
+
+            // Resolve URI to JSON
+            let metadata: any = {};
+            if (uri.startsWith("http") || uri.startsWith("ipfs")) {
+              const fetchUrl = uri.startsWith("ipfs://")
+                ? `https://ipfs.io/ipfs/${uri.slice(7)}`
+                : uri;
+              const res = await fetch(fetchUrl, { signal: AbortSignal.timeout(3000) });
+              if (res.ok) metadata = await res.json();
+            } else if (uri.startsWith("data:")) {
+              const json = uri.split(",")[1];
+              metadata = JSON.parse(atob(json));
+            }
+
+            const agent = mapErc8004Agent(tokenId, owner, metadata, network);
+
+            // Filter by query
+            if (query) {
+              const searchText = `${agent.name} ${agent.description} ${agent.categories.join(" ")}`.toLowerCase();
+              if (!searchText.includes(query.toLowerCase())) continue;
+            }
+
+            agents.push(agent);
+          } catch {
+            // Skip agents with unresolvable metadata
+            continue;
+          }
+        }
+
+        return agents;
+      } catch {
+        return [];
+      }
+    },
+
+    async ping(): Promise<boolean> {
+      try {
+        await client.getBlockNumber();
+        return true;
+      } catch {
+        return false;
+      }
+    },
+  };
+}
+
+function mapErc8004Agent(
+  tokenId: bigint,
+  owner: Address,
+  metadata: any,
+  network: string
+): UnifiedAgent {
+  const services = metadata.services ?? [];
+  const endpoints: UnifiedAgent["endpoints"] = {};
+
+  for (const svc of services) {
+    if (svc.protocol === "mcp") endpoints.mcp = svc.endpoint;
+    if (svc.protocol === "a2a") endpoints.a2a = svc.endpoint;
+    if (svc.protocol === "x402") endpoints.x402 = svc.endpoint;
+    if (svc.protocol === "http") endpoints.http = svc.endpoint;
+  }
+
+  return {
+    id: `erc8004:${network}:${tokenId}`,
+    nativeId: tokenId.toString(),
+    name: metadata.name ?? `Agent #${tokenId}`,
+    description: metadata.description ?? "",
+    categories: metadata.categories ?? extractFromDescription(metadata.description ?? ""),
+    capabilities: services.map((s: any) => `${s.protocol}: ${s.endpoint}`),
+    source: "erc8004",
+    protocol: endpoints.a2a ? "a2a" : endpoints.mcp ? "mcp" : endpoints.x402 ? "x402" : "onchain",
+    endpoints,
+    reputation: {
+      score: 0,
+      count: 0,
+      source: "erc8004",
+    },
+    verified: true,
+    lastSeen: Date.now(),
+    raw: { tokenId: tokenId.toString(), owner, metadata, network },
+  };
+}
+
+function extractFromDescription(text: string): string[] {
+  const lower = text.toLowerCase();
+  const cats: string[] = [];
+  if (lower.match(/defi|yield|swap|pool/)) cats.push("defi");
+  if (lower.match(/data|analyt/)) cats.push("data");
+  if (lower.match(/trade|trading/)) cats.push("trading");
+  if (lower.match(/research/)) cats.push("research");
+  return cats.length > 0 ? cats : ["general"];
+}

package/src/sources/index.ts

@@ -0,0 +1,52 @@
+/**
+ * Source Adapter Registry
+ * Creates and manages all source adapters for universal discovery
+ */
+
+import type { SourceAdapter } from "./types.js";
+import type { KompassConfig } from "../types.js";
+import { mcpRegistryAdapter } from "./mcp-registry.js";
+import { acpAdapter } from "./acp.js";
+import { x402EcosystemAdapter } from "./x402-ecosystem.js";
+import { createErc8004Adapter } from "./erc8004.js";
+import { createKompassRegistryAdapter } from "./kompass-registry.js";
+import { a2aWellknownAdapter } from "./a2a-wellknown.js";
+import { l402DirectoryAdapter } from "./l402-directory.js";
+import { adpAdapter } from "./adp.js";
+import { skillsAdapter } from "./skills.js";
+
+export interface SourceRegistryConfig {
+  /** Kompass SDK config (for kompass-registry adapter) */
+  kompassConfig?: KompassConfig;
+  /** Network for ERC-8004 adapter */
+  erc8004Network?: "base" | "base-sepolia";
+  /** Which sources to enable (default: all) */
+  enabledSources?: string[];
+}
+
+export function createAllSources(config?: SourceRegistryConfig): SourceAdapter[] {
+  const sources: SourceAdapter[] = [
+    mcpRegistryAdapter,
+    acpAdapter,
+    x402EcosystemAdapter,
+    createErc8004Adapter(config?.erc8004Network ?? "base-sepolia"),
+    a2aWellknownAdapter,
+    l402DirectoryAdapter,
+    adpAdapter,
+    skillsAdapter,
+  ];
+
+  // Add Kompass registry if config provided
+  if (config?.kompassConfig) {
+    sources.push(createKompassRegistryAdapter(config.kompassConfig));
+  }
+
+  // Filter to enabled sources if specified
+  if (config?.enabledSources) {
+    return sources.filter((s) => config.enabledSources!.includes(s.name));
+  }
+
+  return sources;
+}
+
+export { type SourceAdapter, type UnifiedAgent, type AgentSource, type AgentProtocol, type SourceSearchOptions } from "./types.js";

package/src/sources/kompass-registry.ts

@@ -0,0 +1,67 @@
+/**
+ * Kompass Registry Source Adapter
+ * Wraps existing discover() function from sdk/src/discover.ts
+ */
+
+import type { SourceAdapter, UnifiedAgent, SourceSearchOptions } from "./types.js";
+import { discover } from "../discover.js";
+import type { AgentProfile } from "../types.js";
+import type { KompassConfig } from "../types.js";
+
+export function createKompassRegistryAdapter(config: KompassConfig): SourceAdapter {
+  return {
+    name: "kompass-registry",
+    displayName: "Kompass Protocol Registry",
+
+    async search(query: string, options?: SourceSearchOptions): Promise<UnifiedAgent[]> {
+      try {
+        const agents = await discover(config, {
+          category: options?.category ?? query,
+          limit: options?.limit ?? 50,
+        });
+        return agents.map(mapKompassAgent);
+      } catch {
+        return [];
+      }
+    },
+
+    async ping(): Promise<boolean> {
+      try {
+        await discover(config, { limit: 1 });
+        return true;
+      } catch {
+        return false;
+      }
+    },
+  };
+}
+
+function mapKompassAgent(agent: AgentProfile): UnifiedAgent {
+  return {
+    id: `kompass-registry:${agent.id}`,
+    nativeId: agent.id,
+    name: agent.ensName || agent.id,
+    description: agent.description ?? "",
+    categories: agent.categories ? agent.categories.split(",").map((c: string) => c.trim()) : [],
+    capabilities: [agent.description, agent.categories].filter(Boolean) as string[],
+    source: "kompass-registry",
+    protocol: agent.x402Enabled ? "x402" : agent.endpointMcp ? "mcp" : agent.endpointA2a ? "a2a" : "onchain",
+    endpoints: {
+      mcp: agent.endpointMcp || undefined,
+      a2a: agent.endpointA2a || undefined,
+      x402: agent.endpointX402 || undefined,
+    },
+    reputation: agent.erc8004Id ? {
+      score: 0,
+      count: 0,
+      source: "kompass-erc8004",
+    } : undefined,
+    pricing: {
+      model: agent.paymentMode === "x402" ? "per-call" : agent.paymentMode === "escrow" ? "escrow" : "unknown",
+      amount: agent.pricingRate || undefined,
+      currency: agent.pricingToken || "USDC",
+    },
+    verified: agent.identityVerified,
+    raw: agent,
+  };
+}

package/src/sources/l402-directory.ts

@@ -0,0 +1,51 @@
+/**
+ * L402 Directory Source Adapter
+ * Indexes Lightning 402 endpoints from known directories
+ */
+
+import type { SourceAdapter, UnifiedAgent, SourceSearchOptions } from "./types.js";
+
+// Known L402 services (from satring, l402.directory, and community)
+const KNOWN_L402_SERVICES = [
+  { name: "Satring", url: "https://satring.com", description: "Curated L402 + x402 API directory. 36 endpoints across 4 providers", categories: ["directory", "tools"] },
+  { name: "Lightning Faucet L402", url: "https://lightningfaucet.com", description: "L402 API registry and testing tools", categories: ["tools", "testing"] },
+  { name: "Nostr NIP-68 Bridge", url: "https://l402.nostr.com", description: "L402 payments over Nostr relay network", categories: ["social", "payments"] },
+  { name: "Stacker News", url: "https://stacker.news", description: "Lightning-powered news with L402 API access", categories: ["content", "data"] },
+  { name: "Nodana", url: "https://nodana.io", description: "L402 agentic access for Bitcoin app deployment", categories: ["development", "compute"] },
+];
+
+export const l402DirectoryAdapter: SourceAdapter = {
+  name: "l402-directory",
+  displayName: "L402 Lightning Directory",
+
+  async search(query: string, options?: SourceSearchOptions): Promise<UnifiedAgent[]> {
+    const lower = query.toLowerCase();
+    const filtered = query
+      ? KNOWN_L402_SERVICES.filter(
+          (s) =>
+            s.name.toLowerCase().includes(lower) ||
+            s.description.toLowerCase().includes(lower) ||
+            s.categories.some((c) => c.includes(lower))
+        )
+      : KNOWN_L402_SERVICES;
+
+    return filtered.slice(0, options?.limit ?? 50).map((service) => ({
+      id: `l402-directory:${service.name.toLowerCase().replace(/\s+/g, "-")}`,
+      nativeId: service.name,
+      name: service.name,
+      description: service.description,
+      categories: service.categories,
+      capabilities: [service.description],
+      source: "l402-directory" as const,
+      protocol: "l402" as const,
+      endpoints: { l402: service.url, http: service.url },
+      pricing: { model: "per-call" as const, currency: "BTC/sats" },
+      verified: true,
+      raw: service,
+    }));
+  },
+
+  async ping(): Promise<boolean> {
+    return true; // Seed list always available
+  },
+};