@anthropic-field/core 0.1.0

package/dist/src/availability/modelAvailabilityService.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export type ModelId = string;
+type TerminalUnavailabilityReason = 'quota' | 'capacity';
+export type TurnUnavailabilityReason = 'retry_once_per_turn';
+export type UnavailabilityReason = TerminalUnavailabilityReason | TurnUnavailabilityReason | 'unknown';
+export type ModelHealthStatus = 'terminal' | 'sticky_retry';
+export interface ModelAvailabilitySnapshot {
+    available: boolean;
+    reason?: UnavailabilityReason;
+}
+export interface ModelSelectionResult {
+    selectedModel: ModelId | null;
+    attempts?: number;
+    skipped: Array<{
+        model: ModelId;
+        reason: UnavailabilityReason;
+    }>;
+}
+export declare class ModelAvailabilityService {
+    private readonly health;
+    markTerminal(model: ModelId, reason: TerminalUnavailabilityReason): void;
+    markHealthy(model: ModelId): void;
+    markRetryOncePerTurn(model: ModelId): void;
+    consumeStickyAttempt(model: ModelId): void;
+    snapshot(model: ModelId): ModelAvailabilitySnapshot;
+    selectFirstAvailable(models: ModelId[]): ModelSelectionResult;
+    resetTurn(): void;
+    reset(): void;
+    private setState;
+    private clearState;
+}
+export {};

package/dist/src/availability/modelAvailabilityService.js

@@ -0,0 +1,87 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export class ModelAvailabilityService {
+    health = new Map();
+    markTerminal(model, reason) {
+        this.setState(model, {
+            status: 'terminal',
+            reason,
+        });
+    }
+    markHealthy(model) {
+        this.clearState(model);
+    }
+    markRetryOncePerTurn(model) {
+        const currentState = this.health.get(model);
+        // Do not override a terminal failure with a transient one.
+        if (currentState?.status === 'terminal') {
+            return;
+        }
+        // Only reset consumption if we are not already in the sticky_retry state.
+        // This prevents infinite loops if the model fails repeatedly in the same turn.
+        let consumed = false;
+        if (currentState?.status === 'sticky_retry') {
+            consumed = currentState.consumed;
+        }
+        this.setState(model, {
+            status: 'sticky_retry',
+            reason: 'retry_once_per_turn',
+            consumed,
+        });
+    }
+    consumeStickyAttempt(model) {
+        const state = this.health.get(model);
+        if (state?.status === 'sticky_retry') {
+            this.setState(model, { ...state, consumed: true });
+        }
+    }
+    snapshot(model) {
+        const state = this.health.get(model);
+        if (!state) {
+            return { available: true };
+        }
+        if (state.status === 'terminal') {
+            return { available: false, reason: state.reason };
+        }
+        if (state.status === 'sticky_retry' && state.consumed) {
+            return { available: false, reason: state.reason };
+        }
+        return { available: true };
+    }
+    selectFirstAvailable(models) {
+        const skipped = [];
+        for (const model of models) {
+            const snapshot = this.snapshot(model);
+            if (snapshot.available) {
+                const state = this.health.get(model);
+                // A sticky model is being attempted, so note that.
+                const attempts = state?.status === 'sticky_retry' ? 1 : undefined;
+                return { selectedModel: model, skipped, attempts };
+            }
+            else {
+                skipped.push({ model, reason: snapshot.reason ?? 'unknown' });
+            }
+        }
+        return { selectedModel: null, skipped };
+    }
+    resetTurn() {
+        for (const [model, state] of this.health.entries()) {
+            if (state.status === 'sticky_retry') {
+                this.setState(model, { ...state, consumed: false });
+            }
+        }
+    }
+    reset() {
+        this.health.clear();
+    }
+    setState(model, nextState) {
+        this.health.set(model, nextState);
+    }
+    clearState(model) {
+        this.health.delete(model);
+    }
+}
+//# sourceMappingURL=modelAvailabilityService.js.map

package/dist/src/availability/modelAvailabilityService.js.map

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

package/dist/src/availability/modelPolicy.d.ts

