@vybestack/llxprt-code-core 0.1.12

package/dist/src/utils/retry.test.js

@@ -0,0 +1,322 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { retryWithBackoff } from './retry.js';
+import { setSimulate429 } from './testUtils.js';
+// Helper to create a mock function that fails a certain number of times
+const createFailingFunction = (failures, successValue = 'success') => {
+    let attempts = 0;
+    return vi.fn(async () => {
+        attempts++;
+        if (attempts <= failures) {
+            // Simulate a retryable error
+            const error = new Error(`Simulated error attempt ${attempts}`);
+            error.status = 500; // Simulate a server error
+            throw error;
+        }
+        return successValue;
+    });
+};
+// Custom error for testing non-retryable conditions
+class NonRetryableError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'NonRetryableError';
+    }
+}
+describe('retryWithBackoff', () => {
+    beforeEach(() => {
+        vi.useFakeTimers();
+        // Disable 429 simulation for tests
+        setSimulate429(false);
+        // Suppress unhandled promise rejection warnings for tests that expect errors
+        console.warn = vi.fn();
+    });
+    afterEach(() => {
+        vi.restoreAllMocks();
+        vi.useRealTimers();
+    });
+    it('should return the result on the first attempt if successful', async () => {
+        const mockFn = createFailingFunction(0);
+        const result = await retryWithBackoff(mockFn);
+        expect(result).toBe('success');
+        expect(mockFn).toHaveBeenCalledTimes(1);
+    });
+    it('should retry and succeed if failures are within maxAttempts', async () => {
+        const mockFn = createFailingFunction(2);
+        const promise = retryWithBackoff(mockFn, {
+            maxAttempts: 3,
+            initialDelayMs: 10,
+        });
+        await vi.runAllTimersAsync(); // Ensure all delays and retries complete
+        const result = await promise;
+        expect(result).toBe('success');
+        expect(mockFn).toHaveBeenCalledTimes(3);
+    });
+    it('should throw an error if all attempts fail', async () => {
+        const mockFn = createFailingFunction(3);
+        // 1. Start the retryable operation, which returns a promise.
+        const promise = retryWithBackoff(mockFn, {
+            maxAttempts: 3,
+            initialDelayMs: 10,
+        });
+        // 2. IMPORTANT: Attach the rejection expectation to the promise *immediately*.
+        //    This ensures a 'catch' handler is present before the promise can reject.
+        //    The result is a new promise that resolves when the assertion is met.
+        const assertionPromise = expect(promise).rejects.toThrow('Simulated error attempt 3');
+        // 3. Now, advance the timers. This will trigger the retries and the
+        //    eventual rejection. The handler attached in step 2 will catch it.
+        await vi.runAllTimersAsync();
+        // 4. Await the assertion promise itself to ensure the test was successful.
+        await assertionPromise;
+        // 5. Finally, assert the number of calls.
+        expect(mockFn).toHaveBeenCalledTimes(3);
+    });
+    it('should not retry if shouldRetry returns false', async () => {
+        const mockFn = vi.fn(async () => {
+            throw new NonRetryableError('Non-retryable error');
+        });
+        const shouldRetry = (error) => !(error instanceof NonRetryableError);
+        const promise = retryWithBackoff(mockFn, {
+            shouldRetry,
+            initialDelayMs: 10,
+        });
+        await expect(promise).rejects.toThrow('Non-retryable error');
+        expect(mockFn).toHaveBeenCalledTimes(1);
+    });
+    it('should use default shouldRetry if not provided, retrying on 429', async () => {
+        const mockFn = vi.fn(async () => {
+            const error = new Error('Too Many Requests');
+            error.status = 429;
+            throw error;
+        });
+        const promise = retryWithBackoff(mockFn, {
+            maxAttempts: 2,
+            initialDelayMs: 10,
+        });
+        // Attach the rejection expectation *before* running timers
+        const assertionPromise = expect(promise).rejects.toThrow('Too Many Requests');
+        // Run timers to trigger retries and eventual rejection
+        await vi.runAllTimersAsync();
+        // Await the assertion
+        await assertionPromise;
+        expect(mockFn).toHaveBeenCalledTimes(2);
+    });
+    it('should use default shouldRetry if not provided, not retrying on 400', async () => {
+        const mockFn = vi.fn(async () => {
+            const error = new Error('Bad Request');
+            error.status = 400;
+            throw error;
+        });
+        const promise = retryWithBackoff(mockFn, {
+            maxAttempts: 2,
+            initialDelayMs: 10,
+        });
+        await expect(promise).rejects.toThrow('Bad Request');
+        expect(mockFn).toHaveBeenCalledTimes(1);
+    });
+    it('should respect maxDelayMs', async () => {
+        const mockFn = createFailingFunction(3);
+        const setTimeoutSpy = vi.spyOn(global, 'setTimeout');
+        const promise = retryWithBackoff(mockFn, {
+            maxAttempts: 4,
+            initialDelayMs: 100,
+            maxDelayMs: 250, // Max delay is less than 100 * 2 * 2 = 400
+        });
+        await vi.advanceTimersByTimeAsync(1000); // Advance well past all delays
+        await promise;
+        const delays = setTimeoutSpy.mock.calls.map((call) => call[1]);
+        // Delays should be around initial, initial*2, maxDelay (due to cap)
+        // Jitter makes exact assertion hard, so we check ranges / caps
+        expect(delays.length).toBe(3);
+        expect(delays[0]).toBeGreaterThanOrEqual(100 * 0.7);
+        expect(delays[0]).toBeLessThanOrEqual(100 * 1.3);
+        expect(delays[1]).toBeGreaterThanOrEqual(200 * 0.7);
+        expect(delays[1]).toBeLessThanOrEqual(200 * 1.3);
+        // The third delay should be capped by maxDelayMs (250ms), accounting for jitter
+        expect(delays[2]).toBeGreaterThanOrEqual(250 * 0.7);
+        expect(delays[2]).toBeLessThanOrEqual(250 * 1.3);
+    });
+    it('should handle jitter correctly, ensuring varied delays', async () => {
+        let mockFn = createFailingFunction(5);
+        const setTimeoutSpy = vi.spyOn(global, 'setTimeout');
+        // Run retryWithBackoff multiple times to observe jitter
+        const runRetry = () => retryWithBackoff(mockFn, {
+            maxAttempts: 2, // Only one retry, so one delay
+            initialDelayMs: 100,
+            maxDelayMs: 1000,
+        });
+        // We expect rejections as mockFn fails 5 times
+        const promise1 = runRetry();
+        // Attach the rejection expectation *before* running timers
+        const assertionPromise1 = expect(promise1).rejects.toThrow();
+        await vi.runAllTimersAsync(); // Advance for the delay in the first runRetry
+        await assertionPromise1;
+        const firstDelaySet = setTimeoutSpy.mock.calls.map((call) => call[1]);
+        setTimeoutSpy.mockClear(); // Clear calls for the next run
+        // Reset mockFn to reset its internal attempt counter for the next run
+        mockFn = createFailingFunction(5); // Re-initialize with 5 failures
+        const promise2 = runRetry();
+        // Attach the rejection expectation *before* running timers
+        const assertionPromise2 = expect(promise2).rejects.toThrow();
+        await vi.runAllTimersAsync(); // Advance for the delay in the second runRetry
+        await assertionPromise2;
+        const secondDelaySet = setTimeoutSpy.mock.calls.map((call) => call[1]);
+        // Check that the delays are not exactly the same due to jitter
+        // This is a probabilistic test, but with +/-30% jitter, it's highly likely they differ.
+        if (firstDelaySet.length > 0 && secondDelaySet.length > 0) {
+            // Check the first delay of each set
+            expect(firstDelaySet[0]).not.toBe(secondDelaySet[0]);
+        }
+        else {
+            // If somehow no delays were captured (e.g. test setup issue), fail explicitly
+            throw new Error('Delays were not captured for jitter test');
+        }
+        // Ensure delays are within the expected jitter range [70, 130] for initialDelayMs = 100
+        [...firstDelaySet, ...secondDelaySet].forEach((d) => {
+            expect(d).toBeGreaterThanOrEqual(100 * 0.7);
+            expect(d).toBeLessThanOrEqual(100 * 1.3);
+        });
+    });
+    describe('Flash model fallback for OAuth users', () => {
+        it('should trigger fallback for OAuth personal users after persistent 429 errors', async () => {
+            const fallbackCallback = vi.fn().mockResolvedValue('gemini-2.5-flash');
+            let fallbackOccurred = false;
+            const mockFn = vi.fn().mockImplementation(async () => {
+                if (!fallbackOccurred) {
+                    const error = new Error('Rate limit exceeded');
+                    error.status = 429;
+                    throw error;
+                }
+                return 'success';
+            });
+            const promise = retryWithBackoff(mockFn, {
+                maxAttempts: 3,
+                initialDelayMs: 100,
+                onPersistent429: async (authType) => {
+                    fallbackOccurred = true;
+                    return await fallbackCallback(authType);
+                },
+                authType: 'oauth-personal',
+            });
+            // Advance all timers to complete retries
+            await vi.runAllTimersAsync();
+            // Should succeed after fallback
+            await expect(promise).resolves.toBe('success');
+            // Verify callback was called with correct auth type
+            expect(fallbackCallback).toHaveBeenCalledWith('oauth-personal');
+            // Should retry again after fallback
+            expect(mockFn).toHaveBeenCalledTimes(3); // 2 initial attempts + 1 after fallback
+        });
+        it('should NOT trigger fallback for API key users', async () => {
+            const fallbackCallback = vi.fn();
+            const mockFn = vi.fn(async () => {
+                const error = new Error('Rate limit exceeded');
+                error.status = 429;
+                throw error;
+            });
+            const promise = retryWithBackoff(mockFn, {
+                maxAttempts: 3,
+                initialDelayMs: 100,
+                onPersistent429: fallbackCallback,
+                authType: 'gemini-api-key',
+            });
+            // Handle the promise properly to avoid unhandled rejections
+            const resultPromise = promise.catch((error) => error);
+            await vi.runAllTimersAsync();
+            const result = await resultPromise;
+            // Should fail after all retries without fallback
+            expect(result).toBeInstanceOf(Error);
+            expect(result.message).toBe('Rate limit exceeded');
+            // Callback should not be called for API key users
+            expect(fallbackCallback).not.toHaveBeenCalled();
+        });
+        it('should reset attempt counter and continue after successful fallback', async () => {
+            let fallbackCalled = false;
+            const fallbackCallback = vi.fn().mockImplementation(async () => {
+                fallbackCalled = true;
+                return 'gemini-2.5-flash';
+            });
+            const mockFn = vi.fn().mockImplementation(async () => {
+                if (!fallbackCalled) {
+                    const error = new Error('Rate limit exceeded');
+                    error.status = 429;
+                    throw error;
+                }
+                return 'success';
+            });
+            const promise = retryWithBackoff(mockFn, {
+                maxAttempts: 3,
+                initialDelayMs: 100,
+                onPersistent429: fallbackCallback,
+                authType: 'oauth-personal',
+            });
+            await vi.runAllTimersAsync();
+            await expect(promise).resolves.toBe('success');
+            expect(fallbackCallback).toHaveBeenCalledOnce();
+        });
+        it('should continue with original error if fallback is rejected', async () => {
+            const fallbackCallback = vi.fn().mockResolvedValue(null); // User rejected fallback
+            const mockFn = vi.fn(async () => {
+                const error = new Error('Rate limit exceeded');
+                error.status = 429;
+                throw error;
+            });
+            const promise = retryWithBackoff(mockFn, {
+                maxAttempts: 3,
+                initialDelayMs: 100,
+                onPersistent429: fallbackCallback,
+                authType: 'oauth-personal',
+            });
+            // Handle the promise properly to avoid unhandled rejections
+            const resultPromise = promise.catch((error) => error);
+            await vi.runAllTimersAsync();
+            const result = await resultPromise;
+            // Should fail with original error when fallback is rejected
+            expect(result).toBeInstanceOf(Error);
+            expect(result.message).toBe('Rate limit exceeded');
+            expect(fallbackCallback).toHaveBeenCalledWith('oauth-personal', expect.any(Error));
+        });
+        it('should handle mixed error types (only count consecutive 429s)', async () => {
+            const fallbackCallback = vi.fn().mockResolvedValue('gemini-2.5-flash');
+            let attempts = 0;
+            let fallbackOccurred = false;
+            const mockFn = vi.fn().mockImplementation(async () => {
+                attempts++;
+                if (fallbackOccurred) {
+                    return 'success';
+                }
+                if (attempts === 1) {
+                    // First attempt: 500 error (resets consecutive count)
+                    const error = new Error('Server error');
+                    error.status = 500;
+                    throw error;
+                }
+                else {
+                    // Remaining attempts: 429 errors
+                    const error = new Error('Rate limit exceeded');
+                    error.status = 429;
+                    throw error;
+                }
+            });
+            const promise = retryWithBackoff(mockFn, {
+                maxAttempts: 5,
+                initialDelayMs: 100,
+                onPersistent429: async (authType) => {
+                    fallbackOccurred = true;
+                    return await fallbackCallback(authType);
+                },
+                authType: 'oauth-personal',
+            });
+            await vi.runAllTimersAsync();
+            await expect(promise).resolves.toBe('success');
+            // Should trigger fallback after 2 consecutive 429s (attempts 2-3)
+            expect(fallbackCallback).toHaveBeenCalledWith('oauth-personal');
+        });
+    });
+});
+//# sourceMappingURL=retry.test.js.map

