@qmediat.io/gemini-code-context-mcp 1.0.3 → 1.3.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.
Files changed (38) hide show
  1. package/CHANGELOG.md +94 -0
  2. package/dist/config.d.ts +12 -0
  3. package/dist/config.d.ts.map +1 -1
  4. package/dist/config.js +13 -1
  5. package/dist/config.js.map +1 -1
  6. package/dist/gemini/models.d.ts.map +1 -1
  7. package/dist/gemini/models.js +34 -25
  8. package/dist/gemini/models.js.map +1 -1
  9. package/dist/indexer/globs.d.ts.map +1 -1
  10. package/dist/indexer/globs.js +18 -0
  11. package/dist/indexer/globs.js.map +1 -1
  12. package/dist/indexer/workspace-validation.d.ts.map +1 -1
  13. package/dist/indexer/workspace-validation.js +33 -0
  14. package/dist/indexer/workspace-validation.js.map +1 -1
  15. package/dist/server.d.ts.map +1 -1
  16. package/dist/server.js +6 -0
  17. package/dist/server.js.map +1 -1
  18. package/dist/tools/ask.tool.d.ts +25 -1
  19. package/dist/tools/ask.tool.d.ts.map +1 -1
  20. package/dist/tools/ask.tool.js +215 -5
  21. package/dist/tools/ask.tool.js.map +1 -1
  22. package/dist/tools/code.tool.d.ts +24 -1
  23. package/dist/tools/code.tool.d.ts.map +1 -1
  24. package/dist/tools/code.tool.js +136 -17
  25. package/dist/tools/code.tool.js.map +1 -1
  26. package/dist/tools/registry.d.ts +24 -0
  27. package/dist/tools/registry.d.ts.map +1 -1
  28. package/dist/tools/registry.js +27 -1
  29. package/dist/tools/registry.js.map +1 -1
  30. package/dist/tools/shared/thinking.d.ts +63 -0
  31. package/dist/tools/shared/thinking.d.ts.map +1 -0
  32. package/dist/tools/shared/thinking.js +62 -0
  33. package/dist/tools/shared/thinking.js.map +1 -0
  34. package/dist/tools/shared/throttle.d.ts +121 -0
  35. package/dist/tools/shared/throttle.d.ts.map +1 -0
  36. package/dist/tools/shared/throttle.js +357 -0
  37. package/dist/tools/shared/throttle.js.map +1 -0
  38. package/package.json +1 -1
