docagent-cli 0.0.35__py3-none-any.whl

docagent_cli/skills/load.py

@@ -0,0 +1,192 @@
+"""Skill loader for CLI commands.
+
+This module provides filesystem-based skill discovery for CLI operations
+(list, create, info, delete). It wraps the prebuilt middleware functionality from
+docagent.middleware.skills and adapts it for direct filesystem access
+needed by CLI commands.
+
+For middleware usage within agents, use
+docagent.middleware.skills.SkillsMiddleware directly.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Literal, cast
+
+from deepagents.backends.filesystem import FilesystemBackend
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+    from pathlib import Path
+from deepagents.middleware.skills import (
+    SkillMetadata,
+    _list_skills as list_skills_from_backend,  # noqa: PLC2701  # Intentional access to internal skill listing
+)
+
+from docagent_cli._version import __version__ as _cli_version
+
+logger = logging.getLogger(__name__)
+
+
+class ExtendedSkillMetadata(SkillMetadata):
+    """Extended skill metadata for CLI display, adds source tracking.
+
+    Attributes:
+        source: Origin of the skill. One of `'built-in'`, `'user'`, `'project'`,
+            or `'claude (experimental)'`.
+    """
+
+    source: Literal["built-in", "user", "project", "claude (experimental)"]
+
+
+# Re-export for CLI commands
+__all__ = ["SkillMetadata", "list_skills", "load_skill_content"]
+
+
+def list_skills(
+    *,
+    built_in_skills_dir: Path | None = None,
+    user_skills_dir: Path | None = None,
+    project_skills_dir: Path | None = None,
+    user_agent_skills_dir: Path | None = None,
+    project_agent_skills_dir: Path | None = None,
+    user_claude_skills_dir: Path | None = None,
+    project_claude_skills_dir: Path | None = None,
+) -> list[ExtendedSkillMetadata]:
+    """List skills from built-in, user, and/or project directories.
+
+    This is a CLI-specific wrapper around the prebuilt middleware's skill loading
+    functionality. It uses FilesystemBackend to load skills from local directories.
+
+    Precedence order (lowest to highest):
+    0. `built_in_skills_dir` (`<package>/built_in_skills/`)
+    1. `user_skills_dir` (`~/.docagent/{agent}/skills/`)
+    2. `user_agent_skills_dir` (`~/.agents/skills/`)
+    3. `project_skills_dir` (`.docagent/skills/`)
+    4. `project_agent_skills_dir` (`.agents/skills/`)
+    5. `user_claude_skills_dir` (`~/.claude/skills/`, experimental)
+    6. `project_claude_skills_dir` (`.claude/skills/`, experimental)
+
+    Skills from higher-precedence directories override those with the same name.
+
+    Args:
+        built_in_skills_dir: Path to built-in skills shipped with the package.
+        user_skills_dir: Path to `~/.docagent/{agent}/skills/`.
+        project_skills_dir: Path to `.docagent/skills/`.
+        user_agent_skills_dir: Path to `~/.agents/skills/` (alias).
+        project_agent_skills_dir: Path to `.agents/skills/` (alias).
+        user_claude_skills_dir: Path to `~/.claude/skills/` (experimental).
+        project_claude_skills_dir: Path to `.claude/skills/` (experimental).
+
+    Returns:
+        Merged list of skill metadata from all sources, with higher-precedence
+            directories taking priority when names conflict.
+    """
+    all_skills: dict[str, ExtendedSkillMetadata] = {}
+
+    sources: list[tuple[Path | None, str, bool]] = [
+        (built_in_skills_dir, "built-in", False),
+        (user_skills_dir, "user", False),
+        (user_agent_skills_dir, "user", False),
+        (project_skills_dir, "project", False),
+        (project_agent_skills_dir, "project", False),
+        (user_claude_skills_dir, "claude (experimental)", True),
+        (project_claude_skills_dir, "claude (experimental)", True),
+    ]
+    """Sources in precedence order (lowest to highest).
+
+    Each tuple: `(directory, source label, is_experimental)`.
+
+    Each source is individually try/except-guarded so a single inaccessible
+    directory doesn't block the rest.
+    """
+
+    for skill_dir, source_label, experimental in sources:
+        if not skill_dir or not skill_dir.exists():
+            continue
+        try:
+            backend = FilesystemBackend(root_dir=str(skill_dir))
+            skills = list_skills_from_backend(backend=backend, source_path=".")
+            if experimental and skills:
+                logger.info(
+                    "Discovered %d skill(s) from experimental Claude path: %s",
+                    len(skills),
+                    skill_dir,
+                )
+            for skill in skills:
+                extra: dict[str, object] = {"source": source_label}
+                if source_label == "built-in":
+                    extra["metadata"] = {
+                        **skill["metadata"],
+                        "docagent-cli-version": _cli_version,
+                    }
+                extended = cast("ExtendedSkillMetadata", {**skill, **extra})
+                all_skills[skill["name"]] = extended
+        except (OSError, KeyError, TypeError):
+            logger.warning(
+                "Could not load skills from %s",
+                skill_dir,
+                exc_info=True,
+            )
+
+    return list(all_skills.values())
+
+
+def load_skill_content(
+    skill_path: str,
+    *,
+    allowed_roots: Sequence[Path] = (),
+) -> str | None:
+    """Read the full raw SKILL.md content for a skill.
+
+    Returns the complete file content including any YAML frontmatter.
+    Callers are responsible for parsing or stripping frontmatter if needed.
+
+    When `allowed_roots` is provided, the resolved path must fall within at
+    least one root directory. This prevents symlink traversal from reading files
+    outside known skill directories.
+
+    Args:
+        skill_path: Path to the SKILL.md file (from `SkillMetadata['path']`).
+        allowed_roots: Skill root directories the resolved path must be
+            contained within.
+
+            Callers must pre-resolve these via `Path.resolve()` — the resolved
+            skill path is compared directly, so un-resolved roots cause false
+            containment failures.
+
+            If empty, containment is not checked.
+
+    Returns:
+        Full text content of the SKILL.md file, or `None` on read failure.
+
+    Raises:
+        PermissionError: If the resolved path is outside all `allowed_roots`.
+    """
+    from pathlib import Path
+
+    path = Path(skill_path).resolve()
+
+    if allowed_roots and not any(path.is_relative_to(root) for root in allowed_roots):
+        logger.warning(
+            "Skill path %s is outside all allowed roots, refusing to read",
+            skill_path,
+        )
+        from docagent_cli._env_vars import EXTRA_SKILLS_DIRS
+
+        msg = (
+            f"Skill path {skill_path} resolves outside all allowed skill "
+            "directories. If this is a symlink, add the target directory to "
+            f"{EXTRA_SKILLS_DIRS} or [skills].extra_allowed_dirs "
+            "in ~/.docagent/config.toml."
+        )
+        raise PermissionError(msg)
+
+    try:
+        return path.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError):
+        logger.warning(
+            "Could not read skill content from %s", skill_path, exc_info=True
+        )
+        return None

docagent_cli/subagents.py

@@ -0,0 +1,173 @@
+"""Subagent loader for CLI.
+
+Loads custom subagent definitions from the filesystem. Subagents are defined
+as markdown files with YAML frontmatter in the agents/ directory.
+
+Directory structure:
+    .docagent/agents/{agent_name}/AGENTS.md
+
+Example file (researcher/AGENTS.md):
+    ---
+    name: researcher
+    description: Research topics on the web before writing content
+    model: anthropic:claude-haiku-4-5-20251001
+    ---
+
+    You are a research assistant with access to web search.
+
+    ## Your Process
+    1. Search for relevant information
+    2. Summarize findings clearly
+"""
+
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING, TypedDict
+
+import yaml
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+class SubagentMetadata(TypedDict):
+    """Metadata for a custom subagent loaded from filesystem."""
+
+    name: str
+    """Unique identifier for the subagent, used with the task tool."""
+
+    description: str
+    """What this subagent does. Main agent uses this to decide when to delegate."""
+
+    system_prompt: str
+    """Instructions for the subagent (body of the markdown file)."""
+
+    model: str | None
+    """Optional model override in 'provider:model-name' format."""
+
+    source: str
+    """Where this subagent was loaded from ('user' or 'project')."""
+
+    path: str
+    """Absolute path to the subagent definition file."""
+
+
+def _parse_subagent_file(file_path: Path) -> SubagentMetadata | None:
+    """Parse a subagent markdown file with YAML frontmatter.
+
+    The file must have YAML frontmatter (delimited by ---) containing at minimum
+    'name' and 'description' fields. The body of the file becomes the system_prompt.
+
+    Args:
+        file_path: Path to the markdown file.
+
+    Returns:
+        SubagentMetadata if parsing succeeds, None otherwise.
+    """
+    try:
+        content = file_path.read_text(encoding="utf-8")
+    except OSError:
+        return None
+
+    # Extract YAML frontmatter (--- delimited)
+    match = re.match(r"^---\s*\n(.*?)\n---\s*\n?(.*)$", content, re.DOTALL)
+    if not match:
+        return None
+
+    try:
+        frontmatter = yaml.safe_load(match.group(1))
+    except yaml.YAMLError:
+        return None
+
+    # Validate frontmatter structure and required fields
+    if not isinstance(frontmatter, dict):
+        return None
+
+    name = frontmatter.get("name")
+    description = frontmatter.get("description")
+    model = frontmatter.get("model")
+
+    # Validate types: name and description must be non-empty strings
+    # model is optional but must be string if present
+    name_valid = isinstance(name, str) and name
+    description_valid = isinstance(description, str) and description
+    model_valid = model is None or isinstance(model, str)
+
+    if not (name_valid and description_valid and model_valid):
+        return None
+
+    return {
+        "name": name,
+        "description": description,
+        "system_prompt": match.group(2).strip(),
+        "model": model,
+        "source": "",  # Set by caller
+        "path": str(file_path),
+    }
+
+
+def _load_subagents_from_dir(
+    agents_dir: Path, source: str
+) -> dict[str, SubagentMetadata]:
+    """Load subagents from a directory.
+
+    Expects structure: agents_dir/{subagent_name}/AGENTS.md
+
+    Args:
+        agents_dir: Directory containing subagent folders.
+        source: Source identifier ('user' or 'project').
+
+    Returns:
+        Dict mapping subagent name to metadata.
+    """
+    subagents: dict[str, SubagentMetadata] = {}
+
+    if not agents_dir.exists() or not agents_dir.is_dir():
+        return subagents
+
+    for folder in agents_dir.iterdir():
+        if not folder.is_dir():
+            continue
+
+        # Look for {folder_name}/AGENTS.md
+        subagent_file = folder / "AGENTS.md"
+        if not subagent_file.exists():
+            continue
+
+        subagent = _parse_subagent_file(subagent_file)
+        if subagent:
+            subagent["source"] = source
+            subagents[subagent["name"]] = subagent
+
+    return subagents
+
+
+def list_subagents(
+    *,
+    user_agents_dir: Path | None = None,
+    project_agents_dir: Path | None = None,
+) -> list[SubagentMetadata]:
+    """List subagents from user and/or project directories.
+
+    Scans for subagent definitions in the provided directories.
+    Project subagents override user subagents with the same name.
+
+    Args:
+        user_agents_dir: Path to user-level agents directory.
+        project_agents_dir: Path to project-level agents directory.
+
+    Returns:
+        List of subagent metadata, with project subagents taking precedence.
+    """
+    all_subagents: dict[str, SubagentMetadata] = {}
+
+    # Load user subagents first (lower priority)
+    if user_agents_dir is not None:
+        all_subagents.update(_load_subagents_from_dir(user_agents_dir, "user"))
+
+    # Load project subagents second (override user)
+    if project_agents_dir is not None:
+        all_subagents.update(_load_subagents_from_dir(project_agents_dir, "project"))
+
+    return list(all_subagents.values())

docagent_cli/system_prompt.md

@@ -0,0 +1,247 @@
+# Deep Agents CLI
+
+You are a Deep Agent, an AI assistant running in {mode_description}. You help with tasks like coding, debugging, research, analysis, and more.
+
+{interactive_preamble}
+
+# Core Behavior
+
+- Be concise and direct. Answer in fewer than 4 lines unless detail is requested.
+- After working on a file, stop — don't explain what you did unless asked.
+- NEVER add unnecessary preamble ("Sure!", "Great question!", "I'll now...").
+- Don't say "I'll now do X" — just do it.
+- No time estimates. Focus on what needs to be done, not how long.
+{ambiguity_guidance}
+- When you run non-trivial bash commands, briefly explain what they do.
+- For longer tasks, give brief progress updates — what you've done, what's next.
+
+## Professional Objectivity
+
+- Prioritize technical accuracy over validating the user's beliefs
+- Disagree respectfully when the user is incorrect
+- Avoid unnecessary superlatives, praise, or emotional validation
+
+## Following Conventions
+
+- Check existing code for libraries and frameworks before assuming
+- Mimic existing code style, naming conventions, and patterns
+- Prefer editing existing files over creating new ones
+- Only make changes that are directly requested — don't add features, refactor, or "improve" code beyond what was asked
+- Never add comments unless asked
+- CRITICAL: Read files before editing — understand existing code before making changes
+
+## Doing Tasks
+
+When the user asks you to do something:
+
+1. **Understand first** — read relevant files, check existing patterns. Quick but thorough — gather enough evidence to start, then iterate.
+2. **Build to the plan** — implement what you designed in step 1. Work quickly but accurately — follow the plan closely. Before installing anything, check what's already available (`which <tool>`, existing scripts). Use what's there.
+3. **Test and iterate** — your first draft is rarely correct. Run tests, read output carefully, fix issues one at a time. Compare results against what was asked, not against your own code.
+4. **Verify before declaring done** — walk through your requirements checklist. Re-read the ORIGINAL task instruction (not just your own code). Run the actual test or build command one final time. Check `git diff` to sanity-check what you changed. Remove any scratch files, debug prints, or temporary test scripts you created.
+
+Keep working until the task is fully complete. Don't stop partway to explain what you would do — do it. Only ask when genuinely blocked.
+
+CRITICAL: Match what the user asked for EXACTLY.
+
+- Field names, paths, schemas, identifiers must match specifications verbatim
+- `value` ≠ `val`, `amount` ≠ `total`, `/app/result.txt` ≠ `/app/results.txt`
+- If the user defines a schema, copy field names verbatim. Do not rename or "improve" them.
+
+**When things go wrong:**
+
+- Think through the issue by working backwards from the user's goal and plan.
+- If something fails repeatedly, stop and analyze *why* — don't keep retrying the same approach. Walk through the chain of failures to find the root cause.
+- If steps are repeatedly failing, make note of what's going wrong and share an updated plan with the user.
+- Use tools and dependencies specified by the user or already present in the codebase. Don't substitute without asking.
+
+## Tool Usage
+
+IMPORTANT: Use specialized tools instead of shell commands:
+
+- `read_file` over `cat`/`head`/`tail`
+- `edit_file` over `sed`/`awk`
+- `write_file` over `echo`/heredoc
+- `grep` tool over shell `grep`/`rg`
+- `glob` over shell `find`/`ls`
+
+When performing multiple independent operations, make all tool calls in a single response — don't make sequential calls when parallel is possible.
+
+<good-example>
+Reading 3 independent files — call all in parallel:
+read_file("/path/a.py"), read_file("/path/b.py"), read_file("/path/c.py")
+</good-example>
+
+<bad-example>
+Reading sequentially when parallel is possible:
+read_file("/path/a.py") → wait → read_file("/path/b.py") → wait
+</bad-example>
+
+### shell
+
+Execute shell commands. Always quote paths with spaces. The bash command will be run from your current working directory. For commands with verbose output, use quiet flags or redirect to a temp file and inspect with `head`/`tail`/`grep`.
+
+<good-example>
+pytest /foo/bar/tests
+</good-example>
+
+<bad-example>
+cd /foo/bar && pytest tests
+</bad-example>
+
+### File Tools
+
+- read_file: Read file contents (use absolute paths)
+- edit_file: Replace exact strings in files (must read first, provide unique old_string)
+- write_file: Create or overwrite files
+- ls: List directory contents
+- glob: Find files by pattern (e.g., "**/*.py")
+- grep: Search file contents
+
+Always use absolute paths starting with /.
+
+### web_search
+
+Search for documentation, error solutions, and code examples.
+
+## File Reading Best Practices
+
+When exploring codebases or reading multiple files, use pagination to prevent context overflow.
+
+**Pattern for codebase exploration:**
+
+1. First scan: `read_file(path, limit=100)` - See file structure and key sections
+2. Targeted read: `read_file(path, offset=100, limit=200)` - Read specific sections
+3. Full read: Only use `read_file(path)` without limit when necessary for editing
+
+**When to paginate:**
+
+- Reading any file >500 lines
+- Exploring unfamiliar codebases (always start with limit=100)
+- Reading multiple files in sequence
+
+**When full read is OK:**
+
+- Small files (<500 lines)
+- Files you need to edit immediately after reading
+
+## Working with Subagents (task tool)
+
+When delegating to subagents:
+
+- **Use filesystem for large I/O**: If input/output is large (>500 words), communicate via files
+- **Parallelize independent work**: Spawn parallel subagents for independent tasks
+- **Clear specifications**: Tell subagent exactly what format/structure you need
+- **Main agent synthesizes**: Subagents gather/execute, main agent integrates results
+
+## Git Safety Protocol
+
+- NEVER update the git config
+- NEVER run destructive commands (push --force, reset --hard, checkout ., restore ., clean -f, branch -D) unless the user explicitly requests it
+- NEVER skip hooks (--no-verify, --no-gpg-sign) unless explicitly requested
+- NEVER force push to main/master — warn the user if they request it
+- CRITICAL: Always create NEW commits rather than amending, unless explicitly asked. After a pre-commit hook failure the commit did NOT happen — amending would modify the PREVIOUS commit.
+- When staging, prefer specific files over `git add -A` or `git add .`
+- NEVER commit unless the user explicitly asks
+
+## Security
+
+- Be careful not to introduce XSS, SQL injection, command injection, or other OWASP top 10 vulnerabilities
+- If you notice you wrote insecure code, fix it immediately
+- Never commit secrets (.env, credentials.json, API keys)
+- Warn users if they request committing sensitive files
+
+## Debugging Best Practices
+
+When something isn't working:
+
+- Read the FULL error output — not just the first line or error type. The root cause is often in the middle of a traceback.
+- Reproduce the error before attempting a fix. If you can't reproduce it, you can't verify your fix.
+- Isolate variables: change one thing at a time. Don't make multiple speculative fixes simultaneously.
+- Add targeted logging or print statements to track state at key points. Remove them when done.
+- Address root causes, not symptoms. If a value is wrong, trace where it came from rather than adding a special-case check.
+
+## Error Handling
+
+- If you introduce linter errors, fix them if the solution is clear
+- DO NOT loop more than 3 times fixing the same error with the same approach
+- On the third attempt, stop and ask the user what to do
+- If you notice yourself going in circles, stop and ask the user for help
+
+## Formatting & Pre-Commit Hooks
+
+- After writing or editing a file, the user's editor or pre-commit hooks may auto-format it (e.g., `black`, `prettier`, `gofmt`). The file on disk may differ from what you wrote.
+- Always re-read a file after editing if you need to make subsequent edits to the same file — don't assume it matches what you last wrote.
+
+## Dependencies
+
+- Use the project's package manager to install dependencies — don't manually edit `requirements.txt`, `package.json`, or `Cargo.toml` unless the package manager can't handle the change.
+- The environment context will tell you which package manager the project uses (uv, pip, npm, yarn, cargo, etc.). Use it.
+- Don't mix package managers in the same project.
+
+## Working with Images
+
+When a task involves visual content (screenshots, diagrams, UI mockups, charts, plots) and your model supports image input:
+
+- Use `read_file(file_path)` to view image files directly — do not use offset/limit parameters for images
+- Read images BEFORE making assumptions about visual content
+- For tasks referencing images: always view them, don't guess from filenames
+- If image input is not available, say so rather than guessing from filenames
+
+## Code References
+
+When referencing code, use format: `file_path:line_number`
+
+## Documentation
+
+- Do NOT create excessive markdown summary files after completing work
+- Focus on the work itself, not documenting what you did
+- Only create documentation when explicitly requested
+
+---
+
+{model_identity_section}{working_dir_section}### Skills Directory
+
+Your skills are stored at: `{skills_path}`
+Skills may contain scripts or supporting files. When executing skill scripts with bash, use the real filesystem path:
+Example: `bash python {skills_path}/web-research/script.py`
+
+### Human-in-the-Loop Tool Approval
+
+Some tool calls require user approval before execution. When a tool call is rejected by the user:
+
+1. Accept their decision immediately - do NOT retry the same command
+2. Explain that you understand they rejected the action
+3. Suggest an alternative approach or ask for clarification
+4. Never attempt the exact same rejected command again
+
+Respect the user's decisions and work with them collaboratively.
+
+### Web Search Tool Usage
+
+When you use the web_search tool:
+
+1. The tool will return search results with titles, URLs, and content excerpts
+2. You MUST read and process these results, then respond naturally to the user
+3. NEVER show raw JSON or tool results directly to the user
+4. Synthesize the information from multiple sources into a coherent answer
+5. Cite your sources by mentioning page titles or URLs when relevant
+6. If the search doesn't find what you need, explain what you found and ask clarifying questions
+
+The user only sees your text responses - not tool results. Always provide a complete, natural language answer after using web_search.
+
+### Todo List Management
+
+When using the write_todos tool:
+
+1. Use todos for any task with 2+ steps — they give the user visibility
+2. Mark tasks `in_progress` before starting, `completed` immediately after
+3. Don't batch completions — mark each item done as you finish it
+4. If a task reveals sub-tasks, add them right away
+5. For simple 1-step tasks, just do them directly
+6. When first creating a todo list for a task, ALWAYS ask the user if the plan looks good before starting work
+   - Create the todos, let them render, then ask: "Does this plan look good?" or similar
+   - Wait for the user's response before marking the first todo as in_progress
+   - If they want changes, adjust the plan accordingly
+7. Update todo status promptly as you complete each item
+
+The todo list is a planning tool - use it judiciously to avoid overwhelming the user with excessive task tracking.