zjcode 0.0.1__py3-none-any.whl

deepagents_code/__init__.py

@@ -0,0 +1,42 @@
+"""Deep Agents Code - Interactive AI coding assistant."""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+from deepagents_code._debug import configure_debug_logging
+from deepagents_code._debug_buffer import install_log_buffer
+from deepagents_code._version import __version__
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+install_log_buffer(logging.getLogger(__name__))  # noqa: RUF067  # attach the always-on tail first so warnings from configure_debug_logging are captured
+configure_debug_logging(logging.getLogger(__name__))  # noqa: RUF067  # package logger must be configured before child modules emit logs; sets the final level over the buffer's INFO floor
+
+__all__ = [
+    "__version__",
+    "cli_main",  # noqa: F822  # resolved lazily by __getattr__
+]
+
+
+def __getattr__(name: str) -> Callable[[], None]:
+    """Lazy import for `cli_main` to avoid loading `main.py` at package import.
+
+    `main.py` pulls in `argparse`, signal handling, and other startup machinery
+    that isn't needed when submodules like `config` or `widgets` are
+    imported directly.
+
+    Returns:
+        The requested callable.
+
+    Raises:
+        AttributeError: If *name* is not a lazily-provided attribute.
+    """
+    if name == "cli_main":
+        from deepagents_code.main import cli_main
+
+        return cli_main
+    msg = f"module {__name__!r} has no attribute {name!r}"
+    raise AttributeError(msg)

deepagents_code/__main__.py

@@ -0,0 +1,6 @@
+"""Allow running the CLI as: `python -m deepagents_code`."""
+
+from deepagents_code.main import cli_main
+
+if __name__ == "__main__":
+    cli_main()

deepagents_code/_ask_user_types.py

