dreadnode 2.0.13__tar.gz → 2.0.14__tar.gz

{dreadnode-2.0.13 → dreadnode-2.0.14}/.gitignore

@@ -215,3 +215,7 @@ __marimo__/
 # Streamlit
 .streamlit/secrets.toml
 .claude/
+
+# Local experiment notebooks
+examples/notebooks/cricket/
+examples/notebooks/llama-scout/

{dreadnode-2.0.13 → dreadnode-2.0.14}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dreadnode
-Version: 2.0.13
+Version: 2.0.14
 Summary: Dreadnode SDK
 Project-URL: Homepage, https://dreadnode.io
 Project-URL: Documentation, https://docs.dreadnode.io
@@ -384,9 +384,9 @@ uv sync --all-extras
 
 ## Documentation
 
-- **[Installation Guide](https://docs.dreadnode.io/strikes/install)** - Setup options
-- **[Introduction](https://docs.dreadnode.io/strikes/intro)** - Getting started guide
-- **[API Reference](https://docs.dreadnode.io/strikes/api)** - Complete API documentation
+- **[Getting started](https://docs.dreadnode.io/getting-started/overview/)** - Install, authenticate, first run
+- **[Quickstart](https://docs.dreadnode.io/getting-started/quickstart/)** - End-to-end walkthrough
+- **[SDK reference](https://docs.dreadnode.io/sdk/overview/)** - Complete SDK reference
 
 ## License
 

{dreadnode-2.0.13 → dreadnode-2.0.14}/README.md

@@ -312,9 +312,9 @@ uv sync --all-extras
 
 ## Documentation
 
-- **[Installation Guide](https://docs.dreadnode.io/strikes/install)** - Setup options
-- **[Introduction](https://docs.dreadnode.io/strikes/intro)** - Getting started guide
-- **[API Reference](https://docs.dreadnode.io/strikes/api)** - Complete API documentation
+- **[Getting started](https://docs.dreadnode.io/getting-started/overview/)** - Install, authenticate, first run
+- **[Quickstart](https://docs.dreadnode.io/getting-started/quickstart/)** - End-to-end walkthrough
+- **[SDK reference](https://docs.dreadnode.io/sdk/overview/)** - Complete SDK reference
 
 ## License
 

{dreadnode-2.0.13 → dreadnode-2.0.14}/dreadnode/__init__.py

@@ -166,6 +166,7 @@ __all__ = [
     "tag",
     "task",
     "task_and_run",
+    "task_env",
     "task_span",
     "tool",
     "tool_method",
@@ -260,6 +261,7 @@ __instance_methods__: list[str] = [
     "task_span",
     "run",
     "task_and_run",
+    "task_env",
     "scorer",
     "evaluation",
     "optimize_anything",

{dreadnode-2.0.13 → dreadnode-2.0.14}/dreadnode/agents/agent.py

@@ -153,7 +153,7 @@ class Agent(Executor[AgentEvent, Trajectory]):
     instructions: t.Annotated[str | None, AfterValidator(lambda x: dedent(x) if x else x)] = Config(
         default=None
     )
-    cache: caching.CacheMode | None = Config(default=None, repr=False)
+    cache: caching.CacheMode | None = Config(default="latest", repr=False)
     tools: list[Tool | Toolset] = Config(default_factory=list, validate_default=False)
     tool_mode: ToolMode = Config(default="auto", repr=False)
     hooks: list[Hook] = Config(default_factory=list, repr=False)
@@ -307,7 +307,8 @@ class Agent(Executor[AgentEvent, Trajectory]):
             post_transforms.append(post_transform)
 
         try:
-            messages = caching.apply_cache_mode_to_messages(self.cache, [messages])[0]
+            if self.cache is not None and self.generator.supports_prompt_caching():
+                messages = caching.apply_cache_mode_to_messages(self.cache, [messages])[0]
             logger.trace(f"Generating with model '{self.generator.model}'. Messages: {messages!r}")
 
             generated = (await self.generator.generate_messages([messages], [params]))[0]
@@ -494,9 +495,18 @@ class Agent(Executor[AgentEvent, Trajectory]):
         )
 
         if not _is_context_length_error(error):
+            logger.debug(
+                "Overflow recovery: error not classified as context-length ({}: {}); skipping",
+                type(error).__name__,
+                str(error)[:200],
+            )
             return None
 
         if len(messages) <= 10:
+            logger.info(
+                "Overflow recovery: too few messages to compact ({} <= 10); skipping",
+                len(messages),
+            )
             return None
 
         work = list(messages)
@@ -504,6 +514,7 @@ class Agent(Executor[AgentEvent, Trajectory]):
 
         summarizer = self._generator
         if summarizer is None:
+            logger.warning("Overflow recovery: no summarizer generator available; skipping")
             return None
 
         # Cap summarizer input at ~60% of the model's token budget (~3 chars/token,
@@ -519,12 +530,27 @@ class Agent(Executor[AgentEvent, Trajectory]):
             max_summarize_chars=max_summarize_chars,
         )
         if boundary == 0:
-            logger.info(
-                "Overflow recovery: no safe summarization window fits summarizer budget "
-                "(budget_tokens={}, max_chars={})",
-                budget_tokens,
-                max_summarize_chars,
-            )
+            # Distinguish "no safe boundary exists" (neither a simple-assistant
+            # nor a complete tool-call group anywhere in the trajectory) from
+            # "boundaries exist but none fit the summarizer budget". Both
+            # currently return 0; telling them apart is the diagnostic split
+            # point ENG-6545 needs.
+            uncapped_boundary = find_summarization_boundary(work, min_messages_to_keep=10)
+            if uncapped_boundary == 0:
+                logger.info(
+                    "Overflow recovery: no API-safe boundary in {} messages "
+                    "(no simple-assistant or complete tool-call group); skipping",
+                    len(work),
+                )
+            else:
+                logger.info(
+                    "Overflow recovery: valid boundary at index {} exceeds summarizer "
+                    "budget (messages={}, budget_tokens={}, max_chars={}); skipping",
+                    uncapped_boundary,
+                    len(work),
+                    budget_tokens,
+                    max_summarize_chars,
+                )
             return None
 
         to_summarize = work[:boundary]
@@ -578,7 +604,7 @@ class Agent(Executor[AgentEvent, Trajectory]):
             async for event in self._dispatch(start_event):
                 yield event
 
-            tool = next((t for t in self.all_tools if t.name == tool_call.name), None)
+            tool = next((t for t in self.all_tools if t.wire_name == tool_call.name), None)
 
             if tool is None:
                 error_msg = f"Tool '{tool_call.name}' not found."
@@ -620,6 +646,14 @@ class Agent(Executor[AgentEvent, Trajectory]):
             try:
                 message, stop = await tool.handle_tool_call(tool_call)
 
+                # Tools that catch their own exceptions (bash non-zero,
+                # @tool(catch=True), MCP isError) lift the failure into
+                # message.metadata. Surface it on ToolEnd so renderers can
+                # mark the call as errored without needing to parse XML
+                # out of the result body.
+                tool_error = message.metadata.get("error")
+                tool_error_type = message.metadata.get("error_type")
+
                 end_event = ToolEnd(
                     agent_id=self.agent_id,
                     agent_name=self.name,
@@ -627,11 +661,19 @@ class Agent(Executor[AgentEvent, Trajectory]):
                     result=message.content,
                     output_file=message.metadata.get("output_file"),
                     stop=stop,
+                    error=tool_error,
+                    error_type=tool_error_type,
                 )
                 async for event in self._dispatch(end_event):
                     yield event
                 end_event.emit(t_span)  # Emit after dispatch - metrics attached
 
+                # ToolStep.error is typed for actual exceptions (uncaught
+                # errors that get re-raised). The metadata error string is
+                # already on ToolEnd.error above — don't double-emit it
+                # here, or Pydantic will reject the str input and the
+                # raised ValidationError will surface as a duplicate
+                # ToolError row in the TUI.
                 step_event = ToolStep(
                     agent_id=self.agent_id,
                     agent_name=self.name,
@@ -799,6 +841,12 @@ class Agent(Executor[AgentEvent, Trajectory]):
                                 yield event
                             messages = recovered_messages
                             step_chat = await self._generate(messages)
+                            if step_chat.failed and step_chat.error:
+                                logger.warning(
+                                    "Overflow recovery: compacted regenerate also failed ({}: {})",
+                                    type(step_chat.error).__name__,
+                                    str(step_chat.error)[:200],
+                                )
 
                     if step_chat.failed and step_chat.error:
                         from dreadnode.agents.hooks import _describe_generation_error

{dreadnode-2.0.13 → dreadnode-2.0.14}/dreadnode/agents/events.py

@@ -212,7 +212,7 @@ class AgentStart(AgentEvent):
 
         goal = self.inputs.get("goal")
         if goal is not None:
-            span.set_attribute(AGENT_ATTRIBUTE_GOAL, str(goal)[:2000])
+            span.set_attribute(AGENT_ATTRIBUTE_GOAL, str(goal))
             span.log_input(name="goal", value=goal)
 
         if session_id := self.params.get("session_id"):
@@ -259,7 +259,7 @@ class AgentEnd(AgentEvent):
 
     def emit(self, span: "TaskSpan") -> None:
         if self.error:
-            span.log_output(name="error", value=str(self.error)[:500])
+            span.log_output(name="error", value=str(self.error))
 
         super().emit(span)
 
@@ -338,11 +338,7 @@ class GenerationRetry(AgentEvent):
 
 
 class AgentStalled(AgentEvent):
-    """Event: The agent is stalled and there are no tool calls, or stop condition).
-
-    Attributes:
-        None
-    """
+    """Event: The agent is stalled and there are no tool calls, or stop condition)."""
 
     def _get_data(self) -> dict[str, t.Any]:
         return {"reason": "No tool calls and no stop condition met"}
@@ -516,16 +512,26 @@ class ToolStart(AgentEvent):
 class ToolEnd(AgentEvent):
     """Event: A tool call has completed.
 
+    A non-empty ``error`` means the tool ran to completion but reported
+    a failure (e.g. bash non-zero exit, ``@tool(catch=True)`` swallowing
+    an exception, or an MCP server returning ``isError=true``). Uncaught
+    exceptions go through :class:`ToolError` instead.
+
     Attributes:
         tool_call: The tool call that was completed.
         result: The result returned by the tool, if applicable.
         stop: Whether this tool requested the agent to stop.
+        error: A failure message lifted from ``message.metadata['error']``.
+        error_type: Exception class name when the error was sourced from
+            an :class:`ErrorModel` carrying that metadata.
     """
 
     tool_call: ToolCall
     result: str | None = None
     stop: bool = False
     output_file: str | None = None
+    error: str | None = None
+    error_type: str | None = None
 
     def _get_data(self) -> dict[str, t.Any]:
         return {
@@ -533,9 +539,11 @@ class ToolEnd(AgentEvent):
                 "id": self.tool_call.id,
                 "name": self.tool_call.name,
             },
-            "result": self.result[:4000] if self.result else None,
+            "result": self.result or None,
             "output_file": self.output_file,
             "stop": self.stop,
+            "error": self.error,
+            "error_type": self.error_type,
         }
 
     def __repr__(self) -> str:
@@ -545,11 +553,15 @@ class ToolEnd(AgentEvent):
     def emit(self, span: "TaskSpan") -> None:
         # Attributes
         if self.result:
-            span.set_attribute(TOOL_ATTRIBUTE_RESULT, self.result[:4000])
-            span.log_output("result", self.result[:4000])
+            span.set_attribute(TOOL_ATTRIBUTE_RESULT, self.result)
+            span.log_output("result", self.result)
 
         span.set_attribute(TOOL_ATTRIBUTE_STOPPED, self.stop)
 
+        if self.error:
+            span.set_attribute(TOOL_ATTRIBUTE_ERROR, self.error)
+            span.log_metric(f"tool/{self.tool_call.name}/error", 1)
+
         super().emit(span)
 
     def format_as_panel(self, *, truncate: bool = False) -> Panel:
@@ -591,7 +603,7 @@ class ToolError(AgentEvent):
 
     def emit(self, span: "TaskSpan") -> None:
         # Attributes
-        span.set_attribute(TOOL_ATTRIBUTE_ERROR, str(self.error)[:1000])
+        span.set_attribute(TOOL_ATTRIBUTE_ERROR, str(self.error))
 
         # Metrics
         span.log_metric(f"tool/{self.tool_call.name}/error", 1)
@@ -666,7 +678,7 @@ class GenerationStep(AgentStep):
 
         if self.messages:
             last_msg = self.messages[-1]
-            content = str(last_msg.content)[:4000] if last_msg.content else None
+            content = str(last_msg.content) if last_msg.content else None
 
             for tc in last_msg.tool_calls or []:
                 try:
@@ -721,7 +733,7 @@ class GenerationStep(AgentStep):
             span.set_attribute(GENERATION_ATTRIBUTE_ROLE, last_msg.role)
 
             if last_msg.content:
-                span.set_attribute(GENERATION_ATTRIBUTE_CONTENT, str(last_msg.content)[:4000])
+                span.set_attribute(GENERATION_ATTRIBUTE_CONTENT, str(last_msg.content))
 
             if last_msg.tool_calls:
                 span.set_attribute(
@@ -780,7 +792,7 @@ class GenerationStart(AgentEvent):
             for m in self.messages:
                 msg: dict[str, t.Any] = {"role": m.role}
                 if m.content:
-                    msg["content"] = str(m.content)[:4000]
+                    msg["content"] = str(m.content)
                 if m.tool_calls:
                     msg["tool_calls"] = [{"name": tc.name, "id": tc.id} for tc in m.tool_calls]
                 input_messages.append(msg)
@@ -806,7 +818,7 @@ class GenerationEnd(AgentStep):
 
         if self.messages:
             last_msg = self.messages[-1]
-            content = str(last_msg.content)[:4000] if last_msg.content else None
+            content = str(last_msg.content) if last_msg.content else None
 
             for tc in last_msg.tool_calls or []:
                 try:
@@ -849,7 +861,7 @@ class GenerationEnd(AgentStep):
             span.set_attribute(GENERATION_ATTRIBUTE_ROLE, last_msg.role)
 
             if last_msg.content:
-                span.set_attribute(GENERATION_ATTRIBUTE_CONTENT, str(last_msg.content)[:4000])
+                span.set_attribute(GENERATION_ATTRIBUTE_CONTENT, str(last_msg.content))
                 span.log_output(
                     name="generation",
                     value=last_msg.content,

{dreadnode-2.0.13 → dreadnode-2.0.14}/dreadnode/agents/hooks.py

@@ -243,8 +243,16 @@ def find_summarization_boundary(
 
     Walks messages from the start and enumerates every safe split point that
     leaves at least ``min_messages_to_keep`` messages in the "keep" portion.
-    A safe boundary is after a simple assistant message (no tool calls) —
-    this is the natural end of a complete conversational turn.
+    A boundary is safe when both sides of the cut are API-valid chat
+    sequences — no orphaned ``tool_calls`` and no orphaned ``tool`` responses.
+    Two kinds of positions qualify:
+
+    - **After a simple assistant message** (no ``tool_calls``) — the natural
+      end of a complete conversational turn.
+    - **After a complete tool-call group** — every ``tool_call.id`` from a
+      preceding ``assistant`` message has a matching ``tool`` response. The
+      cut falls after the last matching tool response, so neither side has a
+      dangling tool call or result.
 
     When ``max_summarize_chars`` is provided, returns the largest safe split
     whose cumulative ``len(str(message))`` stays within the cap. This keeps
@@ -264,15 +272,28 @@ def find_summarization_boundary(
     # (0, 0) is always a valid "no compaction" candidate.
     candidates: list[tuple[int, int]] = [(0, 0)]
     running_chars = 0
+    # Tool-call ids from the most recent assistant(tool_calls) that have not
+    # yet been resolved by matching tool responses. When empty, the preceding
+    # tool-call group is complete and the position is API-safe to cut at.
+    pending_tool_ids: set[str] = set()
     for i, message in enumerate(messages):
         if len(messages) - i <= min_messages_to_keep:
             break
         running_chars += len(str(message))
-        is_simple_assistant = message.role == "assistant" and not getattr(
-            message, "tool_calls", None
-        )
-        if is_simple_assistant:
-            candidates.append((i + 1, running_chars))
+        if message.role == "assistant":
+            tool_calls = getattr(message, "tool_calls", None)
+            if tool_calls:
+                pending_tool_ids = {tc.id for tc in tool_calls}
+            elif not pending_tool_ids:
+                candidates.append((i + 1, running_chars))
+        elif (
+            message.role == "tool"
+            and getattr(message, "tool_call_id", None)
+            and message.tool_call_id in pending_tool_ids
+        ):
+            pending_tool_ids.discard(message.tool_call_id)
+            if not pending_tool_ids:
+                candidates.append((i + 1, running_chars))
 
     if max_summarize_chars is None:
         return candidates[-1][0]

{dreadnode-2.0.13 → dreadnode-2.0.14}/dreadnode/agents/mcp/client.py

@@ -29,6 +29,8 @@ from dreadnode.agents.mcp.config import (
     Transport,
 )
 from dreadnode.agents.tools import Tool
+from dreadnode.app.paths import rotate_log
+from dreadnode.generators.models import ErrorModel
 
 if t.TYPE_CHECKING:
     from mcp import ClientSession
@@ -44,20 +46,36 @@ class _StderrCapture:
     letting it spill into the parent terminal. On connection failure the
     buffered lines are included in the error message so users can see
     why the server process crashed.
+
+    When a ``log_path`` is provided, each captured line is also tee'd to
+    disk so operators can ``tail -f`` the server's stderr — matching the
+    subprocess-worker convention under ``~/.dreadnode/logs/``.
     """
 
     _MAX_LINES = 50
 
-    def __init__(self, read_fd: int, exit_stack: AsyncExitStack) -> None:
+    def __init__(
+        self,
+        read_fd: int,
+        exit_stack: AsyncExitStack,
+        *,
+        log_path: Path | None = None,
+    ) -> None:
         import os
         import threading
 
         self._lines: list[str] = []
         self._read_file = os.fdopen(read_fd, "r")
+        self._log_file = self._open_log_file(log_path)
 
         def _reader() -> None:
             try:
                 for raw in self._read_file:
+                    if self._log_file is not None:
+                        # Don't let a disk-side failure break the in-memory
+                        # buffer or the connection itself.
+                        with contextlib.suppress(OSError):
+                            self._log_file.write(raw)
                     line = raw.rstrip("\n")
                     if line:
                         logger.debug("MCP stderr: {}", line)
@@ -71,9 +89,36 @@ class _StderrCapture:
         self._thread.start()
         exit_stack.callback(self._close)
 
+    @staticmethod
+    def _open_log_file(log_path: Path | None) -> t.TextIO | None:
+        """Open the stderr log file for writing, or ``None`` on failure.
+
+        Rotates the prior log to ``<path>.prev`` first, so a failed connect
+        leaves the previous session's stderr intact for diffing. Truncates
+        on open, line-buffered so ``tail -f`` reflects new output
+        immediately.
+        """
+        if log_path is None:
+            return None
+        rotate_log(log_path)
+        try:
+            log_path.parent.mkdir(parents=True, exist_ok=True)
+            return log_path.open("w", buffering=1, encoding="utf-8", errors="replace")
+        except OSError as exc:
+            logger.warning(
+                "MCP stderr capture: failed to open log file '{}' ({}); keeping in-memory buffer only",
+                log_path,
+                exc,
+            )
+            return None
+
     def _close(self) -> None:
         with contextlib.suppress(OSError):
             self._read_file.close()
+        if self._log_file is not None:
+            with contextlib.suppress(OSError):
+                self._log_file.close()
+            self._log_file = None
         self._thread.join(timeout=1)
 
     @property
@@ -156,6 +201,7 @@ class MCPClient:
         *,
         oauth: t.Any = None,
         init_timeout: float = DEFAULT_INIT_TIMEOUT,
+        log_path: Path | None = None,
     ) -> None:
         # Handle deprecated "sse" transport
         if transport == "sse":
@@ -176,6 +222,9 @@ class MCPClient:
         self._session = None
         self._oauth_config = oauth
         self._init_timeout = init_timeout
+        # Only meaningful for stdio transports — the stderr capture wires it
+        # into _StderrCapture on connect. HTTP transports ignore it.
+        self._log_path = log_path
         self._stderr_capture: _StderrCapture | None = None
         self._owner_task = None
         self._shutdown_event = None
@@ -183,8 +232,13 @@ class MCPClient:
         self._lifecycle_lock = None
 
     @classmethod
-    def from_config(cls, config: ServerConfig) -> "MCPClient":
-        """Create a client from a typed server config."""
+    def from_config(cls, config: ServerConfig, *, log_path: Path | None = None) -> "MCPClient":
+        """Create a client from a typed server config.
+
+        The SDK's MCP lifecycle manager passes ``log_path`` to tee stderr
+        under ``~/.dreadnode/logs/``. User-code callers of
+        :func:`dreadnode.agents.mcp` don't need to supply it.
+        """
         if isinstance(config, StdioServerConfig):
             connection: StdioConnection = StdioConnection(
                 command=config.command,
@@ -192,7 +246,12 @@ class MCPClient:
                 cwd=config.cwd,
                 env=config.env,
             )
-            return cls("stdio", connection, init_timeout=config.init_timeout)
+            return cls(
+                "stdio",
+                connection,
+                init_timeout=config.init_timeout,
+                log_path=log_path,
+            )
 
         # HttpServerConfig
         connection_dict: dict[str, t.Any] = {
@@ -206,6 +265,7 @@ class MCPClient:
             connection_dict,
             oauth=config.oauth,
             init_timeout=config.init_timeout,
+            log_path=log_path,
         )
 
     @property
@@ -217,6 +277,27 @@ class MCPClient:
         """Error message if status is FAILED or NEEDS_AUTH."""
         return self._error
 
+    @property
+    def log_path(self) -> Path | None:
+        """Path that stderr is tee'd to, or ``None`` if capture is in-memory only.
+
+        Only populated for stdio transports; HTTP transports don't spawn a
+        subprocess and have nothing to capture.
+        """
+        return self._log_path
+
+    @property
+    def recent_stderr(self) -> list[str]:
+        """Captured stderr lines from the subprocess, bounded by the ring buffer.
+
+        Mirrors :attr:`SubprocessWorkerRunner.recent_output` so the TUI can
+        render the same progressive-disclosure block for MCP servers and
+        workers. Empty for HTTP transports or before :meth:`connect` runs.
+        """
+        if self._stderr_capture is None:
+            return []
+        return self._stderr_capture.last_lines
+
     @property
     def session(self) -> "ClientSession":
         if self._session is None:
@@ -226,6 +307,21 @@ class MCPClient:
     def _make_execute_on_server(self, tool_name: str) -> t.Callable[..., t.Any]:
         async def execute_on_server(**kwargs: t.Any) -> t.Any:
             result = await self.session.call_tool(tool_name, kwargs)
+            # Protocol-level failures (``isError=true``) are reported as a
+            # successful response carrying error content. Lift them into
+            # an ``ErrorModel`` so ``Tool.handle_tool_call`` routes the
+            # message through the same ``metadata['error']`` path used by
+            # ``@tool(catch=True)`` failures (e.g. bash non-zero exits).
+            if result.isError:
+                error_text = (
+                    "\n".join(
+                        content.text  # ty: ignore[unresolved-attribute]
+                        for content in result.content
+                        if content.type == "text"
+                    )
+                    or f"MCP tool '{tool_name}' reported an error."
+                )
+                return ErrorModel(content=error_text, type="MCPToolError")
             return _convert_mcp_result_to_message_parts(result)
 
         return execute_on_server
@@ -333,7 +429,7 @@ class MCPClient:
         read_fd, write_fd = os.pipe()
         write_file = os.fdopen(write_fd, "w")
 
-        stderr_capture = _StderrCapture(read_fd, self._exit_stack)
+        stderr_capture = _StderrCapture(read_fd, self._exit_stack, log_path=self._log_path)
         self._stderr_capture = stderr_capture
 
         server_params = StdioServerParameters(**connection)