docagent-cli 0.0.35__py3-none-any.whl

docagent_cli/offload.py

@@ -0,0 +1,371 @@
+"""Business logic for the /offload command.
+
+Extracts the core offload workflow from the UI layer so it can be
+tested independently of the Textual app.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING, Any
+
+from langchain_core.messages import get_buffer_string
+from langchain_core.messages.utils import count_tokens_approximately
+
+from docagent_cli.config import create_model
+from docagent_cli.textual_adapter import format_token_count
+
+if TYPE_CHECKING:
+    from deepagents.backends.protocol import BackendProtocol
+    from deepagents.middleware.summarization import (
+        SummarizationEvent,
+        SummarizationMiddleware,
+    )
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Result types
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class OffloadResult:
+    """Successful offload result."""
+
+    new_event: SummarizationEvent
+    """The summarization event to write into agent state."""
+
+    messages_offloaded: int
+    """Number of older messages that were offloaded."""
+
+    messages_kept: int
+    """Number of recent messages retained in context."""
+
+    tokens_before: int
+    """Approximate token count of the conversation before offloading."""
+
+    tokens_after: int
+    """Approximate token count of the conversation after offloading."""
+
+    pct_decrease: int
+    """Percentage decrease in token usage."""
+
+    offload_warning: str | None
+    """Non-`None` when the backend write failed (non-fatal)."""
+
+
+@dataclass(frozen=True)
+class OffloadThresholdNotMet:
+    """Offload was a no-op — conversation is within the retention budget."""
+
+    conversation_tokens: int
+    """Approximate token count of the conversation messages alone."""
+
+    total_context_tokens: int
+    """Total context token count including system overhead, or `0` when no
+    token tracker is available."""
+
+    context_limit: int | None
+    """Model context window limit, if available."""
+
+    budget_str: str
+    """Human-readable retention budget (e.g. "20.0K tokens")."""
+
+
+class OffloadModelError(Exception):
+    """Raised when the model cannot be created for offloading."""
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def format_offload_limit(
+    keep: tuple[str, int | float], context_limit: int | None
+) -> str:
+    """Format offload retention settings into a human-readable limit string.
+
+    Args:
+        keep: Retention policy tuple `(type, value)` from summarization
+            defaults, where `type` is one of `"messages"`, `"tokens"`, or
+            `"fraction"`.
+        context_limit: Model context limit when available.
+
+    Returns:
+        A short display string describing the offload retention limit.
+    """
+    keep_type, keep_value = keep
+
+    if keep_type == "messages":
+        count = int(keep_value)
+        noun = "message" if count == 1 else "messages"
+        return f"last {count} {noun}"
+
+    if keep_type == "tokens":
+        return f"{format_token_count(int(keep_value))} tokens"
+
+    if keep_type == "fraction":
+        percent = float(keep_value) * 100
+        if context_limit is not None:
+            token_limit = max(1, int(context_limit * float(keep_value)))
+            return f"{format_token_count(token_limit)} tokens"
+        return f"{percent:.0f}% of context window"
+
+    return "current retention threshold"
+
+
+async def offload_messages_to_backend(
+    messages: list[Any],
+    middleware: SummarizationMiddleware,
+    *,
+    thread_id: str,
+    backend: BackendProtocol,
+) -> str | None:
+    """Write messages to backend storage before offloading.
+
+    Appends messages as a timestamped markdown section to the conversation
+    history file, matching the `SummarizationMiddleware` offload pattern.
+
+    Filters out prior summary messages using the middleware's
+    `_filter_summary_messages` to avoid storing summaries-of-summaries.
+
+    Args:
+        messages: Messages to offload.
+        middleware: `SummarizationMiddleware` instance for filtering.
+        thread_id: Thread identifier used to derive the storage path.
+        backend: Backend to persist conversation history to.
+
+    Returns:
+        File path where history was stored, `""` (empty string) if there were no
+            non-summary messages to offload (not an error), or `None` if the
+            write failed.
+    """
+    path = f"/conversation_history/{thread_id}.md"
+
+    # Exclude prior summaries so the offloaded history contains only
+    # original messages
+    filtered = middleware._filter_summary_messages(messages)
+    if not filtered:
+        return ""
+
+    timestamp = datetime.now(UTC).isoformat()
+    buf = get_buffer_string(filtered)
+    new_section = f"## Offloaded at {timestamp}\n\n{buf}\n\n"
+
+    existing_content = ""
+    try:
+        responses = await backend.adownload_files([path])
+        resp = responses[0] if responses else None
+        if resp and resp.content is not None and resp.error is None:
+            existing_content = resp.content.decode("utf-8")
+    except Exception as exc:  # abort write on read failure
+        logger.warning(
+            "Failed to read existing history at %s; aborting offload to "
+            "avoid overwriting prior history: %s",
+            path,
+            exc,
+            exc_info=True,
+        )
+        return None
+
+    combined = existing_content + new_section
+
+    try:
+        result = (
+            await backend.aedit(path, existing_content, combined)
+            if existing_content
+            else await backend.awrite(path, combined)
+        )
+        if result is None or result.error:
+            error_detail = result.error if result else "backend returned None"
+            logger.warning(
+                "Failed to offload conversation history to %s: %s",
+                path,
+                error_detail,
+            )
+            return None
+    except Exception as exc:  # defensive: surface write failures gracefully
+        logger.warning(
+            "Exception offloading conversation history to %s: %s",
+            path,
+            exc,
+            exc_info=True,
+        )
+        return None
+
+    logger.debug("Offloaded %d messages to %s", len(filtered), path)
+    return path
+
+
+# ---------------------------------------------------------------------------
+# Core offload workflow
+# ---------------------------------------------------------------------------
+
+
+async def perform_offload(
+    *,
+    messages: list[Any],
+    prior_event: SummarizationEvent | None,
+    thread_id: str,
+    model_spec: str,
+    profile_overrides: dict[str, Any] | None,
+    context_limit: int | None,
+    total_context_tokens: int,
+    backend: BackendProtocol | None,
+) -> OffloadResult | OffloadThresholdNotMet:
+    """Execute the offload workflow: summarize old messages and free context.
+
+    Args:
+        messages: Current conversation messages from agent state.
+        prior_event: Existing `_summarization_event` if any.
+        thread_id: Thread identifier for backend storage.
+        model_spec: Model specification string (e.g. "openai:gpt-4").
+        profile_overrides: Optional profile overrides from CLI flags.
+        context_limit: Model context limit from settings.
+        total_context_tokens: Current total context token count, or `0` when
+            no token tracker is available.
+        backend: Backend for persisting offloaded history.
+
+    Returns:
+        `OffloadResult` on success, `OffloadThresholdNotMet` when the
+            conversation is within the retention budget.
+
+    Raises:
+        OffloadModelError: If the model cannot be created.
+    """
+    from deepagents.middleware.summarization import (
+        SummarizationMiddleware,
+        compute_summarization_defaults,
+    )
+
+    try:
+        result = create_model(model_spec, profile_overrides=profile_overrides)
+        model = result.model
+    except Exception as exc:
+        msg = f"Offload requires a working model configuration: {exc}"
+        raise OffloadModelError(msg) from exc
+
+    # Patch context limit into model profile when it differs from the native
+    # value (e.g. set via --profile-override or runtime config).
+    if context_limit is not None:
+        profile = getattr(model, "profile", None)
+        native = profile.get("max_input_tokens") if isinstance(profile, dict) else None
+        if native != context_limit:
+            merged = (
+                {**profile, "max_input_tokens": context_limit}
+                if isinstance(profile, dict)
+                else {"max_input_tokens": context_limit}
+            )
+            try:
+                model.profile = merged  # type: ignore[union-attr]
+            except (AttributeError, TypeError, ValueError):
+                logger.warning(
+                    "Could not patch context limit (%d) into model profile; "
+                    "offload budget will use the model's native context window",
+                    context_limit,
+                    exc_info=True,
+                )
+
+    defaults = compute_summarization_defaults(model)
+    offload_backend = backend
+    if offload_backend is None:
+        from deepagents.backends.filesystem import FilesystemBackend
+
+        offload_backend = FilesystemBackend()
+        logger.info("Using local FilesystemBackend for offload")
+
+    middleware = SummarizationMiddleware(
+        model=model,
+        backend=offload_backend,
+        keep=defaults["keep"],
+        trim_tokens_to_summarize=None,
+    )
+
+    # Rebuild the message list the model would see, accounting for
+    # any prior offload
+    effective = middleware._apply_event_to_messages(messages, prior_event)
+    cutoff = middleware._determine_cutoff_index(effective)
+    budget_str = format_offload_limit(defaults["keep"], context_limit)
+
+    if cutoff == 0:
+        return OffloadThresholdNotMet(
+            conversation_tokens=count_tokens_approximately(effective),
+            total_context_tokens=total_context_tokens,
+            context_limit=context_limit,
+            budget_str=budget_str,
+        )
+
+    to_summarize, to_keep = middleware._partition_messages(effective, cutoff)
+
+    tokens_summarized = count_tokens_approximately(to_summarize)
+    tokens_kept = count_tokens_approximately(to_keep)
+    tokens_before = tokens_summarized + tokens_kept
+
+    # Generate summary first so no side effects occur if the LLM fails
+    summary = await middleware._acreate_summary(to_summarize)
+
+    backend_path = await offload_messages_to_backend(
+        to_summarize,
+        middleware,
+        thread_id=thread_id,
+        backend=offload_backend,
+    )
+    offload_warning: str | None = None
+    if backend_path is None:
+        offload_warning = (
+            "Warning: conversation history could not be saved to "
+            "storage. Older messages will not be recoverable. "
+            "Check logs for details."
+        )
+        logger.error(
+            "Backend write failed for thread %s; offloading will proceed "
+            "but messages are not recoverable",
+            thread_id,
+        )
+    file_path = backend_path or None
+
+    summary_msg = middleware._build_new_messages_with_path(summary, file_path)[0]
+
+    # Append token savings note so the model is aware of how much context
+    # was reclaimed.
+    tokens_summary = count_tokens_approximately([summary_msg])
+    tokens_after = tokens_summary + tokens_kept
+    pct = (
+        round((tokens_before - tokens_after) / tokens_before * 100)
+        if tokens_before > 0
+        else 0
+    )
+    summarized_before = format_token_count(tokens_summarized)
+    summarized_after = format_token_count(tokens_summary)
+    savings_note = (
+        f"\n\n{len(to_summarize)} messages were offloaded "
+        f"({summarized_before} \u2192 {summarized_after} tokens). "
+        f"Total context: {format_token_count(tokens_before)} \u2192 "
+        f"{format_token_count(tokens_after)} tokens "
+        f"({pct}% decrease), "
+        f"{len(to_keep)} messages unchanged."
+    )
+    summary_msg.content += savings_note
+
+    state_cutoff = middleware._compute_state_cutoff(prior_event, cutoff)
+
+    new_event: SummarizationEvent = {
+        "cutoff_index": state_cutoff,
+        "summary_message": summary_msg,  # ty: ignore[invalid-argument-type]
+        "file_path": file_path,
+    }
+
+    return OffloadResult(
+        new_event=new_event,
+        messages_offloaded=len(to_summarize),
+        messages_kept=len(to_keep),
+        tokens_before=tokens_before,
+        tokens_after=tokens_after,
+        pct_decrease=pct,
+        offload_warning=offload_warning,
+    )

docagent_cli/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()

docagent_cli/project_utils.py

@@ -0,0 +1,188 @@
+"""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 docagent_cli._env_vars import SERVER_ENV_PREFIX
+
+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 CLI 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 `.docagent/skills` directory, if any."""
+        if self.project_root is None:
+            return None
+        return self.project_root / ".docagent" / "skills"
+
+    def project_agents_dir(self) -> Path | None:
+        """Return the project `.docagent/agents` directory, if any."""
+        if self.project_root is None:
+            return None
+        return self.project_root / ".docagent" / "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 directory.
+
+    Walks up the directory tree from start_path (or cwd) looking for a .git
+    directory, which indicates the project root.
+
+    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()
+
+    # Walk up the directory tree
+    for parent in [current, *list(current.parents)]:
+        git_dir = parent / ".git"
+        if git_dir.exists():
+            return parent
+
+    return None
+
+
+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/.docagent/AGENTS.md
+    2. project_root/AGENTS.md
+
+    Both files will be loaded and combined if both exist.
+
+    Args:
+        project_root: Path to the project root directory.
+
+    Returns:
+        Existing AGENTS.md paths.
+
+            Empty if neither file exists, one entry if only one is present, or
+            two entries if both locations have the file.
+    """
+    candidates = [
+        project_root / ".docagent" / "AGENTS.md",
+        project_root / "AGENTS.md",
+    ]
+    paths: list[Path] = []
+    for candidate in candidates:
+        try:
+            if candidate.exists():
+                paths.append(candidate)
+        except OSError:
+            pass
+    return paths