fast-agent-mcp 0.3.15__py3-none-any.whl → 0.3.17__py3-none-any.whl

fast_agent/core/fastagent.py

@@ -6,6 +6,7 @@ directly creates Agent instances without proxies.
 
 import argparse
 import asyncio
+import pathlib
 import sys
 from contextlib import asynccontextmanager
 from importlib.metadata import version as get_version
@@ -76,12 +77,14 @@ from fast_agent.core.validation import (
     validate_workflow_references,
 )
 from fast_agent.mcp.prompts.prompt_load import load_prompt
+from fast_agent.skills import SkillManifest, SkillRegistry
 from fast_agent.ui.usage_display import display_usage_report
 
 if TYPE_CHECKING:
     from mcp.client.session import ElicitationFnT
     from pydantic import AnyUrl
 
+    from fast_agent.constants import DEFAULT_AGENT_INSTRUCTION
     from fast_agent.interfaces import AgentProtocol
     from fast_agent.types import PromptMessageExtended
 
@@ -102,6 +105,7 @@ class FastAgent:
         ignore_unknown_args: bool = False,
         parse_cli_args: bool = True,
         quiet: bool = False,  # Add quiet parameter
+        skills_directory: str | pathlib.Path | None = None,
         **kwargs,
     ) -> None:
         """
@@ -119,6 +123,10 @@ class FastAgent:
         """
         self.args = argparse.Namespace()  # Initialize args always
         self._programmatic_quiet = quiet  # Store the programmatic quiet setting
+        self._skills_directory_override = (
+            Path(skills_directory).expanduser() if skills_directory else None
+        )
+        self._default_skill_manifests: List[SkillManifest] = []
 
         # --- Wrap argument parsing logic ---
         if parse_cli_args:
@@ -173,6 +181,10 @@ class FastAgent:
                 default="0.0.0.0",
                 help="Host address to bind to when running as a server with SSE transport",
             )
+            parser.add_argument(
+                "--skills",
+                help="Path to skills directory to use instead of default .claude/skills",
+            )
 
             if ignore_unknown_args:
                 known_args, _ = parser.parse_known_args()
@@ -200,6 +212,14 @@ class FastAgent:
         if self._programmatic_quiet:
             self.args.quiet = True
 
+        # Apply CLI skills directory if not already set programmatically
+        if (
+            self._skills_directory_override is None
+            and hasattr(self.args, "skills")
+            and self.args.skills
+        ):
+            self._skills_directory_override = Path(self.args.skills).expanduser()
+
         self.name = name
         self.config_path = config_path
 
@@ -271,6 +291,7 @@ class FastAgent:
         from collections.abc import Coroutine
         from pathlib import Path
 
+        from fast_agent.skills import SkillManifest, SkillRegistry
         from fast_agent.types import RequestParams
 
         P = ParamSpec("P")
@@ -281,11 +302,12 @@ class FastAgent:
             name: str = "default",
             instruction_or_kwarg: Optional[str | Path | AnyUrl] = None,
             *,
-            instruction: str | Path | AnyUrl = "You are a helpful agent.",
+            instruction: str | Path | AnyUrl = DEFAULT_AGENT_INSTRUCTION,
             servers: List[str] = [],
             tools: Optional[Dict[str, List[str]]] = None,
             resources: Optional[Dict[str, List[str]]] = None,
             prompts: Optional[Dict[str, List[str]]] = None,
+            skills: Optional[List[SkillManifest | SkillRegistry | Path | str | None]] = None,
             model: Optional[str] = None,
             use_history: bool = True,
             request_params: RequestParams | None = None,
@@ -430,6 +452,21 @@ class FastAgent:
         with tracer.start_as_current_span(self.name):
             try:
                 async with self.app.run():
