Docs n tests for /model feature

Signed-off-by: Christopher Petito <[email protected]>

Author: krissetto

README.md

@@ -32,6 +32,8 @@ experts that collaborate to solve complex problems for you.
 - **🌐 AI provider agnostic** - Support for OpenAI, Anthropic, Gemini, xAI,
   Mistral, Nebius and [Docker Model
   Runner](https://docs.docker.com/ai/model-runner/).
+- **🔀 Runtime model switching** - Change models on-the-fly during a session
+  with the `/model` command, with automatic persistence across session reloads.
 
 ## Your First Agent
 

docs/USAGE.md

@@ -122,9 +122,9 @@ Explain what the code in @pkg/agent/agent.go does
 The agent gets the full file contents and places them in a structured `<attachments>`
 block at the end of the message, while the UI doesn't display full file contents.
 
-#### CLI Interactive Commands
+#### TUI Interactive Commands
 
-During CLI sessions, you can use special commands:
+During TUI sessions, you can use special slash commands. Type `/` to see all available commands or use the command palette (Ctrl+K):
 
 | Command     | Description                                                         |
 |-------------|---------------------------------------------------------------------|
@@ -135,12 +135,35 @@ During CLI sessions, you can use special commands:
 | `/eval`     | Create an evaluation report (usage: /eval [filename])               |
 | `/exit`     | Exit the application                                                |
 | `/export`   | Export the session as HTML (usage: /export [filename])              |
+| `/model`    | Change the model for the current agent (see [Model Switching](#runtime-model-switching)) |
 | `/new`      | Start a new conversation                                            |
 | `/sessions` | Browse and load past sessions                                       |
 | `/shell`    | Start a shell                                                       |
 | `/star`     | Toggle star on current session                                      |
 | `/yolo`     | Toggle automatic approval of tool calls                             |
 
+#### Runtime Model Switching
+
+The `/model` command (or `ctrl+m`) allows you to change the AI model used by the current agent during a session. This is useful when you want to:
+
+- Switch to a more capable model for complex tasks
+- Use a faster/cheaper model for simple queries
+- Test different models without modifying your YAML configuration
+
+**How it works:**
+
+1. Type `/model`, `Ctrl+M` or use the command palette (`Ctrl+K`) and select "Model"
+2. A picker dialog opens showing:
+   - **Config models**: All models defined in your YAML configuration, with the agent's default model marked as "(default)"
+   - **Custom input**: Type any model in `provider/model` format  
+   (e.g., `openai/gpt-5`, `anthropic/claude-sonnet-4-0`)  
+   Alloy models are supported with comma separated definitions (e.g. `provider1/model1,provider2/model2,...`)
+3. Select a model or type a custom one and press Enter
+
+**Persistence:** Your model choice is saved with the session. When you reload a past session using `/sessions`, the model you selected will automatically be restored.
+
+To revert to the agent's default model, select the model marked with "(default)" in the picker.
+
 ## 🔧 Configuration Reference
 
 ### Agent Properties

pkg/agent/agent_test.go

@@ -5,8 +5,11 @@ import (
 	"errors"
 	"testing"
 
+	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 
+	"github.com/docker/cagent/pkg/chat"
+	"github.com/docker/cagent/pkg/model/provider/base"
 	"github.com/docker/cagent/pkg/tools"
 )
 
@@ -83,3 +86,83 @@ func TestAgentTools(t *testing.T) {
 		})
 	}
 }
+
+// mockProvider implements provider.Provider for testing
+type mockProvider struct {
+	id string
+}
+
+func (m *mockProvider) ID() string { return m.id }
+func (m *mockProvider) CreateChatCompletionStream(_ context.Context, _ []chat.Message, _ []tools.Tool) (chat.MessageStream, error) {
+	return nil, nil
+}
+func (m *mockProvider) BaseConfig() base.Config { return base.Config{} }
+
+func TestModelOverride(t *testing.T) {
+	t.Parallel()
+
+	defaultModel := &mockProvider{id: "openai/gpt-4o"}
+	overrideModel := &mockProvider{id: "anthropic/claude-sonnet-4-0"}
+
+	a := New("root", "test", WithModel(defaultModel))
+
+	// Initially should return the default model
+	model := a.Model()
+	assert.Equal(t, "openai/gpt-4o", model.ID())
+	assert.False(t, a.HasModelOverride())
+
+	// Set an override
+	a.SetModelOverride(overrideModel)
+	assert.True(t, a.HasModelOverride())
+
+	// Now Model() should return the override
+	model = a.Model()
+	assert.Equal(t, "anthropic/claude-sonnet-4-0", model.ID())
+
+	// ConfiguredModels should still return the original models
+	configuredModels := a.ConfiguredModels()
+	require.Len(t, configuredModels, 1)
+	assert.Equal(t, "openai/gpt-4o", configuredModels[0].ID())
+
+	// Clear the override
+	a.SetModelOverride(nil)
+	assert.False(t, a.HasModelOverride())
+
+	// Model() should return the default again
+	model = a.Model()
+	assert.Equal(t, "openai/gpt-4o", model.ID())
+}
+
+func TestModelOverride_ConcurrentAccess(t *testing.T) {
+	t.Parallel()
+
+	defaultModel := &mockProvider{id: "default"}
+	overrideModel := &mockProvider{id: "override"}
+
+	a := New("root", "test", WithModel(defaultModel))
+
+	// Run concurrent reads and writes
+	done := make(chan bool)
+
+	// Writer goroutine
+	go func() {
+		for range 100 {
+			a.SetModelOverride(overrideModel)
+			a.SetModelOverride(nil)
+		}
+		done <- true
+	}()
+
+	// Reader goroutine
+	go func() {
+		for range 100 {
+			_ = a.Model()
+			_ = a.HasModelOverride()
+		}
+		done <- true
+	}()
+
+	<-done
+	<-done
+	// If we got here without a race condition panic, the test passes
+}

