glaip-sdk 0.0.19__py3-none-any.whl → 0.1.0__py3-none-any.whl

glaip_sdk/utils/rendering/renderer/config.py

@@ -24,10 +24,8 @@ class RendererConfig:
     live: bool = True
     persist_live: bool = True
 
-    # Debug visibility toggles
-    show_delegate_tool_panels: bool = False
-
     # Scrollback/append options
+    summary_max_steps: int = 0
     append_finished_snapshots: bool = False
-    snapshot_max_chars: int = 12000
-    snapshot_max_lines: int = 200
+    snapshot_max_chars: int = 0
+    snapshot_max_lines: int = 0

glaip_sdk/utils/rendering/renderer/debug.py

@@ -5,25 +5,76 @@ Authors:
 """
 
 import json
-from datetime import datetime
-from time import monotonic
+from datetime import datetime, timezone
 from typing import Any
 
 from rich.console import Console
 from rich.markdown import Markdown
 
+from glaip_sdk.branding import PRIMARY, SUCCESS, WARNING
 from glaip_sdk.rich_components import AIPPanel
 
 
-def _calculate_relative_time(started_ts: float | None) -> tuple[float, str]:
-    """Calculate relative time since start."""
-    now_mono = monotonic()
+def _coerce_datetime(value: Any) -> datetime | None:
+    """Attempt to coerce an arbitrary value to an aware datetime."""
+    if value is None:
+        return None
+
+    if isinstance(value, datetime):
+        return value if value.tzinfo else value.replace(tzinfo=timezone.utc)
+
+    if isinstance(value, str):
+        try:
+            normalised = value.replace("Z", "+00:00")
+            dt = datetime.fromisoformat(normalised)
+        except ValueError:
+            return None
+        return dt if dt.tzinfo else dt.replace(tzinfo=timezone.utc)
+
+    return None
+
+
+def _parse_event_timestamp(
+    event: dict[str, Any], received_ts: datetime | None = None
+) -> datetime | None:
+    """Resolve the most accurate timestamp available for the event."""
+    if received_ts is not None:
+        return (
+            received_ts
+            if received_ts.tzinfo
+            else received_ts.replace(tzinfo=timezone.utc)
+        )
+
+    ts_value = event.get("timestamp") or (event.get("metadata") or {}).get("timestamp")
+    return _coerce_datetime(ts_value)
+
+
+def _format_timestamp_for_display(dt: datetime) -> str:
+    """Format timestamp for panel title, including timezone offset."""
+    local_dt = dt.astimezone()
+    ts_ms = local_dt.strftime("%H:%M:%S.%f")[:-3]
+    offset = local_dt.strftime("%z")
+    # offset is always non-empty for timezone-aware datetimes
+    offset = f"{offset[:3]}:{offset[3:]}"
+    return f"{ts_ms} {offset}"
+
+
+def _calculate_relative_time(
+    event_ts: datetime | None,
+    baseline_ts: datetime | None,
+) -> tuple[float, str]:
+    """Calculate relative time since start and format event timestamp."""
     rel = 0.0
-    if started_ts is not None:
-        rel = max(0.0, now_mono - started_ts)
 
-    ts_full = datetime.now().strftime("%H:%M:%S.%f")
-    ts_ms = ts_full[:-3]  # trim to milliseconds
+    # Determine display timestamp - use event timestamp when present, otherwise current time
+    display_ts: datetime | None = event_ts
+    if display_ts is None:
+        display_ts = datetime.now(timezone.utc)
+
+    if event_ts is not None and baseline_ts is not None:
+        rel = max(0.0, (event_ts - baseline_ts).total_seconds())
+
+    ts_ms = _format_timestamp_for_display(display_ts)
 
     return rel, ts_ms
 
@@ -75,10 +126,10 @@ def _format_event_json(event: dict[str, Any]) -> str:
 def _get_border_color(sse_kind: str) -> str:
     """Get border color for event type."""
     border_map = {
-        "agent_step": "blue",
-        "content": "green",
-        "final_response": "green",
-        "status": "yellow",
+        "agent_step": PRIMARY,
+        "content": SUCCESS,
+        "final_response": SUCCESS,
+        "status": WARNING,
         "artifact": "grey42",
     }
     return border_map.get(sse_kind, "grey42")
@@ -91,18 +142,24 @@ def _create_debug_panel(title: str, event_json: str, border: str) -> AIPPanel:
 
 
 def render_debug_event(
-    event: dict[str, Any], console: Console, started_ts: float | None = None
+    event: dict[str, Any],
+    console: Console,
+    *,
+    received_ts: datetime | None = None,
+    baseline_ts: datetime | None = None,
 ) -> None:
     """Render a debug panel for an SSE event.
 
     Args:
         event: The SSE event data
         console: Rich console to print to
