Skip to content

armgit / strix

Public Imported from GitHub
0

Open-source AI penetration testing tool to find and fix your app’s vulnerabilities.

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

0xallamf0e254c1fd89
diff --git a/pyproject.toml b/pyproject.toml
index 66e20169..f31a8cbf 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -303,6 +303,15 @@ ignore = [
# CaidoCapability uses agents.tool.Tool at runtime — pydantic Field
# annotations and the cached _CAIDO_TOOLS tuple need it eagerly.
"strix/sandbox/caido_capability.py" = ["TC002"]
+# Agent factory: agents.tool.Tool is used at runtime in the _BASE_TOOLS
+# tuple type, not just for annotations.
+"strix/agents/sdk_factory.py" = ["TC002"]
+# Entry point: ``Path`` is used at runtime by the typing of the
+# session_manager call; importing under TYPE_CHECKING would defer
+# resolution past where mypy needs it. ``_build_root_task`` legitimately
+# walks every supported target type — splitting it into per-type
+# helpers would add indirection without simplifying anything.
+"strix/sdk_entry.py" = ["TC003", "PLR0912"]
# Sandbox dispatch helper has many short-circuit error returns (auth fail,
# size cap, decode fail, etc). Each is a distinct, documented failure mode
# the model needs to see verbatim — collapsing them harms readability.
diff --git a/strix/agents/sdk_factory.py b/strix/agents/sdk_factory.py
new file mode 100644
index 00000000..1f622136
--- /dev/null
+++ b/strix/agents/sdk_factory.py
@@ -0,0 +1,221 @@
+"""build_strix_agent — assemble an ``agents.Agent`` for root or child runs.
+
+This is the keystone that links Phase 2's SDK function tools, Phase 3's
+graph tools, Phase 4's CaidoCapability, and the rendered Jinja prompt
+from :mod:`strix.agents.sdk_prompt` into a single ``agents.Agent``
+instance ready for ``Runner.run``.
+
+Two flavors:
+
+- **Root** (``is_root=True``): the top-level scan agent. Carries
+ ``finish_scan`` (terminates the scan), no ``agent_finish`` (that's
+ for subagents). ``tool_use_behavior`` stops on ``finish_scan`` so
+ the model can't accidentally keep talking after marking the scan
+ complete.
+
+- **Child** (``is_root=False``): subagents spawned by the
+ ``create_agent`` graph tool. Carries ``agent_finish``, no
+ ``finish_scan``. ``tool_use_behavior`` stops on ``agent_finish``
+ (C4 — without this, the SDK loop would keep going to ``max_turns``
+ even after the child reported back to its parent).
+
+Caido tools come from ``CaidoCapability.tools()`` automatically via
+the SDK's capability merge — we don't include them here. Skills are
+injected via the prompt; the model can also load more at runtime via
+the ``load_skill`` tool.
+
+References:
+ - PLAYBOOK.md §4.3 (graph tool wiring)
+ - AUDIT.md §2.4 (C4 — stop_at_tool_names is required for subagents)
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from agents import Agent
+from agents.agent import StopAtTools
+from agents.tool import Tool
+
+from strix.agents.sdk_prompt import render_system_prompt
+from strix.tools.agents_graph.agents_graph_sdk_tools import (
+ agent_finish,
+ agent_status,
+ create_agent,
+ send_message_to_agent,
+ view_agent_graph,
+ wait_for_message,
+)
+from strix.tools.browser.browser_sdk_tool import browser_action
+from strix.tools.file_edit.file_edit_sdk_tools import (
+ list_files,
+ search_files,
+ str_replace_editor,
+)
+from strix.tools.finish.finish_sdk_tool import finish_scan
+from strix.tools.load_skill.load_skill_sdk_tool import load_skill
+from strix.tools.notes.notes_sdk_tools import (
+ create_note,
+ delete_note,
+ get_note,
+ list_notes,
+ update_note,
+)
+from strix.tools.python.python_sdk_tool import python_action
+from strix.tools.reporting.reporting_sdk_tools import create_vulnerability_report
+from strix.tools.terminal.terminal_sdk_tool import terminal_execute
+from strix.tools.thinking.thinking_sdk_tools import think
+from strix.tools.todo.todo_sdk_tools import (
+ create_todo,
+ delete_todo,
+ list_todos,
+ mark_todo_done,
+ mark_todo_pending,
+ update_todo,
+)
+from strix.tools.web_search.web_search_sdk_tool import web_search
+
+
+logger = logging.getLogger(__name__)
+
+
+# Tools every Strix agent has, root or child. The Caido proxy tools
+# (list_requests, view_request, send_request, ...) are NOT here —
+# CaidoCapability.tools() returns them and the SDK merges them in.
+_BASE_TOOLS: tuple[Tool, ...] = (
+ # Thinking + planning
+ think,
+ # Per-agent todos
+ create_todo,
+ list_todos,
+ update_todo,
+ mark_todo_done,
+ mark_todo_pending,
+ delete_todo,
+ # Shared notes (per-run JSONL store)
+ create_note,
+ list_notes,
+ get_note,
+ update_note,
+ delete_note,
+ # Web search (only registered if PERPLEXITY_API_KEY is set; the
+ # tool itself returns a structured error when not configured, so
+ # always exposing it is safe)
+ web_search,
+ # File edit (sandbox-bound)
+ str_replace_editor,
+ list_files,
+ search_files,
+ # Reporting
+ create_vulnerability_report,
+ # Skill loading
+ load_skill,
+ # Sandbox primitives
+ browser_action,
+ terminal_execute,
+ python_action,
+ # Multi-agent graph tools (the bus is in ctx.context)
+ view_agent_graph,
+ agent_status,
+ send_message_to_agent,
+ wait_for_message,
+ create_agent,
+)
+
+
+def build_strix_agent(
+ *,
+ name: str = "strix",
+ skills: list[str] | None = None,
+ is_root: bool,
+ scan_mode: str = "deep",
+ is_whitebox: bool = False,
+ interactive: bool = False,
+ system_prompt_context: dict[str, Any] | None = None,
+) -> Agent[Any]:
+ """Build an ``agents.Agent`` configured for either root or child use.
+
+ Args:
+ name: Agent name. Surfaces in traces and the bus's ``names`` map.
+ Defaults to ``"strix"`` for the root; create_agent passes
+ distinct names per child.
+ skills: Skills to preload into the system prompt. The agent can
+ also load more at runtime via the ``load_skill`` tool.
+ is_root: Selects the tool list and ``tool_use_behavior``.
+ Root carries ``finish_scan`` and stops there; child carries
+ ``agent_finish`` and stops there.
+ scan_mode: ``"deep"`` etc.; routes the scan-mode skill section
+ of the prompt template.
+ is_whitebox: Whitebox source-aware mode toggle. Adds two extra
+ skills to the prompt and gates whitebox-only behavior in
+ the create_agent / wiki integration.
+ interactive: Renders the interactive-mode communication block
+ in the system prompt.
+ system_prompt_context: Free-form dict the prompt template
+ renders into the ``system_prompt_context`` variable —
+ today carries the scan scope / authorization block.
+
+ Returns the ``Agent`` instance with ``model=None`` so the
+ ``RunConfig.model`` (built by ``make_run_config``) drives provider
+ selection. ``agents.Agent`` is generic on context type; we let
+ the caller's ``Runner.run(context=...)`` typing determine that.
+ """
+ instructions = render_system_prompt(
+ skills=skills,
+ scan_mode=scan_mode,
+ is_whitebox=is_whitebox,
+ interactive=interactive,
+ system_prompt_context=system_prompt_context,
+ )
+
+ # Tool list + termination tool depend on is_root. The tuple-then-
+ # list dance keeps _BASE_TOOLS immutable so concurrent agent builds
+ # can't accidentally mutate each other's tool list.
+ if is_root:
+ tools: list[Tool] = [*_BASE_TOOLS, finish_scan]
+ stop_at = ("finish_scan",)
+ else:
+ tools = [*_BASE_TOOLS, agent_finish]
+ stop_at = ("agent_finish",)
+
+ return Agent(
+ name=name,
+ instructions=instructions,
+ tools=tools,
+ tool_use_behavior=StopAtTools(stop_at_tool_names=list(stop_at)),
+ # model=None so ``RunConfig.model`` (e.g. ``strix/claude-sonnet-4.6``)
+ # routes through MultiProvider rather than the SDK's default.
+ model=None,
+ )
+
+
+def make_child_factory(
+ *,
+ scan_mode: str = "deep",
+ is_whitebox: bool = False,
+ interactive: bool = False,
+ system_prompt_context: dict[str, Any] | None = None,
+) -> Any:
+ """Return a callable suitable for ``ctx.context['agent_factory']``.
+
+ The Phase 3 ``create_agent`` graph tool reads
+ ``ctx.context['agent_factory']`` and calls it with ``name=`` and
+ ``skills=`` to build a child Agent. We snapshot the run-level
+ arguments (scan_mode, is_whitebox, etc.) into a closure so each
+ child inherits the right scan-level configuration without the
+ create_agent tool having to know about them.
+ """
+
+ def _factory(*, name: str, skills: list[str]) -> Agent[Any]:
+ return build_strix_agent(
+ name=name,
+ skills=skills,
+ is_root=False,
+ scan_mode=scan_mode,
+ is_whitebox=is_whitebox,
+ interactive=interactive,
+ system_prompt_context=system_prompt_context,
+ )
+
+ return _factory
diff --git a/strix/agents/sdk_prompt.py b/strix/agents/sdk_prompt.py
new file mode 100644
index 00000000..f77e964c
--- /dev/null
+++ b/strix/agents/sdk_prompt.py
@@ -0,0 +1,130 @@
+"""Standalone Jinja-based system-prompt renderer for SDK agents.
+
+The legacy ``LLM._load_system_prompt`` couples prompt rendering to the
+LLM client class. The SDK migration owns the model client through
+``MultiProvider`` instead, so we extract the rendering logic into a
+plain function that the SDK agent factory can call without pulling in
+the legacy ``LLM`` instance.
+
+Reuses the existing Jinja template at
+``strix/agents/StrixAgent/system_prompt.jinja`` (508 lines, expanding
+into the multi-section prompt with skills, tools, scan modes, etc.) so
+behavior parity is preserved verbatim — only the call site changes.
+
+References:
+ - HARNESS_WIKI.md §4.1 (system prompt assembly)
+ - PLAYBOOK.md §4 (per-tool migration contracts)
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from jinja2 import Environment, FileSystemLoader, select_autoescape
+
+from strix.skills import load_skills
+from strix.tools import get_tools_prompt
+from strix.utils.resource_paths import get_strix_resource_path
+
+
+logger = logging.getLogger(__name__)
+
+
+# Hard-coded to the StrixAgent template since it's the only agent type
+# under the SDK migration. The legacy harness supported multiple agent
+# names but in practice only StrixAgent ships.
+_AGENT_NAME = "StrixAgent"
+
+
+def _resolve_skills(
+ *,
+ requested: list[str] | None,
+ scan_mode: str = "deep",
+ is_whitebox: bool = False,
+) -> list[str]:
+ """Build the deduped, ordered skills list for the prompt render.
+
+ Mirrors :py:meth:`LLM._get_skills_to_load` exactly so the rendered
+ prompt is byte-identical to the legacy path:
+
+ 1. Whatever the caller asked for, in order.
+ 2. ``scan_modes/<mode>`` (always).
+ 3. Whitebox-specific skills if applicable.
+ """
+ ordered: list[str] = list(requested or [])
+ ordered.append(f"scan_modes/{scan_mode}")
+ if is_whitebox:
+ ordered.append("coordination/source_aware_whitebox")
+ ordered.append("custom/source_aware_sast")
+
+ deduped: list[str] = []
+ seen: set[str] = set()
+ for skill in ordered:
+ if skill and skill not in seen:
+ deduped.append(skill)
+ seen.add(skill)
+ return deduped
+
+
+def render_system_prompt(
+ *,
+ skills: list[str] | None = None,
+ scan_mode: str = "deep",
+ is_whitebox: bool = False,
+ interactive: bool = False,
+ system_prompt_context: dict[str, Any] | None = None,
+) -> str:
+ """Render the StrixAgent system prompt.
+
+ Args:
+ skills: Skills the caller wants preloaded into the prompt
+ context (the agent can also load more at runtime via the
+ ``load_skill`` tool).
+ scan_mode: ``"deep" | "fast" | ...``. Maps to ``scan_modes/<mode>``
+ skill.
+ is_whitebox: When True, the source-aware whitebox skill stack
+ is loaded too.
+ interactive: When True, the prompt renders the interactive-mode
+ communication rules block.
+ system_prompt_context: Free-form dict that the template's
+ ``system_prompt_context`` variable receives — used today for
+ the scan-scope authorization block from
+ :py:meth:`StrixAgent._build_system_scope_context`.
+
+ Returns the rendered prompt string. If anything goes wrong (template
+ missing, render failure), returns an empty string and logs — same
+ fail-soft posture as the legacy method, because a missing prompt is
+ survivable but a hard failure during agent construction is not.
+ """
+ try:
+ prompt_dir = get_strix_resource_path("agents", _AGENT_NAME)
+ skills_dir = get_strix_resource_path("skills")
+ env = Environment(
+ loader=FileSystemLoader([prompt_dir, skills_dir]),
+ autoescape=select_autoescape(
+ enabled_extensions=(),
+ default_for_string=False,
+ ),
+ )
+
+ skills_to_load = _resolve_skills(
+ requested=skills,
+ scan_mode=scan_mode,
+ is_whitebox=is_whitebox,
+ )
+ skill_content = load_skills(skills_to_load)
+ env.globals["get_skill"] = lambda name: skill_content.get(name, "")
+
+ rendered = env.get_template("system_prompt.jinja").render(
+ get_tools_prompt=get_tools_prompt,
+ loaded_skill_names=list(skill_content.keys()),
+ interactive=interactive,
+ system_prompt_context=system_prompt_context or {},
+ **skill_content,
+ )
+ except Exception:
+ logger.exception("render_system_prompt failed; returning empty prompt")
+ return ""
+ else:
+ return str(rendered)
diff --git a/strix/sdk_entry.py b/strix/sdk_entry.py
new file mode 100644
index 00000000..09673860
--- /dev/null
+++ b/strix/sdk_entry.py
@@ -0,0 +1,282 @@
+"""Top-level SDK scan entry point.
+
+Replaces the legacy ``strix.cli.main → StrixAgent.execute_scan``
+pipeline with the SDK-native equivalent:
+
+1. Build the per-scan ``AgentMessageBus``.
+2. Bring up (or reuse) a sandbox session for ``scan_id`` via the
+ :mod:`strix.sandbox.session_manager`.
+3. Build the root ``Agent`` via :func:`build_strix_agent` and a
+ matching child factory via :func:`make_child_factory`.
+4. Build the root context dict (bus + sandbox bundle + agent_factory).
+5. Register the root in the bus.
+6. Build the ``RunConfig`` via the factory.
+7. Call ``Runner.run(...)`` and surface the result.
+8. ``finally`` cleanup the sandbox session.
+
+Phase 5 lands the wiring; the streaming accumulator + TUI integration
+land in Phase 5b. The entry point is intentionally not wired to the
+CLI yet — that's a follow-up under ``STRIX_USE_SDK_HARNESS=1`` (see
+PLAYBOOK §7.1 cutover plan).
+
+References:
+ - PLAYBOOK.md §3.3 (session manager), §4.3 (graph tools), §7.1
+ - AUDIT_R3.md C9 (cancel_descendants on cleanup)
+"""
+
+from __future__ import annotations
+
+import logging
+import uuid
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from agents import Runner
+
+from strix.agents.sdk_factory import build_strix_agent, make_child_factory
+from strix.orchestration.bus import AgentMessageBus
+from strix.orchestration.hooks import StrixOrchestrationHooks
+from strix.run_config_factory import (
+ STRIX_DEFAULT_MAX_TURNS,
+ make_agent_context,
+ make_run_config,
+)
+from strix.sandbox import session_manager
+
+
+if TYPE_CHECKING:
+ from agents.result import RunResult
+
+
+logger = logging.getLogger(__name__)
+
+
+def _build_root_task(scan_config: dict[str, Any]) -> str:
+ """Format the user-facing task for the root agent.
+
+ Mirrors :py:meth:`StrixAgent.execute_scan` (legacy) — collects each
+ target type into a labelled section, appends diff-scope context if
+ active, and tacks on user_instructions. The structured shape is
+ important for prompt parity: the system prompt template references
+ these section headers.
+ """
+ targets = scan_config.get("targets", []) or []
+ diff_scope = scan_config.get("diff_scope") or {}
+ user_instructions = scan_config.get("user_instructions", "") or ""
+
+ repos: list[str] = []
+ locals_: list[str] = []
+ urls: list[str] = []
+ ips: list[str] = []
+
+ for target in targets:
+ ttype = target.get("type")
+ details = target.get("details") or {}
+ workspace_subdir = details.get("workspace_subdir")
+ workspace_path = f"/workspace/{workspace_subdir}" if workspace_subdir else "/workspace"
+
+ if ttype == "repository":
+ url = details.get("target_repo", "")
+ cloned = details.get("cloned_repo_path")
+ repos.append(
+ f"- {url} (available at: {workspace_path})" if cloned else f"- {url}",
+ )
+ elif ttype == "local_code":
+ path = details.get("target_path", "unknown")
+ locals_.append(f"- {path} (available at: {workspace_path})")
+ elif ttype == "web_application":
+ urls.append(f"- {details.get('target_url', '')}")
+ elif ttype == "ip_address":
+ ips.append(f"- {details.get('target_ip', '')}")
+
+ parts: list[str] = []
+ if repos:
+ parts.append("\n\nRepositories:")
+ parts.extend(repos)
+ if locals_:
+ parts.append("\n\nLocal Codebases:")
+ parts.extend(locals_)
+ if urls:
+ parts.append("\n\nURLs:")
+ parts.extend(urls)
+ if ips:
+ parts.append("\n\nIP Addresses:")
+ parts.extend(ips)
+
+ if diff_scope.get("active"):
+ parts.append("\n\nScope Constraints:")
+ parts.append(
+ "- Pull request diff-scope mode is active. Prioritize changed files "
+ "and use other files only for context.",
+ )
+ for repo_scope in diff_scope.get("repos", []) or []:
+ label = (
+ repo_scope.get("workspace_subdir") or repo_scope.get("source_path") or "repository"
+ )
+ changed = repo_scope.get("analyzable_files_count", 0)
+ deleted = repo_scope.get("deleted_files_count", 0)
+ parts.append(f"- {label}: {changed} changed file(s) in primary scope")
+ if deleted:
+ parts.append(f"- {label}: {deleted} deleted file(s) are context-only")
+
+ task = " ".join(parts)
+ if user_instructions:
+ task = f"{task}\n\nSpecial instructions: {user_instructions}"
+ return task
+
+
+def _build_scope_context(scan_config: dict[str, Any]) -> dict[str, Any]:
+ """Produce the system_prompt_context block used by the prompt template.
+
+ Same shape as the legacy
+ :py:meth:`StrixAgent._build_system_scope_context` so the prompt
+ template's ``system_prompt_context.authorized_targets`` lookups
+ stay byte-identical.
+ """
+ authorized: list[dict[str, str]] = []
+ for target in scan_config.get("targets", []) or []:
+ ttype = target.get("type", "unknown")
+ details = target.get("details") or {}
+
+ if ttype == "repository":
+ value = details.get("target_repo", "")
+ elif ttype == "local_code":
+ value = details.get("target_path", "")
+ elif ttype == "web_application":
+ value = details.get("target_url", "")
+ elif ttype == "ip_address":
+ value = details.get("target_ip", "")
+ else:
+ value = target.get("original", "")
+
+ workspace_subdir = details.get("workspace_subdir")
+ workspace_path = f"/workspace/{workspace_subdir}" if workspace_subdir else ""
+ authorized.append(
+ {"type": ttype, "value": value, "workspace_path": workspace_path},
+ )
+
+ return {
+ "scope_source": "system_scan_config",
+ "authorization_source": "strix_platform_verified_targets",
+ "authorized_targets": authorized,
+ "user_instructions_do_not_expand_scope": True,
+ }
+
+
+async def run_strix_scan(
+ *,
+ scan_config: dict[str, Any],
+ scan_id: str | None = None,
+ image: str,
+ sources_path: Path,
+ tracer: Any | None = None,
+ interactive: bool = False,
+ max_turns: int = STRIX_DEFAULT_MAX_TURNS,
+ cleanup_on_exit: bool = True,
+) -> RunResult:
+ """Run one Strix scan end-to-end against a freshly-prepared sandbox.
+
+ Args:
+ scan_config: Same shape the legacy ``StrixAgent.execute_scan``
+ takes (targets, user_instructions, diff_scope, scan_mode,
+ is_whitebox, skills).
+ scan_id: Used to key the sandbox session cache. Auto-generated
+ if omitted — callers that want resume-after-crash semantics
+ should pass a stable id.
+ image: Docker image tag for the sandbox (e.g.
+ ``"strix-sandbox:0.1.13"``).
+ sources_path: Host directory mounted into ``/workspace/sources``.
+ tracer: Optional Strix tracer. Stored in context for the
+ telemetry hook chain. Pass ``None`` for unit tests.
+ interactive: Renders the interactive-mode prompt block on the
+ root agent.
+ max_turns: Cap on root-agent LLM turns. Mirrors legacy
+ ``AgentState.max_iterations`` (300).
+ cleanup_on_exit: When True (default), tears down the sandbox
+ session in a ``finally``. Set to False for resume scenarios
+ where the caller wants to preserve the container.
+
+ Returns the SDK ``RunResult`` from ``Runner.run``. Raises if the
+ sandbox bring-up fails or the run itself raises.
+ """
+ if scan_id is None:
+ scan_id = f"scan-{uuid.uuid4().hex[:8]}"
+ logger.info("Starting Strix scan %s", scan_id)
+
+ bus = AgentMessageBus()
+ root_id = uuid.uuid4().hex[:8]
+
+ bundle = await session_manager.create_or_reuse(
+ scan_id,
+ image=image,
+ sources_path=sources_path,
+ )
+
+ try:
+ scan_mode = str(scan_config.get("scan_mode") or "deep")
+ is_whitebox = bool(scan_config.get("is_whitebox", False))
+ skills = list(scan_config.get("skills") or [])
+ diff_scope = scan_config.get("diff_scope") or None
+ run_id = scan_config.get("run_id") or scan_id
+
+ scope_context = _build_scope_context(scan_config)
+
+ root_agent = build_strix_agent(
+ name="strix",
+ skills=skills,
+ is_root=True,
+ scan_mode=scan_mode,
+ is_whitebox=is_whitebox,
+ interactive=interactive,
+ system_prompt_context=scope_context,
+ )
+
+ await bus.register(root_id, "strix", parent_id=None)
+
+ agent_factory = make_child_factory(
+ scan_mode=scan_mode,
+ is_whitebox=is_whitebox,
+ interactive=interactive,
+ system_prompt_context=scope_context,
+ )
+
+ context = make_agent_context(
+ bus=bus,
+ sandbox_session=bundle["session"],
+ sandbox_client=bundle["client"],
+ sandbox_token=bundle["bearer"],
+ tool_server_host_port=bundle["tool_server_host_port"],
+ caido_host_port=bundle["caido_host_port"],
+ agent_id=root_id,
+ agent_name="strix",
+ parent_id=None,
+ tracer=tracer,
+ max_turns=max_turns,
+ is_whitebox=is_whitebox,
+ diff_scope=diff_scope,
+ run_id=run_id,
+ agent_factory=agent_factory,
+ )
+
+ run_config = make_run_config(
+ sandbox_session=bundle["session"],
+ sandbox_client=bundle["client"],
+ )
+
+ task_text = _build_root_task(scan_config)
+ return await Runner.run(
+ root_agent,
+ input=task_text,
+ run_config=run_config,
+ context=context,
+ hooks=StrixOrchestrationHooks(),
+ max_turns=max_turns,
+ )
+ except BaseException:
+ # Cancel any descendant tasks the root spawned before unwinding.
+ # cancel_descendants is idempotent and handles the empty-tree case.
+ await bus.cancel_descendants(root_id)
+ raise
+ finally:
+ if cleanup_on_exit:
+ await session_manager.cleanup(scan_id)
diff --git a/tests/agents/test_sdk_factory.py b/tests/agents/test_sdk_factory.py
new file mode 100644
index 00000000..452dcb9a
--- /dev/null
+++ b/tests/agents/test_sdk_factory.py
@@ -0,0 +1,201 @@
+"""Phase 5 tests for the SDK agent factory + prompt renderer.
+
+These two modules are the keystone wiring between Phases 2-4 and an
+actual ``Runner.run`` invocation. The tests verify:
+
+- The prompt renderer reuses the existing Jinja template (parity with
+ legacy LLM._load_system_prompt) and degrades gracefully when the
+ template isn't available.
+- ``build_strix_agent(is_root=True)`` carries ``finish_scan`` and
+ stops on it; child agents carry ``agent_finish`` and stop on it.
+- ``make_child_factory`` snapshots scan-level config into a closure
+ so each spawned child inherits the right scan_mode / is_whitebox /
+ prompt context without create_agent having to re-derive it.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+from unittest.mock import patch
+
+from agents import Agent
+from agents.tool import FunctionTool
+
+from strix.agents.sdk_factory import build_strix_agent, make_child_factory
+from strix.agents.sdk_prompt import _resolve_skills, render_system_prompt
+
+
+# --- prompt renderer ----------------------------------------------------
+
+
+def test_resolve_skills_deduplicates_and_orders() -> None:
+ out = _resolve_skills(
+ requested=["recon", "xss", "recon"],
+ scan_mode="deep",
+ is_whitebox=False,
+ )
+ assert out == ["recon", "xss", "scan_modes/deep"]
+
+
+def test_resolve_skills_adds_whitebox_pair() -> None:
+ out = _resolve_skills(requested=None, scan_mode="fast", is_whitebox=True)
+ # The whitebox pair sits at the tail; scan_modes goes in the middle
+ # because callers can append more skills after it via the requested arg.
+ assert out == [
+ "scan_modes/fast",
+ "coordination/source_aware_whitebox",
+ "custom/source_aware_sast",
+ ]
+
+
+def test_render_system_prompt_returns_string() -> None:
+ """Smoke: the StrixAgent template is on disk and renders to non-empty."""
+ out = render_system_prompt(skills=[], scan_mode="deep")
+ assert isinstance(out, str)
+ # The first line of the template starts with 'You are Strix'.
+ assert out.startswith("You are Strix")
+
+
+def test_render_system_prompt_swallows_template_errors() -> None:
+ """If the template path can't be resolved, return an empty string
+ (not raise) — agent construction must never blow up on prompt load."""
+ with patch(
+ "strix.agents.sdk_prompt.get_strix_resource_path",
+ side_effect=RuntimeError("missing"),
+ ):
+ out = render_system_prompt(skills=[])
+ assert out == ""
+
+
+# --- factory: shape + tools --------------------------------------------
+
+
+def test_root_agent_carries_finish_scan_and_stops_there() -> None:
+ agent = build_strix_agent(name="strix", is_root=True)
+ assert isinstance(agent, Agent)
+ tool_names = {t.name for t in agent.tools if isinstance(t, FunctionTool)}
+ assert "finish_scan" in tool_names
+ assert "agent_finish" not in tool_names
+ behavior = agent.tool_use_behavior
+ # StopAtTools is a TypedDict at runtime → behavior is a dict.
+ assert isinstance(behavior, dict)
+ assert behavior["stop_at_tool_names"] == ["finish_scan"]
+
+
+def test_child_agent_carries_agent_finish_and_stops_there() -> None:
+ agent = build_strix_agent(name="recon-bot", is_root=False)
+ tool_names = {t.name for t in agent.tools if isinstance(t, FunctionTool)}
+ assert "agent_finish" in tool_names
+ assert "finish_scan" not in tool_names
+ behavior = agent.tool_use_behavior
+ assert isinstance(behavior, dict)
+ assert behavior["stop_at_tool_names"] == ["agent_finish"]
+
+
+def test_root_and_child_share_base_tool_set() -> None:
+ """The base tool set (think/todo/notes/file_edit/web_search/etc) is
+ identical between root and child — only the terminator differs."""
+ root = build_strix_agent(is_root=True)
+ child = build_strix_agent(is_root=False)
+ root_names = {t.name for t in root.tools if isinstance(t, FunctionTool)}
+ child_names = {t.name for t in child.tools if isinstance(t, FunctionTool)}
+ # Drop the terminators and compare.
+ assert root_names - {"finish_scan"} == child_names - {"agent_finish"}
+
+
+def test_agent_includes_graph_and_sandbox_tools() -> None:
+ """The graph + sandbox tool families are required for parity with
+ legacy. Spot-check the ones most likely to be forgotten in a refactor."""
+ agent = build_strix_agent(is_root=True)
+ names = {t.name for t in agent.tools if isinstance(t, FunctionTool)}
+ expected = {
+ "think",
+ "create_todo",
+ "create_note",
+ "web_search",
+ "str_replace_editor",
+ "create_vulnerability_report",
+ "load_skill",
+ "browser_action",
+ "terminal_execute",
+ "python_action",
+ "view_agent_graph",
+ "agent_status",
+ "send_message_to_agent",
+ "wait_for_message",
+ "create_agent",
+ }
+ missing = expected - names
+ assert not missing, f"missing tools: {missing}"
+
+
+def test_agent_does_not_include_caido_tools() -> None:
+ """Caido tools come from CaidoCapability.tools(); the agent doesn't
+ declare them directly to avoid double-registration when the SDK
+ runtime merges capability tools."""
+ agent = build_strix_agent(is_root=True)
+ names = {t.name for t in agent.tools if isinstance(t, FunctionTool)}
+ caido = {
+ "list_requests",
+ "view_request",
+ "send_request",
+ "repeat_request",
+ "scope_rules",
+ "list_sitemap",
+ "view_sitemap_entry",
+ }
+ overlap = names & caido
+ assert overlap == set(), f"unexpected Caido tools in agent.tools: {overlap}"
+
+
+def test_agent_uses_run_config_model() -> None:
+ """``model=None`` so the RunConfig drives the model alias through
+ MultiProvider rather than an SDK default like gpt-4.1."""
+ agent = build_strix_agent(is_root=True)
+ assert agent.model is None
+
+
+def test_agent_instructions_contain_rendered_prompt() -> None:
+ """The factory must wire the rendered prompt into ``instructions``."""
+ agent = build_strix_agent(is_root=True, scan_mode="deep")
+ assert isinstance(agent.instructions, str)
+ assert agent.instructions.startswith("You are Strix")
+
+
+# --- child factory ------------------------------------------------------
+
+
+def test_make_child_factory_returns_callable_that_builds_child() -> None:
+ factory = make_child_factory(scan_mode="deep", is_whitebox=False)
+ assert callable(factory)
+ child = factory(name="sub-1", skills=["recon"])
+ assert isinstance(child, Agent)
+ assert child.name == "sub-1"
+ behavior = child.tool_use_behavior
+ assert isinstance(behavior, dict)
+ assert behavior["stop_at_tool_names"] == ["agent_finish"]
+
+
+def test_make_child_factory_passes_scan_level_config() -> None:
+ """Verify scan_mode + is_whitebox flow into the rendered prompt
+ via the closure rather than the create_agent call site."""
+ captured: dict[str, Any] = {}
+
+ def fake_render(**kwargs: Any) -> str:
+ captured.update(kwargs)
+ return "stub-prompt"
+
+ factory = make_child_factory(
+ scan_mode="fast",
+ is_whitebox=True,
+ interactive=True,
+ system_prompt_context={"scope_source": "test"},
+ )
+ with patch("strix.agents.sdk_factory.render_system_prompt", side_effect=fake_render):
+ factory(name="child", skills=["xss"])
+
+ assert captured["scan_mode"] == "fast"
+ assert captured["is_whitebox"] is True
+ assert captured["interactive"] is True
+ assert captured["system_prompt_context"] == {"scope_source": "test"}
+ assert captured["skills"] == ["xss"]
diff --git a/tests/test_sdk_entry.py b/tests/test_sdk_entry.py
new file mode 100644
index 00000000..c9e383f9
--- /dev/null
+++ b/tests/test_sdk_entry.py
@@ -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 ---------------------------------------------
+
+
+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"])
+
+
+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")
+
+
+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()
+
+
+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-")
+
+
+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