zjcode 0.0.1__py3-none-any.whl

deepagents_code/onboarding.py

@@ -0,0 +1,223 @@
+"""First-run onboarding state for the interactive TUI."""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import TYPE_CHECKING
+
+from deepagents_code._env_vars import DEBUG_ONBOARDING, is_env_truthy
+from deepagents_code.model_config import DEFAULT_STATE_DIR
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+ONBOARDING_MARKER_FILENAME = "onboarding_complete"
+"""Marker filename under `~/.deepagents/.state` after onboarding has completed."""
+
+ONBOARDING_NAME_MEMORY_START = "<!-- deepagents:onboarding-name:start -->"
+"""Start marker for the managed onboarding name memory block."""
+
+ONBOARDING_NAME_MEMORY_END = "<!-- deepagents:onboarding-name:end -->"
+"""End marker for the managed onboarding name memory block."""
+
+
+def onboarding_marker_path(state_dir: Path | None = None) -> Path:
+    """Return the first-run onboarding marker path.
+
+    Args:
+        state_dir: Optional state directory override for tests.
+
+    Returns:
+        Path to the onboarding completion marker.
+    """
+    return (state_dir or DEFAULT_STATE_DIR) / ONBOARDING_MARKER_FILENAME
+
+
+def has_completed_onboarding(state_dir: Path | None = None) -> bool:
+    """Return whether the user has completed onboarding.
+
+    Args:
+        state_dir: Optional state directory override for tests.
+
+    Returns:
+        `True` when the onboarding marker exists, otherwise `False`.
+    """
+    try:
+        return onboarding_marker_path(state_dir).exists()
+    except OSError:
+        logger.warning("Could not inspect onboarding marker", exc_info=True)
+        return False
+
+
+def mark_onboarding_complete(state_dir: Path | None = None) -> bool:
+    """Persist that onboarding has completed.
+
+    Args:
+        state_dir: Optional state directory override for tests.
+
+    Returns:
+        `True` when the marker was written, otherwise `False`.
+    """
+    path = onboarding_marker_path(state_dir)
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text("1\n", encoding="utf-8")
+    except OSError:
+        logger.warning("Could not write onboarding marker at %s", path, exc_info=True)
+        return False
+    return True
+
+
+def write_onboarding_name_memory(
+    name: str,
+    assistant_id: str,
+    *,
+    memory_path: Path | None = None,
+) -> bool:
+    """Persist the optional onboarding name into user agent memory.
+
+    Empty or whitespace-only names are skipped (no file is written).
+
+    Args:
+        name: Submitted user name.
+        assistant_id: Agent identifier whose user memory should be updated.
+        memory_path: Optional memory file override for tests.
+
+    Returns:
+        `True` when memory was written, otherwise `False`.
+    """
+    clean = _normalize_memory_name(name)
+    if not clean:
+        return False
+
+    if memory_path is None:
+        from deepagents_code.config import settings
+
+        path = settings.get_user_agent_md_path(assistant_id)
+    else:
+        path = memory_path
+
+    block = _onboarding_name_memory_block(clean)
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        try:
+            existing = path.read_text(encoding="utf-8")
+        except FileNotFoundError:
+            existing = ""
+        except UnicodeDecodeError:
+            # Existing memory file is not valid UTF-8. Overwriting would clobber
+            # whatever the user has there, so abort and let them resolve it.
+            logger.warning(
+                "Existing memory file %s is not valid UTF-8; skipping onboarding "
+                "name memory write to avoid clobbering user content",
+                path,
+                exc_info=True,
+            )
+            return False
+        path.write_text(
+            _upsert_onboarding_name_memory(existing, block),
+            encoding="utf-8",
+        )
+    except OSError:
+        logger.warning(
+            "Could not write onboarding name memory at %s",
+            path,
+            exc_info=True,
+        )
+        return False
+    return True
+
+
+def _normalize_memory_name(name: str) -> str:
+    """Normalize whitespace in a name before writing it to memory.
+
+    Returns:
+        Name with leading/trailing whitespace stripped and internal runs
+            collapsed to single spaces.
+    """
+    return " ".join(name.split())
+
+
+def _onboarding_name_memory_block(name: str) -> str:
+    """Return the managed memory block for an onboarding name."""
+    quoted = json.dumps(name)
+    return (
+        f"{ONBOARDING_NAME_MEMORY_START}\n"
+        f"- The user's preferred name is {quoted}.\n"
+        f"{ONBOARDING_NAME_MEMORY_END}"
+    )
+
+
+def _upsert_onboarding_name_memory(existing: str, block: str) -> str:
+    """Insert or replace the managed onboarding name memory block.
+
+    Returns:
+        Updated memory file content.
+    """
+    start = existing.find(ONBOARDING_NAME_MEMORY_START)
+    end = existing.find(ONBOARDING_NAME_MEMORY_END)
+    if start != -1 and end != -1 and start < end:
+        end += len(ONBOARDING_NAME_MEMORY_END)
+        prefix = existing[:start].rstrip()
+        suffix = existing[end:].strip()
+        parts = [part for part in (prefix, block, suffix) if part]
+        return "\n\n".join(parts).rstrip() + "\n"
+
+    base = existing.rstrip()
+    if not base:
+        return f"## User Preferences\n\n{block}\n"
+    if "## User Preferences" in base:
+        return f"{base}\n\n{block}\n"
+    return f"{base}\n\n## User Preferences\n\n{block}\n"
+
+
+def extract_onboarding_name_block(text: str) -> str | None:
+    """Return the managed onboarding name block (markers included) if present.
+
+    Args:
+        text: Memory file content to inspect.
+
+    Returns:
+        The substring from the start marker through the end marker, or `None`
+            when a well-formed block is absent.
+    """
+    start = text.find(ONBOARDING_NAME_MEMORY_START)
+    end = text.find(ONBOARDING_NAME_MEMORY_END)
+    if start == -1 or end == -1 or start >= end:
+        return None
+    return text[start : end + len(ONBOARDING_NAME_MEMORY_END)]
+
+
+def strip_onboarding_name_markers(text: str) -> str:
+    """Remove every onboarding-name marker occurrence from `text`.
+
+    A partial edit can leave a lone start or end marker behind. Stripping all
+    marker strings before re-inserting the managed block keeps re-insertion from
+    producing orphaned markers that would confuse `extract_onboarding_name_block`.
+
+    Args:
+        text: Memory file content to sanitize.
+
+    Returns:
+        `text` with all start and end marker strings removed.
+    """
+    return text.replace(ONBOARDING_NAME_MEMORY_START, "").replace(
+        ONBOARDING_NAME_MEMORY_END, ""
+    )
+
+
+def should_run_onboarding(state_dir: Path | None = None) -> bool:
+    """Return whether onboarding should open at interactive startup.
+
+    Args:
+        state_dir: Optional state directory override for tests.
+
+    Returns:
+        `True` when the debug override is enabled or no completion marker exists.
+    """
+    if is_env_truthy(DEBUG_ONBOARDING):
+        return True
+    return not has_completed_onboarding(state_dir)

