fix: #3043 delimit sandbox prompt instruction sections (#3047)

Author: seratch

src/agents/sandbox/runtime_agent_preparation.py

@@ -58,6 +58,10 @@ def _filesystem_instructions(manifest: Manifest) -> str:
     return f"{header}\n\n{tree}"
 
 
+def _instruction_section(title: str, body: str) -> str:
+    return f"# {title}\n\n{body}"
+
+
 def prepare_sandbox_agent(
     *,
     agent: SandboxAgent[TContext],
@@ -178,15 +182,24 @@ async def _instructions(
                 agent=public_agent,
             )
             if additional:
-                parts.append(additional)
+                parts.append(_instruction_section("Agent instructions", additional))
 
+        capability_fragments: list[str] = []
         for capability in capabilities:
             fragment = await capability.instructions(manifest)
             if fragment:
-                parts.append(fragment)
+                capability_fragments.append(fragment)
+
+        if capability_fragments:
+            parts.append(
+                _instruction_section(
+                    "Sandbox capability instructions",
+                    "\n\n".join(capability_fragments),
+                )
+            )
 
         if remote_mount_policy := build_remote_mount_policy_instructions(manifest):
-            parts.append(remote_mount_policy)
+            parts.append(_instruction_section("Sandbox remote mount policy", remote_mount_policy))
 
         parts.append(_filesystem_instructions(manifest))
 

tests/sandbox/test_runtime.py

@@ -975,7 +975,9 @@ async def test_runner_merges_sandbox_instructions_and_tools() -> None:
     assert model.first_turn_args is not None
     assert model.first_turn_args["system_instructions"] == (
         f"{get_default_sandbox_instructions()}\n\n"
+        "# Agent instructions\n\n"
         "Additional instructions.\n\n"
+        "# Sandbox capability instructions\n\n"
         "Capability instructions.\n\n"
         f"{runtime_agent_preparation_module._filesystem_instructions(manifest)}"
     )
@@ -1055,6 +1057,7 @@ async def test_runner_uses_default_sandbox_prompt_when_instructions_missing() ->
     assert model.first_turn_args is not None
     expected_instructions = (
         f"{get_default_sandbox_instructions()}\n\n"
+        "# Sandbox capability instructions\n\n"
         "Capability instructions.\n\n"
         f"{runtime_agent_preparation_module._filesystem_instructions(session.state.manifest)}"
     )
@@ -1093,7 +1096,9 @@ def _raise_file_not_found(_package: object) -> object:
     assert result.final_output == "done"
     assert model.first_turn_args is not None
     assert model.first_turn_args["system_instructions"] == (
+        "# Agent instructions\n\n"
         "Additional instructions.\n\n"
+        "# Sandbox capability instructions\n\n"
         "Capability instructions.\n\n"
         f"{runtime_agent_preparation_module._filesystem_instructions(session.state.manifest)}"
     )
@@ -1129,6 +1134,7 @@ def dynamic_instructions(
     assert model.first_turn_args is not None
     assert model.first_turn_args["system_instructions"] == (
         f"{get_default_sandbox_instructions()}\n\n"
+        "# Sandbox capability instructions\n\n"
         "Capability instructions.\n\n"
         f"{runtime_agent_preparation_module._filesystem_instructions(session.state.manifest)}"
     )
@@ -1158,7 +1164,9 @@ async def test_runner_base_instructions_override_default_sandbox_prompt() -> Non
     assert model.first_turn_args is not None
     assert model.first_turn_args["system_instructions"] == (
         "Custom base instructions.\n\n"
+        "# Agent instructions\n\n"
         "Additional instructions.\n\n"
+        "# Sandbox capability instructions\n\n"
         "Capability instructions.\n\n"
         f"{runtime_agent_preparation_module._filesystem_instructions(session.state.manifest)}"
     )
@@ -1212,6 +1220,11 @@ async def test_runner_adds_remote_mount_policy_instructions() -> None:
         ),
     )
     assert isinstance(re.search(expected_policy_pattern, system_instructions), re.Match)
+    agent_index = system_instructions.index("# Agent instructions")
+    capability_index = system_instructions.index("# Sandbox capability instructions")
+    remote_policy_index = system_instructions.index("# Sandbox remote mount policy")
+    filesystem_index = system_instructions.index("# Filesystem")
+    assert agent_index < capability_index < remote_policy_index < filesystem_index
 
 
 @pytest.mark.asyncio
