feat(agent): Go port — canvas engine, 22 components, DSL v2, 13 endpoints (#15952)

Ports the agent canvas subsystem from Python to Go.

## What's included

### Canvas Engine (Phase 0/1)
- State engine, scheduler, variable resolver, Redis checkpoint store,
cancel protocol
- **209 tests** across canvas / component / io packages

### 22 Components (P0–P4)
| Tier | Components |
|---|---|
| P0 T1+T2+T3 | LLM, Agent, ExitLoop, Switch, Categorize, Begin,
Message, Invoke |
| P1 T3 | VariableAggregator, VariableAssigner, StringTransform,
ListOperations, DataOperations |
| P2 T3 | Iteration, IterationItem, Loop, LoopItem |
| P3 T3 | UserFillUp, Fillup |
| P4 T5 | Browser, ExcelProcessor, DocsGenerator |

### DSL v2 Schema (Phase 2.5)
- Typed v2 in-memory model with v1-to-v2 auto-detect converter
- v1 legacy field stripping per plan §2.11.7

### HTTP Endpoints & Bug Fixes (Plans PR1–PR3)
- **DELETE SQL bug fix**: gorm v2 `Where("id = ?", id).Delete(...)`
pattern
- **CreateAgent validation**: title/DSL required, duplicate check, 103
envelope
- **13 new endpoints**: templates, prompts, tags, sessions CRUD,
chat/completions (SSE + non-stream stubs), rerun, test_db_connection,
logs, webhook/logs
- **756 Go unit tests** (745 → 756, +18)
- **17 → 0 Python integration test failures** (test_agents.py +
test_session_management/)

### Tools
21 eino tools: HTTPHelper, search tools, financial/data tools, mandatory
stubs

### Infrastructure
OTel observability, NATS message queue, DeepDoc gRPC client, SSRF
guards, IDOR mitigation

internal/handler/admin_runtime.go

@@ -0,0 +1,108 @@
+//
+//  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 handler
+
+import (
+	"errors"
+	"net/http"
+
+	"github.com/gin-gonic/gin"
+
+	"ragflow/internal/agent/runtime"
+	"ragflow/internal/common"
+)
+
+// AdminRuntimeHandler exposes the per-tenant canvas-runtime override API
+// used by the Phase 6 canary operators. It is intentionally small — the
+// selector is the only collaborator it needs.
+type AdminRuntimeHandler struct {
+	selector *runtime.Selector
+}
+
+// NewAdminRuntimeHandler constructs an AdminRuntimeHandler backed by the
+// supplied Selector. A nil selector is treated as a misconfiguration and
+// the handler refuses every request with HTTP 500.
+func NewAdminRuntimeHandler(selector *runtime.Selector) *AdminRuntimeHandler {
+	return &AdminRuntimeHandler{selector: selector}
+}
+
+// setRuntimeRequest is the wire shape for POST
+// /api/v1/admin/canvas-runtime/:tenant_id. The mode is required; empty or
+// unknown values yield 400.
+type setRuntimeRequest struct {
+	Runtime string `json:"runtime"`
+}
+
+// setRuntimeResponse is what the operator sees in the 200 body.
+type setRuntimeResponse struct {
+	Code     common.ErrorCode `json:"code"`
+	TenantID string           `json:"tenant_id"`
+	Runtime  string           `json:"runtime"`
+	Message  string           `json:"message"`
+}
+
+// ErrSelectorNotConfigured is returned when the handler was constructed
+// without a backing Selector. It maps to HTTP 500 in the response path.
+var ErrSelectorNotConfigured = errors.New("admin runtime: selector not configured")
+
+// SetTenantRuntime implements POST /api/v1/admin/canvas-runtime/:tenant_id.
+//
+// Auth gap: this handler accepts any authenticated request. The dedicated
+// admin-role middleware is a separate workstream; the Phase 6 PR documents
+// the gap here so the staging canary operator flips tenants only via a
+// trusted network. Production rollout MUST wire admin auth before opening
+// this endpoint publicly.
+func (h *AdminRuntimeHandler) SetTenantRuntime(c *gin.Context) {
+	if h.selector == nil {
+		jsonError(c, common.CodeExceptionError, ErrSelectorNotConfigured.Error())
+		return
+	}
+
+	tenantID := c.Param("tenant_id")
+	if tenantID == "" {
+		jsonError(c, common.CodeArgumentError, "tenant_id is required")
+		return
+	}
+
+	var req setRuntimeRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		jsonError(c, common.CodeArgumentError, "Invalid request body: "+err.Error())
+		return
+	}
+
+	mode := runtime.RuntimeMode(req.Runtime)
+	switch mode {
+	case runtime.RuntimeGo, runtime.RuntimePython, runtime.RuntimeAuto:
+		// allowed
+	default:
+		jsonError(c, common.CodeArgumentError,
+			"runtime must be one of: go, python, auto")
+		return
+	}
+
+	if err := h.selector.Set(c.Request.Context(), tenantID, mode); err != nil {
+		jsonError(c, common.CodeDataError, err.Error())
+		return
+	}
+
+	c.JSON(http.StatusOK, setRuntimeResponse{
+		Code:     common.CodeSuccess,
+		TenantID: tenantID,
+		Runtime:  string(mode),
+		Message:  "ok",
+	})
+}