deepagents_code/output.py

@@ -0,0 +1,69 @@
+"""Machine-readable JSON output helpers for CLI subcommands.
+
+This module deliberately stays stdlib-only so it can be imported from CLI
+startup paths without pulling in unnecessary dependency trees.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import Literal
+
+OutputFormat = Literal["text", "json"]
+"""Accepted internal output modes for CLI subcommands."""
+
+
+def add_json_output_arg(
+    parser: argparse.ArgumentParser, *, default: OutputFormat | None = None
+) -> None:
+    """Add a `--json` flag to an argparse parser.
+
+    Args:
+        parser: Parser to update.
+        default: Default output format for this parser.
+
+            Pass `None` for subparsers so parent parser values are preserved.
+    """
+    if default is None:
+        parser.add_argument(
+            "--json",
+            dest="output_format",
+            action="store_const",
+            const="json",
+            default=argparse.SUPPRESS,
+            help="Emit machine-readable JSON for this command",
+        )
+    else:
+        parser.add_argument(
+            "--json",
+            dest="output_format",
+            action="store_const",
+            const="json",
+            default=default,
+            help="Emit machine-readable JSON for this command",
+        )
+
+
+def write_json(command: str, data: list | dict) -> None:
+    """Write a JSON envelope to stdout and flush.
+
+    The envelope is a single-line JSON object with a stable schema:
+
+    ```json
+    {"schema_version": 1, "command": "...", "data": ...}
+    ```
+
+    Args:
+        command: Self-documenting command name (e.g. `'list'`,
+            `'threads list'`).
+        data: Payload — typically a list for listing commands or a dict
+            for action/info commands.
+
+            `default=str` is used so that `Path` and `datetime` objects
+            serialize without error.
+    """
+    envelope = {"schema_version": 1, "command": command, "data": data}
+    sys.stdout.write(json.dumps(envelope, default=str) + "\n")
+    sys.stdout.flush()

deepagents_code/paste_collapse.py

@@ -0,0 +1,103 @@
+r"""Large paste collapsing for the chat input.
+
+When the user pastes text exceeding a size or line threshold, the full text
+is stored off-screen and a compact `[Pasted text #N +M lines]` placeholder
+is inserted into the input box instead.  At submission time the placeholder
+is expanded back to the original content so the agent receives the full text.
+
+This mirrors the behavior of Claude Code's paste-collapsing system.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+PASTE_THRESHOLD_CHARS = 800
+"""Minimum character count for a paste to be collapsed into a placeholder."""
+
+PASTE_THRESHOLD_LINES = 2
+"""Minimum line count (newline-separated) for a paste to be collapsed."""
+
+PASTE_PLACEHOLDER_PATTERN = re.compile(r"\[Pasted text #(\d+)(?: \+(\d+) lines)?\]")
+"""Regex matching `[Pasted text #N]` or `[Pasted text #N +M lines]`."""
+
+
+@dataclass(frozen=True)
+class PastedContent:
+    """Stored content for a collapsed paste.
+
+    The paste's numeric identifier is the key under which this record is
+    stored in the input's paste map, so it is not duplicated on the record.
+
+    Attributes:
+        content: The full pasted text.
+    """
+
+    content: str
+
+
+def count_lines(text: str) -> int:
+    r"""Return the number of newline characters in `text`.
+
+    Args:
+        text: The text to count newlines in.
+
+    Returns:
+        The number of `\n` occurrences (0 for single-line text).
+    """
+    return text.count("\n")
+
+
+def should_collapse_paste(text: str) -> bool:
+    """Return whether `text` should be collapsed into a placeholder.
+
+    Collapses when the text exceeds the character threshold or the line
+    threshold.
+
+    Args:
+        text: The pasted text to evaluate.
+
+    Returns:
+        `True` if the paste should be collapsed.
+    """
+    return (
+        len(text) > PASTE_THRESHOLD_CHARS or count_lines(text) > PASTE_THRESHOLD_LINES
+    )
+
+
+def format_paste_ref(paste_id: int, num_lines: int) -> str:
+    """Format a paste placeholder reference string.
+
+    Args:
+        paste_id: The numeric paste identifier.
+        num_lines: The number of extra lines (newlines) in the pasted content.
+
+    Returns:
+        `[Pasted text #N]` when `num_lines` is 0, otherwise
+        `[Pasted text #N +M lines]`.
+    """
+    if num_lines == 0:
+        return f"[Pasted text #{paste_id}]"
+    return f"[Pasted text #{paste_id} +{num_lines} lines]"
+
+
+def expand_paste_refs(text: str, pasted_contents: dict[int, PastedContent]) -> str:
+    """Replace all paste placeholders in `text` with their full content.
+
+    Placeholders whose IDs are not in `pasted_contents` are left unchanged.
+
+    Args:
+        text: The text containing placeholders.
+        pasted_contents: Mapping of paste IDs to stored content.
+
+    Returns:
+        The text with all known placeholders expanded.
+    """
+
+    def _replace(match: re.Match[str]) -> str:
+        content = pasted_contents.get(int(match.group(1)))
+        # Return the stored text literally; unknown IDs keep their placeholder.
+        return content.content if content is not None else match.group(0)
+
+    return PASTE_PLACEHOLDER_PATTERN.sub(_replace, text)

