@zktx.io/sui-mcp 0.5.0

package/dist/mcp/responseGuidance.js

@@ -0,0 +1,326 @@
+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) {
+    return {
+        canAnswer: [
+            "stored_active_account_read_context",
+            "wallet_connections_when_wallet_availability_is_available",
+            "connection_qualified_default_asset_account",
+            "pending_local_wallet_connection_interactions",
+            ...(hasConnectionConflict ? ["multiple_saved_connections_require_user_targeted_disconnection"] : []),
+            "pending_local_review_interactions",
+            "wallet_operation_availability_separate_from_stored_transaction_facts"
+        ],
+        cannotAnswer: [
+            "wallet_login_or_authentication",
+            "implicit_default_unavailability_as_explicit_address_support_for_every_tool",
+            "wallet_custody_or_authorization",
+            "wallet_unavailability_as_chain_failure_or_lost_stored_result",
+            "last_service_observation_as_live_wallet_app_state",
+            "sdk_availability_or_recorded_connection_as_account_use_or_signing_authority",
+            "transaction_execution_result",
+            "transaction_building",
+            "signing_data_or_readiness",
+            "complete_wallet_history",
+            "profit_or_pnl"
+        ],
+        preconditionFields: ["walletAvailability", "assetReadAccount", ...(hasConnectionConflict ? ["connectionConflict"] : [])],
+        answerFields: ["activeAccount", "connections", "assetReadAccount", "pendingWalletConnections", "pendingReviewSessions", "walletAvailability",
+            ...(hasConnectionConflict ? ["connectionConflict"] : []),
+            ...(hasWalletObservation ? ["walletObservation"] : [])],
+        diagnosticOnlyFields: [
+            "pendingWalletConnections.truncated",
+            "pendingReviewSessions.truncated"
+        ],
+        followUp: {
+            tool: TOOL_NAMES.sessionGetReviewStatus,
+            inputFields: ["pendingReviewSessions.items[].reviewSessionId"],
+            answerFields: ["pollingStatus", "statusCategory", "reviewState"],
+            reason: "Read one review's stored preparation and request facts. The overview lists live input or ongoing work; cancelled input alone is not pending."
+        }
+    };
+}
+export function executionResultUserAnswerUse(fields = {}) {
+    const hasExecutionResult = fields.hasExecutionResult ?? false;
+    const hasWaitOutcome = fields.hasWaitOutcome ?? false;
+    return {
+        canAnswer: [
+            "current_local_execution_polling_status",
+            "whether_user_action_or_chain_polling_is_still_pending",
+            "wallet_operation_availability_separate_from_stored_transaction_facts",
+            ...(hasExecutionResult ? ["recorded_review_execution_result"] : [])
+        ],
+        cannotAnswer: [
+            ...(hasExecutionResult ? [] : ["recorded_review_execution_result_without_executionResult_field"]),
+            "transaction_execution_guarantee",
+            "chain_receipt_as_execution_guarantee",
+            "chain_receipt_as_route_quality",
+            "chain_receipt_as_fiat_pnl_tax_or_peg_evidence",
+            "absolute_safety_verdict",
+            "route_quality",
+            "wallet_custody_or_authorization",
+            "wallet_unavailability_as_chain_failure_or_lost_stored_result",
+            "transaction_building",
+            "signing_data_or_readiness",
+            "complete_wallet_history",
+            "profit_or_pnl"
+        ],
+        answerFields: [
+            "walletAvailability", "progress", ...(fields.hasConnectionConflict ? ["connectionConflict"] : []), ...(hasWaitOutcome ? ["waitOutcome"] : []),
+            "reviewSessionId",
+            "status",
+            "pollingStatus",
+            "statusCategory",
+            "lastActivityAt",
+            "pollingHint",
+            ...(fields.hasRequest ? ["attemptId", "requestStatus", "request"] : []),
+            ...(hasExecutionResult ? ["executionResult"] : [])
+        ],
+        conclusionRuleFields: [
+            "walletAvailability.status", "progress.status", "statusCategory",
+            "pollingHint.finalStatuses",
+            "pollingHint.userActionRequiredStatuses",
+            "pollingHint.nonTerminalStatuses"
+        ],
+        diagnosticOnlyFields: [],
+        followUp: {
+            tool: TOOL_NAMES.sessionGetReviewStatus,
+            inputFields: ["reviewSessionId"],
+            answerFields: ["pollingStatus", "statusCategory", "reviewState"],
+            reason: "Use for current review state and checks. Wallet availability describes backend operations, not authorization. An unavailable wait retains stored facts and does not prove chain failure."
+        }
+    };
+}
+export function reviewStatusUserAnswerUse(hasReviewState, hasAdapterLifecycle = false, hasHumanReadableReview = false, hasSimulation = false, hasConnectionConflict = false) {
+    return {
+        canAnswer: [
+            "current_local_review_session_status",
+            "current_review_checks_when_reviewState_is_present",
+            ...(hasAdapterLifecycle ? ["current_adapter_review_lifecycle_stage_status"] : []),
+            ...(hasHumanReadableReview ? ["current_human_readable_review_facts_projected_from_verified_review_evidence"] : []),
+            ...(hasSimulation ? ["current_review_time_simulation_summary_projected_from_private_review_evidence"] : []),
+            "whether_user_action_or_chain_polling_is_still_pending",
+            "wallet_operation_availability_separate_from_stored_transaction_facts"
+        ],
+        cannotAnswer: [
+            "transaction_execution_guarantee",
+            "absolute_safety_verdict",
+            "route_quality",
+            "wallet_custody_or_authorization",
+            "wallet_unavailability_as_chain_failure_or_lost_stored_result",
+            "transaction_building",
+            "transaction_bytes_or_signatures",
+            "signing_data_or_readiness",
+            "complete_wallet_history",
+            "profit_or_pnl"
+        ],
+        answerFields: [
+            "walletAvailability", "progress", ...(hasConnectionConflict ? ["connectionConflict"] : []), "reviewSessionId",
+            "status",
+            "pollingStatus",
+            "statusCategory",
+            ...(hasReviewState
+                ? [
+                    "reviewState.status",
+                    "reviewState.checks",
+                    "reviewState.blockedReason",
+                    "reviewState.refreshReason"
+                ]
+                : []),
+            ...(hasAdapterLifecycle
+                ? [
+                    "reviewState.adapterLifecycle",
+                    "reviewState.adapterLifecycle.stageCatalogId",
+                    "reviewState.adapterLifecycle.completedStages",
+                    "reviewState.adapterLifecycle.missingStages"
+                ]
+                : []),
+            ...(hasHumanReadableReview
+                ? [
+                    "reviewState.humanReadableReview",
+                    "reviewState.humanReadableReview.kind",
+                    "reviewState.humanReadableReview.proposedAction",
+                    "reviewState.humanReadableReview.assetFlow",
+                    "reviewState.humanReadableReview.targets",
+                    "reviewState.humanReadableReview.evidenceUsed",
+                    "reviewState.humanReadableReview.missingEvidence",
+                    "reviewState.humanReadableReview.requiredUserChoices",
+                    "reviewState.humanReadableReview.freshness",
+                    "reviewState.humanReadableReview.unsupportedClaims",
+                    "reviewState.humanReadableReview.blockingChecks"
+                ]
+                : []),
+            ...(hasSimulation
+                ? [
+                    "reviewState.simulation",
+                    "reviewState.simulation.provider",
+                    "reviewState.simulation.checksEnabled",
+                    "reviewState.simulation.success",
+                    "reviewState.simulation.gasCostSummary",
+                    "reviewState.simulation.gasCostSummary.computationCostRaw",
+                    "reviewState.simulation.gasCostSummary.storageCostRaw",
+                    "reviewState.simulation.gasCostSummary.storageRebateRaw",
+                    "reviewState.simulation.gasCostSummary.nonRefundableStorageFeeRaw",
+                    "reviewState.simulation.balanceChanges",
+                    "reviewState.simulation.objectChanges"
+                ]
+                : []),
+            "lastActivityAt"
+        ],
+        diagnosticOnlyFields: [],
+        followUp: {
+            tool: TOOL_NAMES.sessionGetExecutionResult,
+            inputFields: ["reviewSessionId"],
+            answerFields: ["executionResult"],
+            reason: "Use when the user asks for a recorded execution result; status alone is not transaction execution proof."
+        }
+    };
+}
+export function reviewActivityListUserAnswerUse() {
+    return {
+        canAnswer: ["local_review_session_rows_for_the_selected_account", "current_stored_review_status_counts_by_row"],
+        cannotAnswer: [
+            "sui_wallet_transaction_history",
+            "complete_wallet_history",
+            "execution_result_detail",
+            "transaction_building",
+            "signing_data_or_readiness",
+            "profit_or_pnl"
+        ],
+        answerFields: ["activities", "activities[].reviewSessionId", "activities[].reviewStatus", "activities[].updatedAt"],
+        diagnosticOnlyFields: ["dataScope", "accountSource", "lowSampleWarning", "lowSampleThreshold", "truncated"],
+        followUp: {
+            tool: TOOL_NAMES.readGetReviewSessionDetail,
+            inputFields: ["activities[].reviewSessionId"],
+            answerFields: ["session", "planJson", "intentJson", "stateSnapshots", "transitions", "requests"],
+            reason: "Use for stored plan, state snapshot, transition, and execution detail for one review session."
+        }
+    };
+}
+export function reviewFunnelUserAnswerUse() {
+    return {
+        canAnswer: ["local_review_lifecycle_counts_for_the_selected_account"],
+        cannotAnswer: [
+            "sui_wallet_transaction_history",
+            "complete_wallet_history",
+            "execution_success_rate_for_all_wallet_activity",
+            "transaction_building",
+            "signing_data_or_readiness",
+            "profit_or_pnl"
+        ],
+        answerFields: ["summary"],
+        diagnosticOnlyFields: ["dataScope", "accountSource", "lowSampleWarning", "lowSampleThreshold", "truncated"]
+    };
+}
+export function prepareActionReviewUserAnswerUse(fields = {}) {
+    const hasBlockingPreliminaryChecks = fields.hasBlockingPreliminaryChecks ?? false;
+    return {
+        canAnswer: [
+            "internal_review_card_for_user_review",
+            "preliminary_check_results_for_proposed_plan",
+            "proposed_plan_asset_flow_preview",
+            ...(hasBlockingPreliminaryChecks ? ["why_signing_is_currently_blocked_for_this_review"] : [])
+        ],
+        cannotAnswer: [
+            "transaction_execution_guarantee",
+            "transaction_building",
+            "signing_data_or_readiness",
+            "wallet_custody_or_authorization",
+            "route_quality",
+            "fiat_usd_cash_out",
+            "profit_or_pnl"
+        ],
+        answerFields: [
+            "reviewSessionId",
+            "card",
+            "plans",
+            "plans[].title",
+            "plans[].summary",
+            "plans[].assetFlowPreview",
+            "plans[].preliminaryChecks",
+            "preliminaryChecks"
+        ],
+        conclusionRuleFields: ["plans[].preliminaryChecks", "preliminaryChecks"],
+        diagnosticOnlyFields: ["plans[].adapterData", "plans[].createdAt", "plans[].id"],
+        followUp: {
+            tool: TOOL_NAMES.sessionGetReviewStatus,
+            inputFields: ["reviewSessionId"],
+            answerFields: ["pollingStatus", "statusCategory", "reviewState"],
+            reason: "Use for current review readiness; the prepare response only describes the proposal and any blocking preliminary checks."
+        }
+    };
+}
+export function prepareExternalProposalReviewUserAnswerUse() {
+    return {
+        canAnswer: [
+            "internal_review_card_for_user_review",
+            "external_proposal_summary_for_local_review",
+            "proposal_asset_flow_preview",
+            "proposal_recipient_or_target_fields",
+            "missing_evidence_for_non_signable_review",
+            "required_user_choices_for_non_signable_review",
+            "unsupported_claims_for_non_signable_review",
+            "why_signing_is_currently_blocked_for_this_review"
+        ],
+        cannotAnswer: [
+            "transaction_execution_guarantee",
+            "transaction_building",
+            "signing_data_or_readiness",
+            "wallet_custody_or_authorization",
+            "route_quality",
+            EXTERNAL_PROPOSAL_SETTLEMENT_TOKEN_SELECTION_UNSUPPORTED_CLAIM_ID,
+            "fiat_usd_cash_out",
+            "profit_or_pnl"
+        ],
+        answerFields: [
+            "reviewSessionId",
+            "card",
+            "plans",
+            "plans[].reviewModel.proposedAction",
+            "plans[].reviewModel.assetFlow",
+            "plans[].reviewModel.recipients",
+            "plans[].reviewModel.targets",
+            "plans[].reviewModel.evidenceUsed",
+            "plans[].reviewModel.missingEvidence",
+            "plans[].reviewModel.requiredUserChoices",
+            "plans[].reviewModel.unsupportedClaims",
+            "plans[].reviewModel.freshness",
+            "plans[].reviewModel.blockingChecks",
+            "plans[].reviewModel.nonSignableReason",
+            "preliminaryChecks"
+        ],
+        conclusionRuleFields: [
+            "plans[].reviewModel.unsupportedClaims",
+            "plans[].reviewModel.nonSignableReason",
+            "preliminaryChecks"
+        ],
+        diagnosticOnlyFields: [
+            "plans[].adapterData",
+            "plans[].createdAt",
+            "plans[].id",
+            "plans[].reviewModel.rejectedExecutableFields"
+        ],
+        followUp: {
+            tool: TOOL_NAMES.sessionGetReviewStatus,
+            inputFields: ["reviewSessionId"],
+            answerFields: ["pollingStatus", "statusCategory", "reviewState"],
+            reason: "Use for current review status after the user opens the internal card; the prepare response does not make the proposal signable."
+        }
+    };
+}
+export function reviewSessionDetailUserAnswerUse(options = { hasCurrentRequest: false, hasCurrentExecution: false, hasHistoricalExecution: false }) {
+    const hasExecution = options.hasCurrentExecution || options.hasHistoricalExecution;
+    return {
+        canAnswer: ["stored_local_review_session_plan_and_lifecycle_detail", "stored_review_state_snapshots", "stored_transaction_request_history",
+            ...(hasExecution ? ["stored_review_chain_execution_result"] : [])],
+        cannotAnswer: ["sui_wallet_transaction_history", "complete_wallet_history", "transaction_execution_guarantee", "absolute_safety_verdict",
+            "route_quality", "wallet_custody_or_authorization", "transaction_building", "signing_data_or_readiness", "profit_or_pnl",
+            ...(hasExecution ? [] : ["chain_execution_result_without_execution_field"])],
+        answerFields: ["session", "planJson", "intentJson", "stateSnapshots", "transitions", "requests",
+            ...(options.hasCurrentRequest ? ["request"] : []), ...(options.hasCurrentExecution ? ["request.execution"] : [])],
+        diagnosticOnlyFields: ["dataScope", "accountSource", "lowSampleWarning", "lowSampleThreshold", "truncated", "requestCount"],
+        followUp: { tool: TOOL_NAMES.sessionGetReviewStatus, inputFields: ["session.reviewSessionId"],
+            answerFields: ["status", "pollingStatus", "reviewState"],
+            reason: "Read the current DB review and request status. Stored history, including imported history, is not an active approval." }
+    };
+}

