Fix AI chat Responses API tool-chaining and context limit handling

- Fix streaming tool continuations: track currentLegResponseId from
  StreamingResponseCreatedUpdate and clone options with that ID before
  calling ExecuteFunctionCallAsync, so the continuation correctly
  references the response that produced the function call (not the
  outer conversation root).

- Fix non-streaming loop token waste: after each tool-call response,
  advance PreviousResponseId to the new responseId and reset
  responseItems to [] so subsequent iterations only send new tool
  outputs — not the growing full history. This prevents quadratic
  token re-processing.

- Remove redundant functionCallItem from continuation inputs: when
  using previous_response_id chaining, the function call is already
  stored server-side in the referenced response; only the
  FunctionCallOutputResponseItem is new content.

- Add ConversationContextLimitExceededException domain exception and
  IsContextLengthError helper to detect context window overflow from
  ClientResultException (HTTP 400 with context_length_exceeded text).

- Handle context limit in ChatController: both /api/chat/message and
  /api/chat/stream return 400 with errorCode 'context_limit_exceeded'.

- Add CloneOptionsWithPreviousResponseId helper to avoid mutating
  shared options across concurrent streaming legs.

- Add ParseToolArguments helper to deduplicate JSON argument parsing
  in both streaming and non-streaming paths.

- Fix OPENAI001 pragma: extend the disable region to cover the full
  loop body including the ClientResult<OpenAIResponse> declaration.

Author: BenjaminMichaelis

EssentialCSharp.Chat.Shared/Services/AIChatService.cs

@@ -4,6 +4,7 @@
 using ModelContextProtocol.Client;
 using ModelContextProtocol.Protocol;
 using OpenAI.Responses;
+using System.ClientModel;
 using System.Collections.Frozen;
 
 namespace EssentialCSharp.Chat.Common.Services;
