@t2000/engine 1.18.0 → 1.20.0

package/dist/index.js

@@ -19,7 +19,7 @@ function buildTool(opts) {
     jsonSchema: opts.jsonSchema,
     call: opts.call,
     isReadOnly,
-    isConcurrencySafe: isReadOnly,
+    isConcurrencySafe: opts.isConcurrencySafe ?? isReadOnly,
     permissionLevel: opts.permissionLevel ?? (isReadOnly ? "auto" : "confirm"),
     flags: opts.flags ?? {},
     preflight: opts.preflight,
@@ -5171,14 +5171,22 @@ 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
+  status: todoStatusSchema,
+  // [SPEC 9 v0.1.3 P9.3] Per-item persistence flag — opt this todo item
+  // into the long-lived `Goal` row surface. Hosts that wire goal storage
+  // (audric) write a Goal row with `content: label`, `status: 'in_progress'`,
+  // `sourceSessionId: <currentSession>` when this flag is true. Default
+  // false — most turn-scoped items don't survive the turn. Engine is
+  // unaware of how/where the host persists; it just passes the flag
+  // through on the `todo_update` side-channel event.
+  persist: z.boolean().optional()
 });
 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.",
+  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. \n\n[SPEC 9 v0.1.3] To promote an item into a long-lived goal that survives across sessions, set `persist: true` on that item. Reserve this for multi-week commitments the user explicitly wants remembered (e.g. \"save $500 by month-end\", \"track NAVI USDC APY weekly\"). DO NOT set persist on within-turn steps (\"check balance\", \"compute split\") \u2014 those vanish when the turn ends, which is what you want. Default behaviour (no persist field) is don't-persist.",
   inputSchema: inputSchema6,
   jsonSchema: {
     type: "object",
@@ -5202,6 +5210,10 @@ var updateTodoTool = buildTool({
               type: "string",
               enum: ["pending", "in_progress", "completed"],
               description: "Lifecycle state. Exactly one item must be `in_progress` per call."
+            },
+            persist: {
+              type: "boolean",
+              description: 'Set true to promote this item into a long-lived goal that survives across sessions (e.g. "save $500 by month-end"). Default false \u2014 only set true when the item represents a multi-week / multi-session commitment, not a within-turn step. When false or omitted, the item lives only for this turn.'
             }
           },
           required: ["id", "label", "status"]
@@ -5268,6 +5280,92 @@ var updateTodoTool = buildTool({
     };
   }
 });