deepagents_code/project_utils.py

@@ -0,0 +1,231 @@
+"""Utilities for project root detection and project-specific configuration."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from deepagents_code._env_vars import SERVER_ENV_PREFIX
+from deepagents_code._git import find_git_root
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class ProjectContext:
+    """Explicit user/project path context for project-sensitive behavior.
+
+    Attributes:
+        user_cwd: Authoritative working directory from the app invocation.
+        project_root: Resolved project root for `user_cwd`, if one exists.
+    """
+
+    user_cwd: Path
+    project_root: Path | None = None
+
+    def __post_init__(self) -> None:
+        """Validate that path fields are absolute.
+
+        Raises:
+            ValueError: If `user_cwd` or `project_root` is not absolute.
+        """
+        if not self.user_cwd.is_absolute():
+            msg = f"user_cwd must be absolute, got {self.user_cwd!r}"
+            raise ValueError(msg)
+        if self.project_root is not None and not self.project_root.is_absolute():
+            msg = f"project_root must be absolute, got {self.project_root!r}"
+            raise ValueError(msg)
+
+    @classmethod
+    def from_user_cwd(cls, user_cwd: str | Path) -> ProjectContext:
+        """Build a project context from an explicit user working directory.
+
+        Args:
+            user_cwd: User invocation directory.
+
+        Returns:
+            Resolved project context.
+        """
+        resolved_cwd = Path(user_cwd).expanduser().resolve()
+        return cls(
+            user_cwd=resolved_cwd,
+            project_root=find_project_root(resolved_cwd),
+        )
+
+    def resolve_user_path(self, path: str | Path) -> Path:
+        """Resolve a path relative to the explicit user working directory.
+
+        Args:
+            path: Absolute or relative user-facing path.
+
+        Returns:
+            Absolute resolved path.
+        """
+        candidate = Path(path).expanduser()
+        if candidate.is_absolute():
+            return candidate.resolve()
+        return (self.user_cwd / candidate).resolve()
+
+    def project_agent_md_paths(self) -> list[Path]:
+        """Return project-level `AGENTS.md` files for this context."""
+        if self.project_root is None:
+            return []
+        return find_project_agent_md(self.project_root)
+
+    def project_skills_dir(self) -> Path | None:
+        """Return the project `.deepagents/skills` directory, if any."""
+        if self.project_root is None:
+            return None
+        return self.project_root / ".deepagents" / "skills"
+
+    def project_agents_dir(self) -> Path | None:
+        """Return the project `.deepagents/agents` directory, if any."""
+        if self.project_root is None:
+            return None
+        return self.project_root / ".deepagents" / "agents"
+
+    def project_agent_skills_dir(self) -> Path | None:
+        """Return the project `.agents/skills` directory, if any."""
+        if self.project_root is None:
+            return None
+        return self.project_root / ".agents" / "skills"
+
+
+def get_server_project_context(
+    env: Mapping[str, str] | None = None,
+) -> ProjectContext | None:
+    """Read the server project context from environment transport data.
+
+    Args:
+        env: Environment mapping to read from.
+
+    Returns:
+        Reconstructed project context, or `None` if no server context exists.
+    """
+    environment = os.environ if env is None else env
+    raw_cwd = environment.get(f"{SERVER_ENV_PREFIX}CWD")
+    if not raw_cwd:
+        return None
+
+    try:
+        user_cwd = Path(raw_cwd).expanduser().resolve()
+        raw_project_root = environment.get(f"{SERVER_ENV_PREFIX}PROJECT_ROOT")
+        project_root = (
+            Path(raw_project_root).expanduser().resolve()
+            if raw_project_root
+            else find_project_root(user_cwd)
+        )
+    except OSError:
+        logger.warning(
+            "Could not resolve server project context from CWD=%s",
+            raw_cwd,
+            exc_info=True,
+        )
+        return None
+
+    return ProjectContext(user_cwd=user_cwd, project_root=project_root)
+
+
+def find_project_root(start_path: str | Path | None = None) -> Path | None:
+    """Find the project root by looking for git metadata.
+
+    Args:
+        start_path: Directory to start searching from.
+            Defaults to current working directory.
+
+    Returns:
+        Path to the project root if found, None otherwise.
+    """
+    current = Path(start_path or Path.cwd()).expanduser().resolve()
+    return find_git_root(current)
+
+
+def find_project_agent_md(project_root: Path) -> list[Path]:
+    """Find project-specific AGENTS.md file(s).
+
+    Checks two locations and returns ALL that exist:
+    1. project_root/.deepagents/AGENTS.md
+    2. project_root/AGENTS.md
+
+    Both files will be loaded and combined if both exist.
+
+    Candidates with symlinked path components are followed only when the
+    resolved target stays inside `project_root`. The returned `Path` is the
+    resolved target when any symlink component was traversed, so
+    `FilesystemBackend.download_files` opens a regular file rather than
+    tripping `O_NOFOLLOW` on the link itself. Symlinks pointing outside the
+    project root, symlink loops, and unreadable parents are skipped with a
+    warning. Broken symlinks are treated as missing files (no warning),
+    matching the pre-existing behavior for absent candidates.
+
+    Why: project AGENTS.md is auto-discovered and loaded into the system
+    prompt before the first model call. Without the in-tree check, a
+    malicious clone could ship `AGENTS.md -> ~/.ssh/config` (or any other
+    locally-readable file) and have its contents injected as agent
+    instructions on first run.
+
+    Args:
+        project_root: Path to the project root directory.
+
+    Returns:
+        Existing AGENTS.md paths, with in-tree symlinked path components
+            pre-resolved to their targets. Empty if neither file exists, one
+            entry if only one is present, or two entries if both locations
+            have the file.
+    """
+    # Resolve the root once so the candidate-equality check below works even
+    # when the caller passes a non-canonical `project_root` (e.g., macOS
+    # `/var` -> `/private/var`, or a path with symlinked ancestors).
+    project_root_resolved = project_root.resolve()
+    candidates = [
+        project_root_resolved / ".deepagents" / "AGENTS.md",
+        project_root_resolved / "AGENTS.md",
+    ]
+    paths: list[Path] = []
+    for candidate in candidates:
+        try:
+            # Single syscall handles existence, broken symlinks, loops, and
+            # canonicalization. `strict=True` raises rather than returning
+            # the unresolved path.
+            resolved = candidate.resolve(strict=True)
+        except FileNotFoundError:
+            # Absent file or broken symlink — matches the pre-existing
+            # silent-skip behavior for missing candidates. `Path.exists()`
+            # also returns False for symlink loops on some Python versions,
+            # so loops do NOT come through here; see the OSError branch.
+            continue
+        except (OSError, RuntimeError) as exc:
+            # `OSError(ELOOP)` on Python 3.13+, `RuntimeError("Symlink loop
+            # ...")` on 3.11-3.12; bare `OSError` for permission/unreadable
+            # parent. Security-relevant — warn and skip.
+            logger.warning(
+                "Skipping AGENTS.md candidate %s: %s",
+                candidate,
+                exc,
+            )
+            continue
+
+        try:
+            resolved.relative_to(project_root_resolved)
+        except ValueError:
+            logger.warning(
+                "Skipping AGENTS.md symlink %s: target %s is outside "
+                "the project root %s",
+                candidate,
+                resolved,
+                project_root_resolved,
+            )
+            continue
+
+        if candidate.absolute() == resolved:
+            paths.append(candidate)
+        else:
+            paths.append(resolved)
+    return paths