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

Recurring agent confusion: ``sprite-env services create`` runs services
with cwd=$HOME by default, NOT the workspace. Agents create
``python3 -m http.server`` services without ``--dir`` and get directory
listings of the home dir instead of their workspace files.

The ``sprite-env`` CLI does support ``--dir <path>`` to set the
service's working directory, but ``/.sprite/llm.txt`` (the platform's
LLM-facing doc) doesn't currently mention it — agents have no way to
discover it.

Appends a ``--dir``-flagged guidance paragraph to FlyPlatformContext's
framing, interpolated with the agent's actual ``manifest.root`` so the
example is concretely correct for whatever workspace the application
configured. Cache key extended to 3-tuple so different roots produce
different cached strings.

Two regression tests confirm the framing references ``--dir`` with the
actual workspace root and works for non-default roots.

Author: vaurdan

src/agents/extensions/sandbox/flyio/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 FlyPlatformContext(Capability):
@@ -83,13 +83,15 @@ class FlyPlatformContext(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_fly.py

@@ -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 = FlySandboxSession.from_state(state, token="tok")
+    _attach(inner, client=fake_client, sprite=sprite)
+
+    cap = FlyPlatformContext()
+    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 = FlySandboxSession.from_state(state, token="tok")
+    _attach(inner, client=fake_client, sprite=sprite)
+
+    cap = FlyPlatformContext()
+    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