kompass-sdk 0.1.0

package/src/bridge.ts

@@ -0,0 +1,263 @@
+/**
+ * Kompass Protocol Bridge
+ * Routes hire/interact requests to the correct protocol handler
+ */
+
+import type { UnifiedAgent, AgentProtocol } from "./sources/types.js";
+
+export interface BridgeHireOptions {
+  task: string;
+  budget?: bigint;
+  timeout?: number;
+  payload?: Record<string, unknown>;
+}
+
+export interface BridgeHireResult {
+  success: boolean;
+  protocol: AgentProtocol;
+  agent: UnifiedAgent;
+  jobId?: string;
+  deliverable?: unknown;
+  txHash?: string;
+  error?: string;
+  durationMs: number;
+}
+
+export class ProtocolBridge {
+  private acpBackend?: any; // AcpEscrowBackend if available
+
+  constructor(options?: { acpBackend?: any }) {
+    this.acpBackend = options?.acpBackend;
+  }
+
+  async hire(agent: UnifiedAgent, options: BridgeHireOptions): Promise<BridgeHireResult> {
+    const start = Date.now();
+
+    try {
+      switch (agent.protocol) {
+        case "acp":
+          return await this.hireViaAcp(agent, options, start);
+        case "x402":
+          return await this.hireViaX402(agent, options, start);
+        case "mcp":
+          return await this.hireViaMcp(agent, options, start);
+        case "a2a":
+          return await this.hireViaA2A(agent, options, start);
+        case "http":
+          return await this.hireViaHttp(agent, options, start);
+        case "l402":
+          return await this.hireViaL402(agent, options, start);
+        default:
+          return {
+            success: false,
+            protocol: agent.protocol,
+            agent,
+            error: `Unsupported protocol: ${agent.protocol}`,
+            durationMs: Date.now() - start,
+          };
+      }
+    } catch (err) {
+      return {
+        success: false,
+        protocol: agent.protocol,
+        agent,
+        error: err instanceof Error ? err.message : String(err),
+        durationMs: Date.now() - start,
+      };
+    }
+  }
+
+  private async hireViaAcp(
+    agent: UnifiedAgent,
+    options: BridgeHireOptions,
+    start: number
+  ): Promise<BridgeHireResult> {
+    if (!this.acpBackend) {
+      return {
+        success: false, protocol: "acp", agent,
+        error: "ACP backend not configured. Initialize KompassUnified with ACP credentials.",
+        durationMs: Date.now() - start,
+      };
+    }
+
+    const offering = (agent.raw as any)?.jobs?.[0] ?? (agent.raw as any)?.jobOfferings?.[0];
+    if (!offering) {
+      return {
+        success: false, protocol: "acp", agent,
+        error: "Agent has no job offerings on ACP",
+        durationMs: Date.now() - start,
+      };
+    }
+
+    const job = await this.acpBackend.hireAgent(
+      agent,
+      offering.id,
+      { description: options.task, ...options.payload },
+      options.budget
+    );
+
+    const result = await this.acpBackend.waitForResult(
+      job.jobId,
+      options.timeout ?? 300_000
+    );
+
+    return {
+      success: result.phase === "COMPLETED",
+      protocol: "acp",
+      agent,
+      jobId: result.jobId,
+      deliverable: result.deliverable,
+      txHash: result.txHash,
+      durationMs: Date.now() - start,
+    };
+  }
+
+  private async hireViaX402(
+    agent: UnifiedAgent,
+    options: BridgeHireOptions,
+    start: number
+  ): Promise<BridgeHireResult> {
+    const endpoint = agent.endpoints.x402;
+    if (!endpoint) {
+      return {
+        success: false, protocol: "x402", agent,
+        error: "No x402 endpoint",
+        durationMs: Date.now() - start,
+      };
+    }
+
+    // Simple HTTP POST — in production would use @x402/fetch for payment
+    const res = await fetch(endpoint, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ task: options.task, ...options.payload }),
+      signal: AbortSignal.timeout(options.timeout ?? 30000),
+    });
+
+    if (res.status === 402) {
+      // Payment required — return the requirement info
+      const paymentHeader = res.headers.get("PAYMENT-REQUIRED") ?? res.headers.get("payment-required");
+      return {
+        success: false, protocol: "x402", agent,
+        error: `Payment required: ${paymentHeader ?? "x402 payment needed"}`,
+        deliverable: { paymentRequired: true, header: paymentHeader },
+        durationMs: Date.now() - start,
+      };
+    }
+
+    const data = await res.json().catch(() => null);
+    return {
+      success: res.ok,
+      protocol: "x402",
+      agent,
+      deliverable: data,
+      durationMs: Date.now() - start,
+    };
+  }
+
+  private async hireViaMcp(
+    agent: UnifiedAgent,
+    options: BridgeHireOptions,
+    start: number
+  ): Promise<BridgeHireResult> {
+    // MCP servers expose tools — we'd need to connect and call specific tools
+    // For hackathon, we return the connection info
+    return {
+      success: true,
+      protocol: "mcp",
+      agent,
+      deliverable: {
+        type: "mcp-server",
+        endpoint: agent.endpoints.mcp,
+        message: "MCP server available. Connect via MCP client to use tools.",
+        tools: agent.capabilities,
+      },
+      durationMs: Date.now() - start,
+    };
+  }
+
+  private async hireViaA2A(
+    agent: UnifiedAgent,
+    options: BridgeHireOptions,
+    start: number
+  ): Promise<BridgeHireResult> {
+    const endpoint = agent.endpoints.a2a;
+    if (!endpoint) {
+      return {
+        success: false, protocol: "a2a", agent,
+        error: "No A2A endpoint",
+        durationMs: Date.now() - start,
+      };
+    }
+
+    // A2A protocol: POST task to agent's endpoint
+    const res = await fetch(endpoint, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        jsonrpc: "2.0",
+        method: "tasks/send",
+        params: {
+          message: { role: "user", parts: [{ type: "text", text: options.task }] },
+        },
+      }),
+      signal: AbortSignal.timeout(options.timeout ?? 30000),
+    });
+
+    const data = await res.json().catch(() => null);
+    return {
+      success: res.ok,
+      protocol: "a2a",
+      agent,
+      deliverable: data,
+      durationMs: Date.now() - start,
+    };
+  }
+
+  private async hireViaHttp(
+    agent: UnifiedAgent,
+    options: BridgeHireOptions,
+    start: number
+  ): Promise<BridgeHireResult> {
+    const endpoint = agent.endpoints.http;
+    if (!endpoint) {
+      return {
+        success: false, protocol: "http", agent,
+        error: "No HTTP endpoint",
+        durationMs: Date.now() - start,
+      };
+    }
+
+    const res = await fetch(endpoint, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ task: options.task, ...options.payload }),
+      signal: AbortSignal.timeout(options.timeout ?? 30000),
+    });
+
+    const data = await res.json().catch(() => null);
+    return {
+      success: res.ok,
+      protocol: "http",
+      agent,
+      deliverable: data,
+      durationMs: Date.now() - start,
+    };
+  }
+
+  private async hireViaL402(
+    agent: UnifiedAgent,
+    options: BridgeHireOptions,
+    start: number
+  ): Promise<BridgeHireResult> {
+    // L402 requires Lightning payment — return info for now
+    return {
+      success: false,
+      protocol: "l402",
+      agent,
+      error: "L402 Lightning payment required. Use a Lightning wallet to pay the invoice.",
+      deliverable: { endpoint: agent.endpoints.l402, paymentType: "lightning" },
+      durationMs: Date.now() - start,
+    };
+  }
+}

