@indigoai-us/cq 0.0.1

package/dist/budget/__tests__/token-tracker.test.js

@@ -0,0 +1,292 @@
+import { describe, it, expect } from "vitest";
+import { TokenTracker, estimateTokens } from "../token-tracker.js";
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function makeEntry(overrides) {
+    return {
+        category: "test",
+        slug: "test-entry",
+        title: "Test Entry",
+        tags: [],
+        created: "2026-01-01T00:00:00Z",
+        updated: "2026-01-01T00:00:00Z",
+        ...overrides,
+    };
+}
+/** Create content of a specific token size (approx). */
+function contentOfTokens(tokens) {
+    return "x".repeat(tokens * 4);
+}
+// ---------------------------------------------------------------------------
+// estimateTokens
+// ---------------------------------------------------------------------------
+describe("estimateTokens", () => {
+    it("estimates ~4 chars per token", () => {
+        expect(estimateTokens("")).toBe(0);
+        expect(estimateTokens("abcd")).toBe(1);
+        expect(estimateTokens("abcde")).toBe(2); // ceil(5/4) = 2
+        expect(estimateTokens("a".repeat(100))).toBe(25);
+    });
+});
+// ---------------------------------------------------------------------------
+// Constructor
+// ---------------------------------------------------------------------------
+describe("TokenTracker constructor", () => {
+    it("accepts a positive maxTokens value", () => {
+        const tracker = new TokenTracker(1000);
+        expect(tracker.remaining).toBe(1000);
+    });
+    it("throws for zero maxTokens", () => {
+        expect(() => new TokenTracker(0)).toThrow("maxTokens must be a positive number");
+    });
+    it("throws for negative maxTokens", () => {
+        expect(() => new TokenTracker(-1)).toThrow("maxTokens must be a positive number");
+    });
+});
+// ---------------------------------------------------------------------------
+// remaining
+// ---------------------------------------------------------------------------
+describe("remaining", () => {
+    it("starts at maxTokens", () => {
+        const tracker = new TokenTracker(500);
+        expect(tracker.remaining).toBe(500);
+    });
+    it("decreases after reserve", () => {
+        const tracker = new TokenTracker(500);
+        const entry = makeEntry({ content: contentOfTokens(100) });
+        tracker.reserve(entry);
+        expect(tracker.remaining).toBe(400);
+    });
+});
+// ---------------------------------------------------------------------------
+// wouldFit
+// ---------------------------------------------------------------------------
+describe("wouldFit", () => {
+    it("returns true when entry fits", () => {
+        const tracker = new TokenTracker(200);
+        const entry = makeEntry({ content: contentOfTokens(100) });
+        expect(tracker.wouldFit(entry)).toBe(true);
+    });
+    it("returns true when entry exactly fills remaining budget", () => {
+        const tracker = new TokenTracker(100);
+        const entry = makeEntry({ content: contentOfTokens(100) });
+        expect(tracker.wouldFit(entry)).toBe(true);
+    });
+    it("returns false when entry exceeds remaining budget", () => {
+        const tracker = new TokenTracker(50);
+        const entry = makeEntry({ content: contentOfTokens(100) });
+        expect(tracker.wouldFit(entry)).toBe(false);
+    });
+    it("accounts for already-reserved tokens", () => {
+        const tracker = new TokenTracker(200);
+        const first = makeEntry({ slug: "first", content: contentOfTokens(150) });
+        tracker.reserve(first);
+        const second = makeEntry({ slug: "second", content: contentOfTokens(100) });
+        expect(tracker.wouldFit(second)).toBe(false);
+    });
+});
+// ---------------------------------------------------------------------------
+// reserve / release
+// ---------------------------------------------------------------------------
+describe("reserve", () => {
+    it("deducts token count from remaining", () => {
+        const tracker = new TokenTracker(1000);
+        const entry = makeEntry({ content: contentOfTokens(250) });
+        tracker.reserve(entry);
+        expect(tracker.remaining).toBe(750);
+    });
+    it("is idempotent for the same entry", () => {
+        const tracker = new TokenTracker(1000);
+        const entry = makeEntry({ content: contentOfTokens(100) });
+        tracker.reserve(entry);
+        tracker.reserve(entry); // no-op
+        expect(tracker.remaining).toBe(900);
+    });
+    it("throws when entry exceeds remaining budget", () => {
+        const tracker = new TokenTracker(50);
+        const entry = makeEntry({ content: contentOfTokens(100) });
+        expect(() => tracker.reserve(entry)).toThrow("Cannot reserve 100 tokens");
+    });
+    it("tracks entries by category/slug", () => {
+        const tracker = new TokenTracker(1000);
+        const a = makeEntry({ category: "cat-a", slug: "one", content: contentOfTokens(100) });
+        const b = makeEntry({ category: "cat-b", slug: "one", content: contentOfTokens(100) });
+        tracker.reserve(a);
+        tracker.reserve(b);
+        expect(tracker.remaining).toBe(800);
+    });
+});
+describe("release", () => {
+    it("returns tokens to the budget", () => {
+        const tracker = new TokenTracker(1000);
+        const entry = makeEntry({ content: contentOfTokens(300) });
+        tracker.reserve(entry);
+        expect(tracker.remaining).toBe(700);
+        tracker.release(entry);
+        expect(tracker.remaining).toBe(1000);
+    });
+    it("is a no-op for entries not reserved", () => {
+        const tracker = new TokenTracker(1000);
+        const entry = makeEntry({ content: contentOfTokens(100) });
+        tracker.release(entry); // should not throw
+        expect(tracker.remaining).toBe(1000);
+    });
+    it("allows re-reserving after release", () => {
+        const tracker = new TokenTracker(1000);
+        const entry = makeEntry({ content: contentOfTokens(200) });
+        tracker.reserve(entry);
+        tracker.release(entry);
+        tracker.reserve(entry);
+        expect(tracker.remaining).toBe(800);
+    });
+});
+// ---------------------------------------------------------------------------
+// selectEntries — highest_confidence
+// ---------------------------------------------------------------------------
+describe("selectEntries — highest_confidence", () => {
+    it("selects entries in descending confidence order", () => {
+        const tracker = new TokenTracker(1000);
+        const entries = [
+            { entry: makeEntry({ slug: "low", content: contentOfTokens(100) }), confidence: 0.3 },
+            { entry: makeEntry({ slug: "high", content: contentOfTokens(100) }), confidence: 0.9 },
+            { entry: makeEntry({ slug: "mid", content: contentOfTokens(100) }), confidence: 0.6 },
+        ];
+        const selected = tracker.selectEntries(entries, "highest_confidence");
+        expect(selected.map((e) => e.slug)).toEqual(["high", "mid", "low"]);
+    });
+    it("skips entries that do not fit", () => {
+        const tracker = new TokenTracker(250);
+        const entries = [
+            { entry: makeEntry({ slug: "a", content: contentOfTokens(100) }), confidence: 0.9 },
+            { entry: makeEntry({ slug: "b", content: contentOfTokens(200) }), confidence: 0.8 },
+            { entry: makeEntry({ slug: "c", content: contentOfTokens(100) }), confidence: 0.7 },
+        ];
+        const selected = tracker.selectEntries(entries, "highest_confidence");
+        // a (100) fits, b (200) doesn't (only 150 left), c (100) fits
+        expect(selected.map((e) => e.slug)).toEqual(["a", "c"]);
+    });
+    it("treats missing confidence as 0", () => {
+        const tracker = new TokenTracker(1000);
+        const entries = [
+            { entry: makeEntry({ slug: "no-score", content: contentOfTokens(50) }) },
+            { entry: makeEntry({ slug: "scored", content: contentOfTokens(50) }), confidence: 0.5 },
+        ];
+        const selected = tracker.selectEntries(entries, "highest_confidence");
+        expect(selected[0].slug).toBe("scored");
+    });
+});
+// ---------------------------------------------------------------------------
+// selectEntries — most_relevant
+// ---------------------------------------------------------------------------
+describe("selectEntries — most_relevant", () => {
+    it("selects entries in descending relevance order", () => {
+        const tracker = new TokenTracker(1000);
+        const entries = [
+            { entry: makeEntry({ slug: "low", content: contentOfTokens(50) }), relevance: 0.2 },
+            { entry: makeEntry({ slug: "high", content: contentOfTokens(50) }), relevance: 0.95 },
+            { entry: makeEntry({ slug: "mid", content: contentOfTokens(50) }), relevance: 0.5 },
+        ];
+        const selected = tracker.selectEntries(entries, "most_relevant");
+        expect(selected.map((e) => e.slug)).toEqual(["high", "mid", "low"]);
+    });
+    it("falls back to array order when no relevance scores provided", () => {
+        const tracker = new TokenTracker(1000);
+        const entries = [
+            { entry: makeEntry({ slug: "first", content: contentOfTokens(50) }) },
+            { entry: makeEntry({ slug: "second", content: contentOfTokens(50) }) },
+        ];
+        const selected = tracker.selectEntries(entries, "most_relevant");
+        // Both have relevance 0, so sort is stable
+        expect(selected).toHaveLength(2);
+    });
+});
+// ---------------------------------------------------------------------------
+// selectEntries — balanced
+// ---------------------------------------------------------------------------
+describe("selectEntries — balanced", () => {
+    it("interleaves entries from different categories", () => {
+        const tracker = new TokenTracker(1000);
+        const entries = [
+            { entry: makeEntry({ category: "science", slug: "s1", content: contentOfTokens(50) }), confidence: 0.9 },
+            { entry: makeEntry({ category: "science", slug: "s2", content: contentOfTokens(50) }), confidence: 0.8 },
+            { entry: makeEntry({ category: "history", slug: "h1", content: contentOfTokens(50) }), confidence: 0.85 },
+            { entry: makeEntry({ category: "history", slug: "h2", content: contentOfTokens(50) }), confidence: 0.7 },
+        ];
+        const selected = tracker.selectEntries(entries, "balanced");
+        // Should interleave: science first (higher top score), then history, then science, then history
+        expect(selected).toHaveLength(4);
+        // Check categories alternate
+        const categories = selected.map((e) => e.category);
+        expect(categories[0]).toBe("science");
+        expect(categories[1]).toBe("history");
+        expect(categories[2]).toBe("science");
+        expect(categories[3]).toBe("history");
+    });
+    it("respects budget when interleaving", () => {
+        const tracker = new TokenTracker(150);
+        const entries = [
+            { entry: makeEntry({ category: "a", slug: "a1", content: contentOfTokens(100) }), confidence: 0.9 },
+            { entry: makeEntry({ category: "b", slug: "b1", content: contentOfTokens(100) }), confidence: 0.8 },
+        ];
+        const selected = tracker.selectEntries(entries, "balanced");
+        // Only one fits
+        expect(selected).toHaveLength(1);
+        expect(selected[0].slug).toBe("a1");
+    });
+    it("uses combined confidence and relevance score", () => {
+        const tracker = new TokenTracker(1000);
+        const entries = [
+            {
+                entry: makeEntry({ category: "x", slug: "low-both", content: contentOfTokens(50) }),
+                confidence: 0.2,
+                relevance: 0.2,
+            },
+            {
+                entry: makeEntry({ category: "x", slug: "high-both", content: contentOfTokens(50) }),
+                confidence: 0.9,
+                relevance: 0.9,
+            },
+        ];
+        const selected = tracker.selectEntries(entries, "balanced");
+        expect(selected[0].slug).toBe("high-both");
+    });
+});
+// ---------------------------------------------------------------------------
+// selectEntries — budget overflow prevention
+// ---------------------------------------------------------------------------
+describe("selectEntries — budget overflow prevention", () => {
+    it("never exceeds remaining budget", () => {
+        const tracker = new TokenTracker(100);
+        // Pre-reserve some tokens
+        const reserved = makeEntry({ slug: "reserved", content: contentOfTokens(60) });
+        tracker.reserve(reserved);
+        expect(tracker.remaining).toBe(40);
+        const entries = [
+            { entry: makeEntry({ slug: "big", content: contentOfTokens(50) }), confidence: 0.9 },
+            { entry: makeEntry({ slug: "small", content: contentOfTokens(30) }), confidence: 0.5 },
+        ];
+        const selected = tracker.selectEntries(entries, "highest_confidence");
+        // big (50) doesn't fit (only 40 left), small (30) fits
+        expect(selected).toHaveLength(1);
+        expect(selected[0].slug).toBe("small");
+    });
+    it("returns empty array when no entries fit", () => {
+        const tracker = new TokenTracker(10);
+        const entries = [
+            { entry: makeEntry({ slug: "a", content: contentOfTokens(50) }), confidence: 0.9 },
+        ];
+        const selected = tracker.selectEntries(entries, "highest_confidence");
+        expect(selected).toEqual([]);
+    });
+    it("does not mutate the tracker's remaining budget", () => {
+        const tracker = new TokenTracker(500);
+        const entries = [
+            { entry: makeEntry({ slug: "a", content: contentOfTokens(100) }), confidence: 0.9 },
+        ];
+        tracker.selectEntries(entries, "highest_confidence");
+        // selectEntries is read-only — does not actually reserve
+        expect(tracker.remaining).toBe(500);
+    });
+});
+//# sourceMappingURL=token-tracker.test.js.map

