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

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

@@ -1,5 +1,21 @@
 # Deep Agents CLI Changelog
 
+## [0.0.58](https://github.com/langchain-ai/deepagents/compare/deepagents-cli==0.0.57...deepagents-cli==0.0.58) (2026-05-12)
+
+### Features
+
+* Pin v0.6 and fix import race ([4db09ac](https://github.com/langchain-ai/deepagents/commit/4db09acba34b38521192b8f278723524be560779))
+
+## [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.58}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deepagents-cli
-Version: 0.0.56
+Version: 0.0.58
 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/
@@ -27,18 +27,18 @@ Classifier: Topic :: Terminals
 Requires-Python: <4.0,>=3.11
 Requires-Dist: aiosqlite<1.0.0,>=0.19.0
 Requires-Dist: deepagents-acp>=0.0.4
-Requires-Dist: deepagents==0.5.9
+Requires-Dist: deepagents==0.6.1
 Requires-Dist: httpx<1.0.0,>=0.28.1
 Requires-Dist: langchain-anthropic<2.0.0,>=1.4.3
 Requires-Dist: langchain-google-genai<5.0.0,>=4.2.2
 Requires-Dist: langchain-mcp-adapters<1.0.0,>=0.2.2
 Requires-Dist: langchain-openai<2.0.0,>=1.2.1
-Requires-Dist: langchain<2.0.0,>=1.2.17
-Requires-Dist: langgraph-checkpoint-sqlite<4.0.0,>=3.0.3
+Requires-Dist: langchain<2.0.0,>=1.3.0
+Requires-Dist: langgraph-checkpoint-sqlite<4.0.0,>=3.1.0
 Requires-Dist: langgraph-cli[inmem]<1.0.0,>=0.4.24
-Requires-Dist: langgraph-prebuilt<2.0.0,>=1.0.13
+Requires-Dist: langgraph-runtime-inmem<1.0.0,>=0.28.1
 Requires-Dist: langgraph-sdk<1.0.0,>=0.3.13
-Requires-Dist: langgraph<2.0.0,>=1.1.10
+Requires-Dist: langgraph<2.0.0,>=1.2.0
 Requires-Dist: langsmith[sandbox]>=0.8.0
 Requires-Dist: markdownify<2.0.0,>=0.13.0
 Requires-Dist: packaging>=23.0

{deepagents_cli-0.0.56 → deepagents_cli-0.0.58}/THREAT_MODEL.md

@@ -57,7 +57,7 @@
 
 ### Architecture Diagram
 
-```
+```txt
 ┌──────────────────────────────────────────────────────────────────────┐
 │                        User (local machine)                          │
 │                                                                      │
@@ -138,6 +138,7 @@
 | C17 | Model Config Loader         | Resolves model provider, supports `class_path` for arbitrary `BaseChatModel` instantiation via `importlib`          | user-controlled      | N/A      | `config.create_model`, `config._create_model_from_class`, `model_config.ModelConfig.load`         |
 
 **Notes:**
+
 1. `http_request` and `fetch_url` enabled by default; `web_search` requires `TAVILY_API_KEY`.
 2. MCP servers only load if `.mcp.json` config files are present.
 3. Hooks only execute if `~/.deepagents/hooks.json` exists.

{deepagents_cli-0.0.56 → deepagents_cli-0.0.58}/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.58}/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.58"  # 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.58}/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
@@ -1590,7 +1591,7 @@ class DeepAgentsApp(App):
         - The agent is a local `Pregel` graph (e.g. ACP mode, test harnesses).
 
         Used to gate features that require a server-backed agent (e.g. model
-        switching via `ConfigurableModelMiddleware`, checkpointer fallback).
+        switching via `ConfigurableModelMiddleware`, thread registration).
         Checks the agent type rather than server ownership so this works for
         both CLI-spawned servers and externally managed ones.
 
@@ -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:
@@ -5443,9 +5486,6 @@ class DeepAgentsApp(App):
             if result.offload_warning:
                 await self._mount_message(ErrorMessage(result.offload_warning))
 
