@t2000/engine 1.3.0 → 1.4.0

package/README.md

@@ -261,8 +261,11 @@ The `submitMessage()` async generator yields `EngineEvent`:
 | Event | Fields | When |
 |-------|--------|------|
 | `text_delta` | `text` | LLM streams a text chunk |
-| `thinking_delta` | `text` | Extended thinking chunk (reasoning accordion) |
-| `thinking_done` | — | Extended thinking complete |
+| `thinking_delta` | `text`, `blockIndex` | Extended thinking chunk (reasoning accordion). **`blockIndex`** identifies which thinking block this delta belongs to so hosts can render multi-block thinking chronologically (Anthropic streams ≥1 thinking blocks per turn at high effort). |
+| `thinking_done` | `blockIndex`, `signature?`, `summaryMode?`, `evaluationItems?` | Extended thinking block complete. `blockIndex` matches the `thinking_delta` events for that block. **`summaryMode`** flips true and **`evaluationItems`** is populated when the block contained a parseable `<eval_summary>` marker — hosts render `HowIEvaluatedBlock` ("✦ HOW I EVALUATED THIS") from these fields. |
+| `todo_update` | `items`, `toolUseId` | **[SPEC 8 v0.5.1]** Side-channel event paired to every `update_todo` tool call. `items` is the full `TodoItem[]` array; hosts unconditionally replace their rendered list (the tool is idempotent). `toolUseId` keys the render to the originating call. |
+| `tool_progress` | `toolUseId`, `toolName`, `message`, `pct?` | **[SPEC 8 v0.5.1]** Mid-execution progress signal from long-running tools (Cetus swap, protocol_deep_dive, portfolio_analysis). Tools opt in via `context.progress?.(msg, pct?)`. Engine wiring lands with the Cetus SDK integration in a follow-on slice. |
+| `pending_input` | `schema`, `inputId`, `prompt?` | **[SPEC 8 v0.5.1, D2]** Reserved for SPEC 9 v0.1.2 inline forms. Engine doesn't emit under SPEC 8 — host adds a no-op handler now to avoid crashing when SPEC 9 ships emission. |
 | `tool_start` | `toolName`, `toolUseId`, `input` | Tool execution begins |
 | `tool_result` | `toolName`, `toolUseId`, `result`, `isError` | Tool execution completes |
 | `pending_action` | `action` (PendingAction with `attemptId`, `toolUseId`, `turnIndex`, `name`, `input`) | Write tool awaiting client-side execution. `attemptId` is a per-yield UUID — hosts persist it on TurnMetrics and key the resume `updateMany` on it (avoids ambiguous `(sessionId, turnIndex)` updates) |

package/dist/index.d.ts

@@ -584,6 +584,34 @@ declare function toolNameToOperation(toolName: string): PermissionOperation | un
  */
 declare function resolveUsdValue(toolName: string, input: Record<string, unknown>, priceCache: Map<string, number>): number;
 
