@qmediat.io/gemini-code-context-mcp 1.25.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.
Files changed (107) hide show
  1. package/CHANGELOG.md +21 -1
  2. package/README.md +1 -1
  3. package/dist/cache/cache-manager.d.ts +23 -34
  4. package/dist/cache/cache-manager.d.ts.map +1 -1
  5. package/dist/cache/cache-manager.js +324 -272
  6. package/dist/cache/cache-manager.js.map +1 -1
  7. package/dist/cache/caching-mode.d.ts +5 -3
  8. package/dist/cache/caching-mode.d.ts.map +1 -1
  9. package/dist/cache/caching-mode.js +6 -4
  10. package/dist/cache/caching-mode.js.map +1 -1
  11. package/dist/cache/ttl-watcher.d.ts.map +1 -1
  12. package/dist/cache/ttl-watcher.js +7 -1
  13. package/dist/cache/ttl-watcher.js.map +1 -1
  14. package/dist/cache/ttl.d.ts +8 -0
  15. package/dist/cache/ttl.d.ts.map +1 -0
  16. package/dist/cache/ttl.js +10 -0
  17. package/dist/cache/ttl.js.map +1 -0
  18. package/dist/manifest/db.d.ts.map +1 -1
  19. package/dist/manifest/db.js +2 -1
  20. package/dist/manifest/db.js.map +1 -1
  21. package/dist/tools/agentic/run.d.ts.map +1 -1
  22. package/dist/tools/agentic/run.js +3 -6
  23. package/dist/tools/agentic/run.js.map +1 -1
  24. package/dist/tools/ask/answer.d.ts +9 -0
  25. package/dist/tools/ask/answer.d.ts.map +1 -0
  26. package/dist/tools/ask/answer.js +28 -0
  27. package/dist/tools/ask/answer.js.map +1 -0
  28. package/dist/tools/ask/attachments.d.ts +25 -0
  29. package/dist/tools/ask/attachments.d.ts.map +1 -0
  30. package/dist/tools/ask/attachments.js +85 -0
  31. package/dist/tools/ask/attachments.js.map +1 -0
  32. package/dist/tools/ask/call.d.ts +61 -0
  33. package/dist/tools/ask/call.d.ts.map +1 -0
  34. package/dist/tools/ask/call.js +6 -0
  35. package/dist/tools/ask/call.js.map +1 -0
  36. package/dist/tools/ask/guard.d.ts +24 -0
  37. package/dist/tools/ask/guard.d.ts.map +1 -0
  38. package/dist/tools/ask/guard.js +79 -0
  39. package/dist/tools/ask/guard.js.map +1 -0
  40. package/dist/tools/ask/input.d.ts +45 -0
  41. package/dist/tools/ask/input.d.ts.map +1 -0
  42. package/dist/tools/ask/input.js +93 -0
  43. package/dist/tools/ask/input.js.map +1 -0
  44. package/dist/tools/ask/instruction.d.ts +8 -0
  45. package/dist/tools/ask/instruction.d.ts.map +1 -0
  46. package/dist/tools/ask/instruction.js +13 -0
  47. package/dist/tools/ask/instruction.js.map +1 -0
  48. package/dist/tools/ask/request.d.ts +14 -0
  49. package/dist/tools/ask/request.d.ts.map +1 -0
  50. package/dist/tools/ask/request.js +38 -0
  51. package/dist/tools/ask/request.js.map +1 -0
  52. package/dist/tools/ask/results.d.ts +23 -0
  53. package/dist/tools/ask/results.d.ts.map +1 -0
  54. package/dist/tools/ask/results.js +107 -0
  55. package/dist/tools/ask/results.js.map +1 -0
  56. package/dist/tools/ask/setup.d.ts +22 -0
  57. package/dist/tools/ask/setup.d.ts.map +1 -0
  58. package/dist/tools/ask/setup.js +57 -0
  59. package/dist/tools/ask/setup.js.map +1 -0
  60. package/dist/tools/ask/sizing.d.ts +10 -0
  61. package/dist/tools/ask/sizing.d.ts.map +1 -0
  62. package/dist/tools/ask/sizing.js +33 -0
  63. package/dist/tools/ask/sizing.js.map +1 -0
  64. package/dist/tools/ask/thinking.d.ts +54 -0
  65. package/dist/tools/ask/thinking.d.ts.map +1 -0
  66. package/dist/tools/ask/thinking.js +69 -0
  67. package/dist/tools/ask/thinking.js.map +1 -0
  68. package/dist/tools/ask-agentic-fallback.d.ts +1 -1
  69. package/dist/tools/ask-agentic-fallback.d.ts.map +1 -1
  70. package/dist/tools/ask-agentic.tool.d.ts.map +1 -1
  71. package/dist/tools/ask-agentic.tool.js +4 -10
  72. package/dist/tools/ask-agentic.tool.js.map +1 -1
  73. package/dist/tools/ask.tool.d.ts +3 -41
  74. package/dist/tools/ask.tool.d.ts.map +1 -1
  75. package/dist/tools/ask.tool.js +46 -795
  76. package/dist/tools/ask.tool.js.map +1 -1
  77. package/dist/tools/code.tool.d.ts.map +1 -1
  78. package/dist/tools/code.tool.js +375 -502
  79. package/dist/tools/code.tool.js.map +1 -1
  80. package/dist/tools/reindex.tool.d.ts.map +1 -1
  81. package/dist/tools/reindex.tool.js +19 -22
  82. package/dist/tools/reindex.tool.js.map +1 -1
  83. package/dist/tools/shared/eager-answer.d.ts +78 -0
  84. package/dist/tools/shared/eager-answer.d.ts.map +1 -0
  85. package/dist/tools/shared/eager-answer.js +130 -0
  86. package/dist/tools/shared/eager-answer.js.map +1 -0
  87. package/dist/tools/shared/eager-call.d.ts +114 -0
  88. package/dist/tools/shared/eager-call.d.ts.map +1 -0
  89. package/dist/tools/shared/eager-call.js +95 -0
  90. package/dist/tools/shared/eager-call.js.map +1 -0
  91. package/dist/tools/shared/eager-steps.d.ts +114 -0
  92. package/dist/tools/shared/eager-steps.d.ts.map +1 -0
  93. package/dist/tools/shared/eager-steps.js +152 -0
  94. package/dist/tools/shared/eager-steps.js.map +1 -0
  95. package/dist/tools/shared/service-tier.d.ts +9 -0
  96. package/dist/tools/shared/service-tier.d.ts.map +1 -1
  97. package/dist/tools/shared/service-tier.js +15 -0
  98. package/dist/tools/shared/service-tier.js.map +1 -1
  99. package/dist/tools/shared/thinking.d.ts +9 -0
  100. package/dist/tools/shared/thinking.d.ts.map +1 -1
  101. package/dist/tools/shared/thinking.js +10 -0
  102. package/dist/tools/shared/thinking.js.map +1 -1
  103. package/dist/tools/shared/workspace-refusal.d.ts +13 -0
  104. package/dist/tools/shared/workspace-refusal.d.ts.map +1 -0
  105. package/dist/tools/shared/workspace-refusal.js +23 -0
  106. package/dist/tools/shared/workspace-refusal.js.map +1 -0
  107. package/package.json +1 -1
