zjcode 0.0.1__py3-none-any.whl

deepagents_code/_session_stats.py

@@ -0,0 +1,235 @@
+"""Lightweight session statistics, token formatting, and usage-table rendering.
+
+Holds `SessionStats`/`ModelStats`, the `format_token_count` formatter, and
+`print_usage_table` (which imports `rich.table` lazily). The module is
+intentionally kept free of heavy top-level dependencies (no pydantic, no
+config, no widget imports) so that `app.py` can import `SessionStats` and
+`format_token_count` at module level without pulling in the full
+`textual_adapter` dependency tree.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Literal
+
+from deepagents_code.formatting import format_duration
+
+if TYPE_CHECKING:
+    from rich.console import Console
+
+SpinnerStatus = (
+    Literal[
+        "Thinking",
+        "Offloading",
+        "Loading thread",
+        "Drafting acceptance criteria",
+    ]
+    | None
+)
+"""Valid spinner display states, or `None` to hide."""
+
+
+@dataclass
+class ModelStats:
+    """Token stats for a single model within a session."""
+
+    request_count: int = 0
+    """Number of LLM API requests made to this model."""
+
+    input_tokens: int = 0
+    """Cumulative input tokens sent to this model."""
+
+    output_tokens: int = 0
+    """Cumulative output tokens received from this model."""
+
+    provider: str = ""
+    """Provider that served this model (e.g. `openai`), or `""` when unknown."""
+
+    model_name: str = ""
+    """Model name displayed in usage output."""
+
+
+ModelStatsKey = tuple[str, str]
+"""Per-model dict key: the `(provider, model_name)` pair.
+
+Pairing the provider with the model name keeps the same model served by
+different providers (e.g. `gpt-5.5` via `openai` vs `azure`) in separate rows
+instead of collapsing them. The key is always built from the same values stored
+on the corresponding `ModelStats`, so key and fields never diverge.
+"""
+
+
+@dataclass
+class SessionStats:
+    """Stats accumulated over a single agent turn (or full session)."""
+
+    request_count: int = 0
+    """Total LLM API requests made.
+
+    Each chunk with `usage_metadata` counts as one completed request.
+    """
+
+    input_tokens: int = 0
+    """Cumulative input tokens across all LLM requests."""
+
+    output_tokens: int = 0
+    """Cumulative output tokens across all LLM requests."""
+
+    wall_time_seconds: float = 0.0
+    """Wall-clock duration from stream start to end."""
+
+    per_model: dict[ModelStatsKey, ModelStats] = field(default_factory=dict)
+    """Per-model breakdown keyed by `(provider, model_name)`.
+
+    Populated only when `record_request` receives a non-empty `model_name`. Empty
+    dict means no named-model requests were recorded; `print_usage_table` omits
+    the model table in that case and shows only the wall-time line (if applicable).
+    """
+
+    def record_request(
+        self,
+        model_name: str,
+        input_toks: int,
+        output_toks: int,
+        provider: str = "",
+    ) -> None:
+        """Accumulate token counts for one completed LLM request.
+
+        Updates both the session totals and the per-model breakdown.
+
+        Args:
+            model_name: The model that served this request. Combined with
+                `provider` to form the per-model key. Pass an empty string to
+                skip the per-model breakdown for this request.
+            input_toks: Input tokens for this request.
+            output_toks: Output tokens for this request.
+            provider: Provider that served the model (e.g. `openai`). Combined
+                with `model_name` to form the per-model key, so the same model
+                served by different providers is tracked separately.
+        """
+        self.request_count += 1
+        self.input_tokens += input_toks
+        self.output_tokens += output_toks
+        if model_name:
+            key = (provider, model_name)
+            entry = self.per_model.setdefault(
+                key,
+                ModelStats(provider=provider, model_name=model_name),
+            )
+            entry.request_count += 1
+            entry.input_tokens += input_toks
+            entry.output_tokens += output_toks
+
+    def merge(self, other: SessionStats) -> None:
+        """Merge another `SessionStats` into this one (mutates *self*).
+
+        Used to accumulate per-turn stats into a session-level total.
+
+        Args:
+            other: The stats to fold in.
+        """
+        self.request_count += other.request_count
+        self.input_tokens += other.input_tokens
+        self.output_tokens += other.output_tokens
+        self.wall_time_seconds += other.wall_time_seconds
+        for key, ms in other.per_model.items():
+            entry = self.per_model.setdefault(
+                key,
+                ModelStats(provider=ms.provider, model_name=ms.model_name),
+            )
+            entry.request_count += ms.request_count
+            entry.input_tokens += ms.input_tokens
+            entry.output_tokens += ms.output_tokens
+
+
+def format_token_count(count: int) -> str:
+    """Format a token count into a human-readable short string.
+
+    Args:
+        count: Number of tokens.
+
+    Returns:
+        Formatted string like `'12.5K'`, `'1.2M'`, or `'500'`.
+    """
+    if count >= 1_000_000:  # noqa: PLR2004
+        return f"{count / 1_000_000:.1f}M"
+    if count >= 1000:  # noqa: PLR2004
+        return f"{count / 1000:.1f}K"
+    return str(count)
+
+
+def print_usage_table(
+    stats: SessionStats,
+    wall_time: float,
+    console: Console,
+) -> None:
+    """Print a model-usage stats table to a Rich console.
+
+    Each row shows the serving provider alongside the model name. When the
+    session spans multiple models each gets its own row with a totals row
+    appended; single-model sessions show one row.
+
+    Args:
+        stats: Cumulative session stats.
+        wall_time: Total wall-clock time in seconds.
+        console: Rich console for output.
+    """
+    from rich.table import Table
+
+    has_time = wall_time >= 0.1  # noqa: PLR2004
+    if not (stats.request_count or stats.input_tokens or has_time):
+        return
+
+    if stats.per_model:
+        multi_model = len(stats.per_model) > 1
+
+        table = Table(
+            show_header=True,
+            header_style="bold",
+            box=None,
+            padding=(0, 2, 0, 0),
+            show_edge=False,
+        )
+        table.add_column("Provider", style="dim")
+        table.add_column("Model", style="dim")
+        table.add_column("Reqs", justify="right", style="dim")
+        table.add_column("InputTok", justify="right", style="dim")
+        table.add_column("OutputTok", justify="right", style="dim")
+
+        if multi_model:
+            for ms in stats.per_model.values():
+                table.add_row(
+                    ms.provider,
+                    ms.model_name,
+                    str(ms.request_count),
+                    format_token_count(ms.input_tokens),
+                    format_token_count(ms.output_tokens),
+                )
+            table.add_row(
+                "",
+                "Total",
+                str(stats.request_count),
+                format_token_count(stats.input_tokens),
+                format_token_count(stats.output_tokens),
+            )
+        else:
+            ms = next(iter(stats.per_model.values()))
+            table.add_row(
+                ms.provider,
+                ms.model_name,
+                str(stats.request_count),
+                format_token_count(stats.input_tokens),
+                format_token_count(stats.output_tokens),
+            )
+
+        console.print()
+        console.print("[bold]Usage Stats[/bold]")
+        console.print(table)
+    if has_time:
+        console.print()
+        console.print(
+            f"Agent active  {format_duration(wall_time)}",
+            style="dim",
+            highlight=False,
+        )

deepagents_code/_startup_error.py

@@ -0,0 +1,45 @@
+"""Stderr marker emission used by the langgraph server graph entry point.
+
+Lives in its own module so unit tests can exercise the marker contract
+without triggering `server_graph.make_graph()` at import time.
+"""
+
+from __future__ import annotations
+
+import logging
+import sys
+import traceback
+
+logger = logging.getLogger(__name__)
+
+STARTUP_ERROR_MARKER = "DEEPAGENTS_STARTUP_ERROR:"
+"""Stderr marker the parent app scans for in `server._extract_startup_error_marker`
+to upgrade an opaque "Server process exited with code N" into a one-line summary.
+Format is `{STARTUP_ERROR_MARKER}{single-line message}`."""
+
+
+def emit_startup_failure(exc: BaseException) -> None:
+    """Report a server graph startup failure to the parent app process.
+
+    Emits two stderr outputs: the full traceback for logs/debugging, then a
+    single-line `{STARTUP_ERROR_MARKER}{type}: {summary}` line that
+    `server._extract_startup_error_marker` parses to upgrade an opaque
+    "Server process exited with code N" into an actionable summary.
+
+    Args:
+        exc: The exception raised during graph initialization.
+    """
+    logger.critical("Failed to initialize server graph", exc_info=exc)
+    print(  # noqa: T201  # stderr fallback — logger may not reach parent process
+        f"Failed to initialize server graph: {exc}\n{traceback.format_exc()}",
+        file=sys.stderr,
+    )
+    # Marker contract is single-line; guard against multi-line/empty `str(exc)`
+    # and include the type so e.g. `ValueError` and `RuntimeError` are
+    # distinguishable in the parent's truncated summary.
+    exc_lines = str(exc).splitlines()
+    summary = exc_lines[0] if exc_lines else "<no message>"
+    print(  # noqa: T201
+        f"{STARTUP_ERROR_MARKER}{type(exc).__name__}: {summary}",
+        file=sys.stderr,
+    )

deepagents_code/_testing_models.py

@@ -0,0 +1,305 @@
+"""Internal fake chat models for local integration tests.
+
+The tool-binding base these build on (`_fake_models._ToolBindingFakeModel`) is
+factored out into a use-neutral module so the `dcode tools list` enumeration
+path can reuse it without importing this test-named module.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from langchain_core.messages import AIMessage, BaseMessage
+from langchain_core.outputs import ChatGeneration, ChatResult
+
+from deepagents_code._fake_models import _ToolBindingFakeModel
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from langchain_core.callbacks import CallbackManagerForLLMRun
+
+
+# Prompt markers that drive `ToolCallingIntegrationChatModel`. Each marker is the
+# full token (including the trailing `=`); the file path follows on the same line,
+# e.g. `DCA_TEST_WRITE_FILE=/tmp/out.txt`. These are the single source of truth
+# shared with the integration tests, so the model and tests cannot drift apart.
+DCA_TEST_WRITE_FILE_MARKER = "DCA_TEST_WRITE_FILE="
+DCA_TEST_DELEGATE_WRITE_MARKER = "DCA_TEST_DELEGATE_WRITE="
+DCA_SUBAGENT_WRITE_FILE_MARKER = "DCA_SUBAGENT_WRITE_FILE="
+
+# Distinct file contents per write path, so a test asserting on file content can
+# prove which branch executed — in particular that subagent mode delegated through
+# the `task` tool rather than writing directly.
+TOP_LEVEL_WRITE_CONTENT = "auto-approved"
+SUBAGENT_WRITE_CONTENT = "auto-approved-subagent"
+
+
+class DeterministicIntegrationChatModel(_ToolBindingFakeModel):
+    """Deterministic chat model for integration tests.
+
+    This subclasses `_ToolBindingFakeModel` (itself a `GenericFakeChatModel`) so
+    the implementation stays aligned with the core fake-chat-model test surface,
+    while overriding generation to remain prompt-driven and restart-safe for real
+    CLI server integration tests.
+
+    Why the existing `langchain_core` fakes cannot be reused here:
+
+    1. Every core fake (`GenericFakeChatModel`, `FakeListChatModel`,
+        `FakeMessagesListChatModel`) pops from an iterator or cycles an index —
+        the actual prompt is ignored. App integration tests start and stop the
+        server process, which resets in-memory state. An iterator-based model
+        either raises `StopIteration` or replays from the beginning after a
+        restart, producing wrong or missing responses. This model derives output
+        solely from the prompt text, so identical input always produces
+        identical output regardless of process lifecycle.
+
+    2. The agent runtime calls `model.bind_tools(schemas)` during
+        initialization. A bare `GenericFakeChatModel` inherits
+        `BaseChatModel.bind_tools`, which raises `NotImplementedError` in any
+        agent-loop context. The inherited `_ToolBindingFakeModel` supplies a
+        no-op passthrough.
+
+    3. The app server reads `model.profile` for capability negotiation (e.g.
+        `tool_calling`, `max_input_tokens`). A bare fake's `profile` is `None`,
+        causing silent misconfiguration at runtime. The inherited
+        `_ToolBindingFakeModel` supplies a minimal profile.
+
+    Additionally, the compact middleware issues summarization prompts mid-
+    conversation. A list-based model cannot distinguish these from normal user
+    turns without pre-knowledge of exact call ordering, whereas this model
+    detects summary requests by inspecting the prompt content.
+    """
+
+    model: str = "fake"
+    # `messages`, `profile`, and the `bind_tools` passthrough are inherited from
+    # `_ToolBindingFakeModel`; this model adds only prompt-driven generation.
+
+    def _generate(
+        self,
+        messages: list[BaseMessage],
+        stop: list[str] | None = None,  # noqa: ARG002
+        run_manager: CallbackManagerForLLMRun | None = None,  # noqa: ARG002
+        **kwargs: Any,  # noqa: ARG002
+    ) -> ChatResult:
+        """Produce a deterministic reply derived from the prompt text.
+
+        Returns:
+            A single-message `ChatResult` with deterministic content.
+        """
+        prompt = "\n".join(
+            text
+            for message in messages
+            if (text := self._stringify_message(message)).strip()
+        )
+        if self._looks_like_summary_request(prompt):
+            content = "integration summary"
+        else:
+            excerpt = " ".join(prompt.split()[-18:])
+            if excerpt:
+                content = f"integration reply: {excerpt}"
+            else:
+                content = "integration reply"
+
+        return ChatResult(
+            generations=[ChatGeneration(message=AIMessage(content=content))]
+        )
+
+    @property
+    def _llm_type(self) -> str:
+        """LangChain model type identifier."""
+        return "deterministic-integration"
+
+    @staticmethod
+    def _stringify_message(message: BaseMessage) -> str:
+        """Flatten message content into plain text for deterministic responses.
+
+        Returns:
+            Plain-text content extracted from the message.
+        """
+        content = message.content
+        if isinstance(content, str):
+            return content
+        if isinstance(content, list):
+            parts: list[str] = []
+            for block in content:
+                if isinstance(block, str):
+                    parts.append(block)
+                elif isinstance(block, dict) and block.get("type") == "text":
+                    text = block.get("text")
+                    if isinstance(text, str):
+                        parts.append(text)
+            return " ".join(parts)
+        return str(content)
+
+    @staticmethod
+    def _looks_like_summary_request(prompt: str) -> bool:
+        """Detect the middleware's summary-generation prompt.
+
+        Returns:
+            `True` when the prompt appears to be a summarization request.
+        """
+        lowered = prompt.lower()
+        return (
+            "messages to summarize" in lowered
+            or "condense the following conversation" in lowered
+            or "<summary>" in lowered
+        )
+
+
+def _extract_marker_path(prompt: str, marker: str) -> str:
+    """Extract the file path that follows a prompt marker on the same line.
+
+    Args:
+        prompt: The flattened prompt text.
+        marker: The marker token (including its trailing `=`) to locate.
+
+    Returns:
+        The stripped file path immediately following the marker.
+
+    Raises:
+        ValueError: If the marker is present but not followed by a path, so a
+            malformed test prompt fails loudly here instead of silently
+            degrading to a `"done"` reply or raising an opaque `IndexError`.
+    """
+    _, _, tail = prompt.partition(marker)
+    lines = tail.splitlines()
+    file_path = lines[0].strip() if lines else ""
+    if not file_path:
+        msg = (
+            f"Test model saw marker {marker!r} but found no file path after it; "
+            f"check the integration-test prompt construction."
+        )
+        raise ValueError(msg)
+    return file_path
+
+
+def _tool_call_result(name: str, args: dict[str, Any], call_id: str) -> ChatResult:
+    """Build a single-tool-call `ChatResult`.
+
+    Returns:
+        A `ChatResult` wrapping an `AIMessage` with exactly one tool call.
+    """
+    return ChatResult(
+        generations=[
+            ChatGeneration(
+                message=AIMessage(
+                    content="",
+                    tool_calls=[
+                        {
+                            "name": name,
+                            "args": args,
+                            "id": call_id,
+                            "type": "tool_call",
+                        }
+                    ],
+                )
+            )
+        ]
+    )
+
+
+class ToolCallingIntegrationChatModel(DeterministicIntegrationChatModel):
+    """Deterministic tool-calling model for auto-approve integration tests.
+
+    Generation is driven entirely by prompt markers (the module-level `DCA_*`
+    constants), so output is restart-safe and independent of call ordering — the
+    same rationale as the parent `DeterministicIntegrationChatModel`:
+
+    - `DCA_TEST_WRITE_FILE=<path>` emits a top-level `write_file` call.
+    - `DCA_TEST_DELEGATE_WRITE=<path>` emits a `task` call delegating to the
+      `general-purpose` subagent, whose prompt then carries
+      `DCA_SUBAGENT_WRITE_FILE=<path>` to trigger the subagent's `write_file`.
+    - `DCA_SUBAGENT_WRITE_FILE=<path>` emits the subagent's `write_file` call.
+
+    Each marker fires only on the agent's first turn (no prior `ToolMessage`),
+    so once the tool result returns the model replies with a plain `"done"` and
+    the agent loop terminates instead of re-issuing the tool call.
+    """
+
+    # Only `_generate` is overridden; the inherited `_stream` would bypass this
+    # marker dispatch entirely, so streaming must be disabled.
+    disable_streaming: bool = True
+
+    def _generate(
+        self,
+        messages: list[BaseMessage],
+        stop: list[str] | None = None,  # noqa: ARG002
+        run_manager: CallbackManagerForLLMRun | None = None,  # noqa: ARG002
+        **kwargs: Any,  # noqa: ARG002
+    ) -> ChatResult:
+        """Emit a deterministic tool call (or terminal reply) from prompt markers.
+
+        The `has_tool_result` guard ensures each marker fires only on the
+        agent's first turn; once a `ToolMessage` is present the model returns
+        `"done"` so the agent loop terminates.
+
+        A recognized marker with no file path raises `ValueError` (via
+        `_extract_marker_path`) rather than degrading to `"done"`.
+
+        Returns:
+            A single-message `ChatResult`: an `AIMessage` carrying a `task` or
+            `write_file` tool call when a marker matches and no tool result is
+            present yet, otherwise a plain `"done"` reply.
+        """
+        prompt = "\n".join(
+            text
+            for message in messages
+            if (text := self._stringify_message(message)).strip()
+        )
+        has_tool_result = any(message.type == "tool" for message in messages)
+        if not has_tool_result:
+            for marker, build_tool_call in self._marker_dispatch():
+                if marker in prompt:
+                    name, args, call_id = build_tool_call(
+                        _extract_marker_path(prompt, marker)
+                    )
+                    return _tool_call_result(name, args, call_id)
+
+        return ChatResult(
+            generations=[ChatGeneration(message=AIMessage(content="done"))]
+        )
+
+    @staticmethod
+    def _marker_dispatch() -> tuple[
+        tuple[str, Callable[[str], tuple[str, dict[str, Any], str]]], ...
+    ]:
+        """Return ordered `(marker, tool-call builder)` pairs.
+
+        The delegate marker is checked before the plain write markers because
+        its emitted `task` description embeds `DCA_SUBAGENT_WRITE_FILE=`; the
+        first marker found in the prompt wins.
+
+        Returns:
+            Marker-to-builder pairs in precedence order. Each builder maps an
+            extracted file path to a `(tool_name, args, call_id)` triple.
+        """
+        return (
+            (
+                DCA_TEST_DELEGATE_WRITE_MARKER,
+                lambda path: (
+                    "task",
+                    {
+                        "description": f"{DCA_SUBAGENT_WRITE_FILE_MARKER}{path}",
+                        "subagent_type": "general-purpose",
+                    },
+                    "call_task",
+                ),
+            ),
+            (
+                DCA_SUBAGENT_WRITE_FILE_MARKER,
+                lambda path: (
+                    "write_file",
+                    {"file_path": path, "content": SUBAGENT_WRITE_CONTENT},
+                    "call_write_file",
+                ),
+            ),
+            (
+                DCA_TEST_WRITE_FILE_MARKER,
+                lambda path: (
+                    "write_file",
+                    {"file_path": path, "content": TOP_LEVEL_WRITE_CONTENT},
+                    "call_write_file",
+                ),
+            ),
+        )