SessionConfigE2ETests.cs

/*---------------------------------------------------------------------------------------------
 *  Copyright (c) Microsoft Corporation. All rights reserved.
 *--------------------------------------------------------------------------------------------*/

using GitHub.Copilot.Rpc;
using GitHub.Copilot.Test.Harness;
using System.Text;
using System.Text.Json;
using Xunit;
using Xunit.Abstractions;

namespace GitHub.Copilot.Test.E2E;

public class SessionConfigE2ETests(E2ETestFixture fixture, ITestOutputHelper output)
    : E2ETestBase(fixture, "session_config", output)
{
    private const string ViewImagePrompt = "Use the view tool to look at the file test.png and describe what you see";
    private const string ProviderHeaderName = "x-copilot-sdk-provider-header";
    private const string ClientName = "csharp-public-surface-client";

    private static readonly byte[] Png1X1 = Convert.FromBase64String(
        "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==");

    [Fact]
    // TODO(BYOK): Anthropic Messages history diverged after enabling vision via SetModel. Verify
    // that model capability overrides work for provider-backed sessions before keeping this CAPI-only.
    [Trait(E2ETestTraits.Backend, E2ETestTraits.CapiOnly)]
    public async Task Vision_Disabled_Then_Enabled_Via_SetModel()
    {
        await File.WriteAllBytesAsync(Path.Join(Ctx.WorkDir, "test.png"), Png1X1);

        var session = await CreateSessionAsync(new SessionConfig
        {
            Model = "claude-sonnet-5",
            ModelCapabilities = new ModelCapabilitiesOverride
            {
                Supports = new ModelCapabilitiesOverrideSupports { Vision = false },
            },
        });

        // Turn 1: vision off — no image_url expected
        await session.SendAndWaitAsync(new MessageOptions { Prompt = ViewImagePrompt });
        var trafficAfterT1 = await Ctx.GetExchangesAsync();
        var t1Messages = trafficAfterT1.SelectMany(e => e.Request.Messages).ToList();
        Assert.False(HasImageUrlContent(t1Messages), "Expected no image_url content when vision is disabled");

        // Switch vision on
        await session.SetModelAsync(
            "claude-sonnet-5",
            reasoningEffort: null,
            modelCapabilities: new ModelCapabilitiesOverride
            {
                Supports = new ModelCapabilitiesOverrideSupports { Vision = true },
            });

        // Turn 2: vision on — image_url expected
        await session.SendAndWaitAsync(new MessageOptions { Prompt = ViewImagePrompt });
        var trafficAfterT2 = await Ctx.GetExchangesAsync();
        var newExchanges = trafficAfterT2.Skip(trafficAfterT1.Count).ToList();
        Assert.NotEmpty(newExchanges);
        var t2Messages = newExchanges.SelectMany(e => e.Request.Messages).ToList();
        Assert.True(HasImageUrlContent(t2Messages), "Expected image_url content when vision is enabled");

        await session.DisposeAsync();
    }

    [Fact]
    // TODO(BYOK): Anthropic Messages history diverged after disabling vision via SetModel. Verify
    // that model capability overrides work for provider-backed sessions before keeping this CAPI-only.
    [Trait(E2ETestTraits.Backend, E2ETestTraits.CapiOnly)]
    public async Task Vision_Enabled_Then_Disabled_Via_SetModel()
    {
        await File.WriteAllBytesAsync(Path.Join(Ctx.WorkDir, "test.png"), Png1X1);

        var session = await CreateSessionAsync(new SessionConfig
        {
            Model = "claude-sonnet-5",
            ModelCapabilities = new ModelCapabilitiesOverride
            {
                Supports = new ModelCapabilitiesOverrideSupports { Vision = true },
            },
        });

        // Turn 1: vision on — image_url expected
        await session.SendAndWaitAsync(new MessageOptions { Prompt = ViewImagePrompt });
        var trafficAfterT1 = await Ctx.GetExchangesAsync();
        var t1Messages = trafficAfterT1.SelectMany(e => e.Request.Messages).ToList();
        Assert.True(HasImageUrlContent(t1Messages), "Expected image_url content when vision is enabled");

        // Switch vision off
        await session.SetModelAsync(
            "claude-sonnet-5",
            reasoningEffort: null,
            modelCapabilities: new ModelCapabilitiesOverride
            {
                Supports = new ModelCapabilitiesOverrideSupports { Vision = false },
            });

        // Turn 2: vision off — no image_url expected in new exchanges
        await session.SendAndWaitAsync(new MessageOptions { Prompt = ViewImagePrompt });
        var trafficAfterT2 = await Ctx.GetExchangesAsync();
        var newExchanges = trafficAfterT2.Skip(trafficAfterT1.Count).ToList();
        Assert.NotEmpty(newExchanges);
        var t2Messages = newExchanges.SelectMany(e => e.Request.Messages).ToList();
        Assert.False(HasImageUrlContent(t2Messages), "Expected no image_url content when vision is disabled");

        await session.DisposeAsync();
    }

    [Fact]
    public async Task Should_Use_Custom_SessionId()
    {
        var requestedSessionId = Guid.NewGuid().ToString();

        var session = await CreateSessionAsync(new SessionConfig
        {
            SessionId = requestedSessionId,
        });

        Assert.Equal(requestedSessionId, session.SessionId);

        var messages = await session.GetEventsAsync();
        var startEvent = Assert.IsType<SessionStartEvent>(messages[0]);
        Assert.Equal(requestedSessionId, startEvent.Data.SessionId);

        await session.DisposeAsync();
    }

    [Fact]
    [Trait(E2ETestTraits.Backend, E2ETestTraits.SelfConfiguredBackend)]
    public async Task Should_Apply_ReasoningEffort_On_Session_Create()
    {
        const string reasoningModelId = "custom-reasoning-model";

        var session = await CreateSessionAsync(new SessionConfig
        {
            Model = reasoningModelId,
            Provider = CreateProxyProvider("create-reasoning"),
            ReasoningEffort = "high",
        });

        var startEvent = Assert.Single((await session.GetEventsAsync()).OfType<SessionStartEvent>());
        Assert.Equal(reasoningModelId, startEvent.Data.SelectedModel);
        Assert.Equal("high", startEvent.Data.ReasoningEffort);

        await session.DisposeAsync();
    }

    [Theory]
    [Trait(E2ETestTraits.Backend, E2ETestTraits.SelfConfiguredBackend)]
    [InlineData("low")]
    [InlineData("medium")]
    [InlineData("high")]
    public async Task Should_Apply_All_ReasoningEffort_Values_On_Session_Create(string effort)
    {
        const string reasoningModelId = "custom-reasoning-model";

        var session = await CreateSessionAsync(new SessionConfig
        {
            Model = reasoningModelId,
            Provider = CreateProxyProvider($"reasoning-{effort}"),
            ReasoningEffort = effort,
        });

        var startEvent = Assert.Single((await session.GetEventsAsync()).OfType<SessionStartEvent>());
        Assert.Equal(reasoningModelId, startEvent.Data.SelectedModel);
        Assert.Equal(effort, startEvent.Data.ReasoningEffort);

        await session.DisposeAsync();
    }

    [Fact]
    [Trait(E2ETestTraits.Backend, E2ETestTraits.SelfConfiguredBackend)]
    public async Task Should_Apply_ReasoningEffort_On_Session_Resume()
    {
        await using var originalSession = await CreateSessionAsync();
        var sessionId = originalSession.SessionId;
        await SuspendAndUntrackSessionForResumeAsync(originalSession);
        const string reasoningModelId = "custom-reasoning-model";
        var resumedSession = await ResumeSessionAsync(sessionId, new ResumeSessionConfig
        {
            Model = reasoningModelId,
            Provider = CreateProxyProvider("resume-reasoning"),
            ReasoningEffort = "high",
        });

        var resumeEvent = Assert.Single((await resumedSession.GetEventsAsync()).OfType<SessionResumeEvent>());
        Assert.Equal(reasoningModelId, resumeEvent.Data.SelectedModel);
        Assert.Equal("high", resumeEvent.Data.ReasoningEffort);

        await resumedSession.DisposeAsync();
    }

    [Fact]
    // TODO(BYOK): The Anthropic user-agent omitted ClientName and contained only its provider SDK
    // identifier. Determine the expected propagation for custom providers before keeping this CAPI-only.
    [Trait(E2ETestTraits.Backend, E2ETestTraits.CapiOnly)]
    public async Task Should_Forward_ClientName_In_UserAgent()
    {
        var session = await CreateSessionAsync(new SessionConfig
        {
            ClientName = ClientName,
        });

        await session.SendAndWaitAsync(new MessageOptions { Prompt = "What is 1+1?" });

        var exchange = Assert.Single(await Ctx.GetExchangesAsync());
        AssertHeaderContains(exchange.RequestHeaders, "user-agent", ClientName);

        await session.DisposeAsync();
    }

    [Fact]
    [Trait(E2ETestTraits.Backend, E2ETestTraits.SelfConfiguredBackend)]
    public async Task Should_Forward_Custom_Provider_Headers_On_Create()
    {
        var session = await CreateSessionAsync(new SessionConfig
        {
            Model = "claude-sonnet-5",
            Provider = CreateProxyProvider("create-provider-header"),
        });

        var message = await session.SendAndWaitAsync(new MessageOptions { Prompt = "What is 1+1?" });
        Assert.Contains("2", message?.Data.Content ?? string.Empty);

        var exchange = Assert.Single(await Ctx.GetExchangesAsync());
        AssertHeaderContains(exchange.RequestHeaders, "authorization", "Bearer test-provider-key");
        AssertHeaderContains(exchange.RequestHeaders, ProviderHeaderName, "create-provider-header");

        await session.DisposeAsync();
    }

    [Fact]
    [Trait(E2ETestTraits.Backend, E2ETestTraits.SelfConfiguredBackend)]
    public async Task Should_Forward_Custom_Provider_Headers_On_Resume()
    {
        await using var session1 = await CreateSessionAsync();
        var sessionId = session1.SessionId;
        await SuspendAndUntrackSessionForResumeAsync(session1);

        var session2 = await ResumeSessionAsync(sessionId, new ResumeSessionConfig
        {
            Model = "claude-sonnet-5",
            Provider = CreateProxyProvider("resume-provider-header"),
        });

        var message = await session2.SendAndWaitAsync(new MessageOptions { Prompt = "What is 2+2?" });
        Assert.Contains("4", message?.Data.Content ?? string.Empty);

        var exchange = Assert.Single(await Ctx.GetExchangesAsync());
        AssertHeaderContains(exchange.RequestHeaders, "authorization", "Bearer test-provider-key");
        AssertHeaderContains(exchange.RequestHeaders, ProviderHeaderName, "resume-provider-header");

        await session2.DisposeAsync();
    }

    [Fact]
    [Trait(E2ETestTraits.Backend, E2ETestTraits.SelfConfiguredBackend)]
    public async Task Should_Forward_Provider_Wire_Model()
    {
        // Verifies that ProviderConfig.WireModel overrides the model name sent to
        // the provider API, while SessionConfig.Model still drives runtime
        // configuration lookup (capabilities, prompts, reasoning behavior).
        // MaxOutputTokens is also set here to confirm the SDK accepts it without
        // serialization errors; the CLI does not echo it as `max_tokens` on the
        // OpenAI-style wire request, so we don't assert on it directly (see unit
        // tests for serialization coverage).
        var session = await CreateSessionAsync(new SessionConfig
        {
            Model = "claude-sonnet-5",
            Provider = new ProviderConfig
            {
                Type = "openai",
                BaseUrl = Ctx.ProxyUrl,
                ApiKey = "test-provider-key",
                WireModel = "test-wire-model",
                MaxOutputTokens = 1024,
            },
        });

        await session.SendAndWaitAsync(new MessageOptions { Prompt = "What is 1+1?" });

        var exchange = Assert.Single(await Ctx.GetExchangesAsync());
        Assert.Equal("test-wire-model", exchange.Request.Model);

        await session.DisposeAsync();
    }

    [Fact]
    [Trait(E2ETestTraits.Backend, E2ETestTraits.SelfConfiguredBackend)]
    public async Task Should_Use_Provider_Model_Id_As_Wire_Model()
    {
        // ProviderConfig.ModelId drives both the runtime resolved model AND the wire model
        // when WireModel is not specified. Here SessionConfig.Model is intentionally omitted
        // so that ModelId is the only model source.
        var session = await CreateSessionAsync(new SessionConfig
        {
            Provider = new ProviderConfig
            {
                Type = "openai",
                BaseUrl = Ctx.ProxyUrl,
                ApiKey = "test-provider-key",
                ModelId = "claude-sonnet-5",
            },
        });

        await session.SendAndWaitAsync(new MessageOptions { Prompt = "What is 1+1?" });

        var exchange = Assert.Single(await Ctx.GetExchangesAsync());
        Assert.Equal("claude-sonnet-5", exchange.Request.Model);

        await session.DisposeAsync();
    }

    [Fact]
    public async Task Should_Use_WorkingDirectory_For_Tool_Execution()
    {
        var subDir = Path.Join(Ctx.WorkDir, "subproject");
        Directory.CreateDirectory(subDir);
        await File.WriteAllTextAsync(Path.Join(subDir, "marker.txt"), "I am in the subdirectory");

        var session = await CreateSessionAsync(new SessionConfig
        {
            WorkingDirectory = subDir,
        });

        var message = await session.SendAndWaitAsync(new MessageOptions
        {
            Prompt = "Read the file marker.txt and tell me what it says",
        });

        Assert.Contains("subdirectory", message?.Data.Content ?? string.Empty);

        await session.DisposeAsync();
    }

    [Fact]
    public async Task Should_Apply_WorkingDirectory_On_Session_Resume()
    {
        var subDir = Path.Join(Ctx.WorkDir, "resume-subproject");
        Directory.CreateDirectory(subDir);
        await File.WriteAllTextAsync(Path.Join(subDir, "resume-marker.txt"), "I am in the resume working directory");

        await using var session1 = await CreateSessionAsync();
        var sessionId = session1.SessionId;
        await SuspendAndUntrackSessionForResumeAsync(session1);

        var session2 = await ResumeSessionAsync(sessionId, new ResumeSessionConfig
        {
            WorkingDirectory = subDir,
        });

        var message = await session2.SendAndWaitAsync(new MessageOptions
        {
            Prompt = "Read the file resume-marker.txt and tell me what it says",
        });

        Assert.Contains("resume working directory", message?.Data.Content ?? string.Empty);

        await session2.DisposeAsync();
    }

    [Fact]
    public async Task Should_Apply_SystemMessage_On_Session_Resume()
    {
        await using var session1 = await CreateSessionAsync();
        var sessionId = session1.SessionId;
        await SuspendAndUntrackSessionForResumeAsync(session1);

        var resumeInstruction = "End the response with RESUME_SYSTEM_MESSAGE_SENTINEL.";
        var session2 = await ResumeSessionAsync(sessionId, new ResumeSessionConfig
        {
            SystemMessage = new SystemMessageConfig
            {
                Mode = SystemMessageMode.Append,
                Content = resumeInstruction,
            },
        });

        var message = await session2.SendAndWaitAsync(new MessageOptions { Prompt = "What is 1+1?" });
        Assert.Contains("RESUME_SYSTEM_MESSAGE_SENTINEL", message?.Data.Content ?? string.Empty);

        var exchange = Assert.Single(await Ctx.GetExchangesAsync());
        Assert.Contains(resumeInstruction, GetSystemMessage(exchange));

        await session2.DisposeAsync();
    }

    [Fact]
    public async Task Should_Apply_InstructionDirectories_On_Create()
    {
        var projectDir = Path.Join(Ctx.WorkDir, "instruction-create-project");
        var instructionDir = Path.Join(Ctx.WorkDir, "extra-create-instructions");
        var instructionFilesDir = Path.Join(instructionDir, ".github", "instructions");
        const string sentinel = "CS_CREATE_INSTRUCTION_DIRECTORIES_SENTINEL";
        Directory.CreateDirectory(projectDir);
        Directory.CreateDirectory(instructionFilesDir);
        await File.WriteAllTextAsync(
            Path.Join(instructionFilesDir, "extra.instructions.md"),
            $"Always include {sentinel}.");

        var session = await CreateSessionAsync(new SessionConfig
        {
            WorkingDirectory = projectDir,
            InstructionDirectories = [instructionDir],
        });

        await session.SendAndWaitAsync(new MessageOptions { Prompt = "What is 1+1?" });

        var exchange = Assert.Single(await Ctx.GetExchangesAsync());
        Assert.Contains(sentinel, GetSystemMessage(exchange));

        await session.DisposeAsync();
    }

    [Fact]
    public async Task Should_Apply_InstructionDirectories_On_Resume()
    {
        var projectDir = Path.Join(Ctx.WorkDir, "instruction-resume-project");
        var instructionDir = Path.Join(Ctx.WorkDir, "extra-resume-instructions");
        var instructionFilesDir = Path.Join(instructionDir, ".github", "instructions");
        const string sentinel = "CS_RESUME_INSTRUCTION_DIRECTORIES_SENTINEL";
        Directory.CreateDirectory(projectDir);
        Directory.CreateDirectory(instructionFilesDir);
        await File.WriteAllTextAsync(
            Path.Join(instructionFilesDir, "extra.instructions.md"),
            $"Always include {sentinel}.");

        await using var session1 = await CreateSessionAsync(new SessionConfig
        {
            WorkingDirectory = projectDir,
        });
        var sessionId = session1.SessionId;
        await SuspendAndUntrackSessionForResumeAsync(session1);
        var session2 = await ResumeSessionAsync(sessionId, new ResumeSessionConfig
        {
            WorkingDirectory = projectDir,
            InstructionDirectories = [instructionDir],
        });

        await session2.SendAndWaitAsync(new MessageOptions { Prompt = "What is 1+1?" });

        var exchange = Assert.Single(await Ctx.GetExchangesAsync());
        Assert.Contains(sentinel, GetSystemMessage(exchange));

        await session2.DisposeAsync();
    }

    [Fact]
    public async Task Should_Apply_AvailableTools_On_Session_Resume()
    {
        await using var session1 = await CreateSessionAsync();
        var sessionId = session1.SessionId;
        await SuspendAndUntrackSessionForResumeAsync(session1);

        var session2 = await ResumeSessionAsync(sessionId, new ResumeSessionConfig
        {
            AvailableTools = ["view"],
        });

        try
        {
            var exchange = Assert.Single(await SendAndWaitForExchangesAsync(
                session2,
                new MessageOptions { Prompt = "What is 1+1?" }));
            Assert.Equal(["view"], GetToolNames(exchange));
        }
        finally
        {
            await session2.DisposeAsync();
        }
    }

    [Fact]
    public async Task Should_Apply_Session_Limits_On_Create()
    {
        var session = await CreateSessionAsync(new SessionConfig
        {
            SessionLimits = new SessionLimitsConfig
            {
                MaxAiCredits = 30,
            },
        });

        try
        {
            var exchange = await SendAndGetNextExchangeAsync(
                session,
                "Acknowledge the current session limits.");

            AssertSessionLimitsStatus(exchange, "30 AI credits");
        }
        finally
        {
            await session.DisposeAsync();
        }
    }

    [Fact]
    public async Task Should_Apply_Session_Limits_On_Resume()
    {
        await using var session1 = await CreateSessionAsync();
        var sessionId = session1.SessionId;
        await SuspendAndUntrackSessionForResumeAsync(session1);
        var session2 = await ResumeSessionAsync(sessionId, new ResumeSessionConfig
        {
            SessionLimits = new SessionLimitsConfig
            {
                MaxAiCredits = 30,
            },
        });

        try
        {
            var exchange = await SendAndGetNextExchangeAsync(
                session2,
                "Acknowledge the current session limits.");

            AssertSessionLimitsStatus(exchange, "30 AI credits");
        }
        finally
        {
            await session2.DisposeAsync();
        }
    }

    [Fact]
    public async Task Should_Apply_Excluded_Built_In_Agents_On_Create()
    {
        const string excludedAgent = "explore";
        const string prompt = "What is 1+1?";

        var baselineSession = await CreateSessionAsync();
        try
        {
            var baselineExchange = await SendAndGetNextExchangeAsync(baselineSession, prompt);
            Assert.Contains(excludedAgent, GetTaskAgentTypes(baselineExchange));
        }
        finally
        {
            await baselineSession.DisposeAsync();
        }

        var excludedSession = await CreateSessionAsync(new SessionConfig
        {
            ExcludedBuiltInAgents = [excludedAgent],
        });

        try
        {
            var excludedExchange = await SendAndGetNextExchangeAsync(excludedSession, prompt);
            var agentTypes = GetTaskAgentTypes(excludedExchange);

            Assert.NotEmpty(agentTypes);
            Assert.DoesNotContain(excludedAgent, agentTypes);
        }
        finally
        {
            await excludedSession.DisposeAsync();
        }
    }

    [Fact]
    public async Task Should_Apply_Excluded_Built_In_Agents_On_Resume()
    {
        const string excludedAgent = "explore";

        await using var session1 = await CreateSessionAsync();
        var sessionId = session1.SessionId;
        await SuspendAndUntrackSessionForResumeAsync(session1);
        var session2 = await ResumeSessionAsync(sessionId, new ResumeSessionConfig
        {
            ExcludedBuiltInAgents = [excludedAgent],
        });

        try
        {
            var exchange = await SendAndGetNextExchangeAsync(session2, "What is 1+1?");
            var agentTypes = GetTaskAgentTypes(exchange);

            Assert.NotEmpty(agentTypes);
            Assert.DoesNotContain(excludedAgent, agentTypes);
        }
        finally
        {
            await session2.DisposeAsync();
        }
    }

    [Fact]
    [Trait(E2ETestTraits.Backend, E2ETestTraits.SelfConfiguredBackend)]
    public async Task Should_Enable_Citations_For_Anthropic_File_Attachments_On_Create()
    {
        var handler = new RecordingRequestHandler();
        await using var client = CreateClientWithRequestHandler(handler);
        await client.StartAsync();

        var session = await Ctx.CreateSessionAsync(client, new SessionConfig
        {
            OnPermissionRequest = PermissionHandler.ApproveAll,
            Model = "claude-sonnet-5",
            EnableCitations = true,
            Provider = CreateAnthropicProvider(),
        });

        try
        {
            await session.SendAndWaitAsync(new MessageOptions
            {
                Prompt = "Summarize the attached PDF with citations enabled.",
                Attachments = [CreatePdfAttachment()],
            });

            AssertAnthropicDocumentCitationsEnabled(Assert.Single(handler.InferenceRequests).Body);
        }
        finally
        {
            await session.DisposeAsync();
        }
    }

    [Fact]
    [Trait(E2ETestTraits.Backend, E2ETestTraits.SelfConfiguredBackend)]
    public async Task Should_Enable_Citations_For_Anthropic_File_Attachments_On_Resume()
    {
        const string connectionToken = "citation-resume-token";
        var handler = new RecordingRequestHandler();
        await using var client = CreateClientWithRequestHandler(
            handler,
            RuntimeConnection.ForTcp(connectionToken: connectionToken));
        await client.StartAsync();

        var session1 = await Ctx.CreateSessionAsync(client, new SessionConfig
        {
            OnPermissionRequest = PermissionHandler.ApproveAll,
        });
        var sessionId = session1.SessionId;
        var port = client.RuntimePort
            ?? throw new InvalidOperationException("The handler-backed E2E client must use TCP transport to support multi-client resume.");
        await using var resumeClient = Ctx.CreateClient(options: new CopilotClientOptions
        {
            Connection = RuntimeConnection.ForUri($"localhost:{port}", connectionToken: connectionToken),
        });

        var session2 = await Ctx.ResumeSessionAsync(resumeClient, sessionId, new ResumeSessionConfig
        {
            OnPermissionRequest = PermissionHandler.ApproveAll,
            Model = "claude-sonnet-5",
            EnableCitations = true,
            Provider = CreateAnthropicProvider(),
        });

        try
        {
            await session2.SendAndWaitAsync(new MessageOptions
            {
                Prompt = "Summarize the attached PDF with citations enabled.",
                Attachments = [CreatePdfAttachment()],
            });

            AssertAnthropicDocumentCitationsEnabled(Assert.Single(handler.InferenceRequests).Body);
        }
        finally
        {
            await session2.DisposeAsync();
            await session1.DisposeAsync();
        }
    }

    [Fact]
    [Trait(E2ETestTraits.Backend, E2ETestTraits.SelfConfiguredBackend)]
    public async Task Should_Create_Session_With_Custom_Provider_Config()
    {
        // Per the TS test (session_config.e2e.test.ts), this only verifies that a
        // session can be created with a custom provider config and that disconnect
        // is allowed to fail since the fake provider URL won't be reachable.
        var session = await CreateSessionAsync(new SessionConfig
        {
            Provider = new ProviderConfig
            {
                BaseUrl = "https://api.example.com/v1",
                ApiKey = "test-key",
            },
        });

        Assert.Matches(@"^[a-f0-9-]+$", session.SessionId);

        try
        {
            await session.DisposeAsync();
        }
        catch (Exception)
        {
            // disconnect may fail since the provider is fake
        }
    }

    [Fact]
    // TODO(BYOK): Anthropic Messages request history diverged while replaying this blob attachment.
    // Confirm native clients preserve blob/image turns before keeping this CAPI-only.
    [Trait(E2ETestTraits.Backend, E2ETestTraits.CapiOnly)]
    public async Task Should_Accept_Blob_Attachments()
    {
        // Write the image to disk so the model can view it if it tries
        const string pngBase64 =
            "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==";
        await File.WriteAllBytesAsync(
            Path.Join(Ctx.WorkDir, "pixel.png"),
            Convert.FromBase64String(pngBase64));

        var session = await CreateSessionAsync();

        await session.SendAndWaitAsync(new MessageOptions
        {
            Prompt = "What color is this pixel? Reply in one word.",
            Attachments =
            [
                new AttachmentBlob
                {
                    Data = pngBase64,
                    MimeType = "image/png",
                    DisplayName = "pixel.png",
                },
            ],
        });

        await session.DisposeAsync();
    }

    [Fact]
    public async Task Should_Accept_Message_Attachments()
    {
        var attachedPath = Path.Join(Ctx.WorkDir, "attached.txt");
        await File.WriteAllTextAsync(attachedPath, "This file is attached");

        var session = await CreateSessionAsync();

        await session.SendAndWaitAsync(new MessageOptions
        {
            Prompt = "Summarize the attached file",
            Attachments =
            [
                new AttachmentFile
                {
                    Path = attachedPath,
                    DisplayName = "attached.txt",
                },
            ],
        });

        await session.DisposeAsync();
    }

    /// <summary>
    /// Checks whether any user message contains an image_url content part.
    /// Content can be a string (no images) or a JSON array of content parts.
    /// </summary>
    private static bool HasImageUrlContent(List<ChatCompletionMessage> messages)
    {
        return messages
            .Where(m => m.Role == "user" && m.Content is { ValueKind: JsonValueKind.Array })
            .Any(m => m.Content!.Value.EnumerateArray().Any(part =>
                part.TryGetProperty("type", out var typeProp) &&
                typeProp.ValueKind == JsonValueKind.String &&
                typeProp.GetString() == "image_url"));
    }

    private CopilotClient CreateClientWithRequestHandler(
        CopilotRequestHandler handler,
        RuntimeConnection? connection = null)
    {
        return Ctx.CreateClient(options: new CopilotClientOptions
        {
            Connection = connection ?? RuntimeConnection.ForStdio(),
            RequestHandler = handler,
        });
    }

    private async Task<ParsedHttpExchange> SendAndGetNextExchangeAsync(CopilotSession session, string prompt)
    {
        var existingCount = (await Ctx.GetExchangesAsync()).Count;
        var exchanges = await SendAndWaitForExchangesAsync(
            session,
            new MessageOptions { Prompt = prompt },
            minimumCount: existingCount + 1);
        return exchanges[existingCount];
    }

    private static void AssertSessionLimitsStatus(ParsedHttpExchange exchange, string expectedRemaining)
    {
        var message = exchange.Request.Messages.SingleOrDefault(m =>
            m.Role == "user"
            && m.StringContent?.Contains("<session_limits_status>", StringComparison.Ordinal) == true);

        Assert.NotNull(message);
        Assert.Contains($"Remaining session limits: {expectedRemaining}.", message!.StringContent);
        Assert.Contains(
            "Be frugal; avoid optional exploration and unnecessary tool calls.",
            message.StringContent);
    }

    private static IReadOnlyList<string> GetTaskAgentTypes(ParsedHttpExchange exchange)
    {
        var taskTool = Assert.Single(
            exchange.Request.Tools ?? [],
            tool => string.Equals(tool.Function.Name, "task", StringComparison.Ordinal));
        var parameters = taskTool.Function.Parameters;

        Assert.NotNull(parameters);
        var enumValues = parameters!.Value
            .GetProperty("properties")
            .GetProperty("agent_type")
            .GetProperty("enum");

        return [.. enumValues.EnumerateArray().Select(value => value.GetString()).OfType<string>()];
    }

    private static AttachmentBlob CreatePdfAttachment()
    {
        const string pdfText = "%PDF-1.4\n1 0 obj\n<< /Type /Catalog >>\nendobj\ntrailer\n<< /Root 1 0 R >>\n%%EOF\n";

        return new AttachmentBlob
        {
            Data = Convert.ToBase64String(Encoding.ASCII.GetBytes(pdfText)),
            DisplayName = "citation-source.pdf",
            MimeType = "application/pdf",
        };
    }

    private static ProviderConfig CreateAnthropicProvider()
    {
        return new ProviderConfig
        {
            Type = "anthropic",
            BaseUrl = "https://anthropic-citations.invalid/v1",
            ApiKey = "test-provider-key",
            ModelId = "claude-sonnet-5",
            WireModel = "claude-sonnet-5",
        };
    }

    private static void AssertAnthropicDocumentCitationsEnabled(string requestBody)
    {
        using var document = JsonDocument.Parse(requestBody);
        var documentBlocks = document.RootElement
            .GetProperty("messages")
            .EnumerateArray()
            .SelectMany(message => message.GetProperty("content").EnumerateArray())
            .Where(block => block.GetProperty("type").GetString() == "document")
            .ToList();

        var documentBlock = Assert.Single(documentBlocks);
        Assert.Equal("citation-source.pdf", documentBlock.GetProperty("title").GetString());
        Assert.True(documentBlock.GetProperty("citations").GetProperty("enabled").GetBoolean());
    }

    private ProviderConfig CreateProxyProvider(string headerValue)
    {
        return new ProviderConfig
        {
            Type = "openai",
            BaseUrl = Ctx.ProxyUrl,
            ApiKey = "test-provider-key",
            Headers = new Dictionary<string, string>
            {
                [ProviderHeaderName] = headerValue,
            },
        };
    }

    private static void AssertHeaderContains(
        Dictionary<string, JsonElement>? headers,
        string expectedName,
        string expectedValue)
    {
        Assert.NotNull(headers);
        var header = headers.FirstOrDefault(
            pair => string.Equals(pair.Key, expectedName, StringComparison.OrdinalIgnoreCase));

        var actualHeaders = string.Join(", ", headers.Select(pair => $"{pair.Key}={HeaderValueAsString(pair.Value)}"));
        Assert.False(
            string.IsNullOrEmpty(header.Key),
            $"Expected header '{expectedName}' to be present. Actual headers: {actualHeaders}");
        Assert.Contains(expectedValue, HeaderValueAsString(header.Value), StringComparison.Ordinal);
    }

    private static string HeaderValueAsString(JsonElement value)
    {
        return value.ValueKind switch
        {
            JsonValueKind.String => value.GetString() ?? string.Empty,
            JsonValueKind.Array => string.Join(",", value.EnumerateArray().Select(HeaderValueAsString)),
            _ => value.ToString(),
        };
    }
}