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
feat(agent): inspect model inputs during single-node test runs (#21449)
okht961be3d5d39e
diff --git a/internal/entity/models/llm.go b/internal/entity/models/llm.goindex 118d64531c..233a97c7ac 100644--- a/internal/entity/models/llm.go+++ b/internal/entity/models/llm.go@@ -391,6 +391,7 @@ func (m *EinoChatModel) labelOf(idx int) string {}// generateOnce runs one Generate attempt against a single chain entry.+// It captures normalized input immediately before the driver call when enabled.func (m *EinoChatModel) generateOnce(ctx context.Context, cm *ChatModel, msgs []*schema.Message, opts ...model.Option) (*schema.Message, error) {if cm == nil || cm.ModelDriver == nil {return nil, fmt.Errorf("models: EinoChatModel: nil inner ModelDriver")@@ -430,6 +431,7 @@ func (m *EinoChatModel) generateOnce(ctx context.Context, cm *ChatModel, msgs [])common.Debug("models: eino generate message skeleton",zap.String("skeleton", describeInternalMessages(internal)))+ captureModelInput(ctx, *cm.ModelName, internal)resp, err := cm.ModelDriver.ChatWithMessages(ctx, *cm.ModelName, internal, cm.APIConfig, chatCfg, nil)if err != nil {// The chat paths surface this to the user as `**ERROR**: <err>`@@ -787,6 +789,7 @@ func containsToolResult(messages []Message) bool {// With a failover chain, a stream that fails BEFORE any delta was emitted// moves to the next model; once deltas have reached the client the call// cannot be replayed, so the error is surfaced as-is.+// Opt-in input capture records each actual driver attempt, including failover.func (m *EinoChatModel) Stream(ctx context.Context, msgs []*schema.Message, opts ...model.Option) (*schema.StreamReader[*schema.Message], error) {if m == nil || len(m.chain) == 0 {return nil, fmt.Errorf("models: EinoChatModel: empty model chain")@@ -919,6 +922,7 @@ func (m *EinoChatModel) Stream(ctx context.Context, msgs []*schema.Message, opts}attemptCfg.ToolCallsResult = nilattemptCfg.UsageResult = nil+ captureModelInput(ctx, *cm.ModelName, internalMessage)err := cm.ModelDriver.ChatStreamlyWithSender(ctx, *cm.ModelName, internalMessage, cm.APIConfig, attemptCfg, nil, sender)if err != nil {// Same user-visible shape as generateOnce's error: lead with thediff --git a/internal/entity/models/model_input_capture.go b/internal/entity/models/model_input_capture.gonew file mode 100644index 0000000000..3d20088dc0--- /dev/null+++ b/internal/entity/models/model_input_capture.go@@ -0,0 +1,229 @@+package models++import (+ "context"+ "encoding/json"+ "sync"+)++const (+ maxModelInputCalls = 32+ maxModelInputBytes = 1 << 20+ // Reserve the result envelope, commas, and the largest uint64 summary.+ modelInputSummaryReserve = 128 + maxModelInputCalls+ // Keep space for ordinary omission markers after a large captured call.+ modelInputOmissionReserve = 1024+)++type modelInputCaptureKey struct{}++// ModelInputCall describes one attempted provider-driver invocation. Captured+// messages are the normalized input, before provider-specific serialization.+type ModelInputCall struct {+ Sequence uint64 `json:"sequence"`+ Model string `json:"model"`+ Status string `json:"status"`+ Messages json.RawMessage `json:"messages,omitempty"`+ Reason string `json:"reason,omitempty"`+}++// ModelInputs is a bounded, request-local diagnostic result.+type ModelInputs struct {+ Calls []ModelInputCall `json:"calls"`+ OmittedCount uint64 `json:"omitted_count"`+}++type modelInputMessage struct {+ Role string `json:"role"`+ Content any `json:"content"`+ ToolCalls []map[string]any `json:"tool_calls,omitempty"`+ ToolCallID string `json:"tool_call_id,omitempty"`+}++// ModelInputCapture owns its JSON snapshots and never retains provider objects.+// It is enabled only by the single-component debug endpoint.+type ModelInputCapture struct {+ mu sync.Mutex+ sealed bool+ sequence uint64+ bytes int+ result ModelInputs+}++// WithModelInputCapture creates an isolated collector for this request.+func WithModelInputCapture(ctx context.Context) (context.Context, *ModelInputCapture) {+ capture := &ModelInputCapture{result: ModelInputs{Calls: []ModelInputCall{}}}+ return context.WithValue(ctx, modelInputCaptureKey{}, capture), capture+}++// Finalize seals the collector. Work completing after the response is assembled+// cannot mutate its result or retain more messages.+func (c *ModelInputCapture) Finalize() ModelInputs {+ c.mu.Lock()+ defer c.mu.Unlock()+ c.sealed = true+ result := ModelInputs{Calls: make([]ModelInputCall, len(c.result.Calls)), OmittedCount: c.result.OmittedCount}+ for i, call := range c.result.Calls {+ call.Messages = append(json.RawMessage(nil), call.Messages...)+ result.Calls[i] = call+ }+ return result+}++// captureModelInput records an attempt only when the context has a collector.+func captureModelInput(ctx context.Context, model string, messages []Message) {+ capture, _ := ctx.Value(modelInputCaptureKey{}).(*ModelInputCapture)+ if capture == nil {+ return+ }+ capture.record(model, messages)+}++// record serializes one attempt within the count and byte limits, retaining+// omission reasons when space permits and ignoring calls after finalization.+func (c *ModelInputCapture) record(model string, messages []Message) {+ c.mu.Lock()+ defer c.mu.Unlock()+ if c.sealed {+ return+ }+ c.sequence+++ if c.sequence > maxModelInputCalls {+ c.result.OmittedCount+++ return+ }+ // Reserve 1 KiB for each remaining attempt, so ordinary model identifiers+ // can still retain an omission reason when captured content fills its budget.+ futureMarkers := (maxModelInputCalls - int(c.sequence)) * modelInputOmissionReserve+ remaining := maxModelInputBytes - modelInputSummaryReserve - c.bytes - futureMarkers+ call := ModelInputCall{Sequence: c.sequence, Model: model, Status: "captured"}+ call.Messages, call.Reason = snapshotModelInput(messages, remaining-len(model))+ if call.Reason == "" {+ encoded, err := json.Marshal(call)+ if err == nil && len(encoded) <= remaining {+ c.bytes += len(encoded)+ c.result.Calls = append(c.result.Calls, call)+ return+ }+ call.Reason = "size_limit"+ }+ c.result.OmittedCount+++ call.Status, call.Messages = "omitted", nil+ // An exceptionally long model identifier may exceed its remaining budget.+ // Keep only the count, preserving the reserved space for subsequent markers.+ if len(model) > remaining {+ return+ }+ encoded, err := json.Marshal(call)+ if err == nil && len(encoded) <= remaining {+ c.bytes += len(encoded)+ c.result.Calls = append(c.result.Calls, call)+ }+}++// snapshotModelInput copies the allowed text-message fields into owned JSON or+// returns an omission reason without propagating serialization failures.+func snapshotModelInput(messages []Message, budget int) (snapshot json.RawMessage, reason string) {+ // Diagnostic serialization must never prevent a model call.+ defer func() {+ if recover() != nil {+ snapshot, reason = nil, "serialization_error"+ }+ }()+ if budget <= 0 || len(messages) > budget/16 {+ return nil, "size_limit"+ }+ remaining := budget+ retained := make([]modelInputMessage, 0, len(messages))+ for _, message := range messages {+ if parts, ok := message.Content.([]any); ok && len(parts) > remaining/2 {+ return nil, "size_limit"+ }+ if !modelInputTextContent(message.Content) || message.Audio != nil {+ return nil, "unsupported_content"+ }+ for _, value := range []any{message.Role, message.Content, message.ToolCallID, message.ToolCalls} {+ if reason := preflightModelInput(value, &remaining, 0); reason != "" {+ return nil, reason+ }+ }+ retained = append(retained, modelInputMessage{+ Role: message.Role, Content: message.Content,+ ToolCalls: message.ToolCalls, ToolCallID: message.ToolCallID,+ })+ }+ snapshot, err := json.Marshal(retained)+ if err != nil {+ return nil, "serialization_error"+ }+ if len(snapshot) > budget {+ return nil, "size_limit"+ }+ return snapshot, ""+}++// modelInputTextContent accepts strings, nil, and lists of text-only blocks.+func modelInputTextContent(content any) bool {+ switch value := content.(type) {+ case string, nil:+ return true+ case []any:+ for _, part := range value {+ block, ok := part.(map[string]any)+ if !ok || len(block) != 2 || block["type"] != "text" {+ return false+ }+ if _, ok := block["text"].(string); !ok {+ return false+ }+ }+ return true+ default:+ return false+ }+}++// preflightModelInput bounds traversal and string sizes before allocating JSON.+// It accepts only plain JSON values produced by message normalization.+func preflightModelInput(value any, budget *int, depth int) string {+ if depth > 32 {+ return "serialization_error"+ }+ *budget -= 2+ if *budget < 0 {+ return "size_limit"+ }+ switch value := value.(type) {+ case nil, bool, float64, int, int64:+ return ""+ case json.Number:+ *budget -= len(value)+ case string:+ *budget -= len(value)+ case []any:+ for _, child := range value {+ if reason := preflightModelInput(child, budget, depth+1); reason != "" {+ return reason+ }+ }+ case []map[string]any:+ for _, child := range value {+ if reason := preflightModelInput(child, budget, depth+1); reason != "" {+ return reason+ }+ }+ case map[string]any:+ for key, child := range value {+ *budget -= len(key)+ if reason := preflightModelInput(child, budget, depth+1); reason != "" {+ return reason+ }+ }+ default:+ return "serialization_error"+ }+ if *budget < 0 {+ return "size_limit"+ }+ return ""+}diff --git a/internal/entity/models/model_input_capture_test.go b/internal/entity/models/model_input_capture_test.gonew file mode 100644index 0000000000..ecbc5b2658--- /dev/null+++ b/internal/entity/models/model_input_capture_test.go@@ -0,0 +1,301 @@+package models++import (+ "context"+ "encoding/json"+ "errors"+ "fmt"+ "io"+ "strings"+ "sync"+ "testing"++ "github.com/cloudwego/eino/schema"++ "ragflow/internal/common"+)++// TestModelInputCaptureOwnsSnapshotAndSeals checks the field allowlist, snapshot+// ownership, and rejection of writes after finalization.+func TestModelInputCaptureOwnsSnapshotAndSeals(t *testing.T) {+ ctx, capture := WithModelInputCapture(t.Context())+ function := map[string]any{"name": "lookup", "arguments": `{"q":"original"}`}+ messages := []Message{+ {Role: "system", Content: "instruction", Name: "excluded-name", FunctionCall: "excluded-function", Refusal: "excluded-refusal"},+ {Role: "assistant", Content: "", ToolCalls: []map[string]any{{"id": "call-1", "type": "function", "function": function}}},+ {Role: "tool", Content: "original", ToolCallID: "call-1"},+ }+ captureModelInput(ctx, "actual-model", messages)+ messages[0].Content = "changed"+ function["arguments"] = "changed"+ result := capture.Finalize()+ captureModelInput(ctx, "late", messages)+ if len(result.Calls) != 1 || result.Calls[0].Model != "actual-model" || result.Calls[0].Sequence != 1 || result.Calls[0].Status != "captured" {+ t.Fatalf("unexpected calls: %+v", result)+ }+ if strings.Contains(string(result.Calls[0].Messages), "changed") || !strings.Contains(string(result.Calls[0].Messages), "original") {+ t.Fatalf("snapshot changed: %s", result.Calls[0].Messages)+ }+ if strings.Contains(string(result.Calls[0].Messages), "excluded-") {+ t.Fatalf("fields outside the snapshot contract leaked: %s", result.Calls[0].Messages)+ }+ if got := capture.Finalize(); len(got.Calls) != 1 || got.OmittedCount != 0 {+ t.Fatalf("late call changed finalized result: %+v", got)+ }+}++// TestModelInputCaptureReservesLaterOmissionReasons checks that large calls leave+// room for later omission markers and small captured calls.+func TestModelInputCaptureReservesLaterOmissionReasons(t *testing.T) {+ empty, _ := json.Marshal(ModelInputCall{+ Sequence: 1, Model: "fill", Status: "captured",+ Messages: json.RawMessage(`[{"role":"user","content":""}]`),+ })+ for _, tc := range []struct {+ name string+ textBytes int+ firstStatus string+ omitted uint64+ }{+ {"near capture limit", maxModelInputBytes - modelInputSummaryReserve - (maxModelInputCalls-1)*modelInputOmissionReserve - 256, "captured", 1},+ // Without marker headroom this call fills every available byte, leaving+ // later ordinary omissions with no place to explain their reason.+ {"would consume marker headroom", maxModelInputBytes - modelInputSummaryReserve - len(empty), "omitted", 2},+ } {+ t.Run(tc.name, func(t *testing.T) {+ ctx, capture := WithModelInputCapture(t.Context())+ captureModelInput(ctx, "fill", []Message{{Role: "user", Content: strings.Repeat("x", tc.textBytes)}})+ captureModelInput(ctx, "image", []Message{{Role: "user", Content: []any{+ map[string]any{"type": "image_url", "image_url": map[string]any{"url": "private"}},+ }}})+ captureModelInput(ctx, "small", []Message{{Role: "user", Content: "still fits"}})+ result := capture.Finalize()+ if len(result.Calls) != 3 || result.Calls[0].Status != tc.firstStatus || result.Calls[1].Reason != "unsupported_content" || result.Calls[2].Status != "captured" || result.OmittedCount != tc.omitted {+ t.Fatalf("near-limit capture lost subsequent diagnostics: calls=%d omitted=%d", len(result.Calls), result.OmittedCount)+ }+ if tc.firstStatus == "omitted" && result.Calls[0].Reason != "size_limit" {+ t.Fatalf("large call reason = %q", result.Calls[0].Reason)+ }+ encoded, err := json.Marshal(result)+ if err != nil || len(encoded) > maxModelInputBytes {+ t.Fatalf("result exceeds total budget: bytes=%d err=%v", len(encoded), err)+ }+ })+ }+}++// TestModelInputCaptureOmissionsAndLaterSmallCall checks all omission reasons,+// omitted-content exclusion, and retention of a subsequent small call.+func TestModelInputCaptureOmissionsAndLaterSmallCall(t *testing.T) {+ ctx, capture := WithModelInputCapture(t.Context())+ captureModelInput(ctx, "image", []Message{{Role: "user", Content: []any{+ map[string]any{"type": "text", "text": "visible text"},+ map[string]any{"type": "image_url", "image_url": map[string]any{"url": "data:image/png;base64,private"}},+ }}})+ captureModelInput(ctx, "large", []Message{{Role: "user", Content: strings.Repeat("x", maxModelInputBytes+1)}})+ captureModelInput(ctx, "invalid", []Message{{Role: "assistant", Content: "", ToolCalls: []map[string]any{{"bad": json.Number("invalid")}}}})+ captureModelInput(ctx, "small", []Message{{Role: "user", Content: "small"}})+ result := capture.Finalize()+ if len(result.Calls) != 4 || result.OmittedCount != 3 {+ t.Fatalf("unexpected result: %+v", result)+ }+ for i, reason := range []string{"unsupported_content", "size_limit", "serialization_error"} {+ if call := result.Calls[i]; call.Status != "omitted" || call.Reason != reason || len(call.Messages) != 0 {+ t.Fatalf("call %d = %+v, want omission %s", i, call, reason)+ }+ }+ if result.Calls[3].Status != "captured" {+ t.Fatalf("later small call was lost: %+v", result.Calls[3])+ }+ encoded, err := json.Marshal(result)+ if err != nil || strings.Contains(string(encoded), "private") || strings.Contains(string(encoded), "visible text") {+ t.Fatalf("omitted call leaked content: %s (%v)", encoded, err)+ }+}++// TestModelInputCaptureBoundsWholeResult checks serialized size and call limits,+// including escaped text, oversized model names, and omitted-call accounting.+func TestModelInputCaptureBoundsWholeResult(t *testing.T) {+ ctx, capture := WithModelInputCapture(t.Context())+ // Escaping expands '<' to six bytes; the serialized budget must catch it.+ captureModelInput(ctx, "escaped", []Message{{Role: "user", Content: strings.Repeat("<", maxModelInputBytes/4)}})+ captureModelInput(ctx, strings.Repeat("m", maxModelInputBytes+1), []Message{{Role: "user", Content: "small"}})+ for i := 0; i < 40; i++ {+ captureModelInput(ctx, fmt.Sprintf("model-%d", i), []Message{{Role: "user", Content: strings.Repeat("x", 45000)}})+ }+ result := capture.Finalize()+ encoded, err := json.Marshal(result)+ if err != nil || len(encoded) > maxModelInputBytes || len(result.Calls) > maxModelInputCalls {+ t.Fatalf("unbounded result: bytes=%d calls=%d err=%v", len(encoded), len(result.Calls), err)+ }+ captured := uint64(0)+ for _, call := range result.Calls {+ if call.Status == "captured" {+ captured+++ }+ }+ if captured+result.OmittedCount != 42 {+ t.Fatalf("omitted count excludes placeholders or overflow: captured=%d result=%+v", captured, result)+ }+}++// TestModelInputCaptureCountAndRequestIsolation checks concurrent call counting,+// sequence ordering, and separation between request-local collectors.+func TestModelInputCaptureCountAndRequestIsolation(t *testing.T) {+ ctxA, captureA := WithModelInputCapture(t.Context())+ ctxB, captureB := WithModelInputCapture(t.Context())+ var workers sync.WaitGroup+ for i := 0; i < 80; i++ {+ workers.Add(1)+ go func() {+ defer workers.Done()+ captureModelInput(ctxA, "A", []Message{{Role: "user", Content: "only A"}})+ captureModelInput(ctxB, "B", []Message{{Role: "user", Content: "only B"}})+ }()+ }+ workers.Wait()+ for name, result := range map[string]ModelInputs{"A": captureA.Finalize(), "B": captureB.Finalize()} {+ if len(result.Calls) != 32 || result.OmittedCount != 48 {+ t.Fatalf("%s: calls=%d omitted=%d", name, len(result.Calls), result.OmittedCount)+ }+ for i, call := range result.Calls {+ if call.Model != name || call.Sequence != uint64(i+1) || !strings.Contains(string(call.Messages), "only "+name) {+ t.Fatalf("request isolation/order failure: %+v", call)+ }+ }+ }+}++type modelInputDriver struct {+ *captureToolDriver+ invoke func([]Message) error+ calls int+}++// ChatWithMessages counts the stub invocation, runs its optional hook, and+// returns a fixed answer when the hook succeeds.+func (d *modelInputDriver) ChatWithMessages(_ context.Context, _ string, messages []Message, _ *APIConfig, _ *ChatConfig, _ *common.ModelUsage) (*ChatResponse, error) {+ d.calls+++ if d.invoke != nil {+ if err := d.invoke(messages); err != nil {+ return nil, err+ }+ }+ answer := "ok"+ return &ChatResponse{Answer: &answer}, nil+}++// ChatStreamlyWithSender counts the stub invocation, runs its optional hook,+// and sends a fixed answer when the hook succeeds.+func (d *modelInputDriver) ChatStreamlyWithSender(_ context.Context, _ string, messages []Message, _ *APIConfig, _ *ChatConfig, _ *common.ModelUsage, sender func(*string, *string) error) error {+ d.calls+++ if d.invoke != nil {+ if err := d.invoke(messages); err != nil {+ return err+ }+ }+ answer := "ok"+ return sender(&answer, nil)+}++// consumeModelInputStream drains and closes a stream, returning any non-EOF error.+func consumeModelInputStream(t *testing.T, stream *schema.StreamReader[*schema.Message]) error {+ t.Helper()+ defer stream.Close()+ for {+ _, err := stream.Recv()+ if err == io.EOF {+ return nil+ }+ if err != nil {+ return err+ }+ }+}++// TestModelInputCaptureDriverAttemptsAndFailure checks model names and immutable+// snapshots for failed and successful attempts in both generation paths.+func TestModelInputCaptureDriverAttemptsAndFailure(t *testing.T) {+ for _, streaming := range []bool{false, true} {+ t.Run(fmt.Sprintf("stream=%v", streaming), func(t *testing.T) {+ ctx, capture := WithModelInputCapture(t.Context())+ first, second := "primary", "fallback"+ failed := &modelInputDriver{captureToolDriver: &captureToolDriver{}, invoke: func([]Message) error { return errors.New("unavailable") }}+ succeeded := &modelInputDriver{captureToolDriver: &captureToolDriver{}, invoke: func(messages []Message) error {+ messages[0].Content = "provider mutation"+ return nil+ }}+ model, err := NewFailoverEinoChatModel([]*ChatModel{+ NewChatModel(failed, &first, &APIConfig{}),+ NewChatModel(succeeded, &second, &APIConfig{}),+ }, nil)+ if err != nil {+ t.Fatal(err)+ }+ messages := []*schema.Message{schema.SystemMessage("original")}+ if streaming {+ stream, err := model.Stream(ctx, messages)+ if err != nil {+ t.Fatal(err)+ }+ if err := consumeModelInputStream(t, stream); err != nil {+ t.Fatal(err)+ }+ } else if _, err := model.Generate(ctx, messages); err != nil {+ t.Fatal(err)+ }+ result := capture.Finalize()+ if failed.calls != 1 || succeeded.calls != 1 || len(result.Calls) != 2 {+ t.Fatalf("attempts do not match driver calls: failed=%d succeeded=%d result=%+v", failed.calls, succeeded.calls, result)+ }+ for i, name := range []string{first, second} {+ if call := result.Calls[i]; call.Model != name || call.Sequence != uint64(i+1) || !strings.Contains(string(call.Messages), "original") {+ t.Fatalf("wrong attempt snapshot: %+v", call)+ }+ }+ })+ }+}++// TestModelInputCaptureToolStreamDelegatesOnce checks that Stream's delegation+// to Generate records exactly one provider invocation.+func TestModelInputCaptureToolStreamDelegatesOnce(t *testing.T) {+ ctx, capture := WithModelInputCapture(t.Context())+ name := "tool-model"+ driver := &modelInputDriver{captureToolDriver: &captureToolDriver{}}+ model := NewEinoChatModel(NewChatModel(driver, &name, &APIConfig{}), nil)+ bound, err := model.WithTools([]*schema.ToolInfo{{Name: "lookup"}})+ if err != nil {+ t.Fatal(err)+ }+ stream, err := bound.Stream(ctx, []*schema.Message{schema.UserMessage("hello")})+ if err != nil {+ t.Fatal(err)+ }+ if err := consumeModelInputStream(t, stream); err != nil {+ t.Fatal(err)+ }+ if result := capture.Finalize(); driver.calls != 1 || len(result.Calls) != 1 {+ t.Fatalf("Stream-to-Generate duplicated capture: driver=%d result=%+v", driver.calls, result)+ }+}++// TestModelInputOmissionDoesNotPreventProviderCall checks that unsupported+// diagnostic content does not prevent the provider from receiving the call.+func TestModelInputOmissionDoesNotPreventProviderCall(t *testing.T) {+ ctx, capture := WithModelInputCapture(t.Context())+ name := "vision"+ driver := &modelInputDriver{captureToolDriver: &captureToolDriver{}}+ model := NewEinoChatModel(NewChatModel(driver, &name, &APIConfig{}), nil)+ url := "data:image/png;base64,private"+ _, err := model.Generate(ctx, []*schema.Message{{Role: schema.User, UserInputMultiContent: []schema.MessageInputPart{{+ Type: schema.ChatMessagePartTypeImageURL,+ Image: &schema.MessageInputImage{MessagePartCommon: schema.MessagePartCommon{URL: &url}},+ }}}})+ if err != nil || driver.calls != 1 {+ t.Fatalf("capture affected provider execution: calls=%d err=%v", driver.calls, err)+ }+ if result := capture.Finalize(); len(result.Calls) != 1 || result.Calls[0].Reason != "unsupported_content" {+ t.Fatalf("unexpected capture: %+v", result)+ }+}diff --git a/internal/handler/agent_component.go b/internal/handler/agent_component.goindex 977ed36364..cc9e8c45a1 100644--- a/internal/handler/agent_component.go+++ b/internal/handler/agent_component.go@@ -30,6 +30,7 @@ package handlerimport ("context"+ "encoding/json""errors""fmt""strings"@@ -37,10 +38,14 @@ import ("github.com/gin-gonic/gin""ragflow/internal/agent/canvas"+ "ragflow/internal/agent/component""ragflow/internal/agent/dsl""ragflow/internal/agent/runtime""ragflow/internal/common""ragflow/internal/dao"+ "ragflow/internal/entity/models"+ "ragflow/internal/permission"+ "ragflow/internal/service")// GetComponentInputForm GET /api/v1/agents/:canvas_id/components/:component_id/input-form@@ -110,13 +115,10 @@ func (h *AgentHandler) componentInputForm(ctx context.Context, dslMap map[stringreturn form, nil}-// DebugComponent POST /api/v1/agents/:canvas_id/components/:component_id/debug-//-// Body shape (python parity): {"params": {"input_name": {"value": ...}, ...}}-//-// The python reference calls `component.invoke(**{k: o["value"] for k, o in-// req["params"].items()})`. We replicate this by flattening each param's-// "value" field into the Invoke inputs map.+// DebugComponent handles POST /api/v1/agents/:canvas_id/components/:component_id/debug.+// It flattens params.*.value into component inputs and returns the debug outputs.+// An Agent request with include_model_inputs=true requires update permission and+// wraps outputs with request-local model-input diagnostics, including on failure.func (h *AgentHandler) DebugComponent(c *gin.Context) {user, code, msg := GetUser(c)if code != common.CodeSuccess {@@ -131,7 +133,8 @@ func (h *AgentHandler) DebugComponent(c *gin.Context) {}var body struct {- Params map[string]map[string]any `json:"params"`+ Params map[string]map[string]any `json:"params"`+ IncludeModelInputs json.RawMessage `json:"include_model_inputs"`}if err := c.ShouldBindJSON(&body); err != nil {common.ResponseWithCodeData(c, common.CodeArgumentError, nil, "Invalid request: "+err.Error())@@ -141,6 +144,15 @@ func (h *AgentHandler) DebugComponent(c *gin.Context) {common.ResponseWithCodeData(c, common.CodeArgumentError, nil, "`params` is required.")return}+ includeModelInputs := false+ switch strings.TrimSpace(string(body.IncludeModelInputs)) {+ case "", "false":+ case "true":+ includeModelInputs = true+ default:+ common.ResponseWithCodeData(c, common.CodeArgumentError, nil, "`include_model_inputs` must be a boolean.")+ return+ }cv, err := h.loader.LoadCanvasByID(c.Request.Context(), user.ID, canvasID)if err != nil {@@ -194,6 +206,20 @@ func (h *AgentHandler) DebugComponent(c *gin.Context) {common.ResponseWithCodeData(c, common.CodeDataError, nil, "component factory: "+err.Error())return}+ if includeModelInputs {+ if _, ok := comp.(*component.AgentComponent); !ok {+ common.ResponseWithCodeData(c, common.CodeArgumentError, nil, "Model inputs are available only for Agent components.")+ return+ }+ if err := service.CheckCanvasPermission(c.Request.Context(), permission.Subject{UserID: user.ID}, canvasID, permission.OperationUpdate); err != nil {+ if errors.Is(err, permission.ErrResourceNotFound) || errors.Is(err, permission.ErrPermissionDenied) {+ common.ResponseWithCodeData(c, common.CodeOperatingError, nil, canvasNoAccessMessage)+ } else {+ common.ResponseWithCodeData(c, common.CodeServerError, nil, err.Error())+ }+ return+ }+ }// D4: skip set_debug_inputs (python-only LLM debug hook). The// raw Invoke already supports the same inputs.@@ -235,16 +261,31 @@ func (h *AgentHandler) DebugComponent(c *gin.Context) {debugState.SetSys("canvas_id", cv.ID)debugState.SetSys("user_id", user.ID)invokeCtx := runtime.WithState(c.Request.Context(), debugState)+ var capture *models.ModelInputCapture+ if includeModelInputs {+ invokeCtx, capture = models.WithModelInputCapture(invokeCtx)+ defer capture.Finalize()+ }outputs, err := runtime.TrackElapsed(name, func() (map[string]any, error) {return comp.Invoke(invokeCtx, dao.DB, inputs)})+ var data any = outputs+ if capture != nil {+ data = struct {+ Outputs map[string]any `json:"outputs"`+ ModelInputs models.ModelInputs `json:"model_inputs"`+ }{Outputs: outputs, ModelInputs: capture.Finalize()}+ }if err != nil {- common.ResponseWithCodeData(c, common.CodeServerError, nil, "invoke: "+err.Error())+ if capture == nil {+ data = nil+ }+ common.ResponseWithCodeData(c, common.CodeServerError, data, "invoke: "+err.Error())return}- common.SuccessWithData(c, outputs, "success")+ common.SuccessWithData(c, data, "success")}// mapDSLError translates a dsl extractor error into a 102 envelope.diff --git a/internal/handler/agent_model_inputs_test.go b/internal/handler/agent_model_inputs_test.gonew file mode 100644index 0000000000..8374611338--- /dev/null+++ b/internal/handler/agent_model_inputs_test.go@@ -0,0 +1,222 @@+package handler++import (+ "encoding/json"+ "fmt"+ "net/http"+ "net/http/httptest"+ "reflect"+ "strings"+ "sync"+ "sync/atomic"+ "testing"++ "github.com/gin-gonic/gin"++ "ragflow/internal/common"+ "ragflow/internal/dao"+ "ragflow/internal/entity"+ "ragflow/internal/entity/models"+)++type modelInputDebugEnvelope struct {+ Code int `json:"code"`+ Message string `json:"message"`+ Data json.RawMessage `json:"data"`+}++// setupModelInputDebug creates an owned Agent canvas backed by an isolated test+// database and configures its provider to use the supplied HTTP endpoint.+func setupModelInputDebug(t *testing.T, endpoint string) (*AgentHandler, *entity.UserCanvas) {+ t.Helper()+ db := setupHandlerAgentsTestDB(t)+ previous := dao.DB+ dao.DB = db+ t.Cleanup(func() { dao.DB = previous })+ previousHostSetting := common.AllowAnyHostForTest+ common.AllowAnyHostForTest = true+ t.Cleanup(func() { common.AllowAnyHostForTest = previousHostSetting })+ if err := models.InitProviderManager("../../conf/models"); err != nil {+ t.Fatalf("InitProviderManager: %v", err)+ }+ canvas := &entity.UserCanvas{+ ID: "c1", UserID: "u-1", Permission: "me",+ DSL: map[string]any{"components": map[string]any{+ "agent": map[string]any{"obj": map[string]any{+ "component_name": "Agent",+ "params": map[string]any{+ "llm_id": "qwen-flash", "driver": "Tongyi-Qianwen",+ "api_key": "private-test-key", "base_url": endpoint,+ "sys_prompt": "Follow the instruction", "user_prompt": "Hello {{source@content}}",+ "max_rounds": 1,+ },+ }},+ }},+ }+ if err := db.Create(canvas).Error; err != nil {+ t.Fatal(err)+ }+ return &AgentHandler{loader: &fakeCanvasLoader{canvas: canvas}}, canvas+}++// runModelInputDebug invokes Agent debug with the supplied raw JSON flag and+// decodes the response envelope; an empty flag omits the option.+func runModelInputDebug(t *testing.T, handler *AgentHandler, flag string) modelInputDebugEnvelope {+ t.Helper()+ extra := ""+ if flag != "" {+ extra = `,"include_model_inputs":` + flag+ }+ body := `{"params":{"source@content":{"value":"resolved"}}` + extra + `}`+ c, w := componentCtx(t, http.MethodPost, "/api/v1/agents/c1/components/agent/debug", body)+ c.Params = gin.Params{{Key: "canvas_id", Value: "c1"}, {Key: "component_id", Value: "agent"}}+ handler.DebugComponent(c)+ var envelope modelInputDebugEnvelope+ if err := json.Unmarshal(w.Body.Bytes(), &envelope); err != nil {+ t.Fatalf("response: %s (%v)", w.Body.String(), err)+ }+ return envelope+}++// TestDebugAgentModelInputsMatchProviderMessages checks the production Agent+// path's captured system and resolved user messages against the HTTP request.+func TestDebugAgentModelInputsMatchProviderMessages(t *testing.T) {+ var mu sync.Mutex+ var providerMessages json.RawMessage+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {+ var body struct {+ Messages json.RawMessage `json:"messages"`+ }+ if err := json.NewDecoder(r.Body).Decode(&body); err != nil {+ t.Error(err)+ }+ mu.Lock()+ providerMessages = body.Messages+ mu.Unlock()+ w.Header().Set("Content-Type", "text/event-stream")+ fmt.Fprint(w, "data: {\"choices\":[{\"index\":0,\"delta\":{\"content\":\"ok\"},\"finish_reason\":\"stop\"}]}\n\ndata: [DONE]\n\n")+ }))+ defer server.Close()+ handler, _ := setupModelInputDebug(t, server.URL)+ response := runModelInputDebug(t, handler, "true")+ if response.Code != 0 {+ t.Fatalf("debug failed: %+v", response)+ }+ var data struct {+ Outputs map[string]any `json:"outputs"`+ ModelInputs models.ModelInputs `json:"model_inputs"`+ }+ if err := json.Unmarshal(response.Data, &data); err != nil {+ t.Fatal(err)+ }+ if data.Outputs["content"] != "ok" || len(data.ModelInputs.Calls) != 1 || data.ModelInputs.OmittedCount != 0 {+ t.Fatalf("unexpected debug data: %s", response.Data)+ }+ call := data.ModelInputs.Calls[0]+ if call.Model != "qwen-flash" || call.Status != "captured" || call.Sequence != 1 {+ t.Fatalf("unexpected call: %+v", call)+ }+ var actual, expected any+ if err := json.Unmarshal(call.Messages, &actual); err != nil {+ t.Fatal(err)+ }+ mu.Lock()+ defer mu.Unlock()+ if err := json.Unmarshal(providerMessages, &expected); err != nil {+ t.Fatal(err)+ }+ if !reflect.DeepEqual(actual, expected) || !strings.Contains(string(call.Messages), "Follow the instruction") || !strings.Contains(string(call.Messages), "Hello resolved") {+ t.Fatalf("capture=%s provider=%s", call.Messages, providerMessages)+ }+ if strings.Contains(string(response.Data), "private-test-key") || strings.Contains(string(response.Data), server.URL) {+ t.Fatalf("provider configuration leaked: %s", response.Data)+ }+}++// TestDebugAgentModelInputsDefaultAndErrorContracts checks unchanged default+// outputs and error codes, with opt-in diagnostics retained on provider failure.+func TestDebugAgentModelInputsDefaultAndErrorContracts(t *testing.T) {+ var fail atomic.Bool+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {+ if fail.Load() {+ w.WriteHeader(http.StatusBadRequest)+ fmt.Fprint(w, `{"error":{"message":"provider rejected request"}}`)+ return+ }+ w.Header().Set("Content-Type", "text/event-stream")+ fmt.Fprint(w, "data: {\"choices\":[{\"index\":0,\"delta\":{\"content\":\"ok\"},\"finish_reason\":\"stop\"}]}\n\ndata: [DONE]\n\n")+ }))+ defer server.Close()+ handler, _ := setupModelInputDebug(t, server.URL)+ for _, flag := range []string{"", "false"} {+ response := runModelInputDebug(t, handler, flag)+ var outputs map[string]any+ if err := json.Unmarshal(response.Data, &outputs); err != nil {+ t.Fatal(err)+ }+ if response.Code != 0 || outputs["content"] != "ok" || outputs["model_inputs"] != nil || outputs["outputs"] != nil {+ t.Fatalf("default contract changed: %+v %s", response, response.Data)+ }+ }+ fail.Store(true)+ without := runModelInputDebug(t, handler, "false")+ with := runModelInputDebug(t, handler, "true")+ if without.Code == 0 || without.Code != with.Code || without.Message != with.Message || string(without.Data) != "null" {+ t.Fatalf("error contract changed: without=%+v with=%+v", without, with)+ }+ var data struct {+ Outputs map[string]any `json:"outputs"`+ ModelInputs models.ModelInputs `json:"model_inputs"`+ }+ if err := json.Unmarshal(with.Data, &data); err != nil {+ t.Fatal(err)+ }+ if data.Outputs != nil || len(data.ModelInputs.Calls) != 1 || data.ModelInputs.Calls[0].Status != "captured" {+ t.Fatalf("failed provider input was lost: %s", with.Data)+ }+}++// TestDebugAgentModelInputsRejectsInvalidFlagAndUnauthorizedExecution checks+// strict boolean validation and update authorization before provider execution.+func TestDebugAgentModelInputsRejectsInvalidFlagAndUnauthorizedExecution(t *testing.T) {+ var calls atomic.Int32+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {+ calls.Add(1)+ w.WriteHeader(http.StatusInternalServerError)+ }))+ defer server.Close()+ handler, _ := setupModelInputDebug(t, server.URL)+ for _, flag := range []string{`null`, `"true"`, `1`, `{}`, `[]`} {+ if response := runModelInputDebug(t, handler, flag); response.Code != int(common.CodeArgumentError) || string(response.Data) != "null" {+ t.Fatalf("flag %s accepted: %+v", flag, response)+ }+ }+ // The read-side loader deliberately succeeds. The debug endpoint must still+ // check Update against the stored canvas before any Agent/model execution.+ if err := dao.DB.Model(&entity.UserCanvas{}).Where("id = ?", "c1").Update("user_id", "another-owner").Error; err != nil {+ t.Fatal(err)+ }+ response := runModelInputDebug(t, handler, "true")+ if response.Code != int(common.CodeOperatingError) || response.Message != canvasNoAccessMessage || string(response.Data) != "null" {+ t.Fatalf("unauthorized result: %+v", response)+ }+ if calls.Load() != 0 {+ t.Fatalf("rejected requests executed %d provider calls", calls.Load())+ }+}++// TestDebugModelInputsRejectsNonAgent checks that other component types cannot+// opt into model-input capture.+func TestDebugModelInputsRejectsNonAgent(t *testing.T) {+ handler := &AgentHandler{loader: &fakeCanvasLoader{canvas: beginCanvas()}}+ c, w := componentCtx(t, http.MethodPost, "/api/v1/agents/c1/components/begin/debug", `{"params":{"query":{"value":"hello"}},"include_model_inputs":true}`)+ c.Params = gin.Params{{Key: "canvas_id", Value: "c1"}, {Key: "component_id", Value: "begin"}}+ handler.DebugComponent(c)+ var response modelInputDebugEnvelope+ if err := json.Unmarshal(w.Body.Bytes(), &response); err != nil {+ t.Fatal(err)+ }+ if response.Code != int(common.CodeArgumentError) || string(response.Data) != "null" {+ t.Fatalf("non-Agent capture accepted: %+v", response)+ }+}diff --git a/web/src/hooks/use-agent-request.ts b/web/src/hooks/use-agent-request.tsindex 68cf93b3a5..eddb63b707 100644--- a/web/src/hooks/use-agent-request.ts+++ b/web/src/hooks/use-agent-request.ts@@ -34,10 +34,7 @@ import {ITraceData,IWebhookTrace,} from '@/interfaces/database/agent';-import {- IAgentWebhookTraceRequest,- IDebugSingleRequestBody,-} from '@/interfaces/request/agent';+import { IAgentWebhookTraceRequest } from '@/interfaces/request/agent';import i18n from '@/locales/config';import { IInputs } from '@/pages/agent/interface';import { useGetSharedChatSearchParams } from '@/pages/next-chats/hooks/use-send-shared-message';@@ -732,35 +729,6 @@ export const useTestDbConnect = () => {return { data, loading, testDbConnect: mutateAsync };};-export const useDebugSingle = () => {- const { id } = useParams();- const {- data,- isPending: loading,- mutateAsync,- } = useMutation({- mutationKey: [AgentApiAction.DebugSingle],- mutationFn: async (params: IDebugSingleRequestBody) => {- const ret = await agentService.debugSingle(- {- agentId: id as string,- componentId: params.component_id,- data: {- params: params.params,- },- },- true,- );- if (ret?.data?.code !== 0) {- message.error(ret?.data?.message);- }- return ret?.data?.data;- },- });-- return { data, loading, debugSingle: mutateAsync };-};-export const useFetchInputForm = (componentId?: string) => {const { id } = useParams();diff --git a/web/src/hooks/use-single-debug-request.test.tsx b/web/src/hooks/use-single-debug-request.test.tsxnew file mode 100644index 0000000000..a088a1ee51--- /dev/null+++ b/web/src/hooks/use-single-debug-request.test.tsx@@ -0,0 +1,212 @@+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';+import { act, renderHook } from '@testing-library/react';+import { useState } from 'react';+import { useDebugSingle } from './use-single-debug-request';++const mockDebug = jest.fn();+const mockError = jest.fn();++jest.mock('@/services/agent-service', () => ({+ __esModule: true,+ default: { debugSingle: (...args: unknown[]) => mockDebug(...args) },+}));+jest.mock('@/components/ui/message', () => ({+ __esModule: true,+ default: { error: (...args: unknown[]) => mockError(...args) },+}));+jest.mock('react-router', () => ({ useParams: () => ({ id: 'agent-1' }) }));++/** Gives each mounted hook test its own stable React Query client. */+function wrapper({ children }: { children?: any }) {+ const [client] = useState(() => new QueryClient());+ return <QueryClientProvider client={client}>{children}</QueryClientProvider>;+}++/** Lets a test resolve requests out of order to check stale-response handling. */+function pendingResponse() {+ let resolve!: (value: any) => void;+ const promise = new Promise((done) => {+ resolve = done;+ });+ return { promise, resolve };+}++const Request = { component_id: 'Agent:1', params: { question: 'Hello' } };+const Snapshot = {+ calls: [+ {+ sequence: 1,+ model: 'test',+ status: 'captured',+ messages: [{ role: 'user', content: 'Hello' }],+ },+ ],+ omitted_count: 0,+};++beforeEach(() => {+ mockDebug.mockReset();+ mockError.mockReset();+});++it('keeps legacy outputs intact even when they contain envelope-like keys', async () => {+ const output = {+ outputs: 'business value',+ model_inputs: 'another business value',+ };+ mockDebug.mockResolvedValue({ data: { code: 0, message: '', data: output } });+ const { result } = renderHook(() => useDebugSingle('Agent:1'), { wrapper });+ await act(async () => {+ await result.current.debugSingle(Request);+ });+ expect(mockDebug.mock.calls[0][0].data).toEqual({ params: Request.params });+ expect(result.current.data).toEqual(output);+ expect(result.current.result?.modelInputs).toBeUndefined();+});++it('unwraps only an opted-in request and retains errors, outputs and captured attempts', async () => {+ mockDebug.mockResolvedValue({+ data: {+ code: 102,+ message: 'Model failed',+ data: { outputs: { _ERROR: 'Provider failed' }, model_inputs: Snapshot },+ },+ });+ const { result } = renderHook(() => useDebugSingle('Agent:1'), { wrapper });+ await act(async () => {+ await result.current.debugSingle({+ ...Request,+ include_model_inputs: true,+ });+ });+ expect(mockDebug.mock.calls[0][0].data).toEqual({+ params: Request.params,+ include_model_inputs: true,+ });+ expect(result.current.data).toEqual({ _ERROR: 'Provider failed' });+ expect(result.current.result).toMatchObject({+ code: 102,+ message: 'Model failed',+ modelInputs: Snapshot,+ });+ expect(result.current.loading).toBe(false);+});++it('retains capture when outputs are empty and handles rejection before capture starts', async () => {+ mockDebug.mockResolvedValueOnce({+ data: {+ code: 102,+ message: 'Failed after invocation',+ data: { outputs: null, model_inputs: Snapshot },+ },+ });+ mockDebug.mockResolvedValueOnce({+ data: { code: 403, message: 'Update permission required', data: null },+ });+ const { result } = renderHook(() => useDebugSingle('Agent:1'), { wrapper });+ await act(async () => {+ await result.current.debugSingle({+ ...Request,+ include_model_inputs: true,+ });+ });+ expect(result.current.result?.modelInputs).toEqual(Snapshot);+ expect(result.current.data).toBeNull();+ await act(async () => {+ await result.current.debugSingle({+ ...Request,+ include_model_inputs: true,+ });+ });+ expect(result.current.result).toMatchObject({+ code: 403,+ message: 'Update permission required',+ outputs: null,+ });+ expect(result.current.result?.modelInputs).toBeUndefined();+});++it('clears the prior result on a new run and ignores an older completion and finalizer', async () => {+ const first = pendingResponse();+ const second = pendingResponse();+ mockDebug.mockResolvedValueOnce({+ data: { code: 0, message: '', data: { content: 'previous' } },+ });+ mockDebug+ .mockReturnValueOnce(first.promise)+ .mockReturnValueOnce(second.promise);+ const { result } = renderHook(() => useDebugSingle('Agent:1'), { wrapper });+ await act(async () => {+ await result.current.debugSingle(Request);+ });+ expect(result.current.data).toEqual({ content: 'previous' });+ let firstRun!: Promise<void>;+ let secondRun!: Promise<void>;+ await act(async () => {+ firstRun = result.current.debugSingle(Request);+ });+ expect(result.current.data).toBeUndefined();+ await act(async () => {+ secondRun = result.current.debugSingle(Request);+ });+ await act(async () => {+ first.resolve({ data: { code: 102, message: 'stale error', data: {} } });+ await firstRun;+ });+ expect(result.current.result).toBeUndefined();+ expect(result.current.loading).toBe(true);+ expect(mockError).not.toHaveBeenCalled();+ await act(async () => {+ second.resolve({+ data: { code: 0, message: '', data: { content: 'current' } },+ });+ await secondRun;+ });+ expect(result.current.data).toEqual({ content: 'current' });+ expect(result.current.loading).toBe(false);+});++it.each(['node', 'close'])(+ 'invalidates an in-flight response on %s change',+ async (change) => {+ const pending = pendingResponse();+ mockDebug.mockReturnValue(pending.promise);+ const { result, rerender } = renderHook(+ ({ node, visible }) => useDebugSingle(node, visible),+ { wrapper, initialProps: { node: 'Agent:1', visible: true } },+ );+ let run!: Promise<void>;+ await act(async () => {+ run = result.current.debugSingle(Request);+ });+ rerender({+ node: change === 'node' ? 'Agent:2' : 'Agent:1',+ visible: change !== 'close',+ });+ expect(result.current.loading).toBe(false);+ await act(async () => {+ pending.resolve({+ data: { code: 0, message: '', data: { content: 'stale' } },+ });+ await run;+ });+ expect(result.current.result).toBeUndefined();+ },+);++it('keeps a transport error visible without retaining a previous snapshot', async () => {+ mockDebug.mockRejectedValue(new Error('Connection closed'));+ const { result } = renderHook(() => useDebugSingle('Agent:1'), { wrapper });+ await act(async () => {+ await result.current.debugSingle({+ ...Request,+ include_model_inputs: true,+ });+ });+ expect(result.current.result).toMatchObject({+ code: -1,+ message: 'Connection closed',+ outputs: null,+ });+ expect(result.current.loading).toBe(false);+});diff --git a/web/src/hooks/use-single-debug-request.ts b/web/src/hooks/use-single-debug-request.tsnew file mode 100644index 0000000000..bce9c8b93c--- /dev/null+++ b/web/src/hooks/use-single-debug-request.ts@@ -0,0 +1,103 @@+import message from '@/components/ui/message';+import {+ IModelInputSnapshot,+ ISingleDebugCaptureData,+} from '@/interfaces/database/agent';+import { IDebugSingleRequestBody } from '@/interfaces/request/agent';+import agentService from '@/services/agent-service';+import { useMutation } from '@tanstack/react-query';+import { useCallback, useEffect, useRef, useState } from 'react';+import { useParams } from 'react-router';++interface SingleDebugResult {+ code: number;+ message: string;+ outputs: Record<string, unknown> | null;+ modelInputs?: IModelInputSnapshot;+ captureRequested: boolean;+}++/** Keeps each test run's result and loading state owned by its active request. */+export function useDebugSingle(componentId?: string, visible = true) {+ const { id } = useParams();+ const generation = useRef(0);+ const [result, setResult] = useState<SingleDebugResult>();+ const [loading, setLoading] = useState(false);+ const { mutateAsync, reset: resetMutation } = useMutation({+ gcTime: 0,+ /** Sends the debug request without adding capture fields to ordinary runs. */+ mutationFn: async (params: IDebugSingleRequestBody) => {+ const ret = await agentService.debugSingle(+ {+ agentId: id as string,+ componentId: params.component_id,+ data: {+ params: params.params,+ ...(params.include_model_inputs === true+ ? { include_model_inputs: true }+ : {}),+ },+ },+ true,+ );+ return ret.data;+ },+ });++ /** Invalidates pending responses and clears the visible result and mutation. */+ const reset = useCallback(() => {+ generation.current += 1;+ setResult(undefined);+ setLoading(false);+ resetMutation();+ }, [resetMutation]);++ useEffect(() => {+ reset();+ return () => {+ generation.current += 1;+ };+ }, [id, componentId, visible, reset]);++ /** Publishes only the latest run, parsing its result by the requested mode. */+ const debugSingle = useCallback(+ async (params: IDebugSingleRequestBody) => {+ const request = ++generation.current;+ setResult(undefined);+ setLoading(true);+ try {+ const response = await mutateAsync(params);+ if (request !== generation.current) return;+ const captureRequested = params.include_model_inputs === true;+ // Only the request determines the response shape. Ordinary component+ // outputs may legitimately contain outputs or model_inputs keys.+ const captured = captureRequested+ ? (response.data as ISingleDebugCaptureData | null)+ : null;+ setResult({+ code: response.code,+ message: response.message,+ outputs: captureRequested+ ? (captured?.outputs ?? null)+ : response.data,+ modelInputs: captured?.model_inputs,+ captureRequested,+ });+ if (response.code !== 0) message.error(response.message);+ } catch (error) {+ if (request !== generation.current) return;+ setResult({+ code: -1,+ message: error instanceof Error ? error.message : String(error),+ outputs: null,+ captureRequested: params.include_model_inputs === true,+ });+ } finally {+ if (request === generation.current) setLoading(false);+ }+ },+ [mutateAsync],+ );++ return { data: result?.outputs, result, loading, debugSingle, reset };+}diff --git a/web/src/interfaces/database/agent.ts b/web/src/interfaces/database/agent.tsindex 08ce2b73e0..d47d8a190a 100644--- a/web/src/interfaces/database/agent.ts+++ b/web/src/interfaces/database/agent.ts@@ -278,6 +278,22 @@ export interface ITraceData {trace: Array<Record<string, any>>;}+export interface IModelInputSnapshot {+ calls: Array<{+ sequence: number;+ model: string;+ status: 'captured' | 'omitted';+ messages?: Record<string, unknown>[];+ reason?: 'unsupported_content' | 'size_limit' | 'serialization_error';+ }>;+ omitted_count: number;+}++export interface ISingleDebugCaptureData {+ outputs: Record<string, unknown> | null;+ model_inputs: IModelInputSnapshot;+}+export interface IAgentLogResponse {id: string;message: IAgentLogMessage[];diff --git a/web/src/interfaces/request/agent.ts b/web/src/interfaces/request/agent.tsindex 24e5257c8a..85d1026c24 100644--- a/web/src/interfaces/request/agent.ts+++ b/web/src/interfaces/request/agent.ts@@ -1,6 +1,7 @@export interface IDebugSingleRequestBody {component_id: string;params: Record<string, any>;+ include_model_inputs?: boolean;}export interface IAgentWebhookTraceRequest {diff --git a/web/src/locales/en.ts b/web/src/locales/en.tsindex 0034552232..9fd1ff6bf2 100644--- a/web/src/locales/en.ts+++ b/web/src/locales/en.ts@@ -3354,6 +3354,15 @@ Best for: Documents with flowing, contextually connected content — such as boooptional: 'Optional',pasteFileLink: 'Paste file link',testRun: 'Test run',+ captureModelInputs: 'Capture model inputs',+ captureModelInputsHint:+ 'Test runs execute the agent and its tools. Expanding or copying captured inputs does not run them again.',+ modelInputs: 'Model inputs',+ modelInputSummary:+ 'Recorded entries: {{count}} · Omitted calls: {{omittedCount}}',+ noModelInputs: 'No model calls were captured in this run.',+ modelInputsUnavailable: 'Model inputs are unavailable for this run.',+ testRunError: 'Test run failed ({{code}}): {{message}}',debugRunLimits:'A debug run verifies that the flow executes without errors: PDF parses only the first 2 pages (other formats parse all pages); if a chunker node is present, only the first 3 chunks are previewed; if a knowledge-compiler node is present, it runs locally only and does not trigger a dataset rebuild or notification.',template: 'Template',diff --git a/web/src/pages/agent/form-sheet/single-debug-sheet/index.test.tsx b/web/src/pages/agent/form-sheet/single-debug-sheet/index.test.tsxnew file mode 100644index 0000000000..27e47f388f--- /dev/null+++ b/web/src/pages/agent/form-sheet/single-debug-sheet/index.test.tsx@@ -0,0 +1,258 @@+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';+import { fireEvent, render, screen } from '@testing-library/react';+import SingleDebugSheet from '.';++const mockDebug = jest.fn();+const mockCopy = jest.fn();+let mockNode: any;+let mockReadOnly = false;++jest.mock('@/services/agent-service', () => ({+ __esModule: true,+ default: { debugSingle: (...args: unknown[]) => mockDebug(...args) },+}));+jest.mock('@/components/ui/message', () => ({+ __esModule: true,+ default: { error: jest.fn() },+}));+jest.mock('react-router', () => ({ useParams: () => ({ id: 'agent-1' }) }));+jest.mock('@/hooks/use-agent-request', () => ({+ useFetchInputForm: () => ({}),+}));+jest.mock('../../context', () => ({ useCanvasReadonly: () => mockReadOnly }));+jest.mock('../../store', () => ({+ __esModule: true,+ default: (selector: any) => selector({ getNode: () => mockNode }),+}));+jest.mock('../../debug-content', () => ({+ __esModule: true,+ default: ({ ok, loading }: any) => (+ <button disabled={loading} onClick={() => ok([])}>+ Run+ </button>+ ),+}));+jest.mock('@/components/ui/sheet', () => ({+ Sheet: ({ open, children }: any) => (open ? <div>{children}</div> : null),+ SheetContent: ({ children }: any) => <div>{children}</div>,+ SheetHeader: ({ children }: any) => <div>{children}</div>,+}));+jest.mock('react18-json-view', () => ({+ __esModule: true,+ default: ({ src }: any) => (+ <pre data-testid="json">{JSON.stringify(src)}</pre>+ ),+}));+jest.mock('@/components/copy-to-clipboard', () => ({+ __esModule: true,+ default: ({ text }: any) => (+ <button onClick={() => mockCopy(text)}>Copy</button>+ ),+}));+jest.mock('react-i18next', () => ({+ useTranslation: () => ({+ t: (key: string, options?: any) =>+ options ? `${key} ${Object.values(options).join(' ')}` : key,+ }),+}));++const Snapshot = {+ calls: [+ {+ sequence: 1,+ model: 'model-a',+ status: 'captured',+ messages: [+ {+ role: 'system',+ content: 'Resolved prompt <script>literal</script>\nnext line',+ },+ { role: 'user', content: 'Question' },+ ],+ },+ {+ sequence: 2,+ model: 'model-a',+ status: 'omitted',+ reason: 'unsupported_content',+ },+ ],+ omitted_count: 1,+};++/** Renders an open Agent test sheet with an isolated React Query cache. */+function renderSheet() {+ const client = new QueryClient();+ return render(+ <QueryClientProvider client={client}>+ <SingleDebugSheet componentId="Agent:1" visible hideModal={jest.fn()} />+ </QueryClientProvider>,+ );+}++beforeEach(() => {+ mockDebug.mockReset();+ mockCopy.mockReset();+ mockReadOnly = false;+ mockNode = { data: { label: 'Agent', form: {} } };+});++it('offers capture only on editable Agent nodes, defaulting to off', async () => {+ mockDebug.mockResolvedValue({+ data: { code: 0, message: '', data: { content: 'Ordinary output' } },+ });+ renderSheet();+ expect(+ screen.getByRole('switch', { name: 'flow.captureModelInputs' }),+ ).toHaveAttribute('aria-checked', 'false');+ fireEvent.click(screen.getByRole('button', { name: 'Run' }));+ await screen.findByText(/Ordinary output/);+ expect(mockDebug.mock.calls[0][0].data).toEqual({ params: {} });+ expect(+ screen.queryByRole('button', { name: 'flow.modelInputs' }),+ ).not.toBeInTheDocument();+});++it.each(['CodeExec', 'Retrieval', 'Invoke'])(+ 'keeps capture out of %s test runs',+ (label) => {+ mockNode = { data: { label, form: {} } };+ renderSheet();+ expect(screen.queryByRole('switch')).not.toBeInTheDocument();+ },+);++it('keeps capture out of read-only previews', () => {+ mockReadOnly = true;+ renderSheet();+ expect(screen.queryByRole('switch')).not.toBeInTheDocument();+});++it('preserves an error and empty outputs with a collapsed, copyable snapshot', async () => {+ mockDebug.mockResolvedValue({+ data: {+ code: 102,+ message: 'Tool failed',+ data: { outputs: {}, model_inputs: Snapshot },+ },+ });+ const { container } = renderSheet();+ fireEvent.click(+ screen.getByRole('switch', { name: 'flow.captureModelInputs' }),+ );+ fireEvent.click(screen.getByRole('button', { name: 'Run' }));+ expect(await screen.findByRole('alert')).toHaveTextContent('102 Tool failed');+ expect(mockDebug.mock.calls[0][0].data.include_model_inputs).toBe(true);+ const expand = screen.getByRole('button', { name: 'flow.modelInputs' });+ expect(expand).toHaveAttribute('aria-expanded', 'false');+ expect(screen.queryByText(/Resolved prompt/)).not.toBeInTheDocument();+ fireEvent.click(expand);+ const json = screen.getByTestId('json');+ expect(json).toHaveTextContent(JSON.stringify(Snapshot));+ expect(container.querySelector('script')).toBeNull();+ fireEvent.click(screen.getByRole('button', { name: 'Copy' }));+ expect(JSON.parse(mockCopy.mock.calls[0][0])).toEqual(Snapshot);+ expect(mockDebug).toHaveBeenCalledTimes(1);+});++it('retains the component error alongside the top-level error and snapshot', async () => {+ mockDebug.mockResolvedValue({+ data: {+ code: 102,+ message: 'Execution failed',+ data: {+ outputs: { _ERROR: 'Specific provider error' },+ model_inputs: Snapshot,+ },+ },+ });+ renderSheet();+ fireEvent.click(screen.getByRole('switch'));+ fireEvent.click(screen.getByRole('button', { name: 'Run' }));+ expect(await screen.findByRole('alert')).toHaveTextContent(+ 'Execution failed',+ );+ expect(screen.getByTestId('json')).toHaveTextContent(+ 'Specific provider error',+ );+ expect(+ screen.getByRole('button', { name: 'flow.modelInputs' }),+ ).toBeInTheDocument();+});++it('explains a successful run with no model calls and copies the empty summary', async () => {+ const empty = { calls: [], omitted_count: 0 };+ mockDebug.mockResolvedValue({+ data: {+ code: 0,+ message: '',+ data: { outputs: null, model_inputs: empty },+ },+ });+ renderSheet();+ fireEvent.click(screen.getByRole('switch'));+ fireEvent.click(screen.getByRole('button', { name: 'Run' }));+ fireEvent.click(+ await screen.findByRole('button', { name: 'flow.modelInputs' }),+ );+ expect(screen.getByText('flow.noModelInputs')).toBeInTheDocument();+ fireEvent.click(screen.getByRole('button', { name: 'Copy' }));+ expect(JSON.parse(mockCopy.mock.calls[0][0])).toEqual(empty);+});++it('retains CodeExec output sections and never interprets its output keys as capture', async () => {+ mockNode = {+ data: {+ label: 'CodeExec',+ form: { outputs: { result: { type: 'string' } } },+ },+ };+ mockDebug.mockResolvedValue({+ data: {+ code: 0,+ message: '',+ data: {+ result: 'value',+ outputs: 'business outputs',+ model_inputs: 'business capture',+ },+ },+ });+ renderSheet();+ fireEvent.click(screen.getByRole('button', { name: 'Run' }));+ await screen.findByText('Raw Component Output');+ expect(screen.getByText('Business Output')).toBeInTheDocument();+ expect(screen.getByText('System Outputs')).toBeInTheDocument();+ expect(+ screen.queryByRole('button', { name: 'flow.modelInputs' }),+ ).not.toBeInTheDocument();+});++it('clears the snapshot and restores capture to off when another node is selected', async () => {+ mockDebug.mockResolvedValue({+ data: {+ code: 0,+ message: '',+ data: { outputs: {}, model_inputs: Snapshot },+ },+ });+ const client = new QueryClient();+ const view = (componentId: string) => (+ <QueryClientProvider client={client}>+ <SingleDebugSheet+ componentId={componentId}+ visible+ hideModal={jest.fn()}+ />+ </QueryClientProvider>+ );+ const { rerender } = render(view('Agent:1'));+ fireEvent.click(screen.getByRole('switch'));+ fireEvent.click(screen.getByRole('button', { name: 'Run' }));+ await screen.findByRole('button', { name: 'flow.modelInputs' });+ rerender(view('Agent:2'));+ expect(screen.getByRole('switch')).toHaveAttribute('aria-checked', 'false');+ expect(+ screen.queryByRole('button', { name: 'flow.modelInputs' }),+ ).not.toBeInTheDocument();+});diff --git a/web/src/pages/agent/form-sheet/single-debug-sheet/index.tsx b/web/src/pages/agent/form-sheet/single-debug-sheet/index.tsxindex 7724ac8988..a313210775 100644--- a/web/src/pages/agent/form-sheet/single-debug-sheet/index.tsx+++ b/web/src/pages/agent/form-sheet/single-debug-sheet/index.tsx@@ -1,22 +1,27 @@import CopyToClipboard from '@/components/copy-to-clipboard';import { Sheet, SheetContent, SheetHeader } from '@/components/ui/sheet';-import { useDebugSingle, useFetchInputForm } from '@/hooks/use-agent-request';+import { Switch } from '@/components/ui/switch';+import { useFetchInputForm } from '@/hooks/use-agent-request';+import { useDebugSingle } from '@/hooks/use-single-debug-request';import { IModalProps } from '@/interfaces/common';import { ICodeForm } from '@/interfaces/database/agent';import { cn } from '@/lib/utils';import { isEmpty } from 'lodash';import { X } from 'lucide-react';-import { useCallback, useMemo } from 'react';+import { useCallback, useEffect, useId, useMemo, useState } from 'react';import { useTranslation } from 'react-i18next';import JsonView from 'react18-json-view';import 'react18-json-view/src/style.css';import DebugContent from '../../debug-content';+import { Operator } from '../../constant';+import { useCanvasReadonly } from '../../context';import { transferInputsArrayToObject } from '../../form/begin-form/use-watch-change';import {deserializeCodeOutputContract,getBusinessOutputs,} from '../../form/code-form/utils';import useGraphStore from '../../store';+import { ModelInputs } from './model-inputs';import {buildDebugInputList,groupCodeExecDebugOutput,@@ -82,16 +87,24 @@ interface IProps {componentId?: string;}+/** Runs one component and offers model-input capture for editable Agent nodes. */const SingleDebugSheet = ({componentId,visible,hideModal,}: IModalProps<any> & IProps) => {const { t } = useTranslation();+ const readOnly = useCanvasReadonly();+ const captureId = useId();+ const [captureModelInputs, setCaptureModelInputs] = useState(false);const getNode = useGraphStore((state) => state.getNode);const inputForm = useFetchInputForm(componentId);- const { debugSingle, data, loading } = useDebugSingle();+ const { debugSingle, data, result, loading, reset } = useDebugSingle(+ componentId,+ visible,+ );const node = getNode(componentId);+ const canCapture = node?.data.label === Operator.Agent && !readOnly;const shouldUseCodeExecLayout = shouldUseCodeExecDebugLayout(node?.data.label,);@@ -104,16 +117,38 @@ const SingleDebugSheet = ({[list],);+ useEffect(() => {+ setCaptureModelInputs(false);+ }, [componentId, visible]);++ /** Clears the active run before closing so late responses stay hidden. */+ const handleClose = useCallback(() => {+ reset();+ hideModal?.();+ }, [hideModal, reset]);++ /** Routes sheet dismissal through the same result cleanup as the close icon. */+ const handleOpenChange = useCallback(+ (open: boolean) => {+ if (!open) handleClose();+ },+ [handleClose],+ );++ /** Submits form values with capture enabled only when the node permits it. */const onOk = useCallback((nextValues: any[]) => {if (componentId) {debugSingle({component_id: componentId,params: transferInputsArrayToObject(nextValues),+ ...(canCapture && captureModelInputs+ ? { include_model_inputs: true }+ : {}),});}},- [componentId, debugSingle],+ [canCapture, captureModelInputs, componentId, debugSingle],);const formData = shouldUseCodeExecLayout@@ -156,15 +191,34 @@ const SingleDebugSheet = ({: !isEmpty((data as Record<string, unknown> | undefined)?._ERROR);return (- <Sheet open={visible} modal={false}>- <SheetContent className="top-20 p-0" closeIcon={false}>- <SheetHeader className="px-5 py-2">+ <Sheet open={visible} onOpenChange={handleOpenChange} modal={false}>+ <SheetContent+ className="top-20 bottom-0 h-auto flex flex-col gap-0 overflow-hidden p-0"+ closeIcon={false}+ >+ <SheetHeader className="shrink-0 px-5 py-2"><div className="flex justify-between ">{t('flow.testRun')}- <X onClick={hideModal} className="cursor-pointer" />+ <X onClick={handleClose} className="cursor-pointer" /></div></SheetHeader>- <section className="overflow-y-auto px-5 pt-4">+ <section className="min-h-0 flex-1 overflow-y-auto px-5 pt-4 pb-5">+ {canCapture && (+ <div className="mb-4 space-y-2">+ <div className="flex items-center justify-between gap-3">+ <span id={captureId}>{t('flow.captureModelInputs')}</span>+ <Switch+ aria-labelledby={captureId}+ checked={captureModelInputs}+ onCheckedChange={setCaptureModelInputs}+ disabled={loading}+ />+ </div>+ <p className="text-sm text-text-secondary">+ {t('flow.captureModelInputsHint')}+ </p>+ </div>+ )}<DebugContentkey={componentId}parameters={list}@@ -175,6 +229,19 @@ const SingleDebugSheet = ({className="min-h-0 flex-1 overflow-auto pb-5"maxHeight="max-h-[83vh]"></DebugContent>+ {result && result.code !== 0 && (+ <div role="alert" className="mt-4 break-words text-state-error">+ {t('flow.testRunError', {+ code: result.code,+ message: result.message,+ })}+ </div>+ )}+ {result?.captureRequested && (+ <div className="mt-4">+ <ModelInputs snapshot={result.modelInputs} />+ </div>+ )}{!isEmpty(data) ? (<div className="mt-4 space-y-4">{shouldUseCodeExecLayout ? (diff --git a/web/src/pages/agent/form-sheet/single-debug-sheet/model-inputs.module.css b/web/src/pages/agent/form-sheet/single-debug-sheet/model-inputs.module.cssnew file mode 100644index 0000000000..9a764e756b--- /dev/null+++ b/web/src/pages/agent/form-sheet/single-debug-sheet/model-inputs.module.css@@ -0,0 +1,9 @@+.modelInputs:global(.json-view) {+ color: rgb(var(--text-primary));+ --json-property: rgb(var(--text-primary));+ --json-index: rgb(var(--text-secondary));+ --json-number: rgb(var(--text-primary));+ --json-string: rgb(var(--text-primary));+ --json-boolean: rgb(var(--text-primary));+ --json-null: rgb(var(--text-primary));+}diff --git a/web/src/pages/agent/form-sheet/single-debug-sheet/model-inputs.tsx b/web/src/pages/agent/form-sheet/single-debug-sheet/model-inputs.tsxnew file mode 100644index 0000000000..1c5805f134--- /dev/null+++ b/web/src/pages/agent/form-sheet/single-debug-sheet/model-inputs.tsx@@ -0,0 +1,48 @@+import { Collapse } from '@/components/collapse';+import CopyToClipboard from '@/components/copy-to-clipboard';+import { IModelInputSnapshot } from '@/interfaces/database/agent';+import { useTranslation } from 'react-i18next';+import JsonView from 'react18-json-view';+import styles from './model-inputs.module.css';++/** Displays captured attempts without rerunning or reconstructing model inputs. */+export function ModelInputs({ snapshot }: { snapshot?: IModelInputSnapshot }) {+ const { t } = useTranslation();+ return (+ <div className="rounded-md border p-3">+ <Collapse title={t('flow.modelInputs')}>+ {snapshot ? (+ <div className="space-y-2">+ <div className="flex items-center justify-between gap-3">+ <p className="text-sm text-text-secondary">+ {t('flow.modelInputSummary', {+ count: snapshot.calls.length,+ omittedCount: snapshot.omitted_count,+ })}+ </p>+ <CopyToClipboard+ text={JSON.stringify(snapshot, null, 2)}+ aria-label={t('common.copy')}+ />+ </div>+ {snapshot.calls.length === 0 && snapshot.omitted_count === 0 && (+ <p className="text-sm text-text-secondary">+ {t('flow.noModelInputs')}+ </p>+ )}+ <JsonView+ src={snapshot}+ displaySize+ collapseStringsAfterLength={100000000000}+ className={`${styles.modelInputs} max-h-[400px] overflow-auto break-words bg-muted p-2`}+ />+ </div>+ ) : (+ <p className="text-sm text-text-secondary">+ {t('flow.modelInputsUnavailable')}+ </p>+ )}+ </Collapse>+ </div>+ );+}