agentbnb 8.2.0 → 8.2.2

package/dist/{chunk-7EF3HYVZ.js → chunk-MCED4GDW.js}

@@ -319,7 +319,10 @@ var V2_FTS_TRIGGERS = `
       new.id,
       new.owner,
       COALESCE(
-        (SELECT group_concat(json_extract(value, '$.name'), ' ')
+        (SELECT group_concat(
+            COALESCE(json_extract(value, '$.id'), '') || ' ' || COALESCE(json_extract(value, '$.name'), ''),
+            ' '
+         )
          FROM json_each(json_extract(new.data, '$.skills'))),
         json_extract(new.data, '$.name'),
         ''
@@ -359,7 +362,10 @@ var V2_FTS_TRIGGERS = `
       old.id,
       old.owner,
       COALESCE(
-        (SELECT group_concat(json_extract(value, '$.name'), ' ')
+        (SELECT group_concat(
+            COALESCE(json_extract(value, '$.id'), '') || ' ' || COALESCE(json_extract(value, '$.name'), ''),
+            ' '
+         )
          FROM json_each(json_extract(old.data, '$.skills'))),
         json_extract(old.data, '$.name'),
         ''
@@ -395,7 +401,10 @@ var V2_FTS_TRIGGERS = `
       new.id,
       new.owner,
       COALESCE(
-        (SELECT group_concat(json_extract(value, '$.name'), ' ')
+        (SELECT group_concat(
+            COALESCE(json_extract(value, '$.id'), '') || ' ' || COALESCE(json_extract(value, '$.name'), ''),
+            ' '
+         )
          FROM json_each(json_extract(new.data, '$.skills'))),
         json_extract(new.data, '$.name'),
         ''
@@ -435,7 +444,10 @@ var V2_FTS_TRIGGERS = `
       old.id,
       old.owner,
       COALESCE(
-        (SELECT group_concat(json_extract(value, '$.name'), ' ')
+        (SELECT group_concat(
+            COALESCE(json_extract(value, '$.id'), '') || ' ' || COALESCE(json_extract(value, '$.name'), ''),
+            ' '
+         )
          FROM json_each(json_extract(old.data, '$.skills'))),
         json_extract(old.data, '$.name'),
         ''
@@ -502,6 +514,15 @@ function openDatabase(path = ":memory:") {
       tags,
       content=""
     );
+
+    -- Expression index for capability_type lookups (used by Conductor routing).
+    -- Turns json_extract full-table-scan into O(log n) B-tree lookup.
+    CREATE INDEX IF NOT EXISTS idx_cards_capability_type
+      ON capability_cards(json_extract(data, '$.capability_type'));
+
+    -- Owner index for listCards(owner) and other owner-scoped queries.
+    CREATE INDEX IF NOT EXISTS idx_cards_owner
+      ON capability_cards(owner);
   `);
   createRequestLogTable(db);
   initFeedbackTable(db);
@@ -513,6 +534,10 @@ function runMigrations(db) {
   const version = db.pragma("user_version")[0]?.user_version ?? 0;
   if (version < 2) {
     migrateV1toV2(db);
+    return;
+  }
+  if (version < 3) {
+    migrateV2toV3(db);
   }
 }
 function migrateV1toV2(db) {
@@ -554,44 +579,55 @@ function migrateV1toV2(db) {
       );
     }
     db.exec(V2_FTS_TRIGGERS);
-    db.exec(`INSERT INTO cards_fts(cards_fts) VALUES('delete-all')`);
-    const allRows = db.prepare("SELECT rowid, id, owner, data FROM capability_cards").all();
-    const ftsInsert = db.prepare(
-      "INSERT INTO cards_fts(rowid, id, owner, name, description, tags) VALUES (?, ?, ?, ?, ?, ?)"
-    );
-    for (const row of allRows) {
-      const data = JSON.parse(row.data);
-      const skills = data["skills"] ?? [];
-      let name;
-      let description;
-      let tags;
-      if (skills.length > 0) {
-        name = skills.map((s) => String(s["name"] ?? "")).join(" ");
-        description = skills.map((s) => String(s["description"] ?? "")).join(" ");
-        tags = [
-          // tags from metadata.tags[]
-          ...skills.flatMap((s) => {
-            const meta = s["metadata"];
-            return meta?.["tags"] ?? [];
-          }),
-          // capability_type (singular)
-          ...skills.map((s) => s["capability_type"]).filter((v) => typeof v === "string" && v.length > 0),
-          // capability_types[] (plural)
-          ...skills.flatMap((s) => s["capability_types"] ?? [])
-        ].join(" ");
-      } else {
-        name = String(data["name"] ?? "");
-        description = String(data["description"] ?? "");
-        const meta = data["metadata"];
-        const rawTags = meta?.["tags"] ?? [];
-        tags = rawTags.join(" ");
-      }
-      ftsInsert.run(row.rowid, row.id, row.owner, name, description, tags);
-    }
-    db.pragma("user_version = 2");
+    rebuildCardsFts(db);
+    db.pragma("user_version = 3");
   });
   migrate();
 }
+function migrateV2toV3(db) {
+  const migrate = db.transaction(() => {
+    db.exec(V2_FTS_TRIGGERS);
+    rebuildCardsFts(db);
+    db.pragma("user_version = 3");
+  });
+  migrate();
+}
+function rebuildCardsFts(db) {
+  db.exec(`INSERT INTO cards_fts(cards_fts) VALUES('delete-all')`);
+  const allRows = db.prepare("SELECT rowid, id, owner, data FROM capability_cards").all();
+  const ftsInsert = db.prepare(
+    "INSERT INTO cards_fts(rowid, id, owner, name, description, tags) VALUES (?, ?, ?, ?, ?, ?)"
+  );
+  for (const row of allRows) {
+    const data = JSON.parse(row.data);
+    const skills = data["skills"] ?? [];
+    let name;
+    let description;
+    let tags;
+    if (skills.length > 0) {
+      name = skills.map((s) => `${String(s["id"] ?? "")} ${String(s["name"] ?? "")}`.trim()).join(" ");
+      description = skills.map((s) => String(s["description"] ?? "")).join(" ");
+      tags = [
+        // tags from metadata.tags[]
+        ...skills.flatMap((s) => {
+          const meta = s["metadata"];
+          return meta?.["tags"] ?? [];
+        }),
+        // capability_type (singular)
+        ...skills.map((s) => s["capability_type"]).filter((v) => typeof v === "string" && v.length > 0),
+        // capability_types[] (plural)
+        ...skills.flatMap((s) => s["capability_types"] ?? [])
+      ].join(" ");
+    } else {
+      name = String(data["name"] ?? "");
+      description = String(data["description"] ?? "");
+      const meta = data["metadata"];
+      const rawTags = meta?.["tags"] ?? [];
+      tags = rawTags.join(" ");
+    }
+    ftsInsert.run(row.rowid, row.id, row.owner, name, description, tags);
+  }
+}
 function insertCard(db, card) {
   const now = (/* @__PURE__ */ new Date()).toISOString();
   const withTimestamps = { ...card, created_at: card.created_at ?? now, updated_at: now };
@@ -759,6 +795,9 @@ var AGENTS_SCHEMA = `
 function ensureAgentsTable(db) {
   db.exec(AGENTS_SCHEMA);
 }
+function lookupAgent(db, agentId) {
+  return db.prepare("SELECT * FROM agents WHERE agent_id = ?").get(agentId) ?? null;
+}
 
 // src/credit/ledger.ts
 var CREDIT_SCHEMA = `
@@ -839,10 +878,23 @@ function getBalance(db, owner) {
   const row = db.prepare("SELECT balance FROM credit_balances WHERE owner = ?").get(owner);
   return row?.balance ?? 0;
 }
-function getTransactions(db, owner, limit = 100) {
+function getTransactions(db, owner, opts = 100) {
+  const page = typeof opts === "number" ? { limit: opts } : opts;
+  const limit = page.limit ?? 100;
+  const conditions = ["owner = ?"];
+  const params = [owner];
+  if (page.before) {
+    conditions.push("created_at < ?");
+    params.push(page.before);
+  }
+  if (page.after) {
+    conditions.push("created_at > ?");
+    params.push(page.after);
+  }
+  params.push(limit);
   return db.prepare(
-    "SELECT id, owner, amount, reason, reference_id, created_at FROM credit_transactions WHERE owner = ? ORDER BY created_at DESC LIMIT ?"
-  ).all(owner, limit);
+    `SELECT id, owner, amount, reason, reference_id, created_at FROM credit_transactions WHERE ${conditions.join(" AND ")} ORDER BY created_at DESC LIMIT ?`
+  ).all(...params);
 }
 function registerProvider(db, owner) {
   const now = (/* @__PURE__ */ new Date()).toISOString();
@@ -1067,56 +1119,414 @@ function confirmEscrowDebit(db, escrowId) {
   confirm();
 }
 
-// src/credit/signing.ts
-import { generateKeyPairSync, sign, verify, createPublicKey, createPrivateKey } from "crypto";
-import { writeFileSync, readFileSync, existsSync, chmodSync } from "fs";
-import { join } from "path";
-function generateKeyPair() {
-  const { publicKey, privateKey } = generateKeyPairSync("ed25519", {
-    publicKeyEncoding: { type: "spki", format: "der" },
-    privateKeyEncoding: { type: "pkcs8", format: "der" }
+// src/feedback/reputation.ts
+var QUALITY_SCORES = {
+  excellent: 1,
+  good: 0.8,
+  acceptable: 0.6,
+  poor: 0.3,
+  failed: 0
+};
+var COST_VALUE_SCORES = {
+  great: 1,
+  fair: 0.6,
+  overpriced: 0.2
+};
+var DECAY_DAYS = 30;
+var WEIGHTS = {
+  rating: 0.4,
+  quality: 0.3,
+  would_reuse: 0.2,
+  cost_value: 0.1
+};
+function computeReputation(feedbacks) {
+  if (feedbacks.length === 0) return 0.5;
+  const now = Date.now();
+  let weightedSum = 0;
+  let totalWeight = 0;
+  for (const fb of feedbacks) {
+    const feedbackDate = new Date(fb.timestamp).getTime();
+    const ageDays = Math.max(0, (now - feedbackDate) / (1e3 * 60 * 60 * 24));
+    const recencyWeight = Math.exp(-ageDays / DECAY_DAYS);
+    const ratingScore = (fb.rating - 1) / 4;
+    const qualityScore = QUALITY_SCORES[fb.result_quality];
+    const reuseScore = fb.would_reuse ? 1 : 0;
+    const costScore = COST_VALUE_SCORES[fb.cost_value_ratio];
+    const componentScore = WEIGHTS.rating * ratingScore + WEIGHTS.quality * qualityScore + WEIGHTS.would_reuse * reuseScore + WEIGHTS.cost_value * costScore;
+    weightedSum += recencyWeight * componentScore;
+    totalWeight += recencyWeight;
+  }
+  if (totalWeight === 0) return 0.5;
+  const raw = weightedSum / totalWeight;
+  return Math.max(0, Math.min(1, raw));
+}
+function getReputationScore(db, agentId) {
+  const feedbacks = getFeedbackForProvider(db, agentId);
+  return computeReputation(feedbacks);
+}
+
+// src/registry/matcher.ts
+var CACHE_MAX_ENTRIES = 100;
+var CACHE_TTL_MS = 3e4;
+var dbCaches = /* @__PURE__ */ new WeakMap();
+function getDbCache(db) {
+  let cache = dbCaches.get(db);
+  if (!cache) {
+    cache = /* @__PURE__ */ new Map();
+    dbCaches.set(db, cache);
+  }
+  return cache;
+}
+function cacheKey(query, filters) {
+  return `${query}|${filters.level ?? ""}|${filters.online ?? ""}|${(filters.apis_used ?? []).join(",")}|${filters.min_reputation ?? ""}`;
+}
+function evictCache(cache) {
+  const now = Date.now();
+  for (const [key, entry] of cache) {
+    if (entry.expiresAt <= now) cache.delete(key);
+  }
+  while (cache.size > CACHE_MAX_ENTRIES) {
+    const firstKey = cache.keys().next().value;
+    cache.delete(firstKey);
+  }
+}
+function searchCards(db, query, filters = {}) {
+  const cache = getDbCache(db);
+  const key = cacheKey(query, filters);
+  const cached = cache.get(key);
+  if (cached && cached.expiresAt > Date.now()) {
+    return cached.results;
+  }
+  const trimmedQuery = query.trim();
+  const exactSkillMatches = findCardsByExactSkillId(db, trimmedQuery, filters);
+  const words = query.trim().split(/\s+/).map((w) => w.replace(/["*^{}():]/g, "")).filter((w) => w.length > 0);
+  if (words.length === 0) {
+    return exactSkillMatches;
+  }
+  const ftsQuery = words.map((w) => `"${w}"`).join(" OR ");
+  const conditions = [];
+  const params = [ftsQuery];
+  if (filters.level !== void 0) {
+    conditions.push(`json_extract(cc.data, '$.level') = ?`);
+    params.push(filters.level);
+  }
+  if (filters.online !== void 0) {
+    conditions.push(`json_extract(cc.data, '$.availability.online') = ?`);
+    params.push(filters.online ? 1 : 0);
+  }
+  const whereClause = conditions.length > 0 ? `AND ${conditions.join(" AND ")}` : "";
+  const sql = `
+    SELECT cc.data
+    FROM capability_cards cc
+    JOIN cards_fts ON cc.rowid = cards_fts.rowid
+    WHERE cards_fts MATCH ?
+      ${whereClause}
+    ORDER BY bm25(cards_fts)
+    LIMIT 50
+  `;
+  const stmt = db.prepare(sql);
+  const rows = stmt.all(...params);
+  const results = rows.map((row) => JSON.parse(row.data));
+  const mergedResults = mergeByCardId(exactSkillMatches, results);
+  let filtered = mergedResults;
+  if (filters.apis_used && filters.apis_used.length > 0) {
+    const requiredApis = filters.apis_used;
+    filtered = filtered.filter((card) => {
+      const cardApis = card.metadata?.apis_used ?? [];
+      return requiredApis.every((api) => cardApis.includes(api));
+    });
+  }
+  if (filters.min_reputation !== void 0 && filters.min_reputation > 0) {
+    filtered = applyReputationFilter(db, filtered, filters.min_reputation);
+  }
+  evictCache(cache);
+  cache.set(key, { results: filtered, expiresAt: Date.now() + CACHE_TTL_MS });
+  return filtered;
+}
+function mergeByCardId(primary, secondary) {
+  const seen = /* @__PURE__ */ new Set();
+  const merged = [];
+  for (const card of primary) {
+    if (seen.has(card.id)) continue;
+    seen.add(card.id);
+    merged.push(card);
+  }
+  for (const card of secondary) {
+    if (seen.has(card.id)) continue;
+    seen.add(card.id);
+    merged.push(card);
+  }
+  return merged;
+}
+function findCardsByExactSkillId(db, query, filters) {
+  if (query.length === 0) return [];
+  const rows = db.prepare("SELECT data FROM capability_cards").all();
+  const cards = rows.map((row) => JSON.parse(row.data));
+  return cards.filter((card) => {
+    if (filters.level !== void 0 && card.level !== filters.level) return false;
+    if (filters.online !== void 0 && card.availability?.online !== filters.online) return false;
+    const asRecord = card;
+    const skills = asRecord["skills"];
+    if (!Array.isArray(skills)) return false;
+    return skills.some((skill) => String(skill["id"] ?? "") === query);
   });
-  return {
-    publicKey: Buffer.from(publicKey),
-    privateKey: Buffer.from(privateKey)
-  };
 }
-function saveKeyPair(configDir, keys) {
-  const privatePath = join(configDir, "private.key");
-  const publicPath = join(configDir, "public.key");
-  writeFileSync(privatePath, keys.privateKey);
-  chmodSync(privatePath, 384);
-  writeFileSync(publicPath, keys.publicKey);
-}
-function loadKeyPair(configDir) {
-  const privatePath = join(configDir, "private.key");
-  const publicPath = join(configDir, "public.key");
-  if (!existsSync(privatePath) || !existsSync(publicPath)) {
-    throw new AgentBnBError("Keypair not found. Run `agentbnb init` to generate one.", "KEYPAIR_NOT_FOUND");
+function filterCards(db, filters) {
+  const conditions = [];
+  const params = [];
+  if (filters.level !== void 0) {
+    conditions.push(`json_extract(data, '$.level') = ?`);
+    params.push(filters.level);
+  }
+  if (filters.online !== void 0) {
+    conditions.push(`json_extract(data, '$.availability.online') = ?`);
+    params.push(filters.online ? 1 : 0);
+  }
+  const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+  const sql = `SELECT data FROM capability_cards ${whereClause}`;
+  const stmt = db.prepare(sql);
+  const rows = stmt.all(...params);
+  let cards = rows.map((row) => JSON.parse(row.data));
+  if (filters.min_reputation !== void 0 && filters.min_reputation > 0) {
+    cards = applyReputationFilter(db, cards, filters.min_reputation);
+  }
+  return cards;
+}
+function applyReputationFilter(db, cards, minReputation) {
+  const owners = [...new Set(cards.map((c) => c.owner))];
+  const reputationMap = /* @__PURE__ */ new Map();
+  for (const owner of owners) {
+    reputationMap.set(owner, getReputationScore(db, owner));
+  }
+  return cards.filter((card) => {
+    const score = reputationMap.get(card.owner) ?? 0.5;
+    return score >= minReputation;
+  });
+}
+function buildReputationMap(db, owners) {
+  const unique = [...new Set(owners)];
+  const map = /* @__PURE__ */ new Map();
+  for (const owner of unique) {
+    map.set(owner, getReputationScore(db, owner));
+  }
+  return map;
+}
+
+// src/cli/remote-registry.ts
+var RegistryTimeoutError = class extends AgentBnBError {
+  constructor(url) {
+    super(
+      `Registry at ${url} did not respond within 5s. Showing local results only.`,
+      "REGISTRY_TIMEOUT"
+    );
+    this.name = "RegistryTimeoutError";
+  }
+};
+var RegistryConnectionError = class extends AgentBnBError {
+  constructor(url) {
+    super(
+      `Cannot reach ${url}. Is the registry running? Showing local results only.`,
+      "REGISTRY_CONNECTION"
+    );
+    this.name = "RegistryConnectionError";
+  }
+};
+var RegistryAuthError = class extends AgentBnBError {
+  constructor(url) {
+    super(
+      `Authentication failed for ${url}. Run \`agentbnb config set token <your-token>\`.`,
+      "REGISTRY_AUTH"
+    );
+    this.name = "RegistryAuthError";
+  }
+};
+async function fetchRemoteCards(registryUrl, params, timeoutMs = 5e3) {
+  let cardsUrl;
+  try {
+    cardsUrl = new URL("/cards", registryUrl);
+  } catch {
+    throw new AgentBnBError(`Invalid registry URL: ${registryUrl}`, "INVALID_REGISTRY_URL");
+  }
+  const searchParams = new URLSearchParams();
+  if (params.q !== void 0) searchParams.set("q", params.q);
+  if (params.level !== void 0) searchParams.set("level", String(params.level));
+  if (params.online !== void 0) searchParams.set("online", String(params.online));
+  if (params.tag !== void 0) searchParams.set("tag", params.tag);
+  searchParams.set("limit", "100");
+  cardsUrl.search = searchParams.toString();
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  let response;
+  try {
+    response = await fetch(cardsUrl.toString(), { signal: controller.signal });
+  } catch (err) {
+    clearTimeout(timer);
+    const isTimeout = err instanceof Error && err.name === "AbortError";
+    if (isTimeout) {
+      throw new RegistryTimeoutError(registryUrl);
+    }
+    throw new RegistryConnectionError(registryUrl);
+  } finally {
+    clearTimeout(timer);
+  }
+  if (response.status === 401 || response.status === 403) {
+    throw new RegistryAuthError(registryUrl);
+  }
+  if (!response.ok) {
+    throw new RegistryConnectionError(registryUrl);
+  }
+  const body = await response.json();
+  return body.items;
+}
+function mergeResults(localCards, remoteCards, hasQuery) {
+  const taggedLocal = localCards.map((c) => ({ ...c, source: "local" }));
+  const taggedRemote = remoteCards.map((c) => ({ ...c, source: "remote" }));
+  const localIds = new Set(localCards.map((c) => c.id));
+  const dedupedRemote = taggedRemote.filter((c) => !localIds.has(c.id));
+  if (!hasQuery) {
+    return [...taggedLocal, ...dedupedRemote];
+  }
+  const result = [];
+  const maxLen = Math.max(taggedLocal.length, dedupedRemote.length);
+  for (let i = 0; i < maxLen; i++) {
+    if (i < taggedLocal.length) result.push(taggedLocal[i]);
+    if (i < dedupedRemote.length) result.push(dedupedRemote[i]);
+  }
+  return result;
+}
+
+// src/gateway/resolve-target-capability.ts
+function canQueryLocalDb(db) {
+  return Boolean(db) && typeof db.prepare === "function";
+}
+function getGatewayUrl(card) {
+  if (typeof card.gateway_url === "string" && card.gateway_url.length > 0) {
+    return card.gateway_url;
   }
+  const internal = card._internal;
+  const internalGateway = internal?.["gateway_url"];
+  return typeof internalGateway === "string" ? internalGateway : "";
+}
+function isOnline(card) {
+  return card.availability?.online !== false;
+}
+function scoreSkill(skill, query) {
+  const q = query.toLowerCase();
+  if (skill.id.toLowerCase() === q) return 100;
+  let score = 0;
+  if (skill.id.toLowerCase().includes(q)) score += 40;
+  if (skill.name.toLowerCase().includes(q)) score += 20;
+  if (skill.description.toLowerCase().includes(q)) score += 10;
+  return score;
+}
+function pickSkill(card, queryOrId) {
+  const skills = Array.isArray(card.skills) ? card.skills : [];
+  if (skills.length === 0) return void 0;
+  const exact = skills.find((s) => s.id === queryOrId);
+  if (exact) return exact;
+  const scored = skills.map((skill) => ({ skill, score: scoreSkill(skill, queryOrId) })).sort((a, b) => b.score - a.score);
+  if ((scored[0]?.score ?? 0) > 0) return scored[0]?.skill;
+  return skills[0];
+}
+function toResolved(card, queryOrId, source) {
+  const skill = pickSkill(card, queryOrId);
+  const gatewayUrl = getGatewayUrl(card);
+  const viaRelay = source === "local" ? false : gatewayUrl.length === 0;
+  const resolvedSource = viaRelay ? "relay" : source;
   return {
-    publicKey: readFileSync(publicPath),
-    privateKey: readFileSync(privatePath)
+    cardId: card.id,
+    skillId: skill?.id,
+    owner: card.owner,
+    gateway_url: gatewayUrl,
+    via_relay: viaRelay,
+    credits_per_call: skill?.pricing.credits_per_call ?? card.pricing.credits_per_call,
+    source: resolvedSource
   };
 }
-function canonicalJson(data) {
-  return JSON.stringify(data, Object.keys(data).sort());
+function findLocalBySkillId(db, skillId, onlineOnly) {
+  const rows = db.prepare("SELECT data FROM capability_cards").all();
+  for (const row of rows) {
+    const card = JSON.parse(row.data);
+    if (onlineOnly && !isOnline(card)) continue;
+    const skills = Array.isArray(card.skills) ? card.skills : [];
+    if (skills.some((s) => s.id === skillId)) {
+      return card;
+    }
+  }
+  return null;
+}
+function findRemoteBySkillId(cards, skillId) {
+  for (const card of cards) {
+    const skills = Array.isArray(card.skills) ? card.skills : [];
+    if (skills.some((s) => s.id === skillId)) return card;
+  }
+  return null;
 }
-function signEscrowReceipt(data, privateKey) {
-  const message = Buffer.from(canonicalJson(data), "utf-8");
-  const keyObject = createPrivateKey({ key: privateKey, format: "der", type: "pkcs8" });
-  const signature = sign(null, message, keyObject);
-  return signature.toString("base64url");
+function looksLikeCardId(value) {
+  return /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value);
 }
-function verifyEscrowReceipt(data, signature, publicKey) {
+async function resolveTargetCapability(queryOrId, options) {
+  const { registryDb, registryUrl, onlineOnly = true } = options;
+  const needle = queryOrId.trim();
+  if (needle.length === 0) return null;
+  if (canQueryLocalDb(registryDb)) {
+    const byCardId = getCard(registryDb, needle);
+    if (byCardId && (!onlineOnly || isOnline(byCardId))) {
+      return toResolved(byCardId, needle, "local");
+    }
+    const bySkillId = findLocalBySkillId(registryDb, needle, onlineOnly);
+    if (bySkillId) {
+      return toResolved(bySkillId, needle, "local");
+    }
+    const localMatches = searchCards(registryDb, needle, { online: onlineOnly ? true : void 0 });
+    if (localMatches.length > 0) {
+      return toResolved(localMatches[0], needle, "local");
+    }
+  }
+  if (!registryUrl) return null;
+  if (looksLikeCardId(needle)) {
+    try {
+      const cardResp = await fetch(`${registryUrl.replace(/\/$/, "")}/cards/${encodeURIComponent(needle)}`);
+      if (cardResp.ok) {
+        const remoteCard = await cardResp.json();
+        if (!onlineOnly || isOnline(remoteCard)) {
+          return toResolved(remoteCard, needle, "remote");
+        }
+      }
+    } catch {
+    }
+  }
   try {
-    const message = Buffer.from(canonicalJson(data), "utf-8");
-    const keyObject = createPublicKey({ key: publicKey, format: "der", type: "spki" });
-    const sigBuffer = Buffer.from(signature, "base64url");
-    return verify(null, message, keyObject, sigBuffer);
+    const remoteMatches = await fetchRemoteCards(registryUrl, {
+      q: needle,
+      ...onlineOnly ? { online: true } : {}
+    });
+    if (remoteMatches.length > 0) {
+      const exactSkill = findRemoteBySkillId(remoteMatches, needle);
+      if (exactSkill) return toResolved(exactSkill, needle, "remote");
+      return toResolved(remoteMatches[0], needle, "remote");
+    }
+  } catch {
+  }
+  try {
+    const onlineCards = await fetchRemoteCards(registryUrl, {
+      ...onlineOnly ? { online: true } : {}
+    });
+    const exactSkill = findRemoteBySkillId(onlineCards, needle);
+    if (exactSkill) return toResolved(exactSkill, needle, "relay");
+    const tokens = needle.toLowerCase().split(/\s+/).filter((t) => t.length > 0);
+    const fuzzy = onlineCards.find((card) => {
+      const text = [
+        card.name,
+        card.description,
+        ...Array.isArray(card.skills) ? card.skills.map((s) => `${s.id} ${s.name} ${s.description}`) : []
+      ].join(" ").toLowerCase();
+      return tokens.some((token) => text.includes(token));
+    });
+    if (fuzzy) return toResolved(fuzzy, needle, "relay");
   } catch {
-    return false;
   }
+  return null;
 }
 
 export {
@@ -1140,6 +1550,7 @@ export {
   listCards,
   getCardsByCapabilityType,
   getCardsBySkillCapability,
+  lookupAgent,
   openCreditDb,
   bootstrapAgent,
   getBalance,
@@ -1151,9 +1562,11 @@ export {
   settleEscrow,
   releaseEscrow,
   confirmEscrowDebit,
-  generateKeyPair,
-  saveKeyPair,
-  loadKeyPair,
-  signEscrowReceipt,
-  verifyEscrowReceipt
+  computeReputation,
+  searchCards,
+  filterCards,
+  buildReputationMap,
+  fetchRemoteCards,
+  mergeResults,
+  resolveTargetCapability
 };