chore: import upstream snapshot with attribution

dotnet/samples/02-agents/Harness/Harness_Shared_Console/Commands/CommandHandler.cs

@@ -0,0 +1,29 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Agents.AI;
+
+namespace Harness.Shared.Console.Commands;
+
+/// <summary>
+/// Base class for console command handlers (e.g., /todos, /mode). Command handlers
+/// are checked in order before user input is sent to the agent. The first handler
+/// that accepts the input prevents further handlers from being checked.
+/// </summary>
+public abstract class CommandHandler
+{
+    /// <summary>
+    /// Gets the help text for this command, displayed in the mode-and-help bar.
+    /// Returns <see langword="null"/> if the command is not currently available.
+    /// </summary>
+    /// <returns>Help text like <c>"/todos (show todo list)"</c>, or <see langword="null"/>.</returns>
+    public abstract string? GetHelpText();
+
+    /// <summary>
+    /// Attempts to handle the given user input.
+    /// </summary>
+    /// <param name="input">The raw user input string.</param>
+    /// <param name="session">The current agent session.</param>
+    /// <param name="ux">The UX state driver for rendering output.</param>
+    /// <returns><see langword="true"/> if this handler handled the input; <see langword="false"/> otherwise.</returns>
+    public abstract ValueTask<bool> TryHandleAsync(string input, AgentSession session, IUXStateDriver ux);
+}

dotnet/samples/02-agents/Harness/Harness_Shared_Console/Commands/ExitCommandHandler.cs

@@ -0,0 +1,26 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Agents.AI;
+
+namespace Harness.Shared.Console.Commands;
+
+/// <summary>
+/// Handles the <c>/exit</c> command to shut down the console application.
+/// </summary>
+public sealed class ExitCommandHandler : CommandHandler
+{
+    /// <inheritdoc/>
+    public override string? GetHelpText() => "/exit (quit)";
+
+    /// <inheritdoc/>
+    public override ValueTask<bool> TryHandleAsync(string input, AgentSession session, IUXStateDriver ux)
+    {
+        if (!input.Equals("/exit", StringComparison.OrdinalIgnoreCase))
+        {
+            return new ValueTask<bool>(false);
+        }
+
+        ux.RequestShutdown();
+        return new ValueTask<bool>(true);
+    }
+}

dotnet/samples/02-agents/Harness/Harness_Shared_Console/Commands/ModeCommandHandler.cs

@@ -0,0 +1,66 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Agents.AI;
+
+namespace Harness.Shared.Console.Commands;
+
+/// <summary>
+/// Handles the <c>/mode</c> command to display or switch the current agent mode.
+/// </summary>
+public sealed class ModeCommandHandler : CommandHandler
+{
+    private readonly AgentModeProvider? _modeProvider;
+    private readonly IReadOnlyDictionary<string, ConsoleColor>? _modeColors;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="ModeCommandHandler"/> class.
+    /// </summary>
+    /// <param name="modeProvider">The mode provider, or <see langword="null"/> if not available.</param>
+    /// <param name="modeColors">Optional mapping of mode names to console colors.</param>
+    public ModeCommandHandler(AgentModeProvider? modeProvider, IReadOnlyDictionary<string, ConsoleColor>? modeColors = null)
+    {
+        this._modeProvider = modeProvider;
+        this._modeColors = modeColors;
+    }
+
+    /// <inheritdoc/>
+    public override string? GetHelpText() => this._modeProvider is not null ? "/mode [plan|execute] (show or switch mode)" : null;
+
+    /// <inheritdoc/>
+    public override async ValueTask<bool> TryHandleAsync(string input, AgentSession session, IUXStateDriver ux)
+    {
+        if (!input.StartsWith("/mode ", StringComparison.OrdinalIgnoreCase) && !input.Equals("/mode", StringComparison.OrdinalIgnoreCase))
+        {
+            return false;
+        }
+
+        if (this._modeProvider is null)
+        {
+            await ux.WriteInfoLineAsync("AgentModeProvider is not available.").ConfigureAwait(false);
+            return true;
+        }
+
+        string[] parts = input.Split(' ', 2, StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries);
+        if (parts.Length < 2)
+        {
+            string current = this._modeProvider.GetMode(session);
+            await ux.WriteInfoLineAsync($"Current mode: {current}").ConfigureAwait(false);
+            return true;
+        }
+
+        string newMode = parts[1];
+
+        try
+        {
+            this._modeProvider.SetMode(session, newMode);
+            ux.CurrentMode = newMode;
+            await ux.WriteInfoLineAsync($"Switched to {newMode} mode.", ModeColors.Get(newMode, this._modeColors)).ConfigureAwait(false);
+        }
+        catch (ArgumentException ex)
+        {
+            await ux.WriteInfoLineAsync(ex.Message, ConsoleColor.Red).ConfigureAwait(false);
+        }
+
+        return true;
+    }
+}

dotnet/samples/02-agents/Harness/Harness_Shared_Console/Commands/SessionCommandHandler.cs

