feat(agent): wire real ReAct tool-calling loop into Ask tab (M21)

Turns the stubbed ToolExecutor into a working multi-step agent:

- Fix ToolExecutor.execute() bus dispatch: it built a RouteRequest and called
bus.call(req), but the HearthNet CapabilityBus API is positional
bus.call(name, version, body). The tool path was therefore never reachable.
Now dispatches correctly and surfaces bus errors instead of fabricating.
- Add ToolExecutor.run_react_loop(): a model-agnostic ReAct loop mirroring the
proven browser agent format (action: {json} -> Observation:), so it works on
tiny local models with no native function-calling. Returns {final, steps}
with a Thought -> Tool -> Observation trace.
- Add default_tool_set(bus): binds read-only tools to REAL existing caps
(rag.query, rag.list_corpora, trans.text, market.list, moe.route,
tool.plant_identify). No side-effecting tools, no mock handlers.
- Ask tab: add 'Agent mode' toggle + Agent Steps panel showing each tool call
and observation over the live bus.
- tests/test_phase1_agent.py: 5 no-mock tests (real bus + demo rag.query;
only the LLM role is scripted) covering dispatch, grounded answers,
budget finalisation, bad-JSON recovery, and no-silent-fallback errors.

hearthnet/services/llm/tools.py

@@ -192,20 +192,27 @@ class ToolExecutor:
                     is_error=True,
                 )
 
-        # 2. Bus-dispatched capability
+        # 2. Bus-dispatched capability.
+        # NOTE: the HearthNet CapabilityBus API is positional:
+        #   bus.call(capability_name, version_tuple, body_dict)
+        # (see hearthnet/bus and ui/tabs/ask.py). An earlier draft constructed a
+        # RouteRequest and called bus.call(req) — that never matched the real bus
+        # and is why the tool path was never exercised. Use the real API here.
         if definition and definition.bound_capability and self._bus is not None:
             try:
-                from hearthnet.bus.router import RouteRequest
-
-                req = RouteRequest(
-                    capability=definition.bound_capability,
-                    version_req=definition.bound_version or (1, 0),
-                    body={"input": call.arguments},
-                    caller="tool-executor",
-                    trace_id=str(uuid.uuid4()),
+                resp = await self._bus.call(
+                    definition.bound_capability,
+                    definition.bound_version or (1, 0),
+                    {"input": call.arguments},
                 )
-                resp = await self._bus.call(req)
-                out = resp.get("output", resp)
+                if isinstance(resp, dict) and "error" in resp:
+                    return ToolResult(
+                        tool_call_id=call.id,
+                        name=call.name,
+                        content={"error": resp.get("message", resp.get("error"))},
+                        is_error=True,
+                    )
+                out = resp.get("output", resp) if isinstance(resp, dict) else resp
                 return ToolResult(
                     tool_call_id=call.id,
                     name=call.name,
@@ -228,38 +235,257 @@ class ToolExecutor:
             is_error=True,
         )
 
+    # ------------------------------------------------------------------
+    # ReAct agent loop
+    # ------------------------------------------------------------------
+
+    def tool_help(self) -> str:
+        """Human/LLM-readable catalogue of the registered tools."""
+        lines = []
+        for t in self._tools.values():
+            props = (t.parameters_schema or {}).get("properties", {})
+            arg_names = ", ".join(props.keys()) if props else ""
+            lines.append(f"- {t.name}({arg_names}): {t.description}")
+        return "\n".join(lines)
+
+    def system_prompt(self) -> str:
+        """Build the ReAct system prompt that teaches the model to call tools.
+
+        Mirrors the proven browser-agent format (webagent/src/agent/runtime.js):
+        the model emits a line ``action: {json}`` to call a tool, and receives an
+        ``Observation:`` back. When it has the answer it replies normally with no
+        ``action:`` line. This JSON-in-text protocol works on tiny models that
+        have no native function-calling API (Tiny Titan friendly).
+        """
+        return (
+            "You are a HearthNet agent. You can use tools to answer questions about "
+            "the local mesh, documents, neighbours, and the world.\n\n"
+            "Available tools:\n"
+            f"{self.tool_help()}\n\n"
+            "To use a tool, output EXACTLY one line:\n"
+            'action: {"tool": "<tool_name>", "<arg>": "<value>"}\n'
+            "Then stop and wait. You will receive a line starting with 'Observation:'.\n"
+            "You may use tools several times. When you have enough information, "
+            "reply to the user directly in plain text with NO 'action:' line.\n"
+            "Keep tool arguments minimal and valid JSON."
+        )
+
+    async def run_react_loop(
+        self,
+        user_text: str,
+        call_llm: Callable[[list[dict]], Any],
+        *,
+        history: list[dict] | None = None,
+        max_iterations: int = 6,
+        on_step: Callable[[dict], Any] | None = None,
+    ) -> dict:
+        """Run a ReAct tool-use loop and return ``{"final", "steps"}``.
+
+        ``call_llm`` is an async callable taking the running message list and
+        returning the assistant text (str). The caller supplies it — typically a
+        thin wrapper around ``bus.call("llm.chat", ...)`` — so this loop has no
+        hard dependency on any particular backend and is fully testable without
+        mocks (a scripted echo backend suffices).
+
+        Each step dict (also passed to ``on_step``) is one of:
+          {"type": "thought", "text": ...}
+          {"type": "tool", "name": ..., "args": ..., "observation": ..., "is_error": ...}
+          {"type": "final", "text": ...}
+        """
+        import asyncio
+        import re
+
+        chat: list[dict] = [{"role": "system", "content": self.system_prompt()}]
+        if history:
+            chat.extend(history)
+        chat.append({"role": "user", "content": user_text})
+
+        steps: list[dict] = []
+
+        async def _emit(step: dict) -> None:
+            steps.append(step)
+            if on_step is not None:
+                res = on_step(step)
+                if asyncio.iscoroutine(res):
+                    await res
+
+        action_re = re.compile(r"action\s*:\s*(\{.*?\})", re.IGNORECASE | re.DOTALL)
+        final_text = ""
+
+        for _ in range(max(1, max_iterations)):
+            raw = await call_llm(chat)
+            text = raw if isinstance(raw, str) else str(raw)
+            match = action_re.search(text)
+
+            if not match:
+                final_text = text.strip()
+                await _emit({"type": "final", "text": final_text})
+                return {"final": final_text, "steps": steps}
+
+            await _emit({"type": "thought", "text": text[: match.start()].strip()})
+
+            try:
+                action = json.loads(match.group(1))
+            except json.JSONDecodeError:
+                chat.append({"role": "assistant", "content": text})
+                chat.append(
+                    {
+                        "role": "user",
+                        "content": "Observation: action JSON was invalid. Re-emit a single valid JSON action.",
+                    }
+                )
+                continue
+
+            tool_name = action.get("tool", "")
+            args = {k: v for k, v in action.items() if k != "tool"}
+            call = ToolCall(id=str(uuid.uuid4()), name=tool_name, arguments=args)
+            result = await self.execute(call)
+            observation = (
+                json.dumps(result.content)
+                if isinstance(result.content, dict)
+                else str(result.content)
+            )
+            await _emit(
+                {
+                    "type": "tool",
+                    "name": tool_name,
+                    "args": args,
+                    "observation": observation[:2000],
+                    "is_error": result.is_error,
+                }
+            )
+            chat.append({"role": "assistant", "content": text})
+            chat.append(
+                {"role": "user", "content": f"Observation from {tool_name}: {observation[:8000]}"}
+            )
+
+        # Iteration budget exhausted — force a final answer.
+        chat.append(
+            {
+                "role": "user",
+                "content": "Observation: tool budget reached. Give your best final answer now, no action.",
+            }
+        )
+        raw = await call_llm(chat)
+        final_text = (raw if isinstance(raw, str) else str(raw)).strip()
+        # Strip any trailing action line the model may still emit.
+        final_text = action_re.sub("", final_text).strip()
+        await _emit({"type": "final", "text": final_text})
+        return {"final": final_text, "steps": steps}
+
     async def run_loop(
         self,
         initial_messages: list[dict],
         max_rounds: int = 5,
     ) -> list[dict]:
-        """Run a full tool-call loop and return the accumulated message list.
-
-        Each round:
-        1. Calls the LLM (not implemented here — caller provides messages so far)
-        2. If the LLM response contains tool calls, executes them
-        3. Appends tool results and continues
+        """OpenAI-style tool-call loop over a pre-populated message list.
 
-        This is a *stub* for the protocol loop — the actual LLM invocation
-        happens in the LLM service (M04) which calls back via the bus.  This
-        helper is used by the Gradio UI (M08) and tests.
+        Used when the LLM backend emits native ``tool_calls`` (OpenAI / Ollama /
+        Nemotron / MiniCPM). For models without native tool calling, use
+        :meth:`run_react_loop` instead.
 
-        Returns the extended message list after all tool rounds are complete.
+        Executes any pending ``tool_calls`` on the last assistant message and
+        appends ``tool`` role result messages. Returns the extended list.
         """
         messages = list(initial_messages)
         for _ in range(max_rounds):
-            # Check for pending tool calls in the last assistant message
             last = messages[-1] if messages else {}
             tool_calls_raw = last.get("tool_calls", [])
             if not tool_calls_raw:
                 break
-            # Execute each tool call
-            tool_results = []
             for tc_raw in tool_calls_raw:
                 tc = ToolCall.from_openai_delta(tc_raw)
                 result = await self.execute(tc)
-                tool_results.append(result)
                 messages.append(result.to_message())
-            # If all results are returned, no more rounds needed
             break
         return messages
+
+
+# ---------------------------------------------------------------------------
+# Default tool set
+# ---------------------------------------------------------------------------
+
+
+def default_tool_set(bus: Any) -> ToolExecutor:
+    """Build a :class:`ToolExecutor` wired to capabilities already on the bus.
+
+    Only read-only / low-risk tools are bound by default. Side-effecting tools
+    (scheduling, peer writes) are excluded so the agent cannot take destructive
+    actions without explicit opt-in. Every tool maps to a REAL capability — there
+    are no mock handlers here. If a capability is not registered on the bus the
+    tool simply errors at call time with a clear message (no silent fallback).
+    """
+    tools = [
+        ToolDefinition(
+            name="search_corpus",
+            description="Search indexed local documents (RAG). Returns matching passages with sources.",
+            parameters_schema={
+                "type": "object",
+                "properties": {
+                    "query": {"type": "string", "description": "Natural-language search query"},
+                    "corpus": {"type": "string", "description": "Optional corpus id to scope the search"},
+                    "top_k": {"type": "integer", "description": "Max passages to return", "default": 4},
+                },
+                "required": ["query"],
+            },
+            bound_capability="rag.query",
+            bound_version=(1, 0),
+        ),
+        ToolDefinition(
+            name="list_corpora",
+            description="List the document corpora available locally for search.",
+            parameters_schema={"type": "object", "properties": {}},
+            bound_capability="rag.list_corpora",
+            bound_version=(1, 0),
+        ),
+        ToolDefinition(
+            name="translate",
+            description="Translate text between languages using a local model.",
+            parameters_schema={
+                "type": "object",
+                "properties": {
+                    "text": {"type": "string"},
+                    "target_lang": {"type": "string", "description": "Target language code, e.g. 'de'"},
+                    "source_lang": {"type": "string", "description": "Optional source language code"},
+                },
+                "required": ["text", "target_lang"],
+            },
+            bound_capability="trans.text",
+            bound_version=(1, 0),
+        ),
+        ToolDefinition(
+            name="list_marketplace",
+            description="List skills/capabilities offered by neighbours on the mesh.",
+            parameters_schema={"type": "object", "properties": {}},
+            bound_capability="market.list",
+            bound_version=(1, 0),
+        ),
+        ToolDefinition(
+            name="route_expert",
+            description="Ask the mixture-of-experts router which local expert should handle a task.",
+            parameters_schema={
+                "type": "object",
+                "properties": {
+                    "task": {"type": "string", "description": "Description of the task to route"},
+                    "tags": {"type": "array", "items": {"type": "string"}},
+                },
+                "required": ["task"],
+            },
+            bound_capability="moe.route",
+            bound_version=(1, 0),
+        ),
+        ToolDefinition(
+            name="identify_plant",
+            description="Identify a plant from an image reference using local vision + LLM.",
+            parameters_schema={
+                "type": "object",
+                "properties": {
+                    "image": {"type": "string", "description": "Image id, path, or data URL"},
+                },
+                "required": ["image"],
+            },
+            bound_capability="tool.plant_identify",
+            bound_version=(1, 0),
+        ),
+    ]
+    return ToolExecutor(tools=tools, bus=bus)

hearthnet/ui/tabs/ask.py

@@ -113,6 +113,12 @@ to the best available LLM node — either on this device or on a peer.
             )
             refresh_corpora_btn = gr.Button("🔄 Refresh Corpora", size="sm", scale=1)
 
+        agent_toggle = gr.Checkbox(
+            label="🤖 Agent mode — the model plans and calls mesh tools "
+            "(search_corpus, list_marketplace, translate, route_expert, …) over several steps",
+            value=False,
+        )
+
         chatbot = gr.Chatbot(
             label="Conversation",
             height=440,
@@ -132,13 +138,21 @@ to the best available LLM node — either on this device or on a peer.
             sources_out = gr.JSON(label="📚 RAG Sources", visible=False, scale=2)
             route_out = gr.JSON(label="🛣️ Routing Trace", visible=False, scale=2)
 
+        agent_out = gr.JSON(label="🧠 Agent Steps (Thought → Tool → Observation)", visible=False)
+
         def refresh_corpora():
             choices = ["(none)", *_get_corpora_sync(bus)]
             return gr.update(choices=choices, value=choices[0])
 
-        async def handle_send(message: str, history: list, corpus: str, model: str):
+        async def handle_send(message: str, history: list, corpus: str, model: str, agent: bool):
             if not message.strip():
-                return history, "", gr.update(visible=False), gr.update(visible=False)
+                return (
+                    history,
+                    "",
+                    gr.update(visible=False),
+                    gr.update(visible=False),
+                    gr.update(visible=False),
+                )
 
             history = history or []
             history.append({"role": "user", "content": message})
@@ -150,7 +164,67 @@ to the best available LLM node — either on this device or on a peer.
                         "content": "⚠️ Bus not connected — run as a real HearthNet node.",
                     }
                 )
-                return history, "", gr.update(visible=False), gr.update(visible=False)
+                return (
+                    history,
+                    "",
+                    gr.update(visible=False),
+                    gr.update(visible=False),
+                    gr.update(visible=False),
+                )
+
+            params: dict = {}
+            if model and model != "auto":
+                params["model"] = model
+
+            # --- Agent mode: multi-step ReAct loop over real mesh tools --------
+            if agent:
+                from hearthnet.services.llm.tools import default_tool_set
+
+                async def _call_llm(msgs: list) -> str:
+                    res = await bus.call(
+                        "llm.chat",
+                        (1, 0),
+                        {"params": dict(params), "input": {"messages": msgs}},
+                    )
+                    if isinstance(res, dict) and "error" in res:
+                        raise RuntimeError(res.get("message", res.get("error", "llm error")))
+                    out = res.get("output", {}) if isinstance(res, dict) else {}
+                    return (
+                        out.get("message", {}).get("content")
+                        or out.get("text")
+                        or ""
+                    )
+
+                executor = default_tool_set(bus)
+                loop_history = [
+                    {"role": h["role"], "content": _msg_text(h["content"])}
+                    for h in history[:-1]
+                ]
+                try:
+                    agent_result = await executor.run_react_loop(
+                        message,
+                        _call_llm,
+                        history=loop_history,
+                        max_iterations=6,
+                    )
+                    reply = agent_result["final"] or "(agent produced no final answer)"
+                    history.append({"role": "assistant", "content": reply})
+                    return (
+                        history,
+                        "",
+                        gr.update(visible=False),
+                        gr.update(visible=False),
+                        gr.update(visible=True, value=agent_result["steps"]),
+                    )
+                except Exception as exc:
+                    history.append({"role": "assistant", "content": f"❌ Agent error: {exc}"})
+                    return (
+                        history,
+                        "",
+                        gr.update(visible=False),
+                        gr.update(visible=False),
+                        gr.update(visible=True, value=[{"type": "error", "text": str(exc)}]),
+                    )
 
             trace: dict = {"rag": None, "llm": None, "routed_to": None}
             try:
@@ -197,10 +271,6 @@ to the best available LLM node — either on this device or on a peer.
                     {"role": h["role"], "content": _msg_text(h["content"])} for h in history
                 )
 
-                params: dict = {}
-                if model and model != "auto":
-                    params["model"] = model
-
                 result = await bus.call(
                     "llm.chat",
                     (1, 0),
@@ -233,6 +303,7 @@ to the best available LLM node — either on this device or on a peer.
                     "",
                     gr.update(visible=bool(sources), value=sources),
                     gr.update(visible=True, value=trace),
+                    gr.update(visible=False),
                 )
 
             except Exception as exc:
@@ -243,16 +314,17 @@ to the best available LLM node — either on this device or on a peer.
                     "",
                     gr.update(visible=False),
                     gr.update(visible=True, value=trace),
+                    gr.update(visible=False),
                 )
 
         refresh_corpora_btn.click(refresh_corpora, outputs=corpus_selector)
         send_btn.click(
             handle_send,
-            inputs=[msg_input, chatbot, corpus_selector, model_selector],
-            outputs=[chatbot, msg_input, sources_out, route_out],
+            inputs=[msg_input, chatbot, corpus_selector, model_selector, agent_toggle],
+            outputs=[chatbot, msg_input, sources_out, route_out, agent_out],
         )
         msg_input.submit(
             handle_send,
-            inputs=[msg_input, chatbot, corpus_selector, model_selector],
-            outputs=[chatbot, msg_input, sources_out, route_out],
+            inputs=[msg_input, chatbot, corpus_selector, model_selector, agent_toggle],
+            outputs=[chatbot, msg_input, sources_out, route_out, agent_out],
         )

tests/test_phase1_agent.py

@@ -0,0 +1,106 @@
+"""Phase 1 agent loop — M21 tool calls wired to the real capability bus.
+
+No mocks: the bus, registry, router and demo ``rag.query`` capability are all
+real in-process components. The only scripted piece is the LLM *role* itself
+(``call_llm``), which is legitimate — a deterministic local stand-in for the
+model's text output, exactly what a tiny local model would emit.
+"""
+
+from __future__ import annotations
+
+import asyncio
+
+from hearthnet.node import InMemoryNetwork
+from hearthnet.services.llm.tools import ToolCall, ToolExecutor, default_tool_set
+
+
+def _caller_with_demo():
+    network = InMemoryNetwork()
+    caller = network.add_node("ed25519:caller", "caller")
+    provider = network.add_node("ed25519:provider", "provider")
+    provider.install_demo_services()
+    network.mesh_discover()
+    return caller
+
+
+def test_execute_dispatches_tool_to_real_bus() -> None:
+    caller = _caller_with_demo()
+    executor = default_tool_set(caller.bus)
+
+    result = asyncio.run(
+        executor.execute(
+            ToolCall(id="t1", name="search_corpus", arguments={"query": "clean water"})
+        )
+    )
+
+    assert result.is_error is False
+    chunks = result.content["chunks"]
+    assert chunks[0]["metadata"]["doc_title"] == "Water"
+
+
+def test_react_loop_grounds_answer_in_tool_result() -> None:
+    caller = _caller_with_demo()
+    executor = default_tool_set(caller.bus)
+
+    async def call_llm(messages: list[dict]) -> str:
+        # Once the bus has handed back an Observation, answer; otherwise call a tool.
+        if any("Observation from" in str(m.get("content", "")) for m in messages):
+            return "Based on the corpus, the mesh has a Water document about clean water."
+        return 'action: {"tool": "search_corpus", "query": "clean water"}'
+
+    out = asyncio.run(executor.run_react_loop("Tell me about clean water", call_llm))
+
+    assert "Water" in out["final"]
+    tool_steps = [s for s in out["steps"] if s["type"] == "tool"]
+    assert tool_steps and tool_steps[0]["name"] == "search_corpus"
+    assert tool_steps[0]["is_error"] is False
+    assert out["steps"][-1]["type"] == "final"
+
+
+def test_react_loop_finalises_when_budget_exhausted() -> None:
+    caller = _caller_with_demo()
+    executor = default_tool_set(caller.bus)
+
+    async def call_llm(messages: list[dict]) -> str:
+        # Never stops calling tools on its own — force the budget guard to engage.
+        if any("budget reached" in str(m.get("content", "")) for m in messages):
+            return "Final answer after the tool budget was reached."
+        return 'action: {"tool": "list_marketplace"}'
+
+    out = asyncio.run(
+        executor.run_react_loop("keep going", call_llm, max_iterations=2)
+    )
+
+    assert out["final"].startswith("Final answer")
+    tool_steps = [s for s in out["steps"] if s["type"] == "tool"]
+    assert len(tool_steps) == 2
+
+
+def test_react_loop_recovers_from_bad_action_json() -> None:
+    caller = _caller_with_demo()
+    executor = default_tool_set(caller.bus)
+    calls = {"n": 0}
+
+    async def call_llm(messages: list[dict]) -> str:
+        calls["n"] += 1
+        if calls["n"] == 1:
+            return 'action: {not valid json}'
+        return "Recovered and answering directly."
+
+    out = asyncio.run(executor.run_react_loop("hi", call_llm))
+
+    assert out["final"] == "Recovered and answering directly."
+    assert calls["n"] == 2
+
+
+def test_unbound_tool_errors_without_silent_fallback() -> None:
+    # A tool whose capability is not on the bus must error clearly, not fabricate.
+    caller = _caller_with_demo()
+    executor = ToolExecutor(bus=caller.bus, tools=default_tool_set(caller.bus).definitions())
+
+    result = asyncio.run(
+        executor.execute(ToolCall(id="x", name="translate", arguments={"text": "hi", "target_lang": "de"}))
+    )
+
+    assert result.is_error is True
+    assert "error" in result.content