@@ -0,0 +1,90 @@
+"""Lightweight types for the ask-user interrupt protocol.
+
+Extracted from `ask_user` so `textual_adapter` can import `AskUserRequest` at
+module level — and `app` can reference the types at type-check time — without
+pulling in the langchain middleware stack.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Literal, NotRequired
+
+from pydantic import Field
+from typing_extensions import TypedDict
+
+
+class Choice(TypedDict):
+    """A single choice option for a multiple choice question."""
+
+    value: Annotated[str, Field(description="The display label for this choice.")]
+
+
+class Question(TypedDict):
+    """A question to ask the user."""
+
+    question: Annotated[str, Field(description="The question text to display.")]
+
+    type: Annotated[
+        Literal["text", "multiple_choice"],
+        Field(
+            description=(
+                "Question type. 'text' for free-form input, 'multiple_choice' for "
+                "predefined options."
+            )
+        ),
+    ]
+
+    choices: NotRequired[
+        Annotated[
+            list[Choice],
+            Field(
+                description=(
+                    "Options for multiple_choice questions. An 'Other' free-form "
+                    "option is always appended automatically."
+                )
+            ),
+        ]
+    ]
+
+    required: NotRequired[
+        Annotated[
+            bool,
+            Field(
+                description="Whether the user must answer. Defaults to true if omitted."
+            ),
+        ]
+    ]
+
+
+class AskUserRequest(TypedDict):
+    """Request payload sent via interrupt when asking the user questions."""
+
+    type: Literal["ask_user"]
+    """Discriminator tag, always `'ask_user'`."""
+
+    questions: list[Question]
+    """Questions to present to the user."""
+
+    tool_call_id: str
+    """ID of the originating tool call, used to route the response back."""
+
+
+class AskUserAnswered(TypedDict):
+    """Widget result when the user submits answers."""
+
+    type: Literal["answered"]
+    """Discriminator tag, always `'answered'`."""
+
+    answers: list[str]
+    """User-provided answers, one per question."""
+
+
+class AskUserCancelled(TypedDict):
+    """Widget result when the user cancels the prompt."""
+
+    type: Literal["cancelled"]
+    """Discriminator tag, always `'cancelled'`."""
+
+
+AskUserWidgetResult = AskUserAnswered | AskUserCancelled
+"""Discriminated union for the ask_user widget Future result."""

deepagents_code/_cli_context.py

@@ -0,0 +1,96 @@
+"""Lightweight runtime context types for the CLI agent graph.
+
+Carries per-run overrides (model swap/params, approval mode) passed via
+`context=`. Extracted from `configurable_model` so hot-path modules (`app`,
+`textual_adapter`) can import `CLIContext` without pulling in the langchain
+middleware stack.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, TypedDict
+
+
+@dataclass
+class CLIContextSchema:
+    """Declared `context_schema` for the agent graph.
+
+    Registered via `context_schema=` when the graph is built, so LangGraph
+    coerces each run's `context=` payload into this dataclass — in-process,
+    `runtime.context` is a `CLIContextSchema` instance.
+
+    It exists alongside `CLIContext` (below) because the payload is shaped
+    differently on each side of the API boundary: in-process it is coerced to
+    this dataclass, but over the LangGraph API server (RemoteGraph) it is
+    serialized to JSON and arrives as a plain dict. Consumers
+    (`configurable_model._get_context`, `_should_interrupt_tool_call`)
+    therefore accept both shapes. `CLIContext` is the client-facing builder for
+    constructing that payload.
+
+    Fields mirror `CLIContext`; see its per-field docstrings for semantics.
+    """
+
+    model: str | None = None
+
+    model_params: dict[str, Any] = field(default_factory=dict)
+
+    auto_approve: bool = False
+
+    approval_mode_key: str | None = None
+
+    thread_id: str | None = None
+
+    blocked_goal_retry_context: str | None = None
+
+
+class CLIContext(TypedDict, total=False):
+    """Client-facing builder for the per-run graph context payload.
+
+    Callers populate this and pass it via `context=` to `astream`/`ainvoke`.
+    `ConfigurableModelMiddleware` and the `interrupt_on` `when` predicate read
+    it from `request.runtime.context`. In-process LangGraph coerces it into
+    `CLIContextSchema` (the registered `context_schema`); over the API it stays
+    a plain dict — which is why consumers handle both shapes.
+    """
+
+    model: str | None
+    """Model spec to swap at runtime (e.g. `'provider:model'`)."""
+
+    model_params: dict[str, Any]
+    """Invocation params (e.g. `temperature`, `max_tokens`) to merge
+    into `model_settings`."""
+
+    auto_approve: bool
+    """Whether gated tool calls should skip the human-approval interrupt.
+
+    Sourced from the client session (not graph state) so the model cannot
+    self-approve by writing state. The `interrupt_on` `when` predicate reads
+    this to suppress interrupts at the source when "approve always" is on,
+    avoiding the interrupt-then-auto-resolve round-trip.
+    """
+
+    approval_mode_key: str | None
+    """Store key for the live approval-mode control record.
+
+    The TUI updates this record when the user toggles approval mode mid-run.
+    The server-side interrupt predicate reads it from the LangGraph Store on
+    each gated tool call so auto-to-manual changes can take effect before the
+    current stream returns.
+    """
+
+    thread_id: str | None
+    """LangGraph thread ID for the active conversation.
+
+    Mirrors `config.configurable.thread_id` into runtime context for model-call
+    middleware that needs per-request session identity, including Fireworks
+    session-affinity headers.
+    """
+
+    blocked_goal_retry_context: str | None
+    """One-turn model context for retrying a previously blocked goal.
+
+    This is intentionally carried in runtime context instead of the user
+    message so it is not parsed as a file mention or checkpointed as human
+    input.
+    """

deepagents_code/_constants.py

