kompass-sdk 0.1.0

package/src/aggregator.ts

@@ -0,0 +1,203 @@
+/**
+ * Kompass Aggregator
+ * Searches all source adapters in parallel, deduplicates, and ranks results.
+ */
+
+import type { SourceAdapter, UnifiedAgent, SourceSearchOptions } from "./sources/types.js";
+
+export interface AggregatorOptions extends SourceSearchOptions {
+  /** Only search these sources (by name) */
+  sources?: string[];
+  /** Minimum relevance score to include (0-100) */
+  minScore?: number;
+}
+
+export interface AggregatorResult {
+  agents: UnifiedAgent[];
+  sources: { name: string; count: number; durationMs: number; error?: string }[];
+  totalFound: number;
+  deduplicated: number;
+  queryTimeMs: number;
+}
+
+export class Aggregator {
+  private adapters: SourceAdapter[];
+
+  constructor(adapters: SourceAdapter[]) {
+    this.adapters = adapters;
+  }
+
+  async search(query: string, options?: AggregatorOptions): Promise<AggregatorResult> {
+    const startTime = Date.now();
+    const limit = options?.limit ?? 50;
+    const timeout = options?.timeout ?? 15000;
+
+    // Filter adapters by source name if specified
+    const activeAdapters = options?.sources
+      ? this.adapters.filter((a) => options.sources!.includes(a.name))
+      : this.adapters;
+
+    // Fan out to all sources in parallel
+    const promises = activeAdapters.map(async (adapter) => {
+      const adapterStart = Date.now();
+      try {
+        const results = await adapter.search(query, { limit, timeout });
+        return {
+          name: adapter.name,
+          displayName: adapter.displayName,
+          results,
+          durationMs: Date.now() - adapterStart,
+          error: undefined as string | undefined,
+        };
+      } catch (err) {
+        return {
+          name: adapter.name,
+          displayName: adapter.displayName,
+          results: [] as UnifiedAgent[],
+          durationMs: Date.now() - adapterStart,
+          error: err instanceof Error ? err.message : String(err),
+        };
+      }
+    });
+
+    const settled = await Promise.allSettled(promises);
+    const sourceResults = settled.map((s) =>
+      s.status === "fulfilled" ? s.value : { name: "unknown", displayName: "Unknown", results: [], durationMs: 0, error: "Promise rejected" }
+    );
+
+    // Flatten all results
+    const allAgents = sourceResults.flatMap((s) => s.results);
+    const totalFound = allAgents.length;
+
+    // Deduplicate
+    const deduped = this.deduplicate(allAgents);
+    const deduplicated = totalFound - deduped.length;
+
+    // Score and rank
+    const scored = this.scoreAndRank(deduped, query);
+
+    // Apply minimum score filter
+    const filtered = options?.minScore
+      ? scored.filter((a) => (a as any)._score >= options.minScore!)
+      : scored;
+
+    return {
+      agents: filtered.slice(0, limit),
+      sources: sourceResults.map((s) => ({
+        name: s.name,
+        count: s.results.length,
+        durationMs: s.durationMs,
+        error: s.error,
+      })),
+      totalFound,
+      deduplicated,
+      queryTimeMs: Date.now() - startTime,
+    };
+  }
+
+  async healthCheck(): Promise<{ name: string; displayName: string; healthy: boolean }[]> {
+    const results = await Promise.allSettled(
+      this.adapters.map(async (adapter) => ({
+        name: adapter.name,
+        displayName: adapter.displayName,
+        healthy: await adapter.ping(),
+      }))
+    );
+
+    return results.map((r) =>
+      r.status === "fulfilled" ? r.value : { name: "unknown", displayName: "Unknown", healthy: false }
+    );
+  }
+
+  private deduplicate(agents: UnifiedAgent[]): UnifiedAgent[] {
+    const seen = new Map<string, UnifiedAgent>();
+
+    for (const agent of agents) {
+      // Generate dedup keys from endpoints
+      const keys = [
+        agent.endpoints.mcp,
+        agent.endpoints.a2a,
+        agent.endpoints.x402,
+        agent.endpoints.http,
+        agent.endpoints.acp?.walletAddress,
+      ].filter(Boolean);
+
+      let existingKey: string | undefined;
+      for (const key of keys) {
+        if (seen.has(key!)) {
+          existingKey = key!;
+          break;
+        }
+      }
+
+      if (existingKey) {
+        // Merge: keep richer data
+        const existing = seen.get(existingKey)!;
+        existing.categories = [...new Set([...existing.categories, ...agent.categories])];
+        existing.capabilities = [...new Set([...existing.capabilities, ...agent.capabilities])];
+        if (!existing.reputation && agent.reputation) existing.reputation = agent.reputation;
+        if (!existing.pricing && agent.pricing) existing.pricing = agent.pricing;
+        if (agent.description.length > existing.description.length) existing.description = agent.description;
+      } else {
+        // New agent
+        for (const key of keys) {
+          if (key) seen.set(key, agent);
+        }
+        // Also key by name for simple dedup
+        if (!seen.has(agent.name.toLowerCase())) {
+          seen.set(agent.name.toLowerCase(), agent);
+        }
+      }
+    }
+
+    // Return unique agents
+    const uniqueAgents = new Map<string, UnifiedAgent>();
+    for (const agent of seen.values()) {
+      uniqueAgents.set(agent.id, agent);
+    }
+    return Array.from(uniqueAgents.values());
+  }
+
+  private scoreAndRank(agents: UnifiedAgent[], query: string): UnifiedAgent[] {
+    const queryLower = query.toLowerCase();
+    const queryTerms = queryLower.split(/\s+/).filter((t) => t.length > 2);
+
+    return agents
+      .map((agent) => {
+        let score = 0;
+        const searchText = `${agent.name} ${agent.description} ${agent.categories.join(" ")} ${agent.capabilities.join(" ")}`.toLowerCase();
+
+        // Term matching (BM25-lite)
+        for (const term of queryTerms) {
+          if (agent.name.toLowerCase().includes(term)) score += 10;
+          if (agent.description.toLowerCase().includes(term)) score += 5;
+          if (agent.categories.some((c) => c.includes(term))) score += 8;
+          if (agent.capabilities.some((c) => c.toLowerCase().includes(term))) score += 3;
+        }
+
+        // Reputation bonus
+        if (agent.reputation) {
+          score += Math.min(agent.reputation.score * 2, 20);
+          score += Math.min(agent.reputation.count, 10);
+        }
+
+        // Verified bonus
+        if (agent.verified) score += 5;
+
+        // Has pricing info bonus (transparency)
+        if (agent.pricing && agent.pricing.model !== "unknown") score += 3;
+
+        // Has multiple endpoints bonus (more interoperable)
+        const endpointCount = Object.values(agent.endpoints).filter(Boolean).length;
+        score += endpointCount * 2;
+
+        // Protocol diversity bonus
+        if (agent.protocol === "mcp") score += 2; // MCP is most interoperable
+        if (agent.protocol === "a2a") score += 2;
+
+        (agent as any)._score = score;
+        return agent;
+      })
+      .sort((a, b) => ((b as any)._score ?? 0) - ((a as any)._score ?? 0));
+  }
+}

