@t2000/engine 0.46.7 → 0.46.8

package/dist/index.d.ts

@@ -888,6 +888,8 @@ declare class QueryEngine {
     private messages;
     private abortController;
     private guardEvents;
+    private readonly turnReadCache;
+    private turnPaused;
     constructor(config: EngineConfig);
     /**
      * Submit a user message and stream engine events.
@@ -1241,6 +1243,89 @@ interface MicrocompactResult extends Array<Message> {
  */
 declare function microcompact(messages: readonly Message[], tools?: readonly Tool[]): MicrocompactResult;
 
+/**
+ * [v0.46.8] Intra-turn deduplication of read-only tool calls.
+ *
+ * # Problem
+ * Two independent execution paths can call the same read-only tool within
+ * the same user turn:
+ *   1. Host pre-dispatch via `engine.invokeReadTool()` (deterministic — runs
+ *      before the LLM ever sees the message; injects a synthetic
+ *      `tool_use`+`tool_result` pair into the ledger so the card renders
+ *      immediately and the LLM has the data).
+ *   2. The LLM itself, mid-turn, emitting a `tool_use` block for the same
+ *      tool (often because the prompt says "always call balance_check on
+ *      direct read questions" and the model doesn't trust the synthetic
+ *      pair).
+ *
+ * Both paths emit a `tool_result` SSE event, the host renders BOTH cards,
+ * the user sees a duplicate. Coordinating these two paths via prompt rules
+ * is probabilistic ("DO NOT re-call when you see a synthetic pair") and
+ * has empirically shown ~30% miss rate — the LLM still re-calls anyway.
+ *
+ * # Fix
+ * Idempotent intra-turn cache. Within one user turn:
+ *   - Calling the same read-only tool with the same args twice returns the
+ *     cached result on the second call.
+ *   - The second call yields a `tool_result` event with `resultDeduped:true`
+ *     so hosts can skip rendering a duplicate card while the LLM still gets
+ *     the data it needs to satisfy its `tool_use` id.
+ *
+ * # Lifecycle
+ *   - Cache lives on the `QueryEngine` instance.
+ *   - Populated by `invokeReadTool` (host pre-dispatch) AND by the agent
+ *     loop's tool-execution path (LLM-driven calls).
+ *   - Cleared on `turn_complete` (clean slate for the next user turn).
+ *   - Cleared whenever a WRITE tool executes successfully (writes mutate
+ *     on-chain state, so any subsequent read in the same turn must re-fetch
+ *     for freshness).
+ *   - Cleared on errors / abort (defensive cleanup).
+ *
+ * # Why not just extend microcompact?
+ * `microcompact` does CROSS-turn dedup, but explicitly excludes
+ * `cacheable: false` tools (balance_check, health_check, savings_info,
+ * transaction_history) so post-write refreshes always surface fresh data.
+ * Within a single turn (pre-write), those same tools are perfectly
+ * dedup-able — state can't change. This cache fills that exact gap.
+ *
+ * # Invariants
+ *   - Read-only tools only. Write tools never enter the cache.
+ *   - Errored results are NEVER cached (the next call should retry).
+ *   - Cache key includes the full input, stably stringified — different
+ *     filter args (e.g. `transaction_history({minUsd:5})` vs
+ *     `transaction_history({})`) hit different cache entries.
+ */
+declare class TurnReadCache {
+    private readonly store;
+    /**
+     * Build the cache key for a (toolName, input) pair. Stable across object
+     * key ordering so `{a:1,b:2}` and `{b:2,a:1}` map to the same entry.
+     */
+    static keyFor(toolName: string, input: unknown): string;
+    has(key: string): boolean;
+    get(key: string): {
+        result: unknown;
+        sourceToolUseId: string;
+    } | undefined;
+    /**
+     * Populate the cache. Caller is responsible for ensuring the result was
+     * a successful read (no errors). Overwrites any prior entry for the same
+     * key — the most recent successful read wins, which is correct under our
+     * "writes invalidate the whole cache" invariant.
+     */
+    set(key: string, value: {
+        result: unknown;
+        sourceToolUseId: string;
+    }): void;
+    /**
+     * Drop every entry. Called at turn end and after every successful write.
+     * Cheap and intentional — the cache is small (a handful of entries per
+     * turn at most) and clearing is the correct response to any state mutation.
+     */
+    clear(): void;
+    size(): number;
+}
+
 /**
  * EarlyToolDispatcher — dispatches read-only tools mid-stream.
  *
@@ -1257,11 +1342,21 @@ declare class EarlyToolDispatcher {
     private entries;
     private readonly tools;
     private readonly context;
+    private readonly turnReadCache;
     private abortController;
-    constructor(tools: Tool[], context: ToolContext);
+    constructor(tools: Tool[], context: ToolContext, turnReadCache?: TurnReadCache);
     /**
      * Attempt to dispatch a tool call. Returns true if the tool was dispatched
      * (read-only + concurrency-safe), false if it should be queued for later.
+     *
+     * [v0.46.8] Cache-aware: if a `TurnReadCache` was supplied at
+     * construction and a prior call this turn already produced a result
+     * for the same `(toolName, input)`, the dispatcher returns true (the
+     * call IS handled here, not queued for the post-stream loop) but
+     * skips the tool execution entirely — `collectResults` will surface
+     * the cached value with `resultDeduped: true`. On a cache miss for
+     * a successful real execution, the result is written back to the
+     * cache so any later call within the same turn dedups too.
      */
     tryDispatch(call: PendingToolCall): boolean;
     /** True if any tools have been dispatched. */

package/dist/index.js

@@ -4257,27 +4257,116 @@ function safeNum(v) {
   return isNaN(n) ? 0 : n;
 }
 
+// src/turn-read-cache.ts
+var TurnReadCache = class {
+  store = /* @__PURE__ */ new Map();
+  /**
+   * Build the cache key for a (toolName, input) pair. Stable across object
+   * key ordering so `{a:1,b:2}` and `{b:2,a:1}` map to the same entry.
+   */
+  static keyFor(toolName, input) {
+    return `${toolName}:${stableStringify2(input)}`;
+  }
+  has(key) {
+    return this.store.has(key);
+  }
+  get(key) {
+    return this.store.get(key);
+  }
+  /**
+   * Populate the cache. Caller is responsible for ensuring the result was
+   * a successful read (no errors). Overwrites any prior entry for the same
+   * key — the most recent successful read wins, which is correct under our
+   * "writes invalidate the whole cache" invariant.
+   */
+  set(key, value) {
+    this.store.set(key, value);
+  }
+  /**
+   * Drop every entry. Called at turn end and after every successful write.
+   * Cheap and intentional — the cache is small (a handful of entries per
+   * turn at most) and clearing is the correct response to any state mutation.
+   */
+  clear() {
+    this.store.clear();
+  }
+  size() {
+    return this.store.size;
+  }
+};
+function stableStringify2(value) {
+  if (value === null || value === void 0) return "";
+  if (typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return JSON.stringify(value.map(stableStringifyForObject));
+  return stableStringifyForObject(value);
+}
+function stableStringifyForObject(value) {
+  if (value === null || value === void 0) return JSON.stringify(value);
+  if (typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) {
+    return `[${value.map(stableStringifyForObject).join(",")}]`;
+  }
+  const sorted = Object.keys(value).sort();
+  const parts = sorted.map(
+    (k) => `${JSON.stringify(k)}:${stableStringifyForObject(value[k])}`
+  );
+  return `{${parts.join(",")}}`;
+}
+
 // src/early-dispatcher.ts
 var EarlyToolDispatcher = class {
   entries = [];
   tools;
   context;
+  turnReadCache;
   abortController;
-  constructor(tools, context) {
+  constructor(tools, context, turnReadCache) {
     this.tools = tools;
     this.context = context;
+    this.turnReadCache = turnReadCache;
     this.abortController = new AbortController();
   }
   /**
    * Attempt to dispatch a tool call. Returns true if the tool was dispatched
    * (read-only + concurrency-safe), false if it should be queued for later.
+   *
+   * [v0.46.8] Cache-aware: if a `TurnReadCache` was supplied at
+   * construction and a prior call this turn already produced a result
+   * for the same `(toolName, input)`, the dispatcher returns true (the
+   * call IS handled here, not queued for the post-stream loop) but
+   * skips the tool execution entirely — `collectResults` will surface
+   * the cached value with `resultDeduped: true`. On a cache miss for
+   * a successful real execution, the result is written back to the
+   * cache so any later call within the same turn dedups too.
    */
   tryDispatch(call) {
     const tool = findTool(this.tools, call.name);
     if (!tool || !tool.isReadOnly || !tool.isConcurrencySafe) return false;
+    if (this.turnReadCache) {
+      const cacheKey = TurnReadCache.keyFor(call.name, call.input);
+      const cached = this.turnReadCache.get(cacheKey);
+      if (cached) {
+        this.entries.push({
+          call,
+          tool,
+          promise: Promise.resolve({ data: cached.result, isError: false }),
+          deduped: true
+        });
+        return true;
+      }
+    }
     const childContext = { ...this.context, signal: this.abortController.signal };
-    const promise = executeTool(tool, call, childContext);
-    this.entries.push({ call, tool, promise });
+    const promise = executeTool(tool, call, childContext).then((result) => {
+      if (!result.isError && this.turnReadCache) {
+        const cacheKey = TurnReadCache.keyFor(call.name, call.input);
+        this.turnReadCache.set(cacheKey, {
+          result: result.data,
+          sourceToolUseId: call.id
+        });
+      }
+      return result;
+    });
+    this.entries.push({ call, tool, promise, deduped: false });
     return true;
   }
   /** True if any tools have been dispatched. */
@@ -4303,7 +4392,8 @@ var EarlyToolDispatcher = class {
           toolUseId: entry.call.id,
           result: budgeted,
           isError: result.isError,
-          wasEarlyDispatched: true
+          wasEarlyDispatched: true,
+          ...entry.deduped ? { resultDeduped: true } : {}
         };
       } catch (err) {
         yield {
@@ -4375,6 +4465,18 @@ var QueryEngine = class {
   messages = [];
   abortController = null;
   guardEvents = [];
+  // [v0.46.8] Intra-turn dedup cache for read-only tool calls. See
+  // `turn-read-cache.ts` for the full lifecycle. Key takeaway: the cache
+  // lives across the host's pre-dispatch (`invokeReadTool`) and the
+  // agent loop's LLM-driven tool execution within ONE user turn, then
+  // clears on `turn_complete` or after any successful write.
+  turnReadCache = new TurnReadCache();
+  // [v0.46.8] Set to `true` when the agent loop yields `pending_action`
+  // and returns (turn is paused awaiting user confirmation). The
+  // submitMessage / resumeWithToolResult wrappers consult this flag in
+  // 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;
   constructor(config) {
     this.provider = config.provider;
     this.agent = config.agent;
@@ -4426,7 +4528,14 @@ var QueryEngine = class {
       role: "user",
       content: [{ type: "text", text: prompt }]
     });
-    yield* this.agentLoop(prompt, signal);
+    this.turnPaused = false;
+    try {
+      yield* this.agentLoop(prompt, signal);
+    } finally {
+      if (!this.turnPaused) {
+        this.turnReadCache.clear();
+      }
+    }
   }
   /**
    * Resume the conversation after a pending action is resolved.
@@ -4470,10 +4579,19 @@ var QueryEngine = class {
     };
     if (!response.approved) {
       yield { type: "turn_complete", stopReason: "end_turn" };
+      this.turnReadCache.clear();
       return;
     }
+    this.turnReadCache.clear();
     yield* this.runPostWriteRefresh(action, response, signal);
-    yield* this.agentLoop(null, signal, false);
+    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,
@@ -4552,6 +4670,12 @@ var QueryEngine = class {
     }));
     this.messages.push({ role: "user", content: refreshResults });
     for (const r of refreshes) {
+      if (!r.isError) {
+        this.turnReadCache.set(
+          TurnReadCache.keyFor(r.tool.name, {}),
+          { result: r.data, sourceToolUseId: r.id }
+        );
+      }
       yield {
         type: "tool_result",
         toolName: r.tool.name,
@@ -4619,6 +4743,11 @@ var QueryEngine = class {
         `invokeReadTool: invalid input for ${toolName}: ${parsed.error.issues.map((i) => i.message).join(", ")}`
       );
     }
+    const cacheKey = TurnReadCache.keyFor(toolName, parsed.data);
+    const cached = this.turnReadCache.get(cacheKey);
+    if (cached) {
+      return { data: cached.result, isError: false };
+    }
     const signal = options.signal ?? new AbortController().signal;
     const context = {
       agent: this.agent,
@@ -4635,6 +4764,10 @@ var QueryEngine = class {
     };
     try {
       const result = await tool.call(parsed.data, context);
+      this.turnReadCache.set(cacheKey, {
+        result: result.data,
+        sourceToolUseId: "invokeReadTool"
+      });
       return { data: result.data, isError: false };
     } catch (err) {
       return {
@@ -4687,7 +4820,7 @@ var QueryEngine = class {
         assistantBlocks: [],
         pendingToolCalls: []
       };
-      const dispatcher = new EarlyToolDispatcher(this.tools, context);
+      const dispatcher = new EarlyToolDispatcher(this.tools, context, this.turnReadCache);
       try {
         const microcompacted = microcompact(this.messages, this.tools);
         this.messages = microcompacted;
@@ -4859,6 +4992,27 @@ ${recipeCtx}`;
       let pendingWrite = null;
       for (const call of acc.pendingToolCalls) {
         const tool = findTool(this.tools, call.name);
+        if (tool && tool.isReadOnly) {
+          const cacheKey = TurnReadCache.keyFor(call.name, call.input);
+          const cached = this.turnReadCache.get(cacheKey);
+          if (cached) {
+            yield {
+              type: "tool_result",
+              toolName: call.name,
+              toolUseId: call.id,
+              result: cached.result,
+              isError: false,
+              resultDeduped: true
+            };
+            toolResultBlocks.push({
+              type: "tool_result",
+              toolUseId: call.id,
+              content: JSON.stringify(cached.result),
+              isError: false
+            });
+            continue;
+          }
+        }
         const needsConfirmation = (() => {
           if (!tool || tool.isReadOnly) return false;
           if (tool.permissionLevel === "explicit") return true;
@@ -4972,6 +5126,18 @@ ${recipeCtx}`;
             }
           }
           const finalEvent = enrichedResult !== toolEvent.result ? { ...toolEvent, result: enrichedResult } : toolEvent;
+          if (!finalEvent.isError && tool) {
+            if (tool.isReadOnly) {
+              const inputForKey = originalCall?.input ?? {};
+              const cacheKey = TurnReadCache.keyFor(finalEvent.toolName, inputForKey);
+              this.turnReadCache.set(cacheKey, {
+                result: finalEvent.result,
+                sourceToolUseId: finalEvent.toolUseId
+              });
+            } else {
+              this.turnReadCache.clear();
+            }
+          }
           yield finalEvent;
           if (finalEvent.type === "tool_result" && !finalEvent.isError) {
             const r = finalEvent.result;
@@ -5048,6 +5214,7 @@ ${recipeCtx}`;
         const writeGuardInjections = pendingWrite.call._guardInjections;
         const modifiableFields = getModifiableFields(pendingWrite.call.name);
         const turnIndex = this.messages.filter((m) => m.role === "assistant").length;
+        this.turnPaused = true;
         yield {
           type: "pending_action",
           action: {