@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.
Files changed (189) hide show
  1. package/CHANGELOG.md +110 -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/dispatch.d.ts +68 -0
  22. package/dist/tools/agentic/dispatch.d.ts.map +1 -0
  23. package/dist/tools/agentic/dispatch.js +167 -0
  24. package/dist/tools/agentic/dispatch.js.map +1 -0
  25. package/dist/tools/agentic/input.d.ts +28 -0
  26. package/dist/tools/agentic/input.d.ts.map +1 -0
  27. package/dist/tools/agentic/input.js +66 -0
  28. package/dist/tools/agentic/input.js.map +1 -0
  29. package/dist/tools/agentic/instructions.d.ts +46 -0
  30. package/dist/tools/agentic/instructions.d.ts.map +1 -0
  31. package/dist/tools/agentic/instructions.js +170 -0
  32. package/dist/tools/agentic/instructions.js.map +1 -0
  33. package/dist/tools/agentic/iteration.d.ts +81 -0
  34. package/dist/tools/agentic/iteration.d.ts.map +1 -0
  35. package/dist/tools/agentic/iteration.js +317 -0
  36. package/dist/tools/agentic/iteration.js.map +1 -0
  37. package/dist/tools/agentic/ledger.d.ts +64 -0
  38. package/dist/tools/agentic/ledger.d.ts.map +1 -0
  39. package/dist/tools/agentic/ledger.js +110 -0
  40. package/dist/tools/agentic/ledger.js.map +1 -0
  41. package/dist/tools/agentic/loop.d.ts +10 -0
  42. package/dist/tools/agentic/loop.d.ts.map +1 -0
  43. package/dist/tools/agentic/loop.js +179 -0
  44. package/dist/tools/agentic/loop.js.map +1 -0
  45. package/dist/tools/agentic/no-progress.d.ts +90 -0
  46. package/dist/tools/agentic/no-progress.d.ts.map +1 -0
  47. package/dist/tools/agentic/no-progress.js +107 -0
  48. package/dist/tools/agentic/no-progress.js.map +1 -0
  49. package/dist/tools/agentic/pass-clock.d.ts +85 -0
  50. package/dist/tools/agentic/pass-clock.d.ts.map +1 -0
  51. package/dist/tools/agentic/pass-clock.js +162 -0
  52. package/dist/tools/agentic/pass-clock.js.map +1 -0
  53. package/dist/tools/agentic/phase-defaults.d.ts +29 -0
  54. package/dist/tools/agentic/phase-defaults.d.ts.map +1 -0
  55. package/dist/tools/agentic/phase-defaults.js +23 -0
  56. package/dist/tools/agentic/phase-defaults.js.map +1 -0
  57. package/dist/tools/agentic/rescue.d.ts +69 -0
  58. package/dist/tools/agentic/rescue.d.ts.map +1 -0
  59. package/dist/tools/agentic/rescue.js +203 -0
  60. package/dist/tools/agentic/rescue.js.map +1 -0
  61. package/dist/tools/agentic/response.d.ts +16 -0
  62. package/dist/tools/agentic/response.d.ts.map +1 -0
  63. package/dist/tools/agentic/response.js +25 -0
  64. package/dist/tools/agentic/response.js.map +1 -0
  65. package/dist/tools/agentic/results.d.ts +76 -0
  66. package/dist/tools/agentic/results.d.ts.map +1 -0
  67. package/dist/tools/agentic/results.js +228 -0
  68. package/dist/tools/agentic/results.js.map +1 -0
  69. package/dist/tools/agentic/run.d.ts +130 -0
  70. package/dist/tools/agentic/run.d.ts.map +1 -0
  71. package/dist/tools/agentic/run.js +128 -0
  72. package/dist/tools/agentic/run.js.map +1 -0
  73. package/dist/tools/agentic/sandbox.d.ts +13 -2
  74. package/dist/tools/agentic/sandbox.d.ts.map +1 -1
  75. package/dist/tools/agentic/sandbox.js +127 -111
  76. package/dist/tools/agentic/sandbox.js.map +1 -1
  77. package/dist/tools/agentic/workspace-tools.d.ts +30 -27
  78. package/dist/tools/agentic/workspace-tools.d.ts.map +1 -1
  79. package/dist/tools/agentic/workspace-tools.js +324 -385
  80. package/dist/tools/agentic/workspace-tools.js.map +1 -1
  81. package/dist/tools/ask/answer.d.ts +9 -0
  82. package/dist/tools/ask/answer.d.ts.map +1 -0
  83. package/dist/tools/ask/answer.js +28 -0
  84. package/dist/tools/ask/answer.js.map +1 -0
  85. package/dist/tools/ask/attachments.d.ts +25 -0
  86. package/dist/tools/ask/attachments.d.ts.map +1 -0
  87. package/dist/tools/ask/attachments.js +85 -0
  88. package/dist/tools/ask/attachments.js.map +1 -0
  89. package/dist/tools/ask/call.d.ts +61 -0
  90. package/dist/tools/ask/call.d.ts.map +1 -0
  91. package/dist/tools/ask/call.js +6 -0
  92. package/dist/tools/ask/call.js.map +1 -0
  93. package/dist/tools/ask/guard.d.ts +24 -0
  94. package/dist/tools/ask/guard.d.ts.map +1 -0
  95. package/dist/tools/ask/guard.js +79 -0
  96. package/dist/tools/ask/guard.js.map +1 -0
  97. package/dist/tools/ask/input.d.ts +45 -0
  98. package/dist/tools/ask/input.d.ts.map +1 -0
  99. package/dist/tools/ask/input.js +93 -0
  100. package/dist/tools/ask/input.js.map +1 -0
  101. package/dist/tools/ask/instruction.d.ts +8 -0
  102. package/dist/tools/ask/instruction.d.ts.map +1 -0
  103. package/dist/tools/ask/instruction.js +13 -0
  104. package/dist/tools/ask/instruction.js.map +1 -0
  105. package/dist/tools/ask/request.d.ts +14 -0
  106. package/dist/tools/ask/request.d.ts.map +1 -0
  107. package/dist/tools/ask/request.js +38 -0
  108. package/dist/tools/ask/request.js.map +1 -0
  109. package/dist/tools/ask/results.d.ts +23 -0
  110. package/dist/tools/ask/results.d.ts.map +1 -0
  111. package/dist/tools/ask/results.js +107 -0
  112. package/dist/tools/ask/results.js.map +1 -0
  113. package/dist/tools/ask/setup.d.ts +22 -0
  114. package/dist/tools/ask/setup.d.ts.map +1 -0
  115. package/dist/tools/ask/setup.js +57 -0
  116. package/dist/tools/ask/setup.js.map +1 -0
  117. package/dist/tools/ask/sizing.d.ts +10 -0
  118. package/dist/tools/ask/sizing.d.ts.map +1 -0
  119. package/dist/tools/ask/sizing.js +33 -0
  120. package/dist/tools/ask/sizing.js.map +1 -0
  121. package/dist/tools/ask/thinking.d.ts +54 -0
  122. package/dist/tools/ask/thinking.d.ts.map +1 -0
  123. package/dist/tools/ask/thinking.js +69 -0
  124. package/dist/tools/ask/thinking.js.map +1 -0
  125. package/dist/tools/ask-agentic-fallback.d.ts +33 -0
  126. package/dist/tools/ask-agentic-fallback.d.ts.map +1 -0
  127. package/dist/tools/ask-agentic-fallback.js +113 -0
  128. package/dist/tools/ask-agentic-fallback.js.map +1 -0
  129. package/dist/tools/ask-agentic.tool.d.ts +11 -44
  130. package/dist/tools/ask-agentic.tool.d.ts.map +1 -1
  131. package/dist/tools/ask-agentic.tool.js +139 -1618
  132. package/dist/tools/ask-agentic.tool.js.map +1 -1
  133. package/dist/tools/ask.tool.d.ts +3 -41
  134. package/dist/tools/ask.tool.d.ts.map +1 -1
  135. package/dist/tools/ask.tool.js +46 -944
  136. package/dist/tools/ask.tool.js.map +1 -1
  137. package/dist/tools/code.tool.d.ts.map +1 -1
  138. package/dist/tools/code.tool.js +376 -514
  139. package/dist/tools/code.tool.js.map +1 -1
  140. package/dist/tools/reindex.tool.d.ts.map +1 -1
  141. package/dist/tools/reindex.tool.js +19 -22
  142. package/dist/tools/reindex.tool.js.map +1 -1
  143. package/dist/tools/shared/abort-timeout.d.ts +43 -5
  144. package/dist/tools/shared/abort-timeout.d.ts.map +1 -1
  145. package/dist/tools/shared/abort-timeout.js +111 -102
  146. package/dist/tools/shared/abort-timeout.js.map +1 -1
  147. package/dist/tools/shared/call-ledger.d.ts +27 -12
  148. package/dist/tools/shared/call-ledger.d.ts.map +1 -1
  149. package/dist/tools/shared/call-ledger.js +57 -39
  150. package/dist/tools/shared/call-ledger.js.map +1 -1
  151. package/dist/tools/shared/continuation.d.ts +1 -1
  152. package/dist/tools/shared/continuation.d.ts.map +1 -1
  153. package/dist/tools/shared/eager-answer.d.ts +78 -0
  154. package/dist/tools/shared/eager-answer.d.ts.map +1 -0
  155. package/dist/tools/shared/eager-answer.js +130 -0
  156. package/dist/tools/shared/eager-answer.js.map +1 -0
  157. package/dist/tools/shared/eager-call.d.ts +114 -0
  158. package/dist/tools/shared/eager-call.d.ts.map +1 -0
  159. package/dist/tools/shared/eager-call.js +95 -0
  160. package/dist/tools/shared/eager-call.js.map +1 -0
  161. package/dist/tools/shared/eager-steps.d.ts +114 -0
  162. package/dist/tools/shared/eager-steps.d.ts.map +1 -0
  163. package/dist/tools/shared/eager-steps.js +152 -0
  164. package/dist/tools/shared/eager-steps.js.map +1 -0
  165. package/dist/tools/shared/question-fields.d.ts +10 -0
  166. package/dist/tools/shared/question-fields.d.ts.map +1 -0
  167. package/dist/tools/shared/question-fields.js +13 -0
  168. package/dist/tools/shared/question-fields.js.map +1 -0
  169. package/dist/tools/shared/service-tier.d.ts +9 -0
  170. package/dist/tools/shared/service-tier.d.ts.map +1 -1
  171. package/dist/tools/shared/service-tier.js +15 -0
  172. package/dist/tools/shared/service-tier.js.map +1 -1
  173. package/dist/tools/shared/settle-call.d.ts +11 -6
  174. package/dist/tools/shared/settle-call.d.ts.map +1 -1
  175. package/dist/tools/shared/settle-call.js +14 -10
  176. package/dist/tools/shared/settle-call.js.map +1 -1
  177. package/dist/tools/shared/thinking.d.ts +9 -0
  178. package/dist/tools/shared/thinking.d.ts.map +1 -1
  179. package/dist/tools/shared/thinking.js +10 -0
  180. package/dist/tools/shared/thinking.js.map +1 -1
  181. package/dist/tools/shared/throttle.d.ts +7 -0
  182. package/dist/tools/shared/throttle.d.ts.map +1 -1
  183. package/dist/tools/shared/throttle.js +18 -0
  184. package/dist/tools/shared/throttle.js.map +1 -1
  185. package/dist/tools/shared/workspace-refusal.d.ts +13 -0
  186. package/dist/tools/shared/workspace-refusal.d.ts.map +1 -0
  187. package/dist/tools/shared/workspace-refusal.js +23 -0
  188. package/dist/tools/shared/workspace-refusal.js.map +1 -0
  189. package/package.json +1 -1
@@ -21,1658 +21,179 @@
21
21
  * - Hard byte limits on tool responses (executors enforce)
22
22
  * - `realpath` + root jail (sandbox module)
23
23
  * - Prompt-injection defence in `systemInstruction`
24
- * - No-progress detection (same call signature 3× → partial answer)
24
+ * - No-progress detection (a call signature repeated with no new file read → partial answer)
25
25
  * - Parallel tool execution with concurrency cap
26
26
  * - Recoverable-error via `functionResponse.error`; hard-fail for
27
27
  * security / budget / timeouts
28
28
  * - `notifications/progress` per iteration for UX
29
29
  */
30
30
  import { resolve } from 'node:path';
31
- import { ApiError, FunctionCallingConfigMode, Type as GeminiType } from '@google/genai';
32
- import { z } from 'zod';
33
31
  import { thinkingBudgetRefusal } from '../gemini/long-decode.js';
34
32
  import { resolveModel } from '../gemini/models.js';
35
- import { abortableSleep, withNetworkRetry } from '../gemini/retry.js';
36
33
  import { defaultMatchConfig } from '../indexer/globs.js';
37
- import { WorkspaceValidationError, validateWorkspacePath, } from '../indexer/workspace-validation.js';
38
- import { estimateCostUsd, estimateReservationUsd, toMicrosUsd } from '../utils/cost-estimator.js';
39
34
  import { logger, safeForLog } from '../utils/logger.js';
40
35
  import { createProgressEmitter } from '../utils/progress.js';
41
- import { SandboxError, resolveInsideWorkspace, resolveWorkspaceRoot } from './agentic/sandbox.js';
42
- import { findFilesExecutor, grepExecutor, listDirectoryExecutor, readFileExecutor, } from './agentic/workspace-tools.js';
43
- import { errorResult, textResult } from './registry.js';
44
- import { createTimeoutController, getTimeoutKind, isTimeoutAbort, resolveTotalTimeoutMs, } from './shared/abort-timeout.js';
45
- import { billedInputTokens } from './shared/call-ledger.js';
46
- import { collectStream } from './shared/stream-collector.js';
47
- import { SYSTEM_INSTRUCTION_SAFETY_AGENTIC } from './shared/system-instruction-safety.js';
48
- import { THINKING_LEVEL_FIELD } from './shared/thinking.js';
49
- import { isGemini429, parseRetryDelayMs } from './shared/throttle.js';
36
+ import { askAgenticInputSchema } from './agentic/input.js';
37
+ import { runLoop } from './agentic/loop.js';
38
+ import { runRescue } from './agentic/rescue.js';
39
+ import { maxIterationsResult } from './agentic/results.js';
40
+ import { AGENTIC_KNOB_NAMES, baseConfigOf, messageKnobNames, newLoopState, passBudgetOf, resolveAgenticKnobs, runLimitsOf, } from './agentic/run.js';
41
+ import { resolveWorkspaceRoot } from './agentic/sandbox.js';
42
+ import { errorResult, } from './registry.js';
43
+ import { seedRetryHint } from './shared/throttle.js';
44
+ import { workspaceRefusal } from './shared/workspace-refusal.js';
45
+ export { resolveToolExecutionConcurrency } from './agentic/dispatch.js';
46
+ export { askAgenticInputSchema } from './agentic/input.js';
50
47
  // ---------------------------------------------------------------------------
