docagent-cli 0.0.35__py3-none-any.whl

docagent_cli/token_state.py

@@ -0,0 +1,31 @@
+"""Middleware that adds a `_context_tokens` channel to the graph state.
+
+The field is checkpointed (survives across sessions) but not passed to the
+model (`PrivateStateAttr`).  The CLI writes the latest total-context token
+count here after every LLM response and context offload, and reads it back
+when resuming a thread so that `/tokens` and the status bar show accurate
+values immediately.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, NotRequired
+
+from langchain.agents.middleware.types import (
+    AgentMiddleware,
+    AgentState,
+    PrivateStateAttr,
+)
+
+
+class TokenTrackingState(AgentState):
+    """Extends agent state with a persisted context-token counter."""
+
+    _context_tokens: Annotated[NotRequired[int], PrivateStateAttr]
+    """Total context tokens reported by the model's last `usage_metadata`."""
+
+
+class TokenStateMiddleware(AgentMiddleware):
+    """Schema-only middleware that registers `_context_tokens` in the state schema."""
+
+    state_schema = TokenTrackingState

docagent_cli/tool_display.py

@@ -0,0 +1,298 @@
+"""Formatting utilities for tool call display in the CLI.
+
+This module handles rendering tool calls and tool messages for the TUI.
+
+Imported at module level by `textual_adapter` (itself deferred from the startup
+path). Heavy SDK dependencies (e.g., `backends`) are deferred to function bodies.
+"""
+
+import json
+from contextlib import suppress
+from pathlib import Path
+from typing import Any
+
+from docagent_cli.config import MAX_ARG_LENGTH, get_glyphs
+from docagent_cli.unicode_security import strip_dangerous_unicode
+
+_HIDDEN_CHAR_MARKER = " [hidden chars removed]"
+"""Marker appended to display values that had dangerous Unicode stripped, so
+users know the value was modified for safety."""
+
+
+def _format_timeout(seconds: int) -> str:
+    """Format timeout in human-readable units (e.g., 300 -> '5m', 3600 -> '1h').
+
+    Args:
+        seconds: The timeout value in seconds to format.
+
+    Returns:
+        Human-readable timeout string (e.g., '5m', '1h', '300s').
+    """
+    if seconds < 60:  # noqa: PLR2004  # Time unit boundary
+        return f"{seconds}s"
+    if seconds < 3600 and seconds % 60 == 0:  # noqa: PLR2004  # Time unit boundaries
+        return f"{seconds // 60}m"
+    if seconds % 3600 == 0:
+        return f"{seconds // 3600}h"
+    # For odd values, just show seconds
+    return f"{seconds}s"
+
+
+def _coerce_timeout_seconds(timeout: int | str | None) -> int | None:
+    """Normalize timeout values to seconds for display.
+
+    Accepts integer values and numeric strings. Returns `None` for invalid
+    values so display formatting never raises.
+
+    Args:
+        timeout: Raw timeout value from tool arguments.
+
+    Returns:
+        Integer timeout in seconds, or `None` if unavailable/invalid.
+    """
+    if type(timeout) is int:
+        return timeout
+    if isinstance(timeout, str):
+        stripped = timeout.strip()
+        if not stripped:
+            return None
+        try:
+            return int(stripped)
+        except ValueError:
+            return None
+    return None
+
+
+def truncate_value(value: str, max_length: int = MAX_ARG_LENGTH) -> str:
+    """Truncate a string value if it exceeds max_length.
+
+    Returns:
+        Truncated string with ellipsis suffix if exceeded, otherwise original.
+    """
+    if len(value) > max_length:
+        return value[:max_length] + get_glyphs().ellipsis
+    return value
+
+
+def _sanitize_display_value(value: object, *, max_length: int = MAX_ARG_LENGTH) -> str:
+    """Sanitize a value for safe, compact terminal display.
+
+    Hidden/deceptive Unicode controls are stripped. When stripping occurs, a
+    marker is appended so users know the value changed for display safety.
+
+    Args:
+        value: Any value to display.
+        max_length: Maximum display length before truncation.
+
+    Returns:
+        Sanitized display string.
+    """
+    raw = str(value)
+    sanitized = strip_dangerous_unicode(raw)
+    display = truncate_value(sanitized, max_length)
+    if sanitized != raw:
+        return display + _HIDDEN_CHAR_MARKER
+    return display
+
+
+def format_tool_display(tool_name: str, tool_args: dict) -> str:
+    """Format tool calls for display with tool-specific smart formatting.
+
+    Shows the most relevant information for each tool type rather than all arguments.
+
+    Args:
+        tool_name: Name of the tool being called
+        tool_args: Dictionary of tool arguments
+
+    Returns:
+        Formatted string for display (e.g., "(*) read_file(config.py)" in ASCII mode)
+
+    Examples:
+        read_file(path="/long/path/file.py") → "<prefix> read_file(file.py)"
+        web_search(query="how to code") → '<prefix> web_search("how to code")'
+        execute(command="pip install foo") → '<prefix> execute("pip install foo")'
+    """
+    prefix = get_glyphs().tool_prefix
+
+    def abbreviate_path(path_str: str, max_length: int = 60) -> str:
+        """Abbreviate a file path intelligently - show basename or relative path.
+
+        Returns:
+            Shortened path string suitable for display.
+        """
+        try:
+            path = Path(path_str)
+
+            # If it's just a filename (no directory parts), return as-is
+            if len(path.parts) == 1:
+                return path_str
+
+            # Try to get relative path from current working directory
+            with suppress(
+                ValueError,  # ValueError: path is not relative to cwd
+                OSError,  # OSError: filesystem errors when resolving paths
+            ):
+                rel_path = path.relative_to(Path.cwd())
+                rel_str = str(rel_path)
+                # Use relative if it's shorter and not too long
+                if len(rel_str) < len(path_str) and len(rel_str) <= max_length:
+                    return rel_str
+
+            # If absolute path is reasonable length, use it
+            if len(path_str) <= max_length:
+                return path_str
+        except Exception:  # noqa: BLE001  # Fallback to original string on any path resolution error
+            return truncate_value(path_str, max_length)
+        else:
+            # Otherwise, just show basename (filename only)
+            return path.name
+
+    # Tool-specific formatting - show the most important argument(s)
+    if tool_name in {"read_file", "write_file", "edit_file"}:
+        # File operations: show the primary file path argument (file_path or path)
+        path_value = tool_args.get("file_path")
+        if path_value is None:
+            path_value = tool_args.get("path")
+        if path_value is not None:
+            path_raw = strip_dangerous_unicode(str(path_value))
+            path = abbreviate_path(path_raw)
+            if path_raw != str(path_value):
+                path += _HIDDEN_CHAR_MARKER
+            return f"{prefix} {tool_name}({path})"
+
+    elif tool_name == "web_search":
+        # Web search: show the query string
+        if "query" in tool_args:
+            query = _sanitize_display_value(tool_args["query"], max_length=100)
+            return f'{prefix} {tool_name}("{query}")'
+
+    elif tool_name == "grep":
+        # Grep: show the search pattern
+        if "pattern" in tool_args:
+            pattern = _sanitize_display_value(tool_args["pattern"], max_length=70)
+            return f'{prefix} {tool_name}("{pattern}")'
+
+    elif tool_name == "execute":
+        # Execute: show the command, and timeout only if non-default
+        if "command" in tool_args:
+            command = _sanitize_display_value(tool_args["command"], max_length=120)
+            timeout = _coerce_timeout_seconds(tool_args.get("timeout"))
+            from deepagents.backends import DEFAULT_EXECUTE_TIMEOUT
+
+            if timeout is not None and timeout != DEFAULT_EXECUTE_TIMEOUT:
+                timeout_str = _format_timeout(timeout)
+                return f'{prefix} {tool_name}("{command}", timeout={timeout_str})'
+            return f'{prefix} {tool_name}("{command}")'
+
+    elif tool_name == "ls":
+        # ls: show directory, or empty if current directory
+        if tool_args.get("path"):
+            path_raw = strip_dangerous_unicode(str(tool_args["path"]))
+            path = abbreviate_path(path_raw)
+            if path_raw != str(tool_args["path"]):
+                path += _HIDDEN_CHAR_MARKER
+            return f"{prefix} {tool_name}({path})"
+        return f"{prefix} {tool_name}()"
+
+    elif tool_name == "glob":
+        # Glob: show the pattern
+        if "pattern" in tool_args:
+            pattern = _sanitize_display_value(tool_args["pattern"], max_length=80)
+            return f'{prefix} {tool_name}("{pattern}")'
+
+    elif tool_name == "fetch_url":
+        # Fetch URL: show the URL being fetched
+        if "url" in tool_args:
+            url = _sanitize_display_value(tool_args["url"], max_length=80)
+            return f'{prefix} {tool_name}("{url}")'
+
+    elif tool_name == "task":
+        # Task: show subagent type badge
+        agent_type = tool_args.get("subagent_type", "")
+        if agent_type:
+            agent_type = _sanitize_display_value(agent_type, max_length=40)
+            return f"{prefix} {tool_name} [{agent_type}]"
+        return f"{prefix} {tool_name}"
+
+    elif tool_name == "ask_user":
+        if "questions" in tool_args and isinstance(tool_args["questions"], list):
+            count = len(tool_args["questions"])
+            label = "question" if count == 1 else "questions"
+            return f"{prefix} {tool_name}({count} {label})"
+
+    elif tool_name == "compact_conversation":
+        return f"{prefix} {tool_name}()"
+
+    elif tool_name == "write_todos":
+        if "todos" in tool_args and isinstance(tool_args["todos"], list):
+            count = len(tool_args["todos"])
+            return f"{prefix} {tool_name}({count} items)"
+
+    # Fallback: generic formatting for unknown tools
+    # Show all arguments in key=value format
+    args_str = ", ".join(
+        f"{_sanitize_display_value(k, max_length=30)}="
+        f"{_sanitize_display_value(v, max_length=50)}"
+        for k, v in tool_args.items()
+    )
+    return f"{prefix} {tool_name}({args_str})"
+
+
+def _format_content_block(block: dict) -> str:
+    """Format a single content block dict for display.
+
+    Replaces large binary payloads (e.g. base64 image/video data) with a
+    human-readable placeholder so they don't flood the terminal.
+
+    Args:
+        block: An `ImageContentBlock`, `VideoContentBlock`, or `FileContentBlock`
+            dictionary.
+
+    Returns:
+        A display-friendly string for the block.
+    """
+    if block.get("type") == "image" and isinstance(block.get("base64"), str):
+        b64 = block["base64"]
+        size_kb = len(b64) * 3 // 4 // 1024  # approximate decoded size
+        mime = block.get("mime_type", "image")
+        return f"[Image: {mime}, ~{size_kb}KB]"
+    if block.get("type") == "video" and isinstance(block.get("base64"), str):
+        b64 = block["base64"]
+        size_kb = len(b64) * 3 // 4 // 1024  # approximate decoded size
+        mime = block.get("mime_type", "video")
+        return f"[Video: {mime}, ~{size_kb}KB]"
+    if block.get("type") == "file" and isinstance(block.get("base64"), str):
+        b64 = block["base64"]
+        size_kb = len(b64) * 3 // 4 // 1024  # approximate decoded size
+        mime = block.get("mime_type", "file")
+        return f"[File: {mime}, ~{size_kb}KB]"
+    try:
+        # Preserve non-ASCII characters (CJK, emoji, etc.) instead of \uXXXX escapes
+        return json.dumps(block, ensure_ascii=False)
+    except (TypeError, ValueError):
+        return str(block)
+
+
+def format_tool_message_content(content: Any) -> str:  # noqa: ANN401  # Content can be str, list, or dict
+    """Convert `ToolMessage` content into a printable string.
+
+    Returns:
+        Formatted string representation of the tool message content.
+    """
+    if content is None:
+        return ""
+    if isinstance(content, list):
+        parts = []
+        for item in content:
+            if isinstance(item, str):
+                parts.append(item)
+            elif isinstance(item, dict):
+                parts.append(_format_content_block(item))
+            else:
+                try:
+                    # Preserve non-ASCII characters (CJK, emoji, etc.)
+                    parts.append(json.dumps(item, ensure_ascii=False))
+                except (TypeError, ValueError):
+                    parts.append(str(item))
+        return "\n".join(parts)
+    return str(content)

