@stelis/say-ur-intent 0.0.0 → 0.0.2

package/README.md

@@ -30,8 +30,8 @@ choices remain with the user, and what claims are unsupported.
 
 Say Ur Intent is one product, but it must be read at three distinct layers. Do not collapse them:
 
-- **Implemented today:** Sui mainnet evidence, local review, and the first signable review adapter for the DeepBook swap route. The account-bound DeepBook swap review builds unsigned transaction material into a local in-process material store, internally binds a Sui transaction digest to that stored material, derives object ownership, quote/policy provenance, human-readable review facts, and review-time simulation evidence from the same private review artifacts, emits a schema-validated wallet review contract with a PTB visualization on a `ready_for_wallet_review` state, and serves a digest-gated byte handoff to the same-machine review page for user-controlled wallet signing with execution receipts recorded on the session. MCP responses do not contain transaction bytes, signing data, or signing readiness.
-- **Deliberately sequenced next (planned order, ships only after verified review):** server-side receipt verification against chain state, additional protocol adapters registered through the descriptor contract (protocol names appear only after a concrete support decision), and richer local analysis views. Each step ships only from independently built or verified transaction material with a human-readable local review.
+- **Implemented today:** Sui mainnet evidence, local review, and signable review adapters for the DeepBook and FlowX swap routes. The account-bound DeepBook swap review builds unsigned transaction material into a local in-process material store, internally binds a Sui transaction digest to that stored material, derives object ownership, quote/policy provenance, human-readable review facts, and review-time simulation evidence from the same private review artifacts, emits a schema-validated wallet review contract with a PTB visualization on a `ready_for_wallet_review` state, and serves a digest-gated byte handoff to the same-machine review page for user-controlled wallet signing with execution receipts recorded on the session. MCP responses do not contain transaction bytes, signing data, or signing readiness.
+- **Deliberately sequenced next (planned order, ships only after verified review):** server-side receipt verification against chain state, further protocol adapters beyond DeepBook and FlowX registered through the descriptor contract (protocol names appear only after a concrete support decision), and richer local analysis views. Each step ships only from independently built or verified transaction material with a human-readable local review.
 - **Never (permanently unsupported at every layer):** no private-key custody, no MCP or AI autonomous execution, no forwarding of opaque external transaction bytes to a wallet, no silent settlement-token or route choice, no fiat cash-out, no P&L, no peg guarantee.
 
 In one sentence: Say Ur Intent is a local-first Sui intent evidence and review layer that progresses from verified evidence to user-controlled wallet signing only after Say Ur Intent independently builds or verifies the transaction material and shows a human-readable local review.