package/dist/mcp/result.js

@@ -0,0 +1,17 @@
+import { assertNoForbiddenMcpFields } from "../core/action/forbiddenFields.js";
+export function okToolResult(data) {
+    const payload = { ok: true, data };
+    assertNoForbiddenMcpFields(payload);
+    return {
+        structuredContent: payload,
+        content: [{ type: "text", text: JSON.stringify(payload, null, 2) }]
+    };
+}
+export function errorToolResult(error) {
+    const payload = { ok: false, error };
+    assertNoForbiddenMcpFields(payload);
+    return {
+        isError: true,
+        content: [{ type: "text", text: JSON.stringify(payload, null, 2) }]
+    };
+}

package/dist/mcp/schemas.js

@@ -0,0 +1,11 @@
+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 {
+        ok: z.literal(true),
+        data: z.object(dataShape)
+    };
+}

package/dist/mcp/server.js

@@ -0,0 +1,32 @@
+import { registerReadCards } from "../mcp-ui/tools.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { registerMcpPrompts } from "./prompts.js";
+import { registerMcpResources } from "./resources.js";
+import { SERVER_INSTRUCTIONS, SERVER_NAME, SERVER_VERSION } from "./serverInfo.js";
+import { assertAllToolNamesValid } from "./toolNames.js";
+import { registerActionTools } from "./tools/action/prepareSuiActionReview.js";
+import { registerAccountTools } from "./tools/account/index.js";
+import { registerReadTools } from "./tools/read/index.js";
+import { registerSettingsTools } from "./tools/settings/index.js";
+import { registerSessionTools } from "./tools/session/index.js";
+export function createMcpServer(deps) {
+    assertAllToolNamesValid();
+    const server = new McpServer({
+        name: SERVER_NAME,
+        version: SERVER_VERSION
+    }, {
+        instructions: SERVER_INSTRUCTIONS
+    });
+    registerMcpResources(server);
+    registerReadCards(server, deps);
+    registerMcpPrompts(server, deps.promptSurfaces ?? []);
+    registerAccountTools(server, deps);
+    registerReadTools(server, deps);
+    registerSettingsTools(server, deps);
+    registerActionTools(server, deps);
+    registerSessionTools(server, deps);
+    return server;
+}
+export async function startMcp(server, transport) {
+    await server.connect(transport);
+}

