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 // Carry the active plan over the compaction boundary. The step text is
176 // otherwise lost with the summarized transcript, so the model could not
177 // resolve the indices its indexed update and remove actions need. The block
178 // is merged into the internal-context message that survives compaction;
179 // with no plan the retained message is left byte-for-byte unchanged.
180 if latestContext != nil {
181 if block := planContextBlock(a.CurrentPlan()); block != "" {
182 *latestContext = mergePlanContextBlock(*latestContext, block)
183 }
184 }
185
186 next := make([]provider.Message, 0, 2+len(tail))
187 if latestContext != nil {
188 next = append(next, *latestContext)
189 }
190 next = append(next, synthetic)
191 next = append(next, tail...)
192
193 a.mu.Lock()
194 a.messages = next
195 a.rev++
196 onCompacted := a.OnTranscriptCompacted
197 persisted := append([]provider.Message(nil), next...)
198 a.mu.Unlock()
199
200 if onCompacted != nil {
201 onCompacted(persisted)
202 }
203
204 return summary, nil
205}
206
207// planContextStepLimit bounds the steps carried into the retained internal
208// context. It is deliberately the only size bound on a plan: state, storage,
209// and the tool itself have no cap, but the post-compaction block the model
210// reads on every later request stays small.
211const planContextStepLimit = 12
212
213// planContextHeader opens the plan block. The whole block is always appended
214// last, so the final occurrence of this line marks where a previous block
215// starts and mergePlanContextBlock can replace rather than duplicate it.
216const planContextHeader = "## Current plan"
217
218// planContextBlock renders the plan carried across compaction. Step lines use
219// the same markers as show output, so the model can map them to the listing and
220// to the 1-based indices the tool accepts.
221func planContextBlock(steps []PlanStep) string {
222 if len(steps) == 0 {
223 return ""
224 }
225 shown := steps
226 if len(shown) > planContextStepLimit {
227 shown = shown[:planContextStepLimit]
228 }
229 var b strings.Builder
230 b.WriteString(planContextHeader)
231 for idx, step := range shown {
232 fmt.Fprintf(&b, "\n%d. [%s] %s", idx+1, planStepMarker(step.Status), step.Step)
233 }
234 if remaining := len(steps) - len(shown); remaining > 0 {
235 fmt.Fprintf(&b, "\n…and %d more (call action:\"show\")", remaining)
236 }
237 return b.String()
238}
239
240// mergePlanContextBlock returns message with block merged into its internal
241// context text. An earlier plan block is replaced, so compacting twice cannot
242// duplicate it. A message that is not a single text block is returned
243// unchanged rather than risk dropping content.
244func mergePlanContextBlock(message provider.Message, block string) provider.Message {
245 if block == "" || len(message.Content) != 1 {
246 return message
247 }
248 text, ok := message.Content[0].(provider.TextBlock)
249 if !ok {
250 return message
251 }
252 base := stripPlanContextBlock(text.Text)
253 merged := block
254 if base != "" {
255 merged = base + "\n\n" + block
256 }
257 message.Content = []provider.Content{provider.TextBlock{Text: merged}}
258 return message
259}
260
261// stripPlanContextBlock removes a previously injected plan block. The block is
262// always appended last, so the final header occurrence is its start.
263func stripPlanContextBlock(text string) string {
264 idx := strings.LastIndex(text, planContextHeader)
265 if idx < 0 {
266 return text
267 }
268 return strings.TrimRight(text[:idx], " \t\n")
269}
270
271// repairOrphanedToolResults removes tool_result content blocks (and
272// entire messages that become empty) when the matching tool_use ID
273// does not appear anywhere in the given messages. This happens after
274// compaction when the tail preserves a tool_result but the tool_use
275// that produced it was summarized away.
276func repairOrphanedToolResults(msgs []provider.Message) []provider.Message {
277 return provider.RepairOrphanedToolResults(msgs)
278}
279
280// serializeTranscript renders a list of provider.Message into a plain
281// text transcript the summarization model can read without trying to
282// continue the conversation.
283func serializeTranscript(msgs []provider.Message) string {
284 msgs = projectProviderMessages(msgs)
285 var sb strings.Builder
286 for _, m := range msgs {
287 switch m.Role {
288 case provider.RoleUser:
289 sb.WriteString("\n--- user ---\n")
290 case provider.RoleAssistant:
291 sb.WriteString("\n--- assistant ---\n")
292 case provider.RoleTool:
293 sb.WriteString("\n--- tool ---\n")
294 }
295 for _, c := range m.Content {
296 switch v := c.(type) {
297 case provider.TextBlock:
298 sb.WriteString(v.Text)
299 sb.WriteString("\n")
300 case provider.ImageBlock:
301 fmt.Fprintf(&sb, "[image: %s, %d bytes]\n", v.MimeType, len(v.Data))
302 case provider.ToolCallBlock:
303 fmt.Fprintf(&sb, "[tool_call %s %s]\n", v.Name, string(v.Arguments))
304 case provider.ToolResultBlock:
305 for _, inner := range v.Content {
306 if tb, ok := inner.(provider.TextBlock); ok {
307 sb.WriteString("[tool_result] ")
308 sb.WriteString(tb.Text)
309 sb.WriteString("\n")
310 }
311 }
312 }
313 }
314 }
315 return sb.String()
316}
317
318const 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.
319
320Preserve 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.
321
322Do NOT continue the conversation. Do NOT respond to any questions in the conversation. ONLY output the structured summary.`
323
324const compactionPrompt = `The messages above are a conversation to summarize. Create a structured context checkpoint summary that another LLM will use to continue the work.
325
326Use this EXACT format:
327
328## Goal
329[What is the user trying to accomplish? Can be multiple items if the session covers different tasks.]
330
331## Active Instructions & Preferences
332- [Active constraints, preferences, requirements, prohibitions, and requested workflows still in force. Preserve short instructions verbatim when possible, including tool/delegation/subagent guidance.]
333- [Or "(none)" if none are active]
334
335## Progress
336### Done
337- [x] [Completed tasks/changes]
338
339### In Progress
340- [ ] [Current work]
341
342### Blocked
343- [Issues preventing progress, if any]
344
345## Key Decisions
346- **[Decision]**: [Brief rationale]
347
348## Next Steps
3491. [Ordered list of what should happen next]
350
351## Critical Context
352- [Any data, examples, or references needed to continue]
353- [Or "(none)" if not applicable]
354
355Keep 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.`