You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
fix(core): scope prompt cache entries to version and label - #1521
VoltOpsPromptManagerImpl.getCacheKey() builds the key from the prompt name and version only,
defaulting to "latest" when version is absent. PromptReference.label is ignored.
label is a supported selector (@voltagent/core types and VoltOpsPromptApiClient.buildPromptUrl
both use it), so { promptName: "greeting", label: "production" } and { promptName: "greeting" } map to the same key. Whichever call stores first wins the cache entry
(default TTL: 5 minutes); the other selector is then served that prompt's content and metadata.
Two different labels (production / staging) likewise share one entry.
Reproduction (mock API client, same pattern as the existing spec):
getPrompt({ promptName: "greeting" }) -> expected "Latest prompt", actually gets the cached
"Production prompt" with no second API call.
What is the new behavior?
Cache keys now include the selector that was requested:
name:version:1 for version: 1
name:label:production for label: "production"
name:latest for no selector
Version still takes precedence over label, matching PromptReference's documented contract. Repeating
the same selector still hits the cache, so latency is unchanged for the common case. The parts are
escaped before joining, so a prompt name containing : cannot forge a label or version namespace.
Version selectors now use name:version:v where they previously produced name:v. That changes getCacheStats().entries for version lookups; the cache is an in-memory Map, so there is no persisted
key to migrate.
Regression test for the reported bug: should not reuse a cached prompt for a different label.
It fails on main with expected 'Production prompt' to be 'Latest prompt' and passes with the fix.
It also asserts per-selector cache hits, so caching was not disabled for labelled prompts.
Invariant test for the escaping: should not collide for prompt names that contain the selector delimiter. Its behavioural assertions already pass on main; the entries assertion pins the new
key format and fails there, because the base revision builds x:label:y:latest for the first lookup
and x:latest for the second.
Selector precedence and edge cases: should prefer an explicit version over a label when both are supplied pins the precedence documented on PromptReference.version, and should treat an empty label as the unlabelled lookup pins the label: empty-string fallback.
pnpm --filter @voltagent/core exec vitest run src/voltops/prompt-manager.spec.ts
-> 39/39 passed
packages/core suite (run inside packages/core with its own vitest.config.mts): 1265 passed, 5 failed,
2 skipped, 1 todo — the 5 failures are the pre-existing Windows-only src/workspace/sandbox ones
(local.spec.ts, toolkit.spec.ts) and come from the environment, not from this diff. tsc --noEmit and biome are clean.
GitHub Actions matrix (Node 20/22/24) — the workflow is action_required for a first-time
contributor, so a maintainer needs to approve it
Notes for reviewers
The key shape for explicit version selectors changes from name:v to name:version:v. That is
visible in getCacheStats().entries; the cache itself is in-memory only, so nothing is persisted and
there is no migration. If you would rather keep name:v for versions and only namespace labels, say so
and I will restructure the diff.
Fixes prompt cache collisions when selecting by label. VoltOpsPromptManagerImpl.getCacheKey() now keys on the requested selector (version, label, or latest), so labelled prompts no longer reuse entries from a different selector. Key parts are escaped, so prompt names containing : cannot collide with label or version values. Version precedence over label is preserved, an empty label falls back to the unlabelled latest entry, and repeating the same selector still hits the cache. Fixes#1520.
Version lookups change key shape from name:v1 to name:version:v1, so getCacheStats().entries differs for version selectors; the cache is in-memory, so no migration is required.
Written for commit f522dad. Summary will update on new commits.
Summary by CodeRabbit
Bug Fixes
Prompt requests using different selectors—such as a specific version, a label, or the latest prompt—now keep their cached results separate. An explicit version takes precedence over a label, and an empty label is treated like no label.
Repeated requests with the same selector can still reuse the cache. Prompt names and selector values containing delimiter characters no longer cause unrelated requests to share a cache entry, keeping cached responses associated with the intended prompt and selection.
No actionable comments were generated in the recent review.
Walkthrough
The prompt cache key now distinguishes explicit versions, labels without versions, and latest lookups. Tests cover selector isolation, cache reuse, version precedence, empty labels, and key collisions.
Changes: Prompt cache selector isolation
Layer / File(s)
Summary
Selector-specific cache keys and coverage packages/core/src/voltops/prompt-manager.ts, packages/core/src/voltops/prompt-manager.spec.ts, .changeset/quiet-labels-cache.md
getCacheKey distinguishes explicit versions, labels when no version is provided, and latest lookups. It escapes backslashes and colons in prompt names and selector values. Tests cover cache reuse, version precedence, empty-label handling, and key collisions. The Changeset declares a patch release for @voltagent/core.
The selector-specific cache changes appear ready to merge after normal checks.
Pre-merge checks: 5
Check name
Status
Explanation
Title check
The title "fix(core): scope prompt cache entries to version and label" matches the main change. The raw summary and objectives show getCacheKey now keys entries by the requested selector (version, lab…
Linked Issues check
Issue #1520 is the only direct, active linked target. Its coding requirements are: (1) scope cache keys to the requested selector as name:version:, name:label:, or name:latest; (2) keep version …
Out of Scope Changes check
The whole-PR diff from merge base e9fc599 to head f522dad changes the getCacheKey method in prompt-manager.ts, the spec file prompt-manager.spec.ts, and the changeset .changeset/quiet-labels-cache.md.…
Docstring Coverage
No eligible functions found in the changed files. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentat…
Description check
The description covers the current behavior, new behavior, reproduction steps, tests run, changeset, checklist, and reviewer notes, and links the issue with "Fixes #1520". It follows the repository te…
Full details: Title check
Explanation
The title "fix(core): scope prompt cache entries to version and label" matches the main change. The raw summary and objectives show getCacheKey now keys entries by the requested selector (version, label, or latest), which the title describes. The title uses the conventional commit form and names the package. It does not cover the escaping of key parts, but that detail is not required in a title.
Full details: Linked Issues check
Explanation
Issue #1520 is the only direct, active linked target. Its coding requirements are: (1) scope cache keys to the requested selector as name:version:<v>, name:label:<l>, or name:latest; (2) keep version precedence over label; (3) keep repeated identical selectors cacheable. The whole-PR diff (merge base e9fc599 to head f522dad) changes VoltOpsPromptManagerImpl.getCacheKey in packages/core/src/voltops/prompt-manager.ts. When version is defined, the key is name:version:<v>. Otherwise, when label is truthy, the key is name:label:<l>. Otherwise the key is name:latest. This meets (1) and (2). The key is a pure function of the reference, so identical selectors produce the same key and still hit the cache, which meets (3). The escaping of backslashes and colons in the name and selector values is injective, so a prompt name that contains ':label:' cannot collide with a labelled lookup. The escaped format matches the issue's key shape for ordinary names. The escaping is a justified extension for names that contain delimiters. The PR summary reports added spec tests for the label collision, delimiter collision, version-over-label precedence, and empty-label fallback. I did not re-read the spec file at head, so the test coverage claim relies on the supplied summary. The coverage does not change the verdict because the issue sets no test requirement that the code fails to meet.
Full details: Out of Scope Changes check
Explanation
The whole-PR diff from merge base e9fc599 to head f522dad changes the getCacheKey method in prompt-manager.ts, the spec file prompt-manager.spec.ts, and the changeset .changeset/quiet-labels-cache.md. The getCacheKey change implements #1520, including the escaping that keeps scoped keys collision-free. The spec additions test the cache key behavior that #1520 requires. The changeset is patch release metadata for @voltagent/core that describes this fix. The version key shape changes from name:v to name:version:v. This change is required by #1520's expected key format, so it is in scope. The cache is in memory, so the change affects getCacheStats().entries only. I found no unrelated refactoring or behavior change. The incremental diff from the previous reviewed head could not be read, but the whole-PR diff covers the complete change set at head. The PR summary's test count (37/37) differs from the PR objectives' count (36/36). This discrepancy does not affect scope.
Full details: Docstring Coverage
Explanation
No eligible functions found in the changed files. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentation-only edits and deletions within surviving functions are included; unchanged diff context and fully deleted functions are excluded. Analyzed 0 functions across 2 files.
Full details: Description check
Explanation
The description covers the current behavior, new behavior, reproduction steps, tests run, changeset, checklist, and reviewer notes, and links the issue with "Fixes #1520". It follows the repository template's sections. Minor gaps: the template's Bugs/Features checklist items are not all ticked as the template expects, and the "Docs have been added / updated" item is not addressed. The test count is also inconsistent with the objectives text (39/39 in the description versus 37/37 in the objectives), so the author should confirm the correct count.
Finishing Touches
Generate unit tests (beta)
Create a new PR
Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts
Tip
🎯 Customize your risk assessments
Guide how CodeRabbit assesses merge risk and security architecture risk. Highlight sensitive changes and explain your security boundaries using Merge Risk Instructions and Security Risk Instructions in your review settings. Security architecture risk assessments require the Advanced plan or above.
✅ Automatic approvals, with your rules
Let CodeRabbit approve pull requests once required threads are resolved, pre-merge checks pass, and your risk limits are met. Enable Automatic approvals in review settings, with overrides for teams or file paths.
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.
File: No configuration file from this repository applied
Commit: Unavailable
Layers: defaults
Review profile: CHILL
Plan: Advanced
Run ID: 1bdf1b8e-6b86-4e90-a5d3-acd1956f0a83
Commits
Reviewing files that changed from the base of the PR and between 64f65bc and f522dad.
Files selected for processing: 2
packages/core/src/voltops/prompt-manager.spec.ts
packages/core/src/voltops/prompt-manager.ts
Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 9 remain after this review.
`VoltOpsPromptManagerImpl.getCacheKey` ignored the `label` selector, so
`getPrompt({ promptName: "x", label: "y" })` and `getPrompt({ promptName: "x" })`
shared the same cache entry: whichever lookup resolved first was served for the
other one, so a labelled lookup could return the latest prompt (and vice versa).
Fix: derive the key from the selector that is actually used.
- `label` gets its own `name:label:<label>` namespace.
- an explicit `version` now uses `name:version:<version>` (previously
`name:<version>`) so the selector kind is explicit and a label can never be
mistaken for a version or for the `latest` default.
- the namespace and selector are escaped before joining, so a prompt name that
itself contains ":" cannot forge another selector namespace.
Caveat for reviewers: version selectors therefore change key shape (from
`name:v1` to `name:version:v1`), which changes `getCacheStats().entries` for
version lookups. The cache is in-memory only (a Map), so there is no persisted
key to migrate.
Tests (39/39 in packages/core/src/voltops/prompt-manager.spec.ts):
- a labelled lookup no longer reuses the unlabelled entry; this test fails on
the base revision and is the regression test for the bug
- an explicit version wins over a label when both are supplied, matching the
precedence documented on `PromptReference.version`
- an empty label falls back to the unlabelled `latest` entry
- the selector delimiter is escaped, so `promptName: "x:label:y"` and
`{ promptName: "x", label: "y:latest" }` produce different keys. Its
behavioural asserts already pass on the base revision; the `entries`
assertion pins the new key format and fails there, because the base revision
builds "x:label:y:latest" for the first lookup and "x:latest" for the second.
Verified locally: vitest 39/39, `tsc --noEmit` clean, biome clean, changeset for
`@voltagent/core` (patch).
Known limitation, unchanged by this PR: when both selectors are supplied the
label is ignored because the version selector short-circuits. That is the
documented precedence, now recorded in a comment and pinned by a test.
packages/core/src/voltops/prompt-manager.spec.ts: 39/39, tsc --noEmit and biome check clean, changeset for @voltagent/core (patch) included.
cubic's P1 (delimiter collision) and P3 (mojibake) are addressed in f522dad; both reports now say All reported issues were addressed.
One decision worth your eye: getCacheKey also namespaces version selectors now (name:version:<v> instead of name:<v>), so getCacheStats().entries changes shape for version lookups. The cache is in-memory only, so nothing persisted to migrate. Happy to keep the old name:<v> format and namespace only labels if you prefer a smaller behavioural diff.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What is the current behavior?
VoltOpsPromptManagerImpl.getCacheKey()builds the key from the prompt name andversiononly,defaulting to
"latest"whenversionis absent.PromptReference.labelis ignored.labelis a supported selector (@voltagent/coretypes andVoltOpsPromptApiClient.buildPromptUrlboth use it), so
{ promptName: "greeting", label: "production" }and{ promptName: "greeting" }map to the same key. Whichever call stores first wins the cache entry(default TTL: 5 minutes); the other selector is then served that prompt's content and metadata.
Two different labels (
production/staging) likewise share one entry.Reproduction (mock API client, same pattern as the existing spec):
getPrompt({ promptName: "greeting", label: "production" })-> returns "Production prompt", caches it.getPrompt({ promptName: "greeting" })-> expected "Latest prompt", actually gets the cached"Production prompt" with no second API call.
What is the new behavior?
Cache keys now include the selector that was requested:
name:version:1forversion: 1name:label:productionforlabel: "production"name:latestfor no selectorVersion still takes precedence over label, matching
PromptReference's documented contract. Repeatingthe same selector still hits the cache, so latency is unchanged for the common case. The parts are
escaped before joining, so a prompt name containing
:cannot forge a label or version namespace.Version selectors now use
name:version:vwhere they previously producedname:v. That changesgetCacheStats().entriesfor version lookups; the cache is an in-memoryMap, so there is no persistedkey to migrate.
Tests
packages/core/src/voltops/prompt-manager.spec.ts, 39/39 passing.should not reuse a cached prompt for a different label.It fails on
mainwithexpected 'Production prompt' to be 'Latest prompt'and passes with the fix.It also asserts per-selector cache hits, so caching was not disabled for labelled prompts.
should not collide for prompt names that contain the selector delimiter. Its behavioural assertions already pass onmain; theentriesassertion pins the newkey format and fails there, because the base revision builds
x:label:y:latestfor the first lookupand
x:latestfor the second.should prefer an explicit version over a label when both are suppliedpins the precedence documented onPromptReference.version, andshould treat an empty label as the unlabelled lookuppins thelabel:empty-string fallback.packages/coresuite (run insidepackages/corewith its ownvitest.config.mts): 1265 passed, 5 failed,2 skipped, 1 todo — the 5 failures are the pre-existing Windows-only
src/workspace/sandboxones(
local.spec.ts,toolkit.spec.ts) and come from the environment, not from this diff.tsc --noEmitand biome are clean.Changeset
.changeset/quiet-labels-cache.md->@voltagent/core: patch.Checklist
@voltagent/core, patch)action_requiredfor a first-timecontributor, so a maintainer needs to approve it
Notes for reviewers
The key shape for explicit
versionselectors changes fromname:vtoname:version:v. That isvisible in
getCacheStats().entries; the cache itself is in-memory only, so nothing is persisted andthere is no migration. If you would rather keep
name:vfor versions and only namespace labels, say soand I will restructure the diff.
Fixes #1520
Summary by cubic
Fixes prompt cache collisions when selecting by label.
VoltOpsPromptManagerImpl.getCacheKey()now keys on the requested selector (version,label, orlatest), so labelled prompts no longer reuse entries from a different selector. Key parts are escaped, so prompt names containing:cannot collide with label or version values. Version precedence over label is preserved, an empty label falls back to the unlabelledlatestentry, and repeating the same selector still hits the cache. Fixes #1520.name:v1toname:version:v1, sogetCacheStats().entriesdiffers for version selectors; the cache is in-memory, so no migration is required.Written for commit f522dad. Summary will update on new commits.
Summary by CodeRabbit