agentbnb 2.2.0 → 3.1.0

package/dist/chunk-T7ZJPQHD.js

@@ -0,0 +1,372 @@
+import {
+  interpolateObject,
+  requestCapability,
+  scorePeers,
+  searchCards
+} from "./chunk-QVIGMCHA.js";
+
+// src/conductor/task-decomposer.ts
+import { randomUUID } from "crypto";
+var TEMPLATES = {
+  "video-production": {
+    keywords: ["video", "demo", "clip", "animation"],
+    steps: [
+      {
+        description: "Generate script from task description",
+        required_capability: "text_gen",
+        estimated_credits: 2,
+        depends_on_indices: []
+      },
+      {
+        description: "Generate voiceover from script",
+        required_capability: "tts",
+        estimated_credits: 3,
+        depends_on_indices: [0]
+      },
+      {
+        description: "Generate video visuals from script",
+        required_capability: "video_gen",
+        estimated_credits: 5,
+        depends_on_indices: [0]
+      },
+      {
+        description: "Composite voiceover and video into final output",
+        required_capability: "video_edit",
+        estimated_credits: 3,
+        depends_on_indices: [1, 2]
+      }
+    ]
+  },
+  "deep-analysis": {
+    keywords: ["analyze", "analysis", "research", "report", "evaluate"],
+    steps: [
+      {
+        description: "Research and gather relevant data",
+        required_capability: "web_search",
+        estimated_credits: 2,
+        depends_on_indices: []
+      },
+      {
+        description: "Analyze gathered data",
+        required_capability: "text_gen",
+        estimated_credits: 3,
+        depends_on_indices: [0]
+      },
+      {
+        description: "Summarize analysis findings",
+        required_capability: "text_gen",
+        estimated_credits: 2,
+        depends_on_indices: [1]
+      },
+      {
+        description: "Format into final report",
+        required_capability: "text_gen",
+        estimated_credits: 1,
+        depends_on_indices: [2]
+      }
+    ]
+  },
+  "content-generation": {
+    keywords: ["write", "blog", "article", "content", "post", "essay"],
+    steps: [
+      {
+        description: "Create content outline",
+        required_capability: "text_gen",
+        estimated_credits: 1,
+        depends_on_indices: []
+      },
+      {
+        description: "Draft content from outline",
+        required_capability: "text_gen",
+        estimated_credits: 3,
+        depends_on_indices: [0]
+      },
+      {
+        description: "Review and refine draft",
+        required_capability: "text_gen",
+        estimated_credits: 2,
+        depends_on_indices: [1]
+      },
+      {
+        description: "Finalize and polish content",
+        required_capability: "text_gen",
+        estimated_credits: 1,
+        depends_on_indices: [2]
+      }
+    ]
+  }
+};
+function decompose(task, _availableCapabilities) {
+  const lower = task.toLowerCase();
+  for (const template of Object.values(TEMPLATES)) {
+    const matched = template.keywords.some((kw) => lower.includes(kw));
+    if (!matched) continue;
+    const ids = template.steps.map(() => randomUUID());
+    return template.steps.map((step, i) => ({
+      id: ids[i],
+      description: step.description,
+      required_capability: step.required_capability,
+      params: {},
+      depends_on: step.depends_on_indices.map((idx) => ids[idx]),
+      estimated_credits: step.estimated_credits
+    }));
+  }
+  return [];
+}
+
+// src/conductor/capability-matcher.ts
+var MAX_ALTERNATIVES = 2;
+function matchSubTasks(opts) {
+  const { db, subtasks, conductorOwner } = opts;
+  return subtasks.map((subtask) => {
+    const cards = searchCards(db, subtask.required_capability, { online: true });
+    const candidates = [];
+    for (const card of cards) {
+      const cardAsV2 = card;
+      if (Array.isArray(cardAsV2.skills)) {
+        for (const skill of cardAsV2.skills) {
+          candidates.push({
+            card,
+            cost: skill.pricing.credits_per_call,
+            skillId: skill.id
+          });
+        }
+      } else {
+        candidates.push({
+          card,
+          cost: card.pricing.credits_per_call,
+          skillId: void 0
+        });
+      }
+    }
+    const scored = scorePeers(candidates, conductorOwner);
+    if (scored.length === 0) {
+      return {
+        subtask_id: subtask.id,
+        selected_agent: "",
+        selected_skill: "",
+        score: 0,
+        credits: 0,
+        alternatives: []
+      };
+    }
+    const top = scored[0];
+    const alternatives = scored.slice(1, 1 + MAX_ALTERNATIVES).map((s) => ({
+      agent: s.card.owner,
+      skill: s.skillId ?? "",
+      score: s.rawScore,
+      credits: s.cost
+    }));
+    return {
+      subtask_id: subtask.id,
+      selected_agent: top.card.owner,
+      selected_skill: top.skillId ?? "",
+      score: top.rawScore,
+      credits: top.cost,
+      alternatives
+    };
+  });
+}
+
+// src/conductor/budget-controller.ts
+var ORCHESTRATION_FEE = 5;
+var BudgetController = class {
+  /**
+   * Creates a new BudgetController.
+   *
+   * @param budgetManager - Underlying BudgetManager for reserve floor enforcement.
+   * @param maxBudget - Hard ceiling for the orchestration run.
+   */
+  constructor(budgetManager, maxBudget) {
+    this.budgetManager = budgetManager;
+    this.maxBudget = maxBudget;
+  }
+  /**
+   * Pre-calculates the total budget for an orchestration run.
+   *
+   * Sums all matched sub-task credits, adds the orchestration fee,
+   * and determines whether approval is required (estimated > max).
+   *
+   * @param matches - MatchResult[] from the CapabilityMatcher.
+   * @returns An ExecutionBudget with cost breakdown and approval status.
+   */
+  calculateBudget(matches) {
+    const perTaskSpending = /* @__PURE__ */ new Map();
+    let subTotal = 0;
+    for (const match of matches) {
+      perTaskSpending.set(match.subtask_id, match.credits);
+      subTotal += match.credits;
+    }
+    const estimatedTotal = subTotal + ORCHESTRATION_FEE;
+    return {
+      estimated_total: estimatedTotal,
+      max_budget: this.maxBudget,
+      orchestration_fee: ORCHESTRATION_FEE,
+      per_task_spending: perTaskSpending,
+      requires_approval: estimatedTotal > this.maxBudget
+    };
+  }
+  /**
+   * Checks whether orchestration can proceed without explicit approval.
+   *
+   * Returns true only when:
+   * 1. The budget does NOT require approval (estimated_total <= max_budget)
+   * 2. The BudgetManager confirms sufficient credits (respecting reserve floor)
+   *
+   * @param budget - ExecutionBudget from calculateBudget().
+   * @returns true if execution can proceed autonomously.
+   */
+  canExecute(budget) {
+    if (budget.requires_approval) return false;
+    return this.budgetManager.canSpend(budget.estimated_total);
+  }
+  /**
+   * Checks budget after explicit user/agent approval.
+   *
+   * Ignores the requires_approval flag — used when the caller has already
+   * obtained explicit approval for the over-budget orchestration.
+   * Still enforces the reserve floor via BudgetManager.canSpend().
+   *
+   * @param budget - ExecutionBudget from calculateBudget().
+   * @returns true if the agent has sufficient credits (reserve floor check only).
+   */
+  approveAndCheck(budget) {
+    return this.budgetManager.canSpend(budget.estimated_total);
+  }
+};
+
+// src/conductor/pipeline-orchestrator.ts
+function computeWaves(subtasks) {
+  const waves = [];
+  const completed = /* @__PURE__ */ new Set();
+  const remaining = new Map(subtasks.map((s) => [s.id, s]));
+  while (remaining.size > 0) {
+    const wave = [];
+    for (const [id, task] of remaining) {
+      const depsResolved = task.depends_on.every((dep) => completed.has(dep));
+      if (depsResolved) {
+        wave.push(id);
+      }
+    }
+    if (wave.length === 0) {
+      break;
+    }
+    for (const id of wave) {
+      remaining.delete(id);
+      completed.add(id);
+    }
+    waves.push(wave);
+  }
+  return waves;
+}
+async function orchestrate(opts) {
+  const { subtasks, matches, gatewayToken, resolveAgentUrl, timeoutMs = 3e4, maxBudget } = opts;
+  const startTime = Date.now();
+  if (subtasks.length === 0) {
+    return {
+      success: true,
+      results: /* @__PURE__ */ new Map(),
+      total_credits: 0,
+      latency_ms: Date.now() - startTime
+    };
+  }
+  const results = /* @__PURE__ */ new Map();
+  const errors = [];
+  let totalCredits = 0;
+  const waves = computeWaves(subtasks);
+  const subtaskMap = new Map(subtasks.map((s) => [s.id, s]));
+  for (const wave of waves) {
+    if (maxBudget !== void 0 && totalCredits >= maxBudget) {
+      errors.push(`Budget exceeded: spent ${totalCredits} cr, max ${maxBudget} cr`);
+      break;
+    }
+    const executableIds = [];
+    for (const taskId of wave) {
+      const m = matches.get(taskId);
+      if (maxBudget !== void 0 && m && totalCredits + m.credits > maxBudget) {
+        errors.push(`Skipping task ${taskId}: would exceed budget (${totalCredits} + ${m.credits} > ${maxBudget})`);
+        continue;
+      }
+      executableIds.push(taskId);
+    }
+    const waveResults = await Promise.allSettled(
+      executableIds.map(async (taskId) => {
+        const subtask = subtaskMap.get(taskId);
+        const m = matches.get(taskId);
+        if (!m) {
+          throw new Error(`No match found for subtask ${taskId}`);
+        }
+        const stepsContext = {};
+        for (const [id, val] of results) {
+          stepsContext[id] = val;
+        }
+        const interpContext = { steps: stepsContext, prev: void 0 };
+        if (subtask.depends_on.length > 0) {
+          const lastDep = subtask.depends_on[subtask.depends_on.length - 1];
+          interpContext.prev = results.get(lastDep);
+        }
+        const interpolatedParams = interpolateObject(
+          subtask.params,
+          interpContext
+        );
+        const primary = resolveAgentUrl(m.selected_agent);
+        try {
+          const res = await requestCapability({
+            gatewayUrl: primary.url,
+            token: gatewayToken,
+            cardId: primary.cardId,
+            params: interpolatedParams,
+            timeoutMs
+          });
+          return { taskId, result: res, credits: m.credits };
+        } catch (primaryErr) {
+          if (m.alternatives.length > 0) {
+            const alt = m.alternatives[0];
+            const altAgent = resolveAgentUrl(alt.agent);
+            try {
+              const altRes = await requestCapability({
+                gatewayUrl: altAgent.url,
+                token: gatewayToken,
+                cardId: altAgent.cardId,
+                params: interpolatedParams,
+                timeoutMs
+              });
+              return { taskId, result: altRes, credits: alt.credits };
+            } catch (altErr) {
+              throw new Error(
+                `Task ${taskId}: primary (${m.selected_agent}) failed: ${primaryErr instanceof Error ? primaryErr.message : String(primaryErr)}; alternative (${alt.agent}) failed: ${altErr instanceof Error ? altErr.message : String(altErr)}`
+              );
+            }
+          }
+          throw new Error(
+            `Task ${taskId}: ${primaryErr instanceof Error ? primaryErr.message : String(primaryErr)}`
+          );
+        }
+      })
+    );
+    for (const settlement of waveResults) {
+      if (settlement.status === "fulfilled") {
+        const { taskId, result, credits } = settlement.value;
+        results.set(taskId, result);
+        totalCredits += credits;
+      } else {
+        errors.push(settlement.reason instanceof Error ? settlement.reason.message : String(settlement.reason));
+      }
+    }
+  }
+  return {
+    success: errors.length === 0,
+    results,
+    total_credits: totalCredits,
+    latency_ms: Date.now() - startTime,
+    errors: errors.length > 0 ? errors : void 0
+  };
+}
+
+export {
+  decompose,
+  matchSubTasks,
+  ORCHESTRATION_FEE,
+  BudgetController,
+  orchestrate
+};