@@ -183,14 +184,19 @@ private static string SanitizeForXmlContext(string? input) =>
         string? endUserId = null,
         [System.Runtime.CompilerServices.EnumeratorCancellation] CancellationToken cancellationToken = default)
     {
+        // Track this leg's response ID so tool-call continuations chain from it,
+        // ensuring the model's context includes the user's message + reasoning.
+        string? currentLegResponseId = null;
+
         await foreach (var update in streamingUpdates.WithCancellation(cancellationToken))
         {
 #pragma warning disable OPENAI001 // Type is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.
             if (update is StreamingResponseCreatedUpdate created)
             {
                 // Emit the response ID early so the controller can record ownership
                 // before the stream completes — handles client disconnects mid-stream.
-                yield return (string.Empty, responseId: created.Response.Id);
+                currentLegResponseId = created.Response.Id;
+                yield return (string.Empty, responseId: currentLegResponseId);
             }
             else if (update is StreamingResponseOutputItemDoneUpdate itemDone)
             {
@@ -200,10 +206,13 @@ private static string SanitizeForXmlContext(string? input) =>
                     if (toolCallDepth >= 10)
                         throw new InvalidOperationException("Maximum tool call depth exceeded.");
 
-                    // Execute the function call and stream its response.
-                    // Each nested ProcessStreamingUpdatesAsync emits its own StreamingResponseCreatedUpdate
-                    // (which already yields its responseId early), so no extra tracking is needed here.
-                    await foreach (var functionResult in ExecuteFunctionCallAsync(functionCallItem, responseOptions, mcpClient, toolCallDepth + 1, endUserId, cancellationToken))
+                    // Chain the continuation from THIS leg's response ID so the model sees:
+                    //   context(outer) → userMessage + AI reasoning + funcCall (stored in currentLegResponseId)
+                    //   → [toolOutput only] → next response
+                    // Using the outer previousResponseId here would omit the user's message from context.
+                    var continuationOptions = CloneOptionsWithPreviousResponseId(responseOptions, currentLegResponseId);
+
+                    await foreach (var functionResult in ExecuteFunctionCallAsync(functionCallItem, continuationOptions, mcpClient, toolCallDepth + 1, endUserId, cancellationToken))
                     {
                         yield return functionResult;
                     }
@@ -239,12 +248,11 @@ private static string SanitizeForXmlContext(string? input) =>
         if (!IsMcpToolAllowed(functionCallItem.FunctionName))
         {
             LogMcpToolCallRejected(_Logger, functionCallItem.FunctionName, endUserId);
-            // Feed a benign error back to the model so it can recover gracefully,
-            // mirroring what GetChatCompletionCore does on the non-streaming path.
+            // Feed a benign error back to the model so it can recover gracefully.
+            // The functionCallItem is in the stored response at PreviousResponseId — only send the output.
 #pragma warning disable OPENAI001 // Type is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.
             var errorItems = new List<ResponseItem>
             {
-                functionCallItem,
                 new FunctionCallOutputResponseItem(
                     functionCallItem.CallId,
                     $"Tool '{functionCallItem.FunctionName}' is not available.")
@@ -262,45 +270,19 @@ private static string SanitizeForXmlContext(string? input) =>
 
         LogMcpToolCallInvokedStream(_Logger, functionCallItem.FunctionName, toolCallDepth, endUserId);
         // A dictionary of arguments to pass to the tool. Each key represents a parameter name, and its associated value represents the argument value.
-        Dictionary<string, object?> arguments = [];
-        // example JsonResponse:
-        // "{\"question\":\"Azure OpenAI Responses API (Preview)\"}"
-        var jsonResponse = functionCallItem.FunctionArguments.ToString();
-        var jsonArguments = System.Text.Json.JsonSerializer.Deserialize<Dictionary<string, object?>>(jsonResponse) ?? new Dictionary<string, object?>();
-
-        // Convert JsonElement values to their actual types
-        foreach (var kvp in jsonArguments)
-        {
-            if (kvp.Value is System.Text.Json.JsonElement jsonElement)
-            {
-                arguments[kvp.Key] = jsonElement.ValueKind switch
-                {
-                    System.Text.Json.JsonValueKind.String => jsonElement.GetString(),
-                    System.Text.Json.JsonValueKind.Number => jsonElement.GetDecimal(),
-                    System.Text.Json.JsonValueKind.True => true,
-                    System.Text.Json.JsonValueKind.False => false,
-                    System.Text.Json.JsonValueKind.Null => null,
-                    _ => jsonElement.ToString()
-                };
-            }
-            else
-            {
-                arguments[kvp.Key] = kvp.Value;
-            }
-        }
+        var arguments = ParseToolArguments(functionCallItem.FunctionArguments);
 
         // Execute the function call using the MCP client
         var toolResult = await mcpClient.CallToolAsync(
             functionCallItem.FunctionName,
             arguments: arguments,
             cancellationToken: cancellationToken);
 
-        // Create input items with both the function call and the result
-        // This matches the Python pattern: append both tool_call and result
+        // The functionCallItem is already stored in the server's context (referenced by
+        // responseOptions.PreviousResponseId). Only the tool output is new content.
 #pragma warning disable OPENAI001 // Type is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.
         var inputItems = new List<ResponseItem>
         {
-            functionCallItem, // The original function call
             new FunctionCallOutputResponseItem(functionCallItem.CallId, McpToolResultFormatter.GetModelInput(toolResult))
         };
 #pragma warning restore OPENAI001 // Type is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.
@@ -412,15 +394,22 @@ private async Task<ResponseCreationOptions> CreateResponseOptionsAsync(
         // Create the response using the Responses API
 #pragma warning disable OPENAI001 // Type is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.
         List<ResponseItem> responseItems = [ResponseItem.CreateUserMessageItem(prompt)];
-#pragma warning restore OPENAI001 // Type is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.
 
         const int MaxToolCallIterations = 10;
         for (int iteration = 0; iteration < MaxToolCallIterations; iteration++)
         {
-            var response = await _ResponseClient.CreateResponseAsync(
-                responseItems,
-                options: responseOptions,
-                cancellationToken: cancellationToken);
+            ClientResult<OpenAIResponse> response;
+            try
+            {
+                response = await _ResponseClient.CreateResponseAsync(
+                    responseItems,
+                    options: responseOptions,
+                    cancellationToken: cancellationToken);
+            }
+            catch (ClientResultException ex) when (IsContextLengthError(ex))
+            {
+                throw new ConversationContextLimitExceededException(responseOptions.PreviousResponseId, ex);
+            }
 
             string responseId = response.Value.Id;
 
@@ -429,47 +418,36 @@ private async Task<ResponseCreationOptions> CreateResponseOptionsAsync(
 
             if (functionCalls.Count > 0 && mcpClient != null)
             {
+                // Advance the chain: the server now has everything up to responseId stored
+                // (user message + all prior function calls/results + this response's funcCalls).
+                // The next request only needs to supply the tool outputs — not the growing history.
+                responseOptions.PreviousResponseId = responseId;
+                responseItems = [];
+
                 foreach (var functionCallItem in functionCalls)
                 {
                     // Defense-in-depth: validate tool name against static allowlist before executing.
                     // This catches cases where the model hallucinates a tool name not on the list.
                     if (!IsMcpToolAllowed(functionCallItem.FunctionName))
                     {
                         LogMcpToolCallRejected(_Logger, functionCallItem.FunctionName, endUserId);
-                        // Return a benign error to the model so it can respond gracefully
-                        responseItems.Add(functionCallItem);
+                        // The functionCallItem is in the stored response; send only the error output.
                         responseItems.Add(new FunctionCallOutputResponseItem(
                             functionCallItem.CallId,
                             $"Tool '{functionCallItem.FunctionName}' is not available."));
                         continue;
                     }
 
                     LogMcpToolCallInvoked(_Logger, functionCallItem.FunctionName, iteration, endUserId);
-                    var jsonResponse = functionCallItem.FunctionArguments.ToString();
-                    var jsonArguments = System.Text.Json.JsonSerializer.Deserialize<Dictionary<string, object?>>(jsonResponse) ?? new Dictionary<string, object?>();
-
-                    Dictionary<string, object?> arguments = [];
-                    foreach (var kvp in jsonArguments)
-                    {
-                        arguments[kvp.Key] = kvp.Value is System.Text.Json.JsonElement jsonElement
-                            ? jsonElement.ValueKind switch
-                            {
-                                System.Text.Json.JsonValueKind.String => jsonElement.GetString(),
-                                System.Text.Json.JsonValueKind.Number => jsonElement.GetDecimal(),
-                                System.Text.Json.JsonValueKind.True => true,
-                                System.Text.Json.JsonValueKind.False => false,
-                                System.Text.Json.JsonValueKind.Null => null,
-                                _ => (object?)jsonElement.ToString()
-                            }
-                            : kvp.Value;
-                    }
+                    var arguments = ParseToolArguments(functionCallItem.FunctionArguments);
 
                     var toolResult = await mcpClient.CallToolAsync(
                         functionCallItem.FunctionName,
                         arguments: arguments,
                         cancellationToken: cancellationToken);
 
-                    responseItems.Add(functionCallItem);
+                    // The functionCallItem is stored server-side in the response at PreviousResponseId.
+                    // Only the tool output is new content that needs to be included.
                     responseItems.Add(new FunctionCallOutputResponseItem(
                         functionCallItem.CallId,
                         McpToolResultFormatter.GetModelInput(toolResult)));
@@ -501,6 +479,56 @@ private bool IsMcpToolAllowed(string toolName)
         return _AllowedMcpTools.Contains(toolName);
     }
 
+    /// <summary>
+    /// Returns a shallow clone of <paramref name="source"/> with
+    /// <see cref="ResponseCreationOptions.PreviousResponseId"/> replaced.
+    /// Used when chaining tool-call continuations from a specific response leg.
+    /// </summary>
+#pragma warning disable OPENAI001 // Type is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.
+    private static ResponseCreationOptions CloneOptionsWithPreviousResponseId(
+        ResponseCreationOptions source,
+        string? previousResponseId)
+    {
+        var clone = new ResponseCreationOptions
+        {
+            Instructions = source.Instructions,
+            PreviousResponseId = previousResponseId,
+            ReasoningOptions = source.ReasoningOptions,
+        };
+        foreach (var tool in source.Tools)
+            clone.Tools.Add(tool);
+        return clone;
+    }
+#pragma warning restore OPENAI001 // Type is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.
+
+    /// <summary>
+    /// Parses function call arguments from a <see cref="BinaryData"/> JSON payload into a
+    /// strongly-typed dictionary, converting <see cref="System.Text.Json.JsonElement"/> values
+    /// to their native CLR equivalents.
+    /// </summary>
+    private static Dictionary<string, object?> ParseToolArguments(BinaryData functionArguments)
+    {
+        var jsonArguments = System.Text.Json.JsonSerializer.Deserialize<Dictionary<string, object?>>(
+            functionArguments.ToString()) ?? [];
+
+        var arguments = new Dictionary<string, object?>(jsonArguments.Count);
+        foreach (var kvp in jsonArguments)
+        {
+            arguments[kvp.Key] = kvp.Value is System.Text.Json.JsonElement jsonElement
+                ? jsonElement.ValueKind switch
+                {
+                    System.Text.Json.JsonValueKind.String => jsonElement.GetString(),
+                    System.Text.Json.JsonValueKind.Number => jsonElement.GetDecimal(),
+                    System.Text.Json.JsonValueKind.True => true,
+                    System.Text.Json.JsonValueKind.False => false,
+                    System.Text.Json.JsonValueKind.Null => null,
+                    _ => (object?)jsonElement.ToString()
+                }
+                : kvp.Value;
+        }
+        return arguments;
+    }
+
     [LoggerMessage(Level = LogLevel.Information, Message = "AI tool call invoked: tool={ToolName} iteration={Iteration} user={EndUserId}")]
     private static partial void LogMcpToolCallInvoked(ILogger logger, string toolName, int iteration, string? endUserId);
 
@@ -515,4 +543,13 @@ private bool IsMcpToolAllowed(string toolName)
 
     [LoggerMessage(Level = LogLevel.Information, Message = "AI contextual search performed for prompt enrichment")]
     private static partial void LogContextualSearchPerformed(ILogger logger);
+
+    /// <summary>
+    /// Returns <c>true</c> when the API error indicates the conversation context window was exceeded.
+    /// </summary>
+    private static bool IsContextLengthError(ClientResultException ex) =>
+        ex.Status == 400 &&
+        (ex.Message.Contains("context_length_exceeded", StringComparison.OrdinalIgnoreCase) ||
+         ex.Message.Contains("maximum context length", StringComparison.OrdinalIgnoreCase) ||
+         ex.Message.Contains("reduce the length of the messages", StringComparison.OrdinalIgnoreCase));
 }

EssentialCSharp.Chat.Shared/Services/ConversationContextLimitExceededException.cs

@@ -0,0 +1,30 @@
+namespace EssentialCSharp.Chat.Common.Services;
+
+/// <summary>
+/// Thrown when a conversation's accumulated context exceeds the model's context window limit.
+/// </summary>
+/// <remarks>
+/// This occurs when using <c>previous_response_id</c> chaining over many turns — the server
+/// reconstructs the full history on each request, and that history eventually exceeds the model's
+/// maximum input tokens. Callers should prompt the user to start a new conversation rather than
+/// retrying with the same <c>previousResponseId</c>.
+/// </remarks>
+public sealed class ConversationContextLimitExceededException : Exception
+{
+    /// <summary>
+    /// The <c>previous_response_id</c> that caused the overflow, if known.
+    /// </summary>
+    public string? PreviousResponseId { get; }
+
+    public ConversationContextLimitExceededException(string? previousResponseId)
+        : base("This conversation has exceeded the model's context window limit.")
+    {
+        PreviousResponseId = previousResponseId;
+    }
+
+    public ConversationContextLimitExceededException(string? previousResponseId, Exception innerException)
+        : base("This conversation has exceeded the model's context window limit.", innerException)
+    {
+        PreviousResponseId = previousResponseId;
+    }
+}

EssentialCSharp.Web/Controllers/ChatController.cs

@@ -44,21 +44,28 @@ public async Task<IActionResult> SendMessage([FromBody] ChatMessageRequest reque
         if (!_ResponseIdValidationService.ValidateResponseId(userId, previousResponseId))
             return BadRequest(new { error = "Invalid conversation context." });
 
-        var (response, responseId) = await _AiChatService.GetChatCompletion(
-            prompt: request.Message,
-            previousResponseId: previousResponseId,
-            enableContextualSearch: request.EnableContextualSearch,
-            endUserId: userId,
-            cancellationToken: cancellationToken);
+        try
+        {
+            var (response, responseId) = await _AiChatService.GetChatCompletion(
+                prompt: request.Message,
+                previousResponseId: previousResponseId,
+                enableContextualSearch: request.EnableContextualSearch,
+                endUserId: userId,
+                cancellationToken: cancellationToken);
 
-        _ResponseIdValidationService.RecordResponseId(userId, responseId);
+            _ResponseIdValidationService.RecordResponseId(userId, responseId);
 
-        return Ok(new ChatMessageResponse
+            return Ok(new ChatMessageResponse
+            {
+                Response = response,
+                ResponseId = responseId,
+                Timestamp = DateTime.UtcNow
+            });
+        }
+        catch (ConversationContextLimitExceededException)
         {
-            Response = response,
-            ResponseId = responseId,
-            Timestamp = DateTime.UtcNow
-        });
+            return BadRequest(new { error = "This conversation has grown too long. Please start a new one.", errorCode = "context_limit_exceeded" });
+        }
     }
 
     [HttpPost("stream")]
@@ -130,6 +137,22 @@ public async Task StreamMessage([FromBody] ChatMessageRequest request, Cancellat
         {
             LogChatStreamCancelled(_Logger, User.Identity?.Name);
         }
+        catch (ConversationContextLimitExceededException) when (!Response.HasStarted)
+        {
+            Response.StatusCode = 400;
+            Response.ContentType = "application/json";
+            await Response.WriteAsJsonAsync(new { error = "This conversation has grown too long. Please start a new one.", errorCode = "context_limit_exceeded" }, CancellationToken.None);
+        }
+        catch (ConversationContextLimitExceededException)
+        {
+            LogChatStreamErrorMidStream(_Logger, new InvalidOperationException("Context limit exceeded mid-stream"), User.Identity?.Name);
+            try
+            {
+                await Response.WriteAsync("data: {\"type\":\"error\",\"message\":\"This conversation has grown too long. Please start a new one.\",\"errorCode\":\"context_limit_exceeded\"}\n\n", CancellationToken.None);
+                await Response.Body.FlushAsync(CancellationToken.None);
+            }
+            catch { /* client already disconnected */ }
+        }
         catch (Exception ex) when (!Response.HasStarted)
         {
             LogChatStreamErrorBeforeResponseStarted(_Logger, ex, User.Identity?.Name);