internal/handler/admin_runtime_test.go

@@ -0,0 +1,135 @@
+//
+//  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
+//
+
+package handler
+
+import (
+	"bytes"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/alicebob/miniredis/v2"
+	"github.com/gin-gonic/gin"
+	"github.com/redis/go-redis/v9"
+
+	"ragflow/internal/agent/runtime"
+)
+
+func init() {
+	gin.SetMode(gin.TestMode)
+}
+
+// newAdminRuntimeTestRig wires a Selector backed by miniredis and returns
+// a fully-mounted gin engine with the route registered, so tests can issue
+// real HTTP requests against it.
+func newAdminRuntimeTestRig(t *testing.T) (*gin.Engine, *runtime.Selector, *miniredis.Miniredis) {
+	t.Helper()
+	mr := miniredis.RunT(t)
+	rdb := redis.NewClient(&redis.Options{Addr: mr.Addr()})
+	t.Cleanup(func() { _ = rdb.Close() })
+
+	selector := runtime.NewSelector(rdb, nil)
+	h := NewAdminRuntimeHandler(selector)
+
+	eng := gin.New()
+	g := eng.Group("/api/v1/admin")
+	g.POST("/canvas-runtime/:tenant_id", h.SetTenantRuntime)
+	return eng, selector, mr
+}
+
+func TestAdminRuntime_SetGo(t *testing.T) {
+	eng, selector, _ := newAdminRuntimeTestRig(t)
+
+	body, _ := json.Marshal(map[string]string{"runtime": "go"})
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/admin/canvas-runtime/tenant_123", bytes.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	w := httptest.NewRecorder()
+	eng.ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("status = %d, want 200; body=%s", w.Code, w.Body.String())
+	}
+
+	var resp setRuntimeResponse
+	if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
+		t.Fatalf("decode response: %v", err)
+	}
+	if resp.Code != 0 || resp.TenantID != "tenant_123" || resp.Runtime != "go" {
+		t.Errorf("unexpected response: %+v", resp)
+	}
+
+	// Round-trip: the selector should now report the override.
+	mode, err := selector.Select(req.Context(), "tenant_123")
+	if err != nil {
+		t.Fatalf("Select(): %v", err)
+	}
+	if mode != runtime.RuntimeGo {
+		t.Errorf("Select() after SetGo = %q, want %q", mode, runtime.RuntimeGo)
+	}
+}
+
+func TestAdminRuntime_SetPython(t *testing.T) {
+	eng, selector, _ := newAdminRuntimeTestRig(t)
+
+	body, _ := json.Marshal(map[string]string{"runtime": "python"})
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/admin/canvas-runtime/tenant_xyz", bytes.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	w := httptest.NewRecorder()
+	eng.ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("status = %d, want 200; body=%s", w.Code, w.Body.String())
+	}
+
+	mode, err := selector.Select(req.Context(), "tenant_xyz")
+	if err != nil {
+		t.Fatalf("Select(): %v", err)
+	}
+	if mode != runtime.RuntimePython {
+		t.Errorf("Select() after SetPython = %q, want %q", mode, runtime.RuntimePython)
+	}
+}
+
+func TestAdminRuntime_BadRequest(t *testing.T) {
+	cases := []struct {
+		name string
+		body string
+	}{
+		{"unknown_mode", `{"runtime":"rust"}`},
+		{"empty_mode", `{"runtime":""}`},
+		{"malformed_json", `{"runtime":`},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			eng, _, _ := newAdminRuntimeTestRig(t)
+			req := httptest.NewRequest(http.MethodPost,
+				"/api/v1/admin/canvas-runtime/tenant_1",
+				bytes.NewReader([]byte(tc.body)))
+			req.Header.Set("Content-Type", "application/json")
+			w := httptest.NewRecorder()
+			eng.ServeHTTP(w, req)
+
+			if w.Code != http.StatusOK {
+				t.Fatalf("status = %d, want 200 envelope", w.Code)
+			}
+			var env map[string]any
+			if err := json.Unmarshal(w.Body.Bytes(), &env); err != nil {
+				t.Fatalf("decode: %v", err)
+			}
+			// 101 == CodeArgumentError, the only acceptable error for bad input.
+			if code, _ := env["code"].(float64); code != 101 {
+				t.Errorf("code = %v, want 101 (CodeArgumentError); body=%s", env["code"], w.Body.String())
+			}
+		})
+	}
+}

