@qmediat.io/gemini-code-context-mcp 1.24.0 → 1.25.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.
- package/CHANGELOG.md +110 -1
- package/README.md +1 -1
- package/dist/cache/cache-manager.d.ts +23 -34
- package/dist/cache/cache-manager.d.ts.map +1 -1
- package/dist/cache/cache-manager.js +324 -272
- package/dist/cache/cache-manager.js.map +1 -1
- package/dist/cache/caching-mode.d.ts +5 -3
- package/dist/cache/caching-mode.d.ts.map +1 -1
- package/dist/cache/caching-mode.js +6 -4
- package/dist/cache/caching-mode.js.map +1 -1
- package/dist/cache/ttl-watcher.d.ts.map +1 -1
- package/dist/cache/ttl-watcher.js +7 -1
- package/dist/cache/ttl-watcher.js.map +1 -1
- package/dist/cache/ttl.d.ts +8 -0
- package/dist/cache/ttl.d.ts.map +1 -0
- package/dist/cache/ttl.js +10 -0
- package/dist/cache/ttl.js.map +1 -0
- package/dist/manifest/db.d.ts.map +1 -1
- package/dist/manifest/db.js +2 -1
- package/dist/manifest/db.js.map +1 -1
- package/dist/tools/agentic/dispatch.d.ts +68 -0
- package/dist/tools/agentic/dispatch.d.ts.map +1 -0
- package/dist/tools/agentic/dispatch.js +167 -0
- package/dist/tools/agentic/dispatch.js.map +1 -0
- package/dist/tools/agentic/input.d.ts +28 -0
- package/dist/tools/agentic/input.d.ts.map +1 -0
- package/dist/tools/agentic/input.js +66 -0
- package/dist/tools/agentic/input.js.map +1 -0
- package/dist/tools/agentic/instructions.d.ts +46 -0
- package/dist/tools/agentic/instructions.d.ts.map +1 -0
- package/dist/tools/agentic/instructions.js +170 -0
- package/dist/tools/agentic/instructions.js.map +1 -0
- package/dist/tools/agentic/iteration.d.ts +81 -0
- package/dist/tools/agentic/iteration.d.ts.map +1 -0
- package/dist/tools/agentic/iteration.js +317 -0
- package/dist/tools/agentic/iteration.js.map +1 -0
- package/dist/tools/agentic/ledger.d.ts +64 -0
- package/dist/tools/agentic/ledger.d.ts.map +1 -0
- package/dist/tools/agentic/ledger.js +110 -0
- package/dist/tools/agentic/ledger.js.map +1 -0
- package/dist/tools/agentic/loop.d.ts +10 -0
- package/dist/tools/agentic/loop.d.ts.map +1 -0
- package/dist/tools/agentic/loop.js +179 -0
- package/dist/tools/agentic/loop.js.map +1 -0
- package/dist/tools/agentic/no-progress.d.ts +90 -0
- package/dist/tools/agentic/no-progress.d.ts.map +1 -0
- package/dist/tools/agentic/no-progress.js +107 -0
- package/dist/tools/agentic/no-progress.js.map +1 -0
- package/dist/tools/agentic/pass-clock.d.ts +85 -0
- package/dist/tools/agentic/pass-clock.d.ts.map +1 -0
- package/dist/tools/agentic/pass-clock.js +162 -0
- package/dist/tools/agentic/pass-clock.js.map +1 -0
- package/dist/tools/agentic/phase-defaults.d.ts +29 -0
- package/dist/tools/agentic/phase-defaults.d.ts.map +1 -0
- package/dist/tools/agentic/phase-defaults.js +23 -0
- package/dist/tools/agentic/phase-defaults.js.map +1 -0
- package/dist/tools/agentic/rescue.d.ts +69 -0
- package/dist/tools/agentic/rescue.d.ts.map +1 -0
- package/dist/tools/agentic/rescue.js +203 -0
- package/dist/tools/agentic/rescue.js.map +1 -0
- package/dist/tools/agentic/response.d.ts +16 -0
- package/dist/tools/agentic/response.d.ts.map +1 -0
- package/dist/tools/agentic/response.js +25 -0
- package/dist/tools/agentic/response.js.map +1 -0
- package/dist/tools/agentic/results.d.ts +76 -0
- package/dist/tools/agentic/results.d.ts.map +1 -0
- package/dist/tools/agentic/results.js +228 -0
- package/dist/tools/agentic/results.js.map +1 -0
- package/dist/tools/agentic/run.d.ts +130 -0
- package/dist/tools/agentic/run.d.ts.map +1 -0
- package/dist/tools/agentic/run.js +128 -0
- package/dist/tools/agentic/run.js.map +1 -0
- package/dist/tools/agentic/sandbox.d.ts +13 -2
- package/dist/tools/agentic/sandbox.d.ts.map +1 -1
- package/dist/tools/agentic/sandbox.js +127 -111
- package/dist/tools/agentic/sandbox.js.map +1 -1
- package/dist/tools/agentic/workspace-tools.d.ts +30 -27
- package/dist/tools/agentic/workspace-tools.d.ts.map +1 -1
- package/dist/tools/agentic/workspace-tools.js +324 -385
- package/dist/tools/agentic/workspace-tools.js.map +1 -1
- package/dist/tools/ask/answer.d.ts +9 -0
- package/dist/tools/ask/answer.d.ts.map +1 -0
- package/dist/tools/ask/answer.js +28 -0
- package/dist/tools/ask/answer.js.map +1 -0
- package/dist/tools/ask/attachments.d.ts +25 -0
- package/dist/tools/ask/attachments.d.ts.map +1 -0
- package/dist/tools/ask/attachments.js +85 -0
- package/dist/tools/ask/attachments.js.map +1 -0
- package/dist/tools/ask/call.d.ts +61 -0
- package/dist/tools/ask/call.d.ts.map +1 -0
- package/dist/tools/ask/call.js +6 -0
- package/dist/tools/ask/call.js.map +1 -0
- package/dist/tools/ask/guard.d.ts +24 -0
- package/dist/tools/ask/guard.d.ts.map +1 -0
- package/dist/tools/ask/guard.js +79 -0
- package/dist/tools/ask/guard.js.map +1 -0
- package/dist/tools/ask/input.d.ts +45 -0
- package/dist/tools/ask/input.d.ts.map +1 -0
- package/dist/tools/ask/input.js +93 -0
- package/dist/tools/ask/input.js.map +1 -0
- package/dist/tools/ask/instruction.d.ts +8 -0
- package/dist/tools/ask/instruction.d.ts.map +1 -0
- package/dist/tools/ask/instruction.js +13 -0
- package/dist/tools/ask/instruction.js.map +1 -0
- package/dist/tools/ask/request.d.ts +14 -0
- package/dist/tools/ask/request.d.ts.map +1 -0
- package/dist/tools/ask/request.js +38 -0
- package/dist/tools/ask/request.js.map +1 -0
- package/dist/tools/ask/results.d.ts +23 -0
- package/dist/tools/ask/results.d.ts.map +1 -0
- package/dist/tools/ask/results.js +107 -0
- package/dist/tools/ask/results.js.map +1 -0
- package/dist/tools/ask/setup.d.ts +22 -0
- package/dist/tools/ask/setup.d.ts.map +1 -0
- package/dist/tools/ask/setup.js +57 -0
- package/dist/tools/ask/setup.js.map +1 -0
- package/dist/tools/ask/sizing.d.ts +10 -0
- package/dist/tools/ask/sizing.d.ts.map +1 -0
- package/dist/tools/ask/sizing.js +33 -0
- package/dist/tools/ask/sizing.js.map +1 -0
- package/dist/tools/ask/thinking.d.ts +54 -0
- package/dist/tools/ask/thinking.d.ts.map +1 -0
- package/dist/tools/ask/thinking.js +69 -0
- package/dist/tools/ask/thinking.js.map +1 -0
- package/dist/tools/ask-agentic-fallback.d.ts +33 -0
- package/dist/tools/ask-agentic-fallback.d.ts.map +1 -0
- package/dist/tools/ask-agentic-fallback.js +113 -0
- package/dist/tools/ask-agentic-fallback.js.map +1 -0
- package/dist/tools/ask-agentic.tool.d.ts +11 -44
- package/dist/tools/ask-agentic.tool.d.ts.map +1 -1
- package/dist/tools/ask-agentic.tool.js +139 -1618
- package/dist/tools/ask-agentic.tool.js.map +1 -1
- package/dist/tools/ask.tool.d.ts +3 -41
- package/dist/tools/ask.tool.d.ts.map +1 -1
- package/dist/tools/ask.tool.js +46 -944
- package/dist/tools/ask.tool.js.map +1 -1
- package/dist/tools/code.tool.d.ts.map +1 -1
- package/dist/tools/code.tool.js +376 -514
- package/dist/tools/code.tool.js.map +1 -1
- package/dist/tools/reindex.tool.d.ts.map +1 -1
- package/dist/tools/reindex.tool.js +19 -22
- package/dist/tools/reindex.tool.js.map +1 -1
- package/dist/tools/shared/abort-timeout.d.ts +43 -5
- package/dist/tools/shared/abort-timeout.d.ts.map +1 -1
- package/dist/tools/shared/abort-timeout.js +111 -102
- package/dist/tools/shared/abort-timeout.js.map +1 -1
- package/dist/tools/shared/call-ledger.d.ts +27 -12
- package/dist/tools/shared/call-ledger.d.ts.map +1 -1
- package/dist/tools/shared/call-ledger.js +57 -39
- package/dist/tools/shared/call-ledger.js.map +1 -1
- package/dist/tools/shared/continuation.d.ts +1 -1
- package/dist/tools/shared/continuation.d.ts.map +1 -1
- package/dist/tools/shared/eager-answer.d.ts +78 -0
- package/dist/tools/shared/eager-answer.d.ts.map +1 -0
- package/dist/tools/shared/eager-answer.js +130 -0
- package/dist/tools/shared/eager-answer.js.map +1 -0
- package/dist/tools/shared/eager-call.d.ts +114 -0
- package/dist/tools/shared/eager-call.d.ts.map +1 -0
- package/dist/tools/shared/eager-call.js +95 -0
- package/dist/tools/shared/eager-call.js.map +1 -0
- package/dist/tools/shared/eager-steps.d.ts +114 -0
- package/dist/tools/shared/eager-steps.d.ts.map +1 -0
- package/dist/tools/shared/eager-steps.js +152 -0
- package/dist/tools/shared/eager-steps.js.map +1 -0
- package/dist/tools/shared/question-fields.d.ts +10 -0
- package/dist/tools/shared/question-fields.d.ts.map +1 -0
- package/dist/tools/shared/question-fields.js +13 -0
- package/dist/tools/shared/question-fields.js.map +1 -0
- package/dist/tools/shared/service-tier.d.ts +9 -0
- package/dist/tools/shared/service-tier.d.ts.map +1 -1
- package/dist/tools/shared/service-tier.js +15 -0
- package/dist/tools/shared/service-tier.js.map +1 -1
- package/dist/tools/shared/settle-call.d.ts +11 -6
- package/dist/tools/shared/settle-call.d.ts.map +1 -1
- package/dist/tools/shared/settle-call.js +14 -10
- package/dist/tools/shared/settle-call.js.map +1 -1
- package/dist/tools/shared/thinking.d.ts +9 -0
- package/dist/tools/shared/thinking.d.ts.map +1 -1
- package/dist/tools/shared/thinking.js +10 -0
- package/dist/tools/shared/thinking.js.map +1 -1
- package/dist/tools/shared/throttle.d.ts +7 -0
- package/dist/tools/shared/throttle.d.ts.map +1 -1
- package/dist/tools/shared/throttle.js +18 -0
- package/dist/tools/shared/throttle.js.map +1 -1
- package/dist/tools/shared/workspace-refusal.d.ts +13 -0
- package/dist/tools/shared/workspace-refusal.d.ts.map +1 -0
- package/dist/tools/shared/workspace-refusal.js +23 -0
- package/dist/tools/shared/workspace-refusal.js.map +1 -0
- package/package.json +1 -1
package/dist/tools/ask.tool.js
CHANGED
|
@@ -6,156 +6,17 @@
|
|
|
6
6
|
* uploads the workspace once and builds a persistent Context Cache (measured
|
|
7
7
|
* 2026-04-22 on a 670 k-token workspace: first call ~125 s, repeats ~14 s).
|
|
8
8
|
*/
|
|
9
|
-
import { createHash } from 'node:crypto';
|
|
10
9
|
import { resolve } from 'node:path';
|
|
11
|
-
import {
|
|
12
|
-
import {
|
|
13
|
-
import {
|
|
14
|
-
import {
|
|
15
|
-
import {
|
|
16
|
-
import {
|
|
17
|
-
import {
|
|
18
|
-
import {
|
|
19
|
-
import {
|
|
20
|
-
|
|
21
|
-
import { logger, safeForLog } from '../utils/logger.js';
|
|
22
|
-
import { createProgressEmitter } from '../utils/progress.js';
|
|
23
|
-
import { askAgenticTool } from './ask-agentic.tool.js';
|
|
24
|
-
import { errorResult, textResult } from './registry.js';
|
|
25
|
-
import { createTimeoutController, getTimeoutKind, isTimeoutAbort } from './shared/abort-timeout.js';
|
|
26
|
-
import { decodeOnContext } from './shared/context-decode.js';
|
|
27
|
-
import { CompletedRequests, LONG_DECODE_CAP_DESCRIPTION } from './shared/continuation.js';
|
|
28
|
-
import { DispatchThrottle } from './shared/dispatch-throttle.js';
|
|
29
|
-
import { SERVICE_TIER_DESCRIPTION, ServiceTierError, networkAttempts, resolveServiceTier, serviceTierConfig, statusOf, tierErrorMeta, } from './shared/service-tier.js';
|
|
30
|
-
import { settleAnswer, settleFailure } from './shared/settle-call.js';
|
|
31
|
-
import { SYSTEM_INSTRUCTION_SAFETY_EAGER } from './shared/system-instruction-safety.js';
|
|
32
|
-
import { THINKING_LEVEL_FIELD, thinkingBudgetUnder, thinkingReserve } from './shared/thinking.js';
|
|
33
|
-
/**
|
|
34
|
-
* `ask` system instruction. Prepends the shared `SYSTEM_INSTRUCTION_SAFETY_EAGER`
|
|
35
|
-
* data-vs-instruction firewall (added in v1.15.2 — pre-v1.15.2 `ask` had no
|
|
36
|
-
* safety rules at all, leaving it open to indirect prompt injection via
|
|
37
|
-
* adversarial workspace file content; same risk profile as v1.14.4 A1' for
|
|
38
|
-
* `ask_agentic`'s rescue path, just for the eager workspace upload channel).
|
|
39
|
-
*
|
|
40
|
-
* The role-statement after the safety block is the original v1.0 wording —
|
|
41
|
-
* task-specific guidance lives there; cross-tool security boundaries live
|
|
42
|
-
* in the shared safety block above.
|
|
43
|
-
*/
|
|
44
|
-
const SYSTEM_INSTRUCTION_Q_AND_A = [
|
|
45
|
-
SYSTEM_INSTRUCTION_SAFETY_EAGER,
|
|
46
|
-
'',
|
|
47
|
-
'You are a senior software engineer analysing a codebase. Be precise, reference specific file paths and line numbers, and cite evidence from the provided files rather than guessing. If the answer is not derivable from the context, say so.',
|
|
48
|
-
].join('\n');
|
|
49
|
-
/**
|
|
50
|
-
* Fallback output cap used only when the resolved model doesn't advertise
|
|
51
|
-
* an `outputTokenLimit` via `models.list()`. Set generously at the current
|
|
52
|
-
* Gemini pro-tier ceiling so the default behaviour is "let the model use
|
|
53
|
-
* its full trained capacity" — per v1.4.0 user feedback, arbitrary
|
|
54
|
-
* internal caps below the model's advertised limit are unhelpful
|
|
55
|
-
* self-limiting. Callers who want tighter caps for specific calls pass
|
|
56
|
-
* `maxOutputTokens` explicitly in the tool input.
|
|
57
|
-
*/
|
|
58
|
-
const ASK_MAX_OUTPUT_TOKENS_FALLBACK = 65_536;
|
|
59
|
-
/**
|
|
60
|
-
* Sentinel value in our internal normalisation for "user did not pass
|
|
61
|
-
* thinkingBudget". We translate this into an OMITTED `thinkingBudget`
|
|
62
|
-
* field on the wire — Gemini then uses each model's native default, which
|
|
63
|
-
* per Google's Gemini 3 guide (https://ai.google.dev/gemini-api/docs/gemini-3)
|
|
64
|
-
* is HIGH-dynamic on Gemini 3 Pro. Google flags explicit `thinkingBudget`
|
|
65
|
-
* as the "legacy" path on Gemini 3 ("may result in unexpected performance"),
|
|
66
|
-
* and we empirically observed Gemini 3 Pro hanging on low positive budgets
|
|
67
|
-
* with cached content active (see docs/KNOWN-DEFICITS.md). Omitting the
|
|
68
|
-
* field sidesteps both issues while still letting power users opt into
|
|
69
|
-
* explicit budgets on Gemini 2.5 or for cost-bounded deep-dives.
|
|
70
|
-
*/
|
|
71
|
-
const THINKING_BUDGET_MODEL_DEFAULT = null;
|
|
72
|
-
// `THINKING_LEVELS` + `THINKING_LEVEL_RESERVE` live in `./shared/thinking.ts`
|
|
73
|
-
// so both `ask` and `code` share a single source of truth — when Google
|
|
74
|
-
// publishes per-tier token budgets, one edit propagates to both tools.
|
|
75
|
-
export const askInputSchema = z
|
|
76
|
-
.object({
|
|
77
|
-
prompt: z.string().min(1).describe('The question or analysis request.'),
|
|
78
|
-
workspace: z
|
|
79
|
-
.string()
|
|
80
|
-
.optional()
|
|
81
|
-
.describe('Absolute or cwd-relative path to the workspace. Defaults to process.cwd().'),
|
|
82
|
-
model: z
|
|
83
|
-
.string()
|
|
84
|
-
.optional()
|
|
85
|
-
.describe("Model alias ('latest-pro', 'latest-pro-thinking', 'latest-flash', 'latest-lite', 'latest-vision') or literal model ID. Defaults to the configured default."),
|
|
86
|
-
includeGlobs: z
|
|
87
|
-
.array(z.string())
|
|
88
|
-
.optional()
|
|
89
|
-
.describe('Additional file extensions or filenames to include.'),
|
|
90
|
-
excludeGlobs: z
|
|
91
|
-
.array(z.string())
|
|
92
|
-
.optional()
|
|
93
|
-
.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.'),
|
|
94
|
-
noCache: z
|
|
95
|
-
.boolean()
|
|
96
|
-
.optional()
|
|
97
|
-
.describe('Skip the context cache and embed files inline (slower, more expensive).'),
|
|
98
|
-
thinkingBudget: z
|
|
99
|
-
.number()
|
|
100
|
-
.int()
|
|
101
|
-
.min(-1)
|
|
102
|
-
.max(65_536)
|
|
103
|
-
.optional()
|
|
104
|
-
.describe("Explicit reasoning-token cap. OMIT to use each model's native default — recommended on Gemini 3 (Google flags explicit `thinkingBudget` as 'legacy'). Pass a value only when you need a specific cap: `-1` = legacy dynamic, `0` = disable thinking (rejected by Gemini 3 Pro), positive integer = fixed cap. CAVEAT on Gemini 3 Pro: low positive values (empirically ≤256 with cached content) can cause the API to hang — use `-1` or ≥4096 if you must bound it there. For discrete-tier control on Gemini 3 use `thinkingLevel` instead — the two are mutually exclusive."),
|
|
105
|
-
thinkingLevel: THINKING_LEVEL_FIELD,
|
|
106
|
-
maxOutputTokens: z
|
|
107
|
-
.number()
|
|
108
|
-
.int()
|
|
109
|
-
.min(1)
|
|
110
|
-
.optional()
|
|
111
|
-
.describe([
|
|
112
|
-
"Per-call opt-in cap on response length (tokens). OMIT for the default 'auto' behaviour — Gemini uses its model-default cap (per Google docs, equal to the model's advertised `outputTokenLimit`: 65,536 for Gemini 3.x / 2.5 Pro-tier; see ai.google.dev/gemini-api/docs/models/gemini-2.5-pro). Pass a smaller value when you want a bounded response (e.g. strict summary length, tighter budget per call). On any other model a value larger than the resolved model's limit is clamped down to it. Budget reservation always uses the effective cap (explicit OR model limit) as worst-case, so `GEMINI_DAILY_BUDGET_USD` stays a true upper bound.",
|
|
113
|
-
LONG_DECODE_CAP_DESCRIPTION,
|
|
114
|
-
].join(' ')),
|
|
115
|
-
timeoutMs: z
|
|
116
|
-
.number()
|
|
117
|
-
.int()
|
|
118
|
-
.min(1_000)
|
|
119
|
-
.max(1_800_000)
|
|
120
|
-
.optional()
|
|
121
|
-
.describe('Per-call wall-clock TOTAL timeout in ms (1s–30min). The cost ceiling — aborts the in-flight `generateContent` request even if it is actively streaming. Gemini still finishes server-side and bills tokens for completed work. When omitted, falls back to env var `GEMINI_CODE_CONTEXT_ASK_TIMEOUT_MS`, then to disabled. v1.12.0 RECOMMENDATION: prefer `stallMs` for liveness — `timeoutMs` is the cost cap, `stallMs` is the heartbeat-aware liveness watchdog that does NOT fire while the model is actively thinking. Both can be set simultaneously. Returns `errorCode: "TIMEOUT"` with `timeoutKind: "total"` on abort.'),
|
|
122
|
-
stallMs: z
|
|
123
|
-
.number()
|
|
124
|
-
.int()
|
|
125
|
-
.min(1_000)
|
|
126
|
-
.max(600_000)
|
|
127
|
-
.optional()
|
|
128
|
-
.describe('Per-call HEARTBEAT-AWARE stall watchdog in ms (1s–10min, v1.12.0+). Resets on every chunk (text or thought) — fires ONLY when the stream goes silent for this long. Does NOT fire while the model is actively thinking — the streaming heartbeat (every ~1500ms via `onThoughtChunk`) keeps the watchdog reset. This is the right knob for "kill dead sockets quickly without penalising deep reasoning." Recommended setting: `60_000` (60s) — Gemini Pro can pause 15-30s mid-reasoning between thought chunks under heavy thinking; 60s absorbs jitter while still killing truly dead sockets ~30× faster than the wall-clock alternative. When omitted, falls back to env var `GEMINI_CODE_CONTEXT_ASK_STALL_MS`, then to disabled. Returns `errorCode: "TIMEOUT"` with `timeoutKind: "stall"` on abort. Independent of `timeoutMs` — both can be set; whichever fires first wins.'),
|
|
129
|
-
preflightMode: z
|
|
130
|
-
.enum(['heuristic', 'exact', 'auto'])
|
|
131
|
-
.optional()
|
|
132
|
-
.describe("Token-count strategy for the WORKSPACE_TOO_LARGE preflight (v1.10.0+). `'heuristic'` = bytes/4 fast estimate (skips API call; coarse — undercounts dense Unicode by 30-50%). `'exact'` = always call Gemini's `countTokens` (free, no quota share with `generateContent`; ~hundreds of ms per call; cached per (filesHash + prompt + model) — `filesHash` is post-glob-filter so changing globs that resolve to different files invalidates automatically). `'auto'` (default, recommended) = heuristic when the workspace is well under 50% of the model's input limit; exact when near the cliff where accuracy matters. Use `'exact'` in CI / tests where you want predictable, accurate behaviour regardless of size."),
|
|
133
|
-
serviceTier: z.enum(['standard', 'flex']).optional().describe(SERVICE_TIER_DESCRIPTION),
|
|
134
|
-
attachments: z
|
|
135
|
-
.array(z.string().min(1)) // the count cap is inspectAttachments' (ATTACHMENT_INVALID), not the schema's
|
|
136
|
-
.optional()
|
|
137
|
-
.describe(`Local image or PDF files (png, jpg, jpeg, webp, pdf; up to ${MAX_ATTACHMENTS}, ${MAX_ATTACHMENT_BYTES / 1024 / 1024} MB each, ${MAX_ATTACHMENTS_TOTAL_BYTES / 1024 / 1024} MB together) sent inline before the question — a screenshot of the bug, a diagram, a spec. Paths are inside the workspace (relative to it or absolute; a symlink is refused, the sandbox's secret rules apply, the first bytes must match the type). They belong to THIS question only, never to the workspace cache. Their tokens are counted by Gemini (one free countTokens call) and enter the size preflight, the budget reservation and the TPM throttle; a count that cannot be obtained refuses the call (ATTACHMENT_TOKENS_UNCOUNTED — retryable after a transient failure: no status, 429, 5xx; not after 401/403/404; a 400 means Gemini refused the parts: ATTACHMENT_INVALID). The model must support vision (ATTACHMENTS_UNSUPPORTED otherwise); a bad file is ATTACHMENT_INVALID, never retryable, and costs nothing. Not available with the ask_agentic fallback.`),
|
|
138
|
-
cachingMode: z
|
|
139
|
-
.enum(['explicit', 'implicit'])
|
|
140
|
-
.optional()
|
|
141
|
-
.describe(`Cache strategy for the workspace context. **\`'implicit'\` (default since v1.14.0)** skips \`caches.create\` entirely; file content is sent inline every call and Gemini 2.5+/3 Pro applies its automatic implicit caching on the repeated workspace prefix when prefix matches across calls. Optimised for the review→edit→review workflow — no 60–180 s rebuild wait when files change between queries. **\`'explicit'\`** builds a Gemini Context Cache via \`caches.create\` — guaranteed ~75% discount on cached input tokens, but pays the rebuild cost on every file change. Use explicit when you need predictable per-call costs more than warm-path latency; the trade-off is documented in Gemini's docs as 'no cost saving guarantee' for implicit caching. Hit rate is observable via \`status.structuredContent.caching.implicitHitRate\`. Operator-level override available via env \`GEMINI_CODE_CONTEXT_CACHING_MODE\`.${CACHING_MODE_FALLBACK_DESCRIPTION}`),
|
|
142
|
-
forceRescan: z
|
|
143
|
-
.boolean()
|
|
144
|
-
.optional()
|
|
145
|
-
.describe('Bypass the v1.13.0 scan memo and re-hash every file in the workspace (default `false`). The scan memo skips per-file SHA256 when `mtime_ms` and `size` match the previously-stored values — typically ~95% of files on a warm rescan, cutting scan wall-clock by ≥10× on large workspaces. Set this when you suspect the manifest is stale (e.g. files mutated outside the dev workflow, NTP clock-skew, or you ran `git checkout` on a directory tree). Equivalent to setting env `GEMINI_CODE_CONTEXT_FORCE_RESCAN=true` for a single call.'),
|
|
146
|
-
onWorkspaceTooLarge: z
|
|
147
|
-
.enum(['error', 'fallback-to-agentic'])
|
|
148
|
-
.optional()
|
|
149
|
-
.describe("Behaviour when the v1.5.0 preflight detects the workspace exceeds the model's `inputTokenLimit × workspaceGuardRatio` (v1.11.0+). `'error'` (default — preserves v1.5.0 behaviour) returns a structured `errorCode: 'WORKSPACE_TOO_LARGE'` and lets the caller decide how to recover. `'fallback-to-agentic'` opt-in: the server transparently re-routes through `ask_agentic` (sandboxed file-access loop — no eager upload, scales to arbitrarily large repos), wraps the agentic result, and surfaces `fallbackApplied: 'ask_agentic'` in `structuredContent` so callers can audit the swap. **Semantic divergence:** `ask_agentic` runs as a multi-iteration loop, so `timeoutMs` (ask's wall-clock cap) translates to `iterationTimeoutMs` (per-iteration cap); total wall-clock can be N × timeoutMs. Cost shape also changes (multiple smaller calls vs one big eager call). Recommended setting for orchestrators that prioritise getting an answer over a single round-trip; default stays `'error'` so existing callers see no behaviour change. **`code` does NOT support this field** — `code`'s OLD/NEW edit format is load-bearing for Claude's Edit pipeline, and `ask_agentic` returns prose only."),
|
|
150
|
-
})
|
|
151
|
-
.refine((data) => !(data.thinkingBudget !== undefined && data.thinkingLevel !== undefined), {
|
|
152
|
-
message: 'Cannot specify both `thinkingBudget` and `thinkingLevel` — they are mutually exclusive. Gemini rejects the combination with 400. Choose one: `thinkingLevel` (recommended for Gemini 3) or `thinkingBudget` (required on Gemini 2.5).',
|
|
153
|
-
// `path: []` (root-level error) reflects that the violation is the
|
|
154
|
-
// RELATION between two fields, not a problem with either field
|
|
155
|
-
// individually. MCP clients that render per-field errors won't
|
|
156
|
-
// misattribute the issue to `thinkingLevel` alone.
|
|
157
|
-
path: [],
|
|
158
|
-
});
|
|
10
|
+
import { answerAsk } from './ask/answer.js';
|
|
11
|
+
import { attachAsk } from './ask/attachments.js';
|
|
12
|
+
import { guardAsk } from './ask/guard.js';
|
|
13
|
+
import { askInputSchema } from './ask/input.js';
|
|
14
|
+
import { failedResult } from './ask/results.js';
|
|
15
|
+
import { resolveAsk, scanAsk } from './ask/setup.js';
|
|
16
|
+
import { sizeAsk } from './ask/sizing.js';
|
|
17
|
+
import { closeEagerCall, openEagerCall, settleFailedEager, } from './shared/eager-call.js';
|
|
18
|
+
import { workspaceRefusal } from './shared/workspace-refusal.js';
|
|
19
|
+
export { askInputSchema };
|
|
159
20
|
export const askTool = {
|
|
160
21
|
name: 'ask',
|
|
161
22
|
title: 'Ask Gemini',
|
|
@@ -168,807 +29,48 @@ export const askTool = {
|
|
|
168
29
|
return executeAskBody(input, ctx, workspaceRoot, model, started);
|
|
169
30
|
},
|
|
170
31
|
};
|
|
171
|
-
/**
|
|
172
|
-
*
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
return { attached, parts, bytes, tokens };
|
|
178
|
-
}
|
|
179
|
-
/** The attachments of one call, or the refusal that ends it: a model without vision, a bad file (never retryable),
|
|
180
|
-
* a count Gemini could not give. Nothing has been scanned or reserved yet. */
|
|
181
|
-
async function attachmentsOrRefusal(client, paths, resolved, serviceTier, workspaceRoot, signal) {
|
|
182
|
-
const meta = { serviceTier, resolvedModel: resolved.resolved };
|
|
183
|
-
if (paths.length > 0 && !resolved.capabilities.supportsVision) {
|
|
184
|
-
return {
|
|
185
|
-
refusal: errorResult(`ask: ${paths.length} attachment(s) given, but ${safeForLog(resolved.resolved)} does not support vision — use \`latest-vision\` or a model that lists it`, { errorCode: 'ATTACHMENTS_UNSUPPORTED', retryable: false, ...meta }),
|
|
186
|
-
};
|
|
187
|
-
}
|
|
188
|
-
try {
|
|
189
|
-
return {
|
|
190
|
-
prepared: await prepareAttachments(client, paths, workspaceRoot, resolved.resolved, signal),
|
|
191
|
-
};
|
|
192
|
-
}
|
|
193
|
-
catch (err) {
|
|
194
|
-
if (!(err instanceof AttachmentError) && !(err instanceof AttachmentTokensUncountedError))
|
|
195
|
-
throw err;
|
|
196
|
-
return {
|
|
197
|
-
refusal: errorResult(`ask: ${err.message}`, {
|
|
198
|
-
errorCode: err.code,
|
|
199
|
-
retryable: err.retryable,
|
|
200
|
-
...meta,
|
|
201
|
-
}),
|
|
202
|
-
};
|
|
203
|
-
}
|
|
204
|
-
}
|
|
205
|
-
/** The bytes of one workspace file as the request carries it: its body and its `--- FILE: <relpath> ---` marker. */
|
|
206
|
-
const FILE_MARKER_BYTES = '\n\n--- FILE: ---\n\n'.length;
|
|
207
|
-
function inlineFileBytes(files) {
|
|
208
|
-
return files.reduce((sum, f) => sum + f.size + Buffer.byteLength(f.relpath, 'utf8') + FILE_MARKER_BYTES, 0);
|
|
209
|
-
}
|
|
210
|
-
/** Google's inline request limit holds whatever the caching mode (an explicit cache may not be built and the call
|
|
211
|
-
* then runs inline): the refusal, before any reservation, when a conservative size of the request — the attachments
|
|
212
|
-
* encoded, the workspace bodies with their markers, the prompt, the system instruction, the JSON framing — crosses
|
|
213
|
-
* it; nothing otherwise. */
|
|
214
|
-
function inlineRequestRefusal(prepared, files, prompt, serviceTier) {
|
|
215
|
-
if (prepared.attached.length === 0)
|
|
216
|
-
return undefined;
|
|
217
|
-
const textBytes = inlineFileBytes(files) +
|
|
218
|
-
Buffer.byteLength(prompt, 'utf8') +
|
|
219
|
-
Buffer.byteLength(SYSTEM_INSTRUCTION_Q_AND_A, 'utf8');
|
|
220
|
-
const requestBytes = inlineRequestBytes(prepared.attached.map((a) => a.bytes), textBytes, files.length + 2);
|
|
221
|
-
if (requestBytes <= INLINE_REQUEST_LIMIT_BYTES)
|
|
222
|
-
return undefined;
|
|
223
|
-
return errorResult(`ask: the inline request would carry ${requestBytes} bytes (the attachments base64-encoded, the workspace with its file markers, the prompt, the system instruction and the JSON framing), above Google's ${INLINE_REQUEST_LIMIT_BYTES}-byte limit for inline data; use fewer or smaller attachments, or narrow the workspace with includeGlobs / excludeGlobs`, {
|
|
224
|
-
errorCode: 'REQUEST_TOO_LARGE',
|
|
225
|
-
retryable: false,
|
|
226
|
-
serviceTier,
|
|
227
|
-
...attachmentMetadata(prepared),
|
|
228
|
-
});
|
|
229
|
-
}
|
|
230
|
-
/** `structuredContent` fields of a call with attachments; nothing on a call without. */
|
|
231
|
-
function attachmentMetadata(prepared) {
|
|
232
|
-
if (prepared.attached.length === 0)
|
|
233
|
-
return {};
|
|
234
|
-
return {
|
|
235
|
-
attachments: prepared.attached.map((a) => ({
|
|
236
|
-
path: a.path,
|
|
237
|
-
mimeType: a.mimeType,
|
|
238
|
-
bytes: a.bytes,
|
|
239
|
-
})),
|
|
240
|
-
attachmentTokens: prepared.tokens,
|
|
241
|
-
};
|
|
242
|
-
}
|
|
32
|
+
/**
|
|
33
|
+
* One `ask` call: opened before its first await, its steps run in order — each goes on with the next stage or ends the
|
|
34
|
+
* call — and closed on every path. Every throw of a step reaches the one failure path. The `ask_agentic` fallback's
|
|
35
|
+
* promise is returned unawaited from inside the `try`: the `finally` runs while the fallback runs, and a rejection of
|
|
36
|
+
* the fallback reaches the caller as it came, never the call's failure path.
|
|
37
|
+
*/
|
|
243
38
|
async function executeAskBody(input, ctx, workspaceRoot, model, started) {
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
const completed = new CompletedRequests();
|
|
252
|
-
// the running decode's booking and whether a stream opened (a later failure is then billed work, not re-sent)
|
|
253
|
-
const tracking = { ledgerEntry: null, streamOpened: false };
|
|
254
|
-
// the tier this call runs on once resolved (Vertex may force standard); before that, the requested one is reported
|
|
255
|
-
let serviceTier;
|
|
256
|
-
const reportedTier = () => serviceTier ?? input.serviceTier ?? ctx.config.serviceTier;
|
|
257
|
-
const emitter = createProgressEmitter(ctx.server, ctx.progressToken);
|
|
258
|
-
// Composite timeout controller — wall-clock-bound (`timeoutMs`) AND/OR
|
|
259
|
-
// heartbeat-aware stall watchdog (`stallMs`, v1.12.0). Set up before any
|
|
260
|
-
// await so a `timeoutMs: 1000` against a slow scan still fires. The
|
|
261
|
-
// unified signal threads into both `withNetworkRetry({signal})` and the
|
|
262
|
-
// SDK's `config.abortSignal` — whichever timer fires first aborts both
|
|
263
|
-
// layers cleanly. `recordChunk()` is wired into `collectStream` to reset
|
|
264
|
-
// the stall watchdog on every chunk arrival.
|
|
265
|
-
const timeoutController = createTimeoutController({
|
|
266
|
-
...(input.timeoutMs !== undefined ? { totalMs: input.timeoutMs } : {}),
|
|
267
|
-
totalEnvVar: 'GEMINI_CODE_CONTEXT_ASK_TIMEOUT_MS',
|
|
268
|
-
...(input.stallMs !== undefined ? { stallMs: input.stallMs } : {}),
|
|
269
|
-
stallEnvVar: 'GEMINI_CODE_CONTEXT_ASK_STALL_MS',
|
|
270
|
-
});
|
|
271
|
-
const abortSignal = timeoutController.signal;
|
|
272
|
-
// Each request of the decode holds its own TPM reservation; a failure drops the one held.
|
|
273
|
-
const dispatch = new DispatchThrottle({
|
|
274
|
-
throttle: ctx.throttle,
|
|
275
|
-
enabled: ctx.config.tpmThrottleLimit > 0,
|
|
276
|
-
signal: abortSignal,
|
|
277
|
-
emit: (message) => emitter.emit(message),
|
|
278
|
-
});
|
|
39
|
+
const eager = openEagerCall({
|
|
40
|
+
tool: 'ask',
|
|
41
|
+
knobs: input,
|
|
42
|
+
requestedTier: input.serviceTier ?? ctx.config.serviceTier,
|
|
43
|
+
workspaceRoot,
|
|
44
|
+
started,
|
|
45
|
+
}, ctx);
|
|
279
46
|
try {
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
const resolved = await resolveModel(model, ctx.client, {
|
|
302
|
-
requiredCategory: ['text-reasoning', 'text-fast', 'text-lite'],
|
|
303
|
-
});
|
|
304
|
-
resolvedModelKey = resolved.resolved;
|
|
305
|
-
try {
|
|
306
|
-
serviceTier = resolveServiceTier(input.serviceTier, ctx.config.serviceTier, ctx.config.vertex);
|
|
307
|
-
}
|
|
308
|
-
catch (err) {
|
|
309
|
-
if (!(err instanceof ServiceTierError))
|
|
310
|
-
throw err;
|
|
311
|
-
return errorResult(`ask: ${err.message}`, {
|
|
312
|
-
errorCode: err.code,
|
|
313
|
-
retryable: false,
|
|
314
|
-
serviceTier: 'flex',
|
|
315
|
-
resolvedModel: resolved.resolved,
|
|
316
|
-
});
|
|
317
|
-
}
|
|
318
|
-
// Attachments ride with the prompt as inline parts. Inspected, read and counted here — before the scan, the
|
|
319
|
-
// preflight, the budget reservation and the throttle: a bad file costs nothing.
|
|
320
|
-
const attachmentsOutcome = await attachmentsOrRefusal(ctx.client, input.attachments ?? [], resolved, serviceTier, workspaceRoot, abortSignal);
|
|
321
|
-
if ('refusal' in attachmentsOutcome)
|
|
322
|
-
return attachmentsOutcome.refusal;
|
|
323
|
-
const attachments = attachmentsOutcome.prepared;
|
|
324
|
-
const attachmentTokens = attachments.tokens;
|
|
325
|
-
emitter.emit(`scanning workspace ${workspaceRoot}…`);
|
|
326
|
-
// v1.13.0 — build the scan memo from previously-stored file rows so the
|
|
327
|
-
// scanner can skip re-hashing files whose mtime+size haven't changed.
|
|
328
|
-
// First-run on a new workspace produces an empty map (= every file
|
|
329
|
-
// hashes), which matches pre-v1.13 behaviour.
|
|
330
|
-
const scanMemo = buildScanMemo(ctx.manifest.getFiles(workspaceRoot));
|
|
331
|
-
const scan = await scanWorkspace(workspaceRoot, {
|
|
332
|
-
...(input.includeGlobs !== undefined ? { includeGlobs: input.includeGlobs } : {}),
|
|
333
|
-
...(input.excludeGlobs !== undefined ? { excludeGlobs: input.excludeGlobs } : {}),
|
|
334
|
-
maxFiles: ctx.config.maxFilesPerWorkspace,
|
|
335
|
-
maxFileSizeBytes: ctx.config.maxFileSizeBytes,
|
|
336
|
-
manifestMemo: scanMemo,
|
|
337
|
-
forceRescan: input.forceRescan === true || ctx.config.forceRescan === true,
|
|
338
|
-
});
|
|
339
|
-
// Output cap, three layers (`resolveOutputCap`):
|
|
340
|
-
//
|
|
341
|
-
// 1. `input.maxOutputTokens` (per-call, strongest) — clamped to the
|
|
342
|
-
// model's per-request limit, or on a model with long decode
|
|
343
|
-
// (Gemini 4) to its long-decode total: a cap above the per-request
|
|
344
|
-
// limit continues the decode in further requests.
|
|
345
|
-
// 2. `ctx.config.forceMaxOutputTokens` (env override) — every call
|
|
346
|
-
// sends the model's per-request limit.
|
|
347
|
-
// 3. Default — `maxOutputTokens` is omitted: one request, the model's
|
|
348
|
-
// own default (its advertised `outputTokenLimit`), letting the model
|
|
349
|
-
// size the response to the query rather than reserving full capacity.
|
|
350
|
-
//
|
|
351
|
-
// The caller's `thinkingBudget` is checked against `outputCap`; the
|
|
352
|
-
// clamp and the reservation use the cap that runs (`runCap`).
|
|
353
|
-
const outputCap = resolveOutputCap({
|
|
354
|
-
requested: input.maxOutputTokens,
|
|
355
|
-
forceMax: ctx.config.forceMaxOutputTokens,
|
|
356
|
-
outputTokenLimit: resolved.outputTokenLimit,
|
|
357
|
-
longDecodeTokenLimit: resolved.longDecodeTokenLimit,
|
|
358
|
-
fallbackLimit: ASK_MAX_OUTPUT_TOKENS_FALLBACK,
|
|
359
|
-
});
|
|
360
|
-
// Single source of truth for "is the caller driving reasoning via the
|
|
361
|
-
// discrete-tier knob?". Three downstream call sites branch on this
|
|
362
|
-
// (cost estimate, emitter, thinkingConfig build) — extracting to a
|
|
363
|
-
// named const keeps them in lockstep and makes future additions hard
|
|
364
|
-
// to forget.
|
|
365
|
-
const usingThinkingLevel = input.thinkingLevel !== undefined;
|
|
366
|
-
// A positive `thinkingBudget` that leaves no answer reserve under the caller's own cap is refused
|
|
367
|
-
// (`thinkingBudgetRefusal`); below, the budget on the wire is clamped under the cap that runs.
|
|
368
|
-
const budgetRefusal = thinkingBudgetRefusal(input.thinkingBudget, input.maxOutputTokens, outputCap.effective);
|
|
369
|
-
if (budgetRefusal !== null)
|
|
370
|
-
return errorResult(`ask: ${budgetRefusal}`);
|
|
371
|
-
// Estimated input-token count drives both the daily-budget reservation
|
|
372
|
-
// (dollars) and the TPM throttle reservation (rate). Hoisted here so
|
|
373
|
-
// both consumers share one fingerprint — no drift between what the $
|
|
374
|
-
// ledger thinks we'll spend and what the rate-limiter thinks we'll
|
|
375
|
-
// send to Gemini. Budget reservation still uses the bytes/4 heuristic
|
|
376
|
-
// (cheap; `estimatePreCallCostUsd` already takes raw bytes), but the
|
|
377
|
-
// PREFLIGHT against `inputTokenLimit` now goes through the v1.10.0
|
|
378
|
-
// two-tier `countForPreflight` (Tier 1 = heuristic for small repos;
|
|
379
|
-
// Tier 2 = real `countTokens` call when near the cliff). Closes T17
|
|
380
|
-
// (`bytes/4` undercount on dense Unicode). See `src/gemini/token-counter.ts`.
|
|
381
|
-
const workspaceBytes = scan.files.reduce((sum, f) => sum + f.size, 0);
|
|
382
|
-
const estimatedInputTokens = Math.ceil(workspaceBytes / 4) + Math.ceil(input.prompt.length / 4) + attachmentTokens;
|
|
383
|
-
const inlineRefusal = inlineRequestRefusal(attachments, scan.files, input.prompt, serviceTier);
|
|
384
|
-
if (inlineRefusal !== undefined)
|
|
385
|
-
return inlineRefusal;
|
|
386
|
-
// v1.5.0 preflight (rebuilt in v1.10.0 on top of `countTokens`) — refuse
|
|
387
|
-
// immediately if the estimated input doesn't fit under the model's
|
|
388
|
-
// advertised `inputTokenLimit * workspaceGuardRatio`. Before this
|
|
389
|
-
// guard we would dispatch the request, Gemini would reject with
|
|
390
|
-
// `400 INVALID_ARGUMENT "exceeds maximum ..."`, and the calling
|
|
391
|
-
// sub-agent would interpret the 400 as retryable (the error body is
|
|
392
|
-
// indistinguishable from transient quota errors at the string level)
|
|
393
|
-
// → unbounded retry storm. Cheap pre-flight with a structured
|
|
394
|
-
// `WORKSPACE_TOO_LARGE` errorCode + `retryable: false` signals to the
|
|
395
|
-
// orchestrator that this is not recoverable without user action.
|
|
396
|
-
//
|
|
397
|
-
// `inputTokenLimit` can be `null` when `models.list()` didn't advertise
|
|
398
|
-
// it (typically happens only on internal / preview model IDs we've never
|
|
399
|
-
// seen). In that case we fall through without blocking but warn —
|
|
400
|
-
// better to let the request hit the API and fail noisily than to
|
|
401
|
-
// block a legitimate call on missing metadata.
|
|
402
|
-
// Hoisted past the `if (contextWindow > 0)` block so the success-path
|
|
403
|
-
// metadata (lines below) can surface `tokenCountMethod` /
|
|
404
|
-
// `rawTokenCount` / `tokenCountCacheHit` regardless of whether the
|
|
405
|
-
// preflight actually ran. Stays `undefined` only when the resolved
|
|
406
|
-
// model has no advertised `inputTokenLimit`.
|
|
407
|
-
let preflight;
|
|
408
|
-
const contextWindow = resolved.inputTokenLimit;
|
|
409
|
-
// A decode that may take more than one request takes the exact count: its prompt is billed per request.
|
|
410
|
-
const preflightMode = preflightModeFor(input.preflightMode, outputCap);
|
|
411
|
-
if (typeof contextWindow === 'number' && contextWindow > 0) {
|
|
412
|
-
preflight = await countForPreflight(ctx.client, {
|
|
413
|
-
files: scan.files,
|
|
414
|
-
prompt: input.prompt,
|
|
415
|
-
model: resolved.resolved,
|
|
416
|
-
// `filesHash` is post-glob-filter (see `scanWorkspace`), so it
|
|
417
|
-
// already encodes user-supplied includeGlobs/excludeGlobs — no
|
|
418
|
-
// separate globsHash axis needed in the cache key.
|
|
419
|
-
filesHash: scan.filesHash,
|
|
420
|
-
...(preflightMode !== undefined ? { preflightMode } : {}),
|
|
421
|
-
inputTokenLimit: contextWindow,
|
|
422
|
-
extraTokens: attachmentTokens, // weighs on the heuristic-vs-exact decision, added to the count below
|
|
423
|
-
// Thread the user's `timeoutMs` AbortSignal so a hung countTokens
|
|
424
|
-
// call doesn't bleed past the user's stated wall-clock budget. The
|
|
425
|
-
// SDK's `CountTokensConfig` accepts `abortSignal`; on cancellation
|
|
426
|
-
// the SDK throws `AbortError`, which `countForPreflight` re-throws
|
|
427
|
-
// (rather than swallowing as a fallback) so this outer try/catch
|
|
428
|
-
// maps it to `errorCode: 'TIMEOUT'` immediately.
|
|
429
|
-
signal: abortSignal,
|
|
430
|
-
});
|
|
431
|
-
// the attachments' tokens, counted by Gemini, join the count whichever way it was made: the window must hold them
|
|
432
|
-
preflight = { ...preflight, effectiveTokens: preflight.effectiveTokens + attachmentTokens };
|
|
433
|
-
const threshold = Math.floor(contextWindow * ctx.config.workspaceGuardRatio);
|
|
434
|
-
if (preflight.effectiveTokens > threshold) {
|
|
435
|
-
const pctDisplay = Math.round(ctx.config.workspaceGuardRatio * 100);
|
|
436
|
-
// v1.11.0 — opt-in transparent fallback to `ask_agentic` when the
|
|
437
|
-
// caller explicitly asked for it via `onWorkspaceTooLarge:
|
|
438
|
-
// 'fallback-to-agentic'`. Default stays `'error'` so pre-v1.11.0
|
|
439
|
-
// callers see identical behaviour. The fallback re-uses this
|
|
440
|
-
// tool's resolved inputs (model / globs / thinking config /
|
|
441
|
-
// workspace) and re-translates `timeoutMs` to `iterationTimeoutMs`
|
|
442
|
-
// (per-iteration cap; total wall-clock can be N × that). Cost +
|
|
443
|
-
// timing shape genuinely changes — opt-in is the right default.
|
|
444
|
-
if (input.onWorkspaceTooLarge === 'fallback-to-agentic' &&
|
|
445
|
-
attachments.attached.length > 0) {
|
|
446
|
-
return errorResult('ask: the workspace is too large for the eager path and `attachments` cannot follow the ask_agentic fallback (it sends no inline parts); drop the attachments or narrow the workspace', {
|
|
447
|
-
errorCode: 'WORKSPACE_TOO_LARGE',
|
|
448
|
-
retryable: false,
|
|
449
|
-
serviceTier,
|
|
450
|
-
...attachmentMetadata(attachments),
|
|
451
|
-
});
|
|
452
|
-
}
|
|
453
|
-
if (input.onWorkspaceTooLarge === 'fallback-to-agentic') {
|
|
454
|
-
if (serviceTier === 'flex') {
|
|
455
|
-
const note = 'ask: the ask_agentic fallback has no service tier — this call runs standard, not flex';
|
|
456
|
-
emitter.emit(note);
|
|
457
|
-
logger.warn(note);
|
|
458
|
-
}
|
|
459
|
-
logger.warn(`ask: WORKSPACE_TOO_LARGE (${preflight.effectiveTokens} > ${threshold}); falling back to ask_agentic per onWorkspaceTooLarge='fallback-to-agentic'`);
|
|
460
|
-
// Translate `timeoutMs` AND `stallMs` to the agentic per-iteration
|
|
461
|
-
// wall-clock cap (`iterationTimeoutMs`). Pre-v1.12.1 only `timeoutMs`
|
|
462
|
-
// was forwarded — a user who set `stallMs: 60000` (the v1.12.0
|
|
463
|
-
// recommended liveness watchdog) saw it silently dropped on the
|
|
464
|
-
// fallback path. The agentic loop uses non-streaming
|
|
465
|
-
// `generateContent`, so there's no chunk stream to reset on; we
|
|
466
|
-
// collapse both knobs onto the per-iteration cap and use the
|
|
467
|
-
// TIGHTER of the two as the bound. The CHANGELOG documents the
|
|
468
|
-
// semantic divergence on `timeoutMs` (total → per-iteration).
|
|
469
|
-
//
|
|
470
|
-
// v1.12.2 — `iterTimeoutSource` is surfaced in metadata AND emitted
|
|
471
|
-
// in the warn-log so users can see WHICH knob bound their call
|
|
472
|
-
// (one of: 'timeoutMs', 'stallMs', or 'min(timeoutMs,stallMs)').
|
|
473
|
-
// Pre-v1.12.2 the log only fired when stallMs was set alone; the
|
|
474
|
-
// both-set case had no signal explaining the pick.
|
|
475
|
-
const iterTimeoutPick = (() => {
|
|
476
|
-
const a = input.timeoutMs;
|
|
477
|
-
const b = input.stallMs;
|
|
478
|
-
if (a !== undefined && b !== undefined) {
|
|
479
|
-
const cap = Math.min(a, b);
|
|
480
|
-
return { cap, source: 'min(timeoutMs,stallMs)' };
|
|
481
|
-
}
|
|
482
|
-
if (a !== undefined)
|
|
483
|
-
return { cap: a, source: 'timeoutMs' };
|
|
484
|
-
if (b !== undefined)
|
|
485
|
-
return { cap: b, source: 'stallMs' };
|
|
486
|
-
return { cap: undefined, source: 'none' };
|
|
487
|
-
})();
|
|
488
|
-
const tightestPerIterCap = iterTimeoutPick.cap;
|
|
489
|
-
if (iterTimeoutPick.source !== 'none') {
|
|
490
|
-
logger.warn(`ask: fallback to ask_agentic — \`iterationTimeoutMs\` set to ${tightestPerIterCap}ms (source: ${iterTimeoutPick.source}). The agentic loop uses non-streaming \`generateContent\` so there's no chunk stream to reset on; \`stallMs\` (when set) is treated as a per-iteration wall-clock cap, the same way \`timeoutMs\` is. Total wall-clock for the agentic call can reach \`maxIterations × iterationTimeoutMs\`.`);
|
|
491
|
-
}
|
|
492
|
-
const agenticInput = {
|
|
493
|
-
prompt: input.prompt,
|
|
494
|
-
...(input.workspace !== undefined ? { workspace: input.workspace } : {}),
|
|
495
|
-
...(input.model !== undefined ? { model: input.model } : {}),
|
|
496
|
-
...(input.includeGlobs !== undefined ? { includeGlobs: input.includeGlobs } : {}),
|
|
497
|
-
...(input.excludeGlobs !== undefined ? { excludeGlobs: input.excludeGlobs } : {}),
|
|
498
|
-
...(input.thinkingBudget !== undefined ? { thinkingBudget: input.thinkingBudget } : {}),
|
|
499
|
-
...(input.thinkingLevel !== undefined ? { thinkingLevel: input.thinkingLevel } : {}),
|
|
500
|
-
...(input.maxOutputTokens !== undefined
|
|
501
|
-
? { maxOutputTokens: input.maxOutputTokens }
|
|
502
|
-
: {}),
|
|
503
|
-
// `timeoutMs` (ask wall-clock cap) → `iterationTimeoutMs`
|
|
504
|
-
// (ask_agentic per-iteration cap). Total wall-clock for the
|
|
505
|
-
// agentic call can be `maxIterations × iterationTimeoutMs`.
|
|
506
|
-
// v1.12.1 fix: also collapses `stallMs` onto this cap (using
|
|
507
|
-
// the TIGHTER of the two when both are set), so the fallback
|
|
508
|
-
// path doesn't silently drop the user's stall watchdog.
|
|
509
|
-
...(tightestPerIterCap !== undefined ? { iterationTimeoutMs: tightestPerIterCap } : {}),
|
|
510
|
-
};
|
|
511
|
-
const agenticResult = await askAgenticTool.execute(agenticInput, ctx);
|
|
512
|
-
// Wrap the agentic result so callers can audit the swap.
|
|
513
|
-
// The text content (`content[0].text`) is the agentic prose
|
|
514
|
-
// verbatim — same shape any direct `ask_agentic` caller would
|
|
515
|
-
// see. The structuredContent is enriched with fallback-trail
|
|
516
|
-
// metadata so orchestrators can distinguish a fallback-served
|
|
517
|
-
// response from a direct one.
|
|
518
|
-
//
|
|
519
|
-
// Two load-bearing contracts the wrapper must preserve:
|
|
520
|
-
// 1. `structuredContent.responseText` — the T23 wire-format
|
|
521
|
-
// invariant (`textResult` / `errorResult` always write it
|
|
522
|
-
// LAST; sub-agent orchestrators extract from this key
|
|
523
|
-
// ONLY). We pull it from the agentic result's
|
|
524
|
-
// `structuredContent.responseText` (or the prose text from
|
|
525
|
-
// `content[0].text` as a fallback) and write it LAST so
|
|
526
|
-
// it can't be clobbered.
|
|
527
|
-
// 2. Top-level `errorCode` / `retryable` — orchestrator retry
|
|
528
|
-
// policies switch on these. When the agentic call itself
|
|
529
|
-
// fails (e.g. iteration budget exhausted), the failure
|
|
530
|
-
// code lives in `agenticResult.structuredContent.errorCode`;
|
|
531
|
-
// we lift it to the top level of `wrappedStructured` so
|
|
532
|
-
// consumer policies see it without descending into nested
|
|
533
|
-
// `agenticResult.errorCode` (which they wouldn't know
|
|
534
|
-
// about pre-v1.11.0).
|
|
535
|
-
const agenticStructured = agenticResult.structuredContent ?? {};
|
|
536
|
-
const promptResponseText = typeof agenticStructured.responseText === 'string'
|
|
537
|
-
? agenticStructured.responseText
|
|
538
|
-
: agenticResult.content?.[0]?.type === 'text'
|
|
539
|
-
? agenticResult.content[0].text
|
|
540
|
-
: '';
|
|
541
|
-
const wrappedStructured = {
|
|
542
|
-
fallbackApplied: 'ask_agentic',
|
|
543
|
-
serviceTier: 'standard', // ask_agentic has no tier: the fallback runs standard whatever was asked
|
|
544
|
-
...(serviceTier === 'flex' ? { serviceTierDowngraded: 'flex' } : {}),
|
|
545
|
-
fallbackReason: 'WORKSPACE_TOO_LARGE',
|
|
546
|
-
preflightEstimate: {
|
|
547
|
-
tokens: preflight.effectiveTokens,
|
|
548
|
-
threshold,
|
|
549
|
-
source: preflight.method,
|
|
550
|
-
cacheHit: preflight.cacheHit,
|
|
551
|
-
rawTokens: preflight.rawTokens,
|
|
552
|
-
},
|
|
553
|
-
// v1.12.2 — surface the per-iteration cap selection so callers
|
|
554
|
-
// can audit which knob bound the fallback call. Useful when the
|
|
555
|
-
// user passed both `timeoutMs` and `stallMs` (we use the tighter
|
|
556
|
-
// of the two — `iterTimeoutSource: 'min(timeoutMs,stallMs)'`).
|
|
557
|
-
// Omitted when neither knob was set (`source: 'none'`).
|
|
558
|
-
...(iterTimeoutPick.source !== 'none'
|
|
559
|
-
? {
|
|
560
|
-
iterTimeoutMs: tightestPerIterCap,
|
|
561
|
-
iterTimeoutSource: iterTimeoutPick.source,
|
|
562
|
-
}
|
|
563
|
-
: {}),
|
|
564
|
-
// Lift top-level error metadata from the agentic call's
|
|
565
|
-
// structuredContent so orchestrator policies (e.g. retry on
|
|
566
|
-
// BUDGET_EXHAUSTED, retry on stall but not total) keep working
|
|
567
|
-
// without descending into `.agenticResult.errorCode`. v1.12.1
|
|
568
|
-
// adds `timeoutKind` to the lift set — Phase 4 introduced
|
|
569
|
-
// `timeoutKind` as a top-level field on direct-path TIMEOUT
|
|
570
|
-
// errors; the fallback wrapper now mirrors that on the
|
|
571
|
-
// fallback-served TIMEOUT path so the contract is uniform.
|
|
572
|
-
...(agenticResult.isError && typeof agenticStructured.errorCode === 'string'
|
|
573
|
-
? { errorCode: agenticStructured.errorCode }
|
|
574
|
-
: {}),
|
|
575
|
-
...(agenticResult.isError && typeof agenticStructured.retryable === 'boolean'
|
|
576
|
-
? { retryable: agenticStructured.retryable }
|
|
577
|
-
: {}),
|
|
578
|
-
...(agenticResult.isError &&
|
|
579
|
-
(agenticStructured.timeoutKind === 'total' || agenticStructured.timeoutKind === 'stall')
|
|
580
|
-
? { timeoutKind: agenticStructured.timeoutKind }
|
|
581
|
-
: {}),
|
|
582
|
-
...(Object.keys(agenticStructured).length > 0
|
|
583
|
-
? { agenticResult: agenticStructured }
|
|
584
|
-
: {}),
|
|
585
|
-
// T23 wire-format invariant — `responseText` is written LAST
|
|
586
|
-
// so any caller-supplied / nested key with the same name is
|
|
587
|
-
// intentionally clobbered by the canonical value. Sub-agent
|
|
588
|
-
// orchestrators read the prose from this exact key.
|
|
589
|
-
responseText: promptResponseText,
|
|
590
|
-
};
|
|
591
|
-
// `isError` lives at the ROOT of the MCP CallToolResult per spec
|
|
592
|
-
// (sibling to `structuredContent`, not nested inside it). The
|
|
593
|
-
// spread on the return statement carries the agentic root-level
|
|
594
|
-
// `isError` automatically — no need to mirror it inside
|
|
595
|
-
// `structuredContent`.
|
|
596
|
-
return {
|
|
597
|
-
...agenticResult,
|
|
598
|
-
structuredContent: wrappedStructured,
|
|
599
|
-
};
|
|
600
|
-
}
|
|
601
|
-
const attachmentsNote = attachments.attached.length > 0
|
|
602
|
-
? ' — it carries no attachments: drop them, or narrow the workspace and ask again'
|
|
603
|
-
: '';
|
|
604
|
-
return errorResult(`Workspace too large: ~${preflight.effectiveTokens.toLocaleString()} input tokens (${preflight.method} count) 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)${attachmentsNote}. Or set \`onWorkspaceTooLarge: 'fallback-to-agentic'\` on \`ask\` to have the server route automatically. 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.`, {
|
|
605
|
-
errorCode: 'WORKSPACE_TOO_LARGE',
|
|
606
|
-
serviceTier,
|
|
607
|
-
...attachmentMetadata(attachments),
|
|
608
|
-
retryable: false,
|
|
609
|
-
estimatedInputTokens: preflight.effectiveTokens,
|
|
610
|
-
tokenCountMethod: preflight.method,
|
|
611
|
-
rawTokenCount: preflight.rawTokens,
|
|
612
|
-
tokenCountCacheHit: preflight.cacheHit,
|
|
613
|
-
contextWindowTokens: contextWindow,
|
|
614
|
-
thresholdTokens: threshold,
|
|
615
|
-
guardRatio: ctx.config.workspaceGuardRatio,
|
|
616
|
-
resolvedModel: resolved.resolved,
|
|
617
|
-
filesIndexed: scan.files.length,
|
|
618
|
-
});
|
|
619
|
-
}
|
|
620
|
-
}
|
|
621
|
-
else {
|
|
622
|
-
logger.warn(`ask: resolved model ${safeForLog(resolved.resolved)} has no advertised inputTokenLimit — workspace size guard skipped. Request may fail downstream if the workspace exceeds the model's context window.`);
|
|
623
|
-
}
|
|
624
|
-
const { cap: runCap, cut: inputWindowCut } = capThatRuns({
|
|
625
|
-
tool: 'ask',
|
|
626
|
-
cap: outputCap,
|
|
627
|
-
promptTokens: preflight?.effectiveTokens,
|
|
628
|
-
inputTokenLimit: contextWindow,
|
|
629
|
-
emit: (message) => emitter.emit(message),
|
|
630
|
-
});
|
|
631
|
-
// Normalise thinkingBudget:
|
|
632
|
-
// undefined → null (model-default path — `thinkingBudget` OMITTED on wire)
|
|
633
|
-
// -1 → -1 (explicit legacy dynamic; kept for Gemini 2.5 and
|
|
634
|
-
// power-users who want to force the legacy path)
|
|
635
|
-
// 0 → 0 (thinking disabled; Gemini 3 Pro will 400 here)
|
|
636
|
-
// N > 0 → clamp to [0, cap that runs - 1024] — the thinking
|
|
637
|
-
// pool is carved out of the candidate-output allowance,
|
|
638
|
-
// so reserving ≥1024 tokens for the answer prevents 400s
|
|
639
|
-
// when a caller passes N ≥ maxOutputTokens, and under a
|
|
640
|
-
// cap the input window cut to one request (its value on
|
|
641
|
-
// the wire) the budget stays below it.
|
|
642
|
-
//
|
|
643
|
-
// Schema `.refine()` guarantees `thinkingBudget` and `thinkingLevel`
|
|
644
|
-
// are never both set, so we handle them in two mutually-exclusive
|
|
645
|
-
// branches below.
|
|
646
|
-
const rawThinkingBudget = input.thinkingBudget;
|
|
647
|
-
const effectiveThinkingBudget = rawThinkingBudget === undefined
|
|
648
|
-
? THINKING_BUDGET_MODEL_DEFAULT
|
|
649
|
-
: rawThinkingBudget === -1
|
|
650
|
-
? -1
|
|
651
|
-
: rawThinkingBudget > 0
|
|
652
|
-
? thinkingBudgetUnder(runCap, rawThinkingBudget)
|
|
653
|
-
: 0;
|
|
654
|
-
// The thinking the budget reservation counts, from the cap that runs.
|
|
655
|
-
const thinkingTokensForEstimate = thinkingReserve(input.thinkingLevel, effectiveThinkingBudget, runCap);
|
|
656
|
-
// Atomic budget reservation. Happens AFTER scan (so the estimate is
|
|
657
|
-
// accurate) but BEFORE any billable upload or generateContent call.
|
|
658
|
-
// Concurrent tool calls cannot all pass a pre-check and then
|
|
659
|
-
// collectively overshoot the cap: `reserveBudget` uses a
|
|
660
|
-
// `BEGIN IMMEDIATE` SQLite transaction that serialises check-and-insert.
|
|
661
|
-
if (Number.isFinite(ctx.config.dailyBudgetUsd)) {
|
|
662
|
-
const estimateUsd = estimatePreCallCostUsd({
|
|
663
|
-
model: resolved.resolved,
|
|
664
|
-
serviceTier,
|
|
665
|
-
extraInputTokens: attachmentTokens,
|
|
666
|
-
workspaceBytes,
|
|
667
|
-
promptChars: input.prompt.length,
|
|
668
|
-
// Budget reservation uses the effective cap (explicit-user-cap
|
|
669
|
-
// OR model's full limit) as `expectedOutputTokens` — a TRUE
|
|
670
|
-
// upper bound, since Gemini's default stops at the model's
|
|
671
|
-
// advertised `outputTokenLimit`.
|
|
672
|
-
expectedOutputTokens: runCap.effective,
|
|
673
|
-
// A cap above the per-request limit (long decode) adds the input every continuation request bills again.
|
|
674
|
-
perRequestOutputTokens: runCap.perRequest,
|
|
675
|
-
// The preflight's count, when it ran: the reservation takes the larger of it and the bytes/4 heuristic.
|
|
676
|
-
countedInputTokens: preflight?.effectiveTokens,
|
|
677
|
-
thinkingTokens: thinkingTokensForEstimate,
|
|
678
|
-
coverMs: timeoutController.timeoutMs,
|
|
679
|
-
});
|
|
680
|
-
const reserve = ctx.manifest.reserveBudget({
|
|
681
|
-
workspaceRoot,
|
|
682
|
-
toolName: 'ask',
|
|
683
|
-
model: resolved.resolved,
|
|
684
|
-
estimatedCostMicros: toMicrosUsd(estimateUsd),
|
|
685
|
-
dailyBudgetMicros: toMicrosUsd(ctx.config.dailyBudgetUsd),
|
|
686
|
-
nowMs: Date.now(),
|
|
687
|
-
});
|
|
688
|
-
if ('rejected' in reserve) {
|
|
689
|
-
const spentUsd = reserve.spentMicros / 1_000_000;
|
|
690
|
-
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, serviceTier });
|
|
691
|
-
}
|
|
692
|
-
reservationId = reserve.id;
|
|
693
|
-
}
|
|
694
|
-
const systemPromptHash = createHash('sha256')
|
|
695
|
-
.update(SYSTEM_INSTRUCTION_Q_AND_A)
|
|
696
|
-
.digest('hex')
|
|
697
|
-
.slice(0, 16);
|
|
698
|
-
// v1.14.0 — `cachingMode` default flipped to `'implicit'`: Gemini 2.5+/3
|
|
699
|
-
// Pro applies its automatic implicit caching to repeated workspace prefixes,
|
|
700
|
-
// eliminating the 60–180 s `caches.create` rebuild wait on the
|
|
701
|
-
// review→edit→review path. Per-call `input.cachingMode` always wins;
|
|
702
|
-
// env-level override `GEMINI_CODE_CONTEXT_CACHING_MODE` lets operators force
|
|
703
|
-
// `'explicit'` when they need predictable per-call billing more than
|
|
704
|
-
// warm-path speed. Telemetry on the actual mode (vs requested) is computed
|
|
705
|
-
// AFTER `prepareContext` returns from `activePrep.inlineOnly` — see FN2 fix.
|
|
706
|
-
const caching = cachingModeFor(input.cachingMode ?? ctx.config.cachingMode, resolved, emitter);
|
|
707
|
-
const requestedCachingMode = caching.mode;
|
|
708
|
-
// The context of the call: built here, and again by the stale-cache retry on a fresh cache.
|
|
709
|
-
const prepare = () => prepareContext({
|
|
710
|
-
client: ctx.client,
|
|
711
|
-
manifest: ctx.manifest,
|
|
712
|
-
scan,
|
|
713
|
-
model: resolved,
|
|
714
|
-
systemPromptHash,
|
|
715
|
-
systemInstruction: SYSTEM_INSTRUCTION_Q_AND_A,
|
|
716
|
-
ttlSeconds: ctx.config.cacheTtlSeconds,
|
|
717
|
-
cacheMinTokens: ctx.config.cacheMinTokens,
|
|
718
|
-
emitter,
|
|
719
|
-
allowCaching: !input.noCache && scan.files.length > 0,
|
|
720
|
-
// v1.12.1 — let `timeoutMs` interrupt the upload phase too.
|
|
721
|
-
signal: abortSignal,
|
|
722
|
-
// v1.13.0 — opt-in implicit caching path (skip caches.create).
|
|
723
|
-
cachingMode: requestedCachingMode,
|
|
724
|
-
});
|
|
725
|
-
const ctxPrep = await prepare();
|
|
726
|
-
emitter.emit(usingThinkingLevel
|
|
727
|
-
? `generating response (thinking-level=${input.thinkingLevel})…`
|
|
728
|
-
: effectiveThinkingBudget === null
|
|
729
|
-
? 'generating response (thinking=model-default)…'
|
|
730
|
-
: effectiveThinkingBudget === -1
|
|
731
|
-
? 'generating response (thinking=dynamic)…'
|
|
732
|
-
: `generating response (thinking=${effectiveThinkingBudget})…`);
|
|
733
|
-
// Gemini rejects `generateContent({cachedContent, systemInstruction})` with 400:
|
|
734
|
-
// "CachedContent can not be used with GenerateContent request setting
|
|
735
|
-
// system_instruction, tools or tool_config. Move those values to CachedContent."
|
|
736
|
-
// The system instruction was already baked into the cache at build time
|
|
737
|
-
// (see cache-manager.ts:322 `cacheConfig.systemInstruction`), so we must
|
|
738
|
-
// OMIT it on the generate call when a cached context is active.
|
|
739
|
-
// `thinkingConfig` is NOT one of the forbidden fields — it is a
|
|
740
|
-
// per-request reasoning control and travels with every call regardless
|
|
741
|
-
// of cache state. We always set `includeThoughts: true` so callers see
|
|
742
|
-
// Gemini's reasoning digest in the response.
|
|
743
|
-
//
|
|
744
|
-
// Three mutually-exclusive reasoning-control paths (enforced by
|
|
745
|
-
// schema `.refine()`):
|
|
746
|
-
// a) `thinkingLevel` set → pass it through to the SDK enum. Google's
|
|
747
|
-
// recommended path on Gemini 3. Rejected by Gemini 2.5 family.
|
|
748
|
-
// b) `thinkingBudget` set (non-null after normalisation) → legacy
|
|
749
|
-
// budget path. Required on Gemini 2.5; flagged as "legacy" on
|
|
750
|
-
// Gemini 3 but still supported.
|
|
751
|
-
// c) neither set → omit both fields, keep only `includeThoughts`.
|
|
752
|
-
// Model uses its native default (HIGH-dynamic on Gemini 3 Pro).
|
|
753
|
-
//
|
|
754
|
-
// `maxOutputTokens` is only passed on the wire when the caller set
|
|
755
|
-
// `input.maxOutputTokens` — otherwise we omit it and Gemini uses
|
|
756
|
-
// its model-default cap (per docs, = the model's advertised
|
|
757
|
-
// `outputTokenLimit`, currently 65,536 for pro-tier 3.x/2.5). Budget
|
|
758
|
-
// reservation always uses the cap the decode runs under (explicit cap
|
|
759
|
-
// OR model limit, cut by the input window on a long decode) as the
|
|
760
|
-
// worst-case upper bound, so the daily cap stays a true ceiling.
|
|
761
|
-
// Cast to `ThinkingLevel` rather than indexing the runtime enum object
|
|
762
|
-
// (`ThinkingLevel[input.thinkingLevel]`). For string enums the value
|
|
763
|
-
// IS the member name, so passing `"HIGH"` as `ThinkingLevel` is
|
|
764
|
-
// semantically identical at runtime — but it survives SDK renames:
|
|
765
|
-
// if a future `@google/genai` release renames a member, the literal
|
|
766
|
-
// string reaches Gemini's wire, which 400s with a clear message
|
|
767
|
-
// instead of silently becoming `undefined` at the indexing step.
|
|
768
|
-
const thinkingConfig = usingThinkingLevel
|
|
769
|
-
? {
|
|
770
|
-
thinkingLevel: input.thinkingLevel,
|
|
771
|
-
includeThoughts: true,
|
|
772
|
-
}
|
|
773
|
-
: effectiveThinkingBudget === null
|
|
774
|
-
? { includeThoughts: true }
|
|
775
|
-
: { thinkingBudget: effectiveThinkingBudget, includeThoughts: true };
|
|
776
|
-
const tierField = serviceTierConfig(serviceTier);
|
|
777
|
-
const buildConfig = (cacheId) => {
|
|
778
|
-
const maxOutputField = runCap.wire !== undefined ? { maxOutputTokens: runCap.wire } : {};
|
|
779
|
-
return cacheId
|
|
780
|
-
? { cachedContent: cacheId, thinkingConfig, ...maxOutputField, ...tierField }
|
|
781
|
-
: {
|
|
782
|
-
systemInstruction: SYSTEM_INSTRUCTION_Q_AND_A,
|
|
783
|
-
thinkingConfig,
|
|
784
|
-
...maxOutputField,
|
|
785
|
-
...tierField,
|
|
786
|
-
};
|
|
787
|
-
};
|
|
788
|
-
// The user turn: the attachments first, the question last; with a cache the turn still carries the parts.
|
|
789
|
-
const userTurn = {
|
|
790
|
-
role: 'user',
|
|
791
|
-
parts: [...attachments.parts, { text: input.prompt }],
|
|
792
|
-
};
|
|
793
|
-
const buildContents = (cacheId, inline) => {
|
|
794
|
-
if (cacheId)
|
|
795
|
-
return attachments.parts.length === 0 ? input.prompt : [userTurn];
|
|
796
|
-
return [...inline, userTurn];
|
|
797
|
-
};
|
|
798
|
-
// The decode — and, on a stale cache before any request completed, its one retry on a rebuilt cache. The TPM
|
|
799
|
-
// reservation is taken here, after `prepareContext` and immediately before the first request, so its timestamp
|
|
800
|
-
// is when the tokens reach Gemini's quota counter; only the OPENING of a request is retried (a mid-stream
|
|
801
|
-
// failure re-sent would bill the work again).
|
|
802
|
-
const decoded = await decodeOnContext({
|
|
803
|
-
client: ctx.client,
|
|
804
|
-
booking: { workspaceRoot, toolName: 'ask', model: resolved.resolved, serviceTier },
|
|
805
|
-
cachingMode: (prep) => cachingRan(prep, caching).mode,
|
|
806
|
-
request: (prep) => ({
|
|
807
|
-
contents: buildContents(prep.cacheId, prep.inlineContents),
|
|
808
|
-
config: buildConfig(prep.cacheId),
|
|
809
|
-
}),
|
|
810
|
-
cache: {
|
|
811
|
-
ttlWatcher: ctx.ttlWatcher,
|
|
812
|
-
manifest: ctx.manifest,
|
|
813
|
-
ttlSeconds: ctx.config.cacheTtlSeconds,
|
|
814
|
-
prepare,
|
|
815
|
-
},
|
|
816
|
-
openAttempts: networkAttempts(serviceTier), // a flex request is never re-sent
|
|
817
|
-
limits: { maxRequests: runCap.maxRequests, cap: runCap.effective },
|
|
818
|
-
timeout: timeoutController,
|
|
819
|
-
emit: (message) => emitter.emit(message),
|
|
820
|
-
completed,
|
|
821
|
-
tracking,
|
|
822
|
-
throttle: dispatch,
|
|
823
|
-
inputTokens: { estimated: estimatedInputTokens, counted: preflight?.effectiveTokens },
|
|
824
|
-
}, ctxPrep);
|
|
825
|
-
const { response, prep: activePrep, retriedOnStaleCache } = decoded;
|
|
826
|
-
const text = response.text;
|
|
827
|
-
// `collectStream` already aggregated thought-flagged parts and capped
|
|
828
|
-
// the joined summary at 1200 chars (T20). Reuse directly — re-iterating
|
|
829
|
-
// `response.candidates` would risk drift between in-flight thought
|
|
830
|
-
// emit (live progress) and post-call summary.
|
|
831
|
-
const thinkingSummary = response.thoughtsSummary;
|
|
832
|
-
// Telemetry and the response record the mode that ran, not the one asked for.
|
|
833
|
-
const ran = cachingRan(activePrep, caching);
|
|
834
|
-
const effectiveCachingMode = ran.mode;
|
|
835
|
-
const durationMs = Date.now() - started;
|
|
836
|
-
// Settled here, once: the outer catch then neither releases the reservation nor books the call again. What the
|
|
837
|
-
// API billed is every request that completed, over a long decode and a stale-cache retry alike.
|
|
838
|
-
const settledReservation = reservationId;
|
|
839
|
-
reservationId = null;
|
|
840
|
-
tracking.ledgerEntry = null;
|
|
841
|
-
const settled = settleAnswer({
|
|
842
|
-
manifest: ctx.manifest,
|
|
843
|
-
reservationId: settledReservation,
|
|
844
|
-
entry: {
|
|
845
|
-
workspaceRoot,
|
|
846
|
-
toolName: 'ask',
|
|
847
|
-
model: resolved.resolved,
|
|
848
|
-
serviceTier,
|
|
849
|
-
cachingMode: effectiveCachingMode,
|
|
850
|
-
},
|
|
851
|
-
completed,
|
|
852
|
-
response,
|
|
853
|
-
cap: runCap,
|
|
854
|
-
cut: inputWindowCut,
|
|
855
|
-
durationMs,
|
|
856
|
-
});
|
|
857
|
-
const finish = settled.finish;
|
|
858
|
-
// Settled and billed above; an empty answer at the cap is a failure the caller can act on, never a success.
|
|
859
|
-
if (settled.outputCapStop !== null) {
|
|
860
|
-
return errorResult(`ask: ${settled.outputCapStop.message}`, settled.outputCapStop.fields);
|
|
861
|
-
}
|
|
862
|
-
if (scan.truncated) {
|
|
863
|
-
logger.warn(`workspace ${workspaceRoot} contains more files than GEMINI_CODE_CONTEXT_MAX_FILES (${ctx.config.maxFilesPerWorkspace}); the tail was dropped before indexing.`);
|
|
864
|
-
}
|
|
865
|
-
const metadata = {
|
|
866
|
-
resolvedModel: resolved.resolved,
|
|
867
|
-
requestedModel: resolved.requested,
|
|
868
|
-
serviceTier,
|
|
869
|
-
...attachmentMetadata(attachments),
|
|
870
|
-
fallbackApplied: resolved.fallbackApplied,
|
|
871
|
-
modelCategory: resolved.category,
|
|
872
|
-
modelCostTier: resolved.capabilities.costTier,
|
|
873
|
-
contextWindow: resolved.inputTokenLimit,
|
|
874
|
-
thinkingBudget: effectiveThinkingBudget,
|
|
875
|
-
thinkingLevel: input.thinkingLevel ?? null,
|
|
876
|
-
...settled.usage,
|
|
877
|
-
...settled.cutFields,
|
|
878
|
-
// `truncated`: the answer stopped at the output cap (MAX_TOKENS, or a long decode at its limits) — it is cut
|
|
879
|
-
finishReason: finish.finishReason,
|
|
880
|
-
truncated: finish.truncated,
|
|
881
|
-
cacheHit: activePrep.reused,
|
|
882
|
-
cacheRebuilt: activePrep.rebuilt || retriedOnStaleCache,
|
|
883
|
-
retriedOnStaleCache,
|
|
884
|
-
inlineOnly: activePrep.inlineOnly,
|
|
885
|
-
cachingMode: effectiveCachingMode,
|
|
886
|
-
...(ran.note !== null ? { cachingModeNote: ran.note } : {}),
|
|
887
|
-
filesIndexed: scan.files.length,
|
|
888
|
-
filesSkippedTooLarge: scan.skippedTooLarge,
|
|
889
|
-
// v1.21.0+: what the scan left out — the excluded directories it met and the files that are neither source by
|
|
890
|
-
// extension nor a `#!` script — so a caller can tell "not in the workspace" from "not indexed".
|
|
891
|
-
excludedDirs: scan.excludedDirs,
|
|
892
|
-
excludedDirsTotal: scan.excludedDirsTotal,
|
|
893
|
-
filesSkippedNonSource: scan.skippedNonSource,
|
|
894
|
-
filesUploadFailed: activePrep.uploaded.failedCount,
|
|
895
|
-
...(activePrep.uploaded.failedCount > 0
|
|
896
|
-
? { uploadFailures: activePrep.uploaded.failures.slice(0, 5) }
|
|
897
|
-
: {}),
|
|
898
|
-
workspaceTruncated: scan.truncated,
|
|
899
|
-
maxFilesCap: ctx.config.maxFilesPerWorkspace,
|
|
900
|
-
// Preflight token-count provenance — surfaces on every successful
|
|
901
|
-
// call so orchestrators / observability layers can see which path
|
|
902
|
-
// produced the count (`'heuristic'`, `'exact'`, `'fallback'`),
|
|
903
|
-
// whether the LRU saved an API round-trip, and the raw count
|
|
904
|
-
// before `SYSTEM_INSTRUCTION_RESERVE` was applied. Omitted when
|
|
905
|
-
// the resolved model had no `inputTokenLimit` (preflight skipped).
|
|
906
|
-
...(preflight !== undefined
|
|
907
|
-
? {
|
|
908
|
-
tokenCountMethod: preflight.method,
|
|
909
|
-
rawTokenCount: preflight.rawTokens,
|
|
910
|
-
tokenCountCacheHit: preflight.cacheHit,
|
|
911
|
-
}
|
|
912
|
-
: {}),
|
|
913
|
-
durationMs,
|
|
914
|
-
...(thinkingSummary ? { thinkingSummary } : {}),
|
|
915
|
-
};
|
|
916
|
-
return textResult(text, metadata);
|
|
47
|
+
const refusal = workspaceRefusal('ask', workspaceRoot);
|
|
48
|
+
if (refusal !== null)
|
|
49
|
+
return refusal;
|
|
50
|
+
const resolved = await resolveAsk({ input, ctx, model, eager });
|
|
51
|
+
if ('end' in resolved)
|
|
52
|
+
return resolved.end;
|
|
53
|
+
const attached = await attachAsk(resolved.next);
|
|
54
|
+
if ('end' in attached)
|
|
55
|
+
return attached.end;
|
|
56
|
+
const scanned = await scanAsk(attached.next);
|
|
57
|
+
if ('end' in scanned)
|
|
58
|
+
return scanned.end;
|
|
59
|
+
const counted = await guardAsk(scanned.next);
|
|
60
|
+
if ('handOff' in counted)
|
|
61
|
+
return counted.handOff;
|
|
62
|
+
if ('end' in counted)
|
|
63
|
+
return counted.end;
|
|
64
|
+
const sized = sizeAsk(counted.next);
|
|
65
|
+
if ('end' in sized)
|
|
66
|
+
return sized.end;
|
|
67
|
+
return await answerAsk(sized.next);
|
|
917
68
|
}
|
|
918
69
|
catch (err) {
|
|
919
|
-
|
|
920
|
-
// A 429's retry hint seeds the throttle; the ledger keeps what the completed requests billed and releases the rest
|
|
921
|
-
// of the reservation (all of it when none completed); their usage goes into the error result.
|
|
922
|
-
const failedUsage = settleFailure({
|
|
923
|
-
manifest: ctx.manifest,
|
|
924
|
-
failed: {
|
|
925
|
-
toolName: 'ask',
|
|
926
|
-
reservationId,
|
|
927
|
-
entry: tracking.ledgerEntry,
|
|
928
|
-
completed,
|
|
929
|
-
durationMs: Date.now() - started,
|
|
930
|
-
},
|
|
931
|
-
err,
|
|
932
|
-
model: resolvedModelKey,
|
|
933
|
-
throttle: ctx.throttle,
|
|
934
|
-
dispatch,
|
|
935
|
-
});
|
|
936
|
-
reservationId = null;
|
|
937
|
-
// Timeout-driven abort gets a dedicated errorCode so callers can
|
|
938
|
-
// distinguish "Gemini was slow" from "schema invalid" / "auth failed".
|
|
939
|
-
// v1.12.0 — `timeoutKind` ('total' | 'stall') distinguishes the
|
|
940
|
-
// wall-clock cap from the heartbeat-aware stall watchdog so callers
|
|
941
|
-
// can apply different policies (e.g. retry on stall but not on total).
|
|
942
|
-
if (isTimeoutAbort(err)) {
|
|
943
|
-
const ms = timeoutController.timeoutMs;
|
|
944
|
-
const stallMs = timeoutController.stallMs;
|
|
945
|
-
const kind = getTimeoutKind(err);
|
|
946
|
-
const limitMs = kind === 'stall' ? stallMs : ms;
|
|
947
|
-
emitter.emit(`ask: aborted after ${limitMs ?? '?'}ms ${kind ?? 'timeout'}`);
|
|
948
|
-
const message = kind === 'stall'
|
|
949
|
-
? `ask timed out — no chunk received for ${stallMs ?? '?'}ms (stall watchdog). Increase \`stallMs\` per call or set \`GEMINI_CODE_CONTEXT_ASK_STALL_MS\` higher; default disabled. Stall watchdog is heartbeat-aware — it does NOT fire while the model is streaming chunks. A fired stall is usually a dead socket or a server-side hang. Note: AbortSignal is client-only — Gemini still finishes server-side and bills for completed work.`
|
|
950
|
-
: `ask timed out after ${ms ?? '?'}ms (total wall-clock). Increase \`timeoutMs\` per call or set \`GEMINI_CODE_CONTEXT_ASK_TIMEOUT_MS\` higher; default disabled. Consider \`stallMs\` instead — a heartbeat-aware watchdog that does NOT fire while the model is actively thinking. Note: AbortSignal is client-only — Gemini still finishes server-side and bills for completed work.`;
|
|
951
|
-
return errorResult(message, {
|
|
952
|
-
errorCode: 'TIMEOUT',
|
|
953
|
-
timeoutKind: kind ?? 'total',
|
|
954
|
-
timeoutMs: ms,
|
|
955
|
-
stallMs,
|
|
956
|
-
retryable: true,
|
|
957
|
-
serviceTier: reportedTier(),
|
|
958
|
-
...failedUsage,
|
|
959
|
-
});
|
|
960
|
-
}
|
|
961
|
-
const httpStatus = statusOf(err);
|
|
962
|
-
return errorResult(`ask failed: ${err instanceof Error ? err.message : String(err)}`, {
|
|
963
|
-
...tierErrorMeta(err, tracking.streamOpened),
|
|
964
|
-
serviceTier: reportedTier(),
|
|
965
|
-
...(httpStatus !== undefined ? { httpStatus } : {}),
|
|
966
|
-
...failedUsage,
|
|
967
|
-
});
|
|
70
|
+
return failedResult(settleFailedEager(eager, ctx, err));
|
|
968
71
|
}
|
|
969
72
|
finally {
|
|
970
|
-
|
|
971
|
-
emitter.stop();
|
|
73
|
+
closeEagerCall(eager);
|
|
972
74
|
}
|
|
973
75
|
}
|
|
974
76
|
//# sourceMappingURL=ask.tool.js.map
|