Added Shell tool abstractions

src/Libraries/Microsoft.Extensions.AI.Abstractions/Contents/AIContent.cs

@@ -38,6 +38,8 @@ namespace Microsoft.Extensions.AI;
 // [JsonDerivedType(typeof(ImageGenerationToolResultContent), typeDiscriminator: "imageGenerationToolResult")]
 // [JsonDerivedType(typeof(WebSearchToolCallContent), typeDiscriminator: "webSearchToolCall")]
 // [JsonDerivedType(typeof(WebSearchToolResultContent), typeDiscriminator: "webSearchToolResult")]
+// [JsonDerivedType(typeof(ShellCallContent), typeDiscriminator: "shellCall")]
+// [JsonDerivedType(typeof(ShellResultContent), typeDiscriminator: "shellResult")]
 
 public class AIContent
 {

src/Libraries/Microsoft.Extensions.AI.Abstractions/Contents/ShellCallContent.cs

@@ -0,0 +1,49 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System;
+using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
+using Microsoft.Shared.DiagnosticIds;
+
+namespace Microsoft.Extensions.AI;
+
+/// <summary>
+/// Represents a shell tool call invocation by a hosted service.
+/// </summary>
+/// <remarks>
+/// This content type is produced by <see cref="IChatClient"/> implementations that have native shell tool support.
+/// It is informational only and represents the call itself, not the result.
+/// </remarks>
+[Experimental(DiagnosticIds.Experiments.AIShell, UrlFormat = DiagnosticIds.UrlFormat)]
+public sealed class ShellCallContent : ToolCallContent
+{
+    /// <summary>
+    /// Initializes a new instance of the <see cref="ShellCallContent"/> class.
+    /// </summary>
+    /// <param name="callId">The tool call ID.</param>
+    public ShellCallContent(string callId)
+        : base(callId)
+    {
+    }
+
+    /// <summary>
+    /// Gets or sets the list of commands to execute.
+    /// </summary>
+    public IList<string>? Commands { get; set; }
+
+    /// <summary>
+    /// Gets or sets the timeout for the shell command execution.
+    /// </summary>
+    public TimeSpan? Timeout { get; set; }
+
+    /// <summary>
+    /// Gets or sets the maximum output length in characters.
+    /// </summary>
+    public int? MaxOutputLength { get; set; }
+
+    /// <summary>
+    /// Gets or sets the status of the shell call.
+    /// </summary>
+    public string? Status { get; set; }
+}

src/Libraries/Microsoft.Extensions.AI.Abstractions/Contents/ShellCommandOutput.cs

@@ -0,0 +1,34 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System.Diagnostics.CodeAnalysis;
+using Microsoft.Shared.DiagnosticIds;
+
+namespace Microsoft.Extensions.AI;
+
+/// <summary>
+/// Represents the output of a single shell command execution.
+/// </summary>
+[Experimental(DiagnosticIds.Experiments.AIShell, UrlFormat = DiagnosticIds.UrlFormat)]
+public class ShellCommandOutput : AIContent
+{
+    /// <summary>
+    /// Gets or sets the standard output of the command.
+    /// </summary>
+    public string? Stdout { get; set; }
+
+    /// <summary>
+    /// Gets or sets the standard error output of the command.
+    /// </summary>
+    public string? Stderr { get; set; }
+
+    /// <summary>
+    /// Gets or sets the exit code of the command, or <see langword="null"/> if the command timed out.
+    /// </summary>
+    public int? ExitCode { get; set; }
+
+    /// <summary>
+    /// Gets or sets a value indicating whether the command execution timed out.
+    /// </summary>
+    public bool TimedOut { get; set; }
+}

src/Libraries/Microsoft.Extensions.AI.Abstractions/Contents/ShellResultContent.cs

@@ -0,0 +1,34 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
+using Microsoft.Shared.DiagnosticIds;
+
+namespace Microsoft.Extensions.AI;
+
+/// <summary>
+/// Represents the result of a shell tool invocation by a hosted service.
+/// </summary>
+[Experimental(DiagnosticIds.Experiments.AIShell, UrlFormat = DiagnosticIds.UrlFormat)]
+public sealed class ShellResultContent : ToolResultContent
+{
+    /// <summary>
+    /// Initializes a new instance of the <see cref="ShellResultContent"/> class.
+    /// </summary>
+    /// <param name="callId">The tool call ID.</param>
+    public ShellResultContent(string callId)
+        : base(callId)
+    {
+    }
+
+    /// <summary>
+    /// Gets or sets the output of the shell command execution.
+    /// </summary>
+    public IList<ShellCommandOutput>? Output { get; set; }
+
+    /// <summary>
+    /// Gets or sets the maximum output length in characters.
+    /// </summary>
+    public int? MaxOutputLength { get; set; }
+}

src/Libraries/Microsoft.Extensions.AI.Abstractions/Contents/ToolCallContent.cs

@@ -22,6 +22,7 @@ namespace Microsoft.Extensions.AI;
 // [JsonDerivedType(typeof(CodeInterpreterToolCallContent), "codeInterpreterToolCall")]
 // [JsonDerivedType(typeof(ImageGenerationToolCallContent), "imageGenerationToolCall")]
 // [JsonDerivedType(typeof(WebSearchToolCallContent), "webSearchToolCall")]
+// [JsonDerivedType(typeof(ShellCallContent), "shellCall")]
 public class ToolCallContent : AIContent
 {
     /// <summary>

src/Libraries/Microsoft.Extensions.AI.Abstractions/Contents/ToolResultContent.cs

@@ -22,6 +22,7 @@ namespace Microsoft.Extensions.AI;
 // [JsonDerivedType(typeof(CodeInterpreterToolResultContent), "codeInterpreterToolResult")]
 // [JsonDerivedType(typeof(ImageGenerationToolResultContent), "imageGenerationToolResult")]
 // [JsonDerivedType(typeof(WebSearchToolResultContent), "webSearchToolResult")]
+// [JsonDerivedType(typeof(ShellResultContent), "shellResult")]
 public class ToolResultContent : AIContent
 {
     /// <summary>

src/Libraries/Microsoft.Extensions.AI.Abstractions/Tools/HostedShellTool.cs

@@ -0,0 +1,38 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
+using Microsoft.Shared.DiagnosticIds;
+
+namespace Microsoft.Extensions.AI;
+
+/// <summary>Represents a hosted tool that can be specified to an AI service to enable it to execute shell commands.</summary>
+/// <remarks>
+/// This tool does not itself implement shell command execution. It is a marker that can be used to inform a service
+/// that the service is allowed to execute shell commands if the service is capable of doing so.
+/// </remarks>
+[Experimental(DiagnosticIds.Experiments.AIShell, UrlFormat = DiagnosticIds.UrlFormat)]
+public class HostedShellTool : AITool
+{
+    /// <summary>Any additional properties associated with the tool.</summary>
+    private IReadOnlyDictionary<string, object?>? _additionalProperties;
+
+    /// <summary>Initializes a new instance of the <see cref="HostedShellTool"/> class.</summary>
+    public HostedShellTool()
+    {
+    }
+
+    /// <summary>Initializes a new instance of the <see cref="HostedShellTool"/> class.</summary>
+    /// <param name="additionalProperties">Any additional properties associated with the tool.</param>
+    public HostedShellTool(IReadOnlyDictionary<string, object?>? additionalProperties)
+    {
+        _additionalProperties = additionalProperties;
+    }
+
+    /// <inheritdoc />
+    public override string Name => "shell";
+
+    /// <inheritdoc />
+    public override IReadOnlyDictionary<string, object?> AdditionalProperties => _additionalProperties ?? base.AdditionalProperties;
+}

src/Libraries/Microsoft.Extensions.AI.Abstractions/Utilities/AIJsonUtilities.Defaults.cs

@@ -57,14 +57,18 @@ private static JsonSerializerOptions CreateDefaultOptions()
         AddAIContentType(options, typeof(AIContent), typeof(ImageGenerationToolResultContent), typeDiscriminatorId: "imageGenerationToolResult", checkBuiltIn: false);
         AddAIContentType(options, typeof(AIContent), typeof(WebSearchToolCallContent), typeDiscriminatorId: "webSearchToolCall", checkBuiltIn: false);
         AddAIContentType(options, typeof(AIContent), typeof(WebSearchToolResultContent), typeDiscriminatorId: "webSearchToolResult", checkBuiltIn: false);
+        AddAIContentType(options, typeof(AIContent), typeof(ShellCallContent), typeDiscriminatorId: "shellCall", checkBuiltIn: false);
+        AddAIContentType(options, typeof(AIContent), typeof(ShellResultContent), typeDiscriminatorId: "shellResult", checkBuiltIn: false);
 
         // Also register the experimental types as derived types of ToolCallContent/ToolResultContent.
         AddAIContentType(options, typeof(ToolCallContent), typeof(CodeInterpreterToolCallContent), "codeInterpreterToolCall", checkBuiltIn: false);
         AddAIContentType(options, typeof(ToolCallContent), typeof(ImageGenerationToolCallContent), "imageGenerationToolCall", checkBuiltIn: false);
         AddAIContentType(options, typeof(ToolCallContent), typeof(WebSearchToolCallContent), "webSearchToolCall", checkBuiltIn: false);
+        AddAIContentType(options, typeof(ToolCallContent), typeof(ShellCallContent), "shellCall", checkBuiltIn: false);
         AddAIContentType(options, typeof(ToolResultContent), typeof(CodeInterpreterToolResultContent), "codeInterpreterToolResult", checkBuiltIn: false);
         AddAIContentType(options, typeof(ToolResultContent), typeof(ImageGenerationToolResultContent), "imageGenerationToolResult", checkBuiltIn: false);
         AddAIContentType(options, typeof(ToolResultContent), typeof(WebSearchToolResultContent), "webSearchToolResult", checkBuiltIn: false);
+        AddAIContentType(options, typeof(ToolResultContent), typeof(ShellResultContent), "shellResult", checkBuiltIn: false);
 
         if (JsonSerializer.IsReflectionEnabledByDefault)
         {
@@ -135,6 +139,9 @@ private static JsonSerializerOptions CreateDefaultOptions()
     [JsonSerializable(typeof(ImageGenerationToolResultContent))]
     [JsonSerializable(typeof(WebSearchToolCallContent))]
     [JsonSerializable(typeof(WebSearchToolResultContent))]
+    [JsonSerializable(typeof(ShellCallContent))]
+    [JsonSerializable(typeof(ShellResultContent))]
+    [JsonSerializable(typeof(ShellCommandOutput))]
     [JsonSerializable(typeof(ResponseContinuationToken))]
 
     // IEmbeddingGenerator

src/Shared/DiagnosticIds/DiagnosticIds.cs

@@ -57,6 +57,7 @@ internal static class Experiments
         internal const string AIResponseContinuations = AIExperiments;
         internal const string AICodeInterpreter = AIExperiments;
         internal const string AIWebSearch = AIExperiments;
+        internal const string AIShell = AIExperiments;
         internal const string AIRealTime = AIExperiments;
         internal const string AIFiles = AIExperiments;
 

test/Libraries/Microsoft.Extensions.AI.Abstractions.Tests/Contents/ShellCallContentTests.cs

@@ -0,0 +1,101 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System;
+using System.Collections.Generic;
+using System.Text.Json;
+using Xunit;
+
+namespace Microsoft.Extensions.AI;
+
+public class ShellCallContentTests
+{
+    [Fact]
+    public void Constructor_PropsDefault()
+    {
+        ShellCallContent content = new("call123");
+        Assert.Equal("call123", content.CallId);
+        Assert.Null(content.Commands);
+        Assert.Null(content.Timeout);
+        Assert.Null(content.MaxOutputLength);
+        Assert.Null(content.Status);
+    }
+
+    [Fact]
+    public void Properties_Roundtrip()
+    {
+        ShellCallContent content = new("call123");
+
+        Assert.Null(content.Commands);
+        IList<string> commands = ["ls -la", "pwd"];
+        content.Commands = commands;
+        Assert.Same(commands, content.Commands);
+
+        Assert.Null(content.Timeout);
+        content.Timeout = TimeSpan.FromMinutes(2);
+        Assert.Equal(TimeSpan.FromMinutes(2), content.Timeout);
+
+        Assert.Null(content.MaxOutputLength);
+        content.MaxOutputLength = 4096;
+        Assert.Equal(4096, content.MaxOutputLength);
+
+        Assert.Null(content.Status);
+        content.Status = "completed";
+        Assert.Equal("completed", content.Status);
+
+        Assert.Null(content.RawRepresentation);
+        object raw = new();
+        content.RawRepresentation = raw;
+        Assert.Same(raw, content.RawRepresentation);
+
+        Assert.Null(content.AdditionalProperties);
+        AdditionalPropertiesDictionary props = new() { { "key", "value" } };
+        content.AdditionalProperties = props;
+        Assert.Same(props, content.AdditionalProperties);
+    }
+
+    [Fact]
+    public void Serialization_Roundtrips()
+    {
+        ShellCallContent content = new("call123")
+        {
+            Commands = ["ls -la", "pwd"],
+            Timeout = TimeSpan.FromSeconds(60),
+            MaxOutputLength = 4096,
+            Status = "completed",
+        };
+
+        var json = JsonSerializer.Serialize(content, AIJsonUtilities.DefaultOptions);
+        var deserializedSut = JsonSerializer.Deserialize<ShellCallContent>(json, AIJsonUtilities.DefaultOptions);
+
+        Assert.NotNull(deserializedSut);
+        Assert.Equal("call123", deserializedSut.CallId);
+        Assert.NotNull(deserializedSut.Commands);
+        Assert.Equal(2, deserializedSut.Commands.Count);
+        Assert.Equal("ls -la", deserializedSut.Commands[0]);
+        Assert.Equal("pwd", deserializedSut.Commands[1]);
+        Assert.Equal(TimeSpan.FromSeconds(60), deserializedSut.Timeout);
+        Assert.Equal(4096, deserializedSut.MaxOutputLength);
+        Assert.Equal("completed", deserializedSut.Status);
+    }
+
+    [Fact]
+    public void Serialization_PolymorphicAsAIContent_Roundtrips()
+    {
+        AIContent content = new ShellCallContent("call123")
+        {
+            Commands = ["echo hello"],
+        };
+
+        var json = JsonSerializer.Serialize(content, AIJsonUtilities.DefaultOptions);
+        Assert.Contains("\"$type\"", json);
+        Assert.Contains("\"shellCall\"", json);
+
+        var deserializedSut = JsonSerializer.Deserialize<AIContent>(json, AIJsonUtilities.DefaultOptions);
+        var shellCall = Assert.IsType<ShellCallContent>(deserializedSut);
+        Assert.Equal("call123", shellCall.CallId);
+        Assert.NotNull(shellCall.Commands);
+        Assert.Single(shellCall.Commands);
+        Assert.Equal("echo hello", shellCall.Commands[0]);
+    }
+}