fast-agent-mcp 0.3.15__tar.gz → 0.3.17__tar.gz

{fast_agent_mcp-0.3.15 → fast_agent_mcp-0.3.17}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fast-agent-mcp
-Version: 0.3.15
+Version: 0.3.17
 Summary: Define, Prompt and Test MCP enabled Agents and Workflows
 Author-email: Shaun Smith <fastagent@llmindset.co.uk>
 License:                                  Apache License
@@ -209,18 +209,18 @@ Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Requires-Python: <3.14,>=3.13.5
-Requires-Dist: a2a-sdk>=0.3.6
-Requires-Dist: aiohttp>=3.11.13
-Requires-Dist: anthropic>=0.69.0
+Requires-Dist: a2a-sdk>=0.3.10
+Requires-Dist: aiohttp>=3.13.1
+Requires-Dist: anthropic>=0.71.0
 Requires-Dist: azure-identity>=1.14.0
 Requires-Dist: boto3>=1.35.0
 Requires-Dist: deprecated>=1.2.18
 Requires-Dist: email-validator>=2.2.0
 Requires-Dist: fastapi>=0.115.6
-Requires-Dist: google-genai>=1.33.0
+Requires-Dist: google-genai>=1.46.0
 Requires-Dist: keyring>=24.3.1
-Requires-Dist: mcp==1.18.0
-Requires-Dist: openai>=2.3.0
+Requires-Dist: mcp==1.19.0
+Requires-Dist: openai[aiohttp]>=2.6.1
 Requires-Dist: opentelemetry-distro>=0.55b0
 Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.7.0
 Requires-Dist: opentelemetry-instrumentation-anthropic>=0.43.1; python_version >= '3.10' and python_version < '4.0'
@@ -231,6 +231,7 @@ Requires-Dist: prompt-toolkit>=3.0.52
 Requires-Dist: pydantic-settings>=2.7.0
 Requires-Dist: pydantic>=2.10.4
 Requires-Dist: pyperclip>=1.9.0
+Requires-Dist: python-frontmatter>=1.1.0
 Requires-Dist: pyyaml>=6.0.2
 Requires-Dist: rich>=14.1.0
 Requires-Dist: tensorzero>=2025.7.5

{fast_agent_mcp-0.3.15 → fast_agent_mcp-0.3.17}/examples/new-api/textual_markdown_demo.py

@@ -20,12 +20,9 @@ from fast_agent import FastAgent
 from fast_agent.constants import REASONING
 from fast_agent.mcp.helpers.content_helpers import get_text
 from fast_agent.types import PromptMessageExtended
-from fast_agent.ui.console_display import (
-    MESSAGE_CONFIGS,
-    ConsoleDisplay,
-    MessageType,
-    _prepare_markdown_content,
-)
+from fast_agent.ui.console_display import ConsoleDisplay
+from fast_agent.ui.markdown_helpers import prepare_markdown_content
+from fast_agent.ui.message_primitives import MESSAGE_CONFIGS, MessageType
 
 if TYPE_CHECKING:
     from mcp.types import CallToolResult
@@ -208,7 +205,7 @@ class ChatDisplay(RichLog):
             if formatted:
                 segments.append(Markdown(formatted))
         else:
-            prepared = _prepare_markdown_content(content, True) if content else ""
+            prepared = prepare_markdown_content(content, True) if content else ""
             if prepared:
                 segments.append(Markdown(prepared))
 
@@ -362,6 +359,7 @@ class TextualDisplay(ConsoleDisplay):
         name: str | None = None,
         highlight_index: int | None = None,
         max_item_length: int | None = None,
+        metadata: dict | None = None,
     ) -> None:
         self._app.handle_display_tool_call(
             agent_name=name,
@@ -370,6 +368,7 @@ class TextualDisplay(ConsoleDisplay):
             bottom_items=bottom_items,
             highlight_index=highlight_index,
             max_item_length=max_item_length,
+            metadata=metadata,
         )
 
     def show_tool_result(
@@ -680,23 +679,63 @@ class MarkdownLLMApp(App[None]):
         bottom_items: list[str] | None,
         highlight_index: int | None,
         max_item_length: int | None,
+        metadata: dict | None,
     ) -> None:
