@machina.ai/cell-cli-core 1.41.1-rc2 → 1.45.1-rc2

package/dist/src/context/utils/snapshotGenerator.test.js

@@ -0,0 +1,362 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { SnapshotGenerator, SnapshotStateHelper, } from './snapshotGenerator.js';
+import { NodeType } from '../graph/types.js';
+describe('SnapshotStateHelper', () => {
+    describe('exportState', () => {
+        it('should flatten nested abstractsIds to pristine IDs', () => {
+            // Setup a graph with nested snapshots
+            // S3 abstracts [S2, N5]
+            // S2 abstracts [S1, N3, N4]
+            // S1 abstracts [N1, N2]
+            const nodes = [
+                {
+                    id: 'N1',
+                    type: NodeType.USER_PROMPT,
+                    timestamp: 10,
+                    role: 'user',
+                    payload: { text: '1' },
+                    turnId: 'T1',
+                },
+                {
+                    id: 'N2',
+                    type: NodeType.AGENT_THOUGHT,
+                    timestamp: 20,
+                    role: 'model',
+                    payload: { text: '2' },
+                    turnId: 'T1',
+                },
+                {
+                    id: 'S1',
+                    type: NodeType.SNAPSHOT,
+                    timestamp: 30,
+                    role: 'user',
+                    payload: { text: 'State 1' },
+                    turnId: 'S1',
+                    abstractsIds: ['N1', 'N2'],
+                },
+                {
+                    id: 'N3',
+                    type: NodeType.USER_PROMPT,
+                    timestamp: 40,
+                    role: 'user',
+                    payload: { text: '3' },
+                    turnId: 'T2',
+                },
+                {
+                    id: 'N4',
+                    type: NodeType.AGENT_THOUGHT,
+                    timestamp: 50,
+                    role: 'model',
+                    payload: { text: '4' },
+                    turnId: 'T2',
+                },
+                {
+                    id: 'S2',
+                    type: NodeType.SNAPSHOT,
+                    timestamp: 60,
+                    role: 'user',
+                    payload: { text: 'State 2' },
+                    turnId: 'S2',
+                    abstractsIds: ['S1', 'N3', 'N4'],
+                },
+                {
+                    id: 'N5',
+                    type: NodeType.USER_PROMPT,
+                    timestamp: 70,
+                    role: 'user',
+                    payload: { text: '5' },
+                    turnId: 'T3',
+                },
+                {
+                    id: 'S3',
+                    type: NodeType.SNAPSHOT,
+                    timestamp: 80,
+                    role: 'user',
+                    payload: { text: 'State 3' },
+                    turnId: 'S3',
+                    abstractsIds: ['S2', 'N5'],
+                },
+            ];
+            const state = SnapshotStateHelper.exportState(nodes);
+            expect(state.snapshot).toBeDefined();
+            expect(state.snapshot?.text).toBe('State 3');
+            // Should be flattened to only the "pristine" (non-snapshot) IDs
+            const consumedIds = state.snapshot?.consumedIds;
+            expect(consumedIds).toContain('N1');
+            expect(consumedIds).toContain('N2');
+            expect(consumedIds).toContain('N3');
+            expect(consumedIds).toContain('N4');
+            expect(consumedIds).toContain('N5');
+            // Should NOT contain the intermediate snapshot IDs
+            expect(consumedIds).not.toContain('S1');
+            expect(consumedIds).not.toContain('S2');
+            expect(consumedIds?.length).toBe(5);
+        });
+        it('should return empty state if no snapshot baseline is found', () => {
+            const nodes = [
+                {
+                    id: 'N1',
+                    type: NodeType.USER_PROMPT,
+                    timestamp: 10,
+                    role: 'user',
+                    payload: { text: '1' },
+                    turnId: 'T1',
+                },
+            ];
+            const state = SnapshotStateHelper.exportState(nodes);
+            expect(state).toEqual({});
+        });
+    });
+});
+describe('SnapshotGenerator', () => {
+    let mockEnv;
+    let mockGenerateJson;
+    beforeEach(() => {
+        mockGenerateJson = vi.fn();
+        mockEnv = {
+            llmClient: {
+                generateJson: mockGenerateJson,
+            },
+            advancedTokenCalculator: {
+                getRawBaseUnits: vi.fn().mockReturnValue(100),
+            },
+            tokenCalculator: {
+                estimateTokensForString: vi.fn().mockReturnValue(100),
+            },
+            promptId: 'test-prompt',
+        };
+    });
+    const dummyNodes = [
+        {
+            id: '1',
+            turnId: '1',
+            type: NodeType.USER_PROMPT,
+            timestamp: 1000,
+            role: 'user',
+            payload: { text: 'Hello' },
+        },
+    ];
+    it('should initialize an empty state if no previous state is provided', async () => {
+        mockGenerateJson.mockResolvedValue({
+            new_facts: ['Fact A'],
+            chronological_summary: 'Did a thing',
+        });
+        const generator = new SnapshotGenerator(mockEnv);
+        const resultJson = await generator.synthesizeSnapshot(dummyNodes);
+        const result = JSON.parse(resultJson);
+        expect(result.discovered_facts).toEqual(['Fact A']);
+        expect(result.recent_arc).toEqual(['Did a thing']);
+        expect(result.active_tasks).toEqual([]);
+    });
+    it('should merge new facts and tasks without destroying old ones', async () => {
+        const prevState = {
+            active_tasks: [{ id: 'task_1', description: 'Old Task' }],
+            discovered_facts: ['Old Fact'],
+            constraints_and_preferences: ['Old Rule'],
+            recent_arc: ['Old summary.'],
+        };
+        mockGenerateJson.mockResolvedValue({
+            new_facts: ['New Fact'],
+            new_tasks: [{ description: 'New Task' }],
+            new_constraints: ['New Rule'],
+            chronological_summary: 'New summary.',
+        });
+        const generator = new SnapshotGenerator(mockEnv);
+        const resultJson = await generator.synthesizeSnapshot(dummyNodes, JSON.stringify(prevState));
+        const result = JSON.parse(resultJson);
+        // Facts and rules should be appended
+        expect(result.discovered_facts).toEqual(['Old Fact', 'New Fact']);
+        expect(result.constraints_and_preferences).toEqual([
+            'Old Rule',
+            'New Rule',
+        ]);
+        // Arc should be appended
+        expect(result.recent_arc).toEqual(['Old summary.', 'New summary.']);
+        // Tasks should include old task and the new one with a generated ID
+        expect(result.active_tasks).toHaveLength(2);
+        expect(result.active_tasks[0]).toEqual({
+            id: 'task_1',
+            description: 'Old Task',
+        });
+        expect(result.active_tasks[1].description).toBe('New Task');
+        expect(result.active_tasks[1].id).toMatch(/^task_[a-f0-9]{8}$/);
+    });
+    it('should explicitly delete obsolete facts and constraints using array indices', async () => {
+        const prevState = {
+            active_tasks: [],
+            discovered_facts: [
+                'Keep me',
+                'Delete me',
+                'Keep me too',
+                'Delete this also',
+            ],
+            constraints_and_preferences: ['Rule 1', 'Rule to drop', 'Rule 3'],
+            recent_arc: [],
+        };
+        mockGenerateJson.mockResolvedValue({
+            obsolete_fact_indices: [1, 3],
+            obsolete_constraint_indices: [1],
+        });
+        const generator = new SnapshotGenerator(mockEnv);
+        const resultJson = await generator.synthesizeSnapshot(dummyNodes, JSON.stringify(prevState));
+        const result = JSON.parse(resultJson);
+        expect(result.discovered_facts).toEqual(['Keep me', 'Keep me too']);
+        expect(result.constraints_and_preferences).toEqual(['Rule 1', 'Rule 3']);
+    });
+    it('should truncate recent_arc to the configured rolling window limit', async () => {
+        const prevState = {
+            active_tasks: [],
+            discovered_facts: [],
+            constraints_and_preferences: [],
+            recent_arc: ['Turn 1', 'Turn 2', 'Turn 3'],
+        };
+        mockGenerateJson.mockResolvedValue({
+            chronological_summary: 'Turn 4',
+        });
+        const generator = new SnapshotGenerator(mockEnv);
+        const resultJson = await generator.synthesizeSnapshot(dummyNodes, JSON.stringify(prevState), { maxSummaryTurns: 3 });
+        const result = JSON.parse(resultJson);
+        expect(result.recent_arc).toEqual(['Turn 2', 'Turn 3', 'Turn 4']);
+    });
+    it('should delete resolved tasks based on IDs', async () => {
+        const prevState = {
+            active_tasks: [
+                { id: 'task_1', description: 'Task to keep' },
+                { id: 'task_2', description: 'Task to resolve' },
+            ],
+            discovered_facts: [],
+            constraints_and_preferences: [],
+            recent_arc: [],
+        };
+        mockGenerateJson.mockResolvedValue({
+            resolved_task_ids: ['task_2'],
+        });
+        const generator = new SnapshotGenerator(mockEnv);
+        const resultJson = await generator.synthesizeSnapshot(dummyNodes, JSON.stringify(prevState));
+        const result = JSON.parse(resultJson);
+        expect(result.active_tasks).toHaveLength(1);
+        expect(result.active_tasks[0].id).toBe('task_1');
+    });
+    it('should safely return the unmodified previous state if the LLM call throws an error', async () => {
+        const prevState = {
+            active_tasks: [{ id: 'task_1', description: 'Important Task' }],
+            discovered_facts: ['Important Fact'],
+            constraints_and_preferences: [],
+            recent_arc: ['Old'],
+        };
+        mockGenerateJson.mockRejectedValue(new Error('LLM API Error'));
+        const generator = new SnapshotGenerator(mockEnv);
+        const resultJson = await generator.synthesizeSnapshot(dummyNodes, JSON.stringify(prevState));
+        const result = JSON.parse(resultJson);
+        // State should remain perfectly intact
+        expect(result).toEqual(prevState);
+    });
+    it('should safely return the unmodified previous state if the LLM returns completely garbage output', async () => {
+        const prevState = {
+            active_tasks: [{ id: 'task_1', description: 'Important Task' }],
+            discovered_facts: ['Important Fact'],
+            constraints_and_preferences: [],
+            recent_arc: ['Old'],
+        };
+        // Return a patch with wrong types that could crash naive merging
+        mockGenerateJson.mockResolvedValue({
+            new_facts: 'This is a string, not an array!',
+            resolved_task_ids: { obj: 'not an array' },
+        });
+        const generator = new SnapshotGenerator(mockEnv);
+        const resultJson = await generator.synthesizeSnapshot(dummyNodes, JSON.stringify(prevState));
+        const result = JSON.parse(resultJson);
+        // State should remain perfectly intact because Array.isArray checks protect the merge logic
+        expect(result.discovered_facts).toEqual(['Important Fact']);
+        expect(result.active_tasks).toHaveLength(1);
+    });
+    describe('Structured Pruning Backstop', () => {
+        it('should iteratively drop discovered_facts first when over budget', async () => {
+            const prevState = {
+                active_tasks: [{ id: 'task_1', description: 'Surviving Task' }],
+                discovered_facts: ['Old Fact 1', 'Old Fact 2', 'Old Fact 3'],
+                constraints_and_preferences: ['Rule 1', 'Rule 2'],
+                recent_arc: ['Arc 1'],
+            };
+            mockGenerateJson.mockResolvedValue({});
+            vi.mocked(mockEnv.tokenCalculator.estimateTokensForString).mockImplementation((str) => str.length);
+            const generator = new SnapshotGenerator(mockEnv);
+            const resultJson = await generator.synthesizeSnapshot(dummyNodes, JSON.stringify(prevState), { maxStateTokens: 150 });
+            const result = JSON.parse(resultJson);
+            expect(resultJson.length).toBeLessThanOrEqual(150);
+            expect(result.discovered_facts.length).toBeLessThan(3);
+        });
+        it('should cascade to dropping constraints if facts are exhausted', async () => {
+            const prevState = {
+                active_tasks: [{ id: 'task_1', description: 'Surviving Task' }],
+                discovered_facts: ['Only Fact'],
+                constraints_and_preferences: ['Rule 1', 'Rule 2'],
+                recent_arc: ['Arc 1'],
+            };
+            mockGenerateJson.mockResolvedValue({});
+            vi.mocked(mockEnv.tokenCalculator.estimateTokensForString).mockImplementation((str) => str.length);
+            const generator = new SnapshotGenerator(mockEnv);
+            const resultJson = await generator.synthesizeSnapshot(dummyNodes, JSON.stringify(prevState), { maxStateTokens: 150 });
+            const result = JSON.parse(resultJson);
+            expect(resultJson.length).toBeLessThanOrEqual(150);
+            expect(result.discovered_facts).toHaveLength(0); // Facts gone
+            expect(result.constraints_and_preferences.length).toBeLessThan(2);
+        });
+        it('should cascade to dropping recent_arc if facts and constraints are exhausted', async () => {
+            const prevState = {
+                active_tasks: [{ id: 'task_1', description: 'Surviving Task' }],
+                discovered_facts: [],
+                constraints_and_preferences: [],
+                recent_arc: ['Arc 1', 'Arc 2'],
+            };
+            mockGenerateJson.mockResolvedValue({});
+            vi.mocked(mockEnv.tokenCalculator.estimateTokensForString).mockImplementation((str) => str.length);
+            const generator = new SnapshotGenerator(mockEnv);
+            const resultJson = await generator.synthesizeSnapshot(dummyNodes, JSON.stringify(prevState), { maxStateTokens: 140 });
+            const result = JSON.parse(resultJson);
+            // String starts at ~151. 140 budget forces both arcs to drop, task remains (len ~135).
+            expect(resultJson.length).toBeLessThanOrEqual(140);
+            expect(result.recent_arc).toEqual([]);
+            expect(result.active_tasks).toHaveLength(1);
+        });
+        it('should ultimately drop active_tasks as a last resort in a pathological scenario', async () => {
+            const prevState = {
+                active_tasks: [
+                    { id: 'task_1', description: 'Task 1' },
+                    { id: 'task_2', description: 'Task 2' },
+                ],
+                discovered_facts: [],
+                constraints_and_preferences: [],
+                recent_arc: [],
+            };
+            mockGenerateJson.mockResolvedValue({});
+            vi.mocked(mockEnv.tokenCalculator.estimateTokensForString).mockImplementation((str) => str.length);
+            const generator = new SnapshotGenerator(mockEnv);
+            const resultJson = await generator.synthesizeSnapshot(dummyNodes, JSON.stringify(prevState), { maxStateTokens: 100 });
+            const result = JSON.parse(resultJson);
+            expect(resultJson.length).toBeLessThanOrEqual(100);
+            expect(result.active_tasks.length).toBeLessThan(2);
+        });
+        it('should cleanly break the loop if the state is completely empty but still over budget', async () => {
+            const prevState = {
+                active_tasks: [],
+                discovered_facts: [],
+                constraints_and_preferences: [],
+                recent_arc: [],
+            };
+            mockGenerateJson.mockResolvedValue({});
+            // Hardcode it to return 5000 always to simulate empty shell over budget
+            vi.mocked(mockEnv.tokenCalculator.estimateTokensForString).mockReturnValue(5000);
+            const generator = new SnapshotGenerator(mockEnv);
+            const resultJson = await generator.synthesizeSnapshot(dummyNodes, JSON.stringify(prevState), { maxStateTokens: 1000 });
+            const result = JSON.parse(resultJson);
+            expect(result).toEqual(prevState);
+        });
+    });
+});
+//# sourceMappingURL=snapshotGenerator.test.js.map

