@qmediat.io/gemini-code-context-mcp 1.23.1 → 1.24.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 (74) hide show
  1. package/CHANGELOG.md +72 -1
  2. package/README.md +1 -1
  3. package/dist/cache/ttl-watcher.d.ts +29 -0
  4. package/dist/cache/ttl-watcher.d.ts.map +1 -1
  5. package/dist/cache/ttl-watcher.js +104 -43
  6. package/dist/cache/ttl-watcher.js.map +1 -1
  7. package/dist/gemini/client.d.ts +7 -0
  8. package/dist/gemini/client.d.ts.map +1 -1
  9. package/dist/gemini/client.js +8 -1
  10. package/dist/gemini/client.js.map +1 -1
  11. package/dist/gemini/long-decode.d.ts +153 -0
  12. package/dist/gemini/long-decode.d.ts.map +1 -0
  13. package/dist/gemini/long-decode.js +178 -0
  14. package/dist/gemini/long-decode.js.map +1 -0
  15. package/dist/gemini/model-registry.d.ts +2 -0
  16. package/dist/gemini/model-registry.d.ts.map +1 -1
  17. package/dist/gemini/model-registry.js +5 -2
  18. package/dist/gemini/model-registry.js.map +1 -1
  19. package/dist/gemini/models.d.ts.map +1 -1
  20. package/dist/gemini/models.js +1 -0
  21. package/dist/gemini/models.js.map +1 -1
  22. package/dist/gemini/retry.d.ts +8 -0
  23. package/dist/gemini/retry.d.ts.map +1 -1
  24. package/dist/gemini/retry.js +33 -1
  25. package/dist/gemini/retry.js.map +1 -1
  26. package/dist/tools/ask-agentic.tool.d.ts.map +1 -1
  27. package/dist/tools/ask-agentic.tool.js +10 -12
  28. package/dist/tools/ask-agentic.tool.js.map +1 -1
  29. package/dist/tools/ask.tool.d.ts.map +1 -1
  30. package/dist/tools/ask.tool.js +168 -379
  31. package/dist/tools/ask.tool.js.map +1 -1
  32. package/dist/tools/code.tool.d.ts +6 -0
  33. package/dist/tools/code.tool.d.ts.map +1 -1
  34. package/dist/tools/code.tool.js +146 -286
  35. package/dist/tools/code.tool.js.map +1 -1
  36. package/dist/tools/shared/abort-timeout.d.ts +6 -0
  37. package/dist/tools/shared/abort-timeout.d.ts.map +1 -1
  38. package/dist/tools/shared/abort-timeout.js +12 -0
  39. package/dist/tools/shared/abort-timeout.js.map +1 -1
  40. package/dist/tools/shared/call-ledger.d.ts +73 -0
  41. package/dist/tools/shared/call-ledger.d.ts.map +1 -0
  42. package/dist/tools/shared/call-ledger.js +115 -0
  43. package/dist/tools/shared/call-ledger.js.map +1 -0
  44. package/dist/tools/shared/context-decode.d.ts +77 -0
  45. package/dist/tools/shared/context-decode.d.ts.map +1 -0
  46. package/dist/tools/shared/context-decode.js +125 -0
  47. package/dist/tools/shared/context-decode.js.map +1 -0
  48. package/dist/tools/shared/continuation.d.ts +124 -0
  49. package/dist/tools/shared/continuation.d.ts.map +1 -0
  50. package/dist/tools/shared/continuation.js +302 -0
  51. package/dist/tools/shared/continuation.js.map +1 -0
  52. package/dist/tools/shared/dispatch-throttle.d.ts +43 -0
  53. package/dist/tools/shared/dispatch-throttle.d.ts.map +1 -0
  54. package/dist/tools/shared/dispatch-throttle.js +65 -0
  55. package/dist/tools/shared/dispatch-throttle.js.map +1 -0
  56. package/dist/tools/shared/settle-call.d.ts +63 -0
  57. package/dist/tools/shared/settle-call.d.ts.map +1 -0
  58. package/dist/tools/shared/settle-call.js +55 -0
  59. package/dist/tools/shared/settle-call.js.map +1 -0
  60. package/dist/tools/shared/stream-collector.d.ts +7 -0
  61. package/dist/tools/shared/stream-collector.d.ts.map +1 -1
  62. package/dist/tools/shared/stream-collector.js +5 -1
  63. package/dist/tools/shared/stream-collector.js.map +1 -1
  64. package/dist/tools/shared/thinking.d.ts +41 -11
  65. package/dist/tools/shared/thinking.d.ts.map +1 -1
  66. package/dist/tools/shared/thinking.js +62 -9
  67. package/dist/tools/shared/thinking.js.map +1 -1
  68. package/dist/types.d.ts +2 -0
  69. package/dist/types.d.ts.map +1 -1
  70. package/dist/utils/cost-estimator.d.ts +17 -0
  71. package/dist/utils/cost-estimator.d.ts.map +1 -1
  72. package/dist/utils/cost-estimator.js +15 -2
  73. package/dist/utils/cost-estimator.js.map +1 -1
  74. package/package.json +4 -3
@@ -10,24 +10,26 @@ import { createHash } from 'node:crypto';
10
10
  import { resolve } from 'node:path';
11
11
  import { z } from 'zod';
12
12
  import { AttachmentError, AttachmentTokensUncountedError, INLINE_REQUEST_LIMIT_BYTES, MAX_ATTACHMENTS, MAX_ATTACHMENTS_TOTAL_BYTES, MAX_ATTACHMENT_BYTES, countAttachmentTokens, inlineRequestBytes, inspectAttachments, readAttachments, } from '../attachments.js';
13
- import { isStaleCacheError, markCacheStale, prepareContext } from '../cache/cache-manager.js';
13
+ import { prepareContext } from '../cache/cache-manager.js';
14
14
  import { CACHING_MODE_FALLBACK_DESCRIPTION, cachingModeFor, cachingRan, } from '../cache/caching-mode.js';
15
+ import { capThatRuns, preflightModeFor, resolveOutputCap, thinkingBudgetRefusal, } from '../gemini/long-decode.js';
15
16
  import { resolveModel } from '../gemini/models.js';
16
- import { abortableSleep, withNetworkRetry } from '../gemini/retry.js';
17
17
  import { countForPreflight } from '../gemini/token-counter.js';
