Expose Auto tier switching across all six SDKs

docs/features/session-persistence.md

@@ -242,7 +242,7 @@ When resuming a session, you can optionally reconfigure many settings. This is u
 | `availableTools` | Restrict which tools are available |
 | `excludedTools` | Disable specific tools |
 | `provider` | Re-provide BYOK credentials (required for BYOK sessions) |
-| `capi.autoTier` | Override the persisted Auto routing preference on cold resume only |
+| `capi.autoTier` | Override the persisted Auto routing preference |
 | `reasoningEffort` | Adjust reasoning effort level |
 | `streaming` | Enable/disable streaming responses |
 | `workingDirectory` | Change the working directory |
@@ -262,13 +262,55 @@ The runtime persists the selected tier, so applications do not need to resend it
 
 * Omitting the tier when creating a session uses the runtime's default routing behavior.
 * A cold resume restores the persisted tier. Supplying an explicit tier overrides the restored value for the new activation.
-* When resuming a session already resident in the runtime, omitting the tier preserves the current selection, supplying the same tier is a no-op, and supplying a different tier is rejected.
+* When resuming a session already resident in the runtime, omitting the tier preserves the current selection and supplying the same tier is a no-op. Supplying a different tier requests a safe switch that the runtime applies after the resume succeeds; it cannot change a turn that is already in flight.
 * Older sessions without a persisted tier retain default routing behavior.
 
 Tier selection is not a live model-switch operation. The SDK forwards the preference; the runtime owns persistence and validation.
 
 The `session.start` and `session.resume` events expose the selected tier in their optional `data.autoTier` field (`data.auto_tier` in Python). When no tier is selected, the field is omitted.
 
