chore: move chat methods to ExperimentalClient (#23441)

- Changes all 41 chat method receivers in `codersdk/chats.go` from
`*Client` to `*ExperimentalClient` to ensure that callers are aware that
these reference potentially unstable `/api/experimental` endpoints.


> 🤖 This PR was created with the help of Coder Agents, and has been
reviewed by my human. 🧑‍💻

coderd/chatd/chatd_test.go

@@ -111,6 +111,7 @@ func TestSubagentChatExcludesWorkspaceProvisioningTools(t *testing.T) {
 		IncludeProvisionerDaemon: true,
 	})
 	user := coderdtest.CreateFirstUser(t, client)
+	expClient := codersdk.NewExperimentalClient(client)
 
 	agentToken := uuid.NewString()
 	version := coderdtest.CreateTemplateVersion(t, client, user.OrganizationID, &echo.Responses{
@@ -161,7 +162,7 @@ func TestSubagentChatExcludesWorkspaceProvisioningTools(t *testing.T) {
 		)
 	})
 
-	_, err := client.CreateChatProvider(ctx, codersdk.CreateChatProviderConfigRequest{
+	_, err := expClient.CreateChatProvider(ctx, codersdk.CreateChatProviderConfigRequest{
 		Provider: "openai-compat",
 		APIKey:   "test-api-key",
 		BaseURL:  openAIURL,
@@ -170,7 +171,7 @@ func TestSubagentChatExcludesWorkspaceProvisioningTools(t *testing.T) {
 
 	contextLimit := int64(4096)
 	isDefault := true
-	_, err = client.CreateChatModelConfig(ctx, codersdk.CreateChatModelConfigRequest{
+	_, err = expClient.CreateChatModelConfig(ctx, codersdk.CreateChatModelConfigRequest{
 		Provider:     "openai-compat",
 		Model:        "gpt-4o-mini",
 		ContextLimit: &contextLimit,
@@ -179,7 +180,7 @@ func TestSubagentChatExcludesWorkspaceProvisioningTools(t *testing.T) {
 	require.NoError(t, err)
 
 	// Create a root chat whose first model call will spawn a subagent.
-	chat, err := client.CreateChat(ctx, codersdk.CreateChatRequest{
+	chat, err := expClient.CreateChat(ctx, codersdk.CreateChatRequest{
 		Content: []codersdk.ChatInputPart{
 			{
 				Type: codersdk.ChatInputPartTypeText,
@@ -193,7 +194,7 @@ func TestSubagentChatExcludesWorkspaceProvisioningTools(t *testing.T) {
 	// The root chat finishes first, then the chatd server
 	// picks up and runs the child (subagent) chat.
 	require.Eventually(t, func() bool {
-		got, getErr := client.GetChat(ctx, chat.ID)
+		got, getErr := expClient.GetChat(ctx, chat.ID)
 		if getErr != nil {
 			return false
 		}
@@ -1844,6 +1845,7 @@ func TestCreateWorkspaceTool_EndToEnd(t *testing.T) {
 		IncludeProvisionerDaemon: true,
 	})
 	user := coderdtest.CreateFirstUser(t, client)
+	expClient := codersdk.NewExperimentalClient(client)
 
 	agentToken := uuid.NewString()
 	// Add a startup script so the agent spends time in the
@@ -1898,7 +1900,7 @@ func TestCreateWorkspaceTool_EndToEnd(t *testing.T) {
 		)
 	})
 
-	_, err := client.CreateChatProvider(ctx, codersdk.CreateChatProviderConfigRequest{
+	_, err := expClient.CreateChatProvider(ctx, codersdk.CreateChatProviderConfigRequest{
 		Provider: "openai-compat",
 		APIKey:   "test-api-key",
 		BaseURL:  openAIURL,
@@ -1907,7 +1909,7 @@ func TestCreateWorkspaceTool_EndToEnd(t *testing.T) {
 
 	contextLimit := int64(4096)
 	isDefault := true
-	_, err = client.CreateChatModelConfig(ctx, codersdk.CreateChatModelConfigRequest{
+	_, err = expClient.CreateChatModelConfig(ctx, codersdk.CreateChatModelConfigRequest{
 		Provider:     "openai-compat",
 		Model:        "gpt-4o-mini",
 		ContextLimit: &contextLimit,
@@ -1915,7 +1917,7 @@ func TestCreateWorkspaceTool_EndToEnd(t *testing.T) {
 	})
 	require.NoError(t, err)
 
-	chat, err := client.CreateChat(ctx, codersdk.CreateChatRequest{
+	chat, err := expClient.CreateChat(ctx, codersdk.CreateChatRequest{
 		Content: []codersdk.ChatInputPart{
 			{
 				Type: codersdk.ChatInputPartTypeText,
@@ -1927,7 +1929,7 @@ func TestCreateWorkspaceTool_EndToEnd(t *testing.T) {
 
 	var chatResult codersdk.Chat
 	require.Eventually(t, func() bool {
-		got, getErr := client.GetChat(ctx, chat.ID)
+		got, getErr := expClient.GetChat(ctx, chat.ID)
 		if getErr != nil {
 			return false
 		}
@@ -1949,7 +1951,7 @@ func TestCreateWorkspaceTool_EndToEnd(t *testing.T) {
 	require.NoError(t, err)
 	require.Equal(t, workspaceName, workspace.Name)
 
-	chatMsgs, err := client.GetChatMessages(ctx, chat.ID, nil)
+	chatMsgs, err := expClient.GetChatMessages(ctx, chat.ID, nil)
 	require.NoError(t, err)
 
 	var foundCreateWorkspaceResult bool
@@ -2023,6 +2025,7 @@ func TestStartWorkspaceTool_EndToEnd(t *testing.T) {
 		IncludeProvisionerDaemon: true,
 	})
 	user := coderdtest.CreateFirstUser(t, client)
+	expClient := codersdk.NewExperimentalClient(client)
 
 	version := coderdtest.CreateTemplateVersion(t, client, user.OrganizationID, &echo.Responses{
 		Parse:          echo.ParseComplete,
@@ -2067,7 +2070,7 @@ func TestStartWorkspaceTool_EndToEnd(t *testing.T) {
 		)
 	})
 
-	_, err := client.CreateChatProvider(ctx, codersdk.CreateChatProviderConfigRequest{
+	_, err := expClient.CreateChatProvider(ctx, codersdk.CreateChatProviderConfigRequest{
 		Provider: "openai-compat",
 		APIKey:   "test-api-key",
 		BaseURL:  openAIURL,
@@ -2076,7 +2079,7 @@ func TestStartWorkspaceTool_EndToEnd(t *testing.T) {
 
 	contextLimit := int64(4096)
 	isDefault := true
-	_, err = client.CreateChatModelConfig(ctx, codersdk.CreateChatModelConfigRequest{
+	_, err = expClient.CreateChatModelConfig(ctx, codersdk.CreateChatModelConfigRequest{
 		Provider:     "openai-compat",
 		Model:        "gpt-4o-mini",
 		ContextLimit: &contextLimit,
@@ -2085,7 +2088,7 @@ func TestStartWorkspaceTool_EndToEnd(t *testing.T) {
 	require.NoError(t, err)
 
 	// Create a chat with the stopped workspace pre-associated.
-	chat, err := client.CreateChat(ctx, codersdk.CreateChatRequest{
+	chat, err := expClient.CreateChat(ctx, codersdk.CreateChatRequest{
 		Content: []codersdk.ChatInputPart{
 			{
 				Type: codersdk.ChatInputPartTypeText,
@@ -2098,7 +2101,7 @@ func TestStartWorkspaceTool_EndToEnd(t *testing.T) {
 
 	var chatResult codersdk.Chat
 	require.Eventually(t, func() bool {
-		got, getErr := client.GetChat(ctx, chat.ID)
+		got, getErr := expClient.GetChat(ctx, chat.ID)
 		if getErr != nil {
 			return false
 		}
@@ -2120,7 +2123,7 @@ func TestStartWorkspaceTool_EndToEnd(t *testing.T) {
 	require.NoError(t, err)
 	require.Equal(t, codersdk.WorkspaceTransitionStart, updatedWorkspace.LatestBuild.Transition)
 
-	chatMsgs, err := client.GetChatMessages(ctx, chat.ID, nil)
+	chatMsgs, err := expClient.GetChatMessages(ctx, chat.ID, nil)
 	require.NoError(t, err)
 
 	// Verify start_workspace tool result exists in the chat messages.

coderd/chatd/integration_test.go

@@ -42,9 +42,10 @@ func TestAnthropicWebSearchRoundTrip(t *testing.T) {
 		DeploymentValues: deploymentValues,
 	})
 	_ = coderdtest.CreateFirstUser(t, client)
+	expClient := codersdk.NewExperimentalClient(client)
 
 	// Configure an Anthropic provider with the real API key.
-	_, err := client.CreateChatProvider(ctx, codersdk.CreateChatProviderConfigRequest{
+	_, err := expClient.CreateChatProvider(ctx, codersdk.CreateChatProviderConfigRequest{
 		Provider: "anthropic",
 		APIKey:   apiKey,
 		BaseURL:  baseURL,
@@ -54,7 +55,7 @@ func TestAnthropicWebSearchRoundTrip(t *testing.T) {
 	// Create a model config that enables web_search.
 	contextLimit := int64(200000)
 	isDefault := true
-	_, err = client.CreateChatModelConfig(ctx, codersdk.CreateChatModelConfigRequest{
+	_, err = expClient.CreateChatModelConfig(ctx, codersdk.CreateChatModelConfigRequest{
 		Provider:     "anthropic",
 		Model:        "claude-sonnet-4-20250514",
 		ContextLimit: &contextLimit,
@@ -71,7 +72,7 @@ func TestAnthropicWebSearchRoundTrip(t *testing.T) {
 
 	// --- Step 1: Send a message that triggers web_search ---
 	t.Log("Creating chat with web search query...")
-	chat, err := client.CreateChat(ctx, codersdk.CreateChatRequest{
+	chat, err := expClient.CreateChat(ctx, codersdk.CreateChatRequest{
 		Content: []codersdk.ChatInputPart{
 			{
 				Type: codersdk.ChatInputPartTypeText,
@@ -83,16 +84,16 @@ func TestAnthropicWebSearchRoundTrip(t *testing.T) {
 	t.Logf("Chat created: %s (status=%s)", chat.ID, chat.Status)
 
 	// Stream events until the chat reaches a terminal status.
-	events, closer, err := client.StreamChat(ctx, chat.ID, nil)
+	events, closer, err := expClient.StreamChat(ctx, chat.ID, nil)
 	require.NoError(t, err)
 	defer closer.Close()
 
 	waitForChatDone(ctx, t, events, "step 1")
 
 	// Verify the chat completed and messages were persisted.
-	chatData, err := client.GetChat(ctx, chat.ID)
+	chatData, err := expClient.GetChat(ctx, chat.ID)
 	require.NoError(t, err)
-	chatMsgs, err := client.GetChatMessages(ctx, chat.ID, nil)
+	chatMsgs, err := expClient.GetChatMessages(ctx, chat.ID, nil)
 	require.NoError(t, err)
 	t.Logf("Chat status after step 1: %s, messages: %d",
 		chatData.Status, len(chatMsgs.Messages))
@@ -133,7 +134,7 @@ func TestAnthropicWebSearchRoundTrip(t *testing.T) {
 	// by Anthropic because server_tool_use has no matching
 	// web_search_tool_result.
 	t.Log("Sending follow-up message...")
-	_, err = client.CreateChatMessage(ctx, chat.ID,
+	_, err = expClient.CreateChatMessage(ctx, chat.ID,
 		codersdk.CreateChatMessageRequest{
 			Content: []codersdk.ChatInputPart{
 				{
@@ -145,16 +146,16 @@ func TestAnthropicWebSearchRoundTrip(t *testing.T) {
 	require.NoError(t, err)
 
 	// Stream the follow-up response.
-	events2, closer2, err := client.StreamChat(ctx, chat.ID, nil)
+	events2, closer2, err := expClient.StreamChat(ctx, chat.ID, nil)
 	require.NoError(t, err)
 	defer closer2.Close()
 
 	waitForChatDone(ctx, t, events2, "step 2")
 
 	// Verify the follow-up completed and produced content.
-	chatData2, err := client.GetChat(ctx, chat.ID)
+	chatData2, err := expClient.GetChat(ctx, chat.ID)
 	require.NoError(t, err)
-	chatMsgs2, err := client.GetChatMessages(ctx, chat.ID, nil)
+	chatMsgs2, err := expClient.GetChatMessages(ctx, chat.ID, nil)
 	require.NoError(t, err)
 	t.Logf("Chat status after step 2: %s, messages: %d",
 		chatData2.Status, len(chatMsgs2.Messages))
@@ -301,9 +302,10 @@ func TestOpenAIReasoningRoundTrip(t *testing.T) {
 		DeploymentValues: deploymentValues,
 	})
 	_ = coderdtest.CreateFirstUser(t, client)
+	expClient := codersdk.NewExperimentalClient(client)
 
 	// Configure an OpenAI provider with the real API key.
-	_, err := client.CreateChatProvider(ctx, codersdk.CreateChatProviderConfigRequest{
+	_, err := expClient.CreateChatProvider(ctx, codersdk.CreateChatProviderConfigRequest{
 		Provider: "openai",
 		APIKey:   apiKey,
 		BaseURL:  baseURL,
@@ -316,7 +318,7 @@ func TestOpenAIReasoningRoundTrip(t *testing.T) {
 	contextLimit := int64(200000)
 	isDefault := true
 	reasoningSummary := "auto"
-	_, err = client.CreateChatModelConfig(ctx, codersdk.CreateChatModelConfigRequest{
+	_, err = expClient.CreateChatModelConfig(ctx, codersdk.CreateChatModelConfigRequest{
 		Provider:     "openai",
 		Model:        "o4-mini",
 		ContextLimit: &contextLimit,
@@ -334,7 +336,7 @@ func TestOpenAIReasoningRoundTrip(t *testing.T) {
 
 	// --- Step 1: Send a message that triggers reasoning ---
 	t.Log("Creating chat with reasoning query...")
-	chat, err := client.CreateChat(ctx, codersdk.CreateChatRequest{
+	chat, err := expClient.CreateChat(ctx, codersdk.CreateChatRequest{
 		Content: []codersdk.ChatInputPart{
 			{
 				Type: codersdk.ChatInputPartTypeText,
@@ -346,16 +348,16 @@ func TestOpenAIReasoningRoundTrip(t *testing.T) {
 	t.Logf("Chat created: %s (status=%s)", chat.ID, chat.Status)
 
 	// Stream events until the chat reaches a terminal status.
-	events, closer, err := client.StreamChat(ctx, chat.ID, nil)
+	events, closer, err := expClient.StreamChat(ctx, chat.ID, nil)
 	require.NoError(t, err)
 	defer closer.Close()
 
 	waitForChatDone(ctx, t, events, "step 1")
 
 	// Verify the chat completed and messages were persisted.
-	chatData, err := client.GetChat(ctx, chat.ID)
+	chatData, err := expClient.GetChat(ctx, chat.ID)
 	require.NoError(t, err)
-	chatMsgs, err := client.GetChatMessages(ctx, chat.ID, nil)
+	chatMsgs, err := expClient.GetChatMessages(ctx, chat.ID, nil)
 	require.NoError(t, err)
 	t.Logf("Chat status after step 1: %s, messages: %d",
 		chatData.Status, len(chatMsgs.Messages))
@@ -382,7 +384,7 @@ func TestOpenAIReasoningRoundTrip(t *testing.T) {
 	//   Item 'rs_xxx' of type 'reasoning' was provided without its
 	//   required following item.
 	t.Log("Sending follow-up message...")
-	_, err = client.CreateChatMessage(ctx, chat.ID,
+	_, err = expClient.CreateChatMessage(ctx, chat.ID,
 		codersdk.CreateChatMessageRequest{
 			Content: []codersdk.ChatInputPart{
 				{
@@ -394,16 +396,16 @@ func TestOpenAIReasoningRoundTrip(t *testing.T) {
 	require.NoError(t, err)
 
 	// Stream the follow-up response.
-	events2, closer2, err := client.StreamChat(ctx, chat.ID, nil)
+	events2, closer2, err := expClient.StreamChat(ctx, chat.ID, nil)
 	require.NoError(t, err)
 	defer closer2.Close()
 
 	waitForChatDone(ctx, t, events2, "step 2")
 
 	// Verify the follow-up completed and produced content.
-	chatData2, err := client.GetChat(ctx, chat.ID)
+	chatData2, err := expClient.GetChat(ctx, chat.ID)
 	require.NoError(t, err)
-	chatMsgs2, err := client.GetChatMessages(ctx, chat.ID, nil)
+	chatMsgs2, err := expClient.GetChatMessages(ctx, chat.ID, nil)
 	require.NoError(t, err)
 	t.Logf("Chat status after step 2: %s, messages: %d",
 		chatData2.Status, len(chatMsgs2.Messages))
@@ -454,9 +456,10 @@ func TestOpenAIReasoningRoundTripStoreFalse(t *testing.T) {
 		DeploymentValues: deploymentValues,
 	})
 	_ = coderdtest.CreateFirstUser(t, client)
+	expClient := codersdk.NewExperimentalClient(client)
 
 	// Configure an OpenAI provider with the real API key.
-	_, err := client.CreateChatProvider(ctx, codersdk.CreateChatProviderConfigRequest{
+	_, err := expClient.CreateChatProvider(ctx, codersdk.CreateChatProviderConfigRequest{
 		Provider: "openai",
 		APIKey:   apiKey,
 		BaseURL:  baseURL,
@@ -468,7 +471,7 @@ func TestOpenAIReasoningRoundTripStoreFalse(t *testing.T) {
 	contextLimit := int64(200000)
 	isDefault := true
 	reasoningSummary := "auto"
-	_, err = client.CreateChatModelConfig(ctx, codersdk.CreateChatModelConfigRequest{
+	_, err = expClient.CreateChatModelConfig(ctx, codersdk.CreateChatModelConfigRequest{
 		Provider:     "openai",
 		Model:        "o4-mini",
 		ContextLimit: &contextLimit,
@@ -486,7 +489,7 @@ func TestOpenAIReasoningRoundTripStoreFalse(t *testing.T) {
 
 	// --- Step 1: Send a message that triggers reasoning ---
 	t.Log("Creating chat with reasoning query...")
-	chat, err := client.CreateChat(ctx, codersdk.CreateChatRequest{
+	chat, err := expClient.CreateChat(ctx, codersdk.CreateChatRequest{
 		Content: []codersdk.ChatInputPart{
 			{
 				Type: codersdk.ChatInputPartTypeText,
@@ -498,16 +501,16 @@ func TestOpenAIReasoningRoundTripStoreFalse(t *testing.T) {
 	t.Logf("Chat created: %s (status=%s)", chat.ID, chat.Status)
 
 	// Stream events until the chat reaches a terminal status.
-	events, closer, err := client.StreamChat(ctx, chat.ID, nil)
+	events, closer, err := expClient.StreamChat(ctx, chat.ID, nil)
 	require.NoError(t, err)
 	defer closer.Close()
 
 	waitForChatDone(ctx, t, events, "step 1")
 
 	// Verify the chat completed and messages were persisted.
-	chatData, err := client.GetChat(ctx, chat.ID)
+	chatData, err := expClient.GetChat(ctx, chat.ID)
 	require.NoError(t, err)
-	chatMsgs, err := client.GetChatMessages(ctx, chat.ID, nil)
+	chatMsgs, err := expClient.GetChatMessages(ctx, chat.ID, nil)
 	require.NoError(t, err)
 	t.Logf("Chat status after step 1: %s, messages: %d",
 		chatData.Status, len(chatMsgs.Messages))
@@ -531,7 +534,7 @@ func TestOpenAIReasoningRoundTripStoreFalse(t *testing.T) {
 	// This is the critical test: when Store is false, item IDs are
 	// ephemeral and cannot be looked up from OpenAI later.
 	t.Log("Sending follow-up message...")
-	_, err = client.CreateChatMessage(ctx, chat.ID,
+	_, err = expClient.CreateChatMessage(ctx, chat.ID,
 		codersdk.CreateChatMessageRequest{
 			Content: []codersdk.ChatInputPart{
 				{
@@ -548,16 +551,16 @@ func TestOpenAIReasoningRoundTripStoreFalse(t *testing.T) {
 	require.NoError(t, err)
 
 	// Stream the follow-up response.
-	events2, closer2, err := client.StreamChat(ctx, chat.ID, nil)
+	events2, closer2, err := expClient.StreamChat(ctx, chat.ID, nil)
 	require.NoError(t, err)
 	defer closer2.Close()
 
 	waitForChatDone(ctx, t, events2, "step 2")
 
 	// Verify the follow-up completed and produced content.
-	chatData2, err := client.GetChat(ctx, chat.ID)
+	chatData2, err := expClient.GetChat(ctx, chat.ID)
 	require.NoError(t, err)
-	chatMsgs2, err := client.GetChatMessages(ctx, chat.ID, nil)
+	chatMsgs2, err := expClient.GetChatMessages(ctx, chat.ID, nil)
 	require.NoError(t, err)
 	t.Logf("Chat status after step 2: %s, messages: %d",
 		chatData2.Status, len(chatMsgs2.Messages))

coderd/mcp_test.go

@@ -437,14 +437,16 @@ func TestChatWithMCPServerIDs(t *testing.T) {
 	client := newMCPClient(t)
 	_ = coderdtest.CreateFirstUser(t, client)
 
+	expClient := codersdk.NewExperimentalClient(client)
+
 	// Create the chat model config required for creating a chat.
-	_ = createChatModelConfigForMCP(t, client)
+	_ = createChatModelConfigForMCP(t, expClient)
 
 	// Create an enabled MCP server config.
 	mcpConfig := createMCPServerConfig(t, client, "chat-mcp-server", true)
 
 	// Create a chat referencing the MCP server.
-	chat, err := client.CreateChat(ctx, codersdk.CreateChatRequest{
+	chat, err := expClient.CreateChat(ctx, codersdk.CreateChatRequest{
 		Content: []codersdk.ChatInputPart{
 			{
 				Type: codersdk.ChatInputPartTypeText,
@@ -458,7 +460,7 @@ func TestChatWithMCPServerIDs(t *testing.T) {
 	require.Contains(t, chat.MCPServerIDs, mcpConfig.ID)
 
 	// Fetch the chat and verify the MCP server IDs persist.
-	fetched, err := client.GetChat(ctx, chat.ID)
+	fetched, err := expClient.GetChat(ctx, chat.ID)
 	require.NoError(t, err)
 	require.Contains(t, fetched.MCPServerIDs, mcpConfig.ID)
 }
@@ -466,7 +468,7 @@ func TestChatWithMCPServerIDs(t *testing.T) {
 // createChatModelConfigForMCP sets up a chat provider and model
 // config so that CreateChat succeeds. This mirrors the helper in
 // chats_test.go but is defined here to avoid coupling.
-func createChatModelConfigForMCP(t testing.TB, client *codersdk.Client) codersdk.ChatModelConfig {
+func createChatModelConfigForMCP(t testing.TB, client *codersdk.ExperimentalClient) codersdk.ChatModelConfig {
 	t.Helper()
 
 	ctx := testutil.Context(t, testutil.WaitLong)