@qmediat.io/gemini-code-context-mcp 1.4.1 → 1.5.1

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 (45) hide show
  1. package/CHANGELOG.md +100 -0
  2. package/README.md +26 -3
  3. package/dist/config.d.ts +23 -0
  4. package/dist/config.d.ts.map +1 -1
  5. package/dist/config.js +9 -0
  6. package/dist/config.js.map +1 -1
  7. package/dist/gemini/client.d.ts.map +1 -1
  8. package/dist/gemini/client.js +11 -0
  9. package/dist/gemini/client.js.map +1 -1
  10. package/dist/gemini/retry.d.ts +63 -0
  11. package/dist/gemini/retry.d.ts.map +1 -0
  12. package/dist/gemini/retry.js +103 -0
  13. package/dist/gemini/retry.js.map +1 -0
  14. package/dist/indexer/globs.d.ts +106 -0
  15. package/dist/indexer/globs.d.ts.map +1 -1
  16. package/dist/indexer/globs.js +151 -11
  17. package/dist/indexer/globs.js.map +1 -1
  18. package/dist/tools/agentic/sandbox.d.ts +55 -0
  19. package/dist/tools/agentic/sandbox.d.ts.map +1 -0
  20. package/dist/tools/agentic/sandbox.js +272 -0
  21. package/dist/tools/agentic/sandbox.js.map +1 -0
  22. package/dist/tools/agentic/workspace-tools.d.ts +104 -0
  23. package/dist/tools/agentic/workspace-tools.d.ts.map +1 -0
  24. package/dist/tools/agentic/workspace-tools.js +518 -0
  25. package/dist/tools/agentic/workspace-tools.js.map +1 -0
  26. package/dist/tools/ask-agentic.tool.d.ts +85 -0
  27. package/dist/tools/ask-agentic.tool.d.ts.map +1 -0
  28. package/dist/tools/ask-agentic.tool.js +739 -0
  29. package/dist/tools/ask-agentic.tool.js.map +1 -0
  30. package/dist/tools/ask.tool.d.ts +12 -12
  31. package/dist/tools/ask.tool.d.ts.map +1 -1
  32. package/dist/tools/ask.tool.js +537 -477
  33. package/dist/tools/ask.tool.js.map +1 -1
  34. package/dist/tools/code.tool.d.ts +8 -8
  35. package/dist/tools/code.tool.d.ts.map +1 -1
  36. package/dist/tools/code.tool.js +472 -423
  37. package/dist/tools/code.tool.js.map +1 -1
  38. package/dist/tools/index.d.ts.map +1 -1
  39. package/dist/tools/index.js +2 -0
  40. package/dist/tools/index.js.map +1 -1
  41. package/dist/tools/registry.d.ts +1 -1
  42. package/dist/tools/registry.d.ts.map +1 -1
  43. package/dist/tools/registry.js +8 -2
  44. package/dist/tools/registry.js.map +1 -1
  45. package/package.json +2 -2
@@ -10,6 +10,7 @@ import { resolve } from 'node:path';
10
10
  import { z } from 'zod';
11
11
  import { isStaleCacheError, markCacheStale, prepareContext } from '../cache/cache-manager.js';
12
12
  import { resolveModel } from '../gemini/models.js';
13
+ import { withNetworkRetry } from '../gemini/retry.js';
13
14
  import { scanWorkspace } from '../indexer/workspace-scanner.js';
14
15
  import { WorkspaceValidationError, validateWorkspacePath, } from '../indexer/workspace-validation.js';
15
16
  import { estimateCostUsd, estimatePreCallCostUsd, toMicrosUsd } from '../utils/cost-estimator.js';
@@ -60,7 +61,10 @@ export const askInputSchema = z
60
61
  .array(z.string())
61
62
  .optional()
62
63
  .describe('Additional file extensions or filenames to include.'),
63
- excludeGlobs: z.array(z.string()).optional().describe('Additional directory names to exclude.'),
64
+ excludeGlobs: z
65
+ .array(z.string())
66
+ .optional()
67
+ .describe('Additional patterns to exclude. Supports three shapes: (1) directory names or path prefixes (`node_modules`, `src/vendor`, `./dist/`, `.vercel/`), (2) literal filenames exact-match, including bare dot-prefixed names (`pr27-diff.txt`, `foo.bar.baz`, `.env`, `.map`, `.tsbuildinfo`), (3) extension globs that match via endsWith (`*.tsbuildinfo`, `*.map`). Bare dot-prefixed names like `.env` are treated as exact filename literals — write `*.env` for extension semantics. Paths are POSIX-normalised (backslashes → `/`, leading `./` and trailing `/` stripped). Case-insensitive. No mid-string `*` / `**` / `?` — split into dir + extension patterns if needed.'),
64
68
  noCache: z
65
69
  .boolean()
66
70
  .optional()
