Add Phase.extra_init_kwargs and agent/build.py tests

Author: luisorofino

ddev/src/ddev/ai/phases/agentic_phase.py

@@ -8,7 +8,7 @@
 from typing import Any
 
 from ddev.ai.agent.base import BaseAgent
-from ddev.ai.agent.build import AgentBuilder
+from ddev.ai.agent.build import AgentBuilder, make_agent_builder
 from ddev.ai.callbacks.callbacks import Callbacks
 from ddev.ai.phases.base import Phase, PhaseOutcome
 from ddev.ai.phases.checkpoint import CheckpointManager
@@ -90,6 +90,25 @@ def validate_config(
         if not config.tasks:
             raise FlowConfigError(f"Phase {phase_id!r} (AgenticPhase) must have at least one task")
 
+    @classmethod
+    def extra_init_kwargs(
+        cls,
+        phase_id: str,
+        phase_config: PhaseConfig,
+        agents: dict[str, AgentConfig],
+        agent_clients: dict[str, Any],
+        file_registry: FileRegistry,
+    ) -> dict[str, Any]:
+        if phase_config.agent is None:
+            raise FlowConfigError(f"Phase {phase_id!r} (AgenticPhase) requires 'agent'")
+        return {
+            "agent_builder": make_agent_builder(
+                agent_config=agents[phase_config.agent],
+                agent_clients=agent_clients,
+                file_registry=file_registry,
+            )
+        }
+
     def before_react(self) -> None:
         """Called once before agent/tools are created. Override for phase-specific setup."""
 
@@ -152,9 +171,6 @@ async def _run_memory_step(
         return response.text, response.usage.input_tokens, response.usage.output_tokens
 
     async def execute(self, context: dict[str, Any]) -> PhaseOutcome:
-        if self._config.agent is None:
-            raise FlowConfigError(f"Phase '{self._phase_id}': agent must be set before execute()")
-
         self.before_react()
         agent, process = self._build_agent_and_process(context)
         total_input, total_output = await self.run_tasks(process, context)

ddev/src/ddev/ai/phases/base.py

@@ -108,6 +108,18 @@ def validate_config(
         """Override to enforce per-subclass config invariants. Raise FlowConfigError on mismatch."""
         return None
 
+    @classmethod
+    def extra_init_kwargs(
+        cls,
+        phase_id: str,
+        phase_config: PhaseConfig,
+        agents: dict[str, AgentConfig],
+        agent_clients: dict[str, Any],
+        file_registry: FileRegistry,
+    ) -> dict[str, Any]:
+        """Override to inject subclass-specific kwargs into __init__ at construction time."""
+        return {}
+
     @abstractmethod
     async def execute(self, context: dict[str, Any]) -> PhaseOutcome: ...
 
@@ -126,8 +138,6 @@ async def process_message(self, message: PhaseTrigger) -> None:
 
         outcome = await self.execute(context)
 
-        self._checkpoint_manager.write_memory(self._phase_id, outcome.memory_text)
-
         checkpoint_payload: dict[str, Any] = {
             "status": "success",
             "started_at": self._started_at.isoformat(),
@@ -145,6 +155,7 @@ async def process_message(self, message: PhaseTrigger) -> None:
             )
         checkpoint_payload.update(outcome.extra_checkpoint)
 
+        self._checkpoint_manager.write_memory(self._phase_id, outcome.memory_text)
         self._checkpoint_manager.write_phase_checkpoint(self._phase_id, checkpoint_payload)
         await self._callbacks.fire_phase_finish(self._phase_id)
 

ddev/src/ddev/ai/phases/orchestrator.py

@@ -8,9 +8,7 @@
 from pathlib import Path
 from typing import Any
 
-from ddev.ai.agent.build import make_agent_builder
 from ddev.ai.callbacks.callbacks import Callbacks
-from ddev.ai.phases.agentic_phase import AgenticPhase
 from ddev.ai.phases.base import Phase, PhaseRegistry
 from ddev.ai.phases.checkpoint import CheckpointManager
 from ddev.ai.phases.config import FlowConfig, FlowConfigError
@@ -114,14 +112,15 @@ async def on_initialize(self) -> None:
                 "callbacks": self._callbacks,
                 "logger": self._logger,
             }
-            if issubclass(phase_cls, AgenticPhase):
-                if phase_config.agent is None:
-                    raise FlowConfigError(f"Phase '{phase_id}': agent must be set for AgenticPhase")
-                phase_kwargs["agent_builder"] = make_agent_builder(
-                    agent_config=config.agents[phase_config.agent],
+            phase_kwargs.update(
+                phase_cls.extra_init_kwargs(
+                    phase_id=phase_id,
+                    phase_config=phase_config,
+                    agents=config.agents,
                     agent_clients=self._agent_clients,
                     file_registry=self._file_registry,
                 )
+            )
 
             phase = phase_cls(**phase_kwargs)
 

ddev/tests/ai/agent/test_build.py

@@ -0,0 +1,76 @@
+# (C) Datadog, Inc. 2026-present
+# All rights reserved
+# Licensed under a 3-clause BSD style license (see LICENSE)
+
+from unittest.mock import MagicMock
+
+import pytest
+
+from ddev.ai.agent.anthropic_client import AnthropicAgent
+from ddev.ai.agent.build import build_agent, make_agent_builder
+from ddev.ai.phases.config import AgentConfig
+from ddev.ai.tools.fs.file_access_policy import FileAccessPolicy
+from ddev.ai.tools.fs.file_registry import FileRegistry
+from ddev.ai.tools.registry import ToolRegistry
+
+
+@pytest.fixture
+def file_registry(tmp_path) -> FileRegistry:
+    return FileRegistry(policy=FileAccessPolicy(write_root=tmp_path))
+
+
+def test_build_agent_anthropic_returns_agent_and_registry(file_registry):
+    agent_config = AgentConfig(provider="anthropic", model="claude-test", max_tokens=1024, tools=[])
+    agent_clients = {"anthropic": MagicMock()}
+
+    agent, registry = build_agent(
+        agent_config=agent_config,
+        agent_clients=agent_clients,
+        system_prompt="hello",
+        owner_id="p1",
+        file_registry=file_registry,
+    )
+
+    assert isinstance(agent, AnthropicAgent)
+    assert isinstance(registry, ToolRegistry)
+    assert agent.name == "p1"
+
+
+def test_build_agent_missing_client_raises(file_registry):
+    agent_config = AgentConfig(provider="anthropic", tools=[])
+    with pytest.raises(ValueError, match="No client provided for agent provider 'anthropic'"):
+        build_agent(
+            agent_config=agent_config,
+            agent_clients={},
+            system_prompt="hello",
+            owner_id="p1",
+            file_registry=file_registry,
+        )
+
+
+def test_build_agent_unknown_provider_raises(file_registry):
+    agent_config = AgentConfig(provider="openai", tools=[])
+    with pytest.raises(ValueError, match="Unknown agent provider: 'openai'"):
+        build_agent(
+            agent_config=agent_config,
+            agent_clients={"openai": MagicMock()},
+            system_prompt="hello",
+            owner_id="p1",
+            file_registry=file_registry,
+        )
+
+
+def test_make_agent_builder_returns_callable_that_delegates_to_build_agent(file_registry):
+    agent_config = AgentConfig(provider="anthropic", tools=[])
+    agent_clients = {"anthropic": MagicMock()}
+
+    builder = make_agent_builder(
+        agent_config=agent_config,
+        agent_clients=agent_clients,
+        file_registry=file_registry,
+    )
+
+    agent, registry = builder("system prompt", "p2")
+    assert isinstance(agent, AnthropicAgent)
+    assert isinstance(registry, ToolRegistry)
+    assert agent.name == "p2"

ddev/tests/ai/phases/test_agentic_phase.py

@@ -298,7 +298,7 @@ async def test_runtime_variables_override_flow_variables(flow_dir, monkeypatch,
 
 async def test_before_react_raises_propagates(flow_dir, monkeypatch, message_queue):
     mock_agent = MockAgent([])
-    phase, _ = make_agent_phase(flow_dir, mock_agent, monkeypatch, message_queue)
+    phase, mgr = make_agent_phase(flow_dir, mock_agent, monkeypatch, message_queue)
 
     def failing_hook():
         raise RuntimeError("setup failed")
@@ -308,13 +308,15 @@ def failing_hook():
     with pytest.raises(RuntimeError, match="setup failed"):
         await phase.process_message(PhaseTrigger(id="start", phase_id=None))
 
+    assert mgr.read() == {}
+
 
 async def test_after_react_raises_propagates(flow_dir, monkeypatch, message_queue):
     responses = [
         make_response("done", 100, 50),
     ]
     mock_agent = MockAgent(responses)
-    phase, _ = make_agent_phase(flow_dir, mock_agent, monkeypatch, message_queue)
+    phase, mgr = make_agent_phase(flow_dir, mock_agent, monkeypatch, message_queue)
 
     def failing_hook():
         raise RuntimeError("teardown failed")
@@ -324,6 +326,8 @@ def failing_hook():
     with pytest.raises(RuntimeError, match="teardown failed"):
         await phase.process_message(PhaseTrigger(id="start", phase_id=None))
 
+    assert mgr.read() == {}
+
 
 # ---------------------------------------------------------------------------
 # AgenticPhase.process_message — resolver integration with memory files

ddev/tests/ai/phases/test_base.py

@@ -213,6 +213,7 @@ async def test_extra_checkpoint_cannot_override_reserved_keys(flow_dir, message_
         await phase.process_message(PhaseTrigger(id="start", phase_id=None))
 
     assert mgr.read() == {}
+    assert not mgr.memory_path("p1").exists()
 
 
 async def test_failed_phase_omits_memory_path(flow_dir, message_queue):