+type EvaluationStatus = 'good' | 'warning' | 'critical' | 'info';
+interface EvaluationItem {
+    label: string;
+    status: EvaluationStatus;
+    note?: string;
+}
+interface EvalSummaryParseResult {
+    /** Always true when this object is returned (vs null when absent). */
+    summaryMode: true;
+    /** The structured rows the host renders inside the trust card. */
+    evaluationItems: EvaluationItem[];
+    /** Count of markers detected — >1 indicates an LLM compliance violation. */
+    markerCount: number;
+}
+/**
+ * Scan a thinking-block text for one or more `<eval_summary>` markers.
+ *
+ * - Returns null when no marker is present, or when the first marker's
+ *   JSON is malformed (host falls back to standard rendering).
+ * - Returns a parsed result when at least one marker contains valid JSON.
+ *   `markerCount` reflects the total number of markers seen so the
+ *   engine can emit a `evalSummaryViolationsCount` telemetry counter
+ *   when N > 1 (LLM is supposed to emit at most one per turn).
+ *
+ * The function is pure — safe to call per-thinking-block.
+ */
+declare function parseEvalSummary(thinkingText: string): EvalSummaryParseResult | null;
+
 type ContentBlock = {
     type: 'text';
     text: string;
@@ -609,12 +637,34 @@ interface Message {
     role: 'user' | 'assistant';
     content: ContentBlock[];
 }
-type EngineEvent = {
+type EngineEvent = 
+/**
+ * [SPEC 8 v0.5.1] `blockIndex` identifies which thinking block this delta
+ * belongs to. Anthropic streams multi-block thinking with rising indices
+ * across each turn (block 0, 1, 2, ...). Hosts use this to render
+ * chronologically interleaved thinking accordions instead of flattening
+ * every delta into one string. Backwards-compatible: older hosts that
+ * ignore the field still see deltas in emission order.
+ */
+{
     type: 'thinking_delta';
     text: string;
-} | {
+    blockIndex: number;
+}
+/**
+ * [SPEC 8 v0.5.1] When the thinking block contained a parseable
+ * `<eval_summary>...</eval_summary>` marker, `summaryMode` flips true
+ * and `evaluationItems` carries the structured rows. Hosts render the
+ * `HowIEvaluatedBlock` ("✦ HOW I EVALUATED THIS") trust card from
+ * these fields. Both undefined when the block had no marker (every
+ * read-only and most write turns).
+ */
+ | {
     type: 'thinking_done';
+    blockIndex: number;
     signature?: string;
+    summaryMode?: boolean;
+    evaluationItems?: EvaluationItem[];
 } | {
     type: 'text_delta';
     text: string;
@@ -682,7 +732,70 @@ type EngineEvent = {
  */
  | {
     type: 'compaction';
+}
+/**
+ * [SPEC 8 v0.5.1] Side-channel event paired to every `update_todo` tool
+ * call. Hosts render the persistent todo card from this event (NOT from
+ * the tool_result — see `tools/update-todo.ts` § "side-channel" for
+ * rationale). Carries the full items array so the host can
+ * unconditionally replace its rendered list (the tool is idempotent —
+ * each call replaces the previous state). `toolUseId` lets the host
+ * key the render cell to the originating tool call.
+ */
+ | {
+    type: 'todo_update';
+    items: TodoItem$1[];
+    toolUseId: string;
+}
+/**
+ * [SPEC 8 v0.5.1] Mid-execution progress signal from a long-running tool
+ * (Cetus swap_execute 2-5s, protocol_deep_dive 3-8s, portfolio_analysis
+ * 1-2s). Tools opt in by calling `context.progress?.(msg, pct?)` from
+ * inside their `call` implementation. Hosts render the message + bar
+ * inside the corresponding tool block's spinner — kills the dead-air
+ * static-spinner UX that's the explicit SPEC 8 v0.3 fix target.
+ *
+ * Engine wiring (queue-and-yield in the dispatcher) lands with the
+ * Cetus integration in a follow-on slice. SPEC 8 v0.5.1 reserves the
+ * event type now so hosts can pre-wire the renderer.
+ *
+ * `pct` is 0–100 when the tool can express progress quantitatively,
+ * undefined otherwise (free-text status only).
+ */
+ | {
+    type: 'tool_progress';
+    toolUseId: string;
+    toolName: string;
+    message: string;
+    pct?: number;
+}
+/**
+ * [SPEC 8 v0.5.1, D2] Inline-form structured input event reserved for
+ * SPEC 9 v0.1.2 (`pending_input` form primitive). The engine does NOT
+ * emit this event under SPEC 8 — the type is reserved so legacy hosts
+ * can add a no-op handler now and avoid crashing when SPEC 9 ships
+ * `pending_input` emission. See SPEC 8 § "v0.5 cross-spec coupling
+ * fixes" — gap D2 — for the forward-compat rationale.
+ */
+ | {
+    type: 'pending_input';
+    /** Form schema (shape locked in SPEC 9 v0.1.2; engine treats it opaquely). */
+    schema: unknown;
+    /** Engine round-trip identifier — host posts the answer back keyed on this. */
+    inputId: string;
+    /** Optional human-readable prompt the LLM wants the host to display above the form. */
+    prompt?: string;
 };
+/**
+ * [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
+ * consume `EngineEvent` don't need to depend on the tool module.
+ */
+interface TodoItem$1 {
+    id: string;
+    label: string;
+    status: 'pending' | 'in_progress' | 'completed';
+}
 type StopReason = 'end_turn' | 'tool_use' | 'max_tokens' | 'max_turns' | 'error';
 /**
  * [v1.4 Item 6] Describes a single input field on a `PendingAction` that
@@ -1057,10 +1170,14 @@ interface ToolDefinition {
 type ProviderEvent = {
     type: 'thinking_delta';
     text: string;
+    blockIndex: number;
 } | {
     type: 'thinking_done';
+    blockIndex: number;
     thinking: string;
     signature: string;
+    summaryMode?: boolean;
+    evaluationItems?: EvaluationItem[];
 } | {
     type: 'redacted_thinking';
     data: string;
@@ -1276,9 +1393,13 @@ declare function findTool(tools: Tool[], name: string): Tool | undefined;
 type SSEEvent = {
     type: 'thinking_delta';
     text: string;
+    blockIndex: number;
 } | {
     type: 'thinking_done';
+    blockIndex: number;
     signature?: string;
+    summaryMode?: boolean;
+    evaluationItems?: EvaluationItem[];
 } | {
     type: 'text_delta';
     text: string;
@@ -1317,6 +1438,21 @@ type SSEEvent = {
     data: unknown;
     title: string;
     toolUseId: string;
+} | {
+    type: 'todo_update';
+    items: TodoItem$1[];
+    toolUseId: string;
+} | {
+    type: 'tool_progress';
+    toolUseId: string;
+    toolName: string;
+    message: string;
+    pct?: number;
+} | {
+    type: 'pending_input';
+    schema: unknown;
+    inputId: string;
+    prompt?: string;
 };
 declare function serializeSSE(event: SSEEvent): string;
 declare function parseSSE(raw: string): SSEEvent | null;
@@ -1392,6 +1528,24 @@ declare function getToolFlags(name: string): ToolFlags;
  */
 declare function classifyEffort(model: string, userMessage: string, matchedRecipe: Recipe | null, sessionWriteCount: number): ThinkingEffort;
 
+declare const EFFORT_THINKING_BUDGET_CAPS: Record<ThinkingEffort, number | null>;
+/**
+ * Clamp a `ThinkingConfig` to the HARD cap for the given effort tier.
+ *
+ * - When `effort === 'low'`, returns `{ type: 'disabled' }` regardless of
+ *   input — LEAN tier is non-negotiable.
+ * - When `config.type === 'enabled'` and `config.budgetTokens` exceeds
+ *   the cap, returns a copy with `budgetTokens` clamped down.
+ * - When `config.type === 'adaptive'`, returns it unchanged — adaptive
+ *   mode is shape-agnostic by design (Anthropic decides per-turn).
+ * - When `effort` is undefined, returns `config` unchanged — caller
+ *   hasn't classified the turn yet (back-compat for hosts that don't
+ *   route on effort).
+ *
+ * This function is pure and side-effect-free; safe to call per-turn.
+ */
+declare function clampThinkingForEffort(config: ThinkingConfig | undefined, effort: ThinkingEffort | undefined): ThinkingConfig | undefined;
+
 /**
  * Build a cacheable system prompt array from static and dynamic parts.
  *
@@ -2435,6 +2589,63 @@ declare const resolveSuinsTool: Tool<{
     query: string;
 }, ResolveSuinsResult>;
 
+declare const todoItemSchema: z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodString;
+    status: z.ZodEnum<["pending", "in_progress", "completed"]>;
+}, "strip", z.ZodTypeAny, {
+    label: string;
+    status: "pending" | "in_progress" | "completed";
+    id: string;
+}, {
+    label: string;
+    status: "pending" | "in_progress" | "completed";
+    id: string;
+}>;
+declare const inputSchema: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+        status: z.ZodEnum<["pending", "in_progress", "completed"]>;
+    }, "strip", z.ZodTypeAny, {
+        label: string;
+        status: "pending" | "in_progress" | "completed";
+        id: string;
+    }, {
+        label: string;
+        status: "pending" | "in_progress" | "completed";
+        id: string;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    items: {
+        label: string;
+        status: "pending" | "in_progress" | "completed";
+        id: string;
+    }[];
+}, {
+    items: {
+        label: string;
+        status: "pending" | "in_progress" | "completed";
+        id: string;
+    }[];
+}>;
+type TodoItem = z.infer<typeof todoItemSchema>;
+type UpdateTodoInput = z.infer<typeof inputSchema>;
+declare const updateTodoTool: Tool<{
+    items: {
+        label: string;
+        status: "pending" | "in_progress" | "completed";
+        id: string;
+    }[];
+}, {
+    __todoUpdate: boolean;
+    items: {
+        label: string;
+        status: "pending" | "in_progress" | "completed";
+        id: string;
+    }[];
+}>;
+
 declare const tokenPricesTool: Tool<{
     coinTypes: string[];
     include24hChange?: boolean | undefined;
@@ -3020,4 +3231,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, EarlyToolDispatcher, type EngineConfig, type EngineEvent, 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 Tool, type ToolChoice, type ToolContext, type ToolDefinition, type ToolFlags, type ToolJsonSchema, type ToolResult, TxMutex, 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, 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, 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, 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 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 };

package/dist/index.js

@@ -5104,6 +5104,107 @@ var resolveSuinsTool = buildTool({
     }
   }
 });
+var todoStatusSchema = z.enum(["pending", "in_progress", "completed"]);
+var todoItemSchema = z.object({
+  id: z.string().min(1, "id must be a non-empty string").max(40, "id must be \u226440 chars (use a slug, not a sentence)"),
+  label: z.string().min(1, "label must be a non-empty string").max(80, "label must be \u226480 chars (the whole point of this tool is concision)"),
+  status: todoStatusSchema
+});
+var inputSchema6 = z.object({
+  items: z.array(todoItemSchema).min(1, "items must contain at least 1 entry").max(8, "items must contain at most 8 entries (SPEC 8 ceiling)")
+});
+var updateTodoTool = buildTool({
+  name: "update_todo",
+  description: "Declare or replace your plan for the current turn as a structured todo list. Call this when the user's ask is multi-step (\u22653 tools, \u22652 reasoning hops) so the user can see what you're doing as you do it. Each call replaces the entire list \u2014 the tool is idempotent. \n\nRules: 1\u20138 items, each label \u226480 chars, exactly 1 item must be `in_progress`. Use stable `id`s across calls within the same turn so the UI can track item transitions (e.g. `id: 'check-balance'` first as `pending`, later as `completed`). \n\nDO NOT call this for single-step asks ('balance', 'rate') \u2014 it's wasted tokens. DO call it before kicking off long flows where the user benefits from seeing the plan unfold ('save my idle USDC' \u2192 check balance \u2192 check rates \u2192 compute split \u2192 propose). \n\nThis call doesn't count against your turn budget \u2014 re-narrating the plan as items move from pending \u2192 in_progress \u2192 completed is encouraged.",
+  inputSchema: inputSchema6,
+  jsonSchema: {
+    type: "object",
+    properties: {
+      items: {
+        type: "array",
+        minItems: 1,
+        maxItems: 8,
+        items: {
+          type: "object",
+          properties: {
+            id: {
+              type: "string",
+              description: 'Stable identifier across calls within the same turn (e.g. "check-balance"). \u226440 chars.'
+            },
+            label: {
+              type: "string",
+              description: 'What this step is doing, \u226480 chars. Concrete (e.g. "Check USDC rate") not abstract ("Gather data").'
+            },
+            status: {
+              type: "string",
+              enum: ["pending", "in_progress", "completed"],
+              description: "Lifecycle state. Exactly one item must be `in_progress` per call."
+            }
+          },
+          required: ["id", "label", "status"]
+        }
+      }
+    },
+    required: ["items"]
+  },
+  isReadOnly: true,
+  // No I/O, just a pass-through that emits a side-channel event. Skip the
+  // turn-read cache — every call is intentionally distinct (ids may match
+  // but statuses change).
+  cacheable: false,
+  preflight: (input) => {
+    const items = input.items ?? [];
+    if (items.length === 0) {
+      return { valid: false, error: "items must contain at least 1 entry" };
+    }
+    if (items.length > 8) {
+      return { valid: false, error: `items must contain at most 8 entries, got ${items.length}` };
+    }
+    const seenIds = /* @__PURE__ */ new Set();
+    let inProgressCount = 0;
+    for (const item of items) {
+      if (!item.id || item.id.trim().length === 0) {
+        return { valid: false, error: "every item must have a non-empty id" };
+      }
+      if (item.id.length > 40) {
+        return { valid: false, error: `item id "${item.id.slice(0, 30)}\u2026" exceeds 40 chars` };
+      }
+      if (seenIds.has(item.id)) {
+        return { valid: false, error: `duplicate item id "${item.id}" \u2014 ids must be unique within a list` };
+      }
+      seenIds.add(item.id);
+      if (!item.label || item.label.trim().length === 0) {
+        return { valid: false, error: `item "${item.id}" has empty label` };
+      }
+      if (item.label.length > 80) {
+        return { valid: false, error: `item "${item.id}" label exceeds 80 chars (got ${item.label.length})` };
+      }
+      if (item.status === "in_progress") {
+        inProgressCount++;
+      }
+    }
+    if (inProgressCount !== 1) {
+      return {
+        valid: false,
+        error: `exactly 1 item must be in_progress, got ${inProgressCount}`
+      };
+    }
+    return { valid: true };
+  },
+  async call(input) {
+    return {
+      // The `__todoUpdate` flag tells the engine's agent loop to emit a
+      // `todo_update` side-channel event (mirrors the `__canvas` magic
+      // flag pattern). The LLM still gets a normal `tool_result` keyed
+      // to its `tool_use_id` so the Anthropic protocol stays satisfied.
+      data: {
+        __todoUpdate: true,
+        items: input.items
+      },
+      displayText: `${input.items.length} step${input.items.length === 1 ? "" : "s"}: ${input.items.map((i) => `${i.status === "completed" ? "\u2713" : i.status === "in_progress" ? "\u2192" : "\xB7"} ${i.label}`).join(" / ")}`
+    };
+  }
+});
 var tokenPricesTool = buildTool({
   name: "token_prices",
   description: 'Get current USD prices for Sui tokens, with optional 24h change. Accepts full coin type strings (e.g. "0x2::sui::SUI"). Returns price per token and (when requested) 24h change percentage. Use for "what is X worth?" or "did Y move today?". For balance + portfolio rendering, prefer balance_check / portfolio_analysis instead \u2014 they bundle the same prices into the standard cards.',
@@ -5350,6 +5451,29 @@ var CostTracker = class {
   }
 };
 
+// src/thinking-budget.ts
+var EFFORT_THINKING_BUDGET_CAPS = {
+  // null = thinking force-disabled (LEAN tier — single-fact reads need
+  // zero deliberation; a thinking block here adds ~300ms TTFVP for no
+  // benefit — see SPEC 8 § "Decision 2: LEAN shape: zero thinking blocks")
+  low: null,
+  medium: 8e3,
+  high: 16e3,
+  max: 32e3
+};
+function clampThinkingForEffort(config, effort) {
+  if (!config) return config;
+  if (effort === void 0) return config;
+  const cap = EFFORT_THINKING_BUDGET_CAPS[effort];
+  if (cap === null) {
+    return { type: "disabled" };
+  }
+  if (config.type === "enabled" && config.budgetTokens > cap) {
+    return { ...config, budgetTokens: cap };
+  }
+  return config;
+}
+
 // src/guards.ts
 function guardVerdictToAction(verdict) {
   if (verdict === "pass" || verdict === "hint") return "allow";
@@ -6940,6 +7064,7 @@ ${recipeCtx}`;
             ];
           }
         }
+        const cappedThinking = clampThinkingForEffort(this.thinking, this.outputConfig?.effort);
         const stream = this.provider.chat({
           messages: this.messages,
           systemPrompt: effectivePrompt,
@@ -6948,7 +7073,7 @@ ${recipeCtx}`;
           maxTokens: this.maxTokens,
           temperature: this.temperature,
           toolChoice: effectiveToolChoice,
-          thinking: this.thinking,
+          thinking: cappedThinking,
           outputConfig: this.outputConfig,
           signal
         });
@@ -7029,6 +7154,13 @@ ${recipeCtx}`;
                   toolUseId: finalEvent.toolUseId
                 };
               }
+              if (r && r.__todoUpdate === true && Array.isArray(r.items)) {
+                yield {
+                  type: "todo_update",
+                  items: r.items,
+                  toolUseId: finalEvent.toolUseId
+                };
+              }
             }
             earlyResultBlocks.push({
               type: "tool_result",
@@ -7225,6 +7357,13 @@ ${recipeCtx}`;
                 toolUseId: finalEvent.toolUseId
               };
             }
