@sriinnu/kosha-discovery 1.0.0 → 1.2.0

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="logo-icon.svg" alt="Kosha — AI Model Discovery" width="120" />
+  <img src="logo.png" alt="Kosha — AI Model Discovery" width="140" />
 </p>
 
 <h1 align="center">kosha-discovery — कोश</h1>
@@ -13,7 +13,7 @@
   <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, and HTTP API. One source of truth for model identity, pricing, and routing — so your app doesn't break when providers ship new SKUs or change rates.
+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.
 
 ## Install
 
@@ -63,6 +63,53 @@ GET  /api/providers                     GET  /api/roles
 POST /api/refresh                       GET  /health
 ```
 
+### 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.
+
+```bash
+kosha serve   # start on :3000
+```
+
+```typescript
+import OpenAI from "openai";
+
+const client = new OpenAI({
+  baseURL: "http://localhost:3000/proxy/v1",
+  apiKey:  "not-used",   // kosha resolves credentials from env
+});
+
+// Use any canonical model ID or alias
+const res = await client.chat.completions.create({
+  model: "sonnet",
+  messages: [{ role: "user", content: "hello" }],
+});
+
+// Let kosha pick the cheapest model you have a key for
+const cheap = await client.chat.completions.create({
+  model: "kosha:cheapest",
+  messages: [{ role: "user", content: "hello" }],
+});
+
+// Cheapest model with tool_use and at least 128k context
+const routed = await client.chat.completions.create({
+  model: "kosha:cheapest[tool_use,128k]",
+  messages: [{ role: "user", content: "hello" }],
+});
+```
+
+**`kosha:cheapest` filter syntax** (comma-separated, combinable):
+
+| Filter | Example | Meaning |
+|--------|---------|---------|
+| capability | `tool_use`, `vision` | model must have this tag |
+| `<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.
+
+Supported transports: `openai`, `openai-compatible-http`, `ollama`. Anthropic, Google, Bedrock, and Vertex require wire-format translation — not yet proxied.
+
 ## Supported providers
 
 | Provider | Discovery | Credential sources |
@@ -74,6 +121,7 @@ POST /api/refresh                       GET  /health
 | 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 |
 
@@ -85,7 +133,7 @@ Full credential setup: [docs/credentials.md](docs/credentials.md).
   <img src="architecture.svg" alt="Kosha Architecture" width="720" />
 </p>
 
-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.
+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.
 
 ## Docs
 

