Docs n tests for editable session titles

Signed-off-by: krissetto <[email protected]>

Author: krissetto

docs/USAGE.md

@@ -172,6 +172,7 @@ During TUI sessions, you can use special slash commands. Type `/` to see all ava
 | `/star`     | Toggle star on current session                                      |
 | `/theme`    | Change the color theme (see [Theming](#theming))                    |
 | `/think`    | Toggle thinking/reasoning mode                                      |
+| `/title`    | Set or regenerate session title (usage: /title [new title])         |
 | `/yolo`     | Toggle automatic approval of tool calls                             |
 
 #### Runtime Model Switching
@@ -279,6 +280,30 @@ Themes can customize colors in three sections: `colors`, `chroma` (syntax highli
 
 See the [built-in themes on GitHub](https://github.com/docker/cagent/tree/main/pkg/tui/styles/themes) for complete examples.
 
+#### Session Title Editing
+
+You can customize session titles to make them more meaningful and easier to find later. By default, cagent automatically generates titles based on your first message, but you can override or regenerate them at any time.
+
+**Using the `/title` command:**
+
+```
+/title                     # Regenerate title using AI (based on at most the last 2 user messages)
+/title My Custom Title     # Set a specific title
+```
+
+**Using the sidebar:**
+
+In the TUI, you can click on the pencil icon (✎) next to the session title in the sidebar to edit it inline:
+
+1. Click the pencil icon next to the title
+2. Type your new title
+3. Press Enter to save, or Escape to cancel
+
+**Notes:**
+- Manually set titles are preserved and won't be overwritten by auto-generation
+- Title changes are persisted immediately to the session
+- Works with both local and remote runtimes
+
 ## 🔧 Configuration Reference
 
 ### Agent Properties

e2e/runtime_test.go

@@ -32,7 +32,7 @@ func TestRuntime_OpenAI_Basic(t *testing.T) {
 
 	response := sess.GetLastAssistantMessageContent()
 	assert.Equal(t, "2 + 2 equals 4.", response)
-	assert.Equal(t, "Simple Math: Addition of 2 and 2", sess.Title)
+	// Title generation is now handled by pkg/app or pkg/server, not the runtime
 }
 
 func TestRuntime_Mistral_Basic(t *testing.T) {
@@ -55,5 +55,5 @@ func TestRuntime_Mistral_Basic(t *testing.T) {
 
 	response := sess.GetLastAssistantMessageContent()
 	assert.Equal(t, "The sum of 2 + 2 is 4.", response)
-	assert.Equal(t, "Math Basics: Simple Addition", sess.Title)
+	// Title generation is now handled by pkg/app or pkg/server, not the runtime
 }

e2e/testdata/cassettes/TestRuntime_Mistral_Basic.yaml

@@ -58,7 +58,7 @@ interactions:
         proto_minor: 1
         content_length: 0
         host: api.mistral.ai
-        body: '{"messages":[{"content":"You are a helpful AI assistant that generates concise, descriptive titles for conversations. You will be given a conversation history and asked to create a single-line title that captures the main topic. Never use newlines or line breaks in your response.","role":"system"},{"content":"Based on the following message a user sent to an AI assistant, generate a short, descriptive title (maximum 50 characters) that captures the main topic or purpose of the conversation. Return ONLY the title text on a single line, nothing else. Do not include any newlines, explanations, or formatting.\n\nUser message: What''s 2+2?\n\n","role":"user"}],"model":"mistral-small","stream_options":{"include_usage":true},"stream":true}'
+        body: '{"messages":[{"content":"You are a helpful AI assistant that generates concise, descriptive titles for conversations. You will be given up to 2 recent user messages and asked to create a single-line title that captures the main topic. Never use newlines or line breaks in your response.","role":"system"},{"content":"Based on the following recent user messages from a conversation with an AI assistant, generate a short, descriptive title (maximum 50 characters) that captures the main topic or purpose of the conversation. Return ONLY the title text on a single line, nothing else. Do not include any newlines, explanations, or formatting.\n\nRecent user messages:\n1. What''s 2+2?\n\n\n","role":"user"}],"model":"mistral-small","stream_options":{"include_usage":true},"stream":true}'
         url: https://api.mistral.ai/v1/chat/completions
         method: POST
       response:

e2e/testdata/cassettes/TestRuntime_OpenAI_Basic.yaml

@@ -52,7 +52,7 @@ interactions:
         proto_minor: 1
         content_length: 0
         host: api.openai.com
-        body: '{"messages":[{"content":"You are a helpful AI assistant that generates concise, descriptive titles for conversations. You will be given a conversation history and asked to create a single-line title that captures the main topic. Never use newlines or line breaks in your response.","role":"system"},{"content":"Based on the following message a user sent to an AI assistant, generate a short, descriptive title (maximum 50 characters) that captures the main topic or purpose of the conversation. Return ONLY the title text on a single line, nothing else. Do not include any newlines, explanations, or formatting.\n\nUser message: What''s 2+2?\n\n","role":"user"}],"model":"gpt-3.5-turbo","stream_options":{"include_usage":true},"stream":true}'
+        body: '{"messages":[{"content":"You are a helpful AI assistant that generates concise, descriptive titles for conversations. You will be given up to 2 recent user messages and asked to create a single-line title that captures the main topic. Never use newlines or line breaks in your response.","role":"system"},{"content":"Based on the following recent user messages from a conversation with an AI assistant, generate a short, descriptive title (maximum 50 characters) that captures the main topic or purpose of the conversation. Return ONLY the title text on a single line, nothing else. Do not include any newlines, explanations, or formatting.\n\nRecent user messages:\n1. What''s 2+2?\n\n\n","role":"user"}],"model":"gpt-3.5-turbo","stream_options":{"include_usage":true},"stream":true}'
         url: https://api.openai.com/v1/chat/completions
         method: POST
       response:

pkg/app/app_test.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"testing"
 
+	tea "charm.land/bubbletea/v2"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 
@@ -140,3 +141,130 @@ func TestApp_NewSession_WithNilSession(t *testing.T) {
 	// Default values
 	assert.False(t, app.Session().Thinking, "NewSession with nil should use default thinking=true")
 }
+
+func TestApp_UpdateSessionTitle(t *testing.T) {
+	t.Parallel()
+
+	ctx := t.Context()
+
+	t.Run("updates title in session", func(t *testing.T) {
+		t.Parallel()
+
+		rt := &mockRuntime{}
+		sess := session.New()
+		events := make(chan tea.Msg, 16)
+		app := &App{
+			runtime: rt,
+			session: sess,
+			events:  events,
+		}
+
+		err := app.UpdateSessionTitle(ctx, "New Title")
+		require.NoError(t, err)
+
+		assert.Equal(t, "New Title", sess.Title)
+
+		// Check that an event was emitted
+		select {
+		case event := <-events:
+			titleEvent, ok := event.(*runtime.SessionTitleEvent)
+			require.True(t, ok, "should emit SessionTitleEvent")
+			assert.Equal(t, "New Title", titleEvent.Title)
+		default:
+			t.Fatal("expected SessionTitleEvent to be emitted")
+		}
+	})
+
+	t.Run("returns error when no session", func(t *testing.T) {
+		t.Parallel()
+
+		rt := &mockRuntime{}
+		app := &App{
+			runtime: rt,
+			session: nil,
+		}
+
+		err := app.UpdateSessionTitle(ctx, "New Title")
+		require.Error(t, err)
+		assert.Contains(t, err.Error(), "no active session")
+	})
+
+	t.Run("returns ErrTitleGenerating when generation in progress", func(t *testing.T) {
+		t.Parallel()
+
+		rt := &mockRuntime{}
+		sess := session.New()
+		events := make(chan tea.Msg, 16)
+		app := &App{
+			runtime: rt,
+			session: sess,
+			events:  events,
+		}
+
+		// Simulate title generation in progress
+		app.titleGenerating.Store(true)
+
+		err := app.UpdateSessionTitle(ctx, "New Title")
+		require.ErrorIs(t, err, ErrTitleGenerating)
+
+		// Title should not be updated
+		assert.Empty(t, sess.Title)
+	})
+}
+
+func TestApp_RegenerateSessionTitle(t *testing.T) {
+	t.Parallel()
+
+	ctx := t.Context()
+
+	t.Run("returns error when no session", func(t *testing.T) {
+		t.Parallel()
+
+		rt := &mockRuntime{}
+		app := &App{
+			runtime: rt,
+			session: nil,
+		}
+
+		err := app.RegenerateSessionTitle(ctx)
+		require.Error(t, err)
+		assert.Contains(t, err.Error(), "no active session")
+	})
+
+	t.Run("returns error when no title generator is available", func(t *testing.T) {
+		t.Parallel()
+
+		rt := &mockRuntime{}
+		sess := session.New()
+		events := make(chan tea.Msg, 16)
+		app := &App{
+			runtime: rt,
+			session: sess,
+			events:  events,
+			// titleGen is nil - no title generator available
+		}
+
+		err := app.RegenerateSessionTitle(ctx)
+		require.Error(t, err)
+		assert.Contains(t, err.Error(), "title regeneration not available")
+	})
+
+	t.Run("returns ErrTitleGenerating when already generating", func(t *testing.T) {
+		t.Parallel()
+
+		rt := &mockRuntime{}
+		sess := session.New()
+		events := make(chan tea.Msg, 16)
+		app := &App{
+			runtime: rt,
+			session: sess,
+			events:  events,
+		}
+
+		// Simulate title generation already in progress
+		app.titleGenerating.Store(true)
+
+		err := app.RegenerateSessionTitle(ctx)
+		require.ErrorIs(t, err, ErrTitleGenerating)
+	})
+}

pkg/runtime/commands_test.go

@@ -49,6 +49,9 @@ func (m *mockRuntime) SessionStore() session.Store { return nil }
 func (m *mockRuntime) Summarize(context.Context, *session.Session, string, chan Event) {
 }
 
+func (m *mockRuntime) RegenerateTitle(context.Context, *session.Session, chan Event) {
+}
+
 func TestResolveCommand_SimpleCommand(t *testing.T) {
 	t.Parallel()
 

pkg/server/server_test.go

@@ -169,6 +169,61 @@ func unmarshal(t *testing.T, buf []byte, v any) {
 	require.NoError(t, err)
 }
 
+func TestServer_UpdateSessionTitle(t *testing.T) {
+	t.Parallel()
+
+	ctx := t.Context()
+	store := session.NewInMemorySessionStore()
+	lnPath := startServerWithStore(t, ctx, prepareAgentsDir(t), store)
+
+	// Create a session first
+	createResp := httpDo(t, ctx, http.MethodPost, lnPath, "/api/sessions", map[string]any{})
+	var createdSession session.Session
+	unmarshal(t, createResp, &createdSession)
+	require.NotEmpty(t, createdSession.ID)
+
+	// Update the session title
+	newTitle := "My Custom Title"
+	updateResp := httpDo(t, ctx, http.MethodPatch, lnPath, "/api/sessions/"+createdSession.ID+"/title", api.UpdateSessionTitleRequest{Title: newTitle})
+	var titleResp api.UpdateSessionTitleResponse
+	unmarshal(t, updateResp, &titleResp)
+
+	assert.Equal(t, createdSession.ID, titleResp.ID)
+	assert.Equal(t, newTitle, titleResp.Title)
+
+	// Verify the session was updated in the store
+	getResp := httpGET(t, ctx, lnPath, "/api/sessions/"+createdSession.ID)
+	var sessionResp api.SessionResponse
+	unmarshal(t, getResp, &sessionResp)
+
+	assert.Equal(t, newTitle, sessionResp.Title)
+}
+
+func startServerWithStore(t *testing.T, ctx context.Context, agentsDir string, store session.Store) string {
+	t.Helper()
+
+	runConfig := config.RuntimeConfig{}
+
+	sources, err := config.ResolveSources(agentsDir)
+	require.NoError(t, err)
+	srv, err := New(ctx, store, &runConfig, 0, sources)
+	require.NoError(t, err)
+
+	socketPath := "unix://" + filepath.Join(t.TempDir(), "sock")
+	ln, err := Listen(ctx, socketPath)
+	require.NoError(t, err)
+	go func() {
+		<-ctx.Done()
+		_ = ln.Close()
+	}()
+
+	go func() {
+		_ = srv.Serve(ctx, ln)
+	}()
+
+	return socketPath
+}
+
 type mockStore struct {
 	session.Store
 }

pkg/session/session_test.go

@@ -318,3 +318,79 @@ func TestUpdateLastAssistantMessageUsage_UpdatesOnlyLast(t *testing.T) {
 	assert.InEpsilon(t, 0.02, messages[2].Message.Cost, 0.0001)
 	assert.Equal(t, "new-model", messages[2].Message.Model)
 }
+
+func TestGetLastUserMessages(t *testing.T) {
+	t.Parallel()
+
+	testAgent := &agent.Agent{}
+
+	t.Run("empty session returns empty slice", func(t *testing.T) {
+		t.Parallel()
+		s := New()
+		assert.Empty(t, s.GetLastUserMessages(2))
+	})
+
+	t.Run("session with fewer messages than requested returns all", func(t *testing.T) {
+		t.Parallel()
+		s := New()
+		s.AddMessage(NewAgentMessage(testAgent, &chat.Message{
+			Role:    chat.MessageRoleUser,
+			Content: "Only message",
+		}))
+		msgs := s.GetLastUserMessages(2)
+		assert.Len(t, msgs, 1)
+		assert.Equal(t, "Only message", msgs[0])
+	})
+
+	t.Run("session returns last n user messages in order", func(t *testing.T) {
+		t.Parallel()
+		s := New()
+		s.AddMessage(NewAgentMessage(testAgent, &chat.Message{
+			Role:    chat.MessageRoleUser,
+			Content: "First",
+		}))
+		s.AddMessage(NewAgentMessage(testAgent, &chat.Message{
+			Role:    chat.MessageRoleAssistant,
+			Content: "Response 1",
+		}))
+		s.AddMessage(NewAgentMessage(testAgent, &chat.Message{
+			Role:    chat.MessageRoleUser,
+			Content: "Second",
+		}))
+		s.AddMessage(NewAgentMessage(testAgent, &chat.Message{
+			Role:    chat.MessageRoleAssistant,
+			Content: "Response 2",
+		}))
+		s.AddMessage(NewAgentMessage(testAgent, &chat.Message{
+			Role:    chat.MessageRoleUser,
+			Content: "Third",
+		}))
+
+		msgs := s.GetLastUserMessages(2)
+		assert.Len(t, msgs, 2)
+		assert.Equal(t, "Second", msgs[0]) // Ordered oldest to newest
+		assert.Equal(t, "Third", msgs[1])
+	})
+
+	t.Run("skips empty user messages", func(t *testing.T) {
+		t.Parallel()
+		s := New()
+		s.AddMessage(NewAgentMessage(testAgent, &chat.Message{
+			Role:    chat.MessageRoleUser,
+			Content: "First",
+		}))
+		s.AddMessage(NewAgentMessage(testAgent, &chat.Message{
+			Role:    chat.MessageRoleUser,
+			Content: "   ", // Empty after trim
+		}))
+		s.AddMessage(NewAgentMessage(testAgent, &chat.Message{
+			Role:    chat.MessageRoleUser,
+			Content: "Third",
+		}))
+
+		msgs := s.GetLastUserMessages(2)
+		assert.Len(t, msgs, 2)
+		assert.Equal(t, "First", msgs[0])
+		assert.Equal(t, "Third", msgs[1])
+	})
+}

pkg/sessiontitle/generator.go

@@ -17,8 +17,8 @@ import (
 )
 
 const (
-	systemPrompt     = "You are a helpful AI assistant that generates concise, descriptive titles for conversations. You will be given recent user messages and asked to create a title that captures the main topic."
-	userPromptFormat = "Based on the following recent user messages from a conversation with an AI assistant, generate a short, descriptive title (maximum 50 characters) that captures the main topic or purpose of the conversation. Return ONLY the title text, nothing else.\n\nRecent user messages:\n%s\n\n"
+	systemPrompt     = "You are a helpful AI assistant that generates concise, descriptive titles for conversations. You will be given up to 2 recent user messages and asked to create a single-line title that captures the main topic. Never use newlines or line breaks in your response."
+	userPromptFormat = "Based on the following recent user messages from a conversation with an AI assistant, generate a short, descriptive title (maximum 50 characters) that captures the main topic or purpose of the conversation. Return ONLY the title text on a single line, nothing else. Do not include any newlines, explanations, or formatting.\n\nRecent user messages:\n%s\n\n"
 )
 
 // Generator generates session titles using a one-shot LLM completion.