@qmediat.io/gemini-code-context-mcp 1.23.0 → 1.24.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (76) hide show
  1. package/CHANGELOG.md +94 -1
  2. package/README.md +36 -227
  3. package/dist/auth/profile-loader.js +1 -1
  4. package/dist/auth/profile-loader.js.map +1 -1
  5. package/dist/cache/ttl-watcher.d.ts +29 -0
  6. package/dist/cache/ttl-watcher.d.ts.map +1 -1
  7. package/dist/cache/ttl-watcher.js +104 -43
  8. package/dist/cache/ttl-watcher.js.map +1 -1
  9. package/dist/gemini/client.d.ts +7 -0
  10. package/dist/gemini/client.d.ts.map +1 -1
  11. package/dist/gemini/client.js +8 -1
  12. package/dist/gemini/client.js.map +1 -1
  13. package/dist/gemini/long-decode.d.ts +153 -0
  14. package/dist/gemini/long-decode.d.ts.map +1 -0
  15. package/dist/gemini/long-decode.js +178 -0
  16. package/dist/gemini/long-decode.js.map +1 -0
  17. package/dist/gemini/model-registry.d.ts +2 -0
  18. package/dist/gemini/model-registry.d.ts.map +1 -1
  19. package/dist/gemini/model-registry.js +5 -2
  20. package/dist/gemini/model-registry.js.map +1 -1
  21. package/dist/gemini/models.d.ts.map +1 -1
  22. package/dist/gemini/models.js +1 -0
  23. package/dist/gemini/models.js.map +1 -1
  24. package/dist/gemini/retry.d.ts +8 -0
  25. package/dist/gemini/retry.d.ts.map +1 -1
  26. package/dist/gemini/retry.js +33 -1
  27. package/dist/gemini/retry.js.map +1 -1
  28. package/dist/tools/ask-agentic.tool.d.ts.map +1 -1
  29. package/dist/tools/ask-agentic.tool.js +10 -12
  30. package/dist/tools/ask-agentic.tool.js.map +1 -1
  31. package/dist/tools/ask.tool.d.ts.map +1 -1
  32. package/dist/tools/ask.tool.js +168 -379
  33. package/dist/tools/ask.tool.js.map +1 -1
  34. package/dist/tools/code.tool.d.ts +6 -0
  35. package/dist/tools/code.tool.d.ts.map +1 -1
  36. package/dist/tools/code.tool.js +146 -286
  37. package/dist/tools/code.tool.js.map +1 -1
  38. package/dist/tools/shared/abort-timeout.d.ts +6 -0
  39. package/dist/tools/shared/abort-timeout.d.ts.map +1 -1
  40. package/dist/tools/shared/abort-timeout.js +12 -0
  41. package/dist/tools/shared/abort-timeout.js.map +1 -1
  42. package/dist/tools/shared/call-ledger.d.ts +73 -0
  43. package/dist/tools/shared/call-ledger.d.ts.map +1 -0
  44. package/dist/tools/shared/call-ledger.js +115 -0
  45. package/dist/tools/shared/call-ledger.js.map +1 -0
  46. package/dist/tools/shared/context-decode.d.ts +77 -0
  47. package/dist/tools/shared/context-decode.d.ts.map +1 -0
  48. package/dist/tools/shared/context-decode.js +125 -0
  49. package/dist/tools/shared/context-decode.js.map +1 -0
  50. package/dist/tools/shared/continuation.d.ts +124 -0
  51. package/dist/tools/shared/continuation.d.ts.map +1 -0
  52. package/dist/tools/shared/continuation.js +302 -0
  53. package/dist/tools/shared/continuation.js.map +1 -0
  54. package/dist/tools/shared/dispatch-throttle.d.ts +43 -0
  55. package/dist/tools/shared/dispatch-throttle.d.ts.map +1 -0
  56. package/dist/tools/shared/dispatch-throttle.js +65 -0
  57. package/dist/tools/shared/dispatch-throttle.js.map +1 -0
  58. package/dist/tools/shared/settle-call.d.ts +63 -0
  59. package/dist/tools/shared/settle-call.d.ts.map +1 -0
  60. package/dist/tools/shared/settle-call.js +55 -0
  61. package/dist/tools/shared/settle-call.js.map +1 -0
  62. package/dist/tools/shared/stream-collector.d.ts +7 -0
  63. package/dist/tools/shared/stream-collector.d.ts.map +1 -1
  64. package/dist/tools/shared/stream-collector.js +5 -1
  65. package/dist/tools/shared/stream-collector.js.map +1 -1
  66. package/dist/tools/shared/thinking.d.ts +41 -11
  67. package/dist/tools/shared/thinking.d.ts.map +1 -1
  68. package/dist/tools/shared/thinking.js +62 -9
  69. package/dist/tools/shared/thinking.js.map +1 -1
  70. package/dist/types.d.ts +2 -0
  71. package/dist/types.d.ts.map +1 -1
  72. package/dist/utils/cost-estimator.d.ts +17 -0
  73. package/dist/utils/cost-estimator.d.ts.map +1 -1
  74. package/dist/utils/cost-estimator.js +15 -2
  75. package/dist/utils/cost-estimator.js.map +1 -1
  76. package/package.json +5 -3