package/dist/src/context/utils/snapshotGenerator.test.js.map

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

package/dist/src/context/utils/tokenCalibration.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { Content } from '@google/genai';
+import type { ContextEnvironment } from '../pipeline/environment.js';
+import type { ConcreteNode } from '../graph/types.js';
+export declare function performCalibration(env: ContextEnvironment, finalNodes: readonly ConcreteNode[], finalContents: Content[]): void;

package/dist/src/context/utils/tokenCalibration.js

@@ -0,0 +1,30 @@
+import { debugLogger } from '../../utils/debugLogger.js';
+export function performCalibration(env, finalNodes, finalContents) {
+    if (!env.renderOptions?.calibrateTokenCalculation) {
+        return;
+    }
+    void (async () => {
+        try {
+            const exactResp = await env.llmClient.countTokens({
+                contents: finalContents,
+            });
+            const exactTokens = typeof exactResp.totalTokens === 'number' ? exactResp.totalTokens : 0;
+            const estimatedTokens = env.tokenCalculator.calculateConcreteListTokens(finalNodes);
+            const delta = Math.abs(exactTokens - estimatedTokens);
+            const tolerance = Math.max(exactTokens, estimatedTokens) * 0.2; // 20% tolerance
+            env.tracer.logEvent('Render', 'Token Calibration Measurement', {
+                exactTokens,
+                estimatedTokens,
+                delta,
+                isWithinTolerance: delta <= tolerance,
+            });
+            if (delta > tolerance) {
+                debugLogger.error(`[Token Calibration] Large deviation detected: exact ${exactTokens} vs estimated ${estimatedTokens} (delta: ${delta})`);
+            }
+        }
+        catch {
+            // Ignore API failures during background calibration
+        }
+    })();
+}
+//# sourceMappingURL=tokenCalibration.js.map