+                    registry = getattr(self.context, "skill_registry", None)
+                    if self._skills_directory_override is not None:
+                        override_registry = SkillRegistry(
+                            base_dir=Path.cwd(),
+                            override_directory=self._skills_directory_override,
+                        )
+                        self.context.skill_registry = override_registry
+                        registry = override_registry
+
+                    default_skills: List[SkillManifest] = []
+                    if registry:
+                        default_skills = registry.load_manifests()
+
+                    self._apply_skills_to_agent_configs(default_skills)
+
                     # Apply quiet mode if requested
                     if quiet_mode:
                         cfg = self.app.context.config
@@ -621,6 +658,69 @@ class FastAgent:
                         except Exception:
                             pass
 
+    def _apply_skills_to_agent_configs(self, default_skills: List[SkillManifest]) -> None:
+        self._default_skill_manifests = list(default_skills)
+
+        for agent_data in self.agents.values():
+            config_obj = agent_data.get("config")
+            if not config_obj:
+                continue
+
+            resolved = self._resolve_skills(config_obj.skills)
+            if not resolved:
+                resolved = list(default_skills)
+            else:
+                resolved = self._deduplicate_skills(resolved)
+
+            config_obj.skill_manifests = resolved
+
+    def _resolve_skills(
+        self,
+        entry: SkillManifest
+        | SkillRegistry
+        | Path
+        | str
+        | List[SkillManifest | SkillRegistry | Path | str | None]
+        | None,
+    ) -> List[SkillManifest]:
+        if entry is None:
+            return []
+        if isinstance(entry, list):
+            manifests: List[SkillManifest] = []
+            for item in entry:
+                manifests.extend(self._resolve_skills(item))
+            return manifests
+        if isinstance(entry, SkillManifest):
+            return [entry]
+        if isinstance(entry, SkillRegistry):
+            try:
+                return entry.load_manifests()
+            except Exception:
+                logger.debug(
+                    "Failed to load skills from registry",
+                    data={"registry": type(entry).__name__},
+                )
+                return []
+        if isinstance(entry, Path):
+            return SkillRegistry.load_directory(entry.expanduser().resolve())
+        if isinstance(entry, str):
+            return SkillRegistry.load_directory(Path(entry).expanduser().resolve())
+
+        logger.debug(
+            "Unsupported skill entry type",
+            data={"type": type(entry).__name__},
+        )
+        return []
+
+    @staticmethod
+    def _deduplicate_skills(manifests: List[SkillManifest]) -> List[SkillManifest]:
+        unique: Dict[str, SkillManifest] = {}
+        for manifest in manifests:
+            key = manifest.name.lower()
+            if key not in unique:
+                unique[key] = manifest
+        return list(unique.values())
+
     def _handle_error(self, e: Exception, error_type: Optional[str] = None) -> None:
         """
         Handle errors with consistent formatting and messaging.

fast_agent/core/logging/listeners.py

@@ -64,6 +64,14 @@ def convert_log_event(event: Event) -> "ProgressEvent | None":
         chat_turn = event_data.get("chat_turn")
         if chat_turn is not None:
             details = f"{model} turn {chat_turn}"
+
+        tool_name = event_data.get("tool_name")
+        tool_event = event_data.get("tool_event")
+        if tool_name:
+            tool_suffix = tool_name
+            if tool_event:
+                tool_suffix = f"{tool_suffix} ({tool_event})"
+            details = f"{details} • {tool_suffix}".strip()
     else:
         if not target:
             target = event_data.get("target", "unknown")

fast_agent/interfaces.py

@@ -18,6 +18,7 @@ from typing import (
     Type,
     TypeVar,
     Union,
+    runtime_checkable,
 )
 
 from a2a.types import AgentCard
@@ -59,6 +60,7 @@ class ModelFactoryFunctionProtocol(Protocol):
     def __call__(self, model: str | None = None) -> LLMFactoryProtocol: ...
 
 
+@runtime_checkable
 class FastAgentLLMProtocol(Protocol):
     """Protocol defining the interface for LLMs"""
 
@@ -87,9 +89,15 @@ class FastAgentLLMProtocol(Protocol):
 
     def add_stream_listener(self, listener: Callable[[str], None]) -> Callable[[], None]: ...
 
+    def add_tool_stream_listener(
+        self, listener: Callable[[str, Dict[str, Any] | None], None]
+    ) -> Callable[[], None]: ...
+
     @property
     def message_history(self) -> List[PromptMessageExtended]: ...
 
+    def pop_last_message(self) -> PromptMessageExtended | None: ...
+
     @property
     def usage_accumulator(self) -> UsageAccumulator | None: ...
 
@@ -105,6 +113,7 @@ class FastAgentLLMProtocol(Protocol):
     def clear(self, *, clear_prompts: bool = False) -> None: ...
 
 
+@runtime_checkable
 class LlmAgentProtocol(Protocol):
     """Protocol defining the minimal interface for LLM agents."""
 
@@ -123,7 +132,10 @@ class LlmAgentProtocol(Protocol):
 
     def clear(self, *, clear_prompts: bool = False) -> None: ...
 
+    def pop_last_message(self) -> PromptMessageExtended | None: ...
+
 
+@runtime_checkable
 class AgentProtocol(LlmAgentProtocol, Protocol):
     """Standard agent interface with flexible input types."""
 

fast_agent/llm/fastagent_llm.py

@@ -159,6 +159,7 @@ class FastAgentLLM(ContextDependent, FastAgentLLMProtocol, Generic[MessageParamT
         # Initialize usage tracking
         self._usage_accumulator = UsageAccumulator()
         self._stream_listeners: set[Callable[[str], None]] = set()
+        self._tool_stream_listeners: set[Callable[[str, Dict[str, Any] | None], None]] = set()
 
     def _initialize_default_params(self, kwargs: dict) -> RequestParams:
         """Initialize default parameters for the LLM.
