deepagents-code 0.1.7__tar.gz → 0.1.8__tar.gz

{deepagents_code-0.1.7 → deepagents_code-0.1.8}/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 # Deep Agents Code Changelog
 
+## [0.1.8](https://github.com/langchain-ai/deepagents/compare/deepagents-code==0.1.7...deepagents-code==0.1.8) (2026-06-02)
+
+### Features
+
+* List valid extras when `/install` has no argument ([#3695](https://github.com/langchain-ai/deepagents/issues/3695)) ([c7d529c](https://github.com/langchain-ai/deepagents/commit/c7d529ca0fc478dec9060ea04bcc8589f9b1cd3a))
+* Add MCP error detail modal ([#3687](https://github.com/langchain-ai/deepagents/issues/3687)) ([4ae4754](https://github.com/langchain-ai/deepagents/commit/4ae475453ce0df6d6b057b7e163396aa27d55143))
+
+### Bug Fixes
+
+* Allow recovery commands when startup fails ([#3706](https://github.com/langchain-ai/deepagents/issues/3706)) ([727d022](https://github.com/langchain-ai/deepagents/commit/727d022cd1526836c3d1de997c1f036e870881f7))
+* Preserve extras during install ([#3707](https://github.com/langchain-ai/deepagents/issues/3707)) ([e636ce9](https://github.com/langchain-ai/deepagents/commit/e636ce9e979fd1c30335ec340acdabbd0a5ae79e))
+* Normalize empty file list tool output ([#3697](https://github.com/langchain-ai/deepagents/issues/3697)) ([b67aead](https://github.com/langchain-ai/deepagents/commit/b67aead2b86e04aaee8f2dbfba7b263e3e23597d))
+* Point MCP re-enable guidance at `Ctrl+R` ([#3688](https://github.com/langchain-ai/deepagents/issues/3688)) ([15ca302](https://github.com/langchain-ai/deepagents/commit/15ca3029f18fa38c1592859febc2a6d0469bff2d))
+* Preserve MCP token refresh when metadata discovery fails ([#3685](https://github.com/langchain-ai/deepagents/issues/3685)) ([afafeeb](https://github.com/langchain-ai/deepagents/commit/afafeeb471c4008d4eb4263ec478cf868833fe0b))
+* Reduce OAuth login modal noise ([#3693](https://github.com/langchain-ai/deepagents/issues/3693)) ([0e8a780](https://github.com/langchain-ai/deepagents/commit/0e8a780e2dfea2e22ac44545a16279dbe30eb8ee))
+* Repair MCP OAuth login redirect and stale client registration ([#3692](https://github.com/langchain-ai/deepagents/issues/3692)) ([f741293](https://github.com/langchain-ai/deepagents/commit/f741293524f7d47eb8a16a3cd4def336c3c3c13f))
+* Search all models from `/model` filter ([#3690](https://github.com/langchain-ai/deepagents/issues/3690)) ([5fcb877](https://github.com/langchain-ai/deepagents/commit/5fcb877d094c4504f671bb7aeb52efa7bf3a5b48))
+* Serialize `QueuedUserMessage` as user input ([#3708](https://github.com/langchain-ai/deepagents/issues/3708)) ([307d598](https://github.com/langchain-ai/deepagents/commit/307d59826da9b1ddcbcdab8dccef6d18ecf16d10))
+* Serialize cold SDK imports ([#3712](https://github.com/langchain-ai/deepagents/issues/3712)) ([fb2adc0](https://github.com/langchain-ai/deepagents/commit/fb2adc0585e978b12646602ba922e252abf41f81))
+* Pluralize singular MCP login splash text ([#3689](https://github.com/langchain-ai/deepagents/issues/3689)) ([492b0fc](https://github.com/langchain-ai/deepagents/commit/492b0fc9209e13cd7004a255ef67b31b7e78e95e))
+
 ## [0.1.7](https://github.com/langchain-ai/deepagents/compare/deepagents-code==0.1.6...deepagents-code==0.1.7) (2026-05-30)
 
 ### Features
@@ -102,5 +123,7 @@ Hello world! Ported from `libs/cli`.
 
 ---
 
+## Prior Releases
+
 `deepagents-code` was forked from `deepagents-cli` at v0.1.0 (2026-05-12).
 For history prior to the fork, see [the `deepagents-cli` changelog](https://github.com/langchain-ai/deepagents/blob/main/libs/cli/CHANGELOG.md).

{deepagents_code-0.1.7 → deepagents_code-0.1.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deepagents-code
-Version: 0.1.7
+Version: 0.1.8
 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/
@@ -33,7 +33,7 @@ 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.3.2
+Requires-Dist: langchain<2.0.0,>=1.3.4
 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-runtime-inmem<1.0.0,>=0.28.1

{deepagents_code-0.1.7 → deepagents_code-0.1.8}/deepagents_code/_version.py

@@ -2,7 +2,7 @@
 
 # Keep the `x-release-please-version` annotation — release-please uses it to
 # bump `__version__` in sync with `pyproject.toml` on every release PR.
-__version__ = "0.1.7"  # x-release-please-version
+__version__ = "0.1.8"  # x-release-please-version
 
 DOCS_URL = "https://docs.langchain.com/oss/python/deepagents/code"
 """URL for `deepagents-code` documentation."""

{deepagents_code-0.1.7 → deepagents_code-0.1.8}/deepagents_code/agent.py

@@ -62,6 +62,7 @@ from deepagents_code.config import (
     settings,
 )
 from deepagents_code.configurable_model import ConfigurableModelMiddleware
+from deepagents_code.filesystem_empty_result import _FilesystemEmptyResultMiddleware
 from deepagents_code.integrations.sandbox_factory import get_default_working_dir
 from deepagents_code.local_context import (
     LocalContextMiddleware,
@@ -1240,8 +1241,10 @@ def create_cli_agent(
             custom_subagents.append(general_purpose_subagent)
 
     # Build middleware stack based on enabled features
-    agent_middleware = []
-    agent_middleware.append(ConfigurableModelMiddleware())
+    agent_middleware = [
+        ConfigurableModelMiddleware(),
+        _FilesystemEmptyResultMiddleware(),
+    ]
 
     # Resume state: declares the `_context_tokens` and `_model_spec` channels
     # and writes them from `after_model` (token count from the latest

{deepagents_code-0.1.7 → deepagents_code-0.1.8}/deepagents_code/app.py

@@ -103,6 +103,14 @@ _DEFERRED_START_NOTICE = (
 # read the same pre-mutation state and then clobber the other's keys.
 _CONFIG_WRITE_LOCK = threading.Lock()
 
+_DEEPAGENTS_IMPORT_LOCK = threading.RLock()
+"""Serializes process-local cold imports into the Deep Agents SDK graph.
+
+The SDK currently has a package-to-backend circular import that is safe when a
+single thread imports it re-entrantly, but can trip CPython's per-module import
+deadlock detector when two threads cold-import overlapping modules.
+"""
+
 _MESSAGE_TIMESTAMP_FOOTER_CLASS = "message-timestamp-footer"
 
 _TIMESTAMP_FOOTER_EXCLUDED_TYPES: frozenset[MessageType] = frozenset(
@@ -127,6 +135,32 @@ def _is_message_timestamp_footer(widget: Widget) -> bool:
     return widget.has_class(_MESSAGE_TIMESTAMP_FOOTER_CLASS)
 
 
+def _create_model_with_deepagents_import_lock(
+    model_spec: str | None = None,
+    *,
+    extra_kwargs: dict[str, Any] | None = None,
+    profile_overrides: dict[str, Any] | None = None,
+) -> ModelResult:
+    """Create a model while serializing Deep Agents SDK import entry.
+
+    Args:
+        model_spec: Model specification in `provider:model` format.
+        extra_kwargs: Extra model constructor kwargs.
+        profile_overrides: Model profile metadata overrides.
+
+    Returns:
+        Created model and resolved metadata.
+    """
+    with _DEEPAGENTS_IMPORT_LOCK:
+        from deepagents_code.config import create_model
+
+        return create_model(
+            model_spec,
+            extra_kwargs=extra_kwargs,
+            profile_overrides=profile_overrides,
+        )
+
+
 @dataclass(frozen=True)
 class _ConfigWriteResult:
     """Result of a config write with TUI-facing failure context."""
@@ -156,6 +190,7 @@ if TYPE_CHECKING:
     from textual.worker import Worker
 
     from deepagents_code._ask_user_types import AskUserWidgetResult, Question
+    from deepagents_code.config import ModelResult
     from deepagents_code.event_bus import EventSource, ExternalEvent
     from deepagents_code.mcp_tools import MCPServerInfo
     from deepagents_code.model_config import MissingProviderPackageError
@@ -525,6 +560,49 @@ def save_theme_preference(name: str) -> bool:
     return _save_theme_preference_result(name).ok
 
 
+def _load_cursor_blink_preference() -> bool:
+    """Load the saved cursor-blink preference from `~/.deepagents/config.toml`.
+
+    The chat input cursor blink can be turned off by setting
+    `[ui].cursor_blink = false` in the config file. There is no in-app command
+    for this; the file is edited manually.
+
+    Returns:
+        The saved `[ui].cursor_blink` value, or `True` (blink on) when unset,
+            unreadable, or malformed.
+    """
+    import tomllib
+
+    from deepagents_code.model_config import DEFAULT_CONFIG_PATH
+
+    if not DEFAULT_CONFIG_PATH.exists():
+        return True
+    try:
+        with DEFAULT_CONFIG_PATH.open("rb") as f:
+            data = tomllib.load(f)
+    except (tomllib.TOMLDecodeError, PermissionError, OSError) as exc:
+        logger.warning("Could not read config for cursor blink preference: %s", exc)
+        return True
+
+    ui = data.get("ui", {})
+    if not isinstance(ui, dict):
+        logger.warning(
+            "[ui] should be a table; got %s while loading cursor blink preference",
+            type(ui).__name__,
+        )
+        return True
+
+    value = ui.get("cursor_blink")
+    if isinstance(value, bool):
+        return value
+    if value is not None:
+        logger.warning(
+            "[ui].cursor_blink should be a boolean; got %s",
+            type(value).__name__,
+        )
+    return True
+
+
 def _save_terminal_theme_mapping_result(
     term_program: str,
     name: str,
@@ -1328,6 +1406,10 @@ class DeepAgentsApp(App):
         Loaded from the user's saved preference (or the default) so the app
         boots with consistent colors before `/theme` runs.
         """
+
+        self._cursor_blink_enabled = _load_cursor_blink_preference()
+        """Whether the chat input cursor should blink (user preference)."""
+
         self.sync_terminal_background()
 
         # Injected session config
@@ -1612,14 +1694,6 @@ class DeepAgentsApp(App):
         loop re-enters the same module graph (see that method for why).
         """
 
-        self._deepagents_import_lock = asyncio.Lock()
-        """Serializes cold imports into the Deep Agents graph after prewarm.
-
-        Startup model creation and skill discovery can both be triggered during
-        first paint. If prewarm failed or did not cover a transitive module,
-        both paths may cold-import overlapping modules at the same time.
-        """
-
         # Lifecycle flags & re-entry guards
         self._connecting = (
             server_kwargs is not None and not self._server_startup_deferred
@@ -1963,6 +2037,7 @@ class DeepAgentsApp(App):
 
         self._status_bar = self.query_one("#status-bar", StatusBar)
         self._chat_input = self.query_one("#input-area", ChatInput)
+        self._chat_input.set_cursor_blink(blink=self._cursor_blink_enabled)
 
         # Apply any skill commands discovered before the widget was mounted
         if self._discovered_skills:
@@ -2406,8 +2481,9 @@ class DeepAgentsApp(App):
             # graph in separate workers. Let prewarm finish first so CPython's
             # per-module import locks cannot form a cycle.
             await self._await_prewarm_imports()
-            async with self._deepagents_import_lock:
-                skills, roots = await asyncio.to_thread(self._discover_skills_and_roots)
+            skills, roots = await asyncio.to_thread(
+                self._discover_skills_and_roots_with_import_lock,
+            )
         except OSError:
             logger.warning(
                 "Filesystem error during skill discovery",
@@ -2465,6 +2541,17 @@ class DeepAgentsApp(App):
         assistant_id = self._assistant_id or DEFAULT_ASSISTANT_ID
         return discover_skills_and_roots(assistant_id)
 
+    def _discover_skills_and_roots_with_import_lock(
+        self,
+    ) -> tuple[list[ExtendedSkillMetadata], list[Path]]:
+        """Discover skills while serializing Deep Agents SDK import entry.
+
+        Returns:
+            Tuple of `(skill metadata list, pre-resolved containment roots)`.
+        """
+        with _DEEPAGENTS_IMPORT_LOCK:
+            return self._discover_skills_and_roots()
+
     async def _resolve_resume_thread(self) -> None:
         """Resolve a `-r` resume intent into a concrete thread ID.
 
@@ -2595,7 +2682,6 @@ class DeepAgentsApp(App):
             # `_await_prewarm_imports` for the deadlock rationale.
             await self._await_prewarm_imports()
 
-            from deepagents_code.config import create_model
             from deepagents_code.model_config import (
                 ModelConfigError,
                 save_recent_model,
@@ -2603,8 +2689,10 @@ class DeepAgentsApp(App):
             )
 
             try:
-                async with self._deepagents_import_lock:
-                    result = create_model(**self._model_kwargs)
+                result = await asyncio.to_thread(
+                    _create_model_with_deepagents_import_lock,
+                    **self._model_kwargs,
+                )
             except ModelConfigError as exc:
                 self.post_message(self.ServerStartFailed(error=exc))
                 return
@@ -2958,12 +3046,13 @@ class DeepAgentsApp(App):
             # tool_display — hit on first message send and first tool
             # approval. Best-effort: missing optional deps should not block the
             # TUI from rendering.
-            from deepagents.backends import DEFAULT_EXECUTE_TIMEOUT  # noqa: F401
-            from langchain.agents.middleware.human_in_the_loop import (  # noqa: F401
-                ApproveDecision,
-            )
-            from langchain_core.messages import AIMessage  # noqa: F401
-            from langgraph.types import Command  # noqa: F401
+            with _DEEPAGENTS_IMPORT_LOCK:
+                from deepagents.backends import DEFAULT_EXECUTE_TIMEOUT  # noqa: F401
+                from langchain.agents.middleware.human_in_the_loop import (  # noqa: F401
+                    ApproveDecision,
+                )
+                from langchain_core.messages import AIMessage  # noqa: F401
+                from langgraph.types import Command  # noqa: F401
         except Exception:
             logger.warning("Could not prewarm third-party imports", exc_info=True)
 
@@ -3349,9 +3438,13 @@ class DeepAgentsApp(App):
         force = "--force" in parts[1:]
         extras = [p for p in parts[1:] if not p.startswith("-")]
         if not extras:
+            from deepagents_code.extras_info import format_known_extras
+
             await self._mount_message(
                 AppMessage(
-                    "Usage: /install <extra> [--force]\nExample: /install quickjs",
+                    "Usage: /install <extra> [--force]\n"
+                    "Example: /install quickjs\n\n"
+                    f"{format_known_extras()}",
                 ),
             )
             return
@@ -3372,6 +3465,7 @@ class DeepAgentsApp(App):
                 KNOWN_EXTRAS,
                 MODEL_PROVIDER_EXTRAS,
                 SANDBOX_EXTRAS,
+                ExtrasIntrospectionError,
             )
             from deepagents_code.update_check import (
                 create_update_log_path,
@@ -3406,12 +3500,20 @@ class DeepAgentsApp(App):
             return
 
         if extra not in KNOWN_EXTRAS and not force:
+            try:
+                manual_cmd = await asyncio.to_thread(install_extra_command, extra)
+            except (ExtrasIntrospectionError, ValueError) as exc:
+                logger.warning("/install command failed", exc_info=True)
+                await self._mount_message(
+                    ErrorMessage(f"Install failed: {type(exc).__name__}: {exc}"),
+                )
+                return
             known = ", ".join(sorted(KNOWN_EXTRAS))
             await self._mount_message(
                 AppMessage(
                     f"'{extra}' is not a known extra.\n"
                     f"Known extras: {known}\n\n"
-                    f"This would run: `{install_extra_command(extra)}`\n"
+                    f"This would run: `{manual_cmd}`\n"
                     f"Re-run with `--force` to install anyway: "
                     f"`/install {extra} --force`",
                 ),
@@ -3422,7 +3524,16 @@ class DeepAgentsApp(App):
         await self._mount_message(
             AppMessage(f"Installing extra '{extra}'..."),
         )
-        manual_cmd = install_extra_command(extra)
+        try:
+            manual_cmd = await asyncio.to_thread(install_extra_command, extra)
+        except (ExtrasIntrospectionError, ValueError) as exc:
+            logger.warning("/install command failed", exc_info=True)
+            await self._mount_message(
+                ErrorMessage(
+                    f"Install failed: {type(exc).__name__}: {exc}\nLog: {log_path}",
+                ),
+            )
+            return
         try:
             success, output = await perform_install_extra(extra, log_path=log_path)
         except (OSError, asyncio.CancelledError) as exc:
@@ -4843,9 +4954,21 @@ class DeepAgentsApp(App):
             BYPASS_WHEN_CONNECTING,
             IMMEDIATE_UI,
             SIDE_EFFECT_FREE,
+            STARTUP_RECOVERY_COMMANDS,
         )
 
         cmd = value.split(maxsplit=1)[0] if value else ""
+        # Recovery escape hatch: when startup failed (`_server_startup_error`
+        # set) and nothing is running, the commands that repair the session
+        # must run instead of being parked behind the failure they fix — e.g.
+        # `/install <pkg>` for a missing provider package. Gated on no active
+        # work so a reinstall never swaps the running binary mid-turn.
+        if (
+            cmd in STARTUP_RECOVERY_COMMANDS
+            and self._server_startup_error is not None
+            and not (self._agent_running or self._shell_running)
+        ):
+            return True
         if cmd in BYPASS_WHEN_CONNECTING:
             return self._connecting and not (self._agent_running or self._shell_running)
         if cmd in IMMEDIATE_UI:
@@ -5841,7 +5964,7 @@ class DeepAgentsApp(App):
         if cached is None:
             try:
                 skills, allowed_roots = await asyncio.to_thread(
-                    self._discover_skills_and_roots,
+                    self._discover_skills_and_roots_with_import_lock,
                 )
                 # Backfill cache so subsequent invocations are fast
                 self._discovered_skills = skills
@@ -6010,31 +6133,33 @@ class DeepAgentsApp(App):
         """Resolve the offload retention budget as a human-readable string.
 
         Instantiates a model and computes summarization defaults, so this is
-        not a trivial accessor.
+        not a trivial accessor. Call only from a worker thread; cold imports
+        and model construction run under the process-wide import lock.
 
         Returns:
             A string like `"20.0K (10% of 200.0K)"` or
             `"last 6 messages"`, or `None` if the budget cannot be determined.
         """
-        from deepagents_code.config import create_model, settings
+        from deepagents_code.config import settings
 
         try:
-            from deepagents.middleware.summarization import (
-                compute_summarization_defaults,
-            )
+            with _DEEPAGENTS_IMPORT_LOCK:
+                from deepagents.middleware.summarization import (
+                    compute_summarization_defaults,
+                )
 
-            model_spec = f"{settings.model_provider}:{settings.model_name}"
-            result = create_model(
-                model_spec,
-                profile_overrides=self._profile_override,
-            )
-            defaults = compute_summarization_defaults(result.model)
-            from deepagents_code.offload import format_offload_limit
+                model_spec = f"{settings.model_provider}:{settings.model_name}"
+                result = _create_model_with_deepagents_import_lock(
+                    model_spec,
+                    profile_overrides=self._profile_override,
+                )
+                defaults = compute_summarization_defaults(result.model)
+                from deepagents_code.offload import format_offload_limit
 
-            return format_offload_limit(
-                defaults["keep"],
-                settings.model_context_limit,
-            )
+                return format_offload_limit(
+                    defaults["keep"],
+                    settings.model_context_limit,
+                )
         except Exception:  # best-effort for /tokens display
             logger.debug("Failed to compute offload budget string", exc_info=True)
             return None
@@ -6918,6 +7043,17 @@ class DeepAgentsApp(App):
         if not messages.is_attached:
             return
 
+        if isinstance(widget, QueuedUserMessage):
+            # Queued placeholders mount at the bottom and stay out of the
+            # message store; drain remounts them as real UserMessage widgets.
+            await messages.mount(widget)
+            try:
+                input_container = self.query_one("#bottom-app-container", Container)
+                input_container.scroll_visible()
+            except NoMatches:
+                pass
+            return
+
         # Store message data for virtualization
         message_data = MessageData.from_widget(widget)
         if not widget.id:
@@ -6927,14 +7063,9 @@ class DeepAgentsApp(App):
         self._message_store.append(message_data)
         footer = self._build_message_timestamp_footer(message_data)
 
-        # Queued-message widgets must always stay at the bottom so they
-        # remain visually anchored below the current agent response.
-        if isinstance(widget, QueuedUserMessage):
-            await messages.mount(widget)
-        else:
-            await self._mount_before_queued(messages, widget)
-            if footer is not None:
-                await self._mount_before_queued(messages, footer)
+        await self._mount_before_queued(messages, widget)
+        if footer is not None:
+            await self._mount_before_queued(messages, footer)
 
         # Prune old widgets if window exceeded
         await self._prune_old_messages()
@@ -7622,7 +7753,7 @@ class DeepAgentsApp(App):
         """
         if self._chat_input is None:
             return
-        self._chat_input.set_cursor_blink(blink=True)
+        self._chat_input.set_cursor_blink(blink=self._cursor_blink_enabled)
         if isinstance(self.screen, ModalScreen):
             return
         if self._pending_approval_widget or self._pending_ask_user_widget:
@@ -9198,7 +9329,7 @@ class DeepAgentsApp(App):
                             name=entry.name,
                             transport=entry.transport,
                             status="disabled",
-                            error="Re-enabled — run `/mcp reconnect` to load.",
+                            error="Re-enabled — press Ctrl+R to load.",
                         ),
                     )
         self._mcp_server_info = updated
@@ -9995,7 +10126,7 @@ class DeepAgentsApp(App):
                 messaging (which model couldn't be restored and what the session
                 is falling back to) rather than the interactive `/model` errors.
         """
-        from deepagents_code.config import create_model, detect_provider, settings
+        from deepagents_code.config import detect_provider, settings
         from deepagents_code.model_config import (
             ModelSpec,
             ProviderAuthState,
@@ -10121,7 +10252,8 @@ class DeepAgentsApp(App):
                 display = f"{provider}:{model_name}"
 
             try:
-                result = create_model(
+                result = await asyncio.to_thread(
+                    _create_model_with_deepagents_import_lock,
                     display,
                     extra_kwargs=extra_kwargs,
                     profile_overrides=self._profile_override,

{deepagents_code-0.1.7 → deepagents_code-0.1.8}/deepagents_code/ask_user.py

@@ -248,6 +248,11 @@ class AskUserMiddleware(AgentMiddleware[Any, ContextT, ResponseT]):
                 questions=questions,
                 tool_call_id=tool_call_id,
             )
+            # interrupt() raises GraphInterrupt from INSIDE tool execution,
+            # within ToolNode's wrap_tool_call chain. Any
+            # wrap_tool_call middleware that catches exceptions MUST re-raise
+            # GraphBubbleUp — a broad `except Exception` (e.g. ToolRetryMiddleware)
+            # would swallow this interrupt and silently break ask_user.
             response = interrupt(ask_request)
             return _parse_answers(response, questions, tool_call_id)
 

{deepagents_code-0.1.7 → deepagents_code-0.1.8}/deepagents_code/command_registry.py

@@ -282,6 +282,23 @@ Includes both debug helpers (`/debug-error`) and recovery escape hatches
 (`/restart` — hot-respawn the app-owned LangGraph server).
 """
 
+STARTUP_RECOVERY_COMMANDS: frozenset[str] = frozenset(
+    {"/install", "/reload", "/update"}
+)
+"""`QUEUED`-tier commands that must still run when startup has failed.
+
+When the configured model can't be built (e.g. its provider package is
+missing) the server never starts and the app holds a `_server_startup_error`
+state that parks queued messages. These are the recovery escape hatches for
+that state — install the missing package, reload config/env, or upgrade the
+tool — so they must bypass the queue rather than sit behind the very failure
+they repair. `/model` and `/auth` already escape via `IMMEDIATE_UI` (which
+opens a modal and defers the real work); the commands here instead perform
+their repair work directly, so they stay `QUEUED` and rely on this exemption.
+The bypass itself is gated in `_can_bypass_queue`. Every entry is also
+`QUEUE_BOUND` — the recovery exemption is orthogonal to the normal queue.
+"""
+
 ALL_CLASSIFIED: frozenset[str] = (
     ALWAYS_IMMEDIATE
     | BYPASS_WHEN_CONNECTING

{deepagents_code-0.1.7 → deepagents_code-0.1.8}/deepagents_code/extras_info.py

@@ -24,6 +24,11 @@ logger = logging.getLogger(__name__)
 
 _EXTRA_MARKER_RE = re.compile(r"""extra\s*==\s*["']([^"']+)["']""")
 
+
+class ExtrasIntrospectionError(RuntimeError):
+    """Raised when installed extras cannot be determined safely."""
+
+
 _COMPOSITE_EXTRAS: frozenset[str] = frozenset({"all-providers", "all-sandboxes"})
 """Extras whose package set is already covered by other, more specific extras.
 
@@ -84,6 +89,31 @@ model-provider-drift checks; new extras must be added to the corresponding
 category frozenset above.
 """
 
+
+def format_known_extras() -> str:
+    """Render the installable extras grouped by category as plain text.
+
+    Drives the no-argument `/install` slash-command help so users can
+    discover valid extras without consulting `pyproject.toml`. Sourced from
+    the category frozensets above, so it stays in sync with `KNOWN_EXTRAS`
+    automatically.
+
+    Returns:
+        Multi-line string with one labeled line per category, each listing
+            its extras alphabetically.
+    """
+    groups: tuple[tuple[str, frozenset[str]], ...] = (
+        ("Model providers", MODEL_PROVIDER_EXTRAS),
+        ("Sandboxes", SANDBOX_EXTRAS),
+        ("Other", STANDALONE_EXTRAS),
+    )
+    lines = ["Available extras:"]
+    lines.extend(
+        f"  {label}: {', '.join(sorted(extras))}" for label, extras in groups if extras
+    )
+    return "\n".join(lines)
+
+
 ExtrasStatus = dict[str, list[tuple[str, str]]]
 """Mapping from extra name to `(package, installed_version)` tuples.
 
@@ -155,21 +185,55 @@ def get_extras_status(
     return result
 
 
+def installed_extra_names(
+    distribution_name: str = "deepagents-code",
+    *,
+    strict: bool = False,
+) -> set[str]:
+    """Return extras with at least one installed dependency.
+
+    Args:
+        distribution_name: Name of the installed distribution to inspect.
+        strict: Raise when the distribution metadata cannot be read or parsed
+            reliably.
+
+    Returns:
+        Set of extra names whose optional dependency metadata has at least one
+            installed package. Composite extras are excluded.
+    """
+    statuses = get_optional_dependency_status(distribution_name, strict=strict)
+    return {extra.name for extra in statuses if extra.installed}
+
+
 def get_optional_dependency_status(
     distribution_name: str = "deepagents-code",
+    *,
+    strict: bool = False,
 ) -> tuple[ExtraDependencyStatus, ...]:
     """Return installed and missing optional dependencies grouped by extra.
 
     Args:
         distribution_name: Name of the installed distribution to inspect.
+        strict: Raise when the distribution metadata cannot be read or parsed
+            reliably.
 
     Returns:
         Sorted tuple of optional extra statuses. An empty tuple is returned
             when the distribution itself is not found.
+
+    Raises:
+        ExtrasIntrospectionError: If `strict` is `True` and metadata
+            introspection fails.
     """
     try:
         dist = distribution(distribution_name)
     except PackageNotFoundError:
+        if strict:
+            msg = (
+                f"Distribution {distribution_name!r} not found; cannot preserve "
+                "already-installed extras safely"
+            )
+            raise ExtrasIntrospectionError(msg) from None
         # Editable installs renamed by the user, dev checkouts without metadata,
         # or vendored copies all hit this path. The dependency screen otherwise
         # silently renders "none detected" twice; warn so the cause is visible.
@@ -186,6 +250,12 @@ def get_optional_dependency_status(
         try:
             req = Requirement(raw)
         except InvalidRequirement:
+            if strict:
+                msg = (
+                    "Could not parse optional-dependency metadata; cannot "
+                    f"preserve already-installed extras safely: {raw}"
+                )
+                raise ExtrasIntrospectionError(msg) from None
             logger.warning("Could not parse Requires-Dist entry: %s", raw)
             continue
         if not req.marker: