@zktx.io/sui-mcp 0.5.0 → 0.6.0

package/dist/core/session/walletWorkflow.js

@@ -1,3 +1,4 @@
+import { workflowConnectionEligibility } from "./workflowState.js";
 import { SessionStoreError } from "./sessionErrors.js";
 import { Transaction } from "@mysten/sui/transactions";
 import { verifyTransactionSignature } from "@mysten/sui/verify";
@@ -18,7 +19,11 @@ export class WalletWorkflow {
     observing = new Map();
     preparing = new Set();
     pendingWrites = new Map();
+    // Child exit ends child I/O, not verification or submit work already running
+    // in this parent. The owning signature continuation alone ends that work.
+    parentSignatureWork = new Set();
     eventListener;
+    settingsRecovery;
     constructor(options) {
         this.options = options;
     }
@@ -48,6 +53,7 @@ export class WalletWorkflow {
         if (this.started)
             throw new WorkflowConflict("The wallet service has already started.");
         this.started = true;
+        this.options.records.setWalletRunId(this.options.runtime.runId);
         this.options.records.recover(this.now());
         this.bindEvents();
         this.options.runtime.start((event) => this.eventListener?.(event));
@@ -61,9 +67,11 @@ export class WalletWorkflow {
             return;
         const runtime = this.options.runtime;
         if (event.type === "snapshot") {
-            this.options.records.applyWalletObservation(event.snapshot, event.previous, event.ready);
-            if (event.ready)
+            this.options.records.applyWalletObservation(event.snapshot, event.previous, event.ready, () => this.settingsRecovery?.runtimeEvent(event));
+            if (event.ready) {
                 runtime.publishReady(event.runId);
+                this.settingsRecovery?.readyPublished(event.runId);
+            }
         }
         else if (event.type === "stage") {
             this.options.records.publishWalletState();
@@ -71,8 +79,38 @@ export class WalletWorkflow {
         else if (event.type === "lost") {
             this.pairings.clear();
             this.retainWrite({ kind: "runtime_failure", runId: event.runId, observedAt: this.now().toISOString() });
+            this.settingsRecovery?.runtimeEvent(event);
+        }
+        else if (event.type === "exit") {
+            this.retainWrite({ kind: "runtime_exit", runId: event.runId, observedAt: this.now().toISOString(), parentProcessing: [...this.parentSignatureWork] });
         }
     }
+    attachSettingsRecovery(recovery) {
+        if (this.settingsRecovery)
+            throw new Error("Settings recovery is already attached.");
+        this.settingsRecovery = recovery;
+    }
+    recoveryContext() {
+        this.synchronizeWalletState();
+        return this.currentRecoveryFacts();
+    }
+    currentRecoveryFacts() {
+        return { availability: this.walletAvailability(), impact: this.options.records.recoveryImpact(this.options.runtime.runId) };
+    }
+    blockSettingsAdmissionFailure() {
+        const runId = this.options.runtime.runId;
+        this.options.runtime.block("wallet_state_unavailable");
+        this.retainWrite({ kind: "runtime_failure", runId, observedAt: this.now().toISOString() });
+    }
+    fenceForSettings(runId) { this.assertCurrent(); this.options.runtime.fence(runId); }
+    replaceForSettings(runId, reserve) {
+        this.assertCurrent();
+        return this.options.runtime.replace(runId, (nextRunId) => {
+            this.synchronizeWalletState();
+            reserve(nextRunId);
+            this.options.records.setWalletRunId(nextRunId);
+        });
+    }
     dataReplaced() {
         this.pairings.clear();
         this.pendingWrites.clear();
@@ -99,7 +137,7 @@ export class WalletWorkflow {
         catch {
             return;
         }
-        const key = completion.kind === "runtime_failure" ? `runtime:${completion.runId}` :
+        const key = completion.kind === "runtime_failure" || completion.kind === "runtime_exit" ? `${completion.kind}:${completion.runId}` :
             completion.kind === "request" ? `request:${completion.id}:${completion.field}` : `connection:${completion.cardId}:${completion.runId}`;
         if (!this.pendingWrites.has(key))
             this.pendingWrites.set(key, completion);
@@ -115,7 +153,9 @@ export class WalletWorkflow {
             this.options.records.settle(completion.id, completion.field, false);
         else if (completion.kind === "connection")
             this.options.records.settleConnection(completion.id, completion);
-        else if (completion.runId === this.options.runtime.runId)
+        else if (completion.kind === "runtime_exit")
+            this.options.records.recordRunExit(completion.runId, completion.parentProcessing);
+        else
             this.options.records.recordWalletFailure(completion);
         this.pendingWrites.delete(key);
     }
@@ -137,6 +177,8 @@ export class WalletWorkflow {
         // read recorded facts. Retain failed repairs for the next applicable read.
         if (failure && walletDependent)
             throw failure;
+        if (walletDependent)
+            this.settingsRecovery?.synchronize();
         if (walletDependent)
             this.options.runtime.synchronize();
     }
@@ -159,16 +201,27 @@ export class WalletWorkflow {
         }
         return { status: "ready" };
     }
-    readConnectionContext() {
+    reconcileConnectionContext() {
         this.assertCurrent();
         this.synchronizeWalletState();
         this.recoverDisconnects();
-        const state = this.options.records.evaluate({ walletAvailability: this.walletAvailability(), walletObservation: this.observation() });
-        // Current-owner rows are published by the same SDK observation/admission
-        // transactions that gate availability. Use their evaluated selection in
-        // every consumer instead of deriving another default from address matches.
-        return { connections: state.connections, connectionConflict: state.connectionConflict, walletAvailability: state.walletAvailability, walletObservation: this.observation(),
-            assetReadAccount: state.assetReadAccount ?? { status: "address_required" } };
+        const state = this.options.records.reconcileAndEvaluate({ purpose: "current_wallet", walletAvailability: this.walletAvailability(), walletObservation: this.observation() });
+        return { connections: state.connections, connectionConflict: state.connectionConflict, walletAvailability: state.walletAvailability,
+            walletObservation: state.walletObservation, manageableConnectionIds: state.manageableConnectionIds,
+            connectionReconciliationRequired: state.connectionReconciliationRequired, assetReadAccount: state.assetReadAccount ?? { status: "address_required" } };
+    }
+    // Diagnostic facts are collected without maintenance. Reconciliation and
+    // admission own durable transitions and cannot use this snapshot as authority.
+    currentConnectionContext() {
+        this.assertCurrent();
+        const facts = this.options.records.readConnectionFacts(this.now()), availability = this.walletAvailability();
+        const { selection: _selection, ...eligibility } = workflowConnectionEligibility({ ...facts, walletAvailability: availability });
+        // The shared projection gates qualification on published availability;
+        // a memory snapshot alone does not prove its journal/result has committed.
+        return { connections: facts.connections, walletAvailability: availability, walletObservation: facts.walletObservation,
+            connectionConflict: eligibility.connectionConflict, manageableConnectionIds: eligibility.manageableConnectionIds,
+            connectionReconciliationRequired: eligibility.connectionReconciliationRequired,
+            assetReadAccount: eligibility.assetReadAccount ?? { status: "address_required" } };
     }
     recoverDisconnects() {
         const available = this.walletAvailability().status === "available";
@@ -194,7 +247,9 @@ export class WalletWorkflow {
             this.options.records.failPreparation(id, preparation, this.now());
         const candidate = await this.options.sessions.inspectReview(id, this.now());
         this.assertCurrent();
-        const evaluated = this.options.records.evaluate({ reviewSessionId: id, candidate, expectedCard, readTarget,
+        if (!candidate)
+            throw new SessionStoreError("session_not_found", "The saved review is unavailable.");
+        const evaluated = this.options.records.reconcileAndEvaluate({ purpose: "review", reviewSessionId: id, candidate, expectedCard, readTarget,
             walletAvailability: this.walletAvailability(), walletObservation: this.observation(), uiObservation });
         this.options.sessions.recordEvaluationEvents(evaluated.events);
         return evaluated;
@@ -216,15 +271,16 @@ export class WalletWorkflow {
         if (!state.session)
             return undefined;
         return { session: state.session, request: state.request, hasReviewInput: state.hasReviewInput, connectionConflict: state.connectionConflict, walletAvailability: state.walletAvailability, walletObservation: this.observation(),
+            connectionReconciliationRequired: state.connectionReconciliationRequired,
             progress: reviewProgress(!!state.session.preparationId, state.request, state.walletAvailability, { stopped: state.authority?.observation_stopped === 1, pending: state.authority?.lookup_pending === 1 }) };
     }
     async describe(record, uiObservation = false) {
         this.assertCurrent();
         if (record.state.kind === "connect")
-            this.readConnectionContext();
+            this.reconcileConnectionContext();
         const evaluated = record.state.kind === "review"
             ? await this.evaluateReview(String(record.state.input.reviewSessionId), record, uiObservation)
-            : this.options.records.evaluate({ expectedCard: record, walletAvailability: this.walletAvailability(), walletObservation: this.observation() });
+            : this.options.records.reconcileAndEvaluate({ purpose: "current_wallet", expectedCard: record, walletAvailability: this.walletAvailability(), walletObservation: this.observation() });
         this.assertCurrent();
         if (record.state.kind === "connect") {
             const data = projectConnectionView(evaluated);
@@ -444,6 +500,7 @@ export class WalletWorkflow {
             await this.performSignature(request, connectionId, bytesBase64, run);
         }
         finally {
+            this.parentSignatureWork.delete(request.attemptId);
             this.completeCallback({ kind: "request", id: request.attemptId, field: "sdk_pending" });
         }
     }
@@ -458,6 +515,7 @@ export class WalletWorkflow {
             this.assertWalletAvailable(run);
             response = await run.sign({ topic: connection.topic, account: request.account, transactionBytesBase64: bytesBase64,
                 sessionVersion: proof.observed.version }, request.attemptId);
+            this.parentSignatureWork.add(request.attemptId);
             this.assertWalletAvailable(run);
         }
         catch {
@@ -581,7 +639,7 @@ export class WalletWorkflow {
         this.recoverDisconnects();
         const rows = [];
         for (const card of this.options.records.pendingConnectionCards(this.now())) {
-            const evaluated = this.options.records.evaluate({ expectedCard: card, walletAvailability: this.walletAvailability(), walletObservation: this.observation() });
+            const evaluated = this.options.records.reconcileAndEvaluate({ purpose: "current_wallet", expectedCard: card, walletAvailability: this.walletAvailability(), walletObservation: this.observation() });
             if (evaluated.record?.state.state === "closed")
                 continue;
             const data = projectConnectionView(evaluated);

package/dist/core/session/workflowState.js

@@ -15,6 +15,18 @@ export function reviewPreparationAccount(boundAccount, activeAccount, selectedAc
             message: "The selected account has changed since this request was made." };
     return { allowed: true, account: activeAccount };
 }
+export function workflowConnectionEligibility(facts) {
+    const selection = walletConnectionSelection(facts.connections, Date.parse(facts.evaluatedAt), facts.connectionPresence, facts.activeAccount ? { address: facts.activeAccount, walletId: facts.activeAccountConnectionId } : undefined);
+    const available = facts.walletAvailability.status === "available", dependent = facts.walletDependent !== false;
+    const usableConnectionId = available && dependent ? selection.connection?.connectionId : undefined;
+    const assetReadAccount = !dependent ? undefined
+        : usableConnectionId ? selection.assetReadAccount : { status: "address_required" };
+    return { selection, usableConnectionId, assetReadAccount, connectionConflict: selection.conflict,
+        manageableConnectionIds: available ? selection.manageableConnectionIds : [],
+        // A pending memory snapshot is not a published SDK observation. Startup
+        // and state-sync failures retain their own result and neutral diagnosis.
+        connectionReconciliationRequired: available && dependent ? selection.connectionReconciliationRequired : undefined };
+}
 // Shared domain eligibility. The DB supplies current facts at its decision
 // boundary. Returned choices are advisory; admission still binds concrete input.
 export function workflowEligibility(facts) {
@@ -27,12 +39,8 @@ export function workflowEligibility(facts) {
         ? Math.min(cardRemaining, Math.max(0, Date.parse(session.expiresAt) - at)) : cardRemaining;
     const inputAvailable = remaining > 0 && record?.state.state === "ready" && record.acceptedInput === undefined;
     const allowedActions = [];
-    const selection = walletConnectionSelection(facts.connections, at, facts.activeAccount
-        ? { address: facts.activeAccount, walletId: facts.activeAccountConnectionId } : undefined);
-    const usableConnectionId = walletAvailability.status === "available" && facts.walletDependent !== false
-        ? selection.connection?.connectionId : undefined;
-    const assetReadAccount = facts.walletDependent === false ? undefined
-        : usableConnectionId ? selection.assetReadAccount : { status: "address_required" };
+    const { selection, ...connectionEligibility } = workflowConnectionEligibility(facts);
+    const { assetReadAccount } = connectionEligibility;
     let preparationIssue;
     if (record?.scope === "connect") {
         if (inputAvailable) {
@@ -40,7 +48,7 @@ export function workflowEligibility(facts) {
             if (walletAvailability.status === "available") {
                 if (["connect", "manage"].includes(String(record.state.input.intent)) && selection.pairingAllowed)
                     allowedActions.push("connect");
-                if (facts.connections.some((item) => item.status === "connected" && !item.pendingAction))
+                if (selection.manageableConnectionIds.length)
                     allowedActions.push("disconnect");
                 if (selection.connection)
                     allowedActions.push("use_account");
@@ -74,7 +82,7 @@ export function workflowEligibility(facts) {
         session.status === "ready_for_wallet_review" && (!request || request.reviewRevision !== session.reviewRevision)
         ? session.reviewState?.humanReadableReview?.freshness.expiresAt : undefined;
     const nextRead = expiry && session ? Math.min(remaining, Date.parse(session.expiresAt) - at, Date.parse(expiry) - at) : undefined;
-    return { allowedActions, preparationIssue, usableConnectionId, assetReadAccount, connectionConflict: selection.conflict,
+    return { allowedActions, preparationIssue, ...connectionEligibility,
         actionRemainingMs: remaining, inputRemainingMs: inputAvailable ? remaining : 0,
         ...(nextRead !== undefined && nextRead > 0 ? { nextStateReadAfterMs: nextRead } : {}) };
 }

package/dist/core/session/workflowView.js

@@ -37,6 +37,8 @@ export const workflowViewSchema = z.object({
     walletObservation: walletObservationSchema.optional(),
     runtimeRecovery: walletRecoverySchema.optional(),
     connectionConflict: connectionConflictSchema.optional(),
+    manageableConnectionIds: z.array(z.string().min(1)),
+    connectionReconciliationRequired: z.literal(true).optional(),
     usableConnectionId: z.string().min(1).optional(),
     assetReadAccount: assetReadAccountSchema.optional(),
     acceptedWalletRunId: walletRunIdSchema.optional(),
@@ -60,10 +62,19 @@ export const workflowViewSchema = z.object({
 }).strict().superRefine((view, context) => {
     const connection = view.connections.find((item) => item.connectionId === view.usableConnectionId);
     if (view.usableConnectionId && (!connection || connection.status !== "connected" ||
-        view.walletAvailability.status !== "available" || view.connectionConflict ||
+        view.walletAvailability.status !== "available" || view.connectionConflict || view.connectionReconciliationRequired ||
         view.connections.some((item) => item.pendingAction || item.status === "awaiting_approval"))) {
         context.addIssue({ code: "custom", path: ["usableConnectionId"], message: "The usable connection must match current connection facts." });
     }
+    if (new Set(view.manageableConnectionIds).size !== view.manageableConnectionIds.length ||
+        view.manageableConnectionIds.some((id) => !view.connections.some((item) => item.connectionId === id &&
+            !item.pendingAction && item.status !== "awaiting_approval"))) {
+        context.addIssue({ code: "custom", path: ["manageableConnectionIds"], message: "Management must name distinct recorded targets without pending operations." });
+    }
+    if (view.connectionReconciliationRequired && (view.usableConnectionId || view.assetReadAccount?.status === "available" ||
+        view.allowedActions.some((action) => ["connect", "use_account", "prepare_review", "request_signature"].includes(action)))) {
+        context.addIssue({ code: "custom", path: ["connectionReconciliationRequired"], message: "Unrecorded SDK connections cannot authorize connection or account use." });
+    }
     if (view.assetReadAccount?.status === "available" && (!connection ||
         !connection.accounts.includes(view.assetReadAccount.account) || view.activeAccount !== view.assetReadAccount.account)) {
         context.addIssue({ code: "custom", path: ["assetReadAccount"], message: "The default address must belong to the usable connection and stored selection." });
@@ -104,7 +115,10 @@ function nextStateRead(input) {
 // These projections do not read clocks, storage, or admission rules. The
 // evaluated facts and choices were collected together by the database owner.
 export function projectConnectionView(input) {
-    const { connection, walletAvailability } = input;
+    const { walletAvailability } = input;
+    const stored = input.record?.state.data;
+    const connection = input.record?.acceptedInput?.action === "disconnect" && stored?.disconnectOutcome
+        ? connectionViewSchema.parse(stored.disconnectOutcome) : input.connection;
     const readAfter = nextStateRead(input);
     const progress = input.runtimeRecovery ? { status: "phase" in input.runtimeRecovery ? "waiting" : "idle" } :
         workflowProgress(connection?.status === "awaiting_approval" || connection?.pendingAction === "disconnect", true, walletAvailability);
@@ -114,6 +128,7 @@ export function projectConnectionView(input) {
             ? { automaticAction: { action: "connect", walletRunId: walletAvailability.walletRunId } } : {}),
         runtimeRecovery: input.runtimeRecovery, walletObservation: input.walletObservation,
         connectionConflict: input.connectionConflict, usableConnectionId: input.usableConnectionId, assetReadAccount: input.assetReadAccount,
+        manageableConnectionIds: input.manageableConnectionIds, connectionReconciliationRequired: input.connectionReconciliationRequired,
         connectionAction: ["connect", "disconnect"].includes(String(input.record?.acceptedInput?.action)) ? input.record?.acceptedInput?.action : undefined,
         acceptedWalletRunId: input.record?.acceptedInput?.walletRunId,
         ...(readAfter === undefined ? {} : { nextStateReadAfterMs: readAfter }),
@@ -133,6 +148,7 @@ export function projectReviewView(input) {
     return workflowViewSchema.parse({ kind: "review", mode: record.scope === "review_manage" ? "review_manage" : "review",
         allowedActions: input.allowedActions, actionRemainingMs: input.actionRemainingMs, observe: progress.status === "waiting", progress, walletAvailability,
         connections: input.connections, connectionConflict: input.connectionConflict, usableConnectionId: input.usableConnectionId,
+        manageableConnectionIds: input.manageableConnectionIds, connectionReconciliationRequired: input.connectionReconciliationRequired,
         assetReadAccount: input.assetReadAccount, activeAccount: input.activeAccount, boundary: REVIEW_BOUNDARY, receipt: input.receipt,
         walletObservation: input.walletObservation,
         acceptedWalletRunId: record.acceptedInput?.walletRunId,

package/dist/mcp/responseGuidance.js

@@ -1,6 +1,6 @@
 import { EXTERNAL_PROPOSAL_SETTLEMENT_TOKEN_SELECTION_UNSUPPORTED_CLAIM_ID } from "../core/proposal/types.js";
 import { TOOL_NAMES } from "./toolNames.js";
-export function interactionStatusUserAnswerUse(hasWalletObservation = false, hasConnectionConflict = false) {
+export function interactionStatusUserAnswerUse(hasWalletObservation = false, hasConnectionConflict = false, reconciliationRequired = false) {
     return {
         canAnswer: [
             "stored_active_account_read_context",
@@ -8,6 +8,7 @@ export function interactionStatusUserAnswerUse(hasWalletObservation = false, has
             "connection_qualified_default_asset_account",
             "pending_local_wallet_connection_interactions",
             ...(hasConnectionConflict ? ["multiple_saved_connections_require_user_targeted_disconnection"] : []),
+            ...(reconciliationRequired ? ["unrecorded_service_connection_requires_wallet_removal_and_confirmed_absence"] : []),
             "pending_local_review_interactions",
             "wallet_operation_availability_separate_from_stored_transaction_facts"
         ],
@@ -24,9 +25,11 @@ export function interactionStatusUserAnswerUse(hasWalletObservation = false, has
             "complete_wallet_history",
             "profit_or_pnl"
         ],
-        preconditionFields: ["walletAvailability", "assetReadAccount", ...(hasConnectionConflict ? ["connectionConflict"] : [])],
+        preconditionFields: ["walletAvailability", "assetReadAccount", ...(hasConnectionConflict ? ["connectionConflict"] : []),
+            ...(reconciliationRequired ? ["connectionReconciliationRequired"] : [])],
         answerFields: ["activeAccount", "connections", "assetReadAccount", "pendingWalletConnections", "pendingReviewSessions", "walletAvailability",
             ...(hasConnectionConflict ? ["connectionConflict"] : []),
+            "manageableConnectionIds", ...(reconciliationRequired ? ["connectionReconciliationRequired"] : []),
             ...(hasWalletObservation ? ["walletObservation"] : [])],
         diagnosticOnlyFields: [
             "pendingWalletConnections.truncated",
@@ -66,7 +69,8 @@ export function executionResultUserAnswerUse(fields = {}) {
             "profit_or_pnl"
         ],
         answerFields: [
-            "walletAvailability", "progress", ...(fields.hasConnectionConflict ? ["connectionConflict"] : []), ...(hasWaitOutcome ? ["waitOutcome"] : []),
+            "walletAvailability", "progress", ...(fields.hasConnectionConflict ? ["connectionConflict"] : []),
+            ...(fields.reconciliationRequired ? ["connectionReconciliationRequired"] : []), ...(hasWaitOutcome ? ["waitOutcome"] : []),
             "reviewSessionId",
             "status",
             "pollingStatus",
@@ -91,7 +95,7 @@ export function executionResultUserAnswerUse(fields = {}) {
         }
     };
 }
-export function reviewStatusUserAnswerUse(hasReviewState, hasAdapterLifecycle = false, hasHumanReadableReview = false, hasSimulation = false, hasConnectionConflict = false) {
+export function reviewStatusUserAnswerUse(hasReviewState, hasAdapterLifecycle = false, hasHumanReadableReview = false, hasSimulation = false, hasConnectionConflict = false, reconciliationRequired = false) {
     return {
         canAnswer: [
             "current_local_review_session_status",
@@ -115,7 +119,8 @@ export function reviewStatusUserAnswerUse(hasReviewState, hasAdapterLifecycle =
             "profit_or_pnl"
         ],
         answerFields: [
-            "walletAvailability", "progress", ...(hasConnectionConflict ? ["connectionConflict"] : []), "reviewSessionId",
+            "walletAvailability", "progress", ...(hasConnectionConflict ? ["connectionConflict"] : []),
+            ...(reconciliationRequired ? ["connectionReconciliationRequired"] : []), "reviewSessionId",
             "status",
             "pollingStatus",
             "statusCategory",

package/dist/mcp/serverInfo.js

@@ -50,11 +50,11 @@ export const SERVER_INSTRUCTIONS = [
     "For USD-denominated payment coverage, balance total, or shortfall questions, call read.get_server_status, then read.list_settlement_asset_groups, then read.preview_intent_evidence. Use toolAvailability.requiredToolsAvailable and responseSummary.doNotCallQuoteToolsForThisQuestion; do not call wallet inventory or quote tools unless user asks a separate inventory or conversion question. For parity, use read.summarize_settlement_asset_group_parity. If toolAvailability cannot be used, say the current MCP server build cannot support the answer.",
     "The active account context is read-only, not login, custody or signing permission. Implicit asset reads require session.get_interaction_status.assetReadAccount: available. Otherwise ask for an address only if the tool accepts account; connected-only tools require connection/account selection or wallet recovery.",
     "Unsupported: other chains, autonomous trading, alerts, investment advice, arbitrary Move/package calls, P&L/tax.",
-    "One wallet connection at a time; guidance: suimcp://docs/agent-behavior."
+    "One wallet connection at a time; docs: suimcp://docs/agent-behavior, suimcp://docs/mcp-tools."
 ].join("\n");
 export const IMPLEMENTED_TOOLS = [
     TOOL_NAMES.uiOpenAccount, TOOL_NAMES.uiOpenReceipt, TOOL_NAMES.uiOpenChart,
-    TOOL_NAMES.uiReadCard, TOOL_NAMES.uiSubmitCard, TOOL_NAMES.uiActCard,
+    TOOL_NAMES.uiReadCard, TOOL_NAMES.uiSubmitCard, TOOL_NAMES.uiActCard, TOOL_NAMES.uiReadSettingsFile,
     TOOL_NAMES.readGetServerStatus,
     TOOL_NAMES.readListSupportedProtocols,
     TOOL_NAMES.readListDeepbookPools,
@@ -86,7 +86,6 @@ export const IMPLEMENTED_TOOLS = [
     TOOL_NAMES.actionPrepareSuiActionReview,
     TOOL_NAMES.actionPrepareExternalProposalReview,
     TOOL_NAMES.accountGetActiveAccount,
-    TOOL_NAMES.accountClearActiveAccount,
     TOOL_NAMES.sessionCreateWalletConnection,
     TOOL_NAMES.sessionGetWalletConnection,
     TOOL_NAMES.sessionWaitWalletConnection,
@@ -127,5 +126,5 @@ export const SERVER_LIMITATIONS = [
     `DeepBook orderbook, mid-price, and quote outputs are ${DEEPBOOK_SOURCE_OWNER_RUNTIME_WORDING.pinnedSdkSnapshots} at fetchedAt; treat them as stale if the user delays.`,
     `DeepBook USDC price history and price-at-time reads use ${DEEPBOOK_SOURCE_OWNER_RUNTIME_WORDING.officialIndexerCandleData} for the requested official interval. They are external candle evidence only, not live quotes, historical mid prices, global market prices, fiat USD values, USDC/USD peg guarantees, route recommendations, transaction-building inputs, signing readiness, P&L, cost basis, user-account transaction history, or user-account balance history. Sui MCP does not independently recompute those candle values from chain history for the response.`,
     `ui.open_chart displays ${DEEPBOOK_SOURCE_OWNER_RUNTIME_WORDING.officialIndexerUsdcDenominatedCandles} in an internal read-only card. ui.open_account displays a public-address asset snapshot; ui.open_receipt displays the executed transaction graph when bound UI metadata is available, followed by on-chain facts and a Details slide. Card inputs end after backend admission, expiry or invalidation; chat navigation and frame recreation do not end valid unsubmitted input. Read the same DB state after a lost reply rather than resubmitting. Saved results do not authorize a new query or transaction. These cards are not live feeds, trading interfaces, route recommendations, fiat USD value, P&L, tax, cost basis, signing data, or signing readiness.`,
-    "Settings mutations happen through local settings pages on the review server. MCP settings tools create settings sessions or read current settings only."
+    "Settings uses an internal card. MCP settings tools create the card or read current settings; only the user's scoped card confirmation applies local changes or restarts the connection service. Backup bytes stay in app-only file transfer. No external Settings URL exists."
 ];

package/dist/mcp/toolNames.js

@@ -5,6 +5,7 @@ export const TOOL_NAMES = {
     uiReadCard: "ui.read_card",
     uiSubmitCard: "ui.submit_card",
     uiActCard: "ui.act_card",
+    uiReadSettingsFile: "ui.read_settings_file",
     sessionOpenReviewManagement: "session.open_review_management",
     readGetServerStatus: "read.get_server_status",
     readListSupportedProtocols: "read.list_supported_protocols",
@@ -43,8 +44,7 @@ export const TOOL_NAMES = {
     sessionGetReviewStatus: "session.get_review_status",
     sessionGetExecutionResult: "session.get_execution_result",
     sessionWaitExecutionResult: "session.wait_execution_result",
-    accountGetActiveAccount: "account.get_active_account",
-    accountClearActiveAccount: "account.clear_active_account"
+    accountGetActiveAccount: "account.get_active_account"
 };
 export function assertValidToolName(name) {
     if (!/^[A-Za-z0-9_.-]{1,128}$/.test(name)) {

package/dist/mcp/tools/account/index.js

@@ -1,8 +1,7 @@
 import { z } from "zod";
 import { activeAccountResponse, activeAccountResponseSchema } from "../../activeAccountResponse.js";
-import { registerSuiMcpTool } from "../../registerTool.js";
 import { okToolResult } from "../../result.js";
-import { noParamsInputSchema, successOutputSchema } from "../../schemas.js";
+import { noParamsInputSchema } from "../../schemas.js";
 import { activityStoreToolError } from "../../toolErrors.js";
 import { TOOL_NAMES } from "../../toolNames.js";
 export function registerAccountTools(server, deps) {
@@ -24,21 +23,4 @@ export function registerAccountTools(server, deps) {
             return activityStoreToolError(error, deps.logger);
         }
     });
-    registerSuiMcpTool(server, TOOL_NAMES.accountClearActiveAccount, {
-        title: "Clear active account read context",
-        description: "Remove the active read context. Does not disconnect a wallet or revoke onchain permission.",
-        inputSchema: noParamsInputSchema,
-        outputSchema: successOutputSchema({
-            status: z.literal("cleared")
-        }),
-        annotations: { readOnlyHint: false, openWorldHint: false }
-    }, async () => {
-        try {
-            await deps.activityStore.clearActiveAccount();
-            return okToolResult({ status: "cleared" });
-        }
-        catch (error) {
-            return activityStoreToolError(error, deps.logger);
-        }
-    });
 }

package/dist/mcp/tools/read/readToolHelpers.js

@@ -1,4 +1,4 @@
-import { CONNECTION_CONFLICT_MESSAGE } from "../../../core/session/walletConnection.js";
+import { CONNECTION_CONFLICT_MESSAGE, CONNECTION_RECONCILIATION_MESSAGE } from "../../../core/session/walletConnection.js";
 import { ReadServiceCacheError, ReadServiceInputError } from "../../../core/read/readService.js";
 import { parseSuiAddress } from "../../../core/suiAddress.js";
 import { errorToolResult } from "../../result.js";
@@ -41,7 +41,7 @@ export async function resolveExplicitOrActiveAccount(input, deps) {
         };
     }
     try {
-        const context = deps.workflow?.readConnectionContext();
+        const context = deps.workflow?.reconcileConnectionContext();
         if (context?.assetReadAccount.status === "available")
             return { status: "ok", account: context.assetReadAccount.account };
         const availability = context?.walletAvailability ?? walletUnavailable("initialization_failed");
@@ -51,13 +51,14 @@ export async function resolveExplicitOrActiveAccount(input, deps) {
                         details: { ...(availability.status === "unavailable" ? { reason: availability.reason } : {}), message: availability.message, walletAvailability: availability } }) };
             return { status: "error", result: errorToolResult({ kind: active ? "input_invalid" : "active_account_not_set",
                     details: { reason: "connected_account_required",
-                        message: context?.connectionConflict ? CONNECTION_CONFLICT_MESSAGE : "This tool requires a selected account with a usable wallet connection. An address alone cannot be used.",
+                        message: context?.connectionReconciliationRequired ? CONNECTION_RECONCILIATION_MESSAGE : context?.connectionConflict ? CONNECTION_CONFLICT_MESSAGE : "This tool requires a selected account with a usable wallet connection. An address alone cannot be used.",
                         ...(context?.connectionConflict ? { connectionConflict: context.connectionConflict } : {}),
+                        ...(context?.connectionReconciliationRequired ? { connectionReconciliationRequired: true } : {}),
                         followUp: { tool: TOOL_NAMES.sessionGetInteractionStatus,
                             answerFields: ["walletAvailability", "connections", "pendingWalletConnections", "assetReadAccount"],
                             reason: `Check current connections and pending operations. Use pendingWalletConnections.items[].cardId with ${TOOL_NAMES.sessionGetWalletConnection} or ${TOOL_NAMES.sessionWaitWalletConnection}. If no operation is pending and the user requests connection or account selection, open ${TOOL_NAMES.sessionCreateWalletConnection}. Only the user may act in that card.` } } }) };
         }
-        const message = context?.connectionConflict ? CONNECTION_CONFLICT_MESSAGE + " Provide a Sui address in chat for this public read." : availability.status !== "available"
+        const message = context?.connectionReconciliationRequired ? CONNECTION_RECONCILIATION_MESSAGE + " Provide a Sui address in chat for this public read." : context?.connectionConflict ? CONNECTION_CONFLICT_MESSAGE + " Provide a Sui address in chat for this public read." : availability.status !== "available"
             ? "The wallet connection cannot be checked. Please provide a Sui address in chat to view its assets."
             : "No connected wallet is available for the selected account. Please provide a Sui address in chat.";
         return { status: "address_required", message, result: errorToolResult({ kind: "input_invalid",

package/dist/mcp/tools/session/executionResultTools.js

@@ -20,7 +20,7 @@ export function registerExecutionResultTools(server, deps) {
             if (!state)
                 return errorToolResult({ kind: "session_not_found", details: { reviewSessionId } });
             const request = state.request;
-            return okToolResult({ ...reviewStatusResponse(state), userAnswerUse: executionResultUserAnswerUse({ hasConnectionConflict: !!state.connectionConflict, hasRequest: !!request, hasExecutionResult: !!request?.execution }) });
+            return okToolResult({ ...reviewStatusResponse(state), userAnswerUse: executionResultUserAnswerUse({ hasConnectionConflict: !!state.connectionConflict, reconciliationRequired: !!state.connectionReconciliationRequired, hasRequest: !!request, hasExecutionResult: !!request?.execution }) });
         }
         catch (error) {
             return sessionStoreToolError(error, deps.logger);
@@ -35,7 +35,7 @@ export function registerExecutionResultTools(server, deps) {
         try {
             const result = await waitForExecutionResult((id) => readCurrentReview(deps, id), reviewSessionId, { timeoutMs, signal: extra.signal });
             return okToolResult({ waitOutcome: result.waitOutcome, ...reviewStatusResponse(result),
-                userAnswerUse: executionResultUserAnswerUse({ hasConnectionConflict: !!result.connectionConflict, hasRequest: !!result.request, hasExecutionResult: !!result.request?.execution, hasWaitOutcome: true }) });
+                userAnswerUse: executionResultUserAnswerUse({ hasConnectionConflict: !!result.connectionConflict, reconciliationRequired: !!result.connectionReconciliationRequired, hasRequest: !!result.request, hasExecutionResult: !!result.request?.execution, hasWaitOutcome: true }) });
         }
         catch (error) {
             return sessionStoreToolError(error, deps.logger);

package/dist/mcp/tools/session/shared.js

@@ -15,6 +15,7 @@ export function executionStatusCategorySchema() { return z.enum(EXECUTION_STATUS
 export const timeoutInputSchema = z.number().int().min(1).max(MAX_WAIT_TIMEOUT_MS).default(DEFAULT_WAIT_TIMEOUT_MS).optional();
 export function waitExecutionInputSchema() { return { reviewSessionId: z.string().min(1), timeoutMs: timeoutInputSchema }; }
 export const reviewStatusResponseShape = {
+    connectionReconciliationRequired: z.literal(true).optional(),
     connectionConflict: connectionConflictSchema.optional(), walletAvailability: walletAvailabilitySchema, walletObservation: walletObservationSchema.optional(), progress: workflowProgressSchema,
     reviewSessionId: z.string(), status: internalSessionStatusSchema, reviewRevision: z.number().int().nonnegative(),
     account: z.string().optional(), plans: z.array(actionPlanSchema), reviewState: reviewStateOutputSchema.optional(),

package/dist/mcp/tools/session/statusTools.js

@@ -18,6 +18,7 @@ export function registerSessionStatusTools(server, deps) {
         outputSchema: successOutputSchema({ walletAvailability: walletAvailabilitySchema, walletObservation: walletObservationSchema.optional(), activeAccount: activeAccountResponseSchema,
             connections: z.array(connectionViewSchema), assetReadAccount: assetReadAccountSchema,
             connectionConflict: connectionConflictSchema.optional(),
+            manageableConnectionIds: z.array(z.string().min(1)), connectionReconciliationRequired: z.literal(true).optional(),
             pendingWalletConnections: z.object({ limit: z.number().int().positive(), truncated: z.boolean(),
                 items: z.array(z.object({ cardId: z.string(), connectionId: z.string().optional(),
                     status: pendingConnectionStatusSchema, progress: workflowProgressSchema, lastActivityAt: z.string() })) }),
@@ -35,14 +36,14 @@ export function registerSessionStatusTools(server, deps) {
         try {
             // Connection reconciliation can invalidate reviews and interrupt requests.
             // Complete that maintenance before projecting its dependent review facts.
-            const context = deps.workflow?.readConnectionContext() ?? { connections: [],
+            const context = deps.workflow?.reconcileConnectionContext() ?? { connections: [], manageableConnectionIds: [],
                 assetReadAccount: { status: "address_required" }, walletAvailability: walletUnavailable("initialization_failed") };
             const connections = deps.workflow?.pendingConnections() ?? [];
             const states = await Promise.all(deps.sessions.reviewSessionIds().map((id) => readCurrentReview(deps, id)));
             const reviews = states.flatMap((state) => state && isReviewInteractionPending(state) ? [reviewStatusResponse(state)] : []);
             return okToolResult({ activeAccount: activeAccountResponse(active), pendingWalletConnections: latest(connections),
                 pendingReviewSessions: latest(reviews), ...context,
-                userAnswerUse: interactionStatusUserAnswerUse("walletObservation" in context && context.walletObservation !== undefined, "connectionConflict" in context && !!context.connectionConflict) });
+                userAnswerUse: interactionStatusUserAnswerUse("walletObservation" in context && context.walletObservation !== undefined, "connectionConflict" in context && !!context.connectionConflict, "connectionReconciliationRequired" in context && !!context.connectionReconciliationRequired) });
         }
         catch (error) {
             return sessionStoreToolError(error, deps.logger);
@@ -60,7 +61,7 @@ export function registerSessionStatusTools(server, deps) {
                 return errorToolResult({ kind: "session_not_found", details: { reviewSessionId } });
             const session = state.session;
             return okToolResult({ ...reviewStatusResponse(state),
-                userAnswerUse: reviewStatusUserAnswerUse(!!session.reviewState, !!session.reviewState?.adapterLifecycle, !!session.reviewState?.humanReadableReview, !!session.reviewState?.simulation, !!state.connectionConflict) });
+                userAnswerUse: reviewStatusUserAnswerUse(!!session.reviewState, !!session.reviewState?.adapterLifecycle, !!session.reviewState?.humanReadableReview, !!session.reviewState?.simulation, !!state.connectionConflict, !!state.connectionReconciliationRequired) });
         }
         catch (error) {
             return sessionStoreToolError(error, deps.logger);

package/dist/mcp/tools/settings/index.js

@@ -1,10 +1,13 @@
 import { z } from "zod";
 import { SETTINGS_APPLIES_AFTER_RESTART } from "../../../core/preferences/preferencesStore.js";
 import { registerSuiMcpTool } from "../../registerTool.js";
-import { errorToolResult, okToolResult } from "../../result.js";
+import { okToolResult } from "../../result.js";
 import { noParamsInputSchema, successOutputSchema } from "../../schemas.js";
 import { localSettingsToolError, sessionStoreToolError } from "../../toolErrors.js";
 import { TOOL_NAMES } from "../../toolNames.js";
+import { registerAppTool } from "@modelcontextprotocol/ext-apps/server";
+import { cardMetadata, createWorkflowCard } from "../../../mcp-ui/tools.js";
+import { cardSnapshotSchema } from "../../../mcp-ui/contracts.js";
 const endpointSettingSchema = z.object({
     storedValue: z.string(),
     effectiveValue: z.string(),
@@ -13,34 +16,11 @@ const endpointSettingSchema = z.object({
     appliesAfter: z.literal(SETTINGS_APPLIES_AFTER_RESTART).optional()
 });
 export function registerSettingsTools(server, deps) {
-    server.registerTool(TOOL_NAMES.settingsCreateLocalSettingsSession, {
-        title: "Create local settings session",
-        description: "Create a local settings page session.",
-        inputSchema: noParamsInputSchema,
-        outputSchema: successOutputSchema({
-            settingsSessionId: z.string(),
-            settingsUrl: z.string(),
-            status: z.literal("created"),
-            openTarget: z.literal("system_browser"),
-            accessScope: z.literal("same_machine_loopback"),
-            expiresAt: z.string(),
-            lastActivityAt: z.string()
-        }),
-        annotations: { readOnlyHint: false, openWorldHint: false }
-    }, async () => {
+    registerAppTool(server, TOOL_NAMES.settingsCreateLocalSettingsSession, { title: "Settings", description: "Open a local settings card.", inputSchema: noParamsInputSchema,
+        outputSchema: successOutputSchema(cardSnapshotSchema.shape), _meta: cardMetadata("settings"),
+        annotations: { readOnlyHint: false, openWorldHint: false } }, async () => {
         try {
-            if (!deps.reviewBaseUrl)
-                return errorToolResult({ kind: "ui_unavailable", details: { reason: "Settings UI is unavailable in this runtime." } });
-            const created = await deps.sessions.createSettingsSession();
-            return okToolResult({
-                settingsSessionId: created.session.id,
-                settingsUrl: `${deps.reviewBaseUrl}/settings/${created.session.id}#${created.token}`,
-                status: "created",
-                openTarget: "system_browser",
-                accessScope: "same_machine_loopback",
-                expiresAt: created.session.expiresAt,
-                lastActivityAt: created.session.lastActivityAt
-            });
+            return await createWorkflowCard(server, deps, "settings", {});
         }
         catch (error) {
             return sessionStoreToolError(error, deps.logger);