deepagents-cli 0.0.56__tar.gz → 0.0.57__tar.gz

{deepagents_cli-0.0.56 → deepagents_cli-0.0.57}/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Deep Agents CLI Changelog
 
+## [0.0.57](https://github.com/langchain-ai/deepagents/compare/deepagents-cli==0.0.56...deepagents-cli==0.0.57) (2026-05-12)
+
+### Features
+
+* OSC 9;4 progress & escape helper ([#3347](https://github.com/langchain-ai/deepagents/issues/3347)) ([75d60cd](https://github.com/langchain-ai/deepagents/commit/75d60cd82f559b2944b78a348d16b0a10a00d663))
+
+### Bug Fixes
+
+* Suppress LangSmith trace for `_context_tokens` state writes ([#3317](https://github.com/langchain-ai/deepagents/issues/3317)) ([63db13e](https://github.com/langchain-ai/deepagents/commit/63db13ee262d19a1a87fbe4df1271a2e958deed6))
+
 ## [0.0.56](https://github.com/langchain-ai/deepagents/compare/deepagents-cli==0.0.55...deepagents-cli==0.0.56) (2026-05-11)
 
 ### Features

{deepagents_cli-0.0.56 → deepagents_cli-0.0.57}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deepagents-cli
-Version: 0.0.56
+Version: 0.0.57
 Summary: Terminal interface for Deep Agents - interactive AI agent with file operations, shell access, and sub-agent capabilities.
 Project-URL: Homepage, https://docs.langchain.com/oss/python/deepagents/overview
 Project-URL: Documentation, https://reference.langchain.com/python/deepagents/

{deepagents_cli-0.0.56 → deepagents_cli-0.0.57}/deepagents_cli/_env_vars.py

@@ -110,6 +110,9 @@ KITTY_KEYBOARD = "DEEPAGENTS_CLI_KITTY_KEYBOARD"
 LANGSMITH_PROJECT = "DEEPAGENTS_CLI_LANGSMITH_PROJECT"
 """Override LangSmith project name for agent traces."""
 
+NO_TERMINAL_ESCAPE = "DEEPAGENTS_CLI_NO_TERMINAL_ESCAPE"
+"""Disable all terminal escape/control sequence output when enabled."""
+
 NO_UPDATE_CHECK = "DEEPAGENTS_CLI_NO_UPDATE_CHECK"
 """Disable automatic update checking when set."""
 

{deepagents_cli-0.0.56 → deepagents_cli-0.0.57}/deepagents_cli/_version.py

@@ -1,6 +1,6 @@
 """Version information and lightweight constants for `deepagents-cli`."""
 
-__version__ = "0.0.56"  # x-release-please-version
+__version__ = "0.0.57"  # x-release-please-version
 
 DOCS_URL = "https://docs.langchain.com/oss/python/deepagents/cli"
 """URL for `deepagents-cli` documentation."""

{deepagents_cli-0.0.56 → deepagents_cli-0.0.57}/deepagents_cli/app.py

@@ -1151,6 +1151,7 @@ class DeepAgentsApp(App):
         Loaded from the user's saved preference (or the default) so the app
         boots with consistent colors before `/theme` runs.
         """
+        self.sync_terminal_background()
 
         # Injected session config
         self._agent = agent
@@ -3290,19 +3291,61 @@ class DeepAgentsApp(App):
 
         return children[-1] == self._loading_widget
 
+    def sync_terminal_background(self) -> None:
+        """Best-effort sync of terminal default background to the active theme.
+
+        Custom themes use their stored registry colors; built-in Textual themes
+        resolve colors from the active app theme. Terminal write failures are
+        logged and swallowed because the OSC background sync is cosmetic.
+        """
+        from deepagents_cli.terminal_escape import set_terminal_background
+
+        entry = theme.get_registry().get(self.theme)
+        colors = (
+            entry.colors
+            if entry is not None and entry.custom
+            else theme.get_theme_colors(self)
+        )
+        try:
+            set_terminal_background(colors.background)
+        except Exception:
+            # Cosmetic only: must never break app startup or theme changes.
+            logger.warning("set_terminal_background raised unexpectedly", exc_info=True)
+
     async def _set_spinner(self, status: SpinnerStatus) -> None:
         """Show, update, or hide the loading spinner.
 
+        Also drives the terminal's `OSC 9;4` progress indicator, when
+        supported, so taskbar / dock / tab badges reflect agent activity while
+        the user is in another window.
+
         Args:
             status: The spinner status to display, or `None` to hide.
         """
+        from deepagents_cli.terminal_escape import (
+            TerminalProgressState,
+            clear_terminal_progress,
+            set_terminal_progress,
+        )
+
         if status is None:
             # Hide
             if self._loading_widget:
                 await self._loading_widget.remove()
                 self._loading_widget = None
+            try:
+                clear_terminal_progress()
+            except Exception:
+                # Cosmetic only — must never break spinner lifecycle.
+                logger.exception("clear_terminal_progress raised unexpectedly")
             return
 
+        try:
+            set_terminal_progress(state=TerminalProgressState.INDETERMINATE)
+        except Exception:
+            # Cosmetic only — must never break spinner lifecycle.
+            logger.exception("set_terminal_progress raised unexpectedly")
+
         try:
             messages = self.query_one("#messages", Container)
         except NoMatches:
@@ -6582,6 +6625,15 @@ class DeepAgentsApp(App):
             ).encode()
             _dispatch_hook_sync("session.end", payload, hooks)
 
+        from deepagents_cli.terminal_escape import reset_terminal_background
+
+        try:
+            reset_terminal_background()
+        except Exception:
+            # Cosmetic only: must never raise during shutdown.
+            logger.warning(
+                "reset_terminal_background raised unexpectedly", exc_info=True
+            )
         restore_iterm_cursor_guide()
         super().exit(result=result, return_code=return_code, message=message)
 
@@ -6986,6 +7038,7 @@ class DeepAgentsApp(App):
             """Handle the theme selector result."""
             if result is not None:
                 self.theme = result
+                self.sync_terminal_background()
                 self.refresh_css(animate=False)
 
                 async def _persist() -> None:

deepagents_cli-0.0.57/deepagents_cli/terminal_escape.py

@@ -0,0 +1,287 @@
+"""Best-effort writer for terminal escape/control sequences.
+
+Centralizes the "fire and forget" pattern the CLI uses for cosmetic terminal
+control (OSC 9;4 taskbar progress today; eventually OSC 52 clipboard and the
+iTerm2 cursor guide). Writes prefer `/dev/tty` so output reaches the terminal
+even when stdout/stderr are redirected, fall back to `sys.__stderr__`, and
+never raise — cosmetic control output must not crash the app.
+
+Set `DEEPAGENTS_CLI_NO_TERMINAL_ESCAPE=1` to disable all output (useful for
+unsupported terminals or noisy logs).
+"""
+
+from __future__ import annotations
+
+import atexit
+import logging
+import pathlib
+import sys
+import threading
+from enum import StrEnum
+from typing import TYPE_CHECKING
+
+from deepagents_cli._env_vars import NO_TERMINAL_ESCAPE, is_env_truthy
+
+if TYPE_CHECKING:
+    from typing import TextIO
+
+logger = logging.getLogger(__name__)
+
+_PROGRESS_MIN = 0
+"""Lower clamp bound for determinate `OSC 9;4` progress percentages."""
+
+_PROGRESS_MAX = 100
+"""Upper clamp bound for determinate `OSC 9;4` progress percentages."""
+
+
+class TerminalProgressState(StrEnum):
+    """`OSC 9;4` progress states.
+
+    See https://learn.microsoft.com/en-us/windows/terminal/tutorials/progress-bar-sequences.
+    """
+
+    CLEAR = "0"
+    """Remove any progress indicator. Percentage is ignored."""
+
+    NORMAL = "1"
+    """Determinate progress shown with the default (success) color."""
+
+    ERROR = "2"
+    """Determinate progress shown with the error/red color."""
+
+    INDETERMINATE = "3"
+    """Activity in progress with no known percentage; renders as a pulse."""
+
+    WARNING = "4"
+    """Determinate progress shown with the warning/yellow color."""
+
+
+def _is_disabled() -> bool:
+    """Return whether terminal-escape output is opt-out disabled."""
+    return is_env_truthy(NO_TERMINAL_ESCAPE)
+
+
+def _open_tty() -> TextIO | None:
+    """Return an open `/dev/tty` handle, or `None` if unavailable."""
+    try:
+        return pathlib.Path("/dev/tty").open("w", encoding="utf-8")
+    except OSError:
+        return None
+
+
+def _is_stream_tty(stream: TextIO | None) -> bool:
+    """Return whether `stream` is a real TTY."""
+    if stream is None:
+        return False
+    try:
+        return bool(stream.isatty())
+    except (ValueError, OSError):
+        return False
+
+
+def write_terminal_escape(sequence: str) -> bool:
+    r"""Best-effort write of a terminal control sequence.
+
+    Prefers `/dev/tty` so the sequence reaches the terminal even when stdout
+    or stderr are redirected. Falls back to `sys.__stderr__` only if it is a
+    TTY.
+
+    Returns `False` (no-op) when output is disabled or no TTY is reachable.
+
+    Args:
+        sequence: Raw escape sequence to write, including leading `\x1b`/`ESC`
+            and terminator.
+
+    Returns:
+        `True` if the sequence was written and flushed without error.
+    """
+    if _is_disabled() or not sequence:
+        return False
+    tty = _open_tty()
+    if tty is not None:
+        try:
+            with tty:
+                tty.write(sequence)
+                tty.flush()
+        except (OSError, UnicodeError) as exc:
+            logger.debug("terminal_escape /dev/tty write failed: %s", exc)
+        else:
+            return True
+    stderr = sys.__stderr__
+    if stderr is not None and _is_stream_tty(stderr):
+        try:
+            stderr.write(sequence)
+            stderr.flush()
+        except (OSError, ValueError) as exc:
+            logger.debug("terminal_escape stderr write failed: %s", exc)
+            return False
+        return True
+    return False
+
+
+def write_osc(command: str, payload: str = "", *, st: bool = False) -> bool:
+    r"""Write an `OSC <command>;<payload>` sequence.
+
+    Args:
+        command: The numeric OSC command (e.g. ``"9;4"`` for taskbar progress).
+        payload: Optional semicolon-joined payload appended after the command.
+        st: When `True`, terminate with String Terminator (`ESC \`) instead of
+            the default BEL (`\a`).
+
+            BEL matches the Windows Terminal docs and works on most terminals;
+            VTE-derived terminals may prefer ST.
+
+    Returns:
+        `True` if the sequence was written.
+    """
+    body = f"{command};{payload}" if payload else command
+    terminator = "\x1b\\" if st else "\a"
+    return write_terminal_escape(f"\x1b]{body}{terminator}")
+
+
+_progress_active = False
+_terminal_background_active = False
+_atexit_registered = False
+_atexit_lock = threading.Lock()
+
+
+def _ensure_atexit_registered() -> None:
+    """Register terminal-state cleanup exactly once."""
+    global _atexit_registered  # noqa: PLW0603
+
+    with _atexit_lock:
+        if not _atexit_registered:
+            atexit.register(_atexit_clear)
+            _atexit_registered = True
+
+
+def _validate_progress(progress: int | None, state: TerminalProgressState) -> int:
+    """Clamp/normalize `progress` for a given `state`.
+
+    Determinate states (`NORMAL`, `ERROR`, `WARNING`) clamp to `[0, 100]`;
+    `INDETERMINATE` and `CLEAR` always emit `0`. A non-`None` `progress`
+    supplied with `CLEAR`/`INDETERMINATE` is dropped with a debug log so
+    misuse stays observable without raising on a cosmetic write path. A
+    `progress` that can't be coerced to `int` is treated the same way.
+
+    Args:
+        progress: Raw percentage, or `None`.
+        state: The OSC 9;4 progress state.
+
+    Returns:
+        The normalized progress integer to emit.
+    """
+    if state in {TerminalProgressState.CLEAR, TerminalProgressState.INDETERMINATE}:
+        if progress is not None and progress != 0:
+            logger.debug(
+                "terminal_progress: ignoring progress=%r for state=%s",
+                progress,
+                state.name,
+            )
+        return 0
+    if progress is None:
+        return 0
+    try:
+        coerced = int(progress)
+    except (TypeError, ValueError) as exc:
+        logger.debug(
+            "terminal_progress: non-numeric progress=%r ignored (%s)", progress, exc
+        )
+        return 0
+    return max(_PROGRESS_MIN, min(_PROGRESS_MAX, coerced))
+
+
+def set_terminal_progress(
+    progress: int | None = None,
+    *,
+    state: TerminalProgressState = TerminalProgressState.NORMAL,
+) -> bool:
+    """Set the terminal's `OSC 9;4` progress indicator.
+
+    Fires unconditionally — terminals that don't recognize `OSC 9;4` silently
+    ignore the sequence. Set `DEEPAGENTS_CLI_NO_TERMINAL_ESCAPE=1` to opt out
+    entirely.
+
+    Args:
+        progress: Percentage `0-100` for determinate states. Ignored for
+            `INDETERMINATE` and `CLEAR`.
+        state: One of `TerminalProgressState`.
+
+    Returns:
+        `True` if the sequence was written.
+    """
+    global _progress_active  # noqa: PLW0603
+
+    value = _validate_progress(progress, state)
+    payload = f"{state.value};{value}"
+    written = write_osc("9;4", payload)
+    if written and state is not TerminalProgressState.CLEAR:
+        _ensure_atexit_registered()
+        _progress_active = True
+    elif state is TerminalProgressState.CLEAR:
+        _progress_active = False
+    return written
+
+
+def clear_terminal_progress() -> bool:
+    """Clear the terminal's progress indicator.
+
+    Emits `OSC 9;4;0;0`.
+
+    Returns:
+        `True` if the sequence was written.
+    """
+    return set_terminal_progress(state=TerminalProgressState.CLEAR)
+
+
+def set_terminal_background(color: str) -> bool:
+    """Set the terminal's dynamic default background color with `OSC 11`.
+
+    This is cosmetic and intentionally best-effort. Terminals that don't
+    support `OSC 11` ignore it; `OSC 111` is emitted from `atexit` to restore
+    the default background when this call succeeds.
+
+    Args:
+        color: Terminal color payload, usually a CSS-style hex color such as
+            `#11121D`.
+
+    Returns:
+        `True` if the sequence was written.
+    """
+    global _terminal_background_active  # noqa: PLW0603
+
+    if not color:
+        return False
+    written = write_osc("11", color, st=True)
+    if written:
+        _ensure_atexit_registered()
+        _terminal_background_active = True
+    return written
+
+
+def reset_terminal_background() -> bool:
+    """Reset the terminal's dynamic default background color with `OSC 111`.
+
+    Returns:
+        `True` if the sequence was written.
+    """
+    global _terminal_background_active  # noqa: PLW0603
+
+    written = write_osc("111", st=True)
+    if written:
+        _terminal_background_active = False
+    return written
+
+
+def _atexit_clear() -> None:
+    """`atexit` hook that clears any leftover terminal state."""
+    if _progress_active:
+        try:
+            clear_terminal_progress()
+        except Exception:
+            logger.warning("Failed to clear terminal progress at exit", exc_info=True)
+    if _terminal_background_active:
+        try:
+            reset_terminal_background()
+        except Exception:
+            logger.warning("Failed to reset terminal background at exit", exc_info=True)

{deepagents_cli-0.0.56 → deepagents_cli-0.0.57}/deepagents_cli/textual_adapter.py

@@ -1432,13 +1432,22 @@ async def _persist_context_tokens(
 ) -> None:
     """Best-effort persist of the context token count into graph state.
 
+    The `aupdate_state` call is wrapped in `tracing_context(enabled=False)` so
+    this purely-internal bookkeeping write does not surface as a separate
+    `UpdateState` run in LangSmith. `_context_tokens` is already marked
+    `PrivateStateAttr`, but `aupdate_state` itself creates its own traced run
+    that would otherwise clutter the project's traces.
+
     Args:
         agent: The LangGraph agent (must support `aupdate_state`).
         config: Runnable config with `thread_id`.
         tokens: Total context tokens to persist.
     """
+    from langsmith import tracing_context
+
     try:
-        await agent.aupdate_state(config, {"_context_tokens": tokens})
+        with tracing_context(enabled=False):
+            await agent.aupdate_state(config, {"_context_tokens": tokens})
     except (httpx.TransportError, httpx.TimeoutException) as e:
         logger.warning(
             "Could not persist _context_tokens=%d (network): %s; "

{deepagents_cli-0.0.56 → deepagents_cli-0.0.57}/deepagents_cli/widgets/theme_selector.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 import asyncio
 import logging
 import os
-from typing import TYPE_CHECKING, ClassVar
+from typing import TYPE_CHECKING, ClassVar, Protocol, runtime_checkable
 
 from textual.binding import Binding, BindingType
 from textual.containers import Vertical
@@ -22,6 +22,14 @@ from deepagents_cli.config import get_glyphs, is_ascii_mode
 logger = logging.getLogger(__name__)
 
 
+@runtime_checkable
+class _TerminalBackgroundSyncApp(Protocol):
+    """App protocol for terminal background sync after theme preview changes."""
+
+    def sync_terminal_background(self) -> None:
+        """Sync the terminal background to the active theme."""
+
+
 class ThemeSelectorScreen(ModalScreen[str | None]):
     """Modal dialog for theme selection with live preview.
 
@@ -103,6 +111,11 @@ class ThemeSelectorScreen(ModalScreen[str | None]):
         self._terminal_default = terminal_default
         self._show_keys = False
 
+    def _sync_terminal_background(self) -> None:
+        """Ask the app to sync terminal background after preview changes."""
+        if isinstance(self.app, _TerminalBackgroundSyncApp):
+            self.app.sync_terminal_background()
+
     def _format_option(self, name: str, entry: theme.ThemeEntry) -> str:
         """Render the option text for a theme entry.
 
@@ -172,6 +185,7 @@ class ThemeSelectorScreen(ModalScreen[str | None]):
         if name is not None and name in theme.get_registry():
             try:
                 self.app.theme = name
+                self._sync_terminal_background()
                 # refresh_css only repaints the active (modal) screen's layout;
                 # force the screen beneath us to repaint so the user sees the
                 # preview through the transparent scrim.
@@ -182,6 +196,7 @@ class ThemeSelectorScreen(ModalScreen[str | None]):
                 logger.warning("Failed to preview theme '%s'", name, exc_info=True)
                 try:
                     self.app.theme = self._original_theme
+                    self._sync_terminal_background()
                 except Exception:
                     logger.warning(
                         "Failed to restore original theme '%s'",
@@ -205,6 +220,7 @@ class ThemeSelectorScreen(ModalScreen[str | None]):
     def action_cancel(self) -> None:
         """Restore the original theme and dismiss."""
         self.app.theme = self._original_theme
+        self._sync_terminal_background()
         self.dismiss(None)
 
     def action_cursor_down(self) -> None:

{deepagents_cli-0.0.56 → deepagents_cli-0.0.57}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "deepagents-cli"
-version = "0.0.56"
+version = "0.0.57"
 description = "Terminal interface for Deep Agents - interactive AI agent with file operations, shell access, and sub-agent capabilities."
 readme = "README.md"
 license = { text = "MIT" }