@@ -2,9 +2,9 @@
2
2
  * Build / reuse / invalidate Gemini Context Caches keyed by workspace state.
3
3
  *
4
4
  * Cache key = `(workspaceRoot, filesHash, model, systemPromptHash)`. When any
5
- * component changes, we rebuild. When the same key is requested concurrently
6
- * (two ask() calls in parallel), we coalesce via a per-workspace in-process
7
- * mutex so only one cache is created.
5
+ * component changes, we rebuild. Concurrent calls with the same whole call
6
+ * fingerprint (`inFlightKey`: the cache key plus the caching options) coalesce
7
+ * onto one in-process build, so only one cache is created for them.
8
8
  *
9
9
  * Inline fallback path: for small workspaces or `noCache:true`, we skip the
10
10
  * Files API upload entirely and embed file text inline. This avoids unnecessary
@@ -20,16 +20,14 @@
20
20
  import { readFile } from 'node:fs/promises';
21
21
  import { logger, safeForLog } from '../utils/logger.js';
22
22
  import { uploadWorkspaceFiles } from './files-uploader.js';
23
- function ttlString(seconds) {
24
- return `${Math.max(60, Math.floor(seconds))}s`;
25
- }
23
+ import { effectiveTtlSeconds } from './ttl.js';
26
24
  /**
27
25
  * Convert whatever identifier we stored in `files.file_id` back to the
28
26
  * `files/<id>` resource name that `client.files.delete` expects.
29
27
  *
30
28
  * The uploader stores `.uri` in preference to `.name` (see
31
- * `src/cache/files-uploader.ts:170-176` — `fileData.fileUri` at cache build
32
- * time rejects the bare `files/abc` form). But the `files.delete` endpoint
29
+ * `uploadWorkspaceFiles` in `files-uploader.ts` — `fileData.fileUri` at cache
30
+ * build time rejects the bare `files/abc` form). But the `files.delete` endpoint
33
31
  * takes the resource-name form, so we need the reverse transform on
34
32
  * teardown. The URI looks like
35
33
  * `https://generativelanguage.googleapis.com/v1beta/files/abc123-xyz`;
@@ -79,7 +77,7 @@ function isUsableExistingCache(ws, scan, model, systemPromptHash, now) {
79
77
  function buildContentFromUploaded(files) {
80
78
  const parts = [];
81
79
  for (const f of files) {
82
- if (typeof f.fileId !== 'string' || f.fileId.length === 0)
80
+ if (!isFileId(f.fileId))
83
81
  continue;
84
82
  parts.push({ text: `\n\n--- FILE: ${f.relpath} ---\n` });
85
83
  parts.push({
@@ -107,9 +105,8 @@ function buildContentFromUploaded(files) {
107
105
  */
108
106
  const MAX_INLINE_TOTAL_BYTES = 20 * 1024 * 1024; // 20 MB aggregate inline content
