perf(prefix-cache): pin session-start workspace snapshot across compaction rebuilds

- pin session-start workspace snapshot (_frozen_workspace_snapshot) on first build so dynamic git probes don't churn Tier 2 during compaction rebuilds in active coding sessions
- replay pinned snapshot across rebuilds when cwd matches; re-probe only on cwd switch
- honor coding_context invariant that workspace is a session-start snapshot, preventing prefix-cache divergence at offset ~4,662
- add invariant tests covering workspace snapshot pinning across git mutations and cwd transitions
- addresses upstream prompt divergence identified in #103326
This commit is contained in:
joaomarcos
2026-09-04 23:28:45 -03:00
committed by kshitij
parent 5e645791ac
commit 0ed7acb051
4 changed files with 175 additions and 11 deletions
+4
View File
@@ -564,6 +564,10 @@ _SESSION_STATE: Dict[str, Any] = {
# prefix, kept separately only to place an early cache marker.
"_cached_system_prompt": None,
"_cached_system_prompt_static": None,
# ``(cwd, workspace_block)`` pinned on the first build: the git/workspace snapshot is
# probed once per session and replayed on every rebuild, so a moving repo can't push the
# prefix-cache divergence point ahead of the volatile band at a compaction boundary.
"_frozen_workspace_snapshot": None,
# Whether close() also closes _session_db. False: a caller-supplied handle is usually the
# SHARED launch handle; callers handing over a DEDICATED handle set True.
"_owns_session_db": False,
+11 -7
View File
@@ -5,7 +5,8 @@ frozen :class:`RuntimeMode` built from a :class:`ContextProfile` (pure data). Th
system prompt reads ``system_prompt_parts()``; the toolset collapses ONLY under opt-in
``focus`` (never strips a user-enabled toolset). ``agent.coding_context``: ``auto``
(default, prompt-only) / ``focus`` / ``on`` / ``off``. Resolved once, immutable; the
workspace snapshot is never re-probed per turn (cache safety).
workspace snapshot is probed once per session and replayed through
``system_prompt_parts(workspace_block=...)`` on every later build (cache safety).
"""
from __future__ import annotations
@@ -322,13 +323,15 @@ class RuntimeMode:
return None
return [self.profile.toolset, *_enabled_mcp_servers(config)]
def system_prompt_parts(self, valid_tool_names=None) -> tuple[list[str], list[str], list[str]]:
def system_prompt_parts(self, valid_tool_names=None, workspace_block: Optional[str] = None) -> tuple[list[str], list[str], list[str]]:
"""Return (prefix, workspace, trailing) posture blocks in the historical flat order —
brief, snapshot, operator instructions — so prompt assembly can put a cache boundary
before the snapshot without changing persisted bytes. The brief carries the model-family
edit-format nudge (one cached string); ``valid_tool_names`` drops the ``todo_list``
sentence when that tool isn't loaded; operator instructions ride their own block so
the brief stays byte-stable."""
the brief stays byte-stable. ``workspace_block`` replays a snapshot the caller already
pinned at session start (``""`` = no workspace) instead of re-running the git probe;
``None`` probes."""
if not self.is_coding:
return [], [], []
prefix: list[str] = []
@@ -340,7 +343,7 @@ class RuntimeMode:
if family is not None:
brief = f"{brief}\n{_EDIT_FORMAT_GUIDANCE[family][1]}"
prefix.append(brief)
workspace = build_coding_workspace_block(self.cwd)
workspace = build_coding_workspace_block(self.cwd) if workspace_block is None else workspace_block
trailing = [f"Operator instructions (from config):\n{self.instructions}"] if self.instructions else []
return prefix, [workspace] if workspace else [], trailing
@@ -395,11 +398,12 @@ def coding_selection(*, platform: Optional[str] = None, cwd: Optional[str | Path
def coding_system_prompt_parts(
*, platform: Optional[str] = None, cwd: Optional[str | Path] = None, config: Optional[dict[str, Any]] = None,
model: Optional[str] = None, valid_tool_names=None,
model: Optional[str] = None, valid_tool_names=None, workspace_block: Optional[str] = None,
) -> tuple[list[str], list[str], list[str]]:
"""Return coding prefix, workspace snapshot, and trailing guidance."""
"""Return coding prefix, workspace snapshot, and trailing guidance. ``workspace_block``
replays the caller's pinned session-start snapshot instead of probing git again."""
mode = resolve_runtime_mode(platform=platform, cwd=cwd, config=config, model=model)
return mode.system_prompt_parts(valid_tool_names=valid_tool_names)
return mode.system_prompt_parts(valid_tool_names=valid_tool_names, workspace_block=workspace_block)
def coding_compact_skill_categories(*, platform: Optional[str] = None, cwd: Optional[str | Path] = None, config: Optional[dict[str, Any]] = None) -> frozenset[str]:
+26 -4
View File
@@ -538,12 +538,34 @@ def _alibaba_identity_part(agent: Any) -> List[str]:
def _coding_parts(agent: Any) -> Tuple[List[str], List[str], List[str]]:
"""``(prefix, workspace, trailing)`` coding-posture blocks; all empty
without tools or when probing fails (it must never block prompt build)."""
without tools or when probing fails (it must never block prompt build).
The workspace block is a LIVE ``git status``/``git log`` probe and it leads the
context tier — ahead of the entire volatile band. Since #98426 the builder runs
again at every compaction boundary, so re-probing here re-emits different bytes on
any session whose repo moved (a commit, one edited or untracked file), pushing the
prefix-cache divergence point in front of skills, memory and the timestamp line and
making #98426's byte-equality keep-prompt fast path unreachable in a coding session.
It also contradicts the block's own "snapshot at session start" wording and the
freeze ``coding_context`` documents. So the first build pins the bytes on the agent,
keyed by the resolved cwd (one gateway serves many cwds, and the per-turn terminal
scope can move it), and later rebuilds replay them instead of shelling out again.
A resumed process has no pin and legitimately re-snapshots at its own session start.
"""
try:
from agent.coding_context import coding_system_prompt_parts
if agent.valid_tool_names:
return coding_system_prompt_parts(platform=agent.platform, cwd=resolve_context_cwd(),
model=agent.model, valid_tool_names=agent.valid_tool_names)
if not agent.valid_tool_names:
return [], [], []
cwd = resolve_context_cwd()
cwd_key = str(cwd) if cwd is not None else ""
pinned = getattr(agent, "_frozen_workspace_snapshot", None)
# "" is a real pinned value (no workspace here) — only a cwd mismatch re-probes.
replay = pinned[1] if isinstance(pinned, tuple) and len(pinned) == 2 and pinned[0] == cwd_key else None
parts = coding_system_prompt_parts(platform=agent.platform, cwd=cwd, model=agent.model,
valid_tool_names=agent.valid_tool_names, workspace_block=replay)
if replay is None:
agent._frozen_workspace_snapshot = (cwd_key, parts[1][0] if parts[1] else "")
return parts
except Exception:
pass
return [], [], []
+134
View File
@@ -23,6 +23,12 @@ def _agent(**over):
_cached_system_prompt="OLD PROMPT",
_cached_system_prompt_static="OLD",
_memory_store=None,
_memory_manager=None,
provider="",
model="",
platform="",
_memory_enabled=False,
_user_profile_enabled=False,
)
base.update(over)
return SimpleNamespace(**base)
@@ -89,5 +95,133 @@ class TestCommitAlwaysRebuilds(unittest.TestCase):
self.assertIn("Compaction rebuilt a drifted system prompt", src)
class TestWorkspaceSnapshotPinnedAcrossCompaction(unittest.TestCase):
"""Compaction rebuilds must not invalidate the prefix at the workspace snapshot (#103326)."""
def test_workspace_snapshot_replayed_across_rebuilds_when_repo_mutates(self):
import tempfile, shutil, subprocess
from pathlib import Path
from agent.system_prompt import build_system_prompt, invalidate_system_prompt
tmp = Path(tempfile.mkdtemp(prefix="test-pinned-ws-"))
try:
repo = tmp / "proj"
repo.mkdir()
for cmd in (
["git", "init", "-q", "-b", "main"],
["git", "config", "user.email", "t@t"],
["git", "config", "user.name", "t"],
["git", "config", "core.autocrlf", "false"],
):
subprocess.run(cmd, cwd=repo, check=True)
(repo / "main.py").write_text("print(1)\n")
subprocess.run(["git", "add", "-A"], cwd=repo, check=True)
subprocess.run(["git", "commit", "-qm", "init commit"], cwd=repo, check=True)
agent = _agent(
load_soul_identity=False,
skip_context_files=True,
valid_tool_names={"terminal", "file_write"},
platform="cli",
model="gpt-4o",
_memory_enabled=False,
_user_profile_enabled=False,
_task_completion_guidance=False,
_parallel_tool_call_guidance=False,
_tool_use_enforcement=False,
_execution_guidance=False,
_environment_probe=False,
_bot_mode_protocol=False,
_kanban_worker_guidance="",
pass_session_id=False,
session_id="s1",
_emit_status=lambda *a, **k: None,
)
with patch("agent.prompt_builder.load_soul_md", return_value=""), \
patch("agent.prompt_builder.build_environment_hints", return_value="ENV HINTS"), \
patch("agent.system_prompt.resolve_context_cwd", return_value=repo):
# First build: pins the snapshot
p1 = build_system_prompt(agent)
self.assertIn("Workspace (snapshot at session start", p1)
self.assertIsNotNone(agent._frozen_workspace_snapshot)
self.assertEqual(agent._frozen_workspace_snapshot[0], str(repo))
# Now repo mutates (agent touched and committed new files)
(repo / "new_file.py").write_text("print(2)\n")
subprocess.run(["git", "add", "-A"], cwd=repo, check=True)
subprocess.run(["git", "commit", "-qm", "second commit"], cwd=repo, check=True)
(repo / "untracked.txt").write_text("wip\n")
# Invalidate prompt (as happens during context compression)
invalidate_system_prompt(agent)
# Second build: must replay pinned snapshot without re-probing git
p2 = build_system_prompt(agent)
self.assertEqual(p1, p2, "Prompt must remain byte-identical despite repo mutations")
self.assertNotIn("second commit", p2, "Rebuilt prompt must not leak mutated git log")
finally:
shutil.rmtree(tmp, ignore_errors=True)
def test_workspace_snapshot_reprobes_when_cwd_changes(self):
import tempfile, shutil, subprocess
from pathlib import Path
from agent.system_prompt import build_system_prompt
tmp = Path(tempfile.mkdtemp(prefix="test-pinned-cwd-"))
try:
repo1 = tmp / "r1"; repo1.mkdir()
repo2 = tmp / "r2"; repo2.mkdir()
for r in (repo1, repo2):
for cmd in (
["git", "init", "-q", "-b", "main"],
["git", "config", "user.email", "t@t"],
["git", "config", "user.name", "t"],
["git", "config", "core.autocrlf", "false"],
):
subprocess.run(cmd, cwd=r, check=True)
(r / "main.py").write_text("print(1)\n")
subprocess.run(["git", "add", "-A"], cwd=r, check=True)
subprocess.run(["git", "commit", "-qm", f"init {r.name}"], cwd=r, check=True)
agent = _agent(
load_soul_identity=False,
skip_context_files=True,
valid_tool_names={"terminal"},
platform="cli",
model="gpt-4o",
_memory_enabled=False,
_user_profile_enabled=False,
_task_completion_guidance=False,
_parallel_tool_call_guidance=False,
_tool_use_enforcement=False,
_execution_guidance=False,
_environment_probe=False,
_bot_mode_protocol=False,
_kanban_worker_guidance="",
pass_session_id=False,
session_id="s1",
_emit_status=lambda *a, **k: None,
)
with patch("agent.prompt_builder.load_soul_md", return_value=""), \
patch("agent.prompt_builder.build_environment_hints", return_value="ENV HINTS"), \
patch("agent.system_prompt.resolve_context_cwd", return_value=repo1):
p1 = build_system_prompt(agent)
self.assertIn(f"init {repo1.name}", p1)
with patch("agent.prompt_builder.load_soul_md", return_value=""), \
patch("agent.prompt_builder.build_environment_hints", return_value="ENV HINTS"), \
patch("agent.system_prompt.resolve_context_cwd", return_value=repo2):
p2 = build_system_prompt(agent)
self.assertIn(f"init {repo2.name}", p2)
self.assertEqual(agent._frozen_workspace_snapshot[0], str(repo2))
finally:
shutil.rmtree(tmp, ignore_errors=True)
if __name__ == "__main__":
unittest.main()