@@ -0,0 +1,49 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { ModelAvailabilityService, ModelHealthStatus, ModelId } from './modelAvailabilityService.js';
+/**
+ * Whether to prompt the user or fallback silently on a model API failure.
+ */
+export type FallbackAction = 'silent' | 'prompt';
+/**
+ * Type of possible errors from model API failures.
+ */
+export type FailureKind = 'terminal' | 'transient' | 'not_found' | 'unknown';
+/**
+ * Map from model API failure reason to user interaction.
+ */
+export type ModelPolicyActionMap = Partial<Record<FailureKind, FallbackAction>>;
+/**
+ * What state (e.g. Terminal, Sticky Retry) to set a model after failed API call.
+ */
+export type ModelPolicyStateMap = Partial<Record<FailureKind, ModelHealthStatus>>;
+/**
+ * Defines the policy for a single model in the availability chain.
+ *
+ * This includes:
+ * - Which model this policy applies to.
+ * - What actions to take (prompt vs silent fallback) for different failure kinds.
+ * - How the model's health status should transition upon failure.
+ * - Whether this model is considered a "last resort" (i.e. use if all models are unavailable).
+ */
+export interface ModelPolicy {
+    model: ModelId;
+    actions: ModelPolicyActionMap;
+    stateTransitions: ModelPolicyStateMap;
+    isLastResort?: boolean;
+}
+/**
+ * A chain of model policies defining the priority and fallback behavior.
+ * The first model in the chain is the primary model.
+ */
+export type ModelPolicyChain = ModelPolicy[];
+/**
+ * Context required by retry logic to apply availability policies on failure.
+ */
+export interface RetryAvailabilityContext {
+    service: ModelAvailabilityService;
+    policy: ModelPolicy;
+}

package/dist/src/availability/modelPolicy.js

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

package/dist/src/availability/modelPolicy.js.map

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

package/dist/src/availability/policyCatalog.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { ModelPolicy, ModelPolicyChain } from './modelPolicy.js';
+import type { UserTierId } from '../code_assist/types.js';
+export interface ModelPolicyOptions {
+    previewEnabled: boolean;
+    userTier?: UserTierId;
+}
+/**
+ * Returns the default ordered model policy chain for the user.
+ */
+export declare function getModelPolicyChain(options: ModelPolicyOptions): ModelPolicyChain;
+export declare function createSingleModelChain(model: string): ModelPolicyChain;
+export declare function getFlashLitePolicyChain(): ModelPolicyChain;
+/**
+ * Provides a default policy scaffold for models not present in the catalog.
+ */
+export declare function createDefaultPolicy(model: string, options?: {
+    isLastResort?: boolean;
+}): ModelPolicy;
+export declare function validateModelPolicyChain(chain: ModelPolicyChain): void;

package/dist/src/availability/policyCatalog.js