-        if tool_args:
-            try:
-                args_text = json.dumps(tool_args, indent=2, sort_keys=True)
-            except TypeError:  # pragma: no cover - fallback for unserializable args
-                args_text = str(tool_args)
-            content = f"```json\n{args_text}\n```"
+        metadata = metadata or {}
+
+        if metadata.get("variant") == "shell":
+            command = metadata.get("command") or tool_args.get("command")
+            command_display = command if isinstance(command, str) and command.strip() else None
+            if command_display:
+                content = f"```shell\n$ {command_display}\n```"
+            else:
+                content = "_No shell command provided._"
+
+            details: list[str] = []
+            shell_name = metadata.get("shell_name")
+            shell_path = metadata.get("shell_path")
+            if shell_name or shell_path:
+                if shell_name and shell_path and shell_path != shell_name:
+                    details.append(f"shell: {shell_name} ({shell_path})")
+                elif shell_path:
+                    details.append(f"shell: {shell_path}")
+                elif shell_name:
+                    details.append(f"shell: {shell_name}")
+            working_dir = metadata.get("working_dir_display") or metadata.get("working_dir")
+            if working_dir:
+                details.append(f"cwd: {working_dir}")
+
+            capability_bits: list[str] = []
+            if metadata.get("streams_output"):
+                capability_bits.append("streams stdout/stderr")
+            if metadata.get("returns_exit_code"):
+                capability_bits.append("reports exit code")
+
+            if capability_bits:
+                details.append("; ".join(capability_bits))
+
+            if details:
+                bullet_points = "\n".join(f"- {line}" for line in details)
+                content = f"{content}\n\n{bullet_points}"
         else:
-            content = "_No arguments provided._"
+            if tool_args:
+                try:
+                    args_text = json.dumps(tool_args, indent=2, sort_keys=True)
+                except TypeError:  # pragma: no cover - fallback for unserializable args
+                    args_text = str(tool_args)
+                content = f"```json\n{args_text}\n```"
+            else:
+                content = "_No arguments provided._"
 
         self._active_assistant_message = None
 
