kompass-sdk 0.1.0

package/dist/router.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Kompass Capability Router
+ *
+ * The core product logic. Given a task, figure out the best way to get it done.
+ *
+ * kompass.do("get DeFi yield data") →
+ *   1. Parse intent → what capability is needed
+ *   2. Search all sources → where can I get it
+ *   3. Rank options → cost, speed, reliability, reputation
+ *   4. Execute via right protocol → ACP, x402, MCP, skill, A2A
+ *   5. Return result
+ */
+import type { UnifiedAgent } from "./sources/types.js";
+import { Aggregator } from "./aggregator.js";
+import { type MatchResult } from "./matching.js";
+import { ProtocolBridge, type BridgeHireResult } from "./bridge.js";
+export type CostPreference = "cheapest" | "balanced" | "best-quality";
+export interface DoOptions {
+    /** What you want done — natural language */
+    task: string;
+    /** Cost preference */
+    costPreference?: CostPreference;
+    /** Max budget in USD (e.g., 1.0 = $1) */
+    maxBudgetUSD?: number;
+    /** Prefer specific protocol */
+    preferProtocol?: string;
+    /** Prefer specific source */
+    preferSource?: string;
+    /** Timeout per capability in ms */
+    timeout?: number;
+    /** Return options without executing (dry run) */
+    dryRun?: boolean;
+    /** Additional payload to send to the capability */
+    payload?: Record<string, unknown>;
+}
+export interface CapabilityOption {
+    agent: UnifiedAgent;
+    scores: MatchResult["scores"];
+    estimatedCost: number | null;
+    protocol: string;
+    source: string;
+    why: string;
+}
+export interface DoResult {
+    success: boolean;
+    /** The task that was requested */
+    task: string;
+    /** All options found across protocols */
+    options: CapabilityOption[];
+    /** The option that was selected and executed */
+    selected: CapabilityOption | null;
+    /** Result from executing the selected option */
+    execution: BridgeHireResult | null;
+    /** Discovery metadata */
+    discovery: {
+        sourcesQueried: number;
+        totalFound: number;
+        queryTimeMs: number;
+    };
+    /** Why this option was selected */
+    reasoning: string;
+}
+export declare class CapabilityRouter {
+    private aggregator;
+    private bridge;
+    constructor(aggregator: Aggregator, bridge: ProtocolBridge);
+    do(options: DoOptions): Promise<DoResult>;
+    private buildOption;
+    private applyPreferences;
+    private explainChoice;
+}
+//# sourceMappingURL=router.d.ts.map

package/dist/router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../src/router.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAA2B,KAAK,WAAW,EAAE,MAAM,eAAe,CAAC;AAC1E,OAAO,EAAE,cAAc,EAAE,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEpE,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG,UAAU,GAAG,cAAc,CAAC;AAEtE,MAAM,WAAW,SAAS;IACxB,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,sBAAsB;IACtB,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,yCAAyC;IACzC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,+BAA+B;IAC/B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,6BAA6B;IAC7B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,mCAAmC;IACnC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iDAAiD;IACjD,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,mDAAmD;IACnD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,YAAY,CAAC;IACpB,MAAM,EAAE,WAAW,CAAC,QAAQ,CAAC,CAAC;IAC9B,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,QAAQ;IACvB,OAAO,EAAE,OAAO,CAAC;IACjB,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B,gDAAgD;IAChD,QAAQ,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAClC,gDAAgD;IAChD,SAAS,EAAE,gBAAgB,GAAG,IAAI,CAAC;IACnC,yBAAyB;IACzB,SAAS,EAAE;QACT,cAAc,EAAE,MAAM,CAAC;QACvB,UAAU,EAAE,MAAM,CAAC;QACnB,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC;IACF,mCAAmC;IACnC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,UAAU,CAAa;IAC/B,OAAO,CAAC,MAAM,CAAiB;gBAEnB,UAAU,EAAE,UAAU,EAAE,MAAM,EAAE,cAAc;IAKpD,EAAE,CAAC,OAAO,EAAE,SAAS,GAAG,OAAO,CAAC,QAAQ,CAAC;IA0F/C,OAAO,CAAC,WAAW;IA2BnB,OAAO,CAAC,gBAAgB;IAyDxB,OAAO,CAAC,aAAa;CA2BtB"}

