@qmediat.io/gemini-code-context-mcp 1.3.1 → 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 +83 -0
- package/README.md +14 -0
- package/dist/config.d.ts +12 -0
- package/dist/config.d.ts.map +1 -1
- package/dist/config.js +15 -1
- package/dist/config.js.map +1 -1
- package/dist/gemini/model-taxonomy.d.ts +94 -0
- package/dist/gemini/model-taxonomy.d.ts.map +1 -0
- package/dist/gemini/model-taxonomy.js +176 -0
- package/dist/gemini/model-taxonomy.js.map +1 -0
- package/dist/gemini/models.d.ts +68 -10
- package/dist/gemini/models.d.ts.map +1 -1
- package/dist/gemini/models.js +137 -71
- package/dist/gemini/models.js.map +1 -1
- package/dist/tools/ask.tool.d.ts +5 -0
- package/dist/tools/ask.tool.d.ts.map +1 -1
- package/dist/tools/ask.tool.js +109 -38
- package/dist/tools/ask.tool.js.map +1 -1
- package/dist/tools/code.tool.d.ts +5 -0
- package/dist/tools/code.tool.d.ts.map +1 -1
- package/dist/tools/code.tool.js +66 -21
- package/dist/tools/code.tool.js.map +1 -1
- package/dist/tools/shared/throttle.d.ts +35 -0
- package/dist/tools/shared/throttle.d.ts.map +1 -1
- package/dist/tools/shared/throttle.js +66 -4
- package/dist/tools/shared/throttle.js.map +1 -1
- package/dist/types.d.ts +13 -0
- package/dist/types.d.ts.map +1 -1
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -7,6 +7,89 @@ 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
|
+
|
|
60
|
+
## [1.3.2] — 2026-04-20
|
|
61
|
+
|
|
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.
|
|
63
|
+
|
|
64
|
+
### Fixed
|
|
65
|
+
|
|
66
|
+
- **Retry-hint poisoning closed via SDK-provenance gate.** `parseRetryDelayMs` was called on EVERY `Error.message` that reached `ask`/`code` catch blocks in v1.3.1 — not gated to confirmed Gemini 429s. A user-controlled prompt containing the literal substring `"retryDelay":"60s"` echoed into any non-429 error body (safety filter, validation rejection, log re-serialisation) would seed the per-model throttle at the clamp ceiling and self-DoS the MCP server for the rest of its process lifetime. v1.3.2 gates the parser behind a new exported `isGemini429(err)` type-guard that requires BOTH `err instanceof ApiError` (prototype-chain identity — class only instantiated by `@google/genai`'s `throwErrorIfNotOK` from real HTTP responses) AND `err.status === 429` (typed field, strict equality — rejects stringified `"429"` from buggy wrappers). User-controlled content cannot forge either marker from prompt-string input. An earlier draft with a `/RESOURCE_EXHAUSTED/` substring fallback was itself flagged by GPT + Grok as bypassable (attacker injects both markers) and removed before merge. GPT + Grok both CRITICAL on round-1, both confirmed closed on round-2.
|
|
67
|
+
- **Escaped-JSON form now extracted.** `parseRetryDelayMs` previously required bare-quoted `"retryDelay":"Ns"` in the error message. Empirically verified that the common `@google/genai` SDK path produces bare quotes via `JSON.stringify(errorBody)` in `throwErrorIfNotOK`, so real 429s from `generativelanguage.googleapis.com` / Vertex `aiplatform.googleapis.com` match directly — regardless of which auth tier constructed the client (`apiKey` vs `vertexai` paths share the same error-handling code). BUT: the non-JSON content-type branch of `throwErrorIfNotOK` wraps raw text body into `{error: {message: "<raw-text>"}}` before stringifying, ESCAPING any literal `"retryDelay":"Ns"` substring inside — a narrow path hit when a corporate proxy / MITM / Cloudflare edge returns an HTML 429 page instead of the upstream JSON. The parser now unescapes once on fallback (`errorMessage.replace(/\\"/g, '"')`) when `\\"` is present, and re-runs the regex. Bare-form common path unchanged (no allocation). `/6step` verdict: LOW TP — safe direction even if missed (falls back to pure-window math, no quota overshoot). With the prototype gate above, user-controlled content can't reach the parser regardless of escape form.
|
|
68
|
+
- **Test comment correctness** — `"returns null on negative / zero values"` now documents that `"-1s"` fails at the regex stage (the `\d+` class rejects leading `-`) while `"0s"` fails via the `seconds <= 0` guard. Two different reject paths converging on `null`. Grok NIT.
|
|
69
|
+
|
|
70
|
+
### Added
|
|
71
|
+
|
|
72
|
+
- **`isGemini429(err): err is ApiError`** — type-guard exported from `src/tools/shared/throttle.ts`. Imports `ApiError` from `@google/genai`. Narrows `err` to `ApiError` in call-site catch blocks, eliminating the `(err as Error).message` cast that appeared in an earlier draft.
|
|
73
|
+
- **11 new unit tests** covering: `parseRetryDelayMs` escaped form + mixed bare/escaped tie-break, 7 `isGemini429` cases (real ApiError-429, non-ApiError wrapper with forged status=429, plain Error with RESOURCE_EXHAUSTED substring, ApiError with non-429 status, user-controlled poisoning attempt with both markers, non-Error values, ApiError with non-number status).
|
|
74
|
+
- **8 new integration tests across `ask` + `code`** — both tool files now cover the full bypass-guard surface: real ApiError 429 → hint seeded; plain Error with RESOURCE_EXHAUSTED substring → NO hint (gate tightened, substring path removed); combined-marker poisoning attempt (RESOURCE_EXHAUSTED + retryDelay substring in non-429 error) → NO hint; custom Object.assign wrapper with forged status=429 → NO hint; ApiError with non-429 status + retryDelay in body → NO hint.
|
|
75
|
+
|
|
76
|
+
### Tests
|
|
77
|
+
|
|
78
|
+
- 77 throttle-family tests (up from 56 in v1.3.1: 9 `parseRetryDelayMs` + 11 `parseRetryDelayMs` extended cases + 7 `isGemini429` + 40 core throttle + 15 integration = 77). Exact count may vary with jitter randomness.
|
|
79
|
+
- 221 total PR tests (up from 205 in v1.3.1). Lint + typecheck + build all green on Node 22.
|
|
80
|
+
|
|
81
|
+
### Reviewer notes (not a code change)
|
|
82
|
+
|
|
83
|
+
**Round-1 on PR #21** (tightening's first draft): GPT `gpt-5.3-codex` + Grok `grok-4.20-beta-0309-reasoning` both flagged the `RESOURCE_EXHAUSTED` substring fallback as itself bypassable — attacker injecting BOTH markers (`RESOURCE_EXHAUSTED` + `"retryDelay":"60s"`) reopened the same poisoning class the gate was meant to close. Grok additionally flagged missing word boundaries, brittle escape-fallback on double-escape, and the type-guard regression risk from the `(err as Error)` cast.
|
|
84
|
+
|
|
85
|
+
**Round-2 response**: tightened `isGemini429` to require `err instanceof ApiError` (class imported from `@google/genai`) AND `err.status === 429`. Substring fallback REMOVED entirely. Cast eliminated via type-guard signature. Prototype check is not forgeable from user-controlled string input — closes both bypass classes. Copilot's round-2 queue did not return in the review window; 2-of-2 available reviewers (GPT + Grok) on round-1 + `/6step` on round-2 tightening provided sufficient signal.
|
|
86
|
+
|
|
87
|
+
**Not fixed (documented as accepted)**:
|
|
88
|
+
- Numeric / protobuf retry-delay forms (`"retryDelay":5`, `{"seconds":5,"nanos":0}`). Not observed in Gemini REST API output per AIP-140 (`"Ns"` string form mandated). Future-proof; defer.
|
|
89
|
+
- Integration mock fidelity drift. Hand-written shapes for `scanWorkspace` / `resolveModel` / `prepareContext` leaf mocks. Follow-up: replace `as Type[...]` casts with `satisfies` to force compile-time drift detection.
|
|
90
|
+
- `TextToolResult` type narrowing as minor API surface change. Runtime-safe; external TS consumers (none known) get narrower field type, not break.
|
|
91
|
+
- Disabled-throttle path still runs `parseRetryDelayMs` on every catch — `recordRetryHint` itself no-ops when disabled so the result is discarded. Perf: microseconds. Not worth conditionalizing.
|
|
92
|
+
|
|
10
93
|
## [1.3.1] — 2026-04-20
|
|
11
94
|
|
|
12
95
|
Patch release closing the three LOW/NIT follow-ups deferred from v1.3.0's multi-round review cycle (T22a retry-hint wiring, T22b ask/code integration tests, T23a helper return-type narrowing). No user-visible API breaks; smallest possible diff that moves GPT's round-2 "still live" findings to closed.
|
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
|
package/dist/config.d.ts.map
CHANGED
|
@@ -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;
|
|
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:
|
|
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
|
package/dist/config.js.map
CHANGED
|
@@ -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;
|
|
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":"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"}
|
package/dist/gemini/models.d.ts
CHANGED
|
@@ -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`).
|
|
6
|
-
* model for the current API key
|
|
7
|
-
*
|
|
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
|
|
22
|
+
import { type CapabilityFlags, type ModelCategory } from './model-taxonomy.js';
|
|
12
23
|
declare const ALIASES: {
|
|
13
|
-
readonly 'latest-pro':
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
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
|
-
|
|
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
|
|
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"}
|