package/dist/src/utils/retry.test.js.map

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

package/dist/src/utils/safeJsonStringify.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Safely stringifies an object to JSON, handling circular references by replacing them with [Circular].
+ *
+ * @param obj - The object to stringify
+ * @param space - Optional space parameter for formatting (defaults to no formatting)
+ * @returns JSON string with circular references replaced by [Circular]
+ */
+export declare function safeJsonStringify(obj: unknown, space?: string | number): string;

package/dist/src/utils/safeJsonStringify.js

@@ -0,0 +1,25 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Safely stringifies an object to JSON, handling circular references by replacing them with [Circular].
+ *
+ * @param obj - The object to stringify
+ * @param space - Optional space parameter for formatting (defaults to no formatting)
+ * @returns JSON string with circular references replaced by [Circular]
+ */
+export function safeJsonStringify(obj, space) {
+    const seen = new WeakSet();
+    return JSON.stringify(obj, (key, value) => {
+        if (typeof value === 'object' && value !== null) {
+            if (seen.has(value)) {
+                return '[Circular]';
+            }
+            seen.add(value);
+        }
+        return value;
+    }, space);
+}
+//# sourceMappingURL=safeJsonStringify.js.map

package/dist/src/utils/safeJsonStringify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"safeJsonStringify.js","sourceRoot":"","sources":["../../../src/utils/safeJsonStringify.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAC/B,GAAY,EACZ,KAAuB;IAEvB,MAAM,IAAI,GAAG,IAAI,OAAO,EAAE,CAAC;IAC3B,OAAO,IAAI,CAAC,SAAS,CACnB,GAAG,EACH,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE;QACb,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;YAChD,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;gBACpB,OAAO,YAAY,CAAC;YACtB,CAAC;YACD,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAClB,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC,EACD,KAAK,CACN,CAAC;AACJ,CAAC"}