18
18
  import { buildScanMemo, scanWorkspace } from '../indexer/workspace-scanner.js';
19
19
  import { WorkspaceValidationError, validateWorkspacePath, } from '../indexer/workspace-validation.js';
20
- import { estimateCostUsd, estimatePreCallCostUsd, toMicrosUsd } from '../utils/cost-estimator.js';
20
+ import { estimatePreCallCostUsd, toMicrosUsd } from '../utils/cost-estimator.js';
21
21
  import { logger, safeForLog } from '../utils/logger.js';
22
22
  import { createProgressEmitter } from '../utils/progress.js';
23
23
  import { askAgenticTool } from './ask-agentic.tool.js';
24
24
  import { errorResult, textResult } from './registry.js';
25
25
  import { createTimeoutController, getTimeoutKind, isTimeoutAbort } from './shared/abort-timeout.js';
26
+ import { decodeOnContext } from './shared/context-decode.js';
27
+ import { CompletedRequests, LONG_DECODE_CAP_DESCRIPTION } from './shared/continuation.js';
28
+ import { DispatchThrottle } from './shared/dispatch-throttle.js';
26
29
  import { SERVICE_TIER_DESCRIPTION, ServiceTierError, networkAttempts, resolveServiceTier, serviceTierConfig, statusOf, tierErrorMeta, } from './shared/service-tier.js';
27
- import { collectStream } from './shared/stream-collector.js';
30
+ import { settleAnswer, settleFailure } from './shared/settle-call.js';
28
31
  import { SYSTEM_INSTRUCTION_SAFETY_EAGER } from './shared/system-instruction-safety.js';
