fix: honor MEAI instructions and reject unsupported generation options

Author: KSemenenko

CodexSharpSDK.Extensions.AI/CodexChatClient.cs

@@ -27,8 +27,9 @@ public async Task<ChatResponse> GetResponseAsync(
     {
         ArgumentNullException.ThrowIfNull(messages);
         ChatOptionsMapper.ValidateFunctionCallingOptions(options);
+        ChatOptionsMapper.ValidateGenerationOptions(options);
 
-        var (prompt, imageContents) = ChatMessageMapper.ToCodexInput(messages);
+        var (prompt, imageContents) = ChatMessageMapper.ToCodexInput(messages, options?.Instructions);
         var threadOptions = ChatOptionsMapper.ToThreadOptions(options, _options);
         var turnOptions = ChatOptionsMapper.ToTurnOptions(options, cancellationToken);
 
@@ -51,8 +52,9 @@ public async IAsyncEnumerable<ChatResponseUpdate> GetStreamingResponseAsync(
     {
         ArgumentNullException.ThrowIfNull(messages);
         ChatOptionsMapper.ValidateFunctionCallingOptions(options);
+        ChatOptionsMapper.ValidateGenerationOptions(options);
 
-        var (prompt, imageContents) = ChatMessageMapper.ToCodexInput(messages);
+        var (prompt, imageContents) = ChatMessageMapper.ToCodexInput(messages, options?.Instructions);
         var threadOptions = ChatOptionsMapper.ToThreadOptions(options, _options);
         var turnOptions = ChatOptionsMapper.ToTurnOptions(options, cancellationToken);
 

CodexSharpSDK.Extensions.AI/Internal/ChatMessageMapper.cs

@@ -10,9 +10,13 @@ internal static class ChatMessageMapper
     private const string ParagraphSeparator = "\n\n";
     private const string ImageMediaPrefix = "image/";
 
-    internal static (string Prompt, List<DataContent> ImageContents) ToCodexInput(IEnumerable<ChatMessage> messages)
+    internal static (string Prompt, List<DataContent> ImageContents) ToCodexInput(IEnumerable<ChatMessage> messages, string? instructions = null)
     {
         var promptParts = new List<string>();
+        if (!string.IsNullOrWhiteSpace(instructions))
+        {
+            promptParts.Add(string.Concat(SystemPrefix, instructions));
+        }
         var imageContents = new List<DataContent>();
 
         foreach (var message in messages)

CodexSharpSDK.Extensions.AI/Internal/ChatOptionsMapper.cs

@@ -5,6 +5,7 @@ namespace ManagedCode.CodexSharpSDK.Extensions.AI.Internal;
 
 internal static class ChatOptionsMapper
 {
+    private const string GenerationOptionsUnsupportedMessage = "The Codex CLI adapter does not support the requested MEAI generation options.";
     private const string FunctionToolsUnsupportedMessage = "MEAI function tools are not supported by the Codex CLI adapter.";
     private const string ToolModeUnsupportedMessage = "Only automatic MEAI tool mode is supported by the Codex CLI adapter.";
     internal const string SandboxModeKey = "codex:sandbox_mode";
@@ -18,6 +19,17 @@ internal static class ChatOptionsMapper
     internal const string ProfileKey = "codex:profile";
     internal const string SkipGitRepoCheckKey = "codex:skip_git_repo_check";
 
+    internal static void ValidateGenerationOptions(ChatOptions? options)
+    {
+        if (options is { Temperature: not null } or { TopP: not null } or { TopK: not null } or
+            { MaxOutputTokens: not null } or { Seed: not null } or { FrequencyPenalty: not null } or
+            { PresencePenalty: not null } || options?.StopSequences is { Count: > 0 } ||
+            options?.ResponseFormat is { } format && format is not ChatResponseFormatText)
+        {
+            throw new NotSupportedException(GenerationOptionsUnsupportedMessage);
+        }
+    }
+
     internal static void ValidateFunctionCallingOptions(ChatOptions? chatOptions)
     {
         if (chatOptions?.Tools is { Count: > 0 })

CodexSharpSDK.Tests/MEAI/ChatMessageMapperTests.cs

@@ -6,6 +6,19 @@ namespace ManagedCode.CodexSharpSDK.Extensions.AI.Tests;
 
 public class ChatMessageMapperTests
 {
+    private const string StandardInstructions = "Follow the standard MEAI instructions.";
+    private const string ExistingSystemText = "Existing system message.";
+    private const string UserQuestion = "User question.";
+    private const string ExpectedInstructionPrompt = "[System] Follow the standard MEAI instructions.\n\n[System] Existing system message.\n\nUser question.";
+
+    [Test]
+    public async Task StandardInstructionsPrecedeSystemAndUserMessages()
+    {
+        var messages = new[] { new ChatMessage(ChatRole.System, ExistingSystemText), new ChatMessage(ChatRole.User, UserQuestion) };
+        var (prompt, _) = ChatMessageMapper.ToCodexInput(messages, StandardInstructions);
+        await Assert.That(prompt).IsEqualTo(ExpectedInstructionPrompt);
+    }
+
     [Test]
     public async Task ToCodexInput_TextOnly_ReturnsPrompt()
     {

CodexSharpSDK.Tests/MEAI/UnsupportedToolOptionsTests.cs

@@ -25,6 +25,35 @@ public sealed class UnsupportedToolOptionsTests
     private const string NodeEvalArgument = "-e";
     private const string NodeMarkerScript = "require('node:fs').writeFileSync(process.argv[1], 'started');";
 
+    private const string GenerationStopSequence = "fixture stop";
+
+    [Test]
+    [Arguments(0)]
+    [Arguments(1)]
+    [Arguments(2)]
+    [Arguments(3)]
+    [Arguments(4)]
+    [Arguments(5)]
+    [Arguments(6)]
+    [Arguments(7)]
+    [Arguments(8)]
+    public async Task ExplicitUnsupportedGenerationOptionsFailBeforeNativeExecution(int vector)
+    {
+        var options = vector switch
+        {
+            0 => new ChatOptions { Temperature = 0.5f },
+            1 => new ChatOptions { TopP = 0.5f },
+            2 => new ChatOptions { TopK = 1 },
+            3 => new ChatOptions { MaxOutputTokens = 1 },
+            4 => new ChatOptions { Seed = 1 },
+            5 => new ChatOptions { FrequencyPenalty = 0.5f },
+            6 => new ChatOptions { PresencePenalty = 0.5f },
+            7 => new ChatOptions { StopSequences = [GenerationStopSequence] },
+            _ => new ChatOptions { ResponseFormat = ChatResponseFormat.Json }
+        };
+        await AssertRejectedWithoutLaunchingAsync(options);
+    }
+
     [Test]
     public async Task NonemptyMeaiToolsAreRejectedBeforeLaunchingOrCreatingAThread()
     {
@@ -78,12 +107,8 @@ private static async Task AssertRejectedWithoutLaunchingAsync(ChatOptions option
             await Assert.That(streamError).IsTypeOf<NotSupportedException>();
             await Assert.That(File.Exists(markerPath)).IsFalse();
 
-            var resumeOptions = new ChatOptions
-            {
-                ConversationId = EmptyConversationId,
-                Tools = options.Tools,
-                ToolMode = options.ToolMode,
-            };
+            var resumeOptions = options.Clone();
+            resumeOptions.ConversationId = EmptyConversationId;
             var resumeError = await Assert.That(async () =>
             {
                 _ = await client.GetResponseAsync(CreateMessages(), resumeOptions);

Directory.Build.props

@@ -32,7 +32,7 @@
     <PublishRepositoryUrl>true</PublishRepositoryUrl>
     <EmbedUntrackedSources>true</EmbedUntrackedSources>
     <EnablePackageValidation>true</EnablePackageValidation>
-    <Version>0.160.1.3</Version>
+    <Version>0.160.1.4</Version>
     <PackageVersion>$(Version)</PackageVersion>
   </PropertyGroup>
 

docs/Features/meai-integration.md

@@ -184,3 +184,7 @@ Native provider failures stop producing response updates, but the adapter contin
 - All mapper and DI tests pass.
 - ADR and feature docs created.
 - Architecture overview updated.
+
+## Standard MEAI request options
+
+`ChatOptions.Instructions` is included before the supplied messages using the adapter’s existing system-message mapping in both response modes. Existing system and user messages retain their order. Model selection remains supported through `ModelId`. Explicit temperature, nucleus/top-k sampling, maximum output tokens, seed, penalties, stop sequences and non-text response formats are rejected before any native thread/process starts because this adapter does not implement those generation controls. The core typed `OutputSchema` API remains separate; arbitrary MEAI JSON schemas are not silently approximated.