@@ -1619,7 +1632,9 @@ def dynamic_instructions(_ctx: RunContextWrapper[Any], current_agent: Agent[Any]
     assert model.first_turn_args is not None
     assert model.first_turn_args["system_instructions"] == (
         f"{get_default_sandbox_instructions()}\n\n"
+        "# Agent instructions\n\n"
         "Saw public agent.\n\n"
+        "# Sandbox capability instructions\n\n"
         "Capability instructions.\n\n"
         f"{runtime_agent_preparation_module._filesystem_instructions(Manifest())}"
     )
@@ -1800,7 +1815,9 @@ async def test_runner_rebuilds_sandbox_resources_for_handoff_target_agent() -> N
     assert worker_model.first_turn_args is not None
     assert worker_model.first_turn_args["system_instructions"] == (
         f"{get_default_sandbox_instructions()}\n\n"
+        "# Agent instructions\n\n"
         "Worker instructions.\n\n"
+        "# Sandbox capability instructions\n\n"
         "Worker workspace\n\n"
         f"{runtime_agent_preparation_module._filesystem_instructions(worker_manifest)}"
     )
@@ -1863,7 +1880,9 @@ def approval_tool() -> str:
     assert worker_model.first_turn_args is not None
     assert worker_model.first_turn_args["system_instructions"] == (
         f"{get_default_sandbox_instructions()}\n\n"
+        "# Agent instructions\n\n"
         "Worker instructions.\n\n"
+        "# Sandbox capability instructions\n\n"
         "Worker workspace\n\n"
         f"{runtime_agent_preparation_module._filesystem_instructions(worker_manifest)}"
     )
@@ -4533,7 +4552,9 @@ async def test_runner_reapplies_sandbox_prep_on_handoff() -> None:
     assert worker_model.first_turn_args is not None
     assert worker_model.first_turn_args["system_instructions"] == (
         f"{get_default_sandbox_instructions()}\n\n"
+        "# Agent instructions\n\n"
         "Worker instructions.\n\n"
+        "# Sandbox capability instructions\n\n"
         "Worker capability.\n\n"
         f"{runtime_agent_preparation_module._filesystem_instructions(session.state.manifest)}"
     )
@@ -4738,13 +4759,17 @@ async def test_runner_isolates_shared_capabilities_per_run() -> None:
     assert model_two.first_turn_args is not None
     assert model_one.first_turn_args["system_instructions"] == (
         f"{get_default_sandbox_instructions()}\n\n"
+        "# Agent instructions\n\n"
         "Base instructions.\n\n"
+        "# Sandbox capability instructions\n\n"
         "Session one instructions.\n\n"
         f"{runtime_agent_preparation_module._filesystem_instructions(session_one.state.manifest)}"
     )
     assert model_two.first_turn_args["system_instructions"] == (
         f"{get_default_sandbox_instructions()}\n\n"
+        "# Agent instructions\n\n"
         "Base instructions.\n\n"
+        "# Sandbox capability instructions\n\n"
         "Session two instructions.\n\n"
         f"{runtime_agent_preparation_module._filesystem_instructions(session_two.state.manifest)}"
     )

tests/test_sandbox_runtime_agent_preparation.py

@@ -74,7 +74,44 @@ def test_prepare_sandbox_agent_passes_session_manifest_to_capability_instruction
 
     assert result == (
         "base instructions\n\n"
+        "# Agent instructions\n\n"
         "additional instructions\n\n"
+        "# Sandbox capability instructions\n\n"
+        "capability fragment\n\n"
+        f"{sandbox_prep._filesystem_instructions(manifest)}"
+    )
+    assert capability.manifests == [manifest]
+
+
+def test_prepare_sandbox_agent_wraps_capabilities_without_agent_instructions():
+    manifest = Manifest(root="/workspace")
+    capability = _Capability("capability fragment")
+    prepared = sandbox_prep.prepare_sandbox_agent(
+        agent=SandboxAgent(
+            name="sandbox",
+            base_instructions="base instructions",
+        ),
+        session=cast(BaseSandboxSession, _session_with_manifest(manifest)),
+        capabilities=cast(list[Capability], [capability]),
+    )
+    instructions = cast(
+        Callable[[RunContextWrapper[object], SandboxAgent[object]], Awaitable[str | None]],
+        prepared.instructions,
+    )
+
+    result: str | None = asyncio.run(
+        cast(
+            Coroutine[Any, Any, str | None],
+            instructions(
+                cast(RunContextWrapper[object], None),
+                cast(SandboxAgent[object], prepared),
+            ),
+        )
+    )
+
+    assert result == (
+        "base instructions\n\n"
+        "# Sandbox capability instructions\n\n"
         "capability fragment\n\n"
         f"{sandbox_prep._filesystem_instructions(manifest)}"
     )
@@ -145,7 +182,9 @@ def test_prepare_sandbox_agent_uses_default_sandbox_instructions_when_base_missi
     assert default_instructions is not None
     assert result == (
         f"{default_instructions}\n\n"
+        "# Agent instructions\n\n"
         "additional instructions\n\n"
+        "# Sandbox capability instructions\n\n"
         "capability fragment\n\n"
         f"{sandbox_prep._filesystem_instructions(manifest)}"
     )