@t2000/engine 0.41.0 → 0.43.0

package/dist/index.d.ts

@@ -432,6 +432,16 @@ type EngineEvent = {
      * actually re-running the tool.
      */
     resultDeduped?: boolean;
+    /**
+     * [v1.5] True when this result was produced by the engine's
+     * post-write refresh mechanism (see `EngineConfig.postWriteRefresh`).
+     * The engine auto-runs configured read tools immediately after a
+     * successful write so the LLM narrates from fresh on-chain state
+     * instead of inferring from a stale snapshot. Hosts should render
+     * these like any other tool result; the flag is for analytics and
+     * UI affordances (e.g. a subtle "auto-refreshed" badge).
+     */
+    wasPostWriteRefresh?: boolean;
 } | {
     type: 'pending_action';
     action: PendingAction;
@@ -615,6 +625,18 @@ interface Tool<TInput = unknown, TOutput = unknown> {
     maxResultSizeChars?: number;
     /** Custom truncation strategy. Falls back to generic slice + hint when omitted. */
     summarizeOnTruncate?: (result: string, maxChars: number) => string;
+    /**
+     * [v1.5.1] Whether `microcompact` may dedupe this tool's results across
+     * multiple calls with identical input. Default `true` — most tools are
+     * effectively pure within a session (price lookups, protocol info,
+     * yield pools). Set to `false` for tools whose result depends on
+     * mutable on-chain state and therefore changes after writes
+     * (`balance_check`, `savings_info`, `health_check`,
+     * `transaction_history`). Non-cacheable tools are excluded from the
+     * `seen` map entirely, so neither this call nor any later call with
+     * the same input gets replaced with a "[Same result …]" back-reference.
+     */
+    cacheable?: boolean;
 }
 type ThinkingEffort = 'low' | 'medium' | 'high' | 'max';
 type ThinkingConfig = {
@@ -699,6 +721,43 @@ interface EngineConfig {
      * verdict→action mapping. Errors thrown by the host are caught.
      */
     onGuardFired?: (guard: GuardMetric) => void;
+    /**
+     * [v1.5] Map of write tool name → list of read tool names whose state
+     * the write invalidates. After a successful write resumes via
+     * `resumeWithToolResult`, the engine auto-runs each configured read
+     * tool with empty input, pushes synthetic `tool_use` + `tool_result`
+     * messages into the conversation, and yields `tool_result` events
+     * with `wasPostWriteRefresh: true` BEFORE handing control back to the
+     * LLM for narration.
+     *
+     * Why: writes change on-chain state. Without a fresh read, the LLM
+     * narrates from the pre-write snapshot and frequently invents balance
+     * totals. Auto-injecting fresh reads makes the hallucination class
+     * physically impossible — the model has authoritative ground truth in
+     * its context before generating the post-write sentence.
+     *
+     * Constraints:
+     *  - Refresh tools MUST be `isReadOnly` and `isConcurrencySafe`.
+     *  - Refresh runs only when the write succeeded (executionResult is
+     *    not `{ success: false }`); failed writes leave state unchanged
+     *    and refreshing would be misleading.
+     *  - Tools are invoked with empty input; refresh tools should accept
+     *    an empty object schema (e.g. `balance_check`, `savings_info`).
+     *  - Errors during refresh are non-fatal — a tool_result with
+     *    `isError: true` is still pushed so the LLM knows refresh failed.
+     *
+     * Example:
+     * ```
+     * {
+     *   save_deposit: ['balance_check', 'savings_info'],
+     *   send_transfer: ['balance_check'],
+     *   borrow: ['balance_check', 'savings_info', 'health_check'],
+     * }
+     * ```
+     *
+     * Omit (undefined / empty map) to disable post-write refresh entirely.
+     */
+    postWriteRefresh?: Record<string, string[]>;
 }
 interface LLMProvider {
     chat(params: ChatParams): AsyncGenerator<ProviderEvent>;
@@ -824,6 +883,7 @@ declare class QueryEngine {
     private readonly sessionSpendUsd;
     private readonly onAutoExecuted;
     private readonly onGuardFired;
+    private readonly postWriteRefresh;
     private matchedRecipe;
     private messages;
     private abortController;
@@ -845,6 +905,16 @@ declare class QueryEngine {
      * This is a separate HTTP request — no persistent connection from submitMessage.
      */
     resumeWithToolResult(action: PendingAction, response: PermissionResponse): AsyncGenerator<EngineEvent>;
+    /**
+     * [v1.5] Auto-run configured read tools after a successful write,
+     * push their results into the conversation, and yield `tool_result`
+     * events so hosts/UI render them in the timeline. See
+     * `EngineConfig.postWriteRefresh`.
+     *
+     * Pure injection — no LLM call here. The next `agentLoop` turn sees
+     * the fresh tool results and narrates from them.
+     */
+    private runPostWriteRefresh;
     interrupt(): void;
     getMessages(): readonly Message[];
     getMatchedRecipe(): Recipe | null;
@@ -887,6 +957,11 @@ interface BuildToolOptions<TInput, TOutput> {
     preflight?: (input: TInput) => PreflightResult;
     maxResultSizeChars?: number;
     summarizeOnTruncate?: (result: string, maxChars: number) => string;
+    /**
+     * [v1.5.1] See `Tool.cacheable`. Default `true`. Set `false` for
+     * tools whose results depend on mutable on-chain state.
+     */
+    cacheable?: boolean;
 }
 declare function buildTool<TInput, TOutput>(opts: BuildToolOptions<TInput, TOutput>): Tool<TInput, TOutput>;
 declare function toolsToDefinitions(tools: Tool[]): {
@@ -916,6 +991,9 @@ type SSEEvent = {
     toolUseId: string;
     result: unknown;
     isError: boolean;
+    wasEarlyDispatched?: boolean;
+    resultDeduped?: boolean;
+    wasPostWriteRefresh?: boolean;
 } | {
     type: 'pending_action';
     action: PendingAction;
@@ -1119,11 +1197,23 @@ interface MicrocompactResult extends Array<Message> {
  * the full prior result with a compact back-reference. Runs before any
  * LLM-based compaction and costs nothing.
  *
+ * [v1.5.1] Tools may opt out of dedupe by setting `cacheable: false` on
+ * their `Tool` definition. Non-cacheable tools (e.g. `balance_check`,
+ * `savings_info`, `health_check`, `transaction_history`) are excluded
+ * from the `seen` map entirely, so neither the current call nor any
+ * later call with identical inputs gets replaced — necessary because
+ * their results depend on mutable on-chain state that writes invalidate.
+ *
  * Returns a new array — does not mutate the input. The returned array
  * carries a `dedupedToolUseIds` property listing every tool-use ID whose
  * tool_result block was replaced with a back-reference this pass.
+ *
+ * @param messages — conversation ledger to compact.
+ * @param tools    — optional tool registry consulted to resolve the
+ *                   per-tool `cacheable` flag. Omit to dedupe every
+ *                   tool (legacy behavior — back-compat).
  */
-declare function microcompact(messages: readonly Message[]): MicrocompactResult;
+declare function microcompact(messages: readonly Message[], tools?: readonly Tool[]): MicrocompactResult;
 
 /**
  * EarlyToolDispatcher — dispatches read-only tools mid-stream.

package/dist/index.js

@@ -23,7 +23,8 @@ function buildTool(opts) {
     flags: opts.flags ?? {},
     preflight: opts.preflight,
     maxResultSizeChars: opts.maxResultSizeChars,
-    summarizeOnTruncate: opts.summarizeOnTruncate
+    summarizeOnTruncate: opts.summarizeOnTruncate,
+    cacheable: opts.cacheable
   };
 }
 function toolsToDefinitions(tools) {
@@ -557,6 +558,10 @@ var balanceCheckTool = buildTool({
   inputSchema: z.object({}),
   jsonSchema: { type: "object", properties: {}, required: [] },
   isReadOnly: true,
+  // [v1.5.1] Wallet contents change after every send/swap/save/etc.
+  // Microcompact must NEVER dedupe these calls — each one reflects a
+  // different on-chain state.
+  cacheable: false,
   async call(_input, context) {
     if (hasNaviMcp(context)) {
       const address = getWalletAddress(context);
@@ -850,6 +855,9 @@ var savingsInfoTool = buildTool({
   inputSchema: z.object({}),
   jsonSchema: { type: "object", properties: {}, required: [] },
   isReadOnly: true,
+  // [v1.5.1] NAVI deposits change on save_deposit / withdraw / claim.
+  // Each call reflects a fresh on-chain snapshot — never dedupe.
+  cacheable: false,
   async call(_input, context) {
     if (context.positionFetcher && context.walletAddress) {
       const sp = await context.positionFetcher(context.walletAddress);
@@ -910,6 +918,9 @@ var healthCheckTool = buildTool({
   inputSchema: z.object({}),
   jsonSchema: { type: "object", properties: {}, required: [] },
   isReadOnly: true,
+  // [v1.5.1] Health factor changes on every borrow / repay / collateral
+  // movement and even passively as oracle prices update. Never dedupe.
+  cacheable: false,
   async call(_input, context) {
     if (context.positionFetcher && context.walletAddress) {
       const sp = await context.positionFetcher(context.walletAddress);
@@ -1151,6 +1162,10 @@ var transactionHistoryTool = buildTool({
   },
   isReadOnly: true,
   maxResultSizeChars: 8e3,
+  // [v1.5.1] New transactions land continuously. Even with an explicit
+  // `date` filter the dedupe is wrong post-write because the just-
+  // executed write may now be in history. Never dedupe.
+  cacheable: false,
   async call(input, context) {
     const limit = input.limit ?? 10;
     const action = input.action;
@@ -3724,15 +3739,23 @@ function extractConversationText(messages) {
 }
 
 // src/compact/microcompact.ts
-function microcompact(messages) {
+function microcompact(messages, tools) {
   const seen = /* @__PURE__ */ new Map();
   let toolUseIndex = 0;
   const toolUseInputs = /* @__PURE__ */ new Map();
+  const cacheableByName = /* @__PURE__ */ new Map();
+  if (tools) {
+    for (const t of tools) {
+      cacheableByName.set(t.name, t.cacheable ?? true);
+    }
+  }
   const dedupedToolUseIds = /* @__PURE__ */ new Set();
+  const toolNameById = /* @__PURE__ */ new Map();
   for (const msg of messages) {
     for (const block of msg.content) {
       if (block.type === "tool_use") {
         toolUseInputs.set(block.id, `${block.name}:${stableStringify(block.input)}`);
+        toolNameById.set(block.id, block.name);
       }
     }
   }
@@ -3744,6 +3767,11 @@ function microcompact(messages) {
       if (block.type !== "tool_result") return block;
       const key = toolUseInputs.get(block.toolUseId);
       if (!key) return block;
+      const toolName = toolNameById.get(block.toolUseId);
+      if (toolName && cacheableByName.get(toolName) === false) {
+        toolUseIndex++;
+        return block;
+      }
       toolUseIndex++;
       const prior = seen.get(key);
       if (prior && !block.isError) {
@@ -4177,6 +4205,9 @@ var QueryEngine = class {
   sessionSpendUsd;
   onAutoExecuted;
   onGuardFired;
+  // [v1.5] See `EngineConfig.postWriteRefresh` — drives the post-write
+  // synthetic read injection in `resumeWithToolResult`.
+  postWriteRefresh;
   matchedRecipe = null;
   messages = [];
   abortController = null;
@@ -4209,6 +4240,7 @@ var QueryEngine = class {
     this.sessionSpendUsd = config.sessionSpendUsd;
     this.onAutoExecuted = config.onAutoExecuted;
     this.onGuardFired = config.onGuardFired;
+    this.postWriteRefresh = config.postWriteRefresh;
     this.tools = config.tools ?? (config.agent ? getDefaultTools() : []);
   }
   /**
@@ -4277,8 +4309,96 @@ var QueryEngine = class {
       yield { type: "turn_complete", stopReason: "end_turn" };
       return;
     }
+    yield* this.runPostWriteRefresh(action, response, signal);
     yield* this.agentLoop(null, signal, false);
   }
+  /**
+   * [v1.5] Auto-run configured read tools after a successful write,
+   * push their results into the conversation, and yield `tool_result`
+   * events so hosts/UI render them in the timeline. See
+   * `EngineConfig.postWriteRefresh`.
+   *
+   * Pure injection — no LLM call here. The next `agentLoop` turn sees
+   * the fresh tool results and narrates from them.
+   */
+  async *runPostWriteRefresh(action, response, signal) {
+    const refreshList = this.postWriteRefresh?.[action.toolName];
+    if (!refreshList || refreshList.length === 0) return;
+    const exec = response.executionResult;
+    const writeFailed = exec != null && typeof exec === "object" && "success" in exec && exec.success === false;
+    if (writeFailed) return;
+    const refreshTools = refreshList.map((name) => findTool(this.tools, name)).filter(
+      (t) => t !== void 0 && t.isReadOnly && t.isConcurrencySafe
+    );
+    if (refreshTools.length === 0) return;
+    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
+    };
+    const idStem = `pwr_${action.toolUseId.slice(-6)}`;
+    const refreshes = await Promise.all(
+      refreshTools.map(async (tool, idx) => {
+        const id = `${idStem}_${idx}_${tool.name}`;
+        try {
+          const parsed = tool.inputSchema.safeParse({});
+          if (!parsed.success) {
+            return {
+              tool,
+              id,
+              isError: true,
+              data: {
+                error: `Post-write refresh: invalid input for ${tool.name}`
+              }
+            };
+          }
+          const result = await tool.call(parsed.data, context);
+          return { tool, id, isError: false, data: result.data };
+        } catch (err) {
+          return {
+            tool,
+            id,
+            isError: true,
+            data: {
+              error: err instanceof Error ? err.message : "Post-write refresh failed"
+            }
+          };
+        }
+      })
+    );
+    const refreshUses = refreshes.map((r) => ({
+      type: "tool_use",
+      id: r.id,
+      name: r.tool.name,
+      input: {}
+    }));
+    this.messages.push({ role: "assistant", content: refreshUses });
+    const refreshResults = refreshes.map((r) => ({
+      type: "tool_result",
+      toolUseId: r.id,
+      content: typeof r.data === "string" ? r.data : JSON.stringify(r.data),
+      isError: r.isError
+    }));
+    this.messages.push({ role: "user", content: refreshResults });
+    for (const r of refreshes) {
+      yield {
+        type: "tool_result",
+        toolName: r.tool.name,
+        toolUseId: r.id,
+        result: r.data,
+        isError: r.isError,
+        wasPostWriteRefresh: true
+      };
+    }
+  }
   interrupt() {
     this.abortController?.abort();
   }
@@ -4350,7 +4470,7 @@ var QueryEngine = class {
       };
       const dispatcher = new EarlyToolDispatcher(this.tools, context);
       try {
-        const microcompacted = microcompact(this.messages);
+        const microcompacted = microcompact(this.messages, this.tools);
         this.messages = microcompacted;
         for (const dedupedId of microcompacted.dedupedToolUseIds) {
           yield {