feat: add experimental agents support (#22290)

feat: add AI chat system with agent tools and chat UI Introduce the chatd subsystem and Agents UI for AI-powered chat within Coder workspaces. - Add chatd package with chat loop, message compaction, prompt management, and LLM provider integration (OpenAI, Anthropic) - Add agent tools: create workspace, list/read templates, read/write/ edit files, execute commands - Add chat API endpoints with streaming, message editing, and durable reconnection - Add database schema and migrations for chats, chat messages, chat providers, and chat model configs - Add RBAC policies and dbauthz enforcement for chat resources - Add Agents UI pages with conversation timeline, queued messages list, diff viewer, and model configuration panel - Add comprehensive test coverage including coderd integration tests, chatd unit tests, and Storybook stories - Gate feature behind experiments flag --------- Co-authored-by: Cian Johnston <cian@coder.com> Co-authored-by: Danielle Maywood <danielle@themaywoods.com> Co-authored-by: Jeremy Ruppel <jeremy@coder.com> Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-09-24 15:04:27 +08:00 · 2026-02-27 16:50:56 +00:00
parent 67da4e8b56
commit edee917d88
201 changed files with 44828 additions and 1859 deletions
@@ -0,0 +1,676 @@
+package chatloop
+
+import (
+	"context"
+	"database/sql"
+	"encoding/json"
+	"errors"
+	"strconv"
+	"strings"
+	"sync"
+
+	"charm.land/fantasy"
+	fantasyanthropic "charm.land/fantasy/providers/anthropic"
+	"github.com/google/uuid"
+	"golang.org/x/xerrors"
+
+	"github.com/coder/coder/v2/coderd/chatd/chatprompt"
+	"github.com/coder/coder/v2/codersdk"
+)
+
+const (
+	interruptedToolResultErrorMessage = "tool call was interrupted before it produced a result"
+)
+
+var ErrInterrupted = xerrors.New("chat interrupted")
+
+// PersistedStep contains the full content of a completed or
+// interrupted agent step. Content includes both assistant blocks
+// (text, reasoning, tool calls) and tool result blocks, mirroring
+// what fantasy provides in StepResult.Content. The persistence
+// layer is responsible for splitting these into separate database
+// messages by role.
+type PersistedStep struct {
+	Content      []fantasy.Content
+	Usage        fantasy.Usage
+	ContextLimit sql.NullInt64
+}
+
+// RunOptions configures a single streaming chat loop run.
+type RunOptions struct {
+	Model      fantasy.LanguageModel
+	Messages   []fantasy.Message
+	Tools      []fantasy.AgentTool
+	StreamCall fantasy.AgentStreamCall
+	MaxSteps   int
+
+	ActiveTools          []string
+	ContextLimitFallback int64
+
+	PersistStep        func(context.Context, PersistedStep) error
+	PublishMessagePart func(
+		role fantasy.MessageRole,
+		part codersdk.ChatMessagePart,
+	)
+	Compaction *CompactionOptions
+
+	OnInterruptedPersistError func(error)
+}
+
+// Run executes the chat step-stream loop and delegates persistence/publishing to callbacks.
+func Run(ctx context.Context, opts RunOptions) (*fantasy.AgentResult, error) {
+	if opts.Model == nil {
+		return nil, xerrors.New("chat model is required")
+	}
+	if opts.PersistStep == nil {
+		return nil, xerrors.New("persist step callback is required")
+	}
+	if opts.MaxSteps <= 0 {
+		opts.MaxSteps = 1
+	}
+
+	publishMessagePart := func(role fantasy.MessageRole, part codersdk.ChatMessagePart) {
+		if opts.PublishMessagePart == nil {
+			return
+		}
+		opts.PublishMessagePart(role, part)
+	}
+
+	var (
+		stepStateMu           sync.Mutex
+		streamToolNames       map[string]string
+		streamReasoningTitles map[string]string
+		streamReasoningText   map[string]string
+		// stepToolResultContents tracks tool results received during
+		// streaming. These are needed for the interrupted-step path
+		// where OnStepFinish never fires.
+		stepToolResultContents []fantasy.ToolResultContent
+		stepAssistantDraft     []fantasy.Content
+		stepToolCallIndexByID  map[string]int
+	)
+
+	resetStepState := func() {
+		stepStateMu.Lock()
+		streamToolNames = make(map[string]string)
+		streamReasoningTitles = make(map[string]string)
+		streamReasoningText = make(map[string]string)
+		stepToolResultContents = nil
+		stepAssistantDraft = nil
+		stepToolCallIndexByID = make(map[string]int)
+		stepStateMu.Unlock()
+	}
+
+	setReasoningTitleFromText := func(id string, text string) {
+		if id == "" || strings.TrimSpace(text) == "" {
+			return
+		}
+
+		stepStateMu.Lock()
+		defer stepStateMu.Unlock()
+
+		if streamReasoningTitles[id] != "" {
+			return
+		}
+
+		streamReasoningText[id] += text
+		if !strings.ContainsAny(streamReasoningText[id], "\r\n") {
+			return
+		}
+		title := chatprompt.ReasoningTitleFromFirstLine(streamReasoningText[id])
+		if title == "" {
+			return
+		}
+
+		streamReasoningTitles[id] = title
+	}
+
+	appendDraftText := func(text string) {
+		if text == "" {
+			return
+		}
+
+		stepStateMu.Lock()
+		defer stepStateMu.Unlock()
+
+		if len(stepAssistantDraft) > 0 {
+			lastIndex := len(stepAssistantDraft) - 1
+			switch last := stepAssistantDraft[lastIndex].(type) {
+			case fantasy.TextContent:
+				last.Text += text
+				stepAssistantDraft[lastIndex] = last
+				return
+			case *fantasy.TextContent:
+				last.Text += text
+				stepAssistantDraft[lastIndex] = fantasy.TextContent{Text: last.Text}
+				return
+			}
+		}
+		stepAssistantDraft = append(stepAssistantDraft, fantasy.TextContent{Text: text})
+	}
+
+	appendDraftReasoning := func(text string) {
+		if text == "" {
+			return
+		}
+
+		stepStateMu.Lock()
+		defer stepStateMu.Unlock()
+
+		if len(stepAssistantDraft) > 0 {
+			lastIndex := len(stepAssistantDraft) - 1
+			switch last := stepAssistantDraft[lastIndex].(type) {
+			case fantasy.ReasoningContent:
+				last.Text += text
+				stepAssistantDraft[lastIndex] = last
+				return
+			case *fantasy.ReasoningContent:
+				last.Text += text
+				stepAssistantDraft[lastIndex] = fantasy.ReasoningContent{Text: last.Text}
+				return
+			}
+		}
+		stepAssistantDraft = append(stepAssistantDraft, fantasy.ReasoningContent{Text: text})
+	}
+
+	upsertDraftToolCall := func(toolCallID, toolName, input string, appendInput bool) {
+		if toolCallID == "" {
+			return
+		}
+
+		stepStateMu.Lock()
+		defer stepStateMu.Unlock()
+
+		if strings.TrimSpace(toolName) != "" {
+			streamToolNames[toolCallID] = toolName
+		}
+
+		index, exists := stepToolCallIndexByID[toolCallID]
+		if !exists {
+			stepToolCallIndexByID[toolCallID] = len(stepAssistantDraft)
+			stepAssistantDraft = append(stepAssistantDraft, fantasy.ToolCallContent{
+				ToolCallID: toolCallID,
+				ToolName:   toolName,
+				Input:      input,
+			})
+			return
+		}
+
+		if index < 0 || index >= len(stepAssistantDraft) {
+			stepToolCallIndexByID[toolCallID] = len(stepAssistantDraft)
+			stepAssistantDraft = append(stepAssistantDraft, fantasy.ToolCallContent{
+				ToolCallID: toolCallID,
+				ToolName:   toolName,
+				Input:      input,
+			})
+			return
+		}
+
+		existingCall, ok := fantasy.AsContentType[fantasy.ToolCallContent](stepAssistantDraft[index])
+		if !ok {
+			if ptrCall, ptrOK := fantasy.AsContentType[*fantasy.ToolCallContent](stepAssistantDraft[index]); ptrOK && ptrCall != nil {
+				existingCall = *ptrCall
+				ok = true
+			}
+		}
+		if !ok {
+			stepToolCallIndexByID[toolCallID] = len(stepAssistantDraft)
+			stepAssistantDraft = append(stepAssistantDraft, fantasy.ToolCallContent{
+				ToolCallID: toolCallID,
+				ToolName:   toolName,
+				Input:      input,
+			})
+			return
+		}
+
+		if strings.TrimSpace(toolName) != "" {
+			existingCall.ToolName = toolName
+		}
+		if appendInput {
+			existingCall.Input += input
+		} else if input != "" || existingCall.Input == "" {
+			existingCall.Input = input
+		}
+		stepAssistantDraft[index] = existingCall
+	}
+
+	appendDraftSource := func(source fantasy.SourceContent) {
+		stepStateMu.Lock()
+		stepAssistantDraft = append(stepAssistantDraft, source)
+		stepStateMu.Unlock()
+	}
+
+	persistInterruptedStep := func() error {
+		stepStateMu.Lock()
+		draft := append([]fantasy.Content(nil), stepAssistantDraft...)
+		toolResults := append([]fantasy.ToolResultContent(nil), stepToolResultContents...)
+		toolNameByCallID := make(map[string]string, len(streamToolNames))
+		for id, name := range streamToolNames {
+			toolNameByCallID[id] = name
+		}
+		stepStateMu.Unlock()
+
+		if len(draft) == 0 && len(toolResults) == 0 {
+			return nil
+		}
+
+		// Track which tool calls already have results.
+		answeredToolCalls := make(map[string]struct{}, len(toolResults))
+		for _, tr := range toolResults {
+			if tr.ToolCallID != "" {
+				answeredToolCalls[tr.ToolCallID] = struct{}{}
+			}
+		}
+
+		// Build the combined content: draft + received tool results
+		// + synthetic interrupted results for unanswered tool calls.
+		content := make([]fantasy.Content, 0, len(draft)+len(toolResults))
+		content = append(content, draft...)
+		for _, tr := range toolResults {
+			content = append(content, tr)
+		}
+
+		for _, block := range draft {
+			toolCall, ok := fantasy.AsContentType[fantasy.ToolCallContent](block)
+			if !ok {
+				if ptrCall, ptrOK := fantasy.AsContentType[*fantasy.ToolCallContent](block); ptrOK && ptrCall != nil {
+					toolCall = *ptrCall
+					ok = true
+				}
+			}
+			if !ok || toolCall.ToolCallID == "" {
+				continue
+			}
+			if _, exists := answeredToolCalls[toolCall.ToolCallID]; exists {
+				continue
+			}
+
+			toolName := strings.TrimSpace(toolCall.ToolName)
+			if toolName == "" {
+				toolName = strings.TrimSpace(toolNameByCallID[toolCall.ToolCallID])
+			}
+
+			content = append(content, fantasy.ToolResultContent{
+				ToolCallID: toolCall.ToolCallID,
+				ToolName:   toolName,
+				Result: fantasy.ToolResultOutputContentError{
+					Error: xerrors.New(interruptedToolResultErrorMessage),
+				},
+			})
+			answeredToolCalls[toolCall.ToolCallID] = struct{}{}
+		}
+
+		persistCtx := context.WithoutCancel(ctx)
+		return opts.PersistStep(persistCtx, PersistedStep{
+			Content: content,
+		})
+	}
+
+	resetStepState()
+
+	agent := fantasy.NewAgent(
+		opts.Model,
+		fantasy.WithTools(opts.Tools...),
+		fantasy.WithStopConditions(fantasy.StepCountIs(opts.MaxSteps)),
+	)
+	applyAnthropicCaching := shouldApplyAnthropicPromptCaching(opts.Model)
+	// Fantasy's AgentStreamCall currently requires a non-empty Prompt and always
+	// appends it as a user message. chatd already supplies the full history in
+	// Messages, so we pass and then strip a sentinel user message in PrepareStep.
+	sentinelPrompt := "__chatd_agent_prompt_sentinel_" + uuid.NewString()
+
+	streamCall := opts.StreamCall
+	streamCall.Prompt = sentinelPrompt
+	streamCall.Messages = opts.Messages
+	streamCall.PrepareStep = func(
+		stepCtx context.Context,
+		options fantasy.PrepareStepFunctionOptions,
+	) (context.Context, fantasy.PrepareStepResult, error) {
+		return stepCtx, prepareStepResult(
+			options.Messages,
+			sentinelPrompt,
+			opts.ActiveTools,
+			applyAnthropicCaching,
+		), nil
+	}
+	streamCall.OnStepStart = func(_ int) error {
+		resetStepState()
+		return nil
+	}
+	streamCall.OnTextDelta = func(_ string, text string) error {
+		appendDraftText(text)
+		publishMessagePart(fantasy.MessageRoleAssistant, codersdk.ChatMessagePart{
+			Type: codersdk.ChatMessagePartTypeText,
+			Text: text,
+		})
+		return nil
+	}
+	streamCall.OnReasoningDelta = func(id string, text string) error {
+		appendDraftReasoning(text)
+		setReasoningTitleFromText(id, text)
+		stepStateMu.Lock()
+		title := streamReasoningTitles[id]
+		stepStateMu.Unlock()
+		publishMessagePart(fantasy.MessageRoleAssistant, codersdk.ChatMessagePart{
+			Type:  codersdk.ChatMessagePartTypeReasoning,
+			Text:  text,
+			Title: title,
+		})
+		return nil
+	}
+	streamCall.OnReasoningEnd = func(id string, _ fantasy.ReasoningContent) error {
+		stepStateMu.Lock()
+		if streamReasoningTitles[id] == "" {
+			// At the end of reasoning we have the full text, so we can
+			// safely evaluate first-line title format even if no newline
+			// ever arrived in deltas.
+			streamReasoningTitles[id] = chatprompt.ReasoningTitleFromFirstLine(
+				streamReasoningText[id],
+			)
+		}
+		title := streamReasoningTitles[id]
+		stepStateMu.Unlock()
+		if title != "" {
+			// Publish a title-only reasoning part so clients can update the
+			// reasoning header when metadata arrives at the end of streaming.
+			publishMessagePart(fantasy.MessageRoleAssistant, codersdk.ChatMessagePart{
+				Type:  codersdk.ChatMessagePartTypeReasoning,
+				Title: title,
+			})
+		}
+		return nil
+	}
+	streamCall.OnToolInputStart = func(id, toolName string) error {
+		upsertDraftToolCall(id, toolName, "", false)
+		return nil
+	}
+	streamCall.OnToolInputDelta = func(id, delta string) error {
+		stepStateMu.Lock()
+		toolName := streamToolNames[id]
+		stepStateMu.Unlock()
+		upsertDraftToolCall(id, toolName, delta, true)
+		publishMessagePart(fantasy.MessageRoleAssistant, codersdk.ChatMessagePart{
+			Type:       codersdk.ChatMessagePartTypeToolCall,
+			ToolCallID: id,
+			ToolName:   toolName,
+			ArgsDelta:  delta,
+		})
+		return nil
+	}
+	streamCall.OnToolCall = func(toolCall fantasy.ToolCallContent) error {
+		upsertDraftToolCall(toolCall.ToolCallID, toolCall.ToolName, toolCall.Input, false)
+		publishMessagePart(
+			fantasy.MessageRoleAssistant,
+			chatprompt.PartFromContent(toolCall),
+		)
+		return nil
+	}
+	streamCall.OnSource = func(source fantasy.SourceContent) error {
+		appendDraftSource(source)
+		publishMessagePart(
+			fantasy.MessageRoleAssistant,
+			chatprompt.PartFromContent(source),
+		)
+		return nil
+	}
+	streamCall.OnToolResult = func(result fantasy.ToolResultContent) error {
+		publishMessagePart(
+			fantasy.MessageRoleTool,
+			chatprompt.PartFromContent(result),
+		)
+
+		stepStateMu.Lock()
+		if result.ToolCallID != "" && strings.TrimSpace(result.ToolName) != "" {
+			streamToolNames[result.ToolCallID] = result.ToolName
+		}
+		stepToolResultContents = append(stepToolResultContents, result)
+		stepStateMu.Unlock()
+
+		return nil
+	}
+	streamCall.OnStepFinish = func(stepResult fantasy.StepResult) error {
+		contextLimit := extractContextLimit(stepResult.ProviderMetadata)
+		if !contextLimit.Valid && opts.ContextLimitFallback > 0 {
+			contextLimit = sql.NullInt64{
+				Int64: opts.ContextLimitFallback,
+				Valid: true,
+			}
+		}
+
+		return opts.PersistStep(ctx, PersistedStep{
+			Content:      stepResult.Content,
+			Usage:        stepResult.Usage,
+			ContextLimit: contextLimit,
+		})
+	}
+
+	result, err := agent.Stream(ctx, streamCall)
+	if err != nil {
+		if errors.Is(err, context.Canceled) &&
+			errors.Is(context.Cause(ctx), ErrInterrupted) {
+			if persistErr := persistInterruptedStep(); persistErr != nil {
+				if opts.OnInterruptedPersistError != nil {
+					opts.OnInterruptedPersistError(persistErr)
+				}
+			}
+			return nil, ErrInterrupted
+		}
+		return nil, xerrors.Errorf("stream response: %w", err)
+	}
+	if opts.Compaction != nil {
+		if err := maybeCompact(ctx, opts, result); err != nil {
+			if opts.Compaction.OnError != nil {
+				opts.Compaction.OnError(err)
+			}
+		}
+	}
+
+	return result, nil
+}
+
+//nolint:revive // Boolean controls Anthropic-specific caching behavior.
+func prepareStepResult(
+	messages []fantasy.Message,
+	sentinel string,
+	activeTools []string,
+	anthropicCaching bool,
+) fantasy.PrepareStepResult {
+	filtered := make([]fantasy.Message, 0, len(messages))
+	removed := false
+	for _, message := range messages {
+		if !removed &&
+			message.Role == fantasy.MessageRoleUser &&
+			len(message.Content) == 1 {
+			textPart, ok := fantasy.AsMessagePart[fantasy.TextPart](message.Content[0])
+			if ok && textPart.Text == sentinel {
+				removed = true
+				continue
+			}
+		}
+		filtered = append(filtered, message)
+	}
+
+	result := fantasy.PrepareStepResult{
+		Messages: filtered,
+	}
+	if anthropicCaching {
+		result.Messages = addAnthropicPromptCaching(result.Messages)
+	}
+	if len(activeTools) > 0 {
+		result.ActiveTools = append([]string(nil), activeTools...)
+	}
+	return result
+}
+
+func shouldApplyAnthropicPromptCaching(model fantasy.LanguageModel) bool {
+	if model == nil {
+		return false
+	}
+	return model.Provider() == fantasyanthropic.Name
+}
+
+func addAnthropicPromptCaching(messages []fantasy.Message) []fantasy.Message {
+	for i := range messages {
+		messages[i].ProviderOptions = nil
+	}
+
+	providerOption := fantasy.ProviderOptions{
+		fantasyanthropic.Name: &fantasyanthropic.ProviderCacheControlOptions{
+			CacheControl: fantasyanthropic.CacheControl{Type: "ephemeral"},
+		},
+	}
+
+	lastSystemRoleIdx := -1
+	systemMessageUpdated := false
+	for i, msg := range messages {
+		if msg.Role == fantasy.MessageRoleSystem {
+			lastSystemRoleIdx = i
+		} else if !systemMessageUpdated && lastSystemRoleIdx >= 0 {
+			messages[lastSystemRoleIdx].ProviderOptions = providerOption
+			systemMessageUpdated = true
+		}
+		if i > len(messages)-3 {
+			messages[i].ProviderOptions = providerOption
+		}
+	}
+
+	return messages
+}
+
+func extractContextLimit(metadata fantasy.ProviderMetadata) sql.NullInt64 {
+	if len(metadata) == 0 {
+		return sql.NullInt64{}
+	}
+
+	encoded, err := json.Marshal(metadata)
+	if err != nil || len(encoded) == 0 {
+		return sql.NullInt64{}
+	}
+
+	var payload any
+	if err := json.Unmarshal(encoded, &payload); err != nil {
+		return sql.NullInt64{}
+	}
+
+	limit, ok := findContextLimitValue(payload)
+	if !ok {
+		return sql.NullInt64{}
+	}
+
+	return sql.NullInt64{
+		Int64: limit,
+		Valid: true,
+	}
+}
+
+func findContextLimitValue(value any) (int64, bool) {
+	var (
+		limit int64
+		found bool
+	)
+
+	collectContextLimitValues(value, func(candidate int64) {
+		if !found || candidate > limit {
+			limit = candidate
+			found = true
+		}
+	})
+
+	return limit, found
+}
+
+func collectContextLimitValues(value any, onValue func(int64)) {
+	switch typed := value.(type) {
+	case map[string]any:
+		for key, child := range typed {
+			if isContextLimitKey(key) {
+				if numeric, ok := numericContextLimitValue(child); ok {
+					onValue(numeric)
+				}
+			}
+			collectContextLimitValues(child, onValue)
+		}
+	case []any:
+		for _, child := range typed {
+			collectContextLimitValues(child, onValue)
+		}
+	}
+}
+
+func isContextLimitKey(key string) bool {
+	normalized := normalizeMetadataKey(key)
+	if normalized == "" {
+		return false
+	}
+
+	switch normalized {
+	case
+		"contextlimit",
+		"contextwindow",
+		"contextlength",
+		"maxcontext",
+		"maxcontexttokens",
+		"maxinputtokens",
+		"maxinputtoken",
+		"inputtokenlimit":
+		return true
+	}
+
+	return strings.Contains(normalized, "context") &&
+		(strings.Contains(normalized, "limit") ||
+			strings.Contains(normalized, "window") ||
+			strings.Contains(normalized, "length") ||
+			strings.HasPrefix(normalized, "max"))
+}
+
+func normalizeMetadataKey(key string) string {
+	var b strings.Builder
+	b.Grow(len(key))
+
+	for _, r := range key {
+		switch {
+		case r >= 'a' && r <= 'z':
+			_, _ = b.WriteRune(r)
+		case r >= 'A' && r <= 'Z':
+			_, _ = b.WriteRune(r + ('a' - 'A'))
+		case r >= '0' && r <= '9':
+			_, _ = b.WriteRune(r)
+		}
+	}
+
+	return b.String()
+}
+
+func numericContextLimitValue(value any) (int64, bool) {
+	switch typed := value.(type) {
+	case int64:
+		return positiveInt64(typed)
+	case int32:
+		return positiveInt64(int64(typed))
+	case int:
+		return positiveInt64(int64(typed))
+	case float64:
+		casted := int64(typed)
+		if typed > 0 && float64(casted) == typed {
+			return casted, true
+		}
+	case string:
+		parsed, err := strconv.ParseInt(strings.TrimSpace(typed), 10, 64)
+		if err == nil {
+			return positiveInt64(parsed)
+		}
+	case json.Number:
+		parsed, err := typed.Int64()
+		if err == nil {
+			return positiveInt64(parsed)
+		}
+	}
+
+	return 0, false
+}
+
+func positiveInt64(value int64) (int64, bool) {
+	if value <= 0 {
+		return 0, false
+	}
+	return value, true
+}
@@ -0,0 +1,289 @@
+package chatloop //nolint:testpackage // Uses internal symbols.
+
+import (
+	"context"
+	"iter"
+	"strings"
+	"testing"
+
+	"charm.land/fantasy"
+	fantasyanthropic "charm.land/fantasy/providers/anthropic"
+	"github.com/stretchr/testify/require"
+	"golang.org/x/xerrors"
+)
+
+const activeToolName = "read_file"
+
+func TestRun_ActiveToolsPrepareBehavior(t *testing.T) {
+	t.Parallel()
+
+	var capturedCall fantasy.Call
+	model := &loopTestModel{
+		provider: fantasyanthropic.Name,
+		streamFn: func(_ context.Context, call fantasy.Call) (fantasy.StreamResponse, error) {
+			capturedCall = call
+			return streamFromParts([]fantasy.StreamPart{
+				{Type: fantasy.StreamPartTypeTextStart, ID: "text-1"},
+				{Type: fantasy.StreamPartTypeTextDelta, ID: "text-1", Delta: "done"},
+				{Type: fantasy.StreamPartTypeTextEnd, ID: "text-1"},
+				{Type: fantasy.StreamPartTypeFinish, FinishReason: fantasy.FinishReasonStop},
+			}), nil
+		},
+	}
+
+	persistStepCalls := 0
+	var persistedStep PersistedStep
+
+	_, err := Run(context.Background(), RunOptions{
+		Model: model,
+		Messages: []fantasy.Message{
+			textMessage(fantasy.MessageRoleSystem, "sys-1"),
+			textMessage(fantasy.MessageRoleSystem, "sys-2"),
+			textMessage(fantasy.MessageRoleUser, "hello"),
+			textMessage(fantasy.MessageRoleAssistant, "working"),
+			textMessage(fantasy.MessageRoleUser, "continue"),
+		},
+		Tools: []fantasy.AgentTool{
+			newNoopTool(activeToolName),
+			newNoopTool("write_file"),
+		},
+		MaxSteps:             3,
+		ActiveTools:          []string{activeToolName},
+		ContextLimitFallback: 4096,
+		PersistStep: func(_ context.Context, step PersistedStep) error {
+			persistStepCalls++
+			persistedStep = step
+			return nil
+		},
+	})
+	require.NoError(t, err)
+
+	require.Equal(t, 1, persistStepCalls)
+	require.True(t, persistedStep.ContextLimit.Valid)
+	require.Equal(t, int64(4096), persistedStep.ContextLimit.Int64)
+
+	require.NotEmpty(t, capturedCall.Prompt)
+	require.False(t, containsPromptSentinel(capturedCall.Prompt))
+	require.Len(t, capturedCall.Tools, 1)
+	require.Equal(t, activeToolName, capturedCall.Tools[0].GetName())
+
+	require.Len(t, capturedCall.Prompt, 5)
+	require.False(t, hasAnthropicEphemeralCacheControl(capturedCall.Prompt[0]))
+	require.True(t, hasAnthropicEphemeralCacheControl(capturedCall.Prompt[1]))
+	require.False(t, hasAnthropicEphemeralCacheControl(capturedCall.Prompt[2]))
+	require.True(t, hasAnthropicEphemeralCacheControl(capturedCall.Prompt[3]))
+	require.True(t, hasAnthropicEphemeralCacheControl(capturedCall.Prompt[4]))
+}
+
+func TestRun_InterruptedStepPersistsSyntheticToolResult(t *testing.T) {
+	t.Parallel()
+
+	started := make(chan struct{})
+	model := &loopTestModel{
+		provider: "fake",
+		streamFn: func(ctx context.Context, _ fantasy.Call) (fantasy.StreamResponse, error) {
+			return iter.Seq[fantasy.StreamPart](func(yield func(fantasy.StreamPart) bool) {
+				parts := []fantasy.StreamPart{
+					{
+						Type:         fantasy.StreamPartTypeToolInputStart,
+						ID:           "interrupt-tool-1",
+						ToolCallName: "read_file",
+					},
+					{
+						Type:         fantasy.StreamPartTypeToolInputDelta,
+						ID:           "interrupt-tool-1",
+						ToolCallName: "read_file",
+						Delta:        `{"path":"main.go"`,
+					},
+					{Type: fantasy.StreamPartTypeTextStart, ID: "text-1"},
+					{Type: fantasy.StreamPartTypeTextDelta, ID: "text-1", Delta: "partial assistant output"},
+				}
+				for _, part := range parts {
+					if !yield(part) {
+						return
+					}
+				}
+
+				select {
+				case <-started:
+				default:
+					close(started)
+				}
+
+				<-ctx.Done()
+				_ = yield(fantasy.StreamPart{
+					Type:  fantasy.StreamPartTypeError,
+					Error: ctx.Err(),
+				})
+			}), nil
+		},
+	}
+
+	ctx, cancel := context.WithCancelCause(context.Background())
+	defer cancel(nil)
+
+	go func() {
+		<-started
+		cancel(ErrInterrupted)
+	}()
+
+	persistedAssistantCtxErr := xerrors.New("unset")
+	var persistedContent []fantasy.Content
+
+	_, err := Run(ctx, RunOptions{
+		Model: model,
+		Messages: []fantasy.Message{
+			textMessage(fantasy.MessageRoleUser, "hello"),
+		},
+		Tools: []fantasy.AgentTool{
+			newNoopTool("read_file"),
+		},
+		MaxSteps: 3,
+		PersistStep: func(persistCtx context.Context, step PersistedStep) error {
+			persistedAssistantCtxErr = persistCtx.Err()
+			persistedContent = append([]fantasy.Content(nil), step.Content...)
+			return nil
+		},
+	})
+	require.ErrorIs(t, err, ErrInterrupted)
+	require.NoError(t, persistedAssistantCtxErr)
+
+	require.NotEmpty(t, persistedContent)
+	var (
+		foundText       bool
+		foundToolCall   bool
+		foundToolResult bool
+	)
+	for _, block := range persistedContent {
+		if text, ok := fantasy.AsContentType[fantasy.TextContent](block); ok {
+			if strings.Contains(text.Text, "partial assistant output") {
+				foundText = true
+			}
+			continue
+		}
+		if toolCall, ok := fantasy.AsContentType[fantasy.ToolCallContent](block); ok {
+			if toolCall.ToolCallID == "interrupt-tool-1" &&
+				toolCall.ToolName == "read_file" &&
+				strings.Contains(toolCall.Input, `"path":"main.go"`) {
+				foundToolCall = true
+			}
+			continue
+		}
+		if toolResult, ok := fantasy.AsContentType[fantasy.ToolResultContent](block); ok {
+			if toolResult.ToolCallID == "interrupt-tool-1" &&
+				toolResult.ToolName == "read_file" {
+				_, isErr := toolResult.Result.(fantasy.ToolResultOutputContentError)
+				require.True(t, isErr, "interrupted tool result should be an error")
+				foundToolResult = true
+			}
+		}
+	}
+	require.True(t, foundText)
+	require.True(t, foundToolCall)
+	require.True(t, foundToolResult)
+}
+
+type loopTestModel struct {
+	provider   string
+	model      string
+	generateFn func(context.Context, fantasy.Call) (*fantasy.Response, error)
+	streamFn   func(context.Context, fantasy.Call) (fantasy.StreamResponse, error)
+}
+
+func (m *loopTestModel) Provider() string {
+	if m.provider != "" {
+		return m.provider
+	}
+	return "fake"
+}
+
+func (m *loopTestModel) Model() string {
+	if m.model != "" {
+		return m.model
+	}
+	return "fake"
+}
+
+func (m *loopTestModel) Generate(ctx context.Context, call fantasy.Call) (*fantasy.Response, error) {
+	if m.generateFn != nil {
+		return m.generateFn(ctx, call)
+	}
+	return &fantasy.Response{}, nil
+}
+
+func (m *loopTestModel) Stream(ctx context.Context, call fantasy.Call) (fantasy.StreamResponse, error) {
+	if m.streamFn != nil {
+		return m.streamFn(ctx, call)
+	}
+	return streamFromParts([]fantasy.StreamPart{{
+		Type:         fantasy.StreamPartTypeFinish,
+		FinishReason: fantasy.FinishReasonStop,
+	}}), nil
+}
+
+func (*loopTestModel) GenerateObject(context.Context, fantasy.ObjectCall) (*fantasy.ObjectResponse, error) {
+	return nil, xerrors.New("not implemented")
+}
+
+func (*loopTestModel) StreamObject(context.Context, fantasy.ObjectCall) (fantasy.ObjectStreamResponse, error) {
+	return nil, xerrors.New("not implemented")
+}
+
+func streamFromParts(parts []fantasy.StreamPart) fantasy.StreamResponse {
+	return iter.Seq[fantasy.StreamPart](func(yield func(fantasy.StreamPart) bool) {
+		for _, part := range parts {
+			if !yield(part) {
+				return
+			}
+		}
+	})
+}
+
+func newNoopTool(name string) fantasy.AgentTool {
+	return fantasy.NewAgentTool(
+		name,
+		"test noop tool",
+		func(context.Context, struct{}, fantasy.ToolCall) (fantasy.ToolResponse, error) {
+			return fantasy.ToolResponse{}, nil
+		},
+	)
+}
+
+func textMessage(role fantasy.MessageRole, text string) fantasy.Message {
+	return fantasy.Message{
+		Role: role,
+		Content: []fantasy.MessagePart{
+			fantasy.TextPart{Text: text},
+		},
+	}
+}
+
+func containsPromptSentinel(prompt []fantasy.Message) bool {
+	for _, message := range prompt {
+		if message.Role != fantasy.MessageRoleUser || len(message.Content) != 1 {
+			continue
+		}
+		textPart, ok := fantasy.AsMessagePart[fantasy.TextPart](message.Content[0])
+		if !ok {
+			continue
+		}
+		if strings.HasPrefix(textPart.Text, "__chatd_agent_prompt_sentinel_") {
+			return true
+		}
+	}
+	return false
+}
+
+func hasAnthropicEphemeralCacheControl(message fantasy.Message) bool {
+	if len(message.ProviderOptions) == 0 {
+		return false
+	}
+
+	options, ok := message.ProviderOptions[fantasyanthropic.Name]
+	if !ok {
+		return false
+	}
+
+	cacheOptions, ok := options.(*fantasyanthropic.ProviderCacheControlOptions)
+	return ok && cacheOptions.CacheControl.Type == "ephemeral"
+}
@@ -0,0 +1,209 @@
+package chatloop
+
+import (
+	"context"
+	"strings"
+	"time"
+
+	"charm.land/fantasy"
+	"golang.org/x/xerrors"
+)
+
+const (
+	defaultCompactionThresholdPercent = int32(70)
+	minCompactionThresholdPercent     = int32(0)
+	maxCompactionThresholdPercent     = int32(100)
+
+	defaultCompactionSummaryPrompt = "Summarize the current chat so a " +
+		"new assistant can continue seamlessly. Include the user's goals, " +
+		"decisions made, concrete technical details (files, commands, APIs), " +
+		"errors encountered and fixes, and open questions. Be dense and factual. " +
+		"Omit pleasantries and next-step suggestions."
+	defaultCompactionSystemSummaryPrefix = "Summary of earlier chat context:"
+	defaultCompactionTimeout             = 90 * time.Second
+)
+
+type CompactionOptions struct {
+	ThresholdPercent    int32
+	ContextLimit        int64
+	SummaryPrompt       string
+	SystemSummaryPrefix string
+	Timeout             time.Duration
+	Persist             func(context.Context, CompactionResult) error
+	OnError             func(error)
+}
+
+type CompactionResult struct {
+	SystemSummary    string
+	SummaryReport    string
+	ThresholdPercent int32
+	UsagePercent     float64
+	ContextTokens    int64
+	ContextLimit     int64
+}
+
+func maybeCompact(
+	ctx context.Context,
+	runOpts RunOptions,
+	runResult *fantasy.AgentResult,
+) error {
+	if runResult == nil || runOpts.Compaction == nil {
+		return nil
+	}
+
+	config := *runOpts.Compaction
+	if config.Persist == nil {
+		return xerrors.New("compaction persist callback is required")
+	}
+	if strings.TrimSpace(config.SummaryPrompt) == "" {
+		config.SummaryPrompt = defaultCompactionSummaryPrompt
+	}
+	if strings.TrimSpace(config.SystemSummaryPrefix) == "" {
+		config.SystemSummaryPrefix = defaultCompactionSystemSummaryPrefix
+	}
+	if config.Timeout <= 0 {
+		config.Timeout = defaultCompactionTimeout
+	}
+	if config.ThresholdPercent < minCompactionThresholdPercent ||
+		config.ThresholdPercent > maxCompactionThresholdPercent {
+		config.ThresholdPercent = defaultCompactionThresholdPercent
+	}
+
+	if config.ThresholdPercent >= maxCompactionThresholdPercent {
+		return nil
+	}
+	if runOpts.MaxSteps > 0 && len(runResult.Steps) >= runOpts.MaxSteps {
+		lastStep := runResult.Steps[len(runResult.Steps)-1]
+		if lastStep.FinishReason == fantasy.FinishReasonToolCalls &&
+			len(lastStep.Content.ToolCalls()) > 0 {
+			return nil
+		}
+	}
+
+	contextTokens := int64(0)
+	contextLimitFromMetadata := int64(0)
+	for i := len(runResult.Steps) - 1; i >= 0; i-- {
+		usage := runResult.Steps[i].Usage
+		total := int64(0)
+		hasContextTokens := false
+
+		if usage.InputTokens > 0 {
+			total += usage.InputTokens
+			hasContextTokens = true
+		}
+		if usage.CacheReadTokens > 0 {
+			total += usage.CacheReadTokens
+			hasContextTokens = true
+		}
+		if usage.CacheCreationTokens > 0 {
+			total += usage.CacheCreationTokens
+			hasContextTokens = true
+		}
+		if !hasContextTokens && usage.TotalTokens > 0 {
+			total = usage.TotalTokens
+			hasContextTokens = true
+		}
+		if !hasContextTokens || total <= 0 {
+			continue
+		}
+
+		contextTokens = total
+		metadataLimit := extractContextLimit(runResult.Steps[i].ProviderMetadata)
+		if metadataLimit.Valid && metadataLimit.Int64 > 0 {
+			contextLimitFromMetadata = metadataLimit.Int64
+		}
+		break
+	}
+	if contextTokens <= 0 {
+		return nil
+	}
+
+	contextLimit := contextLimitFromMetadata
+	if contextLimit <= 0 && config.ContextLimit > 0 {
+		contextLimit = config.ContextLimit
+	}
+	if contextLimit <= 0 && runOpts.ContextLimitFallback > 0 {
+		contextLimit = runOpts.ContextLimitFallback
+	}
+	if contextLimit <= 0 {
+		return nil
+	}
+
+	usagePercent := (float64(contextTokens) / float64(contextLimit)) * 100
+	if usagePercent < float64(config.ThresholdPercent) {
+		return nil
+	}
+
+	summary, err := generateCompactionSummary(
+		ctx,
+		runOpts.Model,
+		runOpts.Messages,
+		runResult.Steps,
+		config,
+	)
+	if err != nil {
+		return err
+	}
+	if summary == "" {
+		return nil
+	}
+
+	systemSummary := strings.TrimSpace(
+		config.SystemSummaryPrefix + "\n\n" + summary,
+	)
+
+	return config.Persist(ctx, CompactionResult{
+		SystemSummary:    systemSummary,
+		SummaryReport:    summary,
+		ThresholdPercent: config.ThresholdPercent,
+		UsagePercent:     usagePercent,
+		ContextTokens:    contextTokens,
+		ContextLimit:     contextLimit,
+	})
+}
+
+func generateCompactionSummary(
+	ctx context.Context,
+	model fantasy.LanguageModel,
+	messages []fantasy.Message,
+	steps []fantasy.StepResult,
+	options CompactionOptions,
+) (string, error) {
+	summaryPrompt := make([]fantasy.Message, 0, len(messages)+len(steps)+1)
+	summaryPrompt = append(summaryPrompt, messages...)
+	for _, step := range steps {
+		summaryPrompt = append(summaryPrompt, step.Messages...)
+	}
+	summaryPrompt = append(summaryPrompt, fantasy.Message{
+		Role: fantasy.MessageRoleUser,
+		Content: []fantasy.MessagePart{
+			fantasy.TextPart{Text: options.SummaryPrompt},
+		},
+	})
+	toolChoice := fantasy.ToolChoiceNone
+
+	summaryCtx, cancel := context.WithTimeout(ctx, options.Timeout)
+	defer cancel()
+
+	response, err := model.Generate(summaryCtx, fantasy.Call{
+		Prompt:     summaryPrompt,
+		ToolChoice: &toolChoice,
+	})
+	if err != nil {
+		return "", xerrors.Errorf("generate summary text: %w", err)
+	}
+
+	parts := make([]string, 0, len(response.Content))
+	for _, block := range response.Content {
+		textBlock, ok := fantasy.AsContentType[fantasy.TextContent](block)
+		if !ok {
+			continue
+		}
+		text := strings.TrimSpace(textBlock.Text)
+		if text == "" {
+			continue
+		}
+		parts = append(parts, text)
+	}
+	return strings.TrimSpace(strings.Join(parts, " ")), nil
+}
@@ -0,0 +1,132 @@
+package chatloop //nolint:testpackage // Uses internal symbols.
+
+import (
+	"context"
+	"testing"
+
+	"charm.land/fantasy"
+	"github.com/stretchr/testify/require"
+	"golang.org/x/xerrors"
+)
+
+func TestRun_Compaction(t *testing.T) {
+	t.Parallel()
+
+	t.Run("PersistsWhenThresholdReached", func(t *testing.T) {
+		t.Parallel()
+
+		persistCompactionCalls := 0
+		var persistedCompaction CompactionResult
+		const summaryText = "summary text for compaction"
+
+		model := &loopTestModel{
+			provider: "fake",
+			streamFn: func(_ context.Context, _ fantasy.Call) (fantasy.StreamResponse, error) {
+				return streamFromParts([]fantasy.StreamPart{
+					{Type: fantasy.StreamPartTypeTextStart, ID: "text-1"},
+					{Type: fantasy.StreamPartTypeTextDelta, ID: "text-1", Delta: "done"},
+					{Type: fantasy.StreamPartTypeTextEnd, ID: "text-1"},
+					{
+						Type:         fantasy.StreamPartTypeFinish,
+						FinishReason: fantasy.FinishReasonStop,
+						Usage: fantasy.Usage{
+							InputTokens: 80,
+							TotalTokens: 85,
+						},
+					},
+				}), nil
+			},
+			generateFn: func(_ context.Context, call fantasy.Call) (*fantasy.Response, error) {
+				require.NotEmpty(t, call.Prompt)
+				lastPrompt := call.Prompt[len(call.Prompt)-1]
+				require.Equal(t, fantasy.MessageRoleUser, lastPrompt.Role)
+				require.Len(t, lastPrompt.Content, 1)
+
+				instruction, ok := fantasy.AsMessagePart[fantasy.TextPart](lastPrompt.Content[0])
+				require.True(t, ok)
+				require.Equal(t, "summarize now", instruction.Text)
+
+				return &fantasy.Response{
+					Content: []fantasy.Content{
+						fantasy.TextContent{Text: summaryText},
+					},
+				}, nil
+			},
+		}
+
+		_, err := Run(context.Background(), RunOptions{
+			Model: model,
+			Messages: []fantasy.Message{
+				textMessage(fantasy.MessageRoleUser, "hello"),
+			},
+			MaxSteps: 1,
+			PersistStep: func(_ context.Context, _ PersistedStep) error {
+				return nil
+			},
+			ContextLimitFallback: 100,
+			Compaction: &CompactionOptions{
+				ThresholdPercent: 70,
+				SummaryPrompt:    "summarize now",
+				Persist: func(_ context.Context, result CompactionResult) error {
+					persistCompactionCalls++
+					persistedCompaction = result
+					return nil
+				},
+			},
+		})
+		require.NoError(t, err)
+		require.Equal(t, 1, persistCompactionCalls)
+		require.Contains(t, persistedCompaction.SystemSummary, summaryText)
+		require.Equal(t, summaryText, persistedCompaction.SummaryReport)
+		require.Equal(t, int64(80), persistedCompaction.ContextTokens)
+		require.Equal(t, int64(100), persistedCompaction.ContextLimit)
+		require.InDelta(t, 80.0, persistedCompaction.UsagePercent, 0.0001)
+	})
+
+	t.Run("ErrorsAreReported", func(t *testing.T) {
+		t.Parallel()
+
+		model := &loopTestModel{
+			provider: "fake",
+			streamFn: func(_ context.Context, _ fantasy.Call) (fantasy.StreamResponse, error) {
+				return streamFromParts([]fantasy.StreamPart{
+					{
+						Type:         fantasy.StreamPartTypeFinish,
+						FinishReason: fantasy.FinishReasonStop,
+						Usage: fantasy.Usage{
+							InputTokens: 80,
+						},
+					},
+				}), nil
+			},
+			generateFn: func(_ context.Context, _ fantasy.Call) (*fantasy.Response, error) {
+				return nil, xerrors.New("generate failed")
+			},
+		}
+
+		compactionErr := xerrors.New("unset")
+		_, err := Run(context.Background(), RunOptions{
+			Model: model,
+			Messages: []fantasy.Message{
+				textMessage(fantasy.MessageRoleUser, "hello"),
+			},
+			MaxSteps: 1,
+			PersistStep: func(_ context.Context, _ PersistedStep) error {
+				return nil
+			},
+			ContextLimitFallback: 100,
+			Compaction: &CompactionOptions{
+				ThresholdPercent: 70,
+				Persist: func(_ context.Context, _ CompactionResult) error {
+					return nil
+				},
+				OnError: func(err error) {
+					compactionErr = err
+				},
+			},
+		})
+		require.NoError(t, err)
+		require.Error(t, compactionErr)
+		require.ErrorContains(t, compactionErr, "generate summary text")
+	})
+}