@owney/sdk 0.7.16 → 0.7.17-beta.1

package/dist/index.js

@@ -1,3 +1,165 @@
+// src/errors.ts
+var OwneyError = class extends Error {
+  code;
+  details;
+  agentId;
+  constructor(code, message, details, agentId) {
+    const prefix = agentId ? `[${code}][agent:${agentId}]` : `[${code}]`;
+    super(`${prefix} ${message}`);
+    this.name = "OwneyError";
+    this.code = code;
+    this.details = details;
+    this.agentId = agentId;
+  }
+};
+var AgentNotFoundError = class extends OwneyError {
+  constructor(agentId, available) {
+    super(
+      "AGENT_NOT_FOUND",
+      `Unknown agent "${agentId}". Available agents: ${available.join(", ")}`,
+      { agentId, available },
+      agentId
+    );
+    this.name = "AgentNotFoundError";
+  }
+};
+var NotConnectedError = class extends OwneyError {
+  constructor() {
+    super("NOT_CONNECTED", "Not connected. Call sdk.connect(provider) first.");
+    this.name = "NotConnectedError";
+  }
+};
+var AgentChainIncompatibleError = class extends OwneyError {
+  incompatibleAgents;
+  connectedChainId;
+  constructor(incompatibleAgents, connectedChainId) {
+    const details = incompatibleAgents.map(
+      ({ agentId, supportedChainIds }) => `"${agentId}" supports chains [${supportedChainIds.join(", ")}]`
+    ).join("; ");
+    super(
+      "AGENT_CHAIN_INCOMPATIBLE",
+      `Chain ${connectedChainId} is not supported by the following agents: ${details}`,
+      { incompatibleAgents, connectedChainId }
+    );
+    this.name = "AgentChainIncompatibleError";
+    this.incompatibleAgents = incompatibleAgents;
+    this.connectedChainId = connectedChainId;
+  }
+};
+
+// src/lib/rate-limit.ts
+function rateLimitDelay(error, now = Date.now()) {
+  const seen = /* @__PURE__ */ new Set();
+  let limited = false;
+  let delay = 0;
+  function visit(value, depth = 0) {
+    if (depth > 6 || value == null) return;
+    if (typeof value === "string") {
+      if (/rate[ _-]?limit|too many requests|HTTP_429|\b429\b/i.test(value))
+        limited = true;
+      return;
+    }
+    if (typeof value !== "object" || seen.has(value)) return;
+    seen.add(value);
+    const record = value;
+    if ([record.status, record.statusCode, record.code].some(
+      (code) => String(code) === "429"
+    )) {
+      limited = true;
+    }
+    for (const key2 of ["retryAfterSeconds", "retryAfter"]) {
+      const seconds = Number(record[key2]);
+      if (Number.isFinite(seconds) && seconds > 0)
+        delay = Math.max(delay, seconds * 1e3);
+    }
+    const retryAt = Number(record.retryAt);
+    if (Number.isFinite(retryAt) && retryAt > now)
+      delay = Math.max(delay, retryAt - now);
+    const headers = record.headers;
+    const header = typeof headers?.get === "function" ? headers.get("Retry-After") : headers?.["retry-after"] ?? headers?.["Retry-After"];
+    if (typeof header === "string" || typeof header === "number") {
+      const seconds = Number(header);
+      const ms = Number.isFinite(seconds) ? seconds * 1e3 : Date.parse(String(header)) - now;
+      if (Number.isFinite(ms) && ms > 0) delay = Math.max(delay, ms);
+    }
+    for (const key2 of [
+      "message",
+      "code",
+      "cause",
+      "details",
+      "response",
+      "data",
+      "fields"
+    ]) {
+      visit(record[key2], depth + 1);
+    }
+    for (const key2 of ["agentErrors", "failures"]) {
+      const entries = record[key2];
+      if (entries && typeof entries === "object") {
+        for (const entry of Object.values(entries)) visit(entry, depth + 1);
+      }
+    }
+  }
+  visit(error);
+  return limited ? delay : void 0;
+}
+
+// src/lib/agent-reads.ts
+var AgentReads = class {
+  inFlight = /* @__PURE__ */ new Map();
+  cooldowns = /* @__PURE__ */ new Map();
+  // A reconnect must not reuse work started by the previous connection.
+  clearInFlight() {
+    this.inFlight.clear();
+  }
+  limited(agentId, until) {
+    return new OwneyError(
+      "AGENT_RATE_LIMITED",
+      "Too many requests. Please wait before trying again.",
+      {
+        statusCode: 429,
+        retryAt: until,
+        retryAfterSeconds: Math.max(0, Math.ceil((until - Date.now()) / 1e3))
+      },
+      agentId
+    );
+  }
+  run(agentId, key2, fetch2) {
+    const cooldown = this.cooldowns.get(agentId);
+    if (cooldown && cooldown.until > Date.now()) {
+      return Promise.reject(this.limited(agentId, cooldown.until));
+    }
+    const requestKey = JSON.stringify([agentId, key2]);
+    const existing = this.inFlight.get(requestKey);
+    if (existing) return existing;
+    const promise = Promise.resolve().then(fetch2).then(
+      (value) => {
+        if (this.cooldowns.get(agentId) === cooldown)
+          this.cooldowns.delete(agentId);
+        return value;
+      },
+      (error) => {
+        const requestedDelay = rateLimitDelay(error);
+        if (requestedDelay === void 0) throw error;
+        const previous = this.cooldowns.get(agentId);
+        const failures = previous && previous.until > Date.now() ? previous.failures : Math.min((previous?.failures ?? 0) + 1, 5);
+        const delay = Math.max(
+          requestedDelay,
+          Math.min(3e4 * 2 ** (failures - 1), 3e5)
+        );
+        const until = Math.max(previous?.until ?? 0, Date.now() + delay);
+        this.cooldowns.set(agentId, { until, failures });
+        throw this.limited(agentId, until);
+      }
+    ).finally(() => {
+      if (this.inFlight.get(requestKey) === promise)
+        this.inFlight.delete(requestKey);
+    });
+    this.inFlight.set(requestKey, promise);
+    return promise;
+  }
+};
+
 // src/agents/zyfai/zyfai.agent.ts
 import { SMART_SESSIONS_VALIDATOR, ZyfaiSDK } from "@zyfai/sdk";
 import { createPublicClient, http, parseAbi } from "viem";