+        right_info = "shell command" if metadata.get("variant") == "shell" else f"tool request - {tool_name}"
+
         message = ChatMessage(
             role="tool_call",
             content=content,
             name=agent_name or "Tool",
-            right_info=f"tool request - {tool_name}",
+            right_info=right_info,
             bottom_metadata=bottom_items,
             highlight_index=highlight_index,
             max_item_length=max_item_length,

{fast_agent_mcp-0.3.15 → fast_agent_mcp-0.3.17}/examples/openapi/agent.py

@@ -1,16 +1,13 @@
 import asyncio
 
 from fast_agent import FastAgent
+from fast_agent.constants import DEFAULT_AGENT_INSTRUCTION
 
 # Create the application
 fast = FastAgent("fast-agent example")
 
 
-default_instruction = """You are a helpful AI Agent.
-
-{{serverInstructions}}
-
-The current date is {{currentDate}}."""
+default_instruction = DEFAULT_AGENT_INSTRUCTION
 
 
 # Define the agent

{fast_agent_mcp-0.3.15/src/fast_agent/resources → fast_agent_mcp-0.3.17/examples}/setup/agent.py

@@ -10,6 +10,8 @@ default_instruction = """You are a helpful AI Agent.
 
 {{serverInstructions}}
 
+{{agentSkills}}
+
 The current date is {{currentDate}}."""
 
 

{fast_agent_mcp-0.3.15 → fast_agent_mcp-0.3.17}/examples/setup/fastagent.config.yaml

@@ -20,6 +20,12 @@ mcp_timeline:
   steps: 20 # number of timeline buckets to render
   step_seconds: 15 # seconds per bucket (accepts values like "45s", "2m")
 
+#shell_execution:
+# length of time before terminating subprocess
+#  timeout_seconds: 20
+# warning interval if no output seen
+#  warning_seconds: 5
+
 # Logging and Console Configuration:
 logger:
   # level: "debug" | "info" | "warning" | "error"

{fast_agent_mcp-0.3.15 → fast_agent_mcp-0.3.17}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fast-agent-mcp"
-version = "0.3.15"
+version = "0.3.17"
 description = "Define, Prompt and Test MCP enabled Agents and Workflows"
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -15,7 +15,7 @@ classifiers = [
 requires-python = ">=3.13.5,<3.14"
 dependencies = [
     "fastapi>=0.115.6",
-    "mcp==1.18.0",
+    "mcp==1.19.0",
     "opentelemetry-distro>=0.55b0",
     "opentelemetry-exporter-otlp-proto-http>=1.7.0",
     "pydantic-settings>=2.7.0",
@@ -23,24 +23,25 @@ dependencies = [
     "pyyaml>=6.0.2",
     "rich>=14.1.0",
     "typer>=0.15.1",
-    "anthropic>=0.69.0",
-    "openai>=2.3.0",
+    "anthropic>=0.71.0",
+    "openai[aiohttp]>=2.6.1",
     "azure-identity>=1.14.0",
     "boto3>=1.35.0",
     "prompt-toolkit>=3.0.52",
-    "aiohttp>=3.11.13",
+    "aiohttp>=3.13.1",
     "opentelemetry-instrumentation-openai>=0.43.1; python_version >= '3.10' and python_version < '4.0'",
     "opentelemetry-instrumentation-anthropic>=0.43.1; python_version >= '3.10' and python_version < '4.0'",
     "opentelemetry-instrumentation-mcp>=0.43.1; python_version >= '3.10' and python_version < '4.0'",
-    "google-genai>=1.33.0",
+    "google-genai>=1.46.0",
     "opentelemetry-instrumentation-google-genai>=0.3b0",
     "tensorzero>=2025.7.5",
     "deprecated>=1.2.18",
-    "a2a-sdk>=0.3.6",
+    "a2a-sdk>=0.3.10",
     "email-validator>=2.2.0",
     "pyperclip>=1.9.0",
     "keyring>=24.3.1",
     "textual>=6.2.1",
+    "python-frontmatter>=1.1.0",
 ]
 
 # For Azure OpenAI with DefaultAzureCredential support, install with: pip install fast-agent-mcp[azure]

{fast_agent_mcp-0.3.15 → fast_agent_mcp-0.3.17}/src/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_mcp-0.3.15 → fast_agent_mcp-0.3.17}/src/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_mcp-0.3.15 → fast_agent_mcp-0.3.17}/src/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_mcp-0.3.15 → fast_agent_mcp-0.3.17}/src/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_mcp-0.3.15 → fast_agent_mcp-0.3.17}/src/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("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_mcp-0.3.17/src/fast_agent/cli/__main__.py

@@ -0,0 +1,73 @@
+import asyncio
+import json
+import sys
+
+from fast_agent.cli.constants import GO_SPECIFIC_OPTIONS, KNOWN_SUBCOMMANDS
+from fast_agent.cli.main import app
+
+# if the arguments would work with "go" we'll just route to it
+
+
+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
+        first_arg = sys.argv[1]
+
+        # Only auto-route if any known go-specific options are present
+        has_go_options = any(
+            (arg in GO_SPECIFIC_OPTIONS) or any(arg.startswith(opt + "=") for opt in GO_SPECIFIC_OPTIONS)
+            for arg in sys.argv[1:]
+        )
+
+        if first_arg not in KNOWN_SUBCOMMANDS and has_go_options:
+            # Find where to insert 'go' - before the first go-specific option
+            insert_pos = 1
+            for i, arg in enumerate(sys.argv[1:], 1):
+                if (arg in GO_SPECIFIC_OPTIONS) or any(
+                    arg.startswith(opt + "=") for opt in GO_SPECIFIC_OPTIONS
+                ):
+                    insert_pos = i
+                    break
+            # Auto-route to go command
+            sys.argv.insert(insert_pos, "go")
+
+    app()
+
+
+if __name__ == "__main__":
+    main()