Skip to content

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

fix(agent): harden runtime boundary contracts (#20186)

Sbaaoui Idriss345fb45deb4f
diff --git a/internal/agent/canvas/scheduler.go b/internal/agent/canvas/scheduler.go
index 06a8d537a5..80003f176f 100644
--- a/internal/agent/canvas/scheduler.go
+++ b/internal/agent/canvas/scheduler.go
@@ -157,21 +157,13 @@ func statePre(ctx context.Context, in map[string]any, state *CanvasState) (map[s
contextMemory := ctxState.SnapshotMemory()
localSysHistory := state.SnapshotSysHistory()
contextSysHistory := ctxState.SnapshotSysHistory()
- for cpnID, bucket := range state.Outputs {
+ for cpnID, bucket := range state.Snapshot() {
for k, v := range bucket {
ctxState.SetVar(cpnID, k, v)
}
}
sysNS, envNS, globalsNS := state.SnapshotNamespaces()
- for k, v := range sysNS {
- ctxState.Sys[k] = v
- }
- for k, v := range envNS {
- ctxState.Env[k] = v
- }
- for k, v := range globalsNS {
- ctxState.Globals[k] = v
- }
+ ctxState.MergeNamespaces(sysNS, envNS, globalsNS)
if len(contextHistory) >= len(localHistory) {
state.SetHistory(contextHistory)
} else {
@@ -235,9 +227,7 @@ func statePost(ctx context.Context, out map[string]any, state *CanvasState) (map
}
if ctxState != nil && state != nil && ctxState != state {
sysNS, envNS, globalsNS := ctxState.SnapshotNamespaces()
- state.Sys = sysNS
- state.Env = envNS
- state.Globals = globalsNS
+ state.ReplaceNamespaces(sysNS, envNS, globalsNS)
state.SetHistory(ctxState.SnapshotHistory())
state.SetMemory(ctxState.SnapshotMemory())
}
@@ -282,10 +272,10 @@ func nodeStartedAt(ctx context.Context, state *CanvasState, cpnID, componentName
}
now := float64(time.Now().UnixNano()) / 1e9
- if state.Sys != nil {
- state.Sys["_node_start_"+cpnID] = now
- state.Sys["_node_inputs_"+cpnID] = sanitizeNodeInputs(inputs)
- }
+ state.MergeNamespaces(map[string]any{
+ "_node_start_" + cpnID: now,
+ "_node_inputs_" + cpnID: sanitizeNodeInputs(inputs),
+ }, nil, nil)
nsData, err := runtime.SafeJSONMarshal(NodeStartedData{
Inputs: sanitizeNodeInputs(inputs),
CreatedAt: now,
@@ -324,10 +314,9 @@ func nodeFinishedNow(ctx context.Context, state *CanvasState, cpnID, componentNa
}
now := float64(time.Now().UnixNano()) / 1e9
var elapsed float64
- if state.Sys != nil {
- if start, ok := state.Sys["_node_start_"+cpnID].(float64); ok {
- elapsed = now - start
- }
+ sysNS, _, _ := state.SnapshotNamespaces()
+ if start, ok := sysNS["_node_start_"+cpnID].(float64); ok {
+ elapsed = now - start
}
if elapsed < 0 {
elapsed = 0
@@ -335,20 +324,13 @@ func nodeFinishedNow(ctx context.Context, state *CanvasState, cpnID, componentNa
// Collect outputs from the state's Outputs bucket for this cpn.
var outputs map[string]any
- if state.Outputs != nil {
- if bucket, ok := state.Outputs[cpnID]; ok && len(bucket) > 0 {
- outputs = make(map[string]any, len(bucket))
- for k, v := range bucket {
- outputs[k] = v
- }
- }
+ if bucket := state.Snapshot()[cpnID]; len(bucket) > 0 {
+ outputs = bucket
}
inputs := map[string]any{}
- if state.Sys != nil {
- if v, ok := state.Sys["_node_inputs_"+cpnID].(map[string]any); ok {
- inputs = v
- }
+ if v, ok := sysNS["_node_inputs_"+cpnID].(map[string]any); ok {
+ inputs = v
}
var nfErr interface{}
@@ -437,9 +419,7 @@ func BuildWorkflow(ctx context.Context, c *Canvas) (*compose.Workflow[map[string
}
}
sysNS, envNS, globalsNS := ctxState.SnapshotNamespaces()
- st.Sys = sysNS
- st.Env = envNS
- st.Globals = globalsNS
+ st.ReplaceNamespaces(sysNS, envNS, globalsNS)
st.Path = append([]string(nil), ctxState.Path...)
st.SetHistory(ctxState.SnapshotHistory())
st.SetMemory(ctxState.SnapshotMemory())
@@ -447,15 +427,19 @@ func BuildWorkflow(ctx context.Context, c *Canvas) (*compose.Workflow[map[string
}
st := NewCanvasState("", "")
if globals != nil {
+ sysNS := make(map[string]any)
+ envNS := make(map[string]any)
+ globalsNS := make(map[string]any)
for k, v := range globals {
if strings.HasPrefix(k, "sys.") {
- st.Sys[strings.TrimPrefix(k, "sys.")] = v
+ sysNS[strings.TrimPrefix(k, "sys.")] = v
} else if strings.HasPrefix(k, "env.") {
- st.Env[strings.TrimPrefix(k, "env.")] = v
+ envNS[strings.TrimPrefix(k, "env.")] = v
} else {
- st.Globals[k] = v
+ globalsNS[k] = v
}
}
+ st.MergeNamespaces(sysNS, envNS, globalsNS)
}
st.SetHistory(c.History)
st.SetMemory(c.Memory)
diff --git a/internal/agent/dsl/normalize.go b/internal/agent/dsl/normalize.go
index 45db7f2990..fa8563d34e 100644
--- a/internal/agent/dsl/normalize.go
+++ b/internal/agent/dsl/normalize.go
@@ -425,51 +425,13 @@ func toStringSlice(v any) []string {
return out
}
-// deepCopyDSL returns a deep copy of the parts of `dsl` that
-// NormalizeForCanvas mutates: the top-level keys "graph" and
-// "components", and within `graph` the "nodes" and "edges" slices.
-// All other top-level keys (`globals`, `variables`, `path`,
-// `retrieval`, `history`, `*`) are shallow-copied by reference —
-// they are read-only and never modified by the normalize pipeline.
-//
-// The deep copy is required because:
-// - enforceHandleIds rewrites graph.edges[*].sourceHandle /
-// targetHandle in place.
-// - foldLegacyLoopVariants deletes entries from components,
-// rewrites components[*].obj.component_name, and rewrites
-// graph.nodes[*].data.label / type.
-//
-// Without the deep copy, a caller that reuses the original
-// decoded DSL map (e.g. for re-validation or diffing) would
-// observe side effects that contradict the documented
-// "never mutates its input"
-//
-// Primitives and non-mutable values (string, number, bool) are
-// shared by reference; only the maps and slices that the
-// normalize pipeline touches are duplicated.
+// deepCopyDSL returns a recursive copy so normalization never mutates the
+// caller's nested JSON values. Runtime alias rewrites walk every string in
+// the DSL, not only graph and component entries.
func deepCopyDSL(dsl map[string]any) map[string]any {
out := make(map[string]any, len(dsl)+1)
for k, v := range dsl {
- switch k {
- case "graph":
- if g, ok := v.(map[string]any); ok {
- out["graph"] = deepCopyGraph(g)
- } else {
- out["graph"] = v
- }
- case "components":
- if c, ok := v.(map[string]any); ok {
- out["components"] = deepCopyComponents(c)
- } else {
- out["components"] = v
- }
- default:
- // Shallow: globals, variables, path, retrieval,
- // history, and any other top-level key are not
- // mutated by the normalize pipeline. Sharing the
- // reference is safe.
- out[k] = v
- }
+ out[k] = deepCopyAny(v)
}
return out
}
@@ -497,64 +459,8 @@ func deepCopyAny(v any) any {
}
}
-// deepCopyGraph copies a graph block. Nodes and edges are deep-copied
-// element-by-element so that later mutations (e.g. data.label rewrite
-// in fixComponentNames) target the copy, not the caller's input.
-func deepCopyGraph(g map[string]any) map[string]any {
- out := make(map[string]any, len(g))
- for k, v := range g {
- switch k {
- case "nodes":
- if nodes, ok := v.([]any); ok {
- copied := make([]any, len(nodes))
- for i, n := range nodes {
- copied[i] = deepCopyAny(n)
- }
- out["nodes"] = copied
- } else {
- out["nodes"] = v
- }
- case "edges":
- if edges, ok := v.([]any); ok {
- copied := make([]any, len(edges))
- for i, e := range edges {
- copied[i] = deepCopyAny(e)
- }
- out["edges"] = copied
- } else {
- out["edges"] = v
- }
- default:
- out[k] = v
- }
- }
- return out
-}
-
-// deepCopyComponents copies a components block. Each component
-// entry is a new map; the `obj` sub-map (when present) is also
-// deep-copied so rewrites to component_name / params land on
-// the copy.
-func deepCopyComponents(c map[string]any) map[string]any {
- out := make(map[string]any, len(c))
- for k, v := range c {
- if cm, ok := v.(map[string]any); ok {
- entry := deepCopyAny(cm).(map[string]any)
- if obj, ok := cm["obj"].(map[string]any); ok {
- entry["obj"] = deepCopyAny(obj)
- }
- out[k] = entry
- } else {
- out[k] = v
- }
- }
- return out
-}
-
// copyMapStringAny returns a shallow copy of m. The new map
-// aliases the original values; callers that need a deeper copy
-// recurse on their own (e.g. deepCopyGraph / deepCopyComponents
-// recurse on `obj` and on each node / edge).
+// aliases the original values.
func copyMapStringAny(m map[string]any) map[string]any {
out := make(map[string]any, len(m))
for k, v := range m {
diff --git a/internal/agent/dsl/normalize_test.go b/internal/agent/dsl/normalize_test.go
index 79fb49a245..2325c54bdc 100644
--- a/internal/agent/dsl/normalize_test.go
+++ b/internal/agent/dsl/normalize_test.go
@@ -19,6 +19,7 @@ import (
"encoding/json"
"os"
"path/filepath"
+ "reflect"
"strings"
"testing"
)
@@ -32,6 +33,20 @@ func fixturesDir(t *testing.T) string {
return filepath.Join("testdata")
}
+func TestNormalizeForRunDoesNotMutateNestedDSLValues(t *testing.T) {
+ in := map[string]any{
+ "globals": map[string]any{"nested": map[string]any{"value": "{IterationItem:x@item}"}},
+ "variables": []any{map[string]any{"value": "{IterationItem:x@index}"}},
+ }
+ original := deepCopyAny(in).(map[string]any)
+
+ _ = NormalizeForRun(in)
+
+ if !reflect.DeepEqual(in, original) {
+ t.Fatalf("NormalizeForRun mutated nested input: got %#v, want %#v", in, original)
+ }
+}
+
// loadFixture reads a JSON file from internal/agent/dsl/testdata into a
// map[string]any. The function t.Skip()s (not t.Fatal) on a missing
// file so a test run on a slim checkout still goes green.
diff --git a/internal/agent/retrievalbridge/runtime_adapter.go b/internal/agent/retrievalbridge/runtime_adapter.go
index a9c4e8e369..e205f30e12 100644
--- a/internal/agent/retrievalbridge/runtime_adapter.go
+++ b/internal/agent/retrievalbridge/runtime_adapter.go
@@ -71,9 +71,6 @@ func (a *RuntimeAdapter) Search(ctx context.Context, db *gorm.DB, req agentrunt.
toolReq := agenttool.RetrievalRequest(req)
toolReq.AllowDenseFallback = new(false)
toolReq.RankFeature = rankFeatureOrNil(req.RankFeature)
- // Python hybrid_search excludes compiled products from plain retrieval via
- // must_not={"exists":"compile_kwd"}.
- toolReq.ExcludeCompiled = req.OnlyOriginalText
chunks, err := svc.Search(ctx, db, toolReq)
if err != nil {
return nil, err
diff --git a/internal/agent/retrievalbridge/runtime_adapter_test.go b/internal/agent/retrievalbridge/runtime_adapter_test.go
index 65c60144a5..a81632a01b 100644
--- a/internal/agent/retrievalbridge/runtime_adapter_test.go
+++ b/internal/agent/retrievalbridge/runtime_adapter_test.go
@@ -8,6 +8,7 @@ import (
agentrunt "ragflow/internal/agent/runtime"
agenttool "ragflow/internal/agent/tool"
+ agenticruntime "ragflow/internal/rag/agentic-rag/runtime"
"gorm.io/gorm"
)
@@ -34,6 +35,99 @@ func TestRuntimeAdapterDisablesDenseFallback(t *testing.T) {
}
}
+func TestRuntimeAdapterPreservesMetadataFilter(t *testing.T) {
+ service := &captureRetrievalService{}
+ filter := map[string]any{"method": "manual", "value": "invoice"}
+ _, err := NewRuntimeAdapter(service).Search(t.Context(), nil, agentrunt.RetrievalRequest{
+ Query: "test",
+ MetaDataFilter: filter,
+ })
+ if err != nil {
+ t.Fatal(err)
+ }
+ if !reflect.DeepEqual(service.req.MetaDataFilter, filter) {
+ t.Fatalf("MetaDataFilter = %#v, want %#v", service.req.MetaDataFilter, filter)
+ }
+}
+
+func TestRuntimeAdapterPreservesCompiledExclusion(t *testing.T) {
+ for _, tc := range []struct {
+ name string
+ excludeCompiled bool
+ onlyOriginalText bool
+ }{
+ {name: "neither"},
+ {name: "exclude compiled", excludeCompiled: true},
+ {name: "original text", onlyOriginalText: true},
+ {name: "both", excludeCompiled: true, onlyOriginalText: true},
+ } {
+ t.Run(tc.name, func(t *testing.T) {
+ service := &captureRetrievalService{}
+ req := agentrunt.RetrievalRequest{
+ Query: "test",
+ RerankID: "reranker",
+ ExcludeCompiled: tc.excludeCompiled,
+ OnlyOriginalText: tc.onlyOriginalText,
+ }
+ if _, err := NewRuntimeAdapter(service).Search(t.Context(), nil, req); err != nil {
+ t.Fatal(err)
+ }
+ if service.req.ExcludeCompiled != req.ExcludeCompiled || service.req.OnlyOriginalText != req.OnlyOriginalText {
+ t.Fatalf("retrieval flags = (%v, %v), want (%v, %v)", service.req.ExcludeCompiled, service.req.OnlyOriginalText, req.ExcludeCompiled, req.OnlyOriginalText)
+ }
+ if service.req.RerankID != req.RerankID {
+ t.Fatalf("RerankID = %q, want %q", service.req.RerankID, req.RerankID)
+ }
+ })
+ }
+}
+
+func TestRuntimeRetrieverSurvivesProductionBridge(t *testing.T) {
+ previous := agentrunt.GetRetrievalService()
+ service := &captureRetrievalService{}
+ agentrunt.SetRetrievalService(NewRuntimeAdapter(service))
+ t.Cleanup(func() { agentrunt.SetRetrievalService(previous) })
+
+ filter := map[string]any{"method": "manual", "value": "invoice"}
+ _, err := (&agenticruntime.RuntimeRetriever{}).Retrieve(t.Context(), agenticruntime.RetrieveRequest{
+ Query: "test",
+ MetaDataFilter: filter,
+ ExcludeCompiled: true,
+ })
+ if err != nil {
+ t.Fatal(err)
+ }
+ if !reflect.DeepEqual(service.req.MetaDataFilter, filter) {
+ t.Fatalf("MetaDataFilter = %#v, want %#v", service.req.MetaDataFilter, filter)
+ }
+ if !service.req.ExcludeCompiled {
+ t.Fatal("ExcludeCompiled was dropped across RuntimeRetriever and RuntimeAdapter")
+ }
+}
+
+func TestAgenticSearchSurvivesProductionRegistryBridge(t *testing.T) {
+ previous := agenttool.GetRetrievalService()
+ service := &captureRetrievalService{}
+ agenttool.SetRetrievalService(NewRuntimeAdapter(service))
+ t.Cleanup(func() { agenttool.SetRetrievalService(previous) })
+
+ state := agentrunt.NewCanvasState("run-1", "task-1")
+ state.Sys["tenant_id"] = "tenant-1"
+ ctx := agentrunt.WithState(t.Context(), state)
+ if _, err := agenttool.NewAgenticSearchTool("hybrid_search").InvokableRun(ctx, `{"query":"test","kb_ids":["kb-1"]}`); err != nil {
+ t.Fatal(err)
+ }
+ if service.req.TenantID != "tenant-1" {
+ t.Fatalf("TenantID = %q, want tenant-1", service.req.TenantID)
+ }
+ if !service.req.ExcludeCompiled {
+ t.Fatal("AgenticSearch ExcludeCompiled was overwritten by the production bridge")
+ }
+ if service.req.AllowDenseFallback == nil || *service.req.AllowDenseFallback {
+ t.Fatal("AgenticSearch dense fallback policy was lost by the production bridge")
+ }
+}
+
// TestRuntimeAdapterDoesNotResolveItsTargetFromTheSharedRegistry reproduces the
// server's boot order (cmd/ragflow_server.go): the NLP adapter is registered,
// then the bridge REPLACES it in the same shared registry
diff --git a/internal/agent/runtime/state.go b/internal/agent/runtime/state.go
index 2d380c6d62..058773f019 100644
--- a/internal/agent/runtime/state.go
+++ b/internal/agent/runtime/state.go
@@ -33,6 +33,7 @@ package runtime
import (
"encoding/json"
"fmt"
+ "maps"
"reflect"
"sort"
"strings"
@@ -201,15 +202,9 @@ func (s *CanvasState) UnmarshalJSON(b []byte) error {
}
s.mu.Lock()
defer s.mu.Unlock()
- if snap.Outputs != nil {
- s.Outputs = snap.Outputs
- }
- if snap.Sys != nil {
- s.Sys = snap.Sys
- }
- if snap.Env != nil {
- s.Env = snap.Env
- }
+ s.Outputs = snap.Outputs
+ s.Sys = snap.Sys
+ s.Env = snap.Env
s.Path = snap.Path
s.History = snap.History
s.activeHistoryIndex = -1
@@ -217,15 +212,9 @@ func (s *CanvasState) UnmarshalJSON(b []byte) error {
s.activeHistoryIndex = *snap.ActiveHistoryIndex
}
s.Memory = snap.Memory
- if snap.Retrieval != nil {
- s.Retrieval = snap.Retrieval
- }
- if snap.Globals != nil {
- s.Globals = snap.Globals
- }
- if s.CancelFlag == nil {
- s.CancelFlag = &atomic.Bool{}
- }
+ s.Retrieval = snap.Retrieval
+ s.Globals = snap.Globals
+ s.ensureInitializedLocked()
s.CancelFlag.Store(snap.CancelFlag)
s.RunID = snap.RunID
s.SessionID = snap.SessionID
@@ -261,6 +250,7 @@ func (s *CanvasState) GetVar(ref string) (any, error) {
func (s *CanvasState) SetVar(cpnID, param string, v any) {
s.mu.Lock()
defer s.mu.Unlock()
+ s.ensureInitializedLocked()
setVarLocked(s.Outputs, cpnID, param, v)
}
@@ -329,6 +319,42 @@ func (s *CanvasState) SnapshotNamespaces() (sys map[string]any, env map[string]a
return sys, env, globals
}
+// MergeNamespaces adds the supplied values to the three shared namespaces.
+// Existing keys are preserved unless replaced by an incoming value.
+func (s *CanvasState) MergeNamespaces(sys, env, globals map[string]any) {
+ if s == nil {
+ return
+ }
+ s.mu.Lock()
+ defer s.mu.Unlock()
+ s.ensureInitializedLocked()
+ maps.Copy(s.Sys, sys)
+ maps.Copy(s.Env, env)
+ maps.Copy(s.Globals, globals)
+}
+
+// ReplaceNamespaces replaces the three shared namespaces with defensive
+// copies of the supplied maps.
+func (s *CanvasState) ReplaceNamespaces(sys, env, globals map[string]any) {
+ if s == nil {
+ return
+ }
+ s.mu.Lock()
+ defer s.mu.Unlock()
+ s.Sys = maps.Clone(sys)
+ if s.Sys == nil {
+ s.Sys = make(map[string]any)
+ }
+ s.Env = maps.Clone(env)
+ if s.Env == nil {
+ s.Env = make(map[string]any)
+ }
+ s.Globals = maps.Clone(globals)
+ if s.Globals == nil {
+ s.Globals = make(map[string]any)
+ }
+}
+
// SetHistory replaces the conversation history with a defensive copy.
func (s *CanvasState) SetHistory(history []map[string]any) {
if s == nil {
@@ -610,14 +636,36 @@ func (s *CanvasState) RecordOutput(cpnID, bucket string, payload any) {
}
s.mu.Lock()
defer s.mu.Unlock()
+ s.ensureInitializedLocked()
b, ok := s.Outputs[cpnID]
- if !ok {
+ if !ok || b == nil {
b = make(map[string]any)
s.Outputs[cpnID] = b
}
b[bucket] = payload
}
+func (s *CanvasState) ensureInitializedLocked() {
+ if s.Outputs == nil {
+ s.Outputs = make(map[string]map[string]any)
+ }
+ if s.Sys == nil {
+ s.Sys = make(map[string]any)
+ }
+ if s.Env == nil {
+ s.Env = make(map[string]any)
+ }
+ if s.Retrieval == nil {
+ s.Retrieval = make(map[string]any)
+ }
+ if s.Globals == nil {
+ s.Globals = make(map[string]any)
+ }
+ if s.CancelFlag == nil {
+ s.CancelFlag = &atomic.Bool{}
+ }
+}
+
// GetGlobal returns a value from the workflow-wide Globals bag. Globals is a
// generic, cross-component scratch space owned by CanvasState; the set of
// keys an ingestion pipeline elects to store there is ingestion-specific and
@@ -885,7 +933,7 @@ func getVarLocked(s *CanvasState, ref string) (any, error) {
// setVarLocked is the lock-free inner SetVar. Caller must hold s.mu.
func setVarLocked(outputs map[string]map[string]any, cpnID, param string, v any) {
bucket, ok := outputs[cpnID]
- if !ok {
+ if !ok || bucket == nil {
bucket = make(map[string]any)
outputs[cpnID] = bucket
}
@@ -897,7 +945,7 @@ func setVarLocked(outputs map[string]map[string]any, cpnID, param string, v any)
return
}
next, ok := cur[p].(map[string]any)
- if !ok {
+ if !ok || next == nil {
next = make(map[string]any)
cur[p] = next
}
diff --git a/internal/agent/runtime/state_test.go b/internal/agent/runtime/state_test.go
index ea74e49f76..5546579b8b 100644
--- a/internal/agent/runtime/state_test.go
+++ b/internal/agent/runtime/state_test.go
@@ -66,6 +66,105 @@ func TestCanvasState_MarshalUnmarshalJSON(t *testing.T) {
}
}
+func TestCanvasState_UnmarshalInitializesMutableState(t *testing.T) {
+ t.Parallel()
+
+ var state CanvasState
+ if err := json.Unmarshal([]byte(`{"outputs":null,"sys":null,"env":null,"retrieval":null,"globals":null}`), &state); err != nil {
+ t.Fatalf("Unmarshal: %v", err)
+ }
+
+ state.SetVar("message_0", "content", "hello")
+ state.RecordOutput("message_0", "result", map[string]any{"ok": true})
+ state.SetGlobal("flag", true)
+
+ if got := state.Outputs["message_0"]["content"]; got != "hello" {
+ t.Fatalf("SetVar after restore = %#v, want hello", got)
+ }
+ if got := state.Outputs["message_0"]["result"]; got == nil {
+ t.Fatal("RecordOutput after restore did not persist")
+ }
+ if got, ok := state.GetGlobal("flag"); !ok || got != true {
+ t.Fatalf("SetGlobal after restore = %#v, %v; want true, true", got, ok)
+ }
+}
+
+func TestCanvasStateRestoreReplacesNamespaces(t *testing.T) {
+ for _, raw := range []string{`{}`, `{"outputs":null,"sys":null,"env":null,"retrieval":null,"globals":null}`} {
+ t.Run(raw, func(t *testing.T) {
+ state := NewCanvasState("old-run", "old-session")
+ state.SetVar("old", "value", true)
+ state.Sys["old"] = true
+ state.Env["old"] = true
+ state.Retrieval["old"] = true
+ state.SetGlobal("old", true)
+ state.CancelFlag.Store(true)
+ if err := json.Unmarshal([]byte(raw), state); err != nil {
+ t.Fatal(err)
+ }
+ if state.Outputs == nil || len(state.Outputs) != 0 {
+ t.Fatalf("outputs = %#v, want empty writable map", state.Outputs)
+ }
+ for name, namespace := range map[string]map[string]any{
+ "sys": state.Sys, "env": state.Env, "retrieval": state.Retrieval, "globals": state.Globals,
+ } {
+ if namespace == nil || len(namespace) != 0 {
+ t.Fatalf("%s = %#v, want empty writable map", name, namespace)
+ }
+ }
+ if state.CancelFlag.Load() || state.RunID != "" || state.SessionID != "" {
+ t.Fatal("restore retained prior cancellation or identity")
+ }
+ })
+ }
+}
+
+func TestCanvasStateMergeAndReplaceNamespaces(t *testing.T) {
+ state := NewCanvasState("run", "session")
+ state.MergeNamespaces(
+ map[string]any{"query": "hello"},
+ map[string]any{"region": "test"},
+ map[string]any{"item": 1},
+ )
+ state.MergeNamespaces(map[string]any{"user_id": "user", "query": "updated"}, nil, nil)
+
+ sys, env, globals := state.SnapshotNamespaces()
+ if sys["query"] != "updated" || sys["user_id"] != "user" || env["region"] != "test" || globals["item"] != 1 {
+ t.Fatalf("merged namespaces = %#v, %#v, %#v", sys, env, globals)
+ }
+
+ replacement := map[string]any{"query": "replacement"}
+ state.ReplaceNamespaces(replacement, nil, nil)
+ replacement["query"] = "mutated"
+
+ sys, env, globals = state.SnapshotNamespaces()
+ if sys["query"] != "replacement" || len(sys) != 1 {
+ t.Fatalf("replaced sys = %#v", sys)
+ }
+ if env == nil || globals == nil || len(env) != 0 || len(globals) != 0 {
+ t.Fatalf("replaced empty namespaces = %#v, %#v", env, globals)
+ }
+}
+
+func TestCanvasStateWritesNullOutputBuckets(t *testing.T) {
+ for _, method := range []string{"SetVar", "RecordOutput"} {
+ t.Run(method, func(t *testing.T) {
+ var state CanvasState
+ if err := json.Unmarshal([]byte(`{"outputs":{"node":null}}`), &state); err != nil {
+ t.Fatal(err)
+ }
+ if method == "SetVar" {
+ state.SetVar("node", "value", "result")
+ } else {
+ state.RecordOutput("node", "value", "result")
+ }
+ if got, _ := state.GetVar("node@value"); got != "result" {
+ t.Fatalf("value = %#v, want result", got)
+ }
+ })
+ }
+}
+
func TestCanvasStateCheckpointPreservesCurrentUserMarker(t *testing.T) {
t.Parallel()
src := NewCanvasState("run-checkpoint", "task-checkpoint")
diff --git a/internal/agent/sandbox/http.go b/internal/agent/sandbox/http.go
index 29c53a3f3d..4597f051f0 100644
--- a/internal/agent/sandbox/http.go
+++ b/internal/agent/sandbox/http.go
@@ -20,9 +20,8 @@
// tool package — the tool package depends on the sandbox package
// (for ManagerClient) and not the other way around.
//
-// The retry semantics mirror the tool/http_helper defaults (3
-// attempts, 200ms base backoff, 3s cap, 5xx + network errors only).
-// 4xx is the caller's error and is not retried.
+// Idempotent requests retry up to 3 attempts by default with a 200ms
+// base backoff and 3s cap. Non-idempotent requests are attempted once.
package sandbox
@@ -94,10 +93,11 @@ func NewHTTPClient(cfg HTTPConfig) *HTTPClient {
// application/octet-stream.
//
// Retry policy:
-// - 5xx: retried
-// - network errors: retried
+// - 5xx: retried for idempotent methods
+// - network errors: retried for idempotent methods
// - 4xx: NOT retried
// - 2xx/3xx: returned as-is
+// - non-idempotent methods: attempted once and returned as-is
//
// The context is honored on every attempt; cancellation aborts the
// loop.
@@ -113,6 +113,7 @@ func (h *HTTPClient) Do(
contentType = "application/octet-stream"
}
+ retry := isIdempotent(method)
var lastErr error
for attempt := 1; attempt <= h.maxAttempts; attempt++ {
if err := ctx.Err(); err != nil {
@@ -132,6 +133,9 @@ func (h *HTTPClient) Do(
resp, err := h.client.Do(req)
if err != nil {
+ if !retry {
+ return nil, err
+ }
lastErr = err
if !isRetryableNetError(err) {
return nil, err
@@ -145,6 +149,9 @@ func (h *HTTPClient) Do(
// 5xx is retryable, 4xx is not.
if resp.StatusCode >= 500 {
+ if !retry {
+ return resp, nil
+ }
lastErr = fmt.Errorf("sandbox http: %s %s returned %d", method, url, resp.StatusCode)
_, _ = io.Copy(io.Discard, resp.Body)
_ = resp.Body.Close()
@@ -164,6 +171,15 @@ func (h *HTTPClient) Do(
return nil, errors.New("sandbox http: exhausted retries with no recorded error")
}
+func isIdempotent(method string) bool {
+ switch method {
+ case http.MethodGet, http.MethodHead, http.MethodPut, http.MethodDelete, http.MethodOptions, http.MethodTrace:
+ return true
+ default:
+ return false
+ }
+}
+
// backoff returns an exponentially increasing duration with full jitter,
// capped at max. attempt is 1-indexed; the first retry uses base.
func backoff(base, max time.Duration, attempt int) time.Duration {
diff --git a/internal/agent/sandbox/http_test.go b/internal/agent/sandbox/http_test.go
new file mode 100644
index 0000000000..af36feae11
--- /dev/null
+++ b/internal/agent/sandbox/http_test.go
@@ -0,0 +1,128 @@
+//
+// Copyright 2026 The InfiniFlow Authors. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+
+package sandbox
+
+import (
+ "errors"
+ "io"
+ "net"
+ "net/http"
+ "net/http/httptest"
+ "sync/atomic"
+ "syscall"
+ "testing"
+ "time"
+)
+
+func TestHTTPClientRetriesGETServerErrors(t *testing.T) {
+ var attempts atomic.Int32
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+ if attempts.Add(1) < 3 {
+ http.Error(w, "retry", http.StatusBadGateway)
+ return
+ }
+ w.WriteHeader(http.StatusOK)
+ }))
+ t.Cleanup(server.Close)
+
+ client := NewHTTPClient(HTTPConfig{MaxAttempts: 3, BaseBackoff: time.Nanosecond})
+ response, err := client.Do(t.Context(), http.MethodGet, server.URL, "", "", nil)
+ if err != nil {
+ t.Fatalf("GET: %v", err)
+ }
+ response.Body.Close()
+ if got := attempts.Load(); got != 3 {
+ t.Fatalf("GET attempts = %d, want 3", got)
+ }
+}
+
+func TestHTTPClientDoesNotRetryPOSTServerErrors(t *testing.T) {
+ var attempts atomic.Int32
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+ attempts.Add(1)
+ http.Error(w, "failed", http.StatusBadGateway)
+ }))
+ t.Cleanup(server.Close)
+
+ client := NewHTTPClient(HTTPConfig{MaxAttempts: 3, BaseBackoff: time.Nanosecond})
+ response, err := client.Do(t.Context(), http.MethodPost, server.URL+"/run", "{}", "application/json", nil)
+ if err != nil {
+ t.Fatalf("POST: %v", err)
+ }
+ defer response.Body.Close()
+ if got := attempts.Load(); got != 1 {
+ t.Fatalf("POST attempts = %d, want 1", got)
+ }
+ if response.StatusCode != http.StatusBadGateway {
+ t.Fatalf("POST status = %d, want %d", response.StatusCode, http.StatusBadGateway)
+ }
+ body, err := io.ReadAll(response.Body)
+ if err != nil {
+ t.Fatalf("read POST response: %v", err)
+ }
+ if string(body) != "failed\n" {
+ t.Fatalf("POST body = %q, want %q", body, "failed\\n")
+ }
+}
+
+func TestHTTPClientDoesNotRetryPOSTNetworkErrors(t *testing.T) {
+ wantErr := &net.OpError{Op: "read", Net: "tcp", Err: syscall.ETIMEDOUT}
+ transport := &errorTransport{err: wantErr}
+ client := NewHTTPClient(HTTPConfig{MaxAttempts: 3, BaseBackoff: time.Nanosecond})
+ client.client.Transport = transport
+
+ response, err := client.Do(t.Context(), http.MethodPost, "http://sandbox.test/run", "{}", "application/json", nil)
+ if response != nil {
+ response.Body.Close()
+ t.Fatalf("POST response = %v, want nil", response)
+ }
+ if !errors.Is(err, wantErr) {
+ t.Fatalf("POST error = %v, want %v", err, wantErr)
+ }
+ if got := transport.attempts.Load(); got != 1 {
+ t.Fatalf("POST attempts = %d, want 1", got)
+ }
+}
+
+func TestHTTPClientRetriesGETNetworkErrors(t *testing.T) {
+ wantErr := &net.OpError{Op: "read", Net: "tcp", Err: syscall.ETIMEDOUT}
+ transport := &errorTransport{err: wantErr}
+ client := NewHTTPClient(HTTPConfig{MaxAttempts: 3, BaseBackoff: time.Nanosecond})
+ client.client.Transport = transport
+
+ response, err := client.Do(t.Context(), http.MethodGet, "http://sandbox.test/healthz", "", "", nil)
+ if response != nil {
+ response.Body.Close()
+ t.Fatalf("GET response = %v, want nil", response)
+ }
+ if !errors.Is(err, syscall.ETIMEDOUT) {
+ t.Fatalf("GET error = %v, want timeout", err)
+ }
+ if got := transport.attempts.Load(); got != 3 {
+ t.Fatalf("GET attempts = %d, want 3", got)
+ }
+}
+
+type errorTransport struct {
+ attempts atomic.Int32
+ err error
+}
+
+func (t *errorTransport) RoundTrip(*http.Request) (*http.Response, error) {
+ t.attempts.Add(1)
+ return nil, t.err
+}
diff --git a/internal/agent/sandbox/ucloud_agent_sandbox.go b/internal/agent/sandbox/ucloud_agent_sandbox.go
index 1f593ea119..975fb9ba6c 100644
--- a/internal/agent/sandbox/ucloud_agent_sandbox.go
+++ b/internal/agent/sandbox/ucloud_agent_sandbox.go
@@ -291,17 +291,15 @@ func (p *UCloudAgentSandboxProvider) ExecuteCode(
ExitCode: commandResult.ExitCode,
ExecutionTime: executionTime,
Metadata: map[string]any{
- "instance_id": inst.InstanceID,
- "sandbox_id": instance.sandbox.ID,
- "language": normalizedLanguage,
- "script_path": scriptPath,
- "remote_work_dir": instance.remoteWorkDir,
- "status": map[bool]string{true: "ok", false: "error"}[commandResult.ExitCode == 0],
- "timeout": executionTimeout,
- "artifacts": artifacts,
- "result_present": structured["present"],
- "result_value": structured["value"],
- "result_type": structured["type"],
+ "instance_id": inst.InstanceID,
+ "sandbox_id": instance.sandbox.ID,
+ "language": normalizedLanguage,
+ "script_path": scriptPath,
+ "remote_work_dir": instance.remoteWorkDir,
+ "status": map[bool]string{true: "ok", false: "error"}[commandResult.ExitCode == 0],
+ "timeout": executionTimeout,
+ "artifacts": artifacts,
+ "structured_result": structured,
},
}, nil
}
diff --git a/internal/agent/tool/agentic_search.go b/internal/agent/tool/agentic_search.go
index 2bcb3b9b86..57f293cd7a 100644
--- a/internal/agent/tool/agentic_search.go
+++ b/internal/agent/tool/agentic_search.go
@@ -41,12 +41,11 @@ const (
// hybridSearchArgs is the shared JSON schema for the three retrieval tools.
type hybridSearchArgs struct {
- Query string `json:"query"`
- KbIDs []string `json:"kb_ids,omitempty"`
- TopN int `json:"top_n,omitempty"`
- DocScope []string `json:"doc_scope,omitempty"`
- Keywords string `json:"keywords,omitempty"`
- UseCompiled bool `json:"use_compiled,omitempty"`
+ Query string `json:"query"`
+ KbIDs []string `json:"kb_ids,omitempty"`
+ TopN int `json:"top_n,omitempty"`
+ DocScope []string `json:"doc_scope,omitempty"`
+ Keywords string `json:"keywords,omitempty"`
}
type agenticSearchResult struct {
@@ -89,18 +88,17 @@ func (a *AgenticSearchTool) Info(_ context.Context) (*schema.ToolInfo, error) {
"query": {
Type: schema.String, Required: true, Desc: "The search query.",
},
- "kb_ids": {Type: schema.Array, Desc: "Optional dataset ids to restrict to."},
- "top_n": {Type: schema.Number, Desc: "Number of passages to return (default 12)."},
- "doc_scope": {Type: schema.Array, Desc: "Optional doc ids to restrict to."},
- "keywords": {Type: schema.String, Desc: "Comma-separated keywords to narrow results."},
- "use_compiled": {Type: schema.Boolean, Desc: "Whether to enrich with compiled products."},
+ "kb_ids": {Type: schema.Array, Desc: "Optional dataset ids to restrict to."},
+ "top_n": {Type: schema.Number, Desc: "Number of passages to return (default 12)."},
+ "doc_scope": {Type: schema.Array, Desc: "Optional doc ids to restrict to."},
+ "keywords": {Type: schema.String, Desc: "Comma-separated keywords to narrow results."},
}),
}, nil
}
// InvokableRun executes the retrieval. It returns JSON with "chunks" (array of
-// chunk maps). Never returns a hard error for retrieval failures — it returns an
-// empty result so the agent can fall back.
+// chunk maps). Retrieval failures are returned so the caller can distinguish
+// an unavailable backend from a successful search with no matches.
func (a *AgenticSearchTool) InvokableRun(ctx context.Context, argumentsInJSON string, _ ...einotool.Option) (string, error) {
var args hybridSearchArgs
if err := json.Unmarshal([]byte(argumentsInJSON), &args); err != nil {
@@ -132,10 +130,12 @@ func (a *AgenticSearchTool) InvokableRun(ctx context.Context, argumentsInJSON st
AllowDenseFallback: new(false),
KeywordsSimilarityWeight: &weight,
DocScope: args.DocScope,
+ TenantID: tenantID,
+ ExcludeCompiled: true,
}
chunks, err := svc.Search(ctx, nil, req)
if err != nil {
- return jsonChunksEmpty(), nil // agent falls back on failure
+ return "", fmt.Errorf("%s: retrieval: %w", a.mode, err)
}
// Keyword narrowing (mirrors Python _narrow_by_keywords).
diff --git a/internal/agent/tool/code_exec.go b/internal/agent/tool/code_exec.go
index 04196c704f..64201bcf4a 100644
--- a/internal/agent/tool/code_exec.go
+++ b/internal/agent/tool/code_exec.go
@@ -223,6 +223,7 @@ func codeExecResultJSON(ctx context.Context, r *SandboxResponse) (string, error)
}
if strings.TrimSpace(r.Stderr) != "" &&
!hasStructuredResult &&
+ r.Returned == "" &&
len(out.Artifacts) == 0 &&
strings.TrimSpace(r.Stdout) == "" {
out.Error = r.Stderr
@@ -231,8 +232,8 @@ func codeExecResultJSON(ctx context.Context, r *SandboxResponse) (string, error)
fmt.Fprintln(os.Stderr, "code_exec: falling back to stdout deserialization because no structured result metadata was provided")
}
out.RawResult = NormalizeCodeExecOutputValue(resolvedValue)
- out.ActualType = InferCodeExecActualType(out.RawResult)
- out.Content = RenderCodeExecCanonicalContent(out.RawResult)
+ out.ActualType = inferCodeExecActualType(out.RawResult)
+ out.Content = renderCodeExecCanonicalContent(out.RawResult)
}
common.Debug("CodeExec tool",
zap.Any("structured_result", r.StructuredResult),
@@ -385,6 +386,9 @@ func resolveCodeExecResultValue(r *SandboxResponse) (any, bool) {
return r.StructuredResult["value"], false
}
}
+ if r != nil && r.Returned != "" {
+ return r.Returned, false
+ }
return deserializeCodeExecStdout(r.Stdout), true
}
diff --git a/internal/agent/tool/code_exec_contract.go b/internal/agent/tool/code_exec_contract.go
index d7d98a39c6..847c0117a7 100644
--- a/internal/agent/tool/code_exec_contract.go
+++ b/internal/agent/tool/code_exec_contract.go
@@ -64,8 +64,8 @@ func BuildCodeExecContract(outputs map[string]any, rawResult any) (*CodeExecCont
return &CodeExecContract{
BusinessOutput: businessName,
Value: normalizedValue,
- ActualType: InferCodeExecActualType(normalizedValue),
- Content: RenderCodeExecCanonicalContent(normalizedValue),
+ ActualType: inferCodeExecActualType(normalizedValue),
+ Content: renderCodeExecCanonicalContent(normalizedValue),
}, nil
}
@@ -89,7 +89,10 @@ func NormalizeCodeExecOutputValue(value any) any {
}
func InferCodeExecActualType(value any) string {
- value = NormalizeCodeExecOutputValue(value)
+ return inferCodeExecActualType(NormalizeCodeExecOutputValue(value))
+}
+
+func inferCodeExecActualType(value any) string {
switch v := value.(type) {
case nil:
return "Null"
@@ -103,9 +106,9 @@ func InferCodeExecActualType(value any) string {
if len(v) == 0 {
return "Array<Any>"
}
- first := InferCodeExecActualType(v[0])
+ first := inferCodeExecActualType(v[0])
for _, item := range v[1:] {
- if InferCodeExecActualType(item) != first {
+ if inferCodeExecActualType(item) != first {
return "Array<Any>"
}
}
@@ -130,7 +133,10 @@ func InferCodeExecActualType(value any) string {
}
func RenderCodeExecCanonicalContent(value any) string {
- value = NormalizeCodeExecOutputValue(value)
+ return renderCodeExecCanonicalContent(NormalizeCodeExecOutputValue(value))
+}
+
+func renderCodeExecCanonicalContent(value any) string {
switch v := value.(type) {
case nil:
return ""
@@ -215,13 +221,12 @@ func validateCodeExecExpectedType(expectedType string, value any, path string) e
return nil
}
- value = NormalizeCodeExecOutputValue(value)
if strings.HasPrefix(etype, "Array<") && strings.HasSuffix(etype, ">") {
list, ok := value.([]any)
if !ok {
return fmt.Errorf(
"CodeExec contract mismatch at %s: expected type %s, got %s",
- codeExecPathOrValue(path), etype, InferCodeExecActualType(value),
+ codeExecPathOrValue(path), etype, inferCodeExecActualType(value),
)
}
innerType := strings.TrimSpace(etype[len("Array<") : len(etype)-1])
@@ -260,7 +265,7 @@ func validateCodeExecExpectedType(expectedType string, value any, path string) e
}
return fmt.Errorf(
"CodeExec contract mismatch at %s: expected type %s, got %s",
- codeExecPathOrValue(path), etype, InferCodeExecActualType(value),
+ codeExecPathOrValue(path), etype, inferCodeExecActualType(value),
)
}
diff --git a/internal/agent/tool/code_exec_test.go b/internal/agent/tool/code_exec_test.go
index e86f9e1147..27fdfd05a3 100644
--- a/internal/agent/tool/code_exec_test.go
+++ b/internal/agent/tool/code_exec_test.go
@@ -22,6 +22,7 @@ import (
"encoding/base64"
"encoding/json"
"errors"
+ "reflect"
"strings"
"testing"
@@ -182,6 +183,27 @@ func TestCodeExec_Info(t *testing.T) {
}
}
+func TestCodeExecPublicFormattingHandlesTypedNilSlice(t *testing.T) {
+ t.Parallel()
+
+ var value []any
+ if got := InferCodeExecActualType(value); got != "Array<Any>" {
+ t.Fatalf("InferCodeExecActualType(typed nil) = %q, want Array<Any>", got)
+ }
+ if got := RenderCodeExecCanonicalContent(value); got != "[]" {
+ t.Fatalf("RenderCodeExecCanonicalContent(typed nil) = %q, want []", got)
+ }
+
+ contract, err := BuildCodeExecContract(map[string]any{"result": nil}, value)
+ if err != nil {
+ t.Fatalf("BuildCodeExecContract(typed nil): %v", err)
+ }
+ normalized, ok := contract.Value.([]any)
+ if !ok || normalized == nil {
+ t.Fatalf("contract.Value = %#v, want non-nil empty []any", contract.Value)
+ }
+}
+
// TestCodeExec_ResultExtractsArtifacts pins the artifact
// collection: SandboxResponse.Metadata["artifacts"] entries that
// already carry a hosted URL surface unchanged as `_ARTIFACTS` in
@@ -526,6 +548,90 @@ func TestCodeExec_ResultUsesStructuredResultValue(t *testing.T) {
}
}
+func TestCodeExec_ResultPrecedence(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ response *SandboxResponse
+ wantResult any
+ wantType string
+ }{
+ {
+ name: "structured result wins over legacy and streams",
+ response: &SandboxResponse{
+ StructuredResult: map[string]any{"present": true, "value": float64(8)},
+ Returned: "legacy",
+ Stdout: "stdout",
+ Stderr: "warning",
+ },
+ wantResult: float64(8),
+ wantType: "Number",
+ },
+ {
+ name: "explicit structured null wins over legacy and streams",
+ response: &SandboxResponse{
+ StructuredResult: map[string]any{"present": true, "value": nil},
+ Returned: "legacy",
+ Stdout: "stdout",
+ Stderr: "warning",
+ },
+ wantType: "Null",
+ },
+ {
+ name: "legacy returned value tolerates warning streams",
+ response: &SandboxResponse{
+ Returned: "legacy result",
+ Stderr: "warning",
+ },
+ wantResult: "legacy result",
+ wantType: "String",
+ },
+ {
+ name: "legacy returned value wins over stdout and stderr",
+ response: &SandboxResponse{
+ Returned: "legacy result",
+ Stdout: "diagnostic output",
+ Stderr: "warning",
+ },
+ wantResult: "legacy result",
+ wantType: "String",
+ },
+ {
+ name: "stdout remains the final fallback",
+ response: &SandboxResponse{Stdout: `{"a":[1,2]}`},
+ wantResult: map[string]any{"a": []any{float64(1), float64(2)}},
+ wantType: "Object",
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ out, err := codeExecResultJSON(t.Context(), tt.response)
+ if err != nil {
+ t.Fatalf("codeExecResultJSON: %v", err)
+ }
+ var got map[string]any
+ if err := json.Unmarshal([]byte(out), &got); err != nil {
+ t.Fatalf("output not valid JSON: %v", err)
+ }
+ if got["_ERROR"] != nil {
+ t.Fatalf("_ERROR = %#v, want successful result", got["_ERROR"])
+ }
+ if tt.wantResult == nil {
+ if _, ok := got["raw_result"]; ok {
+ t.Fatalf("raw_result = %#v, want omitted JSON null", got["raw_result"])
+ }
+ } else if !reflect.DeepEqual(got["raw_result"], tt.wantResult) {
+ t.Fatalf("raw_result = %#v, want %#v", got["raw_result"], tt.wantResult)
+ }
+ if got["actual_type"] != tt.wantType {
+ t.Fatalf("actual_type = %#v, want %q", got["actual_type"], tt.wantType)
+ }
+ })
+ }
+}
+
func TestCodeExec_ResultFallsBackToStdoutJSON(t *testing.T) {
t.Parallel()
diff --git a/internal/agent/tool/retrieval_test.go b/internal/agent/tool/retrieval_test.go
index 5bb5563f23..6bc16d0a2b 100644
--- a/internal/agent/tool/retrieval_test.go
+++ b/internal/agent/tool/retrieval_test.go
@@ -143,6 +143,62 @@ func TestAgenticSearchDisablesDenseFallback(t *testing.T) {
}
}
+func TestAgenticSearchExcludesCompiledResults(t *testing.T) {
+ previous := GetRetrievalService()
+ service := &capturingRetrievalService{}
+ SetRetrievalService(service)
+ t.Cleanup(func() { SetRetrievalService(previous) })
+
+ state := runtime.NewCanvasState("run-compiled", "session-compiled")
+ state.Sys["tenant_id"] = "tenant-1"
+ ctx := runtime.WithState(t.Context(), state)
+
+ if _, err := NewAgenticSearchTool(toolHybridSearch).InvokableRun(ctx, `{"query":"plain","kb_ids":["kb-1"]}`); err != nil {
+ t.Fatal(err)
+ }
+ if !service.req.ExcludeCompiled {
+ t.Fatal("default agentic search should exclude compiled results")
+ }
+ if service.req.TenantID != "tenant-1" {
+ t.Fatalf("TenantID = %q, want tenant-1", service.req.TenantID)
+ }
+}
+
+func TestAgenticSearchDoesNotAdvertiseUnsupportedCompiledExpansion(t *testing.T) {
+ info, err := NewAgenticSearchTool(toolHybridSearch).Info(t.Context())
+ if err != nil {
+ t.Fatal(err)
+ }
+ schemaJSON, err := json.Marshal(info.ParamsOneOf)
+ if err != nil {
+ t.Fatal(err)
+ }
+ if strings.Contains(string(schemaJSON), `"use_compiled"`) {
+ t.Fatalf("schema advertises unsupported compiled expansion: %s", schemaJSON)
+ }
+}
+
+type failingAgenticRetrievalService struct{}
+
+func (failingAgenticRetrievalService) Search(context.Context, *gorm.DB, RetrievalRequest) ([]RetrievalChunk, error) {
+ return nil, errors.New("backend unavailable")
+}
+
+func TestAgenticSearchReturnsRetrievalError(t *testing.T) {
+ previous := GetRetrievalService()
+ SetRetrievalService(failingAgenticRetrievalService{})
+ t.Cleanup(func() { SetRetrievalService(previous) })
+
+ state := runtime.NewCanvasState("run-error", "session-error")
+ state.Sys["tenant_id"] = "tenant-1"
+ ctx := runtime.WithState(t.Context(), state)
+
+ _, err := NewAgenticSearchTool(toolHybridSearch).InvokableRun(ctx, `{"query":"hello","kb_ids":["kb-1"]}`)
+ if err == nil || !strings.Contains(err.Error(), "backend unavailable") {
+ t.Fatalf("error = %v, want backend unavailable", err)
+ }
+}
+
func TestRetrieval_PassesTenantIDFromCanvasState(t *testing.T) {
prev := GetRetrievalService()
svc := &capturingRetrievalService{}
diff --git a/internal/agent/tool/ssrf.go b/internal/agent/tool/ssrf.go
index e85bed4eee..f465107d7e 100644
--- a/internal/agent/tool/ssrf.go
+++ b/internal/agent/tool/ssrf.go
@@ -88,14 +88,18 @@ func ResolveAndValidate(rawURL string) (originalHost string, pinnedIP net.IP, er
if ip := net.ParseIP(host); ip != nil {
return host, ip, nil
}
- ips, lerr := net.LookupIP(host)
+ addrs, lerr := common.LookupHost(host)
if lerr != nil {
return "", nil, fmt.Errorf("ssrf: resolve %s: %w", host, lerr)
}
- if len(ips) == 0 {
+ if len(addrs) == 0 {
return "", nil, fmt.Errorf("ssrf: %s has no A/AAAA records", host)
}
- return host, ips[0], nil
+ ip := net.ParseIP(addrs[0])
+ if ip == nil {
+ return "", nil, fmt.Errorf("ssrf: could not parse resolved address %q for %s", addrs[0], host)
+ }
+ return host, ip, nil
}
// Short-circuit the well-known host aliases that DNS lookups may
@@ -116,12 +120,16 @@ func ResolveAndValidate(rawURL string) (originalHost string, pinnedIP net.IP, er
return host, ip, nil
}
- ips, lerr := net.LookupIP(host)
+ addrs, lerr := common.LookupHost(host)
if lerr != nil {
return "", nil, fmt.Errorf("ssrf: resolve %s: %w", host, lerr)
}
var firstSafe net.IP
- for _, ip := range ips {
+ for _, addr := range addrs {
+ ip := net.ParseIP(addr)
+ if ip == nil {
+ return "", nil, fmt.Errorf("ssrf: could not parse resolved address %q for %s", addr, host)
+ }
if isPrivateOrLoopback(ip) {
return "", nil, fmt.Errorf("%w: %s -> %s", ErrSSRFBlocked, host, ip)
}
@@ -152,12 +160,7 @@ func isPrivateOrLoopback(ip net.IP) bool {
}
func allowAnyHost() bool {
- switch strings.ToLower(strings.TrimSpace(common.GetEnv(common.EnvAllowAnyHost))) {
- case "1", "true", "yes", "on":
- return true
- default:
- return false
- }
+ return common.AllowAnyHostForTest
}
// ValidateDBHost parses host (literal IP or DNS name), verifies it
@@ -180,7 +183,7 @@ func ValidateDBHost(host string) (string, error) {
return "", fmt.Errorf("%w: empty host", ErrSSRFBlocked)
}
- // Mirror ResolveAndValidate's bypass for dev/test runs.
+ // Mirror ResolveAndValidate's test-only bypass.
if allowAnyHost() {
if ip := net.ParseIP(host); ip != nil {
return ip.String(), nil
diff --git a/internal/agent/tool/ssrf_test.go b/internal/agent/tool/ssrf_test.go
index 72571278b6..79778bea3e 100644
--- a/internal/agent/tool/ssrf_test.go
+++ b/internal/agent/tool/ssrf_test.go
@@ -18,19 +18,27 @@ package tool
import (
"net"
+ "ragflow/internal/common"
"strings"
"testing"
- "time"
)
func TestValidateURLForSSRF(t *testing.T) {
+ originalLookupHost := common.LookupHost
+ common.LookupHost = func(host string) ([]string, error) {
+ if host == "example.com" {
+ return []string{"93.184.216.34"}, nil
+ }
+ return originalLookupHost(host)
+ }
+ t.Cleanup(func() { common.LookupHost = originalLookupHost })
+
cases := []struct {
name string
rawURL string
wantErr bool
}{
- // Public targets: should pass (DNS may still fail in CI; we
- // accept both "ok" and "resolve error").
+ // Public targets: should pass.
{"https_public", "https://example.com/", false},
{"http_public", "http://1.1.1.1/", false},
@@ -68,10 +76,7 @@ func TestValidateURLForSSRF(t *testing.T) {
t.Errorf("validateURLForSSRF(%q) = %q, want an ssrf-tagged error", tc.rawURL, err)
}
} else if err != nil {
- // Public target may fail DNS in CI; tolerate resolve errors.
- if !strings.Contains(err.Error(), "resolve") {
- t.Errorf("validateURLForSSRF(%q) = %q, want nil or resolve error", tc.rawURL, err)
- }
+ t.Errorf("validateURLForSSRF(%q) = %q, want nil", tc.rawURL, err)
}
})
}
@@ -122,41 +127,24 @@ func TestResolveAndValidate(t *testing.T) {
})
t.Run("hostname_resolves_to_public", func(t *testing.T) {
- // example.com is required to resolve to a public IP per RFC 2606.
- // The DNS lookup is wrapped in a goroutine with a 2s deadline so
- // sandboxed CI environments without upstream DNS can skip the
- // test rather than hang the suite (the default LookupIP honours
- // no timeout; this was the root cause of the 60s test timeout
- // during the rebinding-hardening review).
- type result struct {
- host string
- ip net.IP
- err error
- }
- ch := make(chan result, 1)
- go func() {
- h, ip, err := ResolveAndValidate("https://example.com/")
- ch <- result{h, ip, err}
- }()
- select {
- case r := <-ch:
- if r.err != nil {
- if strings.Contains(r.err.Error(), "resolve") {
- t.Skipf("DNS unavailable in CI: %v", r.err)
- }
- t.Fatalf("ResolveAndValidate(example.com) = %v, want nil", r.err)
- }
- if r.host != "example.com" {
- t.Errorf("host = %q, want example.com", r.host)
- }
- if r.ip == nil {
- t.Fatalf("ip = nil, want non-nil")
+ originalLookupHost := common.LookupHost
+ common.LookupHost = func(host string) ([]string, error) {
+ if host == "example.test" {
+ return []string{"93.184.216.34"}, nil
}
- if r.ip.IsLoopback() || r.ip.IsPrivate() || r.ip.IsLinkLocalUnicast() {
- t.Errorf("ip = %s, want a public address", r.ip)
- }
- case <-time.After(2 * time.Second):
- t.Skip("DNS lookup for example.com timed out — sandboxed CI without upstream DNS")
+ return originalLookupHost(host)
+ }
+ t.Cleanup(func() { common.LookupHost = originalLookupHost })
+
+ host, ip, err := ResolveAndValidate("https://example.test/")
+ if err != nil {
+ t.Fatalf("ResolveAndValidate(example.test) = %v, want nil", err)
+ }
+ if host != "example.test" {
+ t.Errorf("host = %q, want example.test", host)
+ }
+ if !ip.Equal(net.ParseIP("93.184.216.34")) {
+ t.Errorf("ip = %s, want 93.184.216.34", ip)
}
})
@@ -183,6 +171,38 @@ func TestResolveAndValidate(t *testing.T) {
})
}
+func TestResolveAndValidateProductionEnvCannotDisableGuard(t *testing.T) {
+ t.Setenv(common.EnvAllowAnyHost, "true")
+
+ if _, _, err := ResolveAndValidate("http://127.0.0.1/"); err == nil {
+ t.Fatal("ResolveAndValidate(loopback) = nil, want SSRF rejection")
+ }
+ if _, err := ValidateDBHost("127.0.0.1"); err == nil {
+ t.Fatal("ValidateDBHost(loopback) = nil, want SSRF rejection")
+ }
+}
+
+func TestResolveAndValidateTestHookAllowsLocalhost(t *testing.T) {
+ common.AllowAnyHostForTest = true
+ t.Cleanup(func() { common.AllowAnyHostForTest = false })
+
+ host, ip, err := ResolveAndValidate("http://127.0.0.1/")
+ if err != nil {
+ t.Fatalf("ResolveAndValidate(loopback) = %v, want nil with test hook", err)
+ }
+ if host != "127.0.0.1" || !ip.Equal(net.ParseIP("127.0.0.1")) {
+ t.Fatalf("ResolveAndValidate(loopback) = (%q, %v), want (127.0.0.1, 127.0.0.1)", host, ip)
+ }
+
+ dbHost, err := ValidateDBHost("127.0.0.1")
+ if err != nil {
+ t.Fatalf("ValidateDBHost(loopback) = %v, want nil with test hook", err)
+ }
+ if dbHost != "127.0.0.1" {
+ t.Fatalf("ValidateDBHost(loopback) = %q, want 127.0.0.1", dbHost)
+ }
+}
+
func TestSanitizeURL(t *testing.T) {
cases := []struct {
name string
diff --git a/internal/dao/user_canvas_version.go b/internal/dao/user_canvas_version.go
index 679c751452..8715bf793f 100644
--- a/internal/dao/user_canvas_version.go
+++ b/internal/dao/user_canvas_version.go
@@ -52,13 +52,6 @@ func NewUserCanvasVersionDAO() *UserCanvasVersionDAO {
return &UserCanvasVersionDAO{}
}
-// Create inserts a new version row. The caller assigns ID, UserCanvasID,
-// Title, Description, DSL. CreateTime/UpdateTime are stamped by the
-// BaseModel BeforeCreate hook.
-func (dao *UserCanvasVersionDAO) Create(ctx context.Context, db *gorm.DB, v *entity.UserCanvasVersion) error {
- return db.WithContext(ctx).Create(v).Error
-}
-
// GetByID fetches a single version by primary key. Returns
// ErrUserCanvasVersionNotFound when the row is absent so callers can map
// to a 404 instead of inspecting gorm.ErrRecordNotFound directly.
@@ -144,11 +137,6 @@ func (dao *UserCanvasVersionDAO) GetLatestReleaseTimes(ctx context.Context, db *
return result, nil
}
-// Delete removes a single version by id. No-op when the row is absent.
-func (dao *UserCanvasVersionDAO) Delete(ctx context.Context, db *gorm.DB, id string) error {
- return db.WithContext(ctx).Where("id = ?", id).Delete(&entity.UserCanvasVersion{}).Error
-}
-
// DeleteTx is the transactional variant of Delete. Used by
// service.AgentService.DeleteVersion so the version-row removal and the
// (future) parent-canvas stat update land in one atomic write.
@@ -156,14 +144,6 @@ func (dao *UserCanvasVersionDAO) DeleteTx(ctx context.Context, tx *gorm.DB, id s
return tx.WithContext(ctx).Where("id = ?", id).Delete(&entity.UserCanvasVersion{}).Error
}
-// DeleteByCanvasID removes every version of the given canvas. Called from
-// the service layer when the parent canvas is deleted to enforce the
-// §2.9 cascade rule. Returns the number of rows actually deleted.
-func (dao *UserCanvasVersionDAO) DeleteByCanvasID(ctx context.Context, db *gorm.DB, canvasID string) (int64, error) {
- res := db.WithContext(ctx).Where("user_canvas_id = ?", canvasID).Delete(&entity.UserCanvasVersion{})
- return res.RowsAffected, res.Error
-}
-
// DeleteByCanvasIDTx is the transactional variant of DeleteByCanvasID.
// Used by service.AgentService.DeleteAgent so the cascade runs atomically
// with the parent canvas row removal.
@@ -172,34 +152,13 @@ func (dao *UserCanvasVersionDAO) DeleteByCanvasIDTx(ctx context.Context, tx *gor
return res.RowsAffected, res.Error
}
-// CreateTx is the transactional variant of Create.
+// CreateTx inserts a version using the caller's transaction.
func (dao *UserCanvasVersionDAO) CreateTx(ctx context.Context, tx *gorm.DB, v *entity.UserCanvasVersion) error {
return tx.WithContext(ctx).Create(v).Error
}
-// SaveOrReplaceLatest inserts a new version or refreshes the latest matching
-// draft in place. If the latest matching version is released and the current
-// save is a draft, it creates a new draft to preserve the released snapshot.
-func (dao *UserCanvasVersionDAO) SaveOrReplaceLatest(ctx context.Context, db *gorm.DB, opts SaveOrReplaceLatestVersionOptions) (*entity.UserCanvasVersion, error) {
- if opts.KeepUnpublished <= 0 {
- opts.KeepUnpublished = 20
- }
- var saved *entity.UserCanvasVersion
- if err := db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
- row, err := dao.SaveOrReplaceLatestTx(ctx, tx, opts)
- if err != nil {
- return err
- }
- saved = row
- return nil
- }); err != nil {
- return nil, err
- }
- return saved, nil
-}
-
// SaveOrReplaceLatestTx inserts or refreshes a version using the caller's
-// transaction. Its write semantics match SaveOrReplaceLatest exactly.
+// transaction.
func (dao *UserCanvasVersionDAO) SaveOrReplaceLatestTx(ctx context.Context, tx *gorm.DB, opts SaveOrReplaceLatestVersionOptions) (*entity.UserCanvasVersion, error) {
if opts.KeepUnpublished <= 0 {
opts.KeepUnpublished = 20
diff --git a/internal/dao/user_canvas_version_test.go b/internal/dao/user_canvas_version_test.go
index 5ecc50509b..f956389231 100644
--- a/internal/dao/user_canvas_version_test.go
+++ b/internal/dao/user_canvas_version_test.go
@@ -64,13 +64,13 @@ func TestUserCanvasVersionDAO_NotFoundSentinel(t *testing.T) {
// UserCanvasVersionDAO. Asserting at compile time that the concrete DAO
// satisfies it prevents accidental signature drift in future refactors.
type daoInterface interface {
- Create(ctx context.Context, db *gorm.DB, v *entity.UserCanvasVersion) error
GetByID(ctx context.Context, db *gorm.DB, id string) (*entity.UserCanvasVersion, error)
ListByCanvasID(ctx context.Context, db *gorm.DB, canvasID string) ([]*entity.UserCanvasVersion, error)
GetLatest(ctx context.Context, db *gorm.DB, canvasID string) (*entity.UserCanvasVersion, error)
- SaveOrReplaceLatest(ctx context.Context, db *gorm.DB, opts SaveOrReplaceLatestVersionOptions) (*entity.UserCanvasVersion, error)
- Delete(ctx context.Context, db *gorm.DB, id string) error
- DeleteByCanvasID(ctx context.Context, db *gorm.DB, canvasID string) (int64, error)
+ CreateTx(ctx context.Context, tx *gorm.DB, v *entity.UserCanvasVersion) error
+ SaveOrReplaceLatestTx(ctx context.Context, tx *gorm.DB, opts SaveOrReplaceLatestVersionOptions) (*entity.UserCanvasVersion, error)
+ DeleteTx(ctx context.Context, tx *gorm.DB, id string) error
+ DeleteByCanvasIDTx(ctx context.Context, tx *gorm.DB, canvasID string) (int64, error)
}
var _ daoInterface = (*UserCanvasVersionDAO)(nil)
diff --git a/internal/handler/agent.go b/internal/handler/agent.go
index 44dcbd6159..cdb33b8311 100644
--- a/internal/handler/agent.go
+++ b/internal/handler/agent.go
@@ -469,6 +469,7 @@ func (h *AgentHandler) RunAgent(c *gin.Context) {
// Allocate the ordinary-Agent session identity at the HTTP boundary.
// Persistence of the session record remains owned by AgentService.RunAgent.
sessionID = utility.GenerateToken()
+ c.Request = c.Request.WithContext(service.WithAgentSessionID(c.Request.Context(), sessionID))
}
userInput, err := readUserInput(c)
if err != nil {
@@ -1271,6 +1272,7 @@ func (h *AgentHandler) AgentChatCompletions(c *gin.Context) {
// to the task_id=session_id wire alias even when the canvas emits no
// events (for example an empty query).
req.SessionID = utility.GenerateToken()
+ c.Request = c.Request.WithContext(service.WithAgentSessionID(c.Request.Context(), req.SessionID))
}
// req.Files is already normalized to the 1D file list by the
diff --git a/internal/handler/agent_openai.go b/internal/handler/agent_openai.go
index d5e8958e62..5f96a3af44 100644
--- a/internal/handler/agent_openai.go
+++ b/internal/handler/agent_openai.go
@@ -108,6 +108,7 @@ func (h *AgentHandler) handleOpenAICompat(c *gin.Context, user *entity.User, req
question := extractLastUserContent(req.Messages)
if req.SessionID == "" {
req.SessionID = utility.GenerateToken()
+ c.Request = c.Request.WithContext(service.WithAgentSessionID(c.Request.Context(), req.SessionID))
}
runContext := service.WithOpenAICompatMessages(c.Request.Context(), req.Messages)
diff --git a/internal/handler/agent_test.go b/internal/handler/agent_test.go
index 9ed0eb87b4..5e37e01c2f 100644
--- a/internal/handler/agent_test.go
+++ b/internal/handler/agent_test.go
@@ -717,14 +717,16 @@ func TestAgentChatCompletions_OpenAICompat_EmptyMessages(t *testing.T) {
// event, trailing `data: [DONE]\n\n`) without standing up the eino
// runner or a live DB.
type stubChatRunner struct {
- events []canvas.RunEvent
- err error
- sessionID string
- userInput any
+ events []canvas.RunEvent
+ err error
+ sessionID string
+ trustedSessionID string
+ userInput any
}
-func (s *stubChatRunner) RunAgent(_ context.Context, _, _, sessionID, _ string, userInput any, _ []map[string]interface{}) (<-chan canvas.RunEvent, error) {
+func (s *stubChatRunner) RunAgent(ctx context.Context, _, _, sessionID, _ string, userInput any, _ []map[string]interface{}) (<-chan canvas.RunEvent, error) {
s.sessionID = sessionID
+ s.trustedSessionID = service.AgentSessionIDFromContext(ctx)
s.userInput = userInput
if s.err != nil {
return nil, s.err
@@ -823,6 +825,9 @@ func TestRunAgent_StreamAddsDoneWhenRunnerCloses(t *testing.T) {
h := &AgentHandler{chatRunner: runner}
h.RunAgent(c)
+ if runner.sessionID == "" || runner.trustedSessionID != runner.sessionID {
+ t.Fatalf("generated session id = %q, trusted session id = %q", runner.sessionID, runner.trustedSessionID)
+ }
body := w.Body.String()
if got := strings.Count(body, "data:[DONE]\n\n"); got != 1 {
t.Fatalf("expected exactly one [DONE] terminator, got %d in %q", got, body)
@@ -832,6 +837,28 @@ func TestRunAgent_StreamAddsDoneWhenRunnerCloses(t *testing.T) {
}
}
+func TestRunAgent_SuppliedSessionIsNotTrustedFirstTouch(t *testing.T) {
+ gin.SetMode(gin.TestMode)
+ w := httptest.NewRecorder()
+ c, _ := gin.CreateTestContext(w)
+ c.Params = gin.Params{{Key: "canvas_id", Value: "a1"}}
+ c.Request = httptest.NewRequest("POST", "/api/v1/agents/a1/run?session_id=client-session",
+ strings.NewReader(`{"user_input":"hi"}`))
+ c.Request.Header.Set("Content-Type", "application/json")
+ c.Set("user", &entity.User{ID: "u1"})
+ c.Set("user_id", "u1")
+
+ runner := &stubChatRunner{}
+ (&AgentHandler{chatRunner: runner}).RunAgent(c)
+
+ if runner.sessionID != "client-session" {
+ t.Fatalf("session id = %q, want client-session", runner.sessionID)
+ }
+ if runner.trustedSessionID != "" {
+ t.Fatalf("trusted session id = %q, want empty", runner.trustedSessionID)
+ }
+}
+
// TestAgentChatCompletions_DefaultBranchNonStreaming covers the
// scenario where `stream` is omitted from the request body. When
// `stream` is absent, the handler must return a plain JSON response
@@ -940,11 +967,13 @@ func TestAgentChatCompletions_NonStreamingPreservesThinkMarkers(t *testing.T) {
}
type emptySessionCaptureRunner struct {
- sessionID string
+ sessionID string
+ trustedSessionID string
}
-func (r *emptySessionCaptureRunner) RunAgent(_ context.Context, _, _, sessionID, _ string, _ any, _ []map[string]interface{}) (<-chan canvas.RunEvent, error) {
+func (r *emptySessionCaptureRunner) RunAgent(ctx context.Context, _, _, sessionID, _ string, _ any, _ []map[string]interface{}) (<-chan canvas.RunEvent, error) {
r.sessionID = sessionID
+ r.trustedSessionID = service.AgentSessionIDFromContext(ctx)
ch := make(chan canvas.RunEvent)
close(ch)
return ch, nil
@@ -967,6 +996,9 @@ func TestAgentChatCompletions_EmptyOutputReturnsGeneratedSession(t *testing.T) {
if runner.sessionID == "" {
t.Fatal("handler passed an empty session id to RunAgent")
}
+ if runner.trustedSessionID != runner.sessionID {
+ t.Fatalf("trusted session id = %q, want generated id %q", runner.trustedSessionID, runner.sessionID)
+ }
var response map[string]any
if err := json.Unmarshal(w.Body.Bytes(), &response); err != nil {
t.Fatalf("decode response: %v", err)
@@ -1144,6 +1176,9 @@ func TestAgentChatCompletions_OpenAICompat_NonStreamReturnsCompletion(t *testing
if runner.sessionID == "" {
t.Error("runner sessionID should be generated for a new OpenAI-compatible request")
}
+ if runner.trustedSessionID != runner.sessionID {
+ t.Fatalf("trusted session id = %q, want generated id %q", runner.trustedSessionID, runner.sessionID)
+ }
var resp map[string]interface{}
if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
@@ -1192,6 +1227,27 @@ func TestAgentChatCompletions_OpenAICompat_NonStreamReturnsCompletion(t *testing
}
}
+func TestAgentChatCompletions_OpenAICompat_SuppliedSessionIsNotTrustedFirstTouch(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","session_id":"client-session","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{}
+ (&AgentHandler{chatRunner: runner}).AgentChatCompletions(c)
+
+ if runner.sessionID != "client-session" {
+ t.Fatalf("session id = %q, want client-session", runner.sessionID)
+ }
+ if runner.trustedSessionID != "" {
+ t.Fatalf("trusted session id = %q, want empty", runner.trustedSessionID)
+ }
+}
+
func TestAgentChatCompletions_OpenAICompat_NonStreamReturnsRunnerError(t *testing.T) {
gin.SetMode(gin.TestMode)
w := httptest.NewRecorder()
diff --git a/internal/rag/agentic-rag/runtime/tool_executor.go b/internal/rag/agentic-rag/runtime/tool_executor.go
index 64c4110bc1..32517e2dca 100644
--- a/internal/rag/agentic-rag/runtime/tool_executor.go
+++ b/internal/rag/agentic-rag/runtime/tool_executor.go
@@ -2041,11 +2041,11 @@ func (r *RuntimeRetriever) Retrieve(ctx context.Context, req RetrieveRequest) ([
SimilarityThreshold: req.SimilarityThreshold,
KeywordsSimilarityWeight: req.KeywordsSimilarityWeight,
TenantID: req.TenantID,
+ MetaDataFilter: req.MetaDataFilter,
RankFeature: &req.RankFeature,
- // ExcludeCompiled maps Python hybrid_search's
- // must_not={"exists":"compile_kwd"} onto the runtime request's
- // OnlyOriginalText (the "no compile_kwd" exclusion).
- OnlyOriginalText: req.ExcludeCompiled,
+ // Python hybrid_search always excludes compile_kwd rows from the base
+ // retrieval; use_compiled controls a separate expansion step.
+ ExcludeCompiled: req.ExcludeCompiled,
})
if err != nil {
return nil, err
diff --git a/internal/service/agent.go b/internal/service/agent.go
index 3e606bdc9d..5cbc5f2709 100644
--- a/internal/service/agent.go
+++ b/internal/service/agent.go
@@ -1463,6 +1463,20 @@ func (s *AgentService) RunAgent(ctx context.Context, userID, canvasID, sessionID
if sessionID == "" {
sessionID = utility.GenerateToken()
}
+ trustedFirstTouch := AgentSessionIDFromContext(ctx) == sessionID
+ if !newSession && s.api4ConversationDAO != nil && dao.DB != nil {
+ existingSession, err := s.api4ConversationDAO.GetMetadataBySessionID(ctx, dao.DB, sessionID, canvasID)
+ if err != nil {
+ return nil, fmt.Errorf("RunAgent: load session %q: %w: %w", sessionID, err, ErrAgentStorageError)
+ }
+ if existingSession == nil {
+ if !trustedFirstTouch {
+ return nil, fmt.Errorf("RunAgent: session %q not found: %w", sessionID, dao.ErrUserCanvasNotFound)
+ }
+ } else if existingSession.DialogID != canvasID || existingSession.UserID != userID {
+ return nil, fmt.Errorf("RunAgent: session %q not found: %w", sessionID, dao.ErrUserCanvasNotFound)
+ }
+ }
messageID := utility.GenerateToken()
questionSaved := false
persistQuestion := func() error {
@@ -1703,26 +1717,24 @@ func (s *AgentService) RunAgent(ctx context.Context, userID, canvasID, sessionID
dsl = normalisedDSLForRun(versionRow)
}
sessionFound := false
- if sessionID != "" && s.api4ConversationDAO != nil {
- session, sessionErr := s.api4ConversationDAO.GetMetadataBySessionID(ctx, dao.DB, sessionID, canvasID)
- if sessionErr != nil {
- return nil, fmt.Errorf("RunAgent: load session %q: %w: %w", sessionID, sessionErr, ErrAgentStorageError)
+ if sessionID != "" && s.api4ConversationDAO != nil && dao.DB != nil {
+ existingSession, err := s.api4ConversationDAO.GetMetadataBySessionID(ctx, dao.DB, sessionID, canvasID)
+ if err != nil {
+ return nil, fmt.Errorf("RunAgent: load session %q: %w: %w", sessionID, err, ErrAgentStorageError)
}
- if session != nil && session.UserID != userID {
+ if existingSession != nil && (existingSession.DialogID != canvasID || existingSession.UserID != userID) {
return nil, fmt.Errorf("RunAgent: session %q not found: %w", sessionID, dao.ErrUserCanvasNotFound)
}
- sessionFound = session != nil
- if session != nil && len(session.DSL) > 0 {
- dsl = dslpkg.NormalizeForRun(session.DSL)
+ sessionFound = existingSession != nil
+ if existingSession != nil && len(existingSession.DSL) > 0 {
+ dsl = dslpkg.NormalizeForRun(existingSession.DSL)
}
}
if err := validateAgentChatModels(ctx, userID, dsl); err != nil {
return nil, err
}
- // A handler may allocate the session id before calling RunAgent so the
- // effective id is available even when the run emits no events. Treat an
- // absent conversation row as a first touch regardless of who generated the
- // id; there is still only one business identity (session_id).
+ // A trusted boundary may allocate the session id before calling RunAgent so
+ // the effective id is available even when the run emits no events.
if !sessionFound || newSession {
// The editable/released canvas can be a runtime replica from another
// conversation. A new session may reuse its graph, memory, and env state,
diff --git a/internal/service/agent_deferred_failure_test.go b/internal/service/agent_deferred_failure_test.go
index 8e24b4ba26..68c3198bd3 100644
--- a/internal/service/agent_deferred_failure_test.go
+++ b/internal/service/agent_deferred_failure_test.go
@@ -114,7 +114,7 @@ func TestRunAgent_DeferredAgentModelFailureStaysInChatStream(t *testing.T) {
tracker, _ := newAgentCancelTracker(t)
svc := NewAgentServiceWithOptions(nil, nil, tracker)
events, err := svc.RunAgent(
- t.Context(),
+ WithAgentSessionID(t.Context(), "session-deferred-fail"),
"user-1",
"canvas-deferred-fail",
"session-deferred-fail",
diff --git a/internal/service/agent_run_e2e_test.go b/internal/service/agent_run_e2e_test.go
index da08c65b31..99fab5090a 100644
--- a/internal/service/agent_run_e2e_test.go
+++ b/internal/service/agent_run_e2e_test.go
@@ -202,7 +202,7 @@ func TestRunAgent_RealCanvas_BeginMessage(t *testing.T) {
cp := canvas.NewKvrocksCheckPointStoreWithClient(cpClient, 30*24*time.Hour)
svc := NewAgentServiceWithOptions(cp, nil, tracker)
events, err := svc.RunAgent(
- t.Context(),
+ WithAgentSessionID(t.Context(), "session-hello"),
"user-1",
"canvas-hello",
"session-hello",
@@ -800,7 +800,7 @@ func TestRunAgent_RealCanvas_WaitForUserResume_EventSemantics(t *testing.T) {
svc := NewAgentServiceWithOptions(cp, nil, tracker)
events1, err := svc.RunAgent(
- t.Context(),
+ WithAgentSessionID(t.Context(), "session-fillup-events"),
"user-1",
"canvas-fillup-events",
"session-fillup-events",
@@ -941,7 +941,7 @@ func TestRunAgent_RealCanvas_GroupedParallelOuterFollower(t *testing.T) {
svc := NewAgentService()
events, err := svc.RunAgent(
- t.Context(),
+ WithAgentSessionID(t.Context(), "session-parallel"),
"user-1",
"canvas-parallel",
"session-parallel",
@@ -1011,7 +1011,7 @@ func TestRunAgent_AllFixture_LoopInterruptResume(t *testing.T) {
svc := NewAgentServiceWithOptions(cp, nil, tracker)
events1, err := svc.RunAgent(
- t.Context(),
+ WithAgentSessionID(t.Context(), "session-all-loop"),
"user-1",
"canvas-all",
"session-all-loop",
@@ -1136,8 +1136,12 @@ func TestRunAgent_AllFixture_LoopInterruptResume_MultiTurn(t *testing.T) {
var allMessages []canvas.MessageEvent
for i, input := range inputs {
+ runCtx := t.Context()
+ if i == 0 {
+ runCtx = WithAgentSessionID(runCtx, sessionID)
+ }
events, err := svc.RunAgent(
- t.Context(),
+ runCtx,
"user-1",
"canvas-all-multi",
sessionID,
@@ -1230,7 +1234,7 @@ func TestRunAgent_AllFixture_IterationFormatsItems(t *testing.T) {
sessionID := "session-all-iteration"
events1, err := svc.RunAgent(
- t.Context(),
+ WithAgentSessionID(t.Context(), sessionID),
"user-1",
"canvas-all-iteration",
sessionID,
@@ -1340,7 +1344,7 @@ func TestRunAgent_AllFixture_VarAssigner(t *testing.T) {
cp := canvas.NewKvrocksCheckPointStoreWithClient(cpClient, 30*24*time.Hour)
svc := NewAgentServiceWithOptions(cp, nil, tracker)
events, err := svc.RunAgent(
- t.Context(),
+ WithAgentSessionID(t.Context(), "session-all-var-assigner"),
"user-1",
"canvas-all-var-assigner",
"session-all-var-assigner",
@@ -1424,7 +1428,7 @@ func TestRunAgent_AllFixture_DataOps(t *testing.T) {
cp := canvas.NewKvrocksCheckPointStoreWithClient(cpClient, 30*24*time.Hour)
svc := NewAgentServiceWithOptions(cp, nil, tracker)
events, err := svc.RunAgent(
- t.Context(),
+ WithAgentSessionID(t.Context(), "session-all-data-ops"),
"user-1",
"canvas-all-data-ops",
"session-all-data-ops",
@@ -1526,7 +1530,7 @@ func TestRunAgent_RealCanvas_CompileFails(t *testing.T) {
svc := NewAgentService()
events, err := svc.RunAgent(
- t.Context(),
+ WithAgentSessionID(t.Context(), "session-bogus"),
"user-1",
"canvas-bogus",
"session-bogus",
@@ -1598,7 +1602,7 @@ func TestRunAgent_AllFixture_CategorizeResume(t *testing.T) {
cp := canvas.NewKvrocksCheckPointStoreWithClient(cpClient, 30*24*time.Hour)
svc := NewAgentServiceWithOptions(cp, nil, tracker)
events1, err := svc.RunAgent(
- t.Context(),
+ WithAgentSessionID(t.Context(), "session-all-categorize"),
"user-1",
"canvas-all-categorize",
"session-all-categorize",
@@ -1756,7 +1760,7 @@ func TestRunAgent_RealCanvas_InvokeFails(t *testing.T) {
svc := NewAgentService()
events, err := svc.RunAgent(
- t.Context(),
+ WithAgentSessionID(t.Context(), "session-invoke-fail"),
"user-1",
"canvas-invoke-fail",
"session-invoke-fail",
@@ -1863,7 +1867,7 @@ func TestRunAgent_RunTracker_AttachCheckpoint_CallSequence(t *testing.T) {
svc := NewAgentServiceWithOptions(cp, canvas.CanvasStateSerializer{}, tracker)
events, err := svc.RunAgent(
- t.Context(),
+ WithAgentSessionID(t.Context(), "session-cp"),
"user-1",
"canvas-cp",
"session-cp",
@@ -2038,7 +2042,7 @@ func TestRunAgent_FilesPopulateIteration(t *testing.T) {
svc := NewAgentService()
events, err := svc.RunAgent(
- ctx,
+ WithAgentSessionID(ctx, sessionID),
"user-1",
canvasID,
sessionID,
@@ -2105,7 +2109,7 @@ func TestRunAgent_MissingUploadEmitsError(t *testing.T) {
makeCanvasWithDSL(t, "canvas-missing-upload", "user-1", "tenant-1", "v-missing-upload", dsl)
events, err := NewAgentService().RunAgent(
- t.Context(),
+ WithAgentSessionID(t.Context(), "session-missing-upload"),
"user-1",
"canvas-missing-upload",
"session-missing-upload",
@@ -2183,7 +2187,7 @@ func TestRunAgent_NoFilesRunsNormally(t *testing.T) {
svc := NewAgentService()
events, err := svc.RunAgent(
- t.Context(),
+ WithAgentSessionID(t.Context(), sessionID),
"user-1",
canvasID,
sessionID,
diff --git a/internal/service/agent_test.go b/internal/service/agent_test.go
index c41a4a8c06..9bfc2ecfb0 100644
--- a/internal/service/agent_test.go
+++ b/internal/service/agent_test.go
@@ -686,7 +686,7 @@ func TestRunAgent_NoVersionPublishedPlaceholder(t *testing.T) {
ctx := t.Context()
svc := NewAgentService()
events, err := svc.RunAgent(
- ctx,
+ WithAgentSessionID(ctx, "test-session"),
"user-1",
"canvas-empty",
"test-session",
@@ -742,6 +742,43 @@ func TestRunAgent_NoVersionPublishedPlaceholder(t *testing.T) {
}
}
+func TestRunAgentRejectsUntrustedSessionContinuation(t *testing.T) {
+ setupAgentSessionServiceTest(t)
+ createAgentSessionTestCanvas(t, "canvas-1", "user-1")
+ createAgentSessionTestCanvas(t, "canvas-2", "user-1")
+ createAgentSessionTestConversation(t, "session-other-agent", "canvas-2", "user-1", 1000)
+ createAgentSessionTestConversation(t, "session-other-user", "canvas-1", "user-2", 1000)
+ createAgentSessionTestConversation(t, "session-valid", "canvas-1", "user-1", 1000)
+
+ svc := NewAgentService()
+ for _, tc := range []struct {
+ name string
+ sessionID string
+ userID string
+ wantErr bool
+ }{
+ {name: "unknown", sessionID: "session-missing", userID: "user-1", wantErr: true},
+ {name: "wrong agent", sessionID: "session-other-agent", userID: "user-1", wantErr: true},
+ {name: "foreign owner", sessionID: "session-other-user", userID: "user-1", wantErr: true},
+ {name: "valid resume", sessionID: "session-valid", userID: "user-1"},
+ } {
+ t.Run(tc.name, func(t *testing.T) {
+ events, err := svc.RunAgent(t.Context(), tc.userID, "canvas-1", tc.sessionID, "", "hello", nil)
+ if tc.wantErr {
+ if !errors.Is(err, dao.ErrUserCanvasNotFound) {
+ t.Fatalf("RunAgent error = %v, want ErrUserCanvasNotFound", err)
+ }
+ return
+ }
+ if err != nil {
+ t.Fatalf("RunAgent valid resume failed: %v", err)
+ }
+ for range events {
+ }
+ })
+ }
+}
+
// TestRunAgent_StorageErrorFromCanvasAccess pins the v3.5.2
// follow-up: when loadCanvasForUser's underlying DAO surfaces a
// real DB error (NOT the ErrUserCanvasNotFound sentinel), RunAgent