@substrate-ai/core 0.19.54

package/dist/routing/model-routing-config.js

@@ -0,0 +1,110 @@
+/**
+ * ModelRoutingConfig — Zod schema, types, error, and loader for substrate.routing.yml.
+ *
+ * The routing config YAML controls which model is used for each pipeline phase
+ * (explore / generate / review) and supports per-task-type overrides.
+ *
+ * References:
+ *  - Epic 28, Story 28-4: Model Routing Configuration Schema
+ */
+import { readFileSync } from 'node:fs';
+import { load as yamlLoad } from 'js-yaml';
+import { z } from 'zod';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const MODEL_NAME_PATTERN = /^[a-zA-Z0-9._-]+$/;
+// ---------------------------------------------------------------------------
+// Zod Schemas
+// ---------------------------------------------------------------------------
+/**
+ * Per-phase model configuration.
+ */
+export const ModelPhaseConfigSchema = z.object({
+    model: z.string().regex(MODEL_NAME_PATTERN, 'Model name contains invalid characters (must match /^[a-zA-Z0-9._-]+$/)'),
+    max_tokens: z.number().int().positive().optional(),
+});
+/**
+ * Complete model routing configuration document.
+ *
+ * All three phase keys (explore, generate, review) are optional — an absent
+ * phase causes resolveModel() to return null, signalling callers to use their
+ * own default model.
+ */
+export const ModelRoutingConfigSchema = z.object({
+    version: z.literal(1),
+    phases: z.object({
+        explore: ModelPhaseConfigSchema.optional(),
+        generate: ModelPhaseConfigSchema.optional(),
+        review: ModelPhaseConfigSchema.optional(),
+    }),
+    baseline_model: z.string().regex(MODEL_NAME_PATTERN, 'Baseline model name contains invalid characters (must match /^[a-zA-Z0-9._-]+$/)'),
+    overrides: z.record(z.string(), ModelPhaseConfigSchema).optional(),
+    /**
+     * When true, RoutingTuner will automatically apply conservative model downgrades
+     * at the end of each pipeline run based on historical phase token data.
+     */
+    auto_tune: z.boolean().optional(),
+});
+/**
+ * Error thrown by loadModelRoutingConfig() for all failure modes.
+ *
+ * Extends plain Error (not SubstrateError) to keep core package free of monolith imports.
+ */
+export class RoutingConfigError extends Error {
+    context;
+    code;
+    constructor(message, code, context) {
+        super(message);
+        this.context = context;
+        this.name = 'RoutingConfigError';
+        this.code = code;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+// ---------------------------------------------------------------------------
+// Loader
+// ---------------------------------------------------------------------------
+/**
+ * Load and validate a model routing config YAML file.
+ *
+ * @param filePath - Absolute or relative path to substrate.routing.yml
+ * @returns Parsed and validated ModelRoutingConfig object
+ * @throws {RoutingConfigError} with code CONFIG_NOT_FOUND if the file cannot be read
+ * @throws {RoutingConfigError} with code INVALID_YAML if the file contains invalid YAML
+ * @throws {RoutingConfigError} with code SCHEMA_INVALID if validation fails
+ *
+ * @example
+ * const config = loadModelRoutingConfig('.substrate/routing.yml')
+ */
+export function loadModelRoutingConfig(filePath) {
+    // Read the file
+    let rawContent;
+    try {
+        rawContent = readFileSync(filePath, 'utf-8');
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new RoutingConfigError(`Cannot read routing config file at "${filePath}": ${message}`, 'CONFIG_NOT_FOUND', { filePath });
+    }
+    // Parse YAML
+    let rawObject;
+    try {
+        rawObject = yamlLoad(rawContent);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new RoutingConfigError(`Invalid YAML in routing config file at "${filePath}": ${message}`, 'INVALID_YAML', { filePath });
+    }
+    // Validate with Zod
+    const result = ModelRoutingConfigSchema.safeParse(rawObject);
+    if (!result.success) {
+        const issues = result.error.issues;
+        const details = issues
+            .map((e) => `  - ${e.path.join('.')}: ${e.message}`)
+            .join('\n');
+        throw new RoutingConfigError(`Routing config validation failed for "${filePath}":\n${details}`, 'SCHEMA_INVALID', { filePath });
+    }
+    return result.data;
+}
+//# sourceMappingURL=model-routing-config.js.map

package/dist/routing/model-routing-config.js.map

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

package/dist/routing/model-routing-resolver.d.ts

@@ -0,0 +1,48 @@
+/**
+ * RoutingResolver — resolves the appropriate model for each pipeline task type.
+ *
+ * Uses ModelRoutingConfig to map task types to pipeline phases and return
+ * the configured model (with optional per-task-type overrides).
+ *
+ * References:
+ *  - Epic 28, Story 28-4: Model Routing Configuration Schema
+ */
+import type { ILogger } from '../dispatch/types.js';
+import type { ModelRoutingConfig } from './model-routing-config.js';
+import type { ModelResolution } from './routing-engine.js';
+/**
+ * Resolves which model to use for each pipeline task type.
+ *
+ * Constructed with a ModelRoutingConfig and a logger. Use the static
+ * createWithFallback() factory to construct from a file path with graceful
+ * handling of missing config files.
+ */
+export declare class RoutingResolver {
+    private readonly config;
+    private readonly logger;
+    constructor(config: ModelRoutingConfig, logger: ILogger);
+    /**
+     * Resolve the model for a given task type.
+     *
+     * Resolution order:
+     *  1. config.overrides[taskType] (source: 'override')
+     *  2. config.phases[phase] via TASK_TYPE_PHASE_MAP (source: 'phase')
+     *  3. null if the phase key is absent in config.phases
+     *
+     * @returns ModelResolution if a model is configured, null if in fallback mode
+     */
+    resolveModel(taskType: string): ModelResolution | null;
+    /**
+     * Static factory that loads a routing config from a file with graceful fallback.
+     *
+     * If the config file does not exist (CONFIG_NOT_FOUND), emits a single debug
+     * log and returns a resolver in fallback mode where all resolveModel() calls
+     * return null. Other errors are rethrown.
+     *
+     * @param filePath - Path to the substrate.routing.yml file
+     * @param logger - Logger instance
+     */
+    static createWithFallback(filePath: string, logger: ILogger): RoutingResolver;
+}
+export declare const ROUTING_RESOLVER_LOGGER_NAME = "routing:model-resolver";
+//# sourceMappingURL=model-routing-resolver.d.ts.map

package/dist/routing/model-routing-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-routing-resolver.d.ts","sourceRoot":"","sources":["../../src/routing/model-routing-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAA;AAEnD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAA;AACnE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAA;AAc1D;;;;;;GAMG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoB;IAC3C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAEpB,MAAM,EAAE,kBAAkB,EAAE,MAAM,EAAE,OAAO;IAKvD;;;;;;;;;OASG;IACH,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI;IAuCtD;;;;;;;;;OASG;IACH,MAAM,CAAC,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,eAAe;CAqB9E;AAGD,eAAO,MAAM,4BAA4B,2BAA2B,CAAA"}

package/dist/routing/model-routing-resolver.js

@@ -0,0 +1,105 @@
+/**
+ * RoutingResolver — resolves the appropriate model for each pipeline task type.
+ *
+ * Uses ModelRoutingConfig to map task types to pipeline phases and return
+ * the configured model (with optional per-task-type overrides).
+ *
+ * References:
+ *  - Epic 28, Story 28-4: Model Routing Configuration Schema
+ */
+import { loadModelRoutingConfig, RoutingConfigError } from './model-routing-config.js';
+// TASK_TYPE_PHASE_MAP already defined in routing-engine.ts (story 40-6); import from there
+import { TASK_TYPE_PHASE_MAP } from './routing-engine.js';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const DEFAULT_PHASE = 'generate';
+// ---------------------------------------------------------------------------
+// RoutingResolver
+// ---------------------------------------------------------------------------
+/**
+ * Resolves which model to use for each pipeline task type.
+ *
+ * Constructed with a ModelRoutingConfig and a logger. Use the static
+ * createWithFallback() factory to construct from a file path with graceful
+ * handling of missing config files.
+ */
+export class RoutingResolver {
+    config;
+    logger;
+    constructor(config, logger) {
+        this.config = config;
+        this.logger = logger;
+    }
+    /**
+     * Resolve the model for a given task type.
+     *
+     * Resolution order:
+     *  1. config.overrides[taskType] (source: 'override')
+     *  2. config.phases[phase] via TASK_TYPE_PHASE_MAP (source: 'phase')
+     *  3. null if the phase key is absent in config.phases
+     *
+     * @returns ModelResolution if a model is configured, null if in fallback mode
+     */
+    resolveModel(taskType) {
+        // Check overrides first
+        const override = this.config.overrides?.[taskType];
+        if (override) {
+            const phase = TASK_TYPE_PHASE_MAP[taskType] ?? DEFAULT_PHASE;
+            const resolution = {
+                model: override.model,
+                phase,
+                source: 'override',
+                ...(override.max_tokens !== undefined ? { maxTokens: override.max_tokens } : {}),
+            };
+            this.logger.debug({ taskType, phase: resolution.phase, model: resolution.model, source: 'override' }, 'Resolved model');
+            return resolution;
+        }
+        // Look up phase
+        const phase = TASK_TYPE_PHASE_MAP[taskType] ?? DEFAULT_PHASE;
+        const phaseConfig = this.config.phases[phase];
+        if (!phaseConfig) {
+            return null;
+        }
+        const resolution = {
+            model: phaseConfig.model,
+            phase,
+            source: 'phase',
+            ...(phaseConfig.max_tokens !== undefined ? { maxTokens: phaseConfig.max_tokens } : {}),
+        };
+        this.logger.debug({ taskType, phase, model: resolution.model, source: 'phase' }, 'Resolved model');
+        return resolution;
+    }
+    /**
+     * Static factory that loads a routing config from a file with graceful fallback.
+     *
+     * If the config file does not exist (CONFIG_NOT_FOUND), emits a single debug
+     * log and returns a resolver in fallback mode where all resolveModel() calls
+     * return null. Other errors are rethrown.
+     *
+     * @param filePath - Path to the substrate.routing.yml file
+     * @param logger - Logger instance
+     */
+    static createWithFallback(filePath, logger) {
+        try {
+            const config = loadModelRoutingConfig(filePath);
+            return new RoutingResolver(config, logger);
+        }
+        catch (err) {
+            if (err instanceof RoutingConfigError && err.code === 'CONFIG_NOT_FOUND') {
+                logger.debug({ configPath: filePath, component: 'routing', reason: 'config not found' }, `Model routing config not found at "${filePath}"; using fallback mode (all resolveModel calls will return null)`);
+                // Construct a sentinel config with empty phases so resolveModel always returns null
+                const fallbackConfig = {
+                    version: 1,
+                    phases: {},
+                    baseline_model: '',
+                };
+                return new RoutingResolver(fallbackConfig, logger);
+            }
+            throw err;
+        }
+    }
+}
+// Export the module-level logger name for external callers
+export const ROUTING_RESOLVER_LOGGER_NAME = 'routing:model-resolver';
+//# sourceMappingURL=model-routing-resolver.js.map

package/dist/routing/model-routing-resolver.js.map

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

package/dist/routing/model-tier.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Shared model tier resolution utility.
+ *
+ * Determines whether a model string belongs to the haiku (1), sonnet (2),
+ * or opus (3) tier based on substring matching against well-known keywords.
+ *
+ * Used by both RoutingRecommender and RoutingTuner to ensure consistent
+ * tier comparisons — in particular the one-step guard in RoutingTuner.
+ */
+/**
+ * Get the model tier for a given model name string.
+ *
+ * Returns:
+ *  - 1  for haiku-tier models
+ *  - 2  for sonnet-tier models (also the default when unrecognized)
+ *  - 3  for opus-tier models
+ *
+ * Matching is case-insensitive substring search.
+ */
+export declare function getModelTier(model: string): number;
+//# sourceMappingURL=model-tier.d.ts.map

package/dist/routing/model-tier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-tier.d.ts","sourceRoot":"","sources":["../../src/routing/model-tier.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AASH;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAMlD"}

package/dist/routing/model-tier.js

@@ -0,0 +1,34 @@
+/**
+ * Shared model tier resolution utility.
+ *
+ * Determines whether a model string belongs to the haiku (1), sonnet (2),
+ * or opus (3) tier based on substring matching against well-known keywords.
+ *
+ * Used by both RoutingRecommender and RoutingTuner to ensure consistent
+ * tier comparisons — in particular the one-step guard in RoutingTuner.
+ */
+/** Ordered tier keywords: index 0 = cheapest, index N = most expensive. */
+const TIER_KEYWORDS = [
+    { keyword: 'haiku', tier: 1 },
+    { keyword: 'sonnet', tier: 2 },
+    { keyword: 'opus', tier: 3 },
+];
+/**
+ * Get the model tier for a given model name string.
+ *
+ * Returns:
+ *  - 1  for haiku-tier models
+ *  - 2  for sonnet-tier models (also the default when unrecognized)
+ *  - 3  for opus-tier models
+ *
+ * Matching is case-insensitive substring search.
+ */
+export function getModelTier(model) {
+    const lower = model.toLowerCase();
+    for (const { keyword, tier } of TIER_KEYWORDS) {
+        if (lower.includes(keyword))
+            return tier;
+    }
+    return 2; // default: sonnet tier
+}
+//# sourceMappingURL=model-tier.js.map

package/dist/routing/model-tier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-tier.js","sourceRoot":"","sources":["../../src/routing/model-tier.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,2EAA2E;AAC3E,MAAM,aAAa,GAA6C;IAC9D,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,EAAE;IAC7B,EAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,EAAE;IAC9B,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE;CAC7B,CAAA;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,YAAY,CAAC,KAAa;IACxC,MAAM,KAAK,GAAG,KAAK,CAAC,WAAW,EAAE,CAAA;IACjC,KAAK,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,aAAa,EAAE,CAAC;QAC9C,IAAI,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC;YAAE,OAAO,IAAI,CAAA;IAC1C,CAAC;IACD,OAAO,CAAC,CAAA,CAAC,uBAAuB;AAClC,CAAC"}

package/dist/routing/provider-status.d.ts

@@ -0,0 +1,99 @@
+/**
+ * ProviderStatus — in-memory rate limit and status tracking per provider.
+ *
+ * Tracks:
+ *  - Subscription routing enabled/disabled
+ *  - API billing availability
+ *  - Rate limit consumption within the current window
+ *
+ * References:
+ *  - Architecture Section 8: Rate limit tracking per provider
+ *  - FR29: Rate limit management
+ *  - ADR-004: RoutingEngine is stateless except for rate limit tracking in-memory
+ */
+/**
+ * Snapshot of a single provider's current status.
+ */
+export interface ProviderStatus {
+    /** Provider name (e.g., 'claude', 'codex', 'gemini') */
+    provider: string;
+    /** Whether subscription routing is enabled for this provider */
+    subscriptionRoutingEnabled: boolean;
+    /** Whether API billing is available for this provider */
+    apiBillingEnabled: boolean;
+    /** Tokens consumed in the current rate limit window */
+    tokensUsedInWindow: number;
+    /** Millisecond timestamp when the current window resets (0 if no rate limit configured) */
+    windowResetAtMs: number;
+    /** Rate limit configuration */
+    rateLimit: {
+        tokensPerWindow: number;
+        windowSeconds: number;
+    };
+}
+/**
+ * Manages in-memory rate limit state and provider availability for all providers.
+ *
+ * This is a pure in-memory tracker — all state is reset when the daemon restarts.
+ * This is acceptable per ADR-004 (stateless except for rate limit tracking).
+ *
+ * @example
+ * const tracker = new ProviderStatusTracker()
+ * tracker.initProvider('claude', true, true, { tokensPerWindow: 220000, windowSeconds: 18000 })
+ * const ok = tracker.checkRateLimit('claude', 1000) // true if capacity available
+ * tracker.recordTokenUsage('claude', 1000)
+ */
+export declare class ProviderStatusTracker {
+    private readonly _windows;
+    private readonly _subscriptionEnabled;
+    private readonly _apiBillingEnabled;
+    /**
+     * Initialize tracking for a provider.
+     * Called once during RoutingEngine initialization from the routing policy.
+     *
+     * @param provider - Provider name
+     * @param subscriptionEnabled - Whether subscription routing is on
+     * @param apiBillingEnabled - Whether API billing is available
+     * @param rateLimit - Rate limit configuration (optional)
+     */
+    initProvider(provider: string, subscriptionEnabled: boolean, apiBillingEnabled: boolean, rateLimit?: {
+        tokensPerWindow: number;
+        windowSeconds: number;
+    }): void;
+    /**
+     * Check whether a provider can accept the estimated token usage without exceeding its limit.
+     *
+     * @param provider - Provider name
+     * @param estimatedTokens - Tokens that would be consumed
+     * @returns true if tokens won't exceed limit (or no rate limit configured), false otherwise
+     */
+    checkRateLimit(provider: string, estimatedTokens: number): boolean;
+    /**
+     * Record token usage for a provider after task completion.
+     * Resets the window if it has expired before recording.
+     *
+     * @param provider - Provider name
+     * @param tokensUsed - Actual tokens consumed
+     */
+    recordTokenUsage(provider: string, tokensUsed: number): void;
+    /**
+     * Get the timestamp when the current rate limit window resets.
+     *
+     * @param provider - Provider name
+     * @returns Date when the window resets, or the current time if no rate limit configured
+     */
+    getRateLimitResetTime(provider: string): Date;
+    /**
+     * Return a snapshot of the current status for a provider.
+     *
+     * @param provider - Provider name
+     * @returns ProviderStatus snapshot, or null if provider is not tracked
+     */
+    getStatus(provider: string): ProviderStatus | null;
+    /**
+     * Return all tracked provider names.
+     */
+    getTrackedProviders(): string[];
+    private _resetWindowIfExpired;
+}
+//# sourceMappingURL=provider-status.d.ts.map

package/dist/routing/provider-status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-status.d.ts","sourceRoot":"","sources":["../../src/routing/provider-status.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAMH;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,wDAAwD;IACxD,QAAQ,EAAE,MAAM,CAAA;IAChB,gEAAgE;IAChE,0BAA0B,EAAE,OAAO,CAAA;IACnC,yDAAyD;IACzD,iBAAiB,EAAE,OAAO,CAAA;IAC1B,uDAAuD;IACvD,kBAAkB,EAAE,MAAM,CAAA;IAC1B,2FAA2F;IAC3F,eAAe,EAAE,MAAM,CAAA;IACvB,+BAA+B;IAC/B,SAAS,EAAE;QAAE,eAAe,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE,CAAA;CAC9D;AAkBD;;;;;;;;;;;GAWG;AACH,qBAAa,qBAAqB;IAChC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA0C;IACnE,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAkC;IACvE,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAkC;IAMrE;;;;;;;;OAQG;IACH,YAAY,CACV,QAAQ,EAAE,MAAM,EAChB,mBAAmB,EAAE,OAAO,EAC5B,iBAAiB,EAAE,OAAO,EAC1B,SAAS,CAAC,EAAE;QAAE,eAAe,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE,GAC7D,IAAI;IAmBP;;;;;;OAMG;IACH,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,GAAG,OAAO;IAalE;;;;;;OAMG;IACH,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI;IAY5D;;;;;OAKG;IACH,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAY7C;;;;;OAKG;IACH,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI;IAkClD;;OAEG;IACH,mBAAmB,IAAI,MAAM,EAAE;IAQ/B,OAAO,CAAC,qBAAqB;CAO9B"}

package/dist/routing/provider-status.js

@@ -0,0 +1,163 @@
+/**
+ * ProviderStatus — in-memory rate limit and status tracking per provider.
+ *
+ * Tracks:
+ *  - Subscription routing enabled/disabled
+ *  - API billing availability
+ *  - Rate limit consumption within the current window
+ *
+ * References:
+ *  - Architecture Section 8: Rate limit tracking per provider
+ *  - FR29: Rate limit management
+ *  - ADR-004: RoutingEngine is stateless except for rate limit tracking in-memory
+ */
+// ---------------------------------------------------------------------------
+// ProviderStatusTracker
+// ---------------------------------------------------------------------------
+/**
+ * Manages in-memory rate limit state and provider availability for all providers.
+ *
+ * This is a pure in-memory tracker — all state is reset when the daemon restarts.
+ * This is acceptable per ADR-004 (stateless except for rate limit tracking).
+ *
+ * @example
+ * const tracker = new ProviderStatusTracker()
+ * tracker.initProvider('claude', true, true, { tokensPerWindow: 220000, windowSeconds: 18000 })
+ * const ok = tracker.checkRateLimit('claude', 1000) // true if capacity available
+ * tracker.recordTokenUsage('claude', 1000)
+ */
+export class ProviderStatusTracker {
+    _windows = new Map();
+    _subscriptionEnabled = new Map();
+    _apiBillingEnabled = new Map();
+    // ---------------------------------------------------------------------------
+    // Initialization
+    // ---------------------------------------------------------------------------
+    /**
+     * Initialize tracking for a provider.
+     * Called once during RoutingEngine initialization from the routing policy.
+     *
+     * @param provider - Provider name
+     * @param subscriptionEnabled - Whether subscription routing is on
+     * @param apiBillingEnabled - Whether API billing is available
+     * @param rateLimit - Rate limit configuration (optional)
+     */
+    initProvider(provider, subscriptionEnabled, apiBillingEnabled, rateLimit) {
+        this._subscriptionEnabled.set(provider, subscriptionEnabled);
+        this._apiBillingEnabled.set(provider, apiBillingEnabled);
+        if (rateLimit !== undefined) {
+            this._windows.set(provider, {
+                provider,
+                tokensUsedInWindow: 0,
+                windowStartAtMs: Date.now(),
+                windowDurationMs: rateLimit.windowSeconds * 1000,
+                tokensPerWindow: rateLimit.tokensPerWindow,
+            });
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Rate limit management
+    // ---------------------------------------------------------------------------
+    /**
+     * Check whether a provider can accept the estimated token usage without exceeding its limit.
+     *
+     * @param provider - Provider name
+     * @param estimatedTokens - Tokens that would be consumed
+     * @returns true if tokens won't exceed limit (or no rate limit configured), false otherwise
+     */
+    checkRateLimit(provider, estimatedTokens) {
+        const window = this._windows.get(provider);
+        if (window === undefined) {
+            // No rate limit configured — always available
+            return true;
+        }
+        // Check if window has expired and reset if needed
+        this._resetWindowIfExpired(window);
+        return window.tokensUsedInWindow + estimatedTokens <= window.tokensPerWindow;
+    }
+    /**
+     * Record token usage for a provider after task completion.
+     * Resets the window if it has expired before recording.
+     *
+     * @param provider - Provider name
+     * @param tokensUsed - Actual tokens consumed
+     */
+    recordTokenUsage(provider, tokensUsed) {
+        const window = this._windows.get(provider);
+        if (window === undefined) {
+            return;
+        }
+        // Reset if window expired
+        this._resetWindowIfExpired(window);
+        window.tokensUsedInWindow += tokensUsed;
+    }
+    /**
+     * Get the timestamp when the current rate limit window resets.
+     *
+     * @param provider - Provider name
+     * @returns Date when the window resets, or the current time if no rate limit configured
+     */
+    getRateLimitResetTime(provider) {
+        const window = this._windows.get(provider);
+        if (window === undefined) {
+            return new Date();
+        }
+        return new Date(window.windowStartAtMs + window.windowDurationMs);
+    }
+    // ---------------------------------------------------------------------------
+    // Status snapshot
+    // ---------------------------------------------------------------------------
+    /**
+     * Return a snapshot of the current status for a provider.
+     *
+     * @param provider - Provider name
+     * @returns ProviderStatus snapshot, or null if provider is not tracked
+     */
+    getStatus(provider) {
+        const subscriptionEnabled = this._subscriptionEnabled.get(provider);
+        if (subscriptionEnabled === undefined) {
+            return null;
+        }
+        const apiBillingEnabled = this._apiBillingEnabled.get(provider) ?? false;
+        const window = this._windows.get(provider);
+        if (window !== undefined) {
+            this._resetWindowIfExpired(window);
+            return {
+                provider,
+                subscriptionRoutingEnabled: subscriptionEnabled,
+                apiBillingEnabled,
+                tokensUsedInWindow: window.tokensUsedInWindow,
+                windowResetAtMs: window.windowStartAtMs + window.windowDurationMs,
+                rateLimit: {
+                    tokensPerWindow: window.tokensPerWindow,
+                    windowSeconds: window.windowDurationMs / 1000,
+                },
+            };
+        }
+        return {
+            provider,
+            subscriptionRoutingEnabled: subscriptionEnabled,
+            apiBillingEnabled,
+            tokensUsedInWindow: 0,
+            windowResetAtMs: 0,
+            rateLimit: { tokensPerWindow: 0, windowSeconds: 0 },
+        };
+    }
+    /**
+     * Return all tracked provider names.
+     */
+    getTrackedProviders() {
+        return Array.from(this._subscriptionEnabled.keys());
+    }
+    // ---------------------------------------------------------------------------
+    // Private helpers
+    // ---------------------------------------------------------------------------
+    _resetWindowIfExpired(window) {
+        const now = Date.now();
+        if (now > window.windowStartAtMs + window.windowDurationMs) {
+            window.tokensUsedInWindow = 0;
+            window.windowStartAtMs = now;
+        }
+    }
+}
+//# sourceMappingURL=provider-status.js.map

package/dist/routing/provider-status.js.map

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