docagent_cli/tools.py

@@ -0,0 +1,236 @@
+"""Custom tools for the CLI agent."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Literal
+
+if TYPE_CHECKING:
+    from tavily import TavilyClient
+
+_UNSET = object()
+_tavily_client: TavilyClient | object | None = _UNSET
+
+
+def _get_tavily_client() -> TavilyClient | None:
+    """Get or initialize the lazy Tavily client singleton.
+
+    Returns:
+        TavilyClient instance, or None if API key is not configured.
+    """
+    global _tavily_client  # noqa: PLW0603  # Module-level cache requires global statement
+    if _tavily_client is not _UNSET:
+        return _tavily_client  # type: ignore[return-value]  # narrowed by sentinel check
+
+    from docagent_cli.config import settings
+
+    if settings.has_tavily:
+        from tavily import TavilyClient as _TavilyClient
+
+        _tavily_client = _TavilyClient(api_key=settings.tavily_api_key)
+    else:
+        _tavily_client = None
+    return _tavily_client
+
+
+def http_request(
+    url: str,
+    method: str = "GET",
+    headers: dict[str, str] | None = None,
+    data: str | dict | None = None,
+    params: dict[str, str] | None = None,
+    timeout: int = 30,
+) -> dict[str, Any]:
+    """Make HTTP requests to APIs and web services.
+
+    Args:
+        url: Target URL
+        method: HTTP method (GET, POST, PUT, DELETE, etc.)
+        headers: HTTP headers to include
+        data: Request body data (string or dict)
+        params: URL query parameters
+        timeout: Request timeout in seconds
+
+    Returns:
+        Dictionary with response data including status, headers, and content
+    """
+    import requests
+
+    try:
+        kwargs: dict[str, Any] = {}
+
+        if headers:
+            kwargs["headers"] = headers
+        if params:
+            kwargs["params"] = params
+        if data:
+            if isinstance(data, dict):
+                kwargs["json"] = data
+            else:
+                kwargs["data"] = data
+
+        response = requests.request(method.upper(), url, timeout=timeout, **kwargs)
+
+        try:
+            content = response.json()
+        except (ValueError, requests.exceptions.JSONDecodeError):
+            content = response.text
+
+        return {
+            "success": response.status_code < 400,  # noqa: PLR2004  # HTTP status code threshold
+            "status_code": response.status_code,
+            "headers": dict(response.headers),
+            "content": content,
+            "url": response.url,
+        }
+
+    except requests.exceptions.Timeout:
+        return {
+            "success": False,
+            "status_code": 0,
+            "headers": {},
+            "content": f"Request timed out after {timeout} seconds",
+            "url": url,
+        }
+    except requests.exceptions.RequestException as e:
+        return {
+            "success": False,
+            "status_code": 0,
+            "headers": {},
+            "content": f"Request error: {e!s}",
+            "url": url,
+        }
+
+
+def web_search(  # noqa: ANN201  # Return type depends on dynamic tool configuration
+    query: str,
+    max_results: int = 5,
+    topic: Literal["general", "news", "finance"] = "general",
+    include_raw_content: bool = False,
+):
+    """Search the web using Tavily for current information and documentation.
+
+    This tool searches the web and returns relevant results. After receiving results,
+    you MUST synthesize the information into a natural, helpful response for the user.
+
+    Args:
+        query: The search query (be specific and detailed)
+        max_results: Number of results to return (default: 5)
+        topic: Search topic type - "general" for most queries, "news" for current events
+        include_raw_content: Include full page content (warning: uses more tokens)
+
+    Returns:
+        Dictionary containing:
+        - results: List of search results, each with:
+            - title: Page title
+            - url: Page URL
+            - content: Relevant excerpt from the page
+            - score: Relevance score (0-1)
+        - query: The original search query
+
+    IMPORTANT: After using this tool:
+    1. Read through the 'content' field of each result
+    2. Extract relevant information that answers the user's question
+    3. Synthesize this into a clear, natural language response
+    4. Cite sources by mentioning the page titles or URLs
+    5. NEVER show the raw JSON to the user - always provide a formatted response
+    """
+    try:
+        import requests
+        from tavily import (
+            BadRequestError,
+            InvalidAPIKeyError,
+            MissingAPIKeyError,
+            UsageLimitExceededError,
+        )
+        from tavily.errors import ForbiddenError, TimeoutError as TavilyTimeoutError
+    except ImportError as exc:
+        return {
+            "error": f"Required package not installed: {exc.name}. "
+            "Install with: pip install 'docagent[cli]'",
+            "query": query,
+        }
+
+    client = _get_tavily_client()
+    if client is None:
+        return {
+            "error": "Tavily API key not configured. "
+            "Please set TAVILY_API_KEY environment variable.",
+            "query": query,
+        }
+
+    try:
+        return client.search(
+            query,
+            max_results=max_results,
+            include_raw_content=include_raw_content,
+            topic=topic,
+        )
+    except (
+        requests.exceptions.RequestException,
+        ValueError,
+        TypeError,
+        # Tavily-specific exceptions
+        BadRequestError,
+        ForbiddenError,
+        InvalidAPIKeyError,
+        MissingAPIKeyError,
+        TavilyTimeoutError,
+        UsageLimitExceededError,
+    ) as e:
+        return {"error": f"Web search error: {e!s}", "query": query}
+
+
+def fetch_url(url: str, timeout: int = 30) -> dict[str, Any]:
+    """Fetch content from a URL and convert HTML to markdown format.
+
+    This tool fetches web page content and converts it to clean markdown text,
+    making it easy to read and process HTML content. After receiving the markdown,
+    you MUST synthesize the information into a natural, helpful response for the user.
+
+    Args:
+        url: The URL to fetch (must be a valid HTTP/HTTPS URL)
+        timeout: Request timeout in seconds (default: 30)
+
+    Returns:
+        Dictionary containing:
+        - success: Whether the request succeeded
+        - url: The final URL after redirects
+        - markdown_content: The page content converted to markdown
+        - status_code: HTTP status code
+        - content_length: Length of the markdown content in characters
+
+    IMPORTANT: After using this tool:
+    1. Read through the markdown content
+    2. Extract relevant information that answers the user's question
+    3. Synthesize this into a clear, natural language response
+    4. NEVER show the raw markdown to the user unless specifically requested
+    """
+    try:
+        import requests
+        from markdownify import markdownify
+    except ImportError as exc:
+        return {
+            "error": f"Required package not installed: {exc.name}. "
+            "Install with: pip install 'docagent[cli]'",
+            "url": url,
+        }
+
+    try:
+        response = requests.get(
+            url,
+            timeout=timeout,
+            headers={"User-Agent": "Mozilla/5.0 (compatible; DeepAgents/1.0)"},
+        )
+        response.raise_for_status()
+
+        # Convert HTML content to markdown
+        markdown_content = markdownify(response.text)
+
+        return {
+            "url": str(response.url),
+            "markdown_content": markdown_content,
+            "status_code": response.status_code,
+            "content_length": len(markdown_content),
+        }
+    except requests.exceptions.RequestException as e:
+        return {"error": f"Fetch URL error: {e!s}", "url": url}