package/dist/budget/__tests__/token-tracker.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-tracker.test.js","sourceRoot":"","sources":["../../../src/budget/__tests__/token-tracker.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAInE,8EAA8E;AAC9E,UAAU;AACV,8EAA8E;AAE9E,SAAS,SAAS,CAAC,SAAwD;IACzE,OAAO;QACL,QAAQ,EAAE,MAAM;QAChB,IAAI,EAAE,YAAY;QAClB,KAAK,EAAE,YAAY;QACnB,IAAI,EAAE,EAAE;QACR,OAAO,EAAE,sBAAsB;QAC/B,OAAO,EAAE,sBAAsB;QAC/B,GAAG,SAAS;KACb,CAAC;AACJ,CAAC;AAED,wDAAwD;AACxD,SAAS,eAAe,CAAC,MAAc;IACrC,OAAO,GAAG,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AAChC,CAAC;AAED,8EAA8E;AAC9E,iBAAiB;AACjB,8EAA8E;AAE9E,QAAQ,CAAC,gBAAgB,EAAE,GAAG,EAAE;IAC9B,EAAE,CAAC,8BAA8B,EAAE,GAAG,EAAE;QACtC,MAAM,CAAC,cAAc,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACnC,MAAM,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACvC,MAAM,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,gBAAgB;QACzD,MAAM,CAAC,cAAc,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACnD,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,8EAA8E;AAC9E,cAAc;AACd,8EAA8E;AAE9E,QAAQ,CAAC,0BAA0B,EAAE,GAAG,EAAE;IACxC,EAAE,CAAC,oCAAoC,EAAE,GAAG,EAAE;QAC5C,MAAM,OAAO,GAAG,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC;QACvC,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACvC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,2BAA2B,EAAE,GAAG,EAAE;QACnC,MAAM,CAAC,GAAG,EAAE,CAAC,IAAI,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,qCAAqC,CAAC,CAAC;IACnF,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,+BAA+B,EAAE,GAAG,EAAE;QACvC,MAAM,CAAC,GAAG,EAAE,CAAC,IAAI,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,qCAAqC,CAAC,CAAC;IACpF,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,8EAA8E;AAC9E,YAAY;AACZ,8EAA8E;AAE9E,QAAQ,CAAC,WAAW,EAAE,GAAG,EAAE;IACzB,EAAE,CAAC,qBAAqB,EAAE,GAAG,EAAE;QAC7B,MAAM,OAAO,GAAG,IAAI,YAAY,CAAC,GAAG,CAAC,CAAC;QACtC,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACtC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,yBAAyB,EAAE,GAAG,EAAE;QACjC,MAAM,OAAO,GAAG,IAAI,YAAY,CAAC,GAAG,CAAC,CAAC;QACtC,MAAM,KAAK,GAAG,SAAS,CAAC,EAAE,OAAO,EAAE,eAAe,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC3D,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QACvB,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACtC,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,8EAA8E;AAC9E,WAAW;AACX,8EAA8E;AAE9E,QAAQ,CAAC,UAAU,EAAE,GAAG,EAAE;IACxB,EAAE,CAAC,8BAA8B,EAAE,GAAG,EAAE;QACtC,MAAM,OAAO,GAAG,IAAI,YAAY,CAAC,GAAG,CAAC,CAAC;QACtC,MAAM,KAAK,GAAG,SAAS,CAAC,EAAE,OAAO,EAAE,eAAe,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC3D,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC7C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,wDAAwD,EAAE,GAAG,EAAE;QAChE,MAAM,OAAO,GAAG,IAAI,YAAY,CAAC,GAAG,CAAC,CAAC;QACtC,MAAM,KAAK,GAAG,SAAS,CAAC,EAAE,OAAO,EAAE,eAAe,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC3D,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC7C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,mDAAmD,EAAE,GAAG,EAAE;QAC3D,MAAM,OAAO,GAAG,IAAI,YAAY,CAAC,EAAE,CAAC,CAAC;QACrC,MAAM,KAAK,GAAG,SAAS,CAAC,EAAE,OAAO,EAAE,eAAe,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC3D,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC9C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,sCAAsC,EAAE,GAAG,EAAE;QAC9C,MAAM,OAAO,GAAG,IAAI,YAAY,CAAC,GAAG,CAAC,CAAC;QACtC,MAAM,KAAK,GAAG,SAAS,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,eAAe,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC1E,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QACvB,MAAM,MAAM,GAAG,SAAS,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,eAAe,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC5E,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC/C,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,8EAA8E;AAC9E,oBAAoB;AACpB,8EAA8E;AAE9E,QAAQ,CAAC,SAAS,EAAE,GAAG,EAAE;IACvB,EAAE,CAAC,oCAAoC,EAAE,GAAG,EAAE;QAC5C,MAAM,OAAO,GAAG,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC;QACvC,MAAM,KAAK,GAAG,SAAS,CAAC,EAAE,OAAO,EAAE,eAAe,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC3D,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QACvB,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACtC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,kCAAkC,EAAE,GAAG,EAAE;QAC1C,MAAM,OAAO,GAAG,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC;QACvC,MAAM,KAAK,GAAG,SAAS,CAAC,EAAE,OAAO,EAAE,eAAe,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC3D,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QACvB,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,QAAQ;QAChC,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACtC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,4CAA4C,EAAE,GAAG,EAAE;QACpD,MAAM,OAAO,GAAG,IAAI,YAAY,CAAC,EAAE,CAAC,CAAC;QACrC,MAAM,KAAK,GAAG,SAAS,CAAC,EAAE,OAAO,EAAE,eAAe,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC3D,MAAM,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,2BAA2B,CAAC,CAAC;IAC5E,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,iCAAiC,EAAE,GAAG,EAAE;QACzC,MAAM,OAAO,GAAG,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC;QACvC,MAAM,CAAC,GAAG,SAAS,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,eAAe,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACvF,MAAM,CAAC,GAAG,SAAS,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,eAAe,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACvF,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;QACnB,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;QACnB,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACtC,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,QAAQ,CAAC,SAAS,EAAE,GAAG,EAAE;IACvB,EAAE,CAAC,8BAA8B,EAAE,GAAG,EAAE;QACtC,MAAM,OAAO,GAAG,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC;QACvC,MAAM,KAAK,GAAG,SAAS,CAAC,EAAE,OAAO,EAAE,eAAe,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC3D,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QACvB,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACpC,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QACvB,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACvC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,qCAAqC,EAAE,GAAG,EAAE;QAC7C,MAAM,OAAO,GAAG,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC;QACvC,MAAM,KAAK,GAAG,SAAS,CAAC,EAAE,OAAO,EAAE,eAAe,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC3D,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,mBAAmB;QAC3C,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACvC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,mCAAmC,EAAE,GAAG,EAAE;QAC3C,MAAM,OAAO,GAAG,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC;QACvC,MAAM,KAAK,GAAG,SAAS,CAAC,EAAE,OAAO,EAAE,eAAe,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC3D,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QACvB,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QACvB,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QACvB,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACtC,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,8EAA8E;AAC9E,qCAAqC;AACrC,8EAA8E;AAE9E,QAAQ,CAAC,oCAAoC,EAAE,GAAG,EAAE;IAClD,EAAE,CAAC,gDAAgD,EAAE,GAAG,EAAE;QACxD,MAAM,OAAO,GAAG,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC;QACvC,MAAM,OAAO,GAAkB;YAC7B,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,eAAe,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,UAAU,EAAE,GAAG,EAAE;YACrF,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,UAAU,EAAE,GAAG,EAAE;YACtF,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,eAAe,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,UAAU,EAAE,GAAG,EAAE;SACtF,CAAC;QACF,MAAM,QAAQ,GAAG,OAAO,CAAC,aAAa,CAAC,OAAO,EAAE,oBAAoB,CAAC,CAAC;QACtE,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,MAAM,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC;IACtE,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,+BAA+B,EAAE,GAAG,EAAE;QACvC,MAAM,OAAO,GAAG,IAAI,YAAY,CAAC,GAAG,CAAC,CAAC;QACtC,MAAM,OAAO,GAAkB;YAC7B,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,eAAe,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,UAAU,EAAE,GAAG,EAAE;YACnF,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,eAAe,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,UAAU,EAAE,GAAG,EAAE;YACnF,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,eAAe,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,UAAU,EAAE,GAAG,EAAE;SACpF,CAAC;QACF,MAAM,QAAQ,GAAG,OAAO,CAAC,aAAa,CAAC,OAAO,EAAE,oBAAoB,CAAC,CAAC;QACtE,8DAA8D;QAC9D,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC;IAC1D,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,gCAAgC,EAAE,GAAG,EAAE;QACxC,MAAM,OAAO,GAAG,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC;QACvC,MAAM,OAAO,GAAkB;YAC7B,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,eAAe,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE;YACxE,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,eAAe,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,UAAU,EAAE,GAAG,EAAE;SACxF,CAAC;QACF,MAAM,QAAQ,GAAG,OAAO,CAAC,aAAa,CAAC,OAAO,EAAE,oBAAoB,CAAC,CAAC;QACtE,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC1C,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,8EAA8E;AAC9E,gCAAgC;AAChC,8EAA8E;AAE9E,QAAQ,CAAC,+BAA+B,EAAE,GAAG,EAAE;IAC7C,EAAE,CAAC,+CAA+C,EAAE,GAAG,EAAE;QACvD,MAAM,OAAO,GAAG,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC;QACvC,MAAM,OAAO,GAAkB;YAC7B,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,eAAe,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,SAAS,EAAE,GAAG,EAAE;YACnF,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE;YACrF,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,eAAe,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,SAAS,EAAE,GAAG,EAAE;SACpF,CAAC;QACF,MAAM,QAAQ,GAAG,OAAO,CAAC,aAAa,CAAC,OAAO,EAAE,eAAe,CAAC,CAAC;QACjE,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,MAAM,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC;IACtE,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,6DAA6D,EAAE,GAAG,EAAE;QACrE,MAAM,OAAO,GAAG,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC;QACvC,MAAM,OAAO,GAAkB;YAC7B,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,eAAe,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE;YACrE,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,eAAe,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE;SACvE,CAAC;QACF,MAAM,QAAQ,GAAG,OAAO,CAAC,aAAa,CAAC,OAAO,EAAE,eAAe,CAAC,CAAC;QACjE,2CAA2C;QAC3C,MAAM,CAAC,QAAQ,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;IACnC,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,8EAA8E;AAC9E,2BAA2B;AAC3B,8EAA8E;AAE9E,QAAQ,CAAC,0BAA0B,EAAE,GAAG,EAAE;IACxC,EAAE,CAAC,+CAA+C,EAAE,GAAG,EAAE;QACvD,MAAM,OAAO,GAAG,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC;QACvC,MAAM,OAAO,GAAkB;YAC7B,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,QAAQ,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,eAAe,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,UAAU,EAAE,GAAG,EAAE;YACxG,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,QAAQ,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,eAAe,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,UAAU,EAAE,GAAG,EAAE;YACxG,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,QAAQ,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,eAAe,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,UAAU,EAAE,IAAI,EAAE;YACzG,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,QAAQ,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,eAAe,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,UAAU,EAAE,GAAG,EAAE;SACzG,CAAC;QACF,MAAM,QAAQ,GAAG,OAAO,CAAC,aAAa,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;QAC5D,gGAAgG;QAChG,MAAM,CAAC,QAAQ,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;QACjC,6BAA6B;QAC7B,MAAM,UAAU,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;QACnD,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACtC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACtC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACtC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IACxC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,mCAAmC,EAAE,GAAG,EAAE;QAC3C,MAAM,OAAO,GAAG,IAAI,YAAY,CAAC,GAAG,CAAC,CAAC;QACtC,MAAM,OAAO,GAAkB;YAC7B,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,QAAQ,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,eAAe,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,UAAU,EAAE,GAAG,EAAE;YACnG,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,QAAQ,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,eAAe,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,UAAU,EAAE,GAAG,EAAE;SACpG,CAAC;QACF,MAAM,QAAQ,GAAG,OAAO,CAAC,aAAa,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;QAC5D,gBAAgB;QAChB,MAAM,CAAC,QAAQ,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;QACjC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACtC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,8CAA8C,EAAE,GAAG,EAAE;QACtD,MAAM,OAAO,GAAG,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC;QACvC,MAAM,OAAO,GAAkB;YAC7B;gBACE,KAAK,EAAE,SAAS,CAAC,EAAE,QAAQ,EAAE,GAAG,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,eAAe,CAAC,EAAE,CAAC,EAAE,CAAC;gBACnF,UAAU,EAAE,GAAG;gBACf,SAAS,EAAE,GAAG;aACf;YACD;gBACE,KAAK,EAAE,SAAS,CAAC,EAAE,QAAQ,EAAE,GAAG,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,eAAe,CAAC,EAAE,CAAC,EAAE,CAAC;gBACpF,UAAU,EAAE,GAAG;gBACf,SAAS,EAAE,GAAG;aACf;SACF,CAAC;QACF,MAAM,QAAQ,GAAG,OAAO,CAAC,aAAa,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;QAC5D,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IAC7C,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,8EAA8E;AAC9E,6CAA6C;AAC7C,8EAA8E;AAE9E,QAAQ,CAAC,4CAA4C,EAAE,GAAG,EAAE;IAC1D,EAAE,CAAC,gCAAgC,EAAE,GAAG,EAAE;QACxC,MAAM,OAAO,GAAG,IAAI,YAAY,CAAC,GAAG,CAAC,CAAC;QACtC,0BAA0B;QAC1B,MAAM,QAAQ,GAAG,SAAS,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,eAAe,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;QAC/E,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QAC1B,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAEnC,MAAM,OAAO,GAAkB;YAC7B,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,eAAe,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,UAAU,EAAE,GAAG,EAAE;YACpF,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,eAAe,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,UAAU,EAAE,GAAG,EAAE;SACvF,CAAC;QACF,MAAM,QAAQ,GAAG,OAAO,CAAC,aAAa,CAAC,OAAO,EAAE,oBAAoB,CAAC,CAAC;QACtE,uDAAuD;QACvD,MAAM,CAAC,QAAQ,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;QACjC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACzC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,yCAAyC,EAAE,GAAG,EAAE;QACjD,MAAM,OAAO,GAAG,IAAI,YAAY,CAAC,EAAE,CAAC,CAAC;QACrC,MAAM,OAAO,GAAkB;YAC7B,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,eAAe,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,UAAU,EAAE,GAAG,EAAE;SACnF,CAAC;QACF,MAAM,QAAQ,GAAG,OAAO,CAAC,aAAa,CAAC,OAAO,EAAE,oBAAoB,CAAC,CAAC;QACtE,MAAM,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IAC/B,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,gDAAgD,EAAE,GAAG,EAAE;QACxD,MAAM,OAAO,GAAG,IAAI,YAAY,CAAC,GAAG,CAAC,CAAC;QACtC,MAAM,OAAO,GAAkB;YAC7B,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,eAAe,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,UAAU,EAAE,GAAG,EAAE;SACpF,CAAC;QACF,OAAO,CAAC,aAAa,CAAC,OAAO,EAAE,oBAAoB,CAAC,CAAC;QACrD,yDAAyD;QACzD,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACtC,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/budget/index.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Budget Tracker — configurable spend limits with daily reset (UTC).
+ *
+ * Uses the shared cq_settings table for config storage and a dedicated
+ * research_budget table for charge records.
+ */
+import type { BudgetConfig, BudgetCheckResult, BudgetStatus, ChargeType } from "./types.js";
+export type { BudgetConfig, BudgetCheckResult, BudgetStatus, ChargeType } from "./types.js";
+export { TokenTracker, estimateTokens } from "./token-tracker.js";
+export type { SelectionStrategy, ScoredEntry } from "./token-tracker.js";
+/** Ensure budget tables exist. Called lazily on first use. */
+export declare function initBudgetTables(): void;
+/**
+ * Store a BudgetConfig in the settings table.
+ * Merges with defaults so callers can provide partial overrides.
+ */
+export declare function setBudgetConfig(config: Partial<BudgetConfig>): void;
+/**
+ * Retrieve the stored BudgetConfig, falling back to defaults.
+ */
+export declare function getBudgetConfig(): BudgetConfig;
+/**
+ * Record a charge against the budget.
+ */
+export declare function charge(type: ChargeType, costUsd: number, description?: string, now?: string): void;
+/**
+ * Check whether an estimated charge fits within budget limits.
+ */
+export declare function checkBudget(estimatedCost?: number, now?: string): BudgetCheckResult;
+/**
+ * Return usage vs daily limit for a given date (defaults to today UTC).
+ */
+export declare function getDailyBudgetStatus(now?: string): BudgetStatus;
+/**
+ * Return lifetime usage vs total limit (if configured).
+ */
+export declare function getTotalBudgetStatus(): BudgetStatus;
+//# sourceMappingURL=index.d.ts.map

