@qmediat.io/gemini-code-context-mcp 1.3.2 → 1.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -7,6 +7,56 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [1.4.0] — 2026-04-20
11
+
12
+ **Model taxonomy — allowlist-first category system.** The v1.2.0–v1.3.2 defence against `nano-banana-pro-preview` (image-gen) resolving to `latest-pro-thinking` was a reactive substring blocklist (`NON_TEXT_GEN_MARKERS = ['banana', 'lyria', 'research', ...]`). Every new non-text-gen family Google shipped under a `pro` / `flash` token required a patch release. v1.4.0 flips the model: each model ID is matched against an explicit rule set that assigns one of nine functional categories (`text-reasoning`, `text-fast`, `text-lite`, `image-generation`, `audio-generation`, `video-generation`, `embedding`, `agent`, `unknown`). Tools declare a required category; the resolver refuses to dispatch outside that set. Unknown families land in `unknown` and are excluded from every alias until the taxonomy is extended — forcing a conscious patch release rather than silent admission.
13
+
14
+ **Why this is a minor bump (1.4.0 not 1.3.3)**: the `ResolvedModel` type exported from `src/types.ts` gains two required fields (`category`, `capabilities`). Internal consumers compile cleanly; external TS consumers (none documented) would see the addition as type-surface widening. Runtime behaviour is strictly safer — existing aliases work identically for legitimate use, and the only callers that see new behaviour are those passing an image-gen / audio-gen model ID where a text-gen model was expected (pre-v1.4.0 silently dispatched; now throws `ModelCategoryMismatchError` with an actionable message).
15
+
16
+ ### Breaking
17
+
18
+ Fail-fast resolver replaces v1.3.x's silent cross-category fallback. Three scenarios that previously produced (possibly mis-routed) calls now throw a clear error:
19
+
20
+ 1. **Literal model ID not in registry** — pre-v1.4.0: silent swap to `latest-pro`. v1.4.0: `Model 'X' is not available for this API key. Pass an alias (…) or a literal ID available on your tier.`
21
+ 2. **Alias has no model in its required category** — pre-v1.4.0: cascade `latest-pro-thinking` → `latest-pro` → `latest-flash` → `latest-lite` → first model. v1.4.0: `Alias 'X' could not be resolved — no model in category [...] is available for this API key.`
22
+ 3. **Literal model ID in the wrong category for the tool** — pre-v1.4.0: dispatched anyway (e.g. `code({ model: 'nano-banana-pro-preview' })` silently hit an image-gen model at ~10× text pricing). v1.4.0: `ModelCategoryMismatchError: Model 'X' is in category 'image-generation', but this tool requires: text-reasoning.`
23
+
24
+ Callers on non-default tiers where the required-category list was empty were the ones most likely to hit scenario 2 silently pre-v1.4.0. If your workflow depended on the implicit cross-category fall-through, pass an explicit model ID in the correct category or upgrade your Gemini tier (https://aistudio.google.com/apikey).
25
+
26
+ ### Added
27
+
28
+ - **Output-cap three-layer precedence** (replaces the v1.3.x hard-coded self-caps `ASK_MAX_OUTPUT_TOKENS_DEFAULT=8192` / `CODE_MAX_OUTPUT_TOKENS_DEFAULT=32768` that artificially limited responses below the model's advertised capacity):
29
+ - **Default (auto)** — `maxOutputTokens` omitted from the `generateContent` wire. Gemini uses its model-default cap which per [Google docs](https://ai.google.dev/gemini-api/docs/models/gemini-2.5-pro) equals the model's `outputTokenLimit` (65,536 for Gemini 3.x / 2.5 Pro). Short Q&A doesn't reserve full capacity; long responses get full 65k.
30
+ - **MCP-host env override** — `GEMINI_CODE_CONTEXT_FORCE_MAX_OUTPUT=true` pins every call at model's full capacity. Primary use case: code-review workloads producing long OLD/NEW diffs.
31
+ - **Per-call override** — new `maxOutputTokens` field on both `ask` and `code` schemas. Beats both default and env-force. Clamped to model's limit if larger.
32
+ - Budget reservation uses effective cap (explicit OR model limit) as worst-case regardless of which layer applies, so `GEMINI_DAILY_BUDGET_USD` stays a true upper bound.
33
+ - New env var documented in `docs/configuration.md`; full three-layer table + examples in `docs/models.md`.
34
+ - **`src/gemini/model-taxonomy.ts`** — new module with `ModelCategory` type, `CATEGORY_RULES` ordered pattern-allowlist, `categorizeModel(id)`, `extractCapabilityFlags(id, sdkMeta)`, `costTierOf(id)`, `isTextGenCategory(cat)`, and the exported `ModelCategoryMismatchError` class with actionable message pointing at `docs/models.md`.
35
+ - **`latest-vision` alias** — picks the newest vision-capable text model (prefers `text-reasoning`, falls back to `text-fast`). Previously users needed to know a specific Gemini 2.5 / 3 Pro model ID for screenshot analysis.
36
+ - **New response metadata fields** on `ask` / `code` structured content: `modelCategory` (string) and `modelCostTier` (`premium` | `standard` | `budget` | `unknown`). Use these for billing dashboards or to verify that an alias resolved to what you expected.
37
+ - **New docs — [`docs/models.md`](./docs/models.md)** — complete guide: category table with descriptions, alias contract, usage examples (code review, quick Q&A, vision analysis, explicit model IDs), failure-mode walkthroughs (wrong category error, unknown future family error), and the "when to extend the taxonomy" maintainer note.
38
+ - **48 new unit tests** (`test/unit/model-taxonomy.test.ts`) covering every current Gemini model's expected categorisation, precedence rules (the core invariant — `nano-banana-pro-preview` must resolve to `image-generation`, not `text-reasoning`), `unknown` fallback for future families, `costTierOf` + `extractCapabilityFlags` paths, and `ModelCategoryMismatchError` shape.
39
+ - **9 new resolver tests** in `test/unit/models.test.ts` covering v1.4.0 contract: `ResolvedModel` carries `category` + `capabilities`, `requiredCategory` rejects literal model IDs in the wrong category, alias path enforces category too, `latest-vision` picks vision-capable, `latest-lite` binds strictly to budget tier, unknown-category explicit ID throws under required-category gate, + `describeAlias` / `listAliases` public API tests.
40
+
41
+ ### Changed
42
+
43
+ - **`ResolvedModel` interface** (`src/types.ts`) gains `category: ModelCategory` and `capabilities: CapabilityFlags` required fields. Populated by `src/gemini/models.ts`'s `resolveModel` via `src/gemini/model-taxonomy.ts`.
44
+ - **`resolveModel(requested, client, opts?)`** (`src/gemini/models.ts`) accepts `opts.requiredCategory: readonly ModelCategory[]` — the set of categories this call-site accepts. Throws `ModelCategoryMismatchError` if the resolved model (alias-picked or literal) falls outside that set. Tools pass this parameter:
45
+ - `ask.tool.ts` → `['text-reasoning', 'text-fast', 'text-lite']` (any text tier)
46
+ - `code.tool.ts` → `['text-reasoning']` (strictest; coding benefits from reasoning tokens and we refuse to dispatch to fast/lite tiers for correctness)
47
+ - **Literal model ID fallback removed** — pre-v1.4.0, passing a literal ID that wasn't in the API-key's registry silently swapped to `latest-pro`, which could resolve to an image-gen model. v1.4.0 throws a clear error instead: `Model 'X' is not available for this API key. Pass an alias (…) or a literal ID available on your tier (…). See docs/models.md.`
48
+ - **Alias fallback across categories removed** — pre-v1.4.0, if `latest-pro-thinking` found nothing, it fell back to `latest-pro` → `latest-flash` → `latest-lite` → first model. This meant a registry with only image-gen pro models would return an image model for a code-review alias. v1.4.0 throws a clear error naming the required category and listing available categories for the API key.
49
+ - **Existing blocklist `NON_TEXT_GEN_MARKERS`** retained as belt-and-suspenders defence — runs AFTER categorisation. If a taxonomy rule erroneously classifies a model as text-gen but its ID matches a blocklist marker, the resolver logs and demotes it to `unknown`. Empirically fired once during testing for `gemini-2.5-flash-native-audio-preview-09-2025` (flash-token + audio-suffix combo); that pattern has since been added to the primary taxonomy rule set, so the belt-and-suspenders should no longer fire under the current model lineup.
50
+ - **New native-audio rule** in the taxonomy: `gemini-*-native-audio-*` → `audio-generation`. Surfaced by the belt-and-suspenders path during Phase 3 integration testing.
51
+ - **`docs/configuration.md`** alias table updated with category column and a link to the new `docs/models.md`.
52
+ - **`README.md`** gains an "Model aliases (v1.4.0+)" block explaining the category safety property.
53
+
54
+ ### Reviewer notes (not a code change)
55
+
56
+ - Implemented in five phases (taxonomy → resolver refactor → tool integration → docs → validate/PR), each locked behind user review checkpoint per global `CLAUDE.md` phase-by-phase rule.
57
+ - The allowlist-first design was chosen explicitly over the v1.2.0–v1.3.2 reactive blocklist after the user flagged the core concern: "never let `nano-banana` do my code review". Blocklists catch *known* offenders; allowlists refuse *everything unknown*. Google shipping a new `pro`-token image-gen family that we haven't classified is now a `HARD ERROR` with a clear upgrade path, not a silent pricing surprise.
58
+ - Belt-and-suspenders `NON_TEXT_GEN_MARKERS` blocklist retained even though the taxonomy is primary — shouldn't fire in practice, catches taxonomy bugs before they reach production.
59
+
10
60
  ## [1.3.2] — 2026-04-20
11
61
 
12
62
  Security-flavoured hotfix closing hint-poisoning attack surface flagged in PR #20 (v1.3.1) multi-round review. **Two review rounds on this hotfix itself** (PR #21 round-1 + round-2) refined the gate design — the initial substring fallback was itself bypassable and got tightened to prototype-based SDK provenance. `/6step` verified all findings closed end-to-end against a real `@google/genai` `ApiError` instance.
package/README.md CHANGED
@@ -64,6 +64,20 @@ See [`docs/getting-started.md`](./docs/getting-started.md) for a 3-minute walkth
64
64
 
65
65
  All tools accept an optional `workspace` path (defaults to `cwd`), `model` alias or literal ID, and glob overrides.
66
66
 
67
+ ### Model aliases (v1.4.0+)
68
+
69
+ Aliases are **category-safe** — they resolve against a known functional category (text-reasoning, text-fast, text-lite, etc.) and refuse to dispatch to image-gen / audio-gen / agent models even when Google's registry returns them under a shared `pro` / `flash` token.
70
+
71
+ | Alias | Category | Typical use |
72
+ |---|---|---|
73
+ | `latest-pro-thinking` *(default for `code`)* | `text-reasoning` + thinking | Code review, deep analysis |
74
+ | `latest-pro` | `text-reasoning` | Best pro-tier text model |
75
+ | `latest-flash` | `text-fast` | Fast Q&A, cheap |
76
+ | `latest-lite` | `text-lite` | Simplest / cheapest |
77
+ | `latest-vision` | `text-reasoning` ∪ `text-fast` + vision | Screenshot / image analysis |
78
+
79
+ Full contract, category table, and examples: [`docs/models.md`](./docs/models.md).
80
+
67
81
  ## Installation methods
68
82
 
69
83
  | Method | Config |
package/dist/config.d.ts CHANGED
@@ -20,6 +20,18 @@ export interface Config {
20
20
  maxFileSizeBytes: number;
21
21
  /** Opt-in anonymous usage telemetry (count per tool, no payloads). */
22
22
  telemetryEnabled: boolean;
23
+ /**
24
+ * When `true`, `ask` and `code` tools send `maxOutputTokens =
25
+ * modelOutputLimit` on every `generateContent` call (instead of omitting
26
+ * the field and relying on Gemini's model-default). Use this in MCP host
27
+ * configs where you want every call to run at the model's full output
28
+ * capacity — primary use case is code review that routinely produces
29
+ * long OLD/NEW diff blocks. Per-call `input.maxOutputTokens` still
30
+ * overrides (caller can cap a specific call lower). Default `false`
31
+ * (auto — Gemini decides response length based on query complexity).
32
+ * Controlled by `GEMINI_CODE_CONTEXT_FORCE_MAX_OUTPUT` env var.
33
+ */
34
+ forceMaxOutputTokens: boolean;
23
35
  /**
24
36
  * Client-side TPM (tokens-per-minute) throttle ceiling, per resolved model.
25
37
  * `0` disables the throttle entirely; positive integer caps how many input
@@ -1 +1 @@
1
- {"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,KAAK,YAAY,EAAe,MAAM,0BAA0B,CAAC;AAE1E,MAAM,WAAW,MAAM;IACrB,IAAI,EAAE,YAAY,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,cAAc,EAAE,MAAM,CAAC;IACvB,uDAAuD;IACvD,oBAAoB,EAAE,MAAM,CAAC;IAC7B,2CAA2C;IAC3C,gBAAgB,EAAE,MAAM,CAAC;IACzB,sEAAsE;IACtE,gBAAgB,EAAE,OAAO,CAAC;IAC1B;;;;;;;;;;OAUG;IACH,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAgBD,wBAAgB,UAAU,IAAI,MAAM,CAkCnC"}
1
+ {"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,KAAK,YAAY,EAAe,MAAM,0BAA0B,CAAC;AAE1E,MAAM,WAAW,MAAM;IACrB,IAAI,EAAE,YAAY,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,cAAc,EAAE,MAAM,CAAC;IACvB,uDAAuD;IACvD,oBAAoB,EAAE,MAAM,CAAC;IAC7B,2CAA2C;IAC3C,gBAAgB,EAAE,MAAM,CAAC;IACzB,sEAAsE;IACtE,gBAAgB,EAAE,OAAO,CAAC;IAC1B;;;;;;;;;;OAUG;IACH,oBAAoB,EAAE,OAAO,CAAC;IAC9B;;;;;;;;;;OAUG;IACH,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AA6BD,wBAAgB,UAAU,IAAI,MAAM,CAmCnC"}
package/dist/config.js CHANGED
@@ -16,6 +16,19 @@ function readFloatEnv(name, fallback) {
16
16
  const n = Number.parseFloat(raw);
17
17
  return Number.isFinite(n) ? n : fallback;
18
18
  }
19
+ /**
20
+ * Parse a boolean env var permissively. Accepts `true`/`1`/`yes`/`on`
21
+ * case-insensitively as `true`; everything else (including unset) is `false`.
22
+ * Strict equality to `'true'` (our pre-v1.4.0 pattern) surprised operators
23
+ * who copied values like `TRUE` / `1` from other docs.
24
+ */
25
+ function readBoolEnv(name) {
26
+ const raw = process.env[name];
27
+ if (!raw)
28
+ return false;
29
+ const v = raw.trim().toLowerCase();
30
+ return v === 'true' || v === '1' || v === 'yes' || v === 'on';
31
+ }
19
32
  export function loadConfig() {
20
33
  const auth = resolveAuth();
21
34
  // Default alias resolves to the newest Pro-class model that advertises
@@ -39,8 +52,9 @@ export function loadConfig() {
39
52
  cacheMinTokens: readIntEnv('GEMINI_CODE_CONTEXT_CACHE_MIN_TOKENS', 1024),
40
53
  maxFilesPerWorkspace: readIntEnv('GEMINI_CODE_CONTEXT_MAX_FILES', 2000),
41
54
  maxFileSizeBytes: readIntEnv('GEMINI_CODE_CONTEXT_MAX_FILE_SIZE', 1_000_000),
42
- telemetryEnabled: process.env.GEMINI_CODE_CONTEXT_TELEMETRY === 'true',
55
+ telemetryEnabled: readBoolEnv('GEMINI_CODE_CONTEXT_TELEMETRY'),
43
56
  tpmThrottleLimit,
57
+ forceMaxOutputTokens: readBoolEnv('GEMINI_CODE_CONTEXT_FORCE_MAX_OUTPUT'),
44
58
  };
45
59
  }
46
60
  //# sourceMappingURL=config.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAqB,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAkC1E,SAAS,UAAU,CAAC,IAAY,EAAE,QAAgB;IAChD,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC9B,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,QAAQ,CAAC;IAC9C,MAAM,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;IACnC,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;AAC3C,CAAC;AAED,SAAS,YAAY,CAAC,IAAY,EAAE,QAAgB;IAClD,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC9B,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,QAAQ,CAAC;IAC9C,MAAM,CAAC,GAAG,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;IACjC,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;AAC3C,CAAC;AAED,MAAM,UAAU,UAAU;IACxB,MAAM,IAAI,GAAG,WAAW,EAAE,CAAC;IAE3B,uEAAuE;IACvE,4EAA4E;IAC5E,6EAA6E;IAC7E,0EAA0E;IAC1E,MAAM,YAAY,GAChB,OAAO,CAAC,GAAG,CAAC,iCAAiC,IAAI,IAAI,CAAC,YAAY,IAAI,qBAAqB,CAAC;IAE9F,MAAM,WAAW,GAAG,YAAY,CAC9B,yBAAyB,EACzB,IAAI,CAAC,cAAc,IAAI,MAAM,CAAC,iBAAiB,CAChD,CAAC;IAEF,uEAAuE;IACvE,sEAAsE;IACtE,oEAAoE;IACpE,yEAAyE;IACzE,6CAA6C;IAC7C,MAAM,cAAc,GAAG,UAAU,CAAC,wCAAwC,EAAE,MAAM,CAAC,CAAC;IACpF,MAAM,gBAAgB,GAAG,cAAc,IAAI,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,MAAM,CAAC;IAEvE,OAAO;QACL,IAAI;QACJ,YAAY;QACZ,cAAc,EAAE,WAAW;QAC3B,eAAe,EAAE,UAAU,CAAC,uCAAuC,EAAE,IAAI,CAAC;QAC1E,cAAc,EAAE,UAAU,CAAC,sCAAsC,EAAE,IAAI,CAAC;QACxE,oBAAoB,EAAE,UAAU,CAAC,+BAA+B,EAAE,IAAI,CAAC;QACvE,gBAAgB,EAAE,UAAU,CAAC,mCAAmC,EAAE,SAAS,CAAC;QAC5E,gBAAgB,EAAE,OAAO,CAAC,GAAG,CAAC,6BAA6B,KAAK,MAAM;QACtE,gBAAgB;KACjB,CAAC;AACJ,CAAC"}
1
+ {"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAqB,WAAW,EAAE,MAAM,0BAA0B,CAAC;AA8C1E,SAAS,UAAU,CAAC,IAAY,EAAE,QAAgB;IAChD,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC9B,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,QAAQ,CAAC;IAC9C,MAAM,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;IACnC,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;AAC3C,CAAC;AAED,SAAS,YAAY,CAAC,IAAY,EAAE,QAAgB;IAClD,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC9B,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,QAAQ,CAAC;IAC9C,MAAM,CAAC,GAAG,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;IACjC,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;AAC3C,CAAC;AAED;;;;;GAKG;AACH,SAAS,WAAW,CAAC,IAAY;IAC/B,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC9B,IAAI,CAAC,GAAG;QAAE,OAAO,KAAK,CAAC;IACvB,MAAM,CAAC,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACnC,OAAO,CAAC,KAAK,MAAM,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,KAAK,IAAI,CAAC,KAAK,IAAI,CAAC;AAChE,CAAC;AAED,MAAM,UAAU,UAAU;IACxB,MAAM,IAAI,GAAG,WAAW,EAAE,CAAC;IAE3B,uEAAuE;IACvE,4EAA4E;IAC5E,6EAA6E;IAC7E,0EAA0E;IAC1E,MAAM,YAAY,GAChB,OAAO,CAAC,GAAG,CAAC,iCAAiC,IAAI,IAAI,CAAC,YAAY,IAAI,qBAAqB,CAAC;IAE9F,MAAM,WAAW,GAAG,YAAY,CAC9B,yBAAyB,EACzB,IAAI,CAAC,cAAc,IAAI,MAAM,CAAC,iBAAiB,CAChD,CAAC;IAEF,uEAAuE;IACvE,sEAAsE;IACtE,oEAAoE;IACpE,yEAAyE;IACzE,6CAA6C;IAC7C,MAAM,cAAc,GAAG,UAAU,CAAC,wCAAwC,EAAE,MAAM,CAAC,CAAC;IACpF,MAAM,gBAAgB,GAAG,cAAc,IAAI,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,MAAM,CAAC;IAEvE,OAAO;QACL,IAAI;QACJ,YAAY;QACZ,cAAc,EAAE,WAAW;QAC3B,eAAe,EAAE,UAAU,CAAC,uCAAuC,EAAE,IAAI,CAAC;QAC1E,cAAc,EAAE,UAAU,CAAC,sCAAsC,EAAE,IAAI,CAAC;QACxE,oBAAoB,EAAE,UAAU,CAAC,+BAA+B,EAAE,IAAI,CAAC;QACvE,gBAAgB,EAAE,UAAU,CAAC,mCAAmC,EAAE,SAAS,CAAC;QAC5E,gBAAgB,EAAE,WAAW,CAAC,+BAA+B,CAAC;QAC9D,gBAAgB;QAChB,oBAAoB,EAAE,WAAW,CAAC,sCAAsC,CAAC;KAC1E,CAAC;AACJ,CAAC"}
@@ -0,0 +1,94 @@
1
+ /**
2
+ * Model taxonomy — maps Gemini model IDs to functional categories and
3
+ * capability flags, so the resolver can refuse to dispatch (e.g.) a code
4
+ * review to an image-generation model that happens to share the `pro` token
5
+ * with text-gen models.
6
+ *
7
+ * Design principle: **allowlist-first**. Each category has an explicit list
8
+ * of regex patterns. Unrecognised model IDs fall back to `unknown` — the
9
+ * resolver then refuses to bind them to any alias. This is the inverse of
10
+ * the v1.2.0 approach (blocklist of substrings like `banana`, `lyria`,
11
+ * `research`), which required reactive maintenance whenever Google shipped
12
+ * a new non-text-gen family under a `pro`/`flash` token. Allowlist forces
13
+ * a conscious addition of new families rather than silently admitting them.
14
+ *
15
+ * When Google ships a new model family:
16
+ * 1. Update `CATEGORY_RULES` with the canonical pattern → category entry.
17
+ * 2. Update `docs/models.md` with the new row.
18
+ * 3. Ship a patch release — users who haven't upgraded get the `unknown`
19
+ * path (aliases fail with actionable error, explicit IDs still work
20
+ * via direct-pass).
21
+ *
22
+ * The blocklist from v1.2.0 (`NON_TEXT_GEN_MARKERS`) is retained in
23
+ * `models.ts` as belt-and-suspenders defence-in-depth — runs AFTER
24
+ * categorisation to catch any bugs that would let a mis-categorised model
25
+ * through. Shouldn't fire in practice.
26
+ */
27
+ /**
28
+ * Functional category a model belongs to. Tools bind to required categories
29
+ * (e.g. `code` needs `text-reasoning`); the resolver refuses to return
30
+ * models outside the required set. Unknown category = no alias picks it.
31
+ */
32
+ export type ModelCategory = 'text-reasoning' | 'text-fast' | 'text-lite' | 'image-generation' | 'audio-generation' | 'video-generation' | 'embedding' | 'agent' | 'unknown';
33
+ /**
34
+ * Orthogonal capability flags. Multiple can apply to a single model. Used
35
+ * by the resolver to filter WITHIN a category (e.g. `latest-pro-thinking`
36
+ * needs `text-reasoning` + `supportsThinking: true`).
37
+ */
38
+ export interface CapabilityFlags {
39
+ readonly supportsThinking: boolean;
40
+ readonly supportsVision: boolean;
41
+ readonly supportsCodeExecution: boolean;
42
+ /** `premium` (pro-tier), `standard` (flash), `budget` (lite). */
43
+ readonly costTier: 'premium' | 'standard' | 'budget' | 'unknown';
44
+ }
45
+ /**
46
+ * Classify a model by ID. Returns `unknown` for any ID that doesn't match
47
+ * an explicit rule — the resolver then refuses to bind this model to any
48
+ * text-* alias, forcing either a patch release (to extend the rules) or
49
+ * an explicit model ID pass-through from the caller.
50
+ */
51
+ export declare function categorizeModel(modelId: string): ModelCategory;
52
+ /**
53
+ * Derive the cost tier from the model ID via the same rule set. When no
54
+ * rule matches, tier is `unknown` — the resolver treats this as
55
+ * ineligible for tiered aliases (`latest-pro`, `latest-flash`, `latest-lite`).
56
+ */
57
+ export declare function costTierOf(modelId: string): CapabilityFlags['costTier'];
58
+ /**
59
+ * Extract capability flags from the model ID plus any metadata already
60
+ * available (supportsThinking is surfaced by `@google/genai`'s `models.list`,
61
+ * vision / code-execution are inferred from ID patterns since the SDK
62
+ * doesn't advertise them consistently).
63
+ */
64
+ export declare function extractCapabilityFlags(modelId: string, sdkMetadata: {
65
+ readonly supportsThinking: boolean;
66
+ }): CapabilityFlags;
67
+ /**
68
+ * True iff `category` is one of the three text-gen tiers — the categories
69
+ * that `ask` / `code` tools accept via their `requiredCategory` option.
70
+ * Exposed for external diagnostics / tooling (`docs/models.md` alias table
71
+ * derivations, integration tests); the resolver itself does an explicit
72
+ * `requiredCategory.includes(...)` check per call rather than routing
73
+ * through this helper, since `requiredCategory` can legitimately be a
74
+ * narrower subset (`code` → `['text-reasoning']` only).
75
+ */
76
+ export declare function isTextGenCategory(category: ModelCategory): boolean;
77
+ /**
78
+ * Error thrown when a resolver call requests a category that the resolved
79
+ * model does NOT satisfy. Actionable message: tells the caller what the
80
+ * resolved model's category actually is and which categories the tool
81
+ * accepts, so they can either pick a different model or file an issue if
82
+ * they believe the taxonomy is wrong.
83
+ */
84
+ export declare class ModelCategoryMismatchError extends Error {
85
+ readonly modelId: string;
86
+ readonly actualCategory: ModelCategory;
87
+ readonly requiredCategory: readonly ModelCategory[];
88
+ constructor(options: {
89
+ modelId: string;
90
+ actualCategory: ModelCategory;
91
+ requiredCategory: readonly ModelCategory[];
92
+ });
93
+ }
94
+ //# sourceMappingURL=model-taxonomy.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"model-taxonomy.d.ts","sourceRoot":"","sources":["../../src/gemini/model-taxonomy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH;;;;GAIG;AACH,MAAM,MAAM,aAAa,GACrB,gBAAgB,GAChB,WAAW,GACX,WAAW,GACX,kBAAkB,GAClB,kBAAkB,GAClB,kBAAkB,GAClB,WAAW,GACX,OAAO,GACP,SAAS,CAAC;AAEd;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;IACnC,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,qBAAqB,EAAE,OAAO,CAAC;IACxC,iEAAiE;IACjE,QAAQ,CAAC,QAAQ,EAAE,SAAS,GAAG,UAAU,GAAG,QAAQ,GAAG,SAAS,CAAC;CAClE;AAoFD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,aAAa,CAM9D;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,eAAe,CAAC,UAAU,CAAC,CAKvE;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,MAAM,EACf,WAAW,EAAE;IAAE,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAA;CAAE,GAClD,eAAe,CAuBjB;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,aAAa,GAAG,OAAO,CAElE;AAED;;;;;;GAMG;AACH,qBAAa,0BAA2B,SAAQ,KAAK;IACnD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,cAAc,EAAE,aAAa,CAAC;IACvC,QAAQ,CAAC,gBAAgB,EAAE,SAAS,aAAa,EAAE,CAAC;gBAExC,OAAO,EAAE;QACnB,OAAO,EAAE,MAAM,CAAC;QAChB,cAAc,EAAE,aAAa,CAAC;QAC9B,gBAAgB,EAAE,SAAS,aAAa,EAAE,CAAC;KAC5C;CAWF"}
@@ -0,0 +1,176 @@
1
+ /**
2
+ * Model taxonomy — maps Gemini model IDs to functional categories and
3
+ * capability flags, so the resolver can refuse to dispatch (e.g.) a code
4
+ * review to an image-generation model that happens to share the `pro` token
5
+ * with text-gen models.
6
+ *
7
+ * Design principle: **allowlist-first**. Each category has an explicit list
8
+ * of regex patterns. Unrecognised model IDs fall back to `unknown` — the
9
+ * resolver then refuses to bind them to any alias. This is the inverse of
10
+ * the v1.2.0 approach (blocklist of substrings like `banana`, `lyria`,
11
+ * `research`), which required reactive maintenance whenever Google shipped
12
+ * a new non-text-gen family under a `pro`/`flash` token. Allowlist forces
13
+ * a conscious addition of new families rather than silently admitting them.
14
+ *
15
+ * When Google ships a new model family:
16
+ * 1. Update `CATEGORY_RULES` with the canonical pattern → category entry.
17
+ * 2. Update `docs/models.md` with the new row.
18
+ * 3. Ship a patch release — users who haven't upgraded get the `unknown`
19
+ * path (aliases fail with actionable error, explicit IDs still work
20
+ * via direct-pass).
21
+ *
22
+ * The blocklist from v1.2.0 (`NON_TEXT_GEN_MARKERS`) is retained in
23
+ * `models.ts` as belt-and-suspenders defence-in-depth — runs AFTER
24
+ * categorisation to catch any bugs that would let a mis-categorised model
25
+ * through. Shouldn't fire in practice.
26
+ */
27
+ const CATEGORY_RULES = [
28
+ // === Image generation — MUST come before pro/flash text rules ===
29
+ // `nano-banana-*` is Google's image-gen family (pro/flash tiers), IDs
30
+ // like `nano-banana-pro-preview`. Shares the `pro` token with text models
31
+ // but bills at the image tier (~10× text rates).
32
+ { pattern: /^nano-banana/i, category: 'image-generation', costTier: 'premium' },
33
+ // `*-image` suffix (e.g. `gemini-3-pro-image`) identifies Gemini's native
34
+ // image-output variants.
35
+ { pattern: /-image(?:-|$)/i, category: 'image-generation', costTier: 'premium' },
36
+ // Google's Imagen family — dedicated image generation.
37
+ { pattern: /^imagen-/i, category: 'image-generation', costTier: 'premium' },
38
+ // === Audio generation ===
39
+ // Lyria = Google's music generation family (`lyria-3-pro-preview` etc.).
40
+ { pattern: /^lyria-/i, category: 'audio-generation', costTier: 'premium' },
41
+ // TTS variants — any model with `-tts` suffix or `text-to-speech` in ID.
42
+ // Token-boundary anchoring prevents `-tts-like-foo` false positives.
43
+ { pattern: /(?:^|-)tts(?:-|$)/i, category: 'audio-generation', costTier: 'standard' },
44
+ { pattern: /(?:^|-)text-to-speech(?:-|$)/i, category: 'audio-generation', costTier: 'standard' },
45
+ // Native-audio variants (`gemini-2.5-flash-native-audio-preview-*`) —
46
+ // dialog-native audio generation. Shares `flash` token with text-gen
47
+ // models; must classify before the flash rule.
48
+ { pattern: /(?:^|-)native-audio(?:-|$)/i, category: 'audio-generation', costTier: 'standard' },
49
+ // === Video generation ===
50
+ // Veo = Google's video generation family (`veo-3`, `veo-3.1` etc.).
51
+ { pattern: /^veo-/i, category: 'video-generation', costTier: 'premium' },
52
+ // === Multimodal Live API (bidirectional streaming) ===
53
+ // `gemini-*-live-*` (e.g. `gemini-2.0-flash-live-001`) uses the
54
+ // `bidiGenerateContent` WebRTC/streaming API, NOT `generateContent`.
55
+ // Dispatching a text prompt here returns 400 or an unexpected response
56
+ // shape. Must classify before the flash/pro text rules to avoid
57
+ // admission as text-fast. `agent` category signals "not drop-in
58
+ // replaceable with a text model" (flagged by GPT PR #22 review).
59
+ { pattern: /(?:^|-)live(?:-|$)/i, category: 'agent', costTier: 'standard' },
60
+ // === Embeddings ===
61
+ // Token-boundary anchoring: matches `text-embedding-004`,
62
+ // `gemini-embedding-001` etc., rejects hypothetical `foo-embedding-like-helper`.
63
+ { pattern: /(?:^|-)embedding(?:-|$)/i, category: 'embedding', costTier: 'budget' },
64
+ { pattern: /^text-embedding/i, category: 'embedding', costTier: 'budget' },
65
+ // === Agents (not drop-in replaceable) ===
66
+ // Deep Research — a specialised research agent, not a conversational model.
67
+ { pattern: /(?:^|-)deep-research(?:-|$)/i, category: 'agent', costTier: 'premium' },
68
+ { pattern: /(?:^|-)research(?:-|$)/i, category: 'agent', costTier: 'premium' },
69
+ // `customtools` variants require a `tools` param on every call; mis-used
70
+ // as a conversational model returns errors.
71
+ { pattern: /(?:^|-)customtools(?:-|$)/i, category: 'agent', costTier: 'premium' },
72
+ // === Text tiers — AFTER all specialisations above ===
73
+ // Lite (budget / smallest). Matches `gemini-3-flash-lite`, `gemini-flash-lite`,
74
+ // `flash-lite`. The single `-lite` rule is a superset of the previously
75
+ // also-listed `flash-lite` rule — the latter was unreachable dead code
76
+ // (Grok PR #22 review finding F); removed.
77
+ { pattern: /-lite(?:-|$)/i, category: 'text-lite', costTier: 'budget' },
78
+ // Flash (standard speed tier).
79
+ { pattern: /^gemini-.*-flash/i, category: 'text-fast', costTier: 'standard' },
80
+ { pattern: /-flash(?:-|$)/i, category: 'text-fast', costTier: 'standard' },
81
+ // Pro (reasoning / premium tier). Only reaches here if no specialisation
82
+ // above claimed the model. The `^gemini-pro` rule previously at the end
83
+ // of this list was unreachable because `/-pro(?:-|$)/i` already matches
84
+ // `gemini-pro` (Grok PR #22 review finding K); removed.
85
+ { pattern: /^gemini-.*-pro/i, category: 'text-reasoning', costTier: 'premium' },
86
+ { pattern: /-pro(?:-|$)/i, category: 'text-reasoning', costTier: 'premium' },
87
+ ];
88
+ /**
89
+ * Classify a model by ID. Returns `unknown` for any ID that doesn't match
90
+ * an explicit rule — the resolver then refuses to bind this model to any
91
+ * text-* alias, forcing either a patch release (to extend the rules) or
92
+ * an explicit model ID pass-through from the caller.
93
+ */
94
+ export function categorizeModel(modelId) {
95
+ if (typeof modelId !== 'string' || modelId.length === 0)
96
+ return 'unknown';
97
+ for (const rule of CATEGORY_RULES) {
98
+ if (rule.pattern.test(modelId))
99
+ return rule.category;
100
+ }
101
+ return 'unknown';
102
+ }
103
+ /**
104
+ * Derive the cost tier from the model ID via the same rule set. When no
105
+ * rule matches, tier is `unknown` — the resolver treats this as
106
+ * ineligible for tiered aliases (`latest-pro`, `latest-flash`, `latest-lite`).
107
+ */
108
+ export function costTierOf(modelId) {
109
+ for (const rule of CATEGORY_RULES) {
110
+ if (rule.pattern.test(modelId))
111
+ return rule.costTier;
112
+ }
113
+ return 'unknown';
114
+ }
115
+ /**
116
+ * Extract capability flags from the model ID plus any metadata already
117
+ * available (supportsThinking is surfaced by `@google/genai`'s `models.list`,
118
+ * vision / code-execution are inferred from ID patterns since the SDK
119
+ * doesn't advertise them consistently).
120
+ */
121
+ export function extractCapabilityFlags(modelId, sdkMetadata) {
122
+ // Single categorisation — CATEGORY_RULES runs a regex loop on every call,
123
+ // and capability derivation previously invoked `categorizeModel` four
124
+ // times per call. Classify once, then derive flags from the local
125
+ // `category` variable (Copilot PR #22 review).
126
+ const category = categorizeModel(modelId);
127
+ return {
128
+ supportsThinking: sdkMetadata.supportsThinking,
129
+ // Most current Gemini text models accept image input (multimodal by
130
+ // default). Only *-lite variants and embedding models don't. Heuristic
131
+ // matches Google's documented vision support table as of 2026-04.
132
+ supportsVision: category !== 'embedding' &&
133
+ category !== 'audio-generation' &&
134
+ category !== 'video-generation' &&
135
+ !/-lite(?:-|$)/i.test(modelId),
136
+ // Code execution is an explicit tool flag on generateContent; all
137
+ // current Gemini 2.5+/3.x text models support it. Exclude image /
138
+ // audio / video variants and embeddings.
139
+ supportsCodeExecution: category === 'text-reasoning' || category === 'text-fast' || category === 'text-lite',
140
+ costTier: costTierOf(modelId),
141
+ };
142
+ }
143
+ /**
144
+ * True iff `category` is one of the three text-gen tiers — the categories
145
+ * that `ask` / `code` tools accept via their `requiredCategory` option.
146
+ * Exposed for external diagnostics / tooling (`docs/models.md` alias table
147
+ * derivations, integration tests); the resolver itself does an explicit
148
+ * `requiredCategory.includes(...)` check per call rather than routing
149
+ * through this helper, since `requiredCategory` can legitimately be a
150
+ * narrower subset (`code` → `['text-reasoning']` only).
151
+ */
152
+ export function isTextGenCategory(category) {
153
+ return category === 'text-reasoning' || category === 'text-fast' || category === 'text-lite';
154
+ }
155
+ /**
156
+ * Error thrown when a resolver call requests a category that the resolved
157
+ * model does NOT satisfy. Actionable message: tells the caller what the
158
+ * resolved model's category actually is and which categories the tool
159
+ * accepts, so they can either pick a different model or file an issue if
160
+ * they believe the taxonomy is wrong.
161
+ */
162
+ export class ModelCategoryMismatchError extends Error {
163
+ modelId;
164
+ actualCategory;
165
+ requiredCategory;
166
+ constructor(options) {
167
+ const required = options.requiredCategory.join(' | ');
168
+ super(`Model '${options.modelId}' is in category '${options.actualCategory}', but this tool requires: ${required}. Pass a model with a compatible category (e.g. 'latest-pro' or a literal model ID from docs/models.md). If you believe '${options.modelId}' is mis-categorised, file an issue at https://github.com/qmediat/gemini-code-context-mcp/issues.`);
169
+ this.name = 'ModelCategoryMismatchError';
170
+ this.modelId = options.modelId;
171
+ this.actualCategory = options.actualCategory;
172
+ this.requiredCategory = options.requiredCategory;
173
+ Object.setPrototypeOf(this, ModelCategoryMismatchError.prototype);
174
+ }
175
+ }
176
+ //# sourceMappingURL=model-taxonomy.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"model-taxonomy.js","sourceRoot":"","sources":["../../src/gemini/model-taxonomy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AA6CH,MAAM,cAAc,GAA4B;IAC9C,mEAAmE;IACnE,sEAAsE;IACtE,0EAA0E;IAC1E,iDAAiD;IACjD,EAAE,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,kBAAkB,EAAE,QAAQ,EAAE,SAAS,EAAE;IAC/E,0EAA0E;IAC1E,yBAAyB;IACzB,EAAE,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,kBAAkB,EAAE,QAAQ,EAAE,SAAS,EAAE;IAChF,uDAAuD;IACvD,EAAE,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,kBAAkB,EAAE,QAAQ,EAAE,SAAS,EAAE;IAE3E,2BAA2B;IAC3B,yEAAyE;IACzE,EAAE,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,kBAAkB,EAAE,QAAQ,EAAE,SAAS,EAAE;IAC1E,yEAAyE;IACzE,qEAAqE;IACrE,EAAE,OAAO,EAAE,oBAAoB,EAAE,QAAQ,EAAE,kBAAkB,EAAE,QAAQ,EAAE,UAAU,EAAE;IACrF,EAAE,OAAO,EAAE,+BAA+B,EAAE,QAAQ,EAAE,kBAAkB,EAAE,QAAQ,EAAE,UAAU,EAAE;IAChG,sEAAsE;IACtE,qEAAqE;IACrE,+CAA+C;IAC/C,EAAE,OAAO,EAAE,6BAA6B,EAAE,QAAQ,EAAE,kBAAkB,EAAE,QAAQ,EAAE,UAAU,EAAE;IAE9F,2BAA2B;IAC3B,oEAAoE;IACpE,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,kBAAkB,EAAE,QAAQ,EAAE,SAAS,EAAE;IAExE,wDAAwD;IACxD,gEAAgE;IAChE,qEAAqE;IACrE,uEAAuE;IACvE,gEAAgE;IAChE,gEAAgE;IAChE,iEAAiE;IACjE,EAAE,OAAO,EAAE,qBAAqB,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE;IAE3E,qBAAqB;IACrB,0DAA0D;IAC1D,iFAAiF;IACjF,EAAE,OAAO,EAAE,0BAA0B,EAAE,QAAQ,EAAE,WAAW,EAAE,QAAQ,EAAE,QAAQ,EAAE;IAClF,EAAE,OAAO,EAAE,kBAAkB,EAAE,QAAQ,EAAE,WAAW,EAAE,QAAQ,EAAE,QAAQ,EAAE;IAE1E,2CAA2C;IAC3C,4EAA4E;IAC5E,EAAE,OAAO,EAAE,8BAA8B,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE;IACnF,EAAE,OAAO,EAAE,yBAAyB,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE;IAC9E,yEAAyE;IACzE,4CAA4C;IAC5C,EAAE,OAAO,EAAE,4BAA4B,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE;IAEjF,uDAAuD;IACvD,gFAAgF;IAChF,wEAAwE;IACxE,uEAAuE;IACvE,2CAA2C;IAC3C,EAAE,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,WAAW,EAAE,QAAQ,EAAE,QAAQ,EAAE;IACvE,+BAA+B;IAC/B,EAAE,OAAO,EAAE,mBAAmB,EAAE,QAAQ,EAAE,WAAW,EAAE,QAAQ,EAAE,UAAU,EAAE;IAC7E,EAAE,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,WAAW,EAAE,QAAQ,EAAE,UAAU,EAAE;IAC1E,yEAAyE;IACzE,wEAAwE;IACxE,wEAAwE;IACxE,wDAAwD;IACxD,EAAE,OAAO,EAAE,iBAAiB,EAAE,QAAQ,EAAE,gBAAgB,EAAE,QAAQ,EAAE,SAAS,EAAE;IAC/E,EAAE,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,gBAAgB,EAAE,QAAQ,EAAE,SAAS,EAAE;CAC7E,CAAC;AAEF;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,OAAe;IAC7C,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IAC1E,KAAK,MAAM,IAAI,IAAI,cAAc,EAAE,CAAC;QAClC,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC;YAAE,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvD,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAC,OAAe;IACxC,KAAK,MAAM,IAAI,IAAI,cAAc,EAAE,CAAC;QAClC,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC;YAAE,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvD,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CACpC,OAAe,EACf,WAAmD;IAEnD,0EAA0E;IAC1E,sEAAsE;IACtE,kEAAkE;IAClE,+CAA+C;IAC/C,MAAM,QAAQ,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC;IAC1C,OAAO;QACL,gBAAgB,EAAE,WAAW,CAAC,gBAAgB;QAC9C,oEAAoE;QACpE,uEAAuE;QACvE,kEAAkE;QAClE,cAAc,EACZ,QAAQ,KAAK,WAAW;YACxB,QAAQ,KAAK,kBAAkB;YAC/B,QAAQ,KAAK,kBAAkB;YAC/B,CAAC,eAAe,CAAC,IAAI,CAAC,OAAO,CAAC;QAChC,kEAAkE;QAClE,kEAAkE;QAClE,yCAAyC;QACzC,qBAAqB,EACnB,QAAQ,KAAK,gBAAgB,IAAI,QAAQ,KAAK,WAAW,IAAI,QAAQ,KAAK,WAAW;QACvF,QAAQ,EAAE,UAAU,CAAC,OAAO,CAAC;KAC9B,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,iBAAiB,CAAC,QAAuB;IACvD,OAAO,QAAQ,KAAK,gBAAgB,IAAI,QAAQ,KAAK,WAAW,IAAI,QAAQ,KAAK,WAAW,CAAC;AAC/F,CAAC;AAED;;;;;;GAMG;AACH,MAAM,OAAO,0BAA2B,SAAQ,KAAK;IAC1C,OAAO,CAAS;IAChB,cAAc,CAAgB;IAC9B,gBAAgB,CAA2B;IAEpD,YAAY,OAIX;QACC,MAAM,QAAQ,GAAG,OAAO,CAAC,gBAAgB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACtD,KAAK,CACH,UAAU,OAAO,CAAC,OAAO,qBAAqB,OAAO,CAAC,cAAc,8BAA8B,QAAQ,4HAA4H,OAAO,CAAC,OAAO,mGAAmG,CACzV,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,4BAA4B,CAAC;QACzC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;QAC/B,IAAI,CAAC,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC;QAC7C,IAAI,CAAC,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC;QACjD,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,0BAA0B,CAAC,SAAS,CAAC,CAAC;IACpE,CAAC;CACF"}
@@ -1,23 +1,81 @@
1
1
  /**
2
2
  * Alias resolution for model selection.
3
3
  *
4
- * Users pass either an alias (`latest-pro`, `latest-flash`, `latest-pro-thinking`)
5
- * or a literal model ID (`gemini-3-pro-preview`). We resolve to the best available
6
- * model for the current API key and log if we fell back because the requested
7
- * model isn't reachable.
4
+ * Users pass either an alias (`latest-pro`, `latest-flash`, `latest-pro-thinking`,
5
+ * `latest-lite`, `latest-vision`) or a literal model ID (`gemini-3-pro-preview`).
6
+ * We resolve to the best available model for the current API key.
7
+ *
8
+ * v1.4.0: category-based filtering. Each alias declares the set of
9
+ * taxonomy categories it accepts. The resolver picks only from models
10
+ * whose category is in the accepted set — a pro-tier image-gen model
11
+ * (e.g. `nano-banana-pro-preview`) is NO LONGER eligible for
12
+ * `latest-pro-thinking` even if it shares the `pro` token with text-gen
13
+ * models. Literal model IDs ALSO go through a category check against the
14
+ * tool's required category — passing `model: "nano-banana-pro-preview"`
15
+ * to `code` throws `ModelCategoryMismatchError` with an actionable message.
16
+ *
17
+ * See `src/gemini/model-taxonomy.ts` for the category rule set and
18
+ * `docs/models.md` for the user-facing alias → category contract.
8
19
  */
9
20
  import type { GoogleGenAI } from '@google/genai';
10
21
  import type { ResolvedModel } from '../types.js';
11
- import { type ModelInfo } from './model-registry.js';
22
+ import { type CapabilityFlags, type ModelCategory } from './model-taxonomy.js';
12
23
  declare const ALIASES: {
13
- readonly 'latest-pro': (models: ModelInfo[]) => ModelInfo | undefined;
14
- readonly 'latest-pro-thinking': (models: ModelInfo[]) => ModelInfo | undefined;
15
- readonly 'latest-flash': (models: ModelInfo[]) => ModelInfo | undefined;
16
- readonly 'latest-lite': (models: ModelInfo[]) => ModelInfo | undefined;
24
+ readonly 'latest-pro': {
25
+ readonly acceptedCategories: readonly ["text-reasoning"];
26
+ readonly description: "latest pro-tier text-reasoning model";
27
+ };
28
+ readonly 'latest-pro-thinking': {
29
+ readonly acceptedCategories: readonly ["text-reasoning"];
30
+ readonly capabilityFilter: (flags: CapabilityFlags) => boolean;
31
+ readonly description: "latest pro-tier text-reasoning model with thinking support";
32
+ };
33
+ readonly 'latest-flash': {
34
+ readonly acceptedCategories: readonly ["text-fast"];
35
+ readonly description: "latest flash-tier (fast text-gen) model";
36
+ };
37
+ readonly 'latest-lite': {
38
+ readonly acceptedCategories: readonly ["text-lite"];
39
+ readonly description: "latest lite-tier (budget text-gen) model";
40
+ };
41
+ readonly 'latest-vision': {
42
+ readonly acceptedCategories: readonly ["text-reasoning", "text-fast"];
43
+ readonly capabilityFilter: (flags: CapabilityFlags) => boolean;
44
+ readonly description: "latest vision-capable text-gen model (prefers pro tier)";
45
+ };
17
46
  };
18
47
  export type Alias = keyof typeof ALIASES;
19
48
  export declare function isAlias(value: string): value is Alias;
20
- export declare function resolveModel(requested: string, client: GoogleGenAI): Promise<ResolvedModel>;
49
+ /**
50
+ * Options for `resolveModel`. Tools pass `requiredCategory` to assert the
51
+ * tool's category contract — the resolver throws `ModelCategoryMismatchError`
52
+ * if the resolved model doesn't satisfy it (even when the user passed a
53
+ * literal model ID). Omit to skip the category check (e.g. internal utility
54
+ * callers).
55
+ */
56
+ export interface ResolveModelOptions {
57
+ /**
58
+ * Tool's accepted category set. The resolved model's `category` MUST be
59
+ * in this list. When unset, any category is accepted (back-compat with
60
+ * callers that don't enforce a contract).
61
+ */
62
+ readonly requiredCategory?: readonly ModelCategory[];
63
+ }
64
+ export declare function resolveModel(requested: string, client: GoogleGenAI, options?: ResolveModelOptions): Promise<ResolvedModel>;
21
65
  export declare function listAliases(): readonly Alias[];
66
+ /**
67
+ * Alias contract for documentation / diagnostics. Stable public API —
68
+ * kept in parity with `docs/models.md`. Returning a fresh copy per call so
69
+ * consumers can't mutate module state — even though the source array is
70
+ * `as const` (`readonly` at type level), a TypeScript cast would let a
71
+ * consumer mutate the live ALIASES table and corrupt future resolver calls.
72
+ * Spread-copy `[...spec.acceptedCategories]` makes the boundary explicit.
73
+ */
74
+ export declare function describeAlias(alias: Alias): {
75
+ readonly acceptedCategories: readonly ModelCategory[];
76
+ readonly description: string;
77
+ readonly requiresThinking: boolean;
78
+ readonly requiresVision: boolean;
79
+ };
22
80
  export {};
23
81
  //# sourceMappingURL=models.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"models.d.ts","sourceRoot":"","sources":["../../src/gemini/models.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,OAAO,EAAE,KAAK,SAAS,EAAuB,MAAM,qBAAqB,CAAC;AAiC1E,QAAA,MAAM,OAAO;oCACY,SAAS,EAAE,KAAG,SAAS,GAAG,SAAS;6CAE1B,SAAS,EAAE,KAAG,SAAS,GAAG,SAAS;sCAG1C,SAAS,EAAE,KAAG,SAAS,GAAG,SAAS;qCAEpC,SAAS,EAAE,KAAG,SAAS,GAAG,SAAS;CAEnD,CAAC;AAEX,MAAM,MAAM,KAAK,GAAG,MAAM,OAAO,OAAO,CAAC;AAEzC,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,KAAK,CAErD;AAED,wBAAsB,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,CAAC,CA6DjG;AAED,wBAAgB,WAAW,IAAI,SAAS,KAAK,EAAE,CAE9C"}
1
+ {"version":3,"file":"models.d.ts","sourceRoot":"","sources":["../../src/gemini/models.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAGjD,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,aAAa,EAInB,MAAM,qBAAqB,CAAC;AAkD7B,QAAA,MAAM,OAAO;;;;;;;2CAOiB,eAAe;;;;;;;;;;;;;2CAaf,eAAe;;;CAGC,CAAC;AAE/C,MAAM,MAAM,KAAK,GAAG,MAAM,OAAO,OAAO,CAAC;AAEzC,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,KAAK,CAErD;AAmCD;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;CACtD;AAED,wBAAsB,YAAY,CAChC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,WAAW,EACnB,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,aAAa,CAAC,CAyDxB;AAaD,wBAAgB,WAAW,IAAI,SAAS,KAAK,EAAE,CAE9C;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,KAAK,GAAG;IAC3C,QAAQ,CAAC,kBAAkB,EAAE,SAAS,aAAa,EAAE,CAAC;IACtD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;IACnC,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;CAClC,CAQA"}