RAGFlow is an agent-native database: a Retrieval-Augmented Generation (RAG) engine that grew into context infrastructure.
Go agent-harnessagent-native-databaseagentic-aiagentic-retrievalagentic-searchaiai-agentscontext-enginecontext-engineeringcontext-managementharness-engineeringknowledge-compilationragretrieval-augmented-generationretrieval-harnesssearch-harness
fix(agent): surface cancellation terminal state (#18579)
Guofang.Tangda68cad1a08e
diff --git a/internal/agent/canvas/runner.go b/internal/agent/canvas/runner.goindex cc022d866b..b75068a1f8 100644--- a/internal/agent/canvas/runner.go+++ b/internal/agent/canvas/runner.go@@ -36,14 +36,18 @@// id. Persist the id so the next call can resume via// compose.ResumeWithData (signalled through root:// __resume_interrupt_id__ + __resume_data__).-// 3. Cancel / timeout (errors.Is(err, context.Canceled) etc.):-// silently close. The HTTP handler has already detached.+// 3. Cancellation (errors.Is(err, context.Canceled)):+// emit `cancelled` so protocol adapters do not mistake an aborted run+// for a successful empty completion. The HTTP handler may already have+// detached; in that case the event is simply dropped by the forwarding+// layer.// 4. Other errors: emit `error` event with the err.Error() string.//// SSE wire contract (matches the handler envelope):// - RunEvent.Type == "message" → {data: <string>}// - RunEvent.Type == "waiting_for_user" → {cpn_id: <string>}// - RunEvent.Type == "error" → {message: <string>}+// - RunEvent.Type == "cancelled" → {message: <string>}package canvasimport (@@ -136,6 +140,38 @@ type ErrorEvent struct {Message string `json:"message"`}+// CancelledEvent is an alias for ErrorEvent because both terminal payloads+// carry the same message-only schema.+type CancelledEvent = ErrorEvent++type eventContextKey struct{}++// WithEventContext attaches the context that represents the event consumer.+// It is intentionally separate from the workflow context: an explicit run+// cancellation should still deliver a terminal cancelled event to an active+// client, while a disconnected client must be able to stop event delivery.+func WithEventContext(ctx, eventCtx context.Context) context.Context {+ if ctx == nil {+ ctx = context.Background()+ }+ if eventCtx == nil {+ eventCtx = ctx+ }+ return context.WithValue(ctx, eventContextKey{}, eventCtx)+}++// getEventContext returns the consumer context attached to a workflow context,+// falling back to the workflow context when no separate consumer exists.+func getEventContext(ctx context.Context) context.Context {+ if ctx == nil {+ return context.Background()+ }+ if eventCtx, ok := ctx.Value(eventContextKey{}).(context.Context); ok && eventCtx != nil {+ return eventCtx+ }+ return ctx+}+// RunFunc is the canvas execution contract the Runner depends on.// Service-layer code supplies an implementation that compiles the// DSL and invokes the eino Workflow; the Runner is agnostic to@@ -227,7 +263,7 @@ func (r *Runner) Run(out := make(chan RunEvent, 8)if run == nil {- pushErr(out, "canvas: nil RunFunc", sessionID)+ pushErr(ctx, out, "canvas: nil RunFunc", sessionID)close(out)return out}@@ -276,6 +312,13 @@ func (r *Runner) Run(_, runErr := safeInvoke(ctx, run, root)if runErr != nil {if errors.Is(runErr, context.Canceled) {+ push(ctx, out, RunEvent{+ Type: "cancelled",+ Data: safeEventJSON(CancelledEvent{Message: "Agent run was cancelled."}),+ MessageID: messageID,+ CreatedAt: nowUnix(),+ SessionID: sessionID,+ })return}if ctxs := ExtractInterruptContexts(runErr); len(ctxs) > 0 {@@ -303,7 +346,7 @@ func (r *Runner) Run(}}}- push(out, RunEvent{Type: "waiting_for_user", Data: safeEventJSON(waiting), MessageID: messageID, CreatedAt: nowUnix(), SessionID: sessionID})+ push(ctx, out, RunEvent{Type: "waiting_for_user", Data: safeEventJSON(waiting), MessageID: messageID, CreatedAt: nowUnix(), SessionID: sessionID})return}if IsInterruptError(runErr) {@@ -312,10 +355,10 @@ func (r *Runner) Run(// without a cpn id — the front-end falls back to// the first paused session it knows about.r.saveInterruptID(canvasID, sessionID, runErr.Error())- push(out, RunEvent{Type: "waiting_for_user", Data: safeEventJSON(WaitingForUserEvent{CpnID: runErr.Error()}), MessageID: messageID, CreatedAt: nowUnix(), SessionID: sessionID})+ push(ctx, out, RunEvent{Type: "waiting_for_user", Data: safeEventJSON(WaitingForUserEvent{CpnID: runErr.Error()}), MessageID: messageID, CreatedAt: nowUnix(), SessionID: sessionID})return}- pushErr(out, runErr.Error(), sessionID)+ pushErr(ctx, out, runErr.Error(), sessionID)return}}()@@ -376,22 +419,31 @@ func safeInvoke(ctx context.Context, run RunFunc, root map[string]any) (*CanvasS// has gone away (handler cancelled). Exported so the service layer's// buildRunFunc can emit intermediate workflow events through the// same channel during execution.-func PushEvent(ch chan<- RunEvent, ev RunEvent) {+func PushEvent(ctx context.Context, ch chan<- RunEvent, ev RunEvent) {+ if ch == nil {+ return+ }defer func() { _ = recover() }()- ch <- ev+ eventCtx := getEventContext(ctx)+ if eventCtx.Err() != nil {+ return+ }+ select {+ case ch <- ev:+ case <-eventCtx.Done():+ }}// push sends an event to the channel, dropping it if the consumer// has gone away (handler cancelled). Errors on send are intentional// and ignored — the handler is the only consumer and its// `for-range` loop exits when the request context is cancelled.-func push(out chan<- RunEvent, ev RunEvent) {- defer func() { _ = recover() }()- out <- ev+func push(ctx context.Context, out chan<- RunEvent, ev RunEvent) {+ PushEvent(ctx, out, ev)}// pushErr serialises an ErrorEvent and pushes it on the channel.-func pushErr(out chan<- RunEvent, msg, sessionID string) {+func pushErr(ctx context.Context, out chan<- RunEvent, msg, sessionID string) {payload, err := json.Marshal(ErrorEvent{Message: msg})if err != nil {common.Warn("runner: pushErr json.Marshal failed, falling back",@@ -400,7 +452,7 @@ func pushErr(out chan<- RunEvent, msg, sessionID string) {// Fall back to a hard-coded minimal JSON.payload = []byte(`{"message":"event serialization failed"}`)}- push(out, RunEvent{Type: "error", Data: string(payload), SessionID: sessionID, CreatedAt: nowUnix()})+ push(ctx, out, RunEvent{Type: "error", Data: string(payload), SessionID: sessionID, CreatedAt: nowUnix()})}// safeEventJSON marshals v to a JSON string, falling back todiff --git a/internal/agent/canvas/runner_cancel_test.go b/internal/agent/canvas/runner_cancel_test.goindex 6cc00af7d0..990a519fa2 100644--- a/internal/agent/canvas/runner_cancel_test.go+++ b/internal/agent/canvas/runner_cancel_test.go@@ -6,6 +6,7 @@ package canvasimport ("context"+ "encoding/json""testing""time")@@ -66,3 +67,71 @@ func TestRunnerParentContextCancelsManagedRun(t *testing.T) {t.Fatal("RunFunc was left running after parent context cancellation")}}++func TestRunnerEmitsCancelledEvent(t *testing.T) {+ r := NewRunner()+ ctx, cancel := context.WithCancel(context.Background())+ started := make(chan struct{})+ events := r.Run(WithEventContext(ctx, context.Background()), blockingRun(started), "canvas", "session", nil, map[string]any{})+ <-started+ cancel()++ select {+ case ev, ok := <-events:+ if !ok {+ t.Fatal("run event channel closed without a cancellation event")+ }+ if ev.Type != "cancelled" {+ t.Fatalf("event type = %q, want cancelled", ev.Type)+ }+ var payload CancelledEvent+ if err := json.Unmarshal([]byte(ev.Data), &payload); err != nil {+ t.Fatalf("decode cancellation event: %v", err)+ }+ if payload.Message != "Agent run was cancelled." {+ t.Errorf("cancellation message = %q, want default message", payload.Message)+ }+ case <-time.After(2 * time.Second):+ t.Fatal("timed out waiting for cancellation event")+ }++ if _, ok := <-events; ok {+ t.Fatal("run event channel should close after cancellation event")+ }+}++// TestPushEventSkipsCancelledConsumer verifies that an already-cancelled+// event context prevents delivery even when the destination buffer is writable.+func TestPushEventSkipsCancelledConsumer(t *testing.T) {+ eventCtx, cancelEvents := context.WithCancel(context.Background())+ workflowCtx := WithEventContext(context.Background(), eventCtx)+ events := make(chan RunEvent, 1)+ cancelEvents()++ PushEvent(workflowCtx, events, RunEvent{Type: "message"})+ if len(events) != 0 {+ t.Fatalf("event channel length = %d, want 0 after consumer cancellation", len(events))+ }+}++// TestRunnerDropsEventsAfterConsumerCancellation verifies that a blocked+// producer is released when the event consumer cancels its context.+func TestRunnerDropsEventsAfterConsumerCancellation(t *testing.T) {+ r := NewRunner()+ runCtx := context.Background()+ eventCtx, cancelEvents := context.WithCancel(context.Background())+ runCtx = WithEventContext(runCtx, eventCtx)+ started := make(chan struct{})+ run := func(ctx context.Context, root map[string]any) (*CanvasState, error) {+ close(started)+ events := root["__events__"].(chan RunEvent)+ for i := 0; i <= cap(events); i++ {+ PushEvent(ctx, events, RunEvent{Type: "message"})+ }+ return nil, nil+ }+ events := r.Run(runCtx, run, "canvas", "session", nil, map[string]any{})+ <-started+ cancelEvents()+ waitClosed(t, events)+}diff --git a/internal/agent/canvas/scheduler.go b/internal/agent/canvas/scheduler.goindex ad07c0857a..1972f08e80 100644--- a/internal/agent/canvas/scheduler.go+++ b/internal/agent/canvas/scheduler.go@@ -250,7 +250,7 @@ func emitEventFromCtx(ctx context.Context, ev RunEvent) {if meta == nil || meta.Events == nil {return}- PushEvent(meta.Events, ev)+ PushEvent(ctx, meta.Events, ev)}func sanitizeNodeInputs(inputs map[string]any) map[string]any {diff --git a/internal/handler/agent_openai.go b/internal/handler/agent_openai.goindex a4c7155253..a198b3446e 100644--- a/internal/handler/agent_openai.go+++ b/internal/handler/agent_openai.go@@ -57,6 +57,7 @@ type openAICompatStreamDelta struct {ToolCalls any `json:"tool_calls"`Reference any `json:"reference,omitempty"`Error any `json:"error,omitempty"`+ Cancelled any `json:"cancelled,omitempty"`WaitingForUser any `json:"waiting_for_user,omitempty"`}@@ -163,6 +164,13 @@ func (h *AgentHandler) streamOpenAICompat(chunk.Usage = openAICompatUsageForCompletion(promptTokens, completionTokens)_ = writeOpenAICompatSSE(c, chunk)return+ case "cancelled":+ message := openAICompatRunEventMessage(ev, "Agent run was cancelled.")+ chunk := newOpenAICompatStreamChunk(completionID, model, nil, "cancelled")+ chunk.Choices[0].Delta.Cancelled = map[string]string{"message": message}+ chunk.Usage = openAICompatUsageForCompletion(promptTokens, completionTokens)+ _ = writeOpenAICompatSSE(c, chunk)+ return}if ev.Type != "message" && ev.Type != "message_end" {@@ -232,6 +240,12 @@ func collectOpenAICompatCompletion(}return openAICompatCompletion{}, common.NewCodedError(common.CodeConflict, message)}+ if ev.Type == "cancelled" {+ return openAICompatCompletion{}, common.NewCodedError(+ common.CodeConflict,+ openAICompatRunEventMessage(ev, "Agent run was cancelled."),+ )+ }if ev.Type != "message" && ev.Type != "message_end" {continue}diff --git a/internal/handler/agent_test.go b/internal/handler/agent_test.goindex 911c64e55d..b9051c3e73 100644--- a/internal/handler/agent_test.go+++ b/internal/handler/agent_test.go@@ -1196,6 +1196,42 @@ func TestAgentChatCompletions_OpenAICompat_NonStreamReturnsWaitingForUser(t *tes}}+func TestAgentChatCompletions_OpenAICompat_NonStreamReturnsCancelled(t *testing.T) {+ gin.SetMode(gin.TestMode)+ w := httptest.NewRecorder()+ c, _ := gin.CreateTestContext(w)+ c.Request = httptest.NewRequest("POST", "/api/v1/agents/chat/completions",+ strings.NewReader(`{"agent_id":"a1","openai-compatible":true,"messages":[{"role":"user","content":"hi"}]}`))+ c.Request.Header.Set("Content-Type", "application/json")+ c.Set("user", &entity.User{ID: "u1"})+ c.Set("user_id", "u1")++ runner := &stubChatRunner{events: []canvas.RunEvent{+ {Type: "cancelled", Data: `{"message":"Agent run was cancelled."}`},+ }}+ h := &AgentHandler{chatRunner: runner}+ h.AgentChatCompletions(c)++ if w.Code != http.StatusConflict {+ t.Fatalf("status = %d, want 409: %s", w.Code, w.Body.String())+ }+ var response struct {+ Error struct {+ Message string `json:"message"`+ Type string `json:"type"`+ } `json:"error"`+ }+ if err := json.Unmarshal(w.Body.Bytes(), &response); err != nil {+ t.Fatalf("decode error response: %v", err)+ }+ if response.Error.Type != "invalid_request_error" {+ t.Errorf("error.type = %q, want invalid_request_error", response.Error.Type)+ }+ if response.Error.Message != "Agent run was cancelled." {+ t.Errorf("error.message = %q, want cancellation message", response.Error.Message)+ }+}+func TestAgentChatCompletions_OpenAICompat_MapsErrors(t *testing.T) {tests := []struct {name string@@ -1416,6 +1452,41 @@ func TestAgentChatCompletions_OpenAICompat_StreamSurfacesWaitingForUser(t *testi}}+func TestAgentChatCompletions_OpenAICompat_StreamSurfacesCancelled(t *testing.T) {+ gin.SetMode(gin.TestMode)+ w := httptest.NewRecorder()+ c, _ := gin.CreateTestContext(w)+ c.Request = httptest.NewRequest("POST", "/api/v1/agents/chat/completions",+ strings.NewReader(`{"agent_id":"a1","openai-compatible":true,"stream":true,"messages":[{"role":"user","content":"hi"}]}`))+ c.Request.Header.Set("Content-Type", "application/json")+ c.Set("user", &entity.User{ID: "u1"})+ c.Set("user_id", "u1")++ runner := &stubChatRunner{events: []canvas.RunEvent{+ {Type: "cancelled", Data: `{"message":"Agent run was cancelled."}`},+ }}+ h := &AgentHandler{chatRunner: runner}+ h.AgentChatCompletions(c)++ chunks, done := decodeOpenAICompatStream(t, w.Body.String())+ if done {+ t.Fatal("cancelled stream must not end with [DONE]")+ }+ if len(chunks) != 1 {+ t.Fatalf("decoded %d chunks, want cancellation state", len(chunks))+ }+ choices := chunks[0]["choices"].([]interface{})+ choice := choices[0].(map[string]interface{})+ if choice["finish_reason"] != "cancelled" {+ t.Errorf("finish_reason = %v, want cancelled", choice["finish_reason"])+ }+ delta := choice["delta"].(map[string]interface{})+ cancelled := delta["cancelled"].(map[string]interface{})+ if cancelled["message"] != "Agent run was cancelled." {+ t.Errorf("cancelled payload = %v, want cancellation message", cancelled)+ }+}+func decodeOpenAICompatStream(t *testing.T, body string) ([]map[string]interface{}, bool) {t.Helper()frames := strings.Split(strings.TrimSuffix(body, "\n\n"), "\n\n")diff --git a/internal/service/agent.go b/internal/service/agent.goindex 41674f473d..7b878c913d 100644--- a/internal/service/agent.go+++ b/internal/service/agent.go@@ -1464,6 +1464,10 @@ func (s *AgentService) RunAgent(ctx context.Context, userID, canvasID, sessionIDrunID := runIDFor(canvasID, map[string]any{"session_id": sessionID})lockToken := utility.GenerateToken()runCtx, cancelRun := context.WithCancel(ctx)+ // Keep workflow cancellation separate from event-consumer cancellation.+ // An explicit session cancellation should still reach an attached client,+ // while a disconnected HTTP request must stop event delivery promptly.+ runCtx = canvas.WithEventContext(runCtx, ctx)active := &activeAgentRun{userID: userID,canvasID: canvasID,@@ -1899,7 +1903,7 @@ func (s *AgentService) buildRunFunc(canvasID string, versionRow *entity.UserCanvif events == nil {return}- canvas.PushEvent(events, canvas.RunEvent{+ canvas.PushEvent(ctx, events, canvas.RunEvent{Type: typ, Data: data,MessageID: messageID,CreatedAt: time.Now().Unix(),