chore: import upstream snapshot with attribution

python/samples/02-agents/harness/console/commands/__init__.py

@@ -0,0 +1,65 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Command handler package for the harness console.
+
+Provides slash-command handling (e.g., /exit, /mode, /todos, /session-export)
+that intercepts user input before it reaches the agent.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .base import CommandHandler
+from .exit_handler import ExitCommandHandler
+from .mode_handler import ModeCommandHandler
+from .session_handler import SessionCommandHandler
+from .todo_handler import TodoCommandHandler
+
+if TYPE_CHECKING:
+    from agent_framework import Agent
+
+__all__ = [
+    "CommandHandler",
+    "ExitCommandHandler",
+    "ModeCommandHandler",
+    "SessionCommandHandler",
+    "TodoCommandHandler",
+    "build_default_command_handlers",
+]
+
+
+def build_default_command_handlers(
+    agent: Agent,
+    *,
+    mode_colors: dict[str, str] | None = None,
+) -> list[CommandHandler]:
+    """Build the default set of command handlers by inspecting the agent.
+
+    Auto-detects TodoProvider and AgentModeProvider from the agent's
+    context_providers list.
+
+    Args:
+        agent: The agent to inspect for providers.
+        mode_colors: Optional mapping of mode names to Rich color strings.
+
+    Returns:
+        List of command handlers in evaluation order.
+    """
+    from agent_framework import AgentModeProvider, TodoProvider
+
+    todo_provider: TodoProvider | None = None
+    mode_provider: AgentModeProvider | None = None
+
+    for provider in getattr(agent, "context_providers", []):
+        if isinstance(provider, TodoProvider) and todo_provider is None:
+            todo_provider = provider
+        elif isinstance(provider, AgentModeProvider) and mode_provider is None:
+            mode_provider = provider
+
+    return [
+        ExitCommandHandler(),
+        TodoCommandHandler(todo_provider),
+        ModeCommandHandler(mode_provider, mode_colors),
+        SessionCommandHandler(),
+    ]

python/samples/02-agents/harness/console/commands/base.py

@@ -0,0 +1,58 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Abstract base class for console command handlers.
+
+Command handlers intercept user input starting with '/' and execute
+local commands before input reaches the agent. They are checked in order;
+the first handler that accepts the input prevents further handlers from
+being checked.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from agent_framework import AgentSession
+
+    from ..state_driver import IUXStateDriver
+
+
+class CommandHandler(ABC):
+    """Base class for console command handlers.
+
+    Subclasses implement get_help_text() for the mode bar and
+    try_handle() to intercept matching commands.
+    """
+
+    @abstractmethod
+    def get_help_text(self) -> str | None:
+        """Get the help text for this command.
+
+        Displayed in the mode-and-help bar. Return None if the
+        command is not currently available.
+
+        Returns:
+            Help text like '/todos (show todo list)', or None.
+        """
+        ...
+
+    @abstractmethod
+    async def try_handle(
+        self,
+        user_input: str,
+        session: AgentSession,
+        ux: IUXStateDriver,
+    ) -> bool:
+        """Attempt to handle the given user input.
+
+        Args:
+            user_input: The raw user input string.
+            session: The current agent session.
+            ux: The UX state driver for rendering output.
+
+        Returns:
+            True if this handler handled the input; False otherwise.
+        """
+        ...

python/samples/02-agents/harness/console/commands/exit_handler.py

@@ -0,0 +1,35 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Exit command handler — /exit to quit the console."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .base import CommandHandler
+
+if TYPE_CHECKING:
+    from agent_framework import AgentSession
+
+    from ..state_driver import IUXStateDriver
+
+
+class ExitCommandHandler(CommandHandler):
+    """Handle the /exit command to shut down the console application."""
+
+    def get_help_text(self) -> str | None:
+        """Return help text for the exit command."""
+        return "/exit (quit)"
+
+    async def try_handle(
+        self,
+        user_input: str,
+        session: AgentSession,
+        ux: IUXStateDriver,
+    ) -> bool:
+        """Handle /exit by requesting shutdown."""
+        if user_input.strip().lower() != "/exit":
+            return False
+
+        ux.request_shutdown()
+        return True

