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

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.cts CHANGED
@@ -586,13 +586,12 @@ type UserPoolSelection = {
586
586
  /**
587
587
  * The complete saved draft for the asset/chain legs selected in the deposit.
588
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.
589
+ * Every agent keeps at least one pool (2026-11-11): a request whose every
590
+ * entry for an asset and chain has empty `pools` (with pools shown) is
591
+ * refused with POOL_SELECTION_REQUIRED before anything is written, unless
592
+ * (Zyfai) a protocol the request does not touch keeps a pool there. A "none
593
+ * chosen" saved before that rule is still read back as none. Entries that
594
+ * showed nothing (`availablePools` empty) change nothing.
596
595
  */
597
596
  type UserPoolSelectionRequest = {
598
597
  strategies: Array<{
@@ -651,12 +650,22 @@ type AgentFundingLedgerAccess = {
651
650
  before: Date;
652
651
  }): Promise<ProviderSnapshotSample | null>;
653
652
  };
654
- /** What an agent did with a confirmed-deposit notice (`IAgent.depositConfirmed`). */
653
+ /**
654
+ * What an agent did with a confirmed-deposit notice (`IAgent.depositConfirmed`).
655
+ * `attempts` counts the provider calls made. `allocated` is set when the agent
656
+ * checked whether the deposit was put to work; `allocatesAfter` (ISO) is when
657
+ * the provider will act on it at the earliest, when it said so.
658
+ */
655
659
  type DepositNotice = {
656
660
  notified: true;
661
+ attempts?: number;
662
+ allocated?: boolean;
663
+ reason?: string;
664
+ allocatesAfter?: string;
657
665
  } | {
658
666
  notified: false;
659
667
  reason: string;
668
+ attempts?: number;
660
669
  };
661
670
  interface IAgent {
662
671
  readonly id: string;
@@ -742,7 +751,11 @@ interface IAgent {
742
751
  /**
743
752
  * Apply a user's own pool selection to their account, driven by the
744
753
  * deposit-time Pools step. Optional. A failure throws, and the caller
745
- * must not start the deposit.
754
+ * must not start the deposit. A save must also reach money already
755
+ * invested: Zyfai rebalances on its own, Yieldseeker is told with
756
+ * `deposit-made`. Every agent keeps at least one pool: a selection that
757
+ * would leave the agent with no pool for an asset on a chain it offers pools
758
+ * for throws POOL_SELECTION_REQUIRED before anything is written.
746
759
  * `state` is the client's connection, or undefined when there is none; an
747
760
  * agent that signs in per call (Yieldseeker) needs it, and one that is
748
761
  * already connected (Zyfai) ignores it. (ROUT-569)
@@ -786,8 +799,12 @@ interface IAgent {
786
799
  * instead of waiting for its next scheduled check). The client calls it once
787
800
  * per confirmed transfer, in the background: it must never prompt the wallet
788
801
  * and never throw. Agents without it rely on their provider's own discovery.
802
+ * An agent that calls its provider more than once, or checks the outcome,
803
+ * reports each call through `onNotice` and resolves with the final outcome.
789
804
  */
790
- depositConfirmed?(state: ConnectionState, chainId: number, evidence: FundingEvidence): Promise<DepositNotice>;
805
+ depositConfirmed?(state: ConnectionState, chainId: number, evidence: FundingEvidence, onNotice?: (notice: DepositNotice & {
806
+ attempt: number;
807
+ }) => void): Promise<DepositNotice>;
791
808
  /** Invalidate only the confirmed asset. This hook must not sign or submit transactions. */
792
809
  invalidateFundingRead?(state: ConnectionState, chainId: number, asset: OwneySupportedTokens, refreshUntil?: number, txHash?: string): void;
793
810
  /** End accelerated balance reads only for the exact snapshot the caller displayed. */
@@ -815,6 +832,11 @@ interface IAgent {
815
832
  getEarnings(state: ConnectionState, chainId: number): Promise<AgentEarnings>;
816
833
  /** Funding-ledger read access for earnings holds. Optional; without it an agent behaves as before. */
817
834
  setFundingLedgerAccess?(access: AgentFundingLedgerAccess | undefined): void;
835
+ /**
836
+ * Called each time the agent maps a provider refusal for a wallet whose
837
+ * account was not created through Owney (AGENT_ACCOUNT_NOT_OWNEY). Optional.
838
+ */
839
+ setAccountRefusedListener?(listener: (() => void) | undefined): void;
818
840
  /**
819
841
  * A small, never-prompting read of the provider's earnings bookkeeping for a
820
842
  * `provider.sample` ledger event (Zyfai). Null when unavailable; never throws.
@@ -1772,7 +1794,7 @@ type WithdrawalPayoutScan = {
1772
1794
  caughtUp: boolean;
1773
1795
  };
1774
1796
 
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";
1797
+ 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" | "AGENT_ACCOUNT_NOT_OWNEY" | "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" | "POOL_SELECTION_REQUIRED" | "VALIDATION_INVALID_DAYS";
1776
1798
  declare class OwneyError extends Error {
1777
1799
  readonly code: OwneyErrorCode;
1778
1800
  readonly details?: Record<string, unknown>;
@@ -1943,6 +1965,7 @@ declare class OwneySDK {
1943
1965
  * withdraw, but they are excluded from new deposits / activations.
1944
1966
  */
1945
1967
  private disabledAgents;
1968
+ private readonly accountRefusedListeners;
1946
1969
  /**
1947
1970
  * Agents whose sign-in the user cancelled this session (the wallet rejected
1948
1971
  * the prompt), keyed by chain. Until the app ends the session they are read
@@ -2036,6 +2059,14 @@ declare class OwneySDK {
2036
2059
  * a later sample is skipped once the wallet disconnects or changes.
2037
2060
  */
2038
2061
  private ledgerProviderSamples;
2062
+ /**
2063
+ * Listens for an agent refusing the connected wallet because its provider
2064
+ * account was not created through Owney (`AGENT_ACCOUNT_NOT_OWNEY`). Fires
2065
+ * each time an agent maps such a refusal. Returns the unsubscribe function.
2066
+ */
2067
+ onAccountRefused(listener: (agentId: AgentId) => void): () => void;
2068
+ /** Wires the optional hooks the SDK offers an agent. */
2069
+ private attachAgentHooks;
2039
2070
  /**
2040
2071
  * Funding-ledger read access handed to agents for earnings holds. Reads only
2041
2072
  * for the connected owner; null otherwise and on any failure.
@@ -2321,6 +2352,11 @@ declare class OwneySDK {
2321
2352
  * deposit's ledger operation when there is one. In the background: never
2322
2353
  * throws and never delays the deposit. A missed notice only leaves the
2323
2354
  * provider on its own schedule.
2355
+ *
2356
+ * An agent that reports its provider calls (`onNotice`) gets one
2357
+ * `provider.deposit_notified` event per call and a final
2358
+ * `provider.deposit_allocation` with the outcome (allocated or why not).
2359
+ * Otherwise the outcome is the one `provider.deposit_notified`.
2324
2360
  */
2325
2361
  private announceDepositConfirmed;
2326
2362
  private noteFundingRefresh;
@@ -3171,6 +3207,7 @@ declare class YieldseekerAgent implements IAgent {
3171
3207
  private readonly agentContexts;
3172
3208
  private readonly walletContexts;
3173
3209
  private readonly agentAccountReads;
3210
+ private readonly sessionAgents;
3174
3211
  private readonly reportedAccounts;
3175
3212
  private readonly missingSlots;
3176
3213
  private readonly rethrownSlotFailures;
@@ -3204,6 +3241,7 @@ declare class YieldseekerAgent implements IAgent {
3204
3241
  private readonly movementEpochs;
3205
3242
  private readonly settlementChecks;
3206
3243
  private ledgerAccess?;
3244
+ private accountRefusedListener?;
3207
3245
  private readonly ledgerReads;
3208
3246
  /** contextKey -> movements this instance started settling (by tx hash) and how they refresh:
3209
3247
  * awaiting the ledger, refreshed when ready (ledger), or on the timed backoff (legacy). */
@@ -3242,8 +3280,9 @@ declare class YieldseekerAgent implements IAgent {
3242
3280
  * - closed (`deactivatedDate` set): reactivates it, re-reads the wallet, and
3243
3281
  * continues only when it is now open with the same address. Only the
3244
3282
  * 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;
3283
+ * superseded-wallet match, or the agent this session created or adopted
3284
+ * before its record exists, also when the accounts could not be read)
3285
+ * refuses without a request;
3247
3286
  * - anything else refuses with nothing sent, before any progress event,
3248
3287
  * signature or callback. Every refusal carries `notSubmitted` and
3249
3288
  * `safeToFallback: false`, so no paid fallback runs.
@@ -3317,13 +3356,47 @@ declare class YieldseekerAgent implements IAgent {
3317
3356
  endFundingBalanceRefresh(state: ConnectionState, chainId: number, asset: OwneySupportedTokens, read: AssetReadMetadata): boolean;
3318
3357
  /**
3319
3358
  * 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>;
3359
+ * it now instead of on its next 30-minute check, and confirms it did.
3360
+ * Yieldseeker decides whether anything moves (the funding minimum, a
3361
+ * deployed agent, no manual withdrawal in the last hour), and its answer
3362
+ * (`{}`) does not say, so a minute after each notice the agent reads its
3363
+ * wallet: the deposit has gone into a vault when less than its amount is
3364
+ * left idle. While it has not, Yieldseeker is told again, up to
3365
+ * DEPOSIT_NOTICE_ATTEMPTS calls in all; a failed call (network, server, rate
3366
+ * limit) is sent again after a wait. Within an hour of a withdrawal it is
3367
+ * told once, since nothing can move yet. Uses the agent this session already
3368
+ * knows for the asset and the saved sign-in only: never prompts, never
3369
+ * throws. Each call is reported through `onNotice`.
3370
+ */
3371
+ depositConfirmed(state: ConnectionState, chainId: number, evidence: FundingEvidence, onNotice?: (notice: DepositNotice & {
3372
+ attempt: number;
3373
+ }) => void): Promise<DepositNotice>;
3374
+ /** One `deposit-made` call. A failure that may pass on its own carries the wait before the next try. */
3375
+ private sendDepositNotice;
3376
+ /**
3377
+ * Tells Yieldseeker (`deposit-made`) after a pool save, so the agent runs
3378
+ * now and rebalances money already in a vault the list no longer allows.
3379
+ * Up to DEPOSIT_NOTICE_ATTEMPTS calls in all, waiting between them only
3380
+ * after a failure that may pass; stops when the session ends. Never throws.
3381
+ */
3382
+ private rebalanceAfterPoolSave;
3383
+ /**
3384
+ * When Yieldseeker may move funds again after this agent wallet's last
3385
+ * confirmed withdrawal, if that is still ahead; null when there was none in
3386
+ * the last hour or the ledger cannot say.
3387
+ */
3388
+ private withdrawalCooldownEnd;
3389
+ /**
3390
+ * The agent wallet's base-asset balance and the platform fee Yieldseeker has
3391
+ * not collected from it, read at one block for a balance read. Cached
3392
+ * briefly per agent wallet and dropped by funding and allocation
3393
+ * invalidations. Null when any read fails or is slow: the snapshot's
3394
+ * amounts are used instead.
3395
+ */
3396
+ private readLiveWallet;
3397
+ private readWalletFunds;
3398
+ /** The agent wallet's idle base asset; null when the read fails. */
3399
+ private readIdleBalance;
3327
3400
  getFundingWallet(state: ConnectionState, chainId: number, asset: OwneySupportedTokens): Promise<string>;
3328
3401
  hasExistingDepositFunds(state: ConnectionState, chainId: number, asset: OwneySupportedTokens): Promise<true | undefined>;
3329
3402
  getEarnings(state: ConnectionState, chainId: number): Promise<AgentEarnings>;
@@ -3363,13 +3436,11 @@ declare class YieldseekerAgent implements IAgent {
3363
3436
  *
3364
3437
  * - Only Base entries are ours. An asset with no picks whose entries showed
3365
3438
  * no vault is skipped and nothing is sent.
3439
+ * - None picked (vaults shown) for any asset: every agent keeps at least one
3440
+ * pool (2026-11-11), so the whole save throws POOL_SELECTION_REQUIRED
3441
+ * before anything is written, for any asset.
3366
3442
  * - Some vaults picked: the managed list names them. Saving it again
3367
3443
  * 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
3444
  * - Every vault picked: the managed list is deleted, and no allow-list may
3374
3445
  * remain, so vaults Yieldseeker adds later are allowed too.
3375
3446
  * - A free-text allow-list we saved before the managed list existed is
@@ -3394,7 +3465,8 @@ declare class YieldseekerAgent implements IAgent {
3394
3465
  private deleteLegacyPoolMemories;
3395
3466
  /**
3396
3467
  * `<address> (<name>)` for each pick, under the prefix. An unnamed address
3397
- * has no brackets. No picks names no vault.
3468
+ * has no brackets. There is always at least one pick (setPoolSelection
3469
+ * refuses a save with none).
3398
3470
  */
3399
3471
  private poolMemoryContent;
3400
3472
  /** Undo a failed save of the managed list. Never throws: the caller reports the save's own failure. */
@@ -3461,8 +3533,9 @@ declare class YieldseekerAgent implements IAgent {
3461
3533
  private listAgents;
3462
3534
  /**
3463
3535
  * The routing API's stored accounts for owner+chain, read once per session.
3464
- * Resolves null when unavailable (callers keep name matching) and never
3465
- * rejects. A failure is retried after a short window.
3536
+ * Resolves null when unavailable and never rejects; callers then refuse
3537
+ * (AGENT_ACCOUNTS_UNAVAILABLE) and create nothing. A failure is not kept:
3538
+ * concurrent callers share the in-flight read, and the next call reads again.
3466
3539
  */
3467
3540
  private agentAccounts;
3468
3541
  /** Yieldseeker accounts for one slot (returned addresses are compared lowercase). */
@@ -3545,11 +3618,15 @@ declare class YieldseekerAgent implements IAgent {
3545
3618
  * 1. the listed fitting agent whose wallet is the verified account's wallet,
3546
3619
  * whatever its name; the stored agentId is only a hint;
3547
3620
  * 2. else a listed fitting agent whose wallet is a superseded account's wallet;
3548
- * 3. else the fitting agent named "owney" (first use, migration, or a
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;
3551
- * 4. else, with a verified account, throw YIELDSEEKER_AGENT_MISSING (never
3552
- * create); without one, undefined (the caller may create).
3621
+ * 3. else, with a verified account, throw YIELDSEEKER_AGENT_MISSING (never
3622
+ * create);
3623
+ * 4. else, with no record at all, the listed agent this session created or
3624
+ * adopted for the slot (sessionAgents); without one, undefined (the
3625
+ * caller creates an agent named "owney"). An agent is never picked by
3626
+ * its name: only our records, and this session's own create, say which
3627
+ * agents are Owney's.
3628
+ * Without the account records (`null`: the read failed) nothing can be
3629
+ * known, so the call is refused and nothing is created.
3553
3630
  * Steps 1 and 2 share one search of at most YIELDSEEKER_WALLET_MATCH_LIMIT
3554
3631
  * wallet reads. The account report then records the selected wallet; the
3555
3632
  * server marks it superseded when it differs from the verified wallet.
@@ -3582,7 +3659,12 @@ declare class YieldseekerAgent implements IAgent {
3582
3659
  private ensureAgent;
3583
3660
  private findAgent;
3584
3661
  private resolveAgent;
3585
- /** Create the slot's agent. Only reached when no stored or named agent matched. */
3662
+ /**
3663
+ * Create the slot's agent, named "owney". Only reached when the slot has no
3664
+ * account record and no agent this session made; the created agent is
3665
+ * remembered for the session (sessionAgents) so reads select it before its
3666
+ * record exists.
3667
+ */
3586
3668
  private createAgent;
3587
3669
  /**
3588
3670
  * The routing create lock refused the create: another tab or app owns or is
@@ -3618,6 +3700,7 @@ declare class YieldseekerAgent implements IAgent {
3618
3700
  private loadActivityContext;
3619
3701
  private loadPortfolioParts;
3620
3702
  private deployAgent;
3703
+ setAccountRefusedListener(listener: (() => void) | undefined): void;
3621
3704
  setFundingLedgerAccess(access: AgentFundingLedgerAccess | undefined): void;
3622
3705
  private historyKey;
3623
3706
  /** Funding-ledger rows for this slot, cached 15 s. Never throws: null on any failure. */
@@ -3687,7 +3770,6 @@ declare class YieldseekerAgent implements IAgent {
3687
3770
  private waitForReceipt;
3688
3771
  private assertTransaction;
3689
3772
  private assertAgent;
3690
- private isOwneyAgent;
3691
3773
  private assetForAgent;
3692
3774
  private isTransactionHash;
3693
3775
  private assertChain;
package/dist/index.d.ts CHANGED
@@ -586,13 +586,12 @@ type UserPoolSelection = {
586
586
  /**
587
587
  * The complete saved draft for the asset/chain legs selected in the deposit.
588
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.
589
+ * Every agent keeps at least one pool (2026-11-11): a request whose every
590
+ * entry for an asset and chain has empty `pools` (with pools shown) is
591
+ * refused with POOL_SELECTION_REQUIRED before anything is written, unless
592
+ * (Zyfai) a protocol the request does not touch keeps a pool there. A "none
593
+ * chosen" saved before that rule is still read back as none. Entries that
594
+ * showed nothing (`availablePools` empty) change nothing.
596
595
  */
597
596
  type UserPoolSelectionRequest = {
598
597
  strategies: Array<{
@@ -651,12 +650,22 @@ type AgentFundingLedgerAccess = {
651
650
  before: Date;
652
651
  }): Promise<ProviderSnapshotSample | null>;
653
652
  };
654
- /** What an agent did with a confirmed-deposit notice (`IAgent.depositConfirmed`). */
653
+ /**
654
+ * What an agent did with a confirmed-deposit notice (`IAgent.depositConfirmed`).
655
+ * `attempts` counts the provider calls made. `allocated` is set when the agent
656
+ * checked whether the deposit was put to work; `allocatesAfter` (ISO) is when
657
+ * the provider will act on it at the earliest, when it said so.
658
+ */
655
659
  type DepositNotice = {
656
660
  notified: true;
661
+ attempts?: number;
662
+ allocated?: boolean;
663
+ reason?: string;
664
+ allocatesAfter?: string;
657
665
  } | {
658
666
  notified: false;
659
667
  reason: string;
668
+ attempts?: number;
660
669
  };
661
670
  interface IAgent {
662
671
  readonly id: string;
@@ -742,7 +751,11 @@ interface IAgent {
742
751
  /**
743
752
  * Apply a user's own pool selection to their account, driven by the
744
753
  * deposit-time Pools step. Optional. A failure throws, and the caller
745
- * must not start the deposit.
754
+ * must not start the deposit. A save must also reach money already
755
+ * invested: Zyfai rebalances on its own, Yieldseeker is told with
756
+ * `deposit-made`. Every agent keeps at least one pool: a selection that
757
+ * would leave the agent with no pool for an asset on a chain it offers pools
758
+ * for throws POOL_SELECTION_REQUIRED before anything is written.
746
759
  * `state` is the client's connection, or undefined when there is none; an
747
760
  * agent that signs in per call (Yieldseeker) needs it, and one that is
748
761
  * already connected (Zyfai) ignores it. (ROUT-569)
@@ -786,8 +799,12 @@ interface IAgent {
786
799
  * instead of waiting for its next scheduled check). The client calls it once
787
800
  * per confirmed transfer, in the background: it must never prompt the wallet
788
801
  * and never throw. Agents without it rely on their provider's own discovery.
802
+ * An agent that calls its provider more than once, or checks the outcome,
803
+ * reports each call through `onNotice` and resolves with the final outcome.
789
804
  */
790
- depositConfirmed?(state: ConnectionState, chainId: number, evidence: FundingEvidence): Promise<DepositNotice>;
805
+ depositConfirmed?(state: ConnectionState, chainId: number, evidence: FundingEvidence, onNotice?: (notice: DepositNotice & {
806
+ attempt: number;
807
+ }) => void): Promise<DepositNotice>;
791
808
  /** Invalidate only the confirmed asset. This hook must not sign or submit transactions. */
792
809
  invalidateFundingRead?(state: ConnectionState, chainId: number, asset: OwneySupportedTokens, refreshUntil?: number, txHash?: string): void;
793
810
  /** End accelerated balance reads only for the exact snapshot the caller displayed. */
@@ -815,6 +832,11 @@ interface IAgent {
815
832
  getEarnings(state: ConnectionState, chainId: number): Promise<AgentEarnings>;
816
833
  /** Funding-ledger read access for earnings holds. Optional; without it an agent behaves as before. */
817
834
  setFundingLedgerAccess?(access: AgentFundingLedgerAccess | undefined): void;
835
+ /**
836
+ * Called each time the agent maps a provider refusal for a wallet whose
837
+ * account was not created through Owney (AGENT_ACCOUNT_NOT_OWNEY). Optional.
838
+ */
839
+ setAccountRefusedListener?(listener: (() => void) | undefined): void;
818
840
  /**
819
841
  * A small, never-prompting read of the provider's earnings bookkeeping for a
820
842
  * `provider.sample` ledger event (Zyfai). Null when unavailable; never throws.
@@ -1772,7 +1794,7 @@ type WithdrawalPayoutScan = {
1772
1794
  caughtUp: boolean;
1773
1795
  };
1774
1796
 
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";
1797
+ 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" | "AGENT_ACCOUNT_NOT_OWNEY" | "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" | "POOL_SELECTION_REQUIRED" | "VALIDATION_INVALID_DAYS";
1776
1798
  declare class OwneyError extends Error {
1777
1799
  readonly code: OwneyErrorCode;
1778
1800
  readonly details?: Record<string, unknown>;
@@ -1943,6 +1965,7 @@ declare class OwneySDK {
1943
1965
  * withdraw, but they are excluded from new deposits / activations.
1944
1966
  */
1945
1967
  private disabledAgents;
1968
+ private readonly accountRefusedListeners;
1946
1969
  /**
1947
1970
  * Agents whose sign-in the user cancelled this session (the wallet rejected
1948
1971
  * the prompt), keyed by chain. Until the app ends the session they are read
@@ -2036,6 +2059,14 @@ declare class OwneySDK {
2036
2059
  * a later sample is skipped once the wallet disconnects or changes.
2037
2060
  */
2038
2061
  private ledgerProviderSamples;
2062
+ /**
2063
+ * Listens for an agent refusing the connected wallet because its provider
2064
+ * account was not created through Owney (`AGENT_ACCOUNT_NOT_OWNEY`). Fires
2065
+ * each time an agent maps such a refusal. Returns the unsubscribe function.
2066
+ */
2067
+ onAccountRefused(listener: (agentId: AgentId) => void): () => void;
2068
+ /** Wires the optional hooks the SDK offers an agent. */
2069
+ private attachAgentHooks;
2039
2070
  /**
2040
2071
  * Funding-ledger read access handed to agents for earnings holds. Reads only
2041
2072
  * for the connected owner; null otherwise and on any failure.
@@ -2321,6 +2352,11 @@ declare class OwneySDK {
2321
2352
  * deposit's ledger operation when there is one. In the background: never
2322
2353
  * throws and never delays the deposit. A missed notice only leaves the
2323
2354
  * provider on its own schedule.
2355
+ *
2356
+ * An agent that reports its provider calls (`onNotice`) gets one
2357
+ * `provider.deposit_notified` event per call and a final
2358
+ * `provider.deposit_allocation` with the outcome (allocated or why not).
2359
+ * Otherwise the outcome is the one `provider.deposit_notified`.
2324
2360
  */
2325
2361
  private announceDepositConfirmed;
2326
2362
  private noteFundingRefresh;
@@ -3171,6 +3207,7 @@ declare class YieldseekerAgent implements IAgent {
3171
3207
  private readonly agentContexts;
3172
3208
  private readonly walletContexts;
3173
3209
  private readonly agentAccountReads;
3210
+ private readonly sessionAgents;
3174
3211
  private readonly reportedAccounts;
3175
3212
  private readonly missingSlots;
3176
3213
  private readonly rethrownSlotFailures;
@@ -3204,6 +3241,7 @@ declare class YieldseekerAgent implements IAgent {
3204
3241
  private readonly movementEpochs;
3205
3242
  private readonly settlementChecks;
3206
3243
  private ledgerAccess?;
3244
+ private accountRefusedListener?;
3207
3245
  private readonly ledgerReads;
3208
3246
  /** contextKey -> movements this instance started settling (by tx hash) and how they refresh:
3209
3247
  * awaiting the ledger, refreshed when ready (ledger), or on the timed backoff (legacy). */
@@ -3242,8 +3280,9 @@ declare class YieldseekerAgent implements IAgent {
3242
3280
  * - closed (`deactivatedDate` set): reactivates it, re-reads the wallet, and
3243
3281
  * continues only when it is now open with the same address. Only the
3244
3282
  * 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;
3283
+ * superseded-wallet match, or the agent this session created or adopted
3284
+ * before its record exists, also when the accounts could not be read)
3285
+ * refuses without a request;
3247
3286
  * - anything else refuses with nothing sent, before any progress event,
3248
3287
  * signature or callback. Every refusal carries `notSubmitted` and
3249
3288
  * `safeToFallback: false`, so no paid fallback runs.
@@ -3317,13 +3356,47 @@ declare class YieldseekerAgent implements IAgent {
3317
3356
  endFundingBalanceRefresh(state: ConnectionState, chainId: number, asset: OwneySupportedTokens, read: AssetReadMetadata): boolean;
3318
3357
  /**
3319
3358
  * 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>;
3359
+ * it now instead of on its next 30-minute check, and confirms it did.
3360
+ * Yieldseeker decides whether anything moves (the funding minimum, a
3361
+ * deployed agent, no manual withdrawal in the last hour), and its answer
3362
+ * (`{}`) does not say, so a minute after each notice the agent reads its
3363
+ * wallet: the deposit has gone into a vault when less than its amount is
3364
+ * left idle. While it has not, Yieldseeker is told again, up to
3365
+ * DEPOSIT_NOTICE_ATTEMPTS calls in all; a failed call (network, server, rate
3366
+ * limit) is sent again after a wait. Within an hour of a withdrawal it is
3367
+ * told once, since nothing can move yet. Uses the agent this session already
3368
+ * knows for the asset and the saved sign-in only: never prompts, never
3369
+ * throws. Each call is reported through `onNotice`.
3370
+ */
3371
+ depositConfirmed(state: ConnectionState, chainId: number, evidence: FundingEvidence, onNotice?: (notice: DepositNotice & {
3372
+ attempt: number;
3373
+ }) => void): Promise<DepositNotice>;
3374
+ /** One `deposit-made` call. A failure that may pass on its own carries the wait before the next try. */
3375
+ private sendDepositNotice;
3376
+ /**
3377
+ * Tells Yieldseeker (`deposit-made`) after a pool save, so the agent runs
3378
+ * now and rebalances money already in a vault the list no longer allows.
3379
+ * Up to DEPOSIT_NOTICE_ATTEMPTS calls in all, waiting between them only
3380
+ * after a failure that may pass; stops when the session ends. Never throws.
3381
+ */
3382
+ private rebalanceAfterPoolSave;
3383
+ /**
3384
+ * When Yieldseeker may move funds again after this agent wallet's last
3385
+ * confirmed withdrawal, if that is still ahead; null when there was none in
3386
+ * the last hour or the ledger cannot say.
3387
+ */
3388
+ private withdrawalCooldownEnd;
3389
+ /**
3390
+ * The agent wallet's base-asset balance and the platform fee Yieldseeker has
3391
+ * not collected from it, read at one block for a balance read. Cached
3392
+ * briefly per agent wallet and dropped by funding and allocation
3393
+ * invalidations. Null when any read fails or is slow: the snapshot's
3394
+ * amounts are used instead.
3395
+ */
3396
+ private readLiveWallet;
3397
+ private readWalletFunds;
3398
+ /** The agent wallet's idle base asset; null when the read fails. */
3399
+ private readIdleBalance;
3327
3400
  getFundingWallet(state: ConnectionState, chainId: number, asset: OwneySupportedTokens): Promise<string>;
3328
3401
  hasExistingDepositFunds(state: ConnectionState, chainId: number, asset: OwneySupportedTokens): Promise<true | undefined>;
3329
3402
  getEarnings(state: ConnectionState, chainId: number): Promise<AgentEarnings>;
@@ -3363,13 +3436,11 @@ declare class YieldseekerAgent implements IAgent {
3363
3436
  *
3364
3437
  * - Only Base entries are ours. An asset with no picks whose entries showed
3365
3438
  * no vault is skipped and nothing is sent.
3439
+ * - None picked (vaults shown) for any asset: every agent keeps at least one
3440
+ * pool (2026-11-11), so the whole save throws POOL_SELECTION_REQUIRED
3441
+ * before anything is written, for any asset.
3366
3442
  * - Some vaults picked: the managed list names them. Saving it again
3367
3443
  * 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
3444
  * - Every vault picked: the managed list is deleted, and no allow-list may
3374
3445
  * remain, so vaults Yieldseeker adds later are allowed too.
3375
3446
  * - A free-text allow-list we saved before the managed list existed is
@@ -3394,7 +3465,8 @@ declare class YieldseekerAgent implements IAgent {
3394
3465
  private deleteLegacyPoolMemories;
3395
3466
  /**
3396
3467
  * `<address> (<name>)` for each pick, under the prefix. An unnamed address
3397
- * has no brackets. No picks names no vault.
3468
+ * has no brackets. There is always at least one pick (setPoolSelection
3469
+ * refuses a save with none).
3398
3470
  */
3399
3471
  private poolMemoryContent;
3400
3472
  /** Undo a failed save of the managed list. Never throws: the caller reports the save's own failure. */
@@ -3461,8 +3533,9 @@ declare class YieldseekerAgent implements IAgent {
3461
3533
  private listAgents;
3462
3534
  /**
3463
3535
  * The routing API's stored accounts for owner+chain, read once per session.
3464
- * Resolves null when unavailable (callers keep name matching) and never
3465
- * rejects. A failure is retried after a short window.
3536
+ * Resolves null when unavailable and never rejects; callers then refuse
3537
+ * (AGENT_ACCOUNTS_UNAVAILABLE) and create nothing. A failure is not kept:
3538
+ * concurrent callers share the in-flight read, and the next call reads again.
3466
3539
  */
3467
3540
  private agentAccounts;
3468
3541
  /** Yieldseeker accounts for one slot (returned addresses are compared lowercase). */
@@ -3545,11 +3618,15 @@ declare class YieldseekerAgent implements IAgent {
3545
3618
  * 1. the listed fitting agent whose wallet is the verified account's wallet,
3546
3619
  * whatever its name; the stored agentId is only a hint;
3547
3620
  * 2. else a listed fitting agent whose wallet is a superseded account's wallet;
3548
- * 3. else the fitting agent named "owney" (first use, migration, or a
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;
3551
- * 4. else, with a verified account, throw YIELDSEEKER_AGENT_MISSING (never
3552
- * create); without one, undefined (the caller may create).
3621
+ * 3. else, with a verified account, throw YIELDSEEKER_AGENT_MISSING (never
3622
+ * create);
3623
+ * 4. else, with no record at all, the listed agent this session created or
3624
+ * adopted for the slot (sessionAgents); without one, undefined (the
3625
+ * caller creates an agent named "owney"). An agent is never picked by
3626
+ * its name: only our records, and this session's own create, say which
3627
+ * agents are Owney's.
3628
+ * Without the account records (`null`: the read failed) nothing can be
3629
+ * known, so the call is refused and nothing is created.
3553
3630
  * Steps 1 and 2 share one search of at most YIELDSEEKER_WALLET_MATCH_LIMIT
3554
3631
  * wallet reads. The account report then records the selected wallet; the
3555
3632
  * server marks it superseded when it differs from the verified wallet.
@@ -3582,7 +3659,12 @@ declare class YieldseekerAgent implements IAgent {
3582
3659
  private ensureAgent;
3583
3660
  private findAgent;
3584
3661
  private resolveAgent;
3585
- /** Create the slot's agent. Only reached when no stored or named agent matched. */
3662
+ /**
3663
+ * Create the slot's agent, named "owney". Only reached when the slot has no
3664
+ * account record and no agent this session made; the created agent is
3665
+ * remembered for the session (sessionAgents) so reads select it before its
3666
+ * record exists.
3667
+ */
3586
3668
  private createAgent;
3587
3669
  /**
3588
3670
  * The routing create lock refused the create: another tab or app owns or is
@@ -3618,6 +3700,7 @@ declare class YieldseekerAgent implements IAgent {
3618
3700
  private loadActivityContext;
3619
3701
  private loadPortfolioParts;
3620
3702
  private deployAgent;
3703
+ setAccountRefusedListener(listener: (() => void) | undefined): void;
3621
3704
  setFundingLedgerAccess(access: AgentFundingLedgerAccess | undefined): void;
3622
3705
  private historyKey;
3623
3706
  /** Funding-ledger rows for this slot, cached 15 s. Never throws: null on any failure. */
@@ -3687,7 +3770,6 @@ declare class YieldseekerAgent implements IAgent {
3687
3770
  private waitForReceipt;
3688
3771
  private assertTransaction;
3689
3772
  private assertAgent;
3690
- private isOwneyAgent;
3691
3773
  private assetForAgent;
3692
3774
  private isTransactionHash;
3693
3775
  private assertChain;