@@ -0,0 +1,106 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { DEFAULT_GEMINI_FLASH_LITE_MODEL, DEFAULT_GEMINI_FLASH_MODEL, DEFAULT_GEMINI_MODEL, PREVIEW_GEMINI_FLASH_MODEL, PREVIEW_GEMINI_MODEL, } from '../config/models.js';
+const DEFAULT_ACTIONS = {
+    terminal: 'prompt',
+    transient: 'prompt',
+    not_found: 'prompt',
+    unknown: 'prompt',
+};
+const SILENT_ACTIONS = {
+    terminal: 'silent',
+    transient: 'silent',
+    not_found: 'silent',
+    unknown: 'silent',
+};
+const DEFAULT_STATE = {
+    terminal: 'terminal',
+    transient: 'terminal',
+    not_found: 'terminal',
+    unknown: 'terminal',
+};
+const DEFAULT_CHAIN = [
+    definePolicy({ model: DEFAULT_GEMINI_MODEL }),
+    definePolicy({ model: DEFAULT_GEMINI_FLASH_MODEL, isLastResort: true }),
+];
+const PREVIEW_CHAIN = [
+    definePolicy({ model: PREVIEW_GEMINI_MODEL }),
+    definePolicy({ model: PREVIEW_GEMINI_FLASH_MODEL, isLastResort: true }),
+];
+const FLASH_LITE_CHAIN = [
+    definePolicy({
+        model: DEFAULT_GEMINI_FLASH_LITE_MODEL,
+        actions: SILENT_ACTIONS,
+    }),
+    definePolicy({
+        model: DEFAULT_GEMINI_FLASH_MODEL,
+        actions: SILENT_ACTIONS,
+    }),
+    definePolicy({
+        model: DEFAULT_GEMINI_MODEL,
+        isLastResort: true,
+        actions: SILENT_ACTIONS,
+    }),
+];
+/**
+ * Returns the default ordered model policy chain for the user.
+ */
+export function getModelPolicyChain(options) {
+    if (options.previewEnabled) {
+        return cloneChain(PREVIEW_CHAIN);
+    }
+    return cloneChain(DEFAULT_CHAIN);
+}
+export function createSingleModelChain(model) {
+    return [definePolicy({ model, isLastResort: true })];
+}
+export function getFlashLitePolicyChain() {
+    return cloneChain(FLASH_LITE_CHAIN);
+}
+/**
+ * Provides a default policy scaffold for models not present in the catalog.
+ */
+export function createDefaultPolicy(model, options) {
+    return definePolicy({ model, isLastResort: options?.isLastResort });
+}
+export function validateModelPolicyChain(chain) {
+    if (chain.length === 0) {
+        throw new Error('Model policy chain must include at least one model.');
+    }
+    const lastResortCount = chain.filter((policy) => policy.isLastResort).length;
+    if (lastResortCount === 0) {
+        throw new Error('Model policy chain must include an `isLastResort` model.');
+    }
+    if (lastResortCount > 1) {
+        throw new Error('Model policy chain must only have one `isLastResort`.');
+    }
+}
+/**
+ * Helper to define a ModelPolicy with default actions and state transitions.
+ * Ensures every policy is a fresh instance to avoid shared state.
+ */
+function definePolicy(config) {
+    return {
+        model: config.model,
+        isLastResort: config.isLastResort,
+        actions: { ...DEFAULT_ACTIONS, ...(config.actions ?? {}) },
+        stateTransitions: {
+            ...DEFAULT_STATE,
+            ...(config.stateTransitions ?? {}),
+        },
+    };
+}
+function clonePolicy(policy) {
+    return {
+        ...policy,
+        actions: { ...policy.actions },
+        stateTransitions: { ...policy.stateTransitions },
+    };
+}
+function cloneChain(chain) {
+    return chain.map(clonePolicy);
+}
+//# sourceMappingURL=policyCatalog.js.map

package/dist/src/availability/policyCatalog.js.map

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

package/dist/src/availability/policyHelpers.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { GenerateContentConfig } from '@google/genai';
+import type { Config } from '../config/config.js';
+import type { FailureKind, FallbackAction, ModelPolicy, ModelPolicyChain, RetryAvailabilityContext } from './modelPolicy.js';
+import type { ModelSelectionResult } from './modelAvailabilityService.js';
+import type { ModelConfigKey } from '../services/modelConfigService.js';
+/**
+ * Resolves the active policy chain for the given config, ensuring the
+ * user-selected active model is represented.
+ */
+export declare function resolvePolicyChain(config: Config, preferredModel?: string, wrapsAround?: boolean): ModelPolicyChain;
+/**
+ * Produces the failed policy (if it exists in the chain) and the list of
+ * fallback candidates that follow it.
+ * @param chain - The ordered list of available model policies.
+ * @param failedModel - The identifier of the model that failed.
+ * @param wrapsAround - If true, treats the chain as a circular buffer.
+ */
+export declare function buildFallbackPolicyContext(chain: ModelPolicyChain, failedModel: string, wrapsAround?: boolean): {
+    failedPolicy?: ModelPolicy;
+    candidates: ModelPolicy[];
+};
+export declare function resolvePolicyAction(failureKind: FailureKind, policy: ModelPolicy): FallbackAction;
+/**
+ * Creates a context provider for retry logic that returns the availability
+ * sevice and resolves the current model's policy.
+ *
+ * @param modelGetter A function that returns the model ID currently being attempted.
+ *        (Allows handling dynamic model changes during retries).
+ */
+export declare function createAvailabilityContextProvider(config: Config, modelGetter: () => string): () => RetryAvailabilityContext | undefined;
+/**
+ * Selects the model to use for an attempt via the availability service and
+ * returns the selection context.
+ */
+export declare function selectModelForAvailability(config: Config, requestedModel: string): ModelSelectionResult;
+/**
+ * Applies the model availability selection logic, including side effects
+ * (setting active model, consuming sticky attempts) and config updates.
+ */
+export declare function applyModelSelection(config: Config, modelConfigKey: ModelConfigKey, options?: {
+    consumeAttempt?: boolean;
+}): {
+    model: string;
+    config: GenerateContentConfig;
+    maxAttempts?: number;
+};
+export declare function applyAvailabilityTransition(getContext: (() => RetryAvailabilityContext | undefined) | undefined, failureKind: FailureKind): void;