python/samples/02-agents/harness/console/commands/mode_handler.py

@@ -0,0 +1,91 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Mode command handler — /mode to show or switch agent mode."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .base import CommandHandler
+
+if TYPE_CHECKING:
+    from agent_framework import AgentModeProvider, AgentSession
+
+    from ..state_driver import IUXStateDriver
+
+
+class ModeCommandHandler(CommandHandler):
+    """Handle the /mode command to display or switch the current agent mode."""
+
+    def __init__(
+        self,
+        mode_provider: AgentModeProvider | None,
+        mode_colors: dict[str, str] | None = None,
+    ) -> None:
+        """Initialize with mode provider and color mapping.
+
+        Args:
+            mode_provider: The mode provider, or None if not available.
+            mode_colors: Optional mapping of mode names to Rich color strings.
+        """
+        self._mode_provider = mode_provider
+        self._mode_colors = mode_colors or {}
+
+    def get_help_text(self) -> str | None:
+        """Return help text, or None if mode provider is unavailable."""
+        if self._mode_provider is None:
+            return None
+        return "/mode [plan|execute] (show or switch mode)"
+
+    async def try_handle(
+        self,
+        user_input: str,
+        session: AgentSession,
+        ux: IUXStateDriver,
+    ) -> bool:
+        """Handle /mode [name] command."""
+        stripped = user_input.strip()
+        lower = stripped.lower()
+
+        if not (lower == "/mode" or lower.startswith("/mode ")):
+            return False
+
+        if self._mode_provider is None:
+            ux.append_info_line("AgentModeProvider is not available.")
+            return True
+
+        parts = stripped.split(None, 1)
+        if len(parts) < 2:
+            # Show current mode
+            from agent_framework import get_agent_mode
+
+            current = get_agent_mode(
+                session,
+                source_id=self._mode_provider.source_id,
+                default_mode=self._mode_provider.default_mode,
+                available_modes=self._mode_provider.available_modes,
+            )
+            ux.append_info_line(f"Current mode: {current}")
+            return True
+
+        # Switch mode
+        new_mode = parts[1].strip()
+        try:
+            from agent_framework import set_agent_mode
+
+            normalized = set_agent_mode(
+                session,
+                new_mode,
+                source_id=self._mode_provider.source_id,
+                available_modes=self._mode_provider.available_modes,
+            )
+            color = self._mode_colors.get(normalized)
+            ux.set_mode(normalized, color)
+            ux.append_info_line(
+                f"Switched to {normalized} mode.",
+                color=color,
+            )
+        except ValueError as ex:
+            ux.append_info_line(str(ex), color="red")
+
+        return True

python/samples/02-agents/harness/console/commands/session_handler.py