package/dist/mcp/serverInfo.js

@@ -0,0 +1,131 @@
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { DEEPBOOK_SOURCE_OWNER_RUNTIME_WORDING } from "../core/read/deepbookSourceOwners.js";
+import { TOOL_NAMES } from "./toolNames.js";
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "../..");
+const packageMetadata = JSON.parse(readFileSync(resolve(packageRoot, "package.json"), "utf8"));
+export const PACKAGE_NAME = packageMetadata.name;
+export const SERVER_NAME = "sui-mcp";
+export const SERVER_VERSION = packageMetadata.version;
+export const SERVER_NETWORK = "mainnet";
+export const SERVER_RUNTIME = "local_stdio";
+export const SERVER_TRANSPORT = "grpc_graphql";
+export const USD_INTENT_ANSWER_REQUIRED_TOOLS = [
+    TOOL_NAMES.readGetServerStatus,
+    TOOL_NAMES.readListSettlementAssetGroups,
+    TOOL_NAMES.readPreviewIntentEvidence
+];
+export const USD_PARITY_ANSWER_REQUIRED_TOOLS = [
+    TOOL_NAMES.readGetServerStatus,
+    TOOL_NAMES.readListSettlementAssetGroups,
+    TOOL_NAMES.readSummarizeSettlementAssetGroupParity
+];
+export const EVIDENCE_POLICY = {
+    version: "intent-evidence-alpha-2026-05-23",
+    releaseGate: "intent_evidence_v1",
+    requiredFirstCheck: true,
+    requiredStatusFields: [
+        "packageName",
+        "version",
+        "evidencePolicy.version",
+        "network",
+        "implementedToolsCount"
+    ],
+    gates: [
+        "server_status_version_check",
+        "natural_language_settlement_asset_group_evidence",
+        "sdk_sot_no_duplicate_registry_or_amount_parser",
+        "requested_account_inference_policy",
+        "wallet_balance_snapshot_not_receipt_proof",
+        "deepbook_quote_no_fiat_or_route_inference",
+        "pnl_unsupported"
+    ]
+};
+export const SERVER_INSTRUCTIONS = [
+    "Sui MCP is a mainnet-only Sui DeFi intent evidence toolkit. Ordinary MCP tools return evidence or internal cards, never signing authority, bytes or signatures. Only user card selection and wallet approval authorize the backend WalletConnect flow: verify reviewed digest and signer, submit once, then read chain effects. Request status is separate from chain success/failure; uncertain results are read by digest, never resubmitted.",
+    "External proposals are untrusted facts; plans[].reviewModel is review context, not transaction material, route/settlement choice, signing/readiness, or execution readiness.",
+    "PTB graphs are diagnostics only; not transaction input, wallet authorization, signing/readiness, execution readiness, route quality, or safety.",
+    "Use response-local fields: userAnswerUse.answerFields/preconditionFields/conclusionRuleFields/cannotAnswer/diagnosticOnlyFields/followUp, pollingHint, and quantitySemantics.",
+    "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."
+].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.readGetServerStatus,
+    TOOL_NAMES.readListSupportedProtocols,
+    TOOL_NAMES.readListDeepbookPools,
+    TOOL_NAMES.readListDeepbookTokens,
+    TOOL_NAMES.readInspectDeepbookOrderbook,
+    TOOL_NAMES.readGetDeepbookMidPrice,
+    TOOL_NAMES.readGetDeepbookUsdcPriceHistory,
+    TOOL_NAMES.readGetDeepbookUsdcPriceAtTime,
+    TOOL_NAMES.readQuoteDeepbookAction,
+    TOOL_NAMES.readQuoteDeepbookDisplayAmount,
+    TOOL_NAMES.readSummarizeDeepbookAccountInventory,
+    TOOL_NAMES.readSummarizeWalletAssets,
+    TOOL_NAMES.readClassifyWalletAssets,
+    TOOL_NAMES.readListSettlementAssetGroups,
+    TOOL_NAMES.readSummarizeSettlementAssetGroupParity,
+    TOOL_NAMES.readPreviewIntentEvidence,
+    TOOL_NAMES.readListReviewActivity,
+    TOOL_NAMES.readSummarizeReviewFunnel,
+    TOOL_NAMES.readGetReviewSessionDetail,
+    TOOL_NAMES.readInspectSuiTransaction,
+    TOOL_NAMES.readScanSuiAccountActivity,
+    TOOL_NAMES.readSummarizeSuiActivityScan,
+    TOOL_NAMES.readScanSuiFunctionActivity,
+    TOOL_NAMES.readSummarizeSuiFunctionActivityScan,
+    TOOL_NAMES.readSummarizeSuiAccountActivity,
+    TOOL_NAMES.readGetAccountAssetTimeline,
+    TOOL_NAMES.settingsCreateLocalSettingsSession,
+    TOOL_NAMES.settingsGetLocalSettings,
+    TOOL_NAMES.actionPrepareSuiActionReview,
+    TOOL_NAMES.actionPrepareExternalProposalReview,
+    TOOL_NAMES.accountGetActiveAccount,
+    TOOL_NAMES.accountClearActiveAccount,
+    TOOL_NAMES.sessionCreateWalletConnection,
+    TOOL_NAMES.sessionGetWalletConnection,
+    TOOL_NAMES.sessionWaitWalletConnection,
+    TOOL_NAMES.sessionOpenReviewManagement,
+    TOOL_NAMES.sessionGetInteractionStatus,
+    TOOL_NAMES.sessionGetReviewStatus,
+    TOOL_NAMES.sessionGetExecutionResult,
+    TOOL_NAMES.sessionWaitExecutionResult
+];
+export const FAIL_CLOSED_TOOLS = [];
+export function toolAvailability(requiredTools) {
+    const implemented = new Set(IMPLEMENTED_TOOLS);
+    const missingRequiredTools = requiredTools.filter((tool) => !implemented.has(tool));
+    return {
+        statusTool: TOOL_NAMES.readGetServerStatus,
+        packageName: PACKAGE_NAME,
+        version: SERVER_VERSION,
+        evidencePolicyVersion: EVIDENCE_POLICY.version,
+        network: SERVER_NETWORK,
+        implementedToolsCount: IMPLEMENTED_TOOLS.length,
+        requiredTools: requiredTools.map((name) => ({ name, available: implemented.has(name) })),
+        missingRequiredTools,
+        requiredToolsAvailable: missingRequiredTools.length === 0,
+        unavailableReason: missingRequiredTools.length === 0 ? null : "required_tool_missing_from_current_server_build"
+    };
+}
+export const SERVER_LIMITATIONS = [
+    "Current asset reads without a user-provided address require a selected account with a usable current wallet connection. session.get_interaction_status.assetReadAccount reports whether that default is available. Only tools with an account input accept explicit addresses; DeepBook account inventory requires a connected selected account. Explicit-address coin balance reads are public-address snapshots and do not create active account context. Active account is read context only, not signing authorization, login, custody, or persistent permission.",
+    "Review activity tools summarize local Sui MCP review evidence only. Sui activity tools use user-requested bounded GraphQL reads and store normalized transaction facts only for known wallet context; function activity scans are sent-transaction scans only. They are not background indexers, complete history, balance history, complete gas history, affected-object history, or P&L.",
+    `read.get_account_asset_timeline reads stored local account activity facts and returns observed raw net-flow bars with scan coverage. It does not start scans, prove complete wallet history, provide held balances without balanceBars, compute USD value, P&L, tax, cost basis, route advice, transaction-building input, signing data, or signing readiness. Optional USDC references are token-denominated ${DEEPBOOK_SOURCE_OWNER_RUNTIME_WORDING.officialIndexerCandleReferences} only, ${DEEPBOOK_SOURCE_OWNER_RUNTIME_WORDING.usdcNotFiatUsdAndNotPeg}.`,
+    "Sui activity transactionContext facts are transaction-level facts without transaction-wide balance-change aggregates, and they are answer fields only when the response returns them. requestedAccountTransactionFacts, requestedAccount, and requestedAccountEffect are the account-specific balance-change surfaces. Activity quantitySemantics marks balance amountRaw fields as raw integers that require verified decimals for display conversion. accountBalanceChangeInferencePolicy marks whether returned account balance rows can be used or transaction-level context must not be used for account amount inference. Gas raw fields use MIST, and returned gasCost display facts use @mysten/sui MIST_PER_SUI.",
+    "Wallet asset classification covers only current coin balances returned by Sui gRPC listBalances for an explicit address or the active account. Wallet balance quantitySemantics marks those reads as current snapshots, not transaction history, receipt proof, acquisition source, object provenance, P&L, cost basis, or signing material. DeepBook account inventory is a separate active-account read surface; neither surface creates routes, funding plans, portfolio plans, or signing material.",
+    "High-risk read responses include userAnswerUse. Prefer userAnswerUse.preconditionFields before answering, userAnswerUse.answerFields for the answer path, userAnswerUse.conclusionRuleFields for conclusion limits, userAnswerUse.diagnosticOnlyFields for source or troubleshooting context, and userAnswerUse.followUp when a different tool and field are required. USD intent and parity responses also include toolAvailability as a precondition field for current server-build support.",
+    "Intent evidence maps natural-language USD-denominated targets to pinned DeepBook SDK settlement asset groups and current wallet balance evidence. responseSummary.answerCompleteness names the answer class and required fields. Settlement-asset-only answers use responseSummary; selected-target evidence requires user selection provenance and also uses selectedTarget, candidateConversions, and requiredUserChoices when userAnswerUse.answerFields lists them. Direct pool quote evidence is returned and supported only when a quoted candidate exists. responseSummary.doNotUseForConclusion names quote results, outside-settlement-group assets, and route-dependent support as excluded from the conclusion. Intent evidence does not silently choose settlement assets, rank venues or routes, evaluate gas reserve, build transactions, or produce signing material.",
+    "DeepBook quotes convert explicit raw or display source inputs through pinned token units and return scoped SDK simulation facts plus raw quote evidence. Their quantitySemantics says canUseForPaymentAnswer and canUseForShortfallAnswer are false, doNotCombineWithPaymentAnswer is true, requiredPaymentAnswerTool is read.preview_intent_evidence, and requiredPaymentAnswerField is responseSummary.",
+    "Action preparation returns internal Review cards. A current card with valid UI permission automatically prepares and renews verified conditions for one selected wallet/account; only the explicit Request wallet approval action can request a signature. Supported DeepBook account-bound swap review verifies stored transaction material, digest, ownership, quote/policy, human-readable facts, simulation and PTB evidence. Only a scoped app-only user action and wallet approval authorize the backend WalletConnect request; ordinary MCP calls never sign or submit. Transaction bytes and signatures never enter card/model results. The backend verifies returned transaction digest and signer, submits once, and independently reads chain effects. requestStatus is separate from chain execution success/failure: stopped, request_failed and outcome_unknown do not prove a chain failure. Lost replies are resolved by reading the same request/digest, never automatic resubmission. External proposals remain non-signable. Receipts do not establish execution guarantees, route quality, fiat value, P&L, tax, peg proof or best-price advice.",
+    "read.list_deepbook_pools and read.list_deepbook_tokens return static SDK registry metadata, not live liquidity, live token discovery, or active pool state.",
+    `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."
+];

package/dist/mcp/toolErrors.js

@@ -0,0 +1,118 @@
+import { WalletUnavailableError } from "../core/session/walletConnection.js";
+import { WorkflowConflict } from "../core/session/sqliteWalletWorkflowStore.js";
+import { CardError } from "../core/session/cardSessionStore.js";
+import { ActivityStoreReadError } from "../core/activity/activityStore.js";
+import { TransactionActivityError } from "../core/activity/transactionActivityTypes.js";
+import { LocalSettingsError, PreferencesStoreError } from "../core/preferences/preferencesStore.js";
+import { SessionStoreError } from "../core/session/sessionStore.js";
+import { WaitRequestAbortedError } from "../core/session/wait.js";
+import { SuiEndpointError } from "../core/suiEndpoint.js";
+import { errorToolResult } from "./result.js";
+export function activityStoreToolError(error, logger) {
+    if (error instanceof ActivityStoreReadError) {
+        return errorToolResult({
+            kind: error.kind,
+            details: error.details
+        });
+    }
+    logger.error("activity store call failed", {
+        error: error instanceof Error ? error.message : String(error)
+    });
+    return errorToolResult({
+        kind: "internal_error",
+        details: { message: "Activity store call failed" }
+    });
+}
+export function transactionActivityToolError(error, logger) {
+    if (error instanceof TransactionActivityError) {
+        return errorToolResult({
+            kind: error.kind,
+            details: error.details
+        });
+    }
+    if (error instanceof ActivityStoreReadError) {
+        return errorToolResult({
+            kind: error.kind,
+            details: error.details
+        });
+    }
+    logger.error("transaction activity call failed", {
+        error: error instanceof Error ? error.message : String(error)
+    });
+    return errorToolResult({
+        kind: "internal_error",
+        details: { message: "Transaction activity call failed" }
+    });
+}
+export function sessionDomainToolError(error) {
+    if (error instanceof WalletUnavailableError)
+        return errorToolResult({ kind: "wallet_unavailable",
+            details: { reason: error.reason, message: error.message } });
+    if (error instanceof WorkflowConflict || error instanceof CardError) {
+        return errorToolResult({ kind: "input_invalid", details: { reason: error.message } });
+    }
+    if (error instanceof WaitRequestAbortedError) {
+        return errorToolResult({
+            kind: "request_aborted",
+            details: { reason: error.reason }
+        });
+    }
+    if (error instanceof SessionStoreError) {
+        return errorToolResult({
+            kind: error.code,
+            details: { code: error.code, ...error.details }
+        });
+    }
+    return undefined;
+}
+export function sessionStoreToolError(error, logger) {
+    const known = sessionDomainToolError(error);
+    if (known)
+        return known;
+    logger.error("session store call failed");
+    return errorToolResult({
+        kind: "internal_error",
+        details: { message: "Session store call failed" }
+    });
+}
+export function localSettingsToolError(error, logger) {
+    if (error instanceof LocalSettingsError) {
+        return errorToolResult({
+            kind: error.kind,
+            details: error.details
+        });
+    }
+    if (error instanceof PreferencesStoreError) {
+        logger.error("local settings store error", {
+            error: error.message,
+            details: error.details
+        });
+        return errorToolResult({
+            kind: "internal_error",
+            details: {
+                reason: error.kind,
+                message: error.message
+            }
+        });
+    }
+    if (error instanceof SuiEndpointError) {
+        logger.error("local settings endpoint value error", {
+            error: error.message,
+            kind: error.kind
+        });
+        return errorToolResult({
+            kind: "internal_error",
+            details: {
+                reason: error.kind,
+                message: error.message
+            }
+        });
+    }
+    logger.error("local settings call failed", {
+        error: error instanceof Error ? error.message : String(error)
+    });
+    return errorToolResult({
+        kind: "internal_error",
+        details: { message: "Local settings call failed" }
+    });
+}