@google/gemini-cli-core 0.5.0-preview.1 → 0.7.0-nightly.20250912.68035591

package/dist/src/policy/stable-stringify.js

@@ -0,0 +1,122 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Produces a stable, deterministic JSON string representation with sorted keys.
+ *
+ * This method is critical for security policy matching. It ensures that the same
+ * object always produces the same string representation, regardless of property
+ * insertion order, which could vary across different JavaScript engines or
+ * runtime conditions.
+ *
+ * Key behaviors:
+ * 1. **Sorted Keys**: Object properties are always serialized in alphabetical order,
+ *    ensuring deterministic output for pattern matching.
+ *
+ * 2. **Circular Reference Protection**: Uses ancestor chain tracking (not just
+ *    object identity) to detect true circular references while correctly handling
+ *    repeated non-circular object references. Circular references are replaced
+ *    with "[Circular]" to prevent stack overflow attacks.
+ *
+ * 3. **JSON Spec Compliance**:
+ *    - undefined values: Omitted from objects, converted to null in arrays
+ *    - Functions: Omitted from objects, converted to null in arrays
+ *    - toJSON methods: Respected and called when present (per JSON.stringify spec)
+ *
+ * 4. **Security Considerations**:
+ *    - Prevents DoS via circular references that would cause infinite recursion
+ *    - Ensures consistent policy rule matching by normalizing property order
+ *    - Respects toJSON for objects that sanitize their output
+ *    - Handles toJSON methods that throw errors gracefully
+ *
+ * @param obj - The object to stringify (typically toolCall.args)
+ * @returns A deterministic JSON string representation
+ *
+ * @example
+ * // Different property orders produce the same output:
+ * stableStringify({b: 2, a: 1}) === stableStringify({a: 1, b: 2})
+ * // Returns: '{"a":1,"b":2}'
+ *
+ * @example
+ * // Circular references are handled safely:
+ * const obj = {a: 1};
+ * obj.self = obj;
+ * stableStringify(obj)
+ * // Returns: '{"a":1,"self":"[Circular]"}'
+ *
+ * @example
+ * // toJSON methods are respected:
+ * const obj = {
+ *   sensitive: 'secret',
+ *   toJSON: () => ({ safe: 'data' })
+ * };
+ * stableStringify(obj)
+ * // Returns: '{"safe":"data"}'
+ */
+export function stableStringify(obj) {
+    const stringify = (currentObj, ancestors) => {
+        // Handle primitives and null
+        if (currentObj === undefined) {
+            return 'null'; // undefined in arrays becomes null in JSON
+        }
+        if (currentObj === null) {
+            return 'null';
+        }
+        if (typeof currentObj === 'function') {
+            return 'null'; // functions in arrays become null in JSON
+        }
+        if (typeof currentObj !== 'object') {
+            return JSON.stringify(currentObj);
+        }
+        // Check for circular reference (object is in ancestor chain)
+        if (ancestors.has(currentObj)) {
+            return '"[Circular]"';
+        }
+        ancestors.add(currentObj);
+        try {
+            // Check for toJSON method and use it if present
+            const objWithToJSON = currentObj;
+            if (typeof objWithToJSON.toJSON === 'function') {
+                try {
+                    const jsonValue = objWithToJSON.toJSON();
+                    // The result of toJSON needs to be stringified recursively
+                    if (jsonValue === null) {
+                        return 'null';
+                    }
+                    return stringify(jsonValue, ancestors);
+                }
+                catch {
+                    // If toJSON throws, treat as a regular object
+                }
+            }
+            if (Array.isArray(currentObj)) {
+                const items = currentObj.map((item) => {
+                    // undefined and functions in arrays become null
+                    if (item === undefined || typeof item === 'function') {
+                        return 'null';
+                    }
+                    return stringify(item, ancestors);
+                });
+                return '[' + items.join(',') + ']';
+            }
+            // Handle objects - sort keys and filter out undefined/function values
+            const sortedKeys = Object.keys(currentObj).sort();
+            const pairs = [];
+            for (const key of sortedKeys) {
+                const value = currentObj[key];
+                // Skip undefined and function values in objects (per JSON spec)
+                if (value !== undefined && typeof value !== 'function') {
+                    pairs.push(JSON.stringify(key) + ':' + stringify(value, ancestors));
+                }
+            }
+            return '{' + pairs.join(',') + '}';
+        }
+        finally {
+            ancestors.delete(currentObj);
+        }
+    };
+    return stringify(obj, new Set());
+}
+//# sourceMappingURL=stable-stringify.js.map