@@ -0,0 +1,107 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Session command handler — /session-export and /session-import."""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING
+
+from .base import CommandHandler
+
+if TYPE_CHECKING:
+    from agent_framework import AgentSession
+
+    from ..state_driver import IUXStateDriver
+
+
+class SessionCommandHandler(CommandHandler):
+    """Handle /session-export and /session-import commands."""
+
+    def get_help_text(self) -> str | None:
+        """Return help text for session commands."""
+        return "/session-export <file> | /session-import <file>"
+
+    async def try_handle(
+        self,
+        user_input: str,
+        session: AgentSession,
+        ux: IUXStateDriver,
+    ) -> bool:
+        """Handle session export/import commands."""
+        stripped = user_input.strip()
+        command = stripped.split(None, 1)[0].lower() if stripped else ""
+
+        if command == "/session-export":
+            await self._handle_export(stripped, session, ux)
+            return True
+
+        if command == "/session-import":
+            await self._handle_import(stripped, ux)
+            return True
+
+        return False
+
+    async def _handle_export(
+        self,
+        user_input: str,
+        session: AgentSession,
+        ux: IUXStateDriver,
+    ) -> None:
+        """Export the current session to a JSON file."""
+        parts = user_input.split(None, 1)
+        if len(parts) < 2:
+            ux.append_info_line("Usage: /session-export <filename>")
+            return
+
+        filename = parts[1].strip()
+        try:
+            serialized = session.to_dict()
+            json_str = json.dumps(serialized, indent=2)
+            self._write_file(filename, json_str)
+            ux.append_info_line(f"Session exported to {filename}")
+        except Exception as ex:
+            ux.append_info_line(
+                f"Failed to export session to {filename}: {ex}",
+                color="red",
+            )
+
+    async def _handle_import(
+        self,
+        user_input: str,
+        ux: IUXStateDriver,
+    ) -> None:
+        """Import a session from a JSON file."""
+        parts = user_input.split(None, 1)
+        if len(parts) < 2:
+            ux.append_info_line("Usage: /session-import <filename>")
+            return
+
+        filename = parts[1].strip()
+        try:
+            from agent_framework import AgentSession
+
+            json_str = self._read_file(filename)
+            data = json.loads(json_str)
+            new_session = AgentSession.from_dict(data)
+            ux.replace_session(new_session)
+            ux.append_info_line(f"Session imported from {filename}")
+        except FileNotFoundError:
+            ux.append_info_line(f"File not found: {filename}", color="red")
+        except Exception as ex:
+            ux.append_info_line(
+                f"Failed to import session from {filename}: {ex}",
+                color="red",
+            )
+
+    @staticmethod
+    def _write_file(filename: str, content: str) -> None:
+        """Write content to a file (sync helper to satisfy ASYNC230)."""
+        with open(filename, "w", encoding="utf-8") as f:  # noqa: ASYNC230
+            f.write(content)
+
+    @staticmethod
+    def _read_file(filename: str) -> str:
+        """Read content from a file (sync helper to satisfy ASYNC230)."""
+        with open(filename, encoding="utf-8") as f:  # noqa: ASYNC230
+            return f.read()

python/samples/02-agents/harness/console/commands/todo_handler.py

@@ -0,0 +1,64 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Todo command handler — /todos to display the todo list."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .base import CommandHandler
+
+if TYPE_CHECKING:
+    from agent_framework import AgentSession, TodoProvider
+
+    from ..state_driver import IUXStateDriver
+
+
+class TodoCommandHandler(CommandHandler):
+    """Handle the /todos command to display the current todo list."""
+
+    def __init__(self, todo_provider: TodoProvider | None) -> None:
+        """Initialize with the todo provider.
+
+        Args:
+            todo_provider: The todo provider, or None if not available.
+        """
+        self._todo_provider = todo_provider
+
+    def get_help_text(self) -> str | None:
+        """Return help text, or None if todo provider is unavailable."""
+        if self._todo_provider is None:
+            return None
+        return "/todos (show todo list)"
+
+    async def try_handle(
+        self,
+        user_input: str,
+        session: AgentSession,
+        ux: IUXStateDriver,
+    ) -> bool:
+        """Handle /todos by displaying the todo list."""
+        if user_input.strip().lower() != "/todos":
+            return False
+
+        if self._todo_provider is None:
+            ux.append_info_line("TodoProvider is not available.")
+            return True
+
+        todos = await self._todo_provider.store.load_items(session, source_id=self._todo_provider.source_id)
+
+        if not todos:
+            ux.append_info_line("No todos yet.")
+            return True
+
+        ux.append_info_line("── Todo List ──")
+        for item in todos:
+            status = "✓" if item.is_complete else "○"
+            color = "dim" if item.is_complete else None
+            description = f" — {item.description}" if item.description else ""
+            ux.append_info_line(
+                f"[{status}] #{item.id} {item.title}{description}",
+                color=color,
+            )
+
+        return True