deepagents-code 0.1.86__tar.gz → 0.1.87__tar.gz

{deepagents_code-0.1.86 → deepagents_code-0.1.87}/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 # Deep Agents Code Changelog
 
+## [0.1.87](https://github.com/langchain-ai/deepagents/compare/deepagents-code==0.1.86...deepagents-code==0.1.87) (2026-10-20)
+
+### Features
+
+- Resume threads in non-interactive mode ([#7011](https://github.com/langchain-ai/deepagents/pull/7011)).
+- Compact large idle sessions before the prompt cache expires ([#6956](https://github.com/langchain-ai/deepagents/pull/6956)) and show the prompt-cache expiration time ([#7005](https://github.com/langchain-ai/deepagents/pull/7005)).
+- Support custom Slack OAuth app identity ([#7061](https://github.com/langchain-ai/deepagents/pull/7061)).
+- Load older threads from the thread switcher ([#7051](https://github.com/langchain-ai/deepagents/pull/7051)).
+
+### Bug Fixes
+
+- Stop the local server when its owner dies ([#7038](https://github.com/langchain-ai/deepagents/pull/7038)).
+- Support non-ASCII file names in `@` mentions ([#7023](https://github.com/langchain-ai/deepagents/pull/7023)).
+- Correct misleading `/reload` change summaries ([#7063](https://github.com/langchain-ai/deepagents/pull/7063)).
+
 ## [0.1.86](https://github.com/langchain-ai/deepagents/compare/deepagents-code==0.1.85...deepagents-code==0.1.86) (2026-10-16)
 
 ### Features

{deepagents_code-0.1.86 → deepagents_code-0.1.87}/DEVELOPMENT.md

@@ -69,6 +69,30 @@ make lint
 
 Run `make help` to see every available target.
 
+## Custom Slack MCP app identity
+
+Slack's hosted MCP server attributes sent messages to the OAuth app used to connect. To use your own registered Slack app instead of Deep Agents Code, add an `oauth` object to its `.mcp.json` server entry:
+
+```json
+{
+  "mcpServers": {
+    "slack": {
+      "type": "http",
+      "url": "https://mcp.slack.com/mcp",
+      "auth": "oauth",
+      "oauth": {
+        "client_id": "${SLACK_CLIENT_ID}",
+        "client_secret": "${SLACK_CLIENT_SECRET}"
+      }
+    }
+  }
+}
+```
+
+Enable MCP access for your Slack app and register `http://localhost:3118/callback` as its redirect URL. Set the environment variables and run `dcode mcp login slack` to authorize it. Confidential apps use `client_secret_post`; omit `client_secret` only for an app registered as a public client. Keep secrets in environment variables, not committed config. The registration, including any secret, is saved in the existing restricted local token store.
+
+Credentials are isolated by server name, URL, and configured client ID, so changing apps requires a separate login and never reuses the default app's grant. Re-run login after rotating a client secret. Omitting `oauth` preserves the existing app and credentials. This selects the authenticated app; it does not let a message supply arbitrary attribution or suppress Slack's footer. These settings apply to dcode; Talon's separate OAuth implementation is unchanged.
+
 ## LangSmith tracing projects
 
 When LangSmith tracing is enabled and a `LANGSMITH_API_KEY` is available, `deepagents-code` traces its own agent runs to LangSmith. A key alone is not enough for environment-supplied keys — set `LANGSMITH_TRACING=true`. Keys stored via `/auth` auto- enable tracing unless you explicitly opt out (for example `DEEPAGENTS_CODE_LANGSMITH_TRACING=false`).
@@ -91,6 +115,33 @@ When onboarding a new tracing project to Engine, capture the nature of that proj
 
 A server keeps the first workspace's tracing configuration for its lifetime. Workspaces sharing that server must use matching tracing credentials, projects, endpoints, profile selectors, tracing flags, and redaction policy. A conflicting workspace is refused before its settings can affect cached or concurrent runs; start a separate server for that workspace. Restart the server to change its tracing configuration.
 
+## Idle context compaction
+
+Idle compaction is disabled by default. When enabled, the interactive client
+automatically uses the existing `/offload` operation for contexts at or above
+the configured token threshold during the final 20% of a known prompt-cache
+retention window, capped at 120 seconds (60 seconds for a 5-minute window). This keeps the same thread and archives older
+messages; it does not create a handoff thread. The configured offload model is
+used, so summarization can incur costs and cache reuse is not guaranteed.
+
+Opt in with a token threshold through the normal layered config:
+
+```toml
+[history]
+idle_compaction_tokens = 100000
+```
+
+Alternatively, set `DEEPAGENTS_CODE_IDLE_COMPACTION_TOKENS=100000` before
+launching dcode.
+
+Set `idle_compaction_tokens = 0` to disable it again. File edits take effect after
+`/reload`. This setting is independent of cold-cache warning preferences.
+Compaction skips busy sessions, queued input, active typing, modals, lifecycle
+transitions, and approximate token counts. It attempts at most once per thread
+and cache window, announces the operation, and supports Escape cancellation.
+Input arriving before the worker starts skips compaction; input arriving after
+it starts uses the normal offload queue and runs once compaction finishes.
+
 ## Debugging
 
 Deep Agents Code runs as two processes: the **Textual TUI** you interact with, and a **`langgraph dev` subprocess** that hosts the agent graph. Each writes its own log, and a single switch turns both on:

{deepagents_code-0.1.86 → deepagents_code-0.1.87}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: deepagents-code
-Version: 0.1.86
+Version: 0.1.87
 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://www.langchain.com/dcode
 Project-URL: Documentation, https://docs.langchain.com/oss/deepagents/code/overview
@@ -30,7 +30,7 @@ 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.28
+Requires-Dist: deepagents==0.7.29
 Requires-Dist: fastmcp<5.0.0,>=4.0.0b4
 Requires-Dist: filelock<3.30,>=3.29.7
 Requires-Dist: genai-prices<0.2.0,>=0.1.13
@@ -41,9 +41,9 @@ Requires-Dist: langchain-openai<2.0.0,>=1.7.2
 Requires-Dist: langchain-quickjs<0.4.0,>=0.3.4
 Requires-Dist: langchain<2.0.0,>=1.4.6
 Requires-Dist: langgraph-checkpoint-sqlite<4.0.0,>=3.1.2
-Requires-Dist: langgraph-cli[inmem]<1.0.0,>=0.4.35
-Requires-Dist: langgraph-runtime-inmem<1.0.0,>=0.36.1
-Requires-Dist: langgraph-sdk<1.0.0,>=0.4.7
+Requires-Dist: langgraph-cli[inmem]<1.0.0,>=0.4.37
+Requires-Dist: langgraph-runtime-inmem<1.0.0,>=0.36.2
+Requires-Dist: langgraph-sdk<1.0.0,>=0.4.8
 Requires-Dist: langsmith[sandbox]>=0.14.11
 Requires-Dist: markdownify<2.0.0,>=1.2.3
 Requires-Dist: mcp<3.0.0,>=2.0.0

{deepagents_code-0.1.86 → deepagents_code-0.1.87}/deepagents_code/_build_info.py

@@ -1,3 +1,3 @@
 """Generated at build time. Do not edit or commit."""
 
-BUILD_COMMIT = "577e3f1"
+BUILD_COMMIT = "d1962cf"

{deepagents_code-0.1.86 → deepagents_code-0.1.87}/deepagents_code/_constants.py

@@ -14,7 +14,7 @@ DEFAULT_AGENT_NAME: Final[str] = "agent"
 """Default agent / assistant identifier when no `-a` flag is given."""
 
 DEFAULT_THREAD_LIMIT: Final[int] = 100
-"""Fallback maximum number of recent threads to load and display."""
+"""Fallback for `get_thread_limit()`, the thread switcher batch size."""
 
 FS_TOOL_NAMES: Final[frozenset[str]] = frozenset(
     {"ls", "read_file", "write_file", "edit_file", "delete", "glob", "grep", "execute"}

{deepagents_code-0.1.86 → deepagents_code-0.1.87}/deepagents_code/_env_vars.py

@@ -328,6 +328,9 @@ HIDE_SPLASH_TIPS = "DEEPAGENTS_CODE_HIDE_SPLASH_TIPS"
 HIDE_SPLASH_VERSION = "DEEPAGENTS_CODE_HIDE_SPLASH_VERSION"
 """Hide version and local-install details in the splash screen when enabled."""
 
+IDLE_COMPACTION_TOKENS = "DEEPAGENTS_CODE_IDLE_COMPACTION_TOKENS"
+"""Minimum context tokens for opt-in idle compaction; 0 disables it."""
+
 HISTORY_RETENTION_DAYS = "DEEPAGENTS_CODE_HISTORY_RETENTION_DAYS"
 """Days an offloaded conversation-history archive is kept before the startup
 sweep deletes it.
@@ -514,7 +517,11 @@ repo file, so a project `.env` cannot disable itself.
 """
 
 RECENT_THREADS = "DEEPAGENTS_CODE_RECENT_THREADS"
-"""Maximum recent threads (default: `_constants.DEFAULT_THREAD_LIMIT`)."""
+"""Recent threads per batch (default: 100, `_constants.DEFAULT_THREAD_LIMIT`).
+
+The thread switcher loads this many at a time. It is also the default row
+limit for `threads list` (override with `-n`) and `@@` thread completion.
+"""
 
 RECURSION_LIMIT = "DEEPAGENTS_CODE_RECURSION_LIMIT"
 """Override the main agent's LangGraph `recursion_limit` (graph step budget).

{deepagents_code-0.1.86 → deepagents_code-0.1.87}/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.86"  # x-release-please-version
+__version__ = "0.1.87"  # x-release-please-version
 
 DOCS_URL = "https://docs.langchain.com/oss/python/deepagents/code"
 """URL for `deepagents-code` documentation."""

{deepagents_code-0.1.86 → deepagents_code-0.1.87}/deepagents_code/app.py

@@ -2111,6 +2111,9 @@ Two seconds balances responsiveness with avoiding accidental approval
 key presses.
 """
 
+_IDLE_COMPACTION_LEAD_SECONDS = 120
+"""Lead time for automatic idle context compaction."""
+
 _CACHE_EXPIRING_LEAD_SECONDS = 60
 """Lead time for the prompt-cache retention notification."""
 
@@ -4579,6 +4582,7 @@ class DeepAgentsApp(App):
         )
         """Minimum estimated cold-versus-warm cost delta that opens the modal."""
 
+        self._idle_compaction_seen: dict[str, datetime] = {}
         self._cache_expiring_seen: dict[str, datetime] = {}
         self._cache_expiring_worker: Worker[None] | None = None
 
@@ -6016,16 +6020,9 @@ class DeepAgentsApp(App):
         Returns:
             A short user-facing provenance and rationale sentence.
         """
-        if source == "managed config":
-            owner = "Your administrator set this policy through managed config"
-        elif source == "config.toml":
-            owner = "This policy was set in your config.toml"
-        else:
-            owner = "This policy was set by active configuration"
-        return (
-            f"{owner} to keep older threads from restoring stale context after "
-            "model or policy changes."
-        )
+        from deepagents_code.resume_policy import resume_cutoff_explanation
+
+        return resume_cutoff_explanation(source)
 
     @staticmethod
     def _resume_cutoff() -> tuple[datetime, str, bool] | None:
@@ -6034,69 +6031,16 @@ class DeepAgentsApp(App):
         Returns:
             The cutoff, its source, and whether it is rolling, or `None`.
         """
-        from deepagents_code.config_manifest import (
-            _emit_ranked_diagnostics,
-            _ranked_source,
-            get_option,
-            parse_duration_seconds,
-        )
-        from deepagents_code.configuration.resolver import get_config_resolver
+        from deepagents_code.resume_policy import resume_cutoff
 
-        resolver = get_config_resolver()
-        cutoffs: list[tuple[datetime, str, bool]] = []
-        for key in ("threads.resume_after", "threads.max_resume_age"):
-            option = get_option(key)
-            if option is None:
-                continue
-            resolved = resolver.get(option)
-            _emit_ranked_diagnostics(option, resolved)
-            value = resolved.value
-            if key.endswith("resume_after") and isinstance(value, str):
-                cutoffs.append(
-                    (datetime.fromisoformat(value), _ranked_source(resolved), False)
-                )
-            elif key.endswith("max_resume_age") and isinstance(value, str):
-                seconds = parse_duration_seconds(value)
-                if seconds is not None:
-                    cutoff = datetime.min.replace(tzinfo=UTC)
-                    with suppress(OverflowError):
-                        cutoff = datetime.now(UTC) - timedelta(seconds=seconds)
-                    cutoffs.append((cutoff, _ranked_source(resolved), True))
-        return max(cutoffs, default=None)
+        return resume_cutoff()
 
     @staticmethod
     async def _thread_resume_block(thread_id: str) -> str | None:
         """Return why configured policy blocks resuming a thread, if applicable."""
-        from deepagents_code.config_manifest import normalize_iso_datetime
-        from deepagents_code.sessions import get_thread_updated_at
+        from deepagents_code.resume_policy import thread_resume_block
 
-        policy = DeepAgentsApp._resume_cutoff()
-        if policy is None:
-            return None
-        cutoff, source, rolling = policy
-        explanation = DeepAgentsApp._resume_cutoff_explanation(source)
-        updated_value = await get_thread_updated_at(thread_id)
-        normalized = normalize_iso_datetime(updated_value)
-        if normalized is None:
-            logger.warning(
-                "Blocking resume for thread %s: missing or invalid updated_at %r",
-                thread_id,
-                updated_value,
-            )
-            return (
-                f"Thread {thread_id} cannot be resumed because its last-updated "
-                f"time could not be verified.\n\n{explanation}"
-            )
-        if datetime.fromisoformat(normalized) >= cutoff:
-            return None
-        reason = (
-            "it is older than the configured maximum age"
-            if rolling
-            else f"it was last updated before {cutoff.isoformat()}"
-        )
-        return (
-            f"Thread {thread_id} cannot be resumed because {reason}.\n\n{explanation}"
-        )
+        return await thread_resume_block(thread_id, DeepAgentsApp._resume_cutoff())
 
     def _reserve_thread(self, thread_id: str) -> None:
         """Reserve a locally managed thread before reading or adopting it."""
@@ -9758,29 +9702,72 @@ class DeepAgentsApp(App):
         banners = self.screen_stack[0].query("#cache-expired-banner")
         if banners:
             expires_at = self._status_bar.cache_expires_at if self._status_bar else None
-            banners.first().display = (
+            banner = banners.first(Static)
+            banner.display = (
                 not self._cache_reconciliation_pending
                 and expires_at is not None
                 and datetime.now(UTC) >= expires_at
             )
+            if banner.display and expires_at is not None:
+                expired_at = expires_at.astimezone().strftime("%H:%M:%S")
+                elapsed = datetime.now(UTC) - expires_at
+                age = "just now"
+                for unit in ("day", "hour", "minute"):
+                    count = elapsed // timedelta(**{f"{unit}s": 1})
+                    if count:
+                        age = f"{count} {unit}{'s' if count != 1 else ''} ago"
+                        break
+                banner.update(f"Prompt cache expired at {expired_at} ({age})")
 
-    def _check_cache_expiry(self) -> None:
-        """Offer a handoff once per expired cache window, only when idle.
+    def _check_idle_compaction(self) -> None:
+        """Reserve one offload per warm cache window, without yielding to input."""
+        from deepagents_code.config_manifest import get_option
+        from deepagents_code.configuration.resolver import get_config_resolver
 
-        Polled every second from `on_mount`. Acts only when
-        `warnings.cache_prompt` is `expiry` and no cold-cache opt-out applies.
-        """
-        self._refresh_cache_expiry_banner()
+        option = get_option("history.idle_compaction_tokens")
+        threshold = get_config_resolver().get(option).value if option else 0
         expires_at = self._status_bar.cache_expires_at if self._status_bar else None
+        window = self._status_bar.cache_window_seconds if self._status_bar else None
+        lead = min(window * 0.2, _IDLE_COMPACTION_LEAD_SECONDS) if window else 0
         thread_id = self._lc_thread_id
         if (
-            expires_at is None
+            not isinstance(threshold, int)
+            or threshold <= 0
+            or self._tokens_approximate
+            or self._context_tokens < threshold
             or not thread_id
-            or datetime.now(UTC) < expires_at
-            or self._cache_expiry_seen.get(thread_id) == expires_at
-            or not self._agent
+            or expires_at is None
+            or self._idle_compaction_seen.get(thread_id) == expires_at
+            or not 0 < (expires_at - datetime.now(UTC)).total_seconds() <= lead
+            or not self._cache_maintenance_idle()
+            or self._remote_agent() is None
+        ):
+            return
+        self._idle_compaction_seen[thread_id] = expires_at
+        self._set_agent_running(True)
+        try:
+            self._offload_worker = self.run_worker(
+                self._run_offload_task(idle_window=(thread_id, expires_at)),
+                group="offload",
+                exit_on_error=False,
+            )
+        except Exception:
+            self._set_agent_running(False)
+            logger.exception("Failed to schedule idle compaction")
+
+    def _cache_maintenance_idle(self, *, reserved: bool = False) -> bool:
+        """Require a quiescent UI before automatic cache maintenance.
+
+        Args:
+            reserved: Ignore the automatic offload's own busy reservation.
+
+        Returns:
+            Whether no UI activity competes with cache maintenance.
+        """
+        return not (
+            not self._agent
             or not self._session_state
-            or self._agent_running
+            or (self._agent_running and not reserved)
             or self._agent_reconciling
             or self._goal_state_mutating
             or self._shell_running
@@ -9796,6 +9783,25 @@ class DeepAgentsApp(App):
             or self._reloading
             or self._exiting
             or isinstance(self.screen, ModalScreen)
+            or self._cache_reconciliation_pending
+        )
+
+    def _check_cache_expiry(self) -> None:
+        """Offer a handoff once per expired cache window, only when idle.
+
+        Polled every second from `on_mount`. Acts only when
+        `warnings.cache_prompt` is `expiry` and no cold-cache opt-out applies.
+        """
+        self._refresh_cache_expiry_banner()
+        self._check_idle_compaction()
+        expires_at = self._status_bar.cache_expires_at if self._status_bar else None
+        thread_id = self._lc_thread_id
+        if (
+            expires_at is None
+            or not thread_id
+            or datetime.now(UTC) < expires_at
+            or self._cache_expiry_seen.get(thread_id) == expires_at
+            or not self._cache_maintenance_idle()
         ):
             return
         if (
@@ -18310,7 +18316,7 @@ class DeepAgentsApp(App):
                     f"  - {change}" for change in changes
                 )
             else:
-                report = "Configuration reloaded. No changes detected."
+                report = "Configuration reloaded."
             report += "\nModel config caches cleared."
             if theme_reload_ok:
                 report += "\nTheme registry reloaded."
@@ -18803,10 +18809,26 @@ class DeepAgentsApp(App):
                 ErrorMessage(f"Offload failed: {format_agent_exception(exc)}")
             )
 
-    async def _run_offload_task(self) -> None:
+    async def _run_offload_task(
+        self, *, idle_window: tuple[str, datetime] | None = None
+    ) -> None:
         """Run a synchronously reserved `/offload` outside the App message pump."""
         self._offload_task_started = True
         try:
+            if idle_window is not None:
+                if (
+                    self._lc_thread_id != idle_window[0]
+                    or not self._status_bar
+                    or self._status_bar.cache_expires_at != idle_window[1]
+                    or datetime.now(UTC) >= idle_window[1]
+                    or not self._cache_maintenance_idle(reserved=True)
+                ):
+                    self._set_agent_running(False)
+                    return
+                self.notify(
+                    "Compacting idle context before cache expiry.",
+                    markup=False,
+                )
             await self._handle_offload(reserved=True)
         finally:
             self._offload_task_started = False
@@ -30632,46 +30654,14 @@ class DeepAgentsApp(App):
     ) -> tuple[Literal["match", "unavailable", "mismatch"], Path | None]:
         """Classify a stored thread cwd against the current app cwd.
 
-        Args:
-            raw: The cwd recorded in the thread's checkpoint metadata. May be
-                relative or use `~`; both are normalized here.
-            current_cwd: The app's current working directory.
+        See `resume_policy.classify_thread_cwd`.
 
         Returns:
-            A `(status, path)` pair. `path` is only set when `status` is
-            `"mismatch"`; it is `None` otherwise. `status` is one of:
-
-            - `"match"`: the stored cwd resolves to the current cwd; no action.
-            - `"unavailable"`: the stored cwd is relative/malformed, or names an
-                absolute directory that no longer exists — it cannot be honored,
-                so the caller should warn and stay put.
-            - `"mismatch"`: the stored cwd is a real directory that differs from
-                the current cwd — the caller should offer to switch.
-        """
-        target = Path(raw).expanduser()
-        if not target.is_absolute() or not target.is_dir():
-            # Relative/malformed or missing directory: cannot be honored.
-            return "unavailable", None
-        try:
-            current = Path(current_cwd).expanduser().resolve()
-            resolved = target.resolve()
-        except OSError:
-            # Symlink resolution failed (e.g. ELOOP, permission on a path
-            # component). Fall back to a non-resolving comparison, which can
-            # report a spurious mismatch for symlinked-but-equal paths; log so
-            # the degraded comparison is traceable.
-            logger.debug(
-                "Could not resolve cwd paths for mismatch check (%r vs %r); "
-                "falling back to non-resolving comparison",
-                current_cwd,
-                raw,
-                exc_info=True,
-            )
-            current = Path(current_cwd).expanduser().absolute()
-            resolved = target.absolute()
-        if current == resolved:
-            return "match", None
-        return "mismatch", resolved
+            A `(status, path)` pair; `path` is set only for `"mismatch"`.
+        """
+        from deepagents_code.resume_policy import classify_thread_cwd
+
+        return classify_thread_cwd(raw, current_cwd)
 
     async def _thread_cwd_mismatch(self, thread_id: str) -> Path | None:
         """Return the thread cwd when it differs from the current app cwd."""

{deepagents_code-0.1.86 → deepagents_code-0.1.87}/deepagents_code/client/commands/mcp.py

@@ -152,14 +152,18 @@ async def run_mcp_login_list(*, config_path: str | None) -> int:
             continue
         try:
             resolved_config = resolve_mcp_server_env(server_name, server_config)
-        except (RuntimeError, TypeError) as exc:
+        except (RuntimeError, TypeError, ValueError) as exc:
             print(  # noqa: T201
                 f"Invalid MCP server config for {server_name!r}: {exc}",
                 file=sys.stderr,
             )
             unreadable += 1
             continue
-        storage = FileTokenStorage(server_name, server_url=resolved_config["url"])
+        storage = FileTokenStorage(
+            server_name,
+            server_url=resolved_config["url"],
+            oauth_client_id=(resolved_config.get("oauth") or {}).get("client_id"),
+        )
         try:
             tokens = await storage.get_tokens()
         except (OSError, RuntimeError, ValueError) as exc:

deepagents_code-0.1.87/deepagents_code/client/headless_resume.py

@@ -0,0 +1,133 @@
+"""Resolve `dcode -r <id> -n ...` into a thread the headless run may continue.
+
+Headless resume never falls back to a new thread. Threads stay bound to the
+workspace policy they were created with, so only threads started headless from
+the same directory with the same flags can be resumed here.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, cast
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+
+@dataclass(frozen=True)
+class ResumeRequest:
+    """An explicit `-r <id>` resume request from the command line."""
+
+    thread_id: str
+
+    adopt_agent: bool
+    """Use the thread's agent; `False` when `-a` was given."""
+
+    adopt_model: bool
+    """Use the thread's last model; `False` when `-M` was given."""
+
+
+@dataclass(frozen=True)
+class ResumeTarget:
+    """A thread that exists and passes the resume-age policy."""
+
+    thread_id: str
+    agent_name: str | None
+    cwd: str | None
+
+
+class ResumeError(Exception):
+    """A user-facing reason the requested thread cannot be resumed."""
+
+
+WORKSPACE_CONFLICT_MESSAGE = (
+    "Couldn't resume this thread because it was created with different "
+    "settings. A thread keeps the directory, agent, approval, shell, sandbox, "
+    "and MCP settings it started with, so threads from the interactive UI "
+    "can't be resumed with -n. Rerun from the same directory with the same "
+    "flags as the run that created it."
+)
+
+
+async def resolve_resume_target(thread_id: str) -> ResumeTarget:
+    """Look up a thread to resume and enforce the resume-age policy.
+
+    Args:
+        thread_id: The exact thread ID given to `-r`.
+
+    Returns:
+        The thread's persisted agent and directory.
+
+    Raises:
+        ResumeError: The thread is missing or blocked by policy.
+    """
+    from deepagents_code.resume_policy import resume_cutoff, thread_resume_block
+    from deepagents_code.sessions import (
+        find_similar_threads,
+        get_thread_agent,
+        get_thread_cwd,
+        thread_exists,
+    )
+
+    if not await thread_exists(thread_id):
+        similar = await find_similar_threads(thread_id)
+        msg = f"Thread '{thread_id}' not found."
+        if similar:
+            msg += f" Did you mean: {', '.join(similar)}?"
+        raise ResumeError(msg)
+    if blocked := await thread_resume_block(thread_id, resume_cutoff()):
+        raise ResumeError(blocked)
+    return ResumeTarget(
+        thread_id=thread_id,
+        agent_name=await get_thread_agent(thread_id),
+        cwd=await get_thread_cwd(thread_id),
+    )
+
+
+def cwd_conflict(target: ResumeTarget, current_cwd: str) -> str | None:
+    """Explain why `target` cannot be resumed from `current_cwd`.
+
+    The server refuses a directory change through the thread's workspace
+    binding; checking first turns that generic refusal into a specific message.
+
+    Returns:
+        A user-facing message, or `None` when the directories match.
+    """
+    from deepagents_code.resume_policy import classify_thread_cwd
+
+    if not target.cwd:
+        return None
+    status, path = classify_thread_cwd(target.cwd, current_cwd)
+    if status == "mismatch":
+        return (
+            f"Thread {target.thread_id} belongs to {path}. "
+            "Run from that directory to resume it."
+        )
+    if status == "unavailable":
+        return (
+            f"Thread {target.thread_id} was last used in {target.cwd!r}, "
+            "which is no longer available, so it can't be resumed."
+        )
+    return None
+
+
+def persisted_model(
+    values: Mapping[str, object],
+) -> tuple[str, dict[str, Any] | None] | None:
+    """Read the model a thread last ran with from its checkpoint values.
+
+    Returns:
+        The `(spec, params)` pair, or `None` when no model is recorded.
+    """
+    from deepagents_code.resume_state import coerce_model_spec
+
+    spec = coerce_model_spec(values.get("_model_spec"))
+    if spec is None:
+        return None
+    raw_params = values.get("_model_params")
+    params = (
+        dict(cast("dict[str, Any]", raw_params))
+        if isinstance(raw_params, dict)
+        else None
+    )
+    return spec, params