@zktx.io/sui-mcp 0.5.0 → 0.6.1

package/dist/core/read/readService.js

@@ -14,9 +14,6 @@ import { DEEPBOOK_MID_PRICE_DIRECTION, DEEPBOOK_MID_PRICE_PRECISION, DEEPBOOK_MI
 export * from "./readServiceTypes.js";
 export { listDeepbookTokenRegistry } from "./deepbookRegistry.js";
 const DEFAULT_DEEPBOOK_USDC_PRICE_AT_TIME_MAX_DISTANCE_MINUTES = 360;
-// Account inventory object scan: pages of listOwnedObjects to walk (50 objects per
-// page) and the max NFTs to surface. A coin-heavy account may truncate before all
-// objects are seen; the snapshot flags that rather than paging unbounded.
 const ACCOUNT_OBJECT_SCAN_PAGES = 6;
 const ACCOUNT_NFT_LIMIT = 60;
 const DEEPBOOK_USDC_PRICE_HISTORY_RESPONSE_SUMMARY = {
@@ -332,10 +329,6 @@ export class SuiReadService {
             cursor: summary.cursor
         };
     }
-    // The public account snapshot for the account page: the SuiNS name, coin
-    // balances (with the held-as split), owned NFTs, and other owned objects grouped
-    // by type. Each part is read independently so a missing name or object scan never
-    // blocks the balances.
     async summarizeAccountInventory(input) {
         const [walletSummary, name, owned] = await Promise.all([
             this.summarizeWalletAssets(input),
@@ -347,8 +340,6 @@ export class SuiReadService {
             account: input.account,
             fetchedAt: this.#fetchedAt(),
             name,
-            // Drop coins whose total balance is zero — an emptied coin object or
-            // accumulator residue is not a holding worth listing on the account page.
             balances: walletSummary.balances.filter((balance) => {
                 try {
                     return BigInt(balance.balance) !== 0n;
@@ -363,8 +354,6 @@ export class SuiReadService {
             objectsTruncated: owned.truncated
         };
     }
-    // The account's primary SuiNS name, or null when it has none (the lookup throws
-    // NOT_FOUND) or the call fails — a name is convenience, never gating.
     async #resolveAccountName(account) {
         const resolve = this.#client.core.defaultNameServiceName;
         if (!resolve) {
@@ -378,10 +367,6 @@ export class SuiReadService {
             return null;
         }
     }
-    // Enumerate owned objects (capped) and split them: Coin objects belong to the
-    // balance view, objects carrying a Display name/image are NFTs, and the rest are
-    // grouped by Move type. listOwnedObjects returns all three intermixed, so a
-    // coin-heavy account may truncate before reaching every NFT.
     async #scanOwnedObjects(account) {
         const nfts = [];
         const groups = new Map();
@@ -1493,10 +1478,6 @@ export class SuiReadService {
     #fetchedAt() {
         return this.#now().toISOString();
     }
-    // Resolve one coin type's verified unit (decimals/symbol) through the shared
-    // coin-metadata cache and DeepBook fallback. Public so other readers (e.g. the
-    // public chain-receipt reader) can render decimal amounts without duplicating
-    // the cache logic. Fails soft to an unavailable unit on an unresolvable type.
     async resolveCoinUnit(coinType) {
         let normalizedCoinType;
         try {

package/dist/core/read/readServiceTypes.js

@@ -42,8 +42,6 @@ export const DEEPBOOK_USDC_PRICE_HISTORY_SOURCE_UNAVAILABLE_REASONS = [
     "candle_fetch_failed",
     "official_indexer_invalid_payload"
 ];
-// Internal placeholder for sender-independent DeepBook market reads. The pinned Sui gRPC
-// resolver uses the same dummy sender when no transaction sender is provided.
 export const DEFAULT_DEEPBOOK_SIMULATION_SENDER = "0x0000000000000000000000000000000000000000000000000000000000000000";
 export const NOT_INSPECTED_ASSET_CLASSES = [
     {

package/dist/core/session/cardSession.js

@@ -2,7 +2,7 @@ import { z } from "zod";
 export const walletDisplaySchema = z.object({
     connectionId: z.string().min(1), pairingUri: z.string().startsWith("wc:"), expiresAt: z.string().datetime()
 }).strict();
-export const cardKindSchema = z.enum(["account", "receipt", "chart", "connect", "review"]);
+export const cardKindSchema = z.enum(["account", "receipt", "chart", "connect", "review", "settings"]);
 export const cardStateSchema = z.object({
     cardId: z.string().min(1), kind: cardKindSchema,
     state: z.enum(["ready", "running", "closed"]),
@@ -17,11 +17,7 @@ export const cardSnapshotSchema = cardStateSchema.extend({
     pollAfterMs: z.number().int().positive(),
     inputRemainingMs: z.number().int().nonnegative()
 });
-// Private display values from a receipt already read by the backend. These are
-// individual on-chain inputs, never a serialized transaction or a signature.
 export const receiptDisplaySchema = z.object({
-    // Sui syntax is validated by the backend producer/projection. The View checks
-    // equality with its selected digest and does not load an SDK to recompute it.
     transactionDigest: z.string().min(1),
     pureInputs: z.array(z.object({
         index: z.number().int().nonnegative(),

package/dist/core/session/cardSessionStore.js

@@ -8,6 +8,9 @@ import { assertNoForbiddenMcpFields } from "../action/forbiddenFields.js";
 import { cardSnapshotSchema } from "./cardSession.js";
 import { WorkflowConflict } from "./sqliteWalletWorkflowStore.js";
 import { parseWorkflowAction } from "./workflowView.js";
+import { randomUUID } from "node:crypto";
+import { settingsActionSchema, isSettingsDownloadFileAction, SettingsConflict } from "./settingsOperation.js";
+import { settingsInputError } from "./settingsInputError.js";
 export class CardError extends Error {
 }
 export class CardStore {
@@ -27,6 +30,8 @@ export class CardStore {
     async create(kind, input, execute = false) {
         this.assertCurrent();
         const business = kind === "connect" || kind === "review";
+        if (kind === "settings" && (!this.options.settings || execute || Object.keys(input).length))
+            throw new CardError("Settings cards are unavailable for this input.");
         if (business && (!this.options.workflow || execute))
             throw new CardError("This type of card is unavailable.");
         const parsed = execute ? parseCardInput(kind, input) : undefined;
@@ -42,20 +47,22 @@ export class CardStore {
             catch {
                 preparation = { status: "failed", error: "The choices for this card could not be loaded." };
             }
-            // Preparation may finish after reset/import or shutdown. Never create a
-            // card in replacement data from that stale continuation.
             this.assertCurrent();
         }
         assertNoForbiddenMcpFields({ input, preparation });
         const { base, token } = createLocalSessionBase(this.now(), DEFAULT_SESSION_TTL_MS);
         const record = { ownerId: this.options.ownerId, tokenHash: base.tokenHash,
-            scope: kind === "connect" ? "connect" : kind === "review" ? input.mode === "manage" ? "review_manage" : "review" : "read",
+            scope: kind === "settings" ? "settings" : kind === "connect" ? "connect" : kind === "review" ? input.mode === "manage" ? "review_manage" : "review" : "read",
+            ...(kind === "settings" ? { operationId: randomUUID() } : {}),
             ...(kind === "review" && input.mode === "manage" && typeof input.attemptId === "string" ? { operationId: input.attemptId } : {}),
             state: { cardId: base.id, kind, state: preparation.status === "failed" ? "closed" : "ready", revision: 0,
                 createdAt: base.createdAt, expiresAt: base.expiresAt, input,
                 ...(preparation.status === "failed" ? { reason: "failed", error: preparation.error } :
                     preparation.data === undefined ? {} : { data: preparation.data }) } };
-        this.options.records.create(record);
+        if (kind === "settings")
+            this.options.settings.create(record);
+        else
+            this.options.records.create(record);
         if (preparation.status === "failed")
             this.reportFailure(record, "input_preparation");
         const result = parsed === undefined ? await this.describe(record, false) : await this.submit({
@@ -64,8 +71,24 @@ export class CardStore {
         return { ...result, permission: token };
     }
     async read(input) { return this.describe(this.require(input), true); }
+    async readSettingsFile(input, limit) {
+        const record = this.require(input);
+        if (record.state.kind !== "settings" || !this.options.settings)
+            throw new CardError("This card does not provide a backup file.");
+        if (record.operationId !== input.operationId)
+            throw new CardError("This backup does not match the Settings operation.");
+        return this.options.settings.readFile(record, input.fileId, input.offset, limit, input.attemptId);
+    }
     async readSaved(cardId) { return (await this.describe(this.current(cardId), false)).snapshot; }
     async describe(record, uiObservation) {
+        if (record.state.kind === "settings") {
+            if (!this.options.settings)
+                throw new CardError("Settings cards are unavailable.");
+            const described = await this.options.settings.describe(record);
+            return { snapshot: cardSnapshotSchema.parse({ ...described.record.state, data: described.data,
+                    inputRemainingMs: described.record.state.state === "ready" ? Math.max(0, Date.parse(described.record.state.expiresAt) - this.now().getTime()) : 0,
+                    pollAfterMs: EXECUTION_POLLING_INTERVAL_SECONDS * 1000 }) };
+        }
         if (record.state.kind !== "connect" && record.state.kind !== "review")
             return this.response(record);
         if (!this.options.workflow)
@@ -83,6 +106,31 @@ export class CardStore {
     }
     async act(input) {
         const record = this.require(input);
+        if (record.state.kind === "settings") {
+            if (!this.options.settings)
+                throw new CardError("Settings cards are unavailable.");
+            const parsed = settingsActionSchema.safeParse(input.input);
+            if (!parsed.success)
+                return { ...await this.describe(record, false), error: { code: "invalid_card_input", message: "This Settings action is not valid." } };
+            if ((parsed.data.action === "settings_confirm" || parsed.data.action === "settings_download_backup") && record.acceptedInput !== undefined && isDeepStrictEqual(record.acceptedInput, parsed.data))
+                return this.describe(record, false);
+            if (input.revision !== record.state.revision && !isSettingsDownloadFileAction(parsed.data))
+                return { ...await this.describe(record, false), error: { code: "card_conflict", message: "This Settings selection changed. Review the current selection before continuing." } };
+            const kind = parsed.data.action === "settings_select" ? parsed.data.draft.kind : this.options.settings.operationKind(record);
+            try {
+                await this.options.settings.act(record, parsed.data);
+            }
+            catch (error) {
+                const invalid = settingsInputError(error, kind);
+                if (!(error instanceof SettingsConflict) && invalid === undefined)
+                    throw error;
+                return { ...await this.describe(this.current(input.cardId), false), error: {
+                        code: invalid === undefined ? "card_conflict" : "invalid_card_input",
+                        message: invalid?.message ?? error.message
+                    } };
+            }
+            return this.describe(this.current(input.cardId), false);
+        }
         if ((record.state.kind !== "connect" && record.state.kind !== "review") || !this.options.workflow) {
             return this.conflict(record, "This card does not accept wallet workflow actions.");
         }
@@ -112,7 +160,7 @@ export class CardStore {
     }
     async submit(input) {
         const record = this.require(input);
-        if (record.state.kind === "connect" || record.state.kind === "review")
+        if (record.state.kind === "connect" || record.state.kind === "review" || record.state.kind === "settings")
             throw new CardError("This card does not accept data selections.");
         let parsed;
         try {
@@ -149,7 +197,6 @@ export class CardStore {
         }
         const complete = { ...admitted, ...("receiptDisplay" in projected ? { receiptDisplay: projected.receiptDisplay } : {}),
             state: { ...admitted.state, data: projected.data, state: "closed", reason: "completed", revision: admitted.state.revision + 1 } };
-        // Do not report success or replay the source call if this commit fails.
         try {
             this.options.records.replace(admitted, complete);
         }
@@ -170,7 +217,7 @@ export class CardStore {
         try {
             this.options.logger?.error("Card read failed", { cardId: record.state.cardId, kind: record.state.kind, stage });
         }
-        catch { /* Logging does not own the operation's state. */ }
+        catch { }
     }
     conflict(record, message) {
         return { ...this.response(record), error: { code: "card_conflict", message } };

package/dist/core/session/reviewValidity.js

@@ -11,8 +11,6 @@ export function invalidateReviewEvidence(session, now) {
         const state = { ...session.reviewState, evidenceValidity: "invalidated", updatedAt: now.toISOString() };
         for (const field of REVIEW_MATERIAL_DERIVED_FIELDS)
             delete state[field];
-        // Keep the computation's failure reason, checks and stage provenance. Their
-        // presence describes that failed attempt, not currently usable material.
         return { ...session, lastActivityAt: now.toISOString(), reviewState: state };
     }
     return { ...session, status: "refresh_required", lastActivityAt: now.toISOString(),
@@ -33,7 +31,6 @@ export function materialStillMatches(verified, session, rowRevision, artifacts,
         !!material && sameHandle(material, verified.transactionMaterial) && Date.parse(material.expiresAt) > now.getTime() &&
         Buffer.from(material.transactionBytes).toString("base64") === verified.transactionBytesBase64;
 }
-// The caller owns a synchronous transaction and supplies its one decision time.
 export function decideReviewEvaluation(candidate, current, rowRevision, artifacts, material, admitted, now) {
     if (current.status !== "expired" && Date.parse(current.expiresAt) <= now.getTime()) {
         return { ...current, status: "expired" };

package/dist/core/session/sessionRecordStore.js

@@ -34,7 +34,6 @@ export class InMemorySessionRecordStore {
         this.revisions.clear();
     }
     hasUnsettledRequest(_id, _now) {
-        // This preparation-only fixture owns no wallet request records.
         return false;
     }
 }

package/dist/core/session/sessionStore.js

@@ -16,7 +16,6 @@ import { isFinalSessionStatus } from "./status.js";
 import { parseSuiAddress } from "../suiAddress.js";
 import { cloneLocalSession, createLocalSessionBase, DEFAULT_SESSION_TTL_MS, isLocalSessionExpired, tokenMatchesHash } from "./localSession.js";
 import { SessionStoreError } from "./sessionErrors.js";
-import { SettingsSessionManager } from "./settingsSessions.js";
 const PRIVATE_DERIVED_REVIEW_FIELD_BINDINGS = [
     {
         field: "humanReadableReview",
@@ -51,7 +50,6 @@ export class LocalSessionStore {
     sessions;
     privateReviewArtifacts;
     ownerId;
-    settings;
     ttlMs;
     clock;
     eventLog;
@@ -65,11 +63,6 @@ export class LocalSessionStore {
         this.privateReviewArtifacts = options.artifacts;
         this.ttlMs = options.ttlMs ?? DEFAULT_SESSION_TTL_MS;
         this.ownerId = options.ownerId ?? randomUUID();
-        this.settings = new SettingsSessionManager({
-            ttlMs: this.ttlMs,
-            appendEventLog: (record) => this.appendEventLog(record),
-            ...(options.settingsStore ? { recordStore: options.settingsStore } : {})
-        });
         this.eventLog = options.eventLog ?? new NullEventLogSink();
         this.activityStore = options.activityStore;
         this.transactionMaterialStore = options.transactionMaterialStore;
@@ -111,8 +104,6 @@ export class LocalSessionStore {
         });
         return { session: cloneLocalSession(session), token };
     }
-    // Snapshot access has no expiry, artifact reconciliation or external work.
-    // Public consumers project this private record before exposing any fields.
     readReviewSession(id) {
         const session = this.sessions.get(id);
         return session ? cloneLocalSession(session) : undefined;
@@ -137,8 +128,6 @@ export class LocalSessionStore {
                 transactionBytesBase64: Buffer.from(checked.transactionBytes).toString("base64") };
         }
         catch (error) {
-            // Invalid evidence is a candidate for refresh, never permission to mutate
-            // a potentially newer revision. Storage failures must still propagate.
             if (!(error instanceof LocalTransactionMaterialStoreError) && !(error instanceof ReviewEvidenceMismatch) && !(error instanceof ZodError))
                 throw error;
         }
@@ -157,8 +146,6 @@ export class LocalSessionStore {
             this.recordEvaluationEvents(result.events);
             return cloneLocalSession(result.session);
         }
-        // Preparation-only in-memory fixtures share the decision function. They do
-        // not establish SQLite atomicity or wallet admission guarantees.
         const current = this.sessions.get(id);
         if (!current)
             return undefined;
@@ -193,8 +180,6 @@ export class LocalSessionStore {
         if (!session) {
             return false;
         }
-        // Review sessions expose expired/final lifecycle states through read APIs after token validation.
-        // Mutable methods own expiry transitions and return lifecycle-specific errors.
         return tokenMatchesHash(session.tokenHash, token);
     }
     async recordWalletConnected(id, account, now = new Date()) {
@@ -215,9 +200,6 @@ export class LocalSessionStore {
             throw new SessionStoreError("invalid_session_transition", `Review session already bound to a different account: ${id}`);
         }
         if (nextSession.status === "proposed") {
-            // Explicit backend account binding follows the preparation lifecycle.
-            // Active read context alone is not wallet approval; the workflow checks
-            // the live wallet connection before invoking this operation.
             transition(nextSession, "awaiting_wallet");
             transition(nextSession, "wallet_connected");
         }
@@ -327,15 +309,6 @@ export class LocalSessionStore {
         }
         return session;
     }
-    async createSettingsSession(now = new Date()) {
-        return this.settings.create(now);
-    }
-    async getSettingsSession(id, now = new Date()) {
-        return this.settings.get(id, now);
-    }
-    async validateSettingsToken(id, token, now = new Date()) {
-        return this.settings.validateToken(id, token, now);
-    }
     async prepareReviewedTransaction(id, planId, account, now = this.clock()) {
         const candidate = await this.inspectReview(id, now);
         if (!candidate)
@@ -360,7 +333,6 @@ export class LocalSessionStore {
             this.deleteReviewSessionTransactionMaterials(id);
         }
         this.sessions.clear();
-        this.settings.clear();
         await this.appendEventLog({
             type: "local_sessions.invalidated",
             sessionId: "all",
@@ -373,7 +345,6 @@ export class LocalSessionStore {
             await this.eventLog.append(record);
         }
         catch (error) {
-            // Event logs are optional audit/debug sinks. SQLite and in-memory session state remain authoritative.
             this.logger.error("event log append failed", {
                 eventType: record.type,
                 error: error instanceof Error ? error.message : String(error)
@@ -589,9 +560,6 @@ export class LocalSessionStore {
         }
     }
 }
-// In-memory session store: the orchestration above with Map-backed record and
-// artifact stores. Public name + constructor are unchanged so existing callers and
-// the session-store contract test keep working as the regression wall.
 export class InMemorySessionStore extends LocalSessionStore {
     constructor(options) {
         super({

package/dist/core/session/settingsFileIdentity.js

@@ -0,0 +1,9 @@
+export function settingsDownloadPath(fileId) {
+    return `.settings-staging/${fileId}.download`;
+}
+export function settingsBackupPath(operationId) { return `backups/${operationId}.json`; }
+export function isSettingsDownloadFile(file) {
+    return file.role === "export" && file.relativePath === settingsDownloadPath(file.fileId);
+}
+export const SETTINGS_DOWNLOAD_FILE_SQL = "(role='export' AND relative_path=('.settings-staging/' || file_id || '.download'))";
+export const SETTINGS_FILE_CLEANUP_SQL = `(invalidated=1 OR (role='export' AND NOT ${SETTINGS_DOWNLOAD_FILE_SQL}))`;

package/dist/core/session/settingsFileProtocol.js

@@ -0,0 +1,20 @@
+import { SETTINGS_IMPORT_MAX_SIZE } from "./settingsOperation.js";
+export const MAX_JSON_BODY_BYTES = 64 * 1024;
+export function settingsJsonSize(value) { return new TextEncoder().encode(JSON.stringify(value)).length; }
+export function settingsRawChunkBudget(envelopeWithEmptyBase64) {
+    const room = MAX_JSON_BODY_BYTES - settingsJsonSize(envelopeWithEmptyBase64);
+    return room > 0 ? 3 * Math.floor(room / 4) : 0;
+}
+export function settingsUploadMessageBudget(message) {
+    if (!message || typeof message !== "object")
+        return undefined;
+    const envelope = structuredClone(message);
+    if (envelope.method !== "tools/call" || envelope.params?.name !== "ui.act_card" ||
+        envelope.params.arguments?.input?.action !== "settings_upload_chunk")
+        return undefined;
+    envelope.id = Number.MAX_SAFE_INTEGER;
+    envelope.params.arguments.revision = Number.MAX_SAFE_INTEGER;
+    envelope.params.arguments.input.offset = SETTINGS_IMPORT_MAX_SIZE;
+    envelope.params.arguments.input.chunkBase64 = "";
+    return settingsRawChunkBudget(envelope);
+}