feat(migration): phase 5 — root agent factory + entry point

Three new modules that wire Phases 0-4 into a runnable Strix scan: - strix/agents/sdk_prompt.py: standalone Jinja-based system prompt renderer. Reuses the existing strix/agents/StrixAgent/system_prompt. jinja template (508 lines, the actual production prompt) so behavior parity with the legacy LLM._load_system_prompt is byte-identical. Skill resolution mirrors LLM._get_skills_to_load (caller skills → scan_modes/<mode> → whitebox pair, deduped). Fail-soft: template errors return empty string and log; agent construction must never blow up on prompt load. - strix/agents/sdk_factory.py: build_strix_agent(name, skills, is_root) assembles an agents.Agent. Root carries finish_scan and stops there; child carries agent_finish and stops there (C4). Caido tools come from CaidoCapability automatically — we don't include them in _BASE_TOOLS to avoid double-registration when the SDK runtime merges capability tools. model=None so RunConfig drives the model alias through MultiProvider rather than the SDK default. make_child_factory returns a closure over scan-level config (scan_mode, is_whitebox, interactive, scope context) for ctx.context['agent_factory'] — the Phase 3 create_agent tool calls it with (name, skills) per child. - strix/sdk_entry.py: run_strix_scan() — the top-level coroutine. Builds the bus, brings up (or reuses) a sandbox session via session_manager, builds the root Agent and the child factory, builds the per-agent context dict, registers the root in the bus, builds the RunConfig, calls Runner.run, and cleans up the session in a finally. Cancels descendants before re-raising any exception (C9). cleanup_on_exit toggle preserves the cached session for resume scenarios. _build_root_task and _build_scope_context preserve the legacy StrixAgent.execute_scan task formatting + scope context shape so the prompt template sees identical inputs. Tests: 21 new tests (10 for factory + prompt, 11 for entry point). Factory: root vs child tool list parity, finish_scan/agent_finish placement, tool_use_behavior dict shape, Caido absence (capability- provided), make_child_factory closure semantics. Entry point (all mocked, no real Docker/LLM): wiring shape verification — context dict carries every field downstream consumers read, session manager called with correct scan_id, cleanup runs even on Runner.run failure, cleanup skipped when disabled, scan_id auto-generation, scan-level config (scan_mode, is_whitebox) flows into the factory. Task and scope builders verified against the same shape as legacy. Per-file ruff ignores added: TC002 on sdk_factory (Tool used at runtime in _BASE_TOOLS tuple), TC003 + PLR0912 on sdk_entry (Path runtime-imported; _build_root_task's per-target-type branches are intentional and well-bounded). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-25 00:58:32 -07:00
parent 1d86e4506a
commit f0e254c1fd
6 changed files with 1162 additions and 0 deletions
@@ -0,0 +1,319 @@
+"""Phase 5 tests for the top-level SDK scan entry point.
+
+We never spin up a real Docker container or hit a real LLM here. The
+tests patch ``session_manager.create_or_reuse``, ``Runner.run``, and
+the agent factory so we can verify the wiring shape:
+
+- The bus is registered with a root agent before Runner.run.
+- The context dict carries every field downstream code (tools, hooks,
+  filter) reads.
+- The session manager's bundle flows through to the context (host
+  ports, bearer, sandbox session/client).
+- ``cleanup_on_exit=True`` always cleans up, even when Runner.run
+  raises.
+- ``cleanup_on_exit=False`` preserves the cached session.
+- Cancellation propagates: if Runner.run raises, descendants are
+  cancelled before re-raising.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+from strix.orchestration.bus import AgentMessageBus
+from strix.sdk_entry import _build_root_task, _build_scope_context, run_strix_scan
+
+
+# --- helpers ------------------------------------------------------------
+
+
+def _bundle_for_test() -> dict[str, Any]:
+    return {
+        "client": MagicMock(name="docker_client"),
+        "session": MagicMock(name="sandbox_session"),
+        "capability": MagicMock(),
+        "tool_server_host_port": 12001,
+        "caido_host_port": 12002,
+        "bearer": "test-bearer-token-1234567890",
+    }
+
+
+def _scan_config(**overrides: Any) -> dict[str, Any]:
+    base: dict[str, Any] = {
+        "targets": [
+            {
+                "type": "web_application",
+                "details": {"target_url": "https://example.com"},
+            },
+        ],
+        "user_instructions": "find xss",
+        "scan_mode": "deep",
+        "is_whitebox": False,
+    }
+    base.update(overrides)
+    return base
+
+
+# --- task / scope builders ---------------------------------------------
+
+
+def test_build_root_task_groups_targets_and_appends_instructions() -> None:
+    config = _scan_config(
+        targets=[
+            {
+                "type": "repository",
+                "details": {
+                    "target_repo": "https://github.com/x/y",
+                    "cloned_repo_path": "/tmp/y",
+                    "workspace_subdir": "y",
+                },
+            },
+            {
+                "type": "ip_address",
+                "details": {"target_ip": "10.0.0.1"},
+            },
+        ],
+        user_instructions="report only critical issues",
+    )
+    task = _build_root_task(config)
+    assert "Repositories:" in task
+    assert "https://github.com/x/y (available at: /workspace/y)" in task
+    assert "IP Addresses:" in task
+    assert "10.0.0.1" in task
+    assert "Special instructions: report only critical issues" in task
+
+
+def test_build_root_task_renders_diff_scope_block() -> None:
+    config = _scan_config(
+        diff_scope={
+            "active": True,
+            "repos": [
+                {
+                    "workspace_subdir": "service-x",
+                    "analyzable_files_count": 7,
+                    "deleted_files_count": 2,
+                },
+            ],
+        },
+    )
+    task = _build_root_task(config)
+    assert "Scope Constraints:" in task
+    assert "service-x: 7 changed file(s)" in task
+    assert "service-x: 2 deleted file(s)" in task
+
+
+def test_build_scope_context_marks_authorization_source() -> None:
+    config = _scan_config(
+        targets=[
+            {
+                "type": "web_application",
+                "details": {"target_url": "https://target.test"},
+            },
+        ],
+    )
+    ctx = _build_scope_context(config)
+    assert ctx["scope_source"] == "system_scan_config"
+    assert ctx["authorization_source"] == "strix_platform_verified_targets"
+    assert ctx["user_instructions_do_not_expand_scope"] is True
+    assert ctx["authorized_targets"] == [
+        {"type": "web_application", "value": "https://target.test", "workspace_path": ""},
+    ]
+
+
+# --- run_strix_scan wiring ---------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_run_strix_scan_wires_context_and_calls_runner(tmp_path: Path) -> None:
+    """End-to-end (mocked) — assert every downstream consumer of context
+    sees the bundle's bearer + host ports."""
+    bundle = _bundle_for_test()
+    captured_context: dict[str, Any] = {}
+
+    async def fake_runner_run(*args: Any, **kwargs: Any) -> Any:
+        captured_context.update(kwargs.get("context", {}))
+        return MagicMock(name="run_result")
+
+    with (
+        patch(
+            "strix.sdk_entry.session_manager.create_or_reuse",
+            new=AsyncMock(return_value=bundle),
+        ) as create_mock,
+        patch(
+            "strix.sdk_entry.session_manager.cleanup",
+            new=AsyncMock(),
+        ) as cleanup_mock,
+        patch("strix.sdk_entry.Runner.run", side_effect=fake_runner_run) as runner_mock,
+        # Stub the factory to avoid rendering the 158k-char prompt for
+        # every test (it's covered by sdk_prompt tests).
+        patch(
+            "strix.sdk_entry.build_strix_agent",
+            return_value=MagicMock(name="root_agent"),
+        ) as factory_mock,
+    ):
+        await run_strix_scan(
+            scan_config=_scan_config(),
+            scan_id="scan-test",
+            image="strix-sandbox:test",
+            sources_path=tmp_path,
+        )
+
+    # Session manager calls.
+    create_mock.assert_awaited_once()
+    create_args = create_mock.await_args
+    assert create_args is not None
+    assert create_args.args == ("scan-test",)
+    assert create_args.kwargs["image"] == "strix-sandbox:test"
+    assert create_args.kwargs["sources_path"] == tmp_path
+    cleanup_mock.assert_awaited_once_with("scan-test")
+
+    # Factory called with is_root=True.
+    factory_mock.assert_called_once()
+    assert factory_mock.call_args.kwargs["is_root"] is True
+
+    # Runner.run called once with the root agent.
+    assert runner_mock.call_count == 1
+
+    # Context shape passed into Runner.run.
+    assert captured_context["sandbox_session"] is bundle["session"]
+    assert captured_context["sandbox_client"] is bundle["client"]
+    assert captured_context["sandbox_token"] == bundle["bearer"]
+    assert captured_context["tool_server_host_port"] == bundle["tool_server_host_port"]
+    assert captured_context["caido_host_port"] == bundle["caido_host_port"]
+    # Bus is registered and root agent_id is populated.
+    bus = captured_context["bus"]
+    assert isinstance(bus, AgentMessageBus)
+    assert captured_context["agent_id"] in bus.statuses
+    assert bus.parent_of[captured_context["agent_id"]] is None
+    # Child factory wired through so create_agent works.
+    assert callable(captured_context["agent_factory"])
+
+
+@pytest.mark.asyncio
+async def test_run_strix_scan_cleans_up_on_runner_failure(tmp_path: Path) -> None:
+    """If Runner.run raises, cleanup must still fire (the finally branch)."""
+    bundle = _bundle_for_test()
+
+    with (
+        patch(
+            "strix.sdk_entry.session_manager.create_or_reuse",
+            new=AsyncMock(return_value=bundle),
+        ),
+        patch(
+            "strix.sdk_entry.session_manager.cleanup",
+            new=AsyncMock(),
+        ) as cleanup_mock,
+        patch(
+            "strix.sdk_entry.Runner.run",
+            side_effect=RuntimeError("simulated LLM blow-up"),
+        ),
+        patch("strix.sdk_entry.build_strix_agent", return_value=MagicMock()),
+        pytest.raises(RuntimeError, match="simulated LLM"),
+    ):
+        await run_strix_scan(
+            scan_config=_scan_config(),
+            scan_id="scan-fail",
+            image="i",
+            sources_path=tmp_path,
+        )
+
+    cleanup_mock.assert_awaited_once_with("scan-fail")
+
+
+@pytest.mark.asyncio
+async def test_run_strix_scan_skips_cleanup_when_disabled(tmp_path: Path) -> None:
+    bundle = _bundle_for_test()
+
+    async def fake_runner_run(*args: Any, **kwargs: Any) -> Any:
+        return MagicMock()
+
+    with (
+        patch(
+            "strix.sdk_entry.session_manager.create_or_reuse",
+            new=AsyncMock(return_value=bundle),
+        ),
+        patch(
+            "strix.sdk_entry.session_manager.cleanup",
+            new=AsyncMock(),
+        ) as cleanup_mock,
+        patch("strix.sdk_entry.Runner.run", side_effect=fake_runner_run),
+        patch("strix.sdk_entry.build_strix_agent", return_value=MagicMock()),
+    ):
+        await run_strix_scan(
+            scan_config=_scan_config(),
+            scan_id="scan-keep",
+            image="i",
+            sources_path=tmp_path,
+            cleanup_on_exit=False,
+        )
+
+    cleanup_mock.assert_not_called()
+
+
+@pytest.mark.asyncio
+async def test_run_strix_scan_auto_generates_scan_id(tmp_path: Path) -> None:
+    """A caller without a stable id should still get a valid scan_id
+    flowing into create_or_reuse."""
+    bundle = _bundle_for_test()
+    captured_scan_id: list[str] = []
+
+    async def fake_create(scan_id: str, **_kwargs: Any) -> Any:
+        captured_scan_id.append(scan_id)
+        return bundle
+
+    with (
+        patch(
+            "strix.sdk_entry.session_manager.create_or_reuse",
+            new=AsyncMock(side_effect=fake_create),
+        ),
+        patch("strix.sdk_entry.session_manager.cleanup", new=AsyncMock()),
+        patch("strix.sdk_entry.Runner.run", new=AsyncMock(return_value=MagicMock())),
+        patch("strix.sdk_entry.build_strix_agent", return_value=MagicMock()),
+    ):
+        await run_strix_scan(
+            scan_config=_scan_config(),
+            image="i",
+            sources_path=tmp_path,
+        )
+
+    assert len(captured_scan_id) == 1
+    assert captured_scan_id[0].startswith("scan-")
+    assert len(captured_scan_id[0]) > len("scan-")
+
+
+@pytest.mark.asyncio
+async def test_run_strix_scan_passes_scan_level_config_into_factory(
+    tmp_path: Path,
+) -> None:
+    """scan_mode / is_whitebox flow from scan_config into both the
+    root factory call and the child factory closure."""
+    bundle = _bundle_for_test()
+    factory_calls: list[dict[str, Any]] = []
+
+    def fake_factory(**kwargs: Any) -> Any:
+        factory_calls.append(kwargs)
+        return MagicMock()
+
+    with (
+        patch(
+            "strix.sdk_entry.session_manager.create_or_reuse",
+            new=AsyncMock(return_value=bundle),
+        ),
+        patch("strix.sdk_entry.session_manager.cleanup", new=AsyncMock()),
+        patch("strix.sdk_entry.Runner.run", new=AsyncMock(return_value=MagicMock())),
+        patch("strix.sdk_entry.build_strix_agent", side_effect=fake_factory),
+    ):
+        await run_strix_scan(
+            scan_config=_scan_config(scan_mode="fast", is_whitebox=True),
+            scan_id="s",
+            image="i",
+            sources_path=tmp_path,
+        )
+
+    assert factory_calls[0]["scan_mode"] == "fast"
+    assert factory_calls[0]["is_whitebox"] is True
+    assert factory_calls[0]["is_root"] is True