package/dist/src/availability/policyHelpers.js

@@ -0,0 +1,143 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { createDefaultPolicy, createSingleModelChain, getModelPolicyChain, getFlashLitePolicyChain, } from './policyCatalog.js';
+import { DEFAULT_GEMINI_FLASH_LITE_MODEL, DEFAULT_GEMINI_MODEL, PREVIEW_GEMINI_MODEL_AUTO, isAutoModel, resolveModel, } from '../config/models.js';
+/**
+ * Resolves the active policy chain for the given config, ensuring the
+ * user-selected active model is represented.
+ */
+export function resolvePolicyChain(config, preferredModel, wrapsAround = false) {
+    const modelFromConfig = preferredModel ?? config.getActiveModel?.() ?? config.getModel();
+    const configuredModel = config.getModel();
+    let chain;
+    const resolvedModel = resolveModel(modelFromConfig);
+    const isAutoPreferred = preferredModel ? isAutoModel(preferredModel) : false;
+    const isAutoConfigured = isAutoModel(configuredModel);
+    if (resolvedModel === DEFAULT_GEMINI_FLASH_LITE_MODEL) {
+        chain = getFlashLitePolicyChain();
+    }
+    else if (isAutoPreferred || isAutoConfigured) {
+        const previewEnabled = preferredModel === PREVIEW_GEMINI_MODEL_AUTO ||
+            configuredModel === PREVIEW_GEMINI_MODEL_AUTO;
+        chain = getModelPolicyChain({
+            previewEnabled,
+            userTier: config.getUserTier(),
+        });
+    }
+    else {
+        chain = createSingleModelChain(modelFromConfig);
+    }
+    const activeIndex = chain.findIndex((policy) => policy.model === resolvedModel);
+    if (activeIndex !== -1) {
+        return wrapsAround
+            ? [...chain.slice(activeIndex), ...chain.slice(0, activeIndex)]
+            : [...chain.slice(activeIndex)];
+    }
+    // If the user specified a model not in the default chain, we assume they want
+    // *only* that model. We do not fallback to the default chain.
+    return [createDefaultPolicy(resolvedModel, { isLastResort: true })];
+}
+/**
+ * Produces the failed policy (if it exists in the chain) and the list of
+ * fallback candidates that follow it.
+ * @param chain - The ordered list of available model policies.
+ * @param failedModel - The identifier of the model that failed.
+ * @param wrapsAround - If true, treats the chain as a circular buffer.
+ */
+export function buildFallbackPolicyContext(chain, failedModel, wrapsAround = false) {
+    const index = chain.findIndex((policy) => policy.model === failedModel);
+    if (index === -1) {
+        return { failedPolicy: undefined, candidates: chain };
+    }
+    // Return [candidates_after, candidates_before] to prioritize downgrades
+    // (continuing the chain) before wrapping around to upgrades.
+    const candidates = wrapsAround
+        ? [...chain.slice(index + 1), ...chain.slice(0, index)]
+        : [...chain.slice(index + 1)];
+    return {
+        failedPolicy: chain[index],
+        candidates,
+    };
+}
+export function resolvePolicyAction(failureKind, policy) {
+    return policy.actions?.[failureKind] ?? 'prompt';
+}
+/**
+ * Creates a context provider for retry logic that returns the availability
+ * sevice and resolves the current model's policy.
+ *
+ * @param modelGetter A function that returns the model ID currently being attempted.
+ *        (Allows handling dynamic model changes during retries).
+ */
+export function createAvailabilityContextProvider(config, modelGetter) {
+    return () => {
+        const service = config.getModelAvailabilityService();
+        const currentModel = modelGetter();
+        // Resolve the chain for the specific model we are attempting.
+        const chain = resolvePolicyChain(config, currentModel);
+        const policy = chain.find((p) => p.model === currentModel);
+        return policy ? { service, policy } : undefined;
+    };
+}
+/**
+ * Selects the model to use for an attempt via the availability service and
+ * returns the selection context.
+ */
+export function selectModelForAvailability(config, requestedModel) {
+    const chain = resolvePolicyChain(config, requestedModel);
+    const selection = config
+        .getModelAvailabilityService()
+        .selectFirstAvailable(chain.map((p) => p.model));
+    if (selection.selectedModel)
+        return selection;
+    const backupModel = chain.find((p) => p.isLastResort)?.model ?? DEFAULT_GEMINI_MODEL;
+    return { selectedModel: backupModel, skipped: [] };
+}
+/**
+ * Applies the model availability selection logic, including side effects
+ * (setting active model, consuming sticky attempts) and config updates.
+ */
+export function applyModelSelection(config, modelConfigKey, options = {}) {
+    const resolved = config.modelConfigService.getResolvedConfig(modelConfigKey);
+    const model = resolved.model;
+    const selection = selectModelForAvailability(config, model);
+    if (!selection) {
+        return { model, config: resolved.generateContentConfig };
+    }
+    const finalModel = selection.selectedModel ?? model;
+    let generateContentConfig = resolved.generateContentConfig;
+    if (finalModel !== model) {
+        const fallbackResolved = config.modelConfigService.getResolvedConfig({
+            ...modelConfigKey,
+            model: finalModel,
+        });
+        generateContentConfig = fallbackResolved.generateContentConfig;
+    }
+    config.setActiveModel(finalModel);
+    if (selection.attempts && options.consumeAttempt !== false) {
+        config.getModelAvailabilityService().consumeStickyAttempt(finalModel);
+    }
+    return {
+        model: finalModel,
+        config: generateContentConfig,
+        maxAttempts: selection.attempts,
+    };
+}
+export function applyAvailabilityTransition(getContext, failureKind) {
+    const context = getContext?.();
+    if (!context)
+        return;
+    const transition = context.policy.stateTransitions?.[failureKind];
+    if (!transition)
+        return;
+    if (transition === 'terminal') {
+        context.service.markTerminal(context.policy.model, failureKind === 'terminal' ? 'quota' : 'capacity');
+    }
+    else if (transition === 'sticky_retry') {
+        context.service.markRetryOncePerTurn(context.policy.model);
+    }
+}
+//# sourceMappingURL=policyHelpers.js.map

