@zktx.io/sui-mcp 0.7.0 → 0.8.0

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.
Files changed (69) hide show
  1. package/README.md +83 -42
  2. package/dist/core/activity/localDataService.js +8 -21
  3. package/dist/core/activity/localDataValidation.js +22 -46
  4. package/dist/core/activity/sqliteAccountStore.js +46 -0
  5. package/dist/core/activity/sqliteActivityStore.js +65 -147
  6. package/dist/core/activity/sqliteActivityStoreSchema.js +42 -26
  7. package/dist/core/activity/transactionActivityService.js +2 -2
  8. package/dist/core/preferences/preferencesStore.js +2 -2
  9. package/dist/core/preferences/sqlitePreferencesRepository.js +10 -0
  10. package/dist/core/session/cardResult.js +41 -0
  11. package/dist/core/session/cardSession.js +1 -1
  12. package/dist/core/session/cardSessionStore.js +51 -19
  13. package/dist/core/session/chainAccounts.js +120 -0
  14. package/dist/core/session/sessionStore.js +4 -8
  15. package/dist/core/session/settingsFileStore.js +3 -30
  16. package/dist/core/session/settingsOperation.js +27 -19
  17. package/dist/core/session/settingsWorkflow.js +161 -87
  18. package/dist/core/session/sqliteCardStore.js +34 -14
  19. package/dist/core/session/sqliteSessionStore.js +5 -5
  20. package/dist/core/session/sqliteSettingsWorkflowStore.js +135 -41
  21. package/dist/core/session/sqliteTransactionRequest.js +18 -0
  22. package/dist/core/session/sqliteWalletConnectionOperation.js +13 -0
  23. package/dist/core/session/sqliteWalletWorkflowStore.js +569 -333
  24. package/dist/core/session/status.js +2 -2
  25. package/dist/core/session/wait.js +6 -11
  26. package/dist/core/session/walletConnection.js +71 -46
  27. package/dist/core/session/walletConnectionOperations.js +24 -0
  28. package/dist/core/session/walletRuntime.js +7 -13
  29. package/dist/core/session/walletWorkflow.js +248 -99
  30. package/dist/core/session/workflowState.js +104 -38
  31. package/dist/core/session/workflowView.js +92 -101
  32. package/dist/mcp/activeAccountResponse.js +3 -0
  33. package/dist/mcp/responseGuidance.js +7 -9
  34. package/dist/mcp/serverInfo.js +11 -10
  35. package/dist/mcp/toolErrors.js +5 -3
  36. package/dist/mcp/toolNames.js +1 -0
  37. package/dist/mcp/tools/action/prepareSuiActionReview.js +9 -16
  38. package/dist/mcp/tools/read/readToolHelpers.js +9 -7
  39. package/dist/mcp/tools/session/executionResultTools.js +2 -2
  40. package/dist/mcp/tools/session/shared.js +2 -2
  41. package/dist/mcp/tools/session/statusTools.js +12 -10
  42. package/dist/mcp/tools/session/walletConnectionTools.js +26 -14
  43. package/dist/mcp/tools/settings/index.js +7 -4
  44. package/dist/mcp-app/account.html +7 -7
  45. package/dist/mcp-app/chart.html +3 -3
  46. package/dist/mcp-app/connect.html +13 -13
  47. package/dist/mcp-app/disconnect.html +3637 -0
  48. package/dist/mcp-app/disconnect.notices.txt +1480 -0
  49. package/dist/mcp-app/receipt.html +393 -393
  50. package/dist/mcp-app/review.html +459 -459
  51. package/dist/mcp-app/settings.html +7 -7
  52. package/dist/mcp-ui/contracts.js +3 -1
  53. package/dist/mcp-ui/tools.js +4 -4
  54. package/dist/runtime/application.js +1 -1
  55. package/dist/runtime/localSettingsService.js +7 -4
  56. package/dist/runtime/smokeMainnetRead.js +5 -4
  57. package/dist/runtime/walletConnectTransport.js +16 -16
  58. package/dist/runtime/walletSdkChildRuntime.js +29 -12
  59. package/dist/runtime/walletSdkIpc.js +5 -4
  60. package/dist/runtime/walletSdkProcess.js +24 -8
  61. package/docs/AGENT_BEHAVIOR.md +82 -54
  62. package/docs/LOCAL_DB_ARCHITECTURE.md +100 -70
  63. package/docs/MCP_SETUP.md +319 -339
  64. package/docs/MCP_TOOLS.md +292 -177
  65. package/docs/SDK_API.md +15 -6
  66. package/docs/TRANSACTION_ACTIVITY_LOG.md +4 -0
  67. package/docs/UTILITY_INDEX.md +9 -7
  68. package/docs/WALLET_CONNECTION.md +162 -167
  69. package/package.json +1 -1
package/docs/MCP_TOOLS.md CHANGED
@@ -68,7 +68,7 @@ Read-only tools split by address requirement.
68
68
 
69
69
  Address-free reads do not need wallet connection. Examples include DeepBook pool lists, orderbook snapshots, mid price, and quote facts.
70
70
 
71
- Current asset reads need either an explicit public Sui address supplied by the user or a selected account with a usable current wallet connection. Stored activity and transaction-result reads retain their own read-context rules.
71
+ Current asset reads need either an explicit public Sui address supplied by the user or the saved Sui read address with a usable current wallet connection. Stored activity and transaction-result reads retain their own read-context rules.
72
72
 
73
73
  An explicit public-address read does not prove ownership, create active account context, or authorize active-account-only tools.
74
74
 
