kompass-sdk 0.1.0

package/src/unified.ts

@@ -0,0 +1,155 @@
+/**
+ * KompassUnified — Universal Agent Discovery + Coordination
+ *
+ * The Google for AI agents. One API that searches across ALL registries
+ * and lets you hire any agent regardless of protocol.
+ *
+ * @example
+ * const kompass = await KompassUnified.create({ network: "base-sepolia" });
+ * const agents = await kompass.find("yield optimization");
+ * const result = await kompass.hire(agents[0], "Find best yield on Base");
+ */
+
+import { createAllSources, type SourceAdapter, type UnifiedAgent } from "./sources/index.js";
+import { Aggregator, type AggregatorOptions, type AggregatorResult } from "./aggregator.js";
+import { rankAgents, type MatchResult } from "./matching.js";
+import { ProtocolBridge, type BridgeHireOptions, type BridgeHireResult } from "./bridge.js";
+import { CapabilityRouter, type DoOptions, type DoResult } from "./router.js";
+
+export interface UnifiedConfig {
+  /** Network for on-chain sources */
+  network?: "base" | "base-sepolia";
+  /** Which sources to enable (default: all) */
+  enabledSources?: string[];
+  /** ACP backend instance (for hiring via ACP) */
+  acpBackend?: any;
+  /** Kompass SDK config (for kompass-registry source) */
+  kompassConfig?: any;
+}
+
+export interface FindOptions {
+  /** Max results */
+  limit?: number;
+  /** Filter by source */
+  sources?: string[];
+  /** Timeout per source in ms */
+  timeout?: number;
+  /** Minimum match score (0-100) */
+  minScore?: number;
+}
+
+export interface FindResult extends AggregatorResult {
+  /** Agents re-ranked by multi-layer matching */
+  ranked: MatchResult[];
+}
+
+export class KompassUnified {
+  private aggregator: Aggregator;
+  private bridge: ProtocolBridge;
+  private router: CapabilityRouter;
+  private adapters: SourceAdapter[];
+
+  private constructor(adapters: SourceAdapter[], bridge: ProtocolBridge) {
+    this.adapters = adapters;
+    this.aggregator = new Aggregator(adapters);
+    this.bridge = bridge;
+    this.router = new CapabilityRouter(this.aggregator, this.bridge);
+  }
+
+  static async create(config?: UnifiedConfig): Promise<KompassUnified> {
+    const adapters = createAllSources({
+      erc8004Network: config?.network ?? "base-sepolia",
+      kompassConfig: config?.kompassConfig,
+      enabledSources: config?.enabledSources,
+    });
+
+    const bridge = new ProtocolBridge({
+      acpBackend: config?.acpBackend,
+    });
+
+    return new KompassUnified(adapters, bridge);
+  }
+
+  /**
+   * Search for agents across all registries.
+   * Returns results ranked by multi-layer matching (structured + BM25 + multi-criteria).
+   */
+  async find(query: string, options?: FindOptions): Promise<FindResult> {
+    const aggregatorResult = await this.aggregator.search(query, {
+      limit: (options?.limit ?? 20) * 2, // Over-fetch for re-ranking
+      sources: options?.sources,
+      timeout: options?.timeout,
+    });
+
+    // Re-rank with multi-layer matching
+    const ranked = rankAgents(aggregatorResult.agents, query);
+
+    // Apply limit and min score
+    const filtered = options?.minScore
+      ? ranked.filter((r) => r.scores.total >= options.minScore!)
+      : ranked;
+
+    return {
+      ...aggregatorResult,
+      agents: filtered.slice(0, options?.limit ?? 20).map((r) => r.agent),
+      ranked: filtered.slice(0, options?.limit ?? 20),
+    };
+  }
+
+  /**
+   * Hire a specific agent via its native protocol.
+   * The bridge routes to ACP, x402, MCP, A2A, HTTP, or L402 automatically.
+   */
+  async hire(agent: UnifiedAgent, task: string, options?: Partial<BridgeHireOptions>): Promise<BridgeHireResult> {
+    return this.bridge.hire(agent, { task, ...options });
+  }
+
+  /**
+   * Find the best agent for a task and hire it.
+   * One function: discover → rank → hire.
+   */
+  async findAndHire(
+    query: string,
+    task: string,
+    options?: FindOptions & Partial<BridgeHireOptions>
+  ): Promise<{ discovery: FindResult; hire: BridgeHireResult }> {
+    const discovery = await this.find(query, options);
+
+    if (discovery.agents.length === 0) {
+      throw new Error(`No agents found for: "${query}"`);
+    }
+
+    const bestAgent = discovery.agents[0];
+    const hireResult = await this.hire(bestAgent, task, options);
+
+    return { discovery, hire: hireResult };
+  }
+
+  /**
+   * Check health of all discovery sources.
+   */
+  async sources(): Promise<{ name: string; displayName: string; healthy: boolean }[]> {
+    return this.aggregator.healthCheck();
+  }
+
+  /**
+   * Get any job done. The core Kompass function.
+   *
+   * Discovers the right capability across all protocols, picks the best option,
+   * executes via the right payment rail, and returns the result.
+   *
+   * @example
+   * const result = await kompass.do({ task: "get DeFi yield data for Base" });
+   * console.log(result.execution?.deliverable);
+   */
+  async do(options: DoOptions): Promise<DoResult> {
+    return this.router.do(options);
+  }
+
+  /**
+   * Get the number of registered source adapters.
+   */
+  get sourceCount(): number {
+    return this.adapters.length;
+  }
+}

