@qmediat.io/gemini-code-context-mcp 1.23.0 → 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 (76) hide show
  1. package/CHANGELOG.md +94 -1
  2. package/README.md +36 -227
  3. package/dist/auth/profile-loader.js +1 -1
  4. package/dist/auth/profile-loader.js.map +1 -1
  5. package/dist/cache/ttl-watcher.d.ts +29 -0
  6. package/dist/cache/ttl-watcher.d.ts.map +1 -1
  7. package/dist/cache/ttl-watcher.js +104 -43
  8. package/dist/cache/ttl-watcher.js.map +1 -1
  9. package/dist/gemini/client.d.ts +7 -0
  10. package/dist/gemini/client.d.ts.map +1 -1
  11. package/dist/gemini/client.js +8 -1
  12. package/dist/gemini/client.js.map +1 -1
  13. package/dist/gemini/long-decode.d.ts +153 -0
  14. package/dist/gemini/long-decode.d.ts.map +1 -0
  15. package/dist/gemini/long-decode.js +178 -0
  16. package/dist/gemini/long-decode.js.map +1 -0
  17. package/dist/gemini/model-registry.d.ts +2 -0
  18. package/dist/gemini/model-registry.d.ts.map +1 -1
  19. package/dist/gemini/model-registry.js +5 -2
  20. package/dist/gemini/model-registry.js.map +1 -1
  21. package/dist/gemini/models.d.ts.map +1 -1
  22. package/dist/gemini/models.js +1 -0
  23. package/dist/gemini/models.js.map +1 -1
  24. package/dist/gemini/retry.d.ts +8 -0
  25. package/dist/gemini/retry.d.ts.map +1 -1
  26. package/dist/gemini/retry.js +33 -1
  27. package/dist/gemini/retry.js.map +1 -1
  28. package/dist/tools/ask-agentic.tool.d.ts.map +1 -1
  29. package/dist/tools/ask-agentic.tool.js +10 -12
  30. package/dist/tools/ask-agentic.tool.js.map +1 -1
  31. package/dist/tools/ask.tool.d.ts.map +1 -1
  32. package/dist/tools/ask.tool.js +168 -379
  33. package/dist/tools/ask.tool.js.map +1 -1
  34. package/dist/tools/code.tool.d.ts +6 -0
  35. package/dist/tools/code.tool.d.ts.map +1 -1
  36. package/dist/tools/code.tool.js +146 -286
  37. package/dist/tools/code.tool.js.map +1 -1
  38. package/dist/tools/shared/abort-timeout.d.ts +6 -0
  39. package/dist/tools/shared/abort-timeout.d.ts.map +1 -1
  40. package/dist/tools/shared/abort-timeout.js +12 -0
  41. package/dist/tools/shared/abort-timeout.js.map +1 -1
  42. package/dist/tools/shared/call-ledger.d.ts +73 -0
  43. package/dist/tools/shared/call-ledger.d.ts.map +1 -0
  44. package/dist/tools/shared/call-ledger.js +115 -0
  45. package/dist/tools/shared/call-ledger.js.map +1 -0
  46. package/dist/tools/shared/context-decode.d.ts +77 -0
  47. package/dist/tools/shared/context-decode.d.ts.map +1 -0
  48. package/dist/tools/shared/context-decode.js +125 -0
  49. package/dist/tools/shared/context-decode.js.map +1 -0
  50. package/dist/tools/shared/continuation.d.ts +124 -0
  51. package/dist/tools/shared/continuation.d.ts.map +1 -0
  52. package/dist/tools/shared/continuation.js +302 -0
  53. package/dist/tools/shared/continuation.js.map +1 -0
  54. package/dist/tools/shared/dispatch-throttle.d.ts +43 -0
  55. package/dist/tools/shared/dispatch-throttle.d.ts.map +1 -0
  56. package/dist/tools/shared/dispatch-throttle.js +65 -0
  57. package/dist/tools/shared/dispatch-throttle.js.map +1 -0
  58. package/dist/tools/shared/settle-call.d.ts +63 -0
  59. package/dist/tools/shared/settle-call.d.ts.map +1 -0
  60. package/dist/tools/shared/settle-call.js +55 -0
  61. package/dist/tools/shared/settle-call.js.map +1 -0
  62. package/dist/tools/shared/stream-collector.d.ts +7 -0
  63. package/dist/tools/shared/stream-collector.d.ts.map +1 -1
  64. package/dist/tools/shared/stream-collector.js +5 -1
  65. package/dist/tools/shared/stream-collector.js.map +1 -1
  66. package/dist/tools/shared/thinking.d.ts +41 -11
  67. package/dist/tools/shared/thinking.d.ts.map +1 -1
  68. package/dist/tools/shared/thinking.js +62 -9
  69. package/dist/tools/shared/thinking.js.map +1 -1
  70. package/dist/types.d.ts +2 -0
  71. package/dist/types.d.ts.map +1 -1
  72. package/dist/utils/cost-estimator.d.ts +17 -0
  73. package/dist/utils/cost-estimator.d.ts.map +1 -1
  74. package/dist/utils/cost-estimator.js +15 -2
  75. package/dist/utils/cost-estimator.js.map +1 -1
  76. package/package.json +5 -3
