fast-agent-mcp 0.4.7__py3-none-any.whl

fast_agent/utils/reasoning_stream_parser.py

@@ -0,0 +1,77 @@
+from dataclasses import dataclass
+from typing import List
+
+
+@dataclass
+class ReasoningSegment:
+    """Represents a slice of streamed text and whether it's a reasoning chunk."""
+
+    text: str
+    is_thinking: bool
+
+
+class ReasoningStreamParser:
+    """Incrementally split streamed text into thought vs final answer segments."""
+
+    def __init__(self) -> None:
+        self._buffer = ""
+        self._in_think = False
+
+    @property
+    def in_think(self) -> bool:
+        """Whether the parser is currently inside a <think>...</think> block."""
+        return self._in_think
+
+    def feed(self, chunk: str) -> list[ReasoningSegment]:
+        """Consume a new chunk and return parsed segments."""
+        if not chunk:
+            return []
+
+        self._buffer += chunk
+        return self._extract_segments()
+
+    def flush(self) -> list[ReasoningSegment]:
+        """Return any remaining buffered text as a final segment."""
+        if not self._buffer:
+            return []
+        remaining = ReasoningSegment(text=self._buffer, is_thinking=self._in_think)
+        self._buffer = ""
+        return [remaining]
+
+    def _extract_segments(self) -> list[ReasoningSegment]:
+        segments: List[ReasoningSegment] = []
+
+        while self._buffer:
+            if self._in_think:
+                closing_index = self._buffer.find("</think>")
+                if closing_index == -1:
+                    segments.append(ReasoningSegment(text=self._buffer, is_thinking=True))
+                    self._buffer = ""
+                    break
+
+                if closing_index > 0:
+                    segments.append(
+                        ReasoningSegment(text=self._buffer[:closing_index], is_thinking=True)
+                    )
+
+                self._buffer = self._buffer[closing_index + len("</think>") :]
+                self._in_think = False
+            else:
+                opening_index = self._buffer.find("<think>")
+                if opening_index == -1:
+                    segments.append(ReasoningSegment(text=self._buffer, is_thinking=False))
+                    self._buffer = ""
+                    break
+
+                if opening_index > 0:
+                    segments.append(
+                        ReasoningSegment(
+                            text=self._buffer[:opening_index],
+                            is_thinking=False,
+                        )
+                    )
+
+                self._buffer = self._buffer[opening_index + len("<think>") :]
+                self._in_think = True
+
+        return [segment for segment in segments if segment.text]

fast_agent/utils/time.py

@@ -0,0 +1,22 @@
+"""Common time and duration helpers."""
+
+from __future__ import annotations
+
+
+def format_duration(seconds: float) -> str:
+    """Return a concise, human-friendly duration string."""
+    seconds = max(seconds, 0.0)
+    if seconds < 60:
+        return f"{seconds:.2f}s"
+
+    total_seconds = int(round(seconds))
+    minutes, sec = divmod(total_seconds, 60)
+    if minutes < 60:
+        return f"{minutes}m {sec:02d}s"
+
+    hours, minutes = divmod(minutes, 60)
+    if hours < 24:
+        return f"{hours}h {minutes:02d}m"
+
+    days, hours = divmod(hours, 24)
+    return f"{days}d {hours}h {minutes}m"

fast_agent/workflow_telemetry.py

