zjcode 0.0.1__py3-none-any.whl

deepagents_code/subagents.py

@@ -0,0 +1,278 @@
+"""Subagent loader for app.
+
+Loads custom subagent definitions from the filesystem. Subagents are defined
+as markdown files with YAML frontmatter in the agents/ directory.
+
+Directory structure:
+    .deepagents/agents/{agent_name}/AGENTS.md
+
+Example file (researcher/AGENTS.md):
+    ---
+    name: researcher  # optional; defaults to the folder name
+    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
+
+The `name` field is optional; when omitted it defaults to the folder name
+(e.g. `researcher`). This diverges from the Agent Skills specification
+(`deepagents.middleware.skills`), which requires `name` in frontmatter and
+warns when it does not match the parent directory name. Subagents use the
+folder name as an implicit fallback instead because subagent definitions are
+already uniquely identified by their folder — requiring a redundant `name`
+field adds friction without adding information.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from typing import TYPE_CHECKING, TypedDict
+
+import yaml
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+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, *, fallback_name: str | None = None
+) -> SubagentMetadata | None:
+    """Parse a subagent markdown file with YAML frontmatter.
+
+    The file must have YAML frontmatter (delimited by ---) containing at minimum
+    a 'description' field. The body of the file becomes the system_prompt.
+
+    Unlike the Agent Skills spec, `name` is optional here — when omitted the
+    folder name passed via `fallback_name` is used instead. Skills require
+    `name` in frontmatter and warn when it doesn't match the directory name;
+    subagents relax that to a fallback so users don't repeat the folder name
+    redundantly.
+
+    Args:
+        file_path: Path to the markdown file.
+        fallback_name: Name to use when the frontmatter omits `name` entirely.
+            A present-but-empty, whitespace-only, or non-string `name` is
+            treated as invalid and rejected rather than falling back, so a typo
+            surfaces loudly instead of being silently masked by the folder name.
+
+    Returns:
+        SubagentMetadata if parsing succeeds, None otherwise.
+    """
+    try:
+        content = file_path.read_text(encoding="utf-8")
+    except OSError as exc:
+        logger.warning("Skipping subagent %s: could not read file (%s)", file_path, exc)
+        return None
+
+    # Extract YAML frontmatter (--- delimited)
+    match = re.match(r"^---\s*\n(.*?)\n---\s*\n?(.*)$", content, re.DOTALL)
+    if not match:
+        logger.warning(
+            "Skipping subagent %s: missing YAML frontmatter. The file must start "
+            "with a '---' delimited block containing at least 'description'.",
+            file_path,
+        )
+        return None
+
+    try:
+        frontmatter = yaml.safe_load(match.group(1))
+    except yaml.YAMLError as exc:
+        logger.warning(
+            "Skipping subagent %s: invalid YAML frontmatter (%s)", file_path, exc
+        )
+        return None
+
+    # Validate frontmatter structure and required fields
+    if not isinstance(frontmatter, dict):
+        logger.warning(
+            "Skipping subagent %s: frontmatter must be a mapping with a "
+            "'description' field.",
+            file_path,
+        )
+        return None
+
+    name_value = frontmatter.get("name", fallback_name)
+    description_value = frontmatter.get("description")
+    model = frontmatter.get("model")
+
+    # Validate types: name and description must be non-empty strings (leading and
+    # trailing whitespace is stripped, so a whitespace-only value is rejected).
+    # model is optional but must be a string if present.
+    name = (
+        name_value.strip()
+        if isinstance(name_value, str) and name_value.strip()
+        else None
+    )
+    description = (
+        description_value.strip()
+        if isinstance(description_value, str) and description_value.strip()
+        else None
+    )
+    model_valid = model is None or isinstance(model, str)
+
+    if name is None or description is None or not model_valid:
+        invalid_fields: list[str] = []
+        if name is None:
+            invalid_fields.append("name (non-empty string required)")
+        if description is None:
+            invalid_fields.append("description (non-empty string required)")
+        if not model_valid:
+            invalid_fields.append("model (string required when present)")
+        logger.warning(
+            "Skipping subagent %s: invalid or missing frontmatter field(s): %s",
+            file_path,
+            ", ".join(invalid_fields),
+        )
+        return None
+
+    if "name" not in frontmatter:
+        # Fallback engaged. Log it so a typo'd key (e.g. `nmae:`) that silently
+        # resolves to the folder name is at least diagnosable at debug level.
+        logger.debug(
+            "Subagent %s: 'name' omitted from frontmatter; using folder name %r.",
+            file_path,
+            name,
+        )
+
+    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 entry in agents_dir.iterdir():
+        if not entry.is_dir():
+            # A stray file directly under agents/ is a common mistake: subagents
+            # must live at agents/{name}/AGENTS.md, not agents/{name}.md.
+            if entry.suffix.lower() == ".md":
+                logger.warning(
+                    "Ignoring %s subagent file %s: subagents must be defined at "
+                    "%s/{subagent-name}/AGENTS.md, not as a file directly in the "
+                    "agents directory.",
+                    source,
+                    entry,
+                    agents_dir,
+                )
+            continue
+
+        # Look for {folder_name}/AGENTS.md
+        subagent_file = entry / "AGENTS.md"
+        if not subagent_file.exists():
+            # The folder exists but holds a differently-named markdown file
+            # (e.g. agent.md or {name}.md) instead of the required AGENTS.md.
+            stray_md = [p.name for p in entry.glob("*.md")]
+            if stray_md:
+                logger.warning(
+                    "Ignoring %s subagent folder %s: expected an AGENTS.md file "
+                    "but found %s. Rename the definition to AGENTS.md.",
+                    source,
+                    entry,
+                    ", ".join(sorted(stray_md)),
+                )
+            continue
+
+        subagent = _parse_subagent_file(subagent_file, fallback_name=entry.name)
+        if subagent:
+            subagent["source"] = source
+            # The folder name and a declared `name` can differ, so two folders can
+            # resolve to the same subagent name and silently collapse to one entry.
+            # Iteration order is filesystem-dependent, so warn rather than let a
+            # definition vanish without explanation.
+            existing = subagents.get(subagent["name"])
+            if existing is not None:
+                logger.warning(
+                    "Subagent name collision in %s: %s and %s both resolve to "
+                    "name=%r. Using %s; give each subagent a unique folder or "
+                    "frontmatter 'name'.",
+                    agents_dir,
+                    existing["path"],
+                    subagent["path"],
+                    subagent["name"],
+                    subagent["path"],
+                )
+            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())

deepagents_code/system_prompt.md

@@ -0,0 +1,204 @@
+# Deep Agents Code (dcode)
+
+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.
+- 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.
+
+## Following Conventions
+
+- Check existing code for libraries and frameworks before assuming
+- 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
+
+## 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>
+
+When a single tool call in a parallel fanout fails with a schema error like `Unknown JSON field`, do NOT submit additional parallel calls with the same invalid field — drop the offending field and retry as a single corrected call before fanning out again.
+
+### 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(file_path="...", limit=100)` - See file structure and key sections
+2. Targeted read: `read_file(file_path="...", offset=100, limit=200)` - Read specific sections
+3. Full read: Only use `read_file(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
+
+## 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_section}

deepagents_code/terminal_capabilities.py

@@ -0,0 +1,115 @@
+"""Terminal capability detection.
+
+Detect optional terminal features without reading from `stdin`.
+
+The app only uses kitty-keyboard-protocol support to choose a user-facing
+newline shortcut label. To keep startup safe on remote or high-latency PTYs,
+detection is conservative and relies on side-effect-free terminal identity
+signals plus an explicit environment-variable override.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import sys
+from functools import cache
+from typing import TYPE_CHECKING
+
+from deepagents_code._env_vars import KITTY_KEYBOARD
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+logger = logging.getLogger(__name__)
+
+_TRUE_VALUES = frozenset({"1", "true", "yes", "on"})
+_FALSE_VALUES = frozenset({"0", "false", "no", "off"})
+_KNOWN_KITTY_KEYBOARD_TERMS = frozenset({"xterm-ghostty", "xterm-kitty"})
+
+
+def _override_supports_kitty_keyboard_protocol(
+    env: Mapping[str, str],
+) -> bool | None:
+    """Return an explicit kitty-keyboard override from `env`, if present.
+
+    Accepted truthy values are `'1'`, `'true'`, `'yes'`, and `'on'`.
+    Accepted falsy values are `'0'`, `'false'`, `'no'`, and `'off'`.
+    `'auto'`, the empty string, and invalid values fall back to heuristic
+    detection.
+    """
+    raw = env.get(KITTY_KEYBOARD)
+    if raw is None:
+        return None
+
+    normalized = raw.strip().lower()
+    if normalized in {"", "auto"}:
+        return None
+    if normalized in _TRUE_VALUES:
+        return True
+    if normalized in _FALSE_VALUES:
+        return False
+
+    logger.warning(
+        "%s=%r ignored; expected one of: %s, or 'auto' to defer to detection.",
+        KITTY_KEYBOARD,
+        raw,
+        ", ".join(sorted(_TRUE_VALUES | _FALSE_VALUES)),
+    )
+    return None
+
+
+def _terminal_identity_supports_kitty_keyboard_protocol(
+    env: Mapping[str, str],
+) -> bool:
+    """Return whether `env` identifies a terminal with built-in kitty support.
+
+    This intentionally only recognizes terminals whose environment markers
+    imply kitty-keyboard support is part of the terminal's default identity.
+    Configurable terminals such as iTerm2 and WezTerm are intentionally not
+    auto-detected because protocol support can be disabled in user settings.
+    """
+    if env.get("KITTY_WINDOW_ID"):
+        return True
+
+    term = env.get("TERM", "")
+    return term in _KNOWN_KITTY_KEYBOARD_TERMS
+
+
+@cache
+def supports_kitty_keyboard_protocol() -> bool:
+    """Return whether the attached terminal should be treated as kitty-aware.
+
+    Detection is side-effect free: it never writes escape sequences or reads
+    queued input bytes. That means it may under-detect some configurable
+    terminals, but it will not interfere with Textual's input stream.
+
+    Set `DEEPAGENTS_CODE_KITTY_KEYBOARD` to an accepted truthy value (`1`,
+    `true`, `yes`, `on`) to force-enable the label, a falsy value (`0`,
+    `false`, `no`, `off`) to force-disable it, or `auto`/unset to use
+    heuristic detection.
+
+    Returns:
+        `True` when the terminal is known to support the kitty keyboard
+        protocol, `False` otherwise.
+    """
+    if sys.platform == "win32":
+        logger.debug("kitty kbd detection: False (win32 unsupported)")
+        return False
+    if not (sys.stdin.isatty() and sys.stdout.isatty()):
+        logger.debug("kitty kbd detection: False (stdin/stdout not a tty)")
+        return False
+
+    override = _override_supports_kitty_keyboard_protocol(os.environ)
+    if override is not None:
+        logger.debug("kitty kbd detection: %s (explicit override)", override)
+        return override
+
+    detected = _terminal_identity_supports_kitty_keyboard_protocol(os.environ)
+    logger.debug(
+        "kitty kbd detection: %s (terminal identity TERM=%r KITTY_WINDOW_ID=%r)",
+        detected,
+        os.environ.get("TERM", ""),
+        os.environ.get("KITTY_WINDOW_ID"),
+    )
+    return detected