+### Changing the Auto tier during a session
+
+Call `setAutoTier` to change the routing preference on a live session without changing the selected model. Pass `null` (Python `None`, Go `nil`) to return to the provider's default Auto routing. This requires Copilot CLI `1.0.83-4` or later, which is newer than the `1.0.82-1` needed to select a tier when creating or resuming a session.
+
+```typescript
+const result = await session.setAutoTier("intelligence");
+if (result.status === "pending") {
+  // Accepted, but not yet in effect.
+}
+```
+
+The runtime does not apply the preference immediately. It records the request and commits it only when a later user turn using the `auto` model successfully obtains a usable model from the provider. A `pending` status therefore confirms that the request was accepted, not that it took effect. Only the most recent request survives: a new request replaces any earlier one that no turn has claimed yet.
+
+Watch for the outcome through these events:
+
+* `session.model_change` when the preference commits.
+* `session.auto_tier_switch_failed` when it does not. This event is ephemeral, so the runtime never persists or replays it on resume. Its `reason` field is one of `policy_rejected`, `request_failed`, `setup_failed`, or `unsupported`, and the previously effective preference stays active.
+
+You can also read the authoritative state at any time through the session's `model.getCurrent` RPC method, which reports the committed `autoTier`, any unclaimed `pendingAutoTier`, and the `activatingAutoTier` currently claimed by an in-progress activation.
+
+| SDK | Change the tier | Return to provider-default routing |
+|-----|-----------------|------------------------------------|
+| Node.js | `session.setAutoTier("balance")` | `session.setAutoTier(null)` |
+| Python | `session.set_auto_tier("balance")` | `session.set_auto_tier(None)` |
+| Go | `session.SetAutoTier(ctx, &tier)` | `session.SetAutoTier(ctx, nil)` |
+| .NET | `session.SetAutoTierAsync(AutoTier.Balance)` | `session.SetAutoTierAsync(null)` |
+| Rust | `session.set_auto_tier(Some(AutoTier::Balance))` | `session.set_auto_tier(None)` |
+| Java | `session.setAutoTier(AutoTier.BALANCE)` | `session.setAutoTier(null)` |
+
+To select the `auto` model and its routing preference in a single call, stage the tier on the model switch instead. The runtime rejects this option when the model is anything other than `auto`.
+
+| SDK | Stage a tier with the switch | Reset to provider-default routing |
+|-----|------------------------------|-----------------------------------|
+| Node.js | `setModel("auto", { autoTier: "balance" })` | `setModel("auto", { autoTier: null })` |
+| Python | `set_model("auto", auto_tier="balance")` | `set_model("auto", auto_tier=None)` |
+| Go | `SetModelOptions{AutoTier: &tier}` | `SetModelOptions{ResetAutoTier: true}` |
+| .NET | `new SetModelOptions { AutoTier = AutoTier.Balance }` | `new SetModelOptions { ResetAutoTier = true }` |
+| Rust | `SetModelOptions::default().with_auto_tier(AutoTier::Balance)` | `SetModelOptions::default().with_reset_auto_tier()` |
+| Java | `new SetModelOptions().setModel("auto").setAutoTier(AutoTier.BALANCE)` | `new SetModelOptions().setModel("auto").setResetAutoTier(true)` |
+
+Node.js, Python, and Rust express all three states in a single value: Node.js and Python because `null`/`None` is distinguishable from an omitted argument, and Rust because `AutoTierPreference::Reset` is a distinct variant of the same option. Go, .NET, and Java have no way to distinguish "reset" from "unset" in one value, so they carry a separate reset flag. Omitting both always means "leave the current preference alone."
+
 ### Example: changing model on resume
 
 ```typescript

dotnet/README.md

@@ -284,6 +284,27 @@ await session2.DisposeAsync();
 
 ---
 
+## Auto routing tiers
+
+Change the Auto routing preference without changing the selected model. The runtime does not apply the preference immediately: it records the request and commits it only when a later user turn using the `auto` model successfully obtains a usable model from the provider, so a `pending` status confirms acceptance rather than effect. Only the most recent request survives.
+
+Watch for the outcome through the `session.model_change` event on success or the ephemeral `session.auto_tier_switch_failed` event on failure. Read the authoritative committed, pending, and activating preferences at any time through the session's `model.getCurrent` RPC method.
+
+```csharp
+var result = await session.SetAutoTierAsync(AutoTier.Intelligence);
+if (result.Status == ModelSwitchAutoTierStatus.Pending)
+{
+    // Accepted, but not yet in effect.
+}
+
+// Return to the provider's default Auto routing.
+await session.SetAutoTierAsync(null);
+```
+
+`SetModelAsync` accepts the same preference through `SetModelOptions.AutoTier`, which stages the tier atomically with selecting `auto`. Set `ResetAutoTier` instead to return to provider-default routing; the two options are mutually exclusive.
+
+See [Auto tier persistence](../docs/features/session-persistence.md#auto-tier-persistence) for the full lifecycle rules.
+
 ## Event Types
 
 Sessions emit various events during processing. Each event type is a class that inherits from `SessionEvent`:

dotnet/src/Session.cs

@@ -11,6 +11,7 @@
 using System.Text.Json;
 using System.Text.Json.Nodes;
 using System.Text.Json.Serialization;
+using System.Text.Json.Serialization.Metadata;
 using System.Threading.Channels;
 
 namespace GitHub.Copilot;
@@ -1927,8 +1928,35 @@ public async Task SetModelAsync(string model, SetModelOptions options, Cancellat
         ArgumentNullException.ThrowIfNull(model);
         ThrowIfDisposed();
 
+        if (options.AutoTier is not null && options.ResetAutoTier)
+        {
+            throw new ArgumentException(
+                $"{nameof(SetModelOptions.AutoTier)} and {nameof(SetModelOptions.ResetAutoTier)} are mutually exclusive.",
+                nameof(options));
+        }
+
+        if (options.ResetAutoTier)
+        {
+            var request = new ModelSwitchToRequest
+            {
+                SessionId = SessionId,
+                ModelId = model,
+                ReasoningEffort = options.ReasoningEffort,
+                ReasoningSummary = options.ReasoningSummary,
+                ModelCapabilities = options.ModelCapabilities,
+                ContextTier = options.ContextTier,
+            };
+            await CopilotClient.InvokeRpcAsync(
+                Rpc,
+                "session.model.switchTo",
+                [WithExplicitNullAutoTier(request, RpcJsonContext.Default.ModelSwitchToRequest)],
+                cancellationToken);
+            return;
+        }
+
         await Rpc.Model.SwitchToAsync(
             modelId: model,
+            autoTier: options.AutoTier,
             reasoningEffort: options.ReasoningEffort,
             reasoningSummary: options.ReasoningSummary,
             verbosity: null,
@@ -1938,6 +1966,69 @@ await Rpc.Model.SwitchToAsync(
             cancellationToken: cancellationToken);
     }
 
+    /// <summary>
+    /// Changes the Auto routing preference without changing the selected model.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// The runtime does not apply the preference immediately. It records the request and
+    /// commits it only when a later user turn using the <c>auto</c> model successfully
+    /// obtains a usable model from the provider. A <c>pending</c> status therefore confirms
+    /// that the request was accepted, not that it took effect.
+    /// </para>
+    /// <para>
+    /// Watch for the outcome through the <c>session.model_change</c> event on success, or the
+    /// ephemeral <c>session.auto_tier_switch_failed</c> event on failure. You can also read
+    /// the current committed and in-flight state at any time with
+    /// <c>session.Rpc.Model.GetCurrentAsync</c>.
+    /// </para>
+    /// <para>
+    /// Only the most recent request survives: issuing a new request replaces any earlier one
+    /// that has not yet been claimed by a turn.
+    /// </para>
+    /// </remarks>
+    /// <param name="autoTier">Routing preference to activate, or <see langword="null"/> to return to the provider's default Auto routing.</param>
+    /// <param name="cancellationToken">Optional cancellation token.</param>
+    /// <returns>The runtime's immediate acknowledgement and Auto preference snapshot.</returns>
+    /// <example>
+    /// <code>
+    /// var result = await session.SetAutoTierAsync(AutoTier.Intelligence);
+    /// </code>
+    /// </example>
+    [Experimental(Diagnostics.Experimental)]
+    public async Task<ModelSwitchAutoTierResult> SetAutoTierAsync(AutoTier? autoTier, CancellationToken cancellationToken = default)
+    {
+        ThrowIfDisposed();
+
+        if (autoTier is not null)
+        {
+            return await Rpc.Model.SwitchAutoTierAsync(autoTier, cancellationToken: cancellationToken);
+        }
+
+        var request = new ModelSwitchAutoTierRequest { SessionId = SessionId };
+        return await CopilotClient.InvokeRpcAsync<ModelSwitchAutoTierResult>(
+            Rpc,
+            "session.model.switchAutoTier",
+            [WithExplicitNullAutoTier(request, RpcJsonContext.Default.ModelSwitchAutoTierRequest)],
+            cancellationToken);
+    }
+
+    /// <summary>
+    /// Serializes a generated request and restores the <c>autoTier</c> property as an explicit null.
+    /// </summary>
+    /// <remarks>
+    /// The generated request types omit <c>autoTier</c> when it is null. The runtime reads an
+    /// omitted tier as "leave the current preference alone" and an explicit null as "return to
+    /// provider-default Auto routing", so the null has to survive serialization. Serializing the
+    /// generated type keeps every other field on the request in sync with the schema.
+    /// </remarks>
+    private static JsonObject WithExplicitNullAutoTier<T>(T request, JsonTypeInfo<T> typeInfo)
+    {
+        var payload = JsonSerializer.SerializeToNode(request, typeInfo)!.AsObject();
+        payload["autoTier"] = null;
+        return payload;
+    }
+
     /// <summary>
     /// Changes the model for this session.
     /// </summary>

dotnet/src/Types.cs

@@ -2447,9 +2447,11 @@ public sealed class CapiSessionOptions
     /// </summary>
     /// <remarks>
     /// Requires a runtime that supports Auto tiers; it has no effect outside V2 Auto.
-    /// When omitted, the runtime uses its default on create and preserves the persisted or current
-    /// tier on resume. An explicit tier overrides the persisted tier on a cold resume; a conflicting
-    /// tier on a resident session resume is rejected by the runtime.
+    /// When omitted, the runtime uses its default on create and restores the last committed
+    /// tier on cold resume. On resident resume, a different tier requests a safe switch that
+    /// takes effect after resume succeeds and never disturbs a turn that is already running.
+    /// To change the preference on a live session, use
+    /// <see cref="CopilotSession.SetAutoTierAsync"/>.
     /// </remarks>
     [JsonPropertyName("autoTier")]
     public AutoTier? AutoTier { get; set; }
@@ -3017,6 +3019,26 @@ public struct SetModelOptions
 
     /// <summary>Per-property overrides for model capabilities, deep-merged over runtime defaults.</summary>
     public ModelCapabilitiesOverride? ModelCapabilities { get; set; }
+
+    /// <summary>
+    /// Routing preference to stage atomically with selecting the <c>auto</c> model.
+    /// </summary>
+    /// <remarks>
+    /// Leave unset to leave the current preference alone. Set
+    /// <see cref="ResetAutoTier"/> instead to return to the provider's default Auto
+    /// routing. The runtime rejects this option when the model is anything other than
+    /// <c>auto</c>; use <see cref="CopilotSession.SetAutoTierAsync"/> to change the
+    /// preference without changing the selected model.
+    /// </remarks>
+    [Experimental(Diagnostics.Experimental)]
+    public AutoTier? AutoTier { get; set; }
+
+    /// <summary>
+    /// Returns to the provider's default Auto routing as part of this switch.
+    /// Mutually exclusive with <see cref="AutoTier"/>.
+    /// </summary>
+    [Experimental(Diagnostics.Experimental)]
+    public bool ResetAutoTier { get; set; }
 }
 
 /// <summary>

dotnet/test/E2E/AutoTierE2ETests.cs

@@ -0,0 +1,88 @@
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) Microsoft Corporation. All rights reserved.
+ *--------------------------------------------------------------------------------------------*/
+
+using GitHub.Copilot.Rpc;
+using GitHub.Copilot.Test.Harness;
+using Xunit;
+using Xunit.Abstractions;
+
+namespace GitHub.Copilot.Test.E2E;
+
+/// <summary>
+/// Mirrors nodejs/test/e2e/auto_tier.e2e.test.ts (snapshot category "auto_tier").
+/// </summary>
+/// <remarks>
+/// The runtime stages an Auto routing preference instead of applying it immediately: a
+/// request stays unclaimed until a later turn using the <c>auto</c> model mints a usable
+/// model and token pair. These tests observe that staged state through
+/// <c>Model.GetCurrentAsync</c>, so they assert what the runtime actually recorded rather
+/// than what the SDK serialized.
+/// </remarks>
+public class AutoTierE2ETests(E2ETestFixture fixture, ITestOutputHelper output)
+    : E2ETestBase(fixture, "auto_tier", output)
+{
+    private static async Task AssertPendingAutoTierAsync(CopilotSession session, AutoTier? expected)
+    {
+        var current = await session.Rpc.Model.GetCurrentAsync();
+        Assert.Equal(expected, current.PendingAutoTier);
+    }
+
+    [Fact]
+    public async Task Should_Stage_And_Reset_Auto_Tier_Preference()
+    {
+        await using var session = await CreateSessionAsync(new SessionConfig
+        {
+            Model = "auto",
+            OnPermissionRequest = PermissionHandler.ApproveAll,
+        });
+
+        await AssertPendingAutoTierAsync(session, null);
+
+        var staged = await session.SetAutoTierAsync(AutoTier.Efficiency);
+        Assert.Equal(ModelSwitchAutoTierStatus.Pending, staged.Status);
+        Assert.Equal(AutoTier.Efficiency, staged.PendingAutoTier);
+        await AssertPendingAutoTierAsync(session, AutoTier.Efficiency);
+
+        // A second request replaces the first and reports the one it displaced.
+        var superseded = await session.SetAutoTierAsync(AutoTier.Intelligence);
+        Assert.Equal(ModelSwitchAutoTierStatus.Pending, superseded.Status);
+        Assert.Equal(AutoTier.Intelligence, superseded.PendingAutoTier);
+        Assert.Equal(AutoTier.Efficiency, superseded.SupersededAutoTier);
+        await AssertPendingAutoTierAsync(session, AutoTier.Intelligence);
+
+        // A null tier returns the session to provider-default routing. The status is
+        // Unchanged because provider-default was already the committed preference; the
+        // request's effect is cancelling the staged one.
+        var reset = await session.SetAutoTierAsync(null);
+        Assert.Equal(ModelSwitchAutoTierStatus.Unchanged, reset.Status);
+        Assert.Equal(AutoTier.Intelligence, reset.SupersededAutoTier);
+        await AssertPendingAutoTierAsync(session, null);
+    }
+
+    [Fact]
+    public async Task Should_Preserve_Auto_Tier_When_Set_Model_Omits_It()
+    {
+        await using var session = await CreateSessionAsync(new SessionConfig
+        {
+            Model = "auto",
+            OnPermissionRequest = PermissionHandler.ApproveAll,
+        });
+
+        await session.SetAutoTierAsync(AutoTier.Balance);
+        await AssertPendingAutoTierAsync(session, AutoTier.Balance);
+
+        // Leaving AutoTier unset without asking for a reset leaves the staged preference alone.
+        await session.SetModelAsync("auto", new SetModelOptions());
+        await AssertPendingAutoTierAsync(session, AutoTier.Balance);
+
+        // Supplying a tier replaces it.
+        await session.SetModelAsync("auto", new SetModelOptions { AutoTier = AutoTier.Intelligence });
+        await AssertPendingAutoTierAsync(session, AutoTier.Intelligence);
+
+        // ResetAutoTier clears it. Omission, a value, and a reset are three distinct
+        // outcomes, which is why a single nullable property cannot express the request.
+        await session.SetModelAsync("auto", new SetModelOptions { ResetAutoTier = true });
+        await AssertPendingAutoTierAsync(session, null);
+    }
+}