-            if remote := self._remote_agent():
-                await remote.aensure_thread(config)  # ty: ignore[invalid-argument-type]
-
             await self._agent.aupdate_state(
                 config, {"_summarization_event": result.new_event}
             )
@@ -5792,12 +5832,14 @@ class DeepAgentsApp(App):
         return result
 
     async def _get_thread_state_values(self, thread_id: str) -> dict[str, Any]:
-        """Fetch thread state values, with remote checkpointer fallback.
+        """Fetch thread state values for a thread.
 
-        In server mode the LangGraph dev server can report an empty thread state
-        after a restart even when checkpoints exist on disk. When that happens,
-        read the latest checkpoint directly so resumed threads can still load
-        history and offload correctly.
+        In server mode the LangGraph dev server starts with an empty in-memory
+        thread store, so `aget_state` returns empty state for any thread that
+        was not registered in the current server session. Calling
+        `aensure_thread` first registers the thread idempotently so the
+        subsequent `aget_state` call can read from the checkpointer correctly,
+        including proper reconstruction of delta channels.
 
         Args:
             thread_id: Thread ID to fetch from checkpoint storage.
@@ -5810,46 +5852,20 @@ class DeepAgentsApp(App):
             return {}
 
         config: RunnableConfig = {"configurable": {"thread_id": thread_id}}
-        state = await self._agent.aget_state(config)
+        remote_config: dict[str, Any] = {"configurable": {"thread_id": thread_id}}
 
-        values: dict[str, Any] = {}
-        if state and state.values:
-            values = dict(state.values)
+        if remote := self._remote_agent():
+            await remote.aensure_thread(remote_config)
 
-        messages = values.get("messages")
-        if isinstance(messages, list) and messages:
-            return values
-        if not self._remote_agent():
-            return values
+        state = await self._agent.aget_state(config)
 
