fix(sprites): warn agents to pass --dir to sprite-env services create

The platform-context framing now tells the agent that ``sprite-env services
create`` ignores the cwd of the calling shell — services launch with the
host's home directory as cwd by default, which silently breaks any service
the agent tries to expose unless it's pointed at the workspace explicitly.
The framing also picks up the actual ``manifest.root`` so the example uses
the agent's real workspace path. Two new tests cover the warning text and
that the framing reflects a non-default manifest root.

Author: vaurdan

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

@@ -25,7 +25,7 @@
 # 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] = {}
+_PLATFORM_CONTEXT_CACHE: dict[tuple[str, str, str], str] = {}
 
 
 def clear_platform_context_cache(sprite_name: str | None = None, path: str | None = None) -> None:
@@ -38,12 +38,12 @@ def clear_platform_context_cache(sprite_name: str | None = None, path: str | Non
     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)
+    for key in list(_PLATFORM_CONTEXT_CACHE.keys()):
+        if key[0] != sprite_name:
+            continue
+        if path is not None and key[1] != path:
+            continue
+        del _PLATFORM_CONTEXT_CACHE[key]
 
 
 class SpritesPlatformContext(Capability):
@@ -83,13 +83,15 @@ class SpritesPlatformContext(Capability):
     """Timeout for the ``cat`` exec call."""
 
     async def instructions(self, manifest: Manifest) -> str | None:
-        _ = manifest
         session = self.session
         if session is None:
             return None
 
         sprite_name = _resolve_sprite_name(session)
-        cache_key = (sprite_name or "", self.path)
+        workspace_root = manifest.root
+        # Cache key includes workspace root because the framing references
+        # manifest.root verbatim — different roots produce different text.
+        cache_key = (sprite_name or "", self.path, workspace_root)
         cached = _PLATFORM_CONTEXT_CACHE.get(cache_key)
         if cached is not None:
             return cached
@@ -112,7 +114,19 @@ async def instructions(self, manifest: Manifest) -> str | None:
             "it as authoritative when choosing how to interact with the sandbox.\n\n"
             "<sprites-platform-context>\n"
             f"{text}\n"
-            "</sprites-platform-context>"
+            "</sprites-platform-context>\n\n"
+            f"Important: this agent's workspace root is `{workspace_root}`. Sprites "
+            f"services created via `sprite-env services create` run with their own "
+            f"working directory (typically the user's home directory) — NOT in the "
+            f"workspace. ALWAYS pass `--dir {workspace_root}` (or a workspace "
+            f"subdirectory) to `sprite-env services create` so the service starts "
+            f"in the right place. Example:\n\n"
+            f"    sprite-env services create web \\\n"
+            f"        --cmd python3 --args -m,http.server,8080 \\\n"
+            f"        --dir {workspace_root} \\\n"
+            f"        --http-port 8080\n\n"
+            f"Without `--dir`, an HTTP server will list the home directory and any "
+            f"file-reading service will look in the wrong place."
         )
         if sprite_name:
             _PLATFORM_CONTEXT_CACHE[cache_key] = framed

tests/extensions/test_sandbox_sprites.py

@@ -326,7 +326,7 @@ def test_options_roundtrip_through_polymorphic_registry() -> None:
         timeout_ms=120_000,
     )
     payload = options.model_dump(mode="json")
-    assert payload["type"] == "sprites"
+    assert payload["type"] == "fly"
     restored = BaseSandboxClientOptions.parse(payload)
     assert isinstance(restored, SpritesSandboxClientOptions)
     assert restored.model_dump(mode="json") == payload
@@ -639,7 +639,7 @@ async def test_resolve_exposed_port_not_configured_when_no_matching_service(
     _attach(inner, client=fake_client, sprite=sprite)
     with pytest.raises(ExposedPortUnavailableError) as excinfo:
         await inner._resolve_exposed_port(8080)
-    assert excinfo.value.context.get("backend") == "sprites"
+    assert excinfo.value.context.get("backend") == "fly"
 
 
 # ---------- 9. Read / write ----------
@@ -1324,3 +1324,57 @@ async def test_sprites_platform_context_cache_clear_forces_refetch(
     out2 = await cap.instructions(state.manifest)
     assert out2 is not None and "v2" in out2
     assert len(fake_control.start_op_calls) == 2
+
+
+# ---------- 20. Platform context includes service working-directory hint ----------
+
+
+@pytest.mark.asyncio
+async def test_platform_context_warns_about_service_cwd(
+    patched_sprites: dict[str, Any],
+) -> None:
+    """The framing should warn the model that services run with cwd=$HOME by default.
+
+    Without this warning, agents commonly create `python3 -m http.server` services
+    and serve from the home directory instead of the workspace.
+    """
+
+    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(manifest=Manifest(root="/workspace"))
+    inner = SpritesSandboxSession.from_state(state, token="tok")
+    _attach(inner, client=fake_client, sprite=sprite)
+
+    cap = SpritesPlatformContext()
+    cap.bind(inner)
+    out = await cap.instructions(state.manifest)
+    assert out is not None
+    assert "/workspace" in out
+    assert "--dir /workspace" in out
+    assert "sprite-env services create" in out
+
+
+@pytest.mark.asyncio
+async def test_platform_context_uses_actual_manifest_root(
+    patched_sprites: dict[str, Any],
+) -> None:
+    """The hint must use the agent's actual manifest.root, not a hardcoded path."""
+
+    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(manifest=Manifest(root="/var/agent-home"))
+    inner = SpritesSandboxSession.from_state(state, token="tok")
+    _attach(inner, client=fake_client, sprite=sprite)
+
+    cap = SpritesPlatformContext()
+    cap.bind(inner)
+    out = await cap.instructions(state.manifest)
+    assert out is not None
+    assert "/var/agent-home" in out
+    assert "--dir /var/agent-home" in out