@agentkarma/sdk 0.1.0 → 0.2.0

package/dist/tools.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentkarma/sdk",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "TypeScript SDK for AgentKarma — the reputation layer for autonomous on-chain agents.",
   "license": "MIT",
   "author": "Kerem Noras <kerem@noras.tech>",
@@ -20,8 +20,19 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./tools": {
+      "types": "./dist/tools.d.ts",
+      "import": "./dist/tools.js"
+    },
+    "./mcp": {
+      "types": "./dist/mcp.d.ts",
+      "import": "./dist/mcp.js"
     }
   },
+  "bin": {
+    "agentkarma-mcp": "./dist/mcp-cli.js"
+  },
   "files": [
     "dist",
     "src",
@@ -32,11 +43,15 @@
   "engines": {
     "node": ">=18"
   },
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
-    "build": "tsc -p tsconfig.json",
+    "build": "tsc -p tsconfig.json && chmod +x dist/mcp-cli.js",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "bun test",
-    "clean": "rm -rf dist"
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run build"
   },
   "keywords": [
     "agentkarma",
@@ -47,9 +62,20 @@
     "x402",
     "solana",
     "celo",
-    "preflight"
+    "preflight",
+    "mcp",
+    "model-context-protocol"
   ],
+  "peerDependencies": {
+    "@modelcontextprotocol/sdk": ">=1.0.0 <2"
+  },
+  "peerDependenciesMeta": {
+    "@modelcontextprotocol/sdk": {
+      "optional": true
+    }
+  },
   "devDependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "@types/node": "^25.5.2",
     "bun-types": "^1.3.13",
     "typescript": "^6.0.2"

package/src/mcp-cli.ts

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+/**
+ * `agentkarma-mcp` — run the AgentKarma MCP server over stdio.
+ *
+ * Backed by the public AgentKarma API (read-only, non-routing). Point it at a
+ * different host with AGENTKARMA_BASE_URL.
+ *
+ *   npx agentkarma-mcp
+ *   AGENTKARMA_BASE_URL=https://staging.agentkarma.io npx agentkarma-mcp
+ *
+ * Requires the optional peer dependency `@modelcontextprotocol/sdk`.
+ */
+
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createAgentKarmaMcpServer } from './mcp.js';
+
+const baseUrl = process.env.AGENTKARMA_BASE_URL;
+const server = createAgentKarmaMcpServer({
+  config: baseUrl ? { baseUrl } : undefined,
+});
+
+try {
+  await server.connect(new StdioServerTransport());
+  // stderr only — stdout is the JSON-RPC channel and must stay clean.
+  console.error(
+    `agentkarma-mcp ready (${baseUrl ?? 'https://agentkarma.io'}) over stdio`,
+  );
+} catch (err) {
+  console.error(
+    'agentkarma-mcp failed to start:',
+    err instanceof Error ? err.message : err,
+  );
+  process.exit(1);
+}

package/src/mcp.ts

