@t2000/engine 1.4.0 → 1.5.0

package/dist/index.d.ts

@@ -393,7 +393,11 @@ interface AddressPortfolio {
  *     overwrite — preserves the original `pricedAt` so a UI can
  *     render "last refresh Nm ago".
  */
-declare function fetchAddressPortfolio(address: string, apiKey: string | undefined, fallbackRpcUrl?: string): Promise<AddressPortfolio>;
+declare function fetchAddressPortfolio(address: string, apiKey: string | undefined, fallbackRpcUrl?: string, opts?: {
+    retryStats?: {
+        attemptCount: number;
+    };
+}): Promise<AddressPortfolio>;
 /**
  * Multi-token price lookup. Returns a map of coinType → `{ price, change24h }`
  * with the `change24h` field populated when BlockVision returns it.
@@ -404,7 +408,11 @@ declare function fetchAddressPortfolio(address: string, apiKey: string | undefin
  * requested coins fetches only the missing 2 instead of throwing the
  * whole map away.
  */
-declare function fetchTokenPrices(coinTypes: string[], apiKey: string | undefined): Promise<Record<string, {
+declare function fetchTokenPrices(coinTypes: string[], apiKey: string | undefined, opts?: {
+    retryStats?: {
+        attemptCount: number;
+    };
+}): Promise<Record<string, {
     price: number;
     change24h?: number;
 }>>;
@@ -431,7 +439,11 @@ interface DefiSummary {
      */
     source: 'blockvision' | 'partial' | 'partial-stale' | 'degraded';
 }
-declare function fetchAddressDefiPortfolio(address: string, apiKey: string | undefined, priceHints?: Record<string, number>): Promise<DefiSummary>;
+declare function fetchAddressDefiPortfolio(address: string, apiKey: string | undefined, priceHints?: Record<string, number>, opts?: {
+    retryStats?: {
+        attemptCount: number;
+    };
+}): Promise<DefiSummary>;
 /**
  * Wipe the wallet portfolio cache plus any in-flight promises.
  *
@@ -701,6 +713,22 @@ type EngineEvent =
      * UI affordances (e.g. a subtle "auto-refreshed" badge).
      */
     wasPostWriteRefresh?: boolean;
+    /**
+     * [SPEC 8 v0.5.1 B3.2] Number of HTTP attempts the tool made before
+     * succeeding (or returning the final result). Surfaced when the tool
+     * went through one or more retries inside its retry wrapper
+     * (`fetchBlockVisionWithRetry` and equivalents). Set ONLY when N > 1
+     * — a successful first try leaves the field undefined to avoid
+     * header noise in the host's `ToolBlockView`. Hosts render
+     * "TOOL · attempt N · 1.4s" subtitle when present, hidden otherwise.
+     *
+     * Plumbing: engine sets a per-tool `retryStats: { attemptCount: 1 }`
+     * counter on `ToolContext`; the BlockVision retry wrapper increments
+     * it on every retry attempt; the engine reads it back after the tool
+     * returns and surfaces here when > 1. Tools that don't use a retry
+     * wrapper never emit a value.
+     */
+    attemptCount?: number;
 } | {
     type: 'pending_action';
     action: PendingAction;
@@ -785,7 +813,52 @@ type EngineEvent =
     inputId: string;
     /** Optional human-readable prompt the LLM wants the host to display above the form. */
     prompt?: string;
+}
+/**
+ * [SPEC 8 v0.5.1 B3.2] One-shot per-turn declaration of which adaptive
+ * harness shape this turn is running under. Emitted at the start of
+ * `submitMessage` BEFORE `agentLoop` begins (not on `resumeWithToolResult`
+ * — resume is a continuation of the same turn, not a new shape decision).
+ *
+ * Derived from `classifyEffort()` on the host side: `low → 'lean'`,
+ * `medium → 'standard'`, `high → 'rich'`, `max → 'max'`. Hosts use it
+ * to (a) pre-allocate UI affordances (todo surface for `rich+`),
+ * (b) stamp `TurnMetrics.harnessShape` for dashboard segmentation,
+ * and (c) gate optional features (e.g. forbid `update_todo` rendering
+ * on `lean` even if a misbehaving LLM emits one).
+ *
+ * If absent, hosts MUST default to `'legacy'` for telemetry purposes
+ * (existing engines that don't emit this event are pre-SPEC-8). The
+ * engine emits it ONLY when the host passes `harnessShape` into
+ * `submitMessage` options; hosts that don't classify won't see this
+ * event.
+ */
+ | {
+    type: 'harness_shape';
+    shape: HarnessShape;
+    /**
+     * 1-line human-readable explanation of why this shape was picked.
+     * Examples: "matched recipe portfolio_rebalance → max",
+     * "session has prior writes + 'borrow' keyword → rich",
+     * "single-fact lookup → lean". Forwarded into telemetry verbatim.
+     */
+    rationale: string;
 };
+/**
+ * [SPEC 8 v0.5.1 B3.2] Adaptive harness shape — driven by `classifyEffort()`,
+ * pinned per-turn at turn start. Each shape implies a different
+ * `thinking.budget_tokens` cap, soft block limit, and `update_todo`
+ * permission. See SPEC 8 § "Adaptive thresholds: harness shape gate"
+ * for the canonical mapping.
+ */
+type HarnessShape = 'lean' | 'standard' | 'rich' | 'max';
+/**
+ * [SPEC 8 v0.5.1 B3.2] Maps the engine's `ThinkingEffort` to the host-facing
+ * harness shape. Single source of truth for the `low → lean`, `medium →
+ * standard`, `high → rich`, `max → max` mapping. Exported so hosts (and
+ * tests) get the mapping for free without re-implementing it.
+ */
+declare function harnessShapeForEffort(effort: ThinkingEffort): HarnessShape;
 /**
  * [SPEC 8 v0.5.1] One row in an `update_todo` payload. Mirrored from
  * `packages/engine/src/tools/update-todo.ts`. Kept here so hosts that
@@ -920,6 +993,23 @@ interface ToolContext {
      * primarily a fast-path optimisation rather than a correctness primitive.
      */
     portfolioCache?: Map<string, AddressPortfolio>;
+    /**
+     * [SPEC 8 v0.5.1 B3.2] Per-tool-invocation HTTP attempt counter. The
+     * engine's tool dispatcher attaches a fresh `{ attemptCount: 1 }` to
+     * the context before calling each tool; retry wrappers
+     * (`fetchBlockVisionWithRetry` and equivalents) bump
+     * `retryStats.attemptCount` on every retry beyond the first attempt;
+     * the dispatcher reads the final value back and surfaces it on the
+     * `tool_result` event (only when > 1). Tools that don't use a retry
+     * wrapper never observe a non-default value.
+     *
+     * The mutable-ref shape is deliberate — it lets retry wrappers deep
+     * in the call stack record state without changing every caller's
+     * return type.
+     */
+    retryStats?: {
+        attemptCount: number;
+    };
 }
 interface ServerPositionData {
     savings: number;
@@ -1289,8 +1379,20 @@ declare class QueryEngine {
      * `pending_action` event and the stream ends — no persistent connection needed.
      * The caller should save messages + pendingAction to the session store, then
      * call `resumeWithToolResult()` after the user approves/denies and executes.
+     *
+     * [SPEC 8 v0.5.1 B3.2] Optional `options.harnessShape` + `options.harnessRationale`
+     * cause a one-shot `harness_shape` event to be yielded BEFORE the agent loop
+     * begins. The engine itself doesn't classify — the host calls
+     * `classifyEffort()` (host already does this for thinking-budget routing)
+     * and maps via `harnessShapeForEffort()` before calling `submitMessage`.
+     * Hosts that don't pass `harnessShape` won't see the event (existing
+     * pre-SPEC-8 hosts continue to work; their `TurnMetrics.harnessShape`
+     * defaults to `'legacy'`).
      */
-    submitMessage(prompt: string): AsyncGenerator<EngineEvent>;
+    submitMessage(prompt: string, options?: {
+        harnessShape?: HarnessShape;
+        harnessRationale?: string;
+    }): AsyncGenerator<EngineEvent>;
     /**
      * Resume the conversation after a pending action is resolved.
      * Called with the user's approval/denial and optional client-side execution result.
@@ -1417,6 +1519,7 @@ type SSEEvent = {
     wasEarlyDispatched?: boolean;
     resultDeduped?: boolean;
     wasPostWriteRefresh?: boolean;
+    attemptCount?: number;
 } | {
     type: 'pending_action';
     action: PendingAction;
@@ -1453,6 +1556,10 @@ type SSEEvent = {
     schema: unknown;
     inputId: string;
     prompt?: string;
+} | {
+    type: 'harness_shape';
+    shape: HarnessShape;
+    rationale: string;
 };
 declare function serializeSSE(event: SSEEvent): string;
 declare function parseSSE(raw: string): SSEEvent | null;
@@ -3231,4 +3338,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, 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, 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 GuardCheckResult, type GuardConfig, type GuardEvent, type GuardInjection, type GuardResult, type GuardRunnerState, type GuardTier, type GuardVerdict, type HealthFactorResult, InMemoryDefiCacheStore, InMemoryFetchLock, InMemoryNaviCacheStore, InMemoryWalletCacheStore, InvalidAddressError, type LLMProvider, 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 PendingReward, type PendingToolCall, type PermissionLevel, type PermissionOperation, type PermissionResponse, type PermissionRule, type PortfolioCoin, type PositionEntry, type PreflightResult, type ProtocolStats, type ProviderEvent, QueryEngine, READ_TOOLS, type RatesResult, type Recipe, type RecipePrerequisite, RecipeRegistry, type RecipeStep, type RecipeStepOnError, 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, 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, WRITE_TOOLS, type WalletCacheEntry, type WalletCacheStore, type WalletCoin, _resetNaviCircuitBreaker, activitySummaryTool, adaptAllMcpTools, adaptAllServerTools, adaptMcpTool, applyToolFlags, awaitOrFetch, balanceCheckTool, borrowTool, budgetToolResult, buildCachedSystemPrompt, buildMcpTools, buildProactivenessInstructions, buildProfileContext, buildSelfEvaluationInstruction, buildStateContext, buildTool, claimRewardsTool, clampThinkingForEffort, classifyEffort, clearPortfolioCache, clearPortfolioCacheFor, clearPriceMapCache, compactMessages, createGuardRunnerState, engineToSSE, estimateTokens, explainTxTool, extractConversationText, extractMcpText, 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, hasNaviMcp, healthCheckTool, loadRecipes, looksLikeSuiNs, microcompact, mppServicesTool, naviKey, normalizeAddressInput, parseEvalSummary, parseMcpJson, parseRecipe, parseSSE, payApiTool, portfolioAnalysisTool, protocolDeepDiveTool, ratesInfoTool, 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, 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, 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, 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 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, 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 PendingReward, type PendingToolCall, type PermissionLevel, type PermissionOperation, type PermissionResponse, type PermissionRule, type PortfolioCoin, type PositionEntry, type PreflightResult, type ProtocolStats, type ProviderEvent, QueryEngine, READ_TOOLS, type RatesResult, type Recipe, type RecipePrerequisite, RecipeRegistry, type RecipeStep, type RecipeStepOnError, 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, 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, WRITE_TOOLS, type WalletCacheEntry, type WalletCacheStore, type WalletCoin, _resetNaviCircuitBreaker, activitySummaryTool, adaptAllMcpTools, adaptAllServerTools, adaptMcpTool, applyToolFlags, awaitOrFetch, balanceCheckTool, borrowTool, budgetToolResult, buildCachedSystemPrompt, buildMcpTools, buildProactivenessInstructions, buildProfileContext, buildSelfEvaluationInstruction, buildStateContext, buildTool, claimRewardsTool, clampThinkingForEffort, classifyEffort, clearPortfolioCache, clearPortfolioCacheFor, clearPriceMapCache, compactMessages, createGuardRunnerState, engineToSSE, estimateTokens, explainTxTool, extractConversationText, extractMcpText, 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, loadRecipes, looksLikeSuiNs, microcompact, mppServicesTool, naviKey, normalizeAddressInput, parseEvalSummary, parseMcpJson, parseRecipe, parseSSE, payApiTool, portfolioAnalysisTool, protocolDeepDiveTool, ratesInfoTool, 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, 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

@@ -61,6 +61,13 @@ var TxMutex = class {
     }
   }
 };
+function withRetryStats(context) {
+  const retryStats = { attemptCount: 1 };
+  return {
+    context: { ...context, retryStats },
+    readAttemptCount: () => retryStats.attemptCount > 1 ? retryStats.attemptCount : void 0
+  };
+}
 async function* runTools(pending, tools, context, txMutex) {
   const { reads, writes } = partitionToolCalls(pending, tools);
   if (reads.length > 0) {
@@ -68,24 +75,36 @@ async function* runTools(pending, tools, context, txMutex) {
       reads.map(async (call) => {
         const tool = findTool(tools, call.name);
         if (!tool) {
-          return { call, result: { data: { error: `Unknown tool: ${call.name}` } }, isError: true };
+          return {
+            call,
+            result: { data: { error: `Unknown tool: ${call.name}` } },
+            isError: true,
+            attemptCount: void 0
+          };
         }
-        const execResult = await executeSingleTool(tool, call, context);
+        const { context: toolCtx, readAttemptCount } = withRetryStats(context);
+        const execResult = await executeSingleTool(tool, call, toolCtx);
         if (!execResult.isError) {
           execResult.data = budgetToolResult(execResult.data, tool);
         }
-        return { call, result: execResult, isError: execResult.isError };
+        return {
+          call,
+          result: execResult,
+          isError: execResult.isError,
+          attemptCount: readAttemptCount()
+        };
       })
     );
     for (const settled of readResults) {
       if (settled.status === "fulfilled") {
-        const { call, result, isError } = settled.value;
+        const { call, result, isError, attemptCount } = settled.value;
         yield {
           type: "tool_result",
           toolName: call.name,
           toolUseId: call.id,
           result: result.data,
-          isError
+          isError,
+          ...attemptCount !== void 0 ? { attemptCount } : {}
         };
       } else {
         const idx = readResults.indexOf(settled);
@@ -114,16 +133,19 @@ async function* runTools(pending, tools, context, txMutex) {
     }
     await txMutex.acquire();
     try {
-      const result = await executeSingleTool(tool, call, context);
+      const { context: toolCtx, readAttemptCount } = withRetryStats(context);
+      const result = await executeSingleTool(tool, call, toolCtx);
       if (!result.isError) {
         result.data = budgetToolResult(result.data, tool);
       }
+      const attemptCount = readAttemptCount();
       yield {
         type: "tool_result",
         toolName: call.name,
         toolUseId: call.id,
         result: result.data,
-        isError: result.isError
+        isError: result.isError,
+        ...attemptCount !== void 0 ? { attemptCount } : {}
       };
     } catch (err) {
       yield {
@@ -726,6 +748,7 @@ async function fetchBlockVisionWithRetry(url, init, opts = {}) {
   let lastError = null;
   let lastResponse = null;
   for (let attempt = 0; attempt < BV_RETRY_MAX_ATTEMPTS; attempt++) {
+    if (opts.retryStats) opts.retryStats.attemptCount = attempt + 1;
     if (attempt > 0) {
       let waitMs = BV_RETRY_BASE_DELAY_MS * Math.pow(BV_RETRY_BACKOFF_FACTOR, attempt - 1);
       const retryAfter = lastResponse?.headers.get("retry-after");
@@ -808,7 +831,7 @@ async function safeWalletStoreGet(store, address) {
     return null;
   }
 }
-async function fetchAddressPortfolio(address, apiKey, fallbackRpcUrl) {
+async function fetchAddressPortfolio(address, apiKey, fallbackRpcUrl, opts = {}) {
   const store = getWalletCacheStore();
   const cachedEntry = await safeWalletStoreGet(store, address);
   if (cachedEntry) {
@@ -841,7 +864,7 @@ async function fetchAddressPortfolio(address, apiKey, fallbackRpcUrl) {
             }
           }
           if (apiKey && apiKey.trim().length > 0) {
-            const blockvision = await fetchPortfolioFromBlockVision(address, apiKey);
+            const blockvision = await fetchPortfolioFromBlockVision(address, apiKey, opts.retryStats);
             if (blockvision) {
               await safeWalletStoreSet(
                 store,
@@ -885,7 +908,7 @@ async function fetchAddressPortfolio(address, apiKey, fallbackRpcUrl) {
   portfolioInflight.set(address, promise);
   return promise;
 }
-async function fetchPortfolioFromBlockVision(address, apiKey) {
+async function fetchPortfolioFromBlockVision(address, apiKey, retryStats) {
   const url = `${BLOCKVISION_BASE}/account/coins?account=${encodeURIComponent(address)}`;
   const signal = AbortSignal.timeout(PORTFOLIO_TIMEOUT_MS);
   let res;
@@ -896,7 +919,7 @@ async function fetchPortfolioFromBlockVision(address, apiKey) {
         headers: { "x-api-key": apiKey, accept: "application/json" },
         signal
       },
-      { signal }
+      { signal, retryStats }
     );
   } catch (err) {
     console.warn("[blockvision-prices] portfolio fetch threw, degrading:", err);
@@ -982,7 +1005,7 @@ async function fetchPortfolioFromSuiRpc(address, apiKey, fallbackRpcUrl) {
     source: "sui-rpc-degraded"
   };
 }
-async function fetchTokenPrices(coinTypes, apiKey) {
+async function fetchTokenPrices(coinTypes, apiKey, opts = {}) {
   if (coinTypes.length === 0) return {};
   const now = Date.now();
   const cacheValid = priceMapCache !== null && now - priceMapCache.ts < CACHE_TTL_MS;
@@ -1006,7 +1029,7 @@ async function fetchTokenPrices(coinTypes, apiKey) {
   if (!apiKey || apiKey.trim().length === 0) {
     return result;
   }
-  const fetched = await fetchPricesFromBlockVision(stillMissing, apiKey);
+  const fetched = await fetchPricesFromBlockVision(stillMissing, apiKey, opts.retryStats);
   Object.assign(result, fetched);
   const cacheUpdates = {};
   for (const [original, value] of Object.entries(fetched)) {
@@ -1016,7 +1039,7 @@ async function fetchTokenPrices(coinTypes, apiKey) {
   priceMapCache = { prices: merged, ts: cacheValid ? priceMapCache.ts : now };
   return result;
 }
-async function fetchPricesFromBlockVision(coinTypes, apiKey) {
+async function fetchPricesFromBlockVision(coinTypes, apiKey, retryStats) {
   const out = {};
   const longToOriginal = /* @__PURE__ */ new Map();
   for (const original of coinTypes) {
@@ -1037,7 +1060,7 @@ async function fetchPricesFromBlockVision(coinTypes, apiKey) {
           headers: { "x-api-key": apiKey, accept: "application/json" },
           signal
         },
-        { signal }
+        { signal, retryStats }
       );
     } catch (err) {
       console.warn("[blockvision-prices] price chunk threw, skipping:", err);
@@ -1123,7 +1146,7 @@ async function safeDefiStoreGet(store, address) {
   }
 }
 var warnedMissingApiKey = false;
-async function fetchAddressDefiPortfolio(address, apiKey, priceHints = {}) {
+async function fetchAddressDefiPortfolio(address, apiKey, priceHints = {}, opts = {}) {
   if (!apiKey || apiKey.trim().length === 0) {
     if (!warnedMissingApiKey) {
       warnedMissingApiKey = true;
@@ -1164,7 +1187,7 @@ async function fetchAddressDefiPortfolio(address, apiKey, priceHints = {}) {
           const stickyBasis = recheck ?? cachedEntry;
           const fanoutAt = Date.now();
           const settled = await Promise.allSettled(
-            DEFI_PROTOCOLS.map((p) => fetchOneDefiProtocol(address, p, apiKey))
+            DEFI_PROTOCOLS.map((p) => fetchOneDefiProtocol(address, p, apiKey, opts.retryStats))
           );
           const seen = /* @__PURE__ */ new Set();
           for (const s of settled) {
@@ -1259,7 +1282,7 @@ async function fetchAddressDefiPortfolio(address, apiKey, priceHints = {}) {
   defiInflight.set(address, inflight);
   return inflight;
 }
-async function fetchOneDefiProtocol(address, protocol, apiKey) {
+async function fetchOneDefiProtocol(address, protocol, apiKey, retryStats) {
   const url = `${BLOCKVISION_BASE}/account/defiPortfolio?address=${encodeURIComponent(address)}&protocol=${protocol}`;
   const signal = AbortSignal.timeout(DEFI_PORTFOLIO_TIMEOUT_MS);
   let res;
@@ -1270,7 +1293,7 @@ async function fetchOneDefiProtocol(address, protocol, apiKey) {
         headers: { "x-api-key": apiKey, accept: "application/json" },
         signal
       },
-      { signal }
+      { signal, retryStats }
     );
   } catch (err) {
     console.warn(`[defi] ${protocol} fetch threw:`, err);
@@ -1810,12 +1833,12 @@ async function applyVsuiPriceFallback(portfolio) {
     portfolio.totalUsd = portfolio.totalUsd - previousUsd + usdValue;
   }
 }
-async function loadPortfolio(address, blockvisionApiKey, fallbackRpcUrl, cache) {
+async function loadPortfolio(address, blockvisionApiKey, fallbackRpcUrl, cache, retryStats) {
   if (cache) {
     const hit = cache.get(address);
     if (hit) return hit;
   }
-  const portfolio = await fetchAddressPortfolio(address, blockvisionApiKey, fallbackRpcUrl);
+  const portfolio = await fetchAddressPortfolio(address, blockvisionApiKey, fallbackRpcUrl, { retryStats });
   if (cache) cache.set(address, portfolio);
   return portfolio;
 }
@@ -1874,7 +1897,8 @@ var balanceCheckTool = buildTool({
           address,
           context.blockvisionApiKey,
           context.suiRpcUrl,
-          context.portfolioCache
+          context.portfolioCache,
+          context.retryStats
         ).catch((err) => {
           console.warn("[balance_check] portfolio fetch failed, returning empty:", err);
           const fallback = {
@@ -1906,7 +1930,7 @@ var balanceCheckTool = buildTool({
         // as defi.totalUsd === 0 and `source: 'degraded'`, leaving the
         // rest of balance_check unaffected. The fetcher fills its own
         // prices via fetchTokenPrices for any coin types it discovers.
-        fetchAddressDefiPortfolio(address, context.blockvisionApiKey).catch((err) => {
+        fetchAddressDefiPortfolio(address, context.blockvisionApiKey, {}, { retryStats: context.retryStats }).catch((err) => {
           console.warn("[balance_check] defi fetch failed:", err);
           const fallback = {
             totalUsd: 0,
@@ -2023,7 +2047,7 @@ var balanceCheckTool = buildTool({
     const fetchAddress = targetAddress ?? context.walletAddress;
     const [balance, defi] = await Promise.all([
       agent.balance(),
-      fetchAddressDefiPortfolio(fetchAddress, context.blockvisionApiKey).catch((err) => {
+      fetchAddressDefiPortfolio(fetchAddress, context.blockvisionApiKey, {}, { retryStats: context.retryStats }).catch((err) => {
         console.warn("[balance_check] sdk-path defi fetch failed:", err);
         const fallback = {
           totalUsd: 0,
@@ -3986,7 +4010,8 @@ var portfolioAnalysisTool = buildTool({
         const fresh = await fetchAddressPortfolio(
           address,
           context.blockvisionApiKey,
-          context.suiRpcUrl
+          context.suiRpcUrl,
+          { retryStats: context.retryStats }
         );
         context.portfolioCache?.set(address, fresh);
         return fresh;
@@ -4036,7 +4061,7 @@ var portfolioAnalysisTool = buildTool({
         perProtocol: {},
         pricedAt: Date.now(),
         source: audricSnapshot.defiSource
-      }) : fetchAddressDefiPortfolio(address, context.blockvisionApiKey).catch(
+      }) : fetchAddressDefiPortfolio(address, context.blockvisionApiKey, {}, { retryStats: context.retryStats }).catch(
         (err) => {
           console.warn("[portfolio_analysis] defi fetch failed:", err);
           return { totalUsd: 0, perProtocol: {}, pricedAt: Date.now(), source: "degraded" };
@@ -5229,7 +5254,7 @@ var tokenPricesTool = buildTool({
   },
   isReadOnly: true,
   async call(input, context) {
-    const prices = await fetchTokenPrices(input.coinTypes, context.blockvisionApiKey);
+    const prices = await fetchTokenPrices(input.coinTypes, context.blockvisionApiKey, { retryStats: context.retryStats });
     const results = input.coinTypes.map((coinType) => {
       const entry = prices[coinType];
       const symbol = coinType.split("::").pop() ?? coinType;
@@ -6498,12 +6523,14 @@ var EarlyToolDispatcher = class {
           call,
           tool,
           promise: Promise.resolve({ data: cached.result, isError: false }),
-          deduped: true
+          deduped: true,
+          readAttemptCount: () => void 0
         });
         return true;
       }
     }
-    const childContext = { ...this.context, signal: this.abortController.signal };
+    const baseChildContext = { ...this.context, signal: this.abortController.signal };
+    const { context: childContext, readAttemptCount } = withRetryStats(baseChildContext);
     const promise = executeTool(tool, call, childContext).then((result) => {
       if (!result.isError && this.turnReadCache) {
         const cacheKey = TurnReadCache.keyFor(call.name, call.input);
@@ -6514,7 +6541,7 @@ var EarlyToolDispatcher = class {
       }
       return result;
     });
-    this.entries.push({ call, tool, promise, deduped: false });
+    this.entries.push({ call, tool, promise, deduped: false, readAttemptCount });
     return true;
   }
   /** True if any tools have been dispatched. */
@@ -6543,6 +6570,7 @@ var EarlyToolDispatcher = class {
       try {
         const result = await entry.promise;
         const budgeted = result.isError ? result.data : budgetToolResult(result.data, entry.tool);
+        const attemptCount = entry.readAttemptCount();
         yield {
           type: "tool_result",
           toolName: entry.call.name,
@@ -6550,7 +6578,8 @@ var EarlyToolDispatcher = class {
           result: budgeted,
           isError: result.isError,
           wasEarlyDispatched: true,
-          ...entry.deduped ? { resultDeduped: true } : {}
+          ...entry.deduped ? { resultDeduped: true } : {},
+          ...attemptCount !== void 0 ? { attemptCount } : {}
         };
       } catch (err) {
         yield {
@@ -6684,8 +6713,17 @@ var QueryEngine = class {
    * `pending_action` event and the stream ends — no persistent connection needed.
    * The caller should save messages + pendingAction to the session store, then
    * call `resumeWithToolResult()` after the user approves/denies and executes.
+   *
+   * [SPEC 8 v0.5.1 B3.2] Optional `options.harnessShape` + `options.harnessRationale`
+   * cause a one-shot `harness_shape` event to be yielded BEFORE the agent loop
+   * begins. The engine itself doesn't classify — the host calls
+   * `classifyEffort()` (host already does this for thinking-budget routing)
+   * and maps via `harnessShapeForEffort()` before calling `submitMessage`.
+   * Hosts that don't pass `harnessShape` won't see the event (existing
+   * pre-SPEC-8 hosts continue to work; their `TurnMetrics.harnessShape`
+   * defaults to `'legacy'`).
    */
-  async *submitMessage(prompt) {
+  async *submitMessage(prompt, options) {
     if (this.costTracker.isOverBudget()) {
       yield { type: "error", error: new Error("Session budget exceeded") };
       return;
@@ -6697,6 +6735,13 @@ var QueryEngine = class {
       role: "user",
       content: [{ type: "text", text: prompt }]
     });
+    if (options?.harnessShape) {
+      yield {
+        type: "harness_shape",
+        shape: options.harnessShape,
+        rationale: options.harnessRationale && options.harnessRationale.trim().length > 0 ? options.harnessRationale : `host-classified ${options.harnessShape}`
+      };
+    }
     this.turnPaused = false;
     try {
       yield* this.agentLoop(prompt, signal);
@@ -6823,11 +6868,19 @@ var QueryEngine = class {
               isError: true,
               data: {
                 error: `Post-write refresh: invalid input for ${tool.name}`
-              }
+              },
+              attemptCount: void 0
             };
           }
-          const result = await tool.call(parsed.data, context);
-          return { tool, id, isError: false, data: result.data };
+          const { context: toolCtx, readAttemptCount } = withRetryStats(context);
+          const result = await tool.call(parsed.data, toolCtx);
+          return {
+            tool,
+            id,
+            isError: false,
+            data: result.data,
+            attemptCount: readAttemptCount()
+          };
         } catch (err) {
           return {
             tool,
@@ -6835,7 +6888,8 @@ var QueryEngine = class {
             isError: true,
             data: {
               error: err instanceof Error ? err.message : "Post-write refresh failed"
-            }
+            },
+            attemptCount: void 0
           };
         }
       })
@@ -6867,7 +6921,8 @@ var QueryEngine = class {
         toolUseId: r.id,
         result: r.data,
         isError: r.isError,
-        wasPostWriteRefresh: true
+        wasPostWriteRefresh: true,
+        ...r.attemptCount !== void 0 ? { attemptCount: r.attemptCount } : {}
       };
     }
   }
@@ -7702,6 +7757,20 @@ function flagSuspiciousResult(toolName, result) {
   return null;
 }
 
+// src/types.ts
+function harnessShapeForEffort(effort) {
+  switch (effort) {
+    case "low":
+      return "lean";
+    case "medium":
+      return "standard";
+    case "high":
+      return "rich";
+    case "max":
+      return "max";
+  }
+}
+
 // src/streaming.ts
 function serializeSSE(event) {
   const data = JSON.stringify(event);
@@ -8788,6 +8857,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, EFFORT_THINKING_BUDGET_CAPS, EarlyToolDispatcher, InMemoryDefiCacheStore, InMemoryFetchLock, InMemoryNaviCacheStore, InMemoryWalletCacheStore, InvalidAddressError, 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, RecipeRegistry, RetryTracker, SUINS_NAME_REGEX, SUI_ADDRESS_REGEX, SUI_ADDRESS_STRICT_REGEX, SuinsNotRegisteredError, SuinsRpcError, TOOL_FLAGS, TOOL_MODIFIABLE_FIELDS, TxMutex, WRITE_TOOLS, _resetNaviCircuitBreaker, activitySummaryTool, adaptAllMcpTools, adaptAllServerTools, adaptMcpTool, applyToolFlags, awaitOrFetch, balanceCheckTool, borrowTool, budgetToolResult, buildCachedSystemPrompt, buildMcpTools, buildProactivenessInstructions, buildProfileContext, buildSelfEvaluationInstruction, buildStateContext, buildTool, claimRewardsTool, clampThinkingForEffort, classifyEffort, clearPortfolioCache, clearPortfolioCacheFor, clearPriceMapCache, compactMessages, createGuardRunnerState, engineToSSE, estimateTokens, explainTxTool, extractConversationText, extractMcpText, 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, hasNaviMcp, healthCheckTool, loadRecipes, looksLikeSuiNs, microcompact, mppServicesTool, naviKey, normalizeAddressInput, parseEvalSummary, parseMcpJson, parseRecipe, parseSSE, payApiTool, portfolioAnalysisTool, protocolDeepDiveTool, ratesInfoTool, 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, 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, EFFORT_THINKING_BUDGET_CAPS, EarlyToolDispatcher, InMemoryDefiCacheStore, InMemoryFetchLock, InMemoryNaviCacheStore, InMemoryWalletCacheStore, InvalidAddressError, 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, RecipeRegistry, RetryTracker, SUINS_NAME_REGEX, SUI_ADDRESS_REGEX, SUI_ADDRESS_STRICT_REGEX, SuinsNotRegisteredError, SuinsRpcError, TOOL_FLAGS, TOOL_MODIFIABLE_FIELDS, TxMutex, WRITE_TOOLS, _resetNaviCircuitBreaker, activitySummaryTool, adaptAllMcpTools, adaptAllServerTools, adaptMcpTool, applyToolFlags, awaitOrFetch, balanceCheckTool, borrowTool, budgetToolResult, buildCachedSystemPrompt, buildMcpTools, buildProactivenessInstructions, buildProfileContext, buildSelfEvaluationInstruction, buildStateContext, buildTool, claimRewardsTool, clampThinkingForEffort, classifyEffort, clearPortfolioCache, clearPortfolioCacheFor, clearPriceMapCache, compactMessages, createGuardRunnerState, engineToSSE, estimateTokens, explainTxTool, extractConversationText, extractMcpText, 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, loadRecipes, looksLikeSuiNs, microcompact, mppServicesTool, naviKey, normalizeAddressInput, parseEvalSummary, parseMcpJson, parseRecipe, parseSSE, payApiTool, portfolioAnalysisTool, protocolDeepDiveTool, ratesInfoTool, 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, 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