package/dist/chunk-TQMI73LL.js

@@ -0,0 +1,125 @@
+// src/types/index.ts
+import { z } from "zod";
+var IOSchemaSchema = z.object({
+  name: z.string(),
+  type: z.enum(["text", "json", "file", "audio", "image", "video", "stream"]),
+  description: z.string().optional(),
+  required: z.boolean().default(true),
+  schema: z.record(z.unknown()).optional()
+  // JSON Schema
+});
+var PoweredBySchema = z.object({
+  provider: z.string().min(1),
+  model: z.string().optional(),
+  tier: z.string().optional()
+});
+var CapabilityCardSchema = z.object({
+  spec_version: z.literal("1.0").default("1.0"),
+  id: z.string().uuid(),
+  owner: z.string().min(1),
+  name: z.string().min(1).max(100),
+  description: z.string().max(500),
+  level: z.union([z.literal(1), z.literal(2), z.literal(3)]),
+  inputs: z.array(IOSchemaSchema),
+  outputs: z.array(IOSchemaSchema),
+  pricing: z.object({
+    credits_per_call: z.number().nonnegative(),
+    credits_per_minute: z.number().nonnegative().optional(),
+    /** Number of free monthly calls. Shown as a "N free/mo" badge in the Hub. */
+    free_tier: z.number().nonnegative().optional()
+  }),
+  availability: z.object({
+    online: z.boolean(),
+    schedule: z.string().optional()
+    // cron expression
+  }),
+  powered_by: z.array(PoweredBySchema).optional(),
+  /**
+   * Private per-card metadata. Stripped from all API and CLI responses —
+   * never transmitted beyond the local store.
+   */
+  _internal: z.record(z.unknown()).optional(),
+  metadata: z.object({
+    apis_used: z.array(z.string()).optional(),
+    avg_latency_ms: z.number().nonnegative().optional(),
+    success_rate: z.number().min(0).max(1).optional(),
+    tags: z.array(z.string()).optional()
+  }).optional(),
+  created_at: z.string().datetime().optional(),
+  updated_at: z.string().datetime().optional()
+});
+var SkillSchema = z.object({
+  /** Stable skill identifier, e.g. 'tts-elevenlabs'. Used for gateway routing and idle tracking. */
+  id: z.string().min(1),
+  name: z.string().min(1).max(100),
+  description: z.string().max(500),
+  level: z.union([z.literal(1), z.literal(2), z.literal(3)]),
+  /** Optional grouping category, e.g. 'tts' | 'video_gen' | 'code_review'. */
+  category: z.string().optional(),
+  inputs: z.array(IOSchemaSchema),
+  outputs: z.array(IOSchemaSchema),
+  pricing: z.object({
+    credits_per_call: z.number().nonnegative(),
+    credits_per_minute: z.number().nonnegative().optional(),
+    free_tier: z.number().nonnegative().optional()
+  }),
+  /** Per-skill online flag — overrides card-level availability for this skill. */
+  availability: z.object({ online: z.boolean() }).optional(),
+  powered_by: z.array(PoweredBySchema).optional(),
+  metadata: z.object({
+    apis_used: z.array(z.string()).optional(),
+    avg_latency_ms: z.number().nonnegative().optional(),
+    success_rate: z.number().min(0).max(1).optional(),
+    tags: z.array(z.string()).optional(),
+    capacity: z.object({
+      calls_per_hour: z.number().positive().default(60)
+    }).optional()
+  }).optional(),
+  /**
+   * Private per-skill metadata. Stripped from all API and CLI responses —
+   * never transmitted beyond the local store.
+   */
+  _internal: z.record(z.unknown()).optional()
+});
+var CapabilityCardV2Schema = z.object({
+  spec_version: z.literal("2.0"),
+  id: z.string().uuid(),
+  owner: z.string().min(1),
+  /** Agent display name — was 'name' in v1.0. */
+  agent_name: z.string().min(1).max(100),
+  /** At least one skill is required. */
+  skills: z.array(SkillSchema).min(1),
+  availability: z.object({
+    online: z.boolean(),
+    schedule: z.string().optional()
+  }),
+  /** Optional deployment environment metadata. */
+  environment: z.object({
+    runtime: z.string(),
+    region: z.string().optional()
+  }).optional(),
+  /**
+   * Private per-card metadata. Stripped from all API and CLI responses —
+   * never transmitted beyond the local store.
+   */
+  _internal: z.record(z.unknown()).optional(),
+  created_at: z.string().datetime().optional(),
+  updated_at: z.string().datetime().optional()
+});
+var AnyCardSchema = z.discriminatedUnion("spec_version", [
+  CapabilityCardSchema,
+  CapabilityCardV2Schema
+]);
+var AgentBnBError = class extends Error {
+  constructor(message, code) {
+    super(message);
+    this.code = code;
+    this.name = "AgentBnBError";
+  }
+};
+
+export {
+  CapabilityCardSchema,
+  CapabilityCardV2Schema,
+  AgentBnBError
+};