package/dist/src/policy/stable-stringify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stable-stringify.js","sourceRoot":"","sources":["../../../src/policy/stable-stringify.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,MAAM,UAAU,eAAe,CAAC,GAAY;IAC1C,MAAM,SAAS,GAAG,CAAC,UAAmB,EAAE,SAAuB,EAAU,EAAE;QACzE,6BAA6B;QAC7B,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;YAC7B,OAAO,MAAM,CAAC,CAAC,2CAA2C;QAC5D,CAAC;QACD,IAAI,UAAU,KAAK,IAAI,EAAE,CAAC;YACxB,OAAO,MAAM,CAAC;QAChB,CAAC;QACD,IAAI,OAAO,UAAU,KAAK,UAAU,EAAE,CAAC;YACrC,OAAO,MAAM,CAAC,CAAC,0CAA0C;QAC3D,CAAC;QACD,IAAI,OAAO,UAAU,KAAK,QAAQ,EAAE,CAAC;YACnC,OAAO,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC;QACpC,CAAC;QAED,6DAA6D;QAC7D,IAAI,SAAS,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC;YAC9B,OAAO,cAAc,CAAC;QACxB,CAAC;QAED,SAAS,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;QAE1B,IAAI,CAAC;YACH,gDAAgD;YAChD,MAAM,aAAa,GAAG,UAAwC,CAAC;YAC/D,IAAI,OAAO,aAAa,CAAC,MAAM,KAAK,UAAU,EAAE,CAAC;gBAC/C,IAAI,CAAC;oBACH,MAAM,SAAS,GAAG,aAAa,CAAC,MAAM,EAAE,CAAC;oBACzC,2DAA2D;oBAC3D,IAAI,SAAS,KAAK,IAAI,EAAE,CAAC;wBACvB,OAAO,MAAM,CAAC;oBAChB,CAAC;oBACD,OAAO,SAAS,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;gBACzC,CAAC;gBAAC,MAAM,CAAC;oBACP,8CAA8C;gBAChD,CAAC;YACH,CAAC;YAED,IAAI,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC;gBAC9B,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;oBACpC,gDAAgD;oBAChD,IAAI,IAAI,KAAK,SAAS,IAAI,OAAO,IAAI,KAAK,UAAU,EAAE,CAAC;wBACrD,OAAO,MAAM,CAAC;oBAChB,CAAC;oBACD,OAAO,SAAS,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;gBACpC,CAAC,CAAC,CAAC;gBACH,OAAO,GAAG,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC;YACrC,CAAC;YAED,sEAAsE;YACtE,MAAM,UAAU,GAAG,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,IAAI,EAAE,CAAC;YAClD,MAAM,KAAK,GAAa,EAAE,CAAC;YAE3B,KAAK,MAAM,GAAG,IAAI,UAAU,EAAE,CAAC;gBAC7B,MAAM,KAAK,GAAI,UAAsC,CAAC,GAAG,CAAC,CAAC;gBAC3D,gEAAgE;gBAChE,IAAI,KAAK,KAAK,SAAS,IAAI,OAAO,KAAK,KAAK,UAAU,EAAE,CAAC;oBACvD,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,GAAG,GAAG,SAAS,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC;gBACtE,CAAC;YACH,CAAC;YAED,OAAO,GAAG,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC;QACrC,CAAC;gBAAS,CAAC;YACT,SAAS,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;QAC/B,CAAC;IACH,CAAC,CAAC;IAEF,OAAO,SAAS,CAAC,GAAG,EAAE,IAAI,GAAG,EAAE,CAAC,CAAC;AACnC,CAAC"}

