feat(sprites): lazy-warm ephemeral sessions too

Extends the lazy wait-for-running pattern from named-attach to the
created_by_us=True path. Sprites can transition between cold/warm/
running freely with auto-wake-on-traffic, and ``create_sprite`` already
raises eagerly on platform rejection — so the eager poll on the
ephemeral path was paying ~1.5s per session just to confirm something
the platform implicitly handles.

Now both paths skip the poll in ``_ensure_sprite``; ``_ensure_warm``
runs once on first I/O. ``_resolve_exposed_port`` calls ``_ensure_warm``
explicitly because it needs ``Sprite.url`` populated (which happens
during the post-poll refresh).

TUI startup goes from ~7.6s to ~6.0s. The ~1.5s saved is exactly the
poll we now skip; the wake-up cost shifts to the agent's first exec,
where it overlaps with model thinking time and is invisible to the user.

Updates ``test_create_ephemeral_sprite`` to assert no eager get_sprite
poll fires, mirroring the named-attach assertion.

Author: vaurdan

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

@@ -327,6 +327,9 @@ async def _ensure_sprite(self) -> Sprite:
         client = self._ensure_client_sync()
         sprite: Sprite
         if self.state.created_by_us:
+            # Provision a fresh sprite. ``create_sprite`` raises eagerly if the
+            # platform rejects the request, so we still surface creation
+            # failures synchronously here.
             config = self._build_sprite_config()
             try:
                 sprite = await asyncio.to_thread(
@@ -344,29 +347,21 @@ async def _ensure_sprite(self) -> Sprite:
                 ) from exc
             await self._maybe_update_url_settings(sprite)
             self._sprite = sprite
-            # Fresh sprite: poll until it reaches a ready status, then refresh
-            # its info so ``url`` / ``organization_name`` are populated. We
-            # have to poll regardless because the create call doesn't tell us
-            # when provisioning finishes.
-            await self._wait_for_sprite_running()
-            self._warmth_verified = True
-            refreshed: Sprite
-            try:
-                refreshed = await asyncio.to_thread(client.get_sprite, self.state.sprite_name)
-            except SpriteError:
-                refreshed = sprite
-            self._sprite = refreshed
-            return refreshed
-
-        # Named-attach: skip the readiness poll on attach. The sprite may be
-        # cold (paused) and we don't want to pay wake-up latency just to hand
-        # the agent a session handle. The first I/O operation drives the
-        # wake-up via ``_ensure_warm`` — the platform auto-wakes a paused
-        # sprite when traffic arrives, so this is essentially free.
+            return sprite
+
+        # Named-attach: just construct the handle.
         sprite = await asyncio.to_thread(client.sprite, self.state.sprite_name)
         self._sprite = sprite
         return sprite
 
+    # Both ephemeral and named-attach paths now defer the wait-for-running poll
+    # (and the URL/org-info refresh that comes with it) until the first I/O
+    # operation runs ``_ensure_warm``. The platform auto-wakes paused sprites
+    # on traffic arrival and the create POST raises eagerly on rejection, so
+    # this purely shifts the warm-up cost from session creation to first use
+    # without losing any safety. Callers that need ``Sprite.url`` (e.g.
+    # ``_resolve_exposed_port``) call ``_ensure_warm`` themselves.
+
     async def _ensure_warm(self) -> None:
         """Block until the sprite is ready to accept I/O, but only on first use.
 
@@ -952,7 +947,19 @@ async def _terminate_pty_entry(self, entry: _SpritePtyProcessEntry) -> None:
             self._release_control(entry.control)
 
     async def _resolve_exposed_port(self, port: int) -> ExposedPortEndpoint:
-        sprite = await self._ensure_sprite()
+        await self._ensure_sprite()
+        # Make sure the sprite is reachable AND that ``Sprite.url`` /
+        # ``organization_name`` are populated — these come from the post-poll
+        # ``get_sprite`` refresh.
+        await self._ensure_warm()
+        sprite = self._sprite
+        if sprite is None:
+            raise ExposedPortUnavailableError(
+                port=port,
+                exposed_ports=self.state.exposed_ports,
+                reason="backend_unavailable",
+                context={"backend": "sprites", "sprite_name": self.state.sprite_name},
+            )
         url = sprite.url
         if not url:
             raise ExposedPortUnavailableError(

tests/extensions/test_sandbox_sprites.py

@@ -378,8 +378,10 @@ async def test_create_ephemeral_sprite(patched_sprites: dict[str, Any]) -> None:
     assert inner.state.created_by_us is True
     assert len(fake_client.create_sprite_calls) == 1
     assert fake_client.create_sprite_calls[0][0].startswith("openai-agents-")
-    # get_sprite called for status poll + the post-create refresh
-    assert len(fake_client.get_sprite_calls) >= 1
+    # No eager get_sprite poll — ephemeral path is lazy too. The first I/O
+    # operation drives the wait-for-running via ``_ensure_warm``.
+    assert fake_client.get_sprite_calls == []
+    assert inner._warmth_verified is False
     # delete via client.delete deletes the ephemeral sprite
     await client.delete(session)
     assert fake_client.delete_sprite_calls == [fake_client.create_sprite_calls[0][0]]