fix(agents): dispatch Python-call-style embedded tool syntax (#2573)

On the NPU (non-tool-calling) path, the model sometimes emits a tool
call as Python-call syntax, e.g. `remember(fact="...", category="...")`,
instead of the JSON shape the prompt teaches. The parser only recognized
JSON, so that text fell through to the plain-text answer path — the raw
syntax was shown to the user and the tool never ran (in one case the
model even claimed the action succeeded when it hadn't).

`_extract_embedded_tool_call` now falls back to a Python-call-syntax
detector: only names matching a tool actually registered on the agent
are treated as calls (so ordinary prose isn't misfired on), arguments
are parsed with `ast.literal_eval`, and a matched tool name with
unparseable arguments raises a loud `ValueError` instead of being echoed
— reusing the existing tool-call-parse-error recovery loop in
`process_query`.

Closes #2521

**Not fixed here (flagging per plan):** tool-call logging is
inconsistent — some tools that execute and mutate state produce no
`log_tool_call` entry (e.g. `set_low_priority_sender`), while others do
(`list_inbox`, `triage_inbox`). This made diagnosing #2521 harder
(database inspection was the only reliable signal). Filing separately
rather than expanding this PR's scope.

**Also per plan:** this touches core agent tool-call parsing, which
normally requires an eval run before merge — intentionally not run here
per the orchestrator's instruction; category to check before merge is
`agent_behavior` / tool-call related scenarios.

## Test plan

- [x] New failing-first unit tests in
`tests/unit/agents/test_embedded_function_call_syntax.py` reproduce the
exact reported response (`remember(fact="TechCrunch emails are low
priority", category="preference")`) and fail before the fix
- [x] `.venv-wt/bin/python -m pytest
tests/unit/agents/test_embedded_function_call_syntax.py -q` → 8 passed
- [x] `.venv-wt/bin/python -m pytest tests/unit/agents/ -q` → 486
passed, 60 skipped (3 pre-existing failures unrelated to this change —
missing `fastapi`/`[ui]` extra in the test env)
- [x] `python util/lint.py --all` → all checks pass
- [ ] Not run (per instructions): `gaia eval agent`, and no
NPU/FastFlowLM hardware test — this defect only reproduces on that
backend

Author: itomek

src/gaia/agents/base/agent.py

@@ -228,6 +228,42 @@ def _fix(m: re.Match) -> str:
     return re.sub(r"\\(.)", _fix, s)
 
 
+def _find_matching_close_paren(text: str, open_pos: int) -> Optional[int]:
+    """Return the index of the ``)`` that closes ``text[open_pos]`` (a ``(``).
+
+    Depth- and quote-aware (mirrors the brace matcher used for embedded JSON
+    tool calls) so a ``)`` inside a quoted argument value doesn't close the
+    call early. Returns ``None`` if the call is never terminated.
+    """
+    depth = 0
+    in_str = False
+    quote_char = ""
+    escape = False
+    for j in range(open_pos, len(text)):
+        ch = text[j]
+        if escape:
+            escape = False
+            continue
+        if ch == "\\":
+            escape = True
+            continue
+        if in_str:
+            if ch == quote_char:
+                in_str = False
+            continue
+        if ch in ("'", '"'):
+            in_str = True
+            quote_char = ch
+            continue
+        if ch == "(":
+            depth += 1
+        elif ch == ")":
+            depth -= 1
+            if depth == 0:
+                return j
+    return None
+
+
 # Suffix appended to the last tool-result message when ``single_tool_per_turn``
 # agents have completed their one tool call. The model sees this and emits a
 # short final reply instead of calling another tool. Greppable for fixtures
@@ -920,16 +956,25 @@ def _extract_embedded_tool_call(self, response: str) -> Optional[Dict[str, Any]]
           1. ≥1 unfenced candidate → return the first (unchanged — zero regression).
           2. else exactly one fenced candidate → return it (the fix for #1428).
           3. else >1 fenced, 0 unfenced → ambiguous (looks like docs) → None + warning.
-          4. else → None.
+          4. else → fall back to Python-call syntax detection (#2521), e.g.
+             ``remember(fact="...", category="preference")``.
 
         This method finds the JSON block using brace-depth matching and returns
         the parsed tool call if it contains a "tool" key.  Returns None if no
         embedded tool call is found, allowing the caller to treat the response
         as plain text.
+
+        Raises:
+            ValueError: propagated from the Python-call-syntax fallback (#2521)
+                when a *registered* tool's name is followed by an argument list
+                that can't be parsed — a loud failure rather than echoing the
+                raw syntax to the user as an answer.
         """
-        # Quick check: must contain "tool" to be worth scanning
+        # Quick check: must contain "tool" to be worth scanning for the JSON
+        # shape. Responses without it may still carry the #2521 Python-call
+        # shape below (e.g. no literal "tool" substring at all).
         if '"tool"' not in response:
-            return None
+            return self._extract_function_call_tool_syntax(response)
 
         # Build a set of character ranges inside code fences (```...```)
         _code_ranges: list[tuple[int, int]] = []
@@ -1043,6 +1088,79 @@ def _parse_candidate(raw: str) -> Optional[Dict[str, Any]]:
             )
             return None
 
+        # Rule 4: the "tool" marker was present but matched no JSON-shaped
+        # candidate (e.g. it appeared in unrelated text) — fall back to the
+        # Python-call syntax detector (#2521) before giving up.
+        return self._extract_function_call_tool_syntax(response)
+
+    _FUNC_CALL_NAME_RE = re.compile(r"\b([A-Za-z_][A-Za-z0-9_]*)\s*\(")
+
+    def _extract_function_call_tool_syntax(
+        self, response: str
+    ) -> Optional[Dict[str, Any]]:
+        """Detect a Python-call-style tool invocation embedded in text (#2521).
+
+        On the non-tool-calling (embedded-JSON) path the prompt only ever
+        teaches the JSON shape ``{"tool": "name", "tool_args": {...}}``, but
+        some models — observed on the FastFlowLM/NPU backend — instead emit
+        a bare Python-style call, e.g.::
+
+            remember(fact="TechCrunch emails are low priority", category="preference")
+
+        Without this, that text falls through to the plain-text answer path:
+        the raw call syntax is shown to the user and the tool never runs.
+
+        Only names that match a tool actually **registered** on this agent
+        are treated as calls, so ordinary prose that happens to contain
+        "word(...)" (code snippets, examples) is left as plain text. A name
+        match with an argument list that can't be parsed is a loud failure
+        (raises ``ValueError``) rather than being echoed to the user.
+
+        Returns:
+            ``{"tool": name, "tool_args": {...}}`` on a successful match, or
+            ``None`` if no registered-tool call syntax is present.
+
+        Raises:
+            ValueError: a registered tool's name is followed by an argument
+                list that could not be parsed as Python literals.
+        """
+        registry = self._tools_registry
+        if not registry:
+            return None
+
+        for match in self._FUNC_CALL_NAME_RE.finditer(response):
+            name = match.group(1)
+            if name not in registry:
+                continue
+
+            open_paren = match.end() - 1
+            close_paren = _find_matching_close_paren(response, open_paren)
+            if close_paren is None:
+                raise ValueError(
+                    f"Detected an unterminated call to tool '{name}' — cannot "
+                    "execute it. Raw text: "
+                    f"{response[match.start():match.start() + 200]!r}"
+                )
+
+            call_src = response[match.start() : close_paren + 1]
+            try:
+                node = ast.parse(call_src, mode="eval").body
+                if not isinstance(node, ast.Call) or node.args:
+                    raise ValueError("expected a call with only keyword arguments")
+                tool_args: Dict[str, Any] = {}
+                for kw in node.keywords:
+                    if kw.arg is None:
+                        raise ValueError("**kwargs expansion is not supported")
+                    tool_args[kw.arg] = ast.literal_eval(kw.value)
+            except (SyntaxError, ValueError) as exc:
+                raise ValueError(
+                    f"Detected a call to tool '{name}' but could not parse "
+                    f"its arguments: {exc}. Raw call: {call_src[:200]!r}"
+                ) from exc
+
+            logger.debug("[PARSE] Extracted function-call-syntax tool call: %s", name)
+            return {"tool": name, "tool_args": tool_args}
+
         return None
 
     def _extract_json_from_response(self, response: str) -> Optional[Dict[str, Any]]:

tests/unit/agents/test_embedded_function_call_syntax.py

@@ -0,0 +1,229 @@
+# Copyright(C) 2025-2026 Advanced Micro Devices, Inc. All rights reserved.
+# SPDX-License-Identifier: MIT
+"""Unit tests for #2521: embedded tool-call syntax echoed as text on the
+non-tool-calling (NPU / FastFlowLM) path.
+
+On that path the model sometimes emits a Python-call-style invocation
+instead of the JSON shape the prompt teaches, e.g.::
+
+    remember(fact="TechCrunch emails are low priority", category="preference")
+
+Before this fix ``_extract_embedded_tool_call`` only recognised the JSON
+shape (``{"tool": ..., "tool_args": ...}``); the call-syntax text fell
+through to the plain-text answer path, so the raw syntax reached the user
+and the tool never ran.
+"""
+
+import json
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from gaia.agents.base.agent import Agent
+
+
+class _DummyAgent(Agent):
+    """Minimal concrete Agent for testing."""
+
+    def _get_system_prompt(self) -> str:
+        return "You are a test agent."
+
+    def _register_tools(self) -> None:
+        pass
+
+    def _create_console(self):
+        from gaia.agents.base.console import AgentConsole
+
+        return AgentConsole()
+
+
+@pytest.fixture
+def agent():
+    with patch("gaia.agents.base.agent.AgentSDK"):
+        a = _DummyAgent(silent_mode=True, skip_lemonade=True)
+        a.streaming = False
+        return a
+
+
+def _register_remember(agent, result=None):
+    """Register a fake ``remember`` tool in this instance's snapshot only."""
+    calls = []
+    result = result if result is not None else {"status": "success"}
+
+    def _remember(**kwargs):
+        calls.append(kwargs)
+        return result
+
+    agent._instance_tools = {
+        "remember": {
+            "name": "remember",
+            "description": "stub",
+            "parameters": {
+                "fact": {"type": "string", "required": True},
+                "category": {"type": "string", "required": False},
+            },
+            "function": _remember,
+            "atomic": True,
+        }
+    }
+    return calls
+
+
+# ---------------------------------------------------------------------------
+# 1. Core guard: bare function-call syntax dispatches the tool
+# ---------------------------------------------------------------------------
+
+
+class TestFunctionCallSyntaxParsing:
+    def test_bare_call_is_parsed_as_tool_call(self, agent):
+        _register_remember(agent)
+        response = (
+            'remember(fact="TechCrunch emails are low priority", '
+            'category="preference")'
+        )
+        parsed = agent._parse_llm_response(response)
+        assert parsed.get("tool") == "remember"
+        assert parsed.get("tool_args") == {
+            "fact": "TechCrunch emails are low priority",
+            "category": "preference",
+        }
+        # The raw call syntax must not be echoed as an "answer".
+        assert "answer" not in parsed or parsed.get("answer") != response
+
+    def test_unregistered_name_is_left_as_plain_text(self, agent):
+        """A word(...) pattern that isn't a registered tool stays plain text."""
+        _register_remember(agent)
+        response = 'Please call cleanup(now="true") if needed.'
+        parsed = agent._parse_llm_response(response)
+        assert not parsed.get("tool")
+        assert parsed.get("answer") == response
+
+    def test_call_followed_by_prose_still_dispatches(self, agent):
+        """A success-claiming sentence after the call must not become the
+        final answer -- the tool call is dispatched instead (same class as
+        #2520: never let the model claim an unexecuted action succeeded)."""
+        _register_remember(agent)
+        response = (
+            'remember(fact="TechCrunch emails are low priority", '
+            'category="preference")\n'
+            "I have updated my preferences to treat emails from "
+            "TechCrunch as low priority."
+        )
+        parsed = agent._parse_llm_response(response)
+        assert parsed.get("tool") == "remember"
+        assert parsed.get("tool_args") == {
+            "fact": "TechCrunch emails are low priority",
+            "category": "preference",
+        }
+        # The trailing success claim must not surface as the answer.
+        assert parsed.get("answer") != response
+        assert "answer" not in parsed or "updated my preferences" not in (
+            parsed.get("answer") or ""
+        )
+
+
+# ---------------------------------------------------------------------------
+# 2. Unparseable call -> loud, actionable failure (never echoed)
+# ---------------------------------------------------------------------------
+
+
+class TestUnparseableCallRaises:
+    def test_unquoted_kwarg_value_raises_actionable_error(self, agent):
+        """A registered tool name followed by malformed args must raise --
+        not be echoed back to the user as plain text."""
+        _register_remember(agent)
+        response = "remember(fact=TechCrunch is low priority, category=preference)"
+        with pytest.raises(ValueError, match="remember"):
+            agent._parse_llm_response(response)
+
+    def test_unterminated_call_raises_actionable_error(self, agent):
+        _register_remember(agent)
+        response = 'remember(fact="TechCrunch emails are low priority"'
+        with pytest.raises(ValueError, match="remember"):
+            agent._parse_llm_response(response)
+
+
+# ---------------------------------------------------------------------------
+# 3. Native tool-calling models are unaffected
+# ---------------------------------------------------------------------------
+
+
+class TestNativeToolCallingUnaffected:
+    def test_native_sentinel_envelope_unaffected(self, agent):
+        """The __tool_calls__ sentinel path is handled before any embedded
+        extraction and must keep working unchanged."""
+        _register_remember(agent)
+        response = json.dumps(
+            {
+                "__tool_calls__": [
+                    {
+                        "function": {
+                            "name": "remember",
+                            "arguments": json.dumps(
+                                {
+                                    "fact": "TechCrunch emails are low priority",
+                                    "category": "preference",
+                                }
+                            ),
+                        }
+                    }
+                ]
+            }
+        )
+        parsed = agent._parse_llm_response(response)
+        assert parsed["tool"] == "remember"
+        assert parsed["tool_args"]["category"] == "preference"
+
+    def test_plain_prose_without_any_registered_tool_name_untouched(self, agent):
+        _register_remember(agent)
+        response = "Sure, I can help with that. What would you like to know?"
+        parsed = agent._parse_llm_response(response)
+        assert not parsed.get("tool")
+        assert parsed.get("answer") == response
+
+
+# ---------------------------------------------------------------------------
+# 4. End-to-end: process_query dispatches the tool and never leaks raw syntax
+# ---------------------------------------------------------------------------
+
+
+class TestProcessQueryDispatchesEmbeddedFunctionCallSyntax:
+    def _stub_chat(self, agent, *responses):
+        responses = list(responses)
+        chat = MagicMock()
+
+        def _send(*_, **__):
+            r = responses.pop(0)
+            resp = MagicMock()
+            resp.text = r
+            resp.stats = {}
+            return resp
+
+        chat.send_messages = MagicMock(side_effect=_send)
+        agent.chat = chat
+        return chat
+
+    def test_embedded_call_executes_and_raw_syntax_never_reaches_user(self, agent):
+        calls = _register_remember(agent)
+        step1 = (
+            'remember(fact="TechCrunch emails are low priority", '
+            'category="preference")'
+        )
+        step2 = json.dumps({"thought": "done", "answer": "Got it, noted."})
+        self._stub_chat(agent, step1, step2)
+
+        result = agent.process_query(
+            "From now on treat anything from TechCrunch as low priority.",
+            max_steps=5,
+        )
+
+        # The tool actually ran.
+        assert calls == [
+            {
+                "fact": "TechCrunch emails are low priority",
+                "category": "preference",
+            }
+        ]
+        text = result.get("result") if isinstance(result, dict) else str(result)
+        # Raw internal call syntax never reached the user-visible output.
+        assert "remember(" not in (text or "")