package/dist/chunk-ZJCIBK6O.js

@@ -0,0 +1,192 @@
+import {
+  AgentBnBError
+} from "./chunk-TQMI73LL.js";
+
+// src/credit/escrow.ts
+import { randomUUID } from "crypto";
+function holdEscrow(db, owner, amount, cardId) {
+  const escrowId = randomUUID();
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const hold = db.transaction(() => {
+    const row = db.prepare("SELECT balance FROM credit_balances WHERE owner = ?").get(owner);
+    if (!row || row.balance < amount) {
+      throw new AgentBnBError("Insufficient credits", "INSUFFICIENT_CREDITS");
+    }
+    db.prepare(
+      "UPDATE credit_balances SET balance = balance - ?, updated_at = ? WHERE owner = ? AND balance >= ?"
+    ).run(amount, now, owner, amount);
+    db.prepare(
+      "INSERT INTO credit_escrow (id, owner, amount, card_id, status, created_at) VALUES (?, ?, ?, ?, ?, ?)"
+    ).run(escrowId, owner, amount, cardId, "held", now);
+    db.prepare(
+      "INSERT INTO credit_transactions (id, owner, amount, reason, reference_id, created_at) VALUES (?, ?, ?, ?, ?, ?)"
+    ).run(randomUUID(), owner, -amount, "escrow_hold", escrowId, now);
+  });
+  hold();
+  return escrowId;
+}
+function settleEscrow(db, escrowId, recipientOwner) {
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const settle = db.transaction(() => {
+    const escrow = db.prepare("SELECT id, owner, amount, status FROM credit_escrow WHERE id = ?").get(escrowId);
+    if (!escrow) {
+      throw new AgentBnBError(`Escrow not found: ${escrowId}`, "ESCROW_NOT_FOUND");
+    }
+    if (escrow.status !== "held") {
+      throw new AgentBnBError(
+        `Escrow ${escrowId} is already ${escrow.status}`,
+        "ESCROW_ALREADY_SETTLED"
+      );
+    }
+    db.prepare(
+      "INSERT OR IGNORE INTO credit_balances (owner, balance, updated_at) VALUES (?, 0, ?)"
+    ).run(recipientOwner, now);
+    db.prepare(
+      "UPDATE credit_balances SET balance = balance + ?, updated_at = ? WHERE owner = ?"
+    ).run(escrow.amount, now, recipientOwner);
+    db.prepare(
+      "UPDATE credit_escrow SET status = ?, settled_at = ? WHERE id = ?"
+    ).run("settled", now, escrowId);
+    db.prepare(
+      "INSERT INTO credit_transactions (id, owner, amount, reason, reference_id, created_at) VALUES (?, ?, ?, ?, ?, ?)"
+    ).run(randomUUID(), recipientOwner, escrow.amount, "settlement", escrowId, now);
+  });
+  settle();
+}
+function releaseEscrow(db, escrowId) {
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const release = db.transaction(() => {
+    const escrow = db.prepare("SELECT id, owner, amount, status FROM credit_escrow WHERE id = ?").get(escrowId);
+    if (!escrow) {
+      throw new AgentBnBError(`Escrow not found: ${escrowId}`, "ESCROW_NOT_FOUND");
+    }
+    if (escrow.status !== "held") {
+      throw new AgentBnBError(
+        `Escrow ${escrowId} is already ${escrow.status}`,
+        "ESCROW_ALREADY_SETTLED"
+      );
+    }
+    db.prepare(
+      "UPDATE credit_balances SET balance = balance + ?, updated_at = ? WHERE owner = ?"
+    ).run(escrow.amount, now, escrow.owner);
+    db.prepare(
+      "UPDATE credit_escrow SET status = ?, settled_at = ? WHERE id = ?"
+    ).run("released", now, escrowId);
+    db.prepare(
+      "INSERT INTO credit_transactions (id, owner, amount, reason, reference_id, created_at) VALUES (?, ?, ?, ?, ?, ?)"
+    ).run(randomUUID(), escrow.owner, escrow.amount, "refund", escrowId, now);
+  });
+  release();
+}
+function confirmEscrowDebit(db, escrowId) {
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const confirm = db.transaction(() => {
+    const escrow = db.prepare("SELECT id, owner, amount, status FROM credit_escrow WHERE id = ?").get(escrowId);
+    if (!escrow) {
+      throw new AgentBnBError(`Escrow not found: ${escrowId}`, "ESCROW_NOT_FOUND");
+    }
+    if (escrow.status !== "held") {
+      throw new AgentBnBError(
+        `Escrow ${escrowId} is already ${escrow.status}`,
+        "ESCROW_ALREADY_SETTLED"
+      );
+    }
+    db.prepare(
+      "UPDATE credit_escrow SET status = ?, settled_at = ? WHERE id = ?"
+    ).run("settled", now, escrowId);
+    db.prepare(
+      "INSERT INTO credit_transactions (id, owner, amount, reason, reference_id, created_at) VALUES (?, ?, ?, ?, ?, ?)"
+    ).run(randomUUID(), escrow.owner, 0, "remote_settlement_confirmed", escrowId, now);
+  });
+  confirm();
+}
+
+// src/credit/ledger.ts
+import Database from "better-sqlite3";
+import { randomUUID as randomUUID2 } from "crypto";
+var CREDIT_SCHEMA = `
+  CREATE TABLE IF NOT EXISTS credit_balances (
+    owner TEXT PRIMARY KEY,
+    balance INTEGER NOT NULL DEFAULT 0,
+    updated_at TEXT NOT NULL
+  );
+
+  CREATE TABLE IF NOT EXISTS credit_transactions (
+    id TEXT PRIMARY KEY,
+    owner TEXT NOT NULL,
+    amount INTEGER NOT NULL,
+    reason TEXT NOT NULL,
+    reference_id TEXT,
+    created_at TEXT NOT NULL
+  );
+
+  CREATE TABLE IF NOT EXISTS credit_escrow (
+    id TEXT PRIMARY KEY,
+    owner TEXT NOT NULL,
+    amount INTEGER NOT NULL,
+    card_id TEXT NOT NULL,
+    status TEXT NOT NULL DEFAULT 'held',
+    created_at TEXT NOT NULL,
+    settled_at TEXT
+  );
+
+  CREATE INDEX IF NOT EXISTS idx_transactions_owner ON credit_transactions(owner, created_at);
+  CREATE INDEX IF NOT EXISTS idx_escrow_owner ON credit_escrow(owner);
+`;
+function openCreditDb(path = ":memory:") {
+  const db = new Database(path);
+  db.pragma("journal_mode = WAL");
+  db.pragma("foreign_keys = ON");
+  db.exec(CREDIT_SCHEMA);
+  return db;
+}
+function bootstrapAgent(db, owner, amount = 100) {
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  db.transaction(() => {
+    const result = db.prepare("INSERT OR IGNORE INTO credit_balances (owner, balance, updated_at) VALUES (?, ?, ?)").run(owner, amount, now);
+    if (result.changes > 0) {
+      db.prepare(
+        "INSERT INTO credit_transactions (id, owner, amount, reason, reference_id, created_at) VALUES (?, ?, ?, ?, ?, ?)"
+      ).run(randomUUID2(), owner, amount, "bootstrap", null, now);
+    }
+  })();
+}
+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) {
+  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);
+}
+function recordEarning(db, owner, amount, _cardId, receiptNonce) {
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  db.transaction(() => {
+    const existing = db.prepare(
+      "SELECT id FROM credit_transactions WHERE reference_id = ? AND reason = 'remote_earning'"
+    ).get(receiptNonce);
+    if (existing) return;
+    db.prepare(
+      "INSERT OR IGNORE INTO credit_balances (owner, balance, updated_at) VALUES (?, 0, ?)"
+    ).run(owner, now);
+    db.prepare(
+      "UPDATE credit_balances SET balance = balance + ?, updated_at = ? WHERE owner = ?"
+    ).run(amount, now, owner);
+    db.prepare(
+      "INSERT INTO credit_transactions (id, owner, amount, reason, reference_id, created_at) VALUES (?, ?, ?, ?, ?, ?)"
+    ).run(randomUUID2(), owner, amount, "remote_earning", receiptNonce, now);
+  })();
+}
+
+export {
+  holdEscrow,
+  settleEscrow,
+  releaseEscrow,
+  confirmEscrowDebit,
+  openCreditDb,
+  bootstrapAgent,
+  getBalance,
+  getTransactions,
+  recordEarning
+};