agentbnb 8.4.3 → 8.4.5

package/dist/chunk-5SIGMKOD.js

@@ -0,0 +1,1086 @@
+import {
+  bootstrapAgent,
+  getBalance,
+  getTransactions,
+  holdEscrow,
+  migrateOwner,
+  openCreditDb,
+  releaseEscrow,
+  resolveTargetCapability,
+  settleEscrow
+} from "./chunk-NQANA6WH.js";
+import {
+  canonicalizeCreditOwner
+} from "./chunk-6QMDJVMS.js";
+import {
+  generateKeyPair,
+  loadKeyPair,
+  saveKeyPair,
+  signEscrowReceipt,
+  verifyEscrowReceipt
+} from "./chunk-GIEJVKZZ.js";
+import {
+  getConfigDir,
+  loadConfig
+} from "./chunk-IVOYM3WG.js";
+import {
+  getCard,
+  insertRequestLog,
+  updateReputation
+} from "./chunk-ZU2TP7CN.js";
+import {
+  lookupAgent
+} from "./chunk-EE3V3DXK.js";
+import {
+  AgentBnBError
+} from "./chunk-I7KWA7OB.js";
+
+// src/gateway/execute.ts
+import { randomUUID } from "crypto";
+
+// src/identity/identity.ts
+import { z } from "zod";
+import { createHash, createPrivateKey, createPublicKey } from "crypto";
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "fs";
+import { join } from "path";
+var AgentIdentitySchema = z.object({
+  /** Deterministic ID derived from public key: sha256(hex).slice(0, 16). */
+  agent_id: z.string().min(1),
+  /** Human-readable owner name (from config or init). */
+  owner: z.string().min(1),
+  /** Hex-encoded Ed25519 public key. */
+  public_key: z.string().min(1),
+  /** ISO 8601 timestamp of identity creation. */
+  created_at: z.string().datetime(),
+  /** Optional guarantor info if linked to a human. */
+  guarantor: z.object({
+    github_login: z.string().min(1),
+    verified_at: z.string().datetime()
+  }).optional()
+});
+var AgentCertificateSchema = z.object({
+  identity: AgentIdentitySchema,
+  /** ISO 8601 timestamp of certificate issuance. */
+  issued_at: z.string().datetime(),
+  /** ISO 8601 timestamp of certificate expiry. */
+  expires_at: z.string().datetime(),
+  /** Hex-encoded public key of the issuer (same as identity for self-signed). */
+  issuer_public_key: z.string().min(1),
+  /** Base64url Ed25519 signature over { identity, issued_at, expires_at, issuer_public_key }. */
+  signature: z.string().min(1)
+});
+var IDENTITY_FILENAME = "identity.json";
+var PRIVATE_KEY_FILENAME = "private.key";
+var PUBLIC_KEY_FILENAME = "public.key";
+function derivePublicKeyFromPrivate(privateKey) {
+  const privateKeyObject = createPrivateKey({ key: privateKey, format: "der", type: "pkcs8" });
+  const publicKeyObject = createPublicKey(privateKeyObject);
+  const publicKey = publicKeyObject.export({ format: "der", type: "spki" });
+  return Buffer.from(publicKey);
+}
+function buildIdentityFromPublicKey(publicKey, owner, createdAt) {
+  const publicKeyHex = publicKey.toString("hex");
+  return {
+    agent_id: deriveAgentId(publicKeyHex),
+    owner,
+    public_key: publicKeyHex,
+    created_at: createdAt ?? (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+function generateFreshIdentity(configDir, owner) {
+  const keys = generateKeyPair();
+  saveKeyPair(configDir, keys);
+  const identity = buildIdentityFromPublicKey(keys.publicKey, owner);
+  saveIdentity(configDir, identity);
+  return { identity, keys, status: "generated" };
+}
+function deriveAgentId(publicKeyHex) {
+  return createHash("sha256").update(publicKeyHex, "hex").digest("hex").slice(0, 16);
+}
+function loadIdentity(configDir) {
+  const filePath = join(configDir, IDENTITY_FILENAME);
+  if (!existsSync(filePath)) return null;
+  try {
+    const raw = readFileSync(filePath, "utf-8");
+    return AgentIdentitySchema.parse(JSON.parse(raw));
+  } catch {
+    return null;
+  }
+}
+function saveIdentity(configDir, identity) {
+  if (!existsSync(configDir)) {
+    mkdirSync(configDir, { recursive: true });
+  }
+  const filePath = join(configDir, IDENTITY_FILENAME);
+  writeFileSync(filePath, JSON.stringify(identity, null, 2), "utf-8");
+}
+function loadOrRepairIdentity(configDir, ownerHint) {
+  if (!existsSync(configDir)) {
+    mkdirSync(configDir, { recursive: true });
+  }
+  const identityPath = join(configDir, IDENTITY_FILENAME);
+  const privateKeyPath = join(configDir, PRIVATE_KEY_FILENAME);
+  const publicKeyPath = join(configDir, PUBLIC_KEY_FILENAME);
+  const hasIdentity = existsSync(identityPath);
+  const hasPrivateKey = existsSync(privateKeyPath);
+  const hasPublicKey = existsSync(publicKeyPath);
+  if (!hasIdentity || !hasPrivateKey || !hasPublicKey) {
+    return generateFreshIdentity(configDir, ownerHint ?? "agent");
+  }
+  let keys;
+  try {
+    keys = loadKeyPair(configDir);
+  } catch {
+    return generateFreshIdentity(configDir, ownerHint ?? "agent");
+  }
+  let derivedPublicKey;
+  try {
+    derivedPublicKey = derivePublicKeyFromPrivate(keys.privateKey);
+  } catch {
+    return generateFreshIdentity(configDir, ownerHint ?? "agent");
+  }
+  let keypairRepaired = false;
+  if (!keys.publicKey.equals(derivedPublicKey)) {
+    keypairRepaired = true;
+    keys = { privateKey: keys.privateKey, publicKey: derivedPublicKey };
+    saveKeyPair(configDir, keys);
+  }
+  const loadedIdentity = loadIdentity(configDir);
+  const expectedAgentId = deriveAgentId(derivedPublicKey.toString("hex"));
+  const expectedPublicKeyHex = derivedPublicKey.toString("hex");
+  const identityMismatch = !loadedIdentity || loadedIdentity.public_key !== expectedPublicKeyHex || loadedIdentity.agent_id !== expectedAgentId;
+  if (identityMismatch) {
+    const repairedIdentity = buildIdentityFromPublicKey(
+      derivedPublicKey,
+      loadedIdentity?.owner ?? ownerHint ?? "agent",
+      loadedIdentity?.created_at
+    );
+    saveIdentity(configDir, repairedIdentity);
+    return { identity: repairedIdentity, keys, status: "repaired" };
+  }
+  if (ownerHint && loadedIdentity.owner !== ownerHint) {
+    const updatedIdentity = { ...loadedIdentity, owner: ownerHint };
+    saveIdentity(configDir, updatedIdentity);
+    return { identity: updatedIdentity, keys, status: "repaired" };
+  }
+  return { identity: loadedIdentity, keys, status: keypairRepaired ? "repaired" : "existing" };
+}
+function ensureIdentity(configDir, owner) {
+  return loadOrRepairIdentity(configDir, owner).identity;
+}
+
+// src/credit/local-credit-ledger.ts
+var LocalCreditLedger = class {
+  constructor(db) {
+    this.db = db;
+  }
+  /**
+   * Holds credits in escrow during capability execution.
+   *
+   * @param owner - Agent identifier (requester).
+   * @param amount - Number of credits to hold.
+   * @param cardId - Capability Card ID being requested.
+   * @returns EscrowResult with the new escrowId.
+   * @throws {AgentBnBError} with code 'INSUFFICIENT_CREDITS' if balance < amount.
+   */
+  async hold(owner, amount, cardId) {
+    const escrowId = holdEscrow(this.db, owner, amount, cardId);
+    return { escrowId };
+  }
+  /**
+   * Settles an escrow — transfers held credits to the capability provider.
+   *
+   * @param escrowId - The escrow ID to settle.
+   * @param recipientOwner - Agent identifier who will receive the credits.
+   * @throws {AgentBnBError} with code 'ESCROW_NOT_FOUND' if escrow does not exist.
+   * @throws {AgentBnBError} with code 'ESCROW_ALREADY_SETTLED' if escrow is not in 'held' status.
+   */
+  async settle(escrowId, recipientOwner) {
+    settleEscrow(this.db, escrowId, recipientOwner);
+  }
+  /**
+   * Releases an escrow — refunds credits back to the requester.
+   *
+   * @param escrowId - The escrow ID to release.
+   * @throws {AgentBnBError} with code 'ESCROW_NOT_FOUND' if escrow does not exist.
+   * @throws {AgentBnBError} with code 'ESCROW_ALREADY_SETTLED' if escrow is not in 'held' status.
+   */
+  async release(escrowId) {
+    releaseEscrow(this.db, escrowId);
+  }
+  /**
+   * Returns the current credit balance for an agent.
+   *
+   * @param owner - Agent identifier.
+   * @returns Current balance in credits (0 if agent is unknown).
+   */
+  async getBalance(owner) {
+    return getBalance(this.db, owner);
+  }
+  /**
+   * Returns the transaction history for an agent, newest first.
+   *
+   * @param owner - Agent identifier.
+   * @param limit - Maximum number of transactions to return. Defaults to 100.
+   * @returns Array of credit transactions ordered newest first.
+   */
+  async getHistory(owner, limit) {
+    return getTransactions(this.db, owner, limit);
+  }
+  /**
+   * Grants initial credits to an agent (bootstrap grant).
+   * Idempotent — calling multiple times has no additional effect on balance.
+   *
+   * @param owner - Agent identifier.
+   * @param amount - Number of credits to grant. Defaults to 100.
+   */
+  async grant(owner, amount) {
+    bootstrapAgent(this.db, owner, amount);
+  }
+  async rename(oldOwner, newOwner) {
+    migrateOwner(this.db, oldOwner, newOwner);
+  }
+};
+
+// src/registry/identity-auth.ts
+var MAX_REQUEST_AGE_MS = 5 * 60 * 1e3;
+function normalizeSignedParams(body) {
+  return body === void 0 ? null : body;
+}
+function buildIdentityPayload(method, path, timestamp, publicKeyHex, agentId, params) {
+  return {
+    method,
+    path,
+    timestamp,
+    publicKey: publicKeyHex,
+    agentId,
+    params: normalizeSignedParams(params)
+  };
+}
+function extractClaimedRequester(request) {
+  const extractFromObject = (obj) => {
+    const directOwner = typeof obj.owner === "string" ? obj.owner.trim() : "";
+    if (directOwner) return directOwner;
+    const directRequester = typeof obj.requester === "string" ? obj.requester.trim() : "";
+    if (directRequester) return directRequester;
+    const oldOwner = typeof obj.oldOwner === "string" ? obj.oldOwner.trim() : "";
+    if (oldOwner) return oldOwner;
+    const nestedParams = obj.params;
+    if (nestedParams && typeof nestedParams === "object" && !Array.isArray(nestedParams)) {
+      const nested = nestedParams;
+      const nestedOwner = typeof nested.owner === "string" ? nested.owner.trim() : "";
+      if (nestedOwner) return nestedOwner;
+      const nestedRequester = typeof nested.requester === "string" ? nested.requester.trim() : "";
+      if (nestedRequester) return nestedRequester;
+    }
+    return null;
+  };
+  if (request.body && typeof request.body === "object" && !Array.isArray(request.body)) {
+    const claimed = extractFromObject(request.body);
+    if (claimed) return claimed;
+  }
+  if (request.params && typeof request.params === "object" && !Array.isArray(request.params)) {
+    const claimed = extractFromObject(request.params);
+    if (claimed) return claimed;
+  }
+  return null;
+}
+async function verifyIdentity(request, reply, options) {
+  const agentIdHeader = request.headers["x-agent-id"];
+  const publicKeyHeader = request.headers["x-agent-publickey"];
+  const signatureHeader = request.headers["x-agent-signature"];
+  const timestampHeader = request.headers["x-agent-timestamp"];
+  const agentId = agentIdHeader?.trim();
+  const publicKeyHex = publicKeyHeader?.trim();
+  const signature = signatureHeader?.trim();
+  const timestamp = timestampHeader?.trim();
+  if (!agentId || !publicKeyHex || !signature || !timestamp) {
+    await reply.code(401).send({ error: "Missing identity headers" });
+    return false;
+  }
+  const requestTime = new Date(timestamp).getTime();
+  if (isNaN(requestTime) || Math.abs(Date.now() - requestTime) > MAX_REQUEST_AGE_MS) {
+    await reply.code(401).send({ error: "Request expired" });
+    return false;
+  }
+  if (!/^[0-9a-fA-F]+$/.test(publicKeyHex) || publicKeyHex.length % 2 !== 0) {
+    await reply.code(401).send({ error: "Invalid identity signature" });
+    return false;
+  }
+  let expectedAgentId;
+  try {
+    expectedAgentId = deriveAgentId(publicKeyHex);
+  } catch {
+    await reply.code(401).send({ error: "Invalid identity signature" });
+    return false;
+  }
+  if (agentId !== expectedAgentId) {
+    await reply.code(401).send({ error: "Invalid identity signature" });
+    return false;
+  }
+  let publicKeyBuffer;
+  try {
+    publicKeyBuffer = Buffer.from(publicKeyHex, "hex");
+  } catch {
+    await reply.code(401).send({ error: "Invalid identity signature" });
+    return false;
+  }
+  const knownAgent = options.agentDb ? lookupAgent(options.agentDb, agentId) : null;
+  if (knownAgent && knownAgent.public_key.toLowerCase() !== publicKeyHex.toLowerCase()) {
+    await reply.code(401).send({ error: "Invalid identity signature" });
+    return false;
+  }
+  const payload = buildIdentityPayload(
+    request.method,
+    request.url,
+    timestamp,
+    publicKeyHex,
+    agentId,
+    request.body
+  );
+  const valid = verifyEscrowReceipt(payload, signature, publicKeyBuffer);
+  if (!valid) {
+    await reply.code(401).send({ error: "Invalid identity signature" });
+    return false;
+  }
+  const claimedRequester = extractClaimedRequester(request);
+  if (claimedRequester && knownAgent !== null) {
+    const matchesAgentId = claimedRequester === agentId;
+    const matchesDisplayName = knownAgent.display_name === claimedRequester;
+    const matchesLegacyOwner = knownAgent.legacy_owner === claimedRequester;
+    if (!matchesAgentId && !matchesDisplayName && !matchesLegacyOwner) {
+      await reply.code(401).send({ error: "Identity does not match requester" });
+      return false;
+    }
+  }
+  request.agentPublicKey = publicKeyHex;
+  request.agentId = agentId;
+  return true;
+}
+function identityAuthPlugin(fastify, options = {}) {
+  fastify.addHook("preHandler", async (request, reply) => {
+    const ok = await verifyIdentity(request, reply, options);
+    if (!ok) {
+      return reply;
+    }
+  });
+}
+function signRequest(method, path, body, privateKey, publicKeyHex, agentIdOverride) {
+  const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+  const agentId = agentIdOverride ?? deriveAgentId(publicKeyHex);
+  const payload = buildIdentityPayload(method, path, timestamp, publicKeyHex, agentId, body);
+  const signature = signEscrowReceipt(payload, privateKey);
+  return {
+    "X-Agent-Id": agentId,
+    "X-Agent-PublicKey": publicKeyHex,
+    "X-Agent-Signature": signature,
+    "X-Agent-Timestamp": timestamp
+  };
+}
+
+// src/credit/registry-credit-ledger.ts
+var HTTP_TIMEOUT_MS = 1e4;
+var RegistryCreditLedger = class {
+  config;
+  constructor(config) {
+    this.config = config;
+  }
+  /**
+   * Holds credits in escrow during capability execution.
+   *
+   * @param owner - Agent identifier (requester).
+   * @param amount - Number of credits to hold.
+   * @param cardId - Capability Card ID being requested.
+   * @returns EscrowResult with the new escrowId.
+   * @throws {AgentBnBError} with code 'INSUFFICIENT_CREDITS' if balance < amount.
+   */
+  async hold(owner, amount, cardId) {
+    if (this.config.mode === "direct") {
+      const escrowId = holdEscrow(this.config.db, owner, amount, cardId);
+      return { escrowId };
+    }
+    const data = await this.post("/api/credits/hold", owner, {
+      owner,
+      amount,
+      cardId
+    });
+    return { escrowId: data.escrowId };
+  }
+  /**
+   * Settles an escrow — transfers held credits to the capability provider.
+   *
+   * @param escrowId - The escrow ID to settle.
+   * @param recipientOwner - Agent identifier who will receive the credits.
+   * @throws {AgentBnBError} with code 'ESCROW_NOT_FOUND' if escrow does not exist.
+   * @throws {AgentBnBError} with code 'ESCROW_ALREADY_SETTLED' if escrow is not in 'held' status.
+   */
+  async settle(escrowId, recipientOwner) {
+    if (this.config.mode === "direct") {
+      settleEscrow(this.config.db, escrowId, recipientOwner);
+      return;
+    }
+    await this.post("/api/credits/settle", null, { escrowId, recipientOwner });
+  }
+  /**
+   * Releases an escrow — refunds credits back to the requester.
+   *
+   * @param escrowId - The escrow ID to release.
+   * @throws {AgentBnBError} with code 'ESCROW_NOT_FOUND' if escrow does not exist.
+   * @throws {AgentBnBError} with code 'ESCROW_ALREADY_SETTLED' if escrow is not in 'held' status.
+   */
+  async release(escrowId) {
+    if (this.config.mode === "direct") {
+      releaseEscrow(this.config.db, escrowId);
+      return;
+    }
+    await this.post("/api/credits/release", null, { escrowId });
+  }
+  /**
+   * Returns the current credit balance for an agent.
+   *
+   * @param owner - Agent identifier.
+   * @returns Current balance in credits (0 if agent is unknown).
+   */
+  async getBalance(owner) {
+    if (this.config.mode === "direct") {
+      return getBalance(this.config.db, owner);
+    }
+    const data = await this.get(`/api/credits/${owner}`, owner);
+    return data.balance;
+  }
+  /**
+   * Returns the transaction history for an agent, newest first.
+   *
+   * @param owner - Agent identifier.
+   * @param limit - Maximum number of transactions to return. Defaults to 100.
+   * @returns Array of credit transactions ordered newest first.
+   */
+  async getHistory(owner, limit = 100) {
+    if (this.config.mode === "direct") {
+      return getTransactions(this.config.db, owner, limit);
+    }
+    const data = await this.get(
+      `/api/credits/${owner}/history?limit=${limit}`,
+      owner
+    );
+    return data.transactions;
+  }
+  /**
+   * Grants initial credits to an agent (bootstrap grant).
+   * Idempotent — calling multiple times has no additional effect on balance.
+   *
+   * @param owner - Agent identifier.
+   * @param amount - Number of credits to grant. Defaults to 100.
+   */
+  async grant(owner, amount = 100) {
+    if (this.config.mode === "direct") {
+      bootstrapAgent(this.config.db, owner, amount);
+      return;
+    }
+    await this.post("/api/credits/grant", owner, { owner, amount });
+  }
+  /**
+   * Renames an owner — migrates balance, transactions, and escrows.
+   */
+  async rename(oldOwner, newOwner) {
+    if (oldOwner === newOwner) return;
+    if (this.config.mode === "direct") {
+      migrateOwner(this.config.db, oldOwner, newOwner);
+      return;
+    }
+    await this.post("/api/credits/rename", null, { oldOwner, newOwner });
+  }
+  // ─── Private HTTP helpers ─────────────────────────────────────────────────
+  /**
+   * Makes an authenticated POST request to the Registry HTTP API.
+   * Includes a 10s timeout via AbortController.
+   *
+   * @param path - API path (e.g., '/api/credits/hold').
+   * @param ownerForHeader - Agent owner identifier for X-Agent-Owner header, or null to omit.
+   * @param body - JSON body to send.
+   * @returns Parsed JSON response body.
+   * @throws {AgentBnBError} on non-2xx responses or network errors.
+   */
+  async post(path, ownerForHeader, body) {
+    const cfg = this.config;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), HTTP_TIMEOUT_MS);
+    try {
+      const authHeaders = signRequest("POST", path, body, cfg.privateKey, cfg.ownerPublicKey);
+      const headers = {
+        "Content-Type": "application/json",
+        ...authHeaders
+      };
+      void ownerForHeader;
+      const res = await fetch(`${cfg.registryUrl}${path}`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(body),
+        signal: controller.signal
+      });
+      return await this.handleResponse(res);
+    } catch (err) {
+      if (err instanceof AgentBnBError) throw err;
+      throw new AgentBnBError(
+        `Registry unreachable: ${err.message}`,
+        "REGISTRY_UNREACHABLE"
+      );
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+  /**
+   * Makes an authenticated GET request to the Registry HTTP API.
+   * Includes a 10s timeout via AbortController.
+   *
+   * @param path - API path (e.g., '/api/credits/owner-id').
+   * @param owner - Agent owner identifier for X-Agent-Owner header.
+   * @returns Parsed JSON response body.
+   * @throws {AgentBnBError} on non-2xx responses or network errors.
+   */
+  async get(path, owner) {
+    const cfg = this.config;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), HTTP_TIMEOUT_MS);
+    try {
+      const authHeaders = signRequest("GET", path, null, cfg.privateKey, cfg.ownerPublicKey);
+      void owner;
+      const res = await fetch(`${cfg.registryUrl}${path}`, {
+        method: "GET",
+        headers: {
+          "Content-Type": "application/json",
+          ...authHeaders
+        },
+        signal: controller.signal
+      });
+      return await this.handleResponse(res);
+    } catch (err) {
+      if (err instanceof AgentBnBError) throw err;
+      throw new AgentBnBError(
+        `Registry unreachable: ${err.message}`,
+        "REGISTRY_UNREACHABLE"
+      );
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+  /**
+   * Handles an HTTP response — returns parsed JSON on 2xx, throws AgentBnBError on error.
+   */
+  async handleResponse(res) {
+    const json = await res.json();
+    if (!res.ok) {
+      const code = typeof json["code"] === "string" ? json["code"] : "REGISTRY_ERROR";
+      const message = typeof json["error"] === "string" ? json["error"] : `HTTP ${res.status}`;
+      throw new AgentBnBError(message, code);
+    }
+    return json;
+  }
+};
+
+// src/credit/create-ledger.ts
+function createLedger(opts) {
+  if ("registryUrl" in opts && opts.registryUrl !== void 0) {
+    return new RegistryCreditLedger({
+      mode: "http",
+      registryUrl: opts.registryUrl,
+      ownerPublicKey: opts.ownerPublicKey,
+      privateKey: opts.privateKey
+    });
+  }
+  if ("db" in opts && opts.db !== void 0) {
+    return new RegistryCreditLedger({
+      mode: "direct",
+      db: opts.db
+    });
+  }
+  const db = openCreditDb(opts.creditDbPath);
+  return new LocalCreditLedger(db);
+}
+
+// src/credit/registry-sync.ts
+async function syncCreditsFromRegistry(config, localDb) {
+  if (!config.registry) {
+    return { synced: false, error: "no registry configured" };
+  }
+  try {
+    const configDir = getConfigDir();
+    const { identity, keys } = loadOrRepairIdentity(configDir, config.owner);
+    const ledger = createLedger({
+      registryUrl: config.registry,
+      ownerPublicKey: identity.public_key,
+      privateKey: keys.privateKey
+    });
+    const [remoteBalance, remoteHistory] = await Promise.all([
+      ledger.getBalance(config.owner),
+      ledger.getHistory(config.owner, 50)
+    ]);
+    const localWas = getBalance(localDb, config.owner);
+    localDb.transaction(() => {
+      const now = (/* @__PURE__ */ new Date()).toISOString();
+      const canonicalOwner = canonicalizeCreditOwner(localDb, config.owner);
+      localDb.prepare(
+        "INSERT OR REPLACE INTO credit_balances (owner, balance, updated_at) VALUES (?, ?, ?)"
+      ).run(canonicalOwner, remoteBalance, now);
+      const insertTxn = localDb.prepare(
+        "INSERT OR IGNORE INTO credit_transactions (id, owner, amount, reason, reference_id, created_at) VALUES (?, ?, ?, ?, ?, ?)"
+      );
+      for (const txn of remoteHistory) {
+        insertTxn.run(
+          txn.id,
+          txn.owner,
+          txn.amount,
+          txn.reason,
+          txn.reference_id,
+          txn.created_at
+        );
+      }
+    })();
+    return { synced: true, remoteBalance, localWas };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return { synced: false, error: message };
+  }
+}
+
+// src/gateway/execute.ts
+async function notifyTelegramSkillExecuted(opts) {
+  const cfg = loadConfig();
+  if (!cfg?.telegram_notifications) return;
+  const token = cfg.telegram_bot_token ?? process.env["TELEGRAM_BOT_TOKEN"];
+  const chatId = cfg.telegram_chat_id ?? process.env["TELEGRAM_CHAT_ID"];
+  if (!token || !chatId) return;
+  const balance = getBalance(opts.creditDb, opts.owner);
+  const skillLabel = opts.skillId ? `${opts.skillName} (${opts.skillId})` : opts.skillName;
+  const text = [
+    "[AgentBnB] Skill executed",
+    `Skill: ${skillLabel}`,
+    `Requester: ${opts.requester}`,
+    `Earned: +${opts.creditsEarned} credits`,
+    `Balance: ${balance} credits`,
+    `Latency: ${opts.latencyMs}ms`
+  ].join("\n");
+  await fetch(`https://api.telegram.org/bot${token}/sendMessage`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ chat_id: chatId, text })
+  });
+}
+async function notifyTelegramSkillFailed(opts) {
+  const cfg = loadConfig();
+  if (!cfg?.telegram_notifications) return;
+  const token = cfg.telegram_bot_token ?? process.env["TELEGRAM_BOT_TOKEN"];
+  const chatId = cfg.telegram_chat_id ?? process.env["TELEGRAM_CHAT_ID"];
+  if (!token || !chatId) return;
+  const balance = getBalance(opts.creditDb, opts.owner);
+  const skillLabel = opts.skillId ? `${opts.skillName} (${opts.skillId})` : opts.skillName;
+  const text = [
+    "[AgentBnB] Skill failed",
+    `Skill: ${skillLabel}`,
+    `Requester: ${opts.requester}`,
+    `Reason: ${opts.failureReason}`,
+    `Error: ${opts.message}`,
+    `Balance: ${balance} credits`,
+    `Latency: ${opts.latencyMs}ms`
+  ].join("\n");
+  await fetch(`https://api.telegram.org/bot${token}/sendMessage`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ chat_id: chatId, text })
+  });
+}
+async function executeCapabilityRequest(opts) {
+  const {
+    registryDb,
+    creditDb,
+    cardId,
+    skillId,
+    params,
+    requester,
+    escrowReceipt: receipt,
+    skillExecutor,
+    handlerUrl,
+    timeoutMs = 3e5,
+    onProgress,
+    relayAuthorized = false
+  } = opts;
+  const card = getCard(registryDb, cardId);
+  if (!card) {
+    return { success: false, error: { code: -32602, message: `Card not found: ${cardId}` } };
+  }
+  if (requester === card.owner && !relayAuthorized) {
+    const msg = `Self-request blocked: requester (${requester}) is the card owner. Set AGENTBNB_DIR to your agent's config directory before calling agentbnb request.`;
+    try {
+      insertRequestLog(registryDb, {
+        id: randomUUID(),
+        card_id: cardId,
+        card_name: card.name,
+        skill_id: skillId,
+        requester,
+        status: "failure",
+        latency_ms: 0,
+        credits_charged: 0,
+        created_at: (/* @__PURE__ */ new Date()).toISOString(),
+        failure_reason: "auth_error"
+      });
+    } catch {
+    }
+    return { success: false, error: { code: -32603, message: msg } };
+  }
+  let creditsNeeded;
+  let cardName;
+  let resolvedSkillId;
+  const rawCard = card;
+  if (Array.isArray(rawCard["skills"])) {
+    const v2card = card;
+    const skill = skillId ? v2card.skills.find((s) => s.id === skillId) : v2card.skills[0];
+    if (!skill) {
+      return { success: false, error: { code: -32602, message: `Skill not found: ${skillId}` } };
+    }
+    creditsNeeded = skill.pricing.credits_per_call;
+    cardName = skill.name;
+    resolvedSkillId = skill.id;
+  } else {
+    creditsNeeded = card.pricing.credits_per_call;
+    cardName = card.name;
+  }
+  let escrowId = null;
+  if (relayAuthorized) {
+  } else if (receipt) {
+    if (creditsNeeded > 0) {
+      return {
+        success: false,
+        error: {
+          code: -32603,
+          message: "Direct HTTP paid remote settlement is disabled. Route paid requests through relay."
+        }
+      };
+    }
+  } else {
+    const cfg = loadConfig();
+    if (cfg?.registry) {
+      try {
+        await Promise.race([
+          syncCreditsFromRegistry(cfg, creditDb),
+          new Promise(
+            (_, reject) => setTimeout(() => reject(new Error("sync timeout")), 2e3)
+          )
+        ]);
+      } catch {
+      }
+    }
+    try {
+      const balance = getBalance(creditDb, requester);
+      if (balance < creditsNeeded) {
+        return { success: false, error: { code: -32603, message: "Insufficient credits" } };
+      }
+      escrowId = holdEscrow(creditDb, requester, creditsNeeded, cardId);
+    } catch (err) {
+      const msg = err instanceof AgentBnBError ? err.message : "Failed to hold escrow";
+      return { success: false, error: { code: -32603, message: msg } };
+    }
+  }
+  const startMs = Date.now();
+  const handleFailure = (status, latencyMs, message, failureReason = "bad_execution") => {
+    if (escrowId) releaseEscrow(creditDb, escrowId);
+    if (failureReason === "bad_execution" || failureReason === "auth_error") {
+      updateReputation(registryDb, cardId, false, latencyMs);
+    }
+    try {
+      insertRequestLog(registryDb, {
+        id: randomUUID(),
+        card_id: cardId,
+        card_name: cardName,
+        skill_id: resolvedSkillId,
+        requester,
+        status,
+        latency_ms: latencyMs,
+        credits_charged: 0,
+        created_at: (/* @__PURE__ */ new Date()).toISOString(),
+        failure_reason: failureReason
+      });
+    } catch {
+    }
+    notifyTelegramSkillFailed({
+      creditDb,
+      owner: card.owner,
+      skillName: cardName,
+      skillId: resolvedSkillId ?? null,
+      requester,
+      latencyMs,
+      failureReason,
+      message
+    }).catch(() => {
+    });
+    return { success: false, error: { code: -32603, message } };
+  };
+  const handleSuccess = (result, latencyMs) => {
+    if (escrowId) {
+      settleEscrow(creditDb, escrowId, card.owner);
+    }
+    updateReputation(registryDb, cardId, true, latencyMs);
+    try {
+      insertRequestLog(registryDb, {
+        id: randomUUID(),
+        card_id: cardId,
+        card_name: cardName,
+        skill_id: resolvedSkillId,
+        requester,
+        status: "success",
+        latency_ms: latencyMs,
+        credits_charged: creditsNeeded,
+        created_at: (/* @__PURE__ */ new Date()).toISOString()
+      });
+    } catch {
+    }
+    notifyTelegramSkillExecuted({
+      creditDb,
+      owner: card.owner,
+      skillName: cardName,
+      skillId: resolvedSkillId ?? null,
+      requester,
+      creditsEarned: creditsNeeded,
+      latencyMs
+    }).catch(() => {
+    });
+    return { success: true, result };
+  };
+  if (skillExecutor) {
+    let targetSkillId = resolvedSkillId ?? skillId;
+    if (!targetSkillId) {
+      const available = skillExecutor.listSkills();
+      if (available.length > 0) {
+        targetSkillId = available[0];
+      } else {
+        return handleFailure(
+          "failure",
+          Date.now() - startMs,
+          "No skill_id specified and no skills registered on this provider.",
+          "not_found"
+        );
+      }
+    }
+    try {
+      const execResult = await skillExecutor.execute(targetSkillId, params, onProgress);
+      if (!execResult.success) {
+        return handleFailure("failure", execResult.latency_ms, execResult.error ?? "Execution failed", "bad_execution");
+      }
+      return handleSuccess(execResult.result, execResult.latency_ms);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : "Execution error";
+      return handleFailure("failure", Date.now() - startMs, message, "bad_execution");
+    }
+  }
+  if (!handlerUrl) {
+    return handleFailure("failure", Date.now() - startMs, "No skill executor or handler URL configured", "bad_execution");
+  }
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetch(handlerUrl, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ card_id: cardId, skill_id: resolvedSkillId, params }),
+      signal: controller.signal
+    });
+    clearTimeout(timer);
+    if (!response.ok) {
+      return handleFailure("failure", Date.now() - startMs, `Handler returned ${response.status}`, "bad_execution");
+    }
+    const result = await response.json();
+    return handleSuccess(result, Date.now() - startMs);
+  } catch (err) {
+    clearTimeout(timer);
+    const isTimeout = err instanceof Error && err.name === "AbortError";
+    return handleFailure(
+      isTimeout ? "timeout" : "failure",
+      Date.now() - startMs,
+      isTimeout ? "Execution timeout" : "Handler error",
+      isTimeout ? "timeout" : "bad_execution"
+    );
+  }
+}
+async function executeCapabilityBatch(options) {
+  const { requests, strategy, total_budget, registryDb, creditDb, owner } = options;
+  if (requests.length === 0) {
+    return { results: [], total_credits_spent: 0, total_credits_refunded: 0, success: true };
+  }
+  const sumMaxCredits = requests.reduce((acc, r) => acc + r.max_credits, 0);
+  if (sumMaxCredits > total_budget) {
+    return {
+      results: requests.map((_, i) => ({
+        request_index: i,
+        status: "skipped",
+        credits_spent: 0,
+        credits_refunded: 0,
+        error: `Total requested credits (${sumMaxCredits}) exceeds total_budget (${total_budget})`
+      })),
+      total_credits_spent: 0,
+      total_credits_refunded: 0,
+      success: false
+    };
+  }
+  const executeItem = async (item, index) => {
+    const resolved = await resolveTargetCapability(item.skill_id, {
+      registryDb,
+      registryUrl: options.registryUrl,
+      onlineOnly: true
+    });
+    if (!resolved) {
+      return {
+        request_index: index,
+        status: "failed",
+        credits_spent: 0,
+        credits_refunded: 0,
+        error: `Card/skill not found: ${item.skill_id}`
+      };
+    }
+    const localCard = getCard(registryDb, resolved.cardId);
+    const localCardRaw = localCard;
+    const cardName = typeof localCardRaw?.["name"] === "string" ? localCardRaw["name"] : typeof localCardRaw?.["agent_name"] === "string" ? localCardRaw["agent_name"] : resolved.cardId;
+    const creditsNeeded = resolved.credits_per_call;
+    const resolvedSkillId = resolved.skillId;
+    if (creditsNeeded > item.max_credits) {
+      return {
+        request_index: index,
+        status: "failed",
+        credits_spent: 0,
+        credits_refunded: 0,
+        error: `Skill costs ${creditsNeeded} credits but max_credits is ${item.max_credits}`
+      };
+    }
+    let escrowId;
+    try {
+      const balance = getBalance(creditDb, owner);
+      if (balance < creditsNeeded) {
+        return {
+          request_index: index,
+          status: "failed",
+          credits_spent: 0,
+          credits_refunded: 0,
+          error: "Insufficient credits"
+        };
+      }
+      escrowId = holdEscrow(creditDb, owner, creditsNeeded, resolved.cardId);
+    } catch (err) {
+      const msg = err instanceof AgentBnBError ? err.message : "Failed to hold escrow";
+      return {
+        request_index: index,
+        status: "failed",
+        credits_spent: 0,
+        credits_refunded: 0,
+        error: msg
+      };
+    }
+    const startMs = Date.now();
+    try {
+      const result = options.dispatchRequest ? await options.dispatchRequest({
+        target: resolved,
+        params: item.params,
+        requester: owner
+      }) : { card_id: resolved.cardId, skill_id: resolvedSkillId };
+      const latencyMs = Date.now() - startMs;
+      settleEscrow(creditDb, escrowId, resolved.owner);
+      updateReputation(registryDb, resolved.cardId, true, latencyMs);
+      try {
+        insertRequestLog(registryDb, {
+          id: randomUUID(),
+          card_id: resolved.cardId,
+          card_name: cardName,
+          skill_id: resolvedSkillId,
+          requester: owner,
+          status: "success",
+          latency_ms: latencyMs,
+          credits_charged: creditsNeeded,
+          created_at: (/* @__PURE__ */ new Date()).toISOString()
+        });
+      } catch {
+      }
+      return {
+        request_index: index,
+        status: "success",
+        result,
+        credits_spent: creditsNeeded,
+        credits_refunded: 0
+      };
+    } catch (err) {
+      releaseEscrow(creditDb, escrowId);
+      const latencyMs = Date.now() - startMs;
+      try {
+        insertRequestLog(registryDb, {
+          id: randomUUID(),
+          card_id: resolved.cardId,
+          card_name: cardName,
+          skill_id: resolvedSkillId,
+          requester: owner,
+          status: "failure",
+          latency_ms: latencyMs,
+          credits_charged: 0,
+          created_at: (/* @__PURE__ */ new Date()).toISOString(),
+          failure_reason: "not_found"
+        });
+      } catch {
+      }
+      return {
+        request_index: index,
+        status: "failed",
+        credits_spent: 0,
+        credits_refunded: creditsNeeded,
+        error: err instanceof Error ? err.message : String(err)
+      };
+    }
+  };
+  let results;
+  if (strategy === "sequential") {
+    results = [];
+    let stopped = false;
+    for (let i = 0; i < requests.length; i++) {
+      if (stopped) {
+        results.push({
+          request_index: i,
+          status: "skipped",
+          credits_spent: 0,
+          credits_refunded: 0,
+          error: "Skipped due to earlier failure"
+        });
+        continue;
+      }
+      const result = await executeItem(requests[i], i);
+      results.push(result);
+      if (result.status === "failed") {
+        stopped = true;
+      }
+    }
+  } else {
+    const settled = await Promise.allSettled(
+      requests.map((item, i) => executeItem(item, i))
+    );
+    results = settled.map((outcome, i) => {
+      if (outcome.status === "fulfilled") {
+        return outcome.value;
+      }
+      return {
+        request_index: i,
+        status: "failed",
+        credits_spent: 0,
+        credits_refunded: 0,
+        error: outcome.reason instanceof Error ? outcome.reason.message : "Unknown error"
+      };
+    });
+  }
+  const total_credits_spent = results.reduce((acc, r) => acc + r.credits_spent, 0);
+  const total_credits_refunded = results.reduce((acc, r) => acc + r.credits_refunded, 0);
+  const success = results.every((r) => r.status === "success");
+  return { results, total_credits_spent, total_credits_refunded, success };
+}
+
+export {
+  deriveAgentId,
+  loadOrRepairIdentity,
+  ensureIdentity,
+  identityAuthPlugin,
+  createLedger,
+  syncCreditsFromRegistry,
+  executeCapabilityRequest,
+  executeCapabilityBatch
+};