kompass-sdk 0.20.0 → 0.21.1

package/src/onboard.ts

@@ -0,0 +1,420 @@
+/**
+ * Kompass Agent Onboarding — Full Identity Registration
+ *
+ * Orchestrates the complete flow:
+ *   1. Create wallet (free — generates keypair)
+ *   2. Register ERC-8004 identity (~$0.005 gas)
+ *   3. Register Basename (~$0.25-$2.50)
+ *   4. Set ENS text records (~$0.02 gas)
+ *   5. Register on Kompass Registry (gas only)
+ *
+ * Total cost: ~$2.55 in ETH (agent pays from their own wallet)
+ */
+
+import type { Address, Hex } from "viem";
+import { KompassWallet } from "./wallet/index.js";
+import {
+  registerERC8004,
+  buildAgentCard,
+  ERC8004_IDENTITY_REGISTRY,
+  type RegisterERC8004Result,
+} from "./erc8004.js";
+import {
+  registerBasename,
+  setBasenameTextRecords,
+  basenameNode,
+  isBasenameAvailable,
+  getBasenamePrice,
+  BASENAME_REGISTRAR,
+  BASENAME_L2_RESOLVER,
+  type BasenameResult,
+  type TextRecord,
+} from "./basename.js";
+
+// ── Types ──────────────────────────────────────────────────
+
+export interface OnboardOptions {
+  /** Agent name (used for Basename, e.g. "my-agent" → my-agent.base.eth) */
+  name: string;
+  /** What this agent does */
+  description: string;
+  /** e.g. ["defi", "trading", "data"] */
+  categories: string[];
+  /** What the agent can do */
+  capabilities: string[];
+  /** Agent role */
+  agentType: "provider" | "evaluator" | "both";
+  /** Reachable endpoints */
+  endpoints?: {
+    mcp?: string;
+    a2a?: string;
+    x402?: string;
+    http?: string;
+  };
+  /** How this agent gets paid */
+  pricingModel?: "escrow" | "x402" | "free";
+  /** e.g. "0.01" (USDC per task) */
+  pricingRate?: string;
+  /** Network to deploy on */
+  network?: "base" | "base-sepolia";
+  /** Skip Basename registration if agent already has a name */
+  skipBasename?: boolean;
+  /** Skip Kompass Registry (e.g. if on mainnet where registry isn't deployed) */
+  skipKompassRegistry?: boolean;
+  /** Existing wallet path (skip wallet creation) */
+  walletPath?: string;
+  /** Wallet password */
+  walletPassword?: string;
+  /** URL where the agent card JSON will be hosted */
+  agentCardUrl?: string;
+}
+
+export interface OnboardResult {
+  wallet: {
+    address: Address;
+    network: string;
+    keystorePath: string;
+    isNew: boolean;
+  };
+  erc8004: RegisterERC8004Result;
+  basename?: BasenameResult;
+  ensRecords: {
+    txHashes: Hex[];
+    records: Record<string, string>;
+  };
+  kompassRegistry?: {
+    txHash: Hex;
+    ensNode: Hex;
+  };
+  agentCard: {
+    name: string;
+    description: string;
+    capabilities: string[];
+    categories: string[];
+    paymentAddress: Address;
+  };
+  totalSteps: number;
+  completedSteps: number;
+}
+
+export interface OnboardInitResult {
+  walletAddress: Address;
+  network: string;
+  keystorePath: string;
+  fundingRequired: {
+    eth: string;
+    description: string;
+  };
+  estimatedCosts: {
+    erc8004Gas: string;
+    basename: string;
+    ensRecordsGas: string;
+    total: string;
+  };
+}
+
+// ── Step 1: Initialize (create wallet, return funding instructions) ────
+
+/**
+ * Initialize onboarding: create wallet, estimate costs.
+ * Call this first, then fund the wallet, then call completeOnboarding().
+ */
+export function initOnboarding(options: OnboardOptions): OnboardInitResult {
+  const network = options.network ?? "base";
+
+  // Create or load wallet
+  let wallet: KompassWallet;
+  if (options.walletPath) {
+    wallet = KompassWallet.load(options.walletPath, options.walletPassword);
+  } else {
+    wallet = KompassWallet.create({ network, password: options.walletPassword });
+  }
+
+  const basenameEstimate = options.skipBasename
+    ? "0"
+    : options.name.length >= 10
+      ? "0.0001"
+      : "0.001";
+
+  return {
+    walletAddress: wallet.getAddress(),
+    network,
+    keystorePath: options.walletPath ?? `${process.env.HOME ?? "~"}/.kompass/wallet.json`,
+    fundingRequired: {
+      eth: options.skipBasename ? "0.001" : "0.003",
+      description: `Send ETH to ${wallet.getAddress()} on Base ${network === "base" ? "mainnet" : "Sepolia"} to cover gas + basename registration`,
+    },
+    estimatedCosts: {
+      erc8004Gas: "~0.0001 ETH",
+      basename: options.skipBasename ? "skipped" : `~${basenameEstimate} ETH`,
+      ensRecordsGas: "~0.0005 ETH",
+      total: options.skipBasename ? "~0.001 ETH" : `~${(parseFloat(basenameEstimate) + 0.001).toFixed(4)} ETH`,
+    },
+  };
+}
+
+// ── Step 2: Complete (run full registration after funding) ─────────────
+
+/**
+ * Complete the full onboarding flow. The wallet must be funded before calling this.
+ *
+ * Flow:
+ *   1. Build agent card JSON
+ *   2. Register ERC-8004 identity (mint agent NFT)
+ *   3. Register Basename (optional)
+ *   4. Set ENS text records (agent metadata)
+ *   5. Register on Kompass Registry (optional)
+ */
+export async function completeOnboarding(
+  options: OnboardOptions,
+  walletPathOrWallet?: string | KompassWallet,
+): Promise<OnboardResult> {
+  const network = options.network ?? "base";
+
+  // Load or create wallet
+  let wallet: KompassWallet;
+  let isNew = false;
+  if (walletPathOrWallet instanceof KompassWallet) {
+    wallet = walletPathOrWallet;
+  } else {
+    const loadPath = walletPathOrWallet ?? options.walletPath;
+    try {
+      wallet = KompassWallet.load(loadPath, options.walletPassword);
+    } catch {
+      // Wallet doesn't exist yet — create it
+      wallet = KompassWallet.create({ path: loadPath, network, password: options.walletPassword });
+      isNew = true;
+    }
+  }
+
+  const address = wallet.getAddress();
+  const totalSteps = 2 + (options.skipBasename ? 0 : 1) + 1 + (options.skipKompassRegistry ? 0 : 1);
+  let completedSteps = 0;
+
+  // Check balance
+  const balance = await wallet.getBalance();
+  if (balance.ethRaw < 500000000000000n) {
+    // < 0.0005 ETH
+    throw new Error(
+      `Insufficient ETH balance: ${balance.eth} ETH. ` +
+      `Fund wallet ${address} with at least 0.003 ETH on Base ${network === "base" ? "mainnet" : "Sepolia"}.`,
+    );
+  }
+
+  // ── Step 1: Build agent card ──────────────────────────────
+  const agentCard = buildAgentCard({
+    name: options.name,
+    description: options.description,
+    capabilities: options.capabilities,
+    categories: options.categories,
+    walletAddress: address,
+    endpoints: options.endpoints,
+  });
+
+  // Determine agent card URL
+  const agentCardUrl = options.agentCardUrl ?? `https://kompasss.xyz/agents/${address}.json`;
+  completedSteps++;
+
+  // ── Step 2: Register ERC-8004 Identity ────────────────────
+  console.log(`[onboard] Registering ERC-8004 identity for ${options.name}...`);
+  const erc8004Result = await registerERC8004(wallet, agentCardUrl);
+  console.log(`[onboard] ERC-8004 identity registered: agentId=${erc8004Result.agentId}`);
+  completedSteps++;
+
+  // ── Step 3: Register Basename (optional) ──────────────────
+  let basenameResult: BasenameResult | undefined;
+  if (!options.skipBasename) {
+    console.log(`[onboard] Registering basename: ${options.name}.base.eth...`);
+
+    // Build text records to set atomically during registration
+    const textRecords: TextRecord[] = [
+      { key: "com.kompass.type", value: options.agentType },
+      { key: "com.kompass.categories", value: options.categories.join(",") },
+      { key: "com.kompass.description", value: options.description },
+      { key: "com.kompass.erc8004.id", value: erc8004Result.agentId.toString() },
+    ];
+
+    if (options.endpoints?.mcp) textRecords.push({ key: "com.kompass.endpoint.mcp", value: options.endpoints.mcp });
+    if (options.endpoints?.a2a) textRecords.push({ key: "com.kompass.endpoint.a2a", value: options.endpoints.a2a });
+    if (options.endpoints?.x402) textRecords.push({ key: "com.kompass.endpoint.x402", value: options.endpoints.x402 });
+    if (options.endpoints?.http) textRecords.push({ key: "com.kompass.endpoint.http", value: options.endpoints.http });
+    if (options.pricingModel) textRecords.push({ key: "com.kompass.payment.mode", value: options.pricingModel });
+    if (options.pricingRate) textRecords.push({ key: "com.kompass.pricing.rate", value: options.pricingRate });
+
+    try {
+      basenameResult = await registerBasename(wallet, options.name, textRecords);
+      console.log(`[onboard] Basename registered: ${basenameResult.fullName}`);
+    } catch (err: any) {
+      console.warn(`[onboard] Basename registration failed (non-critical): ${err.message}`);
+    }
+    completedSteps++;
+  }
+
+  // ── Step 4: Set ENS text records (if basename was skipped or failed) ──
+  const ensRecords: Record<string, string> = {};
+  const ensRecordTxHashes: Hex[] = [];
+
+  // If basename was registered with text records, they're already set atomically.
+  // If basename failed or was skipped but we have an existing name, set records separately.
+  if (!basenameResult && basenameResult === undefined) {
+    // Try setting records on the name if it exists (maybe registered before)
+    try {
+      const { setBasenameTextRecords } = await import("./basename.js");
+      const records = [
+        { key: "com.kompass.type", value: options.agentType },
+        { key: "com.kompass.categories", value: options.categories.join(",") },
+        { key: "com.kompass.description", value: options.description },
+        { key: "com.kompass.erc8004.id", value: erc8004Result.agentId.toString() },
+      ];
+      if (options.pricingModel) records.push({ key: "com.kompass.payment.mode", value: options.pricingModel });
+      if (options.pricingRate) records.push({ key: "com.kompass.pricing.rate", value: options.pricingRate });
+
+      const txHashes = await setBasenameTextRecords(wallet, options.name, records);
+      ensRecordTxHashes.push(...txHashes);
+      console.log(`[onboard] Set ${records.length} ENS text records separately`);
+    } catch (err: any) {
+      console.warn(`[onboard] Could not set ENS text records separately: ${err.message}`);
+    }
+  }
+
+  // Always track what records we set/would set
+  ensRecords["com.kompass.type"] = options.agentType;
+  ensRecords["com.kompass.categories"] = options.categories.join(",");
+  ensRecords["com.kompass.description"] = options.description;
+  ensRecords["com.kompass.erc8004.id"] = erc8004Result.agentId.toString();
+  if (options.pricingModel) ensRecords["com.kompass.payment.mode"] = options.pricingModel;
+  if (options.pricingRate) ensRecords["com.kompass.pricing.rate"] = options.pricingRate;
+  if (options.endpoints?.mcp) ensRecords["com.kompass.endpoint.mcp"] = options.endpoints.mcp;
+  if (options.endpoints?.x402) ensRecords["com.kompass.endpoint.x402"] = options.endpoints.x402;
+  completedSteps++;
+
+  // ── Step 5: Register on Kompass Registry (optional) ───────
+  let kompassRegistryResult: { txHash: Hex; ensNode: Hex } | undefined;
+  if (!options.skipKompassRegistry && basenameResult) {
+    console.log(`[onboard] Registering on Kompass Registry...`);
+    try {
+      // Import registry dynamically to avoid circular deps
+      const { register } = await import("./registry.js");
+      const { createPublicClient, createWalletClient, http } = await import("viem");
+      const { baseSepolia } = await import("viem/chains");
+
+      // Kompass Registry is on Base Sepolia
+      const publicClient = createPublicClient({ chain: baseSepolia, transport: http("https://sepolia.base.org") });
+      const walletClient = createWalletClient({
+        account: wallet.getAccount(),
+        chain: baseSepolia,
+        transport: http("https://sepolia.base.org"),
+      });
+
+      const config = {
+        publicClient: publicClient as any,
+        walletClient: walletClient as any,
+        escrowAddress: "0xbc003cE4bd4B272c1C25919B6b8ec379bccdE6ac" as Address,
+        registryAddress: "0x94D394362a4BA850673bEF368Ed907996287C7d7" as Address,
+        reputationRegistryAddress: "0x8004BAa17C55a88189AE136b182e5fdA19dE9b63" as Address,
+        indexerUrl: "https://kompasss.xyz/api",
+      };
+
+      const result = await register(config, {
+        ensNode: basenameResult.node,
+        ensName: basenameResult.fullName,
+        agentType: options.agentType,
+        categories: options.categories.join(","),
+        description: options.description,
+        erc8004Id: erc8004Result.agentId.toString(),
+        pricingModel: options.pricingModel,
+        pricingRate: options.pricingRate,
+        endpointMcp: options.endpoints?.mcp,
+        endpointA2a: options.endpoints?.a2a,
+        endpointX402: options.endpoints?.x402,
+        paymentMode: options.pricingModel as any,
+      });
+
+      kompassRegistryResult = { txHash: result.txHash, ensNode: basenameResult.node };
+      console.log(`[onboard] Kompass Registry registration complete`);
+    } catch (err: any) {
+      console.warn(`[onboard] Kompass Registry registration failed (non-critical): ${err.message}`);
+    }
+    completedSteps++;
+  }
+
+  return {
+    wallet: {
+      address,
+      network,
+      keystorePath: options.walletPath ?? `${process.env.HOME ?? "~"}/.kompass/wallet.json`,
+      isNew,
+    },
+    erc8004: erc8004Result,
+    basename: basenameResult,
+    ensRecords: {
+      txHashes: ensRecordTxHashes,
+      records: ensRecords,
+    },
+    kompassRegistry: kompassRegistryResult,
+    agentCard,
+    totalSteps,
+    completedSteps,
+  };
+}
+
+// ── Convenience: Full onboard in one call ──────────────────
+
+/**
+ * Full onboarding: create wallet + register everything.
+ * Returns immediately with wallet address if funding is needed.
+ */
+export async function onboardAgent(options: OnboardOptions): Promise<OnboardResult> {
+  return completeOnboarding(options);
+}
+
+// ── Utilities ──────────────────────────────────────────────
+
+/**
+ * Check if a wallet has enough funds for onboarding.
+ */
+export async function checkOnboardingFunds(
+  walletPath?: string,
+  password?: string,
+): Promise<{
+  address: Address;
+  eth: string;
+  sufficient: boolean;
+  network: string;
+}> {
+  const wallet = KompassWallet.load(walletPath, password);
+  const balance = await wallet.getBalance();
+
+  return {
+    address: wallet.getAddress(),
+    eth: balance.eth,
+    sufficient: balance.ethRaw >= 500000000000000n, // 0.0005 ETH minimum
+    network: balance.network,
+  };
+}
+
+/**
+ * Estimate the total cost of onboarding.
+ */
+export async function estimateOnboardingCost(
+  name: string,
+  skipBasename: boolean = false,
+): Promise<{
+  basename: string;
+  gas: string;
+  total: string;
+}> {
+  const basenameEth = skipBasename
+    ? 0
+    : name.length >= 10
+      ? 0.0001
+      : 0.001;
+
+  const gasEstimate = 0.001; // ~$2.50 at current prices
+
+  return {
+    basename: skipBasename ? "0" : basenameEth.toString(),
+    gas: gasEstimate.toString(),
+    total: (basenameEth + gasEstimate).toFixed(4),
+  };
+}

