fix(agents): stabilize prompt cache fingerprints by vincentkoc · Pull Request #60731 · openclaw/openclaw

vincentkoc · 2026-04-04T07:01:17Z

Summary

Problem: cache-relevant system prompt bytes could drift for semantically identical inputs because generated prompt sections preserved CRLF, trailing horizontal whitespace, and runtime capability ordering.
Why it matters: OpenAI-family and other prompt-byte-sensitive paths can miss KV/prompt-cache reuse even when the logical prompt did not change.
What changed: added conservative normalization for structured prompt sections, canonicalized runtime capability ids, and normalized post-boundary hook/addition text.
What did NOT change (scope boundary): no broad Unicode normalization, no user-message rewriting, and no mutation of injected project-context file contents.
AI-assisted: Codex.

Change Type (select all)

Scope (select all touched areas)

Linked Issue/PR

Closes #
Related feat(agents): add prompt cache break diagnostics #60707
This PR fixes a bug or regression

Root Cause (if applicable)

Root cause: structured prompt assembly normalized too little. Generated sections such as extra system context, heartbeat text, skills catalog text, hook-provided system additions, and runtime capability lists could preserve byte-level noise that did not change semantics.
Missing detection / guardrail: there were no tests asserting byte-stable output across CRLF/LF, trailing-space noise, and equivalent capability-order permutations.
Contributing context (if known): earlier KV/cache work fixed transport/path divergence; this follow-up addresses prompt-byte drift inside the assembled system prompt itself.

Regression Test Plan (if applicable)

Coverage level that should have caught this:
- Unit test
- Seam / integration test
- End-to-end test
- Existing coverage already sufficient
Target test or file:
- src/agents/system-prompt.test.ts
- src/agents/system-prompt-cache-boundary.test.ts
- src/agents/pi-embedded-runner/run/attempt.test.ts
Scenario the test should lock in: semantically equivalent CRLF/trailing-whitespace/capability-order inputs produce identical system-prompt bytes.
Why this is the smallest reliable guardrail: the bug is in prompt-string assembly, not provider transport behavior.
Existing test that already covers this (if any): existing cache-boundary tests cover split/strip, but not byte-stability of noisy structured inputs.
If no new test is added, why not: N/A.

User-visible / Behavior Changes

None directly. This should improve cache reuse stability for equivalent prompt inputs.

Diagram (if applicable)

Before:
[generated prompt sections with CRLF / trailing spaces / reordered caps]
-> [different system prompt bytes]
-> [cache miss risk]

After:
[equivalent structured prompt inputs]
-> [canonicalized system prompt bytes]
-> [stable cache fingerprint]

Security Impact (required)

New permissions/capabilities? (No)
Secrets/tokens handling changed? (No)
New/changed network calls? (No)
Command/tool execution surface changed? (No)
Data access scope changed? (No)
If any Yes, explain risk + mitigation:

Repro + Verification

Environment

OS: macOS
Runtime/container: local Node 22 / pnpm
Model/provider: N/A
Integration/channel (if any): N/A
Relevant config (redacted): N/A

Steps

Build equivalent system prompts with CRLF/trailing-space noise in structured sections.
Compare the resulting prompt bytes before and after normalization.
Check hook-composed and post-boundary additions for the same behavior.

Expected

Equivalent structured inputs should yield identical cache-relevant prompt bytes.

Actual

Before this patch, equivalent inputs could differ by CRLF, trailing spaces, or runtime capability ordering.

Evidence

Attach at least one:

Failing test/log before + passing after
Trace/log snippets
Screenshot/recording
Perf numbers (if relevant)

Human Verification (required)

Verified scenarios:
- direct TS sanity probe for prompt-byte equality across noisy vs clean structured inputs
- direct TS sanity probe for normalized boundary additions and hook-composed system context
- git diff --check
Edge cases checked:
- runtime capability dedupe + sort
- CRLF normalization without broad prompt-body rewriting
- boundary-preserving insertion of normalized dynamic additions
What you did not verify:
- full Vitest targeted runner stayed non-reporting in this environment
- pnpm build is currently blocked on unrelated existing latest-main type failures in src/agents/tools/sessions-spawn-tool.ts and src/plugin-sdk/core.ts

Review Conversations

I replied to or resolved every bot review conversation I addressed in this PR.
I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

Backward compatible? (Yes)
Config/env changes? (No)
Migration needed? (No)
If yes, exact upgrade steps:

Risks and Mitigations

Risk: canonicalizing structured prompt sections could change intentionally preserved trailing whitespace in those sections.
- Mitigation: scope is limited to generated/structured prompt sections and capability ids; injected project-context file contents remain untouched.

greptile-apps · 2026-04-04T07:11:28Z

Greptile Summary

This PR adds conservative normalization of structured prompt sections to stabilize prompt-cache fingerprints for OpenAI-family and other prompt-byte-sensitive transports. It introduces a new src/agents/prompt-cache-stability.ts utility with normalizeStructuredPromptSection (CRLF → LF, trailing horizontal whitespace stripping, trim) and normalizePromptCapabilityIds (deduplicate, lowercase, sort). These normalizers are then applied to extraSystemPrompt, skillsPrompt, heartbeatPrompt, workspaceNotes, modelAliasLines, hook-injected system context, and the post-boundary addition in prependSystemPromptAdditionAfterCacheBoundary. Runtime capability IDs in the prompt line are also canonicalized, while injected project-context file contents are deliberately left untouched.