package/dist/src/policy/types.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export declare enum PolicyDecision {
+    ALLOW = "allow",
+    DENY = "deny",
+    ASK_USER = "ask_user"
+}
+export interface PolicyRule {
+    /**
+     * The name of the tool this rule applies to.
+     * If undefined, the rule applies to all tools.
+     */
+    toolName?: string;
+    /**
+     * Pattern to match against tool arguments.
+     * Can be used for more fine-grained control.
+     */
+    argsPattern?: RegExp;
+    /**
+     * The decision to make when this rule matches.
+     */
+    decision: PolicyDecision;
+    /**
+     * Priority of this rule. Higher numbers take precedence.
+     * Default is 0.
+     */
+    priority?: number;
+}
+export interface PolicyEngineConfig {
+    /**
+     * List of policy rules to apply.
+     */
+    rules?: PolicyRule[];
+    /**
+     * Default decision when no rules match.
+     * Defaults to ASK_USER.
+     */
+    defaultDecision?: PolicyDecision;
+    /**
+     * Whether to allow tools in non-interactive mode.
+     * When true, ASK_USER decisions become DENY.
+     */
+    nonInteractive?: boolean;
+}

package/dist/src/policy/types.js

@@ -0,0 +1,12 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export var PolicyDecision;
+(function (PolicyDecision) {
+    PolicyDecision["ALLOW"] = "allow";
+    PolicyDecision["DENY"] = "deny";
+    PolicyDecision["ASK_USER"] = "ask_user";
+})(PolicyDecision || (PolicyDecision = {}));
+//# sourceMappingURL=types.js.map

package/dist/src/policy/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/policy/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,CAAN,IAAY,cAIX;AAJD,WAAY,cAAc;IACxB,iCAAe,CAAA;IACf,+BAAa,CAAA;IACb,uCAAqB,CAAA;AACvB,CAAC,EAJW,cAAc,KAAd,cAAc,QAIzB"}

package/dist/src/routing/modelRouterService.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { Config } from '../config/config.js';
+import type { RoutingContext, RoutingDecision } from './routingStrategy.js';
+/**
+ * A centralized service for making model routing decisions.
+ */
+export declare class ModelRouterService {
+    private config;
+    private strategy;
+    constructor(config: Config);
+    private initializeDefaultStrategy;
+    /**
+     * Determines which model to use for a given request context.
+     *
+     * @param context The full context of the request.
+     * @returns A promise that resolves to a RoutingDecision.
+     */
+    route(context: RoutingContext): Promise<RoutingDecision>;
+}

package/dist/src/routing/modelRouterService.js

@@ -0,0 +1,36 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { DefaultStrategy } from './strategies/defaultStrategy.js';
+import { CompositeStrategy } from './strategies/compositeStrategy.js';
+import { FallbackStrategy } from './strategies/fallbackStrategy.js';
+import { OverrideStrategy } from './strategies/overrideStrategy.js';
+/**
+ * A centralized service for making model routing decisions.
+ */
+export class ModelRouterService {
+    config;
+    strategy;
+    constructor(config) {
+        this.config = config;
+        this.strategy = this.initializeDefaultStrategy();
+    }
+    initializeDefaultStrategy() {
+        // Initialize the composite strategy with the desired priority order.
+        // The strategies are ordered in order of highest priority.
+        return new CompositeStrategy([new FallbackStrategy(), new OverrideStrategy(), new DefaultStrategy()], 'agent-router');
+    }
+    /**
+     * Determines which model to use for a given request context.
+     *
+     * @param context The full context of the request.
+     * @returns A promise that resolves to a RoutingDecision.
+     */
+    async route(context) {
+        const decision = await this.strategy.route(context, this.config, this.config.getBaseLlmClient());
+        return decision;
+    }
+}
+//# sourceMappingURL=modelRouterService.js.map