package/dist/cli-format.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli-format.d.ts","sourceRoot":"","sources":["../src/cli-format.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAYH,+EAA+E;AAC/E,eAAO,MAAM,QAAQ,SAAyB,CAAC;AAE/C,4BAA4B;AAC5B,eAAO,MAAM,IAAI,cAAY,CAAC;AAE9B,mCAAmC;AACnC,eAAO,MAAM,GAAG,cAAY,CAAC;AAE7B,uCAAuC;AACvC,eAAO,MAAM,KAAK,cAAY,CAAC;AAE/B,mCAAmC;AACnC,eAAO,MAAM,KAAK,eAAa,CAAC;AAEhC,iCAAiC;AACjC,eAAO,MAAM,GAAG,eAAa,CAAC;AAE9B,oCAAoC;AACpC,eAAO,MAAM,MAAM,eAAa,CAAC;AAEjC,kCAAkC;AAClC,eAAO,MAAM,IAAI,eAAa,CAAC;AAE/B,yDAAyD;AACzD,eAAO,MAAM,OAAO,eAAa,CAAC;AAMlC;;;;;;;;;GASG;AACH,wBAAgB,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAEpD;AAMD;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAK1D;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAI7D;AAED,wFAAwF;AACxF,UAAU,WAAW;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,gBAAgB,EAAE,MAAM,CAAC;IACzB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,WAAW,GAAG,SAAS,GAAG,MAAM,CAO1E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,WAAW,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAgBxF;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE9C;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAElD;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,GAAE,MAAmB,GAAG,MAAM,CAW/E;AAMD;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAKzD;AAED;;;;;;GAMG;AACH,wBAAgB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAEtD;AAMD;;GAEG;AACH,MAAM,WAAW,MAAM;IACtB,2BAA2B;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,yCAAyC;IACzC,KAAK,EAAE,MAAM,CAAC;IACd,6CAA6C;IAC7C,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACzB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,MAAM,CAuBvE"}
+{"version":3,"file":"cli-format.d.ts","sourceRoot":"","sources":["../src/cli-format.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAYH,+EAA+E;AAC/E,eAAO,MAAM,QAAQ,SAAyB,CAAC;AAE/C,4BAA4B;AAC5B,eAAO,MAAM,IAAI,cAAY,CAAC;AAE9B,mCAAmC;AACnC,eAAO,MAAM,GAAG,cAAY,CAAC;AAE7B,uCAAuC;AACvC,eAAO,MAAM,KAAK,cAAY,CAAC;AAE/B,mCAAmC;AACnC,eAAO,MAAM,KAAK,eAAa,CAAC;AAEhC,iCAAiC;AACjC,eAAO,MAAM,GAAG,eAAa,CAAC;AAE9B,oCAAoC;AACpC,eAAO,MAAM,MAAM,eAAa,CAAC;AAEjC,kCAAkC;AAClC,eAAO,MAAM,IAAI,eAAa,CAAC;AAE/B,yDAAyD;AACzD,eAAO,MAAM,OAAO,eAAa,CAAC;AAMlC;;;;;;;;;GASG;AACH,wBAAgB,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAEpD;AAMD;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAK1D;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAI7D;AAED,wFAAwF;AACxF,UAAU,WAAW;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,gBAAgB,EAAE,MAAM,CAAC;IACzB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,WAAW,GAAG,SAAS,GAAG,MAAM,CAO1E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,WAAW,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAgBxF;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE9C;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAElD;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,GAAE,MAAmB,GAAG,MAAM,CAW/E;AAMD;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAMzD;AAED;;;;;;GAMG;AACH,wBAAgB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAEtD;AAMD;;GAEG;AACH,MAAM,WAAW,MAAM;IACtB,2BAA2B;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,yCAAyC;IACzC,KAAK,EAAE,MAAM,CAAC;IACd,6CAA6C;IAC7C,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACzB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,MAAM,CAuBvE"}

package/dist/cli-format.js

@@ -196,7 +196,8 @@ export function formatRelativeTime(ts, now = Date.now()) {
  */
 export function padRight(str, len) {
     // Strip ANSI codes for length calculation
-    const plainLen = str.replace(/\x1b\[[0-9;]*m/g, "").length;
+    const ansiEscapePattern = new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*m`, "g");
+    const plainLen = str.replace(ansiEscapePattern, "").length;
     if (plainLen >= len)
         return str;
     return str + " ".repeat(len - plainLen);

package/dist/cli-format.js.map

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

package/dist/context-strategy.d.ts

@@ -0,0 +1,48 @@
+/**
+ * kosha-discovery — Context-management strategy advisor.
+ *
+ * Pure synthesis over the model + provider catalog: given where a caller is
+ * in their conversation, return ranked options (continue / cache / compact /
+ * switch model / long-context tier / batch offload) with rough cost math.
+ *
+ * No tokenization, no model inference — just arithmetic over the registry.
+ * @module
+ */
+import type { ModelCard, ProviderCacheBehavior } from "./types.js";
+export interface ContextStrategyInput {
+    model: ModelCard;
+    currentTokens: number;
+    expectedRemainingTurns?: number;
+    expectedOutputTokens?: number;
+    candidateAlternatives?: ModelCard[];
+}
+export interface ContextSituation {
+    tokensUsed: number;
+    contextWindow: number;
+    headroomTokens: number;
+    headroomPercent: number;
+    inLongContextTier: boolean;
+    longContextThresholdTokens?: number;
+}
+export interface StrategyOption {
+    strategy: "continue" | "enable_prompt_cache" | "compact_and_continue" | "switch_to_long_context_tier" | "switch_model" | "batch_offload";
+    viable: boolean;
+    costPerTurnUsd?: number;
+    savingsPerTurnUsd?: number;
+    notes: string;
+    details?: Record<string, unknown>;
+}
+export interface ContextStrategy {
+    model: {
+        id: string;
+        provider: string;
+        contextWindow: number;
+    };
+    situation: ContextSituation;
+    cacheBehavior?: ProviderCacheBehavior;
+    options: StrategyOption[];
+    recommended: StrategyOption["strategy"];
+}
+/** Compute ranked context-management options for the given conversation state. */
+export declare function computeContextStrategy(input: ContextStrategyInput): ContextStrategy;
+//# sourceMappingURL=context-strategy.d.ts.map

package/dist/context-strategy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-strategy.d.ts","sourceRoot":"","sources":["../src/context-strategy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAgB,qBAAqB,EAAE,MAAM,YAAY,CAAC;AASjF,MAAM,WAAW,oBAAoB;IACpC,KAAK,EAAE,SAAS,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,qBAAqB,CAAC,EAAE,SAAS,EAAE,CAAC;CACpC;AAED,MAAM,WAAW,gBAAgB;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,MAAM,CAAC;IACxB,iBAAiB,EAAE,OAAO,CAAC;IAC3B,0BAA0B,CAAC,EAAE,MAAM,CAAC;CACpC;AAED,MAAM,WAAW,cAAc;IAC9B,QAAQ,EACL,UAAU,GACV,qBAAqB,GACrB,sBAAsB,GACtB,6BAA6B,GAC7B,cAAc,GACd,eAAe,CAAC;IACnB,MAAM,EAAE,OAAO,CAAC;IAChB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,eAAe;IAC/B,KAAK,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/D,SAAS,EAAE,gBAAgB,CAAC;IAC5B,aAAa,CAAC,EAAE,qBAAqB,CAAC;IACtC,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,WAAW,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC;CACxC;AAED,kFAAkF;AAClF,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,oBAAoB,GAAG,eAAe,CA6CnF"}

package/dist/context-strategy.js

@@ -0,0 +1,274 @@
+/**
+ * kosha-discovery — Context-management strategy advisor.
+ *
+ * Pure synthesis over the model + provider catalog: given where a caller is
+ * in their conversation, return ranked options (continue / cache / compact /
+ * switch model / long-context tier / batch offload) with rough cost math.
+ *
+ * No tokenization, no model inference — just arithmetic over the registry.
+ * @module
+ */
+import { getProviderCacheBehavior } from "./provider-catalog.js";
+const DEFAULT_EXPECTED_OUTPUT_TOKENS = 1024;
+const DEFAULT_EXPECTED_REMAINING_TURNS = 5;
+const HEADROOM_WARN_PERCENT = 20;
+const HEADROOM_CRITICAL_PERCENT = 10;
+const COMPACTION_TARGET_PERCENT = 25;
+const CACHE_READ_DISCOUNT_FLOOR = 0.5;
+/** Compute ranked context-management options for the given conversation state. */
+export function computeContextStrategy(input) {
+    const { model, currentTokens, expectedRemainingTurns = DEFAULT_EXPECTED_REMAINING_TURNS, expectedOutputTokens = DEFAULT_EXPECTED_OUTPUT_TOKENS, candidateAlternatives = [], } = input;
+    const tokensUsed = Math.max(0, Math.floor(currentTokens));
+    const headroomTokens = Math.max(0, model.contextWindow - tokensUsed);
+    const headroomPercent = model.contextWindow > 0 ? (headroomTokens / model.contextWindow) * 100 : 0;
+    const longThreshold = model.pricing?.longContextThresholdTokens;
+    const inLongContextTier = longThreshold !== undefined && tokensUsed >= longThreshold;
+    const situation = {
+        tokensUsed,
+        contextWindow: model.contextWindow,
+        headroomTokens,
+        headroomPercent: round(headroomPercent, 2),
+        inLongContextTier,
+        ...(longThreshold !== undefined ? { longContextThresholdTokens: longThreshold } : {}),
+    };
+    const cacheBehavior = getProviderCacheBehavior(model.provider);
+    const baselineCost = perTurnCost(model.pricing, tokensUsed, expectedOutputTokens, inLongContextTier);
+    const options = [];
+    options.push(buildContinueOption(situation, baselineCost, expectedRemainingTurns));
+    options.push(buildPromptCacheOption(model, tokensUsed, expectedOutputTokens, baselineCost, cacheBehavior));
+    options.push(buildLongContextTierOption(model, situation, baselineCost, expectedOutputTokens));
+    options.push(buildCompactionOption(model, situation, baselineCost, expectedOutputTokens, candidateAlternatives));
+    options.push(buildSwitchModelOption(model, tokensUsed, expectedOutputTokens, baselineCost, candidateAlternatives));
+    options.push(buildBatchOffloadOption(model, tokensUsed, expectedOutputTokens, baselineCost));
+    const recommended = pickRecommended(options, situation);
+    return {
+        model: { id: model.id, provider: model.provider, contextWindow: model.contextWindow },
+        situation,
+        ...(cacheBehavior ? { cacheBehavior } : {}),
+        options,
+        recommended,
+    };
+}
+function buildContinueOption(situation, baselineCost, expectedRemainingTurns) {
+    const viable = situation.headroomPercent > 0;
+    const tone = situation.headroomPercent < HEADROOM_CRITICAL_PERCENT
+        ? `Only ${situation.headroomPercent.toFixed(1)}% headroom — likely to overflow within 1–2 turns.`
+        : situation.headroomPercent < HEADROOM_WARN_PERCENT
+            ? `${situation.headroomPercent.toFixed(1)}% headroom — comfortable for a few more turns.`
+            : `${situation.headroomPercent.toFixed(1)}% headroom — no pressure.`;
+    return {
+        strategy: "continue",
+        viable,
+        ...(baselineCost !== undefined ? { costPerTurnUsd: round(baselineCost, 6) } : {}),
+        notes: tone,
+        details: {
+            projectedCostForRemainingTurnsUsd: baselineCost !== undefined ? round(baselineCost * expectedRemainingTurns, 6) : undefined,
+            inLongContextTier: situation.inLongContextTier,
+        },
+    };
+}
+function buildPromptCacheOption(model, currentTokens, expectedOutputTokens, baselineCost, cacheBehavior) {
+    if (!cacheBehavior || cacheBehavior.mode === "none") {
+        return {
+            strategy: "enable_prompt_cache",
+            viable: false,
+            notes: cacheBehavior?.mode === "none"
+                ? "Provider has no documented prompt cache."
+                : "Cache behavior for this provider has not been curated yet.",
+        };
+    }
+    const cacheReadRate = model.pricing?.cacheReadPerMillion;
+    const inputRate = model.pricing?.inputPerMillion;
+    const outputRate = model.pricing?.outputPerMillion;
+    const canEstimate = cacheReadRate !== undefined && inputRate !== undefined && outputRate !== undefined;
+    const cachedTurnCost = canEstimate
+        ? (currentTokens * cacheReadRate + expectedOutputTokens * outputRate) / 1_000_000
+        : undefined;
+    const savings = baselineCost !== undefined && cachedTurnCost !== undefined ? baselineCost - cachedTurnCost : undefined;
+    const ttlGuidance = cacheBehavior.mode === "explicit"
+        ? cacheBehavior.ttlTiers
+            ? `Pick a TTL from: ${cacheBehavior.ttlTiers.join(", ")}.`
+            : cacheBehavior.maxTtlSeconds
+                ? `Set TTL up to ${cacheBehavior.maxTtlSeconds}s (default ${cacheBehavior.defaultTtlSeconds ?? "provider-defined"}).`
+                : "Caller picks TTL."
+        : cacheBehavior.mode === "automatic"
+            ? `Provider manages TTL${cacheBehavior.approximateTtlSeconds ? ` (~${cacheBehavior.approximateTtlSeconds}s typical)` : ""}.`
+            : "Gateway forwards cache_control to the routed model — TTL inherits from the underlying provider.";
+    return {
+        strategy: "enable_prompt_cache",
+        viable: true,
+        ...(cachedTurnCost !== undefined ? { costPerTurnUsd: round(cachedTurnCost, 6) } : {}),
+        ...(savings !== undefined ? { savingsPerTurnUsd: round(savings, 6) } : {}),
+        notes: cacheReadRate !== undefined &&
+            inputRate !== undefined &&
+            inputRate > 0 &&
+            cacheReadRate / inputRate < CACHE_READ_DISCOUNT_FLOOR
+            ? `Cache reads cost ${round((cacheReadRate / inputRate) * 100, 1)}% of base input — meaningful savings on a stable prefix. ${ttlGuidance}`
+            : `Mode: ${cacheBehavior.mode}. ${ttlGuidance}`,
+        details: {
+            cacheMode: cacheBehavior.mode,
+            ttlTiers: cacheBehavior.ttlTiers,
+            defaultTtlSeconds: cacheBehavior.defaultTtlSeconds,
+            maxTtlSeconds: cacheBehavior.maxTtlSeconds,
+            approximateTtlSeconds: cacheBehavior.approximateTtlSeconds,
+            cacheReadRatePerMillion: cacheReadRate,
+            documented: cacheBehavior.documented,
+        },
+    };
+}
+function buildLongContextTierOption(model, situation, baselineCost, expectedOutputTokens) {
+    const threshold = model.pricing?.longContextThresholdTokens;
+    const longIn = model.pricing?.longContextInputPerMillion;
+    const longOut = model.pricing?.longContextOutputPerMillion;
+    if (threshold === undefined || longIn === undefined || longOut === undefined) {
+        return {
+            strategy: "switch_to_long_context_tier",
+            viable: false,
+            notes: "Model does not publish a tiered long-context price — single rate applies regardless of size.",
+        };
+    }
+    const tieredCost = (situation.tokensUsed * longIn + expectedOutputTokens * longOut) / 1_000_000;
+    const delta = baselineCost !== undefined ? tieredCost - baselineCost : undefined;
+    return {
+        strategy: "switch_to_long_context_tier",
+        viable: true,
+        costPerTurnUsd: round(tieredCost, 6),
+        ...(delta !== undefined ? { savingsPerTurnUsd: round(-delta, 6) } : {}),
+        notes: situation.inLongContextTier
+            ? `Already in long-context tier (>${threshold} tokens). Cost is what it is — consider compaction or a smaller-context-priced model instead.`
+            : `You're under the ${threshold}-token threshold; growing past it triggers tiered pricing (input ${longIn}/M, output ${longOut}/M).`,
+        details: { thresholdTokens: threshold, longInputPerMillion: longIn, longOutputPerMillion: longOut },
+    };
+}
+function buildCompactionOption(model, situation, baselineCost, expectedOutputTokens, candidateAlternatives) {
+    if (situation.tokensUsed === 0) {
+        return { strategy: "compact_and_continue", viable: false, notes: "Nothing to compact yet." };
+    }
+    const targetTokens = Math.max(1024, Math.floor(model.contextWindow * (COMPACTION_TARGET_PERCENT / 100)));
+    const tokensReclaimed = Math.max(0, situation.tokensUsed - targetTokens);
+    const summarizer = pickCheapestChatModel(candidateAlternatives, model);
+    const summarizationCost = summarizer?.pricing?.inputPerMillion !== undefined
+        ? (situation.tokensUsed * summarizer.pricing.inputPerMillion +
+            targetTokens * (summarizer.pricing.outputPerMillion ?? 0)) /
+            1_000_000
+        : undefined;
+    const postCompactionTurnCost = model.pricing?.inputPerMillion !== undefined && model.pricing?.outputPerMillion !== undefined
+        ? (targetTokens * model.pricing.inputPerMillion + expectedOutputTokens * model.pricing.outputPerMillion) / 1_000_000
+        : undefined;
+    const savings = baselineCost !== undefined && postCompactionTurnCost !== undefined ? baselineCost - postCompactionTurnCost : undefined;
+    return {
+        strategy: "compact_and_continue",
+        viable: tokensReclaimed > 0,
+        ...(postCompactionTurnCost !== undefined ? { costPerTurnUsd: round(postCompactionTurnCost, 6) } : {}),
+        ...(savings !== undefined ? { savingsPerTurnUsd: round(savings, 6) } : {}),
+        notes: summarizer
+            ? `Summarize older turns down to ~${targetTokens} tokens using ${summarizer.id}; reclaims ${tokensReclaimed} tokens.`
+            : `Summarize older turns down to ~${targetTokens} tokens; reclaims ${tokensReclaimed} tokens. No cheap summarizer in candidate set.`,
+        details: {
+            targetTokens,
+            tokensReclaimed,
+            summarizerModelId: summarizer?.id,
+            summarizationCostUsd: summarizationCost !== undefined ? round(summarizationCost, 6) : undefined,
+        },
+    };
+}
+function buildSwitchModelOption(currentModel, currentTokens, expectedOutputTokens, baselineCost, candidateAlternatives) {
+    const candidates = candidateAlternatives
+        .filter((m) => m.id !== currentModel.id && m.contextWindow >= currentTokens && m.pricing?.inputPerMillion !== undefined)
+        .map((m) => ({
+        model: m,
+        cost: perTurnCost(m.pricing, currentTokens, expectedOutputTokens, false) ?? Number.POSITIVE_INFINITY,
+    }))
+        .sort((a, b) => a.cost - b.cost)
+        .slice(0, 3);
+    if (candidates.length === 0) {
+        return {
+            strategy: "switch_model",
+            viable: false,
+            notes: "No alternative model in the candidate set fits the current context size.",
+        };
+    }
+    const best = candidates[0];
+    const savings = baselineCost !== undefined ? baselineCost - best.cost : undefined;
+    return {
+        strategy: "switch_model",
+        viable: true,
+        costPerTurnUsd: round(best.cost, 6),
+        ...(savings !== undefined ? { savingsPerTurnUsd: round(savings, 6) } : {}),
+        notes: `Cheapest fit: ${best.model.id} (${best.model.contextWindow} context). ${candidates.length - 1} other option(s) considered.`,
+        details: {
+            alternatives: candidates.map((c) => ({
+                id: c.model.id,
+                provider: c.model.provider,
+                contextWindow: c.model.contextWindow,
+                costPerTurnUsd: Number.isFinite(c.cost) ? round(c.cost, 6) : null,
+            })),
+        },
+    };
+}
+function buildBatchOffloadOption(model, currentTokens, expectedOutputTokens, baselineCost) {
+    const batchIn = model.pricing?.batchInputPerMillion;
+    const batchOut = model.pricing?.batchOutputPerMillion;
+    if (batchIn === undefined || batchOut === undefined) {
+        return {
+            strategy: "batch_offload",
+            viable: false,
+            notes: "Model does not publish Batch API pricing.",
+        };
+    }
+    const batchCost = (currentTokens * batchIn + expectedOutputTokens * batchOut) / 1_000_000;
+    const savings = baselineCost !== undefined ? baselineCost - batchCost : undefined;
+    return {
+        strategy: "batch_offload",
+        viable: true,
+        costPerTurnUsd: round(batchCost, 6),
+        ...(savings !== undefined ? { savingsPerTurnUsd: round(savings, 6) } : {}),
+        notes: "Batch API trades latency (typically 24h SLO) for cheaper tokens — only viable if the workload is not real-time.",
+        details: { batchInputPerMillion: batchIn, batchOutputPerMillion: batchOut },
+    };
+}
+function pickRecommended(options, situation) {
+    const viable = options.filter((o) => o.viable);
+    if (viable.length === 0)
+        return "continue";
+    if (situation.headroomPercent < HEADROOM_CRITICAL_PERCENT) {
+        const compact = viable.find((o) => o.strategy === "compact_and_continue");
+        if (compact)
+            return "compact_and_continue";
+        const switchModel = viable.find((o) => o.strategy === "switch_model");
+        if (switchModel)
+            return "switch_model";
+    }
+    const withSavings = viable
+        .filter((o) => o.strategy !== "continue" && typeof o.savingsPerTurnUsd === "number" && o.savingsPerTurnUsd > 0)
+        .sort((a, b) => (b.savingsPerTurnUsd ?? 0) - (a.savingsPerTurnUsd ?? 0));
+    if (withSavings.length > 0)
+        return withSavings[0].strategy;
+    return "continue";
+}
+function pickCheapestChatModel(candidates, currentModel) {
+    return candidates
+        .filter((m) => m.id !== currentModel.id &&
+        m.mode === "chat" &&
+        typeof m.pricing?.inputPerMillion === "number" &&
+        typeof m.pricing?.outputPerMillion === "number")
+        .sort((a, b) => (a.pricing?.inputPerMillion ?? 0) - (b.pricing?.inputPerMillion ?? 0))[0];
+}
+function perTurnCost(pricing, inputTokens, outputTokens, useLongContextTier) {
+    if (!pricing)
+        return undefined;
+    const inputRate = useLongContextTier
+        ? (pricing.longContextInputPerMillion ?? pricing.inputPerMillion)
+        : pricing.inputPerMillion;
+    const outputRate = useLongContextTier
+        ? (pricing.longContextOutputPerMillion ?? pricing.outputPerMillion)
+        : pricing.outputPerMillion;
+    if (inputRate === undefined || outputRate === undefined)
+        return undefined;
+    return (inputTokens * inputRate + outputTokens * outputRate) / 1_000_000;
+}
+function round(n, digits) {
+    const factor = 10 ** digits;
+    return Math.round(n * factor) / factor;
+}
+//# sourceMappingURL=context-strategy.js.map

package/dist/context-strategy.js.map

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

package/dist/credentials/resolver.d.ts

@@ -71,6 +71,13 @@ export declare class CredentialResolver {
      *   (No known CLI tool stores OpenRouter keys on disk.)
      */
     private resolveOpenRouter;
+    /**
+     * Search hierarchy for Vercel AI Gateway credentials:
+     *   1. Explicit config key
+     *   2. `AI_GATEWAY_API_KEY` env var
+     *   3. `VERCEL_OIDC_TOKEN` env var (available on Vercel deployments)
+     */
+    private resolveVercelAIGateway;
     /**
      * Ollama runs locally and never requires authentication.
      * Returns `{ source: "none" }` unconditionally.

package/dist/credentials/resolver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolver.d.ts","sourceRoot":"","sources":["../../src/credentials/resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAMH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAGpD;;;;;;;;;;GAUG;AACH,qBAAa,kBAAkB;IAC9B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAa;IAClC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA0B;IAEpD;;;;;;;OAOG;IACG,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAuDlF;;;;;;;;OAQG;YACW,gBAAgB;IAuD9B;;;;;;OAMG;YACW,aAAa;IA2C3B;;;;;;OAMG;YACW,aAAa;IAkD3B;;;;;OAKG;YACW,iBAAiB;IAoB/B;;;OAGG;IACH,OAAO,CAAC,aAAa;IAQrB;;;;;;;;;;;;;OAaG;YACW,wBAAwB;IAqDtC;;;;;;;;;OASG;YACW,gBAAgB;IAsB9B;;;;;;;;;;OAUG;IACH,OAAO,CAAC,kBAAkB;IAkC1B;;;;;;;;;;;;;;OAcG;YACW,uBAAuB;IA0CrC;;;;;;;OAOG;YACW,qBAAqB;IAkBnC;;;OAGG;IACH,OAAO,CAAC,eAAe;IAavB;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAkBzB;;;OAGG;IACH,OAAO,CAAC,aAAa;IAIrB,OAAO,CAAC,mBAAmB;IAa3B,OAAO,CAAC,kBAAkB;IAmB1B,oEAAoE;YACtD,QAAQ;IAStB,sEAAsE;YACxD,YAAY;IAQ1B,8DAA8D;IAC9D,OAAO,CAAC,eAAe;IAiBvB,6CAA6C;IAC7C,OAAO,CAAC,cAAc;IAetB,8EAA8E;IAC9E,OAAO,CAAC,mBAAmB;CAS3B"}
+{"version":3,"file":"resolver.d.ts","sourceRoot":"","sources":["../../src/credentials/resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAMH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAGpD;;;;;;;;;;GAUG;AACH,qBAAa,kBAAkB;IAC9B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAa;IAClC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA0B;IAEpD;;;;;;;OAOG;IACG,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAyDlF;;;;;;;;OAQG;YACW,gBAAgB;IAuD9B;;;;;;OAMG;YACW,aAAa;IA2C3B;;;;;;OAMG;YACW,aAAa;IAkD3B;;;;;OAKG;YACW,iBAAiB;IAoB/B;;;;;OAKG;YACW,sBAAsB;IAsBpC;;;OAGG;IACH,OAAO,CAAC,aAAa;IAQrB;;;;;;;;;;;;;OAaG;YACW,wBAAwB;IAqDtC;;;;;;;;;OASG;YACW,gBAAgB;IAsB9B;;;;;;;;;;OAUG;IACH,OAAO,CAAC,kBAAkB;IAkC1B;;;;;;;;;;;;;;OAcG;YACW,uBAAuB;IA0CrC;;;;;;;OAOG;YACW,qBAAqB;IAkBnC;;;OAGG;IACH,OAAO,CAAC,eAAe;IAavB;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAkBzB;;;OAGG;IACH,OAAO,CAAC,aAAa;IAIrB,OAAO,CAAC,mBAAmB;IAa3B,OAAO,CAAC,kBAAkB;IAmB1B,oEAAoE;YACtD,QAAQ;IAStB,sEAAsE;YACxD,YAAY;IAQ1B,8DAA8D;IAC9D,OAAO,CAAC,eAAe;IAiBvB,6CAA6C;IAC7C,OAAO,CAAC,cAAc;IAetB,8EAA8E;IAC9E,OAAO,CAAC,mBAAmB;CAS3B"}

package/dist/credentials/resolver.js

@@ -52,6 +52,8 @@ export class CredentialResolver {
                 return this.resolveGoogle(explicitKey);
             case "openrouter":
                 return this.resolveOpenRouter(explicitKey);
+            case "vercel":
+                return this.resolveVercelAIGateway(explicitKey);
             case "ollama":
             case "llama.cpp":
                 return this.resolveOllama();
@@ -259,6 +261,29 @@ export class CredentialResolver {
         return { source: "none" };
     }
     // ---------------------------------------------------------------------------
+    // Vercel AI Gateway
+    // ---------------------------------------------------------------------------
+    /**
+     * Search hierarchy for Vercel AI Gateway credentials:
+     *   1. Explicit config key
+     *   2. `AI_GATEWAY_API_KEY` env var
+     *   3. `VERCEL_OIDC_TOKEN` env var (available on Vercel deployments)
+     */
+    async resolveVercelAIGateway(explicitKey) {
+        if (explicitKey) {
+            return { apiKey: explicitKey, source: "config" };
+        }
+        const apiKey = process.env.AI_GATEWAY_API_KEY;
+        if (apiKey) {
+            return { apiKey, source: "env" };
+        }
+        const oidcToken = process.env.VERCEL_OIDC_TOKEN;
+        if (oidcToken) {
+            return { accessToken: oidcToken, source: "env" };
+        }
+        return { source: "none" };
+    }
+    // ---------------------------------------------------------------------------
     // Ollama (no auth needed)
     // ---------------------------------------------------------------------------
     /**
@@ -309,7 +334,7 @@ export class CredentialResolver {
         const awsCredentialsRaw = await this.readTextFile(awsCredentialsPath);
         if (awsCredentialsRaw !== null) {
             const defaultProfile = this.parseAwsIniSection(awsCredentialsRaw, "default");
-            const keyId = defaultProfile["aws_access_key_id"];
+            const keyId = defaultProfile.aws_access_key_id;
             if (keyId) {
                 const region = await this.resolveAwsRegion();
                 return { apiKey: keyId, source: "cli", path: awsCredentialsPath, metadata: { region } };
@@ -352,8 +377,8 @@ export class CredentialResolver {
         const configText = awsConfigRaw ?? (await this.readTextFile(join(this.home, ".aws", "config")));
         if (configText !== null) {
             // AWS config uses [profile default] for non-default profiles and [default] for the default
-            const section = this.parseAwsIniSection(configText, "profile default")["region"] ??
-                this.parseAwsIniSection(configText, "default")["region"];
+            const section = this.parseAwsIniSection(configText, "profile default").region ??
+                this.parseAwsIniSection(configText, "default").region;
             if (section) {
                 return section;
             }