Agent Cost Router

Type: CLI / MCP Server / Local HTTP Dashboard

Value: Routes each agent subtask to the cheapest capable model tier while respecting quality needs and budget caps.

Current Status

Complete as a local CLI / MCP / HTTP dashboard slice. It supports deterministic routing from the built-in catalog, optional OpenRouter model sync, local history, and budget summaries.

Implemented Local Slice

• Task complexity scorer
• Routing policy for low, medium, and high complexity work
• Budget cap and per-run cost estimate
• CLI dry-run and run commands
• MCP tools for route, run, list models, sync models, estimate cost, route history, and budget summary
• Local HTTP API and dashboard
• Persistent routing history, budget ledger, and savings audit log
• Static model catalog with optional OpenRouter model sync

Commands

npm install
npm run build
npm test

agent-cost-router route --prompt "Summarize this briefly"
agent-cost-router run --prompt "Summarize this briefly" --provider openrouter
agent-cost-router models list
agent-cost-router models sync
agent-cost-router history list --project demo
agent-cost-router budget summary --project demo --budget-id may
agent-cost-router serve --port 4317

The dashboard is available at http://127.0.0.1:4317/dashboard after agent-cost-router serve.

Local API

The HTTP server binds to 127.0.0.1 by default.

• GET /health or GET /api/status
• GET /api/models?tier=&provider=&free_only=
• POST /api/route
• POST /api/estimate
• POST /api/models/sync
• GET /api/history?project=&budget_id=&limit=
• GET /api/budget?project=&budget_id=

POST /api/route accepts prompt, provider, budget_mode, max_cost_usd, requires_tools, requires_vision, min_context_window, force_model, force_tier, allow_free, project, budget_id, and record_history.

History Store

Route and run decisions are persisted to ~/.agent-cost-router-history.json by default. Override with AGENT_COST_ROUTER_HISTORY_PATH or AGENT_COST_ROUTER_HISTORY_STORE.

The store records sanitized prompt previews and SHA-256 prompt hashes, not full prompts. It also records source, project, budget id, model, provider, tier, complexity, estimated cost, actual cost when known, savings, and alternatives considered.

Current Guardrails

• Hard provider, budget, allowed-model, context-window, and forced-model constraints fail closed when no capable model matches.
• allowFree: false excludes free models instead of only changing sort order.
• Dry-run and run paths share the same merged static/live model catalog.
• models list works with the built-in catalog even without OPENROUTER_API_KEY.
• MCP JSON-RPC envelopes and tool calls are validated. Bad envelopes return -32600; bad tool params return -32602.
• History stores prompt hashes and truncated previews instead of full prompts.

Current Limits

• This is a local product, not a hosted multi-user SaaS service.
• No public npm publication, hosted account system, billing, team workspace, or live checkout is included.
• Model pricing is only as fresh as the static catalog or the last OpenRouter sync.
• Actual provider execution requires the relevant API key.
• The dashboard can route and report history/budgets locally; provider-backed execution still happens through CLI/MCP/SDK.

Verification

Fresh suite verification on 2026-05-28:

• npm test passed, 28/28 tests.
• npm run build passed.