deepagents-code 0.1.63__tar.gz → 0.1.64__tar.gz

{deepagents_code-0.1.63 → deepagents_code-0.1.64}/AGENTS.md

@@ -139,7 +139,7 @@ Hints that tell the user to run something (for example the teardown `-r <thread>
 
 ## Splash screen tips
 
-When adding a user-facing CLI feature (new slash command, keybinding, workflow), add a corresponding entry to the `_TIPS` dict in `deepagents_code/tui/widgets/startup_tip.py`, mapping the tip text to a relative selection weight (higher = shown more often). One tip is chosen at random above the input on startup to help users discover features. Keep tips short and action-oriented (e.g., `"Press ctrl+x to compose prompts in your external editor"`).
+When adding a user-facing CLI feature (new slash command, keybinding, workflow), add a corresponding entry to the `_TIPS` dict in `deepagents_code/tui/widgets/startup_tip.py`, mapping the tip text to a relative selection weight (higher = shown more often). One tip is chosen at random above the input on startup to help users discover features. Keep tips short and action-oriented (e.g., `"Press ctrl+g to compose prompts in your external editor"`).
 
 ## Slash commands
 
@@ -170,6 +170,6 @@ To add a new slash command: (1) add a `SlashCommand` entry to `COMMANDS`, (2) se
 **Not required** unless the provider's models have a distinctive name prefix (like `gpt-*`, `claude*`, `gemini*`):
 
 - `detect_provider()` in `config.py` — only needed for auto-detection from bare model names
-- `Settings.has_*` property in `config.py` — only needed if referenced by `detect_provider()` fallback logic
+- `Credentials.has_*` property in `config.py` — only needed if referenced by `detect_provider()` fallback logic
 
 Model discovery, credential checking, and UI integration are automatic once `PROVIDER_API_KEY_ENV` is populated and the `langchain-*` package is installed.

{deepagents_code-0.1.63 → deepagents_code-0.1.64}/ARCHITECTURE.md

@@ -59,6 +59,8 @@ The main extension points are:
 - **Tools and MCP servers** for external capabilities
 - **Sandboxes** for changing where tool execution happens
 - **Hooks and commands** for integrating with local workflows
+- **Python extensions** for middleware, tools, and virtual storage routes,
+  loaded from user-authorized sources or a trusted project
 
 These pieces are designed to compose. A project can provide shared defaults and integrations, while each user can layer personal configuration on top.
 
@@ -79,6 +81,7 @@ The main cost is the client/server boundary. When debugging, first decide which
 - For local setup and debugging, see [`DEVELOPMENT.md`](./DEVELOPMENT.md).
 - For command behavior, see [`COMMANDS.md`](./COMMANDS.md).
 - For lifecycle hooks (`hooks.json`), see [`HOOKS.md`](./HOOKS.md).
+- For server-side Python extensions, see [`EXTENSIONS.md`](./EXTENSIONS.md).
 - For cost estimates and local pricing overrides (`prices.json`), see
   [`PRICING.md`](./PRICING.md).
 - For security boundaries, see [`THREAT_MODEL.md`](./THREAT_MODEL.md).

{deepagents_code-0.1.63 → deepagents_code-0.1.64}/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 # Deep Agents Code Changelog
 
+## [0.1.64](https://github.com/langchain-ai/deepagents/compare/deepagents-code==0.1.63...deepagents-code==0.1.64) (2026-08-28)
+
+### Features
+
+- Added trace metadata attribution for skill invocations ([#5925](https://github.com/langchain-ai/deepagents/issues/5925)).
+- Added a list of MCP servers that require login ([#5867](https://github.com/langchain-ai/deepagents/issues/5867)).
+- Added the ability to copy the current model from the picker header ([#5904](https://github.com/langchain-ai/deepagents/issues/5904)).
+- Linked the doctor commit hash to GitHub ([#5920](https://github.com/langchain-ai/deepagents/issues/5920)).
+- Standardized the external editor shortcut ([#5911](https://github.com/langchain-ai/deepagents/issues/5911)).
+
+### Bug Fixes
+
+- Deferred recursion-limit handling to the LangGraph server ([#5882](https://github.com/langchain-ai/deepagents/issues/5882)).
+- Disabled Git terminal prompts in `execute` ([#5878](https://github.com/langchain-ai/deepagents/issues/5878)).
+- Improved privacy and debug-only visibility for MCP token and editable paths ([#5866](https://github.com/langchain-ai/deepagents/issues/5866), [#5850](https://github.com/langchain-ai/deepagents/issues/5850)).
+- Updated the model-switch warning to point to `/offload` ([#5901](https://github.com/langchain-ai/deepagents/issues/5901)).
+- Rejected stale successful updates ([#5847](https://github.com/langchain-ai/deepagents/issues/5847)).
+- Fixed thread timestamp rendering on systems without the glibc-only `%-I` `strftime` flag ([#5886](https://github.com/langchain-ai/deepagents/issues/5886)).
+- Respected ASCII mode in the splash border ([#5923](https://github.com/langchain-ai/deepagents/issues/5923)).
+- Skipped unchanged config writes ([#5919](https://github.com/langchain-ai/deepagents/issues/5919)).
+- Skipped uncorrelated-result warnings for auto-mode policy denials ([#5869](https://github.com/langchain-ai/deepagents/issues/5869)).
+
 ## [0.1.63](https://github.com/langchain-ai/deepagents/compare/deepagents-code==0.1.62...deepagents-code==0.1.63) (2026-08-26)
 
 ### Features

{deepagents_code-0.1.63 → deepagents_code-0.1.64}/COMMANDS.md

@@ -8,7 +8,7 @@ Regenerate this file with `make commands-catalog` after changing command names,
 aliases, descriptions, visibility, or hidden-command metadata.
 
 
-## Public (42)
+## Public (43)
 
 | Command | Aliases | Description |
 | --- | --- | --- |
@@ -25,6 +25,7 @@ aliases, descriptions, visibility, or hidden-command metadata.
 | `/docs` |  | Open the docs |
 | `/editor` |  | Open prompt in an external editor ($EDITOR) |
 | `/effort` |  | Set reasoning effort for the current model |
+| `/extensions` |  | List loaded Python extensions and their provenance |
 | `/feedback` |  | Send feedback or report an issue |
 | `/force-clear` |  | Recover a stuck session with a fresh thread |
 | `/goal` |  | Set and manage a persistent objective with acceptance criteria |

deepagents_code-0.1.64/EXTENSIONS.md

@@ -0,0 +1,148 @@
+# Python extensions
+
+Python extensions customize the agent server without modifying `dcode`. They
+are experimental and load only when `DEEPAGENTS_CODE_EXPERIMENTAL=1` is set
+before starting `dcode`.
+
+An installed plugin declares one or more Python entry files in its manifest:
+
+```json
+{
+  "name": "shared-memory",
+  "version": "1.0.0",
+  "extensions": {
+    "com.langchain.deepagents.code": {
+      "pythonExtensions": "./extension.py"
+    }
+  }
+}
+```
+
+The entry file exposes an async `extension` setup function. See
+[`memory_store.py`](./examples/extensions/memory_store.py) for an example that
+registers a shared `/memories/` storage route.
+
+Install and enable the plugin through the normal plugin commands, then run
+`/restart`. Backend composition happens while the agent graph is built, so
+backend route changes cannot be applied by `/reload`. A separately managed
+remote agent server must be restarted or redeployed by its operator.
+
+The `/memories/` route makes shared storage available to model file
+operations. It does not automatically move dcode's built-in `AGENTS.md` memory.
+An extension that wants that content in the model's prompt must also register
+middleware that reads the shared location.
+
+## Supported registrations
+
+| Method | Purpose |
+| --- | --- |
+| `register_middleware(class_or_instance)` | Add LangChain `AgentMiddleware`. Classes must have a zero-argument constructor; use an instance otherwise. |
+| `register_tool(function_or_tool)` | Expose a callable or `BaseTool` to the model. |
+| `register_backend_route(prefix, storage)` | Make a `BackendProtocol` storage provider available under a virtual path. |
+| `on_shutdown(callback)` | Release session resources when the agent server stops. Sync and async callbacks are supported. |
+
+The factory must be declared with `async def`; dcode awaits every factory before
+building the agent. The registrar remains valid for callbacks that outlive the
+factory. Runtime tools appear on the next model request, backend routes update
+the registry but require `/restart`, and middleware also takes effect after the
+next server rebuild. `/extensions` reports when a restart is required.
+
+Do not open long-lived connections or start background tasks during module
+import. A storage provider may connect lazily on first use. If setup opens a
+session resource, register an idempotent `on_shutdown` callback to release it.
+
+The API exposes read-only session context (`d.cwd`, `d.mode`, `d.has_ui`, and
+`d.path`), not mutable TUI or thread state. Custom slash commands are not part
+of this API. Run `/extensions` to inspect registered units and their source.
+
+## Storage routes
+
+`BackendProtocol` is the SDK name for a storage implementation. Route prefixes
+are lowercase absolute paths with leading and trailing slashes, such as
+`/memories/` or `/company/knowledge/`. Traversal, empty segments, backslashes,
+URL query or fragment syntax, and overlaps with dcode's internal routes are
+rejected.
+
+Routed content is available through the model's file tools. Shell `execute`
+remains attached to the default local or sandbox storage, so shell commands
+cannot see virtual routed content.
+
+Local agents may mount `FilesystemBackend` and `LocalShellBackend`. Sandboxed
+agents reject direct instances of either class, including subclasses, because
+they would expose host storage while `execute` still runs inside the sandbox.
+Other `BackendProtocol` implementations such as `StateBackend`, `StoreBackend`,
+and `ContextHubBackend` are supported. This check is intentionally shallow:
+dcode does not recursively inspect custom or composite backend wrappers, whose
+authors own their isolation contract.
+
+The first extension registration of a route prefix or unit name wins. Extension
+tools and middleware replace same-named built-ins. A route that is a parent or
+child of dcode's artifact or conversation-history storage fails agent
+construction or runtime registration immediately; internal routes cannot be
+replaced.
+
+## Packaging, discovery, and trust
+
+For quick user-wide extensions, place Python files in
+`~/.deepagents/extensions/`. Installed plugins remain the preferred
+distribution mechanism: they provide stable identity, versions, updates, and a
+durable data directory. Dcode resolves plugin manifest entries inside the
+installed snapshot and rejects traversal, absolute paths, symlink escapes,
+missing files, and non-Python files. Entries without a plugin version are
+ignored. Installed Python distributions may also expose module entry points in
+the `dcode.extensions` group.
+
+Sources load in this order:
+
+| Source | Version and trust behavior |
+| --- | --- |
+| `~/.deepagents/extensions/` | User-owned loose files; implicitly authorized. |
+| `[extensions].extra_files` and `extra_dirs` | Explicit paths in trusted user configuration. |
+| `-e/--extension PATH` | Temporary file or directory authorized for one run. |
+| Enabled installed plugins | Identified by `name@marketplace`, loaded from the versioned plugin cache. Installing and enabling the plugin authorizes its code. |
+| `dcode.extensions` entry points | Modules from installed Python distributions. |
+| `.deepagents/extensions/` | Project-controlled and normally versioned with the project; never scanned before project trust. |
+
+The project directory is the local development escape hatch. Its scan is
+shallow: direct `*.py` files are extensions, and a direct subdirectory is a
+package extension when it contains `__init__.py` or `extension.py`.
+
+Project extensions execute arbitrary Python with the user's process privileges.
+Interactive launches ask before loading them and can remember the canonical
+project path. Headless or CI launches can opt in for one run with
+`--trust-project-extensions`. Only trust projects you control.
+
+## Configuration
+
+```toml
+# ~/.deepagents/config.toml
+[extensions]
+enabled = true
+trust = "ask"  # ask | always | never
+extra_files = ["~/src/policy.py"]
+extra_dirs = ["~/src/company-extensions"]
+```
+
+Environment overrides:
+
+- `DEEPAGENTS_CODE_EXTENSIONS` enables or disables all extension loading.
+- `DEEPAGENTS_CODE_EXTENSIONS_TRUST` overrides the project trust policy.
+
+Relative extra paths resolve from `~/.deepagents/`. Repeat `-e PATH` to add
+multiple temporary sources for one invocation.
+
+## Failure and security behavior
+
+Each setup function is transactional. If import or initialization fails, all of
+that extension's partial registrations are removed and later extensions still
+load. Failures are written to the debug log.
+
+Extension tools override same-named built-ins and are not automatically added to
+dcode's human-approval map. An extension that performs sensitive work must
+enforce its own approval or policy through middleware.
+
+Every registration retains its plugin ID, version, installed root, and source
+scope. This attribution tells dcode which extension added a storage route; it
+does not prove that an arbitrary storage implementation is safe. A provider can
+access the network or host files, so install plugins only from trusted sources
+and choose shared namespaces that preserve tenant and user isolation.

{deepagents_code-0.1.63 → deepagents_code-0.1.64}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: deepagents-code
-Version: 0.1.63
+Version: 0.1.64
 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,20 +30,20 @@ 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.9
+Requires-Dist: deepagents==0.7.10
 Requires-Dist: filelock<3.30,>=3.29.7
 Requires-Dist: genai-prices<0.2.0,>=0.1.4
 Requires-Dist: httpx<1.0.0,>=0.28.1
-Requires-Dist: langchain-anthropic<2.0.0,>=1.6.1
-Requires-Dist: langchain-google-genai<5.0.0,>=4.3.5
+Requires-Dist: langchain-anthropic<2.0.0,>=1.7.0
+Requires-Dist: langchain-google-genai<5.0.0,>=4.3.7
 Requires-Dist: langchain-mcp-adapters<1.0.0,>=0.3.2
 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.17
+Requires-Dist: langchain<2.0.0,>=1.3.18
 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.33.0
-Requires-Dist: langgraph-sdk<1.0.0,>=0.4.3
+Requires-Dist: langgraph-sdk<1.0.0,>=0.4.4
 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
@@ -66,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.6.1; extra == 'all-providers'
-Requires-Dist: langchain-aws<2.0.0,>=1.7.3; extra == 'all-providers'
-Requires-Dist: langchain-baseten<1.0.0,>=0.2.3; extra == 'all-providers'
+Requires-Dist: langchain-anthropic<2.0.0,>=1.7.0; extra == 'all-providers'
+Requires-Dist: langchain-aws<2.0.0,>=1.7.4; extra == 'all-providers'
+Requires-Dist: langchain-baseten<1.0.0,>=0.2.4; 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.6.0; extra == 'all-providers'
-Requires-Dist: langchain-google-genai<5.0.0,>=4.3.5; extra == 'all-providers'
+Requires-Dist: langchain-fireworks<2.0.0,>=1.6.1; extra == 'all-providers'
+Requires-Dist: langchain-google-genai<5.0.0,>=4.3.7; 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'
@@ -94,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.6.1; extra == 'anthropic'
+Requires-Dist: langchain-anthropic<2.0.0,>=1.7.0; extra == 'anthropic'
 Provides-Extra: baseten
-Requires-Dist: langchain-baseten<1.0.0,>=0.2.3; extra == 'baseten'
+Requires-Dist: langchain-baseten<1.0.0,>=0.2.4; extra == 'baseten'
 Provides-Extra: bedrock
-Requires-Dist: langchain-aws<2.0.0,>=1.7.3; extra == 'bedrock'
+Requires-Dist: langchain-aws<2.0.0,>=1.7.4; extra == 'bedrock'
 Provides-Extra: cohere
 Requires-Dist: langchain-cohere<1.0.0,>=0.6.0; extra == 'cohere'
 Provides-Extra: daytona
@@ -106,9 +106,9 @@ Requires-Dist: langchain-daytona>=0.0.7; extra == 'daytona'
 Provides-Extra: deepseek
 Requires-Dist: langchain-deepseek<2.0.0,>=1.1.0; extra == 'deepseek'
 Provides-Extra: fireworks
-Requires-Dist: langchain-fireworks<2.0.0,>=1.6.0; extra == 'fireworks'
+Requires-Dist: langchain-fireworks<2.0.0,>=1.6.1; extra == 'fireworks'
 Provides-Extra: google-genai
-Requires-Dist: langchain-google-genai<5.0.0,>=4.3.5; extra == 'google-genai'
+Requires-Dist: langchain-google-genai<5.0.0,>=4.3.7; extra == 'google-genai'
 Provides-Extra: groq
 Requires-Dist: langchain-groq<2.0.0,>=1.1.3; extra == 'groq'
 Provides-Extra: huggingface

{deepagents_code-0.1.63 → deepagents_code-0.1.64}/THREAT_MODEL.md

@@ -28,6 +28,7 @@
 - Custom subagent loader (`subagents.py`, `agent.py:load_async_subagents`)
 - Conversation offload (`offload.py`)
 - Skill management (`skills/commands.py`)
+- Python extension loading (`extensions/`)
 - Persisted goal/rubric state notices (`goal_state_notice.py`, `goal_tools.py`,
   `goal_state_limits.py`)
 
@@ -55,6 +56,8 @@
 7. `DA_SERVER_*` environment variables are readable only by the CLI process and its child server subprocess (OS process isolation assumption).
 8. Users who set `class_path` in `config.toml` accept the same trust model as `pyproject.toml` build scripts — they control their own machine.
 9. Administrators deploy and protect the fixed `managed_config.toml` path with operating-system controls; the CLI does not validate its owner or mode and never writes it.
+10. User-directory, user-config, CLI, installed-plugin, and Python entry-point extensions are authorized by the user action that supplied them. Project extensions execute only after explicit, configured, or persisted trust.
+11. Extension backend routes cannot overlap dcode's local artifact or conversation-history storage. A sandboxed agent rejects direct `FilesystemBackend` and `LocalShellBackend` mounts, including subclasses; wrapper implementations are responsible for their own isolation because dcode does not recursively inspect arbitrary backend object graphs.
 
 ---
 
@@ -140,7 +143,7 @@
 | C6  | Hook Runtime                | Fires subprocess commands on agent lifecycle events                                                                 | framework-controlled | No³      | `hooks.runtime.HooksRuntime`, `hooks.runner.run_command_handler`                                  |
 | C7  | Sandbox Integration         | Creates/destroys remote sandboxes (Daytona, LangSmith, Modal, Runloop, AgentCore)                                  | framework-controlled | No⁴      | `integrations.sandbox_factory.create_sandbox`                                                     |
 | C8  | Session Persistence         | SQLite checkpoint store for LangGraph thread state                                                                  | framework-controlled | Yes      | `sessions.get_db_path`, `sessions.generate_thread_id`                                             |
-| C9  | Configuration System        | Managed/user TOML, env vars, `AGENTS.md` system prompts, model config                                               | administrator/user-controlled | N/A | `configuration`, `config.settings`, `model_config.ModelConfig`, fixed managed path, `~/.deepagents/config.toml` |
+| C9  | Configuration System        | Managed/user TOML, env vars, `AGENTS.md` system prompts, model config                                               | administrator/user-controlled | N/A | `configuration`, `config.Credentials`, `config.RuntimeState`, `_paths.PATHS`, `model_config.ModelConfig`, fixed managed path, `~/.deepagents/config.toml` |
 | C10 | Unicode/URL Safety          | Detects hidden Unicode, checks URL domain spoofing for approval UI warnings                                         | framework-controlled | Yes      | `unicode_security.detect_dangerous_unicode`, `unicode_security.check_url_safety`                  |
 | C11 | LangGraph Dev Server        | Subprocess running `langgraph dev` with `LANGGRAPH_AUTH_TYPE=noop`; managed by `ServerProcess`                      | framework-controlled | Yes⁵     | `client.launch.server.ServerProcess.start`, `client.launch.server.generate_langgraph_json`, `client.launch.server_manager.start_server_and_get_agent` |
 | C12 | Remote Agent Client         | HTTP+SSE client wrapping `RemoteGraph`; connects to C11 on localhost                                                | framework-controlled | Yes⁵     | `client.remote_client.RemoteAgent.astream`, `client.remote_client.RemoteAgent.aget_state`         |

{deepagents_code-0.1.63 → deepagents_code-0.1.64}/deepagents_code/_build_info.py

@@ -1,3 +1,3 @@
 """Generated at build time. Do not edit or commit."""
 
-BUILD_COMMIT = "970003e"
+BUILD_COMMIT = "d8686f7"

{deepagents_code-0.1.63 → deepagents_code-0.1.64}/deepagents_code/_env_vars.py

@@ -256,6 +256,12 @@ values). Marks experimental runs in UI/trace metadata. Behavior behind this
 flag may change or be removed without notice.
 """
 
+EXTENSIONS = "DEEPAGENTS_CODE_EXTENSIONS"
+"""Enable loading installed-plugin and trusted-project Python extensions."""
+
+EXTENSIONS_TRUST = "DEEPAGENTS_CODE_EXTENSIONS_TRUST"
+"""Default project extension trust policy: `ask`, `always`, or `never`."""
+
 EXTERNAL_EVENT_SOCKET = "DEEPAGENTS_CODE_EXTERNAL_EVENT_SOCKET"
 """Enable the local Unix-socket external event listener.
 
@@ -487,10 +493,9 @@ repo file, so a project `.env` cannot disable itself.
 RECURSION_LIMIT = "DEEPAGENTS_CODE_RECURSION_LIMIT"
 """Override the main agent's LangGraph `recursion_limit` (graph step budget).
 
-Parsed as an integer by the config manifest. Values below the LangGraph floor
-(`25`) or above the manifest ceiling are ignored with a logged warning, falling
-back to `config.toml` then the default. See `[runtime].recursion_limit` and the
-`--recursion-limit` CLI flag.
+Parsed as an integer by the config manifest. Values outside the accepted range
+are ignored with a logged warning, falling back to `config.toml`. See
+`[runtime].recursion_limit` and the `--recursion-limit` CLI flag.
 """
 
 RESTARTED_AFTER_UPDATE = "DEEPAGENTS_CODE_RESTARTED_AFTER_UPDATE"

{deepagents_code-0.1.63 → deepagents_code-0.1.64}/deepagents_code/_paths.py

@@ -21,6 +21,7 @@ from __future__ import annotations
 import errno
 import logging
 import os
+import re
 import sys
 import tempfile
 from dataclasses import dataclass
@@ -49,12 +50,29 @@ __all__ = [
     "ProfilePaths",
     "ProjectPaths",
     "classify_path",
+    "ensure_agent_dir",
+    "ensure_project_skills_dir",
+    "ensure_user_skills_dir",
     "export_profile_env",
     "first_writable",
+    "get_agent_dir",
+    "get_built_in_skills_dir",
     "get_deepagents_home",
+    "get_project_agent_md_path",
+    "get_project_agent_skills_dir",
+    "get_project_agents_dir",
+    "get_project_claude_skills_dir",
+    "get_project_skills_dir",
+    "get_user_agent_md_path",
+    "get_user_agent_skills_dir",
+    "get_user_agents_dir",
+    "get_user_claude_skills_dir",
+    "get_user_skills_dir",
     "harden_state_dir",
     "probe_writable",
     "project_paths",
+    "user_agents_dir",
+    "user_deepagents_dir",
 ]
 
 DEEPAGENTS_HOME_ENV = "DEEPAGENTS_HOME"
@@ -221,6 +239,149 @@ def project_paths(root: Path) -> ProjectPaths:
     )
 
 
+def user_deepagents_dir() -> Path:
+    """Return the immutable launch-time user profile root."""
+    return PATHS.profile.root
+
+
+def _validate_agent_name(agent_name: str) -> None:
+    """Raise when an agent name cannot safely identify a profile directory.
+
+    Raises:
+        ValueError: If the name is empty, unsafe, or reserved by dcode.
+    """
+    if (
+        not agent_name
+        or not agent_name.strip()
+        or not re.fullmatch(r"[a-zA-Z0-9_\-\s]+", agent_name)
+    ):
+        msg = (
+            f"Invalid agent name: {agent_name!r}. Agent names can only "
+            "contain letters, numbers, hyphens, underscores, and spaces."
+        )
+        raise ValueError(msg)
+    from deepagents_code._reserved_names import is_reserved_agent_dir_name
+
+    if is_reserved_agent_dir_name(agent_name):
+        msg = f"Invalid agent name: {agent_name!r} is reserved for dcode's own state."
+        raise ValueError(msg)
+
+
+def get_agent_dir(agent_name: str) -> Path:
+    """Return the validated profile directory for an agent name.
+
+    Args:
+        agent_name: Agent profile name.
+
+    Returns:
+        Path to the agent's profile directory.
+
+    """
+    _validate_agent_name(agent_name)
+    return PATHS.profile.agent_dir(agent_name)
+
+
+def ensure_agent_dir(agent_name: str) -> Path:
+    """Create the validated profile directory for an agent.
+
+    Returns:
+        Path to the agent's profile directory.
+    """
+    agent_dir = get_agent_dir(agent_name)
+    agent_dir.mkdir(parents=True, exist_ok=True)
+    return agent_dir
+
+
+def get_user_agent_md_path(agent_name: str) -> Path:
+    """Return the user-level `AGENTS.md` path for an agent profile."""
+    return get_agent_dir(agent_name) / "AGENTS.md"
+
+
+def get_project_agent_md_path(project_root: Path | None) -> list[Path]:
+    """Return existing project-level `AGENTS.md` paths."""
+    if project_root is None:
+        return []
+    from deepagents_code.project_utils import find_project_agent_md
+
+    return find_project_agent_md(project_root)
+
+
+def get_user_skills_dir(agent_name: str) -> Path:
+    """Return the user-level skills directory for an agent profile."""
+    return get_agent_dir(agent_name) / "skills"
+
+
+def ensure_user_skills_dir(agent_name: str) -> Path:
+    """Create the user-level skills directory for an agent.
+
+    Returns:
+        Path to the agent's user-level skills directory.
+    """
+    skills_dir = get_user_skills_dir(agent_name)
+    skills_dir.mkdir(parents=True, exist_ok=True)
+    return skills_dir
+
+
+def get_project_skills_dir(project_root: Path | None) -> Path | None:
+    """Return the project-level dcode skills directory, when in a project."""
+    return None if project_root is None else project_paths(project_root).skills_dir
+
+
+def ensure_project_skills_dir(project_root: Path | None) -> Path | None:
+    """Create the project-level dcode skills directory.
+
+    Returns:
+        Path to the project skills directory, or `None` outside a project.
+    """
+    skills_dir = get_project_skills_dir(project_root)
+    if skills_dir is not None:
+        skills_dir.mkdir(parents=True, exist_ok=True)
+    return skills_dir
+
+
+def get_user_agents_dir(agent_name: str) -> Path:
+    """Return the custom-subagent directory for an agent profile."""
+    return get_agent_dir(agent_name) / "agents"
+
+
+def get_project_agents_dir(project_root: Path | None) -> Path | None:
+    """Return the project-level custom-subagent directory, when available."""
+    return None if project_root is None else project_paths(project_root).agents_dir
+
+
+def user_agents_dir() -> Path | None:
+    """Return the launch user's tool-agnostic `~/.agents` directory."""
+    return None if PATHS.launch_home is None else PATHS.launch_home / ".agents"
+
+
+def get_user_agent_skills_dir() -> Path | None:
+    """Return the launch user's tool-agnostic `~/.agents/skills` directory."""
+    base = user_agents_dir()
+    return None if base is None else base / "skills"
+
+
+def get_project_agent_skills_dir(project_root: Path | None) -> Path | None:
+    """Return the project-level tool-agnostic `.agents/skills` directory."""
+    return None if project_root is None else project_root / ".agents" / "skills"
+
+
+def get_user_claude_skills_dir() -> Path | None:
+    """Return the launch user's experimental `~/.claude/skills` directory."""
+    if PATHS.launch_home is None:
+        return None
+    return PATHS.launch_home / ".claude" / "skills"
+
+
+def get_project_claude_skills_dir(project_root: Path | None) -> Path | None:
+    """Return the project's experimental `.claude/skills` directory."""
+    return None if project_root is None else project_root / ".claude" / "skills"
+
+
+def get_built_in_skills_dir() -> Path:
+    """Return the directory containing skills bundled with dcode."""
+    return Path(__file__).parent / "built_in_skills"
+
+
 class PathState(StrEnum):
     """Whether a probed path exists, is absent, or could not be read.
 

{deepagents_code-0.1.63 → deepagents_code-0.1.64}/deepagents_code/_reserved_names.py

@@ -4,7 +4,7 @@ Agent profiles are siblings of the app's own directories under the profile
 root, so an agent named after one of them would resolve onto app state. Both
 the picker and the write path need that list.
 
-This module is imported on the CLI startup path (`config.get_agent_dir` and
+This module is imported on the CLI startup path (`_paths.get_agent_dir` and
 `main`) and by the agent picker. Keep its module level free of heavy imports.
 The constants are read inside the function, so importing this module never
 pulls in `deepagents` or LangChain. The function itself must stay light too,