@@ -0,0 +1,261 @@
+"""
+Workflow telemetry helpers for emitting virtual tool progress.
+
+This module provides a pluggable abstraction that workflows (router, parallel)
+can use to announce delegation steps without knowing which transport consumes
+the events. Transports that care about surfacing these events (e.g. ACP) can
+install a telemetry implementation that forwards them to tool progress
+notifications, while the default implementation is a no-op.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from contextlib import AbstractAsyncContextManager
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Literal, Protocol
+
+from mcp.types import ContentBlock, TextContent
+
+if TYPE_CHECKING:
+    from fast_agent.mcp.tool_execution_handler import ToolExecutionHandler
+
+
+# Plan entry types for ACP plan mode
+PlanEntryStatus = Literal["pending", "in_progress", "completed"]
+PlanEntryPriority = Literal["high", "medium", "low"]
+
+
+@dataclass
+class PlanEntry:
+    """A task within a plan."""
+
+    content: str
+    priority: PlanEntryPriority
+    status: PlanEntryStatus
+
+
+class PlanTelemetryProvider(Protocol):
+    """Provider capable of sending plan updates."""
+
+    async def update_plan(self, entries: list[PlanEntry]) -> None:
+        """Send a plan update with the current list of plan entries."""
+        ...
+
+
+class NoOpPlanTelemetryProvider:
+    """Provider that does nothing with plan updates."""
+
+    async def update_plan(self, entries: list[PlanEntry]) -> None:
+        pass
+
+
+class WorkflowStepHandle(Protocol):
+    """Represents a virtual workflow step that can emit progress and completion."""
+
+    async def update(
+        self,
+        *,
+        message: str | None = None,
+        progress: float | None = None,
+        total: float | None = None,
+    ) -> None:
+        """Send an incremental update about this workflow step."""
+
+    async def finish(
+        self,
+        success: bool,
+        *,
+        text: str | None = None,
+        content: list[ContentBlock] | None = None,
+        error: str | None = None,
+    ) -> None:
+        """Complete the workflow step with optional success text/content."""
+
+
+class WorkflowTelemetry(AbstractAsyncContextManager, WorkflowStepHandle):
+    """
+    Base async context manager returned by telemetry providers.
+
+    Implementations should override __aenter__/__aexit__ along with update/finish.
+    """
+
+    async def __aenter__(self) -> WorkflowStepHandle:
+        return self
+
+    async def __aexit__(self, exc_type, exc, tb) -> bool:
+        # Default no-op exit (override in subclasses to auto-complete)
+        return False
+
+    async def update(  # pragma: no cover - default no-op
+        self,
+        *,
+        message: str | None = None,
+        progress: float | None = None,
+        total: float | None = None,
+    ) -> None:
+        return None
+
+    async def finish(  # pragma: no cover - default no-op
+        self,
+        success: bool,
+        *,
+        text: str | None = None,
+        content: list[ContentBlock] | None = None,
+        error: str | None = None,
+    ) -> None:
+        return None
+
+
+class NullWorkflowTelemetry(WorkflowTelemetry):
+    """No-op telemetry implementation used when no transport wants workflow updates."""
+
+    async def __aexit__(self, exc_type, exc, tb) -> bool:
+        return False
+
+
+class WorkflowTelemetryProvider(Protocol):
+    """Provider capable of starting workflow steps."""
+
+    def start_step(
+        self,
+        tool_name: str,
+        *,
+        server_name: str = "workflow",
+        arguments: dict[str, Any] | None = None,
+    ) -> WorkflowTelemetry: ...
+
+
+class NoOpWorkflowTelemetryProvider:
+    """Provider that always returns a no-op workflow step."""
+
+    def start_step(
+        self,
+        tool_name: str,
+        *,
+        server_name: str = "workflow",
+        arguments: dict[str, Any] | None = None,
+    ) -> WorkflowTelemetry:
+        return NullWorkflowTelemetry()
+
+
+@dataclass
+class _ToolHandlerWorkflowStep(WorkflowTelemetry):
+    handler: ToolExecutionHandler
+    tool_name: str
+    server_name: str
+    arguments: dict[str, Any] | None
+
+    _tool_call_id: str | None = None
+    _finished: bool = False
+    _lock: asyncio.Lock = asyncio.Lock()
+
+    async def __aenter__(self) -> WorkflowStepHandle:
+        self._tool_call_id = await self.handler.on_tool_start(
+            self.tool_name, self.server_name, self.arguments
+        )
+        return self
+
+    async def __aexit__(self, exc_type, exc, tb) -> bool:
+        if not self._finished:
+            success = exc_type is None
+            error_message = str(exc) if exc else None
+            await self.finish(success, error=error_message)
+        return False
+
+    async def update(
+        self,
+        *,
+        message: str | None = None,
+        progress: float | None = None,
+        total: float | None = None,
+    ) -> None:
+        if not self._tool_call_id or (message is None and progress is None):
+            return
+        await self.handler.on_tool_progress(
+            self._tool_call_id,
+            progress if progress is not None else 0.0,
+            total,
+            message,
+        )
+
+    async def finish(
+        self,
+        success: bool,
+        *,
+        text: str | None = None,
+        content: list[ContentBlock] | None = None,
+        error: str | None = None,
+    ) -> None:
+        if self._finished or not self._tool_call_id:
+            self._finished = True
+            return
+
+        final_content = content
+        if final_content is None and text:
+            final_content: list[ContentBlock] = [TextContent(type="text", text=text)]
+
+        await self.handler.on_tool_complete(
+            self._tool_call_id,
+            success,
+            final_content,
+            error,
+        )
+        self._finished = True
+
+
+class ToolHandlerWorkflowTelemetry(NoOpWorkflowTelemetryProvider):
+    """
+    Telemetry provider that forwards workflow steps to a ToolExecutionHandler.
+    """
+
+    def __init__(self, handler: ToolExecutionHandler, *, server_name: str = "workflow") -> None:
+        self._handler = handler
+        self._server_name = server_name
+
+    def start_step(
+        self,
+        tool_name: str,
+        *,
+        server_name: str | None = None,
+        arguments: dict[str, Any] | None = None,
+    ) -> WorkflowTelemetry:
+        effective_server = server_name or self._server_name
+        return _ToolHandlerWorkflowStep(
+            handler=self._handler,
+            tool_name=tool_name,
+            server_name=effective_server,
+            arguments=arguments,
+        )
+
+
+class ACPPlanTelemetryProvider:
+    """
+    Telemetry provider that sends plan updates via ACP session/update notifications.
+    """
+
+    def __init__(self, connection: Any, session_id: str) -> None:
+        self._connection = connection
+        self._session_id = session_id
+
+    async def update_plan(self, entries: list[PlanEntry]) -> None:
+        """Send a plan update with the current list of plan entries."""
+        if not self._connection:
+            return
+
+        # Convert PlanEntry to dict format expected by ACP
+        plan_entries = [
+            {
+                "content": entry.content,
+                "priority": entry.priority,
+                "status": entry.status,
+            }
+            for entry in entries
+        ]
+
+        plan_update = {
+            "sessionUpdate": "plan",
+            "entries": plan_entries,
+        }
+
+        await self._connection.session_update(session_id=self._session_id, update=plan_update)