@@ -10,24 +10,26 @@
10
10
  import { createHash } from 'node:crypto';
11
11
  import { resolve } from 'node:path';
12
12
  import { z } from 'zod';
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 { ModelCategoryMismatchError } from '../gemini/model-taxonomy.js';
16
17
  import { resolveModel } from '../gemini/models.js';
17
- import { abortableSleep, withNetworkRetry } from '../gemini/retry.js';
18
18
  import { countForPreflight } from '../gemini/token-counter.js';
19
19
  import { buildScanMemo, scanWorkspace } from '../indexer/workspace-scanner.js';
20
20
  import { WorkspaceValidationError, validateWorkspacePath, } from '../indexer/workspace-validation.js';
21
- import { estimateCostUsd, estimatePreCallCostUsd, toMicrosUsd } from '../utils/cost-estimator.js';
21
+ import { estimatePreCallCostUsd, toMicrosUsd } from '../utils/cost-estimator.js';
22
22
  import { logger, safeForLog } from '../utils/logger.js';
23
23
  import { createProgressEmitter } from '../utils/progress.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
  * `code` system instruction. Prepends the shared `SYSTEM_INSTRUCTION_SAFETY_EAGER`
33
35
  * data-vs-instruction firewall (added in v1.15.2 — pre-v1.15.2 `code` had no
@@ -92,7 +94,10 @@ export const codeInputSchema = z
92
94
  .int()
93
95
  .min(1)
94
96
  .optional()
95
- .describe("Per-call opt-in cap on response length (tokens). OMIT for auto — 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 to bound a specific call (e.g. `maxOutputTokens: 16384` for a tight code-review summary). Values larger than the resolved model's limit are clamped. Operators who want EVERY call at full model capacity set `GEMINI_CODE_CONTEXT_FORCE_MAX_OUTPUT=true` at MCP-host level — that env override is still beaten by this per-call field."),
97
+ .describe([
98
+ "Per-call opt-in cap on response length (tokens). OMIT for auto — 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 to bound a specific call (e.g. `maxOutputTokens: 16384` for a tight code-review summary). On any other model a value larger than the resolved model's limit is clamped to it. Operators who want EVERY call at full model capacity set `GEMINI_CODE_CONTEXT_FORCE_MAX_OUTPUT=true` at MCP-host level — that env override is still beaten by this per-call field.",
99
+ LONG_DECODE_CAP_DESCRIPTION,
100
+ ].join(' ')),
96
101
  includeGlobs: z
97
102
  .array(z.string())
98
103
  .optional()
@@ -140,6 +145,14 @@ export const codeInputSchema = z
140
145
  message: "`thinkingLevel: 'XHIGH'` is not usable with `code`: only Gemini 4 Hydrogen takes it, a fast-tier model, and `code` runs reasoning-tier models, which answer it with a 400. Use `HIGH` here, or `ask` with `model: 'gemini-4-hydrogen'`.",
141
146
  path: ['thinkingLevel'],
142
147
  });
148
+ /** Leads the text result of an answer with edits (`expectEdits`) cut at the output cap: its edit list is incomplete. */
149
+ export const TRUNCATED_EDITS_NOTE = '[truncated] The answer stopped at the output cap before the model finished it (see `finishReason`): the edit list below is cut — do not apply it as complete. Raise `maxOutputTokens` or lower the thinking, and ask again.';
150
+ /** Leads the text result of a prose answer (`expectEdits: false`) cut at the output cap. */
151
+ export const TRUNCATED_ANSWER_NOTE = '[truncated] The answer stopped at the output cap before the model finished it (see `finishReason`): the answer below is cut. Raise `maxOutputTokens` or lower the thinking, and ask again.';
152
+ /** The note that leads a truncated answer: about its edit list when edits were asked for, else about the prose. */
153
+ export function truncatedNote(expectEdits) {
154
+ return expectEdits ? TRUNCATED_EDITS_NOTE : TRUNCATED_ANSWER_NOTE;
155
+ }
143
156
  const EDIT_REGEX = /\*\*FILE: (.+?)\*\*\s*\n```[^\n]*\n(?:OLD:\s*\n([\s\S]*?)\n)?NEW:\s*\n([\s\S]*?)\n```/g;
144
157
  /** @internal — exported for testing only. Not part of the public API surface. */