@@ -67,55 +229,6 @@ function debugLog(scope, message, data) {
   }
 }
 
-// src/errors.ts
-var OwneyError = class extends Error {
-  code;
-  details;
-  agentId;
-  constructor(code, message, details, agentId) {
-    const prefix = agentId ? `[${code}][agent:${agentId}]` : `[${code}]`;
-    super(`${prefix} ${message}`);
-    this.name = "OwneyError";
-    this.code = code;
-    this.details = details;
-    this.agentId = agentId;
-  }
-};
-var AgentNotFoundError = class extends OwneyError {
-  constructor(agentId, available) {
-    super(
-      "AGENT_NOT_FOUND",
-      `Unknown agent "${agentId}". Available agents: ${available.join(", ")}`,
-      { agentId, available },
-      agentId
-    );
-    this.name = "AgentNotFoundError";
-  }
-};
-var NotConnectedError = class extends OwneyError {
-  constructor() {
-    super("NOT_CONNECTED", "Not connected. Call sdk.connect(provider) first.");
-    this.name = "NotConnectedError";
-  }
-};
-var AgentChainIncompatibleError = class extends OwneyError {
-  incompatibleAgents;
-  connectedChainId;
-  constructor(incompatibleAgents, connectedChainId) {
-    const details = incompatibleAgents.map(
-      ({ agentId, supportedChainIds }) => `"${agentId}" supports chains [${supportedChainIds.join(", ")}]`
-    ).join("; ");
-    super(
-      "AGENT_CHAIN_INCOMPATIBLE",
-      `Chain ${connectedChainId} is not supported by the following agents: ${details}`,
-      { incompatibleAgents, connectedChainId }
-    );
-    this.name = "AgentChainIncompatibleError";
-    this.incompatibleAgents = incompatibleAgents;
-    this.connectedChainId = connectedChainId;
-  }
-};
-
 // src/lib/utils.ts
 var isValidChainId = (chainId) => {
   if (!SUPPORTED_CHAIN_IDS.includes(chainId)) {
@@ -919,7 +1032,10 @@ var ZyfaiAgent = class _ZyfaiAgent {
   // successful decode is cached forever; failures are NOT cached so a transient
   // RPC error retries on the next fetch.
   withdrawAmountCache = /* @__PURE__ */ new Map();
-  earningsRefreshInFlight = null;
+  earningsReads = /* @__PURE__ */ new Map();
+  earningsRefreshes = /* @__PURE__ */ new Map();
+  earningsSnapshot = null;
+  earningsGeneration = 0;
   constructor(apiKey, rpcUrls, referralSource) {
     this.rpcUrls = rpcUrls ?? DEFAULT_ZYFAI_RPC_URLS;
     this.sdk = new ZyfaiSDK({
@@ -1164,6 +1280,10 @@ var ZyfaiAgent = class _ZyfaiAgent {
   }
   // --- IAgent: Connection lifecycle ---
   async disconnect() {
+    this.earningsGeneration++;
+    this.earningsReads.clear();
+    this.earningsRefreshes.clear();
+    this.earningsSnapshot = null;
     if (this.connectedAddress && this.connectedChainId !== null) {
       clearSession(this.connectedAddress, this.connectedChainId);
     }
@@ -1712,26 +1832,59 @@ var ZyfaiAgent = class _ZyfaiAgent {
     const raw = await this.sdk.getPortfolio(this.getAddress());
     return mapBalances(raw, validChainId, smartWallet);
   }
+  earningsKey(state, chainId, smartWallet) {
+    return JSON.stringify([
+      state.walletAddress?.toLowerCase(),
+      chainId,
+      smartWallet.toLowerCase()
+    ]);
+  }
+  readEarnings(key2, smartWallet) {
+    const existing = this.earningsReads.get(key2);
+    if (existing) return existing;
+    const generation = this.earningsGeneration;
+    const pending = Promise.resolve().then(() => this.sdk.getOnchainEarnings(smartWallet)).then((raw) => {
+      if (generation === this.earningsGeneration) {
+        this.earningsSnapshot = { key: key2, raw, at: Date.now() };
+      }
+      return raw;
+    }).finally(() => {
+      if (this.earningsReads.get(key2) === pending)
+        this.earningsReads.delete(key2);
+    });
+    this.earningsReads.set(key2, pending);
+    return pending;
+  }
   async getEarnings(state, chainId) {
     const { smartWallet } = await this.resolveSmartWallet(state, chainId);
-    const raw = await this.sdk.getOnchainEarnings(smartWallet);
+    const raw = await this.readEarnings(
+      this.earningsKey(state, chainId, smartWallet),
+      smartWallet
+    );
     return mapEarnings(raw, smartWallet);
   }
   async refreshEarnings(state, chainId) {
-    if (this.earningsRefreshInFlight) return this.earningsRefreshInFlight;
-    this.earningsRefreshInFlight = (async () => {
-      const { smartWallet } = await this.resolveSmartWallet(state, chainId);
-      const current = await this.sdk.getOnchainEarnings(smartWallet);
+    const { smartWallet } = await this.resolveSmartWallet(state, chainId);
+    const key2 = this.earningsKey(state, chainId, smartWallet);
+    const existing = this.earningsRefreshes.get(key2);
+    if (existing) return existing;
+    const generation = this.earningsGeneration;
+    const pending = (async () => {
+      const recent = this.earningsSnapshot;
+      const current = recent?.key === key2 && Date.now() - recent.at < 5e3 ? recent.raw : await this.readEarnings(key2, smartWallet);
       const lastCheck = current.data.lastCheckTimestamp ? Date.parse(current.data.lastCheckTimestamp) : Number.NaN;
       const isFresh = Number.isFinite(lastCheck) && Date.now() - lastCheck < EARNINGS_REFRESH_COOLDOWN_MS;
       const earnings = isFresh ? current : await this.sdk.calculateOnchainEarnings(smartWallet);
+      if (!isFresh && generation === this.earningsGeneration) {
+        this.earningsSnapshot = { key: key2, raw: earnings, at: Date.now() };
+      }
       return mapEarnings(earnings, smartWallet);
-    })();
-    try {
-      return await this.earningsRefreshInFlight;
-    } finally {
-      this.earningsRefreshInFlight = null;
-    }
+    })().finally(() => {
+      if (this.earningsRefreshes.get(key2) === pending)
+        this.earningsRefreshes.delete(key2);
+    });
+    this.earningsRefreshes.set(key2, pending);
+    return pending;
   }
   async getAccountApy(state, chainId, days, tokenSymbol) {
     const { smartWallet } = await this.resolveSmartWallet(state, chainId);
@@ -2653,6 +2806,17 @@ var OwneySDK = class {
   cachedWethSponsoredCallback = null;
   paymasterServiceUrl;
   cachedSponsoredCallsCallbacks = /* @__PURE__ */ new Map();
+  agentReads = new AgentReads();
+  activationChecks = /* @__PURE__ */ new Map();
+  readAgent(agent, method, fetch2, params = null) {
+    const key2 = JSON.stringify([
+      this.state?.walletAddress.toLowerCase() ?? null,
+      this.state?.chainId ?? null,
+      method,
+      params
+    ]);
+    return this.agentReads.run(agent.id, key2, fetch2);
+  }
   initializingAgentsPromise = null;
   constructor(config) {
     this.apiKey = config.apiKey;
@@ -2679,6 +2843,8 @@ var OwneySDK = class {
         "No accounts found. Ensure the wallet is unlocked and connected."
       );
     }
+    this.agentReads.clearInFlight();
+    this.activationChecks.clear();
     this.state = { provider, walletAddress, chainId: null };
     this.cachedSponsoredCallback = null;
     this.cachedWethSponsoredCallback = null;
@@ -2694,6 +2860,8 @@ var OwneySDK = class {
     }
     this.activeAgents.clear();
     this.disabledAgents.clear();
+    this.agentReads.clearInFlight();
+    this.activationChecks.clear();
     this.state = null;
     this.cachedSponsoredCallback = null;
     this.cachedWethSponsoredCallback = null;
@@ -2924,6 +3092,37 @@ var OwneySDK = class {
     }
     return null;
   }
+  /**
+   * Discover the agents actually returned by routing for this organization.
+   * Consumers should use this instead of hardcoding a global agent roster.
+   */
+  async getAvailableAgents(options = {}) {
+    await this.ensureAgentsInitialized();
+    const { chainId, asset, includeDisabled = false } = options;
+    const available = [];
+    for (const [id, agent] of this.agents) {
+      const isEnabled = !this.isAgentDisabled(id);
+      if (!includeDisabled && !isEnabled) continue;
+      if (chainId !== void 0 && !agent.supportedChainIds.includes(chainId)) {
+        continue;
+      }
+      if (asset !== void 0) {
+        const supportsAsset = agent.supportedAssets.some(
+          (entry) => (chainId === void 0 || entry.chainId === chainId) && entry.assets.some((candidate) => candidate.symbol === asset)
+        );
+        if (!supportsAsset) {
+          continue;
+        }
+      }
+      available.push({
+        id,
+        isEnabled,
+        supportedChainIds: agent.supportedChainIds,
+        supportedAssets: agent.supportedAssets
+      });
+    }
+    return available;
+  }
   // --- Account lifecycle ---
   /**
    * Activate the user's smart wallet for the specified agents, or all chain-compatible agents if omitted.
@@ -2971,9 +3170,7 @@ var OwneySDK = class {
         this.activeAgents.add(id);
       }
       state.chainId = chainId;
-      this.activateAgentsInTurn(agents, state, chainId).catch((error) => {
-        console.error("activateAgent background init failed:", error);
-      });
+      await this.activateAgentsInTurn(agents, state, chainId);
       return;
     }
     const compatible = [...this.agents.values()].filter(
@@ -2994,11 +3191,7 @@ var OwneySDK = class {
     const enabledCompatible = compatible.filter(
       (agent) => !this.isAgentDisabled(agent.id)
     );
-    this.activateAgentsInTurn(enabledCompatible, state, chainId).catch(
-      (error) => {
-        console.error("activateAgent background init failed:", error);
-      }
-    );
+    await this.activateAgentsInTurn(enabledCompatible, state, chainId);
   }
   /**
    * Activate agents ONE AT A TIME, each followed by its org policy.
@@ -3035,7 +3228,7 @@ var OwneySDK = class {
     if (firstError !== null) throw firstError;
   }
   /**
-   * Deposit funds into a specific agent, or split equally across all agents if agentId is omitted.
+   * Deposit into a specific agent, or distribute across all eligible agents.
    * Validates that the asset is supported and amount meets minimums for the target agent(s).
    * @param options - Deposit parameters
    * @param options.amount - Amount to deposit in smallest unit (e.g. "100000000" for 100 USDC)
@@ -3043,7 +3236,8 @@ var OwneySDK = class {
    * @param options.depositCallback - Callback that performs the token transfer and returns a tx hash.
    *   When agentId is omitted, this callback is invoked once per eligible agent with that agent's
    *   split amount and smart wallet address — expect multiple wallet prompts.
-   * @param options.agentId - Optional. Target agent. Omit to split equally across all agents.
+   * @param options.agentId - Optional explicit target. Otherwise split equally,
+   *   or fund remaining agents when a recovery deposit cannot meet every minimum.
    * @returns {OwneyDepositResult} for a single agent, or {OwneyMultiDepositResult} with per-agent results
    */
   async deposit(options) {
@@ -3081,7 +3275,7 @@ var OwneySDK = class {
     });
     const exemptFlags = await Promise.all(
       eligibleAgents.map(
-        (a) => this.hasExistingBalance(a, state, chainId, asset)
+        (a) => this.hasExistingBalance(a, state, chainId, asset, true)
       )
     );
     const exempt = new Set(
@@ -3095,23 +3289,67 @@ var OwneySDK = class {
       exempt
     );
     if (agentAmounts.length === 0) {
+      const agentsRequiringActivation = eligibleAgents.filter(
+        (agent) => !exempt.has(agent.id)
+      );
+      const perAgentMinimum = agentsRequiringActivation.reduce(
+        (highest, agent) => {
+          const minimum = this.getMinDepositAmount(agent, chainId, asset);
+          return minimum > highest ? minimum : highest;
+        },
+        0n
+      );
+      const minimumRequired = agentsRequiringActivation.length > 0 ? (perAgentMinimum > 0n ? perAgentMinimum : 1n) * BigInt(agentsRequiringActivation.length) : BigInt(eligibleAgents.length);
       throw new OwneyError(
         "DEPOSIT_AMOUNT_BELOW_MINIMUM",
-        `Amount "${amount}" cannot satisfy minimum deposit requirements for any eligible agent.`,
-        { amount }
+        `Amount "${amount}" cannot activate every eligible agent. The combined minimum is "${minimumRequired.toString()}" for ${asset}.`,
+        {
+          amount,
+          asset,
+          chainId,
+          minDepositAmount: minimumRequired.toString(),
+          perAgentDepositAmount: perAgentMinimum.toString(),
+          agentMinimums: agentsRequiringActivation.map((agent) => ({
+            agentId: agent.id,
+            minDepositAmount: this.getMinDepositAmount(
+              agent,
+              chainId,
+              asset
+            ).toString()
+          }))
+        }
       );
     }
     const agentResults = {};
-    for (const { agent, amount: agentAmount } of agentAmounts) {
-      agentResults[agent.id] = await this.depositWithFallback(
-        agent,
-        state,
-        chainId,
-        agentAmount,
-        asset,
-        effectiveCallback,
-        depositCallback
-      );
+    for (const [
+      index,
+      { agent, amount: agentAmount }
+    ] of agentAmounts.entries()) {
+      try {
+        agentResults[agent.id] = await this.depositWithFallback(
+          agent,
+          state,
+          chainId,
+          agentAmount,
+          asset,
+          effectiveCallback,
+          depositCallback
+        );
+      } catch (error) {
+        if (Object.keys(agentResults).length === 0) throw error;
+        throw new OwneyError(
+          "DEPOSIT_PARTIAL_FAILURE",
+          "Some deposits completed before another agent failed. Check activity and balances before depositing again; the failed transfer may still settle.",
+          {
+            agentResults,
+            failedAgentId: agent.id,
+            failedAmount: agentAmount,
+            unattemptedAgentIds: agentAmounts.slice(index + 1).map(({ agent: agent2 }) => agent2.id),
+            cause: error
+          },
+          agent.id
+        );
+      }
     }
     return { agentResults };
   }
@@ -3184,6 +3422,17 @@ var OwneySDK = class {
   }
   splitDepositAmount(totalAmount, agents, chainId, asset, exempt = /* @__PURE__ */ new Set()) {
     if (agents.length === 0) return [];
+    const agentsRequiringActivation = agents.filter(
+      (agent) => !exempt.has(agent.id)
+    );
+    if (agentsRequiringActivation.length === agents.length) {
+      const highestMinimum2 = agents.reduce((highest, agent) => {
+        const minimum = this.getMinDepositAmount(agent, chainId, asset);
+        return minimum > highest ? minimum : highest;
+      }, 0n);
+      const minimumRequired2 = (highestMinimum2 > 0n ? highestMinimum2 : 1n) * BigInt(agents.length);
+      if (totalAmount < minimumRequired2) return [];
+    }
     const perAgent = totalAmount / BigInt(agents.length);
     const remainder = totalAmount % BigInt(agents.length);
     const splits = agents.map((agent, i) => ({
@@ -3191,18 +3440,26 @@ var OwneySDK = class {
       amount: i === agents.length - 1 ? perAgent + remainder : perAgent
     }));
     const valid = splits.filter(
-      (s) => exempt.has(s.agent.id) || s.amount >= this.getMinDepositAmount(s.agent, chainId, asset)
+      (s) => s.amount > 0n && (exempt.has(s.agent.id) || s.amount >= this.getMinDepositAmount(s.agent, chainId, asset))
     );
     if (valid.length === agents.length) {
       return splits.map((s) => ({ agent: s.agent, amount: String(s.amount) }));
     }
-    return this.splitDepositAmount(
-      totalAmount,
-      valid.map((s) => s.agent),
-      chainId,
-      asset,
-      exempt
-    );
+    const targets = agentsRequiringActivation.length > 0 ? agentsRequiringActivation : agents;
+    const highestMinimum = targets.reduce((highest, agent) => {
+      const minimum = this.getMinDepositAmount(agent, chainId, asset);
+      return minimum > highest ? minimum : highest;
+    }, 0n);
+    const minimumRequired = (highestMinimum > 0n ? highestMinimum : 1n) * BigInt(targets.length);
+    if (totalAmount < minimumRequired) return [];
+    const targetShare = totalAmount / BigInt(targets.length);
+    const targetRemainder = totalAmount % BigInt(targets.length);
+    return targets.map((agent, index) => ({
+      agent,
+      amount: String(
+        targetShare + (index === targets.length - 1 ? targetRemainder : 0n)
+      )
+    }));
   }
   async validateMinDepositAmount(agent, state, chainId, asset, amount) {
     const minDepositAmount = this.getMinDepositAmount(agent, chainId, asset);
@@ -3227,15 +3484,29 @@ var OwneySDK = class {
    * per-agent minimum. Fails closed: any error reading balances returns
    * false, so the minimum is enforced as today.
    */
-  async hasExistingBalance(agent, state, chainId, asset) {
+  async hasExistingBalance(agent, state, chainId, asset, requireReliableRead = false) {
     try {
       const balance = await agent.getBalances(state, chainId);
       const target = asset.toLowerCase();
       const token = balance.tokens.find(
         (t) => t.chainId === chainId && t.asset.toLowerCase() === target
       );
-      return !!token && Number(token.amount) > 0;
-    } catch {
+      const targetChainName = agent.supportedAssets.find((entry) => entry.chainId === chainId)?.chain?.trim().toUpperCase();
+      const position = (balance.positions ?? []).find((p) => {
+        const positionChain = p.chain.trim().toUpperCase();
+        const matchesChain = positionChain === String(chainId) || targetChainName !== void 0 && positionChain === targetChainName;
+        return matchesChain && p.asset.toLowerCase() === target && Number(p.amount) > 0;
+      });
+      return !!token && Number(token.amount) > 0 || !!position;
+    } catch (error) {
+      if (requireReliableRead) {
+        throw new OwneyError(
+          "DEPOSIT_BALANCE_UNAVAILABLE",
+          "Could not verify every agent balance. No deposit was submitted. Try again once balances are available.",
+          { agentId: agent.id, chainId, asset, cause: error },
+          agent.id
+        );
+      }
       return false;
     }
   }
@@ -3331,9 +3602,12 @@ var OwneySDK = class {
           { asset, agentErrors: agentErrors2 }
         );
       }
+      const amountsKnown = Object.values(results2).every(
+        (result) => typeof result.amount === "string" && /^\d+$/.test(result.amount)
+      );
       return {
         agentResult: results2,
-        totalWithdrawn: sumWithdrawnAmount(results2).toString()
+        totalWithdrawn: amountsKnown ? sumWithdrawnAmount(results2).toString() : null
       };
     }
     const requested = BigInt(amount);
@@ -3438,7 +3712,8 @@ var OwneySDK = class {
     const state = this.requireState();
     const chainId = this.requireChainId();
     if (agentId) {
-      const result = await this.getAgent(agentId).getBalances(state, chainId);
+      const agent = this.getAgent(agentId);
+      const result = await this.readAgent(agent, "balances", () => agent.getBalances(state, chainId));
       return result;
     }
     let totalBalance = 0;
@@ -3446,12 +3721,14 @@ var OwneySDK = class {
     const entries = [...this.getActiveAgents().entries()];
     const balanceResults = await Promise.allSettled(
       entries.map(async ([id, agent]) => {
-        const b = await agent.getBalances(state, chainId);
+        const b = await this.readAgent(agent, "balances", () => agent.getBalances(state, chainId));
         return [id, b];
       })
     );
     let successCount = 0;
     const agentErrors = {};
+    const agentRetryAt = {};
+    const agentFailures = [];
     for (let i = 0; i < balanceResults.length; i++) {
       const settledResult = balanceResults[i];
       const [agentId2] = entries[i];
@@ -3463,19 +3740,23 @@ var OwneySDK = class {
         continue;
       }
       const reason = settledResult.reason;
+      agentFailures.push(reason);
+      const retryDelay = rateLimitDelay(reason);
+      if (retryDelay !== void 0) agentRetryAt[agentId2] = Date.now() + retryDelay;
       agentErrors[agentId2] = reason instanceof Error ? reason.message : String(reason);
     }
     if (successCount === 0) {
       throw new OwneyError(
         "BALANCE_ALL_FAILED",
         "Failed to fetch balances for all active agents.",
-        { agentErrors }
+        { agentErrors, failures: agentFailures }
       );
     }
     return {
       totalBalance: String(totalBalance),
       totalBalanceAsset: "usdc",
-      agentBalances: results
+      agentBalances: results,
+      ...Object.keys(agentErrors).length > 0 ? { agentErrors, agentRetryAt } : {}
     };
   }
   /**
@@ -3487,14 +3768,15 @@ var OwneySDK = class {
     const state = this.requireState();
     const chainId = this.requireChainId();
     if (agentId) {
-      return this.getAgent(agentId).getEarnings(state, chainId);
+      const agent = this.getAgent(agentId);
+      return this.readAgent(agent, "earnings", () => agent.getEarnings(state, chainId));
     }
     let totalEarnings = 0;
     const results = {};
     const entries = [...this.getActiveAgents().entries()];
     const earningsResults = await Promise.all(
       entries.map(async ([id, agent]) => {
-        const e = await agent.getEarnings(state, chainId);
+        const e = await this.readAgent(agent, "earnings", () => agent.getEarnings(state, chainId));
         return [id, e];
       })
     );
@@ -3514,7 +3796,11 @@ var OwneySDK = class {
   async refreshEarnings(agentId) {
     const state = this.requireState();
     const chainId = this.requireChainId();
-    const refreshAgent = (agent) => agent.refreshEarnings?.(state, chainId) ?? agent.getEarnings(state, chainId);
+    const refreshAgent = (agent) => this.readAgent(
+      agent,
+      agent.refreshEarnings ? "refreshEarnings" : "earnings",
+      () => agent.refreshEarnings?.(state, chainId) ?? agent.getEarnings(state, chainId)
+    );
     if (agentId) return refreshAgent(this.getAgent(agentId));
     let totalEarnings = 0;
     const agentEarnings = {};
@@ -3545,11 +3831,12 @@ var OwneySDK = class {
     const state = this.requireState();
     const chainId = this.requireChainId();
     if (agentId) {
-      return this.getAgent(agentId).getAccountApy(
-        state,
-        chainId,
-        days,
-        tokenSymbol
+      const agent = this.getAgent(agentId);
+      return this.readAgent(
+        agent,
+        "accountApy",
+        () => agent.getAccountApy(state, chainId, days, tokenSymbol),
+        { days, tokenSymbol }
       );
     }
     const activeAgents = this.getActiveAgents();
@@ -3557,18 +3844,18 @@ var OwneySDK = class {
     const [apyResults, balanceResults] = await Promise.all([
       Promise.all(
         entries.map(async ([id, agent]) => {
-          const apy = await agent.getAccountApy(
-            state,
-            chainId,
-            days,
-            tokenSymbol
+          const apy = await this.readAgent(
+            agent,
+            "accountApy",
+            () => agent.getAccountApy(state, chainId, days, tokenSymbol),
+            { days, tokenSymbol }
           );
           return [id, apy];
         })
       ),
       Promise.all(
         entries.map(async ([id, agent]) => {
-          const b = await agent.getBalances(state, chainId);
+          const b = await this.readAgent(agent, "balances", () => agent.getBalances(state, chainId));
           return [id, Number(b.totalBalance)];
         })
       )
@@ -3625,7 +3912,8 @@ var OwneySDK = class {
     const chainId = this.requireChainId();
     const { agentId, filters } = options ?? {};
     if (agentId) {
-      return this.getAgent(agentId).getHistory(state, chainId, filters);
+      const agent = this.getAgent(agentId);
+      return this.readAgent(agent, "history", () => agent.getHistory(state, chainId, filters), filters);
     }
     const activeAgents = [...this.getActiveAgents().values()];
     const cursorMap = filters?.cursor ? decodeMultiAgentCursor(filters.cursor) : {};
@@ -3635,10 +3923,13 @@ var OwneySDK = class {
         if (filters?.cursor && agentCursor === void 0) {
           return { agentId: agent.id, page: null };
         }
-        const page = await agent.getHistory(state, chainId, {
-          ...filters,
-          cursor: agentCursor
-        });
+        const agentFilters = { ...filters, cursor: agentCursor };
+        const page = await this.readAgent(
+          agent,
+          "history",
+          () => agent.getHistory(state, chainId, agentFilters),
+          agentFilters
+        );
         return { agentId: agent.id, page };
       })
     );
@@ -3678,13 +3969,14 @@ var OwneySDK = class {
     const state = this.requireState();
     const chainId = this.requireChainId();
     if (agentId) {
-      return this.getAgent(agentId).getUserProfile(state, chainId);
+      const agent = this.getAgent(agentId);
+      return this.readAgent(agent, "profile", () => agent.getUserProfile(state, chainId));
     }
     const results = {};
     const entries = [...this.getActiveAgents().entries()];
     const profileResults = await Promise.all(
       entries.map(async ([id, agent]) => {
-        const p = await agent.getUserProfile(state, chainId);
+        const p = await this.readAgent(agent, "profile", () => agent.getUserProfile(state, chainId));
         return [id, p];
       })
     );
@@ -3707,7 +3999,20 @@ var OwneySDK = class {
     const chainId = this.requireChainId();
     const agent = this.getAgent(agentId);
     if (typeof agent.ensureAutoSelectProtocols !== "function") return false;
-    return agent.ensureAutoSelectProtocols(state, chainId, asset);
+    const key2 = JSON.stringify([
+      state.walletAddress.toLowerCase(),
+      agentId,
+      chainId,
+      asset
+    ]);
+    const existing = this.activationChecks.get(key2);
+    if (existing) return existing;
+    const pending = Promise.resolve().then(() => agent.ensureAutoSelectProtocols(state, chainId, asset)).finally(() => {
+      if (this.activationChecks.get(key2) === pending)
+        this.activationChecks.delete(key2);
+    });
+    this.activationChecks.set(key2, pending);
+    return pending;
   }
   /**
    * One-time, user-paid approval of Permit2 on the sponsored WETH token for
@@ -3778,13 +4083,14 @@ var OwneySDK = class {
     await this.ensureAgentsInitialized();
     const agentOptions = { tokenSymbol, chainId };
     if (agentId) {
-      return this.getAgent(agentId).getAgentApy(days, agentOptions);
+      const agent = this.getAgent(agentId);
+      return this.readAgent(agent, "agentApy", () => agent.getAgentApy(days, agentOptions), { days, ...agentOptions });
     }
     const results = {};
     const agentEntries = [...this.agents.entries()];
     const apyResults = await Promise.all(
       agentEntries.map(async ([id, agent]) => {
-        const apy = await agent.getAgentApy(days, agentOptions);
+        const apy = await this.readAgent(agent, "agentApy", () => agent.getAgentApy(days, agentOptions), { days, ...agentOptions });
         return [id, apy];
       })
     );
@@ -3811,7 +4117,7 @@ var OwneySDK = class {
     const entries = [...activeAgents.entries()];
     const balanceResults = await Promise.allSettled(
       entries.map(async ([id, agent]) => {
-        const b = await agent.getBalances(state, chainId);
+        const b = await this.readAgent(agent, "balances", () => agent.getBalances(state, chainId));
         return [id, b.positions ?? []];
       })
     );
@@ -3819,6 +4125,7 @@ var OwneySDK = class {
     const allPositions = [];
     let successCount = 0;
     const agentErrors = {};
+    const agentFailures = [];
     for (let i = 0; i < balanceResults.length; i++) {
       const settled = balanceResults[i];
       const [aid] = entries[i];
@@ -3833,6 +4140,7 @@ var OwneySDK = class {
         successCount += 1;
       } else {
         const reason = settled.reason;
+        agentFailures.push(reason);
         agentErrors[aid] = reason instanceof Error ? reason.message : String(reason);
         console.error(`getAllocationApy agent "${aid}" failed:`, reason);
       }
@@ -3841,7 +4149,7 @@ var OwneySDK = class {
       throw new OwneyError(
         "ALLOCATION_ALL_FAILED",
         "Failed to fetch allocation APY: all agents failed.",
-        { agentErrors }
+        { agentErrors, failures: agentFailures }
       );
     }
     const overall = computeAllocationApy(allPositions);