@t2000/engine 1.10.1 → 1.11.0

package/dist/index.d.ts

@@ -279,6 +279,18 @@ declare class BalanceTracker {
     private lastBalanceAt;
     private lastWriteAt;
     recordRead(): void;
+    /**
+     * [v1.11 F2] Seed `lastBalanceAt` from an external snapshot timestamp.
+     * Used by the engine constructor when the host passes
+     * `EngineConfig.financialContextSeed.balanceAt` — i.e. the system
+     * prompt already embeds a fresh balance snapshot from that time so
+     * the LLM has authoritative balance data without the host
+     * round-tripping a `balance_check` tool call first. Pre-fix the
+     * `Balance has not been checked this session` hint fired on every
+     * first-turn write, even when audric had just embedded the daily
+     * `<financial_context>` block — pure noise for the LLM and the user.
+     */
+    recordReadAt(at: number): void;
     recordWrite(): void;
     isStale(): boolean;
     hasEverRead(): boolean;
@@ -1311,6 +1323,45 @@ interface EngineConfig {
         usdValue: number;
         walletAddress?: string;
     }) => void | Promise<void>;
+    /**
+     * [v1.11 F2] Trust signal from the host: the system prompt already
+     * embeds a fresh financial-context snapshot covering balance + HF as
+     * of `balanceAt` (Unix ms). Pre-seeds the guard runner so the
+     * "Balance has not been checked this session" / "Health factor has
+     * not been checked this session" hints DON'T fire on the first turn.
+     *
+     * Pre-v1.11 the guards started cold every chat: the LLM saw the
+     * `<financial_context>` block in the system prompt (with balances +
+     * HF baked in) but the BalanceTracker still reported `hasEverRead()`
+     * = false, so every first-turn write got pinged with a redundant
+     * "call balance_check first" hint. Audric's UC1/UC2/UC3 P2.6 runs
+     * showed the noise verbatim ("Balance not checked this session"
+     * appeared on every first-turn permission card).
+     *
+     * Why a host-supplied seed (vs. engine sniffing the system prompt):
+     * the engine doesn't own the prompt format. Audric builds
+     * `<financial_context>` from `UserFinancialContext`; another host
+     * may not (Audric CLI, server-signed automations). Having the host
+     * pass an explicit seed keeps the engine prompt-agnostic.
+     *
+     * Stale snapshots (>30min old): still seed. The LLM can judge
+     * whether to call `balance_check` for a fresh value based on the
+     * snapshot timestamp surfaced inside the financial-context block;
+     * the guard's job is to prevent unprompted writes against
+     * unknown-state, NOT to enforce a freshness SLA.
+     */
+    financialContextSeed?: {
+        /** Unix ms timestamp of the snapshot. Any non-zero value seeds `lastBalanceAt`. */
+        balanceAt?: number;
+        /**
+         * Health factor at snapshot time. Pass `null` if the user has no
+         * debt (HF undefined / Infinity in audric — render the snapshot
+         * row as "no debt" and don't seed). Pass a number to skip the
+         * "Health factor has not been checked this session" hint on
+         * first-turn write.
+         */
+        healthFactor?: number | null;
+    };
     /**
      * [v1.4 Item 4] Per-guard observation hook. Forwarded to `runGuards`
      * and fired once per non-`pass` verdict so hosts can record guard

package/dist/index.js

@@ -5575,6 +5575,22 @@ var BalanceTracker = class {
   recordRead() {
     this.lastBalanceAt = Date.now();
   }
+  /**
+   * [v1.11 F2] Seed `lastBalanceAt` from an external snapshot timestamp.
+   * Used by the engine constructor when the host passes
+   * `EngineConfig.financialContextSeed.balanceAt` — i.e. the system
+   * prompt already embeds a fresh balance snapshot from that time so
+   * the LLM has authoritative balance data without the host
+   * round-tripping a `balance_check` tool call first. Pre-fix the
+   * `Balance has not been checked this session` hint fired on every
+   * first-turn write, even when audric had just embedded the daily
+   * `<financial_context>` block — pure noise for the LLM and the user.
+   */
+  recordReadAt(at) {
+    if (at > this.lastBalanceAt) {
+      this.lastBalanceAt = at;
+    }
+  }
   recordWrite() {
     this.lastWriteAt = Date.now();
   }
@@ -6832,6 +6848,15 @@ var QueryEngine = class {
     this.costTracker = new CostTracker(config.costTracker);
     this.guardConfig = config.guards;
     this.guardState = createGuardRunnerState();
+    if (config.financialContextSeed) {
+      const { balanceAt, healthFactor } = config.financialContextSeed;
+      if (typeof balanceAt === "number" && balanceAt > 0) {
+        this.guardState.balanceTracker.recordReadAt(balanceAt);
+      }
+      if (typeof healthFactor === "number") {
+        this.guardState.lastHealthFactor = healthFactor;
+      }
+    }
     this.recipes = config.recipes;
     this.contextBudget = new ContextBudget(config.contextBudget);
     this.contextSummarizer = config.contextSummarizer;