@@ -0,0 +1,41 @@
+"""Lightweight shared constants for the app.
+
+This module is intentionally dependency-free (no third-party imports, no
+sibling-module imports) so any other module — including the startup-critical
+`main.py` and the heavy `agent.py` — can import from it without triggering a
+chain of expensive imports.
+"""
+
+from __future__ import annotations
+
+from typing import Final
+
+DEFAULT_AGENT_NAME: Final[str] = "agent"
+"""Default agent / assistant identifier when no `-a` flag is given."""
+
+FIREWORKS_PROVIDER_ID_PREFIX: Final[str] = "accounts/fireworks/"
+"""Prefix used to infer Fireworks from fully-qualified IDs."""
+
+FIREWORKS_MODEL_ID_PREFIXES: Final[tuple[str, ...]] = (
+    "accounts/fireworks/models/",
+    "accounts/fireworks/routers/",
+)
+"""Model and router ID prefixes used for stripping and classification."""
+
+MCP_REENABLED_PENDING_ERROR: Final[str] = "Re-enabled — press Ctrl+R to load."
+"""User-facing reconnect guidance shown for an MCP server that was optimistically
+re-enabled but whose agent has not yet reconnected.
+
+Set as `MCPServerInfo.error` by `app._apply_optimistic_disabled_state` (alongside
+`pending_reconnect=True`, which is what `/tools` actually keys off). Named here
+so the producer and the tests asserting the message share one literal.
+"""
+
+SYSTEM_MESSAGE_PREFIX: Final[str] = "[SYSTEM]"
+"""Prefix for synthetic human messages (e.g. interrupt cancellation notices).
+
+Such messages are written to the `messages` channel for the agent's benefit on
+resume but are not user-authored, so they are filtered out of both the rendered
+transcript and a thread's initial prompt. Shared here so the single producer
+(`textual_adapter`) and its consumers (`app`, `sessions`) agree on one literal.
+"""

deepagents_code/_debug.py