@@ -166,13 +166,13 @@ Internal read cards are opened with `ui_open_account`, `ui_open_receipt`, and `u
166
166
 
167
167
  | Tool | Input and result |
168
168
  | --- | --- |
169
- | `ui_open_account` | Optional explicit Sui address; otherwise use the selected read account only when its wallet connection is currently usable. Missing input returns `input_required` with no card or source query. Shows name, address, coin totals, Display NFTs, other-object count, fetched time and enumeration limits; no address form. |
169
+ | `ui_open_account` | Optional explicit Sui address; otherwise use the saved Sui read address only when its wallet connection is currently usable. Missing input returns `input_required` with no card or source query. Shows name, address, coin totals, Display NFTs, other-object count, fetched time and enumeration limits; no address form. |
170
170
  | `ui_open_receipt` | A transaction digest is required for a query. Omission returns `input_required` with no card or source query. The result view shows execution outcome, balance changes, net gas, sender, digest and fetched time; no hash form. No wallet or active account is needed. Normalized receipt evidence and private display metadata remain available under their existing boundaries. |
171
171
  | `ui_open_chart` | Optional `poolName`, official Indexer interval, UTC `startTimeMs`/`endTimeMs`, and candle `limit`. Shows one selected USDC pool as candlesticks and volume. Range shortcuts fill these query fields. The initial time axis uses the saved request boundaries, with price-free whitespace at boundaries without candles; omitted boundaries use the returned data. |
172
172
 
173
173
  A missing Account/Receipt target returns `data: { kind, status: "input_required", field, message }`, with no permission, card ID, saved resource or query. A host-rendered view shows the message without input controls or polling. Other errors remain errors.
174
174
 
175
- A successful card-creating response contains a `cardId`, `kind`, `state`, `revision`, timestamps, original `input`, and available `data`. `inputRemainingMs` is computed by the backend; `pollAfterMs` controls sequential observation of a running read. Card `ready` permits a read selection, not signing or payment readiness. An initial supplied input uses the same admission path as a form submission. DB states are `ready`, `running`, and `closed`, with terminal reasons `completed`, `expired`, `failed`, or `server_restarted`.
175
+ A successful card-creating response contains a `cardId`, `kind`, `state`, `revision`, timestamps, original `input`, and available `data`. `inputRemainingMs` is computed by the backend; `pollAfterMs` controls sequential observation of a running read. Card `ready` permits a read selection, not signing or payment readiness. An initial supplied input uses the same admission path as a form submission. DB states are `ready`, `running`, and `closed`, with terminal reasons `completed`, `expired`, `failed`, `server_restarted`, or `cancelled`.
176
176
 
177
177
  When Chart pool choices cannot be prepared, the backend creates a `closed`/`failed` card with a readable error. No selection is admitted and no candles are requested. Reading that card again returns the stored failure; retrying the source requires an explicit request for a new card. A database access or write failure is a tool error, not a successfully stored failure card.
178
178
 
@@ -210,8 +210,8 @@ current instruction or proof that a cancellation succeeded.
210
210
  A failed Request delivery never triggers a repeated signature request. Same-card
211
211
  reads still follow the existing expiry hints; a confirmed unadmitted stale review
212
212
  may prepare new conditions, which require a new Request click. Failed initial
213
- preparation can be retried for the displayed current wallet/account after another
214
- state check. A delayed action response does not clear an intervening read failure:
213
+ preparation can be retried for the Review's original wallet/account after another
214
+ state check, while that exact connection remains usable. A delayed action response does not clear an intervening read failure:
215
215
  the card retains explicit state-read recovery until a current read succeeds.
216
216
 
217
217
  Overlapping successful responses for the same card may arrive out of order.
@@ -219,7 +219,7 @@ A lower revision does not replace displayed facts or create a read error, and
219
219
  required observations continue from the retained current state. Equal revisions
220
220
  are validated rather than discarded. Actual error responses remain failures.
221
221
 
222
- An unconfirmed Cancel review, wallet disconnection, account selection or stop
222
+ An unconfirmed Cancel review, wallet disconnection or stop
223
223
  request retains its error and pauses new automatic preparation/pairing in that
224
224
  View. State reads still report already admitted work. Existing permitted actions
225
225
  can be retried explicitly. An unconfirmed Cancel review followed by expired
@@ -231,12 +231,12 @@ pause does not claim that the backend or other frames stopped; new frames use
231
231
  the actual saved state.
232
232
 
233
233
  Connect eligibility and its SQLite admission use the same current-owner
234
- connection set. An unexpired connected wallet, pending approval or pending disconnection
234
+ connection and SDK observation. An unexpired connected wallet, pending approval or pending disconnection
235
235
  removes `connect` from `allowedActions` and prevents a second pairing even when
236
236
  different cards race with current revisions. The losing card gets the existing
237
- conflict response and its own snapshot, without another card's private QR or
238
- permission. Later availability requires an explicit Retry for that failed
239
- attempt; a saved-state read does not repeat it.
237
+ fixed no-request result, without another card's private QR or permission. It ends
238
+ without pairing; later availability requires a new prompted Connect card. A saved
239
+ result read cannot reopen it.
240
240
 
241
241
  Failed attempts whose exact target or command authority has ended are shown as
242
242
  earlier attempts, without a command retry or a saved-read button solely for that
@@ -244,11 +244,13 @@ old failure. The current stored result remains authoritative; natural completion
244
244
  is not proof that an earlier stop was accepted. This includes failed automatic
245
245
  connection/preparation and an unadmitted Request when its card or review expires.
246
246
  Card action expiry does not end an already admitted request or result lookup.
247
- For unadmitted disconnection or account selection, the exact target in
248
- `connections` can establish that the earlier attempt has ended even while the
249
- card input remains available. An account returning later does not revive that
250
- attempt or clear its local automatic pause; the user can make a new selection.
251
- If an unknown result needs another lookup after the card's action period, request
247
+ For an unadmitted disconnection, compare the attempted connection ID with the
248
+ current `connection` and confirmed SDK facts. A replacement connection cannot
249
+ be the target of that earlier attempt. Missing or unavailable observations alone
250
+ do not establish termination. A later state change does not revive the attempt
251
+ or clear its local automatic pause. A dedicated Disconnect card remains limited
252
+ to its original connection; a new purpose card is required for an operation on the current connection.
253
+ Once a result card has ended, request another lookup when needed through
252
254
  `session_open_review_management` with the same `reviewSessionId` and `attemptId`.
253
255
  It adds no signing authority and does not repeat the transaction.
254
256
 
@@ -258,7 +260,7 @@ an actual read failure instead requires explicit recovery. A valid current read
258
260
  also clears an identified card's earlier opening-projection error. Neither path
259
261
  repairs malformed permissions or changes the card's target.
260
262
 
261
- Review displays one current wallet candidate without a dropdown. Its current authenticated View executes the backend-projected `automaticAction` to prepare or renew stale verified conditions. Multiple valid connections block preparation and signing until the user resolves them with targeted Disconnect actions. A failed computation requires explicit retry. `review_evidence_stale` distinguishes invalidated verified material from a failed quote/computation. Only Request wallet approval authorizes a signature request for the displayed revision. Result cards show the correct PTB, actual chain facts and one Details slide; Review keeps earlier estimates in its Reviewed conditions section.
263
+ Review displays its exact account and wallet connection without a dropdown. Its current authenticated View executes the backend-projected `automaticAction` to prepare or renew stale verified conditions. A new Review uses the one current fixed Sui account and connection. Its public input has no account/connection selector. Disconnecting requires a new Review for the replacement connection. A failed computation requires explicit retry. `review_evidence_stale` distinguishes invalidated verified material from a failed quote/computation. Only Request wallet approval authorizes a signature request for the displayed revision. Result cards show the correct PTB, actual chain facts and one Details slide; Review keeps earlier estimates in its Reviewed conditions section.
262
264
 
263
265
  Cards provide no clipboard actions or copy buttons. Their text remains readable and selectable. Chart values remain USDC-denominated source candles, not fiat USD, peg guarantees, route advice, portfolio valuation or P&L. Cards do not fetch chain/Indexer endpoints directly or poll completed results.
264
266
 
@@ -310,7 +312,7 @@ This quote is not a settlement asset choice.
310
312
 
311
313
  ### DeepBook account inventory
312
314
 
313
- `read_summarize_deepbook_account_inventory` uses the selected account only when its current wallet connection is usable, to discover DeepBook BalanceManager addresses. It has no explicit public-address input. Without a usable default, a missing selection returns `active_account_not_set`, and a stored but ineligible selection returns `input_invalid`; both carry `details.reason: "connected_account_required"` and `details.followUp` naming `session_get_interaction_status` and its connection/availability/pending/default-account fields. These responses do not request an address. Unavailable wallet operations return `wallet_unavailable` with the existing safe reason and recovery message.
315
+ `read_summarize_deepbook_account_inventory` uses the saved Sui read address only when its current wallet connection is usable, to discover DeepBook BalanceManager addresses. It has no explicit public-address input. A missing or cleared read address returns `active_account_not_set`; a stored but ineligible address returns `input_invalid`. Both carry `details.reason: "connected_account_required"` and `details.followUp` naming `session_get_interaction_status` and its wallet availability, current connection, pending operations and `assetReadAccount`. A cleared read address is reported separately from disconnection and cannot be bypassed with a typed address. These responses do not request an address. Unavailable wallet operations return `wallet_unavailable` with the existing safe reason and recovery message.
314
316
 
315
317
  With both `poolKey` and `managerAddress`, it checks pool account existence and returns display-like account inventory:
316
318
 
@@ -334,7 +336,7 @@ They are not raw balances, route liquidity, funding sources, withdrawal readines
334
336
 
335
337
  `read_summarize_wallet_assets` accepts an optional `account` input for public-address coin balance snapshots.
336
338
 
337
- When `account` is omitted, it uses the same connection-qualified default as `session_get_interaction_status.assetReadAccount`. No stored selection returns `active_account_not_set` with `details.action: "provide_account"`; a stored but ineligible selection returns `input_invalid` with `details.reason: "address_required"`. Both request an explicit address. SDK unavailability is not reported as absence of a stored account.
339
+ When `account` is omitted, it uses the same connection-qualified read address as `session_get_interaction_status.assetReadAccount`. A missing or cleared read address returns `active_account_not_set` with `details.action: "provide_account"`; a stored but ineligible address returns `input_invalid` with `details.reason: "address_required"`. Both request an explicit address. SDK unavailability is not reported as absence of a stored account.
338
340
 
339
341
  An explicit `account` read does not prove ownership, store the address as a known wallet, or create active account context.
340
342
 
@@ -404,7 +406,7 @@ Use it this way:
404
406
 
405
407
  - Coverage question: `intentKind: "cover_payment_like_amount"`, `denomination: "dollar"`, and `requiredDisplayAmount: "1000"`.
406
408
  - AssetGroup-total question: `intentKind: "summarize_settlement_asset_group_balance"` and `denomination: "dollar"` without a target amount.
407
- - Account scope: explicit public `account` or a selected account with a usable current wallet connection.
409
+ - Account scope: explicit public `account` or the saved Sui read address with a usable current wallet connection.
408
410
 
409
411
  For settlement-asset-only coverage, shortfall, and balance-total answers, use `responseSummary`.
410
412
 
@@ -452,7 +454,7 @@ Review activity tools read only local Sui MCP review evidence.
452
454
 
453
455
  They are not complete wallet transaction history, gas history, P&L, or external wallet activity.
454
456
 
455
- The optional `account` input is a read filter and does not change the active account context. If `account` is omitted, the tools use the active account context.
457
+ The optional `account` input is a read filter and does not change the saved read address. If `account` is omitted, the tools use stored read context without requiring a live wallet. If that context is absent or cleared, they return `active_account_not_set` with `details.action: "provide_account"`. Supply an explicit Sui address for the read; this error does not establish that the wallet is disconnected.
456
458
 
457
459
  Successful review activity responses include `dataScope`, `accountSource`, `lowSampleWarning`, and `lowSampleThreshold`.
458
460
 
@@ -529,8 +531,9 @@ Coverage and pagination boundaries:
529
531
 
530
532
  Local persistence boundaries:
531
533
 
532
- - The default account is the active account.
533
- - An explicit account is allowed as a read filter.
534
+ - An omitted account uses the saved read address without a live-wallet requirement.
535
+ - A missing or cleared address returns `active_account_not_set` with `details.action: "provide_account"`; it does not establish wallet disconnection.
536
+ - An explicit account is allowed as a read filter and does not restore implicit context.
534
537
  - The local DB stores only normalized facts for transactions tied to a known account by returned sender or balance-change owner facts.
535
538
  - Function activity scans store only sender-matching rows for known accounts.
536
539
  - Provider-returned account scan rows that cannot prove the local relation can appear in the current response but are counted as skipped for storage.
@@ -686,7 +689,7 @@ If stored or summary details are missing or capped, use the digest metadata with
686
689
 
687
690
  Inputs:
688
691
 
689
- - `account` is optional. If omitted, the tool uses active account context. Supplying an explicit public account does not create active account context or prove ownership.
692
+ - `account` is optional. If omitted, the tool uses saved Sui read context with `accountSource: "active_account_context"`, without requiring a live wallet. Missing or cleared context returns `active_account_not_set` with `details.action: "provide_account"`; supply an explicit Sui address for this read. That error does not establish wallet disconnection. Supplying an explicit public account does not create saved read context or prove ownership.
690
693
  - `start` and `end` are ISO 8601 UTC timestamps. The requested range is half-open: `start` is included and `end` is excluded.
691
694
  - `interval` is optional and uses the same official Indexer interval values as DeepBook USDC price tools. Omitted `interval` uses `15m`.
692
695
 
@@ -711,14 +714,17 @@ This tool does not run scans, start a background indexer, create a price cache,
711
714
  | `action_start_review` | Internal swap Review card | Creates a local review session and internal Review card for a supported swap action proposal. Account-bound DeepBook reviews may build local unsigned transaction material inside the review server, internally bind a Sui transaction digest to it, and derive object ownership, quote/policy, human-readable review, review-time simulation, and PTB visualization evidence. When every required evidence stage completes, an explicit Review card selection can admit backend-mediated WalletConnect approval for that exact transaction. The MCP tool does not return transaction bytes, signing data, or signing readiness. |
712
715
  | `action_create_proposal_review` | Non-signable review | Creates a local review session and internal Review card from an untrusted structured external proposal. It does not return transaction bytes. |
713
716
 
714
- `action_start_review` is account-bound: a swap review computes
715
- its evidence (balances, transaction material, digest, simulation) for a
716
- specific sender, so the tool requires an active wallet account. Connect first
717
- with `session_open_wallet_connection_card`; with no active account the tool returns
718
- `active_account_not_set` with `details.action: "connect_wallet_connection"`
719
- instead of creating a proposal that can never be computed or signed. The
720
- Review card reads that account from the server as the single source of truth
721
- and never connects a wallet itself.
717
+ `action_start_review` accepts only `intent` and verifies the requested adapter
718
+ before resolving the current connection's fixed Sui address. Public `account` or
719
+ `connectionId` selectors are not accepted. No usable current target returns
720
+ `active_account_not_set` with `details.reason: "connection_required"`. An unexpected
721
+ retained SDK session returns `input_invalid` with
722
+ `details.reason: "connection_state_unconfirmed"`; inspect connection status and
723
+ remove the unwanted session in the wallet app. An unavailable service returns
724
+ `wallet_unavailable`. These errors create no empty Review or wallet effect.
725
+ The accepted account and connection are fixed in the initial card, before
726
+ preparation. Preparation, display and retry retain that same target, including
727
+ when it becomes unavailable or its saved read address is cleared.
722
728
 
723
729
  `action_start_review` accepts a protocol-neutral swap `intent`
724
730
  (`type: "swap"`, `from.symbol`, `from.amount`, `to.symbol`,
@@ -944,28 +950,95 @@ It is not a signing readiness signal. Review-state checks are pre-signing review
944
950
 
945
951
  | Tool | Input and result |
946
952
  | --- | --- |
947
- | `session_open_wallet_connection_card` | Opens an internal card with `intent: connect`, `disconnect` or `manage` (default). A connect-intent View automatically starts pairing after authenticated state confirmation; manage pairs only after the user chooses Connect wallet. A disconnect-intent card opens confirmation for a unique connected target. Disconnection requires target-specific confirmation and does not revoke onchain permissions. |
948
- | `session_get_wallet_connection_card` | Reads one `cardId`; public response excludes pairing and permission. |
949
- | `session_wait_wallet_connection_card` | Waits on one `cardId`, with an optional timeout up to 55 seconds; stops when user input is needed or the admitted connection/disconnection operation ends. |
953
+ | `session_open_wallet_connection_card` | Opens one Connect card with empty input. Authenticated View confirmation admits its one pairing. A current session or unsettled SDK work prevents another pairing. |
954
+ | `session_open_wallet_disconnection_card` | Opens one Disconnect card bound to the exact current manageable session. The user confirms removal or cancels this card. It never starts pairing or targets a replacement session. |
955
+ | `session_get_wallet_connection_card` | Reads one `cardId`, returning `{card, operation, walletAvailability, evaluatedAt}` without UI authority or QR data. `card` is the stored snapshot; `operation` is that card's exact current public journal entry or null before admission. |
956
+ | `session_wait_wallet_connection_card` | Uses `cardId` and an optional timeout up to 55 seconds. Returns the same envelope plus `waitOutcome`, when that exact operation and SDK settlement end, no operation is admitted, service is unavailable, or the bounded wait ends. It accepts no operation selector. |
950
957
  | `session_open_review_management` | Opens management for exact `reviewSessionId` + `attemptId`; no refresh or signing authority. |
951
- | `session_get_interaction_status` | Stored `activeAccount`, current-owner `connections`, `assetReadAccount`, wallet availability, and bounded pending connection/review lists. `assetReadAccount` is `available` with an account only when that selected address has a usable current connection; otherwise `address_required`. Stored `activeAccount` does not prove a live connection. `address_required` reports that no implicit default is available; it does not add an address input to connected-account-only tools. When wallet availability is unavailable, connection rows are last recorded facts, not proof of presence or absence. |
958
+ | `session_get_interaction_status` | Stored `activeAccount`, current `connection`, optional `pendingOperation`, `assetReadAccount`, wallet availability, and bounded pending connection/review lists. `assetReadAccount` is `available` with an account only when the saved Sui read address has a usable current connection; otherwise `address_required`. Stored `activeAccount` does not prove a live connection. `address_required` reports that no implicit default is available; it does not add an address input to connected-account-only tools. When wallet availability is unavailable, connection rows are last recorded facts, not proof of presence or absence. |
952
959
  | `session_get_review_status` | Current preparation status, review revision, optional current request and chain execution. |
953
960
  | `session_get_execution_result` | Observes the current explicitly referenced attempt and may read its known digest; never submits again. |
954
961
  | `session_wait_execution_result` | Bounded wait on the same request, separate from its signing and chain-observation deadlines. |
955
962
 
956
- `pendingWalletConnections.items[].status` is `input_required`,
957
- `awaiting_approval`, or `disconnect_pending`. The last value describes an
958
- admitted, running disconnect card, not a new wallet connection state. In card
959
- workflow data, a connection's optional `pendingAction: "disconnect"` is derived
960
- from that stored card operation. Its `status` remains the last confirmed
961
- connection fact. Such a connection is unavailable for a new account selection,
962
- review or signature request. `observe` remains true while disconnection can be
963
- observed, and becomes false on completion or unavailable wallet progress.
964
- While its SDK callback remains pending, unavailable progress preserves the
965
- operation and its last recorded connection state. Repeating the same selection
966
- does not send another SDK request.
967
-
968
- `session_get_interaction_status` reconciles stored connections against current SDK sessions before reading dependent review/request facts. This can record a connection change and invalidate a review or interrupt an unsubmitted request under the existing rules. It preserves the stored account selection and submitted chain results; it does not start pairing, SDK disconnect, signing or submission.
963
+ `pendingWalletConnections.items[]` identifies each admitted `operationId`, its
964
+ card and connection. Status is `awaiting_approval`, `disconnect_pending` or
965
+ `cleanup_pending`. Unadmitted cards are not pending effects. These statuses
966
+ describe management work, not a new wallet connection state. Interaction status has an optional top-level `pendingOperation` describing the current connection's
967
+ outstanding operation. It contains `operationId`, `action`
968
+ (`connect` or `disconnect`), `status` (`running`, `completed`, `failed` or
969
+ `stopped`) and `settlementPending`. It is derived from that connection's existing
970
+ operation when it is running or still has pending SDK work; it is not another
971
+ operation or authorization. Connection `status` remains the last confirmed
972
+ connection fact. Pending work makes that connection unavailable for a new review
973
+ or signature request. `observe` follows the operation's remaining progress and
974
+ wallet availability. SDK settlement remains observable through get/wait independently of the immutable
975
+ terminal card result. Unavailable progress preserves the operation and its last
976
+ recorded connection state. Repeating the same selection does not send another
977
+ SDK request.
978
+
979
+ Match `pendingOperation.operationId` to the one operation fixed to that card,
980
+ rather than inferring ownership from the action name. Closed card data is a
981
+ recorded snapshot; the get/wait envelope's `operation` reports current settlement.
982
+ A running disconnect is disconnecting; a completed disconnect is disconnected
983
+ with any outstanding cleanup reported separately. It is not another connection
984
+ request, and pending cleanup does not turn completion into failure or reopen a
985
+ cancelled card.
986
+
987
+ `connection.sessionPresence` reports whether the current connection has an SDK
988
+ session: `present`, `absent`, `unusable`, or `unconfirmed`. Absence includes an
989
+ exact current-session absence observation or a settled attempt without an approved
990
+ session or recorded session reference. The latter requires confirmed current-run
991
+ ownership, no pending connection work and no unrecorded SDK session. A missing
992
+ observation for a recorded session is not absence. Unavailable service or an
993
+ unconfirmed current-run observation is `unconfirmed`, never evidence of absence.
994
+ This field does not change the saved connection status or grant input authority.
995
+ A failed or expired connection may still need explicit disconnection. Once
996
+ absence is confirmed and cleanup ends, the user can request a new Connect card.
997
+ An ended card never offers a new connection. An existing Review bound to the ended connection requires a new Review
998
+ after reconnection. A declined connection alone does not require a transaction
999
+ Review. Stored connection messages in Details are historical facts, not current
1000
+ recovery instructions.
1001
+
1002
+ Live card data is purpose-specific. Connect includes fixed `requestedChains`,
1003
+ its optional `operation` and permitted initial `automaticAction`. Disconnect
1004
+ includes its exact `connection` confirmation and optional `operation`. Review
1005
+ includes `review`, `reviewTarget`, optional exact `request`/receipt facts, and
1006
+ permitted preparation action. All expose `allowedActions`, progress, service
1007
+ availability and `nextStep` (`kind`, optional safe `message`/`reason`). This is
1008
+ advisory guidance, never authorization. Read-address overview and current
1009
+ `pendingOperation` belong to interaction status, not the live card payloads.
1010
+
1011
+ | `nextStep.kind` | Meaning |
1012
+ | --- | --- |
1013
+ | `none` | No additional business recovery step is required by this evaluation. |
1014
+ | `wait` | Service startup or existing wallet/account work must finish before continuing. |
1015
+ | `check_status` | Read the indicated existing request or session; no new wallet effect is authorized. |
1016
+ | `open_settings` | Open the named Settings section for configuration or explicit service recovery. |
1017
+ | `request_disconnect` | Ask for a new exact-target Disconnect card before changing the connection. |
1018
+ | `request_review` | Ask for a new transaction Review; the old target cannot be replaced. |
1019
+
1020
+ The backend's message identifies the applicable condition. A saved preparation
1021
+ error does not override this guidance. Reasons such as `operation_busy`,
1022
+ `connection_state_unconfirmed`, `connection_target_changed`,
1023
+ `wallet_networks_required` and `no_session_to_disconnect` describe the particular
1024
+ refusal; they grant no input or effect authority. Service `initializing` and
1025
+ `recovering` mean wait, not another restart request.
1026
+
1027
+ A closed wallet card has no operation copy. Optional `result.pendingWork` records
1028
+ `approval_response`, `session_removal` or `session_status` at closure. Normal
1029
+ success does not create a recovery obligation from callback bookkeeping.
1030
+ Exact-operation get/wait still reports current `settlementPending`, including
1031
+ failed bookkeeping writes, without changing the card or replaying effects.
1032
+ A Connect card that sends no request has no network approval result or wallet
1033
+ name copied from another connection.
1034
+
1035
+ Every Connect and Disconnect terminal snapshot is address-free from the moment
1036
+ it is recorded: no address, account, address-bearing chain states or QR payload
1037
+ is included. Its result, recorded time, wallet name and network approval statuses
1038
+ stay fixed. Current `connection.chainResults` belong to interaction status;
1039
+ stored history and transaction targets keep their exact addresses.
1040
+
1041
+ `session_get_interaction_status` reconciles stored connections against current SDK sessions before reading dependent review/request facts. This can record a connection change and invalidate a review or interrupt an unsubmitted request under the existing rules. It preserves fixed addresses, read-address suppression and submitted chain results; it does not start pairing, SDK disconnect, signing or submission.
969
1042
 
970
1043
  When a disconnect callback ended but its completion write failed, current reads
971
1044
  reconcile that stored operation without another SDK disconnect. If the SDK is
@@ -999,8 +1072,9 @@ neither a completed result nor a wait timeout. A command already committed
999
1072
  before its response fails remains recorded and is recovered by reading it.
1000
1073
 
1001
1074
  Wallet startup and restoration are asynchronous dependencies of the parent
1002
- service. Connect/manage cards remain available during initialization or failure
1003
- so the user can inspect state. They do not provide service-restart input. Ordinary evidence
1075
+ service. Connect can explain service initialization or failure; Disconnect
1076
+ creation instead returns its applicable availability error without issuing a
1077
+ card. Neither card provides service-restart input. Ordinary evidence
1004
1078
  and saved-result reads do not await the SDK. The package supplies its project
1005
1079
  identifier; these failures do not ask the user for a project ID. SDK error bodies
1006
1080
  and private configuration values are not returned.
@@ -1013,19 +1087,16 @@ Review status is preparation state (`proposed`, `awaiting_wallet`,
1013
1087
  otherwise the preparation state. The `user_action_required` category and
1014
1088
  `pollingHint.userActionRequiredStatuses` identify states where the model-facing
1015
1089
  wait returns; they do not require a manual preparation click. A permitted live
1016
- card can prepare automatically, while an ambiguous selection or failed update
1017
- can require user input. Preparation is not an already pending wallet signature.
1018
-
1019
- A review's bound account is fixed; changing the active read account does not
1020
- rebind it. Preparation choices and final admission use the same account rule.
1021
- To update a review bound to A, select A again in a new Connect card. To review
1022
- for B, request a new Review. An absent or incompatible read account removes the
1023
- preparation choice without recording a preparation failure. The existing
1024
- `review.error` card text distinguishes `Current account selection` guidance from
1025
- a quoted saved review message. It does not decide permissions. Changing
1026
- read context alone does not revoke an already valid A review's signing choice.
1027
- Once a signing request consumes its card, retrying needs a new Review; a
1028
- management card only refers to its existing exact attempt.
1090
+ card can prepare automatically, while a failed update
1091
+ can require an explicit retry. Preparation is not an already pending wallet signature.
1092
+
1093
+ A Review keeps its exact account and connection. Clearing the saved read address does not change its target. Disconnecting means
1094
+ a replacement connection needs a new Review. A new target requires
1095
+ a new Review; another connection with the same address cannot take over.
1096
+ Preparation and signing still require that original binding's current grant,
1097
+ method/event scope, revision and material. Saved preparation errors remain
1098
+ separate from current eligibility. After signing admission, a management card
1099
+ only refers to its exact attempt and grants no new preparation or signature.
1029
1100
 
1030
1101
  Only `completed` has `executionResult`, with `attemptId`, review/plan IDs,
1031
1102
  `status: success | failure`, the exact digest, verified `chainReceipt` and time.
@@ -1033,7 +1104,10 @@ Only failed chain effects have `failureReason: chain_execution_failed`. Wallet
1033
1104
  rejection, local timeout, unavailable receipts and lost submission responses
1034
1105
  never fabricate a chain failure. An unknown result retains the digest for later
1035
1106
  reads. An explicit user stop after submission stops observation, not an on-chain
1036
- transaction. Wallet connection changes or a requested disconnect stop pending
1107
+ transaction. Accepted `stop_waiting` also closes that card's business input;
1108
+ a new `session_open_review_management` card may explicitly inspect the same
1109
+ attempt later. A duplicate stop on the cancelled card does not stop work started
1110
+ from a newer card. Wallet connection changes or a requested disconnect stop pending
1037
1111
  submission permission with their own recorded reason; they do not claim that the
1038
1112
  user stopped waiting or that disconnection already succeeded. After submission,
1039
1113
  those connection events preserve independent observation of the same digest,
@@ -1068,80 +1142,70 @@ for the last confirmed local SDK observation. Ordinary reads do not perform a
1068
1142
  fresh SDK check or prove that the wallet app is online. Implicit asset reads
1069
1143
  require an available service and a usable observation in that same run.
1070
1144
 
1071
- Wallet-dependent app inputs (`connect`, `disconnect`, `use_account`,
1072
- `prepare_review`, `request_signature`) carry the displayed `walletRunId`. A stale
1073
- run cannot be transferred to a replacement SDK. Backend commands verify the
1074
- session, account, chain, method and stored authority at their decision boundary.
1075
- `acceptedWalletRunId` identifies a card's stored wallet input, when present; it
1076
- is not new permission.
1077
-
1078
- Connect workflow data includes optional `connectionAction: "connect" | "disconnect"`
1079
- only when that action was admitted on the card. The connection's current status
1080
- is separate from the card's original operation. In particular, failed disconnect
1081
- means remote removal was not confirmed, including after local service recovery.
1082
-
1083
- `connectionConflict`, when present, is
1084
- `{ reason: "multiple_connections", connectionIds: [...] }`. It contains distinct
1085
- IDs for the multiple live, known connections that prevent selecting a usable
1086
- wallet. It appears in Connect/Review `data`, the connection wait's `card.data`,
1087
- interaction status and relevant review-status responses. Its shared schema and
1088
- backend evaluation own the meaning; the View does not count rows to grant authority.
1089
- `walletAvailability: available` only confirms the SDK dependency, not the absence
1090
- of this conflict. `connections` describes recorded targets, not signing choices.
1091
- In conflict, `assetReadAccount` is `address_required`; explicit-address reads and
1092
- saved transaction results retain their independent access rules.
1093
-
1094
- A valid Connect card can still offer exact-target `disconnect` during conflict.
1095
- `connect`, `use_account`, `prepare_review` and `request_signature` remain blocked.
1096
- Each disconnection uses the same scoped UI permission, current run and revision,
1097
- atomic admission and saved result as an ordinary single-connection disconnect.
1098
- No first/newest/default wallet is silently selected. When one valid connection
1099
- remains and no connection operation is pending, normal account use can resume;
1100
- with no recorded or SDK-present connection and no pending operation, pairing is
1101
- available. A failed disconnect does not prove remote removal.
1102
- A failed or stopped product connection is not restored merely because its SDK
1103
- session remains saved.
1104
-
1105
- `connectionConflict` is optional. Its absence alone is not proof of a usable
1106
- connection or permission, especially in a historical result that does not need
1107
- current wallet eligibility. Filling optional context never adds global cleanup
1108
- writes or SDK requests to independent saved-result reads. `allowedActions`
1109
- identifies permitted action types; it is not a list of visible buttons or model
1110
- authority. Only the exact current target, UI permission and final admission
1111
- checks allow a user action.
1112
-
1113
- Current Connect/Review `data` also publishes `usableConnectionId` and
1114
- `assetReadAccount`. The first identifies the single connection eligible for
1115
- account use at the backend's evaluation time; it is absent during conflict,
1116
- pending connection work, unavailable service, or when no unexpired connection
1117
- qualifies. It does not authorize a signature. `assetReadAccount` uses the same
1118
- `available`/`address_required` shape as interaction status. Availability requires
1119
- the stored default's source connection ID to match this connection and its
1120
- address to remain approved. Matching the address in a different connection is
1121
- insufficient. A source-less stored selection requires explicit Use address.
1122
-
1123
- `manageableConnectionIds` identifies exact recorded targets for a new scoped
1124
- Disconnect, separately from account use. It includes nonpending connected records
1125
- (including expired ones) and known terminal records whose current SDK session
1126
- remains present. `connectionReconciliationRequired: true` identifies a present SDK
1127
- session without a journal target after normal registration/cleanup ends. It
1128
- blocks pairing, account use, preparation and signing while preserving SDK
1129
- availability and saved outcomes. Remove the retained connection in the wallet
1130
- app, then confirm absence through a complete current service observation.
1131
- Settings/Troubleshooting can explicitly restart the service to inspect it again;
1132
- restart alone does not remove or approve that connection. No private topic or synthetic target ID
1133
- is exposed. Both fields also appear in interaction status; review status includes
1134
- the reconciliation flag when current eligibility is needed.
1135
-
1136
- These fields are emitted together for current wallet eligibility. Independent
1137
- historical or completed-result reads may omit them; omission does not establish
1138
- current eligibility. Recorded `connections` and `activeAccount` remain facts,
1139
- including expired records and a stored default that cannot currently be used.
1140
- Views consume the published selection instead of counting recorded rows or
1141
- using their own clock. An expired record may remain a disconnection target;
1142
- expiry alone does not confirm remote removal. Final admission checks current
1143
- backend facts again. Changing a read default never changes an existing review's
1144
- account or grants new authority to an admitted transaction.
1145
+ Wallet-dependent app inputs (`connect`, `disconnect`, `prepare_review`,
1146
+ `request_signature`) carry the displayed `walletRunId`. A stale run cannot be
1147
+ transferred to a replacement SDK. Exact account, chain, method, grant revision
1148
+ and stored request authority are rechecked at admission. `acceptedWalletRunId`
1149
+ is a stored fact, not new permission.
1150
+
1151
+ In `session_get_interaction_status`, `requestedChains` is the Settings scope for new connections. Singular `connection`
1152
+ publishes its frozen requested scope and `chainResults`: exactly one result per
1153
+ requested chain, either `bound` with an address, `not_approved`, `multiple_accounts`
1154
+ or `invalid_response`. One valid distinct address binds automatically. There is
1155
+ no account selector. Only that chain becomes unavailable on multiple/invalid data.
1156
+ Later observations cannot change those results. Current `grants`, `grantRevisions`
1157
+ and `chainStates` describe availability separately; methods remain account-local.
1158
+ Sui actions require the fixed Sui address and exact Sui method/event scope.
1159
+ Ethereum/Solana address fields do not provide financial authority.
1160
+
1161
+ Both wallet gateways accept empty input. Disconnect creation checks the current
1162
+ exact session before issuing any card or permission. No recorded session or a
1163
+ confirmed absent settled session returns `input_invalid` with reason
1164
+ `no_session_to_disconnect`; unconfirmed or unrecorded presence uses
1165
+ `connection_state_unconfirmed`, and outstanding SDK work uses `operation_busy`.
1166
+ An unavailable service returns `wallet_unavailable` with its actual cause.
1167
+ These refusals create no card, operation or wallet effect. A present or unusable
1168
+ manageable session is fixed to the new Disconnect card; admission rechecks its
1169
+ run and impact. Changing wallet, address or approved network scope requires
1170
+ confirmed disconnection and a new explicit connection.
1171
+
1172
+ Connect fixes requested networks and expected connection identity at creation.
1173
+ A confirmed change before admission closes it failed, sends no wallet request,
1174
+ and asks for a new card; restoring the earlier Settings value does not reopen it.
1175
+ Transient service initialization is not proof of such a change.
1176
+
1177
+ `reviewTarget` retains the Review's original account and connection before,
1178
+ during and after preparation, even when that target is no longer usable.
1179
+ `allowedActions` lists currently permitted app input, computed for that exact
1180
+ target. A live Review's `nextStep` names the applicable recovery action and safe
1181
+ message; the view does not infer it from another connection's status. A replacement
1182
+ connection is never substituted for the original Review target.
1183
+ The interaction-status field `assetReadAccount` independently describes the fixed Sui read address as
1184
+ `available` with `account`, or `address_required`. Reason `read_address_cleared`
1185
+ means the user cleared the saved read address in Settings; this does not change
1186
+ fixed addresses or financial targets. `account_get_active_account` reports stored
1187
+ read context, not current eligibility. Restored public accounts never restore
1188
+ wallet or card authority.
1189
+
1190
+ The status overview returns `connection: null` when no current connection is recorded.
1191
+ `canDisconnect` qualifies the current exact nonpending cleanup target, including
1192
+ terminal or older-generation records whose SDK session is present/unusable.
1193
+ Current-run confirmed absence and ended I/O permit a new explicit Connect; a
1194
+ historical failed/expired row alone is not absence evidence. Recovery can transfer
1195
+ cleanup ownership without restoring usage or old card/signing authority.
1196
+
1197
+ In interaction status, `connectionReconciliationRequired: true` means current SDK presence has no approved
1198
+ product target after pending registration/cleanup. New pairing and financial
1199
+ inputs are blocked; saved evidence remains readable. Unrecorded sessions are not
1200
+ adopted by address or ordering. Remove unwanted retained sessions in the wallet
1201
+ app, then check again. Restarting inspects but neither approves nor removes them.
1202
+ Private topics are not exposed. An already admitted transaction still uses its
1203
+ original exact grant and submission checks.
1204
+
1205
+ These are backend-evaluated facts, not View row counts or clock decisions.
1206
+ `allowedActions` is not model authority. Scoped UI permission and the exact target
1207
+ remain required at atomic admission. Reconnection cannot retarget a Review or an
1208
+ admitted transaction.
1145
1209
 
1146
1210
  Views additionally know whether their own confirmation read or command response
1147
1211
  is pending. They show neutral communication guidance without synthesizing DB
@@ -1190,7 +1254,9 @@ as uncertain without resending them. Neither event establishes cancellation or
1190
1254
  chain failure, and verified chain outcomes remain unchanged.
1191
1255
 
1192
1256
  Wallet-dependent commands rejected for dependency failure use the error kind
1193
- `wallet_unavailable`, with a safe reason and message. Invalid input and domain
1257
+ `wallet_unavailable`, with the actual safe `walletAvailability` and message.
1258
+ An unavailable service includes its recorded `reason`; initializing/recovering
1259
+ states have no failure reason, so none is invented in error details. Invalid input and domain
1194
1260
  conflicts retain their own meaning. Validated app actions can also return a
1195
1261
  current snapshot with `error.code: "wallet_unavailable"`; invalid permissions
1196
1262
  and storage failures do not receive a success snapshot. Review creation can
@@ -1253,27 +1319,64 @@ facts actually exist.
1253
1319
  | --- | --- | --- |
1254
1320
  | `account_get_active_account` | Implemented | Reads the active wallet-account read context. |
1255
1321
 
1256
- The user clears the default read address through a confirmed Settings card action. Ordinary MCP calls do not clear it.
1322
+ Settings provides Clear saved read address for the current Sui read context.
1323
+ The explicit app-only action `settings_clear_read_address` binds the displayed
1324
+ connection and address and records its effect atomically. It suppresses implicit
1325
+ read context for that connection across restarts, without disconnecting the wallet,
1326
+ changing fixed addresses or cancelling transaction requests. A fresh connection
1327
+ can supply its new fixed read address. Ordinary MCP calls cannot apply this effect.
1328
+ Changing from a restore upload to this effect invalidates the unused upload
1329
+ atomically with the saved result. File cleanup runs separately; a cleanup failure
1330
+ does not repeat the address-clearing effect or change its stored outcome.
1257
1331
 
1258
1332
  ## Settings Tools
1259
1333
 
1260
1334
  | Tool | Status | Purpose |
1261
1335
  | --- | --- | --- |
1262
- | `settings_create_local_settings_session` | Implemented | Opens one internal Settings card with an unsubmitted draft. |
1263
- | `settings_get_local_settings` | Implemented | Reads stored/effective Sui gRPC and GraphQL endpoints, sources and pending restart information. |
1336
+ | `settings_create_local_settings_session` | Implemented | Empty input opens Settings. `operationStatus: {operationId}` records a read-only status card. `backupDelivery: {operationId, fileId}` opens a new delivery-purpose card for the exact retained backup. These strict input forms cannot be mixed. |
1337
+ | `settings_get_local_settings` | Implemented | Reads requested wallet networks and stored/effective Sui endpoints, sources and pending restart information. |
1264
1338
 
1265
1339
  The result is a `kind: "settings"` card snapshot
1266
1340
  and a public saved-result link. Card permission is only in `sui-mcp/card` UI
1267
- metadata. There is no `settingsUrl`, `openTarget`, external page, HTTP mutation
1341
+ metadata. Every closed Settings card keeps its recorded result and has empty
1342
+ `allowedActions` and `allowedFileActions`. A fresh `operationStatus` card records
1343
+ current operation/cleanup facts once; its `createdAt` is that query's timestamp,
1344
+ and any stored operation result retains its original `recordedAt`. A current
1345
+ backup-delivery summary is recorded at the query time; do not infer a delivery
1346
+ completion time from that read timestamp. It issues no settings
1347
+ or file effect authority. A new `backupDelivery` card uses the original artifact,
1348
+ owner, epoch and expiry; creating it performs no transfer. Only its explicit Retry
1349
+ download or Save a local copy admits one attempt. A late exact Host report updates
1350
+ the domain journal only; it cannot change a closed card or initiate local saving. There is no `settingsUrl`, `openTarget`, external page, HTTP mutation
1268
1351
  API or compatibility alias. A client without internal cards receives
1269
1352
  `ui_unavailable`; ordinary model calls never apply a Settings change.
1270
1353
 
1271
- Settings groups Address for viewing assets, Local records, Troubleshooting and Advanced
1272
- settings. Confirmed changes are `clear_read_address`, `set_endpoint`,
1273
- `restore_endpoint` (gRPC or GraphQL), `import_local_data`, `reset_local_data`
1274
- and `restart_wallet_service`. Their preparation and confirmation use app-only
1354
+ Settings groups Address for viewing assets, Wallet networks, Local records,
1355
+ Troubleshooting and Advanced settings. Address for viewing assets owns the
1356
+ `settings_clear_read_address` action described under Account Tools; clearing
1357
+ does not disconnect the wallet or change transaction targets.
1358
+
1359
+ Wallet networks uses one explicit Save networks action:
1360
+ `settings_save_wallet_networks` with `operationId`, the selected `chains`, and
1361
+ `expectedChains` containing the saved scope displayed to the user. App-only
1362
+ `ui_act_card` checks the card permission, owner, data epoch, revision and expiry,
1363
+ compares the current saved scope with `expectedChains`, and reserves, saves and
1364
+ records the exact selection in one transaction. Its `data.draft.kind` is
1365
+ `set_wallet_networks`. There is no selection/preparation/confirmation
1366
+ sequence for this setting. An identical admitted save returns its stored result;
1367
+ a conflicting selection cannot replace it. Editing checkboxes does not save,
1368
+ pair a wallet or update an existing connection. Saving a changed scope atomically
1369
+ ends unsent Connect cards with different captured networks; restoring the earlier
1370
+ setting does not reopen those cards. Already admitted wallet requests retain their
1371
+ original scope.
1372
+
1373
+ Endpoint changes (`set_endpoint`, `restore_endpoint` for gRPC or GraphQL),
1374
+ `import_local_data`, `reset_local_data` and `restart_wallet_service` retain a
1375
+ concrete impact confirmation. Selecting an endpoint change, reset or restart
1376
+ starts preparation directly; no intermediate Continue action is required.
1377
+ Selecting a backup file starts its checks. Final confirmation uses app-only
1275
1378
  `ui_act_card` with card permission, revision, operation identity and the exact
1276
- preparation identity. Choosing or checking data does not apply it, contact a
1379
+ preparation identity. Preparing or checking data does not apply it, contact a
1277
1380
  wallet or restart the SDK. Duplicate confirmation returns the same admitted
1278
1381
  result; MCP JSON-RPC request IDs do not authorize another operation.
1279
1382
 
@@ -1281,8 +1384,7 @@ Download backup uses one `settings_download_backup` action with `operationId`
1281
1384
  and an `attemptId` UUID, admitted atomically through the same scoped card input.
1282
1385
  It creates a `download_backup` operation and one immutable snapshot. It requires
1283
1386
  no separate selection, preparation or confirmation action. The same admitted
1284
- start returns the same request; a different start cannot replace it. New
1285
- `export_local_data` selection/preparation/confirmation is not accepted.
1387
+ start returns the same request; a different start cannot replace it.
1286
1388
 
1287
1389
  The card uses plain-language display labels without changing wire fields or
1288
1390
  enums. Wallet-service `available`, `initializing`, `recovering` and `unavailable`
@@ -1320,16 +1422,21 @@ failure-recovery policy.
1320
1422
  `file.sealed` records complete, integrity-checked transfer; it does not by itself
1321
1423
  establish a supported backup or permission to restore it. `settings_back` and user-data
1322
1424
  changes invalidate preparation while preserving a reusable complete file.
1323
- The explicit `settings_prepare` action rechecks such a file; normal file
1324
- selection requires no separate Preview action. A failed check preserves its
1425
+ The explicit `settings_prepare` action rechecks such a file; selecting a file
1426
+ starts its backup check without another action. A failed check preserves its
1325
1427
  current file/operation identity and correction path. Owner replacement ends old
1326
1428
  input; a new card must receive a new explicit file selection.
1327
1429
 
1328
- A download's `result.completionScope: "backup_snapshot"` identifies the immutable
1329
- preparation result, not a saved user file. `data.download` separately carries
1430
+ Physical snapshot readiness is intermediate: the delivery card stays running.
1431
+ Its final `result.completionScope: "backup_delivery"` records a Host report,
1432
+ verified local publication, cancellation, expiry or failure, not merely snapshot
1433
+ preparation. A Host acknowledgment is not proof that a user file was saved. `data.download` separately carries
1330
1434
  `availability` (`preparing`, `available`, `ended`), `currentAttemptId`, an optional
1331
- `hostReport` (`acknowledged`, `not_completed`, `unconfirmed`, `unsupported`), `previousUnconfirmed`,
1332
- `expiresAt`, `remainingMs`, `endReason` and `allowedFileActions`. End reasons are
1435
+ `hostReport` (`acknowledged`, `not_completed`, `unconfirmed`, `unsupported`, `not_sent`), `previousUnconfirmed`,
1436
+ `expiresAt`, `remainingMs`, `endReason` and `allowedFileActions`. `not_sent` is the
1437
+ View's report that transfer verification failed before any Host download request;
1438
+ it is not a Host rejection or non-support response. Like `unsupported`, it
1439
+ establishes no earlier Host copy for local-copy consent. End reasons are
1333
1440
  `acknowledged`, `cancelled`, `expired`, `server_restarted`, `data_replaced`,
1334
1441
  `source_unavailable`, `stored_locally` or `local_save_failed`. Replacement revokes the old card rather than preserving
1335
1442
  its input. The transfer period is thirty minutes from physical readiness;
@@ -1345,13 +1452,12 @@ absence was not established, including an unreported or not-completed request.
1345
1452
 
1346
1453
  A verified local `saved` result provides `data.backupLocation.directory` and
1347
1454
  `filename` for `<SUI_MCP_DATA_DIR>/backups/<operationId>.json`. Snapshot preparation
1348
- and Host acknowledgment do not provide that local success. A recorded
1349
- `export_local_data` result can also identify its existing file. These fields
1350
- never identify the destination chosen by a Host download dialog. Existing user
1455
+ and Host acknowledgment do not provide that local success. These fields never
1456
+ identify the destination chosen by a Host download dialog. Existing user
1351
1457
  files are never deleted by private snapshot cleanup. Private publication
1352
1458
  identities and source inode/device facts are not public projection fields.
1353
1459
 
1354
- Current `data.facts` uses the same connection selection and qualification rules
1460
+ Current `data.facts` uses the same fixed-address and connection qualification rules
1355
1461
  as interaction status, through a fact reader that does not settle another
1356
1462
  request's deadlines or callback writes. General counts describe stored records;
1357
1463
  reset/import preparation and confirmation independently settle deadlines and
@@ -1384,8 +1490,10 @@ recorded idempotently without resending bytes. Public fields include
1384
1490
  local operation, not a transaction's chain outcome. Optional
1385
1491
  `temporaryFileCleanup` separately reports `pending`, `failed` or `complete`;
1386
1492
  reading/checking it never repeats data replacement, backup creation, Host delivery or SDK
1387
- replacement. Terminal business input remains closed; only the separate scoped
1388
- file continuations in `data.download.allowedFileActions` may remain available. Public fields contain no raw file, transaction bytes, signatures,
1493
+ replacement. Terminal business input remains closed; the separate scoped
1494
+ file continuations in `data.download.allowedFileActions` are also closed. A new
1495
+ `backupDelivery` card is required for another attempt, while `operationStatus`
1496
+ reads current cleanup without granting a file effect. Public fields contain no raw file, transaction bytes, signatures,
1389
1497
  SDK credentials or card permission.
1390
1498
 
1391
1499
  A user-data writer invalidates its affected prepared confirmation atomically.
@@ -1404,8 +1512,8 @@ rejection can report a smaller raw chunk limit before any write. The backup chec
1404
1512
  strict current backup shape/references without endpoint contact. Confirmation
1405
1513
  verifies imported endpoints report Sui mainnet and rechecks current data and
1406
1514
  unsettled wallet/transaction work before atomic replacement.
1407
- The prepared import includes `currentReadAddress` and `incomingReadAddress`
1408
- (`null` when unset), the corresponding change and current/incoming record counts.
1515
+ The prepared import includes current/incoming record counts. Accounts and records
1516
+ are restored as history, never as active connection or signing authority.
1409
1517
  Both preparation and final admission settle request deadlines before capturing
1410
1518
  or comparing that decision basis. A newly unknown outcome requires a new backup check.
1411
1519
  Reset/import revoke other live permissions and preserve only their own read-only card/result.
@@ -1417,8 +1525,9 @@ automatic result checks. Stopping those checks does not shorten that window.
1417
1525
  They cannot cancel a transaction on Sui or disconnect a remote wallet session.
1418
1526
  The private connection-service journal is preserved; it is not imported from
1419
1527
  the public backup and cannot restore old permissions or signing authority.
1420
- Reset clears the default address. A restored default requires its exact current
1421
- connection ID and approved address. Outstanding connection SDK callbacks block
1528
+ Reset and restore invalidate the retained connection for financial use. Neither
1529
+ restores a live connection reference; the retained session remains a cleanup
1530
+ target until disconnected. A new explicit connection establishes new fixed addresses. Outstanding connection SDK callbacks block
1422
1531
  replacement along with unsettled transaction work.
1423
1532
 
1424
1533
  Endpoint preparation records the gRPC/GraphQL kind, current stored/effective
@@ -1439,9 +1548,10 @@ The View checks the complete hash before standard Host delivery.
1439
1548
  File continuations also use app-only `ui_act_card`:
1440
1549
 
1441
1550
  - `settings_retry_download`: `operationId`, `fileId`, `previousAttemptId` and a
1442
- new `attemptId`; atomically advances one attempt on the same live snapshot.
1551
+ new `attemptId`; only a new backup-delivery card may admit this attempt on the
1552
+ same retained snapshot. It consumes that card's one delivery input.
1443
1553
  - `settings_report_download`: `operationId`, `fileId`, `attemptId` and `status`
1444
- (`acknowledged`, `not_completed`, `unconfirmed`, `unsupported`); the same report is idempotent,
1554
+ (`acknowledged`, `not_completed`, `unconfirmed`, `unsupported`, `not_sent`); the same report is idempotent,
1445
1555
  and conflicting reports for one attempt are rejected. A late older report
1446
1556
  cannot change the current attempt or end its retention. `unsupported` requires
1447
1557
  exactly `failure: {method: "ui/download-file", code: -32601}`; other statuses
@@ -1454,34 +1564,39 @@ File continuations also use app-only `ui_act_card`:
1454
1564
  - `settings_cancel_download`: `operationId`, `fileId` and `attemptId`; ends
1455
1565
  further delivery of that snapshot, not a Host dialog or a user-saved file.
1456
1566
  Cancellation is refused while a local save is in progress or its outcome is
1457
- uncertain. After a failure recorded as `not_published`, cancellation remains
1458
- available within the transfer period for the current authorized request.
1567
+ uncertain. A finished failed delivery has no further cancellation or retry input;
1568
+ another attempt requires a new delivery card.
1459
1569
  - `settings_store_backup`: `operationId`, `fileId`, current `attemptId`, a new
1460
1570
  `saveAttemptId`, required boolean `allowPossibleCopy`, and optional
1461
1571
  `previousSaveAttemptId`. It is available only for that snapshot's recorded
1462
- unsupported result. Possible earlier delivery requires explicit true consent;
1572
+ unsupported result and a new delivery-purpose card. Possible earlier delivery requires explicit true consent;
1463
1573
  otherwise false is required. Initial consent has no previous save ID. A retry
1464
1574
  of a confirmed no-publication failure must name the current failed save ID.
1465
1575
  IDs and consent are immutable per admission; duplicates do not repeat effects.
1466
1576
  It accepts no arbitrary path, name or bytes.
1467
1577
 
1468
1578
  These actions validate current owner, epoch, credential and exact file/attempt
1469
- identity independently of terminal business input. Retry/read requires a live
1470
- transfer period. A late report can record a fact after that period ends but
1579
+ identity. Effect admissions and file reads require an active purpose card and the
1580
+ original live transfer period. Closed cards grant none of these effect permissions.
1581
+ Only an exact late result report may update an already-admitted attempt's journal,
1582
+ without modifying its closed card or starting publication. A late report can record a fact after that period ends but
1471
1583
  cannot restore the file or authority. Host acknowledgment ends retention and
1472
1584
  requests cleanup; it does not prove a save location or completed disk storage.
1473
1585
  `isError` does not distinguish cancellation, denial or failure. A lost response
1474
1586
  is unconfirmed and never triggers automatic retransmission. Cleanup failure is
1475
- reported separately and is retried through Check status or owner recovery.
1587
+ reported separately; a new operation-status card or owner recovery can settle
1588
+ known cleanup without repeating the original effect.
1476
1589
  Local publication closes further Host reads/retries for that snapshot. Its
1477
- final/file-I/O reservations survive the immutable terminal snapshot result.
1590
+ file-I/O reservation lasts until the actual admitted file work ends, independently
1591
+ of the immutable card result.
1478
1592
  New save admissions and retries require the original live period; admitted
1479
1593
  file work settles even if it outlives that period. A process restart verifies
1480
1594
  only an existing target bound to its recorded source identity/content. It never
1481
1595
  publishes a missing target or restores the departed card's action authority.
1482
1596
  A missing or changed source ends that private transfer; a new explicit request
1483
- is required. An existing public backup is verified on the same descriptor used
1484
- for each range and is never truncated or removed by temporary cleanup.
1597
+ is required. Private snapshot reads verify the artifact on the same descriptor
1598
+ used for each range. Temporary cleanup never truncates or removes a saved
1599
+ local backup.
1485
1600
 
1486
1601
  Troubleshooting recovery confirms a precise SDK run and affected unsubmitted
1487
1602
  requests. Admission revokes their submission authority before stopping the old