agent: validate goal input in StandardAgent.solve() (#130)

Closes #76

Before this change, passing `None`, a non-string, or an empty/whitespace
string to `solve()` resulted in a confusing traceback from deep inside
either the goal preprocessor (`process(None, ...)`) or the reasoner. The
state machine could even be left in `BUSY` because validation happened
*after* `_state = AgentState.BUSY`.

This PR validates `goal` at the very top of `solve()`:

- `goal is None`         → `TypeError("goal must be a non-empty str, got None")`
- `not isinstance(str)`  → `TypeError("goal must be a str, got <type>")`
  (informative type name in the message)
- `not goal.strip()`     → `ValueError("goal must be a non-empty string ...")`

Whitespace-bearing goals like `"  do the thing  "` are still accepted —
we only reject *empty* or *only-whitespace* inputs.

Why these specific exceptions:

- `TypeError` for None / wrong type, matching the Python stdlib
  convention for "you passed an object of the wrong shape".
- `ValueError` for empty/whitespace, matching the convention for
  "right type, wrong value".

State machine invariant: validation happens *before* any state mutation,
so a rejected `solve(...)` leaves `agent.state == READY` (asserted in
every new test).

Tests (`tests/agents/test_standard_agent.py`):

- `test_solve_raises_type_error_on_none_goal`
- `test_solve_raises_type_error_on_non_string_goal` — parametrized over
  `[123, 1.5, ["a"], {"x": 1}, b"bytes"]`
- `test_solve_raises_value_error_on_empty_or_whitespace_goal` —
  parametrized over `["", "   ", "\n", "\t \n"]`
- `test_solve_accepts_goal_with_leading_or_trailing_whitespace` —
  guards against over-strict validation regression.

All 28 tests in `tests/agents/test_standard_agent.py` pass (17
existing + 11 new). `ruff check` clean on touched files. Pre-existing
mypy issues are unchanged (verified: same count on `main` vs this
branch).

AI-assisted via Cursor (Claude Opus 4.7). Personal token-burn
initiative by @adv0r to use up an expiring Cursor subscription budget
on small, useful upstream contributions.

Co-authored-by: adv0r <>
Co-authored-by: Cursor <cursoragent@cursor.com>

Author: adv0r

agents/standard_agent.py

@@ -85,7 +85,28 @@ def state(self) -> AgentState:
 
     @observe(root=True)
     def solve(self, goal: str) -> ReasoningResult:
-        """Solves a goal synchronously (library-style API)."""
+        """Solves a goal synchronously (library-style API).
+
+        Args:
+            goal: A non-empty string describing what to solve.
+
+        Raises:
+            TypeError: ``goal`` is not a ``str`` (or is ``None``).
+            ValueError: ``goal`` is empty or contains only whitespace.
+        """
+        # Validate the goal up-front so callers get a clear, immediate error
+        # instead of a confusing traceback from deep inside the reasoner or
+        # the goal preprocessor (which can blow up on None / non-string
+        # inputs in non-obvious ways).
+        if goal is None:
+            raise TypeError("goal must be a non-empty str, got None")
+        if not isinstance(goal, str):
+            raise TypeError(
+                f"goal must be a str, got {type(goal).__name__}"
+            )
+        if not goal.strip():
+            raise ValueError("goal must be a non-empty string (got empty or whitespace-only)")
+
         run_id = uuid4().hex
         start_time = time.perf_counter()
 

tests/agents/test_standard_agent.py

@@ -101,6 +101,49 @@ def test_agent_solve_sets_final_answer_from_summarizer_and_records_history(monke
     assert hist[-1]["result"] == "SUMMARIZED"
 
 
+def _make_validation_agent():
+    """Helper: build a StandardAgent good enough to call solve() on."""
+    llm = DummyLLM(text_queue=["SUMMARIZED"])
+    tools = DummyTools()
+    memory: Dict[str, Any] = DictMemory()
+    reasoner = DummyReasoner()
+    return StandardAgent(llm=llm, tools=tools, memory=memory, reasoner=reasoner)
+
+
+def test_solve_raises_type_error_on_none_goal():
+    """solve(None) -> TypeError, agent never reaches the reasoner."""
+    agent = _make_validation_agent()
+    with pytest.raises(TypeError, match="goal must be"):
+        agent.solve(None)  # type: ignore[arg-type]
+    # State must NOT flip to BUSY/NEEDS_ATTENTION on input validation.
+    assert agent.state == AgentState.READY
+
+
+@pytest.mark.parametrize("bad_goal", [123, 1.5, ["a"], {"x": 1}, b"bytes"])
+def test_solve_raises_type_error_on_non_string_goal(bad_goal):
+    """solve(<non-str>) -> TypeError with type name in the message."""
+    agent = _make_validation_agent()
+    with pytest.raises(TypeError, match=r"goal must be a str, got "):
+        agent.solve(bad_goal)  # type: ignore[arg-type]
+    assert agent.state == AgentState.READY
+
+
+@pytest.mark.parametrize("empty", ["", "   ", "\n", "\t \n"])
+def test_solve_raises_value_error_on_empty_or_whitespace_goal(empty):
+    """solve('' or whitespace-only) -> ValueError."""
+    agent = _make_validation_agent()
+    with pytest.raises(ValueError, match="non-empty"):
+        agent.solve(empty)
+    assert agent.state == AgentState.READY
+
+
+def test_solve_accepts_goal_with_leading_or_trailing_whitespace():
+    """Leading/trailing whitespace is allowed as long as content exists."""
+    agent = _make_validation_agent()
+    result = agent.solve("  do the thing  ")
+    assert result.final_answer == "SUMMARIZED"
+
+
 def test_agent_uses_goal_preprocessor_and_returns_intervention_message(monkeypatch):
     _fixed_uuid4(monkeypatch, "RUNINT")
     llm = DummyLLM(text_queue=["UNUSED"])