@t2000/engine 1.24.14 → 1.25.1

package/dist/index.d.ts

@@ -1,9 +1,9 @@
+import * as _t2000_sdk from '@t2000/sdk';
+import { SerializedCetusRoute, PendingReward as PendingReward$1, SwapQuoteResult, T2000 } from '@t2000/sdk';
 import { z } from 'zod';
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
 import { Tool as Tool$1 } from '@modelcontextprotocol/sdk/types.js';
-import * as _t2000_sdk from '@t2000/sdk';
-import { PendingReward as PendingReward$1, SwapQuoteResult, T2000 } from '@t2000/sdk';
 
 type ProactiveType = 'idle_balance' | 'hf_warning' | 'apy_drift' | 'goal_progress';
 interface ProactiveMarker {
@@ -1223,6 +1223,12 @@ interface PendingActionStep {
      *   `inputCoinFromStep < currentStepIndex` (forward-only references).
      */
     inputCoinFromStep?: number;
+    /**
+     * [SPEC 20.2 / D-1 (a)] Per-step Cetus route — populated for `swap_execute`
+     * steps when a same-turn `swap_quote` matched the step's input. See
+     * `PendingAction.cetusRoute` for the full contract.
+     */
+    cetusRoute?: _t2000_sdk.SerializedCetusRoute;
 }
 /**
  * Serializable description of a write tool that needs user approval.
@@ -1283,6 +1289,25 @@ interface PendingAction {
      * route loops `stepResults` and updates each per-step row.
      */
     attemptId: string;
+    /**
+     * [SPEC 20.2 / D-1 (a)] Cetus route captured at `swap_quote` time and
+     * threaded through to the prepare-route to skip the ~400-500ms
+     * `findSwapRoute()` re-discovery call. Only populated when the same-turn
+     * read pipeline included a successful `swap_quote` whose input matches
+     * this `pending_action`'s amount/from/to (the engine matches at emission
+     * time). Audric's prepare-route validates freshness + coin-type match
+     * before using as fast-path; falls back to fresh discovery on any
+     * mismatch (D-2 structural verification + D-3 TTL re-validation).
+     *
+     * Also rendered into the post-write resume system prompt as a
+     * `<canonical_route>` block (D-4) so LLM narration grounds against the
+     * canonical route — closes S19-F2 (LLM cites stale swap routes).
+     *
+     * **Bundles:** when present on a `steps[]` entry, the per-step
+     * `cetusRoute` takes precedence over the top-level field (which mirrors
+     * `steps[0].cetusRoute` for backward compat with pre-bundle hosts).
+     */
+    cetusRoute?: _t2000_sdk.SerializedCetusRoute;
     /**
      * [SPEC 7 v0.4 Layer 2] When set, this `pending_action` represents a
      * multi-write Payment Intent. Single-step bundles are NOT created — the
@@ -2078,6 +2103,51 @@ declare function bundleShortestTtl(toolUseIds: string[], toolNamesById: Record<s
 /** The set of read tools whose results re-fire on REGENERATE. */
 declare const REGENERATABLE_READ_TOOLS: ReadonlySet<string>;
 
+/**
+ * [SPEC 20.2 / D-1 (a)] Match a `swap_execute` pending write against the
+ * same-turn `swap_quote` reads to thread the captured Cetus route into
+ * the emitted `pending_action.cetusRoute`.
+ *
+ * The match key is `(from, to, amount, byAmountIn)` — the four fields that
+ * deterministically identify a Cetus route. `slippage` is NOT part of the
+ * key because slippage is a tx-build-time parameter, not a route-discovery
+ * parameter (Cetus's `findSwapRoute` does not take slippage).
+ *
+ * No match → return undefined → caller emits the pending_action without
+ * `cetusRoute`, audric prepare-route falls back to fresh `findSwapRoute()`
+ * (D-5 dual-path). This is the legacy path; correct behavior, just slower.
+ */
+
+interface SwapQuoteInput {
+    from: string;
+    to: string;
+    amount: number;
+    byAmountIn?: boolean;
+}
+interface SwapQuoteResultLike {
+    serializedRoute?: SerializedCetusRoute;
+}
+/**
+ * Per-turn read-result entry for swap_quote matching. The engine collects
+ * these alongside the existing `turnReadToolResults` metadata array;
+ * `data` + `input` are populated only for successful `swap_quote` results.
+ */
+interface SwapQuoteReadEntry {
+    toolUseId: string;
+    input: SwapQuoteInput;
+    result: SwapQuoteResultLike;
+    timestamp: number;
+}
+/**
+ * Return the most recent matching `swap_quote`'s serialized route, or
+ * undefined if no same-turn quote matches the swap_execute's input.
+ *
+ * "Most recent" matters when the LLM calls `swap_quote` multiple times in
+ * the same turn (e.g. exploring different amounts) — the most recent
+ * matching quote is the one the user just saw on the quote card.
+ */
+declare function findMatchingCetusRoute(swapExecuteInput: unknown, swapQuoteReads: SwapQuoteReadEntry[]): SerializedCetusRoute | undefined;
+
 /**
  * [Phase 0 → Phase 3a / SPEC 13] Maximum number of writes per atomic bundle.
  *
@@ -2230,6 +2300,14 @@ interface BundleCompositionInput {
         toolName: string;
         timestamp: number;
     }>;
+    /**
+     * [SPEC 20.2 / D-1 (a)] Same-turn `swap_quote` results paired with their
+     * input + serialized Cetus route. Used to populate `step.cetusRoute` for
+     * any `swap_execute` step whose input matches a quote. Empty / undefined
+     * is fine — the bundle still composes correctly without per-step routes
+     * (audric's prepare-route falls back to fresh `findSwapRoute()`).
+     */
+    swapQuoteReads?: SwapQuoteReadEntry[];
     /** Full assistant message blocks for the deferred turn (engine.ts uses this). */
     assistantContent: ContentBlock[];
     /** Already-resolved tool_result blocks (early-dispatched reads + auto writes). */
@@ -4347,4 +4425,4 @@ declare function getTelemetrySink(): TelemetrySink;
 /** Restore the default noop sink. Used by test teardowns. */
 declare function resetTelemetrySink(): void;
 
-export { type AddressPortfolio, AnthropicProvider, type AnthropicProviderConfig, type AudricHistoryRecord, type AudricPortfolioResult, type AwaitOrFetchOpts, type BalancePrices, type BalanceResult, BalanceTracker, type BuildToolOptions, type BundleCompositionInput, CANVAS_TEMPLATES, type CanvasTemplate, type ChatParams, type CompactOptions, type ContentBlock, ContextBudget, type ContextBudgetConfig, type ConversationState, type ConversationStateStore, type CostSnapshot, CostTracker, type CostTrackerConfig, DEFAULT_GUARD_CONFIG, DEFAULT_LEASE_SEC, DEFAULT_PERMISSION_CONFIG, DEFAULT_POLL_BUDGET_MS, DEFAULT_POLL_INTERVAL_MS, DEFAULT_SYSTEM_PROMPT, DEFAULT_TOOL_TTL_MS, type DefiCacheEntry, type DefiCacheStore, type DefiProtocol, type DefiSummary, EFFORT_THINKING_BUDGET_CAPS, EarlyToolDispatcher, type EngineConfig, type EngineEvent, type EvalSummaryParseResult, type EvaluationItem, type EvaluationStatus, type FetchLock, type FormField, type FormFieldKind, type FormSchema, type GuardCheckResult, type GuardConfig, type GuardEvent, type GuardInjection, type GuardResult, type GuardRunnerState, type GuardTier, type GuardVerdict, type HarnessShape, type HealthFactorResult, InMemoryDefiCacheStore, InMemoryFetchLock, InMemoryNaviCacheStore, InMemoryWalletCacheStore, InvalidAddressError, type LLMProvider, MAX_BUNDLE_OPS, type McpCallResult, McpClientManager, McpResponseCache, type McpServerConfig, type McpServerConnection, type McpToolAdapterConfig, type McpToolDescriptor, MemorySessionStore, type Message, NAVI_ADDR_TTL_SEC, NAVI_MCP_CONFIG, NAVI_MCP_URL, NAVI_RATES_TTL_SEC, NAVI_SERVER_NAME, type NaviCacheEntry, type NaviCacheStore, type NaviRawCoin, type NaviRawHealthFactor, type NaviRawPool, type NaviRawPosition, type NaviRawPositionsResponse, type NaviRawProtocolStats, type NaviRawRewardsResponse, type NaviReadOptions, NaviTools, type NormalizedAddress, type OutputConfig, PERMISSION_PRESETS, type PendingAction, type PendingActionModifiableField, type PendingActionStep, type PendingInput, type PendingInputState, type PendingReward, type PendingToolCall, type PermissionLevel, type PermissionOperation, type PermissionResponse, type PermissionRule, type PortfolioCoin, type PositionEntry, type PostWritePollOptions, type PostWritePollOutcome, type PostWritePollResult, type PreflightResult, type ProactiveMarker, type ProactiveType, type ProtocolStats, type ProviderEvent, QueryEngine, READ_TOOLS, REGENERATABLE_READ_TOOLS, type RatesResult, type Recipe, type RecipePrerequisite, RecipeRegistry, type RecipeStep, type RecipeStepOnError, type RegenerateFailure, type RegenerateResult, type RegenerateSuccess, type RegenerateTimelineEvent, RetryTracker, type SSEEvent, SUINS_NAME_REGEX, SUI_ADDRESS_REGEX, SUI_ADDRESS_STRICT_REGEX, type SavingsResult, type ServerPositionData, type SessionData, type SessionStore, type StateType, type StopReason, type SuiCoinBalance, SuinsNotRegisteredError, SuinsRpcError, type SystemBlock, type SystemPrompt, TOOL_FLAGS, TOOL_MODIFIABLE_FIELDS, TOOL_TTL_MS, type TelemetrySink, type TelemetryTags, type ThinkingConfig, type ThinkingEffort, type TodoItem$1 as TodoItem, type Tool, type ToolChoice, type ToolContext, type ToolDefinition, type ToolFlags, type ToolJsonSchema, type ToolResult, TxMutex, type UpdateTodoInput, type TodoItem as UpdateTodoItem, type UserFinancialProfile, type UserPermissionConfig, VALID_PAIRS, WRITE_TOOLS, type WalletCacheEntry, type WalletCacheStore, type WalletCoin, _resetNaviCircuitBreaker, activitySummaryTool, adaptAllMcpTools, adaptAllServerTools, adaptMcpTool, addRecipientTool, applyToolFlags, awaitOrFetch, balanceCheckTool, borrowTool, budgetToolResult, buildCachedSystemPrompt, buildMcpTools, buildProactivenessInstructions, buildProfileContext, buildSelfEvaluationInstruction, buildStateContext, buildTool, bundleShortestTtl, checkValidPair, claimRewardsTool, clampThinkingForEffort, classifyEffort, clearPortfolioCache, clearPortfolioCacheFor, clearPriceMapCache, compactMessages, composeBundleFromToolResults, computeRegenerateFields, createGuardRunnerState, engineToSSE, estimateTokens, explainTxTool, extractAllProactiveMarkers, extractConversationText, extractMcpText, extractTrustedAddressesFromResult, fetchAddressDefiPortfolio, fetchAddressPortfolio, fetchAudricHistory, fetchAudricPortfolio, fetchAvailableRewards, fetchBalance, fetchHealthFactor, fetchPositions, fetchProtocolStats, fetchRates, fetchSavings, fetchTokenPrices, fetchWalletCoins, findTool, getAudricApiBase, getDefaultTools, getDefiCacheStore, getFetchLock, getMcpManager, getModifiableFields, getNaviCacheStore, getTelemetrySink, getToolFlags, getWalletAddress, getWalletCacheStore, guardArtifactPreview, guardStaleData, harnessShapeForEffort, hasNaviMcp, healthCheckTool, isBundleableTool, loadRecipes, looksLikeSuiNs, microcompact, mppServicesTool, naviKey, normalizeAddressInput, parseEvalSummary, parseMcpJson, parseProactiveMarker, parseRecipe, parseSSE, payApiTool, pollForIndexerCatchup, portfolioAnalysisTool, protocolDeepDiveTool, ratesInfoTool, regenerateBundle, registerEngineTools, renderCanvasTool, repayDebtTool, requireAgent, resetDefiCacheStore, resetFetchLock, resetNaviCacheStore, resetTelemetrySink, resetWalletCacheStore, resolveAddressToSuinsViaRpc, resolvePermissionTier, resolveSuinsTool, resolveSuinsViaRpc, resolveUsdValue, runGuards, runTools, saveContactTool, saveDepositTool, savingsInfoTool, sendTransferTool, serializeSSE, setDefiCacheStore, setFetchLock, setNaviCacheStore, setTelemetrySink, setWalletCacheStore, spendingAnalyticsTool, stripProactiveMarkers, swapExecuteTool, swapQuoteTool, tokenPricesTool, toolNameToOperation, toolsToDefinitions, transactionHistoryTool, transformBalance, transformHealthFactor, transformPositions, transformRates, transformRewards, transformSavings, updateGuardStateAfterToolResult, updateTodoTool, validateHistory, voloStakeTool, voloStatsTool, voloUnstakeTool, webSearchTool, withdrawTool, yieldSummaryTool };
+export { type AddressPortfolio, AnthropicProvider, type AnthropicProviderConfig, type AudricHistoryRecord, type AudricPortfolioResult, type AwaitOrFetchOpts, type BalancePrices, type BalanceResult, BalanceTracker, type BuildToolOptions, type BundleCompositionInput, CANVAS_TEMPLATES, type CanvasTemplate, type ChatParams, type CompactOptions, type ContentBlock, ContextBudget, type ContextBudgetConfig, type ConversationState, type ConversationStateStore, type CostSnapshot, CostTracker, type CostTrackerConfig, DEFAULT_GUARD_CONFIG, DEFAULT_LEASE_SEC, DEFAULT_PERMISSION_CONFIG, DEFAULT_POLL_BUDGET_MS, DEFAULT_POLL_INTERVAL_MS, DEFAULT_SYSTEM_PROMPT, DEFAULT_TOOL_TTL_MS, type DefiCacheEntry, type DefiCacheStore, type DefiProtocol, type DefiSummary, EFFORT_THINKING_BUDGET_CAPS, EarlyToolDispatcher, type EngineConfig, type EngineEvent, type EvalSummaryParseResult, type EvaluationItem, type EvaluationStatus, type FetchLock, type FormField, type FormFieldKind, type FormSchema, type GuardCheckResult, type GuardConfig, type GuardEvent, type GuardInjection, type GuardResult, type GuardRunnerState, type GuardTier, type GuardVerdict, type HarnessShape, type HealthFactorResult, InMemoryDefiCacheStore, InMemoryFetchLock, InMemoryNaviCacheStore, InMemoryWalletCacheStore, InvalidAddressError, type LLMProvider, MAX_BUNDLE_OPS, type McpCallResult, McpClientManager, McpResponseCache, type McpServerConfig, type McpServerConnection, type McpToolAdapterConfig, type McpToolDescriptor, MemorySessionStore, type Message, NAVI_ADDR_TTL_SEC, NAVI_MCP_CONFIG, NAVI_MCP_URL, NAVI_RATES_TTL_SEC, NAVI_SERVER_NAME, type NaviCacheEntry, type NaviCacheStore, type NaviRawCoin, type NaviRawHealthFactor, type NaviRawPool, type NaviRawPosition, type NaviRawPositionsResponse, type NaviRawProtocolStats, type NaviRawRewardsResponse, type NaviReadOptions, NaviTools, type NormalizedAddress, type OutputConfig, PERMISSION_PRESETS, type PendingAction, type PendingActionModifiableField, type PendingActionStep, type PendingInput, type PendingInputState, type PendingReward, type PendingToolCall, type PermissionLevel, type PermissionOperation, type PermissionResponse, type PermissionRule, type PortfolioCoin, type PositionEntry, type PostWritePollOptions, type PostWritePollOutcome, type PostWritePollResult, type PreflightResult, type ProactiveMarker, type ProactiveType, type ProtocolStats, type ProviderEvent, QueryEngine, READ_TOOLS, REGENERATABLE_READ_TOOLS, type RatesResult, type Recipe, type RecipePrerequisite, RecipeRegistry, type RecipeStep, type RecipeStepOnError, type RegenerateFailure, type RegenerateResult, type RegenerateSuccess, type RegenerateTimelineEvent, RetryTracker, type SSEEvent, SUINS_NAME_REGEX, SUI_ADDRESS_REGEX, SUI_ADDRESS_STRICT_REGEX, type SavingsResult, type ServerPositionData, type SessionData, type SessionStore, type StateType, type StopReason, type SuiCoinBalance, SuinsNotRegisteredError, SuinsRpcError, type SwapQuoteReadEntry, type SystemBlock, type SystemPrompt, TOOL_FLAGS, TOOL_MODIFIABLE_FIELDS, TOOL_TTL_MS, type TelemetrySink, type TelemetryTags, type ThinkingConfig, type ThinkingEffort, type TodoItem$1 as TodoItem, type Tool, type ToolChoice, type ToolContext, type ToolDefinition, type ToolFlags, type ToolJsonSchema, type ToolResult, TxMutex, type UpdateTodoInput, type TodoItem as UpdateTodoItem, type UserFinancialProfile, type UserPermissionConfig, VALID_PAIRS, WRITE_TOOLS, type WalletCacheEntry, type WalletCacheStore, type WalletCoin, _resetNaviCircuitBreaker, activitySummaryTool, adaptAllMcpTools, adaptAllServerTools, adaptMcpTool, addRecipientTool, applyToolFlags, awaitOrFetch, balanceCheckTool, borrowTool, budgetToolResult, buildCachedSystemPrompt, buildMcpTools, buildProactivenessInstructions, buildProfileContext, buildSelfEvaluationInstruction, buildStateContext, buildTool, bundleShortestTtl, checkValidPair, claimRewardsTool, clampThinkingForEffort, classifyEffort, clearPortfolioCache, clearPortfolioCacheFor, clearPriceMapCache, compactMessages, composeBundleFromToolResults, computeRegenerateFields, createGuardRunnerState, engineToSSE, estimateTokens, explainTxTool, extractAllProactiveMarkers, extractConversationText, extractMcpText, extractTrustedAddressesFromResult, fetchAddressDefiPortfolio, fetchAddressPortfolio, fetchAudricHistory, fetchAudricPortfolio, fetchAvailableRewards, fetchBalance, fetchHealthFactor, fetchPositions, fetchProtocolStats, fetchRates, fetchSavings, fetchTokenPrices, fetchWalletCoins, findMatchingCetusRoute, findTool, getAudricApiBase, getDefaultTools, getDefiCacheStore, getFetchLock, getMcpManager, getModifiableFields, getNaviCacheStore, getTelemetrySink, getToolFlags, getWalletAddress, getWalletCacheStore, guardArtifactPreview, guardStaleData, harnessShapeForEffort, hasNaviMcp, healthCheckTool, isBundleableTool, loadRecipes, looksLikeSuiNs, microcompact, mppServicesTool, naviKey, normalizeAddressInput, parseEvalSummary, parseMcpJson, parseProactiveMarker, parseRecipe, parseSSE, payApiTool, pollForIndexerCatchup, portfolioAnalysisTool, protocolDeepDiveTool, ratesInfoTool, regenerateBundle, registerEngineTools, renderCanvasTool, repayDebtTool, requireAgent, resetDefiCacheStore, resetFetchLock, resetNaviCacheStore, resetTelemetrySink, resetWalletCacheStore, resolveAddressToSuinsViaRpc, resolvePermissionTier, resolveSuinsTool, resolveSuinsViaRpc, resolveUsdValue, runGuards, runTools, saveContactTool, saveDepositTool, savingsInfoTool, sendTransferTool, serializeSSE, setDefiCacheStore, setFetchLock, setNaviCacheStore, setTelemetrySink, setWalletCacheStore, spendingAnalyticsTool, stripProactiveMarkers, swapExecuteTool, swapQuoteTool, tokenPricesTool, toolNameToOperation, toolsToDefinitions, transactionHistoryTool, transformBalance, transformHealthFactor, transformPositions, transformRates, transformRewards, transformSavings, updateGuardStateAfterToolResult, updateTodoTool, validateHistory, voloStakeTool, voloStatsTool, voloUnstakeTool, webSearchTool, withdrawTool, yieldSummaryTool };

package/dist/index.js

@@ -3771,6 +3771,34 @@ var swapQuoteTool = buildTool({
     required: ["from", "to", "amount"]
   },
   isReadOnly: true,
+  // [SPEC 20.2 / D-1 (a) follow-on, 2026-05-10] Quote results MUST NOT be
+  // cross-turn deduped by microcompact. Every call legitimately produces a
+  // new result — pool reserves move per block, slippage windows update, the
+  // best route can shift if liquidity moves, and the result's `discoveredAt`
+  // timestamp is different per call by definition.
+  //
+  // Pre-fix: microcompact's default `cacheable: true` replaced the second
+  // identical-input swap_quote tool_result with a `[Same result as call #N
+  // — swap_quote with identical inputs. Result unchanged.]` placeholder.
+  // The placeholder lied — the route and `discoveredAt` had legitimately
+  // updated. Audric's bundle fast-path (which reads quote results from the
+  // persisted ledger to thread `step.cetusRoute`) lost the fresh route and
+  // had to fall back to whichever earlier same-input call WAS preserved
+  // (the "first-seen" anchor, often >30s old → rejected by audric's
+  // `isCetusRouteFresh` 30s gate → fast path missed → bundle paid full
+  // ~400-500ms `findSwapRoute()` round-trip at confirm time).
+  //
+  // Production smoke trace (2026-05-10, session s_1778362657811_c0ed9009a5fb):
+  //   T0     swap_quote(USDC,SUI,0.5)              → route X discovered
+  //   T0+34s swap_quote(USDC,SUI,0.5) [bundle]     → route Y discovered (FRESH)
+  //   T0+50s "Confirm" → fast-path walks history   → walker sees placeholder
+  //                                                   on route Y, falls back
+  //                                                   to route X (52s old)
+  //   T0+52s prepare → cetusRoute STALE → fallback → no perf win
+  //
+  // With `cacheable: false`: route Y stays as full content in the ledger,
+  // walker finds it (~18s old), passes the freshness gate, fast path fires.
+  cacheable: false,
   async call(input, context) {
     const walletAddress = context.agent ? context.agent.address() : getWalletAddress(context);
     const sink = getTelemetrySink();
@@ -7235,6 +7263,34 @@ var REGENERATABLE_READ_TOOLS = /* @__PURE__ */ new Set([
   "health_check"
 ]);
 
+// src/swap-route-matching.ts
+function findMatchingCetusRoute(swapExecuteInput, swapQuoteReads) {
+  if (!isSwapExecuteInput(swapExecuteInput)) return void 0;
+  if (swapQuoteReads.length === 0) return void 0;
+  const target = normalizeSwapKey(swapExecuteInput);
+  for (let i = swapQuoteReads.length - 1; i >= 0; i--) {
+    const entry = swapQuoteReads[i];
+    const candidate = normalizeSwapKey(entry.input);
+    if (candidate.from === target.from && candidate.to === target.to && candidate.amount === target.amount && candidate.byAmountIn === target.byAmountIn) {
+      return entry.result.serializedRoute;
+    }
+  }
+  return void 0;
+}
+function isSwapExecuteInput(input) {
+  if (typeof input !== "object" || input === null) return false;
+  const obj = input;
+  return typeof obj.from === "string" && typeof obj.to === "string" && typeof obj.amount === "number";
+}
+function normalizeSwapKey(input) {
+  return {
+    from: input.from.toLowerCase(),
+    to: input.to.toLowerCase(),
+    amount: input.amount,
+    byAmountIn: input.byAmountIn ?? true
+  };
+}
+
 // src/compose-bundle.ts
 var MAX_BUNDLE_OPS = 4;
 var VALID_PAIRS = /* @__PURE__ */ new Set([
@@ -7310,13 +7366,15 @@ function composeBundleFromToolResults(input) {
     }
     const description = describeAction(tool, call);
     const modifiableFields = getModifiableFields(call.name);
+    const cetusRoute = call.name === "swap_execute" && input.swapQuoteReads ? findMatchingCetusRoute(call.input, input.swapQuoteReads) : void 0;
     return {
       toolName: call.name,
       toolUseId: call.id,
       attemptId: randomUUID(),
       input: call.input,
       description,
-      ...modifiableFields?.length ? { modifiableFields } : {}
+      ...modifiableFields?.length ? { modifiableFields } : {},
+      ...cetusRoute ? { cetusRoute } : {}
     };
   });
   for (let i = 1; i < input.pendingWrites.length; i++) {
@@ -7349,6 +7407,10 @@ function composeBundleFromToolResults(input) {
     ...allGuardInjections.length ? { guardInjections: allGuardInjections } : {},
     turnIndex: input.turnIndex,
     attemptId: firstStep.attemptId,
+    // [SPEC 20.2 / D-1 (a)] Mirror step[0]'s cetusRoute to the top-level
+    // field for backward compat with pre-bundle hosts that don't iterate
+    // steps[]. Bundle-aware hosts read per-step `step.cetusRoute`.
+    ...firstStep.cetusRoute ? { cetusRoute: firstStep.cetusRoute } : {},
     steps,
     canRegenerate,
     ...quoteAge !== void 0 ? { quoteAge } : {},
@@ -7606,6 +7668,10 @@ var QueryEngine = class {
       })),
       ...writeResultBlocks
     ];
+    const canonicalRouteText = response.approved ? buildCanonicalRouteText(action) : null;
+    if (canonicalRouteText) {
+      allResults.push({ type: "text", text: canonicalRouteText });
+    }
     this.messages.push({ role: "user", content: allResults });
     if (isBundle) {
       const steps = action.steps;
@@ -8155,6 +8221,7 @@ var QueryEngine = class {
       sink.gauge("engine.turn_turns_used", turns, tags);
     };
     const turnReadToolResults = [];
+    const swapQuoteReads = [];
     while (turns < this.maxTurns) {
       if (signal.aborted) {
         yield { type: "error", error: new Error("Aborted") };
@@ -8337,6 +8404,19 @@ ${recipeCtx}`;
                 toolName: finalEvent.toolName,
                 timestamp: Date.now()
               });
+              if (finalEvent.toolName === "swap_quote" && earlyInput) {
+                const r = finalEvent.result;
+                const dataResult = r?.data && typeof r.data === "object" ? r.data : null;
+                const serializedRoute = r?.serializedRoute ?? dataResult?.serializedRoute;
+                if (serializedRoute) {
+                  swapQuoteReads.push({
+                    toolUseId: finalEvent.toolUseId,
+                    input: earlyInput,
+                    result: { serializedRoute },
+                    timestamp: Date.now()
+                  });
+                }
+              }
             }
             earlyResultBlocks.push({
               type: "tool_result",
@@ -8578,6 +8658,19 @@ ${recipeCtx}`;
                 toolName: finalEvent.toolName,
                 timestamp: Date.now()
               });
+              if (finalEvent.toolName === "swap_quote" && originalCall) {
+                const r = finalEvent.result;
+                const dataResult = r?.data && typeof r.data === "object" ? r.data : null;
+                const serializedRoute = r?.serializedRoute ?? dataResult?.serializedRoute;
+                if (serializedRoute) {
+                  swapQuoteReads.push({
+                    toolUseId: finalEvent.toolUseId,
+                    input: originalCall.input,
+                    result: { serializedRoute },
+                    timestamp: Date.now()
+                  });
+                }
+              }
             } else {
               this.turnReadCache.clear();
             }
@@ -8728,6 +8821,7 @@ ${recipeCtx}`;
             pendingWrites: guardPassedWrites.map((w) => w.call),
             tools: this.tools,
             readResults: turnReadToolResults,
+            swapQuoteReads,
             assistantContent: acc.assistantBlocks,
             completedResults,
             guardInjectionsByCallId,
@@ -8764,6 +8858,7 @@ ${recipeCtx}`;
         const modifiableFields = getModifiableFields(pendingWrite.call.name);
         const attemptId = randomUUID();
         const singleWriteRegen = computeRegenerateFields(turnReadToolResults);
+        const singleCetusRoute = pendingWrite.call.name === "swap_execute" ? findMatchingCetusRoute(pendingWrite.call.input, swapQuoteReads) : void 0;
         yield {
           type: "pending_action",
           action: {
@@ -8781,6 +8876,7 @@ ${recipeCtx}`;
             ...modifiableFields?.length ? { modifiableFields } : {},
             turnIndex,
             attemptId,
+            ...singleCetusRoute ? { cetusRoute: singleCetusRoute } : {},
             ...singleWriteRegen.canRegenerate ? {
               canRegenerate: true,
               regenerateInput: { toolUseIds: singleWriteRegen.regenerateToolUseIds },
@@ -8932,6 +9028,35 @@ ${recipeCtx}`;
     }
   }
 };
+function buildCanonicalRouteText(action) {
+  const swaps = [];
+  if (Array.isArray(action.steps) && action.steps.length > 0) {
+    for (const step of action.steps) {
+      if (step.toolName === "swap_execute" && step.cetusRoute) {
+        swaps.push({ input: step.input, cetusRoute: step.cetusRoute });
+      }
+    }
+  } else if (action.toolName === "swap_execute" && action.cetusRoute) {
+    swaps.push({ input: action.input, cetusRoute: action.cetusRoute });
+  }
+  if (swaps.length === 0) return null;
+  const blocks = swaps.map(({ input, cetusRoute }) => {
+    const inp = input;
+    const providers = cetusRoute.routerData.paths.map((p) => p.provider).filter(Boolean).slice(0, 5);
+    const providerLine = providers.length > 0 ? providers.join(" + ") : "Cetus Aggregator";
+    const impactPct = (cetusRoute.priceImpact * 100).toFixed(3);
+    return [
+      "<canonical_route>",
+      `The user just approved a swap. The CANONICAL route taken on-chain is:`,
+      `- Pair: ${inp?.from ?? "?"} \u2192 ${inp?.to ?? "?"}`,
+      `- Path: ${providerLine}`,
+      `- Price impact: ${impactPct}%`,
+      `When narrating this swap, cite this EXACT path string. Do NOT reference any prior swap_quote that produced a different route \u2014 that quote is no longer canonical.`,
+      "</canonical_route>"
+    ].join("\n");
+  });
+  return blocks.join("\n\n");
+}
 function isCorruptHistoryError(err) {
   const msg = err instanceof Error ? err.message : String(err);
   return msg.includes("tool_use") && msg.includes("tool_result") || msg.includes("roles must alternate") || msg.includes("400") && msg.includes("invalid_request_error");
@@ -10498,6 +10623,6 @@ function sanitizeAnthropicMessages(messages) {
   return merged;
 }
 
-export { AnthropicProvider, BalanceTracker, CANVAS_TEMPLATES, ContextBudget, CostTracker, DEFAULT_GUARD_CONFIG, DEFAULT_LEASE_SEC, DEFAULT_PERMISSION_CONFIG, DEFAULT_POLL_BUDGET_MS, DEFAULT_POLL_INTERVAL_MS, DEFAULT_SYSTEM_PROMPT, DEFAULT_TOOL_TTL_MS, EFFORT_THINKING_BUDGET_CAPS, EarlyToolDispatcher, InMemoryDefiCacheStore, InMemoryFetchLock, InMemoryNaviCacheStore, InMemoryWalletCacheStore, InvalidAddressError, MAX_BUNDLE_OPS, McpClientManager, McpResponseCache, MemorySessionStore, NAVI_ADDR_TTL_SEC, NAVI_MCP_CONFIG, NAVI_MCP_URL, NAVI_RATES_TTL_SEC, NAVI_SERVER_NAME, NaviTools, PERMISSION_PRESETS, QueryEngine, READ_TOOLS, REGENERATABLE_READ_TOOLS, RecipeRegistry, RetryTracker, SUINS_NAME_REGEX, SUI_ADDRESS_REGEX, SUI_ADDRESS_STRICT_REGEX, SuinsNotRegisteredError, SuinsRpcError, TOOL_FLAGS, TOOL_MODIFIABLE_FIELDS, TOOL_TTL_MS, TxMutex, VALID_PAIRS, WRITE_TOOLS, _resetNaviCircuitBreaker, activitySummaryTool, adaptAllMcpTools, adaptAllServerTools, adaptMcpTool, addRecipientTool, applyToolFlags, awaitOrFetch, balanceCheckTool, borrowTool, budgetToolResult, buildCachedSystemPrompt, buildMcpTools, buildProactivenessInstructions, buildProfileContext, buildSelfEvaluationInstruction, buildStateContext, buildTool, bundleShortestTtl, checkValidPair, claimRewardsTool, clampThinkingForEffort, classifyEffort, clearPortfolioCache, clearPortfolioCacheFor, clearPriceMapCache, compactMessages, composeBundleFromToolResults, computeRegenerateFields, createGuardRunnerState, engineToSSE, estimateTokens, explainTxTool, extractAllProactiveMarkers, extractConversationText, extractMcpText, extractTrustedAddressesFromResult, fetchAddressDefiPortfolio, fetchAddressPortfolio, fetchAudricHistory, fetchAudricPortfolio, fetchAvailableRewards, fetchBalance, fetchHealthFactor, fetchPositions, fetchProtocolStats, fetchRates, fetchSavings, fetchTokenPrices, fetchWalletCoins, findTool, getAudricApiBase, getDefaultTools, getDefiCacheStore, getFetchLock, getMcpManager, getModifiableFields, getNaviCacheStore, getTelemetrySink, getToolFlags, getWalletAddress, getWalletCacheStore, guardArtifactPreview, guardStaleData, harnessShapeForEffort, hasNaviMcp, healthCheckTool, isBundleableTool, loadRecipes, looksLikeSuiNs, microcompact, mppServicesTool, naviKey, normalizeAddressInput, parseEvalSummary, parseMcpJson, parseProactiveMarker, parseRecipe, parseSSE, payApiTool, pollForIndexerCatchup, portfolioAnalysisTool, protocolDeepDiveTool, ratesInfoTool, regenerateBundle, registerEngineTools, renderCanvasTool, repayDebtTool, requireAgent, resetDefiCacheStore, resetFetchLock, resetNaviCacheStore, resetTelemetrySink, resetWalletCacheStore, resolveAddressToSuinsViaRpc, resolvePermissionTier, resolveSuinsTool, resolveSuinsViaRpc, resolveUsdValue, runGuards, runTools, saveContactTool, saveDepositTool, savingsInfoTool, sendTransferTool, serializeSSE, setDefiCacheStore, setFetchLock, setNaviCacheStore, setTelemetrySink, setWalletCacheStore, spendingAnalyticsTool, stripProactiveMarkers, swapExecuteTool, swapQuoteTool, tokenPricesTool, toolNameToOperation, toolsToDefinitions, transactionHistoryTool, transformBalance, transformHealthFactor, transformPositions, transformRates, transformRewards, transformSavings, updateGuardStateAfterToolResult, updateTodoTool, validateHistory, voloStakeTool, voloStatsTool, voloUnstakeTool, webSearchTool, withdrawTool, yieldSummaryTool };
+export { AnthropicProvider, BalanceTracker, CANVAS_TEMPLATES, ContextBudget, CostTracker, DEFAULT_GUARD_CONFIG, DEFAULT_LEASE_SEC, DEFAULT_PERMISSION_CONFIG, DEFAULT_POLL_BUDGET_MS, DEFAULT_POLL_INTERVAL_MS, DEFAULT_SYSTEM_PROMPT, DEFAULT_TOOL_TTL_MS, EFFORT_THINKING_BUDGET_CAPS, EarlyToolDispatcher, InMemoryDefiCacheStore, InMemoryFetchLock, InMemoryNaviCacheStore, InMemoryWalletCacheStore, InvalidAddressError, MAX_BUNDLE_OPS, McpClientManager, McpResponseCache, MemorySessionStore, NAVI_ADDR_TTL_SEC, NAVI_MCP_CONFIG, NAVI_MCP_URL, NAVI_RATES_TTL_SEC, NAVI_SERVER_NAME, NaviTools, PERMISSION_PRESETS, QueryEngine, READ_TOOLS, REGENERATABLE_READ_TOOLS, RecipeRegistry, RetryTracker, SUINS_NAME_REGEX, SUI_ADDRESS_REGEX, SUI_ADDRESS_STRICT_REGEX, SuinsNotRegisteredError, SuinsRpcError, TOOL_FLAGS, TOOL_MODIFIABLE_FIELDS, TOOL_TTL_MS, TxMutex, VALID_PAIRS, WRITE_TOOLS, _resetNaviCircuitBreaker, activitySummaryTool, adaptAllMcpTools, adaptAllServerTools, adaptMcpTool, addRecipientTool, applyToolFlags, awaitOrFetch, balanceCheckTool, borrowTool, budgetToolResult, buildCachedSystemPrompt, buildMcpTools, buildProactivenessInstructions, buildProfileContext, buildSelfEvaluationInstruction, buildStateContext, buildTool, bundleShortestTtl, checkValidPair, claimRewardsTool, clampThinkingForEffort, classifyEffort, clearPortfolioCache, clearPortfolioCacheFor, clearPriceMapCache, compactMessages, composeBundleFromToolResults, computeRegenerateFields, createGuardRunnerState, engineToSSE, estimateTokens, explainTxTool, extractAllProactiveMarkers, extractConversationText, extractMcpText, extractTrustedAddressesFromResult, fetchAddressDefiPortfolio, fetchAddressPortfolio, fetchAudricHistory, fetchAudricPortfolio, fetchAvailableRewards, fetchBalance, fetchHealthFactor, fetchPositions, fetchProtocolStats, fetchRates, fetchSavings, fetchTokenPrices, fetchWalletCoins, findMatchingCetusRoute, findTool, getAudricApiBase, getDefaultTools, getDefiCacheStore, getFetchLock, getMcpManager, getModifiableFields, getNaviCacheStore, getTelemetrySink, getToolFlags, getWalletAddress, getWalletCacheStore, guardArtifactPreview, guardStaleData, harnessShapeForEffort, hasNaviMcp, healthCheckTool, isBundleableTool, loadRecipes, looksLikeSuiNs, microcompact, mppServicesTool, naviKey, normalizeAddressInput, parseEvalSummary, parseMcpJson, parseProactiveMarker, parseRecipe, parseSSE, payApiTool, pollForIndexerCatchup, portfolioAnalysisTool, protocolDeepDiveTool, ratesInfoTool, regenerateBundle, registerEngineTools, renderCanvasTool, repayDebtTool, requireAgent, resetDefiCacheStore, resetFetchLock, resetNaviCacheStore, resetTelemetrySink, resetWalletCacheStore, resolveAddressToSuinsViaRpc, resolvePermissionTier, resolveSuinsTool, resolveSuinsViaRpc, resolveUsdValue, runGuards, runTools, saveContactTool, saveDepositTool, savingsInfoTool, sendTransferTool, serializeSSE, setDefiCacheStore, setFetchLock, setNaviCacheStore, setTelemetrySink, setWalletCacheStore, spendingAnalyticsTool, stripProactiveMarkers, swapExecuteTool, swapQuoteTool, tokenPricesTool, toolNameToOperation, toolsToDefinitions, transactionHistoryTool, transformBalance, transformHealthFactor, transformPositions, transformRates, transformRewards, transformSavings, updateGuardStateAfterToolResult, updateTodoTool, validateHistory, voloStakeTool, voloStatsTool, voloUnstakeTool, webSearchTool, withdrawTool, yieldSummaryTool };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map