package/src/router.ts

@@ -95,9 +95,9 @@ export class CapabilityRouter {
       ? `${options.task}\n\nContext from previous step:\n${options.context.slice(0, 2000)}`
       : options.task;
 
-    // 1. Search all sources
+    // 1. Search all sources — use high limit to ensure callable agents aren't cut off
     const searchResult = await this.aggregator.search(task, {
-      limit: 30,
+      limit: 100,
       timeout: options.timeout ?? 15000,
     });
 

package/src/sources/acp.ts

@@ -37,16 +37,17 @@ export const acpAdapter: SourceAdapter = {
         return offerings.length > 0;
       });
 
-      // Client-side text matching if query provided
+      // Client-side text matching if query provided (skip for browse-all)
       let filtered = withOfferings;
-      if (query) {
+      if (query && query !== "*") {
         const lower = query.toLowerCase();
         const terms = lower.split(/\s+/).filter(t => t.length > 2);
-        filtered = withOfferings.filter((a: any) => {
-          const text = `${a.name} ${a.description ?? ""} ${(a.jobs ?? a.offerings ?? []).map((o: any) => `${o.name} ${o.description ?? ""}`).join(" ")}`.toLowerCase();
-          return terms.some(t => text.includes(t));
-        });
-        // No matches — return empty, don't pollute results with irrelevant agents
+        if (terms.length > 0) {
+          filtered = withOfferings.filter((a: any) => {
+            const text = `${a.name} ${a.description ?? ""} ${(a.jobs ?? a.offerings ?? []).map((o: any) => `${o.name} ${o.description ?? ""}`).join(" ")}`.toLowerCase();
+            return terms.some(t => text.includes(t));
+          });
+        }
       }
 
       return filtered.slice(0, limit).map(mapAcpAgent);

package/src/sources/bankr.ts

@@ -27,10 +27,12 @@ export const bankrAdapter: SourceAdapter = {
   async search(query: string, options?: SourceSearchOptions): Promise<UnifiedAgent[]> {
     if (!process.env.BANKR_API_KEY) return [];
 
-    const lower = query.toLowerCase();
-    const isRelevant = BANKR_CAPABILITIES.some(cap => lower.includes(cap));
-
-    if (!isRelevant && query.length > 0) return [];
+    // Return self for browse-all queries or when query matches capabilities
+    if (query && query !== "*") {
+      const lower = query.toLowerCase();
+      const isRelevant = BANKR_CAPABILITIES.some(cap => lower.includes(cap));
+      if (!isRelevant) return [];
+    }
 
     return [createBankrAgent()];
   },

package/src/sources/erc8004.ts

@@ -20,7 +20,7 @@ export function createErc8004Adapter(network: "base" | "base-sepolia" = "base"):
       try {
         // Search across all chains on 8004scan
         const url = new URL(`${SCAN_API}/agents`);
-        if (query) url.searchParams.set("search", query);
+        if (query && query !== "*") url.searchParams.set("search", query);
         url.searchParams.set("limit", String(limit));
 
         const res = await fetch(url.toString(), {
@@ -36,7 +36,7 @@ export function createErc8004Adapter(network: "base" | "base-sepolia" = "base"):
 
         return agents
           .filter((a: any) => {
-            if (!query) return true;
+            if (!query || query === "*") return true;
             const text = `${a.name ?? ""} ${a.description ?? ""}`.toLowerCase();
             return query.toLowerCase().split(/\s+/).some((t) => text.includes(t));
           })

package/src/sources/locus.ts

@@ -89,6 +89,11 @@ export const locusAdapter: SourceAdapter = {
 
     const providers = await fetchProviders(timeout);
 
+    // Return all providers for browse-all queries
+    if (!query || query === "*" || terms.length === 0) {
+      return providers.slice(0, limit).map(mapLocusProvider);
+    }
+
     // Score each provider by relevance
     const scored = providers.map(provider => {
       let score = 0;

package/src/sources/mcp-registry.ts

@@ -61,7 +61,13 @@ async function fetchAllServers(timeout: number): Promise<McpServer[]> {
  * Much better than the registry's keyword search which only matches names.
  */
 function searchLocally(servers: McpServer[], query: string, limit: number): McpServer[] {
+  // Return all for browse-all queries
+  if (!query || query === "*") {
+    return servers.slice(0, limit);
+  }
+
   const queryTerms = query.toLowerCase().split(/\s+/).filter((t) => t.length > 2);
+  if (queryTerms.length === 0) return servers.slice(0, limit);
 
   return servers
     .map((server) => {