feat(compaction): auto-compact and retry on context overflow errors

README.md

@@ -210,7 +210,7 @@ mcpServers:
 --max-steps              Maximum agent steps (0 for unlimited)
 --stream                 Enable streaming output (default: true)
 --compact                Enable compact output mode
---auto-compact           Auto-compact conversation near context limit
+--auto-compact           Auto-compact conversation near context limit (reactive compact-and-retry on provider context-overflow errors is always on)
 
 # Extensions and tools
 --extension, -e          Load additional extension file(s) (repeatable)
@@ -718,8 +718,10 @@ host, err := kit.New(ctx, &kit.Options{
     // Configuration
     SkipConfig:   true,                   // Skip .kit.yml files (viper defaults + env vars still apply)
 
-    // Compaction
-    AutoCompact:  true,                // Auto-compact near context limit
+    // Compaction — proactive check before turns near the context limit.
+    // Reactive compaction (compact + replay once on provider context-overflow
+    // errors) is always on, independent of this setting.
+    AutoCompact:  true,
 
     Debug:        true,                // Debug logging
 })

pkg/kit/README.md

@@ -107,8 +107,10 @@ host, err := kit.New(ctx, &kit.Options{
     // Configuration
     SkipConfig:   true,                        // Skip .kit.yml files (viper defaults + env vars still apply)
 
-    // Compaction
-    AutoCompact:  true,                       // Auto-compact near context limit
+    // Compaction — proactive check before turns near the context limit.
+    // Reactive compact-and-replay on provider context-overflow errors is
+    // always on, independent of this setting.
+    AutoCompact:  true,
 
     // In-process MCP servers (map name → *kit.MCPServer)
     InProcessMCPServers: map[string]*kit.MCPServer{
@@ -374,7 +376,9 @@ msg  := kit.ConvertFromLLMMessage(lMsg)  // LLMMessage  → SDK Message
   agent loop and surface a typed result
 - Provider-error sentinels - `ErrContextOverflow`, `ErrRateLimit`, `ErrAuth`,
   `ErrProviderUnavailable`, `ErrInvalidRequest`; classify with
-  `ClassifyProviderError(err)` and match via `errors.Is`
+  `ClassifyProviderError(err)` and match via `errors.Is`. `ErrContextOverflow`
+  is surfaced only after the turn loop's automatic compact-and-replay
+  recovery also failed
 
 ### Key Methods
 

pkg/kit/errors.go

@@ -11,7 +11,10 @@ import (
 // arbitrary provider error to one of these sentinels.
 var (
 	// ErrContextOverflow indicates the request exceeded the model's maximum
-	// context window. Embedders typically respond by compacting and retrying.
+	// context window. Kit's turn loop recovers from this automatically:
+	// it compacts the conversation and replays the turn once before
+	// surfacing the error. When this error still reaches the caller,
+	// compaction was impossible or insufficient.
 	ErrContextOverflow = errors.New("context window exceeded")
 
 	// ErrRateLimit indicates the provider throttled the request. Embedders

pkg/kit/kit.go

@@ -1227,7 +1227,11 @@ type Options struct {
 	InProcessMCPServers map[string]*MCPServer
 
 	// Compaction
-	AutoCompact       bool               // Auto-compact when near context limit
+	// AutoCompact enables proactive compaction before turns that near the
+	// context limit. Independent of this setting, the turn loop always
+	// compacts reactively and replays the turn once when a provider call
+	// fails with a context-overflow error.
+	AutoCompact       bool
 	CompactionOptions *CompactionOptions // Config for auto-compaction (nil = defaults)
 
 	// Debug enables debug logging for the SDK. When DebugLogger is nil this
@@ -2774,6 +2778,23 @@ func (m *Kit) generate(ctx context.Context, messages []fantasy.Message) (*agent.
 	})
 }
 
+// persistGenerationRemainder persists messages produced by generation that
+// were not already persisted incrementally by the onStepMessages callback.
+// sentCount is the number of input messages sent to the LLM (the prefix of
+// result.ConversationMessages to skip). Safe to call with a nil result.
+func (m *Kit) persistGenerationRemainder(result *agent.GenerateWithLoopResult, sentCount int) {
+	if result == nil || len(result.ConversationMessages) <= sentCount {
+		return
+	}
+	newMessages := result.ConversationMessages[sentCount:]
+	if result.PersistedMessageCount >= len(newMessages) {
+		return
+	}
+	for _, msg := range newMessages[result.PersistedMessageCount:] {
+		_, _ = m.session.AppendMessage(msg)
+	}
+}
+
 // runTurn is the shared lifecycle for every prompt mode:
 //  1. Run BeforeTurn hooks (can modify prompt, inject messages).
 //  2. Persist pre-generation messages to the tree session.
@@ -2866,21 +2887,45 @@ func (m *Kit) runTurn(ctx context.Context, promptLabel string, prompt string, pr
 	m.events.emit(MessageStartEvent{})
 
 	result, err := m.generate(ctx, messages)
+
+	// Reactive compaction (issue #85): when the provider rejected the
+	// request because the context window was exceeded, compact the
+	// conversation and replay the turn once instead of failing. This is the
+	// safety net for token-estimate drift and huge mid-turn tool results
+	// that the proactive ShouldCompact() check cannot catch. A single-retry
+	// guard (no loop) prevents compact/overflow cycles.
+	if isContextOverflow(err) {
+		// Persist completed-step messages from the failed attempt first so
+		// compaction and the rebuilt context include them — the replay then
+		// resumes from where the turn overflowed rather than restarting.
+		m.persistGenerationRemainder(result, sentCount)
+		result = nil
+
+		if retryMessages, retryErr := m.prepareOverflowRetry(ctx); retryErr != nil {
+			// Recovery impossible — wrap the original provider error with
+			// the recovery failure. ClassifyProviderError below still maps
+			// the chain to ErrContextOverflow, so the errors.Is contract
+			// holds even when the provider error was raw text.
+			err = fmt.Errorf("conversation too large to compact — context-overflow recovery failed (%v): %w", retryErr, err)
+		} else {
+			// Discard stream deltas captured during the failed attempt so
+			// TurnResult.Stream reflects only the replay.
+			collector.drain()
+			sentCount = len(retryMessages)
+			result, err = m.generate(ctx, retryMessages)
+			if isContextOverflow(err) {
+				err = fmt.Errorf("conversation too large to compact — still exceeds the model context window after compaction: %w", err)
+			}
+		}
+	}
+
 	if err != nil {
 		// Persist any messages from completed steps that were NOT already
 		// persisted incrementally by the onStepMessages callback. The agent
 		// layer only includes fully-paired tool_use + tool_result messages
 		// in completedStepMessages, so there are no orphaned entries that
 		// would break subsequent API requests.
-		if result != nil {
-			newMessages := result.ConversationMessages[sentCount:]
-			alreadyPersisted := result.PersistedMessageCount
-			if alreadyPersisted < len(newMessages) {
-				for _, msg := range newMessages[alreadyPersisted:] {
-					_, _ = m.session.AppendMessage(msg)
-				}
-			}
-		}
+		m.persistGenerationRemainder(result, sentCount)
 		m.events.emit(TurnEndEvent{Error: err})
 		// Run AfterTurn hooks even on error.
 		m.afterTurn.run(AfterTurnHook{Error: err})
@@ -2893,15 +2938,7 @@ func (m *Kit) runTurn(ctx context.Context, promptLabel string, prompt string, pr
 	// by the onStepMessages callback during generation. This handles the
 	// non-streaming path (where onStepMessages is not called) and any edge
 	// cases where the final response messages weren't covered by step callbacks.
-	if len(result.ConversationMessages) > sentCount {
-		newMessages := result.ConversationMessages[sentCount:]
-		alreadyPersisted := result.PersistedMessageCount
-		if alreadyPersisted < len(newMessages) {
-			for _, msg := range newMessages[alreadyPersisted:] {
-				_, _ = m.session.AppendMessage(msg)
-			}
-		}
-	}
+	m.persistGenerationRemainder(result, sentCount)
 
 	// Store the API-reported token count so GetContextStats() matches the
 	// built-in status bar. The context window is filled by all token

pkg/kit/overflow.go

@@ -0,0 +1,106 @@
+package kit
+
+import (
+	"context"
+	"errors"
+	"fmt"
+
+	"charm.land/fantasy"
+)
+
+// This file implements reactive compaction (issue #85): when a provider call
+// fails with a context-length/overflow error, Kit automatically compacts the
+// conversation and replays the turn once instead of surfacing a hard failure.
+//
+// Proactive compaction (ShouldCompact() before a turn) relies on token
+// estimates that inevitably drift from real tokenizer counts — especially
+// with tool-heavy traffic, non-English text, and images. A single huge
+// mid-turn tool result can also overflow the context even when the turn
+// started well under the limit. The reactive path is the safety net that
+// makes an imprecise estimator acceptable in practice.
+
+// isContextOverflow reports whether err is (or classifies as) a provider
+// context-window overflow.
+func isContextOverflow(err error) bool {
+	return err != nil && errors.Is(ClassifyProviderError(err), ErrContextOverflow)
+}
+
+// prepareOverflowRetry runs reactive compaction after a provider
+// context-overflow error and rebuilds the request context for a single
+// replay. Media attachments in the rebuilt context are replaced with text
+// placeholders — they are typically the largest contributors and cannot be
+// shrunk by summarisation, so dropping them from the replayed request gives
+// it the best chance to fit. The session itself is not modified beyond the
+// appended compaction entry.
+//
+// Returns the replay messages on success. On failure (compaction failed,
+// was cancelled, or produced no usable context) it returns a non-nil error
+// describing why recovery was impossible; callers wrap it together with the
+// original provider error so the surfaced failure both explains the failed
+// recovery and preserves the [ErrContextOverflow] classification.
+func (m *Kit) prepareOverflowRetry(ctx context.Context) ([]fantasy.Message, error) {
+	if _, err := m.compactInternal(ctx, m.compactionOpts, "", true); err != nil {
+		return nil, fmt.Errorf("compaction failed: %w", err)
+	}
+
+	// Rebuild the context from the session: the compaction summary now
+	// replaces the summarised prefix, and any completed steps persisted
+	// from the failed attempt are included so the replay resumes rather
+	// than restarts.
+	messages, _, _ := m.session.BuildContext()
+	messages = stripMediaParts(messages)
+
+	// Re-run ContextPrepare hooks on the rebuilt context, mirroring the
+	// initial attempt so extensions observe every outgoing request. Strip
+	// media from the hook result too — a hook may replace the messages and
+	// reintroduce attachments, which would defeat the recovery.
+	if hookResult := m.contextPrepare.run(ContextPrepareHook{Messages: messages}); hookResult != nil && hookResult.Messages != nil {
+		messages = stripMediaParts(hookResult.Messages)
+	}
+
+	if len(messages) == 0 {
+		return nil, fmt.Errorf("compaction produced an empty context")
+	}
+	return messages, nil
+}
+
+// stripMediaParts returns a copy of messages with file/media attachments
+// replaced by short text placeholders. Message slices and non-file parts are
+// shared, not copied; only messages containing file parts get a new Content
+// slice.
+func stripMediaParts(messages []fantasy.Message) []fantasy.Message {
+	out := make([]fantasy.Message, len(messages))
+	for i, msg := range messages {
+		out[i] = msg
+		hasFile := false
+		for _, part := range msg.Content {
+			if _, ok := part.(fantasy.FilePart); ok {
+				hasFile = true
+				break
+			}
+		}
+		if !hasFile {
+			continue
+		}
+		replaced := make([]fantasy.MessagePart, 0, len(msg.Content))
+		for _, part := range msg.Content {
+			fp, ok := part.(fantasy.FilePart)
+			if !ok {
+				replaced = append(replaced, part)
+				continue
+			}
+			name := fp.Filename
+			if name == "" {
+				name = fp.MediaType
+			}
+			if name == "" {
+				name = "attachment"
+			}
+			replaced = append(replaced, fantasy.TextPart{
+				Text: fmt.Sprintf("[attachment %q removed after context overflow]", name),
+			})
+		}
+		out[i].Content = replaced
+	}
+	return out
+}