51
- // Schema
52
- // ---------------------------------------------------------------------------
53
- export const askAgenticInputSchema = z
54
- .object({
55
- prompt: z.string().min(1).describe('The question or analysis request.'),
56
- workspace: z
57
- .string()
58
- .optional()
59
- .describe('Absolute or cwd-relative path to the workspace. Defaults to process.cwd().'),
60
- model: z
61
- .string()
62
- .optional()
63
- .describe("Model alias ('latest-pro', 'latest-pro-thinking', 'latest-flash') or literal model ID. Defaults to the configured default (GEMINI_CODE_CONTEXT_DEFAULT_MODEL, then the credentials profile, then `latest-pro-thinking`)."),
64
- includeGlobs: z
65
- .array(z.string())
66
- .optional()
67
- .describe('Additional file extensions or filenames to include. Honoured by the four agentic tools (`list_directory`, `find_files`, `read_file`, `grep`) — the model never sees paths outside these globs. Mirrors the `ask` / `code` semantics so callers (or `ask` → `ask_agentic` fallback in v1.9.0+) get consistent filtering.'),
68
- excludeGlobs: z
69
- .array(z.string())
70
- .optional()
71
- .describe('Additional patterns to exclude. Same three shapes as `ask` / `code`: (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`, `.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. Case-insensitive. No mid-string `*` / `**` / `?`. **Privacy-relevant:** when `ask` falls back to `ask_agentic` on `WORKSPACE_TOO_LARGE`, the user-supplied excludes here are honoured by every executor: `read_file` rejects with `EXCLUDED_FILE` (generic message — does NOT echo the excluded path, so the error string cannot be used as a path-existence oracle); `list_directory` and `grep` reject the requested directory / `pathPrefix` itself with `EXCLUDED_DIR` when it matches an exclude (top-level gate, not just child filtering); `find_files` skips the dir during walk; child entries inside an unexcluded parent are still hidden when they themselves match an exclude.'),
72
- thinkingBudget: z.number().int().min(-1).max(65_536).optional(),
73
- thinkingLevel: THINKING_LEVEL_FIELD,
74
- maxOutputTokens: z.number().int().min(1).optional(),
75
- maxIterations: z
76
- .number()
77
- .int()
78
- .min(1)
79
- .max(50)
80
- .optional()
81
- .describe("Hard cap on agentic LOOP iterations (each iteration = one Gemini generateContent + possible tool calls). Default 20. When the loop exhausts this cap without producing final-text, ONE additional non-tool `generateContent` (forced-finalization rescue) runs to synthesise an answer from gathered tool responses. **`structuredContent.apiCalls` is the authoritative total `generateContent` count** (loop iterations + 1 if the rescue dispatched, regardless of outcome). `convergenceForced: true` indicates ONLY that the rescue produced text successfully — an attempted-but-failed rescue increments `apiCalls` without setting `convergenceForced`. Rescue is bounded by `dailyBudgetUsd` and `iterationTimeoutMs`; see `maxTotalInputTokens` for the cap-overshoot contract. **v1.15.0:** rescue-attempted-but-failed paths additionally surface `structuredContent.rescueErrorCode` (`'TIMEOUT' | 'RATE_LIMIT' | 'INTERNAL' | 'API_ERROR' | 'NETWORK' | 'EMPTY_TEXT'`) + `rescueErrorMessage` (truncated to 500 chars) so wrappers can branch retry behaviour without log scraping. Retry policy: TIMEOUT → raise iterationTimeoutMs; RATE_LIMIT → wait retry-hint window; INTERNAL → investigate code (don't retry blindly); API_ERROR → check status (don't retry 4xx); NETWORK → safe to retry; EMPTY_TEXT → narrow prompt."),
82
- maxTotalInputTokens: z
83
- .number()
84
- .int()
85
- .min(10_000)
86
- .optional()
87
- .describe("Cumulative input-token budget across all iterations. Default 1_000_000. Loop iterations HARD-STOP past this cap (subReason: 'AGENTIC_INPUT_BUDGET_EXCEEDED'). The post-loop forced-finalization rescue is NOT gated on this cap — it may push cumulative tokens past by one call's worth, signalled via `overBudget: true` on the result. Rescue cost remains bounded by `dailyBudgetUsd`; wall-clock by `iterationTimeoutMs`."),
88
- maxFilesRead: z
89
- .number()
90
- .int()
91
- .min(1)
92
- .max(500)
93
- .optional()
94
- .describe('Cap on distinct files opened via `read_file` during this agentic call. Default 40.'),
95
- iterationTimeoutMs: z
96
- .number()
97
- .int()
98
- .min(1_000)
99
- .max(1_800_000)
100
- .optional()
101
- .describe("Per-iteration wall-clock timeout in ms (1s–30min). Each agentic iteration (one generateContent + possible tool calls + per-iteration TPM throttle wait) is bounded by this. **A single iteration that times out FAILS THE WHOLE agentic call** with `errorCode: 'TIMEOUT'` (the failed iteration's function-call results never came back, leaving the conversation structurally incomplete — continuing with partial state would 400 on the next turn). The post-loop forced-finalization rescue pass is ALSO bounded by this timeout, but its timeout behaviour DIFFERS: rescue timeouts are caught best-effort and fall through to the original `subReason: 'AGENTIC_MAX_ITERATIONS'` shape with `errorCode: 'UNKNOWN'` (NOT `'TIMEOUT'`) — the rescue is the documented exit path, and surfacing TIMEOUT for it would obscure the underlying maxIterations exhaustion. Operators detect rescue-attempted-but-failed via `apiCalls > iterations` and `convergenceForced` absent. Whole-loop budget is also bounded by `maxIterations` × `maxTotalInputTokens`. When omitted, falls back to env var `GEMINI_CODE_CONTEXT_AGENTIC_ITERATION_TIMEOUT_MS`, then to disabled."),
102
- stallMs: z
103
- .number()
104
- .int()
105
- .min(1_000)
106
- .max(600_000)
107
- .optional()
108
- .describe('Per-iteration HEARTBEAT-AWARE stall watchdog in ms (1s–10min). Resets on every chunk yielded by `generateContentStream` (text or thought) — fires ONLY when the stream goes silent for this long. Does NOT fire while the model is actively thinking. Right knob for "kill dead sockets quickly without penalising deep reasoning." Recommended: `60_000` (60s). Falls back to env var `GEMINI_CODE_CONTEXT_AGENTIC_STALL_MS`, then disabled. Returns `errorCode: "TIMEOUT"` with `timeoutKind: "stall"` on abort. Independent of `iterationTimeoutMs` — both can be set; whichever fires first wins. **Loop iterations only — the post-loop forced-finalization rescue pass keeps the v1.15.0 `apiCallSucceeded` non-streaming contract.**'),
109
- })
110
- .refine((data) => !(data.thinkingBudget !== undefined && data.thinkingLevel !== undefined), {
111
- message: 'Cannot specify both `thinkingBudget` and `thinkingLevel` — mutually exclusive (Gemini rejects).',
112
- path: [],
113
- });
114
- // ---------------------------------------------------------------------------
115
- // Defaults + limits
48
+ // Tool definition
116
49
  // ---------------------------------------------------------------------------
117
- const DEFAULT_MAX_ITERATIONS = 20;
118
- const DEFAULT_MAX_TOTAL_INPUT_TOKENS = 1_000_000;
119
- const DEFAULT_MAX_FILES_READ = 40;
50
+ export const askAgenticTool = {
51
+ name: 'ask_agentic',
52
+ title: 'Ask Gemini (agentic)',
53
+ description: "Surgical fallback for repos that exceed `ask`'s model input-token limit (~1M tokens for Gemini Pro), OR when you only need a handful of files (cheaper than eager-uploading a large repo). Gemini uses sandboxed file-access tools (`list_directory`, `find_files`, `read_file`, `grep`) to read only what it needs across multiple iterations (default 20). Cost profile: more API round trips than `ask`, but total tokens usually much smaller on big repos. **Wall-clock is structurally slower than `ask`** — each iteration pays ~30-60s of HIGH-thinking latency, so a 20-iter call can take 10-20 minutes. For the fast path, use `ask`. For oversize repos or focused investigation, use `ask_agentic`.",
54
+ schema: askAgenticInputSchema,
55
+ execute: (input, ctx) => runAskAgentic(input, ctx, AGENTIC_KNOB_NAMES),
56
+ };
120
57
  /**
121
- * Default cap on parallel tool-call dispatch within a single iteration.
122
- *
123
- * Bumped 3 → 10 in v1.15.1 (P9_a). Pre-bump rationale was "be conservative,
124
- * avoid hammering local filesystem I/O." Empirical: today's `read_file` /
125
- * `grep` / `find_files` run against the SQLite-backed manifest + workspace
126
- * mmap, all of which are CPU-bound and parallelism-friendly. The 3-wide cap
127
- * forced the model to serialise even small batches like 5 `read_file` calls
128
- * into 2 round-trips of the iteration loop, eating ~30-60s of HIGH-thinking
129
- * latency per artificial split. 10-wide handles the typical batch a Gemini
130
- * 3 Pro response emits without queuing.
131
- *
132
- * Operators can override via `GEMINI_CODE_CONTEXT_AGENTIC_TOOL_CONCURRENCY`
133
- * env var (clamped to [1, 50]) — kill switch for environments where
134
- * filesystem contention or local I/O bandwidth makes wider concurrency
135
- * counter-productive. v1.15.1+ telemetry gap: no per-call dispatch metric
136
- * yet exists; if a future release adds one, the env-override knob lets
137
- * operators dial back without code changes. (Tracked in `wiggly-twirling-karp.md`.)
58
+ * One `ask_agentic` call. `knobNames` are the knobs its timeout messages name: `ask_agentic`'s own, or `ask`'s when
59
+ * the call is `ask`'s fallback (its `timeoutMs` / `stallMs` became this call's `iterationTimeoutMs` / `stallMs`).
138
60
  */
