Skip to content

RAGFlow is an agent-native database: a Retrieval-Augmented Generation (RAG) engine that grew into context infrastructure.

fix(agent): surface cancellation terminal state (#18579)

Guofang.Tangda68cad1a08e
diff --git a/internal/agent/canvas/runner.go b/internal/agent/canvas/runner.go
index 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 canvas
import (
@@ -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 to
diff --git a/internal/agent/canvas/runner_cancel_test.go b/internal/agent/canvas/runner_cancel_test.go
index 6cc00af7d0..990a519fa2 100644
--- a/internal/agent/canvas/runner_cancel_test.go
+++ b/internal/agent/canvas/runner_cancel_test.go
@@ -6,6 +6,7 @@ package canvas
import (
"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.go
index 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.go
index 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.go
index 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.go
index 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, sessionID
runID := 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.UserCanv
if events == nil {
return
}
- canvas.PushEvent(events, canvas.RunEvent{
+ canvas.PushEvent(ctx, events, canvas.RunEvent{
Type: typ, Data: data,
MessageID: messageID,
CreatedAt: time.Now().Unix(),