Key observations:

The normalization scope is tight and well-justified: only structured/generated sections, not user-provided file content.
The new attempt.thread-helpers.ts cleanly extracts composeSystemPromptWithHookContext and applies the normalizer to hook-provided context without touching the base system prompt (which is already normalized at construction time).
Test coverage is thorough: byte-stable equivalence tests across CRLF/trailing-space/capability-order permutations are added in all three relevant test files.
Array.prototype.toSorted is used in normalizePromptCapabilityIds; this is available in Node.js 20+ and the repo mandates Node 22+, so this is safe.
runtimeCapabilitiesLower (used for the inlineButtonsEnabled runtime check) still uses its own inline String(cap).trim().toLowerCase() path rather than normalizePromptCapabilityIds — this is an intentional split: the inline path is for in-memory runtime behavior detection, while normalizePromptCapabilityIds is only for prompt string assembly.

Confidence Score: 5/5

This PR is safe to merge; all changes are additive normalizations with no behavioral impact on the prompt's logical content and are well-covered by new tests.

No P0 or P1 issues found. The change is narrowly scoped to structured prompt assembly, leaves user-injected file content untouched as documented, and is backed by byte-stability regression tests. Previously flagged issues in earlier review threads are pre-existing style observations, not blocking bugs.

No files require special attention.

_{Reviews (2): Last reviewed commit: "refactor(agents): simplify prompt capabi..." | Re-trigger Greptile}

vincentkoc · 2026-04-04T07:17:55Z

@greptileai review

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 5f61ff6390

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-04-04T07:21:33Z

+  const seen = new Set<string>();
+  const normalized: string[] = [];
+  for (const capability of capabilities) {
+    const value = normalizeStructuredPromptSection(String(capability ?? "")).toLowerCase();


Preserve capability ID casing in prompt normalization

Lowercasing each capability in normalizePromptCapabilityIds rewrites canonical IDs before they are rendered in the runtime line, so values like inlineButtons become inlinebuttons. This creates inconsistent prompt guidance (the same system prompt still references capabilities.inlineButtons) and can cause the agent to surface invalid or non-canonical capability names for camelCase/plugin-defined capabilities. Please dedupe/sort case-insensitively but keep the original canonical token when emitting capability IDs.

Useful? React with 👍 / 👎.

* fix(agents): stabilize prompt cache fingerprints * chore(changelog): note prompt cache fingerprint stability * refactor(agents): simplify capability normalization * refactor(agents): simplify prompt capability normalization helper

fix(agents): stabilize prompt cache fingerprints

2655a19

vincentkoc self-assigned this Apr 4, 2026

openclaw-barnacle Bot added agents Agent runtime and tooling size: S maintainer Maintainer-authored PR labels Apr 4, 2026

chore(changelog): note prompt cache fingerprint stability

5f61ff6

vincentkoc marked this pull request as ready for review April 4, 2026 07:07

greptile-apps Bot reviewed Apr 4, 2026

View reviewed changes

Comment thread src/agents/system-prompt.ts Outdated

Comment thread src/agents/system-prompt.ts

Comment thread src/agents/prompt-cache-stability.ts Outdated

vincentkoc added 3 commits April 4, 2026 16:12

Merge branch 'main' into codex/prompt-fingerprint-stability

94abcd1

refactor(agents): simplify capability normalization

7a45fa9

refactor(agents): simplify prompt capability normalization helper

94a9f4d

vincentkoc merged commit d75a893 into main Apr 4, 2026
20 of 37 checks passed

vincentkoc deleted the codex/prompt-fingerprint-stability branch April 4, 2026 07:20

chatgpt-codex-connector Bot reviewed Apr 4, 2026

View reviewed changes

affsantos mentioned this pull request Apr 4, 2026

fix(cache): enable prompt cache retention for Anthropic Vertex AI #60888

Merged

27 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

fix(agents): stabilize prompt cache fingerprints#60731

fix(agents): stabilize prompt cache fingerprints#60731
vincentkoc merged 5 commits into
mainfrom
codex/prompt-fingerprint-stability

vincentkoc commented Apr 4, 2026

Uh oh!

greptile-apps Bot commented Apr 4, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

vincentkoc commented Apr 4, 2026

Uh oh!

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

chatgpt-codex-connector Bot Apr 4, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Uh oh!

Conversation

vincentkoc commented Apr 4, 2026

Summary

Change Type (select all)

Scope (select all touched areas)

Linked Issue/PR

Root Cause (if applicable)

Regression Test Plan (if applicable)

User-visible / Behavior Changes

Diagram (if applicable)

Security Impact (required)

Repro + Verification

Environment

Steps

Expected

Actual

Evidence

Human Verification (required)

Review Conversations

Compatibility / Migration

Risks and Mitigations

Uh oh!

greptile-apps Bot commented Apr 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Greptile Summary

Confidence Score: 5/5

Uh oh!

Uh oh!

Uh oh!

Uh oh!

vincentkoc commented Apr 4, 2026

Uh oh!

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot Apr 4, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

greptile-apps Bot commented Apr 4, 2026 •

edited

Loading