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 if len(msgs) == 0 {
41 return "", fmt.Errorf("nothing to compact")
42 }
43 if keepTail < 0 {
44 keepTail = 0
45 }
46 if keepTail > len(msgs) {
47 keepTail = len(msgs)
48 }
49 summarizable := msgs[:len(msgs)-keepTail]
50 if len(summarizable) == 0 {
51 return "", fmt.Errorf("nothing to compact: keep-tail covers the whole transcript")
52 }
53
54 fastMode := a.FastModeEnabled()
55 if err := provider.ValidateFastMode(a.Client.Name(), fastMode); err != nil {
56 return "", err
57 }
58
59 // Serialize the summarizable transcript to text and wrap it in tags
60 // so the model treats it as material to summarize, not to continue.
61 transcript := serializeTranscript(summarizable)
62
63 prompt := "<conversation>\n" + transcript + "\n</conversation>\n\n" + compactionPrompt
64
65 systemContext := a.providerTimeContext().systemText()
66 req := provider.Request{
67 Model: a.Model,
68 System: summarizationSystem,
69 SystemContext: systemContext,
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 stream, err := a.Client.Stream(ctx, req)
104 if err != nil {
105 return "", err
106 }
107 if eventSink != nil {
108 eventSink(EvAssistantStart{})
109 }
110
111 var sb strings.Builder
112 for ev := range stream {
113 switch e := ev.(type) {
114 case provider.EventTextDelta:
115 sb.WriteString(e.Delta)
116 if textSink != nil {
117 textSink(e.Delta)
118 }
119 if eventSink != nil {
120 eventSink(EvTextDelta{Delta: e.Delta})
121 }
122 case provider.EventUsage:
123 cum := a.addUsage(e.Usage)
124 if eventSink != nil {
125 eventSink(EvUsage{Usage: e.Usage, Cumulative: cum})
126 }
127 if a.OnUsage != nil {
128 a.OnUsage(cum)
129 }
130 case provider.EventDone:
131 if e.Err != nil {
132 return "", e.Err
133 }
134 }
135 }
136 summary = strings.TrimSpace(sb.String())
137 if summary == "" {
138 return "", fmt.Errorf("empty summary from model")
139 }
140
141 // Estimate token count before compaction (rough: 1 token ~ 4 chars).
142 tokensBefore := len(transcript) / 4
143
144 // Replace transcript: one synthetic user message with the summary,
145 // followed by the preserved tail (if any).
146 var activatedTools []string
147 for _, message := range msgs {
148 for _, name := range message.AddedToolNames {
149 if !containsString(activatedTools, name) {
150 activatedTools = append(activatedTools, name)
151 }
152 }
153 }
154 synthetic := provider.Message{
155 Role: provider.RoleUser,
156 AddedToolNames: activatedTools,
157 Content: []provider.Content{
158 provider.TextBlock{Text: "## Context Summary (compacted)\n\n" + summary},
159 },
160 Time: time.Now(),
161 Meta: map[string]string{
162 "compaction": "true",
163 "tokens_before": strconv.Itoa(tokensBefore),
164 },
165 }
166
167 tail := msgs[len(msgs)-keepTail:]
168 // Repair the tail: remove orphaned tool_result blocks whose
169 // matching tool_use was in the compacted (now-removed) portion.
170 // Anthropic rejects transcripts where a tool_result references
171 // a tool_use ID that doesn't exist.
172 tail = repairOrphanedToolResults(tail)
173
174 next := make([]provider.Message, 0, 1+len(tail))
175 next = append(next, synthetic)
176 next = append(next, tail...)
177
178 a.mu.Lock()
179 a.messages = next
180 a.rev++
181 onCompacted := a.OnTranscriptCompacted
182 persisted := append([]provider.Message(nil), next...)
183 a.mu.Unlock()
184
185 if onCompacted != nil {
186 onCompacted(persisted)
187 }
188
189 return summary, nil
190}
191
192// repairOrphanedToolResults removes tool_result content blocks (and
193// entire messages that become empty) when the matching tool_use ID
194// does not appear anywhere in the given messages. This happens after
195// compaction when the tail preserves a tool_result but the tool_use
196// that produced it was summarized away.
197func repairOrphanedToolResults(msgs []provider.Message) []provider.Message {
198 return provider.RepairOrphanedToolResults(msgs)
199}
200
201// serializeTranscript renders a list of provider.Message into a plain
202// text transcript the summarization model can read without trying to
203// continue the conversation.
204func serializeTranscript(msgs []provider.Message) string {
205 msgs = projectProviderMessages(msgs)
206 var sb strings.Builder
207 for _, m := range msgs {
208 switch m.Role {
209 case provider.RoleUser:
210 sb.WriteString("\n--- user ---\n")
211 case provider.RoleAssistant:
212 sb.WriteString("\n--- assistant ---\n")
213 case provider.RoleTool:
214 sb.WriteString("\n--- tool ---\n")
215 }
216 for _, c := range m.Content {
217 switch v := c.(type) {
218 case provider.TextBlock:
219 sb.WriteString(v.Text)
220 sb.WriteString("\n")
221 case provider.ImageBlock:
222 fmt.Fprintf(&sb, "[image: %s, %d bytes]\n", v.MimeType, len(v.Data))
223 case provider.ToolCallBlock:
224 fmt.Fprintf(&sb, "[tool_call %s %s]\n", v.Name, string(v.Arguments))
225 case provider.ToolResultBlock:
226 for _, inner := range v.Content {
227 if tb, ok := inner.(provider.TextBlock); ok {
228 sb.WriteString("[tool_result] ")
229 sb.WriteString(tb.Text)
230 sb.WriteString("\n")
231 }
232 }
233 }
234 }
235 }
236 return sb.String()
237}
238
239const 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.
240
241Preserve 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.
242
243Do NOT continue the conversation. Do NOT respond to any questions in the conversation. ONLY output the structured summary.`
244
245const compactionPrompt = `The messages above are a conversation to summarize. Create a structured context checkpoint summary that another LLM will use to continue the work.
246
247Use this EXACT format:
248
249## Goal
250[What is the user trying to accomplish? Can be multiple items if the session covers different tasks.]
251
252## Active Instructions & Preferences
253- [Active constraints, preferences, requirements, prohibitions, and requested workflows still in force. Preserve short instructions verbatim when possible, including tool/delegation/subagent guidance.]
254- [Or "(none)" if none are active]
255
256## Progress
257### Done
258- [x] [Completed tasks/changes]
259
260### In Progress
261- [ ] [Current work]
262
263### Blocked
264- [Issues preventing progress, if any]
265
266## Key Decisions
267- **[Decision]**: [Brief rationale]
268
269## Next Steps
2701. [Ordered list of what should happen next]
271
272## Critical Context
273- [Any data, examples, or references needed to continue]
274- [Or "(none)" if not applicable]
275
276Keep 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.`