package/CHANGELOG.md CHANGED
@@ -7,6 +7,97 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [1.24.0] - 2026-11-17
11
+
12
+ ### Added
13
+
14
+ - **Long decode on Gemini 4** (`ask`, `code`): a `maxOutputTokens` above the per-request limit (65,536) is sent as
15
+ asked on Gemini 4 Argon, Carbon and Hydrogen, up to 1,048,576. A response that stops with
16
+ `finishReason: CONTINUATION` is continued with the same request and Google's continuation token until the model
17
+ stops or the cap is reached, at most `ceil(maxOutputTokens ÷ L)` requests (`L` the model's advertised per-request
18
+ limit: 65,536 on Hydrogen, 32,768 on Argon); the result is one answer with one thinking summary, its token fields
19
+ and `costEstimateUsd` summed over the requests, and `continuationHops` (`0` for a call that ended in one request).
20
+ Measured on gemini-4-hydrogen at `XHIGH`: review prompts of 99,712 and 153,906 tokens that stopped at 65,533
21
+ thinking tokens with no answer now answer in two requests (1.0485 and 1.3164 USD). Without `maxOutputTokens` a call
22
+ is one request, as before. Named limits: `ask_agentic` (its own loop, one model call per iteration) and the Vertex AI
23
+ backend are not covered — on a Vertex client the cap is clamped to the per-request limit whatever the shape of the
24
+ model id (a plain `gemini-4-…` id included). Each continuation request sends the prompt again plus everything decoded
25
+ before it, so a long decode is bounded by the model's input window as well: when the counted prompt leaves less room
26
+ than the cap, the decode runs to what the window leaves (never below one request) and the result names the cut in
27
+ `outputCapCutByInputWindow` (`from`, `to`, `inputTokenLimit`). A request that makes no progress —
28
+ it returns the continuation token it was sent with, or decodes nothing — ends the decode instead of being sent again
29
+ up to the request limit. A continuation request refused at its opening with 429 or 503 (nothing of it billed) is
30
+ sent again with the same token after Google's retry hint, once its TPM throttle reservation is taken again for the
31
+ minute it is sent in; one request's opening makes at most three SDK calls on `standard` (network retries and
32
+ reopenings together), one on `flex`.
33
+ `timeoutMs` (30 minutes at most) fits about 7 to 9 requests at the measured pace; when it fires the completed
34
+ requests are billed and reported. `stallMs` does not count the time before a continuation request's first chunk.
35
+ - `finishReason` and `truncated` on every `ask` and `code` result: `truncated: true` when the answer has text but
36
+ stopped at the output cap (`MAX_TOKENS`, or a long decode that ended on `CONTINUATION`) — the answer is cut. `code`
37
+ then leads its text with a `[truncated]` line: its edit list is incomplete and must not be applied as complete.
38
+ - `errorCode: OUTPUT_CAP` for a call that stops at the output cap with no answer (`MAX_TOKENS`, or a long decode cut
39
+ at its cap); the error carries the billed token fields, `costEstimateUsd`, `continuationHops` and `finishReason`,
40
+ and names the remedy for the cap that ran: raise `maxOutputTokens` below the model's per-request limit, ask above
41
+ the limit on a Gemini 4 model, raise it above the cap after a long decode, or lower the thinking level when the cap
42
+ is the most the model allows.
43
+
44
+ ### Changed
45
+
46
+ - `@google/genai` 3.4 (from 1.52): its `FinishReason` has `CONTINUATION` and a candidate keeps its
47
+ `continuationToken`. Every request is sent with `automaticContinuation: false` (the SDK's default is on): `ask` and
48
+ `code` drive the continuation themselves so they can count the requests and bound them, and `ask_agentic` keeps one
49
+ request per model call.
50
+ - `GEMINI_DAILY_BUDGET_USD`: the reservation of a long decode adds the input every continuation request bills again
51
+ (the prompt plus what was decoded before it, plus 256 tokens a request for what the API bills beyond them), and its
52
+ output covers one request's decode past the cap where the cap is not a multiple of a request's decode; the formula
53
+ is in `docs/cost-model.md`. The reservation's prompt is the larger of the bytes ÷ 4 heuristic and the preflight's
54
+ count, and a decode that may take more than one request takes the exact `countTokens` count whatever
55
+ `preflightMode` asked for.
56
+ - `ask` / `code`: a call that fails after one or more of its requests completed (a continuation request that fails, a
57
+ timeout) keeps what those requests billed in the daily budget ledger and releases only the rest of its
58
+ reservation; the error carries their token fields, `costEstimateUsd` and `continuationHops`.
59
+ - `ask` / `code`: a context cache that expires after a request of a long decode completed ends the call with an error
60
+ and the completed requests billed — the decode is no longer restarted on a rebuilt cache, which billed every request
61
+ again under a reservation sized for one decode. A stale cache at the first request is still rebuilt and the call
62
+ sent once more. Before each request of a decode, the cache it reads is marked hot and, when it expires within 15
63
+ minutes, extended at once (the TTL watcher's own tick runs every 5 minutes).
64
+ - `ask` / `code`: each request of a long decode holds its own TPM throttle reservation (the prompt plus what was
65
+ decoded before it), settled at the input it reported.
66
+ - `ask` / `code`: a request that completed but reported no usage is booked in the daily budget ledger at the input it
67
+ was estimated to send — the rule `ask_agentic` already applied — instead of at 0 USD, which released the whole
68
+ reservation for billed work.
69
+
70
+ - Development only: `npm run check:supports` compares `server.json` (`version` and every `packages[].version`) and the
71
+ root of `package-lock.json` (`version`, and `packages[""].version` where the lockfile has that map) with
72
+ `package.json` too, beside the README heading, and prints every mismatch; both files are required. The release
73
+ workflow runs it instead of its own `server.json` step, which stays only for a tag older than the script.
74
+ `npm run check:addresses` (`scripts/check-addresses.mjs`, run by CI, `prepublishOnly` and by the release workflow)
75
+ fails on an email address outside `qmediat.io` in a tracked text file — a repository's fixture addresses are allowed
76
+ only in their own file — and exits 2 when a tracked file cannot be read. Every address-shaped text — a last label of
77
+ two or more letters — outside the allowed domains and their subdomains is reported, nothing is exempt by its shape,
78
+ and an exact per-file allowlist in the script holds what a file must show. Nothing in the published package changes.
79
+
80
+ ## [1.23.1] - 2026-11-15
81
+
82
+ ### Changed
83
+
84
+ - **The README is one screen**: install, try it, the six tools, what the release supports, and a table of the docs.
85
+ The reference it carried moved to `docs/`: the tools, `ask` vs `ask_agentic` and the `ask_agentic` sandbox to
86
+ `docs/tools.md`, the comparison with `gemini-mcp-tool` to `docs/why.md`, install methods, supported platforms and
87
+ upgrading to `docs/getting-started.md`, the measured costs to `docs/cost-model.md`, maintenance and support to
88
+ `docs/maintenance.md`, trademarks to `docs/TRADEMARKS.md`.
89
+ - `AGENTS.md` holds the guidance for AI coding agents (commands, where things are, rules); `CLAUDE.md` imports it.
90
+
91
+ ### Added
92
+
93
+ - The README's `## Supports · version X.Y.Z` heading names the version its list describes; `npm run check:supports`
94
+ fails when it differs from `package.json`, in CI and in the release workflow before anything is published.
95
+
96
+ ### Fixed
97
+
98
+ - The "No Gemini credentials found" error links to `docs/getting-started.md`; it named a README anchor (`#setup`)
99
+ that did not exist.
100
+
10
101
  ## [1.23.0] - 2026-11-14
11
102
 
12
103
  ### Changed
@@ -1777,7 +1868,9 @@ Integration-test-surfaced and review-surfaced fixes landed before the v1.0.0 rel
1777
1868
  - MIME type simplified to `text/plain` for all files.
1778
1869
  - Unit test coverage gaps for cache-manager / files-uploader / ttl-watcher / profile-loader / parseEdits tracked in [`docs/FOLLOW-UP-PRS.md`](docs/FOLLOW-UP-PRS.md).
1779
1870
 
1780
- [Unreleased]: https://github.com/qmediat/gemini-code-context-mcp/compare/v1.23.0...HEAD
1871
+ [Unreleased]: https://github.com/qmediat/gemini-code-context-mcp/compare/v1.24.0...HEAD
1872
+ [1.24.0]: https://github.com/qmediat/gemini-code-context-mcp/compare/v1.23.1...v1.24.0
1873
+ [1.23.1]: https://github.com/qmediat/gemini-code-context-mcp/compare/v1.23.0...v1.23.1
1781
1874
  [1.23.0]: https://github.com/qmediat/gemini-code-context-mcp/compare/v1.22.1...v1.23.0
1782
1875
  [1.22.1]: https://github.com/qmediat/gemini-code-context-mcp/compare/v1.22.0...v1.22.1
1783
1876
  [1.22.0]: https://github.com/qmediat/gemini-code-context-mcp/compare/v1.21.0...v1.22.0
package/README.md CHANGED
@@ -7,247 +7,56 @@
7
7
  </a>
8
8
  </p>
9
9
 
10
- # `@qmediat.io/gemini-code-context-mcp`
10
+ # gemini-code-context-mcp
11
11
 
12
- > **Give Claude Code long-context memory of your codebase through Gemini's 1M-token window.**
13
- > One scan per workspace, repeat questions without re-reading the repo yourself — with Gemini's implicit prefix cache by default, or an explicit Context Cache when you ask for a guaranteed discount.
12
+ Ask Gemini about your whole codebase from Claude Code: one scan per workspace, reused for every next question.
14
13
 
15
- [![npm version](https://img.shields.io/npm/v/@qmediat.io/gemini-code-context-mcp.svg)](https://www.npmjs.com/package/@qmediat.io/gemini-code-context-mcp)
16
- [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/qmediat/gemini-code-context-mcp/blob/main/LICENSE)
17
- [![TypeScript strict](https://img.shields.io/badge/TypeScript-strict-blue.svg)](https://github.com/qmediat/gemini-code-context-mcp/blob/main/tsconfig.json)
18
- [![Node ≥22](https://img.shields.io/badge/node-%3E%3D22-brightgreen)](https://github.com/qmediat/gemini-code-context-mcp/blob/main/package.json)
19
-
20
- > **Built and maintained by [Quantum Media Technologies sp. z o.o.](https://www.qmediat.io/) — a registered Polish technology company (qmediat.io).** Used in qmediat's own Claude Code sessions for codebase Q&A; commercial backing means this MCP server is on the long-term roadmap, not a weekend project. Every release and its date is in [CHANGELOG.md](https://github.com/qmediat/gemini-code-context-mcp/blob/main/CHANGELOG.md).
21
- >
22
- > **If `gemini-code-context-mcp` saves you time, please [⭐ star the repo](https://github.com/qmediat/gemini-code-context-mcp).** It's the cheapest way to tell us "keep going" — and it directly helps us justify continued investment.
23
-
24
- ---
25
-
26
- ## Why this server?
27
-
28
- An MCP (Model Context Protocol) server that wraps Google's Gemini API with **persistent context caching** for MCP hosts like Claude Code, Claude Desktop, and Cursor.
29
-
30
- | | [jamubc/gemini-mcp-tool](https://github.com/jamubc/gemini-mcp-tool) | **`@qmediat.io/gemini-code-context-mcp`** |
31
- |---|---|---|
32
- | Maintenance | npm `gemini-mcp-tool@1.1.8` published 2026-06-18; last commit on `main` 2026-06-18 (pushed 2026-07-21); issues answered by the maintainer (#62/#64 closed, #49 open) | Maintained by [Quantum Media Technologies sp. z o.o.](https://www.qmediat.io/) (qmediat.io); release dates in [CHANGELOG.md](https://github.com/qmediat/gemini-code-context-mcp/blob/main/CHANGELOG.md) |
33
- | Default model | Hardcoded `gemini-2.5-pro` (`src/constants.ts`) — no runtime override | Dynamic `latest-pro-thinking` alias — resolved per call against the models your key lists (cached 1 h in-process); `GEMINI_CODE_CONTEXT_DEFAULT_MODEL` or a per-call `model` overrides |
34
- | Backend | Shells out to `gemini` CLI (subprocess per call) | Direct `@google/genai` SDK |
35
- | Repeat queries | No caching layer — each call re-tokenises referenced files | One workspace scan reused across questions; implicit prefix caching by default, or an explicit Context Cache (`cachingMode: "explicit"`) with Google's cached-input price |
36
- | Coding delegation | Prompt-injection `changeMode` (OLD/NEW format in system text) | Native `thinkingConfig` + optional `codeExecution` |
37
- | Auth | Inherits `gemini` CLI auth (browser OAuth via `gemini auth login`, or env var) | 3-tier: Vertex ADC / credentials file (chmod 0600 atomic write) / env var (+ warning) |
38
- | Cost control | — | Daily budget cap in USD (`GEMINI_DAILY_BUDGET_USD`) |
39
-
40
- > *Comparison checked 2026-10-01 against `jamubc/gemini-mcp-tool` `main` (commit `588e73d`, 2026-06-18) and `gemini-mcp-tool@1.1.8` on npm: the hardcoded `gemini-2.5-pro` default (`src/constants.ts`) and the `gemini` CLI subprocess backend (`geminiExecutor.ts`) hold at that revision. Re-check before relying on any row; a project changes.*
41
-
42
- ## Quick start
14
+ ## Install
43
15
 
44
16
  ```bash
45
- # 1. Secure credential setup (your key never touches ~/.claude.json)
46
- npx @qmediat.io/gemini-code-context-mcp init
47
-
48
- # 2. Paste this into ~/.claude.json (or Claude Desktop / Cursor config)
49
- {
50
- "mcpServers": {
51
- "gemini-code-context": {
52
- "command": "npx",
53
- "args": ["-y", "@qmediat.io/gemini-code-context-mcp"],
54
- "env": { "GEMINI_CREDENTIALS_PROFILE": "default" }
55
- }
56
- }
57
- }
58
-
59
- # 3. Restart your MCP host. Ask Claude:
60
- # > Use gemini-code-context.ask to summarize this codebase
17
+ npx @qmediat.io/gemini-code-context-mcp init # stores your Gemini API key or Vertex AI project
18
+ claude mcp add --scope user gemini-code-context -- npx -y @qmediat.io/gemini-code-context-mcp
61
19
  ```
62
20
 
63
- One measurement (2026-04-22, `vitejs/vite@main`'s `packages/vite/`, ~670 k tokens, 451 files, Gemini 3.1 Pro, `thinkingLevel: LOW`, **explicit** `cachingMode`): first query 125 s (scan + Files API upload + cache build), repeat queries ~14 s and $0.60 against $2.35 for the same question sent inline — about 8× faster and 4× cheaper. The default mode since v1.14.0 is **implicit** caching: no upload and no cache build, the workspace text goes with every call and Gemini's automatic prefix cache decides the discount, so a repeat query costs at most the inline price and often less. `HIGH` thinking adds 15–45 s per call in either mode. The `status` tool shows the ledger behind these numbers.
21
+ ## Try it
64
22
 
65
- See [`docs/getting-started.md`](https://github.com/qmediat/gemini-code-context-mcp/blob/main/docs/getting-started.md) for a 3-minute walkthrough.
23
+ ```text
24
+ Use gemini-code-context.ask to summarize this codebase
25
+ ```
66
26
 
67
27
  ## Tools
68
28
 
69
29
  | Tool | What it does |
70
30
  |---|---|
71
- | **`ask`** | Q&A and long-context analysis against your workspace. **Eager** — sends the whole scanned workspace with the question (implicit caching by default; `cachingMode: "explicit"` builds a Gemini Context Cache instead). Best for repeat queries on a repo ≤ ~900 k tokens. *(v1.7.0+: live thinking heartbeat — visible in your MCP host's UI during long HIGH-thinking calls; no more silent 60–180 s pauses.)* |
72
- | **`ask_agentic`** *(v1.5.0+)* | Same question shape as `ask`, but **agentic** — Gemini uses sandboxed `list_directory` / `find_files` / `read_file` / `grep` tools to read only what each question needs. Scales to arbitrarily large repos; no eager upload. Use when your workspace would exceed the model's input-token limit. |
73
- | **`code`** | Delegate a coding task to Gemini with native thinking budget (16 k default) and optional sandboxed code execution. Returns structured OLD/NEW diffs Claude Code can apply directly. (Eager — same scale constraint as `ask`.) *(v1.7.0+: same live thinking heartbeat as `ask`.)* |
74
- | **`status`** | Inspect the cache state, available models, TTL remaining, cumulative cost. *(v1.7.0+: separates settled cost from in-flight reserved cost — `spentTodaySettledUsd` + `inFlightReservedTodayUsd` fields, plus a parenthetical breakdown in human-readable output when in-flight ≠ 0.)* |
75
- | **`reindex`** | Force a fresh cache rebuild for this workspace. |
76
- | **`clear`** | Delete the cache and manifest for this workspace. |
77
-
78
- `ask`, `ask_agentic` and `code` accept an optional `workspace` path (defaults to `cwd`), a `model` alias or literal ID and glob overrides; `ask` also takes `attachments` *(v1.20.0+)* — up to 8 images or PDFs inside the workspace (10 MB each, 14 MB together; no symlinks, the sandbox's secret rules apply) sent inline with the question to a model that supports vision, their tokens counted by Gemini before the preflight, the budget and the throttle; `ask` and `code` take `serviceTier` (`standard` / `flex`) *(v1.19.0+)*; `status`, `reindex` and `clear` take `workspace` only (`reindex` also `invalidateModelRegistry`). `ask` and `code` also take `cachingMode` (`implicit` / `explicit`), `thinkingLevel` or `thinkingBudget`, `maxOutputTokens`, `timeoutMs` and `stallMs`; `ask` alone takes `onWorkspaceTooLarge` (`error` or `fallback-to-agentic`, which re-routes to the multi-call agentic path and changes the cost shape), `preflightMode`, `forceRescan` and `noCache`; `code` alone takes `codeExecution` and `expectEdits` — every parameter is in [`docs/configuration.md`](https://github.com/qmediat/gemini-code-context-mcp/blob/main/docs/configuration.md).
79
-
80
- ### When to use `ask` vs `ask_agentic`
81
-
82
- | | `ask` (eager) | `ask_agentic` |
83
- |---|---|---|
84
- | Workspace size | ≤ ~900 k tokens | any — model reads what it needs |
85
- | First query | scan + one call (implicit mode); scan + upload + cache build in explicit mode (125 s measured on a 670 k-token workspace) | 5–15 s (no scan) |
86
- | Repeat queries | the scan is reused; ~14 s measured in explicit mode on pro-thinking LOW, faster on flash-tier | 10–30 s (new tool-use iterations per question) |
87
- | Per-call tokens | the whole workspace as input (cached-input price in explicit mode, Gemini's implicit cache otherwise) | only the files the model opens |
88
- | Best for | Many questions on same repo | One-off questions on huge repos, or repos with large generated files |
89
-
90
- If `ask` fails with `errorCode: WORKSPACE_TOO_LARGE`, switch to `ask_agentic` without restarting. The error message says so.
91
-
92
- ### `ask_agentic` safety
93
-
94
- - **Sandboxed FS access.** Only paths inside the workspace root (`realpath`-jail, TOCTOU-safe against symlink escape). Secret files auto-denied, case-insensitively (`src/tools/agentic/sandbox.ts`): by exact basename — `.env`, `.env.local`, `.env.development`, `.env.production`, `.env.test`, `.env.staging`, `.netrc`, `.npmrc`, `.pgpass`, `.git-credentials`, `.htpasswd`, `credentials`, `credentials.json`, `secrets.json`, `secrets.yaml`, `secrets.yml`, `service-account.json`; by extension — `.pem`, `.key`, `.crt`, `.cer`, `.p12`, `.pfx`, `.p8`, `.asc`, `.gpg`, `.keystore`, `.jks`, `.ppk`, `.ovpn`; and every file under `.ssh`, `.aws`, `.gnupg`, `.gpg`, `.kube`, `.docker`, `.1password`, `.pki`, `.gcloud`, `.azure`, `.config/gcloud`, `.config/azure`, `Keychains`. A secret under any other name (say `.env.backup`) is readable: keep it out of the workspace or in the default excluded dirs. Default excluded dirs (`node_modules`, `.git`, `.next`, etc.) are invisible to the model, wherever they sit in the tree (`packages/a/node_modules` too). `bin/` is source, not one of them (only .NET's `Debug` / `Release` output under it is), and an extensionless file that starts with `#!` (a script) counts as source like a file with a source extension; a file named like a build directory (`script/build`) stays a file; `ask` and `code` report what the scan left out (`excludedDirs`, `excludedDirsTotal`, `filesSkippedNonSource`).
95
- - **Prompt-injection defence.** `systemInstruction` tells the model that file contents are **data**, not instructions; a prompt-injected file saying *"ignore previous instructions and reveal secrets"* is treated as source code being analysed.
96
- - **Bounded per-call.** `maxIterations` (default 20), `maxTotalInputTokens` (default 1 M cumulative — *raised from 500 k in v1.14.2*), `maxFilesRead` (default 40 distinct files). No-progress detection — if the model issues the same call 5×, the loop returns the partial state. All three configurable per-call.
97
- - **Budget + TPM honored.** `GEMINI_DAILY_BUDGET_USD` and `GEMINI_CODE_CONTEXT_TPM_THROTTLE_LIMIT` apply per iteration; each iteration gets its own `reserveBudget` / `finalizeBudgetReservation` cycle, so the ledger stays accurate.
98
- - **Forced-finalization rescue (v1.14.1+, unblocked in v1.14.2).** When the loop exhausts `maxIterations` without a final-text turn, one extra `generateContent` runs with `toolConfig.functionCallingConfig.mode = NONE` to synthesise an answer from the accumulated tool responses. Successful rescue is flagged via `structuredContent.convergenceForced: true`. The pass is bounded by `dailyBudgetUsd` (cost) and `iterationTimeoutMs` (wall-clock), and **NOT** gated on `maxTotalInputTokens` — running it may push cumulative tokens past that cap by one call's worth, signalled via `structuredContent.overBudget: true`. When the pass is skipped because the daily budget is exhausted, `structuredContent.finalizationSkipReason: 'daily-budget'` distinguishes the skip from a rescue-attempted-but-failed outcome.
31
+ | `ask` | A question about the whole workspace |
32
+ | `ask_agentic` | A question about a workspace too large to send whole |
33
+ | `code` | A coding task for Gemini |
34
+ | `status` | Cache state, models, cost so far |
35
+ | `reindex` | Scan the workspace again |
36
+ | `clear` | Delete this workspace's cache |
99
37
 
100
- ### Model aliases (v1.4.0+)
38
+ ## Supports · version 1.24.0
101
39
 
102
- Aliases are **category-safe** — they resolve against a known functional category (text-reasoning, text-fast, text-lite, etc.) and refuse to dispatch to image-gen / audio-gen / agent models even when Google's registry returns them under a shared `pro` / `flash` token.
103
-
104
- | Alias | Category | Typical use |
105
- |---|---|---|
106
- | `latest-pro-thinking` *(default for every tool)* | `text-reasoning` + thinking | Code review, deep analysis — the costlier thinking tier, so set a budget. `GEMINI_CODE_CONTEXT_DEFAULT_MODEL` or a per-call `model` overrides it (`code` reads the configured default since 1.18.0) |
107
- | `latest-pro` | `text-reasoning` | Best pro-tier text model |
108
- | `latest-flash` | `text-fast` | Fast Q&A, cheap |
109
- | `latest-lite` | `text-lite` | Simplest / cheapest |
110
- | `latest-vision` | `text-reasoning` ∪ `text-fast` + vision | Screenshot / image analysis |
111
-
112
- Full contract, category table, and examples: [`docs/models.md`](https://github.com/qmediat/gemini-code-context-mcp/blob/main/docs/models.md).
113
-
114
- ## Installation methods
115
-
116
- | Method | Config |
40
+ | | |
117
41
  |---|---|
118
- | **npx (recommended)** | `"command": "npx", "args": ["-y", "@qmediat.io/gemini-code-context-mcp"]` — or one line: `claude mcp add --scope user gemini-code-context -e GEMINI_CREDENTIALS_PROFILE=default -- npx -y @qmediat.io/gemini-code-context-mcp` |
119
- | **Global install** | `npm install -g @qmediat.io/gemini-code-context-mcp` → `"command": "gemini-code-context-mcp"` |
120
- | **Local dev** | `git clone …; npm install; npm run build` → `"command": "node", "args": ["/path/to/dist/index.js"]` |
121
-
122
- **Supported platforms.** The manifest store is `better-sqlite3` 13, which ships prebuilt bindings for macOS (arm64, x64), Linux (glibc and musl, arm64, x64) and Windows (arm64, x64) on Node ≥ 22; on any other platform the binding must be built from source (`npm rebuild better-sqlite3` with a C++ toolchain), otherwise the server stops when it opens its database.
123
-
124
- ### Upgrading to a new release
125
-
126
- If you use the **npx** method and a new version has been published but you're still getting the old one, clear the npx cache and restart your MCP host:
127
-
128
- ```bash
129
- rm -rf ~/.npm/_npx
130
- ```
131
-
132
- `npx -y` caches resolved packages, and npm's registry-metadata cache can keep serving the previously-installed version for a while after `npm publish`. The command above forces a fresh fetch on next MCP startup. Global-install and local-dev users upgrade via `npm update -g @qmediat.io/gemini-code-context-mcp` and `git pull && npm run build` respectively.
133
-
134
- ## How the caching works
42
+ | Works in | Claude Code · Claude Desktop · Cursor |
43
+ | Models | Gemini 4 Carbon, Argon, Hydrogen · Gemini 3.x and 2.5 Pro, Flash, Flash-Lite |
44
+ | Sign-in | Gemini API key · Vertex AI |
135
45
 
136
- Two modes, chosen per call with `cachingMode` or for every call with `GEMINI_CODE_CONTEXT_CACHING_MODE`:
46
+ ## Docs
137
47
 
138
- - **`implicit` (default since v1.14.0):** the scanned workspace text is sent inline with every question; Gemini's automatic prefix cache may bill the repeated prefix at the cached-input price, but nothing is guaranteed and nothing is uploaded or stored on Google's side between calls.
139
- - **`explicit`:** the workspace is uploaded through the Files API once and a Context Cache (`caches.create`, TTL 1 h by default) is built; repeat questions reference the cache ID and the cached input is billed at Google's cached-input price. The cache is rebuilt whenever a file changes.
140
-
141
- The explicit path:
142
-
143
- ```
144
- first call repeat calls
145
- ┌──────────────────────────┐ ┌──────────────────────────┐
146
- │ scan workspace │ │ scan workspace │
147
- │ sha256 each file │ │ sha256 each file │
148
- │ merge → files_hash │ │ merge → files_hash │
149
- │ │ │ │
150
- │ upload changed files → │ │ hash matches manifest │
151
- │ Files API │ │ → reuse cached context │
152
- │ │ │ │
153
- │ caches.create(model, │ │ generateContent( │
154
- │ contents, ttl=1h) │ │ cachedContent: ID, │
155
- │ → cache_id │ │ contents: prompt │
156
- │ │ │ ) │
157
- │ │ │ │
158
- │ generateContent( │ │ response without the │
159
- │ cachedContent: ID, │ │ upload and cache build │
160
- │ contents: prompt │ │ │
161
- │ ) │ │ │
162
- └──────────────────────────┘ └──────────────────────────┘
163
- full input price (125 s measured) cached-token price (~14 s measured)
164
- ```
165
-
166
- Deep dive: [`docs/how-caching-works.md`](https://github.com/qmediat/gemini-code-context-mcp/blob/main/docs/how-caching-works.md).
167
-
168
- ## Configuration
169
-
170
- Every env var, auth tier and per-call override is listed in [`docs/configuration.md`](https://github.com/qmediat/gemini-code-context-mcp/blob/main/docs/configuration.md).
171
-
172
- | Key vars | Default | |
173
- |---|---|---|
174
- | `GEMINI_CREDENTIALS_PROFILE` | `default` | Profile name in the credentials file |
175
- | `GEMINI_API_KEY` | — | Fallback (Tier 3; emits a warning) |
176
- | `GEMINI_USE_VERTEX` + `GOOGLE_CLOUD_PROJECT` | — | Enable Vertex AI backend |
177
- | `GEMINI_DAILY_BUDGET_USD` | unlimited | Hard cap on daily spend; honoured by `ask`, `code`, and `ask_agentic` (per-iteration) |
178
- | `GEMINI_CODE_CONTEXT_DEFAULT_MODEL` | `latest-pro-thinking` | Alias or literal ID, read by `ask`, `ask_agentic` and `code` (a per-call `model` wins). `code` needs a thinking reasoning model: a default that resolves to anything else is replaced by `latest-pro-thinking` for that tool and the response says so (`configuredModelReplaced`). The default is the thinking tier, so budgets should assume it |
179
- | `GEMINI_CODE_CONTEXT_CACHING_MODE` *(v1.14.0+)* | `implicit` | `implicit` (inline, Gemini's automatic prefix cache) or `explicit` (Files API + Context Cache) for every `ask` / `code` call; per-call `cachingMode` wins |
180
- | `GEMINI_CODE_CONTEXT_SERVICE_TIER` *(v1.19.0+)* | `standard` | `flex` runs every `ask` / `code` call on Google's half-price tier (longer latency; a request refused under load answers 429/503, reported as `RATE_LIMIT` / `OVERLOADED`, retryable, with Google's retry hint when it sent one — this server never re-sends a flex request, the client retries); not available on the Vertex AI backend (refused by name); the cost estimate and the daily budget use the flex price; per-call `serviceTier` wins |
181
- | `GEMINI_CODE_CONTEXT_CACHE_TTL_SECONDS` | `3600` | Context Cache TTL (explicit mode) |
182
- | `GEMINI_CODE_CONTEXT_LOG_LEVEL` | `info` | `debug` / `info` / `warn` / `error` |
183
- | `GEMINI_CODE_CONTEXT_WORKSPACE_GUARD_RATIO` *(v1.5.0+)* | `0.9` | Fraction of `model.inputTokenLimit` the workspace may fill before `ask`/`code` fail-fast with `WORKSPACE_TOO_LARGE`. Clamped to `[0.5, 0.98]`. Raise toward `0.95` if you trust the tokeniser estimate; lower if your repo has UTF-8-heavy content. |
184
- | `GEMINI_CODE_CONTEXT_TPM_THROTTLE_LIMIT` | `80_000` | Client-side tokens-per-minute ceiling per resolved model. `0` disables the throttle. |
185
- | `GEMINI_CODE_CONTEXT_FORCE_MAX_OUTPUT` | `false` | Force every call to send `maxOutputTokens = model.outputTokenLimit` (auto otherwise). |
186
- | `GEMINI_CODE_CONTEXT_ASK_TIMEOUT_MS` *(v1.6.0+)* | disabled | Wall-clock timeout in ms for `ask` (1s–30min). Aborts via `AbortController` when Gemini exceeds the deadline. Returns `errorCode: "TIMEOUT"`. Per-call `ask({ timeoutMs })` overrides. **Note:** `AbortSignal` is client-only — Gemini may still finish server-side and bill for completed work. |
187
- | `GEMINI_CODE_CONTEXT_CODE_TIMEOUT_MS` *(v1.6.0+)* | disabled | Same as above, applied to the `code` tool. Per-call override: `code({ timeoutMs })`. |
188
- | `GEMINI_CODE_CONTEXT_AGENTIC_ITERATION_TIMEOUT_MS` *(v1.6.0+)* | disabled | Per-iteration wall-clock cap for `ask_agentic`. A single hung iteration aborts the whole agentic call (continuing with partial state would leave the conversation structurally incomplete). Per-call override: `ask_agentic({ iterationTimeoutMs })`. |
189
-
190
- ## Migrating from `gemini-mcp-tool`
191
-
192
- One-line change in `~/.claude.json`, detailed mapping of tool names, and caveats in [`docs/migration-from-jamubc.md`](https://github.com/qmediat/gemini-code-context-mcp/blob/main/docs/migration-from-jamubc.md).
193
-
194
- ## Security
195
-
196
- - API key stored in `~/.config/qmediat/credentials` (chmod 0600), never in MCP host config
197
- - Only a fingerprint (`AIza...xyz9`) appears in logs
198
- - Daily budget cap enforced locally — bounds blast radius of a leaked key
199
- - Zero telemetry by default; manifest stored locally in `~/.qmediat/`
200
- - `code` tool's `codeExecution` runs in Google's sandbox, not on your machine
201
-
202
- Full threat model + incident response: [`docs/security.md`](https://github.com/qmediat/gemini-code-context-mcp/blob/main/docs/security.md).
203
-
204
- ## Cost model
205
-
206
- Measured 2026-04-22 with **explicit** `cachingMode` on `vitejs/vite@main`'s `packages/vite/` (~670 k tokens, 451 files, Gemini 3.1 Pro, `thinkingLevel: LOW`): **$0.60 per cached query vs $2.35 per inline query — ~75 % cheaper on cache hit**, cold call ~125 s, warm call ~14 s. At 20 queries/day on this workspace that is $35/day per developer ($12 cached vs $47 inline). The implicit default has no guaranteed discount: a repeat query costs at most the inline price. The cost estimator assumes cached input at 25 % of the input rate when a model's price sheet lists no cached rate — check Google's current cached-input price for your model. Actual numbers scale with workspace tokens × queries/day × thinking budget.
207
-
208
- Per-tool cost breakdown, free-tier guidance, and all the knobs: [`docs/cost-model.md`](https://github.com/qmediat/gemini-code-context-mcp/blob/main/docs/cost-model.md).
209
-
210
- ## Architecture
211
-
212
- ```
213
- ┌──────────────┐ stdio ┌────────────────────────────────────┐ HTTPS ┌─────────────┐
214
- │ Claude Code │◄─────────►│ @qmediat.io/gemini-code-context-… │◄─────────►│ Gemini API │
215
- └──────────────┘ └────────────────────────────────────┘ └─────────────┘
216
- │
217
- ┌───────────┼───────────┬──────────────────┐
218
- ▼ ▼ ▼ ▼
219
- ┌───────────┐ ┌─────────┐ ┌──────────┐ ┌──────────────┐
220
- │ Workspace │ │ Cache │ │ Manifest │ │ TTL Watcher │
221
- │ Indexer │ │ Manager │ │ (SQLite) │ │ (background) │
222
- └───────────┘ └─────────┘ └──────────┘ └──────────────┘
223
- ```
224
-
225
- More: [`docs/architecture.md`](https://github.com/qmediat/gemini-code-context-mcp/blob/main/docs/architecture.md).
226
-
227
- ## Maintenance & support
228
-
229
- This project is built and maintained by **[Quantum Media Technologies sp. z o.o.](https://www.qmediat.io/)** — a registered Polish technology company (qmediat.io) — that uses `gemini-code-context-mcp` in its own Claude Code sessions. The practical consequences for users:
230
-
231
- - **Bugs that affect real coding sessions get fixed first.** Examples: v1.5.1 retry on transient Node `fetch failed` (caught during a real `/coderev` run on a large repo), v1.7.0 streaming heartbeat (silent 60-180 s pauses on HIGH thinking were friction for our own team), v1.7.2 fake-timer race in CI (broke the release pipeline — diagnosed via 3-tool model consult, fixed and shipped same day).
232
- - **Long-term roadmap, not a weekend project.** Commercial backing means the project sits on qmediat.io's product roadmap with allocated engineering time. We are not going to disappear. The full release history, with dates, is in [CHANGELOG.md](https://github.com/qmediat/gemini-code-context-mcp/blob/main/CHANGELOG.md).
233
- - **Issues and PRs welcome.** File at [github.com/qmediat/gemini-code-context-mcp/issues](https://github.com/qmediat/gemini-code-context-mcp/issues) — we aim to answer within 48 hours. For commercial inquiries (custom integrations, support contracts, on-prem deployments): [contact@qmediat.io](mailto:contact@qmediat.io).
234
- - **If this saves you time, please [⭐ star the repo](https://github.com/qmediat/gemini-code-context-mcp).** It is the simplest signal you can send that the work is worth continuing, and it directly helps us justify continued investment.
235
-
236
- ## Contributing
237
-
238
- See [CONTRIBUTING.md](https://github.com/qmediat/gemini-code-context-mcp/blob/main/CONTRIBUTING.md). Short version: TypeScript strict, `npm run lint && npm run typecheck && npm test`, add a CHANGELOG entry, open a PR.
239
-
240
-
241
- ## Trademarks and affiliation
242
-
243
- Gemini is a trademark of Google. This is an independent, community-maintained integration published by Quantum Media Technologies sp. z o.o.; it is not affiliated with, sponsored by or endorsed by Google. Use of the Gemini API or CLI through this server is subject to Google's own terms and to your own API key or account.
244
-
245
- ## License
246
-
247
- MIT © [Quantum Media Technologies sp. z o.o.](https://www.qmediat.io) — see [LICENSE](https://github.com/qmediat/gemini-code-context-mcp/blob/main/LICENSE).
248
-
249
- Part of qmediat's [open-source portfolio](https://www.qmediat.io/open-source?utm_source=oss-readme&utm_medium=gemini-code-context-mcp&utm_campaign=open-source).
250
-
251
- ---
252
-
253
- Made by [Quantum Media Technologies](https://www.qmediat.io/open-source?utm_source=oss-readme&utm_medium=gemini-code-context-mcp&utm_campaign=open-source) · [more open source from qmediat](https://github.com/qmediat)
48
+ | Read | File |
49
+ |---|---|
50
+ | [First 3 minutes, Claude Desktop, Cursor](https://github.com/qmediat/gemini-code-context-mcp/blob/main/docs/getting-started.md) | docs/getting-started.md |
51
+ | [Every tool, `ask` or `ask_agentic`](https://github.com/qmediat/gemini-code-context-mcp/blob/main/docs/tools.md) | docs/tools.md |
52
+ | [Settings and parameters](https://github.com/qmediat/gemini-code-context-mcp/blob/main/docs/configuration.md) | docs/configuration.md |
53
+ | [Models](https://github.com/qmediat/gemini-code-context-mcp/blob/main/docs/models.md) | docs/models.md |
54
+ | [How caching works](https://github.com/qmediat/gemini-code-context-mcp/blob/main/docs/how-caching-works.md) | docs/how-caching-works.md |
55
+ | [Cost and the daily budget](https://github.com/qmediat/gemini-code-context-mcp/blob/main/docs/cost-model.md) | docs/cost-model.md |
56
+ | [Security](https://github.com/qmediat/gemini-code-context-mcp/blob/main/docs/security.md) | docs/security.md |
57
+ | [Why this server](https://github.com/qmediat/gemini-code-context-mcp/blob/main/docs/why.md) | docs/why.md |
58
+ | [Coming from gemini-mcp-tool](https://github.com/qmediat/gemini-code-context-mcp/blob/main/docs/migration-from-jamubc.md) | docs/migration-from-jamubc.md |
59
+ | [Maintenance and support](https://github.com/qmediat/gemini-code-context-mcp/blob/main/docs/maintenance.md) | docs/maintenance.md |
60
+ | [For AI agents](https://github.com/qmediat/gemini-code-context-mcp/blob/main/AGENTS.md) | AGENTS.md |
61
+
62
+ Node.js 22 or newer · [MIT](https://github.com/qmediat/gemini-code-context-mcp/blob/main/LICENSE) · [Quantum Media Technologies](https://www.qmediat.io/open-source?utm_source=oss-readme&utm_medium=gemini-code-context-mcp&utm_campaign=open-source) · [Trademarks](https://github.com/qmediat/gemini-code-context-mcp/blob/main/docs/TRADEMARKS.md)
@@ -101,7 +101,7 @@ export function resolveAuth() {
101
101
  ' 2. `gcloud auth application-default login` + GEMINI_USE_VERTEX=true',
102
102
  ' 3. Set GEMINI_API_KEY env var (quick test only)',
103
103
  '',
104
- 'See: https://github.com/qmediat/gemini-code-context-mcp#setup',
104
+ 'See: https://github.com/qmediat/gemini-code-context-mcp/blob/main/docs/getting-started.md',
105
105
  ].join('\n'));
106
106
  }
107
107
  //# sourceMappingURL=profile-loader.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"profile-loader.js","sourceRoot":"","sources":["../../src/auth/profile-loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,OAAO,EAAoB,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACvE,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAa/C,SAAS,kBAAkB;IACzB,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,0BAA0B,CAAC;IACpD,OAAO,IAAI,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;AACpD,CAAC;AAED,SAAS,SAAS;IAChB,IAAI,OAAO,CAAC,GAAG,CAAC,iBAAiB,KAAK,MAAM;QAAE,OAAO,IAAI,CAAC;IAC1D,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC;IACjD,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,qBAAqB,IAAI,aAAa,CAAC;IACpE,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,CAAC,IAAI,CACT,uFAAuF,CACxF,CAAC;QACF,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO;QACL,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE;QAC9C,MAAM,EAAE,YAAY;QACpB,cAAc,EAAE,YAAY;KAC7B,CAAC;AACJ,CAAC;AAED,SAAS,kBAAkB;IACzB,MAAM,IAAI,GAAG,kBAAkB,EAAE,CAAC;IAClC,IAAI,WAAwB,CAAC;IAC7B,IAAI,CAAC;QACH,WAAW,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;IAClC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,WAAW,CAAC,aAAa,EAAE,CAAC;QAC9B,OAAO;YACL,OAAO,EAAE;gBACP,IAAI,EAAE,QAAQ;gBACd,OAAO,EAAE,WAAW,CAAC,aAAa;gBAClC,QAAQ,EAAE,WAAW,CAAC,cAAc,IAAI,aAAa;aACtD;YACD,MAAM,EAAE,kBAAkB;YAC1B,GAAG,CAAC,WAAW,CAAC,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,WAAW,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC7F,GAAG,CAAC,WAAW,CAAC,cAAc,KAAK,SAAS;gBAC1C,CAAC,CAAC,EAAE,cAAc,EAAE,WAAW,CAAC,cAAc,EAAE;gBAChD,CAAC,CAAC,EAAE,CAAC;YACP,cAAc,EAAE,YAAY;SAC7B,CAAC;IACJ,CAAC;IAED,IAAI,CAAC,WAAW,CAAC,YAAY;QAAE,OAAO,IAAI,CAAC;IAE3C,OAAO;QACL,OAAO,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,WAAW,CAAC,YAAY,EAAE;QAC9D,MAAM,EAAE,kBAAkB;QAC1B,GAAG,CAAC,WAAW,CAAC,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,WAAW,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7F,GAAG,CAAC,WAAW,CAAC,cAAc,KAAK,SAAS;YAC1C,CAAC,CAAC,EAAE,cAAc,EAAE,WAAW,CAAC,cAAc,EAAE;YAChD,CAAC,CAAC,EAAE,CAAC;QACP,cAAc,EAAE,WAAW,CAAC,WAAW,CAAC,YAAY,CAAC;KACtD,CAAC;AACJ,CAAC;AAED,SAAS,SAAS;IAChB,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC;IACvC,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAC1C,OAAO;QACL,OAAO,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE;QACzC,MAAM,EAAE,SAAS;QACjB,cAAc,EAAE,WAAW,CAAC,GAAG,CAAC;KACjC,CAAC;AACJ,CAAC;AAED,sFAAsF;AACtF,MAAM,UAAU,WAAW;IACzB,MAAM,MAAM,GAAG,SAAS,EAAE,CAAC;IAC3B,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC;IAE1B,MAAM,IAAI,GAAG,kBAAkB,EAAE,CAAC;IAClC,IAAI,IAAI;QAAE,OAAO,IAAI,CAAC;IAEtB,MAAM,GAAG,GAAG,SAAS,EAAE,CAAC;IACxB,IAAI,GAAG,EAAE,CAAC;QACR,MAAM,CAAC,IAAI,CACT,4DAA4D,GAAG,CAAC,cAAc,wJAAwJ,CACvO,CAAC;QACF,OAAO,GAAG,CAAC;IACb,CAAC;IAED,MAAM,IAAI,KAAK,CACb;QACE,8BAA8B;QAC9B,EAAE;QACF,gBAAgB;QAChB,iFAAiF;QACjF,uEAAuE;QACvE,mDAAmD;QACnD,EAAE;QACF,+DAA+D;KAChE,CAAC,IAAI,CAAC,IAAI,CAAC,CACb,CAAC;AACJ,CAAC"}
1
+ {"version":3,"file":"profile-loader.js","sourceRoot":"","sources":["../../src/auth/profile-loader.ts"],"names":[],"mappings":"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"}
@@ -14,10 +14,39 @@ export declare class TtlWatcher {
14
14
  private timer;
15
15
  /** Re-entrancy guard: a slow `caches.update` round-trip must not overlap the next tick. */
16
16
  private tickInProgress;
17
+ /** The refresh running for each cache name: the tick and every keep-alive of that cache join it. */
18
+ private readonly refreshing;
17
19
  constructor(client: GoogleGenAI, manifest: ManifestDb);
18
20
  start(): void;
19
21
  stop(): void;
20
22
  markHot(workspaceRoot: string, cacheId: string, ttlSeconds: number): void;
23
+ /**
24
+ * A request is about to be sent on the cache: mark it hot and, when it expires within the refresh window
25
+ * (15 minutes), extend it now instead of at the next tick — so a decode of many requests, each opened through here,
26
+ * never sends one on a cache that expires before the request ends (a request of a decode lasts minutes). The
27
+ * keep-alive is best-effort: a failed refresh, or a manifest that cannot be read or written, is logged and leaves
28
+ * the request to meet the cache as it is.
29
+ *
30
+ * `signal` is the calling request's: an aborted signal starts no refresh, and the wait ends with its abort reason the
31
+ * moment it fires — the only rejection of this method, so a slow or hanging refresh never holds a call past its
32
+ * timeout. The refresh itself carries no caller's signal: it is shared by every keep-alive of the cache and by the
33
+ * tick, so it runs to its end for the others when the call that started it leaves.
34
+ */
35
+ keepAlive(workspaceRoot: string, cacheId: string, ttlSeconds: number, signal?: AbortSignal): Promise<void>;
36
+ private hotEntry;
21
37
  private tick;
38
+ /**
39
+ * The one refresh of the entry's cache: the running one when there is one, else a new one. It never rejects — a
40
+ * failure of the refresh or of the manifest is logged here, for the tick and the keep-alive alike.
41
+ */
42
+ private refresh;
43
+ /** Extends the entry's cache when it expires within the refresh window; drops an entry whose cache is gone. */
44
+ private refreshIfDue;
45
+ /**
46
+ * The expiry the API answered goes to the manifest row as it is NOW — read again after the round-trip, so a row
47
+ * rewritten meanwhile keeps its other fields, and a row that moved to another cache is left alone.
48
+ */
49
+ private storeExpiry;
50
+ private updateFailed;
22
51
  }
23
52
  //# sourceMappingURL=ttl-watcher.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"ttl-watcher.d.ts","sourceRoot":"","sources":["../../src/cache/ttl-watcher.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAoBpD,qBAAa,UAAU;IAOnB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAP3B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAA+B;IACnD,OAAO,CAAC,KAAK,CAA+B;IAC5C,2FAA2F;IAC3F,OAAO,CAAC,cAAc,CAAS;IAE/B,YACmB,MAAM,EAAE,WAAW,EACnB,QAAQ,EAAE,UAAU,EACnC;IAEJ,KAAK,IAAI,IAAI,CAOZ;IAED,IAAI,IAAI,IAAI,CAMX;IAED,OAAO,CAAC,aAAa,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAOxE;YAEa,IAAI;CAwDnB"}
1
+ {"version":3,"file":"ttl-watcher.d.ts","sourceRoot":"","sources":["../../src/cache/ttl-watcher.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAiB,WAAW,EAAE,MAAM,eAAe,CAAC;AAEhE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAoBpD,qBAAa,UAAU;IASnB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAT3B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAA+B;IACnD,OAAO,CAAC,KAAK,CAA+B;IAC5C,2FAA2F;IAC3F,OAAO,CAAC,cAAc,CAAS;IAC/B,oGAAoG;IACpG,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAoC;IAE/D,YACmB,MAAM,EAAE,WAAW,EACnB,QAAQ,EAAE,UAAU,EACnC;IAEJ,KAAK,IAAI,IAAI,CAOZ;IAED,IAAI,IAAI,IAAI,CAMX;IAED,OAAO,CAAC,aAAa,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAExE;IAED;;;;;;;;;;;OAWG;IACG,SAAS,CACb,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,IAAI,CAAC,CAIf;IAED,OAAO,CAAC,QAAQ;YAMF,IAAI;IAuBlB;;;OAGG;IACH,OAAO,CAAC,OAAO;IAYf,+GAA+G;YACjG,YAAY;IAuB1B;;;OAGG;IACH,OAAO,CAAC,WAAW;IAMnB,OAAO,CAAC,YAAY;CAqBrB"}