@@ -0,0 +1,148 @@
+"""Shared debug-logging configuration for runtime and file-based tracing.
+
+When the `DEEPAGENTS_CODE_DEBUG` environment variable is set, modules that handle
+streaming or remote communication can enable detailed file-based logging. This
+helper centralizes the setup so the env-var names, file path, log level, and
+format are defined in one place.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import sys
+from pathlib import Path
+
+from deepagents_code._env_vars import (
+    DEBUG,
+    DEBUG_FILE,
+    DEFAULT_DEBUG_FILE,
+    LOG_LEVEL,
+    is_env_truthy,
+)
+
+logger = logging.getLogger(__name__)
+
+_DEBUG_HANDLER_ATTR = "_deepagents_code_debug_handler"
+LOG_LEVELS = {
+    "DEBUG": logging.DEBUG,
+    "INFO": logging.INFO,
+    "WARNING": logging.WARNING,
+    "ERROR": logging.ERROR,
+    "CRITICAL": logging.CRITICAL,
+}
+"""Canonical level-name to `logging` level mapping.
+
+The single source of truth for level names and their numeric values, shared with
+the Debug Console's level filter so severity ordering is never re-derived from
+hardcoded integers.
+"""
+
+
+def resolve_log_level(*, debug_enabled: bool | None = None) -> int:
+    """Resolve the configured runtime logging level.
+
+    Args:
+        debug_enabled: Whether `DEEPAGENTS_CODE_DEBUG` is truthy. When omitted,
+            the current environment is checked.
+
+    Returns:
+        A standard `logging` level integer. Defaults to `DEBUG` when debug file
+        logging is enabled and `INFO` otherwise.
+    """
+    if debug_enabled is None:
+        debug_enabled = is_env_truthy(DEBUG)
+    fallback = logging.DEBUG if debug_enabled else logging.INFO
+    raw = os.environ.get(LOG_LEVEL)
+    if raw is None or not raw.strip():
+        return fallback
+    level = LOG_LEVELS.get(raw.strip().upper())
+    if level is not None:
+        return level
+    valid = ", ".join(LOG_LEVELS)
+    message = f"ignoring invalid {LOG_LEVEL}={raw!r}; expected one of {valid}"
+    # stderr for headless / pre-TUI visibility; the logger so it also lands in
+    # the always-on in-memory buffer and surfaces in the Debug Console (the
+    # buffer is installed before this runs; see __init__.py).
+    print(f"Warning: {message}", file=sys.stderr)  # noqa: T201
+    logger.warning("%s", message)
+    return fallback
+
+
+def configure_debug_logging(target: logging.Logger) -> None:
+    """Configure runtime log level and optional file logging for *target*.
+
+    Intended to be called once on the `deepagents_code` package logger; child
+    module loggers reach the same handlers via propagation, so individual modules
+    do not configure logging themselves.
+
+    `DEEPAGENTS_CODE_LOG_LEVEL` controls the package logger level independently of
+    file logging. If it is unset, `DEEPAGENTS_CODE_DEBUG=1` defaults to `DEBUG`;
+    otherwise the runtime level defaults to `INFO`.
+
+    When `DEEPAGENTS_CODE_DEBUG` is truthy, a file handler is attached. The log
+    file defaults to `DEFAULT_DEBUG_FILE` but can be overridden with
+    `DEEPAGENTS_CODE_DEBUG_FILE`. The handler appends (`mode='a'`) so logs are
+    preserved across separate process runs. Calling this again with the same
+    resolved path does not stack duplicate handlers: the existing tagged handler
+    is reused and its level re-applied. If the resolved path changes, the stale
+    handler is closed and replaced.
+
+    Args:
+        target: Logger to configure.
+    """
+    debug_enabled = is_env_truthy(DEBUG)
+    level = resolve_log_level(debug_enabled=debug_enabled)
+    target.setLevel(level)
+
+    if not debug_enabled:
+        return
+
+    debug_path = Path(os.environ.get(DEBUG_FILE, DEFAULT_DEBUG_FILE))
+    for existing in list(target.handlers):
+        if not (
+            isinstance(existing, logging.FileHandler)
+            and getattr(existing, _DEBUG_HANDLER_ATTR, False)
+        ):
+            continue
+        if Path(existing.baseFilename) == debug_path:
+            existing.setLevel(level)
+            return
+        # The debug path changed; drop the stale handler before re-attaching so
+        # we don't leak its file descriptor or fan logs out to two files.
+        target.removeHandler(existing)
+        existing.close()
+
+    try:
+        handler = logging.FileHandler(str(debug_path), mode="a")
+    except OSError as exc:
+        message = f"could not open debug log file {debug_path}: {exc}"
+        # stderr for headless / pre-TUI visibility; the logger so it also lands
+        # in the always-on in-memory buffer and surfaces in the Debug Console.
+        print(f"Warning: {message}", file=sys.stderr)  # noqa: T201
+        logger.warning("%s", message)
+        return
+    setattr(handler, _DEBUG_HANDLER_ATTR, True)
+    handler.setLevel(level)
+    handler.setFormatter(logging.Formatter("%(asctime)s %(name)s %(message)s"))
+    target.addHandler(handler)
+
+
+def installed_debug_log_path() -> Path | None:
+    """Return the path of the active debug log file, or `None` if not logging.
+
+    Reflects the file handler actually attached by `configure_debug_logging`,
+    not the current `DEEPAGENTS_CODE_DEBUG` env value. The two diverge when the
+    variable is set after import — e.g. via a project/global `.env` loaded during
+    settings bootstrap — in which case the variable reads truthy but no handler
+    was installed and no log file exists. Callers that surface "full error in
+    <path>" hints must use this rather than the env var to avoid pointing users
+    at a file that was never created.
+    """
+    package_logger = logging.getLogger(__package__ or "deepagents_code")
+    for handler in package_logger.handlers:
+        if isinstance(handler, logging.FileHandler) and getattr(
+            handler, _DEBUG_HANDLER_ATTR, False
+        ):
+            return Path(handler.baseFilename)
+    return None

deepagents_code/_debug_buffer.py

@@ -0,0 +1,204 @@
+r"""In-memory ring buffer of recent log records for the in-app Debug Console.
+
+A lightweight `logging.Handler` keeps the most recent structured log records in a
+bounded `deque` so the Debug Console (`Ctrl+\`) can show a live tail without
+requiring the opt-in file logging from `_debug.configure_debug_logging`. The
+handler is installed once on the `deepagents_code` package logger (see
+`__init__.py`); child module loggers reach it via propagation.
+
+Installation is negligible, and each emitted record only appends a structured
+record to a bounded `deque`, so the buffer is cheap enough to keep always on.
+"""
+
+from __future__ import annotations
+
+import itertools
+import logging
+import os
+from collections import deque
+from dataclasses import dataclass
+
+from deepagents_code._env_vars import LOG_LEVEL
+
+DEFAULT_CAPACITY = 1000
+"""Maximum number of records retained in the ring buffer."""
+
+_DATE_FORMAT = "%H:%M:%S"
+_FORMATTER = logging.Formatter(datefmt=_DATE_FORMAT)
+
+
+@dataclass(frozen=True, slots=True)
+class InMemoryLogRecord:
+    """Structured log record retained by the in-memory debug buffer."""
+
+    timestamp: str
+    level: str
+    levelno: int
+    logger: str
+    message: str
+
+    @property
+    def plain_line(self) -> str:
+        """The record in the legacy plain-text debug-console format."""
+        return f"{self.timestamp} {self.level} {self.logger} {self.message}"
+
+
+class InMemoryLogBuffer(logging.Handler):
+    """Logging handler retaining the most recent structured records in memory."""
+
+    def __init__(self, capacity: int = DEFAULT_CAPACITY) -> None:
+        """Create the handler with a bounded backing `deque`.
+
+        Args:
+            capacity: Maximum records to retain; oldest are dropped first.
+
+        Raises:
+            ValueError: If *capacity* is less than 1. A zero-capacity buffer
+                would silently discard every record while `total_emitted` kept
+                climbing, so it is rejected at the boundary.
+        """
+        if capacity < 1:
+            msg = f"capacity must be >= 1, got {capacity}"
+            raise ValueError(msg)
+        super().__init__()
+        self._records: deque[InMemoryLogRecord] = deque(maxlen=capacity)
+        self._total = 0
+
+    def emit(self, record: logging.LogRecord) -> None:
+        """Append the structured *record* to the ring buffer."""
+        self.acquire()
+        try:
+            self._records.append(self._make_record(record))
+            self._total += 1
+        except Exception:  # noqa: BLE001  # never let logging crash the app
+            self.handleError(record)
+        finally:
+            self.release()
+
+    @property
+    def total_emitted(self) -> int:
+        """Total records ever emitted (monotonic; survives buffer eviction)."""
+        self.acquire()
+        try:
+            return self._total
+        finally:
+            self.release()
+
+    def snapshot_records_since(self, index: int) -> tuple[list[InMemoryLogRecord], int]:
+        """Return retained structured records and the next absolute index.
+
+        Absolute indices are stable even as old records are evicted, so callers
+        can poll incrementally without re-reading records they already consumed.
+        Returning the records and the resume index together under the handler
+        lock prevents a concurrent append from being skipped between separate
+        reads.
+
+        Args:
+            index: Absolute emission index to start from.
+
+        Returns:
+            A tuple of the structured records from *index* onward that are still
+            retained, and the current total emitted count to resume from.
+        """
+        self.acquire()
+        try:
+            return self._records_since_unlocked(index), self._total
+        finally:
+            self.release()
+
+    def _records_since_unlocked(self, index: int) -> list[InMemoryLogRecord]:
+        """Return retained records from *index* while the handler lock is held."""
+        start_abs = self._total - len(self._records)
+        offset = index - start_abs
+        if offset <= 0:
+            return list(self._records)
+        if offset >= len(self._records):
+            return []
+        # islice avoids materializing the full deque just to slice off the tail.
+        return list(itertools.islice(self._records, offset, None))
+
+    @staticmethod
+    def _make_record(record: logging.LogRecord) -> InMemoryLogRecord:
+        """Convert a standard logging record into a structured debug record.
+
+        Returns:
+            Structured record for display and filtering.
+        """
+        message = record.getMessage()
+        if record.exc_info:
+            if not record.exc_text:
+                record.exc_text = _FORMATTER.formatException(record.exc_info)
+            if record.exc_text:
+                message = f"{message}\n{record.exc_text}"
+        if record.stack_info:
+            message = f"{message}\n{_FORMATTER.formatStack(record.stack_info)}"
+        return InMemoryLogRecord(
+            timestamp=_FORMATTER.formatTime(record, _DATE_FORMAT),
+            level=record.levelname,
+            levelno=record.levelno,
+            logger=record.name,
+            message=message,
+        )
+
+
+_buffer: InMemoryLogBuffer | None = None
+
+
+def install_log_buffer(
+    target: logging.Logger, capacity: int = DEFAULT_CAPACITY
+) -> InMemoryLogBuffer:
+    """Attach the in-memory buffer handler to *target* (idempotent).
+
+    Lowers *target*'s level to at most `INFO` so the console shows a useful tail
+    even when `DEEPAGENTS_CODE_DEBUG` is off; never raises the level. In
+    `__init__.py` this runs *before* `configure_debug_logging`, which then sets
+    the final level (honoring `DEEPAGENTS_CODE_DEBUG` and
+    `DEEPAGENTS_CODE_LOG_LEVEL`) over this `INFO` floor — so any startup warnings
+    `configure_debug_logging` emits are captured by the already-installed buffer.
+    On a fresh `NOTSET` logger the `NOTSET` branch forces `INFO` without
+    consulting `DEEPAGENTS_CODE_LOG_LEVEL`; the `> INFO and no env` branch only
+    matters on reconfiguration (e.g. an `importlib.reload`), where it preserves
+    an explicit `DEEPAGENTS_CODE_LOG_LEVEL` rather than clobbering it with `INFO`.
+
+    Lowering the level does not spill log output onto the terminal: because this
+    handler is present in the propagation chain, `Logger.callHandlers` finds a
+    handler (`found > 0`) and Python's `lastResort` stderr handler is never
+    consulted. The exception is an embedding process that attaches its own
+    `INFO`-or-lower handler to the root logger, which would then see the
+    propagated records.
+
+    Note: this runs as an import-time side effect (see `__init__.py`), so every
+    `import deepagents_code` attaches the handler and may lower the package
+    logger's level to `INFO` for the lifetime of the process.
+
+    Args:
+        target: Logger to attach the buffer to (the package logger).
+        capacity: Maximum records to retain.
+
+    Returns:
+        The installed (or already-installed) buffer handler.
+    """
+    global _buffer  # noqa: PLW0603  # module-level singleton accessor
+    for existing in target.handlers:
+        if isinstance(existing, InMemoryLogBuffer):
+            _buffer = existing
+            return existing
+
+    handler = InMemoryLogBuffer(capacity)
+    handler.setLevel(logging.DEBUG)
+    target.addHandler(handler)
+    if target.level == logging.NOTSET or (
+        target.level > logging.INFO and not os.environ.get(LOG_LEVEL)
+    ):
+        target.setLevel(logging.INFO)
+    _buffer = handler
+    return handler
+
+
+def get_log_buffer() -> InMemoryLogBuffer | None:
+    """Return the installed buffer handler.
+
+    Returns:
+        The installed buffer handler, or `None` if not yet installed.
+    """
+    return _buffer