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

fast_agent/__init__.py

@@ -23,6 +23,7 @@ from fast_agent.config import (
     OpenRouterSettings,
     OpenTelemetrySettings,
     Settings,
+    SkillsSettings,
     TensorZeroSettings,
     XAISettings,
 )
@@ -126,6 +127,7 @@ __all__ = [
     "BedrockSettings",
     "HuggingFaceSettings",
     "LoggerSettings",
+    "SkillsSettings",
     # Progress and event tracking (lazy loaded)
     "ProgressAction",
     "ProgressEvent",

fast_agent/agents/agent_types.py

@@ -4,10 +4,13 @@ Type definitions for agents and agent configurations.
 
 from dataclasses import dataclass, field
 from enum import StrEnum, auto
+from pathlib import Path
 from typing import Dict, List, Optional
 
 from mcp.client.session import ElicitationFnT
 
+from fast_agent.skills import SkillManifest, SkillRegistry
+
 # Forward imports to avoid circular dependencies
 from fast_agent.types import RequestParams
 
@@ -36,6 +39,8 @@ class AgentConfig:
     tools: Optional[Dict[str, List[str]]] = None
     resources: Optional[Dict[str, List[str]]] = None
     prompts: Optional[Dict[str, List[str]]] = None
+    skills: SkillManifest | SkillRegistry | Path | str | None = None
+    skill_manifests: List[SkillManifest] = field(default_factory=list, repr=False)
     model: str | None = None
     use_history: bool = True
     default_request_params: RequestParams | None = None

fast_agent/agents/llm_agent.py

@@ -246,6 +246,7 @@ class LlmAgent(LlmDecorator):
             display_model = self.llm.model_name if self._llm else None
 
             remove_listener: Callable[[], None] | None = None
+            remove_tool_listener: Callable[[], None] | None = None
 
             with self.display.streaming_assistant_message(
                 name=display_name,
@@ -253,8 +254,12 @@ class LlmAgent(LlmDecorator):
             ) as stream_handle:
                 try:
                     remove_listener = self.llm.add_stream_listener(stream_handle.update)
+                    remove_tool_listener = self.llm.add_tool_stream_listener(
+                        stream_handle.handle_tool_event
+                    )
                 except Exception:
                     remove_listener = None
+                    remove_tool_listener = None
 
                 try:
                     result, summary = await self._generate_with_summary(
@@ -263,6 +268,8 @@ class LlmAgent(LlmDecorator):
                 finally:
                     if remove_listener:
                         remove_listener()
+                    if remove_tool_listener:
+                        remove_tool_listener()
 
                 if summary:
                     summary_text = Text(f"\n\n{summary.message}", style="dim red italic")

fast_agent/agents/llm_decorator.py

@@ -718,6 +718,12 @@ class LlmDecorator(AgentProtocol):
             return self._llm.message_history
         return []
 
+    def pop_last_message(self) -> PromptMessageExtended | None:
+        """Remove and return the most recent message from the conversation history."""
+        if self._llm:
+            return self._llm.pop_last_message()
+        return None
+
     @property
     def usage_accumulator(self) -> UsageAccumulator | None:
         """

fast_agent/agents/mcp_agent.py

@@ -42,12 +42,15 @@ from fast_agent.core.exceptions import PromptExitError
 from fast_agent.core.logging.logger import get_logger
 from fast_agent.interfaces import FastAgentLLMProtocol
 from fast_agent.mcp.mcp_aggregator import MCPAggregator, ServerStatus
+from fast_agent.skills.registry import format_skills_for_prompt
 from fast_agent.tools.elicitation import (
     get_elicitation_tool,
     run_elicitation_form,
     set_elicitation_input_callback,
 )
+from fast_agent.tools.shell_runtime import ShellRuntime
 from fast_agent.types import PromptMessageExtended, RequestParams
+from fast_agent.ui import console
 
 # Define a TypeVar for models
 ModelT = TypeVar("ModelT", bound=BaseModel)
@@ -59,6 +62,7 @@ if TYPE_CHECKING:
 
     from fast_agent.context import Context
     from fast_agent.llm.usage_tracking import UsageAccumulator
+    from fast_agent.skills import SkillManifest
 
 
 class McpAgent(ABC, ToolAgent):
@@ -73,7 +77,6 @@ class McpAgent(ABC, ToolAgent):
         self,
         config: AgentConfig,
         connection_persistence: bool = True,
-        # legacy human_input_callback removed
         context: "Context | None" = None,
         **kwargs,
     ) -> None:
@@ -96,6 +99,69 @@ class McpAgent(ABC, ToolAgent):
         self.instruction = self.config.instruction
         self.executor = context.executor if context else None
         self.logger = get_logger(f"{__name__}.{self._name}")
+        manifests: List[SkillManifest] = list(getattr(self.config, "skill_manifests", []) or [])
+        if not manifests and context and getattr(context, "skill_registry", None):
+            try:
+                manifests = list(context.skill_registry.load_manifests())  # type: ignore[assignment]
+            except Exception:
+                manifests = []
+
+        self._skill_manifests = list(manifests)
+        self._skill_map: Dict[str, SkillManifest] = {
+            manifest.name: manifest for manifest in manifests
+        }
+        self._agent_skills_warning_shown = False
+        shell_flag_requested = bool(context and getattr(context, "shell_runtime", False))
+        skills_configured = bool(self._skill_manifests)
+        self._shell_runtime_activation_reason: str | None = None
+
+        if shell_flag_requested and skills_configured:
+            self._shell_runtime_activation_reason = (
+                "via --shell flag and agent skills configuration"
+            )
+        elif shell_flag_requested:
+            self._shell_runtime_activation_reason = "via --shell flag"
+        elif skills_configured:
+            self._shell_runtime_activation_reason = "because agent skills are configured"
+
+        # Get timeout configuration from context
+        timeout_seconds = 90  # default
+        warning_interval_seconds = 30  # default
+        if context and context.config:
+            shell_config = getattr(context.config, "shell_execution", None)
+            if shell_config:
+                timeout_seconds = getattr(shell_config, "timeout_seconds", 90)
+                warning_interval_seconds = getattr(shell_config, "warning_interval_seconds", 30)
+
+        # Derive skills directory from this agent's manifests (respects per-agent config)
+        skills_directory = None
+        if self._skill_manifests:
+            # Get the skills directory from the first manifest's path
+            # Path structure: .fast-agent/skills/skill-name/SKILL.md
+            # So we need parent.parent of the manifest path
+            first_manifest = self._skill_manifests[0]
+            if first_manifest.path:
+                skills_directory = first_manifest.path.parent.parent
+
+        self._shell_runtime = ShellRuntime(
+            self._shell_runtime_activation_reason,
+            self.logger,
+            timeout_seconds=timeout_seconds,
+            warning_interval_seconds=warning_interval_seconds,
+            skills_directory=skills_directory,
+        )
+        self._shell_runtime_enabled = self._shell_runtime.enabled
+        self._shell_access_modes: tuple[str, ...] = ()
+        if self._shell_runtime_enabled:
+            modes: list[str] = ["[red]direct[/red]"]
+            if skills_configured:
+                modes.append("skills")
+            if shell_flag_requested:
+                modes.append("command switch")
+            self._shell_access_modes = tuple(modes)
+        self._bash_tool = self._shell_runtime.tool
+        if self._shell_runtime_enabled:
+            self._shell_runtime.announce()
 
         # Store the default request params from config
         self._default_request_params = self.config.default_request_params
@@ -207,6 +273,24 @@ class McpAgent(ABC, ToolAgent):
                 "{{serverInstructions}}", server_instructions
             )
 
+        skills_placeholder_present = "{{agentSkills}}" in self.instruction
+
+        if skills_placeholder_present:
+            agent_skills = format_skills_for_prompt(self._skill_manifests)
+            self.instruction = self.instruction.replace("{{agentSkills}}", agent_skills)
+            self._agent_skills_warning_shown = True
+        elif self._skill_manifests and not self._agent_skills_warning_shown:
+            warning_message = (
+                "Agent skills are configured but the system prompt does not include {{agentSkills}}. "
+                "Skill descriptions will not be added to the system prompt."
+            )
+            self.logger.warning(warning_message)
+            try:
+                console.console.print(f"[yellow]{warning_message}[/yellow]")
+            except Exception:  # pragma: no cover - console fallback
+                pass
+            self._agent_skills_warning_shown = True
+
         # Update default request params to match
         if self._default_request_params:
             self._default_request_params.systemPrompt = self.instruction
@@ -315,11 +399,12 @@ class McpAgent(ABC, ToolAgent):
         """
         # Get all tools from the aggregator
         result = await self._aggregator.list_tools()
+        aggregator_tools = list(result.tools)
 
         # Apply filtering if tools are specified in config
         if self.config.tools is not None:
             filtered_tools = []
-            for tool in result.tools:
+            for tool in aggregator_tools:
                 # Extract server name from tool name, handling server names with hyphens
                 server_name = None
                 for configured_server in self.config.tools.keys():
@@ -334,7 +419,12 @@ class McpAgent(ABC, ToolAgent):
                         if self._matches_pattern(tool.name, pattern, server_name):
                             filtered_tools.append(tool)
                             break
-            result.tools = filtered_tools
+            aggregator_tools = filtered_tools
+
+        result.tools = aggregator_tools
+
+        if self._bash_tool and all(tool.name != self._bash_tool.name for tool in result.tools):
+            result.tools.append(self._bash_tool)
 
         # Append human input tool if enabled and available
         if self.config.human_input and getattr(self, "_human_input_tool", None):
@@ -353,6 +443,9 @@ class McpAgent(ABC, ToolAgent):
         Returns:
             Result of the tool call
         """
+        if self._shell_runtime.tool and name == self._shell_runtime.tool.name:
+            return await self._shell_runtime.execute(arguments)
+
         if name == HUMAN_INPUT_TOOL_NAME:
             # Call the elicitation-backed human input tool
             return await self._call_human_input_tool(arguments)
@@ -615,6 +708,10 @@ class McpAgent(ABC, ToolAgent):
             namespaced_tool.tool.name
             for namespaced_tool in self._aggregator._namespaced_tool_map.values()
         ]
+        if self._shell_runtime.tool:
+            available_tools.append(self._shell_runtime.tool.name)
+
+        available_tools = list(dict.fromkeys(available_tools))
 
         # Process each tool call using our aggregator
         for correlation_id, tool_request in request.tool_calls.items():
@@ -628,6 +725,8 @@ class McpAgent(ABC, ToolAgent):
             tool_available = False
             if tool_name == HUMAN_INPUT_TOOL_NAME:
                 tool_available = True
+            elif self._bash_tool and tool_name == self._bash_tool.name:
+                tool_available = True
             elif namespaced_tool:
                 tool_available = True
             else:
@@ -654,6 +753,14 @@ class McpAgent(ABC, ToolAgent):
                 # Tool not found in list, no highlighting
                 pass
 
+            metadata: dict[str, Any] | None = None
+            if (
+                self._shell_runtime_enabled
+                and self._shell_runtime.tool
+                and display_tool_name == self._shell_runtime.tool.name
+            ):
+                metadata = self._shell_runtime.metadata(tool_args.get("command"))
+
             self.display.show_tool_call(
                 name=self._name,
                 tool_args=tool_args,
@@ -661,10 +768,11 @@ class McpAgent(ABC, ToolAgent):
                 tool_name=display_tool_name,
                 highlight_index=highlight_index,
                 max_item_length=12,
+                metadata=metadata,
             )
 
             try:
-                # Use our aggregator to call the MCP tool
+                # Use the appropriate handler for this tool
                 result = await self.call_tool(tool_name, tool_args)
                 tool_results[correlation_id] = result
 
@@ -675,12 +783,13 @@ class McpAgent(ABC, ToolAgent):
                         namespaced_tool.server_name
                     )
 
-                self.display.show_tool_result(
-                    name=self._name,
-                    result=result,
-                    tool_name=display_tool_name,
-                    skybridge_config=skybridge_config,
-                )
+                if not getattr(result, "_suppress_display", False):
+                    self.display.show_tool_result(
+                        name=self._name,
+                        result=result,
+                        tool_name=display_tool_name,
+                        skybridge_config=skybridge_config,
+                    )
 
                 self.logger.debug(f"MCP tool {display_tool_name} executed successfully")
             except Exception as e:
@@ -873,6 +982,9 @@ class McpAgent(ABC, ToolAgent):
 
             result[special_server_name].append(self._human_input_tool)
 
+        # if self._skill_lookup_tool:
+        #     result.setdefault("__skills__", []).append(self._skill_lookup_tool)
+
         return result
 
     @property
@@ -985,6 +1097,18 @@ class McpAgent(ABC, ToolAgent):
         Convert a Tool to an AgentSkill.
         """
 
+        if tool.name in self._skill_map:
+            manifest = self._skill_map[tool.name]
+            return AgentSkill(
+                id=f"skill:{manifest.name}",
+                name=manifest.name,
+                description=manifest.description or "",
+                tags=["skill"],
+                examples=None,
+                input_modes=None,
+                output_modes=None,
+            )
+
         _, tool_without_namespace = await self._parse_resource_name(tool.name, "tool")
         return AgentSkill(
             id=tool.name,

fast_agent/cli/__main__.py

@@ -1,3 +1,5 @@
+import asyncio
+import json
 import sys
 
 from fast_agent.cli.constants import GO_SPECIFIC_OPTIONS, KNOWN_SUBCOMMANDS
@@ -8,6 +10,39 @@ from fast_agent.cli.main import app
 
 def main():
     """Main entry point that handles auto-routing to 'go' command."""
+    try:
+        loop = asyncio.get_event_loop()
+
+        def _log_asyncio_exception(loop: asyncio.AbstractEventLoop, context: dict) -> None:
+            import logging
+
+            logger = logging.getLogger("fast_agent.asyncio")
+
+            message = context.get("message", "(no message)")
+            task = context.get("task")
+            future = context.get("future")
+            handle = context.get("handle")
+            source_traceback = context.get("source_traceback")
+            exception = context.get("exception")
+
+            details = {
+                "message": message,
+                "task": repr(task) if task else None,
+                "future": repr(future) if future else None,
+                "handle": repr(handle) if handle else None,
+                "source_traceback": [str(frame) for frame in source_traceback] if source_traceback else None,
+            }
+
+            logger.error("Unhandled asyncio error: %s", message)
+            logger.error("Asyncio context: %s", json.dumps(details, indent=2))
+
+            if exception:
+                logger.exception("Asyncio exception", exc_info=exception)
+
+        loop.set_exception_handler(_log_asyncio_exception)
+    except RuntimeError:
+        # No running loop yet (rare for sync entry), safe to ignore
+        pass
     # Check if we should auto-route to 'go'
     if len(sys.argv) > 1:
         # Check if first arg is not already a subcommand

fast_agent/cli/commands/check_config.py

@@ -13,6 +13,7 @@ from rich.text import Text
 
 from fast_agent.llm.provider_key_manager import API_KEY_HINT_TEXT, ProviderKeyManager
 from fast_agent.llm.provider_types import Provider
+from fast_agent.skills import SkillRegistry
 from fast_agent.ui.console import console
 
 app = typer.Typer(
@@ -169,6 +170,7 @@ def get_config_summary(config_path: Optional[Path]) -> dict:
             "step_seconds": default_settings.mcp_timeline.step_seconds,
         },
         "mcp_servers": [],
+        "skills_directory": None,
     }
 
     if not config_path:
@@ -278,6 +280,13 @@ def get_config_summary(config_path: Optional[Path]) -> dict:
 
                 result["mcp_servers"].append(server_info)
 
+        # Skills directory override
+        skills_cfg = config.get("skills") if isinstance(config, dict) else None
+        if isinstance(skills_cfg, dict):
+            directory_value = skills_cfg.get("directory")
+            if isinstance(directory_value, str) and directory_value.strip():
+                result["skills_directory"] = directory_value.strip()
+
     except Exception as e:
         # File exists but has parse errors
         result["status"] = "error"
@@ -388,6 +397,18 @@ def show_check_summary() -> None:
 
     console.print(env_table)
 
+    def _relative_path(path: Path) -> str:
+        try:
+            return str(path.relative_to(cwd))
+        except ValueError:
+            return str(path)
+
+    skills_override = config_summary.get("skills_directory")
+    override_directory = Path(skills_override).expanduser() if skills_override else None
+    skills_registry = SkillRegistry(base_dir=cwd, override_directory=override_directory)
+    skills_dir = skills_registry.directory
+    skills_manifests, skill_errors = skills_registry.load_manifests_with_errors()
+
     # Logger Settings panel with two-column layout
     logger = config_summary.get("logger", {})
     logger_table = Table(show_header=True, box=None)
@@ -613,6 +634,70 @@ def show_check_summary() -> None:
             _print_section_header("MCP Servers", color="blue")
             console.print(servers_table)
 
+    _print_section_header("Agent Skills", color="blue")
+    if skills_dir:
+        console.print(f"Directory: [green]{_relative_path(skills_dir)}[/green]")
+
+        if skills_manifests or skill_errors:
+            skills_table = Table(show_header=True, box=None)
+            skills_table.add_column("Name", style="cyan", header_style="bold bright_white")
+            skills_table.add_column("Description", style="white", header_style="bold bright_white")
+            skills_table.add_column("Source", style="dim", header_style="bold bright_white")
+            skills_table.add_column("Status", style="green", header_style="bold bright_white")
+
+            def _truncate(text: str, length: int = 70) -> str:
+                if len(text) <= length:
+                    return text
+                return text[: length - 3] + "..."
+
+            for manifest in skills_manifests:
+                try:
+                    relative_source = manifest.path.parent.relative_to(skills_dir)
+                    source_display = str(relative_source) if relative_source != Path(".") else "."
+                except ValueError:
+                    source_display = _relative_path(manifest.path.parent)
+
+                skills_table.add_row(
+                    manifest.name,
+                    _truncate(manifest.description or ""),
+                    source_display,
+                    "[green]ok[/green]",
+                )
+
+            for error in skill_errors:
+                error_path_str = error.get("path", "")
+                source_display = "[dim]n/a[/dim]"
+                if error_path_str:
+                    error_path = Path(error_path_str)
+                    try:
+                        relative_error = error_path.parent.relative_to(skills_dir)
+                        source_display = str(relative_error) if relative_error != Path(".") else "."
+                    except ValueError:
+                        source_display = _relative_path(error_path.parent)
+                message = error.get("error", "Failed to parse skill manifest")
+                skills_table.add_row(
+                    "[red]—[/red]",
+                    "[red]n/a[/red]",
+                    source_display,
+                    f"[red]{_truncate(message, 60)}[/red]",
+                )
+
+            console.print(skills_table)
+        else:
+            console.print("[yellow]No skills found in the directory[/yellow]")
+    else:
+        if skills_registry.override_failed and override_directory:
+            console.print(
+                f"[red]Override directory not found:[/red] {_relative_path(override_directory)}"
+            )
+            console.print(
+                "[yellow]Default folders were not loaded because the override failed[/yellow]"
+            )
+        else:
+            console.print(
+                "[dim]Agent Skills not configured. Go to https://fast-agent.ai/agents/skills/[/dim]"
+            )
+
     # Show help tips
     if config_status == "not_found" or secrets_status == "not_found":
         console.print("\n[bold]Setup Tips:[/bold]")