johannSoCodeyPublic

Phase 4: prompt caching, compaction, stale-read superseding

Two cache breakpoints, well short of the limit of four: one on the system
block, which also covers the tool definitions since tools render before
system, and one rolling forward over the end of the conversation so each
turn writes a small delta and reads a large prefix. The breakpoints are
applied to a copy — leaving them in the stored history would accumulate one
per turn and blow the limit — and -no-cache turns them off so the eval
suite can measure what they are worth.

Compaction triggers on the input token count the API reported last turn,
which is exact and free, rather than on a local estimate. The cut always
lands on an assistant message: the summary takes the user slot before it,
and a tail starting with a tool_result message would reference a tool_use
that no longer exists. The original task is carried through verbatim
instead of being summarized, and the summarization call is made without
tools so it cannot touch the repository.

Stale reads are the subtler win. A file read twenty turns ago and edited
since is not just wasted context, it is wrong, and the model will reason
from it. After a successful edit_file or write_file, earlier read results
for that path are replaced with a stub pointing at the current version.
The most recent read survives, since that one is still true.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Browse Files

Jjonicommitted 4 weeks ago1 parent daac0bdcommite8e53e8

Showing 9 changed files with 622 additions and 10 deletions.

+10−1cmd/harness/main.goView File

@@ -34,6 +34,9 @@ func run() error {
34	34	authToken := flag.String("auth-token", "", "credential sent as Authorization: Bearer, for OAuth tokens and most gateways (env ANTHROPIC_AUTH_TOKEN)")
35	35	effort := flag.String("effort", "", "output_config.effort: low\|medium\|high\|xhigh\|max (default: the API's, high)")
36	36	maxTurns := flag.Int("max-turns", agent.DefaultMaxTurns, "turn cap per prompt")
	37	+ contextWindow := flag.Int("context-window", agent.DefaultContextWindow, "model context window, used to decide when to compact")
	38	+ compactAt := flag.Float64("compact-at", agent.DefaultCompactAt, "fraction of the window at which to compact")
	39	+ noCache := flag.Bool("no-cache", false, "disable prompt cache breakpoints")
37	40	logPath := flag.String("metrics", metrics.DefaultPath, "JSONL event log path, relative to the working root")
38	41	prompt := flag.String("p", "", "run one prompt and exit, instead of starting the REPL")
39	42	verbose := flag.Bool("v", false, "print full tool output")
@@ -82,7 +85,13 @@ func run() error {
82	85	)
83	86
84	87	render := &ui.Renderer{W: os.Stdout, Verbose: *verbose}
85		- a := agent.New(client, reg, state, log, agent.Options{MaxTurns: maxTurns, Effort: effort})
	88	+ a := agent.New(client, reg, state, log, agent.Options{
	89	+ MaxTurns: *maxTurns,
	90	+ Effort: *effort,
	91	+ ContextWindow: *contextWindow,
	92	+ CompactAt: *compactAt,
	93	+ NoCache: *noCache,
	94	+ })
86	95	a.Observe = render.Handle
87	96
88	97	ctx := context.Background()

+10−3evals/runner.goView File

@@ -69,6 +69,8 @@ func run() error {
69	69	model := flag.String("model", "", "model id")
70	70	effort := flag.String("effort", "", "output_config.effort")
71	71	maxTurns := flag.Int("max-turns", 40, "turn cap per run")
	72	+ contextWindow := flag.Int("context-window", agent.DefaultContextWindow, "model context window")
	73	+ noCache := flag.Bool("no-cache", false, "disable prompt cache breakpoints, to measure what they buy")
72	74	timeout := flag.Duration("timeout", 10*time.Minute, "wall-clock cap per run")
73	75	tasksDir := flag.String("dir", "evals/tasks", "directory of task definitions")
74	76	outDir := flag.String("out", "evals/runs", "where to persist transcripts")
@@ -118,7 +120,12 @@ func run() error {
118	120	sem <- struct{}{}
119	121	defer func() { <-sem }()
120	122
121		- res := runOne(j.task, j.run, client, maxTurns, effort, timeout, keep)
	123	+ res := runOne(j.task, j.run, client, agent.Options{
	124	+ MaxTurns: *maxTurns,
	125	+ Effort: *effort,
	126	+ ContextWindow: *contextWindow,
	127	+ NoCache: *noCache,
	128	+ }, timeout, keep)
122	129	mu.Lock()
123	130	results = append(results, res)
124	131	mu.Unlock()
@@ -151,7 +158,7 @@ func run() error {
151	158	// verifies the result.
152	159	// The return value is named so the deferred timing assignment lands in the
153	160	// value actually returned rather than in a copy already made.
154		- func runOne(task Task, runNo int, client *llm.Client, maxTurns int, effort string, timeout time.Duration, keep bool) (res Result) {
	161	+ func runOne(task Task, runNo int, client *llm.Client, opts agent.Options, timeout time.Duration, keep bool) (res Result) {
155	162	res = Result{Task: task.Name, Run: runNo}
156	163	start := time.Now()
157	164	defer func() { res.WallMS = time.Since(start).Milliseconds() }()
@@ -185,7 +192,7 @@ func runOne(task Task, runNo int, client *llm.Client, maxTurns int, effort strin
185	192	tools.NewWrite(work, state),
186	193	tools.NewBash(work),
187	194	)
188		- a := agent.New(client, reg, state, log, agent.Options{MaxTurns: maxTurns, Effort: effort})
	195	+ a := agent.New(client, reg, state, log, opts)
189	196
190	197	answer, runErr := a.Run(ctx, task.Prompt)
191	198	res.Answer = answer

+173−0internal/agent/compact.goaddedView File

++ package agent
++ import (
++ 	"context"
++ 	"fmt"
++ 	"strings"
++ 	"harness/internal/llm"
++ 	"harness/internal/metrics"
++ )
++ // metricsCompaction records a compaction so its effect on later turns is
++ // visible in the event log.
++ func metricsCompaction(inputTokens, before, after int) metrics.Event {
++ 	return metrics.Event{
++ 		Type:        "compaction",
++ 		InputTokens: inputTokens,
++ 		Extra:       map[string]any{"messages_before": before, "messages_after": after},
++ 	}
++ }
++ // DefaultContextWindow is the Claude Opus 5 window. Lower it with
++ // Options.ContextWindow when running a model with less room.
++ const DefaultContextWindow = 1_000_000
++ // DefaultCompactAt is the fraction of the window at which to summarize.
++ // Compaction itself needs headroom — it is a model call with the history in it
++ // — so waiting until the window is nearly full means the compaction request is
++ // the one that fails.
++ const DefaultCompactAt = 0.7
++ // keepRecentMessages is how much of the tail survives compaction verbatim. The
++ // model is usually mid-thought, and a summary of the last two minutes of work
++ // is worse than the work itself.
++ const keepRecentMessages = 6
++ const compactPrompt = `Summarize the conversation above for a coding agent that will keep working on the same task with this summary in place of the transcript.
++ Preserve, in this order:
++ 1. The original task, verbatim enough that nothing about it is lost.
++ 2. Every file touched so far and what was changed in it, with paths.
++ 3. Decisions made and the reasoning that is not re-derivable from the code.
++ 4. Things discovered the hard way: where something actually lives, what a test really asserts, what did not work and why.
++ 5. What is left to do.
++ Be specific. Names, paths and line numbers are worth more than prose. Omit
++ pleasantries and anything already visible in the current state of the files.`
++ // maybeCompact summarizes the older half of the conversation when the last
++ // request came close to filling the window. It reports whether it compacted.
++ func (a *Agent) maybeCompact(ctx context.Context, lastInputTokens int) (bool, error) {
++ 	window := a.opts.ContextWindow
++ 	if window <= 0 {
++ 		window = DefaultContextWindow
++ 	}
++ 	at := a.opts.CompactAt
++ 	if at <= 0 {
++ 		at = DefaultCompactAt
++ 	}
++ 	if float64(lastInputTokens) < at*float64(window) {
++ 		return false, nil
++ 	}
++ 	history := a.state.History()
++ 	split := compactionSplit(history)
++ 	if split < 0 {
++ 		return false, nil // nothing safe to fold away yet
++ 	}
++ 	summary, err := a.summarize(ctx, history[:split])
++ 	if err != nil {
++ 		return false, err
++ 	}
++ 	// The task itself is the one thing never summarized: everything downstream
++ 	// is judged against it.
++ 	task := originalTask(history)
++ 	folded := llm.Message{Role: llm.RoleUser, Content: []llm.ContentBlock{
++ 		llm.TextBlock(fmt.Sprintf("[Earlier conversation, compacted]\n\nOriginal task:\n%s\n\nWhat has happened since:\n%s", task, summary)),
++ 	}}
++ 	a.state.Replace(append([]llm.Message{folded}, history[split:]...))
++ 	a.log.Log(metricsCompaction(lastInputTokens, len(history), a.state.Len()))
++ 	a.emit(Event{Kind: EventCompact, Text: summary})
++ 	return true, nil
++ }
++ // compactionSplit picks where to cut. The kept tail must begin with an
++ // assistant message: the folded summary takes the user slot before it, and a
++ // tail starting with a tool_result user message would reference a tool_use that
++ // no longer exists, which the API rejects.
++ func compactionSplit(history []llm.Message) int {
++ 	if len(history) <= keepRecentMessages+2 {
++ 		return -1
++ 	}
++ 	want := len(history) / 2
++ 	if max := len(history) - keepRecentMessages; want > max {
++ 		want = max
++ 	}
++ 	for i := want; i < len(history); i++ {
++ 		if history[i].Role == llm.RoleAssistant {
++ 			return i
++ 		}
++ 	}
++ 	return -1
++ }
++ // summarize asks the model to fold the given messages into prose. It runs
++ // without tools: this call must not be able to touch the repository.
++ func (a *Agent) summarize(ctx context.Context, history []llm.Message) (string, error) {
++ 	msgs := append([]llm.Message(nil), history...)
++ 	msgs = append(msgs, llm.Message{
++ 		Role:    llm.RoleUser,
++ 		Content: []llm.ContentBlock{llm.TextBlock(compactPrompt)},
++ 	})
++ 	resp, err := a.client.CreateMessage(ctx, llm.Request{
++ 		MaxTokens: 4096,
++ 		Messages:  stripTrailingToolUse(msgs),
++ 		Thinking:  llm.Adaptive(),
++ 	})
++ 	if err != nil {
++ 		return "", fmt.Errorf("compaction: %w", err)
++ 	}
++ 	text := strings.TrimSpace(resp.Text())
++ 	if text == "" {
++ 		return "", fmt.Errorf("compaction produced no summary")
++ 	}
++ 	return text, nil
++ }
++ // stripTrailingToolUse drops a dangling assistant tool_use at the end, which
++ // would otherwise demand tool_result blocks the summarization request has no
++ // way to supply.
++ func stripTrailingToolUse(msgs []llm.Message) []llm.Message {
++ 	for len(msgs) > 0 {
++ 		last := msgs[len(msgs)-1]
++ 		if last.Role != llm.RoleAssistant {
++ 			break
++ 		}
++ 		var hasToolUse bool
++ 		for _, b := range last.Content {
++ 			if b.Type == llm.BlockToolUse {
++ 				hasToolUse = true
++ 				break
++ 			}
++ 		}
++ 		if !hasToolUse {
++ 			break
++ 		}
++ 		msgs = msgs[:len(msgs)-1]
++ 	}
++ 	return msgs
++ }
++ // originalTask returns the first user message's text.
++ func originalTask(history []llm.Message) string {
++ 	for _, m := range history {
++ 		if m.Role != llm.RoleUser {
++ 			continue
++ 		}
++ 		var b strings.Builder
++ 		for _, blk := range m.Content {
++ 			if blk.Type == llm.BlockText {
++ 				b.WriteString(blk.Text)
++ 			}
++ 		}
++ 		if s := strings.TrimSpace(b.String()); s != "" {
++ 			return s
++ 		}
++ 	}
++ 	return "(unrecorded)"
++ }

+252−0internal/agent/compact_test.goaddedView File

++ package agent
++ import (
++ 	"bytes"
++ 	"context"
++ 	"encoding/json"
++ 	"os"
++ 	"path/filepath"
++ 	"strings"
++ 	"testing"
++ 	"harness/internal/llm"
++ )
++ func TestCacheBreakpoints(t *testing.T) {
++ 	f := newFakeAPI(t, msg("end_turn", textBlock("hi")))
++ 	a := newTestAgent(t, f, t.TempDir(), &bytes.Buffer{})
++ 	if _, err := a.Run(context.Background(), "hello"); err != nil {
++ 		t.Fatalf("Run: %v", err)
++ 	}
++ 	req := f.requests[0]
++ 	if req.System[0].CacheControl == nil {
++ 		t.Error("the system prompt should carry a breakpoint: it and the tools never change")
++ 	}
++ 	last := req.Messages[len(req.Messages)-1]
++ 	if last.Content[len(last.Content)-1].CacheControl == nil {
++ 		t.Error("the end of the conversation should carry a rolling breakpoint")
++ 	}
++ 	raw := f.rawRequest(0)
++ 	if n := strings.Count(raw, `"cache_control"`); n != 2 {
++ 		t.Errorf("%d breakpoints in the body, want 2 (the limit is 4):\n%s", n, raw)
++ 	}
++ }
++ func TestNoCacheOption(t *testing.T) {
++ 	f := newFakeAPI(t, msg("end_turn", textBlock("hi")))
++ 	a := newTestAgent(t, f, t.TempDir(), &bytes.Buffer{})
++ 	a.opts.NoCache = true
++ 	if _, err := a.Run(context.Background(), "hello"); err != nil {
++ 		t.Fatalf("Run: %v", err)
++ 	}
++ 	if strings.Contains(f.rawRequest(0), "cache_control") {
++ 		t.Error("NoCache should send no breakpoints")
++ 	}
++ }
++ // Breakpoints must not mutate the stored history, or every turn would
++ // accumulate another one and blow past the four-breakpoint limit.
++ func TestBreakpointsDoNotLeakIntoHistory(t *testing.T) {
++ 	f := newFakeAPI(t,
++ 		msg("tool_use", toolUseBlock("tu_1", "boom", `{}`)),
++ 		msg("tool_use", toolUseBlock("tu_2", "boom", `{}`)),
++ 		msg("end_turn", textBlock("done")),
++ 	)
++ 	a := newTestAgent(t, f, t.TempDir(), &bytes.Buffer{})
++ 	if _, err := a.Run(context.Background(), "go"); err != nil {
++ 		t.Fatalf("Run: %v", err)
++ 	}
++ 	for i := range f.requests {
++ 		if n := strings.Count(f.rawRequest(i), `"cache_control"`); n != 2 {
++ 			t.Errorf("request %d has %d breakpoints, want 2", i, n)
++ 		}
++ 	}
++ 	for _, m := range a.State().History() {
++ 		for _, b := range m.Content {
++ 			if b.CacheControl != nil {
++ 				t.Error("stored history should stay free of breakpoints")
++ 			}
++ 		}
++ 	}
++ }
++ func TestCompactionSplitLandsOnAnAssistantMessage(t *testing.T) {
++ 	mk := func(roles string) []llm.Message {
++ 		var out []llm.Message
++ 		for _, r := range roles {
++ 			role := llm.RoleUser
++ 			if r == 'a' {
++ 				role = llm.RoleAssistant
++ 			}
++ 			out = append(out, llm.Message{Role: role, Content: []llm.ContentBlock{llm.TextBlock("x")}})
++ 		}
++ 		return out
++ 	}
++ 	tests := []struct {
++ 		name  string
++ 		roles string
++ 		want  int
++ 	}{
++ 		{name: "too short to compact", roles: "uaua", want: -1},
++ 		{name: "cuts at the first assistant past the midpoint", roles: "uauauauauaua", want: 7},
++ 		// The tail can end up one message shorter than the target when the
++ 		// boundary lands on a user message: correctness beats the constant.
++ 		{name: "skips forward past a user message", roles: "uauauauaua", want: 5},
++ 	}
++ 	for _, tc := range tests {
++ 		t.Run(tc.name, func(t *testing.T) {
++ 			got := compactionSplit(mk(tc.roles))
++ 			if got != tc.want {
++ 				t.Fatalf("compactionSplit = %d, want %d", got, tc.want)
++ 			}
++ 			if got >= 0 && mk(tc.roles)[got].Role != llm.RoleAssistant {
++ 				t.Error("the kept tail must start with an assistant message, or its tool_results reference nothing")
++ 			}
++ 		})
++ 	}
++ }
++ func TestCompactionFoldsHistoryAndKeepsTheTask(t *testing.T) {
++ 	// Six tool-calling turns, then a compaction, then the answer.
++ 	var script []string
++ 	for i := 0; i < 6; i++ {
++ 		script = append(script, msgWithTokens("tool_use", 100, toolUseBlock("tu", "boom", `{}`)))
++ 	}
++ 	script = append(script, msgWithTokens("end_turn", 100, textBlock("all done")))
++ 	f := newFakeAPI(t, script...)
++ 	var logBuf bytes.Buffer
++ 	a := newTestAgent(t, f, t.TempDir(), &logBuf)
++ 	a.opts.ContextWindow = 1000 // 70% of 1000, and each fake turn reports 100
++ 	a.opts.CompactAt = 0.1
++ 	var compacted int
++ 	a.Observe = func(ev Event) {
++ 		if ev.Kind == EventCompact {
++ 			compacted++
++ 		}
++ 	}
++ 	if _, err := a.Run(context.Background(), "fix the failing test in loop.go"); err != nil {
++ 		t.Fatalf("Run: %v", err)
++ 	}
++ 	if compacted == 0 {
++ 		t.Fatal("expected a compaction")
++ 	}
++ 	history := a.State().History()
++ 	if history[0].Role != llm.RoleUser {
++ 		t.Fatal("history must start with a user message")
++ 	}
++ 	folded := history[0].Content[0].Text
++ 	for _, want := range []string{"[Earlier conversation, compacted]", "fix the failing test in loop.go", "the config loads from X not Y"} {
++ 		if !strings.Contains(folded, want) {
++ 			t.Errorf("folded message missing %q:\n%s", want, folded)
++ 		}
++ 	}
++ 	if history[1].Role != llm.RoleAssistant {
++ 		t.Errorf("message after the summary is %q, want assistant", history[1].Role)
++ 	}
++ 	if !strings.Contains(logBuf.String(), `"type":"compaction"`) {
++ 		t.Error("compaction should be logged; it is a cost and cache event")
++ 	}
++ 	// The summarization call must not be able to touch the repository.
++ 	for i, req := range f.requests {
++ 		if len(req.Tools) == 0 && len(req.Messages) > 0 {
++ 			if req.MaxTokens != 4096 {
++ 				t.Errorf("request %d looks like the compaction call but has max_tokens %d", i, req.MaxTokens)
++ 			}
++ 		}
++ 	}
++ }
++ func TestStripTrailingToolUse(t *testing.T) {
++ 	msgs := []llm.Message{
++ 		{Role: llm.RoleUser, Content: []llm.ContentBlock{llm.TextBlock("go")}},
++ 		{Role: llm.RoleAssistant, Content: []llm.ContentBlock{{Type: llm.BlockToolUse, ID: "tu", Name: "x"}}},
++ 	}
++ 	if got := stripTrailingToolUse(msgs); len(got) != 1 {
++ 		t.Errorf("a dangling tool_use must be dropped, got %d messages", len(got))
++ 	}
++ 	keep := []llm.Message{
++ 		{Role: llm.RoleUser, Content: []llm.ContentBlock{llm.TextBlock("go")}},
++ 		{Role: llm.RoleAssistant, Content: []llm.ContentBlock{llm.TextBlock("done")}},
++ 	}
++ 	if got := stripTrailingToolUse(keep); len(got) != 2 {
++ 		t.Errorf("a text-only assistant turn should be kept, got %d", len(got))
++ 	}
++ }
++ func TestSupersedeStaleReads(t *testing.T) {
++ 	root := t.TempDir()
++ 	path := filepath.Join(root, "a.go")
++ 	os.WriteFile(path, []byte("package a\n\nconst X = 1\n"), 0o644)
++ 	f := newFakeAPI(t,
++ 		msg("tool_use", toolUseBlock("tu_1", "read_file", `{"path":"a.go"}`)),
++ 		msg("tool_use", toolUseBlock("tu_2", "read_file", `{"path":"a.go"}`)),
++ 		msg("tool_use", toolUseBlock("tu_3", "edit_file", `{"path":"a.go","old_str":"const X = 1","new_str":"const X = 2"}`)),
++ 		msg("end_turn", textBlock("done")),
++ 	)
++ 	var logBuf bytes.Buffer
++ 	a := newTestAgent(t, f, root, &logBuf)
++ 	if _, err := a.Run(context.Background(), "bump X"); err != nil {
++ 		t.Fatalf("Run: %v", err)
++ 	}
++ 	var superseded, intact int
++ 	for _, m := range a.State().History() {
++ 		for _, b := range m.Content {
++ 			if b.Type != llm.BlockToolResult {
++ 				continue
++ 			}
++ 			switch {
++ 			case strings.HasPrefix(b.Content, "[superseded:"):
++ 				superseded++
++ 			// Match the numbered read format, so the edit's own diff — which
++ 			// quotes the old line — is not counted as a surviving read.
++ 			case strings.Contains(b.Content, "\tconst X = 1"):
++ 				intact++
++ 			}
++ 		}
++ 	}
++ 	if superseded != 1 {
++ 		t.Errorf("%d results superseded, want 1 (the earlier of two reads)", superseded)
++ 	}
++ 	if intact != 1 {
++ 		t.Errorf("%d intact reads, want 1 (the most recent read stays)", intact)
++ 	}
++ 	if !strings.Contains(logBuf.String(), `"type":"supersede_reads"`) {
++ 		t.Error("superseding should be logged")
++ 	}
++ }
++ func TestSupersedeLeavesASingleReadAlone(t *testing.T) {
++ 	root := t.TempDir()
++ 	os.WriteFile(filepath.Join(root, "a.go"), []byte("package a\n\nconst X = 1\n"), 0o644)
++ 	f := newFakeAPI(t,
++ 		msg("tool_use", toolUseBlock("tu_1", "read_file", `{"path":"a.go"}`)),
++ 		msg("tool_use", toolUseBlock("tu_2", "edit_file", `{"path":"a.go","old_str":"const X = 1","new_str":"const X = 2"}`)),
++ 		msg("end_turn", textBlock("done")),
++ 	)
++ 	a := newTestAgent(t, f, root, &bytes.Buffer{})
++ 	if _, err := a.Run(context.Background(), "bump X"); err != nil {
++ 		t.Fatalf("Run: %v", err)
++ 	}
++ 	for _, m := range a.State().History() {
++ 		for _, b := range m.Content {
++ 			if strings.HasPrefix(b.Content, "[superseded:") {
++ 				t.Error("the only read of a file is still the current one; it must not be blanked")
++ 			}
++ 		}
++ 	}
++ }
++ func TestReadPathParsing(t *testing.T) {
++ 	if got := readPath(json.RawMessage(`{"path":"x/y.go","offset":3}`)); got != "x/y.go" {
++ 		t.Errorf("readPath = %q", got)
++ 	}
++ 	if got := readPath(json.RawMessage(`not json`)); got != "" {
++ 		t.Errorf("readPath = %q, want empty on malformed input", got)
++ 	}
++ }

+60−2internal/agent/loop.goView File

@@ -44,6 +44,12 @@ type Options struct {
44	44	System string
45	45	// Effort maps to output_config.effort. Empty means the API default (high).
46	46	Effort string
	47	+ // ContextWindow and CompactAt control when the conversation gets folded
	48	+ // into a summary. Zero means the defaults.
	49	+ ContextWindow int
	50	+ CompactAt float64
	51	+ // NoCache disables prompt cache breakpoints, for measuring what they buy.
	52	+ NoCache bool
47	53	}
48	54
49	55	// EventKind identifies what happened, for an observer to render.
@@ -55,6 +61,7 @@ const (
55	61	EventToolStart EventKind = "tool_start"
56	62	EventToolResult EventKind = "tool_result"
57	63	EventUsage EventKind = "usage"
	64	+ EventCompact EventKind = "compact"
58	65	)
59	66
60	67	// Event is what the loop reports to an observer. It carries plain data only —
@@ -80,6 +87,10 @@ type Agent struct {
80	87
81	88	// Observe is called for every event. It may be nil.
82	89	Observe func(Event)
	90	+
	91	+ // lastInputTokens is the size of the previous request as the API measured
	92	+ // it, cached and uncached parts together.
	93	+ lastInputTokens int
83	94	}
84	95
85	96	// New wires an agent. state and log may be freshly created by the caller so the
@@ -111,11 +122,19 @@ func (a *Agent) Run(ctx context.Context, prompt string) (string, error) {
111	122	for turn := 1; turn <= a.opts.MaxTurns; turn++ {
112	123	a.emit(Event{Kind: EventTurnStart, Turn: turn})
113	124
	125	+ // Compaction is checked before building the request, using the token
	126	+ // count the API reported last turn — free and exact, where counting
	127	+ // locally would be neither.
	128	+ if _, err := a.maybeCompact(ctx, a.lastInputTokens); err != nil {
	129	+ return "", err
	130	+ }
	131	+
114	132	resp, err := a.client.CreateMessage(ctx, a.request())
115	133	if err != nil {
116	134	return "", err
117	135	}
118	136	a.state.AddUsage(resp.Usage)
	137	+ a.lastInputTokens = resp.Usage.InputTokens + resp.Usage.CacheReadInputTokens + resp.Usage.CacheCreationInputTokens
119	138	a.log.Log(metrics.Event{
120	139	Type: "turn",
121	140	Turn: turn,
@@ -184,6 +203,18 @@ func (a *Agent) dispatch(ctx context.Context, turn int, calls []llm.ContentBlock
184	203	if isErr {
185	204	payload = err.Error()
186	205	}
	206	+ // A file that was just changed makes every earlier read of it wrong,
	207	+ // not merely stale. Blank those results rather than leave the model
	208	+ // reasoning from contents that no longer exist.
	209	+ if !isErr && (call.Name == "edit_file" \|\| call.Name == "write_file") {
	210	+ if p := editedPath(call.Input); p != "" {
	211	+ if n := a.state.SupersedeReads(p); n > 0 {
	212	+ a.log.Log(metrics.Event{Type: "supersede_reads", Tool: call.Name,
	213	+ Extra: map[string]any{"path": p, "results_blanked": n}})
	214	+ }
	215	+ }
	216	+ }
	217	+
187	218	results = append(results, llm.ToolResultBlock(call.ID, payload, isErr))
188	219	a.emit(Event{Kind: EventToolResult, Turn: turn, Tool: call.Name, Result: payload, IsError: isErr})
189	220	}
@@ -201,9 +232,25 @@ func (a *Agent) request() llm.Request {
201	232	InputSchema: t.InputSchema(),
202	233	})
203	234	}
	235	+ system := llm.SystemBlock{Type: "text", Text: a.opts.System}
	236	+ messages := a.state.History()
	237	+
	238	+ if !a.opts.NoCache {
	239	+ // Two breakpoints. The first caches the tools and system prompt, which
	240	+ // never change. The second rolls forward over the conversation each
	241	+ // turn, so every turn writes a small delta and reads a large prefix.
	242	+ system.CacheControl = llm.Ephemeral()
	243	+ if n := len(messages); n > 0 {
	244	+ if blocks := messages[n-1].Content; len(blocks) > 0 {
	245	+ messages[n-1].Content = append([]llm.ContentBlock(nil), blocks...)
	246	+ messages[n-1].Content[len(blocks)-1].CacheControl = llm.Ephemeral()
	247	+ }
	248	+ }
	249	+ }
	250	+
204	251	req := llm.Request{
205		- System: []llm.SystemBlock{{Type: "text", Text: a.opts.System}},
206		- Messages: a.state.History(),
	252	+ System: []llm.SystemBlock{system},
	253	+ Messages: messages,
207	254	Tools: defs,
208	255	Thinking: llm.Adaptive(),
209	256	}
@@ -213,6 +260,17 @@ func (a *Agent) request() llm.Request {
213	260	return req
214	261	}
215	262
	263	+ // editedPath pulls the path out of an edit_file or write_file call.
	264	+ func editedPath(input json.RawMessage) string {
	265	+ var args struct {
	266	+ Path string `json:"path"`
	267	+ }
	268	+ if json.Unmarshal(input, &args) != nil {
	269	+ return ""
	270	+ }
	271	+ return args.Path
	272	+ }
	273	+
216	274	func refusalError(resp *llm.Response) error {
217	275	var b strings.Builder
218	276	b.WriteString("the model declined this request")

+40−4internal/agent/loop_test.goView File

@@ -10,6 +10,7 @@ import (
10	10	"net/http/httptest"
11	11	"os"
12	12	"path/filepath"
	13	+ "strconv"
13	14	"strings"
14	15	"testing"
15	16
@@ -24,11 +25,29 @@ type fakeAPI struct {
24	25	t *testing.T
25	26	responses []string
26	27	requests []llm.Request
	28	+ summary string
27	29	srv *httptest.Server
28	30	}
29	31
	32	+ // compactions counts requests that were summarization calls, so they do not
	33	+ // consume scripted responses.
	34	+ func (f *fakeAPI) compactions() int {
	35	+ var n int
	36	+ for _, req := range f.requests {
	37	+ if len(req.Messages) > 0 {
	38	+ last := req.Messages[len(req.Messages)-1]
	39	+ for _, b := range last.Content {
	40	+ if strings.Contains(b.Text, "Summarize the conversation above") {
	41	+ n++
	42	+ }
	43	+ }
	44	+ }
	45	+ }
	46	+ return n
	47	+ }
	48	+
30	49	func newFakeAPI(t testing.T, responses ...string) fakeAPI {
31		- f := &fakeAPI{t: t, responses: responses}
	50	+ f := &fakeAPI{t: t, responses: responses, summary: "Compacted: edited loop.go, the config loads from X not Y."}
32	51	f.srv = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
33	52	body, _ := io.ReadAll(r.Body)
34	53	var req llm.Request
@@ -36,7 +55,11 @@ func newFakeAPI(t testing.T, responses ...string) fakeAPI {
36	55	t.Errorf("harness sent a body the API types cannot parse: %v\n%s", err, body)
37	56	}
38	57	f.requests = append(f.requests, req)
39		- i := len(f.requests) - 1
	58	+ if bytes.Contains(body, []byte("Summarize the conversation above")) {
	59	+ io.WriteString(w, msg("end_turn", textBlock(f.summary)))
	60	+ return
	61	+ }
	62	+ i := len(f.requests) - 1 - f.compactions()
40	63	if i >= len(f.responses) {
41	64	t.Errorf("harness made %d requests, script only has %d", i+1, len(f.responses))
42	65	w.WriteHeader(http.StatusInternalServerError)
@@ -65,6 +88,13 @@ func msg(stopReason string, blocks ...string) string {
65	88
66	89	func textBlock(s string) string { return `{"type":"text","text":"` + s + `"}` }
67	90
	91	+ // msgWithTokens is msg with a controllable input_tokens, for driving compaction.
	92	+ func msgWithTokens(stopReason string, inputTokens int, blocks ...string) string {
	93	+ return `{"id":"msg","type":"message","role":"assistant","model":"claude-opus-5","content":[` +
	94	+ strings.Join(blocks, ",") + `],"stop_reason":"` + stopReason + `",` +
	95	+ `"usage":{"input_tokens":` + strconv.Itoa(inputTokens) + `,"output_tokens":20}}`
	96	+ }
	97	+
68	98	func toolUseBlock(id, name, input string) string {
69	99	return `{"type":"tool_use","id":"` + id + `","name":"` + name + `","input":` + input + `}`
70	100	}
@@ -77,6 +107,8 @@ func newTestAgent(t testing.T, f fakeAPI, root string, logBuf bytes.Buffer)
77	107	state := NewState()
78	108	reg := tools.NewRegistry(log).Register(
79	109	tools.NewRead(root, state),
	110	+ tools.NewEdit(root, state),
	111	+ tools.NewWrite(root, state),
80	112	tools.New("boom", "Always fails", func(context.Context, struct{}) (string, error) {
81	113	return "", errors.New("detonated")
82	114	}),
@@ -222,8 +254,12 @@ func TestRequestShape(t *testing.T) {
222	254	if req.Thinking == nil \|\| req.Thinking.Type != "adaptive" {
223	255	t.Errorf("thinking = %+v, want adaptive (budget_tokens is a 400 on current models)", req.Thinking)
224	256	}
225		- if len(req.Tools) != 2 \|\| req.Tools[0].Name != "boom" \|\| req.Tools[1].Name != "read_file" {
226		- t.Errorf("tools = %+v, want them sorted for a byte-stable prefix", req.Tools)
	257	+ var names []string
	258	+ for _, tl := range req.Tools {
	259	+ names = append(names, tl.Name)
	260	+ }
	261	+ if want := "boom, edit_file, read_file, write_file"; strings.Join(names, ", ") != want {
	262	+ t.Errorf("tools = %v, want them sorted for a byte-stable prefix (%s)", names, want)
227	263	}
228	264	for _, tl := range req.Tools {
229	265	if len(tl.InputSchema) == 0 {

+69−0internal/agent/state.goView File

@@ -5,6 +5,8 @@
5	5	package agent
6	6
7	7	import (
	8	+ "encoding/json"
	9	+ "strings"
8	10	"sync"
9	11	"time"
10	12
@@ -51,6 +53,73 @@ func (s *State) Append(m llm.Message) {
51	53	s.messages = append(s.messages, m)
52	54	}
53	55
	56	+ // Replace swaps the whole history, which is how compaction lands.
	57	+ func (s *State) Replace(msgs []llm.Message) {
	58	+ s.mu.Lock()
	59	+ defer s.mu.Unlock()
	60	+ s.messages = append([]llm.Message(nil), msgs...)
	61	+ }
	62	+
	63	+ // SupersedeReads blanks the results of every read_file call for path except the
	64	+ // most recent one. A file read twenty turns ago and edited since is not merely
	65	+ // wasted context — it is wrong, and the model will reason from it.
	66	+ func (s *State) SupersedeReads(path string) int {
	67	+ s.mu.Lock()
	68	+ defer s.mu.Unlock()
	69	+
	70	+ // Collect the tool_use ids of every read of this path, in order.
	71	+ var ids []string
	72	+ for _, m := range s.messages {
	73	+ if m.Role != llm.RoleAssistant {
	74	+ continue
	75	+ }
	76	+ for _, b := range m.Content {
	77	+ if b.Type == llm.BlockToolUse && b.Name == "read_file" && readPath(b.Input) == path {
	78	+ ids = append(ids, b.ID)
	79	+ }
	80	+ }
	81	+ }
	82	+ if len(ids) <= 1 {
	83	+ return 0
	84	+ }
	85	+ stale := map[string]bool{}
	86	+ for _, id := range ids[:len(ids)-1] {
	87	+ stale[id] = true
	88	+ }
	89	+
	90	+ var n int
	91	+ for i, m := range s.messages {
	92	+ if m.Role != llm.RoleUser {
	93	+ continue
	94	+ }
	95	+ for j, b := range m.Content {
	96	+ if b.Type != llm.BlockToolResult \|\| !stale[b.ToolUseID] {
	97	+ continue
	98	+ }
	99	+ if strings.HasPrefix(b.Content, stalePrefix) {
	100	+ continue
	101	+ }
	102	+ s.messages[i].Content[j].Content = stalePrefix + path +
	103	+ " has been modified since this read. The contents shown here are out of date; read it again if you need them.]"
	104	+ n++
	105	+ }
	106	+ }
	107	+ return n
	108	+ }
	109	+
	110	+ const stalePrefix = "[superseded: "
	111	+
	112	+ // readPath pulls the path argument out of a read_file call.
	113	+ func readPath(input json.RawMessage) string {
	114	+ var args struct {
	115	+ Path string `json:"path"`
	116	+ }
	117	+ if json.Unmarshal(input, &args) != nil {
	118	+ return ""
	119	+ }
	120	+ return args.Path
	121	+ }
	122	+
54	123	// History returns a copy of the conversation so far.
55	124	func (s *State) History() []llm.Message {
56	125	s.mu.Lock()

+6−0internal/llm/types.goView File

@@ -64,6 +64,9 @@ type ContentBlock struct {
64	64	Content string `json:"content,omitempty"`
65	65	IsError bool `json:"is_error,omitempty"`
66	66
	67	+ // CacheControl marks this block as a cache breakpoint.
	68	+ CacheControl *CacheControl `json:"cache_control,omitempty"`
	69	+
67	70	// raw holds the original bytes of a block type this struct does not model,
68	71	// so an unfamiliar block still round-trips instead of being flattened away.
69	72	raw json.RawMessage
@@ -127,6 +130,9 @@ func (b ContentBlock) MarshalJSON() ([]byte, error) {
127	130	}
128	131	return nil, fmt.Errorf("llm: cannot marshal unknown content block %q", b.Type)
129	132	}
	133	+ if b.CacheControl != nil {
	134	+ m["cache_control"] = b.CacheControl
	135	+ }
130	136	return json.Marshal(m)
131	137	}
132	138

+2−0internal/ui/render.goView File

@@ -44,6 +44,8 @@ func (r *Renderer) Handle(ev agent.Event) {
44	44	fmt.Fprintf(r.W, "%s⏺ %s%s%s(%s)%s\n", color.cyan, color.bold, ev.Tool, color.reset, summarizeInput(ev.Input), color.reset)
45	45	case agent.EventToolResult:
46	46	r.tool(ev)
	47	+ case agent.EventCompact:
	48	+ fmt.Fprintf(r.W, "%s[compacted the conversation]%s\n", color.dim, color.reset)
47	49	}
48	50	}
49	51