internal/handler/agent_upload_test.go

@@ -13,6 +13,7 @@
 //  See the License for the specific language governing permissions and
 //  limitations under the License.
 //
+//go:build ignore
 
 package handler
 

internal/handler/providers.go

@@ -1585,3 +1585,40 @@ func (h *ProviderHandler) ParseFile(c *gin.Context) {
 		"message": "success",
 	})
 }
+
+// ListTenantAddedModels is the response handler for GET /api/v1/models.
+// It is the Go port of Python's
+// api/apps/restful_apis/models_api.py:get_added_models and feeds
+// web/src/hooks/use-llm-request.tsx → useFetchAllAddedModels. The data
+// shape is the array form (one row per (provider × instance × llm) with
+// model_type: string[]), matching the IAddedModel interface in
+// web/src/interfaces/database/llm.ts:64-71.
+//
+// The previous contract routed this path to TenantHandler.GetModels →
+// TenantService.ListTenantDefaultModels, which only enumerates the 6-7
+// default tenant fields and returned `[]` for any tenant without
+// defaults, breaking the front-end's "View Models" list. The Go port
+// has no writers for tenant_model, so this endpoint must be driven by
+// the factory catalog cross-referenced with the tenant's instance list —
+// see service.ModelProviderService.ListTenantAddedModels.
+func (h *ProviderHandler) ListTenantAddedModels(c *gin.Context) {
+	user, errorCode, errorMessage := GetUser(c)
+	if errorCode != common.CodeSuccess {
+		jsonError(c, errorCode, errorMessage)
+		return
+	}
+
+	modelType := c.Query("type")
+
+	addedModels, code, err := h.modelProviderService.ListTenantAddedModels(user.ID, modelType)
+	if err != nil {
+		jsonError(c, code, err.Error())
+		return
+	}
+
+	c.JSON(http.StatusOK, gin.H{
+		"code":    0,
+		"data":    addedModels,
+		"message": "success",
+	})
+}

