fix(sprites): cache platform-context text across capability clones

``Capability.clone`` runs every agent turn and resets per-instance
attribute state, so the previous ``_cached_text`` PrivateAttr never
hit — every turn re-executed ``cat /.sprite/llm.txt`` to inject
the platform doc, waking the sprite even when the model never made
a tool call.

Promotes the cache to module scope keyed by ``(sprite_name, path)``.
Survives across all clones for the same sprite, so the file lands
exactly once per sprite for the life of the process. Adds
``clear_platform_context_cache`` for applications that need to force
a re-fetch (e.g. after a sprite image upgrade).

Adds an autouse fixture in the test suite that clears the cache
between tests so state doesn't leak. 2 new regression tests cover
the cross-clone caching and the explicit clear path.

Author: vaurdan

src/agents/extensions/sandbox/sprites/__init__.py

@@ -6,6 +6,7 @@
     SpritesPlatformContext,
     SpritesUrlAccess,
     UrlVisibility,
+    clear_platform_context_cache,
 )
 from .sandbox import (
     DEFAULT_SPRITES_API_URL,
@@ -30,4 +31,5 @@
     "SpritesSandboxSessionState",
     "SpritesUrlAccess",
     "UrlVisibility",
+    "clear_platform_context_cache",
 ]

src/agents/extensions/sandbox/sprites/capabilities.py

@@ -5,8 +5,6 @@
 import asyncio
 from typing import Any, Literal
 
-from pydantic import PrivateAttr
-
 from ....run_context import RunContextWrapper
 from ....sandbox.capabilities.capability import Capability
 from ....sandbox.manifest import Manifest
@@ -19,6 +17,34 @@
 """Sprites URL visibility values. ``"sprite"`` restricts the URL to organization
 members (the platform's default); ``"public"`` opens it to the internet."""
 