package/dist/src/availability/policyHelpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"policyHelpers.js","sourceRoot":"","sources":["../../../src/availability/policyHelpers.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAWH,OAAO,EACL,mBAAmB,EACnB,sBAAsB,EACtB,mBAAmB,EACnB,uBAAuB,GACxB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,+BAA+B,EAC/B,oBAAoB,EACpB,yBAAyB,EACzB,WAAW,EACX,YAAY,GACb,MAAM,qBAAqB,CAAC;AAI7B;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAChC,MAAc,EACd,cAAuB,EACvB,cAAuB,KAAK;IAE5B,MAAM,eAAe,GACnB,cAAc,IAAI,MAAM,CAAC,cAAc,EAAE,EAAE,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;IACnE,MAAM,eAAe,GAAG,MAAM,CAAC,QAAQ,EAAE,CAAC;IAE1C,IAAI,KAAK,CAAC;IACV,MAAM,aAAa,GAAG,YAAY,CAAC,eAAe,CAAC,CAAC;IACpD,MAAM,eAAe,GAAG,cAAc,CAAC,CAAC,CAAC,WAAW,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;IAC7E,MAAM,gBAAgB,GAAG,WAAW,CAAC,eAAe,CAAC,CAAC;IAEtD,IAAI,aAAa,KAAK,+BAA+B,EAAE,CAAC;QACtD,KAAK,GAAG,uBAAuB,EAAE,CAAC;IACpC,CAAC;SAAM,IAAI,eAAe,IAAI,gBAAgB,EAAE,CAAC;QAC/C,MAAM,cAAc,GAClB,cAAc,KAAK,yBAAyB;YAC5C,eAAe,KAAK,yBAAyB,CAAC;QAChD,KAAK,GAAG,mBAAmB,CAAC;YAC1B,cAAc;YACd,QAAQ,EAAE,MAAM,CAAC,WAAW,EAAE;SAC/B,CAAC,CAAC;IACL,CAAC;SAAM,CAAC;QACN,KAAK,GAAG,sBAAsB,CAAC,eAAe,CAAC,CAAC;IAClD,CAAC;IAED,MAAM,WAAW,GAAG,KAAK,CAAC,SAAS,CACjC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,KAAK,aAAa,CAC3C,CAAC;IACF,IAAI,WAAW,KAAK,CAAC,CAAC,EAAE,CAAC;QACvB,OAAO,WAAW;YAChB,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,WAAW,CAAC,EAAE,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC;YAC/D,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC;IACpC,CAAC;IAED,8EAA8E;IAC9E,8DAA8D;IAC9D,OAAO,CAAC,mBAAmB,CAAC,aAAa,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;AACtE,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,0BAA0B,CACxC,KAAuB,EACvB,WAAmB,EACnB,cAAuB,KAAK;IAK5B,MAAM,KAAK,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,KAAK,WAAW,CAAC,CAAC;IACxE,IAAI,KAAK,KAAK,CAAC,CAAC,EAAE,CAAC;QACjB,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC;IACxD,CAAC;IACD,wEAAwE;IACxE,6DAA6D;IAC7D,MAAM,UAAU,GAAG,WAAW;QAC5B,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,EAAE,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;QACvD,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC;IAChC,OAAO;QACL,YAAY,EAAE,KAAK,CAAC,KAAK,CAAC;QAC1B,UAAU;KACX,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,mBAAmB,CACjC,WAAwB,EACxB,MAAmB;IAEnB,OAAO,MAAM,CAAC,OAAO,EAAE,CAAC,WAAW,CAAC,IAAI,QAAQ,CAAC;AACnD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,iCAAiC,CAC/C,MAAc,EACd,WAAyB;IAEzB,OAAO,GAAG,EAAE;QACV,MAAM,OAAO,GAAG,MAAM,CAAC,2BAA2B,EAAE,CAAC;QACrD,MAAM,YAAY,GAAG,WAAW,EAAE,CAAC;QAEnC,8DAA8D;QAC9D,MAAM,KAAK,GAAG,kBAAkB,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;QACvD,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,YAAY,CAAC,CAAC;QAE3D,OAAO,MAAM,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;IAClD,CAAC,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,0BAA0B,CACxC,MAAc,EACd,cAAsB;IAEtB,MAAM,KAAK,GAAG,kBAAkB,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IACzD,MAAM,SAAS,GAAG,MAAM;SACrB,2BAA2B,EAAE;SAC7B,oBAAoB,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;IAEnD,IAAI,SAAS,CAAC,aAAa;QAAE,OAAO,SAAS,CAAC;IAE9C,MAAM,WAAW,GACf,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,YAAY,CAAC,EAAE,KAAK,IAAI,oBAAoB,CAAC;IAEnE,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;AACrD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CACjC,MAAc,EACd,cAA8B,EAC9B,UAAwC,EAAE;IAE1C,MAAM,QAAQ,GAAG,MAAM,CAAC,kBAAkB,CAAC,iBAAiB,CAAC,cAAc,CAAC,CAAC;IAC7E,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC;IAC7B,MAAM,SAAS,GAAG,0BAA0B,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAE5D,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,qBAAqB,EAAE,CAAC;IAC3D,CAAC;IAED,MAAM,UAAU,GAAG,SAAS,CAAC,aAAa,IAAI,KAAK,CAAC;IACpD,IAAI,qBAAqB,GAAG,QAAQ,CAAC,qBAAqB,CAAC;IAE3D,IAAI,UAAU,KAAK,KAAK,EAAE,CAAC;QACzB,MAAM,gBAAgB,GAAG,MAAM,CAAC,kBAAkB,CAAC,iBAAiB,CAAC;YACnE,GAAG,cAAc;YACjB,KAAK,EAAE,UAAU;SAClB,CAAC,CAAC;QACH,qBAAqB,GAAG,gBAAgB,CAAC,qBAAqB,CAAC;IACjE,CAAC;IAED,MAAM,CAAC,cAAc,CAAC,UAAU,CAAC,CAAC;IAElC,IAAI,SAAS,CAAC,QAAQ,IAAI,OAAO,CAAC,cAAc,KAAK,KAAK,EAAE,CAAC;QAC3D,MAAM,CAAC,2BAA2B,EAAE,CAAC,oBAAoB,CAAC,UAAU,CAAC,CAAC;IACxE,CAAC;IAED,OAAO;QACL,KAAK,EAAE,UAAU;QACjB,MAAM,EAAE,qBAAqB;QAC7B,WAAW,EAAE,SAAS,CAAC,QAAQ;KAChC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,2BAA2B,CACzC,UAAoE,EACpE,WAAwB;IAExB,MAAM,OAAO,GAAG,UAAU,EAAE,EAAE,CAAC;IAC/B,IAAI,CAAC,OAAO;QAAE,OAAO;IAErB,MAAM,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,gBAAgB,EAAE,CAAC,WAAW,CAAC,CAAC;IAClE,IAAI,CAAC,UAAU;QAAE,OAAO;IAExB,IAAI,UAAU,KAAK,UAAU,EAAE,CAAC;QAC9B,OAAO,CAAC,OAAO,CAAC,YAAY,CAC1B,OAAO,CAAC,MAAM,CAAC,KAAK,EACpB,WAAW,KAAK,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,UAAU,CAClD,CAAC;IACJ,CAAC;SAAM,IAAI,UAAU,KAAK,cAAc,EAAE,CAAC;QACzC,OAAO,CAAC,OAAO,CAAC,oBAAoB,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC7D,CAAC;AACH,CAAC"}

