@substrate-ai/core 0.19.54

package/dist/routing/routing-policy.d.ts

@@ -0,0 +1,138 @@
+/**
+ * RoutingPolicy — Zod schema, types, and loader for the routing policy YAML file.
+ *
+ * The routing policy YAML (default: .substrate/routing-policy.yaml) controls:
+ *  - Which agents are preferred for which task types
+ *  - Subscription-first vs. API billing preference
+ *  - Per-provider rate limits
+ *  - Fallback chains when preferred agents are unavailable
+ *
+ * References:
+ *  - Architecture Section 8: Subscription-first algorithm
+ *  - FR22, FR23, FR25: Subscription routing toggles
+ *  - NFR13: Schema validation with Zod
+ */
+import { z } from 'zod';
+/**
+ * API billing configuration for a provider.
+ */
+export declare const ApiBillingConfigSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    api_key_env: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ApiBillingConfig = z.infer<typeof ApiBillingConfigSchema>;
+/**
+ * Rate limit configuration for a provider.
+ */
+export declare const RateLimitConfigSchema: z.ZodObject<{
+    tokens_per_window: z.ZodNumber;
+    window_seconds: z.ZodNumber;
+}, z.core.$strip>;
+export type RateLimitConfig = z.infer<typeof RateLimitConfigSchema>;
+/**
+ * Per-provider configuration.
+ */
+export declare const ProviderPolicySchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    cli_path: z.ZodDefault<z.ZodString>;
+    subscription_routing: z.ZodDefault<z.ZodBoolean>;
+    max_concurrent: z.ZodDefault<z.ZodNumber>;
+    rate_limit: z.ZodOptional<z.ZodObject<{
+        tokens_per_window: z.ZodNumber;
+        window_seconds: z.ZodNumber;
+    }, z.core.$strip>>;
+    api_billing: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        api_key_env: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ProviderPolicy = z.infer<typeof ProviderPolicySchema>;
+/**
+ * Per-task-type routing configuration.
+ * Specifies which agents are preferred for a given task type and optional model preferences.
+ */
+export declare const TaskTypePolicySchema: z.ZodObject<{
+    preferred_agents: z.ZodArray<z.ZodString>;
+    model_preferences: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strip>;
+export type TaskTypePolicy = z.infer<typeof TaskTypePolicySchema>;
+/**
+ * Default routing configuration (used when no task-type-specific policy applies).
+ */
+export declare const DefaultRoutingPolicySchema: z.ZodObject<{
+    preferred_agents: z.ZodArray<z.ZodString>;
+    billing_preference: z.ZodDefault<z.ZodEnum<{
+        subscription_first: "subscription_first";
+        api_only: "api_only";
+        subscription_only: "subscription_only";
+    }>>;
+    use_monitor_recommendations: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+export type DefaultRoutingPolicy = z.infer<typeof DefaultRoutingPolicySchema>;
+/**
+ * Global routing settings.
+ */
+export declare const GlobalRoutingSettingsSchema: z.ZodObject<{
+    max_concurrent_workers: z.ZodDefault<z.ZodNumber>;
+    fallback_enabled: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+export type GlobalRoutingSettings = z.infer<typeof GlobalRoutingSettingsSchema>;
+/**
+ * Complete routing policy document schema.
+ * Supports optional fields gracefully (AC6 — extensibility).
+ */
+export declare const RoutingPolicySchema: z.ZodObject<{
+    default: z.ZodObject<{
+        preferred_agents: z.ZodArray<z.ZodString>;
+        billing_preference: z.ZodDefault<z.ZodEnum<{
+            subscription_first: "subscription_first";
+            api_only: "api_only";
+            subscription_only: "subscription_only";
+        }>>;
+        use_monitor_recommendations: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>;
+    task_types: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        preferred_agents: z.ZodArray<z.ZodString>;
+        model_preferences: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.core.$strip>>>>;
+    providers: z.ZodRecord<z.ZodString, z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        cli_path: z.ZodDefault<z.ZodString>;
+        subscription_routing: z.ZodDefault<z.ZodBoolean>;
+        max_concurrent: z.ZodDefault<z.ZodNumber>;
+        rate_limit: z.ZodOptional<z.ZodObject<{
+            tokens_per_window: z.ZodNumber;
+            window_seconds: z.ZodNumber;
+        }, z.core.$strip>>;
+        api_billing: z.ZodOptional<z.ZodObject<{
+            enabled: z.ZodDefault<z.ZodBoolean>;
+            api_key_env: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    global: z.ZodDefault<z.ZodOptional<z.ZodObject<{
+        max_concurrent_workers: z.ZodDefault<z.ZodNumber>;
+        fallback_enabled: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type RoutingPolicy = z.infer<typeof RoutingPolicySchema>;
+/**
+ * Error thrown when routing policy validation fails.
+ *
+ * Extends plain Error (not SubstrateError) to keep core package free of monolith imports.
+ */
+export declare class RoutingPolicyValidationError extends Error {
+    readonly details?: string | undefined;
+    constructor(message: string, details?: string | undefined);
+}
+/**
+ * Load and validate a routing policy YAML file.
+ *
+ * @param filePath - Absolute or relative path to the routing policy YAML
+ * @returns Parsed and validated RoutingPolicy object
+ * @throws {RoutingPolicyValidationError} if the file cannot be parsed or the schema is invalid
+ *
+ * @example
+ * const policy = loadRoutingPolicy('.substrate/routing-policy.yaml')
+ */
+export declare function loadRoutingPolicy(filePath: string): RoutingPolicy;
+//# sourceMappingURL=routing-policy.d.ts.map

package/dist/routing/routing-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routing-policy.d.ts","sourceRoot":"","sources":["../../src/routing/routing-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAMvB;;GAEG;AACH,eAAO,MAAM,sBAAsB;;;iBAGjC,CAAA;AAEF,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAA;AAErE;;GAEG;AACH,eAAO,MAAM,qBAAqB;;;iBAGhC,CAAA;AAEF,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAA;AAEnE;;GAEG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;iBAO/B,CAAA;AAEF,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAA;AAEjE;;;GAGG;AACH,eAAO,MAAM,oBAAoB;;;iBAG/B,CAAA;AAEF,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAA;AAEjE;;GAEG;AACH,eAAO,MAAM,0BAA0B;;;;;;;;iBAIrC,CAAA;AAEF,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAA;AAE7E;;GAEG;AACH,eAAO,MAAM,2BAA2B;;;iBAGtC,CAAA;AAEF,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAA;AAE/E;;;GAGG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAQ9B,CAAA;AAEF,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAA;AAM/D;;;;GAIG;AACH,qBAAa,4BAA6B,SAAQ,KAAK;aACR,OAAO,CAAC,EAAE,MAAM;gBAAjD,OAAO,EAAE,MAAM,EAAkB,OAAO,CAAC,EAAE,MAAM,YAAA;CAK9D;AAMD;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,aAAa,CAmEjE"}

package/dist/routing/routing-policy.js

@@ -0,0 +1,159 @@
+/**
+ * RoutingPolicy — Zod schema, types, and loader for the routing policy YAML file.
+ *
+ * The routing policy YAML (default: .substrate/routing-policy.yaml) controls:
+ *  - Which agents are preferred for which task types
+ *  - Subscription-first vs. API billing preference
+ *  - Per-provider rate limits
+ *  - Fallback chains when preferred agents are unavailable
+ *
+ * References:
+ *  - Architecture Section 8: Subscription-first algorithm
+ *  - FR22, FR23, FR25: Subscription routing toggles
+ *  - NFR13: Schema validation with Zod
+ */
+import { readFileSync } from 'node:fs';
+import { load as yamlLoad } from 'js-yaml';
+import { z } from 'zod';
+// ---------------------------------------------------------------------------
+// Zod Schemas
+// ---------------------------------------------------------------------------
+/**
+ * API billing configuration for a provider.
+ */
+export const ApiBillingConfigSchema = z.object({
+    enabled: z.boolean().default(false),
+    api_key_env: z.string().optional(),
+});
+/**
+ * Rate limit configuration for a provider.
+ */
+export const RateLimitConfigSchema = z.object({
+    tokens_per_window: z.number().int().positive(),
+    window_seconds: z.number().int().positive(),
+});
+/**
+ * Per-provider configuration.
+ */
+export const ProviderPolicySchema = z.object({
+    enabled: z.boolean().default(true),
+    cli_path: z.string().default(''),
+    subscription_routing: z.boolean().default(false),
+    max_concurrent: z.number().int().min(1).max(32).default(1),
+    rate_limit: RateLimitConfigSchema.optional(),
+    api_billing: ApiBillingConfigSchema.optional(),
+});
+/**
+ * Per-task-type routing configuration.
+ * Specifies which agents are preferred for a given task type and optional model preferences.
+ */
+export const TaskTypePolicySchema = z.object({
+    preferred_agents: z.array(z.string()).min(1),
+    model_preferences: z.record(z.string(), z.string()).optional(),
+});
+/**
+ * Default routing configuration (used when no task-type-specific policy applies).
+ */
+export const DefaultRoutingPolicySchema = z.object({
+    preferred_agents: z.array(z.string()).min(1),
+    billing_preference: z.enum(['subscription_first', 'api_only', 'subscription_only']).default('subscription_first'),
+    use_monitor_recommendations: z.boolean().default(false),
+});
+/**
+ * Global routing settings.
+ */
+export const GlobalRoutingSettingsSchema = z.object({
+    max_concurrent_workers: z.number().int().min(1).max(100).default(5),
+    fallback_enabled: z.boolean().default(true),
+});
+/**
+ * Complete routing policy document schema.
+ * Supports optional fields gracefully (AC6 — extensibility).
+ */
+export const RoutingPolicySchema = z.object({
+    default: DefaultRoutingPolicySchema,
+    task_types: z.record(z.string(), TaskTypePolicySchema).optional().default({}),
+    providers: z.record(z.string(), ProviderPolicySchema).refine((providers) => Object.keys(providers).length > 0, { message: 'Routing policy must have at least one provider configured' }),
+    global: GlobalRoutingSettingsSchema.optional().default({ max_concurrent_workers: 5, fallback_enabled: true }),
+});
+// ---------------------------------------------------------------------------
+// Validation errors
+// ---------------------------------------------------------------------------
+/**
+ * Error thrown when routing policy validation fails.
+ *
+ * Extends plain Error (not SubstrateError) to keep core package free of monolith imports.
+ */
+export class RoutingPolicyValidationError extends Error {
+    details;
+    constructor(message, details) {
+        super(message);
+        this.details = details;
+        this.name = 'RoutingPolicyValidationError';
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+// ---------------------------------------------------------------------------
+// loadRoutingPolicy
+// ---------------------------------------------------------------------------
+/**
+ * Load and validate a routing policy YAML file.
+ *
+ * @param filePath - Absolute or relative path to the routing policy YAML
+ * @returns Parsed and validated RoutingPolicy object
+ * @throws {RoutingPolicyValidationError} if the file cannot be parsed or the schema is invalid
+ *
+ * @example
+ * const policy = loadRoutingPolicy('.substrate/routing-policy.yaml')
+ */
+export function loadRoutingPolicy(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 RoutingPolicyValidationError(`Cannot read routing policy file at "${filePath}": ${message}`);
+    }
+    // Parse YAML
+    let rawObject;
+    try {
+        rawObject = yamlLoad(rawContent);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new RoutingPolicyValidationError(`Invalid YAML in routing policy file at "${filePath}": ${message}`);
+    }
+    if (rawObject === null || typeof rawObject !== 'object') {
+        throw new RoutingPolicyValidationError(`Routing policy file at "${filePath}" must contain a YAML object`);
+    }
+    // Validate with Zod
+    const result = RoutingPolicySchema.safeParse(rawObject);
+    if (!result.success) {
+        // Zod v4 uses `.issues` instead of deprecated `.errors`
+        const issues = result.error.issues ?? result.error.errors ?? [];
+        const details = issues
+            .map((e) => `  - ${e.path.join('.')}: ${e.message}`)
+            .join('\n');
+        throw new RoutingPolicyValidationError(`Routing policy validation failed for "${filePath}":\n${details}`, details);
+    }
+    // Validate that all task_type agents exist in providers
+    const policy = result.data;
+    const providerNames = new Set(Object.keys(policy.providers));
+    for (const [taskType, taskPolicy] of Object.entries(policy.task_types ?? {})) {
+        for (const agent of taskPolicy.preferred_agents) {
+            if (!providerNames.has(agent)) {
+                throw new RoutingPolicyValidationError(`Task type "${taskType}" references agent "${agent}" which is not defined in the providers section`);
+            }
+        }
+    }
+    // Validate default agents
+    for (const agent of policy.default.preferred_agents) {
+        if (!providerNames.has(agent)) {
+            throw new RoutingPolicyValidationError(`Default routing references agent "${agent}" which is not defined in the providers section`);
+        }
+    }
+    return policy;
+}
+//# sourceMappingURL=routing-policy.js.map

package/dist/routing/routing-policy.js.map

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

package/dist/routing/routing-recommender.d.ts

@@ -0,0 +1,60 @@
+/**
+ * RoutingRecommender — analyzes per-phase token breakdown history and generates
+ * model routing recommendations.
+ *
+ * High output ratios (output / (input + output) > 0.40) indicate the model is
+ * doing more generation work than context consumption, suggesting an upgrade may
+ * be justified.  Low output ratios (< 0.15) indicate mostly context-reading work
+ * where a cheaper model should suffice, triggering a downgrade recommendation.
+ *
+ * References:
+ *  - Epic 28, Story 28-8: Feedback Loop — Telemetry-Driven Routing Tuning
+ */
+import type { ILogger } from '../dispatch/types.js';
+import type { ModelRoutingConfig } from './model-routing-config.js';
+import type { PhaseTokenBreakdown, RoutingAnalysis } from './types.js';
+/**
+ * Analyzes phase-level token breakdown history and produces routing
+ * recommendations based on observed output ratios.
+ *
+ * This class is stateless: call `analyze()` with historical breakdowns to
+ * get fresh recommendations each time.
+ */
+export declare class RoutingRecommender {
+    private readonly _logger;
+    constructor(logger: ILogger);
+    /**
+     * Determine the model tier (1=haiku, 2=sonnet, 3=opus) for a given model name.
+     * Defaults to tier 2 (sonnet) when no keyword matches.
+     */
+    private _getTier;
+    /**
+     * Get the canonical model keyword fragment for a given tier.
+     */
+    private _getTierKeyword;
+    /**
+     * Compute the output ratio for a set of phase token entries:
+     *   outputRatio = sum(outputTokens) / (sum(inputTokens) + sum(outputTokens))
+     *
+     * Returns 0.5 when the total token count is zero to avoid division by zero.
+     */
+    private _computeOutputRatio;
+    /**
+     * Analyze historical phase token breakdowns and produce routing recommendations.
+     *
+     * @param breakdowns - Historical PhaseTokenBreakdown records (one per pipeline run)
+     * @param config     - Current model routing configuration
+     * @returns RoutingAnalysis with recommendations and per-phase output ratios
+     */
+    analyze(breakdowns: PhaseTokenBreakdown[], config: ModelRoutingConfig): RoutingAnalysis;
+    /**
+     * Replace the tier keyword in a model name string with a new keyword.
+     *
+     * e.g. ('claude-haiku-4-5', 1, 'sonnet') → 'claude-sonnet-4-5'
+     *
+     * If the current tier keyword is not found in the model name, returns
+     * a synthesised name like 'claude-sonnet' using the new keyword.
+     */
+    private _substituteTierKeyword;
+}
+//# sourceMappingURL=routing-recommender.d.ts.map

package/dist/routing/routing-recommender.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routing-recommender.d.ts","sourceRoot":"","sources":["../../src/routing/routing-recommender.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAA;AACnD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAA;AACnE,OAAO,KAAK,EACV,mBAAmB,EAEnB,eAAe,EAEhB,MAAM,YAAY,CAAA;AAoCnB;;;;;;GAMG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAErB,MAAM,EAAE,OAAO;IAQ3B;;;OAGG;IACH,OAAO,CAAC,QAAQ;IAQhB;;OAEG;IACH,OAAO,CAAC,eAAe;IAIvB;;;;;OAKG;IACH,OAAO,CAAC,mBAAmB;IAgB3B;;;;;;OAMG;IACH,OAAO,CAAC,UAAU,EAAE,mBAAmB,EAAE,EAAE,MAAM,EAAE,kBAAkB,GAAG,eAAe;IA4GvF;;;;;;;OAOG;IACH,OAAO,CAAC,sBAAsB;CAe/B"}

package/dist/routing/routing-recommender.js

@@ -0,0 +1,209 @@
+/**
+ * RoutingRecommender — analyzes per-phase token breakdown history and generates
+ * model routing recommendations.
+ *
+ * High output ratios (output / (input + output) > 0.40) indicate the model is
+ * doing more generation work than context consumption, suggesting an upgrade may
+ * be justified.  Low output ratios (< 0.15) indicate mostly context-reading work
+ * where a cheaper model should suffice, triggering a downgrade recommendation.
+ *
+ * References:
+ *  - Epic 28, Story 28-8: Feedback Loop — Telemetry-Driven Routing Tuning
+ */
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/**
+ * Ordered tier list: index 0 = cheapest / smallest, index N = most expensive / largest.
+ * Tiers are determined by substring matching — e.g. 'claude-haiku-4-5' → tier 1.
+ */
+const TIER_KEYWORDS = [
+    { keyword: 'haiku', tier: 1 },
+    { keyword: 'sonnet', tier: 2 },
+    { keyword: 'opus', tier: 3 },
+];
+/** Minimum historical breakdowns required before any recommendations are generated. */
+const MIN_BREAKDOWNS = 3;
+/** Output ratio below this threshold triggers a downgrade recommendation. */
+const DOWNGRADE_THRESHOLD = 0.15;
+/** Output ratio above this threshold triggers an upgrade recommendation. */
+const UPGRADE_THRESHOLD = 0.40;
+/** Ordered list of model name fragments by tier (cheapest → most expensive). */
+const TIER_TO_MODEL_FRAGMENT = {
+    1: 'haiku',
+    2: 'sonnet',
+    3: 'opus',
+};
+// ---------------------------------------------------------------------------
+// RoutingRecommender
+// ---------------------------------------------------------------------------
+/**
+ * Analyzes phase-level token breakdown history and produces routing
+ * recommendations based on observed output ratios.
+ *
+ * This class is stateless: call `analyze()` with historical breakdowns to
+ * get fresh recommendations each time.
+ */
+export class RoutingRecommender {
+    _logger;
+    constructor(logger) {
+        this._logger = logger;
+    }
+    // ---------------------------------------------------------------------------
+    // Private helpers
+    // ---------------------------------------------------------------------------
+    /**
+     * Determine the model tier (1=haiku, 2=sonnet, 3=opus) for a given model name.
+     * Defaults to tier 2 (sonnet) when no keyword matches.
+     */
+    _getTier(model) {
+        const lower = model.toLowerCase();
+        for (const { keyword, tier } of TIER_KEYWORDS) {
+            if (lower.includes(keyword))
+                return tier;
+        }
+        return 2; // default: sonnet tier
+    }
+    /**
+     * Get the canonical model keyword fragment for a given tier.
+     */
+    _getTierKeyword(tier) {
+        return TIER_TO_MODEL_FRAGMENT[tier] ?? 'sonnet';
+    }
+    /**
+     * Compute the output ratio for a set of phase token entries:
+     *   outputRatio = sum(outputTokens) / (sum(inputTokens) + sum(outputTokens))
+     *
+     * Returns 0.5 when the total token count is zero to avoid division by zero.
+     */
+    _computeOutputRatio(entries) {
+        let totalInput = 0;
+        let totalOutput = 0;
+        for (const entry of entries) {
+            totalInput += entry.inputTokens;
+            totalOutput += entry.outputTokens;
+        }
+        const total = totalInput + totalOutput;
+        if (total === 0)
+            return 0.5;
+        return totalOutput / total;
+    }
+    // ---------------------------------------------------------------------------
+    // Public API
+    // ---------------------------------------------------------------------------
+    /**
+     * Analyze historical phase token breakdowns and produce routing recommendations.
+     *
+     * @param breakdowns - Historical PhaseTokenBreakdown records (one per pipeline run)
+     * @param config     - Current model routing configuration
+     * @returns RoutingAnalysis with recommendations and per-phase output ratios
+     */
+    analyze(breakdowns, config) {
+        if (breakdowns.length < MIN_BREAKDOWNS) {
+            this._logger.debug({ dataPoints: breakdowns.length, threshold: MIN_BREAKDOWNS, reason: 'insufficient_data' }, 'Insufficient data for routing analysis');
+            return {
+                recommendations: [],
+                analysisRuns: breakdowns.length,
+                insufficientData: true,
+                phaseOutputRatios: {},
+            };
+        }
+        // Group all entries by phase across all breakdowns
+        const phaseEntries = {};
+        for (const breakdown of breakdowns) {
+            for (const entry of breakdown.entries) {
+                const phase = entry.phase;
+                if (phaseEntries[phase] === undefined) {
+                    phaseEntries[phase] = [];
+                }
+                phaseEntries[phase].push(entry);
+            }
+        }
+        // Compute output ratio per phase
+        const phaseOutputRatios = {};
+        for (const [phase, entries] of Object.entries(phaseEntries)) {
+            phaseOutputRatios[phase] = this._computeOutputRatio(entries);
+        }
+        // Generate recommendations per phase
+        const recommendations = [];
+        const confidence = Math.min(breakdowns.length / 10, 1);
+        for (const [phase, outputRatio] of Object.entries(phaseOutputRatios)) {
+            const currentModel = config.phases[phase]?.model ?? config.baseline_model;
+            const currentTier = this._getTier(currentModel);
+            if (outputRatio < DOWNGRADE_THRESHOLD) {
+                // Candidate for downgrade
+                const suggestedTier = currentTier - 1;
+                if (suggestedTier < 1) {
+                    this._logger.debug({ phase, currentTier }, 'Already at minimum tier — skipping downgrade');
+                    continue;
+                }
+                const suggestedKeyword = this._getTierKeyword(suggestedTier);
+                // Build suggested model name by replacing the tier keyword in the current model name.
+                // Falls back to just the keyword fragment if no keyword found in current model.
+                const suggestedModel = this._substituteTierKeyword(currentModel, currentTier, suggestedKeyword);
+                const estimatedSavingsPct = ((currentTier - suggestedTier) / currentTier) * 50;
+                recommendations.push({
+                    phase,
+                    currentModel,
+                    suggestedModel,
+                    estimatedSavingsPct,
+                    confidence,
+                    dataPoints: breakdowns.length,
+                    direction: 'downgrade',
+                });
+                this._logger.debug({ phase, currentModel, suggestedModel, outputRatio, estimatedSavingsPct }, 'Downgrade recommendation generated');
+            }
+            else if (outputRatio > UPGRADE_THRESHOLD) {
+                // Candidate for upgrade
+                const suggestedTier = currentTier + 1;
+                if (suggestedTier > 3) {
+                    this._logger.debug({ phase, currentTier }, 'Already at maximum tier — skipping upgrade');
+                    continue;
+                }
+                const suggestedKeyword = this._getTierKeyword(suggestedTier);
+                const suggestedModel = this._substituteTierKeyword(currentModel, currentTier, suggestedKeyword);
+                const estimatedSavingsPct = ((currentTier - suggestedTier) / currentTier) * 50;
+                recommendations.push({
+                    phase,
+                    currentModel,
+                    suggestedModel,
+                    estimatedSavingsPct,
+                    confidence,
+                    dataPoints: breakdowns.length,
+                    direction: 'upgrade',
+                });
+                this._logger.debug({ phase, currentModel, suggestedModel, outputRatio, estimatedSavingsPct }, 'Upgrade recommendation generated');
+            }
+            // Neutral zone (0.15..0.40): no recommendation
+        }
+        return {
+            recommendations,
+            analysisRuns: breakdowns.length,
+            insufficientData: false,
+            phaseOutputRatios,
+        };
+    }
+    // ---------------------------------------------------------------------------
+    // Private helpers
+    // ---------------------------------------------------------------------------
+    /**
+     * Replace the tier keyword in a model name string with a new keyword.
+     *
+     * e.g. ('claude-haiku-4-5', 1, 'sonnet') → 'claude-sonnet-4-5'
+     *
+     * If the current tier keyword is not found in the model name, returns
+     * a synthesised name like 'claude-sonnet' using the new keyword.
+     */
+    _substituteTierKeyword(currentModel, currentTier, newKeyword) {
+        const currentKeyword = this._getTierKeyword(currentTier);
+        if (currentModel.toLowerCase().includes(currentKeyword)) {
+            // Case-insensitive replacement
+            return currentModel.replace(new RegExp(currentKeyword, 'i'), newKeyword);
+        }
+        // Fallback: synthesize from prefix
+        const dashIdx = currentModel.indexOf('-');
+        const prefix = dashIdx !== -1 ? currentModel.slice(0, dashIdx) : currentModel;
+        return `${prefix}-${newKeyword}`;
+    }
+}
+//# sourceMappingURL=routing-recommender.js.map

package/dist/routing/routing-recommender.js.map

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

package/dist/routing/routing-telemetry.d.ts

@@ -0,0 +1,36 @@
+/**
+ * RoutingTelemetry — emits OTEL spans for model routing decisions.
+ *
+ * Call `recordModelResolved()` immediately after `RoutingResolver.resolveModel()`
+ * returns a non-null result to capture per-dispatch routing latency and metadata.
+ *
+ * References:
+ *  - Epic 28, Story 28-6: Routing Telemetry — Per-Phase Token Tracking and OTEL Spans
+ */
+import type { ILogger } from '../dispatch/types.js';
+import type { IRoutingTelemetryPersistence } from './types.js';
+/**
+ * Emits `routing.model_resolved` OTEL spans via an IRoutingTelemetryPersistence instance.
+ *
+ * Injected into the run command alongside RoutingResolver. When telemetry is
+ * not configured, pass null to the run command; no spans are emitted.
+ */
+export declare class RoutingTelemetry {
+    private readonly _telemetry;
+    private readonly _logger;
+    constructor(telemetry: IRoutingTelemetryPersistence, logger: ILogger);
+    /**
+     * Emit a `routing.model_resolved` span for a single routing decision.
+     *
+     * @param attrs - span attributes including dispatchId, taskType, phase, model, source, latencyMs
+     */
+    recordModelResolved(attrs: {
+        dispatchId: string;
+        taskType: string;
+        phase: string;
+        model: string;
+        source: string;
+        latencyMs: number;
+    }): void;
+}
+//# sourceMappingURL=routing-telemetry.d.ts.map

package/dist/routing/routing-telemetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routing-telemetry.d.ts","sourceRoot":"","sources":["../../src/routing/routing-telemetry.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAA;AACnD,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,YAAY,CAAA;AAM9D;;;;;GAKG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA8B;IACzD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAErB,SAAS,EAAE,4BAA4B,EAAE,MAAM,EAAE,OAAO;IAKpE;;;;OAIG;IACH,mBAAmB,CAAC,KAAK,EAAE;QACzB,UAAU,EAAE,MAAM,CAAA;QAClB,QAAQ,EAAE,MAAM,CAAA;QAChB,KAAK,EAAE,MAAM,CAAA;QACb,KAAK,EAAE,MAAM,CAAA;QACb,MAAM,EAAE,MAAM,CAAA;QACd,SAAS,EAAE,MAAM,CAAA;KAClB,GAAG,IAAI;CAOT"}