@sriinnu/kosha-discovery 1.2.0 → 1.5.1

package/README.md

@@ -1,19 +1,10 @@
 <p align="center">
-  <img src="logo.png" alt="Kosha — AI Model Discovery" width="140" />
+  <img src="logo.svg" alt="Kosha — AI Model Discovery" width="140" />
 </p>
 
-<h1 align="center">kosha-discovery — कोश</h1>
+# kosha-discovery
 
-<p align="center"><strong>AI Model & Provider Discovery Registry</strong></p>
-
-<p align="center">
-  <a href="https://www.npmjs.com/package/@sriinnu/kosha-discovery"><img src="https://img.shields.io/npm/v/%40sriinnu%2Fkosha-discovery?color=7C3AED&label=npm" alt="npm version" /></a>
-  <a href="https://www.npmjs.com/package/@sriinnu/kosha-discovery"><img src="https://img.shields.io/npm/dm/%40sriinnu%2Fkosha-discovery?color=0EA5E9&label=downloads" alt="npm downloads" /></a>
-  <a href="https://github.com/sriinnu/kosha-discovery/blob/main/LICENSE"><img src="https://img.shields.io/github/license/sriinnu/kosha-discovery?color=F59E0B" alt="license" /></a>
-  <a href="https://www.npmjs.com/package/@sriinnu/kosha-discovery"><img src="https://img.shields.io/node/v/%40sriinnu%2Fkosha-discovery?color=5B21B6" alt="node version" /></a>
-</p>
-
-Kosha (कोश — *treasury*) discovers AI models across providers, resolves credentials, enriches with pricing, and exposes the catalog through a library, CLI, HTTP API, and a built-in OpenAI-compatible proxy. One source of truth for model identity, pricing, and routing — so your app doesn't break when providers ship new SKUs or change rates.
+Model and provider discovery registry for LLM apps. It queries 25 provider APIs and local runtimes for their model lists, resolves credentials from env vars and CLI config files, fills in pricing and context limits from models.dev and LiteLLM, and exposes the result as a TypeScript library, a CLI, an HTTP API, an OpenAI-compatible proxy with cost tracking, and an MCP server.
 
 ## Install
 
@@ -22,6 +13,8 @@ npm install @sriinnu/kosha-discovery       # library / server
 npm install -g @sriinnu/kosha-discovery    # global `kosha` CLI
 ```
 
+Requires Node.js 22+.
+
 ## Quick start
 
 ### Library
@@ -31,24 +24,29 @@ import { createKosha } from "@sriinnu/kosha-discovery";
 
 const kosha = await createKosha();
 
-const models    = kosha.models();                          // all
-const cheapest  = kosha.cheapestModels({ role: "image" }); // ranked
-const sonnet    = kosha.model("sonnet");                   // alias resolves
-console.log(sonnet.pricing); // { inputPerMillion: 3, outputPerMillion: 15, ... }
+const models   = kosha.models();                          // ModelCard[] across every provider
+const cheapest = kosha.cheapestModels({ role: "image" }); // ranked by price, with missingCredentials
+const sonnet   = kosha.model("sonnet");                   // alias → canonical ID; undefined if unknown
+console.log(sonnet?.pricing); // { inputPerMillion: 2, outputPerMillion: 10, cacheReadPerMillion: 0.2, ... }
 ```
 
 ### CLI
 
 ```bash
-kosha discover                       # discover all providers (writes cache + manifest)
-kosha list --provider anthropic      # filter from local cache
-kosha model sonnet                   # details for one model (alias-aware)
-kosha cheapest --role embeddings     # rank cheapest for a role
-kosha update                         # force a fresh fetch
-kosha serve --port 3000              # HTTP API
+kosha discover                       # query every provider; writes ~/.kosha/cache and the manifest
+kosha list --provider anthropic      # read from the local cache
+kosha model sonnet                   # one model, alias-aware
+kosha routes claude-opus-5           # every serving route for a model (direct, OpenRouter, Bedrock, …)
+kosha cheapest --role embeddings     # rank by price for a role
+kosha doctor --ci                    # deprecations + provider health; non-zero exit for CI
+kosha spend --since 2026-09-01       # roll up the proxy's spend ledger
+kosha refresh                        # bypass the cache and re-discover
+kosha serve --port 3000              # HTTP API + proxy; binds 127.0.0.1 (see Proxy below)
 ```
 
-After each discovery, a stable v1 manifest lands at `~/.kosha/registry.json` — any tool that reads JSON can consume it:
+Every command takes `--json`. `kosha --help` lists the rest.
+
+After each discovery, a stable v1 manifest lands at `~/.kosha/registry.json`:
 
 ```bash
 jq '.models[] | select(.pricing.inputPerMillion < 0.1) | .modelId' ~/.kosha/registry.json
@@ -57,15 +55,21 @@ jq '.models[] | select(.pricing.inputPerMillion < 0.1) | .modelId' ~/.kosha/regi
 ### HTTP API
 
 ```
