Skip to content

fix(core): scope prompt cache entries to version and label - #1521

Open
shhhhhhjokerist wants to merge 1 commit into
VoltAgent:mainfrom
shhhhhhjokerist:fix/core-prompt-cache-label
Open

shhhhhhjokerist wants to merge 1 commit into
VoltAgent:mainfrom
shhhhhhjokerist:fix/core-prompt-cache-label

Conversation

@shhhhhhjokerist

@shhhhhhjokerist shhhhhhjokerist commented Nov 8, 2026 •

Copy link
Copy Markdown

What is the current behavior?

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):

  1. getPrompt({ promptName: "greeting", label: "production" }) -> returns "Production prompt", caches it.
  2. 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.

Tests

packages/core/src/voltops/prompt-manager.spec.ts, 39/39 passing.

  • 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.

Changeset

.changeset/quiet-labels-cache.md -> @voltagent/core: patch.

Checklist

  • Read the contributing guide
  • Changeset added (@voltagent/core, patch)
  • Tests covering the change
  • Core package test suite run locally (39/39)
  • 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 #1520


Summary by cubic

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.

View guided diff

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.

@changeset-bot

changeset-bot Bot commented Nov 8, 2026 •

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: f522dad

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package
Name Type
@voltagent/core Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All reported issues were addressed across 3 files

Reply to a comment to ask cubic a question or push back. It learns from your replies.

View guided diff | Re-trigger cubic

@coderabbitai

coderabbitai Bot commented Nov 8, 2026 •

Copy link
Copy Markdown
Contributor

Explain Change →

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.

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Bug fix · Severity of issue fixed: Medium

Suggested reviewers: omeraplak

Merge Risk: Minimal · up to f522d

The selector-specific cache changes appear ready to merge after normal checks.

Pre-merge checks: Passed 5

Check name Status Explanation
Title check Passed 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 Passed 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 Passed 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 Passed 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 Passed 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.

Share

Recent review info

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • 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.

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All reported issues were addressed across 2 files (changes from recent commits).

Reply with feedback, questions, or to request a fix.

View guided diff | Re-trigger cubic

@shhhhhhjokerist
shhhhhhjokerist force-pushed the fix/core-prompt-cache-label branch 3 times, most recently from 5e7836f to 64f65bc Compare November 8, 2026 16:31
`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.
@shhhhhhjokerist
shhhhhhjokerist force-pushed the fix/core-prompt-cache-label branch from 64f65bc to f522dad Compare November 8, 2026 18:52
@shhhhhhjokerist

Copy link
Copy Markdown
Author

Ready for review when you have a moment.

  • 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 branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Prompt cache key ignores label, so labelled and unlabelled lookups share an entry

1 participant