llm-cli-gateway 2.16.0 → 2.17.0

package/dist/validation-tools.js

@@ -3,8 +3,62 @@ import { CLI_TYPES } from "./session-manager.js";
 import { getAvailableCliInfo } from "./model-registry.js";
 import { apiProviderCatalogEntry } from "./api-request.js";
 import { getRequestContext, principalCanAccess, resolveOwnerPrincipal } from "./request-context.js";
+import { PerformanceMetrics } from "./metrics.js";
+import { loadLeastCostConfig } from "./config.js";
+import { buildRouterEnv, toRouterConfig } from "./lcr-router-env.js";
+import { selectCandidate, selectCheapestPerTier, } from "./least-cost-router.js";
 import { currentCaller, eagerMintFromJobId, eagerMintFromValidationId, resolveValidationReceipt, } from "./validation-receipt.js";
 import { collectValidationJobResult, startJudgeSynthesis, startValidationRun, } from "./validation-orchestrator.js";
+const selectSchema = z
+    .enum(["cheapest", "cheapest_per_tier"])
+    .optional()
+    .describe("Optional least-cost routing: fill the provider target(s) from the LCR selector instead of the explicit list. 'cheapest' picks the single cheapest eligible provider; 'cheapest_per_tier' picks the cheapest in each quality tier. Requires [least_cost].enabled=true; fails closed (no default-list fallback) when disabled or nothing is eligible.");
+function selectorFailureMessage(decision) {
+    const reasons = decision.rejected.map(r => `${r.candidate.provider}/${r.candidate.model}: ${r.reason}`);
+    const detail = reasons.length > 0 ? ` Rejections: ${reasons.join("; ")}.` : "";
+    return `least-cost routing found no eligible provider (${decision.error ?? "NoEligibleCandidate"}); no fallback to the default provider list (fail closed).${detail}`;
+}
+function resolveSelectedProviders(ctx, prompt, mode, singleProvider) {
+    if (!ctx.leastCost.enabled) {
+        return {
+            ok: false,
+            error: "select requires least-cost routing; set [least_cost].enabled=true in ~/.llm-cli-gateway/config.toml (no fallback to the default provider list).",
+        };
+    }
+    const env = buildRouterEnv({
+        performanceMetrics: ctx.performanceMetrics,
+        limiterSnapshot: ctx.asyncJobManager.getLimiterSnapshot(),
+        apiProviders: ctx.apiProviders,
+        preferCatalogPrice: ctx.leastCost.preferCatalogPrice,
+        flightRecorder: ctx.flightRecorder,
+        priorsScope: ctx.leastCost.priorsScope,
+        ownerPrincipal: resolveOwnerPrincipal(getRequestContext()),
+    });
+    const config = toRouterConfig(ctx.leastCost);
+    const req = { prompt };
+    if (singleProvider || mode === "cheapest") {
+        const decision = selectCandidate(req, env, config);
+        if (!decision.chosen)
+            return { ok: false, error: selectorFailureMessage(decision) };
+        return { ok: true, providers: [decision.chosen.provider] };
+    }
+    const decisions = selectCheapestPerTier(req, env, config);
+    const seen = new Set();
+    const providers = [];
+    for (const decision of decisions) {
+        if (!decision.chosen || seen.has(decision.chosen.provider))
+            continue;
+        seen.add(decision.chosen.provider);
+        providers.push(decision.chosen.provider);
+    }
+    if (providers.length === 0) {
+        return {
+            ok: false,
+            error: "least-cost routing found no eligible provider for select='cheapest_per_tier' (fail closed).",
+        };
+    }
+    return { ok: true, providers };
+}
 export function buildValidationSchemas(deps) {
     const apiNames = (deps.apiProviders ?? []).map(p => p.name);
     const allowed = [...CLI_TYPES, ...apiNames];
@@ -57,6 +111,13 @@ function findHumanReadableReport(value) {
 }
 export function registerValidationTools(server, deps) {
     const { providerSchema, providerListSchema, normalizedProviderResultSchema } = buildValidationSchemas(deps);
+    const selectionContext = {
+        asyncJobManager: deps.asyncJobManager,
+        apiProviders: deps.apiProviders ?? [],
+        leastCost: deps.leastCost ?? loadLeastCostConfig(),
+        performanceMetrics: deps.performanceMetrics ?? new PerformanceMetrics(),
+        flightRecorder: deps.flightRecorder,
+    };
     server.tool("validate_with_models", "Ask two or more provider CLIs to independently validate a question. Starts validation jobs — poll with job_status, collect with job_result (not llm_job_*).", {
         question: z.string().min(1).describe("Question or content to validate."),
         models: providerListSchema.describe("Providers to ask. Defaults to Claude and Codex."),
@@ -67,45 +128,71 @@ export function registerValidationTools(server, deps) {
         judgeModel: providerSchema
             .optional()
             .describe("Optional provider to run an explicit judge synthesis job."),
+        select: selectSchema,
     }, {
         title: "Multi-model validation",
         readOnlyHint: false,
         destructiveHint: true,
         idempotentHint: false,
         openWorldHint: true,
-    }, async ({ question, models, focus, judgeModel }) => textResponse({
-        success: true,
-        tool: "validate_with_models",
-        readMostly: true,
-        report: startValidationRun(deps, {
-            intent: "validate",
-            question,
-            providers: models,
-            focus,
-            judgeProvider: judgeModel,
-        }),
-    }));
+    }, async ({ question, models, focus, judgeModel, select }) => {
+        let providers = models;
+        if (select) {
+            const resolved = resolveSelectedProviders(selectionContext, question, select, false);
+            if (!resolved.ok) {
+                return textResponse({
+                    success: false,
+                    tool: "validate_with_models",
+                    error: resolved.error,
+                });
+            }
+            providers = resolved.providers;
+        }
+        return textResponse({
+            success: true,
+            tool: "validate_with_models",
+            readMostly: true,
+            report: startValidationRun(deps, {
+                intent: "validate",
+                question,
+                providers,
+                focus,
+                judgeProvider: judgeModel,
+            }),
+        });
+    });
     server.tool("second_opinion", "Ask one provider CLI to review an answer (starts a validation job; poll job_status, collect job_result).", {
         answer: z.string().min(1).describe("Answer to review."),
         question: z.string().optional().describe("Original question, if available."),
         model: providerSchema.default("codex").describe("Provider to ask for the second opinion."),
+        select: selectSchema,
     }, {
         title: "Second opinion",
         readOnlyHint: false,
         destructiveHint: true,
         idempotentHint: false,
         openWorldHint: true,
-    }, async ({ answer, question, model }) => textResponse({
-        success: true,
-        tool: "second_opinion",
-        readMostly: true,
-        report: startValidationRun(deps, {
-            intent: "second_opinion",
-            question,
-            content: answer,
-            providers: [model],
-        }),
-    }));
+    }, async ({ answer, question, model, select }) => {
+        let providers = [model];
+        if (select) {
+            const resolved = resolveSelectedProviders(selectionContext, answer, select, true);
+            if (!resolved.ok) {
+                return textResponse({ success: false, tool: "second_opinion", error: resolved.error });
+            }
+            providers = resolved.providers;
+        }
+        return textResponse({
+            success: true,
+            tool: "second_opinion",
+            readMostly: true,
+            report: startValidationRun(deps, {
+                intent: "second_opinion",
+                question,
+                content: answer,
+                providers,
+            }),
+        });
+    });
     server.tool("compare_answers", "Summarize agreement/differences between caller-provided answers LOCALLY — does not call any provider.", {
         question: z.string().min(1).describe("Question the answers respond to."),
         answers: z.array(z.string().min(1)).min(2).describe("Two or more answers to compare."),
@@ -134,61 +221,94 @@ export function registerValidationTools(server, deps) {
             .default("normal")
             .describe("How aggressively to review."),
         models: providerListSchema.describe("Providers to ask for adversarial review."),
+        select: selectSchema,
     }, {
         title: "Red-team review",
         readOnlyHint: false,
         destructiveHint: true,
         idempotentHint: false,
         openWorldHint: true,
-    }, async ({ content, riskLevel, models }) => textResponse({
-        success: true,
-        tool: "red_team_review",
-        readMostly: true,
-        report: startValidationRun(deps, {
-            intent: "red_team",
-            content,
-            providers: models,
-            riskLevel,
-        }),
-    }));
+    }, async ({ content, riskLevel, models, select }) => {
+        let providers = models;
+        if (select) {
+            const resolved = resolveSelectedProviders(selectionContext, content, select, false);
+            if (!resolved.ok) {
+                return textResponse({ success: false, tool: "red_team_review", error: resolved.error });
+            }
+            providers = resolved.providers;
+        }
+        return textResponse({
+            success: true,
+            tool: "red_team_review",
+            readMostly: true,
+            report: startValidationRun(deps, {
+                intent: "red_team",
+                content,
+                providers,
+                riskLevel,
+            }),
+        });
+    });
     server.tool("consensus_check", "Ask provider CLIs whether they agree or disagree with a claim (starts validation jobs).", {
         claim: z.string().min(1).describe("Claim to check across providers."),
         models: providerListSchema.describe("Providers to ask for agreement or disagreement."),
+        select: selectSchema,
     }, {
         title: "Consensus check",
         readOnlyHint: false,
         destructiveHint: true,
         idempotentHint: false,
         openWorldHint: true,
-    }, async ({ claim, models }) => textResponse({
-        success: true,
-        tool: "consensus_check",
-        readMostly: true,
-        report: startValidationRun(deps, {
-            intent: "consensus",
-            content: claim,
-            providers: models,
-        }),
-    }));
+    }, async ({ claim, models, select }) => {
+        let providers = models;
+        if (select) {
+            const resolved = resolveSelectedProviders(selectionContext, claim, select, false);
+            if (!resolved.ok) {
+                return textResponse({ success: false, tool: "consensus_check", error: resolved.error });
+            }
+            providers = resolved.providers;
+        }
+        return textResponse({
+            success: true,
+            tool: "consensus_check",
+            readMostly: true,
+            report: startValidationRun(deps, {
+                intent: "consensus",
+                content: claim,
+                providers,
+            }),
+        });
+    });
     server.tool("ask_model", "Ask one provider CLI a question through the simplified validation surface (starts a validation job).", {
         question: z.string().min(1).describe("Question for one provider."),
         model: providerSchema.default("claude").describe("Provider to ask."),
+        select: selectSchema,
     }, {
         title: "Ask one model",
         readOnlyHint: false,
         destructiveHint: true,
         idempotentHint: false,
         openWorldHint: true,
-    }, async ({ question, model }) => textResponse({
-        success: true,
-        tool: "ask_model",
-        readMostly: true,
-        report: startValidationRun(deps, {
-            intent: "ask_model",
-            question,
-            providers: [model],
-        }),
-    }));
+    }, async ({ question, model, select }) => {
+        let providers = [model];
+        if (select) {
+            const resolved = resolveSelectedProviders(selectionContext, question, select, true);
+            if (!resolved.ok) {
+                return textResponse({ success: false, tool: "ask_model", error: resolved.error });
+            }
+            providers = resolved.providers;
+        }
+        return textResponse({
+            success: true,
+            tool: "ask_model",
+            readMostly: true,
+            report: startValidationRun(deps, {
+                intent: "ask_model",
+                question,
+                providers,
+            }),
+        });
+    });
     server.tool("synthesize_validation", "Run an explicit judge model over already-collected validation results to produce a synthesis.", {
         question: z.string().min(1).describe("Original request that was validated."),
         providerResults: z

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "llm-cli-gateway",
-  "version": "2.16.0",
+  "version": "2.17.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "llm-cli-gateway",
-      "version": "2.16.0",
+      "version": "2.17.0",
       "license": "MIT",
       "dependencies": {
         "@modelcontextprotocol/sdk": "^1.29.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llm-cli-gateway",
-  "version": "2.16.0",
+  "version": "2.17.0",
   "mcpName": "io.github.verivus-oss/llm-cli-gateway",
   "description": "Secure local control plane for AI coding agents across supported MCP clients, with workspace-scoped remote access, approval gates, durable jobs, sessions, and audit receipts.",
   "license": "MIT",
@@ -60,7 +60,8 @@
     ".agents/skills/secure-orchestration/SKILL.md",
     ".agents/skills/implement-review-fix/SKILL.md",
     ".agents/skills/retrospective-walk/SKILL.md",
-    ".agents/skills/public-demo-session/SKILL.md"
+    ".agents/skills/public-demo-session/SKILL.md",
+    ".agents/skills/least-cost-routing/SKILL.md"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
@@ -88,8 +89,12 @@
     "site:generate": "node scripts/generate-site-discovery.mjs",
     "site:generate:check": "node scripts/generate-site-discovery.mjs --check",
     "site:validate": "node scripts/validate-site-discovery.mjs",
-    "lint": "eslint src/**/*.ts",
-    "lint:fix": "eslint src/**/*.ts --fix",
+    "supply-chain:scan": "node scripts/supply-chain/dep-drift-scan.mjs --advisory",
+    "supply-chain:scan:check": "node scripts/supply-chain/dep-drift-scan.mjs --frozen",
+    "supply-chain:seed": "node scripts/supply-chain/dep-drift-scan.mjs --seed",
+    "test:supply-chain": "vitest run scripts/supply-chain/dep-drift-scan.test.mjs",
+    "lint": "eslint src --ignore-pattern 'src/__tests__/**'",
+    "lint:fix": "eslint src --ignore-pattern 'src/__tests__/**' --fix",
     "format": "prettier --write 'src/**/*.ts'",
     "format:check": "prettier --check 'src/**/*.ts'",
     "security:audit": "bash scripts/release-security-audit.sh",

package/setup/status.schema.json

@@ -18,6 +18,7 @@
     "client_config",
     "cache_awareness",
     "provider_capabilities",
+    "least_cost",
     "upstream",
     "next_actions"
   ],
@@ -480,6 +481,73 @@
       },
       "additionalProperties": false
     },