@@ -91,42 +91,6 @@ For manual maintainer and developer utilities, see [docs/UTILITY_INDEX.md](docs/
 
 User-question flows for USD-denominated coverage, balance totals, and shortfall answers live in [docs/AGENT_BEHAVIOR.md](docs/AGENT_BEHAVIOR.md). The response fields for those answers live in [docs/MCP_TOOLS.md](docs/MCP_TOOLS.md).
 
-## How Product Quality Improves: Three Axes
-
-Future quality work moves along three axes. They multiply rather than add,
-so neglecting any one of them caps the value of the other two:
-
-- **Axis 1 - intent, evidence, answer quality.** Understanding what the user
-  asked, routing it to the right tool (prompt surfaces, `userAnswerUse`
-  response guidance), and answering only from verified mainnet evidence -
-  including saying plainly when a question cannot be answered from the
-  returned evidence. This axis is never finished; it is sharpened
-  continuously.
-- **Axis 2 - protocol breadth.** Additional protocol adapters registered
-  through the descriptor contract (protocol names appear only after a
-  concrete support decision). Breadth is a multiplier, not a list: with a
-  second protocol, action routing starts doing real work (the bare action
-  prompt asks the user to choose a venue instead of routing silently), and
-  the execution-trust foundation proves it is not single-protocol.
-- **Axis 3 - execution-trust foundation.** The guarantee that what the user
-  reviewed is exactly what gets signed, held under any wallet and any signing
-  speed: the review-session state machine, the one-transaction-per-session
-  handoff lock, sign-only wallets and slow hardware signers, review-page
-  security headers, and runtime lifecycle stability. Packaging and runtime
-  operability belong here too. This axis is the product differentiator, so
-  it is tracked as its own axis rather than as a side effect of feature work.
-
-```text
-axis 1 (intent-evidence quality) --+
-                                   +--x axis 2 (protocol breadth) = product value
-axis 3 (execution-trust base)   --+
-```
-
-Work that advances several axes at once - for example, a new adapter that
-forces the intent entry point to generalize and re-proves the trust pipeline
-on a second protocol - is preferred over work that advances one axis in
-isolation.
-
 ## What Works Today
 
 The current release can run as a local stdio MCP server and expose mainnet Sui DeFi evidence:
@@ -136,10 +100,11 @@ The current release can run as a local stdio MCP server and expose mainnet Sui D
 - USD-denominated settlement asset groups derived from pinned DeepBook SDK registry metadata;
 - intent evidence with response summaries for natural-language USD-denominated payment coverage, balance-total, and shortfall questions;
 - DeepBook pools, tokens, mid price, orderbook context, raw quotes, display-amount quotes, and account inventory;
+- FlowX CLMM pools and indicative single-hop swap route quotes from the chain-verified pinned registry;
 - user-requested bounded Sui transaction digest lookup, account activity scans, sent-function activity scans with known-wallet-only persistence, and stored normalized activity summaries;
 - read-only external proposal review sessions that display proposed action, asset flow, recipient or target, freshness, missing evidence, user choices, unsupported claims, and non-signable reason;
 - local Say Ur Intent review evidence and review-session status reads;
-- account-bound DeepBook swap review progress through local unsigned transaction material build, internal Sui transaction digest binding, object ownership evidence, quote/policy provenance binding, human-readable review facts, and review-time simulation evidence; when every stage completes the review reaches `ready_for_wallet_review` and the local review page offers a digest-gated byte handoff, user-controlled wallet signing, and execution-receipt recording. The MCP layer and review API never sign, execute, or return transaction bytes.
+- account-bound DeepBook and FlowX swap review progress through local unsigned transaction material build, internal Sui transaction digest binding, object ownership evidence, quote/policy provenance binding, human-readable review facts, and review-time simulation evidence; when every stage completes the review reaches `ready_for_wallet_review` and the local review page offers a digest-gated byte handoff, user-controlled wallet signing, and execution-receipt recording. The MCP layer and review API never sign, execute, or return transaction bytes.
 
 It also includes:
 

package/dist/adapters/adapterLifecycleValidators.js

@@ -0,0 +1,7 @@
+import { DEEPBOOK_SWAP_REVIEW_LIFECYCLE_STAGE_CATALOG_ID, validateDeepbookSwapReviewLifecycle } from "./deepbook/deepbookReviewLifecycle.js";
+import { FLOWX_SWAP_REVIEW_LIFECYCLE_STAGE_CATALOG_ID, validateFlowxSwapReviewLifecycle } from "./flowx/flowxSwapReviewLifecycle.js";
+import { createAdapterLifecycleValidator } from "../core/action/adapterLifecycleValidation.js";
+export const validateSupportedAdapterLifecycle = createAdapterLifecycleValidator({
+    [DEEPBOOK_SWAP_REVIEW_LIFECYCLE_STAGE_CATALOG_ID]: validateDeepbookSwapReviewLifecycle,
+    [FLOWX_SWAP_REVIEW_LIFECYCLE_STAGE_CATALOG_ID]: validateFlowxSwapReviewLifecycle
+});

package/dist/adapters/adapterPromptSurfaces.js

@@ -0,0 +1,71 @@
+import { z } from "zod";
+import { DEEPBOOK_SWAP_ACTION_KIND, DEEPBOOK_SWAP_ADAPTER_ID } from "./deepbook/deepbookSwapIntent.js";
+import { FLOWX_SWAP_ACTION_KIND, FLOWX_SWAP_ADAPTER_ID } from "./flowx/flowxSwapIntent.js";
+/**
+ * One slash-prompt surface contributed by a review adapter.
+ *
+ * Prompt names follow action-first naming: `<action>-<protocolSlug>`
+ * (for example `swap-deep`). Users reach for the verb before the venue, so
+ * action-first keeps autocomplete grouped by what the user wants to do. When
+ * an action has exactly one registered protocol, the bare action name (for
+ * example `swap`) is also registered as a shorthand.
+ *
+ * The surface carries only protocol-specific copy. Boundary language (no
+ * signing data, no transaction bytes, local-review-only signing) is owned by
+ * the platform and appended at registration time; adapters cannot weaken it.
+ */
+export const adapterPromptSurfaceSchema = z
+    .object({
+    adapterId: z.string().min(1),
+    action: z
+        .string()
+        .regex(/^[a-z][a-z0-9]*$/, "action must be a lowercase slug, e.g. swap"),
+    protocolSlug: z
+        .string()
+        .regex(/^[a-z][a-z0-9]*$/, "protocolSlug must be a lowercase slug, e.g. deep"),
+    title: z.string().min(1),
+    description: z.string().min(1),
+    intentArgDescription: z.string().min(1),
+    exampleIntents: z.array(z.string().min(1)).min(1),
+    toolName: z.string().min(1)
+})
+    .strict();
+export function promptNameFor(surface) {
+    return `${surface.action}-${surface.protocolSlug}`;
+}
+/**
+ * Bare action prompts (`swap`) are always registered. With a single
+ * registered protocol they go straight to that protocol; with several they
+ * carry an optional `protocol` argument (completion suggests the slugs) and
+ * instruct the model to ask the user which protocol to use - never to pick a
+ * venue silently.
+ */
+export function actionGroups(surfaces) {
+    const byAction = new Map();
+    for (const surface of surfaces) {
+        byAction.set(surface.action, [...(byAction.get(surface.action) ?? []), surface]);
+    }
+    return byAction;
+}
+export const ADAPTER_PROMPT_SURFACES = [
+    {
+        adapterId: DEEPBOOK_SWAP_ADAPTER_ID,
+        action: DEEPBOOK_SWAP_ACTION_KIND,
+        protocolSlug: "deep",
+        title: "DeepBook Swap Review",
+        description: 'Prepare a reviewable DeepBook mainnet swap from a one-line intent, e.g. "10 sui to usdc".',
+        intentArgDescription: 'Swap intent in one line, any language, e.g. "10 sui to usdc" or "10 수이 usdc로 환전"',
+        exampleIntents: ["10 sui to usdc", "10 수이 usdc로 환전"],
+        toolName: "action.prepare_sui_action_review"
+    },
+    {
+        adapterId: FLOWX_SWAP_ADAPTER_ID,
+        action: FLOWX_SWAP_ACTION_KIND,
+        protocolSlug: "flowx",
+        title: "FlowX Swap Review",
+        description: 'Prepare a reviewable FlowX CLMM mainnet swap from a one-line intent, e.g. "10 sui to usdc".',
+        intentArgDescription: 'Swap intent in one line, any language, e.g. "10 sui to usdc" or "10 수이 usdc로 환전"',
+        exampleIntents: ["10 sui to usdc", "10 수이 usdc로 환전"],
+        toolName: "action.prepare_sui_action_review"
+    }
+];

package/dist/adapters/deepbook/deepbookHumanReviewProducer.js

@@ -0,0 +1,175 @@
+import { createSwapHumanReadableReviewEvidence } from "../../core/action/swapHumanReadableReviewProjection.js";
+import { failReviewCheck, passReviewCheck } from "../../core/review/reviewComputationResult.js";
+export function createDeepbookSwapHumanReadableReviewProducer() {
+    return (input) => {
+        try {
+            assertDeepbookHumanReviewSources(input);
+            const review = buildDeepbookHumanReadableReview(input);
+            const evidence = createSwapHumanReadableReviewEvidence({
+                transactionMaterial: input.transactionMaterial,
+                transactionMaterialDigest: input.transactionMaterialDigest,
+                swapQuotePolicy: input.swapQuotePolicy,
+                transactionObjectOwnership: input.transactionObjectOwnership,
+                adapterId: input.plan.adapterId,
+                protocol: input.plan.protocol,
+                actionKind: input.plan.actionKind,
+                review,
+                derivedAt: input.now
+            });
+            return {
+                status: "completed",
+                evidence,
+                checks: [
+                    passReviewCheck("deepbook_human_readable_review_evidence", "Human-readable review", "Prepared a human-readable account-bound swap review from material-bound quote policy and object ownership evidence. This is not wallet handoff, signing data, signing readiness, or execution readiness.", "adapter")
+                ]
+            };
+        }
+        catch (error) {
+            return {
+                status: "blocked",
+                blockedReason: classifyHumanReviewFailure(error),
+                checks: [
+                    failReviewCheck("deepbook_human_readable_review_failed", "Human-readable review", error instanceof Error ? error.message : "DeepBook human-readable review evidence could not be produced.", "adapter")
+                ]
+            };
+        }
+    };
+}
+function buildDeepbookHumanReadableReview(input) {
+    const sourceAmount = amountFromQuotePolicy("input", input.swapQuotePolicy.sourceAmount, {
+        displayAmount: input.requestedIntent.from.amountDisplay,
+        displayAmountSource: "user_display_intent_not_signing_input"
+    });
+    const expectedOutput = amountFromQuotePolicy("expected_output", input.swapQuotePolicy.expectedOutput);
+    const minimumOutput = amountFromQuotePolicy("minimum_output", input.swapQuotePolicy.minimumOutput);
+    const protocolFee = amountFromQuotePolicy("fee", input.swapQuotePolicy.protocolFee);
+    return {
+        kind: "swap_human_readable_review",
+        proposedAction: {
+            title: input.plan.title,
+            summary: input.plan.summary,
+            actionKind: input.plan.actionKind,
+            adapterId: input.plan.adapterId,
+            protocol: input.plan.protocol,
+            network: "sui:mainnet"
+        },
+        assetFlow: {
+            outgoing: [sourceAmount],
+            expectedIncoming: [expectedOutput],
+            minimumIncoming: [minimumOutput],
+            fees: [protocolFee]
+        },
+        recipients: [
+            { role: "connected_account", address: input.account },
+            { role: "output_recipient", address: input.account }
+        ],
+        targets: [
+            {
+                kind: "swap_output_asset",
+                symbol: input.swapQuotePolicy.expectedOutput.asset.symbol,
+                coinType: input.swapQuotePolicy.expectedOutput.asset.coinType,
+                protocol: input.plan.protocol,
+                poolKey: input.swapQuotePolicy.quoteSource.poolKey,
+                direction: input.swapQuotePolicy.quoteSource.direction
+            }
+        ],
+        evidenceUsed: [
+            {
+                id: "deepbook_quote_policy",
+                label: "Quote policy",
+                source: "quote",
+                summary: "Quote policy evidence supplies the input, expected output, minimum output, protocol fee, and slippage policy shown in asset flow; it is not route choice or signing readiness."
+            },
+            {
+                id: "transaction_material_digest",
+                label: "Transaction material digest",
+                source: "digest_commitment",
+                summary: "The review is bound internally to the stored local unsigned transaction material digest; the digest and transaction bytes are not public review output."
+            },
+            {
+                id: "transaction_object_ownership",
+                label: "Object ownership",
+                source: "wallet",
+                summary: "Object ownership evidence is derived from stored transaction data and Sui mainnet object reads."
+            }
+        ],
+        missingEvidence: [
+            {
+                id: "review_time_simulation",
+                label: "Review-time simulation",
+                reason: "The review has not simulated the stored transaction material with required effects, balance changes, object types, and transaction fields."
+            }
+        ],
+        requiredUserChoices: [
+            {
+                id: "wallet_authorization_later",
+                label: "Wallet authorization",
+                reason: "The wallet signature request happens on this review page after the digest-gated handoff; nothing is signed without your approval in the wallet."
+            }
+        ],
+        unsupportedClaims: [
+            {
+                id: "no_signing_readiness",
+                label: "No signing readiness",
+                reason: "Human-readable review evidence does not prove the action is ready to sign."
+            },
+            {
+                id: "no_execution_readiness",
+                label: "No execution readiness",
+                reason: "Review-time simulation, wallet handoff, signing, and execution receipt evidence are not complete."
+            },
+            {
+                id: "no_route_recommendation",
+                label: "No route recommendation",
+                reason: "The account-bound swap review uses an explicit direct pool path and does not rank venues or recommend routes."
+            }
+        ],
+        freshness: {
+            status: "current",
+            evaluatedAt: input.now.toISOString(),
+            expiresAt: input.transactionMaterial.expiresAt,
+            reason: "Human-readable review evidence expires with the stored local transaction material and quote policy."
+        },
+        blockingChecks: [
+            failReviewCheck("deepbook_review_time_simulation_missing", "Review-time simulation", "Review-time simulation evidence is still required before any wallet handoff, signing, or execution.", "simulation")
+        ]
+    };
+}
+function assertDeepbookHumanReviewSources(input) {
+    if (input.swapQuotePolicy.adapterId !== input.plan.adapterId ||
+        input.swapQuotePolicy.protocol !== input.plan.protocol ||
+        input.swapQuotePolicy.actionKind !== input.plan.actionKind) {
+        throw new Error("human-readable review quote policy identity must match the action plan");
+    }
+    if (input.swapQuotePolicy.quoteSource.poolKey !== input.poolResolution.poolKey) {
+        throw new Error("human-readable review pool target must match swap quote policy poolKey");
+    }
+    if (input.swapQuotePolicy.quoteSource.direction !== input.quotePolicy.direction) {
+        throw new Error("human-readable review target direction must match swap quote policy direction");
+    }
+}
+function classifyHumanReviewFailure(error) {
+    const message = error instanceof Error ? error.message : "";
+    if (/object ownership/i.test(message)) {
+        return "object_resolution_failed";
+    }
+    if (/asset|target|pool|direction|protocol|adapter/i.test(message)) {
+        return "asset_mismatch";
+    }
+    if (/amount|quote|slippage|min/i.test(message)) {
+        return "amount_mismatch";
+    }
+    return "unsupported_action";
+}
+function amountFromQuotePolicy(role, amount, display) {
+    return {
+        role,
+        symbol: amount.asset.symbol,
+        coinType: amount.asset.coinType,
+        decimals: amount.asset.decimals,
+        rawAmount: amount.raw,
+        rawAmountSource: "quote_policy_evidence",
+        ...(display?.displayAmount ? { displayAmount: display.displayAmount } : {}),
+        ...(display?.displayAmountSource ? { displayAmountSource: display.displayAmountSource } : {})
+    };
+}

package/dist/adapters/deepbook/deepbookQuotePolicy.js

@@ -0,0 +1,112 @@
+import { parseDeepbookRawU64 } from "../../core/read/deepbookReadHelpers.js";
+export const DEEPBOOK_REVIEW_QUOTE_STALE_AFTER_MS = 30_000;
+// Same-machine pipelines capture `now` before the network quote fetch, so the
+// fetch timestamp can land a few hundred milliseconds "in the future". Treat
+// skew within this tolerance as a fresh quote (age 0) and record the skew;
+// anything beyond it is a real clock-integrity violation and refuses.
+export const DEEPBOOK_QUOTE_FUTURE_SKEW_TOLERANCE_MS = 5_000;
+export const DEEPBOOK_MAX_SLIPPAGE_BPS = 1000;
+export const DEEPBOOK_MIN_SLIPPAGE_BPS = 1;
+const BPS_DENOMINATOR = 10000n;
+export function deriveDeepbookSwapQuotePolicy(input) {
+    assertSlippageBps(input.maxSlippageBps);
+    const staleAfterMs = input.staleAfterMs ?? DEEPBOOK_REVIEW_QUOTE_STALE_AFTER_MS;
+    if (!Number.isInteger(staleAfterMs) || staleAfterMs < 1) {
+        throw new Error("staleAfterMs must be a positive integer");
+    }
+    const fetchedAtMs = parseIsoUtcTimestampMs(input.fetchedAt, "fetchedAt");
+    const nowMs = parseValidDateMs(input.now, "now");
+    const rawQuoteAgeMs = nowMs - fetchedAtMs;
+    const direction = directionFromRawQuote(input.rawQuote);
+    if (rawQuoteAgeMs < -DEEPBOOK_QUOTE_FUTURE_SKEW_TOLERANCE_MS) {
+        return {
+            status: "refresh_required",
+            refreshReason: "quote_stale",
+            reason: "quote_timestamp_in_future",
+            direction,
+            fetchedAt: input.fetchedAt,
+            quoteAgeMs: 0,
+            staleAfterMs,
+            clockSkewMs: -rawQuoteAgeMs
+        };
+    }
+    const clockSkewMs = rawQuoteAgeMs < 0 ? -rawQuoteAgeMs : undefined;
+    const quoteAgeMs = rawQuoteAgeMs < 0 ? 0 : rawQuoteAgeMs;
+    if (quoteAgeMs > staleAfterMs) {
+        return {
+            status: "refresh_required",
+            refreshReason: "quote_stale",
+            reason: "quote_stale",
+            direction,
+            fetchedAt: input.fetchedAt,
+            quoteAgeMs,
+            staleAfterMs
+        };
+    }
+    const expectedOut = parseUnsignedRaw(input.rawQuote.directionalOutput.raw, "directionalOutput.raw");
+    if (expectedOut === 0n) {
+        return unavailableQuote(input, direction, quoteAgeMs, staleAfterMs, "zero_expected_output");
+    }
+    const minOut = (expectedOut * (BPS_DENOMINATOR - BigInt(input.maxSlippageBps))) / BPS_DENOMINATOR;
+    if (minOut === 0n) {
+        return unavailableQuote(input, direction, quoteAgeMs, staleAfterMs, "zero_min_out");
+    }
+    return {
+        status: "ok",
+        direction,
+        quoteFresh: true,
+        fetchedAt: input.fetchedAt,
+        quoteAgeMs,
+        staleAfterMs,
+        ...(clockSkewMs !== undefined ? { clockSkewMs } : {}),
+        feeMode: input.feeMode ?? "deep",
+        maxSlippageBps: input.maxSlippageBps,
+        sourceAmountRaw: parsePositiveRaw(input.rawQuote.inputAmount.raw, "inputAmount.raw").toString(),
+        expectedOutRaw: expectedOut.toString(),
+        minOutRaw: minOut.toString(),
+        deepAmountRaw: parseUnsignedRaw(input.rawQuote.deepRequired.raw, "deepRequired.raw").toString()
+    };
+}
+function assertSlippageBps(value) {
+    if (!Number.isInteger(value) || value < DEEPBOOK_MIN_SLIPPAGE_BPS || value > DEEPBOOK_MAX_SLIPPAGE_BPS) {
+        throw new Error(`maxSlippageBps must be an integer from ${DEEPBOOK_MIN_SLIPPAGE_BPS} to ${DEEPBOOK_MAX_SLIPPAGE_BPS}`);
+    }
+}
+function parseIsoUtcTimestampMs(value, field) {
+    const parsed = new Date(value);
+    const timestampMs = parsed.getTime();
+    if (!Number.isFinite(timestampMs) || parsed.toISOString() !== value) {
+        throw new Error(`${field} must be an ISO 8601 UTC timestamp`);
+    }
+    return timestampMs;
+}
+function parseValidDateMs(value, field) {
+    if (!(value instanceof Date)) {
+        throw new Error(`${field} must be a valid Date`);
+    }
+    const timestampMs = value.getTime();
+    if (!Number.isFinite(timestampMs)) {
+        throw new Error(`${field} must be a valid Date`);
+    }
+    return timestampMs;
+}
+function directionFromRawQuote(rawQuote) {
+    return rawQuote.sourceMoveFunction.startsWith("pool::get_quote_quantity_out") ? "base_to_quote" : "quote_to_base";
+}
+function unavailableQuote(input, direction, quoteAgeMs, staleAfterMs, reason) {
+    return {
+        status: "refresh_required",
+        refreshReason: "quote_unavailable",
+        reason,
+        direction,
+        fetchedAt: input.fetchedAt,
+        quoteAgeMs,
+        staleAfterMs
+    };
+}
+function parsePositiveRaw(value, field) {
+    return parseDeepbookRawU64(value, field, { positive: true });
+}
+function parseUnsignedRaw(value, field) {
+    return parseDeepbookRawU64(value, field);
+}