@ast-ai-model-router/cli 0.1.1 → 1.0.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ast-ai-model-router",
-  "version": "0.1.0",
-  "description": "AST-aware Claude and Codex model routing for cost-conscious coding tasks.",
+  "version": "1.0.0",
+  "description": "AST-based Claude Code and Codex model routing with token-cost estimates and CI policy checks.",
   "author": {
     "name": "Faraazuddin Mohammed",
     "email": "opensource@faraa2m.dev",
@@ -11,11 +11,14 @@
   "repository": "https://github.com/faraa2m/ast-ai-model-router",
   "license": "MIT",
   "keywords": [
+    "ai-coding-agent",
     "token-economics",
+    "llm-cost-optimization",
     "model-router",
     "claude-code",
     "codex",
-    "ast"
+    "ast",
+    "ci"
   ],
   "skills": "./skills/"
 }

package/.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ast-ai-model-router",
-  "version": "0.1.0",
-  "description": "AST-aware Claude and Codex model routing for cost-conscious coding tasks.",
+  "version": "1.0.0",
+  "description": "AST-based Claude Code and Codex model routing with token-cost estimates and CI policy checks.",
   "author": {
     "name": "Faraazuddin Mohammed",
     "email": "opensource@faraa2m.dev",
@@ -11,17 +11,20 @@
   "repository": "https://github.com/faraa2m/ast-ai-model-router",
   "license": "MIT",
   "keywords": [
+    "ai-coding-agent",
     "token-economics",
+    "llm-cost-optimization",
     "model-router",
     "claude-code",
     "codex",
-    "ast"
+    "ast",
+    "ci"
   ],
   "skills": "./skills/",
   "interface": {
     "displayName": "AST AI Model Router",
-    "shortDescription": "Pick Claude or Codex models from AST and task complexity signals.",
-    "longDescription": "AST AI Model Router analyzes JavaScript, TypeScript, and Python project structure plus the current task to choose an appropriate Claude or Codex model before launch. It is part of a token-economics toolkit for measuring, reducing, and routing LLM spend.",
+    "shortDescription": "Pick Claude Code or Codex models from AST, task, cost, and policy signals.",
+    "longDescription": "AST AI Model Router analyzes JavaScript, TypeScript, and Python project structure plus the current task to choose an appropriate Claude Code or Codex model before launch. It adds Tokenometer-backed token-cost estimates, explainable decision records, and CI policy checks for teams. It is part of the faraa2m token-economics toolkit for measuring, reducing, and routing LLM spend.",
     "developerName": "Faraazuddin Mohammed",
     "category": "Developer Tools",
     "capabilities": [

package/README.md

@@ -1,14 +1,23 @@
 # AST AI Model Router
 
-AST-aware model selection for Claude Code and Codex. It inspects the current task, JavaScript/TypeScript ASTs, Python ASTs, and repo shape, then launches the coding agent with a dynamically chosen model.
+[![npm](https://img.shields.io/npm/v/@ast-ai-model-router/cli.svg?label=%40ast-ai-model-router%2Fcli)](https://www.npmjs.com/package/@ast-ai-model-router/cli)
+[![CI](https://github.com/faraa2m/ast-ai-model-router/actions/workflows/ci.yml/badge.svg)](https://github.com/faraa2m/ast-ai-model-router/actions/workflows/ci.yml)
+[![npm smoke](https://github.com/faraa2m/ast-ai-model-router/actions/workflows/npm-smoke.yml/badge.svg)](https://github.com/faraa2m/ast-ai-model-router/actions/workflows/npm-smoke.yml)
+[![License: MIT](https://img.shields.io/github/license/faraa2m/ast-ai-model-router.svg)](LICENSE)
+[![GitHub stars](https://img.shields.io/github/stars/faraa2m/ast-ai-model-router.svg?style=social)](https://github.com/faraa2m/ast-ai-model-router/stargazers)
 
-This project is part of the [`faraa2m`](https://github.com/faraa2m) token economics stack:
+AST-based Claude Code and Codex model router for developers who want explainable AI coding-agent model selection, token-cost visibility, and CI policy checks.
 
-- [`tokenometer`](https://github.com/faraa2m/tokenometer) measures tokens, USD cost, latency, and CI prompt-cost regressions.
-- [`llm-tokens-atlas`](https://github.com/faraa2m/llm-tokens-atlas) calibrates offline tokenizers against empirical provider counts.
-- [`routerlab`](https://github.com/faraa2m/routerlab) builds cost-quality routing frontiers for LLM APIs.
-- [`promptc`](https://github.com/faraa2m/promptc) compiles prompts through deterministic cost-reduction passes.
-- `ast-ai-model-router` brings that cost-aware routing idea into local coding agents.
+`ast-ai-model-router` inspects the current task, JavaScript/TypeScript ASTs, Python ASTs, and repo shape, then recommends or launches Claude Code / Codex with the right model tier. It is deterministic, local-first, and designed for both personal coding workflows and production team guardrails.
+
+## Why Use It
+
+- Avoid defaulting every coding-agent task to the strongest model.
+- Keep simple documentation and explanation tasks on cheaper/faster models.
+- Escalate refactors, migrations, security, auth, database, and architecture work.
+- Get a readable rationale for every model decision.
+- Add CI checks for max model tier and estimated prompt cost.
+- Connect local coding-agent routing to the same token-economics stack as Tokenometer and RouterLab.
 
 ## Install
 
@@ -16,39 +25,78 @@ This project is part of the [`faraa2m`](https://github.com/faraa2m) token econom
 npm install -g @ast-ai-model-router/cli
 ```
 
-For local development:
+Run without installing:
+
+```bash
+npx --yes --package @ast-ai-model-router/cli ast-ai-model-router --help
+```
+
+## Quick Start
+
+Initialize config in a repo:
+
+```bash
+ast-ai-model-router init
+```
+
+Analyze a Claude Code task:
 
 ```bash
-npm install
-npm link
+ast-ai-model-router analyze --agent claude --task "write docs for the parser" 
 ```
 
-## Usage
+Explain the decision:
 
-Analyze a task without launching an agent:
+```bash
+ast-ai-model-router explain --agent codex --task "refactor auth middleware and add regression tests"
+```
+
+Preview a launch command without starting an agent:
 
 ```bash
-ast-ai-model-router analyze --agent codex --task "refactor the auth parser and add tests"
+ast-ai-model-router run codex --task "fix failing Python AST tests" --dry-run -- --cd .
 ```
 
 Launch Codex with the selected model:
 
 ```bash
-ast-ai-model-router run codex --task "fix the failing Python AST tests" -- --cd .
+ast-ai-model-router run codex --task "fix failing Python AST tests" -- --cd .
 ```
 
 Launch Claude Code with the selected alias:
 
 ```bash
-ast-ai-model-router run claude --task "plan a cross-module migration" -- --permission-mode plan
+ast-ai-model-router run claude --task "plan a cross-module database migration" -- --permission-mode plan
+```
+
+## CI And Team Policy
+
+Fail if a task would exceed the allowed tier:
+
+```bash
+ast-ai-model-router ci \
+  --agent claude \
+  --task "plan a production database migration" \
+  --max-tier complex
+```
+
+Fail if Tokenometer can estimate the task prompt above your budget:
+
+```bash
+ast-ai-model-router ci \
+  --agent codex \
+  --task "review this large auth refactor" \
+  --max-cost-usd 0.001
 ```
 
-Machine-readable output:
+Machine-readable decision output:
 
 ```bash
-ast-ai-model-router analyze --agent codex --task "write docs" --json
+ast-ai-model-router analyze --agent codex --task "write tests" --json
 ```
 
+The JSON includes `selectedModel`, `tier`, `confidence`, `signals`, `rationale`, `warnings`, `costEstimate`, `policy`, and `commandPreview`.
+
 ## How Routing Works
 
 The router scores four groups of signals:
@@ -56,20 +104,38 @@ The router scores four groups of signals:
 - Prompt intent: docs, tests, debugging, refactors, architecture, security, migrations.
 - Repo shape: file count, AST file count, package/build/config files.
 - AST complexity: functions, classes, branches, imports, and language mix.
-- Agent model catalog: Codex models are discovered through `codex debug models`; Claude uses dynamic aliases.
+- Agent model catalog: Codex models are discovered through `codex debug models`; Claude Code uses dynamic aliases.
 
-Claude targets are intentionally aliases, not dated model names:
+Claude Code targets are aliases, not dated model names:
 
 - `simple` -> `haiku`
 - `balanced` -> `sonnet`
 - `complex` -> `opus`
 - `planning` -> `opusplan`
 
-Codex targets are selected from the installed Codex model catalog. If discovery fails, the router falls back to configurable defaults in `model-router.config.json`.
+Codex targets are selected from the installed Codex model catalog. If discovery fails, the router falls back to configured defaults.
+
+## Token-Cost Estimates
+
+Cost estimates use [`@tokenometer/core`](https://github.com/faraa2m/tokenometer) when the selected model maps to a known provider model.
+
+Examples:
+
+- Claude alias `haiku` maps to `claude-haiku-4-5`.
+- Claude alias `sonnet` maps to `claude-sonnet-4-6`.
+- Codex `gpt-5.4-mini` maps to Tokenometer model `gpt-5-mini`.
+
+If a model cannot be mapped, routing still works and the decision includes a warning:
+
+```text
+Cost estimate unavailable: No Tokenometer model mapping for codex model "..."
+```
+
+Cost estimates are for the task prompt text, not source-file contents. This keeps the tool privacy-preserving and fast by default.
 
 ## Configuration
 
-Add `model-router.config.json` to a project root:
+`ast-ai-model-router init` writes `model-router.config.json`:
 
 ```json
 {
@@ -86,25 +152,66 @@ Add `model-router.config.json` to a project root:
     }
   },
   "codex": {
-    "discoveryCommand": "codex debug models"
+    "discoveryCommand": "codex debug models",
+    "fallbackModels": {
+      "simple": "gpt-5.4-mini",
+      "balanced": "gpt-5.4",
+      "complex": "gpt-5.5",
+      "planning": "gpt-5.5"
+    }
+  },
+  "policy": {
+    "maxTier": "planning",
+    "maxCostUsd": null
+  },
+  "logging": {
+    "enabled": false,
+    "path": ".model-router/decisions.jsonl"
   }
 }
 ```
 
-## Plugin
+Decision logging is disabled by default. When enabled with config or `--log`, logs store model decisions and scores, not source code.
+
+## Exit Codes
+
+- `0`: success
+- `1`: runtime failure
+- `2`: invalid input or config
+- `3`: policy failure
+
+## Plugin Support
+
+This repo includes:
 
-This repo includes a Codex/Claude plugin manifest at `.codex-plugin/plugin.json` and a skill under `skills/model-router/`.
+- `.codex-plugin/plugin.json`
+- `.claude-plugin/plugin.json`
+- `skills/model-router/SKILL.md`
 
-Use it directly while developing:
+Use the plugin locally:
 
 ```bash
 claude --plugin-dir .
 codex plugin marketplace add .
 ```
 
+## Token Economics Stack
+
+This project is part of the [`faraa2m`](https://github.com/faraa2m) token-economics ecosystem:
+
+- [`tokenometer`](https://github.com/faraa2m/tokenometer): token counts, USD cost, latency benchmarks, and CI prompt-cost guardrails.
+- [`llm-tokens-atlas`](https://github.com/faraa2m/llm-tokens-atlas): empirical tokenizer calibration dataset.
+- [`routerlab`](https://github.com/faraa2m/routerlab): cost-quality routing frontiers for LLM APIs.
+- [`promptc`](https://github.com/faraa2m/promptc): deterministic prompt compiler for cost reduction.
+- `ast-ai-model-router`: model routing for local coding agents.
+
 ## Privacy
 
-The router reads local source files to compute AST complexity and launches the local `claude` or `codex` CLI. It does not add a separate network service. Any model traffic comes from the Claude/Codex CLI you choose to run.
+The router reads local source files to compute AST complexity and launches the local `claude` or `codex` CLI. It does not run a separate network service and does not upload source code. Any model traffic comes from the Claude Code or Codex CLI you choose to run.
+
+## Status
+
+This is an explainable heuristic router. It is production-usable for policy and workflow guardrails, but it does not claim empirically proven model-quality optimization yet. Future releases can add outcome logging and calibration against real task success.
 
 ## License
 

package/bin/ast-ai-model-router.js

@@ -1,25 +1,37 @@
 #!/usr/bin/env node
 import { spawn } from "node:child_process";
+import { access, writeFile } from "node:fs/promises";
+import path from "node:path";
 import { parseArgs } from "node:util";
-import { analyzeTask } from "../lib/analyzer.js";
-import { loadConfig } from "../lib/config.js";
-import { chooseModel } from "../lib/models.js";
+import { CONFIG_TEMPLATE, loadConfig, validateTier } from "../lib/config.js";
+import { createDecision, maybeLogDecision } from "../lib/decision.js";
+import { formatUsd } from "../lib/policy.js";
 
 const HELP = `ast-ai-model-router
 
 Usage:
   ast-ai-model-router analyze --agent claude|codex --task "fix auth bug" [--json]
+  ast-ai-model-router explain --agent claude|codex --task "plan migration" [--json]
+  ast-ai-model-router ci --agent claude|codex --task "deploy change" [--max-tier complex]
   ast-ai-model-router run claude --task "refactor parser" -- [extra claude args]
   ast-ai-model-router run codex --task "write tests" -- [extra codex args]
+  ast-ai-model-router init [--cwd <path>] [--force]
 
 Options:
   --agent <agent>      claude or codex for analyze
   --task <text>        Current task description
   --cwd <path>         Workspace to inspect, defaults to current directory
   --json               Emit machine-readable JSON
+  --max-tier <tier>    Policy ceiling: simple, balanced, complex, planning
+  --max-cost-usd <n>   Policy ceiling when cost estimate is available
+  --log                Append a local JSONL decision record
+  --dry-run            For run: print the command instead of launching
   --refresh-models     Refresh Codex model catalog cache
 `;
 
+const EXIT_INVALID = 2;
+const EXIT_POLICY = 3;
+
 async function main() {
   const [command, maybeAgent, ...rest] = process.argv.slice(2);
   if (!command || command === "--help" || command === "-h") {
@@ -27,7 +39,30 @@ async function main() {
     return;
   }
 
-  if (command === "analyze") {
+  if (command === "init") {
+    const { values } = parseArgs({
+      args: [maybeAgent, ...rest].filter(Boolean),
+      options: {
+        cwd: { type: "string" },
+        force: { type: "boolean" }
+      }
+    });
+    const cwd = path.resolve(values.cwd ?? process.cwd());
+    const configPath = path.join(cwd, "model-router.config.json");
+    if (!values.force) {
+      try {
+        await access(configPath);
+        throw new Error(`model-router.config.json already exists at ${configPath}. Use --force to replace it.`);
+      } catch (error) {
+        if (error.code !== "ENOENT") throw error;
+      }
+    }
+    await writeFile(configPath, `${JSON.stringify(CONFIG_TEMPLATE, null, 2)}\n`, "utf8");
+    process.stdout.write(`Wrote ${configPath}\n`);
+    return;
+  }
+
+  if (command === "analyze" || command === "explain" || command === "ci") {
     const { values } = parseArgs({
       args: [maybeAgent, ...rest].filter(Boolean),
       options: {
@@ -35,11 +70,24 @@ async function main() {
         task: { type: "string" },
         cwd: { type: "string" },
         json: { type: "boolean" },
+        log: { type: "boolean" },
+        "max-tier": { type: "string" },
+        "max-cost-usd": { type: "string" },
         "refresh-models": { type: "boolean" }
       }
     });
     const agent = assertAgent(values.agent);
-    const result = await route({ agent, task: values.task, cwd: values.cwd, refreshModels: values["refresh-models"] });
+    const result = await routeFromValues({ agent, values });
+    if (values.log) await maybeLogDecision(result, await loadConfig(values.cwd ?? process.cwd()), true);
+    if (command === "explain") {
+      printExplanation(result, Boolean(values.json));
+      return;
+    }
+    if (command === "ci") {
+      printCi(result, Boolean(values.json));
+      if (!result.policy.passed) process.exit(EXIT_POLICY);
+      return;
+    }
     printResult(result, Boolean(values.json));
     return;
   }
@@ -54,12 +102,25 @@ async function main() {
       options: {
         task: { type: "string" },
         cwd: { type: "string" },
+        log: { type: "boolean" },
+        "max-tier": { type: "string" },
+        "max-cost-usd": { type: "string" },
+        "dry-run": { type: "boolean" },
         "refresh-models": { type: "boolean" }
       }
     });
-    const result = await route({ agent, task: values.task, cwd: values.cwd, refreshModels: values["refresh-models"] });
+    const result = await routeFromValues({ agent, values });
+    if (values.log) await maybeLogDecision(result, await loadConfig(values.cwd ?? process.cwd()), true);
+    if (!result.policy.passed) {
+      process.stderr.write(`[model-router] policy failed: ${result.policy.failures.join("; ")}\n`);
+      process.exit(EXIT_POLICY);
+    }
     const executable = agent === "claude" ? "claude" : "codex";
     const args = ["--model", result.selectedModel, ...passthrough];
+    if (values["dry-run"]) {
+      process.stdout.write(`${executable} ${args.map(shellQuote).join(" ")}\n`);
+      return;
+    }
     process.stderr.write(`[model-router] ${agent}: ${result.selectedModel} (${result.tier}, confidence ${result.confidence.toFixed(2)})\n`);
     const child = spawn(executable, args, { cwd: result.cwd, stdio: "inherit" });
     child.on("exit", (code, signal) => {
@@ -79,20 +140,19 @@ async function main() {
   throw new Error(`Unknown command: ${command}`);
 }
 
-async function route({ agent, task, cwd, refreshModels }) {
-  const config = await loadConfig(cwd ?? process.cwd());
-  const analysis = await analyzeTask({ cwd: cwd ?? process.cwd(), task: task ?? "", config });
-  const model = await chooseModel({ agent, tier: analysis.tier, task: task ?? "", config, refreshModels: Boolean(refreshModels) });
-  return {
+async function routeFromValues({ agent, values }) {
+  const maxTier = values["max-tier"] ? validateTier(values["max-tier"], "--max-tier") : undefined;
+  const maxCostUsd = parseOptionalNumber(values["max-cost-usd"], "--max-cost-usd");
+  const config = await loadConfig(values.cwd ?? process.cwd());
+  return createDecision({
     agent,
-    cwd: analysis.cwd,
-    selectedModel: model.model,
-    tier: analysis.tier,
-    confidence: analysis.confidence,
-    signals: analysis.signals,
-    modelSource: model.source,
-    commandPreview: `${agent} --model ${model.model}`
-  };
+    task: values.task ?? "",
+    cwd: values.cwd ?? process.cwd(),
+    config,
+    refreshModels: Boolean(values["refresh-models"]),
+    maxTier,
+    maxCostUsd
+  });
 }
 
 function assertAgent(agent) {
@@ -110,10 +170,56 @@ function printResult(result, asJson) {
   process.stdout.write(`Tier: ${result.tier}\n`);
   process.stdout.write(`Confidence: ${result.confidence.toFixed(2)}\n`);
   process.stdout.write(`Signals: ${result.signals.map((signal) => `${signal.name}=${signal.value}`).join(", ")}\n`);
+  process.stdout.write(`Cost: ${formatCost(result.costEstimate)}\n`);
+  if (result.warnings.length) process.stdout.write(`Warnings: ${result.warnings.join(" ")}\n`);
+  process.stdout.write(`Why: ${result.rationale[0]}\n`);
   process.stdout.write(`Run: ${result.commandPreview}\n`);
 }
 
+function printExplanation(result, asJson) {
+  if (asJson) {
+    process.stdout.write(`${JSON.stringify({ ...result, explanation: result.rationale }, null, 2)}\n`);
+    return;
+  }
+  printResult(result, false);
+  process.stdout.write("\nExplanation:\n");
+  for (const line of result.rationale) process.stdout.write(`- ${line}\n`);
+  process.stdout.write("\nSignal details:\n");
+  for (const signal of result.signals) {
+    process.stdout.write(`- ${signal.name}: ${signal.value} (${signal.detail})\n`);
+  }
+}
+
+function printCi(result, asJson) {
+  if (asJson) {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    return;
+  }
+  process.stdout.write(result.policy.passed ? "model-router ci: passed\n" : "model-router ci: failed\n");
+  printResult(result, false);
+  if (!result.policy.passed) {
+    for (const failure of result.policy.failures) process.stdout.write(`Policy failure: ${failure}\n`);
+  }
+}
+
+function formatCost(costEstimate) {
+  if (!costEstimate?.available) return `unavailable (${costEstimate?.reason ?? "unknown"})`;
+  return `${costEstimate.inputTokens} input tokens, ${formatUsd(costEstimate.inputCostUsd)} (${costEstimate.model})`;
+}
+
+function parseOptionalNumber(raw, field) {
+  if (raw === undefined || raw === null) return undefined;
+  const value = Number(raw);
+  if (!Number.isFinite(value) || value < 0) throw new Error(`${field} must be a non-negative number`);
+  return value;
+}
+
+function shellQuote(value) {
+  if (/^[A-Za-z0-9_./:=@-]+$/.test(value)) return value;
+  return `'${value.replaceAll("'", "'\\''")}'`;
+}
+
 main().catch((error) => {
   process.stderr.write(`[model-router] ${error.message}\n`);
-  process.exit(1);
+  process.exit(error.message.includes("must be") || error.message.includes("Expected") ? EXIT_INVALID : 1);
 });

package/lib/analyzer.js

@@ -100,6 +100,9 @@ function scoreRepo(files, astFiles) {
 }
 
 function tierFor(score, task, config) {
+  if (/explain|summarize|readme|docs|comment/i.test(task) && !/architecture|migration|security|auth|database|billing|payment|production|deploy/i.test(task) && score <= config.thresholds.balancedMax) {
+    return "simple";
+  }
   if (/plan|architecture|migration|strategy/i.test(task) && score >= config.thresholds.simpleMax) return "planning";
   if (score <= config.thresholds.simpleMax) return "simple";
   if (score <= config.thresholds.balancedMax) return "balanced";

package/lib/config.js

@@ -23,6 +23,41 @@ export const DEFAULT_CONFIG = {
       planning: "gpt-5.5"
     }
   },
+  modelMappings: {
+    claude: {
+      haiku: "claude-haiku-4-5",
+      sonnet: "claude-sonnet-4-6",
+      opus: "claude-opus-4-7",
+      opusplan: "claude-opus-4-7"
+    },
+    codex: {
+      "gpt-5.4-mini": "gpt-5-mini",
+      "gpt-5.4": "gpt-5",
+      "gpt-5.5": "gpt-5",
+      "codex-mini-latest": "codex-mini-latest"
+    }
+  },
+  policy: {
+    maxTier: "planning",
+    maxCostUsd: null
+  },
+  logging: {
+    enabled: false,
+    path: ".model-router/decisions.jsonl"
+  },
+  overrides: []
+};
+
+export const CONFIG_TEMPLATE = {
+  thresholds: DEFAULT_CONFIG.thresholds,
+  claude: DEFAULT_CONFIG.claude,
+  codex: DEFAULT_CONFIG.codex,
+  modelMappings: DEFAULT_CONFIG.modelMappings,
+  policy: {
+    maxTier: "planning",
+    maxCostUsd: null
+  },
+  logging: DEFAULT_CONFIG.logging,
   overrides: []
 };
 
@@ -52,6 +87,17 @@ function mergeConfig(base, override) {
       ...override.codex,
       fallbackModels: { ...base.codex.fallbackModels, ...override.codex?.fallbackModels }
     },
+    modelMappings: {
+      claude: { ...base.modelMappings.claude, ...override.modelMappings?.claude },
+      codex: { ...base.modelMappings.codex, ...override.modelMappings?.codex }
+    },
+    policy: { ...base.policy, ...override.policy },
+    logging: { ...base.logging, ...override.logging },
     overrides: override.overrides ?? base.overrides
   };
 }
+
+export function validateTier(tier, field = "tier") {
+  if (["simple", "balanced", "complex", "planning"].includes(tier)) return tier;
+  throw new Error(`${field} must be one of: simple, balanced, complex, planning`);
+}

package/lib/cost.js

@@ -0,0 +1,47 @@
+import { tokenize } from "@tokenometer/core";
+
+export function estimateCost({ agent, selectedModel, task, config }) {
+  const mappedModel = config.modelMappings?.[agent]?.[selectedModel];
+  if (!task?.trim()) {
+    return unavailable("No task text was provided, so there is no prompt to estimate.");
+  }
+  if (!mappedModel) {
+    return unavailable(`No Tokenometer model mapping for ${agent} model "${selectedModel}".`);
+  }
+  try {
+    const result = tokenize({
+      format: "text",
+      modelId: mappedModel,
+      prompt: task
+    });
+    return {
+      available: true,
+      scope: "task",
+      source: "tokenometer",
+      model: mappedModel,
+      inputTokens: result.inputTokens,
+      inputCostUsd: result.inputCost,
+      approximate: result.approximate,
+      tokenizer: result.tokenizer,
+      reason: result.approximate
+        ? "Estimated from Tokenometer offline/proxy tokenizer."
+        : "Estimated from Tokenometer exact offline tokenizer."
+    };
+  } catch (error) {
+    return unavailable(error instanceof Error ? error.message : String(error), mappedModel);
+  }
+}
+
+function unavailable(reason, model = null) {
+  return {
+    available: false,
+    scope: "task",
+    source: "tokenometer",
+    model,
+    inputTokens: null,
+    inputCostUsd: null,
+    approximate: null,
+    tokenizer: null,
+    reason
+  };
+}

package/lib/decision.js

@@ -0,0 +1,68 @@
+import { appendFile, mkdir } from "node:fs/promises";
+import path from "node:path";
+import { analyzeTask } from "./analyzer.js";
+import { estimateCost } from "./cost.js";
+import { chooseModel } from "./models.js";
+import { evaluatePolicy } from "./policy.js";
+
+export async function createDecision({ agent, task, cwd, config, refreshModels = false, maxTier, maxCostUsd }) {
+  const analysis = await analyzeTask({ cwd, task, config });
+  const model = await chooseModel({ agent, tier: analysis.tier, task, config, refreshModels });
+  const costEstimate = estimateCost({ agent, selectedModel: model.model, task, config });
+  const policy = evaluatePolicy({ tier: analysis.tier, costEstimate, config, maxTier, maxCostUsd });
+  const warnings = [];
+  if (model.source === "fallback") warnings.push("Codex model discovery failed; using configured fallback model.");
+  if (!costEstimate.available) warnings.push(`Cost estimate unavailable: ${costEstimate.reason}`);
+  if (!policy.passed) warnings.push(`Policy failed: ${policy.failures.join("; ")}`);
+  const rationale = buildRationale({ analysis, model, costEstimate, policy });
+  return {
+    agent,
+    cwd: analysis.cwd,
+    selectedModel: model.model,
+    tier: analysis.tier,
+    confidence: analysis.confidence,
+    score: analysis.score,
+    signals: analysis.signals,
+    rationale,
+    warnings,
+    costEstimate,
+    policy,
+    modelSource: model.source,
+    commandPreview: `${agent} --model ${model.model}`
+  };
+}
+
+export async function maybeLogDecision(decision, config, explicitLog = false) {
+  if (!explicitLog && !config.logging?.enabled) return;
+  const logPath = path.resolve(decision.cwd, config.logging?.path ?? ".model-router/decisions.jsonl");
+  await mkdir(path.dirname(logPath), { recursive: true });
+  const record = {
+    timestamp: new Date().toISOString(),
+    agent: decision.agent,
+    selectedModel: decision.selectedModel,
+    tier: decision.tier,
+    confidence: decision.confidence,
+    score: decision.score,
+    costEstimate: decision.costEstimate,
+    policy: decision.policy,
+    signals: decision.signals
+  };
+  await appendFile(logPath, `${JSON.stringify(record)}\n`, "utf8");
+}
+
+function buildRationale({ analysis, model, costEstimate, policy }) {
+  const sorted = [...analysis.signals].sort((a, b) => Number(b.value) - Number(a.value));
+  const top = sorted.slice(0, 3).map((signal) => `${signal.name}=${signal.value} (${signal.detail})`);
+  const lines = [
+    `Selected ${model.model} because the task scored as ${analysis.tier} complexity.`,
+    `Top signals: ${top.join("; ")}.`,
+    `Model source: ${model.source}.`
+  ];
+  if (costEstimate.available) {
+    lines.push(`Estimated task prompt cost: ${costEstimate.inputTokens} input tokens, ${costEstimate.inputCostUsd.toFixed(6)} USD (${costEstimate.model}).`);
+  } else {
+    lines.push(`Cost estimate unavailable: ${costEstimate.reason}`);
+  }
+  lines.push(policy.passed ? "Policy: passed." : `Policy: failed (${policy.failures.join("; ")}).`);
+  return lines;
+}

package/lib/policy.js

@@ -0,0 +1,35 @@
+export const TIER_ORDER = {
+  simple: 0,
+  balanced: 1,
+  complex: 2,
+  planning: 3
+};
+
+export function evaluatePolicy({ tier, costEstimate, config, maxTier, maxCostUsd }) {
+  const effectiveMaxTier = maxTier ?? config.policy?.maxTier ?? "planning";
+  const effectiveMaxCostUsd = maxCostUsd ?? config.policy?.maxCostUsd ?? null;
+  const failures = [];
+  if (TIER_ORDER[tier] > TIER_ORDER[effectiveMaxTier]) {
+    failures.push(`tier ${tier} exceeds max tier ${effectiveMaxTier}`);
+  }
+  if (
+    effectiveMaxCostUsd !== null &&
+    effectiveMaxCostUsd !== undefined &&
+    costEstimate?.available &&
+    costEstimate.inputCostUsd > Number(effectiveMaxCostUsd)
+  ) {
+    failures.push(`estimated cost ${formatUsd(costEstimate.inputCostUsd)} exceeds max cost ${formatUsd(Number(effectiveMaxCostUsd))}`);
+  }
+  return {
+    passed: failures.length === 0,
+    failures,
+    maxTier: effectiveMaxTier,
+    maxCostUsd: effectiveMaxCostUsd
+  };
+}
+
+export function formatUsd(value) {
+  if (!Number.isFinite(value)) return "unavailable";
+  if (value === 0) return "$0.000000";
+  return `$${value.toFixed(6)}`;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ast-ai-model-router/cli",
-  "version": "0.1.1",
-  "description": "AST-aware Claude and Codex model router for cost-conscious coding tasks.",
+  "version": "1.0.0",
+  "description": "AST-based Claude Code and Codex model router with token-cost estimates, CI policy checks, and explainable AI coding-agent model selection.",
   "type": "module",
   "bin": {
     "ast-ai-model-router": "bin/ast-ai-model-router.js",
@@ -28,12 +28,20 @@
   },
   "keywords": [
     "llm",
+    "ai-coding-agent",
     "token-economics",
+    "llm-cost-optimization",
     "model-router",
+    "model-selection",
     "claude-code",
+    "claude-code-model-router",
     "codex",
+    "codex-cli",
+    "codex-model-router",
     "ast",
-    "prompt-cost"
+    "prompt-cost",
+    "developer-tools",
+    "ci"
   ],
   "author": {
     "name": "Faraazuddin Mohammed",
@@ -51,7 +59,8 @@
     "provenance": true
   },
   "dependencies": {
-    "@babel/parser": "^7.28.5"
+    "@babel/parser": "^7.28.5",
+    "@tokenometer/core": "^1.1.0"
   },
   "devDependencies": {
     "@changesets/cli": "^2.31.0"

package/skills/model-router/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: model-router
-description: Use AST AI Model Router to choose an appropriate Claude or Codex model from task and code complexity before launching or recommending an agent command.
+description: Use AST AI Model Router to choose an appropriate Claude Code or Codex model from task, code complexity, token-cost, and policy signals before launching or recommending an agent command.
 ---
 
 # Model Router
@@ -21,7 +21,19 @@ or:
 ast-ai-model-router analyze --agent claude --task "<task>"
 ```
 
-2. If the user wants execution, launch through the wrapper:
+2. When the user needs rationale, use:
+
+```bash
+ast-ai-model-router explain --agent codex --task "<task>"
+```
+
+3. For CI or production policy checks, use:
+
+```bash
+ast-ai-model-router ci --agent codex --task "<task>" --max-tier complex
+```
+
+4. If the user wants execution, launch through the wrapper:
 
 ```bash
 ast-ai-model-router run codex --task "<task>" -- <codex args>
@@ -31,10 +43,11 @@ ast-ai-model-router run codex --task "<task>" -- <codex args>
 ast-ai-model-router run claude --task "<task>" -- <claude args>
 ```
 
-3. Explain the selected model in token-economics terms: simple tasks should use faster/cheaper models; complex migrations, security-sensitive work, and architecture planning should use stronger models.
+5. Explain the selected model in token-economics terms: simple tasks should use faster/cheaper models; complex migrations, security-sensitive work, and architecture planning should use stronger models.
 
 ## Notes
 
 - Codex model names are discovered dynamically from `codex debug models`.
 - Claude model names use aliases: `haiku`, `sonnet`, `opus`, and `opusplan`.
+- Token-cost estimates use Tokenometer when a selected model maps cleanly to a known provider model.
 - The router analyzes JavaScript/TypeScript with Babel ASTs and Python with stdlib `ast`.