"Vibe-Trading: Your Personal Trading Agent"
Python ai-agentalgorithmic-tradingbacktestingfintechllmmcpmulti-agentpythonquantitative-financetrading
refactor(agent): extract final-status resolution from _run_bound into run_outcome
Jackzigenda48546bdd92
diff --git a/agent/src/agent/loop.py b/agent/src/agent/loop.pyindex f90a6de41..006cdff52 100644--- a/agent/src/agent/loop.py+++ b/agent/src/agent/loop.py@@ -54,7 +54,6 @@ from src.providers.session_context import bind_llm_session_id, reset_llm_sessionfrom src.providers.content_filter import (CONTENT_FILTER_SKIP_MESSAGE,MAX_CONSECUTIVE_CONTENT_FILTER_SKIPS,- compute_content_filter_warnings,)from src.config.accessor import get_env_configfrom src.config.paths import get_runs_dir, get_sessions_dir@@ -896,6 +895,13 @@ from src.agent.tool_results import ( # noqa: E402_previously_archived as _previously_archived,_archive_backtest_result,)+from src.agent.run_outcome import ( # noqa: E402+ OutcomeInputs,+ RunOutcome as RunOutcome, # noqa: F401 — re-exported for callers/tests+ build_end_event,+ build_result_dict,+ resolve_final_status,+)class AgentLoop:@@ -2066,109 +2072,56 @@ class AgentLoop:# Determine final status. The reason is also propagated into the# returned dict so SessionService can surface a meaningful UI# message instead of "Execution failed: unknown" (issue #114).- final_reason: str | None = None- if self._stall_reason is not None:- # The stall watchdog already wrote the failed state; keep this- # run's terminal status honest instead of overwriting it.- final_reason = self._stall_reason- final_status = "failed"- elif self._cancel_event.is_set():- final_reason = "cancelled by user"- state_store.mark_cancelled(run_dir, final_reason)- final_status = "cancelled"- elif no_progress_reason is not None:- final_reason = no_progress_reason- state_store.mark_failure(run_dir, final_reason)- final_status = "failed"- elif content_filter_circuit_breaker:- final_reason = (- f"content_filter_circuit_breaker: "- f"{MAX_CONSECUTIVE_CONTENT_FILTER_SKIPS} consecutive LLM "- "responses were blocked by content moderation"- )- state_store.mark_failure(run_dir, final_reason)- final_status = "failed"- elif (run_dir / "artifacts" / "metrics.csv").exists() or final_content:- state_store.mark_success(run_dir)- final_status = "success"- if self._released_fallback:- final_reason = self._released_fallback_reason or (- "final answer degraded to the deterministic fallback after "- f"{self._grounding.validation_count if self._grounding else 0} "- "rejected drafts could not be corrected within the iteration budget"- )- elif not self._released_fallback:- pending_directive = self._pending_write_directive(+ outcome = resolve_final_status(+ OutcomeInputs(+ stall_reason=self._stall_reason,+ cancelled=self._cancel_event.is_set(),+ no_progress_reason=no_progress_reason,+ content_filter_circuit_breaker=content_filter_circuit_breaker,+ has_output=(run_dir / "artifacts" / "metrics.csv").exists() or bool(final_content),+ released_fallback=self._released_fallback,+ released_fallback_reason=self._released_fallback_reason,+ grounding_validation_count=(+ self._grounding.validation_count if self._grounding else 0+ ),+ pending_write_directive=lambda: self._pending_write_directive(user_message, run_started_wall- )- if pending_directive:- final_reason = (- "run ended without writing the task target file(s): "- + pending_directive- )- self._released_fallback = True- elif empty_model_response_iter is not None:- provider = self._llm_runtime.provider- model = self._llm_runtime.configured_model or "(unset)"- final_reason = (- "empty_model_response: "- f"provider={provider} model={model} iteration {empty_model_response_iter} "- "returned no content and no tool calls"- )- state_store.mark_failure(run_dir, final_reason)- final_status = "failed"- else:- final_reason = (- f"reached max iterations ({self.max_iterations}) without final answer"+ ),+ empty_model_response_iter=empty_model_response_iter,+ empty_response_provider=self._llm_runtime.provider,+ empty_response_model=self._llm_runtime.configured_model or "(unset)",+ max_iterations=self.max_iterations,)- state_store.mark_failure(run_dir, final_reason)- final_status = "failed"-- end_event: dict[str, Any] = {- "type": "end",- "iter": self._run_iteration,- "status": final_status,- "iterations": iteration,- }- if self._released_fallback:- end_event["degraded"] = True- if final_reason is not None:- end_event["reason"] = final_reason- trace.write(end_event)+ )+ final_reason = outcome.reason+ if outcome.mark == "cancelled":+ state_store.mark_cancelled(run_dir, final_reason or "cancelled by user")+ elif outcome.mark == "failure":+ state_store.mark_failure(run_dir, final_reason or "")+ elif outcome.mark == "success":+ state_store.mark_success(run_dir)+ if outcome.mark == "success" and outcome.degraded and final_reason and not self._released_fallback:+ # A success that ended without writing the target file(s): the+ # pre-extraction code flagged it degraded only for this case.+ self._released_fallback = True++ trace.write(build_end_event(outcome, self._run_iteration, iteration))trace.close()- result: dict[str, Any] = {- "status": final_status,- "run_dir": str(run_dir),- "run_id": run_dir.name,- "content": final_content,- "react_trace": react_trace,- "iterations": iteration,- "max_iterations": self.max_iterations,- }- if self._released_fallback:- result["degraded"] = True- configured_model = self._llm_runtime.configured_model- result.update(- {- "provider": self._llm_runtime.provider,- "configured_model": configured_model,- "model": last_response_model or configured_model,- "model_source": "provider_response" if last_response_model else "configured",- "reasoning_effort": self._llm_runtime.reasoning_effort,- }+ result = build_result_dict(+ outcome,+ run_dir,+ react_trace,+ iteration,+ self.max_iterations,+ final_content,+ self._llm_runtime,+ last_response_model,+ content_filter_count,)- if final_reason is not None:- result["reason"] = final_reasonself._run_done.set()- cf_warnings = compute_content_filter_warnings(- content_filter_count, max(1, iteration),- )- if cf_warnings:- result["content_filter_warnings"] = cf_warnings-return resultdef _stall_watchdog(diff --git a/agent/src/agent/run_outcome.py b/agent/src/agent/run_outcome.pynew file mode 100644index 000000000..2d3c2e399--- /dev/null+++ b/agent/src/agent/run_outcome.py@@ -0,0 +1,216 @@+"""Final outcome of an agent run: status resolution, end event, result dict.++Extracted from the tail of ``AgentLoop._run_bound`` (issue #1624, roadmap+item 3: split ``loop.py`` along its existing seams). This module owns the+decision ladder that maps how a run ended — stall, cancellation,+no-progress, content-filter circuit breaker, success, empty model+response, max iterations — onto ``(status, reason)`` plus the ``end``+trace event and the caller-facing result dict.++Everything here is pure: no state-store writes, no trace writes. The+side-effectful calls (``state_store.mark_*``, ``trace.write/close``) stay+in ``loop.py`` right after ``resolve_final_status`` returns, in the same+order they executed before the extraction.++Behavior is unchanged: every branch condition and message string moved+verbatim.+"""++from __future__ import annotations++from dataclasses import dataclass+from pathlib import Path+from typing import Any, Callable, Optional++from src.providers.chat import LLMRuntimeSnapshot+from src.providers.content_filter import (+ MAX_CONSECUTIVE_CONTENT_FILTER_SKIPS,+ compute_content_filter_warnings,+)+++@dataclass+class OutcomeInputs:+ """The run-end facts the status ladder reads.++ Attributes:+ stall_reason: Reason the stall watchdog already recorded, if any.+ A non-None value wins the ladder: the watchdog already wrote+ the failed state, so the run's terminal status must stay+ honest instead of overwriting it.+ cancelled: Whether the user cancel event is set.+ no_progress_reason: Reason the no-progress check recorded, if any.+ content_filter_circuit_breaker: Whether the content-filter skip+ streak tripped the breaker.+ has_output: Whether the run produced any user-visible output —+ a metrics artifact or a non-empty final answer.+ released_fallback: Whether the grounding gate degraded the final+ answer to the deterministic fallback.+ released_fallback_reason: Reason captured at the release site, if+ the release path set one.+ grounding_validation_count: Rejected-draft count from the+ grounding ledger, used only to build the lazily-worded+ fallback reason when none was captured.+ pending_write_directive: The ``run ended without writing the task+ target file(s)`` directive, or ``None``. Evaluated lazily by+ the caller only on the success path.+ empty_model_response_iter: Iteration of the final empty model+ response, if the run died that way.+ empty_response_provider: Provider name for the empty-response+ failure message.+ empty_response_model: Configured model name for the+ empty-response failure message.+ max_iterations: The run's iteration budget (for the failure+ message).+ """++ stall_reason: Optional[str]+ cancelled: bool+ no_progress_reason: Optional[str]+ content_filter_circuit_breaker: bool+ has_output: bool+ released_fallback: bool+ released_fallback_reason: Optional[str]+ grounding_validation_count: int+ pending_write_directive: Callable[[], Optional[str]]+ empty_model_response_iter: Optional[int]+ empty_response_provider: str+ empty_response_model: str+ max_iterations: int+++@dataclass+class RunOutcome:+ """Terminal status plus the side effects the caller must still perform.++ Attributes:+ status: One of ``success``, ``failed``, ``cancelled``.+ reason: Human-readable terminal reason, or ``None`` on a clean+ success. Propagates into the result dict so SessionService+ can surface a meaningful UI message instead of+ ``Execution failed: unknown`` (issue #114).+ mark: Which ``RunStateStore`` transition to record, or ``None``+ when the stall watchdog already wrote the failed state.+ degraded: Whether the final answer was released through the+ degraded fallback path. Drives the ``degraded`` flag on both+ the end event and the result dict.+ """++ status: str+ reason: Optional[str]+ mark: Optional[str]+ degraded: bool+++def resolve_final_status(inputs: OutcomeInputs) -> RunOutcome:+ """Run the terminal-status decision ladder.++ The branch order is load-bearing and unchanged from the pre-extraction+ ``_run_bound`` tail: stall (already recorded) → cancelled → no+ progress → content-filter breaker → success → empty response → max+ iterations.+ """+ if inputs.stall_reason is not None:+ # The stall watchdog already wrote the failed state; keep this+ # run's terminal status honest instead of overwriting it.+ return RunOutcome("failed", inputs.stall_reason, None, False)+ if inputs.cancelled:+ return RunOutcome("cancelled", "cancelled by user", "cancelled", False)+ if inputs.no_progress_reason is not None:+ return RunOutcome("failed", inputs.no_progress_reason, "failure", False)+ if inputs.content_filter_circuit_breaker:+ reason = (+ f"content_filter_circuit_breaker: "+ f"{MAX_CONSECUTIVE_CONTENT_FILTER_SKIPS} consecutive LLM "+ "responses were blocked by content moderation"+ )+ return RunOutcome("failed", reason, "failure", False)+ if inputs.has_output:+ if inputs.released_fallback:+ reason = inputs.released_fallback_reason or (+ "final answer degraded to the deterministic fallback after "+ f"{inputs.grounding_validation_count} "+ "rejected drafts could not be corrected within the iteration budget"+ )+ return RunOutcome("success", reason, "success", True)+ pending_directive = inputs.pending_write_directive()+ if pending_directive:+ reason = (+ "run ended without writing the task target file(s): "+ + pending_directive+ )+ return RunOutcome("success", reason, "success", True)+ return RunOutcome("success", None, "success", False)+ if inputs.empty_model_response_iter is not None:+ reason = (+ "empty_model_response: "+ f"provider={inputs.empty_response_provider} "+ f"model={inputs.empty_response_model} "+ f"iteration {inputs.empty_model_response_iter} "+ "returned no content and no tool calls"+ )+ return RunOutcome("failed", reason, "failure", False)+ reason = f"reached max iterations ({inputs.max_iterations}) without final answer"+ return RunOutcome("failed", reason, "failure", False)+++def build_end_event(+ outcome: RunOutcome,+ run_iteration: int,+ iterations: int,+) -> dict[str, Any]:+ """The ``end`` trace event for a finished run."""+ end_event: dict[str, Any] = {+ "type": "end",+ "iter": run_iteration,+ "status": outcome.status,+ "iterations": iterations,+ }+ if outcome.degraded:+ end_event["degraded"] = True+ if outcome.reason is not None:+ end_event["reason"] = outcome.reason+ return end_event+++def build_result_dict(+ outcome: RunOutcome,+ run_dir: Path,+ react_trace: Any,+ iterations: int,+ max_iterations: int,+ final_content: str,+ runtime: LLMRuntimeSnapshot,+ last_response_model: Optional[str],+ content_filter_count: int,+) -> dict[str, Any]:+ """The caller-facing result dict for a finished run."""+ result: dict[str, Any] = {+ "status": outcome.status,+ "run_dir": str(run_dir),+ "run_id": run_dir.name,+ "content": final_content,+ "react_trace": react_trace,+ "iterations": iterations,+ "max_iterations": max_iterations,+ }+ if outcome.degraded:+ result["degraded"] = True+ configured_model = runtime.configured_model+ result.update(+ {+ "provider": runtime.provider,+ "configured_model": configured_model,+ "model": last_response_model or configured_model,+ "model_source": "provider_response" if last_response_model else "configured",+ "reasoning_effort": runtime.reasoning_effort,+ }+ )+ if outcome.reason is not None:+ result["reason"] = outcome.reason+ cf_warnings = compute_content_filter_warnings(+ content_filter_count, max(1, iterations),+ )+ if cf_warnings:+ result["content_filter_warnings"] = cf_warnings+ return resultdiff --git a/agent/tests/test_run_outcome_module.py b/agent/tests/test_run_outcome_module.pynew file mode 100644index 000000000..3dc7edf51--- /dev/null+++ b/agent/tests/test_run_outcome_module.py@@ -0,0 +1,226 @@+"""Pin the extraction contract of the run-outcome module (issue #1624).++``AgentLoop._run_bound`` used to resolve its terminal status, end event,+and result dict inline in a 100-line tail; that ladder now lives in+``src.agent.run_outcome`` and is called from ``loop.py``. These tests pin+each branch of the ladder directly — something the pre-extraction layout+could only exercise by stubbing a whole LLM — plus the re-export surface+``loop.py`` must keep importing.+"""++from __future__ import annotations++from pathlib import Path+from types import SimpleNamespace+from typing import Optional++import pytest++import src.agent.loop as loop+import src.agent.run_outcome as run_outcome+from src.agent.run_outcome import (+ OutcomeInputs,+ RunOutcome,+ build_end_event,+ build_result_dict,+ resolve_final_status,+)++RE_EXPORTS = [+ "OutcomeInputs",+ "RunOutcome",+ "build_end_event",+ "build_result_dict",+ "resolve_final_status",+]++[email protected]("name", RE_EXPORTS)+def test_loop_reexports(name: str) -> None:+ """Every moved name resolves through ``src.agent.loop`` (back-compat)."""+ assert getattr(loop, name) is getattr(run_outcome, name)+++def _inputs(**over: object) -> OutcomeInputs:+ base = dict(+ stall_reason=None,+ cancelled=False,+ no_progress_reason=None,+ content_filter_circuit_breaker=False,+ has_output=True,+ released_fallback=False,+ released_fallback_reason=None,+ grounding_validation_count=0,+ pending_write_directive=lambda: None,+ empty_model_response_iter=None,+ empty_response_provider="openai",+ empty_response_model="stub-model",+ max_iterations=12,+ )+ base.update(over)+ return OutcomeInputs(**base) # type: ignore[arg-type]+++class TestResolveFinalStatus:+ def test_clean_success(self) -> None:+ out = resolve_final_status(_inputs())+ assert (out.status, out.reason, out.mark, out.degraded) == (+ "success", None, "success", False,+ )++ def test_stall_wins_and_does_not_remark(self) -> None:+ out = resolve_final_status(_inputs(stall_reason="stalled: no progress"))+ assert out.status == "failed"+ assert out.reason == "stalled: no progress"+ # The watchdog already wrote the failed state.+ assert out.mark is None++ def test_cancelled(self) -> None:+ out = resolve_final_status(_inputs(cancelled=True))+ assert (out.status, out.reason, out.mark) == (+ "cancelled", "cancelled by user", "cancelled",+ )++ def test_no_progress(self) -> None:+ out = resolve_final_status(_inputs(no_progress_reason="no forward progress"))+ assert (out.status, out.mark) == ("failed", "failure")+ assert out.reason == "no forward progress"++ def test_content_filter_breaker_message(self) -> None:+ out = resolve_final_status(_inputs(content_filter_circuit_breaker=True))+ assert out.status == "failed"+ assert out.reason is not None+ assert out.reason.startswith("content_filter_circuit_breaker:")+ from src.providers.content_filter import MAX_CONSECUTIVE_CONTENT_FILTER_SKIPS+ assert str(MAX_CONSECUTIVE_CONTENT_FILTER_SKIPS) in out.reason++ def test_success_with_released_fallback_reason(self) -> None:+ out = resolve_final_status(+ _inputs(+ released_fallback=True,+ released_fallback_reason="final answer released with unverified figures redacted after 2 rejected drafts",+ )+ )+ assert (out.status, out.degraded, out.mark) == ("success", True, "success")+ assert out.reason is not None+ assert "unverified figures" in out.reason++ def test_success_fallback_reason_built_lazily_from_count(self) -> None:+ out = resolve_final_status(+ _inputs(released_fallback=True, grounding_validation_count=3)+ )+ assert out.reason is not None+ assert "3" in out.reason+ assert "deterministic fallback" in out.reason++ def test_success_with_pending_write_directive(self) -> None:+ calls: list[int] = []++ def directive() -> Optional[str]:+ calls.append(1)+ return "metrics.csv named in the task but never written"++ out = resolve_final_status(_inputs(pending_write_directive=directive))+ assert (out.status, out.degraded) == ("success", True)+ assert out.reason is not None+ assert out.reason.startswith("run ended without writing the task target file(s):")+ assert calls == [1]++ def test_pending_directive_not_evaluated_on_other_paths(self) -> None:+ def boom() -> str:+ raise AssertionError("directive must be lazy")++ # Failure path: directive is never consulted.+ out = resolve_final_status(_inputs(cancelled=True, pending_write_directive=boom))+ assert out.status == "cancelled"++ def test_empty_model_response(self) -> None:+ out = resolve_final_status(+ _inputs(has_output=False, empty_model_response_iter=4)+ )+ assert (out.status, out.mark) == ("failed", "failure")+ assert out.reason is not None+ assert out.reason.startswith("empty_model_response:")+ assert "provider=openai" in out.reason+ assert "model=stub-model" in out.reason+ assert "iteration 4" in out.reason++ def test_max_iterations(self) -> None:+ out = resolve_final_status(_inputs(has_output=False, max_iterations=12))+ assert out.status == "failed"+ assert out.reason == "reached max iterations (12) without final answer"++ def test_ladder_precedence_stall_beats_cancel(self) -> None:+ out = resolve_final_status(+ _inputs(stall_reason="stalled", cancelled=True)+ )+ assert out.status == "failed"+ assert out.mark is None+++class TestBuildEndEvent:+ def test_clean(self) -> None:+ ev = build_end_event(RunOutcome("success", None, "success", False), 3, 7)+ assert ev == {"type": "end", "iter": 3, "status": "success", "iterations": 7}++ def test_reason_and_degraded_flags(self) -> None:+ ev = build_end_event(RunOutcome("failed", "boom", "failure", True), 2, 5)+ assert ev["reason"] == "boom"+ assert ev["degraded"] is True+++class TestBuildResultDict:+ def _runtime(self) -> SimpleNamespace:+ return SimpleNamespace(+ provider="openai", configured_model="gpt-test", reasoning_effort="low"+ )++ def test_fields_and_model_source(self) -> None:+ r = build_result_dict(+ RunOutcome("success", None, "success", False),+ Path("/tmp/runs/abc123"),+ [{"type": "answer"}],+ 4,+ 12,+ "the answer",+ self._runtime(),+ None,+ content_filter_count=0,+ )+ assert r["status"] == "success"+ assert r["run_id"] == "abc123"+ assert r["content"] == "the answer"+ assert r["model"] == "gpt-test"+ assert r["model_source"] == "configured"+ assert "degraded" not in r+ assert "reason" not in r++ def test_provider_response_model_wins(self) -> None:+ r = build_result_dict(+ RunOutcome("success", None, "success", False),+ Path("/tmp/runs/x"),+ [],+ 1,+ 12,+ "",+ self._runtime(),+ "provider-reported-model",+ content_filter_count=0,+ )+ assert r["model"] == "provider-reported-model"+ assert r["model_source"] == "provider_response"++ def test_degraded_and_reason_propagate(self) -> None:+ r = build_result_dict(+ RunOutcome("success", "degraded for a reason", "success", True),+ Path("/tmp/runs/x"),+ [],+ 1,+ 12,+ "text",+ self._runtime(),+ None,+ content_filter_count=0,+ )+ assert r["degraded"] is True+ assert r["reason"] == "degraded for a reason"