package/dist/src/context/utils/tokenCalibration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokenCalibration.js","sourceRoot":"","sources":["../../../../src/context/utils/tokenCalibration.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAEzD,MAAM,UAAU,kBAAkB,CAChC,GAAuB,EACvB,UAAmC,EACnC,aAAwB;IAExB,IAAI,CAAC,GAAG,CAAC,aAAa,EAAE,yBAAyB,EAAE,CAAC;QAClD,OAAO;IACT,CAAC;IAED,KAAK,CAAC,KAAK,IAAI,EAAE;QACf,IAAI,CAAC;YACH,MAAM,SAAS,GAAG,MAAM,GAAG,CAAC,SAAS,CAAC,WAAW,CAAC;gBAChD,QAAQ,EAAE,aAAa;aACxB,CAAC,CAAC;YACH,MAAM,WAAW,GACf,OAAO,SAAS,CAAC,WAAW,KAAK,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;YACxE,MAAM,eAAe,GACnB,GAAG,CAAC,eAAe,CAAC,2BAA2B,CAAC,UAAU,CAAC,CAAC;YAE9D,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,WAAW,GAAG,eAAe,CAAC,CAAC;YACtD,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,eAAe,CAAC,GAAG,GAAG,CAAC,CAAC,gBAAgB;YAEhF,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,EAAE,+BAA+B,EAAE;gBAC7D,WAAW;gBACX,eAAe;gBACf,KAAK;gBACL,iBAAiB,EAAE,KAAK,IAAI,SAAS;aACtC,CAAC,CAAC;YAEH,IAAI,KAAK,GAAG,SAAS,EAAE,CAAC;gBACtB,WAAW,CAAC,KAAK,CACf,uDAAuD,WAAW,iBAAiB,eAAe,YAAY,KAAK,GAAG,CACvH,CAAC;YACJ,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,oDAAoD;QACtD,CAAC;IACH,CAAC,CAAC,EAAE,CAAC;AACP,CAAC"}