+var ADD_RECIPIENT_FORM = {
+  fields: [
+    {
+      name: "name",
+      label: "Nickname",
+      kind: "text",
+      required: true,
+      placeholder: "Mom",
+      helpText: "How you'll refer to this contact in chat."
+    },
+    {
+      name: "identifier",
+      label: "Audric handle, SuiNS name, or wallet address",
+      // [v0.1.3 R6] Polymorphic kind — accepts handles, names, and 0x.
+      // The host renderer treats this as a single text input with
+      // help-text guidance; server-side `normalizeAddressInput` does
+      // the resolution.
+      kind: "sui-recipient",
+      required: true,
+      placeholder: "mom.audric.sui  /  alex.sui  /  0x40cd\u20263e62",
+      helpText: "Type @alice for an Audric user, alex.sui for any SuiNS, or paste a 0x address. We'll resolve it to the canonical wallet automatically."
+    }
+  ]
+};
+var addRecipientTool = buildTool({
+  name: "add_recipient",
+  description: `Add a new contact to the user's saved-recipients list. Call this when you (the LLM) need to reference a contact that isn't saved yet \u2014 e.g. the user said "send $10 to Mom" but no contact named "Mom" exists. The user will fill in the nickname + identifier (an Audric handle, SuiNS name, or wallet address) via an inline form. The contact is persisted before this tool returns; the resumed call returns confirmation only. Do NOT call when the user manually opens the contact-add UI from settings \u2014 that's a separate user-initiated flow that doesn't need the LLM. Only call when YOU need to add a contact mid-conversation to make a downstream action work.`,
+  inputSchema: z.object({
+    name: z.string().min(1).optional(),
+    identifier: z.string().min(1).optional()
+  }),
+  jsonSchema: {
+    type: "object",
+    properties: {
+      name: {
+        type: "string",
+        description: 'Optional nickname for the contact ("Mom"). Omit to let the user fill the form.'
+      },
+      identifier: {
+        type: "string",
+        description: "Optional polymorphic identifier (Audric handle, SuiNS name, or 0x address). Omit to let the user fill the form."
+      }
+    },
+    required: []
+  },
+  // Permission: read-only from the engine's perspective. The HOST writes
+  // the Contact row in the resume endpoint; the tool's call() body is a
+  // thin confirmation message. Treating as read-only keeps the engine's
+  // permission gate from yielding `pending_action` (which would conflict
+  // with the `pending_input` flow — you'd get a form, then a confirm card,
+  // for what's semantically one user action).
+  isReadOnly: true,
+  // [SPEC 9 v0.1.3 P9.4] Opt out of EarlyToolDispatcher. Early-dispatch
+  // runs the tool's call() mid-stream BEFORE the post-stream guard loop
+  // (where preflight is invoked). If add_recipient ran via early-dispatch,
+  // call() would fire with name/identifier=undefined and "save" garbage
+  // before the form pause path is even consulted. Forcing the tool
+  // through the post-stream loop guarantees preflight runs first.
+  isConcurrencySafe: false,
+  permissionLevel: "auto",
+  flags: {},
+  preflight: (input) => {
+    if (!input.name || !input.identifier) {
+      return {
+        valid: false,
+        needsInput: {
+          schema: ADD_RECIPIENT_FORM,
+          description: "Add a new contact"
+        }
+      };
+    }
+    return { valid: true };
+  },
+  async call(input) {
+    const name = input.name;
+    const identifier = input.identifier;
+    return {
+      data: {
+        saved: true,
+        name,
+        identifier
+      },
+      displayText: `Saved ${name} (${identifier}) to contacts.`
+    };
+  }
+});
 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.',
@@ -5467,7 +5565,73 @@ Only offer to execute actions you have tools for. If you retrieved a quote, data
 ## Safety
 - Never encourage risky financial behavior.
 - Warn when health factor < 1.5.
-- All amounts in USDC unless stated otherwise.`;
+- All amounts in USDC unless stated otherwise.
+
+## Proactive insights (only when there's a clear opportunity)
+- When you spot a 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 emit a \`<proactive type="..." subjectKey="...">BODY</proactive>\` block. ALWAYS use the wrapper \u2014 plain-text proactive prose without the wrapper renders as regular text and skips the engine's per-session cooldown (the same nudge will then re-fire every turn).
+- Two valid placements \u2014 pick whichever fits the turn:
+  - **No user question** (or the question is unrelated to the insight): wrap your ENTIRE response in the \`<proactive>\` block.
+  - **You're answering a user question AND have a related insight to add**: answer the question normally, then APPEND the \`<proactive>\` block at the end, separated by a line break. The "after the answer" form is also taught in detail under \xA7 Proactive Awareness \u2014 same syntax, both placements valid.
+- The host renders the wrapped block with a distinct "\u2726 ADDED BY AUDRIC" lockup so the user knows this is your suggestion, not an answer.
+- 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).
+- \`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.
+- Cap: at most ONE proactive block per turn.
+- 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.`;
+
+// src/proactive-marker.ts
+var VALID_TYPES = /* @__PURE__ */ new Set([
+  "idle_balance",
+  "hf_warning",
+  "apy_drift",
+  "goal_progress"
+]);
+var MARKER_REGEX = /<proactive\s+([^>]+)>([\s\S]*?)<\/proactive>/g;
+var ATTR_TYPE_REGEX = /\btype\s*=\s*"([^"]+)"/;
+var ATTR_SUBJECT_KEY_REGEX = /\bsubjectKey\s*=\s*"([^"]+)"/;
+function parseProactiveMarker(text) {
+  if (!text.includes("<proactive")) return null;
+  const matches = [];
+  for (const match of text.matchAll(MARKER_REGEX)) {
+    matches.push({ attrs: match[1] ?? "", body: match[2] ?? "" });
+  }
+  if (matches.length === 0) return null;
+  for (const { attrs, body } of matches) {
+    const typeMatch = attrs.match(ATTR_TYPE_REGEX);
+    const subjectKeyMatch = attrs.match(ATTR_SUBJECT_KEY_REGEX);
+    if (!typeMatch || !subjectKeyMatch) continue;
+    const proactiveType = typeMatch[1];
+    const subjectKey = subjectKeyMatch[1].trim();
+    if (!VALID_TYPES.has(proactiveType)) continue;
+    if (subjectKey.length === 0) continue;
+    const trimmedBody = body.trim();
+    if (trimmedBody.length === 0) continue;
+    return {
+      proactiveType,
+      subjectKey,
+      body: trimmedBody,
+      markerCount: matches.length
+    };
+  }
+  return null;
+}
+function stripProactiveMarkers(text) {
+  if (!text.includes("<proactive")) return text;
+  return text.replace(MARKER_REGEX, (_match, _attrs, body) => body);
+}
+function extractAllProactiveMarkers(text) {
+  if (!text.includes("<proactive")) return [];
+  const out = [];
+  for (const match of text.matchAll(MARKER_REGEX)) {
+    const attrs = match[1] ?? "";
+    const typeMatch = attrs.match(ATTR_TYPE_REGEX);
+    const subjectKeyMatch = attrs.match(ATTR_SUBJECT_KEY_REGEX);
+    if (!typeMatch || !subjectKeyMatch) continue;
+    const subjectKey = subjectKeyMatch[1].trim();
+    if (subjectKey.length === 0) continue;
+    out.push({ proactiveType: typeMatch[1], subjectKey });
+  }
+  return out;
+}
 
 // src/cost.ts
 var DEFAULT_INPUT_COST = 3 / 1e6;