package/src/x402.ts

@@ -0,0 +1,122 @@
+import type { PaymentMode } from "./types.js";
+
+export interface X402PaymentRequirement {
+  protocol: PaymentMode | "unknown";
+  amount?: string;
+  asset?: string;
+  payTo?: string;
+  facilitator?: string;
+  network?: string;
+  scheme?: string;
+  raw: unknown;
+  rawBody?: string;
+  rawHeaders: Record<string, string>;
+}
+
+export interface X402PaymentRequestContext {
+  url: string;
+  init: RequestInit;
+  response: Response;
+  requirement: X402PaymentRequirement;
+}
+
+export interface X402PaymentResponse {
+  headers?: HeadersInit;
+}
+
+export interface X402ClientOptions {
+  fetchFn?: typeof fetch;
+  parseRequirement?: (response: Response) => Promise<X402PaymentRequirement>;
+  onPaymentRequired: (context: X402PaymentRequestContext) => Promise<X402PaymentResponse>;
+}
+
+function headersToObject(headers: Headers): Record<string, string> {
+  return Object.fromEntries(headers.entries());
+}
+
+function detectProtocol(raw: unknown): X402PaymentRequirement["protocol"] {
+  if (raw && typeof raw === "object") {
+    const protocol = Reflect.get(raw, "protocol");
+    if (protocol === "x402" || protocol === "escrow" || protocol === "hybrid") {
+      return protocol;
+    }
+  }
+  return "unknown";
+}
+
+export async function parseX402Requirement(response: Response): Promise<X402PaymentRequirement> {
+  const rawHeaders = headersToObject(response.headers);
+  const headerPayload =
+    response.headers.get("x-payment-requirement") ??
+    response.headers.get("x-payment-requirements") ??
+    response.headers.get("x-402-payment-requirement");
+
+  let raw: unknown = headerPayload ?? {};
+  let rawBody: string | undefined;
+
+  if (headerPayload) {
+    try {
+      raw = JSON.parse(headerPayload);
+    } catch {
+      raw = { value: headerPayload };
+    }
+  } else {
+    rawBody = await response.clone().text();
+    try {
+      raw = JSON.parse(rawBody);
+    } catch {
+      raw = { value: rawBody };
+    }
+  }
+
+  const payload = raw && typeof raw === "object" ? raw as Record<string, unknown> : {};
+  const accepts = Array.isArray(payload.accepts) ? payload.accepts[0] : undefined;
+  const requirement = (accepts && typeof accepts === "object" ? accepts : payload) as Record<string, unknown>;
+
+  return {
+    protocol: detectProtocol(requirement),
+    amount: typeof requirement.amount === "string" ? requirement.amount : undefined,
+    asset: typeof requirement.asset === "string" ? requirement.asset : undefined,
+    payTo: typeof requirement.payTo === "string" ? requirement.payTo : undefined,
+    facilitator: typeof requirement.facilitator === "string" ? requirement.facilitator : undefined,
+    network: typeof requirement.network === "string" ? requirement.network : undefined,
+    scheme: typeof requirement.scheme === "string" ? requirement.scheme : undefined,
+    raw,
+    rawBody,
+    rawHeaders,
+  };
+}
+
+function mergeHeaders(base?: HeadersInit, extra?: HeadersInit): Headers {
+  const headers = new Headers(base);
+  if (!extra) return headers;
+  const extraHeaders = new Headers(extra);
+  extraHeaders.forEach((value, key) => headers.set(key, value));
+  return headers;
+}
+
+export async function requestWithX402(
+  url: string,
+  init: RequestInit,
+  options: X402ClientOptions
+): Promise<Response> {
+  const fetchFn = options.fetchFn ?? fetch;
+  const firstResponse = await fetchFn(url, init);
+
+  if (firstResponse.status !== 402) {
+    return firstResponse;
+  }
+
+  const requirement = await (options.parseRequirement ?? parseX402Requirement)(firstResponse);
+  const payment = await options.onPaymentRequired({
+    url,
+    init,
+    response: firstResponse,
+    requirement,
+  });
+
+  return fetchFn(url, {
+    ...init,
+    headers: mergeHeaders(init.headers, payment.headers),
+  });
+}

