refactor: make AgentProvisionPlan the source of truth for instance_name, prompt_file, image, dockerfile, guest_home

Drop the parallel fields passed through prepare() → _resolve_plan and
read everything from agent_provision instead. The provider plugin now
declares its own guest_home (so the backend stops hardcoding
"/home/node") and the wrapper that builds the provision plan accepts
instance_name and prompt_file, which providers store on the plan.

DockerBottlePlan and SmolmachinesBottlePlan expose container_name /
machine_name, image / agent_image, dockerfile_path /
agent_dockerfile_path, and prompt_file as properties that delegate to
agent_provision so existing call sites keep working unchanged.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

tests/unit/test_agent_provider.py

@@ -26,10 +26,11 @@ class TestAgentProviderRuntime(unittest.TestCase):
     def test_codex_plan_declares_home_state(self):
         with tempfile.TemporaryDirectory(prefix="bb-provider.") as tmp:
             plan = build_agent_provision_plan(
-                guest_home="/home/node",
                 template="codex",
                 dockerfile="/tmp/Dockerfile.codex",
                 state_dir=Path(tmp),
+                instance_name="bot-bottle-test",
+                prompt_file=Path(tmp) / "prompt.txt",
             )
             config = Path(tmp, "codex-config.toml").read_text()
         self.assertEqual("codex", plan.template)
@@ -51,10 +52,11 @@ class TestAgentProviderRuntime(unittest.TestCase):
     def test_codex_trusts_requested_project_path(self):
         with tempfile.TemporaryDirectory(prefix="bb-provider.") as tmp:
             build_agent_provision_plan(
-                guest_home="/home/node",
                 template="codex",
                 dockerfile="",
                 state_dir=Path(tmp),
+                instance_name="bot-bottle-test",
+                prompt_file=Path(tmp) / "prompt.txt",
                 trusted_project_path="/home/node/workspace",
             )
             config = Path(tmp, "codex-config.toml").read_text()
@@ -69,10 +71,11 @@ class TestAgentProviderRuntime(unittest.TestCase):
                 "tokens": {"access_token": _jwt(2000000000)},
             }))
             plan = build_agent_provision_plan(
-                guest_home="/home/node",
                 template="codex",
                 dockerfile="",
                 state_dir=Path(tmp),
+                instance_name="bot-bottle-test",
+                prompt_file=Path(tmp) / "prompt.txt",
                 guest_env={"CODEX_HOME": "/run/codex-home"},
                 forward_host_credentials=True,
                 host_env={"CODEX_HOME": str(home)},
@@ -89,10 +92,11 @@ class TestAgentProviderRuntime(unittest.TestCase):
     def test_claude_with_auth_token_injects_provider_route_and_placeholder(self):
         with tempfile.TemporaryDirectory(prefix="bb-provider.") as tmp:
             plan = build_agent_provision_plan(
-                guest_home="/home/node",
                 template="claude",
                 dockerfile="/tmp/Dockerfile.claude",
                 state_dir=Path(tmp),
+                instance_name="bot-bottle-test",
+                prompt_file=Path(tmp) / "prompt.txt",
                 auth_token="BOT_BOTTLE_CLAUDE_OAUTH_TOKEN",
             )
             claude_config = json.loads(Path(tmp, "claude.json").read_text())
@@ -111,10 +115,11 @@ class TestAgentProviderRuntime(unittest.TestCase):
     def test_claude_trusts_requested_project_path(self):
         with tempfile.TemporaryDirectory(prefix="bb-provider.") as tmp:
             build_agent_provision_plan(
-                guest_home="/home/node",
                 template="claude",
                 dockerfile="",
                 state_dir=Path(tmp),
+                instance_name="bot-bottle-test",
+                prompt_file=Path(tmp) / "prompt.txt",
                 trusted_project_path="/home/node/workspace",
             )
             config = json.loads(Path(tmp, "claude.json").read_text())
@@ -130,10 +135,11 @@ class TestAgentProviderRuntime(unittest.TestCase):
                 "tokens": {"access_token": _jwt(2000000000)},
             }))
             plan = build_agent_provision_plan(
-                guest_home="/home/node",
                 template="codex",
                 dockerfile="",
                 state_dir=Path(tmp),
+                instance_name="bot-bottle-test",
+                prompt_file=Path(tmp) / "prompt.txt",
                 forward_host_credentials=True,
                 host_env={"CODEX_HOME": str(home)},
             )
