Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.
Go agentagenticaichatbotdsh-pluginembeddingsevaluationgenerative-aigolangknowledge-basellmmulti-tenantollamaopenaiquestion-answeringragrerankingsemantic-searchvector-searchwiki
feat(agent): persist compaction checkpoints across turns (#3407)
lyingbug62f7da5eea3c
diff --git a/internal/agent/checkpoint.go b/internal/agent/checkpoint.gonew file mode 100644index 000000000..8b256a738--- /dev/null+++ b/internal/agent/checkpoint.go@@ -0,0 +1,36 @@+package agent++import (+ "context"+ "time"++ "github.com/Tencent/WeKnora/internal/agent/compaction"+ "github.com/Tencent/WeKnora/internal/logger"+ "github.com/Tencent/WeKnora/internal/types"+)++// SetContextCheckpointSink enables persisting compaction checkpoints. Nil (the+// default) keeps every compaction local to the turn that ran it.+func (e *AgentEngine) SetContextCheckpointSink(sink types.ContextCheckpointSink) {+ e.checkpointSink = sink+}++// saveContextCheckpoint writes a compaction that ends on a stored turn onto+// that turn. Best-effort: a failed write costs the next turn one more+// summarization, never this turn anything.+func (e *AgentEngine) saveContextCheckpoint(ctx context.Context, cp *compaction.Checkpoint, round int) {+ if cp == nil || e.checkpointSink == nil {+ return+ }+ err := e.checkpointSink.SaveContextCheckpoint(ctx, cp.TurnID, &types.ContextCheckpoint{+ Summary: cp.Summary,+ CreatedAt: time.Now(),+ })+ if err != nil {+ logger.Warnf(ctx, "[Agent][Round-%d] Failed to save context checkpoint on turn %s: %v",+ round, cp.TurnID, err)+ return+ }+ logger.Infof(ctx, "[Agent][Round-%d] Saved context checkpoint through turn %s (%d chars)",+ round, cp.TurnID, len(cp.Summary))+}diff --git a/internal/agent/compaction/checkpoint_test.go b/internal/agent/compaction/checkpoint_test.gonew file mode 100644index 000000000..65096556d--- /dev/null+++ b/internal/agent/compaction/checkpoint_test.go@@ -0,0 +1,164 @@+package compaction++import (+ "context"+ "testing"++ "github.com/Tencent/WeKnora/internal/models/chat"+ "github.com/stretchr/testify/assert"+ "github.com/stretchr/testify/require"+)++// storedTurn is a turn replayed from the database: every message carries the+// ID of the assistant message that closes it.+func storedTurn(id string, rounds int, path string) []chat.Message {+ msgs := []chat.Message{{Role: "user", Content: "question " + id}}+ for i := 0; i < rounds; i++ {+ callID := id + "-call-" + string(rune('a'+i%26))+ msgs = append(msgs,+ chat.Message{+ Role: "assistant",+ Content: filler(20),+ ToolCalls: []chat.ToolCall{{+ ID: callID,+ Type: "function",+ Function: chat.FunctionCall{+ Name: "write_sandbox_file",+ Arguments: `{"path":"` + path + `","content":"` + filler(40) + `"}`,+ },+ }},+ },+ chat.Message{Role: "tool", Name: "write_sandbox_file", ToolCallID: callID, Content: filler(30)},+ )+ }+ msgs = append(msgs, chat.Message{Role: "assistant", Content: "answer " + id})+ for i := range msgs {+ msgs[i].TurnID = id+ }+ return msgs+}++// withStoredHistory puts stored turns between the system prompt and the live+// turn, the way the engine assembles a request.+func withStoredHistory(live []chat.Message, turns ...[]chat.Message) []chat.Message {+ out := []chat.Message{live[0]}+ for _, turn := range turns {+ out = append(out, turn...)+ }+ return append(out, live[1:]...)+}++// The common case: the live turn outgrows the budget, so every stored turn is+// summarized and the cut splits the live turn. The history part ends on the+// last stored turn and can stand in for it later; the live turn's prefix+// cannot, because that turn will be replayed verbatim once it is stored.+func TestCheckpointEndsOnTheLastStoredTurn(t *testing.T) {+ llm := &stubChat{response: "## Goal\nsummary"}+ c := New(llm, newEstimator(t), testSettings())++ msgs := withStoredHistory(reactTurn(12),+ storedTurn("turn-a", 1, "/workspace/a.txt"),+ storedTurn("turn-b", 1, "/workspace/b.txt"))+ result, err := c.Compact(context.Background(), msgs, ReasonThreshold)+ require.NoError(t, err)+ require.True(t, result.SplitTurn)++ require.NotNil(t, result.Checkpoint)+ assert.Equal(t, "turn-b", result.Checkpoint.TurnID)+ assert.Contains(t, result.Summary, "Turn Context (split turn)")+ assert.NotContains(t, result.Checkpoint.Summary, "Turn Context (split turn)",+ "the live turn's prefix must not outlive the turn")+ assert.Contains(t, result.Checkpoint.Summary, "/workspace/b.txt")+ assert.NotContains(t, result.Checkpoint.Summary, "/workspace/out.html",+ "files touched only by the live turn belong to its own replay")+}++// A cut that splits a stored turn still ends the history part on the turn+// before it. The split turn's prefix is summarized for this request only; the+// next request replays that turn whole.+func TestCheckpointStopsBeforeASplitStoredTurn(t *testing.T) {+ c := New(&stubChat{response: "## Goal\nsummary"}, newEstimator(t), testSettings())++ live := []chat.Message{{Role: "system", Content: "you are an agent"}, {Role: "user", Content: "next"}}+ msgs := withStoredHistory(live,+ storedTurn("turn-a", 1, "/workspace/a.txt"),+ storedTurn("turn-b", 12, "/workspace/b.txt"))+ result, err := c.Compact(context.Background(), msgs, ReasonThreshold)+ require.NoError(t, err)+ require.True(t, result.SplitTurn)++ require.NotNil(t, result.Checkpoint)+ assert.Equal(t, "turn-a", result.Checkpoint.TurnID)+ assert.NotContains(t, result.Checkpoint.Summary, "/workspace/b.txt")+}++// A steered message opens a compaction turn but not a stored one. Cutting+// there summarizes half of a stored turn as history, which no stored boundary+// describes, so nothing is persisted.+func TestNoCheckpointWhenHistoryEndsInsideAStoredTurn(t *testing.T) {+ c := New(&stubChat{response: "## Goal\nsummary"}, newEstimator(t), testSettings())++ turn := []chat.Message{+ {Role: "user", Content: "question"},+ {Role: "assistant", ToolCalls: []chat.ToolCall{{+ ID: "call-1", Type: "function",+ Function: chat.FunctionCall{Name: "read_file", Arguments: `{"path":"/workspace/big.txt"}`},+ }}},+ {Role: "tool", Name: "read_file", ToolCallID: "call-1", Content: filler(800)},+ {Role: "user", Content: "steered: also check the footer"},+ {Role: "assistant", Content: "done"},+ }+ for i := range turn {+ turn[i].TurnID = "turn-a"+ }+ live := []chat.Message{{Role: "system", Content: "you are an agent"}, {Role: "user", Content: "next"}}++ result, err := c.Compact(context.Background(), withStoredHistory(live, turn), ReasonThreshold)+ require.NoError(t, err)+ require.False(t, result.SplitTurn, "the steered message is where the cut lands")+ assert.Nil(t, result.Checkpoint)+}++func TestNoCheckpointForALiveTurnOnly(t *testing.T) {+ c := New(&stubChat{response: "## Goal\nsummary"}, newEstimator(t), testSettings())++ result, err := c.Compact(context.Background(), reactTurn(12), ReasonThreshold)+ require.NoError(t, err)+ assert.Nil(t, result.Checkpoint, "nothing stored was summarized")+}++// A raw archive is a stopgap for the request that needed it. Persisting it+// would make every later turn carry the archive instead of retrying the+// summarizer.+func TestNoCheckpointFromADegradedSummary(t *testing.T) {+ c := New(&stubChat{err: assert.AnError}, newEstimator(t), testSettings())++ msgs := withStoredHistory(reactTurn(12), storedTurn("turn-a", 1, "/workspace/a.txt"))+ result, err := c.Compact(context.Background(), msgs, ReasonThreshold)+ require.NoError(t, err)+ require.True(t, result.Degraded)+ assert.Nil(t, result.Checkpoint)+}++// History loaded from a checkpoint starts with that summary. The next+// checkpoint must fold it in, including the files it recorded, or everything+// before the loaded turns is lost the moment a new checkpoint replaces it.+func TestCheckpointCarriesTheLoadedSummaryForward(t *testing.T) {+ llm := &stubChat{response: "## Goal\nupdated"}+ c := New(llm, newEstimator(t), testSettings())++ loaded := SummaryMessage("## Goal\nearlier work" + fileOps{written: []string{"/workspace/old.txt"}}.format())+ live := reactTurn(12)+ msgs := append([]chat.Message{live[0], loaded}, storedTurn("turn-c", 1, "/workspace/c.txt")...)+ msgs = append(msgs, live[1:]...)++ result, err := c.Compact(context.Background(), msgs, ReasonThreshold)+ require.NoError(t, err)++ require.NotNil(t, result.Checkpoint)+ assert.Equal(t, "turn-c", result.Checkpoint.TurnID)+ assert.Contains(t, llm.prompts[0], "<previous-summary>")+ assert.Contains(t, llm.prompts[0], "earlier work")+ assert.Contains(t, result.Checkpoint.Summary, "/workspace/old.txt")+ assert.Contains(t, result.Checkpoint.Summary, "/workspace/c.txt")+}diff --git a/internal/agent/compaction/compactor.go b/internal/agent/compaction/compactor.goindex 5cf174afd..4be437dfa 100644--- a/internal/agent/compaction/compactor.go+++ b/internal/agent/compaction/compactor.go@@ -59,6 +59,18 @@ type Result struct {// SplitTurn reports that the cut divided a single turn, so a turn-prefix// summary was generated alongside the history summary.SplitTurn bool+ // Checkpoint is the part of this compaction a later turn can start from,+ // or nil when there is none (see Preparation.checkpoint).+ Checkpoint *Checkpoint+}++// Checkpoint is a summary that ends exactly on a stored turn. Persisted onto+// that turn, it lets the next turn load the summary in place of everything up+// to and including the turn, instead of summarizing the same history again.+type Checkpoint struct {+ // TurnID is the stored turn the summary covers through, inclusive.+ TurnID string+ Summary string}// Freed is how much room the compaction actually recovered. A non-positive@@ -104,7 +116,8 @@ func (c *Compactor) Compact(return nil, ErrNothingToCompact}- summary, degraded := c.buildSummary(ctx, prep)+ history, historyDegraded := c.summarizeHistory(ctx, prep)+ summary, prefixDegraded := c.appendTurnPrefix(ctx, prep, history)summary += prep.fileOps.format()compacted := Apply(messages, prep, summary)@@ -116,51 +129,52 @@ func (c *Compactor) Compact(TokensAfter: c.estimator.EstimateMessages(compacted),MessagesBefore: len(messages),MessagesAfter: len(compacted),- Degraded: degraded,+ Degraded: historyDegraded || prefixDegraded,SplitTurn: prep.IsSplitTurn,+ Checkpoint: prep.checkpoint(history, historyDegraded),}, nil}-// buildSummary produces the checkpoint text, falling back to a raw archive for-// any part the summarizer could not produce.-func (c *Compactor) buildSummary(ctx context.Context, p *Preparation) (string, bool) {- degraded := false-- history := p.PreviousSummary- if len(p.MessagesToSummarize) > 0 {- instructions := initialSummarizationInstructions- if p.PreviousSummary != "" {- instructions = updateSummarizationInstructions- }- text, err := c.summarize(- ctx, p.MessagesToSummarize, p.PreviousSummary, instructions, c.settings.summaryBudget(),- )- if err != nil {- degraded = true- // The previous summary is still the best record of everything- // before this span, so the archive is appended to it rather than- // replacing it.- history = joinNonEmpty(p.PreviousSummary, rawArchive(p.MessagesToSummarize))- } else {- history = text- }+// summarizeHistory folds the complete turns being dropped into the previous+// summary, falling back to a raw archive when the summarizer fails.+func (c *Compactor) summarizeHistory(ctx context.Context, p *Preparation) (string, bool) {+ if len(p.MessagesToSummarize) == 0 {+ return p.PreviousSummary, false}-- if p.IsSplitTurn && len(p.TurnPrefixMessages) > 0 {- prefix, err := c.summarize(- ctx, p.TurnPrefixMessages, "", turnPrefixInstructions, c.settings.turnPrefixBudget(),- )- if err != nil {- degraded = true- prefix = rawArchive(p.TurnPrefixMessages)- }- if history == "" {- history = "No prior history."- }- history += splitTurnSeparator + prefix+ instructions := initialSummarizationInstructions+ if p.PreviousSummary != "" {+ instructions = updateSummarizationInstructions}+ text, err := c.summarize(+ ctx, p.MessagesToSummarize, p.PreviousSummary, instructions, c.settings.summaryBudget(),+ )+ if err != nil {+ // The previous summary is still the best record of everything+ // before this span, so the archive is appended to it rather than+ // replacing it.+ return joinNonEmpty(p.PreviousSummary, rawArchive(p.MessagesToSummarize)), true+ }+ return text, false+}- return history, degraded+// appendTurnPrefix adds the summary of a split turn's discarded head, so the+// retained tail still has its originating request.+func (c *Compactor) appendTurnPrefix(ctx context.Context, p *Preparation, history string) (string, bool) {+ if !p.IsSplitTurn || len(p.TurnPrefixMessages) == 0 {+ return history, false+ }+ degraded := false+ prefix, err := c.summarize(+ ctx, p.TurnPrefixMessages, "", turnPrefixInstructions, c.settings.turnPrefixBudget(),+ )+ if err != nil {+ degraded = true+ prefix = rawArchive(p.TurnPrefixMessages)+ }+ if history == "" {+ history = "No prior history."+ }+ return history + splitTurnSeparator + prefix, degraded}// summarize runs one summarization call with retries.diff --git a/internal/agent/compaction/prepare.go b/internal/agent/compaction/prepare.goindex 3a2808f29..a3f16685a 100644--- a/internal/agent/compaction/prepare.go+++ b/internal/agent/compaction/prepare.go@@ -33,6 +33,9 @@ type Preparation struct {PreviousSummary stringTokensBefore intfileOps fileOps+ // storedTurnID is the stored turn MessagesToSummarize ends exactly on, or+ // "" when it ends inside a turn or reaches into the live one.+ storedTurnID string}// Prepare picks the cut point and collects the message ranges around it.@@ -89,9 +92,44 @@ func Prepare(messages []chat.Message, s Settings, estimator *agenttoken.EstimatoPreviousSummary: previousSummary,TokensBefore: estimator.EstimateMessages(messages),fileOps: extractFileOps(previousSummary, toSummarize, turnPrefix),+ storedTurnID: storedTurnEndingAt(messages, historyEnd),}}+// checkpoint returns the history summary as a Checkpoint when it ends exactly+// on a stored turn. The turn-prefix summary is left out: it describes part of a+// turn the next turn replays verbatim. Nothing newly summarized means the+// previous checkpoint still stands, and a raw archive is not worth keeping+// past the turn that needed it — the next turn retries the summarizer instead.+func (p *Preparation) checkpoint(history string, degraded bool) *Checkpoint {+ if p.storedTurnID == "" || len(p.MessagesToSummarize) == 0 || degraded {+ return nil+ }+ ops := extractFileOps(p.PreviousSummary, p.MessagesToSummarize)+ return &Checkpoint{TurnID: p.storedTurnID, Summary: history + ops.format()}+}++// storedTurnEndingAt returns the stored turn that ends immediately before end,+// or "" if the message there is live or the same turn continues past end.+//+// Stored history always precedes the live turn, so a tagged message just+// before end means everything since the previous summary is stored history+// too, and the previous summary itself covered nothing live: a cut inside the+// live turn leaves only live messages after it.+func storedTurnEndingAt(messages []chat.Message, end int) string {+ if end <= 0 || end > len(messages) {+ return ""+ }+ turnID := messages[end-1].TurnID+ if turnID == "" {+ return ""+ }+ if end < len(messages) && messages[end].TurnID == turnID {+ return ""+ }+ return turnID+}+// Apply rebuilds the message list as system prompt, summary, and the verbatim// tail. Nothing between the system prompt and the cut point survives.func Apply(messages []chat.Message, p *Preparation, summary string) []chat.Message {diff --git a/internal/agent/engine.go b/internal/agent/engine.goindex 2baa773e4..4e30df2c8 100644--- a/internal/agent/engine.go+++ b/internal/agent/engine.go@@ -61,7 +61,10 @@ type AgentEngine struct {// reported it could free nothing. Below that count the answer has not// changed, so there is no reason to spend another summarization call.compactionExhaustedAt int- modelContext *modelcontext.Registry // single request-local boundary for every model handle+ // checkpointSink, when set, persists compactions that end on a stored+ // turn so later turns start from them. Nil keeps compaction turn-local.+ checkpointSink types.ContextCheckpointSink+ modelContext *modelcontext.Registry // single request-local boundary for every model handle// steerSink, when set, lets users append messages into the running turn.// Drained at every round boundary; nil disables mid-run injection.steerSink types.SteerSinkdiff --git a/internal/agent/engine_test.go b/internal/agent/engine_test.goindex b7a4fe290..405fe0b36 100644--- a/internal/agent/engine_test.go+++ b/internal/agent/engine_test.go@@ -3,6 +3,7 @@ package agentimport ("context""encoding/json"+ "errors""fmt""strings""sync"@@ -500,6 +501,92 @@ func TestContextCompactionDoesNotRunEveryRound(t *testing.T) {"a context that cannot shrink must not spend another summarization call")}+// recordingCheckpointSink captures what the engine persists.+type recordingCheckpointSink struct {+ turnIDs []string+ saved []*types.ContextCheckpoint+ err error+}++func (s *recordingCheckpointSink) SaveContextCheckpoint(+ _ context.Context, turnMessageID string, checkpoint *types.ContextCheckpoint,+) error {+ s.turnIDs = append(s.turnIDs, turnMessageID)+ s.saved = append(s.saved, checkpoint)+ return s.err+}++// storedHistoryOverflow is a request whose stored history ends on turn-b and+// whose live turn has outgrown the keep-recent budget on its own.+func storedHistoryOverflow() []chat.Message {+ messages := []chat.Message{+ {Role: "system", Content: "you are an agent"},+ {Role: "user", Content: "first question", TurnID: "turn-a"},+ {Role: "assistant", Content: "first answer", TurnID: "turn-a"},+ {Role: "user", Content: "second question", TurnID: "turn-b"},+ {Role: "assistant", Content: "second answer", TurnID: "turn-b"},+ {Role: "user", Content: "build me a deck"},+ }+ body := strings.Repeat("tool output content ", 400)+ for i := 0; i < 20; i++ {+ id := fmt.Sprintf("call-%d", i)+ messages = append(messages,+ chat.Message{Role: "assistant", ToolCalls: []chat.ToolCall{{+ ID: id,+ Type: "function",+ Function: chat.FunctionCall{Name: "write_sandbox_file", Arguments: `{"path":"/w/a.html"}`},+ }}},+ chat.Message{Role: "tool", Name: "write_sandbox_file", ToolCallID: id, Content: body},+ )+ }+ return messages+}++// Without persistence every later turn re-summarizes the same stored history.+// A compaction that ends on a stored turn is written back onto that turn.+func TestContextCompactionPersistsACheckpointOnTheLastStoredTurn(t *testing.T) {+ engine := newTestEngine(t, &summarizerChat{},+ withMaxContextTokens(40000), withMaxCompletionTokens(4000))+ sink := &recordingCheckpointSink{}+ engine.SetContextCheckpointSink(sink)++ messages := storedHistoryOverflow()+ _, changed := engine.manageContextWindow(+ context.Background(), messages, 1, engine.tokenEstimator.EstimateMessages(messages),+ )+ require.True(t, changed)++ require.Equal(t, []string{"turn-b"}, sink.turnIDs)+ require.Contains(t, sink.saved[0].Summary, "do the thing")+ require.False(t, sink.saved[0].CreatedAt.IsZero())+}++// The checkpoint is an optimization for later turns. Failing to store it must+// not undo the compaction this turn needed.+func TestContextCheckpointFailureKeepsTheCompaction(t *testing.T) {+ engine := newTestEngine(t, &summarizerChat{},+ withMaxContextTokens(40000), withMaxCompletionTokens(4000))+ engine.SetContextCheckpointSink(&recordingCheckpointSink{err: errors.New("db down")})++ messages := storedHistoryOverflow()+ before := engine.tokenEstimator.EstimateMessages(messages)+ compacted, changed := engine.manageContextWindow(context.Background(), messages, 1, before)+ require.True(t, changed)+ require.Less(t, engine.tokenEstimator.EstimateMessages(compacted), before/2)+}++// Redacting a stored KB result must not detach it from its turn, or a summary+// ending on that turn could no longer be recognized as ending there.+func TestRedactHistoryKBResultsKeepsTurnID(t *testing.T) {+ redacted := redactHistoryKBResults([]chat.Message{{+ Role: "tool", Name: agenttools.ToolSearchKnowledge, ToolCallID: "c1",+ Content: "stale chunk", TurnID: "turn-a",+ }})+ require.Len(t, redacted, 1)+ require.NotEqual(t, "stale chunk", redacted[0].Content)+ require.Equal(t, "turn-a", redacted[0].TurnID)+}+// Asking for more output than the window can still hold is rejected outright// by the provider, which surfaces to the agent as an unexplained failure.func TestClampCompletionBudgetToContext(t *testing.T) {diff --git a/internal/agent/observe.go b/internal/agent/observe.goindex 80955a21e..c945412ef 100644--- a/internal/agent/observe.go+++ b/internal/agent/observe.go@@ -124,6 +124,7 @@ func (e *AgentEngine) runCompaction("degraded": result.Degraded,})e.emitContextCompacted(ctx, result, round)+ e.saveContextCheckpoint(ctx, result.Checkpoint, round)// The usage baseline described the pre-compaction context; keeping it// would have the next round estimate against history that no longer@@ -919,6 +920,7 @@ func redactHistoryKBResults(llmContext []chat.Message) []chat.Message {Content: "[Previous retrieval result omitted — knowledge base may have changed. Please perform a fresh search.]",ToolCallID: msg.ToolCallID,Name: msg.Name,+ TurnID: msg.TurnID,})} else {redacted = append(redacted, msg)diff --git a/internal/application/repository/message.go b/internal/application/repository/message.goindex 19ccf13b9..c36c83f32 100644--- a/internal/application/repository/message.go+++ b/internal/application/repository/message.go@@ -406,6 +406,38 @@ func (r *messageRepository) UpdateMessageRenderedContent(ctx context.Context, seUpdate("rendered_content", renderedContent).Error}+// UpdateMessageContextCheckpoint updates only the context_checkpoint column, so+// it cannot race a full-row write of the same message.+func (r *messageRepository) UpdateMessageContextCheckpoint(+ ctx context.Context, sessionID, messageID string, checkpoint *types.ContextCheckpoint,+) error {+ return r.db.WithContext(ctx).+ Model(&types.Message{}).+ Where("id = ? AND session_id = ? AND role = ?", messageID, sessionID, "assistant").+ Update("context_checkpoint", checkpoint).Error+}++// GetLatestContextCheckpoint returns the newest checkpointed assistant message.+// Only the identity and ordering columns come back with the checkpoint: the+// caller matches it against turns it has already loaded.+func (r *messageRepository) GetLatestContextCheckpoint(+ ctx context.Context, sessionID string,+) (*types.Message, error) {+ var messages []*types.Message+ if err := r.db.WithContext(ctx).+ Select("id", "session_id", "request_id", "role", "created_at", "context_checkpoint").+ Where("session_id = ? AND role = ? AND context_checkpoint IS NOT NULL", sessionID, "assistant").+ Order("created_at DESC, id DESC").+ Limit(1).+ Find(&messages).Error; err != nil {+ return nil, err+ }+ if len(messages) == 0 {+ return nil, nil+ }+ return messages[0], nil+}+// DeleteMessagesBySessionID deletes all messages belonging to a session (soft delete)func (r *messageRepository) DeleteMessagesBySessionID(ctx context.Context, sessionID string) error {return r.db.WithContext(ctx).Where("session_id = ?", sessionID).Delete(&types.Message{}).Errordiff --git a/internal/application/repository/message_context_checkpoint_test.go b/internal/application/repository/message_context_checkpoint_test.gonew file mode 100644index 000000000..d0b80cced--- /dev/null+++ b/internal/application/repository/message_context_checkpoint_test.go@@ -0,0 +1,87 @@+package repository++import (+ "context"+ "testing"+ "time"++ "github.com/Tencent/WeKnora/internal/types"+ "github.com/stretchr/testify/require"+)++func TestGetLatestContextCheckpointReturnsTheNewestInTheSession(t *testing.T) {+ repo, db := newMessageRepositoryForForkTest(t)+ ctx := context.Background()+ base := time.Date(2026, 9, 18, 9, 0, 0, 0, time.UTC)++ none, err := repo.GetLatestContextCheckpoint(ctx, "s1")+ require.NoError(t, err)+ require.Nil(t, none)++ seedMessage(t, db, "a1", "s1", "assistant", base)+ seedMessage(t, db, "a2", "s1", "assistant", base.Add(time.Minute))+ seedMessage(t, db, "a3", "s1", "assistant", base.Add(2*time.Minute))+ seedMessage(t, db, "other", "s2", "assistant", base.Add(time.Hour))++ require.NoError(t, repo.UpdateMessageContextCheckpoint(ctx, "s1", "a1",+ &types.ContextCheckpoint{Summary: "through one"}))+ require.NoError(t, repo.UpdateMessageContextCheckpoint(ctx, "s1", "a2",+ &types.ContextCheckpoint{Summary: "through two"}))+ require.NoError(t, repo.UpdateMessageContextCheckpoint(ctx, "s2", "other",+ &types.ContextCheckpoint{Summary: "another session"}))++ got, err := repo.GetLatestContextCheckpoint(ctx, "s1")+ require.NoError(t, err)+ require.NotNil(t, got)+ require.Equal(t, "a2", got.ID)+ require.Equal(t, "through two", got.ContextCheckpoint.Summary)+ require.True(t, got.CreatedAt.Equal(base.Add(time.Minute)))++ // A deleted turn takes its checkpoint with it.+ require.NoError(t, repo.DeleteMessage(ctx, "s1", "a2"))+ got, err = repo.GetLatestContextCheckpoint(ctx, "s1")+ require.NoError(t, err)+ require.Equal(t, "a1", got.ID)+}++// The session guard keeps a stray turn ID from writing into another session,+// and the role guard keeps it off user rows.+func TestUpdateMessageContextCheckpointIsScopedToTheSessionsAssistantRows(t *testing.T) {+ repo, db := newMessageRepositoryForForkTest(t)+ ctx := context.Background()+ at := time.Date(2026, 9, 18, 9, 0, 0, 0, time.UTC)++ seedMessage(t, db, "u1", "s1", "user", at)+ seedMessage(t, db, "a1", "s1", "assistant", at)++ require.NoError(t, repo.UpdateMessageContextCheckpoint(ctx, "s2", "a1",+ &types.ContextCheckpoint{Summary: "wrong session"}))+ require.NoError(t, repo.UpdateMessageContextCheckpoint(ctx, "s1", "u1",+ &types.ContextCheckpoint{Summary: "user row"}))++ got, err := repo.GetLatestContextCheckpoint(ctx, "s1")+ require.NoError(t, err)+ require.Nil(t, got)+}++// Messages are also saved whole (UpdateMessage) by paths that loaded them+// before a checkpoint was written. Such a save must not clear it.+func TestUpdateMessageKeepsAnExistingContextCheckpoint(t *testing.T) {+ repo, db := newMessageRepositoryForForkTest(t)+ ctx := context.Background()+ at := time.Date(2026, 9, 18, 9, 0, 0, 0, time.UTC)++ seedMessage(t, db, "a1", "s1", "assistant", at)+ stale, err := repo.GetMessage(ctx, "s1", "a1")+ require.NoError(t, err)++ require.NoError(t, repo.UpdateMessageContextCheckpoint(ctx, "s1", "a1",+ &types.ContextCheckpoint{Summary: "kept"}))+ stale.Content = "edited"+ require.NoError(t, repo.UpdateMessage(ctx, stale))++ got, err := repo.GetLatestContextCheckpoint(ctx, "s1")+ require.NoError(t, err)+ require.NotNil(t, got)+ require.Equal(t, "kept", got.ContextCheckpoint.Summary)+}diff --git a/internal/application/service/agent_history.go b/internal/application/service/agent_history.goindex 5b93eb718..28b4e5c5b 100644--- a/internal/application/service/agent_history.go+++ b/internal/application/service/agent_history.go@@ -9,7 +9,9 @@ import ("strings""time"+ "github.com/Tencent/WeKnora/internal/agent/compaction"agenttools "github.com/Tencent/WeKnora/internal/agent/tools"+ "github.com/Tencent/WeKnora/internal/logger""github.com/Tencent/WeKnora/internal/models/chat""github.com/Tencent/WeKnora/internal/types""github.com/Tencent/WeKnora/internal/types/interfaces"@@ -44,6 +46,12 @@ var agentHistoryThinkTagRegex = regexp.MustCompile(`(?s)<think>.*?</think>`)// Turns lacking either user or assistant content are skipped. The newest// maxRounds turns are returned in chronological order.//+// When a turn carries a context checkpoint (a compaction summary persisted by+// an earlier run), history starts from it: the summary replaces that turn and+// everything before it, and only later turns are replayed. Every replayed+// message is tagged with its turn's assistant message ID so this run's+// compaction can persist a new checkpoint in turn.+//// DB is treated as the single source of truth — there is no Redis/in-memory// cache layer above this function. Callers are expected to invoke it once// per turn before handing the messages to the agent engine.@@ -70,20 +78,11 @@ func LoadAgentHistory(return []chat.Message{}, nil}- // A turn is not always one user message. Mid-run steering persists every- // injected message under the running turn's request ID, so a turn can be- // user → tools → user → tools → answer. Keeping only the last user row- // would drop the original question from the next turn's context.- type turn struct {- users []*types.Message- assistant *types.Message- createdAt time.Time- }- turns := make(map[string]*turn)+ turns := make(map[string]*agentHistoryTurn)for _, msg := range rows {t, ok := turns[msg.RequestID]if !ok {- t = &turn{}+ t = &agentHistoryTurn{}turns[msg.RequestID] = t}switch msg.Role {@@ -97,7 +96,7 @@ func LoadAgentHistory(}}- completeTurns := make([]*turn, 0, len(turns))+ completeTurns := make([]*agentHistoryTurn, 0, len(turns))for _, t := range turns {if len(t.users) > 0 && t.assistant != nil && t.assistant.IsCompleted {sort.SliceStable(t.users, func(i, j int) bool {@@ -111,18 +110,93 @@ func LoadAgentHistory(return completeTurns[i].createdAt.Before(completeTurns[j].createdAt)})+ summary := ""+ if checkpoint := loadContextCheckpoint(ctx, messageRepo, sessionID); checkpoint != nil {+ completeTurns = turnsAfterCheckpoint(completeTurns, checkpoint)+ summary = checkpoint.ContextCheckpoint.Summary+ logger.Infof(ctx, "Agent history resumes from the context checkpoint on %s, %d turn(s) after it",+ checkpoint.ID, len(completeTurns))+ }+if len(completeTurns) > maxRounds {completeTurns = completeTurns[len(completeTurns)-maxRounds:]}- out := make([]chat.Message, 0, len(completeTurns)*4)+ out := make([]chat.Message, 0, len(completeTurns)*4+1)+ if summary != "" {+ out = append(out, compaction.SummaryMessage(summary))+ }for _, t := range completeTurns {+ start := len(out)out = append(out, buildUserHistoryMessage(t.users[0]))out = append(out, buildTurnBodyMessages(t.assistant, t.users[1:])...)+ for i := start; i < len(out); i++ {+ out[i].TurnID = t.assistant.ID+ }}return out, nil}+// agentHistoryTurn is one stored turn. A turn is not always one user message.+// Mid-run steering persists every injected message under the running turn's+// request ID, so a turn can be user → tools → user → tools → answer. Keeping+// only the last user row would drop the original question from the next+// turn's context.+type agentHistoryTurn struct {+ users []*types.Message+ assistant *types.Message+ createdAt time.Time+}++// loadContextCheckpoint returns the session's newest usable checkpoint, or nil.+// A failed lookup degrades to history without one: the turn still runs, it+// just pays for compaction again.+func loadContextCheckpoint(+ ctx context.Context, messageRepo interfaces.MessageRepository, sessionID string,+) *types.Message {+ msg, err := messageRepo.GetLatestContextCheckpoint(ctx, sessionID)+ if err != nil {+ logger.Warnf(ctx, "Failed to load the context checkpoint of session %s, "++ "loading history without it: %v", sessionID, err)+ return nil+ }+ if msg == nil || msg.ContextCheckpoint == nil || strings.TrimSpace(msg.ContextCheckpoint.Summary) == "" {+ return nil+ }+ return msg+}++// turnsAfterCheckpoint drops the turns a checkpoint already covers: its own+// turn and every turn before it. A checkpoint older than the loaded window is+// matched by time instead, which keeps every loaded turn.+func turnsAfterCheckpoint(turns []*agentHistoryTurn, checkpoint *types.Message) []*agentHistoryTurn {+ for i, t := range turns {+ if t.assistant.ID == checkpoint.ID {+ return turns[i+1:]+ }+ }+ after := make([]*agentHistoryTurn, 0, len(turns))+ for _, t := range turns {+ if t.createdAt.After(checkpoint.CreatedAt) {+ after = append(after, t)+ }+ }+ return after+}++// messageCheckpointSink persists the engine's compaction checkpoints onto the+// session's assistant messages, where LoadAgentHistory reads them back.+type messageCheckpointSink struct {+ repo interfaces.MessageRepository+ sessionID string+}++func (s messageCheckpointSink) SaveContextCheckpoint(+ ctx context.Context, turnMessageID string, checkpoint *types.ContextCheckpoint,+) error {+ return s.repo.UpdateMessageContextCheckpoint(ctx, s.sessionID, turnMessageID, checkpoint)+}+// buildTurnBodyMessages replays one turn's assistant work with any mid-run// user messages put back where they happened. Steered messages arrive between// tool rounds, so replaying them all up-front (or dropping them) would telldiff --git a/internal/application/service/agent_history_checkpoint_test.go b/internal/application/service/agent_history_checkpoint_test.gonew file mode 100644index 000000000..339cdc8dd--- /dev/null+++ b/internal/application/service/agent_history_checkpoint_test.go@@ -0,0 +1,168 @@+package service++import (+ "context"+ "errors"+ "fmt"+ "testing"+ "time"++ "github.com/Tencent/WeKnora/internal/models/chat"+ "github.com/Tencent/WeKnora/internal/types"+ "github.com/Tencent/WeKnora/internal/types/interfaces"+ "github.com/stretchr/testify/assert"+ "github.com/stretchr/testify/require"+)++// checkpointHistoryRepo serves a fixed message list and one checkpoint lookup.+type checkpointHistoryRepo struct {+ interfaces.MessageRepository+ rows []*types.Message+ checkpoint *types.Message+ checkpointErr error+ updates []string+}++func (r *checkpointHistoryRepo) GetRecentMessagesBySession(+ context.Context, string, int,+) ([]*types.Message, error) {+ return r.rows, nil+}++func (r *checkpointHistoryRepo) GetLatestContextCheckpoint(+ context.Context, string,+) (*types.Message, error) {+ return r.checkpoint, r.checkpointErr+}++func (r *checkpointHistoryRepo) UpdateMessageContextCheckpoint(+ _ context.Context, sessionID, messageID string, checkpoint *types.ContextCheckpoint,+) error {+ r.updates = append(r.updates, sessionID+"/"+messageID+"/"+checkpoint.Summary)+ return nil+}++var historyBase = time.Date(2026, 9, 18, 9, 0, 0, 0, time.UTC)++// storedTurns builds n completed turns; turn i has user u<i> and assistant a<i>.+func storedTurns(n int) []*types.Message {+ var rows []*types.Message+ for i := 1; i <= n; i++ {+ at := historyBase.Add(time.Duration(i) * time.Minute)+ req := fmt.Sprintf("req-%d", i)+ rows = append(rows,+ &types.Message{+ ID: fmt.Sprintf("u%d", i), RequestID: req, Role: "user",+ Content: fmt.Sprintf("question %d", i), CreatedAt: at,+ },+ &types.Message{+ ID: fmt.Sprintf("a%d", i), RequestID: req, Role: "assistant",+ Content: fmt.Sprintf("answer %d", i), IsCompleted: true, CreatedAt: at.Add(time.Second),+ },+ )+ }+ return rows+}++func checkpointOn(msg *types.Message, summary string) *types.Message {+ return &types.Message{+ ID: msg.ID, SessionID: msg.SessionID, RequestID: msg.RequestID, Role: "assistant",+ CreatedAt: msg.CreatedAt, ContextCheckpoint: &types.ContextCheckpoint{Summary: summary},+ }+}++func contents(msgs []chat.Message) []string {+ out := make([]string, len(msgs))+ for i, m := range msgs {+ out[i] = m.Content+ }+ return out+}++// Without a checkpoint history is what it always was, plus the turn tags the+// engine needs to recognize a summary that ends on a stored turn.+func TestLoadAgentHistoryTagsEveryMessageWithItsTurn(t *testing.T) {+ repo := &checkpointHistoryRepo{rows: storedTurns(2)}++ got, err := LoadAgentHistory(context.Background(), repo, "s1", 5)+ require.NoError(t, err)++ require.Equal(t, []string{"question 1", "answer 1", "question 2", "answer 2"}, contents(got))+ for i, want := range []string{"a1", "a1", "a2", "a2"} {+ assert.Equal(t, want, got[i].TurnID, "message %d", i)+ }+}++// The summary replaces its own turn and every turn before it; later turns are+// replayed verbatim after it.+func TestLoadAgentHistoryResumesFromTheCheckpoint(t *testing.T) {+ rows := storedTurns(4)+ repo := &checkpointHistoryRepo{rows: rows, checkpoint: checkpointOn(rows[3], "## Goal\nturns one and two")}++ got, err := LoadAgentHistory(context.Background(), repo, "s1", 5)+ require.NoError(t, err)++ require.Len(t, got, 5)+ assert.Equal(t, chat.MessageKindCompactionSummary, got[0].Kind)+ assert.Equal(t, "user", got[0].Role)+ assert.Contains(t, got[0].Content, "turns one and two")+ assert.Empty(t, got[0].TurnID, "the summary is not a stored turn")+ assert.Equal(t, []string{"question 3", "answer 3", "question 4", "answer 4"}, contents(got[1:]))+ assert.Equal(t, "a3", got[1].TurnID)+ assert.Equal(t, "a4", got[4].TurnID)+}++// A checkpoint can predate the rows fetched for the window. It still covers+// everything before it, and every fetched turn is newer.+func TestLoadAgentHistoryUsesACheckpointOlderThanTheWindow(t *testing.T) {+ rows := storedTurns(4)+ repo := &checkpointHistoryRepo{rows: rows[4:], checkpoint: checkpointOn(rows[1], "## Goal\nturn one")}++ got, err := LoadAgentHistory(context.Background(), repo, "s1", 5)+ require.NoError(t, err)++ require.Len(t, got, 5)+ assert.Contains(t, got[0].Content, "turn one")+ assert.Equal(t, []string{"question 3", "answer 3", "question 4", "answer 4"}, contents(got[1:]))+}++// The turn cap bounds the verbatim turns after the checkpoint, not the+// summary, which is already bounded by the summarizer's budget.+func TestLoadAgentHistoryCapsTurnsAfterTheCheckpoint(t *testing.T) {+ rows := storedTurns(3)+ repo := &checkpointHistoryRepo{rows: rows, checkpoint: checkpointOn(rows[1], "## Goal\nturn one")}++ got, err := LoadAgentHistory(context.Background(), repo, "s1", 1)+ require.NoError(t, err)++ require.Len(t, got, 3)+ assert.Equal(t, chat.MessageKindCompactionSummary, got[0].Kind)+ assert.Equal(t, []string{"question 3", "answer 3"}, contents(got[1:]))+}++// A failed lookup costs the turn a re-summarization, not its history.+func TestLoadAgentHistoryWithoutACheckpointWhenTheLookupFails(t *testing.T) {+ repo := &checkpointHistoryRepo{rows: storedTurns(2), checkpointErr: errors.New("db down")}++ got, err := LoadAgentHistory(context.Background(), repo, "s1", 5)+ require.NoError(t, err)+ assert.Equal(t, []string{"question 1", "answer 1", "question 2", "answer 2"}, contents(got))+}++func TestLoadAgentHistoryIgnoresAnEmptyCheckpoint(t *testing.T) {+ rows := storedTurns(2)+ repo := &checkpointHistoryRepo{rows: rows, checkpoint: checkpointOn(rows[1], " ")}++ got, err := LoadAgentHistory(context.Background(), repo, "s1", 5)+ require.NoError(t, err)+ assert.Equal(t, []string{"question 1", "answer 1", "question 2", "answer 2"}, contents(got))+}++func TestMessageCheckpointSinkWritesThroughTheSession(t *testing.T) {+ repo := &checkpointHistoryRepo{}+ sink := messageCheckpointSink{repo: repo, sessionID: "s1"}++ require.NoError(t, sink.SaveContextCheckpoint(context.Background(), "a2",+ &types.ContextCheckpoint{Summary: "sum"}))+ assert.Equal(t, []string{"s1/a2/sum"}, repo.updates)+}diff --git a/internal/application/service/session_agent_qa.go b/internal/application/service/session_agent_qa.goindex fa989efb5..f15cc2782 100644--- a/internal/application/service/session_agent_qa.go+++ b/internal/application/service/session_agent_qa.go@@ -241,6 +241,13 @@ func (s *sessionService) AgentQA(engine.SetSteerSink(req.SteerSink)}+ // A compaction that ends on a stored turn is written back onto it, so the+ // next turn loads the summary instead of summarizing the same history+ // again. Without multi-turn there is no stored history to end on.+ if agentConfig.MultiTurnEnabled {+ engine.SetContextCheckpointSink(messageCheckpointSink{repo: s.messageRepo, sessionID: sessionID})+ }+agentQuery := req.Queryvar agentImageURLs []stringif agentModelSupportsVision && len(req.ImageURLs) > 0 {diff --git a/internal/application/service/tenant_skill_install_test.go b/internal/application/service/tenant_skill_install_test.goindex d908247f2..05b0d64f8 100644--- a/internal/application/service/tenant_skill_install_test.go+++ b/internal/application/service/tenant_skill_install_test.go@@ -748,9 +748,10 @@ func TestInstallSkillRecoversFromNameConflict(t *testing.T) {require.NoError(t, err)require.Equal(t, "sk-1", id,"the upload that lost the unique index must reuse the row that won")- skill, getErr := fx.skillRepo.GetSkill(context.Background(), 7, "cfg-1", "sk-1")- require.NoError(t, getErr)- require.Equal(t, types.SkillStatusInstalling, skill.Status)+ // The install runs in the background and the fixture row already starts at+ // installing, so an immediate status read raced the goroutine and proved+ // nothing. The run finishing on the reused row is what shows it was taken.+ waitBackgroundInstallReady(t, fx, "the install must run on the row that won")}func TestInstallSkillRefusesWhenBundleCannotBeStored(t *testing.T) {@@ -3206,8 +3207,9 @@ func (e *installAgentEngine) Execute(}return &types.AgentState{IsComplete: true}, nil}-func (e *installAgentEngine) SetMemoryPrompt(string) {}-func (e *installAgentEngine) SetSteerSink(sink types.SteerSink) { e.sink = sink }+func (e *installAgentEngine) SetMemoryPrompt(string) {}+func (e *installAgentEngine) SetSteerSink(sink types.SteerSink) { e.sink = sink }+func (e *installAgentEngine) SetContextCheckpointSink(types.ContextCheckpointSink) {}type installSessionService struct {fx *installFixturediff --git a/internal/database/migration_sqlite_versioned_schema_test.go b/internal/database/migration_sqlite_versioned_schema_test.goindex bf7123184..28bff5ec7 100644--- a/internal/database/migration_sqlite_versioned_schema_test.go+++ b/internal/database/migration_sqlite_versioned_schema_test.go@@ -34,21 +34,21 @@ var versionedSQLiteTables = []string{// versionedSQLiteColumns maps each existing table to the columns that the// versioned migrations add and the SQLite baseline was missing.var versionedSQLiteColumns = map[string][]string{- "memory_subjects": {"extraction_state"}, // 000094- "memory_items": {"replaces_id"}, // 000094- "tenants": {"api_principal_config"}, // 000064- "users": {"is_system_admin"}, // 000053- "knowledges": {"pending_subtasks_count", "profile"}, // 000056, 000101- "knowledge_bases": {"profile_config", "generated_profile"}, // 000101- "messages": {"attachments", "usage", "sandbox_checkpoint"}, // 000034, 000085, 000097- "sessions": {"parent_session_id", "forked_from_message_id", "fork_bootstrap"}, // 000097- "tenant_invitations": {"token", "accepted_count"}, // 000054- "embed_channels": {"allow_memory"}, // 000060- "mcp_oauth_tokens": {"principal_type", "principal_id"}, // 000064- "mcp_tool_approvals": {"enabled"}, // 000091+ "memory_subjects": {"extraction_state"}, // 000094+ "memory_items": {"replaces_id"}, // 000094+ "tenants": {"api_principal_config"}, // 000064+ "users": {"is_system_admin"}, // 000053+ "knowledges": {"pending_subtasks_count", "profile"}, // 000056, 000101+ "knowledge_bases": {"profile_config", "generated_profile"}, // 000101+ "messages": {"attachments", "usage", "sandbox_checkpoint", "context_checkpoint"}, // 000034/085/097/104+ "sessions": {"parent_session_id", "forked_from_message_id", "fork_bootstrap"}, // 000097+ "tenant_invitations": {"token", "accepted_count"}, // 000054+ "embed_channels": {"allow_memory"}, // 000060+ "mcp_oauth_tokens": {"principal_type", "principal_id"}, // 000064+ "mcp_tool_approvals": {"enabled"}, // 000091}-const expectedSQLiteMigrationVersion = 23+const expectedSQLiteMigrationVersion = 24func TestSQLiteMigrationsCreateVersionedSchema(t *testing.T) {repoRoot := sqliteRepoRoot(t)diff --git a/internal/models/chat/chat.go b/internal/models/chat/chat.goindex 5a908ee22..55e34048b 100644--- a/internal/models/chat/chat.go+++ b/internal/models/chat/chat.go@@ -93,6 +93,12 @@ type Message struct {// providers reject unknown message fields on some endpoints, and this one// means nothing to them anyway.Kind MessageKind `json:"-"`+ // TurnID is the stored assistant message whose turn this history message+ // was replayed from. It is empty for the live turn and for messages the+ // engine synthesized. Compaction uses it to tell whether a summary ends+ // exactly on a stored turn, the only kind it can persist for later turns.+ // Engine-internal like Kind, and kept off the wire for the same reason.+ TurnID string `json:"-"`}// ToolCall represents a tool call in a messagediff --git a/internal/types/context_checkpoint.go b/internal/types/context_checkpoint.gonew file mode 100644index 000000000..0ed58d2aa--- /dev/null+++ b/internal/types/context_checkpoint.go@@ -0,0 +1,58 @@+package types++import (+ "context"+ "database/sql/driver"+ "encoding/json"+ "errors"+ "time"+)++// ContextCheckpoint is an agent compaction summary persisted on the assistant+// message of the last turn it covers. The next turn's history starts from the+// newest checkpoint instead of from the raw turns it replaces, so a compaction+// is paid for once rather than again on every later turn.+//+// Storing it on the covered turn rather than on the turn that ran the+// compaction keeps the boundary implicit: a fork that copies the turn copies+// the checkpoint with it, and deleting the turn drops the checkpoint too.+type ContextCheckpoint struct {+ Summary string `json:"summary"`+ CreatedAt time.Time `json:"created_at"`+}++// Value implements the driver.Valuer interface for database serialization.+func (c ContextCheckpoint) Value() (driver.Value, error) {+ return json.Marshal(c)+}++// Scan implements the sql.Scanner interface for database deserialization.+func (c *ContextCheckpoint) Scan(value any) error {+ if value == nil {+ *c = ContextCheckpoint{}+ return nil+ }+ var b []byte+ switch v := value.(type) {+ case []byte:+ b = v+ case string:+ b = []byte(v)+ default:+ return errors.New("types: cannot scan context checkpoint from unsupported type")+ }+ if len(b) == 0 {+ *c = ContextCheckpoint{}+ return nil+ }+ return json.Unmarshal(b, c)+}++// ContextCheckpointSink persists compaction checkpoints for the agent engine.+// Declared in types for the same reason as SteerSink: the engine and the+// service both need the shape and neither may import the other.+type ContextCheckpointSink interface {+ // SaveContextCheckpoint stores checkpoint on the assistant message+ // turnMessageID, replacing any earlier checkpoint there.+ SaveContextCheckpoint(ctx context.Context, turnMessageID string, checkpoint *ContextCheckpoint) error+}diff --git a/internal/types/interfaces/agent.go b/internal/types/interfaces/agent.goindex ab3edd8bc..f0c3a2ea8 100644--- a/internal/types/interfaces/agent.go+++ b/internal/types/interfaces/agent.go@@ -38,6 +38,11 @@ type AgentEngine interface {// messages at every round boundary and persists accepted ones through// the sink. Must be called before Execute.SetSteerSink(sink types.SteerSink)++ // SetContextCheckpointSink enables persisting compaction summaries that+ // end on a stored turn, so later turns start from them. Nil (default)+ // keeps compaction local to the turn. Must be called before Execute.+ SetContextCheckpointSink(sink types.ContextCheckpointSink)}// AgentService defines the interface for agent-related operationsdiff --git a/internal/types/interfaces/message.go b/internal/types/interfaces/message.goindex dbed461d4..543ec3714 100644--- a/internal/types/interfaces/message.go+++ b/internal/types/interfaces/message.go@@ -106,6 +106,15 @@ type MessageRepository interface {UpdateMessageImages(ctx context.Context, sessionID, messageID string, images types.MessageImages) error// UpdateMessageRenderedContent updates the rendered_content column for a user messageUpdateMessageRenderedContent(ctx context.Context, sessionID, messageID string, renderedContent string) error+ // UpdateMessageContextCheckpoint writes only the context_checkpoint column+ // of an assistant message.+ UpdateMessageContextCheckpoint(+ ctx context.Context, sessionID, messageID string, checkpoint *types.ContextCheckpoint,+ ) error+ // GetLatestContextCheckpoint returns the newest assistant message in the+ // session that carries a context checkpoint, projected to the columns+ // history loading needs, or nil when there is none.+ GetLatestContextCheckpoint(ctx context.Context, sessionID string) (*types.Message, error)// DeleteMessage deletes a messageDeleteMessage(ctx context.Context, sessionID string, id string) error// DeleteMessagesBySessionID deletes all messages belonging to a sessiondiff --git a/internal/types/message.go b/internal/types/message.goindex 32f7db04b..36e8fbced 100644--- a/internal/types/message.go+++ b/internal/types/message.go@@ -410,6 +410,11 @@ type Message struct {// failed checkpoint must never block the reply). A message without a// checkpoint cannot serve as a fork point with sandbox state.SandboxCheckpoint *SandboxCheckpoint `json:"sandbox_checkpoint,omitempty" gorm:"type:jsonb"`+ // ContextCheckpoint is the agent compaction summary covering this turn+ // and every turn before it (see ContextCheckpoint). Assistant messages+ // only; nil unless a later turn's compaction ended exactly here. Internal+ // to history loading, so it stays out of API responses.+ ContextCheckpoint *ContextCheckpoint `json:"-" gorm:"type:jsonb;column:context_checkpoint"`// Message creation timestampCreatedAt time.Time `json:"created_at"`// Last update timestampdiff --git a/migrations/sqlite/000024_message_context_checkpoint.down.sql b/migrations/sqlite/000024_message_context_checkpoint.down.sqlnew file mode 100644index 000000000..fa0921c4b--- /dev/null+++ b/migrations/sqlite/000024_message_context_checkpoint.down.sql@@ -0,0 +1 @@+ALTER TABLE messages DROP COLUMN context_checkpoint;diff --git a/migrations/sqlite/000024_message_context_checkpoint.up.sql b/migrations/sqlite/000024_message_context_checkpoint.up.sqlnew file mode 100644index 000000000..1a133430e--- /dev/null+++ b/migrations/sqlite/000024_message_context_checkpoint.up.sql@@ -0,0 +1,3 @@+-- Mirrors versioned migration 000104_message_context_checkpoint: the agent+-- compaction summary persisted on the last turn it covers.+ALTER TABLE messages ADD COLUMN context_checkpoint TEXT;diff --git a/migrations/versioned/000104_message_context_checkpoint.down.sql b/migrations/versioned/000104_message_context_checkpoint.down.sqlnew file mode 100644index 000000000..7f173f6c2--- /dev/null+++ b/migrations/versioned/000104_message_context_checkpoint.down.sql@@ -0,0 +1 @@+ALTER TABLE messages DROP COLUMN IF EXISTS context_checkpoint;diff --git a/migrations/versioned/000104_message_context_checkpoint.up.sql b/migrations/versioned/000104_message_context_checkpoint.up.sqlnew file mode 100644index 000000000..f4a1120fb--- /dev/null+++ b/migrations/versioned/000104_message_context_checkpoint.up.sql@@ -0,0 +1,7 @@+-- Migration: 000104_message_context_checkpoint+-- Agent compaction summaries persisted on the assistant message of the last+-- turn they cover, so the next turn's history starts from the summary instead+-- of summarizing the same turns again.+ALTER TABLE messages ADD COLUMN IF NOT EXISTS context_checkpoint JSONB;++COMMENT ON COLUMN messages.context_checkpoint IS 'Agent compaction summary covering this turn and every turn before it';diff --git a/website-docs/03-features/07-agent.md b/website-docs/03-features/07-agent.mdindex 11ad95c7f..25ee6bf6d 100644--- a/website-docs/03-features/07-agent.md+++ b/website-docs/03-features/07-agent.md@@ -514,13 +514,17 @@ var ToolCapabilityRequirements = map[string]ToolRequirement{若压缩后仍超预算,最后才裁短工具结果,工具结果预算取窗口的 20%,限制在 8192–32768 Token。没有可压缩内容或释放空间不足 5% 时,记下当前消息数量,避免在同一上下文大小反复花费模型调用。成功压缩会清除旧 usage 基线,并发出 context_compacted 事件,包含前后 Token/消息数、原因、split_turn 与 degraded。+**压缩点持久化**。当摘要的历史部分恰好结束在某个已落库轮次的末尾时,引擎把这段摘要作为压缩点(`messages.context_checkpoint`)写回该轮的 assistant 消息,下一轮直接从它开始,不再对同一段历史重复摘要。历史消息在重建时带上所属轮次的 assistant 消息 ID(`chat.Message.TurnID`,不上线),据此判断切点是否落在轮次边界。以下情况不写压缩点:切点落在某个已落库轮次内部(例如停在追加消息处);摘要只覆盖当前轮;历史摘要回退成了原始归档(degraded)。切分轮前半段的摘要不写入压缩点,因为该轮下次会被完整重放。写入只更新这一列,失败时仅记日志,不影响本轮。压缩点存在被覆盖的那一轮上,所以会话分叉复制该轮时会一起复制,删除该轮时压缩点也随之失效。+提供商报告上下文超限(错误或响应截断判据)时,还可强制压缩并重试一次。仅因生成耗尽 completion 预算的截断不应误判成上下文超限。具体提供商错误识别见 `internal/agent/compaction/overflow.go`。#### 会话历史(agent_history) {#_4-3-会话历史-agent-history}跨轮历史由 `LoadAgentHistory`(`internal/application/service/agent_history.go`)每轮从 messages 表重建(DB 是唯一事实来源,无 Redis/内存缓存):-- 取 `HistoryTurns × 4`(最低 50)条原始消息,按 `RequestID` 配对 user/assistant,只保留 assistant 已完成(`IsCompleted`)的完整轮,按时间排序取最近 `HistoryTurns` 轮;+- 取 `HistoryTurns × 4`(最低 50)条原始消息,按 `RequestID` 配对 user/assistant,只保留 assistant 已完成(`IsCompleted`)的完整轮,按时间排序;+- 会话中存在压缩点(见[上下文压缩与溢出恢复](#_4-2-上下文压缩与溢出恢复))时,取最新的一个:它所在的轮及更早的轮由一条摘要消息代替,放在历史最前面,之后的轮原样重放。压缩点早于本次读取范围时按时间判断,读到的轮都在它之后。压缩点查询失败时退回无压缩点的历史;+- 再取最近 `HistoryTurns` 轮。这个上限只约束压缩点之后原样重放的轮,不包括摘要;- 每轮展开为:user 消息(含图片 caption 与附件 prompt;忽略 `RenderedContent` 快照,避免将旧渲染协议带入上下文)→ 每个含工具调用的 `AgentStep` 展开为 assistant(with tool_calls) + 若干 tool 消息 → 末尾一条规范化最终答案 assistant 消息(剥离 `<think>` 块);- 历史中的 tool 消息内容用 `CompactToolOutputForHistory`(`internal/agent/tools/persist.go`)压缩:带 `display_type` 的大载荷(如 `knowledge_chunks_list` 的 chunks、`grep_results` 的 chunk_results)替换为一行摘要(如 `"Listed 20/87 chunks from X (content omitted from history)"`)。