-GET  /api/models[?provider=…&role=…]    GET  /api/models/:idOrAlias
-GET  /api/models/:idOrAlias/routes      GET  /api/models/cheapest?role=…
-GET  /api/providers                     GET  /api/roles
-POST /api/refresh                       GET  /health
+GET  /api/models?provider=&originProvider=&mode=&capability=
+GET  /api/models/:idOrAlias             GET  /api/models/:idOrAlias/routes
+GET  /api/models/cheapest?role=…        GET  /api/capabilities
+GET  /api/providers[/:id]               GET  /api/roles
+GET  /api/resolve/:alias                GET  /api/discovery-errors
+GET  /api/discovery[/delta|/watch|/cheapest|/binding]   (stable v1 contract)
+POST /api/refresh                       GET  /health          GET  /metrics
+GET  /proxy/v1/models                   POST /proxy/v1/chat/completions
 ```
 
+Parameters and response shapes: [docs/api.md](docs/api.md).
+
 ### Proxy
 
-Kosha runs as an OpenAI-compatible proxy. Point your SDK at `http://localhost:3000/proxy/v1` and it resolves the model, picks the right provider, injects credentials, and forwards — streaming included.
+`kosha serve` also exposes an OpenAI-compatible endpoint at `/proxy/v1`. Point any OpenAI SDK at it; the proxy resolves the model or alias, picks a provider you hold credentials for, injects the upstream key, forwards the request, and writes a row to the spend ledger.
 
 ```bash
 kosha serve   # start on :3000
@@ -106,34 +110,104 @@ const routed = await client.chat.completions.create({
 | `<N>k` | `128k`, `200k` | minimum context window |
 | `provider:<id>` | `provider:groq` | pin to a specific provider |
 
-The response always includes `x-kosha-model`, `x-kosha-provider`, and `x-kosha-requested` headers so the caller knows exactly what ran.
+`kosha:fastest`, `kosha:reliable`, and `kosha:balanced` take the same filters and rank on observed latency and circuit-breaker state instead of price.
+
+Every response carries `x-kosha-model`, `x-kosha-provider`, `x-kosha-requested`, `x-kosha-attempt-chain`, and `x-kosha-estimated-cost-usd`; non-streaming responses add `x-kosha-actual-cost-usd` when the upstream returned a usage block.
+
+What the proxy can forward:
+
+| Upstream wire format | Providers | Support |
+|---|---|---|
+| OpenAI-compatible | OpenAI, Ollama, OpenRouter, Vercel, Groq, Together, Fireworks, DeepInfra, … | passthrough, streaming included |
+| Anthropic Messages | Anthropic | translated: streaming, tools, `image_url`, `response_format`, `reasoning_effort`; audio input and non-function tools fail over to an OpenAI-compatible route for the same model |
+| Cloud SDKs | Google, Bedrock, Vertex | discovery only, not proxied yet |
+
+Defaults that matter before you expose it: the server binds `127.0.0.1`. Pass `--host 0.0.0.0` (or `KOSHA_HOST`) to listen on a network interface, and set `KOSHA_PROXY_TOKEN` so `/proxy/*` and `POST /api/refresh` require `Authorization: Bearer <token>` or `x-kosha-token`. `KOSHA_MONTHLY_BUDGET_USD` caps spend per calendar month. Reference: [docs/api.md](docs/api.md#openai-compatible-proxy), [docs/operations.md](docs/operations.md).
+
+### MCP server
+
+`kosha-mcp` serves the registry over the Model Context Protocol on stdio, so an agent can call `kosha_query_models`, `kosha_cheapest_model`, `kosha_ranked_routes`, `kosha_model_detail`, `kosha_model_routes`, `kosha_resolve_alias`, `kosha_provider_health`, and `kosha_context_strategy` without an HTTP server.
+
+```bash
+claude mcp add kosha -- kosha-mcp
+```
 
-Supported transports: `openai`, `openai-compatible-http`, `ollama`. Anthropic, Google, Bedrock, and Vertex require wire-format translation — not yet proxied.
+Tools and protocol details: [docs/mcp.md](docs/mcp.md).
 
 ## Supported providers
 
+25 providers. Each has a discoverer in `src/discovery/` and a credential resolver in `src/credentials/`.
+
 | Provider | Discovery | Credential sources |
 |----------|-----------|--------------------|
-| Anthropic | `/v1/models` | `ANTHROPIC_API_KEY`, Claude CLI, Codex CLI |
-| OpenAI | `/v1/models` | `OPENAI_API_KEY`, GitHub Copilot tokens |
-| Google | `/v1beta/models` | `GOOGLE_API_KEY`, `GEMINI_API_KEY`, Gemini CLI, gcloud |
-| AWS Bedrock | SDK → CLI → static | `AWS_ACCESS_KEY_ID`, `~/.aws/credentials`, SSO, IAM |
+| Anthropic | `GET /v1/models` (context, output cap, capabilities read from the API) | `ANTHROPIC_API_KEY`, Claude CLI, Codex CLI |
+| OpenAI | `GET /v1/models` | `OPENAI_API_KEY`, GitHub Copilot tokens |
+| Google | `GET /v1beta/models` | `GOOGLE_API_KEY`, `GEMINI_API_KEY`, Gemini CLI, gcloud |
+| AWS Bedrock | SDK → CLI → static list | `AWS_ACCESS_KEY_ID`, `~/.aws/credentials`, SSO, IAM |
 | Vertex AI | API + gcloud | `GOOGLE_APPLICATION_CREDENTIALS`, ADC |
-| Ollama | local API | — (local) |
-| OpenRouter | API | `OPENROUTER_API_KEY` *(optional)* |
-| Vercel AI Gateway | `/v1/models` | `AI_GATEWAY_API_KEY`, `VERCEL_OIDC_TOKEN` *(public discovery, required for execution)* |
-| NVIDIA / Together / Fireworks / Groq / Cerebras / Cohere / DeepInfra / Perplexity | API | provider key env var |
-| DeepSeek / Mistral / Moonshot (Kimi) / GLM (Zhipu) / Z.AI / MiniMax | API | provider key env var |
+| Ollama, llama.cpp, LM Studio, vLLM | local HTTP API | none |
+| OpenRouter | API | `OPENROUTER_API_KEY` (optional; unauthenticated is rate-limited) |
+| Vercel AI Gateway | `GET /v1/models` | `AI_GATEWAY_API_KEY`, `VERCEL_OIDC_TOKEN` (discovery works without; execution needs one) |
+| NVIDIA, Together, Fireworks, Groq, Cerebras, Cohere, DeepInfra, Perplexity | OpenAI-compatible API | `<PROVIDER>_API_KEY` |
+| DeepSeek, Mistral, Moonshot (Kimi), GLM (Zhipu), Z.AI, MiniMax | OpenAI-compatible API | `<PROVIDER>_API_KEY` |
 
-Full credential setup: [docs/credentials.md](docs/credentials.md).
+Without a key, direct providers fall back to the public models.dev + LiteLLM catalog, then to a curated static list, so `kosha list` works on a fresh machine. Exact env var names: [docs/credentials.md](docs/credentials.md).
 
-## Architecture
+## How it works
 
-<p align="center">
-  <img src="architecture.svg" alt="Kosha Architecture" width="720" />
-</p>
+1. **Discovery** — one discoverer per provider runs concurrently (`Promise.allSettled`); each returns normalized `ModelCard`s. A failing provider is recorded in `discoveryErrors()` and doesn't block the others.
+2. **Enrichment** — pricing, context window, and output cap are filled from models.dev and LiteLLM where the provider API doesn't publish them; `pricingSource` on each card says which.
+3. **Resilience** — a per-provider circuit breaker with exponential cooldown, plus stale-cache fallback, so a provider outage degrades to cached data rather than an error.
+4. **Cache and manifest** — results are cached under `~/.kosha/cache/` (24 h TTL) and exported as a versioned snapshot at `~/.kosha/registry.json` for other tools to read.
+5. **Proxy** — resolves the requested model or `kosha:<strategy>[filters]` selector against the registry, ranks candidate routes, forwards with failover, and records estimated and reconciled cost in `~/.kosha/ledger-YYYY-MM.jsonl`.
+
+Details: [docs/architecture.md](docs/architecture.md), [docs/resilience.md](docs/resilience.md).
+
+## Development
+
+```bash
+pnpm install
+pnpm run build        # compile to dist/
+pnpm run typecheck    # tsc --noEmit
+pnpm run lint         # biome lint
+pnpm test             # vitest run
+pnpm run check        # lint + build + test
+```
 
-Discovery layer talks to provider APIs and local catalogs. Enrichment layer fills pricing and context windows from the LiteLLM catalog and models.dev. Resilience layer (circuit breaker + stale-cache fallback + health tracker) keeps a flaky provider a degraded read, never a crash. Manifest layer writes a v1-stable JSON snapshot so downstream consumers — `tokmeter`, `chitragupta`, `ayuh` — read prices from one source instead of inventing their own. Proxy layer exposes an OpenAI-compatible endpoint that resolves `kosha:cheapest[…]` hints at request time, injects credentials, and forwards to the winning provider.
+### Project layout
+
+```
+src/
+  cli.ts                 # CLI entry point and arg parsing
+  cli-commands.ts        # command implementations (+ cli-cmd-*.ts for the larger ones)
+  registry.ts            # ModelRegistry public API
+  registry-runtime.ts    # discovery orchestration, enrichment, cache, manifest export
+  registry-query.ts      # model / role / capability queries
+  registry-selection.ts  # cheapest candidates, binding hints
+  registry-routing.ts    # cheapest / fastest / reliable / balanced ranking
+  discovery/             # one discoverer per provider + static and public-seed catalogs
+  enrichment/            # models.dev + LiteLLM pricing enrichment
+  credentials/           # credential resolution (env, CLI files, ADC, OAuth)
+  provider-catalog.ts    # provider descriptors: base URLs, transport, env var names
+  aliases.ts             # built-in short names → canonical model IDs
+  claude-generation.ts   # which Claude generation accepts which API parameters
+  model-features.ts      # tool dialect / structured-output inference per model
+  proxy.ts               # OpenAI-compatible proxy: routing, failover, ledger
+  wire-anthropic.ts      # OpenAI ↔ Anthropic request / response / SSE translation
+  cost.ts                # spend ledger, budget gates, usage reconciliation
+  tally.ts               # zero-dependency token usage + USD tally (also exported as ./tally)
+  server.ts              # Hono HTTP API + operator token gate
+  mcp-server.ts          # MCP stdio server
+  types.ts               # shared types
+```
+
+### Adding a provider
+
+1. Add a descriptor to `PROVIDER_CATALOG` in `src/provider-catalog.ts` (id, base URL, transport, credential env vars).
+2. Create `src/discovery/<provider>.ts` extending `BaseDiscoverer`; `fetchJSON` and `makeCard` are provided.
+3. Export it from `src/discovery/index.ts` and add a factory entry to `DISCOVERER_REGISTRY` in the same file.
+4. If the provider needs more than a single env var, add a resolver branch in `src/credentials/resolver.ts`.
+5. Add `test/discovery/<provider>.test.ts` (mock `fetch`; see `anthropic.test.ts`) and document the env vars in `docs/credentials.md`.
 
 ## Docs
 
@@ -142,26 +216,25 @@ Discovery layer talks to provider APIs and local catalogs. Enrichment layer fill
 | [Credentials](docs/credentials.md) | Env vars, CLI tools, and config files for every provider |
 | [CLI](docs/cli.md) | Commands, flags, examples |
 | [HTTP API](docs/api.md) | Endpoints, parameters, response schemas |
+| [MCP server](docs/mcp.md) | Tools, protocol negotiation, client setup |
 | [Configuration](docs/configuration.md) | Aliases, routing, enrichment, programmatic config |
 | [Architecture](docs/architecture.md) | Discovery flow, module map, adding providers |
 | [Resilience](docs/resilience.md) | Circuit breakers, stale cache, health |
+| [Operations](docs/operations.md) | Deployment sizing, metrics, spend ledger, recovery recipes |
 | [Security](docs/security.md) | Threat catalogue, runtime scanning, pre-commit hook |
 | [Discovery Plane v1](docs/discovery-plane-v1.md) | Stable daemon contract (deltas, SSE watch, binding hints) |
 
 ## Release
 
-Tag-driven via GitHub Actions:
+1. Bump `version` in `package.json` and date the `[Unreleased]` section in `CHANGELOG.md`; merge that as a PR.
+2. Tag and push:
 
 ```bash
 git tag -s vX.Y.Z -m "vX.Y.Z" && git push origin vX.Y.Z
-# → Actions → "Manual Release (Tag + npm)" → run with tag=vX.Y.Z
+gh workflow run release-npm.yml -f tag=vX.Y.Z
 ```
 
-The workflow checks tag ↔ package.json match, builds, tests, publishes to npm, and creates the GitHub Release. Requires the `NPM_TOKEN` secret.
-
-## Credits
-
-[litellm](https://github.com/BerriAI/litellm) (pricing data) · [openrouter](https://openrouter.ai) · [ollama](https://ollama.ai) · [chitragupta](https://github.com/sriinnu/chitragupta) (registry patterns) · [takumi](https://github.com/sriinnu/takumi) (routing needs that drove kosha's creation).
+The workflow checks that the tag matches `package.json`, runs lint / build / test, publishes to npm with provenance, and creates the GitHub Release. Publishing authenticates through npm trusted publishing (OIDC) when a trusted publisher is configured for this repo and workflow on npmjs.com, or through an `NPM_TOKEN` repository secret.
 
 ## License
 

package/dist/aliases.d.ts

@@ -9,7 +9,12 @@
  * Curated default aliases mapping short names to canonical model IDs.
  *
  * These are production-ready and cover the most commonly referenced
- * models across major providers. Updated February 2026.
+ * models across major providers. Updated September 2026.
+ *
+ * Convention: a bare family name (`opus`, `sonnet`, `gemini-pro`) always
+ * tracks the newest generally-available model in that family; a suffixed
+ * form (`opus-4.8`, `sonnet-4`) pins a generation and is kept for
+ * backward compatibility when the bare alias moves on.
  */
 export declare const DEFAULT_ALIASES: Readonly<Record<string, string>>;
 /**

package/dist/aliases.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"aliases.d.ts","sourceRoot":"","sources":["../src/aliases.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,eAAe,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAgD5D,CAAC;AAEF;;;;;GAKG;AACH,qBAAa,aAAa;IACzB,sEAAsE;IACtE,OAAO,CAAC,OAAO,CAAsB;IAErC;;;OAGG;gBACS,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAUlD;;;OAGG;IACH,OAAO,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM;IAIpC;;OAEG;IACH,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE;IAUzC;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAI9C;;OAEG;IACH,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAIhC;;OAEG;IACH,GAAG,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;CAG7B"}
+{"version":3,"file":"aliases.d.ts","sourceRoot":"","sources":["../src/aliases.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,eAAe,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAsE5D,CAAC;AAEF;;;;;GAKG;AACH,qBAAa,aAAa;IACzB,sEAAsE;IACtE,OAAO,CAAC,OAAO,CAAsB;IAErC;;;OAGG;IACH,YAAY,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAQjD;IAED;;;OAGG;IACH,OAAO,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAEnC;IAED;;OAEG;IACH,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAQxC;IAED;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAE7C;IAED;;OAEG;IACH,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAE/B;IAED;;OAEG;IACH,GAAG,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAE5B;CACD"}

package/dist/aliases.js

@@ -9,27 +9,53 @@
  * Curated default aliases mapping short names to canonical model IDs.
  *
  * These are production-ready and cover the most commonly referenced
- * models across major providers. Updated February 2026.
+ * models across major providers. Updated September 2026.
+ *
+ * Convention: a bare family name (`opus`, `sonnet`, `gemini-pro`) always
+ * tracks the newest generally-available model in that family; a suffixed
+ * form (`opus-4.8`, `sonnet-4`) pins a generation and is kept for
+ * backward compatibility when the bare alias moves on.
  */
 export const DEFAULT_ALIASES = {
-    // ── Anthropic — Claude 4.6 family (latest as of Feb 2026) ──
-    "opus": "claude-opus-4-6",
-    "opus-4": "claude-opus-4-6",
-    "sonnet": "claude-sonnet-4-6",
+    // ── Anthropic — Claude 5 family (latest as of Sep 2026) ──
+    // Bare IDs, never date-suffixed: `claude-haiku-4-5` is the canonical
+    // form; the dated `claude-haiku-4-5-20251001` snapshot still resolves via
+    // normalizeModelId() for callers that pinned it.
+    "fable": "claude-fable-5-1",
+    "fable-5.1": "claude-fable-5-1",
+    "fable-5": "claude-fable-5",
+    "mythos": "claude-mythos-5-1",
+    "mythos-5.1": "claude-mythos-5-1",
+    "opus": "claude-opus-5",
+    "opus-5": "claude-opus-5",
+    "opus-4": "claude-opus-4-8",
+    "opus-4.8": "claude-opus-4-8",
+    "opus-4.7": "claude-opus-4-7",
+    "sonnet": "claude-sonnet-5",
+    "sonnet-5": "claude-sonnet-5",
     "sonnet-4": "claude-sonnet-4-6",
-    "haiku": "claude-haiku-4-5-20251001",
-    "haiku-4.5": "claude-haiku-4-5-20251001",
-    // ── OpenAI — latest reasoning and chat models ──
+    "sonnet-4.6": "claude-sonnet-4-6",
+    "haiku": "claude-haiku-4-5",
+    "haiku-4.5": "claude-haiku-4-5",
+    // ── OpenAI — GPT-5 family, GPT-4o, and o-series reasoning ──
+    "gpt5": "gpt-5",
+    "gpt5-mini": "gpt-5-mini",
+    "gpt5-nano": "gpt-5-nano",
+    "gpt5-pro": "gpt-5-pro",
+    "gpt4.1": "gpt-4.1",
     "gpt4o": "gpt-4o",
     "gpt4o-mini": "gpt-4o-mini",
     "o1": "o1",
     "o3": "o3",
     "o3-mini": "o3-mini",
     "o4-mini": "o4-mini",
-    // ── Google — Gemini 2.5 series ──
-    "gemini-pro": "gemini-2.5-pro-preview-05-06",
-    "gemini-flash": "gemini-2.5-flash-preview-04-17",
-    "gemini-flash-lite": "gemini-2.0-flash-lite",
+    // ── Google — Gemini 2.5 GA IDs (the dated -preview- IDs are retired) ──
+    "gemini-pro": "gemini-2.5-pro",
+    "gemini-flash": "gemini-2.5-flash",
+    "gemini-flash-lite": "gemini-2.5-flash-lite",
+    // ── Moonshot — Kimi family ──
+    "kimi": "kimi-k3",
+    "kimi-k3": "kimi-k3",
     // ── Local — latest popular open-weight models for Ollama ──
     "qwen": "qwen3:8b",
     "llama": "llama3.3:latest",

package/dist/aliases.js.map

@@ -1 +1 @@
-{"version":3,"file":"aliases.js","sourceRoot":"","sources":["../src/aliases.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,eAAe,GAAqC;IAChE,8DAA8D;IAC9D,MAAM,EAAE,iBAAiB;IACzB,QAAQ,EAAE,iBAAiB;IAC3B,QAAQ,EAAE,mBAAmB;IAC7B,UAAU,EAAE,mBAAmB;IAC/B,OAAO,EAAE,2BAA2B;IACpC,WAAW,EAAE,2BAA2B;IAExC,kDAAkD;IAClD,OAAO,EAAE,QAAQ;IACjB,YAAY,EAAE,aAAa;IAC3B,IAAI,EAAE,IAAI;IACV,IAAI,EAAE,IAAI;IACV,SAAS,EAAE,SAAS;IACpB,SAAS,EAAE,SAAS;IAEpB,mCAAmC;IACnC,YAAY,EAAE,8BAA8B;IAC5C,cAAc,EAAE,gCAAgC;IAChD,mBAAmB,EAAE,uBAAuB;IAE5C,6DAA6D;IAC7D,MAAM,EAAE,UAAU;IAClB,OAAO,EAAE,iBAAiB;IAC1B,WAAW,EAAE,kBAAkB;IAC/B,UAAU,EAAE,oBAAoB;IAEhC,sDAAsD;IACtD,gBAAgB,EAAE,yCAAyC;IAC3D,gBAAgB,EAAE,wCAAwC;IAC1D,eAAe,EAAE,sCAAsC;IAEvD,mCAAmC;IACnC,eAAe,EAAE,sBAAsB;IACvC,eAAe,EAAE,sBAAsB;IACvC,mBAAmB,EAAE,kBAAkB;IACvC,SAAS,EAAE,sBAAsB;IAEjC,8BAA8B;IAC9B,YAAY,EAAE,yBAAyB;IACvC,cAAc,EAAE,oBAAoB;IAEpC,gEAAgE;IAChE,aAAa,EAAE,wBAAwB;IACvC,aAAa,EAAE,wBAAwB;IACvC,OAAO,EAAE,kBAAkB;IAC3B,cAAc,EAAE,sBAAsB;CACtC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,OAAO,aAAa;IACzB,sEAAsE;IAC9D,OAAO,CAAsB;IAErC;;;OAGG;IACH,YAAY,aAAsC;QACjD,IAAI,CAAC,OAAO,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC;QAExD,IAAI,aAAa,EAAE,CAAC;YACnB,KAAK,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,aAAa,CAAC,EAAE,CAAC;gBAC9D,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;YAClC,CAAC;QACF,CAAC;IACF,CAAC;IAED;;;OAGG;IACH,OAAO,CAAC,WAAmB;QAC1B,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,IAAI,WAAW,CAAC;IACrD,CAAC;IAED;;OAEG;IACH,cAAc,CAAC,OAAe;QAC7B,MAAM,MAAM,GAAa,EAAE,CAAC;QAC5B,KAAK,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YAC5C,IAAI,MAAM,KAAK,OAAO,EAAE,CAAC;gBACxB,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACpB,CAAC;QACF,CAAC;QACD,OAAO,MAAM,CAAC;IACf,CAAC;IAED;;OAEG;IACH,QAAQ,CAAC,KAAa,EAAE,OAAe;QACtC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IAClC,CAAC;IAED;;OAEG;IACH,WAAW,CAAC,KAAa;QACxB,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC5B,CAAC;IAED;;OAEG;IACH,GAAG;QACF,OAAO,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACzC,CAAC;CACD"}
+{"version":3,"file":"aliases.js","sourceRoot":"","sources":["../src/aliases.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,eAAe,GAAqC;IAChE,4DAA4D;IAC5D,qEAAqE;IACrE,0EAA0E;IAC1E,iDAAiD;IACjD,OAAO,EAAE,kBAAkB;IAC3B,WAAW,EAAE,kBAAkB;IAC/B,SAAS,EAAE,gBAAgB;IAC3B,QAAQ,EAAE,mBAAmB;IAC7B,YAAY,EAAE,mBAAmB;IACjC,MAAM,EAAE,eAAe;IACvB,QAAQ,EAAE,eAAe;IACzB,QAAQ,EAAE,iBAAiB;IAC3B,UAAU,EAAE,iBAAiB;IAC7B,UAAU,EAAE,iBAAiB;IAC7B,QAAQ,EAAE,iBAAiB;IAC3B,UAAU,EAAE,iBAAiB;IAC7B,UAAU,EAAE,mBAAmB;IAC/B,YAAY,EAAE,mBAAmB;IACjC,OAAO,EAAE,kBAAkB;IAC3B,WAAW,EAAE,kBAAkB;IAE/B,8DAA8D;IAC9D,MAAM,EAAE,OAAO;IACf,WAAW,EAAE,YAAY;IACzB,WAAW,EAAE,YAAY;IACzB,UAAU,EAAE,WAAW;IACvB,QAAQ,EAAE,SAAS;IACnB,OAAO,EAAE,QAAQ;IACjB,YAAY,EAAE,aAAa;IAC3B,IAAI,EAAE,IAAI;IACV,IAAI,EAAE,IAAI;IACV,SAAS,EAAE,SAAS;IACpB,SAAS,EAAE,SAAS;IAEpB,yEAAyE;IACzE,YAAY,EAAE,gBAAgB;IAC9B,cAAc,EAAE,kBAAkB;IAClC,mBAAmB,EAAE,uBAAuB;IAE5C,+BAA+B;IAC/B,MAAM,EAAE,SAAS;IACjB,SAAS,EAAE,SAAS;IAEpB,6DAA6D;IAC7D,MAAM,EAAE,UAAU;IAClB,OAAO,EAAE,iBAAiB;IAC1B,WAAW,EAAE,kBAAkB;IAC/B,UAAU,EAAE,oBAAoB;IAEhC,sDAAsD;IACtD,gBAAgB,EAAE,yCAAyC;IAC3D,gBAAgB,EAAE,wCAAwC;IAC1D,eAAe,EAAE,sCAAsC;IAEvD,mCAAmC;IACnC,eAAe,EAAE,sBAAsB;IACvC,eAAe,EAAE,sBAAsB;IACvC,mBAAmB,EAAE,kBAAkB;IACvC,SAAS,EAAE,sBAAsB;IAEjC,8BAA8B;IAC9B,YAAY,EAAE,yBAAyB;IACvC,cAAc,EAAE,oBAAoB;IAEpC,gEAAgE;IAChE,aAAa,EAAE,wBAAwB;IACvC,aAAa,EAAE,wBAAwB;IACvC,OAAO,EAAE,kBAAkB;IAC3B,cAAc,EAAE,sBAAsB;CACtC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,OAAO,aAAa;IACzB,sEAAsE;IAC9D,OAAO,CAAsB;IAErC;;;OAGG;IACH,YAAY,aAAsC;QACjD,IAAI,CAAC,OAAO,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC;QAExD,IAAI,aAAa,EAAE,CAAC;YACnB,KAAK,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,aAAa,CAAC,EAAE,CAAC;gBAC9D,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;YAClC,CAAC;QACF,CAAC;IACF,CAAC;IAED;;;OAGG;IACH,OAAO,CAAC,WAAmB;QAC1B,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,IAAI,WAAW,CAAC;IACrD,CAAC;IAED;;OAEG;IACH,cAAc,CAAC,OAAe;QAC7B,MAAM,MAAM,GAAa,EAAE,CAAC;QAC5B,KAAK,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YAC5C,IAAI,MAAM,KAAK,OAAO,EAAE,CAAC;gBACxB,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACpB,CAAC;QACF,CAAC;QACD,OAAO,MAAM,CAAC;IACf,CAAC;IAED;;OAEG;IACH,QAAQ,CAAC,KAAa,EAAE,OAAe;QACtC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IAClC,CAAC;IAED;;OAEG;IACH,WAAW,CAAC,KAAa;QACxB,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC5B,CAAC;IAED;;OAEG;IACH,GAAG;QACF,OAAO,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACzC,CAAC;CACD"}

package/dist/cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAQH,UAAU,UAAU,CAAC,CAAC;IACrB,IAAI,EAAE,CAAC,CAAC;IACR,SAAS,EAAE,MAAM,CAAC;CAClB;AAED;;;;;GAKG;AACH,qBAAa,UAAU;IACtB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;gBAEtB,QAAQ,CAAC,EAAE,MAAM;IAI7B;;;OAGG;IACG,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAmBxD;;;;;OAKG;IACG,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAiBjD;;OAEG;IACG,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAS5C;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAY5B;;OAEG;IACH,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO;IAQpD;;;OAGG;IACH,OAAO,CAAC,SAAS;IAKjB;;OAEG;YACW,SAAS;CAGvB"}
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAQH,UAAU,UAAU,CAAC,CAAC;IACrB,IAAI,EAAE,CAAC,CAAC;IACR,SAAS,EAAE,MAAM,CAAC;CAClB;AAqBD;;;;;GAKG;AACH,qBAAa,UAAU;IACtB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAElC,YAAY,QAAQ,CAAC,EAAE,MAAM,EAE5B;IAED;;;OAGG;IACG,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAsCvD;IAED;;;;;OAKG;IACG,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAehD;IAED;;OAEG;IACG,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAO3C;IAED;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAU3B;IAED;;OAEG;IACH,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAEnD;IAMD;;;OAGG;IACH,OAAO,CAAC,SAAS;IAKjB;;OAEG;YACW,SAAS;CAGvB"}

package/dist/cache.js

@@ -6,11 +6,28 @@
  * Each cache key maps to a `{key}.json` file inside the cache directory.
  * @module
  */
-import { mkdir, readFile, readdir, rename, unlink, writeFile } from "fs/promises";
+import { mkdir, open, readdir, rename, unlink, writeFile } from "fs/promises";
 import { randomBytes } from "crypto";
 import { homedir } from "os";
 import { join } from "path";
 import { assertCleanPayload } from "./security.js";
+/**
+ * Hard ceiling on a single cache file before we even attempt to parse it.
+ * A legitimate full-registry snapshot is a few hundred KB; anything past
+ * this is either corruption or a hostile payload crafted to exhaust memory
+ * (a "JSON bomb"). We reject it as a cache miss rather than feeding it to
+ * `JSON.parse`, which buffers and parses the whole string eagerly.
+ */
+const MAX_CACHE_FILE_BYTES = 25 * 1024 * 1024;
+/**
+ * Strip CR/LF (and other control chars) from a cache key before it is
+ * interpolated into a log line. A key can derive from a CLI/HTTP-supplied
+ * provider id (`provider_<id>`), so logging it verbatim would let crafted
+ * input forge extra log records (log injection / CWE-117).
+ */
+function sanitizeKeyForLog(key) {
+    return key.replace(/[\r\n\t]/g, "").slice(0, 200);
+}
 /**
  * Simple file-based JSON cache with TTL support.
  * Stores discovered provider data to avoid re-fetching on every startup.
@@ -27,9 +44,26 @@ export class KoshaCache {
      * Returns null if the entry is missing or the file cannot be read.
      */
     async get(key) {
+        let handle;
         try {
             const filePath = this.keyToPath(key);
-            const raw = await readFile(filePath, "utf-8");
+            // Stat and read through the SAME open file descriptor rather than
+            // by path. fstat() on an fd reflects exactly the bytes the
+            // following read will see, so a rename/replace of the path in the
+            // gap between a path-based stat() and a path-based readFile()
+            // can't smuggle a file past the size guard below (CodeQL
+            // js/file-system-race; the fd-bound fstat+read pair has no such
+            // gap — the descriptor stays pinned to one inode).
+            handle = await open(filePath, "r");
+            const { size } = await handle.stat();
+            if (size > MAX_CACHE_FILE_BYTES) {
+                console.warn(`KoshaCache: cache file for key "${sanitizeKeyForLog(key)}" is ${size} bytes (> ${MAX_CACHE_FILE_BYTES}); refusing to parse and invalidating`);
+                await handle.close();
+                handle = undefined;
+                await this.invalidate(key);
+                return null;
+            }
+            const raw = await handle.readFile("utf-8");
             const entry = JSON.parse(raw);
             assertCleanPayload(entry, `cache/${key}`);
             return entry;
@@ -41,10 +75,13 @@ export class KoshaCache {
                 await this.invalidate(key);
             }
             else if (err instanceof SyntaxError) {
-                console.warn(`KoshaCache: corrupted cache file for key "${key}"`);
+                console.warn(`KoshaCache: corrupted cache file for key "${sanitizeKeyForLog(key)}"`);
             }
             return null;
         }
+        finally {
+            await handle?.close().catch(() => { });
+        }
     }
     /**
      * Write data to the cache under the given key.

package/dist/cache.js.map

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

package/dist/claude-generation.d.ts

@@ -0,0 +1,59 @@
+/**
+ * kosha-discovery — Claude generation parsing and per-generation behaviour.
+ *
+ * One source of truth for "which Claude is this and what does it accept",
+ * shared by the catalog feature inference (`model-features.ts`) and the
+ * proxy's wire translator (`wire-anthropic.ts`). Keeping it in one module
+ * means an OpenRouter-style `anthropic/claude-sonnet-4.6`, a Bedrock-style
+ * `anthropic.claude-opus-4-8-v1:0`, and the bare `claude-opus-4-8` all
+ * classify identically everywhere.
+ * @module
+ */
+export interface ClaudeGeneration {
+    family: "opus" | "sonnet" | "haiku" | "fable" | "mythos";
+    major: number;
+    minor: number;
+}
+/**
+ * Parse the generation out of a family-first Claude ID such as
+ * `claude-opus-4-8`, `claude-sonnet-5`, `claude-fable-5-1`, a dated
+ * `claude-haiku-4-5-20251001`, or a prefixed / dotted variant. Legacy
+ * version-first IDs (`claude-3-5-sonnet-…`, `claude-2.1`) and non-Claude IDs
+ * return `undefined`.
+ */
+export declare function parseClaudeGeneration(modelId: string): ClaudeGeneration | undefined;
+/** How a Claude model treats `temperature` / `top_p`. */
+export type SamplingSupport = "both" | "one" | "none";
+/**
+ * Sampling parameters were removed on Opus 4.7 and every later model (Opus
+ * 4.8, Opus 5, Sonnet 5, Fable, Mythos): sending them returns a 400. Every
+ * Claude 4.x model accepts at most one of `temperature` / `top_p` (sending
+ * both is a 400). Claude 3.x and unrecognized IDs accept both.
+ */
+export declare function claudeSamplingSupport(modelId: string): SamplingSupport;
+/** Anthropic's accepted `temperature` range; OpenAI's is 0..2. */
+export declare const CLAUDE_TEMPERATURE_MAX = 1;
+export type ClaudeEffort = "low" | "medium" | "high" | "xhigh" | "max";
+/**
+ * Effort levels a generation accepts under `output_config.effort`; empty when
+ * effort is unsupported. `xhigh` arrived with Opus 4.7; `max` with 4.6; in
+ * the 4.5 generation only Opus 4.5 had an effort parameter at all (Sonnet
+ * 4.5 and Haiku 4.5 reject it).
+ */
+export declare function claudeEffortLadder(modelId: string): readonly ClaudeEffort[];
+/**
+ * Last-assistant-turn prefill returns a 400 on Opus 4.6 / Sonnet 4.6 and every
+ * later model. Older generations still accept a trailing assistant message.
+ */
+export declare function claudeSupportsPrefill(modelId: string): boolean;
+/**
+ * Native JSON-schema structured outputs (`output_config.format`) shipped with
+ * the 4.5 generation (Sonnet 4.5, Haiku 4.5, Opus 4.1) and every model since.
+ */
+export declare function claudeSupportsNativeJsonSchema(modelId: string): boolean;
+/**
+ * Claude Fable 5.1 and Claude Mythos 5.1 return a 400 for forced tool use
+ * (`tool_choice` `any` / `tool`); everything else still honours it.
+ */
+export declare function claudeSupportsForcedToolChoice(modelId: string): boolean;
+//# sourceMappingURL=claude-generation.d.ts.map

package/dist/claude-generation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-generation.d.ts","sourceRoot":"","sources":["../src/claude-generation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,gBAAgB;IAChC,MAAM,EAAE,MAAM,GAAG,QAAQ,GAAG,OAAO,GAAG,OAAO,GAAG,QAAQ,CAAC;IACzD,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACd;AAgBD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS,CAUnF;AAMD,yDAAyD;AACzD,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,CAAC;AAEtD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,eAAe,CAMtE;AAED,kEAAkE;AAClE,eAAO,MAAM,sBAAsB,IAAI,CAAC;AAExC,MAAM,MAAM,YAAY,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,GAAG,KAAK,CAAC;AAEvE;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,YAAY,EAAE,CAO3E;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAI9D;AAED;;;GAGG;AACH,wBAAgB,8BAA8B,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAKvE;AAED;;;GAGG;AACH,wBAAgB,8BAA8B,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAKvE"}