145
158
  export function parseEdits(text) {
@@ -234,13 +247,13 @@ async function executeCodeBody(input, ctx, workspaceRoot, started) {
234
247
  // undefined and we take the level branch below.
235
248
  const thinkingBudget = usingThinkingLevel ? undefined : (input.thinkingBudget ?? 16_384);
236
249
  let reservationId = null;
237
- // `-1` signals "no reservation held". Mirror of ask.tool.ts.
238
- let throttleReservationId = -1;
239
250
  // Canonical resolved-model string for retry-hint seeding (T22a).
240
251
  // See ask.tool.ts for rationale.
241
252
  let resolvedModelKey = null;
242
- // once a stream opened, a later transport failure is mid-stream: billed work, not to be re-sent
243
- let streamOpened = false;
253
+ // every request that completed is billed: the ledger settles from these, on an answer and on a failure alike
254
+ const completed = new CompletedRequests();
255
+ // the running decode's booking and whether a stream opened (a later failure is then billed work, not re-sent)
256
+ const tracking = { ledgerEntry: null, streamOpened: false };
244
257
  let modelAudit = {};
245
258
  const emitter = createProgressEmitter(ctx.server, ctx.progressToken);
246
259
  // T19 + Phase 4 — composite controller (wall-clock + stall watchdog).
@@ -252,6 +265,13 @@ async function executeCodeBody(input, ctx, workspaceRoot, started) {
252
265
  stallEnvVar: 'GEMINI_CODE_CONTEXT_CODE_STALL_MS',
253
266
  });
254
267
  const abortSignal = timeoutController.signal;
268
+ // Each request of the decode holds its own TPM reservation; a failure drops the one held.
269
+ const dispatch = new DispatchThrottle({
270
+ throttle: ctx.throttle,
271
+ enabled: ctx.config.tpmThrottleLimit > 0,
272
+ signal: abortSignal,
273
+ emit: (message) => emitter.emit(message),
274
+ });
255
275
  try {
256
276
  // Workspace validation inside try → reported as a regular tool error
257
277
  // (errorResult, "code failed: …") rather than an unhandled exception
@@ -320,62 +340,20 @@ async function executeCodeBody(input, ctx, workspaceRoot, started) {
320
340
  // heavy review work set `GEMINI_CODE_CONTEXT_FORCE_MAX_OUTPUT=true`
321
341
  // to pin every call at the model's full 65,536-token capacity.
322
342
  const CODE_MAX_OUTPUT_TOKENS_FALLBACK = 65_536;
323
- const modelOutputLimit = typeof resolved.outputTokenLimit === 'number' && resolved.outputTokenLimit > 0
324
- ? resolved.outputTokenLimit
325
- : CODE_MAX_OUTPUT_TOKENS_FALLBACK;
326
- const wireMaxOutputTokens = input.maxOutputTokens !== undefined
327
- ? Math.min(input.maxOutputTokens, modelOutputLimit)
328
- : ctx.config.forceMaxOutputTokens
329
- ? modelOutputLimit
330
- : undefined;
331
- // Effective cap for thinking-budget clamp and budget reservation.
332
- // When auto (neither override set), Gemini's model-default equals
333
- // modelOutputLimit per Google docs, so using the limit as worst-case
334
- // keeps the daily $ cap a true upper bound.
335
- const effectiveOutputCap = wireMaxOutputTokens ?? modelOutputLimit;
336
- // Gemini requires `thinkingBudget < maxOutputTokens` (the thinking pool
337
- // is carved out of the candidate-output allowance). The hard cap above
338
- // may clamp maxOutputTokens as low as the model's `outputTokenLimit`
339
- // (e.g. 8_192 on Flash-lite). Clamp the effective thinkingBudget so
340
- // the generateContent call never 400s on this invariant; reserve at
341
- // least 1_024 tokens for the actual completion.
342
- //
343
- // Only meaningful on the thinkingBudget path — when the caller uses
344
- // `thinkingLevel` instead, `thinkingBudget` is `undefined` and this
345
- // value is ignored by the thinkingConfig builder below.
346
- //
347
- // Early-reject when the caller's per-call `maxOutputTokens` can't fit
348
- // an explicit positive `thinkingBudget` + 1024-token answer reserve.
349
- // Silently clamping to 0 would make Gemini 3 Pro 400 on a
350
- // "thinking disabled" error and obscure the real mismatch (PR #22
351
- // round-3 review finding #C).
352
- if (input.thinkingBudget !== undefined &&
353
- input.thinkingBudget > 0 &&
354
- input.maxOutputTokens !== undefined &&
355
- effectiveOutputCap < input.thinkingBudget + 1024) {
356
- return errorResult(`code: thinkingBudget (${input.thinkingBudget}) + 1024-token answer reserve exceeds maxOutputTokens (${effectiveOutputCap}). Raise \`maxOutputTokens\` to at least ${input.thinkingBudget + 1024}, or lower \`thinkingBudget\`.`);
357
- }
358
- const effectiveThinkingBudget = thinkingBudget !== undefined && thinkingBudget > 0
359
- ? Math.max(0, Math.min(thinkingBudget, effectiveOutputCap - 1024))
360
- : 0;
361
- // Cost-estimate thinking-token reserve — tier-aware when the caller
362
- // uses `thinkingLevel`, exact-on-the-budget when they use
363
- // `thinkingBudget`. Mirror of `ask.tool.ts` logic; see
364
- // `THINKING_LEVEL_RESERVE` in `shared/thinking.ts` for the rationale
365
- // behind the per-tier numbers and why HIGH falls through to the
366
- // dynamic cap.
367
- //
368
- // Defensive clamp: tier reserves (MINIMAL=512, LOW=2048, MEDIUM=4096)
369
- // are fixed constants, but `maxOutputTokens` can be clamped down to a
370
- // resolved model's `outputTokenLimit`. A future small-cap model (say
371
- // `outputTokenLimit: 4000`) would let MEDIUM's 4096 exceed the
372
- // available headroom and over-estimate the budget reservation. Clamp
373
- // every tier's reserve against the dynamic headroom so the upper
374
- // bound stays coherent across model rollouts (PR #17 self-review F2).
375
- const thinkingHeadroom = Math.max(0, effectiveOutputCap - 1024);
376
- const thinkingTokensForEstimate = input.thinkingLevel !== undefined
377
- ? Math.min(THINKING_LEVEL_RESERVE[input.thinkingLevel] ?? thinkingHeadroom, thinkingHeadroom)
378
- : effectiveThinkingBudget;
343
+ // The caller's `thinkingBudget` is checked against `outputCap` (the wire cap, else the model's per-request limit);
344
+ // the clamp and the reservation use the cap that runs (`runCap`, after the input window's cut).
345
+ const outputCap = resolveOutputCap({
346
+ requested: input.maxOutputTokens,
347
+ forceMax: ctx.config.forceMaxOutputTokens,
348
+ outputTokenLimit: resolved.outputTokenLimit,
349
+ longDecodeTokenLimit: resolved.longDecodeTokenLimit,
350
+ fallbackLimit: CODE_MAX_OUTPUT_TOKENS_FALLBACK,
351
+ });
352
+ // A positive `thinkingBudget` that leaves no answer reserve under the caller's own cap is refused
353
+ // (`thinkingBudgetRefusal`); below, the budget on the wire is clamped under the cap that runs.
354
+ const budgetRefusal = thinkingBudgetRefusal(input.thinkingBudget, input.maxOutputTokens, outputCap.effective);
355
+ if (budgetRefusal !== null)
356
+ return errorResult(`code: ${budgetRefusal}`);
379
357
  // Shared input-token fingerprint for budget + TPM throttle (see
380
358
  // ask.tool.ts for the rationale — same `Math.ceil(bytes/4)` tokenisation
381
359
  // used by `estimatePreCallCostUsd`). The PREFLIGHT against
@@ -389,6 +367,8 @@ async function executeCodeBody(input, ctx, workspaceRoot, started) {
389
367
  // success-path metadata can surface preflight provenance.
390
368
  let preflight;
391
369
  const contextWindow = resolved.inputTokenLimit;
370
+ // A decode that may take more than one request takes the exact count: its prompt is billed per request.
371
+ const preflightMode = preflightModeFor(input.preflightMode, outputCap);
392
372
  if (typeof contextWindow === 'number' && contextWindow > 0) {
393
373
  preflight = await countForPreflight(ctx.client, {
394
374
  files: scan.files,
@@ -396,7 +376,7 @@ async function executeCodeBody(input, ctx, workspaceRoot, started) {
396
376
  model: resolved.resolved,
397
377
  // `filesHash` is post-glob-filter — no separate globsHash needed.
398
378
  filesHash: scan.filesHash,
399
- ...(input.preflightMode !== undefined ? { preflightMode: input.preflightMode } : {}),
379
+ ...(preflightMode !== undefined ? { preflightMode } : {}),
400
380
  inputTokenLimit: contextWindow,
401
381
  // See ask.tool.ts for AbortSignal contract — abort propagates as
402
382
  // `AbortError` to outer catch (mapped to `errorCode: 'TIMEOUT'`).
@@ -423,6 +403,20 @@ async function executeCodeBody(input, ctx, workspaceRoot, started) {
423
403
  else {
424
404
  logger.warn(`code: 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.`);
425
405
  }
406
+ const { cap: runCap, cut: inputWindowCut } = capThatRuns({
407
+ tool: 'code',
408
+ cap: outputCap,
409
+ promptTokens: preflight?.effectiveTokens,
410
+ inputTokenLimit: contextWindow,
411
+ emit: (message) => emitter.emit(message),
412
+ });
413
+ // The budget on the wire: clamped below the cap that runs, after the input window's cut — a cap cut to one
414
+ // request goes on the wire as its cut value, and `thinkingBudget < maxOutputTokens` holds there too.
415
+ const effectiveThinkingBudget = thinkingBudget !== undefined && thinkingBudget > 0
416
+ ? thinkingBudgetUnder(runCap, thinkingBudget)
417
+ : 0;
418
+ // The thinking the budget reservation counts, from the cap that runs.
419
+ const thinkingTokensForEstimate = thinkingReserve(input.thinkingLevel, effectiveThinkingBudget, runCap);
426
420
  // Atomic budget reservation — see ask.tool.ts for the full rationale.
427
421
  // Estimate includes the thinking budget (billed as output tokens on Pro)
428
422
  // PLUS the candidate output cap.
@@ -432,7 +426,11 @@ async function executeCodeBody(input, ctx, workspaceRoot, started) {
432
426
  serviceTier,
433
427
  workspaceBytes,
434
428
  promptChars: input.task.length,
435
- expectedOutputTokens: effectiveOutputCap,
429
+ expectedOutputTokens: runCap.effective,
430
+ // A cap above the per-request limit (long decode) adds the input every continuation request bills again.
431
+ perRequestOutputTokens: runCap.perRequest,
432
+ // The preflight's count, when it ran: the reservation takes the larger of it and the bytes/4 heuristic.
433
+ countedInputTokens: preflight?.effectiveTokens,
436
434
  thinkingTokens: thinkingTokensForEstimate,
437
435
  coverMs: timeoutController.timeoutMs,
438
436
  });
@@ -461,7 +459,8 @@ async function executeCodeBody(input, ctx, workspaceRoot, started) {
461
459
  // codeExecution-forced-inline path stay distinguishable.
462
460
  const caching = cachingModeFor(input.cachingMode ?? ctx.config.cachingMode, resolved, emitter);
463
461
  const requestedCachingMode = caching.mode;
464
- const ctxPrep = await prepareContext({
462
+ // The context of the call: built here, and again by the stale-cache retry on a fresh cache.
463
+ const prepare = () => prepareContext({
465
464
  client: ctx.client,
466
465
  manifest: ctx.manifest,
467
466
  scan,
@@ -481,26 +480,7 @@ async function executeCodeBody(input, ctx, workspaceRoot, started) {
481
480
  // v1.13.0 — opt-in implicit caching path (skip caches.create).
482
481
  cachingMode: requestedCachingMode,
483
482
  });
484
- // TPM throttle — placed AFTER `prepareContext`, immediately before
485
- // `generateContent`, so the reservation's `tsMs` accurately reflects
486
- // when tokens hit Gemini's quota counter. See ask.tool.ts for the
487
- // full rationale and the cold-cache-timing concern it fixes.
488
- //
489
- // Extracted into a helper so the stale-cache retry branch can
490
- // cancel-and-re-reserve with an accurate tsMs rather than reusing a
491
- // stale reservation.
492
- const reserveForDispatch = async () => {
493
- if (ctx.config.tpmThrottleLimit <= 0)
494
- return;
495
- const reservation = ctx.throttle.reserve(resolved.resolved, estimatedInputTokens);
496
- throttleReservationId = reservation.releaseId;
497
- if (reservation.delayMs > 0) {
498
- emitter.emit(`throttle: waiting ${Math.ceil(reservation.delayMs / 1000)}s for TPM window…`);
499
- // Abortable — wall-clock timeout (T19) must beat throttle delay.
500
- await abortableSleep(reservation.delayMs, abortSignal);
501
- }
502
- };
503
- await reserveForDispatch();
483
+ const ctxPrep = await prepare();
504
484
  const userPrompt = expectEdits
505
485
  ? `${input.task}\n\nRespond with your rationale and OLD/NEW diff blocks per the system instruction.`
506
486
  : input.task;
@@ -537,7 +517,7 @@ async function executeCodeBody(input, ctx, workspaceRoot, started) {
537
517
  }
538
518
  const tierField = serviceTierConfig(serviceTier);
539
519
  const buildConfig = (cacheId) => {
540
- const maxOutputField = wireMaxOutputTokens !== undefined ? { maxOutputTokens: wireMaxOutputTokens } : {};
520
+ const maxOutputField = runCap.wire !== undefined ? { maxOutputTokens: runCap.wire } : {};
541
521
  if (canUseCache(cacheId) && cacheId) {
542
522
  // With cache: system_instruction is baked in; thinkingConfig remains OK.
543
523
  // `maxOutputTokens` only emitted when the caller set it explicitly
@@ -562,119 +542,32 @@ async function executeCodeBody(input, ctx, workspaceRoot, started) {
562
542
  const buildContents = (cacheId, inline) => canUseCache(cacheId)
563
543
  ? userPrompt
564
544
  : [...inline, { role: 'user', parts: [{ text: userPrompt }] }];
565
- let activePrep = ctxPrep;
566
- let retriedOnStaleCache = false;
567
- let response;
568
- try {
569
- // T20 (v1.7.0) — withNetworkRetry wraps ONLY the stream opening.
570
- // Mid-stream failures cannot be retried (Gemini's stream API has no
571
- // resume) — wrapping collectStream too would discard the partial
572
- // response and re-open a new stream → DOUBLE BILLING. See
573
- // ask.tool.ts for the full rationale.
574
- const stream = await withNetworkRetry(() => ctx.client.models.generateContentStream({
575
- model: resolved.resolved,
576
- contents: buildContents(activePrep.cacheId, activePrep.inlineContents),
577
- config: { ...buildConfig(activePrep.cacheId), abortSignal },
578
- }), {
579
- attempts: networkAttempts(serviceTier), // a flex request is never re-sent
580
- signal: abortSignal,
581
- onRetry: (attempt, retryErr) => {
582
- logger.warn(`code: retrying generateContent after transient network failure (attempt ${attempt}): ${retryErr instanceof Error ? retryErr.message : String(retryErr)}`);
583
- },
584
- });
585
- streamOpened = true;
586
- response = await collectStream(stream, {
587
- signal: abortSignal,
588
- onThoughtChunk: (text) => {
589
- const trimmed = text.trim().slice(0, 80);
590
- if (trimmed.length > 0)
591
- emitter.emit(`thinking: ${trimmed}…`);
592
- },
593
- // v1.12.0 — stall watchdog reset on every chunk.
594
- onChunkReceived: () => timeoutController.recordChunk(),
595
- });
596
- }
597
- catch (err) {
598
- if (activePrep.cacheId && isStaleCacheError(err)) {
599
- logger.warn(`Gemini rejected cached content ${activePrep.cacheId}; invalidating and retrying once.`);
600
- try {
601
- // Reset cache pointer only — preserve `files` rows so the rebuild
602
- // reuses uploaded files via content-hash dedup instead of double-
603
- // uploading. The Gemini-side cache is already dead.
604
- markCacheStale({ manifest: ctx.manifest, workspaceRoot });
605
- const rebuilt = await prepareContext({
606
- client: ctx.client,
607
- manifest: ctx.manifest,
608
- scan,
609
- model: resolved,
610
- systemPromptHash,
611
- systemInstruction: SYSTEM_INSTRUCTION_CODE,
612
- ttlSeconds: ctx.config.cacheTtlSeconds,
613
- cacheMinTokens: ctx.config.cacheMinTokens,
614
- emitter,
615
- allowCaching: scan.files.length > 0 && !codeExecution,
616
- // v1.12.1 — propagate signal into stale-cache rebuild too.
617
- signal: abortSignal,
618
- // v1.13.0 — keep cachingMode consistent across happy + retry paths.
619
- cachingMode: requestedCachingMode,
620
- });
621
- // Cancel stale reservation (tsMs was stamped before first
622
- // dispatch, now seconds old after rebuild) and re-reserve so
623
- // the retry's tsMs matches actual dispatch time. Mirror of
624
- // ask.tool.ts — see rationale there.
625
- if (throttleReservationId !== -1) {
626
- ctx.throttle.cancel(throttleReservationId);
627
- throttleReservationId = -1;
628
- }
629
- await reserveForDispatch();
630
- // The stale-cache retry itself can hit a transient network failure;
631
- // wrap it too so the rebuild isn't wasted on a one-off blip.
632
- // Stale-cache retry — discard partial, open fresh stream. Same
633
- // retry-OPENING-only contract as the happy path above.
634
- const retryStream = await withNetworkRetry(() => ctx.client.models.generateContentStream({
635
- model: resolved.resolved,
636
- contents: buildContents(rebuilt.cacheId, rebuilt.inlineContents),
637
- config: { ...buildConfig(rebuilt.cacheId), abortSignal },
638
- }), {
639
- attempts: networkAttempts(serviceTier),
640
- signal: abortSignal,
641
- onRetry: (attempt, retryErr) => {
642
- logger.warn(`code (stale-cache retry): retrying generateContent after transient network failure (attempt ${attempt}): ${retryErr instanceof Error ? retryErr.message : String(retryErr)}`);
643
- },
644
- });
645
- streamOpened = true;
646
- response = await collectStream(retryStream, {
647
- signal: abortSignal,
648
- onThoughtChunk: (text) => {
649
- const trimmed = text.trim().slice(0, 80);
650
- if (trimmed.length > 0)
651
- emitter.emit(`thinking: ${trimmed}…`);
652
- },
653
- // v1.12.0 — stall watchdog reset on retry stream.
654
- onChunkReceived: () => timeoutController.recordChunk(),
655
- });
656
- activePrep = rebuilt;
657
- retriedOnStaleCache = true;
658
- }
659
- catch (retryErr) {
660
- // Re-throw timeout directly so the outer catch's `isTimeoutAbort`
661
- // sees it. Wrapping with `cause: err` (the original stale-cache
662
- // error) would mask the timeout; outer catch would map to UNKNOWN
663
- // instead of TIMEOUT.
664
- if (isTimeoutAbort(retryErr))
665
- throw retryErr;
666
- if (statusOf(retryErr) !== undefined)
667
- throw retryErr; // an HTTP error on the retry is the error itself
668
- throw new Error(`code retry after stale cache failed: ${retryErr instanceof Error ? retryErr.message : String(retryErr)}`, { cause: err });
669
- }
670
- }
671
- else {
672
- throw err;
673
- }
674
- }
675
- if (activePrep.cacheId) {
676
- ctx.ttlWatcher.markHot(workspaceRoot, activePrep.cacheId, ctx.config.cacheTtlSeconds);
677
- }
545
+ // The decode and its one stale-cache retry — the shared path of `ask` and `code` (see ask.tool.ts).
546
+ const decoded = await decodeOnContext({
547
+ client: ctx.client,
548
+ booking: { workspaceRoot, toolName: 'code', model: resolved.resolved, serviceTier },
549
+ // `cachingRan`: a codeExecution call is forced inline and never builds a cache.
550
+ cachingMode: (prep) => cachingRan(prep, caching).mode,
551
+ request: (prep) => ({
552
+ contents: buildContents(prep.cacheId, prep.inlineContents),
553
+ config: buildConfig(prep.cacheId),
554
+ }),
555
+ cache: {
556
+ ttlWatcher: ctx.ttlWatcher,
557
+ manifest: ctx.manifest,
558
+ ttlSeconds: ctx.config.cacheTtlSeconds,
559
+ prepare,
560
+ },
561
+ openAttempts: networkAttempts(serviceTier), // a flex request is never re-sent
562
+ limits: { maxRequests: runCap.maxRequests, cap: runCap.effective },
563
+ timeout: timeoutController,
564
+ emit: (message) => emitter.emit(message),
565
+ completed,
566
+ tracking,
567
+ throttle: dispatch,
568
+ inputTokens: { estimated: estimatedInputTokens, counted: preflight?.effectiveTokens },
569
+ }, ctxPrep);
570
+ const { response, prep: activePrep, retriedOnStaleCache } = decoded;
678
571
  const text = response.text;
679
572
  const edits = expectEdits ? parseEdits(text) : [];
680
573
  const codeBlocks = parseCodeBlocks(text);
@@ -696,70 +589,40 @@ async function executeCodeBody(input, ctx, workspaceRoot, started) {
696
589
  }
697
590
  }
698
591
  const thinkingSummary = response.thoughtsSummary;
699
- const usage = response.usageMetadata;
700
- const cached = typeof usage?.cachedContentTokenCount === 'number' ? usage.cachedContentTokenCount : 0;
701
- const inputTotal = typeof usage?.promptTokenCount === 'number' ? usage.promptTokenCount : 0;
702
- const uncached = Math.max(0, inputTotal - cached);
703
- const output = typeof usage?.candidatesTokenCount === 'number' ? usage.candidatesTokenCount : 0;
704
- const thinking = typeof usage?.thoughtsTokenCount === 'number' ? usage.thoughtsTokenCount : 0;
705
- // Finalise TPM throttle reservation with actual input tokens
706
- // (cached + uncached — both count toward Gemini's per-minute quota).
707
- if (throttleReservationId !== -1) {
708
- ctx.throttle.release(throttleReservationId, inputTotal);
709
- throttleReservationId = -1;
710
- }
711
- const cost = estimateCostUsd({
712
- model: resolved.resolved,
713
- serviceTier,
714
- uncachedInputTokens: uncached,
715
- cachedInputTokens: cached,
716
- outputTokens: output,
717
- thinkingTokens: thinking,
718
- });
719
- const costMicros = toMicrosUsd(cost);
720
592
  // Telemetry and the response record the mode that ran, not the one asked for
721
593
  // (`cachingRan`: a codeExecution call is forced inline and never builds a cache).
722
594
  const ran = cachingRan(activePrep, caching);
723
595
  const effectiveCachingMode = ran.mode;
724
596
  const durationMs = Date.now() - started;
725
- if (reservationId !== null) {
726
- // Defensive: if `finalize` throws (disk full / lock contention), keep
727
- // the reservation row so we don't lose all record of this billable
728
- // call. Drop `reservationId` either way so the outer catch doesn't
729
- // touch it.
730
- try {
731
- ctx.manifest.finalizeBudgetReservation(reservationId, {
732
- cachedTokens: cached,
733
- uncachedTokens: uncached,
734
- costUsdMicro: costMicros,
735
- durationMs,
736
- cachingMode: effectiveCachingMode,
737
- cachedContentTokenCount: cached,
738
- });
739
- }
740
- catch (finalizeErr) {
741
- logger.error(`code: finalizeBudgetReservation failed for id=${reservationId}; reservation row keeps the estimate (${costMicros} micros). Error: ${String(finalizeErr)}`);
742
- }
743
- reservationId = null;
744
- }
745
- else {
746
- ctx.manifest.insertUsageMetric({
597
+ // Settled here, once: the outer catch then neither releases the reservation nor books the call again. What the
598
+ // API billed is every request that completed, over a long decode and a stale-cache retry alike.
599
+ const settledReservation = reservationId;
600
+ reservationId = null;
601
+ tracking.ledgerEntry = null;
602
+ const settled = settleAnswer({
603
+ manifest: ctx.manifest,
604
+ reservationId: settledReservation,
605
+ entry: {
747
606
  workspaceRoot,
748
607
  toolName: 'code',
749
608
  model: resolved.resolved,
750
- cachedTokens: cached,
751
- uncachedTokens: uncached,
752
- costUsdMicro: costMicros,
753
- durationMs,
754
- occurredAt: Date.now(),
609
+ serviceTier,
755
610
  cachingMode: effectiveCachingMode,
756
- cachedContentTokenCount: cached,
611
+ },
612
+ completed,
613
+ response,
614
+ cap: runCap,
615
+ cut: inputWindowCut,
616
+ durationMs,
617
+ });
618
+ const finish = settled.finish;
619
+ // Settled and billed above; an empty answer at the cap is a failure the caller can act on, never a success.
620
+ if (settled.outputCapStop !== null) {
621
+ return errorResult(`code: ${settled.outputCapStop.message}`, {
622
+ ...modelAudit,
623
+ ...settled.outputCapStop.fields,
757
624
  });
758
625
  }
759
- // Settled and billed above; an empty answer at the cap is a failure the caller can act on, never a success.
760
- const starved = emptyAtOutputCap(response, thinking);
761
- if (starved !== null)
762
- return errorResult(`code: ${starved}`);
763
626
  if (scan.truncated) {
764
627
  logger.warn(`workspace ${workspaceRoot} contains more files than GEMINI_CODE_CONTEXT_MAX_FILES (${ctx.config.maxFilesPerWorkspace}); the tail was dropped before indexing.`);
765
628
  }
@@ -782,11 +645,11 @@ async function executeCodeBody(input, ctx, workspaceRoot, started) {
782
645
  cacheHit: activePrep.reused,
783
646
  cacheRebuilt: activePrep.rebuilt || retriedOnStaleCache,
784
647
  retriedOnStaleCache,
785
- cachedTokens: cached,
786
- uncachedTokens: uncached,
787
- thinkingTokens: thinking,
788
- outputTokens: output,
789
- costEstimateUsd: Math.round(cost * 10000) / 10000,
648
+ ...settled.usage,
649
+ ...settled.cutFields,
650
+ // `truncated`: the answer stopped at the output cap (MAX_TOKENS, or a long decode at its limits) — it is cut
651
+ finishReason: finish.finishReason,
652
+ truncated: finish.truncated,
790
653
  durationMs,
791
654
  edits: edits.map((e) => ({
792
655
  file: e.file,
@@ -821,32 +684,27 @@ async function executeCodeBody(input, ctx, workspaceRoot, started) {
821
684
  ...(executedCode.length > 0 ? { executedCode } : {}),
822
685
  ...(executionOutput.length > 0 ? { executionOutput } : {}),
823
686
  };
824
- return textResult(text, structured);
687
+ return textResult(finish.truncated ? `${truncatedNote(expectEdits)}\n\n${text}` : text, structured);
825
688
  }
826
689
  catch (err) {
827
690
  logger.error(`code failed: ${safeForLog(err)}`);
828
- // T22a + v1.3.2 — seed the throttle's retry-hint from Gemini 429
829
- // bodies, gated on `isGemini429` (ApiError instance + status===429)
830
- // to prevent hint-poisoning. Mirror of ask.tool.ts — see there for
831
- // full rationale.
832
- const retryDelayMs = isGemini429(err) ? parseRetryDelayMs(err.message) : null;
833
- if (retryDelayMs !== null && resolvedModelKey !== null) {
834
- ctx.throttle.recordRetryHint(resolvedModelKey, retryDelayMs);
835
- }
836
- if (reservationId !== null) {
837
- try {
838
- ctx.manifest.cancelBudgetReservation(reservationId);
839
- }
840
- catch (cancelErr) {
841
- logger.error(`code: cancelBudgetReservation failed for id=${reservationId}; reservation row keeps the estimate. Error: ${String(cancelErr)}`);
842
- }
843
- reservationId = null;
844
- }
845
- // Drop TPM reservation on failure — mirror of ask.tool.ts rationale.
846
- if (throttleReservationId !== -1) {
847
- ctx.throttle.cancel(throttleReservationId);
848
- throttleReservationId = -1;
849
- }
691
+ // A 429's retry hint seeds the throttle; the ledger keeps what the completed requests billed and releases the rest
692
+ // (all of it when none completed).
693
+ const failedUsage = settleFailure({
694
+ manifest: ctx.manifest,
695
+ failed: {
696
+ toolName: 'code',
697
+ reservationId,
698
+ entry: tracking.ledgerEntry,
699
+ completed,
700
+ durationMs: Date.now() - started,
701
+ },
702
+ err,
703
+ model: resolvedModelKey,
704
+ throttle: ctx.throttle,
705
+ dispatch,
706
+ });
707
+ reservationId = null;
850
708
  // v1.12.0 — `timeoutKind` distinguishes wall-clock cap from stall watchdog.
851
709
  if (isTimeoutAbort(err)) {
852
710
  const ms = timeoutController.timeoutMs;
@@ -864,14 +722,16 @@ async function executeCodeBody(input, ctx, workspaceRoot, started) {
864
722
  stallMs,
865
723
  retryable: true,
866
724
  ...modelAudit,
725
+ ...failedUsage,
867
726
  });
868
727
  }
869
728
  const httpStatus = statusOf(err);
870
729
  return errorResult(`code failed: ${err instanceof Error ? err.message : String(err)}`, {
871
- ...tierErrorMeta(err, streamOpened),
730
+ ...tierErrorMeta(err, tracking.streamOpened),
872
731
  ...(httpStatus !== undefined ? { httpStatus } : {}),
873
732
  serviceTier: input.serviceTier ?? ctx.config.serviceTier, // before the model is resolved: the requested tier
874
733
  ...modelAudit,
734
+ ...failedUsage,
875
735
  });
876
736
  }
877
737
  finally {