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

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