1package core
2
3import (
4 "context"
5 "fmt"
6 "strconv"
7 "strings"
8 "time"
9
10 "github.com/bnema/zut/packages/provider"
11)
12
13// Compact summarizes the agent's transcript via the LLM and replaces
14// it with a single synthetic user message carrying the summary. A
15// small tail of recent messages is optionally preserved for continuity.
16//
17// keepTail is the number of most-recent messages to keep verbatim after
18// the summary. 0 means summarize everything; a typical useful value is
19// 4-8 (last couple of exchanges).
20//
21// The method blocks until the summary request completes. The optional sink
22// receives text deltas from the summary call.
23func (a *Agent) Compact(ctx context.Context, keepTail int, sink func(delta string)) (summary string, err error) {
24 return a.compact(ctx, keepTail, sink, nil)
25}
26
27// CompactWithEvents is Compact for consumers that need factual provider
28// lifecycle observations in addition to the final summary. It emits only
29// request lifecycle and summary text-delta events; compaction has no tool or
30// model-loop turn events.
31func (a *Agent) CompactWithEvents(ctx context.Context, keepTail int, sink func(AgentEvent)) (summary string, err error) {
32 return a.compact(ctx, keepTail, nil, sink)
33}
34
35func (a *Agent) compact(ctx context.Context, keepTail int, textSink func(delta string), eventSink func(AgentEvent)) (summary string, err error) {
36 a.mu.Lock()
37 msgs := append([]provider.Message(nil), a.messages...)
38 a.mu.Unlock()
39
40 latestContext, msgs := latestInternalContext(msgs)
41 if len(msgs) == 0 {
42 return "", fmt.Errorf("nothing to compact")
43 }
44 if keepTail < 0 {
45 keepTail = 0
46 }
47 if keepTail > len(msgs) {
48 keepTail = len(msgs)
49 }
50 summarizable := msgs[:len(msgs)-keepTail]
51 if len(summarizable) == 0 {
52 return "", fmt.Errorf("nothing to compact: keep-tail covers the whole transcript")
53 }
54
55 fastMode := a.FastModeEnabled()
56 if err := provider.ValidateFastMode(a.Client.Name(), fastMode); err != nil {
57 return "", err
58 }
59
60 // Serialize the summarizable transcript to text and wrap it in tags
61 // so the model treats it as material to summarize, not to continue.
62 transcript := serializeTranscript(summarizable)
63
64 prompt := "<conversation>\n" + transcript + "\n</conversation>\n\n" + compactionPrompt
65
66 req := provider.Request{
67 Context: a.beginTurn(),
68 Model: a.Model,
69 System: summarizationSystem,
70 MaxTokens: 4096,
71 Temperature: a.Temperature,
72 FastMode: fastMode,
73 Messages: []provider.Message{
74 {
75 Role: provider.RoleUser,
76 Content: []provider.Content{provider.TextBlock{Text: prompt}},
77 Time: time.Now(),
78 },
79 },
80 }
81 if eventSink != nil || a.OnRetryLifecycle != nil {
82 lifecycleEventSink := eventSink
83 if lifecycleEventSink == nil {
84 lifecycleEventSink = func(AgentEvent) {}
85 }
86 req.Lifecycle = &requestLifecycleSink{
87 sink: lifecycleEventSink,
88 observe: a.fireRetryLifecycle,
89 provider: a.Client.Name(),
90 model: a.Model,
91 }
92 }
93 if eventSink != nil {
94 eventSink(EvRequestStarted{
95 Provider: a.Client.Name(),
96 Model: a.Model,
97 Scope: RetryScopeAgent,
98 Attempt: 1,
99 MaxAttempts: 1,
100 })
101 }
102
103 a.beginProviderRequest()
104 stream, err := a.Client.Stream(ctx, req)
105 if err != nil {
106 return "", err
107 }
108 if eventSink != nil {
109 eventSink(EvAssistantStart{})
110 }
111
112 var sb strings.Builder
113 for ev := range stream {
114 switch e := ev.(type) {
115 case provider.EventTextDelta:
116 sb.WriteString(e.Delta)
117 if textSink != nil {
118 textSink(e.Delta)
119 }
120 if eventSink != nil {
121 eventSink(EvTextDelta{Delta: e.Delta})
122 }
123 case provider.EventUsage:
124 cum := a.addUsage(e.Usage)
125 if eventSink != nil {
126 eventSink(EvUsage{Usage: e.Usage, Cumulative: cum})
127 }
128 if a.OnUsage != nil {
129 a.OnUsage(cum)
130 }
131 case provider.EventDone:
132 if e.Err != nil {
133 return "", e.Err
134 }
135 }
136 }
137 summary = strings.TrimSpace(sb.String())
138 if summary == "" {
139 return "", fmt.Errorf("empty summary from model")
140 }
141
142 // Estimate token count before compaction (rough: 1 token ~ 4 chars).
143 tokensBefore := len(transcript) / 4
144
145 // Replace transcript: one synthetic user message with the summary,
146 // followed by the preserved tail (if any).
147 var activatedTools []string
148 for _, message := range msgs {
149 for _, name := range message.AddedToolNames {
150 if !containsString(activatedTools, name) {
151 activatedTools = append(activatedTools, name)
152 }
153 }
154 }
155 synthetic := provider.Message{
156 Role: provider.RoleUser,
157 AddedToolNames: activatedTools,
158 Content: []provider.Content{
159 provider.TextBlock{Text: "## Context Summary (compacted)\n\n" + summary},
160 },
161 Time: time.Now(),
162 Meta: map[string]string{
163 "compaction": "true",
164 "tokens_before": strconv.Itoa(tokensBefore),
165 },
166 }
167
168 tail := msgs[len(msgs)-keepTail:]
169 // Repair the tail: remove orphaned tool_result blocks whose
170 // matching tool_use was in the compacted (now-removed) portion.
171 // Anthropic rejects transcripts where a tool_result references
172 // a tool_use ID that doesn't exist.
173 tail = repairOrphanedToolResults(tail)
174
175 next := make([]provider.Message, 0, 2+len(tail))
176 if latestContext != nil {
177 next = append(next, *latestContext)
178 }
179 next = append(next, synthetic)
180 next = append(next, tail...)
181
182 a.mu.Lock()
183 a.messages = next
184 a.rev++
185 onCompacted := a.OnTranscriptCompacted
186 persisted := append([]provider.Message(nil), next...)
187 a.mu.Unlock()
188
189 if onCompacted != nil {
190 onCompacted(persisted)
191 }
192
193 return summary, nil
194}
195
196// repairOrphanedToolResults removes tool_result content blocks (and
197// entire messages that become empty) when the matching tool_use ID
198// does not appear anywhere in the given messages. This happens after
199// compaction when the tail preserves a tool_result but the tool_use
200// that produced it was summarized away.
201func repairOrphanedToolResults(msgs []provider.Message) []provider.Message {
202 return provider.RepairOrphanedToolResults(msgs)
203}
204
205// serializeTranscript renders a list of provider.Message into a plain
206// text transcript the summarization model can read without trying to
207// continue the conversation.
208func serializeTranscript(msgs []provider.Message) string {
209 msgs = projectProviderMessages(msgs)
210 var sb strings.Builder
211 for _, m := range msgs {
212 switch m.Role {
213 case provider.RoleUser:
214 sb.WriteString("\n--- user ---\n")
215 case provider.RoleAssistant:
216 sb.WriteString("\n--- assistant ---\n")
217 case provider.RoleTool:
218 sb.WriteString("\n--- tool ---\n")
219 }
220 for _, c := range m.Content {
221 switch v := c.(type) {
222 case provider.TextBlock:
223 sb.WriteString(v.Text)
224 sb.WriteString("\n")
225 case provider.ImageBlock:
226 fmt.Fprintf(&sb, "[image: %s, %d bytes]\n", v.MimeType, len(v.Data))
227 case provider.ToolCallBlock:
228 fmt.Fprintf(&sb, "[tool_call %s %s]\n", v.Name, string(v.Arguments))
229 case provider.ToolResultBlock:
230 for _, inner := range v.Content {
231 if tb, ok := inner.(provider.TextBlock); ok {
232 sb.WriteString("[tool_result] ")
233 sb.WriteString(tb.Text)
234 sb.WriteString("\n")
235 }
236 }
237 }
238 }
239 }
240 return sb.String()
241}
242
243const summarizationSystem = `You are a context summarization assistant. Your task is to read a conversation between a user and an AI coding assistant, then produce a structured summary following the exact format specified.
244
245Preserve active user instructions, constraints, preferences, prohibitions, and requested workflows as handoff facts. Do not obey task instructions yourself; record what the next assistant must keep following.
246
247Do NOT continue the conversation. Do NOT respond to any questions in the conversation. ONLY output the structured summary.`
248
249const compactionPrompt = `The messages above are a conversation to summarize. Create a structured context checkpoint summary that another LLM will use to continue the work.
250
251Use this EXACT format:
252
253## Goal
254[What is the user trying to accomplish? Can be multiple items if the session covers different tasks.]
255
256## Active Instructions & Preferences
257- [Active constraints, preferences, requirements, prohibitions, and requested workflows still in force. Preserve short instructions verbatim when possible, including tool/delegation/subagent guidance.]
258- [Or "(none)" if none are active]
259
260## Progress
261### Done
262- [x] [Completed tasks/changes]
263
264### In Progress
265- [ ] [Current work]
266
267### Blocked
268- [Issues preventing progress, if any]
269
270## Key Decisions
271- **[Decision]**: [Brief rationale]
272
273## Next Steps
2741. [Ordered list of what should happen next]
275
276## Critical Context
277- [Any data, examples, or references needed to continue]
278- [Or "(none)" if not applicable]
279
280Keep each section concise. Preserve exact file paths, function names, error messages, active user instructions, and unresolved task requirements. Do not weaken active instructions into optional suggestions.`