package/dist/src/routing/modelRouterService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"modelRouterService.js","sourceRoot":"","sources":["../../../src/routing/modelRouterService.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAQH,OAAO,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAClE,OAAO,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AACtE,OAAO,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AACpE,OAAO,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AAEpE;;GAEG;AACH,MAAM,OAAO,kBAAkB;IACrB,MAAM,CAAS;IACf,QAAQ,CAAmB;IAEnC,YAAY,MAAc;QACxB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,yBAAyB,EAAE,CAAC;IACnD,CAAC;IAEO,yBAAyB;QAC/B,qEAAqE;QACrE,2DAA2D;QAC3D,OAAO,IAAI,iBAAiB,CAC1B,CAAC,IAAI,gBAAgB,EAAE,EAAE,IAAI,gBAAgB,EAAE,EAAE,IAAI,eAAe,EAAE,CAAC,EACvE,cAAc,CACf,CAAC;IACJ,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,KAAK,CAAC,OAAuB;QACjC,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,KAAK,CACxC,OAAO,EACP,IAAI,CAAC,MAAM,EACX,IAAI,CAAC,MAAM,CAAC,gBAAgB,EAAE,CAC/B,CAAC;QAEF,OAAO,QAAQ,CAAC;IAClB,CAAC;CACF"}

package/dist/src/routing/modelRouterService.test.d.ts

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

package/dist/src/routing/modelRouterService.test.js

@@ -0,0 +1,72 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { ModelRouterService } from './modelRouterService.js';
+import { Config } from '../config/config.js';
+import { DefaultStrategy } from './strategies/defaultStrategy.js';
+import { CompositeStrategy } from './strategies/compositeStrategy.js';
+import { FallbackStrategy } from './strategies/fallbackStrategy.js';
+import { OverrideStrategy } from './strategies/overrideStrategy.js';
+vi.mock('../config/config.js');
+vi.mock('../core/baseLlmClient.js');
+vi.mock('./strategies/defaultStrategy.js');
+vi.mock('./strategies/compositeStrategy.js');
+vi.mock('./strategies/fallbackStrategy.js');
+vi.mock('./strategies/overrideStrategy.js');
+describe('ModelRouterService', () => {
+    let service;
+    let mockConfig;
+    let mockBaseLlmClient;
+    let mockContext;
+    let mockCompositeStrategy;
+    beforeEach(() => {
+        vi.clearAllMocks();
+        mockConfig = new Config({});
+        mockBaseLlmClient = {};
+        vi.spyOn(mockConfig, 'getBaseLlmClient').mockReturnValue(mockBaseLlmClient);
+        mockCompositeStrategy = new CompositeStrategy([new FallbackStrategy(), new OverrideStrategy(), new DefaultStrategy()], 'agent-router');
+        vi.mocked(CompositeStrategy).mockImplementation(() => mockCompositeStrategy);
+        service = new ModelRouterService(mockConfig);
+        mockContext = {
+            history: [],
+            request: [{ text: 'test prompt' }],
+            signal: new AbortController().signal,
+        };
+    });
+    it('should initialize with a CompositeStrategy', () => {
+        expect(CompositeStrategy).toHaveBeenCalled();
+        expect(service['strategy']).toBeInstanceOf(CompositeStrategy);
+    });
+    it('should initialize the CompositeStrategy with the correct child strategies in order', () => {
+        // This test relies on the mock implementation detail of the constructor
+        const compositeStrategyArgs = vi.mocked(CompositeStrategy).mock.calls[0];
+        const childStrategies = compositeStrategyArgs[0];
+        expect(childStrategies.length).toBe(3);
+        expect(childStrategies[0]).toBeInstanceOf(FallbackStrategy);
+        expect(childStrategies[1]).toBeInstanceOf(OverrideStrategy);
+        expect(childStrategies[2]).toBeInstanceOf(DefaultStrategy);
+        expect(compositeStrategyArgs[1]).toBe('agent-router');
+    });
+    describe('route()', () => {
+        it('should delegate routing to the composite strategy', async () => {
+            const strategyDecision = {
+                model: 'strategy-chosen-model',
+                metadata: {
+                    source: 'test-router/fallback',
+                    latencyMs: 10,
+                    reasoning: 'Strategy reasoning',
+                },
+            };
+            const strategySpy = vi
+                .spyOn(mockCompositeStrategy, 'route')
+                .mockResolvedValue(strategyDecision);
+            const decision = await service.route(mockContext);
+            expect(strategySpy).toHaveBeenCalledWith(mockContext, mockConfig, mockBaseLlmClient);
+            expect(decision).toEqual(strategyDecision);
+        });
+    });
+});
+//# sourceMappingURL=modelRouterService.test.js.map