@@ -6024,6 +6188,29 @@ function runGuards(tool, call, state, config, conversationContext, onGuardFired,
   if (config.inputValidation !== false && tool.preflight) {
     const check = tool.preflight(call.input);
     if (!check.valid) {
+      if ("needsInput" in check && check.needsInput) {
+        const event2 = {
+          timestamp: now,
+          toolName: tool.name,
+          toolUseId: call.id,
+          gate: "input_validation",
+          verdict: "pass",
+          tier: "safety",
+          message: check.needsInput.description
+        };
+        fire("pass", "safety", "input_validation", false);
+        return {
+          blocked: false,
+          injections: [],
+          events: [event2],
+          needsInput: check.needsInput
+        };
+      }
+      if (!("error" in check)) {
+        throw new Error(
+          `Preflight returned a non-needsInput, non-error invalid result for tool ${tool.name}`
+        );
+      }
       const event = {
         timestamp: now,
         toolName: tool.name,
@@ -6945,6 +7132,26 @@ var QueryEngine = class {
   // their `finally` block so they DON'T clear the cache mid-turn — the
   // pending write may resume, and the cache should survive the pause.
   turnPaused = false;
+  // [SPEC 9 v0.1.1 P9.2 / R3] Per-engine-instance cooldown set for
+  // proactive insight markers. Same `(proactiveType, subjectKey)` tuple
+  // emitted twice in one session ⇒ second emission is suppressed (host
+  // strips the wrapper, renders body as plain text). Cooldown is
+  // per-session, not cross-session — a fresh QueryEngine on the next
+  // user session starts with an empty set and may re-emit the same
+  // tuple. Drops automatically when the engine is GC'd.
+  //
+  // Storage shape: serialised key `${type}:${subjectKey}` for cheap
+  // Set membership without an extra hash function.
+  proactiveCooldown = /* @__PURE__ */ new Set();
+  // [SPEC 9 v0.1.3 P9.4] In-flight `pending_input` state, keyed by `inputId`.
+  // Set when the agent loop hits a tool whose preflight returned `needsInput`;
+  // consulted by `resumeWithInput()` to look up which paused tool call to
+  // re-feed with the user's submitted values. Cleared on resume (whether
+  // success or abandonment via a fresh `submitMessage`). Multiple concurrent
+  // entries are allowed in principle (LLM could call two `add_recipient`s
+  // in one turn) but in practice we yield + return on the FIRST hit, so
+  // the map is almost always 0 or 1 entries deep.
+  pendingInputs = /* @__PURE__ */ new Map();
   constructor(config) {
     this.provider = config.provider;
     this.agent = config.agent;
@@ -7168,6 +7375,159 @@ var QueryEngine = class {
       }
     }
   }
+  /**
+   * [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).
+   */
+  async *resumeWithInput(pendingInput, values) {
+    this.abortController = new AbortController();
+    const signal = this.abortController.signal;
+    if (pendingInput.assistantContent.length > 0) {
+      this.messages.push({
+        role: "assistant",
+        content: pendingInput.assistantContent
+      });
+    }
+    const tool = findTool(this.tools, pendingInput.toolName);
+    let resumedToolResult;
+    let toolResultEventPayload;
+    if (!tool) {
+      const errorPayload = {
+        error: `Tool "${pendingInput.toolName}" not found on resume \u2014 engine may have been reconfigured between pause and resume.`,
+        _hostBugMissingTool: true
+      };
+      resumedToolResult = {
+        content: JSON.stringify(errorPayload),
+        isError: true
+      };
+      toolResultEventPayload = { result: errorPayload, isError: true };
+    } else {
+      const preflightCheck = tool.preflight ? tool.preflight(values) : { valid: true };
+      if (!preflightCheck.valid && "error" in preflightCheck) {
+        const errorPayload = {
+          error: `Form values failed re-validation: ${preflightCheck.error}`,
+          _hostFormValidationFailed: true
+        };
+        resumedToolResult = {
+          content: JSON.stringify(errorPayload),
+          isError: true
+        };
+        toolResultEventPayload = { result: errorPayload, isError: true };
+      } else if (!preflightCheck.valid && "needsInput" in preflightCheck) {
+        const errorPayload = {
+          error: "Tool requested another form on resume \u2014 multi-step forms are not supported in v0.1.3. Re-prompt the user with a fresh single-step request.",
+          _multiStepFormUnsupported: true
+        };
+        resumedToolResult = {
+          content: JSON.stringify(errorPayload),
+          isError: true
+        };
+        toolResultEventPayload = { result: errorPayload, isError: true };
+      } else {
+        const parsed = tool.inputSchema.safeParse(values);
+        if (!parsed.success) {
+          const errorPayload = {
+            error: `Invalid input on resume: ${parsed.error.issues.map((i) => i.message).join(", ")}`,
+            _hostFormZodFailed: true
+          };
+          resumedToolResult = {
+            content: JSON.stringify(errorPayload),
+            isError: true
+          };
+          toolResultEventPayload = { result: errorPayload, isError: true };
+        } else {
+          const context = {
+            agent: this.agent,
+            mcpManager: this.mcpManager,
+            walletAddress: this.walletAddress,
+            suiRpcUrl: this.suiRpcUrl,
+            serverPositions: this.serverPositions,
+            positionFetcher: this.positionFetcher,
+            env: this.env,
+            signal,
+            priceCache: this.priceCache,
+            permissionConfig: this.permissionConfig,
+            sessionSpendUsd: this.sessionSpendUsd,
+            blockvisionApiKey: this.blockvisionApiKey,
+            portfolioCache: this.portfolioCache
+          };
+          try {
+            const callResult = await tool.call(parsed.data, context);
+            resumedToolResult = {
+              content: JSON.stringify(callResult.data),
+              isError: false
+            };
+            toolResultEventPayload = { result: callResult.data, isError: false };
+          } catch (err) {
+            const message = err instanceof Error ? err.message : "Tool execution failed";
+            const errorPayload = { error: message };
+            resumedToolResult = {
+              content: JSON.stringify(errorPayload),
+              isError: true
+            };
+            toolResultEventPayload = { result: errorPayload, isError: true };
+          }
+        }
+      }
+    }
+    const userMessageBlocks = [
+      ...pendingInput.completedResults.map((r) => ({
+        type: "tool_result",
+        toolUseId: r.toolUseId,
+        content: r.content,
+        isError: r.isError
+      })),
+      {
+        type: "tool_result",
+        toolUseId: pendingInput.toolUseId,
+        content: resumedToolResult.content,
+        isError: resumedToolResult.isError
+      }
+    ];
+    this.messages.push({ role: "user", content: userMessageBlocks });
+    yield {
+      type: "tool_result",
+      toolName: pendingInput.toolName,
+      toolUseId: pendingInput.toolUseId,
+      result: toolResultEventPayload.result,
+      isError: toolResultEventPayload.isError
+    };
+    this.pendingInputs.delete(pendingInput.inputId);
+    this.turnPaused = false;
+    try {
+      yield* this.agentLoop(null, signal, false);
+    } finally {
+      if (!this.turnPaused) {
+        this.turnReadCache.clear();
+      }
+    }
+  }
   /**
    * [v1.5] Auto-run configured read tools after a successful write,
    * push their results into the conversation, and yield `tool_result`
@@ -7338,6 +7698,25 @@ var QueryEngine = class {
   }
   loadMessages(messages) {
     this.messages = [...messages];
+    this.rehydrateProactiveCooldown();
+  }
+  /**
+   * [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.
+   */
+  rehydrateProactiveCooldown() {
+    for (const message of this.messages) {
+      if (message.role !== "assistant") continue;
+      const blocks = Array.isArray(message.content) ? message.content : [];
+      for (const block of blocks) {
+        if (block.type !== "text" || typeof block.text !== "string") continue;
+        for (const { proactiveType, subjectKey } of extractAllProactiveMarkers(block.text)) {
+          this.proactiveCooldown.add(`${proactiveType}:${subjectKey}`);
+        }
+      }
+    }
   }
   /**
    * [v0.46.7] Run a read-only tool out-of-band, using the engine's tool
@@ -7745,6 +8124,45 @@ ${recipeCtx}`;
             });
             continue;
           }
+          if (check.needsInput) {
+            const inputId = randomUUID();
+            const pendingInput = {
+              inputId,
+              toolName: call.name,
+              toolUseId: call.id,
+              schema: check.needsInput.schema,
+              description: check.needsInput.description,
+              assistantContent: acc.assistantBlocks,
+              completedResults: toolResultBlocks.map((b) => ({
+                toolUseId: b.toolUseId,
+                content: b.content,
+                isError: b.isError ?? false
+              }))
+            };
+            this.pendingInputs.set(inputId, pendingInput);
+            this.turnPaused = true;
+            getTelemetrySink().counter("engine.pending_input_emitted", {
+              tool: call.name
+            });
+            yield {
+              type: "pending_input",
+              inputId,
+              toolName: call.name,
+              toolUseId: call.id,
+              schema: check.needsInput.schema,
+              description: check.needsInput.description,
+              // [SPEC 9 v0.1.3 P9.4] Round-trip fields on the wire so
+              // stateless hosts (audric — request-scoped engines) can
+              // persist + echo back on resume. In-process hosts (CLI,
+              // long-lived engine instances) can ignore — the engine
+              // also stashes the state on `this.pendingInputs[inputId]`
+              // for in-memory recall.
+              assistantContent: pendingInput.assistantContent,
+              completedResults: pendingInput.completedResults
+            };
+            recordTurnOutcome("pending_input");
+            return;
+          }
           if (check.injections.length > 0) {
             call._guardInjections = check.injections;
           }
@@ -8081,6 +8499,32 @@ ${recipeCtx}`;
         yield { type: "text_delta", text: event.text };
         break;
       }
+      case "text_done": {
+        if (event.proactiveMarker) {
+          const { proactiveType, subjectKey, body, markerCount } = event.proactiveMarker;
+          const dedupKey = `${proactiveType}:${subjectKey}`;
+          const suppressed = this.proactiveCooldown.has(dedupKey);
+          if (!suppressed) this.proactiveCooldown.add(dedupKey);
+          const sink = getTelemetrySink();
+          if (suppressed) {
+            sink.counter("audric.harness.proactive_text_suppressed_count", { reason: "cooldown" }, 1);
+          } else {
+            sink.counter("audric.harness.proactive_text_emitted_count", { type: proactiveType }, 1);
+          }
+          if (markerCount > 1) {
+            sink.counter("audric.harness.proactive_marker_violations_count", {}, 1);
+          }
+          yield {
+            type: "proactive_text",
+            proactiveType,
+            subjectKey,
+            body,
+            suppressed,
+            markerCount
+          };
+        }
+        break;
+      }
       case "tool_use_done": {
         if (acc.text) {
           acc.assistantBlocks.push({ type: "text", text: acc.text });
@@ -8680,7 +9124,7 @@ function classifyEffort(model, userMessage, matchedRecipe, sessionWriteCount) {
 }
 
 // src/eval-summary.ts
-var MARKER_REGEX = /<eval_summary>([\s\S]*?)<\/eval_summary>/g;
+var MARKER_REGEX2 = /<eval_summary>([\s\S]*?)<\/eval_summary>/g;
 var VALID_STATUSES = /* @__PURE__ */ new Set([
   "good",
   "warning",
@@ -8690,7 +9134,7 @@ var VALID_STATUSES = /* @__PURE__ */ new Set([
 function parseEvalSummary(thinkingText) {
   if (!thinkingText.includes("<eval_summary>")) return null;
   const matches = [];
-  for (const match of thinkingText.matchAll(MARKER_REGEX)) {
+  for (const match of thinkingText.matchAll(MARKER_REGEX2)) {
     matches.push(match[1] ?? "");
   }
   if (matches.length === 0) return null;
@@ -8791,7 +9235,10 @@ context is worth mentioning. ${brevityGuidance}
 - Would seem pushy or sales-y
 
 ${styleGuidance}
-Format: One sentence maximum, after main response, separated by a line break.
+Format: One sentence maximum, AFTER your main response, separated by a line break, WRAPPED in a \`<proactive type="..." subjectKey="...">BODY</proactive>\` block. The host renders the wrapped block with the "\u2726 ADDED BY AUDRIC" lockup styling \u2014 without the wrapper the host shows only plain text and the engine's per-session cooldown won't deduplicate future repeats (so the same nudge re-fires every turn).
+Allowed types (closed list \u2014 anything else is dropped by the host): \`idle_balance\` (cash sitting idle that could earn yield), \`hf_warning\` (debt approaching liquidation), \`apy_drift\` (rate change on a position they hold), \`goal_progress\` (update on a saved goal).
+\`subjectKey\` is a stable identifier for the SPECIFIC subject (e.g. "USDC" for an idle-USDC insight, "1.45" for HF at that level, "tokyo-trip" for a saved goal). Same (type, subjectKey) won't fire twice in one session \u2014 pick the same key for the same subject so cooldown works.
+Example (post-answer suffix form): \`<proactive type="goal_progress" subjectKey="tokyo-trip">Your Tokyo goal is $80 behind pace.</proactive>\`
 Frame as observation, not advice: "Your Tokyo goal is $80 behind pace." \u2014 not "You should deposit more."`;
 }
 function buildSelfEvaluationInstruction() {
@@ -9223,6 +9670,7 @@ var AnthropicProvider = class {
     const stream = params.signal ? this.client.messages.stream(streamParams, { signal: params.signal }) : this.client.messages.stream(streamParams);
     const toolInputBuffers = /* @__PURE__ */ new Map();
     const thinkingBuffers = /* @__PURE__ */ new Map();
+    const textBuffers = /* @__PURE__ */ new Map();
     let outputTokensFromStart = 0;
     try {
       for await (const event of stream) {
@@ -9264,12 +9712,16 @@ var AnthropicProvider = class {
               thinkingBuffers.set(event.index, { type: "thinking", text: "", signature: "" });
             } else if (block.type === "redacted_thinking") {
               thinkingBuffers.set(event.index, { type: "redacted_thinking", data: block.data ?? "" });
+            } else if (block.type === "text") {
+              textBuffers.set(event.index, { text: "" });
             }
             break;
           }
           case "content_block_delta": {
             const delta = event.delta;
             if (delta.type === "text_delta") {
+              const buf = textBuffers.get(event.index);
+              if (buf) buf.text += delta.text ?? "";
               yield { type: "text_delta", text: delta.text };
             } else if (delta.type === "input_json_delta") {
               const buf = toolInputBuffers.get(event.index);
@@ -9323,6 +9775,15 @@ var AnthropicProvider = class {
               yield { type: "redacted_thinking", data: thinkBuf.data };
               thinkingBuffers.delete(event.index);
             }
+            const textBuf = textBuffers.get(event.index);
+            if (textBuf) {
+              const proactiveMarker = parseProactiveMarker(textBuf.text);
+              yield {
+                type: "text_done",
+                ...proactiveMarker ? { proactiveMarker } : {}
+              };
+              textBuffers.delete(event.index);
+            }
             break;
           }
           case "message_delta": {
@@ -9531,6 +9992,6 @@ function sanitizeAnthropicMessages(messages) {
   return merged;
 }
 
-export { AnthropicProvider, BalanceTracker, CANVAS_TEMPLATES, ContextBudget, CostTracker, DEFAULT_GUARD_CONFIG, DEFAULT_LEASE_SEC, DEFAULT_PERMISSION_CONFIG, DEFAULT_POLL_BUDGET_MS, DEFAULT_POLL_INTERVAL_MS, DEFAULT_SYSTEM_PROMPT, DEFAULT_TOOL_TTL_MS, EFFORT_THINKING_BUDGET_CAPS, EarlyToolDispatcher, InMemoryDefiCacheStore, InMemoryFetchLock, InMemoryNaviCacheStore, InMemoryWalletCacheStore, InvalidAddressError, MAX_BUNDLE_OPS, McpClientManager, McpResponseCache, MemorySessionStore, NAVI_ADDR_TTL_SEC, NAVI_MCP_CONFIG, NAVI_MCP_URL, NAVI_RATES_TTL_SEC, NAVI_SERVER_NAME, NaviTools, PERMISSION_PRESETS, QueryEngine, READ_TOOLS, REGENERATABLE_READ_TOOLS, RecipeRegistry, RetryTracker, SUINS_NAME_REGEX, SUI_ADDRESS_REGEX, SUI_ADDRESS_STRICT_REGEX, SuinsNotRegisteredError, SuinsRpcError, TOOL_FLAGS, TOOL_MODIFIABLE_FIELDS, TOOL_TTL_MS, TxMutex, VALID_PAIRS, WRITE_TOOLS, _resetNaviCircuitBreaker, activitySummaryTool, adaptAllMcpTools, adaptAllServerTools, adaptMcpTool, 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 { AnthropicProvider, BalanceTracker, CANVAS_TEMPLATES, ContextBudget, CostTracker, DEFAULT_GUARD_CONFIG, DEFAULT_LEASE_SEC, DEFAULT_PERMISSION_CONFIG, DEFAULT_POLL_BUDGET_MS, DEFAULT_POLL_INTERVAL_MS, DEFAULT_SYSTEM_PROMPT, DEFAULT_TOOL_TTL_MS, EFFORT_THINKING_BUDGET_CAPS, EarlyToolDispatcher, InMemoryDefiCacheStore, InMemoryFetchLock, InMemoryNaviCacheStore, InMemoryWalletCacheStore, InvalidAddressError, MAX_BUNDLE_OPS, McpClientManager, McpResponseCache, MemorySessionStore, NAVI_ADDR_TTL_SEC, NAVI_MCP_CONFIG, NAVI_MCP_URL, NAVI_RATES_TTL_SEC, NAVI_SERVER_NAME, NaviTools, PERMISSION_PRESETS, QueryEngine, READ_TOOLS, REGENERATABLE_READ_TOOLS, RecipeRegistry, RetryTracker, SUINS_NAME_REGEX, SUI_ADDRESS_REGEX, SUI_ADDRESS_STRICT_REGEX, SuinsNotRegisteredError, SuinsRpcError, TOOL_FLAGS, TOOL_MODIFIABLE_FIELDS, TOOL_TTL_MS, TxMutex, VALID_PAIRS, WRITE_TOOLS, _resetNaviCircuitBreaker, activitySummaryTool, adaptAllMcpTools, adaptAllServerTools, adaptMcpTool, addRecipientTool, applyToolFlags, awaitOrFetch, balanceCheckTool, borrowTool, budgetToolResult, buildCachedSystemPrompt, buildMcpTools, buildProactivenessInstructions, buildProfileContext, buildSelfEvaluationInstruction, buildStateContext, buildTool, bundleShortestTtl, checkValidPair, claimRewardsTool, clampThinkingForEffort, classifyEffort, clearPortfolioCache, clearPortfolioCacheFor, clearPriceMapCache, compactMessages, composeBundleFromToolResults, computeRegenerateFields, createGuardRunnerState, engineToSSE, estimateTokens, explainTxTool, extractAllProactiveMarkers, extractConversationText, extractMcpText, 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 };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map