@stelis/say-ur-intent 0.0.0 → 0.0.2

package/dist/mcp/responseGuidance.js

@@ -0,0 +1,381 @@
+import { EXTERNAL_PROPOSAL_SETTLEMENT_TOKEN_SELECTION_UNSUPPORTED_CLAIM_ID } from "../core/proposal/types.js";
+import { TOOL_NAMES } from "./toolNames.js";
+export function interactionStatusUserAnswerUse() {
+    return {
+        canAnswer: [
+            "current_active_account_read_context",
+            "pending_local_wallet_identity_interactions",
+            "pending_local_review_interactions"
+        ],
+        cannotAnswer: [
+            "wallet_login_or_authentication",
+            "wallet_custody_or_authorization",
+            "transaction_execution_result",
+            "transaction_building",
+            "signing_data_or_readiness",
+            "complete_wallet_history",
+            "profit_or_pnl"
+        ],
+        answerFields: ["activeAccount", "pendingWalletIdentitySessions", "pendingReviewSessions"],
+        diagnosticOnlyFields: [
+            "pendingWalletIdentitySessions.truncated",
+            "pendingReviewSessions.truncated"
+        ],
+        followUp: {
+            tool: TOOL_NAMES.sessionGetReviewStatus,
+            inputFields: ["pendingReviewSessions.items[].reviewSessionId"],
+            answerFields: ["pollingStatus", "statusCategory", "reviewState"],
+            reason: "Use for the current status of a specific pending review; interaction status is a local overview."
+        }
+    };
+}
+export function walletIdentityUserAnswerUse(fields = {}) {
+    const hasAccount = fields.hasAccount ?? false;
+    const hasFailure = fields.hasFailure ?? false;
+    const hasWalletInfo = fields.hasWalletInfo ?? false;
+    const hasWaitOutcome = fields.hasWaitOutcome ?? false;
+    const hasOpenFields = fields.hasOpenFields ?? false;
+    const followUp = hasOpenFields || (!hasAccount && !hasFailure)
+        ? {
+            tool: TOOL_NAMES.sessionWaitWalletIdentity,
+            inputFields: ["walletSessionId"],
+            answerFields: ["status", "account", "chain", "waitOutcome"],
+            reason: "Use after giving the walletUrl to check whether the local wallet identity capture connected, timed out, failed, or was rejected."
+        }
+        : hasAccount
+            ? {
+                tool: TOOL_NAMES.accountGetActiveAccount,
+                answerFields: ["status", "account", "boundary"],
+                reason: "Use after a connected wallet identity result before telling the user which active account read context is stored."
+            }
+            : undefined;
+    return {
+        canAnswer: [
+            "local_wallet_identity_capture_status",
+            ...(hasAccount ? ["active_account_candidate_captured_for_read_context"] : []),
+            ...(hasFailure ? ["wallet_identity_failure_reason"] : []),
+            ...(hasWaitOutcome ? ["whether_the_bounded_wait_finished_or_timed_out"] : [])
+        ],
+        cannotAnswer: [
+            "wallet_login_or_authentication",
+            "wallet_custody_or_authorization",
+            "transaction_authorization",
+            "transaction_building",
+            "signing_data_or_readiness",
+            "wallet_balance_or_activity",
+            "complete_wallet_history",
+            "profit_or_pnl"
+        ],
+        answerFields: [
+            ...(hasWaitOutcome ? ["waitOutcome"] : []),
+            "walletSessionId",
+            ...(hasOpenFields ? ["walletUrl", "openTarget", "accessScope"] : []),
+            "status",
+            ...(hasAccount ? ["account", "chain"] : []),
+            ...(hasFailure ? ["failureReason"] : []),
+            "expiresAt",
+            "lastActivityAt",
+            "pollingHint"
+        ],
+        diagnosticOnlyFields: [
+            ...(hasWalletInfo ? ["walletName", "walletId"] : []),
+            ...(hasFailure ? ["failureDetail"] : [])
+        ],
+        ...(followUp === undefined ? {} : { followUp })
+    };
+}
+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",
+            ...(hasExecutionResult ? ["recorded_review_execution_result"] : [])
+        ],
+        cannotAnswer: [
+            ...(hasExecutionResult ? [] : ["recorded_review_execution_result_without_executionResult_field"]),
+            "transaction_execution_guarantee",
+            "absolute_safety_verdict",
+            "route_quality",
+            "wallet_custody_or_authorization",
+            "transaction_building",
+            "signing_data_or_readiness",
+            "complete_wallet_history",
+            "profit_or_pnl"
+        ],
+        answerFields: [
+            ...(hasWaitOutcome ? ["waitOutcome"] : []),
+            "reviewSessionId",
+            "status",
+            "statusCategory",
+            "lastActivityAt",
+            "pollingHint",
+            ...(hasExecutionResult ? ["executionResult"] : [])
+        ],
+        conclusionRuleFields: [
+            "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; execution polling status alone is not a safety or signing verdict."
+        }
+    };
+}
+export function reviewStatusUserAnswerUse(hasReviewState, hasAdapterLifecycle = false, hasHumanReadableReview = false, hasSimulation = false) {
+    return {
+        canAnswer: [
+            "current_local_review_session_status",
+            "current_review_checks_when_reviewState_is_present",
+            ...(hasAdapterLifecycle ? ["current_deepbook_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"
+        ],
+        cannotAnswer: [
+            "transaction_execution_guarantee",
+            "absolute_safety_verdict",
+            "route_quality",
+            "wallet_custody_or_authorization",
+            "transaction_building",
+            "transaction_bytes_or_digest_values",
+            "signing_data_or_readiness",
+            "complete_wallet_history",
+            "profit_or_pnl"
+        ],
+        answerFields: [
+            "reviewSessionId",
+            "internalStatus",
+            "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[].currentStatus", "activities[].updatedAt"],
+        diagnosticOnlyFields: ["dataScope", "accountSource", "lowSampleWarning", "lowSampleThreshold", "truncated"],
+        followUp: {
+            tool: TOOL_NAMES.readGetReviewSessionDetail,
+            inputFields: ["activities[].reviewSessionId"],
+            answerFields: ["session", "planJson", "intentJson", "stateSnapshots", "transitions", "execution"],
+            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: [
+            "review_session_url_for_local_review_page",
+            "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",
+            "reviewUrl",
+            "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: [
+            "review_session_url_for_local_review_page",
+            "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",
+            "reviewUrl",
+            "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 local page; the prepare response does not make the proposal signable."
+        }
+    };
+}
+export function reviewSessionDetailUserAnswerUse(hasExecution = false) {
+    return {
+        canAnswer: [
+            "stored_local_review_session_plan_and_lifecycle_detail",
+            "stored_review_state_snapshots",
+            ...(hasExecution ? ["stored_review_execution_result"] : [])
+        ],
+        cannotAnswer: [
+            "sui_wallet_transaction_history",
+            "complete_wallet_history",
+            ...(hasExecution ? [] : ["stored_review_execution_result_without_execution_field"]),
+            "transaction_execution_guarantee",
+            "absolute_safety_verdict",
+            "route_quality",
+            "wallet_custody_or_authorization",
+            "transaction_building",
+            "signing_data_or_readiness",
+            "profit_or_pnl"
+        ],
+        answerFields: [
+            "session",
+            "planJson",
+            "intentJson",
+            "stateSnapshots",
+            "transitions",
+            ...(hasExecution ? ["execution", "execution.resultJson"] : [])
+        ],
+        diagnosticOnlyFields: ["dataScope", "accountSource", "lowSampleWarning", "lowSampleThreshold", "truncated"],
+        followUp: {
+            tool: TOOL_NAMES.sessionGetReviewStatus,
+            inputFields: ["session.reviewSessionId"],
+            answerFields: ["pollingStatus", "reviewState"],
+            reason: "Use for the current in-memory review status; stored detail is local review history."
+        }
+    };
+}

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,8 @@
+import { z } from "zod";
+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,30 @@
+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);
+    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,123 @@
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+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 = "say-ur-intent";
+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 = [
+    "Say Ur Intent is a mainnet-only Sui DeFi intent evidence toolkit. The MCP layer is a session gateway for local review, wallet identity/settings sessions; it does not execute transactions, request wallet signatures, or return transaction bytes. DeepBook review may build internal unsigned material, bind a Sui digest, and derive object ownership, quote/policy, human review, and review-time simulation evidence; not wallet handoff, signing data/readiness, or execution readiness. No custody, autonomous trading, fiat cash-out, P&L, peg proof, payment readiness, route choice, best-price advice, or silent settlement-token selection.",
+    "External proposals are untrusted facts; plans[].reviewModel is review context, not transaction material, route/settlement choice, signing/readiness, or execution readiness.",
+    "Future 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. If answerSourceStatus.canUseThisResponseForUserAnswer and responseSummary.doNotCallQuoteToolsForThisQuestion are true, answer from responseSummary; 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 answerSourceStatus cannot be used, say the current MCP server build cannot support the answer.",
+    "active account context is read context only; not login, transaction/signing auth, custody, or permission.",
+    "Unsupported: other chains, autonomous trading, alerts, investment advice, arbitrary Move/package calls, P&L/tax/cost basis.",
+    "Read sayurintent://docs/agent-behavior."
+].join("\n");
+export const IMPLEMENTED_TOOLS = [
+    TOOL_NAMES.readGetServerStatus,
+    TOOL_NAMES.readListSupportedProtocols,
+    TOOL_NAMES.readListDeepbookPools,
+    TOOL_NAMES.readListDeepbookTokens,
+    TOOL_NAMES.readInspectDeepbookOrderbook,
+    TOOL_NAMES.readGetDeepbookMidPrice,
+    TOOL_NAMES.readQuoteDeepbookAction,
+    TOOL_NAMES.readQuoteDeepbookDisplayAmount,
+    TOOL_NAMES.readListFlowxPools,
+    TOOL_NAMES.readQuoteFlowxSwap,
+    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.settingsCreateLocalSettingsSession,
+    TOOL_NAMES.settingsGetLocalSettings,
+    TOOL_NAMES.actionPrepareSuiActionReview,
+    TOOL_NAMES.actionPrepareExternalProposalReview,
+    TOOL_NAMES.accountGetActiveAccount,
+    TOOL_NAMES.accountClearActiveAccount,
+    TOOL_NAMES.sessionCreateWalletIdentity,
+    TOOL_NAMES.sessionGetWalletIdentity,
+    TOOL_NAMES.sessionWaitWalletIdentity,
+    TOOL_NAMES.sessionGetInteractionStatus,
+    TOOL_NAMES.sessionGetReviewStatus,
+    TOOL_NAMES.sessionGetExecutionResult,
+    TOOL_NAMES.sessionWaitExecutionResult
+];
+export const FAIL_CLOSED_TOOLS = [];
+export function answerSourceStatus(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,
+        canUseThisResponseForUserAnswer: missingRequiredTools.length === 0,
+        cannotUseReason: missingRequiredTools.length === 0 ? null : "required_tool_missing_from_current_server_build"
+    };
+}
+export const SERVER_LIMITATIONS = [
+    "Active-account reads require active account context from wallet identity. 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 Say Ur Intent 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.",
+    "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 answerSourceStatus 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 creates local review sessions. DeepBook account-bound review may report adapterLifecycle.completedStages and missingStages as pre-signing review evidence progress through local transaction-material build, internal digest binding, object ownership evidence, quote/policy provenance, human-readable review evidence, and review-time simulation evidence; these fields do not expose transaction bytes, wallet handoff, signing readiness, or execution readiness. External proposal ingestion stores untrusted structured proposal facts for local review only, rejects forbidden executable or signing fields plus recognized sensitive key material, and never becomes signing authority. When every review evidence stage completes, the review layer emits a schema-validated wallet review contract with a PTB visualization on a ready_for_wallet_review state; the local review page can then request a digest-gated byte handoff and offer user-controlled wallet signing, recording execution receipts on the session. MCP responses never contain signing data, a wallet signature request, or signing readiness; this is not execution by the MCP layer.",
+    "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 pinned-SDK snapshots at fetchedAt; treat them as stale if the user delays.",
+    "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,105 @@
+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 sessionStoreToolError(error, logger) {
+    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 }
+        });
+    }
+    logger.error("session store call failed", {
+        error: error instanceof Error ? error.message : String(error)
+    });
+    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" }
+    });
+}