refactor(agent): context boundary detection, proactive budget check, and safe compression

[is-Xiaoen]

Summary

Addresses track 6 of the agent refactor (#1439): context management boundaries, compression triggers, and token budgeting.

This PR fixes four concrete problems in the current context management:

1. ContextWindow defaults to MaxTokens — conflates input capacity with output generation limit, causing premature summarization or missed compression triggers (fix(agent): decouple context_window from max_tokens #556)
2. forceCompression can orphan tool pairs — slices at len/2 without checking whether the cut falls inside an assistant+ToolCalls → tool_result sequence (fix(agent): prevent history compression from orphaning tool_call/tool_result pairs #665)
3. forceCompression assumes history[0] is a system prompt — session history only stores user/assistant/tool messages; the system prompt is built dynamically by BuildMessages. The old code incorrectly skipped the first user message and appended a compression note to it.
4. Compression is reactive only — forceCompression runs after the LLM already rejected the request with a 400, wasting a billed call
5. Token estimation undercounts — estimateTokens only counted m.Content, ignoring ToolCalls arguments, ReasoningContent, and Media items

Changes

New file: docs/agent-refactor/context.md

Design document for Track 6, as called for in the agent-refactor README (suggested document split, item 5: "context scope, history, summary, compression"). Documents:

• Context window region definitions and history budget formula
• ContextWindow vs MaxTokens distinction
• Session history contents (no system prompt stored)
• Turn as the atomic compression unit ([Agent refactor] Event-driven agent loop with hooks, interrupts, and steering #1316)
• Three compression paths and their ordering
• Token estimation approach and limitations
• Interface boundaries between budget functions and BuildMessages
• Known gaps

New file: pkg/agent/context_budget.go

Uses the Turn concept from the agent refactor design (#1316) as the atomic unit for compression. A Turn is a complete "user input → LLM iterations → final response" cycle.

• parseTurnBoundaries(history) — identifies each Turn start index in the session history
• isSafeBoundary(history, index) — checks whether an index is at a Turn boundary
• findSafeBoundary(history, targetIndex) — finds the nearest Turn boundary to a target index (prefers backward to keep more recent context)
• estimateMessageTokens(msg) — counts Content + ReasoningContent + ToolCalls (ID, type, name, arguments) + ToolCallID + Media items with 2.5 chars/token heuristic
• estimateToolDefsTokens(defs) — estimates token cost of tool definitions (name + description + JSON schema)
• isOverContextBudget(contextWindow, messages, toolDefs, maxTokens) — proactive budget check

All are pure functions with no AgentLoop dependency — forward-compatible with the agent refactor.

pkg/agent/loop.go

• Proactive budget check (step 1.5 in runAgentLoop): before calling the LLM, estimate total token cost of assembled messages + tool definitions + output reserve. If over budget, run forceCompression and rebuild messages. The reactive path stays as a fallback for estimation undershoots.
• forceCompression: rewritten to drop the oldest half of Turns (not arbitrary messages). Uses parseTurnBoundaries to find Turn-aligned cut points. Fixed to work with actual session data (no system prompt in history). Compression note goes into session summary, not into history messages.
• summarizeSession: use findSafeBoundary to align cut to nearest Turn boundary instead of hardcoded history[:len-4]
• estimateTokens: delegate to estimateMessageTokens — counts ToolCalls, ReasoningContent, Media, not just Content

pkg/agent/instance.go

• Resolve ContextWindow independently from MaxTokens with a 4x heuristic default. This gives 131K for the default 32K max_tokens — reasonable for modern models. The reactive forceCompression handles any overshoot.

pkg/config/config.go

• Add context_window field to AgentDefaults (with env var PICOCLAW_AGENTS_DEFAULTS_CONTEXT_WINDOW)

config/config.example.json

• Add context_window field with default 131072

Web UI (web/frontend/)

• Add context_window input field to the configuration page (form model, section, save handler)
• Add i18n strings (en/zh). Optional field — leaving it empty falls back to the 4x heuristic.

Design decisions

• Turn as the atomic unit — compression operates on complete Turns ([Agent refactor] Event-driven agent loop with hooks, interrupts, and steering #1316), not individual messages. parseTurnBoundaries identifies Turn starts; forceCompression drops "the oldest half of Turns." This naturally prevents splitting tool-call sequences since each Turn is atomic.
• Pure functions, no new types — follows the refactor's "minimum concepts" rule. No ContextBudget struct, no ContextManager interface.
• Compression note in summary, not history — session history stores only real conversation messages. The compression note goes into the session summary, which BuildMessages already injects into the system prompt. This avoids corrupting the stored history.
• 4x heuristic for default context_window — conservative lower bound. A follow-up improvement could auto-detect from the provider, but the reactive path covers any mismatch.
• No dependency on other refactor tracks — operates on []providers.Message and integer token counts. Independent of agent abstraction ([Agent refactor]what an Agent is #1218), event model ([Agent refactor] Event-driven agent loop with hooks, interrupts, and steering #1316), or capability model.

Issue mapping

Proposal in #1439	Status
A. Separate context_window from max_tokens	Done
B. Explicit history budget	Partial — proactive pre-call check uses full formula (messages + tool defs + output reserve); maybeSummarize still uses history-only percentage threshold against the now-correct ContextWindow base. Full budget-aware summarization trigger is a follow-up.
C. Proactive pre-call check	Done
D. Tool-pair-aware truncation	Done — Turn-based, aligned with #1316
E. ToolCalls in token estimation	Done (+ ReasoningContent, Media)

Test plan

• 54 test cases in context_budget_test.go covering all pure functions
• parseTurnBoundaries tests: simple exchange, tool calls, chained tools, no user messages, leading non-user
• Realistic session-shaped tests (no system in history, chained tools, reasoning content, media)
• Single-Turn regression: findSafeBoundary returns 0 when only one Turn exists
• Context retry integration test with realistic session data (no system message in history)
• go build ./pkg/... — no compilation errors
• golangci-lint run — no new lint issues
• No changes to session storage format or API signatures — backward compatible

Closes #556
Closes #665
Ref #1439

cc @alexhoshina @yinwm

[alexhoshina]

hi @is-Xiaoen, I've looked at this PR and have a simple idea.
In #1316, we used the concept of a Turn to define a complete iteration of the agent. Could we use the Turn as a cut-off point? Would using the Turn as a cut-off point be simpler and more intuitive than heuristic searching?

[is-Xiaoen]

Good call — using the Turn as the atomic unit is cleaner than the raw heuristic scan. I've updated the implementation:

New function: parseTurnBoundaries(history)

Returns the starting index of each Turn in the session history. A Turn begins at a user message and extends through all subsequent assistant/tool messages until the next user message — matching the Turn definition from #1316.

How it's used:

• findSafeBoundary now uses parseTurnBoundaries internally to locate the nearest Turn boundary, instead of scanning for Role == "user" directly. Same result, but the intent is explicit.

• forceCompression drops the oldest half of Turns (not arbitrary messages):

turns := parseTurnBoundaries(history)
if len(turns) >= 2 {
    mid = turns[len(turns)/2]  // drop oldest half of Turns
}

This reads as "drop the oldest N Turns" rather than "find nearest user message to midpoint" — simpler and self-documenting.

The Turn-based approach also naturally handles chained tool calls within a single Turn (user → assistantTC → tool → assistantTC → tool → assistant), since the entire chain lives inside one Turn and is never split.

See commit 4eaa2ec for the full change.

[is-Xiaoen]

@alexhoshina Saw your mention in #1218 about combining this with the new context builder. I've added docs/agent-refactor/context.md covering the context window regions, Turn as the compression unit, how the three compression paths relate, and the interface boundaries between budget functions and the builder — should make alignment easier going forward.

The budget-related functions (parseTurnBoundaries, isOverContextBudget,etc.) are all pure — they take []providers.Message and int parameters with no AgentLoop dependency, so the new builder can call them directly without
interface changes. Remaining gaps (e.g. budget-aware summarization trigger) are documented in context.md and can be followed up once the builder direction stabilizes.

If anything needs adjusting to better fit the architecture you have in mind — how the proactive check integrates, the Turn boundary detection logic, interface signatures — happy to iterate. Will rebase onto refactor/agent once the branch is up.

[is-Xiaoen]

Rebased onto refactor/agent now that the branch is up — sits cleanly on top of steering (#1517), no conflicts. Updated the PR base branch accordingly.

CI should stay green. Ready for review when you get a chance.

[afjcjsbx]

If an LLM or user generates a single massive message (or a massive tool response) that exceeds the context window on its own, the entire history is technically a single "Turn" (index 0). findSafeBoundary will correctly identify that there are no safe boundaries to split the sequence and return 0. By aborting compression entirely, the agent gets permanently stuck in a "Context Window Exceeded" loop because it can never shrink the context.
If a Turn boundary cannot be found, we might think about fall back to a hard split to ensure the system can recover, or return the context to the initial empty state. WDYT??

[is-Xiaoen]

Good catch — you're right, the agent would get stuck retrying if a single Turn exceeds the window.

Fixed in c63c644: when mid <= 0 (no safe Turn boundary), forceCompression now falls back to keeping only the most recent user message. This breaks Turn atomicity as a last resort, but guarantees recovery instead of looping.

The reactive path needs this especially since it passes "" for UserMessage when rebuilding — without at least the latest user message in history, the LLM would get no user context at all.

@afjcjsbx thanks for the review!

[afjcjsbx]

I reviewed the PR and I like both the ideas and the clear and clean implementation, I left you a note, but for me we can merge, thank you!