Open-source AI penetration testing tool to find and fix your app’s vulnerabilities.
Python agentsai-hackingai-penetration-testingai-pentestingai-securityartificial-intelligencebug-bountycode-qualityctf-toolscybersecuritycybersecurity-toolsethical-hackinghackingllm-securityoffensive-securitypenetration-testingpentesting-toolsred-teamingsecuritysecurity-automation
feat(budget): budget_policy=pause parks every agent at the limit until the operator resumes
Ahmed Allamd355838ea070
diff --git a/strix/core/agents.py b/strix/core/agents.pyindex 4d3d65cc..095d5fba 100644--- a/strix/core/agents.py+++ b/strix/core/agents.py@@ -24,6 +24,8 @@ logger = logging.getLogger(__name__)Status = Literal["running", "waiting", "completed", "stopped", "crashed", "failed", "budget_paused"]+BudgetPolicy = Literal["stop", "pause"]+TERMINAL_STATUSES: frozenset[str] = frozenset({"completed", "stopped", "crashed", "failed"})# Why an agent parked. The user can message any agent, so this - not the agent's@@ -68,7 +70,10 @@ class AgentCoordinator:self._budget_stopped = Falseself._reserve_stopped = Falseself._budget_paused = False+ self._resume_epoch = 0+ self._budget_policy: BudgetPolicy = "stop"self._extend_budget: Callable[[], None] | None = None+ self._set_budget_limit: Callable[[float | None], None] | None = Nonedef set_snapshot_path(self, path: Path) -> None:self._snapshot_path = path@@ -95,15 +100,89 @@ class AgentCoordinator:def budget_paused(self) -> bool:return self._budget_paused+ @property+ def resume_epoch(self) -> int:+ """Bumped by every ``resume_budget``; an agent parks against the value it read."""+ return self._resume_epoch++ @property+ def budget_policy(self) -> BudgetPolicy:+ return self._budget_policy++ def set_budget_policy(self, policy: BudgetPolicy) -> None:+ self._budget_policy = policy+def set_budget_extender(self, extend: Callable[[], None]) -> None:self._extend_budget = extend+ def set_budget_limit_setter(self, setter: Callable[[float | None], None]) -> None:+ self._set_budget_limit = setter+async def pause_for_budget(self, agent_id: str) -> None:async with self._lock:self._budget_paused = Trueawait self.set_status(agent_id, "budget_paused")+ async def park_for_budget(self, agent_id: str) -> None:+ """Record that ``agent_id`` parked before an LLM call (pause policy)."""+ await self.set_status(agent_id, "budget_paused")++ async def pause_budget(self) -> None:+ """Operator pause: every agent parks before its next LLM call.++ Agents mid-call or mid-tool finish that step first, so their spend still+ lands; nothing is cancelled.+ """+ async with self._lock:+ self._budget_paused = True+ logger.info("scan paused by the operator")+ await self._maybe_snapshot()++ async def resume_budget(self, *, max_budget_usd: float | None = None) -> list[str]:+ """Lift the pause and wake every parked agent; returns the woken agent ids.++ With ``max_budget_usd`` the scan's limit is replaced first (``None`` keeps+ the current one). Agents continue with the LLM call they parked on; no+ message is added to any session. An agent that parks again on its next+ call (the new limit is already spent) is not an error.+ """+ if max_budget_usd is not None and self._set_budget_limit is not None:+ self._set_budget_limit(max_budget_usd)+ async with self._lock:+ self._budget_paused = False+ self._resume_epoch += 1+ woken = [aid for aid, status in self.statuses.items() if status == "budget_paused"]+ for aid in woken:+ self.runtimes.setdefault(aid, AgentRuntime()).wake.set()+ logger.info("scan resumed; woke %d parked agent(s)", len(woken))+ await self._maybe_snapshot()+ return woken++ async def wait_for_budget_resume(self, agent_id: str, *, parked_epoch: int) -> None:+ """Block until a resume newer than ``parked_epoch``, a scan-wide stop, or+ the agent itself being stopped while parked.++ ``parked_epoch`` is the ``resume_epoch`` the agent read when it decided to+ park, so a resume that lands between that decision and this wait is not+ missed. ``agent_id`` is ``running`` again on return unless it was stopped.+ """+ while True:+ async with self._lock:+ runtime = self.runtimes.setdefault(agent_id, AgentRuntime())+ if (+ self._budget_stopped+ or self._resume_epoch != parked_epoch+ or self.statuses.get(agent_id) != "budget_paused"+ ):+ break+ wake = runtime.wake+ wake.clear()+ await wake.wait()+ if not self._budget_stopped and self.statuses.get(agent_id) == "budget_paused":+ await self.set_status(agent_id, "running")+async def resume_from_budget_pause(self, *, exclude: str | None = None) -> None:+ """Legacy interactive resume: extend by the original budget and nudge agents."""async with self._lock:if not self._budget_paused:return@@ -308,7 +387,7 @@ class AgentCoordinator:unknown, or it is terminal and its loop does not park for wake-ups."""from_user = message.get("from") == "user"- if from_user and self._budget_paused:+ if from_user and self._budget_paused and self._budget_policy != "pause":await self.resume_from_budget_pause(exclude=target_agent_id)async with self._lock:if target_agent_id not in self.statuses:diff --git a/strix/core/execution.py b/strix/core/execution.pyindex d5d94eb5..69a5cf87 100644--- a/strix/core/execution.py+++ b/strix/core/execution.py@@ -522,33 +522,51 @@ async def _run_until_lifecycle(await coordinator.set_status(agent_id, "stopped")raise SubagentBudgetReservedError("scan reached the sub-agent budget reserve")- if interactive:- result = await _run_cycle_parked(- agent,- coordinator,- agent_id,- input_data=input_data,- run_config=run_config,- context=context,- max_turns=max_turns,- session=session,- event_sink=event_sink,- hooks=hooks,- )- else:- result = await _run_cycle(- agent,- coordinator,- agent_id,- input_data=input_data,- run_config=run_config,- context=context,- max_turns=max_turns,- session=session,- interactive=False,- event_sink=event_sink,- hooks=hooks,- )+ try:+ if interactive:+ result = await _run_cycle_parked(+ agent,+ coordinator,+ agent_id,+ input_data=input_data,+ run_config=run_config,+ context=context,+ max_turns=max_turns,+ session=session,+ event_sink=event_sink,+ hooks=hooks,+ )+ else:+ result = await _run_cycle(+ agent,+ coordinator,+ agent_id,+ input_data=input_data,+ run_config=run_config,+ context=context,+ max_turns=max_turns,+ session=session,+ interactive=False,+ event_sink=event_sink,+ hooks=hooks,+ )+ except BudgetPausedError as exc:+ if coordinator.budget_policy != "pause":+ raise+ # The agent parked right before an LLM call; everything up to that+ # point is already in its session. Once resumed, the same call goes+ # out with nothing added to the conversation.+ await coordinator.wait_for_budget_resume(agent_id, parked_epoch=exc.resume_epoch)+ if (+ not coordinator.budget_stopped+ and await _agent_status(coordinator, agent_id) != "running"+ ):+ # Stopped while parked (operator stop or a parent's stop_agent).+ await coordinator.reset_recovery(agent_id)+ return result+ if session is not None:+ input_data = []+ continuestatus = await _agent_status(coordinator, agent_id)if status != "running":@@ -759,7 +777,10 @@ async def _run_cycle( # noqa: PLR0912, PLR0915await coordinator.detach_stream(agent_id, stream)except BudgetPausedError as exc:logger.info("agent %s paused at the scan budget limit: %s", agent_id, exc)- await coordinator.pause_for_budget(agent_id)+ if coordinator.budget_policy == "pause":+ await coordinator.park_for_budget(agent_id)+ else:+ await coordinator.pause_for_budget(agent_id)raiseexcept SubagentBudgetReservedError as exc:logger.info("sub-agent %s stopped at the budget reserve: %s", agent_id, exc)diff --git a/strix/core/hooks.py b/strix/core/hooks.pyindex 21400c0b..eae4d7c7 100644--- a/strix/core/hooks.py+++ b/strix/core/hooks.py@@ -8,6 +8,7 @@ from typing import TYPE_CHECKING, Anyfrom agents.lifecycle import RunHooks+from strix.core.agents import BudgetPolicy, coordinator_from_contextfrom strix.report.state import get_global_report_state@@ -22,6 +23,26 @@ logger = logging.getLogger(__name__)LLM_TURN_KEY = "llm_turn"+# ``BudgetPolicy`` decides what happens when the accumulated LLM cost reaches+# ``max_budget_usd``.+#+# ``stop``: the agents are warned as the limit approaches, sub-agents are cut at+# a reserve so the root can write its report, and the scan ends at the limit.+#+# ``pause``: the agents are never told a limit exists. Every agent parks right+# before its next LLM call once the limit is reached (or an operator pauses the+# scan), keeping its session, context and sandbox alive, and continues with that+# same call when the operator raises the limit or resumes.+__all__ = [+ "LLM_TURN_KEY",+ "BudgetExceededError",+ "BudgetPausedError",+ "BudgetPolicy",+ "ReportUsageHooks",+ "SubagentBudgetReservedError",+ "recomputed_budget_flags",+]+_STAGE_LABELS: tuple[str, ...] = ("NOTICE", "URGENT", "CRITICAL")_TURN_WARN_BANDS: tuple[float, ...] = (0.70, 0.85, 0.95)_ROOT_BUDGET_WARN_BANDS: tuple[float, ...] = (0.70, 0.85, 0.95)@@ -38,7 +59,20 @@ class SubagentBudgetReservedError(RuntimeError):class BudgetPausedError(RuntimeError):- """Raised to park one agent when an interactive scan reaches its budget."""+ """Raised to park one agent until the scan budget is raised or the pause lifted.++ ``resume_epoch`` is the coordinator's ``resume_epoch`` at the moment the agent+ decided to park; the agent waits for a resume newer than that.+ """++ def __init__(self, message: str, *, resume_epoch: int = 0) -> None:+ super().__init__(message)+ self.resume_epoch = resume_epoch+++def _validate_budget(max_budget_usd: float | None) -> None:+ if max_budget_usd is not None and (not math.isfinite(max_budget_usd) or max_budget_usd <= 0):+ raise ValueError("max_budget_usd must be a finite number greater than 0")def recomputed_budget_flags(@@ -46,11 +80,12 @@ def recomputed_budget_flags(max_budget_usd: float | None,*,interactive: bool,+ budget_policy: BudgetPolicy = "stop",) -> tuple[bool, bool]:"""Return the (budget_stopped, reserve_stopped) flags a resumed scan should carry."""if max_budget_usd is None:return False, False- if interactive:+ if interactive or budget_policy == "pause":return False, Falsebudget_stopped = cost >= max_budget_usdreserve_stopped = cost >= max_budget_usd * _SUBAGENT_BUDGET_RESERVE@@ -121,18 +156,32 @@ class ReportUsageHooks(RunHooks[dict[str, Any]]):max_budget_usd: float | None = None,max_turns: int | None = None,interactive: bool = False,+ budget_policy: BudgetPolicy = "stop",) -> None:- if max_budget_usd is not None and (- not math.isfinite(max_budget_usd) or max_budget_usd <= 0- ):- raise ValueError("max_budget_usd must be a finite number greater than 0")+ _validate_budget(max_budget_usd)if max_turns is not None and max_turns <= 0:raise ValueError("max_turns must be a positive integer")+ if budget_policy not in ("stop", "pause"):+ raise ValueError(f"unknown budget_policy: {budget_policy!r}")self._model = modelself._max_budget_usd = max_budget_usdself._budget_increment = max_budget_usdself._max_turns = max_turnsself._interactive = interactive+ self._budget_policy: BudgetPolicy = budget_policy++ @property+ def max_budget_usd(self) -> float | None:+ return self._max_budget_usd++ @property+ def budget_policy(self) -> BudgetPolicy:+ return self._budget_policy++ def set_max_budget_usd(self, max_budget_usd: float | None) -> None:+ """Replace the scan's cost limit; ``None`` removes it."""+ _validate_budget(max_budget_usd)+ self._max_budget_usd = max_budget_usddef extend_budget(self) -> None:if self._max_budget_usd is None or self._budget_increment is None:@@ -146,6 +195,8 @@ class ReportUsageHooks(RunHooks[dict[str, Any]]):system_prompt: str | None, # noqa: ARG002input_items: list[TResponseInputItem],) -> None:+ if self._budget_policy == "pause":+ self._pause_if_limited(context)context.context[LLM_TURN_KEY] = int(context.context.get(LLM_TURN_KEY, 0)) + 1try:self._maybe_warn_turns(context, input_items)@@ -153,6 +204,32 @@ class ReportUsageHooks(RunHooks[dict[str, Any]]):except Exception:logger.exception("budget/turn warning injection failed")+ def _pause_if_limited(self, context: RunContextWrapper[dict[str, Any]]) -> None:+ """Park the agent before a paid call when the scan is at its limit or paused.++ Only calls that have already returned are counted, so calls in flight on+ other agents still land and are paid for: ``spent`` may end up above the+ limit, which is expected and never an error under this policy.+ """+ coordinator = coordinator_from_context(context.context)+ epoch = coordinator.resume_epoch if coordinator is not None else 0+ if coordinator is not None and coordinator.budget_paused:+ raise BudgetPausedError(+ "scan paused; waiting for the operator to resume", resume_epoch=epoch+ )+ if self._max_budget_usd is None:+ return+ report_state = get_global_report_state()+ if report_state is None:+ return+ cost = report_state.get_total_llm_cost()+ if cost >= self._max_budget_usd:+ raise BudgetPausedError(+ f"Scan budget of ${self._max_budget_usd:.2f} reached (spent ${cost:.4f}); "+ "pausing until the operator raises the limit",+ resume_epoch=epoch,+ )+def _maybe_warn_turns(self,context: RunContextWrapper[dict[str, Any]],@@ -182,7 +259,7 @@ class ReportUsageHooks(RunHooks[dict[str, Any]]):context: RunContextWrapper[dict[str, Any]],input_items: list[TResponseInputItem],) -> None:- if self._max_budget_usd is None:+ if self._max_budget_usd is None or self._budget_policy == "pause":returnreport_state = get_global_report_state()if report_state is None:@@ -250,6 +327,11 @@ class ReportUsageHooks(RunHooks[dict[str, Any]]):except Exception:logger.exception("failed to record SDK usage for agent %s", agent_id)+ if self._budget_policy == "pause":+ # The finished call is paid for and its tool calls still run for free;+ # the agent parks before its next call, in ``on_llm_start``.+ return+if self._max_budget_usd is not None:cost = report_state.get_total_llm_cost()if cost >= self._max_budget_usd:diff --git a/strix/core/runner.py b/strix/core/runner.pyindex 9420b76e..7fdf2662 100644--- a/strix/core/runner.py+++ b/strix/core/runner.py@@ -26,7 +26,7 @@ from strix.config.models import (uses_chat_completions_tool_schema,)from strix.config.settings import DEFAULT_MAX_TURNS-from strix.core.agents import AgentCoordinator+from strix.core.agents import AgentCoordinator, BudgetPolicyfrom strix.core.execution import (respawn_subagents,run_agent_loop,@@ -189,6 +189,7 @@ async def run_strix_scan(interactive: bool = False,max_turns: int = DEFAULT_MAX_TURNS,max_budget_usd: float | None = None,+ budget_policy: BudgetPolicy = "stop",model: str | None = None,cleanup_on_exit: bool = True,event_sink: StreamEventSink | None = None,@@ -208,6 +209,12 @@ async def run_strix_scan(``extra_system_prompt_context`` is merged into the root agent's scancontext before prompt rendering. Child agents keep the standard scan promptand context.+ ``budget_policy`` decides what happens when the LLM spend reaches+ ``max_budget_usd``: ``"stop"`` warns the agents as the limit approaches and+ ends the scan at it; ``"pause"`` tells the agents nothing and parks every+ agent before its next LLM call until the caller resumes the scan through+ ``coordinator.resume_budget()`` (optionally with a higher limit) or cancels+ it. ``coordinator.pause_budget()`` parks a running scan the same way.``mcp_connection_requests`` supplies the run's MCP connections from anysource: when given, the engine connects those requests; when ``None`` (thecommand-line default) it reads ``~/.strix/mcp-servers.json`` itself. Either@@ -256,9 +263,12 @@ async def run_strix_scan(if not strict_tool_schemas:logger.info("Sending non-strict tool schemas: %s caps strict tools", resolved_model)+ if budget_policy not in ("stop", "pause"):+ raise ValueError(f"unknown budget_policy: {budget_policy!r}")if coordinator is None:coordinator = AgentCoordinator()coordinator.set_snapshot_path(agents_path)+ coordinator.set_budget_policy(budget_policy)from strix.tools.coverage.tools import hydrate_coverage_from_diskfrom strix.tools.notes.tools import hydrate_notes_from_disk@@ -289,11 +299,17 @@ async def run_strix_scan(report_state.get_total_llm_cost(),max_budget_usd,interactive=interactive,+ budget_policy=budget_policy,)+ # Under the pause policy the hooks re-park at the first call if the+ # spend is still at the limit, so a restored pause flag would only+ # hold agents back after the limit was raised.await coordinator.reset_budget_stops(budget_stopped=budget_stopped,reserve_stopped=reserve_stopped,- budget_paused=interactive and coordinator.budget_paused,+ budget_paused=(+ interactive and budget_policy != "pause" and coordinator.budget_paused+ ),)for aid, parent in coordinator.parent_of.items():if parent is None:@@ -372,8 +388,10 @@ async def run_strix_scan(max_budget_usd=max_budget_usd,max_turns=max_turns,interactive=interactive,+ budget_policy=budget_policy,)- if interactive:+ coordinator.set_budget_limit_setter(hooks.set_max_budget_usd)+ if interactive and budget_policy != "pause":coordinator.set_budget_extender(hooks.extend_budget)scope_context = build_scope_context(scan_config)diff --git a/strix/tools/agents_graph/tools.py b/strix/tools/agents_graph/tools.pyindex da05bb1e..2807b1c9 100644--- a/strix/tools/agents_graph/tools.py+++ b/strix/tools/agents_graph/tools.py@@ -19,7 +19,7 @@ from strix.report.state import get_global_report_statefrom strix.skills import validate_requested_skills-_ACTIVE_STATUSES: frozenset[str] = frozenset({"running", "waiting"})+_ACTIVE_STATUSES: frozenset[str] = frozenset({"running", "waiting", "budget_paused"})logger = logging.getLogger(__name__)@@ -816,7 +816,7 @@ async def stop_agent("success": False,"error": (f"Agent {target_agent_id} is already '{current_status}'; "- "stop_agent only acts on running/waiting agents — use "+ "stop_agent only acts on running/waiting/paused agents — use ""view_agent_graph to find still-active descendants and ""stop them individually, or send_message_to_agent if you ""want to wake this one with new instructions"diff --git a/tests/test_budget_pause_policy.py b/tests/test_budget_pause_policy.pynew file mode 100644index 00000000..302b23ba--- /dev/null+++ b/tests/test_budget_pause_policy.py@@ -0,0 +1,510 @@+"""``budget_policy="pause"``: agents park before a paid call and never hear about budgets."""++from __future__ import annotations++import asyncio+from typing import TYPE_CHECKING, Any+from unittest.mock import MagicMock, patch++import pytest++from strix.core import execution+from strix.core.agents import AgentCoordinator+from strix.core.execution import _start_child_runner, run_agent_loop+from strix.core.hooks import (+ BudgetExceededError,+ BudgetPausedError,+ ReportUsageHooks,+ recomputed_budget_flags,+)+from strix.core.sessions import open_agent_session+++if TYPE_CHECKING:+ from collections.abc import AsyncIterator, Callable+ from pathlib import Path+++COST_PER_CALL = 1.0+_CALL_LATENCY_S = 0.005+++class _FakeLedger:+ def __init__(self) -> None:+ self.cost = 0.0+ self.calls: list[str] = []+ self.remaining: dict[str, int] = {}+ self.warned_inputs: list[list[Any]] = []+ self.gate: asyncio.Event | None = None+ self.in_flight = 0++ def record_sdk_usage(self, **_kwargs: Any) -> None:+ return++ def get_total_llm_cost(self) -> float:+ return self.cost+++class _FakeStream:+ """One ``Runner.run_streamed`` call: several LLM turns, each guarded by the hooks.++ Mirrors the SDK's ordering: ``on_llm_start`` runs before the paid request,+ ``on_llm_end`` after it. A ``BudgetPausedError`` from ``on_llm_start`` ends+ the stream without spending, exactly like the SDK surfacing a hook error.+ """++ def __init__(+ self,+ *,+ ledger: _FakeLedger,+ hooks: ReportUsageHooks,+ context: dict[str, Any],+ agent: Any,+ coordinator: AgentCoordinator,+ ) -> None:+ self._ledger = ledger+ self._hooks = hooks+ self._context = context+ self._agent = agent+ self._coordinator = coordinator+ self.run_loop_exception: BaseException | None = None+ self.final_output = None++ async def stream_events(self) -> AsyncIterator[Any]:+ agent_id = str(self._context.get("agent_id"))+ ctx_wrapper = MagicMock()+ ctx_wrapper.context = self._context+ while self._ledger.remaining.get(agent_id, 0) > 0:+ input_items: list[Any] = []+ try:+ await self._hooks.on_llm_start(ctx_wrapper, self._agent, None, input_items)+ except BudgetPausedError as exc:+ self.run_loop_exception = exc+ return+ self._ledger.warned_inputs.append(input_items)+ if self._ledger.gate is not None:+ self._ledger.in_flight += 1+ await self._ledger.gate.wait()+ self._ledger.in_flight -= 1+ self._ledger.cost += COST_PER_CALL+ self._ledger.calls.append(agent_id)+ self._ledger.remaining[agent_id] -= 1+ await self._hooks.on_llm_end(ctx_wrapper, self._agent, MagicMock())+ await asyncio.sleep(_CALL_LATENCY_S)+ if self._coordinator.statuses.get(agent_id) == "running":+ await self._coordinator.set_status(agent_id, "completed")+ items: tuple[Any, ...] = ()+ for item in items:+ yield item++ def cancel(self, mode: str = "immediate") -> None: # noqa: ARG002+ return+++def _fake_runner(ledger: _FakeLedger, coordinator: AgentCoordinator) -> Any:+ class _FakeRunner:+ @staticmethod+ def run_streamed(+ agent: Any,+ input: Any, # noqa: A002, ARG004+ *,+ run_config: Any, # noqa: ARG004+ context: dict[str, Any],+ max_turns: int, # noqa: ARG004+ session: Any, # noqa: ARG004+ hooks: ReportUsageHooks,+ ) -> _FakeStream:+ return _FakeStream(+ ledger=ledger,+ hooks=hooks,+ context=context,+ agent=agent,+ coordinator=coordinator,+ )++ return _FakeRunner+++async def _noop_compact(*_args: Any, **_kwargs: Any) -> bool:+ return False+++async def _wait_until(predicate: Callable[[], bool], *, timeout: float = 5.0) -> None:+ async def _poll() -> None:+ while not predicate():+ await asyncio.sleep(0.001)++ await asyncio.wait_for(_poll(), timeout=timeout)+++def _all_parked(coordinator: AgentCoordinator, *agent_ids: str) -> bool:+ return all(coordinator.statuses.get(aid) == "budget_paused" for aid in agent_ids)+++class _Scan:+ """Root + children driven through the real non-interactive loops."""++ def __init__(+ self,+ tmp_path: Path,+ monkeypatch: pytest.MonkeyPatch,+ *,+ max_budget_usd: float | None,+ ) -> None:+ self.ledger = _FakeLedger()+ self.hooks = ReportUsageHooks(+ model="test-model", max_budget_usd=max_budget_usd, budget_policy="pause"+ )+ self.coordinator = AgentCoordinator()+ self.coordinator.set_budget_policy("pause")+ self.coordinator.set_budget_limit_setter(self.hooks.set_max_budget_usd)+ monkeypatch.setattr(execution, "Runner", _fake_runner(self.ledger, self.coordinator))+ monkeypatch.setattr(execution, "_compact_session", _noop_compact)+ self.db_path = tmp_path / "agents.sqlite"+ self.sessions: list[Any] = []+ self.run_config = MagicMock()+ self.root_ctx: dict[str, Any] = {+ "agent_id": "root",+ "parent_id": None,+ "coordinator": self.coordinator,+ }+ self.root_task: asyncio.Task[Any] | None = None++ async def start_root(self, *, calls: int) -> None:+ self.ledger.remaining["root"] = calls+ await self.coordinator.register("root", "strix", parent_id=None)+ session = open_agent_session("root", self.db_path)+ self.sessions.append(session)+ self.root_task = asyncio.create_task(+ run_agent_loop(+ agent=MagicMock(),+ initial_input=[],+ run_config=self.run_config,+ context=self.root_ctx,+ max_turns=500,+ coordinator=self.coordinator,+ agent_id="root",+ interactive=False,+ session=session,+ hooks=self.hooks,+ )+ )++ async def start_child(self, child_id: str, *, calls: int) -> None:+ self.ledger.remaining[child_id] = calls+ await self.coordinator.register(child_id, "recon", parent_id="root")+ await _start_child_runner(+ parent_ctx=self.root_ctx,+ coordinator=self.coordinator,+ agents_db_path=self.db_path,+ sessions_to_close=self.sessions,+ run_config=self.run_config,+ max_turns=500,+ interactive=False,+ child_agent=MagicMock(),+ child_id=child_id,+ name=f"recon-{child_id}",+ parent_id="root",+ task="probe things",+ initial_input=[],+ hooks=self.hooks,+ )++ def tasks(self) -> list[asyncio.Task[Any]]:+ tasks = [self.root_task] if self.root_task is not None else []+ tasks.extend(rt.task for rt in self.coordinator.runtimes.values() if rt.task is not None)+ return tasks++ async def teardown(self) -> None:+ for task in self.tasks():+ task.cancel()+ await asyncio.gather(*self.tasks(), return_exceptions=True)+ for session in self.sessions:+ session.close()+++async def test_pause_policy_parks_every_agent_at_the_limit_and_resumes_in_place(+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch+) -> None:+ scan = _Scan(tmp_path, monkeypatch, max_budget_usd=5.0)+ agents = ("root", "child-a", "child-b")++ with patch("strix.core.hooks.get_global_report_state", return_value=scan.ledger):+ await scan.start_root(calls=100)+ await scan.start_child("child-a", calls=100)+ await scan.start_child("child-b", calls=100)++ await _wait_until(lambda: _all_parked(scan.coordinator, *agents))+ assert scan.ledger.cost == pytest.approx(5.0)+ assert len(scan.ledger.calls) == 5+ assert scan.coordinator.budget_paused is False+ assert scan.coordinator.budget_stopped is False+ assert scan.coordinator.reserve_stopped is False+ assert all(not task.done() for task in scan.tasks())++ woken = await scan.coordinator.resume_budget(max_budget_usd=8.0)+ assert sorted(woken) == sorted(agents)+ assert scan.hooks.max_budget_usd == 8.0+ await _wait_until(lambda: scan.ledger.cost >= 8.0)+ await _wait_until(lambda: _all_parked(scan.coordinator, *agents))+ assert scan.ledger.cost == pytest.approx(8.0)++ await scan.coordinator.resume_budget(max_budget_usd=9.0)+ await _wait_until(lambda: scan.ledger.cost >= 9.0)+ await _wait_until(lambda: _all_parked(scan.coordinator, *agents))+ assert scan.ledger.cost == pytest.approx(9.0)+ assert len(scan.ledger.calls) == 9+ assert all(not task.done() for task in scan.tasks())++ # The model never saw a budget message: no warning band, no resume note.+ assert scan.ledger.warned_inputs+ assert all(items == [] for items in scan.ledger.warned_inputs)+ for session in scan.sessions:+ assert await session.get_items() == []++ # Stop while parked: an individual stop wakes that loop and it exits.+ child_a_task = scan.coordinator.runtimes["child-a"].task+ assert child_a_task is not None+ await scan.coordinator.request_stop("child-a")+ await asyncio.wait_for(child_a_task, timeout=5.0)+ assert scan.coordinator.statuses["child-a"] == "stopped"+ assert scan.coordinator.statuses["root"] == "budget_paused"+ assert scan.coordinator.statuses["child-b"] == "budget_paused"++ # A scan-wide cancel while parked tears the rest down cleanly.+ await scan.teardown()+ assert all(task.done() for task in scan.tasks())+ assert scan.ledger.cost == pytest.approx(9.0)+++async def test_pause_policy_operator_pause_and_resume_without_a_limit(+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch+) -> None:+ scan = _Scan(tmp_path, monkeypatch, max_budget_usd=None)+ agents = ("root", "child-a", "child-b")++ with patch("strix.core.hooks.get_global_report_state", return_value=scan.ledger):+ await scan.start_root(calls=6)+ await scan.start_child("child-a", calls=6)+ await scan.start_child("child-b", calls=6)++ await _wait_until(lambda: scan.ledger.cost >= 3.0)+ await scan.coordinator.pause_budget()+ spent_at_pause = scan.ledger.cost+ await _wait_until(lambda: _all_parked(scan.coordinator, *agents))+ await _wait_until(lambda: scan.coordinator.budget_paused, timeout=0.1)+ assert scan.ledger.cost == pytest.approx(spent_at_pause)+ assert all(not task.done() for task in scan.tasks())++ await asyncio.sleep(0.05)+ assert scan.ledger.cost == pytest.approx(spent_at_pause)++ woken = await scan.coordinator.resume_budget()+ assert sorted(woken) == sorted(agents)+ await _wait_until(lambda: not scan.coordinator.budget_paused, timeout=0.1)+ await asyncio.wait_for(asyncio.gather(*scan.tasks(), return_exceptions=True), timeout=5.0)+ assert scan.ledger.cost == pytest.approx(18.0)+ assert {aid: str(s) for aid, s in scan.coordinator.statuses.items()} == {+ "root": "completed",+ "child-a": "completed",+ "child-b": "completed",+ }+ assert all(items == [] for items in scan.ledger.warned_inputs)++ for session in scan.sessions:+ session.close()+++async def test_pause_policy_keeps_in_flight_overshoot(+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch+) -> None:+ scan = _Scan(tmp_path, monkeypatch, max_budget_usd=1.0)+ scan.ledger.gate = asyncio.Event()+ await scan.coordinator.register("root", "strix", parent_id=None)++ with patch("strix.core.hooks.get_global_report_state", return_value=scan.ledger):+ await scan.start_child("child-a", calls=100)+ await scan.start_child("child-b", calls=100)++ # Both calls were dispatched under the limit; neither is cancelled.+ await _wait_until(lambda: scan.ledger.in_flight == 2)+ assert scan.ledger.cost == 0.0+ scan.ledger.gate.set()++ await _wait_until(lambda: _all_parked(scan.coordinator, "child-a", "child-b"))+ assert scan.ledger.cost == pytest.approx(2.0)+ assert scan.hooks.max_budget_usd is not None+ assert scan.ledger.cost > scan.hooks.max_budget_usd+ assert scan.coordinator.budget_stopped is False+ assert all(not task.done() for task in scan.tasks())++ # Resuming at a limit that is already spent parks again without a call.+ await scan.coordinator.resume_budget(max_budget_usd=1.5)+ await asyncio.sleep(0.05)+ await _wait_until(lambda: _all_parked(scan.coordinator, "child-a", "child-b"))+ assert scan.ledger.cost == pytest.approx(2.0)++ await scan.teardown()+++async def test_resume_between_park_decision_and_wait_is_not_missed() -> None:+ coordinator = AgentCoordinator()+ coordinator.set_budget_policy("pause")+ await coordinator.register("a", "strix", parent_id=None)++ parked_epoch = coordinator.resume_epoch+ await coordinator.park_for_budget("a")+ assert _all_parked(coordinator, "a")+ await coordinator.resume_budget()++ await asyncio.wait_for(+ coordinator.wait_for_budget_resume("a", parked_epoch=parked_epoch), timeout=1.0+ )+ assert coordinator.statuses["a"] == "running"+++async def test_parked_wait_returns_on_stop_signals() -> None:+ coordinator = AgentCoordinator()+ coordinator.set_budget_policy("pause")+ await coordinator.register("a", "strix", parent_id=None)+ await coordinator.register("b", "recon", parent_id="a")+ await coordinator.park_for_budget("a")+ await coordinator.park_for_budget("b")++ wait_a = asyncio.create_task(+ coordinator.wait_for_budget_resume("a", parked_epoch=coordinator.resume_epoch)+ )+ wait_b = asyncio.create_task(+ coordinator.wait_for_budget_resume("b", parked_epoch=coordinator.resume_epoch)+ )+ await asyncio.sleep(0.02)+ assert not wait_a.done()+ assert not wait_b.done()++ await coordinator.request_stop("b")+ await asyncio.wait_for(wait_b, timeout=1.0)+ assert coordinator.statuses["b"] == "stopped"+ assert not wait_a.done()++ await coordinator.trigger_budget_stop()+ await asyncio.wait_for(wait_a, timeout=1.0)+ assert coordinator.statuses["a"] == "budget_paused"+++async def test_resume_budget_replaces_the_limit_and_validates_it() -> None:+ hooks = ReportUsageHooks(model="m", max_budget_usd=10.0, budget_policy="pause")+ coordinator = AgentCoordinator()+ coordinator.set_budget_policy("pause")+ coordinator.set_budget_limit_setter(hooks.set_max_budget_usd)++ await coordinator.resume_budget(max_budget_usd=25.0)+ assert hooks.max_budget_usd == 25.0+ await coordinator.resume_budget()+ assert hooks.max_budget_usd == 25.0+ with pytest.raises(ValueError, match="greater than 0"):+ await coordinator.resume_budget(max_budget_usd=0.0)+ with pytest.raises(ValueError, match="finite"):+ await coordinator.resume_budget(max_budget_usd=float("inf"))+ assert hooks.max_budget_usd == 25.0+++def _ctx(coordinator: AgentCoordinator | None, *, parent_id: str | None = None) -> MagicMock:+ wrapper = MagicMock()+ wrapper.context = {"agent_id": "x", "parent_id": parent_id}+ if coordinator is not None:+ wrapper.context["coordinator"] = coordinator+ return wrapper+++async def test_pause_hooks_never_warn_and_park_only_at_the_limit() -> None:+ ledger = _FakeLedger()+ hooks = ReportUsageHooks(model="m", max_budget_usd=10.0, budget_policy="pause")+ coordinator = AgentCoordinator()+ coordinator.set_budget_policy("pause")++ with patch("strix.core.hooks.get_global_report_state", return_value=ledger):+ for cost in (7.0, 8.5, 9.5, 9.99):+ ledger.cost = cost+ for parent_id in (None, "root"):+ items: list[Any] = []+ await hooks.on_llm_start(+ _ctx(coordinator, parent_id=parent_id), MagicMock(), None, items+ )+ assert items == []+ await hooks.on_llm_end(+ _ctx(coordinator, parent_id=parent_id), MagicMock(), MagicMock()+ )++ ledger.cost = 10.0+ await hooks.on_llm_end(_ctx(coordinator, parent_id="root"), MagicMock(), MagicMock())+ with pytest.raises(BudgetPausedError) as at_limit:+ await hooks.on_llm_start(_ctx(coordinator), MagicMock(), None, [])+ assert at_limit.value.resume_epoch == coordinator.resume_epoch++ ledger.cost = 13.7+ with pytest.raises(BudgetPausedError):+ await hooks.on_llm_start(_ctx(coordinator, parent_id="root"), MagicMock(), None, [])++ hooks.set_max_budget_usd(20.0)+ items = []+ await hooks.on_llm_start(_ctx(coordinator), MagicMock(), None, items)+ assert items == []++ await coordinator.pause_budget()+ with pytest.raises(BudgetPausedError, match="paused"):+ await hooks.on_llm_start(_ctx(coordinator), MagicMock(), None, [])+++async def test_pause_hooks_do_not_count_a_parked_turn() -> None:+ ledger = _FakeLedger()+ ledger.cost = 10.0+ hooks = ReportUsageHooks(model="m", max_budget_usd=10.0, budget_policy="pause")+ coordinator = AgentCoordinator()+ ctx = _ctx(coordinator)+ with patch("strix.core.hooks.get_global_report_state", return_value=ledger):+ with pytest.raises(BudgetPausedError):+ await hooks.on_llm_start(ctx, MagicMock(), None, [])+ assert "llm_turn" not in ctx.context+ hooks.set_max_budget_usd(11.0)+ await hooks.on_llm_start(ctx, MagicMock(), None, [])+ assert ctx.context["llm_turn"] == 1+++async def test_stop_policy_is_unchanged() -> None:+ ledger = _FakeLedger()+ hooks = ReportUsageHooks(model="m", max_budget_usd=10.0)+ assert hooks.budget_policy == "stop"++ with patch("strix.core.hooks.get_global_report_state", return_value=ledger):+ ledger.cost = 7.0+ items: list[Any] = []+ await hooks.on_llm_start(_ctx(None), MagicMock(), None, items)+ assert len(items) == 1+ assert "Scan cost budget" in str(items[0])++ ledger.cost = 10.0+ with pytest.raises(BudgetExceededError):+ await hooks.on_llm_end(_ctx(None), MagicMock(), MagicMock())++ assert recomputed_budget_flags(10.0, 10.0, interactive=False, budget_policy="stop") == (+ True,+ True,+ )+ assert recomputed_budget_flags(10.0, 10.0, interactive=False, budget_policy="pause") == (+ False,+ False,+ )+++def test_budget_policy_is_validated() -> None:+ with pytest.raises(ValueError, match="budget_policy"):+ ReportUsageHooks(model="m", budget_policy="later") # type: ignore[arg-type]