-        started_ts: Monotonic timestamp when streaming started
+        received_ts: Client-side receipt timestamp, if available
+        baseline_ts: Baseline event timestamp for elapsed timing
     """
     try:
         # Calculate timing information
-        rel, ts_ms = _calculate_relative_time(started_ts)
+        event_ts = _parse_event_timestamp(event, received_ts)
+        rel, ts_ms = _calculate_relative_time(event_ts, baseline_ts)
 
         # Extract event metadata
         sse_kind, status_str = _get_event_metadata(event)

glaip_sdk/utils/rendering/renderer/panels.py

@@ -11,6 +11,7 @@ from rich.markdown import Markdown
 from rich.spinner import Spinner
 from rich.text import Text
 
+from glaip_sdk.branding import INFO, PRIMARY, SUCCESS, WARNING
 from glaip_sdk.rich_components import AIPPanel
 
 
@@ -19,7 +20,7 @@ def _spinner_renderable(message: str = "Processing...") -> Align:
     spinner = Spinner(
         "dots",
         text=Text(f" {message}", style="dim"),
-        style="cyan",
+        style=INFO,
     )
     return Align.left(spinner)
 
@@ -39,13 +40,13 @@ def create_main_panel(content: str, title: str, theme: str = "dark") -> AIPPanel
         return AIPPanel(
             Markdown(content, code_theme=("monokai" if theme == "dark" else "github")),
             title=title,
-            border_style="green",
+            border_style=SUCCESS,
         )
     else:
         return AIPPanel(
             _spinner_renderable(),
             title=title,
-            border_style="green",
+            border_style=SUCCESS,
         )
 
 
@@ -55,6 +56,8 @@ def create_tool_panel(
     status: str = "running",
     theme: str = "dark",
     is_delegation: bool = False,
+    *,
+    spinner_message: str | None = None,
 ) -> AIPPanel:
     """Create a tool execution panel.
 