@@ -0,0 +1,146 @@
+/**
+ * @agentkarma/sdk/mcp — a turnkey AgentKarma MCP server, built from the
+ * `@agentkarma/sdk/tools` catalog and backed by the public AgentKarma client.
+ *
+ * This is the OPTIONAL server layer. It depends on `@modelcontextprotocol/sdk`
+ * (declared as an optional peer dependency) — install it only if you use this
+ * module. The core client (`@agentkarma/sdk`) and the tool catalog
+ * (`@agentkarma/sdk/tools`) stay dependency-free.
+ *
+ * The server is read-only and non-routing: it exposes the read catalog, never
+ * signs, and never proxies a call on the caller's behalf.
+ *
+ *   import { createAgentKarmaMcpServer } from '@agentkarma/sdk/mcp';
+ *   import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+ *   const server = createAgentKarmaMcpServer();
+ *   await server.connect(new StdioServerTransport());
+ */
+
+// Low-level `Server` (not the high-level `McpServer`) is deliberate: `McpServer`
+// requires Zod for every tool's `inputSchema`, whereas this catalog ships plain
+// JSON Schema (zero-dep, portable). The SDK documents `Server` as the path for
+// exactly this "advanced use case", so the @deprecated hint is acknowledged and
+// intentional — we want JSON Schema on the wire without a Zod dependency.
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  type CallToolResult,
+  type Tool,
+} from '@modelcontextprotocol/sdk/types.js';
+
+import { createAgentKarmaClient, type AgentKarmaClient } from './client.js';
+import {
+  AgentKarmaError,
+  AgentKarmaNotFoundError,
+  AgentKarmaValidationError,
+} from './errors.js';
+import { agentKarmaTools, getAgentKarmaTool } from './tools.js';
+import type { ClientConfig } from './types.js';
+
+const MCP_SERVER_NAME = 'agentkarma';
+const MCP_SERVER_VERSION = '0.1.0';
+
+const SERVER_INSTRUCTIONS = [
+  'AgentKarma is the reputation layer for autonomous on-chain agents.',
+  'Use these read-only tools to look up trust signals BEFORE paying or',
+  'delegating to a wallet — every response carries two-faced karma (provider +',
+  'consumer) and a confidence badge. `check_trust` runs a local allow/deny',
+  'policy. AgentKarma does not proxy paid calls (non-routing).',
+].join(' ');
+
+/** The tool advertisements (MCP `tools/list` shape), derived from the catalog. */
+export function agentKarmaMcpTools(): Tool[] {
+  return agentKarmaTools.map((t) => ({
+    name: t.name,
+    title: t.title,
+    description: t.description,
+    inputSchema: t.inputSchema as Tool['inputSchema'],
+    annotations: { title: t.title, ...t.annotations },
+  }));
+}
+
+/**
+ * Run a catalog tool and shape the result as an MCP `CallToolResult`. Errors
+ * are converted to clean, non-leaky tool errors — raw network/stack detail is
+ * NEVER echoed to the caller.
+ */
+export async function callAgentKarmaTool(
+  client: AgentKarmaClient,
+  name: string,
+  args: Record<string, unknown> = {},
+): Promise<CallToolResult> {
+  const tool = getAgentKarmaTool(name);
+  if (!tool) {
+    return toolError('unknown_tool', `Unknown tool: ${name}`);
+  }
+  try {
+    const data = await tool.handler(client, args);
+    return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+  } catch (err) {
+    if (err instanceof AgentKarmaNotFoundError) {
+      return toolError('not_found', `No record found for this ${name} lookup.`);
+    }
+    if (err instanceof AgentKarmaValidationError) {
+      // Validation messages describe the caller's own bad argument — safe to echo.
+      // INVARIANT: AgentKarmaValidationError messages MUST stay caller-facing —
+      // never interpolate a host, URL, response body, or any upstream/network
+      // detail into one, because this branch echoes err.message verbatim to a
+      // public MCP caller. Upstream/network errors take the non-echoing branches
+      // below instead.
+      return toolError('invalid_input', err.message);
+    }
+    if (err instanceof AgentKarmaError && typeof err.status === 'number') {
+      return toolError('upstream_error', `AgentKarma returned ${err.status}.`);
+    }
+    // Unknown/network error: log server-side, return a generic message.
+    console.error(`[agentkarma-mcp:${name}]`, err);
+    return toolError(
+      'tool_error',
+      `${name} encountered an unexpected error. Verify the arguments and try again.`,
+    );
+  }
+}
+
+function toolError(error: string, message: string): CallToolResult {
+  return {
+    isError: true,
+    content: [{ type: 'text', text: JSON.stringify({ error, message }) }],
+  };
+}
+
+/** Options for {@link createAgentKarmaMcpServer}. */
+export interface CreateAgentKarmaMcpServerOptions {
+  /** Pre-built client. Takes precedence over `config`. */
+  client?: AgentKarmaClient;
+  /** Client config (baseUrl, timeout, fetch, …) when no `client` is supplied. */
+  config?: ClientConfig;
+}
+
+/**
+ * Build a low-level MCP `Server` exposing the AgentKarma read catalog. Connect
+ * it to any transport (`StdioServerTransport`, an HTTP transport, …).
+ */
+export function createAgentKarmaMcpServer(
+  options: CreateAgentKarmaMcpServerOptions = {},
+): Server {
+  const client = options.client ?? createAgentKarmaClient(options.config);
+  const server = new Server(
+    { name: MCP_SERVER_NAME, version: MCP_SERVER_VERSION },
+    { capabilities: { tools: {} }, instructions: SERVER_INSTRUCTIONS },
+  );
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: agentKarmaMcpTools(),
+  }));
+
+  server.setRequestHandler(CallToolRequestSchema, async (request) =>
+    callAgentKarmaTool(
+      client,
+      request.params.name,
+      (request.params.arguments ?? {}) as Record<string, unknown>,
+    ),
+  );
+
+  return server;
+}