+# Module-level cache of the framed platform-context text keyed by sprite name.
+# ``Capability.clone`` runs every agent turn and resets per-instance attribute
+# state, so a per-instance cache would re-exec ``cat /.sprite/llm.txt`` every
+# turn — waking a paused sprite for nothing on turns where the model never
+# calls a tool. Caching at module scope by sprite name lets the file land
+# exactly once per sprite for the life of the process. ``clear_platform_context_cache``
+# below is exposed for applications that want to force a re-fetch (e.g.
+# after a sprite image upgrade).
+_PLATFORM_CONTEXT_CACHE: dict[tuple[str, str], str] = {}
+
+
+def clear_platform_context_cache(sprite_name: str | None = None, path: str | None = None) -> None:
+    """Forget cached platform-context text.
+
+    With no arguments, clears every entry. Pass ``sprite_name`` (and optionally
+    ``path``) to evict a specific entry.
+    """
+
+    if sprite_name is None:
+        _PLATFORM_CONTEXT_CACHE.clear()
+        return
+    if path is None:
+        for key in list(_PLATFORM_CONTEXT_CACHE.keys()):
+            if key[0] == sprite_name:
+                del _PLATFORM_CONTEXT_CACHE[key]
+        return
+    _PLATFORM_CONTEXT_CACHE.pop((sprite_name, path), None)
+
 
 class SpritesPlatformContext(Capability):
     """Inject the sprite's ``/.sprite/llm.txt`` platform-context file into the agent's instructions.
@@ -56,24 +82,20 @@ class SpritesPlatformContext(Capability):
     timeout_s: float = 5.0
     """Timeout for the ``cat`` exec call."""
 
-    _cached_text: str | None = PrivateAttr(default=None)
-
-    def bind(self, session: BaseSandboxSession) -> None:
-        super().bind(session)
-        # Reset the cache on rebind so a different session re-reads its own file.
-        self._cached_text = None
-
     async def instructions(self, manifest: Manifest) -> str | None:
         _ = manifest
-        if self._cached_text is not None:
-            return self._cached_text
-        if self.session is None:
+        session = self.session
+        if session is None:
             return None
 
+        sprite_name = _resolve_sprite_name(session)
+        cache_key = (sprite_name or "", self.path)
+        cached = _PLATFORM_CONTEXT_CACHE.get(cache_key)
+        if cached is not None:
+            return cached
+
         try:
-            result = await self.session.exec(
-                "cat", "--", self.path, shell=False, timeout=self.timeout_s
-            )
+            result = await session.exec("cat", "--", self.path, shell=False, timeout=self.timeout_s)
         except Exception:
             return None
         if not result.ok():
@@ -92,7 +114,8 @@ async def instructions(self, manifest: Manifest) -> str | None:
             f"{text}\n"
             "</sprites-platform-context>"
         )
-        self._cached_text = framed
+        if sprite_name:
+            _PLATFORM_CONTEXT_CACHE[cache_key] = framed
         return framed
 
 
@@ -111,6 +134,17 @@ def _resolve_sprite_handle(session: BaseSandboxSession | None) -> Any | None:
     return sprite
 
 
+def _resolve_sprite_name(session: BaseSandboxSession | None) -> str | None:
+    """Return the underlying sprite's name, or None if not yet known."""
+
+    if session is None:
+        return None
+    inner = getattr(session, "_inner", session)
+    state = getattr(inner, "state", None)
+    name = getattr(state, "sprite_name", None) if state is not None else None
+    return name if isinstance(name, str) and name else None
+
+
 class SpritesUrlAccess(Capability):
     """Expose a tool that lets the agent toggle the sprite's public URL visibility.
 
@@ -357,4 +391,5 @@ def _do_restore() -> list[str]:
     "SpritesPlatformContext",
     "SpritesUrlAccess",
     "UrlVisibility",
+    "clear_platform_context_cache",
 ]

tests/extensions/test_sandbox_sprites.py

@@ -41,6 +41,17 @@
 SESSION_UUID = uuid.UUID("11111111-1111-1111-1111-111111111111")
 
 
+@pytest.fixture(autouse=True)
+def _clear_platform_context_cache() -> Any:
+    """Make sure cached platform-context text from one test doesn't leak."""
+
+    from agents.extensions.sandbox.sprites import clear_platform_context_cache
+
+    clear_platform_context_cache()
+    yield
+    clear_platform_context_cache()
+
+
 def _attach(inner: SpritesSandboxSession, *, client: Any, sprite: Any = None) -> None:
     """Inject fake client/sprite into a SpritesSandboxSession.
 
@@ -1243,3 +1254,73 @@ async def test_activity_during_idle_window_keeps_connection_open(
     assert watcher is not None
     await asyncio.wait_for(watcher, timeout=0.2)
     assert sprite.close_control_connection_calls == 1
+
+
+# ---------- 19. Platform-context cache survives cloning ----------
+
+
+@pytest.mark.asyncio
+async def test_sprites_platform_context_cache_survives_clone(
+    patched_sprites: dict[str, Any],
+) -> None:
+    """Each agent turn re-clones capabilities; the cache must survive that.
+
+    Without a module-level cache, a new clone wakes the sprite every turn
+    just to re-read the (unchanged) platform-context file. With it, only
+    the first turn for a given sprite-name pays the exec.
+    """
+
+    fake_control = patched_sprites["control"]
+    fake_control.next_ops.append(_FakeOpConn(stdout=b"# Sprite\n", exit_code=0))
+    fake_client = patched_sprites["client"]
+    sprite = _FakeSprite(name=SPRITE_NAME)
+    fake_client._sprites_by_name[SPRITE_NAME] = sprite
+    state = _make_state()
+    inner = SpritesSandboxSession.from_state(state, token="tok")
+    _attach(inner, client=fake_client, sprite=sprite)
+
+    # Turn 1: a fresh clone fetches and caches.
+    cap1 = SpritesPlatformContext()
+    cap1.bind(inner)
+    out1 = await cap1.instructions(state.manifest)
+    assert out1 is not None
+    assert "<sprites-platform-context>" in out1
+    assert len(fake_control.start_op_calls) == 1
+
+    # Turn 2: a NEW clone targeting the same sprite hits the module cache.
+    cap2 = SpritesPlatformContext()
+    cap2.bind(inner)
+    out2 = await cap2.instructions(state.manifest)
+    assert out2 == out1
+    # Still just the one exec — turn 2 didn't touch the sprite.
+    assert len(fake_control.start_op_calls) == 1
+
+
+@pytest.mark.asyncio
+async def test_sprites_platform_context_cache_clear_forces_refetch(
+    patched_sprites: dict[str, Any],
+) -> None:
+    from agents.extensions.sandbox.sprites import clear_platform_context_cache
+
+    fake_control = patched_sprites["control"]
+    fake_control.next_ops.extend(
+        [_FakeOpConn(stdout=b"v1\n", exit_code=0), _FakeOpConn(stdout=b"v2\n", exit_code=0)]
+    )
+    fake_client = patched_sprites["client"]
+    sprite = _FakeSprite(name=SPRITE_NAME)
+    fake_client._sprites_by_name[SPRITE_NAME] = sprite
+    state = _make_state()
+    inner = SpritesSandboxSession.from_state(state, token="tok")
+    _attach(inner, client=fake_client, sprite=sprite)
+
+    cap = SpritesPlatformContext()
+    cap.bind(inner)
+    out1 = await cap.instructions(state.manifest)
+    assert out1 is not None and "v1" in out1
+    assert len(fake_control.start_op_calls) == 1
+
+    # Cache invalidation forces a re-fetch.
+    clear_platform_context_cache(SPRITE_NAME)
+    out2 = await cap.instructions(state.manifest)
+    assert out2 is not None and "v2" in out2
+    assert len(fake_control.start_op_calls) == 2

tests/sandbox/test_compatibility_guards.py

@@ -347,6 +347,7 @@ def test_core_sandbox_public_export_surface_is_stable() -> None:
                 "SpritesSandboxSessionState",
                 "SpritesUrlAccess",
                 "UrlVisibility",
+                "clear_platform_context_cache",
             },
         ),
     ],