pkg/runtime/model_switcher_test.go

@@ -0,0 +1,71 @@
+package runtime
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestIsInlineAlloySpec(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name     string
+		modelRef string
+		want     bool
+	}{
+		{
+			name:     "single inline model",
+			modelRef: "openai/gpt-4o",
+			want:     false,
+		},
+		{
+			name:     "two inline models",
+			modelRef: "openai/gpt-4o,anthropic/claude-sonnet-4-0",
+			want:     true,
+		},
+		{
+			name:     "three inline models",
+			modelRef: "openai/gpt-4o,anthropic/claude-sonnet-4-0,google/gemini-2.0-flash",
+			want:     true,
+		},
+		{
+			name:     "with spaces",
+			modelRef: "openai/gpt-4o, anthropic/claude-sonnet-4-0",
+			want:     true,
+		},
+		{
+			name:     "named model (no slash)",
+			modelRef: "my_fast_model",
+			want:     false,
+		},
+		{
+			name:     "comma separated named models (not inline alloy)",
+			modelRef: "fast_model,smart_model",
+			want:     false,
+		},
+		{
+			name:     "mixed named and inline",
+			modelRef: "fast_model,openai/gpt-4o",
+			want:     false, // "fast_model" doesn't contain "/" so it's not an inline alloy
+		},
+		{
+			name:     "empty string",
+			modelRef: "",
+			want:     false,
+		},
+		{
+			name:     "just commas",
+			modelRef: ",,",
+			want:     false, // No valid parts after trimming
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+			got := isInlineAlloySpec(tt.modelRef)
+			assert.Equal(t, tt.want, got)
+		})
+	}
+}

pkg/session/store_test.go

@@ -441,3 +441,96 @@ func TestUpdateSession_Permissions(t *testing.T) {
 	assert.Equal(t, []string{"safe_*"}, retrieved.Permissions.Allow)
 	assert.Equal(t, []string{"dangerous_*"}, retrieved.Permissions.Deny)
 }
+
+func TestAgentModelOverrides_SQLite(t *testing.T) {
+	tempDB := filepath.Join(t.TempDir(), "test_model_overrides.db")
+
+	store, err := NewSQLiteSessionStore(tempDB)
+	require.NoError(t, err)
+	defer store.(*SQLiteSessionStore).Close()
+
+	// Create a session with model overrides
+	session := &Session{
+		ID:        "model-override-session",
+		Title:     "Test Session",
+		CreatedAt: time.Now(),
+		AgentModelOverrides: map[string]string{
+			"root":       "openai/gpt-4o",
+			"researcher": "anthropic/claude-sonnet-4-0",
+		},
+	}
+
+	// Store the session
+	err = store.AddSession(t.Context(), session)
+	require.NoError(t, err)
+
+	// Retrieve the session
+	retrieved, err := store.GetSession(t.Context(), "model-override-session")
+	require.NoError(t, err)
+	require.NotNil(t, retrieved)
+
+	// Verify model overrides were persisted
+	assert.Len(t, retrieved.AgentModelOverrides, 2)
+	assert.Equal(t, "openai/gpt-4o", retrieved.AgentModelOverrides["root"])
+	assert.Equal(t, "anthropic/claude-sonnet-4-0", retrieved.AgentModelOverrides["researcher"])
+}
+
+func TestAgentModelOverrides_Update(t *testing.T) {
+	tempDB := filepath.Join(t.TempDir(), "test_model_overrides_update.db")
+
+	store, err := NewSQLiteSessionStore(tempDB)
+	require.NoError(t, err)
+	defer store.(*SQLiteSessionStore).Close()
+
+	// Create a session without model overrides
+	session := &Session{
+		ID:        "update-model-override-session",
+		Title:     "Test Session",
+		CreatedAt: time.Now(),
+	}
+
+	err = store.AddSession(t.Context(), session)
+	require.NoError(t, err)
+
+	// Update the session with model overrides
+	session.AgentModelOverrides = map[string]string{
+		"root": "google/gemini-2.5-flash",
+	}
+
+	err = store.UpdateSession(t.Context(), session)
+	require.NoError(t, err)
+
+	// Retrieve and verify
+	retrieved, err := store.GetSession(t.Context(), "update-model-override-session")
+	require.NoError(t, err)
+	require.NotNil(t, retrieved)
+
+	assert.Len(t, retrieved.AgentModelOverrides, 1)
+	assert.Equal(t, "google/gemini-2.5-flash", retrieved.AgentModelOverrides["root"])
+}
+
+func TestAgentModelOverrides_EmptyMap(t *testing.T) {
+	tempDB := filepath.Join(t.TempDir(), "test_model_overrides_empty.db")
+
+	store, err := NewSQLiteSessionStore(tempDB)
+	require.NoError(t, err)
+	defer store.(*SQLiteSessionStore).Close()
+
+	// Create a session without model overrides (nil map)
+	session := &Session{
+		ID:        "no-override-session",
+		Title:     "Test Session",
+		CreatedAt: time.Now(),
+	}
+
+	err = store.AddSession(t.Context(), session)
+	require.NoError(t, err)
+
+	// Retrieve the session
+	retrieved, err := store.GetSession(t.Context(), "no-override-session")
+	require.NoError(t, err)
+	require.NotNil(t, retrieved)
+
+	// Verify no model overrides (should be nil or empty)
+	assert.Empty(t, retrieved.AgentModelOverrides)
+}