package/src/cli.ts

@@ -0,0 +1,397 @@
+#!/usr/bin/env node
+
+/**
+ * Kompass CLI — Agent Commerce from the Command Line
+ *
+ * Usage:
+ *   npx kompass discover "yield research"
+ *   npx kompass hire "Find best yield on Base" --budget 1
+ *   npx kompass accept-jobs --capabilities "defi,yield"
+ *   npx kompass reputation 0x...
+ */
+
+import { Command } from "commander";
+import { KompassSimple } from "./simple.js";
+import { createAllSources } from "./sources/index.js";
+import { Aggregator } from "./aggregator.js";
+
+const program = new Command();
+
+program
+  .name("kompass")
+  .description("Kompass — The intelligence layer for agent commerce on Base")
+  .version("1.0.0");
+
+// ── Helper ───────────────────────────────────────────────
+
+function getConfig() {
+  const privateKey = process.env.KOMPASS_PRIVATE_KEY ?? process.env.PRIVATE_KEY;
+  if (!privateKey) {
+    console.error("Error: Set KOMPASS_PRIVATE_KEY or PRIVATE_KEY env var");
+    process.exit(1);
+  }
+  return {
+    privateKey,
+    network: (process.env.KOMPASS_NETWORK ?? "base-sepolia") as "base-sepolia" | "base",
+    acpEntityAddress: process.env.ACP_ENTITY_ADDRESS,
+    acpWalletAddress: process.env.ACP_WALLET_ADDRESS,
+    indexerUrl: process.env.KOMPASS_INDEXER_URL,
+    reputationRegistryAddress: process.env.ERC8004_REPUTATION_REGISTRY as `0x${string}` | undefined,
+    rpcUrl: process.env.KOMPASS_RPC_URL ?? process.env.BASE_SEPOLIA_RPC,
+  };
+}
+
+// ── Commands ─────────────────────────────────────────────
+
+program
+  .command("discover <query>")
+  .description("Search for agents on the ACP marketplace with Kompass reputation filtering")
+  .option("-l, --limit <n>", "max results", "10")
+  .option("--online", "only show online agents")
+  .action(async (query: string, opts: { limit: string; online?: boolean }) => {
+    const kompass = await KompassSimple.create(getConfig());
+    const agents = await kompass.discover(query, { limit: parseInt(opts.limit) });
+
+    if (agents.length === 0) {
+      console.log("No agents found.");
+      return;
+    }
+
+    console.log(`\nFound ${agents.length} agents:\n`);
+    for (const agent of agents) {
+      console.log(`  ${agent.name} (${agent.address.slice(0, 10)}...)`);
+      console.log(`    ${agent.description.slice(0, 100)}`);
+      console.log(`    Categories: ${agent.categories.join(", ") || "—"}`);
+      console.log(`    Offerings: ${agent.offerings.length}`);
+      if (agent.metrics?.successRate !== undefined) {
+        console.log(`    Success rate: ${(agent.metrics.successRate * 100).toFixed(0)}%`);
+      }
+      console.log();
+    }
+  });
+
+program
+  .command("hire <task>")
+  .description("Hire an agent to complete a task via ACP escrow")
+  .option("-b, --budget <usdc>", "max budget in USDC", "1")
+  .option("-r, --min-reputation <score>", "minimum ERC-8004 reputation score", "0")
+  .option("-t, --timeout <seconds>", "timeout in seconds", "300")
+  .option("--json", "output as JSON")
+  .action(
+    async (
+      task: string,
+      opts: { budget: string; minReputation: string; timeout: string; json?: boolean }
+    ) => {
+      const kompass = await KompassSimple.create(getConfig());
+
+      console.log(`\nHiring agent for: "${task}"`);
+      console.log(`Budget: $${opts.budget} USDC | Min reputation: ${opts.minReputation}\n`);
+
+      const result = await kompass.hireAgent({
+        task,
+        maxBudget: BigInt(Math.round(parseFloat(opts.budget) * 1_000_000)),
+        minReputation: parseInt(opts.minReputation),
+        timeoutMs: parseInt(opts.timeout) * 1000,
+      });
+
+      if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        console.log(`Agent: ${result.agent.name}`);
+        console.log(`Job ID: ${result.jobId}`);
+        console.log(`Phase: ${result.phase}`);
+        console.log(`Reputation checked: ${result.reputationChecked}`);
+        if (result.txHash) console.log(`TX: ${result.txHash}`);
+        console.log(`\nDeliverable:`);
+        console.log(
+          typeof result.deliverable === "string"
+            ? result.deliverable
+            : JSON.stringify(result.deliverable, null, 2)
+        );
+      }
+    }
+  );
+
+program
+  .command("orchestrate <intent>")
+  .description("Orchestrate a multi-agent pipeline for a complex intent")
+  .option("-b, --budget <usdc>", "total budget in USDC", "5")
+  .option("--risk <level>", "risk tolerance: conservative, balanced, aggressive", "balanced")
+  .option("--json", "output as JSON")
+  .action(
+    async (
+      intent: string,
+      opts: { budget: string; risk: string; json?: boolean }
+    ) => {
+      const kompass = await KompassSimple.create(getConfig());
+
+      console.log(`\nOrchestrating: "${intent}"`);
+      console.log(`Budget: $${opts.budget} USDC | Risk: ${opts.risk}\n`);
+
+      const result = await kompass.orchestrate({
+        intent,
+        riskTolerance: opts.risk as "conservative" | "balanced" | "aggressive",
+        budget: BigInt(Math.round(parseFloat(opts.budget) * 1_000_000)),
+      });
+
+      if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        console.log(`Completed ${result.completedSteps}/${result.steps.length} steps`);
+        console.log(`Total cost: $${result.totalCostUSDC} USDC\n`);
+        for (const step of result.steps) {
+          const status = step.skipped ? "SKIPPED" : "DONE";
+          const agent = step.agent?.name ?? "—";
+          console.log(`  [${status}] ${step.role}: ${agent}`);
+          if (step.reason) console.log(`    Reason: ${step.reason}`);
+        }
+      }
+    }
+  );
+
+program
+  .command("accept-jobs")
+  .description("Start listening for incoming ACP jobs")
+  .option("-c, --capabilities <list>", "comma-separated capabilities", "general")
+  .action(async (opts: { capabilities: string }) => {
+    const kompass = await KompassSimple.create(getConfig());
+    const capabilities = opts.capabilities.split(",").map((s) => s.trim());
+
+    console.log(`\nListening for jobs: ${capabilities.join(", ")}`);
+    console.log("Press Ctrl+C to stop.\n");
+
+    await kompass.acceptJobs({
+      capabilities,
+      handler: async (job) => {
+        console.log(`\nReceived job: ${job.jobId}`);
+        console.log(`  Description: ${job.description}`);
+        console.log(`  Budget: ${job.budget}`);
+        // Default handler just acknowledges
+        return { status: "received", jobId: job.jobId, message: "Job acknowledged" };
+      },
+    });
+
+    // Keep alive
+    await new Promise(() => {});
+  });
+
+program
+  .command("balance")
+  .description("Check your wallet balance")
+  .action(async () => {
+    const config = getConfig();
+    const { privateKeyToAccount } = await import("viem/accounts");
+    const { createPublicClient, http, formatEther, formatUnits } = await import("viem");
+    const { baseSepolia } = await import("viem/chains");
+
+    const account = privateKeyToAccount(config.privateKey as `0x${string}`);
+    const client = createPublicClient({
+      chain: baseSepolia,
+      transport: http(config.rpcUrl ?? "https://sepolia.base.org"),
+    });
+
+    const eth = await client.getBalance({ address: account.address });
+    console.log(`\nAddress: ${account.address}`);
+    console.log(`ETH: ${formatEther(eth)}`);
+    console.log(`Backend: ACP (Virtuals Protocol)`);
+  });
+
+// ── Core Command: Do ─────────────────────────────────────
+
+program
+  .command("do <task>")
+  .description("Get any job done — finds the right capability across all protocols and executes it")
+  .option("-b, --budget <usd>", "max budget in USD", "1")
+  .option("-c, --cost <preference>", "cheapest | balanced | best-quality", "balanced")
+  .option("-p, --protocol <protocol>", "prefer specific protocol (acp, x402, mcp, skill)")
+  .option("--dry-run", "show options without executing")
+  .option("--json", "output as JSON")
+  .action(
+    async (
+      task: string,
+      opts: { budget: string; cost: string; protocol?: string; dryRun?: boolean; json?: boolean }
+    ) => {
+      const { KompassUnified } = await import("./unified.js");
+      const kompass = await KompassUnified.create();
+
+      if (!opts.json) {
+        console.log(`\n⚡ Kompass: Getting it done — "${task}"\n`);
+      }
+
+      const result = await kompass.do({
+        task,
+        maxBudgetUSD: parseFloat(opts.budget),
+        costPreference: opts.cost as any,
+        preferProtocol: opts.protocol,
+        dryRun: opts.dryRun,
+      });
+
+      if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+      }
+
+      console.log(`Sources queried: ${result.discovery.sourcesQueried} (${result.discovery.queryTimeMs}ms)`);
+      console.log(`Options found: ${result.options.length}\n`);
+
+      if (result.options.length > 0) {
+        console.log("Top options:");
+        for (const opt of result.options.slice(0, 5)) {
+          const cost = opt.estimatedCost !== null ? `$${opt.estimatedCost}` : "unknown";
+          console.log(`  [${opt.protocol.toUpperCase()}] ${opt.agent.name} (${opt.source}) — ${cost}`);
+          console.log(`    ${opt.why}`);
+        }
+      }
+
+      if (result.selected) {
+        console.log(`\n${opts.dryRun ? "Would select" : "Selected"}: ${result.selected.agent.name} [${result.selected.protocol}]`);
+        console.log(`Reasoning: ${result.reasoning}`);
+      }
+
+      if (result.execution) {
+        console.log(`\nExecution: ${result.execution.success ? "✅ Success" : "❌ Failed"}`);
+        if (result.execution.error) console.log(`Error: ${result.execution.error}`);
+        if (result.execution.deliverable) {
+          console.log(`\nDeliverable:`);
+          console.log(typeof result.execution.deliverable === "string"
+            ? result.execution.deliverable.slice(0, 500)
+            : JSON.stringify(result.execution.deliverable, null, 2).slice(0, 500));
+        }
+      }
+
+      console.log();
+    }
+  );
+
+// ── A2A Server Command ───────────────────────────────────
+
+program
+  .command("serve")
+  .description("Start Kompass as an A2A-compatible agent server")
+  .option("-p, --port <port>", "port to listen on", "3000")
+  .action(async (opts: { port: string }) => {
+    const { startA2AServer } = await import("./a2a/server.js");
+    const { KompassUnified } = await import("./unified.js");
+    const kompass = await KompassUnified.create();
+    await startA2AServer({ port: parseInt(opts.port), kompass });
+  });
+
+program
+  .command("coordinate <intent>")
+  .description("Coordinate multiple agents across protocols via A2A")
+  .option("--steps <roles>", "comma-separated roles", "research,analysis")
+  .option("--json", "output as JSON")
+  .action(async (intent: string, opts: { steps: string; json?: boolean }) => {
+    const { KompassUnified } = await import("./unified.js");
+    const { A2ABridge } = await import("./a2a/bridge.js");
+    const { ProtocolBridge } = await import("./bridge.js");
+
+    const kompass = await KompassUnified.create();
+    const bridge = new A2ABridge(new ProtocolBridge());
+
+    const roles = opts.steps.split(",").map((r) => r.trim());
+    const steps = roles.map((role, i) => ({
+      id: role,
+      role,
+      query: `${role} ${intent}`,
+      dependsOn: i > 0 ? roles[i - 1] : undefined,
+    }));
+
+    console.log(`\n🔗 Coordinating ${roles.length} agents for: "${intent}"\n`);
+
+    const result = await bridge.coordinate(steps, async (query) => {
+      const found = await kompass.find(query, { limit: 3 });
+      return found.agents[0] ?? null;
+    });
+
+    if (opts.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      for (const step of result.steps) {
+        const status = step.success ? "✅" : step.skipped ? "⏭️" : "❌";
+        const agent = step.agent ? `${step.agent.name} [${step.agent.protocol}]` : "no agent";
+        console.log(`  ${status} ${step.role}: ${agent}`);
+        if (step.error) console.log(`     Error: ${step.error}`);
+      }
+      console.log(`\n${result.completedCount}/${result.totalCount} steps completed\n`);
+    }
+  });
+
+// ── Universal Discovery Commands ─────────────────────────
+
+program
+  .command("find <query>")
+  .description("Search for agents across ALL registries (ACP, MCP, ERC-8004, x402, A2A, L402)")
+  .option("-l, --limit <n>", "max results", "20")
+  .option("-s, --source <sources...>", "filter by source (e.g., acp mcp-registry x402-ecosystem)")
+  .option("--json", "output as JSON")
+  .action(async (query: string, opts: { limit: string; source?: string[]; json?: boolean }) => {
+    console.log(`\n🔍 Searching across all agent registries for: "${query}"\n`);
+
+    const sources = createAllSources();
+    const aggregator = new Aggregator(sources);
+
+    const result = await aggregator.search(query, {
+      limit: parseInt(opts.limit),
+      sources: opts.source,
+    });
+
+    if (opts.json) {
+      console.log(JSON.stringify(result, null, 2));
+      return;
+    }
+
+    // Print source stats
+    console.log("Sources queried:");
+    for (const src of result.sources) {
+      const status = src.error ? `❌ ${src.error}` : `✅ ${src.count} agents`;
+      console.log(`  ${src.name.padEnd(20)} ${status} (${src.durationMs}ms)`);
+    }
+
+    console.log(`\nFound ${result.totalFound} agents (${result.deduplicated} duplicates removed)`);
+    console.log(`Query time: ${result.queryTimeMs}ms\n`);
+
+    if (result.agents.length === 0) {
+      console.log("No agents found.");
+      return;
+    }
+
+    console.log("─".repeat(80));
+    for (const agent of result.agents) {
+      const score = (agent as any)._score ?? 0;
+      const rep = agent.reputation ? ` | rep: ${agent.reputation.score}/${agent.reputation.count}` : "";
+      const price = agent.pricing?.amount ? ` | $${agent.pricing.amount} ${agent.pricing.currency ?? ""}` : "";
+      const protocol = agent.protocol.toUpperCase();
+
+      console.log(`  [${protocol}] ${agent.name} (${agent.source})`);
+      console.log(`    ${agent.description.slice(0, 120)}`);
+      console.log(`    Categories: ${agent.categories.join(", ")} | Score: ${score}${rep}${price}`);
+      if (agent.endpoints.x402) console.log(`    x402: ${agent.endpoints.x402}`);
+      if (agent.endpoints.mcp) console.log(`    MCP: ${agent.endpoints.mcp}`);
+      console.log();
+    }
+    console.log("─".repeat(80));
+  });
+
+program
+  .command("sources")
+  .description("List all available discovery sources and their health status")
+  .action(async () => {
+    console.log("\n📡 Checking discovery sources...\n");
+
+    const sources = createAllSources();
+    const aggregator = new Aggregator(sources);
+    const health = await aggregator.healthCheck();
+
+    for (const src of health) {
+      const status = src.healthy ? "🟢 ONLINE" : "🔴 OFFLINE";
+      console.log(`  ${status} ${src.displayName} (${src.name})`);
+    }
+
+    const online = health.filter((h) => h.healthy).length;
+    console.log(`\n${online}/${health.length} sources online\n`);
+  });
+
+// ── Run ──────────────────────────────────────────────────
+
+program.parse();