+    "least_cost": {
+      "type": "object",
+      "description": "LCR phase_3: least-cost-routing eligibility summary. Economics-only and secret-free (model names, pricing families, price provenance, tiers, telemetry tiers, price-table staleness, anonymized calibration buckets). ALWAYS present; compact (empty arrays) when routing is disabled.",
+      "required": ["enabled", "pricing", "providers", "untieredModels", "calibrationQuality"],
+      "properties": {
+        "enabled": { "type": "boolean" },
+        "pricing": {
+          "type": "object",
+          "required": ["tableAsOf", "apiCatalogAsOf", "staleDays"],
+          "properties": {
+            "tableAsOf": { "type": "string" },
+            "apiCatalogAsOf": { "type": "string" },
+            "staleDays": { "type": "integer", "minimum": 0 }
+          },
+          "additionalProperties": false
+        },
+        "providers": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["provider", "telemetryTier", "candidates"],
+            "properties": {
+              "provider": { "type": "string" },
+              "telemetryTier": { "enum": ["T1", "T2", "T3", "T4"] },
+              "candidates": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "required": ["model", "family", "priced", "priceSource", "tier"],
+                  "properties": {
+                    "model": { "type": "string" },
+                    "family": { "type": "string" },
+                    "priced": { "type": "boolean" },
+                    "priceSource": { "enum": ["table", "api-catalog", "unknown"] },
+                    "tier": {
+                      "type": ["string", "null"],
+                      "enum": ["economy", "standard", "frontier", null]
+                    }
+                  },
+                  "additionalProperties": false
+                }
+              }
+            },
+            "additionalProperties": false
+          }
+        },
+        "untieredModels": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "calibrationQuality": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["bucket", "k", "samples", "confidence"],
+            "properties": {
+              "bucket": { "type": "string" },
+              "k": { "type": "number" },
+              "samples": { "type": "integer", "minimum": 0 },
+              "confidence": { "enum": ["high", "medium", "low"] }
+            },
+            "additionalProperties": false
+          }
+        }
+      },
+      "additionalProperties": false
+    },
     "api_providers": {
       "type": "object",
       "description": "Slice 6: health of enabled [providers.<name>] (kind:api) providers. OMITTED entirely when none are enabled (dormant byte-identical).",