fruxon 0.5.2__tar.gz → 0.5.3__tar.gz

{fruxon-0.5.2 → fruxon-0.5.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fruxon
-Version: 0.5.2
+Version: 0.5.3
 Summary: The Fruxon SDK is a lightweight Python client for integrating with the Fruxon platform.
 Project-URL: bugs, https://github.com/fruxon-ai/fruxon-sdk/issues
 Project-URL: changelog, https://github.com/fruxon-ai/fruxon-sdk/blob/main/HISTORY.md

{fruxon-0.5.2 → fruxon-0.5.3}/src/fruxon/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.5.2'
-__version_tuple__ = version_tuple = (0, 5, 2)
+__version__ = version = '0.5.3'
+__version_tuple__ = version_tuple = (0, 5, 3)
 
 __commit_id__ = commit_id = None

{fruxon-0.5.2 → fruxon-0.5.3}/src/fruxon/cli/run.py

@@ -333,8 +333,10 @@ def _run_stream(
     # Live spinner area at the bottom of stderr for currently-running tools.
     # Disabled when stderr isn't a TTY (pipes, CI logs) — those consumers
     # can't render cursor-movement updates anyway, and our merge-only
-    # fallback gives them clean line-per-tool output.
-    spinner_area = _ToolSpinnerArea(enabled=stderr.is_terminal)
+    # fallback gives them clean line-per-tool output. ``verbose`` flows
+    # through so the live rows expand args inline while running, not just
+    # once each tool completes.
+    spinner_area = _ToolSpinnerArea(enabled=stderr.is_terminal, verbose=verbose)
 
     try:
         for event in client.stream(agent, parameters=parameters, session_id=session_id):
@@ -364,19 +366,22 @@ def _run_stream(
                 break_text_line()
                 tool_id_raw = event.data.get("id")
                 tool_id = str(tool_id_raw) if tool_id_raw is not None else ""
-                # 1. Drop this id from the running set *first* so the next
-                #    Live refresh-tick redraws without its spinner row.
-                # 2. ``_render_tool_result`` prints the permanent merged row
-                #    via the same stderr console Live is attached to —
-                #    Rich automatically routes that print *above* the live
-                #    area instead of stopping/restarting it. No flicker.
-                # 3. Refresh updates the Live's renderable to the reduced
-                #    set; if empty, the renderable becomes a zero-line
-                #    placeholder (still no stop, no flicker).
+                # Order matters for smooth rendering:
+                # 1. Drop from running_ids and push the new (smaller)
+                #    renderable into Live *before* printing anything. If
+                #    we printed first, Rich's Live would redraw the
+                #    permanent row above the *old* renderable — leaving
+                #    the completed tool's spinner row visible for one
+                #    frame, which reads as a flash.
+                # 2. Emit the permanent row as a single console.print of
+                #    a Group. One print = one Live clear+redraw, instead
+                #    of one per line (merged line, each args line, each
+                #    result line). Bundling is what makes verbose /
+                #    failure expansion stop flickering.
                 if tool_id in running_ids:
                     running_ids.remove(tool_id)
-                _render_tool_result(event.data, tools_state, verbose=verbose)
                 spinner_area.refresh(running_ids, tools_state)
+                _render_tool_result(event.data, tools_state, verbose=verbose)
                 continue
 
             if event.event == "error":
@@ -539,19 +544,26 @@ def _render_tool_result(
         args_preview = _format_args(arguments)
         if args_preview:
             line += f" [dim]{args_preview}[/dim]"
-    stderr.print(line)
 
-    # Failure auto-expand: show the full args + result body. Same rationale
-    # as before — a failed tool with only a one-liner is unactionable.
+    # Build the full block (header + optional expanded args + optional
+    # expanded result) and emit it as ONE console.print. When a Live
+    # spinner area is active above us on the same console, each print
+    # call triggers a clear-and-redraw of the live area; one print per
+    # completed tool keeps that to a single redraw instead of N.
     expand = verbose or is_failure
+    detail_lines: list[str] = []
     if expand:
-        # Args were not printed inline (verbose drops the preview; failure
-        # gets the full block here regardless). Show the full args + the
-        # full result body so the user has everything they need without
-        # rerunning.
         if arguments is not None:
-            _render_args_detail(arguments)
-        _render_result_detail(data.get("result"), is_failure=is_failure)
+            detail_lines.extend(_args_detail_lines(arguments))
+        detail_lines.extend(_result_detail_lines(data.get("result"), is_failure=is_failure))
+
+    if detail_lines:
+        from rich.console import Group
+        from rich.text import Text
+
+        stderr.print(Group(Text.from_markup(line), *(Text.from_markup(d) for d in detail_lines)))
+    else:
+        stderr.print(line)
 
 
 # ─────────────────────────────────────────────────────────────────────────────
@@ -587,8 +599,15 @@ class _ToolSpinnerArea:
     gives them clean line-per-tool output.
     """
 
-    def __init__(self, *, enabled: bool) -> None:
+    def __init__(self, *, enabled: bool, verbose: bool = False) -> None:
         self._enabled = enabled
+        # ``verbose`` matches the ``fruxon run -v`` flag. Without it the
+        # spinner row is a single line with truncated args (what fits at
+        # a glance). With it, each running tool gets a multi-line block
+        # showing every argument keyed-and-aligned — the same expansion
+        # the permanent completion row uses, just visible *while* the
+        # tool is running instead of only after it finishes.
+        self._verbose = verbose
         self._live = None  # rich.live.Live | None — lazy start
 
     def refresh(self, running_ids: list[str], state: dict[str, dict[str, object]]) -> None:
@@ -627,6 +646,20 @@ class _ToolSpinnerArea:
         lines drawn, but the underlying Live stays alive so the next
         tool dispatch updates in place rather than triggering a fresh
         start (which would flicker).
+
+        Verbose mode expands each tool into:
+
+            ⠋ #1 list_commits
+                owner     fruxon-ai
+                repo      fruxon-backend
+                per_page  100
+
+        Compact mode keeps it to one line with a truncated arg preview:
+
+            ⠋ #1 list_commits  owner=fruxon-ai, repo=fruxon-backend, …
+
+        The spinner only animates on the header line; the args block
+        below it is static, which keeps the live area redraw cheap.
         """
         from rich.console import Group
         from rich.spinner import Spinner
@@ -640,15 +673,26 @@ class _ToolSpinnerArea:
             entry = state.get(tid) or {}
             name = entry.get("name", "tool")
             index = entry.get("index")
+            arguments = entry.get("arguments")
             tag = f"[dim]#{index}[/dim] " if isinstance(index, int) else ""
-            label = f"{tag}[bold]{name}[/bold]"
-            args_preview = _format_args(entry.get("arguments"))
-            if args_preview:
-                label += f" [dim]{args_preview}[/dim]"
-            # ``dots`` matches the spinner used by ``rich.console.status``
-            # — the same visual language as the spinners in
-            # ``fruxon agents list`` and ``fruxon trace`` fetches.
-            rows.append(Spinner("dots", text=label, style="cyan"))
+
+            if self._verbose:
+                # Header gets the spinner; args block stays static below.
+                header = Spinner("dots", text=f"{tag}[bold]{name}[/bold]", style="cyan")
+                args_block = _format_args_block(arguments)
+                if args_block is not None:
+                    rows.append(Group(header, args_block))
+                else:
+                    rows.append(header)
+            else:
+                label = f"{tag}[bold]{name}[/bold]"
+                args_preview = _format_args(arguments)
+                if args_preview:
+                    label += f" [dim]{args_preview}[/dim]"
+                # ``dots`` matches the spinner used by
+                # ``rich.console.status`` — same visual language as the
+                # spinners in ``fruxon agents list`` and ``fruxon trace``.
+                rows.append(Spinner("dots", text=label, style="cyan"))
         return Group(*rows)
 
 
@@ -661,60 +705,78 @@ _DETAIL_INDENT = "    "  # 4 spaces — visually nests under the #N tag column
 _DETAIL_VALUE_MAX = 200  # per-value cap; full payloads still live in `trace`
 
 
-def _render_args_detail(arguments: object) -> None:
-    """Pretty-print tool-call arguments as an indented detail block.
+def _args_detail_lines(arguments: object) -> list[str]:
+    """Produce the formatted line strings for an args detail block.
 
-    Three shapes the backend emits in practice:
+    Pure function — returns lines, doesn't print. The lines are
+    rich-markup-aware (``[dim]…[/dim]`` etc.) and use ``_DETAIL_INDENT``
+    so they nest visually under whatever they appear below.
 
-    * ``dict`` — render as ``key  value`` rows with the key column padded
-      so values line up vertically. Most tool calls are dicts.
-    * ``str``  — render as a quoted line. Common for tools that take a
-      single freeform string (search queries, prompts).
-    * other (list, scalar, None) — JSON-dump as a single line.
+    Shared by the permanent completion row (bundled into a single
+    Group print to avoid Live redraw flicker) and the live spinner
+    area (wraps the lines inside the Live renderable while a tool is
+    still running).
 
-    Long individual values are truncated to ``_DETAIL_VALUE_MAX`` chars.
-    Anyone needing the full payload can pull the run via ``fruxon trace``.
+    Three argument shapes:
+      ``dict`` — ``key  value`` rows, key column padded to longest key.
+      ``str``  — single quoted-ish line, truncated to value cap.
+      other   — JSON-dump on one line.
     """
     if arguments is None:
-        return
+        return []
     if isinstance(arguments, dict):
         if not arguments:
-            return
+            return []
         # Pad keys to the longest one so values line up — same trick the
         # ``whoami`` and ``agents get`` views use for kv rows.
         key_width = max(len(str(k)) for k in arguments)
-        for key, value in arguments.items():
-            rendered_value = _render_detail_value(value)
-            stderr.print(f"[dim]{_DETAIL_INDENT}{str(key):<{key_width}}[/dim]  {rendered_value}")
-        return
+        return [
+            f"[dim]{_DETAIL_INDENT}{str(key):<{key_width}}[/dim]  {_render_detail_value(value)}"
+            for key, value in arguments.items()
+        ]
     if isinstance(arguments, str):
-        stderr.print(f"[dim]{_DETAIL_INDENT}{_truncate(arguments, _DETAIL_VALUE_MAX)}[/dim]")
-        return
-    stderr.print(f"[dim]{_DETAIL_INDENT}{_render_detail_value(arguments)}[/dim]")
+        return [f"[dim]{_DETAIL_INDENT}{_truncate(arguments, _DETAIL_VALUE_MAX)}[/dim]"]
+    return [f"[dim]{_DETAIL_INDENT}{_render_detail_value(arguments)}[/dim]"]
+
 
+def _format_args_block(arguments: object):
+    """Return a Rich renderable of the indented args block, or ``None``.
+
+    Used by the live spinner area to embed full argument details under
+    the running tool's header line when ``--verbose`` is on. Returns
+    ``None`` when there are no args worth rendering (empty dict, ``None``,
+    etc.) so the caller can skip the block entirely.
+    """
+    lines = _args_detail_lines(arguments)
+    if not lines:
+        return None
+    from rich.console import Group
+    from rich.text import Text
+
+    return Group(*(Text.from_markup(line) for line in lines))
 
-def _render_result_detail(result: object, *, is_failure: bool) -> None:
-    """Pretty-print a tool result under the completion line.
 
-    Strings render as-is (most tool results are unstructured text);
-    structured payloads are JSON-dumped one item per line. Failures get
-    a red tint so they're scannable in a wall of green checks.
+def _result_detail_lines(result: object, *, is_failure: bool) -> list[str]:
+    """Produce formatted line strings for a tool-result detail block.
+
+    Pure function — returns rich-markup lines. Strings render as-is;
+    structured payloads are JSON-dumped one item per line, capped at 20.
+    Failures get a red tint so they're scannable in a wall of green
+    checks. The caller decides whether to print line-by-line or bundle
+    into one renderable (the streaming path bundles to avoid Live
+    redraw flicker).
     """
     if result is None:
-        return
+        return []
     style = "red" if is_failure else "dim"
     if isinstance(result, str):
         text = _truncate(result, _DETAIL_VALUE_MAX * 3)  # results can be longer than args
-        for line in text.splitlines() or [text]:
-            stderr.print(f"[{style}]{_DETAIL_INDENT}{line}[/{style}]")
-        return
-    # Structured — render as pretty JSON, capped to keep the block scannable.
+        return [f"[{style}]{_DETAIL_INDENT}{line}[/{style}]" for line in (text.splitlines() or [text])]
     try:
         rendered = json.dumps(result, indent=2, ensure_ascii=False)
     except (TypeError, ValueError):
         rendered = str(result)
-    for line in rendered.splitlines()[:20]:  # cap at 20 lines; full payload via `trace`
-        stderr.print(f"[{style}]{_DETAIL_INDENT}{line}[/{style}]")
+    return [f"[{style}]{_DETAIL_INDENT}{line}[/{style}]" for line in rendered.splitlines()[:20]]
 
 
 def _render_detail_value(value: object) -> str:

{fruxon-0.5.2 → fruxon-0.5.3}/tests/test_cli.py

@@ -1637,6 +1637,185 @@ class TestRunStreamPath:
         assert result.exit_code == 0
         assert unique not in result.stderr
 
+    def test_stream_tool_result_refreshes_spinner_before_printing(self, runner, monkeypatch):
+        """Live spinner area is updated to drop the completed tool *before*
+        the permanent completion row is printed.
+
+        Why this order matters: Rich's Live re-renders the live area below
+        the cursor on every console.print to the same console. If we print
+        first, Live redraws using the *old* renderable that still contains
+        the just-completed tool's spinner row — a one-frame flash that
+        reads as flicker. Refreshing first means the live area below the
+        printed row already reflects the reduced set.
+        """
+        credentials.save(credentials.StoredCredentials(api_key="fxn_x", org="acme"))
+
+        from fruxon.cli import run as run_mod
+        from fruxon.fruxon import StreamEvent
+
+        events = [
+            StreamEvent(
+                event="tool_call",
+                data={
+                    "id": "1",
+                    "toolTrace": {"displayName": "ping"},
+                    "arguments": {"host": "example.com"},
+                    "startTime": 0,
+                },
+            ),
+            StreamEvent(
+                event="tool_result",
+                data={"id": "1", "endTime": 50, "status": "SUCCESS"},
+            ),
+            StreamEvent(event="done", data={"trace": {}}),
+        ]
+
+        class _StubClient:
+            DEFAULT_BASE_URL = "https://api.fruxon.com"
+
+            def __init__(self, **kwargs):
+                pass
+
+            def stream(self, agent, **kwargs):
+                yield from events
+
+        # Record refreshes and prints into one ordered log. Each entry is
+        # ("refresh", running_ids_snapshot) or ("print",). We only care
+        # about prints that come from the streaming completion path —
+        # everything emitted *during* a tool_result event.
+        log: list[tuple] = []
+
+        real_refresh = run_mod._ToolSpinnerArea.refresh
+
+        def fake_refresh(self, running_ids, state):
+            log.append(("refresh", list(running_ids)))
+            return real_refresh(self, running_ids, state)
+
+        real_print = run_mod.stderr.print
+
+        def fake_print(*args, **kwargs):
+            log.append(("print",))
+            return real_print(*args, **kwargs)
+
+        monkeypatch.setattr(run_mod._ToolSpinnerArea, "refresh", fake_refresh)
+        monkeypatch.setattr(run_mod.stderr, "print", fake_print)
+        monkeypatch.setattr("fruxon.cli.run.FruxonClient", _StubClient)
+
+        result = runner.invoke(app, ["run", "my-agent"])
+        assert result.exit_code == 0
+
+        # Find the refresh that drops the completed tool (running_ids == [])
+        # and the *next* print after it. That print must be a tool-result
+        # row, not preceded by an extra print that would have triggered
+        # a Live redraw with the stale renderable still in place.
+        empty_refresh_idx = next(i for i, entry in enumerate(log) if entry == ("refresh", []))
+        # Everything between the previous refresh (still containing the
+        # tool) and this one must NOT include a print — that's the bug
+        # the ordering fix prevents.
+        prev_refresh_idx = next(i for i, entry in enumerate(log) if entry == ("refresh", ["1"]))
+        between = log[prev_refresh_idx + 1 : empty_refresh_idx]
+        assert ("print",) not in between, (
+            "spinner area must be refreshed (dropping completed tool) "
+            "BEFORE the permanent row is printed — otherwise Live redraws "
+            "with the stale renderable and the row flashes"
+        )
+
+    def test_stream_failure_block_emitted_as_single_print(self, runner, monkeypatch):
+        """Failure auto-expansion (header + args block + result block) is
+        emitted as ONE ``stderr.print`` call.
+
+        Each print to the Live's console triggers a clear-and-redraw of
+        the spinner area below. Emitting N prints per completed tool —
+        the merged row, plus each indented args line, plus each result
+        line — produces N flickers. Bundling into a single Group keeps
+        it to one redraw.
+        """
+        credentials.save(credentials.StoredCredentials(api_key="fxn_x", org="acme"))
+
+        from fruxon.cli import run as run_mod
+        from fruxon.fruxon import StreamEvent
+
+        events = [
+            StreamEvent(
+                event="tool_call",
+                data={
+                    "id": "1",
+                    "toolTrace": {"displayName": "fetch_url"},
+                    "arguments": {"url": "https://broken.example", "retries": 3},
+                    "startTime": 0,
+                },
+            ),
+            StreamEvent(
+                event="tool_result",
+                data={
+                    "id": "1",
+                    "endTime": 100,
+                    "status": "ERROR",
+                    "result": "line one\nline two\nline three",
+                },
+            ),
+            StreamEvent(event="done", data={"trace": {}}),
+        ]
+
+        class _StubClient:
+            DEFAULT_BASE_URL = "https://api.fruxon.com"
+
+            def __init__(self, **kwargs):
+                pass
+
+            def stream(self, agent, **kwargs):
+                yield from events
+
+        # Count prints that occur between the tool_result handling's
+        # spinner refresh and the next refresh (the "done" path's
+        # spinner.close doesn't refresh). One print is the success
+        # criterion; >1 would mean we're back to flickering.
+        prints_during_result: list[object] = []
+        in_result_window = {"on": False}
+
+        real_refresh = run_mod._ToolSpinnerArea.refresh
+
+        def fake_refresh(self, running_ids, state):
+            # The refresh with running_ids=[] runs inside the tool_result
+            # handler *before* the bundled print — open the window then.
+            if not running_ids:
+                in_result_window["on"] = True
+            return real_refresh(self, running_ids, state)
+
+        real_print = run_mod.stderr.print
+
+        def fake_print(*args, **kwargs):
+            if in_result_window["on"]:
+                prints_during_result.append(args[0] if args else None)
+            return real_print(*args, **kwargs)
+
+        monkeypatch.setattr(run_mod._ToolSpinnerArea, "refresh", fake_refresh)
+        monkeypatch.setattr(run_mod.stderr, "print", fake_print)
+        monkeypatch.setattr("fruxon.cli.run.FruxonClient", _StubClient)
+
+        result = runner.invoke(app, ["run", "my-agent"])
+        assert result.exit_code == 0
+
+        # Exactly one print for the whole expanded failure block —
+        # header + args (2 keys) + result (3 lines) would have been
+        # 6 separate prints under the old code. One print here is
+        # the bundling guarantee.
+        assert len(prints_during_result) == 1, (
+            f"expected one bundled print for the completion block, got {len(prints_during_result)} — flicker regression"
+        )
+        # And the bundled renderable carries the full payload — args
+        # keys, the URL, and every result line.
+        from rich.console import Console
+
+        buf = Console(record=True, file=open("/dev/null", "w"))
+        buf.print(prints_during_result[0])
+        rendered = buf.export_text()
+        assert "fetch_url" in rendered
+        assert "https://broken.example" in rendered
+        assert "retries" in rendered
+        assert "line one" in rendered
+        assert "line three" in rendered
+
     def test_stream_renders_tool_calls_to_stderr(self, runner, monkeypatch):
         credentials.save(credentials.StoredCredentials(api_key="fxn_x", org="acme"))