review: optional advisory fields, LLM/tool parity test, undate CHANGELOG

Address CodeRabbit feedback on #53:
- BudgetAdvisory.expectedCost / estCallsRemaining are now optional in TS, so
  the additive fields don't break any code constructing an advisory literal
  (advisory() still always sets them). Python already ships defaulted fields.
- Add a JS test asserting expectedCost is the costlier of the last LLM and tool
  call, matching the Python suite.
- Keep the CHANGELOG entry under Unreleased instead of a future release date.

Author: hatimanees

CHANGELOG.md

@@ -8,9 +8,7 @@ packages — `floe-guard` on [PyPI](https://pypi.org/project/floe-guard/) and
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
 both packages adhere to [Semantic Versioning](https://semver.org/).
 
-## Unreleased
-
-## py 0.11.0 / js 0.8.0 — 2026-07-25
+## Unreleased — py 0.11.0 / js 0.8.0
 
 ### Added (py + js)
 

js/src/guard.ts

@@ -117,14 +117,18 @@ export interface BudgetAdvisory {
    * The guard's own next-call estimate (the costlier of the last LLM and last
    * tool call — the same value the default reservation uses). 0 until the first
    * call is recorded, so a planner can't divide by a cold estimate.
+   *
+   * Optional so adding it stays a non-breaking, additive change for any code
+   * that constructs a `BudgetAdvisory` literal; `advisory()` always sets it.
    */
-  expectedCost: number;
+  expectedCost?: number;
   /**
    * How many more calls the remaining budget buys at expectedCost:
    * floor(remainingUsd / expectedCost). null when expectedCost is 0 (no call
-   * recorded yet) — unknown, not zero.
+   * recorded yet) — unknown, not zero. Optional for the same additive reason as
+   * expectedCost; `advisory()` always sets it.
    */
-  estCallsRemaining: number | null;
+  estCallsRemaining?: number | null;
 }
 
 export class BudgetGuard {

js/test/advisory.test.ts

@@ -66,6 +66,18 @@ describe("BudgetGuard.advisory", () => {
     expect(a.estCallsRemaining).toBe(9); // floor(0.90 / 0.10)
   });
 
+  it("expectedCost is the costlier of the last LLM and tool call", () => {
+    // Parity with the Python suite: a cheap tool after an expensive LLM call
+    // must not shrink the estimate — the max wins (conservative).
+    const g = new BudgetGuard(1.0);
+    g.record("gpt-4o", 1_000, 1_000); // $0.0125 LLM
+    g.recordTool("exa.search", 0.001); // cheaper tool, spent = $0.0135
+    const a = g.advisory();
+    expect(a.expectedCost).toBeCloseTo(0.0125, 9); // LLM side, not the cheaper tool
+    // floor((1.0 - 0.0135) / 0.0125) = floor(78.92) = 78
+    expect(a.estCallsRemaining).toBe(78);
+  });
+
   it("rejects an out-of-range or non-integer nearLimitBps", () => {
     expect(() => new BudgetGuard(1.0, { nearLimitBps: -1 })).toThrow(RangeError);
     expect(() => new BudgetGuard(1.0, { nearLimitBps: 10001 })).toThrow(RangeError);