@owney/sdk 0.7.32-beta.5 → 0.7.32-beta.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -430,7 +430,9 @@ interface ConnectionState {
430
430
  /**
431
431
  * Reads under this state use a saved sign-in only: an agent never opens a
432
432
  * wallet prompt for them and fails instead. Set by the whole-portfolio reads
433
- * of an agent that is not active on the connection chain.
433
+ * of an agent that is not active on the connection chain, and by every read
434
+ * of an agent that did not sign in this session (it failed while another
435
+ * agent signed in, or the user cancelled its sign-in).
434
436
  */
435
437
  promptless?: boolean;
436
438
  }
@@ -557,6 +559,14 @@ type AvailablePool = {
557
559
  tvlUsd: number | null;
558
560
  /** Per-pool deep link (e.g. the Morpho vault page). null when absent. */
559
561
  link: string | null;
562
+ /**
563
+ * The pool's on-chain vault address. Yieldseeker identifies its pools by it.
564
+ * Zyfai identifies its pools by name and sends no address, so for Zyfai it is
565
+ * read from the pool's link where that names a vault (Morpho and Euler
566
+ * vaults) and is unset otherwise. It is how the same vault offered by two
567
+ * agents is recognised.
568
+ */
569
+ address?: string;
560
570
  };
561
571
  /** Public Zyfai strategies used by deposit-time pool customization. */
562
572
  type PoolSelectionStrategy = "aggressive" | "yieldmaxxing";
@@ -565,12 +575,25 @@ type UserPoolSelection = {
565
575
  asset: "USDC" | "WETH";
566
576
  protocolId: string;
567
577
  chainId: number;
568
- /** Names enabled by the user for this asset/protocol/chain. */
578
+ /**
579
+ * Names enabled by the user for this asset/protocol/chain. Empty, with
580
+ * `availablePools` not empty, means the user chose none of them.
581
+ */
569
582
  pools: string[];
570
583
  /** Every name shown for this asset/protocol/chain in the superset catalog. */
571
584
  availablePools: string[];
572
585
  };