package/dist/src/routing/modelRouterService.test.js.map

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

package/dist/src/routing/routingStrategy.d.ts

@@ -0,0 +1,62 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { Content, PartListUnion } from '@google/genai';
+import type { BaseLlmClient } from '../core/baseLlmClient.js';
+import type { Config } from '../config/config.js';
+/**
+ * The output of a routing decision. It specifies which model to use and why.
+ */
+export interface RoutingDecision {
+    /** The model identifier string to use for the next API call (e.g., 'gemini-2.5-pro'). */
+    model: string;
+    /**
+     * Metadata about the routing decision for logging purposes.
+     */
+    metadata: {
+        source: string;
+        latencyMs: number;
+        reasoning: string;
+        error?: string;
+    };
+}
+/**
+ * The context provided to the router for making a decision.
+ */
+export interface RoutingContext {
+    /** The full history of the conversation. */
+    history: Content[];
+    /** The immediate request parts to be processed. */
+    request: PartListUnion;
+    /** An abort signal to cancel an LLM call during routing. */
+    signal: AbortSignal;
+}
+/**
+ * The core interface that all routing strategies must implement.
+ * Strategies implementing this interface may decline a request by returning null.
+ */
+export interface RoutingStrategy {
+    /** The name of the strategy (e.g., 'fallback', 'override', 'composite'). */
+    readonly name: string;
+    /**
+     * Determines which model to use for a given request context.
+     * @param context The full context of the request.
+     * @param config The current configuration.
+     * @param client A reference to the GeminiClient, allowing the strategy to make its own API calls if needed.
+     * @returns A promise that resolves to a RoutingDecision, or null if the strategy is not applicable.
+     */
+    route(context: RoutingContext, config: Config, baseLlmClient: BaseLlmClient): Promise<RoutingDecision | null>;
+}
+/**
+ * A strategy that is guaranteed to return a decision. It must not return null.
+ * This is used to ensure that a composite chain always terminates.
+ */
+export interface TerminalStrategy extends RoutingStrategy {
+    /**
+     * Determines which model to use for a given request context.
+     * @returns A promise that resolves to a RoutingDecision.
+     */
+    route(context: RoutingContext, config: Config, baseLlmClient: BaseLlmClient): Promise<RoutingDecision>;
+}

package/dist/src/routing/routingStrategy.js

@@ -0,0 +1,7 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export {};
+//# sourceMappingURL=routingStrategy.js.map