package/dist/src/utils/safeJsonStringify.test.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export {};

package/dist/src/utils/safeJsonStringify.test.js

@@ -0,0 +1,61 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { describe, it, expect } from 'vitest';
+import { safeJsonStringify } from './safeJsonStringify.js';
+describe('safeJsonStringify', () => {
+    it('should stringify normal objects without issues', () => {
+        const obj = { name: 'test', value: 42 };
+        const result = safeJsonStringify(obj);
+        expect(result).toBe('{"name":"test","value":42}');
+    });
+    it('should handle circular references by replacing them with [Circular]', () => {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const obj = { name: 'test' };
+        obj.circular = obj; // Create circular reference
+        const result = safeJsonStringify(obj);
+        expect(result).toBe('{"name":"test","circular":"[Circular]"}');
+    });
+    it('should handle complex circular structures like HttpsProxyAgent', () => {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const agent = {
+            sockets: {},
+            options: { host: 'example.com' },
+        };
+        agent.sockets['example.com'] = [{ agent }];
+        const result = safeJsonStringify(agent);
+        expect(result).toContain('[Circular]');
+        expect(result).toContain('example.com');
+    });
+    it('should respect the space parameter for formatting', () => {
+        const obj = { name: 'test', value: 42 };
+        const result = safeJsonStringify(obj, 2);
+        expect(result).toBe('{\n  "name": "test",\n  "value": 42\n}');
+    });
+    it('should handle circular references with formatting', () => {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const obj = { name: 'test' };
+        obj.circular = obj;
+        const result = safeJsonStringify(obj, 2);
+        expect(result).toBe('{\n  "name": "test",\n  "circular": "[Circular]"\n}');
+    });
+    it('should handle arrays with circular references', () => {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const arr = [{ id: 1 }];
+        arr[0].parent = arr; // Create circular reference
+        const result = safeJsonStringify(arr);
+        expect(result).toBe('[{"id":1,"parent":"[Circular]"}]');
+    });
+    it('should handle null and undefined values', () => {
+        expect(safeJsonStringify(null)).toBe('null');
+        expect(safeJsonStringify(undefined)).toBe(undefined);
+    });
+    it('should handle primitive values', () => {
+        expect(safeJsonStringify('test')).toBe('"test"');
+        expect(safeJsonStringify(42)).toBe('42');
+        expect(safeJsonStringify(true)).toBe('true');
+    });
+});
+//# sourceMappingURL=safeJsonStringify.test.js.map