@@ -146,10 +152,11 @@ class TestAgentProviderRuntime(unittest.TestCase):
     def test_codex_without_forward_host_credentials_has_passthrough_egress_routes(self):
         with tempfile.TemporaryDirectory(prefix="bb-provider.") as tmp:
             plan = build_agent_provision_plan(
-                guest_home="/home/node",
                 template="codex",
                 dockerfile="",
                 state_dir=Path(tmp),
+                instance_name="bot-bottle-test",
+                prompt_file=Path(tmp) / "prompt.txt",
                 forward_host_credentials=False,
             )
         self.assertEqual(
@@ -163,10 +170,11 @@ class TestAgentProviderRuntime(unittest.TestCase):
     def test_claude_without_auth_token_has_passthrough_egress_route(self):
         with tempfile.TemporaryDirectory(prefix="bb-provider.") as tmp:
             plan = build_agent_provision_plan(
-                guest_home="/home/node",
                 template="claude",
                 dockerfile="",
                 state_dir=Path(tmp),
+                instance_name="bot-bottle-test",
+                prompt_file=Path(tmp) / "prompt.txt",
             )
         self.assertEqual(1, len(plan.egress_routes))
         route = plan.egress_routes[0]
@@ -186,10 +194,11 @@ class TestAgentProviderRuntime(unittest.TestCase):
                 "tokens": {"access_token": access},
             }))
             plan = build_agent_provision_plan(
-                guest_home="/home/node",
                 template="codex",
                 dockerfile="",
                 state_dir=Path(tmp),
+                instance_name="bot-bottle-test",
+                prompt_file=Path(tmp) / "prompt.txt",
                 forward_host_credentials=True,
                 host_env={"CODEX_HOME": str(home)},
             )
@@ -201,10 +210,11 @@ class TestAgentProviderRuntime(unittest.TestCase):
     def test_codex_without_forward_host_credentials_has_empty_provisioned_env(self):
         with tempfile.TemporaryDirectory(prefix="bb-provider.") as tmp:
             plan = build_agent_provision_plan(
-                guest_home="/home/node",
                 template="codex",
                 dockerfile="",
                 state_dir=Path(tmp),
+                instance_name="bot-bottle-test",
+                prompt_file=Path(tmp) / "prompt.txt",
                 forward_host_credentials=False,
             )
         self.assertEqual({}, plan.provisioned_env)

tests/unit/test_compose.py

@@ -152,11 +152,7 @@ def _plan(
         spec=spec,
         stage_dir=STAGE,
         slug=SLUG,
-        container_name=f"bot-bottle-{SLUG}",
-        image="bot-bottle-claude:latest",
-        dockerfile_path="",
         forwarded_env={"CLAUDE_CODE_OAUTH_TOKEN": "x"},
-        prompt_file=STAGE / "prompt",
         git_gate_plan=_git_gate_plan(upstreams),
         egress_plan=_egress_plan(routes),
         supervise_plan=_supervise_plan() if supervise else None,
@@ -168,6 +164,8 @@ def _plan(
             image="bot-bottle-claude:latest",
             dockerfile="",
             guest_home="/home/node",
+            instance_name=f"bot-bottle-{SLUG}",
+            prompt_file=STAGE / "prompt",
             guest_env={},
         ),
     )
@@ -248,6 +246,8 @@ class TestAgentAlwaysPresent(unittest.TestCase):
             image="bot-bottle-codex:latest",
             dockerfile="",
             guest_home="/home/node",