package/dist/router.js

@@ -0,0 +1,190 @@
+/**
+ * Kompass Capability Router
+ *
+ * The core product logic. Given a task, figure out the best way to get it done.
+ *
+ * kompass.do("get DeFi yield data") →
+ *   1. Parse intent → what capability is needed
+ *   2. Search all sources → where can I get it
+ *   3. Rank options → cost, speed, reliability, reputation
+ *   4. Execute via right protocol → ACP, x402, MCP, skill, A2A
+ *   5. Return result
+ */
+import { rankAgents } from "./matching.js";
+export class CapabilityRouter {
+    aggregator;
+    bridge;
+    constructor(aggregator, bridge) {
+        this.aggregator = aggregator;
+        this.bridge = bridge;
+    }
+    async do(options) {
+        const { task, dryRun = false } = options;
+        // 1. Search all sources
+        const searchResult = await this.aggregator.search(task, {
+            limit: 30,
+            timeout: options.timeout ?? 15000,
+        });
+        if (searchResult.agents.length === 0) {
+            return {
+                success: false,
+                task,
+                options: [],
+                selected: null,
+                execution: null,
+                discovery: {
+                    sourcesQueried: searchResult.sources.length,
+                    totalFound: 0,
+                    queryTimeMs: searchResult.queryTimeMs,
+                },
+                reasoning: "No capabilities found for this task across any registry.",
+            };
+        }
+        // 2. Rank with multi-layer matching
+        const ranked = rankAgents(searchResult.agents, task);
+        // 3. Build options with cost estimates
+        const capabilityOptions = ranked.map((r) => this.buildOption(r, options));
+        // 4. Filter by budget
+        const affordable = options.maxBudgetUSD
+            ? capabilityOptions.filter((o) => o.estimatedCost === null || o.estimatedCost <= options.maxBudgetUSD)
+            : capabilityOptions;
+        // 5. Apply preference-based reranking
+        const reranked = this.applyPreferences(affordable.length > 0 ? affordable : capabilityOptions, options);
+        // 6. Select best option
+        const selected = reranked[0] ?? null;
+        if (!selected) {
+            return {
+                success: false,
+                task,
+                options: capabilityOptions,
+                selected: null,
+                execution: null,
+                discovery: {
+                    sourcesQueried: searchResult.sources.length,
+                    totalFound: searchResult.totalFound,
+                    queryTimeMs: searchResult.queryTimeMs,
+                },
+                reasoning: options.maxBudgetUSD
+                    ? `Found ${capabilityOptions.length} options but none within budget ($${options.maxBudgetUSD}).`
+                    : "No suitable options found after ranking.",
+            };
+        }
+        // 7. Execute (unless dry run)
+        let execution = null;
+        if (!dryRun) {
+            execution = await this.bridge.hire(selected.agent, {
+                task,
+                timeout: options.timeout,
+                payload: options.payload,
+            });
+        }
+        const reasoning = this.explainChoice(selected, reranked, options);
+        return {
+            success: dryRun ? true : (execution?.success ?? false),
+            task,
+            options: capabilityOptions.slice(0, 10), // Top 10 options
+            selected,
+            execution,
+            discovery: {
+                sourcesQueried: searchResult.sources.length,
+                totalFound: searchResult.totalFound,
+                queryTimeMs: searchResult.queryTimeMs,
+            },
+            reasoning,
+        };
+    }
+    buildOption(match, options) {
+        const agent = match.agent;
+        let estimatedCost = null;
+        if (agent.pricing?.amount) {
+            estimatedCost = parseFloat(agent.pricing.amount);
+        }
+        else if (agent.pricing?.model === "free") {
+            estimatedCost = 0;
+        }
+        let why = "";
+        if (match.scores.structured > 10)
+            why += "Strong capability match. ";
+        if (match.scores.bm25 > 5)
+            why += "High text relevance. ";
+        if (match.scores.multiCriteria > 15)
+            why += "Good reputation/trust signals. ";
+        if (estimatedCost === 0)
+            why += "Free. ";
+        if (estimatedCost !== null && estimatedCost > 0 && estimatedCost < 0.05)
+            why += "Very affordable. ";
+        return {
+            agent,
+            scores: match.scores,
+            estimatedCost,
+            protocol: agent.protocol,
+            source: agent.source,
+            why: why.trim() || "General match.",
+        };
+    }
+    applyPreferences(options, doOptions) {
+        let sorted = [...options];
+        // Protocol preference
+        if (doOptions.preferProtocol) {
+            sorted.sort((a, b) => {
+                const aMatch = a.protocol === doOptions.preferProtocol ? 1 : 0;
+                const bMatch = b.protocol === doOptions.preferProtocol ? 1 : 0;
+                return bMatch - aMatch;
+            });
+        }
+        // Source preference
+        if (doOptions.preferSource) {
+            sorted.sort((a, b) => {
+                const aMatch = a.source === doOptions.preferSource ? 1 : 0;
+                const bMatch = b.source === doOptions.preferSource ? 1 : 0;
+                return bMatch - aMatch;
+            });
+        }
+        // Cost preference reranking
+        switch (doOptions.costPreference) {
+            case "cheapest":
+                sorted.sort((a, b) => {
+                    const aCost = a.estimatedCost ?? Infinity;
+                    const bCost = b.estimatedCost ?? Infinity;
+                    return aCost - bCost;
+                });
+                break;
+            case "best-quality":
+                // Already sorted by score, but boost high-reputation agents
+                sorted.sort((a, b) => {
+                    const aRep = a.agent.reputation?.score ?? 0;
+                    const bRep = b.agent.reputation?.score ?? 0;
+                    return bRep - aRep || b.scores.total - a.scores.total;
+                });
+                break;
+            case "balanced":
+            default:
+                // Default: score-based with cost as tiebreaker
+                sorted.sort((a, b) => {
+                    if (Math.abs(b.scores.total - a.scores.total) > 5) {
+                        return b.scores.total - a.scores.total;
+                    }
+                    const aCost = a.estimatedCost ?? 1;
+                    const bCost = b.estimatedCost ?? 1;
+                    return aCost - bCost;
+                });
+                break;
+        }
+        return sorted;
+    }
+    explainChoice(selected, alternatives, options) {
+        const parts = [];
+        parts.push(`Selected "${selected.agent.name}" via ${selected.protocol.toUpperCase()} from ${selected.source}.`);
+        if (selected.estimatedCost !== null) {
+            parts.push(selected.estimatedCost === 0
+                ? "This option is free."
+                : `Estimated cost: $${selected.estimatedCost}.`);
+        }
+        parts.push(selected.why);
+        if (alternatives.length > 1) {
+            parts.push(`${alternatives.length - 1} other options available.`);
+        }
+        return parts.join(" ");
+    }
+}
+//# sourceMappingURL=router.js.map