package/dist/src/availability/testUtils.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { ModelAvailabilityService, ModelSelectionResult } from './modelAvailabilityService.js';
+/**
+ * Test helper to create a fully mocked ModelAvailabilityService.
+ */
+export declare function createAvailabilityServiceMock(selection?: ModelSelectionResult): ModelAvailabilityService;

package/dist/src/availability/testUtils.js

@@ -0,0 +1,22 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { vi } from 'vitest';
+/**
+ * Test helper to create a fully mocked ModelAvailabilityService.
+ */
+export function createAvailabilityServiceMock(selection = { selectedModel: null, skipped: [] }) {
+    const service = {
+        markTerminal: vi.fn(),
+        markHealthy: vi.fn(),
+        markRetryOncePerTurn: vi.fn(),
+        consumeStickyAttempt: vi.fn(),
+        snapshot: vi.fn(),
+        resetTurn: vi.fn(),
+        selectFirstAvailable: vi.fn().mockReturnValue(selection),
+    };
+    return service;
+}
+//# sourceMappingURL=testUtils.js.map

package/dist/src/availability/testUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"testUtils.js","sourceRoot":"","sources":["../../../src/availability/testUtils.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAM5B;;GAEG;AACH,MAAM,UAAU,6BAA6B,CAC3C,YAAkC,EAAE,aAAa,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE;IAEtE,MAAM,OAAO,GAAG;QACd,YAAY,EAAE,EAAE,CAAC,EAAE,EAAE;QACrB,WAAW,EAAE,EAAE,CAAC,EAAE,EAAE;QACpB,oBAAoB,EAAE,EAAE,CAAC,EAAE,EAAE;QAC7B,oBAAoB,EAAE,EAAE,CAAC,EAAE,EAAE;QAC7B,QAAQ,EAAE,EAAE,CAAC,EAAE,EAAE;QACjB,SAAS,EAAE,EAAE,CAAC,EAAE,EAAE;QAClB,oBAAoB,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,eAAe,CAAC,SAAS,CAAC;KACzD,CAAC;IAEF,OAAO,OAA8C,CAAC;AACxD,CAAC"}