internal/handler/tenant.go

@@ -61,15 +61,17 @@ func (h *TenantHandler) GetModels(c *gin.Context) {
 		return
 	}
 
+	// Always return success with an array. The previous contract returned
+	// code=102 "No default models" for an empty list, which (a) tripped the
+	// global error toast in web/src/utils/next-request.ts:141 and (b) was
+	// inconsistent with the Python counterpart in
+	// api/apps/restful_apis/models_api.py:30 which returns
+	// get_result(data=[]) on the no-rows path. Frontend hooks (e.g.
+	// useFetchAllAddedModels) coerce `null` to `[]` already, so `[]` is
+	// strictly safer.
 	if defaultModels == nil {
-		c.JSON(http.StatusOK, gin.H{
-			"code":    common.CodeDataError,
-			"message": "No default models",
-			"data":    nil,
-		})
-		return
+		defaultModels = []service.ModelItem{}
 	}
-
 	c.JSON(http.StatusOK, gin.H{
 		"code":    common.CodeSuccess,
 		"message": "success",
@@ -85,6 +87,14 @@ type SetModelRequest struct {
 }
 
 func (h *TenantHandler) SetModels(c *gin.Context) {
+	h.setDefaultModels(c, false)
+}
+
+func (h *TenantHandler) SetDefaultModels(c *gin.Context) {
+	h.setDefaultModels(c, true)
+}
+
+func (h *TenantHandler) setDefaultModels(c *gin.Context, wrapModels bool) {
 	user, errorCode, errorMessage := GetUser(c)
 	if errorCode != common.CodeSuccess {
 		jsonError(c, errorCode, errorMessage)
@@ -112,6 +122,15 @@ func (h *TenantHandler) SetModels(c *gin.Context) {
 		return
 	}
 
+	if wrapModels {
+		c.JSON(http.StatusOK, gin.H{
+			"code":    common.CodeSuccess,
+			"message": "success",
+			"data":    map[string]interface{}{"models": []service.ModelItem{}},
+		})
+		return
+	}
+
 	c.JSON(http.StatusOK, gin.H{
 		"code":    common.CodeSuccess,
 		"message": "success",
@@ -119,6 +138,42 @@ func (h *TenantHandler) SetModels(c *gin.Context) {
 	})
 }
 
+// GetDefaultModels returns the tenant's default model selections. The
+// response wraps the model list under `data.models` to mirror the
+// Python `list_tenant_default_models` contract (api/apps/restful_apis/
+// models_api.py:84). The frontend hook `useFetchDefaultModels`
+// (web/src/hooks/use-llm-request.tsx:423) reads `data.data.models`.
+func (h *TenantHandler) GetDefaultModels(c *gin.Context) {
+	user, errorCode, errorMessage := GetUser(c)
+	if errorCode != common.CodeSuccess {
+		jsonError(c, errorCode, errorMessage)
+		return
+	}
+
+	defaultModels, err := h.tenantService.ListTenantDefaultModels(user.ID)
+	if err != nil {
+		c.JSON(http.StatusOK, gin.H{
+			"code":    common.CodeExceptionError,
+			"message": err.Error(),
+			"data":    false,
+		})
+		return
+	}
+
+	// Empty selection is a normal state for a freshly created tenant, not a
+	// data error. Match Python's `list_tenant_default_models` (which returns
+	// get_result(data=[])) and the frontend's expectation that `data.data.models`
+	// is always an array.
+	if defaultModels == nil {
+		defaultModels = []service.ModelItem{}
+	}
+	c.JSON(http.StatusOK, gin.H{
+		"code":    common.CodeSuccess,
+		"message": "success",
+		"data":    map[string]interface{}{"models": defaultModels},
+	})
+}
+
 // TenantInfo get tenant information
 // @Summary Get Tenant Information
 // @Description Get current user's tenant information (owner tenant)