@@ -534,6 +535,37 @@ class FastAgentLLM(ContextDependent, FastAgentLLMProtocol, Generic[MessageParamT
             except Exception:
                 self.logger.exception("Stream listener raised an exception")
 
+    def add_tool_stream_listener(
+        self, listener: Callable[[str, Dict[str, Any] | None], None]
+    ) -> Callable[[], None]:
+        """Register a callback invoked with tool streaming events.
+
+        Args:
+            listener: Callable receiving event_type (str) and optional info dict.
+
+        Returns:
+            A function that removes the listener when called.
+        """
+
+        self._tool_stream_listeners.add(listener)
+
+        def remove() -> None:
+            self._tool_stream_listeners.discard(listener)
+
+        return remove
+
+    def _notify_tool_stream_listeners(
+        self, event_type: str, payload: Dict[str, Any] | None = None
+    ) -> None:
+        """Notify listeners about tool streaming lifecycle events."""
+
+        data = payload or {}
+        for listener in list(self._tool_stream_listeners):
+            try:
+                listener(event_type, data)
+            except Exception:
+                self.logger.exception("Tool stream listener raised an exception")
+
     def _log_chat_finished(self, model: Optional[str] = None) -> None:
         """Log a chat finished event"""
         data = {
@@ -643,6 +675,19 @@ class FastAgentLLM(ContextDependent, FastAgentLLMProtocol, Generic[MessageParamT
         """
         return self._message_history
 
+    def pop_last_message(self) -> PromptMessageExtended | None:
+        """Remove and return the most recent message from the conversation history."""
+        if not self._message_history:
+            return None
+
+        removed = self._message_history.pop()
+        try:
+            self.history.pop()
+        except Exception:
+            # If provider-specific memory isn't available, ignore to avoid crashing UX
+            pass
+        return removed
+
     def clear(self, *, clear_prompts: bool = False) -> None:
         """Reset stored message history while optionally retaining prompt templates."""
 

fast_agent/llm/memory.py

@@ -1,4 +1,4 @@
-from typing import Generic, List, Protocol, TypeVar
+from typing import Generic, List, Optional, Protocol, TypeVar
 
 # Define our own type variable for implementation use
 MessageParamT = TypeVar("MessageParamT")
@@ -23,6 +23,8 @@ class Memory(Protocol, Generic[MessageParamT]):
 
     def clear(self, clear_prompts: bool = False) -> None: ...
 
+    def pop(self, *, from_prompts: bool = False) -> Optional[MessageParamT]: ...
+
 
 class SimpleMemory(Memory, Generic[MessageParamT]):
     """
@@ -108,6 +110,29 @@ class SimpleMemory(Memory, Generic[MessageParamT]):
         if clear_prompts:
             self.prompt_messages = []
 
+    def pop(self, *, from_prompts: bool = False) -> Optional[MessageParamT]:
+        """
+        Remove and return the most recent message from history or prompt messages.
+
+        Args:
+            from_prompts: If True, pop from prompt_messages instead of history
+
+        Returns:
+            The removed message if available, otherwise None
+        """
+        if from_prompts:
+            if not self.prompt_messages:
+                return None
+            return self.prompt_messages.pop()
+
+        if not self.history:
+            return None
+
+        removed = self.history.pop()
+        # Recalculate cache positions now that the history shrank
+        self.conversation_cache_positions = self._calculate_cache_positions(len(self.history))
+        return removed
+
     def should_apply_conversation_cache(self) -> bool:
         """
         Determine if conversation caching should be applied based on walking algorithm.

fast_agent/llm/model_database.py

@@ -87,7 +87,7 @@ class ModelDatabase:
     )
 
     GEMINI_PRO = ModelParameters(
-        context_window=2097152, max_output_tokens=8192, tokenizes=GOOGLE_MULTIMODAL
+        context_window=1_048_576, max_output_tokens=65_536, tokenizes=GOOGLE_MULTIMODAL
     )
 
     QWEN_STANDARD = ModelParameters(
@@ -245,6 +245,9 @@ class ModelDatabase:
         "gemini-2.5-pro-preview": GEMINI_2_5_PRO,
         "gemini-2.5-flash-preview-05-20": GEMINI_FLASH,
         "gemini-2.5-pro-preview-05-06": GEMINI_PRO,
+        "gemini-2.5-pro": GEMINI_PRO,
+        "gemini-2.5-flash-preview-09-2025": GEMINI_FLASH,
+        "gemini-2.5-flash": GEMINI_FLASH,
         # xAI Grok Models
         "grok-4-fast-reasoning": GROK_4_VLM,
         "grok-4-fast-non-reasoning": GROK_4_VLM,

fast_agent/llm/model_factory.py

@@ -90,7 +90,9 @@ class ModelFactory:
         "deepseek-chat": Provider.DEEPSEEK,
         "gemini-2.0-flash": Provider.GOOGLE,
         "gemini-2.5-flash-preview-05-20": Provider.GOOGLE,
+        "gemini-2.5-flash-preview-09-2025": Provider.GOOGLE,
         "gemini-2.5-pro-preview-05-06": Provider.GOOGLE,
+        "gemini-2.5-pro": Provider.GOOGLE,
         "grok-4": Provider.XAI,
         "grok-4-0709": Provider.XAI,
         "grok-3": Provider.XAI,
@@ -120,8 +122,8 @@ class ModelFactory:
         "deepseekv3": "deepseek-chat",
         "deepseek": "deepseek-chat",
         "gemini2": "gemini-2.0-flash",
-        "gemini25": "gemini-2.5-flash-preview-05-20",
-        "gemini25pro": "gemini-2.5-pro-preview-05-06",
+        "gemini25": "gemini-2.5-flash-preview-09-2025",
+        "gemini25pro": "gemini-2.5-pro",
         "kimi": "groq.moonshotai/kimi-k2-instruct-0905",
         "gpt-oss": "groq.openai/gpt-oss-120b",
         "gpt-oss-20b": "groq.openai/gpt-oss-20b",

fast_agent/llm/model_info.py

@@ -8,14 +8,15 @@ capabilities (Text/Document/Vision), backed by the model database.
 from __future__ import annotations
 
 from dataclasses import dataclass
-from typing import TYPE_CHECKING, List, Optional, Union
+from typing import TYPE_CHECKING, List, Optional
 
 from fast_agent.llm.model_database import ModelDatabase
+from fast_agent.llm.model_factory import ModelFactory
 from fast_agent.llm.provider_types import Provider
 
 if TYPE_CHECKING:
     # Import behind TYPE_CHECKING to avoid import cycles at runtime
-    from fast_agent.interfaces import AgentProtocol, FastAgentLLMProtocol
+    from fast_agent.interfaces import FastAgentLLMProtocol
 
 
 @dataclass(frozen=True)
@@ -32,16 +33,24 @@ class ModelInfo:
 
     @property
     def supports_text(self) -> bool:
+        if "text/plain" in (self.tokenizes or []):
+            return True
         return ModelDatabase.supports_mime(self.name, "text/plain")
 
     @property
     def supports_document(self) -> bool:
         # Document support currently keyed off PDF support
+        if "application/pdf" in (self.tokenizes or []):
+            return True
         return ModelDatabase.supports_mime(self.name, "pdf")
 
     @property
     def supports_vision(self) -> bool:
         # Any common image format indicates vision support
+        tokenizes = self.tokenizes or []
+        if any(mt in tokenizes for mt in ("image/jpeg", "image/png", "image/webp")):
+            return True
+
         return any(
             ModelDatabase.supports_mime(self.name, mt)
             for mt in ("image/jpeg", "image/png", "image/webp")
@@ -62,14 +71,15 @@ class ModelInfo:
 
     @classmethod
     def from_name(cls, name: str, provider: Provider | None = None) -> Optional["ModelInfo"]:
-        params = ModelDatabase.get_model_params(name)
+        canonical_name = ModelFactory.MODEL_ALIASES.get(name, name)
+        params = ModelDatabase.get_model_params(canonical_name)
         if not params:
             # Unknown model: return a conservative default that supports text only.
             # This matches the desired behavior for TDV display fallbacks.
             if provider is None:
                 provider = Provider.GENERIC
             return ModelInfo(
-                name=name,
+                name=canonical_name,
                 provider=provider,
                 context_window=None,
                 max_output_tokens=None,
@@ -78,49 +88,15 @@ class ModelInfo:
                 reasoning=None,
             )
 
+        if provider is None:
+            provider = ModelFactory.DEFAULT_PROVIDERS.get(canonical_name, Provider.GENERIC)
+
         return ModelInfo(
-            name=name,
-            provider=provider or Provider.GENERIC,
+            name=canonical_name,
+            provider=provider,
             context_window=params.context_window,
             max_output_tokens=params.max_output_tokens,
             tokenizes=params.tokenizes,
             json_mode=params.json_mode,
             reasoning=params.reasoning,
         )
-
-
-def get_model_info(
-    subject: Union["AgentProtocol", "FastAgentLLMProtocol", str, None],
-    provider: Provider | None = None,
-) -> Optional[ModelInfo]:
-    """Resolve a ModelInfo from an Agent, LLM, or model name.
-
-    Keeps the public API small while enabling type-safe access to model
-    capabilities across the codebase.
-    """
-    if subject is None:
-        return None
-
-    # Agent → LLM
-    try:
-        from fast_agent.interfaces import AgentProtocol as _AgentProtocol
-    except Exception:
-        _AgentProtocol = None  # type: ignore
-
-    if _AgentProtocol and isinstance(subject, _AgentProtocol):  # type: ignore[arg-type]
-        return ModelInfo.from_llm(subject.llm)
-
-    # LLM → ModelInfo
-    try:
-        from fast_agent.interfaces import FastAgentLLMProtocol as _LLMProtocol
-    except Exception:
-        _LLMProtocol = None  # type: ignore
-
-    if _LLMProtocol and isinstance(subject, _LLMProtocol):  # type: ignore[arg-type]
-        return ModelInfo.from_llm(subject)
-
-    # String model name
-    if isinstance(subject, str):
-        return ModelInfo.from_name(subject, provider)
-
-    return None

fast_agent/llm/provider/anthropic/llm_anthropic.py

@@ -244,10 +244,114 @@ class AnthropicLLM(FastAgentLLM[MessageParam, Message]):
         """Process the streaming response and display real-time token usage."""
         # Track estimated output tokens by counting text chunks
         estimated_tokens = 0
+        tool_streams: dict[int, dict[str, Any]] = {}
 
         try:
             # Process the raw event stream to get token counts
             async for event in stream:
+                if (
+                    event.type == "content_block_start"
+                    and hasattr(event, "content_block")
+                    and getattr(event.content_block, "type", None) == "tool_use"
+                ):
+                    content_block = event.content_block
+                    tool_streams[event.index] = {
+                        "name": content_block.name,
+                        "id": content_block.id,
+                        "buffer": [],
+                    }
+                    self._notify_tool_stream_listeners(
+                        "start",
+                        {
+                            "tool_name": content_block.name,
+                            "tool_use_id": content_block.id,
+                            "index": event.index,
+                            "streams_arguments": False,  # Anthropic doesn't stream arguments
+                        },
+                    )
+                    self.logger.info(
+                        "Model started streaming tool input",
+                        data={
+                            "progress_action": ProgressAction.CALLING_TOOL,
+                            "agent_name": self.name,
+                            "model": model,
+                            "tool_name": content_block.name,
+                            "tool_use_id": content_block.id,
+                            "tool_event": "start",
+                        },
+                    )
+                    continue
+
+                if (
+                    event.type == "content_block_delta"
+                    and hasattr(event, "delta")
+                    and event.delta.type == "input_json_delta"
+                ):
+                    info = tool_streams.get(event.index)
+                    if info is not None:
+                        chunk = event.delta.partial_json or ""
+                        info["buffer"].append(chunk)
+                        preview = chunk if len(chunk) <= 80 else chunk[:77] + "..."
+                        self._notify_tool_stream_listeners(
+                            "delta",
+                            {
+                                "tool_name": info.get("name"),
+                                "tool_use_id": info.get("id"),
+                                "index": event.index,
+                                "chunk": chunk,
+                                "streams_arguments": False,
+                            },
+                        )
+                        self.logger.debug(
+                            "Streaming tool input delta",
+                            data={
+                                "tool_name": info.get("name"),
+                                "tool_use_id": info.get("id"),
+                                "chunk": preview,
+                            },
+                        )
+                    continue
+
+                if (
+                    event.type == "content_block_stop"
+                    and event.index in tool_streams
+                ):
+                    info = tool_streams.pop(event.index)
+                    preview_raw = "".join(info.get("buffer", []))
+                    if preview_raw:
+                        preview = (
+                            preview_raw if len(preview_raw) <= 120 else preview_raw[:117] + "..."
+                        )
+                        self.logger.debug(
+                            "Completed tool input stream",
+                            data={
+                                "tool_name": info.get("name"),
+                                "tool_use_id": info.get("id"),
+                                "input_preview": preview,
+                            },
+                        )
+                    self._notify_tool_stream_listeners(
+                        "stop",
+                        {
+                            "tool_name": info.get("name"),
+                            "tool_use_id": info.get("id"),
+                            "index": event.index,
+                            "streams_arguments": False,
+                        },
+                    )
+                    self.logger.info(
+                        "Model finished streaming tool input",
+                        data={
+                            "progress_action": ProgressAction.CALLING_TOOL,
+                            "agent_name": self.name,
+                            "model": model,
+                            "tool_name": info.get("name"),
+                            "tool_use_id": info.get("id"),
+                            "tool_event": "stop",
+                        },
+                    )
+                    continue
+
                 # Count tokens in real-time from content_block_delta events
                 if (
                     event.type == "content_block_delta"
@@ -258,6 +362,14 @@ class AnthropicLLM(FastAgentLLM[MessageParam, Message]):
                     estimated_tokens = self._update_streaming_progress(
                         event.delta.text, model, estimated_tokens
                     )
+                    self._notify_tool_stream_listeners(
+                        "text",
+                        {
+                            "chunk": event.delta.text,
+                            "index": event.index,
+                            "streams_arguments": False,
+                        },
+                    )
 
                 # Also check for final message_delta events with actual usage info
                 elif (