573
- /** The complete saved draft for the asset/chain legs selected in the deposit. */
586
+ /**
587
+ * The complete saved draft for the asset/chain legs selected in the deposit.
588
+ *
589
+ * An agent whose every entry for an asset and chain has empty `pools` (with
590
+ * vaults shown) gets none of that asset's new deposits there. The agent
591
+ * remembers that "none chosen" on the provider's side, so the next Pools step
592
+ * opens with it, and money already in the agent leaves those pools too:
593
+ * Zyfai saves an empty pool list, and Yieldseeker a vault list naming none, so
594
+ * its money stays idle in the agent. Entries that showed nothing
595
+ * (`availablePools` empty) change nothing.
596
+ */
574
597
  type UserPoolSelectionRequest = {
575
598
  strategies: Array<{
576
599
  asset: "USDC" | "WETH";
@@ -581,7 +604,9 @@ type UserPoolSelectionRequest = {
581
604
  /**
582
605
  * What a user's account currently has saved (ROUT-650): each asset's strategy,
583
606
  * plus the pool list of every protocol/chain pair frozen by an earlier Save.
584
- * Pairs Zyfai still autoselects are left out, so "no entry" means "default".
607
+ * Pairs Zyfai still autoselects are left out, so "no entry" means "default"
608
+ * (nothing saved). A pair that is present with empty `pools` means none
609
+ * chosen: the user picked none of that pair's pools.
585
610
  */
586
611
  type SavedPoolSelection = {
587
612
  strategies: Array<{
@@ -626,6 +651,13 @@ type AgentFundingLedgerAccess = {
626
651
  before: Date;
627
652
  }): Promise<ProviderSnapshotSample | null>;
628
653
  };
654
+ /** What an agent did with a confirmed-deposit notice (`IAgent.depositConfirmed`). */
655
+ type DepositNotice = {
656
+ notified: true;
657
+ } | {
658
+ notified: false;
659
+ reason: string;
660
+ };
629
661
  interface IAgent {
630
662
  readonly id: string;
631
663
  readonly supportedChainIds: readonly OwneySupportedChainId[];
@@ -671,7 +703,20 @@ interface IAgent {
671
703
  beforeRequest?: () => void;
672
704
  }): Promise<ZyfaiHandoffAnswer>;
673
705
  disconnect(): Promise<void>;
706
+ /**
707
+ * Ready the user's account for every asset the agent supports on `chainId`,
708
+ * `asset` first. A failure the provider says will not go away (the user can
709
+ * never have this agent) carries `details.permanent: true`, and the client
710
+ * then refuses the whole connect (`AGENT_ACTIVATION_BLOCKED`).
711
+ */
674
712
  activateAgent(state: ConnectionState, chainId: number, asset?: OwneySupportedTokens): Promise<void>;
713
+ /**
714
+ * True when the provider reported this session that the user cannot have an
715
+ * agent for this chain and asset (Yieldseeker's active-agent limit). Callers
716
+ * leave the slot out of deposits. Optional: an agent without such a limit
717
+ * omits it.
718
+ */
719
+ isSlotUnavailable?(state: ConnectionState, chainId: number, asset: OwneySupportedTokens): boolean;
675
720
  /**
676
721
  * Apply the organization's agent policy to this user's account.
677
722
  *
@@ -696,10 +741,13 @@ interface IAgent {
696
741
  }): Promise<PoolCatalogProtocol[]>;
697
742
  /**
698
743
  * Apply a user's own pool selection to their account, driven by the
699
- * deposit-time Pools step. Optional, and non-fatal like `applyOrgPolicy`.
700
- * (ROUT-569)
744
+ * deposit-time Pools step. Optional. A failure throws, and the caller
745
+ * must not start the deposit.
746
+ * `state` is the client's connection, or undefined when there is none; an
747
+ * agent that signs in per call (Yieldseeker) needs it, and one that is
748
+ * already connected (Zyfai) ignores it. (ROUT-569)
701
749
  */
702
- setPoolSelection?(selection: UserPoolSelectionRequest): Promise<void>;
750
+ setPoolSelection?(selection: UserPoolSelectionRequest, state?: ConnectionState): Promise<void>;
703
751
  /**
704
752
  * Read back what `setPoolSelection` saved, for the pairs and assets given,
705
753
  * so the Pools step can open on the user's own choices. Optional. (ROUT-650)
@@ -732,6 +780,14 @@ interface IAgent {
732
780
  verifyWithdrawalCompletion?(state: ConnectionState, evidence: FundingEvidence): Promise<WithdrawalCompletion>;
733
781
  /** A newly observed pool allocation invalidates this asset's portfolio cache only. */
734
782
  invalidateAllocationRead?(state: ConnectionState, chainId: number, asset: OwneySupportedTokens): void;
783
+ /**
784
+ * A deposit into this agent just confirmed on-chain. An agent whose provider
785
+ * can act on a deposit at once tells it here (Yieldseeker then allocates it
786
+ * instead of waiting for its next scheduled check). The client calls it once
787
+ * per confirmed transfer, in the background: it must never prompt the wallet
788
+ * and never throw. Agents without it rely on their provider's own discovery.
789
+ */
790
+ depositConfirmed?(state: ConnectionState, chainId: number, evidence: FundingEvidence): Promise<DepositNotice>;
735
791
  /** Invalidate only the confirmed asset. This hook must not sign or submit transactions. */
736
792
  invalidateFundingRead?(state: ConnectionState, chainId: number, asset: OwneySupportedTokens, refreshUntil?: number, txHash?: string): void;
737
793
  /** End accelerated balance reads only for the exact snapshot the caller displayed. */
@@ -828,11 +884,27 @@ type AvailableAgent = {
828
884
  supportedChainIds: readonly number[];
829
885
  supportedAssets: readonly AgentSupportedAssets[];
830
886
  };
887
+ type ActivateAgentOptions = {
888
+ /** Limits agent setup to what this asset needs. Omit for every asset. */
889
+ asset?: OwneySupportedTokens;
890
+ /**
891
+ * Called once the chain and agents are registered, before any agent signs in
892
+ * or runs its setup. From then on reads such as `getBalances` are safe to
893
+ * start: each agent's reads wait on that agent's own sign-in, so they share
894
+ * the activation's one wallet prompt instead of waiting for all of setup.
895
+ */
896
+ onAgentsSelected?: () => void;
897
+ };
831
898
  type AvailableAgentsOptions = {
832
899
  chainId?: number;
833
900
  asset?: Asset;
834
- /** Disabled agents are omitted by default because they cannot accept funds. */
901
+ /** Disabled agents are omitted by default because they cannot accept funds.
902
+ * Listing them also lists unavailable agents: both may still hold funds. */
835
903
  includeDisabled?: boolean;
904
+ /** Agents unavailable on `chainId` and `asset` this session are omitted by
905
+ * default because they get no deposits: their provider has no agent for the
906
+ * slot. See `OwneySDK.getUnavailableAgentIds`. */
907
+ includeUnavailable?: boolean;
836
908
  };
837
909
  /**
838
910
  * A lookback window for any "last N days" read — the APY series, the daily
@@ -1004,6 +1076,17 @@ type DepositOptions = {
1004
1076
  asset: Asset;
1005
1077
  depositCallback?: DepositCallback;
1006
1078
  agentId?: AgentId;
1079
+ /**
1080
+ * Agents that must receive nothing from this deposit. The rest split the
1081
+ * whole amount, and only their minimums apply; an excluded agent is not read,
1082
+ * not prioritized as unfunded and not reported on.
1083
+ *
1084
+ * Throws `ALL_AGENTS_EXCLUDED` (before anything is read or sent) when no
1085
+ * agent is left, or when `agentId` itself is listed. Unknown ids are ignored.
1086
+ * Ignored by `resumeTxHash` and `resumeSavedBatch`: a signed batch is already
1087
+ * committed to its wallets and must be finished as signed.
1088
+ */
1089
+ excludeAgentIds?: AgentId[];
1007
1090
  onApproved?: () => void;
1008
1091
  /** Funding ledger reference (a UUID). Defaults to a new random UUID; apps pass
1009
1092
  * their own so the app record and the ledger share one reference. */
@@ -1405,17 +1488,31 @@ interface OwneyEarnings {
1405
1488
  agentRetryAt?: Partial<Record<AgentId, number>>;
1406
1489
  }
1407
1490
  type ApyByChainAndAsset = Partial<Record<OwneySupportedChainId, Partial<Record<OwneySupportedTokens, number>>>>;
1491
+ /** One external reward program contributing percentage points to a day. */
1492
+ interface ApyIncentive {
1493
+ source: "merkl";
1494
+ agentId: AgentId;
1495
+ opportunityId: string;
1496
+ /** All on-chain campaigns represented by the opportunity APR that day. */
1497
+ campaignIds: string[];
1498
+ /** Source APR before portfolio weighting, expressed as a percentage. */
1499
+ apr: number;
1500
+ /** Percentage points to add to this point's native/provider `apy`. */
1501
+ apyContribution: number;
1502
+ }
1408
1503
  /** A single day's net APY for the connected account, as a percentage number. */
1409
1504
  interface ApyHistoryPoint {
1410
1505
  /** ISO date string for the day, e.g. "2026-06-20". */
1411
1506
  date: string;
1412
- /** Net (after-fee) weighted APY for that day, summed across tokens. */
1507
+ /** Native/provider net APY. External incentives are deliberately excluded. */
1413
1508
  apy: number;
1414
1509
  /** Balance on this date, in the explicitly named unit; never today's balance. */
1415
1510
  historicalBalance?: {
1416
1511
  amount: number;
1417
1512
  unit: string;
1418
1513
  };
1514
+ /** Best-effort external rewards. Absent when none apply or cannot be read. */
1515
+ incentives?: ApyIncentive[];
1419
1516
  }
1420
1517
  /**
1421
1518
  * What the APY chart's chain/asset menus are allowed to offer, and how far
@@ -1675,7 +1772,7 @@ type WithdrawalPayoutScan = {
1675
1772
  caughtUp: boolean;
1676
1773
  };
1677
1774
 
1678
- type OwneyErrorCode = "NOT_CONNECTED" | "NO_ACTIVE_CHAIN" | "WALLET_NO_ACCOUNTS" | "WALLET_ADDRESS_REQUIRED" | "WALLET_NOT_DEPLOYED" | "AGENT_NOT_FOUND" | "AGENT_CHAIN_INCOMPATIBLE" | "AGENT_EMPTY_LIST" | "AGENT_DISABLED" | "AGENT_ACTIVATION_PARTIAL_FAILURE" | "YIELDSEEKER_AGENT_MISSING" | "YIELDSEEKER_WALLET_UNVERIFIED" | "CHAIN_UNSUPPORTED" | "CHAIN_NO_COMPATIBLE_AGENTS" | "CHAIN_MISMATCH" | "ASSET_UNSUPPORTED" | "ASSET_NO_COMPATIBLE_AGENTS" | "DEPOSIT_BALANCE_UNAVAILABLE" | "DEPOSIT_PARTIAL_FAILURE" | "DEPOSIT_IN_PROGRESS" | "DEPOSIT_CHECKPOINT_FAILED" | "DEPOSIT_AMOUNT_BELOW_MINIMUM" | "DEPOSIT_INVALID_AMOUNT" | "DEPOSIT_CALLBACK_REQUIRED" | "DEPOSIT_CALLBACK_INVALID" | "DEPOSIT_NO_PERMITTED_TOKENS" | "DEPOSIT_INSUFFICIENT_BALANCE" | "WITHDRAW_IN_PROGRESS" | "WITHDRAW_NO_PERMITTED_TOKENS" | "WITHDRAW_BALANCE_UNAVAILABLE" | "WITHDRAW_INSUFFICIENT_BALANCE" | "WITHDRAW_ALL_FAILED" | "WITHDRAW_UNCONFIRMED" | "WITHDRAW_NOTHING_TO_WITHDRAW" | "WITHDRAW_PARTIAL_FAILURE" | "WITHDRAW_SWAP_INCOMPLETE" | "WITHDRAW_FAILED" | "WITHDRAW_INVALID_AMOUNT" | "WITHDRAW_RESERVATION_UNAVAILABLE" | "AGENT_RATE_LIMITED" | "API_ROUTING_ERROR" | "API_ROUTING_FAILED" | "API_NO_AGENTS" | "AGENT_API_ERROR" | "AGENT_AUTH_FAILED" | "AGENT_INVALID_RESPONSE" | "AGENT_TIMEOUT" | "AGENT_TRANSACTION_REVERTED" | "AGENT_APY_PERIOD_UNSUPPORTED" | "SPONSOR_REQUEST_FAILED" | "PERMIT2_APPROVAL_REQUIRED" | "SPONSORED_CALLS_UNSUPPORTED" | "SPONSORED_CALLS_NO_ID" | "SPONSORED_CALLS_NO_RECEIPT" | "SWAP_DISABLED" | "SWAP_RATE_LIMITED" | "SWAP_REQUEST_FAILED" | "SWAP_QUOTE_FAILED" | "SWAP_UNSUPPORTED_PAIR" | "SWAP_APPROVAL_REQUIRED" | "SWAP_BELOW_DEPOSIT_MINIMUM" | "SWAP_DEPOSIT_PENDING" | "SWAP_WALLET_PROMPT_TIMEOUT" | "SWAP_INSUFFICIENT_GAS" | "SWAP_NATIVE_UNSUPPORTED" | "SWAP_ORDER_EXPIRED" | "SWAP_ORDER_REFUNDED" | "SWAP_ORDER_CANCELLED" | "SWAP_ORDER_NOT_FOUND" | "WITHDRAW_ARRIVAL_TIMEOUT" | "WITHDRAW_SWAP_FAILED" | "BALANCE_ALL_FAILED" | "EARNINGS_ALL_FAILED" | "ALLOCATION_ALL_FAILED" | "POOL_CATALOG_UNSUPPORTED" | "POOL_SELECTION_UNSUPPORTED" | "VALIDATION_INVALID_DAYS";
1775
+ type OwneyErrorCode = "NOT_CONNECTED" | "NO_ACTIVE_CHAIN" | "WALLET_NO_ACCOUNTS" | "WALLET_ADDRESS_REQUIRED" | "WALLET_NOT_DEPLOYED" | "AGENT_NOT_FOUND" | "AGENT_CHAIN_INCOMPATIBLE" | "AGENT_EMPTY_LIST" | "AGENT_DISABLED" | "AGENT_ACTIVATION_PARTIAL_FAILURE" | "AGENT_ACTIVATION_BLOCKED" | "YIELDSEEKER_AGENT_MISSING" | "YIELDSEEKER_AGENT_CLOSED" | "YIELDSEEKER_SLOT_UNAVAILABLE" | "YIELDSEEKER_WALLET_UNVERIFIED" | "CHAIN_UNSUPPORTED" | "CHAIN_NO_COMPATIBLE_AGENTS" | "CHAIN_MISMATCH" | "ASSET_UNSUPPORTED" | "ASSET_NO_COMPATIBLE_AGENTS" | "DEPOSIT_BALANCE_UNAVAILABLE" | "DEPOSIT_PARTIAL_FAILURE" | "DEPOSIT_IN_PROGRESS" | "DEPOSIT_CHECKPOINT_FAILED" | "DEPOSIT_AMOUNT_BELOW_MINIMUM" | "DEPOSIT_INVALID_AMOUNT" | "DEPOSIT_CALLBACK_REQUIRED" | "DEPOSIT_CALLBACK_INVALID" | "DEPOSIT_NO_PERMITTED_TOKENS" | "DEPOSIT_INSUFFICIENT_BALANCE" | "ALL_AGENTS_EXCLUDED" | "WITHDRAW_IN_PROGRESS" | "WITHDRAW_NO_PERMITTED_TOKENS" | "WITHDRAW_BALANCE_UNAVAILABLE" | "WITHDRAW_INSUFFICIENT_BALANCE" | "WITHDRAW_ALL_FAILED" | "WITHDRAW_UNCONFIRMED" | "WITHDRAW_NOTHING_TO_WITHDRAW" | "WITHDRAW_PARTIAL_FAILURE" | "WITHDRAW_SWAP_INCOMPLETE" | "WITHDRAW_FAILED" | "WITHDRAW_INVALID_AMOUNT" | "WITHDRAW_RESERVATION_UNAVAILABLE" | "AGENT_RATE_LIMITED" | "API_ROUTING_ERROR" | "API_ROUTING_FAILED" | "API_NO_AGENTS" | "AGENT_API_ERROR" | "AGENT_AUTH_FAILED" | "AGENT_INVALID_RESPONSE" | "AGENT_TIMEOUT" | "AGENT_TRANSACTION_REVERTED" | "AGENT_APY_PERIOD_UNSUPPORTED" | "SPONSOR_REQUEST_FAILED" | "PERMIT2_APPROVAL_REQUIRED" | "SPONSORED_CALLS_UNSUPPORTED" | "SPONSORED_CALLS_NO_ID" | "SPONSORED_CALLS_NO_RECEIPT" | "SWAP_DISABLED" | "SWAP_RATE_LIMITED" | "SWAP_REQUEST_FAILED" | "SWAP_QUOTE_FAILED" | "SWAP_UNSUPPORTED_PAIR" | "SWAP_APPROVAL_REQUIRED" | "SWAP_BELOW_DEPOSIT_MINIMUM" | "SWAP_DEPOSIT_PENDING" | "SWAP_WALLET_PROMPT_TIMEOUT" | "SWAP_INSUFFICIENT_GAS" | "SWAP_NATIVE_UNSUPPORTED" | "SWAP_ORDER_EXPIRED" | "SWAP_ORDER_REFUNDED" | "SWAP_ORDER_CANCELLED" | "SWAP_ORDER_NOT_FOUND" | "WITHDRAW_ARRIVAL_TIMEOUT" | "WITHDRAW_SWAP_FAILED" | "BALANCE_ALL_FAILED" | "EARNINGS_ALL_FAILED" | "ALLOCATION_ALL_FAILED" | "POOL_CATALOG_UNSUPPORTED" | "POOL_SELECTION_UNSUPPORTED" | "POOL_SELECTION_NOT_APPLIED" | "POOL_SELECTION_RULE_LIMIT" | "VALIDATION_INVALID_DAYS";
1679
1776
  declare class OwneyError extends Error {
1680
1777
  readonly code: OwneyErrorCode;
1681
1778
  readonly details?: Record<string, unknown>;
@@ -1846,6 +1943,14 @@ declare class OwneySDK {
1846
1943
  * withdraw, but they are excluded from new deposits / activations.
1847
1944
  */
1848
1945
  private disabledAgents;
1946
+ /**
1947
+ * Agents whose sign-in the user cancelled this session (the wallet rejected
1948
+ * the prompt), keyed by chain. Until the app ends the session they are read
1949
+ * from a saved sign-in only (`readStateFor`), so no read reopens the prompt
1950
+ * the user cancelled. A later successful activation of the agent removes
1951
+ * it, and `disconnect()` or a different wallet's `connect()` clears the map.
1952
+ */
1953
+ private declinedSignIns;
1849
1954
  private state;
1850
1955
  private connectionRevision;
1851
1956
  private disconnectingAgents;
@@ -1877,6 +1982,8 @@ declare class OwneySDK {
1877
1982
  * session started: true when it armed the refresh, false when its deadline
1878
1983
  * had passed (it only dropped the cache and forced one snapshot read). */
1879
1984
  private readonly recoveredFundingReads;
1985
+ /** Confirmed deposits already announced to their agent (`depositConfirmed`), bounded. */
1986
+ private readonly announcedDeposits;
1880
1987
  private fundingBalanceChecks;
1881
1988
  private readonly activationChecks;
1882
1989
  private readonly withdrawalSubmissions;
@@ -1952,6 +2059,33 @@ declare class OwneySDK {
1952
2059
  private clearConnectionState;
1953
2060
  private disconnectAgents;
1954
2061
  private isAgentDisabled;
2062
+ /**
2063
+ * True when `id` takes no new deposits on this chain and asset this
2064
+ * session: its adapter reports no agent for the slot.
2065
+ */
2066
+ private isAgentUnavailable;
2067
+ /**
2068
+ * The agents that take no new deposits on this chain and asset this
2069
+ * session, so the app can show them as unavailable: each agent whose
2070
+ * provider has no agent for this slot. They stay withdrawable.
2071
+ */
2072
+ getUnavailableAgentIds(chainId: number, asset?: string): AgentId[];
2073
+ /**
2074
+ * The adapter reports no agent for this chain and asset this session (see
2075
+ * `IAgent.isSlotUnavailable`): there is nothing there to withdraw, so a
2076
+ * withdrawal without an explicit agent leaves it out instead of failing its
2077
+ * leg.
2078
+ */
2079
+ private hasNoAgentForSlot;
2080
+ /**
2081
+ * The state an agent's reads use. An agent whose sign-in the user cancelled
2082
+ * on the connection chain this session is read from a saved sign-in only,
2083
+ * as `offChainPortfolioAgents` reads: a read that would need a wallet
2084
+ * prompt fails for that agent instead of reopening the prompt the user
2085
+ * cancelled. A later successful activation of the agent, or `disconnect()`,
2086
+ * lifts it.
2087
+ */
2088
+ private readStateFor;
1955
2089
  /**
1956
2090
  * Check if the SDK has an active connection state.
1957
2091
  * @returns `true` if `connect()` has been called and `disconnect()` has not
@@ -2006,6 +2140,8 @@ declare class OwneySDK {
2006
2140
  /** Every agent a whole-portfolio read covers: the active ones on the
2007
2141
  * connection chain, then the off-chain ones on their own chain. */
2008
2142
  private portfolioReads;
2143
+ /** The active agents, each with the state its reads use (`readStateFor`). */
2144
+ private activeReads;
2009
2145
  /**
2010
2146
  * Read the org's agent policy once and reuse it. fetchOrgAgentConfig never
2011
2147
  * throws — it degrades to null — so this cannot break activation.
@@ -2036,8 +2172,17 @@ declare class OwneySDK {
2036
2172
  * that support the given chainId (incompatible agents are silently skipped).
2037
2173
  * If provided, ALL specified agents must support the chainId or the call
2038
2174
  * throws before activating any agent.
2039
- */
2040
- activateAgent(chainId: number, agentId?: AgentId[], asset?: OwneySupportedTokens): Promise<void>;
2175
+ * @param options - Optional. `asset` limits setup to that asset;
2176
+ * `onAgentsSelected` fires once reads can start.
2177
+ * @throws Activation stops at the first agent that fails, and the caller
2178
+ * should end the session. `AGENT_ACTIVATION_PARTIAL_FAILURE` when an
2179
+ * earlier agent activated; `walletRejected` in its details means the user
2180
+ * rejected a signature. `AGENT_ACTIVATION_BLOCKED` when the agent can
2181
+ * never be readied (`details.permanent`). Otherwise the agent's own error
2182
+ * is thrown as is. Until it signs in, an agent whose signature the user
2183
+ * rejected is read from a saved sign-in only and opens no prompt.
2184
+ */
2185
+ activateAgent(chainId: number, agentId?: AgentId[], options?: ActivateAgentOptions): Promise<void>;
2041
2186
  private assertActivationSession;
2042
2187
  /**
2043
2188
  * Activate agents ONE AT A TIME, each followed by its org policy.
@@ -2052,9 +2197,13 @@ declare class OwneySDK {
2052
2197
  * Serializing costs no real wall-clock: the user can only approve one prompt
2053
2198
  * at a time anyway.
2054
2199
  *
2055
- * Stop at the first failure so a canceled sign-in does not open another
2056
- * agent's wallet prompt. Report any earlier successes for diagnostics; the
2057
- * app discards the session when the complete sign-in does not succeed.
2200
+ * Stop at the first failure (2026-11-06): a connect needs every agent, so
2201
+ * no later agent's wallet prompt opens for a sign-in that already failed.
2202
+ * When an earlier agent activated, the partial failure reports it, and
2203
+ * `walletRejected` tells the app the user canceled; the app ends the
2204
+ * session either way. When none activated, the agent's own error is thrown.
2205
+ * A failure the provider marks `permanent` is thrown as
2206
+ * `AGENT_ACTIVATION_BLOCKED`.
2058
2207
  */
2059
2208
  private activateAgentsInTurn;
2060
2209
  /**
@@ -2069,6 +2218,10 @@ declare class OwneySDK {
2069
2218
  * all shares into one signature; custom callbacks still run once per agent.
2070
2219
  * @param options.agentId - Optional explicit target. Otherwise split equally,
2071
2220
  * or fund remaining agents when a recovery deposit cannot meet every minimum.
2221
+ * @param options.excludeAgentIds - Agents that must receive nothing. The rest
2222
+ * split the whole amount under their own minimums. Throws
2223
+ * `ALL_AGENTS_EXCLUDED` when none is left or `agentId` is listed. Ignored
2224
+ * when resuming a signed batch.
2072
2225
  * @returns {OwneyDepositResult} for a single agent, or {OwneyMultiDepositResult} with per-agent results
2073
2226
  */
2074
2227
  deposit(options: DepositOptions): Promise<OwneyDepositResult | OwneyMultiDepositResult>;
@@ -2100,6 +2253,13 @@ declare class OwneySDK {
2100
2253
  * doesn't force a retry of sibling agents in a multi-agent split.
2101
2254
  */
2102
2255
  private depositWithFallback;
2256
+ /**
2257
+ * Refuses a new deposit that `excludeAgentIds` leaves with nobody to fund:
2258
+ * the explicit `agentId` is listed, or every agent that can take this asset
2259
+ * on this chain (and is not disabled) is. A no-op without a list, so a deposit
2260
+ * without exclusions is exactly as it was. Reads no provider.
2261
+ */
2262
+ private assertDepositAgentsRemain;
2103
2263
  private getMinDepositAmount;
2104
2264
  private splitDepositAmount;
2105
2265
  private formatAgentName;
@@ -2129,6 +2289,12 @@ declare class OwneySDK {
2129
2289
  */
2130
2290
  private validateChainHasAgents;
2131
2291
  private validateAssetSupport;
2292
+ /**
2293
+ * The agents that support this asset on this chain. `excludeDisabled` is for
2294
+ * new deposits: it also leaves out the agents unavailable for this slot this
2295
+ * session (see `getUnavailableAgentIds`). Without it, withdrawals and deposit
2296
+ * recovery still see every agent that may hold funds.
2297
+ */
2132
2298
  private getEligibleAgents;
2133
2299
  /**
2134
2300
  * Run owner-approved withdrawals before relayer-only withdrawals. Wallet
@@ -2136,6 +2302,11 @@ declare class OwneySDK {
2136
2302
  * operation, so no relayer leg should commit before it has completed.
2137
2303
  */
2138
2304
  private orderAgentsForWithdrawal;
2305
+ /**
2306
+ * The user cancelled a wallet prompt, for any agent: see isWalletRejection.
2307
+ * That includes an agent error that kept the rejection only as text in
2308
+ * `details.cause`.
2309
+ */
2139
2310
  private isUserRejectedWithdrawal;
2140
2311
  private captureReadScope;
2141
2312
  /** Revalidate a saved transfer against the authenticated account and actual receipt. */
@@ -2144,6 +2315,14 @@ declare class OwneySDK {
2144
2315
  refreshBalance?: boolean;
2145
2316
  requireAmountMatch?: boolean;
2146
2317
  }): Promise<FundingEvidence>;
2318
+ /**
2319
+ * Tells the agent, once per confirmed deposit transfer, that its deposit
2320
+ * landed (`IAgent.depositConfirmed`), and records the outcome on the
2321
+ * deposit's ledger operation when there is one. In the background: never
2322
+ * throws and never delays the deposit. A missed notice only leaves the
2323
+ * provider on its own schedule.
2324
+ */
2325
+ private announceDepositConfirmed;
2147
2326
  private noteFundingRefresh;
2148
2327
  /**
2149
2328
  * Re-arms an agent's balance refresh after a confirmed deposit or withdrawal
@@ -2379,8 +2558,19 @@ declare class OwneySDK {
2379
2558
  * second half of `swapAndDeposit` on its own. Cleared only once the deposit
2380
2559
  * has actually gone through — a failure here leaves the record in place so it
2381
2560
  * can be offered again rather than silently dropped.
2561
+ *
2562
+ * The record does not remember `excludeAgentIds`, on purpose: the caller must
2563
+ * pass the CURRENT list, because the user's choice may have changed since the
2564
+ * swap (a deposit reads it fresh each time). Without it, a record with no
2565
+ * `agentId` splits across every eligible agent. When the list leaves nobody to
2566
+ * fund (or names the record's own agent) it throws `ALL_AGENTS_EXCLUDED`
2567
+ * before the wallet is touched and keeps the record.
2568
+ *
2569
+ * @param options.excludeAgentIds - See `DepositOptions.excludeAgentIds`.
2382
2570
  */
2383
- completePendingDeposit(id: string): Promise<OwneyDepositResult | OwneyMultiDepositResult>;
2571
+ completePendingDeposit(id: string, options?: {
2572
+ excludeAgentIds?: AgentId[];
2573
+ }): Promise<OwneyDepositResult | OwneyMultiDepositResult>;
2384
2574
  /**
2385
2575
  * Pick up cross-chain swaps a previous session left in flight.
2386
2576
  *
@@ -2517,6 +2707,13 @@ declare class OwneySDK {
2517
2707
  symbol: string;
2518
2708
  };
2519
2709
  agentId?: AgentId;
2710
+ /**
2711
+ * Agents the deposit must not fund (see `DepositOptions.excludeAgentIds`).
2712
+ * Checked before the quote, so a swap that could not end in a deposit never
2713
+ * starts. Not stored on a pending deposit: whoever finishes one later
2714
+ * passes the then-current list to `completePendingDeposit(id, options)`.
2715
+ */
2716
+ excludeAgentIds?: AgentId[];
2520
2717
  /** Percent, classic rail only. Fusion+ prices through its auction. */
2521
2718
  slippage?: number;
2522
2719
  onSwapProgress?: (stage: SwapStage) => void;
@@ -2823,7 +3020,14 @@ declare class OwneySDK {
2823
3020
  assets: Array<"USDC" | "WETH">;
2824
3021
  agentId?: AgentId;
2825
3022
  }): Promise<SavedPoolSelection>;
3023
+ /**
3024
+ * The agents a person can customize pools for: registered, enabled, and
3025
+ * able to list a pool catalogue. Waits for agent initialization, so an agent
3026
+ * the organization disabled is known and left out.
3027
+ */
3028
+ getPoolCustomizationAgents(): Promise<AgentId[]>;
2826
3029
  getAccountApy({ agentId, days, tokenSymbol, chainId: scope, }: AccountApyOptions): Promise<OwneyAccountApy | AccountAgentApy>;
3030
+ private enrichApyHistory;
2827
3031
  /**
2828
3032
  * Get transaction history for a specific agent, or all agents.
2829
3033
  *
@@ -2969,6 +3173,11 @@ declare class YieldseekerAgent implements IAgent {
2969
3173
  private readonly agentAccountReads;
2970
3174
  private readonly reportedAccounts;
2971
3175
  private readonly missingSlots;
3176
+ private readonly rethrownSlotFailures;
3177
+ private readonly closedSlots;
3178
+ private readonly pendingReopens;
3179
+ private readonly unavailableSlots;
3180
+ private readonly pendingReactivates;
2972
3181
  private readonly freshListReads;
2973
3182
  private readonly knownContextKeys;
2974
3183
  private readonly pendingSlotInvalidations;
@@ -3013,6 +3222,7 @@ declare class YieldseekerAgent implements IAgent {
3013
3222
  private ledgerBudgetMs;
3014
3223
  /** slotKey -> the last successful ledger rows and when they arrived. */
3015
3224
  private readonly lastLedgerRows;
3225
+ /** Keyed by `vaultOptionsKey`: each asset's usable list and its full list are cached apart. */
3016
3226
  private readonly vaultOptions;
3017
3227
  private readonly pendingVaultOptions;
3018
3228
  private readonly assetApyStats;
@@ -3023,6 +3233,32 @@ declare class YieldseekerAgent implements IAgent {
3023
3233
  getWalletStatus(state: ConnectionState, chainId: number, asset: OwneySupportedTokens, useCachedV2?: boolean): Promise<YieldseekerWalletStatus | null>;
3024
3234
  /** Reads (or reuses the 15-minute verified V2 hint for) this exact context's wallet. */
3025
3235
  private readWalletStatus;
3236
+ /**
3237
+ * Deposits go only to an agent Yieldseeker still has open. The session caches
3238
+ * the selected agent, so a tab left open can hold one Yieldseeker has since
3239
+ * closed (deactivated). This reads the agent wallet fresh from Yieldseeker,
3240
+ * bypassing the cached wallet contexts, and:
3241
+ * - open, same wallet address: returns the context to deposit with;
3242
+ * - closed (`deactivatedDate` set): reactivates it, re-reads the wallet, and
3243
+ * continues only when it is now open with the same address. Only the
3244
+ * verified record's agent is reopened: any other closed agent (a
3245
+ * superseded-wallet match, or a named agent with no verified record, also
3246
+ * when the accounts could not be read) refuses without a request;
3247
+ * - anything else refuses with nothing sent, before any progress event,
3248
+ * signature or callback. Every refusal carries `notSubmitted` and
3249
+ * `safeToFallback: false`, so no paid fallback runs.
3250
+ * A slot recorded unavailable (the active-agent limit) refuses at once with
3251
+ * no request. The reactivate goes through reactivateSlot, which shares one
3252
+ * request per slot and remembers a failure for the list-cache window, so
3253
+ * repeated deposits do not repeat it. A failed wallet read fails closed
3254
+ * (YIELDSEEKER_WALLET_UNVERIFIED, reason UNAVAILABLE), like the on-chain
3255
+ * gate. A reactivate that fails keeps its error code
3256
+ * (YIELDSEEKER_AGENT_CLOSED, or the mapped API error for a transient
3257
+ * failure). At the limit the slot is also recorded unavailable for the
3258
+ * session (see isSlotUnavailable). Session changes keep their own
3259
+ * NOT_CONNECTED error.
3260
+ */
3261
+ private assertAgentOpen;
3026
3262
  /**
3027
3263
  * Deposits go only to a wallet whose identity is verified on chain (factory
3028
3264
  * mapping, owner, base asset, FACTORY). The API key is public, so the wallet
@@ -3039,7 +3275,20 @@ declare class YieldseekerAgent implements IAgent {
3039
3275
  status: YieldseekerWalletStatus;
3040
3276
  }>;
3041
3277
  disconnect(): Promise<void>;
3278
+ /**
3279
+ * Ready every asset's agent, `asset` first: a missing one is created and a
3280
+ * closed one reopened (2026-11-06). A slot Yieldseeker will never let the
3281
+ * user have (the agent limit, closed for good, missing with no way to
3282
+ * reopen) is rethrown with `details.permanent`, which refuses the connect.
3283
+ * A temporary failure (an API error or timeout) on another asset does not:
3284
+ * that slot answers again where it is needed. On the selected asset every
3285
+ * failure is thrown as before, without readying the rest, so a failed
3286
+ * sign-in never opens a second prompt.
3287
+ */
3042
3288
  activateAgent(state: ConnectionState, chainId: number, asset?: OwneySupportedTokens): Promise<void>;
3289
+ /** The same failure, marked as one that will not go away this session. */
3290
+ private permanentFailure;
3291
+ isSlotUnavailable(state: ConnectionState, chainId: number, asset: OwneySupportedTokens): boolean;
3043
3292
  deposit(state: ConnectionState, chainId: number, amount: string, asset: OwneySupportedTokens, depositCallback?: DepositCallback, onProgress?: FundingProgress, onBeforeSubmission?: (evidence: FundingEvidence) => void | Promise<void>): Promise<OwneyDepositResult>;
3044
3293
  withdraw(state: ConnectionState, chainId: number, asset: OwneySupportedTokens, amount?: string, onProgress?: FundingProgress, gasMode?: "auto" | "sponsored" | "paid", onBeforeSubmission?: FundingProgress, assertOperation?: () => void, submission?: {
3045
3294
  operationId?: string;
@@ -3066,6 +3315,15 @@ declare class YieldseekerAgent implements IAgent {
3066
3315
  invalidateAllocationRead(state: ConnectionState, chainId: number, asset: OwneySupportedTokens): void;
3067
3316
  invalidateFundingRead(state: ConnectionState, chainId: number, asset: OwneySupportedTokens, refreshUntil?: number, txHash?: string): void;
3068
3317
  endFundingBalanceRefresh(state: ConnectionState, chainId: number, asset: OwneySupportedTokens, read: AssetReadMetadata): boolean;
3318
+ /**
3319
+ * Tells Yieldseeker a deposit landed (`deposit-made`), so the agent allocates
3320
+ * it now instead of on its next 30-minute check. Yieldseeker decides whether
3321
+ * anything moves (the funding minimum, a deployed agent, no manual
3322
+ * withdrawal in the last hour). Uses the agent this session already knows
3323
+ * for the asset and the saved sign-in only: never prompts, never retries,
3324
+ * never throws.
3325
+ */
3326
+ depositConfirmed(state: ConnectionState, chainId: number, evidence: FundingEvidence): Promise<DepositNotice>;
3069
3327
  getFundingWallet(state: ConnectionState, chainId: number, asset: OwneySupportedTokens): Promise<string>;
3070
3328
  hasExistingDepositFunds(state: ConnectionState, chainId: number, asset: OwneySupportedTokens): Promise<true | undefined>;
3071
3329
  getEarnings(state: ConnectionState, chainId: number): Promise<AgentEarnings>;
@@ -3078,7 +3336,104 @@ declare class YieldseekerAgent implements IAgent {
3078
3336
  getAgentApy(days: DailyApyDays, options?: AgentApyOptions): Promise<AgentApy>;
3079
3337
  supportsAgentApyPeriod(days: DailyApyDays): boolean;
3080
3338
  private loadAssetApyStats;
3339
+ /**
3340
+ * The deposit-time Pools step's catalogue: every vault Yieldseeker lists
3341
+ * for a new agent on `asset` on Base, grouped by provider (the provider is
3342
+ * both `protocolId` and `name`). Nothing is filtered on our side, on
3343
+ * liquidity, size or provider. `strategy` is accepted for the IAgent
3344
+ * contract and ignored.
3345
+ */
3346
+ getPoolCatalog(params: {
3347
+ asset: string;
3348
+ strategy?: "conservative" | "aggressive" | "yieldmaxxing";
3349
+ }): Promise<PoolCatalogProtocol[]>;
3350
+ /**
3351
+ * The asset's vaults on Base. By default only those a new agent can use:
3352
+ * Yieldseeker leaves out the ones it has disabled (40acres and Moonwell
3353
+ * among them), gated or can't use, so the picker follows its list
3354
+ * (2026-11-04). `includeUnavailable` adds those back, for anything about
3355
+ * money an agent may still hold in one: withdrawals and activity.
3356
+ */
3081
3357
  private loadVaultOptions;
3358
+ /**
3359
+ * Save the user's Yieldseeker picks as the agent's managed vault list, then
3360
+ * read the rules back before any money moves. Each asset has its own agent,
3361
+ * so each is saved on its own. `pools` and `availablePools` hold vault
3362
+ * addresses.
3363
+ *
3364
+ * - Only Base entries are ours. An asset with no picks whose entries showed
3365
+ * no vault is skipped and nothing is sent.
3366
+ * - Some vaults picked: the managed list names them. Saving it again
3367
+ * replaces it, so there is only ever one.
3368
+ * - None picked (vaults shown): the managed list names no vault, and the
3369
+ * rules must read back as an empty allow-list. Yieldseeker then keeps the
3370
+ * agent's money out of every vault, as Zyfai does with an empty pool list,
3371
+ * and the next Pools step reads "none". Only an agent that already exists
3372
+ * is written: one is never created just to hold "none".
3373
+ * - Every vault picked: the managed list is deleted, and no allow-list may
3374
+ * remain, so vaults Yieldseeker adds later are allowed too.
3375
+ * - A free-text allow-list we saved before the managed list existed is
3376
+ * deleted once the new state is written. A failed delete does not fail the
3377
+ * save; it is debug-logged, and the read-back decides.
3378
+ * - A read-back that differs puts the previous managed list back (or deletes
3379
+ * the one just created) and throws POOL_SELECTION_NOT_APPLIED. If putting
3380
+ * it back fails too, that is still the error thrown. An old free-text list
3381
+ * already deleted is not put back.
3382
+ * - An agent already holding the most active memories, none of them ours,
3383
+ * throws POOL_SELECTION_RULE_LIMIT before anything is written.
3384
+ *
3385
+ * Always Base, whichever chain the wallet is connected on.
3386
+ */
3387
+ setPoolSelection(selection: UserPoolSelectionRequest, state?: ConnectionState): Promise<void>;
3388
+ private savePoolPicks;
3389
+ /**
3390
+ * Delete the free-text allow-lists we saved before the managed list existed.
3391
+ * Never throws: a list left behind is caught by the read-back. Logs no
3392
+ * sign-in token.
3393
+ */
3394
+ private deleteLegacyPoolMemories;
3395
+ /**
3396
+ * `<address> (<name>)` for each pick, under the prefix. An unnamed address
3397
+ * has no brackets. No picks names no vault.
3398
+ */
3399
+ private poolMemoryContent;
3400
+ /** Undo a failed save of the managed list. Never throws: the caller reports the save's own failure. */
3401
+ private restorePoolMemory;
3402
+ /**
3403
+ * What the user's Yieldseeker agents currently allow, as `SavedPoolSelection`
3404
+ * pairs: the allowed vault addresses under the provider each belongs to, for
3405
+ * the vaults a new agent can use. An agent with no allow-list adds nothing,
3406
+ * and no pairs at all means every shown vault is on. Reads never create an
3407
+ * agent, and always read Base. A read that fails throws, because "no
3408
+ * allow-list" would wrongly mean "everything".
3409
+ *
3410
+ * An allow-list naming none of the listed vaults (the saved "none", or vaults
3411
+ * Yieldseeker has since stopped listing) leaves the agent nowhere to go, so
3412
+ * it reports none chosen for its asset: a pair with empty `pools` for every
3413
+ * provider listing vaults for it. With no vault listed at all there is
3414
+ * nothing to name that by, and it throws: the rules still restrict the agent.
3415
+ *
3416
+ * `pairs` is accepted for the contract but does not trim the answer: cutting
3417
+ * a real allow-list down to the pairs asked about could leave none, and none
3418
+ * reads as every vault on.
3419
+ */
3420
+ getPoolSelection(state: ConnectionState, _chainId: number, params: {
3421
+ pairs: Array<{
3422
+ protocolId: string;
3423
+ chainId: number;
3424
+ }>;
3425
+ assets: Array<"USDC" | "WETH">;
3426
+ }): Promise<SavedPoolSelection>;
3427
+ /**
3428
+ * The allow-list in the agent's rules: every `allowedVaultAddresses` on an
3429
+ * `ignored_vault` user rule. Undefined when no rule has one, which allows
3430
+ * every vault; an empty list allows none. A response that does not have the
3431
+ * expected shape throws rather than reading as no allow-list.
3432
+ */
3433
+ private readAllowList;
3434
+ private listMemories;
3435
+ /** A memory call for an agent, on Base whichever chain the wallet is on. */
3436
+ private memoryRequest;
3082
3437
  private userKey;
3083
3438
  /** One deposit/withdraw slot: owner, chain and asset. */
3084
3439
  private slotKey;
@@ -3118,23 +3473,81 @@ declare class YieldseekerAgent implements IAgent {
3118
3473
  * highest-priority set of `priorities` (index 0 first). Hinted agentIds are
3119
3474
  * resolved first and a hinted top-priority match ends the search; then other
3120
3475
  * listed agents, at most YIELDSEEKER_WALLET_MATCH_LIMIT wallets in total.
3476
+ * A candidate whose wallet shows it closed (deactivated) never ranks, and its
3477
+ * agentId is added to `closed`.
3121
3478
  */
3122
3479
  private agentWithWallet;
3123
3480
  /**
3124
3481
  * chooseAgent, re-reading a cached list once (bypassing its cache) when the
3125
- * verified agent is missing. A slot still missing after that re-read is
3126
- * remembered for the list cache window, so later reads fail from the cached
3127
- * list without another re-read.
3482
+ * verified agent is missing. Still missing, Yieldseeker may have closed
3483
+ * (deactivated) it: the verified record's agent is reactivated and selected
3484
+ * from a fresh list, by the verified wallet only (never created). A slot
3485
+ * that still fails is remembered with its error for the list cache window,
3486
+ * so later reads fail without another re-read or reactivate. A slot
3487
+ * Yieldseeker will not reopen because of its active-agent limit throws
3488
+ * YIELDSEEKER_SLOT_UNAVAILABLE, here and for the rest of the session, with
3489
+ * no request.
3128
3490
  */
3129
3491
  private chooseAgentRefreshing;
3130
- private isSlotMissing;
3492
+ private throwIfSlotUnavailable;
3493
+ /**
3494
+ * Rethrow the error a slot's lookup failed with while the slot is still
3495
+ * marked, or for the session when Yieldseeker will never reopen its agent.
3496
+ * A remembered rate limit is rethrown with the time left on its marker as
3497
+ * its retry delay (`retryAfterSeconds`): no new attempt is made before then,
3498
+ * so a caller that waits it out retries once instead of every few seconds.
3499
+ */
3500
+ private throwIfSlotMissing;
3501
+ /**
3502
+ * Remember a slot's failed lookup or reactivate for the list-cache window.
3503
+ * A sign-in failure is not remembered (the wallet's rejection,
3504
+ * AGENT_AUTH_FAILED, NOT_CONNECTED): it says nothing about the slot, and
3505
+ * remembered it would refuse the next sign-in, even one the user starts,
3506
+ * with no request for the whole window.
3507
+ */
3508
+ private rememberMissingSlot;
3509
+ /**
3510
+ * Reactivate the slot's verified agent, then read the list bypassing its
3511
+ * cache, with a read sent after the reactivate answered. Concurrent lookups
3512
+ * of one slot share one reopen. Resolves to the fresh list. At the
3513
+ * active-agent limit the slot is recorded unavailable and this throws
3514
+ * YIELDSEEKER_SLOT_UNAVAILABLE.
3515
+ */
3516
+ private reopenAgent;
3517
+ /**
3518
+ * The one way to reactivate a slot's agent, for the slot lookup (reopenAgent)
3519
+ * and the pre-deposit check (assertAgentOpen), so a slot costs at most one
3520
+ * reactivate per list-cache window:
3521
+ * - a slot recorded unavailable (the limit) answers "limit" with no request;
3522
+ * - concurrent callers share one request;
3523
+ * - a failed reactivate (closed code, rate limit, timeout, 5xx...) is
3524
+ * remembered as the slot's failure for the list-cache window (missingSlots)
3525
+ * and rethrown to later callers with no request; a closed code
3526
+ * (closedSlots) for the session; a sign-in failure is not remembered;
3527
+ * - the limit is recorded in unavailableSlots only while the session is
3528
+ * unchanged, so a disconnect during the request is not undone by its late
3529
+ * answer.
3530
+ */
3531
+ private reactivateSlot;
3532
+ /**
3533
+ * Ask Yieldseeker to reopen a closed (deactivated) agent, with the user's
3534
+ * Yieldseeker sign-in. AGENT_NOT_DEACTIVATED (already open, e.g. reopened
3535
+ * by another tab) counts as reopened; the active-agent limit is an outcome,
3536
+ * not an error. An agent that cannot come back throws
3537
+ * YIELDSEEKER_AGENT_CLOSED; any other failure (rate limit, timeout, network,
3538
+ * 5xx, an unknown code) throws the mapped API error.
3539
+ */
3540
+ private reactivateAgent;
3541
+ /** Drop the cached and in-flight wallet contexts of one agent, in every slot. */
3542
+ private forgetAgentWallet;
3131
3543
  /**
3132
3544
  * The agent that serves deposits and withdrawals for a slot (Ruling 23):
3133
3545
  * 1. the listed fitting agent whose wallet is the verified account's wallet,
3134
3546
  * whatever its name; the stored agentId is only a hint;
3135
3547
  * 2. else a listed fitting agent whose wallet is a superseded account's wallet;
3136
3548
  * 3. else the fitting agent named "owney" (first use, migration, or a
3137
- * verified wallet that is not a fitting listed agent);
3549
+ * verified wallet that is not a fitting listed agent), unless step 1/2
3550
+ * read its wallet and it is closed (deactivated): that agent is not listed;
3138
3551
  * 4. else, with a verified account, throw YIELDSEEKER_AGENT_MISSING (never
3139
3552
  * create); without one, undefined (the caller may create).
3140
3553
  * Steps 1 and 2 share one search of at most YIELDSEEKER_WALLET_MATCH_LIMIT
@@ -3144,6 +3557,19 @@ declare class YieldseekerAgent implements IAgent {
3144
3557
  private chooseAgent;
3145
3558
  private isAgentMissing;
3146
3559
  private agentMissing;
3560
+ private slotUnavailable;
3561
+ /** The slot has no usable agent: missing, at Yieldseeker's agent limit, or closed for good. */
3562
+ private isSlotEmpty;
3563
+ /**
3564
+ * The slot's lookup failed through the missing-agent / reopen path and was
3565
+ * remembered with this very error, even a transient one (429, 5xx, timeout),
3566
+ * or with the copy of it a remembered rate limit is rethrown as. Compares
3567
+ * the remembered error, not its expiry, so it holds however long the rest
3568
+ * of the read takes.
3569
+ */
3570
+ private isMarkedSlotFailure;
3571
+ /** providerCode is absent when Yieldseeker named none (the agent stayed closed after a reopen). */
3572
+ private agentClosed;
3147
3573
  /**
3148
3574
  * Fire-and-forget: record which agent serves this slot. Never awaited on the
3149
3575
  * funds path and never throws; once per agent wallet and deployment state
@@ -3248,6 +3674,14 @@ declare class YieldseekerAgent implements IAgent {
3248
3674
  private agentPath;
3249
3675
  private walletRequest;
3250
3676
  private providerRequest;
3677
+ /**
3678
+ * mapApiError for a request that may have opened the Yieldseeker sign-in
3679
+ * prompt (providerRequest signs when no sign-in is saved, and again when
3680
+ * Yieldseeker refuses one). The wallet's rejection, the user cancelling that
3681
+ * prompt, is returned unchanged: the client and the app must see the user's
3682
+ * cancel (no further prompt, no retry), never a provider failure.
3683
+ */
3684
+ private mapRequestFailure;
3251
3685
  private mapApiError;
3252
3686
  private submitTransaction;
3253
3687
  private waitForReceipt;
@@ -3303,6 +3737,23 @@ type OwneySIWXConfig = {
3303
3737
  */
3304
3738
  declare function createOwneySIWX(config: OwneySIWXConfig): SIWXConfig;
3305
3739
 
3740
+ /**
3741
+ * Ask the wallet ITSELF to switch networks, over WalletConnect.
3742
+ *
3743
+ * WalletConnect's provider answers `wallet_switchEthereumChain` locally when
3744
+ * the chain was approved at connect time: it moves its own default chain and
3745
+ * reports success without telling the wallet. MetaMask mobile then stays on
3746
+ * its network, keeps reporting it, and every guard downstream fails with
3747
+ * CHAIN_MISMATCH — after a swap, with the user's funds already moved (ROUT-727).
3748
+ * Sending the request through the session client reaches the wallet, which
3749
+ * shows a real "switch network" prompt; the client also deep-links the wallet
3750
+ * app open on mobile.
3751
+ *
3752
+ * Returns false when `provider` is not a WalletConnect session, so the caller
3753
+ * can fall back to an ordinary switch.
3754
+ */
3755
+ declare function switchWalletConnectChain(provider: unknown, chainId: number, timeoutMs?: number): Promise<boolean>;
3756
+
3306
3757
  /**
3307
3758
  * Persists cross-chain swap secrets so an in-flight order survives a reload.
3308
3759
  *
@@ -3434,4 +3885,4 @@ declare const YIELDSEEKER_WITHDRAW_SERVER_SUBMIT: 1;
3434
3885
  * Older builds do not export this. */
3435
3886
  declare const FUNDING_DEPOSIT_RECOVERY_REPORT: 1;
3436
3887
 
3437
- export { type AccountAgentApy, type AccountApyOptions, type AccountDailyEarnings, type AgentApy, type AgentApyDetails, type AgentBalance, AgentChainIncompatibleError, type AgentEarnings, type AgentFundingLedgerAccess, type AgentHistoryEntry, type AgentHistoryPosition, type AgentId, AgentNotFoundError, type AgentSupportedAsset, type AgentSupportedAssets, type AgentUserProfile, type AgentWithdrawResult, type AgentsApyOptions, type AllocationAgentApy, type AllocationApyOptions, type ApyByChainAndAsset, type ApyCoverage, type ApyHistoryPoint, type Asset, type AssetDailyEarnings, type AssetReadMetadata, type AvailableAgent, type AvailableAgentsOptions, type AvailablePool, type ConnectionState, type DailyApyDays, type DailyEarningsOptions, type DailyEarningsPoint, type DepositAuthorizationReference, type DepositCallback, type DepositOptions, type DepositReplacementValidation, FUNDING_DEPOSIT_RECOVERY_REPORT, FUSION_SECRET_SERVER_PUBLISH, type FundingEvidence, type FundingOperationKind, type FundingOperationLeg, type FundingOperationRow, type FundingProgress, type FundingStage, type HistoryAction, type HistoryFilters, type HistoryOptions, type HistoryTransaction, type IAgent, InvalidHistoryCursorError, type LedgerLegReport, type LookbackDays, NotConnectedError, type OrgPoolPolicy, type OrgPoolSelection, type OwneyAccountApy, type OwneyAgentApy, type OwneyAgentHistory, type OwneyAllocationApy, type OwneyBalances, type OwneyDepositResult, type OwneyEarnings, OwneyError, type OwneyErrorCode, type OwneyMultiDepositResult, type OwneyPosition, OwneySDK, type OwneySDKConfig, type OwneySIWXConfig, type OwneySupportedChainId, type OwneySupportedChains, type OwneySupportedTokens, type OwneyToken, type OwneyUserProfile, type OwneyWithdrawAllLeg, type OwneyWithdrawAllResult, type OwneyWithdrawResult, type PendingDeposit, type PoolCatalogProtocol, type PoolSelectionStrategy, type ProviderSnapshotSample, type RebalanceLog, type ReservationAgent, type ReservationReleaseReason, type RpcUrlsConfig, SDK_VERSION, SPONSORED_DEPOSIT_SERVER_BROADCAST, type SavedPoolSelection, type SwapChainTokens, type SwapDirection, type SwapOrderStatus, type SwapQuote, type SwapQuoteParams, type SwapRail, type SwapStage, type SwapTokenInfo, type SwapTokenSearchResult, type UnsignedUserOperationEvidence, type UserPoolSelection, type UserPoolSelectionRequest, type WithdrawOptions, type WithdrawSwapRecord, type WithdrawSwapStatus, type WithdrawalCompletion, type WithdrawalCompletionContext, type WithdrawalPayoutCandidate, type WithdrawalPayoutScan, type WithdrawalReservationConflict, type WithdrawalReservationMode, type WithdrawalReservationOptions, type WithdrawalSwapRecovery, YIELDSEEKER_WITHDRAW_SERVER_SUBMIT, YieldseekerAgent, type YieldseekerWalletStatus, ZYFAI_REGISTRATION_NOT_SENT_CODES, ZYFAI_SERVER_TASKS, ZYFAI_WITHDRAWAL_NOT_SENT_CODES, ZYFAI_WITHDRAW_DISPATCH_CHECKPOINT, type ZyfaiDepositPlacement, type ZyfaiRpcUrlsConfig, type ZyfaiWithdrawalLifecycle, clearWithdrawSwap, createOwneySIWX, listPendingDeposits, listOrders as listPendingSwaps, listWithdrawSwaps, saveWithdrawSwap, setOwneyDebug, subscribeWithdrawSwaps, updateWithdrawSwap };
3888
+ export { type AccountAgentApy, type AccountApyOptions, type AccountDailyEarnings, type ActivateAgentOptions, type AgentApy, type AgentApyDetails, type AgentBalance, AgentChainIncompatibleError, type AgentEarnings, type AgentFundingLedgerAccess, type AgentHistoryEntry, type AgentHistoryPosition, type AgentId, AgentNotFoundError, type AgentSupportedAsset, type AgentSupportedAssets, type AgentUserProfile, type AgentWithdrawResult, type AgentsApyOptions, type AllocationAgentApy, type AllocationApyOptions, type ApyByChainAndAsset, type ApyCoverage, type ApyHistoryPoint, type ApyIncentive, type Asset, type AssetDailyEarnings, type AssetReadMetadata, type AvailableAgent, type AvailableAgentsOptions, type AvailablePool, type ConnectionState, type DailyApyDays, type DailyEarningsOptions, type DailyEarningsPoint, type DepositAuthorizationReference, type DepositCallback, type DepositOptions, type DepositReplacementValidation, FUNDING_DEPOSIT_RECOVERY_REPORT, FUSION_SECRET_SERVER_PUBLISH, type FundingEvidence, type FundingOperationKind, type FundingOperationLeg, type FundingOperationRow, type FundingProgress, type FundingStage, type HistoryAction, type HistoryFilters, type HistoryOptions, type HistoryTransaction, type IAgent, InvalidHistoryCursorError, type LedgerLegReport, type LookbackDays, NotConnectedError, type OrgPoolPolicy, type OrgPoolSelection, type OwneyAccountApy, type OwneyAgentApy, type OwneyAgentHistory, type OwneyAllocationApy, type OwneyBalances, type OwneyDepositResult, type OwneyEarnings, OwneyError, type OwneyErrorCode, type OwneyMultiDepositResult, type OwneyPosition, OwneySDK, type OwneySDKConfig, type OwneySIWXConfig, type OwneySupportedChainId, type OwneySupportedChains, type OwneySupportedTokens, type OwneyToken, type OwneyUserProfile, type OwneyWithdrawAllLeg, type OwneyWithdrawAllResult, type OwneyWithdrawResult, type PendingDeposit, type PoolCatalogProtocol, type PoolSelectionStrategy, type ProviderSnapshotSample, type RebalanceLog, type ReservationAgent, type ReservationReleaseReason, type RpcUrlsConfig, SDK_VERSION, SPONSORED_DEPOSIT_SERVER_BROADCAST, type SavedPoolSelection, type SwapChainTokens, type SwapDirection, type SwapOrderStatus, type SwapQuote, type SwapQuoteParams, type SwapRail, type SwapStage, type SwapTokenInfo, type SwapTokenSearchResult, type UnsignedUserOperationEvidence, type UserPoolSelection, type UserPoolSelectionRequest, type WithdrawOptions, type WithdrawSwapRecord, type WithdrawSwapStatus, type WithdrawalCompletion, type WithdrawalCompletionContext, type WithdrawalPayoutCandidate, type WithdrawalPayoutScan, type WithdrawalReservationConflict, type WithdrawalReservationMode, type WithdrawalReservationOptions, type WithdrawalSwapRecovery, YIELDSEEKER_WITHDRAW_SERVER_SUBMIT, YieldseekerAgent, type YieldseekerWalletStatus, ZYFAI_REGISTRATION_NOT_SENT_CODES, ZYFAI_SERVER_TASKS, ZYFAI_WITHDRAWAL_NOT_SENT_CODES, ZYFAI_WITHDRAW_DISPATCH_CHECKPOINT, type ZyfaiDepositPlacement, type ZyfaiRpcUrlsConfig, type ZyfaiWithdrawalLifecycle, clearWithdrawSwap, createOwneySIWX, listPendingDeposits, listOrders as listPendingSwaps, listWithdrawSwaps, saveWithdrawSwap, setOwneyDebug, subscribeWithdrawSwaps, switchWalletConnectChain, updateWithdrawSwap };