@@ -0,0 +1,121 @@
1
+ /**
2
+ * Client-side TPM (tokens-per-minute) throttle for Gemini API calls.
3
+ *
4
+ * Google enforces a per-minute input-token quota on paid Tier 1 Gemini 3 Pro
5
+ * at 100_000 tokens/minute/model/project (per AI Studio dashboard, subject
6
+ * to change). Without a client-side preflight we discover the limit only
7
+ * when Gemini returns 429 `RESOURCE_EXHAUSTED` — by which point the call
8
+ * is already billed (per `@google/genai@1.50.x` genai.d.ts: "AbortSignal
9
+ * is a client-only operation … you will still be charged").
10
+ *
11
+ * The module keeps an in-memory sliding 60-second window of recent input-
12
+ * token usage per resolved model. The primary API is a three-method
13
+ * reservation lifecycle — `reserve` / `release` / `cancel` — because a
14
+ * read-only "peek" API (the obvious design) has a TOCTOU race: between
15
+ * `peek()` → `await sleep()` → `await generateContent()` → `record()`, a
16
+ * concurrent MCP tool call observes the same pre-peek window and both
17
+ * callers proceed, collectively overshooting the quota.
18
+ *
19
+ * `reserve` solves the race by inserting a provisional `WindowEntry` with
20
+ * the caller's ESTIMATE at the moment the reservation is taken (plus the
21
+ * computed delay) — so subsequent concurrent `reserve` calls see the
22
+ * provisional entry and back off. When the call completes, `release`
23
+ * overwrites the estimate with actual token usage; on failure, `cancel`
24
+ * removes the provisional entry so it doesn't keep blocking future calls.
25
+ *
26
+ * Multi-entry eviction math: when the window is over-limit, we find the
27
+ * smallest index `k` such that evicting `entries[0..k]` drops the remaining
28
+ * sum enough to admit the new estimate. Waiting for JUST the oldest entry
29
+ * to expire (the naïve design this module replaced) under-delays whenever
30
+ * two or more large entries are still inside the window after that oldest
31
+ * one ages out.
32
+ *
33
+ * Sorted-array invariant: `entries[model]` is always kept sorted ascending
34
+ * by `tsMs`. `reserve` uses binary-search insertion (not `push`) because
35
+ * future-dated provisionals (hint-driven or window-eviction-driven delay)
36
+ * can produce tsMs values that are out-of-order relative to a subsequent
37
+ * `delayMs = 0` reservation. Without sorted-insert, `prune`'s head-only
38
+ * fast-path silently skips expired entries buried mid-array, causing
39
+ * over-throttle; and `computeWindowDelay`'s oldest-first eviction picks
40
+ * the wrong `entries[k].tsMs` to wait for. Empirically demonstrated during
41
+ * PR #19 code review (Copilot + Grok + Gemini independently flagged).
42
+ *
43
+ * Retry-hint extend-only: `recordRetryHint` keeps the LONGER of existing
44
+ * and new expiry. Allowing a shorter hint to replace a longer one would
45
+ * let a future reserve compute a smaller `tsMs` than an entry previously
46
+ * appended under the longer hint — same ordering break as above via a
47
+ * different trigger path.
48
+ *
49
+ * Deliberate non-goals (tracked in docs/FOLLOW-UP-PRS.md T22 follow-ups):
50
+ * - Cross-process coordination. State is per-server-process, not shared
51
+ * across multiple MCP instances keyed on the same API key.
52
+ * - Persistence across restarts. The window is rebuilt from zero each
53
+ * server boot; a rapid restart during heavy usage can briefly exceed
54
+ * the limit until the window saturates again. Acceptable: startup is
55
+ * rare and the first 429 would re-teach us via `recordRetryHint`.
56
+ * - Server-side cancellation of in-flight Gemini calls. The throttle is
57
+ * preflight-only; it never aborts a `generateContent` in progress.
58
+ */
59
+ export interface TpmReservation {
60
+ /** Milliseconds the caller must sleep before issuing the `generateContent`
61
+ * call. `0` means proceed immediately. */
62
+ readonly delayMs: number;
63
+ /** Opaque handle for `release` / `cancel`. Forget it and the provisional
64
+ * entry ages out of the window at `reservedAt + 60s` without updating
65
+ * to actuals — safe (errs on over-throttle) but leaves the estimate in
66
+ * the window longer than needed. */
67
+ readonly releaseId: number;
68
+ }
69
+ export interface TpmThrottle {
70
+ /**
71
+ * Reserve capacity for a planned `generateContent` call. Always returns
72
+ * a reservation — even when the throttle is disabled or the estimate
73
+ * exceeds the cap (in which case `delayMs === 0` and the provisional
74
+ * entry is still inserted so concurrent callers see our footprint).
75
+ *
76
+ * The reservation is provisional at `reserve` time: its token count is
77
+ * the caller's estimate. Always pair with exactly ONE of:
78
+ * - `release(id, actual)` on a successful Gemini response, or
79
+ * - `cancel(id)` on any failure BEFORE the call reached Gemini.
80
+ *
81
+ * Forgetting both is not a correctness bug — the provisional entry ages
82
+ * out naturally — but it leaves the estimate in the window for up to
83
+ * 60 seconds, potentially over-throttling future calls.
84
+ */
85
+ reserve(model: string, estimatedInputTokens: number, nowMs?: number): TpmReservation;
86
+ /**
87
+ * Finalise a reservation with the actual input tokens Gemini reports
88
+ * (pass the full `promptTokenCount`, cached + uncached — both count
89
+ * toward Gemini's per-minute budget, empirically confirmed 2026-04-20).
90
+ * No-op if `releaseId` is unknown (already released, or throttle reset).
91
+ */
92
+ release(releaseId: number, actualInputTokens: number, nowMs?: number): void;
93
+ /**
94
+ * Drop a reservation's provisional entry. Call on any failure that did
95
+ * not reach Gemini's billing path (validation error before dispatch,
96
+ * network error, local exception). No-op if `releaseId` is unknown.
97
+ */
98
+ cancel(releaseId: number): void;
99
+ /**
100
+ * Peek the delay the next call would receive WITHOUT inserting a new
101
+ * `WindowEntry`. Exposed for diagnostics, tests, and progress-message
102
+ * rendering — NOT as the primary throttle API, because it has the
103
+ * TOCTOU race this module was written to eliminate.
104
+ *
105
+ * Not strictly side-effect-free: this call opportunistically `prune`s
106
+ * expired entries and advances the `lastObservedNowMs` floor. Both are
107
+ * normalisation, not state *changes* to the throttle's contract — the
108
+ * window's token accounting is unchanged by any number of peeks.
109
+ */
110
+ shouldDelay(model: string, estimatedInputTokens: number, nowMs?: number): number;
111
+ /**
112
+ * Store a `retryInfo.retryDelay` hint extracted from a Gemini 429
113
+ * response. Google's hint is typically more accurate than our clock
114
+ * (we've seen 2–16s hints where our pure-window calculation returned
115
+ * 40+ seconds), so we use `max(computed, hint)` in `reserve` while
116
+ * the hint is active. Auto-expires at `now + retryDelayMs`.
117
+ */
118
+ recordRetryHint(model: string, retryDelayMs: number, nowMs?: number): void;
119
+ }
120
+ export declare function createTpmThrottle(limitTokensPerMinute: number): TpmThrottle;
121
+ //# sourceMappingURL=throttle.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"throttle.d.ts","sourceRoot":"","sources":["../../../src/tools/shared/throttle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AAiDH,MAAM,WAAW,cAAc;IAC7B;8CAC0C;IAC1C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;wCAGoC;IACpC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,WAAW;IAC1B;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,oBAAoB,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,cAAc,CAAC;IAErF;;;;;OAKG;IACH,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAE5E;;;;OAIG;IACH,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAEhC;;;;;;;;;;OAUG;IACH,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,oBAAoB,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAEjF;;;;;;OAMG;IACH,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5E;AAED,wBAAgB,iBAAiB,CAAC,oBAAoB,EAAE,MAAM,GAAG,WAAW,CA8O3E"}
@@ -0,0 +1,357 @@
1
+ /**
2
+ * Client-side TPM (tokens-per-minute) throttle for Gemini API calls.
3
+ *
4
+ * Google enforces a per-minute input-token quota on paid Tier 1 Gemini 3 Pro
5
+ * at 100_000 tokens/minute/model/project (per AI Studio dashboard, subject
6
+ * to change). Without a client-side preflight we discover the limit only
7
+ * when Gemini returns 429 `RESOURCE_EXHAUSTED` — by which point the call
8
+ * is already billed (per `@google/genai@1.50.x` genai.d.ts: "AbortSignal
9
+ * is a client-only operation … you will still be charged").
10
+ *
11
+ * The module keeps an in-memory sliding 60-second window of recent input-
12
+ * token usage per resolved model. The primary API is a three-method
13
+ * reservation lifecycle — `reserve` / `release` / `cancel` — because a
14
+ * read-only "peek" API (the obvious design) has a TOCTOU race: between
15
+ * `peek()` → `await sleep()` → `await generateContent()` → `record()`, a
16
+ * concurrent MCP tool call observes the same pre-peek window and both
17
+ * callers proceed, collectively overshooting the quota.
18
+ *
19
+ * `reserve` solves the race by inserting a provisional `WindowEntry` with
20
+ * the caller's ESTIMATE at the moment the reservation is taken (plus the
21
+ * computed delay) — so subsequent concurrent `reserve` calls see the
22
+ * provisional entry and back off. When the call completes, `release`
23
+ * overwrites the estimate with actual token usage; on failure, `cancel`
24
+ * removes the provisional entry so it doesn't keep blocking future calls.
25
+ *
26
+ * Multi-entry eviction math: when the window is over-limit, we find the
27
+ * smallest index `k` such that evicting `entries[0..k]` drops the remaining
28
+ * sum enough to admit the new estimate. Waiting for JUST the oldest entry
29
+ * to expire (the naïve design this module replaced) under-delays whenever
30
+ * two or more large entries are still inside the window after that oldest
31
+ * one ages out.
32
+ *
33
+ * Sorted-array invariant: `entries[model]` is always kept sorted ascending
34
+ * by `tsMs`. `reserve` uses binary-search insertion (not `push`) because
35
+ * future-dated provisionals (hint-driven or window-eviction-driven delay)
36
+ * can produce tsMs values that are out-of-order relative to a subsequent
37
+ * `delayMs = 0` reservation. Without sorted-insert, `prune`'s head-only
38
+ * fast-path silently skips expired entries buried mid-array, causing
39
+ * over-throttle; and `computeWindowDelay`'s oldest-first eviction picks
40
+ * the wrong `entries[k].tsMs` to wait for. Empirically demonstrated during
41
+ * PR #19 code review (Copilot + Grok + Gemini independently flagged).
42
+ *
43
+ * Retry-hint extend-only: `recordRetryHint` keeps the LONGER of existing
44
+ * and new expiry. Allowing a shorter hint to replace a longer one would
45
+ * let a future reserve compute a smaller `tsMs` than an entry previously
46
+ * appended under the longer hint — same ordering break as above via a
47
+ * different trigger path.
48
+ *
49
+ * Deliberate non-goals (tracked in docs/FOLLOW-UP-PRS.md T22 follow-ups):
50
+ * - Cross-process coordination. State is per-server-process, not shared
51
+ * across multiple MCP instances keyed on the same API key.
52
+ * - Persistence across restarts. The window is rebuilt from zero each
53
+ * server boot; a rapid restart during heavy usage can briefly exceed
54
+ * the limit until the window saturates again. Acceptable: startup is
55
+ * rare and the first 429 would re-teach us via `recordRetryHint`.
56
+ * - Server-side cancellation of in-flight Gemini calls. The throttle is
57
+ * preflight-only; it never aborts a `generateContent` in progress.
58
+ */
59
+ const WINDOW_MS = 60_000;
60
+ /**
61
+ * Randomised jitter padded onto computed wait times so a cluster of
62
+ * concurrent waiters evicting the same entry don't all compute the
63
+ * identical wait and wake at the same millisecond — which would re-create
64
+ * the burst they were trying to avoid. Range picked for a human-noticeable
65
+ * spread (≥1 s) without inflating typical waits excessively (≤3 s).
66
+ *
67
+ * `computeJitterMs` is a function (not a constant) because `Math.random()`
68
+ * MUST be evaluated per-caller — a module-scope `const` would be
69
+ * deterministic, which is exactly the thundering-herd bug Gemini flagged
70
+ * during PR #19 review.
71
+ */
72
+ const JITTER_MIN_MS = 1_000;
73
+ const JITTER_MAX_MS = 3_000;
74
+ /**
75
+ * Uniformly distributed integer in `[JITTER_MIN_MS, JITTER_MAX_MS]` —
76
+ * BOTH endpoints inclusive. The `+ 1` in the multiplier width ensures
77
+ * `JITTER_MAX_MS` is reachable (without it, `Math.floor` clamps to
78
+ * `MAX - 1`, producing the `[1000, 2999]` off-by-one Copilot flagged in
79
+ * the PR #19 round-2 review).
80
+ */
81
+ function computeJitterMs() {
82
+ return JITTER_MIN_MS + Math.floor(Math.random() * (JITTER_MAX_MS - JITTER_MIN_MS + 1));
83
+ }
84
+ export function createTpmThrottle(limitTokensPerMinute) {
85
+ if (!Number.isFinite(limitTokensPerMinute) || limitTokensPerMinute < 0) {
86
+ throw new Error(`createTpmThrottle: limit must be a non-negative finite number, got ${limitTokensPerMinute}`);
87
+ }
88
+ const disabled = limitTokensPerMinute === 0;
89
+ const windows = new Map();
90
+ const hints = new Map();
91
+ const reservationIndex = new Map();
92
+ let nextReservationId = 1;
93
+ /**
94
+ * Highest `nowMs` ever observed from a public-method call. Used to clamp
95
+ * backwards-jumping clocks (NTP correction, VM suspend/resume) — when
96
+ * the caller supplies a `nowMs` smaller than what we already know to have
97
+ * happened, we pin to our floor. Tracked separately from `entry.tsMs`
98
+ * because entries can be FUTURE-dated (a provisional reservation with
99
+ * `delayMs > 0` inserts at `now + delayMs`), and using those to clamp
100
+ * would pin "now" past the current real-time into scheduled-call time —
101
+ * which breaks multi-entry eviction math by making all past entries look
102
+ * like they've already aged out.
103
+ */
104
+ let lastObservedNowMs = Number.NEGATIVE_INFINITY;
105
+ function effectiveNow(nowMs) {
106
+ // Guard against non-finite caller input (NaN, ±Infinity). Consistent with
107
+ // `sanitizeTokens`' "coerce rather than crash/deadlock" philosophy:
108
+ // passing `Number.NEGATIVE_INFINITY` would otherwise poison
109
+ // `lastObservedNowMs` and cause every subsequent call to compute
110
+ // delays of +Infinity. Fall back to `Date.now()` — the same value
111
+ // the public-API defaults use when `nowMs` is omitted.
112
+ const candidate = Number.isFinite(nowMs) ? nowMs : Date.now();
113
+ const clamped = candidate > lastObservedNowMs ? candidate : lastObservedNowMs;
114
+ lastObservedNowMs = clamped;
115
+ return clamped;
116
+ }
117
+ function prune(model, nowMs) {
118
+ const existing = windows.get(model);
119
+ if (!existing || existing.length === 0)
120
+ return [];
121
+ const cutoff = nowMs - WINDOW_MS;
122
+ // Fast path: nothing expired → return the array as-is without allocating.
123
+ // Entries are append-sorted by tsMs (chronological), so the head is oldest.
124
+ const first = existing[0];
125
+ if (first && first.tsMs > cutoff)
126
+ return existing;
127
+ const kept = [];
128
+ for (const e of existing) {
129
+ if (e.tsMs > cutoff) {
130
+ kept.push(e);
131
+ }
132
+ else {
133
+ // Drop expired reservations from the ID index too — otherwise a late
134
+ // release/cancel would silently resurrect or mutate a stale entry.
135
+ reservationIndex.delete(e.id);
136
+ }
137
+ }
138
+ if (kept.length === 0) {
139
+ windows.delete(model);
140
+ return [];
141
+ }
142
+ windows.set(model, kept);
143
+ return kept;
144
+ }
145
+ function activeHint(model, nowMs) {
146
+ const hint = hints.get(model);
147
+ if (!hint)
148
+ return null;
149
+ if (hint.expiresAtMs <= nowMs) {
150
+ hints.delete(model);
151
+ return null;
152
+ }
153
+ return hint;
154
+ }
155
+ /**
156
+ * Compute the PURE (un-jittered) delay needed before a call estimated at
157
+ * `estimate` tokens can fit under `limitTokensPerMinute`, given the
158
+ * current `entries`.
159
+ *
160
+ * Returns `0` when the call fits immediately. Returns `0` when `estimate`
161
+ * alone exceeds the limit — sleeping forever would deadlock the tool;
162
+ * Gemini will either accept (actual < estimate) or 429, at which point
163
+ * `recordRetryHint` seeds the hint path.
164
+ *
165
+ * Otherwise: find the smallest `k` such that evicting `entries[0..k]`
166
+ * leaves `sum(entries[k+1..]) + estimate <= limit`, and wait just long
167
+ * enough for `entries[k]` to age out of the 60s window.
168
+ *
169
+ * Jitter is NOT applied here — that's the caller's responsibility. See
170
+ * `computeWindowDelay` for the jittered variant used by `reserve`, and
171
+ * `shouldDelay` for the un-jittered peek used by diagnostics.
172
+ */
173
+ function computeWindowDelayPure(entries, estimate, nowMs) {
174
+ let sum = 0;
175
+ for (const e of entries)
176
+ sum += e.tokens;
177
+ if (sum + estimate <= limitTokensPerMinute)
178
+ return 0;
179
+ if (estimate >= limitTokensPerMinute)
180
+ return 0;
181
+ // Iterate oldest-first, evict one entry at a time, stop when remaining
182
+ // tail + estimate fits. Since entries are chronological (tsMs ascending),
183
+ // evicting `entries[k]` also evicts everything older (they're already
184
+ // past their 60s age when `entries[k]` is).
185
+ let remaining = sum;
186
+ for (let k = 0; k < entries.length; k++) {
187
+ const e = entries[k];
188
+ if (!e)
189
+ break; // TS narrowing, unreachable given loop bound
190
+ remaining -= e.tokens;
191
+ if (remaining + estimate <= limitTokensPerMinute) {
192
+ const wait = e.tsMs + WINDOW_MS - nowMs;
193
+ return Math.max(0, wait);
194
+ }
195
+ }
196
+ // Unreachable in practice: `estimate < limit` (checked above) means
197
+ // evicting ALL entries (remaining=0) always fits. Return 0 defensively.
198
+ return 0;
199
+ }
200
+ /**
201
+ * Jittered variant of `computeWindowDelayPure`. Used by `reserve` so that
202
+ * concurrent waiters evicting the same entry wake at slightly different
203
+ * times instead of thundering back into generateContent simultaneously.
204
+ * Pure delay of `0` stays `0` — jitter only applies when there's actual
205
+ * waiting to do.
206
+ */
207
+ function computeWindowDelay(entries, estimate, nowMs) {
208
+ const pure = computeWindowDelayPure(entries, estimate, nowMs);
209
+ return pure === 0 ? 0 : pure + computeJitterMs();
210
+ }
211
+ return {
212
+ reserve(model, estimatedInputTokens, nowMs = Date.now()) {
213
+ if (disabled) {
214
+ // Return a no-op reservation that cancel/release will accept. We
215
+ // don't index it — lookups short-circuit on the disabled path.
216
+ return { delayMs: 0, releaseId: -1 };
217
+ }
218
+ const now = effectiveNow(nowMs);
219
+ const estimate = sanitizeTokens(estimatedInputTokens);
220
+ const entries = prune(model, now);
221
+ let delayMs = computeWindowDelay(entries, estimate, now);
222
+ const hint = activeHint(model, now);
223
+ if (hint) {
224
+ const hintDelayMs = Math.max(0, hint.expiresAtMs - now);
225
+ if (hintDelayMs > delayMs)
226
+ delayMs = hintDelayMs;
227
+ }
228
+ const id = nextReservationId++;
229
+ const entry = {
230
+ id,
231
+ tsMs: now + delayMs,
232
+ tokens: estimate,
233
+ };
234
+ // Sorted-insert by tsMs ascending. Append-order is NOT a reliable
235
+ // proxy for chronological tsMs order — a `delayMs = 0` reservation
236
+ // arriving after a future-dated provisional (hint-driven or
237
+ // eviction-driven delay) has a smaller tsMs than the provisional's.
238
+ // Without sorted-insert the head-only fast-path in `prune` silently
239
+ // skips expired entries buried mid-array and `computeWindowDelay`'s
240
+ // oldest-first eviction picks the wrong entry to wait for.
241
+ insertSortedByTsMs(entries, entry);
242
+ windows.set(model, entries);
243
+ reservationIndex.set(id, { model, entry });
244
+ return { delayMs, releaseId: id };
245
+ },
246
+ release(releaseId, actualInputTokens, nowMs = Date.now()) {
247
+ if (disabled || releaseId < 0)
248
+ return;
249
+ const ref = reservationIndex.get(releaseId);
250
+ if (!ref)
251
+ return;
252
+ const actual = sanitizeTokens(actualInputTokens);
253
+ // Mutate the entry in place so the window sum reflects reality for
254
+ // future `reserve` callers. Leave tsMs unchanged: the call happened
255
+ // at the reservation's effective time regardless of how long the
256
+ // response took to arrive.
257
+ ref.entry.tokens = actual;
258
+ // Delete from the index AFTER mutating so a duplicate `release` or a
259
+ // late `cancel` on the same id becomes a safe no-op — without this,
260
+ // `cancel(alreadyReleasedId)` would remove the already-accounted
261
+ // entry from the window and under-throttle subsequent callers. The
262
+ // entry itself remains in `windows[model]` to count against the
263
+ // running window until it ages out naturally.
264
+ reservationIndex.delete(releaseId);
265
+ // Opportunistically prune while we have a nowMs — amortises cleanup
266
+ // cost across release calls and avoids relying solely on future
267
+ // `reserve` calls for the same model.
268
+ prune(ref.model, effectiveNow(nowMs));
269
+ },
270
+ cancel(releaseId) {
271
+ if (disabled || releaseId < 0)
272
+ return;
273
+ const ref = reservationIndex.get(releaseId);
274
+ if (!ref)
275
+ return;
276
+ reservationIndex.delete(releaseId);
277
+ const existing = windows.get(ref.model);
278
+ if (!existing)
279
+ return;
280
+ const filtered = existing.filter((e) => e.id !== releaseId);
281
+ if (filtered.length === 0)
282
+ windows.delete(ref.model);
283
+ else
284
+ windows.set(ref.model, filtered);
285
+ },
286
+ shouldDelay(model, estimatedInputTokens, nowMs = Date.now()) {
287
+ if (disabled)
288
+ return 0;
289
+ const now = effectiveNow(nowMs);
290
+ const estimate = sanitizeTokens(estimatedInputTokens);
291
+ const entries = prune(model, now);
292
+ // Peek uses the PURE delay — callers polling for progress-bar
293
+ // updates or diagnostics would otherwise see bouncing values for
294
+ // unchanged state, which `computeWindowDelay`'s random jitter
295
+ // introduces for `reserve`'s thundering-herd avoidance.
296
+ const windowDelay = computeWindowDelayPure(entries, estimate, now);
297
+ const hint = activeHint(model, now);
298
+ const hintDelay = hint ? Math.max(0, hint.expiresAtMs - now) : 0;
299
+ return Math.max(windowDelay, hintDelay);
300
+ },
301
+ recordRetryHint(model, retryDelayMs, nowMs = Date.now()) {
302
+ if (disabled)
303
+ return;
304
+ if (!Number.isFinite(retryDelayMs) || retryDelayMs <= 0)
305
+ return;
306
+ const now = effectiveNow(nowMs);
307
+ const newExpiresAtMs = now + retryDelayMs;
308
+ // Extend-only: a shorter hint replacing a longer one would produce
309
+ // a `reserve` that computes a smaller `tsMs` than entries already
310
+ // appended under the longer hint, breaking the sorted-array
311
+ // invariant. Keep the longer expiry when both exist — even if the
312
+ // new hint's `retryDelayMs` is smaller numerically, the wall-clock
313
+ // expiry monotonically increases.
314
+ const existing = hints.get(model);
315
+ if (existing && existing.expiresAtMs >= newExpiresAtMs)
316
+ return;
317
+ hints.set(model, { expiresAtMs: newExpiresAtMs, retryDelayMs });
318
+ },
319
+ };
320
+ }
321
+ /** Coerce non-finite / negative token values to 0 so callers with bad
322
+ * instrumentation data can't crash the throttle. A 0-token reservation
323
+ * still takes an ID (for lifecycle symmetry) but contributes nothing. */
324
+ function sanitizeTokens(n) {
325
+ if (!Number.isFinite(n) || n <= 0)
326
+ return 0;
327
+ return n;
328
+ }
329
+ /**
330
+ * Insert `entry` into `entries` at the position that keeps the array
331
+ * sorted ascending by `tsMs`. Binary-search for the insertion point;
332
+ * `splice` to insert. O(log n) compares + O(n) shift, same asymptotic
333
+ * cost as `push + sort` but with a smaller constant factor on the
334
+ * append-to-end fast path (the common case when clocks and delays are
335
+ * monotonic).
336
+ */
337
+ function insertSortedByTsMs(entries, entry) {
338
+ // Common case: new entry is latest. Skip the binary search.
339
+ const last = entries[entries.length - 1];
340
+ if (!last || entry.tsMs >= last.tsMs) {
341
+ entries.push(entry);
342
+ return;
343
+ }
344
+ let lo = 0;
345
+ let hi = entries.length;
346
+ while (lo < hi) {
347
+ const mid = (lo + hi) >>> 1;
348
+ const probe = entries[mid];
349
+ // `probe` is defined because `mid < hi <= entries.length`.
350
+ if (probe && probe.tsMs <= entry.tsMs)
351
+ lo = mid + 1;
352
+ else
353
+ hi = mid;
354
+ }
355
+ entries.splice(lo, 0, entry);
356
+ }
357
+ //# sourceMappingURL=throttle.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"throttle.js","sourceRoot":"","sources":["../../../src/tools/shared/throttle.ts"],"names":[],"mappings":"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"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@qmediat.io/gemini-code-context-mcp",
3
- "version": "1.0.3",
3
+ "version": "1.3.0",
4
4
  "description": "MCP server that gives Claude Code persistent memory of your codebase, backed by Gemini's 2M-token context. Drop-in upgrade over the abandoned gemini-mcp-tool.",
5
5
  "keywords": [
6
6
  "mcp",