package/dist/src/routing/routingStrategy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"routingStrategy.js","sourceRoot":"","sources":["../../../src/routing/routingStrategy.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/src/routing/strategies/compositeStrategy.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { Config } from '../../config/config.js';
+import type { BaseLlmClient } from '../../core/baseLlmClient.js';
+import type { RoutingContext, RoutingDecision, RoutingStrategy, TerminalStrategy } from '../routingStrategy.js';
+/**
+ * A strategy that attempts a list of child strategies in order (Chain of Responsibility).
+ */
+export declare class CompositeStrategy implements TerminalStrategy {
+    readonly name: string;
+    private strategies;
+    /**
+     * Initializes the CompositeStrategy.
+     * @param strategies The strategies to try, in order of priority. The last strategy must be terminal.
+     * @param name The name of this composite configuration (e.g., 'router' or 'composite').
+     */
+    constructor(strategies: [...RoutingStrategy[], TerminalStrategy], name?: string);
+    route(context: RoutingContext, config: Config, baseLlmClient: BaseLlmClient): Promise<RoutingDecision>;
+    /**
+     * Helper function to enhance the decision metadata with composite information.
+     */
+    private finalizeDecision;
+}

package/dist/src/routing/strategies/compositeStrategy.js

@@ -0,0 +1,67 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * A strategy that attempts a list of child strategies in order (Chain of Responsibility).
+ */
+export class CompositeStrategy {
+    name;
+    strategies;
+    /**
+     * Initializes the CompositeStrategy.
+     * @param strategies The strategies to try, in order of priority. The last strategy must be terminal.
+     * @param name The name of this composite configuration (e.g., 'router' or 'composite').
+     */
+    constructor(strategies, name = 'composite') {
+        this.strategies = strategies;
+        this.name = name;
+    }
+    async route(context, config, baseLlmClient) {
+        const startTime = performance.now();
+        // Separate non-terminal strategies from the terminal one.
+        // This separation allows TypeScript to understand the control flow guarantees.
+        const nonTerminalStrategies = this.strategies.slice(0, -1);
+        const terminalStrategy = this.strategies[this.strategies.length - 1];
+        // Try non-terminal strategies, allowing them to fail gracefully.
+        for (const strategy of nonTerminalStrategies) {
+            try {
+                const decision = await strategy.route(context, config, baseLlmClient);
+                if (decision) {
+                    return this.finalizeDecision(decision, startTime);
+                }
+            }
+            catch (error) {
+                console.error(`[Routing] Strategy '${strategy.name}' failed. Continuing to next strategy. Error:`, error);
+            }
+        }
+        // If no other strategy matched, execute the terminal strategy.
+        try {
+            const decision = await terminalStrategy.route(context, config, baseLlmClient);
+            return this.finalizeDecision(decision, startTime);
+        }
+        catch (error) {
+            console.error(`[Routing] Critical Error: Terminal strategy '${terminalStrategy.name}' failed. Routing cannot proceed. Error:`, error);
+            throw error;
+        }
+    }
+    /**
+     * Helper function to enhance the decision metadata with composite information.
+     */
+    finalizeDecision(decision, startTime) {
+        const endTime = performance.now();
+        const totalLatency = endTime - startTime;
+        // Combine the source paths: composite_name/child_source (e.g. 'router/default')
+        const compositeSource = `${this.name}/${decision.metadata.source}`;
+        return {
+            ...decision,
+            metadata: {
+                ...decision.metadata,
+                source: compositeSource,
+                latencyMs: decision.metadata.latencyMs || totalLatency,
+            },
+        };
+    }
+}
+//# sourceMappingURL=compositeStrategy.js.map

package/dist/src/routing/strategies/compositeStrategy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compositeStrategy.js","sourceRoot":"","sources":["../../../../src/routing/strategies/compositeStrategy.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAWH;;GAEG;AACH,MAAM,OAAO,iBAAiB;IACnB,IAAI,CAAS;IAEd,UAAU,CAA2C;IAE7D;;;;OAIG;IACH,YACE,UAAoD,EACpD,OAAe,WAAW;QAE1B,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;IAED,KAAK,CAAC,KAAK,CACT,OAAuB,EACvB,MAAc,EACd,aAA4B;QAE5B,MAAM,SAAS,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;QAEpC,0DAA0D;QAC1D,+EAA+E;QAC/E,MAAM,qBAAqB,GAAG,IAAI,CAAC,UAAU,CAAC,KAAK,CACjD,CAAC,EACD,CAAC,CAAC,CACkB,CAAC;QACvB,MAAM,gBAAgB,GAAG,IAAI,CAAC,UAAU,CACtC,IAAI,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,CACP,CAAC;QAEtB,iEAAiE;QACjE,KAAK,MAAM,QAAQ,IAAI,qBAAqB,EAAE,CAAC;YAC7C,IAAI,CAAC;gBACH,MAAM,QAAQ,GAAG,MAAM,QAAQ,CAAC,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,aAAa,CAAC,CAAC;gBACtE,IAAI,QAAQ,EAAE,CAAC;oBACb,OAAO,IAAI,CAAC,gBAAgB,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;gBACpD,CAAC;YACH,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,OAAO,CAAC,KAAK,CACX,uBAAuB,QAAQ,CAAC,IAAI,+CAA+C,EACnF,KAAK,CACN,CAAC;YACJ,CAAC;QACH,CAAC;QAED,+DAA+D;QAC/D,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,gBAAgB,CAAC,KAAK,CAC3C,OAAO,EACP,MAAM,EACN,aAAa,CACd,CAAC;YAEF,OAAO,IAAI,CAAC,gBAAgB,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;QACpD,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,KAAK,CACX,gDAAgD,gBAAgB,CAAC,IAAI,0CAA0C,EAC/G,KAAK,CACN,CAAC;YACF,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IAED;;OAEG;IACK,gBAAgB,CACtB,QAAyB,EACzB,SAAiB;QAEjB,MAAM,OAAO,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;QAClC,MAAM,YAAY,GAAG,OAAO,GAAG,SAAS,CAAC;QAEzC,gFAAgF;QAChF,MAAM,eAAe,GAAG,GAAG,IAAI,CAAC,IAAI,IAAI,QAAQ,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC;QAEnE,OAAO;YACL,GAAG,QAAQ;YACX,QAAQ,EAAE;gBACR,GAAG,QAAQ,CAAC,QAAQ;gBACpB,MAAM,EAAE,eAAe;gBACvB,SAAS,EAAE,QAAQ,CAAC,QAAQ,CAAC,SAAS,IAAI,YAAY;aACvD;SACF,CAAC;IACJ,CAAC;CACF"}

package/dist/src/routing/strategies/compositeStrategy.test.d.ts

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

package/dist/src/routing/strategies/compositeStrategy.test.js

@@ -0,0 +1,123 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { CompositeStrategy } from './compositeStrategy.js';
+describe('CompositeStrategy', () => {
+    let mockContext;
+    let mockConfig;
+    let mockBaseLlmClient;
+    let mockStrategy1;
+    let mockStrategy2;
+    let mockTerminalStrategy;
+    beforeEach(() => {
+        vi.clearAllMocks();
+        mockContext = {};
+        mockConfig = {};
+        mockBaseLlmClient = {};
+        mockStrategy1 = {
+            name: 'strategy1',
+            route: vi.fn().mockResolvedValue(null),
+        };
+        mockStrategy2 = {
+            name: 'strategy2',
+            route: vi.fn().mockResolvedValue(null),
+        };
+        mockTerminalStrategy = {
+            name: 'terminal',
+            route: vi.fn().mockResolvedValue({
+                model: 'terminal-model',
+                metadata: {
+                    source: 'terminal',
+                    latencyMs: 10,
+                    reasoning: 'Terminal decision',
+                },
+            }),
+        };
+    });
+    it('should try strategies in order and return the first successful decision', async () => {
+        const decision = {
+            model: 'strategy2-model',
+            metadata: {
+                source: 'strategy2',
+                latencyMs: 20,
+                reasoning: 'Strategy 2 decided',
+            },
+        };
+        vi.spyOn(mockStrategy2, 'route').mockResolvedValue(decision);
+        const composite = new CompositeStrategy([mockStrategy1, mockStrategy2, mockTerminalStrategy], 'test-router');
+        const result = await composite.route(mockContext, mockConfig, mockBaseLlmClient);
+        expect(mockStrategy1.route).toHaveBeenCalledWith(mockContext, mockConfig, mockBaseLlmClient);
+        expect(mockStrategy2.route).toHaveBeenCalledWith(mockContext, mockConfig, mockBaseLlmClient);
+        expect(mockTerminalStrategy.route).not.toHaveBeenCalled();
+        expect(result.model).toBe('strategy2-model');
+        expect(result.metadata.source).toBe('test-router/strategy2');
+    });
+    it('should fall back to the terminal strategy if no other strategy provides a decision', async () => {
+        const composite = new CompositeStrategy([mockStrategy1, mockStrategy2, mockTerminalStrategy], 'test-router');
+        const result = await composite.route(mockContext, mockConfig, mockBaseLlmClient);
+        expect(mockStrategy1.route).toHaveBeenCalledTimes(1);
+        expect(mockStrategy2.route).toHaveBeenCalledTimes(1);
+        expect(mockTerminalStrategy.route).toHaveBeenCalledTimes(1);
+        expect(result.model).toBe('terminal-model');
+        expect(result.metadata.source).toBe('test-router/terminal');
+    });
+    it('should handle errors in non-terminal strategies and continue', async () => {
+        const consoleErrorSpy = vi
+            .spyOn(console, 'error')
+            .mockImplementation(() => { });
+        vi.spyOn(mockStrategy1, 'route').mockRejectedValue(new Error('Strategy 1 failed'));
+        const composite = new CompositeStrategy([mockStrategy1, mockTerminalStrategy], 'test-router');
+        const result = await composite.route(mockContext, mockConfig, mockBaseLlmClient);
+        expect(consoleErrorSpy).toHaveBeenCalledWith("[Routing] Strategy 'strategy1' failed. Continuing to next strategy. Error:", expect.any(Error));
+        expect(result.model).toBe('terminal-model');
+        consoleErrorSpy.mockRestore();
+    });
+    it('should re-throw an error from the terminal strategy', async () => {
+        const consoleErrorSpy = vi
+            .spyOn(console, 'error')
+            .mockImplementation(() => { });
+        const terminalError = new Error('Terminal strategy failed');
+        vi.spyOn(mockTerminalStrategy, 'route').mockRejectedValue(terminalError);
+        const composite = new CompositeStrategy([mockTerminalStrategy]);
+        await expect(composite.route(mockContext, mockConfig, mockBaseLlmClient)).rejects.toThrow(terminalError);
+        expect(consoleErrorSpy).toHaveBeenCalledWith("[Routing] Critical Error: Terminal strategy 'terminal' failed. Routing cannot proceed. Error:", terminalError);
+        consoleErrorSpy.mockRestore();
+    });
+    it('should correctly finalize the decision metadata', async () => {
+        const decision = {
+            model: 'some-model',
+            metadata: {
+                source: 'child-source',
+                latencyMs: 50,
+                reasoning: 'Child reasoning',
+            },
+        };
+        vi.spyOn(mockStrategy1, 'route').mockResolvedValue(decision);
+        const composite = new CompositeStrategy([mockStrategy1, mockTerminalStrategy], 'my-composite');
+        const result = await composite.route(mockContext, mockConfig, mockBaseLlmClient);
+        expect(result.model).toBe('some-model');
+        expect(result.metadata.source).toBe('my-composite/child-source');
+        expect(result.metadata.reasoning).toBe('Child reasoning');
+        // It should keep the child's latency
+        expect(result.metadata.latencyMs).toBe(50);
+    });
+    it('should calculate total latency if child latency is not provided', async () => {
+        const decision = {
+            model: 'some-model',
+            metadata: {
+                source: 'child-source',
+                // No latencyMs here
+                latencyMs: 0,
+                reasoning: 'Child reasoning',
+            },
+        };
+        vi.spyOn(mockStrategy1, 'route').mockResolvedValue(decision);
+        const composite = new CompositeStrategy([mockStrategy1, mockTerminalStrategy], 'my-composite');
+        const result = await composite.route(mockContext, mockConfig, mockBaseLlmClient);
+        expect(result.metadata.latencyMs).toBeGreaterThanOrEqual(0);
+    });
+});
+//# sourceMappingURL=compositeStrategy.test.js.map