feat(cli): cohesive terminal UX — shared tables, empty states, error hygiene

Author: ctrl-gaurav

effgen/cli/_main.py

@@ -18,6 +18,7 @@
 import json
 import logging
 import os
+import sys
 import time
 from datetime import datetime
 from pathlib import Path
@@ -64,6 +65,13 @@ def __init__(self, cli: Any, args: Any):
         self.quiet = getattr(args, "quiet", False)
         self.verbose = getattr(args, "verbose", False)
         self.animate = cli._animate(args)
+        # A piped session (``echo hi | effgen chat``) has no terminal to show a
+        # transient "Thinking…" indicator on, so the placeholder is suppressed
+        # there and only the labeled answer and footer are emitted.
+        try:
+            self.interactive = sys.stdin.isatty() and sys.stdout.isatty()
+        except (ValueError, OSError):  # pragma: no cover - closed std streams
+            self.interactive = False
 
         self.model_id = getattr(args, "model", None) or self.DEFAULT_MODEL
         self.preset = getattr(args, "preset", None)
@@ -105,6 +113,30 @@ def __init__(self, cli: Any, args: Any):
                 self._preset_system_prompt = _preset_cfg.system_prompt
                 self._preset_temperature = _preset_cfg.temperature
 
+        # Tools named with --tools/-t start attached (in addition to any the
+        # preset brought), matching `effgen run --tools`. An unknown name is
+        # reported with a close-match hint rather than silently ignored.
+        requested_tools = getattr(args, "tools", None) or []
+        if requested_tools:
+            try:
+                registry = self.cli.tool_registry
+                registry.discover_builtin_tools()
+                available = set(registry.list_tools())
+            except Exception:  # noqa: BLE001 - never let tool discovery sink startup
+                available = set()
+            for name in requested_tools:
+                if available and name not in available:
+                    import difflib
+
+                    hint = difflib.get_close_matches(name, sorted(available), n=1)
+                    suffix = f" Did you mean: {hint[0]}?" if hint else ""
+                    self.cli.print_warning(
+                        f"No tool named '{name}'.{suffix} See: effgen tools list"
+                    )
+                    continue
+                if name not in self.tool_names:
+                    self.tool_names.append(name)
+
         self.agent: Any = None
         self.session_tokens = 0
         self.session_cost = 0.0
@@ -514,13 +546,14 @@ def _stream_plain(self, user_input: str) -> str:
                         first = tok
                         break
         else:
-            if not self.quiet:
+            show_placeholder = not self.quiet and self.interactive
+            if show_placeholder:
                 print("Thinking…", end="", flush=True)
             for tok in gen:
                 if tok:
                     first = tok
                     break
-            if not self.quiet:
+            if show_placeholder:
                 print("\r" + " " * 10 + "\r", end="", flush=True)
 
         if self.console:
@@ -552,7 +585,7 @@ def _run_with_tools(self, user_input: str) -> str:
             ):
                 response = self.agent.run(user_input, mode=AgentMode.AUTO)
         else:
-            if not self.quiet:
+            if not self.quiet and self.interactive:
                 print("Thinking…")
             response = self.agent.run(user_input, mode=AgentMode.AUTO)
 

effgen/cli/chat.py

@@ -21,6 +21,7 @@
 
 from __future__ import annotations
 
+import json
 import os
 import sys
 import time
@@ -374,6 +375,42 @@ def _truncate(value: Any, limit: int) -> str:
     return text if len(text) <= limit else text[: limit - 1] + "…"
 
 
+def format_tool_call(name: str, tool_input: Any, limit: int = 72) -> str:
+    """Render a tool call as ``name(key="value", …)`` on one balanced line.
+
+    ``tool_input`` may be a dict of arguments or a JSON string of one; either
+    is shown as compact ``key="value"`` pairs. Anything else is shown as a
+    single truncated argument. The parentheses always close — a call trimmed to
+    fit ends in ``…)`` rather than a dangling ``,`` or an unbalanced brace.
+    """
+    args: Any = tool_input
+    if isinstance(args, str):
+        text = args.strip()
+        if text[:1] in ("{", "["):
+            try:
+                args = json.loads(text)
+            except (ValueError, TypeError):
+                args = text
+        else:
+            args = text
+
+    if isinstance(args, dict):
+        parts = []
+        for key, val in args.items():
+            if isinstance(val, str):
+                rendered = f'{key}="{val}"'
+            else:
+                rendered = f"{key}={val}"
+            parts.append(rendered.replace("\n", " "))
+        inner = ", ".join(parts)
+    else:
+        inner = str(args).replace("\n", " ")
+
+    if len(inner) > limit:
+        inner = inner[: limit - 1].rstrip(", ") + "…"
+    return f"{name}({inner})"
+
+
 def execution_trace_lines(trace: list[dict[str, Any]] | None) -> list[tuple[str, str]]:
     """Turn an :class:`ExecutionTracker` event trace into readable ``(style, text)``.
 
@@ -394,9 +431,10 @@ def execution_trace_lines(trace: list[dict[str, Any]] | None) -> list[tuple[str,
         elif etype == "tool_call_start":
             name = data.get("tool_name", "tool")
             tool_input = data.get("tool_input", data.get("input", ""))
-            detail = f"🔧 {name}"
             if tool_input:
-                detail += f"({_truncate(tool_input, 80)})"
+                detail = f"🔧 {format_tool_call(name, tool_input)}"
+            else:
+                detail = f"🔧 {name}"
             out.append(("green", detail))
         elif etype == "tool_call_complete":
             result = data.get("result", data.get("output", ""))

effgen/cli/progress.py

@@ -34,6 +34,11 @@
 # works without ``--query-field``.
 _QUERY_ALIASES = ("query", "input", "prompt", "question", "text")
 
+# File extensions ``write_results`` can serialize a batch to. The CLI checks a
+# requested ``--output`` against this set up front so an unsupported extension
+# fails before any billed call rather than after the whole run.
+SUPPORTED_OUTPUT_FORMATS = (".jsonl", ".json", ".csv")
+
 
 def _resolve_row_query(obj: dict[str, Any], query_field: str) -> str:
     """Return a row's query text, trying *query_field* then the common aliases.