-        logger.debug(
-            "Remote state empty for thread %s; falling back to local checkpointer",
-            thread_id,
-        )
-        fallback_values = await self._read_channel_values_from_checkpointer(thread_id)
-        fallback_messages = fallback_values.get("messages")
-        if isinstance(fallback_messages, list) and fallback_messages:
-            values["messages"] = fallback_messages
-        if (
-            values.get("_summarization_event") is None
-            and "_summarization_event" in fallback_values
-        ):
-            values["_summarization_event"] = fallback_values["_summarization_event"]
-        if (
-            values.get("_context_tokens") is None
-            and "_context_tokens" in fallback_values
-        ):
-            values["_context_tokens"] = fallback_values["_context_tokens"]
-        return values
+        if state and state.values:
+            return dict(state.values)
+        return {}
 
     async def _fetch_thread_history_data(self, thread_id: str) -> _ThreadHistoryPayload:
         """Fetch and convert stored messages for a thread.
 
-        In server mode the LangGraph dev server starts with an empty thread
-        store, so `aget_state` via the HTTP API returns no messages even when
-        checkpoints exist on disk. We fall back to reading the SQLite
-        checkpointer directly to guarantee resumed threads load their history.
-
         Args:
             thread_id: Thread ID to fetch from checkpoint storage.
 
@@ -5867,10 +5883,8 @@ class DeepAgentsApp(App):
         if not messages:
             return _ThreadHistoryPayload([], context_tokens)
 
-        # Server mode / direct checkpointer may return dicts; convert to
+        # RemoteGraph.aget_state returns values as raw JSON dicts; convert to
         # LangChain message objects so _convert_messages_to_data works.
-        # `any(...)` guards against heterogeneous lists where only some
-        # elements are serialized.
         if any(isinstance(m, dict) for m in messages):
             from langchain_core.messages.utils import convert_to_messages
 
@@ -5880,44 +5894,6 @@ class DeepAgentsApp(App):
         data = await asyncio.to_thread(self._convert_messages_to_data, messages)
         return _ThreadHistoryPayload(data, context_tokens)
 
-    @staticmethod
-    async def _read_channel_values_from_checkpointer(thread_id: str) -> dict[str, Any]:
-        """Read checkpoint channel values directly from the SQLite checkpointer.
-
-        Args:
-            thread_id: Thread ID to look up.
-
-        Returns:
-            Channel values from the latest checkpoint, or an empty dict on
-                failure.
-        """
-        try:
-            from langgraph.checkpoint.sqlite.aio import AsyncSqliteSaver
-
-            from deepagents_cli.sessions import get_db_path
-
-            db_path = str(get_db_path())
-            config: RunnableConfig = {"configurable": {"thread_id": thread_id}}
-            async with AsyncSqliteSaver.from_conn_string(db_path) as saver:
-                tup = await saver.aget_tuple(config)
-                if tup and tup.checkpoint:
-                    channel_values = tup.checkpoint.get("channel_values", {})
-                    if isinstance(channel_values, dict):
-                        return dict(channel_values)
-        except (ImportError, OSError) as exc:
-            logger.warning(
-                "Failed to read checkpointer directly for %s: %s",
-                thread_id,
-                exc,
-            )
-        except Exception:
-            logger.warning(
-                "Unexpected error reading checkpointer for %s",
-                thread_id,
-                exc_info=True,
-            )
-        return {}
-
     async def _upgrade_thread_message_link(
         self,
         widget: AppMessage,
@@ -6582,6 +6558,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 +6971,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.56 → deepagents_cli-0.0.58}/deepagents_cli/integrations/sandbox_factory.py

@@ -710,7 +710,7 @@ class _AgentCoreProvider(SandboxProvider):
 
         # Validate AWS credentials early for a clear error message.
         try:
-            import boto3  # ty: ignore[unresolved-import, unused-ignore-comment]
+            import boto3  # ty: ignore[unresolved-import]
 
             session = boto3.Session()
             credentials = session.get_credentials()

{deepagents_cli-0.0.56 → deepagents_cli-0.0.58}/deepagents_cli/local_context.py

@@ -104,6 +104,7 @@ class _AsyncExecutableBackend(Protocol):
 
 logger = logging.getLogger(__name__)
 
+
 # ---------------------------------------------------------------------------
 # Context detection script
 #

{deepagents_cli-0.0.56 → deepagents_cli-0.0.58}/deepagents_cli/remote_client.py

@@ -183,7 +183,8 @@ class RemoteAgent:
     ) -> Any:  # noqa: ANN401
         """Get the current state of a thread.
 
-        Returns `None` when the thread does not exist on the server (404).
+        Returns `None` when the thread does not exist on the server (404) or
+        when the thread exists but has no checkpoint yet (new/empty thread).
         All other errors (network, auth, 500) are logged at WARNING and
         re-raised so callers can handle them.
 
@@ -196,10 +197,11 @@ class RemoteAgent:
 
         Returns:
             Thread state object with `values` and `next` attributes, or `None`
-                if the thread is not found.
+                if the thread is not found or has no checkpoint.
 
         Raises:
             ValueError: If `thread_id` is not present in `config`.
+            TypeError: If the server returns an unexpected state shape.
         """  # noqa: DOC502 — raised by _require_thread_id
         from langgraph_sdk.errors import NotFoundError
 
@@ -211,6 +213,20 @@ class RemoteAgent:
         except NotFoundError:
             logger.debug("Thread %s not found on server", thread_id)
             return None
+        except TypeError as e:
+            # langgraph SDK bug: _create_state_snapshot does
+            # state["checkpoint"]["thread_id"], but the server returns
+            # checkpoint=null for threads with no checkpoint yet (new threads,
+            # or threads registered via aensure_thread before any run).
+            if "subscriptable" in str(e).lower():
+                logger.debug(
+                    "Thread %s has no checkpoint yet; treating as empty", thread_id
+                )
+                return None
+            logger.warning(
+                "Failed to get state for thread %s", thread_id, exc_info=True
+            )
+            raise
         except Exception:
             logger.warning(
                 "Failed to get state for thread %s", thread_id, exc_info=True

deepagents_cli-0.0.58/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)