@@ -64,22 +67,29 @@ def create_tool_panel(
         status: Tool execution status
         theme: Color theme
         is_delegation: Whether this is a delegation tool
+        spinner_message: Optional custom message to show alongside the spinner
 
     Returns:
         Rich Panel instance
     """
-    mark = "✓" if status == "finished" else "⟳"
-    border_style = "magenta" if is_delegation else "blue"
+    mark = "✓" if status == "finished" else ""
+    border_style = WARNING if is_delegation else PRIMARY
 
-    body_renderable = (
-        Markdown(content, code_theme=("monokai" if theme == "dark" else "github"))
-        if content
-        else _spinner_renderable()
-    )
+    if content:
+        body_renderable = Markdown(
+            content,
+            code_theme=("monokai" if theme == "dark" else "github"),
+        )
+    elif status == "running":
+        body_renderable = _spinner_renderable(spinner_message or f"{title} running...")
+    else:
+        body_renderable = Text("No output yet.", style="dim")
+
+    title_text = f"{title}  {mark}".rstrip()
 
     return AIPPanel(
         body_renderable,
-        title=f"{title}  {mark}",
+        title=title_text,
         border_style=border_style,
     )
 
@@ -103,15 +113,17 @@ def create_context_panel(
     Returns:
         Rich Panel instance
     """
-    mark = "✓" if status == "finished" else "⟳"
-    border_style = "magenta" if is_delegation else "cyan"
+    mark = "✓" if status == "finished" else ""
+    border_style = WARNING if is_delegation else INFO
+
+    title_text = f"{title}  {mark}".rstrip()
 
     return AIPPanel(
         Markdown(
             content,
             code_theme=("monokai" if theme == "dark" else "github"),
         ),
-        title=f"{title}  {mark}",
+        title=title_text,
         border_style=border_style,
     )
 
@@ -132,6 +144,6 @@ def create_final_panel(
     return AIPPanel(
         Markdown(content, code_theme=("monokai" if theme == "dark" else "github")),
         title=title,
-        border_style="green",
+        border_style=SUCCESS,
         padding=(0, 1),
     )

glaip_sdk/utils/rendering/renderer/progress.py

@@ -16,40 +16,52 @@ def get_spinner() -> str:
     return get_spinner_char()
 
 
+def _resolve_elapsed_time(
+    started_at: float | None,
+    server_elapsed_time: float | None,
+    streaming_started_at: float | None,
+) -> float | None:
+    """Return the elapsed seconds using server data when available."""
+    if server_elapsed_time is not None and streaming_started_at is not None:
+        return server_elapsed_time
+    if started_at is None:
+        return None
+    try:
+        return monotonic() - started_at
+    except Exception:
+        return None
+
+
+def _format_elapsed_suffix(elapsed: float) -> str:
+    """Return formatting suffix for elapsed timing."""
+    if elapsed >= 1:
+        return f"{elapsed:.2f}s"
+    elapsed_ms = int(elapsed * 1000)
+    return f"{elapsed_ms}ms" if elapsed_ms > 0 else "<1ms"
+
+
 def format_working_indicator(
     started_at: float | None,
     server_elapsed_time: float | None = None,
     streaming_started_at: float | None = None,
 ) -> str:
-    """Format a working indicator with elapsed time.
+    """Format a working indicator with elapsed time."""
+    base_message = "Working..."
 
-    Args:
-        started_at: Timestamp when work started, or None
-        server_elapsed_time: Server-reported elapsed time if available
-        streaming_started_at: When streaming started
-
-    Returns:
-        Formatted working indicator string with elapsed time
-    """
-    chip = "Working..."
+    if started_at is None and (
+        server_elapsed_time is None or streaming_started_at is None
+    ):
+        return base_message
 
-    # Use server timing if available (more accurate)
-    if server_elapsed_time is not None and streaming_started_at is not None:
-        elapsed = server_elapsed_time
-    elif started_at:
-        try:
-            elapsed = monotonic() - started_at
-        except Exception:
-            return chip
-    else:
-        return chip
+    spinner_chip = f"{get_spinner_char()} {base_message}"
+    elapsed = _resolve_elapsed_time(
+        started_at, server_elapsed_time, streaming_started_at
+    )
+    if elapsed is None:
+        return spinner_chip
 
-    if elapsed >= 1:
-        chip = f"Working... ({elapsed:.2f}s)"
-    else:
-        elapsed_ms = int(elapsed * 1000)
-        chip = f"Working... ({elapsed_ms}ms)" if elapsed_ms > 0 else "Working... (<1ms)"
-    return chip
+    suffix = _format_elapsed_suffix(elapsed)
+    return f"{spinner_chip} ({suffix})"
 
 
 def format_elapsed_time(elapsed_seconds: float) -> str:
@@ -88,6 +100,24 @@ def is_delegation_tool(tool_name: str) -> bool:
     )
 
 
+def _delegation_tool_title(tool_name: str) -> str | None:
+    """Return delegation-aware title or ``None`` when not applicable."""
+    if tool_name.startswith("delegate_to_"):
+        sub_agent_name = tool_name.replace("delegate_to_", "", 1)
+        return f"Sub-Agent: {sub_agent_name}"
+    if tool_name.startswith("delegate_"):
+        sub_agent_name = tool_name.replace("delegate_", "", 1)
+        return f"Sub-Agent: {sub_agent_name}"
+    return None
+
+
+def _strip_path_and_extension(tool_name: str) -> str:
+    """Return tool name without path segments or extensions."""
+    filename = tool_name.rsplit("/", 1)[-1]
+    base_name = filename.split(".", 1)[0]
+    return base_name
+
+
 def format_tool_title(tool_name: str) -> str:
     """Format tool name for panel title display.
 
@@ -99,20 +129,13 @@ def format_tool_title(tool_name: str) -> str:
     """
     # Check if this is a delegation tool
     if is_delegation_tool(tool_name):
-        # Extract the sub-agent name from delegation tool names
-        if tool_name.startswith("delegate_to_"):
-            sub_agent_name = tool_name.replace("delegate_to_", "")
-            return f"Sub-Agent: {sub_agent_name}"
-        elif tool_name.startswith("delegate_"):
-            sub_agent_name = tool_name.replace("delegate_", "")
-            return f"Sub-Agent: {sub_agent_name}"
+        delegation_title = _delegation_tool_title(tool_name)
+        if delegation_title:
+            return delegation_title
 
     # For regular tools, clean up the name
     # Remove file path prefixes if present
-    if "/" in tool_name:
-        tool_name = tool_name.split("/")[-1]
-    if "." in tool_name:
-        tool_name = tool_name.split(".")[0]
+    clean_name = _strip_path_and_extension(tool_name)
 
     # Convert snake_case to Title Case
-    return tool_name.replace("_", " ").title()
+    return clean_name.replace("_", " ").title()

glaip_sdk/utils/rendering/renderer/stream.py

@@ -38,7 +38,7 @@ class StreamProcessor:
         Returns:
             Dictionary with extracted metadata
         """
-        metadata = event.get("metadata", {})
+        metadata = event.get("metadata") or {}
         # Update server elapsed timing if backend provides it
         try:
             t = metadata.get("time")
@@ -49,8 +49,8 @@ class StreamProcessor:
 
         return {
             "kind": metadata.get("kind") if metadata else event.get("kind"),
-            "task_id": event.get("task_id"),
-            "context_id": event.get("context_id"),
+            "task_id": metadata.get("task_id") or event.get("task_id"),
+            "context_id": metadata.get("context_id") or event.get("context_id"),
             "content": event.get("content", ""),
             "status": metadata.get("status") if metadata else event.get("status"),
             "metadata": metadata,

glaip_sdk/utils/rendering/renderer/toggle.py

@@ -0,0 +1,184 @@
+"""Keyboard-driven transcript toggling support for the live renderer.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import threading
+import time
+from typing import Any
+
+try:  # pragma: no cover - Windows-specific dependencies
+    import msvcrt  # type: ignore[import]
+except ImportError:  # pragma: no cover - POSIX fallback
+    msvcrt = None  # type: ignore[assignment]
+
+if os.name != "nt":  # pragma: no cover - POSIX-only imports
+    import select
+    import termios
+    import tty
+
+
+CTRL_T = "\x14"
+
+
+class TranscriptToggleController:
+    """Manage mid-run transcript toggling for RichStreamRenderer instances."""
+
+    def __init__(self, *, enabled: bool) -> None:
+        """Initialise controller.
+
+        Args:
+            enabled: Whether toggling should be active (usually gated by TTY checks).
+        """
+        self._enabled = enabled and bool(sys.stdin) and sys.stdin.isatty()
+        self._lock = threading.Lock()
+        self._posix_fd: int | None = None
+        self._posix_attrs: list[int] | None = None
+        self._active = False
+        self._stop_event = threading.Event()
+        self._poll_thread: threading.Thread | None = None
+
+    @property
+    def enabled(self) -> bool:
+        """Return True when controller is able to process keypresses."""
+        return self._enabled
+
+    def on_stream_start(self, renderer: Any) -> None:
+        """Prepare terminal state before streaming begins."""
+        if not self._enabled:
+            return
+
+        if os.name == "nt":  # pragma: no cover - Windows behaviour not in CI
+            self._active = True
+            self._start_polling_thread(renderer)
+            return
+
+        fd = sys.stdin.fileno()
+        try:
+            attrs = termios.tcgetattr(fd)
+        except Exception:
+            self._enabled = False
+            return
+
+        try:
+            tty.setcbreak(fd)
+        except Exception:
+            try:
+                termios.tcsetattr(fd, termios.TCSADRAIN, attrs)
+            except Exception:
+                pass
+            self._enabled = False
+            return
+
+        with self._lock:
+            self._posix_fd = fd
+            self._posix_attrs = attrs
+            self._active = True
+
+        self._start_polling_thread(renderer)
+
+    def on_stream_complete(self) -> None:
+        """Restore terminal state when streaming ends."""
+        if not self._active:
+            return
+
+        self._stop_polling_thread()
+
+        if os.name == "nt":  # pragma: no cover - Windows behaviour not in CI
+            self._active = False
+            return
+
+        with self._lock:
+            fd = self._posix_fd
+            attrs = self._posix_attrs
+            self._posix_fd = None
+            self._posix_attrs = None
+            self._active = False
+
+        if fd is None or attrs is None:
+            return
+
+        try:
+            termios.tcsetattr(fd, termios.TCSADRAIN, attrs)
+        except Exception:
+            pass
+
+    def poll(self, renderer: Any) -> None:
+        """Poll for toggle keypresses and update renderer if needed."""
+        if not self._active:
+            return
+
+        if os.name == "nt":  # pragma: no cover - Windows behaviour not in CI
+            self._poll_windows(renderer)
+        else:
+            self._poll_posix(renderer)
+
+    # ------------------------------------------------------------------
+    # Platform-specific polling
+    # ------------------------------------------------------------------
+    def _poll_windows(self, renderer: Any) -> None:
+        if not msvcrt:  # pragma: no cover - safety guard
+            return
+
+        while msvcrt.kbhit():
+            ch = msvcrt.getwch()
+            if ch == CTRL_T:
+                renderer.toggle_transcript_mode()
+
+    def _poll_posix(self, renderer: Any) -> None:  # pragma: no cover - requires TTY
+        fd = self._posix_fd
+        if fd is None:
+            return
+
+        while True:
+            readable, _, _ = select.select([fd], [], [], 0)
+            if not readable:
+                return
+
+            try:
+                data = os.read(fd, 1)
+            except Exception:
+                return
+
+            if not data:
+                return
+
+            ch = data.decode(errors="ignore")
+            if ch == CTRL_T:
+                renderer.toggle_transcript_mode()
+
+    def _start_polling_thread(self, renderer: Any) -> None:
+        if self._poll_thread and self._poll_thread.is_alive():
+            return
+        if not self._active:
+            return
+
+        self._stop_event.clear()
+        self._poll_thread = threading.Thread(
+            target=self._poll_loop, args=(renderer,), daemon=True
+        )
+        self._poll_thread.start()
+
+    def _stop_polling_thread(self) -> None:
+        self._stop_event.set()
+        thread = self._poll_thread
+        if thread and thread.is_alive():
+            thread.join(timeout=0.2)
+        self._poll_thread = None
+
+    def _poll_loop(self, renderer: Any) -> None:
+        while self._active and not self._stop_event.is_set():
+            try:
+                if os.name == "nt":
+                    self._poll_windows(renderer)
+                else:
+                    self._poll_posix(renderer)
+            except Exception:
+                # Never let background polling disrupt the main stream
+                pass
+            time.sleep(0.05)

glaip_sdk/utils/rendering/step_tree_state.py

@@ -0,0 +1,102 @@
+"""State container for hierarchical renderer steps.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from dataclasses import dataclass, field
+
+from glaip_sdk.utils.rendering.models import Step
+
+
+@dataclass(slots=True)
+class StepTreeState:
+    """Track hierarchical ordering, buffers, and pruning metadata."""
+
+    max_steps: int = 200
+    root_order: list[str] = field(default_factory=list)
+    child_map: dict[str, list[str]] = field(default_factory=dict)
+    buffered_children: dict[str, list[str]] = field(default_factory=dict)
+    running_by_context: dict[tuple[str | None, str | None], set[str]] = field(
+        default_factory=dict
+    )
+    retained_ids: set[str] = field(default_factory=set)
+    step_index: dict[str, Step] = field(default_factory=dict)
+    pending_branch_failures: set[str] = field(default_factory=set)
+
+    def link_root(self, step_id: str) -> None:
+        """Ensure a step id is present in the root ordering."""
+        if step_id not in self.root_order:
+            self.root_order.append(step_id)
+
+    def unlink_root(self, step_id: str) -> None:
+        """Remove a step id from the root ordering if present."""
+        if step_id in self.root_order:
+            self.root_order.remove(step_id)
+
+    def link_child(self, parent_id: str, child_id: str) -> None:
+        """Attach a child step to a parent."""
+        children = self.child_map.setdefault(parent_id, [])
+        if child_id not in children:
+            children.append(child_id)
+
+    def unlink_child(self, parent_id: str, child_id: str) -> None:
+        """Detach a child from a parent."""
+        children = self.child_map.get(parent_id)
+        if not children:
+            return
+
+        if child_id in children:
+            children.remove(child_id)
+        # Clean up if the list is now empty
+        if len(children) == 0:
+            self.child_map.pop(parent_id, None)
+
+    def buffer_child(self, parent_id: str, child_id: str) -> None:
+        """Track a child that is waiting for its parent to appear."""
+        queue = self.buffered_children.setdefault(parent_id, [])
+        if child_id not in queue:
+            queue.append(child_id)
+
+    def pop_buffered_children(self, parent_id: str) -> list[str]:
+        """Return any buffered children for a parent."""
+        return self.buffered_children.pop(parent_id, [])
+
+    def discard_running(self, step_id: str) -> None:
+        """Remove a step from running context tracking."""
+        for key, running in tuple(self.running_by_context.items()):
+            if step_id in running:
+                running.discard(step_id)
+                if not running:
+                    self.running_by_context.pop(key, None)
+
+    def iter_visible_tree(self) -> Iterator[tuple[str, tuple[bool, ...]]]:
+        """Yield step ids in depth-first order alongside branch metadata.
+
+        Returns:
+            Iterator of (step_id, branch_state) tuples where branch_state
+            captures whether each ancestor was the last child. This data
+            is later used by rendering helpers to draw connectors such as
+            `│`, `├─`, and `└─` consistently.
+        """
+        roots = tuple(self.root_order)
+        total_roots = len(roots)
+        for index, root_id in enumerate(roots):
+            yield root_id, ()
+            ancestor_state = (index == total_roots - 1,)
+            yield from self._walk_children(root_id, ancestor_state)
+
+    def _walk_children(
+        self, parent_id: str, ancestor_state: tuple[bool, ...]
+    ) -> Iterator[tuple[str, tuple[bool, ...]]]:
+        """Depth-first traversal helper yielding children with ancestry info."""
+        children = self.child_map.get(parent_id, [])
+        total_children = len(children)
+        for idx, child_id in enumerate(children):
+            is_last = idx == total_children - 1
+            branch_state = ancestor_state + (is_last,)
+            yield child_id, branch_state
+            yield from self._walk_children(child_id, branch_state)