@@ -100,511 +104,567 @@ export const askTool = {
100
104
  const started = Date.now();
101
105
  const workspaceRoot = resolve(input.workspace ?? process.cwd());
102
106
  const model = input.model ?? ctx.config.defaultModel;
103
- let reservationId = null;
104
- // `-1` signals "no reservation held" (distinct from 0 which is a valid
105
- // releaseId). Mirrors the pattern used by `reservationId`.
106
- let throttleReservationId = -1;
107
- // Canonical resolved-model string, captured once after `resolveModel`
108
- // so the outer catch can feed retry hints into the same throttle bucket
109
- // `reserve` used. `model` at the top of execute is the request alias
110
- // ("latest-pro-thinking") — different key, different bucket.
111
- let resolvedModelKey = null;
112
- const emitter = createProgressEmitter(ctx.server, ctx.progressToken);
107
+ return executeAskBody(input, ctx, workspaceRoot, model, started);
108
+ },
109
+ };
110
+ async function executeAskBody(input, ctx, workspaceRoot, model, started) {
111
+ let reservationId = null;
112
+ // `-1` signals "no reservation held" (distinct from 0 which is a valid
113
+ // releaseId). Mirrors the pattern used by `reservationId`.
114
+ let throttleReservationId = -1;
115
+ // Canonical resolved-model string, captured once after `resolveModel`
116
+ // so the outer catch can feed retry hints into the same throttle bucket
117
+ // `reserve` used. `model` at the top of execute is the request alias
118
+ // ("latest-pro-thinking") — different key, different bucket.
119
+ let resolvedModelKey = null;
120
+ const emitter = createProgressEmitter(ctx.server, ctx.progressToken);
121
+ try {
122
+ // Workspace path validation lives INSIDE the try so a
123
+ // `WorkspaceValidationError` is reported as a regular tool error
124
+ // (errorResult, "ask failed: …") rather than an unhandled tool
125
+ // exception logged by the server-level handler. Both arrive at the
126
+ // user as text, but only the inside-try path keeps logs tidy and the
127
+ // user-facing prefix consistent with other validation failures.
113
128
  try {
114
- // Workspace path validation lives INSIDE the try so a
115
- // `WorkspaceValidationError` is reported as a regular tool error
116
- // (errorResult, "ask failed: …") rather than an unhandled tool
117
- // exception logged by the server-level handler. Both arrive at the
118
- // user as text, but only the inside-try path keeps logs tidy and the
119
- // user-facing prefix consistent with other validation failures.
120
- try {
121
- validateWorkspacePath(workspaceRoot);
122
- }
123
- catch (err) {
124
- if (err instanceof WorkspaceValidationError) {
125
- return errorResult(`ask: ${err.message}`);
126
- }
127
- throw err;
128
- }
129
- emitter.emit(`resolving model '${model}'…`);
130
- // `ask` accepts all three text-gen tiers — caller picks via alias
131
- // (`latest-pro` / `latest-flash` / `latest-lite` / `latest-vision`)
132
- // or literal model ID. Resolver refuses to dispatch to a category
133
- // outside this set — protects against an image/audio/agent model
134
- // slipping in (e.g. `nano-banana-pro-preview` pre-v1.4.0).
135
- const resolved = await resolveModel(model, ctx.client, {
136
- requiredCategory: ['text-reasoning', 'text-fast', 'text-lite'],
137
- });
138
- resolvedModelKey = resolved.resolved;
139
- emitter.emit(`scanning workspace ${workspaceRoot}…`);
140
- const scan = await scanWorkspace(workspaceRoot, {
141
- ...(input.includeGlobs !== undefined ? { includeGlobs: input.includeGlobs } : {}),
142
- ...(input.excludeGlobs !== undefined ? { excludeGlobs: input.excludeGlobs } : {}),
143
- maxFiles: ctx.config.maxFilesPerWorkspace,
144
- maxFileSizeBytes: ctx.config.maxFileSizeBytes,
145
- });
146
- // Output-cap strategy (v1.4.0): three-layer precedence.
147
- //
148
- // 1. `input.maxOutputTokens` (per-call, strongest) — user explicitly
149
- // caps this one call. Clamped to `modelOutputLimit`.
150
- // 2. `ctx.config.forceMaxOutputTokens` (env override) — when the
151
- // MCP host sets `GEMINI_CODE_CONTEXT_FORCE_MAX_OUTPUT=true`,
152
- // every call sends `maxOutputTokens = modelOutputLimit` so
153
- // code-review workloads always run at the model's full capacity
154
- // (65,536 tokens for Gemini 3.x / 2.5 Pro per Google docs).
155
- // 3. Default (no overrides) — omit `maxOutputTokens` from the
156
- // `generateContent` config. Gemini uses its model-default cap
157
- // (documented as the model's advertised `outputTokenLimit`),
158
- // letting the model size the response to the query's complexity
159
- // rather than reserving full capacity on short Q&A.
160
- //
161
- // `modelOutputLimit` is the model's advertised ceiling from
162
- // `models.list()` (or a fallback if the SDK doesn't report one).
163
- // Used as the clamp target and as the budget-reservation worst-case.
164
- const modelOutputLimit = typeof resolved.outputTokenLimit === 'number' && resolved.outputTokenLimit > 0
165
- ? resolved.outputTokenLimit
166
- : ASK_MAX_OUTPUT_TOKENS_FALLBACK;
167
- const wireMaxOutputTokens = input.maxOutputTokens !== undefined
168
- ? Math.min(input.maxOutputTokens, modelOutputLimit)
169
- : ctx.config.forceMaxOutputTokens
170
- ? modelOutputLimit
171
- : undefined;
172
- // Effective cap used for thinking-budget clamp and budget reservation.
173
- // When neither override is set, the model's internal default equals
174
- // `modelOutputLimit` per Google docs — so using the limit as
175
- // worst-case keeps `GEMINI_DAILY_BUDGET_USD` a true upper bound.
176
- const effectiveOutputCap = wireMaxOutputTokens ?? modelOutputLimit;
177
- // Single source of truth for "is the caller driving reasoning via the
178
- // discrete-tier knob?". Three downstream call sites branch on this
179
- // (cost estimate, emitter, thinkingConfig build) — extracting to a
180
- // named const keeps them in lockstep and makes future additions hard
181
- // to forget.
182
- const usingThinkingLevel = input.thinkingLevel !== undefined;
183
- // Gemini requires `thinkingBudget < maxOutputTokens` (the thinking pool
184
- // is carved out of the candidate-output allowance). Reject the call
185
- // early when the caller's `maxOutputTokens` leaves no headroom for a
186
- // positive `thinkingBudget`, rather than silently clamping to 0 —
187
- // clamp-to-0 would make Gemini 3 Pro 400 ("thinking disabled"
188
- // rejected) and mislead the caller about the actual cause (PR #22
189
- // round-3 review finding #C). Minimum answer reserve: 1024 tokens.
190
- if (input.thinkingBudget !== undefined &&
191
- input.thinkingBudget > 0 &&
192
- input.maxOutputTokens !== undefined &&
193
- effectiveOutputCap < input.thinkingBudget + 1024) {
194
- return errorResult(`ask: thinkingBudget (${input.thinkingBudget}) + 1024-token answer reserve exceeds maxOutputTokens (${effectiveOutputCap}). Raise \`maxOutputTokens\` to at least ${input.thinkingBudget + 1024}, or lower \`thinkingBudget\`.`);
129
+ validateWorkspacePath(workspaceRoot);
130
+ }
131
+ catch (err) {
132
+ if (err instanceof WorkspaceValidationError) {
133
+ return errorResult(`ask: ${err.message}`);
195
134
  }
196
- // Normalise thinkingBudget:
197
- // undefined → null (model-default path — `thinkingBudget` OMITTED on wire)
198
- // -1 → -1 (explicit legacy dynamic; kept for Gemini 2.5 and
199
- // power-users who want to force the legacy path)
200
- // 0 → 0 (thinking disabled; Gemini 3 Pro will 400 here)
201
- // N > 0 → clamp to [0, maxOutputTokens - 1024] — the thinking
202
- // pool is carved out of the candidate-output allowance,
203
- // so reserving ≥1024 tokens for the answer prevents 400s
204
- // when a caller passes N ≥ maxOutputTokens.
205
- //
206
- // Schema `.refine()` guarantees `thinkingBudget` and `thinkingLevel`
207
- // are never both set, so we handle them in two mutually-exclusive
208
- // branches below.
209
- const rawThinkingBudget = input.thinkingBudget;
210
- const effectiveThinkingBudget = rawThinkingBudget === undefined
211
- ? THINKING_BUDGET_MODEL_DEFAULT
212
- : rawThinkingBudget === -1
213
- ? -1
214
- : rawThinkingBudget > 0
215
- ? Math.max(0, Math.min(rawThinkingBudget, effectiveOutputCap - 1024))
216
- : 0;
217
- // Cost-estimate thinking-token reserve — tier-aware when the caller
218
- // uses `thinkingLevel`, worst-case when they use `thinkingBudget: -1`
219
- // or omit both fields (Gemini 3 Pro always spends thinking tokens per
220
- // Google's docs, so we reserve dynamic-thinking headroom there too).
221
- // When the caller passes an explicit positive `thinkingBudget`, we
222
- // reserve only that much. Keeps `GEMINI_DAILY_BUDGET_USD` a TRUE
223
- // upper bound on completed spend without false-rejecting callers
224
- // who legitimately use a low tier (see `THINKING_LEVEL_RESERVE`
225
- // rationale above).
226
- //
227
- // We dereference `input.thinkingLevel` directly (rather than via
228
- // `usingThinkingLevel`) so TypeScript narrows the type inside the
229
- // ternary — `THINKING_LEVEL_RESERVE[undefined]` would be a compile
230
- // error. The `?? worst-case` fallback handles the HIGH tier (which
231
- // maps to `null` in the reserve table to mean "use the dynamic cap").
232
- const thinkingTokensForEstimate = input.thinkingLevel !== undefined
233
- ? (THINKING_LEVEL_RESERVE[input.thinkingLevel] ?? Math.max(0, effectiveOutputCap - 1024))
234
- : effectiveThinkingBudget === null || effectiveThinkingBudget === -1
235
- ? Math.max(0, effectiveOutputCap - 1024)
236
- : effectiveThinkingBudget;
237
- // Estimated input-token count drives both the daily-budget reservation
238
- // (dollars) and the TPM throttle reservation (rate). Hoisted here so
239
- // both consumers share one fingerprint — no drift between what the $
240
- // ledger thinks we'll spend and what the rate-limiter thinks we'll
241
- // send to Gemini. Matches `estimatePreCallCostUsd`'s `Math.ceil(bytes/4)`
242
- // tokenisation on purpose; see `docs/FOLLOW-UP-PRS.md` T17 for the
243
- // known UTF-8 / CJK undercount.
244
- const workspaceBytes = scan.files.reduce((sum, f) => sum + f.size, 0);
245
- const estimatedInputTokens = Math.ceil(workspaceBytes / 4) + Math.ceil(input.prompt.length / 4);
246
- // Atomic budget reservation. Happens AFTER scan (so the estimate is
247
- // accurate) but BEFORE any billable upload or generateContent call.
248
- // Concurrent tool calls cannot all pass a pre-check and then
249
- // collectively overshoot the cap: `reserveBudget` uses a
250
- // `BEGIN IMMEDIATE` SQLite transaction that serialises check-and-insert.
251
- if (Number.isFinite(ctx.config.dailyBudgetUsd)) {
252
- const estimateUsd = estimatePreCallCostUsd({
253
- model: resolved.resolved,
254
- workspaceBytes,
255
- promptChars: input.prompt.length,
256
- // Budget reservation uses the effective cap (explicit-user-cap
257
- // OR model's full limit) as `expectedOutputTokens` — a TRUE
258
- // upper bound, since Gemini's default stops at the model's
259
- // advertised `outputTokenLimit`.
260
- expectedOutputTokens: effectiveOutputCap,
261
- thinkingTokens: thinkingTokensForEstimate,
262
- });
263
- const reserve = ctx.manifest.reserveBudget({
264
- workspaceRoot,
265
- toolName: 'ask',
266
- model: resolved.resolved,
267
- estimatedCostMicros: toMicrosUsd(estimateUsd),
268
- dailyBudgetMicros: toMicrosUsd(ctx.config.dailyBudgetUsd),
269
- nowMs: Date.now(),
135
+ throw err;
136
+ }
137
+ emitter.emit(`resolving model '${model}'…`);
138
+ // `ask` accepts all three text-gen tiers — caller picks via alias
139
+ // (`latest-pro` / `latest-flash` / `latest-lite` / `latest-vision`)
140
+ // or literal model ID. Resolver refuses to dispatch to a category
141
+ // outside this set — protects against an image/audio/agent model
142
+ // slipping in (e.g. `nano-banana-pro-preview` pre-v1.4.0).
143
+ const resolved = await resolveModel(model, ctx.client, {
144
+ requiredCategory: ['text-reasoning', 'text-fast', 'text-lite'],
145
+ });
146
+ resolvedModelKey = resolved.resolved;
147
+ emitter.emit(`scanning workspace ${workspaceRoot}…`);
148
+ const scan = await scanWorkspace(workspaceRoot, {
149
+ ...(input.includeGlobs !== undefined ? { includeGlobs: input.includeGlobs } : {}),
150
+ ...(input.excludeGlobs !== undefined ? { excludeGlobs: input.excludeGlobs } : {}),
151
+ maxFiles: ctx.config.maxFilesPerWorkspace,
152
+ maxFileSizeBytes: ctx.config.maxFileSizeBytes,
153
+ });
154
+ // Output-cap strategy (v1.4.0): three-layer precedence.
155
+ //
156
+ // 1. `input.maxOutputTokens` (per-call, strongest) — user explicitly
157
+ // caps this one call. Clamped to `modelOutputLimit`.
158
+ // 2. `ctx.config.forceMaxOutputTokens` (env override) — when the
159
+ // MCP host sets `GEMINI_CODE_CONTEXT_FORCE_MAX_OUTPUT=true`,
160
+ // every call sends `maxOutputTokens = modelOutputLimit` so
161
+ // code-review workloads always run at the model's full capacity
162
+ // (65,536 tokens for Gemini 3.x / 2.5 Pro per Google docs).
163
+ // 3. Default (no overrides) — omit `maxOutputTokens` from the
164
+ // `generateContent` config. Gemini uses its model-default cap
165
+ // (documented as the model's advertised `outputTokenLimit`),
166
+ // letting the model size the response to the query's complexity
167
+ // rather than reserving full capacity on short Q&A.
168
+ //
169
+ // `modelOutputLimit` is the model's advertised ceiling from
170
+ // `models.list()` (or a fallback if the SDK doesn't report one).
171
+ // Used as the clamp target and as the budget-reservation worst-case.
172
+ const modelOutputLimit = typeof resolved.outputTokenLimit === 'number' && resolved.outputTokenLimit > 0
173
+ ? resolved.outputTokenLimit
174
+ : ASK_MAX_OUTPUT_TOKENS_FALLBACK;
175
+ const wireMaxOutputTokens = input.maxOutputTokens !== undefined
176
+ ? Math.min(input.maxOutputTokens, modelOutputLimit)
177
+ : ctx.config.forceMaxOutputTokens
178
+ ? modelOutputLimit
179
+ : undefined;
180
+ // Effective cap used for thinking-budget clamp and budget reservation.
181
+ // When neither override is set, the model's internal default equals
182
+ // `modelOutputLimit` per Google docs — so using the limit as
183
+ // worst-case keeps `GEMINI_DAILY_BUDGET_USD` a true upper bound.
184
+ const effectiveOutputCap = wireMaxOutputTokens ?? modelOutputLimit;
185
+ // Single source of truth for "is the caller driving reasoning via the
186
+ // discrete-tier knob?". Three downstream call sites branch on this
187
+ // (cost estimate, emitter, thinkingConfig build) — extracting to a
188
+ // named const keeps them in lockstep and makes future additions hard
189
+ // to forget.
190
+ const usingThinkingLevel = input.thinkingLevel !== undefined;
191
+ // Gemini requires `thinkingBudget < maxOutputTokens` (the thinking pool
192
+ // is carved out of the candidate-output allowance). Reject the call
193
+ // early when the caller's `maxOutputTokens` leaves no headroom for a
194
+ // positive `thinkingBudget`, rather than silently clamping to 0 —
195
+ // clamp-to-0 would make Gemini 3 Pro 400 ("thinking disabled"
196
+ // rejected) and mislead the caller about the actual cause (PR #22
197
+ // round-3 review finding #C). Minimum answer reserve: 1024 tokens.
198
+ if (input.thinkingBudget !== undefined &&
199
+ input.thinkingBudget > 0 &&
200
+ input.maxOutputTokens !== undefined &&
201
+ effectiveOutputCap < input.thinkingBudget + 1024) {
202
+ return errorResult(`ask: thinkingBudget (${input.thinkingBudget}) + 1024-token answer reserve exceeds maxOutputTokens (${effectiveOutputCap}). Raise \`maxOutputTokens\` to at least ${input.thinkingBudget + 1024}, or lower \`thinkingBudget\`.`);
203
+ }
204
+ // Normalise thinkingBudget:
205
+ // undefined → null (model-default path — `thinkingBudget` OMITTED on wire)
206
+ // -1 → -1 (explicit legacy dynamic; kept for Gemini 2.5 and
207
+ // power-users who want to force the legacy path)
208
+ // 0 → 0 (thinking disabled; Gemini 3 Pro will 400 here)
209
+ // N > 0 → clamp to [0, maxOutputTokens - 1024] — the thinking
210
+ // pool is carved out of the candidate-output allowance,
211
+ // so reserving ≥1024 tokens for the answer prevents 400s
212
+ // when a caller passes N ≥ maxOutputTokens.
213
+ //
214
+ // Schema `.refine()` guarantees `thinkingBudget` and `thinkingLevel`
215
+ // are never both set, so we handle them in two mutually-exclusive
216
+ // branches below.
217
+ const rawThinkingBudget = input.thinkingBudget;
218
+ const effectiveThinkingBudget = rawThinkingBudget === undefined
219
+ ? THINKING_BUDGET_MODEL_DEFAULT
220
+ : rawThinkingBudget === -1
221
+ ? -1
222
+ : rawThinkingBudget > 0
223
+ ? Math.max(0, Math.min(rawThinkingBudget, effectiveOutputCap - 1024))
224
+ : 0;
225
+ // Cost-estimate thinking-token reserve — tier-aware when the caller
226
+ // uses `thinkingLevel`, worst-case when they use `thinkingBudget: -1`
227
+ // or omit both fields (Gemini 3 Pro always spends thinking tokens per
228
+ // Google's docs, so we reserve dynamic-thinking headroom there too).
229
+ // When the caller passes an explicit positive `thinkingBudget`, we
230
+ // reserve only that much. Keeps `GEMINI_DAILY_BUDGET_USD` a TRUE
231
+ // upper bound on completed spend without false-rejecting callers
232
+ // who legitimately use a low tier (see `THINKING_LEVEL_RESERVE`
233
+ // rationale above).
234
+ //
235
+ // We dereference `input.thinkingLevel` directly (rather than via
236
+ // `usingThinkingLevel`) so TypeScript narrows the type inside the
237
+ // ternary — `THINKING_LEVEL_RESERVE[undefined]` would be a compile
238
+ // error. The `?? worst-case` fallback handles the HIGH tier (which
239
+ // maps to `null` in the reserve table to mean "use the dynamic cap").
240
+ const thinkingTokensForEstimate = input.thinkingLevel !== undefined
241
+ ? (THINKING_LEVEL_RESERVE[input.thinkingLevel] ?? Math.max(0, effectiveOutputCap - 1024))
242
+ : effectiveThinkingBudget === null || effectiveThinkingBudget === -1
243
+ ? Math.max(0, effectiveOutputCap - 1024)
244
+ : effectiveThinkingBudget;
245
+ // Estimated input-token count drives both the daily-budget reservation
246
+ // (dollars) and the TPM throttle reservation (rate). Hoisted here so
247
+ // both consumers share one fingerprint — no drift between what the $
248
+ // ledger thinks we'll spend and what the rate-limiter thinks we'll
249
+ // send to Gemini. Matches `estimatePreCallCostUsd`'s `Math.ceil(bytes/4)`
250
+ // tokenisation on purpose; see `docs/FOLLOW-UP-PRS.md` T17 for the
251
+ // known UTF-8 / CJK undercount.
252
+ const workspaceBytes = scan.files.reduce((sum, f) => sum + f.size, 0);
253
+ const estimatedInputTokens = Math.ceil(workspaceBytes / 4) + Math.ceil(input.prompt.length / 4);
254
+ // v1.5.0 preflight — refuse immediately if the estimated input doesn't
255
+ // fit under the model's advertised `inputTokenLimit * workspaceGuardRatio`.
256
+ // Before this guard we would dispatch the request, Gemini would reject
257
+ // with `400 INVALID_ARGUMENT "exceeds maximum ..."`, and the calling
258
+ // sub-agent would interpret the 400 as retryable (the error body is
259
+ // indistinguishable from transient quota errors at the string level)
260
+ // → unbounded retry storm. Cheap pre-flight with a structured
261
+ // `WORKSPACE_TOO_LARGE` errorCode + `retryable: false` signals to the
262
+ // orchestrator that this is not recoverable without user action.
263
+ //
264
+ // `inputTokenLimit` can be `null` when `models.list()` didn't advertise
265
+ // it (typically happens only on internal / preview model IDs we've never
266
+ // seen). In that case we fall through without blocking but warn —
267
+ // better to let the request hit the API and fail noisily than to
268
+ // block a legitimate call on missing metadata.
269
+ const contextWindow = resolved.inputTokenLimit;
270
+ if (typeof contextWindow === 'number' && contextWindow > 0) {
271
+ const threshold = Math.floor(contextWindow * ctx.config.workspaceGuardRatio);
272
+ if (estimatedInputTokens > threshold) {
273
+ const pctDisplay = Math.round(ctx.config.workspaceGuardRatio * 100);
274
+ return errorResult(`Workspace too large: ~${estimatedInputTokens.toLocaleString()} input tokens exceeds ${threshold.toLocaleString()} (${pctDisplay}% of ${resolved.resolved}'s ${contextWindow.toLocaleString()} context window). Best option: use \`mcp__gemini-code-context__ask_agentic\` — same model, but it reads only the files it needs via sandboxed tool calls (no eager repo upload). Other options: (a) pass \`excludeGlobs\` to filter large/generated files — supports \`*.ext\` patterns, filenames, and directory paths, (b) narrow with \`includeGlobs\`, (c) switch to a larger-context model, or (d) split the workspace into subdirectories.`, {
275
+ errorCode: 'WORKSPACE_TOO_LARGE',
276
+ retryable: false,
277
+ estimatedInputTokens,
278
+ contextWindowTokens: contextWindow,
279
+ thresholdTokens: threshold,
280
+ guardRatio: ctx.config.workspaceGuardRatio,
281
+ resolvedModel: resolved.resolved,
282
+ filesIndexed: scan.files.length,
270
283
  });
271
- if ('rejected' in reserve) {
272
- const spentUsd = reserve.spentMicros / 1_000_000;
273
- return errorResult(`Daily budget cap would be exceeded: spent $${spentUsd.toFixed(4)} + estimate $${estimateUsd.toFixed(4)} > cap $${ctx.config.dailyBudgetUsd.toFixed(2)}. Retry after UTC midnight, or raise \`GEMINI_DAILY_BUDGET_USD\`.`);
274
- }
275
- reservationId = reserve.id;
276
284
  }
277
- const systemPromptHash = createHash('sha256')
278
- .update(SYSTEM_INSTRUCTION_Q_AND_A)
279
- .digest('hex')
280
- .slice(0, 16);
281
- const ctxPrep = await prepareContext({
282
- client: ctx.client,
283
- manifest: ctx.manifest,
284
- scan,
285
- model: resolved,
286
- systemPromptHash,
287
- systemInstruction: SYSTEM_INSTRUCTION_Q_AND_A,
288
- ttlSeconds: ctx.config.cacheTtlSeconds,
289
- cacheMinTokens: ctx.config.cacheMinTokens,
290
- emitter,
291
- allowCaching: !input.noCache && scan.files.length > 0,
285
+ }
286
+ else {
287
+ logger.warn(`ask: resolved model ${resolved.resolved} has no advertised inputTokenLimit — workspace size guard skipped. Request may fail downstream if the workspace exceeds the model's context window.`);
288
+ }
289
+ // Atomic budget reservation. Happens AFTER scan (so the estimate is
290
+ // accurate) but BEFORE any billable upload or generateContent call.
291
+ // Concurrent tool calls cannot all pass a pre-check and then
292
+ // collectively overshoot the cap: `reserveBudget` uses a
293
+ // `BEGIN IMMEDIATE` SQLite transaction that serialises check-and-insert.
294
+ if (Number.isFinite(ctx.config.dailyBudgetUsd)) {
295
+ const estimateUsd = estimatePreCallCostUsd({
296
+ model: resolved.resolved,
297
+ workspaceBytes,
298
+ promptChars: input.prompt.length,
299
+ // Budget reservation uses the effective cap (explicit-user-cap
300
+ // OR model's full limit) as `expectedOutputTokens` — a TRUE
301
+ // upper bound, since Gemini's default stops at the model's
302
+ // advertised `outputTokenLimit`.
303
+ expectedOutputTokens: effectiveOutputCap,
304
+ thinkingTokens: thinkingTokensForEstimate,
292
305
  });
293
- // TPM throttle reservation — placed HERE (after `prepareContext`,
294
- // immediately before `generateContent`) so the reservation's `tsMs`
295
- // accurately reflects when tokens hit Gemini's quota counter. An
296
- // earlier reserve (before `prepareContext`) would stamp `tsMs`
297
- // minutes before actual dispatch on cold-cache calls; our window
298
- // would then expire before Gemini's, leaving a gap where we admit
299
- // concurrent calls that bust Gemini's per-minute quota. Trade-off:
300
- // two concurrent cold-cache callers will both complete
301
- // `prepareContext` before one backs off at `reserve` — mostly
302
- // idempotent via file-hash dedup, minor upload duplication.
303
- //
304
- // Extracted into a helper so the stale-cache retry branch can
305
- // cancel-and-re-reserve with an accurate tsMs rather than reusing a
306
- // stale reservation stamped before the first (failed) dispatch.
307
- const reserveForDispatch = async () => {
308
- if (ctx.config.tpmThrottleLimit <= 0)
309
- return;
310
- const reservation = ctx.throttle.reserve(resolved.resolved, estimatedInputTokens);
311
- throttleReservationId = reservation.releaseId;
312
- if (reservation.delayMs > 0) {
313
- emitter.emit(`throttle: waiting ${Math.ceil(reservation.delayMs / 1000)}s for TPM window…`);
314
- await new Promise((resolveSleep) => setTimeout(resolveSleep, reservation.delayMs));
315
- }
316
- };
317
- await reserveForDispatch();
318
- emitter.emit(usingThinkingLevel
319
- ? `generating response (thinking-level=${input.thinkingLevel})…`
320
- : effectiveThinkingBudget === null
321
- ? 'generating response (thinking=model-default)…'
322
- : effectiveThinkingBudget === -1
323
- ? 'generating response (thinking=dynamic)…'
324
- : `generating response (thinking=${effectiveThinkingBudget})…`);
325
- // Gemini rejects `generateContent({cachedContent, systemInstruction})` with 400:
326
- // "CachedContent can not be used with GenerateContent request setting
327
- // system_instruction, tools or tool_config. Move those values to CachedContent."
328
- // The system instruction was already baked into the cache at build time
329
- // (see cache-manager.ts:322 `cacheConfig.systemInstruction`), so we must
330
- // OMIT it on the generate call when a cached context is active.
331
- // `thinkingConfig` is NOT one of the forbidden fields — it is a
332
- // per-request reasoning control and travels with every call regardless
333
- // of cache state. We always set `includeThoughts: true` so callers see
334
- // Gemini's reasoning digest in the response.
335
- //
336
- // Three mutually-exclusive reasoning-control paths (enforced by
337
- // schema `.refine()`):
338
- // a) `thinkingLevel` set → pass it through to the SDK enum. Google's
339
- // recommended path on Gemini 3. Rejected by Gemini 2.5 family.
340
- // b) `thinkingBudget` set (non-null after normalisation) → legacy
341
- // budget path. Required on Gemini 2.5; flagged as "legacy" on
342
- // Gemini 3 but still supported.
343
- // c) neither set → omit both fields, keep only `includeThoughts`.
344
- // Model uses its native default (HIGH-dynamic on Gemini 3 Pro).
345
- //
346
- // `maxOutputTokens` is only passed on the wire when the caller set
347
- // `input.maxOutputTokens` — otherwise we omit it and Gemini uses
348
- // its model-default cap (per docs, = the model's advertised
349
- // `outputTokenLimit`, currently 65,536 for pro-tier 3.x/2.5). Budget
350
- // reservation always uses `effectiveOutputCap` (= explicit cap OR
351
- // model limit) as worst-case upper bound, so the daily cap stays a
352
- // true ceiling regardless.
353
- // Cast to `ThinkingLevel` rather than indexing the runtime enum object
354
- // (`ThinkingLevel[input.thinkingLevel]`). For string enums the value
355
- // IS the member name, so passing `"HIGH"` as `ThinkingLevel` is
356
- // semantically identical at runtime — but it survives SDK renames:
357
- // if a future `@google/genai` release renames a member, the literal
358
- // string reaches Gemini's wire, which 400s with a clear message
359
- // instead of silently becoming `undefined` at the indexing step.
360
- const thinkingConfig = usingThinkingLevel
361
- ? {
362
- thinkingLevel: input.thinkingLevel,
363
- includeThoughts: true,
364
- }
365
- : effectiveThinkingBudget === null
366
- ? { includeThoughts: true }
367
- : { thinkingBudget: effectiveThinkingBudget, includeThoughts: true };
368
- const buildConfig = (cacheId) => {
369
- const maxOutputField = wireMaxOutputTokens !== undefined ? { maxOutputTokens: wireMaxOutputTokens } : {};
370
- return cacheId
371
- ? { cachedContent: cacheId, thinkingConfig, ...maxOutputField }
372
- : {
373
- systemInstruction: SYSTEM_INSTRUCTION_Q_AND_A,
374
- thinkingConfig,
375
- ...maxOutputField,
376
- };
377
- };
378
- const buildContents = (cacheId, inline) => cacheId ? input.prompt : [...inline, { role: 'user', parts: [{ text: input.prompt }] }];
379
- // Track the prepared-context used for the FINAL successful call. Starts
380
- // pointing at the initial ctxPrep; retry branch below reassigns to the
381
- // rebuilt PreparedContext so post-call markHot + metadata reflect reality.
382
- let activePrep = ctxPrep;
383
- let retriedOnStaleCache = false;
384
- let response;
385
- try {
386
- response = await ctx.client.models.generateContent({
387
- model: resolved.resolved,
388
- contents: buildContents(activePrep.cacheId, activePrep.inlineContents),
389
- config: buildConfig(activePrep.cacheId),
390
- });
391
- }
392
- catch (err) {
393
- // Self-heal: if Gemini rejected our cached content (evicted, expired,
394
- // externally deleted), invalidate locally and retry ONCE with a fresh
395
- // cache. Prevents users from seeing hard failures they'd otherwise need
396
- // to clear/reindex manually. Budget: one retry; a second stale-cache
397
- // error propagates with both errors chained via Error.cause.
398
- if (activePrep.cacheId && isStaleCacheError(err)) {
399
- logger.warn(`Gemini rejected cached content ${activePrep.cacheId}; invalidating and retrying once.`);
400
- try {
401
- // Reset the cache pointer only — keep `files` rows so the rebuild
402
- // can reuse uploaded files via content-hash dedup instead of
403
- // re-uploading. The Gemini-side cache is already dead (that's
404
- // what triggered this branch), so no `caches.delete` needed.
405
- markCacheStale({ manifest: ctx.manifest, workspaceRoot });
406
- const rebuilt = await prepareContext({
407
- client: ctx.client,
408
- manifest: ctx.manifest,
409
- scan,
410
- model: resolved,
411
- systemPromptHash,
412
- systemInstruction: SYSTEM_INSTRUCTION_Q_AND_A,
413
- ttlSeconds: ctx.config.cacheTtlSeconds,
414
- cacheMinTokens: ctx.config.cacheMinTokens,
415
- emitter,
416
- allowCaching: !input.noCache && scan.files.length > 0,
417
- });
418
- // Cancel the original throttle reservation — its `tsMs` was
419
- // stamped at first-dispatch time, which is now seconds in the
420
- // past (the rebuild took real time). Re-reserve fresh so the
421
- // retry's tsMs reflects when the retry call actually hits
422
- // Gemini's quota counter. Without this, our window would expire
423
- // locally before Gemini's, leaving a gap where concurrent
424
- // callers bust the per-minute limit (PR #19 round-2 GPT review).
425
- if (throttleReservationId !== -1) {
426
- ctx.throttle.cancel(throttleReservationId);
427
- throttleReservationId = -1;
428
- }
429
- await reserveForDispatch();
430
- response = await ctx.client.models.generateContent({
431
- model: resolved.resolved,
432
- contents: buildContents(rebuilt.cacheId, rebuilt.inlineContents),
433
- config: buildConfig(rebuilt.cacheId),
434
- });
435
- activePrep = rebuilt;
436
- retriedOnStaleCache = true;
437
- }
438
- catch (retryErr) {
439
- // Preserve the ORIGINAL stale-cache error as `cause` so ops can
440
- // root-cause diagnostics across both the first 404 and any
441
- // rebuild-time failure.
442
- throw new Error(`ask retry after stale cache failed: ${retryErr instanceof Error ? retryErr.message : String(retryErr)}`, { cause: err });
443
- }
444
- }
445
- else {
446
- throw err;
447
- }
448
- }
449
- if (activePrep.cacheId) {
450
- ctx.ttlWatcher.markHot(workspaceRoot, activePrep.cacheId, ctx.config.cacheTtlSeconds);
306
+ const reserve = ctx.manifest.reserveBudget({
307
+ workspaceRoot,
308
+ toolName: 'ask',
309
+ model: resolved.resolved,
310
+ estimatedCostMicros: toMicrosUsd(estimateUsd),
311
+ dailyBudgetMicros: toMicrosUsd(ctx.config.dailyBudgetUsd),
312
+ nowMs: Date.now(),
313
+ });
314
+ if ('rejected' in reserve) {
315
+ const spentUsd = reserve.spentMicros / 1_000_000;
316
+ return errorResult(`Daily budget cap would be exceeded: spent $${spentUsd.toFixed(4)} + estimate $${estimateUsd.toFixed(4)} > cap $${ctx.config.dailyBudgetUsd.toFixed(2)}. Retry after UTC midnight, or raise \`GEMINI_DAILY_BUDGET_USD\`.`, { errorCode: 'BUDGET_REJECT', retryable: false });
451
317
  }
452
- const text = response.text ?? '';
453
- // Extract Gemini's thinking summary when `includeThoughts: true` is set.
454
- // Parts flagged `thought: true` carry the model's internal reasoning
455
- // digest — useful for the caller to see *why* an answer was given.
456
- // We cap the joined summary at 1200 chars so it never dominates the
457
- // MCP response payload (matches `code.tool.ts` behaviour).
458
- const thoughtTexts = [];
459
- for (const cand of response.candidates ?? []) {
460
- for (const part of cand.content?.parts ?? []) {
461
- if (part.thought === true && typeof part.text === 'string') {
462
- thoughtTexts.push(part.text);
463
- }
464
- }
318
+ reservationId = reserve.id;
319
+ }
320
+ const systemPromptHash = createHash('sha256')
321
+ .update(SYSTEM_INSTRUCTION_Q_AND_A)
322
+ .digest('hex')
323
+ .slice(0, 16);
324
+ const ctxPrep = await prepareContext({
325
+ client: ctx.client,
326
+ manifest: ctx.manifest,
327
+ scan,
328
+ model: resolved,
329
+ systemPromptHash,
330
+ systemInstruction: SYSTEM_INSTRUCTION_Q_AND_A,
331
+ ttlSeconds: ctx.config.cacheTtlSeconds,
332
+ cacheMinTokens: ctx.config.cacheMinTokens,
333
+ emitter,
334
+ allowCaching: !input.noCache && scan.files.length > 0,
335
+ });
336
+ // TPM throttle reservation — placed HERE (after `prepareContext`,
337
+ // immediately before `generateContent`) so the reservation's `tsMs`
338
+ // accurately reflects when tokens hit Gemini's quota counter. An
339
+ // earlier reserve (before `prepareContext`) would stamp `tsMs`
340
+ // minutes before actual dispatch on cold-cache calls; our window
341
+ // would then expire before Gemini's, leaving a gap where we admit
342
+ // concurrent calls that bust Gemini's per-minute quota. Trade-off:
343
+ // two concurrent cold-cache callers will both complete
344
+ // `prepareContext` before one backs off at `reserve` — mostly
345
+ // idempotent via file-hash dedup, minor upload duplication.
346
+ //
347
+ // Extracted into a helper so the stale-cache retry branch can
348
+ // cancel-and-re-reserve with an accurate tsMs rather than reusing a
349
+ // stale reservation stamped before the first (failed) dispatch.
350
+ const reserveForDispatch = async () => {
351
+ if (ctx.config.tpmThrottleLimit <= 0)
352
+ return;
353
+ const reservation = ctx.throttle.reserve(resolved.resolved, estimatedInputTokens);
354
+ throttleReservationId = reservation.releaseId;
355
+ if (reservation.delayMs > 0) {
356
+ emitter.emit(`throttle: waiting ${Math.ceil(reservation.delayMs / 1000)}s for TPM window…`);
357
+ await new Promise((resolveSleep) => setTimeout(resolveSleep, reservation.delayMs));
465
358
  }
466
- const thinkingSummary = thoughtTexts.length > 0 ? thoughtTexts.join('\n').slice(0, 1200) : null;
467
- const usage = response.usageMetadata;
468
- const cached = typeof usage?.cachedContentTokenCount === 'number' ? usage.cachedContentTokenCount : 0;
469
- const inputTotal = typeof usage?.promptTokenCount === 'number' ? usage.promptTokenCount : 0;
470
- const uncached = Math.max(0, inputTotal - cached);
471
- const output = typeof usage?.candidatesTokenCount === 'number' ? usage.candidatesTokenCount : 0;
472
- const thinking = typeof usage?.thoughtsTokenCount === 'number' ? usage.thoughtsTokenCount : 0;
473
- // Finalise the throttle reservation with Gemini's actual
474
- // `promptTokenCount` — includes cached tokens, which DO count against
475
- // the per-minute quota (empirically confirmed 2026-04-20). If actual
476
- // < estimate, subsequent reserves see the freed headroom; if >, they
477
- // back off accordingly.
478
- if (throttleReservationId !== -1) {
479
- ctx.throttle.release(throttleReservationId, inputTotal);
480
- throttleReservationId = -1;
359
+ };
360
+ await reserveForDispatch();
361
+ emitter.emit(usingThinkingLevel
362
+ ? `generating response (thinking-level=${input.thinkingLevel})…`
363
+ : effectiveThinkingBudget === null
364
+ ? 'generating response (thinking=model-default)…'
365
+ : effectiveThinkingBudget === -1
366
+ ? 'generating response (thinking=dynamic)…'
367
+ : `generating response (thinking=${effectiveThinkingBudget})…`);
368
+ // Gemini rejects `generateContent({cachedContent, systemInstruction})` with 400:
369
+ // "CachedContent can not be used with GenerateContent request setting
370
+ // system_instruction, tools or tool_config. Move those values to CachedContent."
371
+ // The system instruction was already baked into the cache at build time
372
+ // (see cache-manager.ts:322 `cacheConfig.systemInstruction`), so we must
373
+ // OMIT it on the generate call when a cached context is active.
374
+ // `thinkingConfig` is NOT one of the forbidden fields — it is a
375
+ // per-request reasoning control and travels with every call regardless
376
+ // of cache state. We always set `includeThoughts: true` so callers see
377
+ // Gemini's reasoning digest in the response.
378
+ //
379
+ // Three mutually-exclusive reasoning-control paths (enforced by
380
+ // schema `.refine()`):
381
+ // a) `thinkingLevel` set → pass it through to the SDK enum. Google's
382
+ // recommended path on Gemini 3. Rejected by Gemini 2.5 family.
383
+ // b) `thinkingBudget` set (non-null after normalisation) → legacy
384
+ // budget path. Required on Gemini 2.5; flagged as "legacy" on
385
+ // Gemini 3 but still supported.
386
+ // c) neither set → omit both fields, keep only `includeThoughts`.
387
+ // Model uses its native default (HIGH-dynamic on Gemini 3 Pro).
388
+ //
389
+ // `maxOutputTokens` is only passed on the wire when the caller set
390
+ // `input.maxOutputTokens` — otherwise we omit it and Gemini uses
391
+ // its model-default cap (per docs, = the model's advertised
392
+ // `outputTokenLimit`, currently 65,536 for pro-tier 3.x/2.5). Budget
393
+ // reservation always uses `effectiveOutputCap` (= explicit cap OR
394
+ // model limit) as worst-case upper bound, so the daily cap stays a
395
+ // true ceiling regardless.
396
+ // Cast to `ThinkingLevel` rather than indexing the runtime enum object
397
+ // (`ThinkingLevel[input.thinkingLevel]`). For string enums the value
398
+ // IS the member name, so passing `"HIGH"` as `ThinkingLevel` is
399
+ // semantically identical at runtime — but it survives SDK renames:
400
+ // if a future `@google/genai` release renames a member, the literal
401
+ // string reaches Gemini's wire, which 400s with a clear message
402
+ // instead of silently becoming `undefined` at the indexing step.
403
+ const thinkingConfig = usingThinkingLevel
404
+ ? {
405
+ thinkingLevel: input.thinkingLevel,
406
+ includeThoughts: true,
481
407
  }
482
- const cost = estimateCostUsd({
408
+ : effectiveThinkingBudget === null
409
+ ? { includeThoughts: true }
410
+ : { thinkingBudget: effectiveThinkingBudget, includeThoughts: true };
411
+ const buildConfig = (cacheId) => {
412
+ const maxOutputField = wireMaxOutputTokens !== undefined ? { maxOutputTokens: wireMaxOutputTokens } : {};
413
+ return cacheId
414
+ ? { cachedContent: cacheId, thinkingConfig, ...maxOutputField }
415
+ : {
416
+ systemInstruction: SYSTEM_INSTRUCTION_Q_AND_A,
417
+ thinkingConfig,
418
+ ...maxOutputField,
419
+ };
420
+ };
421
+ const buildContents = (cacheId, inline) => cacheId ? input.prompt : [...inline, { role: 'user', parts: [{ text: input.prompt }] }];
422
+ // Track the prepared-context used for the FINAL successful call. Starts
423
+ // pointing at the initial ctxPrep; retry branch below reassigns to the
424
+ // rebuilt PreparedContext so post-call markHot + metadata reflect reality.
425
+ let activePrep = ctxPrep;
426
+ let retriedOnStaleCache = false;
427
+ let response;
428
+ try {
429
+ // `withNetworkRetry` covers pre-response transient failures
430
+ // (`TypeError: fetch failed`). See `src/gemini/retry.ts` for the full
431
+ // rationale; 429 rate-limits continue to be handled at the tool layer
432
+ // via `isGemini429` + `parseRetryDelayMs`.
433
+ response = await withNetworkRetry(() => ctx.client.models.generateContent({
483
434
  model: resolved.resolved,
484
- uncachedInputTokens: uncached,
485
- cachedInputTokens: cached,
486
- outputTokens: output,
487
- thinkingTokens: thinking,
435
+ contents: buildContents(activePrep.cacheId, activePrep.inlineContents),
436
+ config: buildConfig(activePrep.cacheId),
437
+ }), {
438
+ onRetry: (attempt, retryErr) => {
439
+ logger.warn(`ask: retrying generateContent after transient network failure (attempt ${attempt}): ${retryErr instanceof Error ? retryErr.message : String(retryErr)}`);
440
+ },
488
441
  });
489
- const costMicros = toMicrosUsd(cost);
490
- const durationMs = Date.now() - started;
491
- if (reservationId !== null) {
492
- // The finalize UPDATE on a row we just inserted should be infallible
493
- // in practice, but a disk-full / lock-contention edge could throw.
494
- // If it does, we'd rather keep the reservation row (estimate stays
495
- // billed, slight overcharge) than let the outer catch CANCEL it
496
- // — cancelling would erase any record of this billable, completed
497
- // call. Either way, drop `reservationId` so the outer catch doesn't
498
- // touch it.
442
+ }
443
+ catch (err) {
444
+ // Self-heal: if Gemini rejected our cached content (evicted, expired,
445
+ // externally deleted), invalidate locally and retry ONCE with a fresh
446
+ // cache. Prevents users from seeing hard failures they'd otherwise need
447
+ // to clear/reindex manually. Budget: one retry; a second stale-cache
448
+ // error propagates with both errors chained via Error.cause.
449
+ if (activePrep.cacheId && isStaleCacheError(err)) {
450
+ logger.warn(`Gemini rejected cached content ${activePrep.cacheId}; invalidating and retrying once.`);
499
451
  try {
500
- ctx.manifest.finalizeBudgetReservation(reservationId, {
501
- cachedTokens: cached,
502
- uncachedTokens: uncached,
503
- costUsdMicro: costMicros,
504
- durationMs,
452
+ // Reset the cache pointer only — keep `files` rows so the rebuild
453
+ // can reuse uploaded files via content-hash dedup instead of
454
+ // re-uploading. The Gemini-side cache is already dead (that's
455
+ // what triggered this branch), so no `caches.delete` needed.
456
+ markCacheStale({ manifest: ctx.manifest, workspaceRoot });
457
+ const rebuilt = await prepareContext({
458
+ client: ctx.client,
459
+ manifest: ctx.manifest,
460
+ scan,
461
+ model: resolved,
462
+ systemPromptHash,
463
+ systemInstruction: SYSTEM_INSTRUCTION_Q_AND_A,
464
+ ttlSeconds: ctx.config.cacheTtlSeconds,
465
+ cacheMinTokens: ctx.config.cacheMinTokens,
466
+ emitter,
467
+ allowCaching: !input.noCache && scan.files.length > 0,
505
468
  });
469
+ // Cancel the original throttle reservation — its `tsMs` was
470
+ // stamped at first-dispatch time, which is now seconds in the
471
+ // past (the rebuild took real time). Re-reserve fresh so the
472
+ // retry's tsMs reflects when the retry call actually hits
473
+ // Gemini's quota counter. Without this, our window would expire
474
+ // locally before Gemini's, leaving a gap where concurrent
475
+ // callers bust the per-minute limit (PR #19 round-2 GPT review).
476
+ if (throttleReservationId !== -1) {
477
+ ctx.throttle.cancel(throttleReservationId);
478
+ throttleReservationId = -1;
479
+ }
480
+ await reserveForDispatch();
481
+ // The stale-cache retry itself can hit a transient network failure;
482
+ // wrap it too so the rebuild isn't wasted on a one-off blip.
483
+ response = await withNetworkRetry(() => ctx.client.models.generateContent({
484
+ model: resolved.resolved,
485
+ contents: buildContents(rebuilt.cacheId, rebuilt.inlineContents),
486
+ config: buildConfig(rebuilt.cacheId),
487
+ }), {
488
+ onRetry: (attempt, retryErr) => {
489
+ logger.warn(`ask (stale-cache retry): retrying generateContent after transient network failure (attempt ${attempt}): ${retryErr instanceof Error ? retryErr.message : String(retryErr)}`);
490
+ },
491
+ });
492
+ activePrep = rebuilt;
493
+ retriedOnStaleCache = true;
506
494
  }
507
- catch (finalizeErr) {
508
- logger.error(`ask: finalizeBudgetReservation failed for id=${reservationId}; reservation row keeps the estimate (${costMicros} micros). Error: ${String(finalizeErr)}`);
495
+ catch (retryErr) {
496
+ // Preserve the ORIGINAL stale-cache error as `cause` so ops can
497
+ // root-cause diagnostics across both the first 404 and any
498
+ // rebuild-time failure.
499
+ throw new Error(`ask retry after stale cache failed: ${retryErr instanceof Error ? retryErr.message : String(retryErr)}`, { cause: err });
509
500
  }
510
- reservationId = null;
511
501
  }
512
502
  else {
513
- ctx.manifest.insertUsageMetric({
514
- workspaceRoot,
515
- toolName: 'ask',
516
- model: resolved.resolved,
503
+ throw err;
504
+ }
505
+ }
506
+ if (activePrep.cacheId) {
507
+ ctx.ttlWatcher.markHot(workspaceRoot, activePrep.cacheId, ctx.config.cacheTtlSeconds);
508
+ }
509
+ const text = response.text ?? '';
510
+ // Extract Gemini's thinking summary when `includeThoughts: true` is set.
511
+ // Parts flagged `thought: true` carry the model's internal reasoning
512
+ // digest — useful for the caller to see *why* an answer was given.
513
+ // We cap the joined summary at 1200 chars so it never dominates the
514
+ // MCP response payload (matches `code.tool.ts` behaviour).
515
+ const thoughtTexts = [];
516
+ for (const cand of response.candidates ?? []) {
517
+ for (const part of cand.content?.parts ?? []) {
518
+ if (part.thought === true && typeof part.text === 'string') {
519
+ thoughtTexts.push(part.text);
520
+ }
521
+ }
522
+ }
523
+ const thinkingSummary = thoughtTexts.length > 0 ? thoughtTexts.join('\n').slice(0, 1200) : null;
524
+ const usage = response.usageMetadata;
525
+ const cached = typeof usage?.cachedContentTokenCount === 'number' ? usage.cachedContentTokenCount : 0;
526
+ const inputTotal = typeof usage?.promptTokenCount === 'number' ? usage.promptTokenCount : 0;
527
+ const uncached = Math.max(0, inputTotal - cached);
528
+ const output = typeof usage?.candidatesTokenCount === 'number' ? usage.candidatesTokenCount : 0;
529
+ const thinking = typeof usage?.thoughtsTokenCount === 'number' ? usage.thoughtsTokenCount : 0;
530
+ // Finalise the throttle reservation with Gemini's actual
531
+ // `promptTokenCount` — includes cached tokens, which DO count against
532
+ // the per-minute quota (empirically confirmed 2026-04-20). If actual
533
+ // < estimate, subsequent reserves see the freed headroom; if >, they
534
+ // back off accordingly.
535
+ if (throttleReservationId !== -1) {
536
+ ctx.throttle.release(throttleReservationId, inputTotal);
537
+ throttleReservationId = -1;
538
+ }
539
+ const cost = estimateCostUsd({
540
+ model: resolved.resolved,
541
+ uncachedInputTokens: uncached,
542
+ cachedInputTokens: cached,
543
+ outputTokens: output,
544
+ thinkingTokens: thinking,
545
+ });
546
+ const costMicros = toMicrosUsd(cost);
547
+ const durationMs = Date.now() - started;
548
+ if (reservationId !== null) {
549
+ // The finalize UPDATE on a row we just inserted should be infallible
550
+ // in practice, but a disk-full / lock-contention edge could throw.
551
+ // If it does, we'd rather keep the reservation row (estimate stays
552
+ // billed, slight overcharge) than let the outer catch CANCEL it
553
+ // — cancelling would erase any record of this billable, completed
554
+ // call. Either way, drop `reservationId` so the outer catch doesn't
555
+ // touch it.
556
+ try {
557
+ ctx.manifest.finalizeBudgetReservation(reservationId, {
517
558
  cachedTokens: cached,
518
559
  uncachedTokens: uncached,
519
560
  costUsdMicro: costMicros,
520
561
  durationMs,
521
- occurredAt: Date.now(),
522
562
  });
523
563
  }
524
- if (scan.truncated) {
525
- logger.warn(`workspace ${workspaceRoot} contains more files than GEMINI_CODE_CONTEXT_MAX_FILES (${ctx.config.maxFilesPerWorkspace}); the tail was dropped before indexing.`);
564
+ catch (finalizeErr) {
565
+ logger.error(`ask: finalizeBudgetReservation failed for id=${reservationId}; reservation row keeps the estimate (${costMicros} micros). Error: ${String(finalizeErr)}`);
526
566
  }
527
- const metadata = {
528
- resolvedModel: resolved.resolved,
529
- requestedModel: resolved.requested,
530
- fallbackApplied: resolved.fallbackApplied,
531
- modelCategory: resolved.category,
532
- modelCostTier: resolved.capabilities.costTier,
533
- contextWindow: resolved.inputTokenLimit,
534
- thinkingBudget: effectiveThinkingBudget,
535
- thinkingLevel: input.thinkingLevel ?? null,
567
+ reservationId = null;
568
+ }
569
+ else {
570
+ ctx.manifest.insertUsageMetric({
571
+ workspaceRoot,
572
+ toolName: 'ask',
573
+ model: resolved.resolved,
536
574
  cachedTokens: cached,
537
575
  uncachedTokens: uncached,
538
- outputTokens: output,
539
- thinkingTokens: thinking,
540
- costEstimateUsd: Math.round(cost * 10000) / 10000,
541
- cacheHit: activePrep.reused,
542
- cacheRebuilt: activePrep.rebuilt || retriedOnStaleCache,
543
- retriedOnStaleCache,
544
- inlineOnly: activePrep.inlineOnly,
545
- filesIndexed: scan.files.length,
546
- filesSkippedTooLarge: scan.skippedTooLarge,
547
- filesUploadFailed: activePrep.uploaded.failedCount,
548
- ...(activePrep.uploaded.failedCount > 0
549
- ? { uploadFailures: activePrep.uploaded.failures.slice(0, 5) }
550
- : {}),
551
- workspaceTruncated: scan.truncated,
552
- maxFilesCap: ctx.config.maxFilesPerWorkspace,
576
+ costUsdMicro: costMicros,
553
577
  durationMs,
554
- ...(thinkingSummary ? { thinkingSummary } : {}),
555
- };
556
- return textResult(text, metadata);
578
+ occurredAt: Date.now(),
579
+ });
557
580
  }
558
- catch (err) {
559
- logger.error(`ask failed: ${String(err)}`);
560
- // T22a — extract Gemini's `retryInfo.retryDelay` from 429 bodies and
561
- // seed the throttle's per-model hint before we release the
562
- // reservation. Google's hint is typically shorter (2-16s) than our
563
- // pure-window math would compute (up to 60s+) so honouring it
564
- // shortens the next caller's wait.
565
- //
566
- // Gated on `isGemini429` BEFORE parsing. The predicate requires BOTH
567
- // `err instanceof ApiError` (SDK-provenance marker — user-controlled
568
- // content can't forge an ApiError prototype) AND `err.status === 429`
569
- // (typed field from the HTTP response). The earlier v1.3.2 draft had
570
- // a `RESOURCE_EXHAUSTED` substring fallback; GPT + Grok round-2
571
- // review (PR #21) showed that path was user-influenceable — echoed
572
- // prompt content re-opened the hint-poisoning class the gate was
573
- // meant to close. Removing the fallback drops hint extraction for
574
- // errors that lose the ApiError shape in transit, but production
575
- // 429s always arrive as real ApiError instances.
576
- const retryDelayMs = isGemini429(err) ? parseRetryDelayMs(err.message) : null;
577
- if (retryDelayMs !== null && resolvedModelKey !== null) {
578
- ctx.throttle.recordRetryHint(resolvedModelKey, retryDelayMs);
579
- }
580
- // Release any unconsumed budget reservation so the failed call's
581
- // estimate doesn't eat into future headroom for today. Wrap in its
582
- // own try/catch — better-sqlite3 can throw SQLITE_BUSY or I/O errors
583
- // and we must not let a rollback-time DB failure replace the real
584
- // tool error the user is waiting on.
585
- if (reservationId !== null) {
586
- try {
587
- ctx.manifest.cancelBudgetReservation(reservationId);
588
- }
589
- catch (cancelErr) {
590
- logger.error(`ask: cancelBudgetReservation failed for id=${reservationId}; reservation row keeps the estimate. Error: ${String(cancelErr)}`);
591
- }
592
- reservationId = null;
581
+ if (scan.truncated) {
582
+ logger.warn(`workspace ${workspaceRoot} contains more files than GEMINI_CODE_CONTEXT_MAX_FILES (${ctx.config.maxFilesPerWorkspace}); the tail was dropped before indexing.`);
583
+ }
584
+ const metadata = {
585
+ resolvedModel: resolved.resolved,
586
+ requestedModel: resolved.requested,
587
+ fallbackApplied: resolved.fallbackApplied,
588
+ modelCategory: resolved.category,
589
+ modelCostTier: resolved.capabilities.costTier,
590
+ contextWindow: resolved.inputTokenLimit,
591
+ thinkingBudget: effectiveThinkingBudget,
592
+ thinkingLevel: input.thinkingLevel ?? null,
593
+ cachedTokens: cached,
594
+ uncachedTokens: uncached,
595
+ outputTokens: output,
596
+ thinkingTokens: thinking,
597
+ costEstimateUsd: Math.round(cost * 10000) / 10000,
598
+ cacheHit: activePrep.reused,
599
+ cacheRebuilt: activePrep.rebuilt || retriedOnStaleCache,
600
+ retriedOnStaleCache,
601
+ inlineOnly: activePrep.inlineOnly,
602
+ filesIndexed: scan.files.length,
603
+ filesSkippedTooLarge: scan.skippedTooLarge,
604
+ filesUploadFailed: activePrep.uploaded.failedCount,
605
+ ...(activePrep.uploaded.failedCount > 0
606
+ ? { uploadFailures: activePrep.uploaded.failures.slice(0, 5) }
607
+ : {}),
608
+ workspaceTruncated: scan.truncated,
609
+ maxFilesCap: ctx.config.maxFilesPerWorkspace,
610
+ durationMs,
611
+ ...(thinkingSummary ? { thinkingSummary } : {}),
612
+ };
613
+ return textResult(text, metadata);
614
+ }
615
+ catch (err) {
616
+ logger.error(`ask failed: ${String(err)}`);
617
+ // T22a — extract Gemini's `retryInfo.retryDelay` from 429 bodies and
618
+ // seed the throttle's per-model hint before we release the
619
+ // reservation. Google's hint is typically shorter (2-16s) than our
620
+ // pure-window math would compute (up to 60s+) so honouring it
621
+ // shortens the next caller's wait.
622
+ //
623
+ // Gated on `isGemini429` BEFORE parsing. The predicate requires BOTH
624
+ // `err instanceof ApiError` (SDK-provenance marker — user-controlled
625
+ // content can't forge an ApiError prototype) AND `err.status === 429`
626
+ // (typed field from the HTTP response). The earlier v1.3.2 draft had
627
+ // a `RESOURCE_EXHAUSTED` substring fallback; GPT + Grok round-2
628
+ // review (PR #21) showed that path was user-influenceable — echoed
629
+ // prompt content re-opened the hint-poisoning class the gate was
630
+ // meant to close. Removing the fallback drops hint extraction for
631
+ // errors that lose the ApiError shape in transit, but production
632
+ // 429s always arrive as real ApiError instances.
633
+ const retryDelayMs = isGemini429(err) ? parseRetryDelayMs(err.message) : null;
634
+ if (retryDelayMs !== null && resolvedModelKey !== null) {
635
+ ctx.throttle.recordRetryHint(resolvedModelKey, retryDelayMs);
636
+ }
637
+ // Release any unconsumed budget reservation so the failed call's
638
+ // estimate doesn't eat into future headroom for today. Wrap in its
639
+ // own try/catch — better-sqlite3 can throw SQLITE_BUSY or I/O errors
640
+ // and we must not let a rollback-time DB failure replace the real
641
+ // tool error the user is waiting on.
642
+ if (reservationId !== null) {
643
+ try {
644
+ ctx.manifest.cancelBudgetReservation(reservationId);
593
645
  }
594
- // Drop the TPM reservation on any failure path. If Gemini actually
595
- // consumed quota server-side before failing, the hint path above
596
- // (T22a) compensates via `recordRetryHint` before we cancel. For
597
- // non-429 errors (validation, transport), we under-count slightly
598
- // but bounded — accepted trade-off documented in PR #19 round-2.
599
- if (throttleReservationId !== -1) {
600
- ctx.throttle.cancel(throttleReservationId);
601
- throttleReservationId = -1;
646
+ catch (cancelErr) {
647
+ logger.error(`ask: cancelBudgetReservation failed for id=${reservationId}; reservation row keeps the estimate. Error: ${String(cancelErr)}`);
602
648
  }
603
- return errorResult(`ask failed: ${err instanceof Error ? err.message : String(err)}`);
649
+ reservationId = null;
604
650
  }
605
- finally {
606
- emitter.stop();
651
+ // Drop the TPM reservation on any failure path. If Gemini actually
652
+ // consumed quota server-side before failing, the hint path above
653
+ // (T22a) compensates via `recordRetryHint` before we cancel. For
654
+ // non-429 errors (validation, transport), we under-count slightly
655
+ // but bounded — accepted trade-off documented in PR #19 round-2.
656
+ if (throttleReservationId !== -1) {
657
+ ctx.throttle.cancel(throttleReservationId);
658
+ throttleReservationId = -1;
607
659
  }
608
- },
609
- };
660
+ const httpStatus = err.status;
661
+ return errorResult(`ask failed: ${err instanceof Error ? err.message : String(err)}`, {
662
+ errorCode: 'UNKNOWN',
663
+ ...(httpStatus !== undefined ? { httpStatus } : {}),
664
+ });
665
+ }
666
+ finally {
667
+ emitter.stop();
668
+ }
669
+ }
610
670
  //# sourceMappingURL=ask.tool.js.map