package/src/tools.ts

@@ -0,0 +1,423 @@
+/**
+ * @agentkarma/sdk/tools — framework-agnostic MCP tool catalog.
+ *
+ * One canonical, dependency-free description of AgentKarma's read surface as
+ * MCP-style tools. Each descriptor carries a JSON Schema (draft-07) input
+ * contract and a `handler` that runs against an `AgentKarmaClient` — so the
+ * SAME catalog can be mounted on any MCP server (`@agentkarma/sdk/mcp`), wired
+ * into another agent framework, or called directly.
+ *
+ * These are READ tools only. They never sign, never execute a transaction,
+ * never proxy a call (non-routing, RFC §12). The one write in the SDK —
+ * `submitFeedback` — needs a wallet signature and is intentionally NOT exposed
+ * here, so an MCP server built from this catalog requires no keys.
+ *
+ * Zero runtime dependencies: schemas are plain JSON Schema objects, not Zod, so
+ * importing this module pulls nothing extra into a client-only consumer.
+ */
+
+import type { AgentKarmaClient } from './client.js';
+import { AgentKarmaValidationError } from './errors.js';
+import { evaluateTrust, type TrustPolicy } from './policy.js';
+import type { Chain, KarmaFace } from './types.js';
+
+/** MCP tool annotations (subset of the MCP spec) describing tool behaviour. */
+export interface AgentKarmaToolAnnotations {
+  /** The tool does not modify state. Always true here. */
+  readOnlyHint: true;
+  /** Repeated calls with the same args yield the same result. Always true here. */
+  idempotentHint: true;
+  /** The tool reads from an external service (agentkarma.io). Always true here. */
+  openWorldHint: true;
+}
+
+/** A JSON Schema (draft-07) object — kept loose to avoid a schema-lib dependency. */
+export type JSONSchema = Record<string, unknown>;
+
+/**
+ * A single AgentKarma tool: its MCP advertisement (name/title/description/schema)
+ * plus a handler that executes it against an `AgentKarmaClient`.
+ */
+export interface AgentKarmaToolDescriptor {
+  /** Stable tool name (snake_case), e.g. `get_karma`. */
+  name: string;
+  /** Human-readable title for tool pickers. */
+  title: string;
+  /** What the tool does and when to use it. */
+  description: string;
+  /** JSON Schema (draft-07) for the tool's arguments. */
+  inputSchema: JSONSchema;
+  /** MCP behaviour hints. */
+  annotations: AgentKarmaToolAnnotations;
+  /** Execute the tool against a client. Returns plain JSON-serializable data. */
+  handler: (
+    client: AgentKarmaClient,
+    input: Record<string, unknown>,
+  ) => Promise<unknown>;
+}
+
+const READ_ONLY: AgentKarmaToolAnnotations = {
+  readOnlyHint: true,
+  idempotentHint: true,
+  openWorldHint: true,
+};
+
+const SUPPORTED_CHAINS = ['solana', 'celo', 'stellar', 'arc'] as const;
+
+// ─── Reusable schema fragments ──────────────────────────────────────────────
+
+const walletProp: JSONSchema = {
+  type: 'string',
+  description:
+    'On-chain agent wallet address (Solana base58, Stellar G-address, or EVM 0x address).',
+};
+
+/** Solana-only endpoints (history, feedback) reject non-base58 addresses. */
+const solanaWalletProp: JSONSchema = {
+  type: 'string',
+  description:
+    'Solana agent wallet address (base58, 32–44 chars). This endpoint is Solana-only.',
+};
+
+const optionalChainProp: JSONSchema = {
+  type: 'string',
+  enum: [...SUPPORTED_CHAINS],
+  description:
+    "Chain for the lookup. Defaults to 'solana'. Pass for celo/arc/stellar wallets.",
+};
+
+const requiredChainProp: JSONSchema = {
+  type: 'string',
+  enum: [...SUPPORTED_CHAINS],
+  description: 'Chain the wallet lives on (spans all chains; must be explicit).',
+};
+
+const faceProp: JSONSchema = {
+  type: 'string',
+  enum: ['provider', 'consumer', 'both'],
+  description:
+    "Karma face: 'provider' (will it deliver?), 'consumer' (will it pay cleanly?), or 'both' (default).",
+};
+
+function objectSchema(
+  properties: Record<string, JSONSchema>,
+  required: string[],
+): JSONSchema {
+  return {
+    type: 'object',
+    properties,
+    required,
+    additionalProperties: false,
+  };
+}
+
+// ─── Input coercion helpers (handlers receive raw, possibly-stringy args) ────
+
+function asString(value: unknown): string {
+  return typeof value === 'string' ? value : String(value ?? '');
+}
+
+/** Coerce an MCP arg to a number, tolerating JSON-string numbers. `undefined` passes through. */
+function asOptionalNumber(value: unknown): number | undefined {
+  if (value === undefined || value === null || value === '') return undefined;
+  const n = typeof value === 'number' ? value : Number(value);
+  return Number.isNaN(n) ? undefined : n;
+}
+
+function asOptionalBoolean(value: unknown): boolean | undefined {
+  if (value === undefined || value === null || value === '') return undefined;
+  if (typeof value === 'boolean') return value;
+  if (value === 'true' || value === '1') return true;
+  if (value === 'false' || value === '0') return false;
+  return Boolean(value);
+}
+
+function asChain(value: unknown): Chain | undefined {
+  return typeof value === 'string' && (SUPPORTED_CHAINS as readonly string[]).includes(value)
+    ? (value as Chain)
+    : undefined;
+}
+
+function asFace(value: unknown): KarmaFace | 'both' | undefined {
+  return value === 'provider' || value === 'consumer' || value === 'both'
+    ? value
+    : undefined;
+}
+
+/**
+ * Resolve an OPTIONAL chain argument: `undefined` when absent, the validated
+ * chain otherwise. Unlike a bare `asChain`, a present-but-invalid value throws
+ * rather than silently downgrading to the client's 'solana' default — so
+ * `chain: 'polygon'` fails loudly instead of returning a wrong Solana lookup.
+ */
+function resolveOptionalChain(value: unknown): Chain | undefined {
+  if (value === undefined || value === null || value === '') return undefined;
+  const chain = asChain(value);
+  if (!chain) {
+    throw new AgentKarmaValidationError(
+      `chain must be one of ${SUPPORTED_CHAINS.join(', ')}`,
+    );
+  }
+  return chain;
+}
+
+/** Clamp an optional limit to the tool's advertised [1, max] bound. */
+function clampLimit(value: unknown, max: number): number | undefined {
+  const n = asOptionalNumber(value);
+  if (n === undefined) return undefined;
+  return Math.min(Math.max(1, Math.trunc(n)), max);
+}
+
+// ─── The catalog ─────────────────────────────────────────────────────────────
+
+export const agentKarmaTools: AgentKarmaToolDescriptor[] = [
+  {
+    name: 'get_karma',
+    title: 'Get Karma (both faces)',
+    description:
+      'Look up the full two-faced Karma snapshot for an agent wallet — provider score, consumer score, confidence badge, autonomy, identity. Use BEFORE paying an agent or accepting work from one.',
+    inputSchema: objectSchema(
+      { wallet: walletProp, chain: optionalChainProp, face: faceProp },
+      ['wallet'],
+    ),
+    annotations: READ_ONLY,
+    handler: (client, input) =>
+      client.getKarma(asString(input.wallet), {
+        chain: resolveOptionalChain(input.chain),
+        face: asFace(input.face) ?? 'both',
+      }),
+  },
+  {
+    name: 'get_celo_agent',
+    title: 'Get Celo agent (ERC-8004)',
+    description:
+      'Resolve a Celo ERC-8004 agent by numeric agentId: IdentityRegistry record (owner, agentURI, declared services) plus aggregate ReputationRegistry feedback.',
+    inputSchema: objectSchema(
+      {
+        agent_id: {
+          type: 'integer',
+          minimum: 1,
+          description: 'ERC-8004 agentId on Celo mainnet (positive integer).',
+        },
+      },
+      ['agent_id'],
+    ),
+    annotations: READ_ONLY,
+    handler: (client, input) => client.getCeloAgent(Number(input.agent_id)),
+  },
+  {
+    name: 'search_agents',
+    title: 'Search agents',
+    description:
+      'Find agents by a substring of their display name or wallet address (case-insensitive), ranked by score. Returns up to `limit` results.',
+    inputSchema: objectSchema(
+      {
+        query: {
+          type: 'string',
+          minLength: 3,
+          description: 'Name or wallet-address substring (≥3 chars).',
+        },
+        limit: {
+          type: 'integer',
+          minimum: 1,
+          maximum: 50,
+          description: 'Max results (1–50, clamped to 50).',
+        },
+      },
+      ['query'],
+    ),
+    annotations: READ_ONLY,
+    handler: (client, input) =>
+      client.searchAgents(asString(input.query), {
+        limit: clampLimit(input.limit, 50),
+      }),
+  },
+  {
+    name: 'get_agent_history',
+    title: 'Get agent payment history',
+    description:
+      "Paginated x402 payment history for a Solana agent wallet, with each transaction's consumer feedback rating. Solana-only today.",
+    inputSchema: objectSchema(
+      {
+        wallet: solanaWalletProp,
+        limit: {
+          type: 'integer',
+          minimum: 1,
+          maximum: 200,
+          description: 'Page size (1–200, clamped to 200).',
+        },
+        offset: { type: 'integer', minimum: 0, description: 'Page offset.' },
+      },
+      ['wallet'],
+    ),
+    annotations: READ_ONLY,
+    handler: (client, input) =>
+      client.getAgentHistory(asString(input.wallet), {
+        limit: clampLimit(input.limit, 200),
+        offset: asOptionalNumber(input.offset),
+      }),
+  },
+  {
+    name: 'get_feedback_summary',
+    title: 'Get feedback summary',
+    description:
+      'Aggregate delivered/failed counts and delivery rate for a Solana agent wallet.',
+    inputSchema: objectSchema({ wallet: solanaWalletProp }, ['wallet']),
+    annotations: READ_ONLY,
+    handler: (client, input) => client.getFeedbackSummary(asString(input.wallet)),
+  },
+  {
+    name: 'get_succession',
+    title: "Get succession plan (Dead Man's Switch)",
+    description:
+      "Return the agent's declared succession plan plus AgentKarma's OBSERVED heartbeat liveness (derived status, heir count, deadline). A continuity/trust signal. AgentKarma never holds a key or executes the will (non-custody). Throws not-found when no plan is declared.",
+    inputSchema: objectSchema(
+      { chain: requiredChainProp, wallet: walletProp },
+      ['chain', 'wallet'],
+    ),
+    annotations: READ_ONLY,
+    handler: async (client, input) => {
+      const chain = asChain(input.chain);
+      if (!chain) {
+        throw new AgentKarmaValidationError(
+          `chain must be one of ${SUPPORTED_CHAINS.join(', ')}`,
+        );
+      }
+      return client.getSuccessionStatus(chain, asString(input.wallet));
+    },
+  },
+  {
+    name: 'get_bond',
+    title: 'Get bonding status',
+    description:
+      'Return surety bonds taken out ON this agent (open vs resolved, total bonded USDC, demo flag). A bond lifts confidence/Tier-1 presence only — never the trust ceiling. Returns an empty block when the agent has no bonds.',
+    inputSchema: objectSchema(
+      { chain: requiredChainProp, wallet: walletProp },
+      ['chain', 'wallet'],
+    ),
+    annotations: READ_ONLY,
+    handler: async (client, input) => {
+      const chain = asChain(input.chain);
+      if (!chain) {
+        throw new AgentKarmaValidationError(
+          `chain must be one of ${SUPPORTED_CHAINS.join(', ')}`,
+        );
+      }
+      return client.getBondStatus(chain, asString(input.wallet));
+    },
+  },
+  {
+    name: 'get_surety',
+    title: 'Get Surety Karma',
+    description:
+      "Return this wallet's ORTHOGONAL Surety Karma from underwriting OTHER agents' bonds (score, settled/success/in-flight counts). Never folded into Provider/Consumer karma. Returns null when the wallet has never underwritten.",
+    inputSchema: objectSchema(
+      { chain: requiredChainProp, wallet: walletProp },
+      ['chain', 'wallet'],
+    ),
+    annotations: READ_ONLY,
+    handler: async (client, input) => {
+      const chain = asChain(input.chain);
+      if (!chain) {
+        throw new AgentKarmaValidationError(
+          `chain must be one of ${SUPPORTED_CHAINS.join(', ')}`,
+        );
+      }
+      return client.getSuretyKarma(chain, asString(input.wallet));
+    },
+  },
+  {
+    name: 'check_trust',
+    title: 'Check trust before executing',
+    description:
+      'Fetch an agent\'s Karma and evaluate a local trust policy against it — the "should I trust this agent before paying?" gate. Returns an explainable allow/deny decision plus the snapshot it read. Pure local evaluation: no routing, no signing.',
+    inputSchema: objectSchema(
+      {
+        wallet: walletProp,
+        chain: optionalChainProp,
+        face: {
+          type: 'string',
+          enum: ['provider', 'consumer'],
+          description: 'Face to score the decision on (default provider).',
+        },
+        min_score: {
+          type: 'integer',
+          minimum: 0,
+          maximum: 100,
+          description: 'Reject when the face score is below this.',
+        },
+        require_receipt_backed: {
+          type: 'boolean',
+          description: 'Require at least one Tier-1 receipt-backed signal.',
+        },
+        min_tx_count: {
+          type: 'integer',
+          minimum: 0,
+          description: 'Require at least this many indexed transactions.',
+        },
+        min_autonomy_score: {
+          type: 'integer',
+          minimum: 0,
+          maximum: 100,
+          description: 'Require autonomy score at or above this.',
+        },
+        require_live_succession: {
+          type: 'boolean',
+          description: 'Require a live (declared/live) succession plan.',
+        },
+      },
+      ['wallet'],
+    ),
+    annotations: READ_ONLY,
+    handler: async (client, input) => {
+      const wallet = asString(input.wallet);
+      const chain = resolveOptionalChain(input.chain);
+      const policy: TrustPolicy = {};
+      const face = input.face;
+      if (face === 'provider' || face === 'consumer') policy.face = face;
+      const minScore = asOptionalNumber(input.min_score);
+      if (minScore !== undefined) policy.minScore = minScore;
+      const requireReceipt = asOptionalBoolean(input.require_receipt_backed);
+      if (requireReceipt !== undefined) policy.requireReceiptBacked = requireReceipt;
+      const minTx = asOptionalNumber(input.min_tx_count);
+      if (minTx !== undefined) policy.minTxCount = minTx;
+      const minAutonomy = asOptionalNumber(input.min_autonomy_score);
+      if (minAutonomy !== undefined) policy.minAutonomyScore = minAutonomy;
+      const requireLive = asOptionalBoolean(input.require_live_succession);
+      if (requireLive !== undefined) policy.requireLiveSuccession = requireLive;
+
+      const snapshot = await client.getKarma(wallet, { chain, face: 'both' });
+      const decision = evaluateTrust(snapshot, policy);
+      return { wallet, chain: chain ?? 'solana', decision, snapshot };
+    },
+  },
+];
+
+/** Look up a tool descriptor by name. */
+export function getAgentKarmaTool(
+  name: string,
+): AgentKarmaToolDescriptor | undefined {
+  return agentKarmaTools.find((t) => t.name === name);
+}
+
+/** Every tool name in the catalog. */
+export function agentKarmaToolNames(): string[] {
+  return agentKarmaTools.map((t) => t.name);
+}
+
+/**
+ * Run a catalog tool by name against a client. Throws
+ * `AgentKarmaValidationError` for an unknown tool; the client's own validation
+ * governs the arguments.
+ */
+export async function runAgentKarmaTool(
+  client: AgentKarmaClient,
+  name: string,
+  input: Record<string, unknown> = {},
+): Promise<unknown> {
+  const tool = getAgentKarmaTool(name);
+  if (!tool) {
+    throw new AgentKarmaValidationError(`Unknown AgentKarma tool: ${name}`);
+  }
+  return tool.handler(client, input);
+}