package/tests/pipelineFlow.test.ts

@@ -0,0 +1,239 @@
+import { describe, expect, it, vi } from "vitest";
+import { encodeAbiParameters, encodeEventTopics, keccak256, toHex, type Address, type Hex } from "viem";
+import { routeYieldIntent } from "../src/intents.js";
+import { buildYieldPipelinePlan, createYieldPipeline } from "../src/pipelines.js";
+import { PipelineOrchestratorAbi } from "../src/pipelineAbi.js";
+import type { AgentProfile, KompassConfig } from "../src/types.js";
+
+const RESEARCH_AGENT = "0x1000000000000000000000000000000000000001" as Address;
+const DATA_AGENT = "0x1000000000000000000000000000000000000002" as Address;
+const RISK_AGENT = "0x1000000000000000000000000000000000000003" as Address;
+const EXECUTION_AGENT = "0x1000000000000000000000000000000000000004" as Address;
+const PIPELINE_ADDRESS = "0x2000000000000000000000000000000000000001" as Address;
+const TOKEN_ADDRESS = "0x2000000000000000000000000000000000000002" as Address;
+
+function makeAgent(overrides: Partial<AgentProfile> & Pick<AgentProfile, "id" | "agentType" | "categories">): AgentProfile {
+  return {
+    id: overrides.id,
+    ensNode: "0x1111111111111111111111111111111111111111111111111111111111111111",
+    ensName: "",
+    agentType: overrides.agentType,
+    categories: overrides.categories,
+    pricingModel: "fixed",
+    pricingRate: "0",
+    pricingToken: TOKEN_ADDRESS,
+    erc8004Id: "1",
+    identityVerification: "agent-registration[0xregistry][1]",
+    identityVerified: true,
+    paymentMode: "escrow",
+    endpointMcp: "",
+    endpointA2a: "",
+    endpointX402: "",
+    x402Enabled: false,
+    evaluatorDomains: "",
+    description: "Kompass test agent",
+    registered: true,
+    registeredAt: 1n,
+    updatedAt: 1n,
+    ...overrides,
+  };
+}
+
+function createPipelineCreatedLog(pipelineId: bigint, client: Address, intentHash: Hex) {
+  const topics = encodeEventTopics({
+    abi: PipelineOrchestratorAbi,
+    eventName: "PipelineCreated",
+    args: {
+      pipelineId,
+      client,
+    },
+  });
+
+  const data = encodeAbiParameters([{ name: "intentHash", type: "bytes32" }], [intentHash]);
+
+  return {
+    address: PIPELINE_ADDRESS,
+    topics,
+    data,
+    blockHash: "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" as Hex,
+    blockNumber: 1n,
+    transactionHash: "0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb" as Hex,
+    transactionIndex: 0,
+    logIndex: 0,
+    removed: false,
+  };
+}
+
+describe("Kompass pipeline flow", () => {
+  const agents: AgentProfile[] = [
+    makeAgent({
+      id: RESEARCH_AGENT,
+      ensName: "research.kompass.eth",
+      agentType: "provider",
+      categories: "defi,analytics,yield,research",
+      paymentMode: "hybrid",
+      pricingRate: "1250000",
+    }),
+    makeAgent({
+      id: DATA_AGENT,
+      ensName: "data.kompass.eth",
+      agentType: "provider",
+      categories: "data,analytics,signals",
+      paymentMode: "x402",
+      endpointX402: "https://api.kompass.test",
+      x402Enabled: true,
+      pricingRate: "500000",
+    }),
+    makeAgent({
+      id: RISK_AGENT,
+      ensName: "risk.kompass.eth",
+      agentType: "evaluator",
+      categories: "risk,security,defi",
+      paymentMode: "hybrid",
+      pricingRate: "1000000",
+    }),
+    makeAgent({
+      id: EXECUTION_AGENT,
+      ensName: "execute.kompass.eth",
+      agentType: "provider",
+      categories: "yield,swap,bridge,defi",
+      paymentMode: "escrow",
+      pricingRate: "1500000",
+    }),
+  ];
+
+  it("routes the intent and keeps x402 premium data offchain", () => {
+    const route = routeYieldIntent(agents, {
+      amount: 1_000_000_000n,
+      riskTolerance: "balanced",
+      chain: "Base",
+      stablecoin: "USDC",
+    });
+
+    expect(route.missingCapabilities).toEqual([]);
+    expect(route.recommendedAgents).toHaveLength(4);
+
+    const plan = buildYieldPipelinePlan(route, { token: TOKEN_ADDRESS });
+
+    expect(plan.offchainSteps).toHaveLength(1);
+    expect(plan.offchainSteps[0].role).toBe("premium-data");
+    expect(plan.offchainSteps[0].endpointX402).toBe("https://api.kompass.test");
+
+    expect(plan.subtasks).toHaveLength(3);
+    expect(plan.subtasks.map((step) => step.role)).toEqual(["research", "risk", "execution"]);
+    expect(plan.subtasks[0].evaluator).toBe(RISK_AGENT);
+    expect(plan.subtasks[1].dependencies).toEqual([0]);
+    expect(plan.subtasks[2].dependencies).toEqual([1]);
+    expect(plan.subtasks[2].evaluator).toBe(RISK_AGENT);
+  });
+
+  it("creates, funds, and activates the escrow-capable pipeline sequence", async () => {
+    const route = routeYieldIntent(agents, {
+      amount: 1_000_000_000n,
+      riskTolerance: "balanced",
+      chain: "Base",
+      stablecoin: "USDC",
+    });
+    const plan = buildYieldPipelinePlan(route, { token: TOKEN_ADDRESS });
+    const pipelineId = 42n;
+
+    const writeContract = vi
+      .fn()
+      .mockResolvedValueOnce("0x0000000000000000000000000000000000000000000000000000000000000001")
+      .mockResolvedValueOnce("0x0000000000000000000000000000000000000000000000000000000000000002")
+      .mockResolvedValueOnce("0x0000000000000000000000000000000000000000000000000000000000000003")
+      .mockResolvedValueOnce("0x0000000000000000000000000000000000000000000000000000000000000004")
+      .mockResolvedValueOnce("0x0000000000000000000000000000000000000000000000000000000000000005")
+      .mockResolvedValueOnce("0x0000000000000000000000000000000000000000000000000000000000000006")
+      .mockResolvedValueOnce("0x0000000000000000000000000000000000000000000000000000000000000007");
+
+    const waitForTransactionReceipt = vi.fn(async ({ hash }: { hash: Hex }) => {
+      if (hash === "0x0000000000000000000000000000000000000000000000000000000000000001") {
+        return {
+          logs: [createPipelineCreatedLog(pipelineId, RESEARCH_AGENT, plan.intentHash)],
+        };
+      }
+      return { logs: [] };
+    });
+
+    const config: KompassConfig = {
+      escrowAddress: "0x3000000000000000000000000000000000000001",
+      registryAddress: "0x3000000000000000000000000000000000000002",
+      reputationRegistryAddress: "0x3000000000000000000000000000000000000003",
+      pipelineAddress: PIPELINE_ADDRESS,
+      paymentTokenAddress: TOKEN_ADDRESS,
+      indexerUrl: "http://localhost:42069/graphql",
+      walletClient: {
+        writeContract,
+      } as unknown as KompassConfig["walletClient"],
+      publicClient: {
+        waitForTransactionReceipt,
+      } as unknown as KompassConfig["publicClient"],
+    };
+
+    const result = await createYieldPipeline(config, route);
+
+    expect(result.pipelineId).toBe(pipelineId);
+    expect(result.approveTxHash).toBe("0x0000000000000000000000000000000000000000000000000000000000000005");
+    expect(result.fundTxHash).toBe("0x0000000000000000000000000000000000000000000000000000000000000006");
+    expect(result.activateTxHash).toBe("0x0000000000000000000000000000000000000000000000000000000000000007");
+
+    expect(writeContract).toHaveBeenCalledTimes(7);
+    expect(writeContract.mock.calls[0][0]).toMatchObject({
+      address: PIPELINE_ADDRESS,
+      functionName: "createPipeline",
+      args: [TOKEN_ADDRESS, keccak256(toHex(route.summary))],
+    });
+    expect(writeContract.mock.calls[1][0]).toMatchObject({
+      address: PIPELINE_ADDRESS,
+      functionName: "addSubTask",
+    });
+    expect(writeContract.mock.calls[1][0].args.slice(0, 4)).toEqual([
+      pipelineId,
+      RESEARCH_AGENT,
+      RISK_AGENT,
+      1_250_000n,
+    ]);
+    expect(writeContract.mock.calls[1][0].args[5]).toEqual([]);
+
+    expect(writeContract.mock.calls[2][0]).toMatchObject({
+      address: PIPELINE_ADDRESS,
+      functionName: "addSubTask",
+    });
+    expect(writeContract.mock.calls[2][0].args.slice(0, 4)).toEqual([
+      pipelineId,
+      RISK_AGENT,
+      RISK_AGENT,
+      1_000_000n,
+    ]);
+    expect(writeContract.mock.calls[2][0].args[5]).toEqual([0n]);
+
+    expect(writeContract.mock.calls[3][0]).toMatchObject({
+      address: PIPELINE_ADDRESS,
+      functionName: "addSubTask",
+    });
+    expect(writeContract.mock.calls[3][0].args.slice(0, 4)).toEqual([
+      pipelineId,
+      EXECUTION_AGENT,
+      RISK_AGENT,
+      1_500_000n,
+    ]);
+    expect(writeContract.mock.calls[3][0].args[5]).toEqual([1n]);
+    expect(writeContract.mock.calls[4][0]).toMatchObject({
+      address: TOKEN_ADDRESS,
+      functionName: "approve",
+      args: [PIPELINE_ADDRESS, 3_750_000n],
+    });
+    expect(writeContract.mock.calls[5][0]).toMatchObject({
+      address: PIPELINE_ADDRESS,
+      functionName: "fundPipeline",
+      args: [pipelineId],
+    });
+    expect(writeContract.mock.calls[6][0]).toMatchObject({
+      address: PIPELINE_ADDRESS,
+      functionName: "activateNextTasks",
+      args: [pipelineId],
+    });
+    expect(waitForTransactionReceipt).toHaveBeenCalledTimes(7);
+  });
+});

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ES2022",
+    "moduleResolution": "bundler",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts"]
+}