@@ -317,7 +322,10 @@ def write_results(
                     for row in rows:
                         writer.writerow(BatchRunner._csv_flatten(row))
         else:
-            raise ValueError(f"Unsupported output format: {suffix}")
+            raise ValueError(
+                f"Unsupported output format: {suffix}. "
+                f"Use one of: {', '.join(SUPPORTED_OUTPUT_FORMATS)}."
+            )
 
         logger.info("Wrote %d results to %s", len(rows), path)
 

effgen/core/batch.py

@@ -21,12 +21,15 @@
     response_show,
     response_trace,
 )
+from .tables import console_is_interactive, render_table
 from .theme import EFFGEN_THEME, color_enabled, get_console, rich_available
 
 __all__ = [
     "EFFGEN_THEME",
     "color_enabled",
+    "console_is_interactive",
     "get_console",
+    "render_table",
     "rich_available",
     "answer_renderable",
     "format_cost",

effgen/ui/__init__.py

@@ -0,0 +1,115 @@
+"""Aligned table rendering shared by the CLI listing/results commands.
+
+Renders a Rich table on an interactive terminal and a clean, aligned
+plain-text table when output is piped or Rich is unavailable, so the results
+commands (``eval``, ``compare``, ``cost``, ``sessions list``) read as one
+family without adding box-drawing or color to piped/``--json`` output.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any
+
+from .theme import rich_available
+
+
+def console_is_interactive(console: Any) -> bool:
+    """True when *console* writes to a real terminal (not a pipe or file)."""
+    return bool(console is not None and getattr(console, "is_terminal", False))
+
+
+def render_table(
+    *,
+    columns: Sequence[str],
+    rows: Sequence[Sequence[Any]],
+    console: Any = None,
+    title: str | None = None,
+    justify: Sequence[str] | None = None,
+    styles: Sequence[str | None] | None = None,
+    footer: Sequence[str] | None = None,
+    caption: str | None = None,
+    file: Any = None,
+) -> None:
+    """Print *rows* under *columns* as a table.
+
+    A Rich table (with the shared theme) is used on an interactive terminal;
+    output that is piped or redirected gets an aligned plain-text table with no
+    box-drawing characters or color, so a ``| command | grep`` pipeline stays
+    readable. ``justify`` is a per-column ``"left"``/``"right"``/``"center"``
+    list; ``styles`` a per-column Rich style (ignored in the plain path);
+    ``footer`` a per-column footer row; ``caption`` a trailing note.
+
+    ``file`` forces the plain-text path to a specific stream (e.g. ``stderr``);
+    a caller routing human output away from stdout under ``--json`` passes it so
+    the table never lands on the JSON stream.
+    """
+    cell_rows = [["" if c is None else str(c) for c in row] for row in rows]
+    if file is None and rich_available() and console_is_interactive(console):
+        _render_rich(console, columns, cell_rows, title, justify, styles, footer, caption)
+    else:
+        _render_plain(columns, cell_rows, title, justify, footer, caption, file)
+
+
+def _render_rich(
+    console: Any,
+    columns: Sequence[str],
+    rows: Sequence[Sequence[str]],
+    title: str | None,
+    justify: Sequence[str] | None,
+    styles: Sequence[str | None] | None,
+    footer: Sequence[str] | None,
+    caption: str | None,
+) -> None:
+    from rich.table import Table
+
+    table = Table(title=title, caption=caption, show_footer=footer is not None)
+    for i, col in enumerate(columns):
+        table.add_column(
+            col,
+            justify=(justify[i] if justify and i < len(justify) else "left"),
+            style=(styles[i] if styles and i < len(styles) else None),
+            footer=(footer[i] if footer and i < len(footer) else ""),
+            overflow="fold",
+        )
+    for row in rows:
+        table.add_row(*row)
+    console.print(table)
+
+
+def _render_plain(
+    columns: Sequence[str],
+    rows: Sequence[Sequence[str]],
+    title: str | None,
+    justify: Sequence[str] | None,
+    footer: Sequence[str] | None,
+    caption: str | None,
+    file: Any = None,
+) -> None:
+    n = len(columns)
+    body = list(rows) + ([list(footer)] if footer else [])
+    widths = [len(str(columns[i])) for i in range(n)]
+    for row in body:
+        for i in range(n):
+            cell = str(row[i]) if i < len(row) else ""
+            widths[i] = max(widths[i], len(cell))
+
+    def _fmt(row: Sequence[str]) -> str:
+        cells = []
+        for i in range(n):
+            cell = str(row[i]) if i < len(row) else ""
+            right = bool(justify and i < len(justify) and justify[i] == "right")
+            cells.append(cell.rjust(widths[i]) if right else cell.ljust(widths[i]))
+        return "  ".join(cells).rstrip()
+
+    if title:
+        print(title, file=file)
+    print(_fmt(list(columns)), file=file)
+    print("  ".join("-" * w for w in widths), file=file)
+    for row in rows:
+        print(_fmt(row), file=file)
+    if footer:
+        print("  ".join("-" * w for w in widths), file=file)
+        print(_fmt(list(footer)), file=file)
+    if caption:
+        print(caption, file=file)