package/dist/src/utils/safeJsonStringify.test.js.map

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

package/dist/src/utils/schemaValidator.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Schema } from '@google/genai';
+/**
+ * Simple utility to validate objects against JSON Schemas
+ */
+export declare class SchemaValidator {
+    /**
+     * Returns null if the data confroms to the schema described by schema (or if schema
+     *  is null). Otherwise, returns a string describing the error.
+     */
+    static validate(schema: Schema | undefined, data: unknown): string | null;
+    /**
+     * Converts @google/genai's Schema to an object compatible with avj.
+     * This is necessary because it represents Types as an Enum (with
+     * UPPERCASE values) and some numeric properties (minItems, maxItems, minLength, maxLength,
+     * minProperties, maxProperties) as strings, when they should be numbers for AJV.
+     */
+    private static toObjectSchema;
+}

package/dist/src/utils/schemaValidator.js

@@ -0,0 +1,142 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import * as ajv from 'ajv';
+const ajValidator = new ajv.Ajv();
+/**
+ * Simple utility to validate objects against JSON Schemas
+ */
+export class SchemaValidator {
+    /**
+     * Returns null if the data confroms to the schema described by schema (or if schema
+     *  is null). Otherwise, returns a string describing the error.
+     */
+    static validate(schema, data) {
+        if (!schema) {
+            return null;
+        }
+        if (typeof data !== 'object' || data === null) {
+            return 'Value of params must be an object';
+        }
+        const objectSchema = this.toObjectSchema(schema);
+        const validate = ajValidator.compile(objectSchema);
+        const valid = validate(data);
+        if (!valid && validate.errors) {
+            const errorText = ajValidator.errorsText(validate.errors, {
+                dataVar: 'params',
+            });
+            return errorText;
+        }
+        return null;
+    }
+    /**
+     * Converts @google/genai's Schema to an object compatible with avj.
+     * This is necessary because it represents Types as an Enum (with
+     * UPPERCASE values) and some numeric properties (minItems, maxItems, minLength, maxLength,
+     * minProperties, maxProperties) as strings, when they should be numbers for AJV.
+     */
+    static toObjectSchema(schema) {
+        const newSchema = { ...schema };
+        // Handle schema composition keywords
+        if (newSchema.anyOf && Array.isArray(newSchema.anyOf)) {
+            newSchema.anyOf = newSchema.anyOf.map((v) => this.toObjectSchema(v));
+        }
+        if (newSchema.allOf && Array.isArray(newSchema.allOf)) {
+            newSchema.allOf = newSchema.allOf.map((v) => this.toObjectSchema(v));
+        }
+        if (newSchema.oneOf && Array.isArray(newSchema.oneOf)) {
+            newSchema.oneOf = newSchema.oneOf.map((v) => this.toObjectSchema(v));
+        }
+        // Handle items (can be a schema or array of schemas for tuples)
+        if (newSchema.items) {
+            if (Array.isArray(newSchema.items)) {
+                newSchema.items = newSchema.items.map((item) => this.toObjectSchema(item));
+            }
+            else {
+                newSchema.items = this.toObjectSchema(newSchema.items);
+            }
+        }
+        // Handle properties
+        if (newSchema.properties && typeof newSchema.properties === 'object') {
+            const newProperties = {};
+            for (const [key, value] of Object.entries(newSchema.properties)) {
+                newProperties[key] = this.toObjectSchema(value);
+            }
+            newSchema.properties = newProperties;
+        }
+        // Handle additionalProperties if it's a schema
+        if (newSchema.additionalProperties &&
+            typeof newSchema.additionalProperties === 'object') {
+            newSchema.additionalProperties = this.toObjectSchema(newSchema.additionalProperties);
+        }
+        // Handle patternProperties
+        if (newSchema.patternProperties &&
+            typeof newSchema.patternProperties === 'object') {
+            const newPatternProperties = {};
+            for (const [key, value] of Object.entries(newSchema.patternProperties)) {
+                newPatternProperties[key] = this.toObjectSchema(value);
+            }
+            newSchema.patternProperties = newPatternProperties;
+        }
+        // Handle dependencies (can be array of property names or schema)
+        if (newSchema.dependencies && typeof newSchema.dependencies === 'object') {
+            const newDependencies = {};
+            for (const [key, value] of Object.entries(newSchema.dependencies)) {
+                if (Array.isArray(value)) {
+                    // Property dependencies (array of property names)
+                    newDependencies[key] = value;
+                }
+                else {
+                    // Schema dependencies
+                    newDependencies[key] = this.toObjectSchema(value);
+                }
+            }
+            newSchema.dependencies = newDependencies;
+        }
+        // Handle if/then/else
+        if (newSchema.if) {
+            newSchema.if = this.toObjectSchema(newSchema.if);
+        }
+        if (newSchema.then) {
+            newSchema.then = this.toObjectSchema(newSchema.then);
+        }
+        if (newSchema.else) {
+            newSchema.else = this.toObjectSchema(newSchema.else);
+        }
+        // Handle not
+        if (newSchema.not) {
+            newSchema.not = this.toObjectSchema(newSchema.not);
+        }
+        // Convert type from UPPERCASE enum to lowercase string
+        if (newSchema.type) {
+            newSchema.type = String(newSchema.type).toLowerCase();
+        }
+        // Convert string-based numeric properties to numbers for AJV
+        const stringNumericProperties = [
+            'minItems',
+            'maxItems',
+            'minLength',
+            'maxLength',
+            'minProperties',
+            'maxProperties',
+        ];
+        for (const prop of stringNumericProperties) {
+            if (newSchema[prop] !== undefined) {
+                newSchema[prop] = Number(newSchema[prop]);
+            }
+        }
+        // These properties are already numbers in @google/genai Schema,
+        // but ensure they are numbers for AJV compatibility
+        const numericProperties = ['minimum', 'maximum', 'multipleOf'];
+        for (const prop of numericProperties) {
+            if (newSchema[prop] !== undefined &&
+                typeof newSchema[prop] === 'string') {
+                newSchema[prop] = Number(newSchema[prop]);
+            }
+        }
+        return newSchema;
+    }
+}
+//# sourceMappingURL=schemaValidator.js.map

package/dist/src/utils/schemaValidator.js.map

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

package/dist/src/utils/schemaValidator.test.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export {};