29
- import { THINKING_LEVEL_FIELD, THINKING_LEVEL_RESERVE, emptyAtOutputCap, } from './shared/thinking.js';
30
- import { isGemini429, parseRetryDelayMs } from './shared/throttle.js';
32
+ import { THINKING_LEVEL_FIELD, thinkingBudgetUnder, thinkingReserve } from './shared/thinking.js';
31
33
  /**
32
34
  * `ask` system instruction. Prepends the shared `SYSTEM_INSTRUCTION_SAFETY_EAGER`
33
35
  * data-vs-instruction firewall (added in v1.15.2 — pre-v1.15.2 `ask` had no
@@ -106,7 +108,10 @@ export const askInputSchema = z
106
108
  .int()
107
109
  .min(1)
108
110
  .optional()
109
- .describe("Per-call opt-in cap on response length (tokens). OMIT for the default 'auto' behaviour — Gemini uses its model-default cap (per Google docs, equal to the model's advertised `outputTokenLimit`: 65,536 for Gemini 3.x / 2.5 Pro-tier; see ai.google.dev/gemini-api/docs/models/gemini-2.5-pro). Pass a smaller value when you want a bounded response (e.g. strict summary length, tighter budget per call). Values larger than the resolved model's limit are clamped down. Budget reservation always uses the effective cap (explicit OR model limit) as worst-case, so `GEMINI_DAILY_BUDGET_USD` stays a true upper bound."),
111
+ .describe([
112
+ "Per-call opt-in cap on response length (tokens). OMIT for the default 'auto' behaviour — Gemini uses its model-default cap (per Google docs, equal to the model's advertised `outputTokenLimit`: 65,536 for Gemini 3.x / 2.5 Pro-tier; see ai.google.dev/gemini-api/docs/models/gemini-2.5-pro). Pass a smaller value when you want a bounded response (e.g. strict summary length, tighter budget per call). On any other model a value larger than the resolved model's limit is clamped down to it. Budget reservation always uses the effective cap (explicit OR model limit) as worst-case, so `GEMINI_DAILY_BUDGET_USD` stays a true upper bound.",
113
+ LONG_DECODE_CAP_DESCRIPTION,
114
+ ].join(' ')),
110
115
  timeoutMs: z
111
116
  .number()
112
117
  .int()
@@ -237,16 +242,15 @@ function attachmentMetadata(prepared) {
237
242
  }
238
243
  async function executeAskBody(input, ctx, workspaceRoot, model, started) {
239
244
  let reservationId = null;
240
- // `-1` signals "no reservation held" (distinct from 0 which is a valid
241
- // releaseId). Mirrors the pattern used by `reservationId`.
242
- let throttleReservationId = -1;
243
245
  // Canonical resolved-model string, captured once after `resolveModel`
244
246
  // so the outer catch can feed retry hints into the same throttle bucket
245
247
  // `reserve` used. `model` at the top of execute is the request alias
246
248
  // ("latest-pro-thinking") — different key, different bucket.
247
249
  let resolvedModelKey = null;
248
- // once a stream opened, a later transport failure is mid-stream: billed work, not to be re-sent
249
- let streamOpened = false;
250
+ // every request that completed is billed: the ledger settles from these, on an answer and on a failure alike
251
+ const completed = new CompletedRequests();
252
+ // the running decode's booking and whether a stream opened (a later failure is then billed work, not re-sent)
253
+ const tracking = { ledgerEntry: null, streamOpened: false };
250
254
  // the tier this call runs on once resolved (Vertex may force standard); before that, the requested one is reported
251
255
  let serviceTier;
252
256
  const reportedTier = () => serviceTier ?? input.serviceTier ?? ctx.config.serviceTier;
@@ -265,6 +269,13 @@ async function executeAskBody(input, ctx, workspaceRoot, model, started) {
265
269
  stallEnvVar: 'GEMINI_CODE_CONTEXT_ASK_STALL_MS',
266
270
  });
267
271
  const abortSignal = timeoutController.signal;
272
+ // Each request of the decode holds its own TPM reservation; a failure drops the one held.
273
+ const dispatch = new DispatchThrottle({
274
+ throttle: ctx.throttle,
275
+ enabled: ctx.config.tpmThrottleLimit > 0,
276
+ signal: abortSignal,
277
+ emit: (message) => emitter.emit(message),
278
+ });
268
279
  try {
269
280
  // Workspace path validation lives INSIDE the try so a
270
281
  // `WorkspaceValidationError` is reported as a regular tool error
@@ -325,97 +336,38 @@ async function executeAskBody(input, ctx, workspaceRoot, model, started) {
325
336
  manifestMemo: scanMemo,
326
337
  forceRescan: input.forceRescan === true || ctx.config.forceRescan === true,
327
338
  });
328
- // Output-cap strategy (v1.4.0): three-layer precedence.
339
+ // Output cap, three layers (`resolveOutputCap`):
329
340
  //
330
- // 1. `input.maxOutputTokens` (per-call, strongest) — user explicitly
331
- // caps this one call. Clamped to `modelOutputLimit`.
332
- // 2. `ctx.config.forceMaxOutputTokens` (env override) — when the
333
- // MCP host sets `GEMINI_CODE_CONTEXT_FORCE_MAX_OUTPUT=true`,
334
- // every call sends `maxOutputTokens = modelOutputLimit` so
335
- // code-review workloads always run at the model's full capacity
336
- // (65,536 tokens for Gemini 3.x / 2.5 Pro per Google docs).
337
- // 3. Default (no overrides) — omit `maxOutputTokens` from the
338
- // `generateContent` config. Gemini uses its model-default cap
339
- // (documented as the model's advertised `outputTokenLimit`),
340
- // letting the model size the response to the query's complexity
341
- // rather than reserving full capacity on short Q&A.
341
+ // 1. `input.maxOutputTokens` (per-call, strongest) — clamped to the
342
+ // model's per-request limit, or on a model with long decode
343
+ // (Gemini 4) to its long-decode total: a cap above the per-request
344
+ // limit continues the decode in further requests.
345
+ // 2. `ctx.config.forceMaxOutputTokens` (env override) — every call
346
+ // sends the model's per-request limit.
347
+ // 3. Default — `maxOutputTokens` is omitted: one request, the model's
348
+ // own default (its advertised `outputTokenLimit`), letting the model
349
+ // size the response to the query rather than reserving full capacity.
342
350
  //
343
- // `modelOutputLimit` is the model's advertised ceiling from
344
- // `models.list()` (or a fallback if the SDK doesn't report one).
345
- // Used as the clamp target and as the budget-reservation worst-case.
346
- const modelOutputLimit = typeof resolved.outputTokenLimit === 'number' && resolved.outputTokenLimit > 0
347
- ? resolved.outputTokenLimit
348
- : ASK_MAX_OUTPUT_TOKENS_FALLBACK;
349
- const wireMaxOutputTokens = input.maxOutputTokens !== undefined
350
- ? Math.min(input.maxOutputTokens, modelOutputLimit)
351
- : ctx.config.forceMaxOutputTokens
352
- ? modelOutputLimit
353
- : undefined;
354
- // Effective cap used for thinking-budget clamp and budget reservation.
355
- // When neither override is set, the model's internal default equals
356
- // `modelOutputLimit` per Google docs — so using the limit as
357
- // worst-case keeps `GEMINI_DAILY_BUDGET_USD` a true upper bound.
358
- const effectiveOutputCap = wireMaxOutputTokens ?? modelOutputLimit;
351
+ // The caller's `thinkingBudget` is checked against `outputCap`; the
352
+ // clamp and the reservation use the cap that runs (`runCap`).
353
+ const outputCap = resolveOutputCap({
354
+ requested: input.maxOutputTokens,
355
+ forceMax: ctx.config.forceMaxOutputTokens,
356
+ outputTokenLimit: resolved.outputTokenLimit,
357
+ longDecodeTokenLimit: resolved.longDecodeTokenLimit,
358
+ fallbackLimit: ASK_MAX_OUTPUT_TOKENS_FALLBACK,
359
+ });
359
360
  // Single source of truth for "is the caller driving reasoning via the
360
361
  // discrete-tier knob?". Three downstream call sites branch on this
361
362
  // (cost estimate, emitter, thinkingConfig build) — extracting to a
362
363
  // named const keeps them in lockstep and makes future additions hard
363
364
  // to forget.
364
365
  const usingThinkingLevel = input.thinkingLevel !== undefined;
365
- // Gemini requires `thinkingBudget < maxOutputTokens` (the thinking pool
366
- // is carved out of the candidate-output allowance). Reject the call
367
- // early when the caller's `maxOutputTokens` leaves no headroom for a
368
- // positive `thinkingBudget`, rather than silently clamping to 0 —
369
- // clamp-to-0 would make Gemini 3 Pro 400 ("thinking disabled"
370
- // rejected) and mislead the caller about the actual cause (PR #22
371
- // round-3 review finding #C). Minimum answer reserve: 1024 tokens.
372
- if (input.thinkingBudget !== undefined &&
373
- input.thinkingBudget > 0 &&
374
- input.maxOutputTokens !== undefined &&
375
- effectiveOutputCap < input.thinkingBudget + 1024) {
376
- return errorResult(`ask: thinkingBudget (${input.thinkingBudget}) + 1024-token answer reserve exceeds maxOutputTokens (${effectiveOutputCap}). Raise \`maxOutputTokens\` to at least ${input.thinkingBudget + 1024}, or lower \`thinkingBudget\`.`);
377
- }
378
- // Normalise thinkingBudget:
379
- // undefined → null (model-default path — `thinkingBudget` OMITTED on wire)
380
- // -1 → -1 (explicit legacy dynamic; kept for Gemini 2.5 and
381
- // power-users who want to force the legacy path)
382
- // 0 → 0 (thinking disabled; Gemini 3 Pro will 400 here)
383
- // N > 0 → clamp to [0, maxOutputTokens - 1024] — the thinking
384
- // pool is carved out of the candidate-output allowance,
385
- // so reserving ≥1024 tokens for the answer prevents 400s
386
- // when a caller passes N ≥ maxOutputTokens.
387
- //
388
- // Schema `.refine()` guarantees `thinkingBudget` and `thinkingLevel`
389
- // are never both set, so we handle them in two mutually-exclusive
390
- // branches below.
391
- const rawThinkingBudget = input.thinkingBudget;
392
- const effectiveThinkingBudget = rawThinkingBudget === undefined
393
- ? THINKING_BUDGET_MODEL_DEFAULT
394
- : rawThinkingBudget === -1
395
- ? -1
396
- : rawThinkingBudget > 0
397
- ? Math.max(0, Math.min(rawThinkingBudget, effectiveOutputCap - 1024))
398
- : 0;
399
- // Cost-estimate thinking-token reserve — tier-aware when the caller
400
- // uses `thinkingLevel`, worst-case when they use `thinkingBudget: -1`
401
- // or omit both fields (Gemini 3 Pro always spends thinking tokens per
402
- // Google's docs, so we reserve dynamic-thinking headroom there too).
403
- // When the caller passes an explicit positive `thinkingBudget`, we
404
- // reserve only that much. Keeps `GEMINI_DAILY_BUDGET_USD` a TRUE
405
- // upper bound on completed spend without false-rejecting callers
406
- // who legitimately use a low tier (see `THINKING_LEVEL_RESERVE`
407
- // rationale above).
408
- //
409
- // We dereference `input.thinkingLevel` directly (rather than via
410
- // `usingThinkingLevel`) so TypeScript narrows the type inside the
411
- // ternary — `THINKING_LEVEL_RESERVE[undefined]` would be a compile
412
- // error. The `?? worst-case` fallback handles the HIGH tier (which
413
- // maps to `null` in the reserve table to mean "use the dynamic cap").
414
- const thinkingTokensForEstimate = input.thinkingLevel !== undefined
415
- ? (THINKING_LEVEL_RESERVE[input.thinkingLevel] ?? Math.max(0, effectiveOutputCap - 1024))
416
- : effectiveThinkingBudget === null || effectiveThinkingBudget === -1
417
- ? Math.max(0, effectiveOutputCap - 1024)
418
- : effectiveThinkingBudget;
366
+ // A positive `thinkingBudget` that leaves no answer reserve under the caller's own cap is refused
367
+ // (`thinkingBudgetRefusal`); below, the budget on the wire is clamped under the cap that runs.
368
+ const budgetRefusal = thinkingBudgetRefusal(input.thinkingBudget, input.maxOutputTokens, outputCap.effective);
369
+ if (budgetRefusal !== null)
370
+ return errorResult(`ask: ${budgetRefusal}`);
419
371
  // Estimated input-token count drives both the daily-budget reservation
420
372
  // (dollars) and the TPM throttle reservation (rate). Hoisted here so
421
373
  // both consumers share one fingerprint — no drift between what the $
@@ -454,6 +406,8 @@ async function executeAskBody(input, ctx, workspaceRoot, model, started) {
454
406
  // model has no advertised `inputTokenLimit`.
455
407
  let preflight;
456
408
  const contextWindow = resolved.inputTokenLimit;
409
+ // A decode that may take more than one request takes the exact count: its prompt is billed per request.
410
+ const preflightMode = preflightModeFor(input.preflightMode, outputCap);
457
411
  if (typeof contextWindow === 'number' && contextWindow > 0) {
458
412
  preflight = await countForPreflight(ctx.client, {
459
413
  files: scan.files,
@@ -463,7 +417,7 @@ async function executeAskBody(input, ctx, workspaceRoot, model, started) {
463
417
  // already encodes user-supplied includeGlobs/excludeGlobs — no
464
418
  // separate globsHash axis needed in the cache key.
465
419
  filesHash: scan.filesHash,
466
- ...(input.preflightMode !== undefined ? { preflightMode: input.preflightMode } : {}),
420
+ ...(preflightMode !== undefined ? { preflightMode } : {}),
467
421
  inputTokenLimit: contextWindow,
468
422
  extraTokens: attachmentTokens, // weighs on the heuristic-vs-exact decision, added to the count below
469
423
  // Thread the user's `timeoutMs` AbortSignal so a hung countTokens
@@ -667,6 +621,38 @@ async function executeAskBody(input, ctx, workspaceRoot, model, started) {
667
621
  else {
668
622
  logger.warn(`ask: resolved model ${safeForLog(resolved.resolved)} has no advertised inputTokenLimit — workspace size guard skipped. Request may fail downstream if the workspace exceeds the model's context window.`);
669
623
  }
624
+ const { cap: runCap, cut: inputWindowCut } = capThatRuns({
625
+ tool: 'ask',
626
+ cap: outputCap,
627
+ promptTokens: preflight?.effectiveTokens,
628
+ inputTokenLimit: contextWindow,
629
+ emit: (message) => emitter.emit(message),
630
+ });
631
+ // Normalise thinkingBudget:
632
+ // undefined → null (model-default path — `thinkingBudget` OMITTED on wire)
633
+ // -1 → -1 (explicit legacy dynamic; kept for Gemini 2.5 and
634
+ // power-users who want to force the legacy path)
635
+ // 0 → 0 (thinking disabled; Gemini 3 Pro will 400 here)
636
+ // N > 0 → clamp to [0, cap that runs - 1024] — the thinking
637
+ // pool is carved out of the candidate-output allowance,
638
+ // so reserving ≥1024 tokens for the answer prevents 400s
639
+ // when a caller passes N ≥ maxOutputTokens, and under a
640
+ // cap the input window cut to one request (its value on
641
+ // the wire) the budget stays below it.
642
+ //
643
+ // Schema `.refine()` guarantees `thinkingBudget` and `thinkingLevel`
644
+ // are never both set, so we handle them in two mutually-exclusive
645
+ // branches below.
646
+ const rawThinkingBudget = input.thinkingBudget;
647
+ const effectiveThinkingBudget = rawThinkingBudget === undefined
648
+ ? THINKING_BUDGET_MODEL_DEFAULT
649
+ : rawThinkingBudget === -1
650
+ ? -1
651
+ : rawThinkingBudget > 0
652
+ ? thinkingBudgetUnder(runCap, rawThinkingBudget)
653
+ : 0;
654
+ // The thinking the budget reservation counts, from the cap that runs.
655
+ const thinkingTokensForEstimate = thinkingReserve(input.thinkingLevel, effectiveThinkingBudget, runCap);
670
656
  // Atomic budget reservation. Happens AFTER scan (so the estimate is
671
657
  // accurate) but BEFORE any billable upload or generateContent call.
672
658
  // Concurrent tool calls cannot all pass a pre-check and then
@@ -683,7 +669,11 @@ async function executeAskBody(input, ctx, workspaceRoot, model, started) {
683
669
  // OR model's full limit) as `expectedOutputTokens` — a TRUE
684
670
  // upper bound, since Gemini's default stops at the model's
685
671
  // advertised `outputTokenLimit`.
686
- expectedOutputTokens: effectiveOutputCap,
672
+ expectedOutputTokens: runCap.effective,
673
+ // A cap above the per-request limit (long decode) adds the input every continuation request bills again.
674
+ perRequestOutputTokens: runCap.perRequest,
675
+ // The preflight's count, when it ran: the reservation takes the larger of it and the bytes/4 heuristic.
676
+ countedInputTokens: preflight?.effectiveTokens,
687
677
  thinkingTokens: thinkingTokensForEstimate,
688
678
  coverMs: timeoutController.timeoutMs,
689
679
  });
@@ -715,7 +705,8 @@ async function executeAskBody(input, ctx, workspaceRoot, model, started) {
715
705
  // AFTER `prepareContext` returns from `activePrep.inlineOnly` — see FN2 fix.
716
706
  const caching = cachingModeFor(input.cachingMode ?? ctx.config.cachingMode, resolved, emitter);
717
707
  const requestedCachingMode = caching.mode;
718
- const ctxPrep = await prepareContext({
708
+ // The context of the call: built here, and again by the stale-cache retry on a fresh cache.
709
+ const prepare = () => prepareContext({
719
710
  client: ctx.client,
720
711
  manifest: ctx.manifest,
721
712
  scan,
@@ -731,33 +722,7 @@ async function executeAskBody(input, ctx, workspaceRoot, model, started) {
731
722
  // v1.13.0 — opt-in implicit caching path (skip caches.create).
732
723
  cachingMode: requestedCachingMode,
733
724
  });
734
- // TPM throttle reservation — placed HERE (after `prepareContext`,
735
- // immediately before `generateContent`) so the reservation's `tsMs`
736
- // accurately reflects when tokens hit Gemini's quota counter. An
737
- // earlier reserve (before `prepareContext`) would stamp `tsMs`
738
- // minutes before actual dispatch on cold-cache calls; our window
739
- // would then expire before Gemini's, leaving a gap where we admit
740
- // concurrent calls that bust Gemini's per-minute quota. Trade-off:
741
- // two concurrent cold-cache callers will both complete
742
- // `prepareContext` before one backs off at `reserve` — mostly
743
- // idempotent via file-hash dedup, minor upload duplication.
744
- //
745
- // Extracted into a helper so the stale-cache retry branch can
746
- // cancel-and-re-reserve with an accurate tsMs rather than reusing a
747
- // stale reservation stamped before the first (failed) dispatch.
748
- const reserveForDispatch = async () => {
749
- if (ctx.config.tpmThrottleLimit <= 0)
750
- return;
751
- const reservation = ctx.throttle.reserve(resolved.resolved, estimatedInputTokens);
752
- throttleReservationId = reservation.releaseId;
753
- if (reservation.delayMs > 0) {
754
- emitter.emit(`throttle: waiting ${Math.ceil(reservation.delayMs / 1000)}s for TPM window…`);
755
- // Abortable sleep — without this a 60s TPM throttle wait would block
756
- // a 10s wall-clock timeout, defeating T19's whole-dispatch contract.
757
- await abortableSleep(reservation.delayMs, abortSignal);
758
- }
759
- };
760
- await reserveForDispatch();
725
+ const ctxPrep = await prepare();
761
726
  emitter.emit(usingThinkingLevel
762
727
  ? `generating response (thinking-level=${input.thinkingLevel})…`
763
728
  : effectiveThinkingBudget === null
@@ -790,9 +755,9 @@ async function executeAskBody(input, ctx, workspaceRoot, model, started) {
790
755
  // `input.maxOutputTokens` — otherwise we omit it and Gemini uses
791
756
  // its model-default cap (per docs, = the model's advertised
792
757
  // `outputTokenLimit`, currently 65,536 for pro-tier 3.x/2.5). Budget
793
- // reservation always uses `effectiveOutputCap` (= explicit cap OR
794
- // model limit) as worst-case upper bound, so the daily cap stays a
795
- // true ceiling regardless.
758
+ // reservation always uses the cap the decode runs under (explicit cap
759
+ // OR model limit, cut by the input window on a long decode) as the
760
+ // worst-case upper bound, so the daily cap stays a true ceiling.
796
761
  // Cast to `ThinkingLevel` rather than indexing the runtime enum object
797
762
  // (`ThinkingLevel[input.thinkingLevel]`). For string enums the value
798
763
  // IS the member name, so passing `"HIGH"` as `ThinkingLevel` is
@@ -810,7 +775,7 @@ async function executeAskBody(input, ctx, workspaceRoot, model, started) {
810
775
  : { thinkingBudget: effectiveThinkingBudget, includeThoughts: true };
811
776
  const tierField = serviceTierConfig(serviceTier);
812
777
  const buildConfig = (cacheId) => {
813
- const maxOutputField = wireMaxOutputTokens !== undefined ? { maxOutputTokens: wireMaxOutputTokens } : {};
778
+ const maxOutputField = runCap.wire !== undefined ? { maxOutputTokens: runCap.wire } : {};
814
779
  return cacheId
815
780
  ? { cachedContent: cacheId, thinkingConfig, ...maxOutputField, ...tierField }
816
781
  : {
@@ -830,222 +795,70 @@ async function executeAskBody(input, ctx, workspaceRoot, model, started) {
830
795
  return attachments.parts.length === 0 ? input.prompt : [userTurn];
831
796
  return [...inline, userTurn];
832
797
  };
833
- // Track the prepared-context used for the FINAL successful call. Starts
834
- // pointing at the initial ctxPrep; retry branch below reassigns to the
835
- // rebuilt PreparedContext so post-call markHot + metadata reflect reality.
836
- let activePrep = ctxPrep;
837
- let retriedOnStaleCache = false;
838
- let response;
839
- try {
840
- // T20 (v1.7.0) — CRITICAL: withNetworkRetry wraps ONLY the stream
841
- // opening, NOT collectStream itself. If collectStream were inside the
842
- // retry closure, a mid-stream `TypeError: fetch failed` would discard
843
- // the partial response and re-issue a brand-new generateContentStream
844
- // — duplicating the model's billable work and emitting double
845
- // "thinking: …" progress lines. Mid-stream failure CANNOT be retried
846
- // (Gemini's generateContentStream doesn't support resume), so it must
847
- // propagate verbatim to the caller.
848
- const stream = await withNetworkRetry(() => ctx.client.models.generateContentStream({
849
- model: resolved.resolved,
850
- contents: buildContents(activePrep.cacheId, activePrep.inlineContents),
851
- config: { ...buildConfig(activePrep.cacheId), abortSignal },
852
- }), {
853
- attempts: networkAttempts(serviceTier), // a flex request is never re-sent
854
- signal: abortSignal,
855
- onRetry: (attempt, retryErr) => {
856
- logger.warn(`ask: retrying generateContent after transient network failure (attempt ${attempt}): ${retryErr instanceof Error ? retryErr.message : String(retryErr)}`);
857
- },
858
- });
859
- streamOpened = true;
860
- response = await collectStream(stream, {
861
- signal: abortSignal,
862
- onThoughtChunk: (text) => {
863
- // Surface the model's reasoning live as it arrives. Throttled
864
- // to ~1.5s by collectStream so the MCP host's progress channel
865
- // doesn't get flooded on long thinking bursts.
866
- const trimmed = text.trim().slice(0, 80);
867
- if (trimmed.length > 0)
868
- emitter.emit(`thinking: ${trimmed}…`);
869
- },
870
- // v1.12.0 — reset the stall watchdog on every chunk (text or
871
- // thought). Both prove the stream is alive. No-op when stall
872
- // is disabled (env + per-call both unset).
873
- onChunkReceived: () => timeoutController.recordChunk(),
874
- });
875
- }
876
- catch (err) {
877
- // Self-heal: if Gemini rejected our cached content (evicted, expired,
878
- // externally deleted), invalidate locally and retry ONCE with a fresh
879
- // cache. Prevents users from seeing hard failures they'd otherwise need
880
- // to clear/reindex manually. Budget: one retry; a second stale-cache
881
- // error propagates with both errors chained via Error.cause.
882
- if (activePrep.cacheId && isStaleCacheError(err)) {
883
- logger.warn(`Gemini rejected cached content ${activePrep.cacheId}; invalidating and retrying once.`);
884
- try {
885
- // Reset the cache pointer only — keep `files` rows so the rebuild
886
- // can reuse uploaded files via content-hash dedup instead of
887
- // re-uploading. The Gemini-side cache is already dead (that's
888
- // what triggered this branch), so no `caches.delete` needed.
889
- markCacheStale({ manifest: ctx.manifest, workspaceRoot });
890
- const rebuilt = await prepareContext({
891
- client: ctx.client,
892
- manifest: ctx.manifest,
893
- scan,
894
- model: resolved,
895
- systemPromptHash,
896
- systemInstruction: SYSTEM_INSTRUCTION_Q_AND_A,
897
- ttlSeconds: ctx.config.cacheTtlSeconds,
898
- cacheMinTokens: ctx.config.cacheMinTokens,
899
- emitter,
900
- allowCaching: !input.noCache && scan.files.length > 0,
901
- // v1.12.1 — propagate signal into stale-cache rebuild too.
902
- signal: abortSignal,
903
- // v1.13.0 — keep cachingMode consistent across happy + retry paths.
904
- cachingMode: requestedCachingMode,
905
- });
906
- // Cancel the original throttle reservation — its `tsMs` was
907
- // stamped at first-dispatch time, which is now seconds in the
908
- // past (the rebuild took real time). Re-reserve fresh so the
909
- // retry's tsMs reflects when the retry call actually hits
910
- // Gemini's quota counter. Without this, our window would expire
911
- // locally before Gemini's, leaving a gap where concurrent
912
- // callers bust the per-minute limit (PR #19 round-2 GPT review).
913
- if (throttleReservationId !== -1) {
914
- ctx.throttle.cancel(throttleReservationId);
915
- throttleReservationId = -1;
916
- }
917
- await reserveForDispatch();
918
- // The stale-cache retry itself can hit a transient network failure;
919
- // wrap it too so the rebuild isn't wasted on a one-off blip.
920
- // Stale-cache retry: discard partial response, open a brand-new
921
- // stream with the rebuilt cache. Gemini's stream API doesn't
922
- // support resume, so this is the only correct semantics.
923
- // Same retry-OPENING-only contract as the happy path — see above.
924
- const retryStream = await withNetworkRetry(() => ctx.client.models.generateContentStream({
925
- model: resolved.resolved,
926
- contents: buildContents(rebuilt.cacheId, rebuilt.inlineContents),
927
- config: { ...buildConfig(rebuilt.cacheId), abortSignal },
928
- }), {
929
- attempts: networkAttempts(serviceTier),
930
- signal: abortSignal,
931
- onRetry: (attempt, retryErr) => {
932
- logger.warn(`ask (stale-cache retry): retrying generateContent after transient network failure (attempt ${attempt}): ${retryErr instanceof Error ? retryErr.message : String(retryErr)}`);
933
- },
934
- });
935
- streamOpened = true;
936
- response = await collectStream(retryStream, {
937
- signal: abortSignal,
938
- onThoughtChunk: (text) => {
939
- const trimmed = text.trim().slice(0, 80);
940
- if (trimmed.length > 0)
941
- emitter.emit(`thinking: ${trimmed}…`);
942
- },
943
- // v1.12.0 — stall watchdog reset on retry stream too.
944
- onChunkReceived: () => timeoutController.recordChunk(),
945
- });
946
- activePrep = rebuilt;
947
- retriedOnStaleCache = true;
948
- }
949
- catch (retryErr) {
950
- // Re-throw the retry's TimeoutError directly so the outer catch's
951
- // `isTimeoutAbort` check sees it on the cause chain. Without this,
952
- // wrapping with `cause: err` (the original stale-cache error)
953
- // would mask the timeout — outer catch maps to UNKNOWN instead of
954
- // TIMEOUT, breaking the contract on stale-cache+timeout paths.
955
- if (isTimeoutAbort(retryErr))
956
- throw retryErr;
957
- // Otherwise preserve the ORIGINAL stale-cache error as `cause` so
958
- // ops can root-cause diagnostics across both the first 404 and any
959
- // rebuild-time failure.
960
- // an HTTP error on the retry (a 429/503) IS the error: thrown as the SDK made it, so its status and the
961
- // throttle's retry hint are read as usual; only a status-less failure is wrapped over the stale 404
962
- if (statusOf(retryErr) !== undefined)
963
- throw retryErr;
964
- throw new Error(`ask retry after stale cache failed: ${retryErr instanceof Error ? retryErr.message : String(retryErr)}`, { cause: err });
965
- }
966
- }
967
- else {
968
- throw err;
969
- }
970
- }
971
- if (activePrep.cacheId) {
972
- ctx.ttlWatcher.markHot(workspaceRoot, activePrep.cacheId, ctx.config.cacheTtlSeconds);
973
- }
798
+ // The decode — and, on a stale cache before any request completed, its one retry on a rebuilt cache. The TPM
799
+ // reservation is taken here, after `prepareContext` and immediately before the first request, so its timestamp
800
+ // is when the tokens reach Gemini's quota counter; only the OPENING of a request is retried (a mid-stream
801
+ // failure re-sent would bill the work again).
802
+ const decoded = await decodeOnContext({
803
+ client: ctx.client,
804
+ booking: { workspaceRoot, toolName: 'ask', model: resolved.resolved, serviceTier },
805
+ cachingMode: (prep) => cachingRan(prep, caching).mode,
806
+ request: (prep) => ({
807
+ contents: buildContents(prep.cacheId, prep.inlineContents),
808
+ config: buildConfig(prep.cacheId),
809
+ }),
810
+ cache: {
811
+ ttlWatcher: ctx.ttlWatcher,
812
+ manifest: ctx.manifest,
813
+ ttlSeconds: ctx.config.cacheTtlSeconds,
814
+ prepare,
815
+ },
816
+ openAttempts: networkAttempts(serviceTier), // a flex request is never re-sent
817
+ limits: { maxRequests: runCap.maxRequests, cap: runCap.effective },
818
+ timeout: timeoutController,
819
+ emit: (message) => emitter.emit(message),
820
+ completed,
821
+ tracking,
822
+ throttle: dispatch,
823
+ inputTokens: { estimated: estimatedInputTokens, counted: preflight?.effectiveTokens },
824
+ }, ctxPrep);
825
+ const { response, prep: activePrep, retriedOnStaleCache } = decoded;
974
826
  const text = response.text;
975
827
  // `collectStream` already aggregated thought-flagged parts and capped
976
828
  // the joined summary at 1200 chars (T20). Reuse directly — re-iterating
977
829
  // `response.candidates` would risk drift between in-flight thought
978
830
  // emit (live progress) and post-call summary.
979
831
  const thinkingSummary = response.thoughtsSummary;
980
- const usage = response.usageMetadata;
981
- const cached = typeof usage?.cachedContentTokenCount === 'number' ? usage.cachedContentTokenCount : 0;
982
- const inputTotal = typeof usage?.promptTokenCount === 'number' ? usage.promptTokenCount : 0;
983
- const uncached = Math.max(0, inputTotal - cached);
984
- const output = typeof usage?.candidatesTokenCount === 'number' ? usage.candidatesTokenCount : 0;
985
- const thinking = typeof usage?.thoughtsTokenCount === 'number' ? usage.thoughtsTokenCount : 0;
986
- // Finalise the throttle reservation with Gemini's actual
987
- // `promptTokenCount` — includes cached tokens, which DO count against
988
- // the per-minute quota (empirically confirmed 2026-04-20). If actual
989
- // < estimate, subsequent reserves see the freed headroom; if >, they
990
- // back off accordingly.
991
- if (throttleReservationId !== -1) {
992
- ctx.throttle.release(throttleReservationId, inputTotal);
993
- throttleReservationId = -1;
994
- }
995
- const cost = estimateCostUsd({
996
- model: resolved.resolved,
997
- serviceTier,
998
- uncachedInputTokens: uncached,
999
- cachedInputTokens: cached,
1000
- outputTokens: output,
1001
- thinkingTokens: thinking,
1002
- });
1003
- const costMicros = toMicrosUsd(cost);
1004
832
  // Telemetry and the response record the mode that ran, not the one asked for.
1005
833
  const ran = cachingRan(activePrep, caching);
1006
834
  const effectiveCachingMode = ran.mode;
1007
835
  const durationMs = Date.now() - started;
1008
- if (reservationId !== null) {
1009
- // The finalize UPDATE on a row we just inserted should be infallible
1010
- // in practice, but a disk-full / lock-contention edge could throw.
1011
- // If it does, we'd rather keep the reservation row (estimate stays
1012
- // billed, slight overcharge) than let the outer catch CANCEL it
1013
- // — cancelling would erase any record of this billable, completed
1014
- // call. Either way, drop `reservationId` so the outer catch doesn't
1015
- // touch it.
1016
- try {
1017
- ctx.manifest.finalizeBudgetReservation(reservationId, {
1018
- cachedTokens: cached,
1019
- uncachedTokens: uncached,
1020
- costUsdMicro: costMicros,
1021
- durationMs,
1022
- cachingMode: effectiveCachingMode,
1023
- cachedContentTokenCount: cached,
1024
- });
1025
- }
1026
- catch (finalizeErr) {
1027
- logger.error(`ask: finalizeBudgetReservation failed for id=${reservationId}; reservation row keeps the estimate (${costMicros} micros). Error: ${String(finalizeErr)}`);
1028
- }
1029
- reservationId = null;
1030
- }
1031
- else {
1032
- ctx.manifest.insertUsageMetric({
836
+ // Settled here, once: the outer catch then neither releases the reservation nor books the call again. What the
837
+ // API billed is every request that completed, over a long decode and a stale-cache retry alike.
838
+ const settledReservation = reservationId;
839
+ reservationId = null;
840
+ tracking.ledgerEntry = null;
841
+ const settled = settleAnswer({
842
+ manifest: ctx.manifest,
843
+ reservationId: settledReservation,
844
+ entry: {
1033
845
  workspaceRoot,
1034
846
  toolName: 'ask',
1035
847
  model: resolved.resolved,
1036
- cachedTokens: cached,
1037
- uncachedTokens: uncached,
1038
- costUsdMicro: costMicros,
1039
- durationMs,
1040
- occurredAt: Date.now(),
848
+ serviceTier,
1041
849
  cachingMode: effectiveCachingMode,
1042
- cachedContentTokenCount: cached,
1043
- });
1044
- }
850
+ },
851
+ completed,
852
+ response,
853
+ cap: runCap,
854
+ cut: inputWindowCut,
855
+ durationMs,
856
+ });
857
+ const finish = settled.finish;
1045
858
  // Settled and billed above; an empty answer at the cap is a failure the caller can act on, never a success.
1046
- const starved = emptyAtOutputCap(response, thinking);
1047
- if (starved !== null)
1048
- return errorResult(`ask: ${starved}`);
859
+ if (settled.outputCapStop !== null) {
860
+ return errorResult(`ask: ${settled.outputCapStop.message}`, settled.outputCapStop.fields);
861
+ }
1049
862
  if (scan.truncated) {
1050
863
  logger.warn(`workspace ${workspaceRoot} contains more files than GEMINI_CODE_CONTEXT_MAX_FILES (${ctx.config.maxFilesPerWorkspace}); the tail was dropped before indexing.`);
1051
864
  }
@@ -1060,11 +873,11 @@ async function executeAskBody(input, ctx, workspaceRoot, model, started) {
1060
873
  contextWindow: resolved.inputTokenLimit,
1061
874
  thinkingBudget: effectiveThinkingBudget,
1062
875
  thinkingLevel: input.thinkingLevel ?? null,
1063
- cachedTokens: cached,
1064
- uncachedTokens: uncached,
1065
- outputTokens: output,
1066
- thinkingTokens: thinking,
1067
- costEstimateUsd: Math.round(cost * 10000) / 10000,
876
+ ...settled.usage,
877
+ ...settled.cutFields,
878
+ // `truncated`: the answer stopped at the output cap (MAX_TOKENS, or a long decode at its limits) — it is cut
879
+ finishReason: finish.finishReason,
880
+ truncated: finish.truncated,
1068
881
  cacheHit: activePrep.reused,
1069
882
  cacheRebuilt: activePrep.rebuilt || retriedOnStaleCache,
1070
883
  retriedOnStaleCache,
@@ -1104,49 +917,23 @@ async function executeAskBody(input, ctx, workspaceRoot, model, started) {
1104
917
  }
1105
918
  catch (err) {
1106
919
  logger.error(`ask failed: ${safeForLog(err)}`);
1107
- // T22a — extract Gemini's `retryInfo.retryDelay` from 429 bodies and
1108
- // seed the throttle's per-model hint before we release the
1109
- // reservation. Google's hint is typically shorter (2-16s) than our
1110
- // pure-window math would compute (up to 60s+) so honouring it
1111
- // shortens the next caller's wait.
1112
- //
1113
- // Gated on `isGemini429` BEFORE parsing. The predicate requires BOTH
1114
- // `err instanceof ApiError` (SDK-provenance marker — user-controlled
1115
- // content can't forge an ApiError prototype) AND `err.status === 429`
1116
- // (typed field from the HTTP response). The earlier v1.3.2 draft had
1117
- // a `RESOURCE_EXHAUSTED` substring fallback; GPT + Grok round-2
1118
- // review (PR #21) showed that path was user-influenceable — echoed
1119
- // prompt content re-opened the hint-poisoning class the gate was
1120
- // meant to close. Removing the fallback drops hint extraction for
1121
- // errors that lose the ApiError shape in transit, but production
1122
- // 429s always arrive as real ApiError instances.
1123
- const retryDelayMs = isGemini429(err) ? parseRetryDelayMs(err.message) : null;
1124
- if (retryDelayMs !== null && resolvedModelKey !== null) {
1125
- ctx.throttle.recordRetryHint(resolvedModelKey, retryDelayMs);
1126
- }
1127
- // Release any unconsumed budget reservation so the failed call's
1128
- // estimate doesn't eat into future headroom for today. Wrap in its
1129
- // own try/catch — better-sqlite3 can throw SQLITE_BUSY or I/O errors
1130
- // and we must not let a rollback-time DB failure replace the real
1131
- // tool error the user is waiting on.
1132
- if (reservationId !== null) {
1133
- try {
1134
- ctx.manifest.cancelBudgetReservation(reservationId);
1135
- }
1136
- catch (cancelErr) {
1137
- logger.error(`ask: cancelBudgetReservation failed for id=${reservationId}; reservation row keeps the estimate. Error: ${String(cancelErr)}`);
1138
- }
1139
- reservationId = null;
1140
- }
1141
- // Drop the TPM reservation on any failure path. If Gemini actually
1142
- // consumed quota server-side before failing, the hint path above
1143
- // (T22a) compensates via `recordRetryHint` before we cancel. For
1144
- // non-429 errors (validation, transport), we under-count slightly
1145
- // but bounded — accepted trade-off documented in PR #19 round-2.
1146
- if (throttleReservationId !== -1) {
1147
- ctx.throttle.cancel(throttleReservationId);
1148
- throttleReservationId = -1;
1149
- }
920
+ // A 429's retry hint seeds the throttle; the ledger keeps what the completed requests billed and releases the rest
921
+ // of the reservation (all of it when none completed); their usage goes into the error result.
922
+ const failedUsage = settleFailure({
923
+ manifest: ctx.manifest,
924
+ failed: {
925
+ toolName: 'ask',
926
+ reservationId,
927
+ entry: tracking.ledgerEntry,
928
+ completed,
929
+ durationMs: Date.now() - started,
930
+ },
931
+ err,
932
+ model: resolvedModelKey,
933
+ throttle: ctx.throttle,
934
+ dispatch,
935
+ });
936
+ reservationId = null;
1150
937
  // Timeout-driven abort gets a dedicated errorCode so callers can
1151
938
  // distinguish "Gemini was slow" from "schema invalid" / "auth failed".
1152
939
  // v1.12.0 — `timeoutKind` ('total' | 'stall') distinguishes the
@@ -1168,13 +955,15 @@ async function executeAskBody(input, ctx, workspaceRoot, model, started) {
1168
955
  stallMs,
1169
956
  retryable: true,
1170
957
  serviceTier: reportedTier(),
958
+ ...failedUsage,
1171
959
  });
1172
960
  }
1173
961
  const httpStatus = statusOf(err);
1174
962
  return errorResult(`ask failed: ${err instanceof Error ? err.message : String(err)}`, {
1175
- ...tierErrorMeta(err, streamOpened),
963
+ ...tierErrorMeta(err, tracking.streamOpened),
1176
964
  serviceTier: reportedTier(),
1177
965
  ...(httpStatus !== undefined ? { httpStatus } : {}),
966
+ ...failedUsage,
1178
967
  });
1179
968
  }
1180
969
  finally {