@t2000/engine 1.17.1 → 1.19.0

package/dist/index.d.ts

@@ -5,6 +5,54 @@ import { Tool as Tool$1 } from '@modelcontextprotocol/sdk/types.js';
 import * as _t2000_sdk from '@t2000/sdk';
 import { T2000 } from '@t2000/sdk';
 
+type ProactiveType = 'idle_balance' | 'hf_warning' | 'apy_drift' | 'goal_progress';
+interface ProactiveMarker {
+    /** Allow-listed insight category (drives host icon/lockup variant). */
+    proactiveType: ProactiveType;
+    /** Stable per-subject key — engine uses (proactiveType, subjectKey) for cooldown. */
+    subjectKey: string;
+    /** Marker body with the wrapping tags stripped, trimmed of leading/trailing whitespace. */
+    body: string;
+    /** Total marker count detected — >1 indicates an LLM compliance violation. */
+    markerCount: number;
+}
+/**
+ * Scan completed final-text for one or more `<proactive>` markers.
+ *
+ * Returns null when no parseable marker exists. When at least one valid
+ * marker is found, returns the FIRST marker's payload + the total count
+ * (so the engine can emit `proactiveMarkerViolationsCount` telemetry
+ * when the LLM emitted >1 — the contract is at-most-one per turn).
+ *
+ * Pure function — safe to call per-text-block at content_block_stop.
+ */
+declare function parseProactiveMarker(text: string): ProactiveMarker | null;
+/**
+ * Strip every `<proactive ...>...</proactive>` wrapper from a text, leaving
+ * the body. Used by the engine's cooldown-suppression path: when the
+ * `(type, subjectKey)` was already seen in this session, the marker stays
+ * out of the rendered text but the body still reads cleanly.
+ *
+ * Idempotent — safe to call on text without markers.
+ */
+declare function stripProactiveMarkers(text: string): string;
+/**
+ * [SPEC 9 v0.1.1 P9.2 / R3] Yield every `(proactiveType, subjectKey)` pair
+ * present in `text`, in document order, regardless of whether the type is
+ * in the allow-list. Used by the engine's rehydration path on
+ * `loadMessages` to seed the per-session cooldown set from prior assistant
+ * blocks. Lenient (no `VALID_TYPES` filter) by design: extra cooldown
+ * entries for invalid types are inert because future valid emissions will
+ * never share the key, so seeding them costs nothing and keeps this helper
+ * decoupled from the emit-side validation policy.
+ *
+ * Returns `subjectKey` un-trimmed — caller is responsible for normalising.
+ */
+declare function extractAllProactiveMarkers(text: string): Array<{
+    proactiveType: string;
+    subjectKey: string;
+}>;
+
 /** Rough token count for a message array. */
 declare function estimateTokens(messages: Message[]): number;
 interface CompactOptions {
@@ -96,10 +144,10 @@ interface RecipeStep {
     cost_per_unit?: string;
     /**
      * [SPEC 7 P2.5 Layer 4] When true, this step is part of a multi-write
-     * Payment Stream bundle group. Steps with `bundle: true` MUST resolve
+     * Payment Intent compile group. Steps with `bundle: true` MUST resolve
      * to confirm-tier write tools that carry `bundleable: true` in
      * `TOOL_FLAGS` (validated at recipe load time). The loader fails fast
-     * on auto-tier writes / read-only tools / non-bundleable confirm tools
+     * on auto-tier writes / read-only tools / non-`bundleable` confirm tools
      * (`pay_api`, `save_contact`) inside a `bundle: true` group.
      *
      * The engine emits parallel `tool_use` blocks for `bundle: true`
@@ -153,6 +201,118 @@ declare function loadRecipes(yamlDir: string): Recipe[];
  */
 declare function parseRecipe(yamlContent: string): Recipe;
 
+/**
+ * Discriminator for the typed form-field kinds the host renderer supports.
+ * Closed list — adding a new kind requires a coordinated host-renderer +
+ * engine MINOR version bump.
+ */
+type FormFieldKind = 'text' | 'sui-recipient' | 'number' | 'usd' | 'select' | 'date';
+/**
+ * One row in a `pending_input` form. The host renderer keys on `kind` to
+ * pick the right input component.
+ */
+interface FormField {
+    /** Input key on the resumed-tool input object (e.g. `name`, `identifier`). */
+    name: string;
+    /** User-facing label rendered above the input. */
+    label: string;
+    /** Renderer discriminator — see `FormFieldKind` for the closed list. */
+    kind: FormFieldKind;
+    /** When true, the host blocks submit while the value is empty/null. */
+    required: boolean;
+    /** Optional grey-text guidance shown inside the empty input. */
+    placeholder?: string;
+    /** Optional help text rendered below the input (small font). */
+    helpText?: string;
+    /**
+     * Required for `kind: 'select'` — closed-set choices the user can pick.
+     * `value` is what gets sent back; `label` is what's rendered.
+     * Omitted (or empty) for non-select kinds — the host renderer ignores it.
+     */
+    options?: Array<{
+        value: string;
+        label: string;
+    }>;
+}
+/**
+ * Top-level form payload carried on `pending_input`.
+ */
+interface FormSchema {
+    /** Ordered list of fields the form renders top-to-bottom. */
+    fields: FormField[];
+}
+/**
+ * Engine-side state for a paused tool call awaiting user input. Stored on
+ * the QueryEngine instance keyed by `inputId` so the resume entry point
+ * can look up which tool to feed the values back into.
+ *
+ * Mirrors the (private) book-keeping the engine does for `pending_action`,
+ * but for the input-collection pause case rather than the user-confirm case.
+ *
+ * Identical shape to `PendingInput` (the wire payload) — alias kept for
+ * symmetry with `PendingAction` / "ActionState" naming elsewhere.
+ */
+type PendingInputState = PendingInput;
+/**
+ * Wire + state payload for a paused tool call awaiting user input.
+ *
+ * Carries BOTH the form-rendering fields (`inputId`, `schema`, etc) AND
+ * the conversation round-trip fields (`assistantContent`, `completedResults`)
+ * that the engine needs to atomically reconstruct the turn on resume.
+ *
+ * Hosts that store sessions across HTTP requests (e.g. audric) MUST
+ * persist the entire `PendingInput` payload — not just `inputId` — and
+ * pass it back as the first argument to `engine.resumeWithInput()`.
+ * Pattern mirrors `PendingAction.assistantContent` / `.completedResults`
+ * round-trip exactly.
+ *
+ * Why include the round-trip fields on the same payload:
+ * - Host's session schema only adds ONE new column for `pendingInput`
+ *   (instead of two: one for the wire fields + one for round-trip state).
+ * - The engine API surface stays small — `resumeWithInput(pendingInput, values)`.
+ * - Audric's existing pattern for `pendingAction` is the same shape, so
+ *   the reviewer can pattern-match.
+ *
+ * The host renderer ignores `assistantContent` / `completedResults` —
+ * they're opaque to the form UI. Only the engine reads them on resume.
+ */
+interface PendingInput {
+    /** UUID v4 stamped per-emit. Host posts back keyed on this. */
+    inputId: string;
+    /** Tool that requested the input. Useful for host debug logs / fallback caption. */
+    toolName: string;
+    /** Original `tool_use_id` from the LLM's call — the resumed tool_result block uses this id. */
+    toolUseId: string;
+    /** Typed form schema — host renderer keys on `field.kind` per row. */
+    schema: FormSchema;
+    /** Optional human-readable description rendered above the form (e.g. "Add a new contact"). */
+    description?: string;
+    /**
+     * Assistant message blocks captured at pause time — the LLM's
+     * `tool_use` blocks (including the one that triggered this pause) plus
+     * any thinking / text blocks from the same turn. Pushed back to
+     * `messages` atomically on `resumeWithInput` so the conversation stays
+     * well-formed (no orphan tool_use blocks in the persisted history).
+     *
+     * Typed as `unknown[]` here to avoid pulling `ContentBlock` into
+     * `pending-input.ts` and creating a type-import cycle through `types.ts`.
+     * The engine casts to `ContentBlock[]` on resume; hosts treat as opaque.
+     */
+    assistantContent: unknown[];
+    /**
+     * Tool results from reads that completed BEFORE the paused tool call
+     * (same turn). On resume the engine merges these with the resumed
+     * tool's result into ONE `user`-role message — keeps Anthropic's
+     * "every tool_use must have a tool_result in the next user message"
+     * invariant satisfied.
+     */
+    completedResults: Array<{
+        toolUseId: string;
+        content: string;
+        isError: boolean;
+    }>;
+}
+
 interface PendingToolCall {
     id: string;
     name: string;
@@ -192,6 +352,18 @@ interface GuardCheckResult {
     blockGate?: string;
     injections: GuardInjection[];
     events: GuardEvent[];
+    /**
+     * [SPEC 9 v0.1.3 P9.4] Set when the tool's preflight returned
+     * `needsInput` instead of either valid or error. The engine consults
+     * this BEFORE checking `blocked`: if present, the engine yields a
+     * `pending_input` event and pauses the turn. Distinct from `blocked`
+     * because the engine should NOT push a tool_result error back to the
+     * LLM — the turn is intentionally paused, not failed.
+     */
+    needsInput?: {
+        schema: FormSchema;
+        description?: string;
+    };
 }
 interface GuardEvent {
     timestamp: number;
@@ -786,6 +958,39 @@ type EngineEvent =
  | {
     type: 'compaction';
 }
+/**
+ * [SPEC 9 v0.1.1 P9.2] Proactive insight emitted by the LLM via a
+ * `<proactive type="..." subjectKey="...">BODY</proactive>` wrapper in
+ * the final-text block. Engine fires this event AFTER the matching
+ * text_delta stream has finished, once `parseProactiveMarker` has
+ * extracted the marker at content_block_stop on the text block AND
+ * the per-session cooldown check has run.
+ *
+ * `suppressed === false` (cold marker, first time seen this session)
+ * → host applies the `✦ ADDED BY AUDRIC` lockup styling on the matching
+ *   `text` TimelineBlock (italic body, dim border-left accent).
+ * `suppressed === true` (cooldown hit, same `(type, subjectKey)` already
+ *   fired this session) → host strips the wrapper from the displayed
+ *   text and renders as a regular text block — narrative still flows,
+ *   the visual lockup just doesn't fire twice.
+ *
+ * In both cases the streamed `text_delta` events still contain the raw
+ * marker chars (the engine doesn't buffer-and-rewrite mid-stream); the
+ * host applies marker stripping post-hoc using `body` from this event.
+ * Hosts that ignore this event render markers visibly — acceptable for
+ * legacy hosts as a graceful fallback.
+ */
+ | {
+    type: 'proactive_text';
+    proactiveType: 'idle_balance' | 'hf_warning' | 'apy_drift' | 'goal_progress';
+    subjectKey: string;
+    /** Marker body, trimmed. Host renders this inside the lockup (or as plain text when suppressed). */
+    body: string;
+    /** True when (proactiveType, subjectKey) was already seen this session — host skips the lockup. */
+    suppressed: boolean;
+    /** Total marker count detected in the text. >1 = LLM violation; counted by the host telemetry. */
+    markerCount: number;
+}
 /**
  * [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
@@ -823,21 +1028,62 @@ type EngineEvent =
     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.
+ * [SPEC 9 v0.1.3 P9.4] Inline-form structured input event. Emitted when a
+ * tool's preflight returns `needsInput` — the engine pauses the turn,
+ * stores the pending state on the QueryEngine instance keyed by `inputId`,
+ * and waits for the host to call `engine.resumeWithInput(inputId, values)`
+ * with the user's submitted form values. The schema is the typed shape
+ * defined in `pending-input.ts` (closed list of field kinds).
+ *
+ * Upgraded from the SPEC 8 v0.5.1 D2 forward-compat reservation (which
+ * carried `schema: unknown` + a `prompt?: string` placeholder). The
+ * upgrade is wire-compatible: the new shape is a SUPERSET of the
+ * reservation — `schema` narrows from `unknown` to `FormSchema`, and the
+ * additional `toolName` / `toolUseId` / `description` fields are new.
+ * Legacy hosts that no-op on `pending_input` keep working.
  */
  | {
     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. */
+    /** UUID v4 stamped per-emit. Host posts back keyed on this. */
     inputId: string;
-    /** Optional human-readable prompt the LLM wants the host to display above the form. */
-    prompt?: string;
+    /** Tool that requested the input — useful for host debug logs + fallback caption. */
+    toolName: string;
+    /** Original `tool_use_id` from the LLM's call — preserved for the resumed tool_result. */
+    toolUseId: string;
+    /** Form schema (typed — see `pending-input.ts`). */
+    schema: FormSchema;
+    /** Optional human-readable description rendered above the form (e.g. "Add a new contact"). */
+    description?: string;
+    /**
+     * Assistant message blocks captured at pause time. Hosts that
+     * re-instantiate `QueryEngine` per-request (e.g. audric) MUST
+     * persist these alongside the rest of the `PendingInput` payload
+     * and echo them back on `resumeWithInput` so the conversation
+     * stays well-formed.
+     *
+     * Mirrors `pending_action.action.assistantContent` — same
+     * round-trip pattern. In-process hosts can ignore the field
+     * (the engine also stashes the state on `this.pendingInputs`
+     * keyed by `inputId`).
+     *
+     * Typed as `unknown[]` to avoid pulling `ContentBlock` into
+     * `pending-input.ts` and creating a type-import cycle.
+     */
+    assistantContent: unknown[];
+    /**
+     * Tool results from reads that completed BEFORE the paused tool
+     * call (same turn). On resume the engine merges these with the
+     * resumed tool's result into ONE `user`-role message — keeps
+     * Anthropic's "every tool_use must have a tool_result in the next
+     * user message" invariant satisfied.
+     *
+     * Mirrors the round-trip half of `PendingAction.completedResults`.
+     */
+    completedResults: Array<{
+        toolUseId: string;
+        content: string;
+        isError: boolean;
+    }>;
 }
 /**
  * [SPEC 8 v0.5.1 B3.2] One-shot per-turn declaration of which adaptive
@@ -888,11 +1134,17 @@ 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
  * consume `EngineEvent` don't need to depend on the tool module.
+ *
+ * [SPEC 9 v0.1.3 P9.3] `persist?: boolean` — when true, hosts wired
+ * for goal storage (audric) write a long-lived `Goal` row from this
+ * item. Engine is unaware of how the host persists; this flag just
+ * passes through on the `todo_update` side-channel event.
  */
 interface TodoItem$1 {
     id: string;
     label: string;
     status: 'pending' | 'in_progress' | 'completed';
+    persist?: boolean;
 }
 type StopReason = 'end_turn' | 'tool_use' | 'max_tokens' | 'max_turns' | 'error';
 /**
@@ -915,7 +1167,7 @@ interface PendingActionModifiableField {
     asset?: string;
 }
 /**
- * [SPEC 7 v0.4 Layer 2] One step inside a multi-write Payment Stream
+ * [SPEC 7 v0.4 Layer 2] One step inside a multi-write Payment Intent
  * `PendingAction`. Single-write actions never carry `steps[]`; the
  * legacy `toolName`/`toolUseId`/`input`/`attemptId` fields cover them.
  */
@@ -1005,7 +1257,7 @@ interface PendingAction {
      * exists to kill. Also survives session persistence so the resume call
      * can read it back from the rehydrated `PendingAction`.
      *
-     * **Bundles:** when `steps !== undefined` (multi-write Payment Stream),
+     * **Bundles:** when `steps !== undefined` (multi-write Payment Intent),
      * the top-level `attemptId` mirrors `steps[0].attemptId` per SPEC 7
      * § Layer 2 line 463 ("`steps[0]` mirrors the top-level
      * toolName/toolUseId/input/attemptId for hosts that haven't been
@@ -1019,7 +1271,7 @@ interface PendingAction {
     attemptId: string;
     /**
      * [SPEC 7 v0.4 Layer 2] When set, this `pending_action` represents a
-     * multi-write Payment Stream. Single-step bundles are NOT created — the
+     * multi-write Payment Intent. Single-step bundles are NOT created — the
      * engine emits the legacy single-write shape when N=1. Hosts that haven't
      * been updated read `toolName`/`toolUseId`/`input` (which mirror
      * `steps[0]`); newer hosts iterate `steps`.
@@ -1091,7 +1343,7 @@ interface PermissionResponse {
      * Each carries the step's `toolUseId` + `attemptId` so the host's resume
      * route can update the matching `TurnMetrics` row.
      *
-     * **Atomic semantics:** PTB execution is atomic at the Sui layer. If the
+     * **Atomic semantics:** Payment Intent execution is atomic at the Sui layer. If the
      * host detects a bundle-level failure, it should populate every entry
      * with `isError: true` carrying the same error message (so the LLM
      * narrates the failure once, not N times).
@@ -1204,7 +1456,7 @@ interface ToolFlags {
     maxRetries?: number;
     /**
      * [SPEC 7 v0.4 Layer 2] Opt-in: this write tool can participate in a
-     * multi-write Payment Stream. When the LLM emits ≥2 `tool_use` blocks
+     * multi-write Payment Intent. When the LLM emits ≥2 `tool_use` blocks
      * in a single assistant turn AND every block resolves to a `confirm`-tier
      * write tool with `bundleable: true`, the engine collapses them into one
      * `pending_action` with `steps[]` instead of yielding N times. Default
@@ -1215,8 +1467,8 @@ interface ToolFlags {
      * **Permanently non-bundleable:**
      *  - `pay_api` — recipient/amount/currency aren't known at LLM intent
      *    time (gateway 402 challenge resolves them at route time, after a
-     *    network round-trip the engine has no knowledge of). PTB cannot be
-     *    composed at compose time.
+     *    network round-trip the engine has no knowledge of). Payment Intent
+     *    cannot be composed at compose time.
      *  - `save_contact` — Postgres-only, no on-chain effect.
      */
     bundleable?: boolean;
@@ -1226,6 +1478,12 @@ type PreflightResult = {
 } | {
     valid: false;
     error: string;
+} | {
+    valid: false;
+    needsInput: {
+        schema: FormSchema;
+        description?: string;
+    };
 };
 interface Tool<TInput = unknown, TOutput = unknown> {
     name: string;
@@ -1487,6 +1745,23 @@ type ProviderEvent = {
 } | {
     type: 'text_delta';
     text: string;
+}
+/**
+ * [SPEC 9 v0.1.1 P9.2] Fired by the provider at content_block_stop on
+ * a TEXT block when a `<proactive>` marker was detected in the
+ * accumulated text. Carries the parsed marker payload so the engine
+ * can run cooldown logic (per-session dedup) and emit the public
+ * `proactive_text` engine event. Absent when no marker was found —
+ * regular text turns don't pay the cost.
+ *
+ * The provider does NOT do the cooldown check (that's engine state);
+ * it just parses + forwards. Pre-SPEC-9 hosts that handle provider
+ * events directly will silently no-op on this event; the engine's
+ * `handleProviderEvent` is the only consumer in production.
+ */
+ | {
+    type: 'text_done';
+    proactiveMarker?: ProactiveMarker;
 } | {
     type: 'tool_use_start';
     id: string;
@@ -1584,6 +1859,8 @@ declare class QueryEngine {
     private guardEvents;
     private readonly turnReadCache;
     private turnPaused;
+    private readonly proactiveCooldown;
+    private readonly pendingInputs;
     constructor(config: EngineConfig);
     /**
      * Submit a user message and stream engine events.
@@ -1613,6 +1890,37 @@ declare class QueryEngine {
      * This is a separate HTTP request — no persistent connection from submitMessage.
      */
     resumeWithToolResult(action: PendingAction, response: PermissionResponse): AsyncGenerator<EngineEvent>;
+    /**
+     * [SPEC 9 v0.1.3 P9.4] Resume a turn that paused on `pending_input`.
+     *
+     * Called by the host after the user submitted the inline form. The
+     * `pendingInput` argument is the EXACT payload that was yielded as
+     * `pending_input` (host stored it in session storage); `values` is the
+     * `{ fieldName: value }` map the user submitted, post-host-validation
+     * against `pendingInput.schema`.
+     *
+     * Engine responsibilities (in order):
+     * 1. Push the captured `assistantContent` (assistant blocks from the
+     *    paused turn — includes the tool_use that triggered this pause).
+     * 2. Run the paused tool's `call()` with `values` as input. Re-runs
+     *    preflight first as a defense-in-depth gate (host SHOULD have
+     *    validated against the schema, but malformed input would otherwise
+     *    poison the conversation history with an orphan tool_use).
+     * 3. Combine `completedResults` (read tool_results that already ran in
+     *    the same turn before the pause) with the new tool_result into ONE
+     *    user-role message. Anthropic's API requires every tool_use to have
+     *    a tool_result in the immediately-following user message — splitting
+     *    them would produce two consecutive user messages, which the API
+     *    rejects.
+     * 4. Yield `tool_result` for the host's timeline + run `agentLoop` to
+     *    continue the turn (LLM gets the resumed result and narrates).
+     *
+     * Mirrors `resumeWithToolResult` for the user-confirm case but feeds
+     * the values back as the tool's INPUT (the call() runs here for the
+     * first time) instead of as the tool's OUTPUT (the call() ran on the
+     * client side via sponsored-tx for pending_action).
+     */
+    resumeWithInput(pendingInput: PendingInputState, values: Record<string, unknown>): AsyncGenerator<EngineEvent>;
     /**
      * [v1.5] Auto-run configured read tools after a successful write,
      * push their results into the conversation, and yield `tool_result`
@@ -1638,6 +1946,13 @@ declare class QueryEngine {
     reset(): void;
     getGuardEvents(): readonly GuardEvent[];
     loadMessages(messages: Message[]): void;
+    /**
+     * [SPEC 9 v0.1.1 P9.2 / R3] Walk loaded assistant text blocks and seed the
+     * cooldown set with every parseable `(proactiveType, subjectKey)` tuple.
+     * Called automatically from `loadMessages`. Idempotent — safe to call on
+     * an already-populated set; duplicates are absorbed by Set semantics.
+     */
+    private rehydrateProactiveCooldown;
     /**
      * [v0.46.7] Run a read-only tool out-of-band, using the engine's tool
      * registry and ToolContext. Used by hosts to deterministically pre-dispatch
@@ -1690,7 +2005,7 @@ declare function validateHistory(messages: Message[]): Message[];
 /**
  * SPEC 7 v0.3 Quote-Refresh ReviewCard — per-tool result freshness budgets.
  *
- * When a Payment Stream `pending_action` is composed at T=0 from upstream
+ * When a Payment Intent `pending_action` is composed at T=0 from upstream
  * read results, the user may take 30–60s to read + tap APPROVE. By that
  * time some upstream results have drifted (Cetus quotes refresh in
  * ~30s; NAVI APYs change slower). The host renders a "QUOTE Ns OLD"
@@ -1755,15 +2070,15 @@ declare const REGENERATABLE_READ_TOOLS: ReadonlySet<string>;
  *    relaxed to DAG-aware: only pairs that actually chain via
  *    `inputCoinFromStep` need whitelist checking. Standalone steps
  *    interleaved between chained steps run wallet-mode independently
- *    inside the same atomic PTB.** This unlocks Demo 1 ("swap 10% to
+ *    inside the same atomic Payment Intent.** This unlocks Demo 1 ("swap 10% to
  *    SUI, save 50% as USDsui, send $100 to Mom" — 4-op DAG with one
  *    chain at step 1→2, three standalone wallet-mode steps).
  *
  * **DAG-aware semantics.** Pre-3a: every adjacent pair gates the entire
  * bundle. Phase 3a+: each (i, i+1) pair contributes IF a chain is wired
  * (via `shouldChainCoin`). Non-chained pairs are independent — they
- * each pre-fetch their own coin from the wallet inside the PTB. Atomic
- * settlement at the PTB level holds either way.
+ * each pre-fetch their own coin from the wallet inside the Payment Intent.
+ * Atomic settlement at the Payment Intent level holds either way.
  *
  * **Phase 3b (deferred):** `swap_execute → swap_execute` whitelist add
  * for explicit multi-hop swap chains (rare; flag-gated when shipped).
@@ -1785,7 +2100,7 @@ declare const MAX_BUNDLE_OPS = 4;
  *
  * | Pair | Why it works at compose time today |
  * |---|---|
- * | `swap_execute → send_transfer` | Swap's `tx.transferObjects([result.coin], sender)` lands the swap output in the wallet for the same PTB; send's `selectAndSplitCoin` finds it. |
+ * | `swap_execute → send_transfer` | Swap's `tx.transferObjects([result.coin], sender)` lands the swap output in the wallet for the same Payment Intent; send's `selectAndSplitCoin` finds it. |
  * | `swap_execute → save_deposit` | Same mechanism — swap output is back in wallet for save's coin fetch. (P0 caveat: this currently *fails* if the wallet has zero of `swap.to` BEFORE the swap step. Phase 1's `inputCoinFromStep` fixes that. For now we accept the pair but warn the LLM in the prompt rule that wallet must hold ≥0 of target asset.) |
  * | `swap_execute → repay_debt` | Same as save. Same caveat. |
  * | `withdraw → swap_execute` | Withdraw's output is transferred to user; swap's coin fetch finds it. Same wallet caveat in reverse. |
@@ -1913,7 +2228,7 @@ declare function composeBundleFromToolResults(input: BundleCompositionInput): Pe
 /**
  * SPEC 7 v0.3 Quote-Refresh ReviewCard — engine-side bundle regeneration.
  *
- * When a user takes 30–60s to read a multi-step Payment Stream
+ * When a user takes 30–60s to read a multi-step Payment Intent
  * `pending_action`, the upstream read results that fed bundle composition
  * (Cetus quotes, NAVI APYs, wallet balances) drift. Today the user has to
  * either approve with stale data (Sui dry-run is the safety gate, but the
@@ -2038,6 +2353,22 @@ interface BuildToolOptions<TInput, TOutput> {
     jsonSchema: ToolJsonSchema;
     call: (input: TInput, context: ToolContext) => Promise<ToolResult<TOutput>>;
     isReadOnly?: boolean;
+    /**
+     * [SPEC 9 v0.1.3 P9.4] When `false`, the tool opts out of mid-stream
+     * `EarlyToolDispatcher` execution and is forced through the post-stream
+     * guard loop where `tool.preflight` runs (Tier 0 of `runGuards`).
+     *
+     * Default: `isReadOnly` (mirrors v1 behavior — read-only tools are
+     * considered concurrency-safe by default).
+     *
+     * Set to `false` for read-only tools that need preflight before
+     * executing. Notable example: `add_recipient` returns `needsInput`
+     * from preflight to pause the turn for an inline form. If it ran
+     * via early-dispatch, the tool's `call()` would fire BEFORE preflight
+     * is consulted (early-dispatch skips the guard loop), and the form
+     * pause path would be unreachable.
+     */
+    isConcurrencySafe?: boolean;
     permissionLevel?: PermissionLevel;
     flags?: ToolFlags;
     preflight?: (input: TInput) => PreflightResult;
@@ -2118,9 +2449,24 @@ type SSEEvent = {
     pct?: number;
 } | {
     type: 'pending_input';
-    schema: unknown;
     inputId: string;
-    prompt?: string;
+    toolName: string;
+    toolUseId: string;
+    schema: FormSchema;
+    description?: string;
+    assistantContent: unknown[];
+    completedResults: Array<{
+        toolUseId: string;
+        content: string;
+        isError: boolean;
+    }>;
+} | {
+    type: 'proactive_text';
+    proactiveType: ProactiveType;
+    subjectKey: string;
+    body: string;
+    suppressed: boolean;
+    markerCount: number;
 } | {
     type: 'harness_shape';
     shape: HarnessShape;
@@ -2179,11 +2525,12 @@ declare class MemorySessionStore implements SessionStore {
  *   producesArtifact — returns images, documents, generated content
  *   costAware       — has a monetary cost the user should know about
  *   maxRetries      — max calls with same input (default: unlimited for reads, 1 for writes)
- *   bundleable      — [SPEC 7 Layer 2] can participate in a multi-write Payment Stream
- *                     PTB. Set on every confirm-tier write whose on-chain effect is
- *                     fully expressible at compose time. Excluded: `pay_api` (recipient/
- *                     amount/currency unknown until gateway 402 challenge resolves at
- *                     route time) and `save_contact` (Postgres-only, no on-chain effect).
+ *   bundleable      — [SPEC 7 Layer 2] can participate in a multi-write Payment
+ *                     Intent. Set on every confirm-tier write whose on-chain effect
+ *                     is fully expressible at compose time. Excluded: `pay_api`
+ *                     (recipient/amount/currency unknown until gateway 402 challenge
+ *                     resolves at route time) and `save_contact` (Postgres-only, no
+ *                     on-chain effect).
  */
 declare const TOOL_FLAGS: Record<string, ToolFlags>;
 /**
@@ -2939,9 +3286,9 @@ declare const ratesInfoTool: Tool<{
 }, RateMap>;
 
 declare const transactionHistoryTool: Tool<{
+    date?: string | undefined;
     action?: "send" | "swap" | "transaction" | "lending" | undefined;
     address?: string | undefined;
-    date?: string | undefined;
     limit?: number | undefined;
     direction?: "out" | "in" | undefined;
     counterparty?: string | undefined;
@@ -3282,40 +3629,48 @@ declare const todoItemSchema: z.ZodObject<{
     id: z.ZodString;
     label: z.ZodString;
     status: z.ZodEnum<["pending", "in_progress", "completed"]>;
+    persist: z.ZodOptional<z.ZodBoolean>;
 }, "strip", z.ZodTypeAny, {
     label: string;
     status: "pending" | "in_progress" | "completed";
     id: string;
+    persist?: boolean | undefined;
 }, {
     label: string;
     status: "pending" | "in_progress" | "completed";
     id: string;
+    persist?: boolean | undefined;
 }>;
 declare const inputSchema: z.ZodObject<{
     items: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         label: z.ZodString;
         status: z.ZodEnum<["pending", "in_progress", "completed"]>;
+        persist: z.ZodOptional<z.ZodBoolean>;
     }, "strip", z.ZodTypeAny, {
         label: string;
         status: "pending" | "in_progress" | "completed";
         id: string;
+        persist?: boolean | undefined;
     }, {
         label: string;
         status: "pending" | "in_progress" | "completed";
         id: string;
+        persist?: boolean | undefined;
     }>, "many">;
 }, "strip", z.ZodTypeAny, {
     items: {
         label: string;
         status: "pending" | "in_progress" | "completed";
         id: string;
+        persist?: boolean | undefined;
     }[];
 }, {
     items: {
         label: string;
         status: "pending" | "in_progress" | "completed";
         id: string;
+        persist?: boolean | undefined;
     }[];
 }>;
 type TodoItem = z.infer<typeof todoItemSchema>;
@@ -3325,6 +3680,7 @@ declare const updateTodoTool: Tool<{
         label: string;
         status: "pending" | "in_progress" | "completed";
         id: string;
+        persist?: boolean | undefined;
     }[];
 }, {
     __todoUpdate: boolean;
@@ -3332,9 +3688,19 @@ declare const updateTodoTool: Tool<{
         label: string;
         status: "pending" | "in_progress" | "completed";
         id: string;
+        persist?: boolean | undefined;
     }[];
 }>;
 
+declare const addRecipientTool: Tool<{
+    name?: string | undefined;
+    identifier?: string | undefined;
+}, {
+    saved: boolean;
+    name: string;
+    identifier: string;
+}>;
+
 declare const tokenPricesTool: Tool<{
     coinTypes: string[];
     include24hChange?: boolean | undefined;
@@ -3837,7 +4203,7 @@ declare function fetchAudricHistory(address: string, opts: {
     limit?: number;
 }, env?: Record<string, string>, signal?: AbortSignal): Promise<AudricHistoryRecord[] | null>;
 
-declare const DEFAULT_SYSTEM_PROMPT = "You are Audric \u2014 a financial agent on Sui. Audric is exactly five products: Audric Passport (the trust layer \u2014 Google sign-in, non-custodial wallet, tap-to-confirm consent, sponsored gas \u2014 wraps every other product), Audric Intelligence (you \u2014 the 5-system brain: Agent Harness with 34 tools, Reasoning Engine with 14 guards and 6 skill recipes, Silent Profile, Chain Memory, AdviceLog), Audric Finance (manage money on Sui \u2014 Save via NAVI lending at 3-8% APY USDC, Credit via NAVI borrowing with health factor, Swap via Cetus aggregator across 20+ DEXs at 0.1% fee, Charts for yield/health/portfolio viz), Audric Pay (move money \u2014 send USDC, receive via payment links / invoices / QR; free, global, instant on Sui), and Audric Store (creator marketplace, ships Phase 5 \u2014 say \"coming soon\" if asked). Save, swap, borrow, repay, withdraw, charts \u2192 Audric Finance. Send, receive, payment-link, invoice, QR \u2192 Audric Pay. Your silent context (profile, memory, chain facts, advice log) shapes your replies but never surfaces as a notification \u2014 you act only when the user asks, and every write waits on their tap-to-confirm via Passport. You can also call 41 paid APIs (music, image, research, translation, weather, fulfilment) via MPP micropayments using the pay_api tool \u2014 this is an internal capability, not a promoted product, so only mention it when the user asks for something that needs it.\n\n## Response rules\n- 1-2 sentences max. No bullet lists unless asked. No preambles.\n- Never say \"Would you like me to...\", \"Sure!\", \"Great question!\", \"Absolutely!\" \u2014 just do it or say you can't.\n- Present amounts as $1,234.56 and rates as X.XX% APY.\n- Show top 3 results unless asked for more. Summarize totals in one line.\n\n## Caption rules (after tool calls)\n- **When a canvas was rendered (`render_canvas` was called, or any tool that auto-renders a card like balance_check / portfolio_analysis / savings_info / health_check / transaction_history): the canvas IS the answer.** Your chat message must NOT restate wallet, savings, debt, holdings, or net-worth numbers \u2014 they are already on screen. Add at most ONE sentence of context, advice, or next step (e.g. \"Your USDC is idle \u2014 consider depositing for ~4.5% APY\"), or say nothing.\n- **When NO canvas was rendered:** lead with the result and quote the actual numbers from the tool. One sentence.\n- **NEVER describe a position as \"no\", \"none\", \"minimal\", \"zero\", or \"inactive\" if the tool result contains a positive value for that field.** The tool result is the source of truth \u2014 never your interior summary. If the canvas shows $100 in savings, you cannot say \"no active savings\" in the caption.\n- **NEVER claim \"no DeFi positions\" when the tool result says the DeFi slice is UNAVAILABLE.** When `balance_check` displayText contains \"DeFi positions: UNAVAILABLE\" or \"DeFi data source unreachable\", the slice is unknown \u2014 say \"DeFi data is currently unavailable\" or omit the mention. Only claim \"no DeFi positions\" when the displayText explicitly omits any DeFi line (i.e. the fetch succeeded with $0 across every covered protocol).\n\n## Execution rule\nOnly offer to execute actions you have tools for. If you retrieved a quote, data, or information but have no tool to act on it, give the user the result and tell them where to execute manually \u2014 in one sentence. Never say \"Would you like me to proceed?\" unless you have a tool that can actually proceed.\n\n## Before acting\n- ALWAYS call a read tool first before any write tool \u2014 balance_check before save/send/borrow, savings_info before withdraw.\n- Show real numbers from tools \u2014 never fabricate rates, amounts, or balances.\n- When user says \"all\" or an imprecise amount, call the read tool first to get the exact number.\n\n## Tool usage\n- Use tools proactively \u2014 don't refuse requests you can handle.\n- For real-world questions (weather, search, news, prices), use pay_api. Tell the user the cost first.\n- For NAVI lending APYs, use rates_info; for VOLO liquid staking stats, use volo_stats; for spot token prices, use token_prices.\n- For protocol-level due diligence (TVL, fees, audits, safety) on Sui DeFi protocols, use protocol_deep_dive with the slug.\n- Run multiple read-only tools in parallel when you need several data points.\n- If a tool errors, say what went wrong and what to try instead. One sentence.\n\n## Savings = USDC or USDsui (critical)\n- save_deposit and borrow accept ONLY USDC or USDsui. No other token can be deposited or borrowed.\n- USDC is the canonical default. USDsui is permitted because it has a productive NAVI pool (often a higher APY than USDC). All other holdings (GOLD, SUI, USDT, USDe, ETH, NAVX, WAL) are NOT saveable.\n- When asked \"how much can I save?\":\n  - Report saveableUsdc from balance_check (the user's USDC wallet balance \u2014 canonical saveable).\n  - If the user also holds USDsui in their wallet, report that separately as \"USDsui (saveable): X.XX\". Do NOT roll the two together \u2014 the LLM must keep the per-asset distinction so the user can pick.\n- When the user says \"save 10 USDC\" \u2192 call save_deposit with asset=\"USDC\". When they say \"save 10 USDsui\" \u2192 call with asset=\"USDsui\". Never silently substitute.\n- When the user says \"save 10\" (no asset) \u2192 call balance_check first and ask which stable they want, OR pick whichever they hold more of with a one-line explanation.\n- \"Best stable to save right now?\" \u2192 call rates_info to compare USDC vs USDsui APY on NAVI; let the user pick.\n- NEVER say a non-saveable token (GOLD, SUI, USDT, etc.) is \"in savings\" or \"earning APY in savings\". Wallet holdings \u2260 savings positions, even for stables we don't accept.\n- If user wants to save a non-saveable token, tell them to swap to USDC or USDsui first. Do NOT auto-chain swap + deposit.\n- Repay symmetry: a USDsui debt MUST be repaid with USDsui (and USDC debt with USDC). When calling repay_debt, pass asset=\"USDsui\" if the borrow is USDsui. If the user asks \"repay my debt\" and savings_info shows borrows in BOTH stables, list both and ask which to repay first. If the user holds the wrong stable, tell them to swap manually \u2014 do NOT auto-chain swap + repay.\n\n## Fees (critical \u2014 never deny having fees)\n- **Swap:** 0.1% Audric overlay fee on the output amount, taken by the aggregator and sent to the Audric treasury. The Cetus DEX fee (typically 0.01\u20130.25%) is separate and goes to the DEX. Both are shown on the swap card. Never say Audric takes no cut on swaps \u2014 it does.\n- **Save (deposit):** 0.1% Audric fee on the deposit amount, taken atomically in the same transaction.\n- **Borrow:** 0.05% Audric fee on the borrow amount, taken atomically in the same transaction.\n- **Withdraw / Repay / Send / Receive:** No Audric fee. Gas is sponsored (free to the user).\n- When a user asks about fees, quote the above. Do NOT say \"I don't take a cut\", \"fees are zero\", \"all your value stays with you\", or \"I'm here to execute, not extract\" \u2014 those are incorrect for swap, save, and borrow.\n\n## Multi-step flows\n- \"How much X for Y?\": swap_quote first, then swap_execute if user confirms.\n- \"Swap then save\": swap_execute \u2192 balance_check \u2192 save_deposit. Confirm each step.\n- \"Buy $X of token\": token_prices \u2192 calculate amount \u2192 swap_execute.\n- \"Best yield on SUI\": compare rates_info (NAVI lending) + volo_stats (vSUI liquid staking).\n- withdraw supports legacy positions: USDC, USDe, USDsui, SUI. Pass asset param to withdraw a specific token.\n- \"Deposit SUI to earn yield\": volo_stake for SUI liquid staking. save_deposit only accepts USDC or USDsui.\n- \"Is protocol X safe?\" / \"Tell me about NAVI\": protocol_deep_dive with the slug.\n- \"Full account report\" / \"account summary\" / \"give me everything\" / \"complete overview\": triggers the `account_report` recipe \u2014 when the recipe block appears, follow EVERY step including all six tool calls. Each step renders a distinct rich card; skipping a step means a missing card.\n\n## Safety\n- Never encourage risky financial behavior.\n- Warn when health factor < 1.5.\n- All amounts in USDC unless stated otherwise.";
+declare const DEFAULT_SYSTEM_PROMPT = "You are Audric \u2014 a financial agent on Sui. Audric is exactly five products: Audric Passport (the trust layer \u2014 Google sign-in, non-custodial wallet, tap-to-confirm consent, sponsored gas \u2014 wraps every other product), Audric Intelligence (you \u2014 the 5-system brain: Agent Harness with 34 tools, Reasoning Engine with 14 guards and 6 skill recipes, Silent Profile, Chain Memory, AdviceLog), Audric Finance (manage money on Sui \u2014 Save via NAVI lending at 3-8% APY USDC, Credit via NAVI borrowing with health factor, Swap via Cetus aggregator across 20+ DEXs at 0.1% fee, Charts for yield/health/portfolio viz), Audric Pay (move money \u2014 send USDC, receive via payment links / invoices / QR; free, global, instant on Sui), and Audric Store (creator marketplace, ships Phase 5 \u2014 say \"coming soon\" if asked). Save, swap, borrow, repay, withdraw, charts \u2192 Audric Finance. Send, receive, payment-link, invoice, QR \u2192 Audric Pay. Your silent context (profile, memory, chain facts, advice log) shapes your replies but never surfaces as a notification \u2014 you act only when the user asks, and every write waits on their tap-to-confirm via Passport. You can also call 41 paid APIs (music, image, research, translation, weather, fulfilment) via MPP micropayments using the pay_api tool \u2014 this is an internal capability, not a promoted product, so only mention it when the user asks for something that needs it.\n\n## Response rules\n- 1-2 sentences max. No bullet lists unless asked. No preambles.\n- Never say \"Would you like me to...\", \"Sure!\", \"Great question!\", \"Absolutely!\" \u2014 just do it or say you can't.\n- Present amounts as $1,234.56 and rates as X.XX% APY.\n- Show top 3 results unless asked for more. Summarize totals in one line.\n\n## Caption rules (after tool calls)\n- **When a canvas was rendered (`render_canvas` was called, or any tool that auto-renders a card like balance_check / portfolio_analysis / savings_info / health_check / transaction_history): the canvas IS the answer.** Your chat message must NOT restate wallet, savings, debt, holdings, or net-worth numbers \u2014 they are already on screen. Add at most ONE sentence of context, advice, or next step (e.g. \"Your USDC is idle \u2014 consider depositing for ~4.5% APY\"), or say nothing.\n- **When NO canvas was rendered:** lead with the result and quote the actual numbers from the tool. One sentence.\n- **NEVER describe a position as \"no\", \"none\", \"minimal\", \"zero\", or \"inactive\" if the tool result contains a positive value for that field.** The tool result is the source of truth \u2014 never your interior summary. If the canvas shows $100 in savings, you cannot say \"no active savings\" in the caption.\n- **NEVER claim \"no DeFi positions\" when the tool result says the DeFi slice is UNAVAILABLE.** When `balance_check` displayText contains \"DeFi positions: UNAVAILABLE\" or \"DeFi data source unreachable\", the slice is unknown \u2014 say \"DeFi data is currently unavailable\" or omit the mention. Only claim \"no DeFi positions\" when the displayText explicitly omits any DeFi line (i.e. the fetch succeeded with $0 across every covered protocol).\n\n## Execution rule\nOnly offer to execute actions you have tools for. If you retrieved a quote, data, or information but have no tool to act on it, give the user the result and tell them where to execute manually \u2014 in one sentence. Never say \"Would you like me to proceed?\" unless you have a tool that can actually proceed.\n\n## Before acting\n- ALWAYS call a read tool first before any write tool \u2014 balance_check before save/send/borrow, savings_info before withdraw.\n- Show real numbers from tools \u2014 never fabricate rates, amounts, or balances.\n- When user says \"all\" or an imprecise amount, call the read tool first to get the exact number.\n\n## Tool usage\n- Use tools proactively \u2014 don't refuse requests you can handle.\n- For real-world questions (weather, search, news, prices), use pay_api. Tell the user the cost first.\n- For NAVI lending APYs, use rates_info; for VOLO liquid staking stats, use volo_stats; for spot token prices, use token_prices.\n- For protocol-level due diligence (TVL, fees, audits, safety) on Sui DeFi protocols, use protocol_deep_dive with the slug.\n- Run multiple read-only tools in parallel when you need several data points.\n- If a tool errors, say what went wrong and what to try instead. One sentence.\n\n## Savings = USDC or USDsui (critical)\n- save_deposit and borrow accept ONLY USDC or USDsui. No other token can be deposited or borrowed.\n- USDC is the canonical default. USDsui is permitted because it has a productive NAVI pool (often a higher APY than USDC). All other holdings (GOLD, SUI, USDT, USDe, ETH, NAVX, WAL) are NOT saveable.\n- When asked \"how much can I save?\":\n  - Report saveableUsdc from balance_check (the user's USDC wallet balance \u2014 canonical saveable).\n  - If the user also holds USDsui in their wallet, report that separately as \"USDsui (saveable): X.XX\". Do NOT roll the two together \u2014 the LLM must keep the per-asset distinction so the user can pick.\n- When the user says \"save 10 USDC\" \u2192 call save_deposit with asset=\"USDC\". When they say \"save 10 USDsui\" \u2192 call with asset=\"USDsui\". Never silently substitute.\n- When the user says \"save 10\" (no asset) \u2192 call balance_check first and ask which stable they want, OR pick whichever they hold more of with a one-line explanation.\n- \"Best stable to save right now?\" \u2192 call rates_info to compare USDC vs USDsui APY on NAVI; let the user pick.\n- NEVER say a non-saveable token (GOLD, SUI, USDT, etc.) is \"in savings\" or \"earning APY in savings\". Wallet holdings \u2260 savings positions, even for stables we don't accept.\n- If user wants to save a non-saveable token, tell them to swap to USDC or USDsui first. Do NOT auto-chain swap + deposit.\n- Repay symmetry: a USDsui debt MUST be repaid with USDsui (and USDC debt with USDC). When calling repay_debt, pass asset=\"USDsui\" if the borrow is USDsui. If the user asks \"repay my debt\" and savings_info shows borrows in BOTH stables, list both and ask which to repay first. If the user holds the wrong stable, tell them to swap manually \u2014 do NOT auto-chain swap + repay.\n\n## Fees (critical \u2014 never deny having fees)\n- **Swap:** 0.1% Audric overlay fee on the output amount, taken by the aggregator and sent to the Audric treasury. The Cetus DEX fee (typically 0.01\u20130.25%) is separate and goes to the DEX. Both are shown on the swap card. Never say Audric takes no cut on swaps \u2014 it does.\n- **Save (deposit):** 0.1% Audric fee on the deposit amount, taken atomically in the same transaction.\n- **Borrow:** 0.05% Audric fee on the borrow amount, taken atomically in the same transaction.\n- **Withdraw / Repay / Send / Receive:** No Audric fee. Gas is sponsored (free to the user).\n- When a user asks about fees, quote the above. Do NOT say \"I don't take a cut\", \"fees are zero\", \"all your value stays with you\", or \"I'm here to execute, not extract\" \u2014 those are incorrect for swap, save, and borrow.\n\n## Multi-step flows\n- \"How much X for Y?\": swap_quote first, then swap_execute if user confirms.\n- \"Swap then save\": swap_execute \u2192 balance_check \u2192 save_deposit. Confirm each step.\n- \"Buy $X of token\": token_prices \u2192 calculate amount \u2192 swap_execute.\n- \"Best yield on SUI\": compare rates_info (NAVI lending) + volo_stats (vSUI liquid staking).\n- withdraw supports legacy positions: USDC, USDe, USDsui, SUI. Pass asset param to withdraw a specific token.\n- \"Deposit SUI to earn yield\": volo_stake for SUI liquid staking. save_deposit only accepts USDC or USDsui.\n- \"Is protocol X safe?\" / \"Tell me about NAVI\": protocol_deep_dive with the slug.\n- \"Full account report\" / \"account summary\" / \"give me everything\" / \"complete overview\": triggers the `account_report` recipe \u2014 when the recipe block appears, follow EVERY step including all six tool calls. Each step renders a distinct rich card; skipping a step means a missing card.\n\n## Safety\n- Never encourage risky financial behavior.\n- Warn when health factor < 1.5.\n- All amounts in USDC unless stated otherwise.\n\n## Proactive insights (only when there's a clear opportunity)\n- When you spot an unsolicited financial insight worth surfacing \u2014 idle balance worth saving, health factor approaching the warning band, APY drift on a known position, progress against a saved goal \u2014 wrap your ENTIRE response in a `<proactive type=\"...\" subjectKey=\"...\">BODY</proactive>` block.\n- The host renders proactive blocks with a distinct \"\u2726 ADDED BY AUDRIC\" lockup so the user knows this is your suggestion, not an answer to a question.\n- Allowed types (closed list \u2014 anything else is dropped): `idle_balance` (cash sitting idle that could earn yield), `hf_warning` (debt position approaching liquidation), `apy_drift` (rate change on a position they hold), `goal_progress` (update on a saved goal).\n- `subjectKey` is a stable identifier for the SPECIFIC subject \u2014 examples: `USDC` for an idle-balance insight on USDC, `1.45` for a HF warning at that level, `save-500-by-may` for goal progress. Same (type, subjectKey) won't fire twice in one session \u2014 pick the same key for the same subject so the engine cooldown works.\n- Cap: at most ONE proactive block per turn. Do NOT mix proactive insights with answers to user questions \u2014 if the user asked a question, answer it; emit a proactive block only when there's no user question OR when the question is unrelated to the insight.\n- Skip proactive blocks when nothing notable changed since the last turn, when the user is mid-flow on something else, or when you'd just be restating the financial-context block. Quality over quantity \u2014 a block ignored is worse than no block.";
 
 /** Cache entry shape. `cachedAt` is the wall-clock ms at write time. */
 interface NaviCacheEntry {
@@ -3920,4 +4286,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 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 PendingReward, type PendingToolCall, type PermissionLevel, type PermissionOperation, type PermissionResponse, type PermissionRule, type PortfolioCoin, type PositionEntry, type PreflightResult, 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, 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, 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, isBundleableTool, loadRecipes, looksLikeSuiNs, microcompact, mppServicesTool, naviKey, normalizeAddressInput, parseEvalSummary, parseMcpJson, parseRecipe, parseSSE, payApiTool, 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, 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 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, 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, 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 };