deepagents-code 0.1.57__tar.gz → 0.1.58__tar.gz

{deepagents_code-0.1.57 → deepagents_code-0.1.58}/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 # Deep Agents Code Changelog
 
+## [0.1.58](https://github.com/langchain-ai/deepagents/compare/deepagents-code==0.1.57...deepagents-code==0.1.58) (2026-08-19)
+
+### Breaking Changes
+
+- `deepagents-code` now requires Python 3.12 or newer. ([#5603](https://github.com/langchain-ai/deepagents/issues/5603))
+
+### Features
+
+- Added OpenRouter `z-ai/glm-5.3` to the model switcher. ([#5641](https://github.com/langchain-ai/deepagents/issues/5641))
+- Added support for re-authenticating MCP servers from the viewer. ([#5637](https://github.com/langchain-ai/deepagents/issues/5637))
+- Footer pickers can now be opened with `ctrl+click`. ([#5611](https://github.com/langchain-ai/deepagents/issues/5611))
+- Resume hints now account for `TERM_PROGRAM` support before showing terminal-specific guidance. ([#5580](https://github.com/langchain-ai/deepagents/issues/5580))
+
+### Fixes
+
+- Completed the `dcode config` command surface. ([#5581](https://github.com/langchain-ai/deepagents/issues/5581))
+- Made `/offload` interruptible. ([#5590](https://github.com/langchain-ai/deepagents/issues/5590))
+- Improved chat and footer UI behavior: rapid typing stays visible, double-click collapses a resized chat input, and the MCP footer wraps on narrow windows. ([#5424](https://github.com/langchain-ai/deepagents/issues/5424), [#5578](https://github.com/langchain-ai/deepagents/issues/5578), [#5651](https://github.com/langchain-ai/deepagents/issues/5651))
+- Captured stdio MCP server stderr in the logger. ([#5610](https://github.com/langchain-ai/deepagents/issues/5610))
+- Drained hook pipes after timeout. ([#5606](https://github.com/langchain-ai/deepagents/issues/5606))
+- Grouped resume trace rounds. ([#5593](https://github.com/langchain-ai/deepagents/issues/5593))
+- Omitted web-search prompt guidance when web search is unavailable. ([#5602](https://github.com/langchain-ai/deepagents/issues/5602))
+- Resolved message pointer shapes per cell. ([#5592](https://github.com/langchain-ai/deepagents/issues/5592))
+
 ## [0.1.57](https://github.com/langchain-ai/deepagents/compare/deepagents-code==0.1.56...deepagents-code==0.1.57) (2026-08-18)
 
 ### Features

{deepagents_code-0.1.57 → deepagents_code-0.1.58}/DEVELOPMENT.md

@@ -138,6 +138,10 @@ tail -f /tmp/deepagents_debug.log
 
 To send it elsewhere, also `export DEEPAGENTS_CODE_DEBUG_FILE=<path>`. The handler appends across runs, so a single file accumulates every session.
 
+The file is created or tightened to user-only access. A symlink at the path is refused. If the file cannot be secured, no file handler is attached and a warning goes to stderr. Use the in-app Debug Console in that case.
+
+Stdio MCP server stderr is captured here at `DEBUG`. This keeps server-side failures visible when the TUI cannot show process stderr. Each record is one line, capped at 4096 characters. Characters in the Unicode `C` categories are removed, which includes control and format characters. The ESC byte of an ANSI sequence is removed but the rest stays as literal text, so the log is not free of escape-sequence residue. The text comes from the server. It can contain credentials or other sensitive values. Enable `DEBUG` logging only if you accept that risk, and do not share the log file.
+
 ### In-app Debug Console (`Ctrl+\`)
 
 Press `Ctrl+\` (or run the hidden `/debug` command) inside a session to toggle a read-only Debug Console overlay. It shows a point-in-time session/runtime snapshot (version, model, thread, cwd, auto-approve, sandbox, MCP servers, token usage, debug-log path) plus a live tail of recent `deepagents_code.*` log records.
@@ -168,7 +172,7 @@ uv pip install --python ~/.local/share/dcode-dev/bin/python -e <repo>/libs/code
 ln -sf ~/.local/share/dcode-dev/bin/dcode ~/.local/bin/dcode-dev
 ```
 
-The `--python 3.13` is illustrative — any interpreter satisfying the package's `requires-python` (currently `>=3.11`) works; omit the flag to let `uv` pick.
+The `--python 3.13` is illustrative — any interpreter satisfying the package's `requires-python` (currently `>=3.12`) works; omit the flag to let `uv` pick.
 
 > **Why `uv venv` + `uv pip install -e` rather than `uv sync` or `uv tool install --editable`?** This builds an isolated venv *outside* the workspace's locked environment, so the dev binary can be re-resolved on demand without disturbing the released tool or the repo's `uv.lock`. (`uv pip` and `uv venv` are first-class `uv` subcommands here, not bare `pip`.)
 

{deepagents_code-0.1.57 → deepagents_code-0.1.58}/PKG-INFO

@@ -1,15 +1,17 @@
 Metadata-Version: 2.5
 Name: deepagents-code
-Version: 0.1.57
+Version: 0.1.58
 Summary: Terminal coding agent built on the Deep Agents SDK - works with any model, with persistent memory, customizable skills, subagents, and approval controls.
-Project-URL: Homepage, https://docs.langchain.com/oss/python/deepagents/overview
-Project-URL: Documentation, https://reference.langchain.com/python/deepagents/
+Project-URL: Homepage, https://www.langchain.com/dcode
+Project-URL: Documentation, https://docs.langchain.com/oss/deepagents/code/overview
 Project-URL: Repository, https://github.com/langchain-ai/deepagents
 Project-URL: Issues, https://github.com/langchain-ai/deepagents/issues
 Project-URL: Changelog, https://github.com/langchain-ai/deepagents/blob/main/libs/code/CHANGELOG.md
 Project-URL: Twitter, https://x.com/langchain_oss
 Project-URL: Slack, https://www.langchain.com/join-community
 Project-URL: Reddit, https://www.reddit.com/r/LangChain/
+Author: LangChain
+Maintainer: LangChain
 License: MIT
 License-File: LICENSE
 Keywords: agents,ai,cli,deep-agent,langchain,langgraph,llm,terminal
@@ -18,32 +20,31 @@ Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: Terminals
-Requires-Python: <4.0,>=3.11
+Requires-Python: <4.0,>=3.12
 Requires-Dist: aiosqlite<1.0.0,>=0.22.1
 Requires-Dist: anyio<5.0.0,>=4.14.2
 Requires-Dist: deepagents-acp<1.0.0,>=0.0.10
-Requires-Dist: deepagents==0.7.6
+Requires-Dist: deepagents==0.7.7
 Requires-Dist: filelock<3.30,>=3.29.7
 Requires-Dist: genai-prices<0.2.0,>=0.1.3
 Requires-Dist: httpx<1.0.0,>=0.28.1
-Requires-Dist: langchain-anthropic<2.0.0,>=1.5.6
-Requires-Dist: langchain-google-genai<5.0.0,>=4.3.3
+Requires-Dist: langchain-anthropic<2.0.0,>=1.6.0
+Requires-Dist: langchain-google-genai<5.0.0,>=4.3.4
 Requires-Dist: langchain-mcp-adapters<1.0.0,>=0.3.2
-Requires-Dist: langchain-openai<2.0.0,>=1.5.0
+Requires-Dist: langchain-openai<2.0.0,>=1.6.0
 Requires-Dist: langchain-quickjs<0.4.0,>=0.3.4
 Requires-Dist: langchain<2.0.0,>=1.3.15
 Requires-Dist: langgraph-checkpoint-sqlite<4.0.0,>=3.1.1
 Requires-Dist: langgraph-cli[inmem]<1.0.0,>=0.4.31
-Requires-Dist: langgraph-runtime-inmem<1.0.0,>=0.32.4
-Requires-Dist: langgraph-sdk<1.0.0,>=0.4.2
-Requires-Dist: langsmith[sandbox]>=0.10.18
+Requires-Dist: langgraph-runtime-inmem<1.0.0,>=0.32.6
+Requires-Dist: langgraph-sdk<1.0.0,>=0.4.3
+Requires-Dist: langsmith[sandbox]>=0.11.1
 Requires-Dist: markdownify<2.0.0,>=1.2.3
 Requires-Dist: mcp<2.0.0,>=1.28.1
 Requires-Dist: packaging>=26.2
@@ -65,13 +66,13 @@ Provides-Extra: agentcore
 Requires-Dist: langchain-agentcore-codeinterpreter<1.0.0,>=0.0.5; extra == 'agentcore'
 Provides-Extra: all-providers
 Requires-Dist: aiohttp<3.15.0,>=3.14.3; extra == 'all-providers'
-Requires-Dist: langchain-anthropic<2.0.0,>=1.5.6; extra == 'all-providers'
-Requires-Dist: langchain-aws<2.0.0,>=1.7.0; extra == 'all-providers'
+Requires-Dist: langchain-anthropic<2.0.0,>=1.6.0; extra == 'all-providers'
+Requires-Dist: langchain-aws<2.0.0,>=1.7.2; extra == 'all-providers'
 Requires-Dist: langchain-baseten<1.0.0,>=0.2.3; extra == 'all-providers'
 Requires-Dist: langchain-cohere<1.0.0,>=0.6.0; extra == 'all-providers'
 Requires-Dist: langchain-deepseek<2.0.0,>=1.1.0; extra == 'all-providers'
 Requires-Dist: langchain-fireworks<2.0.0,>=1.5.2; extra == 'all-providers'
-Requires-Dist: langchain-google-genai<5.0.0,>=4.3.3; extra == 'all-providers'
+Requires-Dist: langchain-google-genai<5.0.0,>=4.3.4; extra == 'all-providers'
 Requires-Dist: langchain-google-vertexai<4.0.0,>=3.2.4; extra == 'all-providers'
 Requires-Dist: langchain-groq<2.0.0,>=1.1.3; extra == 'all-providers'
 Requires-Dist: langchain-huggingface<2.0.0,>=1.2.2; extra == 'all-providers'
@@ -81,8 +82,8 @@ Requires-Dist: langchain-meta<2.0.0,>=0.5.0; extra == 'all-providers'
 Requires-Dist: langchain-mistralai<2.0.0,>=1.1.6; extra == 'all-providers'
 Requires-Dist: langchain-nvidia-ai-endpoints<2.0.0,>=1.4.3; extra == 'all-providers'
 Requires-Dist: langchain-ollama<2.0.0,>=1.1.0; extra == 'all-providers'
-Requires-Dist: langchain-openai<2.0.0,>=1.5.0; extra == 'all-providers'
-Requires-Dist: langchain-openrouter<2.0.0,>=0.2.7; extra == 'all-providers'
+Requires-Dist: langchain-openai<2.0.0,>=1.6.0; extra == 'all-providers'
+Requires-Dist: langchain-openrouter<2.0.0,>=0.2.8; extra == 'all-providers'
 Requires-Dist: langchain-perplexity<2.0.0,>=1.4.0; extra == 'all-providers'
 Requires-Dist: langchain-together<2.0.0,>=0.4.0; extra == 'all-providers'
 Requires-Dist: langchain-xai<2.0.0,>=1.3.0; extra == 'all-providers'
@@ -93,11 +94,11 @@ Requires-Dist: langchain-modal>=0.0.5; extra == 'all-sandboxes'
 Requires-Dist: langchain-runloop>=0.0.6; extra == 'all-sandboxes'
 Requires-Dist: langchain-vercel-sandbox>=0.0.1; extra == 'all-sandboxes'
 Provides-Extra: anthropic
-Requires-Dist: langchain-anthropic<2.0.0,>=1.5.6; extra == 'anthropic'
+Requires-Dist: langchain-anthropic<2.0.0,>=1.6.0; extra == 'anthropic'
 Provides-Extra: baseten
 Requires-Dist: langchain-baseten<1.0.0,>=0.2.3; extra == 'baseten'
 Provides-Extra: bedrock
-Requires-Dist: langchain-aws<2.0.0,>=1.7.0; extra == 'bedrock'
+Requires-Dist: langchain-aws<2.0.0,>=1.7.2; extra == 'bedrock'
 Provides-Extra: cohere
 Requires-Dist: langchain-cohere<1.0.0,>=0.6.0; extra == 'cohere'
 Provides-Extra: daytona
@@ -107,7 +108,7 @@ Requires-Dist: langchain-deepseek<2.0.0,>=1.1.0; extra == 'deepseek'
 Provides-Extra: fireworks
 Requires-Dist: langchain-fireworks<2.0.0,>=1.5.2; extra == 'fireworks'
 Provides-Extra: google-genai
-Requires-Dist: langchain-google-genai<5.0.0,>=4.3.3; extra == 'google-genai'
+Requires-Dist: langchain-google-genai<5.0.0,>=4.3.4; extra == 'google-genai'
 Provides-Extra: groq
 Requires-Dist: langchain-groq<2.0.0,>=1.1.3; extra == 'groq'
 Provides-Extra: huggingface
@@ -131,9 +132,9 @@ Requires-Dist: langchain-nvidia-ai-endpoints<2.0.0,>=1.4.3; extra == 'nvidia'
 Provides-Extra: ollama
 Requires-Dist: langchain-ollama<2.0.0,>=1.1.0; extra == 'ollama'
 Provides-Extra: openai
-Requires-Dist: langchain-openai<2.0.0,>=1.5.0; extra == 'openai'
+Requires-Dist: langchain-openai<2.0.0,>=1.6.0; extra == 'openai'
 Provides-Extra: openrouter
-Requires-Dist: langchain-openrouter<2.0.0,>=0.2.7; extra == 'openrouter'
+Requires-Dist: langchain-openrouter<2.0.0,>=0.2.8; extra == 'openrouter'
 Provides-Extra: perplexity
 Requires-Dist: langchain-perplexity<2.0.0,>=1.4.0; extra == 'perplexity'
 Provides-Extra: quickjs

{deepagents_code-0.1.57 → deepagents_code-0.1.58}/deepagents_code/_build_info.py

@@ -1,3 +1,3 @@
 """Generated at build time. Do not edit or commit."""
 
-BUILD_COMMIT = "57e15ea"
+BUILD_COMMIT = "863c615"

deepagents_code-0.1.58/deepagents_code/_debug.py

@@ -0,0 +1,371 @@
+"""Shared debug-logging configuration for runtime and file-based tracing.
+
+When the `DEEPAGENTS_CODE_DEBUG` environment variable is set, modules that handle
+streaming or remote communication can enable detailed file-based logging. This
+helper centralizes the setup so the env-var names, file path, log level, and
+format are defined in one place.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import sys
+from pathlib import Path
+
+# Windows-only ACL plumbing; see `_apply_windows_owner_only_dacl`. Imported
+# under the guard because `_debug` is on the startup path for every command and
+# `ctypes` costs a few milliseconds it can never repay on POSIX.
+if os.name == "nt":
+    import ctypes
+    from ctypes import wintypes
+
+from deepagents_code._env_vars import (
+    DEBUG,
+    DEBUG_FILE,
+    DEFAULT_DEBUG_FILE,
+    LOG_LEVEL,
+    is_env_truthy,
+)
+
+logger = logging.getLogger(__name__)
+
+_DEBUG_HANDLER_ATTR = "_deepagents_code_debug_handler"
+LOG_LEVELS = {
+    "DEBUG": logging.DEBUG,
+    "INFO": logging.INFO,
+    "WARNING": logging.WARNING,
+    "ERROR": logging.ERROR,
+    "CRITICAL": logging.CRITICAL,
+}
+"""Canonical level-name to `logging` level mapping.
+
+The single source of truth for level names and their numeric values, shared with
+the Debug Console's level filter so severity ordering is never re-derived from
+hardcoded integers.
+"""
+
+
+def _prepare_debug_file(path: Path) -> None:
+    """Create or tighten a debug file before attaching the logging handler.
+
+    On POSIX the file is created or tightened to mode `0o600`. On Windows,
+    where `os.open` mode bits and `chmod` do not tighten the DACL, the DACL is
+    replaced with one granting read and write access to the current user only.
+
+    `O_NOFOLLOW` refuses a symlink at `path`. The default location is a
+    world-writable temp directory, so without it a planted symlink could
+    redirect captured MCP server stderr into a file of the attacker's choosing.
+
+    Raises:
+        OSError: If the file cannot be created, opened, or tightened. The
+            caller must treat this as fatal to file logging.
+    """  # noqa: DOC502 - raised by os.open/fchmod, not by an explicit raise
+    flags = os.O_APPEND | os.O_CREAT | os.O_WRONLY | getattr(os, "O_NOFOLLOW", 0)
+    fd = os.open(path, flags, 0o600)
+    try:
+        if os.name == "nt":
+            _set_windows_owner_only_dacl(path)
+            return
+        fchmod = getattr(os, "fchmod", None)
+        if fchmod is None:
+            path.chmod(0o600)
+        else:
+            fchmod(fd, 0o600)
+    finally:
+        os.close(fd)
+
+
+def _set_windows_owner_only_dacl(path: Path) -> None:
+    """Restrict `path` to the current user on Windows.
+
+    This is a no-op on POSIX, where `_prepare_debug_file` uses mode `0o600`
+    instead. The Windows implementation (defined only when `os.name == "nt"`)
+    replaces the file's DACL with one granting read and write access to the
+    current user and no one else.
+
+    Args:
+        path: Debug log file to lock down.
+
+    Raises:
+        OSError: If the DACL cannot be built or applied. `_prepare_debug_file`
+            propagates it; `configure_debug_logging` catches it and disables
+            file logging.
+    """  # noqa: DOC502 - raised by the callee, not by an explicit raise
+    if os.name != "nt":
+        return
+    _apply_windows_owner_only_dacl(path)
+
+
+if os.name == "nt":
+    # --- Windows user-only DACL ---------------------------------------------
+    # Structures and helpers mirroring the advapi32 API used to build and apply
+    # a DACL granting the current user read and write access, and no one else
+    # any access. `DELETE` and `WRITE_DAC` are deliberately not granted; the
+    # file owner retains them implicitly.
+
+    _SE_FILE_OBJECT = 1
+    _DACL_SECURITY_INFORMATION = 0x00000004
+    _PROTECTED_DACL_SECURITY_INFORMATION = 0x80000000
+    _TOKEN_QUERY = 0x0008
+    _TOKEN_USER_INFORMATION_CLASS = 1
+    _FILE_GENERIC_READ = 0x120089
+    _FILE_GENERIC_WRITE = 0x120116
+    # `TRUSTEE_FORM` / `TRUSTEE_TYPE` / `ACCESS_MODE` from `accctrl.h`. Named
+    # rather than inlined because all three enums start at 0 with unrelated
+    # meanings, so a transposed literal still compiles and is rejected only at
+    # runtime by `SetEntriesInAclW`.
+    _NO_MULTIPLE_TRUSTEE = 0
+    _TRUSTEE_IS_SID = 0
+    _TRUSTEE_IS_USER = 1
+    _SET_ACCESS = 2
+    _NO_INHERITANCE = 0
+
+    class _TRUSTEE_W(ctypes.Structure):  # noqa: N801  # mirrors Win32 TRUSTEE_W
+        """`TRUSTEE_W` identifying the current-user SID to `SetEntriesInAclW`."""
+
+        _fields_ = [
+            ("pMultipleTrustee", ctypes.c_void_p),
+            ("MultipleTrusteeOperation", ctypes.c_int),
+            ("TrusteeForm", ctypes.c_int),
+            ("TrusteeType", ctypes.c_int),
+            ("ptstrName", ctypes.c_void_p),
+        ]
+
+    class _EXPLICIT_ACCESS_W(ctypes.Structure):  # noqa: N801  # mirrors Win32 type
+        """`EXPLICIT_ACCESS_W` describing one access-control entry."""
+
+        _fields_ = [
+            ("grfAccessPermissions", wintypes.DWORD),
+            ("grfAccessMode", ctypes.c_int),
+            ("grfInheritance", wintypes.DWORD),
+            ("Trustee", _TRUSTEE_W),
+        ]
+
+    def _get_current_user_sid() -> ctypes.c_void_p:
+        """Return a pointer to the current user's SID.
+
+        The `TOKEN_USER` buffer the SID points into is attached to the returned
+        pointer as `_buffer`, so it stays alive for the DACL construction.
+        `ctypes` already retains it through `.contents`; the attribute makes
+        that guarantee explicit rather than incidental.
+
+        Returns:
+            A pointer to the current user's SID.
+
+        Raises:
+            OSError: If the process token or user SID cannot be read. Raised
+                via `ctypes.WinError`, which is a factory returning `OSError`.
+        """  # noqa: DOC501, DOC502 - `ctypes.WinError` returns an `OSError`
+        advapi32 = ctypes.windll.advapi32
+        token = wintypes.HANDLE()
+        if not advapi32.OpenProcessToken(
+            ctypes.windll.kernel32.GetCurrentProcess(),
+            _TOKEN_QUERY,
+            ctypes.byref(token),
+        ):
+            raise ctypes.WinError()  # surface the raw OS error
+        try:
+            needed = wintypes.DWORD(0)
+            advapi32.GetTokenInformation(
+                token, _TOKEN_USER_INFORMATION_CLASS, None, 0, ctypes.byref(needed)
+            )
+            if not needed.value:
+                raise ctypes.WinError()
+            buffer = (ctypes.c_byte * needed.value)()
+            if not advapi32.GetTokenInformation(
+                token,
+                _TOKEN_USER_INFORMATION_CLASS,
+                buffer,
+                needed,
+                ctypes.byref(needed),
+            ):
+                raise ctypes.WinError()
+            # TOKEN_USER begins with a single pointer to the user's SID.
+            sid = ctypes.cast(buffer, ctypes.POINTER(ctypes.c_void_p)).contents
+            # Keep the backing buffer alive by attaching it to the pointer object.
+            sid._buffer = buffer  # type: ignore[attr-defined]
+            return sid
+        finally:
+            ctypes.windll.kernel32.CloseHandle(token)
+
+    def _apply_windows_owner_only_dacl(path: Path) -> None:
+        """Replace `path`'s DACL with a single read/write entry for this user.
+
+        The DACL is marked protected, so entries inherited from the parent
+        directory are dropped rather than merged.
+
+        Args:
+            path: Debug log file to lock down.
+
+        Raises:
+            OSError: If the DACL cannot be built or applied. Raised via
+                `ctypes.WinError`, which is a factory returning `OSError`.
+        """  # noqa: DOC501, DOC502 - `ctypes.WinError` returns an `OSError`
+        advapi32 = ctypes.windll.advapi32
+        sid = _get_current_user_sid()
+
+        trustee = _TRUSTEE_W(
+            pMultipleTrustee=None,
+            MultipleTrusteeOperation=_NO_MULTIPLE_TRUSTEE,
+            TrusteeForm=_TRUSTEE_IS_SID,
+            TrusteeType=_TRUSTEE_IS_USER,
+            ptstrName=ctypes.cast(sid, ctypes.c_void_p).value,
+        )
+        explicit = _EXPLICIT_ACCESS_W(
+            grfAccessPermissions=_FILE_GENERIC_READ | _FILE_GENERIC_WRITE,
+            grfAccessMode=_SET_ACCESS,
+            grfInheritance=_NO_INHERITANCE,
+            Trustee=trustee,
+        )
+        new_acl = ctypes.c_void_p()
+        result = advapi32.SetEntriesInAclW(
+            1, ctypes.byref(explicit), None, ctypes.byref(new_acl)
+        )
+        if result != 0:  # ERROR_SUCCESS
+            raise ctypes.WinError(result)
+        try:
+            apply_result = advapi32.SetNamedSecurityInfoW(
+                str(path),
+                _SE_FILE_OBJECT,
+                _DACL_SECURITY_INFORMATION | _PROTECTED_DACL_SECURITY_INFORMATION,
+                None,
+                None,
+                new_acl,
+                None,
+            )
+            if apply_result != 0:  # ERROR_SUCCESS
+                raise ctypes.WinError(apply_result)
+        finally:
+            ctypes.windll.kernel32.LocalFree(new_acl)
+
+
+def resolve_log_level(*, debug_enabled: bool | None = None) -> int:
+    """Resolve the configured runtime logging level.
+
+    Args:
+        debug_enabled: Whether `DEEPAGENTS_CODE_DEBUG` is truthy. When omitted,
+            the current environment is checked.
+
+    Returns:
+        A standard `logging` level integer. Defaults to `DEBUG` when debug file
+        logging is enabled and `INFO` otherwise.
+    """
+    if debug_enabled is None:
+        debug_enabled = is_env_truthy(DEBUG)
+    fallback = logging.DEBUG if debug_enabled else logging.INFO
+    raw = os.environ.get(LOG_LEVEL)
+    if raw is None or not raw.strip():
+        return fallback
+    level = LOG_LEVELS.get(raw.strip().upper())
+    if level is not None:
+        return level
+    valid = ", ".join(LOG_LEVELS)
+    message = f"ignoring invalid {LOG_LEVEL}={raw!r}; expected one of {valid}"
+    # stderr for headless / pre-TUI visibility; the logger so it also lands in
+    # the always-on in-memory buffer and surfaces in the Debug Console (the
+    # buffer is installed before this runs; see __init__.py).
+    print(f"Warning: {message}", file=sys.stderr)  # noqa: T201
+    logger.warning("%s", message)
+    return fallback
+
+
+def configure_debug_logging(target: logging.Logger) -> None:
+    """Configure runtime log level and optional file logging for *target*.
+
+    Intended to be called once on the `deepagents_code` package logger; child
+    module loggers reach the same handlers via propagation, so individual modules
+    do not configure logging themselves.
+
+    `DEEPAGENTS_CODE_LOG_LEVEL` controls the package logger level independently of
+    file logging. If it is unset, `DEEPAGENTS_CODE_DEBUG=1` defaults to `DEBUG`;
+    otherwise the runtime level defaults to `INFO`.
+
+    When `DEEPAGENTS_CODE_DEBUG` is truthy, a file handler is attached. The log
+    file defaults to `DEFAULT_DEBUG_FILE` but can be overridden with
+    `DEEPAGENTS_CODE_DEBUG_FILE`. The handler appends (`mode='a'`) so logs are
+    preserved across separate process runs. Calling this again with the same
+    resolved path does not stack duplicate handlers: the existing tagged handler
+    is reused and its level re-applied. If the resolved path changes, the stale
+    handler is closed and replaced.
+
+    The file is created or tightened to user-only access first. If that fails,
+    no file handler is attached: captured MCP server stderr can carry
+    credentials, so no file log is safer than one that could not be secured.
+
+    Args:
+        target: Logger to configure.
+    """
+    debug_enabled = is_env_truthy(DEBUG)
+    level = resolve_log_level(debug_enabled=debug_enabled)
+    target.setLevel(level)
+
+    if not debug_enabled:
+        return
+
+    debug_path = Path(os.environ.get(DEBUG_FILE, DEFAULT_DEBUG_FILE))
+    for existing in list(target.handlers):
+        if not (
+            isinstance(existing, logging.FileHandler)
+            and getattr(existing, _DEBUG_HANDLER_ATTR, False)
+        ):
+            continue
+        if Path(existing.baseFilename) == debug_path:
+            existing.setLevel(level)
+            return
+        # The debug path changed; drop the stale handler before re-attaching so
+        # we don't leak its file descriptor or fan logs out to two files.
+        target.removeHandler(existing)
+        existing.close()
+
+    try:
+        _prepare_debug_file(debug_path)
+    except OSError as exc:
+        # Fail closed. `_prepare_debug_file` opens with `O_NOFOLLOW`, so this
+        # also fires for a symlink planted at `debug_path` — and the
+        # `FileHandler` below would happily follow it, turning a blocked
+        # redirect into a successful one. Captured MCP server stderr can carry
+        # credentials, so skip file logging entirely; the in-memory buffer
+        # still backs the Debug Console.
+        message = (
+            f"could not restrict debug log file {debug_path} to the current "
+            f"user: {exc}. File logging is disabled because captured MCP "
+            f"server stderr may contain credentials. Set "
+            f"{DEBUG_FILE} to a path you own to enable it."
+        )
+        print(f"Warning: {message}", file=sys.stderr)  # noqa: T201
+        logger.warning("%s", message)
+        return
+    try:
+        handler = logging.FileHandler(str(debug_path), mode="a")
+    except OSError as exc:
+        message = f"could not open debug log file {debug_path}: {exc}"
+        # stderr for headless / pre-TUI visibility; the logger so it also lands
+        # in the always-on in-memory buffer and surfaces in the Debug Console.
+        print(f"Warning: {message}", file=sys.stderr)  # noqa: T201
+        logger.warning("%s", message)
+        return
+    setattr(handler, _DEBUG_HANDLER_ATTR, True)
+    handler.setLevel(level)
+    handler.setFormatter(logging.Formatter("%(asctime)s %(name)s %(message)s"))
+    target.addHandler(handler)
+
+
+def installed_debug_log_path() -> Path | None:
+    """Return the path of the active debug log file, or `None` if not logging.
+
+    Reflects the file handler actually attached by `configure_debug_logging`,
+    not the current `DEEPAGENTS_CODE_DEBUG` env value. The two diverge when the
+    variable is set after import — e.g. via a project/global `.env` loaded during
+    settings bootstrap — in which case the variable reads truthy but no handler
+    was installed and no log file exists. Callers that surface "full error in
+    <path>" hints must use this rather than the env var to avoid pointing users
+    at a file that was never created.
+    """
+    package_logger = logging.getLogger(__package__ or "deepagents_code")
+    for handler in package_logger.handlers:
+        if isinstance(handler, logging.FileHandler) and getattr(
+            handler, _DEBUG_HANDLER_ATTR, False
+        ):
+            return Path(handler.baseFilename)
+    return None

{deepagents_code-0.1.57 → deepagents_code-0.1.58}/deepagents_code/_env_vars.py

@@ -80,6 +80,17 @@ rather than forcing the default). Also settable via `[ui].collapse_pastes` in
 config.toml.
 """
 
+CURSOR_BLINK = "DEEPAGENTS_CODE_CURSOR_BLINK"
+"""Blink the chat input cursor.
+
+Enabled by default; set to a falsy value (`0`, `false`, `no`, `off`, or blank)
+for a steady cursor. Parsed by `classify_env_bool` (an unrecognized value falls
+through to the config value rather than forcing the default). A blank value —
+empty or whitespace-only — counts as `false` because the option declares
+`empty_env_is_false`, so it overrides `config.toml` instead of falling through.
+Also settable via `[ui].cursor_blink` in config.toml.
+"""
+
 CURSOR_STYLE = "DEEPAGENTS_CODE_CURSOR_STYLE"
 """Chat input cursor style (`block` or `underline`).
 
@@ -452,6 +463,15 @@ version), skips auto-updating to break out of an otherwise endless
 upgrade/restart loop. Set and read internally across `os.execv`.
 """
 
+RESUME_TERM_PROGRAM = "DEEPAGENTS_CODE_RESUME_TERM_PROGRAM"
+"""Include launch-time `TERM_PROGRAM` in teardown resume commands.
+
+Disabled by default and enabled by default in experimental or debug mode. An
+explicit boolean (`1`/`true`/`yes`/`on`, or `0`/`false`/`no`/`off`) overrides
+that mode-dependent default, as does an empty value, which reads as false. Also
+settable as `[features].resume_term_program` in config.toml.
+"""
+
 RIPGREP_INSTALLER = "DEEPAGENTS_CODE_RIPGREP_INSTALLER"
 """Select how ripgrep is provisioned: `managed` (default) or `system`.
 
@@ -478,6 +498,17 @@ Defaults to enabled; set to a falsy value (`0`, `false`, `no`, `off`, or empty)
 to hide replica tracing details from the splash while leaving tracing active.
 """
 
+SHOW_MESSAGE_TIMESTAMPS = "DEEPAGENTS_CODE_SHOW_MESSAGE_TIMESTAMPS"
+"""Show the timestamp footer under each chat message when enabled.
+
+Off by default; use the `/timestamps` slash command or
+`[ui].show_message_timestamps` in config.toml to toggle. Parsed by
+`classify_env_bool` (an unrecognized or empty value falls through to the config
+value rather than forcing the default). While this env var is set it outranks
+the persisted value, so a `/timestamps` toggle will not appear to "stick"
+across restarts.
+"""
+
 SHOW_SCROLLBAR = "DEEPAGENTS_CODE_SHOW_SCROLLBAR"
 """Show the vertical scrollbar in the chat area when enabled.
 
@@ -524,6 +555,19 @@ Off by default; set to a truthy value (`1`, `true`, `yes`, `on`) to suppress
 the warning when this coexistence is expected. Parsed by `is_env_truthy`.
 """
 
+TERMINAL_PROGRESS = "DEEPAGENTS_CODE_TERMINAL_PROGRESS"
+"""Report agent activity as `OSC 9;4` taskbar/dock/tab progress.
+
+Enabled by default; set to a falsy value (`0`, `false`, `no`, `off`, or blank)
+to stop emitting the sequence on terminals that render it poorly. Parsed by
+`classify_env_bool` (an unrecognized value falls through to the config value
+rather than forcing the default). A blank value — empty or whitespace-only —
+counts as `false` because the option declares `empty_env_is_false`, so it
+overrides `config.toml` instead of falling through. Also settable via
+`[ui].terminal_progress` in config.toml. `NO_TERMINAL_ESCAPE` suppresses the
+sequence regardless.
+"""
+
 THEME = "DEEPAGENTS_CODE_THEME"
 """Force the CLI to launch with this theme name when set."""