@@ -0,0 +1,98 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text.Json;
+using Microsoft.Agents.AI;
+
+namespace Harness.Shared.Console.Commands;
+
+/// <summary>
+/// Handles <c>/session-export &lt;filename&gt;</c> and <c>/session-import &lt;filename&gt;</c>
+/// commands for serializing the current session to a file and restoring a session from a file.
+/// </summary>
+public sealed class SessionCommandHandler : CommandHandler
+{
+    private readonly AIAgent _agent;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="SessionCommandHandler"/> class.
+    /// </summary>
+    /// <param name="agent">The agent used for session serialization and deserialization.</param>
+    public SessionCommandHandler(AIAgent agent)
+    {
+        this._agent = agent;
+    }
+
+    /// <inheritdoc/>
+    public override string? GetHelpText() => "/session-export <file> | /session-import <file>";
+
+    /// <inheritdoc/>
+    public override async ValueTask<bool> TryHandleAsync(string input, AgentSession session, IUXStateDriver ux)
+    {
+        string command = input.Split(' ', 2)[0];
+
+        if (command.Equals("/session-export", StringComparison.OrdinalIgnoreCase))
+        {
+            await this.HandleExportAsync(input, session, ux).ConfigureAwait(false);
+            return true;
+        }
+
+        if (command.Equals("/session-import", StringComparison.OrdinalIgnoreCase))
+        {
+            await this.HandleImportAsync(input, ux).ConfigureAwait(false);
+            return true;
+        }
+
+        return false;
+    }
+
+    private async Task HandleExportAsync(string input, AgentSession session, IUXStateDriver ux)
+    {
+        string[] parts = input.Split(' ', 2, StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries);
+        if (parts.Length < 2)
+        {
+            await ux.WriteInfoLineAsync("Usage: /session-export <filename>").ConfigureAwait(false);
+            return;
+        }
+
+        string filename = parts[1];
+        try
+        {
+            JsonElement serialized = await this._agent.SerializeSessionAsync(session).ConfigureAwait(false);
+            string json = JsonSerializer.Serialize(serialized);
+            await File.WriteAllTextAsync(filename, json).ConfigureAwait(false);
+            await ux.WriteInfoLineAsync($"Session exported to {filename}").ConfigureAwait(false);
+        }
+        catch (Exception ex)
+        {
+            await ux.WriteInfoLineAsync($"Failed to export session to {filename}: {ex.Message}").ConfigureAwait(false);
+        }
+    }
+
+    private async Task HandleImportAsync(string input, IUXStateDriver ux)
+    {
+        string[] parts = input.Split(' ', 2, StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries);
+        if (parts.Length < 2)
+        {
+            await ux.WriteInfoLineAsync("Usage: /session-import <filename>").ConfigureAwait(false);
+            return;
+        }
+
+        string filename = parts[1];
+        try
+        {
+            string json = await File.ReadAllTextAsync(filename).ConfigureAwait(false);
+            JsonElement element = JsonSerializer.Deserialize<JsonElement>(json);
+            AgentSession newSession = await this._agent.DeserializeSessionAsync(element).ConfigureAwait(false);
+            await ux.ReplaceSessionAsync(newSession).ConfigureAwait(false);
+            await ux.WriteInfoLineAsync($"Session imported from {filename}").ConfigureAwait(false);
+        }
+        catch (FileNotFoundException)
+        {
+            await ux.WriteInfoLineAsync($"File not found: {filename}").ConfigureAwait(false);
+        }
+        catch (Exception ex)
+        {
+            await ux.WriteInfoLineAsync($"Failed to import session from {filename}: {ex.Message}").ConfigureAwait(false);
+        }
+    }
+}

dotnet/samples/02-agents/Harness/Harness_Shared_Console/Commands/TodoCommandHandler.cs

@@ -0,0 +1,60 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Agents.AI;
+
+namespace Harness.Shared.Console.Commands;
+
+/// <summary>
+/// Handles the <c>/todos</c> command to display the current todo list.
+/// </summary>
+public sealed class TodoCommandHandler : CommandHandler
+{
+    private readonly TodoProvider? _todoProvider;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="TodoCommandHandler"/> class.
+    /// </summary>
+    /// <param name="todoProvider">The todo provider, or <see langword="null"/> if not available.</param>
+    public TodoCommandHandler(TodoProvider? todoProvider)
+    {
+        this._todoProvider = todoProvider;
+    }
+
+    /// <inheritdoc/>
+    public override string? GetHelpText() => this._todoProvider is not null ? "/todos (show todo list)" : null;
+
+    /// <inheritdoc/>
+    public override async ValueTask<bool> TryHandleAsync(string input, AgentSession session, IUXStateDriver ux)
+    {
+        if (!input.Equals("/todos", StringComparison.OrdinalIgnoreCase))
+        {
+            return false;
+        }
+
+        if (this._todoProvider is null)
+        {
+            await ux.WriteInfoLineAsync("TodoProvider is not available.").ConfigureAwait(false);
+            return true;
+        }
+
+        var todos = await this._todoProvider.GetAllTodosAsync(session).ConfigureAwait(false);
+        if (todos.Count == 0)
+        {
+            await ux.WriteInfoLineAsync("No todos yet.").ConfigureAwait(false);
+            return true;
+        }
+
+        await ux.WriteInfoLineAsync("── Todo List ──").ConfigureAwait(false);
+        foreach (var item in todos)
+        {
+            string status = item.IsComplete ? "✓" : "○";
+            ConsoleColor color = item.IsComplete ? ConsoleColor.DarkGray : ConsoleColor.White;
+            string description = string.IsNullOrWhiteSpace(item.Description)
+                ? string.Empty
+                : $" — {item.Description}";
+            await ux.WriteInfoLineAsync($"[{status}] #{item.Id} {item.Title}{description}", color).ConfigureAwait(false);
+        }
+
+        return true;
+    }
+}