139
- const DEFAULT_TOOL_EXECUTION_CONCURRENCY = 10;
140
- /** Read + clamp the tool-execution concurrency at dispatch time.
141
- *
142
- * Why a function not a top-level const: env vars can change between calls
143
- * within a long-lived MCP-server process (operator ctrl-Cs and re-launches
144
- * with a different value mid-session). Resolving per-call keeps behaviour
145
- * predictable. Cost: one env-read per iter; negligible vs the
146
- * `generateContent` round-trip dominating wall-clock.
147
- *
148
- * Clamps numeric inputs to `[1, 50]`. Only NaN / unset / empty falls back
149
- * to default. 50 cap prevents pathological "concurrency: 99999" misconfig
150
- * from spawning ~unbounded `read_file` Promise chains. 0 / negative inputs
151
- * clamp UP to 1 (= serial dispatch) — operators setting `0` or `-3` mean
152
- * "minimise parallelism", not "use the default" (the v1.15.1 PR-Round-1
153
- * 2-of-2 cross-reviewer correction: gemini-cli F2 + grok F1 flagged that
154
- * silently mapping operator-supplied `0` back to 10× was the opposite of
155
- * intent and a confusing UX on resource-constrained CI / Windows hosts).
156
- *
157
- * Exported for unit testing — not part of the public MCP surface. */
158
- export function resolveToolExecutionConcurrency() {
159
- const raw = process.env.GEMINI_CODE_CONTEXT_AGENTIC_TOOL_CONCURRENCY;
160
- if (raw === undefined || raw === '')
161
- return DEFAULT_TOOL_EXECUTION_CONCURRENCY;
162
- const parsed = Number.parseInt(raw, 10);
163
- // Only NaN (genuinely malformed input like `'banana'`) falls back to
164
- // default. Numeric inputs always clamp into [1, 50] so the operator's
165
- // stated intent (lower bound = serial; upper bound = throughput cap)
166
- // is honoured for any value parseInt can extract a number from.
167
- if (Number.isNaN(parsed))
168
- return DEFAULT_TOOL_EXECUTION_CONCURRENCY;
169
- return Math.max(1, Math.min(parsed, 50));
61
+ export function runAskAgentic(input, ctx, knobNames) {
62
+ const started = Date.now();
63
+ const rawWorkspaceRoot = resolve(input.workspace ?? process.cwd());
64
+ const model = input.model ?? ctx.config.defaultModel ?? 'latest-pro-thinking';
65
+ return executeAskAgenticBody({ input, ctx, rawWorkspaceRoot, model, started, knobNames });
170
66
  }
171
- /** If the SAME call signature (name + args) appears this many times, we
172
- * conclude the model is stuck in a loop and surface a partial answer.
173
- *
174
- * Bumped 3 → 5 in v1.14.4 after empirical replay (2026-04-30) showed
175
- * Gemini 3 Pro under `thinkingLevel: HIGH` legitimately re-emits the same
176
- * `grep` / `read_file` 3× as "double-checks" within its thought process —
177
- * not a stuck loop. Threshold-3 was tuned for 2.5 Pro and tripped before
178
- * `maxIterations`, killing the rescue path. Threshold-5 covers the empirical
179
- * double-check pattern with margin; `maxIterations` (default 20) and
180
- * `maxTotalInputTokens` (default 1M) remain the upper-bound safety nets.
181
- *
182
- * v1.15.0 will replace this with content-aware dedupe — same signature counts
183
- * toward the cap only if no new `read_file` against an unseen path happened
184
- * between repeats. (See `docs/FOLLOW-UP-PRS.md` for the planned rewrite.) */
185
- const NO_PROGRESS_CALL_THRESHOLD = 5;
186
- // ---------------------------------------------------------------------------
187
- // systemInstruction — prompt-injection defence + tool usage guidance
188
- // ---------------------------------------------------------------------------
189
- // Safety preamble — moved to `./shared/system-instruction-safety.ts` in v1.15.2
190
- // so `ask` and `code` can share the same firewall. See that module for the
191
- // full rationale + threat model. Two variants exist (AGENTIC vs EAGER) because
192
- // the data-vs-instruction wording must match the file-delivery channel.
193
- //
194
- // `ask_agentic` uses the AGENTIC variant (references the four agentic
195
- // executors that surface file content into `conversation`). The rescue pass
196
- // uses the same variant — even though tool dispatch is disabled on the
197
- // rescue, the conversation history still contains tool-response data that
198
- // could carry adversarial text, so the firewall stays in effect.
199
- const SYSTEM_INSTRUCTION_AGENTIC = [
200
- 'You are a senior code reviewer analysing a user codebase via sandboxed file-access tools.',
201
- '',
202
- SYSTEM_INSTRUCTION_SAFETY_AGENTIC,
203
- '',
204
- '# TOOLS AVAILABLE',
205
- '- `list_directory(path)` — list immediate children (files + subdirs) of a workspace-relative path. Start with `"."` to see the root.',
206
- '- `find_files(pattern)` — recursive glob (`*` any-except-slash, `**` any). Good for locating files by name without reading them.',
207
- '- `read_file(path, startLine?, endLine?)` — read a file (or slice). Responses are hard-capped at 200 KB; you will see `truncated: true` with `totalLines` metadata — page through large files via startLine/endLine.',
208
- '- `grep(pattern, pathPrefix?)` — JS RegExp search. Great for finding symbols before opening files.',
209
- '',
210
- '# STRATEGY',
211
- 'Prefer narrow tool calls over wide ones. A typical flow:',
212
- '1. Scout with `list_directory(".")` or `find_files("**/*.ts")`',
213
- '2. Locate relevant symbols with `grep`',
214
- '3. Open only the handful of files that actually bear on the question via `read_file`',
215
- 'When you have enough context, respond with a plain-text answer and make NO further tool calls.',
216
- 'Batch your tool calls within a single iteration. If you need to read 5 files, issue all 5 `read_file` calls in ONE turn rather than one-per-iteration across 5 turns — each iteration costs 30-60s of thinking-token latency that you only pay once when calls are batched. The dispatcher runs the batch in parallel (up to 10 concurrent by default). Only batch calls for paths you have already seen in prior tool results (e.g., from `list_directory`, `find_files`, or `grep` output) or that the user provided. Never synthesize or guess additional paths solely to fill a batch — a hallucinated path costs the same iteration latency as the split you were trying to avoid, and the executors will reject it.',
217
- '',
218
- '# DECISIVENESS',
219
- "Be decisive. Once you have read the relevant files and gathered evidence, produce your final answer. Continuing to call tools when you already have an answer is a failure mode — it wastes the user's budget and delays the response.",
220
- 'When the user provides a complete diff inline, your primary task is reasoning ABOUT the diff. Read each touched file at most once unless a specific concern requires re-reading; do not recursively explore the project tree to verify what the diff already shows.',
221
- 'A focused investigation typically converges in 3–8 iterations. If you find yourself on iteration 10+ still calling tools, stop and synthesize what you know — state findings as Known / Unknown / Next checks rather than chasing completeness.',
222
- '',
223
- '# OUTPUT',
224
- "Your final response (the one with no function calls) should directly answer the user's prompt. Cite specific `file:line` when referring to code. Be concrete; do not speculate beyond what you read.",
225
- ].join('\n');
226
67
  /**
227
- * Forced-finalization system instruction. Sent on the post-loop synthesis
228
- * pass when the iteration budget is exhausted. Combined with
229
- * `toolConfig.functionCallingConfig.mode = NONE`, the model is prohibited
230
- * from emitting further function calls (per Gemini API spec, NONE mode is
231
- * "equivalent to sending a request without any function declarations") and
232
- * must answer with text using the conversation it has already accumulated.
233
- *
234
- * Tightened in v1.14.4 after empirical replay (2026-04-30) showed Gemini 3 Pro
235
- * under HIGH thinking treating the previous "Synthesize the evidence ... in
236
- * the format the user originally requested" wording as an invitation to
237
- * narrate its thought process — producing stream-of-consciousness output
238
- * instead of the structured findings the caller requested. The CRITICAL
239
- * OUTPUT INSTRUCTIONS block below is authoritative ordering: parse the
240
- * caller's format spec, synthesize evidence into it, no preamble, no narrative,
241
- * no apologies. The user's original prompt (with any output-format directive)
242
- * is preserved across the rescue via `contents[0]`, so the model has the
243
- * format spec available — the system instruction's job is to enforce
244
- * compliance.
245
- *
246
- * SAFETY: this rescue runs with `mode: NONE` (tools disabled) but still
247
- * evaluates the FULL conversation history including any malicious payloads
248
- * surfaced by prior `read_file` / `grep` results (LLM calls are stateless
249
- * per Gemini API semantics — each turn's output is generated under THAT
250
- * turn's systemInstruction). The shared `SYSTEM_INSTRUCTION_SAFETY_AGENTIC` block
251
- * (data-vs-instruction firewall) is therefore prepended below. A 3-of-3
252
- * cross-reviewer audit on 2026-04-30 (gemini-cli + gemini-chat + grok)
253
- * flagged the prior absence as an indirect-prompt-injection vector.
254
- *
255
- * v1.15.0 (C2): citation directive conditionalised symmetrically with the
256
- * "Unknown" handling — both gemini-chat (Round-2) and Copilot (Round-1)
257
- * flagged the v1.14.4 unconditional `Cite specific file:line` as a
258
- * potential format-break for strict JSON / fixed-shape outputs (e.g., a
259
- * pure JSON array of strings can't carry `(file:42)` annotations without
260
- * mutating the data). Now reads "ONLY where the requested format provides
261
- * a compatible place to put citations".
68
+ * Validate the workspace and canonicalise its root (symlink-resolved) so every tool call resolves
69
+ * against the same canonical path; the downstream sandbox compares against this root.
262
70
  */
263
- const SYSTEM_INSTRUCTION_FINALIZATION = [
264
- SYSTEM_INSTRUCTION_SAFETY_AGENTIC,
265
- '',
266
- 'You are wrapping up an investigation. The conversation history above already contains the tool responses you have gathered.',
267
- 'Your iteration budget is now exhausted. You CANNOT call any more tools — function calling is disabled for this turn.',
268
- '',
269
- 'CRITICAL OUTPUT INSTRUCTIONS:',
270
- "1. PARSE the user's original prompt for exact output format specifications (e.g., markdown headers, JSON shape, tables).",
271
- '2. STRICTLY follow that requested structure.',
272
- '3. Synthesize the gathered evidence into the final answer and output it DIRECTLY in the requested structure. Provide NO preamble, NO apologies, NO "Here is the summary", and NO internal thinking or narrative notes.',
273
- '',
274
- 'If some details remain unverified, integrate an "Unknown" element ONLY if it is compatible with the parsed output shape (e.g., adds a row to a table, a field to a JSON object, a sub-bullet under a heading); never add extraneous keys or sections that would invalidate the requested format. Cite specific `file:line` for the claims you can support — but ONLY where the requested format provides a compatible place to put citations (e.g., a sub-bullet, an additional column, embedded inside an existing string field); never break the requested structure to add citations.',
275
- ].join('\n');
276
- // ---------------------------------------------------------------------------
277
- // Function declarations — these get serialised and sent to Gemini so the
278
- // model knows which tools it may invoke + what arguments each takes.
279
- // ---------------------------------------------------------------------------
280
- function buildFunctionDeclarations() {
281
- // Schemas use the SDK's Upper-Case type enum values (`STRING`, `INTEGER`,
282
- // `OBJECT`). Literal strings are accepted by the SDK — we avoid pulling
283
- // in the full `Type` enum here to keep imports minimal.
284
- const stringProp = (description) => ({ type: GeminiType.STRING, description });
285
- const intProp = (description) => ({ type: GeminiType.INTEGER, description });
286
- return [
287
- {
288
- name: 'list_directory',
289
- description: 'List the immediate children (files + subdirectories) of a workspace-relative directory path. Does NOT recurse. Excluded directories (node_modules, .git, .next, etc.) and denylisted filenames (lockfiles, .env, etc.) are silently filtered out.',
290
- parameters: {
291
- type: GeminiType.OBJECT,
292
- properties: {
293
- path: stringProp('Workspace-relative directory path. Use "." for the workspace root. No leading `/`.'),
294
- },
295
- required: ['path'],
296
- },
297
- },
298
- {
299
- name: 'find_files',
300
- description: 'Recursive glob search for files under the workspace root. Supports `*` (match any character except `/`) and `**` (match any character including `/`). Examples: `**/*.ts`, `src/**/index.*`, `README.md`. Respects the same default excludes as list_directory.',
301
- parameters: {
302
- type: GeminiType.OBJECT,
303
- properties: {
304
- pattern: stringProp('Glob pattern relative to workspace root. Uses `*` and `**` only (no `?`, no character classes, no `{a,b}`). Match is anchored — the pattern must match the whole relative path.'),
305
- },
306
- required: ['pattern'],
307
- },
308
- },
309
- {
310
- name: 'read_file',
311
- description: 'Read a file from the workspace, optionally a line-range slice. Responses are hard-capped at 200 KB; if the file is larger you get a head-truncated slice with `truncated: true` and `totalLines` metadata. Call again with `startLine` / `endLine` to page through. Rejects binary / non-source extensions.',
312
- parameters: {
313
- type: GeminiType.OBJECT,
314
- properties: {
315
- path: stringProp('Workspace-relative file path.'),
316
- startLine: intProp('1-indexed inclusive start line. Omit for line 1.'),
317
- endLine: intProp('1-indexed inclusive end line. Omit to read until the default or byte cap kicks in.'),
318
- },
319
- required: ['path'],
320
- },
321
- },
322
- {
323
- name: 'grep',
324
- description: 'Regular-expression search through source files in the workspace. Pattern is compiled as a JavaScript RegExp (standard metacharacters). Each match line is capped at 500 characters. At most 100 matches per call.',
325
- parameters: {
326
- type: GeminiType.OBJECT,
327
- properties: {
328
- pattern: stringProp('JavaScript regular-expression pattern (unanchored, no flags).'),
329
- pathPrefix: stringProp('Optional: limit search to files under this workspace-relative directory prefix.'),
330
- },
331
- required: ['pattern'],
332
- },
333
- },
334
- ];
335
- }
336
- async function dispatchToolCall(workspaceRoot, name, args, matchConfig) {
337
- const started = Date.now();
71
+ async function openWorkspace(rawWorkspaceRoot) {
72
+ const refusal = workspaceRefusal('ask_agentic', rawWorkspaceRoot);
73
+ if (refusal !== null)
74
+ return { refused: refusal };
338
75
  try {
339
- let response;
340
- switch (name) {
341
- case 'list_directory': {
342
- const path = String(args.path ?? '.');
343
- response = (await listDirectoryExecutor(workspaceRoot, path, matchConfig));
344
- break;
345
- }
346
- case 'find_files': {
347
- const pattern = String(args.pattern ?? '');
348
- response = (await findFilesExecutor(workspaceRoot, pattern, matchConfig));
349
- break;
350
- }
351
- case 'read_file': {
352
- const path = String(args.path ?? '');
353
- const startLine = typeof args.startLine === 'number' && Number.isFinite(args.startLine)
354
- ? args.startLine
355
- : undefined;
356
- const endLine = typeof args.endLine === 'number' && Number.isFinite(args.endLine)
357
- ? args.endLine
358
- : undefined;
359
- response = (await readFileExecutor(workspaceRoot, path, startLine, endLine, matchConfig));
360
- break;
361
- }
362
- case 'grep': {
363
- const pattern = String(args.pattern ?? '');
364
- const pathPrefix = typeof args.pathPrefix === 'string' && args.pathPrefix.length > 0
365
- ? args.pathPrefix
366
- : undefined;
367
- response = (await grepExecutor(workspaceRoot, pattern, pathPrefix, matchConfig));
368
- break;
369
- }
370
- default:
371
- // Unknown function name — return an error response rather than
372
- // throwing. The model may recover by picking a valid tool.
373
- return {
374
- name,
375
- response: { error: `unknown tool: ${name}` },
376
- durationMs: Date.now() - started,
377
- isError: true,
378
- };
379
- }
380
- return { name, response, durationMs: Date.now() - started, isError: false };
76
+ return { root: await resolveWorkspaceRoot(rawWorkspaceRoot) };
381
77
  }
382
78
  catch (err) {
383
- // SandboxError and anything else that happens in the executor: surface
384
- // as recoverable `response.error` so the model can try a different
385
- // path. Hard failures (e.g. filesystem I/O errors) follow the same path
386
- // — the worst case is we waste one iteration.
387
- const message = err instanceof SandboxError
388
- ? `${err.code}: ${err.message}`
389
- : err instanceof Error
390
- ? err.message
391
- : String(err);
392
- // Ops-side observability for excludeGlobs misconfigurations (v1.9.0
393
- // Phase 1.2, /6step Finding B): the user-visible `.message` for
394
- // `EXCLUDED_FILE` and `EXCLUDED_DIR` is deliberately path-free to
395
- // close the existence-probe oracle (Phase 1.1 Findings #1 + #2).
396
- // Without this debug log, an operator helping a user debug "why is
397
- // ask_agentic refusing my file?" has no way to map the generic error
398
- // back to a specific path. The `requestedPath` field on SandboxError
399
- // was preserved for exactly this purpose; surface it at debug level
400
- // so prod log volume stays unchanged but ops can opt in via
401
- // `GEMINI_CODE_CONTEXT_LOG_LEVEL=debug`.
402
- if (err instanceof SandboxError) {
403
- // NOTE (v1.9.0 self-review S4): no direct regression test on this emit
404
- // path. The Phase 1.1 test pins `requestedPath` is set on SandboxError
405
- // (the input contract this branch consumes), and `safeForLog` has its
406
- // own 18-test coverage in `test/unit/logger.test.ts`. But "the
407
- // dispatcher actually CALLS logger.debug on SandboxError" is verified
408
- // by visual review only — if you remove or refactor this block,
409
- // existing tests will not catch the regression. If you change anything
410
- // here, please add a `vi.spyOn(logger, 'debug')` test that runs an
411
- // agentic scenario through `askAgenticTool.execute` with an
412
- // excludeGlobs config and asserts the spy received a string starting
413
- // with `agentic dispatch refused:`.
414
- logger.debug(`agentic dispatch refused: tool=${safeForLog(name)} code=${safeForLog(err.code)} requestedPath=${safeForLog(err.requestedPath)}`);
415
- }
416
79
  return {
417
- name,
418
- response: { error: message },
419
- durationMs: Date.now() - started,
420
- isError: true,
80
+ refused: errorResult(`ask_agentic: workspace not accessible: ${err instanceof Error ? err.message : String(err)}`, { errorCode: 'UNKNOWN', retryable: false }),
421
81
  };
422
82
  }
423
83
  }
424
- /** Run up to `concurrency` dispatches in parallel, preserving call order. */
425
- async function dispatchToolCallsParallel(workspaceRoot, calls, concurrency, matchConfig) {
426
- const results = new Array(calls.length);
427
- let next = 0;
428
- const worker = async () => {
429
- while (next < calls.length) {
430
- const i = next;
431
- next += 1;
432
- const call = calls[i];
433
- if (!call)
434
- continue;
435
- results[i] = await dispatchToolCall(workspaceRoot, call.name, call.args, matchConfig);
436
- }
84
+ /** A thinking budget the output cap cannot hold is refused locally, so the model never answers a 400
85
+ * "thinking exceeds output budget". */
86
+ function thinkingRefusal(input) {
87
+ const budgetRefusal = thinkingBudgetRefusal(input.thinkingBudget, input.maxOutputTokens, input.maxOutputTokens ?? 0);
88
+ if (budgetRefusal === null)
89
+ return null;
90
+ return errorResult(`ask_agentic: ${budgetRefusal}`, {
91
+ errorCode: 'UNKNOWN',
92
+ retryable: false,
93
+ subReason: 'INVALID_THINKING_OUTPUT_COMBO',
94
+ });
95
+ }
96
+ /**
97
+ * Build the user-glob filter once at entry — the same `MatchConfig` gets threaded through every
98
+ * executor invocation in the loop. v1.9.0+ Phase 1 closes the privacy gap that previously dropped
99
+ * user-supplied `excludeGlobs` whenever a caller (or an `ask` → `ask_agentic` fallback) targeted the
100
+ * agentic loop. Returns the run, or the refusal of a thinking budget the output cap cannot hold.
101
+ */
102
+ function startRun(call, resolved, workspaceRoot) {
103
+ const { input, ctx, emitter } = call;
104
+ const limits = runLimitsOf(input);
105
+ const matchConfig = defaultMatchConfig({
106
+ ...(input.includeGlobs !== undefined ? { includeGlobs: input.includeGlobs } : {}),
107
+ ...(input.excludeGlobs !== undefined ? { excludeGlobs: input.excludeGlobs } : {}),
108
+ });
109
+ const refusal = thinkingRefusal(input);
110
+ if (refusal !== null)
111
+ return { refused: refusal };
112
+ const baseConfig = baseConfigOf(input);
113
+ emitter.emit('starting agentic loop…');
114
+ const knobs = resolveAgenticKnobs(input);
115
+ const budget = passBudgetOf(input, ctx, knobs);
116
+ const { started, knobNames } = call;
117
+ return {
118
+ run: {
119
+ input,
120
+ ctx,
121
+ emitter,
122
+ resolved,
123
+ workspaceRoot,
124
+ started,
125
+ limits,
126
+ matchConfig,
127
+ baseConfig,
128
+ budget,
129
+ knobs,
130
+ knobNames: messageKnobNames(knobNames, knobs),
131
+ },
437
132
  };
438
- const workers = Array.from({ length: Math.max(1, Math.min(concurrency, calls.length)) }, worker);
439
- await Promise.all(workers);
440
- return results;
441
133
  }
442
- // ---------------------------------------------------------------------------
443
- // Tool definition
444
- // ---------------------------------------------------------------------------
445
- export const askAgenticTool = {
446
- name: 'ask_agentic',
447
- title: 'Ask Gemini (agentic)',
448
- description: "Surgical fallback for repos that exceed `ask`'s model input-token limit (~1M tokens for Gemini Pro), OR when you only need a handful of files (cheaper than eager-uploading a large repo). Gemini uses sandboxed file-access tools (`list_directory`, `find_files`, `read_file`, `grep`) to read only what it needs across multiple iterations (default 20). Cost profile: more API round trips than `ask`, but total tokens usually much smaller on big repos. **Wall-clock is structurally slower than `ask`** — each iteration pays ~30-60s of HIGH-thinking latency, so a 20-iter call can take 10-20 minutes. For the fast path, use `ask`. For oversize repos or focused investigation, use `ask_agentic`.",
449
- schema: askAgenticInputSchema,
450
- async execute(input, ctx) {
451
- const started = Date.now();
452
- const workspaceRoot = resolve(input.workspace ?? process.cwd());
453
- const model = input.model ?? ctx.config.defaultModel ?? 'latest-pro-thinking';
454
- return executeAskAgenticBody(input, ctx, workspaceRoot, model, started);
455
- },
456
- };
457
- async function executeAskAgenticBody(input, ctx, rawWorkspaceRoot, model, started) {
134
+ /**
135
+ * The call after the workspace is open: resolve the model, run the loop, and — when it exhausted
136
+ * `maxIterations` without an answer — the forced-finalization pass. `resolveModel` either returns a
137
+ * ResolvedModel or throws; the `undefined` check only narrows the type.
138
+ */
139
+ async function answerAgentic(call, progress) {
140
+ const workspace = await openWorkspace(call.rawWorkspaceRoot);
141
+ if ('refused' in workspace)
142
+ return workspace.refused;
143
+ call.emitter.emit(`resolving model '${call.model}'…`);
144
+ progress.resolved = await resolveModel(call.model, call.ctx.client, {
145
+ requiredCategory: ['text-reasoning', 'text-fast', 'text-lite'],
146
+ });
147
+ const resolved = progress.resolved;
148
+ if (!resolved)
149
+ throw new Error('ask_agentic: resolveModel returned undefined (unreachable)');
150
+ const start = startRun(call, resolved, workspace.root);
151
+ if ('refused' in start)
152
+ return start.refused;
153
+ const { run } = start;
154
+ const state = newLoopState(call.input.prompt);
155
+ progress.loop = state;
156
+ const ended = await runLoop(run, state);
157
+ if (ended !== null)
158
+ return ended;
159
+ const rescue = await runRescue(run, state);
160
+ return maxIterationsResult(run, state, rescue);
161
+ }
162
+ /**
163
+ * Any failure the loop did not shape. A 429 thrown POST-resolution seeds the throttle hint for the
164
+ * resolved model unless an inner catch already seeded it (`seedRetryHint` records each 429 once — an
165
+ * iteration's 429 is re-thrown to here). PRE-RESOLUTION 429s (Google rate-limiting `models.list()` during the very first call after
166
+ * API-key rotation or quota reset) still DISCARD the hint: recording it against the unresolved alias
167
+ * (e.g. 'latest-pro-thinking') would key the throttle hint to a string that future calls won't match
168
+ * — they'd resolve to a literal model id, miss the alias-keyed hint, retry too soon. (Pinned by the
169
+ * `outer-catch 429 from PRE-resolution path... does NOT seed hint` test.) A loop iteration booked
170
+ * before it failed (its stream had ended) reports its billed fields.
171
+ */
172
+ function failedCall(err, ctx, progress) {
173
+ logger.error(`ask_agentic failed: ${safeForLog(err)}`);
174
+ const httpStatus = err.status;
175
+ if (typeof progress.resolved?.resolved === 'string') {
176
+ seedRetryHint(ctx.throttle, progress.resolved.resolved, err);
177
+ }
178
+ return errorResult(`ask_agentic failed: ${err instanceof Error ? err.message : String(err)}`, {
179
+ errorCode: 'UNKNOWN',
180
+ retryable: false,
181
+ ...(httpStatus !== undefined ? { httpStatus } : {}),
182
+ ...(progress.loop?.failedPassBilled ?? {}),
183
+ });
184
+ }
185
+ async function executeAskAgenticBody(request) {
186
+ const { ctx } = request;
458
187
  const emitter = createProgressEmitter(ctx.server, ctx.progressToken);
459
- // v1.14.3: hoisted out of the inner try so the outer catch can access the
460
- // resolved model name when seeding throttle hints from 429s thrown during
461
- // model resolution (`resolveModel.list()` can 429 too — pre-fix that path
462
- // had no hint extraction at all). Declared with `Awaited<ReturnType<...>>`
463
- // inline to avoid importing `ResolvedModel` just for this site.
464
- let resolved;
188
+ const progress = { resolved: undefined, loop: undefined };
465
189
  try {
466
- try {
467
- validateWorkspacePath(rawWorkspaceRoot);
468
- }
469
- catch (err) {
470
- if (err instanceof WorkspaceValidationError) {
471
- return errorResult(`ask_agentic: ${err.message}`);
472
- }
473
- throw err;
474
- }
475
- // Canonicalise the workspace root (symlink-resolved) so every tool call
476
- // resolves against the same canonical path. Downstream sandbox compares
477
- // against this root.
478
- let workspaceRoot;
479
- try {
480
- workspaceRoot = await resolveWorkspaceRoot(rawWorkspaceRoot);
481
- }
482
- catch (err) {
483
- return errorResult(`ask_agentic: workspace not accessible: ${err instanceof Error ? err.message : String(err)}`, { errorCode: 'UNKNOWN', retryable: false });
484
- }
485
- emitter.emit(`resolving model '${model}'…`);
486
- resolved = await resolveModel(model, ctx.client, {
487
- requiredCategory: ['text-reasoning', 'text-fast', 'text-lite'],
488
- });
489
- // Narrow `resolved` to non-undefined for the rest of the body — closure
490
- // captures (e.g., the rescue's `withNetworkRetry` lambda at line ~1003)
491
- // would otherwise see the hoisted `let resolved: ... | undefined` type.
492
- // `resolveModel` either returns ResolvedModel or throws (per its
493
- // signature), so this assertion never fires; it's a TS-narrowing helper.
494
- if (!resolved)
495
- throw new Error('ask_agentic: resolveModel returned undefined (unreachable)');
496
- const maxIterations = input.maxIterations ?? DEFAULT_MAX_ITERATIONS;
497
- const maxTotalInputTokens = input.maxTotalInputTokens ?? DEFAULT_MAX_TOTAL_INPUT_TOKENS;
498
- const maxFilesRead = input.maxFilesRead ?? DEFAULT_MAX_FILES_READ;
499
- // Build the user-glob filter once at entry — the same `MatchConfig`
500
- // gets threaded through every executor invocation in the loop. v1.9.0+
501
- // Phase 1 closes the privacy gap that previously dropped user-supplied
502
- // `excludeGlobs` whenever a caller (or an `ask` → `ask_agentic`
503
- // fallback in Phase 3) targeted the agentic loop.
504
- const matchConfig = defaultMatchConfig({
505
- ...(input.includeGlobs !== undefined ? { includeGlobs: input.includeGlobs } : {}),
506
- ...(input.excludeGlobs !== undefined ? { excludeGlobs: input.excludeGlobs } : {}),
507
- });
508
- // Refused locally, so the model never answers a 400 "thinking exceeds output budget".
509
- const budgetRefusal = thinkingBudgetRefusal(input.thinkingBudget, input.maxOutputTokens, input.maxOutputTokens ?? 0);
510
- if (budgetRefusal !== null) {
511
- return errorResult(`ask_agentic: ${budgetRefusal}`, {
512
- errorCode: 'UNKNOWN',
513
- retryable: false,
514
- subReason: 'INVALID_THINKING_OUTPUT_COMBO',
515
- });
516
- }
517
- const thinkingConfig = (() => {
518
- if (input.thinkingLevel !== undefined) {
519
- return {
520
- thinkingLevel: input.thinkingLevel,
521
- includeThoughts: true,
522
- };
523
- }
524
- if (input.thinkingBudget !== undefined) {
525
- return { thinkingBudget: input.thinkingBudget, includeThoughts: true };
526
- }
527
- return { includeThoughts: true };
528
- })();
529
- const baseConfig = {
530
- systemInstruction: SYSTEM_INSTRUCTION_AGENTIC,
531
- tools: [{ functionDeclarations: buildFunctionDeclarations() }],
532
- thinkingConfig,
533
- ...(input.maxOutputTokens !== undefined ? { maxOutputTokens: input.maxOutputTokens } : {}),
534
- // One request per model call: a response that stops with `CONTINUATION` is never continued here (long decode
535
- // is `ask` / `code` only, `shared/continuation.ts`).
536
- automaticContinuation: false,
537
- };
538
- const conversation = [{ role: 'user', parts: [{ text: input.prompt }] }];
539
- /** Call-signature → state, for content-aware no-progress detection.
540
- *
541
- * v1.16.0 (P2 Phase B): replaces the v1.14.4 simple counter with a
542
- * content-aware version. Pre-Phase-B `signatureCounts: Map<string,
543
- * number>` tracked repeat occurrences of the same signature and
544
- * tripped after N repeats even if the model had made progress
545
- * elsewhere since an earlier occurrence. That was empirically wrong
546
- * on 2026-04-30 — Gemini 3 Pro under HIGH thinking re-runs the same
547
- * `grep` while ALSO reading new files, which IS progress, but the
548
- * simple counter still tripped.
549
- *
550
- * Phase B tracks `lastFilesReadSize` per signature: same signature
551
- * counts toward the threshold ONLY if no `read_file` against an
552
- * unseen path happened between repeats. If `filesReadSet` grew
553
- * since the previous identical signature, count resets to 1
554
- * (current call) — the model is exploring, not stuck.
555
- *
556
- * Why `read_file` specifically and not all tool calls? `list_directory`
557
- * / `find_files` / `grep` are exploration without commitment. They
558
- * tell us where to look but don't capture content into the
559
- * conversation. `read_file` is the progress signal — it means
560
- * "I found something worth examining" and grows the conversation
561
- * the rescue path will replay.
562
- *
563
- * Threshold (NO_PROGRESS_CALL_THRESHOLD = 5) unchanged from v1.14.4
564
- * — Phase B refines the SIGNAL, not the cap. Hard upper bound
565
- * remains `maxIterations` × `maxTotalInputTokens`. */
566
- const signatureCounts = new Map();
567
- const filesReadSet = new Set();
568
- let cumulativeInputTokens = 0;
569
- let cumulativeOutputTokens = 0;
570
- let cumulativeThinkingTokens = 0;
571
- // P5 (v1.15.0): approximate token count of the tool-response Parts
572
- // appended to `conversation` after the most recent iteration's
573
- // `generateContent` returned. Folded into the rescue's
574
- // `finalizationEstimate` so its TPM/budget reservation covers the data
575
- // the rescue actually replays. Pre-P5 the estimate omitted this delta;
576
- // with the parallel tool-dispatch (default 10 in v1.15.1+, was 3
577
- // pre-bump) reading large files, the rescue could under-reserve by
578
- // 100k+ tokens and 429 mid-flight.
579
- let lastToolResponseTokens = 0;
580
- let iterations = 0;
581
- // Tracks the most recent iteration's actual `promptTokenCount` (size of the
582
- // conversation as sent in the LAST loop iter). Used by the v1.14.2
583
- // forced-finalization rescue's TPM-reservation estimate (line ~910) — the
584
- // rescue replays the same accumulated history, so its real prompt size
585
- // ≈ this value, not the static `PER_ITERATION_INPUT_TOKENS = 50_000` that
586
- // under-reserves by 4–6× on a 20-iter loop with file reads. Stays 0 if the
587
- // loop never produced a usage record (defensive — falls back to the static
588
- // estimate at the use site).
589
- let lastIterationPromptTokens = 0;
590
- emitter.emit('starting agentic loop…');
591
- // Conservative per-iteration cost estimate for the pre-iteration
592
- // budget reservation. An agentic iter typically sends a few KB of
593
- // prompt + accumulated tool responses + model thinking + short output.
594
- // We over-estimate on purpose so `reserveBudget` atomicity catches
595
- // overspend early rather than silently racing past the cap. PR #24
596
- // review by Grok (P0: budget bypass on agentic path).
597
- const PER_ITERATION_INPUT_TOKENS = 50_000;
598
- const PER_ITERATION_OUTPUT_TOKENS = typeof input.maxOutputTokens === 'number' ? input.maxOutputTokens : 4096;
599
- // The longest an iteration (or the finalization pass) can run: the window
600
- // each reservation covers.
601
- const iterationCoverMs = resolveTotalTimeoutMs(input.iterationTimeoutMs, 'GEMINI_CODE_CONTEXT_AGENTIC_ITERATION_TIMEOUT_MS');
602
- /** One pass's reservation, at the rates in force from now until its timeout. */
603
- const reservedModel = resolved.resolved;
604
- const passReservationUsd = (inputTokens) => estimateReservationUsd({
605
- model: reservedModel,
606
- uncachedInputTokens: inputTokens,
607
- cachedInputTokens: 0,
608
- outputTokens: PER_ITERATION_OUTPUT_TOKENS,
609
- thinkingTokens: PER_ITERATION_OUTPUT_TOKENS,
610
- }, iterationCoverMs);
611
- const dailyBudgetEnforced = Number.isFinite(ctx.config.dailyBudgetUsd);
612
- const tpmEnforced = ctx.config.tpmThrottleLimit > 0;
613
- while (iterations < maxIterations) {
614
- iterations += 1;
615
- // Priced per iteration, covering the rates in force until its timeout: a
616
- // loop that crosses a price change reserves at the new rate, so each
617
- // reservation stays an upper bound of what its settlement books.
618
- const perIterationCostUsd = passReservationUsd(PER_ITERATION_INPUT_TOKENS);
619
- // Per-iteration budget reservation (mirrors ask.tool.ts). Each
620
- // iteration is an independent generateContent billable, so each
621
- // gets its own reservation/finalize pair. Budget ledger stays
622
- // accurate across the full loop.
623
- let reservationId = null;
624
- if (dailyBudgetEnforced) {
625
- const reserve = ctx.manifest.reserveBudget({
626
- workspaceRoot,
627
- toolName: 'ask_agentic',
628
- model: resolved.resolved,
629
- estimatedCostMicros: toMicrosUsd(perIterationCostUsd),
630
- dailyBudgetMicros: toMicrosUsd(ctx.config.dailyBudgetUsd),
631
- nowMs: Date.now(),
632
- });
633
- if ('rejected' in reserve) {
634
- const spentUsd = reserve.spentMicros / 1_000_000;
635
- return errorResult(`Daily budget cap would be exceeded: spent $${spentUsd.toFixed(4)} + estimate $${perIterationCostUsd.toFixed(4)} > cap $${ctx.config.dailyBudgetUsd.toFixed(2)}. Retry after UTC midnight, or raise GEMINI_DAILY_BUDGET_USD.`, {
636
- errorCode: 'BUDGET_REJECT',
637
- retryable: false,
638
- iterations,
639
- // BUDGET_REJECT is pre-dispatch — `iterations` was incremented
640
- // at the top of the loop body, but this iteration's
641
- // `generateContent` never fired. Subtract 1 to match the
642
- // schema contract that `apiCalls` is the AUTHORITATIVE total
643
- // generateContent count. `Math.max(0, ...)` guards the
644
- // first-iteration-rejection edge (iter 1 + reject → 0 calls).
645
- apiCalls: Math.max(0, iterations - 1),
646
- cumulativeInputTokens,
647
- });
648
- }
649
- reservationId = reserve.id;
650
- }
651
- // Per-iteration timeout — created BEFORE the throttle wait so the
652
- // wait itself is bounded by the iteration timeout. (If iterTimeout
653
- // is created after the wait, a 60s throttle delay can blow past a
654
- // 10s iterationTimeoutMs without ever firing.) Disposed in finally.
655
- // v1.16.2 (T33 TRIM): the loop now streams via `generateContentStream`
656
- // + `collectStream`, so `recordChunk()` is wired in to reset the stall
657
- // watchdog on every text/thought chunk. The TPM throttle wait that
658
- // precedes the dispatch has no chunks to record — `stallMs` only
659
- // governs the stream itself; the wall-clock `totalMs` still bounds
660
- // the throttle wait. Composite signal still fires on whichever cap
661
- // hits first. Rescue path uses non-streaming `generateContent` and
662
- // keeps an empty `stallEnvVar` — see the rescue site below.
663
- const iterTimeout = createTimeoutController({
664
- ...(input.iterationTimeoutMs !== undefined ? { totalMs: input.iterationTimeoutMs } : {}),
665
- totalEnvVar: 'GEMINI_CODE_CONTEXT_AGENTIC_ITERATION_TIMEOUT_MS',
666
- ...(input.stallMs !== undefined ? { stallMs: input.stallMs } : {}),
667
- stallEnvVar: 'GEMINI_CODE_CONTEXT_AGENTIC_STALL_MS',
668
- });
669
- // Per-iteration TPM throttle reservation + iteration call. Both must
670
- // run INSIDE the same try/catch so that a timeout firing during the
671
- // throttle wait — `abortableSleep` rejects with the iter timeout's
672
- // TimeoutError — flows through the same cancel/finalise/TIMEOUT-map
673
- // path as a timeout firing during the SDK call. Earlier shape
674
- // wrapped only `runAgenticIteration`, leaving an aborted throttle
675
- // wait to escape to the outer catch with `errorCode: 'UNKNOWN'` AND
676
- // both reservations leaked (budget over-counts, TPM bucket holds
677
- // `releaseId` forever). Surfaced by the F3 unit test below.
678
- let throttleReservationId = -1;
679
- let iterResult;
680
- const iterStarted = Date.now();
681
- // H2 fix: track whether this iteration's `generateContent` was
682
- // actually dispatched. The iter timeout can fire DURING `abortableSleep`
683
- // (TPM throttle wait, BEFORE runAgenticIteration is called) — in that
684
- // case no API call happened for this iter and `apiCalls` must subtract
685
- // it. Set true immediately before runAgenticIteration so any throw
686
- // after that point counts the dispatched call.
687
- let iterDispatched = false;
688
- try {
689
- if (tpmEnforced) {
690
- const reservation = ctx.throttle.reserve(resolved.resolved, PER_ITERATION_INPUT_TOKENS);
691
- throttleReservationId = reservation.releaseId;
692
- if (reservation.delayMs > 0) {
693
- emitter.emit(`throttle: waiting ${Math.ceil(reservation.delayMs / 1000)}s for TPM window…`);
694
- // Abortable so iteration timeout interrupts the wait.
695
- await abortableSleep(reservation.delayMs, iterTimeout.signal);
696
- }
697
- }
698
- // H2: about to dispatch generateContent. Any throw past this point
699
- // counts the iter as having made an API call (Gemini may bill
700
- // server-side even on aborted-mid-flight calls).
701
- iterDispatched = true;
702
- iterResult = await runAgenticIteration({
703
- ctx,
704
- resolvedModel: resolved.resolved,
705
- conversation,
706
- baseConfig,
707
- workspaceRoot,
708
- filesReadSet,
709
- maxFilesRead,
710
- abortSignal: iterTimeout.signal,
711
- matchConfig,
712
- // v1.16.2 (T33 TRIM): wire stall watchdog reset + live thought
713
- // surfacing. `recordChunk` is the bridge that makes `stallMs`
714
- // heartbeat-aware — it fires on every text/thought chunk arrival.
715
- // `onThoughtChunk` mirrors the ask/code streaming UX so operators
716
- // see model reasoning progress live instead of waiting for the
717
- // 30-120s iteration to complete.
718
- recordChunk: () => iterTimeout.recordChunk(),
719
- onThoughtChunk: (text) => {
720
- const trimmed = text.trim().slice(0, 80);
721
- if (trimmed.length > 0)
722
- emitter.emit(`thinking: ${trimmed}…`);
723
- },
724
- });
725
- }
726
- catch (iterErr) {
727
- // Release both reservations on failure before re-throwing.
728
- if (reservationId !== null) {
729
- try {
730
- ctx.manifest.cancelBudgetReservation(reservationId);
731
- }
732
- catch (cancelErr) {
733
- logger.error(`ask_agentic: cancelBudgetReservation failed: ${safeForLog(cancelErr)}`);
734
- }
735
- }
736
- if (throttleReservationId !== -1) {
737
- ctx.throttle.cancel(throttleReservationId);
738
- }
739
- // v1.14.2 Fix 4: extract Gemini's `retryInfo.retryDelay` from 429s and
740
- // seed the throttle hint cache, mirroring `ask.tool.ts:~1063`. Pre-fix
741
- // ask_agentic catch paths discarded the hint — TPM throttle relied on
742
- // pure-window math which empirically over-estimates by 30s+ on real
743
- // 429s. Gating on `isGemini429` (requires `err instanceof ApiError` +
744
- // `err.status === 429`) is non-user-influenceable; only real Gemini
745
- // 429s match. Future iterations / future `ask_agentic` callers honour
746
- // the recorded hint via `throttle.reserve`'s `activeHint` lookup.
747
- const iterRetryDelayMs = isGemini429(iterErr) ? parseRetryDelayMs(iterErr.message) : null;
748
- if (iterRetryDelayMs !== null) {
749
- ctx.throttle.recordRetryHint(resolved.resolved, iterRetryDelayMs);
750
- }
751
- // If the iteration aborted on timeout, surface a structured TIMEOUT
752
- // error so the caller can distinguish "this iteration was too slow"
753
- // from "Gemini rejected the request". Annotate which iteration so
754
- // ops can correlate with logs. The whole agentic call fails — we do
755
- // NOT continue with partial state because the failed iteration's
756
- // function-call results never came back, so the conversation is
757
- // structurally incomplete.
758
- if (isTimeoutAbort(iterErr)) {
759
- const totalMs = iterTimeout.timeoutMs;
760
- const stallMs = iterTimeout.stallMs;
761
- // v1.16.2 (T33 TRIM): with the loop now streaming, stall vs total
762
- // is meaningful. Surface `timeoutKind` so wrappers can route retry
763
- // policy: 'stall' → safe to retry (dead socket); 'total' → raise
764
- // iterationTimeoutMs or narrow prompt. `limitMs` is the value that
765
- // actually fired — used in the message string + emitter line for
766
- // operator-readable context. The structuredContent payload mirrors
767
- // `ask.tool.ts:1129-1135` exactly: `timeoutMs` always reports the
768
- // configured TOTAL wall-clock cap (or null if disabled), `stallMs`
769
- // reports the configured stall watchdog. The `timeoutKind` field
770
- // is the discriminator. Wrappers that branched on `timeoutMs > X`
771
- // pre-v1.16.2 see a stable contract — only configured-but-not-fired
772
- // adds a new `null` case (which existing branches handle correctly
773
- // since `null > X` is false).
774
- const kind = getTimeoutKind(iterErr) ?? 'total';
775
- const limitMs = kind === 'stall' ? stallMs : totalMs;
776
- const knobHint = kind === 'stall'
777
- ? 'Increase `stallMs` per call or set `GEMINI_CODE_CONTEXT_AGENTIC_STALL_MS` higher; default disabled. Stall fires when the stream goes silent — usually a dead socket or a Gemini server-side hiccup.'
778
- : 'Increase `iterationTimeoutMs` per call or set `GEMINI_CODE_CONTEXT_AGENTIC_ITERATION_TIMEOUT_MS` higher; default disabled.';
779
- emitter.emit(`ask_agentic: iteration ${iterations} aborted after ${limitMs ?? '?'}ms (${kind})`);
780
- return errorResult(`ask_agentic: iteration ${iterations} timed out (${kind}) after ${limitMs ?? '?'}ms. ${knobHint} Note: AbortSignal is client-only — Gemini may still finish server-side and bill tokens for completed work.`, {
781
- errorCode: 'TIMEOUT',
782
- // Mirrors ask.tool.ts:1132 verbatim: `timeoutMs` = configured
783
- // total wall-clock cap (or null when disabled); `stallMs` =
784
- // configured stall watchdog (or null when disabled). The
785
- // discriminator for which one fired is `timeoutKind`. Pre-fix
786
- // (v1.16.2 PR-Round-1) this collapsed to "the limit that fired"
787
- // — diverged from ask/code; flagged by gemini Round-1 as a
788
- // contract regression. Reverted to ask/code parity.
789
- timeoutMs: totalMs,
790
- stallMs,
791
- timeoutKind: kind,
792
- iteration: iterations,
793
- iterations,
794
- // H2 fix: distinguish timeout-during-throttle-wait (no
795
- // dispatch) from timeout-during-generateContent (dispatch
796
- // happened). `iterDispatched` is set true just before the
797
- // runAgenticIteration await — if it's still false, the timeout
798
- // fired during abortableSleep and this iter never reached the
799
- // API. Subtract 1 in that case to keep apiCalls authoritative.
800
- apiCalls: iterDispatched ? iterations : Math.max(0, iterations - 1),
801
- retryable: true,
802
- });
803
- }
804
- throw iterErr;
805
- }
806
- finally {
807
- iterTimeout.dispose();
808
- }
809
- const iterDurationMs = Date.now() - iterStarted;
810
- // Finalise budget reservation with actual cost from usage metadata.
811
- // `durationMs` is per-iteration wall time (matching `ask`/`code`), so
812
- // the manifest row reflects real latency — agentic loops used to write
813
- // `0` here, breaking usage-analytics queries (PR #24 round-4,
814
- // Copilot P1).
815
- if (reservationId !== null) {
816
- const actualCost = estimateCostUsd({
817
- model: resolved.resolved,
818
- uncachedInputTokens: iterResult.usage.promptTokenCount,
819
- cachedInputTokens: 0,
820
- outputTokens: iterResult.usage.candidatesTokenCount,
821
- thinkingTokens: iterResult.usage.thoughtsTokenCount,
822
- });
823
- try {
824
- ctx.manifest.finalizeBudgetReservation(reservationId, {
825
- cachedTokens: 0,
826
- uncachedTokens: iterResult.usage.promptTokenCount,
827
- costUsdMicro: toMicrosUsd(actualCost),
828
- durationMs: iterDurationMs,
829
- });
830
- }
831
- catch (finalizeErr) {
832
- logger.error(`ask_agentic: finalizeBudgetReservation failed for id=${reservationId}: ${String(finalizeErr)}`);
833
- }
834
- }
835
- // Release TPM reservation with actual input tokens.
836
- if (throttleReservationId !== -1) {
837
- ctx.throttle.release(throttleReservationId, iterResult.usage.promptTokenCount);
838
- }
839
- cumulativeInputTokens += iterResult.usage.promptTokenCount;
840
- cumulativeOutputTokens += iterResult.usage.candidatesTokenCount;
841
- cumulativeThinkingTokens += iterResult.usage.thoughtsTokenCount;
842
- lastIterationPromptTokens = iterResult.usage.promptTokenCount;
843
- lastToolResponseTokens = iterResult.toolResponseTokens; // P5 (v1.15.0)
844
- emitter.emit(`iter ${iterations}/${maxIterations}: ${iterResult.functionCallCount} tool calls, ${cumulativeInputTokens} in-tokens so far`);
845
- // Final-text first, budget second: if the iteration produced an
846
- // answer, return it even if the cumulative-token count ticked over
847
- // `maxTotalInputTokens`. Operators already paid for those tokens;
848
- // discarding a successful answer just because this iteration
849
- // nudged the meter over is punitive UX. The budget guard below
850
- // still blocks FUTURE iterations from spending beyond the cap.
851
- // Reported in PR #24 review by Gemini.
852
- if (iterResult.finalText !== null) {
853
- return textResult(iterResult.finalText, {
854
- resolvedModel: resolved.resolved,
855
- requestedModel: resolved.requested,
856
- fallbackApplied: resolved.fallbackApplied,
857
- modelCategory: resolved.category,
858
- contextWindow: resolved.inputTokenLimit,
859
- iterations,
860
- // Organic final-text path: no forced-finalization pass ran, so
861
- // total `generateContent` calls equals loop iterations.
862
- apiCalls: iterations,
863
- cumulativeInputTokens,
864
- cumulativeOutputTokens,
865
- cumulativeThinkingTokens,
866
- filesRead: filesReadSet.size,
867
- filesReadList: [...filesReadSet].slice(0, 40),
868
- durationMs: Date.now() - started,
869
- thinkingSummary: iterResult.thinkingSummary,
870
- overBudget: cumulativeInputTokens > maxTotalInputTokens,
871
- });
872
- }
873
- // Budget guard — runs AFTER the final-text check so a last-iteration
874
- // answer is never discarded. If we're here, the model is still
875
- // asking for tool calls; refuse to fund another round.
876
- if (cumulativeInputTokens > maxTotalInputTokens) {
877
- return errorResult(`ask_agentic: cumulative input tokens (${cumulativeInputTokens.toLocaleString()}) exceeded budget (${maxTotalInputTokens.toLocaleString()}) after ${iterations} iterations. Increase maxTotalInputTokens, narrow your prompt, or lower thinkingLevel.`, {
878
- errorCode: 'UNKNOWN',
879
- retryable: false,
880
- subReason: 'AGENTIC_INPUT_BUDGET_EXCEEDED',
881
- iterations,
882
- // Budget guard fires AFTER the iteration's generateContent
883
- // completed — the call IS counted in apiCalls.
884
- apiCalls: iterations,
885
- cumulativeInputTokens,
886
- });
887
- }
888
- // No-progress detection (v1.16.0 P2 Phase B — content-aware):
889
- // bails when any single call signature has been issued
890
- // `NO_PROGRESS_CALL_THRESHOLD` times without any new
891
- // `filesReadSet` growth between repeats. If `filesReadSet` grew,
892
- // the model is exploring (productive) — reset that signature's
893
- // count to 1.
894
- //
895
- // Implementation note: capture `filesReadSet.size` ONCE per iter
896
- // (after tool execution) so all signatures within the same iter
897
- // see the same "size at end of this iter" snapshot. Without the
898
- // snapshot, a single iter that issues `read_file` AND `grep` AND
899
- // `read_file` would have a different `filesReadSet.size` per
900
- // signature depending on tool-execution order — non-deterministic
901
- // + wrong (the snapshot represents iter-level progress, not
902
- // within-iter).
903
- //
904
- // AA1 fix (v1.16.0 PR-Round-1, 3-of-3 cross-corroborated TP HIGH):
905
- // ALSO dedupe signatures WITHIN an iter before counting. The
906
- // counter conceptually measures iters-spent-stuck, not raw
907
- // emission count. If the model glitches and emits the same
908
- // `grep` 5× in one parallel batch, that's pathological output
909
- // for ONE iter — should count as +1 toward the threshold, not
910
- // +5. Pre-AA1 the counter compounded 1→2→3→4→5 in a single
911
- // iter, instantly tripping AGENTIC_NO_PROGRESS even though
912
- // zero stuck-iters had elapsed.
913
- //
914
- // Tool-surface assumption (AA2 ACCEPTED-DEFERRED): `read_file`
915
- // is the sole progress oracle because ask_agentic's tool
916
- // surface is exclusively read-only (`read_file`, `grep`,
917
- // `list_directory`, `find_files` — no write_file, no terminal
918
- // exec). When a future PR adds workspace-mutating tools, this
919
- // oracle MUST be expanded to track any state-changing tool
920
- // call (e.g., a combined "workspace state version" counter)
921
- // — otherwise a model iterating on edits + command execution
922
- // would false-positive AGENTIC_NO_PROGRESS.
923
- const filesReadSizeAtIterEnd = filesReadSet.size;
924
- const uniqueSigsThisIter = new Set();
925
- for (const { name, args } of iterResult.signatures) {
926
- uniqueSigsThisIter.add(`${name}(${stableJson(args)})`);
927
- }
928
- for (const sig of uniqueSigsThisIter) {
929
- const prev = signatureCounts.get(sig);
930
- // Reset count when files grew between identical signatures —
931
- // model is making progress, not stuck. Otherwise increment.
932
- const count = prev && filesReadSizeAtIterEnd > prev.lastFilesReadSize ? 1 : (prev?.count ?? 0) + 1;
933
- signatureCounts.set(sig, { count, lastFilesReadSize: filesReadSizeAtIterEnd });
934
- if (count >= NO_PROGRESS_CALL_THRESHOLD) {
935
- // R2 message enrichment (v1.16.1 — /6step PARTIAL TP): some MCP
936
- // consumers (notably Claude Code's tool-result rendering) collapse
937
- // isError responses to the message string only and don't surface
938
- // `structuredContent` — wire format includes both per CallToolResultSchema
939
- // (independent optional fields) but rendering is consumer-side. Mirror
940
- // operator-actionable fields (iterations, filesRead) into the message
941
- // string so they're visible regardless of consumer rendering. The
942
- // structuredContent payload stays intact for any consumer that reads it.
943
- return errorResult(`ask_agentic: no-progress loop detected — call '${sig.slice(0, 200)}' was repeated ${count} times without new file reads between repeats (after ${iterations} iter${iterations === 1 ? '' : 's'}, ${filesReadSet.size} file${filesReadSet.size === 1 ? '' : 's'} read). Returning partial state.`, {
944
- errorCode: 'UNKNOWN',
945
- retryable: false,
946
- subReason: 'AGENTIC_NO_PROGRESS',
947
- iterations,
948
- // Dedupe fires AFTER the iteration's generateContent completed —
949
- // the call IS counted in apiCalls.
950
- apiCalls: iterations,
951
- repeatedSignature: sig.slice(0, 500),
952
- cumulativeInputTokens,
953
- filesRead: filesReadSet.size,
954
- });
955
- }
956
- }
957
- }
958
- // Loop exhausted maxIterations without an organic final-text turn.
959
- // Run a single forced-finalization pass — `generateContent` with
960
- // `toolConfig.functionCallingConfig.mode = NONE` so the model is
961
- // prohibited from emitting more function calls (Gemini API spec: NONE
962
- // = "equivalent to sending a request without any function declarations")
963
- // and must answer in text using the conversation it has already
964
- // accumulated. Converts what was previously an opaque error into a
965
- // synthesized text answer derived from the tool responses gathered so
966
- // far. If the forced call itself fails (timeout, network, budget
967
- // exhausted, empty text), fall through to the original error so the
968
- // caller still gets a structured failure signal.
969
- emitter.emit(`maxIterations (${maxIterations}) reached — running forced-finalization pass`);
970
- // v1.14.2: the rescue pass is NOT gated on `maxTotalInputTokens`. It is
971
- // the documented exit path for "loop ran out of iterations without final
972
- // text" and blocking it on rescue's own potential overshoot defeats the
973
- // v1.14.1 feature — an operator running near the cap would never get the
974
- // synthesised answer the rescue is designed to produce. Empirical repro:
975
- // the v1.14.1 PR self-review benchmark hit `cumulativeInputTokens=500_919
976
- // > 500_000` cap mid-loop (the line-790 hard-stop guard, which stays);
977
- // operators hitting maxIters near the cap saw the same self-block via the
978
- // pre-v1.14.2 token-budget guard previously here. Rescue cost remains
979
- // bounded by `dailyBudgetUsd` reservation (line ~892), wall-clock by
980
- // `iterationTimeoutMs` (line ~919). Cap-overshoot is signalled via
981
- // `overBudget: true` on the result so callers can detect the trade.
982
- let finalizationText = '';
983
- let finalizationUsage = {
984
- promptTokenCount: 0,
985
- candidatesTokenCount: 0,
986
- thoughtsTokenCount: 0,
987
- };
988
- let finalizationThinkingSummary = null;
989
- let finalizationReservationId = null;
990
- // Tracks whether the finalization `generateContent` call was actually
991
- // dispatched (regardless of outcome). Used by `apiCalls` accounting so
992
- // mid-flight timeouts / pre-response network failures still count the
993
- // attempt — `finalizationUsage.promptTokenCount` would stay at 0 in those
994
- // cases (response never arrived to populate usageMetadata) and
995
- // inferring "fired" from usage would undercount the API call.
996
- let finalizationAttempted = false;
997
- // P3 (v1.15.0): tracks whether the rescue's `await withNetworkRetry(...)`
998
- // returned a response BEFORE any post-await processing (parsing
999
- // candidates/parts, computing thinking summary, etc.) could throw. The
1000
- // pre-P3 try/catch routed BOTH "API failed" and "API succeeded but
1001
- // post-await parse threw" through the catch → cancelBudgetReservation,
1002
- // even though the second path's tokens WERE billed by Google. This
1003
- // flag is set IMMEDIATELY after the await returns and used in the new
1004
- // `finally` block to decide finalize-vs-cancel: success path gets
1005
- // `finalizeBudgetReservation` even if downstream parsing errored.
1006
- // (3-of-3 cross-reviewer /6step verdict: TRUE POSITIVE — grok F1.)
1007
- let apiCallSucceeded = false;
1008
- // P4 (v1.15.0): caller-visible rescue failure-class signal. Pre-P4 the
1009
- // rescue's catch block extracted the 429 hint server-side (good) but
1010
- // returned a generic `subReason: 'AGENTIC_MAX_ITERATIONS'` errorResult,
1011
- // forcing callers to grep server logs to distinguish 429 vs TIMEOUT vs
1012
- // network failure vs empty-text. Now surfaced as
1013
- // `structuredContent.rescueErrorCode` on the trailing errorResult so
1014
- // wrappers can branch retry behaviour without log scraping. Stays null
1015
- // when the rescue produced text successfully (the textResult path
1016
- // already signals via `convergenceForced: true`). Strict union — extend
1017
- // here when adding new error classes.
1018
- // v1.15.0 PR-Round-1 follow-up (X2/X3 — gemini-chat + grok HIGH/MEDIUM,
1019
- // /6step TP): split the catch-block fallthrough into more precise buckets.
1020
- // Pre-fix every non-timeout non-429 throw bucketed as 'NETWORK', which
1021
- // misled wrappers into retrying 4xx-other-than-429 ApiErrors (e.g., 400
1022
- // INVALID_ARGUMENT) as if they were transient connectivity drops.
1023
- //
1024
- // - 'TIMEOUT' — iterationTimeoutMs fired (isTimeoutAbort)
1025
- // - 'RATE_LIMIT' — Google 429 (isGemini429: ApiError + status===429)
1026
- // - 'INTERNAL' — `apiCallSucceeded === true` (await returned, but
1027
- // post-await processing threw — billed by Google,
1028
- // finalize budget per P3, but caller sees structured
1029
- // failure). Distinguishes "API ok, our code bug" from
1030
- // "API failure" so wrappers don't blindly retry our
1031
- // parse bugs.
1032
- // - 'API_ERROR' — `instanceof ApiError` with status≠429 (4xx other
1033
- // than 429, or 5xx). Wrapper should NOT retry 4xx
1034
- // (fix the payload) but MAY retry 5xx with backoff.
1035
- // - 'NETWORK' — fetch-layer / DNS / TCP / pre-dispatch SDK error.
1036
- // Real transient connectivity case; safe to retry.
1037
- // - 'EMPTY_TEXT' — set in success path: API returned, but extracted
1038
- // text was empty after .trim(). Budget IS finalized.
1039
- let rescueErrorCode = null;
1040
- let rescueErrorMessage = null;
1041
- // v1.14.2 Fix 5: tracks WHY the rescue pass was skipped, so the trailing
1042
- // errorResult can emit a cause-specific message + structured field instead
1043
- // of the misleading generic "Increase maxIterations or narrow your prompt"
1044
- // (active lie when the cause is daily budget exhaustion). Set to
1045
- // 'daily-budget' when `reserveBudget` rejects below; remains null on
1046
- // success or when no rescue was attempted at all (e.g. dailyBudgetEnforced
1047
- // = false). Surfaces as `finalizationSkipReason` on `structuredContent` —
1048
- // additive optional field, no schema break for existing callers.
1049
- let finalizationSkipReason = null;
1050
- // v1.14.2: dynamic estimate for the rescue pass — replaces the static
1051
- // `PER_ITERATION_INPUT_TOKENS = 50_000` baseline with the actual size of
1052
- // the last observed iteration (+5k margin for SYSTEM_INSTRUCTION_FINALIZATION
1053
- // + thinking-config overhead). Used by BOTH the daily-budget reservation
1054
- // (immediately below) AND the TPM-throttle reservation (line ~919) so cost
1055
- // and rate-limit gates stay symmetric — pre-Fix-6.1 only the TPM reserve was
1056
- // dynamic, leaving the daily-budget gate to under-estimate rescue cost
1057
- // (broke the documented "daily budget is a true upper bound" guarantee).
1058
- // Fallback to the static estimate when the loop produced no usage record
1059
- // (defensive — in practice rescue is gated on `iterations >= maxIterations`
1060
- // so iter 1+ ran and lastIterationPromptTokens was populated).
1061
- //
1062
- // v1.15.0 (P5): also fold in `lastToolResponseTokens` — the
1063
- // tool-response Parts appended to `conversation` AFTER the last iteration's
1064
- // `generateContent` returned. The rescue's prompt replays the entire
1065
- // accumulated conversation, so its actual size ≈ last-iter prompt + the
1066
- // tool responses appended after. Pre-P5 a final iteration that issued
1067
- // several concurrent `read_file` calls (default parallel-dispatch is 10
1068
- // in v1.15.1+, was 3 pre-bump) could append 100k+ tokens of file content
1069
- // the estimate missed, causing the rescue to under-reserve TPM and 429
1070
- // mid-flight. (3-of-3 cross-reviewer /6step verdict: TRUE POSITIVE
1071
- // Medium — gcc-ask own F1.)
1072
- const finalizationEstimate = lastIterationPromptTokens > 0
1073
- ? lastIterationPromptTokens + lastToolResponseTokens + 5_000
1074
- : PER_ITERATION_INPUT_TOKENS;
1075
- const finalizationCostUsd = passReservationUsd(finalizationEstimate);
1076
- if (dailyBudgetEnforced) {
1077
- const reserve = ctx.manifest.reserveBudget({
1078
- workspaceRoot,
1079
- toolName: 'ask_agentic',
1080
- model: resolved.resolved,
1081
- estimatedCostMicros: toMicrosUsd(finalizationCostUsd),
1082
- dailyBudgetMicros: toMicrosUsd(ctx.config.dailyBudgetUsd),
1083
- nowMs: Date.now(),
1084
- });
1085
- if ('rejected' in reserve) {
1086
- emitter.emit(`skipping forced-finalization pass — daily budget cap reached (spent $${(reserve.spentMicros / 1_000_000).toFixed(4)})`);
1087
- logger.warn(`ask_agentic: skipping forced-finalization pass — daily budget cap reached (spent $${(reserve.spentMicros / 1_000_000).toFixed(4)})`);
1088
- finalizationSkipReason = 'daily-budget';
1089
- }
1090
- else {
1091
- finalizationReservationId = reserve.id;
1092
- }
1093
- }
1094
- if (finalizationReservationId !== null || !dailyBudgetEnforced) {
1095
- emitter.emit('running forced-finalization pass (tools disabled)');
1096
- const finalizationTimeout = createTimeoutController({
1097
- ...(input.iterationTimeoutMs !== undefined ? { totalMs: input.iterationTimeoutMs } : {}),
1098
- totalEnvVar: 'GEMINI_CODE_CONTEXT_AGENTIC_ITERATION_TIMEOUT_MS',
1099
- stallEnvVar: '',
1100
- });
1101
- let finalizationThrottleId = -1;
1102
- const finalizationStarted = Date.now();
1103
- try {
1104
- if (tpmEnforced) {
1105
- // v1.14.2: use the dynamic `finalizationEstimate` (computed above the
1106
- // daily-budget reserve block — same value, same +5k margin rationale)
1107
- // for the TPM-throttle reservation. Symmetric with the daily-budget
1108
- // reserve so rate-limit and cost gates use the SAME size estimate for
1109
- // the rescue pass. TPM over-reserve = transient throttle wait
1110
- // (harmless); under-reserve = 429 risk; bias is intentional.
1111
- const reservation = ctx.throttle.reserve(resolved.resolved, finalizationEstimate);
1112
- finalizationThrottleId = reservation.releaseId;
1113
- if (reservation.delayMs > 0) {
1114
- emitter.emit(`finalization throttle: waiting ${Math.ceil(reservation.delayMs / 1000)}s for TPM window…`);
1115
- await abortableSleep(reservation.delayMs, finalizationTimeout.signal);
1116
- }
1117
- }
1118
- // G2 fix: omit `tools` (function declarations) from the finalization
1119
- // call. Per Gemini API spec, `mode: NONE` is "equivalent to sending
1120
- // a request without any function declarations" — sending the
1121
- // declarations alongside NONE wastes ~150-300 input tokens and
1122
- // contradicts the spec we depend on. The destructure below is the
1123
- // TS-safe way to OMIT a property from the spread (assignment to
1124
- // `undefined` trips `exactOptionalPropertyTypes`).
1125
- const { tools: _unusedTools, ...baseConfigNoTools } = baseConfig;
1126
- // Mark the API attempt BEFORE dispatch so timeouts / pre-response
1127
- // network failures still count toward `apiCalls`. Set inside the try
1128
- // (after throttle wait) so a throttle-wait abort doesn't mis-count.
1129
- finalizationAttempted = true;
1130
- // Capture `resolved.resolved` outside the closure so TS doesn't
1131
- // re-widen the type to `string | undefined` on the closure boundary
1132
- // (`resolved` is hoisted to function scope in v1.14.3 for outer-catch
1133
- // 429 hint extraction; flow-narrowing past the line-486 assignment
1134
- // doesn't propagate into closures defined further down).
1135
- const resolvedModelName = resolved.resolved;
1136
- const response = await withNetworkRetry(() => ctx.client.models.generateContent({
1137
- model: resolvedModelName,
1138
- contents: conversation,
1139
- config: {
1140
- ...baseConfigNoTools,
1141
- systemInstruction: SYSTEM_INSTRUCTION_FINALIZATION,
1142
- toolConfig: {
1143
- functionCallingConfig: { mode: FunctionCallingConfigMode.NONE },
1144
- },
1145
- abortSignal: finalizationTimeout.signal,
1146
- },
1147
- }), {
1148
- signal: finalizationTimeout.signal,
1149
- onRetry: (attempt, retryErr) => {
1150
- logger.warn(`ask_agentic finalization: retry attempt ${attempt}: ${retryErr instanceof Error ? retryErr.message : String(retryErr)}`);
1151
- },
1152
- });
1153
- // P3 (v1.15.0): the API call returned a response. Mark success
1154
- // IMMEDIATELY — before any post-await parsing that could throw —
1155
- // so the `finally` block routes cleanup to finalize (tokens were
1156
- // billed) rather than cancel (would pretend the call never happened).
1157
- apiCallSucceeded = true;
1158
- const usage = response.usageMetadata;
1159
- finalizationUsage = {
1160
- promptTokenCount: typeof usage?.promptTokenCount === 'number' ? usage.promptTokenCount : 0,
1161
- candidatesTokenCount: typeof usage?.candidatesTokenCount === 'number' ? usage.candidatesTokenCount : 0,
1162
- thoughtsTokenCount: typeof usage?.thoughtsTokenCount === 'number' ? usage.thoughtsTokenCount : 0,
1163
- };
1164
- const parts = response.candidates?.[0]?.content?.parts ?? [];
1165
- finalizationText = (response.text ?? parts.map((p) => p.text ?? '').join('')).trim();
1166
- const thoughtTexts = parts
1167
- .filter((p) => p.thought === true && typeof p.text === 'string')
1168
- .map((p) => p.text);
1169
- finalizationThinkingSummary =
1170
- thoughtTexts.length > 0 ? thoughtTexts.join('\n').slice(0, 1200) : null;
1171
- // P4 (v1.15.0): empty-text is a rescue failure mode (model dispatched,
1172
- // returned a candidate with no extractable text). Surface so callers
1173
- // can branch — distinct from timeouts / 429s / network errors.
1174
- if (finalizationText.length === 0) {
1175
- rescueErrorCode = 'EMPTY_TEXT';
1176
- }
1177
- }
1178
- catch (finalErr) {
1179
- // v1.14.2 Fix 4: same retry-hint extraction as the per-iteration catch
1180
- // — the rescue's generateContent can also 429, and the hint should
1181
- // seed the throttle cache for future ask_agentic / ask / code calls.
1182
- const isRescue429 = isGemini429(finalErr);
1183
- const finalRetryDelayMs = isRescue429 ? parseRetryDelayMs(finalErr.message) : null;
1184
- if (finalRetryDelayMs !== null) {
1185
- ctx.throttle.recordRetryHint(resolved.resolved, finalRetryDelayMs);
1186
- }
1187
- // P4 (v1.15.0): classify rescue failure for caller-facing telemetry.
1188
- // Order matters — earlier branches signal the most user-actionable
1189
- // remediation:
1190
- // 1. TIMEOUT — raise iterationTimeoutMs / narrow prompt (iteration
1191
- // timeout fired; checked first because a 429 surfaced via an
1192
- // aborted-fetch can race the timeout signal).
1193
- // 2. RATE_LIMIT — wait the retry-hint window then retry (429).
1194
- // 3. INTERNAL — our code bug (post-await parse threw); operator
1195
- // should NOT retry blindly. v1.15.0 PR-Round-1 follow-up
1196
- // (X2/X3) — `apiCallSucceeded === true` means the await
1197
- // returned cleanly; any throw past that point is processing
1198
- // logic our side, not Gemini's API.
1199
- // 4. API_ERROR — Gemini API returned a non-429 4xx/5xx. Wrapper
1200
- // should NOT retry 4xx (fix payload); MAY retry 5xx with
1201
- // backoff. v1.15.0 PR-Round-1 follow-up — pre-fix all
1202
- // ApiError-non-429 bucketed as NETWORK, breaking retry
1203
- // policy decisions.
1204
- // 5. NETWORK — fetch-layer / DNS / TCP / SDK pre-dispatch.
1205
- // Genuine transient connectivity case; safe to retry.
1206
- if (isTimeoutAbort(finalErr)) {
1207
- rescueErrorCode = 'TIMEOUT';
1208
- logger.warn('ask_agentic finalization: timed out after maxIterations exhaustion');
1209
- }
1210
- else if (isRescue429) {
1211
- rescueErrorCode = 'RATE_LIMIT';
1212
- logger.warn(`ask_agentic finalization: 429 rate-limit (retryDelay=${finalRetryDelayMs ?? 'unknown'}ms)`);
1213
- }
1214
- else if (apiCallSucceeded) {
1215
- // X2/X3 fix: API roundtrip completed but post-await processing
1216
- // (response parsing, candidates/parts traversal, EMPTY_TEXT check)
1217
- // threw. Distinct from NETWORK — operator's wrapper should treat
1218
- // this as "investigate code bug, do not retry blindly".
1219
- rescueErrorCode = 'INTERNAL';
1220
- logger.warn(`ask_agentic finalization: post-await processing failed: ${finalErr instanceof Error ? finalErr.message : String(finalErr)}`);
1221
- }
1222
- else if (finalErr instanceof ApiError) {
1223
- // X2 fix: Gemini API returned a 4xx-other-than-429 or 5xx.
1224
- // Distinct from NETWORK so wrappers don't retry 400 INVALID_ARGUMENT
1225
- // forever.
1226
- rescueErrorCode = 'API_ERROR';
1227
- logger.warn(`ask_agentic finalization: Gemini API returned ${finalErr.status ?? 'unknown'}: ${finalErr.message.slice(0, 200)}`);
1228
- }
1229
- else {
1230
- rescueErrorCode = 'NETWORK';
1231
- logger.warn(`ask_agentic finalization: network failure: ${finalErr instanceof Error ? finalErr.message : String(finalErr)}`);
1232
- }
1233
- rescueErrorMessage =
1234
- finalErr instanceof Error
1235
- ? finalErr.message.slice(0, 500)
1236
- : String(finalErr).slice(0, 500);
1237
- }
1238
- finally {
1239
- // P3 (v1.15.0): cleanup routed by `apiCallSucceeded`, not by the
1240
- // try/catch boundary. Pre-P3 the try/catch routed cleanup based on
1241
- // whether ANY post-await statement threw — meaning a parse error
1242
- // after a successful API call would land in the catch and call
1243
- // `cancelBudgetReservation` despite tokens being billed. Now:
1244
- // - apiCallSucceeded === true → finalize budget + release throttle
1245
- // (use estimate as fallback if
1246
- // usageMetadata didn't populate)
1247
- // - apiCallSucceeded === false → cancel budget + cancel throttle
1248
- // (pre-dispatch failure or
1249
- // await-itself threw — call never
1250
- // reached Google's billing)
1251
- if (apiCallSucceeded) {
1252
- // CC2 fix (v1.15.0 PR-Round-1, Copilot): hoist billedUncachedTokens
1253
- // OUTSIDE the budget-finalize branch so the throttle.release call
1254
- // below uses the SAME fallback. Pre-fix the asymmetry meant when
1255
- // Google's response omitted usageMetadata (rare but defended-against
1256
- // by the typeof guard at the parse site), budget finalize used
1257
- // `finalizationEstimate` (correct) but throttle.release passed 0,
1258
- // mutating the TPM window entry to 0 — under-throttling subsequent
1259
- // calls. Sharing the same fallback keeps both releases symmetric.
1260
- const billedUncachedTokens = billedInputTokens(finalizationUsage.promptTokenCount, finalizationEstimate);
1261
- if (finalizationReservationId !== null) {
1262
- // If parse-after-await threw, finalizationUsage is still {0,0,0}.
1263
- // Fall back to `finalizationEstimate` for billing — under-billing
1264
- // a known-completed API call is a worse failure mode than
1265
- // over-billing on a parse-error edge case (the operator's
1266
- // dailyBudget cap stays a true upper bound either way).
1267
- const actualCost = estimateCostUsd({
1268
- model: resolved.resolved,
1269
- uncachedInputTokens: billedUncachedTokens,
1270
- cachedInputTokens: 0,
1271
- outputTokens: finalizationUsage.candidatesTokenCount,
1272
- thinkingTokens: finalizationUsage.thoughtsTokenCount,
1273
- });
1274
- try {
1275
- ctx.manifest.finalizeBudgetReservation(finalizationReservationId, {
1276
- cachedTokens: 0,
1277
- uncachedTokens: billedUncachedTokens,
1278
- costUsdMicro: toMicrosUsd(actualCost),
1279
- durationMs: Date.now() - finalizationStarted,
1280
- });
1281
- }
1282
- catch (finalizeErr) {
1283
- logger.error(`ask_agentic finalization: finalize reservation failed: ${safeForLog(finalizeErr)}`);
1284
- }
1285
- }
1286
- if (finalizationThrottleId !== -1) {
1287
- // CC2 fix: use billedUncachedTokens (shared with budget finalize)
1288
- // instead of raw `finalizationUsage.promptTokenCount` so the
1289
- // missing-usageMetadata edge doesn't under-throttle the TPM window.
1290
- ctx.throttle.release(finalizationThrottleId, billedUncachedTokens);
1291
- }
1292
- }
1293
- else {
1294
- if (finalizationReservationId !== null) {
1295
- try {
1296
- ctx.manifest.cancelBudgetReservation(finalizationReservationId);
1297
- }
1298
- catch (cancelErr) {
1299
- logger.error(`ask_agentic finalization: cancelBudgetReservation failed: ${safeForLog(cancelErr)}`);
1300
- }
1301
- }
1302
- if (finalizationThrottleId !== -1) {
1303
- ctx.throttle.cancel(finalizationThrottleId);
1304
- }
1305
- }
1306
- finalizationTimeout.dispose();
1307
- }
1308
- }
1309
- // Token totals after the finalization pass. When the pass succeeded at
1310
- // the API level its tokens ARE billed even if `finalizationText` came
1311
- // back empty, so both branches below report the post-pass totals — this
1312
- // closes the structured-telemetry drift where the empty-text fallback
1313
- // previously under-reported real usage.
1314
- const totalCumulativeInputTokens = cumulativeInputTokens + finalizationUsage.promptTokenCount;
1315
- const totalCumulativeOutputTokens = cumulativeOutputTokens + finalizationUsage.candidatesTokenCount;
1316
- // `apiCalls` = total generateContent calls. Track from the explicit
1317
- // `finalizationAttempted` flag (set IMMEDIATELY BEFORE the
1318
- // `await withNetworkRetry(...)` dispatch) rather than inferring from
1319
- // `finalizationUsage.promptTokenCount > 0` — timeouts and pre-response
1320
- // network failures leave usageMetadata empty even though the API attempt
1321
- // happened (and may have been billed server-side). Skipped paths
1322
- // (daily-budget reject, token-cap overshoot) leave `finalizationAttempted`
1323
- // false so they correctly report `apiCalls = iterations`. Operators can
1324
- // branch on `apiCalls > iterations` to detect the forced pass without
1325
- // parsing `convergenceForced`. (Round-4 Copilot fix.)
1326
- const apiCalls = iterations + (finalizationAttempted ? 1 : 0);
1327
- if (finalizationText.length > 0) {
1328
- return textResult(finalizationText, {
1329
- resolvedModel: resolved.resolved,
1330
- requestedModel: resolved.requested,
1331
- fallbackApplied: resolved.fallbackApplied,
1332
- modelCategory: resolved.category,
1333
- contextWindow: resolved.inputTokenLimit,
1334
- iterations,
1335
- apiCalls,
1336
- cumulativeInputTokens: totalCumulativeInputTokens,
1337
- cumulativeOutputTokens: totalCumulativeOutputTokens,
1338
- cumulativeThinkingTokens: cumulativeThinkingTokens + finalizationUsage.thoughtsTokenCount,
1339
- filesRead: filesReadSet.size,
1340
- filesReadList: [...filesReadSet].slice(0, 40),
1341
- durationMs: Date.now() - started,
1342
- thinkingSummary: finalizationThinkingSummary,
1343
- convergenceForced: true,
1344
- // Mirror the organic-final-text path (line ~754) so callers can
1345
- // detect when the pass pushed cumulative tokens past the cap.
1346
- overBudget: totalCumulativeInputTokens > maxTotalInputTokens,
1347
- });
1348
- }
1349
- // v1.14.2 Fix 5: branch the error message on whether the rescue was
1350
- // skipped due to daily-budget exhaustion vs ran-and-failed (empty text /
1351
- // network error / timeout). Pre-fix the generic "Increase maxIterations"
1352
- // message lied to operators on the daily-budget skip path — the actual
1353
- // remediation is to wait for daily reset or raise GEMINI_DAILY_BUDGET_USD.
1354
- // The structured field `finalizationSkipReason` is additive (only present
1355
- // when set) so existing callers ignore it; new callers can branch on it
1356
- // for automated triage.
1357
- const errorMessage = finalizationSkipReason === 'daily-budget'
1358
- ? `ask_agentic: reached maxIterations (${maxIterations}) without a final answer; forced-finalization pass skipped because daily budget cap reached. Wait for daily reset (UTC midnight) or raise GEMINI_DAILY_BUDGET_USD.`
1359
- : `ask_agentic: reached maxIterations (${maxIterations}) without a final answer. Increase maxIterations or narrow your prompt.`;
1360
- return errorResult(errorMessage, {
1361
- errorCode: 'UNKNOWN',
1362
- retryable: false,
1363
- subReason: 'AGENTIC_MAX_ITERATIONS',
1364
- ...(finalizationSkipReason !== null ? { finalizationSkipReason } : {}),
1365
- // P4 (v1.15.0): caller-visible rescue failure-class. Surfaces
1366
- // `'TIMEOUT' | 'RATE_LIMIT' | 'NETWORK' | 'EMPTY_TEXT'` when the
1367
- // rescue ran-but-failed; absent when rescue was skipped (daily
1368
- // budget) or when the rescue produced text (the textResult path
1369
- // already signals via convergenceForced: true). Wrappers can
1370
- // branch retry behaviour on this without log scraping.
1371
- ...(rescueErrorCode !== null ? { rescueErrorCode } : {}),
1372
- ...(rescueErrorMessage !== null ? { rescueErrorMessage } : {}),
1373
- iterations,
1374
- apiCalls,
1375
- cumulativeInputTokens: totalCumulativeInputTokens,
1376
- cumulativeOutputTokens: totalCumulativeOutputTokens,
1377
- // P8 (v1.15.0): include thinking tokens in the failure-path
1378
- // cumulative telemetry — pre-P8 the textResult path emitted
1379
- // `cumulativeThinkingTokens` (line ~1216) but the errorResult
1380
- // path dropped it, leaving operators with an under-reported
1381
- // billing footprint on rescue-attempted-but-failed calls.
1382
- // (TP from gemini-chat F5.)
1383
- cumulativeThinkingTokens: cumulativeThinkingTokens + finalizationUsage.thoughtsTokenCount,
1384
- filesRead: filesReadSet.size,
1385
- });
190
+ return await answerAgentic({ ...request, emitter }, progress);
1386
191
  }
1387
192
  catch (err) {
1388
- logger.error(`ask_agentic failed: ${safeForLog(err)}`);
1389
- const httpStatus = err.status;
1390
- // v1.14.3 (Phase4-F1 follow-up): outer-catch 429 hint extraction for 429s
1391
- // thrown POST-resolution that bypass the inner iter / finalization catches
1392
- // (e.g., a re-thrown 429 from `runAgenticIteration` setup or any code path
1393
- // between resolution and the inner try blocks). `resolved` is hoisted to
1394
- // function scope (above) so the outer catch can now read `resolved.resolved`
1395
- // when the model has already been resolved.
1396
- //
1397
- // PRE-RESOLUTION 429s (the rarer case — Google rate-limiting `models.list()`
1398
- // during the very first call after API-key rotation or quota reset) still
1399
- // DISCARD the hint here: `resolved` is undefined, optional chaining skips
1400
- // the extraction. Recording the hint against the unresolved alias (e.g.,
1401
- // 'latest-pro-thinking') would key the throttle hint to a string that
1402
- // future calls won't match — they'd resolve to a literal model id like
1403
- // `gemini-3-pro-preview`, miss the alias-keyed hint, retry too soon.
1404
- // Tracked as v1.14.4 followup if alias↔literal hint reconciliation
1405
- // becomes worth the throttle-state widening. (Pinned by the
1406
- // `outer-catch 429 from PRE-resolution path... does NOT seed hint` test.)
1407
- if (typeof resolved?.resolved === 'string') {
1408
- const outerRetryDelayMs = isGemini429(err) ? parseRetryDelayMs(err.message) : null;
1409
- if (outerRetryDelayMs !== null) {
1410
- ctx.throttle.recordRetryHint(resolved.resolved, outerRetryDelayMs);
1411
- }
1412
- }
1413
- return errorResult(`ask_agentic failed: ${err instanceof Error ? err.message : String(err)}`, {
1414
- errorCode: 'UNKNOWN',
1415
- retryable: false,
1416
- ...(httpStatus !== undefined ? { httpStatus } : {}),
1417
- });
193
+ return failedCall(err, ctx, progress);
1418
194
  }
1419
195
  finally {
1420
196
  emitter.stop();
1421
197
  }
1422
198
  }
1423
- async function runAgenticIteration(args) {
1424
- const { ctx, resolvedModel, conversation, baseConfig, workspaceRoot, filesReadSet, maxFilesRead, abortSignal, matchConfig, recordChunk, onThoughtChunk, } = args;
1425
- // Each agentic iteration is its own `generateContent` call; a transient
1426
- // pre-response network failure in the middle of a long loop (default 20
1427
- // iterations) would otherwise discard partial progress. `withNetworkRetry`
1428
- // covers `TypeError: fetch failed` (see `src/gemini/retry.ts` for the
1429
- // rationale — SDK-side retry is intentionally disabled because enabling it
1430
- // strips Gemini's informative error bodies; 429 rate-limits continue to be
1431
- // handled at the tool layer via `isGemini429` + `parseRetryDelayMs`).
1432
- //
1433
- // v1.16.2 (T33 TRIM): switched to `generateContentStream` + `collectStream`
1434
- // for two operator wins: (1) live `thinking: …` progress events during the
1435
- // 30-120s thinking phase (previously only iter-counter notifications),
1436
- // (2) heartbeat-aware `stallMs` watchdog that resets on every chunk —
1437
- // catches dead sockets ~30× faster than wall-clock alone without
1438
- // penalising legitimate deep reasoning. Mid-stream failures cannot be
1439
- // retried (Gemini's generateContentStream has no resume), so the retry
1440
- // wraps ONLY the stream OPENING — same contract as `ask`/`code`. The
1441
- // assembled `CollectedResponse` is shape-identical to the previous
1442
- // `GenerateContentResponse`, so all downstream extraction
1443
- // (`response.candidates[0].content.parts`, `response.usageMetadata`) is
1444
- // unchanged. The post-loop forced-finalization rescue keeps the v1.15.0
1445
- // P3 non-streaming `apiCallSucceeded` contract unchanged — see the
1446
- // rescue site for rationale.
1447
- const stream = await withNetworkRetry(() => ctx.client.models.generateContentStream({
1448
- model: resolvedModel,
1449
- contents: conversation,
1450
- config: { ...baseConfig, abortSignal },
1451
- }), {
1452
- signal: abortSignal,
1453
- onRetry: (attempt, err) => {
1454
- logger.warn(`ask_agentic: retrying generateContent after transient network failure (attempt ${attempt}): ${err instanceof Error ? err.message : String(err)}`);
1455
- },
1456
- });
1457
- const response = await collectStream(stream, {
1458
- signal: abortSignal,
1459
- onThoughtChunk,
1460
- onChunkReceived: recordChunk,
1461
- });
1462
- const usage = response.usageMetadata;
1463
- const usageOut = {
1464
- promptTokenCount: typeof usage?.promptTokenCount === 'number' ? usage.promptTokenCount : 0,
1465
- candidatesTokenCount: typeof usage?.candidatesTokenCount === 'number' ? usage.candidatesTokenCount : 0,
1466
- thoughtsTokenCount: typeof usage?.thoughtsTokenCount === 'number' ? usage.thoughtsTokenCount : 0,
1467
- };
1468
- const parts = response.candidates?.[0]?.content?.parts ?? [];
1469
- const functionCallParts = parts.filter((p) => Boolean(p.functionCall && typeof p.functionCall.name === 'string'));
1470
- const thoughtTexts = parts
1471
- .filter((p) => p.thought === true && typeof p.text === 'string')
1472
- .map((p) => p.text);
1473
- const thinkingSummary = thoughtTexts.length > 0 ? thoughtTexts.join('\n').slice(0, 1200) : null;
1474
- // FINAL TEXT path — no function calls requested.
1475
- if (functionCallParts.length === 0) {
1476
- const finalText = response.text ??
1477
- parts
1478
- .map((p) => p.text ?? '')
1479
- .join('')
1480
- .trim();
1481
- return {
1482
- finalText: finalText.length > 0 ? finalText : '(model returned empty response)',
1483
- functionCallCount: 0,
1484
- signatures: [],
1485
- usage: usageOut,
1486
- thinkingSummary,
1487
- // P5 (v1.15.0): final-text iteration appends nothing new to conversation
1488
- // (it's the iteration that exits the loop). No tool-response delta.
1489
- toolResponseTokens: 0,
1490
- };
1491
- }
1492
- // Record the model's response (including the function calls) so the next
1493
- // turn has full context — Gemini requires the full call-response pair to
1494
- // stay in the conversation.
1495
- conversation.push({ role: 'model', parts });
1496
- // Dispatch — positional correlation between functionCallParts[i] and
1497
- // responseParts[i]. Function-call id is not always present (Gemini API
1498
- // marks it optional), so we MUST NOT use id / name for pairing: two
1499
- // parallel same-name calls without ids would then collide, dropping one
1500
- // response and crashing the next turn with Gemini 400 "call/response
1501
- // mismatch". Reported in PR #24 review by GPT + Gemini.
1502
- const callSignatures = [];
1503
- /** responseParts[i] corresponds to functionCallParts[i] — never resort,
1504
- * never dedupe. `null` until either short-circuited or filled after
1505
- * parallel dispatch. */
1506
- const responseParts = new Array(functionCallParts.length).fill(null);
1507
- /** Indices that actually need dispatch, parallel-index-aligned with
1508
- * `toDispatch`. `toDispatch[k]` corresponds to
1509
- * `functionCallParts[dispatchIndexMap[k]]`. */
1510
- const toDispatch = [];
1511
- const dispatchIndexMap = [];
1512
- for (let i = 0; i < functionCallParts.length; i++) {
1513
- const part = functionCallParts[i];
1514
- if (!part)
1515
- continue;
1516
- const fc = part.functionCall;
1517
- const name = fc.name ?? 'unknown';
1518
- const fcArgs = (fc.args ?? {});
1519
- callSignatures.push({ name, args: fcArgs });
1520
- // Short-circuit cap on distinct files read — canonical check.
1521
- // `filesReadSet` is keyed on the sandbox-resolved `relpath`, not the
1522
- // raw input, so path aliases (`./a.ts`, `a.ts`, `sub/../a.ts`) must
1523
- // be resolved here too before comparing — otherwise the pre-dispatch
1524
- // gate rejects legitimate re-reads at cap boundary. PR #24 round-3
1525
- // review by GPT, Gemini, and self-review. Resolving is async (one
1526
- // `realpath` call), but the loop is already `async` and the downstream
1527
- // `dispatchToolCallsParallel` is also awaited, so the added await
1528
- // doesn't serialise anything new.
1529
- if (name === 'read_file' && filesReadSet.size >= maxFilesRead) {
1530
- const reqPath = typeof fcArgs.path === 'string' ? fcArgs.path : '';
1531
- let canonicalRel = null;
1532
- try {
1533
- const r = await resolveInsideWorkspace(workspaceRoot, reqPath);
1534
- canonicalRel = r.relpath;
1535
- }
1536
- catch {
1537
- /* resolve failed — let dispatch produce the real SandboxError
1538
- * (PATH_TRAVERSAL / NOT_FOUND etc.). That way the model gets a
1539
- * useful error shape, not a stale-cap-fire. */
1540
- }
1541
- const alreadyRead = canonicalRel !== null && filesReadSet.has(canonicalRel);
1542
- if (!alreadyRead) {
1543
- responseParts[i] = {
1544
- functionResponse: {
1545
- ...(fc.id ? { id: fc.id } : {}),
1546
- name,
1547
- response: {
1548
- error: `maxFilesRead (${maxFilesRead}) reached. Summarise with what you have already read, or ask a narrower question.`,
1549
- },
1550
- },
1551
- };
1552
- continue;
1553
- }
1554
- }
1555
- dispatchIndexMap.push(i);
1556
- toDispatch.push({ name, args: fcArgs });
1557
- }
1558
- // Dispatch the non-capped calls in parallel.
1559
- // v1.15.1 (P9_a): concurrency now resolves per-call from env override
1560
- // (`GEMINI_CODE_CONTEXT_AGENTIC_TOOL_CONCURRENCY`), default 10. Bumped from 3.
1561
- const dispatched = await dispatchToolCallsParallel(workspaceRoot, toDispatch, resolveToolExecutionConcurrency(), matchConfig);
1562
- // Check abort AFTER tool execution — local file I/O / large grep regex /
1563
- // huge directory walk can take real wall-clock time, and without this
1564
- // check a 5s iterationTimeoutMs could be ignored for the duration of a
1565
- // multi-second tool call. The next iteration would then start with the
1566
- // signal already aborted, but the user's expectation is that the timeout
1567
- // fires AS SOON AS the deadline passes.
1568
- if (abortSignal.aborted) {
1569
- throw abortSignal.reason instanceof Error
1570
- ? abortSignal.reason
1571
- : new DOMException('Operation aborted', 'AbortError');
1572
- }
1573
- // Merge dispatched results back into responseParts at their original
1574
- // positions. Canonicalise filesReadSet using the sandbox-resolved
1575
- // `relpath` field on successful read_file responses — this closes the
1576
- // alias-bypass on `maxFilesRead` because `./a.ts` and `a.ts` both yield
1577
- // `relpath: 'a.ts'` from `resolveInsideWorkspace`.
1578
- for (let k = 0; k < dispatched.length; k++) {
1579
- const res = dispatched[k];
1580
- const originalIdx = dispatchIndexMap[k];
1581
- if (res === undefined || originalIdx === undefined)
1582
- continue;
1583
- const part = functionCallParts[originalIdx];
1584
- if (!part)
1585
- continue;
1586
- const fc = part.functionCall;
1587
- responseParts[originalIdx] = {
1588
- functionResponse: {
1589
- ...(fc.id ? { id: fc.id } : {}),
1590
- name: res.name,
1591
- response: res.response,
1592
- },
1593
- };
1594
- if (res.name === 'read_file' && !res.isError) {
1595
- const canonical = res.response.relpath;
1596
- if (typeof canonical === 'string' && canonical.length > 0) {
1597
- filesReadSet.add(canonical);
1598
- }
1599
- }
1600
- }
1601
- // Filter out any remaining `null` slots — shouldn't happen in practice
1602
- // (every call gets either a short-circuit or a dispatched response), but
1603
- // defensive: skip nulls rather than sending a malformed turn to Gemini.
1604
- const finalResponseParts = responseParts.filter((p) => p !== null);
1605
- conversation.push({ role: 'user', parts: finalResponseParts });
1606
- // P5 (v1.15.0): bytes/4 heuristic for the tool-response payload size — the
1607
- // rescue's `finalizationEstimate` adds this to `lastIterationPromptTokens`
1608
- // so its TPM/budget reservation accounts for the data that was appended to
1609
- // `conversation` AFTER the iteration's `generateContent` returned (which
1610
- // is what the rescue's prompt will replay). Wrap stringify in try so a
1611
- // pathological circular-ref Part (shouldn't happen — Parts are POJOs from
1612
- // the SDK + our `read_file` output — but defensive) falls back to 0
1613
- // rather than blowing the loop. The static `PER_ITERATION_INPUT_TOKENS`
1614
- // fallback at the rescue site still covers the 0-token edge.
1615
- let toolResponseTokens = 0;
1616
- try {
1617
- // CC1 fix (v1.15.0 PR-Round-1, Copilot): use UTF-8 BYTE length, not
1618
- // String#length. The latter returns UTF-16 code units — for non-ASCII
1619
- // content (CJK, emoji) it under-counts the UTF-8 byte size by 2-3x,
1620
- // re-introducing rescue under-reservation on multilingual workloads.
1621
- // Tokenizers approximate from UTF-8 bytes, so bytes/4 stays the
1622
- // intended heuristic; switching to Buffer.byteLength makes the
1623
- // implementation match the doc-comment's documented "bytes/4" semantics.
1624
- const serialized = JSON.stringify(finalResponseParts);
1625
- toolResponseTokens = Math.ceil(Buffer.byteLength(serialized, 'utf8') / 4);
1626
- }
1627
- catch {
1628
- toolResponseTokens = 0;
1629
- }
1630
- return {
1631
- finalText: null,
1632
- functionCallCount: functionCallParts.length,
1633
- signatures: callSignatures,
1634
- usage: usageOut,
1635
- thinkingSummary,
1636
- toolResponseTokens,
1637
- };
1638
- }
1639
- /** Maximum recursion depth for `stableJson`. Function-call args in
1640
- * practice are flat `{path, startLine, endLine}` objects, so 10 levels
1641
- * is generous. Guards against stack overflow if a prompt-injected cache
1642
- * managed to smuggle a nested structure into the model's tool-call args. */
1643
- const STABLE_JSON_MAX_DEPTH = 10;
1644
- /** Stable-key JSON for comparing function-call signatures across
1645
- * iterations. Sorted keys so `{a:1,b:2}` and `{b:2,a:1}` hash identical.
1646
- *
1647
- * Hardening (PR #24 review by Grok): depth-limited + protected against
1648
- * circular references. The outer `JSON.stringify` would throw on a cycle,
1649
- * which we catch; but we also walk with our own depth counter because a
1650
- * deeply nested (non-cyclic) args tree can still blow the stack on the
1651
- * default V8 async-aware trampoline. On overflow or stringify error we
1652
- * fall back to a truncated `String(value)` so the no-progress detector
1653
- * still has SOME key rather than crashing the loop. */
1654
- function stableJson(value, depth = 0) {
1655
- if (depth > STABLE_JSON_MAX_DEPTH)
1656
- return '"[depth-truncated]"';
1657
- if (value === null || typeof value !== 'object') {
1658
- try {
1659
- return JSON.stringify(value);
1660
- }
1661
- catch {
1662
- return `"[unstringifiable:${typeof value}]"`;
1663
- }
1664
- }
1665
- if (Array.isArray(value)) {
1666
- return `[${value.map((v) => stableJson(v, depth + 1)).join(',')}]`;
1667
- }
1668
- try {
1669
- const keys = Object.keys(value).sort();
1670
- return `{${keys
1671
- .map((k) => `${JSON.stringify(k)}:${stableJson(value[k], depth + 1)}`)
1672
- .join(',')}}`;
1673
- }
1674
- catch {
1675
- return `"[unstringifiable-object]"`;
1676
- }
1677
- }
1678
199
  //# sourceMappingURL=ask-agentic.tool.js.map