@t2000/engine 0.41.0 → 0.42.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;
@@ -699,6 +709,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 +871,7 @@ declare class QueryEngine {
     private readonly sessionSpendUsd;
     private readonly onAutoExecuted;
     private readonly onGuardFired;
+    private readonly postWriteRefresh;
     private matchedRecipe;
     private messages;
     private abortController;
@@ -845,6 +893,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;
@@ -916,6 +974,9 @@ type SSEEvent = {
     toolUseId: string;
     result: unknown;
     isError: boolean;
+    wasEarlyDispatched?: boolean;
+    resultDeduped?: boolean;
+    wasPostWriteRefresh?: boolean;
 } | {
     type: 'pending_action';
     action: PendingAction;

package/dist/index.js

@@ -4177,6 +4177,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 +4212,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 +4281,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();
   }