package/src/backends/acp.ts

@@ -0,0 +1,199 @@
+import AcpClient, {
+  AcpContractClientV2,
+  baseSepoliaAcpConfigV2,
+  baseAcpConfigV2,
+  type AcpAgent,
+  type AcpJob,
+} from "@virtuals-protocol/acp-node";
+import type { Address, Hex } from "viem";
+import type {
+  EscrowBackend,
+  AgentSearchResult,
+  AgentOffering,
+  JobResult,
+  BrowseOptions,
+  IncomingJob,
+} from "./types.js";
+
+export interface AcpBackendConfig {
+  /** Private key for the agent wallet (whitelisted on ACP) */
+  privateKey: string;
+  /** Agent's wallet address on ACP */
+  walletAddress: Address;
+  /** Entity/session key address from ACP registration */
+  entityAddress: Address;
+  /** Network: "base-sepolia" or "base" */
+  network?: "base-sepolia" | "base";
+  /** Custom RPC URL */
+  rpcUrl?: string;
+}
+
+export class AcpEscrowBackend implements EscrowBackend {
+  private client!: AcpClient;
+  private config: AcpBackendConfig;
+  private jobHandlers = new Map<string, (job: IncomingJob) => Promise<unknown>>();
+
+  constructor(config: AcpBackendConfig) {
+    this.config = config;
+  }
+
+  name(): string {
+    return "virtuals-acp";
+  }
+
+  async init(): Promise<void> {
+    const acpConfig =
+      this.config.network === "base"
+        ? baseAcpConfigV2
+        : baseSepoliaAcpConfigV2;
+
+    const contractClient = await (AcpContractClientV2 as any).build(
+      this.config.privateKey,
+      this.config.entityAddress,
+      this.config.walletAddress,
+      this.config.rpcUrl,
+      acpConfig
+    );
+
+    this.client = new AcpClient({
+      acpContractClient: contractClient,
+      walletAddress: this.config.walletAddress as string,
+      entityAddress: this.config.entityAddress as string,
+      onNewTask: (job: any) => this.handleIncomingJob(job),
+    } as any);
+
+    await this.client.init();
+  }
+
+  async browseAgents(
+    query: string,
+    options?: BrowseOptions
+  ): Promise<AgentSearchResult[]> {
+    const agents = await this.client.browseAgents({
+      keyword: query,
+      onlineStatus: options?.onlineOnly ? "online" : "all",
+      limit: options?.limit ?? 20,
+      sortBy: options?.sortBy === "successRate" ? "successRate" : undefined,
+    } as any);
+
+    return (agents ?? []).map((agent: AcpAgent) =>
+      this.mapAcpAgent(agent)
+    );
+  }
+
+  async hireAgent(
+    agent: AgentSearchResult,
+    offeringId: string,
+    requirements: Record<string, unknown>,
+    _budget?: bigint
+  ): Promise<JobResult> {
+    const job = await (this.client as any).initiateJob({
+      providerAddress: agent.address,
+      jobOfferingId: offeringId,
+      requirements,
+      skipEvaluation: true,
+    });
+
+    return {
+      jobId: (job as any).id ?? String(job),
+      phase: "REQUEST",
+      deliverable: null,
+    };
+  }
+
+  async waitForResult(
+    jobId: string,
+    timeoutMs = 300_000
+  ): Promise<JobResult> {
+    const start = Date.now();
+    const pollInterval = 5_000;
+
+    while (Date.now() - start < timeoutMs) {
+      const job = await this.client.getJobById(Number(jobId));
+      const phase = (job as any)?.phase ?? (job as any)?.status;
+
+      if (phase === "COMPLETED" || phase === "completed") {
+        return {
+          jobId,
+          phase: "COMPLETED",
+          deliverable: (job as any)?.deliverable ?? (job as any)?.result,
+          txHash: (job as any)?.txHash,
+        };
+      }
+
+      if (phase === "CANCELLED" || phase === "REJECTED" || phase === "EXPIRED") {
+        return {
+          jobId,
+          phase,
+          deliverable: null,
+        };
+      }
+
+      await new Promise((r) => setTimeout(r, pollInterval));
+    }
+
+    throw new Error(`Timeout waiting for job ${jobId} (${timeoutMs}ms)`);
+  }
+
+  async acceptJobs(
+    capabilities: string[],
+    handler: (job: IncomingJob) => Promise<unknown>
+  ): Promise<void> {
+    for (const cap of capabilities) {
+      this.jobHandlers.set(cap, handler);
+    }
+    // The onNewTask callback set during init() will dispatch to handlers
+    console.log(`[ACP] Listening for jobs: ${capabilities.join(", ")}`);
+  }
+
+  private async handleIncomingJob(acpJob: AcpJob): Promise<void> {
+    const job: IncomingJob = {
+      jobId: (acpJob as any).id,
+      description: (acpJob as any).requirement?.description ?? "",
+      requirements: (acpJob as any).requirement ?? {},
+      budget: BigInt((acpJob as any).price ?? 0),
+      clientAddress: (acpJob as any).clientAddress as Address,
+    };
+
+    // Find a matching handler
+    for (const [, handler] of this.jobHandlers) {
+      try {
+        const result = await handler(job);
+        // Deliver the result back through ACP
+        await (acpJob as any).deliver?.({
+          content: typeof result === "string" ? result : JSON.stringify(result),
+          contentType: "application/json",
+        });
+        return;
+      } catch (err) {
+        console.error(`[ACP] Handler failed for job ${job.jobId}:`, err);
+      }
+    }
+  }
+
+  private mapAcpAgent(agent: AcpAgent): AgentSearchResult {
+    const offerings: AgentOffering[] = ((agent as any).jobOfferings ?? []).map(
+      (o: any) => ({
+        id: o.id,
+        name: o.name ?? o.title ?? "Service",
+        description: o.description ?? "",
+        price: BigInt(o.price ?? 0),
+        currency: "USDC",
+      })
+    );
+
+    return {
+      id: (agent as any).id ?? (agent as any).walletAddress,
+      name: (agent as any).name ?? "Unknown Agent",
+      address: ((agent as any).walletAddress ?? (agent as any).contractAddress) as Address,
+      description: (agent as any).description ?? "",
+      categories: (agent as any).tags ?? (agent as any).categories ?? [],
+      offerings,
+      metrics: {
+        successRate: (agent as any).metrics?.successRate,
+        completedJobs: (agent as any).metrics?.completedJobs,
+      },
+      source: "acp",
+    };
+  }
+}