109
107
  /**
110
- * v1.13.0 post-review fix: seed the scan memo from a ScanResult on the
111
- * inline-return paths (`!allowCaching`, `cachingMode: 'implicit'`,
112
- * small-workspace). The uploader is the only OTHER writer of the memo
108
+ * Seeds the scan memo from a ScanResult on the inline-return paths
109
+ * (`!allowCaching`, `cachingMode: 'implicit'`, small-workspace). The uploader is the only OTHER writer of the memo
113
110
  * columns; on these paths the uploader is skipped, so without this seed
114
111
  * the memo Map next call comes back empty and every file re-hashes.
115
112
  *
@@ -158,7 +155,7 @@ async function buildInlineContentFromDisk(scan) {
158
155
  return [{ role: 'user', parts }];
159
156
  }
160
157
  /**
161
- * In-process mutex. Concurrent `prepareContext` calls for the SAME
158
+ * In-process coalescing. Concurrent `prepareContext` calls for the SAME
162
159
  * `(workspaceRoot, filesHash, model, systemPromptHash, allowCaching,
163
160
  * cacheMinTokens, cachingMode)` fingerprint coalesce onto a single
164
161
  * in-flight promise, avoiding duplicate cache creation (which would leak
@@ -167,14 +164,8 @@ async function buildInlineContentFromDisk(scan) {
167
164
  * Keying on the full fingerprint is critical: `ask` and `code` tools use
168
165
  * different system instructions, so their `systemPromptHash` differs. Coalescing
169
166
  * on workspaceRoot alone would serve one tool's PreparedContext to the other —
170
- * wrong cache / system-instruction mismatch. This bug was flagged by GPT + Copilot.
171
- *
172
- * v1.14.0 round-1 added `cachingMode` to the fingerprint after Copilot
173
- * caught a HIGH concurrency race (`/6step` F1): pre-fix, two concurrent
174
- * calls with different `cachingMode` values produced identical keys, sharing
175
- * one PreparedContext between them. v1.14.0's default flip transformed this
176
- * from a niche edge case into the mainline collision shape — see the F1
177
- * comment inside `inFlightKey()` below for the full failure scenario.
167
+ * wrong cache / system-instruction mismatch. Calls whose keys differ are not
168
+ * serialised: two builds for one workspace with different keys run at once.
178
169
  *
179
170
  * Scope: single Node process. Cross-process races (two MCP servers sharing the
180
171
  * same manifest DB) are not covered — documented in docs/KNOWN-DEFICITS.md.
@@ -188,18 +179,10 @@ function inFlightKey(opts) {
188
179
  opts.systemPromptHash,
189
180
  String(opts.allowCaching),
190
181
  String(opts.cacheMinTokens ?? ''),
191
- // v1.14.0 round-1 fix (F1, Copilot HIGH): `cachingMode` MUST be in the
192
- // key. Pre-fix, two concurrent calls — one with `'explicit'` (per-call
193
- // override), one with `'implicit'` (the v1.14.0 default) — produced
194
- // identical keys and shared the SAME PreparedContext via the coalescing
195
- // map below. Whichever raced first determined the return shape; the
196
- // loser got the wrong caching strategy. Same shape as the v1.13.0
197
- // round-3 stale-fileId bug — a missing dimension on an equality-keyed
198
- // lookup. v1.14.0's default flip turned this from a niche edge case
199
- // into the mainline collision shape because per-call `'explicit'`
200
- // overrides routinely race the new default. `?? ''` keeps `undefined`
201
- // distinct from `'explicit'` so a future third caching mode can't
202
- // silently coalesce with undefined-legacy callers.
182
+ // `cachingMode` is in the key: two concurrent calls that differ only in
183
+ // mode want different shapes (a cache for `'explicit'`, inline parts for
184
+ // `'implicit'`), and a shared promise would hand one of them the other's.
185
+ // `?? ''` keeps `undefined` distinct from `'explicit'`.
203
186
  String(opts.cachingMode ?? ''),
204
187
  ].join('\u241E'); // record-separator sentinel unlikely to appear in any field
205
188
  }
@@ -219,252 +202,316 @@ export async function prepareContext(opts) {
219
202
  inFlight.set(key, promise);
220
203
  return promise;
221
204
  }
205
+ /**
206
+ * The order of the decisions: the inline modes before the reuse test (a `noCache` or implicit call never uses a
207
+ * cache), the reuse test before the token floor (reuse costs nothing, and a workspace that shrank below the floor keeps
208
+ * its valid cache until its TTL instead of orphaning it on Google's side), the uploads only for a build.
209
+ */
222
210
  async function doPrepareContext(opts) {
223
- const { client, manifest, scan, model, systemPromptHash, ttlSeconds, emitter, allowCaching } = opts;
224
- const now = Date.now();
225
- const existing = manifest.getWorkspace(scan.workspaceRoot);
226
- // 1) Ensure the workspace row exists before any file rows reference it.
227
- // The `files` table has a FK to `workspaces(workspace_root)`, so first-time
228
- // uploads on a new workspace would otherwise fail with FOREIGN KEY constraint.
229
- if (!existing) {
230
- manifest.upsertWorkspace({
231
- workspaceRoot: scan.workspaceRoot,
232
- filesHash: scan.filesHash,
233
- model: model.resolved,
234
- systemPromptHash,
235
- cacheId: null,
236
- cacheExpiresAt: null,
237
- fileIds: [],
238
- createdAt: now,
239
- updatedAt: now,
240
- });
211
+ const start = startCall(opts);
212
+ const inlineMode = inlineModeLine(opts);
213
+ if (inlineMode !== null)
214
+ return prepareInline(opts, start, inlineMode);
215
+ if (isUsableExistingCache(start.existing, opts.scan, opts.model, opts.systemPromptHash, start.now)) {
216
+ return reusedCache(start.existing);
241
217
  }
242
- // 2) Inline path — taken when caching is disabled OR the caller opted into
243
- // implicit caching (v1.13.0+). In both cases we skip `caches.create`,
244
- // embed file text inline from disk, and let Gemini handle whatever
245
- // caching it can: zero for `noCache` callers; automatic implicit
246
- // caching on Gemini 2.5+/3 Pro for `cachingMode: 'implicit'` callers.
247
- // No upload round-trip, no 48 h housekeeping.
248
- const implicitMode = opts.cachingMode === 'implicit';
249
- if (!allowCaching || implicitMode) {
250
- logger.debug(implicitMode
251
- ? 'caching mode = implicit — embedding files inline from disk; Gemini 2.5+/3 will auto-cache prefix.'
252
- : 'caching disabled — embedding files inline from disk.');
253
- const inlineContents = await buildInlineContentFromDisk(scan);
254
- manifest.upsertWorkspace({
255
- workspaceRoot: scan.workspaceRoot,
256
- filesHash: scan.filesHash,
257
- model: model.resolved,
258
- systemPromptHash,
218
+ const tooSmall = tokenFloorLine(opts.scan, opts.cacheMinTokens);
219
+ if (tooSmall !== null)
220
+ return prepareInline(opts, start, tooSmall);
221
+ const uploaded = await uploadForCache(opts);
222
+ return buildCache(opts, start, uploaded);
223
+ }
224
+ /**
225
+ * The clock read once and the workspace row as found. A workspace seen for the first time gets its row now, before
226
+ * any file row references it: the `files` table has a FK to `workspaces(workspace_root)`.
227
+ */
228
+ function startCall(opts) {
229
+ const start = {
230
+ now: Date.now(),
231
+ existing: opts.manifest.getWorkspace(opts.scan.workspaceRoot),
232
+ };
233
+ if (!start.existing) {
234
+ writeWorkspaceRow(opts, start, {
259
235
  cacheId: null,
260
236
  cacheExpiresAt: null,
261
237
  fileIds: [],
262
- createdAt: existing?.createdAt ?? now,
263
- updatedAt: now,
238
+ updatedAt: start.now,
264
239
  });
265
- // v1.13.0 memo-seed (post-review fix): the inline path skips
266
- // `uploadWorkspaceFiles`, which is the only other site that calls
267
- // `upsertFile`. Without this seed, `mtime_ms` / `size` columns stay
268
- // NULL on every file row, `buildScanMemo` filters them out next call,
269
- // and the v1.13.0 scan memo silently degrades to cold-every-call —
270
- // exactly defeating the perf headline for implicit-mode users.
271
- seedScanMemo(manifest, scan);
272
- return {
273
- cacheId: null,
274
- cacheExpiresAt: null,
275
- inlineContents,
276
- uploaded: { files: [], uploadedCount: 0, reusedCount: 0, failedCount: 0, failures: [] },
277
- rebuilt: false,
278
- reused: false,
279
- inlineOnly: true,
280
- };
281
240
  }
282
- // 3) Reuse existing cache if fingerprints match. This runs BEFORE the
283
- // token-floor check because reuse costs nothing — even a workspace that
284
- // shrank below the floor should keep its valid cache until TTL expiry
285
- // rather than being forced inline (which would orphan the cache on
286
- // Google's side). Reordering from the previous build->reuse order was
287
- // flagged by GPT review.
288
- if (isUsableExistingCache(existing, scan, model, systemPromptHash, now)) {
289
- logger.debug(`cache hit: ${safeForLog(existing?.cacheId)}`);
290
- return {
291
- cacheId: existing?.cacheId ?? null,
292
- cacheExpiresAt: existing?.cacheExpiresAt ?? null,
293
- inlineContents: [],
294
- uploaded: { files: [], uploadedCount: 0, reusedCount: 0, failedCount: 0, failures: [] },
295
- rebuilt: false,
296
- reused: true,
297
- inlineOnly: false,
298
- };
241
+ return start;
242
+ }
243
+ /** Writes the call's workspace row with `fields`, keeping the `createdAt` the call found (its start for a new row). */
244
+ function writeWorkspaceRow(opts, start, fields) {
245
+ opts.manifest.upsertWorkspace({
246
+ workspaceRoot: opts.scan.workspaceRoot,
247
+ filesHash: opts.scan.filesHash,
248
+ model: opts.model.resolved,
249
+ systemPromptHash: opts.systemPromptHash,
250
+ cacheId: fields.cacheId,
251
+ cacheExpiresAt: fields.cacheExpiresAt,
252
+ fileIds: fields.fileIds,
253
+ createdAt: start.existing?.createdAt ?? start.now,
254
+ updatedAt: fields.updatedAt,
255
+ });
256
+ }
257
+ /**
258
+ * The debug line of a call whose options skip `caches.create`, or null: caching disabled (`noCache`) sends the files
259
+ * with no cache; implicit mode leaves the caching to Gemini 2.5+/3's automatic prefix cache.
260
+ */
261
+ function inlineModeLine(opts) {
262
+ if (opts.cachingMode === 'implicit') {
263
+ return 'caching mode = implicit — embedding files inline from disk; Gemini 2.5+/3 will auto-cache prefix.';
299
264
  }
300
- // 4) Token-floor check — Gemini rejects `caches.create` below 1024 tokens.
301
- // Skip the Files API entirely — there's no cache-build benefit for small
302
- // workspaces and we save the upload overhead. Only applies when we're
303
- // about to BUILD a new cache (reuse above already returned).
304
- const minTokens = opts.cacheMinTokens ?? 1024;
265
+ if (!opts.allowCaching)
266
+ return 'caching disabled — embedding files inline from disk.';
267
+ return null;
268
+ }
269
+ /**
270
+ * The debug line of a workspace too small for a context cache, or null. Gemini rejects `caches.create` below 1024
271
+ * tokens, and a small workspace gains nothing from the upload; the estimate is 4 bytes a token.
272
+ */
273
+ function tokenFloorLine(scan, cacheMinTokens) {
274
+ const minTokens = cacheMinTokens ?? 1024;
305
275
  const estimatedTokens = scan.files.reduce((sum, f) => sum + Math.ceil(f.size / 4), 0);
306
276
  if (estimatedTokens < minTokens) {
307
- logger.debug(`workspace too small for context cache (~${estimatedTokens} tokens < ${minTokens}); embedding inline.`);
308
- const inlineContents = await buildInlineContentFromDisk(scan);
309
- manifest.upsertWorkspace({
310
- workspaceRoot: scan.workspaceRoot,
311
- filesHash: scan.filesHash,
312
- model: model.resolved,
313
- systemPromptHash,
314
- cacheId: null,
315
- cacheExpiresAt: null,
316
- fileIds: [],
317
- createdAt: existing?.createdAt ?? now,
318
- updatedAt: now,
319
- });
320
- // v1.13.0 memo-seed (post-review fix): see the same call upstream in
321
- // the inline / implicit branch for full rationale.
322
- seedScanMemo(manifest, scan);
323
- return {
324
- cacheId: null,
325
- cacheExpiresAt: null,
326
- inlineContents,
327
- uploaded: { files: [], uploadedCount: 0, reusedCount: 0, failedCount: 0, failures: [] },
328
- rebuilt: false,
329
- reused: false,
330
- inlineOnly: true,
331
- };
277
+ return `workspace too small for context cache (~${estimatedTokens} tokens < ${minTokens}); embedding inline.`;
332
278
  }
333
- // 5) Upload files (parallel pool inside uploadWorkspaceFiles).
334
- // v1.12.1: thread `signal` so a fired `timeoutMs` aborts the upload
335
- // loop at the next per-file poll point — pre-v1.12.1 the upload phase
336
- // ignored aborts.
279
+ return null;
280
+ }
281
+ /**
282
+ * The inline exit: the files read from disk and embedded, no upload, no cache; the row drops its cache pointer. The
283
+ * scan memo is seeded here because the uploader, the only other writer of the memo columns, does not run: without
284
+ * the seed `mtime_ms` / `size` stay NULL, `buildScanMemo` filters the rows out and every file re-hashes next call.
285
+ */
286
+ async function prepareInline(opts, start, line) {
287
+ logger.debug(line);
288
+ const inlineContents = await buildInlineContentFromDisk(opts.scan);
289
+ writeWorkspaceRow(opts, start, {
290
+ cacheId: null,
291
+ cacheExpiresAt: null,
292
+ fileIds: [],
293
+ updatedAt: start.now,
294
+ });
295
+ seedScanMemo(opts.manifest, opts.scan);
296
+ return {
297
+ cacheId: null,
298
+ cacheExpiresAt: null,
299
+ inlineContents,
300
+ uploaded: noUploads(),
301
+ rebuilt: false,
302
+ reused: false,
303
+ inlineOnly: true,
304
+ };
305
+ }
306
+ /** The upload result of a call that uploaded nothing. */
307
+ function noUploads() {
308
+ return { files: [], uploadedCount: 0, reusedCount: 0, failedCount: 0, failures: [] };
309
+ }
310
+ /** The cache the row holds, reused as it is: no upload, no write. */
311
+ function reusedCache(existing) {
312
+ logger.debug(`cache hit: ${safeForLog(existing.cacheId)}`);
313
+ return {
314
+ cacheId: existing.cacheId,
315
+ cacheExpiresAt: existing.cacheExpiresAt,
316
+ inlineContents: [],
317
+ uploaded: noUploads(),
318
+ rebuilt: false,
319
+ reused: true,
320
+ inlineOnly: false,
321
+ };
322
+ }
323
+ /** The workspace files uploaded for a cache; `signal` stops the queueing of uploads once a timeout fires. */
324
+ async function uploadForCache(opts) {
325
+ const { scan, emitter } = opts;
337
326
  emitter.emit(`indexing ${scan.files.length} files…`, 0, scan.files.length);
338
327
  const uploaded = await uploadWorkspaceFiles({
339
- client,
340
- manifest,
328
+ client: opts.client,
329
+ manifest: opts.manifest,
341
330
  workspaceRoot: scan.workspaceRoot,
342
331
  files: scan.files,
343
332
  emitter,
344
333
  ...(opts.uploadConcurrency !== undefined ? { concurrency: opts.uploadConcurrency } : {}),
345
334
  ...(opts.signal !== undefined ? { signal: opts.signal } : {}),
346
335
  });
347
- // If enough uploads failed that the context is clearly lossy, bail now so the
348
- // caller surfaces an error instead of silently returning a partial answer.
349
- // Threshold: tiny workspaces (≤5 files) fail-fast on ANY upload failure; larger
350
- // workspaces tolerate ≤5 % or <3 failures. The tiny-workspace carve-out
351
- // prevents a 2-file repo with both uploads failing from falling through to a
352
- // confusing Gemini 400 on empty contents.
353
- const failureThreshold = scan.files.length <= 5 ? 1 : Math.max(3, Math.ceil(scan.files.length * 0.05));
336
+ assertUploadsComplete(scan.files.length, uploaded);
337
+ return uploaded;
338
+ }
339
+ /**
340
+ * Throws when so many uploads failed that the context is clearly lossy, so the caller surfaces an error instead of a
341
+ * partial answer; the workspace row is not written. Up to 5 files any failure counts (a 2-file repo with both uploads
342
+ * failed would otherwise reach Gemini as empty contents); above that, max(3, 5 %) failures.
343
+ */
344
+ function assertUploadsComplete(fileCount, uploaded) {
345
+ const failureThreshold = fileCount <= 5 ? 1 : Math.max(3, Math.ceil(fileCount * 0.05));
354
346
  if (uploaded.failedCount >= failureThreshold) {
355
347
  const preview = uploaded.failures
356
348
  .slice(0, 3)
357
349
  .map((f) => `${f.relpath}: ${f.error}`)
358
350
  .join(' | ');
359
- throw new Error(`Upload failed for ${uploaded.failedCount}/${scan.files.length} files (threshold ${failureThreshold}). First errors: ${preview}`);
351
+ throw new Error(`Upload failed for ${uploaded.failedCount}/${fileCount} files (threshold ${failureThreshold}). First errors: ${preview}`);
360
352
  }
361
- // 6) Capture the stale cacheId for async post-create deletion.
362
- // v1.13.0 — pre-fix the delete ran synchronously before the build,
363
- // adding 5–15 s to the user's critical path on every cache rebuild.
364
- // Post-fix we build the new cache first, swap the manifest pointer,
365
- // return to the caller, and delete the old cache async (best-effort,
366
- // retried) — the user's wait drops by the delete's full duration.
367
- // Worst case on persistent delete failure: an orphaned cache lingers
368
- // on Google's side until its TTL expires (~hours-to-day). Storage
369
- // cost is bounded by `cacheTtlSeconds`. Documented in CHANGELOG.
370
- const staleCacheIdForAsyncDelete = existing?.cacheId ?? null;
371
- // 7) Build a new cache.
372
- emitter.emit('building context cache…');
373
- const fileContents = buildContentFromUploaded(uploaded.files);
353
+ }
354
+ /** Builds a new cache from the uploads; a create that fails falls back to the uploaded file parts inline. */
355
+ async function buildCache(opts, start, uploaded) {
356
+ opts.emitter.emit('building context cache…');
357
+ const build = {
358
+ opts,
359
+ start,
360
+ uploaded,
361
+ fileContents: buildContentFromUploaded(uploaded.files),
362
+ };
363
+ let created;
374
364
  try {
375
- const baseConfig = {
376
- contents: fileContents,
377
- ttl: ttlString(ttlSeconds),
378
- displayName: `gcctx-${scan.workspaceRoot.slice(-40)}`,
379
- };
380
- const cacheConfig = opts.systemInstruction !== undefined
381
- ? { ...baseConfig, systemInstruction: opts.systemInstruction }
382
- : baseConfig;
383
- const created = await client.caches.create({
384
- model: model.resolved,
385
- config: cacheConfig,
386
- });
387
- // Re-read the clock AFTER create returns — long uploads would otherwise
388
- // make our tracked `cacheExpiresAt` artificially earlier than Google's.
389
- const afterCreateMs = Date.now();
390
- const cacheId = created.name ?? null;
391
- const cacheExpiresAt = afterCreateMs + ttlSeconds * 1000;
392
- manifest.upsertWorkspace({
393
- workspaceRoot: scan.workspaceRoot,
394
- filesHash: scan.filesHash,
395
- model: model.resolved,
396
- systemPromptHash,
365
+ created = await createCache(build);
366
+ }
367
+ catch (error) {
368
+ return fallBackInline(build, { stage: 'create', error });
369
+ }
370
+ return recordCreatedCache(build, created);
371
+ }
372
+ /** Points the row at the new cache, then deletes the previous one (`deleteReplacedCache`). */
373
+ function recordCreatedCache(build, created) {
374
+ const { opts, start, uploaded } = build;
375
+ const { cacheId, cacheExpiresAt } = created;
376
+ try {
377
+ const fileIds = uploadedFileIds(uploaded);
378
+ writeWorkspaceRow(opts, start, {
397
379
  cacheId,
398
380
  cacheExpiresAt,
399
- fileIds: uploaded.files.map((f) => f.fileId).filter((v) => v !== null),
400
- createdAt: existing?.createdAt ?? now,
401
- updatedAt: afterCreateMs,
381
+ fileIds,
382
+ updatedAt: created.answeredAtMs,
402
383
  });
403
- // v1.13.0 — fire-and-forget delete of the stale cache. Manifest already
404
- // points at the new cacheId, so a delete failure is purely a Google-side
405
- // orphan (auto-expires at TTL). 3× retry handles transient errors;
406
- // permanent failure is logged at warn but doesn't surface to the caller.
407
- if (staleCacheIdForAsyncDelete !== null) {
408
- void bestEffortDeleteCache(client, staleCacheIdForAsyncDelete);
409
- }
410
- return {
411
- cacheId,
412
- cacheExpiresAt,
413
- inlineContents: [],
414
- uploaded,
415
- rebuilt: true,
416
- reused: false,
417
- inlineOnly: false,
418
- };
419
384
  }
420
- catch (err) {
421
- logger.warn(`cache build failed — falling back to inline parts: ${safeForLog(err)}`);
422
- manifest.upsertWorkspace({
423
- workspaceRoot: scan.workspaceRoot,
424
- filesHash: scan.filesHash,
425
- model: model.resolved,
426
- systemPromptHash,
427
- cacheId: null,
428
- cacheExpiresAt: null,
429
- fileIds: uploaded.files.map((f) => f.fileId).filter((v) => v !== null),
430
- createdAt: existing?.createdAt ?? now,
431
- updatedAt: now,
432
- });
433
- return {
434
- cacheId: null,
435
- cacheExpiresAt: null,
436
- inlineContents: fileContents,
437
- uploaded,
438
- rebuilt: false,
439
- reused: false,
440
- inlineOnly: false,
441
- };
385
+ catch (error) {
386
+ return fallBackInline(build, { stage: 'record', cacheId, error });
442
387
  }
388
+ deleteReplacedCache(opts.client, start, cacheId);
389
+ return {
390
+ cacheId,
391
+ cacheExpiresAt,
392
+ inlineContents: [],
393
+ uploaded,
394
+ rebuilt: true,
395
+ reused: false,
396
+ inlineOnly: false,
397
+ };
443
398
  }
444
399
  /**
445
- * Best-effort async delete of a stale cache after a successful rebuild
446
- * (v1.13.0+). Retries 3× with exponential back-off (1 s, 3 s, 9 s) for
447
- * transient errors. Logs at warn on permanent failure — orphaned caches
448
- * auto-expire at Google's TTL so the worst case is bounded storage cost.
449
- *
450
- * Called as `void bestEffortDeleteCache(...)` so callers don't have to
451
- * await; the manifest's `cacheId` pointer was already swapped to the new
452
- * cache before this fires.
400
+ * Creates the cache and counts its stored expiry from the clock read after the answer, so the stored expiry is later
401
+ * than Google's own by at most the answer's latency (counted from before the create, it would be earlier by the whole
402
+ * create); a request sent on a cache that expired in that window meets the stale-cache retry (`isStaleCacheError`).
403
+ * A create that names no cache built none a request can use: it throws, so the rebuild takes the failed-create path
404
+ * (the files inline), never a context with neither a cache nor its files.
405
+ */
406
+ async function createCache(build) {
407
+ const { opts } = build;
408
+ const ttl = effectiveTtlSeconds(opts.ttlSeconds);
409
+ const baseConfig = {
410
+ contents: build.fileContents,
411
+ ttl: `${ttl}s`,
412
+ displayName: `gcctx-${opts.scan.workspaceRoot.slice(-40)}`,
413
+ };
414
+ const cacheConfig = opts.systemInstruction !== undefined
415
+ ? { ...baseConfig, systemInstruction: opts.systemInstruction }
416
+ : baseConfig;
417
+ const created = await opts.client.caches.create({
418
+ model: opts.model.resolved,
419
+ config: cacheConfig,
420
+ });
421
+ const afterCreateMs = Date.now();
422
+ if (!created.name) {
423
+ throw new Error(`caches.create returned no cache name; a cache may exist on Google's side under no name this server can delete, billed until its TTL (${ttl} s)`);
424
+ }
425
+ return {
426
+ cacheId: created.name,
427
+ cacheExpiresAt: afterCreateMs + ttl * 1000,
428
+ answeredAtMs: afterCreateMs,
429
+ };
430
+ }
431
+ /**
432
+ * The failed-create path: the warning, the row written without a cache (`updatedAt` the call's start), the uploaded
433
+ * file parts inline. A cache created but not recorded is deleted before the row write, so its delete is fired even
434
+ * when that write throws too; the previous cache, which the row no longer names, is deleted after it.
435
+ */
436
+ function fallBackInline(build, failure) {
437
+ const { opts, start, uploaded } = build;
438
+ reportCreateFailure(opts.client, failure);
439
+ const fileIds = uploadedFileIds(uploaded);
440
+ writeWorkspaceRow(opts, start, {
441
+ cacheId: null,
442
+ cacheExpiresAt: null,
443
+ fileIds,
444
+ updatedAt: start.now,
445
+ });
446
+ deleteReplacedCache(opts.client, start, failure.stage === 'record' ? failure.cacheId : null);
447
+ return {
448
+ cacheId: null,
449
+ cacheExpiresAt: null,
450
+ inlineContents: build.fileContents,
451
+ uploaded,
452
+ rebuilt: false,
453
+ reused: false,
454
+ inlineOnly: false,
455
+ };
456
+ }
457
+ /** The warning of a failed create; a cache that was created but could not be recorded is deleted, best-effort. */
458
+ function reportCreateFailure(client, failure) {
459
+ if (failure.stage === 'create') {
460
+ logger.warn(`cache build failed — falling back to inline parts: ${safeForLog(failure.error)}`);
461
+ return;
462
+ }
463
+ logger.warn(`recording cache ${safeForLog(failure.cacheId)} in the manifest failed — deleting it, falling back to inline parts: ${safeForLog(failure.error)}`);
464
+ void bestEffortDeleteCache(client, failure.cacheId, 'unrecorded');
465
+ }
466
+ /**
467
+ * Deletes the cache the row named at the call's start, which the call's own row write has just stopped naming. Called
468
+ * only after that write succeeded, and without waiting: a write that throws leaves the row naming its cache and that
469
+ * cache alive; a delete that fails leaves an orphan on Google's side until its TTL (bounded by `cacheTtlSeconds`).
470
+ * `accountedFor` is the cache the call already holds or deletes — the one the row now names, or a new cache whose
471
+ * `unrecorded` delete is fired — so a create answering with the previous cache's own name never deletes a cache the
472
+ * row names, nor one name twice.
453
473
  */
454
- async function bestEffortDeleteCache(client, cacheId) {
474
+ function deleteReplacedCache(client, start, accountedFor) {
475
+ const previousCacheId = start.existing?.cacheId ?? null;
476
+ if (previousCacheId === null || previousCacheId === accountedFor)
477
+ return;
478
+ void bestEffortDeleteCache(client, previousCacheId, 'stale');
479
+ }
480
+ /**
481
+ * Whether an uploaded or stored file holds a Files API id. The uploader never yields an empty one (an upload Google
482
+ * answers without an identifier throws); a file row without an upload holds `null`, and an empty id means none too.
483
+ */
484
+ function isFileId(fileId) {
485
+ return typeof fileId === 'string' && fileId.length > 0;
486
+ }
487
+ /** The Files API ids of the uploads that have one. */
488
+ function uploadedFileIds(uploaded) {
489
+ return uploaded.files.map((f) => f.fileId).filter(isFileId);
490
+ }
491
+ /**
492
+ * Best-effort async delete of a cache no workspace row names. Tries three times in all, waiting 1 s and then 3 s
493
+ * between attempts, for transient errors. A `NOT_FOUND` answer means the cache is already gone (expired, or deleted by
494
+ * another call): nothing is orphaned, so it is not warned. Logs at warn on a permanent failure — orphaned caches
495
+ * auto-expire at Google's TTL so the worst case is bounded storage cost. Called as `void bestEffortDeleteCache(...)`:
496
+ * the caller never waits for it.
497
+ */
498
+ async function bestEffortDeleteCache(client, cacheId, kind) {
455
499
  const delays = [1000, 3000, 9000];
456
500
  for (let attempt = 0; attempt < delays.length; attempt += 1) {
457
501
  try {
458
502
  await client.caches.delete({ name: cacheId });
459
- logger.debug(`async-deleted stale cache ${safeForLog(cacheId)} (attempt ${attempt + 1})`);
503
+ logger.debug(`async-deleted ${kind} cache ${safeForLog(cacheId)} (attempt ${attempt + 1})`);
460
504
  return;
461
505
  }
462
506
  catch (err) {
463
- // Retry transient errors; give up quickly on 4xx (cache already gone, perms, etc.)
464
507
  const msg = err instanceof Error ? err.message : String(err);
465
- const isTransient = !msg.includes('NOT_FOUND') && !msg.includes('PERMISSION_DENIED');
508
+ if (msg.includes('NOT_FOUND')) {
509
+ logger.debug(`${kind} cache ${safeForLog(cacheId)} was already gone (attempt ${attempt + 1})`);
510
+ return;
511
+ }
512
+ const isTransient = !msg.includes('PERMISSION_DENIED');
466
513
  if (!isTransient || attempt === delays.length - 1) {
467
- logger.warn(`async-delete of stale cache ${safeForLog(cacheId)} permanently failed (attempt ${attempt + 1}): ${safeForLog(msg)}. Orphan will auto-expire at TTL.`);
514
+ logger.warn(`async-delete of ${kind} cache ${safeForLog(cacheId)} permanently failed (attempt ${attempt + 1}): ${safeForLog(msg)}. Orphan will auto-expire at TTL.`);
468
515
  return;
469
516
  }
470
517
  const nextDelay = delays[attempt];
@@ -499,44 +546,49 @@ export async function invalidateWorkspaceCache(args) {
499
546
  logger.debug(`cache delete (${safeForLog(ws.cacheId)}) failed: ${safeForLog(err)}`);
500
547
  }
501
548
  }
502
- // De-duplicate fileIds: the manifest's `files` table can have multiple
503
- // (workspaceRoot, relpath) rows pointing at the SAME `fileId` when the
504
- // uploader reused an existing upload via content-hash dedup (a tool whose
505
- // workspace contains the same file at two paths, or a rebuild that found
506
- // an existing in-batch dedup hit). Without `Set`, we'd `files.delete(X)`
507
- // multiple times — wasteful API calls + 404 noise after the first delete.
508
- const fileIds = Array.from(new Set(args.manifest
509
- .getFiles(args.workspaceRoot)
549
+ const fileIds = storedFileIds(args.manifest, args.workspaceRoot);
550
+ if (fileIds.length > 0)
551
+ await releaseUploadedFiles(args.client, fileIds);
552
+ args.manifest.deleteWorkspace(args.workspaceRoot);
553
+ }
554
+ /**
555
+ * The workspace's Files API ids, each once: several file rows can point at one upload (the uploader's content-hash
556
+ * dedup, the same file at two paths), and a second `files.delete` of it is a wasted call and a 404.
557
+ */
558
+ function storedFileIds(manifest, workspaceRoot) {
559
+ return Array.from(new Set(manifest
560
+ .getFiles(workspaceRoot)
510
561
  .map((r) => r.fileId)
511
- .filter((v) => typeof v === 'string' && v.length > 0)));
512
- if (fileIds.length > 0) {
513
- const concurrency = Math.min(10, fileIds.length);
514
- let idx = 0;
515
- await Promise.all(Array.from({ length: concurrency }, async () => {
516
- while (idx < fileIds.length) {
517
- const i = idx;
518
- idx += 1;
519
- const id = fileIds[i];
520
- if (!id)
521
- continue;
522
- // `files-uploader.ts:172` deliberately stores `uploaded.uri` (the
523
- // `https://…/files/abc` form) rather than `uploaded.name` because
524
- // Gemini's `fileData.fileUri` reference rejects the bare `files/abc`
525
- // resource-name form at `caches.create` time. But `files.delete`
526
- // wants the RESOURCE NAME, not the URI (different endpoint,
527
- // different parameter expectation). Normalise here so deletes
528
- // actually hit — otherwise B3's cost-leak fix silently no-ops.
529
- const deleteName = toFileResourceName(id);
530
- try {
531
- await args.client.files.delete({ name: deleteName });
532
- }
533
- catch (err) {
534
- logger.debug(`files.delete (${safeForLog(deleteName)}, stored as ${safeForLog(id)}) failed: ${safeForLog(err)}`);
535
- }
536
- }
537
- }));
562
+ .filter(isFileId)));
563
+ }
564
+ /** Releases the uploads through a pool of at most 10 concurrent deletes. */
565
+ async function releaseUploadedFiles(client, fileIds) {
566
+ const concurrency = Math.min(10, fileIds.length);
567
+ let idx = 0;
568
+ await Promise.all(Array.from({ length: concurrency }, async () => {
569
+ while (idx < fileIds.length) {
570
+ const i = idx;
571
+ idx += 1;
572
+ const id = fileIds[i];
573
+ if (!id)
574
+ continue;
575
+ await releaseFile(client, id);
576
+ }
577
+ }));
578
+ }
579
+ /**
580
+ * Deletes one upload by its resource name. The manifest stores the `https://…/files/abc` URI (`fileData.fileUri`
581
+ * rejects the bare `files/abc` form at `caches.create`), while `files.delete` takes the resource name. A failure is
582
+ * logged and the purge goes on: Gemini deletes every upload 48 h after it was made.
583
+ */
584
+ async function releaseFile(client, id) {
585
+ const deleteName = toFileResourceName(id);
586
+ try {
587
+ await client.files.delete({ name: deleteName });
588
+ }
589
+ catch (err) {
590
+ logger.debug(`files.delete (${safeForLog(deleteName)}, stored as ${safeForLog(id)}) failed: ${safeForLog(err)}`);
538
591
  }
539
- args.manifest.deleteWorkspace(args.workspaceRoot);
540
592
  }
541
593
  /**
542
594
  * Lightweight cache-pointer reset used by the ask/code stale-cache retry