package/dist/router.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.js","sourceRoot":"","sources":["../src/router.ts"],"names":[],"mappings":"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"}

package/dist/simple.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Kompass Simplified API
+ *
+ * Dead-simple interface for agent-to-agent commerce.
+ * Wraps ACP escrow + Kompass intelligence (reputation, x402, intent routing).
+ *
+ * Usage:
+ *   const kompass = await KompassSimple.create({ privateKey, network: "base-sepolia" });
+ *   const result = await kompass.hireAgent({ task: "Find best yield on Base", maxBudget: 1_000_000n });
+ */
+import type { Address } from "viem";
+import type { AgentSearchResult, IncomingJob } from "./backends/types.js";
+import type { ReputationSummary } from "./types.js";
+export interface KompassSimpleConfig {
+    /** Agent's private key */
+    privateKey: string;
+    /** Network: "base-sepolia" or "base" */
+    network?: "base-sepolia" | "base";
+    /** ACP entity/session key address (from ACP registration) */
+    acpEntityAddress?: string;
+    /** ACP wallet address */
+    acpWalletAddress?: string;
+    /** Kompass indexer URL for ENS discovery + reputation */
+    indexerUrl?: string;
+    /** ERC-8004 reputation registry address */
+    reputationRegistryAddress?: Address;
+    /** Custom RPC URL */
+    rpcUrl?: string;
+}
+export interface HireOptions {
+    /** What you want done — natural language task description */
+    task: string;
+    /** Max budget in USDC base units (6 decimals). 1_000_000 = $1 */
+    maxBudget?: bigint;
+    /** Minimum ERC-8004 reputation score to trust an agent */
+    minReputation?: number;
+    /** Search query override (defaults to task) */
+    searchQuery?: string;
+    /** Specific offering ID if known */
+    offeringId?: string;
+    /** Additional requirements to send to the agent */
+    requirements?: Record<string, unknown>;
+    /** Timeout in ms for waiting for deliverable (default 5 min) */
+    timeoutMs?: number;
+}
+export interface HireResult {
+    agent: AgentSearchResult;
+    jobId: string;
+    deliverable: unknown;
+    phase: string;
+    reputationChecked: boolean;
+    txHash?: string;
+}
+export interface AcceptJobsOptions {
+    /** What capabilities this agent offers */
+    capabilities: string[];
+    /** Handler called when a job comes in — return the deliverable */
+    handler: (job: IncomingJob) => Promise<unknown>;
+}
+export interface OrchestrateOptions {
+    /** High-level intent — will be decomposed into multiple agent hires */
+    intent: string;
+    /** Risk tolerance for DeFi intents */
+    riskTolerance?: "conservative" | "balanced" | "aggressive";
+    /** Total budget across all steps */
+    budget?: bigint;
+    /** Minimum reputation for any hired agent */
+    minReputation?: number;
+}
+export interface OrchestrateResult {
+    intent: string;
+    steps: {
+        role: string;
+        agent: AgentSearchResult | null;
+        result: HireResult | null;
+        skipped: boolean;
+        reason?: string;
+    }[];
+    totalCostUSDC: number;
+    completedSteps: number;
+}
+export declare class KompassSimple {
+    private backend;
+    private config;
+    private kompassConfig;
+    private constructor();
+    /**
+     * Create and initialize a Kompass instance.
+     *
+     * @example
+     * const kompass = await KompassSimple.create({
+     *   privateKey: "0x...",
+     *   network: "base-sepolia",
+     *   acpEntityAddress: "0x...",
+     *   acpWalletAddress: "0x...",
+     * });
+     */
+    static create(config: KompassSimpleConfig): Promise<KompassSimple>;
+    /**
+     * Hire an agent to do a task.
+     *
+     * Under the hood:
+     * 1. Searches ACP marketplace for matching agents
+     * 2. Checks ERC-8004 reputation (if configured)
+     * 3. Creates an ACP job and waits for delivery
+     * 4. Returns the deliverable
+     *
+     * @example
+     * const result = await kompass.hireAgent({
+     *   task: "Find the best yield for 1000 USDC on Base",
+     *   maxBudget: 1_000_000n,
+     * });
+     * console.log(result.deliverable);
+     */
+    hireAgent(options: HireOptions): Promise<HireResult>;
+    /**
+     * Start accepting jobs from other agents.
+     *
+     * Registers on ACP and listens for incoming jobs matching your capabilities.
+     * When a job arrives, your handler is called. Return the deliverable and
+     * the SDK handles ACP delivery automatically.
+     *
+     * @example
+     * await kompass.acceptJobs({
+     *   capabilities: ["defi-research", "yield-analysis"],
+     *   handler: async (job) => {
+     *     const report = await doResearch(job.description);
+     *     return report;
+     *   },
+     * });
+     */
+    acceptJobs(options: AcceptJobsOptions): Promise<void>;
+    /**
+     * Orchestrate a multi-agent pipeline for a complex intent.
+     *
+     * Decomposes the intent into specialist roles (research, data, risk, execution),
+     * hires an agent for each role via ACP, chains results, and returns the combined output.
+     *
+     * @example
+     * const result = await kompass.orchestrate({
+     *   intent: "Find best yield for 1000 USDC on Base",
+     *   riskTolerance: "balanced",
+     *   budget: 5_000_000n,
+     * });
+     */
+    orchestrate(options: OrchestrateOptions): Promise<OrchestrateResult>;
+    /**
+     * Check an agent's ERC-8004 on-chain reputation.
+     */
+    checkReputation(agentAddress: Address): Promise<ReputationSummary>;
+    /**
+     * Search for agents on ACP marketplace.
+     */
+    discover(query: string, options?: {
+        limit?: number;
+    }): Promise<AgentSearchResult[]>;
+    /** Get the backend name */
+    get backendName(): string;
+}
+//# sourceMappingURL=simple.d.ts.map