+            instance_name=f"bot-bottle-{SLUG}",
+            prompt_file=STAGE / "prompt",
             guest_env={"CODEX_HOME": "/home/node/.codex"},
         )
         plan = type(plan)(**{**vars(plan), "agent_provision": provision})  # type: ignore

tests/unit/test_contrib_claude_provider.py

@@ -79,11 +79,7 @@ def _plan(
         spec=spec,
         stage_dir=Path("/tmp/stage"),
         slug="demo-abc12",
-        container_name="bot-bottle-demo-abc12",
-        image="bot-bottle-claude:latest",
-        dockerfile_path="",
         forwarded_env={},
-        prompt_file=Path("/tmp/state/demo-abc12/agent/prompt.txt"),
         git_gate_plan=GitGatePlan(
             slug="demo-abc12",
             entrypoint_script=Path("/tmp/git-gate-entrypoint.sh"),
@@ -101,7 +97,11 @@ def _plan(
         use_runsc=False,
         agent_provision=agent_provision or AgentProvisionPlan(
             template="claude", command="claude", prompt_mode="append_file",
-            image="", dockerfile="", guest_home="/home/node", guest_env={},
+            image="bot-bottle-claude:latest", dockerfile="",
+            guest_home="/home/node",
+            instance_name="bot-bottle-demo-abc12",
+            prompt_file=Path("/tmp/state/demo-abc12/agent/prompt.txt"),
+            guest_env={},
         ),
     )
 
@@ -205,7 +205,10 @@ class TestClaudeProvision(unittest.TestCase):
     def test_copies_files_and_chowns(self):
         provision = AgentProvisionPlan(
             template="claude", command="claude", prompt_mode="append_file",
-            image="", dockerfile="", guest_home="/home/node", guest_env={},
+            image="", dockerfile="", guest_home="/home/node",
+            instance_name="bot-bottle-demo-abc12",
+            prompt_file=Path("/tmp/prompt.txt"),
+            guest_env={},
             files=(AgentProvisionFile(
                 Path("/tmp/claude.json"), "/home/node/.claude.json",
             ),),
@@ -228,7 +231,10 @@ class TestClaudeProvision(unittest.TestCase):
     def test_dies_when_file_chown_fails(self):
         provision = AgentProvisionPlan(
             template="claude", command="claude", prompt_mode="append_file",
-            image="", dockerfile="", guest_home="/home/node", guest_env={},
+            image="", dockerfile="", guest_home="/home/node",
+            instance_name="bot-bottle-demo-abc12",
+            prompt_file=Path("/tmp/prompt.txt"),
+            guest_env={},
             files=(AgentProvisionFile(
                 Path("/tmp/claude.json"), "/home/node/.claude.json",
             ),),
@@ -244,7 +250,10 @@ class TestClaudeProvision(unittest.TestCase):
     def test_runs_verify_commands(self):
         provision = AgentProvisionPlan(
             template="claude", command="claude", prompt_mode="append_file",
-            image="", dockerfile="", guest_home="/home/node", guest_env={},
+            image="", dockerfile="", guest_home="/home/node",
+            instance_name="bot-bottle-demo-abc12",
+            prompt_file=Path("/tmp/prompt.txt"),
+            guest_env={},
             verify=(AgentProvisionCommand(
                 ("/usr/bin/true",), "verify failed",
             ),),

tests/unit/test_contrib_codex_provider.py

@@ -80,11 +80,7 @@ def _plan(
         spec=spec,
         stage_dir=Path("/tmp/stage"),
         slug="demo-abc12",
-        container_name="bot-bottle-demo-abc12",
-        image="bot-bottle-codex:latest",
-        dockerfile_path="",
         forwarded_env={},
-        prompt_file=Path("/tmp/state/demo-abc12/agent/prompt.txt"),
         git_gate_plan=GitGatePlan(
             slug="demo-abc12",
             entrypoint_script=Path("/tmp/git-gate-entrypoint.sh"),
@@ -102,7 +98,11 @@ def _plan(
         use_runsc=False,
         agent_provision=agent_provision or AgentProvisionPlan(
             template="codex", command="codex", prompt_mode="read_prompt_file",
-            image="", dockerfile="", guest_home="/home/node", guest_env={},
+            image="bot-bottle-codex:latest", dockerfile="",
+            guest_home="/home/node",
+            instance_name="bot-bottle-demo-abc12",
+            prompt_file=Path("/tmp/state/demo-abc12/agent/prompt.txt"),
+            guest_env={},
         ),
     )
 
@@ -171,7 +171,10 @@ class TestCodexProvision(unittest.TestCase):
         provision = AgentProvisionPlan(
             template="codex", command="codex",
             prompt_mode="read_prompt_file",
-            image="", dockerfile="", guest_home="/home/node", guest_env={},
+            image="", dockerfile="", guest_home="/home/node",
+            instance_name="bot-bottle-demo-abc12",
+            prompt_file=Path("/tmp/prompt.txt"),
+            guest_env={},
             dirs=(AgentProvisionDir("/home/node/.codex"),),
             files=(AgentProvisionFile(
                 Path("/tmp/codex-config.toml"),
@@ -195,7 +198,10 @@ class TestCodexProvision(unittest.TestCase):
         provision = AgentProvisionPlan(
             template="codex", command="codex",
             prompt_mode="read_prompt_file",
-            image="", dockerfile="", guest_home="/home/node", guest_env={},
+            image="", dockerfile="", guest_home="/home/node",
+            instance_name="bot-bottle-demo-abc12",
+            prompt_file=Path("/tmp/prompt.txt"),
+            guest_env={},
             pre_copy=(AgentProvisionCommand(
                 ("find", "/home/node/.codex", "-name", "*.sqlite", "-delete"),
                 "could not reset runtime db files",
@@ -217,7 +223,10 @@ class TestCodexProvision(unittest.TestCase):
         provision = AgentProvisionPlan(
             template="codex", command="codex",
             prompt_mode="read_prompt_file",
-            image="", dockerfile="", guest_home="/home/node", guest_env={},
+            image="", dockerfile="", guest_home="/home/node",
+            instance_name="bot-bottle-demo-abc12",
+            prompt_file=Path("/tmp/prompt.txt"),
+            guest_env={},
             dirs=(AgentProvisionDir("/home/node/.codex"),),
         )
         bottle = _make_bottle(exec_result=ExecResult(1, "", "mkdir: nope\n"))

tests/unit/test_docker_launch_teardown.py

@@ -63,17 +63,15 @@ def _plan(tmp: str) -> DockerBottlePlan:
             template="claude",
             command="claude",
             prompt_mode="append_file",
-            image="",
+            image="bot-bottle-claude:latest",
             dockerfile="",
             guest_home="/home/node",
+            instance_name="bot-bottle-test-teardown-abc",
+            prompt_file=stage / "prompt.txt",
             guest_env={},
         ),
         slug="test-teardown-00001",
-        container_name="bot-bottle-test-teardown-abc",
-        image="bot-bottle-claude:latest",
-        dockerfile_path="",
         forwarded_env={},
-        prompt_file=stage / "prompt.txt",
         use_runsc=False,
     )
 

tests/unit/test_docker_provision_git_user.py

@@ -64,11 +64,7 @@ def _plan(*, git_user: dict | None = None,  # type: ignore
         spec=spec,
         stage_dir=stage_dir or Path("/tmp/stage"),
         slug="demo-abc12",
-        container_name="bot-bottle-demo-abc12",
-        image="bot-bottle-claude:latest",
-        dockerfile_path="",
         forwarded_env={},
-        prompt_file=Path("/tmp/prompt.txt"),
         git_gate_plan=GitGatePlan(
             slug="demo-abc12",
             entrypoint_script=Path("/tmp/git-gate-entrypoint.sh"),
@@ -91,6 +87,8 @@ def _plan(*, git_user: dict | None = None,  # type: ignore
             image="bot-bottle-claude:latest",
             dockerfile="",
             guest_home="/home/node",
+            instance_name="bot-bottle-demo-abc12",
+            prompt_file=Path("/tmp/prompt.txt"),
             guest_env={},
         ),
     )

tests/unit/test_plan_print_parity.py

@@ -79,14 +79,16 @@ def _egress_plan(tmp: str) -> EgressPlan:
     )
 
 
-def _agent_provision() -> AgentProvisionPlan:
+def _agent_provision(tmp: str) -> AgentProvisionPlan:
     return AgentProvisionPlan(
         template="claude",
         command="claude",
         prompt_mode="append_file",
-        image="",
+        image="bot-bottle-claude:latest",
         dockerfile="",
         guest_home="/home/node",
+        instance_name="bot-bottle-test-00001",
+        prompt_file=Path(tmp) / "prompt.txt",
         guest_env={"HTTPS_PROXY": "http://127.0.0.1:9999"},
     )
 
@@ -99,13 +101,9 @@ def _docker_plan(spec: BottleSpec, tmp: str) -> DockerBottlePlan:
         git_gate_plan=_git_gate_plan(tmp),
         egress_plan=_egress_plan(tmp),
         supervise_plan=None,
-        agent_provision=_agent_provision(),
+        agent_provision=_agent_provision(tmp),
         slug="test-00001",
-        container_name="bot-bottle-test-00001",
-        image="bot-bottle-claude:latest",
-        dockerfile_path="",
         forwarded_env={},
-        prompt_file=stage / "prompt.txt",
         use_runsc=False,
     )
 
@@ -118,15 +116,12 @@ def _smolmachines_plan(spec: BottleSpec, tmp: str) -> SmolmachinesBottlePlan:
         git_gate_plan=_git_gate_plan(tmp),
         egress_plan=_egress_plan(tmp),
         supervise_plan=None,
-        agent_provision=_agent_provision(),
+        agent_provision=_agent_provision(tmp),
         slug="test-00001",
         bundle_subnet="10.99.0.0/24",
         bundle_gateway="10.99.0.1",
         bundle_ip="10.99.0.2",
-        machine_name="bot-bottle-test-00001",
-        agent_image="bot-bottle-claude:latest",
         guest_env={"HTTPS_PROXY": "http://127.0.0.1:9999"},
-        prompt_file=stage / "prompt.txt",
     )
 
 

tests/unit/test_smolmachines_provision.py

@@ -146,10 +146,7 @@ def _plan(
         bundle_subnet="192.168.50.0/24",
         bundle_gateway="192.168.50.1",
         bundle_ip=bundle_ip,
-        machine_name="bot-bottle-demo-abc12",
-        agent_image="bot-bottle-claude:latest",
         guest_env=dict(guest_env or {}),
-        prompt_file=Path("/tmp/state/demo-abc12/agent/prompt.txt"),
         git_gate_plan=GitGatePlan(
             slug="demo-abc12",
             entrypoint_script=Path("/tmp/git-gate-entrypoint.sh"),
@@ -186,9 +183,11 @@ def _agent_provision(
             template=template,
             command=template,
             prompt_mode="append_file",
-            image="",
+            image="bot-bottle-claude:latest",
             dockerfile="",
             guest_home="/home/node",
+            instance_name="bot-bottle-demo-abc12",
+            prompt_file=Path("/tmp/state/demo-abc12/agent/prompt.txt"),
             guest_env=dict(guest_env or {}),
         )
     auth_dir = (guest_env or {}).get("CODEX_HOME", "/home/node/.codex")
@@ -227,6 +226,8 @@ def _agent_provision(
         image="bot-bottle-codex:latest",
         dockerfile="",
         guest_home="/home/node",
+        instance_name="bot-bottle-demo-abc12",
+        prompt_file=Path("/tmp/state/demo-abc12/agent/prompt.txt"),
         guest_env=dict(guest_env or {}),
         dirs=(AgentProvisionDir(auth_dir),),
         files=tuple(files),