+            if (r && r.__todoUpdate === true && Array.isArray(r.items)) {
+              yield {
+                type: "todo_update",
+                items: r.items,
+                toolUseId: finalEvent.toolUseId
+              };
+            }
             if (tool && !tool.isReadOnly && this.onAutoExecuted && this.permissionConfig && this.priceCache) {
               const operation = toolNameToOperation(toolEvent.toolName);
               if (operation && originalCall) {
@@ -7316,6 +7455,11 @@ ${recipeCtx}`;
       }
       this.messages.push({ role: "assistant", content: acc.assistantBlocks });
       this.messages.push({ role: "user", content: toolResultBlocks });
+      const toolUseBlocks = acc.assistantBlocks.filter((b) => b.type === "tool_use");
+      const allUpdateTodo = toolUseBlocks.length > 0 && toolUseBlocks.every((b) => b.name === "update_todo");
+      if (allUpdateTodo) {
+        turns--;
+      }
       if (this.costTracker.isOverBudget()) {
         yield { type: "error", error: new Error("Session budget exceeded") };
         return;
@@ -7340,7 +7484,7 @@ ${recipeCtx}`;
   *handleProviderEvent(event, acc, dispatcher) {
     switch (event.type) {
       case "thinking_delta": {
-        yield { type: "thinking_delta", text: event.text };
+        yield { type: "thinking_delta", text: event.text, blockIndex: event.blockIndex };
         break;
       }
       case "thinking_done": {
@@ -7349,7 +7493,14 @@ ${recipeCtx}`;
           thinking: event.thinking,
           signature: event.signature
         });
-        yield { type: "thinking_done", signature: event.signature };
+        yield {
+          type: "thinking_done",
+          blockIndex: event.blockIndex,
+          signature: event.signature,
+          // [SPEC 8 v0.5.1] forward HowIEvaluated structured fields when
+          // the provider parsed an <eval_summary> marker.
+          ...event.summaryMode && event.evaluationItems ? { summaryMode: true, evaluationItems: event.evaluationItems } : {}
+        };
         break;
       }
       case "redacted_thinking": {
@@ -7785,6 +7936,54 @@ function classifyEffort(model, userMessage, matchedRecipe, sessionWriteCount) {
   return "medium";
 }
 
+// src/eval-summary.ts
+var MARKER_REGEX = /<eval_summary>([\s\S]*?)<\/eval_summary>/g;
+var VALID_STATUSES = /* @__PURE__ */ new Set([
+  "good",
+  "warning",
+  "critical",
+  "info"
+]);
+function parseEvalSummary(thinkingText) {
+  if (!thinkingText.includes("<eval_summary>")) return null;
+  const matches = [];
+  for (const match of thinkingText.matchAll(MARKER_REGEX)) {
+    matches.push(match[1] ?? "");
+  }
+  if (matches.length === 0) return null;
+  const firstPayload = matches[0].trim();
+  let parsed;
+  try {
+    parsed = JSON.parse(firstPayload);
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== "object") return null;
+  const items = parsed.items;
+  if (!Array.isArray(items)) return null;
+  const evaluationItems = [];
+  for (const item of items) {
+    if (!item || typeof item !== "object") continue;
+    const i = item;
+    if (typeof i.label !== "string" || i.label.trim().length === 0) continue;
+    if (typeof i.status !== "string" || !VALID_STATUSES.has(i.status)) continue;
+    const out = {
+      label: i.label,
+      status: i.status
+    };
+    if (typeof i.note === "string" && i.note.length > 0) {
+      out.note = i.note;
+    }
+    evaluationItems.push(out);
+  }
+  if (evaluationItems.length === 0) return null;
+  return {
+    summaryMode: true,
+    evaluationItems,
+    markerCount: matches.length
+  };
+}
+
 // src/prompt-cache.ts
 function buildCachedSystemPrompt(staticParts, dynamicPart) {
   const blocks = staticParts.map((text, i) => ({
@@ -8342,7 +8541,7 @@ var AnthropicProvider = class {
             } else if (delta.type === "thinking_delta") {
               const buf = thinkingBuffers.get(event.index);
               if (buf?.type === "thinking") buf.text += delta.thinking ?? "";
-              yield { type: "thinking_delta", text: delta.thinking ?? "" };
+              yield { type: "thinking_delta", text: delta.thinking ?? "", blockIndex: event.index };
             } else if (delta.type === "signature_delta") {
               const buf = thinkingBuffers.get(event.index);
               if (buf?.type === "thinking") buf.signature = delta.signature ?? "";
@@ -8368,7 +8567,14 @@ var AnthropicProvider = class {
             }
             const thinkBuf = thinkingBuffers.get(event.index);
             if (thinkBuf?.type === "thinking") {
-              yield { type: "thinking_done", thinking: thinkBuf.text, signature: thinkBuf.signature };
+              const summary = parseEvalSummary(thinkBuf.text);
+              yield {
+                type: "thinking_done",
+                blockIndex: event.index,
+                thinking: thinkBuf.text,
+                signature: thinkBuf.signature,
+                ...summary ? { summaryMode: true, evaluationItems: summary.evaluationItems } : {}
+              };
               thinkingBuffers.delete(event.index);
             } else if (thinkBuf?.type === "redacted_thinking") {
               yield { type: "redacted_thinking", data: thinkBuf.data };
@@ -8582,6 +8788,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, 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, 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, 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, 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, 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