package/dist/src/code_assist/admin/admin_controls.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { CodeAssistServer } from '../server.js';
+import { type FetchAdminControlsResponse } from '../types.js';
+import type { Config } from '../../config/config.js';
+export declare function sanitizeAdminSettings(settings: FetchAdminControlsResponse): FetchAdminControlsResponse;
+/**
+ * Fetches the admin controls from the server if enabled by experiment flag.
+ * Safely handles polling start/stop based on the flag and server availability.
+ *
+ * @param server The CodeAssistServer instance.
+ * @param cachedSettings The cached settings to use if available.
+ * @param adminControlsEnabled Whether admin controls are enabled.
+ * @param onSettingsChanged Callback to invoke when settings change during polling.
+ * @returns The fetched settings if enabled and successful, otherwise undefined.
+ */
+export declare function fetchAdminControls(server: CodeAssistServer | undefined, cachedSettings: FetchAdminControlsResponse | undefined, adminControlsEnabled: boolean, onSettingsChanged: (settings: FetchAdminControlsResponse) => void): Promise<FetchAdminControlsResponse>;
+/**
+ * Stops polling for admin controls.
+ */
+export declare function stopAdminControlsPolling(): void;
+/**
+ * Returns a standardized error message for features disabled by admin settings.
+ *
+ * @param featureName The name of the disabled feature
+ * @param config The application config
+ * @returns The formatted error message
+ */
+export declare function getAdminErrorMessage(featureName: string, config: Config | undefined): string;