package/dist/simple.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"simple.d.ts","sourceRoot":"","sources":["../src/simple.ts"],"names":[],"mappings":"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"}

package/dist/simple.js

@@ -0,0 +1,237 @@
+/**
+ * Kompass Simplified API
+ *
+ * Dead-simple interface for agent-to-agent commerce.
+ * Wraps ACP escrow + Kompass intelligence (reputation, x402, intent routing).
+ *
+ * Usage:
+ *   const kompass = await KompassSimple.create({ privateKey, network: "base-sepolia" });
+ *   const result = await kompass.hireAgent({ task: "Find best yield on Base", maxBudget: 1_000_000n });
+ */
+import { createPublicClient, http } from "viem";
+import { baseSepolia, base } from "viem/chains";
+import { privateKeyToAccount } from "viem/accounts";
+import { AcpEscrowBackend } from "./backends/acp.js";
+import { getReputation } from "./reputation.js";
+// ── Main Class ───────────────────────────────────────────
+export class KompassSimple {
+    backend;
+    config;
+    kompassConfig = null;
+    constructor(config, backend) {
+        this.config = config;
+        this.backend = backend;
+    }
+    /**
+     * Create and initialize a Kompass instance.
+     *
+     * @example
+     * const kompass = await KompassSimple.create({
+     *   privateKey: "0x...",
+     *   network: "base-sepolia",
+     *   acpEntityAddress: "0x...",
+     *   acpWalletAddress: "0x...",
+     * });
+     */
+    static async create(config) {
+        const account = privateKeyToAccount(config.privateKey);
+        const chain = config.network === "base" ? base : baseSepolia;
+        const rpcUrl = config.rpcUrl ?? (config.network === "base" ? "https://mainnet.base.org" : "https://sepolia.base.org");
+        // Create ACP backend
+        const acpConfig = {
+            privateKey: config.privateKey,
+            walletAddress: (config.acpWalletAddress ?? account.address),
+            entityAddress: (config.acpEntityAddress ?? account.address),
+            network: config.network ?? "base-sepolia",
+            rpcUrl,
+        };
+        const backend = new AcpEscrowBackend(acpConfig);
+        await backend.init();
+        const instance = new KompassSimple(config, backend);
+        // Set up Kompass config for reputation queries if registry address provided
+        if (config.reputationRegistryAddress) {
+            const publicClient = createPublicClient({
+                chain,
+                transport: http(rpcUrl),
+            });
+            instance.kompassConfig = {
+                publicClient,
+                escrowAddress: "0x0000000000000000000000000000000000000000",
+                registryAddress: "0x0000000000000000000000000000000000000000",
+                reputationRegistryAddress: config.reputationRegistryAddress,
+                indexerUrl: config.indexerUrl ?? "",
+            };
+        }
+        return instance;
+    }
+    /**
+     * Hire an agent to do a task.
+     *
+     * Under the hood:
+     * 1. Searches ACP marketplace for matching agents
+     * 2. Checks ERC-8004 reputation (if configured)
+     * 3. Creates an ACP job and waits for delivery
+     * 4. Returns the deliverable
+     *
+     * @example
+     * const result = await kompass.hireAgent({
+     *   task: "Find the best yield for 1000 USDC on Base",
+     *   maxBudget: 1_000_000n,
+     * });
+     * console.log(result.deliverable);
+     */
+    async hireAgent(options) {
+        const query = options.searchQuery ?? options.task;
+        // 1. Discover agents on ACP
+        const agents = await this.backend.browseAgents(query, {
+            limit: 10,
+            sortBy: "successRate",
+            onlineOnly: true,
+        });
+        if (agents.length === 0) {
+            throw new Error(`No agents found for: "${query}"`);
+        }
+        // 2. Check reputation (if configured)
+        let reputationChecked = false;
+        let filteredAgents = agents;
+        if (this.kompassConfig && options.minReputation !== undefined) {
+            filteredAgents = [];
+            for (const agent of agents) {
+                try {
+                    const rep = await this.checkReputation(agent.address);
+                    const score = Number(rep.summaryValue);
+                    if (score >= options.minReputation || Number(rep.count) === 0) {
+                        filteredAgents.push(agent);
+                    }
+                }
+                catch {
+                    // If reputation check fails, include the agent (permissive)
+                    filteredAgents.push(agent);
+                }
+            }
+            reputationChecked = true;
+            if (filteredAgents.length === 0) {
+                throw new Error(`No agents meet reputation threshold (${options.minReputation}). Found ${agents.length} agents but none passed.`);
+            }
+        }
+        // 3. Select best agent (first match after filtering)
+        const agent = filteredAgents[0];
+        const offering = agent.offerings[0];
+        if (!offering) {
+            throw new Error(`Agent "${agent.name}" has no offerings`);
+        }
+        // 4. Create job on ACP
+        const requirements = {
+            description: options.task,
+            ...options.requirements,
+        };
+        const job = await this.backend.hireAgent(agent, options.offeringId ?? offering.id, requirements, options.maxBudget);
+        // 5. Wait for result
+        const result = await this.backend.waitForResult(job.jobId, options.timeoutMs ?? 300_000);
+        return {
+            agent,
+            jobId: result.jobId,
+            deliverable: result.deliverable,
+            phase: result.phase,
+            reputationChecked,
+            txHash: result.txHash,
+        };
+    }
+    /**
+     * Start accepting jobs from other agents.
+     *
+     * Registers on ACP and listens for incoming jobs matching your capabilities.
+     * When a job arrives, your handler is called. Return the deliverable and
+     * the SDK handles ACP delivery automatically.
+     *
+     * @example
+     * await kompass.acceptJobs({
+     *   capabilities: ["defi-research", "yield-analysis"],
+     *   handler: async (job) => {
+     *     const report = await doResearch(job.description);
+     *     return report;
+     *   },
+     * });
+     */
+    async acceptJobs(options) {
+        await this.backend.acceptJobs(options.capabilities, options.handler);
+    }
+    /**
+     * Orchestrate a multi-agent pipeline for a complex intent.
+     *
+     * Decomposes the intent into specialist roles (research, data, risk, execution),
+     * hires an agent for each role via ACP, chains results, and returns the combined output.
+     *
+     * @example
+     * const result = await kompass.orchestrate({
+     *   intent: "Find best yield for 1000 USDC on Base",
+     *   riskTolerance: "balanced",
+     *   budget: 5_000_000n,
+     * });
+     */
+    async orchestrate(options) {
+        const roles = ["research", "premium-data", "risk", "execution"];
+        const perStepBudget = options.budget
+            ? options.budget / BigInt(roles.length)
+            : 1000000n;
+        const steps = [];
+        let totalCost = 0;
+        for (const role of roles) {
+            try {
+                const result = await this.hireAgent({
+                    task: `[${role}] ${options.intent}`,
+                    searchQuery: role === "premium-data" ? "data analytics" : role,
+                    maxBudget: perStepBudget,
+                    minReputation: options.minReputation,
+                    timeoutMs: 120_000,
+                });
+                steps.push({
+                    role,
+                    agent: result.agent,
+                    result,
+                    skipped: false,
+                });
+                totalCost += Number(perStepBudget) / 1e6;
+            }
+            catch (err) {
+                steps.push({
+                    role,
+                    agent: null,
+                    result: null,
+                    skipped: true,
+                    reason: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+        return {
+            intent: options.intent,
+            steps,
+            totalCostUSDC: totalCost,
+            completedSteps: steps.filter((s) => !s.skipped).length,
+        };
+    }
+    /**
+     * Check an agent's ERC-8004 on-chain reputation.
+     */
+    async checkReputation(agentAddress) {
+        if (!this.kompassConfig) {
+            throw new Error("Reputation checking requires reputationRegistryAddress in config");
+        }
+        // Use agent address as ID (simplified — in production, look up erc8004Id)
+        return getReputation(this.kompassConfig, 0n);
+    }
+    /**
+     * Search for agents on ACP marketplace.
+     */
+    async discover(query, options) {
+        return this.backend.browseAgents(query, {
+            limit: options?.limit ?? 20,
+            sortBy: "successRate",
+        });
+    }
+    /** Get the backend name */
+    get backendName() {
+        return this.backend.name();
+    }
+}
+//# sourceMappingURL=simple.js.map