@zktx.io/sui-mcp 0.5.0 → 0.6.1

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,9 @@ export class WalletWorkflow {
     observing = new Map();
     preparing = new Set();
     pendingWrites = new Map();
+    parentSignatureWork = new Set();
     eventListener;
+    settingsRecovery;
     constructor(options) {
         this.options = options;
     }
@@ -42,12 +45,13 @@ export class WalletWorkflow {
     report(stage) { try {
         this.options.logger.error("Wallet operation failed", { stage });
     }
-    catch { /* SQLite owns outcomes. */ } }
+    catch { } }
     async start() {
         this.assertCurrent();
         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 +65,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 +77,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();
@@ -92,14 +128,13 @@ export class WalletWorkflow {
         this.retainWrite(completion);
     }
     retainWrite(completion) {
-        // An old data generation cannot add repair work to the replacement data.
         try {
             this.assertCurrent();
         }
         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 +150,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);
     }
@@ -133,10 +170,10 @@ export class WalletWorkflow {
                 failure = error;
             }
         }
-        // A completed callback's pending flag is housekeeping, not authority to
-        // 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 +196,23 @@ 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" } };
+    }
+    currentConnectionContext() {
+        this.assertCurrent();
+        const facts = this.options.records.readConnectionFacts(this.now()), availability = this.walletAvailability();
+        const { selection: _selection, ...eligibility } = workflowConnectionEligibility({ ...facts, walletAvailability: availability });
+        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";
@@ -178,7 +222,6 @@ export class WalletWorkflow {
             const pending = this.options.records.pendingDisconnect(record.connection.connectionId);
             if (!pending)
                 continue;
-            // Disabled transports also return undefined; that is not session absence.
             const absent = available && !!record.topic && this.observed(record.topic)?.status === "absent";
             this.options.records.recoverDisconnect(pending.state.cardId, record.connection.connectionId, record.connection.revision, absent);
         }
@@ -194,7 +237,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;
@@ -208,23 +253,22 @@ export class WalletWorkflow {
             if (explicitResult) {
                 await this.observing.get(state.request.attemptId);
                 this.assertCurrent();
-                // An awaited receipt may have committed new facts. Return one freshly
-                // evaluated snapshot; ordinary status reads do not await external I/O.
                 state = await this.evaluateReview(id, undefined, false, state.request.attemptId);
             }
         }
         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);