package/dist/src/core/agentChatHistory.d.ts

@@ -4,23 +4,38 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import type { Content } from '@google/genai';
-export type HistoryEventType = 'PUSH' | 'SYNC_FULL' | 'CLEAR';
-export interface HistoryEvent {
-    type: HistoryEventType;
-    payload: readonly Content[];
+/**
+ * A durable wrapper for Gemini Content that carries a stable ID.
+ * This ID is preserved across all transformations and is used as the anchor
+ * for context graph node identity.
+ */
+export interface HistoryTurn {
+    readonly id: string;
+    readonly content: Content;
 }
-export type HistoryListener = (event: HistoryEvent) => void;
+/**
+ * The 'Strong Owner' of chat history turns.
+ * It ensures that every turn in the session is associated with a durable ID.
+ */
 export declare class AgentChatHistory {
     private history;
-    private listeners;
-    constructor(initialHistory?: Content[]);
-    subscribe(listener: HistoryListener): () => void;
-    private notify;
-    push(content: Content): void;
-    set(history: readonly Content[]): void;
+    constructor(initialTurns?: HistoryTurn[]);
+    /**
+     * Adds a new turn to the history.
+     * Every turn must have a durable ID, usually provided by the ChatRecordingService.
+     */
+    push(turn: HistoryTurn): void;
+    /**
+     * Overwrites the entire history with a new list of turns.
+     */
+    set(turns: readonly HistoryTurn[]): void;
     clear(): void;
-    get(): readonly Content[];
-    map(callback: (value: Content, index: number, array: Content[]) => Content): void;
-    flatMap<U>(callback: (value: Content, index: number, array: Content[]) => U | readonly U[]): U[];
+    get(): readonly HistoryTurn[];
+    /**
+     * Returns a copy of the raw Gemini Content[] for API consumption.
+     */
+    getContents(): Content[];
+    map<U>(callback: (value: HistoryTurn, index: number, array: HistoryTurn[]) => U): U[];
+    flatMap<U>(callback: (value: HistoryTurn, index: number, array: HistoryTurn[]) => U | readonly U[]): U[];
     get length(): number;
 }

package/dist/src/core/agentChatHistory.js

@@ -3,42 +3,42 @@
  * Copyright 2026 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+/**
+ * The 'Strong Owner' of chat history turns.
+ * It ensures that every turn in the session is associated with a durable ID.
+ */
 export class AgentChatHistory {
-    history;
-    listeners = new Set();
-    constructor(initialHistory = []) {
-        this.history = [...initialHistory];
-    }
-    subscribe(listener) {
-        this.listeners.add(listener);
-        // Emit initial state to new subscriber
-        listener({ type: 'SYNC_FULL', payload: this.history });
-        return () => this.listeners.delete(listener);
-    }
-    notify(type, payload) {
-        const event = { type, payload };
-        for (const listener of this.listeners) {
-            listener(event);
-        }
-    }
-    push(content) {
-        this.history.push(content);
-        this.notify('PUSH', [content]);
-    }
-    set(history) {
-        this.history = [...history];
-        this.notify('SYNC_FULL', this.history);
+    history = [];
+    constructor(initialTurns = []) {
+        this.history = [...initialTurns];
+    }
+    /**
+     * Adds a new turn to the history.
+     * Every turn must have a durable ID, usually provided by the ChatRecordingService.
+     */
+    push(turn) {
+        this.history.push(turn);
+    }
+    /**
+     * Overwrites the entire history with a new list of turns.
+     */
+    set(turns) {
+        this.history = [...turns];
     }
     clear() {
         this.history = [];
-        this.notify('CLEAR', []);
     }
     get() {
         return this.history;
     }
+    /**
+     * Returns a copy of the raw Gemini Content[] for API consumption.
+     */
+    getContents() {
+        return this.history.map((h) => h.content);
+    }
     map(callback) {
-        this.history = this.history.map(callback);
-        this.notify('SYNC_FULL', this.history);
+        return this.history.map(callback);
     }
     flatMap(callback) {
         return this.history.flatMap(callback);

package/dist/src/core/agentChatHistory.js.map

@@ -1 +1 @@
-{"version":3,"file":"agentChatHistory.js","sourceRoot":"","sources":["../../../src/core/agentChatHistory.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAaH,MAAM,OAAO,gBAAgB;IACnB,OAAO,CAAY;IACnB,SAAS,GAAyB,IAAI,GAAG,EAAE,CAAC;IAEpD,YAAY,iBAA4B,EAAE;QACxC,IAAI,CAAC,OAAO,GAAG,CAAC,GAAG,cAAc,CAAC,CAAC;IACrC,CAAC;IAED,SAAS,CAAC,QAAyB;QACjC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC7B,uCAAuC;QACvC,QAAQ,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;QACvD,OAAO,GAAG,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC/C,CAAC;IAEO,MAAM,CAAC,IAAsB,EAAE,OAA2B;QAChE,MAAM,KAAK,GAAiB,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;QAC9C,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACtC,QAAQ,CAAC,KAAK,CAAC,CAAC;QAClB,CAAC;IACH,CAAC;IAED,IAAI,CAAC,OAAgB;QACnB,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC3B,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;IACjC,CAAC;IAED,GAAG,CAAC,OAA2B;QAC7B,IAAI,CAAC,OAAO,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC;QAC5B,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;IACzC,CAAC;IAED,KAAK;QACH,IAAI,CAAC,OAAO,GAAG,EAAE,CAAC;QAClB,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;IAC3B,CAAC;IAED,GAAG;QACD,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAED,GAAG,CAAC,QAAsE;QACxE,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC1C,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;IACzC,CAAC;IAED,OAAO,CACL,QAIqB;QAErB,OAAO,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACxC,CAAC;IAED,IAAI,MAAM;QACR,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC;IAC7B,CAAC;CACF"}
+{"version":3,"file":"agentChatHistory.js","sourceRoot":"","sources":["../../../src/core/agentChatHistory.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAcH;;;GAGG;AACH,MAAM,OAAO,gBAAgB;IACnB,OAAO,GAAkB,EAAE,CAAC;IAEpC,YAAY,eAA8B,EAAE;QAC1C,IAAI,CAAC,OAAO,GAAG,CAAC,GAAG,YAAY,CAAC,CAAC;IACnC,CAAC;IAED;;;OAGG;IACH,IAAI,CAAC,IAAiB;QACpB,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IAED;;OAEG;IACH,GAAG,CAAC,KAA6B;QAC/B,IAAI,CAAC,OAAO,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC;IAC5B,CAAC;IAED,KAAK;QACH,IAAI,CAAC,OAAO,GAAG,EAAE,CAAC;IACpB,CAAC;IAED,GAAG;QACD,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAED;;OAEG;IACH,WAAW;QACT,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;IAC5C,CAAC;IAED,GAAG,CACD,QAAwE;QAExE,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACpC,CAAC;IAED,OAAO,CACL,QAIqB;QAErB,OAAO,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACxC,CAAC;IAED,IAAI,MAAM;QACR,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC;IAC7B,CAAC;CACF"}

package/dist/src/core/baseLlmClient.d.ts

@@ -66,6 +66,11 @@ export interface GenerateContentOptions {
      */
     maxAttempts?: number;
 }
+export interface CountTokenOptions {
+    modelConfigKey?: ModelConfigKey;
+    contents: Content[];
+    abortSignal?: AbortSignal;
+}
 /**
  * A client dedicated to stateless, utility-focused LLM calls.
  */
@@ -77,6 +82,9 @@ export declare class BaseLlmClient {
     generateJson(options: GenerateJsonOptions): Promise<Record<string, unknown>>;
     generateEmbedding(texts: string[]): Promise<number[][]>;
     private cleanJsonResponse;
+    countTokens(options: CountTokenOptions): Promise<{
+        totalTokens: number;
+    }>;
     generateContent(options: GenerateContentOptions): Promise<GenerateContentResponse>;
     private _generateWithRetry;
 }

package/dist/src/core/baseLlmClient.js

@@ -56,8 +56,12 @@ export class BaseLlmClient {
             },
         }, shouldRetryOnContent, 'generateJson', role);
         // If we are here, the content is valid (not empty and parsable).
-        // eslint-disable-next-line @typescript-eslint/no-unsafe-return
-        return JSON.parse(this.cleanJsonResponse(getResponseText(result).trim(), model));
+        const parsed = JSON.parse(this.cleanJsonResponse(getResponseText(result).trim(), model));
+        const isRecord = (val) => typeof val === 'object' && val !== null && !Array.isArray(val);
+        if (isRecord(parsed)) {
+            return parsed;
+        }
+        throw new Error('Invalid JSON response format from LLM');
     }
     async generateEmbedding(texts) {
         if (!texts || texts.length === 0) {
@@ -92,6 +96,20 @@ export class BaseLlmClient {
         }
         return text;
     }
+    async countTokens(options) {
+        const model = options.modelConfigKey
+            ? this.config.modelConfigService.getResolvedConfig(options.modelConfigKey)
+                .model
+            : this.config.getActiveModel();
+        const result = await this.contentGenerator.countTokens({
+            model,
+            contents: options.contents,
+            config: options.abortSignal
+                ? { abortSignal: options.abortSignal }
+                : undefined,
+        });
+        return { totalTokens: result.totalTokens || 0 };
+    }
     async generateContent(options) {
         const { modelConfigKey, contents, systemInstruction, abortSignal, promptId, role, maxAttempts, } = options;
         const shouldRetryOnContent = (response) => {
@@ -153,7 +171,9 @@ export class BaseLlmClient {
                 authType: this.authType ?? this.config.getContentGeneratorConfig()?.authType,
                 retryFetchErrors: this.config.getRetryFetchErrors(),
                 onRetry: (attempt, error, delayMs) => {
-                    const actualMaxAttempts = availabilityMaxAttempts ?? maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
+                    const actualMaxAttempts = getAvailabilityContext()?.policy.maxAttempts ??
+                        maxAttempts ??
+                        DEFAULT_MAX_ATTEMPTS;
                     const modelName = getDisplayString(currentModel);
                     const errorType = getRetryErrorType(error);
                     coreEvents.emitRetryAttempt({