package/dist/budget/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/budget/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,iBAAiB,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE5F,YAAY,EAAE,YAAY,EAAE,iBAAiB,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC5F,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAClE,YAAY,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAyCzE,8DAA8D;AAC9D,wBAAgB,gBAAgB,IAAI,IAAI,CAKvC;AAsBD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG,IAAI,CAOnE;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI,YAAY,CAQ9C;AAMD;;GAEG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAQlG;AAMD;;GAEG;AACH,wBAAgB,WAAW,CAAC,aAAa,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,iBAAiB,CAmDnF;AAMD;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,YAAY,CAgB/D;AAED;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,YAAY,CAiBnD"}

package/dist/budget/index.js

@@ -0,0 +1,192 @@
+/**
+ * Budget Tracker — configurable spend limits with daily reset (UTC).
+ *
+ * Uses the shared cq_settings table for config storage and a dedicated
+ * research_budget table for charge records.
+ */
+import { getDb } from "../metadata/index.js";
+export { TokenTracker, estimateTokens } from "./token-tracker.js";
+// ---------------------------------------------------------------------------
+// Table DDL
+// ---------------------------------------------------------------------------
+const SETTINGS_TABLE_SQL = `
+CREATE TABLE IF NOT EXISTS cq_settings (
+  key   TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+);
+`;
+const BUDGET_TABLE_SQL = `
+CREATE TABLE IF NOT EXISTS research_budget (
+  id          INTEGER PRIMARY KEY AUTOINCREMENT,
+  date        TEXT    NOT NULL,
+  type        TEXT    NOT NULL,
+  cost_usd    REAL    NOT NULL,
+  description TEXT,
+  created_at  TEXT    NOT NULL
+);
+`;
+const CONFIG_KEY = "budget_config";
+// ---------------------------------------------------------------------------
+// Default config
+// ---------------------------------------------------------------------------
+const DEFAULT_CONFIG = {
+    dailyLimitUsd: 1.0,
+    searchCostUsd: 0.03,
+    synthesisCostUsd: 0.01,
+    vetCostUsd: 0.005,
+};
+// ---------------------------------------------------------------------------
+// Initialisation
+// ---------------------------------------------------------------------------
+/** Ensure budget tables exist. Called lazily on first use. */
+export function initBudgetTables() {
+    const db = getDb();
+    if (!db)
+        throw new Error("Metadata DB not initialised — call initMetadataDb first");
+    db.exec(SETTINGS_TABLE_SQL);
+    db.exec(BUDGET_TABLE_SQL);
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/** Return today's date as YYYY-MM-DD in UTC. */
+function utcToday(now) {
+    const d = now ? new Date(now) : new Date();
+    return d.toISOString().slice(0, 10);
+}
+function requireDb() {
+    const db = getDb();
+    if (!db)
+        throw new Error("Metadata DB not initialised — call initMetadataDb first");
+    return db;
+}
+// ---------------------------------------------------------------------------
+// Config storage
+// ---------------------------------------------------------------------------
+/**
+ * Store a BudgetConfig in the settings table.
+ * Merges with defaults so callers can provide partial overrides.
+ */
+export function setBudgetConfig(config) {
+    initBudgetTables();
+    const db = requireDb();
+    const merged = { ...DEFAULT_CONFIG, ...config };
+    db.prepare("INSERT INTO cq_settings (key, value) VALUES (?, ?) ON CONFLICT (key) DO UPDATE SET value = ?").run(CONFIG_KEY, JSON.stringify(merged), JSON.stringify(merged));
+}
+/**
+ * Retrieve the stored BudgetConfig, falling back to defaults.
+ */
+export function getBudgetConfig() {
+    initBudgetTables();
+    const db = requireDb();
+    const row = db.prepare("SELECT value FROM cq_settings WHERE key = ?").get(CONFIG_KEY);
+    if (!row)
+        return { ...DEFAULT_CONFIG };
+    return JSON.parse(row.value);
+}
+// ---------------------------------------------------------------------------
+// Charging
+// ---------------------------------------------------------------------------
+/**
+ * Record a charge against the budget.
+ */
+export function charge(type, costUsd, description, now) {
+    initBudgetTables();
+    const db = requireDb();
+    const date = utcToday(now);
+    const createdAt = now ?? new Date().toISOString();
+    db.prepare("INSERT INTO research_budget (date, type, cost_usd, description, created_at) VALUES (?, ?, ?, ?, ?)").run(date, type, costUsd, description ?? null, createdAt);
+}
+// ---------------------------------------------------------------------------
+// Budget checks
+// ---------------------------------------------------------------------------
+/**
+ * Check whether an estimated charge fits within budget limits.
+ */
+export function checkBudget(estimatedCost, now) {
+    initBudgetTables();
+    const db = requireDb();
+    const config = getBudgetConfig();
+    const date = utcToday(now);
+    const cost = estimatedCost ?? 0;
+    const dailyRow = db
+        .prepare("SELECT COALESCE(SUM(cost_usd), 0) AS total FROM research_budget WHERE date = ?")
+        .get(date);
+    const dailyUsedUsd = dailyRow.total;
+    const totalRow = db
+        .prepare("SELECT COALESCE(SUM(cost_usd), 0) AS total FROM research_budget")
+        .get();
+    const totalUsedUsd = totalRow.total;
+    const dailyRemaining = config.dailyLimitUsd - dailyUsedUsd;
+    const totalRemaining = config.totalLimitUsd !== undefined
+        ? config.totalLimitUsd - totalUsedUsd
+        : Infinity;
+    const remainingUsd = Math.min(dailyRemaining, totalRemaining);
+    // Check daily limit
+    if (dailyUsedUsd + cost > config.dailyLimitUsd) {
+        return {
+            allowed: false,
+            remainingUsd: Math.max(0, dailyRemaining),
+            dailyUsedUsd,
+            totalUsedUsd,
+            reason: `Daily limit of $${config.dailyLimitUsd.toFixed(2)} would be exceeded (used: $${dailyUsedUsd.toFixed(2)}, requested: $${cost.toFixed(2)})`,
+        };
+    }
+    // Check total limit
+    if (config.totalLimitUsd !== undefined && totalUsedUsd + cost > config.totalLimitUsd) {
+        return {
+            allowed: false,
+            remainingUsd: Math.max(0, totalRemaining),
+            dailyUsedUsd,
+            totalUsedUsd,
+            reason: `Total limit of $${config.totalLimitUsd.toFixed(2)} would be exceeded (used: $${totalUsedUsd.toFixed(2)}, requested: $${cost.toFixed(2)})`,
+        };
+    }
+    return {
+        allowed: true,
+        remainingUsd: Math.max(0, remainingUsd),
+        dailyUsedUsd,
+        totalUsedUsd,
+    };
+}
+// ---------------------------------------------------------------------------
+// Status queries
+// ---------------------------------------------------------------------------
+/**
+ * Return usage vs daily limit for a given date (defaults to today UTC).
+ */
+export function getDailyBudgetStatus(now) {
+    initBudgetTables();
+    const db = requireDb();
+    const config = getBudgetConfig();
+    const date = utcToday(now);
+    const row = db
+        .prepare("SELECT COALESCE(SUM(cost_usd), 0) AS total FROM research_budget WHERE date = ?")
+        .get(date);
+    const usedUsd = row.total;
+    return {
+        usedUsd,
+        limitUsd: config.dailyLimitUsd,
+        remainingUsd: Math.max(0, config.dailyLimitUsd - usedUsd),
+    };
+}
+/**
+ * Return lifetime usage vs total limit (if configured).
+ */
+export function getTotalBudgetStatus() {
+    initBudgetTables();
+    const db = requireDb();
+    const config = getBudgetConfig();
+    const row = db
+        .prepare("SELECT COALESCE(SUM(cost_usd), 0) AS total FROM research_budget")
+        .get();
+    const usedUsd = row.total;
+    return {
+        usedUsd,
+        limitUsd: config.totalLimitUsd,
+        remainingUsd: config.totalLimitUsd !== undefined
+            ? Math.max(0, config.totalLimitUsd - usedUsd)
+            : undefined,
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/budget/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/budget/index.ts"],"names":[],"mappings":"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"}

package/dist/budget/token-tracker.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Token Tracker — runtime context window budget management.
+ *
+ * Tracks token usage for knowledge entries loaded into an LLM context window.
+ * Supports multiple selection strategies for fitting entries within a budget.
+ */
+import type { KnowledgeEntry } from "../knowledge-tree/types.js";
+/** Strategy for selecting entries that fit within the token budget. */
+export type SelectionStrategy = "highest_confidence" | "most_relevant" | "balanced";
+/** An entry paired with optional scoring metadata for selection. */
+export interface ScoredEntry {
+    entry: KnowledgeEntry;
+    /** Confidence score (0–1). Used by highest_confidence and balanced strategies. */
+    confidence?: number;
+    /** Relevance score (0–1). Used by most_relevant strategy. */
+    relevance?: number;
+}
+/** Estimate token count from content length (~4 chars per token). */
+export declare function estimateTokens(content: string): number;
+/**
+ * Manages a token budget for loading knowledge entries into a context window.
+ *
+ * Not backed by SQLite — this is a purely in-memory runtime tracker.
+ */
+export declare class TokenTracker {
+    private readonly maxTokens;
+    private used;
+    private reserved;
+    constructor(maxTokens: number);
+    /** Key for deduplication in the reserved map. */
+    private entryKey;
+    /** Current available tokens. */
+    get remaining(): number;
+    /** Check whether an entry's content fits in the remaining budget. */
+    wouldFit(entry: KnowledgeEntry): boolean;
+    /**
+     * Reserve tokens for an entry, deducting from the remaining budget.
+     * Throws if the entry would exceed the budget.
+     * No-op if the entry is already reserved.
+     */
+    reserve(entry: KnowledgeEntry): void;
+    /**
+     * Release tokens previously reserved for an entry, returning them to the budget.
+     * No-op if the entry is not currently reserved.
+     */
+    release(entry: KnowledgeEntry): void;
+    /**
+     * Select entries that fit within the remaining budget using the given strategy.
+     *
+     * @param entries - Scored entries to consider.
+     * @param strategy - Selection strategy.
+     * @returns Entries selected to fit within budget, ordered by strategy priority.
+     */
+    selectEntries(entries: ScoredEntry[], strategy: SelectionStrategy): KnowledgeEntry[];
+    private sortByStrategy;
+    /**
+     * Balanced strategy: interleave entries from different categories,
+     * sorted within each category by a combined confidence + relevance score.
+     */
+    private balancedSort;
+}
+//# sourceMappingURL=token-tracker.d.ts.map

package/dist/budget/token-tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-tracker.d.ts","sourceRoot":"","sources":["../../src/budget/token-tracker.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAMjE,uEAAuE;AACvE,MAAM,MAAM,iBAAiB,GAAG,oBAAoB,GAAG,eAAe,GAAG,UAAU,CAAC;AAEpF,oEAAoE;AACpE,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,cAAc,CAAC;IACtB,kFAAkF;IAClF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6DAA6D;IAC7D,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAMD,qEAAqE;AACrE,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEtD;AAMD;;;;GAIG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,IAAI,CAAa;IACzB,OAAO,CAAC,QAAQ,CAAkC;gBAEtC,SAAS,EAAE,MAAM;IAO7B,iDAAiD;IACjD,OAAO,CAAC,QAAQ;IAIhB,gCAAgC;IAChC,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,qEAAqE;IACrE,QAAQ,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO;IAKxC;;;;OAIG;IACH,OAAO,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI;IAcpC;;;OAGG;IACH,OAAO,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI;IASpC;;;;;;OAMG;IACH,aAAa,CAAC,OAAO,EAAE,WAAW,EAAE,EAAE,QAAQ,EAAE,iBAAiB,GAAG,cAAc,EAAE;IAoBpF,OAAO,CAAC,cAAc;IAatB;;;OAGG;IACH,OAAO,CAAC,YAAY;CA8CrB"}