@@ -391,8 +435,6 @@ export class WalletWorkflow {
             catch (error) {
                 displayFailure = error;
             }
-            // The approval remains pending even if setup/QR recording fails or the
-            // wallet dependency is disabled. Settle only after that promise ends.
             const session = await result.approval;
             if (displayFailure)
                 throw displayFailure;
@@ -444,6 +486,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 +501,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 {
@@ -494,8 +538,6 @@ export class WalletWorkflow {
                 return;
         }
         catch (error) {
-            // SDK verification can itself depend on a remote source. An exception is
-            // not proof of a mismatched transaction or signer.
             if (!this.stopped)
                 this.options.records.transitionRequest(request.attemptId, "request_failed", this.now(), {
                     reason: this.walletAvailability().status !== "available" ? "Wallet operations became unavailable before submission. The returned signature will not be submitted."
@@ -506,7 +548,7 @@ export class WalletWorkflow {
         try {
             await this.options.submitTransaction(bytes, response.signature);
         }
-        catch { /* A lost submit response is not proof of failure. Observe the same digest. */ }
+        catch { }
         finally {
             this.completeCallback({ kind: "request", id: request.attemptId, field: "submit_pending" });
         }
@@ -527,8 +569,6 @@ export class WalletWorkflow {
         const current = this.options.records.request(id);
         if (!current || !(isInitialChainObservation(current.requestStatus) || explicit && current.requestStatus === "outcome_unknown"))
             return;
-        // Starting another lookup needs its own previous callback to be settled.
-        // Stored terminal facts above never depend on this write succeeding.
         for (const [key, write] of this.pendingWrites)
             if (write.kind === "request" && write.id === id && write.field === "lookup_pending") {
                 this.settlePendingWrite(key, write);
@@ -549,7 +589,7 @@ export class WalletWorkflow {
                             if (receipt.status === "found")
                                 details = projectReadCardResult("receipt", { digest: request.transactionDigest }, receipt);
                         }
-                        catch { /* Keep verified chain facts if the additional display read is unavailable. */ }
+                        catch { }
                     }
                     this.assertCurrent();
                     this.options.records.transitionRequest(id, "completed", this.now(), { execution: {
@@ -581,7 +621,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

@@ -2,8 +2,6 @@ import { walletConnectionSelection } from "./walletConnection.js";
 import { isInitialChainObservation } from "./transactionRequest.js";
 export const workflowActions = ["connect", "disconnect", "use_account", "stop_connection", "prepare_review",
     "request_signature", "cancel", "stop_waiting", "read_result"];
-// Read context may change; an existing review's account binding may not.
-// Both evaluated choices and admission consume this relation with current facts.
 export function reviewPreparationAccount(boundAccount, activeAccount, selectedAccount = activeAccount) {
     if (!activeAccount)
         return { allowed: false, message: "No account from a connected wallet is selected for this review." };
@@ -15,24 +13,26 @@ export function reviewPreparationAccount(boundAccount, activeAccount, selectedAc
             message: "The selected account has changed since this request was made." };
     return { allowed: true, account: activeAccount };
 }
-// Shared domain eligibility. The DB supplies current facts at its decision
-// boundary. Returned choices are advisory; admission still binds concrete input.
+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 : [],
+        connectionReconciliationRequired: available && dependent ? selection.connectionReconciliationRequired : undefined };
+}
 export function workflowEligibility(facts) {
     const { record, session, request, authority, walletAvailability } = facts;
     const at = Date.parse(facts.evaluatedAt);
     const cardRemaining = record?.ownerId === facts.ownerId ? Math.max(0, Date.parse(record.state.expiresAt) - at) : 0;
-    // A later-created input card cannot extend its review session. Admitted
-    // requests and management cards retain their separate observation authority.
     const remaining = record?.scope === "review" && session && !request
         ? 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 +40,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 +74,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

@@ -9,7 +9,6 @@ import { reviewProgress, EXECUTION_POLLING_INTERVAL_SECONDS } from "./status.js"
 import { walletRunIdSchema, walletRecoverySchema, walletObservationSchema } from "./walletRuntime.js";
 export const CONNECT_BOUNDARY = "A wallet connection provides account context; it is not a transaction approval or proof of address ownership.";
 export const REVIEW_BOUNDARY = "Review evidence is not a safety guarantee. Only an explicit card action and wallet approval may authorize this exact transaction.";
-// A projection of an admitted card operation, not a new wallet connection state.
 export const connectionViewSchema = walletConnectionSchema.extend({ pendingAction: z.literal("disconnect").optional() });
 export { assetReadAccountSchema } from "./walletConnection.js";
 export const pendingConnectionStatusSchema = z.enum(["input_required", "awaiting_approval", "disconnect_pending"]);
@@ -37,6 +36,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,17 +61,24 @@ 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." });
     }
 });
-// Automatic preparation uses the same current selection and typed admission as
-// a deliberate retry. A failed computation is not a reason to compute in a loop.
 function automaticReviewAction(input) {
     const { record, session, request } = input;
     if (!session || record?.scope !== "review" || request || session.preparationError ||
@@ -87,7 +95,6 @@ function automaticReviewAction(input) {
     return { action: "prepare_review", walletRunId: input.walletAvailability.walletRunId, connectionId: candidates[0].connectionId,
         account, reviewRevision: session.reviewRevision };
 }
-// Method support filters wallet choices; it does not authorize a signature.
 export function reviewWalletChoices(selection, account, requireSigningMethod = false) {
     return selection.connections.filter((item) => item.connectionId === selection.usableConnectionId && item.accounts.includes(account) &&
         (!requireSigningMethod || item.methods.includes("sui_signTransaction")));
@@ -101,10 +108,11 @@ function nextStateRead(input) {
         .filter((value) => value !== undefined && value > 0);
     return delays.length ? Math.min(...delays) : undefined;
 }
-// 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 +122,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 +142,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/core/suiAddress.js

@@ -1,13 +1,8 @@
 import { isValidSuiAddress, isValidTransactionDigest, normalizeSuiAddress } from "@mysten/sui/utils";
 import { z } from "zod";
-// Use the string-only schema at MCP/HTTP output boundaries because zod transforms
-// cannot be represented in MCP JSON Schema. Use the normalized schema for values
-// before storing them as local session state.
 export const suiAddressStringSchema = z
     .string()
     .refine(isValidSuiAddress, "Expected a 32-byte Sui address");
-// Shared Sui transaction digest schema (pinned SDK source of truth). Used at
-// MCP/HTTP boundaries and by the signable-adapter commitment fields.
 export const suiTransactionDigestSchema = z
     .string()
     .refine(isValidTransactionDigest, "Expected a Sui transaction digest");

package/dist/core/suiEndpoint.js

@@ -35,9 +35,6 @@ export function parseGrpcUrl(value) {
     }
     return `${parsed.protocol}//${authority}`;
 }
-// GraphQL endpoints commonly include a path such as /graphql and may omit an
-// explicit port. gRPC endpoints stay stricter because the pinned gRPC client
-// runtime expects only scheme, host, and explicit port.
 export function parseGraphqlUrl(value) {
     let parsed;
     if (value.length > MAX_SUI_GRAPHQL_URL_LENGTH) {

package/dist/mcp/prompts.js

@@ -24,9 +24,6 @@ export const MCP_PROMPTS = [
         ].join("\n")
     }
 ];
-// Platform-owned boundary language appended to every adapter prompt surface.
-// Adapters contribute copy about their own action only; they cannot weaken
-// or omit these lines.
 const PLATFORM_PROMPT_BOUNDARY_LINES = [
     "Present the internal Review card and summarize the returned review checks.",
     "This MCP response never contains signing data, transaction bytes, or signing readiness; only an explicit UI action and wallet approval authorize the backend request; request status is separate from server-verified chain execution facts."
@@ -76,18 +73,9 @@ export function registerMcpPrompts(server, surfaces = []) {
             ]
         }));
     }
-    // Adapter prompt surfaces: action-first names (`swap-deep`) with one
-    // free-text intent argument so clients can pass the whole request in one
-    // line (Claude Code: /mcp__sui-mcp__swap-deep 10 sui to usdc;
-    // Claude Desktop shows a single input field). The model parses the
-    // intent; this server never does.
     for (const surface of surfaces) {
         registerSurfacePrompt(server, promptNameFor(surface), surface, surface.description);
     }
-    // Bare action prompts are always registered. One protocol: straight to it.
-    // Several protocols: an optional `protocol` argument (completion suggests
-    // the slugs) and explicit instructions to ask the user - the venue is the
-    // user's choice, never the server's.
     for (const [action, group] of actionGroups(surfaces)) {
         registerBareActionPrompt(server, action, group);
     }

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/schemas.js

@@ -1,7 +1,4 @@
 import { z } from "zod";
-// No-parameter tools. The `.optional()` is load-bearing: it lets the tool be called with
-// no arguments at all (undefined args validate). A bare `{}`/`z.object({})` would instead
-// REQUIRE an (empty) object and reject an argument-less call, so this is not a no-op.
 export const noParamsInputSchema = z.object({}).optional();
 export function successOutputSchema(dataShape) {
     return {

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/action/prepareSuiActionReview.js

@@ -32,12 +32,6 @@ export function registerActionTools(server, deps) {
         if (!supportsCards(server))
             return errorToolResult({ kind: "ui_unavailable", details: { reason: "An internal review card is required." } });
         const now = new Date();
-        // A swap review is account-bound: its evidence (balances, transaction
-        // material, digest, simulation) is computed for a specific sender, and
-        // no transaction can be built without that account. Refuse here when no
-        // wallet account is connected instead of creating a hollow proposal that
-        // can never be computed or signed. Connect first via
-        // session.create_wallet_connection.
         let activeAccount;
         try {
             activeAccount = await deps.activityStore.getActiveAccount();