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