@zktx.io/sui-mcp 0.5.0 → 0.6.0

package/dist/mcp-ui/contracts.js

@@ -7,11 +7,13 @@ export const CARD_RESOURCE_URIS = {
     receipt: "ui://sui-mcp/receipt.html",
     chart: "ui://sui-mcp/chart.html",
     connect: "ui://sui-mcp/connect.html",
-    review: "ui://sui-mcp/review.html"
+    review: "ui://sui-mcp/review.html",
+    settings: "ui://sui-mcp/settings.html"
 };
 export const CARD_METADATA_KEY = "sui-mcp/card";
 export const CARD_DISPLAY_METADATA_KEY = "sui-mcp/receipt-display";
 export const WALLET_DISPLAY_METADATA_KEY = "sui-mcp/wallet-display";
+export const SETTINGS_FILE_METADATA_KEY = "sui-mcp/settings-file";
 export const CARD_RESOURCE_PREFIX = "suimcp://cards/";
 export const cardInputRequiredSchema = z.discriminatedUnion("kind", [
     z.object({ kind: z.literal("account"), status: z.literal("input_required"), field: z.literal("account"), message: z.string().min(1) }).strict(),
@@ -25,7 +27,11 @@ export const cardReceiptDisplaySchema = receiptDisplaySchema.extend({
     cardId: z.string().min(1), revision: z.number().int().nonnegative(), attemptId: z.string().min(1).optional()
 });
 export const cardWalletDisplaySchema = walletDisplaySchema.extend({ cardId: z.string().min(1), revision: z.number().int().nonnegative() });
+export const settingsFileDisplaySchema = z.object({ attemptId: z.string().uuid().optional(), cardId: z.string().min(1), operationId: z.string().uuid(), fileId: z.string().uuid(),
+    offset: z.number().int().nonnegative().safe(), totalSize: z.number().int().nonnegative().safe(), sha256: z.string().regex(/^[a-f0-9]{64}$/),
+    chunkBase64: z.string() }).strict();
 export const CARD_TOOLS = {
     account: TOOL_NAMES.uiOpenAccount, receipt: TOOL_NAMES.uiOpenReceipt, chart: TOOL_NAMES.uiOpenChart,
-    read: TOOL_NAMES.uiReadCard, submit: TOOL_NAMES.uiSubmitCard, act: TOOL_NAMES.uiActCard
+    read: TOOL_NAMES.uiReadCard, submit: TOOL_NAMES.uiSubmitCard, act: TOOL_NAMES.uiActCard,
+    readSettingsFile: TOOL_NAMES.uiReadSettingsFile
 };

package/dist/mcp-ui/readCards.js

@@ -2,7 +2,7 @@ import { CardStore } from "../core/session/cardSessionStore.js";
 import { accountInputSchema, receiptInputSchema, chartInputSchema } from "../core/read/readCardInputs.js";
 export function createReadCardStore(options) {
     return new CardStore({
-        records: options.records, ownerId: options.ownerId, assertCurrent: options.assertCurrent, now: options.now, logger: options.logger, workflow: options.workflow,
+        records: options.records, ownerId: options.ownerId, assertCurrent: options.assertCurrent, now: options.now, logger: options.logger, workflow: options.workflow, settings: options.settings,
         prepare: async (kind) => {
             if (kind !== "chart")
                 return { status: "ready" };

package/dist/mcp-ui/tools.js

@@ -1,4 +1,6 @@
 import { workflowActionSchema } from "../core/session/workflowView.js";
+import { settingsActionSchema } from "../core/session/settingsOperation.js";
+import { MAX_JSON_BODY_BYTES, settingsJsonSize, settingsRawChunkBudget } from "../core/session/settingsFileProtocol.js";
 import { sessionDomainToolError } from "../mcp/toolErrors.js";
 import { accountInputSchema, receiptInputSchema, chartOpenInputSchema } from "../core/read/readCardInputs.js";
 import { readFile } from "node:fs/promises";
@@ -8,8 +10,8 @@ import { z } from "zod";
 import { okToolResult, errorToolResult } from "../mcp/result.js";
 import { CardError } from "../core/session/cardSessionStore.js";
 import { resolveExplicitOrActiveAccount } from "../mcp/tools/read/readToolHelpers.js";
-import { CARD_METADATA_KEY, CARD_DISPLAY_METADATA_KEY, WALLET_DISPLAY_METADATA_KEY, CARD_RESOURCE_PREFIX, CARD_RESOURCE_URIS, CARD_TOOLS, cardReceiptDisplaySchema, cardWalletDisplaySchema, cardReferenceSchema, cardSubmissionSchema, cardInputRequiredSchema } from "./contracts.js";
-const cardActionSchema = cardReferenceSchema.extend({ revision: z.number().int().nonnegative(), input: workflowActionSchema }).strict();
+import { CARD_METADATA_KEY, CARD_DISPLAY_METADATA_KEY, WALLET_DISPLAY_METADATA_KEY, SETTINGS_FILE_METADATA_KEY, CARD_RESOURCE_PREFIX, CARD_RESOURCE_URIS, CARD_TOOLS, cardReceiptDisplaySchema, cardWalletDisplaySchema, cardReferenceSchema, cardSubmissionSchema, cardInputRequiredSchema } from "./contracts.js";
+const cardActionSchema = cardReferenceSchema.extend({ revision: z.number().int().nonnegative().safe(), input: z.union([workflowActionSchema, settingsActionSchema]) }).strict();
 export const cardMetadata = (kind) => ({
     ui: { resourceUri: CARD_RESOURCE_URIS[kind], visibility: ["model"] },
     "openai/outputTemplate": CARD_RESOURCE_URIS[kind]
@@ -131,4 +133,33 @@ export function registerReadCards(server, deps) {
             }
         });
     }
+    const fileInput = cardReferenceSchema.extend({ attemptId: z.string().uuid().optional(), operationId: z.string().uuid(), fileId: z.string().uuid(), offset: z.number().int().nonnegative().safe(),
+        limit: z.number().int().positive().safe().optional() }).strict();
+    registerAppTool(server, CARD_TOOLS.readSettingsFile, { description: "Read a verified backup file for its current download attempt.", inputSchema: fileInput,
+        _meta: { ui: { visibility: ["app"] } }, annotations: { readOnlyHint: true, openWorldHint: false }
+    }, async (input, extra) => {
+        try {
+            if (!deps.cards)
+                throw new CardError("Card service is unavailable.");
+            // Measure the actual response shape, including its text fallback and UI
+            // metadata. Reserve maximum safe-integer digit widths for size fields.
+            const base = okToolResult({ status: "read", fileId: input.fileId, offset: input.offset, rangeSize: Number.MAX_SAFE_INTEGER });
+            const metadata = { ...(input.attemptId ? { attemptId: input.attemptId } : {}), cardId: input.cardId, operationId: input.operationId, fileId: input.fileId, offset: input.offset, totalSize: Number.MAX_SAFE_INTEGER,
+                sha256: "0".repeat(64), chunkBase64: "" };
+            base._meta = { [SETTINGS_FILE_METADATA_KEY]: metadata };
+            const budget = settingsRawChunkBudget({ jsonrpc: "2.0", id: extra.requestId, result: base });
+            if (!budget)
+                throw new CardError("The backup response cannot fit the app's message envelope.");
+            const read = await deps.cards.store.readSettingsFile(input, Math.min(input.limit ?? budget, budget));
+            const rangeSize = Buffer.from(read.chunkBase64, "base64").length;
+            const result = okToolResult({ status: "read", fileId: input.fileId, offset: input.offset, rangeSize });
+            result._meta = { [SETTINGS_FILE_METADATA_KEY]: { ...metadata, totalSize: read.file.totalSize, sha256: read.file.sha256, chunkBase64: read.chunkBase64 } };
+            if (settingsJsonSize({ jsonrpc: "2.0", id: extra.requestId, result }) > MAX_JSON_BODY_BYTES)
+                throw new CardError("The backup response exceeds its message limit.");
+            return result;
+        }
+        catch {
+            return errorToolResult({ kind: "input_invalid", details: { reason: "This backup file could not be read or verified." } });
+        }
+    });
 }

package/dist/review-server/server.js

@@ -1,10 +1,8 @@
-import { createServer } from "node:http";
 import { validateHostOrigin } from "./middleware/hostOrigin.js";
-import { defaultReviewAssetsDir, serveReviewAsset } from "./assets.js";
-import { settingsHtml } from "./html.js";
-import { HttpError, sendHtml, sendJson } from "./http.js";
+import { sendJson } from "../runtime/shared/http.js";
 import { ALLOWED_HOSTNAMES } from "./reviewServerPolicy.js";
-import { routeSettingsApi } from "./settingsApi.js";
+// The shared runtime serves authenticated private MCP/control routes itself.
+// There are no public browser pages, Settings APIs or static-asset fallbacks.
 export function createReviewRequestHandler(options) {
     return async (request, response) => {
         try {
@@ -18,55 +16,11 @@ export function createReviewRequestHandler(options) {
                 sendJson(response, 400, { error: "token_query_not_supported" });
                 return;
             }
-            const settings = /^\/settings\/([^/]+)$/.exec(url.pathname);
-            if (request.method === "GET" && settings?.[1]) {
-                sendHtml(response, settingsHtml(settings[1]), { "content-security-policy": [
-                        "default-src 'none'", "base-uri 'none'", "connect-src 'self'", "script-src 'self'",
-                        "style-src 'self'", "img-src 'self' data:", "form-action 'none'"
-                    ].join("; ") });
-                return;
-            }
-            const asset = /^\/review-assets\/(.+)$/.exec(url.pathname);
-            if (request.method === "GET" && asset?.[1]) {
-                await serveReviewAsset(response, options.reviewAssetsDir ?? defaultReviewAssetsDir(), asset[1]);
-                return;
-            }
-            const route = /^\/api\/settings\/([^/]+)(?:\/(.*))?$/.exec(url.pathname);
-            if (route?.[1]) {
-                const routes = {
-                    "": "status", "clear-active-account": "clearActiveAccount", "sui-grpc-url": "setSuiGrpcUrl",
-                    "sui-grpc-url/restore-default": "restoreDefaultSuiGrpcUrl", "sui-graphql-url": "setSuiGraphqlUrl",
-                    "sui-graphql-url/restore-default": "restoreDefaultSuiGraphqlUrl", "local-data/export": "exportLocalData",
-                    "local-data/import/preview": "previewImport", "local-data/import": "importLocalData", "local-data/reset": "resetLocalData"
-                };
-                const match = routes[route[2] ?? ""];
-                if (match) {
-                    await routeSettingsApi(request, response, options, url, { [match]: route[1] });
-                    return;
-                }
-            }
             sendJson(response, 404, { error: "not_found" });
         }
-        catch (error) {
-            if (error instanceof HttpError) {
-                sendJson(response, error.status, { error: error.code });
-                return;
-            }
-            options.logger.error("settings request failed", { stage: "settings_http" });
+        catch {
+            options.logger.error("HTTP routing failed", { stage: "http_routing" });
             sendJson(response, 500, { error: "internal_error" });
         }
     };
 }
-export function createReviewHttpServer(options) {
-    const handler = createReviewRequestHandler(options);
-    const server = createServer((request, response) => { void handler(request, response); });
-    return {
-        start(port) {
-            return new Promise((resolve, reject) => {
-                server.once("error", reject);
-                server.listen(port, options.host, () => resolve({ host: options.host, port: server.address().port,
-                    close: () => new Promise((done, failed) => { server.close((error) => error ? failed(error) : done()); }) }));
-            });
-        }
-    };
-}

package/dist/runtime/application.js

@@ -5,6 +5,8 @@ import { dirname } from "node:path";
 import { WalletSdkProcess } from "./walletSdkProcess.js";
 import { WALLETCONNECT_PROJECT_ID } from "./walletConnectConfig.js";
 import { WalletWorkflow } from "../core/session/walletWorkflow.js";
+import { SettingsWorkflow } from "../core/session/settingsWorkflow.js";
+import { SettingsFileStore } from "../core/session/settingsFileStore.js";
 import { randomUUID } from "node:crypto";
 import { SqliteActivityStore } from "../core/activity/sqliteActivityStore.js";
 import { validateSupportedAdapterLifecycle } from "../adapters/adapterLifecycleValidators.js";
@@ -33,6 +35,7 @@ export async function createRuntimeApplication(bootConfig, logger, ownerId = ran
     let activityStore;
     let cards;
     let workflow;
+    let settings;
     let chart;
     try {
         const store = new SqliteActivityStore({
@@ -68,10 +71,10 @@ export async function createRuntimeApplication(bootConfig, logger, ownerId = ran
             bootSuiGrpcUrl: config.suiGrpcUrl,
             bootSuiGraphqlUrl: config.suiGraphqlUrl
         });
-        const workflowRecords = store.createWalletWorkflowStore(ownerId);
+        const workflowRecords = store.createWalletWorkflowStore(ownerId, () => new Date(), () => walletRuntime?.snapshot());
         const localData = store.createLocalDataService({
             advanceRequestDeadlines: (now) => workflowRecords.advanceRequestDeadlines(now),
-            onDataReplaced: () => { access.dataReplaced(); workflow?.dataReplaced(); chart?.clearCache(); },
+            onDataReplaced: () => { access.dataReplaced(); workflow?.dataReplaced(); settings?.dataReplaced(); chart?.clearCache(); },
             suiGrpcUrl: DEFAULT_SUI_GRPC_URL,
             suiGraphqlUrl: DEFAULT_SUI_GRAPHQL_URL,
             verifySuiGrpcUrl: async (url) => {
@@ -95,8 +98,7 @@ export async function createRuntimeApplication(bootConfig, logger, ownerId = ran
             validateAdapterLifecycle: validateSupportedAdapterLifecycle,
             sessions: store.createSessionRecordStore(),
             artifacts: store.createPrivateReviewArtifactStore(),
-            ownerId,
-            settingsStore: store.createSettingsRecordStore()
+            ownerId
         });
         const readService = createSuiReadService({
             client: suiClient,
@@ -118,9 +120,7 @@ export async function createRuntimeApplication(bootConfig, logger, ownerId = ran
         }, input);
         const reviewComputationDeps = createRuntimeReviewDependencies({ client: suiClient, chainIdentifier,
             expectedChainIdentifier: config.expectedChainIdentifier, materialStore: transactionMaterialStore, readService });
-        const httpHandler = createReviewRequestHandler({ host: config.reviewHost, store: sessions, logger,
-            activityStore: store, localSettings, localData,
-            serverInfo: { name: SERVER_NAME, version: SERVER_VERSION, network: SERVER_NETWORK } });
+        const httpHandler = createReviewRequestHandler({ logger });
         const cardRecords = store.createCardRecordStore();
         let metadata;
         try {
@@ -141,9 +141,26 @@ export async function createRuntimeApplication(bootConfig, logger, ownerId = ran
             },
             submitTransaction: (transaction, signature) => suiClient.core.executeTransaction({ transaction, signatures: [signature] })
         });
+        const settingsRecords = store.createSettingsWorkflowStore(ownerId);
+        settings = new SettingsWorkflow({ records: settingsRecords, files: new SettingsFileStore(dirname(bootConfig.activityDatabasePath)),
+            activity: store, localData, preferences: preferencesRepository, wallet: workflow, assertCurrent: access.assertCurrent, runMaintenance: (work) => access.run(work),
+            resolveEndpoint: (input) => localSettings.resolveEndpointChange(input),
+            verifyEndpoint: (input) => localSettings.prepareEndpointChange(input),
+            interruptRun: (runId) => workflowRecords.invalidateWalletRun("wallet_service_restarted", new Date(), runId),
+            readFacts: async () => settingsRecords.transaction(() => {
+                const context = workflow.currentConnectionContext(), account = store.getActiveAccountSync();
+                const observedAt = context.walletObservation?.observedAt;
+                return { server: { name: SERVER_NAME, version: SERVER_VERSION, network: SERVER_NETWORK },
+                    localSettings: localSettings.getLocalSettingsSync((key) => preferencesRepository.getLocalSettingSync(key)),
+                    ...(account ? { readAddress: account.address } : {}),
+                    assetReadAccount: context.assetReadAccount, walletAvailability: context.walletAvailability,
+                    ...(context.connectionReconciliationRequired ? { connectionReconciliationRequired: true } : {}),
+                    ...(observedAt ? { observedAt } : {}), counts: localData.getDataCountsSync() };
+            }) });
+        settings.recoverOwner();
         await workflow.start();
         chart = createDeepbookUsdcChartService({ assertCurrent: access.assertCurrent });
-        cards = createReadCardStore({ readService, publicChainReceiptReader, chart, records: cardRecords, ownerId, assertCurrent: access.assertCurrent, logger, workflow });
+        cards = createReadCardStore({ readService, publicChainReceiptReader, chart, records: cardRecords, ownerId, assertCurrent: access.assertCurrent, logger, workflow, settings });
         const transactionActivityService = new TransactionActivityService({
             activityStore: store,
             source: new GraphqlSuiTransactionActivitySource({
@@ -157,31 +174,41 @@ export async function createRuntimeApplication(bootConfig, logger, ownerId = ran
             promptSurfaces: ADAPTER_PROMPT_SURFACES,
             sessions,
             activityStore: store,
-            reviewBaseUrl: `http://${config.reviewHost}:${config.reviewPort}`,
             readService,
             transactionActivityService,
             localSettings,
             logger
         }));
         access.ready();
+        void access.run(() => settings.cleanupAfterOwnerChange()).catch(() => {
+            try {
+                logger.error("Temporary settings file cleanup is incomplete", { stage: "settings_file_cleanup" });
+            }
+            catch { /* Stored cleanup facts remain authoritative. */ }
+        });
         return {
             handleMcp: (request, response) => access.run(() => mcp.handle(request, response)),
             handleHttp: (request, response) => access.run(() => httpHandler(request, response)),
             async close() {
                 workflow?.stop();
-                access.close();
                 cards?.stop();
                 chart?.clearCache();
                 try {
-                    await walletRuntime.close();
+                    await settings.close();
                 }
                 finally {
+                    access.close();
                     try {
-                        await mcp.close();
+                        await walletRuntime.close();
                     }
                     finally {
-                        store.close();
-                        ownership.close();
+                        try {
+                            await mcp.close();
+                        }
+                        finally {
+                            store.close();
+                            ownership.close();
+                        }
                     }
                 }
             }

package/dist/runtime/localSettingsService.js

@@ -33,14 +33,23 @@ export class RuntimeLocalSettingsService {
     async getLocalSettings() {
         const stored = await this.options.preferencesRepository.getSuiGrpcUrl();
         const storedGraphql = await this.options.preferencesRepository.getSuiGraphqlUrl();
+        return this.settingsFromStored(stored?.value, storedGraphql?.value);
+    }
+    getLocalSettingsSync(read) {
+        const grpc = read("suiGrpcUrl"), graphql = read("suiGraphqlUrl");
+        if (grpc && typeof grpc.value !== "string" || graphql && typeof graphql.value !== "string")
+            throw new LocalSettingsError("internal_error", "Stored endpoints are invalid.");
+        return this.settingsFromStored(grpc?.value, graphql?.value);
+    }
+    settingsFromStored(stored, storedGraphql) {
         const currentStoredView = resolveSuiGrpcUrlView({
             defaultSuiGrpcUrl: this.defaultSuiGrpcUrl,
-            storedValue: stored?.value,
+            storedValue: stored,
             envValue: this.env.SUI_GRPC_URL
         });
         const currentStoredGraphqlView = resolveSuiGraphqlUrlView({
             defaultSuiGraphqlUrl: this.defaultSuiGraphqlUrl,
-            storedValue: storedGraphql?.value,
+            storedValue: storedGraphql,
             envValue: this.env.SUI_GRAPHQL_URL
         });
         return {
@@ -48,6 +57,21 @@ export class RuntimeLocalSettingsService {
             suiGraphqlUrl: withBootEffectiveEndpoint(currentStoredGraphqlView, this.bootSuiGraphqlUrl)
         };
     }
+    // The same side-effect-free target resolution serves display and final
+    // verification. Default URLs belong to this service, never to the View.
+    resolveEndpointChange(input) {
+        const value = input.kind === "restore_endpoint"
+            ? input.endpoint === "grpc" ? this.defaultSuiGrpcUrl : this.defaultSuiGraphqlUrl
+            : input.endpoint === "grpc" ? parseEndpointForTool(input.value ?? "") : parseGraphqlEndpointForTool(input.value ?? "");
+        return { key: input.endpoint === "grpc" ? "suiGrpcUrl" : "suiGraphqlUrl", value,
+            status: input.kind === "restore_endpoint" ? "reset" : "saved" };
+    }
+    // Verification does not store a value or change this parent's effective URL.
+    async prepareEndpointChange(input) {
+        const target = this.resolveEndpointChange(input);
+        await this.verifyEndpointForTool(target.value, input.endpoint);
+        return target;
+    }
     async setSuiGrpcUrl(url) {
         const normalized = parseEndpointForTool(url);
         await this.verifyEndpointForTool(normalized, "grpc");

package/dist/runtime/shared/authenticatedFetch.js

@@ -2,7 +2,7 @@ import { Agent, request as httpRequest } from "node:http";
 import { connect } from "node:net";
 import { randomBytes } from "node:crypto";
 import { Readable } from "node:stream";
-import { MAX_JSON_BODY_BYTES } from "../../review-server/http.js";
+import { MAX_JSON_BODY_BYTES } from "./http.js";
 import { IDENTITY_CHALLENGE_HEADER, IDENTITY_PATH, IDENTITY_TIMEOUT_MS, INTERNAL_MCP_PATH, SERVER_INSTANCE_HEADER, verifyServerIdentity } from "./control.js";
 // Proof and authenticated request use the same TCP socket. A closed socket is never
 // transparently replaced: no credential or UI permission can reach a new listener.
@@ -86,7 +86,11 @@ export function createAuthenticatedFetch(port, control, expectedInstanceId) {
         headers.set("host", url.host);
         headers.set("authorization", `Bearer ${control.key}`);
         headers.set(SERVER_INSTANCE_HEADER, channel.identity.instanceId);
-        headers.set("connection", "close");
+        // An early rejection (for example the SDK's body-size guard) must reach
+        // the caller while the request is still being written. Server-side
+        // Connection: close can race that response with EPIPE. This channel is
+        // still destroyed after the response and never reused or replaced.
+        headers.set("connection", "keep-alive");
         const body = init?.body;
         if (body !== undefined && body !== null && typeof body !== "string") {
             channel.close();

package/dist/runtime/shared/control.js

@@ -2,9 +2,8 @@ import { createHash, createHmac, randomBytes, randomUUID, timingSafeEqual } from
 import { link, lstat, mkdir, readFile, realpath, unlink, writeFile } from "node:fs/promises";
 import { basename, dirname, join } from "node:path";
 import { z } from "zod";
-// Version 7 uses the Sui MCP resource, metadata and response-field identities.
-// Clients must not attach to an owner that serves the previous package contract.
-export const INTERNAL_API_VERSION = 7;
+import { SERVER_VERSION } from "../../mcp/serverInfo.js";
+// Peers use the one package release identity, with no separate API counter.
 export const IDENTITY_PATH = "/__runtime/identity";
 export const INTERNAL_MCP_PATH = "/__runtime/mcp";
 export const IDENTITY_CHALLENGE_HEADER = "x-sui-mcp-identity-challenge";
@@ -15,7 +14,7 @@ const secretSchema = z.string().regex(/^[A-Za-z0-9_-]{43}$/);
 export const serverIdentitySchema = z.object({
     service: z.literal("sui-mcp"),
     role: z.literal("shared-server"),
-    apiVersion: z.literal(INTERNAL_API_VERSION),
+    packageVersion: z.literal(SERVER_VERSION),
     databaseId: z.string().regex(/^[0-9a-f]{64}$/),
     configurationId: z.string().regex(/^[0-9a-f]{64}$/),
     instanceId: z.string().uuid(),
@@ -53,12 +52,12 @@ export async function loadControlIdentity(databasePath, configuration) {
     };
 }
 function identityPayload(identity) {
-    return JSON.stringify([identity.service, identity.role, identity.apiVersion, identity.databaseId,
+    return JSON.stringify([identity.service, identity.role, identity.packageVersion, identity.databaseId,
         identity.configurationId, identity.instanceId, identity.pid, identity.challenge]);
 }
 export function createServerIdentity(control, instanceId, challenge) {
     secretSchema.parse(challenge);
-    const identity = { service: "sui-mcp", role: "shared-server", apiVersion: INTERNAL_API_VERSION,
+    const identity = { service: "sui-mcp", role: "shared-server", packageVersion: SERVER_VERSION,
         databaseId: control.databaseId, configurationId: control.configurationId,
         instanceId, pid: process.pid, challenge };
     return { ...identity, proof: createHmac("sha256", control.key).update(identityPayload(identity)).digest("base64url") };

package/dist/runtime/shared/http.js

@@ -0,0 +1,14 @@
+export { MAX_JSON_BODY_BYTES } from "../../core/session/settingsFileProtocol.js";
+export class HttpError extends Error {
+    status;
+    code;
+    constructor(status, code) {
+        super(code);
+        this.status = status;
+        this.code = code;
+    }
+}
+export function sendJson(response, status, body) {
+    response.writeHead(status, { "content-type": "application/json; charset=utf-8" });
+    response.end(JSON.stringify(body));
+}

package/dist/runtime/shared/mcpHttp.js

@@ -2,7 +2,8 @@ import { CARD_TOOLS } from "../../mcp-ui/contracts.js";
 import { randomUUID } from "node:crypto";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { isJSONRPCRequest } from "@modelcontextprotocol/sdk/types.js";
-import { MAX_JSON_BODY_BYTES, sendJson } from "../../review-server/http.js";
+import { MAX_JSON_BODY_BYTES, sendJson } from "./http.js";
+import { settingsUploadMessageBudget } from "../../core/session/settingsFileProtocol.js";
 export function createInternalMcpHandler(createServer) {
     const sessions = new Map();
     const connections = new Set();
@@ -48,12 +49,16 @@ export function createInternalMcpHandler(createServer) {
                     close: () => transport.close()
                 };
                 transport.onmessage = (message, extra) => {
-                    // Preserve ordinary stdio MCP input contracts. The existing HTTP/UI
-                    // body limit applies to card calls, including their JSON-RPC envelope.
+                    // The SDK enforces its 4 MiB HTTP body limit before this callback.
+                    // Card calls additionally have a 64 KiB JSON-RPC envelope budget;
+                    // ordinary MCP calls do not inherit that smaller card limit.
                     if (isJSONRPCRequest(message) && message.method === "tools/call" &&
                         Object.values(CARD_TOOLS).some((name) => name === message.params?.name) &&
                         Buffer.byteLength(JSON.stringify(message)) > MAX_JSON_BODY_BYTES) {
-                        void transport.send({ jsonrpc: "2.0", id: message.id, error: { code: -32600, message: "Card request exceeds the JSON body limit." } });
+                        const budget = settingsUploadMessageBudget(message);
+                        void transport.send({ jsonrpc: "2.0", id: message.id, error: { code: -32600,
+                                message: budget === undefined ? "Card request exceeds the JSON body limit." : "settings_payload_too_large",
+                                ...(budget === undefined ? {} : { data: { code: "settings_payload_too_large", maximumMessageSize: MAX_JSON_BODY_BYTES, rawChunkLimit: budget } }) } });
                         return;
                     }
                     connection.onmessage?.(message, extra);

package/dist/runtime/shared/server.js

@@ -1,6 +1,6 @@
 import { createServer } from "node:http";
 import { randomUUID } from "node:crypto";
-import { HttpError, sendJson } from "../../review-server/http.js";
+import { HttpError, sendJson } from "./http.js";
 import { createServerIdentity, IDENTITY_CHALLENGE_HEADER, IDENTITY_PATH, INTERNAL_MCP_PATH, singleHeader, validControlAuthorization, validInternalRequest } from "./control.js";
 export async function startSharedServer(input) {
     const instanceId = randomUUID();

package/dist/runtime/smokeMainnetRead.js

@@ -122,7 +122,6 @@ async function main() {
             validateAdapterLifecycle: validateSupportedAdapterLifecycle,
             sessions: activityStore.createSessionRecordStore(),
             artifacts: activityStore.createPrivateReviewArtifactStore(),
-            settingsStore: activityStore.createSettingsRecordStore()
         });
         const reviewDependencies = createRuntimeReviewDependencies({ client: suiClient, chainIdentifier,
             expectedChainIdentifier: config.expectedChainIdentifier, materialStore: transactionMaterialStore, readService });

package/dist/runtime/walletConnectStorage.js

@@ -12,12 +12,11 @@ const persistentKeys = new Set([
 ]);
 const storageSchema = "CREATE TABLE sdk_sessions (key TEXT PRIMARY KEY, value BLOB NOT NULL)";
 function storageFormat(db) {
-    const version = db.pragma("user_version", { simple: true });
     const schema = db.prepare("SELECT type,name,sql FROM sqlite_schema WHERE name NOT LIKE 'sqlite_%' ORDER BY type,name")
         .all();
-    if (version === 0 && schema.length === 0)
+    if (schema.length === 0)
         return "empty";
-    if (version === 1 && schema.length === 1 && schema[0]?.type === "table" &&
+    if (schema.length === 1 && schema[0]?.type === "table" &&
         schema[0].name === "sdk_sessions" && schema[0].sql === storageSchema)
         return "current";
     throw new Error("WalletConnect storage format is unsupported.");
@@ -59,7 +58,6 @@ export function openWalletConnectStorage(dataDirectory) {
         if (storageFormat(db) === "empty") {
             db.transaction(() => {
                 db.exec(storageSchema);
-                db.pragma("user_version = 1");
             })();
         }
         // There is exactly one SDK owner. FULL protects the session material that

package/dist/runtime/walletSdkChildRuntime.js

@@ -1,3 +1,4 @@
+import { SERVER_VERSION } from "../mcp/serverInfo.js";
 import { join } from "node:path";
 import { isDeepStrictEqual } from "node:util";
 import { WalletUserRejectedError } from "../core/session/walletConnection.js";
@@ -19,7 +20,7 @@ export function runWalletSdkChild(createTransport) {
         process.send(walletEventSchema.parse(message), (error) => { if (error)
             exit(); });
     };
-    const envelope = () => ({ protocolVersion: 1, runId: init.runId });
+    const envelope = () => ({ packageVersion: SERVER_VERSION, runId: init.runId });
     const exit = () => { if (!exiting) {
         exiting = true;
         void ownership;

package/dist/runtime/walletSdkIpc.js

@@ -1,8 +1,9 @@
+import { SERVER_VERSION } from "../mcp/serverInfo.js";
 import { z } from "zod";
 import { suiAddressStringSchema } from "../core/suiAddress.js";
 import { walletRunIdSchema, walletStartStageSchema, walletSnapshotSchema, walletSessionObservationSchema, walletSessionSchema } from "../core/session/walletRuntime.js";
 import { walletUnavailableReasonSchema } from "../core/session/walletConnection.js";
-const envelope = z.object({ protocolVersion: z.literal(1), runId: walletRunIdSchema });
+const envelope = z.object({ packageVersion: z.literal(SERVER_VERSION), runId: walletRunIdSchema });
 const request = envelope.extend({ requestId: z.number().int().positive(), operationId: z.string().min(1) });
 export const walletCommandSchema = z.union([
     envelope.extend({ type: z.literal("init"), dataDirectory: z.string().min(1), projectId: z.string().regex(/^[0-9a-f]{32}$/i),

package/dist/runtime/walletSdkProcess.js

@@ -1,3 +1,4 @@
+import { SERVER_VERSION } from "../mcp/serverInfo.js";
 import { fork } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { isDeepStrictEqual } from "node:util";
@@ -80,7 +81,7 @@ export class WalletSdkProcess {
             });
             child.once("disconnect", () => { if (!run.fenced && !run.didExit)
                 this.lose(run, this.failureReason()); });
-            this.send(run, { protocolVersion: 1, runId: run.id, type: "init", dataDirectory: this.options.dataDirectory,
+            this.send(run, { packageVersion: SERVER_VERSION, runId: run.id, type: "init", dataDirectory: this.options.dataDirectory,
                 projectId: this.options.projectId, metadata: this.options.metadata });
         }
         catch {
@@ -318,7 +319,7 @@ export class WalletSdkProcess {
             return new Promise((resolve, reject) => {
                 run.pending.set(requestId, { operationId, type: input.type, resolve, reject, ...approval });
                 try {
-                    this.send(run, { ...input, protocolVersion: 1, runId: run.id, requestId, operationId });
+                    this.send(run, { ...input, packageVersion: SERVER_VERSION, runId: run.id, requestId, operationId });
                 }
                 catch (error) {
                     run.pending.delete(requestId);

package/docs/AGENT_BEHAVIOR.md

@@ -311,7 +311,7 @@ For a connected-account-only read, use `session.get_interaction_status` to disti
 1. `account.get_active_account` reports the stored selection, with `source` and `setAt`. For current assets without a user-provided address, use `session.get_interaction_status.assetReadAccount` to check whether that selection is a usable default. If not, request an address only for tools that accept `account`; connected-account-only tools require the connection/account-selection flow. Do not infer current connection from the stored selection.
 2. An explicit connect/reconnect/disconnect/account replacement request opens an internal
    Connect card with `session.create_wallet_connection`: use `intent: connect` for requested pairing, `intent: disconnect` for requested disconnection, and `intent: manage` for inspection or account selection. The model must not call app-only actions on the user's behalf.
-For "disconnect my wallet", when the wallet service is available and the target is connected, open `session.create_wallet_connection` with `intent: disconnect`. For one connected target the card shows Confirm disconnect or Back directly; Back only returns to the connection view; it does not submit Cancel review or disconnect. The card starts no pairing. Do not substitute `account.clear_active_account`, claim disconnection is unsupported merely because there is no direct model-facing disconnect tool, or equate disconnection with revoking onchain permissions. If disconnection is already pending, read or wait on that exact card instead of opening another operation.
+For "disconnect my wallet", when the wallet service is available and the target is connected, open `session.create_wallet_connection` with `intent: disconnect`. For one connected target the card shows Confirm disconnect or Back directly; Back only returns to the connection view; it does not submit Cancel review or disconnect. The card starts no pairing. Do not substitute the Settings action to clear the default read address, claim disconnection is unsupported merely because there is no direct model-facing disconnect tool, or equate disconnection with revoking onchain permissions. If disconnection is already pending, read or wait on that exact card instead of opening another operation.
 
 3. `session.get_wallet_connection` and `session.wait_wallet_connection` use the
    returned cardId. An unsubmitted card needs input; waiting does not create a
@@ -347,12 +347,28 @@ them. `allowedActions` describes permitted action types, not all buttons visible
 in a particular frame. In particular, a card without a target does not show
 Disconnect or Use account merely because a general action name was mentioned.
 
-There is no service-restart button in Connect or Settings. If the service is
-unavailable or disconnection remains unresponsive, explain the operational
-procedure in the setup guide: fully quit all apps using Sui MCP, then
-reopen them. Closing only a non-owning app or a window may leave the shared
-backend running. Do not kill processes or repeatedly send wallet commands for
-the user, and do not report restart success before the new service is observed.
+Connection-service recovery belongs to Settings. When the service is unavailable
+or a connection operation remains unresponsive, open
+`settings.create_local_settings_session` on the user's request and direct them
+to Troubleshooting. The user inspects the affected run/requests and explicitly
+confirms Restart connection service; do not call app-only actions for them.
+A new Settings card can explicitly supersede a startup still pending. Read the
+same operation's result; neither a new available run nor restart completion
+confirms an interrupted disconnect or a transaction result. Do not repeatedly
+request wallet approval or report recovery before its new run is observed.
+`manageableConnectionIds` names exact disconnect targets, not usable wallet
+choices. A terminal record may remain manageable when its SDK session is still
+present; do not describe the old failed operation as successful. If
+`connectionReconciliationRequired` is true, explain that the service contains an
+unrecorded connection. Ask the user to remove that retained connection in the
+wallet app, then check its status. Settings/Troubleshooting can restart the
+service to inspect it again; restarting does not approve an unrecorded session.
+Do not infer a free pairing slot from a failed or expired record.
+
+If the parent or Settings itself cannot be reached, explain the full app exit
+procedure in the setup guide. All participating apps must quit; closing a peer
+or window can leave the owner alive. Full app restart is also required for
+stored endpoint or installation changes. Do not kill another app's processes.
 
 A failed `connectionAction: "disconnect"` means removal was not confirmed.
 Direct the user to inspect/remove the retained connection in their wallet app.
@@ -468,9 +484,27 @@ For `read.list_review_activity`, `dataScope.recordCount` is the full matching lo
 
 For `read.get_review_session_detail`, transition rows with `isNoOp: true` are repeated lifecycle observations where the stored status did not change. Mention them only as audit details; do not count them as extra funnel progress.
 
-For local settings or local data management, call `settings.create_local_settings_session` and tell the user to open the returned settings URL in the same machine's system browser.
-
-Do not call MCP tools to mutate settings directly; direct settings mutator tools are not exposed. Do not call clearing active account a wallet disconnect. Endpoint changes apply after MCP server restart.
+For local settings, local records or connection-service recovery, call `settings.create_local_settings_session` to open the internal Settings card. Its name is unchanged; no external URL is returned. Explain Address for viewing assets, Local records, Troubleshooting or Advanced settings as needed and leave selection/confirmation to the user.
+
+For a backup, use the exact label Download backup in Local records. It prepares
+and verifies the snapshot internally and asks the app to save it in one user
+action. Do not instruct a separate Create backup step or confuse Download backup
+with Restore local records. If the actual download function is unsupported,
+the same file is saved once in the Sui MCP backup folder. Use the verified
+Backup saved result's Folder and File name for that local artifact. Do not
+describe that folder as the Host download destination. Suggested file name and Host acknowledgment do not establish where
+or whether a file was saved. Retry download is explicit and may create another
+copy after an unconfirmed earlier request. It uses the same snapshot only during
+its fixed transfer period; a new request after expiry or server restart captures
+current records. Cancel download does not delete a file already saved by the app.
+Use the same function-based product instructions across desktop apps. Missing
+advertisement is not proof of non-support, and timeout, cancellation or denial
+does not trigger local saving. Save a local copy is the explicit decision after
+an earlier possibly handled request. Retry save follows only a confirmed failure
+with no published file; Check status settles uncertain saving or cleanup without
+another file effect. Report saved-file and cleanup facts separately.
+
+Ordinary MCP tools never apply a Settings change. Do not call `ui.act_card` or `ui.read_settings_file` as model work. Never request/paste raw backup bytes or card permissions in chat. Clear default address only changes read context, not wallet connections or admitted transactions. Endpoint changes require quitting/reopening all apps; a connection-service restart does not apply them. Report operation result, temporary-file cleanup and Host download acknowledgment as separate facts. A saved result is not proof that the Host saved a downloaded file. For restore validation refusal, let the user correct input or choose another file and prepare a new confirmation; reading or returning to a frame never applies it.
 
 ## User Vocabulary