package/src/backends/types.ts

@@ -0,0 +1,78 @@
+import type { Address, Hex } from "viem";
+
+/**
+ * Abstraction over escrow backends (Kompass native or Virtuals ACP).
+ * The simplified SDK uses this interface so it can swap backends
+ * without changing any user-facing code.
+ */
+
+export interface AgentSearchResult {
+  id: string;
+  name: string;
+  address: Address;
+  description: string;
+  categories: string[];
+  offerings: AgentOffering[];
+  metrics?: {
+    successRate?: number;
+    completedJobs?: number;
+  };
+  source: "acp" | "kompass";
+}
+
+export interface AgentOffering {
+  id: string;
+  name: string;
+  description: string;
+  price: bigint;
+  currency: string;
+}
+
+export interface JobResult {
+  jobId: string;
+  phase: string;
+  deliverable: unknown;
+  txHash?: string;
+}
+
+export interface EscrowBackend {
+  /** Initialize the backend (auth, websocket connections, etc.) */
+  init(): Promise<void>;
+
+  /** Search for agents that can do a task */
+  browseAgents(query: string, options?: BrowseOptions): Promise<AgentSearchResult[]>;
+
+  /** Create and fund a job with an agent */
+  hireAgent(
+    agent: AgentSearchResult,
+    offeringId: string,
+    requirements: Record<string, unknown>,
+    budget?: bigint
+  ): Promise<JobResult>;
+
+  /** Poll/wait for a job to complete */
+  waitForResult(jobId: string, timeoutMs?: number): Promise<JobResult>;
+
+  /** Register as a seller and listen for incoming jobs */
+  acceptJobs(
+    capabilities: string[],
+    handler: (job: IncomingJob) => Promise<unknown>
+  ): Promise<void>;
+
+  /** Get the backend name */
+  name(): string;
+}
+
+export interface BrowseOptions {
+  limit?: number;
+  sortBy?: "successRate" | "completedJobs" | "recent";
+  onlineOnly?: boolean;
+}
+
+export interface IncomingJob {
+  jobId: string;
+  description: string;
+  requirements: Record<string, unknown>;
+  budget: bigint;
+  clientAddress: Address;
+}