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

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