Skip to content

"Vibe-Trading: Your Personal Trading Agent"

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.py
index 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_session
from 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_config
from 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_reason
self._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 result
def _stall_watchdog(
diff --git a/agent/src/agent/run_outcome.py b/agent/src/agent/run_outcome.py
new file mode 100644
index 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 result
diff --git a/agent/tests/test_run_outcome_module.py b/agent/tests/test_run_outcome_module.py
new file mode 100644
index 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"